@dreamtree-org/twreact-ui 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamtree-org/twreact-ui",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A comprehensive React + Tailwind components library for building modern web apps",
   "author": {
     "name": "Partha Preetham Krishna",
@@ -21,14 +21,20 @@
     "mcp/catalog-core.mjs",
     "mcp/catalog-snapshot.mjs",
     "mcp/catalog.snapshot.json",
+    "tokens/tokens.json",
+    "tokens/lib.cjs",
+    "tokens/brands",
+    "DESIGN.md",
     "ai-skills",
     "doc/assets/upi-qr.png",
     "package.json",
     "README.md"
   ],
   "scripts": {
-    "build": "npm run build:types && npm run build:js && npm run gen:ai-schema",
-    "build:types": "tsc --project tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build": "npm run build:types && npm run build:tokens && npm run build:js && node scripts/gen-typed-dts.mjs && npm run gen:ai-schema",
+    "build:types": "tsc --project tsconfig.build.json --emitDeclarationOnly --outDir dist && node scripts/gen-typed-dts.mjs",
+    "build:tokens": "node scripts/build-tokens.mjs",
+    "tokens:check": "node scripts/build-tokens.mjs --check",
     "build:js": "node scripts/version-bump.js && cross-env NODE_ENV=production rollup -c --no-sourcemap",
     "gen:ai-schema": "node scripts/gen-ai-schema.mjs",
     "dev": "cross-env NODE_ENV=development rollup -c -w",
@@ -93,8 +99,8 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react": "^18.3.1 || ^19.0.0",
+    "react-dom": "^18.3.1 || ^19.0.0"
   },
   "dependencies": {
     "@hookform/resolvers": "^3.10.0",

package/tokens/brands/default.json

@@ -0,0 +1,5 @@
+{
+  "name": "default",
+  "label": "Dreamtree default",
+  "$description": "No overrides: the shared tokens as shipped (Tailwind blue primary, slate shell)."
+}

package/tokens/brands/practicepro.json

@@ -0,0 +1,27 @@
+{
+  "name": "practicepro",
+  "label": "PracticePro",
+  "$description": "Teal primary and navy shell, taken from PracticePro/app/globals.css (brand-50/100/500/600/700, shell, shell-active). Steps PracticePro does not define are interpolated on the same hue. PracticePro's own muted grey (#64748b) is not carried over: on the #f6f8fb background it is about 4.4:1, below WCAG AA, so the shared muted token (#475569, 7.5:1) is used.",
+  "color": {
+    "primary": {
+      "50": "#ecfbf8",
+      "100": "#d1f3ee",
+      "200": "#a6e6dc",
+      "300": "#6fd1c4",
+      "400": "#34b3a6",
+      "500": "#0f8a8a",
+      "600": "#0d7377",
+      "700": "#0b5d60",
+      "800": "#0b4a4d",
+      "900": "#0a3d40",
+      "950": "#052426"
+    }
+  },
+  "role": {
+    "background": "#f6f8fb",
+    "foreground": "#0f172a",
+    "line": "#e2e8f0",
+    "shell": "#0f2b3d",
+    "shell-active": "#13606a"
+  }
+}

package/tokens/lib.cjs

@@ -0,0 +1,128 @@
+// Shared token helpers for tailwind.config.js (CJS) and scripts/build-tokens.mjs (ESM).
+// tokens.json is the W3C DTCG source of truth; this file only reads and reshapes it.
+const fs = require('fs');
+const path = require('path');
+
+const TOKENS_PATH = path.join(__dirname, 'tokens.json');
+const BRANDS_DIR = path.join(__dirname, 'brands');
+const DARK_KEY = 'org.dreamtree.dark';
+const SCALE_STEPS = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'];
+
+function loadTokens() {
+  return JSON.parse(fs.readFileSync(TOKENS_PATH, 'utf8'));
+}
+
+function listBrands() {
+  if (!fs.existsSync(BRANDS_DIR)) return [];
+  return fs.readdirSync(BRANDS_DIR).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort();
+}
+
+function loadBrand(name) {
+  const file = path.join(BRANDS_DIR, `${name}.json`);
+  if (!fs.existsSync(file)) {
+    throw new Error(`Unknown brand "${name}". Available brands: ${listBrands().join(', ') || '(none)'}. Add tokens/brands/${name}.json to create one.`);
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function hexToChannels(hex) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(hex).trim());
+  if (!m) throw new Error(`Token value "${hex}" is not a hex colour (#rgb or #rrggbb).`);
+  let h = m[1];
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  const n = parseInt(h, 16);
+  return `${(n >> 16) & 255} ${(n >> 8) & 255} ${n & 255}`;
+}
+
+/** Palette scales (primary, secondary, …) as { name: { step: hex } }. */
+function scales(tokens) {
+  const out = {};
+  for (const [name, group] of Object.entries(tokens.color)) {
+    if (name.startsWith('$')) continue;
+    out[name] = {};
+    for (const step of SCALE_STEPS) {
+      if (!group[step]) throw new Error(`color.${name} is missing step ${step}.`);
+      out[name][step] = group[step].$value;
+    }
+  }
+  return out;
+}
+
+/** Semantic roles as { name: { light, dark, description } }. */
+function roles(tokens) {
+  const out = {};
+  for (const [name, t] of Object.entries(tokens.role)) {
+    if (name.startsWith('$')) continue;
+    out[name] = { light: t.$value, dark: (t.$extensions && t.$extensions[DARK_KEY]) || t.$value, description: t.$description || '' };
+  }
+  return out;
+}
+
+/** 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;
+  const next = JSON.parse(JSON.stringify(tokens));
+  for (const [scale, steps] of Object.entries(brand.color || {})) {
+    if (!next.color[scale]) throw new Error(`Brand "${brand.name}" sets unknown colour scale "${scale}". Known: ${Object.keys(scales(tokens)).join(', ')}.`);
+    for (const [step, hex] of Object.entries(steps)) {
+      if (!SCALE_STEPS.includes(step)) throw new Error(`Brand "${brand.name}" sets ${scale}.${step}; steps are ${SCALE_STEPS.join(', ')}.`);
+      next.color[scale][step] = { $value: hex };
+    }
+  }
+  for (const [name, value] of Object.entries(brand.role || {})) {
+    if (!next.role[name]) throw new Error(`Brand "${brand.name}" 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.
+    const current = next.role[name];
+    const light = typeof value === 'string' ? value : value.light || current.$value;
+    const dark = typeof value === 'string' ? roles({ role: { [name]: current } })[name].dark : value.dark || roles({ role: { [name]: current } })[name].dark;
+    next.role[name] = { ...current, $value: light, $extensions: { [DARK_KEY]: dark } };
+  }
+  if (brand.font && brand.font.sans) next.font.family.sans = { $value: brand.font.sans };
+  return next;
+}
+
+const varName = (name, step) => (step ? `--dt-${name}-${step}` : `--dt-${name}`);
+const colorRef = (name, step) => `rgb(var(${varName(name, step)}) / <alpha-value>)`;
+
+/** Tailwind 3 `colors` object whose values point at the --dt-* variables. */
+function tailwindColors(tokens) {
+  const out = {};
+  for (const name of Object.keys(scales(tokens))) {
+    out[name] = Object.fromEntries(SCALE_STEPS.map((s) => [s, colorRef(name, s)]));
+  }
+  for (const name of Object.keys(roles(tokens))) out[name] = colorRef(name);
+  return out;
+}
+
+/** CSS declarations for :root (light) and the dark selectors, as { light: {var: channels}, dark: {...} }. */
+function cssVariables(tokens, { includeScales = true } = {}) {
+  const light = {};
+  const dark = {};
+  if (includeScales) {
+    for (const [name, steps] of Object.entries(scales(tokens))) {
+      for (const [step, hex] of Object.entries(steps)) light[varName(name, step)] = hexToChannels(hex);
+    }
+  }
+  for (const [name, r] of Object.entries(roles(tokens))) {
+    light[varName(name)] = hexToChannels(r.light);
+    dark[varName(name)] = hexToChannels(r.dark);
+  }
+  return { light, dark };
+}
+
+const DARK_SELECTOR = '.dark, [data-theme="dark"]';
+
+module.exports = {
+  SCALE_STEPS,
+  DARK_SELECTOR,
+  loadTokens,
+  loadBrand,
+  listBrands,
+  applyBrand,
+  hexToChannels,
+  scales,
+  roles,
+  tailwindColors,
+  cssVariables,
+  varName,
+};

package/tokens/tokens.json

@@ -0,0 +1,133 @@
+{
+  "$description": "Dreamtree design tokens (W3C Design Tokens Community Group format, 2025.10). Source of truth for twreact-ui's CSS variables, the Tailwind 3 preset, the Tailwind 4 theme and DESIGN.md. Products override only a brand file in tokens/brands/. Dark values live in $extensions[\"org.dreamtree.dark\"].",
+  "color": {
+    "$type": "color",
+    "primary": {
+      "$description": "The one accent: primary actions, active navigation, current step, progress, links and the focus ring. Default is Tailwind blue, which twreact-ui has always shipped.",
+      "50": { "$value": "#eff6ff" },
+      "100": { "$value": "#dbeafe" },
+      "200": { "$value": "#bfdbfe" },
+      "300": { "$value": "#93c5fd" },
+      "400": { "$value": "#60a5fa" },
+      "500": { "$value": "#3b82f6" },
+      "600": { "$value": "#2563eb" },
+      "700": { "$value": "#1d4ed8" },
+      "800": { "$value": "#1e40af" },
+      "900": { "$value": "#1e3a8a" },
+      "950": { "$value": "#172554" }
+    },
+    "secondary": {
+      "$description": "Neutral slate for secondary buttons, muted text and the default app shell.",
+      "50": { "$value": "#f8fafc" },
+      "100": { "$value": "#f1f5f9" },
+      "200": { "$value": "#e2e8f0" },
+      "300": { "$value": "#cbd5e1" },
+      "400": { "$value": "#94a3b8" },
+      "500": { "$value": "#64748b" },
+      "600": { "$value": "#475569" },
+      "700": { "$value": "#334155" },
+      "800": { "$value": "#1e293b" },
+      "900": { "$value": "#0f172a" },
+      "950": { "$value": "#020617" }
+    },
+    "success": {
+      "$description": "Completed, filed, accepted, healthy. Badges use the 100 fill with 800 text.",
+      "50": { "$value": "#f0fdf4" },
+      "100": { "$value": "#dcfce7" },
+      "200": { "$value": "#bbf7d0" },
+      "300": { "$value": "#86efac" },
+      "400": { "$value": "#4ade80" },
+      "500": { "$value": "#22c55e" },
+      "600": { "$value": "#16a34a" },
+      "700": { "$value": "#15803d" },
+      "800": { "$value": "#166534" },
+      "900": { "$value": "#14532d" },
+      "950": { "$value": "#052e16" }
+    },
+    "warning": {
+      "$description": "Needs attention soon: at risk, pending, in review.",
+      "50": { "$value": "#fffbeb" },
+      "100": { "$value": "#fef3c7" },
+      "200": { "$value": "#fde68a" },
+      "300": { "$value": "#fcd34d" },
+      "400": { "$value": "#fbbf24" },
+      "500": { "$value": "#f59e0b" },
+      "600": { "$value": "#d97706" },
+      "700": { "$value": "#b45309" },
+      "800": { "$value": "#92400e" },
+      "900": { "$value": "#78350f" },
+      "950": { "$value": "#451a03" }
+    },
+    "error": {
+      "$description": "Errors, overdue and destructive actions only. Never decoration.",
+      "50": { "$value": "#fef2f2" },
+      "100": { "$value": "#fee2e2" },
+      "200": { "$value": "#fecaca" },
+      "300": { "$value": "#fca5a5" },
+      "400": { "$value": "#f87171" },
+      "500": { "$value": "#ef4444" },
+      "600": { "$value": "#dc2626" },
+      "700": { "$value": "#b91c1c" },
+      "800": { "$value": "#991b1b" },
+      "900": { "$value": "#7f1d1d" },
+      "950": { "$value": "#450a0a" }
+    },
+    "info": {
+      "$description": "Informational and scheduled states that are not the brand accent.",
+      "50": { "$value": "#f0f9ff" },
+      "100": { "$value": "#e0f2fe" },
+      "200": { "$value": "#bae6fd" },
+      "300": { "$value": "#7dd3fc" },
+      "400": { "$value": "#38bdf8" },
+      "500": { "$value": "#0ea5e9" },
+      "600": { "$value": "#0284c7" },
+      "700": { "$value": "#0369a1" },
+      "800": { "$value": "#075985" },
+      "900": { "$value": "#0c4a6e" },
+      "950": { "$value": "#082f49" }
+    },
+    "gray": {
+      "$description": "Borders, dividers and quiet fills. Matches Tailwind gray so existing twreact-ui classes keep their look.",
+      "50": { "$value": "#f9fafb" },
+      "100": { "$value": "#f3f4f6" },
+      "200": { "$value": "#e5e7eb" },
+      "300": { "$value": "#d1d5db" },
+      "400": { "$value": "#9ca3af" },
+      "500": { "$value": "#6b7280" },
+      "600": { "$value": "#4b5563" },
+      "700": { "$value": "#374151" },
+      "800": { "$value": "#1f2937" },
+      "900": { "$value": "#111827" },
+      "950": { "$value": "#030712" }
+    }
+  },
+  "role": {
+    "$type": "color",
+    "$description": "Semantic surface and text roles. Screens use these (bg-surface, text-foreground, border-line) instead of picking palette steps.",
+    "background": { "$value": "#f8fafc", "$description": "Page background.", "$extensions": { "org.dreamtree.dark": "#0b1120" } },
+    "surface": { "$value": "#ffffff", "$description": "Cards, dialogs, menus.", "$extensions": { "org.dreamtree.dark": "#111827" } },
+    "foreground": { "$value": "#0f172a", "$description": "Body text and titles.", "$extensions": { "org.dreamtree.dark": "#e5e7eb" } },
+    "muted": { "$value": "#475569", "$description": "Subtitles, labels, captions (7.5:1 on white).", "$extensions": { "org.dreamtree.dark": "#94a3b8" } },
+    "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" } }
+  },
+  "font": {
+    "family": {
+      "$type": "fontFamily",
+      "sans": { "$value": ["Inter", "system-ui", "-apple-system", "Segoe UI", "Roboto", "Arial", "sans-serif"] },
+      "mono": { "$value": ["JetBrains Mono", "ui-monospace", "SFMono-Regular", "Menlo", "monospace"] }
+    },
+    "size": {
+      "$type": "dimension",
+      "$description": "Type scale. micro replaces the 1,445 hand-written text-[10px]/text-[11px] found across products.",
+      "micro": { "$value": { "value": 0.6875, "unit": "rem" }, "$extensions": { "org.dreamtree.lineHeight": "1rem" } }
+    }
+  },
+  "radius": {
+    "$type": "dimension",
+    "control": { "$value": { "value": 0.5, "unit": "rem" }, "$description": "Buttons, inputs, menus." },
+    "card": { "$value": { "value": 0.75, "unit": "rem" }, "$description": "Cards and dialogs." }
+  }
+}