agentic-ds-kit 0.1.0

package/contracts/datatable.json

@@ -0,0 +1,126 @@
+{
+  "id": "datatable",
+  "status": "stable",
+  "intent": "Framed dataset with search, filters, column settings, and a caption title.",
+  "useWhen": [
+    "Searchable datasets with filters or column settings",
+    "Selectable rows of structured data"
+  ],
+  "doNotUseWhen": [
+    "A short static list \u2014 use Table",
+    "Dashboard or list-detail activity lists \u2014 use Table"
+  ],
+  "props": {
+    "caption": {
+      "type": "string",
+      "required": false
+    },
+    "selectable": {
+      "type": "boolean",
+      "default": false
+    },
+    "toolbar": {
+      "type": "boolean",
+      "default": false,
+      "note": "When true, show search + filters + optional Columns"
+    },
+    "searchPlaceholder": {
+      "type": "string",
+      "default": "Search..."
+    },
+    "filters": {
+      "type": "array",
+      "required": false,
+      "itemShape": {
+        "key": "string",
+        "label": "string"
+      },
+      "note": "Each is a kit DropdownMenu of unique values from that column on the full rows, plus All {label}. Not a native select."
+    },
+    "columnSettings": {
+      "type": "boolean",
+      "required": false,
+      "note": "Columns button; kit Checkboxes to show/hide columns. Name (or first data column) cannot be hidden. Local state only."
+    },
+    "cellSize": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md"
+      ],
+      "default": "md",
+      "note": "Passed to every Cell and HeaderCell"
+    },
+    "columns": {
+      "type": "array",
+      "required": true,
+      "itemShape": {
+        "key": "string",
+        "header": "string",
+        "type": "text | number?",
+        "sortable": "boolean?"
+      },
+      "note": "type number right-aligns cell and header. sortable adds HeaderCell sort (asc, desc, then off). Local state only."
+    },
+    "rows": {
+      "type": "array",
+      "required": true,
+      "itemShape": "Record<string, string | number | CellValue>",
+      "note": "Values may be Cell objects (type + fields) or plain string/number (rendered as Cell type=text). Optional row.id if primitive; skip object ids."
+    },
+    "emptyMessage": {
+      "type": "string",
+      "default": "No results."
+    },
+    "onSelectionChange": {
+      "type": "function",
+      "required": false,
+      "note": "(ids: string[]) => void"
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "surface.elevated",
+    "surface.muted",
+    "border.faint",
+    "border.focus",
+    "radius.surfaceMd",
+    "radius.controlMd",
+    "shadow.sm",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "icon.muted"
+  ],
+  "a11y": {
+    "element": "table",
+    "requirements": [
+      "table + thead th scope=col",
+      "caption element when set",
+      "search input aria-label from searchPlaceholder",
+      "filter DropdownMenu ariaLabel = filter label",
+      "Columns button aria-expanded / aria-haspopup",
+      "Row checkboxes ariaLabel like Select Maya Chen; header Select all rows",
+      "sortable th aria-sort none | ascending | descending"
+    ]
+  },
+  "doNot": [
+    "Do not use a native select for filters \u2014 use kit DropdownMenu",
+    "Do not wrap search in Field \u2014 DataTable owns its input",
+    "Do not invent FilterBar, ColumnPicker, DataGrid, Pagination, or a second Table",
+    "Do not invent a local Cell, DataTableCell, HeaderCell, Tag, Trend, FileIcon, or PaymentMethod \u2014 use Cell and HeaderCell",
+    "Do not use TanStack Table, cmdk, Storybook, Figma, or extra dependencies",
+    "Do not use raw hex",
+    "Do not put a checkbox on every Cell \u2014 row selection stays on DataTable",
+    "Do not add pagination, loading, row actions, expandable rows, sticky header, density, infinite scroll, or a bulk-action bar",
+    "Do not invent a SortButton or use TanStack Table for sort"
+  ],
+  "snippet": "<DataTable\n  caption=\"Team members\"\n  selectable\n  toolbar\n  searchPlaceholder=\"Search members...\"\n  filters={[\n    { key: \"status\", label: \"Status\" },\n    { key: \"role\", label: \"Role\" },\n  ]}\n  columnSettings\n  columns={[\n    { key: \"name\", header: \"Name\", sortable: true },\n    { key: \"role\", header: \"Role\", sortable: true },\n    { key: \"status\", header: \"Status\", sortable: true },\n    { key: \"projects\", header: \"Projects\", type: \"number\", sortable: true },\n  ]}\n  rows={rows}\n/>",
+  "contains": [
+    "cell",
+    "headercell",
+    "checkbox",
+    "button",
+    "dropdownmenu"
+  ]
+}

