@erclx/canon 4.40.2 → 4.42.0

package/tooling/astro/configs/src/components/dev/scenarios.astro

@@ -0,0 +1,127 @@
+---
+/**
+ * Serves candidate treatments of one decision from the running page, selected
+ * by a query parameter, with a switcher for moving between them.
+ *
+ * It exists because a decision about how something feels to cause cannot be
+ * settled from a capture or a recording, both of which are passive, and the
+ * operator has to drive the candidates themselves. Five decisions were served
+ * that way in one run, each with a hand-written parameter, switcher, and
+ * removal, none of which resembled the last.
+ *
+ * Renders nothing in a production build, and nothing in development either
+ * until the page is asked for an arm by name, so a page loaded without the
+ * parameter is what ships.
+ *
+ * An arm carries CSS when the decision is a treatment. When it is a value the
+ * page reads at runtime, a pace or a shader uniform, the arm carries no CSS
+ * and the module holding that value reads the active id off
+ * `document.documentElement.dataset[param]`.
+ */
+interface Arm {
+  /** Appears in the URL. Use `0` for what ships, so the baseline is an arm. */
+  readonly id: string
+  /** Names the arm and what it costs, since an arm with no cost is not one. */
+  readonly label: string
+  readonly css?: string
+}
+
+interface Props {
+  /** The query parameter, which is also the dataset key an arm is read from. */
+  readonly param: string
+  readonly arms: readonly Arm[]
+  /**
+   * Where the switcher mounts, as a selector. A decision inside a modal needs
+   * its switcher inside that modal, since anything outside it sits under the
+   * backdrop. Defaults to the body.
+   */
+  readonly mountInto?: string
+}
+
+const { param, arms, mountInto } = Astro.props
+
+// The component leaves the production tree rather than gating itself at
+// runtime, so neither an arm nor the parameter can reach a reader.
+const enabled = import.meta.env.DEV
+
+// Held as a string and written with `set:html`. Inside an Astro expression a
+// script's children are parsed the way JSX children are, so every brace in the
+// source reads as an interpolation and the body ships as an unevaluated
+// literal. It did, once, silently.
+const SOURCE = `
+const wanted = new URLSearchParams(location.search).get(param)
+const active = arms.find((arm) => arm.id === wanted)
+
+if (active) {
+  document.documentElement.dataset[param] = active.id
+
+  if (active.css) {
+    const style = document.createElement('style')
+    style.textContent = active.css
+    document.head.appendChild(style)
+  }
+
+  const render = () => {
+    const host = mountInto ? document.querySelector(mountInto) : document.body
+    if (!host) return
+    const bar = document.createElement('div')
+    bar.setAttribute('data-scenario-switcher', '')
+    for (const arm of arms) {
+      const link = document.createElement('a')
+      link.href = '?' + param + '=' + arm.id
+      link.textContent = arm.label
+      if (arm.id === active.id) link.setAttribute('data-current', 'true')
+      bar.appendChild(link)
+    }
+    host.appendChild(bar)
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', render)
+  } else {
+    render()
+  }
+}
+`
+
+const SWITCHER_CSS = `
+/* Bottom left rather than bottom centre, which Astro's dev toolbar owns.
+   Centred, the toolbar sits over the switcher and swallows every click on it. */
+[data-scenario-switcher] {
+  position: fixed;
+  left: 1.5rem;
+  bottom: 1.5rem;
+  z-index: 60;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  max-width: calc(100vw - 3rem);
+  font: 500 13px system-ui, sans-serif;
+}
+[data-scenario-switcher] a {
+  padding: 0.4rem 0.8rem;
+  border: 1px solid rgb(128 128 128 / 0.4);
+  border-radius: 999px;
+  background: rgb(255 255 255 / 0.9);
+  color: #1a1815;
+  text-decoration: none;
+  white-space: nowrap;
+}
+[data-scenario-switcher] a[data-current='true'] {
+  background: #1a1815;
+  color: #f8f4ed;
+}
+`
+---
+
+{
+  enabled && (
+    <script
+      is:inline
+      define:vars={{ param, arms, mountInto }}
+      set:html={SOURCE}
+    />
+  )
+}
+
+{enabled && <style is:global set:html={SWITCHER_CSS} />}

package/tooling/astro/reference.md

@@ -58,3 +58,10 @@ Append to the `## Scripts` table:
 ## CI docs (extend)
 
 In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
+
+## Scenario switcher
+
+- `src/components/dev/scenarios.astro` ships as a golden config, always overwritten on sync, since it is toolkit-authored infrastructure rather than a file a project hand-edits.
+- Import it into a page under test to drive candidate treatments of one decision by hand, selected by a query parameter, with a switcher for moving between them.
+- Guarded by `import.meta.env.DEV`, so it renders nothing and ships nothing in a production build.
+- Astro-only. It uses `is:inline`, `define:vars`, and `set:html`, which only the `.astro` file format parses. `vite-react` gets no equivalent until a real decision drives one.