@jaamd/jaad 0.0.0-stage → 1.0.0-rc.1

package/src/site/locales.ts

@@ -0,0 +1,199 @@
+import { ucfirst } from './helpers.ts'
+
+/** ISO 639-1. A three-letter directory such as `api` is never a locale. */
+const LANGUAGES = new Set(
+    (
+        'aa ab ae af ak am an ar as av ay az ba be bg bi bm bn bo br bs ca ce ch co ' +
+        'cr cs cu cv cy da de dv dz ee el en eo es et eu fa ff fi fj fo fr fy ga gd ' +
+        'gl gn gu gv ha he hi ho hr ht hu hy hz ia id ie ig ii ik io is it iu ja jv ' +
+        'ka kg ki kj kk kl km kn ko kr ks ku kv kw ky la lb lg li ln lo lt lu lv mg ' +
+        'mh mi mk ml mn mr ms mt my na nb nd ne ng nl nn no nr nv ny oc oj om or os ' +
+        'pa pi pl ps pt qu rm rn ro ru rw sa sc sd se sg si sk sl sm sn so sq sr ss ' +
+        'st su sv sw ta te tg th ti tk tl tn to tr ts tt tw ty ug uk ur uz ve vi vo ' +
+        'wa wo xh yi yo za zh zu'
+    ).split(' '),
+)
+
+/** Region for a language that does not name one. Listed, never derived. */
+const LANGUAGE_REGION: Record<string, string> = {
+    af: 'ZA',
+    am: 'ET',
+    ar: 'SA',
+    az: 'AZ',
+    be: 'BY',
+    bg: 'BG',
+    bn: 'BD',
+    bs: 'BA',
+    ca: 'ES',
+    cs: 'CZ',
+    cy: 'GB',
+    da: 'DK',
+    de: 'DE',
+    el: 'GR',
+    en: 'GB',
+    es: 'ES',
+    et: 'EE',
+    eu: 'ES',
+    fa: 'IR',
+    fi: 'FI',
+    fr: 'FR',
+    ga: 'IE',
+    gd: 'GB',
+    gl: 'ES',
+    gu: 'IN',
+    ha: 'NG',
+    he: 'IL',
+    hi: 'IN',
+    hr: 'HR',
+    hu: 'HU',
+    hy: 'AM',
+    id: 'ID',
+    ig: 'NG',
+    is: 'IS',
+    it: 'IT',
+    ja: 'JP',
+    jv: 'ID',
+    ka: 'GE',
+    kk: 'KZ',
+    km: 'KH',
+    kn: 'IN',
+    ko: 'KR',
+    ky: 'KG',
+    lo: 'LA',
+    lt: 'LT',
+    lv: 'LV',
+    mk: 'MK',
+    ml: 'IN',
+    mn: 'MN',
+    mr: 'IN',
+    ms: 'MY',
+    mt: 'MT',
+    my: 'MM',
+    nb: 'NO',
+    ne: 'NP',
+    nl: 'NL',
+    nn: 'NO',
+    no: 'NO',
+    pa: 'IN',
+    pl: 'PL',
+    ps: 'AF',
+    pt: 'PT',
+    ro: 'RO',
+    ru: 'RU',
+    si: 'LK',
+    sk: 'SK',
+    sl: 'SI',
+    so: 'SO',
+    sq: 'AL',
+    sr: 'RS',
+    su: 'ID',
+    sv: 'SE',
+    sw: 'TZ',
+    ta: 'IN',
+    te: 'IN',
+    tg: 'TJ',
+    th: 'TH',
+    tk: 'TM',
+    tl: 'PH',
+    tr: 'TR',
+    uk: 'UA',
+    ur: 'PK',
+    uz: 'UZ',
+    vi: 'VN',
+    yo: 'NG',
+    zh: 'CN',
+    zu: 'ZA',
+}
+
+/** language[-Script][-REGION], lowercased: ids arrive slugged from the loader. */
+const LOCALE_RE = /^([a-z]{2})(?:-([a-z]{4}))?(?:-([a-z]{2}))?$/
+
+export interface Locale {
+    /** Lowercased directory name, and the URL segment. */
+    code: string
+    /** BCP-47, for `lang` and `hreflang`. */
+    tag: string
+    /** Native name, for the switcher menu. */
+    name: string
+    /** Emoji, or null for a language with no listed region. */
+    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])
+}
+
+/** "pt-br" becomes "pt-BR", "zh-hans" becomes "zh-Hans". */
+export function localeTag(code: string): string {
+    const match = LOCALE_RE.exec(code.toLowerCase())
+    if (!match) return code
+    const [, language, script, region] = match
+    return [language, script && ucfirst(script), region && region.toUpperCase()].filter(Boolean).join('-')
+}
+
+function localeName(tag: string): string {
+    try {
+        const names = new Intl.DisplayNames([tag], { type: 'language' })
+        return ucfirst(names.of(tag) ?? tag)
+    } catch {
+        return tag
+    }
+}
+
+/** Regional indicators, A at U+1F1E6. */
+function localeFlag(code: string): string | null {
+    const match = LOCALE_RE.exec(code.toLowerCase())
+    if (!match) return null
+    // A group that did not participate is undefined, whatever the type says.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const region = match[3]?.toUpperCase() ?? LANGUAGE_REGION[match[1]]
+    if (!region) return null
+    return String.fromCodePoint(...Array.from(region, (letter) => 0x1f1e6 + letter.charCodeAt(0) - 65))
+}
+
+/** Open Graph wants language_TERRITORY, not a BCP-47 tag. The territory comes
+ *  from the code when it names one, and from LANGUAGE_REGION otherwise. */
+export function openGraphLocale(code: string): string {
+    const match = LOCALE_RE.exec(code.toLowerCase())
+    if (!match) return code
+
+    const language = match[1]
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const region = match[3]?.toUpperCase() ?? LANGUAGE_REGION[language]
+    return region ? `${language}_${region}` : language
+}
+
+export function describeLocale(code: string): Locale {
+    const tag = localeTag(code)
+    return { code, tag, name: localeName(tag), flag: localeFlag(code) }
+}
+
+/** Empty for the locale that owns the unprefixed urls. */
+export function localeSegment(locale?: string, defaultLocale?: string): string {
+    return !locale || locale === defaultLocale ? '' : locale
+}
+
+/** The segment a generated slug carries, with its separator. */
+export function localePrefix(locale?: string, defaultLocale?: string): string {
+    const segment = localeSegment(locale, defaultLocale)
+    return segment ? `${segment}/` : ''
+}
+
+/** What to iterate when building: every locale, or one unlocalised pass. */
+export function routedLocales(locales: Locale[]): (string | undefined)[] {
+    return locales.length > 0 ? locales.map((l) => l.code) : [undefined]
+}
+
+/** The locale codes whose urls carry a prefix. */
+export function prefixedLocales(locales: Locale[], defaultLocale: string): string[] {
+    return locales.map((locale) => locale.code).filter((code) => localeSegment(code, defaultLocale) !== '')
+}

