@jaamd/jaad 0.0.0-stage → 0.11.0

package/src/components/docs/DocsPage.astro

@@ -0,0 +1,68 @@
+---
+import type { DocsEntry } from '../../@types/docs.ts'
+import MarkdownContent from '@jaamd/jaamd/components'
+import config from 'virtual:jaad/config'
+import { DEFAULT_LOCALE, LOCALES, docsUrls, ui } from '../../docs-config.ts'
+import DocsLayout from '../../layouts/Docs.astro'
+import { buildDocsNavigation } from '../../navigation.ts'
+import {
+    getCleanSlug,
+    parseDocCollectionId,
+    docTitle,
+    extractHeadingsFromMarkdown,
+    routedId,
+} from '../../utils/docs.ts'
+import Breadcrumbs from './Breadcrumbs.astro'
+import DocsMobileNav from './DocsMobileNav.astro'
+import DocsPageNav from './DocsPageNav.astro'
+import PageActions from './PageActions.astro'
+
+interface Props {
+    entry: DocsEntry
+    sortedPages: DocsEntry[]
+    /** Left out on the opening page, whose title is the site name alone. */
+    headTitle?: string
+}
+
+const { entry, sortedPages, headTitle } = Astro.props
+
+const cleanSlug = getCleanSlug(routedId(entry))
+const { chapter } = parseDocCollectionId(routedId(entry))
+const title = docTitle(entry)
+const headings = extractHeadingsFromMarkdown(entry.body || '')
+const urls = docsUrls(entry.locale)
+const t = ui(entry.locale)
+const language = LOCALES.find((known) => known.code === (entry.locale ?? DEFAULT_LOCALE))?.tag ?? config.lang
+const updated = entry.data.lastUpdated
+const navigation = buildDocsNavigation(sortedPages, entry.id, urls)
+const contentAttrs = { id: 'content' }
+---
+
+<DocsLayout title={headTitle} chapter={chapter} entry={entry} headings={headings} {navigation}>
+    <DocsMobileNav slot="mobile-navigation" sections={navigation.sections} headings={headings} locale={entry.locale} />
+
+    <Breadcrumbs slot="breadcrumbs" chapter={chapter} title={title} locale={entry.locale} />
+    <PageActions slot="page-actions" id={entry.id} cleanSlug={cleanSlug} locale={entry.locale} />
+
+    <Fragment slot="content">
+        <MarkdownContent {...contentAttrs} class="docs-content">
+            <slot />
+        </MarkdownContent>
+
+        {updated && (
+            <p class="docs-updated">
+                {t('page.lastUpdated')}{' '}
+                <time datetime={updated.toISOString()}>
+                    {new Intl.DateTimeFormat(language, { dateStyle: 'long' }).format(updated)}
+                </time>
+            </p>
+        )}
+    </Fragment>
+
+    <DocsPageNav
+        slot="page-navigation"
+        previousPage={navigation.previousPage}
+        nextPage={navigation.nextPage}
+        locale={entry.locale}
+    />
+</DocsLayout>

package/src/components/docs/DocsPageNav.astro

@@ -0,0 +1,53 @@
+---
+import type { DocsNavItem } from '../../@types/docs.ts'
+import { ui } from '../../docs-config.ts'
+
+interface Props {
+    locale?: string
+    previousPage: DocsNavItem | null
+    nextPage: DocsNavItem | null
+}
+
+const { previousPage, nextPage, locale } = Astro.props
+const t = ui(locale)
+---
+
+{(previousPage || nextPage) && (
+    <nav class="docs-page-nav" aria-label={t('nav.page')}>
+        <div class="docs-page-nav-row">
+            {previousPage && previousPage.title ? (
+                <a href={previousPage.href} rel="prev" class="docs-page-nav-link">
+                    <svg
+                        class="docs-page-nav-icon docs-page-nav-icon-prev"
+                        fill="none"
+                        stroke="currentColor"
+                        viewBox="0 0 24 24"
+                        aria-hidden="true"
+                    >
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
+                    </svg>
+                    <span class="docs-page-nav-label">{previousPage.title}</span>
+                </a>
+            ) : (
+                <div />
+            )}
+
+            {nextPage && nextPage.title ? (
+                <a href={nextPage.href} rel="next" class="docs-page-nav-link">
+                    <span class="docs-page-nav-label">{nextPage.title}</span>
+                    <svg
+                        class="docs-page-nav-icon docs-page-nav-icon-next"
+                        fill="none"
+                        stroke="currentColor"
+                        viewBox="0 0 24 24"
+                        aria-hidden="true"
+                    >
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+                    </svg>
+                </a>
+            ) : (
+                <div />
+            )}
+        </div>
+    </nav>
+)}