package/contracts/datepicker.json

@@ -0,0 +1,102 @@
+{
+  "id": "datepicker",
+  "status": "stable",
+  "intent": "Form field that opens kit Calendar to pick one date.",
+  "useWhen": [
+    "A date in a form or filter",
+    "Need a typed-looking field whose overlay is Calendar"
+  ],
+  "doNotUseWhen": [
+    "The month grid is already on the page \u2014 use Calendar",
+    "Time-only \u2014 ask first",
+    "A range of dates \u2014 not in this contract, ask first"
+  ],
+  "contains": [
+    "calendar"
+  ],
+  "props": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "note": "For Field htmlFor"
+    },
+    "value": {
+      "type": "string",
+      "required": false,
+      "note": "controlled YYYY-MM-DD"
+    },
+    "defaultValue": {
+      "type": "string",
+      "required": false,
+      "note": "uncontrolled YYYY-MM-DD"
+    },
+    "onValueChange": {
+      "type": "function",
+      "required": false,
+      "note": "(date: string) => void // ISO date"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "md",
+        "sm"
+      ],
+      "default": "md",
+      "note": "Trigger size; Calendar in the overlay is sm when size is sm, else md"
+    },
+    "placeholder": {
+      "type": "string",
+      "default": "Pick a date"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "error": {
+      "type": "boolean",
+      "default": false
+    },
+    "minDate": {
+      "type": "string",
+      "required": false,
+      "note": "Passed to kit Calendar"
+    },
+    "maxDate": {
+      "type": "string",
+      "required": false,
+      "note": "Passed to kit Calendar"
+    },
+    "name": {
+      "type": "string",
+      "required": false,
+      "note": "Hidden input for forms"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "icon.muted",
+    "surface.card",
+    "border.faint",
+    "border.focus",
+    "status.danger",
+    "space.1",
+    "space.2"
+  ],
+  "a11y": {
+    "element": "button",
+    "requirements": [
+      "Trigger is a button with aria-haspopup=dialog, aria-expanded, aria-controls",
+      "Overlay is role=dialog labelled Choose date and contains kit Calendar",
+      "Escape and pointer down outside close and return focus to the trigger",
+      "Must have associated label via Field or a visible label pointing at id"
+    ]
+  },
+  "doNot": [
+    "Do not invent a local calendar, Popover, DatePickerDialog, or native input type=date",
+    "Do not use raw hex",
+    "Do not skip kit Calendar in the overlay",
+    "Do not add range selection in this contract"
+  ],
+  "snippet": "<Field label=\"Start date\" htmlFor=\"start-date\"><DatePicker id=\"start-date\" value={date} onValueChange={setDate} /></Field>"
+}

package/contracts/drawer.json

