@usefragments/ui 1.6.0 → 2.0.0

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

@@ -1,302 +0,0 @@
-{
-  "$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",
-  "dependencies": [
-    {
-      "name": "@tanstack/react-table",
-      "version": ">=8.0.0",
-      "reason": "Optional — powers sorting, selection, and expansion; without it DataTable renders a static, non-interactive table."
-    }
-  ],
-  "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",
-    "getRowProps: 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
-    },
-    "getRowProps": {
-      "type": "function",
-      "description": "Returns row-level HTML, ARIA, data, class, and event props for each rendered data row",
-      "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",
-      "Use getRowProps to provide an accessible name and intentional semantics for clickable rows"
-    ],
-    "accessibility": [
-      "Proper table semantics with headers",
-      "Sortable columns are keyboard accessible",
-      "Row selection checkboxes include aria-labels",
-      "Expand/collapse buttons have aria-expanded state",
-      "Clickable rows expose an accessible action label through getRowProps"
-    ]
-  },
-  "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  getRowProps={(row) => ({\n    role: 'button',\n    'aria-label': `Open ${row.method} ${row.path}`,\n  })}\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",
-      "getRowProps: (row) => HTMLAttributes<HTMLTableRowElement> - row-level ARIA, role, data, class, and event props",
-      "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", "preload"],
-    "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"
-  }
-}

package/src/components/Dialog/Dialog.contract.json

