@react-native-rethemed/cli 0.0.0-stage → 0.1.0

package/src/model.ts

@@ -0,0 +1,392 @@
+import {
+  isTextPreset,
+  RN_DEFAULT_FONT_SIZE,
+  resolveBaseFontSize,
+  type ShadowToken,
+  type TextColor,
+  type TextToken,
+  type TextTokenTree,
+  type ThemeConfig,
+  walkSemanticColors,
+  walkTextPresets,
+} from '@react-native-rethemed/core/config';
+import { code, orderedEntries, table } from './emit';
+
+/**
+ * The evaluated theme flattened into display order — the single view of the
+ * tokens that both `themed.gen.ts` and the Markdown docs render from, so the
+ * two can never disagree.
+ */
+export type TokenModel = {
+  /**
+   * `semanticTokens.colors`, flattened to `'group.token'` (or the bare name
+   * for a top-level color, whose `group` is `''`).
+   */
+  colors: { token: string; group: string; light: string; dark: string }[];
+  radii: [string, number][];
+  spacing: [string, number][];
+  fontSizes: [string, number][];
+  fontWeights: [string, unknown][];
+  lineHeights: [string, number][];
+  letterSpacings: [string, number][];
+  shadows: [string, ShadowToken][];
+  zIndices: [string, number][];
+  /** `tokens.colors` — scheme-independent primitives, also color tokens. */
+  primitiveColors: [string, string][];
+  /** `semanticTokens.text` as a tree, each preset's cells already rendered. */
+  text: TextNode[];
+  /**
+   * The first preset (by path) whose `lineHeight` is a token (a ratio, so it
+   * follows `fontSize`) and the first whose `lineHeight` is an absolute
+   * number. Overriding a preset's size works differently for each.
+   */
+  presetLineHeights: { ratio?: string; absolute?: string };
+  /** `defaults.fontSize` resolved, for line-height ratios without a fontSize. */
+  baseFontSize: { value: number; label: string };
+};
+
+/** A node of `semanticTokens.text`: a preset (leaf) or a group. */
+export type TextNode =
+  | {
+      kind: 'preset';
+      name: string;
+      path: string;
+      cells: string[];
+      /** The preset's `color`, rendered; `undefined` when it has none. */
+      color?: string;
+      /** The preset's `textTransform`; `undefined` when it has none. */
+      textTransform?: string;
+    }
+  | { kind: 'group'; name: string; path: string; children: TextNode[] };
+
+export const PRESET_FIELDS = [
+  'fontSize',
+  'lineHeight',
+  'letterSpacing',
+  'fontWeight',
+] as const;
+
+export function buildModel(config: ThemeConfig): TokenModel {
+  const tokens = config.tokens ?? {};
+  const byValue = (v: number) => v;
+
+  const scaleFor = {
+    fontSize: tokens.fontSizes,
+    lineHeight: tokens.lineHeights,
+    letterSpacing: tokens.letterSpacings,
+    fontWeight: tokens.fontWeights,
+  } as const;
+  const baseFontSize = resolveBaseFontSize(config);
+  const fontSizeOf = (preset: TextToken) => {
+    const { fontSize } = preset;
+    if (typeof fontSize === 'number') return fontSize;
+    const scale = tokens.fontSizes;
+    return typeof fontSize === 'string' &&
+      scale &&
+      Object.hasOwn(scale, fontSize)
+      ? scale[fontSize]
+      : baseFontSize;
+  };
+
+  /**
+   * `'lg'` -> `` `lg` (18) `` so a table shows what a reference means. A
+   * line-height token is a ratio, so it also shows the computed value:
+   * `` `short` (×1.375 → 24.75) ``.
+   */
+  const presetCell = (preset: TextToken, field: keyof typeof scaleFor) => {
+    const value = preset[field];
+    if (value === undefined) return '–';
+    const scale = scaleFor[field] as Record<string, unknown> | undefined;
+    if (typeof value === 'string' && scale && Object.hasOwn(scale, value)) {
+      if (field === 'lineHeight') {
+        const ratio = scale[value] as number;
+        return `${code(value)} (×${ratio} → ${round2(fontSizeOf(preset) * ratio)})`;
+      }
+      return `${code(value)} (${scale[value]})`;
+    }
+    return String(value);
+  };
+
+  const baseKey = config.defaults?.fontSize;
+  const baseLabel =
+    typeof baseKey === 'string'
+      ? `${code(baseKey)} (${baseFontSize})`
+      : typeof baseKey === 'number'
+        ? String(baseKey)
+        : `${RN_DEFAULT_FONT_SIZE} (React Native default)`;
+
+  return {
+    colors: semanticColorRows(config),
+    radii: orderedEntries(tokens.radii, byValue),
+    spacing: orderedEntries(tokens.spacing, byValue),
+    fontSizes: orderedEntries(tokens.fontSizes, byValue),
+    fontWeights: orderedEntries(tokens.fontWeights, (v) => Number(v) || 0),
+    lineHeights: orderedEntries(tokens.lineHeights, byValue),
+    letterSpacings: orderedEntries(tokens.letterSpacings, byValue),
+    shadows: Object.entries(tokens.shadows ?? {}),
+    zIndices: orderedEntries(tokens.zIndices, byValue),
+    primitiveColors: Object.entries(tokens.colors ?? {}),
+    text: textNodes(config.semanticTokens?.text, (preset) =>
+      PRESET_FIELDS.map((f) => presetCell(preset, f)),
+    ),
+    presetLineHeights: presetLineHeightKinds(config),
+    baseFontSize: { value: baseFontSize, label: baseLabel },
+  };
+}
+
+function semanticColorRows(config: ThemeConfig): TokenModel['colors'] {
+  const rows: TokenModel['colors'] = [];
+  walkSemanticColors(config.semanticTokens?.colors, (token, color, group) => {
+    rows.push({
+      token,
+      group: group ?? '',
+      light: color.light,
+      dark: color.dark,
+    });
+  });
+  return rows;
+}
+
+const round2 = (value: number) => Math.round(value * 100) / 100;
+
+function presetLineHeightKinds(
+  config: ThemeConfig,
+): TokenModel['presetLineHeights'] {
+  const paths: Record<'ratio' | 'absolute', string[]> = {
+    ratio: [],
+    absolute: [],
+  };
+  walkTextPresets(config.semanticTokens?.text, (path, preset) => {
+    if (typeof preset.lineHeight === 'string') paths.ratio.push(path.join('.'));
+    if (typeof preset.lineHeight === 'number') {
+      paths.absolute.push(path.join('.'));
+    }
+  });
+  // Same preference as `examplePreset`: a mid-sized `title.md` reads best.
+  const pick = (list: string[]) =>
+    list.find((p) => p === 'title.md') ?? list[0];
+  return { ratio: pick(paths.ratio), absolute: pick(paths.absolute) };
+}
+
+/**
+ * A preset `color` as a table cell: `#777777` (both schemes), or
+ * `light: #111111, dark: #ffffff` — a scheme left out is simply not listed.
+ */
+export function colorCell(color: TextColor | undefined): string | undefined {
+  if (color === undefined) return undefined;
+  if (typeof color === 'string') return color;
+  return (['light', 'dark'] as const)
+    .filter((scheme) => color[scheme] !== undefined)
+    .map((scheme) => `${scheme}: ${color[scheme]}`)
+    .join(', ');
+}
+
+function textNodes(
+  tree: TextTokenTree | undefined,
+  cells: (preset: TextToken) => string[],
+  prefix: string[] = [],
+): TextNode[] {
+  return Object.entries(tree ?? {})
+    .filter(([, node]) => typeof node === 'object' && node !== null)
+    .map(([name, node]): TextNode => {
+      const path = [...prefix, name];
+      return isTextPreset(node)
+        ? {
+            kind: 'preset',
+            name,
+            path: path.join('.'),
+            cells: cells(node),
+            color: colorCell(node.color),
+            textTransform: node.textTransform,
+          }
+        : {
+            kind: 'group',
+            name,
+            path: path.join('.'),
+            children: textNodes(node as TextTokenTree, cells, path),
+          };
+    });
+}
+
+/**
+ * Every group that directly holds presets, with those presets — one table
+ * each. The root comes first with path `''` when presets sit at the top.
+ */
+export function presetGroups(
+  nodes: TextNode[],
+  path = '',
+): { path: string; presets: Extract<TextNode, { kind: 'preset' }>[] }[] {
+  const presets = nodes.filter(
+    (n): n is Extract<TextNode, { kind: 'preset' }> => n.kind === 'preset',
+  );
+  return [
+    ...(presets.length > 0 ? [{ path, presets }] : []),
+    ...nodes.flatMap((n) =>
+      n.kind === 'group' ? presetGroups(n.children, n.path) : [],
+    ),
+  ];
+}
+
+/** First preset in definition order, preferring `title.md` for examples. */
+export function examplePreset(nodes: TextNode[]): string | undefined {
+  const all = presetGroups(nodes).flatMap((g) => g.presets.map((p) => p.path));
+  return all.find((p) => p === 'title.md') ?? all[0];
+}
+
+/** Line heights are ratios of `fontSize`; show them as `×1.375`. */
+export function lineHeightRows(model: TokenModel): [string, string][] {
+  return model.lineHeights.map(([k, v]) => [k, `×${v}`]);
+}
+
+/** One sentence explaining how a line-height token resolves. */
+export function lineHeightNote(model: TokenModel): string {
+  return `Ratios of \`fontSize\`: a token resolves to \`fontSize × ratio\`, using the style's own \`fontSize\` or else the default font size, ${model.baseFontSize.label}. A raw number is an absolute line height.`;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown tables shared by the JSDoc and the docs file
+// ---------------------------------------------------------------------------
+
+export function colorTable(rows: TokenModel['colors']): string[] {
+  return table(
+    ['token', 'light', 'dark'],
+    ['left', 'left', 'left'],
+    rows.map((c) => [code(c.token), c.light, c.dark]),
+  );
+}
+
+/** More distinct shade names than this and a grid gets too wide to read. */
+const MAX_PALETTE_SHADES = 12;
+
+/**
+ * `tokens.colors` for display. Keys shaped `<hue>.<shade>` become one grid
+ * row per hue (`| red | #fef2f2 | … |`), which keeps a few hundred palette
+ * colors readable in a hover; anything else (`white`) goes in a plain
+ * token/value table first. Falls back to a single plain table when the keys
+ * don't form a palette.
+ */
+export function primitiveColorTables(rows: [string, string][]): {
+  lines: string[];
+  /** A real `<hue>.<shade>` token to cite next to the grid. */
+  example?: string;
+} {
+  const plain = (r: [string, string][]) =>
+    table(
+      ['token', 'value'],
+      ['left', 'left'],
+      r.map(([k, v]) => [code(k), v]),
+    );
+
+  const singles: [string, string][] = [];
+  const hues = new Map<string, Map<string, string>>();
+  for (const [key, value] of rows) {
+    const parts = key.split('.');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      singles.push([key, value]);
+      continue;
+    }
+    const [hue, shade] = parts;
+    const shades = hues.get(hue) ?? new Map<string, string>();
+    shades.set(shade, value);
+    hues.set(hue, shades);
+  }
+
+  const shades = [...new Set([...hues.values()].flatMap((m) => [...m.keys()]))];
+  if (shades.every((s) => /^\d+$/.test(s))) {
+    shades.sort((a, b) => Number(a) - Number(b));
+  }
+  if (hues.size === 0 || shades.length > MAX_PALETTE_SHADES) {
+    return { lines: plain(rows) };
+  }
+
+  const grid = table(
+    ['hue', ...shades],
+    ['left', ...shades.map(() => 'left' as const)],
+    [...hues].map(([hue, byShade]) => [
+      code(hue),
+      ...shades.map((s) => byShade.get(s) ?? '–'),
+    ]),
+  );
+  const [firstHue, firstShades] = [...hues][0];
+  const exampleShade = firstShades.has('500')
+    ? '500'
+    : [...firstShades.keys()][0];
+  return {
+    lines: singles.length > 0 ? [...plain(singles), '', ...grid] : grid,
+    example: `${firstHue}.${exampleShade}`,
+  };
+}
+
+/** How primitive colors behave, and how to name one from the grid. */
+export function primitiveColorNote(example: string | undefined): string {
+  const grid = example
+    ? ` A grid cell is the token \`'<hue>.<shade>'\`, e.g. \`'${example}'\`.`
+    : '';
+  return `Fixed colors, the same in light and dark.${grid}`;
+}
+
+export function scaleTable(rows: [string, unknown][]): string[] {
+  return table(
+    ['token', 'value'],
+    ['left', 'right'],
+    rows.map(([k, v]) => [code(k), String(v)]),
+  );
+}
+
+export function shadowTable(rows: TokenModel['shadows']): string[] {
+  return table(
+    ['token', 'offset (x, y)', 'radius', 'opacity', 'elevation', 'color'],
+    ['left', 'right', 'right', 'right', 'right', 'left'],
+    rows.map(([k, s]) => [
+      code(k),
+      `${s.shadowOffset?.width ?? 0}, ${s.shadowOffset?.height ?? 0}`,
+      String(s.shadowRadius ?? '–'),
+      String(s.shadowOpacity ?? '–'),
+      String(s.elevation ?? '–'),
+      String(s.shadowColor ?? '–'),
+    ]),
+  );
+}
+
+/** Presets as rows, named by their full path (`title.md`). */
+export function presetTable(
+  presets: Extract<TextNode, { kind: 'preset' }>[],
+): string[] {
+  // Optional columns only appear when a preset in this table has a value.
+  const extras = optionalPresetColumns(presets);
+  return table(
+    ['preset', ...PRESET_FIELDS, ...extras.map((c) => c.header)],
+    [
+      'left',
+      'right',
+      'right',
+      'right',
+      'right',
+      ...extras.map(() => 'left' as const),
+    ],
+    presets.map((p) => [
+      code(p.path),
+      ...p.cells,
+      ...extras.map((c) => c.cell(p)),
+    ]),
+  );
+}
+
+type PresetExtras = Pick<
+  Extract<TextNode, { kind: 'preset' }>,
+  'textTransform' | 'color'
+>;
+
+const OPTIONAL_PRESET_FIELDS = ['textTransform', 'color'] as const;
+
+/**
+ * Preset fields shown only when used (`textTransform`, `color`), in column
+ * order: a table includes a column when any of its presets sets the field.
+ */
+export function optionalPresetColumns(
+  presets: PresetExtras[],
+): { header: string; cell: (preset: PresetExtras) => string }[] {
+  return OPTIONAL_PRESET_FIELDS.filter((field) =>
+    presets.some((p) => p[field] !== undefined),
+  ).map((field) => ({ header: field, cell: (p) => p[field] ?? '–' }));
+}

