@master/internal-site 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,14 @@
+---
+import { siteOf } from '../../astro/site-context'
+import { slotText } from '../utils/slot-text'
+
+/**
+ * Translates its text: a child that is only text is a dictionary key. Markup children render as they are,
+ * since a slot cannot be taken apart into its text runs.
+ */
+const { t } = siteOf(Astro)
+const html = Astro.slots.has('default') ? await Astro.slots.render('default') : ''
+const text = /<[a-z!/]/i.test(html) ? undefined : await slotText(Astro.slots)
+---
+
+{text !== undefined ? t(text.trim()) : <Fragment set:html={html} />}

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

@@ -0,0 +1,5 @@
+---
+import Callout from './Callout.astro'
+---
+
+<Callout tone="warning"><slot /></Callout>

package/src/docs-shell/components/code-props.ts

@@ -0,0 +1,28 @@
+export declare interface CodeProp {
+  name?: string
+  lang: string
+  ext?: string
+  beautify?: boolean
+  dedent?: boolean | 'block'
+  type?: string
+  number?: boolean
+  preClassName?: string
+  masterCSS?: unknown
+  tabbarClassName?: string
+  /** Accepted for older callers; the bar names the file and nothing else. */
+  showControls?: boolean
+  copyable?: boolean
+  class?: string
+}
+
+export declare interface CodeTab {
+  name?: string
+  lang: string
+  ext?: string
+  beautify?: boolean
+  dedent?: boolean | 'block'
+  type?: string
+  number?: boolean
+  showControls?: boolean
+  code: string
+}

package/src/docs-shell/components/document-types.ts

@@ -0,0 +1,119 @@
+import type { ImageMetadata } from 'astro'
+
+/**
+ * Data shapes of the document components. `.astro` components export only themselves, so data
+ * modules import these types from here.
+ */
+
+/** Markup passed as data: a string, MDX JSX or an Astro template value, rendered with `RenderNode`. */
+export type DocumentMarkup = unknown
+
+export interface DocumentAPIEntry {
+  name: string
+  href: string
+  description: string
+}
+
+export interface DocumentChoice {
+  title: string
+  description: string
+  href: string
+  icon?: DocumentMarkup
+}
+
+export interface DocumentCodeExampleViewProps {
+  title: string
+  /** Named code blocks: their bars carry the part's label and its copy control. */
+  sourceCode?: DocumentMarkup
+  resultCode?: DocumentMarkup
+  resultKind?: 'generated-css'
+  diagnostic?: { severity: 'Warning' | 'Error', rule: string, message: string }
+}
+
+export interface DocumentCodeExampleProps extends Omit<DocumentCodeExampleViewProps, 'sourceCode' | 'resultCode'> {
+  language: string
+  resultLanguage?: string
+  source: string
+  result?: string
+  sourceLabel?: string
+  resultLabel?: string
+}
+
+export interface DocumentFileEntry {
+  name: string
+  description?: string
+  children?: readonly DocumentFileEntry[]
+}
+
+export interface DocumentFileTreeProps {
+  title: string
+  entries: readonly DocumentFileEntry[]
+  caption?: string
+}
+
+export interface DocumentFlowStep {
+  title: string
+  description: string
+}
+
+export interface DocumentFlowProps {
+  title: string
+  steps: readonly DocumentFlowStep[]
+  caption?: string
+}
+
+export interface IllustrationImages {
+  light: ImageMetadata
+  dark: ImageMetadata
+}
+
+export interface DocumentOption {
+  name: string
+  defaultValue?: string
+  description: DocumentMarkup
+}
+
+export interface DocumentParameter {
+  name: string
+  type: string
+  requirement?: string
+  description: DocumentMarkup
+}
+
+export interface DocumentPromptProps {
+  title: string
+  text: string
+}
+
+export interface DocumentValueRow {
+  id: string
+  title: string
+  identifier?: string
+  values: { label: string, value: string }[]
+}
+
+export interface NamespaceUtilityGroup {
+  label: string
+  keys: string[]
+  namespace?: string
+  namespaces?: string[]
+  description?: DocumentMarkup
+}
+
+export interface DocumentationIndexEntry {
+  id: string
+  title: string
+  displayTitle?: string
+  description?: string
+  category: string
+  url: string
+  disabled?: boolean
+  unfinished?: boolean
+}
+
+export interface DocumentationIndexSection {
+  id: string
+  title: string
+  description: string
+  groups: { id?: string; title?: string; entries: DocumentationIndexEntry[] }[]
+}

