@fragments-sdk/core 0.1.0

package/src/defineFragment.ts

@@ -0,0 +1,141 @@
+import type { FragmentDefinition, CompiledFragment, FragmentComponent, BlockDefinition, CompiledBlock } from './types.js';
+import { fragmentDefinitionSchema, blockDefinitionSchema } from './schema.js';
+
+/**
+ * Define a fragment for a component.
+ *
+ * This is the main API for creating fragment documentation.
+ * It provides runtime validation and type safety.
+ *
+ * @example
+ * ```tsx
+ * import { defineFragment } from '@fragments-sdk/cli/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>,
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function defineFragment<TProps>(
+  definition: FragmentDefinition<TProps>
+): FragmentDefinition<TProps> {
+  // Validate at runtime in development
+  if (process.env.NODE_ENV !== 'production') {
+    const result = fragmentDefinitionSchema.safeParse(definition);
+    if (!result.success) {
+      const errors = result.error.errors
+        .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
+        .join('\n');
+      throw new Error(
+        `Invalid fragment definition for "${definition.meta?.name || 'unknown'}":\n${errors}`
+      );
+    }
+  }
+
+  return definition;
+}
+
+/**
+ * Compile a fragment definition to JSON-serializable format.
+ * Used for generating fragments.json for AI consumption.
+ */
+export function compileFragment(
+  definition: FragmentDefinition,
+  filePath: string
+): CompiledFragment {
+  return {
+    filePath,
+    meta: definition.meta,
+    usage: definition.usage,
+    props: definition.props,
+    relations: definition.relations,
+    variants: definition.variants.map((v) => ({
+      name: v.name,
+      description: v.description,
+      code: v.code,
+      figma: v.figma,
+    })),
+    contract: definition.contract,
+    _generated: definition._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/figma.ts

@@ -0,0 +1,263 @@
+/**
+ * Figma property mapping DSL
+ *
+ * Provides helpers for mapping Figma component properties to code props.
+ * Inspired by Figma Code Connect's API.
+ *
+ * @example
+ * ```tsx
+ * import { defineFragment, figma } from '@fragments-sdk/cli/core';
+ *
+ * export default defineFragment({
+ *   component: Button,
+ *   meta: {
+ *     name: 'Button',
+ *     description: 'Primary action trigger',
+ *     category: 'actions',
+ *     figma: 'https://figma.com/file/abc/Design?node-id=1-2',
+ *     figmaProps: {
+ *       children: figma.string('Label'),
+ *       disabled: figma.boolean('Disabled'),
+ *       variant: figma.enum('Type', {
+ *         'Primary': 'primary',
+ *         'Secondary': 'secondary',
+ *       }),
+ *     },
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
+
+import type {
+  FigmaStringMapping,
+  FigmaBooleanMapping,
+  FigmaEnumMapping,
+  FigmaInstanceMapping,
+  FigmaChildrenMapping,
+  FigmaTextContentMapping,
+} from './types.js';
+
+/**
+ * Map a Figma text property to a string prop.
+ *
+ * @param figmaProperty - The name of the text property in Figma
+ * @returns A string mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   label: figma.string('Button Text'),
+ *   placeholder: figma.string('Placeholder'),
+ * }
+ * ```
+ */
+function string(figmaProperty: string): FigmaStringMapping {
+  return {
+    __type: 'figma-string',
+    figmaProperty,
+  };
+}
+
+/**
+ * Map a Figma boolean property to a boolean prop.
+ * Optionally map true/false to different values.
+ *
+ * @param figmaProperty - The name of the boolean property in Figma
+ * @param valueMapping - Optional mapping of true/false to other values
+ * @returns A boolean mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   disabled: figma.boolean('Disabled'),
+ *   // Map boolean to string values
+ *   size: figma.boolean('Large', { true: 'lg', false: 'md' }),
+ * }
+ * ```
+ */
+function boolean(
+  figmaProperty: string,
+  valueMapping?: { true: unknown; false: unknown }
+): FigmaBooleanMapping {
+  return {
+    __type: 'figma-boolean',
+    figmaProperty,
+    valueMapping,
+  };
+}
+
+/**
+ * Map a Figma variant property to an enum prop.
+ *
+ * @param figmaProperty - The name of the variant property in Figma
+ * @param valueMapping - Mapping of Figma values to code values
+ * @returns An enum mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   variant: figma.enum('Type', {
+ *     'Primary': 'primary',
+ *     'Secondary': 'secondary',
+ *     'Outline': 'outline',
+ *   }),
+ *   size: figma.enum('Size', {
+ *     'Small': 'sm',
+ *     'Medium': 'md',
+ *     'Large': 'lg',
+ *   }),
+ * }
+ * ```
+ */
+function enumValue<T extends Record<string, unknown>>(
+  figmaProperty: string,
+  valueMapping: T
+): FigmaEnumMapping {
+  return {
+    __type: 'figma-enum',
+    figmaProperty,
+    valueMapping,
+  };
+}
+
+/**
+ * Reference a nested Figma component instance.
+ * Use this when a prop accepts a component that's represented
+ * as an instance swap in Figma.
+ *
+ * @param figmaProperty - The name of the instance property in Figma
+ * @returns An instance mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   icon: figma.instance('Icon'),
+ *   avatar: figma.instance('Avatar'),
+ * }
+ * ```
+ */
+function instance(figmaProperty: string): FigmaInstanceMapping {
+  return {
+    __type: 'figma-instance',
+    figmaProperty,
+  };
+}
+
+/**
+ * Render children from specific Figma layers.
+ * Use this when children are represented as named layers in Figma.
+ *
+ * @param layers - Array of layer names to include as children
+ * @returns A children mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   children: figma.children(['Title', 'Description', 'Actions']),
+ * }
+ * ```
+ */
+function children(layers: string[]): FigmaChildrenMapping {
+  return {
+    __type: 'figma-children',
+    layers,
+  };
+}
+
+/**
+ * Extract text content from a Figma text layer.
+ * Use this when a prop should be the actual text from a layer.
+ *
+ * @param layer - The name of the text layer in Figma
+ * @returns A text content mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   title: figma.textContent('Header Text'),
+ *   description: figma.textContent('Body Text'),
+ * }
+ * ```
+ */
+function textContent(layer: string): FigmaTextContentMapping {
+  return {
+    __type: 'figma-text-content',
+    layer,
+  };
+}
+
+/**
+ * Figma property mapping helpers.
+ *
+ * Use these to define how Figma properties map to your component props.
+ * The mappings are used for:
+ * - Generating accurate code snippets in Figma Dev Mode
+ * - AI agents understanding the design-to-code relationship
+ * - Automated design verification
+ */
+export const figma = {
+  string,
+  boolean,
+  enum: enumValue,
+  instance,
+  children,
+  textContent,
+} as const;
+
+/**
+ * Helper type to check if a value is a Figma prop mapping
+ */
+export function isFigmaPropMapping(
+  value: unknown
+): value is FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping {
+  if (typeof value !== 'object' || value === null || !('__type' in value)) {
+    return false;
+  }
+  const typeValue = (value as Record<string, unknown>).__type;
+  return typeof typeValue === 'string' && typeValue.startsWith('figma-');
+}
+
+/**
+ * Resolve a Figma prop mapping to an actual value given Figma property values.
+ *
+ * @param mapping - The Figma prop mapping
+ * @param figmaValues - Object containing Figma property values
+ * @returns The resolved value for the code prop
+ */
+export function resolveFigmaMapping(
+  mapping: FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping,
+  figmaValues: Record<string, unknown>
+): unknown {
+  switch (mapping.__type) {
+    case 'figma-string':
+      return figmaValues[mapping.figmaProperty] ?? '';
+
+    case 'figma-boolean': {
+      const boolValue = figmaValues[mapping.figmaProperty] as boolean;
+      if (mapping.valueMapping) {
+        return boolValue ? mapping.valueMapping.true : mapping.valueMapping.false;
+      }
+      return boolValue;
+    }
+
+    case 'figma-enum': {
+      const enumKey = figmaValues[mapping.figmaProperty] as string;
+      return mapping.valueMapping[enumKey] ?? enumKey;
+    }
+
+    case 'figma-instance':
+      // Instance mappings return the instance reference
+      return figmaValues[mapping.figmaProperty];
+
+    case 'figma-children':
+      // Children mappings return array of layer contents
+      return mapping.layers.map((layer) => figmaValues[layer]);
+
+    case 'figma-text-content':
+      return figmaValues[mapping.layer] ?? '';
+
+    default:
+      return undefined;
+  }
+}

package/src/fragment-types.ts

@@ -0,0 +1,214 @@
+/**
+ * TypeScript types for Fragment JSON files.
+ * These types correspond to the JSON schemas in ./schema/
+ */
+
+/**
+ * Figma design links and mappings
+ */
+export interface FragmentFigma {
+  /** Figma file URL */
+  file?: string;
+  /** Default Figma node ID for this component */
+  nodeId?: string;
+  /** Mapping of variant names to Figma node IDs */
+  variants?: Record<string, string>;
+}
+
+/**
+ * Anti-pattern with optional alternative
+ */
+export interface FragmentDoNotItem {
+  /** What not to do */
+  text: string;
+  /** Component name to use instead */
+  instead?: string;
+}
+
+/**
+ * Usage pattern with code example
+ */
+export interface FragmentPattern {
+  /** Pattern name */
+  name: string;
+  /** Code example */
+  code: string;
+  /** When to use this pattern */
+  description?: string;
+}
+
+/**
+ * Usage guidelines for AI agents and developers
+ */
+export interface FragmentUsage {
+  /** Scenarios when this component should be used */
+  when?: string[];
+  /** Anti-patterns and what to use instead */
+  doNot?: (string | FragmentDoNotItem)[];
+  /** Common usage patterns with code examples */
+  patterns?: FragmentPattern[];
+}
+
+/**
+ * Accessibility requirements and guidelines
+ */
+export interface FragmentAccessibility {
+  /** ARIA role this component implements */
+  role?: string;
+  /** Accessibility requirements */
+  requirements?: string[];
+  /** Keyboard interaction patterns (key -> description) */
+  keyboard?: Record<string, string>;
+}
+
+/**
+ * Relationships to other components
+ */
+export interface FragmentRelated {
+  /** Similar components that might be alternatives */
+  similar?: string[];
+  /** Components commonly used together with this one */
+  composedWith?: string[];
+  /** Parent components or patterns where this is commonly used */
+  usedIn?: string[];
+}
+
+/**
+ * Administrative metadata
+ */
+export interface FragmentMeta {
+  /** Team or person responsible for this component */
+  owner?: string;
+  /** Component lifecycle status */
+  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
+  /** Version when this component was introduced */
+  since?: string;
+  /** Version when this component was deprecated */
+  deprecatedSince?: string;
+  /** Why this component was deprecated and what to use instead */
+  deprecatedReason?: string;
+  /** Tags for categorization and search */
+  tags?: string[];
+}
+
+/**
+ * Fragment JSON file structure (.fragment.json)
+ * Contains enrichment metadata for a component
+ */
+export interface Fragment {
+  /** JSON Schema reference */
+  $schema?: string;
+  /** Component name (must match the component export name) */
+  name: string;
+  /** Brief description of the component's purpose */
+  description?: string;
+  /** Figma design links and mappings */
+  figma?: FragmentFigma;
+  /** Usage guidelines for AI agents and developers */
+  usage?: FragmentUsage;
+  /** Accessibility requirements and guidelines */
+  accessibility?: FragmentAccessibility;
+  /** Relationships to other components */
+  related?: FragmentRelated;
+  /** Administrative metadata */
+  meta?: FragmentMeta;
+}
+
+/**
+ * Prop entry in the registry
+ */
+export interface RegistryPropEntry {
+  /** TypeScript type (e.g., 'string', 'boolean', enum values) */
+  type?: string;
+  /** Simplified type category */
+  typeKind?: "string" | "number" | "boolean" | "enum" | "object" | "array" | "function" | "node" | "element" | "union" | "unknown";
+  /** For enum types, the allowed values */
+  options?: string[];
+  /** Default value if specified */
+  default?: unknown;
+  /** Whether this prop is required */
+  required?: boolean;
+  /** Prop description from JSDoc or TypeScript */
+  description?: string;
+}
+
+/**
+ * Component entry in the registry (simplified - focuses on paths and enrichment)
+ */
+export interface RegistryComponentEntry {
+  /** Relative path to the component source file */
+  path: string;
+  /** Relative path to the .fragment.json file (if exists) */
+  fragmentPath?: string;
+  /** Relative path to the .stories.tsx file (if exists) */
+  storyPath?: string;
+  /** Component category (inferred from directory or fragment) */
+  category?: string;
+  /** Component lifecycle status (from fragment) */
+  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
+  /** Component description (from fragment or JSDoc) */
+  description?: string;
+  /** Has human-authored enrichment (fragment file exists with content beyond skeleton) */
+  hasEnrichment?: boolean;
+  /** Extracted prop definitions - only included if config.registry.includeProps is true */
+  props?: Record<string, RegistryPropEntry>;
+  /** Named exports from the component file */
+  exports?: string[];
+  /** Component dependencies (other components used) */
+  dependencies?: string[];
+  /** Merged fragment enrichment data - only included if config.registry.embedFragments is true */
+  fragment?: Fragment;
+}
+
+/**
+ * Minimal component index (.fragments/index.json)
+ * Ultra-light name → path mapping for quick lookups
+ */
+export interface FragmentIndex {
+  /** Schema version */
+  version: string;
+  /** When this index was generated */
+  generatedAt: string;
+  /** Simple name → path mapping */
+  components: Record<string, string>;
+  /** Categories for grouping */
+  categories?: Record<string, string[]>;
+}
+
+/**
+ * Registry file structure (.fragments/registry.json)
+ * Component index with resolved paths and optional metadata
+ */
+export interface FragmentRegistry {
+  /** JSON Schema reference */
+  $schema?: string;
+  /** Schema version */
+  version: string;
+  /** When this registry was generated */
+  generatedAt: string;
+  /** Component count for quick reference */
+  componentCount: number;
+  /** Component index keyed by component name */
+  components: Record<string, RegistryComponentEntry>;
+  /** Components grouped by category */
+  categories?: Record<string, string[]>;
+}
+
+/**
+ * Context file options for generation
+ */
+export interface FragmentContextOptions {
+  /** Output format */
+  format?: "markdown" | "json";
+  /** Compact mode - minimal output for token efficiency */
+  compact?: boolean;
+  /** What to include in the output */
+  include?: {
+    /** Include prop details (default: true) */
+    props?: boolean;
+    /** Include code examples (default: false) */
+    code?: boolean;
+    /** Include related components (default: true) */
+    relations?: boolean;
+  };
+}