@@ -1,159 +0,0 @@
-{
-  "$schema": "https://usefragments.com/schemas/contract.v1.json",
-  "name": "Dialog",
-  "description": "Modal overlay for focused user interactions. Use for confirmations, forms, or content requiring full attention.",
-  "category": "feedback",
-  "tags": [
-    "modal",
-    "dialog",
-    "overlay",
-    "popup",
-    "confirmation"
-  ],
-  "status": "stable",
-  "sourcePath": "src/components/Dialog/index.tsx",
-  "exportName": "Dialog",
-  "propsSummary": [
-    "children: node (required)",
-    "open: boolean",
-    "defaultOpen: boolean",
-    "onOpenChange: function",
-    "modal: boolean (default: true)"
-  ],
-  "props": {
-    "children": {
-      "type": "node",
-      "description": "Dialog content (use Dialog.Content, Dialog.Header, etc.)",
-      "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 to render as modal (blocks interaction with rest of page)",
-      "default": "true",
-      "required": false
-    }
-  },
-  "usage": {
-    "when": [
-      "Confirming destructive actions (delete, discard changes)",
-      "Collecting focused input (forms, settings)",
-      "Displaying content that requires acknowledgment",
-      "Multi-step workflows that need isolation"
-    ],
-    "whenNot": [
-      "Simple tooltips or hints (use Tooltip)",
-      "Contextual menus (use Menu or Popover)",
-      "Non-blocking notifications (use Toast or Alert)",
-      "Simple confirmation that can be inline (use Alert)"
-    ],
-    "guidelines": [
-      "Keep dialog content focused on a single task",
-      "Provide clear primary and secondary actions",
-      "Use descriptive title that explains the purpose",
-      "Allow dismissal via backdrop click or close button for non-critical dialogs",
-      "Trap focus within the dialog for accessibility",
-      "Dialog.Trigger and Dialog.Close support asChild for buttons, links, and router link components"
-    ],
-    "accessibility": [
-      "Automatically traps focus within the dialog",
-      "Closes on Escape key press",
-      "Returns focus to trigger element on close",
-      "Uses role=\"dialog\" with proper aria attributes"
-    ]
-  },
-  "examples": [
-    {
-      "name": "Default",
-      "description": "Basic dialog with header, body, and footer",
-      "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <Button>Open Dialog</Button>\n  </Dialog.Trigger>\n  <Dialog.Content>\n    <Dialog.Close />\n    <Dialog.Header>\n      <Dialog.Title>Dialog Title</Dialog.Title>\n      <Dialog.Description>\n        A brief description of what this dialog is for.\n      </Dialog.Description>\n    </Dialog.Header>\n    <Dialog.Body>\n      <p>Dialog content goes here. You can include forms, text, or any other content.</p>\n    </Dialog.Body>\n    <Dialog.Footer>\n      <Dialog.Close asChild>\n        <Button variant=\"secondary\">Cancel</Button>\n      </Dialog.Close>\n      <Button variant=\"primary\">Confirm</Button>\n    </Dialog.Footer>\n  </Dialog.Content>\n</Dialog>"
-    },
-    {
-      "name": "Confirmation",
-      "description": "Destructive action confirmation",
-      "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <Button variant=\"danger\">Delete Item</Button>\n  </Dialog.Trigger>\n  <Dialog.Content size=\"sm\">\n    <Dialog.Header>\n      <Dialog.Title>Delete item?</Dialog.Title>\n      <Dialog.Description>\n        This action cannot be undone. The item will be permanently removed.\n      </Dialog.Description>\n    </Dialog.Header>\n    <Dialog.Footer>\n      <Dialog.Close asChild>\n        <Button variant=\"secondary\">Cancel</Button>\n      </Dialog.Close>\n      <Button variant=\"danger\">Delete</Button>\n    </Dialog.Footer>\n  </Dialog.Content>\n</Dialog>"
-    },
-    {
-      "name": "Large",
-      "description": "Large dialog for complex content",
-      "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <Button>Open Large Dialog</Button>\n  </Dialog.Trigger>\n  <Dialog.Content size=\"lg\">\n    <Dialog.Close />\n    <Dialog.Header>\n      <Dialog.Title>Settings</Dialog.Title>\n      <Dialog.Description>\n        Configure your application preferences.\n      </Dialog.Description>\n    </Dialog.Header>\n    <Dialog.Body>\n      <p>This dialog has more space for complex forms or content layouts.</p>\n    </Dialog.Body>\n    <Dialog.Footer>\n      <Dialog.Close asChild>\n        <Button variant=\"secondary\">Cancel</Button>\n      </Dialog.Close>\n      <Button variant=\"primary\">Save Changes</Button>\n    </Dialog.Footer>\n  </Dialog.Content>\n</Dialog>"
-    },
-    {
-      "name": "Link Trigger + No Initial Focus",
-      "description": "Use asChild with a link trigger and disable automatic initial focus when needed",
-      "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <a href=\"#dialog-demo\">Open via link</a>\n  </Dialog.Trigger>\n  <Dialog.Content size=\"sm\" initialFocus={false}>\n    <Dialog.Header>\n      <Dialog.Title>Linked Trigger</Dialog.Title>\n      <Dialog.Description>\n        Example using asChild with an anchor element and manual focus behavior.\n      </Dialog.Description>\n    </Dialog.Header>\n    <Dialog.Footer>\n      <Dialog.Close asChild>\n        <Button variant=\"secondary\">Close</Button>\n      </Dialog.Close>\n    </Dialog.Footer>\n  </Dialog.Content>\n</Dialog>"
-    }
-  ],
-  "relations": [
-    {
-      "component": "Popover",
-      "relationship": "alternative",
-      "note": "Use Popover for non-modal contextual content"
-    },
-    {
-      "component": "Menu",
-      "relationship": "alternative",
-      "note": "Use Menu for action lists"
-    },
-    {
-      "component": "Alert",
-      "relationship": "sibling",
-      "note": "Use Alert for inline notifications"
-    }
-  ],
-  "contract": {
-    "propsSummary": [
-      "open: boolean - controlled open state",
-      "onOpenChange: (open) => void - open state handler",
-      "modal: boolean - blocks page interaction (default: true)",
-      "Dialog.Content initialFocus?: boolean - control auto-focus on open (default: true)",
-      "Dialog.Content size: sm|md|lg|xl|full - dialog width"
-    ],
-    "a11yRules": [
-      "A11Y_DIALOG_FOCUS",
-      "A11Y_DIALOG_ESCAPE",
-      "A11Y_DIALOG_LABEL"
-    ]
-  },
-  "ai": {
-    "compositionPattern": "compound",
-    "subComponents": [
-      "Trigger",
-      "Content",
-      "Close",
-      "Header",
-      "Title",
-      "Description",
-      "Body",
-      "Footer"
-    ],
-    "requiredChildren": [
-      "Content"
-    ],
-    "commonPatterns": [
-      "<Dialog><Dialog.Trigger><Button>Open</Button></Dialog.Trigger><Dialog.Content><Dialog.Header><Dialog.Title>{title}</Dialog.Title></Dialog.Header><Dialog.Body>{content}</Dialog.Body><Dialog.Footer><Dialog.Close><Button variant=\"secondary\">Cancel</Button></Dialog.Close><Button>Confirm</Button></Dialog.Footer></Dialog.Content></Dialog>",
-      "<Dialog><Dialog.Trigger asChild><a href=\"/settings\">Open settings</a></Dialog.Trigger><Dialog.Content initialFocus={false}>...</Dialog.Content></Dialog>"
-    ]
-  },
-  "provenance": {
-    "source": "migrated",
-    "verified": false,
-    "frameworkSupport": "native",
-    "extractedAt": "2026-03-13T23:18:55.179Z"
-  }
-}