@takazudo/zudo-doc 2.5.1 → 3.1.0

package/README.md

@@ -2,6 +2,10 @@
 
 Framework primitives that sit on top of zfb's engine — the framework layer that zfb deliberately doesn't ship (per ADR-003).
 
+Release history is shipped as `CHANGELOG.md` in the npm package. The file is
+generated from the repository's changelog MDX pages; edit those source pages
+instead of editing the generated markdown directly.
+
 This package provides the missing-by-design framework concerns:
 
 - **Sidebar tree builder** (`./sidebar-tree`) — turns collection entries + `_category_.json` into a sidebar `SidebarNode[]`.

package/dist/chrome/derive.d.ts

@@ -6,7 +6,10 @@ import type { Settings } from "../settings.js";
 import { type ColorScheme } from "../color-scheme-utils.js";
 import { createBodyEndIslands } from "../doc-body-end-islands/index.js";
 /** Package-default color scheme used when `colorSchemes` is `null` or a key is
- *  missing. Exported so `createChrome` keeps the identical fallback. */
+ *  missing. Exported so `createChrome` keeps the identical fallback. Base roles
+ *  follow the epic's Default Dark defaults on the minimized 5-base ramp
+ *  (bg={base:4}, fg={base:0}, selBg={base:2}, selFg={base:0}); semantics use
+ *  `SEMANTIC_RAMP_DEFAULTS`. */
 export declare const DEFAULT_SCHEME: ColorScheme;
 /** Package no-op DocHistory island stub — renders an empty fragment (the
  *  `DocHistoryComponent` contract requires a VNode, not null). */

package/dist/chrome/derive.js

@@ -2,7 +2,8 @@ import { Fragment, jsx } from "preact/jsx-runtime";
 import { createComposeMetaTitle } from "../compose-meta-title/index.js";
 import {
   generateCssCustomProperties,
-  generateLightDarkCssProperties
+  generateLightDarkCssProperties,
+  SEMANTIC_RAMP_DEFAULTS
 } from "../color-scheme-utils.js";
 import { createBodyEndIslands } from "../doc-body-end-islands/index.js";
 import { SearchWidget } from "../search-widget/index.js";
@@ -22,31 +23,35 @@ import {
   getThemeDefaultMode as getThemeDefaultModeBase
 } from "../nav-data-prep/index.js";
 import { buildSidebarForSection } from "../sidebar-utils/index.js";
