@fragments-sdk/ui 0.17.0 → 0.18.0

package/src/components/Listbox/Listbox.contract.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Listbox",
+  "description": "Controlled listbox for search results, autocomplete dropdowns, and command menus. Provides Menu-like styling without requiring a trigger.",
+  "category": "forms",
+  "tags": [
+    "listbox",
+    "search",
+    "autocomplete",
+    "combobox",
+    "command",
+    "dropdown"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Listbox/index.tsx",
+  "exportName": "Listbox",
+  "propsSummary": [
+    "children: node (required)",
+    "style: object",
+    "tabIndex: number",
+    "onFocus: function",
+    "onKeyDown: function"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Listbox.Item, Listbox.Group, or Listbox.Empty components",
+      "required": true
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    },
+    "tabIndex": {
+      "type": "number",
+      "description": "",
+      "required": false
+    },
+    "onFocus": {
+      "type": "function",
+      "description": "",
+      "required": false
+    },
+    "onKeyDown": {
+      "type": "function",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Search result dropdowns",
+      "Autocomplete suggestions",
+      "Command palette results",
+      "Keyboard-navigable option lists"
+    ],
+    "whenNot": [
+      "Static lists without selection (use List)",
+      "Action menus with trigger button (use Menu)",
+      "Form field selection (use Select)",
+      "Navigation menus (use Sidebar or Tabs)"
+    ],
+    "guidelines": [
+      "Control open/close state externally based on input focus or query",
+      "Listbox provides arrow/home/end + Enter/Space keyboard navigation when focused",
+      "Use Listbox.Empty for no results state",
+      "Group related items with Listbox.Group when appropriate"
+    ],
+    "accessibility": [
+      "Uses listbox and option ARIA roles",
+      "aria-selected indicates current selection",
+      "aria-disabled for non-interactive items",
+      "Connect to input with aria-controls for full combobox pattern"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic listbox with selectable items",
+      "code": "<Listbox aria-label=\"Options\">\n  <Listbox.Item selected>First option</Listbox.Item>\n  <Listbox.Item>Second option</Listbox.Item>\n  <Listbox.Item>Third option</Listbox.Item>\n</Listbox>"
+    },
+    {
+      "name": "Search Results",
+      "description": "Typical search results pattern with label and metadata",
+      "code": "<Listbox aria-label=\"Search results\">\n  <Listbox.Item selected>\n    <span style={{ fontWeight: 500 }}>Button</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>\n  </Listbox.Item>\n  <Listbox.Item>\n    <span style={{ fontWeight: 500 }}>Badge</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>\n  </Listbox.Item>\n  <Listbox.Item>\n    <span style={{ fontWeight: 500 }}>Box</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Layout</span>\n  </Listbox.Item>\n</Listbox>"
+    },
+    {
+      "name": "With Groups",
+      "description": "Grouped items with labels",
+      "code": "<Listbox aria-label=\"Commands\">\n  <Listbox.Group label=\"Recent\">\n    <Listbox.Item selected>Open file...</Listbox.Item>\n    <Listbox.Item>Save as...</Listbox.Item>\n  </Listbox.Group>\n  <Listbox.Group label=\"Actions\">\n    <Listbox.Item>Copy</Listbox.Item>\n    <Listbox.Item>Paste</Listbox.Item>\n    <Listbox.Item disabled>Cut</Listbox.Item>\n  </Listbox.Group>\n</Listbox>"
+    },
+    {
+      "name": "Empty State",
+      "description": "No results found message",
+      "code": "<Listbox aria-label=\"Search results\">\n  <Listbox.Empty>No results found</Listbox.Empty>\n</Listbox>"
+    },
+    {
+      "name": "With Disabled Items",
+      "description": "Mix of enabled and disabled items",
+      "code": "<Listbox aria-label=\"Options\">\n  <Listbox.Item>Available option</Listbox.Item>\n  <Listbox.Item disabled>Disabled option</Listbox.Item>\n  <Listbox.Item>Another option</Listbox.Item>\n</Listbox>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "sibling",
+      "note": "Pair with Input for search/autocomplete patterns"
+    },
+    {
+      "component": "Menu",
+      "relationship": "alternative",
+      "note": "Use Menu when you need a trigger button"
+    },
+    {
+      "component": "Select",
+      "relationship": "alternative",
+      "note": "Use Select for form field selection"
+    },
+    {
+      "component": "List",
+      "relationship": "alternative",
+      "note": "Use List for static, non-interactive lists"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - Listbox.Item components (required)",
+      "aria-label: string - accessible label",
+      "Listbox.Item selected: boolean - highlight state",
+      "Listbox.Item disabled: boolean - non-interactive"
+    ],
+    "a11yRules": [
+      "A11Y_LISTBOX_ROLE",
+      "A11Y_OPTION_ROLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Item",
+      "Group",
+      "Empty"
+    ],
+    "requiredChildren": [
+      "Item"
+    ],
+    "commonPatterns": [
+      "<Listbox aria-label=\"Search results\">{results.map(item => <Listbox.Item key={item.id} selected={item.id === selectedId} onClick={() => onSelect(item)}>{item.label}</Listbox.Item>)}</Listbox>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.924Z"
+  }
+}

