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

package/src/site/styles/components/search.css

@@ -0,0 +1,118 @@
+@layer components {
+    .jaad-search-trigger {
+        @apply border-border bg-surface hover:bg-surface-hover text-foreground-muted hidden cursor-pointer items-center gap-2 rounded-lg border px-3 py-1.5 text-sm transition-colors md:flex;
+    }
+
+    .jaad-search-trigger-icon {
+        @apply h-4 w-4 shrink-0;
+    }
+
+    .jaad-search-trigger-label {
+        @apply hidden lg:inline;
+    }
+
+    .jaad-search-shortcut {
+        @apply bg-background-secondary text-foreground-muted rounded px-1.5 py-0.5 text-xs font-medium;
+    }
+
+    /* Icon trigger on a docs page, where the desktop field is shown from md. */
+    .jaad-search-trigger-compact {
+        @apply md:hidden;
+    }
+
+    .jaad-search-overlay {
+        @apply fixed inset-0 z-50 flex items-start justify-center px-4 pt-[15vh];
+    }
+
+    .jaad-search-backdrop {
+        @apply absolute inset-0 bg-black/60 backdrop-blur-sm;
+    }
+
+    .jaad-search-panel {
+        @apply bg-surface border-border relative z-10 w-full max-w-lg overflow-hidden rounded-xl border shadow-2xl;
+    }
+
+    .jaad-search-bar {
+        @apply border-border flex items-center gap-3 border-b px-4 py-3;
+    }
+
+    .jaad-search-bar-icon {
+        @apply text-foreground-muted h-5 w-5 shrink-0;
+    }
+
+    .jaad-search-input {
+        @apply text-foreground placeholder:text-foreground-muted min-w-0 flex-1 bg-transparent text-sm outline-none;
+    }
+
+    .jaad-search-close {
+        @apply bg-background-secondary text-foreground-muted shrink-0 cursor-pointer rounded px-1.5 py-0.5 text-xs;
+    }
+
+    .jaad-search-filters {
+        @apply border-border flex flex-wrap gap-1.5 border-b px-4 py-2;
+    }
+
+    .jaad-search-filter {
+        @apply border-border text-foreground-muted hover:text-foreground cursor-pointer rounded-full border px-2.5 py-0.5 text-xs transition-colors;
+    }
+
+    .jaad-search-filter[aria-pressed='true'] {
+        @apply border-primary/40 bg-primary/10 text-foreground-bright;
+    }
+
+    .jaad-search-results {
+        @apply max-h-96 overflow-y-auto p-2;
+    }
+
+    .jaad-search-group {
+        @apply text-foreground-muted px-3 pt-3 pb-1 text-xs font-semibold tracking-wide uppercase;
+    }
+
+    .jaad-search-footer {
+        @apply border-border text-foreground-muted flex items-center gap-4 border-t px-4 py-2 text-xs;
+    }
+
+    .jaad-search-key {
+        @apply bg-background-secondary rounded px-1 py-0.5;
+    }
+
+    .jaad-search-result {
+        @apply text-foreground cursor-pointer rounded-lg px-3 py-2.5 text-left transition-colors;
+    }
+
+    .jaad-search-result:not([aria-selected='true']) {
+        @apply hover:bg-primary/5;
+    }
+
+    .jaad-search-result[aria-selected='true'] {
+        @apply bg-primary/10 text-foreground-bright;
+    }
+
+    .jaad-search-result-heading {
+        @apply border-border ml-3 rounded-l-none border-l py-2;
+    }
+
+    .jaad-search-result-head {
+        @apply flex items-center gap-2;
+    }
+
+    .jaad-search-result-title {
+        @apply text-sm font-medium;
+    }
+
+    .jaad-search-result-badge {
+        @apply text-foreground-muted bg-background-secondary rounded px-1.5 py-0.5 text-[0.65rem];
+    }
+
+    .jaad-search-result-snippet {
+        @apply text-foreground-secondary mt-1 line-clamp-1 text-xs;
+    }
+
+    .jaad-search-mark {
+        @apply bg-primary/20 text-foreground-bright rounded-sm px-0.5 font-semibold not-italic;
+    }
+
+    .jaad-search-message {
+        @apply text-foreground-muted px-3 py-6 text-center text-sm;
+    }
+}

