Merge pull request #25979 from dvdksn/codex/sandbox-interactive-diagram

docs: prototype interactive Sandboxes diagram

layouts/_partials/interactive-diagram-script.html

@@ -0,0 +1,4 @@
+{{ $diagram := resources.Get "js/interactive-diagram.js"
+  | js.Build (dict "minify" true "targetPath" "interactive-diagram.js")
+}}
+<script defer src="{{ $diagram.RelPermalink }}"></script>

layouts/_shortcodes/interactive-diagram.html

@@ -0,0 +1,102 @@
+{{- $src := .Get "src" -}}
+{{- if not $src -}}
+  {{- errorf "interactive-diagram shortcode: missing src: %s" .Position -}}
+{{- end -}}
+{{- $filePath := path.Join .Page.File.Dir $src -}}
+{{- if not (fileExists $filePath) -}}
+  {{- errorf "interactive-diagram shortcode: file %q not found: %s" $filePath .Position -}}
+{{- end -}}
+{{- $diagram := readFile $filePath | transform.Unmarshal -}}
+{{- $type := $diagram.type | default "sequence" -}}
+{{- $id := printf "interactive-diagram-%s-%d" .Page.File.UniqueID .Ordinal -}}
+{{- .Page.Store.Set "interactive-diagram" true -}}
+<figure
+  id="{{ $id }}"
+  class="interactive-diagram interactive-diagram--{{ $type }} not-prose my-6"
+  data-interactive-diagram
+  data-diagram-type="{{ $type }}"
+  aria-labelledby="{{ $id }}-title"
+>
+  <figcaption class="interactive-diagram__header">
+    <div class="interactive-diagram__header-copy">
+      <p id="{{ $id }}-title" class="interactive-diagram__title">
+        {{ $diagram.title }}
+      </p>
+      <p class="interactive-diagram__description">{{ $diagram.description }}</p>
+    </div>
+  </figcaption>
+  <div class="interactive-diagram__stage" data-diagram-stage></div>
+  {{- if eq $type "topology" }}
+    <div
+      class="interactive-diagram__topology-detail"
+      data-topology-detail
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      <p class="interactive-diagram__topology-category" data-topology-category>
+        {{ $diagram.overview.category }}
+      </p>
+      <div class="interactive-diagram__topology-detail-copy">
+        <p class="interactive-diagram__topology-title" data-topology-title>
+          {{ $diagram.overview.label }}
+        </p>
+        <p class="interactive-diagram__topology-body" data-topology-body>
+          {{ $diagram.overview.body }}
+        </p>
+      </div>
+    </div>
+  {{- else }}
+    <div
+      class="interactive-diagram__status"
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      <div class="interactive-diagram__step-copy">
+        <span class="interactive-diagram__step-number" data-step-number></span>
+        <div>
+          <p class="interactive-diagram__step-title" data-step-title></p>
+          <p class="interactive-diagram__step-body" data-step-body></p>
+        </div>
+      </div>
+      <p class="interactive-diagram__state" data-step-state></p>
+    </div>
+    <div class="interactive-diagram__controls" data-diagram-controls>
+      <button
+        type="button"
+        class="interactive-diagram__button"
+        data-step-previous
+      >
+        Previous
+      </button>
+      <div
+        class="interactive-diagram__progress"
+        data-step-progress
+        aria-label="Diagram steps"
+      ></div>
+      <button type="button" class="interactive-diagram__button" data-step-next>
+        Next
+      </button>
+    </div>
+  {{- end }}
+  <div class="interactive-diagram__fallback">
+    {{- if eq $type "topology" }}
+      <ul>
+        {{- range $diagram.nodes }}
+          <li>{{ .label }}: {{ .details }}</li>
+        {{- end }}
+        {{- range $diagram.edges }}
+          <li>{{ .label }}: {{ .details }}</li>
+        {{- end }}
+      </ul>
+    {{- else }}
+      <ol>
+        {{- range $diagram.steps }}
+          <li>{{ .label }}: {{ .body }}</li>
+        {{- end }}
+      </ol>
+    {{- end }}
+  </div>
+  <script type="application/json" data-interactive-diagram-config>
+    {{- $diagram | jsonify | safeJS -}}
+  </script>
+</figure>

layouts/_shortcodes/interactive-diagram.markdown.md

@@ -0,0 +1,13 @@
+{{- $src := .Get "src" -}}
+{{- $filePath := path.Join .Page.File.Dir $src -}}
+{{- if not (fileExists $filePath) -}}
+  {{- errorf "interactive-diagram shortcode: file %q not found: %s" $filePath .Position -}}
+{{- end -}}
+{{- $diagram := readFile $filePath | transform.Unmarshal -}}
+{{ $diagram.title }}
+
+{{ $diagram.description }}
+
+{{ range $index, $step := $diagram.steps -}}
+{{ add $index 1 }}. {{ $step.label }}: {{ $step.body }}
+{{ end -}}

layouts/baseof.html

@@ -96,5 +96,9 @@
     {{ with .Store.Get "mermaid" }}
       {{ partialCached "mermaid-script.html" "-" "-" }}
     {{ end }}
+    {{/* Load interactive diagrams only on pages that contain the shortcode */}}
+    {{ with .Store.Get "interactive-diagram" }}
+      {{ partialCached "interactive-diagram-script.html" "-" "-" }}
+    {{ end }}
   </body>
 </html>