@devalok/shilp-sutra 0.40.1 → 0.42.0

package/make-kit/components/dropdown-menu.md

@@ -0,0 +1,205 @@
+# DropdownMenu
+
+Click-triggered menu of actions. Use for overflow menus, row actions, account menus.
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuGroup,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+} from '@devalok/shilp-sutra/ui/dropdown-menu'
+```
+
+## When to use
+
+- Row / item actions (kebab menu — Edit, Duplicate, Delete).
+- Account menu (Profile, Settings, Logout).
+- Sort / filter pickers with a fixed list.
+- Toolbar overflow ("More" button).
+- Interactive panel (forms, calendars, complex pickers)? Use `<Popover>`.
+- Single-choice from a fixed list inside a form field? Use `<Select>`.
+- Hover-triggered rich preview? Use `<HoverCard>`.
+- Right-click contextual menu? Use `<ContextMenu>` (separate component).
+
+## Compound shape
+
+```
+DropdownMenu (root — open, onOpenChange, defaultOpen, modal)
+  DropdownMenuTrigger                          ← asChild around your button
+  DropdownMenuContent
+    DropdownMenuLabel                          ← non-interactive section heading
+    DropdownMenuSeparator
+    DropdownMenuItem (+ DropdownMenuShortcut)  ← standard action
+    DropdownMenuCheckboxItem                   ← multi-select toggle
+    DropdownMenuRadioGroup
+      DropdownMenuRadioItem                    ← single-select group
+    DropdownMenuGroup                          ← visual grouping
+    DropdownMenuSub
+      DropdownMenuSubTrigger                   ← visible item that opens submenu
+      DropdownMenuSubContent                   ← the nested submenu panel
+```
+
+## Root state props (Radix passthrough)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `open` | `boolean` | Controlled. |
+| `onOpenChange` | `(open: boolean) => void` | |
+| `defaultOpen` | `boolean` | Uncontrolled. |
+| `modal` | `boolean` | Default `true`. |
+
+## Examples
+
+**Standard kebab menu:**
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <IconButton icon={<Icon icon={IconDots} />} variant="ghost" aria-label="Actions" />
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onSelect={() => edit(item)}>
+      <Icon icon={IconEdit} /> Edit
+    </DropdownMenuItem>
+    <DropdownMenuItem onSelect={() => duplicate(item)}>
+      <Icon icon={IconCopy} /> Duplicate
+    </DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onSelect={() => remove(item)}>
+      <Icon icon={IconTrash} /> Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+**With keyboard shortcut hints:**
+```tsx
+<DropdownMenuContent>
+  <DropdownMenuItem onSelect={save}>
+    Save
+    <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
+  </DropdownMenuItem>
+  <DropdownMenuItem onSelect={find}>
+    Find
+    <DropdownMenuShortcut>⌘F</DropdownMenuShortcut>
+  </DropdownMenuItem>
+</DropdownMenuContent>
+```
+
+`DropdownMenuShortcut` is decorative — it does NOT bind the shortcut globally. Bind shortcuts separately (e.g. with a `useHotkeys` hook).
+
+**Checkbox items (multi-select filters):**
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="soft" endIcon={IconChevronDown}>View</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuLabel>Show columns</DropdownMenuLabel>
+    <DropdownMenuCheckboxItem
+      checked={cols.includes('owner')}
+      onCheckedChange={(checked) => toggleCol('owner', checked)}
+      onSelect={(e) => e.preventDefault()}
+    >
+      Owner
+    </DropdownMenuCheckboxItem>
+    <DropdownMenuCheckboxItem
+      checked={cols.includes('status')}
+      onCheckedChange={(checked) => toggleCol('status', checked)}
+      onSelect={(e) => e.preventDefault()}
+    >
+      Status
+    </DropdownMenuCheckboxItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Calling `e.preventDefault()` inside `onSelect` keeps the menu open after toggling — standard for checkbox items.
+
+**Radio items (single-select sort):**
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="soft">Sort: {sort}</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuLabel>Sort by</DropdownMenuLabel>
+    <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
+      <DropdownMenuRadioItem value="recent">Most recent</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="oldest">Oldest</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="az">A → Z</DropdownMenuRadioItem>
+    </DropdownMenuRadioGroup>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+**Submenu:**
+```tsx
+<DropdownMenuContent>
+  <DropdownMenuItem onSelect={() => share(item)}>Share</DropdownMenuItem>
+  <DropdownMenuSub>
+    <DropdownMenuSubTrigger>
+      <Icon icon={IconFolder} /> Move to
+    </DropdownMenuSubTrigger>
+    <DropdownMenuSubContent>
+      <DropdownMenuItem onSelect={() => move('inbox')}>Inbox</DropdownMenuItem>
+      <DropdownMenuItem onSelect={() => move('archive')}>Archive</DropdownMenuItem>
+      <DropdownMenuItem onSelect={() => move('trash')}>Trash</DropdownMenuItem>
+    </DropdownMenuSubContent>
+  </DropdownMenuSub>
+</DropdownMenuContent>
+```
+
+Both `SubTrigger` AND `SubContent` are required — missing either silently breaks the hover-open behavior.
+
+**Account menu pattern:**
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <IconButton icon={<Avatar size="sm" src={user.avatar} alt={user.name} />} variant="ghost" aria-label="Account" />
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuLabel>{user.email}</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuGroup>
+      <DropdownMenuItem onSelect={() => router.push('/profile')}>Profile</DropdownMenuItem>
+      <DropdownMenuItem onSelect={() => router.push('/settings')}>Settings</DropdownMenuItem>
+    </DropdownMenuGroup>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onSelect={signOut}>
+      <Icon icon={IconLogout} /> Sign out
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Composability
+
+- **Radix DropdownMenu** underneath — `open` / `onOpenChange` / `defaultOpen` / `modal` standard state.
+- **Keyboard:** Arrow keys navigate, Enter/Space activates, Esc closes, typeahead jumps to first letter. All pre-wired.
+- **Trigger:** `<DropdownMenuTrigger asChild>` around any button. `IconButton` is the common pairing for kebab menus.
+- **Closing from a handler:** `onSelect` auto-closes the menu. Call `e.preventDefault()` inside the handler to keep it open (checkbox items, multi-step interactions).
+- **z-popover (1400):** Stacks above Dialog. Nesting dropdowns inside dialogs works correctly.
+
+See `foundations/surfaces.md` for menu surface tokens, `foundations/motion.md` for the spring open animation.
+
+## Rules
+
+- Use `<DropdownMenuTrigger asChild>` around a Button or IconButton. Don't use Dropdown's default injected trigger.
+- For kebab menus, always set `aria-label` on the IconButton — "Actions" or the specific row context.
+- Submenus require BOTH `DropdownMenuSubTrigger` AND `DropdownMenuSubContent`. Missing either silently breaks hover-to-open.
+- `DropdownMenuShortcut` is decorative. Bind the actual shortcut separately.
+- For checkbox items, call `e.preventDefault()` inside `onSelect` to keep the menu open after toggling.
+- For interactive content beyond a list (calendars, forms), use `<Popover>` not DropdownMenu.
+- Don't nest a DropdownMenu inside another DropdownMenu — use `<DropdownMenuSub>` for hierarchy.
+- For right-click menus, use `<ContextMenu>` (separate component). DropdownMenu is click-triggered only.

package/make-kit/components/form.md

@@ -0,0 +1,189 @@
+# Form
+
+Wrap each form field in a `<FormField>`. It cascades state + a11y wiring to compatible controls automatically.
+
+```tsx
+import { FormField, FormHelperText, useFormField } from '@devalok/shilp-sutra/ui/form'
+import { Label } from '@devalok/shilp-sutra/ui/label'
+```
+
+## When to use
+
+- Every input field in a form. One `<FormField>` per logical field.
+- Provides: validation state, helper text, `aria-describedby`, `aria-invalid`, `aria-required` — wired automatically.
+- Not for layout — for stacking fields, use `<Stack gap="ds-05">`.
+
+## Compound shape
+
+```
+FormField (state, required)
+  Label                    ← htmlFor auto-resolves from FormField inputId
+  Input | Textarea | NumberInput | InputOTP | Select | Checkbox | ...
+  FormHelperText           ← reads state + helperTextId from context
+```
+
+`FormField` generates a shared `inputId`. Both `<Label>` (via `htmlFor`) and `<Input>` (via `id`) read it from context — drop the manual id-matching dance. Explicit `htmlFor` / `id` on a child still wins.
+
+## FormField props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `state` | `'helper'\|'error'\|'warning'\|'success'` | Default `helper`. Cascades to compatible controls + FormHelperText. |
+| `helperTextId` | `string` | Auto-generated if omitted. Used by `aria-describedby` wiring. |
+| `inputId` | `string` | Auto-generated if omitted. Shared between `<Label htmlFor>` and `<Input id>`. |
+| `required` | `boolean` | Sets `aria-required` on consuming controls. Does NOT auto-render the asterisk — that comes from `<Label required>`. |
+
+## FormHelperText props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `state` | `'helper'\|'error'\|'warning'\|'success'` | Inherits from FormField context. Override per-helper if needed. |
+
+When `state="error"`, FormHelperText renders `role="alert"` so screen readers interrupt.
+
+## Label props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `htmlFor` | `string` | Optional inside `<FormField>` — falls back to FormField's `inputId`. Required when used outside FormField. |
+| `required` | `boolean` | Renders red asterisk. Does NOT set `aria-required` (that comes from FormField). |
+
+## useFormField hook
+
+```ts
+const field = useFormField()
+// → { state, helperTextId, required } | undefined
+```
+
+Use inside a custom control to consume FormField context.
+
+## What auto-consumes FormField context
+
+| Control | Auto-receives |
+|---|---|
+| `<Input>` | `id` (from `inputId`), `state`, `aria-describedby`, `aria-invalid`, `aria-required` |
+| `<Textarea>` | same |
+| `<NumberInput>` | same |
+| `<InputOTP>` | `state`, `aria-describedby`, `aria-required` |
+| `<Label>` | `htmlFor` (from `inputId`) |
+
+| Control | Manual wiring needed |
+|---|---|
+| `<Select>` / `<SelectTrigger>` | Set `color="error"` on `SelectTrigger` from your validation state. |
+| `<Checkbox>`, `<Radio>`, `<Switch>` | Pair `<Label htmlFor>` manually. State is visual on the control. |
+
+## Examples
+
+**Standard text field with error:**
+```tsx
+<FormField state={errors.email ? 'error' : 'helper'}>
+  <Label htmlFor="email" required>Email</Label>
+  <Input id="email" type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+  <FormHelperText>
+    {errors.email ?? 'We will never share your email.'}
+  </FormHelperText>
+</FormField>
+```
+
+The Input receives `aria-describedby` (linked to FormHelperText), `aria-invalid="true"` when state is error, and `aria-required="true"`.
+
+**Warning state:**
+```tsx
+<FormField state="warning">
+  <Label htmlFor="password" required>Password</Label>
+  <Input id="password" type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
+  <FormHelperText>Password strength: weak. Add a number or symbol.</FormHelperText>
+</FormField>
+```
+
+**Textarea:**
+```tsx
+<FormField state={errors.bio ? 'error' : 'helper'}>
+  <Label htmlFor="bio">Bio</Label>
+  <Textarea id="bio" rows={4} value={bio} onChange={(e) => setBio(e.target.value)} />
+  <FormHelperText>{errors.bio ?? `${bio.length} / 200`}</FormHelperText>
+</FormField>
+```
+
+**Required Checkbox (manual label pairing):**
+```tsx
+<FormField required state={errors.terms ? 'error' : 'helper'}>
+  <Stack direction="horizontal" gap="ds-03" align="center">
+    <Checkbox id="terms" checked={agreed} onCheckedChange={setAgreed} />
+    <Label htmlFor="terms">I agree to the terms.</Label>
+  </Stack>
+  {errors.terms && <FormHelperText>{errors.terms}</FormHelperText>}
+</FormField>
+```
+
+**Full form layout:**
+```tsx
+<form onSubmit={handleSubmit}>
+  <Stack gap="ds-05">
+    <FormField>
+      <Label htmlFor="name" required>Name</Label>
+      <Input id="name" />
+    </FormField>
+
+    <FormField>
+      <Label htmlFor="email" required>Email</Label>
+      <Input id="email" type="email" />
+      <FormHelperText>For account recovery only.</FormHelperText>
+    </FormField>
+
+    <FormField state={errors.role ? 'error' : 'helper'}>
+      <Label htmlFor="role">Role</Label>
+      <Select>
+        <SelectTrigger id="role" color={errors.role ? 'error' : 'default'}>
+          <SelectValue placeholder="Choose a role" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="admin">Admin</SelectItem>
+          <SelectItem value="member">Member</SelectItem>
+        </SelectContent>
+      </Select>
+      {errors.role && <FormHelperText>{errors.role}</FormHelperText>}
+    </FormField>
+
+    <Stack direction="horizontal" gap="ds-03" justify="end">
+      <Button variant="soft" type="button">Cancel</Button>
+      <Button type="submit">Save</Button>
+    </Stack>
+  </Stack>
+</form>
+```
+
+**Custom control consuming FormField context:**
+```tsx
+function ColorPickerField(props) {
+  const field = useFormField()
+  return (
+    <ColorPicker
+      {...props}
+      aria-describedby={field?.helperTextId}
+      aria-invalid={field?.state === 'error' || undefined}
+      aria-required={field?.required || undefined}
+    />
+  )
+}
+```
+
+## Composability
+
+- **Explicit props override context** — `<Input state="error">` inside a `<FormField state="helper">` makes only that input look errored. Same for `id` / `htmlFor`.
+- **Don't nest FormFields** — only the outermost context wins. Some a11y wiring silently breaks.
+- **Label-to-control pairing auto-wires inside FormField** via the shared `inputId`. Outside FormField, set `htmlFor` + `id` explicitly.
+- **For non-auto-wired controls** (Checkbox, Radio, Switch) where the visible label sits beside the control, you can still drop the `htmlFor` if you put the control inside FormField with no other Inputs — `inputId` resolves on the Checkbox via its `id` prop the same way.
+
+See `foundations/color.md` for state colors, `foundations/spacing.md` for inter-field spacing (`ds-05` default).
+
+## Rules
+
+- One FormField per logical field. Never nest FormFields.
+- For error display, drive `FormField state` from your validation state — every consuming control updates together.
+- For Select / Checkbox / Radio / Switch, set the control's error visual manually (`color="error"` on SelectTrigger) — they don't auto-consume FormField state, only ids and a11y attrs.
+- Don't use the removed `getFormFieldA11y()` helper — use the `useFormField()` hook.
+- Inside FormField, `<FormHelperText>` reads `state` + id from context — don't pass them again unless intentionally overriding.
+- Use `<Stack gap="ds-05">` to space fields vertically. Don't reach for `ds-04` or `ds-06` — see `foundations/spacing.md`.
+- `<Label required>` only renders the asterisk. The `aria-required` flag comes from `<FormField required>`.
+- You can omit `id` on `<Input>` and `htmlFor` on `<Label>` inside a `<FormField>` — both resolve from FormField's `inputId`. Set them explicitly only when overriding the auto-generated id.

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.