package/src/docs-shell/components/markdown/Anchor.astro

@@ -0,0 +1,5 @@
+---
+import Link from '../Link.svelte'
+---
+
+<Link {...Astro.props} indicate><slot /></Link>

package/src/docs-shell/components/markdown/Heading2.astro

@@ -0,0 +1,5 @@
+---
+import DocHeading from '../DocHeading.astro'
+---
+
+<DocHeading tagName="h2" {...Astro.props}><slot /></DocHeading>

package/src/docs-shell/components/markdown/Heading3.astro

@@ -0,0 +1,5 @@
+---
+import DocHeading from '../DocHeading.astro'
+---
+
+<DocHeading tagName="h3" {...Astro.props}><slot /></DocHeading>

package/src/docs-shell/components/markdown/Table.astro

@@ -0,0 +1,6 @@
+---
+---
+
+<div class="ui-table">
+  <table {...Astro.props}><slot /></table>
+</div>

package/src/docs-shell/components/markdown-components.ts

@@ -0,0 +1,36 @@
+import '../../styles/system/data.css'
+import Image from './Image.svelte'
+import Do from './Do.astro'
+import DoNot from './DoNot.astro'
+import Info from './Info.astro'
+import InteractingIndicator from './InteractingIndicator.astro'
+import PMAction from './PMAction.astro'
+import Warn from './Warn.astro'
+import InlineCode from './InlineCode.astro'
+import Code from './Code.astro'
+import Anchor from './markdown/Anchor.astro'
+import Heading2 from './markdown/Heading2.astro'
+import Heading3 from './markdown/Heading3.astro'
+import Table from './markdown/Table.astro'
+
+/**
+ * How Markdown renders in MDX. Every MDX module exports these as `components` (see
+ * `docs-shell/remark/markdown-components.js`, which also turns fences, inline code and
+ * marked paragraphs into the `Code`, `InlineCode`, callout and hint elements).
+ */
+export const markdownComponents = {
+  a: Anchor,
+  h2: Heading2,
+  h3: Heading3,
+  img: Image,
+  Image,
+  table: Table,
+  Code,
+  InlineCode,
+  PMAction,
+  Do,
+  DoNot,
+  Info,
+  Warn,
+  InteractingIndicator
+}

package/src/docs-shell/components/page-content-bootstrap.ts

