@master/internal-site 0.0.0-stage → 0.1.1

package/src/docs-shell/components/DocHeader.svelte

@@ -0,0 +1,93 @@
+<script lang="ts" module>
+  import type { DocSidebarProps } from './DocSidebar.svelte'
+
+  export interface DocHeaderProps {
+    class?: string
+    /** See `Header`: overlays the page and slides away while reading down. */
+    stickable?: boolean
+    transitionAtTop?: boolean
+    /** Chapters the compact menu lists. */
+    documentNavigation?: DocSidebarProps['pageCategories']
+    documentNavigationTitle?: string
+    /** Accepted for section shells; the header always spans the page. */
+    contained?: boolean
+  }
+</script>
+
+<script lang="ts">
+  // `.app-wrapper` sets the homepage sections' column gutters; the homepage loads it through this header.
+  import '../../styles/docs-shell/wrapper.css'
+  import Header from './Header.svelte'
+  import HeaderNav from './HeaderNav.svelte'
+  import LanguageButton from './LanguageButton.svelte'
+  import IconChevronDown from '@tabler/icons-svelte-runes/icons/chevron-down'
+  import IconArrowUpRight from '@tabler/icons-svelte-runes/icons/arrow-up-right'
+  import IconSearch from '@tabler/icons-svelte-runes/icons/search'
+  import DocVersionSelect from './DocVersionSelect.svelte'
+  import Link from './Link.svelte'
+  import DocMenuButton from './DocMenuButton.svelte'
+  import SearchButton from './SearchButton.svelte'
+  import isDateWithinSevenDays from '../utils/is-date-within-seven-days'
+  import app from 'virtual:master-site/app'
+  import { getSite } from '../site'
+
+  let { class: className, stickable, transitionAtTop, documentNavigation, documentNavigationTitle }: DocHeaderProps = $props()
+  const { t, locale, pathname, i18n } = getSite()
+  const tw = locale === 'tw'
+  const home = pathname === (tw ? '/tw' : '/')
+  const headerCommunityNavs = app.header?.communityNavs ?? app.communityNavs ?? []
+  const showLanguage = i18n.locales.length > 1
+  const version = import.meta.env.PUBLIC_VERSION ? `v${import.meta.env.PUBLIC_VERSION}` : ''
+</script>
+
+<Header class={className} {stickable} {transitionAtTop}>
+  <DocMenuButton class="ui-header-menu" {documentNavigation} {documentNavigationTitle} />
+  <Link href="/" class="ui-header-brand" aria-label={`${app.name} ${tw ? '首頁' : 'home'}`} oncontextmenu={(event: MouseEvent) => {
+    event.preventDefault()
+    location.assign(app.brandURL)
+  }}>
+    <app.Logotype style="height: 20px; width: auto" aria-hidden="true" />
+  </Link>
+  {#if app.versions.length}
+    <label class="ui-version">
+      {version}
+      <DocVersionSelect aria-label={t('Version')} />
+      <IconChevronDown aria-hidden="true" stroke={1.5} />
+    </label>
+  {:else if version}
+    <span class="ui-version">{version}</span>
+  {/if}
+  <nav class="ui-header-nav" aria-label={tw ? '主要導覽' : 'Main navigation'}>
+    {#each app.navs as { Icon: _Icon, fullName: _fullName, ...eachLink } (eachLink.name)}<HeaderNav {...eachLink}>
+      {t(eachLink.name)}
+      {#if eachLink.date && isDateWithinSevenDays(eachLink.date)}<small>{t('New')}</small>{/if}
+    </HeaderNav>{/each}
+  </nav>
+  <div class="ui-header-end" data-home-controls={app.header?.searchOnHome ? 'full' : undefined}>
+    <!-- Search leads the end group as a quiet pill: the glass and its shortcut. Homepages may opt into the same desktop search control. -->
+    <SearchButton class="ui-header-search" data-compact={home && !app.header?.searchOnHome ? '' : undefined}>
+      <IconSearch size={16} stroke={1.5} aria-hidden="true" />
+      <kbd class="ui-kbd" aria-hidden="true">⌘K</kbd>
+    </SearchButton>
+    {#each headerCommunityNavs as { Icon, disabled, fullName, ...eachLink } (eachLink.name)}
+      <Link
+        {...eachLink}
+        aria-label={fullName || eachLink.name}
+        class="ui-button"
+        data-variant="quiet"
+        data-shape="icon"
+        data-size="sm"
+        data-disabled={disabled || undefined}
+        {disabled}
+      >
+        {#if Icon}<Icon size={18} stroke={1.5} aria-hidden="true" />{/if}
+        {#if eachLink.href?.startsWith('http')}<IconArrowUpRight class="ui-header-external" size={10} stroke={1.5} aria-hidden="true" />{/if}
+        <span class="ui-tooltip" data-side="bottom" aria-hidden="true">{fullName || eachLink.name}</span>
+      </Link>
+    {/each}
+    {#if showLanguage}
+      {#if headerCommunityNavs.length}<span class="ui-header-divider" aria-hidden="true"></span>{/if}
+      <LanguageButton />
+    {/if}
+  </div>
+</Header>

package/src/docs-shell/components/DocHeading.astro

@@ -0,0 +1,28 @@
+---
+import '../../styles/docs-shell/prose.css'
+import resolveHeading from '../utils/resolve-heading'
+
+interface Props {
+  tagName: 'h2' | 'h3'
+  id?: string
+  [key: string]: any
+}
+
+const entities: Record<string, string> = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'", '&#x27;': "'" }
+const decode = (html: string) => html.replace(/&(?:amp|lt|gt|quot|#39|#x27);/g, (entity) => entities[entity])
+
+/** A section heading with its `ui-anchor`. Clicking a heading copies its link; see `docs-shell/scripts/document`. */
+const { tagName, id, class: className, ...props } = Astro.props
+const Element = tagName === 'h2' ? 'h2' : 'h3'
+const html = await Astro.slots.render('default')
+// Plain-text headings may end with ` [sr-only]`; headings with inline code or links render as written.
+const plain = !html.includes('<')
+const text = decode(html.replace(/<[^>]*>/g, '')).trim()
+const heading = resolveHeading(plain ? decode(html) : undefined, id)
+const title = typeof heading.title === 'string' ? heading.title : text
+---
+
+<Element {...props} id={heading.id ?? id} class:list={[className, heading.className]} title={title || undefined} data-doc-heading="">
+  <a class="ui-anchor" href={'#' + (heading.id ?? id)} aria-label={`Link to section: ${title}`}>#</a>
+  <Fragment set:html={plain ? html.replace(' [sr-only]', '') : html} />
+</Element>

package/src/docs-shell/components/DocMain.astro

@@ -0,0 +1,19 @@
+---
+import '../../styles/docs-shell/docs.css'
+import type { HTMLAttributes } from 'astro/types'
+import Footer, { type FooterProps } from './Footer.svelte'
+
+interface Props extends HTMLAttributes<'main'> {
+  footerProps?: FooterProps
+}
+
+/** The main column: the article and its contents rail, then the footer. */
+const { footerProps, class: className, ...props } = Astro.props
+---
+
+<main {...props} class:list={['ui-docs-main', className]}>
+  <div class="ui-docs-body">
+    <slot />
+  </div>
+  {footerProps && <Footer client:load {...footerProps} />}
+</main>

package/src/docs-shell/components/DocMenuButton.svelte

@@ -0,0 +1,96 @@
+<script lang="ts" module>
+  import type { Attachment } from 'svelte/attachments'
+
+  /** The sheet lives at the end of the body, outside the header that opens it. */
+  const portal: Attachment<HTMLElement> = (node) => {
+    document.body.append(node)
+    return () => node.remove()
+  }
+</script>
+
+<script lang="ts">
+  import '../../styles/docs-shell/menu.css'
+  import clsx from 'clsx'
+  import Link from './Link.svelte'
+  import DocSidebar, { type DocSidebarProps } from './DocSidebar.svelte'
+  import SearchButton from './SearchButton.svelte'
+  import IconArrowUpRight from '@tabler/icons-svelte-runes/icons/arrow-up-right'
+  import IconMenu2 from '@tabler/icons-svelte-runes/icons/menu-2'
+  import IconX from '@tabler/icons-svelte-runes/icons/x'
+  import ThemeSelect from './ThemeSelect.svelte'
+  import DocVersionSelect from './DocVersionSelect.svelte'
+  import LanguageSelect from './LanguageSelect.svelte'
+  import app from 'virtual:master-site/app'
+  import { getSite } from '../site'
+
+  interface Props {
+    class?: string
+    documentNavigation?: DocSidebarProps['pageCategories']
+    documentNavigationTitle?: string
+  }
+
+  /** The compact header's menu: site sections, the section's chapters, community links and preferences in one sheet. */
+  let { class: className, documentNavigation, documentNavigationTitle }: Props = $props()
+  let opened = $state(false)
+  const id = $props.id()
+  let dialog = $state<HTMLDialogElement>()
+  let trigger = $state<HTMLButtonElement>()
+  const { t, locale, i18n } = getSite()
+  const tw = locale === 'tw'
+
+  function close() {
+    dialog?.close()
+    opened = false
+    trigger?.focus({ preventScroll: true })
+  }
+
+  $effect(() => {
+    if (!opened) return
+    const element = dialog
+    if (element && !element.open) element.showModal()
+    const wide = matchMedia('(width >= 64rem)')
+    const resize = () => { if (wide.matches) close() }
+    wide.addEventListener('change', resize)
+    return () => wide.removeEventListener('change', resize)
+  })
+</script>
+
+<button bind:this={trigger} type="button" class={clsx('ui-button', className)} data-variant="quiet" data-shape="icon"
+  aria-label={t('Menu')} aria-expanded={opened} aria-haspopup="dialog" aria-controls={opened ? id : undefined}
+  onclick={() => { opened = !opened }}>
+  <IconMenu2 size={20} stroke={1.5} aria-hidden="true" />
+</button>
+{#if opened}
+  <dialog bind:this={dialog} {@attach portal} {id} class="ui-dialog" data-variant="sheet" aria-labelledby={`${id}-title`} oncancel={event => { event.preventDefault(); close() }}>
+    <div class="ui-dialog-bar">
+      <button type="button" class="ui-button" data-variant="quiet" data-shape="icon" onclick={close} aria-label={tw ? '關閉選單' : 'Close menu'}><IconX size={20} stroke={1.5} aria-hidden="true" /></button>
+      <Link href="/" class="ui-header-brand" onclick={close} aria-label={`${app.name} ${tw ? '首頁' : 'home'}`}><app.Logotype style="height: 20px; width: auto" aria-hidden="true" /></Link>
+    </div>
+    <div class="ui-dialog-body">
+      <h2 class="sr-only" id={`${id}-title`}>{tw ? '網站導覽' : 'Navigation'}</h2>
+      <SearchButton class="ui-search-trigger" />
+      <nav class="ui-nav-group" aria-label={tw ? '主要導覽' : 'Main navigation'}>
+        {#each app.navs as { Icon, disabled, fullName, ...link } (link.name)}<Link class="ui-nav-link" current="true" ambiguous {...link} {disabled} onclick={close}>
+          {#if Icon}<Icon size={18} stroke={1.5} aria-hidden="true" />{/if}{t(fullName || link.name)}
+          {#if link.href?.startsWith('http')}<IconArrowUpRight size={14} stroke={1.5} aria-hidden="true" />{/if}
+        </Link>{/each}
+      </nav>
+      {#if documentNavigation?.length}<details class="ui-disclosure" data-variant="rule" open>
+        <summary>{t(documentNavigationTitle || 'Documentation')}<span class="ui-disclosure-meta">{tw ? '文件章節' : 'Chapters'}</span></summary>
+        <DocSidebar embedded includeNestedPages pageCategories={documentNavigation} onNavigate={close} />
+      </details>{/if}
+      {#if app.communityNavs?.length}<nav class="ui-nav-group" aria-labelledby={`${id}-community`}>
+        <h4 id={`${id}-community`}>{t('Community')}</h4>
+        {#each app.communityNavs as { Icon, disabled, fullName, ...link } (link.name)}<Link class="ui-nav-link" {...link} {disabled} onclick={close}>
+          {#if Icon}<Icon size={18} stroke={1.5} aria-hidden="true" />{/if}{t(fullName || link.name)}<IconArrowUpRight size={14} stroke={1.5} aria-hidden="true" />
+        </Link>{/each}
+      </nav>{/if}
+      <section class="ui-dialog-fields" aria-labelledby={`${id}-system`}>
+        <h4 id={`${id}-system`}>{t('System')}</h4>
+        {#if app.versions.length > 0}<label class="ui-field">{t('Version')}<DocVersionSelect aria-label={t('Version')} data-variant={undefined} /></label>{/if}
+        {#if i18n.locales.length > 1}<label class="ui-field">{t('Language')}<LanguageSelect aria-label={t('Language')} data-variant={undefined} /></label>{/if}
+        <label class="ui-field">{t('Theme')}<ThemeSelect aria-label={t('Theme')} data-variant={undefined} /></label>
+      </section>
+    </div>
+  </dialog>
+{/if}

package/src/docs-shell/components/DocSidebar.svelte

@@ -0,0 +1,62 @@
+<script lang="ts" module>
+  import type { DefinedMetadata } from '../types/Metadata'
+
+  export interface DocSidebarProps {
+    pageCategories: {
+      name: string,
+      pages: (Pick<DefinedMetadata, 'pathname' | 'title'> & Partial<DefinedMetadata>)[]
+    }[],
+    includeNestedPages?: boolean
+    /** Inside the compact menu: the groups only, without the documentation landmark. */
+    embedded?: boolean
+    onNavigate?: () => void
+  }
+</script>
+
+<script lang="ts">
+  import Link from './Link.svelte'
+  import { getSite } from '../site'
+
+  /** The documentation sidebar: one navigation group per category; the page being read inks a bar on the guide. Search lives in the header. */
+  let { pageCategories, includeNestedPages = false, embedded = false, onNavigate }: DocSidebarProps = $props()
+  const { t, locale } = getSite()
+  const tw = locale === 'tw'
+  const groups = $derived(pageCategories
+    .filter((eachPageCategory: any) => eachPageCategory.name !== 'Overview')
+    .map((eachPageCategory: any) => ({
+      name: eachPageCategory.name,
+      pages: eachPageCategory.pages.filter((metadata: any) => includeNestedPages || metadata.pathname.split('/').length === 3)
+    }))
+    .filter(({ pages }) => pages.length !== 0))
+</script>
+
+{#snippet sidebarGroups()}
+  {#each groups as eachPageCategory (eachPageCategory.name)}
+    {@const name = t(eachPageCategory.name)}
+    <nav class="ui-nav-group" aria-label={name}>
+      <h4>{name}</h4>
+      {#each eachPageCategory.pages as metadata (metadata.pathname)}
+        {@const translatedTitle = t(metadata.other?.subject || metadata.title.absolute || metadata.title)}
+        <Link class="ui-nav-link"
+          current="true"
+          ambiguous
+          href={metadata.pathname}
+          scrollIntoView
+          disabled={metadata.disabled}
+          unfinished={metadata.unfinished}
+          onclick={onNavigate}>
+          {t(translatedTitle)}
+          {#if metadata.type === 'entity' && locale !== 'en' && translatedTitle !== metadata.title}<small translate="no">{metadata.title}</small>{/if}
+        </Link>
+      {/each}
+    </nav>
+  {/each}
+{/snippet}
+
+{#if embedded}
+  <div class="ui-sidebar">{@render sidebarGroups()}</div>
+{:else}
+  <aside id="sidebar" aria-label={tw ? '文件導覽' : 'Documentation navigation'} class="ui-sidebar">
+    {@render sidebarGroups()}
+  </aside>
+{/if}

package/src/docs-shell/components/DocVersionSelect.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import type { HTMLSelectAttributes } from 'svelte/elements'
+  import clsx from 'clsx'
+  import app from 'virtual:master-site/app'
+
+  type Props = Omit<HTMLSelectAttributes, 'value' | 'onchange'>
+
+  /** A native select; by default invisible over its positioned label (`ui-select[data-variant="overlay"]`), which shows the value. */
+  let { class: className, ...props }: Props = $props()
+  const currentURL = import.meta.env.PUBLIC_URL
+
+  function navigate(event: Event & { currentTarget: HTMLSelectElement }) {
+    window.location.href = event.currentTarget.value
+  }
+</script>
+
+<select name="version" value={currentURL}
+  data-variant="overlay" {...props} class={clsx('ui-select', className)}
+  onchange={navigate}>
+  <option value={currentURL}>v{import.meta.env.PUBLIC_VERSION}</option>
+  {#each app.versions as { name, href } (href)}<option value={href}>{name}</option>{/each}
+</select>

package/src/docs-shell/components/DocWrapper.astro

@@ -0,0 +1,11 @@
+---
+import '../../styles/docs-shell/docs.css'
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'div'>
+
+/** The documentation frame under the header: the sidebar, then the main column. */
+const { class: className, ...props } = Astro.props
+---
+
+<div {...props} class:list={['ui-docs', className]}><slot /></div>

package/src/docs-shell/components/DocumentAPIIndex.astro

@@ -0,0 +1,24 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import Link from '@master/internal-site/components/Link.svelte'
+import DocumentIdentifier from '@master/internal-site/components/DocumentIdentifier.astro'
+import type { DocumentAPIEntry } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentAPIEntry } from '@master/internal-site/components/document-types.ts'
+
+interface Props {
+  label: string
+  entries: readonly DocumentAPIEntry[]
+  compact?: boolean
+}
+
+/** Static navigation for exact identifiers; long names wrap without changing copy text. */
+const { label, entries, compact = false } = Astro.props
+---
+
+<nav class="ui-index" data-density={compact ? 'compact' : undefined} aria-label={label}>
+  {entries.map(entry => <Link href={entry.href}>
+    <b><code><DocumentIdentifier text={entry.name} /></code></b>
+    <span>{entry.description}</span>
+  </Link>)}
+</nav>

package/src/docs-shell/components/DocumentChoices.astro

@@ -0,0 +1,24 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import Link from '@master/internal-site/components/Link.svelte'
+import RenderNode from '@master/internal-site/components/RenderNode.astro'
+import type { DocumentChoice } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentChoice } from '@master/internal-site/components/document-types.ts'
+
+interface Props {
+  label: string
+  entries: readonly DocumentChoice[]
+}
+
+/** A compact reading-column index. Navigation stays outside measured demo layouts. */
+const { label, entries } = Astro.props
+---
+
+<nav aria-label={label} class="ui-index">
+  {entries.map(entry => <Link href={entry.href}>
+    {entry.icon != null && <RenderNode node={entry.icon} />}
+    <b>{entry.title}</b>
+    <span>{entry.description}</span>
+  </Link>)}
+</nav>

package/src/docs-shell/components/DocumentCodeExample.astro

@@ -0,0 +1,20 @@
+---
+import Code from '@master/internal-site/components/Code.astro'
+import DocumentCodeExampleView from '@master/internal-site/components/DocumentCodeExampleView.astro'
+import type { DocumentCodeExampleProps } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentCodeExampleProps } from '@master/internal-site/components/document-types.ts'
+
+type Props = DocumentCodeExampleProps
+
+/** Labels name the two sides of a pair; a source alone, or above its Generated CSS disclosure, needs none. */
+const { language, resultLanguage = language, source, result, sourceLabel, resultLabel = 'Result', ...props } = Astro.props
+const pair = result !== undefined && props.resultKind !== 'generated-css'
+---
+
+<DocumentCodeExampleView {...props}>
+  <Code slot="sourceCode" lang={language} name={sourceLabel ?? (pair ? 'Source' : undefined)} code={source} />
+  {result !== undefined && (props.resultKind === 'generated-css'
+    ? <Code slot="resultCode" lang={resultLanguage} code={result} />
+    : <Code slot="resultCode" lang={resultLanguage} name={resultLabel} code={result} />)}
+</DocumentCodeExampleView>

package/src/docs-shell/components/DocumentCodeExampleView.astro

@@ -0,0 +1,35 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import IconAlertTriangle from '@tabler/icons-svelte-runes/icons/alert-triangle'
+import IconCircleX from '@tabler/icons-svelte-runes/icons/circle-x'
+import RenderNode from '@master/internal-site/components/RenderNode.astro'
+import GeneratedCSS from '@master/internal-site/components/GeneratedCSS.astro'
+import type { DocumentCodeExampleViewProps } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentCodeExampleViewProps } from '@master/internal-site/components/document-types.ts'
+
+type Props = DocumentCodeExampleViewProps
+
+/**
+ * Static, verified source/output pair in one tray. It does not simulate an editor or execute code.
+ * The code blocks arrive as the `sourceCode`/`resultCode` props, or as slots of the same names.
+ */
+const { title, sourceCode, resultCode, resultKind, diagnostic } = Astro.props
+const DiagnosticIcon = diagnostic?.severity === 'Error' ? IconCircleX : IconAlertTriangle
+const hasResult = resultCode != null || Astro.slots.has('resultCode')
+---
+
+<figure class="ui-tray" aria-label={title}>
+  <figcaption class="ui-tray-head"><p class="ui-tray-title">{title}</p></figcaption>
+  {sourceCode != null ? <RenderNode node={sourceCode} /> : <slot name="sourceCode" />}
+  {diagnostic && <div class="ui-callout" data-tone={diagnostic.severity === 'Error' ? 'danger' : 'warning'}>
+    <DiagnosticIcon stroke={1.6} aria-hidden="true" />
+    <div>
+      <p><b>{diagnostic.severity}</b> · <code>{diagnostic.rule}</code></p>
+      <p>{diagnostic.message}</p>
+    </div>
+  </div>}
+  {hasResult && (resultKind === 'generated-css'
+    ? <GeneratedCSS>{resultCode != null ? <RenderNode node={resultCode} /> : <slot name="resultCode" />}</GeneratedCSS>
+    : resultCode != null ? <RenderNode node={resultCode} /> : <slot name="resultCode" />)}
+</figure>

package/src/docs-shell/components/DocumentCodeTable.astro

@@ -0,0 +1,19 @@
+---
+import '@master/internal-site/styles/system/data.css'
+
+interface Props {
+  label?: string
+  rows: { syntax: string, css: string }[]
+}
+
+/** Preserve short syntax tokens while allowing native CSS to wrap at its spaces. */
+const { label = 'Syntax', rows } = Astro.props
+---
+
+{/* The table's narrow overflow region must be focusable for native keyboard scrolling. */}
+<div class="ui-table" data-variant="lookup" role="region" aria-label={`${label} and CSS`} tabindex="0"><table>
+  <thead><tr><th scope="col">{label}</th><th scope="col">CSS</th></tr></thead>
+  <tbody>{rows.map(({ syntax, css }) => <tr>
+    <th scope="row"><code>{syntax}</code></th><td><code>{css}</code></td>
+  </tr>)}</tbody>
+</table></div>

package/src/docs-shell/components/DocumentComparison.astro

@@ -0,0 +1,7 @@
+---
+import '@master/internal-site/styles/document-comparison.css'
+
+/** Opt-in wrapper for short, two-column Markdown comparisons: both columns stay visible and wrap. */
+---
+
+<div class="document-comparison"><slot /></div>

package/src/docs-shell/components/DocumentCopyButton.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import IconCheck from '@tabler/icons-svelte-runes/icons/check'
+  import IconCopy from '@tabler/icons-svelte-runes/icons/copy'
+
+  /** Content stays server-rendered; only clipboard feedback needs client state. */
+  let { text, label }: { text: string, label: string } = $props()
+
+  let result = $state<'success' | 'error'>()
+  // Disabled in the server HTML until hydration can handle the click.
+  let ready = $state(false)
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  onMount(() => {
+    ready = true
+    return () => clearTimeout(timer)
+  })
+
+  async function copy() {
+    clearTimeout(timer)
+    try {
+      await navigator.clipboard.writeText(text)
+      result = 'success'
+      // Success feedback clears itself; an error stays until the next attempt.
+      timer = setTimeout(() => result = undefined, 2000)
+    } catch {
+      result = 'error'
+    }
+  }
+</script>
+
+<span class="ui-copy">
+  <button type="button" class="ui-button" data-size="sm" disabled={!ready} aria-label={`Copy ${label}`} onclick={copy}>
+    {#if result === 'success'}<IconCheck stroke={1.8} aria-hidden="true" />{:else}<IconCopy stroke={1.8} aria-hidden="true" />{/if}
+    Copy
+  </button>
+  <span class="ui-copy-status" role="status" data-result={result}>
+    {#if result === 'success'}Copied<span class="sr-only"> {label}</span>{:else if result === 'error'}Clipboard unavailable. Select the text to copy it.{/if}
+  </span>
+</span>

package/src/docs-shell/components/DocumentDeclaration.astro

@@ -0,0 +1,17 @@
+---
+import Code from '@master/internal-site/components/Code.astro'
+import { slotText } from '@master/internal-site/utils/slot-text'
+import DocumentDeclarationView from '@master/internal-site/components/DocumentDeclarationView.astro'
+
+interface Props {
+  label?: string
+  /** The declaration; text children work too, as in `<DocumentDeclaration>{declaration}</DocumentDeclaration>`. */
+  code?: string
+}
+
+const source = Astro.props.code ?? await slotText(Astro.slots) ?? ''
+---
+
+<DocumentDeclarationView source={source}>
+  <Code lang="typescript" beautify={false} dedent={false} code={source} />
+</DocumentDeclarationView>

package/src/docs-shell/components/DocumentDeclarationView.astro

@@ -0,0 +1,12 @@
+---
+import DocumentDisclosure from '@master/internal-site/components/DocumentDisclosure.astro'
+
+interface Props {
+  source: string
+}
+
+/** Full TypeScript remains server rendered and copyable, including long contracts. */
+const lines = Astro.props.source.split('\n').length
+---
+
+{lines > 40 ? <DocumentDisclosure title={`Complete declaration · ${lines} lines`}><slot /></DocumentDisclosure> : <slot />}

package/src/docs-shell/components/DocumentDisclosure.astro

@@ -0,0 +1,14 @@
+---
+interface Props {
+  title: string
+  open?: boolean
+}
+
+/** A native disclosure remains usable before JavaScript loads; its body reads like the article. */
+const { title, open = false } = Astro.props
+---
+
+<details class="ui-disclosure" data-variant="rule" open={open}>
+  <summary>{title}</summary>
+  <div class="ui-disclosure-body ui-prose"><slot /></div>
+</details>

package/src/docs-shell/components/DocumentFileTree.astro

@@ -0,0 +1,34 @@
+---
+import IconFile from '@tabler/icons-svelte-runes/icons/file'
+import IconFolder from '@tabler/icons-svelte-runes/icons/folder'
+import type { DocumentFileEntry, DocumentFileTreeProps } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentFileEntry, DocumentFileTreeProps } from '@master/internal-site/components/document-types.ts'
+
+type Props = DocumentFileTreeProps | {
+  /** Nested levels render through this component again with only their entries. */
+  entries: readonly DocumentFileEntry[]
+  nested: true
+}
+
+/** Read-only nested lists; no tree widget or keyboard interaction is implied. */
+const props = Astro.props
+const Entries = Astro.self
+---
+
+{'nested' in props
+  ? <ul role="list">{/* Preserve WebKit list semantics when list-style is none. */}
+    {props.entries.map(entry => <li>
+      <div>
+        {entry.children ? <IconFolder stroke={1.6} aria-hidden="true" /> : <IconFile stroke={1.6} aria-hidden="true" />}
+        <b>{entry.name}{entry.children ? '/' : ''}</b>
+        {entry.description && <span>{entry.description}</span>}
+      </div>
+      {!!entry.children?.length && <Entries entries={entry.children} nested />}
+    </li>)}
+  </ul>
+  : <figure class="ui-tray" aria-label={props.title}>
+    <figcaption class="ui-tray-head"><p class="ui-tray-title">{props.title}</p></figcaption>
+    <div class="ui-tree"><Entries entries={props.entries} nested /></div>
+    {props.caption && <p class="ui-tray-caption">{props.caption}</p>}
+  </figure>}

package/src/docs-shell/components/DocumentFlow.astro

@@ -0,0 +1,27 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import type { DocumentFlowProps } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentFlowStep, DocumentFlowProps } from '@master/internal-site/components/document-types.ts'
+
+type Props = DocumentFlowProps
+
+/** A static, ordered process; no timeline duration or interactive state is implied. */
+const { title, steps, caption } = Astro.props
+---
+
+<figure class="ui-tray" aria-label={title}>
+  <figcaption class="ui-tray-head"><p class="ui-tray-title">{title}</p></figcaption>
+  <div class="ui-stage" data-padding="sm" data-align="start">
+    {/* Preserve WebKit list semantics when list-style is none. */}
+    <ol class="ui-steps" role="list">
+      {steps.map(step => <li>
+        <div>
+          <h4>{step.title}</h4>
+          <p>{step.description}</p>
+        </div>
+      </li>)}
+    </ol>
+  </div>
+  {caption && <p class="ui-tray-caption">{caption}</p>}
+</figure>

package/src/docs-shell/components/DocumentIdentifier.astro

@@ -0,0 +1,14 @@
+---
+import { slotText } from '@master/internal-site/utils/slot-text'
+
+interface Props {
+  /** The identifier; text children work too, as in `<DocumentIdentifier>{name}</DocumentIdentifier>`. */
+  text?: string
+}
+
+/** Prefer identifier boundaries without inserting characters into copied text. */
+const text = Astro.props.text ?? await slotText(Astro.slots) ?? ''
+const parts = text.split(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|(?<=[/_-])/)
+---
+
+{parts.map((part, index) => <Fragment>{index > 0 && <wbr />}{part}</Fragment>)}