package/src/site/styles/components/shell.css

@@ -0,0 +1,77 @@
+/* Shared shell classes; first in the layer so component files override them. */
+@layer components {
+    /* Header, footer and docs content share one measure. */
+    .jaad-chrome {
+        width: 100%;
+        max-width: var(--jaad-chrome-width);
+        margin-inline: auto;
+    }
+
+    .jaad-main {
+        flex: 1;
+        margin-block: 4rem;
+        padding-inline: var(--jaad-page-padding);
+    }
+
+    @media (min-width: 64rem) {
+        .jaad-main {
+            padding-inline: calc(var(--jaad-page-padding) * 2);
+        }
+    }
+
+    /* `bare` keeps the landmark without the spacing. */
+    .jaad-main-bare {
+        flex: 1;
+    }
+
+    .jaad-body {
+        @apply bg-background text-foreground flex min-h-screen flex-col text-[14px] leading-[1.6];
+    }
+
+    .jaad-body {
+        padding-top: var(--jaad-header-height);
+    }
+
+    .jaad-icon {
+        @apply h-5 w-5;
+    }
+
+    .jaad-sr-only {
+        @apply sr-only;
+    }
+
+    .jaad-sidebar {
+        width: var(--jaad-sidebar-width);
+        overflow-y: auto;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar {
+        width: 6px;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar-track {
+        background: transparent;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar-thumb {
+        background: rgb(from var(--color-primary) r g b / 0.2);
+        border-radius: 3px;
+    }
+
+    .jaad-sidebar::-webkit-scrollbar-thumb:hover {
+        background: rgb(from var(--color-primary) r g b / 0.4);
+    }
+
+    /* The header controls sit in one row and have to stay identical. */
+    .jaad-icon-button {
+        @apply text-foreground-secondary hover:text-foreground-bright flex h-9 w-9 cursor-pointer items-center justify-center rounded-lg no-underline transition-colors;
+    }
+
+    .jaad-menu {
+        @apply bg-surface border-border absolute top-full right-0 z-40 mt-2 w-44 overflow-hidden rounded-xl border shadow-lg;
+    }
+
+    .jaad-menu-item {
+        @apply text-foreground-secondary hover:text-foreground-bright hover:bg-primary/5 block rounded-lg px-3 py-2 text-sm no-underline transition-colors;
+    }
+}

package/src/site/styles/components/social-links.css

@@ -0,0 +1,8 @@
+@layer components {
+    .jaad-social-icon {
+        @apply flex h-5 w-5 items-center justify-center;
+    }
+    .jaad-social-label {
+        @apply text-xs;
+    }
+}

package/src/site/styles/components/theme-switcher.css

@@ -0,0 +1,14 @@
+@layer components {
+    /* Both icons ship; CSS picks one, so the server-rendered control is correct. */
+    .jaad-theme-icon-to-light {
+        display: none;
+    }
+
+    html.dark .jaad-theme-icon-to-dark {
+        display: none;
+    }
+
+    html.dark .jaad-theme-icon-to-light {
+        display: block;
+    }
+}

package/src/site/styles/components.css

@@ -0,0 +1,10 @@
+@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/not-found.css';
+@import './components/search.css';

package/src/site/styles/global.css

@@ -0,0 +1,140 @@
+@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;
+    /* Sidebar, page and table of contents, with their gaps and the gutters. */
+    --jaad-chrome-width: calc(var(--jaad-content-width) + 2 * var(--jaad-sidebar-width) + 6rem);
+    --jaad-sidebar-width: 16rem;
+    --jaad-header-height: 4.25rem;
+    --jaad-page-padding: 2rem;
+}
+
+@layer base {
+    html {
+        scroll-padding-top: calc(var(--jaad-header-height) + 1.5rem);
+        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/site/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/site/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/site/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/site/themes.ts

@@ -0,0 +1,26 @@
+import { themes } from '@jaamd/astro/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/site/ui/en.ts

@@ -0,0 +1,27 @@
+/** The canonical UI catalogue: its keys define every catalogue JAAD accepts. */
+export const ENGLISH_UI = {
+    'breadcrumb.label': 'Breadcrumb',
+    home: 'Home',
+    'locale.change': 'Change language',
+    'nav.documentation': 'Documentation navigation',
+    'nav.mobile': 'Toggle mobile menu',
+    'nav.page': 'Page navigation',
+    'page.copied': 'Copied!',
+    'page.copy': 'Copy page',
+    'page.edit': 'Edit this page',
+    'page.lastUpdated': 'Last updated on',
+    'search.all': 'All',
+    '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.sections': 'Search in',
+    'search.trigger': 'Search docs...',
+    'theme.toggle': 'Toggle color theme',
+    'toc.label': 'Table of contents',
+    'toc.title': 'On this page',
+} as const

package/src/site/ui/it.ts

@@ -0,0 +1,28 @@
+import type { UiCatalog } from '../ui.ts'
+
+export const ITALIAN_UI = {
+    'breadcrumb.label': 'Percorso di navigazione',
+    home: 'Pagina iniziale',
+    'locale.change': 'Cambia lingua',
+    'nav.documentation': 'Navigazione della documentazione',
+    'nav.mobile': 'Apri o chiudi il menu',
+    'nav.page': 'Navigazione tra le pagine',
+    'page.copied': 'Copiata!',
+    'page.copy': 'Copia',
+    'page.edit': 'Modifica',
+    'page.lastUpdated': 'Ultimo aggiornamento il',
+    'search.all': 'Tutte',
+    '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.sections': 'Cerca in',
+    'search.trigger': 'Cerca…',
+    'theme.toggle': 'Cambia modalità',
+    'toc.label': 'Indice dei contenuti',
+    'toc.title': 'In questa pagina',
+} satisfies UiCatalog

package/src/site/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/site/urls.ts

@@ -0,0 +1,14 @@
+/** 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}`
+}

package/src/site/virtual.ts

@@ -0,0 +1,42 @@
+const MODULE_ID = 'virtual:jaad/config'
+const RESOLVED_ID = '\0' + MODULE_ID
+
+const USER_CSS_ID = 'virtual:jaad/user.css'
+const RESOLVED_USER_CSS = '\0' + USER_CSS_ID
+
+const THEME_CSS_ID = 'virtual:jaad/theme.css'
+const RESOLVED_THEME_CSS = '\0' + THEME_CSS_ID
+
+// Which way the palette travels between JAAD and JAAMD; always one of the two.
+const BRIDGE_CSS_ID = 'virtual:jaad/bridge.css'
+
+const TAILWIND_CSS_ID = 'virtual:jaad/tailwind.css'
+const RESOLVED_TAILWIND_CSS = '\0' + TAILWIND_CSS_ID
+
+export interface SiteStylesheets {
+    user: string | null
+    theme: string | null
+    bridge: string
+    tailwind: string | null
+}
+
+/** The resolved config, serialised, and the stylesheets the site may or may not have. */
+export function siteVirtualPlugin(config: object, stylesheets: SiteStylesheets) {
+    return {
+        name: 'jaad:virtual',
+        resolveId(source: string) {
+            if (source === MODULE_ID) return RESOLVED_ID
+            // Redirecting to the real path lets Vite process it as ordinary CSS.
+            if (source === USER_CSS_ID) return stylesheets.user ?? RESOLVED_USER_CSS
+            if (source === THEME_CSS_ID) return stylesheets.theme ?? RESOLVED_THEME_CSS
+            if (source === BRIDGE_CSS_ID) return stylesheets.bridge
+            if (source === TAILWIND_CSS_ID) return stylesheets.tailwind ?? RESOLVED_TAILWIND_CSS
+            return null
+        },
+        load(id: string) {
+            if (id === RESOLVED_ID) return `export default ${JSON.stringify(config)};`
+            if (id === RESOLVED_USER_CSS || id === RESOLVED_THEME_CSS || id === RESOLVED_TAILWIND_CSS) return ''
+            return null
+        },
+    }
+}

package/src/styles.css

@@ -0,0 +1,5 @@
+/* The package stylesheet: Tailwind, the site's components, the docs', then the tokens. */
+@import 'tailwindcss' source(none);
+@import './site/styles/components.css';
+@import './docs/styles/components.css';
+@import './site/styles/global.css';