@fragments-sdk/ui 0.17.1 → 0.18.0

package/src/components/Command/Command.contract.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Command",
+  "description": "A searchable command palette for quick actions. Combines an input with a filterable, keyboard-navigable list of actions.",
+  "category": "navigation",
+  "tags": [
+    "command",
+    "palette",
+    "search",
+    "spotlight",
+    "quick-actions",
+    "cmdk"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Command/index.tsx",
+  "exportName": "Command",
+  "propsSummary": [
+    "children: node (required)",
+    "search: string",
+    "defaultSearch: string (default: )",
+    "onSearchChange: function",
+    "filter: function",
+    "loop: boolean (default: true)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Command.Input, Command.List, and other sub-components",
+      "required": true
+    },
+    "search": {
+      "type": "string",
+      "description": "Controlled search value",
+      "required": false
+    },
+    "defaultSearch": {
+      "type": "string",
+      "description": "Default search value (uncontrolled)",
+      "default": "",
+      "required": false
+    },
+    "onSearchChange": {
+      "type": "function",
+      "description": "Called when search input changes",
+      "required": false
+    },
+    "filter": {
+      "type": "function",
+      "description": "Custom filter function. Return 0 to hide, >0 to show.",
+      "required": false
+    },
+    "loop": {
+      "type": "boolean",
+      "description": "Whether to loop keyboard navigation",
+      "default": "true",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Quick-access command palettes (Ctrl+K)",
+      "Searchable action menus",
+      "Inline command lists with filtering",
+      "Application-wide search interfaces"
+    ],
+    "whenNot": [
+      "Simple dropdown menus (use Menu)",
+      "Form field selection (use Select or Combobox)",
+      "Static navigation (use Sidebar or Tabs)",
+      "Search with complex result types (build custom)"
+    ],
+    "guidelines": [
+      "Compose inside Dialog for modal command palette usage",
+      "Use Command.Group to organize items by category",
+      "Provide Command.Empty for no-results feedback",
+      "Use keywords prop for items that should match on aliases",
+      "Keep item labels short and action-oriented"
+    ],
+    "accessibility": [
+      "Uses combobox + listbox ARIA pattern",
+      "Keyboard navigation with ArrowUp/ArrowDown, Enter to select",
+      "Home/End jump to first/last item",
+      "aria-activedescendant tracks focused item"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Inline command list with search",
+      "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"Type a command...\" />\n    <Command.List>\n      <Command.Item onItemSelect={() => {}}>Open File</Command.Item>\n      <Command.Item onItemSelect={() => {}}>Save Document</Command.Item>\n      <Command.Item onItemSelect={() => {}}>Print</Command.Item>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
+    },
+    {
+      "name": "Dialog Command Palette",
+      "description": "Command palette inside a Dialog",
+      "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <Button variant=\"secondary\">Open Command Palette</Button>\n  </Dialog.Trigger>\n  <Dialog.Content size=\"sm\">\n    <Command>\n      <Command.Input placeholder=\"Search commands...\" />\n      <Command.List>\n        <Command.Group heading=\"Actions\">\n          <Command.Item onItemSelect={() => {}}>New File</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Open Recent</Command.Item>\n        </Command.Group>\n        <Command.Separator />\n        <Command.Group heading=\"Settings\">\n          <Command.Item onItemSelect={() => {}}>Preferences</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Keyboard Shortcuts</Command.Item>\n        </Command.Group>\n        <Command.Empty>No results found.</Command.Empty>\n      </Command.List>\n    </Command>\n  </Dialog.Content>\n</Dialog>"
+    },
+    {
+      "name": "With Groups",
+      "description": "Organized by category groups",
+      "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"Search...\" />\n    <Command.List>\n      <Command.Group heading=\"Suggestions\">\n        <Command.Item onItemSelect={() => {}}>Calendar</Command.Item>\n        <Command.Item onItemSelect={() => {}}>Calculator</Command.Item>\n      </Command.Group>\n      <Command.Separator />\n      <Command.Group heading=\"Settings\">\n        <Command.Item onItemSelect={() => {}}>Profile</Command.Item>\n        <Command.Item onItemSelect={() => {}}>Billing</Command.Item>\n        <Command.Item disabled onItemSelect={() => {}}>\n          Team (coming soon)\n        </Command.Item>\n      </Command.Group>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
+    },
+    {
+      "name": "With Icons",
+      "description": "Items with leading icons",
+      "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"What do you need?\" />\n    <Command.List>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>+</span> New Document\n      </Command.Item>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>{'>'}</span> Open Folder\n      </Command.Item>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>?</span> Search\n      </Command.Item>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Dialog",
+      "relationship": "sibling",
+      "note": "Compose inside Dialog for modal command palette"
+    },
+    {
+      "component": "Listbox",
+      "relationship": "sibling",
+      "note": "Command uses Listbox-like keyboard navigation internally"
+    },
+    {
+      "component": "Combobox",
+      "relationship": "alternative",
+      "note": "Use Combobox for form field selection with search"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "search: string - controlled search value",
+      "onSearchChange: (search) => void - search change handler",
+      "filter: (value, search, keywords?) => number - custom filter",
+      "loop: boolean - loop keyboard navigation (default: true)",
+      "Command.Item value: string - filter match value",
+      "Command.Item keywords: string[] - extra filter terms",
+      "Command.Item onItemSelect: (value, event) => void - selection handler"
+    ],
+    "a11yRules": [
+      "A11Y_COMBOBOX_ROLE",
+      "A11Y_LISTBOX_ROLE",
+      "A11Y_ACTIVE_DESCENDANT"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Input",
+      "List",
+      "Item",
+      "Group",
+      "Empty",
+      "Separator"
+    ],
+    "requiredChildren": [
+      "Input",
+      "List"
+    ],
+    "commonPatterns": [
+      "<Dialog><Dialog.Trigger><Button>Open Palette</Button></Dialog.Trigger><Dialog.Content size=\"sm\"><Command><Command.Input placeholder=\"Search...\" /><Command.List><Command.Group heading=\"Actions\"><Command.Item onItemSelect={() => {}}>Action 1</Command.Item></Command.Group><Command.Empty>No results.</Command.Empty></Command.List></Command></Dialog.Content></Dialog>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:53.723Z"
+  }
+}

