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

package/src/docs/model/tree.ts

@@ -0,0 +1,124 @@
+import type { DocsPageData } from '../types.ts'
+import type { DocsUrlOptions } from '../urls.ts'
+import type { RenderedMarkdown } from './rendered.ts'
+import { docsPageHref } from '../urls.ts'
+import { namedSlug, parseDocPath, slugToTitle } from './ids.ts'
+import { renderedTitle } from './rendered.ts'
+
+/** A markdown file of one locale: a collection entry, or a file read from disk. */
+export interface DocsSource {
+    /** Collection id. */
+    id: string
+    /** The id without its locale and its section. */
+    path: string
+    /** Set when the docs are localised. */
+    locale?: string
+    /** Set when the docs are split into sections. */
+    section?: string
+    data: Partial<DocsPageData>
+    rendered?: RenderedMarkdown
+}
+
+/** A page with everything its file, its frontmatter and its place in the docs decide. */
+export interface DocsPage<S extends DocsSource = DocsSource> {
+    /** What the page was built from. */
+    source: S
+    id: string
+    path: string
+    locale?: string
+    section?: string
+    /** The chapter directory, without its order prefix. */
+    chapter?: string
+    data: S['data']
+    /** The named url below the docs mount: its section, then its clean path. */
+    slug: string
+    /** Where it is served: empty for the opening page, the section for the first
+     *  page of a later one, `slug` otherwise. */
+    canonical: string
+    /** The other slugs it answers to, each redirecting to `canonical`. */
+    aliases: string[]
+    /** The url of `canonical`. */
+    href: string
+    /** Frontmatter title, then the first h1, then the file name. */
+    title: string
+    /** The name in navigation: frontmatter `label`, then `title`. */
+    label: string
+    /** What pairs it with its translations: frontmatter `translationKey`, then `slug`. */
+    translationKey: string
+    /** Position in reading order. */
+    index: number
+}
+
+/** The pages of one locale in reading order. */
+export interface DocsTree<S extends DocsSource = DocsSource> {
+    pages: DocsPage<S>[]
+    byId: Map<string, DocsPage<S>>
+    byKey: Map<string, DocsPage<S>>
+}
+
+export interface DocsTreeOptions {
+    /** Section keys, in their order. */
+    sections?: string[]
+    /** For `href`. */
+    urls: DocsUrlOptions
+}
+
+/** The order of `sections` first, then chapter order, then file order within
+ *  the chapter. Frontmatter `order` replaces a file's prefix number; root pages
+ *  interleave with chapters by their own number. */
+function sortSources<S extends DocsSource>(sources: S[], sections: string[]): S[] {
+    return sources
+        .map((source) => {
+            const parsed = parseDocPath(source.path)
+            const order = source.data.order ?? parsed.order
+            return {
+                source,
+                section: sections.indexOf(source.section ?? ''),
+                primary: parsed.orderChapter ?? order,
+                secondary: order,
+            }
+        })
+        .toSorted((a, b) => a.section - b.section || a.primary - b.primary || a.secondary - b.secondary)
+        .map((entry) => entry.source)
+}
+
+/** Resolves every page of one locale once. */
+export function buildDocsTree<S extends DocsSource>(sources: S[], options: DocsTreeOptions): DocsTree<S> {
+    const sorted = sortSources(sources, options.sections ?? [])
+
+    const pages = sorted.map((source, index): DocsPage<S> => {
+        const parsed = parseDocPath(source.path)
+        const slug = namedSlug(source.path, source.section)
+        const canonical =
+            index === 0 ? '' : source.section && sorted[index - 1].section !== source.section ? source.section : slug
+        const title = source.data.title ?? renderedTitle(source.rendered) ?? slugToTitle(parsed.slug)
+
+        return {
+            source,
+            id: source.id,
+            path: source.path,
+            locale: source.locale,
+            section: source.section,
+            chapter: parsed.chapter,
+            data: source.data,
+            slug,
+            canonical,
+            aliases: [
+                ...(slug === canonical ? [] : [slug]),
+                // The first section's key leads to the opening page.
+                ...(index === 0 && source.section ? [source.section] : []),
+            ],
+            href: docsPageHref(canonical, options.urls),
+            title,
+            label: source.data.label ?? title,
+            translationKey: source.data.translationKey ?? slug,
+            index,
+        }
+    })
+
+    return {
+        pages,
+        byId: new Map(pages.map((page) => [page.id, page])),
+        byKey: new Map(pages.map((page) => [page.translationKey, page])),
+    }
+}

package/src/docs/model/validate.ts