package/src/site/runtime.ts

@@ -0,0 +1,19 @@
+import type { Locale } from './locales.ts'
+import config from 'virtual:jaad/config'
+import * as locales from './locales.ts'
+import { uiString, type UiKey } from './ui.ts'
+
+/** The virtual config, read once. */
+export const LOCALES: Locale[] = config.locales
+export const DEFAULT_LOCALE: string = config.defaultLocale
+
+export const localePrefix = (locale?: string) => locales.localePrefix(locale, DEFAULT_LOCALE)
+
+export const buildLocales = () => locales.routedLocales(LOCALES)
+
+export const prefixedCodes = () => locales.prefixedLocales(LOCALES, DEFAULT_LOCALE)
+
+/** The interface strings for a page, already resolved. */
+export function ui(locale: string = DEFAULT_LOCALE) {
+    return (key: UiKey) => uiString(config.ui, locale, key)
+}

package/src/site/search.ts

@@ -0,0 +1,227 @@
+/** The search index of one locale, as `search-index.json` serves it. */
+export interface SearchIndex {
+    /** Empty when the docs are not split into sections. */
+    sections: { key: string; label: string }[]
+    pages: SearchPage[]
+    entries: SearchEntry[]
+}
+
+export interface SearchPage {
+    title: string
+    href: string
+    section?: string
+    /** Display title of the chapter. */
+    chapter?: string
+    keywords?: string[]
+}
+
+/** The text under one heading, or before the first one. */
+export interface SearchEntry {
+    /** Position in `pages`. */
+    page: number
+    heading?: string
+    anchor?: string
+    text: string
+}
+
+export interface SearchHit {
+    entry: SearchEntry
+    href: string
+    score: number
+}
+
+/** A page and the headings inside it that matched. */
+export interface SearchGroup {
+    page: SearchPage
+    score: number
+    /** Set when the text before the first heading matched. */
+    intro?: SearchEntry
+    hits: SearchHit[]
+}
+
+const MAX_GROUPS = 8
+const MAX_HITS = 3
+const PAGES_PER_SECTION = 4
+
+/** Page fields count fully on the text before the first heading, and as
+ *  context everywhere else. */
+const WEIGHTS = {
+    title: { intro: 8, heading: 2 },
+    keywords: { intro: 4, heading: 1 },
+    chapter: { intro: 2, heading: 1 },
+    heading: 6,
+    text: 1,
+}
+
+const WORD = /[\p{L}\p{M}\p{N}]+/gu
+
+/** Lowercase, without accents. */
+export function fold(text: string): string {
+    return text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase()
+}
+
+/** The words of a query, folded. */
+export function queryTerms(query: string): string[] {
+    return fold(query).match(WORD) ?? []
+}
+
+const words = (text: string | undefined) => (text ? (fold(text).match(WORD) ?? []) : [])
+
+interface Prepared {
+    title: string[]
+    keywords: string[]
+    chapter: string[]
+    heading: string[]
+    text: string[]
+}
+
+/** The folded words of each entry, computed on first use. */
+const prepared = new WeakMap<SearchEntry, Prepared>()
+
+function prepare(entry: SearchEntry, page: SearchPage): Prepared {
+    let found = prepared.get(entry)
+    if (!found) {
+        found = {
+            title: words(page.title),
+            keywords: words(page.keywords?.join(' ')),
+            chapter: words(page.chapter),
+            heading: words(entry.heading),
+            text: words(entry.text),
+        }
+        prepared.set(entry, found)
+    }
+    return found
+}
+
+/** 2 for a whole word, 1 for a word it starts, 0 for none. */
+function match(fieldWords: string[], term: string): number {
+    let best = 0
+    for (const word of fieldWords) {
+        if (word === term) return 2
+        if (best === 0 && word.startsWith(term)) best = 1
+    }
+    return best
+}
+
+/** The score of an entry, null unless every term is in it or in its page.
+ *  `own` tells whether the heading or its text matched, not just the page. */
+function scoreEntry(fields: Prepared, terms: string[], intro: boolean): { score: number; own: boolean } | null {
+    const place = intro ? 'intro' : 'heading'
+    let score = 0
+    let own = false
+
+    for (const term of terms) {
+        const candidates: [number, number, boolean][] = [
+            [match(fields.title, term), WEIGHTS.title[place], false],
+            [match(fields.keywords, term), WEIGHTS.keywords[place], false],
+            [match(fields.chapter, term), WEIGHTS.chapter[place], false],
+            [match(fields.heading, term), WEIGHTS.heading, true],
+            [match(fields.text, term), WEIGHTS.text, true],
+        ]
+        let best = 0
+        for (const [quality, weight, isOwn] of candidates) {
+            if (quality === 0) continue
+            best = Math.max(best, quality * weight)
+            if (isOwn) own = true
+        }
+        if (best === 0) return null
+        score += best
+    }
+
+    return { score, own }
+}
+
+const entryHref = (page: SearchPage, entry: SearchEntry) => (entry.anchor ? `${page.href}#${entry.anchor}` : page.href)
+
+/** Pages ranked by their best entry, each with the headings that matched.
+ *  Every word must appear; a word also matches the words it starts. */
+export function search(index: SearchIndex, query: string, section?: string): SearchGroup[] {
+    const terms = queryTerms(query)
+    if (terms.length === 0) return []
+
+    const groups = new Map<number, SearchGroup>()
+    for (const entry of index.entries) {
+        const page = index.pages[entry.page]
+        if (section && page.section !== section) continue
+
+        const intro = entry.heading === undefined
+        const scored = scoreEntry(prepare(entry, page), terms, intro)
+        if (!scored) continue
+
+        let group = groups.get(entry.page)
+        if (!group) {
+            group = { page, score: 0, hits: [] }
+            groups.set(entry.page, group)
+        }
+        group.score = Math.max(group.score, scored.score)
+        if (!scored.own) continue
+        if (intro) group.intro = entry
+        else group.hits.push({ entry, href: entryHref(page, entry), score: scored.score })
+    }
+
+    return [...groups.values()]
+        .toSorted((a, b) => b.score - a.score)
+        .slice(0, MAX_GROUPS)
+        .map((group) => ({ ...group, hits: group.hits.toSorted((a, b) => b.score - a.score).slice(0, MAX_HITS) }))
+}
+
+/** What an empty query shows: the pages outside the sections, then the first
+ *  pages of each section; without sections, the first pages of the docs. */
+export function openingPages(index: SearchIndex, section?: string): { label?: string; pages: SearchPage[] }[] {
+    if (index.sections.length === 0) return [{ pages: index.pages.slice(0, MAX_GROUPS) }]
+
+    const loose = section ? [] : index.pages.filter((page) => !page.section).slice(0, PAGES_PER_SECTION)
+    return [
+        { pages: loose },
+        ...index.sections
+            .filter(({ key }) => !section || key === section)
+            .map(({ key, label }) => ({
+                label,
+                pages: index.pages.filter((page) => page.section === key).slice(0, PAGES_PER_SECTION),
+            })),
+    ].filter((group) => group.pages.length > 0)
+}
+
+/** The text around the first matching word, or its start when none matches,
+ *  ellipsised where cut. */
+export function getSnippet(text: string, terms: string[], before = 40, after = 100): string {
+    const parts = markWords(text, terms)
+    const first = parts.findIndex((part) => part.match)
+    const start = parts.slice(0, Math.max(first, 0)).reduce((length, part) => length + part.text.length, 0)
+    const from = Math.max(0, start - before)
+    const to = Math.min(text.length, start + after)
+    return (from > 0 ? '…' : '') + text.slice(from, to).trim() + (to < text.length ? '…' : '')
+}
+
+/** How many characters of `word` fold into the first `length` folded ones,
+ *  accents on the last of them included. */
+function foldedPrefix(word: string, length: number): number {
+    let folded = 0
+    let at = 0
+    for (const char of word) {
+        const size = fold(char).length
+        if (folded >= length && size > 0) break
+        folded += size
+        at += char.length
+    }
+    return at
+}
+
+/** Splits text around the words the terms start, marking the matched starts.
+ *  Case and accents are ignored. */
+export function markWords(text: string, terms: string[]): { text: string; match: boolean }[] {
+    const parts: { text: string; match: boolean }[] = []
+    let last = 0
+    for (const word of text.matchAll(WORD)) {
+        const folded = fold(word[0])
+        const term = terms.find((candidate) => folded.startsWith(candidate))
+        if (!term) continue
+
+        const end = word.index + foldedPrefix(word[0], term.length)
+        if (word.index > last) parts.push({ text: text.slice(last, word.index), match: false })
+        parts.push({ text: text.slice(word.index, end), match: true })
+        last = end
+    }
+    if (last < text.length) parts.push({ text: text.slice(last), match: false })
+    return parts
+}

