@slipstream-ui/core 0.3.0 → 0.4.0

package/dist/manifests/app-shell.manifest.json

@@ -0,0 +1,156 @@
+{
+  "id": "app-shell",
+  "name": "AppShell",
+  "tier": "organism",
+  "description": "Application frame with a sectioned sidebar, sticky header and scrolling main; the sidebar becomes a left Drawer on small screens.",
+  "designIntent": "Every dashboard hand-rolls the same shell: rail, header, scroll owner, and a mobile nav. AppShell owns the structure and responsive switch while staying presentational — you pass the active route and a router link component, so it works with React Router, Next Link, or plain anchors.",
+  "props": [
+    {
+      "name": "sidebar",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Desktop rail content; also rendered inside the mobile drawer (AppShell)."
+    },
+    {
+      "name": "header",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Sticky top bar content (AppShell)."
+    },
+    {
+      "name": "hideMobileMenu",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Hide the built-in burger button when the header owns navigation (AppShell)."
+    },
+    {
+      "name": "sidebarWidth",
+      "type": "string",
+      "required": false,
+      "defaultValue": "w-64",
+      "description": "Tailwind width class for the desktop rail (AppShell)."
+    },
+    {
+      "name": "sections",
+      "type": "{ title?: string; items: SidebarItem[] }[]",
+      "required": true,
+      "description": "Grouped navigation items (Sidebar)."
+    },
+    {
+      "name": "heading",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Brand/mark at the top of the rail (Sidebar)."
+    },
+    {
+      "name": "footer",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Bottom area of the rail (Sidebar)."
+    },
+    {
+      "name": "activeHref",
+      "type": "string",
+      "required": false,
+      "description": "Current route; matching items get aria-current=page (Sidebar)."
+    },
+    {
+      "name": "linkComponent",
+      "type": "React.ElementType",
+      "required": false,
+      "defaultValue": "a",
+      "description": "Router link component (react-router Link, Next Link) (Sidebar)."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Primary",
+      "description": "Accessible name of the nav landmark (Sidebar)."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Dashboard shell",
+      "code": "import { AppShell, Sidebar } from '@slipstream-ui/core';\n\n<AppShell\n  header={<h1 className=\"text-sm font-semibold\">Studio</h1>}\n  sidebar={\n    <Sidebar\n      activeHref={pathname}\n      linkComponent={RouterLink}\n      heading={<strong>Acme</strong>}\n      sections={[\n        { title: 'Workspace', items: [{ href: '/dashboard', label: 'Dashboard' }, { href: '/classes', label: 'Classes', badge: 4 }] },\n      ]}\n    />\n  }\n>\n  <Page />\n</AppShell>",
+      "description": "Router-agnostic: pass your Link component and the current path."
+    },
+    {
+      "title": "Header only",
+      "code": "<AppShell header={<TopBar />}>\n  <Page />\n</AppShell>",
+      "description": "Skip the sidebar when the product is a single surface."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't nest scroll containers",
+      "explanation": "AppShell's main is the scroll owner. Adding h-screen/overflow-hidden wrappers inside breaks sticky headers and mobile drawer focus.",
+      "example": "// Avoid\n<AppShell><div className=\"h-screen overflow-hidden\">…</div></AppShell>\n\n// Prefer\n<AppShell><Page /></AppShell>"
+    },
+    {
+      "title": "Don't hardcode anchors for SPA routes",
+      "explanation": "Plain <a href> triggers full page loads in client-side routers. Pass your router's Link via linkComponent.",
+      "example": "// Avoid (full reload in React Router)\n<Sidebar sections={sections} />\n\n// Prefer\n<Sidebar sections={sections} linkComponent={Link} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Nav landmark",
+      "implementation": "Sidebar renders nav with an accessible name (label prop)",
+      "userRequirements": "Keep one primary nav per page; use other labels for secondary rails"
+    },
+    {
+      "feature": "Current route",
+      "implementation": "aria-current=page on the active item",
+      "userRequirements": "Pass activeHref (or item.active) so the state is announced"
+    },
+    {
+      "feature": "Mobile drawer",
+      "implementation": "The rail becomes a Drawer with focus trap, Escape, focus restore and a labelled dialog",
+      "userRequirements": "Don't duplicate the nav in two places at once"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Item labels",
+      "guidelines": [
+        "Use nouns for destinations",
+        "Keep to 1-2 words",
+        "Group by workflow, not by component type"
+      ],
+      "goodExamples": [
+        "Dashboard",
+        "Classes",
+        "Settings"
+      ],
+      "badExamples": [
+        "Click here",
+        "List page component"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Drawer",
+      "relationship": "AppShell mounts the mobile navigation Drawer for you when a sidebar is provided",
+      "example": "<AppShell sidebar={<Sidebar sections={sections} />}>…</AppShell>"
+    },
+    {
+      "component": "Button",
+      "relationship": "Header actions live in the header slot",
+      "example": "<AppShell header={<Button>New</Button>}>…</AppShell>"
+    }
+  ],
+  "relatedComponents": [
+    "Drawer",
+    "Button",
+    "Breadcrumb",
+    "Menu"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "app-shell",
+  "exportName": "AppShell"
+}

package/dist/manifests/auth-layout.manifest.json

@@ -0,0 +1,99 @@
+{
+  "id": "auth-layout",
+  "name": "AuthLayout",
+  "tier": "organism",
+  "description": "Centered authentication surface: brand, title/description, form card and footer, with size presets.",
+  "designIntent": "Sign-in, sign-up, reset and verify screens should look identical. AuthLayout owns the centered card, brand slot and footer so auth pages only supply the form.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "description": "Card heading (h1)."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "description": "Supporting line under the heading."
+    },
+    {
+      "name": "brand",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Mark rendered above the card."
+    },
+    {
+      "name": "footer",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Links/legal copy under the card."
+    },
+    {
+      "name": "size",
+      "type": "'sm' | 'md' | 'lg'",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Card width preset.",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    }
+  ],
+  "examples": [
+    {
+      "title": "Sign in",
+      "code": "<AuthLayout\n  title=\"Sign in\"\n  description=\"Welcome back.\"\n  brand={<Logo />}\n  footer={<a href=\"/signup\">Create account</a>}\n>\n  <SignInForm />\n</AuthLayout>",
+      "description": "Form lives inside the card."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't nest another full-height page",
+      "explanation": "AuthLayout already owns min-h-screen centering.",
+      "example": "// Avoid\n<div className=\"min-h-screen\"><AuthLayout … /></div>"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "One h1",
+      "implementation": "Renders the page heading",
+      "userRequirements": "Don't add another h1 inside the form"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Titles",
+      "guidelines": [
+        "Action-oriented",
+        "Sentence case"
+      ],
+      "goodExamples": [
+        "Sign in",
+        "Create your account"
+      ],
+      "badExamples": [
+        "Login page"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Form",
+      "relationship": "Place the Form inside children",
+      "example": "<AuthLayout title=\"Sign in\"><Form onSubmit={…}>…</Form></AuthLayout>"
+    }
+  ],
+  "relatedComponents": [
+    "Form",
+    "PasswordInput",
+    "Button"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "auth-layout",
+  "exportName": "AuthLayout"
+}

package/dist/manifests/autocomplete.manifest.json

@@ -2,14 +2,14 @@
   "id": "autocomplete",
   "name": "Autocomplete",
   "tier": "molecule",
-  "description": "Type-ahead input following the HTML autocomplete model: any value is allowed while matching suggestions appear in a keyboard-navigable listbox.",
-  "designIntent": "Form fields often need both freedom and guidance — usernames, tags, city names. Autocomplete extends the native autocomplete spec: the input stays a normal controlled input (native autoComplete hints keep working), and an ARIA combobox listbox overlays suggestions. Unlike Search, no option constrains the result.",
+  "description": "Free-text type-ahead input with a portalled listbox: static or async options, grouped headings, descriptions and custom rows.",
+  "designIntent": "Free text stays first-class: any value may be typed, while matching options accelerate entry. Async sources are debounced with stale-response guards; grouped headings and custom rows cover searchable-select patterns; Escape/arrow keys follow the combobox model.",
   "props": [
     {
       "name": "suggestions",
       "type": "string[]",
-      "required": true,
-      "description": "Suggestion labels offered while typing; any value may still be entered free-form.",
+      "required": false,
+      "description": "Deprecated — use options.",
       "examples": [
         "['react', 'remix', 'astro']"
       ]
@@ -43,13 +43,61 @@
       "name": "emptyText",
       "type": "string",
       "required": false,
-      "description": "Shown when no suggestion matches (optional; defaults to 'No suggestions').",
+      "description": "Shown when no option matches.",
       "examples": [
         "'No matches — press Enter to use your text'"
       ]
+    },
+    {
+      "name": "options",
+      "type": "Array<string | AutocompleteOption>",
+      "required": false,
+      "description": "Static options; strings or { value, label?, group?, description? }."
+    },
+    {
+      "name": "loadOptions",
+      "type": "(query: string) => Promise<Array<string | AutocompleteOption>>",
+      "required": false,
+      "description": "Async option source; debounced and guarded against stale responses."
+    },
+    {
+      "name": "renderOption",
+      "type": "(option, state: { active: boolean }) => ReactNode",
+      "required": false,
+      "description": "Custom row renderer."
+    },
+    {
+      "name": "clearable",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Shows a clear button once the field has text."
+    },
+    {
+      "name": "loadingText",
+      "type": "string",
+      "required": false,
+      "description": "Shown while async options load."
+    },
+    {
+      "name": "debounceMs",
+      "type": "number",
+      "required": false,
+      "defaultValue": "200",
+      "description": "Debounce for loadOptions in ms."
     }
   ],
   "examples": [
+    {
+      "title": "Async search",
+      "code": "<Autocomplete\n  aria-label=\"Search people\"\n  clearable\n  loadOptions={async (query) => searchPeople(query)}\n/>",
+      "description": "Debounced async source with stale-response guard and clear."
+    },
+    {
+      "title": "Grouped options with descriptions",
+      "code": "<Autocomplete\n  aria-label=\"Search\"\n  options={[\n    { value: 'ada', label: 'Ada Lovelace', group: 'People', description: 'Mathematician' },\n    { value: 'rust', label: 'Rust', group: 'Languages' },\n  ]}\n/>",
+      "description": "Section headings plus a supporting line per row."
+    },
     {
       "title": "Controlled form field",
       "code": "const [framework, setFramework] = useState('');\n\n<FormField id=\"framework\" label=\"Primary framework\" hint=\"Type or pick a suggestion\">\n  <Autocomplete\n    suggestions={['react', 'remix', 'next', 'vite']}\n    value={framework}\n    onValueChange={setFramework}\n    name=\"framework\"\n    autoComplete=\"off\"\n  />\n</FormField>",

package/dist/manifests/badge.manifest.json

@@ -40,9 +40,21 @@
       "type": "string",
       "required": false,
       "description": "Additional CSS classes to apply"
+    },
+    {
+      "name": "asChild",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render the child element (e.g. a router Link) with badge styling."
     }
   ],
   "examples": [
+    {
+      "title": "Tag linking to a filter",
+      "code": "<Badge asChild>\n  <Link href=\"/tags/react\">React</Link>\n</Badge>",
+      "description": "Tag that navigates."
+    },
     {
       "title": "Default badge",
       "code": "<Badge>New</Badge>",

package/dist/manifests/button.manifest.json

@@ -7,7 +7,7 @@
   "props": [
     {
       "name": "variant",
-      "type": "'default' | 'destructive' | 'success' | 'warning' | 'info' | 'outline' | 'secondary' | 'ghost' | 'link'",
+      "type": "'default' | 'destructive' | 'success' | 'warning' | 'info' | 'outline' | 'outline-destructive' | 'outline-success' | 'outline-warning' | 'outline-info' | 'secondary' | 'ghost' | 'link'",
       "defaultValue": "default",
       "required": false,
       "description": "Visual style variant of the button",
@@ -20,7 +20,11 @@
         "link",
         "success",
         "warning",
-        "info"
+        "info",
+        "outline-destructive",
+        "outline-success",
+        "outline-warning",
+        "outline-info"
       ],
       "examples": [
         "default",

package/dist/manifests/card.manifest.json

@@ -5,10 +5,32 @@
   "description": "A content container with header, body, and footer sections for grouping related information",
   "designIntent": "Card groups related content into a scannable container. Use it for settings panels, feature highlights, user profiles, and any content that benefits from visual grouping.",
   "props": [
-    { "name": "children", "type": "ReactNode", "required": true, "description": "Card sub-components (CardHeader, CardContent, CardFooter)" },
-    { "name": "className", "type": "string", "required": false, "description": "Additional CSS classes to apply" }
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "description": "Card sub-components (CardHeader, CardContent, CardFooter)"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "description": "Additional CSS classes to apply"
+    },
+    {
+      "name": "asChild",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render the child element (router Link, <a>) with card styling instead of a div."
+    }
   ],
   "examples": [
+    {
+      "title": "Card as a link",
+      "code": "<Card asChild>\n  <Link href=\"/writing/hello\">\n    <CardHeader><CardTitle>Hello</CardTitle></CardHeader>\n  </Link>\n</Card>",
+      "description": "Whole card becomes a semantic link without losing styling."
+    },
     {
       "title": "Basic card",
       "code": "<Card>\n  <CardHeader>\n    <CardTitle>Profile</CardTitle>\n    <CardDescription>Manage your account settings</CardDescription>\n  </CardHeader>\n  <CardContent>Form fields here</CardContent>\n  <CardFooter>\n    <Button>Save</Button>\n  </CardFooter>\n</Card>",
@@ -28,15 +50,40 @@
     }
   ],
   "accessibility": [
-    { "feature": "Heading hierarchy", "implementation": "CardTitle renders as h3", "userRequirements": "Maintain logical heading order in your page" }
+    {
+      "feature": "Heading hierarchy",
+      "implementation": "CardTitle renders as h3",
+      "userRequirements": "Maintain logical heading order in your page"
+    }
   ],
   "contentGuidelines": [
-    { "contentType": "Card titles", "guidelines": ["Keep titles short (2-5 words)", "Use sentence case"], "goodExamples": ["Profile settings", "Billing overview"], "badExamples": ["Card title", "Section"] }
+    {
+      "contentType": "Card titles",
+      "guidelines": [
+        "Keep titles short (2-5 words)",
+        "Use sentence case"
+      ],
+      "goodExamples": [
+        "Profile settings",
+        "Billing overview"
+      ],
+      "badExamples": [
+        "Card title",
+        "Section"
+      ]
+    }
   ],
   "compositionRules": [
-    { "component": "Button", "relationship": "Place primary actions in CardFooter", "example": "<CardFooter><Button>Save</Button></CardFooter>" }
+    {
+      "component": "Button",
+      "relationship": "Place primary actions in CardFooter",
+      "example": "<CardFooter><Button>Save</Button></CardFooter>"
+    }
+  ],
+  "relatedComponents": [
+    "Separator",
+    "Tabs"
   ],
-  "relatedComponents": ["Separator", "Tabs"],
   "package": "@slipstream-ui/core",
   "importPath": "@slipstream-ui/core",
   "version": "0.1.0",

package/dist/manifests/date-picker.manifest.json

@@ -0,0 +1,87 @@
+{
+  "id": "date-picker",
+  "name": "DatePicker",
+  "tier": "molecule",
+  "description": "Native date field with an ISO-string contract, min/max passthrough and an optional clear button.",
+  "designIntent": "A custom calendar is a large accessibility surface. The platform date picker already handles locale formatting, keyboard editing and mobile wheels, so DatePicker standardizes the ISO contract and a clear affordance instead of reimplementing a calendar.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "description": "ISO date (YYYY-MM-DD), controlled."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "required": false,
+      "description": "ISO date, initial value."
+    },
+    {
+      "name": "onValueChange",
+      "type": "(value: string) => void",
+      "required": false,
+      "description": "Fired with the ISO string; '' when cleared."
+    },
+    {
+      "name": "clearable",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Shows a clear button once a value exists."
+    }
+  ],
+  "examples": [
+    {
+      "title": "ISO date field",
+      "code": "<DatePicker\n  aria-label=\"Start date\"\n  value={start}\n  onValueChange={setStart}\n  clearable\n/>",
+      "description": "Controlled ISO value with a clear button."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't store locale-formatted strings",
+      "explanation": "The contract is YYYY-MM-DD; format for display at the edge.",
+      "example": "// Avoid: '03/11/2026' in state\n// Prefer: '2026-11-03'"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Platform input",
+      "implementation": "Renders input[type=date] so OS pickers and keyboard editing apply",
+      "userRequirements": "Always provide a label (FormField or aria-label)"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Labels",
+      "guidelines": [
+        "Name the date's meaning, not 'Date'"
+      ],
+      "goodExamples": [
+        "Start date",
+        "Due on"
+      ],
+      "badExamples": [
+        "Date"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "FormField",
+      "relationship": "Wrap for label/hint/error wiring",
+      "example": "<FormField id=\"start\" label=\"Start date\"><DatePicker /></FormField>"
+    }
+  ],
+  "relatedComponents": [
+    "TimePicker",
+    "FormField",
+    "Input"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "date-picker",
+  "exportName": "DatePicker"
+}

package/dist/manifests/dialog.manifest.json

@@ -2,7 +2,7 @@
   "id": "dialog",
   "name": "Dialog",
   "tier": "molecule",
-  "description": "Accessible modal dialog with focus trapping, escape-to-close and focus restoration",
+  "description": "Accessible modal dialog with focus trap/restore, backdrop and Escape dismissal, size presets, optional header/footer slots, a scrollable body, and opt-in fade motion.",
   "designIntent": "Modals interrupt the task flow on purpose: confirmations, small forms, and destructive-action guards. The Dialog implements the full modal contract — aria-modal labelling, initial focus, a Tab focus trap, Escape and backdrop dismissal, and focus restoration to the opener — so consumers never hand-roll focus management.",
   "props": [
     {
@@ -20,8 +20,8 @@
     {
       "name": "title",
       "type": "string",
-      "required": true,
-      "description": "Accessible dialog name, wired via aria-labelledby"
+      "required": false,
+      "description": "Accessible name + default header title. Optional when composing a custom header with ariaLabel."
     },
     {
       "name": "description",
@@ -69,6 +69,49 @@
         "true",
         "false"
       ]
+    },
+    {
+      "name": "size",
+      "type": "'sm' | 'md' | 'lg' | 'xl' | '2xl'",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Panel max-width preset.",
+      "enum": [
+        "sm",
+        "md",
+        "lg",
+        "xl",
+        "2xl"
+      ],
+      "examples": [
+        "lg",
+        "2xl"
+      ]
+    },
+    {
+      "name": "header",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Replaces the default header row — compose with DialogHeader/DialogTitle/DialogDescription (ids wire automatically)."
+    },
+    {
+      "name": "footer",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Action row pinned under the body."
+    },
+    {
+      "name": "scrollable",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Caps the body height and scrolls inside the panel."
+    },
+    {
+      "name": "bodyClassName",
+      "type": "string",
+      "required": false,
+      "description": "Extra classes for the body wrapper."
     }
   ],
   "examples": [
@@ -107,7 +150,9 @@
   ],
   "relatedComponents": [
     "Button",
-    "Toast"
+    "Toast",
+    "Drawer",
+    "Confirmation"
   ],
   "package": "@slipstream-ui/core",
   "importPath": "@slipstream-ui/core",

package/dist/manifests/drawer.manifest.json

@@ -41,12 +41,26 @@
     },
     {
       "name": "size",
-      "type": "'sm' | 'md' | 'lg'",
+      "type": "'sm' | 'md' | 'lg' | 'xl' | '2xl'",
       "defaultValue": "md",
       "required": false,
-      "description": "Extent along the side axis (width for left/right, height for top/bottom).",
-      "enum": ["sm", "md", "lg"],
-      "examples": ["lg"]
+      "description": "Preset extent along the side axis (width for left/right, height for top/bottom).",
+      "enum": ["sm", "md", "lg", "xl", "2xl"],
+      "examples": ["lg", "xl"]
+    },
+    {
+      "name": "width",
+      "type": "number | string",
+      "required": false,
+      "description": "Custom extent for left/right drawers: pixels (480) or any CSS length (\"70vw\"). Overrides size.",
+      "examples": [480, "70vw"]
+    },
+    {
+      "name": "height",
+      "type": "number | string",
+      "required": false,
+      "description": "Custom extent for top/bottom drawers: pixels (320) or any CSS length (\"60vh\"). Overrides size.",
+      "examples": [320, "60vh"]
     },
     {
       "name": "closeOnBackdrop",