zabi-components 8.0.0 → 9.0.0

package/dist/components/util/zabi-strings.d.ts

@@ -0,0 +1,142 @@
+import type { AvatarGroupStrings } from "./avatar.js";
+import type { CalendarStrings } from "./calendar.js";
+import type { DateFieldStrings, TimeFieldStrings } from "./temporal-field.js";
+import type { MediaGridStrings } from "./media-grid.js";
+import type { CodeFieldStrings } from "./code-field.js";
+import type { PhotoGridStrings, PhotoViewerStrings } from "./photo.js";
+import type { ProgressStrings } from "./progress.js";
+import type { PullToRefreshStrings } from "./pull-to-refresh.js";
+import type { RatingStrings } from "./rating.js";
+import type { ColorPickerStrings, ComponentDemoStrings, ContactFormStrings, PropsTableStrings } from "./ready-made-strings.js";
+import type { SelectStrings } from "./select.js";
+import type { SkeletonStrings } from "./skeleton.js";
+import type { SidebarAccountPanelStrings, SidebarBrandHeaderStrings, SidebarFooterStrings, SidebarNavigationStrings } from "./sidebar.js";
+import type { SortableListStrings } from "./sortable-list.js";
+import type { StepperStrings } from "./stepper.js";
+import type { SwipeableListItemStrings } from "./swipeable-list-item.js";
+import type { ThemeToggleLabels } from "./theme-mode.js";
+import type { ToasterStrings } from "./toaster.js";
+import type { TopNavbarStrings } from "./top-navbar.js";
+/**
+ * The few words that many components' single-text props default to. A
+ * component whose prop is not given says the one here.
+ */
+export interface ZabiCommonStrings {
+    /** The close button of a dialog, a drawer or a sheet (`closeLabel`). */
+    close: string;
+    /** AppBar's back control (`backLabel`). */
+    back: string;
+    /** A sheet's grip while it takes the sheet up a step (`expandLabel`). */
+    expand: string;
+    /** The same, while it takes it down (`collapseLabel`). */
+    collapse: string;
+    /** Read after the label of a required field (FormField's `requiredLabel`). */
+    required: string;
+    /** The button in a password field that shows what was typed (Input's `revealLabel`). */
+    showPassword: string;
+    /** Placeholder of a search field in a sidebar (`searchPlaceholder`). */
+    search: string;
+    /** ConfirmDialog's confirming button (`confirmLabel`). */
+    confirm: string;
+    /** ConfirmDialog's other button (`cancelLabel`). */
+    cancel: string;
+}
+export declare const DEFAULT_ZABI_COMMON_STRINGS: ZabiCommonStrings;
+/** Toast's own text: `closeLabel`. */
+export interface ToastTexts {
+    closeLabel: string;
+}
+export declare const DEFAULT_TOAST_TEXTS: ToastTexts;
+/** Alert's own text: `closeLabel`. */
+export interface AlertTexts {
+    closeLabel: string;
+}
+export declare const DEFAULT_ALERT_TEXTS: AlertTexts;
+/** CodeBlock's own texts: the copy button's name, and what is announced once copied. */
+export interface CodeBlockTexts {
+    copyLabel: string;
+    copiedLabel: string;
+}
+export declare const DEFAULT_CODE_BLOCK_TEXTS: CodeBlockTexts;
+/** ImageUpload's own texts, by the name of the prop each one is. */
+export interface ImageUploadTexts {
+    placeholder: string;
+    browseText: string;
+    changeText: string;
+    removeText: string;
+    selectedText: string;
+    removedText: string;
+    errorTitle: string;
+    errorRecovery: string;
+}
+export declare const DEFAULT_IMAGE_UPLOAD_TEXTS: ImageUploadTexts;
+/** UnsavedChangesBar's own texts, by the name of the prop each one is. */
+export interface UnsavedChangesBarTexts {
+    message: string;
+    label: string;
+    saveLabel: string;
+    discardLabel: string;
+}
+export declare const DEFAULT_UNSAVED_CHANGES_BAR_TEXTS: UnsavedChangesBarTexts;
+/** One optional entry per component that has words of its own, and `common`. */
+export interface ZabiStrings {
+    common?: Partial<ZabiCommonStrings>;
+    alert?: Partial<AlertTexts>;
+    avatarGroup?: Partial<AvatarGroupStrings>;
+    calendar?: Partial<CalendarStrings>;
+    codeBlock?: Partial<CodeBlockTexts>;
+    codeField?: Partial<CodeFieldStrings>;
+    colorPicker?: Partial<ColorPickerStrings>;
+    dateField?: Partial<DateFieldStrings>;
+    componentDemo?: Partial<ComponentDemoStrings>;
+    contactForm?: Partial<ContactFormStrings>;
+    imageUpload?: Partial<ImageUploadTexts>;
+    mediaGrid?: Partial<MediaGridStrings>;
+    photoGrid?: Partial<PhotoGridStrings>;
+    photoViewer?: Partial<PhotoViewerStrings>;
+    propsTable?: Partial<PropsTableStrings>;
+    progress?: Partial<ProgressStrings>;
+    pullToRefresh?: Partial<PullToRefreshStrings>;
+    rating?: Partial<RatingStrings>;
+    select?: Partial<SelectStrings>;
+    skeleton?: Partial<SkeletonStrings>;
+    sidebarAccountPanel?: Partial<SidebarAccountPanelStrings>;
+    sidebarBrandHeader?: Partial<SidebarBrandHeaderStrings>;
+    sidebarFooter?: Partial<SidebarFooterStrings>;
+    sidebarNavigation?: Partial<SidebarNavigationStrings>;
+    sortableList?: Partial<SortableListStrings>;
+    stepper?: Partial<StepperStrings>;
+    swipeableListItem?: Partial<SwipeableListItemStrings>;
+    themeToggle?: Partial<ThemeToggleLabels>;
+    timeField?: Partial<TimeFieldStrings>;
+    toast?: Partial<ToastTexts>;
+    toaster?: Partial<ToasterStrings>;
+    topNavbar?: Partial<TopNavbarStrings>;
+    unsavedChangesBar?: Partial<UnsavedChangesBarTexts>;
+}
+/** What the context holds: an object whose `current` is read when it is needed, so a change reaches every reader. */
+export interface ZabiStringsContext {
+    readonly current: ZabiStrings;
+}
+/** `over` on top of `under`, entry by entry: an inner provider only replaces the words it gives. */
+export declare function mergeZabiStrings(under: ZabiStrings | undefined, over: ZabiStrings | undefined): ZabiStrings;
+/** For `ZabiStringsProvider`: the provider above this one, if any. Call while the component initialises. */
+export declare function outerZabiStrings(): ZabiStringsContext | undefined;
+/** For `ZabiStringsProvider`: makes `context` what everything below reads. */
+export declare function provideZabiStrings(context: ZabiStringsContext): void;
+/**
+ * The words of the provider this component is under, for app code that wants
+ * the same words elsewhere. Call it while the component initialises, and read
+ * `current` where the words are used (in the markup, or a `$derived`), so a
+ * change of language is followed. Outside a provider `current` is empty.
+ */
+export declare function getZabiStrings(): ZabiStringsContext;
+/**
+ * A component's own entry: `zabiStringsFor("select")` returns a function that
+ * gives the provider's words for Select now, or undefined. Call it while the
+ * component initialises; call what it returns inside a `$derived`.
+ */
+export declare function zabiStringsFor<K extends Exclude<keyof ZabiStrings, "common">>(key: K): () => ZabiStrings[K];
+/** The common words with their defaults filled in, the same way. */
+export declare function zabiCommonStrings(): () => ZabiCommonStrings;
+//# sourceMappingURL=zabi-strings.d.ts.map