package/src/site/social.ts

@@ -0,0 +1,44 @@
+import type { SiteResolvedConfig } from './config.ts'
+import { FORGES, forgeForUrl } from './forges.ts'
+
+export interface SocialLink {
+    href: string
+    label: string
+    /** Bundled forge icon. */
+    path?: string
+    /** User-supplied markup, which wins over the bundled icon. */
+    svg?: string
+}
+
+/** The configured links, plus the inferred repository unless already listed. */
+export function buildSocialLinks(config: SiteResolvedConfig): SocialLink[] {
+    const links: SocialLink[] = []
+
+    for (const [key, value] of Object.entries(config.social)) {
+        const entry = typeof value === 'string' ? { href: value } : value
+        const forge = FORGES[key]
+        links.push({
+            href: entry.href,
+            label:
+                // FORGES has no index signature guarantee: a missing key is undefined.
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                ('label' in entry ? entry.label : undefined) ?? forge?.label ?? key,
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            path: forge?.path,
+            svg: 'svg' in entry ? entry.svg : undefined,
+        })
+    }
+
+    const namedAForge = Object.keys(config.social).some((key) => key in FORGES)
+
+    if (config.repoUrl && !namedAForge && !links.some((l) => l.href === config.repoUrl)) {
+        const forge = forgeForUrl(config.repoUrl)
+        links.push({
+            href: config.repoUrl,
+            label: forge ? FORGES[forge].label : 'Repository',
+            path: forge ? FORGES[forge].path : undefined,
+        })
+    }
+
+    return links
+}

