@slipstream-ui/core 0.3.0 → 0.4.0

package/dist/manifests/empty-state.manifest.json

@@ -0,0 +1,108 @@
+{
+  "id": "empty-state",
+  "name": "EmptyState",
+  "tier": "molecule",
+  "description": "Placeholder for empty collections, zero-result searches and unconfigured features, with title, description and action slots.",
+  "designIntent": "Empty states are where users decide what to do next. A consistent icon/title/description/action hierarchy beats ad-hoc 'No data' strings, and a stable structure is easier for screen readers and tests.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "description": "Primary message.",
+      "examples": [
+        "No classes yet"
+      ]
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "description": "Supporting line explaining the next step."
+    },
+    {
+      "name": "icon",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Decorative icon/illustration above the title."
+    },
+    {
+      "name": "action",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Primary action (Button or link)."
+    },
+    {
+      "name": "secondaryAction",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Secondary action beside the primary one."
+    },
+    {
+      "name": "size",
+      "type": "'sm' | 'md'",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Compact padding for panels/table bodies.",
+      "enum": [
+        "sm",
+        "md"
+      ]
+    }
+  ],
+  "examples": [
+    {
+      "title": "Empty collection",
+      "code": "<EmptyState\n  title=\"No classes yet\"\n  description=\"Create your first class to get started.\"\n  action={<Button>New class</Button>}\n/>",
+      "description": "Title, explanation and one primary action."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't use it for errors",
+      "explanation": "Empty is a normal state; failures need Alert/ErrorAlert with retry affordances.",
+      "example": "// Avoid\n<EmptyState title=\"Failed to load\" />\n\n// Prefer\n<Alert variant=\"destructive\">Failed to load. <Button>Retry</Button></Alert>"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Action targets",
+      "implementation": "Actions are whatever you pass — use Button/link components so they stay focusable and announced",
+      "userRequirements": "Always provide a real control, not a bare sentence"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Copy",
+      "guidelines": [
+        "Say what is missing",
+        "Say what to do next",
+        "Avoid blaming the user"
+      ],
+      "goodExamples": [
+        "No classes yet — create your first class"
+      ],
+      "badExamples": [
+        "Empty",
+        "Nothing here"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Card",
+      "relationship": "Often rendered inside a Card body or a DataTable empty slot",
+      "example": "<Card><CardContent><EmptyState … /></CardContent></Card>"
+    }
+  ],
+  "relatedComponents": [
+    "Alert",
+    "Card",
+    "DataTable"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "empty-state",
+  "exportName": "EmptyState"
+}

package/dist/manifests/file-upload.manifest.json

@@ -0,0 +1,103 @@
+{
+  "id": "file-upload",
+  "name": "FileUpload",
+  "tier": "organism",
+  "description": "Drag-and-drop file picker with a removable file list and per-file progress bars.",
+  "designIntent": "File inputs are hard to style and easy to make inaccessible. FileUpload keeps the native input as the real control, adds a drop zone as an enhancement, and exposes plain File objects so the transport and progress stay yours.",
+  "props": [
+    {
+      "name": "files",
+      "type": "File[]",
+      "required": false,
+      "description": "Controlled selection."
+    },
+    {
+      "name": "defaultFiles",
+      "type": "File[]",
+      "required": false,
+      "description": "Initial selection when uncontrolled."
+    },
+    {
+      "name": "onFilesChange",
+      "type": "(files: File[]) => void",
+      "required": false,
+      "description": "Fired on add, drop, remove."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Drop files here or click to browse",
+      "description": "Drop-zone copy."
+    },
+    {
+      "name": "hint",
+      "type": "string",
+      "required": false,
+      "description": "Helper line under the drop zone."
+    },
+    {
+      "name": "progress",
+      "type": "Record<string, number>",
+      "required": false,
+      "description": "Per-file progress 0-100 keyed by file name; renders progress bars."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Attachments with progress",
+      "code": "<FileUpload\n  aria-label=\"Attachments\"\n  accept=\".pdf,.csv\"\n  progress={{ 'report.pdf': 42 }}\n  onFilesChange={setFiles}\n/>",
+      "description": "Native input + drop zone + progress."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't hide the input from the a11y tree",
+      "explanation": "The label targets the real input, keeping keyboard and mobile file dialogs working.",
+      "example": "// Avoid: tabIndex={-1} display:none input\n// Prefer: <FileUpload /> (input is sr-only but focusable)"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Native control",
+      "implementation": "Visible label targets a real (sr-only) file input",
+      "userRequirements": "Provide aria-label or wrap in FormField"
+    },
+    {
+      "feature": "Progress",
+      "implementation": "Each uploading file exposes role=progressbar with a name",
+      "userRequirements": "Keep progress keyed by file name"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Hints",
+      "guidelines": [
+        "State accepted types and size limits"
+      ],
+      "goodExamples": [
+        "PDF or CSV, up to 10 MB"
+      ],
+      "badExamples": [
+        "Upload"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "FormField",
+      "relationship": "Wrap for label/error wiring",
+      "example": "<FormField id=\"files\" label=\"Attachments\"><FileUpload /></FormField>"
+    }
+  ],
+  "relatedComponents": [
+    "Attachment",
+    "FormField",
+    "Progress"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "file-upload",
+  "exportName": "FileUpload"
+}

package/dist/manifests/filter-bar.manifest.json

@@ -0,0 +1,100 @@
+{
+  "id": "filter-bar",
+  "name": "FilterBar",
+  "tier": "molecule",
+  "description": "List-page filter strip: search field, filter controls, reset affordance and trailing actions.",
+  "designIntent": "Filter rows drift: some pages wrap, some scroll, resets appear inconsistently. FilterBar fixes the order (search → filters → reset → trailing) and keeps the strip compact on narrow screens.",
+  "props": [
+    {
+      "name": "searchValue",
+      "type": "string",
+      "required": false,
+      "description": "Controlled search text."
+    },
+    {
+      "name": "onSearchChange",
+      "type": "(value: string) => void",
+      "required": false,
+      "description": "Fires on each keystroke; hides the search box when omitted."
+    },
+    {
+      "name": "searchPlaceholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Search…",
+      "description": "Search input placeholder (also its accessible name)."
+    },
+    {
+      "name": "onReset",
+      "type": "() => void",
+      "required": false,
+      "description": "Shows a reset button when provided."
+    },
+    {
+      "name": "activeCount",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Active filter count appended to the reset label."
+    },
+    {
+      "name": "trailing",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Far-right actions (bulk actions, column settings)."
+    }
+  ],
+  "examples": [
+    {
+      "title": "List filters",
+      "code": "<FilterBar\n  searchValue={query}\n  onSearchChange={setQuery}\n  searchPlaceholder=\"Search students\"\n  onReset={resetFilters}\n  activeCount={activeFilters}\n>\n  <Select label=\"Status\" options={statusOptions} />\n</FilterBar>",
+      "description": "Search, filters, reset and count in one strip."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't put the primary action in the bar",
+      "explanation": "FilterBar is for narrowing; creation actions belong in PageHeader actions.",
+      "example": "// Avoid\n<FilterBar trailing={<Button>New class</Button>} />\n\n// Prefer\n<PageHeader actions={<Button>New class</Button>} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Search landmark",
+      "implementation": "Wraps controls in role=search; the search input is labelled by its placeholder",
+      "userRequirements": "Provide a descriptive placeholder"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Placeholder",
+      "guidelines": [
+        "Name the collection being searched"
+      ],
+      "goodExamples": [
+        "Search students"
+      ],
+      "badExamples": [
+        "Search…"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Select",
+      "relationship": "Filter controls render in children",
+      "example": "<FilterBar><Select … /></FilterBar>"
+    }
+  ],
+  "relatedComponents": [
+    "DataTable",
+    "Select",
+    "Input",
+    "PageHeader"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "filter-bar",
+  "exportName": "FilterBar"
+}

package/dist/manifests/menu.manifest.json

@@ -35,9 +35,21 @@
       "defaultValue": "false",
       "required": false,
       "type": "boolean"
+    },
+    {
+      "name": "asChild",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render the child element (e.g. an <a>) as the menu item (MenuItem)."
     }
   ],
   "examples": [
+    {
+      "title": "Link menu item",
+      "code": "<MenuItem asChild>\n  <a href=\"/settings\">Settings</a>\n</MenuItem>",
+      "description": "Navigation items keep menuitem semantics."
+    },
     {
       "title": "Actions menu",
       "code": "<Menu>\n  <MenuTrigger>Options</MenuTrigger>\n  <MenuContent>\n    <MenuLabel>Actions</MenuLabel>\n    <MenuItem>Profile</MenuItem>\n    <MenuItem>Settings</MenuItem>\n    <MenuSeparator />\n    <MenuItem destructive>Sign out</MenuItem>\n  </MenuContent>\n</Menu>",
@@ -111,4 +123,4 @@
   "version": "0.1.0",
   "sourceDir": "menu",
   "exportName": "Menu"
-}
+}

package/dist/manifests/metric-card.manifest.json

@@ -0,0 +1,105 @@
+{
+  "id": "metric-card",
+  "name": "MetricCard",
+  "tier": "molecule",
+  "description": "KPI tile: label, value, directional delta (arrow + color) and supporting hint.",
+  "designIntent": "Dashboards need comparable tiles. MetricCard standardizes tabular numbers, delta direction (never color-only) and the label/value/hint hierarchy so rows of KPIs align.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "description": "Metric name."
+    },
+    {
+      "name": "value",
+      "type": "string | number",
+      "required": true,
+      "description": "Primary number/value; rendered tabular."
+    },
+    {
+      "name": "delta",
+      "type": "string",
+      "required": false,
+      "description": "Signed change, e.g. +12.4%."
+    },
+    {
+      "name": "trend",
+      "type": "'up' | 'down' | 'flat'",
+      "required": false,
+      "defaultValue": "flat",
+      "description": "Delta direction color + arrow glyph.",
+      "enum": [
+        "up",
+        "down",
+        "flat"
+      ]
+    },
+    {
+      "name": "hint",
+      "type": "string",
+      "required": false,
+      "description": "Comparison context (vs last month)."
+    },
+    {
+      "name": "icon",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Decorative icon."
+    }
+  ],
+  "examples": [
+    {
+      "title": "KPI row",
+      "code": "<div className=\"grid gap-4 sm:grid-cols-3\">\n  <MetricCard label=\"Revenue\" value=\"$12,480\" delta=\"+12.4%\" trend=\"up\" hint=\"vs last month\" />\n  <MetricCard label=\"Churn\" value=\"2.1%\" delta=\"-0.4\" trend=\"down\" />\n</div>",
+      "description": "Deltas carry arrows as well as color."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't encode meaning in color alone",
+      "explanation": "Always pass trend so the arrow glyph accompanies the color.",
+      "example": "// Avoid\n<MetricCard label=\"Churn\" value=\"2.1%\" delta=\"-0.4\" />\n\n// Prefer\n<MetricCard label=\"Churn\" value=\"2.1%\" delta=\"-0.4\" trend=\"down\" />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Color-independent direction",
+      "implementation": "Delta renders ↑/↓/→ glyphs alongside color",
+      "userRequirements": "Include the sign in the delta string"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Labels",
+      "guidelines": [
+        "Short metric names",
+        "State the unit in value or hint"
+      ],
+      "goodExamples": [
+        "Revenue",
+        "Active students"
+      ],
+      "badExamples": [
+        "Total revenue generated across all locations"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Grid",
+      "relationship": "Lay KPI rows out with Grid for even columns",
+      "example": "<Grid columns={3} gap=\"md\"><MetricCard … /></Grid>"
+    }
+  ],
+  "relatedComponents": [
+    "Card",
+    "Grid",
+    "Progress"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "metric-card",
+  "exportName": "MetricCard"
+}

package/dist/manifests/page-header.manifest.json

@@ -0,0 +1,94 @@
+{
+  "id": "page-header",
+  "name": "PageHeader",
+  "tier": "molecule",
+  "description": "Standard page heading: optional breadcrumbs, level-1 title, description, right-aligned actions and a sub-row slot.",
+  "designIntent": "Every list/detail page repeats breadcrumb + title + description + actions with drifting spacing. PageHeader fixes the hierarchy (one h1 per page) and the responsive wrap, so pages stay consistent.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "description": "Page heading rendered as h1."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "description": "Supporting summary under the title."
+    },
+    {
+      "name": "breadcrumbs",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Trail rendered above the title."
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Right-aligned actions (buttons, menus)."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Sub-row under the title (tabs, filters)."
+    }
+  ],
+  "examples": [
+    {
+      "title": "List page header",
+      "code": "<PageHeader\n  title=\"Classes\"\n  description=\"Manage your weekly schedule.\"\n  breadcrumbs={<Breadcrumb … />}\n  actions={<Button>New class</Button>}\n/>",
+      "description": "One h1, one action cluster."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't stack multiple h1s",
+      "explanation": "PageHeader renders the page's h1; section headings inside the page should be h2 via Heading.",
+      "example": "// Avoid\n<PageHeader title=\"A\" /><PageHeader title=\"B\" />\n\n// Prefer one PageHeader per page"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Heading hierarchy",
+      "implementation": "Renders exactly one level-1 heading",
+      "userRequirements": "Use Heading level={2} for sections below"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Titles",
+      "guidelines": [
+        "Noun or noun phrase",
+        "Sentence case",
+        "Under 60 characters"
+      ],
+      "goodExamples": [
+        "Classes",
+        "Billing settings"
+      ],
+      "badExamples": [
+        "Here you can manage all of your classes"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Breadcrumb",
+      "relationship": "Pass a Breadcrumb as breadcrumbs for hierarchy context",
+      "example": "<PageHeader breadcrumbs={<Breadcrumb items={trail} />} title=\"Detail\" />"
+    }
+  ],
+  "relatedComponents": [
+    "Breadcrumb",
+    "Heading",
+    "Tabs"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "page-header",
+  "exportName": "PageHeader"
+}

package/dist/manifests/pagination.manifest.json

@@ -2,81 +2,109 @@
   "id": "pagination",
   "name": "Pagination",
   "tier": "molecule",
-  "description": "Numeric pagination with prev/next, ellipsis, and aria-current on the active page",
+  "description": "Numeric pagination with prev/next and boundary jumps; accepts page/pageCount or currentPage/totalPages and derives the count (plus a Showing X-Y of Z summary) from total/pageSize.",
   "designIntent": "Pagination lets users navigate through paged content. It shows page numbers with ellipsis for large ranges, prev/next buttons, and marks the current page with aria-current=page.",
   "props": [
     {
       "name": "page",
       "type": "number",
-      "required": true,
-      "description": "Current page number (1-based)"
+      "required": false,
+      "defaultValue": "1",
+      "description": "Current page (1-based). Alias: currentPage."
     },
     {
       "name": "pageCount",
       "type": "number",
-      "required": true,
-      "description": "Total number of pages"
+      "required": false,
+      "description": "Total pages. Alias: totalPages, or derived from total/pageSize."
+    },
+    {
+      "name": "currentPage",
+      "type": "number",
+      "required": false,
+      "description": "Alias for page (migration-friendly)."
+    },
+    {
+      "name": "totalPages",
+      "type": "number",
+      "required": false,
+      "description": "Alias for pageCount."
+    },
+    {
+      "name": "pageSize",
+      "type": "number",
+      "required": false,
+      "description": "Rows per page; with total enables the summary and derives pageCount."
+    },
+    {
+      "name": "total",
+      "type": "number",
+      "required": false,
+      "description": "Total item count for the summary."
+    },
+    {
+      "name": "itemLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "items",
+      "description": "Noun used in the summary."
+    },
+    {
+      "name": "showSummary",
+      "type": "boolean",
+      "required": false,
+      "description": "Force the summary on/off (defaults on when total and pageSize are set)."
     },
     {
       "name": "onPageChange",
       "type": "(page: number) => void",
       "required": false,
-      "description": "Called with the new page number"
+      "description": "Called with the new page number."
     },
     {
       "name": "siblings",
       "type": "number",
-      "defaultValue": "1",
       "required": false,
-      "description": "How many page buttons to show around the current page"
+      "defaultValue": "1",
+      "description": "Page buttons shown around the current page."
     },
     {
       "name": "showBoundaries",
       "type": "boolean",
-      "defaultValue": "false",
       "required": false,
-      "description": "Show « / » jump-to-first/last buttons around prev/next",
-      "examples": [
-        "true",
-        "false"
-      ]
-    },
-    {
-      "name": "className",
-      "type": "string",
-      "required": false,
-      "description": "Additional CSS classes to apply"
+      "defaultValue": "false",
+      "description": "Show first/last jump buttons."
     },
     {
       "name": "showFirst",
       "type": "boolean",
-      "defaultValue": "showBoundaries",
       "required": false,
-      "description": "Force-show the first-page button; defaults to showBoundaries.",
-      "examples": [
-        "true",
-        "false"
-      ]
+      "description": "Force-show the first-page button."
     },
     {
       "name": "showLast",
       "type": "boolean",
-      "defaultValue": "showBoundaries",
       "required": false,
-      "description": "Force-show the last-page button; defaults to showBoundaries.",
-      "examples": [
-        "true",
-        "false"
-      ]
+      "description": "Force-show the last-page button."
     },
     {
       "name": "icons",
-      "type": "{ first?: ReactNode; previous?: ReactNode; next?: ReactNode; last?: ReactNode }",
+      "type": "PaginationIcons",
       "required": false,
-      "description": "Replace the default ‹ › « » glyphs with custom markup."
+      "description": "Replace the default glyphs."
     }
   ],
   "examples": [
+    {
+      "title": "Summary + derived pages",
+      "code": "<Pagination\n  page={page}\n  pageSize={25}\n  total={312}\n  itemLabel=\"students\"\n  onPageChange={setPage}\n/>",
+      "description": "Renders \"Showing 26–50 of 312 students\" and derives 13 pages."
+    },
+    {
+      "title": "Migration aliases",
+      "code": "<Pagination currentPage={page} totalPages={pages} onPageChange={setPage} />",
+      "description": "currentPage/totalPages map onto page/pageCount."
+    },
     {
       "title": "Basic pagination",
       "code": "<Pagination page={3} pageCount={10} onPageChange={setPage} />",