package/src/components/Loading/Loading.contract.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Loading",
+  "description": "Versatile loading indicator with multiple variants for showing progress or waiting states",
+  "category": "feedback",
+  "tags": [
+    "loading",
+    "spinner",
+    "progress",
+    "feedback",
+    "indicator",
+    "async"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Loading/index.tsx",
+  "exportName": "Loading",
+  "propsSummary": [
+    "size: sm|md|lg|xl (default: md)",
+    "variant: spinner|dots|pulse (default: spinner)",
+    "label: string (default: Loading...)",
+    "centered: boolean (default: false)",
+    "fill: boolean (default: false)",
+    "overlay: boolean (default: false)",
+    "color: accent|current|muted (default: accent)"
+  ],
+  "props": {
+    "size": {
+      "type": "enum",
+      "description": "Size of the loading indicator",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style of the loading animation",
+      "default": "spinner",
+      "required": false,
+      "values": [
+        "spinner",
+        "dots",
+        "pulse"
+      ]
+    },
+    "label": {
+      "type": "string",
+      "description": "Accessible label for screen readers",
+      "default": "Loading...",
+      "required": false
+    },
+    "centered": {
+      "type": "boolean",
+      "description": "Whether to center the loading indicator in its container",
+      "default": "false",
+      "required": false
+    },
+    "fill": {
+      "type": "boolean",
+      "description": "Whether to fill the parent container",
+      "default": "false",
+      "required": false
+    },
+    "overlay": {
+      "type": "boolean",
+      "description": "Whether to show with a backdrop overlay",
+      "default": "false",
+      "required": false
+    },
+    "color": {
+      "type": "enum",
+      "description": "Color variant - accent uses theme color, current inherits text color",
+      "default": "accent",
+      "required": false,
+      "values": [
+        "accent",
+        "current",
+        "muted"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Indicating content is being fetched or processed",
+      "Showing a pending state while waiting for an async operation",
+      "Displaying loading state for buttons, forms, or page sections",
+      "Full-screen loading during initial app/page load"
+    ],
+    "whenNot": [
+      "For showing determinate progress - use Progress component instead",
+      "For showing skeleton placeholders - use Skeleton component instead",
+      "For AI-specific thinking states - use ThinkingIndicator instead"
+    ],
+    "guidelines": [
+      "Use spinner variant for general loading states",
+      "Use dots variant for chat/messaging contexts",
+      "Use pulse variant for subtle, ambient loading",
+      "Always provide a meaningful label for screen readers",
+      "Consider using Loading.Screen for initial page loads",
+      "Use Loading.Inline when loading indicator should flow with text"
+    ],
+    "accessibility": [
+      "Component uses role=\"status\" and aria-live=\"polite\"",
+      "Always provide descriptive label prop for screen readers",
+      "Animations respect prefers-reduced-motion preference"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Default spinner loading indicator",
+      "code": "<Loading />"
+    },
+    {
+      "name": "Sizes",
+      "description": "Loading indicators in different sizes",
+      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading size=\"sm\" />\n  <Loading size=\"md\" />\n  <Loading size=\"lg\" />\n  <Loading size=\"xl\" />\n</div>"
+    },
+    {
+      "name": "Dots",
+      "description": "Bouncing dots animation",
+      "code": "<Loading variant=\"dots\" />"
+    },
+    {
+      "name": "Pulse",
+      "description": "Pulsing circle animation",
+      "code": "<Loading variant=\"pulse\" />"
+    },
+    {
+      "name": "Colors",
+      "description": "Different color variants",
+      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading color=\"accent\" />\n  <Loading color=\"muted\" />\n  <span style={{ color: '#3b82f6' }}>\n    <Loading color=\"current\" />\n  </span>\n</div>"
+    },
+    {
+      "name": "Inline",
+      "description": "Inline loading indicator that flows with text",
+      "code": "<p style={{ margin: 0 }}>\n  Processing your request <Loading.Inline /> please wait...\n</p>"
+    },
+    {
+      "name": "Centered",
+      "description": "Centered in container",
+      "code": "<div style={{ width: '200px', height: '100px', border: '1px dashed #ccc', borderRadius: '8px' }}>\n  <Loading centered fill />\n</div>"
+    },
+    {
+      "name": "Screen",
+      "description": "Full-screen loading state with optional label",
+      "code": "<div style={{ position: 'relative', width: '300px', height: '200px', border: '1px solid #ccc', borderRadius: '8px', overflow: 'hidden', transform: 'scale(1)' }}>\n  <Loading.Screen size=\"lg\" label=\"Loading application...\" showLabel />\n</div>"
+    }
+  ],
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Inline",
+      "Screen"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.576Z"
+  }
+}