@@ -0,0 +1,75 @@
+import type { DocsSource } from './tree.ts'
+import { getCleanSlug, namedSlug } from './ids.ts'
+
+/** Within a section, like `id`; across them, the section is part of the name. */
+const inSection = (page: DocsSource, id: string) => (page.section ? `${page.section}/${id}` : id)
+
+/** Fail before route generation when the file tree cannot produce one clear
+ * navigation and URL for every page. */
+export function validateDocsStructure(pages: DocsSource[], locale?: string): void {
+    const idsBySlug = new Map<string, string[]>()
+    const directoriesByChapter = new Map<string, Set<string>>()
+    const issues: string[] = []
+    // Messages name the file on disk, locale directory included.
+    const named = (id: string) => (locale ? `${locale}/${id}` : id)
+
+    const byId = pages.map((page) => ({ page, id: inSection(page, page.path) }))
+    for (const { page, id } of byId.toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        const parts = page.path.split('/')
+        if (parts.length > 2) {
+            issues.push(`${named(id)}: only one chapter directory is supported inside docs/`)
+        }
+
+        const slug = namedSlug(page.path, page.section)
+        const ids = idsBySlug.get(slug) ?? []
+        ids.push(id)
+        idsBySlug.set(slug, ids)
+
+        if (parts.length === 2) {
+            const directory = inSection(page, parts[0])
+            const chapter = inSection(page, getCleanSlug(parts[0]))
+            const directories = directoriesByChapter.get(chapter) ?? new Set()
+            directories.add(directory)
+            directoriesByChapter.set(chapter, directories)
+        }
+    }
+
+    for (const [slug, ids] of idsBySlug) {
+        if (ids.length > 1) {
+            issues.push(`${ids.map(named).join(', ')} all resolve to /${slug}`)
+        }
+    }
+
+    // A page outside the sections cannot take a section's url.
+    const keys = new Set(pages.flatMap((page) => page.section ?? []))
+    for (const page of pages) {
+        const first = namedSlug(page.path, page.section).split('/')[0]
+        if (!page.section && keys.has(first)) {
+            issues.push(`${named(page.path)} resolves into section /${first}`)
+        }
+    }
+
+    const byKey = new Map<string, string[]>()
+    for (const page of pages) {
+        const key = page.data.translationKey
+        if (!key) continue
+        const ids = byKey.get(key) ?? []
+        ids.push(inSection(page, page.path))
+        byKey.set(key, ids)
+    }
+    for (const [key, ids] of byKey) {
+        if (ids.length > 1) {
+            issues.push(`${ids.map(named).join(', ')} all claim translationKey ${key}`)
+        }
+    }
+
+    for (const [chapter, directories] of directoriesByChapter) {
+        if (directories.size > 1) {
+            issues.push(`${[...directories].map(named).join(', ')} all resolve to chapter /${chapter}`)
+        }
+    }
+
+    if (issues.length > 0) {
+        throw new Error(`jaad: invalid documentation structure\n${issues.map((issue) => `  ${issue}`).join('\n')}`)
+    }
+}

package/src/docs/navigation.ts

@@ -0,0 +1,75 @@
+import type { DocsTree } from './model/tree.ts'
+import type { DocsNavItem } from './types.ts'
+
+/** A page, or a chapter and its pages. */
+export type DocsNavEntry =
+    | { type: 'page'; item: DocsNavItem }
+    | { type: 'chapter'; chapter: string; items: DocsNavItem[] }
+
+/** A top-level entry. With sections, the pages outside them come first, then
+ *  every section and its entries. */
+export type DocsNavGroup = DocsNavEntry | { type: 'section'; section: string; label: string; entries: DocsNavEntry[] }
+
+export interface DocsNavigation {
+    /** The whole tree, in reading order. */
+    groups: DocsNavGroup[]
+    previousPage: DocsNavItem | null
+    nextPage: DocsNavItem | null
+}
+
+/** Each chapter sits where its first page does. */
+function groupByChapter(items: DocsNavItem[]): DocsNavEntry[] {
+    const chapters = new Map<string, DocsNavItem[]>()
+    const groups: DocsNavEntry[] = []
+
+    for (const item of items) {
+        if (!item.chapter) {
+            groups.push({ type: 'page', item })
+            continue
+        }
+
+        let pages = chapters.get(item.chapter)
+        if (!pages) {
+            pages = []
+            chapters.set(item.chapter, pages)
+            groups.push({ type: 'chapter', chapter: item.chapter, items: pages })
+        }
+        pages.push(item)
+    }
+
+    return groups
+}
+
+/** Each section with pages, under its label, in the order of `sections`. */
+function groupBySection(items: DocsNavItem[], sections: { key: string; label: string }[]): DocsNavGroup[] {
+    return sections.flatMap(({ key, label }) => {
+        const own = items.filter((item) => item.section === key)
+        return own.length > 0 ? [{ type: 'section' as const, section: key, label, entries: groupByChapter(own) }] : []
+    })
+}
+
+/** The navigation seen from one page of `tree`: every group, the page marked
+ *  active, and its neighbours. */
+export function buildDocsNavigation(
+    tree: DocsTree,
+    currentId: string,
+    sections: { key: string; label: string }[] = [],
+): DocsNavigation {
+    const position = tree.byId.get(currentId)?.index ?? -1
+    const items = tree.pages.map((page): DocsNavItem => ({
+        title: page.label,
+        section: page.section,
+        chapter: page.chapter,
+        href: page.href,
+        isActive: page.index === position,
+    }))
+
+    return {
+        groups:
+            sections.length > 0
+                ? [...groupByChapter(items.filter((item) => !item.section)), ...groupBySection(items, sections)]
+                : groupByChapter(items),
+        previousPage: position > 0 ? items[position - 1] : null,
+        nextPage: position >= 0 && position < items.length - 1 ? items[position + 1] : null,
+    }
+}

