@thewhileloop/whileui 4.2.1 → 4.3.0

package/dist/lib/theme-seeds.js

@@ -0,0 +1,143 @@
+// A full theme from a few seed colours, plus a contrast check for any palette.
+// Renderer-free: safe in build scripts and for agents generating themes.
+//
+// Seeds are never altered: a brand colour is a brand decision, so when it fails
+// contrast the check reports it instead. Only derived colours (muted text, the text on
+// each filled colour, status colours) are tuned to meet WCAG.
+import { blend, converter, formatHex, parse, wcagContrast } from 'culori';
+import { createThemePreset } from './theme-presets';
+const toOklch = converter('oklch');
+/** WCAG 2.x contrast ratio between two CSS colours, 1–21. */
+function contrastRatio(a, b) {
+    return wcagContrast(a, b);
+}
+function oklch(color) {
+    const parsed = parse(color);
+    if (!parsed)
+        throw new Error(`Not a CSS colour: "${color}"`);
+    return toOklch(parsed);
+}
+const hex = (l, c, h) => formatHex({ mode: 'oklch', l: Math.min(1, Math.max(0, l)), c, h });
+/** Mix `a` toward `b` by `t` in OKLCH lightness and chroma, keeping `a`'s hue. */
+function toward(a, b, t) {
+    const x = oklch(a);
+    const y = oklch(b);
+    return hex(x.l + (y.l - x.l) * t, (x.c ?? 0) + ((y.c ?? 0) - (x.c ?? 0)) * t, x.h ?? y.h ?? 0);
+}
+/** Move `color` away from `against` in lightness until it reaches `min` contrast. */
+function ensureContrast(color, against, min) {
+    const c = oklch(color);
+    const darker = oklch(against).l > 0.5;
+    for (let l = c.l; l >= 0 && l <= 1; l += darker ? -0.01 : 0.01) {
+        const candidate = hex(l, c.c ?? 0, c.h ?? 0);
+        if (contrastRatio(candidate, against) >= min)
+            return candidate;
+    }
+    return darker ? '#000000' : '#ffffff';
+}
+/** Black or white tinted toward the theme, whichever reads better on `fill`. */
+function onFill(fill, seeds) {
+    const light = oklch(seeds.background).l > oklch(seeds.foreground).l ? seeds.background : seeds.foreground;
+    const dark = light === seeds.background ? seeds.foreground : seeds.background;
+    return contrastRatio(light, fill) >= contrastRatio(dark, fill) ? light : dark;
+}
+// Status hues stay recognisable across brands; only their lightness adapts to the page.
+const STATUS_HUES = { destructive: 27, success: 150, warning: 75, info: 240 };
+/** The 25 base colours a theme needs, derived from its seeds. */
+function themeBaseFromSeeds(seeds) {
+    const { background, foreground, primary } = seeds;
+    const dark = oklch(background).l < 0.5;
+    const accent = seeds.accent ?? toward(primary, background, 0.82);
+    const surface = toward(background, foreground, dark ? 0.06 : 0.025);
+    const muted = toward(background, foreground, dark ? 0.1 : 0.06);
+    const status = (hue) => ensureContrast(hex(dark ? 0.72 : 0.55, 0.15, hue), background, 4.5);
+    const destructive = status(STATUS_HUES.destructive);
+    const success = status(STATUS_HUES.success);
+    const warning = status(STATUS_HUES.warning);
+    const info = status(STATUS_HUES.info);
+    const fills = { background, foreground };
+    return {
+        background,
+        foreground,
+        card: surface,
+        cardForeground: foreground,
+        popover: surface,
+        popoverForeground: foreground,
+        primary,
+        primaryForeground: onFill(primary, fills),
+        secondary: muted,
+        secondaryForeground: foreground,
+        accent,
+        accentForeground: onFill(accent, fills),
+        muted,
+        mutedForeground: ensureContrast(toward(foreground, background, 0.42), muted, 4.5),
+        border: toward(background, foreground, dark ? 0.16 : 0.13),
+        input: muted,
+        ring: primary,
+        destructive,
+        destructiveForeground: onFill(destructive, fills),
+        success,
+        successForeground: onFill(success, fills),
+        warning,
+        warningForeground: onFill(warning, fills),
+        info,
+        infoForeground: onFill(info, fills),
+    };
+}
+/**
+ * A complete preset from seeds. `light` is required; `dark` defaults to a dark page with
+ * the same brand colours. `overrides` replaces any base colour before the rest is
+ * derived, so nothing is out of reach; derived tokens can be adjusted on the result.
+ */
+export function themeFromSeeds(input) {
+    const { light } = input;
+    const page = oklch(light.background);
+    const darkPage = hex(0.17, Math.min(page.c ?? 0, 0.02), page.h ?? 0);
+    // Generated, not supplied, so brand colours may be lifted until they read on a dark page.
+    const dark = input.dark ?? {
+        background: darkPage,
+        foreground: hex(0.94, Math.min(page.c ?? 0, 0.015), page.h ?? 0),
+        primary: ensureContrast(light.primary, darkPage, 4.5),
+        accent: light.accent && ensureContrast(light.accent, darkPage, 3),
+    };
+    return createThemePreset({
+        name: input.name,
+        description: input.description,
+        light: { ...themeBaseFromSeeds(light), ...input.overrides?.light },
+        dark: { ...themeBaseFromSeeds(dark), ...input.overrides?.dark },
+        visual: input.visual,
+    });
+}
+const TEXT_PAIRS = [
+    ['foreground', 'background'],
+    ['cardForeground', 'card'],
+    ['popoverForeground', 'popover'],
+    ['mutedForeground', 'background'],
+    ['mutedForeground', 'muted'],
+    ['primaryForeground', 'primary'],
+    ['secondaryForeground', 'secondary'],
+    ['accentForeground', 'accent'],
+    ['destructiveForeground', 'destructive'],
+    ['successForeground', 'success'],
+    ['warningForeground', 'warning'],
+    ['infoForeground', 'info'],
+    ['primary', 'background'],
+    ['destructive', 'background'],
+];
+const UI_PAIRS = [['ring', 'background']];
+/** A translucent colour as it actually renders: blended onto the page. */
+function onPage(color, page) {
+    const parsed = parse(color);
+    if (!parsed || (parsed.alpha ?? 1) >= 1)
+        return color;
+    return formatHex(blend([page, parsed], 'normal'));
+}
+/** Every text and focus-ring pairing the components render, checked against WCAG AA. */
+export function checkThemeContrast(colors) {
+    const check = ([fg, bg], min) => {
+        const background = onPage(colors[bg], colors.background);
+        const ratio = Math.round(contrastRatio(onPage(colors[fg], background), background) * 100) / 100;
+        return { pair: `${fg} on ${bg}`, ratio, min, pass: ratio >= min };
+    };
+    return [...TEXT_PAIRS.map((p) => check(p, 4.5)), ...UI_PAIRS.map((p) => check(p, 3))];
+}

