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

package/src/docs/layouts/Docs.astro

@@ -0,0 +1,169 @@
+---
+import type { DocsFrameProps } from '../advanced.ts'
+import type { DocsSourceEntry } from '../collection.ts'
+import type { DocsPage } from '../model/tree.ts'
+import type { DocsNavigation } from '../navigation.ts'
+import type { DocsHeading } from '../types.ts'
+import { ClientRouter } from 'astro:transitions'
+import config from 'virtual:jaad/config'
+import DocsFrame from 'virtual:jaad/docs-frame'
+import Footer from '../../site/components/Footer.astro'
+import Head from '../../site/components/Head.astro'
+import Header from '../../site/components/Header.astro'
+import { DEFAULT_LOCALE, LOCALES } from '../../site/runtime.ts'
+import { getLocaleAlternates } from '../collection.ts'
+import DocsSidebarLeft from '../components/DocsSidebarLeft.astro'
+import StructuredData from '../components/StructuredData.astro'
+import TableOfContents from '../components/TableOfContents.astro'
+import { pageDescription } from '../model/rendered.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.ts'
+import '../../../dist/jaad.css'
+import '../styles/docs.css'
+import '../styles/jaamd.css'
+import '@jaamd/astro/styles.css'
+import 'virtual:jaad/theme.css'
+import 'virtual:jaad/bridge.css'
+import 'virtual:jaad/user.css'
+import 'virtual:jaad/tailwind.css'
+
+interface Props {
+    /** The `<title>` before the site name. Left out on the opening page. */
+    title?: string
+    page: DocsPage<DocsSourceEntry>
+    headings?: DocsHeading[]
+    navigation: DocsNavigation
+}
+
+const { title, page, headings = [], navigation } = Astro.props
+
+const pageTitle = title ? `${title} | ${config.title}` : config.title
+
+const description =
+    page.data.description ?? pageDescription(page.source.rendered, page.title) ?? config.description ?? config.title
+
+const locale = page.locale ?? DEFAULT_LOCALE
+const language = LOCALES.find((known) => known.code === locale)?.tag ?? config.lang
+
+const indexUrl = docsPageHref('search-index.json', docsUrls(locale))
+
+const switcherAlternates = await getLocaleAlternates(page.translationKey)
+
+// x-default is a landing place, so it takes the fallback when this page has no
+// translation into the default locale.
+const xDefault = switcherAlternates.find((alternate) => alternate.locale.code === DEFAULT_LOCALE)?.href
+
+// hreflang describes translations of this page, not the switcher's fallbacks.
+const alternates = switcherAlternates
+    .filter((alternate) => alternate.translated)
+    .map((alternate) => ({
+        code: alternate.locale.code,
+        tag: alternate.locale.tag,
+        href: alternate.href,
+    }))
+
+const frameProps: DocsFrameProps = {
+    page: {
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        section: page.section,
+        chapter: page.chapter,
+        data: page.data,
+    },
+    headings,
+    navigation,
+}
+---
+
+<!doctype html>
+<html lang={language} class={config.appearance === 'dark' ? 'dark' : undefined}>
+    <head>
+        <Head
+            title={pageTitle}
+            description={description}
+            keywords={page.data.keywords}
+            author={page.data.author}
+            image={page.data.ogImage}
+            modified={page.data.lastUpdated}
+            language={language}
+            {alternates}
+            {xDefault}
+        />
+        <StructuredData
+            title={page.title || config.title}
+            description={description}
+            chapter={page.chapter}
+            keywords={page.data.keywords}
+            author={page.data.author}
+            modified={page.data.lastUpdated}
+            {language}
+            {locale}
+        />
+        <ClientRouter />
+    </head>
+    <body data-docs class="jaad-body">
+        <DocsFrame {...frameProps}>
+            <Header slot="header" {locale} alternates={switcherAlternates} search={{ indexUrl, prominent: true }} />
+            <DocsSidebarLeft slot="sidebar" groups={navigation.groups} {locale} />
+            <slot name="mobile-navigation" slot="mobile-navigation" />
+            <slot name="breadcrumbs" slot="breadcrumbs" />
+            <slot name="page-actions" slot="page-actions" />
+            <slot name="content" slot="content" />
+            <slot name="page-navigation" slot="page-navigation" />
+            <TableOfContents slot="table-of-contents" headings={headings} {locale} />
+            <Footer slot="footer" />
+        </DocsFrame>
+
+        <script>
+            import { navigate } from 'astro:transitions/client'
+
+            /** Identified by `rel`. */
+            function getPageLinks(): {
+                prev: HTMLAnchorElement | null
+                next: HTMLAnchorElement | null
+            } {
+                const nav = document.querySelector('nav[aria-label="Page navigation"]')
+                if (!nav) return { prev: null, next: null }
+                return {
+                    prev: nav.querySelector<HTMLAnchorElement>('a[rel~="prev"][href]'),
+                    next: nav.querySelector<HTMLAnchorElement>('a[rel~="next"][href]'),
+                }
+            }
+
+            /** A wide table or code block: the arrow keys should scroll it instead. */
+            function inHorizontallyScrollable(el: Element | null): boolean {
+                for (let node = el; node && node !== document.body;) {
+                    if (node instanceof HTMLElement) {
+                        const overflowX = getComputedStyle(node).overflowX
+                        if ((overflowX === 'auto' || overflowX === 'scroll') && node.scrollWidth > node.clientWidth)
+                            return true
+                    }
+                    node = node.parentElement
+                }
+                return false
+            }
+
+            function onKey(e: KeyboardEvent) {
+                // Leave modified chords alone, notably the browser's back/forward.
+                if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return
+                if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return
+
+                const active = document.activeElement as HTMLElement | null
+                const tag = active?.tagName
+                if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return
+                if (active?.isContentEditable) return
+                if (inHorizontallyScrollable(active)) return
+
+                const { prev, next } = getPageLinks()
+                const target = e.key === 'ArrowLeft' ? prev : next
+                if (!target) return
+                e.preventDefault()
+                navigate(target.href)
+            }
+
+            // `document` survives View Transitions, and this module runs once.
+            document.addEventListener('keydown', onKey)
+        </script>
+    </body>
+</html>

