@master/internal-site 0.0.0-stage → 0.1.1

package/src/docs-shell/scripts/document-anchor.ts

@@ -0,0 +1,57 @@
+/** Keep an initial article fragment in view while previews and fonts settle. */
+export {}
+
+const fragment = location.hash
+let target: HTMLElement | null = null
+try { target = document.getElementById(decodeURIComponent(fragment.slice(1))) } catch { /* A malformed fragment has no target. */ }
+const article = target?.closest<HTMLElement>('main article.ui-prose')
+const navigation = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined
+
+// Reload and history navigation keep the browser's own saved reading position.
+if (navigation?.type === 'navigate' && fragment && target && article) {
+  const destination = target
+  const controller = new AbortController()
+  let frame = 0
+  let aligned = false
+  let expectedScroll = scrollY
+  const rootStyle = document.documentElement.style
+  const previousAnchoring = rootStyle.getPropertyValue('overflow-anchor')
+  const previousPriority = rootStyle.getPropertyPriority('overflow-anchor')
+  // One mechanism owns the initial position; native anchoring resumes on reader intent.
+  rootStyle.setProperty('overflow-anchor', 'none')
+
+  const stop = () => {
+    controller.abort()
+    observer.disconnect()
+    cancelAnimationFrame(frame)
+    if (previousAnchoring) rootStyle.setProperty('overflow-anchor', previousAnchoring, previousPriority)
+    else rootStyle.removeProperty('overflow-anchor')
+  }
+  const margin = () => parseFloat(getComputedStyle(destination).scrollMarginTop) || 0
+  const align = () => {
+    frame = 0
+    if (controller.signal.aborted) return
+    if (!destination.isConnected || location.hash !== fragment) return stop()
+    // Native fragment navigation opens containing disclosures; preserve that behavior.
+    if (destination.closest('details:not([open])')) return
+    const offset = destination.getBoundingClientRect().top - margin()
+    if (Math.abs(offset) > 1) scrollBy({ top: offset, behavior: 'instant' })
+    expectedScroll = scrollY
+    aligned = true
+  }
+  const schedule = () => {
+    if (!frame && !controller.signal.aborted) frame = requestAnimationFrame(align)
+  }
+  const observer = new ResizeObserver(schedule)
+  observer.observe(article)
+  document.fonts.ready.then(schedule)
+
+  // Reader intent ends stabilization, including assistive or scripted scrolling.
+  for (const event of ['wheel', 'touchstart', 'pointerdown', 'keydown', 'hashchange', 'pagehide']) {
+    window.addEventListener(event, stop, { once: true, passive: true, signal: controller.signal })
+  }
+  window.addEventListener('scroll', () => {
+    if (aligned && Math.abs(scrollY - expectedScroll) > 1
+      && Math.abs(destination.getBoundingClientRect().top - margin()) > 2) stop()
+  }, { passive: true, signal: controller.signal })
+}

package/src/docs-shell/scripts/document.ts

