@master/internal-site 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,46 @@
+---
+import '@master/internal-site/styles/documentation-illustration.css'
+import IconArrowsMaximize from '@tabler/icons-svelte-runes/icons/arrows-maximize'
+import Image from '@master/internal-site/components/Image.svelte'
+import type { IllustrationImages } from '../types/IllustrationImages'
+
+export type { IllustrationImages } from '../types/IllustrationImages'
+
+interface Props {
+  title: string
+  alt: string
+  images: IllustrationImages
+  caption: string
+  fullSize?: boolean
+}
+
+/** A static figure with one accessible image and an independent text description. */
+const { title, alt, images, caption, fullSize = false } = Astro.props
+---
+
+<figure class="ui-tray" aria-label={title} data-illustration-expandable={fullSize || undefined}>
+  <figcaption class="ui-tray-head">
+    <p class="ui-tray-title">{title}</p>
+    {fullSize && (['light', 'dark'] as const).map(scheme => <a
+      class="document-illustration-expand ui-button"
+      data-variant="quiet" data-shape="icon" data-size="sm" data-scheme={scheme}
+      href={images[scheme].src} target="_blank" rel="noopener noreferrer"
+      aria-label={`View full-size illustration: ${title} (opens in a new tab)`}
+      title="View full-size illustration (opens in a new tab)"
+    ><IconArrowsMaximize aria-hidden="true" /></a>)}
+  </figcaption>
+  <div class="document-illustration" role="img" aria-label={alt}>
+    {(['light', 'dark'] as const).map(scheme => <Image
+      src={images[scheme]}
+      data-scheme={scheme}
+      sizes="(max-width: 834px) 100vw, 900px"
+      alt=""
+      aria-hidden="true"
+    />)}
+  </div>
+  <p class="ui-tray-caption">{caption}</p>
+  <details class="ui-disclosure" data-variant="text-description">
+    <summary>Text description</summary>
+    <div class="ui-disclosure-body ui-tray-caption"><slot /></div>
+  </details>
+</figure>

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

@@ -0,0 +1,22 @@
+---
+import '@master/internal-site/styles/system/data.css'
+
+interface Props {
+  keys: string[]
+  previewCount?: number
+}
+
+/** Keep complete utility keys together when a consumer list wraps. */
+const { keys, previewCount = keys.length } = Astro.props
+const lists = [keys.slice(0, previewCount), keys.slice(previewCount)]
+---
+
+<ul aria-label="Utility keys">
+  {lists[0].map(key => <li><code>{key}</code></li>)}
+</ul>
+{keys.length > previewCount && <details class="ui-disclosure">
+  <summary>Show {keys.length - previewCount} more keys</summary>
+  <ul aria-label="Utility keys">
+    {lists[1].map(key => <li><code>{key}</code></li>)}
+  </ul>
+</details>}

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

