@cueplusplus/ui 0.13.0

package/dist/theming/create-theme.d.ts

@@ -0,0 +1,195 @@
+import { ContrastReport } from "./contrast.js";
+import { Density } from "@cueplusplus/tokens";
+import { ColorToken, ThemeManifest } from "@cueplusplus/theme-base";
+//#region src/theming/create-theme.d.ts
+/**
+ * `createTheme()` — the typed generator behind the spec's second theming tier.
+ *
+ * Three things it is not, because each of them is a trap this deliberately
+ * avoids:
+ *
+ * - **Not a runtime engine.** It is a pure function of its arguments, called at
+ *   build time (or once, in the configurator's export dialog), and what comes
+ *   out is a plain `[data-theme]` stylesheet — tier 1, the guaranteed contract.
+ *   Nothing about a shipped app depends on this module existing.
+ * - **Not a palette generator.** Handed a preset and nothing else it returns the
+ *   preset, byte for byte. Derivation is what happens to the tokens hanging off
+ *   an anchor you actually moved, and only those: swap the accent and the hover,
+ *   the ink on it, the focus ring and the selection wash follow; the ground, the
+ *   ink and the five status tones do not. That rule is the whole reason
+ *   "start from `terminal`, make it orange" is a two-line call rather than a
+ *   fork of a palette.
+ * - **Not a colour opinion.** Every derivation happens in oklch, where a
+ *   lightness step is a step the eye agrees with, and every result is measured
+ *   against WCAG before you are told it is fine. A failing pair comes back in
+ *   the report rather than being silently repaired — with one exception, noted
+ *   below, where the value was this module's invention in the first place.
+ */
+/**
+ * The colour tokens every theme block declares, in the order the contract lists
+ * them.
+ *
+ * Not a list this module owns any more, and not a copy of one: it *is*
+ * `COLOR_CONTRACT`, re-exported under the name this package's public API has
+ * always used. The two were byte-identical — twenty-six names, same order —
+ * because the copy was written from the contract in the first place, and a
+ * second list that has to agree with the first is a drift test waiting to be
+ * written. `test/theming/create-theme.test.ts` asserts the identity, so a future
+ * edit that quietly reintroduces a local array fails rather than diverges.
+ */
+declare const THEME_COLOR_TOKENS: readonly ["bg", "sunken", "surface-1", "surface-2", "surface-3", "fg", "fg-muted", "fg-subtle", "border", "border-strong", "border-overlay", "accent", "accent-hover", "accent-fg", "ok", "busy", "warn", "warn-fg", "danger", "danger-fg", "info", "stream", "selection", "focus", "data-ground", "scrim"];
+/** One of the colour tokens a theme block owns. */
+type ThemeColorToken = ColorToken;
+/**
+ * How far the sunken ground sits below the page, in oklch lightness.
+ *
+ * Small on purpose: sunken is a well, not a second theme. Across the ten
+ * shipped presets the authored gap runs −0.011 to −0.031.
+ */
+declare const SUNKEN_LIGHTNESS_STEP = -0.02;
+/**
+ * The three raised surfaces, as lightness above the ground.
+ *
+ * Even spacing, because the ladder encodes *elevation* and a reader counts
+ * rungs. The shipped presets cluster around these three values.
+ */
+declare const SURFACE_LIGHTNESS_STEPS: readonly number[];
+/**
+ * The hairline and its stronger sibling, as lightness above the ground.
+ *
+ * Above the top surface, so a border still reads as a line when it is drawn on
+ * `surface-3`. `border-overlay` reuses the strong value: an overlay floats over
+ * everything, so its rim has to hold against the brightest thing under it.
+ */
+declare const BORDER_LIGHTNESS_STEPS: readonly number[];
+/** How far secondary ink recedes from primary ink. */
+declare const FG_MUTED_LIGHTNESS_STEP = -0.25;
+/** How far tertiary ink recedes from primary ink. */
+declare const FG_SUBTLE_LIGHTNESS_STEP = -0.45;
+/**
+ * Chroma each rung of the ink ramp keeps from the rung above.
+ *
+ * Ink greys as it recedes rather than staying saturated: a muted label that held
+ * full chroma would read as a *coloured* label — a status, a link — instead of a
+ * quiet one. The hue is preserved throughout, so the ramp still belongs to the
+ * theme. `fg-subtle` takes the square, being two rungs down.
+ */
+declare const INK_RAMP_CHROMA_SCALE = 0.6;
+/** How far the accent darkens on hover. */
+declare const ACCENT_HOVER_LIGHTNESS_STEP = -0.05;
+/** How much accent a derived selection wash carries. */
+declare const SELECTION_ACCENT_PERCENT = 22;
+/** What a label on a solid accent has to reach before this module accepts it. */
+declare const ACCENT_FG_MINIMUM = 4.5;
+/**
+ * How much of the dark ground's lightness survives the flip to paper.
+ *
+ * A ground's job is to be the extreme, so inverting it means going to the *other*
+ * extreme rather than to the arithmetic mirror: `1 − L` of a 0.16 near-black is a
+ * 0.84 mid-grey, which is not a page. Compressing instead maps the ladder of
+ * dark grounds onto a narrow paper band — a deeper dark theme gets a cleaner
+ * white page — and lands within 0.01 of all ten authored light presets.
+ */
+declare const LIGHT_GROUND_COMPRESSION = 0.1;
+interface ThemeAnchors {
+  /**
+   * The theme's name. Lands in `[data-theme="…"]`, so it must be a CSS
+   * identifier: letters, digits and dashes, starting with a letter.
+   */
+  name: string;
+  /**
+   * The manifest to start from. Every token you do not move comes back verbatim.
+   *
+   * A manifest, not a name: this package holds no table of palettes to look a
+   * name up in, and one is exactly what it stopped holding. Pass the default
+   * export of a theme package — `@cueplusplus/theme-terminal`'s, say — or any
+   * manifest of your own. Absent means the blank base: the neutral ramp
+   * `@cueplusplus/theme-base` ships, which every theme's deltas were diffed
+   * against.
+   *
+   * The package is named in prose rather than shown as an `import` line on
+   * purpose. Every barrel test in this package scrapes imports with a regex
+   * that cannot tell a doc comment from code, and to those tests an example
+   * import reads as `ui` depending on a theme package — which it may not, at
+   * runtime or otherwise.
+   */
+  base?: ThemeManifest;
+  /**
+   * The ground. Moving it re-derives the sunken well, the three raised surfaces
+   * and the three border weights.
+   */
+  bg?: string;
+  /** Primary ink. Moving it re-derives `fg-muted` and `fg-subtle`. */
+  fg?: string;
+  /**
+   * The accent. Moving it re-derives `accent-hover`, `accent-fg`, `focus` and
+   * `selection`.
+   */
+  accent?: string;
+  /** Individual rungs of the surface ladder, overriding whatever would be derived. */
+  surfaces?: Partial<Record<"sunken" | "surface-1" | "surface-2" | "surface-3", string>>;
+  /**
+   * Individual status tones, plus `stream` — the live hue an agent surface
+   * paints a token still arriving with. Never derived: a signal colour is a
+   * decision.
+   */
+  status?: Partial<Record<"ok" | "busy" | "warn" | "danger" | "info" | "stream", string>>;
+  /**
+   * Font stacks. `mono` is the one the presets themselves override; `sans` and
+   * `display` are emitted only when given. Values pass through verbatim, so they
+   * are checked for CSS punctuation rather than parsed.
+   */
+  fonts?: Partial<{
+    sans: string;
+    mono: string;
+    display: string;
+  }>;
+  /**
+   * Multiplier on every corner radius. Crossed with the density ladder rather
+   * than declared flat, so `ultra-compact` keeps its tighter corners.
+   */
+  radiusScale?: number;
+  /**
+   * Whether to emit a light block. Defaults to whether the base preset has one.
+   * Setting it `true` on a dark-only preset derives one, and marks the report
+   * provisional.
+   */
+  supportsLight?: boolean;
+}
+interface CreatedTheme {
+  /** The name that was asked for, once validated. */
+  name: string;
+  /**
+   * The stylesheet: the dark block, the light block if there is one, and one
+   * crossed density rule per radius scale that differs from the default's.
+   */
+  css: string;
+  /**
+   * The dark block as a map, keyed by the exact `--cue-*` property names the
+   * tokens build emits. Says the same thing as the dark block of {@link css}.
+   */
+  tokens: Record<string, string>;
+  /** The light block as a map, or `null` when the theme is dark-only. */
+  light: Record<string, string> | null;
+  /** Every WCAG pair, measured. Read it — a failing theme still returns. */
+  report: ContrastReport;
+}
+/**
+ * Generate a theme: a stylesheet, its token map, and a contrast report.
+ *
+ * Pure and synchronous. Call it in a build script, in a test, or in the
+ * configurator's export dialog — never in a render path, because there is
+ * nothing here a stylesheet is not already doing faster.
+ *
+ * @param anchors - The name, the manifest to start from, and whatever you moved.
+ * @returns The stylesheet, the resolved tokens for both modes, and the report.
+ * @throws TypeError if the name is not a CSS identifier, an anchor is not a
+ *   colour, a font stack carries CSS punctuation, or `base` is a theme *name*
+ *   rather than a manifest.
+ * @example
+ * const { css, report } = createTheme({ name: "acme", accent: "#ff8800" });
+ * if (!report.passes) console.warn(report.failures);
+ */
+declare function createTheme(anchors: ThemeAnchors): CreatedTheme;
+//#endregion
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CreatedTheme, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, ThemeAnchors, ThemeColorToken, createTheme };