@khaledeltohamy14/token-pipeline-engine 1.0.0

package/generators/token-utils.js

@@ -0,0 +1,355 @@
+const fs = require('fs');
+
+function readJSON(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`❌ File not found: ${filePath}`);
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `❌ Invalid JSON: ${filePath}\n${error.message}`
+    );
+  }
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function isObject(value) {
+  return value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value);
+}
+
+function isToken(value) {
+  return isObject(value) &&
+      ('$value' in value || 'value' in value);
+}
+
+function getTokenValue(token) {
+  return '$value' in token
+      ? token.$value
+      : token.value;
+}
+
+function getTokenType(token) {
+  return token.$type || token.type;
+}
+
+function isReference(value) {
+  return typeof value === 'string' &&
+      value.startsWith('{') &&
+      value.endsWith('}');
+}
+
+function cleanReference(value) {
+  return value
+      .replace(/^\{/, '')
+      .replace(/\}$/, '')
+      .trim();
+}
+
+/*
+|--------------------------------------------------------------------------
+| Dart naming
+|--------------------------------------------------------------------------
+|
+| JSON naming stays untouched.
+|
+| Dart:
+|
+| red_500                    -> red500
+| card_background            -> cardBackground
+| textfieldcomponent_padding -> textfieldComponentPadding
+| topRightButtonsComponent   -> topRightButtonsComponent
+| toprightbuttonscomponent   -> topRightButtonsComponent
+|
+|--------------------------------------------------------------------------
+*/
+
+const KNOWN_COMPOUND_NAMES = {
+  toprightbuttons: 'topRightButtons',
+  textfield: 'textfield',
+  button: 'button',
+  radio: 'radio',
+  card: 'card',
+};
+
+function normalizeCompoundWord(word) {
+  const lower = word.toLowerCase();
+
+  /*
+   * Handle:
+   *
+   * textfieldcomponent
+   * buttoncomponent
+   * radiocomponent
+   * cardcomponent
+   * toprightbuttonscomponent
+   */
+  if (lower.endsWith('component')) {
+    const base = lower.substring(
+      0,
+      lower.length - 'component'.length
+    );
+
+    const normalizedBase =
+        KNOWN_COMPOUND_NAMES[base] || base;
+
+    return `${normalizedBase}Component`;
+  }
+
+  return KNOWN_COMPOUND_NAMES[lower] || lower;
+}
+
+function splitIdentifier(value) {
+  return String(value)
+      .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+      .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+      .replace(/[_./\\\-]+/g, ' ')
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean);
+}
+
+function toDartIdentifier(value) {
+  const words = splitIdentifier(value);
+
+  if (!words.length) {
+    return '_token';
+  }
+
+  /*
+   * First normalize compound component words.
+   */
+  const normalizedWords = [];
+
+  for (finalWord of words) {
+    const normalized = normalizeCompoundWord(finalWord);
+
+    /*
+     * A word such as:
+     *
+     * topRightButtonsComponent
+     *
+     * can already contain camel casing.
+     */
+    const nested = normalized
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .split(/\s+/);
+
+    normalizedWords.push(...nested);
+  }
+
+  const first = normalizedWords[0].toLowerCase();
+
+  const rest = normalizedWords
+      .slice(1)
+      .map(word => {
+        const lower = word.toLowerCase();
+
+        return lower.charAt(0).toUpperCase() +
+            lower.slice(1);
+      })
+      .join('');
+
+  let result = first + rest;
+
+  if (/^\d/.test(result)) {
+    result = `_${result}`;
+  }
+
+  return result;
+}
+
+/*
+ * Same semantic key for duplicate detection.
+ *
+ * buttonComponent
+ * buttoncomponent
+ *
+ * => buttoncomponent
+ */
+function canonicalTokenKey(value) {
+  return String(value)
+      .replace(/[^a-zA-Z0-9]/g, '')
+      .toLowerCase();
+}
+
+const toSafeName = toDartIdentifier;
+
+function flattenTokens(
+  object,
+  prefix = '',
+  result = {}
+) {
+  for (const [key, value] of Object.entries(object || {})) {
+    const currentPath =
+        prefix
+            ? `${prefix}.${key}`
+            : key;
+
+    if (isToken(value)) {
+      result[currentPath] = value;
+    } else if (isObject(value)) {
+      flattenTokens(
+        value,
+        currentPath,
+        result
+      );
+    }
+  }
+
+  return result;
+}
+
+function colorValue(value) {
+  if (
+    typeof value !== 'string' ||
+    !value.startsWith('#')
+  ) {
+    return null;
+  }
+
+  let hex = value
+      .replace('#', '')
+      .toUpperCase();
+
+  if (hex.length === 3) {
+    hex = hex
+        .split('')
+        .map(x => x + x)
+        .join('');
+  }
+
+  if (hex.length === 6) {
+    return `Color(0xFF${hex})`;
+  }
+
+  if (hex.length === 8) {
+    return `Color(0x${hex})`;
+  }
+
+  return null;
+}
+
+function dimensionValue(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const match = value.match(
+    /^(-?\d+(?:\.\d+)?)px$/
+  );
+
+  return match ? match[1] : null;
+}
+
+function dartType(type) {
+  const types = {
+    color: 'Color',
+    dimension: 'double',
+    number: 'double',
+    string: 'String',
+    boolean: 'bool',
+  };
+
+  if (!types[type]) {
+    throw new Error(
+      `Unsupported type: ${type}`
+    );
+  }
+
+  return types[type];
+}
+
+function dartLiteral(
+  value,
+  type,
+  tokenPath = 'token'
+) {
+  if (type === 'color') {
+    const color = colorValue(value);
+
+    if (!color) {
+      throw new Error(
+        `❌ Invalid color token: ${tokenPath}\n` +
+        `Value: ${value}`
+      );
+    }
+
+    return {
+      type: 'Color',
+      value: color,
+    };
+  }
+
+  if (type === 'dimension') {
+    const dimension =
+        dimensionValue(value);
+
+    if (dimension === null) {
+      throw new Error(
+        `❌ Invalid dimension token: ${tokenPath}\n` +
+        `Value: ${value}`
+      );
+    }
+
+    return {
+      type: 'double',
+      value: dimension,
+    };
+  }
+
+  if (type === 'number') {
+    return {
+      type: 'double',
+      value: String(value),
+    };
+  }
+
+  if (type === 'string') {
+    return {
+      type: 'String',
+      value: JSON.stringify(
+        String(value)
+      ),
+    };
+  }
+
+  if (type === 'boolean') {
+    return {
+      type: 'bool',
+      value: value
+        ? 'true'
+        : 'false',
+    };
+  }
+
+  throw new Error(
+    `❌ Unsupported token type: ${type}\n` +
+    `Token: ${tokenPath}`
+  );
+}
+
+module.exports = {
+  readJSON,
+  ensureDir,
+  isObject,
+  isToken,
+  getTokenValue,
+  getTokenType,
+  isReference,
+  cleanReference,
+  toSafeName,
+  toDartIdentifier,
+  canonicalTokenKey,
+  flattenTokens,
+  colorValue,
+  dimensionValue,
+  dartType,
+  dartLiteral,
+};