-const GREY_RAMP = [
-  "oklch(0.000 0.000 0.00)",
-  "oklch(0.218 0.000 0.00)",
-  "oklch(0.321 0.000 0.00)",
-  "oklch(0.420 0.000 0.00)",
-  "oklch(0.510 0.000 0.00)",
-  "oklch(0.600 0.000 0.00)",
-  "oklch(0.683 0.000 0.00)",
-  "oklch(0.767 0.000 0.00)",
-  "oklch(0.845 0.000 0.00)",
-  "oklch(0.885 0.000 0.00)",
-  "oklch(0.925 0.000 0.00)",
-  "oklch(0.961 0.000 0.00)",
-  "oklch(0.682 0.206 24.43)",
-  "oklch(0.871 0.2195 148.02)",
-  "oklch(0.955 0.134 112.76)",
-  "oklch(0.883 0.0934 212.85)"
-];
+const GREY_RAMPS = {
+  base: [
+    "oklch(0.965 0.000 0)",
+    "oklch(0.705 0.000 0)",
+    "oklch(0.480 0.000 0)",
+    "oklch(0.300 0.000 0)",
+    "oklch(0.185 0.000 0)"
+  ],
+  accent: [
+    "oklch(0.755 0.000 0)",
+    "oklch(0.700 0.000 0)",
+    "oklch(0.470 0.000 0)"
+  ],
+  state: {
+    danger: "oklch(0.640 0.170 25)",
+    success: "oklch(0.680 0.145 145)",
+    warning: "oklch(0.760 0.135 82)",
+    info: "oklch(0.680 0.130 245)"
+  }
+};
 const DEFAULT_SCHEME = {
-  background: "oklch(0.000 0.000 0.00)",
-  foreground: "oklch(1.000 0.000 0.00)",
-  cursor: "oklch(1.000 0.000 0.00)",
-  selectionBg: "oklch(0.387 0.000 0.00)",
-  selectionFg: "oklch(1.000 0.000 0.00)",
-  palette: GREY_RAMP
+  ramps: GREY_RAMPS,
+  map: {
+    bg: { base: 4 },
+    fg: { base: 0 },
+    selectionBg: { base: 2 },
+    selectionFg: { base: 0 },
+    semantic: { ...SEMANTIC_RAMP_DEFAULTS }
+  }
 };
 function DocHistoryStub(_props) {
   return /* @__PURE__ */ jsx(Fragment, {});

package/dist/color-scheme-utils.d.ts

@@ -1,113 +1,161 @@
 /**
- * Color-scheme MECHANISM — palette → `--zd-*` CSS custom-property injection.
+ * Color-scheme MECHANISM — ramp → `--palette-*` / `--zd-*` CSS custom-property
+ * injection.
  *
  * This module ships the pure computation layer used by every project that
  * builds on @takazudo/zudo-doc. It is DATA-free: callers pass in their own
  * color-scheme manifest and settings.
  *
+ * Ramp-native model (Color Ramp Restructure — zudolab/zudo-doc#2584; minimized
+ * to 5/3 in #2602). A `ColorScheme` is `{ ramps, map }`:
+ *   - `ramps` — the shared Tier-1 source of truth: a warm-neutral `base` ramp
+ *     (5 stops, index 0 = lightest), an `accent` ramp (3 stops), and 4 `state`
+ *     colors. Emitted verbatim as `--palette-{group}-{n}`.
+ *   - `map` — the per-mode Tier-2 wiring: which ramp stop (or literal OKLCH)
+ *     each UI role (`--zd-*`) points at, via a `RampRef`.
+ *
+ * The legacy ghostty 16-slot palette (`--zd-0..15`), `cursor`, `shikiTheme`,
+ * and the numeric `ColorRef` were dropped in that epic.
+ *
  * Moved from the host's `src/config/color-scheme-utils.ts` as part of the
- * package-first migration (S9a zudolab/zudo-doc#2333). The DATA (palette
- * values, scheme names, `colorMode` settings) stays project-side.
+ * package-first migration (S9a zudolab/zudo-doc#2333). The DATA (ramp values,
+ * scheme names, `colorMode` settings) stays project-side.
+ */
+/** A color literal — an `oklch(…)` (or any valid CSS color) string. */
+export type OKLCH = string;
+/** The four semantic state colors that live on their own ramp. */
+export type StateRole = "danger" | "success" | "warning" | "info";
+/** Canonical order of the state ramp — used for `--palette-state-*` emit. */
+export declare const STATE_ROLES: readonly StateRole[];
+/**
+ * A reference into the shared ramps, resolved by `resolveRampRef`:
+ *   - `{ base: n }`   → `ramps.base[n]`
+ *   - `{ accent: n }` → `ramps.accent[n]`
+ *   - `{ state: r }`  → `ramps.state[r]`
+ *   - a bare string   → a literal OKLCH value, returned as-is
  */
-/** A color reference: palette index (number) or direct color value (string) */
-export type ColorRef = number | string;
+export type RampRef = {
+    base: number;
+} | {
+    accent: number;
+} | {
+    state: StateRole;
+} | OKLCH;
+/** The shared Tier-1 ramps. Values are identical across light/dark modes; the
+ *  per-mode differences live in `ModeMap`, not here. */
+export interface Ramps {
+    /** Warm-neutral base ramp — 5 entries, index 0 = lightest. */
+    base: OKLCH[];
+    /** Accent ramp — 3 entries. */
+    accent: OKLCH[];
+    /** The four state colors. */
+    state: Record<StateRole, OKLCH>;
+}
+/** The 23 semantic roles that map onto `--zd-*` custom properties. */
+export type SemanticKey = "surface" | "muted" | "accent" | "accentHover" | "codeBg" | "codeFg" | "success" | "danger" | "warning" | "info" | "mermaidNodeBg" | "mermaidText" | "mermaidLine" | "mermaidLabelBg" | "mermaidNoteBg" | "chatUserBg" | "chatUserText" | "chatAssistantBg" | "chatAssistantText" | "imageOverlayBg" | "imageOverlayFg" | "matchedKeywordBg" | "matchedKeywordFg";
+/** Canonical order of the 23 semantic roles — used for `--zd-*` emit. */
+export declare const SEMANTIC_KEYS: readonly SemanticKey[];
+/** The per-mode wiring: each UI role points at a ramp stop (or literal OKLCH)
+ *  via a `RampRef`. Two `ColorScheme`s (light + dark) share `ramps` but carry
+ *  their own `ModeMap`. */
+export interface ModeMap {
+    bg: RampRef;
+    fg: RampRef;
+    selectionBg: RampRef;
+    selectionFg: RampRef;
+    semantic: Record<SemanticKey, RampRef>;
+}
+/** A complete color scheme — shared Tier-1 ramps + per-mode Tier-2 wiring. */
 export interface ColorScheme {
-    background: ColorRef;
-    foreground: ColorRef;
-    cursor: ColorRef;
-    selectionBg: ColorRef;
-    selectionFg: ColorRef;
-    palette: [
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string,
-        string
-    ];
-    /** Optional, vestigial — no visible effect on rendering; carried only for
-     *  the zdtp design-token panel config envelope. See project CLAUDE.md. */
-    shikiTheme?: string;
-    /** Optional semantic overrides. When omitted, defaults from
-     *  `SEMANTIC_DEFAULTS` are used (surface=p0, muted=p8, accent=p5, …). */
-    semantic?: {
-        surface?: ColorRef;
-        muted?: ColorRef;
-        accent?: ColorRef;
-        accentHover?: ColorRef;
-        codeBg?: ColorRef;
-        codeFg?: ColorRef;
-        success?: ColorRef;
-        danger?: ColorRef;
-        warning?: ColorRef;
-        info?: ColorRef;
-        mermaidNodeBg?: ColorRef;
-        mermaidText?: ColorRef;
-        mermaidLine?: ColorRef;
-        mermaidLabelBg?: ColorRef;
-        mermaidNoteBg?: ColorRef;
-        chatUserBg?: ColorRef;
-        chatUserText?: ColorRef;
-        chatAssistantBg?: ColorRef;
-        chatAssistantText?: ColorRef;
-        /** UI chrome over user images — enlarge/close overlay buttons */
-        imageOverlayBg?: ColorRef;
-        imageOverlayFg?: ColorRef;
-        /** <mark> highlight for matched keywords in search results */
-        matchedKeywordBg?: ColorRef;
-        matchedKeywordFg?: ColorRef;
+    ramps: Ramps;
+    map: ModeMap;
+}
+/** Default per-mode semantic wiring (Default Dark reference — see epic #2584).
+ *  Scheme authors spread this into `map.semantic` and override individual roles
+ *  where a mode needs a different stop (or a per-mode AA-tuned literal). */
+export declare const SEMANTIC_RAMP_DEFAULTS: Record<SemanticKey, RampRef>;
+export declare const SEMANTIC_CSS_NAMES: Record<SemanticKey, string>;
+/**
+ * Resolve a `RampRef` to a concrete color string against the given `ramps`.
+ *   - `{ base: n }`   → `ramps.base[n]`
+ *   - `{ accent: n }` → `ramps.accent[n]`
+ *   - `{ state: r }`  → `ramps.state[r]`
+ *   - a bare string   → the literal OKLCH value, returned as-is
+ *
+ * Throws on an out-of-range ramp index — a ramp reference to a stop that does
+ * not exist is a programming/authoring error and must fail loud rather than
+ * silently emit an invalid CSS value.
+ */
+export declare function resolveRampRef(ref: RampRef, ramps: Ramps): string;
+/** Resolve every semantic role to a concrete color string via the scheme's
+ *  per-mode `map.semantic` wiring. Returns all 23 keys. */
+export declare function resolveSemanticColors(scheme: ColorScheme): Record<SemanticKey, string>;
+export interface TierItem {
+    /** Stable id used as the Record key in persisted state (e.g. `surface`). */
+    id: string;
+    /** CSS custom property name written to `:root` (e.g. `--zd-surface`). */
+    cssVar: string;
+    /** Display label in the panel UI. */
+    label: string;
+    /** Default value — a panel-encoded ramp reference or literal OKLCH string. */
+    default: string;
+    /** Always the OKLCH color picker for semantic-tier rows. */
+    type: {
+        kind: "color";
+        format: "oklch";
     };
 }
-/** Default mapping: semantic token name → palette index */
-export declare const SEMANTIC_DEFAULTS: Record<string, number>;
-export declare const SEMANTIC_CSS_NAMES: Record<string, string>;
-/** Resolve a ColorRef to a concrete color string.
- *  - number → palette[value]
- *  - string → used as-is
- *  - undefined → fallback */
-export declare function resolveColor(value: ColorRef | undefined, palette: string[], fallback: string): string;
-/** Resolve semantic colors with fallbacks to default palette slots */
-export declare function resolveSemanticColors(scheme: ColorScheme): {
-    surface: string;
-    muted: string;
-    accent: string;
-    accentHover: string;
-    codeBg: string;
-    codeFg: string;
-    success: string;
-    danger: string;
-    warning: string;
-    info: string;
-    mermaidNodeBg: string;
-    mermaidText: string;
-    mermaidLine: string;
-    mermaidLabelBg: string;
-    mermaidNoteBg: string;
-    chatUserBg: string;
-    chatUserText: string;
-    chatAssistantBg: string;
-    chatAssistantText: string;
-    imageOverlayBg: string;
-    imageOverlayFg: string;
-    matchedKeywordBg: string;
-    matchedKeywordFg: string;
-};
-/** Convert a ColorScheme to a flat list of [cssProperty, value] pairs.
- *  The result is the exact set of `--zd-*` custom properties that the
- *  ColorSchemeProvider emits onto `:root`. */
-export declare function schemeToCssPairs(scheme: ColorScheme): [string, string][];
 /**
- * Generate the `:root { --zd-* }` CSS block for a single active color scheme.
+ * Encode a `RampRef` to the explicit `tierId:itemId` form the design-token
+ * panel's grouped ramp picker (`referencesRamps`) expects as an item default:
+ *   - `{ base: n }`   → `'base:base-n'`
+ *   - `{ accent: n }` → `'accent:accent-n'`
+ *   - `{ state: r }`  → `'state:state-r'`
+ *   - a bare string   → returned as-is (a literal OKLCH/hex passthrough)
+ *
+ * Always the explicit form (independent of `referencesRamps` declaration
+ * order) — see item-id contract in `buildRampTiers`
+ * (`src/config/design-token-panel-config.ts`): tier ids `base`/`accent`/`state`,
+ * item ids `base-0..4`/`accent-0..2`/`state-{danger,success,warning,info}`.
+ */
+export declare function rampRefToPanelDefault(ref: RampRef): string;
+/**
+ * Build the 27-row mode-scoped semantic tier's `items` for the design-token
+ * panel, from a single (already mode-resolved) `ColorScheme`: 4 base roles
+ * (`bg`, `fg`, `selection-bg`, `selection-fg`) followed by the 23
+ * `SEMANTIC_KEYS` rows, in that order. Every row's `default` is
+ * `rampRefToPanelDefault` of the scheme's `map` entry for that role — never a
+ * resolved literal color — so the panel's grouped ramp dropdown can decode it
+ * back to a ramp reference (the no-snapping guarantee: a scheme with no
+ * persisted override always round-trips through the panel to the exact same
+ * ramp stop, not a resolved color that happens to match).
+ */
+export declare function buildSemanticTierItems(scheme: ColorScheme): TierItem[];
+/** Which tiers a `schemeToCssPairs` call emits:
+ *   - `"all"` (default) — base roles + `--palette-*` + `--zd-*` semantic
+ *   - `"palette"`       — only the bare Tier-1 `--palette-*` pairs
+ *   - `"roles"`         — base roles + the 23 `--zd-*` semantic pairs
+ *
+ * The split lets `generateLightDarkCssProperties` emit the shared `--palette-*`
+ * once (bare) while wrapping the per-mode `--zd-*` roles in `light-dark(…)`.
+ * (A literal `"light"|"dark"` param would be inert here — each `ColorScheme`'s
+ * own `map` already encodes its mode.) */
+export type CssEmitScope = "all" | "palette" | "roles";
+/**
+ * Convert a `ColorScheme` to a flat list of `[cssProperty, value]` pairs.
+ *
+ * The full (`"all"`) set is the exact set of custom properties the
+ * ColorSchemeProvider emits onto `:root`:
+ *   - base roles: `--zd-bg`, `--zd-fg`, `--zd-selection-bg`, `--zd-selection-fg`
+ *   - Tier-1 ramps: `--palette-base-0..4`, `--palette-accent-0..2`,
+ *     `--palette-state-{danger,success,warning,info}`
+ *   - the 23 Tier-2 `--zd-{role}` semantic tokens
+ *
+ * It intentionally does NOT emit the retired `--zd-0..15` slots or `--zd-cursor`.
+ */
+export declare function schemeToCssPairs(scheme: ColorScheme, scope?: CssEmitScope): [string, string][];
+/**
+ * Generate the `:root { … }` CSS block for a single active color scheme.
  *
  * The caller passes in the active `ColorScheme` object — resolved from the
  * project's `colorSchemes` map and `settings.colorScheme`. This function is
@@ -115,11 +163,14 @@ export declare function schemeToCssPairs(scheme: ColorScheme): [string, string][
  */
 export declare function generateCssCustomProperties(scheme: ColorScheme): string;
 /**
- * Generate the `:root { --zd-*: light-dark(…, …); }` CSS block for a
- * light/dark pair.
+ * Generate the `:root { … }` CSS block for a light/dark pair.
+ *
+ * Tier-1 `--palette-*` properties are shared across modes (the ramps carry the
+ * same values in both schemes), so they are emitted ONCE, bare. The per-mode
+ * `--zd-*` roles (base roles + semantic) are wrapped in `light-dark(L, D)`.
  *
  * The caller passes in the `light` and `dark` `ColorScheme` objects — resolved
- * from the project's `colorSchemes` map and `settings.colorMode`. This
- * function is DATA-free.
+ * from the project's `colorSchemes` map and `settings.colorMode`. This function
+ * is DATA-free.
  */
 export declare function generateLightDarkCssProperties(light: ColorScheme, dark: ColorScheme): string;