@usefragments/core 1.0.0

package/src/defineFragment.ts

@@ -0,0 +1,293 @@
+import type {
+  FragmentDefinition,
+  FragmentDefinitionV2,
+  CompiledFragment,
+  FragmentComponent,
+  BlockDefinition,
+  CompiledBlock,
+  AIMetadata,
+  FragmentGenerated,
+} from "./types.js";
+import type {
+  GovernedFragmentDefinition,
+  ResolvedGovernedFragmentDefinition,
+} from "./governance.js";
+import {
+  fragmentDefinitionSchema,
+  fragmentDefinitionV2Schema,
+  governedFragmentDefinitionSchema,
+  blockDefinitionSchema,
+} from "./schema.js";
+import { resolveComponentGovernance } from "./governance.js";
+
+function isGovernedDefinition<T>(
+  def: FragmentDefinition<T> | FragmentDefinitionV2<T> | GovernedFragmentDefinition<T>
+): def is GovernedFragmentDefinition<T> {
+  return "govern" in def || "governance" in def;
+}
+
+/**
+ * Check if a definition uses v2 field names.
+ * Detects `guidance` or `examples` (v2) vs `usage` or `variants` (v1).
+ */
+function isV2Definition<T>(
+  def: FragmentDefinition<T> | FragmentDefinitionV2<T> | GovernedFragmentDefinition<T>
+): def is FragmentDefinitionV2<T> {
+  return !isGovernedDefinition(def) && ("guidance" in def || "examples" in def);
+}
+
+/**
+ * Normalize a v2 definition to v1 shape for downstream compatibility.
+ * The build pipeline, compiler, and validators all work with v1 internally.
+ */
+export function normalizeToV1<T>(def: FragmentDefinitionV2<T>): FragmentDefinition<T> {
+  // Map composition → ai (rename fields)
+  let ai: AIMetadata | undefined;
+  if (def.composition) {
+    ai = {
+      compositionPattern: def.composition.pattern,
+      subComponents: def.composition.subComponents,
+      requiredChildren: def.composition.requiredChildren,
+      commonPatterns: def.composition.commonPatterns,
+    };
+  }
+
+  // Map _provenance → _generated (narrow source type, drop extended fields)
+  let generated: FragmentGenerated | undefined;
+  if (def._provenance) {
+    generated = {
+      source: def._provenance.source === "scan" ? "ai" : def._provenance.source,
+      sourceFile: def._provenance.sourceFile,
+      confidence: def._provenance.confidence,
+      timestamp: def._provenance.timestamp,
+    };
+  }
+
+  return {
+    component: def.component,
+    meta: def.meta,
+    usage: def.guidance,
+    props: def.props,
+    relations: def.relations,
+    variants: def.examples,
+    contract: def.contract,
+    ai,
+    _generated: generated,
+  };
+}
+
+/**
+ * Define a fragment for a component.
+ *
+ * This is the main API for creating fragment documentation.
+ * It provides runtime validation and type safety.
+ *
+ * Accepts both v1 and v2 shapes:
+ * - v1: `{ usage, variants, ai, _generated }`
+ * - v2: `{ guidance, examples, composition, _provenance }`
+ *
+ * @example v1
+ * ```tsx
+ * import { defineFragment } from '@usefragments/core';
+ * import { Button } from './Button';
+ *
+ * export default defineFragment({
+ *   component: Button,
+ *   meta: {
+ *     name: 'Button',
+ *     description: 'Primary action trigger',
+ *     category: 'actions',
+ *   },
+ *   usage: {
+ *     when: ['User needs to trigger an action'],
+ *     whenNot: ['Navigation without side effects'],
+ *   },
+ *   props: {
+ *     variant: {
+ *       type: 'enum',
+ *       values: ['primary', 'secondary'],
+ *       default: 'primary',
+ *       description: 'Visual style',
+ *     },
+ *   },
+ *   variants: [
+ *     {
+ *       name: 'Default',
+ *       description: 'Default button',
+ *       render: () => <Button>Click me</Button>,
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @example v2
+ * ```tsx
+ * import { defineFragment } from '@usefragments/core';
+ * import { Card } from './Card';
+ *
+ * export default defineFragment({
+ *   component: Card,
+ *   meta: { name: 'Card', description: 'Content container', category: 'layout' },
+ *   guidance: {
+ *     when: ['Grouping related content'],
+ *     whenNot: ['Full-page layouts'],
+ *   },
+ *   props: { ... },
+ *   examples: [{ name: 'Default', description: 'Basic card', render: () => <Card>...</Card> }],
+ *   composition: { pattern: 'compound', subComponents: ['Header', 'Body', 'Footer'] },
+ * });
+ * ```
+ */
+export function defineFragment<TProps>(
+  definition: GovernedFragmentDefinition<TProps>
+): ResolvedGovernedFragmentDefinition<TProps>;
+export function defineFragment<TProps>(
+  definition: FragmentDefinition<TProps>
+): FragmentDefinition<TProps>;
+export function defineFragment<TProps>(
+  definition: FragmentDefinitionV2<TProps>
+): FragmentDefinitionV2<TProps>;
+export function defineFragment<TProps>(
+  definition:
+    | FragmentDefinition<TProps>
+    | FragmentDefinitionV2<TProps>
+    | GovernedFragmentDefinition<TProps>
+):
+  | FragmentDefinition<TProps>
+  | FragmentDefinitionV2<TProps>
+  | ResolvedGovernedFragmentDefinition<TProps> {
+  // Validate at runtime in development
+  if (process.env.NODE_ENV !== "production") {
+    const governed = isGovernedDefinition(definition);
+    const v2 = isV2Definition(definition);
+    const schema = governed
+      ? governedFragmentDefinitionSchema
+      : v2
+        ? fragmentDefinitionV2Schema
+        : fragmentDefinitionSchema;
+    const result = schema.safeParse(definition);
+    if (!result.success) {
+      const name = definition.meta?.name || "unknown";
+      const errors = result.error.errors
+        .map((e) => `  - ${e.path.join(".")}: ${e.message}`)
+        .join("\n");
+      throw new Error(`Invalid fragment definition for "${name}":\n${errors}`);
+    }
+  }
+
+  if (isGovernedDefinition(definition)) {
+    const governance = resolveComponentGovernance(definition);
+    return {
+      ...definition,
+      governance,
+    };
+  }
+
+  return definition;
+}
+
+/**
+ * Compile a fragment definition to JSON-serializable format.
+ * Used for generating fragments.json for AI consumption.
+ *
+ * Accepts both v1 and v2 shapes. V2 is normalized to v1 internally.
+ */
+export function compileFragment(
+  definition: FragmentDefinition | FragmentDefinitionV2 | GovernedFragmentDefinition,
+  filePath: string
+): CompiledFragment {
+  // Normalize v2 → v1 if needed
+  const v1 = isGovernedDefinition(definition)
+    ? {
+        component: definition.component,
+        meta: definition.meta,
+        usage: definition.guidance,
+        props: definition.props ?? {},
+        relations: definition.relations,
+        variants: definition.examples ?? [],
+        contract: definition.contract,
+        _generated: definition._provenance
+          ? {
+              source:
+                definition._provenance.source === "scan" ? "ai" : definition._provenance.source,
+              sourceFile: definition._provenance.sourceFile,
+              confidence: definition._provenance.confidence,
+              timestamp: definition._provenance.timestamp,
+            }
+          : undefined,
+      }
+    : isV2Definition(definition)
+      ? normalizeToV1(definition)
+      : definition;
+
+  return {
+    filePath,
+    meta: v1.meta,
+    ...(isGovernedDefinition(definition) && { guidance: definition.guidance }),
+    usage: v1.usage,
+    props: v1.props,
+    ...(isGovernedDefinition(definition) && {
+      governance: resolveComponentGovernance(definition),
+    }),
+    relations: v1.relations,
+    variants: v1.variants.map((v) => ({
+      name: v.name,
+      description: v.description,
+      code: v.code,
+      figma: v.figma,
+    })),
+    contract: v1.contract,
+    ai: v1.ai,
+    _generated: v1._generated,
+  };
+}
+
+/**
+ * Define a composition block.
+ *
+ * Blocks are pure data describing how design system components
+ * wire together for common use cases.
+ */
+export function defineBlock(definition: BlockDefinition): BlockDefinition {
+  if (process.env.NODE_ENV !== "production") {
+    const result = blockDefinitionSchema.safeParse(definition);
+    if (!result.success) {
+      const errors = result.error.errors
+        .map((e) => `  - ${e.path.join(".")}: ${e.message}`)
+        .join("\n");
+      throw new Error(`Invalid block definition for "${definition.name || "unknown"}":\n${errors}`);
+    }
+  }
+
+  return definition;
+}
+
+/**
+ * @deprecated Use defineBlock instead
+ */
+export const defineRecipe = defineBlock;
+
+/**
+ * Compile a block definition to JSON-serializable format.
+ */
+export function compileBlock(definition: BlockDefinition, filePath: string): CompiledBlock {
+  return {
+    filePath,
+    name: definition.name,
+    description: definition.description,
+    category: definition.category,
+    components: definition.components,
+    code: definition.code,
+    tags: definition.tags,
+  };
+}
+
+/**
+ * @deprecated Use compileBlock instead
+ */
+export const compileRecipe = compileBlock;
+
+/**
+ * Type helper for extracting props type from a component
+ */
+export type InferProps<T> = T extends FragmentComponent<infer P> ? P : never;