@@ -0,0 +1,93 @@
+{
+  "id": "drawer",
+  "status": "stable",
+  "intent": "Edge panel for secondary tasks. Floating sheet inset from the opening edge.",
+  "useWhen": [
+    "Settings",
+    "Filters",
+    "Detail alongside the page",
+    "Mobile-style sheet from the bottom"
+  ],
+  "doNotUseWhen": [
+    "Centered short task \u2014 use Modal",
+    "Must-choose confirm \u2014 use AlertDialog",
+    "Persistent nav list \u2014 use AppNav",
+    "Closeable app chrome \u2014 use SideNav",
+    "Full page \u2014 use a route"
+  ],
+  "props": {
+    "open": {
+      "type": "boolean",
+      "required": true
+    },
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "description": {
+      "type": "string",
+      "required": false
+    },
+    "side": {
+      "type": "enum",
+      "values": [
+        "right",
+        "left",
+        "bottom",
+        "top"
+      ],
+      "default": "right",
+      "note": "Floating sheet with radius-surface-lg. Right/left inset from top, bottom, and the opening edge. Bottom is centered. Top insets from top, left, and right. Not a flush full-bleed bar."
+    },
+    "showClose": {
+      "type": "boolean",
+      "default": true
+    },
+    "onClose": {
+      "type": "function",
+      "required": true
+    },
+    "children": {
+      "type": "slot",
+      "required": true,
+      "note": "Body"
+    },
+    "footer": {
+      "type": "slot",
+      "required": false,
+      "note": "kit Buttons. Bottom stacks them full width. Use shape=pill and block."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "surface.overlay",
+    "surface.elevated",
+    "border.faint",
+    "border.focus",
+    "shadow.md",
+    "motion.overlay",
+    "motion.modal",
+    "icon.muted",
+    "radius.surfaceLg",
+    "surface.card"
+  ],
+  "a11y": {
+    "element": "dialog",
+    "requirements": [
+      "role=dialog and aria-modal",
+      "Title is the accessible name, description is aria-describedby when present",
+      "Focus is trapped while open",
+      "Escape closes",
+      "Overlay click closes",
+      "Unique ids via useId"
+    ]
+  },
+  "doNot": [
+    "Do not invent Sheet, SidePanel, or local Drawer",
+    "Do not use raw hex",
+    "Do not add snap points or swipe",
+    "Do not skip the close control unless showClose is false AND footer/body still provide a way out. Overlay click and Escape still close."
+  ],
+  "snippet": "<Drawer open={open} title=\"Pick a delivery time\" description=\"We'll prepare your order as soon as possible.\" side=\"bottom\" showClose={false} onClose={close} footer={<><Button variant=\"primary\" size=\"lg\" shape=\"pill\" block>Confirm Delivery Time</Button><Button variant=\"secondary\" size=\"lg\" shape=\"pill\" block onClick={close}>Cancel</Button></>}><RadioGroup name=\"delivery-time\" legend=\"Delivery time\" hideLegend layout=\"card\" defaultValue=\"standard\" options={slots} /></Drawer>"
+}

package/contracts/dropdownmenu.json

@@ -0,0 +1,190 @@
+{
+  "id": "dropdownmenu",
+  "status": "stable",
+  "intent": "Actions or value menu from a button, field, or nav trigger.",
+  "useWhen": [
+    "A button that opens a short list of actions",
+    "Row actions in a DataTable via Cell type=actionMenu",
+    "Select composes this with triggerStyle=field"
+  ],
+  "doNotUseWhen": [
+    "Choosing one value in a form \u2014 use Select (it composes this with triggerStyle=field)",
+    "Searchable commands \u2014 use Command in a Modal",
+    "Must-choose confirm \u2014 use AlertDialog",
+    "Top-of-page site nav with dropdowns \u2014 use NavigationMenu (it composes this with triggerStyle=nav)"
+  ],
+  "props": {
+    "trigger": {
+      "type": "string",
+      "required": false,
+      "note": "Kit Button label. Omit for icon-only; then ariaLabel is required."
+    },
+    "iconStart": {
+      "type": "string",
+      "required": false,
+      "note": "Lucide name on the kit Button"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "required when trigger is omitted"
+    },
+    "variant": {
+      "type": "enum",
+      "values": [
+        "primary",
+        "secondary",
+        "tertiary",
+        "danger"
+      ],
+      "default": "secondary"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "default": "md"
+    },
+    "align": {
+      "type": "enum",
+      "values": [
+        "start",
+        "end"
+      ],
+      "default": "start"
+    },
+    "groups": {
+      "type": "array",
+      "required": true,
+      "itemShape": {
+        "heading": "string?",
+        "items": [
+          {
+            "id": "string",
+            "label": "string",
+            "icon": "string?",
+            "shortcut": "string?",
+            "disabled": "boolean?",
+            "danger": "boolean?",
+            "submenu": "DropdownMenuGroup[]? one level",
+            "description": "string?",
+            "href": "string? renders a when set and not disabled",
+            "selected": "boolean? Check when true unless checkbox is set.",
+            "checkbox": "boolean? Compose kit Checkbox (visual, inert). Not DropdownMenuCheckboxItem."
+          }
+        ]
+      }
+    },
+    "open": {
+      "type": "boolean",
+      "required": false,
+      "note": "controlled"
+    },
+    "onOpenChange": {
+      "type": "function",
+      "required": false,
+      "note": "(open: boolean) => void"
+    },
+    "onSelect": {
+      "type": "function",
+      "required": false,
+      "note": "(id: string) => void"
+    },
+    "triggerStyle": {
+      "type": "enum",
+      "values": [
+        "button",
+        "field",
+        "nav"
+      ],
+      "default": "button",
+      "note": "button is kit Button. field is a full-width control with ChevronsUpDown. Select uses field. nav is a ghost text control with ChevronDown; NavigationMenu uses nav."
+    },
+    "iconEnd": {
+      "type": "string",
+      "required": false,
+      "note": "Lucide name on a field trigger (default ChevronsUpDown) or kit Button trigger."
+    },
+    "columns": {
+      "type": "enum",
+      "values": [
+        1,
+        2
+      ],
+      "default": 1,
+      "note": "2 uses a CSS grid panel, min-width 28rem. 1 stays a list."
+    },
+    "closeOnSelect": {
+      "type": "boolean",
+      "default": true,
+      "note": "false keeps the menu open. Select multiple uses false."
+    },
+    "triggerMuted": {
+      "type": "boolean",
+      "default": false,
+      "note": "Muted field trigger text for a placeholder."
+    },
+    "triggerBadge": {
+      "type": "string",
+      "required": false,
+      "note": "Kit Badge on a field trigger next to the label, e.g. +2. Select overflow uses this."
+    },
+    "searchable": {
+      "type": "boolean",
+      "default": false,
+      "note": "Kit Input at the top of the panel. Filters item labels. Select searchable uses this."
+    },
+    "searchPlaceholder": {
+      "type": "string",
+      "required": false,
+      "default": "Search"
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "surface.muted",
+    "border.faint",
+    "border.focus",
+    "radius.surface.sm",
+    "shadow.sm",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "text.danger",
+    "icon.muted",
+    "type.size.caption",
+    "type.weight.label",
+    "radius.control.md",
+    "focus.ring"
+  ],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "Trigger has aria-haspopup=menu, aria-expanded, aria-controls. button is kit Button; field is a field control; nav is a ghost text control",
+      "Panel is role=menu",
+      "Items are role=menuitem, or menuitemcheckbox when checkbox is set. aria-disabled when disabled. With href and not disabled, the item is an a",
+      "Escape and outside click close; arrows move; Tab closes. Search Input is focused first when searchable",
+      "Icon-only trigger needs ariaLabel",
+      "Item with submenu has aria-haspopup=menu and ChevronRight; ArrowRight opens, ArrowLeft closes"
+    ]
+  },
+  "doNot": [
+    "Do not invent DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuSub, or DropdownMenuPortal",
+    "Do not use Select for actions from a button",
+    "Do not use Command or Modal for a small action menu",
+    "Do not invent DropdownMenuSub \u2014 nest groups on the item, one level",
+    "Do not invent CheckboxItem or RadioItem cousins \u2014 compose kit Checkbox on the item",
+    "Do not use radix, cmdk, or @base-ui/react",
+    "Do not use raw hex"
+  ],
+  "contains": [
+    "button",
+    "checkbox",
+    "input",
+    "badge"
+  ],
+  "snippet": "<DropdownMenu\n  trigger=\"Open\"\n  groups={[{\n    heading: \"My Account\",\n    items: [\n      { id: \"profile\", label: \"Profile\", shortcut: \"\u21e7\u2318P\" },\n      { id: \"invite\", label: \"Invite users\", submenu: [{ items: [{ id: \"email\", label: \"Email\" }] }] },\n    ],\n  }]}\n  onSelect={(id) => {}}\n/>"
+}

