@devalok/shilp-sutra 0.41.0 → 0.42.1

package/make-kit/components/dialog.md

@@ -0,0 +1,167 @@
+# Dialog
+
+Centered modal overlay for focused tasks that interrupt the page flow.
+
+```tsx
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  DialogClose,
+} from '@devalok/shilp-sutra/ui/dialog'
+```
+
+## When to use
+
+- Confirmations (destructive actions, accept-terms).
+- Short forms that need full attention (rename, share, invite).
+- Critical announcements requiring acknowledgment.
+- Side-anchored drawer (settings panel, mobile nav)? Use `<Sheet>`.
+- Lightweight rich tooltip with no required interaction? Use `<HoverCard>`.
+- Interactive panel anchored to a trigger (filter, picker)? Use `<Popover>`.
+
+On mobile, Dialog auto-promotes to a full-screen sheet — don't rebuild this manually.
+
+## Compound shape
+
+```
+Dialog (root — open, onOpenChange, defaultOpen, modal)
+  DialogTrigger          ← uses asChild around a Button
+  DialogContent          ← portalled, traps focus
+    DialogHeader
+      DialogTitle         ← REQUIRED for a11y
+      DialogDescription
+    [body content]
+    DialogFooter
+      DialogClose         ← uses asChild around a Button
+```
+
+## Root props (passthrough to Radix)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `open` | `boolean` | Controlled mode. |
+| `onOpenChange` | `(open: boolean) => void` | Fires on every state change. |
+| `defaultOpen` | `boolean` | Uncontrolled. |
+| `modal` | `boolean` | Default `true`. Set `false` for non-blocking overlays (rare). |
+
+Styling props live on `DialogContent`. Trigger / Close use `asChild` to merge with your Button.
+
+## Examples
+
+**Confirmation:**
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="soft" color="error">Delete project</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Delete this project?</DialogTitle>
+      <DialogDescription>
+        This permanently deletes all tasks, files, and history. Cannot be undone.
+      </DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="soft">Cancel</Button>
+      </DialogClose>
+      <Button variant="solid" color="error" onClick={handleDelete}>
+        Delete
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+**Short form:**
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Rename workspace</DialogTitle>
+    </DialogHeader>
+    <Stack gap="ds-04">
+      <FormField>
+        <Label htmlFor="ws-name">Name</Label>
+        <Input id="ws-name" value={name} onChange={(e) => setName(e.target.value)} />
+      </FormField>
+    </Stack>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="soft">Cancel</Button>
+      </DialogClose>
+      <Button onClickAsync={async () => { await api.rename(name); setOpen(false) }}>
+        Save
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+**Visually-hidden title (a11y compliance without showing the heading):**
+```tsx
+<DialogContent>
+  <VisuallyHidden>
+    <DialogTitle>Image preview</DialogTitle>
+  </VisuallyHidden>
+  <img src={src} alt={alt} />
+</DialogContent>
+```
+
+**Programmatic close from a deep child:**
+```tsx
+<DialogContent>
+  <Stack>
+    <FancyForm onSubmit={handleSubmit} />
+    <DialogClose asChild>
+      <Button variant="ghost">Done</Button>
+    </DialogClose>
+  </Stack>
+</DialogContent>
+```
+
+**Nested Popover inside Dialog:**
+```tsx
+<Dialog>
+  <DialogContent>
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="soft">Pick a date</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <Calendar value={date} onChange={setDate} />
+      </PopoverContent>
+    </Popover>
+  </DialogContent>
+</Dialog>
+```
+
+Popover uses `z-popover` (1400) which is above `z-dialog` — nesting stacks correctly without z-index fights.
+
+## Mobile behavior
+
+On viewports below the `md` breakpoint, DialogContent auto-fullscreens with a top-anchored close button. Layouts that work on desktop in centered modal usually work on mobile in fullscreen as-is — but verify long forms scroll inside the dialog body, not the page.
+
+## Composability
+
+- **Portal rendering:** DialogContent portals to `document.body`. CSS `overflow: hidden`, `transform`, or stacking contexts on ancestors don't clip it.
+- **Focus management:** Focus traps inside while open. First focusable element receives focus. Returns to trigger on close.
+- **Imperative close:** Wrap your own button with `<DialogClose asChild>` — no prop drilling.
+- **z-index:** `z-dialog`. Popovers, DropdownMenus, Tooltips inside stack above using `z-popover`.
+
+See `foundations/surfaces.md` for the overlay surface tokens, `foundations/motion.md` for the spring entry animation.
+
+## Rules
+
+- Always render a `<DialogTitle>` — screen readers depend on it. If the design hides it visually, wrap it in `<VisuallyHidden>`.
+- Use `<DialogTrigger asChild>` with a Button — don't use Dialog's default injected trigger.
+- For destructive actions, place the destructive Button on the right with `color="error"`. Cancel (`<DialogClose>`) sits left with `variant="soft"`.
+- Don't manipulate `open` from inside the content tree without going through `onOpenChange` or `<DialogClose>` — focus restoration breaks.
+- Don't nest Dialogs. Use a single Dialog with stepped state, or close the first before opening the second.
+- For side-anchored drawers, switch to `<Sheet>`. Don't recreate Sheet behavior with custom Dialog styling.
+- If your Dialog is mostly read-only content (image preview, log viewer), still provide a `<DialogTitle>` for a11y, hidden if needed.

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.