package/src/dtcg-generators.ts

@@ -0,0 +1,324 @@
+/**
+ * DTCG Output Generators — generate CSS, SCSS, Tailwind, and Figma output
+ * from a DTCG token source file.
+ *
+ * Makes DTCG the single source of truth with everything else as derived output.
+ */
+
+import type { DTCGTokenFile } from './dtcg.js';
+import { parseColor, parseDtcgTokens } from './tokens/index.js';
+
+// ---------------------------------------------------------------------------
+// Internal: parse a DTCG file to flat tokens
+// ---------------------------------------------------------------------------
+
+function parseToFlatTokens(
+  tokens: DTCGTokenFile,
+  prefix?: string,
+): Array<{ cssName: string; cssValue: string; category: string; description?: string }> {
+  // Use parseDTCGFile to get consistent output
+  const parsed = parseDtcgTokens(JSON.stringify(tokens), 'tokens.tokens.json');
+  const effectivePrefix = prefix ? `--${prefix.replace(/^--/, '').replace(/-$/, '')}-` : parsed.prefix;
+
+  const result: Array<{ cssName: string; cssValue: string; category: string; description?: string }> = [];
+
+  for (const [category, categoryTokens] of Object.entries(parsed.categories)) {
+    for (const token of categoryTokens) {
+      // Re-prefix if a custom prefix was requested
+      let cssName = token.name;
+      if (prefix && token.name.startsWith(parsed.prefix)) {
+        cssName = effectivePrefix + token.name.slice(parsed.prefix.length);
+      }
+
+      result.push({
+        cssName,
+        cssValue: token.value ?? '',
+        category,
+        description: token.description,
+      });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// CSS Custom Properties Generator
+// ---------------------------------------------------------------------------
+
+export interface CSSGeneratorOptions {
+  /** Token name prefix (e.g., 'ds' → '--ds-*') */
+  prefix?: string;
+  /** CSS selector to wrap variables in (default: ':root') */
+  selector?: string;
+}
+
+/**
+ * Generate CSS custom properties from a DTCG token file.
+ */
+export function generateCSSCustomProperties(
+  tokens: DTCGTokenFile,
+  options?: CSSGeneratorOptions,
+): string {
+  const selector = options?.selector ?? ':root';
+  const flatTokens = parseToFlatTokens(tokens, options?.prefix);
+
+  const lines: string[] = [];
+  lines.push(`${selector} {`);
+
+  // Group by category for readability
+  const grouped = new Map<string, typeof flatTokens>();
+  for (const token of flatTokens) {
+    const group = grouped.get(token.category) ?? [];
+    group.push(token);
+    grouped.set(token.category, group);
+  }
+
+  for (const [category, categoryTokens] of grouped) {
+    lines.push(`  /* ${category} */`);
+    for (const token of categoryTokens) {
+      if (token.description) {
+        lines.push(`  /* ${token.description} */`);
+      }
+      lines.push(`  ${token.cssName}: ${token.cssValue};`);
+    }
+    lines.push('');
+  }
+
+  lines.push('}');
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// SCSS Variables Generator
+// ---------------------------------------------------------------------------
+
+export interface SCSSGeneratorOptions {
+  /** Token name prefix (e.g., 'ds' → '$ds-*') */
+  prefix?: string;
+}
+
+/**
+ * Generate SCSS variables from a DTCG token file.
+ */
+export function generateSCSSVariables(
+  tokens: DTCGTokenFile,
+  options?: SCSSGeneratorOptions,
+): string {
+  const flatTokens = parseToFlatTokens(tokens, options?.prefix);
+
+  const lines: string[] = [];
+  lines.push('// Auto-generated from DTCG token file');
+  lines.push('// Do not edit directly — modify the .tokens.json source');
+  lines.push('');
+
+  // Group by category for readability
+  const grouped = new Map<string, typeof flatTokens>();
+  for (const token of flatTokens) {
+    const group = grouped.get(token.category) ?? [];
+    group.push(token);
+    grouped.set(token.category, group);
+  }
+
+  for (const [category, categoryTokens] of grouped) {
+    lines.push(`// ${category}`);
+    for (const token of categoryTokens) {
+      // Convert CSS variable name to SCSS variable name
+      const scssName = token.cssName.replace(/^--/, '$');
+      lines.push(`${scssName}: ${token.cssValue} !default;`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Tailwind Config Generator
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a Tailwind CSS configuration object from a DTCG token file.
+ * Compatible with Tailwind v3 and v4.
+ */
+export function generateTailwindConfig(
+  tokens: DTCGTokenFile,
+): Record<string, unknown> {
+  const flatTokens = parseToFlatTokens(tokens);
+
+  const theme: Record<string, Record<string, string>> = {};
+
+  for (const token of flatTokens) {
+    const tailwindKey = categoryToTailwindKey(token.category);
+    if (!tailwindKey) continue;
+
+    if (!theme[tailwindKey]) {
+      theme[tailwindKey] = {};
+    }
+
+    // Convert CSS name to Tailwind token key
+    // e.g., "--ds-color-brand-primary" → "brand-primary"
+    const parts = token.cssName.replace(/^--[\w]+-/, '').split('-');
+    // Remove the category prefix if it matches
+    const tokenKey = parts.join('-') || token.cssName;
+
+    theme[tailwindKey][tokenKey] = `var(${token.cssName})`;
+  }
+
+  return {
+    theme: {
+      extend: theme,
+    },
+  };
+}
+
+function categoryToTailwindKey(category: string): string | undefined {
+  switch (category) {
+    case 'colors':
+    case 'surfaces':
+    case 'text':
+      return 'colors';
+    case 'spacing':
+      return 'spacing';
+    case 'radius':
+      return 'borderRadius';
+    case 'typography':
+      return 'fontFamily';
+    case 'shadows':
+      return 'boxShadow';
+    case 'borders':
+      return 'borderWidth';
+    case 'transitions':
+      return 'transitionDuration';
+    case 'z-index':
+      return 'zIndex';
+    default:
+      return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Figma Variables Generator
+// ---------------------------------------------------------------------------
+
+export interface FigmaVariable {
+  name: string;
+  type: 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN';
+  value: unknown;
+  description?: string;
+  scopes?: string[];
+}
+
+export interface FigmaVariableCollection {
+  name: string;
+  modes: Array<{ name: string; modeId: string }>;
+  variables: FigmaVariable[];
+}
+
+/**
+ * Generate Figma Variables REST API-compatible payload from a DTCG token file.
+ */
+export function generateFigmaVariables(
+  tokens: DTCGTokenFile,
+): FigmaVariableCollection[] {
+  const flatTokens = parseToFlatTokens(tokens);
+
+  // Group by category into collections
+  const collections = new Map<string, FigmaVariable[]>();
+
+  for (const token of flatTokens) {
+    const collectionName = categoryToFigmaCollection(token.category);
+    const vars = collections.get(collectionName) ?? [];
+
+    vars.push({
+      name: token.cssName.replace(/^--/, '').replace(/-/g, '/'),
+      type: categoryToFigmaType(token.category),
+      value: parseFigmaValue(token.cssValue, token.category),
+      description: token.description,
+      scopes: categoryToFigmaScopes(token.category),
+    });
+
+    collections.set(collectionName, vars);
+  }
+
+  return Array.from(collections.entries()).map(([name, variables]) => ({
+    name,
+    modes: [{ name: 'Default', modeId: 'default' }],
+    variables,
+  }));
+}
+
+function categoryToFigmaCollection(category: string): string {
+  switch (category) {
+    case 'colors':
+    case 'surfaces':
+    case 'text':
+      return 'Colors';
+    case 'spacing':
+    case 'radius':
+      return 'Dimensions';
+    case 'typography':
+      return 'Typography';
+    case 'shadows':
+      return 'Effects';
+    default:
+      return 'Other';
+  }
+}
+
+function categoryToFigmaType(category: string): 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN' {
+  switch (category) {
+    case 'colors':
+    case 'surfaces':
+    case 'text':
+      return 'COLOR';
+    case 'spacing':
+    case 'radius':
+    case 'z-index':
+      return 'FLOAT';
+    default:
+      return 'STRING';
+  }
+}
+
+function categoryToFigmaScopes(category: string): string[] {
+  switch (category) {
+    case 'colors':
+      return ['ALL_FILLS', 'STROKE_COLOR'];
+    case 'surfaces':
+      return ['FRAME_FILL', 'SHAPE_FILL'];
+    case 'text':
+      return ['TEXT_FILL'];
+    case 'spacing':
+      return ['GAP', 'WIDTH_HEIGHT'];
+    case 'radius':
+      return ['CORNER_RADIUS'];
+    default:
+      return ['ALL_SCOPES'];
+  }
+}
+
+function parseFigmaValue(cssValue: string, category: string): unknown {
+  // For colors, try to parse hex to Figma RGBA object
+  if (category === 'colors' || category === 'surfaces' || category === 'text') {
+    const color = parseColor(cssValue);
+    if (color) {
+      return {
+        r: color.r / 255,
+        g: color.g / 255,
+        b: color.b / 255,
+        a: color.a ?? 1,
+      };
+    }
+  }
+
+  // For dimensions, extract numeric value
+  if (category === 'spacing' || category === 'radius') {
+    const numMatch = cssValue.match(/^(\d+(?:\.\d+)?)/);
+    if (numMatch) {
+      return parseFloat(numMatch[1]);
+    }
+  }
+
+  return cssValue;
+}

package/src/dtcg-parser.ts

@@ -0,0 +1 @@
+export { isDTCGFile, parseDtcgTokens as parseDTCGFile } from "./tokens/index.js";