package/src/components/docs/DocsSidebarLeft.astro

@@ -0,0 +1,82 @@
+---
+import type { NavSection } from '../../navigation.ts'
+import { ui } from '../../docs-config.ts'
+import { formatChapterTitle } from '../../utils/docs.ts'
+
+interface Props {
+    sections: NavSection[]
+    locale?: string
+}
+
+const { sections, locale } = Astro.props
+const t = ui(locale)
+---
+
+<aside class="docs-sidebar-left jaad-sidebar">
+    <nav aria-label={t('nav.documentation')}>
+        {sections.map((section) =>
+            section.type === 'page' ? (
+                <div class="docs-sidebar-page">
+                    <a
+                        href={section.item.href}
+                        class="docs-sidebar-link"
+                        aria-current={section.item.isActive ? 'page' : undefined}
+                    >
+                        {section.item.title}
+                    </a>
+                </div>
+            ) : (
+                <div class="docs-sidebar-chapter">
+                    <h3 class="docs-sidebar-chapter-title">{formatChapterTitle(section.chapter)}</h3>
+                    <ul class="docs-sidebar-chapter-list">
+                        {section.items.map((item) => (
+                            <li>
+                                <a
+                                    href={item.href}
+                                    class="docs-sidebar-sublink"
+                                    aria-current={item.isActive ? 'page' : undefined}
+                                >
+                                    {item.title}
+                                </a>
+                            </li>
+                        ))}
+                    </ul>
+                </div>
+            ),
+        )}
+    </nav>
+</aside>
+
+<script>
+    const SELECTOR = '.docs-sidebar-left'
+    let scrollTop = 0
+
+    const sidebar = () => document.querySelector<HTMLElement>(SELECTOR)
+
+    /** Scrolls the sidebar only, never the document, and only when needed. */
+    function revealCurrent() {
+        const el = sidebar()
+        const current = el?.querySelector('[aria-current="page"]')
+        if (!el || !current) return
+
+        const box = el.getBoundingClientRect()
+        const item = current.getBoundingClientRect()
+        if (item.top >= box.top && item.bottom <= box.bottom) return
+
+        el.scrollTop += item.top - box.top - (box.height - item.height) / 2
+    }
+
+    document.addEventListener('astro:before-swap', () => {
+        scrollTop = sidebar()?.scrollTop ?? 0
+    })
+
+    document.addEventListener('astro:after-swap', () => {
+        const el = sidebar()
+        if (!el) return
+        el.scrollTop = scrollTop
+        // A deep link, or a page whose entry sits outside the restored window.
+        revealCurrent()
+    })
+
+    revealCurrent()
+</script>

package/src/components/docs/PageActions.astro

