@master/internal-site 0.0.0-stage → 0.1.0

package/src/demo/DemoTokenTable.astro

@@ -0,0 +1,34 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import InlineCode from '@master/internal-site/components/InlineCode.astro'
+import RenderNode from '@master/internal-site/components/RenderNode.astro'
+
+export interface DemoTokenRow {
+  token: string
+  utilities: string[]
+  value?: string
+  /** Text or markup (an Astro template value or MDX JSX), rendered with RenderNode. */
+  description: unknown
+  preview?: unknown
+}
+
+interface Props {
+  rows: DemoTokenRow[]
+  descriptionTitle?: string
+}
+
+/** A document inventory, separate from any specimen's measured layout. */
+const { rows, descriptionTitle = 'Role' } = Astro.props
+---
+
+{/* Narrow token inventories need native keyboard scrolling. */}
+<div class="ui-table" role="region" aria-label={`${descriptionTitle} token table`} tabindex="0"><table>
+  <thead><tr><th scope="col">Token / class</th><th scope="col" class="(min-width:12rem)">{descriptionTitle}</th></tr></thead>
+  <tbody>{rows.map(({ token, utilities, value, description, preview }) => <tr>
+    <td>
+      <div class="whitespace-nowrap">{preview != null && <RenderNode node={preview} />}<code>{token}</code></div>
+      {utilities.length > 0 && <div class="flex flex-wrap gap-xs mt-xs">{utilities.map(utility => <InlineCode class="whitespace-nowrap" code={utility} />)}</div>}
+    </td>
+    <td>{value && <div class="mb-xs"><code>{value}</code></div>}<RenderNode node={description} /></td>
+  </tr>)}</tbody>
+</table></div>

package/src/demo/DemoViewTransition.astro

@@ -0,0 +1,18 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
+
+interface Props {
+  example?: 'views' | 'articles'
+  origin?: string
+}
+
+const { example = 'views', origin = '' } = Astro.props
+const articles = example === 'articles'
+const title = articles ? 'From collection to article' : 'A change of view'
+---
+
+<Demo title={title} frame="none" data-view-transition={example}
+  caption={articles ? 'Open an article, then return to its card. Each image and title keeps a unique snapshot name. Keyboard focus follows the view change.' : 'Choose a view. The panel and heading use named snapshots; unsupported browsers and reduced motion use the same immediate update.'}>
+  <DemoViewport client:idle={{ timeout: 500 }} title={title} src={origin + (articles ? '/examples/article-transitions' : '/examples/view-transitions')} height={articles ? 640 : 340} sizing="viewport" />
+</Demo>

package/src/demo/DemoViewport.svelte

