@jaamd/jaad 0.0.0-stage → 0.11.0

package/src/styles/global.css

@@ -0,0 +1,162 @@
+@import 'tailwindcss' source(none);
+@import './components/shell.css';
+@import './components/header.css';
+@import './components/footer.css';
+@import './components/nav.css';
+@import './components/nav-mobile.css';
+@import './components/social-links.css';
+@import './components/theme-switcher.css';
+@import './components/locale-switcher.css';
+@import './components/scroll-to-top.css';
+@import './components/not-found.css';
+@import './components/search.css';
+@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';
+
+@theme static {
+    /* Seeds */
+
+    --color-background: #faf8f5;
+    --color-surface: #ffffff;
+    --color-foreground: #3a3a3a;
+    --color-foreground-bright: #1a1a1a;
+    --color-primary: #2d2d2d;
+
+    --color-error: #c45959;
+    --color-warning: #d4a259;
+    --color-info: #5988c4;
+    --color-success: #5a9c7e;
+
+    /* Derived */
+
+    --color-background-secondary: color-mix(in oklab, var(--color-foreground) 2%, var(--color-background));
+    --color-background-tertiary: color-mix(in oklab, var(--color-foreground) 6%, var(--color-background));
+    --color-surface-hover: color-mix(in oklab, var(--color-foreground) 5%, var(--color-background));
+
+    --color-border-light: color-mix(in oklab, var(--color-foreground) 11%, var(--color-background));
+    --color-border: color-mix(in oklab, var(--color-foreground) 17%, var(--color-background));
+    --color-border-dark: color-mix(in oklab, var(--color-foreground) 25%, var(--color-background));
+
+    --color-foreground-muted: color-mix(in oklab, var(--color-foreground) 55%, var(--color-background));
+    --color-foreground-secondary: color-mix(in oklab, var(--color-foreground) 72%, var(--color-background));
+
+    --color-primary-dark: var(--color-foreground-bright);
+    --color-primary-light: color-mix(in oklab, var(--color-primary) 83%, var(--color-background));
+
+    /* Fonts */
+    --font-sans: var(--font-inter), -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    --font-serif: var(--font-merriweather), Georgia, serif;
+    --font-mono: 'SF Mono', SF Mono, Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+
+    /* Layout */
+    --jaad-content-width: 56rem;
+    --jaad-chrome-width: var(--jaad-content-width);
+    --jaad-sidebar-width: 16rem;
+    --jaad-page-padding: 2rem;
+
+    /* Where a sidebar sits beside centred content. Derived, so moving the
+     content width moves the sidebars with it. */
+    --jaad-sidebar-offset: calc(50% - (var(--jaad-content-width) / 2) - var(--jaad-sidebar-width) - 2rem);
+}
+
+@layer base {
+    html {
+        scroll-padding-top: 8rem;
+        background-color: var(--color-background);
+        color: var(--color-foreground);
+        font-family: var(--font-sans);
+        font-size: 16px;
+        scroll-behavior: smooth;
+        scrollbar-gutter: stable;
+    }
+
+    h1,
+    h2,
+    h3 {
+        color: var(--color-foreground-bright);
+        font-family: var(--font-serif);
+    }
+
+    h2 {
+        margin-bottom: 1.5rem;
+        font-size: 1.5rem;
+        font-weight: 600;
+    }
+
+    h3 {
+        margin-bottom: 1rem;
+        font-size: 1.2rem;
+        font-weight: normal;
+    }
+
+    a {
+        @apply text-primary hover:text-primary-dark underline decoration-1 underline-offset-2 transition duration-200 ease-in-out;
+    }
+
+    i {
+        @apply text-primary italic;
+    }
+}
+
+/* Utilities layer: wins over .jaad-brand's line-height. */
+@layer utilities {
+    .font-brand {
+        font-family: var(--font-serif);
+        font-weight: 300;
+        font-style: italic;
+        letter-spacing: -0.01em;
+        line-height: 1;
+    }
+}
+
+/* Dark mode */
+
+html.dark {
+    color-scheme: dark;
+
+    --color-background: #0d1117;
+    --color-surface: #21262d;
+    --color-foreground: #c9d1d9;
+    --color-foreground-bright: #e6edf3;
+    --color-primary: #c9d1d9;
+
+    --color-error: #f85149;
+    --color-warning: #d29922;
+    --color-info: #58a6ff;
+    --color-success: #3fb950;
+
+    --color-background-secondary: color-mix(in oklab, var(--color-foreground) 7%, var(--color-background));
+    --color-background-tertiary: color-mix(in oklab, var(--color-foreground) 10%, var(--color-background));
+    --color-surface-hover: color-mix(in oklab, var(--color-foreground) 22%, var(--color-background));
+
+    --color-border-light: color-mix(in oklab, var(--color-foreground) 13%, var(--color-background));
+    --color-border: color-mix(in oklab, var(--color-foreground) 22%, var(--color-background));
+    --color-border-dark: color-mix(in oklab, var(--color-foreground) 36%, var(--color-background));
+
+    --color-foreground-muted: color-mix(in oklab, var(--color-foreground) 57%, var(--color-background));
+    --color-foreground-secondary: color-mix(in oklab, var(--color-foreground) 71%, var(--color-background));
+
+    --color-primary-light: color-mix(in oklab, var(--color-primary) 71%, var(--color-background));
+}
+
+/* Reduced motion */
+
+@media (prefers-reduced-motion: reduce) {
+    html {
+        scroll-behavior: auto;
+    }
+
+    *,
+    *::before,
+    *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+        scroll-behavior: auto !important;
+    }
+}