@@ -0,0 +1,81 @@
+---
+import config from 'virtual:jaad/config'
+import { docsUrls, ui } from '../../docs-config.ts'
+import { editUrl } from '../../infer.ts'
+import { docsMarkdownHref } from '../../urls.ts'
+
+interface Props {
+    /** Content collection entry id, e.g. "03-markdown/12-inner-html". */
+    id: string
+    /** URL-safe slug, e.g. "markdown/inner-html". */
+    cleanSlug: string
+    locale?: string
+}
+
+const { id, cleanSlug, locale } = Astro.props
+const t = ui(locale)
+
+const mdHref = docsMarkdownHref(cleanSlug, docsUrls(locale))
+const editHref = config.editBase ? editUrl(config.editBase, `${id}.md`) : null
+---
+
+<div class="docs-page-actions">
+    <button type="button" data-copy-page data-md-href={mdHref} data-copied={t('page.copied')} class="docs-page-action">
+        <svg class="docs-page-action-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+            <path
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                stroke-width="2"
+                d="M16 1H4a2 2 0 00-2 2v14h2V3h12V1zm3 4H8a2 2 0 00-2 2v14a2 2 0 002 2h11a2 2 0 002-2V7a2 2 0 00-2-2z"
+            ></path>
+        </svg>
+        <span data-copy-label>{t('page.copy')}</span>
+    </button>
+
+    {editHref && (
+        <a href={editHref} target="_blank" rel="noopener noreferrer" class="docs-page-action">
+            <svg class="docs-page-action-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                <path
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    stroke-width="2"
+                    d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"
+                />
+            </svg>
+            <span>{t('page.edit')}</span>
+        </a>
+    )}
+</div>
+
+<script>
+    function initCopyPageButtons(): void {
+        document.querySelectorAll<HTMLButtonElement>('[data-copy-page]').forEach((btn) => {
+            if (btn.dataset.copyInit) return
+            btn.dataset.copyInit = '1'
+
+            const label = btn.querySelector<HTMLElement>('[data-copy-label]')
+
+            btn.addEventListener('click', async () => {
+                const href = btn.dataset.mdHref
+                if (!href) return
+                try {
+                    const res = await fetch(href)
+                    const text = await res.text()
+                    await navigator.clipboard.writeText(text)
+                    if (label) {
+                        const original = label.textContent
+                        label.textContent = btn.dataset.copied ?? 'Copied!'
+                        setTimeout(() => {
+                            label.textContent = original
+                        }, 2000)
+                    }
+                } catch {
+                    // Network or clipboard unavailable.
+                }
+            })
+        })
+    }
+
+    initCopyPageButtons()
+    document.addEventListener('astro:page-load', initCopyPageButtons)
+</script>

package/src/components/docs/StructuredData.astro

@@ -0,0 +1,55 @@
+---
+import config from 'virtual:jaad/config'
+import { docsUrls } from '../../docs-config.ts'
+import { docsPageHref } from '../../urls.ts'
+import { formatChapterTitle } from '../../utils/docs.ts'
+
+interface Props {
+    title: string
+    description: string
+    chapter?: string
+    keywords?: string[]
+    author?: string
+    modified?: Date
+    /** BCP-47 tag of this page's locale. */
+    language?: string
+    locale?: string
+}
+
+const { title, description, chapter, keywords = [], author, modified, language = config.lang, locale } = Astro.props
+
+// Relative ids are worthless to a crawler, so without `site` emit nothing.
+const site = Astro.site
+const base = site ? docsPageHref('', docsUrls(locale)) : null
+
+const crumbs = base
+    ? [
+          { name: config.title, url: new URL(base, Astro.url.origin).href },
+          ...(chapter ? [{ name: formatChapterTitle(chapter)!, url: null }] : []),
+          { name: title, url: Astro.url.href },
+      ]
+    : []
+
+const data = base && {
+    '@context': 'https://schema.org',
+    '@type': 'TechArticle',
+    headline: title,
+    description,
+    inLanguage: language,
+    ...(keywords.length > 0 ? { keywords } : {}),
+    ...(author ? { author: { '@type': 'Person', name: author } } : {}),
+    ...(modified ? { dateModified: modified.toISOString() } : {}),
+    isPartOf: { '@type': 'WebSite', name: config.title },
+    breadcrumb: {
+        '@type': 'BreadcrumbList',
+        itemListElement: crumbs.map((crumb, i) => ({
+            '@type': 'ListItem',
+            position: i + 1,
+            name: crumb.name,
+            ...(crumb.url ? { item: crumb.url } : {}),
+        })),
+    },
+}
+---
+
+{data && <script type="application/ld+json" set:html={JSON.stringify(data)} is:inline />}

package/src/components/docs/TableOfContents.astro