package/src/docs/layouts/Page.astro

@@ -0,0 +1,18 @@
+---
+import type { ComponentProps } from 'astro/types'
+import Shell from '../../site/layouts/Shell.astro'
+import { DEFAULT_LOCALE } from '../../site/runtime.ts'
+import { getLocaleAlternates } from '../collection.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.ts'
+
+type Props = Omit<ComponentProps<typeof Shell>, 'header'>
+
+// A page of the project's own has no translations: offer each locale's opener.
+const alternates = await getLocaleAlternates('')
+const indexUrl = docsPageHref('search-index.json', docsUrls(DEFAULT_LOCALE))
+---
+
+<Shell {...Astro.props} header={{ alternates, search: { indexUrl } }}>
+    <slot />
+</Shell>

package/src/docs/link-plugins.ts

@@ -0,0 +1,52 @@
+import type { DocLinkContext } from './links.ts'
+import { fileURLToPath } from 'node:url'
+import { resolveDocLink } from './links.ts'
+
+interface HastNode {
+    type: string
+    tagName?: string
+    properties?: Record<string, unknown>
+    children?: HastNode[]
+}
+
+/** rehype: rewrites relative links to markdown files into page urls. */
+export function rehypeDocLinks(context: DocLinkContext) {
+    return function jaadDocLinks() {
+        return (tree: HastNode, file: { path?: string }) => {
+            const from = file.path
+            if (!from) return
+
+            const visit = (node: HastNode) => {
+                const href = node.tagName === 'a' ? node.properties?.href : undefined
+                if (typeof href === 'string') {
+                    const resolved = resolveDocLink(href, from, context)
+                    if (resolved) node.properties!.href = resolved
+                }
+                node.children?.forEach(visit)
+            }
+            visit(tree)
+        }
+    }
+}
+
+interface SatteriContext {
+    fileURL: URL | undefined
+    setProperty(node: HastNode, name: string, value: string): void
+}
+
+/** Sätteri: rewrites relative links to markdown files into page urls. */
+export function satteriDocLinks(context: DocLinkContext) {
+    return {
+        name: 'jaad-doc-links',
+        element: {
+            filter: ['a'],
+            visit(node: HastNode, ctx: SatteriContext) {
+                const href = node.properties?.href
+                if (typeof href !== 'string' || !ctx.fileURL) return
+
+                const resolved = resolveDocLink(href, fileURLToPath(ctx.fileURL), context)
+                if (resolved) ctx.setProperty(node, 'href', resolved)
+            },
+        },
+    }
+}

package/src/docs/links.ts