@@ -0,0 +1,324 @@
+<script module lang="ts">
+  interface ViewportOptions {
+    title: string
+    /** Resize the actual iframe viewport. */
+    responsive?: boolean
+    /** Browser chrome; only where the viewport itself is the lesson. Defaults to `responsive`. The tray head names the document. */
+    chrome?: boolean
+    /** The width range's caption: what the range sizes. */
+    rangeLabel?: string
+    /** Named real viewport widths; the first is the initial width when responsive. */
+    widthPresets?: readonly { label: string; width: number }[]
+    motion?: boolean
+    print?: boolean
+    theme?: boolean
+    /** Pin the initial mode; omit to follow the surrounding document. */
+    initialTheme?: 'light' | 'dark'
+    inspect?: string[]
+    height?: number
+    /** Upper bound for the actual iframe width, including wide breakpoint examples. */
+    maxWidth?: number
+    /** Content sizing is only for normal flow, never viewport-dependent geometry. */
+    sizing?: 'viewport' | 'content'
+  }
+
+  export type DemoViewportProps = ViewportOptions & (
+    { document: string, src?: never } | { document?: never, src: string }
+  )
+</script>
+
+<script lang="ts">
+  import { untrack } from 'svelte'
+  import IconMoon from '@tabler/icons-svelte-runes/icons/moon'
+  import IconPlayerPause from '@tabler/icons-svelte-runes/icons/player-pause'
+  import IconPlayerPlay from '@tabler/icons-svelte-runes/icons/player-play'
+  import IconPrinter from '@tabler/icons-svelte-runes/icons/printer'
+  import IconRefresh from '@tabler/icons-svelte-runes/icons/refresh'
+  import IconSun from '@tabler/icons-svelte-runes/icons/sun'
+  import { demoPlayback, type PlaybackAction } from '@master/internal-site/demo/playback.ts'
+  import { demoDragReadings } from '@master/internal-site/demo/drag-readings.ts'
+
+  let { title, document: source, src, responsive = false, chrome = responsive, rangeLabel = 'Viewport', widthPresets, motion = false, print = false, theme = false, initialTheme, inspect, height = 260, maxWidth = 1600, sizing = 'viewport' }: DemoViewportProps = $props()
+  let frame = $state<HTMLIFrameElement>()
+  let body = $state<HTMLDivElement>()
+  let cleanup = () => {}
+  let playback: ReturnType<typeof demoPlayback> | null = null
+  // Initial values only, like the props that seed them.
+  let width = $state<number | undefined>(untrack(() => responsive ? widthPresets?.[0]?.width : undefined))
+  let fitWidth = $state(480)
+  let minimumWidth = $state(240)
+  let dark = $state<boolean | undefined>(untrack(() => initialTheme === undefined ? undefined : initialTheme === 'dark'))
+  let isDark = $state(false)
+  let playing = $state(false)
+  let ready = $state(false)
+  let contentHeight = $state<number>()
+  let properties = $state('')
+  const widthId = $props.id()
+
+  function load() {
+    cleanup()
+    const doc = frame?.contentDocument
+    const view = frame?.contentWindow
+    if (!frame || !view || !doc?.documentElement || !doc.body?.childElementCount) return
+    const iframe = frame
+    let active = true
+    // Resize/font/event callbacks can run after removal but before effect
+    // cleanup, or after the same iframe has loaded a new document.
+    const current = () => active && iframe.isConnected && iframe.contentDocument === doc
+    const applyTheme = () => {
+      if (!current()) return
+      const mode = dark ?? document.documentElement.classList.contains('dark')
+      doc.documentElement.classList.toggle('dark', mode)
+      doc.documentElement.classList.toggle('light', !mode)
+      doc.documentElement.style.colorScheme = mode ? 'dark' : 'light'
+      isDark = mode
+    }
+    const writeReading = (output: HTMLElement, value: string) => {
+      if (output.textContent !== value) output.textContent = value
+    }
+    const updateReadings = () => {
+      if (!current()) return
+      doc.querySelectorAll<HTMLElement>('[data-font-status]').forEach(output => {
+        const family = output.dataset.fontStatus!
+        const faces = [...doc.fonts].filter(face => face.family.replace(/^["']|["']$/g, '') === family)
+        writeReading(output, faces.some(face => face.status === 'loaded') ? 'Loaded'
+          : faces.some(face => face.status === 'loading') ? 'Loading…' : 'Unavailable · fallback')
+      })
+      doc.querySelectorAll<HTMLElement>('[data-size-readout]').forEach(output => {
+        const element = doc.getElementById(output.dataset.sizeReadout!)
+        if (!element) return
+        const box = element.getBoundingClientRect()
+        writeReading(output, `${Math.round(box.width * 10) / 10} × ${Math.round(box.height * 10) / 10} px`)
+      })
+      doc.querySelectorAll<HTMLElement>('[data-layout-axis]').forEach(output => {
+        const element = doc.getElementById(output.dataset.layoutAxis!)
+        if (!element) return
+        const style = view.getComputedStyle(element)
+        writeReading(output, style.display.includes('flex')
+          ? `Main axis · ${style.flexDirection.startsWith('row') ? 'inline' : 'block'}${style.flexDirection.endsWith('reverse') ? ' · reversed' : ''}`
+          : style.display.includes('grid') ? 'Grid auto-placement' : 'Normal block flow')
+      })
+      doc.querySelectorAll<HTMLElement>('[data-alignment-axis]').forEach(output => {
+        const element = doc.getElementById(output.dataset.alignmentAxis!)
+        if (!element) return
+        const style = view.getComputedStyle(element)
+        const main = style.display.includes('flex') && style.flexDirection.startsWith('column') ? 'block' : 'inline'
+        const cross = main === 'inline' ? 'block' : 'inline'
+        writeReading(output, output.dataset.axisKind === 'both' ? `${cross} + ${main} axes` : `${output.dataset.axisKind === 'cross' ? cross : main} axis`)
+      })
+      doc.querySelectorAll<HTMLElement>('[data-style-readout]').forEach(output => {
+        const element = doc.getElementById(output.dataset.styleReadout!)
+        if (!element) return
+        const value = view.getComputedStyle(element, output.dataset.stylePseudo || null).getPropertyValue(output.dataset.styleProperty!)
+        if (output.hasAttribute('data-round-pixels')) {
+          output.title = value
+          writeReading(output, (value || output.dataset.emptyValue || '').replace(/(-?\d*\.?\d+)px\b/g, (_, number: string) => `${Math.round(Number(number) * 10) / 10}px`))
+        } else writeReading(output, value || output.dataset.emptyValue || '')
+      })
+      doc.querySelectorAll<HTMLElement>('[data-position-readout]').forEach(output => {
+        const element = doc.getElementById(output.dataset.positionReadout!)
+        const origin = doc.getElementById(output.dataset.positionOrigin!)
+        if (!element || !origin) return
+        const box = element.getBoundingClientRect(), parent = origin.getBoundingClientRect()
+        writeReading(output, `x ${Math.round((box.left - parent.left - origin.clientLeft) * 10) / 10} · y ${Math.round((box.top - parent.top - origin.clientTop) * 10) / 10} px`)
+      })
+      doc.querySelectorAll<HTMLElement>('[data-scroll-readout]').forEach(output => {
+        const element = doc.getElementById(output.dataset.scrollReadout!)
+        if (element) writeReading(output, `x ${Math.round(element.scrollLeft)} · y ${Math.round(element.scrollTop)} px`)
+      })
+      doc.querySelectorAll<HTMLElement>('[data-scroll-offset]').forEach(output => {
+        const target = doc.getElementById(output.dataset.scrollOffset!)
+        const port = doc.getElementById(output.dataset.scrollport!)
+        if (!target || !port) return
+        const box = target.getBoundingClientRect(), container = port.getBoundingClientRect()
+        const offset = output.dataset.scrollAxis === 'x' ? box.left - container.left - port.clientLeft : box.top - container.top - port.clientTop
+        writeReading(output, `${Math.round(offset)} px`)
+      })
+    }
+    const update = () => {
+      if (!current()) return
+      updateReadings()
+      if (sizing === 'content') {
+        // The root's normal-flow box includes collapsed body/child margins.
+        // scrollHeight is at least the current viewport and cannot shrink it.
+        contentHeight = Math.max(96, Math.ceil(doc.documentElement.getBoundingClientRect().height))
+      }
+      fitWidth = Math.round(iframe.clientWidth)
+      minimumWidth = Math.min(240, body?.clientWidth ?? 240, maxWidth)
+      const target = doc.querySelector('[data-target]')
+      if (target && inspect?.length) {
+        const computed = view.getComputedStyle(target)
+        properties = inspect.map(name => `${name}: ${computed.getPropertyValue(name)}`).join(' · ')
+      }
+    }
+    applyTheme()
+    update()
+    const themeObserver = new MutationObserver(() => { applyTheme(); update() })
+    themeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
+    // Svelte flushes state in a microtask, still inside the observer's delivery,
+    // so resizing the iframe there trips WebKit's ResizeObserver loop error.
+    let resizeTimer: ReturnType<typeof setTimeout> | undefined
+    const resizeObserver = new ResizeObserver(() => {
+      clearTimeout(resizeTimer)
+      resizeTimer = setTimeout(update)
+    })
+    resizeObserver.observe(iframe)
+    if (body) resizeObserver.observe(body)
+    if (sizing === 'content') {
+      resizeObserver.observe(doc.body)
+      resizeObserver.observe(doc.documentElement)
+    }
+    doc.querySelectorAll<HTMLElement>('[data-size-readout]').forEach(output => {
+      const element = doc.getElementById(output.dataset.sizeReadout!)
+      if (element) resizeObserver.observe(element)
+    })
+    const controller = motion || doc.querySelector('[data-animation-readout]') ? demoPlayback(doc, motion, value => { playing = value }, update) : null
+    const disposeDragReadings = doc.querySelector('[data-drag-readout]') ? demoDragReadings(doc) : undefined
+    playback = controller
+    const preference = matchMedia('(prefers-reduced-motion: reduce)')
+    const preferenceChanged = () => {
+      // Only playback-controlled demos own their animations. Native transitions
+      // follow the authored media queries and must be allowed to finish.
+      if (motion) controller?.pause()
+      if (controller) controller.refresh()
+      else update()
+    }
+    preference.addEventListener('change', preferenceChanged)
+    doc.addEventListener('scroll', updateReadings, true)
+    doc.fonts.addEventListener('loadingdone', update)
+    doc.fonts.addEventListener('loadingerror', update)
+    const events = ['pointerover', 'pointerout', 'pointerdown', 'pointerup', 'focusin', 'focusout', 'input', 'click', 'transitionend', 'transitioncancel']
+    const timers = new Set<ReturnType<typeof setTimeout>>()
+    const afterEvent = () => {
+      if (!current()) return
+      const timer = setTimeout(() => { update(); timers.delete(timer) }, 50)
+      timers.add(timer)
+    }
+    events.forEach(event => doc.addEventListener(event, afterEvent))
+    const click = (event: MouseEvent) => {
+      if (!current()) return
+      const target = (event.target as Element).closest<HTMLElement>('[data-scroll-to]')
+      if (target) {
+        if (target.matches('a')) event.preventDefault()
+        const destination = doc.getElementById(target.dataset.scrollTo!)
+        if (destination) {
+          const alignment = view.getComputedStyle(destination).scrollSnapAlign.split(' ')
+          const edge = (value: string): ScrollLogicalPosition => value === 'center' || value === 'end' ? value : 'start'
+          const options: ScrollIntoViewOptions & { container: 'nearest' } = {
+            block: edge(alignment[0]), inline: edge(alignment[1] ?? alignment[0]), container: 'nearest',
+          }
+          // Safari versions that ignore (container:nearest) also scroll the host page.
+          // Restore only host ancestors; the specimen keeps its native CSS alignment.
+          const ancestors: { element: HTMLElement, top: number, left: number }[] = []
+          for (let element = iframe.parentElement; element; element = element.parentElement) {
+            if (element.scrollHeight > element.clientHeight || element.scrollWidth > element.clientWidth) {
+              ancestors.push({ element, top: element.scrollTop, left: element.scrollLeft })
+            }
+          }
+          destination.scrollIntoView(options)
+          ancestors.forEach(({ element, top, left }) => element.scrollTo({ top, left, behavior: 'instant' }))
+        }
+      }
+      const advance = (event.target as Element).closest<HTMLElement>('[data-scroll-by]')
+      if (advance) {
+        const container = doc.getElementById(advance.dataset.scrollBy!)
+        const distance = Number(advance.dataset.scrollDistance)
+        if (container && Number.isFinite(distance)) container.scrollBy({ left: distance, behavior: 'instant' })
+      }
+      const scrollButton = (event.target as Element).closest<HTMLElement>('[data-scroll-container]')
+      if (scrollButton) {
+        const container = doc.getElementById(scrollButton.dataset.scrollContainer!)
+        const end = scrollButton.dataset.scrollEdge === 'end'
+        container?.scrollTo({ top: end ? container.scrollHeight : 0, left: end ? container.scrollWidth : 0, behavior: 'instant' })
+      }
+    }
+    doc.addEventListener('click', click)
+    ready = true
+    cleanup = () => {
+      active = false
+      themeObserver.disconnect()
+      resizeObserver.disconnect()
+      clearTimeout(resizeTimer)
+      preference.removeEventListener('change', preferenceChanged)
+      doc.removeEventListener('scroll', updateReadings, true)
+      doc.fonts.removeEventListener('loadingdone', update)
+      doc.fonts.removeEventListener('loadingerror', update)
+      events.forEach(event => doc.removeEventListener(event, afterEvent))
+      doc.removeEventListener('click', click)
+      timers.forEach(clearTimeout)
+      controller?.dispose()
+      disposeDragReadings?.()
+      if (playback === controller) playback = null
+      cleanup = () => {}
+    }
+  }
+
+  // Reconnect whenever an option the document readings depend on changes.
+  $effect(() => {
+    void [dark, inspect, maxWidth, motion, sizing]
+    untrack(load)
+    return () => cleanup()
+  })
+
+  const animate = (action: PlaybackAction) => playback?.act(action)
+  const range = $derived({ min: minimumWidth, max: Math.max(minimumWidth, maxWidth), value: width ?? fitWidth })
+  /** The handle mirrors the range input for pointers; the input stays the keyboard control. */
+  const drag = (event: PointerEvent & { currentTarget: HTMLSpanElement }) => {
+    const handle = event.currentTarget
+    const viewport = handle.parentElement!
+    const start = { x: event.clientX, width: viewport.getBoundingClientRect().width }
+    // A centered viewport grows on both sides, so its edge moves at half the width change.
+    const scale = start.width < body!.clientWidth - 1 ? 2 : 1
+    handle.setPointerCapture(event.pointerId)
+    const move = (next: PointerEvent) => { width = Math.round(Math.min(range.max, Math.max(range.min, start.width + (next.clientX - start.x) * scale))) }
+    const end = () => {
+      handle.removeEventListener('pointermove', move)
+      handle.removeEventListener('pointerup', end)
+      handle.removeEventListener('pointercancel', end)
+    }
+    handle.addEventListener('pointermove', move)
+    handle.addEventListener('pointerup', end)
+    handle.addEventListener('pointercancel', end)
+  }
+</script>
+
+<!-- The controls belong to the example, not to the document it shows: they sit on the tray between the stage and the source. -->
+<div class="ui-browser" data-variant={chrome ? undefined : 'plain'} data-ready={ready}>
+  {#if chrome}<div class="ui-browser-bar" aria-hidden="true"><span class="ui-browser-dots"><i></i><i></i><i></i></span></div>{/if}
+  <div bind:this={body} class="ui-browser-body">
+    <div class="ui-browser-viewport" style:width={width ? `${width}px` : `min(100%, ${maxWidth}px)`}>
+      <iframe bind:this={frame} {title} srcdoc={source} {src} loading="lazy" data-ready={ready} data-sizing={sizing}
+        style:height={`${sizing === 'content' ? contentHeight ?? height : height}px`} onload={load}></iframe>
+      {#if responsive}<span class="ui-resize" aria-hidden="true" onpointerdown={drag}></span>{/if}
+    </div>
+  </div>
+</div>
+{#if responsive || motion || print || theme || Boolean(inspect?.length)}
+  <div class="ui-browser-tools" role="group" aria-label={`${title} controls`}>
+    {#if responsive}
+      {#if widthPresets?.length}<div class="ui-segmented" role="group" aria-label={`${rangeLabel} presets`}>
+        {#each widthPresets as preset (preset.label)}<button type="button" disabled={!ready}
+          aria-pressed={width === preset.width} onclick={() => { width = preset.width }}>{preset.label}</button>{/each}
+      </div>{/if}
+      <span class="ui-browser-range">
+        <label class="ui-label" data-case="as-is" for={widthId}>{rangeLabel}</label>
+        <input id={widthId} class="ui-range" disabled={!ready} type="range" min={range.min} max={range.max} step="1" value={range.value}
+          style:--value={`${((range.value - range.min) / Math.max(1, range.max - range.min)) * 100}%`}
+          oninput={event => { width = Number(event.currentTarget.value) }} />
+        {#if ready}<output class="ui-browser-size" for={widthId}>{fitWidth} px</output>{/if}
+      </span>
+      <button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => { width = undefined }}>Fit</button>
+    {/if}
+    {#if theme}<button type="button" disabled={!ready} class="ui-button" data-size="sm" aria-pressed={isDark} title="Toggle dark theme" onclick={() => { dark = !isDark }}>
+      {#if isDark}<IconMoon aria-hidden="true" />{:else}<IconSun aria-hidden="true" />{/if}Theme
+    </button>{/if}
+    {#if motion}
+      <button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => animate(playing ? 'pause' : 'play')}>
+        {#if playing}<IconPlayerPause aria-hidden="true" />{:else}<IconPlayerPlay aria-hidden="true" />{/if}{playing ? 'Pause' : 'Play'}
+      </button>
+      <button type="button" disabled={!ready} class="ui-button" data-size="sm" data-variant="quiet" onclick={() => animate('restart')}><IconRefresh aria-hidden="true" />Replay</button>
+    {/if}
+    {#if print}<button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => frame?.contentWindow?.print()}><IconPrinter aria-hidden="true" />Print preview</button>{/if}
+    {#if properties}<output aria-live="polite">{properties}</output>{/if}
+  </div>
+{/if}

package/src/demo/DemoWaterfall.astro

@@ -0,0 +1,30 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import type { DemoWaterfallProps } from '@master/internal-site/demo/demo-waterfall.ts'
+
+type Props = DemoWaterfallProps
+
+/** A conceptual discovery diagram. Keep measured performance in benchmark charts. */
+const { title, description, rows, marker, caption = 'Illustrative order · no time scale' } = Astro.props
+if (marker && (!Number.isFinite(marker.position) || marker.position < 0 || marker.position > 100)) throw new Error('Invalid waterfall marker')
+for (const { label, start, end } of rows) {
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end > 100 || end <= start) throw new Error(`Invalid waterfall interval: ${label}`)
+}
+---
+
+<Demo title={title} description={description} caption={caption} padding="sm" aria-label={title}>
+  <div class="w-full ui-waterfall">
+    <div class="ui-waterfall-axis" aria-hidden="true"><span /><div class="relative"><span>Earlier</span>{marker && <span class="absolute font-medium fg-text-strong (translate:-50%)" style={{ left: `${marker.position}%` }}>{marker.label}</span>}<span>Later</span></div></div>
+    {/* Preserve WebKit list semantics without list markers. */}
+    <ul role="list" class="grid gap-2xs m(0) p(0) (list-style:none)">
+      {rows.map(({ label, start, end, tone = 'blue' }) => <li class="ui-waterfall-row">
+        <span>{label}</span>
+        <span class="ui-waterfall-track" aria-hidden="true">
+          <i data-tone={tone === 'neutral' ? 'muted' : undefined} style={{ left: `${start}%`, width: `${end - start}%`, ...(tone === 'neutral' ? {} : { background: `var(--ui-tone-${tone})` }) }} />
+          {marker && <span class="ui-waterfall-mark" style={{ left: `${marker.position}%` }} />}
+        </span>
+      </li>)}
+    </ul>
+  </div>
+</Demo>

package/src/demo/FoundationBreakpoint.astro

@@ -0,0 +1,12 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
+import { demoDocument } from '@master/internal-site/demo/reference/document.ts'
+
+const html = "<h1 data-target class=\"m(0) font-2xl font-3xl@md\">Build for the current viewport</h1>\n<p class=\"mt-sm fg-text-muted\">The heading changes at the md viewport threshold.</p>"
+const document = demoDocument({ page: 'guide/breakpoints', id: 'viewport', title: 'Viewport typography', html: [html], css: '', classes: [], classLists: [], highlighted: [] }, { html, caption: '' })
+---
+
+<Demo title="Viewport typography" frame="none" data-foundation="breakpoint" caption="Resize the actual iframe across md. The surrounding document keeps its own viewport.">
+  <DemoViewport client:idle={{ timeout: 500 }} title="Viewport typography" document={document} responsive height={200} inspect={['font-size']} />
+</Demo>

package/src/demo/ProjectStyleExample.astro

@@ -0,0 +1,13 @@
+---
+import DemoConfiguredExample from '@master/internal-site/demo/DemoConfiguredExample.astro'
+import { projectStyleExample, type ProjectStyleName } from '@master/internal-site/demo/project-style-examples.ts'
+
+interface Props {
+  name: ProjectStyleName
+  code?: boolean
+}
+
+const { name, code = true } = Astro.props
+---
+
+<DemoConfiguredExample name={name} {...projectStyleExample(name)} code={code} />

package/src/demo/copy-feedback.ts

@@ -0,0 +1,10 @@
+import { getContext, setContext } from 'svelte'
+
+export type CopyResult = 'success' | 'error' | undefined
+export type CopyFeedback = (message: string, result: CopyResult) => void
+
+const key = Symbol('demo-copy-feedback')
+
+/** A copy group's shared status; buttons inside the same Svelte tree report to it. */
+export const setCopyFeedback = (report: CopyFeedback) => setContext(key, report)
+export const getCopyFeedback = () => getContext<CopyFeedback | undefined>(key)

package/src/demo/demo-waterfall.ts

@@ -0,0 +1,17 @@
+import type { DemoTone } from '@master/internal-site/demo/tone.ts'
+
+export interface DemoWaterfallRow {
+  label: string
+  /** Normalized visual positions, not measured durations. */
+  start: number
+  end: number
+  tone?: DemoTone
+}
+
+export interface DemoWaterfallProps {
+  title: string
+  description: string
+  rows: readonly DemoWaterfallRow[]
+  caption?: string
+  marker?: { label: string; position: number }
+}

package/src/demo/drag-readings.ts

@@ -0,0 +1,20 @@
+/** Observe native events without enabling, canceling or simulating drag behavior. */
+export function demoDragReadings(doc: Document) {
+  const counts = new Map<string, number>()
+  const read = (event: DragEvent) => {
+    const target = (event.target as Element).closest<HTMLElement>('[data-target]')
+    if (!target?.id) return
+    if (event.type === 'dragstart') counts.set(target.id, (counts.get(target.id) ?? 0) + 1)
+    doc.querySelectorAll<HTMLOutputElement>('[data-drag-readout]').forEach(output => {
+      if (output.dataset.dragReadout !== target.id) return
+      const count = counts.get(target.id) ?? 0
+      output.textContent = `${count} ${count === 1 ? 'start' : 'starts'}${event.type === 'dragend' ? ' · ended' : ''}`
+    })
+  }
+  doc.addEventListener('dragstart', read)
+  doc.addEventListener('dragend', read)
+  return () => {
+    doc.removeEventListener('dragstart', read)
+    doc.removeEventListener('dragend', read)
+  }
+}

package/src/demo/foundations/FoundationAxes.astro

@@ -0,0 +1,12 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoItem from '@master/internal-site/demo/DemoItem.svelte'
+import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'
+---
+
+<Demo title="Choose one axis or both" data-foundation="axes">
+  <div class="flex items-end gap-md w-full">
+    <div class="shrink(0) (width:3.5rem)"><DemoLabel>(width:3.5rem) (height:3.5rem)</DemoLabel><DemoItem class="grid (place-content:center) (height:3.5rem) (width:3.5rem) mt-sm font-mono">FN</DemoItem></div>
+    <div class="(flex:1) min-w(0)"><DemoLabel>w-full (height:3.5rem)</DemoLabel><DemoItem tone="violet" class="grid (place-content:center) (height:3.5rem) w-full mt-sm text-sm">Fluid</DemoItem></div>
+  </div>
+</Demo>

package/src/demo/foundations/FoundationColorRoles.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="color-roles" title="One composition, two modes" html={"<article id=\"color-role\" class=\"p-md r-lg b(1) b-solid b-line-divider bg-surface-raised fg-text-body\">\n<h2 class=\"m(0) text-lg font-regular fg-text-strong\">Project updates</h2>\n<p class=\"mt-xs mb-md text-sm fg-text-muted\">Three milestones changed this week.</p>\n<a class=\"fg-text-link fg-text-link-hover:hover underline\" href=\"/guide/colors#choose-a-color-token\" target=\"_top\">Explore color roles</a>\n<p class=\"mt-sm mb(0) font-xs wrap-anywhere\" data-style-readout=\"color-role\" data-style-property=\"color\"></p>\n</article>"} caption="Both documents use identical classes. The active mode supplies the surface, line and text values." />

package/src/demo/foundations/FoundationContainerGrid.astro

@@ -0,0 +1,24 @@
+---
+import DemoContainer from '@master/internal-site/demo/DemoContainer.svelte'
+---
+
+<DemoContainer client:idle={{ timeout: 500 }} title="A summary follows its container" data-foundation="container-grid" caption="Change the ancestor's width. The summary and status share a row from 28rem; the page viewport stays unchanged.">
+  <section class="container-inline">
+    <article class="grid-cols(1) gap-lg p-md b-solid b(1) b-line-divider r-lg bg-surface-raised grid-cols(2)@container(--md)">
+      <div class="min-w(0)">
+        <h3 class="m(0) text-md font-regular fg-text-strong">Release notes</h3>
+        <p class="mb(0) mt-xs text-sm fg-text-muted">Review the changes before publishing.</p>
+      </div>
+      <dl class="grid gap-xs m(0) text-sm">
+        <div>
+          <dt class="fg-text-muted">Status</dt>
+          <dd class="m(0) fg-text-strong">Draft ready</dd>
+        </div>
+        <div>
+          <dt class="fg-text-muted">Next step</dt>
+          <dd class="m(0) fg-text-strong">Editorial review</dd>
+        </div>
+      </dl>
+    </article>
+  </section>
+</DemoContainer>

package/src/demo/foundations/FoundationDialog.astro

@@ -0,0 +1,14 @@
+---
+import FoundationSpecimen from '@master/internal-site/demo/foundations/FoundationSpecimen.astro'
+---
+
+<FoundationSpecimen name="dialog-entrance" title="Motion follows a real action" scene={{ systemButtons: true, sizing: 'viewport', height: 340, css: `@theme {
+  --duration-enter: 180ms;
+  --easing-emphasized: cubic-bezier(.16, 1, .3, 1);
+  --animate-dialog-in: dialog-in var(--duration-enter) var(--easing-emphasized) both;
+ }
+  @keyframes dialog-in {
+    from { translate: 0 0.5rem; opacity: 0; }
+    to { translate: 0; opacity: 1; }
+  }
+`, html: "<article class=\"p-md r-sm b(1) b-solid b-line-divider bg-surface-raised\"><h2 class=\"m(0) text-lg font-regular\">Collection settings</h2><p class=\"mt-xs mb-md fg-text-muted\">Open a native dialog to preview its entrance.</p><button id=\"open\" type=\"button\" class=\"ui-button\">Open details</button></article>\n<dialog id=\"details\" aria-labelledby=\"dialog-title\" aria-describedby=\"dialog-description\" class=\"(width:calc(100%-32px)) max-w-xs m-auto p-md r-lg b(1) b-solid b-line-divider bg-surface-floating fg-text-body shadow-xl animate-dialog-in@media(screen)@motion-safe\">\n<h2 id=\"dialog-title\" class=\"m(0) text-lg font-regular fg-text-strong\">Collection details</h2><p id=\"dialog-description\" class=\"mt-sm mb-md\">This dialog has a finite entrance. Closing it is immediate.</p><form method=\"dialog\"><button class=\"ui-button\" autofocus>Close details</button></form>\n</dialog><script>const dialog = document.getElementById('details'); const openButton = document.getElementById('open'); openButton.addEventListener('click', () => dialog.showModal()); dialog.addEventListener('close', () => openButton.focus());</script>", caption: 'The dialog enters once on opening. Escape or Close details returns focus to its trigger. Reduced motion opens it immediately. Its modal boundary stays inside this preview.' }} />

package/src/demo/foundations/FoundationElevation.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="elevation" title="Quiet separation" html={"<article id=\"shadow-role\" class=\"m-sm p-md r-lg bg-surface-raised shadow-sm\">\n<h2 class=\"m(0) text-lg font-medium fg-text-strong\">Collection notes</h2>\n<p class=\"mt-xs mb(0) fg-text-muted\">A raised surface with a small, consistent shadow.</p>\n<p class=\"mt-sm mb(0) font-xs wrap-anywhere\" data-style-readout=\"shadow-role\" data-style-property=\"box-shadow\"></p>\n</article>"} caption="shadow-sm uses the same offsets across these modes, with different edge and shadow colors." />

package/src/demo/foundations/FoundationElevationState.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="elevation-state" print title="Depth follows interaction" html={"<a class=\"block m-sm p-md r-lg bg-surface-raised fg-text-body shadow-sm shadow-md:hover@media(screen) shadow-md:focus-visible@media(screen) (box-shadow:none)@media(print) (text-decoration:none)\" href=\"/guide/colors#raised-surfaces\" target=\"_top\">\n<strong class=\"block fg-text-strong\">Collection guide ↗</strong>\n<span class=\"block mt-xs fg-text-muted\">Hover or focus this link to lift its surface.</span>\n</a>"} caption="A native link supports pointer and keyboard focus. The focus outline remains visible; printing removes the shadow." />

package/src/demo/foundations/FoundationHue.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="base-hue" title="A fixed hue" html={"<div class=\"grid gap-md\">\n<div class=\"(height:4rem) r-sm bg-yellow\" aria-label=\"Yellow background swatch\" role=\"img\"></div>\n<p class=\"m(0) font-mono font-xs fg-text-muted\">bg-yellow</p>\n<svg class=\"(width:3rem) (height:3rem) fg-yellow\" viewBox=\"0 0 48 48\" role=\"img\" aria-label=\"Yellow diamond\"><path d=\"M24 2 46 24 24 46 2 24Z\" fill=\"currentColor\"/></svg>\n<p class=\"m(0) font-mono font-xs fg-text-muted\">fg-yellow · currentColor</p>\n</div>"} caption="General hue aliases keep the same swatch in both schemes. Use text hue aliases for adaptive readable foregrounds." />

package/src/demo/foundations/FoundationLines.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="lines" title="Visible boundaries" html={"<div class=\"grid gap-md\">\n<section class=\"p-md r-sm b(1) b-solid b-line-divider bg-surface-raised\"><h2 class=\"m(0) text-md font-medium\">Decorative divider</h2><p class=\"mt-xs mb(0) fg-text-muted\">b-line-divider</p></section>\n<section class=\"p-md r-sm b(1) b-solid b-line-control bg-surface-raised\"><h2 class=\"m(0) text-md font-medium\">Control boundary</h2><p class=\"mt-xs mb(0) fg-text-muted\">b-line-control</p></section>\n</div>"} caption="The line role selects a color. Width and style still need an explicit declaration." />

package/src/demo/foundations/FoundationMedia.astro

@@ -0,0 +1,28 @@
+---
+import DemoContainer from '@master/internal-site/demo/DemoContainer.svelte'
+import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'
+import DemoMedia from '@master/internal-site/demo/DemoMedia.svelte'
+import type { ComponentProps } from 'svelte'
+
+const media: ComponentProps<typeof DemoMedia> = {
+  tone: 'blue',
+  class: 'h-auto w-full (aspect-ratio:4/3) r-sm shrink(0)@container(width>=28rem) (width:9rem)@container(width>=28rem)',
+  'aria-label': 'Blue mountain illustration'
+}
+
+/** The query boundary is an ancestor; it never queries its own width. */
+---
+
+<DemoContainer client:idle={{ timeout: 500 }} title="A component follows its container" data-foundation="media" caption="Below 28rem of container width, the media stacks. At 28rem it keeps a 9rem width beside flexible text.">
+    <div class="container-inline">
+      <article class="flex flex-col items-start gap-md p-md flex-row@container(width>=28rem) ui-sheet" data-elevation="1">
+        <DemoMedia {...media} />
+        <div class="(flex:1) min-w(0)">
+          <DemoLabel>Collection / 024</DemoLabel>
+          <h3 class="mb(0) mx(0) mt-xs text-md font-semibold">Field notes</h3>
+          <p class="mb(0) mx(0) mt-xs text-sm fg-text-muted">A small archive of places, textures and quiet details from the trail.</p>
+          <div class="flex flex-wrap gap-sm mt-md"><DemoLabel>12 images</DemoLabel><DemoLabel>Updated today</DemoLabel></div>
+        </div>
+      </article>
+    </div>
+</DemoContainer>

package/src/demo/foundations/FoundationMotion.astro

@@ -0,0 +1,5 @@
+---
+import FoundationSpecimen from '@master/internal-site/demo/foundations/FoundationSpecimen.astro'
+---
+
+<FoundationSpecimen name="finite-motion" title="Two finite entrances" scene={{ motion: true, html: "<div class=\"grid gap-lg\">\n<p class=\"m(0) text-sm fg-text-muted hidden@motion-reduce hidden@media(print)\">Press Play to reveal the two cards.</p>\n<section><p class=\"mb-sm text-sm font-medium\">Fade · 300ms</p><div data-ui=\"surface\"><div id=\"fade\" class=\"p-md r-sm bg-surface-raised b(1) b-solid b-line-divider (animation-name:fade)@media(screen)@motion-safe (animation-duration:var(--duration-slow))@media(screen)@motion-safe (animation-timing-function:var(--easing-smooth))@media(screen)@motion-safe\"><strong class=\"fg-text-strong\">Collection saved</strong><p class=\"mt-xs mb(0) fg-text-muted\">A quiet opacity entrance.</p></div></div><p class=\"mt-xs mb(0)\" data-ui=\"label\"><output data-animation-readout=\"fade\">Paused</output></p></section>\n<section><p class=\"mb-sm text-sm font-medium\">Zoom · 150ms</p><div data-ui=\"surface\"><div id=\"zoom\" class=\"p-md r-sm bg-surface-raised b(1) b-solid b-line-divider (animation-name:zoom)@media(screen)@motion-safe (animation-duration:var(--duration-fast))@media(screen)@motion-safe (animation-timing-function:var(--easing-overshoot))@media(screen)@motion-safe\"><strong class=\"fg-text-strong\">New collection</strong><p class=\"mt-xs mb(0) fg-text-muted\">A brief scale entrance.</p></div></div><p class=\"mt-xs mb(0)\" data-ui=\"label\"><output data-animation-readout=\"zoom\">Paused</output></p></section>\n</div>", caption: 'Both animations run once and start paused. Play and Replay control the native timelines. Reduced motion shows the content immediately without animation.' }} />