package/src/components/Markdown/Markdown.contract.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Markdown",
+  "description": "Renders markdown strings as styled prose using react-markdown and remark-gfm. Supports headings, lists, tables, code blocks, blockquotes, and more.",
+  "category": "display",
+  "tags": [
+    "markdown",
+    "prose",
+    "content",
+    "text",
+    "ai",
+    "chat"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Markdown/index.tsx",
+  "exportName": "Markdown",
+  "propsSummary": [
+    "content: string (required)",
+    "components: object",
+    "className: string"
+  ],
+  "props": {
+    "content": {
+      "type": "string",
+      "description": "Markdown string to render",
+      "required": true
+    },
+    "components": {
+      "type": "object",
+      "description": "Override map for markdown element components (e.g., { h1: MyHeading }). Accepts custom renderer component signatures used by react-markdown",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Additional CSS class name",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Rendering AI/LLM response content",
+      "Displaying user-authored markdown text",
+      "Showing documentation or readme content",
+      "Rich text display without a WYSIWYG editor"
+    ],
+    "whenNot": [
+      "Plain text without formatting (use Text)",
+      "Editing markdown (use a markdown editor component)",
+      "Rendering trusted HTML directly (use dangerouslySetInnerHTML)"
+    ],
+    "guidelines": [
+      "Install react-markdown and remark-gfm as peer dependencies",
+      "Use the components prop to override default element rendering",
+      "Content is sanitized by react-markdown by default",
+      "Falls back to plain text paragraphs if react-markdown is not installed",
+      "Standard div props (id, style, aria-*, data-*) are forwarded to the Markdown wrapper"
+    ],
+    "accessibility": [
+      "Rendered HTML follows semantic structure (headings, lists, tables)",
+      "Links are rendered as proper anchor elements",
+      "Images include alt text from markdown syntax",
+      "Tables use proper th/td structure for screen readers"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic markdown with headings, paragraphs, inline code, lists, and blockquote",
+      "code": "<Markdown content={`# Hello World\n\nThis is a paragraph with **bold text** and *italic text*.\n\nHere is some \\`inline code\\` within a sentence.\n\n- First item\n- Second item\n- Third item\n\n> A blockquote for emphasis.\n`} />"
+    },
+    {
+      "name": "GFM Table",
+      "description": "GitHub Flavored Markdown with tables and task lists",
+      "code": "<Markdown content={`## Data Overview\n\n| Feature    | Status    | Priority |\n|------------|-----------|----------|\n| Markdown   | Done      | High     |\n| Tables     | Done      | Medium   |\n| Task Lists | Planned   | Low      |\n\nNotes:\n- [x] Support GFM tables\n- [x] Support task lists\n- [ ] Syntax highlighting\n`} />"
+    },
+    {
+      "name": "Code Block",
+      "description": "Markdown with fenced code blocks and inline code",
+      "code": "<Markdown content={`## Code Example\\n\\nHere is a JavaScript function:\\n\\n```js\\nfunction greet(name) {\\n  return \\`Hello, ${name}!\\`;\\n}\\n```\\n\\nAnd some inline code: \\`const x = 42;\\``} />"
+    },
+    {
+      "name": "Mixed Content",
+      "description": "Complex markdown mixing headings, lists, tables, blockquotes, and task lists",
+      "code": "<Markdown content={`# Project Update\n\n## Summary\n\nThe project is progressing well. Here are the **key highlights**:\n\n1. Completed the *design system* components\n2. Added markdown rendering support\n3. Integrated with the documentation site\n\n### Performance Metrics\n\n| Metric      | Before | After |\n|-------------|--------|-------|\n| Bundle Size | 142kb  | 98kb  |\n| Load Time   | 1.2s   | 0.8s  |\n| Lighthouse  | 72     | 95    |\n\n> These improvements were achieved through tree-shaking and code splitting.\n\n### Next Steps\n\n- [ ] Add syntax highlighting\n- [ ] Support custom themes\n- [x] GFM table support\n`} />"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Text",
+      "relationship": "alternative",
+      "note": "Use Text for plain, non-markdown text"
+    },
+    {
+      "component": "CodeBlock",
+      "relationship": "complementary",
+      "note": "CodeBlock can be used via components prop for syntax highlighting"
+    },
+    {
+      "component": "Message",
+      "relationship": "parent",
+      "note": "Message wraps Markdown when markdown prop is true"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "content: string - Markdown string to render",
+      "components: object - Override map for element components (react-markdown renderer components)",
+      "className: string - Additional CSS class",
+      "Forwards standard HTML div attributes to the wrapper element"
+    ],
+    "a11yRules": [
+      "A11Y_SEMANTIC_HTML"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:06.091Z"
+  }
+}

package/src/components/Menu/Menu.contract.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Menu",
+  "description": "Dropdown menu for actions and commands. Supports submenus, check items, radio groups, and keyboard shortcuts.",
+  "category": "feedback",
+  "tags": [
+    "menu",
+    "dropdown",
+    "actions",
+    "context-menu",
+    "commands",
+    "submenu"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Menu/index.tsx",
+  "exportName": "Menu",
+  "propsSummary": [
+    "children: node (required)",
+    "open: boolean",
+    "defaultOpen: boolean",
+    "onOpenChange: function",
+    "modal: boolean (default: true)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Menu trigger and content",
+      "required": true
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Controlled open state",
+      "required": false
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "description": "Default open state (uncontrolled)",
+      "default": "false",
+      "required": false
+    },
+    "onOpenChange": {
+      "type": "function",
+      "description": "Called when open state changes",
+      "required": false
+    },
+    "modal": {
+      "type": "boolean",
+      "description": "Whether menu is modal",
+      "default": "true",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Overflow actions that dont fit in the toolbar",
+      "Context menus (right-click)",
+      "User account menus",
+      "Grouped actions with separators",
+      "Nested menus with submenus"
+    ],
+    "whenNot": [
+      "Selecting from options (use Select)",
+      "Navigation (use Tabs or navigation components)",
+      "Form selection (use Select or RadioGroup)"
+    ],
+    "guidelines": [
+      "Group related actions with Menu.Group",
+      "Use separators to divide action categories",
+      "Include keyboard shortcuts where applicable",
+      "Use danger variant for destructive actions",
+      "Keep menu items under 10-12 for usability",
+      "Use checked prop on Menu.Item for simple selection state",
+      "Use Menu.Submenu for nested secondary options",
+      "Menu.Trigger supports asChild for links/router-link components (single valid element child required)"
+    ],
+    "accessibility": [
+      "Full keyboard navigation with arrow keys",
+      "Type-ahead search for items",
+      "Focus returns to trigger on close",
+      "Proper ARIA menu roles",
+      "ArrowRight opens submenus, ArrowLeft closes them"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic dropdown menu",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Actions</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>Edit</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Duplicate</Menu.Item>\n    <Menu.Separator />\n    <Menu.Item danger onSelect={() => {}}>Delete</Menu.Item>\n  </Menu.Content>\n</Menu>"
+    },
+    {
+      "name": "With Shortcuts",
+      "description": "Menu items with keyboard shortcuts",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Edit</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item shortcut=\"Ctrl+Z\" onSelect={() => {}}>Undo</Menu.Item>\n    <Menu.Item shortcut=\"Ctrl+Y\" onSelect={() => {}}>Redo</Menu.Item>\n    <Menu.Separator />\n    <Menu.Item shortcut=\"Ctrl+C\" onSelect={() => {}}>Copy</Menu.Item>\n    <Menu.Item shortcut=\"Ctrl+V\" onSelect={() => {}}>Paste</Menu.Item>\n  </Menu.Content>\n</Menu>"
+    },
+    {
+      "name": "With Groups",
+      "description": "Menu with labeled groups",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Options</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Group>\n      <Menu.GroupLabel>View</Menu.GroupLabel>\n      <Menu.Item onSelect={() => {}}>Zoom In</Menu.Item>\n      <Menu.Item onSelect={() => {}}>Zoom Out</Menu.Item>\n    </Menu.Group>\n    <Menu.Separator />\n    <Menu.Group>\n      <Menu.GroupLabel>Layout</Menu.GroupLabel>\n      <Menu.Item onSelect={() => {}}>Grid View</Menu.Item>\n      <Menu.Item onSelect={() => {}}>List View</Menu.Item>\n    </Menu.Group>\n  </Menu.Content>\n</Menu>"
+    },
+    {
+      "name": "With Checkboxes",
+      "description": "Menu with toggleable checkbox options",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Display</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.CheckboxItem defaultChecked>Show Grid</Menu.CheckboxItem>\n    <Menu.CheckboxItem defaultChecked>Show Rulers</Menu.CheckboxItem>\n    <Menu.CheckboxItem>Show Guides</Menu.CheckboxItem>\n  </Menu.Content>\n</Menu>"
+    },
+    {
+      "name": "With Checked Items",
+      "description": "Filter menu with check marks indicating active selections",
+      "code": "<CheckedItemsMenuDemo />"
+    },
+    {
+      "name": "With Submenu",
+      "description": "Menu with nested submenu for grouped secondary options",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">File</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>New File</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Open</Menu.Item>\n    <Menu.Separator />\n    <Menu.Submenu>\n      <Menu.SubmenuTrigger>Export As</Menu.SubmenuTrigger>\n      <Menu.Content side=\"right\" align=\"start\">\n        <Menu.Item onSelect={() => {}}>PNG</Menu.Item>\n        <Menu.Item onSelect={() => {}}>SVG</Menu.Item>\n        <Menu.Item onSelect={() => {}}>PDF</Menu.Item>\n      </Menu.Content>\n    </Menu.Submenu>\n    <Menu.Separator />\n    <Menu.Item danger onSelect={() => {}}>Delete</Menu.Item>\n  </Menu.Content>\n</Menu>"
+    },
+    {
+      "name": "Link Trigger",
+      "description": "Use asChild with a non-button trigger element",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <a href=\"#menu-actions\">Open menu</a>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>Inspect</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Rename</Menu.Item>\n  </Menu.Content>\n</Menu>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Select",
+      "relationship": "alternative",
+      "note": "Use Select for form field selection"
+    },
+    {
+      "component": "Popover",
+      "relationship": "alternative",
+      "note": "Use Popover for rich non-action content"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "open: boolean - controlled open state",
+      "onOpenChange: (open) => void - state handler",
+      "Menu.Trigger asChild supports non-button trigger elements",
+      "Menu.Item onSelect: (event) => void - selection callback receives click event",
+      "Menu.Item danger: boolean - destructive styling",
+      "Menu.Item shortcut: string - keyboard shortcut text",
+      "Menu.Item checked: boolean - check indicator for selection state"
+    ],
+    "a11yRules": [
+      "A11Y_MENU_KEYBOARD",
+      "A11Y_MENU_ROLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Trigger",
+      "Content",
+      "Item",
+      "CheckboxItem",
+      "RadioGroup",
+      "RadioItem",
+      "Group",
+      "GroupLabel",
+      "Separator",
+      "Submenu",
+      "SubmenuTrigger"
+    ],
+    "requiredChildren": [
+      "Trigger",
+      "Content"
+    ],
+    "commonPatterns": [
+      "<Menu><Menu.Trigger asChild><Button>Actions</Button></Menu.Trigger><Menu.Content><Menu.Item>{action1}</Menu.Item><Menu.Separator /><Menu.Item danger>{delete}</Menu.Item></Menu.Content></Menu>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:00.159Z"
+  }
+}