package/dist/lib/visual-tokens.js

@@ -28,11 +28,24 @@ function resolveVisualToken(spec, value) {
     }
     return parseRatio(value, spec.fallback, spec.min ?? 0, spec.max ?? 1);
 }
+// Resolved once per distinct CSS snapshot and shared, for the same reason as
+// `useThemeColors`: 83 parses per component per render add up on a list screen, and a
+// stable object lets callers memoise on it.
+const resolvedVisualTokens = new Map();
+const RESOLVED_VISUAL_LIMIT = 8;
 export function useVisualTokens() {
     const values = useCSSVariable(VISUAL_TOKEN_VARIABLES);
+    const key = values.join('\u0001');
+    const cached = resolvedVisualTokens.get(key);
+    if (cached)
+        return cached;
     const resolved = {};
     VISUAL_TOKEN_SPECS.forEach((spec, index) => {
         resolved[spec.key] = resolveVisualToken(spec, values[index]);
     });
+    if (resolvedVisualTokens.size >= RESOLVED_VISUAL_LIMIT) {
+        resolvedVisualTokens.delete(resolvedVisualTokens.keys().next().value);
+    }
+    resolvedVisualTokens.set(key, resolved);
     return resolved;
 }

package/dist/metro.cjs

@@ -4,14 +4,20 @@ const { withUniwindConfig } = require('uniwind/metro');
 
 /**
  * Packages that must resolve the real `react-native`. Uniwind's native resolver
- * rewrites every `from 'react-native'` to its component wrapper, which re-exports
- * components and nothing else, so a package importing a non-component export gets
- * `undefined` with no build error. `expo-asset` imports `AssetRegistry` that way, and
- * without it every `@expo/vector-icons` glyph is silently absent on iOS and Android.
+ * rewrites every `from 'react-native'` to its component wrapper. The wrapper re-exports
+ * the components and most of the API, but not all of it, and a missing export arrives
+ * as `undefined` with no build error. `expo-asset` imports `AssetRegistry`, which the
+ * wrapper lacks, and without it every `@expo/vector-icons` glyph is silently absent on
+ * iOS and Android.
  */
 const NEEDS_REAL_REACT_NATIVE = ['expo-asset', 'expo-font', '@expo/vector-icons'];
 
 function withWhileUIMetro(config, options) {
+  if (!options || typeof options.cssEntryFile !== 'string') {
+    throw new Error(
+      "withWhileUIMetro(config, options): pass Uniwind's options, at least { cssEntryFile: './global.css' }"
+    );
+  }
   const { exemptFromUniwindRewrite = [], ...uniwindOptions } = options;
   const wrapped = withUniwindConfig(config, uniwindOptions);
   const exempt = [...NEEDS_REAL_REACT_NATIVE, ...exemptFromUniwindRewrite];
@@ -19,7 +25,8 @@ function withWhileUIMetro(config, options) {
 
   wrapped.resolver.resolveRequest = (context, moduleName, platform) => {
     if (moduleName === 'react-native') {
-      const origin = context.originModulePath ?? '';
+      // Metro reports Windows paths with backslashes; match either separator.
+      const origin = (context.originModulePath ?? '').replace(/\\/g, '/');
       if (exempt.some((pkg) => origin.includes(`node_modules/${pkg}/`))) {
         return context.resolveRequest(context, moduleName, platform);
       }

package/dist/tokens.d.ts

@@ -2,3 +2,4 @@ export * from './lib/theme-contract';
 export * from './lib/visual-token-contract';
 export * from './lib/theme-presets';
 export * from './lib/theme-derive';
+export * from './lib/theme-seeds';

package/dist/tokens.js

@@ -4,3 +4,4 @@ export * from './lib/theme-contract';
 export * from './lib/visual-token-contract';
 export * from './lib/theme-presets';
 export * from './lib/theme-derive';
+export * from './lib/theme-seeds';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thewhileloop/whileui",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "WhileUI Native — Copy-paste components for React Native. You own the code.",
   "license": "MIT",
   "repository": {
@@ -52,6 +52,7 @@
       "types": "./dist/markdown.d.ts",
       "import": "./dist/markdown.js"
     },
+    "./agent/catalog.json": "./dist/agent/catalog.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -63,7 +64,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && cp src/metro.cjs src/metro.d.cts dist/",
+    "build": "tsc -p tsconfig.build.json && cp src/metro.cjs src/metro.d.cts dist/ && bun scripts/build-agent-docs.mjs",
     "prepack": "cp ../../README.md README.md",
     "postpack": "rm -f README.md",
     "prepare": "bun run build",