package/src/react-native-stub.cjs

@@ -0,0 +1,9 @@
+/**
+ * Stands in for `react-native` while the CLI evaluates a theme file in plain
+ * Node (see `load-theme.ts`). `react-native`'s entry is Flow source that Node
+ * can't parse, but a theme file may import from `@react-native-rethemed/core`,
+ * whose root also exports the React Native runtime (`createThemed`). Those
+ * imports are only used at render time, never while building a config, so an
+ * empty module is enough.
+ */
+module.exports = {};

package/src/validate.ts

@@ -0,0 +1,255 @@
+import {
+  isSchemeColor,
+  isTextPreset,
+  TEXT_TOKEN_FIELDS,
+  type TextTokenTree,
+  type ThemeConfig,
+  walkSemanticColors,
+  walkTextPresets,
+} from '@react-native-rethemed/core/config';
+
+/** Values RN's `TextStyle['fontWeight']` accepts as strings. */
+const RN_FONT_WEIGHTS = new Set([
+  'normal',
+  'bold',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  'ultralight',
+  'thin',
+  'light',
+  'medium',
+  'regular',
+  'semibold',
+  'condensedBold',
+  'condensed',
+  'heavy',
+  'black',
+]);
+
+/** Values RN's `TextStyle['textTransform']` accepts. */
+const RN_TEXT_TRANSFORMS = new Set([
+  'none',
+  'capitalize',
+  'uppercase',
+  'lowercase',
+]);
+
+const TEXT_REF_SCALES = {
+  fontSize: 'fontSizes',
+  lineHeight: 'lineHeights',
+  letterSpacing: 'letterSpacings',
+  fontWeight: 'fontWeights',
+} as const;
+
+/**
+ * Top-level preset/group names that would collide with the properties every
+ * function already has, since `themed.text` itself is callable.
+ */
+const RESERVED_TEXT_NAMES = new Set([
+  'apply',
+  'arguments',
+  'bind',
+  'call',
+  'caller',
+  'constructor',
+  'length',
+  'name',
+  'prototype',
+  'toString',
+]);
+
+const isPrimitive = (value: unknown) =>
+  typeof value === 'string' || typeof value === 'number';
+
+const isField = (key: string) =>
+  (TEXT_TOKEN_FIELDS as readonly string[]).includes(key);
+
+/**
+ * A preset `color`: a color string (both schemes), or `{ light?, dark? }`
+ * with at least one string.
+ */
+function checkTextColor(value: unknown, at: string, problems: string[]) {
+  if (typeof value === 'string' && value.length > 0) return;
+  const shape = `must be a color string or { light?, dark? } (preset field names such as 'color' can't name a group or preset)`;
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    problems.push(`${at}: ${shape}`);
+    return;
+  }
+  const entries = Object.entries(value);
+  const valid =
+    entries.length > 0 &&
+    entries.every(
+      ([k, v]) =>
+        (k === 'light' || k === 'dark') &&
+        typeof v === 'string' &&
+        v.length > 0,
+    );
+  if (!valid) problems.push(`${at}: ${shape}`);
+}
+
+/**
+ * Structural checks for the `semanticTokens.text` tree: every node is an
+ * object that is either a preset (known fields only; primitives, plus
+ * `color` which may be `{ light?, dark? }`) or a group (all objects) —
+ * never both, never empty. See `isTextPreset` for how the two are told
+ * apart.
+ */
+function checkTextTree(
+  tree: TextTokenTree,
+  path: string[],
+  problems: string[],
+): void {
+  for (const [key, node] of Object.entries(tree)) {
+    const at = `semanticTokens.text.${[...path, key].join('.')}`;
+
+    if (path.length === 0 && RESERVED_TEXT_NAMES.has(key)) {
+      problems.push(
+        `${at}: '${key}' is reserved (it collides with a function property of themed.text)`,
+      );
+      continue;
+    }
+    if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+      problems.push(`${at}: must be a preset or a group object`);
+      continue;
+    }
+
+    const entries = Object.entries(node);
+    if (entries.length === 0) {
+      problems.push(`${at}: is empty`);
+      continue;
+    }
+
+    if (isTextPreset(node)) {
+      // Objects under a non-field key are groups/presets nested in a preset.
+      const nested = entries
+        .filter(([k, v]) => !isField(k) && !isPrimitive(v))
+        .map(([k]) => k);
+      if (nested.length > 0) {
+        const fields = entries
+          .filter(([k, v]) => isField(k) || isPrimitive(v))
+          .map(([k]) => k);
+        problems.push(
+          `${at}: mixes preset fields (${fields.join(', ')}) with groups (${nested.join(', ')})`,
+        );
+        continue;
+      }
+      for (const [field, value] of entries) {
+        if (!isField(field)) {
+          problems.push(
+            `${at}.${field}: unknown preset field (expected ${TEXT_TOKEN_FIELDS.join(', ')})`,
+          );
+        } else if (field === 'color') {
+          checkTextColor(value, `${at}.color`, problems);
+        } else if (field === 'textTransform') {
+          if (typeof value !== 'string' || !RN_TEXT_TRANSFORMS.has(value)) {
+            problems.push(
+              `${at}.textTransform: must be one of ${[...RN_TEXT_TRANSFORMS].join(', ')}`,
+            );
+          }
+        } else if (!isPrimitive(value)) {
+          problems.push(`${at}.${field}: must be a string or a number`);
+        }
+      }
+    } else {
+      const fields = entries.filter(([, v]) => isPrimitive(v)).map(([k]) => k);
+      if (fields.length > 0) {
+        const groups = entries
+          .filter(([, v]) => !isPrimitive(v))
+          .map(([k]) => k);
+        problems.push(
+          `${at}: mixes preset fields (${fields.join(', ')}) with groups (${groups.join(', ')})`,
+        );
+        continue;
+      }
+      checkTextTree(node as TextTokenTree, [...path, key], problems);
+    }
+  }
+}
+
+/**
+ * Checks what the type system can no longer check once token types are
+ * generated rather than inferred: every `semanticTokens.text` reference must
+ * name a key of the matching `tokens` scale, and every semantic color must
+ * define both schemes. Returns human-readable problems (empty when valid).
+ */
+export function validateTheme(config: ThemeConfig): string[] {
+  const problems: string[] = [];
+  const tokens = config.tokens ?? {};
+
+  checkTextTree(config.semanticTokens?.text ?? {}, [], problems);
+
+  walkTextPresets(config.semanticTokens?.text, (path, preset) => {
+    for (const [field, scaleName] of Object.entries(TEXT_REF_SCALES)) {
+      const value = preset[field as keyof typeof preset];
+      if (typeof value !== 'string') continue;
+
+      const scale = tokens[scaleName];
+      if (scale && Object.hasOwn(scale, value)) continue;
+      if (field === 'fontWeight' && RN_FONT_WEIGHTS.has(value)) continue;
+
+      problems.push(
+        `semanticTokens.text.${path.join('.')}.${field}: '${value}' is not a key of tokens.${scaleName}` +
+          (scale ? '' : ` (tokens.${scaleName} is not defined)`),
+      );
+    }
+  });
+
+  const baseFontSize = config.defaults?.fontSize;
+  if (
+    typeof baseFontSize === 'string' &&
+    !(tokens.fontSizes && Object.hasOwn(tokens.fontSizes, baseFontSize))
+  ) {
+    problems.push(
+      `defaults.fontSize: '${baseFontSize}' is not a key of tokens.fontSizes`,
+    );
+  }
+
+  const checkSchemes = (value: unknown, token: string) => {
+    const color = value as { light?: unknown; dark?: unknown } | null;
+    if (typeof color?.light !== 'string' || typeof color?.dark !== 'string') {
+      problems.push(
+        `semanticTokens.colors.${token}: must define both 'light' and 'dark' strings`,
+      );
+    }
+  };
+  for (const [key, node] of Object.entries(
+    config.semanticTokens?.colors ?? {},
+  )) {
+    // A top-level color (`primary`) or a group of them (`bg.default`).
+    if (isSchemeColor(node) || typeof node !== 'object' || node === null) {
+      checkSchemes(node, key);
+      continue;
+    }
+    for (const [name, value] of Object.entries(node)) {
+      checkSchemes(value, `${key}.${name}`);
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Problems that don't stop codegen. A semantic color named like a primitive
+ * (`semanticTokens.colors.red['500']` vs `tokens.colors['red.500']`) is
+ * legal — color props resolve the name to the semantic color — but usually
+ * an accident, e.g. after `extendTheme` combined two packages.
+ */
+export function themeWarnings(config: ThemeConfig): string[] {
+  const primitives = config.tokens?.colors ?? {};
+  const warnings: string[] = [];
+  walkSemanticColors(config.semanticTokens?.colors, (token) => {
+    if (Object.hasOwn(primitives, token)) {
+      warnings.push(
+        `'${token}' is both a semantic color and a primitive color (tokens.colors); color props resolve it to the semantic color`,
+      );
+    }
+  });
+  return warnings;
+}