@d0nj/dsh-ui-custom 0.0.0-stage → 0.1.0

package/dist/resolve.js

@@ -0,0 +1,149 @@
+/**
+ * Resolving a customization document into theme tokens.
+ *
+ * Three inputs combine, in this order:
+ *
+ * 1. A **preset**, which is a complete token set.
+ * 2. **Per-token overrides**, applied on top of the preset.
+ * 3. **Geometry**, expanded into whichever tokens it can express.
+ *
+ * The result is one `ThemeTokenOverrides` object — token name to `{light, dark}` —
+ * which is exactly what `ctx.theme.overrideTokens` accepts. Keeping the merge
+ * here, as a pure function, is what lets the panel preview a change and the Host
+ * validate one from the same code.
+ *
+ * @module @d0nj/dsh-ui-custom/resolve
+ */
+import { DENSITIES, FONT_SIZE_RANGES, RADIUS_MAX, RADIUS_MIN, TOKEN_NAMES, findPreset, tokenSpec, } from './spec.js';
+/** A colour in one of the forms the theme service and browsers accept. */
+const COLOR_PATTERN = /^(#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})|(?:rgb|hsl|oklch|lab|lch|color)\([^)]*\)|[a-z]+)$/iu;
+/**
+ * Whether a value is a plausible CSS colour.
+ *
+ * Colour tokens are rendered straight into CSS custom properties, so an
+ * arbitrary string would not be a security hole but would silently produce an
+ * unstyled surface. Rejecting it here turns that into a visible warning.
+ * @param value - candidate colour value.
+ * @returns true when the value looks like a CSS colour.
+ */
+export function isColor(value) {
+    return COLOR_PATTERN.test(value.trim());
+}
+/**
+ * Clamp a number into a closed range.
+ * @param value - candidate value.
+ * @param min - lower bound.
+ * @param max - upper bound.
+ * @returns the clamped integer.
+ */
+export function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, Math.round(value)));
+}
+/**
+ * Expand geometry into token values.
+ *
+ * The documented token set has no radius or spacing tokens, so geometry is
+ * expressed as a *shadow layer* of `--d0nj-*` variables the panel's own styles
+ * consume, plus any `--dsw-*` tokens that exist. Emitting our own names keeps
+ * this additive: a token the harness does not define cannot break a surface,
+ * and the panel styles read ours.
+ *
+ * @param geometry - the requested geometry.
+ * @returns derived custom properties with identical light and dark values.
+ */
+export function geometryTokens(geometry) {
+    const radius = clamp(geometry.radius, RADIUS_MIN, RADIUS_MAX);
+    const scale = geometry.density === 'compact' ? 0.8 : geometry.density === 'spacious' ? 1.25 : 1;
+    const value = (px) => ({ light: px, dark: px });
+    return {
+        '--d0nj-radius-sm': value(`${String(Math.round(radius * 0.5))}px`),
+        '--d0nj-radius-md': value(`${String(radius)}px`),
+        '--d0nj-radius-lg': value(`${String(Math.round(radius * 1.5))}px`),
+        '--d0nj-space-1': value(`${String(Math.round(4 * scale))}px`),
+        '--d0nj-space-2': value(`${String(Math.round(8 * scale))}px`),
+        '--d0nj-space-3': value(`${String(Math.round(12 * scale))}px`),
+        '--d0nj-space-4': value(`${String(Math.round(16 * scale))}px`),
+    };
+}
+/**
+ * Correct one role's font size into its accepted range.
+ * @param role - font role.
+ * @param px - requested size.
+ * @returns the in-range size.
+ */
+export function correctFontSize(role, px) {
+    const range = FONT_SIZE_RANGES[role];
+    return clamp(px, range.min, range.max);
+}
+/**
+ * Whether a string names a known density.
+ * @param value - candidate density.
+ * @returns true for a known density.
+ */
+export function isDensity(value) {
+    return DENSITIES.includes(value);
+}
+/**
+ * Resolve a customization document into theme tokens and typography.
+ *
+ * Merge order is preset, then explicit overrides, then geometry, so a user who
+ * picks a preset and then tweaks one token keeps the tweak, and geometry always
+ * wins over a token of the same name (it is the more specific control).
+ *
+ * @param document - the customization document.
+ * @returns the token overrides, corrected typography, and any warnings.
+ */
+export function resolveCustomization(document) {
+    const warnings = [];
+    const tokens = {};
+    if (document.basePreset !== 'none') {
+        const preset = findPreset(document.basePreset);
+        if (preset === undefined) {
+            warnings.push(`unknown preset "${document.basePreset}"; no base tokens applied`);
+        }
+        else {
+            for (const [name, modes] of Object.entries(preset.tokens))
+                tokens[name] = modes;
+        }
+    }
+    for (const [name, modes] of Object.entries(document.tokens)) {
+        const spec = tokenSpec(name);
+        if (spec === undefined) {
+            // A hand-edited document can name a token this build does not document.
+            // Skipping it with a warning beats applying a property nothing reads.
+            warnings.push(`ignoring undocumented token "${name}"`);
+            continue;
+        }
+        const light = modes.light.trim();
+        const dark = modes.dark.trim();
+        if (light.length === 0 || dark.length === 0) {
+            warnings.push(`token "${name}" needs both a light and a dark value`);
+            continue;
+        }
+        if (spec.kind === 'color' && (!isColor(light) || !isColor(dark))) {
+            warnings.push(`token "${name}" is not a valid CSS colour`);
+            continue;
+        }
+        tokens[name] = { light, dark };
+    }
+    for (const [name, modes] of Object.entries(geometryTokens(document.geometry))) {
+        tokens[name] = modes;
+    }
+    const typography = {
+        textFontFamily: document.typography.textFontFamily,
+        codeFontFamily: document.typography.codeFontFamily,
+        terminalFontFamily: document.typography.terminalFontFamily,
+        fontSize: correctFontSize('text', document.typography.fontSize),
+        codeFontSize: correctFontSize('code', document.typography.codeFontSize),
+        terminalFontSize: correctFontSize('terminal', document.typography.terminalFontSize),
+    };
+    if (typography.fontSize !== document.typography.fontSize) {
+        warnings.push(`text font size corrected to ${String(typography.fontSize)}px (allowed ${String(FONT_SIZE_RANGES.text.min)}–${String(FONT_SIZE_RANGES.text.max)})`);
+    }
+    return { tokens, typography, warnings };
+}
+/** Every documented token name, re-exported for the panel's reset action. */
+export { TOKEN_NAMES };
+//# sourceMappingURL=resolve.js.map

