@jaamd/jaad 0.0.0-stage → 0.11.0

package/index.ts

@@ -0,0 +1,45 @@
+import type { AstroIntegration } from 'astro'
+import sitemap from '@astrojs/sitemap'
+import jaamd from '@jaamd/jaamd'
+import { defineConfig } from 'astro/config'
+import { resolveConfig, resolveStylesheets, type JaadUserConfig } from './src/config.ts'
+import { createCoreIntegration, createIntegrationState, createSitemapFilter } from './src/integration.ts'
+
+/** The whole set: Astro flattens nested arrays in `integrations`. */
+export default function jaad(options: JaadUserConfig): AstroIntegration[] {
+    const config = resolveConfig(options)
+    const css = resolveStylesheets(config)
+    const state = createIntegrationState()
+    const core = createCoreIntegration(config, css, state, Boolean(options.site))
+
+    // Without `site` the sitemap integration can only warn and skip.
+    return [
+        jaamd({ theme: config.shiki }),
+        ...(options.site
+            ? [
+                  sitemap({
+                      filter: createSitemapFilter(config.docsBase, state, config.defaultLocale),
+                  }),
+              ]
+            : []),
+        core,
+    ]
+}
+
+/** The whole Astro config for a JAAD site. `astro` is merged in, with its
+ *  integrations appended rather than replacing ours. */
+export function defineJaadSite(options: JaadUserConfig) {
+    const { site, base, astro } = options
+    const extra = astro ?? {}
+    const extraIntegrations = Array.isArray(extra.integrations) ? (extra.integrations as AstroIntegration[]) : []
+
+    return defineConfig({
+        ...(site ? { site } : {}),
+        ...(base ? { base } : {}),
+        ...extra,
+        integrations: [...jaad(options), ...extraIntegrations],
+    })
+}
+
+export { defineJaadConfig } from './src/config.ts'
+export type { JaadUserConfig, JaadConfig, JaadResolvedConfig } from './src/config.ts'

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@jaamd/jaad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.11.0",
+  "description": "Turn a folder of markdown into a documentation site. An Astro integration.",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "docs",
+    "documentation",
+    "markdown",
+    "withastro"
+  ],
+  "homepage": "https://jaamd.org/docs/jaad",
+  "bugs": "https://github.com/jaamd/jaamd/issues",
+  "license": "MIT",
+  "author": "Kasui92 <info@lucapattocchio.dev>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaamd/jaamd.git",
+    "directory": "packages/jaad"
+  },
+  "files": [
+    "index.ts",
+    "site.ts",
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./advanced": "./src/advanced.ts",
+    "./content": "./src/content.ts",
+    "./layouts/Page.astro": "./src/layouts/Page.astro",
+    "./site": "./site.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@astrojs/sitemap": "^3.7.4",
+    "@jaamd/jaamd": "^0.12.0",
+    "github-slugger": "^2.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.3.3",
+    "tailwindcss": "^4.3.3"
+  },
+  "peerDependencies": {
+    "@tailwindcss/vite": "^4.3.0",
+    "astro": ">=7.0.0 <8.0.0",
+    "tailwindcss": "^4.3.0"
+  },
+  "peerDependenciesMeta": {
+    "tailwindcss": {
+      "optional": true
+    },
+    "@tailwindcss/vite": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tailwindcss -i ./src/styles/global.css -o ./dist/jaad.css",
+    "check": "astro check && tsc --noEmit -p tests",
+    "test": "node --test \"tests/unit/**/*.test.ts\" \"tests/unit/**/*.test.mjs\"",
+    "test:consumer": "node --test \"tests/consumer/**/*.test.mjs\"",
+    "test:build": "pnpm --filter jaad-fixture build && node --test \"tests/build/**/*.test.mjs\""
+  }
 }

package/site.ts

@@ -0,0 +1,19 @@
+import type { JaadUserConfig } from './src/config.ts'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { defineJaadSite } from './index.ts'
+
+const CANDIDATES = ['jaad.config.ts', 'jaad.config.mjs', 'jaad.config.js']
+
+const file = CANDIDATES.map((n) => join(process.cwd(), n)).find(existsSync)
+if (!file) {
+    throw new Error(`jaad: no config found. Create one of ${CANDIDATES.join(', ')} in the project root.`)
+}
+
+// Unanalysable on purpose: a static path would make Vite warn on every build.
+const loaded = (await import(/* @vite-ignore */ pathToFileURL(file).href)) as {
+    default: JaadUserConfig
+}
+
+export default defineJaadSite(loaded.default)

package/src/@types/docs.ts

@@ -0,0 +1,47 @@
+export interface ParsedDocsCollectionId {
+    slug: string
+    orderChapter?: number
+    chapter?: string
+    order: number
+    title: string
+}
+
+export interface DocsNavItem {
+    title: string
+    chapter: string | undefined
+    primaryOrder: number
+    href: string
+    isActive: boolean
+}
+
+export interface DocsHeadings {
+    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 the docs collection. Astro generates collection
+ *  types in the consumer project, so the package states its own contract. */
+export interface DocsEntry {
+    id: string
+    /** Set when the docs are localised; the id without its locale directory. */
+    localeId?: string
+    /** Set when the docs are localised. */
+    locale?: string
+    body?: string
+    data: DocsPageData
+}

package/src/advanced.ts

@@ -0,0 +1,21 @@
+import type { DocsHeadings, DocsPageData } from './@types/docs.ts'
+import type { DocsNavigation } from './navigation.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
+        chapter?: string
+        /** Raw frontmatter. */
+        data: DocsPageData
+    }
+    headings: DocsHeadings[]
+    navigation: DocsNavigation
+}
+
+export type { DocsHeadings, DocsNavItem, DocsEntry, DocsPageData } from './@types/docs.ts'
+export type { DocsNavigation, NavSection } from './navigation.ts'

