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

package/src/docs/advanced.ts

@@ -0,0 +1,23 @@
+import type { DocsNavigation } from './navigation.ts'
+import type { DocsHeading, DocsPageData } from './types.ts'
+
+/** Data available to an advanced documentation frame. */
+export interface DocsFrameProps {
+    page: {
+        /** Content collection id, without the Markdown extension. */
+        id: string
+        /** File-derived slug. The opening page keeps its named slug here. */
+        slug: string
+        title: string
+        /** Set when the docs are split into sections. */
+        section?: string
+        chapter?: string
+        /** Raw frontmatter. */
+        data: DocsPageData
+    }
+    headings: DocsHeading[]
+    navigation: DocsNavigation
+}
+
+export type { DocsHeading, DocsNavItem, DocsPageData } from './types.ts'
+export type { DocsNavEntry, DocsNavGroup, DocsNavigation } from './navigation.ts'

package/src/docs/collection.ts

@@ -0,0 +1,109 @@
+import type { LocaleAlternate } from '../site/locales.ts'
+import type { DocsSource, DocsTree } from './model/tree.ts'
+import type { DocsEntry } from './types.ts'
+import { getCollection } from 'astro:content'
+import config from 'virtual:jaad/config'
+import { DEFAULT_LOCALE, LOCALES, prefixedCodes } from '../site/runtime.ts'
+import { collectionName, splitDocLocale } from './model/ids.ts'
+import { buildDocsTree } from './model/tree.ts'
+import { validateDocsStructure } from './model/validate.ts'
+import { SECTIONS, docsUrls } from './runtime.ts'
+import { docsPageHref } from './urls.ts'
+
+/** A collection entry, placed in its locale and section. */
+export type DocsSourceEntry = DocsEntry & DocsSource
+
+const cached = new Map<string, DocsTree<DocsSourceEntry>>()
+
+const CODES = LOCALES.map((locale) => locale.code)
+
+const KEYS = SECTIONS.map((section) => section.key)
+
+/** Attaches the locale, the section and the path, leaving `id` the collection id. */
+function place(entry: DocsEntry, section?: string): DocsSourceEntry {
+    const { locale, id } = splitDocLocale(entry.id, CODES)
+    return {
+        ...entry,
+        locale: locale ?? undefined,
+        section,
+        path: section ? id.slice(section.length + 1) : id,
+    }
+}
+
+/** The pages of one locale, or every page when the docs are not localised.
+ *  Cached in production only: in dev the module would go stale on edit. */
+export async function getDocsTree(locale: string = DEFAULT_LOCALE): Promise<DocsTree<DocsSourceEntry>> {
+    const key = CODES.length > 0 ? locale : ''
+    const hit = cached.get(key)
+    if (import.meta.env.PROD && hit) return hit
+
+    // `docsDir` when in use, then one collection per section.
+    const sections = [...(config.docs.dirInUse ? [undefined] : []), ...KEYS]
+    const collections = await Promise.all(
+        sections.map(async (section) => {
+            const entries = await getCollection(collectionName(section) as 'docsPages')
+            return (entries as unknown as DocsEntry[]).map((entry) => place(entry, section))
+        }),
+    )
+    const sources = collections.flat().filter((source) => key === '' || source.locale === key)
+
+    // Validated before drafts are dropped, so a draft's slug conflict is an error.
+    validateDocsStructure(sources, key || undefined)
+    const tree = buildDocsTree(import.meta.env.PROD ? sources.filter((source) => !source.data.draft) : sources, {
+        sections: KEYS,
+        urls: docsUrls(locale),
+    })
+    if (import.meta.env.PROD) cached.set(key, tree)
+    return tree
+}
+
+export interface SectionLink {
+    key: string
+    label: string
+    href: string
+}
+
+/** The sections with something to serve in a locale, each at the url of its
+ *  first page. */
+export async function getSectionLinks(locale: string = DEFAULT_LOCALE): Promise<SectionLink[]> {
+    const { pages } = await getDocsTree(locale)
+
+    return SECTIONS.flatMap(({ key, label }) => {
+        const first = pages.find((page) => page.section === key)
+        return first ? [{ key, label, href: first.href }] : []
+    })
+}
+
+/** Where a page lives in every locale, paired by `translationKey` or by slug.
+ *  An untranslated page falls back to that locale's opening page. Empty asks
+ *  for the opening pages themselves. */
+export async function getLocaleAlternates(key: string): Promise<LocaleAlternate[]> {
+    const alternates: LocaleAlternate[] = []
+
+    for (const locale of LOCALES) {
+        const tree = await getDocsTree(locale.code)
+        // Every page drafted leaves a locale with nothing to link to.
+        if (tree.pages.length === 0) continue
+
+        const match = key ? tree.byKey.get(key) : tree.pages[0]
+        alternates.push({
+            locale,
+            translated: Boolean(match),
+            href: match ? match.href : docsPageHref('', docsUrls(locale.code)),
+        })
+    }
+
+    return alternates
+}
+
+/** The prefixed locales that have something to serve. */
+export async function getServedLocales(): Promise<string[]> {
+    const served: string[] = []
+
+    for (const code of prefixedCodes()) {
+        const { pages } = await getDocsTree(code)
+        if (pages.length > 0) served.push(code)
+    }
+
+    return served
+}

