@fragments-sdk/cli 0.2.2

package/dist/chunk-LY2CFFPY.js

@@ -0,0 +1,898 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+import {
+  recipeDefinitionSchema,
+  segmentDefinitionSchema
+} from "./chunk-XHNKNI6J.js";
+
+// src/core/defineSegment.ts
+function defineSegment(definition) {
+  if (process.env.NODE_ENV !== "production") {
+    const result = segmentDefinitionSchema.safeParse(definition);
+    if (!result.success) {
+      const errors = result.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+      throw new Error(
+        `Invalid segment definition for "${definition.meta?.name || "unknown"}":
+${errors}`
+      );
+    }
+  }
+  return definition;
+}
+var defineFragment = defineSegment;
+function compileSegment(definition, filePath) {
+  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
+  };
+}
+function defineRecipe(definition) {
+  if (process.env.NODE_ENV !== "production") {
+    const result = recipeDefinitionSchema.safeParse(definition);
+    if (!result.success) {
+      const errors = result.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+      throw new Error(
+        `Invalid recipe definition for "${definition.name || "unknown"}":
+${errors}`
+      );
+    }
+  }
+  return definition;
+}
+function compileRecipe(definition, filePath) {
+  return {
+    filePath,
+    name: definition.name,
+    description: definition.description,
+    category: definition.category,
+    components: definition.components,
+    code: definition.code,
+    tags: definition.tags
+  };
+}
+
+// src/core/storyAdapter.ts
+import { createElement } from "react";
+import { toId, storyNameFromExport, isExportStory } from "@storybook/csf";
+var globalPreviewConfig = {};
+function setPreviewConfig(config) {
+  globalPreviewConfig = config;
+}
+function getPreviewConfig() {
+  return globalPreviewConfig;
+}
+function storyModuleToSegment(storyModule, filePath) {
+  const meta = storyModule.default;
+  const component = meta.component;
+  if (!component) {
+    return null;
+  }
+  const componentName = extractComponentName(meta, filePath);
+  const category = extractCategory(meta.title);
+  const props = convertArgTypes(meta.argTypes ?? {}, globalPreviewConfig.argTypes);
+  const variants = extractVariants(storyModule, component, meta);
+  const figmaUrl = extractFigmaUrl(meta.parameters);
+  const segmentMeta = {
+    name: componentName,
+    description: meta.parameters?.docs?.description?.component ?? `${componentName} component`,
+    category,
+    tags: meta.tags?.filter((t) => t !== "autodocs"),
+    status: "stable",
+    figma: figmaUrl
+  };
+  const usage = {
+    when: [`Use ${componentName} for its intended purpose`],
+    whenNot: ["When a more specific component is available"]
+  };
+  return {
+    component,
+    meta: segmentMeta,
+    usage,
+    props,
+    variants
+  };
+}
+function extractComponentName(meta, filePath) {
+  if (meta.title) {
+    const parts = meta.title.split("/");
+    return parts[parts.length - 1];
+  }
+  if (meta.component?.displayName) {
+    return meta.component.displayName;
+  }
+  if (meta.component?.name && meta.component.name !== "Component") {
+    return meta.component.name;
+  }
+  const match = filePath.match(/([^/\\]+)\.stories\.(tsx?|jsx?)$/);
+  return match?.[1] ?? "Unknown";
+}
+function extractCategory(title) {
+  if (!title) return "general";
+  const parts = title.split("/");
+  if (parts.length >= 3) {
+    return parts[parts.length - 2].toLowerCase();
+  }
+  return "general";
+}
+function extractFigmaUrl(parameters) {
+  if (!parameters) return void 0;
+  const design = parameters.design;
+  if (design?.url && typeof design.url === "string") {
+    return design.url;
+  }
+  if (typeof parameters.figma === "string") {
+    return parameters.figma;
+  }
+  return void 0;
+}
+function convertArgTypes(argTypes, globalArgTypes) {
+  const props = {};
+  const mergedArgTypes = { ...globalArgTypes, ...argTypes };
+  for (const [name, argType] of Object.entries(mergedArgTypes)) {
+    if (argType.table?.disable) continue;
+    if (argType.control === false && argType.action) continue;
+    const { controlType, controlOptions } = extractControlInfo(argType);
+    props[name] = {
+      type: inferPropType(argType),
+      description: argType.description ?? `${name} prop`,
+      ...argType.options && { values: argType.options },
+      ...argType.table?.defaultValue && {
+        default: argType.table.defaultValue.summary
+      },
+      ...argType.defaultValue !== void 0 && {
+        default: argType.defaultValue
+      },
+      ...argType.type?.required && { required: true },
+      ...controlType && { controlType },
+      ...controlOptions && Object.keys(controlOptions).length > 0 && { controlOptions }
+    };
+  }
+  return props;
+}
+function extractControlInfo(argType) {
+  if (argType.control === void 0 || argType.control === false) {
+    return {};
+  }
+  const control = typeof argType.control === "string" ? { type: argType.control } : argType.control;
+  const validControlTypes = [
+    "text",
+    "number",
+    "range",
+    "boolean",
+    "select",
+    "multi-select",
+    "radio",
+    "inline-radio",
+    "check",
+    "inline-check",
+    "object",
+    "file",
+    "color",
+    "date"
+  ];
+  const controlType = validControlTypes.includes(control.type) ? control.type : void 0;
+  const controlOptions = {};
+  if (control.min !== void 0) controlOptions.min = control.min;
+  if (control.max !== void 0) controlOptions.max = control.max;
+  if (control.step !== void 0) controlOptions.step = control.step;
+  if (control.presetColors) controlOptions.presetColors = control.presetColors;
+  return {
+    controlType,
+    controlOptions: Object.keys(controlOptions).length > 0 ? controlOptions : void 0
+  };
+}
+function inferPropType(argType) {
+  if (argType.action) return "function";
+  if (argType.options?.length) return "enum";
+  if (argType.type?.name) {
+    const typeMap = {
+      string: "string",
+      number: "number",
+      boolean: "boolean",
+      object: "object",
+      array: "array",
+      function: "function"
+    };
+    const mapped = typeMap[argType.type.name];
+    if (mapped) return mapped;
+  }
+  const control = typeof argType.control === "string" ? argType.control : argType.control ? argType.control.type : void 0;
+  if (control) {
+    const controlMap = {
+      // Text controls
+      text: "string",
+      // Number controls
+      number: "number",
+      range: "number",
+      // Boolean controls
+      boolean: "boolean",
+      check: "boolean",
+      "inline-check": "boolean",
+      // Enum/selection controls
+      select: "enum",
+      "multi-select": "enum",
+      radio: "enum",
+      "inline-radio": "enum",
+      // Object controls
+      object: "object",
+      file: "object",
+      // Special string controls
+      color: "string",
+      date: "string"
+    };
+    const mapped = controlMap[control];
+    if (mapped) return mapped;
+  }
+  return "string";
+}
+function isStory(value) {
+  if (typeof value === "object" && value !== null) {
+    const obj = value;
+    if ("args" in obj || "render" in obj || "play" in obj) return true;
+  }
+  if (typeof value === "function") {
+    const fn = value;
+    if ("args" in fn) return true;
+  }
+  return false;
+}
+function extractVariants(storyModule, component, meta) {
+  const variants = [];
+  for (const [exportName, exportValue] of Object.entries(storyModule)) {
+    if (exportName === "default") continue;
+    if (!isExportStory(exportName, meta)) continue;
+    if (!isStory(exportValue)) continue;
+    const story = exportValue;
+    const storyName = typeof story === "object" && story.name || typeof story === "object" && story.storyName || typeof story === "function" && story.storyName || storyNameFromExport(exportName);
+    const storyId = toId(meta.title || "Unknown", exportName);
+    let description = `${storyName} variant`;
+    if (typeof story === "object" && story.parameters?.docs?.description?.story) {
+      description = story.parameters.docs.description.story;
+    }
+    const storyPlayFn = typeof story === "object" ? story.play : story.play;
+    const hasPlayFunction = !!storyPlayFn;
+    const wrappedPlay = storyPlayFn ? async (context) => {
+      const args = {
+        ...globalPreviewConfig.args,
+        ...meta.args,
+        ...typeof story === "function" ? story.args : story.args
+      };
+      const fullContext = buildStoryContext(meta, story, args, storyId, storyName);
+      const playContext = {
+        ...fullContext,
+        canvasElement: context.canvasElement,
+        args: context.args,
+        step: context.step
+      };
+      await storyPlayFn(playContext);
+    } : void 0;
+    const storyTags = typeof story === "object" ? story.tags : void 0;
+    const loaders = collectLoaders(meta, story);
+    const variantArgs = {
+      ...globalPreviewConfig.args,
+      ...meta.args,
+      ...typeof story === "function" ? story.args : story.args
+    };
+    const hasArgs = Object.keys(variantArgs).length > 0;
+    variants.push({
+      name: storyName,
+      description,
+      render: createRenderFunction(story, component, meta, storyId, storyName),
+      // Store Storybook-specific metadata
+      ...hasPlayFunction && { hasPlayFunction: true },
+      ...wrappedPlay && { play: wrappedPlay },
+      ...storyId && { storyId },
+      ...storyTags && { tags: storyTags },
+      ...loaders.length > 0 && { loaders },
+      ...hasArgs && { args: variantArgs }
+    });
+  }
+  return variants;
+}
+function collectLoaders(meta, story) {
+  const allLoaders = [
+    ...globalPreviewConfig.loaders ?? [],
+    ...meta.loaders ?? [],
+    ...typeof story === "function" ? story.loaders ?? [] : story.loaders ?? []
+  ];
+  if (allLoaders.length === 0) {
+    return [];
+  }
+  return allLoaders.map((loader) => {
+    return async () => {
+      const minimalContext = {
+        args: {},
+        argTypes: {},
+        globals: {},
+        parameters: {},
+        id: "",
+        kind: meta.title || "Unknown",
+        name: "",
+        story: "",
+        viewMode: "story",
+        loaded: {},
+        abortSignal: new AbortController().signal,
+        componentId: "",
+        title: meta.title || "Unknown"
+      };
+      return loader(minimalContext);
+    };
+  });
+}
+function buildStoryContext(meta, story, args, storyId, storyName, loadedData) {
+  const mergedArgs = {
+    ...globalPreviewConfig.args,
+    ...meta.args,
+    ...typeof story === "object" ? story.args : story.args,
+    ...args
+  };
+  const mergedArgTypes = {
+    ...globalPreviewConfig.argTypes,
+    ...meta.argTypes,
+    ...typeof story === "object" ? story.argTypes : story.argTypes
+  };
+  const mergedParameters = {
+    ...globalPreviewConfig.parameters,
+    ...meta.parameters,
+    ...typeof story === "object" ? story.parameters : story.parameters
+  };
+  return {
+    args: mergedArgs,
+    argTypes: mergedArgTypes ?? {},
+    globals: {},
+    parameters: mergedParameters ?? {},
+    id: storyId,
+    kind: meta.title || "Unknown",
+    name: storyName,
+    story: storyName,
+    viewMode: "story",
+    loaded: loadedData ?? {},
+    abortSignal: new AbortController().signal,
+    componentId: toId(meta.title || "Unknown", ""),
+    title: meta.title || "Unknown"
+  };
+}
+function createRenderFunction(story, component, meta, storyId, storyName) {
+  return (options) => {
+    const args = {
+      ...globalPreviewConfig.args,
+      ...meta.args,
+      ...typeof story === "function" ? story.args : story.args,
+      ...options?.args
+      // Runtime overrides from viewer props panel
+    };
+    const loadedData = options?.loadedData;
+    const context = buildStoryContext(meta, story, args, storyId, storyName, loadedData);
+    let renderFn;
+    if (typeof story === "function") {
+      renderFn = () => story(args);
+    } else if (story.render) {
+      renderFn = () => story.render.length >= 2 ? story.render(args, context) : story.render(args);
+    } else if (meta.render) {
+      renderFn = () => meta.render.length >= 2 ? meta.render(args, context) : meta.render(args);
+    } else {
+      renderFn = () => createElement(component, args);
+    }
+    const allDecorators = [
+      ...globalPreviewConfig.decorators ?? [],
+      ...meta.decorators ?? [],
+      ...typeof story === "function" ? story.decorators ?? [] : story.decorators ?? []
+    ].reverse();
+    if (allDecorators.length > 0) {
+      return applyDecorators(renderFn, allDecorators, context);
+    }
+    return renderFn();
+  };
+}
+function applyDecorators(renderFn, decorators, context) {
+  let storyFn = renderFn;
+  for (const decorator of decorators) {
+    const wrappedFn = storyFn;
+    storyFn = () => decorator(wrappedFn, context);
+  }
+  return storyFn();
+}
+
+// src/core/context.ts
+var PLACEHOLDER_PATTERNS = [
+  /^\w+ component is needed$/i,
+  /^Alternative component is more appropriate$/i,
+  /^Use \w+ when you need/i
+];
+function filterPlaceholders(items) {
+  return items.filter(
+    (item) => !PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(item.trim()))
+  );
+}
+function generateContext(segments, options = {}, recipes) {
+  const format = options.format ?? "markdown";
+  const compact = options.compact ?? false;
+  const include = {
+    props: options.include?.props ?? true,
+    variants: options.include?.variants ?? true,
+    usage: options.include?.usage ?? true,
+    relations: options.include?.relations ?? false,
+    code: options.include?.code ?? false
+  };
+  const sorted = [...segments].sort((a, b) => {
+    const catCompare = a.meta.category.localeCompare(b.meta.category);
+    if (catCompare !== 0) return catCompare;
+    return a.meta.name.localeCompare(b.meta.name);
+  });
+  if (format === "json") {
+    return generateJsonContext(sorted, include, compact, recipes);
+  }
+  return generateMarkdownContext(sorted, include, compact, recipes);
+}
+function generateMarkdownContext(segments, include, compact, recipes) {
+  const lines = [];
+  lines.push("# Design System Reference");
+  lines.push("");
+  lines.push("## Quick Reference");
+  lines.push("");
+  lines.push("| Component | Category | Use For |");
+  lines.push("|-----------|----------|---------|");
+  for (const segment of segments) {
+    const filteredWhen = filterPlaceholders(segment.usage.when);
+    const useFor = filteredWhen.slice(0, 2).join(", ") || segment.meta.description;
+    lines.push(`| ${segment.meta.name} | ${segment.meta.category} | ${truncate(useFor, 50)} |`);
+  }
+  lines.push("");
+  if (compact) {
+    const content2 = lines.join("\n");
+    return {
+      content: content2,
+      tokenEstimate: estimateTokens(content2)
+    };
+  }
+  lines.push("## Components");
+  lines.push("");
+  for (const segment of segments) {
+    lines.push(`### ${segment.meta.name}`);
+    lines.push("");
+    const statusParts = [`**Category:** ${segment.meta.category}`];
+    if (segment.meta.status) {
+      statusParts.push(`**Status:** ${segment.meta.status}`);
+    }
+    lines.push(statusParts.join(" | "));
+    lines.push("");
+    if (segment.meta.description) {
+      lines.push(segment.meta.description);
+      lines.push("");
+    }
+    const whenFiltered = filterPlaceholders(segment.usage.when);
+    const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
+    if (include.usage && (whenFiltered.length > 0 || whenNotFiltered.length > 0)) {
+      if (whenFiltered.length > 0) {
+        lines.push("**When to use:**");
+        for (const when of whenFiltered) {
+          lines.push(`- ${when}`);
+        }
+        lines.push("");
+      }
+      if (whenNotFiltered.length > 0) {
+        lines.push("**When NOT to use:**");
+        for (const whenNot of whenNotFiltered) {
+          lines.push(`- ${whenNot}`);
+        }
+        lines.push("");
+      }
+    }
+    if (include.props && Object.keys(segment.props).length > 0) {
+      lines.push("**Props:**");
+      for (const [name, prop] of Object.entries(segment.props)) {
+        lines.push(`- \`${name}\`: ${formatPropType(prop)}${prop.required ? " (required)" : ""}`);
+      }
+      lines.push("");
+    }
+    if (include.variants && segment.variants.length > 0) {
+      const variantNames = segment.variants.map((v) => v.name).join(", ");
+      lines.push(`**Variants:** ${variantNames}`);
+      lines.push("");
+      if (include.code) {
+        for (const variant of segment.variants) {
+          if (variant.code) {
+            lines.push(`*${variant.name}:*`);
+            lines.push("```tsx");
+            lines.push(variant.code);
+            lines.push("```");
+            lines.push("");
+          }
+        }
+      }
+    }
+    if (include.relations && segment.relations && segment.relations.length > 0) {
+      lines.push("**Related:**");
+      for (const relation of segment.relations) {
+        lines.push(`- ${relation.component} (${relation.relationship}): ${relation.note}`);
+      }
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("");
+  }
+  if (recipes && recipes.length > 0) {
+    lines.push("## Recipes");
+    lines.push("");
+    lines.push("Composition patterns showing how components wire together.");
+    lines.push("");
+    for (const recipe of recipes) {
+      lines.push(`### ${recipe.name}`);
+      lines.push("");
+      lines.push(recipe.description);
+      lines.push("");
+      lines.push(`**Category:** ${recipe.category}`);
+      lines.push(`**Components:** ${recipe.components.join(", ")}`);
+      if (recipe.tags && recipe.tags.length > 0) {
+        lines.push(`**Tags:** ${recipe.tags.join(", ")}`);
+      }
+      lines.push("");
+      lines.push("```tsx");
+      lines.push(recipe.code);
+      lines.push("```");
+      lines.push("");
+      lines.push("---");
+      lines.push("");
+    }
+  }
+  const content = lines.join("\n");
+  return {
+    content,
+    tokenEstimate: estimateTokens(content)
+  };
+}
+function generateJsonContext(segments, include, compact, recipes) {
+  const categories = [...new Set(segments.map((s) => s.meta.category))].sort();
+  const components = {};
+  for (const segment of segments) {
+    const component = {
+      category: segment.meta.category,
+      description: segment.meta.description
+    };
+    if (segment.meta.status) {
+      component.status = segment.meta.status;
+    }
+    if (!compact) {
+      if (include.usage) {
+        const whenFiltered = filterPlaceholders(segment.usage.when);
+        const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
+        if (whenFiltered.length > 0) {
+          component.whenToUse = whenFiltered;
+        }
+        if (whenNotFiltered.length > 0) {
+          component.whenNotToUse = whenNotFiltered;
+        }
+      }
+      if (include.props && Object.keys(segment.props).length > 0) {
+        component.props = {};
+        for (const [name, prop] of Object.entries(segment.props)) {
+          component.props[name] = {
+            type: formatPropType(prop),
+            description: prop.description
+          };
+          if (prop.required) {
+            component.props[name].required = true;
+          }
+          if (prop.default !== void 0) {
+            component.props[name].default = prop.default;
+          }
+        }
+      }
+      if (include.variants && segment.variants.length > 0) {
+        component.variants = segment.variants.map((v) => v.name);
+      }
+      if (include.relations && segment.relations && segment.relations.length > 0) {
+        component.relations = segment.relations.map((r) => ({
+          component: r.component,
+          relationship: r.relationship,
+          note: r.note
+        }));
+      }
+    }
+    components[segment.meta.name] = component;
+  }
+  const recipesMap = recipes && recipes.length > 0 ? Object.fromEntries(recipes.map((r) => [r.name, {
+    description: r.description,
+    category: r.category,
+    components: r.components,
+    code: r.code,
+    tags: r.tags
+  }])) : void 0;
+  const output = {
+    version: "1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: {
+      totalComponents: segments.length,
+      categories,
+      ...recipesMap && { totalRecipes: recipes.length }
+    },
+    components,
+    ...recipesMap && { recipes: recipesMap }
+  };
+  const content = JSON.stringify(output, null, 2);
+  return {
+    content,
+    tokenEstimate: estimateTokens(content)
+  };
+}
+function formatPropType(prop) {
+  if (prop.type === "enum" && prop.values) {
+    return prop.values.map((v) => `"${v}"`).join(" | ");
+  }
+  if (prop.default !== void 0) {
+    return `${prop.type} (default: ${JSON.stringify(prop.default)})`;
+  }
+  return prop.type;
+}
+function truncate(str, maxLength) {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + "...";
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+// src/core/figma.ts
+function string(figmaProperty) {
+  return {
+    __type: "figma-string",
+    figmaProperty
+  };
+}
+function boolean(figmaProperty, valueMapping) {
+  return {
+    __type: "figma-boolean",
+    figmaProperty,
+    valueMapping
+  };
+}
+function enumValue(figmaProperty, valueMapping) {
+  return {
+    __type: "figma-enum",
+    figmaProperty,
+    valueMapping
+  };
+}
+function instance(figmaProperty) {
+  return {
+    __type: "figma-instance",
+    figmaProperty
+  };
+}
+function children(layers) {
+  return {
+    __type: "figma-children",
+    layers
+  };
+}
+function textContent(layer) {
+  return {
+    __type: "figma-text-content",
+    layer
+  };
+}
+var figma = {
+  string,
+  boolean,
+  enum: enumValue,
+  instance,
+  children,
+  textContent
+};
+function isFigmaPropMapping(value) {
+  if (typeof value !== "object" || value === null || !("__type" in value)) {
+    return false;
+  }
+  const typeValue = value.__type;
+  return typeof typeValue === "string" && typeValue.startsWith("figma-");
+}
+function resolveFigmaMapping(mapping, figmaValues) {
+  switch (mapping.__type) {
+    case "figma-string":
+      return figmaValues[mapping.figmaProperty] ?? "";
+    case "figma-boolean": {
+      const boolValue = figmaValues[mapping.figmaProperty];
+      if (mapping.valueMapping) {
+        return boolValue ? mapping.valueMapping.true : mapping.valueMapping.false;
+      }
+      return boolValue;
+    }
+    case "figma-enum": {
+      const enumKey = figmaValues[mapping.figmaProperty];
+      return mapping.valueMapping[enumKey] ?? enumKey;
+    }
+    case "figma-instance":
+      return figmaValues[mapping.figmaProperty];
+    case "figma-children":
+      return mapping.layers.map((layer) => figmaValues[layer]);
+    case "figma-text-content":
+      return figmaValues[mapping.layer] ?? "";
+    default:
+      return void 0;
+  }
+}
+
+// src/core/composition.ts
+var CATEGORY_AFFINITIES = {
+  forms: ["feedback"],
+  actions: ["feedback"]
+};
+function analyzeComposition(segments, componentNames, _context) {
+  const allNames = new Set(Object.keys(segments));
+  const components = [];
+  const unknown = [];
+  for (const name of componentNames) {
+    if (allNames.has(name)) {
+      components.push(name);
+    } else {
+      unknown.push(name);
+    }
+  }
+  const selectedSet = new Set(components);
+  const warnings = [];
+  const suggestions = [];
+  const guidelines = [];
+  const suggestedSet = /* @__PURE__ */ new Set();
+  for (const name of components) {
+    const segment = segments[name];
+    if (segment.relations) {
+      for (const rel of segment.relations) {
+        switch (rel.relationship) {
+          case "parent":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_parent",
+                component: name,
+                message: `"${name}" expects to be wrapped by "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component
+              });
+            }
+            break;
+          case "child":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${name}" typically contains "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "child",
+                sourceComponent: name
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+          case "composition":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_composition",
+                component: name,
+                message: `"${name}" is typically used together with "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component
+              });
+            }
+            break;
+          case "sibling":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${rel.component}" is a sibling of "${name}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "sibling",
+                sourceComponent: name
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+          case "alternative":
+            if (selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "redundant_alternative",
+                component: name,
+                message: `"${name}" and "${rel.component}" are alternatives \u2014 using both may be redundant${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component
+              });
+            }
+            break;
+        }
+      }
+    }
+    if (segment.usage?.whenNot) {
+      for (const whenNotEntry of segment.usage.whenNot) {
+        const lower = whenNotEntry.toLowerCase();
+        for (const other of components) {
+          if (other !== name && lower.includes(other.toLowerCase())) {
+            guidelines.push({
+              component: name,
+              guideline: `Potential conflict with "${other}": ${whenNotEntry}`
+            });
+          }
+        }
+      }
+    }
+    if (segment.meta.status === "deprecated") {
+      warnings.push({
+        type: "deprecated",
+        component: name,
+        message: segment.meta.description ? `"${name}" is deprecated: ${segment.meta.description}` : `"${name}" is deprecated`
+      });
+    } else if (segment.meta.status === "experimental") {
+      warnings.push({
+        type: "experimental",
+        component: name,
+        message: `"${name}" is experimental and may change without notice`
+      });
+    }
+  }
+  const selectedCategories = new Set(
+    components.map((name) => segments[name].meta.category)
+  );
+  for (const [category, affinities] of Object.entries(CATEGORY_AFFINITIES)) {
+    if (!selectedCategories.has(category)) continue;
+    for (const neededCategory of affinities) {
+      if (selectedCategories.has(neededCategory)) continue;
+      const candidate = findBestCategoryCandidate(
+        segments,
+        neededCategory,
+        selectedSet,
+        suggestedSet
+      );
+      if (candidate) {
+        suggestions.push({
+          component: candidate,
+          reason: `Compositions using "${category}" components often benefit from a "${neededCategory}" component`,
+          relationship: "category_gap",
+          sourceComponent: components.find(
+            (n) => segments[n].meta.category === category
+          )
+        });
+        suggestedSet.add(candidate);
+      }
+    }
+  }
+  return { components, unknown, warnings, suggestions, guidelines };
+}
+function findBestCategoryCandidate(segments, category, selectedSet, suggestedSet) {
+  let best = null;
+  let bestScore = -1;
+  for (const [name, segment] of Object.entries(segments)) {
+    if (segment.meta.category !== category) continue;
+    if (selectedSet.has(name) || suggestedSet.has(name)) continue;
+    const status = segment.meta.status ?? "stable";
+    let score = 0;
+    if (status === "stable") score = 3;
+    else if (status === "beta") score = 2;
+    else if (status === "experimental") score = 1;
+    if (score > bestScore) {
+      bestScore = score;
+      best = name;
+    }
+  }
+  return best;
+}
+
+export {
+  defineSegment,
+  defineFragment,
+  compileSegment,
+  defineRecipe,
+  compileRecipe,
+  toId,
+  storyNameFromExport,
+  isExportStory,
+  setPreviewConfig,
+  getPreviewConfig,
+  storyModuleToSegment,
+  generateContext,
+  figma,
+  isFigmaPropMapping,
+  resolveFigmaMapping,
+  analyzeComposition
+};
+//# sourceMappingURL=chunk-LY2CFFPY.js.map