@@ -0,0 +1,73 @@
+---
+import type { DocsHeadings } from '../../@types/docs.ts'
+import { ui } from '../../docs-config.ts'
+
+interface Props {
+    headings: DocsHeadings[]
+    locale?: string
+}
+
+const { headings, locale } = Astro.props
+const t = ui(locale)
+---
+
+{headings.length > 0 && (
+    <aside id="toc-sidebar" class="docs-sidebar-right jaad-sidebar">
+        <nav aria-label={t('toc.label')}>
+            <h2 class="docs-toc-title">{t('toc.title')}</h2>
+            <ul class="docs-toc-list">
+                {headings.map((heading) => (
+                    <li>
+                        <a
+                            href={`#${heading.slug}`}
+                            data-toc-link
+                            class:list={['docs-toc-link', heading.depth === 3 && 'docs-toc-link-nested']}
+                        >
+                            {heading.text}
+                        </a>
+                    </li>
+                ))}
+            </ul>
+        </nav>
+    </aside>
+)}
+
+<script>
+    function initToc(): void {
+        const sidebar = document.getElementById('toc-sidebar')
+        // astro:page-load also fires on the first load, which would observe twice.
+        if (!sidebar || sidebar.dataset.tocInit) return
+        sidebar.dataset.tocInit = '1'
+
+        const links = Array.from(sidebar.querySelectorAll<HTMLAnchorElement>('[data-toc-link]'))
+        const headingEls = links
+            .map((link) => document.getElementById(link.getAttribute('href')!.slice(1)))
+            .filter(Boolean) as HTMLElement[]
+
+        if (!headingEls.length) return
+
+        const setActive = (id: string): void => {
+            links.forEach((link) => {
+                const isActive = link.getAttribute('href') === `#${id}`
+                if (isActive) link.setAttribute('aria-current', 'location')
+                else link.removeAttribute('aria-current')
+            })
+        }
+
+        const observer = new IntersectionObserver(
+            (entries) => {
+                entries.forEach((entry) => {
+                    if (entry.isIntersecting) setActive(entry.target.id)
+                })
+            },
+            { rootMargin: '-100px 0px -66%', threshold: 0 },
+        )
+
+        headingEls.forEach((el) => observer.observe(el))
+
+        document.addEventListener('astro:before-preparation', () => observer.disconnect(), { once: true })
+    }
+
+    initToc()
+    document.addEventListener('astro:page-load', initToc)
+</script>

package/src/components/locale-switcher.ts

@@ -0,0 +1,6 @@
+/** The markup the persisted switcher should adopt from an incoming document,
+ *  or null when there is nothing to adopt. */
+export function nextSwitcherMarkup(incoming: Document): string | null {
+    const next = incoming.querySelector('jaad-locale-switcher')
+    return next ? next.innerHTML : null
+}

package/src/config.ts

