@master/internal-site 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,25 @@
+---
+import '../../styles/docs-shell/page-content.css'
+import type { PageContentItem } from './page-content.svelte'
+import PageContentTitle from './PageContentTitle.svelte'
+import groupPageContent from '../utils/group-page-content'
+
+interface Props {
+  items: (PageContentItem & { lang?: string })[]
+  label: string
+  labelLang?: string
+}
+
+/** The same heading inventory as the documentation rail, closed in a disclosure, available without hydration. */
+const { items, label, labelLang } = Astro.props
+---
+
+<details class="ui-disclosure" data-variant="rule" data-contents-disclosure="">
+  <summary lang={labelLang}>{label}</summary>
+  <nav class="ui-toc" aria-label={label}>
+    <ol>{groupPageContent(items).map(({ item, children }) => <li>
+      <a href={`#${item.id}`} lang={item.lang} data-level={item.level}><PageContentTitle title={item.title} /></a>
+      {children.length > 0 && <ol>{children.map(child => <li><a href={`#${child.id}`} lang={child.lang} data-level={child.level}><PageContentTitle title={child.title} /></a></li>)}</ol>}
+    </li>)}</ol>
+  </nav>
+</details>

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

@@ -0,0 +1,70 @@
+<script lang="ts" module>
+  const initializedPageContentScrollContainers = new WeakSet<HTMLElement>()
+
+  /** A list longer than this folds every section but the one being read to its title. */
+  const foldAfter = 12
+</script>
+
+<script lang="ts">
+  import Link from './Link.svelte'
+  import PageContentTitle from './PageContentTitle.svelte'
+  import { usePageContent, type PageContentItem } from './page-content.svelte'
+  import groupPageContent from '../utils/group-page-content'
+  import { getSite } from '../site'
+
+  interface Props {
+    /** The list element, for a parent that scrolls the list itself. */
+    element?: HTMLOListElement
+    scrollContainer?: HTMLElement
+    lang?: string
+    translate?: boolean
+  }
+
+  /**
+   * The live list inside a `PageContentProvider`, nested as `ui-toc` lists: the entry being read carries
+   * `aria-current="location"`. With a scroll container, the current entry is kept in view inside it. Titles are
+   * translated unless they come from the page's own (already localized) headings.
+   */
+  let { element = $bindable(), scrollContainer, lang, translate = true }: Props = $props()
+  const pageContent = usePageContent()
+  const { t, i18n, locale } = getSite()
+  const { defaultLocale, hreflangOfLocale } = i18n
+  const fold = $derived(pageContent.items.length > foldAfter && pageContent.items.some((item) => item.level === 3))
+
+  // A title the page's language has no translation for is read in its source language.
+  const langOf = (title: string) => translate && locale !== defaultLocale && !title.startsWith('`') && t(title) === title ? hreflangOfLocale?.[defaultLocale] ?? defaultLocale : undefined
+
+  $effect(() => {
+    const container = scrollContainer
+    const currentId = pageContent.currentId
+    const nav = currentId ? element?.querySelector<HTMLElement>(`[data-page-content-nav-id="${CSS.escape(currentId)}"]`) : undefined
+    if (nav && container && container.scrollHeight > container.clientHeight) {
+      const behavior: ScrollBehavior = initializedPageContentScrollContainers.has(container) && !matchMedia('(prefers-reduced-motion: reduce)').matches
+        ? 'smooth'
+        : 'instant' as ScrollBehavior
+
+      // The current entry settles about a third of the way down the scrolling list.
+      container.scrollTo({
+        top: container.scrollTop + nav.getBoundingClientRect().top - container.getBoundingClientRect().top - container.clientHeight / 3,
+        behavior
+      })
+      initializedPageContentScrollContainers.add(container)
+    }
+  })
+</script>
+
+<!-- The bootstrap script marks the live entry before hydration, so its attribute may differ from the first render. -->
+{#snippet nav({ id, title, level }: PageContentItem)}
+  <Link href={'#' + id} aria-current={pageContent.currentId === id ? 'location' : undefined} data-page-content-nav-id={id} data-level={level} lang={langOf(title)}>
+    <PageContentTitle {title} translate={translate ? t : undefined} />
+  </Link>
+{/snippet}
+
+<ol bind:this={element} {lang} data-fold={fold ? '' : undefined}>
+  {#each groupPageContent(pageContent.items) as { item, children } (item.id)}
+    <li>
+      {@render nav(item)}
+      {#if children.length > 0}<ol>{#each children as child (child.id)}<li>{@render nav(child)}</li>{/each}</ol>{/if}
+    </li>
+  {/each}
+</ol>

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

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import { providePageContent, type PageContentItem } from './page-content.svelte'
+
+  interface Props {
+    items: PageContentItem[]
+    children?: Snippet
+  }
+
+  /** Tracks the entry being read for the `PageContentList`s inside it. */
+  let { items, children }: Props = $props()
+  providePageContent(() => items)
+</script>
+
+{@render children?.()}

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

@@ -0,0 +1,16 @@
+<script lang="ts">
+  interface Props {
+    title: string
+    translate?: (text: string) => string
+  }
+
+  /**
+   * A contents entry's words: a title written as `code` is set in the mono face, any other title is translated. The
+   * heading's text runs are joined with spaces when the contents are collected, so a space before punctuation that
+   * followed inline code (`:hover`, `:active`) is taken out again.
+   */
+  let { title, translate }: Props = $props()
+  const text = $derived(translate ? translate(title) : title)
+</script>
+
+{#if title.startsWith('`')}<code>{title.replace(/`/g, '')}</code>{:else}{text.replace(/\s+([,.;:!?)])/g, '$1').replace(/\(\s+/g, '(')}{/if}

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

@@ -0,0 +1,40 @@
+---
+import Link from './Link.svelte'
+import { createTranslation } from '../utils/i18n'
+
+interface Props {
+  pageCategories?: { pages: any[] }[]
+  metadata: any
+  locale: string
+  dictionaries: Record<string, () => Promise<any>>
+}
+
+/** The previous and next documents in the section's order, as a `ui-pager`. */
+const { pageCategories, metadata, locale, dictionaries } = Astro.props
+const $ = await createTranslation(locale, dictionaries)
+const tw = locale === 'tw'
+const unit = metadata?.pathname?.split('/')?.[1]
+const pages = (pageCategories?.flatMap((category: any) => category.pages) || [])
+  .filter(({ pathname }: any) => pathname.split('/').length <= 3 && unit)
+const currentPageIndex = pages.findIndex(({ pathname }: any) => metadata.pathname === pathname)
+const prevDefinedMetadata = currentPageIndex !== -1 && pages[currentPageIndex - 1]
+const nextDefinedMetadata = currentPageIndex !== -1 && pages[currentPageIndex + 1]
+const navs = [
+  prevDefinedMetadata && { direction: 'prev', definedMetadata: prevDefinedMetadata },
+  nextDefinedMetadata && { direction: 'next', definedMetadata: nextDefinedMetadata }
+].filter(Boolean).map(({ direction, definedMetadata }: any) => ({
+  direction,
+  href: definedMetadata.pathname,
+  label: direction === 'prev' ? (tw ? '上一篇' : 'Previous') : (tw ? '下一篇' : 'Next'),
+  title: $(definedMetadata.title.absolute || definedMetadata.title)
+}))
+---
+
+{navs.length > 0 && (
+  <nav class="ui-pager" aria-label={tw ? '前後篇文件' : 'Previous and next documents'}>
+    {navs.map(({ direction, href, label, title }) => <Link {href} rel={direction} aria-label={`${label}: ${title}`}>
+      <small>{label}</small>
+      <b>{title}</b>
+    </Link>)}
+  </nav>
+)}

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

@@ -0,0 +1,12 @@
+---
+import type { CodeProp } from './code-props'
+import type { PreparedCode } from '../utils/prepared-code'
+import CodeView from './CodeView.astro'
+
+type Props = CodeProp & { prepared: PreparedCode }
+
+/** A `CodeView` around a block highlighted ahead of rendering. */
+const { prepared, ...props } = Astro.props
+---
+
+<CodeView {...props}><Fragment set:html={prepared.html} /></CodeView>

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

@@ -0,0 +1,16 @@
+---
+import { renderJSX } from 'astro/runtime/server/jsx.js'
+import { isVNode } from 'astro/jsx-runtime'
+
+interface Props {
+  /** Markup passed as a prop: an Astro template value, or JSX written in MDX. */
+  node: unknown
+}
+
+const { node } = Astro.props
+const containsVNode = (value: unknown): boolean => Array.isArray(value) ? value.some(containsVNode) : isVNode(value)
+// MDX writes JSX with Astro's JSX runtime, whose nodes only render through the page's result.
+const html = containsVNode(node) ? await renderJSX($$result, node) : undefined
+---
+
+{html !== undefined ? <Fragment set:html={html} /> : node}

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

@@ -0,0 +1,17 @@
+---
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js'
+import type { Props as PageProps } from '../types/Props'
+
+interface Props {
+  /** Outermost first; each layer renders the next in its default slot. */
+  layers: AstroComponentFactory[]
+  props: PageProps
+}
+
+const { layers, props } = Astro.props
+const [Layer, ...inner] = layers
+---
+
+{inner.length
+  ? <Layer {...props}><Astro.self layers={inner} props={props} /></Layer>
+  : <Layer {...props} />}

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

@@ -0,0 +1,31 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import type { HTMLButtonAttributes } from 'svelte/elements'
+  import IconSearch from '@tabler/icons-svelte-runes/icons/search'
+  import { openSearch, searchLabels } from '../contexts/search'
+  import { getSite } from '../site'
+
+  interface Props extends HTMLButtonAttributes {
+    children?: Snippet
+  }
+
+  /** Opens the page's search dialog. Without children it renders the search field trigger (`ui-search-trigger`) with its shortcut. */
+  let { class: className, children, onclick, type = 'button', ...props }: Props = $props()
+  const { t, locale } = getSite()
+  const { searchText, searchLabel } = searchLabels(t, locale)
+
+  function handleClick(event: MouseEvent & { currentTarget: EventTarget & HTMLButtonElement }) {
+    onclick?.(event)
+    if (!event.defaultPrevented) openSearch(event.currentTarget)
+  }
+</script>
+
+<button {...props} {type} class={className} aria-label={props['aria-label'] ?? searchLabel} aria-keyshortcuts="Meta+K Control+K" onclick={handleClick}>
+  {#if children}
+    {@render children()}
+  {:else}
+    <IconSearch aria-hidden="true" stroke={1.5} />
+    {searchText}
+    <span class="ui-kbd" aria-hidden="true">⌘K</span>
+  {/if}
+</button>

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

@@ -0,0 +1,174 @@
+<script lang="ts" module>
+  import type { Attachment } from 'svelte/attachments'
+  import type { DocumentationSearchPage } from '../utils/documentation-search'
+
+  const cache: Record<string, Promise<DocumentationSearchPage[]>> = {}
+
+  async function loadPages(locale: string) {
+    cache[locale] ??= fetch(`/search/${encodeURIComponent(locale)}.json`).then(response => {
+      if (!response.ok) throw new Error(`Search unavailable (${response.status})`)
+      return response.json()
+    }).catch(error => { delete cache[locale]; throw error })
+    return cache[locale]
+  }
+
+  /** The dialog lives at the end of the body, outside the island that opens it. */
+  const portal: Attachment<HTMLElement> = (node) => {
+    document.body.append(node)
+    return () => node.remove()
+  }
+</script>
+
+<script lang="ts">
+  import '../../styles/docs-shell/documentation-search.css'
+  import { untrack } from 'svelte'
+  import Link from './Link.svelte'
+  import { getSite } from '../site'
+  import { createDocumentationSearch } from '../utils/documentation-search'
+  import { openSearchEvent } from '../contexts/search'
+  import IconArrowDown from '@tabler/icons-svelte-runes/icons/arrow-down'
+  import IconArrowUp from '@tabler/icons-svelte-runes/icons/arrow-up'
+  import IconCornerDownLeft from '@tabler/icons-svelte-runes/icons/corner-down-left'
+  import IconSearch from '@tabler/icons-svelte-runes/icons/search'
+  import IconX from '@tabler/icons-svelte-runes/icons/x'
+  import { isInteractOutside } from '../utils/isInteractOutside'
+
+  /** The page's single search dialog; search triggers in other islands open it by event (`contexts/search`). */
+  const { t, locale } = getSite()
+  const tw = locale === 'tw'
+  let opened = $state(false)
+  let query = $state('')
+  let pages = $state.raw<DocumentationSearchPage[]>([])
+  let error = $state('')
+  let loading = $state(false)
+  let retry = $state(0)
+  let selected = $state(0)
+  let dialog = $state<HTMLDialogElement>()
+  let input = $state<HTMLInputElement>()
+  let scroll = $state<HTMLDivElement>()
+  let scrollTop = 0
+  let returnFocus: HTMLElement | null = null
+  const search = $derived(createDocumentationSearch(pages))
+  const results = $derived(search(query))
+
+  function selectQuery(value: string) {
+    query = value
+    selected = 0
+    scrollTop = 0
+    if (scroll) scroll.scrollTop = 0
+    input?.focus()
+  }
+
+  function close() {
+    scrollTop = scroll?.scrollTop ?? 0
+    dialog?.close()
+    opened = false
+    returnFocus?.focus()
+  }
+
+  function open(event?: Event) {
+    const trigger = (event as CustomEvent<{ trigger?: HTMLElement }> | undefined)?.detail?.trigger
+    returnFocus = trigger instanceof HTMLElement ? trigger : document.activeElement as HTMLElement
+    opened = true
+  }
+
+  $effect(() => {
+    if (!opened) return
+    void retry
+    let active = true
+    loading = true
+    error = ''
+    loadPages(locale).then(data => {
+      if (active) { pages = data; loading = false }
+    }, reason => {
+      if (active) { error = reason.message; loading = false }
+    })
+    return () => { active = false }
+  })
+
+  $effect(() => {
+    if (opened && dialog) {
+      untrack(() => {
+        if (!dialog!.open) dialog!.showModal()
+        input?.focus()
+        if (scroll) scroll.scrollTop = scrollTop
+      })
+    }
+  })
+
+  const closeOnBackdropClick: Attachment<HTMLDialogElement> = (element) => {
+    const onclick = (event: MouseEvent) => {
+      if (event.target === element && isInteractOutside(element, event)) close()
+    }
+    element.addEventListener('click', onclick)
+    return () => element.removeEventListener('click', onclick)
+  }
+
+  $effect(() => {
+    window.addEventListener(openSearchEvent, open)
+    return () => window.removeEventListener(openSearchEvent, open)
+  })
+
+  function shortcut(event: KeyboardEvent) {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') { event.preventDefault(); opened ? close() : open() }
+  }
+
+  function onkeydown(event: KeyboardEvent) {
+    if (event.isComposing || event.keyCode === 229) return
+    if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); close(); return }
+    if (event.key === 'Enter' && results.length) { event.preventDefault(); document.getElementById(`documentation-result-${selected}`)?.click() }
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault()
+      const next = Math.max(0, Math.min(results.length - 1, selected + (event.key === 'ArrowDown' ? 1 : -1)))
+      selected = next
+      document.getElementById(`documentation-result-${next}`)?.scrollIntoView({ block: 'nearest' })
+    }
+  }
+
+  const reasons: Record<string, string> | undefined = tw ? { Identifier: '識別字', Title: '名稱', Syntax: '語法與範例', Topic: '主題', Content: '內文' } : undefined
+  const kinds: Record<string, string> = tw
+    ? { utility: 'Utility', rule: '規則', tokens: 'Tokens', directive: '指令', tool: '工具', package: 'API' }
+    : { utility: 'Utility', rule: 'Rule', tokens: 'Tokens', directive: 'Directive', tool: 'Tool', package: 'API' }
+</script>
+
+<svelte:window onkeydown={shortcut} />
+
+{#snippet excerpt(text: string, query: string)}
+  {@const index = text.toLowerCase().indexOf(query.toLowerCase())}
+  {@const start = Math.max(0, index - 45)}
+  {@const value = text.slice(start, start + 220)}
+  {@const offset = value.toLowerCase().indexOf(query.toLowerCase())}
+  {start > 0 ? '…' : ''}{#if offset < 0}{value}{:else}{value.slice(0, offset)}<mark>{value.slice(offset, offset + query.length)}</mark>{value.slice(offset + query.length)}{/if}{start + 220 < text.length ? '…' : ''}
+{/snippet}
+
+{#if opened}
+  <dialog bind:this={dialog} {@attach portal} {@attach closeOnBackdropClick} class="ui-dialog" data-variant="search" aria-label={tw ? '搜尋文件' : 'Search documentation'} oncancel={close}>
+    <div class="ui-dialog-search">
+      <IconSearch size={18} stroke={1.5} aria-hidden="true" />
+      <input bind:this={input} type="search" role="combobox" aria-autocomplete="list" aria-expanded={Boolean(query)} value={query} autocomplete="off" spellcheck={false} placeholder={tw ? '搜尋文件…' : 'Search documentation…'} aria-label={tw ? '搜尋文件' : 'Search documentation'} aria-controls="documentation-search-results" aria-activedescendant={results[selected] ? `documentation-result-${selected}` : undefined}
+        oninput={event => selectQuery(event.currentTarget.value)}
+        {onkeydown} />
+      {#if query}<button type="button" class="ui-button" data-variant="quiet" data-shape="icon" data-size="sm" onclick={() => selectQuery('')} aria-label={tw ? '清除搜尋' : 'Clear search'}><IconX size={16} stroke={1.5} aria-hidden="true" /></button>{/if}
+      <button type="button" class="ui-button ui-dialog-close" data-variant="quiet" data-size="sm" onclick={close} aria-label={tw ? '關閉搜尋' : 'Close search'}><span class="ui-kbd">esc</span><span>{tw ? '取消' : 'Cancel'}</span></button>
+    </div>
+    <div class="ui-dialog-body" bind:this={scroll}>
+      <p class="ui-dialog-status" role="status">{loading ? (tw ? '正在載入文件…' : 'Loading documentation…') : error ? (tw ? '搜尋暫時無法載入。' : 'Search could not load.') : query ? `${results.length === 40 ? (tw ? '前 ' : 'Top ') : ''}${results.length} ${tw ? '筆結果' : results.length === 1 ? 'result' : 'results'}` : (tw ? '依名稱、別名或 CSS 屬性查找' : 'Find a name, alias or CSS property')}</p>
+      {#if error}<div class="ui-dialog-note"><p>{tw ? '請檢查連線，再試一次。' : 'Check your connection and try again.'}</p><button type="button" class="ui-button" data-size="sm" onclick={() => { retry += 1; input?.focus() }}>{tw ? '再試一次' : 'Try again'}</button></div>{/if}
+      {#if !query && !error && !loading}<div class="ui-dialog-note">
+        <p>{tw ? '試試看' : 'Try searching'}</p>
+        {#each ['padding', 'padding-inline-start:', 'fg-red:hover@sm'] as value (value)}<button type="button" class="ui-button" data-size="sm" onclick={() => selectQuery(value)}><code>{value}</code><IconCornerDownLeft size={14} stroke={1.5} aria-hidden="true" /></button>{/each}
+      </div>{/if}
+      {#if query && !results.length && !error && !loading}<div class="ui-dialog-note" data-align="center"><IconSearch size={24} stroke={1.25} aria-hidden="true" /><b>{tw ? '找不到相符的文件' : 'No matching documents'}</b><p>{tw ? '試試屬性全名、token 名稱或其他關鍵字。' : 'Try a property name, a token name or a different keyword.'}</p></div>{/if}
+      <ol id="documentation-search-results" class="ui-results" role="listbox" aria-label={tw ? '搜尋結果' : 'Search results'} aria-busy={loading}>
+        {#if !error}{#each results as result, index (result.page.url)}<li role="presentation">
+          <Link id={`documentation-result-${index}`} role="option" tabindex={-1} aria-selected={selected === index} href={result.href} onclick={close} onpointermove={() => { selected = index }}>
+            <small>{t(result.page.category ?? '')} · {kinds[result.page.kind ?? ''] ?? (result.page.url.includes('/guide') ? 'Guide' : 'Page')} · {reasons?.[result.reason] ?? result.reason}</small>
+            <b>{result.page.title}</b>
+            <span>{@render excerpt(result.excerpt, query)}</span>
+          </Link>
+        </li>{/each}{/if}
+      </ol>
+    </div>
+    <div class="ui-dialog-foot" aria-hidden="true"><span><span class="ui-kbd"><IconArrowUp size={12} /></span><span class="ui-kbd"><IconArrowDown size={12} /></span>{tw ? '選擇' : 'Navigate'}</span><span><span class="ui-kbd"><IconCornerDownLeft size={12} /></span>{tw ? '開啟' : 'Open'}</span><span>{tw ? '文件搜尋' : 'Documentation'}</span></div>
+  </dialog>
+{/if}

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

@@ -0,0 +1,62 @@
+<script lang="ts">
+  import '../../styles/docs-shell/segments.css'
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    /** The views' names, in order. Each view's content is the snippet (a named slot from Astro) of the same name. */
+    names: readonly string[]
+    label?: string
+    children?: Snippet
+    // Named slots are supplied by the host; only function-valued entries render.
+    [segment: string]: unknown
+  }
+
+  /** Related document views stay available in the HTML, including without scripting. */
+  let { names, label = 'Document view', ...segments }: Props = $props()
+  const prefix = $props.id()
+  const buttons: (HTMLButtonElement | undefined)[] = []
+  // The first view opens; the choice is the reader's after that.
+  // svelte-ignore state_referenced_locally
+  let activeName = $state(names[0])
+  const activeIndex = $derived(Math.max(0, names.findIndex(name => name === activeName)))
+
+  function navigate(event: KeyboardEvent, index: number) {
+    const next = event.key === 'Home' ? 0 : event.key === 'End' ? names.length - 1
+      : event.key === 'ArrowRight' ? (index + 1) % names.length
+        : event.key === 'ArrowLeft' ? (index - 1 + names.length) % names.length : undefined
+    if (next === undefined) return
+    event.preventDefault()
+    activeName = names[next]
+    buttons[next]?.focus()
+  }
+</script>
+
+{#if names.length}
+  <div class="segment-views">
+    <div class="ui-segmented" role="tablist" aria-label={label}>
+      {#each names as name, index (name)}<button
+        bind:this={buttons[index]}
+        type="button"
+        id={`${prefix}-tab-${index}`}
+        role="tab"
+        aria-controls={`${prefix}-panel-${index}`}
+        aria-selected={activeIndex === index}
+        tabindex={activeIndex === index ? 0 : -1}
+        onclick={() => { activeName = name }}
+        onkeydown={event => navigate(event, index)}>
+        {name}
+      </button>{/each}
+    </div>
+    {#each names as name, index (name)}
+      <div class="segment-panel"
+        id={`${prefix}-panel-${index}`}
+        role="tabpanel"
+        aria-labelledby={`${prefix}-tab-${index}`}
+        tabindex="0"
+        hidden={activeIndex !== index}>
+        <div class="segment-panel-label">{name}</div>
+        {#if typeof segments[name] === 'function'}{@render (segments[name] as Snippet)()}{/if}
+      </div>
+    {/each}
+  </div>
+{/if}

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

@@ -0,0 +1,13 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Text and source side by side (`StepL`, `StepR`). */
+  $row?: boolean
+}
+
+/** One step of a `StepSection`. */
+const { $row, class: className, ...props } = Astro.props
+---
+
+<li><div {...props} class:list={['ui-steps-content', className]} data-columns={$row || undefined}><slot /></div></li>

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

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'div'>
+
+/** A row step's text. */
+const { class: className, ...props } = Astro.props
+---
+
+<div {...props} class:list={['ui-steps-text', className]}><slot /></div>

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

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'div'>
+
+/** A row step's source. */
+const { class: className, ...props } = Astro.props
+---
+
+<div {...props} class:list={['ui-steps-source', className]}><slot /></div>

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

@@ -0,0 +1,12 @@
+---
+import '../../styles/system/data.css'
+import '../../styles/docs-shell/steps.css'
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'ol'>
+
+/** Document steps on `ui-steps`: the list numbers each step beside its authored heading. Steps are `Step.astro`, split into `StepL.astro` and `StepR.astro`. */
+const { class: className, ...props } = Astro.props
+---
+
+<ol {...props} class:list={['ui-steps', className]} data-variant="document"><slot /></ol>

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

@@ -0,0 +1,8 @@
+---
+import Link from './Link.svelte'
+
+/** One link of `Tabs`; it takes `Link`'s props. */
+const props = Astro.props
+---
+
+<Link {...props}><slot /></Link>

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

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'nav'>
+
+/** Links between sibling pages as underlined `ui-segmented` tabs; the page being read is underlined in ink (`aria-current="page"`). Each tab is a `Tab.astro`. */
+const { class: className, ...props } = Astro.props
+---
+
+<nav {...props} class:list={['ui-segmented', className]} data-variant="underline"><slot /></nav>

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

@@ -0,0 +1,19 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+type Props = HTMLAttributes<'svg'>
+
+const { class: className, ...props } = Astro.props
+---
+
+<svg class:list={['block@apply(--site-dark) hidden stroke-accent', className]} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" stroke-linecap="round" stroke-linejoin="round" {...props}>
+  <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+  <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" class="(fill:var(--color-primary)) (opacity:.2)" />
+  <path d="M17 4a2 2 0 0 0 2 2a2 2 0 0 0 -2 2a2 2 0 0 0 -2 -2a2 2 0 0 0 2 -2" />
+  <path d="M19 11h2m-1 -1v2" />
+</svg>
+<svg class:list={['block@apply(--site-light) hidden stroke-accent', className]} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" stroke-linecap="round" stroke-linejoin="round" {...props}>
+  <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+  <circle cx="12" cy="12" r="4" class="(fill:var(--color-primary)) (opacity:.2)" />
+  <path d="M3 12h1m8 -9v1m8 8h1m-9 8v1m-6.4 -15.4l.7 .7m12.1 -.7l-.7 .7m0 11.4l.7 .7m-12.1 -.7l-.7 .7" />
+</svg>

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

@@ -0,0 +1,20 @@
+<script lang="ts">
+  import type { HTMLSelectAttributes } from 'svelte/elements'
+  import clsx from 'clsx'
+  import { useThemeMode } from '../contexts/theme-mode.svelte'
+  import { getSite } from '../site'
+
+  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 themeMode = useThemeMode()
+  const { t } = getSite()
+</script>
+
+<select data-variant="overlay" {...props} class={clsx('ui-select', className)} value={themeMode.preference}
+  onchange={(event) => { themeMode.preference = event.currentTarget.value }}>
+  <option value="light">{t('Light')}</option>
+  <option value="dark">{t('Dark')}</option>
+  <option value="system">{t('System')}</option>
+</select>

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

@@ -0,0 +1,32 @@
+<script lang="ts" module>
+  import dayjs from 'dayjs'
+  import relativeTime from 'dayjs/plugin/relativeTime'
+  import 'dayjs/locale/zh-tw'
+  import 'dayjs/locale/en'
+
+  dayjs.extend(relativeTime)
+
+  const locales: Record<string, string> = {
+    tw: 'zh-tw',
+    en: 'en'
+  }
+</script>
+
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { getSite } from '../site'
+
+  /** The date when rendered; the reader's relative time once hydrated. */
+  let { timestamp }: { timestamp: string | number | Date } = $props()
+  const { locale } = getSite()
+  let hydrated = $state(false)
+  const formattedDate = $derived(hydrated
+    ? dayjs(timestamp).locale(locales[locale]).fromNow()
+    : dayjs(timestamp).format('ddd, MMMM D YYYY'))
+
+  onMount(() => {
+    hydrated = true
+  })
+</script>
+
+{formattedDate}