@dreamtree-org/twreact-ui 1.3.1 → 1.3.3

package/tokens/lib.cjs

@@ -17,12 +17,76 @@ function listBrands() {
   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`);
+const isBrandPath = (s) => /[\\/]/.test(s) || s.endsWith('.json');
+
+/**
+ * Load a brand. A product keeps its brand in its own repo as dreamtree.brand.json and passes the path;
+ * a bare name reads the brands shipped here (only "default" is meant to stay).
+ */
+function loadBrand(nameOrPath) {
+  const file = isBrandPath(nameOrPath) ? path.resolve(nameOrPath) : path.join(BRANDS_DIR, `${nameOrPath}.json`);
   if (!fs.existsSync(file)) {
-    throw new Error(`Unknown brand "${name}". Available brands: ${listBrands().join(', ') || '(none)'}. Add tokens/brands/${name}.json to create one.`);
+    if (isBrandPath(nameOrPath)) throw new Error(`No brand file at ${file}. Create one with: npx @dreamtree-org/twreact-ui brand init`);
+    throw new Error(`Unknown brand "${nameOrPath}". A product's brand lives in its repo: pass the path to its dreamtree.brand.json. Shipped brands: ${listBrands().join(', ') || '(none)'}.`);
+  }
+  let brand;
+  try {
+    brand = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new Error(`${file} is not valid JSON (${err.message}).`);
   }
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  const errors = validateBrand(brand);
+  if (errors.length) throw new Error(`${file} is not a valid brand file:\n- ${errors.join('\n- ')}`);
+  return brand;
+}
+
+/** The brand's id (new files: "id"; the shipped files use "name"). */
+const brandId = (brand) => brand.id || brand.name;
+/** The brand's display name (new files: "name"; the shipped files use "label"). */
+const brandLabel = (brand) => (brand.id ? brand.name : brand.label) || brandId(brand);
+
+const HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const BRAND_KEYS = ['$schema', '$description', '$deprecated', 'id', 'name', 'label', 'logo', 'color', 'role', 'font', 'marketing'];
+
+/** Every problem with a brand file, each phrased as the fix. Empty when the file is valid. */
+function validateBrand(brand, tokens = loadTokens()) {
+  const errors = [];
+  if (!brand || typeof brand !== 'object' || Array.isArray(brand)) return ['The brand file must be a JSON object.'];
+  const id = brandId(brand);
+  if (typeof id !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(id)) errors.push('Set "id" to a lowercase slug, e.g. "practicepro".');
+  for (const key of Object.keys(brand)) if (!BRAND_KEYS.includes(key)) errors.push(`Remove "${key}": allowed keys are ${BRAND_KEYS.join(', ')}.`);
+  const knownScales = Object.keys(scales(tokens));
+  for (const [scale, steps] of Object.entries(brand.color || {})) {
+    if (!knownScales.includes(scale)) {
+      errors.push(`color.${scale} is not a scale. Use one of: ${knownScales.join(', ')}.`);
+      continue;
+    }
+    for (const [step, hex] of Object.entries(steps || {})) {
+      if (!SCALE_STEPS.includes(step)) errors.push(`color.${scale}.${step} is not a step. Steps are ${SCALE_STEPS.join(', ')}.`);
+      else if (typeof hex !== 'string' || !HEX_RE.test(hex)) errors.push(`color.${scale}.${step} must be a hex colour like "#0d7377", not ${JSON.stringify(hex)}.`);
+    }
+  }
+  const knownRoles = Object.keys(roles(tokens));
+  for (const [name, value] of Object.entries(brand.role || {})) {
+    if (!knownRoles.includes(name)) {
+      errors.push(`role.${name} is not a role. Use one of: ${knownRoles.join(', ')}.`);
+      continue;
+    }
+    const values = typeof value === 'string' ? [value] : value && typeof value === 'object' ? [value.light, value.dark].filter((v) => v !== undefined) : [value];
+    for (const v of values) if (typeof v !== 'string' || !HEX_RE.test(v)) errors.push(`role.${name} must be a hex colour or { "light": hex, "dark": hex }, not ${JSON.stringify(value)}.`);
+  }
+  if (brand.font !== undefined) {
+    const sans = brand.font && brand.font.sans;
+    if (!Array.isArray(sans) || !sans.length || !sans.every((f) => typeof f === 'string')) errors.push('font.sans must be a list of font families, e.g. ["Inter", "system-ui", "sans-serif"].');
+  }
+  for (const [key, v] of Object.entries(brand.marketing || {})) {
+    if (!['primary', 'accent', 'panel'].includes(key)) errors.push(`marketing.${key} is not used. Allowed: primary, accent, panel.`);
+    else if (typeof v !== 'string' || !HEX_RE.test(v)) errors.push(`marketing.${key} must be a hex colour.`);
+  }
+  for (const [key, v] of Object.entries(brand.logo || {})) {
+    if (typeof v !== 'string') errors.push(`logo.${key} must be a path or URL string.`);
+  }
+  return errors;
 }
 
 function hexToChannels(hex) {
@@ -63,14 +127,14 @@ 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(', ')}.`);
+    if (!next.color[scale]) throw new Error(`Brand "${brandId(brand)}" 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(', ')}.`);
+      if (!SCALE_STEPS.includes(step)) throw new Error(`Brand "${brandId(brand)}" 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(', ')}.`);
+    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.
     const current = next.role[name];
     const light = typeof value === 'string' ? value : value.light || current.$value;
@@ -81,6 +145,61 @@ function applyBrand(tokens, brand) {
   return next;
 }
 
+/** JSON Schema for dreamtree.brand.json, derived from the tokens (shipped as tokens/brand.schema.json). */
+function brandSchema(tokens = loadTokens()) {
+  const hex = { type: 'string', pattern: '^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$' };
+  const scale = { type: 'object', additionalProperties: false, properties: Object.fromEntries(SCALE_STEPS.map((s) => [s, hex])) };
+  const roleValue = { oneOf: [hex, { type: 'object', additionalProperties: false, properties: { light: hex, dark: hex } }] };
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://unpkg.com/@dreamtree-org/twreact-ui/tokens/brand.schema.json',
+    title: 'Dreamtree brand (dreamtree.brand.json)',
+    description: "A product's look, kept in the product's own repo. Build its CSS with `npx @dreamtree-org/twreact-ui brand build`.",
+    type: 'object',
+    additionalProperties: false,
+    required: ['id'],
+    properties: {
+      $schema: { type: 'string' },
+      $description: { type: 'string' },
+      $deprecated: { type: 'string' },
+      id: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$', description: 'Lowercase slug, e.g. "practicepro".' },
+      name: { type: 'string', description: 'Display name, e.g. "PracticePro".' },
+      label: { type: 'string', description: 'Legacy display name (brands shipped in twreact-ui).' },
+      logo: { type: 'object', additionalProperties: { type: 'string' }, description: 'Paths or URLs, e.g. { "mark": "public/brand/mark.svg" }.' },
+      color: { type: 'object', additionalProperties: false, properties: Object.fromEntries(Object.keys(scales(tokens)).map((s) => [s, scale])) },
+      role: { type: 'object', additionalProperties: false, properties: Object.fromEntries(Object.keys(roles(tokens)).map((r) => [r, roleValue])) },
+      font: { type: 'object', additionalProperties: false, properties: { sans: { type: 'array', items: { type: 'string' }, minItems: 1 } } },
+      marketing: {
+        type: 'object',
+        additionalProperties: false,
+        description: 'Landing and sign-in pages (landing-kit). Defaults: primary = color.primary.600, accent = color.primary.300, panel = role.shell.',
+        properties: { primary: hex, accent: hex, panel: hex },
+      },
+    },
+  };
+}
+
+const block = (selector, decls) =>
+  `${selector} {\n${Object.entries(decls).map(([k, v]) => `  ${k}: ${v};`).join('\n')}\n}\n`;
+
+/**
+ * CSS for only the variables a brand overrides, light and dark. Load it after twreact-ui's CSS.
+ * `scope` limits it to one part of the page (e.g. ".studio-ui") instead of :root.
+ */
+function brandCss(tokens, brand, { scope } = {}) {
+  const base = cssVariables(tokens);
+  const branded = cssVariables(applyBrand(tokens, brand));
+  const pick = (a, b) => Object.fromEntries(Object.entries(b).filter(([k, v]) => a[k] !== v));
+  const light = pick(base.light, branded.light);
+  const dark = pick(base.dark, branded.dark);
+  const lightSel = scope || ':root';
+  const darkSel = scope ? DARK_SELECTOR.split(',').map((s) => `${s.trim()} ${scope}`).join(', ') : DARK_SELECTOR;
+  let css = `/* Brand "${brandId(brand)}": only the variables it overrides. Load after twreact-ui's CSS. */\n`;
+  if (Object.keys(light).length) css += block(lightSel, light);
+  if (Object.keys(dark).length) css += '\n' + block(darkSel, dark);
+  return css;
+}
+
 const varName = (name, step) => (step ? `--dt-${name}-${step}` : `--dt-${name}`);
 const colorRef = (name, step) => `rgb(var(${varName(name, step)}) / <alpha-value>)`;
 
@@ -118,6 +237,11 @@ module.exports = {
   loadTokens,
   loadBrand,
   listBrands,
+  validateBrand,
+  brandSchema,
+  brandId,
+  brandLabel,
+  brandCss,
   applyBrand,
   hexToChannels,
   scales,