@jaamd/jaad 0.11.0 → 1.0.0

package/src/{components → site/components}/SearchPalette.astro

@@ -1,32 +1,28 @@
 ---
-import { DEFAULT_LOCALE, docsUrls, ui } from '../docs-config.ts'
-import { docsPageHref } from '../urls.ts'
+import { DEFAULT_LOCALE, ui } from '../runtime.ts'
 
 interface Props {
-    /** Whether this page is part of the docs. Off them the palette keeps its
-     *  icon trigger and its shortcut, and searches the default locale. */
-    inDocs?: boolean
-    /** Search covers one locale: the one the reader is in. */
+    /** The search index, of the reader's locale. */
+    indexUrl: string
+    /** The full field on wide screens. Otherwise the palette keeps its icon
+     *  trigger and its shortcut. */
+    prominent?: boolean
     locale?: string
 }
 
-const { inDocs = false, locale = DEFAULT_LOCALE } = Astro.props
-const urls = docsUrls(locale)
+const { indexUrl, prominent = false, locale = DEFAULT_LOCALE } = Astro.props
 const t = ui(locale)
-const base = docsPageHref('', urls)
-const indexUrl = docsPageHref('search-index.json', urls)
 
 const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
 ---
 
 <jaad-search
-    data-in-docs={inDocs ? '' : null}
-    data-base={base}
+    data-prominent={prominent ? '' : null}
     data-index-url={indexUrl}
     data-loading={t('search.loading')}
     data-empty={t('search.empty')}
 >
-    <button data-trigger-desktop hidden={!inDocs} class="jaad-search-trigger" aria-label={t('search.label')}>
+    <button data-trigger-desktop hidden={!prominent} class="jaad-search-trigger" aria-label={t('search.label')}>
         <svg class="jaad-search-trigger-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
             <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d={MAGNIFIER}></path>
         </svg>
@@ -38,7 +34,7 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
 
     <button
         data-trigger-icon
-        class:list={['jaad-icon-button', inDocs && 'jaad-search-trigger-compact']}
+        class:list={['jaad-icon-button', prominent && 'jaad-search-trigger-compact']}
         aria-label={t('search.label')}
     >
         <svg class="jaad-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
@@ -78,6 +74,12 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
                 </kbd>
             </div>
 
+            <div data-filters hidden class="jaad-search-filters" role="group" aria-label={t('search.sections')}>
+                <button type="button" data-filter="" aria-pressed="true" class="jaad-search-filter">
+                    {t('search.all')}
+                </button>
+            </div>
+
             <ul
                 data-results
                 id="search-results"
@@ -106,16 +108,30 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
 
 <script>
     import { navigate } from 'astro:transitions/client'