package/src/components/ConversationList/ConversationList.contract.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "ConversationList",
+  "description": "Scrollable message container with auto-scroll and history loading",
+  "category": "ai",
+  "tags": [
+    "conversation",
+    "chat",
+    "messages",
+    "scroll",
+    "ai",
+    "list"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/ConversationList/index.tsx",
+  "exportName": "ConversationList",
+  "propsSummary": [
+    "children: node (required)",
+    "autoScroll: union (default: smart)",
+    "onScrollTop: function",
+    "loadingHistory: boolean (default: false)",
+    "emptyState: node",
+    "scrollTopThreshold: number (default: 50)",
+    "scrollBottomThreshold: number (default: 100)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Message components",
+      "required": true
+    },
+    "autoScroll": {
+      "type": "union",
+      "description": "Auto-scroll behavior: true (always), false (never), or \"smart\" (only when near bottom)",
+      "default": "smart",
+      "required": false
+    },
+    "onScrollTop": {
+      "type": "function",
+      "description": "Callback when user scrolls to top (for loading history). Receives the scroll event.",
+      "required": false
+    },
+    "loadingHistory": {
+      "type": "boolean",
+      "description": "Show loading spinner at top when loading history",
+      "default": "false",
+      "required": false
+    },
+    "emptyState": {
+      "type": "node",
+      "description": "Content to show when conversation is empty",
+      "required": false
+    },
+    "scrollTopThreshold": {
+      "type": "number",
+      "description": "Pixels from top to trigger onScrollTop",
+      "default": "50",
+      "required": false
+    },
+    "scrollBottomThreshold": {
+      "type": "number",
+      "description": "Pixels from bottom for smart auto-scroll",
+      "default": "100",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Building a chat interface with multiple messages",
+      "Need auto-scroll behavior when new messages arrive",
+      "Require infinite scroll for loading message history",
+      "Want date separators between message groups"
+    ],
+    "whenNot": [
+      "Simple list of items without chat context (use List)",
+      "Single message display (use Message directly)",
+      "Non-scrolling message layout"
+    ],
+    "guidelines": [
+      "Use autoScroll=\"smart\" for best UX (only auto-scrolls when near bottom)",
+      "Implement onScrollTop for loading older messages",
+      "ConversationList composes your onScroll handler with internal auto-scroll/history logic",
+      "Provide an emptyState for new conversations",
+      "Use DateSeparator between messages from different days"
+    ],
+    "accessibility": [
+      "Uses proper ARIA roles for separators",
+      "Typing indicator has aria-label",
+      "Smooth scroll respects reduced motion preferences",
+      "Keyboard navigation works within scrollable container"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Basic",
+      "description": "Simple conversation with messages",
+      "code": "<ConversationList>\n  <Message role=\"user\">\n    <Message.Content>Hello!</Message.Content>\n  </Message>\n  <Message role=\"assistant\">\n    <Message.Content>Hi there! How can I help you today?</Message.Content>\n  </Message>\n  <Message role=\"user\">\n    <Message.Content>Can you explain React hooks?</Message.Content>\n  </Message>\n</ConversationList>"
+    },
+    {
+      "name": "With Date Separators",
+      "description": "Messages grouped by date",
+      "code": "<ConversationList>\n  <ConversationList.DateSeparator date={new Date(Date.now() - 86400000)} />\n  <Message role=\"user\">\n    <Message.Content>A message from yesterday</Message.Content>\n  </Message>\n  <ConversationList.DateSeparator date={new Date()} />\n  <Message role=\"assistant\">\n    <Message.Content>And a message from today!</Message.Content>\n  </Message>\n</ConversationList>"
+    },
+    {
+      "name": "With Typing Indicator",
+      "description": "Shows assistant is typing",
+      "code": "<ConversationList>\n  <Message role=\"user\">\n    <Message.Content>What is TypeScript?</Message.Content>\n  </Message>\n  <ConversationList.TypingIndicator name=\"Assistant\" />\n</ConversationList>"
+    },
+    {
+      "name": "Loading History",
+      "description": "Loading older messages",
+      "code": "<ConversationList loadingHistory>\n  <Message role=\"user\">\n    <Message.Content>This is the latest message</Message.Content>\n  </Message>\n</ConversationList>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Message",
+      "relationship": "child",
+      "note": "ConversationList contains Message components"
+    },
+    {
+      "component": "ThinkingIndicator",
+      "relationship": "child",
+      "note": "Show ThinkingIndicator at bottom while awaiting response"
+    },
+    {
+      "component": "Prompt",
+      "relationship": "sibling",
+      "note": "Typically paired with Prompt for input"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - Message components",
+      "autoScroll: boolean | \"smart\" - scroll behavior (default: \"smart\")",
+      "onScrollTop: (event?) => void - callback for loading history (receives scroll event)",
+      "loadingHistory: boolean - show history loading spinner",
+      "emptyState: ReactNode - empty conversation content"
+    ],
+    "a11yRules": [
+      "A11Y_ARIA_ROLES",
+      "A11Y_MOTION_PREFERENCE"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:53.889Z"
+  }
+}