@@ -0,0 +1,20 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import DocumentKeyList from '@master/internal-site/components/DocumentKeyList.astro'
+
+interface Props {
+  rows: { namespace: string, consumers: string[] }[]
+}
+
+/** Native disclosure keeps large registry rows readable; every key remains in the HTML. */
+const { 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="Namespace consumers" tabindex="0"><table>
+  <thead><tr><th scope="col">Namespace</th><th scope="col">Consumers</th></tr></thead>
+  <tbody>{rows.map(({ namespace, consumers }) => <tr>
+    <th scope="row"><code>{namespace}-*</code></th>
+    <td><DocumentKeyList keys={consumers} previewCount={6} /></td>
+  </tr>)}</tbody>
+</table></div>

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

@@ -0,0 +1,15 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import DocumentIdentifier from '@master/internal-site/components/DocumentIdentifier.astro'
+
+interface Props {
+  name: string
+}
+
+const { name } = Astro.props
+---
+
+<div>
+  <dt><DocumentIdentifier text={name} /></dt>
+  <dd><slot /></dd>
+</div>

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

@@ -0,0 +1,11 @@
+---
+import '@master/internal-site/styles/system/data.css'
+
+interface Props {
+  label: string
+}
+
+const { label } = Astro.props
+---
+
+<dl class="ui-params" aria-label={label}><slot /></dl>

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

@@ -0,0 +1,23 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import RenderNode from '@master/internal-site/components/RenderNode.astro'
+import DocumentOptionEntry from '@master/internal-site/components/DocumentOptionEntry.astro'
+import DocumentOptionList from '@master/internal-site/components/DocumentOptionList.astro'
+import type { DocumentOption } from '@master/internal-site/components/document-types.ts'
+
+
+interface Props {
+  label: string
+  options: readonly DocumentOption[]
+}
+
+/** Names keep their own column; defaults and prose stay readable on mobile. */
+const { label, options } = Astro.props
+---
+
+<DocumentOptionList label={label}>
+  {options.map(option => <DocumentOptionEntry name={option.name}>
+    {option.defaultValue !== undefined && <small>Default <code>{option.defaultValue}</code></small>}
+    <p><RenderNode node={option.description} /></p>
+  </DocumentOptionEntry>)}
+</DocumentOptionList>

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

@@ -0,0 +1,30 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import '@master/internal-site/styles/system/specimens.css'
+import RenderNode from '@master/internal-site/components/RenderNode.astro'
+import DocumentIdentifier from '@master/internal-site/components/DocumentIdentifier.astro'
+import type { DocumentParameter } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentParameter } from '@master/internal-site/components/document-types.ts'
+
+interface Props {
+  label: string
+  parameters: readonly DocumentParameter[]
+}
+
+/** Name, type and requirement read as one term; descriptions use the remaining width. */
+const { label, parameters } = Astro.props
+---
+
+<dl class="ui-params" aria-label={label}>
+  {parameters.map(parameter => <div>
+    <dt>
+      <span><DocumentIdentifier text={parameter.name} /></span>
+      <small>{parameter.type}</small>
+      {parameter.requirement && (/^required$/i.test(parameter.requirement)
+        ? <span class="ui-badge" data-size="sm">{parameter.requirement}</span>
+        : <small>{parameter.requirement}</small>)}
+    </dt>
+    <dd><p><RenderNode node={parameter.description} /></p></dd>
+  </div>)}
+</dl>

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

@@ -0,0 +1,16 @@
+---
+import DocumentCopyButton from '@master/internal-site/components/DocumentCopyButton.svelte'
+import type { DocumentPromptProps } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentPromptProps } from '@master/internal-site/components/document-types.ts'
+
+type Props = DocumentPromptProps
+
+/** Readable prose preserves its exact clipboard text while wrapping within the document. */
+const { title, text } = Astro.props
+---
+
+<figure class="ui-prompt" aria-label={title}>
+  <figcaption class="ui-code-bar"><span class="ui-code-file">{title}</span><DocumentCopyButton client:idle={{ timeout: 500 }} text={text} label={title} /></figcaption>
+  <p class="ui-prompt-body">{text}</p>
+</figure>

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

@@ -0,0 +1,25 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import type { DocumentValueRow } from '@master/internal-site/components/document-types.ts'
+
+export type { DocumentValueRow } from '@master/internal-site/components/document-types.ts'
+
+interface Props {
+  rows: DocumentValueRow[]
+  headingLevel?: 3 | 4
+}
+
+/** Compact, selectable reference facts. IDs belong to the visible row headings. */
+const { rows, headingLevel = 3 } = Astro.props
+const Heading = `h${headingLevel}` as const
+---
+
+<dl class="ui-params">
+  {rows.map(row => <div>
+    <dt>
+      <Heading id={row.id}><a href={`#${row.id}`}>{row.title}</a></Heading>
+      {row.identifier && <small>{row.identifier}</small>}
+    </dt>
+    <dd>{row.values.map(({ label, value }) => <p><small>{label}</small> <code>{value}</code></p>)}</dd>
+  </div>)}
+</dl>

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