@@ -0,0 +1,42 @@
+import type { DocsRoot } from './config.ts'
+import type { DocsUrlOptions } from './urls.ts'
+import { existsSync } from 'node:fs'
+import { dirname, relative, resolve, sep } from 'node:path'
+import { getDocCollectionId, namedSlug, splitDocLocale } from './model/ids.ts'
+import { docsPageHref } from './urls.ts'
+
+export interface DocLinkContext {
+    roots: DocsRoot[]
+    locales: string[]
+    urls: (locale?: string) => DocsUrlOptions
+}
+
+/**
+ * The url of the page a relative link to a markdown file points at, or null
+ * when the link is not one: absolute, external, or to a file outside the docs.
+ */
+export function resolveDocLink(href: string, fromFile: string, context: DocLinkContext): string | null {
+    if (/^([a-z][a-z\d+.-]*:|\/|#)/i.test(href)) return null
+
+    const [path, hash = ''] = href.split('#', 2)
+    if (!path.endsWith('.md')) return null
+
+    let decoded: string
+    try {
+        decoded = decodeURI(path)
+    } catch {
+        return null
+    }
+
+    const target = resolve(dirname(fromFile), decoded)
+    const root = context.roots.find(({ dir }) => target.startsWith(dir + sep))
+    if (!root) return null
+
+    if (!existsSync(target)) {
+        throw new Error(`jaad: ${fromFile} links to ${href}, which does not exist`)
+    }
+
+    const { locale, id } = splitDocLocale(getDocCollectionId(relative(root.dir, target)), context.locales)
+    const slug = namedSlug(id, root.section)
+    return docsPageHref(slug, context.urls(locale ?? undefined)) + (hash ? `#${hash}` : '')
+}

package/src/docs/locale-tree.ts

@@ -0,0 +1,51 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { isLocale } from '../site/locales.ts'
+
+function hasMarkdown(dir: string): boolean {
+    return readdirSync(dir, { withFileTypes: true }).some((entry) =>
+        entry.isDirectory() ? hasMarkdown(join(dir, entry.name)) : entry.name.endsWith('.md'),
+    )
+}
+
+/** Locale directories under docs/, or none. Two mean the tree is organised by
+ *  language; one counts only when `lang` names it. */
+export function detectLocales(docsDir: string, lang: string): string[] {
+    if (!existsSync(docsDir)) return []
+
+    const candidates = readdirSync(docsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && isLocale(entry.name))
+        .map((entry) => entry.name.toLowerCase())
+        .toSorted()
+
+    const localised = candidates.length >= 2 || (candidates.length === 1 && candidates[0] === lang.toLowerCase())
+    if (!localised) return []
+
+    // An empty directory would reach the switcher and answer 404.
+    return candidates.filter((code) => hasMarkdown(join(docsDir, code)))
+}
+
+/** Once localised, every top-level entry is a locale and `lang` names one. */
+export function validateLocaleTree(docsDir: string, locales: string[], lang: string): void {
+    const issues: string[] = []
+
+    const strays = readdirSync(docsDir, { withFileTypes: true })
+        .filter((entry) => !(entry.isDirectory() && isLocale(entry.name)))
+        .map((entry) => entry.name)
+        .toSorted()
+
+    for (const stray of strays) {
+        issues.push(`docs/${stray} is not a locale, but ${locales.join(', ')} are`)
+    }
+
+    if (!locales.includes(lang.toLowerCase())) {
+        issues.push(`lang is "${lang}", which has no directory; found ${locales.join(', ')}`)
+    }
+
+    if (issues.length > 0) {
+        throw new Error(
+            `jaad: mixed documentation tree\n${issues.map((issue) => `  ${issue}`).join('\n')}\n` +
+                'Move every page under a locale directory, or set locales: false.',
+        )
+    }
+}

package/src/docs/model/ids.ts

@@ -0,0 +1,87 @@
+import { slug as githubSlug } from 'github-slugger'
+import { ucfirst } from '../../site/helpers.ts'
+
+/** A numeric order prefix, e.g. "01-" or "123-". */
+const NUMBERED_PREFIX_RE = /^(\d+)-(.+)$/
+
+/** What a page's path says: its file order, its chapter and its own name. */
+export interface ParsedDocPath {
+    /** The file name without its order prefix. */
+    slug: string
+    order: number
+    /** The chapter directory without its order prefix. */
+    chapter?: string
+    orderChapter?: number
+}
+
+export function parseDocPath(path: string): ParsedDocPath {
+    const parts = path.split('/')
+    const name = NUMBERED_PREFIX_RE.exec(parts[parts.length - 1])
+    const directory = parts.length >= 2 ? parts[parts.length - 2] : undefined
+    const chapter = directory ? NUMBERED_PREFIX_RE.exec(directory) : null
+
+    return {
+        slug: name ? name[2] : parts[parts.length - 1],
+        order: name ? parseInt(name[1], 10) : 999,
+        chapter: chapter ? chapter[2] : directory,
+        orderChapter: chapter ? parseInt(chapter[1], 10) : undefined,
+    }
+}
+
+/** "01-chapter/02-section" → "chapter/section" */
+export function getCleanSlug(id: string): string {
+    return id
+        .split('/')
+        .map((part) => part.replace(NUMBERED_PREFIX_RE, '$2'))
+        .join('/')
+}
+
+/** A page's named url below the docs mount: its section, then its clean path. */
+export function namedSlug(path: string, section?: string): string {
+    const slug = getCleanSlug(path)
+    return section ? `${section}/${slug}` : slug
+}
+
+/** "it/02-guides/01-setup" becomes locale "it" and "02-guides/01-setup". */
+export function splitDocLocale(id: string, locales: string[]): { locale: string | null; id: string } {
+    const slash = id.indexOf('/')
+    if (slash === -1) return { locale: null, id }
+
+    const first = id.slice(0, slash)
+    if (!locales.includes(first)) return { locale: null, id }
+    return { locale: first, id: id.slice(slash + 1) }
+}
+
+/** Match the ids produced by Astro's glob loader, independently of the OS. */
+export function getDocCollectionId(filePath: string): string {
+    return filePath
+        .replace(/\.md$/, '')
+        .split(/[\\/]/)
+        .map((part) => githubSlug(part))
+        .join('/')
+}
+
+/** The collection holding the docs, or the pages of one section. */
+export function collectionName(section?: string): string {
+    return section ? `docsPages-${section}` : 'docsPages'
+}
+
+/** The id of a file given relative to its docs directory: its locale, the
+ *  section that directory is, then its path. */
+export function collectionIdFor(filePath: string, section: string | undefined, locales: string[]): string {
+    const { locale, id } = splitDocLocale(getDocCollectionId(filePath), locales)
+    return [locale, section, id].filter(Boolean).join('/')
+}
+
+/** Decodes percent-escapes, so "detail_%26_summary" → "Detail & Summary". */
+export function slugToTitle(slug: string): string {
+    return slug
+        .split(/[-_]+/)
+        .map((word) => ucfirst(decodeURIComponent(word)))
+        .join(' ')
+}
+
+export function formatChapterTitle(chapter: string | undefined): string | null {
+    if (!chapter) return null
+    return slugToTitle(chapter)
+}

package/src/docs/model/rendered.ts

@@ -0,0 +1,185 @@
+import type { DocsHeading } from '../types.ts'
+
+/** What Astro's renderer leaves on a markdown entry. */
+export interface RenderedMarkdown {
+    html: string
+    metadata?: { headings?: { depth: number; slug: string; text: string }[] }
+}
+
+/** Elements whose text is not prose: code, controls, icons, and in-page navigation. */
+const DROPPED = /<(pre|button|svg|nav|script|style|template)\b[^>]*>[\s\S]*?<\/\1>|<!--[\s\S]*?-->/gi
+
+const BLOCK =
+    /<\/?(address|article|aside|blockquote|br|dd|details|div|dl|dt|figcaption|figure|footer|h[1-6]|header|hr|li|ol|p|section|summary|table|tbody|td|tfoot|th|thead|tr|ul)\b[^>]*>/gi
+
+const NAMED: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' }
+
+function decodeEntities(text: string): string {
+    return text.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, name: string) => {
+        if (name[0] !== '#') return NAMED[name.toLowerCase()] ?? entity
+        const code = name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10)
+        return Number.isNaN(code) ? entity : String.fromCodePoint(code)
+    })
+}
+
+/** The readable text of an HTML fragment, on one line. */
+export function htmlText(html: string): string {
+    return decodeEntities(
+        html
+            .replace(DROPPED, ' ')
+            .replace(BLOCK, ' ')
+            .replace(/<[^>]*>/g, ''),
+    )
+        .replace(/\s+/g, ' ')
+        .trim()
+}
+
+const VOID = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'source',
+    'track',
+    'wbr',
+])
+
+const TAG = /<(\/?)([a-zA-Z][\w-]*)([^>]*)>/g
+
+interface HeadingTag {
+    depth: number
+    id: string
+    /** Inside an element with `data-toc-ignore`, or carrying it. */
+    ignored: boolean
+    /** Where the opening tag starts, and where the closing one ends. */
+    start: number
+    end: number
+}
+
+/** Every heading of the page, and whether a `data-toc-ignore` element holds it.
+ *  Read from the HTML: an element written as raw HTML wraps what follows it
+ *  only there, not in the syntax tree. */
+function headingTags(html: string): HeadingTag[] {
+    const headings: HeadingTag[] = []
+    let ignored: { tag: string; depth: number } | null = null
+    let open: HeadingTag | null = null
+
+    for (const match of html.matchAll(TAG)) {
+        const [whole, closing, name, attrs] = match
+        const tag = name.toLowerCase()
+        const selfClosing = VOID.has(tag) || attrs.trimEnd().endsWith('/')
+
+        if (ignored && tag === ignored.tag && !selfClosing) {
+            ignored.depth += closing ? -1 : 1
+            if (ignored.depth === 0) ignored = null
+        } else if (!ignored && !closing && !selfClosing && /\sdata-toc-ignore\b/i.test(attrs)) {
+            ignored = { tag, depth: 1 }
+        }
+
+        const heading = /^h([1-6])$/.exec(tag)
+        if (!heading) continue
+        if (!closing) {
+            open = {
+                depth: Number(heading[1]),
+                id: /\sid="([^"]*)"/.exec(attrs)?.[1] ?? '',
+                ignored: ignored !== null || /\sdata-toc-ignore\b/i.test(attrs),
+                start: match.index,
+                end: match.index + whole.length,
+            }
+        } else if (open) {
+            open.end = match.index + whole.length
+            headings.push(open)
+            open = null
+        }
+    }
+
+    return headings
+}
+
+/** The first h1, as the renderer read it. */
+export function renderedTitle(rendered: RenderedMarkdown | undefined): string | null {
+    return rendered?.metadata?.headings?.find((heading) => heading.depth === 1)?.text ?? null
+}
+
+const isOutline = (heading: HeadingTag) => !heading.ignored && (heading.depth === 2 || heading.depth === 3)
+
+function headingOf(tag: HeadingTag, rendered: RenderedMarkdown): DocsHeading {
+    const known = rendered.metadata?.headings?.find((heading) => heading.slug === tag.id)
+    return {
+        depth: tag.depth as 2 | 3,
+        slug: tag.id,
+        text: known?.text ?? htmlText(rendered.html.slice(tag.start, tag.end)),
+    }
+}
+
+/** The h2 and h3 of the page outside `data-toc-ignore`: its table of contents. */
+export function pageHeadings(rendered: RenderedMarkdown | undefined): DocsHeading[] {
+    if (!rendered) return []
+    return headingTags(rendered.html)
+        .filter(isOutline)
+        .map((tag) => headingOf(tag, rendered))
+}
+
+/** A stretch of a page: the text under one h2 or h3, or before the first. */
+export interface DocsChunk {
+    heading: DocsHeading | null
+    text: string
+}
+
+/** The page cut at the headings of its table of contents. The h1 is left out;
+ *  any other heading stays in the text of the stretch it sits in. */
+export function pageChunks(rendered: RenderedMarkdown | undefined): DocsChunk[] {
+    if (!rendered) return [{ heading: null, text: '' }]
+    const { html } = rendered
+    const tags = headingTags(html)
+    const titles = tags.filter((tag) => tag.depth === 1)
+    const cuts = tags.filter(isOutline)
+
+    /** The text from `from` to `to`, without the h1. */
+    const between = (from: number, to: number) => {
+        let text = ''
+        let at = from
+        for (const title of titles) {
+            if (title.end <= from || title.start >= to) continue
+            text += html.slice(at, title.start) + ' '
+            at = title.end
+        }
+        return htmlText(text + html.slice(at, to))
+    }
+
+    return [
+        { heading: null, text: between(0, cuts[0]?.start ?? html.length) },
+        ...cuts.map((tag, at) => ({
+            heading: headingOf(tag, rendered),
+            text: between(tag.end, cuts[at + 1]?.start ?? html.length),
+        })),
+    ]
+}
+
+/** The first paragraph that is not the title, cut to `maxLength` at a word,
+ *  for `<meta name="description">`. */
+export function pageDescription(
+    rendered: RenderedMarkdown | undefined,
+    title: string,
+    maxLength: number = 155,
+): string | null {
+    if (!rendered) return null
+    const prose = rendered.html.replace(DROPPED, ' ')
+    const paragraphs = [...prose.matchAll(/<p\b([^>]*)>([\s\S]*?)<\/p>/gi)]
+        .filter(([, attrs]) => !/markdown-alert-title/.test(attrs))
+        .map(([, , inner]) => htmlText(inner))
+
+    const first = paragraphs.find((text) => text && text.toLowerCase() !== title.trim().toLowerCase())
+    if (!first) return null
+
+    if (first.length <= maxLength) return first
+    const truncated = first.slice(0, maxLength)
+    const lastSpace = truncated.lastIndexOf(' ')
+    return `${truncated.slice(0, lastSpace > 0 ? lastSpace : maxLength)}…`
+}