@awarebydefault/display-case 1.0.0

package/src/ui/primer.tsx

@@ -0,0 +1,277 @@
+import type { ReactNode } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
+import { slugify } from '../core/catalog'
+
+/**
+ * The Primer — Display Case's long-form "wall text". A consumer authors an
+ * `.mdx` document (referenced from `display-case.config.ts`), and it renders
+ * here as a scrolling reading page with embedded LIVE specimens. The MDX can
+ * import any component — case files *and* arbitrary `.tsx` — and wraps each
+ * specimen in the {@link Display} contract below.
+ *
+ * This module is bundled into the isolated `/render/primer` document (never the browse
+ * chrome), so a specimen that throws on load can't blank the chrome — the same
+ * isolation the `/render` frame gives a case. It talks to the chrome over
+ * `postMessage`: it reports its section list (for the sidebar table of contents)
+ * and the active section on scroll, and accepts scroll-to / theme messages back.
+ */
+
+export interface DisplayProps {
+  /** Specimen title — also the sidebar table-of-contents label and scroll anchor. */
+  title: string
+  /** Optional one-line description shown under the title. */
+  subtitle?: string
+  /** Force a theme inside this specimen (e.g. show a dark-mode component on a
+   *  light primer). Omit to inherit the primer's current theme. */
+  theme?: 'light' | 'dark'
+  /** Drop the specimen's own border and padding so a single self-bordered child
+   *  (e.g. a DefinitionList) fills the box edge-to-edge — avoids a
+   *  box-within-a-box. The child supplies the border; this frame just clips it. */
+  flush?: boolean
+  /** Paint the specimen box with the consumer design system's own canvas
+   *  (`--color-bg`/`--color-fg`) instead of the Vitrine's `--dc-bg`, so the
+   *  component sits on the exact background the real app gives it. Opt-in;
+   *  degrades to `--dc-bg` when the consumer defines no `--color-bg`. Combine
+   *  with `theme` to show the app's themed surface. */
+  appSurface?: boolean
+  children?: ReactNode
+}
+
+/**
+ * The contract an `.mdx` primer wraps each live specimen in. Renders a titled
+ * card; the body is a flex row the specimen lays out in. `theme` forces a
+ * light/dark scope local to the card.
+ *
+ * @example
+ * <Display title="Button" subtitle="The quiet bordered control" theme="dark">
+ *   <Button variant="accent">Snapshot</Button>
+ * </Display>
+ */
+export function Display({
+  title,
+  subtitle,
+  theme,
+  flush,
+  appSurface,
+  children,
+}: DisplayProps) {
+  return (
+    <section
+      className="dc-display"
+      id={`section-${slugify(title)}`}
+      data-dc-section=""
+      data-dc-title={title}>
+      <div className="dc-display-head">
+        <div className="dc-display-title">{title}</div>
+        {subtitle ? <div className="dc-display-sub">{subtitle}</div> : null}
+      </div>
+      <div
+        className="dc-display-specimen"
+        data-theme={theme}
+        data-flush={flush ? '' : undefined}
+        data-app-surface={appSurface ? '' : undefined}>
+        {children}
+      </div>
+    </section>
+  )
+}
+
+interface PrimerSection {
+  id: string
+  title: string
+  /** `heading` is a `##` group header; `display` is a specimen card under it. */
+  kind: 'heading' | 'display'
+}
+
+/** Flatten a React node tree to its text content (for a heading's slug + label). */
+function textOf(node: ReactNode): string {
+  if (node == null || typeof node === 'boolean') return ''
+  if (typeof node === 'string' || typeof node === 'number') return String(node)
+  if (Array.isArray(node)) return node.map(textOf).join('')
+  if (typeof node === 'object' && 'props' in node)
+    return textOf(
+      (node as { props?: { children?: ReactNode } }).props?.children,
+    )
+  return ''
+}
+
+/**
+ * The `#`/`##` headings in a primer MDX. Beyond rendering the prose heading,
+ * each becomes a navigable group header in the sidebar table of contents: the
+ * Displays that follow it nest under it (see {@link PrimerRoot} reporting). The
+ * H1 thus doubles as the "top of page" entry, with its intro specimens nested.
+ */
+function PrimerHeading({
+  tag: Tag,
+  children,
+}: {
+  tag: 'h1' | 'h2'
+  children?: ReactNode
+}) {
+  const text = textOf(children)
+  return (
+    <Tag
+      id={`heading-${slugify(text)}`}
+      data-dc-heading=""
+      data-dc-title={text}>
+      {children}
+    </Tag>
+  )
+}
+
+/** Components map handed to the compiled MDX — resolves `<Display>` and `#`/`##`. */
+export const primerComponents = {
+  Display,
+  h1: ({ children }: { children?: ReactNode }) => (
+    <PrimerHeading tag="h1">{children}</PrimerHeading>
+  ),
+  h2: ({ children }: { children?: ReactNode }) => (
+    <PrimerHeading tag="h2">{children}</PrimerHeading>
+  ),
+}
+
+/**
+ * The scrolling reading page. Renders the compiled MDX document and wires the
+ * scrollspy ↔ chrome messaging: it reports the section list and the active
+ * section, and reacts to scroll-to / theme messages from the parent chrome.
+ */
+export function PrimerRoot({
+  content,
+}: {
+  content: (props: { components?: unknown }) => ReactNode
+}) {
+  // Capitalize for JSX use (the compiled MDX document is a component).
+  const Content = content
+  const scrollRef = useRef<HTMLDivElement | null>(null)
+  // During a click-driven smooth scroll, the highlight is locked to the target
+  // and scrollspy is paused — otherwise the active row flickers across every
+  // section the scroll passes over (many hidden inside collapsed nav groups).
+  const programmatic = useRef(false)
+  const settleTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const embedded = typeof window !== 'undefined' && window.parent !== window
+
+  const post = useCallback(
+    (message: unknown) => {
+      if (embedded) window.parent.postMessage(message, '*')
+    },
+    [embedded],
+  )
+
+  // Both `##` headings and Displays anchor the table of contents; in document
+  // order they let the chrome nest each Display under its heading.
+  const sectionEls = useCallback((): HTMLElement[] => {
+    const root = scrollRef.current
+    if (!root) return []
+    return Array.from(
+      root.querySelectorAll<HTMLElement>(
+        '[data-dc-section], [data-dc-heading]',
+      ),
+    )
+  }, [])
+
+  const reportSections = useCallback(() => {
+    const sections: PrimerSection[] = sectionEls().map((el) => ({
+      id: el.id,
+      title: el.dataset.dcTitle ?? el.id,
+      kind: el.hasAttribute('data-dc-heading') ? 'heading' : 'display',
+    }))
+    post({ type: 'dc-primer-sections', sections })
+  }, [post, sectionEls])
+
+  const reportActive = useCallback(() => {
+    const root = scrollRef.current
+    if (!root) return
+    const els = sectionEls()
+    if (!els.length) return
+    // At (or near) the bottom the last section can't scroll to the top, so the
+    // "topmost past the line" rule would never reach it — pin it active there.
+    const atBottom = root.scrollTop + root.clientHeight >= root.scrollHeight - 4
+    let active = els[0].id
+    if (atBottom) {
+      active = els[els.length - 1].id
+    } else {
+      const top = root.getBoundingClientRect().top
+      for (const el of els) {
+        if (el.getBoundingClientRect().top - top <= 80) active = el.id
+      }
+    }
+    post({ type: 'dc-primer-active', id: active })
+  }, [post, sectionEls])
+
+  // Resume scrollspy once a programmatic scroll has settled (no scroll events
+  // for a beat) and re-sync the active section to where it actually landed. Also
+  // covers the no-op case where the target is already at the top, so nothing
+  // ever scrolls and `onScroll` never fires to release the lock.
+  const armSettle = useCallback(() => {
+    if (settleTimer.current) clearTimeout(settleTimer.current)
+    settleTimer.current = setTimeout(() => {
+      programmatic.current = false
+      reportActive()
+    }, 150)
+  }, [reportActive])
+
+  // Report the section list once mounted (and whenever the content resizes, e.g.
+  // late fonts/images shifting offsets), and keep the active section current.
+  useEffect(() => {
+    const root = scrollRef.current
+    if (!root) return
+    reportSections()
+    reportActive()
+    post({ type: 'dc-primer-ready' })
+    const onScroll = () => {
+      // While a click-driven scroll animates, hold the highlight on the target
+      // and just keep pushing the settle deadline out until the motion stops.
+      if (programmatic.current) {
+        armSettle()
+        return
+      }
+      reportActive()
+    }
+    root.addEventListener('scroll', onScroll, { passive: true })
+    const ro = new ResizeObserver(() => {
+      reportSections()
+      reportActive()
+    })
+    ro.observe(root)
+    return () => {
+      root.removeEventListener('scroll', onScroll)
+      ro.disconnect()
+      if (settleTimer.current) clearTimeout(settleTimer.current)
+    }
+  }, [reportSections, reportActive, armSettle, post])
+
+  // Accept scroll-to (sidebar TOC click) and theme messages from the chrome.
+  useEffect(() => {
+    function onMessage(e: MessageEvent) {
+      if (e.source !== window.parent) return
+      const data = e.data as { type?: string; id?: string; theme?: string }
+      if (data?.type === 'dc-primer-scroll' && data.id) {
+        // Section ids are slug-safe (`section-<kebab>`), so id lookup needs no
+        // escaping — and the local `CSS` here is the style string, not the global.
+        const el = document.getElementById(data.id)
+        if (el) {
+          // Lock the highlight to the clicked target and pause scrollspy until
+          // the smooth scroll settles, so it doesn't crawl across intermediate
+          // (often hidden) sections on the way there.
+          programmatic.current = true
+          post({ type: 'dc-primer-active', id: data.id })
+          el.scrollIntoView({ behavior: 'smooth', block: 'start' })
+          armSettle()
+        }
+      } else if (data?.type === 'dc-primer-theme' && data.theme) {
+        document.documentElement.dataset.theme = data.theme
+        document.documentElement.dataset.themePref = data.theme
+      }
+    }
+    window.addEventListener('message', onMessage)
+    return () => window.removeEventListener('message', onMessage)
+  }, [post, armSettle])
+
+  return (
+    <div className="dc-primer" ref={scrollRef}>
+      <div className="dc-primer-inner">
+        <Content components={primerComponents} />
+      </div>
+    </div>
+  )
+}

