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

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

@@ -0,0 +1,51 @@
+@layer components {
+    .docs-page-actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.25rem 1.25rem;
+        margin-top: 2rem;
+        font-size: 0.8125rem;
+    }
+
+    .docs-page-action {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        min-height: 2.75rem;
+        padding: 0;
+        border: 0;
+        background: none;
+        color: var(--color-foreground-muted);
+        font: inherit;
+        text-decoration: none;
+        cursor: pointer;
+    }
+
+    .docs-page-action:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    .docs-page-action-icon {
+        flex: none;
+        width: 0.875rem;
+        height: 0.875rem;
+    }
+
+    /* Under the table of contents: a column of quiet links. */
+    @media (min-width: 64rem) {
+        .docs-page-actions {
+            flex-direction: column;
+            margin-top: 0;
+        }
+
+        .docs-page-action {
+            min-height: 1.75rem;
+        }
+
+        .docs-toc ~ .docs-page-actions {
+            margin-top: 1.5rem;
+            padding-top: 1rem;
+            border-top: 1px solid var(--color-border);
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+@layer components {
+    .docs-toc-title {
+        margin: 0 0 0.5rem;
+        font-family: var(--font-sans);
+        font-size: 0.75rem;
+        font-weight: 500;
+        color: var(--color-foreground-muted);
+    }
+
+    .docs-toc-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+    }
+
+    .docs-toc-link {
+        display: block;
+        padding: 0.1875rem 0 0.1875rem calc(0.625rem - 2px);
+        border-left: 2px solid transparent;
+        color: var(--color-foreground-muted);
+        font-size: 0.8125rem;
+        line-height: 1.5;
+        text-decoration: none;
+    }
+
+    .docs-toc-link-nested {
+        padding-left: calc(1.375rem - 2px);
+    }
+
+    .docs-toc-link:hover {
+        color: var(--color-foreground-bright);
+    }
+
+    .docs-toc-link[aria-current='location'] {
+        border-color: var(--color-foreground-bright);
+        color: var(--color-foreground-bright);
+    }
+}

package/src/docs/styles/components.css

@@ -0,0 +1,7 @@
+@import './components/docs-page.css';
+@import './components/docs-sidebar.css';
+@import './components/toc.css';
+@import './components/docs-mobile-nav.css';
+@import './components/docs-page-nav.css';
+@import './components/page-actions.css';
+@import './components/breadcrumbs.css';

package/src/docs/styles/docs.css

@@ -0,0 +1,81 @@
+/* Layered, so a page's own utilities still win. */
+@layer components {
+    .docs-frame {
+        display: contents;
+    }
+
+    /* The header's column. Wide, it holds the page between two sidebars fixed
+     to the window: only the page scrolls. */
+    .docs-container {
+        width: 100%;
+        max-width: var(--jaad-chrome-width);
+        margin-inline: auto;
+        padding-inline: 1rem;
+    }
+
+    .docs-main {
+        width: 100%;
+        min-width: 0;
+        max-width: var(--jaad-content-width);
+        margin-inline: auto;
+    }
+
+    .docs-page-main {
+        padding-top: 2rem;
+    }
+
+    [data-jaad-default-frame] .docs-container > .jaad-footer {
+        width: 100%;
+        max-width: var(--jaad-content-width);
+        margin-inline: auto;
+    }
+
+    @media (48rem <= width < 64rem) {
+        .docs-page-main {
+            padding-inline: var(--jaad-page-padding);
+        }
+    }
+
+    @media (min-width: 64rem) {
+        .docs-page-main {
+            padding-top: 2.5rem;
+        }
+
+        [data-jaad-default-frame] .docs-container {
+            display: grid;
+            grid-template-columns: var(--jaad-sidebar-width) minmax(0, 1fr) var(--jaad-sidebar-width);
+            column-gap: 3rem;
+        }
+
+        [data-jaad-default-frame] .docs-main,
+        [data-jaad-default-frame] .docs-container > .jaad-footer {
+            grid-column: 2;
+        }
+
+        [data-jaad-default-frame] .docs-sidebar-left,
+        [data-jaad-default-frame] .docs-sidebar-right {
+            position: fixed;
+            top: var(--jaad-header-height);
+            bottom: 0;
+            padding-block: 2rem;
+        }
+
+        /* Widened into the gutter, where the bar of the current page sits. */
+        [data-jaad-default-frame] .docs-sidebar-left {
+            left: max(1rem, calc(50% - var(--jaad-chrome-width) / 2 + 1rem));
+            margin-left: -0.75rem;
+            padding-left: 0.75rem;
+        }
+
+        [data-jaad-default-frame] .docs-sidebar-right {
+            right: max(1rem, calc(50% - var(--jaad-chrome-width) / 2 + 1rem));
+        }
+    }
+
+    @media (width < 64rem) {
+        [data-jaad-default-frame] .docs-sidebar-left,
+        [data-jaad-default-frame] .docs-sidebar-right .docs-toc {
+            display: none;
+        }
+    }
+}

package/src/docs/styles/jaamd.css

@@ -0,0 +1,11 @@
+/* Bridge to JAAMD. */
+
+:root {
+    --jaamd-font-sans: var(--font-sans);
+    --jaamd-font-serif: var(--font-serif);
+    --jaamd-font-mono: var(--font-mono);
+    --jaamd-font-size: 1.125rem;
+    --jaamd-line-height: 1.6;
+
+    --jaamd-scroll-margin-top: 0;
+}

package/src/docs/types.ts

@@ -0,0 +1,39 @@
+import type { RenderedMarkdown } from './model/rendered.ts'
+
+export interface DocsNavItem {
+    title: string
+    /** Set when the docs are split into sections. */
+    section?: string
+    chapter?: string
+    href: string
+    isActive: boolean
+}
+
+export interface DocsHeading {
+    depth: 2 | 3
+    slug: string
+    text: string
+}
+
+/** Resolved frontmatter. Mirrors the schema in content.ts. */
+export interface DocsPageData {
+    title?: string
+    description?: string
+    label?: string
+    translationKey?: string
+    order?: number
+    draft: boolean
+    keywords: string[]
+    author?: string
+    ogImage?: string | false
+    lastUpdated?: Date
+}
+
+/** The shape jaad requires of a docs collection entry. Astro generates
+ *  collection types in the consumer project, so the package states its own contract. */
+export interface DocsEntry {
+    id: string
+    body?: string
+    data: DocsPageData
+    rendered?: RenderedMarkdown
+}

package/src/docs/urls.ts

@@ -0,0 +1,35 @@
+import { localeSegment } from '../site/locales.ts'
+import { normaliseBasePath, withDeploymentBase } from '../site/urls.ts'
+
+export interface DocsUrlOptions {
+    /** routeBase, normalised here: empty at the application root. */
+    docsBase: string
+    /** Astro's deployment base. */
+    deploymentBase?: string
+    /** Locale of the page, when the docs are localised. */
+    locale?: string
+    /** The one locale that owns the unprefixed urls. */
+    defaultLocale?: string
+}
+
+/** Public href for a documentation page. Empty slug means the opening page. */
+export function docsPageHref(slug: string, urls: DocsUrlOptions): string {
+    return docsHref(slug, urls)
+}
+
+/** Raw Markdown keeps the page's named slug, including for the opener. */
+export function docsMarkdownHref(slug: string, urls: DocsUrlOptions): string {
+    return docsHref(slug, urls, '.md')
+}
+
+function docsHref(
+    slug: string,
+    { docsBase, deploymentBase = '', locale, defaultLocale }: DocsUrlOptions,
+    suffix = '',
+): string {
+    const mount = normaliseBasePath(docsBase)
+    const path = [localeSegment(locale, defaultLocale), slug].filter(Boolean).join('/')
+    // Without a suffix an empty path is the mount itself; with one it is a file.
+    const href = path || suffix ? `${mount}/${path}${suffix}` : mount || '/'
+    return withDeploymentBase(href, deploymentBase)
+}

package/src/env.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="astro/client" />
+
+declare module 'virtual:jaad/config' {
+    // oxlint-disable-next-line typescript/consistent-type-imports
+    const config: import('./config.ts').JaadResolvedConfig
+    export default config
+}
+
+declare module 'virtual:jaad/docs-frame' {
+    // oxlint-disable-next-line typescript/consistent-type-imports
+    const DocsFrame: typeof import('./docs/layouts/DefaultDocsFrame.astro').default
+    export default DocsFrame
+}

package/src/integration.ts

@@ -0,0 +1,36 @@
+import type { JaadResolvedConfig } from './config.ts'
+import type { IntegrationState } from './docs/integration.ts'
+import type { SiteStylesheets } from './site/virtual.ts'
+import type { AstroIntegration } from 'astro'
+import { setupDocs } from './docs/integration.ts'
+import { setupSite } from './site/integration.ts'
+import { normaliseBasePath } from './site/urls.ts'
+
+/** The site, then the docs on it. */
+export function createJaadIntegration(
+    config: JaadResolvedConfig,
+    stylesheets: SiteStylesheets,
+    state: IntegrationState,
+    discoverAliases: boolean,
+): AstroIntegration {
+    return {
+        name: 'jaad',
+        hooks: {
+            'astro:config:setup': (params) => {
+                setupSite(params, config, stylesheets)
+                setupDocs(params, config, state, discoverAliases)
+            },
+
+            'astro:config:done': ({ config: astroConfig, injectTypes }) => {
+                state.deploymentBase = normaliseBasePath(astroConfig.base)
+                injectTypes({
+                    filename: 'jaad.d.ts',
+                    content: `declare module "virtual:jaad/config" {
+  const config: import("@jaamd/jaad").JaadResolvedConfig;
+  export default config;
+}`,
+                })
+            },
+        },
+    }
+}

package/src/site/components/Footer.astro

@@ -0,0 +1,18 @@
+---
+import config from 'virtual:jaad/config'
+
+const CREDIT = 'Built with <a href="https://docs.jaamd.org/jaad" rel="noopener">JAAD</a>.'
+
+// Unset is the credit alone; `footer: false` removes it.
+const line = config.footer === undefined ? ':credit' : config.footer
+const html = line === false ? null : line.replaceAll(':credit', CREDIT)
+---
+
+{html && (
+    <footer class="jaad-chrome jaad-footer" aria-labelledby="footer-heading">
+        <h2 class="jaad-sr-only" id="footer-heading">
+            Site footer
+        </h2>
+        <p class="jaad-footer-credit" set:html={html} />
+    </footer>
+)}

package/src/site/components/Head.astro

@@ -0,0 +1,119 @@
+---
+import { Font } from 'astro:assets'
+import config from 'virtual:jaad/config'
+import { openGraphLocale } from '../locales.ts'
+import { withDeploymentBase } from '../urls.ts'
+
+interface Props {
+    title: string
+    description: string
+    /** Page frontmatter; each field overrides the site's. */
+    keywords?: string[]
+    author?: string
+    image?: string | false
+    modified?: Date
+    /** BCP-47 tag of this page's locale. */
+    language?: string
+    /** Every locale that has this page, for hreflang and og:locale:alternate. */
+    alternates?: { code: string; tag: string; href: string }[]
+    /** Where a reader with no matching language should land. */
+    xDefault?: string
+}
+
+const {
+    title,
+    description,
+    keywords = [],
+    author,
+    image,
+    modified,
+    language = config.lang,
+    alternates = [],
+    xDefault,
+} = Astro.props
+const canonical = Astro.site ? Astro.url.href : null
+
+// Open Graph rejects relative paths, so these have to be absolute.
+const resolvedImage = image ?? config.ogImage
+const ogImage =
+    resolvedImage === false
+        ? null
+        : /^https?:\/\//.test(resolvedImage)
+          ? resolvedImage
+          : Astro.site
+            ? new URL(withDeploymentBase(resolvedImage, import.meta.env.BASE_URL), Astro.site).href
+            : null
+const favicon = config.favicon ? withDeploymentBase(config.favicon, import.meta.env.BASE_URL) : null
+
+// Applied before the first paint, so the page never flashes the wrong theme.
+const themeScript = `(function () {
+  function isDark() {
+    var t = localStorage.getItem("theme");
+    return (
+      t === "dark" || (!t && matchMedia("(prefers-color-scheme: dark)").matches)
+    );
+  }
+  function applyTheme(root) {
+    if (isDark()) {
+      root.classList.add("dark");
+    } else {
+      root.classList.remove("dark");
+    }
+  }
+  applyTheme(document.documentElement);
+  document.addEventListener("astro:before-swap", function (e) {
+    applyTheme(e.newDocument.documentElement);
+  });
+  document.addEventListener("astro:after-swap", function () {
+    applyTheme(document.documentElement);
+  });
+})();`
+---
+
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width" />
+<meta name="description" content={description} />
+{keywords.length > 0 && <meta name="keywords" content={keywords.join(', ')} />}
+{author && <meta name="author" content={author} />}
+<title>{title}</title>
+{canonical && <link rel="canonical" href={canonical} />}
+{Astro.site &&
+    alternates.map((alternate) => (
+        <link rel="alternate" hreflang={alternate.tag} href={new URL(alternate.href, Astro.site).href} />
+    ))}
+{Astro.site && xDefault && <link rel="alternate" hreflang="x-default" href={new URL(xDefault, Astro.site).href} />}
+
+{favicon && <link rel="icon" href={favicon} />}
+
+<Font cssVariable="--font-inter" preload />
+<Font cssVariable="--font-merriweather" preload />
+
+{canonical && <meta property="og:url" content={canonical} />}
+<meta property="og:type" content="website" />
+<meta property="og:site_name" content={config.title} />
+<meta property="og:locale" content={openGraphLocale(language)} />
+{alternates
+    .filter((alternate) => alternate.tag !== language)
+    .map((alternate) => (
+        <meta property="og:locale:alternate" content={openGraphLocale(alternate.tag)} />
+    ))}
+<meta property="og:title" content={title} />
+<meta property="og:description" content={description} />
+{modified && <meta property="article:modified_time" content={modified.toISOString()} />}
+{ogImage && <meta property="og:image" content={ogImage} />}
+
+<meta name="twitter:card" content={ogImage ? 'summary_large_image' : 'summary'} />
+{canonical && <meta property="twitter:domain" content={Astro.url.hostname} />}
+{canonical && <meta property="twitter:url" content={canonical} />}
+<meta name="twitter:title" content={title} />
+<meta name="twitter:description" content={description} />
+{ogImage && <meta name="twitter:image" content={ogImage} />}
+
+<meta name="generator" content={Astro.generator} />
+
+{config.head.map((tag) => {
+    const Tag = tag.tag as keyof HTMLElementTagNameMap
+    return <Tag {...tag.attrs} set:html={tag.content ?? ''} />
+})}
+
+{config.appearance === 'auto' && <script is:inline set:html={themeScript} />}

package/src/site/components/Header.astro

@@ -0,0 +1,50 @@
+---
+import type { LocaleAlternate } from '../locales.ts'
+import config from 'virtual:jaad/config'
+import { DEFAULT_LOCALE, ui } from '../runtime.ts'
+import { withDeploymentBase } from '../urls.ts'
+import LocaleSwitcher from './LocaleSwitcher.astro'
+import Nav from './Nav.astro'
+import NavMobile from './NavMobile.astro'
+import SearchPalette from './SearchPalette.astro'
+import SocialLinks from './SocialLinks.astro'
+import ThemeSwitcher from './ThemeSwitcher.astro'
+
+interface Props {
+    locale?: string
+    /** The page in every locale, for the switcher. */
+    alternates: LocaleAlternate[]
+    search: {
+        /** `search-index.json` of the reader's locale. */
+        indexUrl: string
+        /** The full search field on wide screens, not just its icon. */
+        prominent?: boolean
+    }
+}
+
+const { locale = DEFAULT_LOCALE, alternates, search } = Astro.props
+const t = ui(locale)
+const homeHref = withDeploymentBase(config.homeLink, import.meta.env.BASE_URL)
+const logoSrc = config.logo ? withDeploymentBase(config.logo, import.meta.env.BASE_URL) : null
+---
+
+<header class="jaad-header" transition:persist>
+    <div class="jaad-header-inner">
+        <div class="jaad-header-row">
+            <span class="jaad-brand font-brand">
+                <a href={homeHref} title={t('home')} class="jaad-brand-link">
+                    {logoSrc ? <img src={logoSrc} alt={config.title} class="jaad-logo" /> : config.title}
+                </a>
+            </span>
+
+            <div class="jaad-header-actions">
+                <SearchPalette indexUrl={search.indexUrl} prominent={search.prominent} {locale} />
+                <Nav />
+                <SocialLinks />
+                {config.appearance === 'auto' && <ThemeSwitcher {locale} />}
+                {alternates.length > 1 && <LocaleSwitcher {alternates} current={locale} />}
+                <NavMobile {locale} />
+            </div>
+        </div>
+    </div>
+</header>

package/src/site/components/LocaleSwitcher.astro

@@ -0,0 +1,111 @@
+---
+import type { LocaleAlternate } from '../locales.ts'
+import { ui } from '../runtime.ts'
+
+interface Props {
+    alternates: LocaleAlternate[]
+    current: string
+}
+
+const { alternates, current } = Astro.props
+const active = alternates.find((entry) => entry.locale.code === current)
+const t = ui(current)
+---
+
+<jaad-locale-switcher class="jaad-locale-switcher">
+    <button
+        type="button"
+        data-trigger
+        aria-expanded="false"
+        aria-haspopup="true"
+        aria-controls="jaad-locale-menu"
+        aria-label={t('locale.change')}
+        title={t('locale.change')}
+        class="jaad-icon-button jaad-locale-trigger"
+    >
+        {active?.locale.flag && <span aria-hidden="true">{active.locale.flag}</span>}
+        <span class="jaad-locale-code">{current}</span>
+        <svg class="jaad-locale-chevron" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"></path>
+        </svg>
+    </button>
+
+    <div id="jaad-locale-menu" data-menu hidden class="jaad-menu jaad-locale-menu">
+        {alternates.map((entry) => (
+            <a
+                href={entry.href}
+                hreflang={entry.locale.tag}
+                lang={entry.locale.tag}
+                aria-current={entry.locale.code === current ? 'true' : undefined}
+                class="jaad-menu-item jaad-locale-item"
+            >
+                {entry.locale.flag && <span aria-hidden="true">{entry.locale.flag}</span>}
+                <span>{entry.locale.name}</span>
+            </a>
+        ))}
+    </div>
+</jaad-locale-switcher>
+
+<script>
+    import { nextSwitcherMarkup } from './locale-switcher.ts'
+
+    class JaadLocaleSwitcher extends HTMLElement {
+        #onDocumentPointerDown = (event: PointerEvent) => {
+            if (!this.contains(event.target as Node)) this.#close()
+        }
+
+        #onKeyDown = (event: KeyboardEvent) => {
+            if (event.key === 'Escape') this.#close()
+        }
+
+        /** The header persists across navigations; its links must not. */
+        #onBeforeSwap = (event: Event) => {
+            const markup = nextSwitcherMarkup((event as Event & { newDocument: Document }).newDocument)
+            if (markup !== null) this.innerHTML = markup
+        }
+
+        /** Delegated: #onBeforeSwap replaces the button this would bind to. */
+        #onClick = (event: MouseEvent) => {
+            const target = event.target as Element | null
+            if (!target?.closest('[data-trigger]')) return
+            if (this.#menu()?.hidden) this.#open()
+            else this.#close()
+        }
+
+        connectedCallback() {
+            this.addEventListener('click', this.#onClick)
+            document.addEventListener('pointerdown', this.#onDocumentPointerDown)
+            document.addEventListener('keydown', this.#onKeyDown)
+            document.addEventListener('astro:before-swap', this.#onBeforeSwap)
+        }
+
+        disconnectedCallback() {
+            this.removeEventListener('click', this.#onClick)
+            document.removeEventListener('pointerdown', this.#onDocumentPointerDown)
+            document.removeEventListener('keydown', this.#onKeyDown)
+            document.removeEventListener('astro:before-swap', this.#onBeforeSwap)
+        }
+
+        #menu() {
+            return this.querySelector<HTMLElement>('[data-menu]')
+        }
+
+        #open() {
+            const menu = this.#menu()
+            if (menu) menu.hidden = false
+            this.querySelector('[data-trigger]')?.setAttribute('aria-expanded', 'true')
+        }
+
+        #close() {
+            const menu = this.#menu()
+            if (menu) menu.hidden = true
+            const trigger = this.querySelector<HTMLElement>('[data-trigger]')
+            trigger?.setAttribute('aria-expanded', 'false')
+            if (this.contains(document.activeElement)) trigger?.focus()
+        }
+    }
+
+    if (!customElements.get('jaad-locale-switcher')) {
+        customElements.define('jaad-locale-switcher', JaadLocaleSwitcher)
+    }
+</script>

package/src/site/components/Nav.astro

@@ -0,0 +1,22 @@
+---
+import config from 'virtual:jaad/config'
+import { withDeploymentBase } from '../urls.ts'
+---
+
+{config.nav.length > 0 && (
+    <nav class="jaad-nav">
+        <ul class="jaad-nav-list">
+            {config.nav.map((link) => (
+                <li>
+                    <a
+                        href={withDeploymentBase(link.href, import.meta.env.BASE_URL)}
+                        class="jaad-nav-link"
+                        {...(link.href.startsWith('http') ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                    >
+                        {link.label}
+                    </a>
+                </li>
+            ))}
+        </ul>
+    </nav>
+)}