@@ -0,0 +1,115 @@
+import type { PageContentItem } from './page-content.svelte'
+
+const lineSeparator = new RegExp(String.fromCharCode(0x2028), 'g')
+const paragraphSeparator = new RegExp(String.fromCharCode(0x2029), 'g')
+
+function escapeScriptJson(value: unknown) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(lineSeparator, '\\u2028')
+    .replace(paragraphSeparator, '\\u2029')
+}
+
+function pageContentBootstrap(items: Pick<PageContentItem, 'id' | 'level'>[]) {
+  const headingOffset = 110
+  let attempts = 0
+
+  const run = () => {
+    attempts += 1
+    const headings = items
+      .map((item) => document.getElementById(item.id))
+      .filter((heading): heading is HTMLElement => Boolean(heading))
+    const hasPageContentNav = document.querySelector('[data-page-content-nav-id]')
+
+    if (!headings.length || !hasPageContentNav) {
+      if (attempts < 120) {
+        window.requestAnimationFrame(run)
+      }
+      return
+    }
+
+    let currentId = headings[0].id
+    const top = window.scrollY + Math.max(headingOffset, window.innerHeight * 0.3)
+
+    for (const heading of headings) {
+      if (top >= heading.getBoundingClientRect().top + window.scrollY) {
+        currentId = heading.id
+      } else {
+        break
+      }
+    }
+
+    if (window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2) {
+      currentId = headings[headings.length - 1].id
+    }
+
+    const currentIndex = items.findIndex((item) => item.id === currentId)
+    let needsLayoutRetry = false
+    ;(window as any).__pageContentInitialActiveId = currentId
+
+    document.querySelectorAll<HTMLElement>('[data-page-content-nav-id]').forEach((nav) => {
+      const id = nav.dataset.pageContentNavId
+      if (currentId === id) {
+        nav.setAttribute('aria-current', 'location')
+      } else {
+        nav.removeAttribute('aria-current')
+      }
+    })
+
+    const activePageContentNav = Array.from(document.querySelectorAll<HTMLElement>('[data-page-content-nav-id]'))
+      .find((nav) => nav.dataset.pageContentNavId === currentId)
+    const pageContentScroll = activePageContentNav?.closest<HTMLElement>('.ui-toc[data-rail] > ol')
+    if (activePageContentNav && pageContentScroll && window.innerWidth >= 1024) {
+      if (pageContentScroll.offsetHeight && activePageContentNav.offsetHeight) {
+        if (currentIndex <= 0 || activePageContentNav.offsetTop) {
+          pageContentScroll.scrollTo({
+            top: activePageContentNav.offsetTop - pageContentScroll.clientHeight / 3,
+            behavior: 'instant'
+          })
+        } else {
+          needsLayoutRetry = true
+        }
+      } else {
+        needsLayoutRetry = true
+      }
+    }
+
+    const sidebar = document.getElementById('sidebar')
+    const sidebarLinks = Array.from(sidebar?.querySelectorAll<HTMLAnchorElement>('a.ui-nav-link[href]') || [])
+    const activeSidebarLink = sidebar?.querySelector<HTMLElement>('a.ui-nav-link[aria-current]')
+      || sidebarLinks.find((link) => {
+        try {
+          return new URL(link.getAttribute('href') || '', location.href).pathname === location.pathname
+        } catch {
+          return false
+        }
+      })
+    if (sidebar && activeSidebarLink && window.innerWidth >= 768) {
+      const activeSidebarIndex = sidebarLinks.indexOf(activeSidebarLink as HTMLAnchorElement)
+      if (sidebar.offsetHeight && activeSidebarLink.offsetHeight) {
+        if (activeSidebarIndex <= 0 || activeSidebarLink.offsetTop) {
+          sidebar.scrollTo({
+            top: activeSidebarLink.offsetTop + activeSidebarLink.offsetHeight - sidebar.clientHeight / 2,
+            behavior: 'instant'
+          })
+        } else {
+          needsLayoutRetry = true
+        }
+      } else {
+        needsLayoutRetry = true
+      }
+    }
+
+    if (needsLayoutRetry && attempts < 120) {
+      window.requestAnimationFrame(run)
+    }
+  }
+
+  run()
+}
+
+/** The inline script `PageContentBootstrap.astro` writes: it marks the doc-page active state while the document parses, before islands hydrate. */
+export function pageContentBootstrapScript(items: Pick<PageContentItem, 'id' | 'level'>[]) {
+  const serializedItems = escapeScriptJson(items.map(({ id, level }) => ({ id, level })))
+  return `(${pageContentBootstrap.toString()})(${serializedItems});`
+}

package/src/docs-shell/components/page-content.svelte.ts