package/src/docs/components/Breadcrumbs.astro

@@ -0,0 +1,29 @@
+---
+import { ui } from '../../site/runtime.ts'
+import { getSectionLinks } from '../collection.ts'
+import { formatChapterTitle } from '../model/ids.ts'
+
+interface Props {
+    /** The key of the section the page belongs to. */
+    section?: string
+    chapter?: string
+    locale?: string
+}
+
+const { section, chapter, locale } = Astro.props
+const t = ui(locale)
+const chapterTitle = formatChapterTitle(chapter)
+const sectionLink = section ? (await getSectionLinks(locale)).find((link) => link.key === section) : undefined
+---
+
+{(sectionLink || chapterTitle) && (
+    <nav aria-label={t('breadcrumb.label')} class="docs-breadcrumbs">
+        {sectionLink && (
+            <a href={sectionLink.href} class="docs-breadcrumbs-link">
+                {sectionLink.label}
+            </a>
+        )}
+        {sectionLink && chapterTitle && <span aria-hidden="true">·</span>}
+        {chapterTitle && <span>{chapterTitle}</span>}
+    </nav>
+)}

package/src/docs/components/DocsMobileNav.astro

@@ -0,0 +1,90 @@
+---
+import type { DocsNavGroup } from '../navigation.ts'
+import type { DocsHeading, DocsNavItem } from '../types.ts'
+import { ui } from '../../site/runtime.ts'
+import { formatChapterTitle } from '../model/ids.ts'
+import DocsNavTree from './DocsNavTree.astro'
+
+interface Props {
+    locale?: string
+    groups: DocsNavGroup[]
+    headings: DocsHeading[]
+}
+
+const { groups, headings, locale } = Astro.props
+const t = ui(locale)
+
+/** Section, chapter and page of the current page, as the menu's label. */
+function trail(): string[] {
+    for (const group of groups) {
+        const entries = group.type === 'section' ? group.entries : [group]
+        const section = group.type === 'section' ? [group.label] : []
+        for (const entry of entries) {
+            const items: DocsNavItem[] = entry.type === 'page' ? [entry.item] : entry.items
+            const current = items.find((item) => item.isActive)
+            if (!current) continue
+            const chapter = entry.type === 'chapter' ? [formatChapterTitle(entry.chapter) ?? entry.chapter] : []
+            return [...section, ...chapter, current.title]
+        }
+    }
+    return []
+}
+
+const path = trail()
+---
+
+<div class="docs-mobile-nav">
+    <details class="docs-mobile-menu">
+        <summary class="docs-mobile-summary">
+            <svg class="docs-mobile-icon" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true">
+                <path d="M224,128a8,8,0,0,1-8,8H40a8,8,0,0,1,0-16H216A8,8,0,0,1,224,128ZM40,72H216a8,8,0,0,0,0-16H40a8,8,0,0,0,0,16ZM216,184H40a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Z" />
+            </svg>
+            <span class="jaad-sr-only">{t('nav.documentation')}:</span>
+            {path.map((part, index) => (
+                <>
+                    {index > 0 && <span aria-hidden="true">/</span>}
+                    <span class:list={[index === path.length - 1 && 'docs-mobile-current']}>{part}</span>
+                </>
+            ))}
+        </summary>
+        <nav aria-label={t('nav.documentation')} class="docs-mobile-tree">
+            <DocsNavTree {groups} />
+        </nav>
+    </details>
+
+    {headings.length > 0 && (
+        <details class="docs-mobile-menu">
+            <summary class="docs-mobile-summary">{t('toc.title')}</summary>
+            <nav aria-label={t('toc.label')} class="docs-mobile-tree">
+                <ul class="docs-toc-list">
+                    {headings.map((heading) => (
+                        <li>
+                            <a
+                                href={`#${heading.slug}`}
+                                class:list={['docs-toc-link', heading.depth === 3 && 'docs-toc-link-nested']}
+                            >
+                                {heading.text}
+                            </a>
+                        </li>
+                    ))}
+                </ul>
+            </nav>
+        </details>
+    )}
+</div>
+
+<script>
+    // A chosen entry closes its menu, so the page it opens is not covered.
+    function closeOnChoice(): void {
+        for (const menu of document.querySelectorAll<HTMLDetailsElement>('.docs-mobile-menu')) {
+            if (menu.dataset.navInit) continue
+            menu.dataset.navInit = '1'
+            menu.addEventListener('click', (event) => {
+                if ((event.target as Element).closest('a')) menu.open = false
+            })
+        }
+    }
+
+    closeOnChoice()
+    document.addEventListener('astro:page-load', closeOnChoice)
+</script>

package/src/docs/components/DocsNavTree.astro