@@ -0,0 +1,144 @@
+<script module lang="ts">
+  export type { DocumentationIndexEntry, DocumentationIndexSection } from '@master/internal-site/components/document-types.ts'
+</script>
+
+<script lang="ts">
+  import '@master/internal-site/styles/documentation-index.css'
+  import Link from '@master/internal-site/components/Link.svelte'
+  import { getSite } from '@master/internal-site/site'
+  import type { DocumentationIndexEntry, DocumentationIndexSection } from '@master/internal-site/components/document-types.ts'
+
+  interface SectionLink {
+    title: string
+    description: string
+    href: string
+  }
+
+  let { name, sections, related, showDescriptions = false, idPrefix }: {
+    name: 'guide' | 'reference'
+    sections: DocumentationIndexSection[]
+    related: SectionLink
+    showDescriptions?: boolean
+    /** Scope anchor IDs when multiple catalogs are shown in one review. Omit on published indexes. */
+    idPrefix?: string
+  } = $props()
+
+  const { locale, t } = getSite()
+  const tw = locale === 'tw'
+  let alphabetical = $state(false)
+  const entries = $derived(sections.flatMap(section => section.groups.flatMap(group => group.entries)))
+  const letters = $derived(Map.groupBy([...entries].sort((a, b) => a.title.localeCompare(b.title)), entry => /^[a-z]/i.test(entry.title) ? entry.title[0].toUpperCase() : '#'))
+  const groupId = (section: DocumentationIndexSection, index: number) => section.groups[index].id ?? `${section.id}-group-${index + 1}`
+  const sectionIds = $derived(sections.flatMap(section => [section.id, ...section.groups.map((_, index) => groupId(section, index))]).join(','))
+  const panelId = (part: 'category' | 'alphabetical') => `${idPrefix ?? name}-${part}-index`
+  const letterId = (letter: string) => `${idPrefix ? `${idPrefix}-` : ''}index-${letter === '#' ? 'symbols' : letter.toLowerCase()}`
+  const letterHashPrefix = $derived(`#${idPrefix ? `${idPrefix}-` : ''}index-`)
+  const count = (section: DocumentationIndexSection) => section.groups.reduce((total, group) => total + group.entries.length, 0)
+  const ordinal = (index: number) => String(index + 1).padStart(2, '0')
+
+  $effect(() => {
+    const prefix = letterHashPrefix
+    const ids = sectionIds.split(',')
+    function syncView() {
+      if (location.hash.startsWith(prefix) && /^(symbols|[a-z])$/.test(location.hash.slice(prefix.length))) alphabetical = true
+      else if (ids.includes(location.hash.slice(1))) alphabetical = false
+    }
+    syncView()
+    window.addEventListener('hashchange', syncView)
+    return () => window.removeEventListener('hashchange', syncView)
+  })
+  $effect(() => {
+    void alphabetical
+    const target = document.getElementById(location.hash.slice(1))
+    if (target && !target.closest('[hidden]')) target.scrollIntoView({ block: 'start' })
+  })
+</script>
+
+<!-- Described entries read as ruled rows with their summary; bare titles stay a quiet list of links. -->
+{#snippet entryLinks(entries: DocumentationIndexEntry[], { columns = false, showCategory = false, showDescriptions = false } = {})}
+  <ul class="documentation-index-links" data-columns={columns || undefined} data-described={showDescriptions || undefined}>
+    {#each entries as entry (entry.id)}
+      <li>
+        <Link href={entry.url} disabled={entry.disabled} unfinished={entry.unfinished}>
+          <b>{entry.displayTitle || entry.title}</b>
+          {#if showDescriptions && entry.description}<span>{t(entry.description)}</span>{/if}
+          {#if showCategory}<small>{t(entry.category)}</small>{/if}
+        </Link>
+      </li>
+    {/each}
+  </ul>
+{/snippet}
+
+<div class="documentation-index">
+  <!-- A contents list, not a second catalog: each section by its number, name and size; the sibling index closes it. -->
+  <nav class="documentation-index-directory" aria-label={tw ? `${name === 'guide' ? 'Guide' : 'Reference'} 分區` : `${name === 'guide' ? 'Guide' : 'Reference'} sections`}>
+    {#each sections as section, index (section.id)}
+      <a href={`#${section.id}`} onclick={() => alphabetical = false}>
+        <small>{ordinal(index)}</small>
+        <b>{section.title}</b>
+        <span class="documentation-index-count">{count(section)}</span>
+      </a>
+    {/each}
+    <Link href={related.href} data-related="">
+      <small aria-hidden="true">→</small>
+      <b>{related.title}</b>
+      <span>{related.description}</span>
+    </Link>
+  </nav>
+
+  <div class="documentation-index-toolbar">
+    <p>{tw ? (name === 'guide' ? '所有教學' : '所有條目') : (name === 'guide' ? 'All guides' : 'All entries')} <span class="documentation-index-count">{entries.length}</span></p>
+    <div class="ui-segmented" data-variant="underline" role="group" aria-label={tw ? '索引顯示方式' : 'Index view'}>
+      <button type="button" aria-pressed={!alphabetical} aria-controls={panelId('category')} onclick={() => alphabetical = false}>{tw ? '依分類' : 'By category'}</button>
+      <button type="button" aria-pressed={alphabetical} aria-controls={panelId('alphabetical')} onclick={() => alphabetical = true}>A–Z</button>
+    </div>
+  </div>
+
+  <div id={panelId('category')} hidden={alphabetical}>
+    {#each sections as section, sectionIndex (section.id)}
+      <section class="documentation-index-section" aria-labelledby={section.id}>
+        <header>
+          <small aria-hidden="true">{ordinal(sectionIndex)}</small>
+          <h2 id={section.id}>{section.title} <span class="documentation-index-count">{count(section)}</span></h2>
+          <p>{section.description}</p>
+          {#if section.groups.length > 1}
+            <nav class="documentation-index-groups" aria-label={tw ? `${section.title}分類` : `${section.title} categories`}>
+              {#each section.groups as group, index (groupId(section, index))}
+                <a href={`#${groupId(section, index)}`}>{group.title}</a>
+              {/each}
+            </nav>
+          {/if}
+        </header>
+        {#if section.groups.length === 1}
+          {@render entryLinks(section.groups[0].entries, { columns: !showDescriptions, showDescriptions })}
+        {:else}
+          <div class="documentation-index-categories">
+            {#each section.groups as group, index (groupId(section, index))}
+              <section aria-labelledby={groupId(section, index)}>
+                <h3 id={groupId(section, index)}>{group.title} <span class="documentation-index-count">{group.entries.length}</span></h3>
+                {@render entryLinks(group.entries, { columns: true })}
+              </section>
+            {/each}
+          </div>
+        {/if}
+      </section>
+    {/each}
+  </div>
+
+  <div id={panelId('alphabetical')} hidden={!alphabetical}>
+    <nav class="documentation-index-letters" aria-label={tw ? '依字母跳轉' : 'Jump to a letter'}>
+      {#each [...letters.keys()] as letter (letter)}
+        <a href={`#${letterId(letter)}`}>{letter}</a>
+      {/each}
+    </nav>
+    <!-- A book's index: letters run in columns, each title followed by its section. -->
+    <div class="documentation-index-alphabet">
+      {#each [...letters] as [letter, documents] (letter)}
+        <section aria-labelledby={letterId(letter)}>
+          <h2 id={letterId(letter)}>{letter}</h2>
+          {@render entryLinks(documents, { showCategory: true })}
+        </section>
+      {/each}
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,21 @@
+---
+interface Props {
+  p1?: string
+  p2?: string
+  target?: string
+}
+
+let { p1, p2, target } = Astro.props
+if (p1 && p2) {
+  p1 = p1.trim()
+  p2 = p2.trim()
+  if (target === 'class') {
+    p1 = p1.replace(/.*class="(.*)".*/gm, '$1')
+    p2 = p2.replace(/.*class="(.*)".*/gm, '$1')
+  }
+}
+---
+
+{p1 && p2 && <small class="(font-weight:var(--ui-weight-medium)) text-success">↓ {
+  Math.round(Math.abs((p1.length - p2.length) / p1.length) * 100)
+}% code</small>}

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

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import IconChevronDown from '@tabler/icons-svelte-runes/icons/chevron-down'
+  import { getSite } from '../site'
+
+  /** A long surface clamped under a canvas fade; one quiet control shows the rest. */
+  let { children }: { children?: Snippet } = $props()
+  let expanded = $state(false)
+  const id = $props.id()
+  const { t } = getSite()
+</script>
+
+<div class="ui-expand" data-expanded={expanded}>
+  <div {id}>{@render children?.()}</div>
+  <div class="ui-expand-control">
+    <button type="button" class="ui-button" data-size="sm" aria-expanded={expanded} aria-controls={id} onclick={() => { expanded = !expanded }}>
+      {t(expanded ? 'Collapse' : 'Expand')}
+      <IconChevronDown aria-hidden="true" stroke={1.5} />
+    </button>
+  </div>
+</div>

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

@@ -0,0 +1,37 @@
+---
+import FileIcon from './FileIcon.astro'
+import FolderSvg from '../../public/icons/folder.svg'
+
+declare type ExplorerViewItemOption = {
+  name: string
+  children?: ExplorerViewItemOption[]
+}
+
+interface Props {
+  /** The tree's entries; folders list theirs as `children`. */
+  items: ExplorerViewItemOption[]
+  /** Nested folders render their list alone, without the `ui-tree` frame. */
+  nested?: boolean
+}
+
+/** A file tree (`ui-tree`): names in mono, nested folders on hairline guides. */
+const { items, nested } = Astro.props
+const extOf = (name: string) => name.includes('.') ? name.split('.').pop() : ''
+---
+
+{nested
+  ? <ul>
+    {items.map((option) => {
+      const ext = extOf(option.name)
+      return (
+        <li>
+          <div>
+            {ext ? <FileIcon name={option.name} ext={ext} aria-hidden="true" /> : <FolderSvg aria-hidden="true" />}
+            <b>{option.name}</b>
+          </div>
+          {option.children?.length ? <Astro.self items={option.children} nested /> : null}
+        </li>
+      )
+    })}
+  </ul>
+  : <div class="ui-tree"><Astro.self items={items} nested /></div>}

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

@@ -0,0 +1,123 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = {
+  name: string
+  ext?: string
+  lang?: string
+} & Omit<HTMLAttributes<'img'>, 'src' | 'alt'>
+
+const { name, ext, lang, ...props } = Astro.props
+let icon = ''
+if (name) {
+  switch (true) {
+    case name.includes('react'):
+      icon = 'tsx'
+      break
+    case name.includes('eslint.config'):
+    case name.includes('.eslintrc'):
+      icon = 'eslint'
+      break
+    case name.includes('.component.'):
+    case name.includes('angular'):
+    case name == 'angular.json':
+      icon = 'angular'
+      break
+    case name.includes('Tailwind'):
+    case name.includes('tailwind.config'):
+      icon = 'tailwindcss'
+      break
+    case name.endsWith('blade.php'):
+      icon = 'laravel'
+      break
+    case name === 'PHP':
+      icon = 'php'
+      break
+    case name.includes('astro'):
+      icon = 'astro'
+      break
+    case name.includes('vue'):
+    case name.endsWith('vue'):
+      icon = 'vue'
+      break
+    case name == 'npx':
+      icon = 'npm'
+      break
+    case name === 'HTML':
+      icon = 'html'
+      break
+    case name === 'CSS':
+      icon = 'css'
+      break
+    case name.includes('json'):
+      icon = 'json'
+      break
+    case name.includes('webpack'):
+      icon = 'webpack'
+      break
+    case name.includes('vite'):
+    case name.startsWith('Vite'):
+      icon = 'vite'
+      break
+    case name.includes('master'):
+    case name.includes('Master'):
+      icon = 'master'
+      break
+    case name.includes('next.config'):
+      icon = 'nextConfig'
+      break
+    case name.includes('nuxt.config'):
+      icon = 'nuxtjs'
+      break
+    case name.includes('Bootstrap'):
+      icon = 'bootstrap'
+      break
+    case name.includes('.'):
+      icon = name.slice(name.lastIndexOf('.') + 1)
+      break
+  }
+}
+const icons = {
+  svelte: '/icons/svelte.svg',
+  angular: '/icons/angular.svg',
+  astro: '/icons/astro.svg',
+  php: '/icons/php.svg',
+  eslint: '/icons/eslint.svg',
+  ts: '/icons/typescript.svg',
+  js: '/icons/javascript.svg',
+  tsx: '/icons/react.svg',
+  jsx: '/icons/react.svg',
+  css: '/icons/css.svg',
+  html: '/icons/html.svg',
+  npm: '/icons/npm.svg',
+  yarn: '/icons/yarn.svg',
+  pnpm: '/icons/pnpm.svg',
+  bun: '/icons/bun.svg',
+  deno: '/icons/deno.svg',
+  laravel: '/icons/laravel.svg',
+  vue: '/icons/vue.svg',
+  json: '/icons/json.svg',
+  master: '/brand/v2/logo/mark/master-mark-small-on-dark.svg',
+  webpack: '/icons/webpack.svg',
+  styledComponent: '/images/styled-components.svg',
+  tailwindcss: '/images/tailwindcss.svg',
+  nextjs: '/images/frameworks/nextjs.svg',
+  nuxtjs: '/images/frameworks/nuxtjs.svg',
+  parcel: '/images/build-tools/parcel.svg',
+  reactFramework: '/images/frameworks/react.svg',
+  angularFramework: '/images/frameworks/angular.svg',
+  remix: '/images/frameworks/remix.svg',
+  vite: '/images/build-tools/vite.svg',
+  vuejs: '/images/frameworks/vuejs.svg',
+  webpackBuildTool: '/images/build-tools/webpack.svg',
+  nextConfig: '/icons/next.svg',
+  bootstrap: '/images/bootstrap.svg'
+} as Record<string, string>
+let source = icons[icon]
+if (!source) source = icons[name]
+if (!source && ext) source = icons[ext]
+if (!source && lang) source = icons[lang]
+---
+
+{/* Public file badges have fixed colors and do not need an SVG component. */}
+{source && <img {...props} src={source} alt="" />}

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

@@ -0,0 +1,80 @@
+<script lang="ts" module>
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  export interface FooterLink {
+    name: string
+    href?: string
+    disabled?: boolean
+  }
+
+  export interface FooterNavGroup {
+    name: string
+    links: FooterLink[]
+  }
+
+  export interface FooterProps extends HTMLAttributes<HTMLElement> {
+    navGroups?: FooterNavGroup[]
+    /** Replaces the notice; from Astro, a `copyright` slot. */
+    copyright?: Snippet
+  }
+</script>
+
+<script lang="ts">
+  import '../../styles/docs-shell/footer.css'
+  import clsx from 'clsx'
+  import Link from './Link.svelte'
+  import LanguageSelect from './LanguageSelect.svelte'
+  import ThemeSelect from './ThemeSelect.svelte'
+  import { useThemeMode } from '../contexts/theme-mode.svelte'
+  import IconChevronDown from '@tabler/icons-svelte-runes/icons/chevron-down'
+  import IconDeviceDesktop from '@tabler/icons-svelte-runes/icons/device-desktop'
+  import IconLanguage from '@tabler/icons-svelte-runes/icons/language'
+  import IconMoon from '@tabler/icons-svelte-runes/icons/moon'
+  import IconSun from '@tabler/icons-svelte-runes/icons/sun'
+  import { getSite } from '../site'
+
+  /** The site footer: link groups (legal links among them), then one quiet row: the notice, and the theme and language
+   * preferences shown by an icon and their value alone (the selects carry their names). */
+  let { navGroups = [], copyright, class: className, ...props }: FooterProps = $props()
+  const themeMode = useThemeMode()
+  const { locale, i18n, t } = getSite()
+  const localeName = i18n.nameOfLocale[locale] ?? locale
+  // The preference is read on the client; the server and the first paint show the default.
+  const preference = $derived(themeMode.preference ?? 'system')
+  const ThemeIcon = $derived(preference === 'light' ? IconSun : preference === 'dark' ? IconMoon : IconDeviceDesktop)
+</script>
+
+<footer {...props} class={clsx('ui-footer', className)}>
+  <nav aria-label={t('Footer')} class="ui-footer-nav">
+    {#each navGroups as group (group.name)}
+      <div class="ui-footer-group">
+        <h2>{t(group.name)}</h2>
+        <ul>
+          {#each group.links as link (link.href || link.name)}
+            <li>
+              <Link href={link.href} disabled={link.disabled}>{t(link.name)}</Link>
+            </li>
+          {/each}
+        </ul>
+      </div>
+    {/each}
+  </nav>
+  <div class="ui-footer-legal">
+    <p class="ui-footer-notice">{#if copyright}{@render copyright()}{:else}© {new Date().getFullYear()} Aoyue Design LLC.{/if}</p>
+    <label class="ui-footer-preference">
+      <ThemeIcon aria-hidden="true" stroke={1.5} />
+      {t(preference.charAt(0).toUpperCase() + preference.slice(1))}
+      <ThemeSelect aria-label={t('Theme')} />
+      <IconChevronDown aria-hidden="true" stroke={1.5} />
+    </label>
+    {#if i18n.locales.length > 1}
+    <label class="ui-footer-preference">
+      <IconLanguage aria-hidden="true" stroke={1.5} />
+      {localeName}
+      <LanguageSelect aria-label={t('Language')} />
+      <IconChevronDown aria-hidden="true" stroke={1.5} />
+    </label>
+    {/if}
+  </div>
+</footer>

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

@@ -0,0 +1,8 @@
+---
+/** A closed native disclosure keeps the complete output in the server HTML. */
+---
+
+<details class="ui-disclosure" data-generated="">
+  <summary>Generated CSS</summary>
+  <slot />
+</details>