-    import { scoreItems, getSnippet, splitOnMatches, type SearchItem } from '../utils/search.ts'
+    import {
+        getSnippet,
+        markWords,
+        openingPages,
+        queryTerms,
+        search,
+        type SearchIndex,
+        type SearchPage,
+    } from '../search.ts'
+
+    const EMPTY_INDEX: SearchIndex = { sections: [], pages: [], entries: [] }
 
     class JaadSearch extends HTMLElement {
         #overlay!: HTMLElement
         #input!: HTMLInputElement
+        #filters!: HTMLElement
         #list!: HTMLUListElement
-        #index: SearchItem[] | null = null
-        #request: Promise<SearchItem[]> | null = null
-        #results: SearchItem[] = []
+        #index: SearchIndex | null = null
+        #request: Promise<SearchIndex> | null = null
+        /** The selectable rows, in display order. */
+        #options: { li: HTMLLIElement; href: string }[] = []
         #selected = 0
+        /** The section key results are limited to; empty for all. */
+        #section = ''
         #restoreFocus: HTMLElement | null = null
         #previousOverflow = ''
 
@@ -126,6 +142,7 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
         connectedCallback() {
             this.#overlay = this.querySelector('[data-overlay]')!
             this.#input = this.querySelector('[data-input]')!
+            this.#filters = this.querySelector('[data-filters]')!
             this.#list = this.querySelector('[data-results]')!
 
             if (/Mac|iPod|iPhone|iPad/.test(navigator.userAgent)) {
@@ -141,6 +158,10 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
 
             this.querySelector('[data-backdrop]')!.addEventListener('click', () => this.#setOpen(false))
             this.querySelector('[data-close]')!.addEventListener('click', () => this.#setOpen(false))
+            this.#filters.addEventListener('click', (e) => {
+                const button = (e.target as Element).closest<HTMLButtonElement>('[data-filter]')
+                if (button) this.#filter(button.dataset.filter ?? '')
+            })
 
             this.#input.addEventListener('input', () => this.#render())
             this.#input.addEventListener('keydown', (e) => this.#onInputKey(e))
@@ -159,15 +180,13 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
             const next = (event as Event & { newDocument: Document }).newDocument.querySelector<HTMLElement>(
                 'jaad-search',
             )
-            if (!next) return
-
-            const indexUrl = next.dataset.indexUrl
+            const indexUrl = next?.dataset.indexUrl
             if (indexUrl && indexUrl !== this.dataset.indexUrl) {
                 this.dataset.indexUrl = indexUrl
                 this.#index = null
                 this.#request = null
+                this.#section = ''
             }
-            if (next.dataset.base) this.dataset.base = next.dataset.base
         }
 
         #onGlobalKey = (e: KeyboardEvent) => {
@@ -183,26 +202,30 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
         #onInputKey(e: KeyboardEvent) {
             if (e.key === 'ArrowDown') {
                 e.preventDefault()
-                this.#select(Math.min(this.#selected + 1, this.#results.length - 1))
+                this.#select(Math.min(this.#selected + 1, this.#options.length - 1))
             } else if (e.key === 'ArrowUp') {
                 e.preventDefault()
                 this.#select(Math.max(this.#selected - 1, 0))
-            } else if (e.key === 'Enter' && this.#results[this.#selected]) {
-                this.#go(this.#results[this.#selected].slug)
+            } else if (e.key === 'Enter' && this.#options[this.#selected]) {
+                this.#go(this.#options[this.#selected].href)
             }
         }
 
-        #loadIndex(): Promise<SearchItem[]> {
+        #loadIndex(): Promise<SearchIndex> {
             if (this.#index) return Promise.resolve(this.#index)
             if (!this.#request) {
                 const url = this.dataset.indexUrl ?? '/search-index.json'
                 this.#request = fetch(url)
-                    .then((res) => (res.ok ? res.json() : []))
-                    .then((data: SearchItem[]) => (this.#index = data))
+                    .then((res) => (res.ok ? res.json() : EMPTY_INDEX))
+                    .then((data: SearchIndex) => {
+                        this.#index = data
+                        this.#renderFilters(data)
+                        return data
+                    })
                     .catch(() => {
                         // Drop the failed promise so a later attempt can retry.
                         this.#request = null
-                        return []
+                        return EMPTY_INDEX
                     })
             }
             return this.#request
@@ -226,28 +249,47 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
             }
         }
 
-        #go(slug: string) {
+        #go(href: string) {
             this.#setOpen(false)
-            const base = this.dataset.base ?? '/'
-            const prefix = base === '/' ? '' : base.replace(/\/$/, '')
-            navigate(slug ? `${prefix}/${slug}` : base)
+            navigate(href)
+        }
+
+        /** One button per section, after "All"; none with fewer than two. */
+        #renderFilters(index: SearchIndex) {
+            const [all] = this.#filters.querySelectorAll('[data-filter]')
+            this.#filters.replaceChildren(all)
+            this.#filters.hidden = index.sections.length < 2
+            for (const { key, label } of index.sections) {
+                const button = document.createElement('button')
+                button.type = 'button'
+                button.dataset.filter = key
+                button.className = 'jaad-search-filter'
+                button.textContent = label
+                this.#filters.append(button)
+            }
+            this.#filter(this.#section)
+        }
+
+        #filter(section: string) {
+            this.#section = section
+            for (const button of this.#filters.querySelectorAll<HTMLElement>('[data-filter]')) {
+                button.setAttribute('aria-pressed', String(button.dataset.filter === section))
+            }
+            this.#render()
+            this.#input.focus()
         }
 
         #select(i: number) {
             this.#selected = i
