@devalok/shilp-sutra 0.41.0 → 0.42.0

package/make-kit/components/icon.md

@@ -0,0 +1,152 @@
+# Icon
+
+Wrapper around Tabler icon components. Auto-sizes via `IconProvider` context.
+
+```tsx
+import { Icon } from '@devalok/shilp-sutra/ui'
+import { IconPlus, IconCheck, IconX } from '@tabler/icons-react'
+```
+
+For the broader icon system (which icons exist, how to register custom ones, the IconProvider tree), see `foundations/icons.md`. This guide covers the `<Icon>` component itself.
+
+## When to use
+
+- Any inline SVG icon — inside Button slots, IconButton, Badge slots, table cells, list rows.
+- Need an interactive icon button? Use `<IconButton>`, not Icon wrapped in `<button>`.
+- Need a static cluster of related icons? Use `<IconGroup>`.
+- Need a status indicator? Use `<StatusDot>` or `<Badge dot>` — they're optimized for that.
+
+Tabler-only. Don't mix icon libraries — see `foundations/icons.md` for the rationale.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `icon` | `ForwardRefExoticComponent` (REQUIRED) | Tabler icon component (or any ForwardRef SVG icon matching the Tabler shape). |
+| `size` | `'xs'\|'sm'\|'md'\|'lg'\|'xl'\|'2xl'` | Reads from `IconContext` if not set. |
+| `stroke` | `'light'\|'regular'\|'bold'` | Reads from `IconContext` if not set. |
+| `label` | `string` | Accessible label — sets `role="img"`, `aria-label`, and `<title>`. Without it, icon is `aria-hidden="true"`. |
+| `animate` | `'spin'\|'pulse'\|'bounce'\|'draw'\|'none'` \| `{ rotate?, scale? }` | Static when undefined. |
+| `state` | `'idle'\|'loading'\|'success'\|'error'` | State machine — overrides `animate` when both set. |
+| `className` | `string` | |
+
+## Size scale
+
+| Size | Pixel | Default use |
+|---|---|---|
+| `xs` | 14 | Inside `xs` buttons / badges, dense table cells. |
+| `sm` | 16 | Inside `sm` buttons / badges, standard inline. |
+| `md` (default) | 18 | Inside `md` buttons / inputs. |
+| `lg` | 20 | Inside `lg` buttons / large inputs. |
+| `xl` | 24 | Standalone icons in card headers. |
+| `2xl` | 32 | Hero / illustration accents. |
+
+Stroke weight varies by size — smaller icons use lighter strokes for clarity. Override via `stroke` only when the visual weight feels off.
+
+## Accessibility
+
+| Use | Result |
+|---|---|
+| No `label` (inside a labeled Button / IconButton) | `aria-hidden="true"` — screen readers skip. |
+| With `label` (standalone) | `role="img"` + `aria-label` + SVG `<title>`. |
+
+Inside `<IconButton aria-label="Edit">` the icon is decorative — don't set `label` on the Icon.
+
+For standalone icons (status indicators, decorative bullets that convey meaning), pass `label`.
+
+## Examples
+
+**Inside a Button:**
+```tsx
+<Button startIcon={IconPlus}>New project</Button>
+```
+
+`startIcon` accepts the bare Tabler component — Button wraps it in `<Icon>` and provides size via IconProvider. You don't need to wrap manually.
+
+**Inside an IconButton (requires `<Icon>` wrapper):**
+```tsx
+<IconButton
+  icon={<Icon icon={IconEdit} />}
+  variant="ghost"
+  aria-label="Edit item"
+/>
+```
+
+IconButton's `icon` prop expects a React element, so wrap in `<Icon icon={...} />`. Size flows from the button via IconProvider.
+
+**Standalone with label (a11y):**
+```tsx
+<Icon icon={IconAlertCircle} label="Warning" size="lg" />
+```
+
+Renders `role="img"` with `aria-label="Warning"` — screen readers announce it.
+
+**Loading spinner via state:**
+```tsx
+<Icon icon={IconRefresh} state="loading" />
+```
+
+`state="loading"` renders a bare Spinner regardless of the `icon` prop. Use for inline loading affordances.
+
+**Success / error feedback:**
+```tsx
+<Icon icon={IconCheck} state="success" />
+<Icon icon={IconX} state="error" />
+```
+
+`state="success"` / `state="error"` render animated checkmark / cross via Framer Motion. Respects `prefers-reduced-motion`.
+
+**Path-draw animation (check / X / circle-check only):**
+```tsx
+<Icon icon={IconCheck} animate="draw" />
+```
+
+Draws the stroke progressively (0.35s easeOut). Works with `IconCheck`, `IconX`, and `IconCircleCheck` only — other icons fall back to static render.
+
+**Spin animation:**
+```tsx
+<Icon icon={IconLoader} animate="spin" />
+```
+
+For an actual loading state, prefer `state="loading"` — it renders the dedicated Spinner.
+
+**Inside a row, auto-sized from input:**
+```tsx
+<Input
+  size="lg"
+  startSection={<Icon icon={IconSearch} />}  {/* size: 'md' from IconProvider */}
+  placeholder="Search"
+/>
+```
+
+Input's IconProvider sets size by input size: `xs` / `sm` input → `sm` icon, `md` / `lg` input → `md` icon. Don't pass `size` on the nested Icon.
+
+**Status badge with custom-colored icon:**
+```tsx
+<Stack direction="horizontal" gap="ds-02" align="center">
+  <Icon icon={IconCircleFilled} size="xs" className="text-success-9" />
+  <Text variant="body-sm">Online</Text>
+</Stack>
+```
+
+For most status displays prefer `<StatusDot>` — purpose-built. Use this pattern only when you need a specific icon shape.
+
+## Composability
+
+- **IconProvider cascade:** Button, IconButton, Badge, Input (start/endSection), NumberInput, IconGroup all wrap children in an `IconProvider`. Nested `<Icon>` reads size + stroke automatically. Don't pass `size` on those nested Icons.
+- **Explicit props override context.** When you genuinely need a different size, pass `size` on the Icon — it wins.
+- **State overrides animate.** When both are set, `state` wins. `state="loading"` renders a Spinner; `state="success"` / `state="error"` render path-drawn animations.
+- **Reduced motion respected.** All animations fall back to static render under `prefers-reduced-motion: reduce`.
+
+See `foundations/icons.md` for the icon-system overview (Tabler-only rationale, IconProvider tree, custom icons), `foundations/motion.md` for animation tokens.
+
+## Rules
+
+- Use Tabler icons only. See `foundations/icons.md` for the rationale and registry.
+- Inside Button / IconButton / Badge slots, don't pass `size` on the nested Icon — IconProvider sets it.
+- For standalone icons that convey meaning (not in a labeled button), pass `label` — without it, screen readers skip the icon.
+- Inside `<IconButton aria-label="...">`, the Icon is decorative — don't set `label` on the Icon (would duplicate the announcement).
+- For loading affordances, use `state="loading"` — it renders the dedicated Spinner.
+- `animate="draw"` only works for `IconCheck`, `IconX`, `IconCircleCheck`. Other icons silently fall back to static.
+- Don't wrap Icon in `<button>` — use `<IconButton>`.
+- Stroke weight scales with size — only override `stroke` when the default truly feels off, not as a stylistic preference.