package/index.d.ts

@@ -0,0 +1,34 @@
+export type TokenPipelineGeneratedFile = {
+  path: string;
+  content: string;
+  mode: '100644' | '100755';
+};
+
+export type GenerateTokenFilesOptions = {
+  document: Record<string, unknown>;
+  outputRoot?: string;
+};
+
+export type GenerateRepositoryFilesOptions = {
+  document: Record<string, unknown>;
+  outputRoot?: string;
+  tokenRoot?: string;
+  sourceTokenPath?: string;
+};
+
+export function splitTokenDocument(
+  document: Record<string, unknown>,
+): Record<string, unknown>;
+
+export function splitTokenFiles(
+  document: Record<string, unknown>,
+  root?: string,
+): TokenPipelineGeneratedFile[];
+
+export function generateTokenFiles(
+  options: GenerateTokenFilesOptions,
+): TokenPipelineGeneratedFile[];
+
+export function generateRepositoryFiles(
+  options: GenerateRepositoryFilesOptions,
+): TokenPipelineGeneratedFile[];

package/index.js

@@ -0,0 +1,148 @@
+const { splitTokenDocument, splitTokenFiles } = require('./split/split-token-document');
+const { renderGlobalTokens } = require('./generators/global-generator');
+const { renderAliasTokens } = require('./generators/alias-generator');
+const { renderCategoryTokens } = require('./generators/category-generator');
+const { renderComponentTokens } = require('./generators/component-generator');
+const { renderBrandTokens } = require('./generators/brand-generator');
+const { renderTheme, renderThemeTokens } = require('./generators/theme-generator');
+
+const CATEGORY_CONFIG = [
+  ['spacing', 'SpacingTokens'],
+  ['typography', 'TypographyTokens'],
+  ['radius', 'RadiusTokens'],
+  ['shadow', 'ShadowTokens'],
+  ['dimensions', 'DimensionTokens'],
+];
+
+function asRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function normalizeRelativePath(value) {
+  const normalized = String(value || '').trim().replace(/^\/+/, '').replace(/\\/g, '/');
+  if (!normalized || normalized.includes('..') || normalized.split('/').some((part) => !part)) {
+    throw new Error(`Invalid generated output path: ${value}`);
+  }
+  return normalized;
+}
+
+function joinPath(root, file) {
+  const cleanRoot = String(root || '').trim().replace(/^\/+|\/+$/g, '');
+  return cleanRoot ? `${cleanRoot}/${file}` : file;
+}
+
+function brandClassName(brandName) {
+  return String(brandName).split(/[_-]/).map((value) => value.charAt(0).toUpperCase() + value.slice(1)).join('') + 'Tokens';
+}
+
+function brandThemeClassName(brandName) {
+  return String(brandName).split(/[_-]/).map((value) => value.charAt(0).toUpperCase() + value.slice(1)).join('') + 'Theme';
+}
+
+function generateTokenFiles({
+  document,
+  outputRoot = 'packages/tokens/lib',
+}) {
+  const source = asRecord(document);
+  const tokens = asRecord(source.tokens);
+  const globalTokens = asRecord(tokens.global);
+  const aliasTokens = asRecord(tokens.alias);
+  const componentTokens = asRecord(tokens.components);
+  const spacingTokens = asRecord(tokens.spacing);
+  const typographyTokens = asRecord(tokens.typography);
+  const radiusTokens = asRecord(tokens.radius);
+  const shadowTokens = asRecord(tokens.shadow);
+  const dimensionTokens = asRecord(tokens.dimensions);
+  const brands = asRecord(tokens.brands);
+
+  const root = normalizeRelativePath(outputRoot);
+  const files = [];
+  const add = (path, content) => files.push({ path: joinPath(root, path), content, mode: '100644' });
+
+  add('global/global_tokens.dart', renderGlobalTokens({ tokens: globalTokens }));
+  add('alias/alias_tokens.dart', renderAliasTokens({ tokens: aliasTokens, globalTokens }));
+
+  for (const [name, className] of CATEGORY_CONFIG) {
+    add(`${name}/${name}_tokens.dart`, renderCategoryTokens({
+      tokens: asRecord(tokens[name]),
+      globalTokens,
+      aliasTokens,
+      className,
+    }));
+  }
+
+  add('components/component_tokens.dart', renderComponentTokens({
+    tokens: componentTokens,
+    aliasTokens,
+    globalTokens,
+    spacingTokens,
+    radiusTokens,
+    dimensionTokens,
+    typographyTokens,
+    shadowTokens,
+  }));
+
+  const brandNames = Object.keys(brands).sort();
+  const brandMap = {};
+  for (const brandName of brandNames) {
+    const brandTokens = asRecord(brands[brandName]);
+    brandMap[brandName] = brandTokens;
+    add(`brands/${brandName}_tokens.dart`, renderBrandTokens({
+      brandTokens,
+      aliasTokens,
+      globalTokens,
+      className: brandClassName(brandName),
+    }));
+    add(`themes/${brandName}_theme.dart`, renderTheme({
+      aliasTokens,
+      globalTokens,
+      componentTokens,
+      spacingTokens,
+      radiusTokens,
+      dimensionTokens,
+      typographyTokens,
+      shadowTokens,
+      brandTokens,
+      className: brandThemeClassName(brandName),
+    }));
+  }
+
+  add('themes/theme_tokens.dart', renderThemeTokens({
+    aliasTokens,
+    globalTokens,
+    componentTokens,
+    spacingTokens,
+    radiusTokens,
+    dimensionTokens,
+    typographyTokens,
+    shadowTokens,
+    brands: brandMap,
+  }));
+
+  return files;
+}
+
+function generateRepositoryFiles({
+  document,
+  outputRoot = 'packages/tokens/lib',
+  tokenRoot = 'token_pipeline/tokens',
+  sourceTokenPath = 'token_pipeline/tokens.json',
+}) {
+  const files = [];
+  const sourcePath = normalizeRelativePath(sourceTokenPath);
+  files.push({
+    path: sourcePath,
+    content: `${JSON.stringify(document, null, 2)}\n`,
+    mode: '100644',
+  });
+  files.push(...splitTokenFiles(document, tokenRoot));
+  files.push(...generateTokenFiles({ document, outputRoot }));
+  return files;
+}
+
+module.exports = {
+  splitTokenDocument,
+  splitTokenFiles,
+  generateTokenFiles,
+  generateRepositoryFiles,
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@khaledeltohamy14/token-pipeline-engine",
+  "version": "1.0.0",
+  "description": "Reusable Galaxy design token pipeline engine for splitting design tokens and generating token/theme files.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "generators",
+    "split",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_GITHUB_USERNAME/galaxy-token-pipeline-engine.git"
+  },
+  "keywords": [
+    "figma",
+    "design-tokens",
+    "flutter",
+    "dart",
+    "atomic-design",
+    "galaxy"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node test/engine.test.js",
+    "pack:check": "npm pack --dry-run"
+  }
+}