@@ -0,0 +1,47 @@
+import { anchor } from '../utils/anchor'
+import { snackbar } from '../utils/snackbar'
+import './document-anchor'
+
+function isPlainClick(event: MouseEvent) {
+  return event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey
+}
+
+// Static markup has no component handlers; these delegated behaviors replace them.
+document.addEventListener('click', (event) => {
+  if (!(event.target instanceof Element) || !isPlainClick(event)) return
+  const heading = event.target.closest<HTMLElement>('[data-doc-heading][id]')
+  if (heading) {
+    const link = location.origin + location.pathname + '#' + heading.id
+    navigator.clipboard?.writeText(link).then(() => snackbar('Link copied <b>' + link + '</b>'), () => {})
+  }
+  if (event.defaultPrevented) return
+  const hashLink = event.target.closest<HTMLAnchorElement>('a[href^="#"]')
+  const id = hashLink && decodeURIComponent(hashLink.getAttribute('href')!.slice(1))
+  if (id && document.getElementById(id)) {
+    event.preventDefault()
+    const contents = hashLink?.closest<HTMLDetailsElement>('[data-contents-disclosure]')
+    if (contents) contents.open = false
+    anchor(id, { offset: 110 })
+  }
+})
+
+// Give bounded inline previews the same horizontal keys in every browser.
+document.addEventListener('keydown', event => {
+  if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return
+  const element = event.target
+  if (!(element instanceof HTMLElement) || !element.matches('[data-preview-scroll]')) return
+  if ((event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') || element.scrollWidth <= element.clientWidth) return
+  event.preventDefault()
+  element.scrollBy({ left: event.key === 'ArrowRight' ? 40 : -40, behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth' })
+})
+
+// A table wider than its column scrolls sideways; only then does it take a tab stop, so keyboard users can scroll it.
+// Tables inside islands are left to their components: changing their markup before hydration breaks it.
+const tableSizes = new ResizeObserver(entries => {
+  for (const { target } of entries) {
+    const table = target as HTMLElement
+    if (table.scrollWidth > table.clientWidth + 1) table.tabIndex = 0
+    else table.removeAttribute('tabindex')
+  }
+})
+document.querySelectorAll<HTMLElement>('.ui-table:not([tabindex])').forEach(table => { if (!table.closest('site-island')) tableSizes.observe(table) })

package/src/docs-shell/site.ts

@@ -0,0 +1,67 @@
+import { getContext } from 'svelte'
+export type SiteLocale = string
+
+/** What every page knows about where it is; `astro/site-context` derives it from the URL. */
+export interface SiteContextValue {
+  locale: SiteLocale
+  /** Canonical pathname without the default locale prefix. */
+  pathname: string
+  translations: Record<string, string>
+  i18n: Omit<SiteI18n, 'translations'>
+}
+
+export interface SiteI18n {
+  translations: Record<string, string>
+  defaultLocale: string
+  locales: readonly string[]
+  localizablePathnameRoots: string[]
+  hreflangOfLocale: Record<string, string>
+  nameOfLocale: Record<string, string>
+}
+
+export interface Site extends SiteContextValue {
+  i18n: SiteI18n
+  /** Translate a dictionary key; unknown keys read as themselves. */
+  t(text: any): string
+}
+
+/** The Svelte renderer provides the page's site context under this key. */
+export const siteContextKey = 'master:site'
+/** Document.astro serializes the site context into this element for client islands. */
+export const siteContextElementId = 'site-context'
+
+const sites = new WeakMap<SiteContextValue, Site>()
+
+export function createSite(value: SiteContextValue): Site {
+  let site = sites.get(value)
+  if (!site) {
+    const { translations } = value
+    site = {
+      ...value,
+      i18n: { ...value.i18n, translations },
+      t: (text: any) => translations[text || ''] || text
+    }
+    sites.set(value, site)
+  }
+  return site
+}
+
+let clientSite: Site | undefined
+
+/** Read the context Document.astro serializes for client islands. */
+export function readSiteContext(): SiteContextValue {
+  const element = document.getElementById(siteContextElementId)
+  if (!element?.textContent) throw new Error(`Missing #${siteContextElementId}`)
+  return JSON.parse(element.textContent)
+}
+
+/**
+ * The current page's site for Svelte components. Call it during component initialization:
+ * the server renderer provides it as context, and hydrated islands read the page's serialized copy.
+ */
+export function getSite(): Site {
+  const value = getContext<SiteContextValue | undefined>(siteContextKey)
+  if (value) return createSite(value)
+  if (typeof document === 'undefined') throw new Error('getSite() must run inside a component rendered by the site')
+  return clientSite ??= createSite(readSiteContext())
+}

package/src/docs-shell/types/IllustrationImages.ts

@@ -0,0 +1,2 @@
+import type { ImageMetadata } from 'astro'
+export interface IllustrationImages { light: ImageMetadata; dark: ImageMetadata }

package/src/docs-shell/types/Metadata.ts

@@ -0,0 +1,17 @@
+export declare type MetadataTitle = string | { absolute: string } | { default: string, template?: string }
+
+/** Page metadata in the shape `docs-shell/utils/head` renders. */
+export declare type Metadata = {
+  title?: MetadataTitle
+  description?: string
+  category?: string
+  robots?: string | { index?: boolean, follow?: boolean }
+  alternates?: { canonical?: string }
+  openGraph?: { title?: string, description?: string, siteName?: string, images?: string | string[] }
+  twitter?: { card?: string, site?: string, creator?: string, title?: string, description?: string, images?: string | string[] }
+  fileURL: string
+  [key: string]: any
+}
+
+/** `define()` output: the canonical pathname and the repository path of the page content. */
+export declare type DefinedMetadata = Omit<Metadata, 'fileURL'> & { pathname: string, sourcePath: string }

package/src/docs-shell/types/Props.ts

@@ -0,0 +1,9 @@
+export interface PageParams {
+  locale: string
+  [key: string]: any
+}
+
+export interface Props {
+  params: PageParams
+  children?: any
+}

package/src/docs-shell/types/StaticImage.ts

@@ -0,0 +1,6 @@
+/** Static image imports resolve to Astro image metadata. */
+export interface StaticImage {
+  src: string
+  width: number
+  height: number
+}

package/src/docs-shell/uses/use-selected-preview-syntax.svelte.ts

@@ -0,0 +1,16 @@
+/** The preview syntax chosen anywhere on the page (`change:preview-syntax`); call during component initialization. */
+export default function useSelectedPreviewSyntax(defaultValue: string) {
+  let previewSyntax = $state(defaultValue)
+  $effect(() => {
+    const onChange = (event: any) => {
+      previewSyntax = event.detail
+    }
+    window.addEventListener('change:preview-syntax', onChange, { passive: true })
+    return () => window.removeEventListener('change:preview-syntax', onChange)
+  })
+  return {
+    get current() {
+      return previewSyntax
+    }
+  }
+}

package/src/docs-shell/utils/anchor.ts

@@ -0,0 +1,24 @@
+export function anchor(id: string, options?: { offset?: number; still?: boolean }) {
+  const element = document.getElementById(id)
+  if (!element) {
+    return
+  }
+  for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+    if (parent instanceof HTMLDetailsElement) parent.open = true
+  }
+  const hadTabIndex = element.hasAttribute('tabindex')
+  if (!hadTabIndex) element.setAttribute('tabindex', '-1')
+  element.focus({ preventScroll: true })
+  if (!hadTabIndex) element.addEventListener('blur', () => element.removeAttribute('tabindex'), { once: true })
+  const elementPosition = (document.documentElement.scrollTop || document.body.scrollTop) + element.getBoundingClientRect().top
+  const offsetPosition = elementPosition - (options?.offset ?? 0)
+  history.pushState({}, '', window.location.pathname + window.location.search + '#' + id)
+  if (options?.still) {
+    document.body.scrollTop = document.documentElement.scrollTop = offsetPosition
+  } else {
+    window.scrollTo({
+      top: offsetPosition,
+      behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth'
+    })
+  }
+}

package/src/docs-shell/utils/beautify-css.ts

@@ -0,0 +1,14 @@
+// @ts-ignore
+import { css_beautify } from 'js-beautify/js/lib/beautify-css'
+
+/** Comparisons in a query prelude; js-beautify drops the space after `>=`, `<=`, `<` and `>`. */
+const queryPrelude = /^(\s*@(?:media|container|custom-media)\b)([^{;\n]*)/gm
+
+export function beautifyCSS(text: string) {
+  return css_beautify(text.replace(/@(media|container|supports|layer)\(/g,'@$1 ('), {
+    newline_between_rules: true,
+    indent_size: 2,
+    end_with_newline: true,
+    space_around_combinator: true
+  }).replace(queryPrelude, (_match: string, keyword: string, prelude: string) => keyword + prelude.replace(/\([^()]*\)/g, group => group.replace(/\s*(<=|>=|<|>|=)\s*/g, ' $1 ')))
+}

package/src/docs-shell/utils/beautify-html.ts

@@ -0,0 +1,12 @@
+
+// @ts-ignore
+import { prettyPrint } from 'html'
+
+export function beautifyHTML(text: string) {
+  return prettyPrint(text, {
+    unformatted: ['code', 'pre', 'em', 'strong'],
+    indent_size: 2,
+    max_char: 0
+  })
+    .replace(/(\s[a-zA-Z-]+)=""/g, '$1')
+}

package/src/docs-shell/utils/beautify-js.ts

@@ -0,0 +1,9 @@
+// @ts-ignore
+import { js_beautify } from 'js-beautify/js/lib/beautify'
+
+export default function beautifyJS(text: string) {
+  return js_beautify(text, {
+    indent_size: 2,
+    end_with_newline: true
+  })
+}

package/src/docs-shell/utils/create-highlighter.ts

@@ -0,0 +1,50 @@
+import { createHighlighterCore, type LanguageRegistration } from 'shiki/core'
+import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
+import syntaxTheme from './syntax-theme'
+import cssModernLanguages from './css-modern-grammar'
+
+/**
+ * Every language loads at once, so embedded grammars always resolve. Lazy embedding would make Shiki reload
+ * a grammar such as Vue for each lazily embedded language, and the reloaded grammar loses its injections.
+ */
+async function eager(language: Promise<{ default: LanguageRegistration[] }>) {
+  return (await language).default.map(({ embeddedLangsLazy: _lazy, ...registration }) => ({
+    ...registration,
+    // Vue's directive and interpolation grammars still target its former `source.vue` root scope.
+    injectTo: registration.injectTo?.includes('source.vue') ? [...registration.injectTo, 'text.html.vue'] : registration.injectTo
+  }))
+}
+
+export default function createHighlighter(languages: LanguageRegistration[] = []) {
+  return createHighlighterCore({
+    langs: [
+      ...[
+        import('@shikijs/langs/html'),
+        import('@shikijs/langs/javascript'),
+        import('@shikijs/langs/typescript'),
+        import('@shikijs/langs/jsx'),
+        import('@shikijs/langs/tsx'),
+        import('@shikijs/langs/css'),
+        import('@shikijs/langs/scss'),
+        import('@shikijs/langs/json'),
+        import('@shikijs/langs/vue'),
+        import('@shikijs/langs/svelte'),
+        import('@shikijs/langs/astro'),
+        import('@shikijs/langs/markdown'),
+        import('@shikijs/langs/mdx'),
+        import('@shikijs/langs/bash'),
+        import('@shikijs/langs/angular-html'),
+        import('@shikijs/langs/toml'),
+        import('@shikijs/langs/erb'),
+        import('@shikijs/langs/liquid'),
+        import('@shikijs/langs/php')
+      ].map(eager),
+      ...cssModernLanguages,
+      ...languages
+    ],
+    themes: [syntaxTheme],
+    engine: createJavaScriptRegexEngine(),
+  })
+}
+
+export const theme = syntaxTheme.name