package/src/docs/routes/404.astro

@@ -0,0 +1,16 @@
+---
+import { withDeploymentBase } from '../../site/urls.ts'
+import Layout from '../layouts/Page.astro'
+
+const homeHref = withDeploymentBase('/', import.meta.env.BASE_URL)
+---
+
+<Layout title="404" description="The page you're looking for doesn't exist.">
+    <div class="jaad-not-found">
+        <h1 class="jaad-not-found-title">404</h1>
+        <p class="jaad-not-found-text">
+            <i>Oops!</i> The page you're looking for doesn't exist.
+        </p>
+        <a href={homeHref}>Go back to the homepage</a>
+    </div>
+</Layout>

package/src/docs/routes/docs-index.astro

@@ -0,0 +1,19 @@
+---
+import { render } from 'astro:content'
+import { withDeploymentBase } from '../../site/urls.ts'
+import { getDocsTree } from '../collection.ts'
+import DocsPage from '../components/DocsPage.astro'
+
+const tree = await getDocsTree()
+
+const page = tree.pages[0]
+if (!page) {
+    return Astro.redirect(withDeploymentBase('/404', import.meta.env.BASE_URL))
+}
+
+const { Content } = await render(page.source)
+---
+
+<DocsPage {page} {tree}>
+    <Content />
+</DocsPage>

package/src/docs/routes/docs-slug.astro

@@ -0,0 +1,54 @@
+---
+import { render } from 'astro:content'
+import { buildLocales, localePrefix } from '../../site/runtime.ts'
+import { withDeploymentBase } from '../../site/urls.ts'
+import { getDocsTree } from '../collection.ts'
+import DocsPage from '../components/DocsPage.astro'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.ts'
+
+interface DocsPath {
+    params: { slug: string }
+    /** `redirect` is the canonical slug of a page reached by another name. */
+    props: { id: string; locale?: string; redirect?: string }
+}
+
+export async function getStaticPaths() {
+    const paths: DocsPath[] = []
+
+    for (const locale of buildLocales()) {
+        const { pages } = await getDocsTree(locale)
+        const prefix = localePrefix(locale)
+
+        for (const page of pages) {
+            const add = (slug: string, redirect?: string) =>
+                paths.push({ params: { slug }, props: { id: page.id, locale, redirect } })
+
+            // Empty is the index route's; a prefixed locale has none, so /it is this page.
+            const own = `${prefix}${page.canonical}`.replace(/\/$/, '')
+            if (own) add(own)
+            for (const alias of page.aliases) add(`${prefix}${alias}`, page.canonical)
+        }
+    }
+
+    return paths
+}
+
+const { id, locale, redirect } = Astro.props
+
+if (redirect !== undefined) {
+    return Astro.redirect(docsPageHref(redirect, docsUrls(locale)), 301)
+}
+
+const tree = await getDocsTree(locale)
+const page = tree.byId.get(id)
+if (!page) {
+    return Astro.redirect(withDeploymentBase('/404', import.meta.env.BASE_URL))
+}
+
+const { Content } = await render(page.source)
+---
+
+<DocsPage {page} {tree} headTitle={page.title}>
+    <Content />
+</DocsPage>

package/src/docs/routes/docs-slug.md.ts