package/contracts/empty.json

@@ -0,0 +1,79 @@
+{
+  "id": "empty",
+  "status": "stable",
+  "intent": "Placeholder when a list, page, or region has nothing to show. One piece.",
+  "useWhen": [
+    "A list or table has no rows",
+    "A page section has no content yet",
+    "A panel needs a centered placeholder with optional actions"
+  ],
+  "doNotUseWhen": [
+    "Inline page status — use Alert",
+    "Chart with no data — charts use their own emptyLabel",
+    "Loading with no content — use Spinner or LoadingAnimation"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": true,
+      "note": "Primary heading for the empty state."
+    },
+    "description": {
+      "type": "string",
+      "required": false,
+      "note": "Supporting copy under the title."
+    },
+    "icon": {
+      "type": "string",
+      "required": false,
+      "note": "Lucide export name. Shown in a circular media well. Not EmptyMedia."
+    },
+    "media": {
+      "type": "slot",
+      "required": false,
+      "note": "Custom media slot. Compose kit Avatar or AvatarGroup. Not EmptyMedia."
+    },
+    "actions": {
+      "type": "slot",
+      "required": false,
+      "note": "Action row. Compose kit Buttons only. Not EmptyContent."
+    },
+    "outlined": {
+      "type": "boolean",
+      "default": false,
+      "note": "Bordered empty state with surface-card background."
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "surface.muted",
+    "text.primary",
+    "text.secondary",
+    "icon.secondary",
+    "border.faint",
+    "radius.surfaceSm",
+    "radius.full",
+    "space.2",
+    "space.3",
+    "space.4",
+    "space.6",
+    "type.size.heading",
+    "type.size.bodySm",
+    "type.weight.heading",
+    "type.weight.body"
+  ],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "Title uses a heading element",
+      "Icon media is aria-hidden",
+      "Actions are regular interactive controls"
+    ]
+  },
+  "doNot": [
+    "Do not invent EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, or EmptyContent",
+    "Do not use raw hex",
+    "Do not use glass, color-mix, or backdrop-blur"
+  ],
+  "snippet": "<Empty title=\"No projects yet\" description=\"You haven't created any projects yet.\" icon=\"Folder\" actions={<><Button>Create</Button><Button variant=\"secondary\">Import</Button></>} />"
+}