@@ -0,0 +1,57 @@
+---
+import type { DocsNavEntry, DocsNavGroup } from '../navigation.ts'
+import { formatChapterTitle } from '../model/ids.ts'
+
+interface Props {
+    groups: DocsNavGroup[]
+}
+
+const { groups } = Astro.props
+
+/** The pages outside every section, then each section with all its pages. */
+const loose = groups.filter((group): group is DocsNavEntry => group.type !== 'section')
+const blocks = [
+    ...(loose.length > 0 ? [{ entries: loose, label: null }] : []),
+    ...groups.flatMap((group) => (group.type === 'section' ? [{ entries: group.entries, label: group.label }] : [])),
+]
+---
+
+{blocks.map(({ entries, label }) => (
+    <div class:list={[label && 'docs-sidebar-section']}>
+        {label && <p class="docs-sidebar-section-title">{label}</p>}
+        {entries.length > 0 && (
+            <ul class="docs-sidebar-list">
+                {entries.map((entry) =>
+                    entry.type === 'page' ? (
+                        <li>
+                            <a
+                                href={entry.item.href}
+                                class="docs-sidebar-link"
+                                aria-current={entry.item.isActive ? 'page' : undefined}
+                            >
+                                {entry.item.title}
+                            </a>
+                        </li>
+                    ) : (
+                        <li class="docs-sidebar-chapter">
+                            <p class="docs-sidebar-chapter-title">{formatChapterTitle(entry.chapter)}</p>
+                            <ul class="docs-sidebar-list">
+                                {entry.items.map((item) => (
+                                    <li>
+                                        <a
+                                            href={item.href}
+                                            class="docs-sidebar-link"
+                                            aria-current={item.isActive ? 'page' : undefined}
+                                        >
+                                            {item.title}
+                                        </a>
+                                    </li>
+                                ))}
+                            </ul>
+                        </li>
+                    ),
+                )}
+            </ul>
+        )}
+    </div>
+))}

package/src/docs/components/DocsPage.astro

@@ -0,0 +1,66 @@
+---
+import type { DocsSourceEntry } from '../collection.ts'
+import type { DocsPage, DocsTree } from '../model/tree.ts'
+import MarkdownContent from '@jaamd/astro/components'
+import config from 'virtual:jaad/config'
+import { DEFAULT_LOCALE, LOCALES, ui } from '../../site/runtime.ts'
+import DocsLayout from '../layouts/Docs.astro'
+import { pageHeadings } from '../model/rendered.ts'
+import { buildDocsNavigation } from '../navigation.ts'
+import { SECTIONS } from '../runtime.ts'
+import Breadcrumbs from './Breadcrumbs.astro'
+import DocsMobileNav from './DocsMobileNav.astro'
+import DocsPageNav from './DocsPageNav.astro'
+import PageActions from './PageActions.astro'
+
+interface Props {
+    page: DocsPage<DocsSourceEntry>
+    tree: DocsTree<DocsSourceEntry>
+    /** Left out on the opening page, whose title is the site name alone. */
+    headTitle?: string
+}
+
+const { page, tree, headTitle } = Astro.props
+
+const section = SECTIONS.find((known) => known.key === page.section)
+// With sections, the title names the section after the page.
+const title = headTitle && section ? `${headTitle} · ${section.label}` : headTitle
+// A section's files sit in its own directory.
+const editBase = section ? section.editBase : config.docs.editBase
+const editPath = [page.locale, page.path].filter(Boolean).join('/')
+const headings = pageHeadings(page.source.rendered)
+const t = ui(page.locale)
+const language = LOCALES.find((known) => known.code === (page.locale ?? DEFAULT_LOCALE))?.tag ?? config.lang
+const updated = page.data.lastUpdated
+const navigation = buildDocsNavigation(tree, page.id, SECTIONS)
+const contentAttrs = { id: 'content' }
+---
+
+<DocsLayout {title} {page} {headings} {navigation}>
+    <DocsMobileNav slot="mobile-navigation" groups={navigation.groups} headings={headings} locale={page.locale} />
+
+    <Breadcrumbs slot="breadcrumbs" section={page.section} chapter={page.chapter} locale={page.locale} />
+    <PageActions slot="page-actions" {editBase} {editPath} cleanSlug={page.slug} locale={page.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={page.locale}
+    />
+</DocsLayout>

package/src/docs/components/DocsPageNav.astro

@@ -0,0 +1,53 @@
+---
+import type { DocsNavItem } from '../types.ts'
+import { ui } from '../../site/runtime.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"
+                        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"
+                        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/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/docs/components/PageActions.astro

@@ -0,0 +1,83 @@
+---
+import { editUrl } from '../../site/infer.ts'
+import { ui } from '../../site/runtime.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsMarkdownHref } from '../urls.ts'
+
+interface Props {
+    /** 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 { editBase, editPath, cleanSlug, locale } = Astro.props
+const t = ui(locale)
+
+const mdHref = docsMarkdownHref(cleanSlug, docsUrls(locale))
+const editHref = editBase ? editUrl(editBase, `${editPath}.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/docs/components/StructuredData.astro

@@ -0,0 +1,55 @@
+---
+import config from 'virtual:jaad/config'
+import { formatChapterTitle } from '../model/ids.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.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 />}