@jaamd/jaad 0.11.0 → 1.0.0

package/src/docs/components/DocsSidebarLeft.astro

@@ -0,0 +1,53 @@
+---
+import type { DocsNavGroup } from '../navigation.ts'
+import { ui } from '../../site/runtime.ts'
+import DocsNavTree from './DocsNavTree.astro'
+
+interface Props {
+    groups: DocsNavGroup[]
+    locale?: string
+}
+
+const { groups, locale } = Astro.props
+const t = ui(locale)
+---
+
+<aside class="docs-sidebar-left jaad-sidebar">
+    <nav aria-label={t('nav.documentation')}>
+        <DocsNavTree {groups} />
+    </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 → docs/components}/PageActions.astro

@@ -1,22 +1,24 @@
 ---
-import config from 'virtual:jaad/config'
-import { docsUrls, ui } from '../../docs-config.ts'
-import { editUrl } from '../../infer.ts'
-import { docsMarkdownHref } from '../../urls.ts'
+import { editUrl } from '../../site/infer.ts'
+import { ui } from '../../site/runtime.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsMarkdownHref } from '../urls.ts'
 
 interface Props {
-    /** Content collection entry id, e.g. "03-markdown/12-inner-html". */
-    id: string
+    /** Where the page's directory is edited, or null to leave the link out. */
+    editBase: string | null
+    /** The file below that directory, without its extension. */
+    editPath: string
     /** URL-safe slug, e.g. "markdown/inner-html". */
     cleanSlug: string
     locale?: string
 }
 
-const { id, cleanSlug, locale } = Astro.props
+const { editBase, editPath, cleanSlug, locale } = Astro.props
 const t = ui(locale)
 
 const mdHref = docsMarkdownHref(cleanSlug, docsUrls(locale))
-const editHref = config.editBase ? editUrl(config.editBase, `${id}.md`) : null
+const editHref = editBase ? editUrl(editBase, `${editPath}.md`) : null
 ---
 
 <div class="docs-page-actions">

package/src/{components/docs → docs/components}/StructuredData.astro

@@ -1,8 +1,8 @@
 ---
 import config from 'virtual:jaad/config'