package/dist/components/util/zabi-strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zabi-strings.d.ts","sourceRoot":"","sources":["../../../src/components/util/zabi-strings.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EACR,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACR,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,wBAAwB,EAC3B,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAC9B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,2BAA2B,EAAE,iBAUzC,CAAC;AAOF,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,MAAM,CAAC;CACtB;AACD,eAAO,MAAM,mBAAmB,EAAE,UAAiD,CAAC;AAEpF,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,MAAM,CAAC;CACtB;AACD,eAAO,MAAM,mBAAmB,EAAE,UAA4C,CAAC;AAE/E,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACvB;AACD,eAAO,MAAM,wBAAwB,EAAE,cAGtC,CAAC;AAEF,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACzB;AACD,eAAO,MAAM,0BAA0B,EAAE,gBASxC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACxB;AACD,eAAO,MAAM,iCAAiC,EAAE,sBAK/C,CAAC;AAEF,gFAAgF;AAChF,MAAM,WAAW,WAAW;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,aAAa,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC9C,WAAW,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,aAAa,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAC1D,kBAAkB,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACxD,aAAa,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC9C,iBAAiB,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACvD;AAED,qHAAqH;AACrH,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CACjC;AAKD,oGAAoG;AACpG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAQ3G;AAED,4GAA4G;AAC5G,wBAAgB,gBAAgB,IAAI,kBAAkB,GAAG,SAAS,CAEjE;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,kBAAkB,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,WAAW,EAAE,QAAQ,CAAC,EACzE,GAAG,EAAE,CAAC,GACP,MAAM,WAAW,CAAC,CAAC,CAAC,CAGtB;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,MAAM,iBAAiB,CAM3D"}