package/src/site/styles/components/footer.css

@@ -0,0 +1,8 @@
+@layer components {
+    .jaad-footer {
+        @apply border-border-dark mt-4 border-t pt-2;
+    }
+    .jaad-footer-credit {
+        @apply text-foreground-muted mb-1 text-center text-[0.95rem] leading-[1.6] italic;
+    }
+}

package/src/site/styles/components/header.css

@@ -0,0 +1,31 @@
+@layer components {
+    /* Fixed to the top of the window: only the page scrolls below it. */
+    .jaad-header {
+        position: fixed;
+        inset: 0 0 auto;
+        z-index: 40;
+        height: var(--jaad-header-height);
+        background: var(--color-background);
+    }
+    .jaad-header-inner {
+        height: 100%;
+        max-width: var(--jaad-chrome-width);
+        margin-inline: auto;
+        padding-inline: 1rem;
+    }
+    .jaad-header-row {
+        @apply flex h-full items-center gap-4;
+    }
+    .jaad-brand {
+        @apply text-foreground-bright text-xl;
+    }
+    .jaad-brand-link {
+        @apply text-primary no-underline;
+    }
+    .jaad-logo {
+        @apply h-7;
+    }
+    .jaad-header-actions {
+        @apply ml-auto flex items-center gap-2;
+    }
+}