package/make-kit/components/input.md

@@ -0,0 +1,154 @@
+# Input
+
+Single-line text entry. Use instead of `<input type="text" | "email" | "url" | "tel" | "search" | "password">`.
+
+```tsx
+import { Input } from '@devalok/shilp-sutra/ui/input'
+```
+
+## When to use
+
+- Any single-line text capture: email, URL, search, name, password, phone.
+- Multi-line input? Use `<Textarea>`.
+- Number-only with steppers? Use `<NumberInput>`.
+- One-time-code / PIN entry? Use `<InputOTP>`.
+- Searchable list with selection? Use `<Combobox>` or `<Autocomplete>`.
+
+Wrap in a `<FormField>` for automatic a11y wiring (state, `aria-describedby`, `aria-invalid`, `aria-required`).
+
+## Sizes
+
+| Size | Pixel height | When |
+|---|---|---|
+| `xs` | 28 | Toolbar / inline filters. |
+| `sm` | 32 | Dense forms. |
+| `md` (default) | 40 | Standard. |
+| `lg` | 48 | Marketing / spacious layouts. |
+
+All sizes use 14 px text — sizes scale height + padding, not font.
+
+## States
+
+| State | Visual | Use |
+|---|---|---|
+| `default` (default) | Subtle border. | Resting. |
+| `error` | Red border + `aria-invalid="true"`. | Validation failure. |
+| `warning` | Amber border. | Soft caution (caps lock on, weak password). |
+| `success` | Green border. | Inline confirmation. |
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size` | `'xs'\|'sm'\|'md'\|'lg'` | Default `md`. Excludes the HTML native `size` attribute. |
+| `state` | `'default'\|'error'\|'warning'\|'success'` | Inherits from `<FormField>` context if present. |
+| `startSection` | `ReactNode` | Leading slot — icon (React element) or label string. |
+| `endSection` | `ReactNode` | Trailing slot — icon or label. |
+| `startSectionType` | `'icon'\|'label'` | Auto-inferred from content type. Override only when needed. |
+| `endSectionType` | `'icon'\|'label'` | Auto-inferred. |
+| `startSectionClickable` | `boolean` | Enables pointer events on the section (e.g. clear button in slot). |
+| `endSectionClickable` | `boolean` | Same for trailing slot. |
+| `wrapperClassName` | `string` | Classes on the wrapper div (border, bg, ring live here). |
+| `className` | `string` | Classes on the raw `<input>` element (transparent — text only). |
+
+Plus all standard HTML input attributes except the native `size` (renamed to mean visual sizing).
+
+## Section type inference
+
+| Content | Renders as |
+|---|---|
+| React element (`<Icon icon={IconMail} />`) | `'icon'` — fixed-width centered cell. |
+| String (`"https://"`, `".00"`) | `'label'` — tinted bg + border separator. |
+
+Override via `startSectionType` / `endSectionType` when the inference is wrong.
+
+## Examples
+
+**Standard, with leading icon:**
+```tsx
+<Input
+  type="email"
+  placeholder="you@example.com"
+  startSection={<Icon icon={IconMail} />}
+/>
+```
+
+**URL prefix (label section):**
+```tsx
+<Input
+  startSection="https://"
+  placeholder="example.com"
+/>
+```
+
+**Currency with prefix icon + suffix label:**
+```tsx
+<Input
+  startSection={<Icon icon={IconCurrencyDollar} />}
+  endSection=".00"
+  placeholder="0"
+  inputMode="decimal"
+/>
+```
+
+**Clearable search (clickable trailing slot):**
+```tsx
+<Input
+  placeholder="Search projects"
+  startSection={<Icon icon={IconSearch} />}
+  endSection={
+    <button type="button" onClick={() => setValue('')} aria-label="Clear">
+      <Icon icon={IconX} />
+    </button>
+  }
+  endSectionClickable
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+/>
+```
+
+**Inside a FormField (auto-wired a11y):**
+```tsx
+<FormField state="error">
+  <Label htmlFor="email" required>Email</Label>
+  <Input id="email" type="email" />
+  <FormHelperText>Enter a valid work email.</FormHelperText>
+</FormField>
+```
+
+The Input picks up `state="error"`, `aria-describedby` (linked to FormHelperText), `aria-invalid`, and `aria-required` from FormField context automatically.
+
+**Password with reveal toggle:**
+```tsx
+const [visible, setVisible] = useState(false)
+
+<Input
+  type={visible ? 'text' : 'password'}
+  placeholder="Password"
+  endSection={
+    <button type="button" onClick={() => setVisible((v) => !v)} aria-label={visible ? 'Hide password' : 'Show password'}>
+      <Icon icon={visible ? IconEyeOff : IconEye} />
+    </button>
+  }
+  endSectionClickable
+/>
+```
+
+## Composability
+
+- **FormField:** Inside a `<FormField>`, Input auto-reads `state`, `aria-describedby`, `aria-invalid`, `aria-required` from context. Explicit props override.
+- **IconProvider:** Icons in `startSection` / `endSection` are auto-sized via the input's `size`. Don't pass `size` on the nested `<Icon>`.
+- **Container-first architecture:** Border, background, and focus ring live on the wrapper div, not the input element. Style overrides go through `wrapperClassName`, not `className`. The raw `<input>` is transparent.
+
+See `foundations/color.md` for state-color tokens, `foundations/icons.md` for the IconProvider cascade.
+
+## Rules
+
+- Pair every Input with a `<Label htmlFor="x" />` and matching `<Input id="x" />`. FormField does NOT auto-wire labels.
+- Use `wrapperClassName` for border / bg / ring overrides. `className` only changes the raw input text styling.
+- Don't pass `size` on `<Icon>` inside a section — IconProvider sets it.
+- Don't use the HTML native `size` attribute — it's excluded. Use CSS width or the size prop.
+- For interactive sections (clear button, password toggle), set `startSectionClickable` / `endSectionClickable`. Without it, the slot is `pointer-events-none`.
+- For status / validation, set `state` — it sets `aria-invalid` automatically when `state="error"`.
+- Don't use the removed `startIcon` / `endIcon` props — they were removed in 0.38. Use `startSection` / `endSection`.
+- Prefer FormField wrapping for any input with a label + helper — manual a11y wiring is error-prone.

package/make-kit/components/overview.md

@@ -0,0 +1,308 @@
+# Components — catalog & decision trees
+
+Catalog of every major component. Use this file to pick the right component before reaching for raw HTML. Per-component deep guides live alongside this file.
+
+## Decision tree — actions
+
+```
+User wants to commit / cancel / submit?
+  → primary CTA (1 per region)  → <Button variant="solid" color="accent">
+  → secondary action            → <Button variant="soft"> (NOT outline — see preference)
+  → tertiary / dismissive       → <Button variant="ghost">
+  → destructive action          → <Button variant="solid" color="error">
+  → link-styled action          → <Button variant="link">
+
+Action has a side-menu / overflow?
+  → <SplitButton> — primary + adjacent dropdown trigger.
+
+Action is icon-only?
+  → <IconButton> — same as Button, square aspect, aria-label required.
+
+Group of related actions?
+  → <ButtonGroup> — attached or not. Propagates disabled / size.
+```
+
+## Decision tree — input
+
+```
+Single-line text?
+  → <Input> — type="text"/"email"/"password"/"number"/"tel"/"url"/"search"
+  → For search specifically: <SearchInput> (has clear button + icon)
+  → For OTP code: <InputOTP>
+
+Multi-line text?
+  → <Textarea>
+
+Pick one from a list?
+  → static list ≤7 items     → <Select>
+  → static list >7 items     → <Combobox> (searchable)
+  → async / large list       → <Autocomplete>
+  → enum of 2–4 options      → <SegmentedControl> (always-visible) or <Tabs> (if scoping a section)
+
+Pick many?
+  → list with checkboxes     → <Checkbox> per item
+  → compact pills            → <ToggleGroup type="multiple">
+  → searchable               → <Combobox multiple>
+
+Boolean?
+  → <Switch> (settings-style on/off) — instant action
+  → <Checkbox> (form field) — confirmed-on-submit
+  → <Toggle> (button-like toggled state)
+
+Range / scalar?
+  → <Slider> (single or multi-thumb range)
+  → <NumberInput> (precise number with steppers)
+
+Date / time?
+  → <DatePicker> (single date)
+  → <DateRangePicker> (range)
+  → <DateTimePicker> (date + time)
+
+Color?
+  → <ColorInput> (popover swatch + manual hex)
+  → <ColorSwatch> (display-only)
+
+File?
+  → <FileUpload> (drag-drop + click)
+```
+
+## Decision tree — feedback
+
+```
+Permanent inline message?
+  → <Alert>     — page-level notice (info / success / warning / error)
+  → <Banner>    — full-bleed page banner (system status, announcements)
+  → <InfoBlock> — within a form / card (helper context)
+
+Status of an item?
+  → <Badge>          — pill label (status / tag)
+  → <StatusBadge>    — colored dot + label (discriminated union: status="online"/"away"/...)
+  → <StatusDot>      — just the colored dot
+
+Temporary notification?
+  → toast.success / error / warning / info (imperative) — must have <Toaster /> mounted
+
+Loading / pending?
+  → <Spinner>           — generic
+  → <ProgressRing>      — determinate ring
+  → <Progress>          — linear bar
+  → <Skeleton>          — content placeholder shimmer
+  → <PageSkeletons.*>   — pre-built page-level skeletons
+  → <GlobalLoading>     — app-wide loading overlay
+
+Empty state?
+  → <EmptyState> — icon + heading + body + action
+```
+
+## Decision tree — overlays
+
+```
+Confirm a destructive action?         → <AlertDialog> or <ConfirmDialog>
+Show a form / detailed flow?          → <Dialog>  (auto fullScreen on mobile)
+Show a side panel?                    → <Sheet>   (auto bottom-drawer on mobile)
+Show a small floating popup on click? → <Popover>
+Show a small floating popup on hover? → <HoverCard>
+Show a label on hover?                → <Tooltip>
+Show a menu from a button?            → <DropdownMenu>
+Show a menu from right-click?         → <ContextMenu>
+Show a menu in a toolbar?             → <Menubar>
+Show a command palette (cmd+K)?       → <AppCommandPalette> (shell) or <CommandPalette> (composed)
+```
+
+## Decision tree — navigation
+
+```
+Top of every page?
+  → <TopBar> (shell)
+
+Side nav (product)?
+  → <AppSidebar> (shell) — collapsible, with sections, footer
+
+Tabs within a page?
+  → <Tabs>            — horizontal default
+  → <Tabs orientation="vertical"> — side-nav within a card
+
+Pages within a flow?
+  → <Stepper>         — multi-step wizard, optional clickable
+
+Breadcrumb trail?
+  → <Breadcrumb>
+
+Pagination?
+  → <Pagination>
+
+Mobile bottom nav?
+  → <BottomNavbar>
+```
+
+## Decision tree — layout
+
+```
+Page wrapper?
+  → <Container size="..."> — max-width constraints (sm / md / lg / xl / 2xl / full)
+
+Vertical / horizontal stack?
+  → <Stack direction="col|row" gap="ds-*">
+
+A card / panel?
+  → <Card> — surface-raised + shadow-raised
+  → <Card variant="..."> — tinted by color prop
+
+A grid?
+  → use native CSS grid utilities (grid grid-cols-12 gap-ds-05) — no kit primitive for this
+
+Aspect-ratio box?
+  → <AspectRatio ratio={16/9}>
+
+Divider?
+  → <Separator> (horizontal default; orientation="vertical")
+
+Collapsible section?
+  → <Collapsible> (single)
+  → <Accordion> (group, single-open or multi-open)
+```
+
+## Decision tree — data display
+
+```
+Tabular data?
+  → <Table>      — simple, hand-roll rows/cells
+  → <DataTable>  — full-featured (sort, paginate, select, filter, export, density, mobile-card)
+
+Key-value display?
+  → <StatCard>          — single big stat
+  → 4 StatCards in a row → use <Stack direction="row" gap="ds-05">
+
+Activity / event log?
+  → <ActivityFeed>      — vertical timeline with dots
+
+User avatars?
+  → <Avatar>           — single
+  → <AvatarGroup>       — stack with overflow
+
+A list of selectable members?
+  → <MemberPicker>
+
+A chart?
+  → BarChart / LineChart / AreaChart / PieChart / RadarChart / GaugeChart / Sparkline (from /ui/charts)
+
+Code?
+  → <Code> inline
+  → <MarkdownViewer> for rendered markdown
+```
+
+## Component catalog by category
+
+### Actions
+| Component | Subpath | Purpose |
+|---|---|---|
+| Button | `/ui/button` | Primary action element. |
+| IconButton | `/ui/icon-button` | Icon-only square button. |
+| ButtonGroup | `/ui/button-group` | Visually attached group. |
+| SplitButton | `/ui/split-button` | Action + dropdown. |
+| OAuthButton | `/ui/oauth-button` | Brand-aware social login button. |
+| Toggle | `/ui/toggle` | Toggled-state button. |
+| ToggleGroup | `/ui/toggle-group` | Group of toggles (single / multiple). |
+| Link | `/ui/link` | Themed anchor. |
+
+### Inputs
+| Component | Subpath |
+|---|---|
+| Input | `/ui/input` |
+| Textarea | `/ui/textarea` |
+| Select | `/ui/select` |
+| Combobox | `/ui/combobox` |
+| Autocomplete | `/ui/autocomplete` |
+| SearchInput | `/ui/search-input` |
+| NumberInput | `/ui/number-input` |
+| InputOTP | `/ui/input-otp` |
+| Checkbox | `/ui/checkbox` |
+| Radio | `/ui/radio` |
+| Switch | `/ui/switch` |
+| Slider | `/ui/slider` |
+| FileUpload | `/ui/file-upload` |
+| ColorInput | `/ui/color-input` |
+| ColorSwatch | `/ui/color-swatch` |
+| DatePicker | `/composed/date-picker` |
+| Label | `/ui/label` |
+| Form / FormField | `/ui/form` |
+| SegmentedControl | `/ui/segmented-control` |
+
+### Overlays
+| Component | Subpath |
+|---|---|
+| Dialog | `/ui/dialog` |
+| AlertDialog | `/ui/alert-dialog` |
+| Sheet | `/ui/sheet` |
+| Popover | `/ui/popover` |
+| HoverCard | `/ui/hover-card` |
+| Tooltip | `/ui/tooltip` |
+| DropdownMenu | `/ui/dropdown-menu` |
+| ContextMenu | `/ui/context-menu` |
+| Menubar | `/ui/menubar` |
+
+### Feedback
+| Component | Subpath |
+|---|---|
+| Alert | `/ui/alert` |
+| Banner | `/ui/banner` |
+| Toast / Toaster | `/ui/toast`, `/ui/toaster` |
+| Spinner | `/ui/spinner` |
+| Progress | `/ui/progress` |
+| ProgressRing | `/ui/progress-ring` |
+| Skeleton | `/ui/skeleton` |
+| Badge | `/ui/badge` |
+| StatusBadge | `/composed/status-badge` |
+| StatusDot | `/ui/status-dot` |
+| EmptyState | `/composed/empty-state` |
+
+### Layout
+| Component | Subpath |
+|---|---|
+| Container | `/ui/container` |
+| Stack | `/ui/stack` |
+| Card | `/ui/card` |
+| AspectRatio | `/ui/aspect-ratio` |
+| Separator | `/ui/separator` |
+| Accordion | `/ui/accordion` |
+| Collapsible | `/ui/collapsible` |
+
+### Navigation
+| Component | Subpath |
+|---|---|
+| Tabs | `/ui/tabs` |
+| Breadcrumb | `/ui/breadcrumb` |
+| Pagination | `/ui/pagination` |
+| Stepper | `/ui/stepper` |
+| NavigationMenu | `/ui/navigation-menu` |
+| Sidebar (AppSidebar) | `/shell/sidebar` |
+| TopBar | `/shell/top-bar` |
+| BottomNavbar | `/shell/bottom-navbar` |
+
+### Data display
+| Component | Subpath |
+|---|---|
+| Table | `/ui/table` |
+| DataTable | `/ui/data-table` |
+| StatCard | `/ui/stat-card` |
+| ActivityFeed | `/composed/activity-feed` |
+| Avatar | `/ui/avatar` |
+| AvatarGroup | `/composed/avatar-group` |
+| Text | `/ui/text` |
+| Code | `/ui/code` |
+| Charts (bar / line / area / pie / radar / gauge / sparkline) | `/ui/charts/*` |
+
+## Common props across components
+
+| Prop | Type | Where |
+|---|---|---|
+| `className` | string | All. Use sparingly. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | Button, Input, Select, Card, Alert, Badge, Tabs, Checkbox, Radio, Slider, etc. Not all sizes exist on every component. |
+| `color` | `'accent' \| 'error' \| 'success' \| 'warning' \| 'info' \| 'neutral'` | Button, Badge, Card, Tabs (subset), Alert. |
+| `variant` | varies | Button (`solid|soft|outline|ghost|link`), Card, Alert, Badge, Select, etc. |
+| `disabled` | boolean | All interactive. Propagates from ButtonGroup. |
+| `loading` | boolean | Button, IconButton, OAuthButton, async-aware components. |
+
+## Per-component guides
+
+See `components/{button|card|input|dialog|badge|select|tabs|toast|form|table|dropdown-menu|popover|text|stack|icon}.md` for prop tables, examples, and rules.