@atomixstudio/mcp 0.1.1 → 1.0.1

package/src/utils.ts

@@ -1,465 +0,0 @@
-/**
- * Utility functions for token traversal and manipulation
- */
-
-import { TOKEN_CATEGORIES, type TokenCategory } from "./tokens.js";
-
-/**
- * Get a token value by its dot-notation path
- * @example getTokenByPath(primitives, "colors.static.brand.primary")
- */
-export function getTokenByPath(obj: Record<string, unknown>, path: string): unknown {
-  const parts = path.split(".");
-  let current: unknown = obj;
-  
-  for (const part of parts) {
-    if (current === null || current === undefined) return undefined;
-    if (typeof current !== "object") return undefined;
-    current = (current as Record<string, unknown>)[part];
-  }
-  
-  return current;
-}
-
-/**
- * List all tokens in a category, optionally filtered by subcategory
- */
-export function listTokensInCategory(
-  primitives: Record<string, unknown>,
-  category: string,
-  subcategory?: string
-): Record<string, unknown> {
-  let base = primitives[category];
-  
-  if (!base) return {};
-  
-  if (subcategory) {
-    const subParts = subcategory.split(".");
-    for (const part of subParts) {
-      if (typeof base !== "object" || base === null) return {};
-      base = (base as Record<string, unknown>)[part];
-    }
-  }
-  
-  if (typeof base !== "object" || base === null) {
-    return { [subcategory || category]: base };
-  }
-  
-  return flattenTokens(base as Record<string, unknown>);
-}
-
-/**
- * Flatten a nested token object into dot-notation paths
- */
-export function flattenTokens(
-  obj: Record<string, unknown>,
-  prefix = ""
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  
-  for (const [key, value] of Object.entries(obj)) {
-    const path = prefix ? `${prefix}.${key}` : key;
-    
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      Object.assign(result, flattenTokens(value as Record<string, unknown>, path));
-    } else {
-      result[path] = value;
-    }
-  }
-  
-  return result;
-}
-
-/**
- * Get all available token categories
- */
-export function getTokenCategories(): TokenCategory[] {
-  return [...TOKEN_CATEGORIES];
-}
-
-/**
- * Convert a token path to a CSS variable name
- * @example getCssVariableName("colors.static.brand.primary") → "--atomix-colors-static-brand-primary"
- */
-export function getCssVariableName(path: string): string {
-  // Convert dot notation to dash notation
-  const dashPath = path
-    .replace(/\./g, "-")
-    .replace(/([a-z])([A-Z])/g, "$1-$2") // camelCase to kebab-case
-    .toLowerCase();
-  
-  return `--atomix-${dashPath}`;
-}
-
-/**
- * Parse a CSS variable name back to a token path
- * @example parseVariableName("--atomix-colors-static-brand-primary") → "colors.static.brand.primary"
- */
-export function parseVariableName(varName: string): string | null {
-  if (!varName.startsWith("--atomix-")) return null;
-  
-  return varName
-    .replace("--atomix-", "")
-    .replace(/-/g, ".");
-}
-
-/**
- * Check if a value looks like a hardcoded token (hex, rgb, px, etc.)
- */
-export function isHardcodedValue(value: string): {
-  isHardcoded: boolean;
-  type?: "color" | "spacing" | "unknown";
-  details?: string;
-} {
-  // Hex colors
-  if (/^#[0-9A-Fa-f]{3,8}$/.test(value)) {
-    return { isHardcoded: true, type: "color", details: "Hex color" };
-  }
-  
-  // RGB/RGBA/HSL
-  if (/^(rgb|rgba|hsl|hsla)\(/.test(value)) {
-    return { isHardcoded: true, type: "color", details: "Color function" };
-  }
-  
-  // Pixel values
-  if (/^\d+px$/.test(value)) {
-    return { isHardcoded: true, type: "spacing", details: "Pixel value" };
-  }
-  
-  // Rem values (outside of tokens)
-  if (/^\d+(\.\d+)?rem$/.test(value)) {
-    return { isHardcoded: true, type: "spacing", details: "Rem value" };
-  }
-  
-  // Tailwind arbitrary values
-  if (/\[.+\]/.test(value)) {
-    return { isHardcoded: true, type: "unknown", details: "Tailwind arbitrary value" };
-  }
-  
-  return { isHardcoded: false };
-}
-
-/**
- * Find tokens matching a hex color value
- */
-export function findTokensByColor(
-  primitives: Record<string, unknown>,
-  hexColor: string
-): Array<{ path: string; value: string }> {
-  const allTokens = flattenTokens(primitives);
-  const normalizedHex = hexColor.toLowerCase();
-  
-  return Object.entries(allTokens)
-    .filter(([_, value]) => {
-      if (typeof value !== "string") return false;
-      return value.toLowerCase() === normalizedHex;
-    })
-    .map(([path, value]) => ({ path, value: value as string }));
-}
-
-/**
- * Get semantic alias for a token path (for shorter CSS variable names)
- */
-export function getSemanticAlias(path: string): string | null {
-  // Common semantic aliases
-  const aliases: Record<string, string> = {
-    "colors.static.brand.primary": "--atomix-brand",
-    "colors.modes.light.bgPage": "--atomix-bg-page",
-    "colors.modes.light.bgSurface": "--atomix-bg-surface",
-    "colors.modes.light.textPrimary": "--atomix-text-primary",
-    "colors.modes.light.borderPrimary": "--atomix-border-primary",
-    // Icon colors
-    "colors.modes.light.iconBrand": "--atomix-icon-brand",
-    "colors.modes.light.iconStrong": "--atomix-icon-strong",
-    "colors.modes.light.iconSubtle": "--atomix-icon-subtle",
-    "colors.modes.light.iconDisabled": "--atomix-icon-disabled",
-    "typography.fontFamily.sans": "--atomix-font-sans",
-  };
-  
-  return aliases[path] || null;
-}
-
-// ============================================
-// TOKEN TIER CLASSIFICATION
-// ============================================
-
-export type TokenTier = "primitive" | "semantic" | "component";
-
-export interface TokenMetadata {
-  /** Token tier: primitive (raw values), semantic (purpose-driven), component (usage-specific) */
-  tier: TokenTier;
-  /** Whether this token can be modified by external tools */
-  mutable: boolean;
-  /** How to edit this token if mutable */
-  editVia?: "designer" | "code" | "api";
-  /** Usage guidance for AI tools */
-  guidance: string;
-}
-
-/**
- * Determine the tier and metadata for a token path.
- * 
- * TIER DEFINITIONS:
- * - Primitive: Raw foundational values (scales, raw colors, px/rem values)
- *   → Read-only reference for validation/a11y/docs
- *   
- * - Semantic: Purpose-driven mappings that reference primitives
- *   → The primary API for styling, editable via Designer
- *   
- * - Component: Token assignments for specific components
- *   → Editable via Designer, specific to component variants/sizes
- */
-export function getTokenMetadata(path: string): TokenMetadata {
-  // ============================================
-  // PRIMITIVE TIER (Read-Only Reference)
-  // Raw values that should not be modified by AI
-  // ============================================
-  
-  // Color scales (raw palette)
-  if (path.match(/^colors\.scales\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Raw color palette. Use semantic colors (colors.modes.*) in components instead.",
-    };
-  }
-  
-  // Alpha scales
-  if (path.match(/^colors\.scales\.(black|white|green)Alpha\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Alpha transparency scale. Reference only for overlays/effects.",
-    };
-  }
-  
-  // Spacing scale
-  if (path.match(/^spacing\.scale\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Spacing scale values. Use semantic spacing keys (xs, sm, md, lg) in components.",
-    };
-  }
-  
-  // Spacing inset/stack/inline (derived from scale)
-  if (path.match(/^spacing\.(inset|stack|inline|gap)\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Spacing presets derived from scale. Reference only.",
-    };
-  }
-  
-  // Typography raw values (fontSize, fontWeight, lineHeight)
-  if (path.match(/^typography\.(fontSize|fontWeight|lineHeight|lineHeightPx|letterSpacing|paragraphSpacing)\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Raw typography values. Use typeSets (title-lg, text-normal-regular) in components.",
-    };
-  }
-  
-  // Radius scale
-  if (path.match(/^radius\.scale\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Border radius scale. Use semantic radius (radius.semantic.*) or scale keys in components.",
-    };
-  }
-  
-  // Border width scale
-  if (path.match(/^borders\.width\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Border width scale. Use semantic border keys in components.",
-    };
-  }
-  
-  // Shadow elevation (raw shadows)
-  if (path.match(/^shadows\.elevation\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Elevation shadow values. Use elevation keys (sm, md, lg) in components.",
-    };
-  }
-  
-  // Motion duration/easing (raw values)
-  if (path.match(/^motion\.(duration|easing)\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Motion primitives. Use semantic motion presets (motion.semantic.*) when available.",
-    };
-  }
-  
-  // Z-index scale
-  if (path.match(/^zIndex\.scale\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Z-index scale. Use semantic z-index (zIndex.semantic.*) in components.",
-    };
-  }
-  
-  // Sizing raw values
-  if (path.match(/^sizing\./)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Component sizing values. Reference only for layout calculations.",
-    };
-  }
-  
-  // ============================================
-  // SEMANTIC TIER (Primary API)
-  // Purpose-driven tokens, editable via Designer
-  // ============================================
-  
-  // Mode colors (light/dark semantic colors)
-  if (path.match(/^colors\.modes\.(light|dark)\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Semantic color for theming. Use this in components. Editable via Atomix Designer.",
-    };
-  }
-  
-  // Adaptive colors (feedback colors)
-  if (path.match(/^colors\.adaptive\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Adaptive feedback color (error, warning, success, info). Use for validation states.",
-    };
-  }
-  
-  // Static brand colors
-  if (path.match(/^colors\.static\.brand/)) {
-    return {
-      tier: "semantic",
-      mutable: false, // Brand colors are locked
-      guidance: "Brand identity color. Use for primary brand elements. Protected from modification.",
-    };
-  }
-  
-  // Static utility colors (white, black, transparent)
-  if (path.match(/^colors\.static\.(white|black|transparent)/)) {
-    return {
-      tier: "primitive",
-      mutable: false,
-      guidance: "Static utility color. Use for absolute white/black when needed.",
-    };
-  }
-  
-  // Semantic radius
-  if (path.match(/^radius\.semantic\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Semantic border radius for component types. Use this in component styling.",
-    };
-  }
-  
-  // Semantic borders
-  if (path.match(/^borders\.semantic\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Semantic border width for component types. Use this in component styling.",
-    };
-  }
-  
-  // Semantic motion
-  if (path.match(/^motion\.semantic\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Semantic animation preset. Use for consistent motion patterns.",
-    };
-  }
-  
-  // Semantic z-index
-  if (path.match(/^zIndex\.semantic\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Semantic z-index for UI layers. Use for proper stacking order.",
-    };
-  }
-  
-  // Focus shadows
-  if (path.match(/^shadows\.focus\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Focus ring styles for accessibility. Use for keyboard focus indicators.",
-    };
-  }
-  
-  // Typography typeSets
-  if (path.match(/^typography\.typeSets\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Composed typography style. Use these for consistent text styling.",
-    };
-  }
-  
-  // Typography font families
-  if (path.match(/^typography\.fontFamily\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Font family selection. Use 'sans', 'mono', or 'display' keys.",
-    };
-  }
-  
-  // Typography text styles
-  if (path.match(/^typography\.textStyles\./)) {
-    return {
-      tier: "semantic",
-      mutable: true,
-      editVia: "designer",
-      guidance: "Complete text style definition. Use for consistent typography.",
-    };
-  }
-  
-  // ============================================
-  // DEFAULT: Assume primitive if unknown
-  // ============================================
-  return {
-    tier: "primitive",
-    mutable: false,
-    guidance: "Token classification unknown. Treat as read-only reference.",
-  };
-}
-
-/**
- * Check if a token path is a semantic token (the primary API for AI tools)
- */
-export function isSemanticToken(path: string): boolean {
-  const metadata = getTokenMetadata(path);
-  return metadata.tier === "semantic";
-}
-
-/**
- * Check if a token path is a primitive (read-only reference)
- */
-export function isPrimitiveToken(path: string): boolean {
-  const metadata = getTokenMetadata(path);
-  return metadata.tier === "primitive";
-}
-