@@ -0,0 +1,125 @@
+import { getContext, setContext } from 'svelte'
+
+export interface PageContentItem {
+  id: string
+  title: string
+  level: 2 | 3
+}
+
+export interface PageContentState {
+  readonly items: PageContentItem[]
+  readonly currentId: string
+}
+
+declare global {
+  interface Window {
+    __pageContentInitialActiveId?: string
+  }
+}
+
+const headingOffset = 110
+const pageContentKey = Symbol('page-content')
+
+function computeActiveState(items: PageContentItem[]) {
+  const headings = items
+    .map((item) => document.getElementById(item.id))
+    .filter((heading): heading is HTMLElement => Boolean(heading))
+  if (!headings.length) {
+    return { currentId: '' }
+  }
+
+  let currentId = headings[0].id
+  // A section is being read once its heading passes a line a third of the way down the viewport (never above where an
+  // in-page link lands it). Compared in page coordinates: a heading inside a positioned section reports its offsetTop
+  // from that section.
+  const top = window.scrollY + Math.max(headingOffset, window.innerHeight * 0.3)
+
+  for (const heading of headings) {
+    if (top >= heading.getBoundingClientRect().top + window.scrollY) {
+      currentId = heading.id
+    } else {
+      break
+    }
+  }
+
+  // A last section too short to reach the line is the one being read once the page can scroll no further.
+  if (window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2) {
+    currentId = headings[headings.length - 1].id
+  }
+
+  return { currentId }
+}
+
+function applyActiveState({ currentId }: { currentId: string }) {
+  document.querySelectorAll<HTMLElement>('[data-page-content-nav-id]').forEach((nav) => {
+    const id = nav.dataset.pageContentNavId
+    if (currentId === id) {
+      nav.setAttribute('aria-current', 'location')
+    } else {
+      nav.removeAttribute('aria-current')
+    }
+  })
+}
+
+/**
+ * Provides the page's contents and the entry being read to the lists below it (`PageContentProvider.svelte`).
+ * Call during component initialization; `items` is read through a getter so the provider follows its prop.
+ */
+export function providePageContent(getItems: () => PageContentItem[]): PageContentState {
+  let currentId = $state('')
+  const state: PageContentState = {
+    get items() { return getItems() },
+    get currentId() { return currentId }
+  }
+
+  $effect.pre(() => {
+    applyActiveState(computeActiveState(getItems()))
+  })
+
+  $effect(() => {
+    const items = getItems()
+    let animationFrame = 0
+    let initialUpdateTimeout = 0
+
+    const updateCurrentId = () => {
+      animationFrame = 0
+      const activeState = computeActiveState(items)
+
+      applyActiveState(activeState)
+      currentId = activeState.currentId
+    }
+
+    const requestUpdate = () => {
+      if (animationFrame) return
+      animationFrame = window.requestAnimationFrame(updateCurrentId)
+    }
+
+    updateCurrentId()
+    initialUpdateTimeout = window.setTimeout(requestUpdate, 100)
+    document.addEventListener('scroll', requestUpdate, {
+      capture: true,
+      passive: true
+    })
+    window.addEventListener('resize', requestUpdate, { passive: true })
+
+    return () => {
+      document.removeEventListener('scroll', requestUpdate, true)
+      window.removeEventListener('resize', requestUpdate)
+      window.clearTimeout(initialUpdateTimeout)
+      if (animationFrame) {
+        window.cancelAnimationFrame(animationFrame)
+      }
+    }
+  })
+
+  setContext(pageContentKey, state)
+  return state
+}
+
+export function usePageContent() {
+  const context = getContext<PageContentState | undefined>(pageContentKey)
+  if (!context) {
+    throw new Error('usePageContent must be used inside PageContentProvider')
+  }
+  return context
+}

package/src/docs-shell/contexts/search.ts

@@ -0,0 +1,18 @@
+/** The event a search trigger dispatches; `components/SearchDialog.svelte` listens for it. */
+export const openSearchEvent = 'site-search:open'
+
+/** Search triggers live in independent islands; they open the page's single dialog by event. */
+export function openSearch(trigger?: HTMLElement) {
+  window.dispatchEvent(new CustomEvent(openSearchEvent, { detail: { trigger } }))
+}
+
+/** The search trigger's words in the page's language. */
+export function searchLabels(translate: (text: string) => string, locale: string) {
+  const searchPlaceholder = translate('Search ⌘ K …')
+  return {
+    searchPlaceholder,
+    /** The placeholder without its shortcut, which triggers show as a key. */
+    searchText: searchPlaceholder.replace(/\s*⌘\s*K\s*…?$/u, ''),
+    searchLabel: locale === 'tw' ? '搜尋文件' : 'Search documentation',
+  }
+}