package/src/styles/jaamd-forward.css

@@ -0,0 +1,16 @@
+/* JAAD's palette drives JAAMD's. Used when the colours come from JAAD — its own
+   identity, or a custom theme written in src/jaad.css. */
+
+:root {
+    --jaamd-bg: var(--color-background);
+    --jaamd-color-fg: var(--color-foreground);
+    --jaamd-color-fg-bright: var(--color-foreground-bright);
+    --jaamd-color-primary: var(--color-primary);
+    --jaamd-color-success: var(--color-success);
+
+    --jaamd-alert-note-color: var(--color-info);
+    --jaamd-alert-tip-color: var(--color-success);
+    --jaamd-alert-important-color: var(--color-primary);
+    --jaamd-alert-warning-color: var(--color-warning);
+    --jaamd-alert-caution-color: var(--color-error);
+}

package/src/styles/jaamd-reverse.css

@@ -0,0 +1,18 @@
+/* JAAMD's palette drives JAAD's, the opposite direction to jaamd-forward.css.
+   Never both at once: together they are a cycle, and CSS drops both sides.
+
+   Only the seeds; global.css derives the rest with color-mix(). */
+
+:root,
+html.dark {
+    --color-background: var(--jaamd-bg);
+    --color-surface: var(--jaamd-surface-1);
+    --color-foreground: var(--jaamd-color-fg);
+    --color-foreground-bright: var(--jaamd-color-fg-bright);
+    --color-primary: var(--jaamd-color-primary);
+
+    --color-info: var(--jaamd-alert-note-color);
+    --color-success: var(--jaamd-alert-tip-color);
+    --color-warning: var(--jaamd-alert-warning-color);
+    --color-error: var(--jaamd-alert-caution-color);
+}

package/src/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/styles/tailwind.css

@@ -0,0 +1,30 @@
+/* Opt-in (`tailwind: true`): site utilities read JAAD's tokens. No values, no preflight. */
+@import 'tailwindcss/theme.css' layer(theme) theme(reference);
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+@theme reference {
+    --color-background: transparent;
+    --color-surface: transparent;
+    --color-foreground: transparent;
+    --color-foreground-bright: transparent;
+    --color-primary: transparent;
+    --color-error: transparent;
+    --color-warning: transparent;
+    --color-info: transparent;
+    --color-success: transparent;
+    --color-background-secondary: transparent;
+    --color-background-tertiary: transparent;
+    --color-surface-hover: transparent;
+    --color-border-light: transparent;
+    --color-border: transparent;
+    --color-border-dark: transparent;
+    --color-foreground-muted: transparent;
+    --color-foreground-secondary: transparent;
+    --color-primary-dark: transparent;
+    --color-primary-light: transparent;
+    --font-sans: transparent;
+    --font-serif: transparent;
+    --font-mono: transparent;
+}

package/src/themes/index.ts

@@ -0,0 +1,26 @@
+import { themes } from '@jaamd/jaamd/themes'
+
+export interface Preset {
+    /** Shiki theme, or a light/dark pair, for code blocks. */
+    shiki: string | { light: string; dark: string }
+    /** JAAMD theme slug, or null when JAAD's own identity already applies. */
+    theme: string | null
+    /** `dual` carries a light and a dark palette; the others apply in both modes. */
+    mode: 'light' | 'dark' | 'dual'
+}
+
+/** JAAMD's palettes, plus `default`: JAAD's own, which needs no stylesheet. */
+export const PRESETS: Record<string, Preset> = {
+    default: {
+        shiki: { light: 'github-light', dark: 'github-dark' },
+        theme: null,
+        mode: 'dual',
+    },
+    ...Object.fromEntries(
+        themes.map((theme) => [theme.slug, { shiki: theme.shiki, theme: theme.slug, mode: theme.mode }]),
+    ),
+}
+
+export const PRESET_NAMES = Object.keys(PRESETS)
+
+export const isPreset = (value: string): boolean => value in PRESETS

package/src/ui/en.ts

