@dreamtree-org/twreact-ui 2.0.9 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamtree-org/twreact-ui",
-  "version": "2.0.9",
+  "version": "2.1.0",
   "description": "A comprehensive React + Tailwind components library for building modern web apps",
   "author": {
     "name": "Partha Preetham Krishna",

package/tokens/brand.schema.json

@@ -573,6 +573,28 @@
               }
             }
           ]
+        },
+        "primary-foreground": {
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "light": {
+                  "type": "string",
+                  "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
+                },
+                "dark": {
+                  "type": "string",
+                  "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
+                }
+              }
+            }
+          ]
         }
       }
     },

package/tokens/lib.cjs

@@ -122,6 +122,26 @@ function roles(tokens) {
   return out;
 }
 
+// WCAG relative luminance and contrast ratio of two hex colours.
+function luminance(hex) {
+  const [r, g, b] = hexToChannels(hex).split(' ').map((c) => {
+    const v = Number(c) / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+const contrast = (a, b) => {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+/** The colour for text on a primary fill: white or role.foreground, whichever contrasts more with primary-700. */
+function onPrimary(tokens) {
+  const fill = tokens.color.primary['700'].$value;
+  const dark = tokens.role.foreground.$value;
+  return contrast('#ffffff', fill) >= contrast(dark, fill) ? '#ffffff' : dark;
+}
+
 /** Merge a brand file over the tokens: brand.color.<scale>.<step> and brand.role.<name> (string or {light,dark}). */
 function applyBrand(tokens, brand) {
   if (!brand) return tokens;
@@ -133,6 +153,11 @@ function applyBrand(tokens, brand) {
       next.color[scale][step] = { $value: hex };
     }
   }
+  // #189: a light primary needs dark text on it; the brand can still set the role itself.
+  if (brand.color && brand.color.primary && next.role['primary-foreground']) {
+    const on = onPrimary(next);
+    next.role['primary-foreground'] = { ...next.role['primary-foreground'], $value: on, $extensions: { [DARK_KEY]: on } };
+  }
   for (const [name, value] of Object.entries(brand.role || {})) {
     if (!next.role[name]) throw new Error(`Brand "${brandId(brand)}" sets unknown role "${name}". Known: ${Object.keys(roles(tokens)).join(', ')}.`);
     // A plain string overrides light only; dark keeps the shared value unless {light, dark} is given.
@@ -278,6 +303,7 @@ module.exports = {
   brandCss,
   applyBrand,
   hexToChannels,
+  contrast,
   scales,
   roles,
   tailwindColors,

package/tokens/tokens.json

@@ -111,7 +111,8 @@
     "line": { "$value": "#e2e8f0", "$description": "Card and divider borders.", "$extensions": { "org.dreamtree.dark": "#1f2937" } },
     "shell": { "$value": "#0f172a", "$description": "App shell sidebar background.", "$extensions": { "org.dreamtree.dark": "#020617" } },
     "shell-foreground": { "$value": "#cbd5e1", "$description": "Sidebar text.", "$extensions": { "org.dreamtree.dark": "#cbd5e1" } },
-    "shell-active": { "$value": "#1e293b", "$description": "Active sidebar item fill.", "$extensions": { "org.dreamtree.dark": "#1e293b" } }
+    "shell-active": { "$value": "#1e293b", "$description": "Active sidebar item fill.", "$extensions": { "org.dreamtree.dark": "#1e293b" } },
+    "primary-foreground": { "$value": "#ffffff", "$description": "Text, icons, tiles (primary-foreground/12) and focus rings on a primary-600 to primary-900 fill, such as a brand band. A brand that changes color.primary gets white or role.foreground, whichever contrasts more with its primary-700.", "$extensions": { "org.dreamtree.dark": "#ffffff" } }
   },
   "font": {
     "family": {