package/src/ui/render-mount.tsx

@@ -0,0 +1,284 @@
+import { flushSync } from 'react-dom'
+import type { Root } from 'react-dom/client'
+import { createRoot, hydrateRoot } from 'react-dom/client'
+import { slugify } from '../core/catalog'
+import type { CaseModule, DisplayCaseConfig, GotoFn } from '../index'
+import { caseTree, encodeOverrides } from '../render/render-node'
+
+/**
+ * Entry point for the isolated `/render/:component/:case` document. Renders
+ * exactly one case (wrapped in the optional decorator) into #root and nothing
+ * else — this is what the browse iframe embeds and what screenshot tools
+ * capture.
+ *
+ * Three ways to drive it:
+ *  - **Standalone** (snapshot/screenshot tools, direct navigation): the target
+ *    case + theme + width + tweaks are read from the URL on load.
+ *  - **Embedded** (browse chrome iframe): after announcing readiness, the parent
+ *    pushes `dc-render` messages to swap case/theme/width/tweaks *in place*, so
+ *    the iframe never reloads or remounts — no flicker on switch or tweak.
+ *  - **In-flow transition**: a flow step calls its injected `goto`, which makes
+ *    the target step active in place, updates the address (so the new step is
+ *    deep-linkable/snapshottable), and notifies the chrome via `dc-step-changed`.
+ */
+
+interface RenderState {
+  componentId: string
+  caseId: string
+  theme: 'light' | 'dark'
+  width: number | null
+  tweaks: Record<string, string>
+  /** Shrink-wrap #root to the case's natural width (so a small component
+   *  doesn't stretch to fill the frame). Driven by the browse chrome. */
+  fit: boolean
+  /** Drop the document background so the component shows on the stage's grid.
+   *  Decorated components only; the chrome never sets it for pages/flows. */
+  transparent: boolean
+}
+
+interface NavOptions {
+  /** Push the active step to history so it is directly addressable. */
+  pushUrl?: boolean
+  /** Tell the parent chrome the active step changed (in-flow transitions). */
+  notifyParent?: boolean
+}
+
+function stateFromUrl(): RenderState {
+  const params = new URLSearchParams(window.location.search)
+  const parts = window.location.pathname.split('/').filter(Boolean)
+  const widthParam = params.get('width')
+  const tweaks: Record<string, string> = {}
+  for (const [k, v] of params) {
+    if (k.startsWith('t.')) tweaks[k.slice(2)] = v
+  }
+  return {
+    // Path shape: /render/<component>/<case>
+    componentId: parts[1] ?? '',
+    caseId: parts[2] ?? '',
+    theme: params.get('theme') === 'dark' ? 'dark' : 'light',
+    width: widthParam ? Number(widthParam) : null,
+    tweaks,
+    fit: params.get('fit') === '1',
+    transparent: params.get('transparent') === '1',
+  }
+}
+
+/** Write the active step into the address so it can be deep-linked/snapshotted. */
+function pushStepUrl(state: RenderState): void {
+  const params = new URLSearchParams()
+  params.set('theme', state.theme)
+  if (state.width) params.set('width', String(state.width))
+  for (const [k, v] of Object.entries(state.tweaks)) params.set(`t.${k}`, v)
+  window.history.pushState(
+    null,
+    '',
+    `/render/${state.componentId}/${state.caseId}?${params.toString()}`,
+  )
+}
+
+/**
+ * Apply a render's document-level effects — the parts that live outside the
+ * React tree and so are set imperatively, not rendered. The server bakes these
+ * same values into the delivered document (so the first paint is correct and
+ * hydration matches); re-applying them here is idempotent on first load and
+ * carries an in-place swap (theme/width/transparent change) that the server
+ * never sees.
+ */
+function applyDocEffects(state: RenderState): void {
+  document.documentElement.dataset.theme = state.theme
+  // Also set the explicit preference so a `ThemeProvider` used inside app chrome
+  // (e.g. Navbar's ThemeToggle) initializes to the harness theme
+  // rather than re-resolving from the OS and fighting the `?theme=` selection.
+  document.documentElement.dataset.themePref = state.theme
+
+  // Shrink-wrap the mount to the case's natural width when asked, so a
+  // block/flex-rooted component (which would otherwise fill the full-width
+  // frame) renders at its intrinsic size. The chrome measures the result and
+  // hugs the stage to it. Cleared (full width) for pages/flows and presets.
+  const mount = document.getElementById('root')
+  if (mount) mount.style.width = state.fit ? 'fit-content' : ''
+
+  // Drop the document background so a decorated component sits directly on the
+  // stage's dotted grid (the chrome's stage frame paints the surface + grid
+  // behind the transparent iframe). Cleared back to the token bg otherwise.
+  document.body.style.background = state.transparent ? 'transparent' : ''
+
+  // Mark decorated exhibits (atoms…templates — never pages/flows, which lay out
+  // their own full-bleed structure) so the render doc can center the exhibit's
+  // content in the frame by default. Keyed off the same flag as `transparent`.
+  document.body.toggleAttribute('data-decorated', state.transparent)
+}
+
+/** Build the case's React tree — the identical tree the server pre-rendered —
+ *  wiring a flow step's `goto` to drive an in-place transition. */
+function treeFor(
+  modules: CaseModule[],
+  config: DisplayCaseConfig,
+  state: RenderState,
+  navigate: (next: RenderState, opts?: NavOptions) => void,
+) {
+  const goto: GotoFn = (target, overrides) => {
+    // A transition makes the target step active in place; the new step gets its
+    // own address (overrides become its preset state) and the chrome is told to
+    // follow.
+    navigate(
+      { ...state, caseId: slugify(target), tweaks: encodeOverrides(overrides) },
+      { pushUrl: true, notifyParent: true },
+    )
+  }
+  return caseTree(
+    modules,
+    config,
+    {
+      componentId: state.componentId,
+      caseId: state.caseId,
+      width: state.width,
+      tweaks: state.tweaks,
+    },
+    goto,
+  )
+}
+
+/**
+ * Neutralize anchor clicks that would unload the render frame. A case or flow
+ * step can legitimately render a real `<a href="/dashboard">` (the route would
+ * supply a router `<Link>`), but in this isolated frame there is no router, so a
+ * click does a full-document navigation to a non-render path. The server then
+ * serves the browse shell *into the frame*, nesting a shell and severing the
+ * parent↔frame handshake — every case/flow appears broken until a manual reload.
+ * Same-document hash links (in-page scroll) and `target=_blank` (new context)
+ * are harmless and left alone.
+ */
+function blockFrameNavigation(): void {
+  document.addEventListener(
+    'click',
+    (e) => {
+      if (
+        e.defaultPrevented ||
+        e.button !== 0 ||
+        e.metaKey ||
+        e.ctrlKey ||
+        e.shiftKey ||
+        e.altKey
+      ) {
+        return
+      }
+      const anchor = (e.target as HTMLElement | null)?.closest?.('a')
+      const href = anchor?.getAttribute('href')
+      if (!anchor || !href) return
+      if (anchor.target && anchor.target !== '_self') return // new tab/window
+      const url = new URL(href, window.location.href)
+      const sameDocumentHash =
+        url.pathname === window.location.pathname &&
+        url.search === window.location.search &&
+        url.hash !== ''
+      if (sameDocumentHash) return // in-page scroll, doesn't unload the frame
+      e.preventDefault()
+    },
+    true,
+  )
+}
+
+export function mountRender(
+  modules: CaseModule[],
+  config: DisplayCaseConfig,
+): void {
+  blockFrameNavigation()
+  const rootEl = document.getElementById('root') as HTMLElement
+  // The server pre-rendered the case into #root and flagged it `data-ssr="1"`;
+  // adopt that markup instead of mounting from scratch. A browser-only case is
+  // delivered empty (`data-ssr="0"`) and mounted fresh on the client.
+  const ssr = rootEl.dataset.ssr === '1'
+  let root: Root | null = null
+  let state = stateFromUrl()
+  const embedded = !!(window.parent && window.parent !== window)
+
+  // Report the rendered content's natural size to the browse chrome so it can
+  // shrink the iframe to the component (instead of stretching it to fill the
+  // panel) and center it on the stage. Measured off #root: its block height is
+  // the content height regardless of the iframe's (possibly taller) viewport,
+  // which `documentElement.scrollHeight` would clamp to. Hoisted above navigate
+  // so every swap re-announces the size — the ResizeObserver below only fires on
+  // an actual size *change*, so a swap between two same-size cases would never
+  // re-report, leaving the chrome (which hides the stage until the new size
+  // lands) waiting forever.
+  const postSize = (): void => {
+    if (!embedded) return
+    window.parent.postMessage(
+      {
+        type: 'dc-size',
+        size: {
+          height: Math.ceil(rootEl.scrollHeight),
+          width: Math.ceil(rootEl.scrollWidth),
+        },
+      },
+      '*',
+    )
+  }
+
+  // Single entry point for every state change — initial render, parent-driven
+  // `dc-render` swaps, and in-flow `goto` transitions all flow through here.
+  const navigate = (next: RenderState, opts: NavOptions = {}): void => {
+    state = next
+    if (opts.pushUrl) pushStepUrl(state)
+    if (opts.notifyParent && embedded) {
+      window.parent.postMessage(
+        {
+          type: 'dc-step-changed',
+          state: {
+            componentId: state.componentId,
+            caseId: state.caseId,
+            tweaks: state.tweaks,
+          },
+        },
+        '*',
+      )
+    }
+    applyDocEffects(state)
+    const tree = treeFor(modules, config, state, navigate)
+    if (!root) {
+      // First commit: adopt the server markup (hydrate) when present, otherwise
+      // mount fresh. Hydration is its own commit, so it isn't wrapped in
+      // flushSync; a recoverable mismatch (a non-deterministic case) is logged
+      // and React re-renders that subtree on the client.
+      if (ssr) {
+        root = hydrateRoot(rootEl, tree, {
+          onRecoverableError: (err) =>
+            console.warn(
+              '[display-case] adopt mismatch; client re-rendered:',
+              err,
+            ),
+        })
+      } else {
+        root = createRoot(rootEl)
+        flushSync(() => (root as Root).render(tree))
+      }
+    } else {
+      // Commit synchronously so the measurement reads this case's layout (not the
+      // previous one's), then re-announce the size for this navigation.
+      flushSync(() => (root as Root).render(tree))
+    }
+    postSize()
+  }
+
+  navigate(state)
+
+  // Async layout changes (late images/fonts, content that resizes after mount)
+  // re-announce via the observer; navigate() covers the synchronous swaps.
+  if (embedded) new ResizeObserver(postSize).observe(rootEl)
+
+  // Embedded mode: accept in-place updates from the browse chrome so switching
+  // case / theme / width / tweaks never reloads the iframe.
+  window.addEventListener('message', (e: MessageEvent) => {
+    if (e.source !== window.parent) return
+    const data = e.data as { type?: string; state?: Partial<RenderState> }
+    if (data?.type !== 'dc-render' || !data.state) return
+    navigate({ ...state, ...data.state })
+  })
+
+  // Announce readiness so the parent can push the current selection. Harmless
+  // when standalone (parent is self; no dc-render messages are sent).
+  if (window.parent && window.parent !== window) {
+    window.parent.postMessage({ type: 'dc-ready' }, '*')
+  }
+}