@worldcoin/nucleus 0.1.4

package/tokens/formats/icons-android.ts

@@ -0,0 +1,210 @@
+import Handlebars from 'handlebars';
+
+import { readTemplate } from './shared.js';
+import type { IconToken, IconVariant } from './icons-shared.js';
+
+const PACKAGE_NAME = 'com.worldcoin.nucleus.tokens';
+const TEMPLATE = Handlebars.compile(
+  readTemplate('tokens/templates/android/NucleusIcon.kt.hbs'),
+);
+
+// android resource names must be [a-z0-9_]; we prefix with `nucleus_icon_` so the
+// drawables don't collide with whatever the consuming app already ships.
+export const ANDROID_DRAWABLE_PREFIX = 'nucleus_icon';
+
+export function androidDrawableName(token: IconToken, variant: IconVariant): string {
+  return `${ANDROID_DRAWABLE_PREFIX}_${token.androidStem}_${variant}`;
+}
+
+// Kotlin marker interface + resource property generated for each variant an icon ships.
+// Icons that don't ship a variant simply don't implement that interface, so accessing the
+// missing variant's res property is a compile error in consuming code — no nullable res
+// IDs and no runtime variant resolution.
+const VARIANT_KOTLIN: Record<IconVariant, { markerInterface: string; property: string }> = {
+  outline: { markerInterface: 'HasOutline', property: 'outlineRes' },
+  regular: { markerInterface: 'HasRegular', property: 'regularRes' },
+  solid: { markerInterface: 'HasSolid', property: 'solidRes' },
+};
+
+interface AndroidIconEntry {
+  kotlinCase: string;
+  resourceName: string;
+  // marker interfaces for the variants this icon ships, e.g. ['HasOutline', 'HasRegular']
+  interfaces: string[];
+  // one non-null res property override per shipped variant
+  properties: Array<{ property: string; drawable: string }>;
+}
+
+function toAndroidEntry(token: IconToken): AndroidIconEntry {
+  return {
+    kotlinCase: token.kotlinCase,
+    resourceName: token.name,
+    interfaces: token.variants.map((variant) => VARIANT_KOTLIN[variant].markerInterface),
+    properties: token.variants.map((variant) => ({
+      property: VARIANT_KOTLIN[variant].property,
+      drawable: `R.drawable.${androidDrawableName(token, variant)}`,
+    })),
+  };
+}
+
+export function generateAndroidIcons(tokens: IconToken[]): string {
+  return TEMPLATE({ packageName: PACKAGE_NAME, tokens: tokens.map(toAndroidEntry) });
+}
+
+// SVG → VectorDrawable XML conversion. Our SVGs are uniform: a single <svg>
+// containing one or more <path>, <rect>, or <circle> children. The only
+// transform we encounter is a `matrix(...)` on a single rect in `gift.svg`.
+
+type Mat = readonly [number, number, number, number, number, number];
+const IDENTITY: Mat = [1, 0, 0, 1, 0, 0];
+
+function applyMat(mat: Mat, x: number, y: number): [number, number] {
+  return [mat[0] * x + mat[2] * y + mat[4], mat[1] * x + mat[3] * y + mat[5]];
+}
+
+function parseTransform(value: string | undefined): Mat {
+  if (!value) return IDENTITY;
+  const match = /matrix\(\s*([^)]+)\)/.exec(value);
+  if (!match) return IDENTITY;
+  const parts = match[1].split(/[\s,]+/).map(Number);
+  if (parts.length !== 6 || parts.some((n) => Number.isNaN(n))) {
+    throw new Error(`Unsupported svg transform: ${value}`);
+  }
+  return [parts[0], parts[1], parts[2], parts[3], parts[4], parts[5]] as const;
+}
+
+function parseAttrs(raw: string): Map<string, string> {
+  const map = new Map<string, string>();
+  const attrRegex = /([a-zA-Z][\w-]*)\s*=\s*"([^"]*)"/g;
+  let m;
+  while ((m = attrRegex.exec(raw)) !== null) {
+    map.set(m[1], m[2]);
+  }
+  return map;
+}
+
+function fmt(n: number): string {
+  // tidy up floats so the generated XML stays readable
+  return Number.isInteger(n) ? n.toString() : Number(n.toFixed(4)).toString();
+}
+
+function rectToPathData(attrs: Map<string, string>): string {
+  const x = Number(attrs.get('x') ?? '0');
+  const y = Number(attrs.get('y') ?? '0');
+  const width = Number(attrs.get('width') ?? '0');
+  const height = Number(attrs.get('height') ?? '0');
+  const mat = parseTransform(attrs.get('transform'));
+
+  const corners: Array<[number, number]> = [
+    [x, y],
+    [x + width, y],
+    [x + width, y + height],
+    [x, y + height],
+  ];
+  const transformed = corners.map(([cx, cy]) => applyMat(mat, cx, cy));
+
+  const [p0, p1, p2, p3] = transformed;
+  return `M${fmt(p0[0])},${fmt(p0[1])} L${fmt(p1[0])},${fmt(p1[1])} L${fmt(p2[0])},${fmt(p2[1])} L${fmt(p3[0])},${fmt(p3[1])} Z`;
+}
+
+function circleToPathData(attrs: Map<string, string>): string {
+  const cx = Number(attrs.get('cx') ?? '0');
+  const cy = Number(attrs.get('cy') ?? '0');
+  const r = Number(attrs.get('r') ?? '0');
+  const mat = parseTransform(attrs.get('transform'));
+
+  // we only ever apply identity transforms to circles in our icon set, so
+  // approximating with a single radius is fine
+  const [centerX, centerY] = applyMat(mat, cx, cy);
+  const start = centerX - r;
+  return `M${fmt(start)},${fmt(centerY)} a${fmt(r)},${fmt(r)} 0 1,0 ${fmt(2 * r)},0 a${fmt(r)},${fmt(r)} 0 1,0 ${fmt(-2 * r)},0 Z`;
+}
+
+interface DrawablePath {
+  pathData: string;
+  fill: boolean;
+  stroke: boolean;
+  strokeWidth: string | null;
+  strokeMiterLimit: string | null;
+}
+
+function elementToDrawablePath(tag: string, attrs: Map<string, string>): DrawablePath | null {
+  let pathData: string;
+  switch (tag) {
+    case 'path':
+      pathData = attrs.get('d') ?? '';
+      break;
+    case 'rect':
+      pathData = rectToPathData(attrs);
+      break;
+    case 'circle':
+      pathData = circleToPathData(attrs);
+      break;
+    default:
+      throw new Error(`Unsupported svg element: <${tag}>`);
+  }
+  if (!pathData) return null;
+
+  const fill = attrs.get('fill');
+  const stroke = attrs.get('stroke');
+
+  return {
+    pathData,
+    fill: fill !== undefined && fill !== 'none',
+    stroke: stroke !== undefined && stroke !== 'none',
+    strokeWidth: attrs.get('stroke-width') ?? null,
+    strokeMiterLimit: attrs.get('stroke-miterlimit') ?? null,
+  };
+}
+
+export function svgToVectorDrawable(svg: string): string {
+  const svgRoot = /<svg([^>]*)>/.exec(svg);
+  if (!svgRoot) throw new Error('Could not find <svg> root');
+  const rootAttrs = parseAttrs(svgRoot[1]);
+  const viewBox = rootAttrs.get('viewBox')?.split(/\s+/).map(Number) ?? [0, 0, 24, 24];
+  const width = viewBox[2];
+  const height = viewBox[3];
+
+  const elementRegex = /<(path|rect|circle)\b([^/>]*)\/?>/g;
+  const drawablePaths: DrawablePath[] = [];
+  let match;
+  while ((match = elementRegex.exec(svg)) !== null) {
+    const tag = match[1];
+    const attrs = parseAttrs(match[2]);
+    const path = elementToDrawablePath(tag, attrs);
+    if (path) drawablePaths.push(path);
+  }
+
+  // we hard-code black as the baseline color; consumers should tint via Compose
+  // `Icon(painter, tint = ...)` (or `setTint` on a drawable in views)
+  const placeholderColor = '#FF000000';
+
+  const pathXml = drawablePaths
+    .map((path) => {
+      const lines: string[] = [`android:pathData="${path.pathData}"`];
+      if (path.fill) {
+        lines.push(`android:fillColor="${placeholderColor}"`);
+      }
+      if (path.stroke) {
+        lines.push(`android:strokeColor="${placeholderColor}"`);
+        if (path.strokeWidth) {
+          lines.push(`android:strokeWidth="${path.strokeWidth}"`);
+        }
+        if (path.strokeMiterLimit) {
+          lines.push(`android:strokeMiterLimit="${path.strokeMiterLimit}"`);
+        }
+      }
+      return `    <path\n        ${lines.join('\n        ')} />`;
+    })
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="${width}dp"
+    android:height="${height}dp"
+    android:viewportWidth="${width}"
+    android:viewportHeight="${height}">
+${pathXml}
+</vector>
+`;
+}

package/tokens/formats/icons-ios.ts

@@ -0,0 +1,100 @@
+import Handlebars from 'handlebars';
+
+import { readTemplate } from './shared.js';
+import {
+  ICON_VARIANTS,
+  iconAssetBaseName,
+  type IconToken,
+  type IconVariant,
+} from './icons-shared.js';
+
+const TEMPLATE = Handlebars.compile(
+  readTemplate('tokens/templates/ios/NucleusIcon+Defaults.swift.hbs'),
+);
+
+interface IOSIconEntry {
+  name: string;
+  swiftCase: string;
+  availableVariantsSwift: string;
+  availableVariantsHuman: string;
+}
+
+function toIOSEntry(token: IconToken): IOSIconEntry {
+  const cases = token.variants.map((variant) => `.${variant}`).join(', ');
+  const human = token.variants.join(', ');
+
+  return {
+    name: token.name,
+    swiftCase: token.swiftCase,
+    availableVariantsSwift: cases,
+    availableVariantsHuman: human,
+  };
+}
+
+export function generateIOSIcons(tokens: IconToken[]): string {
+  return TEMPLATE({ tokens: tokens.map(toIOSEntry) });
+}
+
+// xcassets generation
+
+interface ImagesetContents {
+  images: Array<{
+    filename: string;
+    idiom: 'universal';
+  }>;
+  info: {
+    author: 'xcode';
+    version: 1;
+  };
+  properties: {
+    'preserves-vector-representation': true;
+    'template-rendering-intent': 'template';
+  };
+}
+
+interface CatalogContents {
+  info: {
+    author: 'xcode';
+    version: 1;
+  };
+}
+
+export function imagesetContentsJson(filename: string): string {
+  const contents: ImagesetContents = {
+    images: [{ filename, idiom: 'universal' }],
+    info: { author: 'xcode', version: 1 },
+    properties: {
+      'preserves-vector-representation': true,
+      'template-rendering-intent': 'template',
+    },
+  };
+  return `${JSON.stringify(contents, null, 2)}\n`;
+}
+
+export function catalogContentsJson(): string {
+  const contents: CatalogContents = {
+    info: { author: 'xcode', version: 1 },
+  };
+  return `${JSON.stringify(contents, null, 2)}\n`;
+}
+
+export interface IOSImagesetPlan {
+  name: string; // imageset directory name without extension
+  variant: IconVariant;
+  iconName: string; // kebab-case icon name (used to locate svg source)
+}
+
+export function planIOSImagesets(tokens: IconToken[]): IOSImagesetPlan[] {
+  const plans: IOSImagesetPlan[] = [];
+  for (const token of tokens) {
+    for (const variant of ICON_VARIANTS) {
+      if (!token.variants.includes(variant)) continue;
+      plans.push({
+        name: iconAssetBaseName(token.name, variant),
+        variant,
+        iconName: token.name,
+      });
+    }
+  }
+  return plans;
+}

package/tokens/formats/icons-shared.ts

@@ -0,0 +1,72 @@
+import { readdirSync, readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+export const ICON_DEFINITIONS_DIR = 'tokens/definitions/icons';
+export const ICON_VARIANTS = ['outline', 'regular', 'solid'] as const;
+export type IconVariant = (typeof ICON_VARIANTS)[number];
+
+export interface IconToken {
+  // kebab-case identifier — also the asset filename and Swift raw value
+  name: string;
+  // camelCase Swift case name
+  swiftCase: string;
+  // PascalCase Kotlin enum entry name
+  kotlinCase: string;
+  // snake_case stem used in android resource filenames
+  androidStem: string;
+  // variants this icon ships in (subset of ICON_VARIANTS)
+  variants: IconVariant[];
+}
+
+function kebabToCamel(name: string): string {
+  return name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+}
+
+function kebabToPascal(name: string): string {
+  const camel = kebabToCamel(name);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+function kebabToSnake(name: string): string {
+  return name.replace(/-/g, '_');
+}
+
+export function discoverIconTokens(): IconToken[] {
+  const seen = new Map<string, Set<IconVariant>>();
+
+  for (const variant of ICON_VARIANTS) {
+    const dir = resolve(ROOT, ICON_DEFINITIONS_DIR, variant);
+    const files = readdirSync(dir).filter((file) => file.toLowerCase().endsWith('.svg'));
+    for (const file of files) {
+      const name = file.replace(/\.svg$/i, '');
+      let variants = seen.get(name);
+      if (!variants) {
+        variants = new Set();
+        seen.set(name, variants);
+      }
+      variants.add(variant);
+    }
+  }
+
+  return [...seen.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, variants]) => ({
+      name,
+      swiftCase: kebabToCamel(name),
+      kotlinCase: kebabToPascal(name),
+      androidStem: kebabToSnake(name),
+      variants: ICON_VARIANTS.filter((variant) => variants.has(variant)),
+    }));
+}
+
+export function readIconSvg(variant: IconVariant, name: string): string {
+  const path = resolve(ROOT, ICON_DEFINITIONS_DIR, variant, `${name}.svg`);
+  return readFileSync(path, 'utf8');
+}
+
+export function iconAssetBaseName(name: string, variant: IconVariant): string {
+  return `${name}-${variant}`;
+}

package/tokens/formats/icons-web.ts

@@ -0,0 +1,36 @@
+import { type IconToken, type IconVariant, ICON_VARIANTS, iconAssetBaseName, readIconSvg } from './icons-shared.js';
+
+export interface WebIconEntry {
+  name: string;
+  // map of variant → relative path to the svg file (relative to the package root)
+  files: Partial<Record<IconVariant, string>>;
+  // map of variant → inlined svg source (handy for direct-paste use)
+  svg: Partial<Record<IconVariant, string>>;
+}
+
+const ICON_FOLDER = 'icons';
+
+export function planWebIcons(tokens: IconToken[]): WebIconEntry[] {
+  return tokens.map((token) => {
+    const files: Partial<Record<IconVariant, string>> = {};
+    const svg: Partial<Record<IconVariant, string>> = {};
+
+    for (const variant of ICON_VARIANTS) {
+      if (!token.variants.includes(variant)) continue;
+      const filename = `${iconAssetBaseName(token.name, variant)}.svg`;
+      files[variant] = `${ICON_FOLDER}/${filename}`;
+      svg[variant] = readIconSvg(variant, token.name).trim();
+    }
+
+    return { name: token.name, files, svg };
+  });
+}
+
+export function generateWebIconsManifest(tokens: IconToken[]): string {
+  const entries = planWebIcons(tokens);
+  const indexedByName: Record<string, Pick<WebIconEntry, 'files' | 'svg'>> = {};
+  for (const entry of entries) {
+    indexedByName[entry.name] = { files: entry.files, svg: entry.svg };
+  }
+  return `${JSON.stringify(indexedByName, null, 2)}\n`;
+}

package/tokens/formats/loaders.ts

@@ -0,0 +1,168 @@
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+function readJson<T>(jsonPath: string): T {
+  const absolute = resolve(ROOT, jsonPath);
+  try {
+    return JSON.parse(readFileSync(absolute, 'utf8')) as T;
+  } catch (err) {
+    throw new Error(`Failed to parse ${jsonPath}: ${(err as Error).message}`);
+  }
+}
+
+// ---------- colors ----------
+
+export interface ColorLeaf {
+  path: string[];
+  rawValue: string;
+}
+
+interface RawColorLeaf {
+  $value?: unknown;
+  $type?: unknown;
+}
+
+type RawColorTree = { [key: string]: RawColorLeaf | RawColorTree };
+
+function isRawLeaf(node: unknown): node is RawColorLeaf {
+  return typeof node === 'object' && node !== null && '$value' in (node as object);
+}
+
+function flattenColorTree(
+  tree: RawColorTree,
+  jsonPath: string,
+  basePath: string[] = [],
+): ColorLeaf[] {
+  const out: ColorLeaf[] = [];
+  for (const [key, value] of Object.entries(tree)) {
+    const path = [...basePath, key];
+    if (isRawLeaf(value)) {
+      const raw = value.$value;
+      if (typeof raw !== 'string') {
+        throw new Error(
+          `Invalid color token at ${path.join('.')} in ${jsonPath}: $value must be a string`,
+        );
+      }
+      out.push({ path, rawValue: raw });
+    } else {
+      out.push(...flattenColorTree(value as RawColorTree, jsonPath, path));
+    }
+  }
+  return out;
+}
+
+export function loadColorTokens(jsonPath: string): ColorLeaf[] {
+  return flattenColorTree(readJson<RawColorTree>(jsonPath), jsonPath);
+}
+
+// ---------- fonts ----------
+
+export interface FontFamily {
+  key: string;
+  file: string;
+  postscriptName: string;
+}
+
+export interface FontToken {
+  name: string;
+  family: FontFamily;
+  size: number;
+  weight: number;
+  letterSpacing: number;
+  lineHeight: number;
+  dynamicTypeStyle?: string;
+}
+
+export interface FontDefinitions {
+  families: FontFamily[];
+  tokens: FontToken[];
+}
+
+interface RawFontFamily {
+  file?: unknown;
+  postscriptName?: unknown;
+}
+
+interface RawFontToken {
+  family?: unknown;
+  size?: unknown;
+  weight?: unknown;
+  letterSpacing?: unknown;
+  lineHeight?: unknown;
+  dynamicTypeStyle?: unknown;
+}
+
+interface RawFontDefinitions {
+  families?: Record<string, RawFontFamily>;
+  tokens?: Record<string, RawFontToken>;
+}
+
+function requireString(value: unknown, where: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${where} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireNumber(value: unknown, where: string): number {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    throw new Error(`${where} must be a number`);
+  }
+  return value;
+}
+
+function parseFamily(key: string, raw: RawFontFamily, jsonPath: string): FontFamily {
+  const where = `${jsonPath} → families.${key}`;
+  return {
+    key,
+    file: requireString(raw.file, `${where}.file`),
+    postscriptName: requireString(raw.postscriptName, `${where}.postscriptName`),
+  };
+}
+
+function parseToken(
+  name: string,
+  raw: RawFontToken,
+  familiesByKey: Map<string, FontFamily>,
+  jsonPath: string,
+): FontToken {
+  const where = `${jsonPath} → tokens.${name}`;
+  const familyKey = requireString(raw.family, `${where}.family`);
+  const family = familiesByKey.get(familyKey);
+  if (!family) {
+    throw new Error(
+      `${where}.family references unknown family "${familyKey}". Known: ${[...familiesByKey.keys()].join(', ')}`,
+    );
+  }
+  return {
+    name,
+    family,
+    size: requireNumber(raw.size, `${where}.size`),
+    weight: requireNumber(raw.weight, `${where}.weight`),
+    letterSpacing: requireNumber(raw.letterSpacing, `${where}.letterSpacing`),
+    lineHeight: requireNumber(raw.lineHeight, `${where}.lineHeight`),
+    dynamicTypeStyle:
+      typeof raw.dynamicTypeStyle === 'string' ? raw.dynamicTypeStyle : undefined,
+  };
+}
+
+export function loadFontDefinitions(jsonPath: string): FontDefinitions {
+  const raw = readJson<RawFontDefinitions>(jsonPath);
+  if (!raw.families || !raw.tokens) {
+    throw new Error(`${jsonPath} must define both "families" and "tokens"`);
+  }
+
+  const families = Object.entries(raw.families).map(([key, value]) =>
+    parseFamily(key, value, jsonPath),
+  );
+  const familiesByKey = new Map(families.map((f) => [f.key, f]));
+
+  const tokens = Object.entries(raw.tokens).map(([name, value]) =>
+    parseToken(name, value, familiesByKey, jsonPath),
+  );
+
+  return { families, tokens };
+}