package/src/site/styles/components/locale-switcher.css

@@ -0,0 +1,20 @@
+@layer components {
+    .jaad-locale-switcher {
+        @apply relative;
+    }
+    .jaad-locale-trigger {
+        @apply w-auto gap-1.5 px-2;
+    }
+    .jaad-locale-code {
+        @apply text-xs font-medium uppercase;
+    }
+    .jaad-locale-chevron {
+        @apply h-3 w-3 shrink-0;
+    }
+    .jaad-locale-menu {
+        @apply p-1;
+    }
+    .jaad-locale-item {
+        @apply flex items-center gap-2 aria-[current]:font-semibold;
+    }
+}

package/src/site/styles/components/nav-mobile.css

@@ -0,0 +1,15 @@
+@layer components {
+    .jaad-nav-mobile {
+        @apply relative md:hidden;
+    }
+    .jaad-nav-mobile [aria-expanded='true'] [data-icon-open],
+    .jaad-nav-mobile [aria-expanded='false'] [data-icon-close] {
+        @apply hidden;
+    }
+    .jaad-nav-mobile-links {
+        @apply p-2;
+    }
+    .jaad-nav-mobile-list {
+        @apply flex flex-col gap-1;
+    }
+}

package/src/site/styles/components/nav.css

@@ -0,0 +1,11 @@
+@layer components {
+    .jaad-nav {
+        @apply hidden md:block;
+    }
+    .jaad-nav-list {
+        @apply flex space-x-4;
+    }
+    .jaad-nav-link {
+        @apply text-foreground-secondary hover:text-foreground-bright no-underline hover:underline;
+    }
+}

package/src/site/styles/components/not-found.css

@@ -0,0 +1,11 @@
+@layer components {
+    .jaad-not-found {
+        @apply m-auto flex h-full w-full flex-col items-center justify-center px-16 text-center;
+    }
+    .jaad-not-found-title {
+        @apply mb-16 text-6xl font-bold;
+    }
+    .jaad-not-found-text {
+        @apply mb-32 text-xl;
+    }
+}