package/dist/spec.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The token catalog and the shipped presets.
+ *
+ * Every override must supply **both** palette modes. The theme runtime requires
+ * it (`ThemeTokenModes`), because a token defined for only one scheme goes
+ * illegible when the user flips to the other — so this module represents that
+ * requirement in the type rather than trusting each caller to remember it.
+ *
+ * @module @d0nj/dsh-ui-custom/spec
+ */
+/** One token's value in each palette mode. */
+export interface TokenModes {
+    readonly light: string;
+    readonly dark: string;
+}
+/** Whether a token is a colour (validated as a colour) or an arbitrary CSS value. */
+export type TokenKind = 'color' | 'length' | 'shadow' | 'font';
+/** One documented token the editor can change. */
+export interface TokenSpec {
+    /** CSS custom property name, such as `--dsw-alias-bg-base`. */
+    readonly name: string;
+    /** Short human label for the editor row. */
+    readonly label: string;
+    /** Grouping in the editor. */
+    readonly group: TokenGroup;
+    /** How the value is validated and rendered. */
+    readonly kind: TokenKind;
+    /** What the token affects, shown as the row hint. */
+    readonly description: string;
+}
+/** Editor grouping, ordered as the panel renders them. */
+export type TokenGroup = 'surface' | 'border' | 'text' | 'accent' | 'state';
+/** Groups in display order, with their headings. */
+export declare const TOKEN_GROUPS: readonly {
+    readonly id: TokenGroup;
+    readonly label: string;
+}[];
+/**
+ * The documented alias tokens.
+ *
+ * These are the tokens the theme Inspect provider reports for this build, so the
+ * editor never offers a row that would silently do nothing.
+ */
+export declare const TOKEN_SPECS: readonly TokenSpec[];
+/** Every documented token name, for validation. */
+export declare const TOKEN_NAMES: readonly string[];
+/**
+ * Look up one token's specification.
+ * @param name - CSS custom property name.
+ * @returns the specification, or `undefined` when the token is not documented.
+ */
+export declare function tokenSpec(name: string): TokenSpec | undefined;
+/** One shipped preset: a complete, legible theme in both modes. */
+export interface ThemePreset {
+    /** Stable id, used as the `basePreset` config value. */
+    readonly id: string;
+    /** Display name. */
+    readonly label: string;
+    /** One-line description shown on the preset card. */
+    readonly description: string;
+    /** The base palette this preset reads as. */
+    readonly colorScheme: 'light' | 'dark';
+    /** Complete token set — every documented token, in both modes. */
+    readonly tokens: Readonly<Record<string, TokenModes>>;
+}
+/**
+ * Shipped presets.
+ *
+ * Each is a complete token set rather than a partial overlay, so selecting one
+ * gives a predictable result no matter what the generated base palette does.
+ * The colours are chosen to keep body text at or above WCAG AA contrast against
+ * their own surfaces, which the tests check.
+ */
+export declare const PRESETS: readonly ThemePreset[];
+/** Every preset id, for validation. */
+export declare const PRESET_IDS: readonly string[];
+/**
+ * Look up one preset by id.
+ * @param id - preset id.
+ * @returns the preset, or `undefined` for an unknown or `none` id.
+ */
+export declare function findPreset(id: string): ThemePreset | undefined;
+/** The role names the theme runtime accepts for typography. */
+export declare const FONT_ROLES: readonly ["text", "code", "terminal"];
+/** One font role. */
+export type FontRole = (typeof FONT_ROLES)[number];
+/** Accepted font-size range per role, mirroring the shipped Appearance rows. */
+export declare const FONT_SIZE_RANGES: Readonly<Record<FontRole, {
+    readonly min: number;
+    readonly max: number;
+    readonly fallback: number;
+}>>;
+/** Density presets, expressed as a spacing multiplier applied to derived tokens. */
+export declare const DENSITIES: readonly ["compact", "comfortable", "spacious"];
+/** One density option. */
+export type Density = (typeof DENSITIES)[number];
+/** Radius bounds in pixels. */
+export declare const RADIUS_MIN = 0;
+/** Upper radius bound in pixels. */
+export declare const RADIUS_MAX = 24;
+//# sourceMappingURL=spec.d.ts.map