@fragments-sdk/cli 0.9.1 → 0.10.0

package/src/core/performance-presets.ts

@@ -1,142 +0,0 @@
-/**
- * Performance budget presets and classification utilities.
- *
- * ESLint model: global defaults, zero-config, auto-measurement.
- * Users configure 0-3 numbers. Per-component overrides are the `eslint-disable` equivalent.
- */
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface PerformanceBudgets {
-  /** Maximum gzipped bundle size in bytes */
-  bundleSize: number;
-}
-
-export interface PerformanceConfig {
-  preset: string;
-  budgets: PerformanceBudgets;
-}
-
-export type ComplexityTier = 'lightweight' | 'moderate' | 'heavy';
-
-export interface PerformanceData {
-  /** Gzipped bundle size in bytes */
-  bundleSize: number;
-  /** Raw (minified, not gzipped) bundle size in bytes */
-  rawSize: number;
-  /** Complexity classification */
-  complexity: ComplexityTier;
-  /** Percentage of budget used (0-100+) */
-  budgetPercent: number;
-  /** Whether the component exceeds its budget */
-  overBudget: boolean;
-  /** ISO timestamp when measured */
-  measuredAt: string;
-}
-
-export interface PerformanceSummary {
-  /** Preset name used */
-  preset: string;
-  /** Budget applied in bytes */
-  budget: number;
-  /** Total components measured */
-  total: number;
-  /** Number of components over budget */
-  overBudget: number;
-  /** Distribution by tier */
-  tiers: Record<ComplexityTier, number>;
-}
-
-// ---------------------------------------------------------------------------
-// Presets
-// ---------------------------------------------------------------------------
-
-const PRESETS: Record<string, PerformanceBudgets> = {
-  strict: { bundleSize: 8 * 1024 },     // 8KB gzipped
-  standard: { bundleSize: 15 * 1024 },   // 15KB gzipped
-  relaxed: { bundleSize: 30 * 1024 },    // 30KB gzipped
-};
-
-export const PRESET_NAMES = Object.keys(PRESETS) as readonly string[];
-
-// ---------------------------------------------------------------------------
-// Resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve a performance config from user input.
- * Accepts a preset name string or a custom config object.
- */
-export function resolvePerformanceConfig(
-  input: string | { preset?: string; budgets?: Partial<PerformanceBudgets> } | undefined
-): PerformanceConfig {
-  if (!input) {
-    return { preset: 'standard', budgets: PRESETS.standard };
-  }
-
-  if (typeof input === 'string') {
-    const budgets = PRESETS[input];
-    if (!budgets) {
-      throw new Error(
-        `Unknown performance preset "${input}". Available: ${PRESET_NAMES.join(', ')}`
-      );
-    }
-    return { preset: input, budgets };
-  }
-
-  const presetName = input.preset ?? 'standard';
-  const baseBudgets = PRESETS[presetName];
-  if (!baseBudgets) {
-    throw new Error(
-      `Unknown performance preset "${presetName}". Available: ${PRESET_NAMES.join(', ')}`
-    );
-  }
-
-  return {
-    preset: presetName,
-    budgets: {
-      bundleSize: input.budgets?.bundleSize ?? baseBudgets.bundleSize,
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Classification
-// ---------------------------------------------------------------------------
-
-/**
- * Classify a component's complexity based on gzipped bundle size.
- *
- * - lightweight: < 5KB — simple, leaf components
- * - moderate: < 15KB — typical composed components
- * - heavy: >= 15KB — complex widgets with dependencies
- */
-export function classifyComplexity(gzipBytes: number): ComplexityTier {
-  if (gzipBytes < 5 * 1024) return 'lightweight';
-  if (gzipBytes < 15 * 1024) return 'moderate';
-  return 'heavy';
-}
-
-// ---------------------------------------------------------------------------
-// Formatting helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Format bytes to a human-readable string (e.g. "2.1KB", "15.3KB").
- */
-export function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes}B`;
-  const kb = bytes / 1024;
-  return kb < 10 ? `${kb.toFixed(1)}KB` : `${Math.round(kb)}KB`;
-}
-
-/**
- * Create a visual budget bar for terminal output.
- */
-export function budgetBar(percent: number, width = 20): string {
-  const filled = Math.min(Math.round((percent / 100) * width), width);
-  const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
-  return percent > 100 ? `\x1b[31m${bar}\x1b[0m` : `\x1b[32m${bar}\x1b[0m`;
-}

package/src/core/preview-runtime.tsx

@@ -1,144 +0,0 @@
-import { useEffect, useState, type ReactNode } from "react";
-import type { VariantLoader, VariantRenderOptions } from "./types.js";
-
-/**
- * Minimal contract for rendering a preview variant.
- * Compatible with fragment variants and Storybook-adapted variants.
- */
-export interface PreviewVariantLike {
-  render: (options?: VariantRenderOptions) => ReactNode;
-  loaders?: VariantLoader[];
-}
-
-export interface PreviewRuntimeState {
-  content: ReactNode | null;
-  isLoading: boolean;
-  error: Error | null;
-  loadedData?: Record<string, unknown>;
-}
-
-export interface PreviewRuntimeOptions {
-  variant?: PreviewVariantLike | null;
-  loadedData?: Record<string, unknown>;
-}
-
-const EMPTY_STATE: PreviewRuntimeState = {
-  content: null,
-  isLoading: false,
-  error: null,
-  loadedData: undefined,
-};
-
-function toError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-/**
- * Execute all variant loaders and merge their payloads.
- * `loadedData` is applied last so host-level overrides win.
- */
-export async function executeVariantLoaders(
-  loaders: VariantLoader[] | undefined,
-  loadedData?: Record<string, unknown>,
-): Promise<Record<string, unknown> | undefined> {
-  const hasLoaders = !!loaders && loaders.length > 0;
-  if (!hasLoaders) {
-    return loadedData;
-  }
-
-  const results = await Promise.all(loaders.map((loader) => loader()));
-  const mergedFromLoaders = results.reduce<Record<string, unknown>>(
-    (acc, result) => ({ ...acc, ...result }),
-    {},
-  );
-
-  return loadedData ? { ...mergedFromLoaders, ...loadedData } : mergedFromLoaders;
-}
-
-/**
- * Resolve a full runtime state (loader execution + render) in one async call.
- * This is useful for testing and for hook/component orchestration.
- */
-export async function resolvePreviewRuntimeState(
-  options: PreviewRuntimeOptions,
-): Promise<PreviewRuntimeState> {
-  const { variant, loadedData } = options;
-  if (!variant) {
-    return EMPTY_STATE;
-  }
-
-  try {
-    const mergedLoadedData = await executeVariantLoaders(variant.loaders, loadedData);
-    const content = variant.render({ loadedData: mergedLoadedData });
-    return {
-      content,
-      isLoading: false,
-      error: null,
-      loadedData: mergedLoadedData,
-    };
-  } catch (error) {
-    return {
-      content: null,
-      isLoading: false,
-      error: toError(error),
-      loadedData: undefined,
-    };
-  }
-}
-
-/**
- * Hook for rendering a preview variant with loader support.
- */
-export function usePreviewVariantRuntime(
-  options: PreviewRuntimeOptions,
-): PreviewRuntimeState {
-  const { variant, loadedData } = options;
-  const [state, setState] = useState<PreviewRuntimeState>(EMPTY_STATE);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    if (!variant) {
-      setState(EMPTY_STATE);
-      return () => {
-        cancelled = true;
-      };
-    }
-
-    const hasLoaders = !!variant.loaders && variant.loaders.length > 0;
-    setState({
-      content: null,
-      isLoading: hasLoaders,
-      error: null,
-      loadedData: undefined,
-    });
-
-    resolvePreviewRuntimeState({ variant, loadedData }).then((nextState) => {
-      if (!cancelled) {
-        setState(nextState);
-      }
-    });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [variant, loadedData]);
-
-  return state;
-}
-
-interface PreviewVariantRuntimeProps extends PreviewRuntimeOptions {
-  children: (state: PreviewRuntimeState) => ReactNode;
-}
-
-/**
- * Render-prop component wrapper around `usePreviewVariantRuntime`.
- */
-export function PreviewVariantRuntime({
-  variant,
-  loadedData,
-  children,
-}: PreviewVariantRuntimeProps) {
-  const state = usePreviewVariantRuntime({ variant, loadedData });
-  return <>{children(state)}</>;
-}

package/src/core/schema.ts

@@ -1,229 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Zod schemas for runtime validation of fragment definitions
- */
-
-// Figma property mapping schemas
-const figmaStringMappingSchema = z.object({
-  __type: z.literal('figma-string'),
-  figmaProperty: z.string().min(1),
-});
-
-const figmaBooleanMappingSchema = z.object({
-  __type: z.literal('figma-boolean'),
-  figmaProperty: z.string().min(1),
-  valueMapping: z.object({ true: z.unknown(), false: z.unknown() }).optional(),
-});
-
-const figmaEnumMappingSchema = z.object({
-  __type: z.literal('figma-enum'),
-  figmaProperty: z.string().min(1),
-  valueMapping: z.record(z.unknown()),
-});
-
-const figmaInstanceMappingSchema = z.object({
-  __type: z.literal('figma-instance'),
-  figmaProperty: z.string().min(1),
-});
-
-const figmaChildrenMappingSchema = z.object({
-  __type: z.literal('figma-children'),
-  layers: z.array(z.string().min(1)),
-});
-
-const figmaTextContentMappingSchema = z.object({
-  __type: z.literal('figma-text-content'),
-  layer: z.string().min(1),
-});
-
-export const figmaPropMappingSchema = z.discriminatedUnion('__type', [
-  figmaStringMappingSchema,
-  figmaBooleanMappingSchema,
-  figmaEnumMappingSchema,
-  figmaInstanceMappingSchema,
-  figmaChildrenMappingSchema,
-  figmaTextContentMappingSchema,
-]);
-
-export const fragmentMetaSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().min(1),
-  category: z.string().min(1),
-  tags: z.array(z.string()).optional(),
-  status: z.enum(['stable', 'beta', 'deprecated', 'experimental']).optional(),
-  since: z.string().optional(),
-  dependencies: z.array(z.object({
-    name: z.string().min(1),
-    version: z.string().min(1),
-    reason: z.string().optional(),
-  })).optional(),
-  figma: z.string().url().optional(),
-  figmaProps: z.record(figmaPropMappingSchema).optional(),
-});
-
-export const fragmentUsageSchema = z.object({
-  when: z.array(z.string()),
-  whenNot: z.array(z.string()),
-  guidelines: z.array(z.string()).optional(),
-  accessibility: z.array(z.string()).optional(),
-});
-
-export const propTypeSchema: z.ZodType<string> = z.enum([
-  'string',
-  'number',
-  'boolean',
-  'enum',
-  'function',
-  'node',
-  'element',
-  'object',
-  'array',
-  'union',
-  'custom',
-]);
-
-export const propDefinitionSchema = z.object({
-  type: propTypeSchema,
-  values: z.array(z.string()).readonly().optional(),
-  default: z.unknown().optional(),
-  description: z.string().optional(),
-  required: z.boolean().optional(),
-  constraints: z.array(z.string()).optional(),
-  typeDetails: z.record(z.unknown()).optional(),
-});
-
-export const relationshipTypeSchema = z.enum([
-  'alternative',
-  'sibling',
-  'parent',
-  'child',
-  'composition',
-  'complementary',
-  'used-by',
-]);
-
-export const componentRelationSchema = z.object({
-  component: z.string().min(1),
-  relationship: relationshipTypeSchema,
-  note: z.string().min(1),
-});
-
-export const fragmentVariantSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().min(1),
-  render: z.function().returns(z.unknown()),
-  code: z.string().optional(),
-  figma: z.string().url().optional(),
-});
-
-/**
- * Schema for banned patterns in codebase
- */
-export const fragmentBanSchema = z.object({
-  pattern: z.string().min(1),
-  message: z.string().min(1),
-});
-
-/**
- * Schema for agent-optimized contract metadata
- */
-export const fragmentContractSchema = z.object({
-  propsSummary: z.array(z.string()).optional(),
-  a11yRules: z.array(z.string()).optional(),
-  bans: z.array(fragmentBanSchema).optional(),
-  scenarioTags: z.array(z.string()).optional(),
-  performanceBudget: z.number().positive().optional(),
-});
-
-/**
- * Schema for provenance tracking of generated fragments
- */
-export const fragmentGeneratedSchema = z.object({
-  source: z.enum(['storybook', 'manual', 'ai']),
-  sourceFile: z.string().optional(),
-  confidence: z.number().min(0).max(1).optional(),
-  timestamp: z.string().datetime().optional(),
-});
-
-/**
- * Schema for AI-specific metadata for playground context generation
- */
-export const aiMetadataSchema = z.object({
-  compositionPattern: z.enum(['compound', 'simple', 'controlled', 'wrapper']).optional(),
-  subComponents: z.array(z.string()).optional(),
-  requiredChildren: z.array(z.string()).optional(),
-  commonPatterns: z.array(z.string()).optional(),
-});
-
-/**
- * Schema for block definitions
- */
-export const blockDefinitionSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().min(1),
-  category: z.string().min(1),
-  components: z.array(z.string().min(1)).min(1),
-  code: z.string().min(1),
-  tags: z.array(z.string()).optional(),
-});
-
-export const fragmentDefinitionSchema = z.object({
-  component: z.any(), // Allow any component type (function, class, forwardRef, etc.)
-  meta: fragmentMetaSchema,
-  usage: fragmentUsageSchema,
-  props: z.record(propDefinitionSchema),
-  relations: z.array(componentRelationSchema).optional(),
-  variants: z.array(fragmentVariantSchema), // Allow empty variants array
-  contract: fragmentContractSchema.optional(),
-  ai: aiMetadataSchema.optional(),
-  _generated: fragmentGeneratedSchema.optional(),
-});
-
-/**
- * Config schema - validates required fields, passes through optional config objects.
- * Type definitions are in types.ts - schema just ensures basic structure.
- */
-export const fragmentsConfigSchema = z.object({
-  include: z.array(z.string()).min(1),
-  exclude: z.array(z.string()).optional(),
-  components: z.array(z.string()).optional(),
-  outFile: z.string().optional(),
-  framework: z.enum(['react', 'vue', 'svelte']).optional(),
-  figmaFile: z.string().url().optional(),
-  figmaToken: z.string().optional(),
-  screenshots: z.object({}).passthrough().optional(),
-  service: z.object({}).passthrough().optional(),
-  registry: z.object({}).passthrough().optional(),
-  tokens: z.object({
-    include: z.array(z.string()).min(1),
-  }).passthrough().optional(),
-  snippets: z.object({
-    mode: z.enum(['warn', 'error']).optional(),
-    scope: z.enum(['snippet', 'snippet+render']).optional(),
-    requireFullSnippet: z.boolean().optional(),
-    allowedExternalModules: z.array(z.string().min(1)).optional(),
-  }).optional(),
-  performance: z.union([
-    z.enum(['strict', 'standard', 'relaxed']),
-    z.object({
-      preset: z.enum(['strict', 'standard', 'relaxed']).optional(),
-      budgets: z.object({
-        bundleSize: z.number().positive().optional(),
-      }).optional(),
-    }),
-  ]).optional(),
-  storybook: z.object({
-    exclude: z.array(z.string()).optional(),
-    include: z.array(z.string()).optional(),
-    excludeDeprecated: z.boolean().optional(),
-    excludeTests: z.boolean().optional(),
-    excludeSvgIcons: z.boolean().optional(),
-    excludeSubComponents: z.boolean().optional(),
-  }).optional(),
-});
-
-/**
- * @deprecated Use blockDefinitionSchema instead
- */
-export const recipeDefinitionSchema = blockDefinitionSchema;