@ghostmind-dev/colors 0.1.0 → 0.2.0

package/README.md

@@ -19,8 +19,8 @@ An app can carry the system without offering themes.
 import { createColors, switchValue } from '@ghostmind-dev/colors/app';
 
 const colors = createColors({
-  themes: switchValue(process.env.COLOR_THEMES), // off unless "on", "true" or "1"
-  own: 'dark',                                   // a built-in id, or a ThemeDefinition of your own
+  themes: switchValue(process.env.COLOR_THEMES), // off unless "on", "true" or "1"; or a list: ['light', 'moss']
+  own: 'dark',                                   // a built-in id, a built-in with overrides, or a ThemeDefinition
 });
 
 colors.css();        // the stylesheet for <head>
@@ -37,7 +37,21 @@ colors.apply(saved); // switch the live document; always the app's own theme whe
 
 Turning it on changes no component: they name roles either way.
 
-`own` can be a full `ThemeDefinition` written for one app. Its colours need not come from any built-in theme, but it passes the same validation, and a bad one throws when the app starts.
+### The app's own version
+
+`own` takes three forms:
+
+```ts
+own: 'dark'                                     // a built-in, as it is
+own: { extends: 'dark', name: 'Potion',         // a built-in with only what differs
+       palette: { brand: { '500': '#7c5cff' } },
+       chips: { tint: 0.2 } }
+own: myThemeDefinition                          // a full ThemeDefinition, colours of its own
+```
+
+The second form is plain data, so every platform can read the same object. Palette steps replace the base's one by one; `chips`, `code` and `lists` replace field by field. Only steps and fields the base already has can be set, and the base's contrast floor is not carried over. With the switch on, the override applies to the app's own theme only: the built-ins stay the same in every app.
+
+Every form is validated, the override is also held to the contrast gate, and a bad one throws when the app starts. `extendTheme(override)` in `./create` does the same without throwing, for an editor: `{ ok, problems, theme, score, lowest, failures }`.
 
 ## Tailwind
 
@@ -76,7 +90,7 @@ The whole palette is derived from the base and three numbers, then validated and
 | `./app` | `createColors`, `switchValue`, `OWN_THEME` |
 | `./engine` | `ThemeDefinition`, `validateThemeDefinition`, `deriveTheme`, chips |
 | `./contrast` | `scoreTheme`, `contrastOf` |
-| `./create` | `createTheme`, `validateThemeInput` |
+| `./create` | `createTheme`, `validateThemeInput`, `extendTheme`, `ThemeOverride` |
 | `./tailwind` | `themeRoles`, `semantic`, `role`, `alpha` |
 | `./native` | `platformColors`, `semanticColors` |
 | `./tokens.json` | the tokens as data |

package/dist/app.d.ts

@@ -3,8 +3,8 @@
  *
  * Off (the default), the app has ONE look: its own theme, painted on `:root`. No choice is read
  * from storage, there is nothing to pick, and the stylesheet holds one rule instead of one per
- * theme. The app's own theme is either a built-in id or a full ThemeDefinition written for that
- * app, so its colours need not come from any theme of ours.
+ * theme. The app's own theme is a built-in id, a built-in with only what differs, or a full
+ * ThemeDefinition written for that app, so its colours need not come from any theme of ours.
  *
  * On, every built-in theme is offered beside the app's own, and the saved choice is honoured.
  *
@@ -13,13 +13,20 @@
  */
 import { type ThemeId } from './index.js';
 import { type Scheme, type ThemeDefinition } from './engine.js';