package/contracts/field.json

@@ -0,0 +1,49 @@
+{
+  "id": "field",
+  "status": "stable",
+  "intent": "One labeled control with optional hint and error. Label on top or start (left).",
+  "useWhen": [
+    "Any labeled Input, Textarea, Select, DatePicker, or Switch",
+    "When helper text or a validation error sits with the control"
+  ],
+  "doNotUseWhen": [
+    "Checkbox with its own label and no extra hint/error — use Checkbox",
+    "RadioGroup — it provides its own legend",
+    "A group of fields with a legend — use FieldSet",
+    "Display-only content — use Section"
+  ],
+  "props": {
+    "label": { "type": "string", "required": true },
+    "htmlFor": { "type": "string", "required": true },
+    "hint": { "type": "string", "required": false, "note": "helper text. Hidden when error is set." },
+    "error": { "type": "string", "required": false },
+    "labelPosition": {
+      "type": "enum",
+      "values": ["top", "start"],
+      "default": "top",
+      "note": "top stacks. start is horizontal (label left). Hint and error stay under the control."
+    },
+    "children": {
+      "type": "slot",
+      "allowedContracts": ["input", "textarea", "select", "datepicker", "switch", "checkbox"],
+      "required": true
+    }
+  },
+  "tokens": ["text.primary", "text.muted", "text.danger"],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "role=group",
+      "Label htmlFor matches child control id",
+      "Hint or error id is passed to the child as describedBy",
+      "data-invalid when error is set"
+    ]
+  },
+  "doNot": [
+    "Do not invent FieldLabel, FieldContent, FieldDescription, FieldError, FieldTitle, FieldGroup, FieldLegend, FieldSeparator, Form, FormField, FormItem, FormControl, or FormMessage",
+    "Do not wrap Button or layout components",
+    "Do not use start on Field for prefix text — that is Input start",
+    "Do not use raw hex"
+  ],
+  "snippet": "<Field label=\"Email\" htmlFor=\"email\" hint=\"We never share your email.\"><Input id=\"email\" type=\"email\" /></Field>"
+}

package/contracts/fieldset.json

@@ -0,0 +1,29 @@
+{
+  "id": "fieldset",
+  "status": "stable",
+  "intent": "Semantic group of fields with a legend and optional description.",
+  "useWhen": [
+    "Related fields that need a shared heading, like billing or profile",
+    "A checkbox or switch sitting under a group legend"
+  ],
+  "doNotUseWhen": [
+    "A single labeled control — use Field",
+    "Page title — use PageHeader or Card title"
+  ],
+  "props": {
+    "legend": { "type": "string", "required": true },
+    "description": { "type": "string", "required": false },
+    "children": { "type": "slot", "required": true, "note": "kit Field, Checkbox, Switch, or RadioGroup" }
+  },
+  "tokens": ["text.primary", "text.muted"],
+  "a11y": {
+    "element": "fieldset",
+    "requirements": ["legend is the accessible name of the group"]
+  },
+  "doNot": [
+    "Do not invent FieldLegend, FieldGroup, or FieldSeparator",
+    "Do not nest FieldSet unless the inner group is truly nested",
+    "Do not use raw hex"
+  ],
+  "snippet": "<FieldSet legend=\"Billing Address\" description=\"The billing address associated with your payment method\"><Checkbox id=\"same\" label=\"Same as shipping address\" /></FieldSet>"
+}