package/dist/create-theme/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * zabi-theme — the command line over createTheme.
+ *
+ *   npx zabi-theme --brand "#0026EA" --out src/lib/brand.generated.css
+ *
+ * The stylesheet goes to --out, or to stdout. Everything else (warnings, the
+ * one-line summary) goes to stderr, so `zabi-theme … > file.css` stays clean.
+ *
+ * Exit codes: 0 done · 1 --strict and a role pair is below WCAG AA · 2 bad usage.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createTheme } from './index.js';
+
+const HELP = `zabi-theme: generate brand tokens for zabi-components
+
+Usage
+  zabi-theme --brand <hex> [--pin] [--accent <hex>] [--pin-accent] [--neutral <hex>]
+             [--neutral-chroma <n>] [--dark-primary brand|mirror]
+             [--out <file>] [--strict] [--set <token>=<value> ...]
+             [--set-light <token>=<value> ...] [--set-dark <token>=<value> ...]
+
+Options
+  --brand <hex>     Brand colour (required). Builds --zabi-brand-50 … 950.
+  --pin             Put the exact brand colour on primary buttons (see below).
+  --accent <hex>    Second brand colour. Builds --zabi-accent-50 … 950.
+  --pin-accent      The same for the solid accent fill. Needs --accent.
+  --neutral <hex>   Tints the 21-step neutral ramp, --zabi-base-50 … 950.
+  --neutral-chroma <n>
+                    Chroma at the neutral ramp's peak, 0 to 0.1 (OKLCH). Default: the
+                    hue of --neutral at most 0.03. Use 0.04 to 0.06 for a clearly
+                    tinted neutral. Needs --neutral. With it, the ink roles (secondary
+                    button, hover and pressed tints, overlay edge, shadow colour)
+                    follow the neutral ramp instead of staying grey.
+  --dark-primary <brand|mirror>
+                    Dark primary and danger fills. brand (default): the same steps as
+                    light, with a white label. mirror: the 8.1 pale mirrored steps.
+  --out <file>      Write the CSS here. Without it the CSS goes to stdout.
+  --strict          Exit 1 when any role pair is below WCAG AA.
+  --set <t>=<v>     Also write this declaration, e.g. --set "--color-link=var(--color-brand-800)".
+                    Repeatable. It applies in light and dark and is contrast-checked.
+  --set-light <t>=<v>
+                    The same, for light only. Dark keeps the library's own value for that
+                    token: the file restates it under the dark selectors. Repeatable.
+  --set-dark <t>=<v>
+                    The same, for dark only. Repeatable. A token given to --set and to
+                    --set-light or --set-dark: the mode-specific value wins in its mode.
+  --help            Show this text.
+
+Each ramp is built on the library's lightness curve. Your colour supplies hue
+and chroma and is not pinned to a step, so the exact hex may not appear in the
+file; the header says which step is closest.
+
+With --pin the ramp is the same, and the primary action is the exact colour in
+light: the fill, its hover and pressed states, and where they still pass, the
+focus ring and links. The label is white or the ramp's dark end, whichever
+reaches 4.5:1. Dark takes the colour only if it passes there; otherwise dark
+keeps the ramp, and the header says so. A pair that fails is reported, and
+the colour is never moved to make it pass.
+
+Import the file after the theme:
+  @import "zabi-components/theme-only";
+  @import "zabi-components/theme-dark-only";
+  @import "./brand.generated.css";
+`;
+
+const VALUE_OPTIONS = ['brand', 'accent', 'neutral', 'neutral-chroma', 'dark-primary', 'out'];
+const FLAG_OPTIONS = ['strict', 'help', 'pin', 'pin-accent'];
+
+function usageError(message) {
+    process.stderr.write(`zabi-theme: ${message}\nRun "zabi-theme --help" for usage.\n`);
+    process.exit(2);
+}
+
+function parseArgs(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '-h') { options.help = true; continue; }
+        if (!arg.startsWith('--')) usageError(`unexpected argument "${arg}"`);
+        const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
+        if (name === 'set' || name === 'set-light' || name === 'set-dark') {
+            // The value is itself a custom property name, so it starts with "--".
+            const pair = inline !== undefined ? inline : argv[(i += 1)];
+            const match = /^(--[\w-]+)\s*[=:]\s*(.+)$/s.exec(pair ?? '');
+            if (!match) usageError(`--${name} needs <token>=<value>, for example --${name} "--color-link=var(--color-brand-800)"`);
+            // `--set` alone stays the flat map; a mode flag adds its own map.
+            const key = name === 'set' ? 'both' : name === 'set-light' ? 'light' : 'dark';
+            options.modes = { ...options.modes, [key]: { ...options.modes?.[key], [match[1]]: match[2].trim() } };
+        } else if (FLAG_OPTIONS.includes(name)) {
+            if (inline !== undefined) usageError(`--${name} takes no value`);
+            options[name] = true;
+        } else if (VALUE_OPTIONS.includes(name)) {
+            const value = inline !== undefined ? inline : argv[(i += 1)];
+            if (value === undefined || value === '' || (inline === undefined && value.startsWith('--'))) {
+                usageError(`--${name} needs a value`);
+            }
+            options[name] = value;
+        } else {
+            usageError(`unknown option "--${name}"`);
+        }
+    }
+    return options;
+}
+
+function parseChroma(text) {
+    const value = Number(text);
+    if (text.trim() === '' || !Number.isFinite(value)) usageError(`--neutral-chroma must be a number such as 0.05 (got "${text}")`);
+    return value;
+}
+
+const options = parseArgs(process.argv.slice(2));
+
+if (options.help) {
+    process.stdout.write(HELP);
+    process.exit(0);
+}
+if (!options.brand) usageError('--brand is required, for example --brand "#0026EA"');
+
+let result;
+try {
+    result = createTheme({
+        brand: options.brand,
+        accent: options.accent,
+        neutral: options.neutral,
+        // Left out when not asked for, so the options are what they always were.
+        ...(options['neutral-chroma'] !== undefined ? { neutralChroma: parseChroma(options['neutral-chroma']) } : {}),
+        ...(options['dark-primary'] !== undefined ? { darkPrimary: options['dark-primary'] } : {}),
+        // `--set` alone is the flat map, as it always was; a mode flag makes it { light, dark, both }.
+        overrides: options.modes && (options.modes.light || options.modes.dark) ? options.modes : options.modes?.both,
+        // Left out when not asked for, so the options are what they always were.
+        ...(options.pin || options['pin-accent'] ? { pin: { brand: !!options.pin, accent: !!options['pin-accent'] } } : {}),
+    });
+} catch (error) {
+    if (error instanceof TypeError) usageError(error.message.replace(/^zabi-theme: /, ''));
+    throw error;
+}
+
+if (options.out) {
+    const target = path.resolve(options.out);
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, result.css, 'utf8');
+    } catch (error) {
+        usageError(`could not write ${options.out}: ${error.message}`);
+    }
+} else {
+    process.stdout.write(result.css);
+}
+
+const contrast = result.warnings.filter((warning) => warning.type === 'contrast');
+for (const warning of result.warnings) {
+    process.stderr.write(`zabi-theme: warning: ${warning.message}\n`);
+}
+const closest = Object.entries(result.closest)
+    .map(([name, c]) => `${name} closest to step ${c.step}`)
+    .join(', ');
+for (const [name, report] of Object.entries(result.pinned ?? {})) {
+    process.stderr.write(
+        `zabi-theme: ${name} ${report.hex} is pinned in light` +
+            (report.dark.pinned ? ' and in dark.\n' : '; dark keeps the ramp, because the colour fails there.\n'),
+    );
+}
+process.stderr.write(
+    `zabi-theme: ${options.out ? `wrote ${options.out}` : 'done'} (${closest}); ` +
+        (contrast.length === 0
+            ? 'every role pair passes WCAG AA in light and dark.\n'
+            : `${contrast.length} role pair${contrast.length === 1 ? '' : 's'} below WCAG AA.\n`),
+);
+
+if (options.strict && contrast.length > 0) process.exit(1);

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