-import { docsUrls } from '../../docs-config.ts'
-import { docsPageHref } from '../../urls.ts'
-import { formatChapterTitle } from '../../utils/docs.ts'
+import { formatChapterTitle } from '../model/ids.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.ts'
 
 interface Props {
     title: string

package/src/{components/docs → docs/components}/TableOfContents.astro

@@ -1,9 +1,9 @@
 ---
-import type { DocsHeadings } from '../../@types/docs.ts'
-import { ui } from '../../docs-config.ts'
+import type { DocsHeading } from '../types.ts'
+import { ui } from '../../site/runtime.ts'
 
 interface Props {
-    headings: DocsHeadings[]
+    headings: DocsHeading[]
     locale?: string
 }
 
@@ -12,29 +12,27 @@ 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>
+    <nav id="docs-toc" aria-label={t('toc.label')} class="docs-toc">
+        <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>
 )}
 
 <script>
     function initToc(): void {
-        const sidebar = document.getElementById('toc-sidebar')
+        const sidebar = document.getElementById('docs-toc')
         // astro:page-load also fires on the first load, which would observe twice.
         if (!sidebar || sidebar.dataset.tocInit) return
         sidebar.dataset.tocInit = '1'

package/src/docs/config.ts

@@ -0,0 +1,167 @@
+import { existsSync } from 'node:fs'
+import { relative, resolve, sep } from 'node:path'
+import { z } from 'astro/zod'
+import { editBaseFrom, type RepoInfo } from '../site/infer.ts'
+import { isLocale } from '../site/locales.ts'
+import { normaliseBasePath } from '../site/urls.ts'
+import { detectLocales, validateLocaleTree } from './locale-tree.ts'
+import { slugToTitle } from './model/ids.ts'
+
+/** The options of the documentation: where the markdown is and where it is served. */
+export const docsConfigShape = {
+    docsDir: z.string().default('./docs'),
+    routeBase: z.string().default('/'),
+    /** One directory per section, keyed by its url segment. Replaces `docsDir`. */
+    sections: z
+        .record(z.string(), z.object({ dir: z.string(), label: z.string().optional() }))
+        .superRefine((sections, context) => {
+            for (const key of Object.keys(sections)) {
+                if (/^[a-z0-9]+(-[a-z0-9]+)*$/.test(key)) continue
+                context.addIssue({
+                    code: 'custom',
+                    path: [key],
+                    message: 'a section key is its url segment: lowercase letters, digits and dashes',
+                })
+            }
+        })
+        .optional(),
+    editLink: z.union([z.boolean(), z.string()]).default(true),
+    /** 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(),
+}
+
+const docsConfigSchema = z.object(docsConfigShape)
+
+export type DocsConfig = z.output<typeof docsConfigSchema>
+
+/** Where the docs are and where they are served. */
+export interface DocsResolvedConfig {
+    /** Where the docs are mounted, without a trailing slash. Empty at the root. */
+    base: string
+    /** `docsDir` as configured, relative to the project. */
+    dir: string
+    /** Whether `dir` holds pages: always without sections; with them, only
+     *  when set, for the pages outside every section. */
+    dirInUse: boolean
+    /** Empty when the docs are not split into sections. */
+    sections: DocsSection[]
+    /** Edit url of the pages in `dir`, `:path` standing for the file. */
+    editBase: string | null
+}
+
+export interface DocsSection {
+    /** The url segment. */
+    key: string
+    label: string
+    /** As configured, relative to the project. */
+    dir: string
+    editBase: string | null
+}
+
+/** A directory of markdown, and the section it is when the docs have sections. */
+export interface DocsRoot {
+    /** Absolute. */
+    dir: string
+    section?: string
+}
+
+/** Empty at the root, otherwise one leading slash and no trailing one. */
+function resolveEditBase(editLink: DocsConfig['editLink'], repo: RepoInfo | null, docsDir: string): string | null {
+    if (typeof editLink === 'string') return editLink
+    if (!editLink || !repo) return null
+    return editBaseFrom(repo, docsDir)
+}
+
+function resolveSections(config: DocsConfig, repo: RepoInfo | null): DocsSection[] {
+    return Object.entries(config.sections ?? {}).map(([key, section]) => ({
+        key,
+        label: section.label ?? slugToTitle(key),
+        dir: section.dir,
+        editBase: resolveEditBase(config.editLink, repo, section.dir),
+    }))
+}
+
+/** No directory may be, or be inside, another. */
+function assertSeparateRoots(roots: DocsRoot[], cwd: string): void {
+    const paths = roots.map((root) => root.dir + sep)
+    const nested = roots.filter((_, at) => paths.some((other, from) => from !== at && paths[at].startsWith(other)))
+    if (nested.length === 0) return
+
+    throw new Error(
+        'jaad: sections overlap\n' +
+            nested
+                .map((root) => `  ${root.section ?? 'docsDir'}: ${relative(cwd, root.dir)} is, or is inside, another`)
+                .join('\n') +
+            '\nGive every section, and docsDir, a directory of its own.',
+    )
+}
+
+/**
+ * The docs, and the locale codes their directories are written in.
+ * `docsDirSet` tells whether the user set `docsDir`: alongside sections, only
+ * then does it hold pages.
+ */
+export function resolveDocsConfig(
+    config: DocsConfig,
+    lang: string,
+    docsDirSet: boolean,
+    repo: RepoInfo | null,
+    cwd: string,
+): { docs: DocsResolvedConfig; locales: string[] } {
+    const sections = resolveSections(config, repo)
+    const docs: DocsResolvedConfig = {
+        base: normaliseBasePath(config.routeBase),
+        dir: config.docsDir,
+        dirInUse: sections.length === 0 || docsDirSet,
+        sections,
+        editBase: resolveEditBase(config.editLink, repo, config.docsDir),
+    }
+
+    const roots = docsRoots(docs, cwd)
+    assertSeparateRoots(roots, cwd)
+    const locales = resolveLocales(config, lang, roots)
+
+    const ambiguous = sections.find((section) => locales.includes(section.key))
+    if (ambiguous) {
+        throw new Error(`jaad: section "${ambiguous.key}" has the name of a language the docs are written in`)
+    }
+
+    return { docs, locales }
+}
+
+/** Where the markdown lives: `dir` when in use, then the directory of every section. */
+export function docsRoots(docs: Pick<DocsResolvedConfig, 'dir' | 'dirInUse' | 'sections'>, cwd: string): DocsRoot[] {
+    return [
+        ...(docs.dirInUse ? [{ dir: resolve(cwd, docs.dir) }] : []),
+        ...docs.sections.map((section) => ({ dir: resolve(cwd, section.dir), section: section.key })),
+    ]
+}
+
+/** Directory names win; `locales` only overrides what detection found. */
+function resolveLocales(config: DocsConfig, lang: string, roots: DocsRoot[]): string[] {
+    if (config.locales === false) return []
+
+    const perRoot = roots.map((root) => resolveLocalesIn(root.dir, config, lang))
+    const [first, ...rest] = perRoot
+    const differing = rest.find((locales) => locales.join() !== first.join())
+    if (differing) {
+        throw new Error(
+            'jaad: sections disagree on their languages\n' +
+                `  found ${first.join(', ') || 'none'} and ${differing.join(', ') || 'none'}\n` +
+                'Give every section the same locale directories, or none.',
+        )
+    }
+    return first
+}
+
+function resolveLocalesIn(docsDir: string, config: DocsConfig, lang: string): string[] {
+    const locales = Array.isArray(config.locales) ? config.locales : detectLocales(docsDir, 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, lang)
+    return locales.map((locale) => locale.toLowerCase()).toSorted()
+}

package/src/docs/content.ts

@@ -0,0 +1,36 @@
+import { frontmatterFields } from '@jaamd/astro/frontmatter'
+import { glob } from 'astro/loaders'
+import { z } from 'astro/zod'
+import { defineCollection } from 'astro:content'
+import config from 'virtual:jaad/config'
+import { collectionIdFor, collectionName } from './model/ids.ts'
+
+const LOCALES = config.locales.map((locale) => locale.code)
+
+/** The markdown of one directory, as the pages of `section` when there is one. */
+const docs = (base: string, section?: string) =>
+    defineCollection({
+        loader: glob({
+            pattern: '**/*.md',
+            base,
+            // Keep URLs file-driven even if markdown contains an unrelated slug field.
+            generateId: ({ entry }) => collectionIdFor(entry, section, LOCALES),
+        }),
+        // Every field is optional: markdown without frontmatter works as-is.
+        schema: z.object({
+            ...frontmatterFields(z),
+            /** Shorter label, in navigation only. */
+            label: z.string().optional(),
+            /** Pairs this page with its translations when the slugs differ. */
+            translationKey: z.string().optional(),
+            /** Replaces the filename prefix number. */
+            order: z.number().int().optional(),
+        }),
+    })
+
+/** `docsPages` for `docsDir`, and one collection per section: each watches its
+ *  own directory. */
+export const collections = Object.fromEntries([
+    ...(config.docs.dirInUse ? [[collectionName(), docs(config.docs.dir)]] : []),
+    ...config.docs.sections.map((section) => [collectionName(section.key), docs(section.dir, section.key)]),
+])

package/src/docs/endpoints.ts

@@ -0,0 +1,89 @@
+import type { DocsPage } from './model/tree.ts'
+import config from 'virtual:jaad/config'
+import { getDocsTree } from './collection.ts'
+import { formatChapterTitle } from './model/ids.ts'
+import { pageDescription } from './model/rendered.ts'
+import { SECTIONS, docsUrls } from './runtime.ts'
+import { buildSearchIndex } from './search-index.ts'
+import { docsMarkdownHref } from './urls.ts'
+
+export async function searchIndexResponse(locale?: string): Promise<Response> {
+    const index = buildSearchIndex(await getDocsTree(locale), SECTIONS)
+
+    return new Response(JSON.stringify(index), {
+        headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    })
+}
+
+interface Row {
+    title: string
+    slug: string
+    description: string | null
+}
+
+/** Plain-text index of every page, per the llms.txt convention. */
+export async function llmsResponse(site: URL | undefined, locale?: string): Promise<Response> {
+    const { pages: sortedPages } = await getDocsTree(locale)
+
+    const markdownHref = (slug: string): string => {
+        const href = docsMarkdownHref(slug, docsUrls(locale))
+        return site ? new URL(href, site.origin).href : href
+    }
+
+    const toLine = (row: Row): string =>
+        `- [${row.title}](${markdownHref(row.slug)})${row.description ? `: ${row.description}` : ''}`
+
+    /** Standalone pages first, then one heading per chapter. */
+    const outline = (pages: DocsPage[], heading: string): string[] => {
+        const standalone: Row[] = []
+        const chapters = new Map<string, Row[]>()
+
+        for (const page of pages) {
+            const { chapter, title } = page
+            const row: Row = {
+                title,
+                slug: page.slug,
+                description: page.data.description ?? pageDescription(page.source.rendered, title),
+            }
+
+            if (!chapter) {
+                standalone.push(row)
+                continue
+            }
+
+            const rows = chapters.get(chapter) ?? []
+            if (rows.length === 0) chapters.set(chapter, rows)
+            rows.push(row)
+        }
+
+        return [
+            ...(standalone.length > 0 ? [standalone.map(toLine).join('\n')] : []),
+            ...[...chapters].map(
+                ([chapter, rows]) =>
+                    `${heading} ${formatChapterTitle(chapter) ?? chapter}\n\n${rows.map(toLine).join('\n')}`,
+            ),
+        ]
+    }
+
+    // With sections, the pages outside them come first; each section is a
+    // heading, and its chapters sit one level below.
+    const loose = sortedPages.filter((page) => !page.section)
+    const sections: string[] =
+        SECTIONS.length === 0
+            ? outline(sortedPages, '##')
+            : [
+                  ...(loose.length > 0 ? outline(loose, '##') : []),
+                  ...SECTIONS.flatMap((section) => {
+                      const pages = sortedPages.filter((page) => page.section === section.key)
+                      return pages.length > 0 ? [`## ${section.label}`, ...outline(pages, '###')] : []
+                  }),
+              ]
+
+    const content = [`# ${config.title}`, ...(config.description ? [`> ${config.description}`] : []), ...sections].join(
+        '\n\n',
+    )
+
+    return new Response(content + '\n', {
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    })
+}