-            this.#input.setAttribute('aria-activedescendant', `search-option-${i}`)
-            ;[...this.#list.children].forEach((li, n) => {
-                const active = n === i
-                li.setAttribute('aria-selected', String(active))
-            })
-            ;(this.#list.children[i] as HTMLElement | undefined)?.scrollIntoView({
-                block: 'nearest',
-            })
+            const option = this.#options[i]
+            if (option) this.#input.setAttribute('aria-activedescendant', option.li.id)
+            this.#options.forEach(({ li }, n) => li.setAttribute('aria-selected', String(n === i)))
+            option?.li.scrollIntoView({ block: 'nearest' })
         }
 
-        #marked(text: string, query: string): DocumentFragment {
+        #marked(text: string, terms: string[]): DocumentFragment {
             const frag = document.createDocumentFragment()
-            for (const part of splitOnMatches(text, query)) {
+            for (const part of markWords(text, terms)) {
                 if (part.match) {
                     const mark = document.createElement('mark')
                     mark.className = 'jaad-search-mark'
@@ -261,8 +303,8 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
         }
 
         #render() {
-            const query = this.#input.value
             this.#list.replaceChildren()
+            this.#options = []
             this.#input.removeAttribute('aria-activedescendant')
 
             if (!this.#index) {
@@ -270,48 +312,87 @@ const MAGNIFIER = 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z'
                 return
             }
 
-            this.#results = scoreItems(this.#index, query)
+            const query = this.#input.value
+            const terms = queryTerms(query)
+            const section = this.#section || undefined
+
+            if (terms.length === 0) {
+                for (const group of openingPages(this.#index, section)) {
+                    if (group.label) this.#list.append(this.#label(group.label))
+                    for (const page of group.pages) this.#option(page.href, this.#pageRow(page, [], ''))
+                }
+            } else {
+                for (const group of search(this.#index, query, section)) {
+                    const snippet = group.intro ? getSnippet(group.intro.text, terms) : ''
+                    this.#option(group.page.href, this.#pageRow(group.page, terms, snippet))
+                    for (const hit of group.hits) {
+                        const li = this.#option(hit.href, this.#row(hit.entry.heading ?? '', terms))
+                        li.classList.add('jaad-search-result-heading')
+                        this.#snippet(li, getSnippet(hit.entry.text, terms), terms)
+                    }
+                }
+            }
 
-            if (this.#results.length === 0) {
+            if (this.#options.length === 0) {
                 this.#list.append(this.#message(`${this.dataset.empty ?? 'No results for'} “${query}”`))
                 return
             }
+            this.#select(0)
+        }
 
-            this.#results.forEach((item, i) => {
-                const li = document.createElement('li')
-                li.id = `search-option-${i}`
-                li.setAttribute('role', 'option')
-                li.className = 'jaad-search-result'
-                li.addEventListener('click', () => this.#go(item.slug))
-                li.addEventListener('mouseenter', () => this.#select(i))
-
-                const head = document.createElement('div')
-                head.className = 'jaad-search-result-head'
-                const title = document.createElement('span')
-                title.className = 'jaad-search-result-title'
-                title.append(this.#marked(item.title, query))
-                head.append(title)
-
-                if (item.chapter) {
-                    const badge = document.createElement('span')
-                    badge.className = 'jaad-search-result-badge'
-                    badge.textContent = item.chapter
-                    head.append(badge)
-                }
-                li.append(head)
-
-                const snippet = getSnippet(item.body, query)
-                if (snippet) {
-                    const p = document.createElement('p')
-                    p.className = 'jaad-search-result-snippet'
-                    p.append(this.#marked(snippet, query))
-                    li.append(p)
-                }
+        /** A selectable row: the list item, given its content. */
+        #option(href: string, content: HTMLElement): HTMLLIElement {
+            const i = this.#options.length
+            const li = document.createElement('li')
+            li.id = `search-option-${i}`
+            li.setAttribute('role', 'option')
+            li.className = 'jaad-search-result'
+            li.addEventListener('click', () => this.#go(href))
+            li.addEventListener('mouseenter', () => this.#select(i))
+            li.append(content)
+            this.#list.append(li)
+            this.#options.push({ li, href })
+            return li
+        }
 
-                this.#list.append(li)
-            })
+        #row(title: string, terms: string[]): HTMLElement {
+            const head = document.createElement('div')
+            head.className = 'jaad-search-result-head'
+            const span = document.createElement('span')
+            span.className = 'jaad-search-result-title'
+            span.append(this.#marked(title, terms))
+            head.append(span)
+            return head
+        }
 
-            this.#select(0)
+        #pageRow(page: SearchPage, terms: string[], snippet: string): HTMLElement {
+            const fragment = document.createElement('div')
+            const head = this.#row(page.title, terms)
+            if (page.chapter) {
+                const badge = document.createElement('span')
+                badge.className = 'jaad-search-result-badge'
+                badge.textContent = page.chapter
+                head.append(badge)
+            }
+            fragment.append(head)
+            this.#snippet(fragment, snippet, terms)
+            return fragment
+        }
+
+        #snippet(parent: HTMLElement, text: string, terms: string[]) {
+            if (!text) return
+            const p = document.createElement('p')
+            p.className = 'jaad-search-result-snippet'
+            p.append(this.#marked(text, terms))
+            parent.append(p)
+        }
+
+        #label(text: string): HTMLLIElement {
+            const li = document.createElement('li')
+            li.setAttribute('role', 'presentation')
+            li.className = 'jaad-search-group'
+            li.textContent = text
+            return li
         }
 
         #message(text: string): HTMLLIElement {

package/src/{components → site/components}/ThemeSwitcher.astro

@@ -1,6 +1,6 @@
 ---
 // The theme class and the icon are already set in <head>; only the click is JS.
-import { ui } from '../docs-config.ts'
+import { ui } from '../runtime.ts'
 
 const t = ui(Astro.props.locale)
 ---

package/src/site/config.ts

@@ -0,0 +1,149 @@
+import type { Locale } from './locales.ts'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { z } from 'astro/zod'
+import { inferDescription, type RepoInfo } from './infer.ts'
+import { PRESETS, PRESET_NAMES, isPreset } from './themes.ts'
+
+const publicUrl = (field: string, example: string) =>
+    z.string().refine((v) => v.startsWith('/') || /^https?:\/\//.test(v), {
+        message: `${field} must be a public url, such as "${example}"`,
+    })
+
+/** The options of the site around the pages: identity, header, footer, head and theme. */
+export const siteConfigShape = {
+    title: z.string(),
+    description: z.string().optional(),
+    lang: z.string().default('en'),
+    logo: publicUrl('logo', '/logo.svg').optional(),
+    /** Where the site name in the header leads: the site root, or another site. */
+    homeLink: z.string().default('/'),
+
+    social: z
+        .record(
+            z.string(),
+            z.union([
+                z.string(),
+                z.object({
+                    href: z.string(),
+                    label: z.string().optional(),
+                    svg: z.string().optional(),
+                }),
+            ]),
+        )
+        .default({}),
+    nav: z.array(z.object({ label: z.string(), href: z.string() })).default([]),
+    footer: z
+        .union([z.string(), z.literal(false)], {
+            error:
+                'footer is one line of text, or false to remove it. ' +
+                'The message/copyright pair is gone: write them as a single string, ' +
+                'e.g. "MIT Licensed · © 2026 Me · :credit".',
+        })
+        .optional(),
+
+    head: z
+        .array(
+            z.object({
+                tag: z.string(),
+                attrs: z.record(z.string(), z.union([z.string(), z.boolean()])).optional(),
+                content: z.string().optional(),
+            }),
+        )
+        .default([]),
+    ogImage: z.union([publicUrl('ogImage', '/og-image.png'), z.literal(false)]).optional(),
+
+    theme: z
+        .union([
+            z.string().refine(isPreset, {
+                message: `unknown theme; available: ${PRESET_NAMES.join(', ')}`,
+            }),
+            z.object({ light: z.string(), dark: z.string() }),
+        ])
+        .default('default'),
+
+    appearance: z
+        .enum(['auto', 'light', 'dark'], {
+            error: 'unknown appearance; available: auto, light, dark',
+        })
+        .default('auto'),
+
+    /** Registers Tailwind (the site's own install) and exposes JAAD's tokens to it. */
+    tailwind: z.boolean().default(false),
+
+    /** Per-locale overrides for JAAD's bundled interface strings. */
+    ui: z.record(z.string(), z.record(z.string(), z.string())).default({}),
+}
+
+const siteConfigSchema = z.object(siteConfigShape)
+
+export type SiteConfig = z.output<typeof siteConfigSchema>
+
+/** The site options plus what the project could tell. Inferred fields are null
+ *  when unavailable. */
+export interface SiteResolvedConfig extends SiteConfig {
+    /** What jaamd gets for code blocks. */
+    shiki: string | { light: string; dark: string }
+    repoUrl: string | null
+    favicon: string | null
+    /** Explicit, inferred from public/, or false when no valid image exists. */
+    ogImage: string | false
+    /** Empty when the site is not localised. */
+    locales: Locale[]
+    /** `lang` when the site is not localised. */
+    defaultLocale: string
+}
+
+const FAVICONS = ['favicon.svg', 'favicon.ico', 'favicon.png']
+const OG_IMAGES = ['og-image.png', 'og-image.jpg', 'og-image.jpeg', 'og-image.webp']
+
+function findPublicAsset(cwd: string, candidates: string[]): string | null {
+    for (const name of candidates) {
+        if (existsSync(join(cwd, 'public', name))) return `/${name}`
+    }
+    return null
+}
+
+/** The fields the site derives from its options and the project. */
+export function resolveSiteConfig(
+    config: SiteConfig,
+    repo: RepoInfo | null,
+    cwd: string,
+): Pick<SiteResolvedConfig, 'description' | 'repoUrl' | 'favicon' | 'ogImage' | 'shiki'> {
+    return {
+        description: config.description ?? inferDescription(cwd) ?? undefined,
+        repoUrl: repo?.url ?? null,
+        favicon: findPublicAsset(cwd, FAVICONS),
+        ogImage: config.ogImage ?? findPublicAsset(cwd, OG_IMAGES) ?? false,
+        shiki: typeof config.theme === 'string' ? PRESETS[config.theme].shiki : config.theme,
+    }
+}
+
+const requireFrom = createRequire(import.meta.url)
+
+const styleInPackage = (name: string) => fileURLToPath(new URL(`./styles/${name}`, import.meta.url))
+
+/** Absolute paths, kept off the resolved config, which gets serialised. */
+export function resolveStylesheets(
+    config: SiteConfig,
+    cwd: string = process.cwd(),
+): {
+    user: string | null
+    theme: string | null
+    bridge: string
+    tailwind: string | null
+} {
+    const userCss = join(cwd, 'src', 'jaad.css')
+    const slug = typeof config.theme === 'string' ? PRESETS[config.theme].theme : null
+
+    return {
+        user: existsSync(userCss) ? userCss : null,
+        // Resolved through JAAMD's export map rather than by path.
+        theme: slug ? requireFrom.resolve(`@jaamd/astro/themes/${slug}.css`) : null,
+        // A preset supplies the palette, so the colours travel the other way.
+        bridge: styleInPackage(slug ? 'jaamd-reverse.css' : 'jaamd-forward.css'),
+        tailwind: config.tailwind ? styleInPackage('tailwind.css') : null,
+    }
+}

package/src/{infer.ts → site/infer.ts}

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, posix } from 'node:path'
 
 const git = (args: string[], cwd: string): string | null => {
     try {
@@ -52,8 +52,8 @@ export function inferRepo(cwd: string = process.cwd()): RepoInfo | null {
 /** Ends in a slash. `docsDir` resolves against the repository root, not the
  *  Astro project, so a site in a subdirectory still links correctly. */
 export function editBaseFrom(repo: RepoInfo, docsDir: string): string {
-    const dir = docsDir.replace(/^\.\//, '').replace(/\/$/, '')
-    const path = `${repo.prefix}${dir}`.replace(/^\/+/, '')
+    // Normalised: a section can sit outside the project, as `../packages/x/docs`.
+    const path = posix.normalize(`${repo.prefix}${docsDir}`).replace(/^\/+|\/+$/g, '')
     return `${repo.url}/edit/${repo.branch}/${path}/`
 }
 

package/src/site/integration.ts

@@ -0,0 +1,59 @@
+import type { SiteResolvedConfig } from './config.ts'
+import type { SiteStylesheets } from './virtual.ts'
+import type { AstroIntegration, AstroUserConfig } from 'astro'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { fonts } from './fonts.ts'
+import { siteVirtualPlugin } from './virtual.ts'
+
+type SetupParams = Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0]
+type VitePlugins = NonNullable<NonNullable<AstroUserConfig['vite']>['plugins']>
+
+const NOT_INSTALLED = new Set(['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'])
+
+/** The site's own `@tailwindcss/vite`, unless it already registered one. */
+export function loadTailwindPlugin(root: string, registered: VitePlugins | undefined): VitePlugins {
+    const plugins = ([registered] as unknown[]).flat(Infinity) as ({
+        name?: string
+    } | null)[]
+    if (plugins.some((p) => p?.name?.startsWith('@tailwindcss/vite'))) return []
+
+    const load = createRequire(join(root, 'package.json'))
+    let tailwindcss: () => VitePlugins
+    try {
+        load.resolve('tailwindcss/package.json')
+        ;({ default: tailwindcss } = load('@tailwindcss/vite') as {
+            default: () => VitePlugins
+        })
+    } catch (error) {
+        if (!NOT_INSTALLED.has((error as { code?: string }).code ?? '')) throw error
+        throw new Error(
+            'jaad: `tailwind: true` needs Tailwind in your project:\n  npm i -D tailwindcss @tailwindcss/vite',
+            { cause: error },
+        )
+    }
+    return tailwindcss()
+}
+
+/** The virtual modules, Tailwind when asked for, and the fonts. `config` is
+ *  what `virtual:jaad/config` serves. */
+export function setupSite(
+    { config: astroConfig, updateConfig }: SetupParams,
+    config: SiteResolvedConfig,
+    stylesheets: SiteStylesheets,
+): void {
+    updateConfig({
+        vite: {
+            plugins: [
+                siteVirtualPlugin(config, stylesheets),
+                ...(config.tailwind
+                    ? [loadTailwindPlugin(fileURLToPath(astroConfig.root), astroConfig.vite.plugins)]
+                    : []),
+            ],
+            // Package .astro sources must reach the Astro compiler.
+            ssr: { noExternal: ['@jaamd/jaad'] },
+        },
+        fonts,
+    })
+}

package/src/{layouts/Page.astro → site/layouts/Shell.astro}

@@ -1,9 +1,10 @@
 ---
+import type { ComponentProps } from 'astro/types'
 import config from 'virtual:jaad/config'
 import Footer from '../components/Footer.astro'
 import Head from '../components/Head.astro'
 import Header from '../components/Header.astro'
-import '../../dist/jaad.css'
+import '../../../dist/jaad.css'
 import 'virtual:jaad/theme.css'
 import 'virtual:jaad/bridge.css'
 import 'virtual:jaad/user.css'
@@ -15,9 +16,11 @@ interface Props {
     bare?: boolean
     /** Added to the body. */
     class?: string
+    /** What the header offers: translations and search. */
+    header: ComponentProps<typeof Header>
 }
 
-const { title, description, bare = false, class: className } = Astro.props
+const { title, description, bare = false, class: className, header } = Astro.props
 
 const pageTitle = title ? `${title} | ${config.title}` : config.title
 const pageDescription = description ?? config.description ?? config.title
@@ -29,7 +32,7 @@ const pageDescription = description ?? config.description ?? config.title
         <Head title={pageTitle} description={pageDescription} />
     </head>
     <body class:list={['jaad-body', className]}>
-        <Header />
+        <Header {...header} />
         <main class={bare ? 'jaad-main-bare' : 'jaad-main'}>
             <slot />
         </main>

package/src/{locales.ts → site/locales.ts}

@@ -1,4 +1,4 @@
-import { ucfirst } from './utils/helpers.ts'
+import { ucfirst } from './helpers.ts'
 
 /** ISO 639-1. A three-letter directory such as `api` is never a locale. */
 const LANGUAGES = new Set(
@@ -119,6 +119,14 @@ export interface Locale {
     flag: string | null
 }
 
+/** Where the page a reader is on lives in one locale. */
+export interface LocaleAlternate {
+    locale: Locale
+    href: string
+    /** False when this locale has no such page and the href is its opening one. */
+    translated: boolean
+}
+
 export function isLocale(segment: string): boolean {
     const match = LOCALE_RE.exec(segment.toLowerCase())
     return match !== null && LANGUAGES.has(match[1])