@@ -0,0 +1,190 @@
+/** A hex colour: `#rgb` or `#rrggbb`, with or without the `#`. */
+export type HexColor = string;
+
+/** A map of custom property names to values. */
+export type TokenMap = Record<string, string>;
+
+/**
+ * Either one map for both modes, or `light`, `dark` and `both` maps. The two
+ * forms may be mixed: a `--token` key beside them counts as `both`.
+ */
+export type Overrides = TokenMap | ({ light?: TokenMap; dark?: TokenMap; both?: TokenMap } & { [token: `--${string}`]: string });
+
+export interface CreateThemeOptions {
+    /**
+     * The brand colour. Supplies hue and chroma for `--zabi-brand-50 … 950`:
+     * primary actions, focus rings, links and brand tints.
+     */
+    brand: HexColor;
+    /** Second brand colour, for `--zabi-accent-50 … 950`. Omitted: the library's citron. */
+    accent?: HexColor;
+    /**
+     * Tints the neutral ramp, `--zabi-base-50 … 950` (21 steps), toward this
+     * hue: text, borders, the page, cards and the dark surface levels. Only the
+     * hue and a little chroma are used. Omitted: the library's greys.
+     */
+    neutral?: HexColor;
+    /**
+     * The OKLCH chroma at the neutral ramp's peak, `0` to `0.1`. Needs
+     * `neutral`, which still supplies the hue. Omitted: the ramp takes the hue
+     * of `neutral` at no more than 0.03 chroma, so it stays a tinted grey. For a
+     * clearly tinted neutral, such as a blue-slate UI, give 0.04 to 0.06. The
+     * profile across the 21 steps is the same; only its peak moves.
+     *
+     * With it, the translucent ink roles follow the neutral ramp instead of
+     * staying grey: `--color-action-secondary` (and `-hover`, `-active`),
+     * `--color-surface-hover`, `--color-surface-active` and
+     * `--color-border-overlay` become `color-mix()` of `--zabi-base-900` (light)
+     * or `--zabi-base-50` (dark) at their usual alphas, and `--shadow-color` is
+     * the ramp's step 900 in light. `--color-overlay` (the modal scrim) stays
+     * black. Dark values are written under the dark selectors, as with `pin`.
+     * Omitted: the output is exactly what it is without the option.
+     *
+     * The contrast check does not evaluate these translucent roles, with or
+     * without the option.
+     */
+    neutralChroma?: number;
+    /**
+     * What the dark primary and danger fills are. `'brand'` (the default) is
+     * what the library does: the same steps as light (600, 700, 800) with a
+     * white label, so the main action keeps its colour in dark, and nothing
+     * extra is written. `'mirror'` restores the 8.1 behaviour: under the dark
+     * selectors the primary is the mirrored `--color-brand-600 | 700 | 800`
+     * (pale steps in dark), danger the mirrored `--color-error-600 | 700 | 800`,
+     * the label is chosen by the contrast check, and the control veil is the
+     * lighten-heavy 22% / 6%. A `dark` or `both` override of any of these roles
+     * wins over both settings. With `pin`, dark takes the pinned colour only
+     * when no guarded pair fails with it, and otherwise keeps what this option
+     * gives.
+     */
+    darkPrimary?: 'brand' | 'mirror';
+    /**
+     * Extra declarations written after the ramps, for example
+     * `{ "--color-link": "var(--color-brand-800)" }`. They apply in light and in
+     * dark, and take part in the contrast check and in the choice of the "on"
+     * colours.
+     *
+     * Or per mode: `{ light, dark, both }`, each a map of the same shape.
+     * `both` is the flat form (flat keys beside the three also count as `both`).
+     * A token in `light` goes on `:root`, and the file restates the library's
+     * own dark value for it under the dark selectors, so dark does not move; a
+     * token in `dark` is written only under the dark selectors. A token set in
+     * `both` and in a mode takes the mode's value in that mode. The contrast
+     * check uses each mode's own values. A token the library defines no dark
+     * value for (or one you invented) cannot be put back in dark: it stays what
+     * `light` says there unless you also set it in `dark`.
+     *
+     * @example
+     * overrides: { light: { "--color-surface-raised": "#f8faff" } }
+     */
+    overrides?: Overrides;
+    /**
+     * Put the exact colour on the solid fill, where the ramp would use its
+     * step 600. `true` pins the brand: in light, `--color-action-primary` is
+     * the hex you gave, with hover and pressed states derived from it and a
+     * label (white, or the ramp's dark end) that reaches 4.5:1 on all three.
+     * The focus ring and links take the colour too where every guarded pair
+     * still passes, and stay on the ramp where it would not. The ramp itself,
+     * and so every tint and border, is unchanged.
+     *
+     * Dark takes the colour only if nothing guarded fails with it; otherwise
+     * dark keeps the mirrored ramp step, as it does without `pin`.
+     *
+     * A pair that fails with the pinned colour is reported in `warnings`. The
+     * colour is never moved to make it pass.
+     *
+     * `{ accent: true }` does the same for `--color-accent` and needs `accent`.
+     * Omitted or `false`: the output is exactly what it is without the option.
+     */
+    pin?: boolean | { brand?: boolean; accent?: boolean };
+}
+
+/** A role pair below WCAG AA with the generated ramps in place. */
+export interface ContrastWarning {
+    type: 'contrast';
+    /** The pair, as the library's contrast guard names it, e.g. `"link on page"`. */
+    pair: string;
+    mode: 'light' | 'dark';
+    /** Measured ratio, to two decimals. */
+    ratio: number;
+    /** 4.5 for text, 3 for UI parts and focus rings. */
+    required: number;
+    foreground: { token: string; value: string };
+    background: { token: string; value: string };
+    message: string;
+}
+
+/** An input that will not give the ramp its author probably expects. */
+/** What `pin` did with one colour. */
+export interface PinReport {
+    /** The pinned colour, as `#rrggbb`. */
+    hex: string;
+    light: {
+        /** Role groups that took the colour besides the fill: `"focus ring"`, `"link"`, `"accent text"`. */
+        followed: string[];
+        /** Role groups left on the ramp, because the colour fails a guarded pair there. */
+        onRamp: string[];
+        /** Which way hover and pressed go from the fill. */
+        states: 'darker' | 'lighter';
+    };
+    dark: {
+        /** False when the colour fails in dark and dark keeps the ramp. */
+        pinned: boolean;
+        followed: string[];
+        onRamp: string[];
+        states?: 'darker' | 'lighter';
+        /** When not pinned: the pairs that would fail with the colour. */
+        failed?: string[];
+    };
+}
+
+export interface InputWarning {
+    type: 'input';
+    option: 'brand' | 'accent' | 'neutral';
+    message: string;
+}
+
+export type ThemeWarning = ContrastWarning | InputWarning;
+
+/** Where an input colour landed in the ramp built from it. */
+export interface ClosestStep {
+    step: number;
+    hex: string;
+    /** CIELAB ΔE*ab between the input and that step, to one decimal. */
+    deltaE: number;
+    exact: boolean;
+}
+
+export interface CreateThemeResult {
+    /**
+     * The stylesheet: a header comment and one `:root { … }` rule. With `pin`,
+     * `neutralChroma`, `darkPrimary: 'mirror'` or `light` / `dark` overrides, two more rules follow, with the dark values of those roles:
+     * `.dark, [data-theme="dark"] { … }` and the same declarations for
+     * `[data-theme="auto"]` inside `@media (prefers-color-scheme: dark)`.
+     */
+    css: string;
+    /** Every declaration of the `:root` rule, name to value, in output order. */
+    tokens: Record<string, string>;
+    /** Only with `pin`, `neutralChroma`, `darkPrimary: 'mirror'` or `light` / `dark` overrides: every declaration of the dark rules. */
+    darkTokens?: Record<string, string>;
+    /** Only with `pin`: what was pinned and which roles took the colour. */
+    pinned?: { brand?: PinReport; accent?: PinReport };
+    /** Contrast failures and input notes. Empty when everything passes. */
+    warnings: ThemeWarning[];
+    closest: { brand: ClosestStep; accent?: ClosestStep; neutral?: ClosestStep };
+}
+
+/**
+ * Builds the ramps for a brand on the library's lightness curve and checks
+ * every guarded role pair in light and dark. Deterministic: the same options
+ * give the same bytes.
+ *
+ * @throws {TypeError} when `brand` is missing, a colour is not a hex value, `neutralChroma` is not a number from 0 to 0.1 or is given without `neutral`, or `darkPrimary` is not `'brand'` or `'mirror'`.
+ */
+export function createTheme(options: CreateThemeOptions): CreateThemeResult;
+export default createTheme;
+
+/** The steps of a chromatic ramp: 50, 100 … 900, 950. */
+export const RAMP_STEPS: number[];
+/** The 21 steps of the neutral ramp, half steps included. */
+export const BASE_STEPS: number[];