@@ -0,0 +1,35 @@
+import type { APIRoute, GetStaticPaths } from 'astro'
+import { buildLocales, localePrefix } from '../../site/runtime.ts'
+import { getDocsTree } from '../collection.ts'
+
+/** Raw markdown at the page's own url plus `.md`, for readers and for LLMs. */
+export const getStaticPaths: GetStaticPaths = async () => {
+    const paths: {
+        params: { slug: string }
+        props: { id: string; locale?: string }
+    }[] = []
+
+    for (const locale of buildLocales()) {
+        const { pages } = await getDocsTree(locale)
+        const prefix = localePrefix(locale)
+
+        for (const page of pages) {
+            paths.push({
+                params: { slug: `${prefix}${page.slug}` },
+                props: { id: page.id, locale },
+            })
+        }
+    }
+
+    return paths
+}
+
+export const GET: APIRoute = async ({ props }) => {
+    const { id, locale } = props as { id: string; locale?: string }
+    const page = (await getDocsTree(locale)).byId.get(id)
+    if (!page) return new Response('Not found', { status: 404 })
+
+    return new Response(page.source.body ?? '', {
+        headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
+    })
+}

package/src/docs/routes/llms-locale.txt.ts

@@ -0,0 +1,8 @@
+import type { APIRoute, GetStaticPaths } from 'astro'
+import { getServedLocales } from '../collection.ts'
+import { llmsResponse } from '../endpoints.ts'
+
+export const getStaticPaths: GetStaticPaths = async () =>
+    (await getServedLocales()).map((locale) => ({ params: { locale } }))
+
+export const GET: APIRoute = ({ site, params }) => llmsResponse(site, params.locale)

package/src/docs/routes/llms.txt.ts

@@ -0,0 +1,4 @@
+import type { APIRoute } from 'astro'
+import { llmsResponse } from '../endpoints.ts'
+
+export const GET: APIRoute = ({ site }) => llmsResponse(site)

package/src/docs/routes/search-index-locale.json.ts

@@ -0,0 +1,8 @@
+import type { APIRoute, GetStaticPaths } from 'astro'
+import { getServedLocales } from '../collection.ts'
+import { searchIndexResponse } from '../endpoints.ts'
+
+export const getStaticPaths: GetStaticPaths = async () =>
+    (await getServedLocales()).map((locale) => ({ params: { locale } }))
+
+export const GET: APIRoute = ({ params }) => searchIndexResponse(params.locale)

package/src/docs/routes/search-index.json.ts

@@ -0,0 +1,4 @@
+import type { APIRoute } from 'astro'
+import { searchIndexResponse } from '../endpoints.ts'
+
+export const GET: APIRoute = () => searchIndexResponse()

package/src/docs/runtime.ts

@@ -0,0 +1,17 @@
+import type { DocsSection } from './config.ts'
+import type { DocsUrlOptions } from './urls.ts'
+import config from 'virtual:jaad/config'
+import { DEFAULT_LOCALE } from '../site/runtime.ts'
+
+/** The virtual config, read once. */
+export const SECTIONS: DocsSection[] = config.docs.sections
+
+/** The four fields every href builder takes, in one place. */
+export function docsUrls(locale?: string): DocsUrlOptions {
+    return {
+        docsBase: config.docs.base,
+        deploymentBase: import.meta.env.BASE_URL,
+        locale,
+        defaultLocale: DEFAULT_LOCALE,
+    }
+}

package/src/docs/search-index.ts

@@ -0,0 +1,39 @@
+import type { SearchIndex } from '../site/search.ts'
+import type { DocsSection } from './config.ts'
+import type { DocsTree } from './model/tree.ts'
+import { formatChapterTitle } from './model/ids.ts'
+import { pageChunks } from './model/rendered.ts'
+
+/** One entry per h2 and h3 of every page, plus one for the text before them. */
+export function buildSearchIndex(tree: DocsTree, sections: Pick<DocsSection, 'key' | 'label'>[]): SearchIndex {
+    const index: SearchIndex = {
+        sections: sections
+            .filter(({ key }) => tree.pages.some((page) => page.section === key))
+            .map(({ key, label }) => ({ key, label })),
+        pages: [],
+        entries: [],
+    }
+
+    for (const page of tree.pages) {
+        const chapter = formatChapterTitle(page.chapter)
+        const keywords = page.data.keywords ?? []
+        index.pages.push({
+            title: page.title,
+            href: page.href,
+            ...(page.section ? { section: page.section } : {}),
+            ...(chapter ? { chapter } : {}),
+            ...(keywords.length > 0 ? { keywords } : {}),
+        })
+
+        for (const { heading, text } of pageChunks(page.source.rendered)) {
+            if (!heading && !text) continue
+            index.entries.push({
+                page: page.index,
+                ...(heading ? { heading: heading.text, anchor: heading.slug } : {}),
+                text,
+            })
+        }
+    }
+
+    return index
+}

