@slipstream-ui/core 0.3.0 → 0.4.0

package/src/manifests/password-input.manifest.json

@@ -0,0 +1,75 @@
+{
+  "id": "password-input",
+  "name": "PasswordInput",
+  "tier": "molecule",
+  "description": "Password field with an accessible show/hide toggle (aria-pressed), built on Input.",
+  "designIntent": "Users mistype passwords; a reveal toggle reduces failed sign-ins. The toggle must be a real button with a pressed state and a proper label so it is not a mystery control.",
+  "props": [
+    {
+      "name": "showLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Show password",
+      "description": "Accessible label while hidden."
+    },
+    {
+      "name": "hideLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Hide password",
+      "description": "Accessible label while visible."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Sign-in field",
+      "code": "<PasswordInput aria-label=\"Password\" autoComplete=\"current-password\" />",
+      "description": "Input props pass through."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't reveal by default",
+      "explanation": "Start masked; reveal is user-initiated.",
+      "example": "// Avoid: type=\"text\" for a password\n<Input type=\"text\" aria-label=\"Password\" />\n\n// Prefer\n<PasswordInput aria-label=\"Password\" />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Toggle semantics",
+      "implementation": "Button with aria-pressed and Show/Hide labels",
+      "userRequirements": "Keep both labels descriptive"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Labels",
+      "guidelines": [
+        "Verb-first toggle labels"
+      ],
+      "goodExamples": [
+        "Show password"
+      ],
+      "badExamples": [
+        "Eye"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "FormField",
+      "relationship": "Wrap for label/hint/error wiring",
+      "example": "<FormField id=\"pw\" label=\"Password\"><PasswordInput /></FormField>"
+    }
+  ],
+  "relatedComponents": [
+    "Input",
+    "FormField",
+    "InputGroup"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "password-input",
+  "exportName": "PasswordInput"
+}

package/src/manifests/select-menu.manifest.json

@@ -0,0 +1,142 @@
+{
+  "id": "select-menu",
+  "name": "SelectMenu",
+  "tier": "molecule",
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "select-menu",
+  "exportName": "SelectMenu",
+  "description": "Custom listbox select for rich options: descriptions, icons, groups, multi-select, custom rows and hidden inputs for forms.",
+  "designIntent": "Native <select> cannot render rich option content. SelectMenu supplies a real listbox with the button/listbox keyboard model while keeping the same value/onValueChange contract as Select, so teams can move between the two without rewriting state.",
+  "props": [
+    {
+      "name": "items",
+      "type": "SelectMenuItem[]",
+      "required": true,
+      "description": "Options: { value, label, description?, icon?, disabled?, group? }."
+    },
+    {
+      "name": "value",
+      "type": "string | string[]",
+      "required": false,
+      "description": "Controlled value(s); string[] when multiple."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string | string[]",
+      "required": false,
+      "description": "Initial value(s) when uncontrolled."
+    },
+    {
+      "name": "onValueChange",
+      "type": "(value: string | string[]) => void",
+      "required": false,
+      "description": "Fired with the new selection."
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Allow several selections; the listbox stays open."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Select…",
+      "description": "Shown when nothing is selected."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "description": "Renders hidden form inputs for the selected values."
+    },
+    {
+      "name": "renderValue",
+      "type": "(selected: SelectMenuItem[]) => ReactNode",
+      "required": false,
+      "description": "Custom trigger content."
+    },
+    {
+      "name": "renderItem",
+      "type": "(item, state: { selected: boolean; active: boolean }) => ReactNode",
+      "required": false,
+      "description": "Custom option row."
+    },
+    {
+      "name": "emptyText",
+      "type": "string",
+      "required": false,
+      "defaultValue": "No options",
+      "description": "Shown when items is empty."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Rich options",
+      "code": "<SelectMenu\n  aria-label=\"Plan\"\n  placeholder=\"Choose a plan\"\n  items={[\n    { value: 'free', label: 'Free', description: '1 project', group: 'Individual' },\n    { value: 'team', label: 'Team', description: 'SSO + audit log', group: 'Business' },\n  ]}\n  value={plan}\n  onValueChange={setPlan}\n/>",
+      "description": "Descriptions and grouped headings inside a real listbox."
+    },
+    {
+      "title": "Multi-select with form input",
+      "code": "<SelectMenu\n  aria-label=\"Channels\"\n  multiple\n  name=\"channels\"\n  items={channels}\n  value={selected}\n  onValueChange={setSelected}\n/>",
+      "description": "Hidden inputs make the selection submit with the form."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't use it for free-text entry",
+      "explanation": "SelectMenu has no text input. Use Autocomplete when typing a value is expected.",
+      "example": "// Avoid: 200 options behind a menu\n<SelectMenu items={allCities} />\n\n// Prefer\n<Autocomplete loadOptions={searchCities} />"
+    },
+    {
+      "title": "Don't render more than ~50 options",
+      "explanation": "There is no filtering. Large sets need Autocomplete or a searchable flow.",
+      "example": "// Avoid\n<SelectMenu items={tenThousandRows} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Keyboard model",
+      "implementation": "Arrows move the active option, Home/End jump, Enter/Space select, Escape closes, typeahead jumps by first letters",
+      "userRequirements": "Keep option labels distinct so typeahead stays predictable"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Option labels",
+      "guidelines": [
+        "Noun phrases",
+        "Use description for the second line",
+        "Parallel phrasing across options"
+      ],
+      "goodExamples": [
+        "Pro — Unlimited projects"
+      ],
+      "badExamples": [
+        "Click to pick the pro plan option"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "FormField",
+      "relationship": "Wrap for label/hint/error wiring",
+      "example": "<FormField id=\"plan\" label=\"Plan\"><SelectMenu items={items} /></FormField>"
+    },
+    {
+      "component": "Select",
+      "relationship": "Prefer Select when options are plain text (native pickers, mobile UX)",
+      "example": "<Select options={plain} />"
+    }
+  ],
+  "relatedComponents": [
+    "Select",
+    "Autocomplete",
+    "Menu",
+    "FormField"
+  ]
+}

package/src/manifests/select.manifest.json

@@ -2,15 +2,20 @@
   "id": "select",
   "name": "Select",
   "tier": "atom",
-  "description": "Accessible select primitive built on the native select element with controlled and uncontrolled modes",
-  "designIntent": "Most dropdown needs are satisfied by the platform select: it brings complete keyboard, screen-reader and mobile behavior for free and never strands focus. This primitive adds consistent styling and a typed options API without re-implementing a listbox.",
+  "description": "Accessible select built on the native <select> with flat options, optgroups, a placeholder row and native multi-select.",
+  "designIntent": "Native selects keep platform keyboard, mobile picker and screen-reader behavior for free. Groups cover coarse categorization, placeholder renders the 'choose one' affordance, and multiple switches the contract to string[] for tag-picker use cases without reimplementing a listbox.",
   "props": [
     {
       "name": "options",
       "type": "SelectOption[]",
-      "required": true,
-      "description": "Options to render; each is { value, label, disabled? }",
-      "examples": [{ "value": "sm", "label": "Small" }]
+      "required": false,
+      "description": "Flat options ({ value, label, disabled? }). Ignored when groups is provided.",
+      "examples": [
+        {
+          "value": "sm",
+          "label": "Small"
+        }
+      ]
     },
     {
       "name": "label",
@@ -20,24 +25,53 @@
     },
     {
       "name": "value",
-      "type": "string",
+      "type": "string | string[]",
       "required": false,
-      "description": "Controlled selected value"
+      "description": "Controlled value (string, or string[] when multiple)."
     },
     {
       "name": "defaultValue",
-      "type": "string",
+      "type": "string | string[]",
       "required": false,
-      "description": "Uncontrolled initial value"
+      "description": "Initial value when uncontrolled."
     },
     {
       "name": "onChange",
-      "type": "(value: string) => void",
+      "type": "(value: string | string[]) => void",
+      "required": false,
+      "description": "Fired with the new value; string[] when multiple."
+    },
+    {
+      "name": "groups",
+      "type": "SelectOptionGroup[]",
+      "required": false,
+      "description": "Optgroups: [{ label, options }] rendered with a heading per section."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
       "required": false,
-      "description": "Called with the newly selected value"
+      "description": "Renders a disabled empty option as the 'choose one' affordance."
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Native multi-select; value/defaultValue/onChange switch to string[]."
     }
   ],
   "examples": [
+    {
+      "title": "Grouped options",
+      "code": "<Select\n  label=\"Plan\"\n  placeholder=\"Choose a plan\"\n  groups={[\n    { label: 'Individual', options: [{ value: 'free', label: 'Free' }] },\n    { label: 'Business', options: [{ value: 'team', label: 'Team' }] },\n  ]}\n/>",
+      "description": "Optgroups with a placeholder row."
+    },
+    {
+      "title": "Multi-select",
+      "code": "<Select\n  label=\"Channels\"\n  multiple\n  value={channels}\n  onChange={setChannels}\n  options={[{ value: 'email', label: 'Email' }, { value: 'slack', label: 'Slack' }]}\n/>",
+      "description": "Native listbox with a string[] contract."
+    },
     {
       "title": "Controlled select",
       "code": "const [size, setSize] = useState('default');\n\n<Select\n  label=\"Size\"\n  value={size}\n  onChange={setSize}\n  options={[\n    { value: 'default', label: 'Default' },\n    { value: 'sm', label: 'Small' },\n    { value: 'lg', label: 'Large' },\n  ]}\n/>",
@@ -66,7 +100,10 @@
       "relationship": "Pair Select with Button in filter toolbars; Button submits, Select filters."
     }
   ],
-  "relatedComponents": ["Button", "Input"],
+  "relatedComponents": [
+    "Button",
+    "Input"
+  ],
   "package": "@slipstream-ui/core",
   "importPath": "@slipstream-ui/core",
   "version": "0.0.1",

package/src/manifests/stepper.manifest.json

@@ -0,0 +1,95 @@
+{
+  "id": "stepper",
+  "name": "Stepper",
+  "tier": "molecule",
+  "description": "Multi-step flow indicator: ordered list, aria-current step, text state for complete/current/upcoming.",
+  "designIntent": "Wizards need orientation: where am I, what is done, what is next. A stepper built on an ordered list keeps the sequence structural and announces state in text, not just color.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "{ label: string; description?: string }[]",
+      "required": true,
+      "description": "Ordered step definitions."
+    },
+    {
+      "name": "current",
+      "type": "number",
+      "required": true,
+      "description": "Zero-based index of the active step."
+    },
+    {
+      "name": "orientation",
+      "type": "'horizontal' | 'vertical'",
+      "required": false,
+      "defaultValue": "horizontal",
+      "description": "Layout direction.",
+      "enum": [
+        "horizontal",
+        "vertical"
+      ]
+    },
+    {
+      "name": "onStepClick",
+      "type": "(index: number) => void",
+      "required": false,
+      "description": "Makes steps clickable (for revisit flows)."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Onboarding wizard",
+      "code": "<Stepper\n  current={step}\n  steps={[{ label: 'Account' }, { label: 'Studio details' }, { label: 'Invite team' }, { label: 'Review' }]}\n/>",
+      "description": "Current step is announced; completed steps show a check."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't use it for progress percentage",
+      "explanation": "Use Progress for measurable 0-100 progress; Stepper is discrete stages.",
+      "example": "// Avoid: 7 steps for an upload\n// Prefer: <Progress value={42} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Sequence + state",
+      "implementation": "Ordered list with aria-current=step and sr-only state text",
+      "userRequirements": "Keep step labels short and parallel"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Step labels",
+      "guidelines": [
+        "Verb or noun phrase",
+        "Parallel grammar",
+        "3-5 steps max"
+      ],
+      "goodExamples": [
+        "Account",
+        "Studio details",
+        "Review"
+      ],
+      "badExamples": [
+        "Step 1",
+        "Now do this"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Form",
+      "relationship": "One Form (or Form step) per Stepper stage",
+      "example": "<Stepper current={1} steps={steps} />"
+    }
+  ],
+  "relatedComponents": [
+    "Progress",
+    "Tabs",
+    "Form"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "stepper",
+  "exportName": "Stepper"
+}

package/src/manifests/table-card.manifest.json

@@ -0,0 +1,123 @@
+{
+  "id": "table-card",
+  "name": "TableCard",
+  "tier": "molecule",
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "table-card",
+  "exportName": "TableCard",
+  "description": "Table shell with title/description, header actions, optional toolbar, edge-to-edge body and a footer row.",
+  "designIntent": "Every list page rebuilds the same chrome around Table/DataTable: heading, count, actions, filter row, pagination. TableCard standardizes that shell so pages only supply the table.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": false,
+      "description": "Card heading."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "description": "Supporting line under the heading."
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Right-aligned header actions."
+    },
+    {
+      "name": "toolbar",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Row between header and table (filters, bulk actions)."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "description": "Table or DataTable content."
+    },
+    {
+      "name": "footer",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Footer row (pagination, summary)."
+    },
+    {
+      "name": "flush",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Remove inner padding so the table reaches the card edges."
+    }
+  ],
+  "examples": [
+    {
+      "title": "List page table",
+      "code": "<TableCard\n  title=\"Classes\"\n  description=\"12 active\"\n  actions={<Button>New class</Button>}\n  toolbar={<FilterBar … />}\n  footer={<Pagination … />}\n>\n  <DataTable columns={columns} data={rows} />\n</TableCard>",
+      "description": "Header, toolbar, table and pagination in one surface."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't nest another bordered card",
+      "explanation": "TableCard is the surface; wrapping it in Card double-borders the content.",
+      "example": "// Avoid\n<Card><TableCard>…</TableCard></Card>"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Heading semantics",
+      "implementation": "Title renders an h2 (page owns the h1 via PageHeader)",
+      "userRequirements": "Don't skip heading levels"
+    },
+    {
+      "feature": "Table labelling",
+      "implementation": "The table keeps its own caption/aria-label",
+      "userRequirements": "Always label the table inside"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Titles",
+      "guidelines": [
+        "Plural noun",
+        "Sentence case",
+        "Pair with a count in description"
+      ],
+      "goodExamples": [
+        "Classes · 12 active"
+      ],
+      "badExamples": [
+        "Data"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "DataTable",
+      "relationship": "Body content; use flush for edge-to-edge rows",
+      "example": "<TableCard flush><DataTable … /></TableCard>"
+    },
+    {
+      "component": "FilterBar",
+      "relationship": "Pass as toolbar for list filtering",
+      "example": "<TableCard toolbar={<FilterBar … />}>…</TableCard>"
+    },
+    {
+      "component": "Pagination",
+      "relationship": "Pass as footer",
+      "example": "<TableCard footer={<Pagination … />}>…</TableCard>"
+    }
+  ],
+  "relatedComponents": [
+    "DataTable",
+    "Table",
+    "FilterBar",
+    "Pagination",
+    "Card"
+  ]
+}

package/src/manifests/time-picker.manifest.json

@@ -0,0 +1,86 @@
+{
+  "id": "time-picker",
+  "name": "TimePicker",
+  "tier": "molecule",
+  "description": "Native time field with an HH:MM contract and an optional clear button.",
+  "designIntent": "Like DatePicker: the platform time control is already accessible and locale-aware. TimePicker standardizes the HH:MM contract and clear affordance.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "description": "\"HH:MM\" (24h), controlled."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "required": false,
+      "description": "\"HH:MM\", initial value."
+    },
+    {
+      "name": "onValueChange",
+      "type": "(value: string) => void",
+      "required": false,
+      "description": "Fired with the time string; '' when cleared."
+    },
+    {
+      "name": "clearable",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Shows a clear button once a value exists."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Time field",
+      "code": "<TimePicker aria-label=\"Starts at\" value={start} onValueChange={setStart} clearable />",
+      "description": "Controlled HH:MM value."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't mix 12h display with 24h state",
+      "explanation": "State stays HH:MM; format for display with Intl.",
+      "example": "// Avoid: '9:30 PM' in state\n// Prefer: '21:30'"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Platform input",
+      "implementation": "Renders input[type=time]",
+      "userRequirements": "Provide a label describing the moment"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Labels",
+      "guidelines": [
+        "Describe the moment (Starts at / Ends by)"
+      ],
+      "goodExamples": [
+        "Starts at"
+      ],
+      "badExamples": [
+        "Time"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "DatePicker",
+      "relationship": "Pair for date+time scheduling",
+      "example": "<DatePicker aria-label=\"Date\" /><TimePicker aria-label=\"Time\" />"
+    }
+  ],
+  "relatedComponents": [
+    "DatePicker",
+    "FormField",
+    "Input"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "time-picker",
+  "exportName": "TimePicker"
+}