@fragments-sdk/core 0.1.0

package/src/index.ts

@@ -0,0 +1,207 @@
+/**
+ * Browser-safe exports for @fragments-sdk/cli/core
+ * For Node.js-only APIs (config, discovery, loader), import from '@fragments-sdk/cli' directly.
+ */
+
+// Brand and default constants
+export { BRAND, DEFAULTS } from "./constants.js";
+export type { Brand, Defaults } from "./constants.js";
+
+// Types
+export type {
+  FragmentComponent,
+  FragmentMeta,
+  FragmentUsage,
+  PropType,
+  PropDefinition,
+  ControlType,
+  RelationshipType,
+  ComponentRelation,
+  VariantLoader,
+  PlayFunction,
+  PlayFunctionContext,
+  FragmentVariant,
+  FragmentDefinition,
+  FragmentsConfig,
+  SnippetPolicyConfig,
+  RegistryOptions,
+  CompiledFragment,
+  CompiledFragmentsFile,
+  BlockDefinition,
+  CompiledBlock,
+  RecipeDefinition, // @deprecated - use BlockDefinition
+  CompiledRecipe, // @deprecated - use CompiledBlock
+  // Contract and provenance types
+  FragmentContract,
+  FragmentGenerated,
+  // AI metadata type
+  AIMetadata,
+  // Screenshot types
+  ScreenshotConfig,
+  ServiceConfig,
+  Viewport,
+  Theme,
+  Screenshot,
+  ScreenshotMetadata,
+  DiffResult,
+  BoundingBox,
+  BaselineInfo,
+  Manifest,
+  VerifyRequest,
+  VerifyResult,
+  // Figma property mapping types
+  FigmaPropMapping,
+  FigmaStringMapping,
+  FigmaBooleanMapping,
+  FigmaEnumMapping,
+  FigmaInstanceMapping,
+  FigmaChildrenMapping,
+  FigmaTextContentMapping,
+  // Storybook filter configuration
+  StorybookFilterConfig,
+  // Token configuration
+  TokenConfig,
+  // Compiled token types
+  CompiledTokenEntry,
+  CompiledTokenData,
+} from "./types.js";
+
+// Performance presets
+export {
+  resolvePerformanceConfig,
+  classifyComplexity,
+  formatBytes,
+  budgetBar,
+  PRESET_NAMES,
+} from "./performance-presets.js";
+export type {
+  PerformanceBudgets,
+  PerformanceConfig,
+  ComplexityTier,
+  PerformanceData as PerfData,
+  PerformanceSummary as PerfSummary,
+} from "./performance-presets.js";
+
+// Token types
+export type {
+  TokenCategory,
+  DesignToken,
+  TokenRegistry,
+  TokenRegistryMeta,
+  EnhancedStyleDiffItem,
+  TokenFix,
+  TokenParseResult,
+  TokenParseError,
+  TokenMatchRequest,
+  TokenMatchResult,
+  TokenUsageSummary,
+} from "./token-types.js";
+
+// Schema validation (Zod is browser-safe)
+export {
+  fragmentMetaSchema,
+  fragmentUsageSchema,
+  propDefinitionSchema,
+  componentRelationSchema,
+  fragmentVariantSchema,
+  fragmentDefinitionSchema,
+  fragmentsConfigSchema,
+  figmaPropMappingSchema,
+  // Contract and provenance schemas
+  fragmentContractSchema,
+  fragmentGeneratedSchema,
+  fragmentBanSchema,
+  blockDefinitionSchema,
+  recipeDefinitionSchema, // @deprecated - use blockDefinitionSchema
+  // AI metadata schema
+  aiMetadataSchema,
+} from "./schema.js";
+
+// Main API
+export { defineFragment, compileFragment, defineBlock, compileBlock, defineRecipe, compileRecipe } from "./defineFragment.js";
+export type { InferProps } from "./defineFragment.js";
+
+// Story adapter (runtime conversion of Storybook modules)
+export {
+  storyModuleToFragment,
+  setPreviewConfig,
+  getPreviewConfig,
+  // Re-export @storybook/csf utilities
+  toId,
+  storyNameFromExport,
+  isExportStory,
+} from "./storyAdapter.js";
+export type {
+  StoryModule,
+  StoryMeta,
+  Story,
+  StoryArgType,
+  StoryContext,
+  Decorator,
+  Loader,
+  PreviewConfig,
+  CSF2Story,
+} from "./storyAdapter.js";
+
+// Storybook adapter filtering
+export {
+  checkStoryExclusion,
+  detectSubComponentPaths,
+  isForceIncluded,
+  isConfigExcluded,
+} from "./storyFilters.js";
+export type {
+  ExclusionReason,
+  ExclusionResult,
+  CheckStoryExclusionOpts,
+} from "./storyFilters.js";
+
+// Context generation for AI agents
+export { generateContext } from "./context.js";
+export type { ContextOptions, ContextResult } from "./context.js";
+
+// Figma property mapping DSL
+export { figma, isFigmaPropMapping, resolveFigmaMapping } from "./figma.js";
+
+// Fragment JSON types (for .fragment.json files)
+export type {
+  Fragment,
+  FragmentFigma,
+  FragmentUsage as FragmentJsonUsage,
+  FragmentDoNotItem,
+  FragmentPattern,
+  FragmentAccessibility,
+  FragmentRelated,
+  FragmentMeta as FragmentJsonMeta,
+  FragmentIndex,
+  FragmentRegistry,
+  RegistryComponentEntry,
+  RegistryPropEntry,
+  FragmentContextOptions,
+} from "./fragment-types.js";
+
+// Token parsing
+export { parseTokenFile } from "./token-parser.js";
+export type { ParsedToken, TokenParseOutput } from "./token-parser.js";
+
+// Composition analysis
+export { analyzeComposition } from "./composition.js";
+export type {
+  CompositionAnalysis,
+  CompositionWarning,
+  CompositionSuggestion,
+  CompositionGuideline,
+} from "./composition.js";
+
+// Shared preview runtime
+export {
+  executeVariantLoaders,
+  resolvePreviewRuntimeState,
+  usePreviewVariantRuntime,
+  PreviewVariantRuntime,
+} from "./preview-runtime.js";
+export type {
+  PreviewVariantLike,
+  PreviewRuntimeState,
+  PreviewRuntimeOptions,
+} from "./preview-runtime.js";

package/src/performance-presets.ts

@@ -0,0 +1,142 @@
+/**
+ * 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/preview-runtime.tsx

@@ -0,0 +1,144 @@
+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)}</>;
+}