+import { type ThemeOverride } from './create.js';
 /** The id an app's own ThemeDefinition is registered under. */
 export declare const OWN_THEME: ThemeId;
 export interface ColorsOptions {
-    /** The multi-theme switch. Off unless this is exactly `true`. */
-    themes?: boolean;
-    /** The app's own look: a built-in theme id, or a ThemeDefinition of its own. Default `dark`. */
-    own?: ThemeId | ThemeDefinition;
+    /**
+     * The multi-theme switch. Off unless `true` (every built-in) or a list of built-in ids (only those).
+     * The app's own theme is always offered as well.
+     */
+    themes?: boolean | ThemeId[];
+    /**
+     * The app's own look: a built-in theme id, a built-in with only what differs (`{ extends, … }`),
+     * or a ThemeDefinition of its own. Default `dark`.
+     */
+    own?: ThemeId | ThemeOverride | ThemeDefinition;
 }
 export interface ThemeEntry {
     id: ThemeId;

package/dist/app.js

@@ -3,8 +3,8 @@
  *
  * Off (the default), the app has ONE look: its own theme, painted on `:root`. No choice is read
  * from storage, there is nothing to pick, and the stylesheet holds one rule instead of one per
- * theme. The app's own theme is either a built-in id or a full ThemeDefinition written for that
- * app, so its colours need not come from any theme of ours.
+ * theme. The app's own theme is a built-in id, a built-in with only what differs, or a full
+ * ThemeDefinition written for that app, so its colours need not come from any theme of ours.
  *
  * On, every built-in theme is offered beside the app's own, and the saved choice is honoured.
  *
@@ -13,6 +13,7 @@
  */
 import { THEMES, THEME_STORAGE_KEY, applyTheme, clearThemeCache, isThemeId, requiredPalette, schemeOf, themeCss, themeRule, } from './index.js';
 import { validateThemeDefinition } from './engine.js';
+import { extendTheme, isThemeOverride } from './create.js';
 /** The id an app's own ThemeDefinition is registered under. */
 export const OWN_THEME = 'own';
 /** `true`, `"true"`, `"on"` and `"1"` turn the switch on; anything else leaves it off. */
@@ -20,20 +21,29 @@ export function switchValue(value) {
     return value === true || value === 'true' || value === 'on' || value === '1';
 }
 export function createColors(options = {}) {
-    const enabled = options.themes === true;
+    const offered = offeredThemes(options.themes);
+    const enabled = offered.length > 0;
     const own = registerOwn(options.own ?? 'dark');
-    const resolve = (saved) => (enabled && isThemeId(saved) ? saved : own);
+    // The ids this app shows: its own first when it is not a built-in, then the ones it offers.
+    const ids = enabled ? [...new Set([...(isBuiltIn(own) ? [] : [own]), ...offered, own])] : [own];
+    const subset = enabled && offered.length < builtIns().length;
+    const resolve = (saved) => (enabled && typeof saved === 'string' && ids.includes(saved) ? saved : own);
     return {
         enabled,
         own,
-        list: () => (enabled ? Object.keys(THEMES) : [own]).map(id => ({ id, name: THEMES[id].name, scheme: schemeOf(id) })),
+        list: () => (enabled && !subset ? Object.keys(THEMES) : ids).map(id => ({ id, name: THEMES[id].name, scheme: schemeOf(id) })),
         resolve,
         // On: every theme by its id, and the app's own on a bare `:root` so the server-rendered page
         // is right before any script runs. Off: the one rule.
-        css: () => (enabled ? `${themeCss()}\n${themeRule(own, ':root:not([data-theme])')}` : themeRule(own, ':root')),
+        css: () => {
+            if (!enabled)
+                return themeRule(own, ':root');
+            const rules = subset ? ids.map(id => themeRule(id, `:root[data-theme="${id}"]`)).join('\n') : themeCss();
+            return `${rules}\n${themeRule(own, ':root:not([data-theme])')}`;
+        },
         prepaint: () => {
             const set = (id) => `var d=document.documentElement;d.dataset.theme=${id};d.classList.toggle('dark',s[${id}]==='dark')`;
-            const schemes = Object.fromEntries((enabled ? Object.keys(THEMES) : [own]).map(id => [id, schemeOf(id)]));
+            const schemes = Object.fromEntries((enabled && !subset ? Object.keys(THEMES) : ids).map(id => [id, schemeOf(id)]));
             const fallback = JSON.stringify(own);
             const pick = enabled
                 ? `var t=localStorage.getItem(${JSON.stringify(THEME_STORAGE_KEY)});if(!s.hasOwnProperty(t))t=${fallback};`
@@ -48,6 +58,19 @@ export function createColors(options = {}) {
         },
     };
 }
+const builtIns = () => Object.keys(THEMES).filter(isBuiltIn);
+const isBuiltIn = (id) => id !== OWN_THEME && !id.startsWith('_');
+/** The built-ins an app offers: all for `true`, the listed ones for a list (an unknown id stops the app), none otherwise. */
+function offeredThemes(themes) {
+    if (themes === true)
+        return builtIns();
+    if (!Array.isArray(themes))
+        return [];
+    const unknown = themes.filter(id => !isBuiltIn(id) || !THEMES[id]);
+    if (unknown.length)
+        throw new Error(`colors: no built-in theme named ${unknown.map(id => `"${id}"`).join(', ')}`);
+    return [...new Set(themes)];
+}
 /** An id is checked; a definition is validated and registered as `own`. A bad one stops the app. */
 function registerOwn(own) {
     if (typeof own === 'string') {
@@ -55,6 +78,17 @@ function registerOwn(own) {
             throw new Error(`colors: no theme named "${own}"`);
         return own;
     }
+    // An override is held to the contrast gate too: the colours it changes must stay readable.
+    if (isThemeOverride(own)) {
+        const result = extendTheme(own);
+        if (!result.theme || !result.ok) {
+            const reasons = result.problems.length
+                ? result.problems
+                : result.failures.map(f => `${f.fg} on ${f.bg} is ${f.ratio.toFixed(2)}, below ${f.floor}.`);
+            throw new Error(`colors: the app's own theme is not usable: ${reasons.join(' ')}`);
+        }
+        own = result.theme;
+    }
     const problems = validateThemeDefinition(own, requiredPalette(own?.scheme === 'light' ? 'light' : 'dark'));
     if (problems.length)
         throw new Error(`colors: the app's own theme is not usable: ${problems.join(' ')}`);

package/dist/create.d.ts

@@ -30,3 +30,39 @@ export declare function validateThemeInput(input: unknown): string[];
  * leaving it registered. `ok` only when there are no problems and no contrast failures.
  */
 export declare function createTheme(input: unknown): CreateResult;
+/**
+ * An app's own version: a built-in theme with only what differs. Plain data, so every platform
+ * (web, React Native, later Swift) can read the same object. Palette steps replace the base's one
+ * by one; chips, code and lists replace field by field. Only steps and fields the base already
+ * has can be set, so an app's own version still lines up with every other app.
+ */
+export interface ThemeOverride {
+    /** The built-in theme it starts from. Its scheme is the version's scheme. */
+    extends: string;
+    name?: string;
+    palette?: Record<string, Record<string, string>>;
+    chips?: Partial<ThemeDefinition['chips']>;
+    code?: Partial<ThemeDefinition['code']>;
+    lists?: Partial<ThemeDefinition['lists']>;
+}
+export interface ExtendResult {
+    ok: boolean;
+    problems: string[];
+    theme?: ThemeDefinition;
+    score?: number;
+    lowest?: number;
+    failures?: {
+        fg: string;
+        bg: string;
+        ratio: number;
+        floor: number;
+    }[];
+}
+/** True for a ThemeOverride's shape (it names what it extends), so `own` can take either form. */
+export declare function isThemeOverride(value: unknown): value is ThemeOverride;
+/**
+ * The override laid over its base, validated and scored like `createTheme`. `ok` only with no
+ * problems and no contrast failure. Never throws. The base's contrast floor is not carried over:
+ * changed colours are held to the normal floor.
+ */
+export declare function extendTheme(override: unknown): ExtendResult;

package/dist/create.js

@@ -85,3 +85,87 @@ export function createTheme(input) {
         clearThemeCache();
     }
 }
+const OVERRIDE_KEYS = ['extends', 'name', 'palette', 'chips', 'code', 'lists'];
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** True for a ThemeOverride's shape (it names what it extends), so `own` can take either form. */
+export function isThemeOverride(value) {
+    return isObject(value) && 'extends' in value;
+}
+/**
+ * The override laid over its base, validated and scored like `createTheme`. `ok` only with no
+ * problems and no contrast failure. Never throws. The base's contrast floor is not carried over:
+ * changed colours are held to the normal floor.
+ */
+export function extendTheme(override) {
+    if (!isObject(override))
+        return { ok: false, problems: ['The override must be an object.'] };
+    const problems = [];
+    for (const key of Object.keys(override))
+        if (!OVERRIDE_KEYS.includes(key))
+            problems.push(`unknown field ${key}`);
+    const baseId = override.extends;
+    const base = typeof baseId === 'string' && !baseId.startsWith('_') && baseId !== 'own' ? THEMES[baseId] : undefined;
+    if (!base)
+        return { ok: false, problems: [...problems, `extends must name a built-in theme (${Object.keys(THEMES).filter(id => id !== 'own' && !id.startsWith('_')).join(', ')}).`] };
+    const theme = structuredClone(base);
+    delete theme.contrast;
+    theme.derived = { extends: baseId };
+    if (override.name !== undefined) {
+        if (typeof override.name !== 'string' || !override.name.trim())
+            problems.push('name must be a non-empty string.');
+        else
+            theme.name = override.name.trim();
+    }
+    if (override.palette !== undefined) {
+        if (!isObject(override.palette))
+            problems.push('palette must be an object of ramps.');
+        else
+            for (const [ramp, steps] of Object.entries(override.palette)) {
+                if (!theme.palette[ramp]) {
+                    problems.push(`palette ${ramp} is not a ramp of ${baseId}.`);
+                    continue;
+                }
+                if (!isObject(steps)) {
+                    problems.push(`palette ${ramp} must be an object of steps.`);
+                    continue;
+                }
+                for (const [step, hex] of Object.entries(steps)) {
+                    if (theme.palette[ramp][step] === undefined)
+                        problems.push(`palette ${ramp}.${step} is not a step of ${baseId}.`);
+                    else
+                        theme.palette[ramp][step] = hex;
+                }
+            }
+    }
+    for (const part of ['chips', 'code', 'lists']) {
+        const patch = override[part];
+        if (patch === undefined)
+            continue;
+        if (!isObject(patch)) {
+            problems.push(`${part} must be an object.`);
+            continue;
+        }
+        const target = theme[part];
+        for (const [key, value] of Object.entries(patch)) {
+            if (!(key in target))
+                problems.push(`${part}.${key} is not a field of ${baseId}.`);
+            else
+                target[key] = value;
+        }
+    }
+    if (problems.length)
+        return { ok: false, problems };
+    const themeProblems = validateThemeDefinition(theme, requiredPalette(theme.scheme));
+    if (themeProblems.length)
+        return { ok: false, problems: themeProblems };
+    THEMES[CANDIDATE] = theme;
+    clearThemeCache();
+    try {
+        const scored = scoreTheme(CANDIDATE);
+        return { ok: scored.failures.length === 0, problems: [], theme, score: scored.score, lowest: scored.lowest?.ratio, failures: scored.failures };
+    }
+    finally {
+        delete THEMES[CANDIDATE];
+        clearThemeCache();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostmind-dev/colors",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One colour theme system for every app: themes as palettes, roles, a WCAG contrast gate, and a theme derived from three numbers",
   "license": "MIT",
   "type": "module",