@@ -0,0 +1,29 @@
+/** The canonical UI catalogue: its keys define every catalogue JAAD accepts. */
+export const ENGLISH_UI = {
+    'breadcrumb.label': 'Breadcrumb',
+    'breadcrumb.root': 'Docs',
+    home: 'Home',
+    'locale.change': 'Change language',
+    'nav.documentation': 'Documentation navigation',
+    'nav.jumpToSection': 'Jump to section...',
+    'nav.mobile': 'Toggle mobile menu',
+    'nav.page': 'Page navigation',
+    'nav.selectPage': 'Select page',
+    'page.copied': 'Copied!',
+    'page.copy': 'Copy page',
+    'page.edit': 'Edit this page',
+    'page.lastUpdated': 'Last updated on',
+    scrollTop: 'Scroll to top',
+    'search.close': 'close',
+    'search.empty': 'No results for',
+    'search.label': 'Search documentation',
+    'search.loading': 'Loading...',
+    'search.navigate': 'navigate',
+    'search.open': 'open',
+    'search.placeholder': 'Search documentation...',
+    'search.results': 'Search results',
+    'search.trigger': 'Search docs...',
+    'theme.toggle': 'Toggle color theme',
+    'toc.label': 'Table of contents',
+    'toc.title': 'On This Page',
+} as const

package/src/ui/it.ts

@@ -0,0 +1,30 @@
+import type { UiCatalog } from '../ui.ts'
+
+export const ITALIAN_UI = {
+    'breadcrumb.label': 'Percorso di navigazione',
+    'breadcrumb.root': 'Documentazione',
+    home: 'Pagina iniziale',
+    'locale.change': 'Cambia lingua',
+    'nav.documentation': 'Navigazione della documentazione',
+    'nav.jumpToSection': 'Vai alla sezione…',
+    'nav.mobile': 'Apri o chiudi il menu',
+    'nav.page': 'Navigazione tra le pagine',
+    'nav.selectPage': 'Seleziona una pagina',
+    'page.copied': 'Copiata!',
+    'page.copy': 'Copia',
+    'page.edit': 'Modifica',
+    'page.lastUpdated': 'Ultimo aggiornamento il',
+    scrollTop: 'Torna in cima',
+    'search.close': 'chiudi',
+    'search.empty': 'Nessun risultato per',
+    'search.label': 'Cerca nella documentazione',
+    'search.loading': 'Caricamento…',
+    'search.navigate': 'naviga',
+    'search.open': 'apri',
+    'search.placeholder': 'Cerca nella documentazione…',
+    'search.results': 'Risultati della ricerca',
+    'search.trigger': 'Cerca…',
+    'theme.toggle': 'Cambia modalità',
+    'toc.label': 'Indice dei contenuti',
+    'toc.title': 'In questa pagina',
+} satisfies UiCatalog

package/src/ui.ts

@@ -0,0 +1,49 @@
+import { ENGLISH_UI } from './ui/en.ts'
+import { ITALIAN_UI } from './ui/it.ts'
+
+/** Every string JAAD puts on a page itself. */
+export const UI_DEFAULTS = ENGLISH_UI
+
+export type UiKey = keyof typeof UI_DEFAULTS
+export type UiCatalog = Record<UiKey, string>
+
+export type UiOverrides = Record<string, Partial<Record<string, string>>>
+
+const UI_CATALOGS = {
+    en: ENGLISH_UI,
+    it: ITALIAN_UI,
+} satisfies Record<string, UiCatalog>
+
+function localeCandidates(locale: string): string[] {
+    const exact = locale.toLowerCase()
+    const base = exact.split('-', 1)[0]
+    return exact === base ? [exact] : [exact, base]
+}
+
+/** Locale keys in config are BCP-47 and therefore case-insensitive. */
+function localeEntry<T>(entries: Record<string, T>, locale: string) {
+    return Object.entries(entries).find(([candidate]) => candidate.toLowerCase() === locale)?.[1]
+}
+
+/** User overrides win, from the exact locale to its base language. Bundled
+ *  catalogues follow the same order; English remains the final fallback. */
+export function uiString(overrides: UiOverrides, locale: string, key: UiKey): string {
+    const candidates = localeCandidates(locale)
+
+    for (const candidate of candidates) {
+        const value = localeEntry(overrides, candidate)?.[key]
+        if (value !== undefined) return value
+    }
+
+    for (const candidate of candidates) {
+        const catalogue = localeEntry<UiCatalog>(UI_CATALOGS, candidate)
+        if (catalogue) return catalogue[key]
+    }
+
+    return UI_DEFAULTS[key]
+}
+
+export const UI_KEYS = Object.keys(UI_DEFAULTS) as UiKey[]
+
+/** Kept internal: consumers customise strings through `ui`. */
+export const UI_SUPPORTED_LOCALES = Object.keys(UI_CATALOGS)

package/src/urls.ts

@@ -0,0 +1,49 @@
+import { localeSegment } from './locales.ts'
+
+/** Empty at the site root, otherwise one leading slash and no trailing slash. */
+export function normaliseBasePath(value: string): string {
+    const trimmed = value.replace(/^\/+/, '').replace(/\/+$/, '')
+    return trimmed ? `/${trimmed}` : ''
+}
+
+/** Apply Astro's deployment base to an application-local, root-relative href. */
+export function withDeploymentBase(href: string, deploymentBase: string): string {
+    if (!href.startsWith('/') || href.startsWith('//')) return href
+
+    const prefix = normaliseBasePath(deploymentBase)
+    if (!prefix) return href
+    return href === '/' ? `${prefix}/` : `${prefix}${href}`
+}
+
+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)
+}