package/src/docs-shell/contexts/theme-mode.svelte.ts

@@ -0,0 +1,61 @@
+import { onMount } from 'svelte'
+import ThemeMode from 'theme-mode'
+
+export type ThemePreference = 'light' | 'dark' | 'system' | (string & {})
+
+interface ThemeModeSnapshot {
+  preference?: ThemePreference
+  value?: string
+}
+
+/** Empty until a component mounts, as on the server, so hydration matches the server's markup. */
+const snapshot = $state<ThemeModeSnapshot>({})
+let themeMode: ThemeMode | undefined
+
+/** One page-wide ThemeMode so every island shows and changes the same preference. */
+function getThemeMode() {
+  themeMode ??= new ThemeMode({ preference: 'system' }).init()
+  return themeMode
+}
+
+/**
+ * A theme swap recolors the whole page at once. Without pausing transitions, every element would fade or slide
+ * to its new colors on its own timing, so the swap commits with transitions off and restores them a frame later.
+ */
+function withoutTransitions(change: () => void) {
+  const style = document.createElement('style')
+  style.textContent = '*,*::before,*::after{transition:none!important}'
+  document.head.append(style)
+  change()
+  void document.body.offsetHeight
+  requestAnimationFrame(() => requestAnimationFrame(() => style.remove()))
+}
+
+/** The page's theme preference and resolved mode; call during component initialization. */
+export function useThemeMode() {
+  onMount(() => {
+    const instance = getThemeMode()
+    const update = () => {
+      snapshot.preference = instance.preference
+      snapshot.value = instance.value
+    }
+    update()
+    document.documentElement.addEventListener('themeModeChange', update)
+    document.documentElement.addEventListener('themePreferenceChange', update)
+    return () => {
+      document.documentElement.removeEventListener('themeModeChange', update)
+      document.documentElement.removeEventListener('themePreferenceChange', update)
+    }
+  })
+  return {
+    get value() {
+      return snapshot.value
+    },
+    set preference(preference: ThemePreference | undefined) {
+      if (preference) withoutTransitions(() => { getThemeMode().preference = preference })
+    },
+    get preference() {
+      return snapshot.preference
+    }
+  }
+}

package/src/docs-shell/data/authors.ts

@@ -0,0 +1,17 @@
+import aronImage from '../../public/images/authors/aron.jpg'
+import lolaImage from '../../public/images/authors/lola.jpg'
+import milesImage from '../../public/images/authors/miles.jpg'
+import benseageImage from '../../public/images/authors/benseage.jpg'
+import joyImage from '../../public/images/authors/joy.jpg'
+
+import type { StaticImage } from '../types/StaticImage'
+
+const authors: { name: string, image: StaticImage, url?: string, twitter?: string }[] = [
+  { name: 'Aron', image: aronImage, url: 'https://github.com/1aron', twitter: '@aron1tw' },
+  { name: 'Lola', image: lolaImage, url: 'https://github.com/0lola', twitter: '@0lolatw' },
+  { name: 'Miles', image: milesImage, url: 'https://github.com/0miles', twitter: '@milestw' },
+  { name: 'BenSeage', image: benseageImage },
+  { name: 'Joy', image: joyImage },
+]
+
+export default authors

package/src/docs-shell/data/base-colors.ts

@@ -0,0 +1,29 @@
+export default [
+  'transparent',
+  'current',
+  'black',
+  'white',
+  'stone',
+  'gray',
+  'zinc',
+  'neutral',
+  'slate',
+  'brown',
+  'orange',
+  'amber',
+  'yellow',
+  'lime',
+  'green',
+  'beryl',
+  'teal',
+  'cyan',
+  'sky',
+  'blue',
+  'indigo',
+  'violet',
+  'purple',
+  'fuchsia',
+  'pink',
+  'crimson',
+  'red'
+]