package/src/collection.ts

@@ -0,0 +1,97 @@
+import type { DocsEntry } from './@types/docs.ts'
+import type { Locale } from './locales.ts'
+import { getCollection } from 'astro:content'
+import { DEFAULT_LOCALE, LOCALES, docsUrls, prefixedCodes } from './docs-config.ts'
+import { docsPageHref } from './urls.ts'
+import {
+    docTranslationKey,
+    getCleanSlug,
+    routedId,
+    sortDocPages,
+    splitDocLocale,
+    validateDocsStructure,
+} from './utils/docs.ts'
+
+const cached = new Map<string, DocsEntry[]>()
+// Keyed on the array: the same object in production, a fresh one in dev.
+const keyIndex = new WeakMap<DocsEntry[], Map<string, number>>()
+
+function indexOfKey(pages: DocsEntry[], key: string): number {
+    let index = keyIndex.get(pages)
+    if (!index) {
+        index = new Map(pages.map((page, at) => [docTranslationKey(page), at]))
+        keyIndex.set(pages, index)
+    }
+    return index.get(key) ?? -1
+}
+
+const CODES = LOCALES.map((locale) => locale.code)
+
+/** Attaches the locale and the id routing reads, leaving `id` the real
+ *  collection id: the edit link points at the file on disk. */
+function localise(page: DocsEntry): DocsEntry {
+    if (CODES.length === 0) return page
+    const split = splitDocLocale(page.id, CODES)
+    return { ...page, locale: split.locale ?? undefined, localeId: split.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 getSortedDocsPages(locale: string = DEFAULT_LOCALE): Promise<DocsEntry[]> {
+    const key = CODES.length > 0 ? locale : ''
+    const hit = cached.get(key)
+    if (import.meta.env.PROD && hit) return hit
+
+    const pages = ((await getCollection('docsPages')) as unknown as DocsEntry[])
+        .map(localise)
+        .filter((page) => key === '' || page.locale === key)
+
+    // Validated before drafts are dropped, so a draft's slug conflict is an error.
+    validateDocsStructure(pages, key || undefined)
+    const sorted = sortDocPages(import.meta.env.PROD ? pages.filter((page) => !page.data.draft) : pages)
+    if (import.meta.env.PROD) cached.set(key, sorted)
+    return sorted
+}
+
+export interface LocaleAlternate {
+    locale: Locale
+    href: string
+    /** False when this locale has no such page and the href is its opening one. */
+    translated: boolean
+}
+
+/** 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 pages = await getSortedDocsPages(locale.code)
+        // Every page drafted leaves a locale with nothing to link to.
+        if (pages.length === 0) continue
+
+        const index = key ? indexOfKey(pages, key) : 0
+        const match = index >= 0 ? pages[index] : undefined
+
+        alternates.push({
+            locale,
+            translated: Boolean(match),
+            href: docsPageHref(match && index > 0 ? getCleanSlug(routedId(match)) : '', 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 getSortedDocsPages(code)
+        if (pages.length > 0) served.push(code)
+    }
+
+    return served
+}

package/src/components/Footer.astro

@@ -0,0 +1,18 @@
+---
+import config from 'virtual:jaad/config'
+
+const CREDIT = 'Built with <a href="https://jaamd.org/docs/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/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/components/Header.astro

@@ -0,0 +1,47 @@
+---
+import config from 'virtual:jaad/config'
+import { getLocaleAlternates, type LocaleAlternate } from '../collection.ts'
+import { DEFAULT_LOCALE, ui } from '../docs-config.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 {
+    /** Whether this page is part of the docs. */
+    inDocs?: boolean
+    locale?: string
+    alternates?: LocaleAlternate[]
+}
+
+const { inDocs = false, locale = DEFAULT_LOCALE } = Astro.props
+// A page of the reader's own has no translations: offer each locale's opener.
+const alternates = Astro.props.alternates ?? (await getLocaleAlternates(''))
+const t = ui(locale)
+const homeHref = withDeploymentBase('/', import.meta.env.BASE_URL)
+const logoSrc = config.logo ? withDeploymentBase(config.logo, import.meta.env.BASE_URL) : null
+---
+
+<header class="jaad-chrome" 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 inDocs={inDocs} locale={locale} />
+                <Nav />
+                <SocialLinks />
+                {config.appearance === 'auto' && <ThemeSwitcher {locale} />}
+                {alternates.length > 1 && <LocaleSwitcher {alternates} current={locale} />}
+                <NavMobile {locale} />
+            </div>
+        </div>
+    </div>
+</header>

package/src/components/LocaleSwitcher.astro

@@ -0,0 +1,111 @@
+---
+import type { LocaleAlternate } from '../collection.ts'
+import { ui } from '../docs-config.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/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>
+)}