@@ -0,0 +1,236 @@
+import type { AstroUserConfig, FontProvider, Locales, SessionDriverConfig } from 'astro'
+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 { inferRepo, inferDescription, editBaseFrom, type RepoInfo } from './infer.ts'
+import { detectLocales, validateLocaleTree } from './locale-tree.ts'
+import { describeLocale, isLocale, type Locale } from './locales.ts'
+import { PRESETS, PRESET_NAMES, isPreset } from './themes/index.ts'
+import { normaliseBasePath } from './urls.ts'
+
+export const jaadConfigSchema = z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    lang: z.string().default('en'),
+    logo: z
+        .string()
+        .refine((v) => v.startsWith('/') || /^https?:\/\//.test(v), {
+            message: 'logo must be a public url, such as "/logo.svg"',
+        })
+        .optional(),
+
+    docsDir: z.string().default('./docs'),
+    routeBase: 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(),
+
+    editLink: z.union([z.boolean(), z.string()]).default(true),
+
+    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([
+            z.string().refine((v) => v.startsWith('/') || /^https?:\/\//.test(v), {
+                message: 'ogImage must be a public url, such as "/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({}),
+
+    /** Only when detection guesses wrong: pin the set, or false to switch it off. */
+    locales: z
+        .union([z.array(z.string().refine(isLocale, { message: 'not a locale code' })), z.literal(false)])
+        .optional(),
+})
+
+export type JaadConfig = z.output<typeof jaadConfigSchema>
+
+/** Out of the schema, so `parse` strips them: the resolved config is
+ *  serialised and an integration is not. */
+type AstroPassthroughConfig = AstroUserConfig<Locales, string | SessionDriverConfig | undefined, FontProvider[]>
+
+export type JaadUserConfig = z.input<typeof jaadConfigSchema> & {
+    site?: string
+    base?: string
+    astro?: AstroPassthroughConfig
+}
+
+/** What the components actually read: the user's options plus whatever the
+ *  repository could tell us. Inferred fields are null when unavailable. */
+export interface JaadResolvedConfig extends JaadConfig {
+    /** Where the docs are mounted, without a trailing slash. Empty at the root. */
+    docsBase: string
+    /** What jaamd gets for code blocks. */
+    shiki: string | { light: string; dark: string }
+    repoUrl: string | null
+    editBase: string | null
+    favicon: string | null
+    /** Explicit, inferred from public/, or false when no valid image exists. */
+    ogImage: string | false
+    /** Empty when the docs are not localised. */
+    docsLocales: Locale[]
+    /** `lang` when the docs are 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
+}
+
+/** Empty at the root, otherwise one leading slash and no trailing one. */
+function resolveEditBase(editLink: JaadConfig['editLink'], repo: RepoInfo | null, docsDir: string): string | null {
+    if (typeof editLink === 'string') return editLink
+    if (!editLink || !repo) return null
+    return editBaseFrom(repo, docsDir)
+}
+
+const OPTIONS = Object.keys(jaadConfigSchema.shape)
+const FORWARDED = ['site', 'base', 'astro']
+
+/** Unknown keys are rejected here: zod would strip a misspelt option in
+ *  silence. Both messages are read in a terminal, not parsed. */
+function parseConfig(options: JaadUserConfig): JaadConfig {
+    const known = new Set([...OPTIONS, ...FORWARDED])
+    const unknown = Object.keys(options).filter((key) => !known.has(key))
+
+    if (unknown.length > 0) {
+        const named = unknown.map((key) => {
+            const close = OPTIONS.find((o) => o.toLowerCase() === key.toLowerCase())
+            return close ? `${key} (did you mean ${close}?)` : key
+        })
+        throw new Error(
+            `jaad: unknown option${unknown.length > 1 ? 's' : ''} ${named.join(', ')}\n` +
+                `  available: ${OPTIONS.join(', ')}`,
+        )
+    }
+
+    const parsed = jaadConfigSchema.safeParse(options)
+    if (parsed.success) return parsed.data
+
+    throw new Error(
+        'jaad: invalid configuration\n' +
+            parsed.error.issues.map((issue) => `  ${issue.path.join('.') || 'config'}: ${issue.message}`).join('\n'),
+    )
+}
+
+export function resolveConfig(options: JaadUserConfig, cwd: string = process.cwd()): JaadResolvedConfig {
+    const config = parseConfig(options)
+    const repo = inferRepo(cwd)
+    const locales = resolveLocales(config, cwd)
+
+    return {
+        ...config,
+        description: config.description ?? inferDescription(cwd) ?? undefined,
+        repoUrl: repo?.url ?? null,
+        favicon: findPublicAsset(cwd, FAVICONS),
+        ogImage: config.ogImage ?? findPublicAsset(cwd, OG_IMAGES) ?? false,
+        docsBase: normaliseBasePath(config.routeBase),
+        shiki: typeof config.theme === 'string' ? PRESETS[config.theme].shiki : config.theme,
+        editBase: resolveEditBase(config.editLink, repo, config.docsDir),
+        docsLocales: locales.map(describeLocale),
+        defaultLocale: locales.length > 0 ? config.lang.toLowerCase() : config.lang,
+    }
+}
+
+/** Directory names win; `locales` only overrides what detection found. */
+function resolveLocales(config: JaadConfig, cwd: string): string[] {
+    if (config.locales === false) return []
+
+    const docsDir = join(cwd, config.docsDir)
+    const locales = config.locales ?? detectLocales(docsDir, config.lang)
+    // A pinned list skips detection, and with it the missing-directory guard;
+    // the integration warns about that case with better words than readdir does.
+    if (locales.length === 0 || !existsSync(docsDir)) return []
+
+    validateLocaleTree(docsDir, locales, config.lang)
+    return locales.map((locale) => locale.toLowerCase()).toSorted()
+}
+
+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: JaadConfig,
+    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/jaamd/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,
+    }
+}
+
+/** Identity helper, for a typed `jaad.config.ts`. */
+export function defineJaadConfig(config: JaadUserConfig): JaadUserConfig {
+    return config
+}