package/src/components/DataTable/DataTable.contract.json

@@ -0,0 +1,302 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "DataTable",
+  "description": "Data table with sorting, selection, and column management. Powered by TanStack Table.",
+  "category": "display",
+  "tags": [
+    "table",
+    "data",
+    "grid",
+    "list",
+    "sorting",
+    "tanstack"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/DataTable/index.tsx",
+  "exportName": "DataTable",
+  "propsSummary": [
+    "columns: array (required)",
+    "data: array (required)",
+    "getRowId: function",
+    "sortable: boolean (default: false)",
+    "sorting: array",
+    "onSortingChange: function",
+    "selectable: boolean (default: false)",
+    "showCheckbox: boolean (default: false)",
+    "rowSelection: object",
+    "onRowSelectionChange: function",
+    "onRowClick: function",
+    "getSubRows: function",
+    "expanded: union",
+    "onExpandedChange: function",
+    "emptyMessage: string (default: No data available)",
+    "size: sm|md (default: md)",
+    "caption: string",
+    "captionHidden: boolean (default: false)",
+    "striped: boolean (default: false)",
+    "bordered: boolean (default: false)",
+    "wrapperClassName: string",
+    "wrapperProps: object"
+  ],
+  "props": {
+    "columns": {
+      "type": "array",
+      "description": "Column definitions",
+      "required": true
+    },
+    "data": {
+      "type": "array",
+      "description": "Data rows to display",
+      "required": true
+    },
+    "getRowId": {
+      "type": "function",
+      "description": "Unique key extractor for each row",
+      "required": false
+    },
+    "sortable": {
+      "type": "boolean",
+      "description": "Enable column sorting",
+      "default": "false",
+      "required": false
+    },
+    "sorting": {
+      "type": "array",
+      "description": "Controlled sorting state",
+      "required": false
+    },
+    "onSortingChange": {
+      "type": "function",
+      "description": "Sorting change handler",
+      "required": false
+    },
+    "selectable": {
+      "type": "boolean",
+      "description": "Enable row selection",
+      "default": "false",
+      "required": false
+    },
+    "showCheckbox": {
+      "type": "boolean",
+      "description": "Show checkbox column for row selection (requires selectable)",
+      "default": "false",
+      "required": false
+    },
+    "rowSelection": {
+      "type": "object",
+      "description": "Controlled row selection state",
+      "required": false
+    },
+    "onRowSelectionChange": {
+      "type": "function",
+      "description": "Row selection change handler",
+      "required": false
+    },
+    "onRowClick": {
+      "type": "function",
+      "description": "Handler for row clicks/keyboard activation. Called as (row, event)",
+      "required": false
+    },
+    "getSubRows": {
+      "type": "function",
+      "description": "Extract sub-rows for expandable tree tables",
+      "required": false
+    },
+    "expanded": {
+      "type": "union",
+      "description": "Controlled expanded state",
+      "required": false
+    },
+    "onExpandedChange": {
+      "type": "function",
+      "description": "Expanded state change handler",
+      "required": false
+    },
+    "emptyMessage": {
+      "type": "string",
+      "description": "Message when no data",
+      "default": "No data available",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Table density",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md"
+      ]
+    },
+    "caption": {
+      "type": "string",
+      "description": "Visible caption for the table",
+      "required": false
+    },
+    "captionHidden": {
+      "type": "boolean",
+      "description": "Hide caption visually but keep it for screen readers",
+      "default": "false",
+      "required": false
+    },
+    "striped": {
+      "type": "boolean",
+      "description": "Show alternating row backgrounds",
+      "default": "false",
+      "required": false
+    },
+    "bordered": {
+      "type": "boolean",
+      "description": "Wrap table in a bordered container",
+      "default": "false",
+      "required": false
+    },
+    "wrapperClassName": {
+      "type": "string",
+      "description": "Additional class name for the outer wrapper div",
+      "required": false
+    },
+    "wrapperProps": {
+      "type": "object",
+      "description": "Props forwarded to the outer wrapper div (id, aria-*, data-*, handlers)",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Displaying structured, tabular data with sorting",
+      "Data that users need to scan, compare, and act upon",
+      "Lists with multiple attributes per item that need sorting or selection",
+      "Data-rich tables requiring column sizing and row clicks",
+      "Hierarchical data with expandable sub-rows"
+    ],
+    "whenNot": [
+      "Simple static tables (use Table component)",
+      "Simple lists (use List component)",
+      "Card-based layouts (use Grid with Cards)",
+      "Small screens (consider card or list view)"
+    ],
+    "guidelines": [
+      "Keep columns to a reasonable number (5-7 max)",
+      "Use consistent alignment (numbers right, text left)",
+      "Provide meaningful empty states",
+      "Consider mobile responsiveness",
+      "Use showCheckbox for bulk selection workflows"
+    ],
+    "accessibility": [
+      "Proper table semantics with headers",
+      "Sortable columns are keyboard accessible",
+      "Row selection checkboxes include aria-labels",
+      "Expand/collapse buttons have aria-expanded state"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic data table with status badges and role columns",
+      "code": "<DataTable\n  columns={basicColumns}\n  data={sampleUsers}\n  aria-label=\"Team members\"\n/>"
+    },
+    {
+      "name": "Rich Cells",
+      "description": "Custom cells with avatars, stacked text, and column sizing",
+      "code": "<DataTable\n  columns={richColumns}\n  data={sampleUsers}\n  bordered\n  aria-label=\"Team members\"\n/>"
+    },
+    {
+      "name": "Sortable",
+      "description": "Click column headers to sort ascending or descending",
+      "code": "<DataTable\n  columns={transactionColumns}\n  data={sampleTransactions}\n  sortable\n  bordered\n  caption=\"Recent transactions\"\n  captionHidden\n  aria-label=\"Transactions\"\n/>"
+    },
+    {
+      "name": "Checkbox Selection",
+      "description": "Select rows with header checkbox for select-all and individual row checkboxes",
+      "code": "function TeamTable() {\n  const [selection, setSelection] = useState({});\n  const selectedCount = Object.values(selection).filter(Boolean).length;\n\n  return (\n    <Stack gap=\"sm\">\n      <Stack direction=\"row\" justify=\"between\" align=\"center\">\n        <Text size=\"sm\" color=\"secondary\">\n          {selectedCount > 0 ? `${selectedCount} selected` : 'Select rows with checkboxes'}\n        </Text>\n        {selectedCount > 0 && (\n          <Button size=\"sm\" variant=\"ghost\" onClick={() => setSelection({})}>\n            Clear\n          </Button>\n        )}\n      </Stack>\n      <DataTable\n        columns={columns}\n        data={users}\n        selectable\n        showCheckbox\n        rowSelection={selection}\n        onRowSelectionChange={setSelection}\n        getRowId={(row) => row.id}\n        bordered\n        aria-label=\"Team members\"\n      />\n    </Stack>\n  );\n}"
+    },
+    {
+      "name": "Expandable Rows",
+      "description": "Hierarchical data with collapsible sub-rows, like a file tree",
+      "code": "const fileTreeData = [\n  {\n    id: '1', name: 'src', type: 'folder', modified: 'Feb 18, 2026',\n    subRows: [\n      { id: '1.1', name: 'components', type: 'folder', modified: 'Feb 18, 2026',\n        subRows: [\n          { id: '1.1.1', name: 'Button.tsx', type: 'file', size: '4.2 KB', modified: 'Feb 17, 2026' },\n          { id: '1.1.2', name: 'Card.tsx', type: 'file', size: '3.8 KB', modified: 'Feb 16, 2026' },\n        ],\n      },\n    ],\n  },\n  { id: '2', name: 'package.json', type: 'file', size: '1.2 KB', modified: 'Feb 18, 2026' },\n];\n\n<DataTable\n  columns={fileColumns}\n  data={fileTreeData}\n  getSubRows={(row) => row.subRows}\n  getRowId={(row) => row.id}\n  bordered\n  size=\"sm\"\n  aria-label=\"File tree\"\n/>"
+    },
+    {
+      "name": "With Filters",
+      "description": "Combine with search input and menu dropdowns for filtered views",
+      "code": "function FilteredTable() {\n  const [search, setSearch] = useState('');\n  const [statusFilter, setStatusFilter] = useState(null);\n\n  const filteredData = useMemo(() => {\n    return users.filter((user) => {\n      if (search && !user.name.toLowerCase().includes(search.toLowerCase())) return false;\n      if (statusFilter && user.status !== statusFilter) return false;\n      return true;\n    });\n  }, [search, statusFilter]);\n\n  return (\n    <Stack gap=\"sm\">\n      <Stack direction=\"row\" gap=\"sm\" align=\"center\">\n        <Input placeholder=\"Search...\" size=\"sm\" value={search} onChange={(e) => setSearch(e.target.value)} />\n        <Menu>\n          <Menu.Trigger asChild>\n            <Button variant=\"secondary\" size=\"sm\">Status</Button>\n          </Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item onClick={() => setStatusFilter(null)}>All</Menu.Item>\n            <Menu.Item onClick={() => setStatusFilter('active')}>Active</Menu.Item>\n            <Menu.Item onClick={() => setStatusFilter('pending')}>Pending</Menu.Item>\n          </Menu.Content>\n        </Menu>\n      </Stack>\n      <DataTable\n        columns={columns}\n        data={filteredData}\n        sortable\n        bordered\n        emptyMessage=\"No users match the current filters\"\n        aria-label=\"Filtered team members\"\n      />\n    </Stack>\n  );\n}"
+    },
+    {
+      "name": "Clickable Rows",
+      "description": "Rows respond to click and keyboard activation",
+      "code": "<DataTable\n  columns={endpointColumns}\n  data={sampleEndpoints}\n  onRowClick={(row) => alert(`${row.method} ${row.path}`)}\n  size=\"sm\"\n  aria-label=\"API endpoints\"\n/>"
+    },
+    {
+      "name": "Striped",
+      "description": "Alternating row backgrounds for dense data",
+      "code": "<DataTable\n  columns={endpointColumns}\n  data={sampleEndpoints}\n  striped\n  size=\"sm\"\n  sortable\n  aria-label=\"API endpoints\"\n/>"
+    },
+    {
+      "name": "Empty State",
+      "description": "Display when no data matches the current filters",
+      "code": "<DataTable\n  columns={basicColumns}\n  data={[]}\n  emptyMessage=\"No users match your search criteria\"\n  aria-label=\"Search results\"\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Table",
+      "relationship": "alternative",
+      "note": "Use Table for simple semantic HTML tables"
+    },
+    {
+      "component": "EmptyState",
+      "relationship": "sibling",
+      "note": "Use EmptyState for empty table states"
+    },
+    {
+      "component": "Badge",
+      "relationship": "sibling",
+      "note": "Use Badge for status columns"
+    },
+    {
+      "component": "Menu",
+      "relationship": "sibling",
+      "note": "Use Menu for filter dropdowns"
+    },
+    {
+      "component": "Checkbox",
+      "relationship": "sibling",
+      "note": "Built-in checkbox selection via showCheckbox"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "columns: ColumnDef[] - column definitions",
+      "data: T[] - row data array",
+      "sortable: boolean - enable sorting",
+      "selectable: boolean - enable row selection",
+      "showCheckbox: boolean - add checkbox column",
+      "getSubRows: (row) => T[] - enable expandable rows",
+      "onRowClick: (row, event) => void - row activation handler with event access",
+      "size: sm|md - table density",
+      "striped: boolean - alternating row backgrounds",
+      "bordered: boolean - bordered container",
+      "wrapperClassName / wrapperProps - style and configure the outer wrapper div"
+    ],
+    "a11yRules": [
+      "A11Y_TABLE_HEADERS",
+      "A11Y_TABLE_SORT"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "simple",
+    "subComponents": [
+      "Root",
+      "Columns"
+    ],
+    "commonPatterns": [
+      "<DataTable columns={createColumns([{key:\"name\",header:\"Name\"},{key:\"status\",header:\"Status\"}])} data={[{name:\"Item 1\",status:\"Active\"}]} />"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:54.097Z"
+  }
+}