package/src/docs/styles/components/breadcrumbs.css

@@ -0,0 +1,26 @@
+@layer components {
+    .docs-breadcrumbs {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.375rem;
+        margin-bottom: 0.5rem;
+        font-size: 0.8125rem;
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-breadcrumbs-link {
+        color: inherit;
+        text-decoration: none;
+    }
+
+    .docs-breadcrumbs-link:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    /* Narrow, the navigation menu above already names them. */
+    @media (width < 64rem) {
+        [data-jaad-default-frame] .docs-breadcrumbs {
+            display: none;
+        }
+    }
+}

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

@@ -0,0 +1,47 @@
+@layer components {
+    .docs-mobile-nav {
+        margin-bottom: 1.5rem;
+        border-top: 1px solid var(--color-border);
+        font-size: 0.875rem;
+    }
+
+    .docs-mobile-menu {
+        border-bottom: 1px solid var(--color-border);
+    }
+
+    .docs-mobile-summary {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 0.375rem;
+        min-height: 2.75rem;
+        color: var(--color-foreground-muted);
+        cursor: pointer;
+        list-style: none;
+    }
+
+    .docs-mobile-summary::-webkit-details-marker {
+        display: none;
+    }
+
+    .docs-mobile-icon {
+        width: 1rem;
+        height: 1rem;
+        margin-right: 0.25rem;
+    }
+
+    .docs-mobile-current {
+        color: var(--color-foreground-bright);
+        font-weight: 500;
+    }
+
+    .docs-mobile-tree {
+        padding: 0.25rem 0 1rem 0.75rem;
+    }
+
+    @media (min-width: 64rem) {
+        .docs-mobile-nav {
+            display: none;
+        }
+    }
+}

package/src/docs/styles/components/docs-page-nav.css

@@ -0,0 +1,41 @@
+@layer components {
+    .docs-page-nav {
+        margin-top: 3rem;
+        padding-top: 0.5rem;
+        border-top: 1px solid var(--color-border);
+    }
+
+    .docs-page-nav-row {
+        display: flex;
+        justify-content: space-between;
+        gap: 1rem;
+    }
+
+    .docs-page-nav-link {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        min-width: 0;
+        max-width: calc(50% - 0.5rem);
+        min-height: 2.75rem;
+        color: var(--color-foreground-bright);
+        font-size: 0.875rem;
+        text-decoration: none;
+    }
+
+    .docs-page-nav-link:hover {
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-page-nav-icon {
+        flex: none;
+        width: 1rem;
+        height: 1rem;
+    }
+
+    .docs-page-nav-label {
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+}

package/src/docs/styles/components/docs-page.css

@@ -0,0 +1,9 @@
+@layer components {
+    .docs-content {
+        @apply w-full leading-relaxed wrap-break-word;
+    }
+
+    .docs-updated {
+        @apply text-foreground-muted mt-8 text-xs;
+    }
+}

package/src/docs/styles/components/docs-sidebar.css

@@ -0,0 +1,59 @@
+@layer components {
+    .docs-sidebar-left nav {
+        font-size: 0.875rem;
+        line-height: 1.5;
+    }
+
+    .docs-sidebar-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+    }
+
+    /* The bar of the current page sits in the gutter, so every label lines up. */
+    .docs-sidebar-link {
+        display: block;
+        margin-left: -0.75rem;
+        padding: 0.25rem 0 0.25rem calc(0.75rem - 2px);
+        border-left: 2px solid transparent;
+        color: var(--color-foreground);
+        text-decoration: none;
+    }
+
+    .docs-sidebar-link:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    .docs-sidebar-link[aria-current='page'] {
+        border-color: var(--color-foreground-bright);
+        color: var(--color-foreground-bright);
+        font-weight: 500;
+    }
+
+    .docs-sidebar-chapter {
+        margin-top: 1rem;
+    }
+
+    .docs-sidebar-chapter + li:not(.docs-sidebar-chapter) {
+        margin-top: 1rem;
+    }
+
+    .docs-sidebar-chapter-title {
+        margin: 0 0 0.25rem;
+        font-size: 0.75rem;
+        font-weight: 500;
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-sidebar-section {
+        margin-top: 1rem;
+        padding-top: 0.75rem;
+        border-top: 1px solid var(--color-border);
+    }
+
+    .docs-sidebar-section-title {
+        margin: 0 0 0.25rem;
+        color: var(--color-foreground-bright);
+        font-weight: 600;
+    }
+}