package/split/split-token-document.js

@@ -0,0 +1,58 @@
+const CATEGORY_NAMES = [
+  'global',
+  'alias',
+  'components',
+  'spacing',
+  'typography',
+  'radius',
+  'shadow',
+  'dimensions',
+];
+
+function asRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+}
+
+function splitTokenDocument(document) {
+  const source = asRecord(document);
+  const tokens = asRecord(source.tokens);
+  const result = {};
+
+  for (const category of CATEGORY_NAMES) {
+    result[category] = asRecord(tokens[category]);
+  }
+
+  result.brands = asRecord(tokens.brands);
+
+  return result;
+}
+
+function splitTokenFiles(document, root = 'token_pipeline/tokens') {
+  const split = splitTokenDocument(document);
+  const files = [];
+
+  for (const category of CATEGORY_NAMES) {
+    files.push({
+      path: `${root}/${category}.json`,
+      content: `${JSON.stringify(split[category], null, 2)}\n`,
+      mode: '100644',
+    });
+  }
+
+  for (const [brandName, brandTokens] of Object.entries(split.brands)) {
+    files.push({
+      path: `token_pipeline/brands/${brandName}.json`,
+      content: `${JSON.stringify(asRecord(brandTokens), null, 2)}\n`,
+      mode: '100644',
+    });
+  }
+
+  return files;
+}
+
+module.exports = {
+  splitTokenDocument,
+  splitTokenFiles,
+};