@devalok/shilp-sutra 0.37.0 → 0.37.1

package/docs/components/ui/chat.md

@@ -199,6 +199,15 @@ Animated bouncing dots with a text description of who is typing.
 
 ---
 
+## Composability
+- **Chat is a kit of 7 primitives, not a monolithic ChatWindow.** Compose MessageList (scroll container) + Message/SystemMessage (row variants) + DateSeparator/UnreadSeparator (visual dividers) + MessageInput (composer) + TypingIndicator (presence).
+- **Message is a compound component** — `Message.Avatar`, `Message.Content`, `Message.Author`, `Message.Body`, `Message.Reactions`, `Message.Actions`, `Message.Action`. Arrange them to match your design; most layouts only need Avatar + Content (with Author + Body inside).
+- **Message.Actions reveal on hover** via `group-hover/message` — ONLY works when Actions is nested inside a Message root. If you want a custom action bar, do it differently.
+- **MessageList ARIA:** `role="log" + aria-live="polite"` — screen readers announce new messages automatically. Don't manually add aria-live to children.
+- **grouped mode:** For consecutive messages from the same user, set `grouped={true}` to hide the avatar and author (typical chat UI pattern). Logic for "same user as previous" is consumer-side.
+- **MessageInput is specifically for chat** — auto-resizing textarea (up to 160px), Enter-to-send, Shift+Enter-for-newline, streaming support. For richer composition (formatting, attachments), use RichChatInput from composed (built on top of this + TipTap).
+- **TypingIndicator** accepts multiple users — handles pluralization of the "is/are typing" label automatically.
+
 ## Gotchas
 - MessageList uses `role="log"` with `aria-live="polite"` — screen readers announce new messages
 - Message entrance animations use Framer Motion springs — AnimatePresence wraps children in MessageList

package/docs/components/ui/checkbox.md

@@ -7,20 +7,34 @@
 ## Props
     checked: boolean | "indeterminate"
     onCheckedChange: (checked: boolean | "indeterminate") => void
+    size: "sm" | "md" | "lg"
     error: boolean (shows red border)
     indeterminate: boolean (overrides checked, shows dash icon)
     disabled: boolean
 
 ## Defaults
-    none
+    size="md"
 
 ## Example
 ```jsx
 <Checkbox checked={agreed} onCheckedChange={(v) => setAgreed(v === true)} />
+
+{/* With label */}
+<label htmlFor="terms" className="flex items-center gap-ds-02">
+  <Checkbox id="terms" checked={agreed} onCheckedChange={(v) => setAgreed(v === true)} />
+  I agree to the terms
+</label>
 ```
 
+## Composability
+- **FormField integration:** Unlike Input/Textarea, Checkbox does NOT auto-consume FormField state — the `error` prop must be set explicitly. (Form-library convention differs for checkboxes since they often don't share the same visual grouping.)
+- **Labels:** Checkbox doesn't carry its own label — pair it with `<Label htmlFor="x" />` + `<Checkbox id="x" />`, or wrap both in a `<label>` element. Screen readers rely on that association.
+- **Controlled vs uncontrolled:** Pass `checked` + `onCheckedChange` for controlled, `defaultChecked` for uncontrolled. Don't mix.
+
 ## Gotchas
 - indeterminate overrides checked visually
+- Checkbox does NOT auto-consume FormField error state — pass `error` explicitly if using inside a FormField
+- WCAG 2.5.8 minimum target size met at md (24px); sm (20px) may fail if not paired with enough label hit area
 
 ## Changes
 ### v0.22.0

package/docs/components/ui/chip.md

@@ -26,11 +26,20 @@
 ## Additional Exports
     ChipGroup — re-exported AnimatePresence from framer-motion; wrap a list of Chips for coordinated exit animations
 
+## Composability
+- **DEPRECATED — use Badge instead.** Chip v0.29.0+ superset capability merged into Badge. Chip remains in the library for backward compatibility; new code should use:
+  - `<Badge>...</Badge>` for static tags (replaces `<Chip label="..." />`)
+  - `<Badge onClick={...} selected={isSelected}>...</Badge>` for interactive filter chips
+  - `<Badge onDismiss={...}>...</Badge>` for dismissible chips
+- **Why deprecated:** Chip used `label` prop (not children) and had a separate CVA; Badge now supports everything Chip did via children + onClick/onDismiss/selected, with more colors and variants.
+- **Migration:** `<Chip label="React" color="info" />` → `<Badge variant="subtle" color="info">React</Badge>`. ChipGroup → BadgeGroup or just AnimatePresence wrapper.
+
 ## Gotchas
 - MUST use label prop — children are NOT rendered
 - `<Chip>text</Chip>` is WRONG — use `<Chip label="text" />`
 - Wrap dynamic chip lists in `<ChipGroup>` for exit animations
 - `color="primary"` will be renamed to `color="brand"` in v1.0 — use `color="primary"` for now
+- **Deprecated — migrate to Badge for all new code**
 
 ## Changes
 ### v0.19.1

package/docs/components/ui/code.md

@@ -17,8 +17,15 @@
 <Code variant="block">{`const x = 1;\nconsole.log(x);`}</Code>
 ```
 
+## Composability
+- **Server-safe.** No context, no cascade.
+- Inline variant composes inside Text, paragraphs, list items, table cells — wherever body text goes.
+- Block variant is a `<pre><code>` pair with overflow-x scroll; pair with a dark background Card or MarkdownViewer for long snippets.
+- Not a syntax-highlighted code viewer — for that, use RichTextEditor's code block or a dedicated library. Code here is typographic emphasis, not lexer-aware rendering.
+
 ## Gotchas
 - "block" renders as `<pre><code>`, "inline" renders as `<code>`
+- Block variant doesn't syntax-highlight — it's a styled pre tag, nothing more
 
 ## Changes
 ### v0.1.1

package/docs/components/ui/collapsible.md

@@ -25,8 +25,17 @@
 </Collapsible>
 ```
 
+## Composability
+- Radix Collapsible primitive — smaller than Accordion (no grouping/value matching, just open/close).
+- **When to use:** A single show/hide section where the state is local (e.g. "Advanced options" inside a form, expandable row detail, show-more). For multi-section with mutual exclusion, use Accordion.
+- **Inline rendering:** CollapsibleContent is NOT portalled — it expands inline and pushes sibling content down. Respects `overflow` rules of the parent.
+- **No built-in chevron** — unlike AccordionTrigger, CollapsibleTrigger is bare. Add your own icon + rotate via `data-state` attribute Radix sets (`[data-state=open]:rotate-180`).
+- **Animation:** Height transition via `animate-collapsible-down/up` keyframes + Radix `--radix-collapsible-content-height` CSS custom property.
+
 ## Gotchas
 - Standard Radix Collapsible API
+- No auto-chevron — add one manually if you want the affordance
+- Not portalled — clipped by parent `overflow: hidden`
 
 ## Changes
 ### v0.13.0

package/docs/components/ui/color-input.md

@@ -61,6 +61,14 @@
 <ColorInput value={color} onChange={setColor} showPicker={false} />
 ```
 
+## Composability
+- **Built on Popover internally** — trigger opens a portal-rendered picker panel. z-popover (1400) stacking.
+- **variant="default" vs "inline":** Default variant is an input-style trigger with gradient swatch + hex label (fits in forms). Inline variant IS the selected color — the entire trigger takes the color as its background with contrast-aware text. Use inline for color-tags in chat, lists, or tight toolbar UIs.
+- **Controlled or uncontrolled:** Works both ways — pass `value` + `onChange` for controlled, or omit and let internal state track.
+- **Presets are compositional:** Pass `{ hex, label }[]` for named brand colors (accessible, keyboard-navigable). Pass `false` to hide the preset strip entirely (picker-only mode).
+- **react-colorful** is bundled (2.8KB gzipped) — zero additional setup. Picker itself is pointer-based; keyboard users edit via the HEX/RGB/HSL format inputs below.
+- **FormField:** Not auto-consumed (no `state` prop). Wrap in FormField for label + helper text; style error visuals via className.
+
 ## Gotchas
 - Value must be a 6-character hex string (e.g. "#d33163")
 - Presets accept both `string[]` (backward-compatible) and `{ hex, label }[]` (recommended for accessibility)

package/docs/components/ui/color-swatch.md

@@ -20,6 +20,13 @@
 <ColorSwatch color="oklch(0.7 0.15 200)" shape="rounded" />
 ```
 
+## Composability
+- **Server-safe, decorative-only primitive.** Accepts any valid CSS color string — hex, rgb, oklch, hsl, named. Pure presentation, no context.
+- **Usage patterns:** Inline color marker next to a label, preview dot in lists, color-indicator in a category chip, legend swatch for charts.
+- **`ring={true}`** adds a subtle outline — essential for white/very-light colors that would otherwise disappear on surface-raised backgrounds.
+- **Interactive color picking:** Use ColorInput (which opens a full picker). ColorSwatch is display-only.
+- No IconProvider cascade, no FormField consumption — composes freely with anything.
+
 ## Gotchas
 - Color is applied via inline `backgroundColor` style, not a token class — accepts any runtime CSS color string
 - Renders `role="presentation"` — purely decorative, not interactive

package/docs/components/ui/combobox.md

@@ -6,6 +6,7 @@
 
 ## Props
     options: ComboboxOption[] (REQUIRED) — { value: string, label: string, description?: string, icon?: ReactNode, disabled?: boolean }
+    size: "xs" | "sm" | "md" | "lg" (trigger height)
     DISCRIMINATED UNION — type depends on `multiple` flag:
     Single (default): multiple?: false, value?: string, onValueChange: (value: string) => void
     Multiple: multiple: true, value?: string[], onValueChange: (value: string[]) => void
@@ -13,13 +14,14 @@
     searchPlaceholder: string (default: "Search...")
     emptyMessage: string (default: "No results found")
     disabled: boolean
-    triggerClassName: string
+    className: string (wrapper div — the positioning container, NOT the trigger)
+    triggerClassName: string (the actual Popover trigger button)
     accessibleLabel: string (custom aria-label for trigger, falls back to placeholder)
     maxVisible: number (default: 6, max dropdown items before scroll)
     renderOption: (option, selected) => ReactNode
 
 ## Defaults
-    placeholder="Select...", searchPlaceholder="Search...", emptyMessage="No results found", maxVisible=6
+    size="md", placeholder="Select...", searchPlaceholder="Search...", emptyMessage="No results found", maxVisible=6
 
 ## Example
 ```jsx
@@ -32,9 +34,20 @@
 />
 ```
 
+## Composability
+- **Combobox vs Autocomplete vs Select:** Combobox = typeahead search + forced selection (the user picks from filtered options). Autocomplete = typeahead + free text allowed. Select = no typeahead, click-to-open with fixed options. Pick by user behavior, not visual style.
+- **Single vs multi mode** is a discriminated union — `multiple: true` changes the shape of value (`string[]`) and onValueChange. TypeScript enforces the pairing.
+- **Multi-select pills:** Capped at 2 visible + "+N more" overflow regardless of `maxVisible`. Clicking the +N opens a popover list of all selected items (handled by the component).
+- **className vs triggerClassName:** className lands on the wrapper (positioning); triggerClassName lands on the trigger button (styling the control). Know which you need.
+- **Portal + z-popover (1400):** content stacks above Dialog/Sheet; works inside scrolling containers without clipping.
+- **renderOption:** For complex option rendering (avatar + label + description), pass `renderOption: (option, selected) => <YourCustom />`. The selected state is a boolean flag.
+- **FormField:** Does NOT auto-consume FormField state. Wrap in FormField for label + helper text, but style error manually.
+
 ## Gotchas
 - Enforces selection from list (unlike Autocomplete which allows free text)
-- In multi mode, selected items appear as pills with "+N more" overflow
+- In multi mode, selected items appear as pills with "+N more" overflow (capped at 2 visible pills regardless of `maxVisible`)
+- `className` vs `triggerClassName`: `className` lands on the wrapper div (useful for width/positioning); `triggerClassName` lands on the actual Popover trigger button (useful for styling the control itself)
+- Dropdown content is portalled to document.body — parent styles like `overflow: hidden` don't clip it, and container-scoped test queries won't find it
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/container.md

@@ -18,8 +18,19 @@
 </Container>
 ```
 
+## Composability
+- **Server-safe layout primitive.** Safe in RSC trees — no hooks, no context.
+- **maxWidth choices:**
+  - `"default"` (standard page container — matches the design system's layout grid)
+  - `"body"` (narrower reading width — use for article/blog content)
+  - `"full"` (no max — edge-to-edge, useful for full-bleed marketing sections)
+- **Polymorphic via `as`:** Change the rendered element for semantics (`as="main"` for page content, `as="section"` for major subdivisions, `as="article"` for standalone content).
+- **mx-auto centering is automatic** — Container handles horizontal centering; it does NOT add vertical spacing. Pair with `py-*` utility classes on the Container itself or inside it.
+- Nothing cascades — nesting Containers is fine but rarely useful (max-width constraints compound).
+
 ## Gotchas
 - Server-safe component — can be imported directly in Next.js Server Components
+- Container does NOT add vertical padding — add it explicitly via className if needed
 
 ## Changes
 ### v0.1.0

package/docs/components/ui/context-menu.md

@@ -29,8 +29,16 @@
 </ContextMenu>
 ```
 
+## Composability
+- Radix ContextMenu — same item-variant surface as DropdownMenu (checkbox, radio group, sub-menus, label, separator) with the same keyboard model. Swap `Dropdown` → `Context` in imports and everything behaves the same.
+- **Trigger is not a button** — ContextMenuTrigger is a wrapper element (defaults to `<div>`) that listens for `contextmenu` events on itself and children. Use `asChild` to pass styling to your own element.
+- **Touch support:** Radix maps long-press to right-click. On mobile, hold-to-open just works without extra code.
+- **No visible trigger affordance** — unlike DropdownMenu/Popover, the user has to *know* the element is right-clickable. Pair with a visible hint (keyboard shortcut label, menu icon elsewhere) for discoverability.
+- **Portal + z-index:** z-popover (1400).
+
 ## Gotchas
 - Triggered by right-click (or long-press on touch devices)
+- ContextMenuTrigger doesn't auto-indicate it's interactive — add visual affordance elsewhere on the page
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/data-table-body.md

@@ -7,6 +7,10 @@
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the tbody + rows for DataTable. Consumes DataTableContext for row data, selection state, expandable state, loading skeletons.
+- Customization routes through DataTable props: `renderExpanded`, `onRowClick`, `getRowId`, `loading`, `emptyState`.
+
 ## Changes
 
 ### v0.32.0

package/docs/components/ui/data-table-bulk-actions.md

@@ -7,6 +7,10 @@
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the floating bulk-action bar that appears when rows are selected. Reads selection state + bulkActions config from DataTableContext.
+- Customization goes through DataTable's `bulkActions` prop — `{ label, onClick, color?, disabled? }[]`.
+
 ## Changes
 
 ### v0.32.0

package/docs/components/ui/data-table-card.md

@@ -7,6 +7,10 @@
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the card wrapper around DataTable (border, shadow, rounded corners matching the Card primitive's surface treatment).
+- DataTable uses this automatically — no consumer-facing prop toggles it.
+
 ## Changes
 
 ### v0.32.0

package/docs/components/ui/data-table-context.md

@@ -7,6 +7,10 @@
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal React context** — binds DataTable's sub-components (header, body, pagination, toolbar, bulk-actions) to shared state: TanStack table instance, density, selection, loading.
+- Consumer code never reads this context — all interaction goes through DataTable's props.
+
 ## Changes
 
 ### v0.32.0

package/docs/components/ui/data-table-header.md

@@ -7,6 +7,10 @@
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the thead + column headers for DataTable. Reads sort state + column definitions from DataTableContext.
+- Customization goes through DataTable's `columns` prop (column definitions are TanStack ColumnDef<TData> — header, sortable, filter, etc. all declared there).
+
 ## Changes
 
 ### v0.32.0

package/docs/components/ui/data-table-pagination.md

@@ -7,6 +7,10 @@
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the pagination footer for DataTable. Reads pagination state from DataTableContext.
+- Customization goes through DataTable's `pagination` prop (server-side: pass `{ page, pageSize, total, onPageChange }`) or `pageSize` + `paginated` (client-side).
+
 ## Changes
 
 ### v0.32.0

package/docs/components/ui/data-table-toolbar.md

@@ -31,10 +31,17 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 />
 ```
 
+## Composability
+- **Companion to DataTable** — typically enabled via DataTable's `toolbar={true}` prop (which auto-renders this internally). Use DataTableToolbar directly only if you're building a custom DataTable integration that needs the toolbar positioned/styled differently.
+- **Reads table state via the `table` instance** (TanStack react-table) — you must pass it. For the auto-rendered version inside DataTable, this wiring is automatic.
+- **Feature toggles:** `globalFilter` (search across all columns), density switcher (compact/standard/comfortable row heights), CSV export. Turn each on/off independently.
+- **Density changes are runtime** — the switcher writes to the same `defaultDensity` that DataTable's prop seeds. State lives in DataTable context.
+
 ## Gotchas
 - Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table-toolbar`, NOT the `ui` barrel
 - Companion to DataTable — provides column visibility, density toggle, and CSV export controls
 - Requires @tanstack/react-table as a peer dependency
+- Prefer DataTable's `toolbar={true}` prop over rendering this directly
 
 ## Changes
 ### v0.5.0

package/docs/components/ui/data-table.md

@@ -55,6 +55,30 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 />
 ```
 
+## Composability
+**Server vs client mode is prop-driven, not explicit.**
+- Pass `onSort` → server-side sort (manual, rows stay in data order — you're responsible for re-fetching).
+- Pass `pagination` object → server-side pagination (manual, pass total count).
+- Omit both → client-side sort/pagination via TanStack react-table.
+- Mix-and-match: `onSort` + no pagination = server sort + client pagination.
+
+**Companion components:**
+- `DataTableToolbar` — enabled via `toolbar={true}`. Provides column visibility, density switcher, CSV export. Reads table state via `DataTableContext` (internal). Rendered ABOVE the table automatically.
+- `BulkActionBar` (floating) — appears when rows are selected AND `bulkActions` array is non-empty. Synced with `selectedIds`; shows count + action buttons.
+- `EmptyState` from `@devalok/shilp-sutra/composed` — pass to `emptyState` prop. Takes precedence over `noResultsText` string.
+
+**Controlled selection:**
+- Pass `selectedIds` (Set<string>) + `onSelectionChange` for controlled row selection.
+- Provide `getRowId: (row) => row.id` so selection survives data refetches (otherwise TanStack uses array index, which breaks on sort/filter).
+- `selectableFilter: (row) => boolean` disables selection on specific rows (e.g. archived items).
+
+**Row click model:**
+- `onRowClick` fires on row-level click BUT excludes clicks on checkboxes, buttons, links, and inputs automatically. No manual `stopPropagation` needed for standard interactive elements.
+
+**Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height.
+
+**Density integration:** `defaultDensity="compact"` is the Karm-style dense mode (h-9 rows). DataTableToolbar's density switcher updates this at runtime; the prop sets the initial state only.
+
 ## Gotchas
 - Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table`, NOT the `ui` barrel
 - Requires @tanstack/react-table and @tanstack/react-virtual as peer dependencies
@@ -63,6 +87,7 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 - selectedIds syncs via useEffect — provide getRowId for custom row IDs
 - onRowClick does NOT fire when clicking checkboxes, buttons, links, or inputs
 - Use defaultDensity="compact" for Karm-style h-9 rows
+- `virtualRows={true}` requires a bounded scroll container — unbounded height silently disables virtualization
 
 ## Changes
 ### v0.29.0

package/docs/components/ui/devalok-grain.md

@@ -41,6 +41,14 @@
 </div>
 ```
 
+## Composability
+- **Brand texture overlay** — drops into any parent with `relative overflow-hidden isolate`. Auto-inherits the parent's border radius.
+- **Button auto-extracts Grain children** — if you nest `<DevalokGrain>` inside a `<Button>`, Button auto-separates it from the label slot and positions it correctly. No extra wrapping needed.
+- **Card, custom hero sections, landing-page tiles** — wrap in a positioned container (or add the `relative overflow-hidden isolate` classes to Card explicitly) and drop Grain in as a sibling to your content.
+- **z-layer contract:** Grain renders at `z-[1]`. Content on top needs `z-[2]+`. The component doesn't boost child z-index — that's consumer responsibility.
+- **`hoverIntensify` depends on parent** — the parent must have the Tailwind `group` class so `group-hover:` selectors apply. Forgetting this silently disables the effect.
+- **Tint composes with surface:** Pass an OKLCH color (or CSS variable reference like `var(--color-accent-9)`) to `tint` for a directional gradient on top of the noise. Without tint, just noise.
+
 ## Gotchas
 - Parent element MUST have `relative overflow-hidden isolate` for the grain to render correctly
 - The grain layers are absolute-positioned at `z-[1]` — content that should appear above must use `z-[2]` or higher

package/docs/components/ui/dialog.md

@@ -35,8 +35,18 @@
 </Dialog>
 ```
 
+## Composability
+- Built on Radix Dialog primitives — every standard Radix prop passes through (`open`, `onOpenChange`, `defaultOpen`, `modal`).
+- **Trigger composition:** `<DialogTrigger asChild>` renders the wrapped element as the trigger — typical pattern is `<DialogTrigger asChild><Button>...</Button></DialogTrigger>`. Without `asChild`, a default button is injected.
+- **Portal rendering:** DialogContent portals to `document.body`. CSS containers (`overflow: hidden`, `transform`, stacking contexts) on ancestors of the trigger don't clip it. Container-scoped test queries miss portalled content — use `screen` or the portal root.
+- **Focus management:** Radix traps focus inside Content while open and restores it to the trigger on close. First focusable element inside receives focus automatically.
+- **Imperative close** from deep children: use `<DialogClose asChild>` around your own button, or `useDialogContext` — no prop drilling.
+- **z-index:** DialogContent uses `z-dialog` (configured in Tailwind theme). Nested overlays (Popover inside Dialog) stack on top because Popover uses `z-popover` (1400) higher than `z-dialog`.
+
 ## Gotchas
 - DialogTitle is required for accessibility — screen readers announce it when the dialog opens
+- If your layout suppresses the title visually, use `<VisuallyHidden>` around DialogTitle — don't omit it
+- Focus returns to the trigger on close — if the trigger is conditionally unmounted, focus lands on body; handle manually if that matters
 
 ## Changes
 ### v0.19.1

package/docs/components/ui/dropdown-menu.md

@@ -31,8 +31,18 @@
 </DropdownMenu>
 ```
 
+## Composability
+- Radix DropdownMenu underneath — same prop surface (`open`, `onOpenChange`, `defaultOpen`, `modal`).
+- **Item variants** stack cleanly: `DropdownMenuCheckboxItem` for multi-select toggles, `DropdownMenuRadioGroup` + `DropdownMenuRadioItem` for single-select, `DropdownMenuSub` + `DropdownMenuSubTrigger/SubContent` for nested submenus. Each has its own keyboard model pre-wired.
+- **Keyboard:** Arrow keys navigate items, Enter/Space activates, Esc closes, typeahead jumps to first letter. All handled by Radix — don't re-implement.
+- **Trigger:** `<DropdownMenuTrigger asChild>` around any button. IconButton is the common pairing.
+- **Shortcut hints:** `<DropdownMenuShortcut>` inside an item renders a right-aligned `⌘K`-style kbd. Visual only — does NOT bind the shortcut globally.
+- **Closing from a handler:** Item onSelect auto-closes the menu by default. Pass `event.preventDefault()` inside the handler to keep it open (e.g. for checkbox items that shouldn't close on toggle).
+
 ## Gotchas
 - Use `asChild` on DropdownMenuTrigger to render your own button element
+- DropdownMenuShortcut is decorative — bind keyboard shortcuts separately (e.g. with `useHotkeys`)
+- Sub-menus need BOTH DropdownMenuSubTrigger (visible item) and DropdownMenuSubContent (the submenu panel) — missing either silently breaks the hover-open behavior
 
 ## Changes
 ### v0.22.0

package/docs/components/ui/file-upload.md

@@ -32,9 +32,17 @@
 />
 ```
 
+## Composability
+- **Two modes, one component:** `compact={false}` (default) = drag-and-drop zone with visible affordance; `compact={true}` = inline "Upload" button. Swap by prop, same callback.
+- **Progress integration:** Drive `uploading` + `progress` from your upload logic. The component renders an embedded Progress bar when uploading=true.
+- **Validation is built-in:** `accept` (MIME types / extensions) + `maxSize` are enforced before `onFiles` fires. Invalid files produce `error` state instead of calling through. Your onFiles never has to re-validate.
+- **Multi-file:** `multiple={true}` accepts File[] (array always, even for single-file mode — use `files[0]`).
+- **Composes with Toast for feedback:** Pair with toast.success on upload complete, toast.error on failure.
+
 ## Gotchas
 - compact=true renders a small inline button; false (default) renders a large drag-and-drop zone
 - Client-side validation: invalid files are rejected before onFiles is called
+- `onFiles` always receives an array — use `files[0]` even when `multiple={false}`
 
 ## Changes
 ### v0.1.0

package/docs/components/ui/form.md

@@ -31,10 +31,31 @@
 </FormField>
 ```
 
+## Composability
+The FormField/useFormField pair is the central a11y wiring pattern. Components that consume it automatically become accessible inside a FormField without any explicit ARIA work on your end.
+
+**FormField cascades through context to:**
+- **Input, Textarea, NumberInput, InputOTP** — auto-receive `aria-describedby` (wired to FormHelperText's id), `aria-invalid` (when state="error"), and `aria-required` (when required=true).
+- **FormHelperText** — auto-reads `state` and `helperTextId` from context; renders `role="alert"` on error so screen readers interrupt.
+- **Label** — pair it with an Input via `htmlFor` / `id` in the normal way; FormField doesn't auto-wire labels (labels need the explicit association to satisfy screen readers reliably).
+
+**Explicit props always override context.** Setting `state="error"` on an Input inside a FormField with `state="helper"` makes only that Input look errored.
+
+**Nesting is NOT supported.** Don't nest FormField inside FormField — only the outermost context wins, and some a11y wiring silently breaks.
+
+**Consuming context in your own components:**
+```tsx
+const field = useFormField()  // returns { state, helperTextId, required } or undefined
+// Thread field?.state onto your control's state prop,
+// and field?.helperTextId onto aria-describedby.
+```
+
 ## Gotchas
 - getFormFieldA11y() was REMOVED — use useFormField() hook instead
 - FormHelperText auto-reads state and id from FormField context
 - FormHelperText renders role="alert" when state="error"
+- Don't nest FormField components — one FormField per field
+- FormField does NOT auto-wire Label→Input association; use `<Label htmlFor="x" />` + `<Input id="x" />` explicitly
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/hover-card.md

@@ -17,8 +17,17 @@
 </HoverCard>
 ```
 
+## Composability
+- Radix HoverCard — accepts `open`, `onOpenChange`, `defaultOpen`, `openDelay` (ms before show), `closeDelay` (ms before hide).
+- **Distinction from Tooltip:** HoverCardContent can contain interactive elements (links, buttons, form fields). Tooltip is for inert text labels. If you need a rich hover preview — user card, link preview, product card — use HoverCard.
+- **Distinction from Popover:** Popover opens on click/focus; HoverCard opens on hover/focus. Use HoverCard when the intent is a passive preview, Popover when the user must explicitly invoke the panel.
+- **Trigger:** `<HoverCardTrigger asChild>` wraps any element. Works on `<span>`, `<a>`, `<button>` — the trigger doesn't need to be interactive itself (unlike Popover where click matters).
+- **Accessibility:** Hover-only interactions are invisible on touch. Pair with a focus-visible state or use Popover instead for critical content.
+- **Portal + z-index:** z-popover (1400), same as DropdownMenu/Popover.
+
 ## Gotchas
 - Overlay component — uses Framer Motion for enter/exit animations (v0.18.0)
+- Don't nest another HoverCard inside one — both open on the same hover and conflict
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/icon-button.md

@@ -25,6 +25,13 @@
 <IconButton icon={<Icon icon={IconTrash} />} variant="solid" color="error" aria-label="Delete" />
 ```
 
+## Composability
+- **Built on Button internally** — inherits ALL Button features: variant, color, loading, onClickAsync, processing, ButtonGroup context consumption, asChild. Use IconButton when your button is icon-only; use Button for label-plus-icon.
+- **aria-label is TypeScript-enforced** — the library makes it impossible to forget. This is the key accessibility constraint for icon-only buttons.
+- **IconProvider cascade:** The `icon` prop expects `<Icon icon={...} />` — Icon auto-sizes based on IconButton's `size` via IconProvider context (no need to pass size to the nested Icon).
+- **Inside ButtonGroup:** Inherits variant/color/size/weight from ButtonGroup context just like Button does. Useful for icon-only toolbars.
+- **IconGroup vs ButtonGroup of IconButtons:** IconGroup is for static icon clusters (not interactive, or for decorative displays). ButtonGroup of IconButtons is for interactive toolbars where each icon is a button.
+
 ## Gotchas
 - aria-label is enforced by TypeScript — you MUST provide it
 - Prefer IconButton over Button with size="icon-*" for icon-only buttons

package/docs/components/ui/icon-context.md

@@ -28,6 +28,13 @@ import { IconProvider, useIconContext } from '@devalok/shilp-sutra/ui'
 const { size, stroke } = useIconContext()
 ```
 
+## Composability
+- **Low-level context primitive** — rarely used directly. Most consumers want IconGroup (which wraps IconProvider + layout) or just nest Icons inside Button/Input/Badge (which provide their own IconProvider).
+- **When to reach for IconProvider manually:** Building a custom container that hosts many Icons (a dashboard tile row, a custom toolbar, a nav rail) and you want consistent icon sizing without repeating props. IconProvider is the escape hatch for that.
+- **Consumer contract:** `useIconContext()` returns `{}` (empty) when no provider is present — your consumer code MUST handle that (fall back to a default size/stroke). Don't assume a provider exists.
+- **Memoization:** The provider memoizes its value, so consumers don't re-render unless size or stroke actually change. Safe to use in tight loops / frequently-re-rendering trees.
+- **Composes down:** IconProvider nests — inner providers override outer ones. A `<Button size="lg"><IconProvider size="xs">...</IconProvider></Button>` overrides the button's icon sizing.
+
 ## Gotchas
 - Used internally by IconGroup and Button to propagate icon sizing to children
 - If no provider is present, `useIconContext()` returns `{}` (empty object) — consumers should fall back to defaults

package/docs/components/ui/icon-group.md

@@ -26,6 +26,15 @@
 </IconGroup>
 ```
 
+## Composability
+- **IconProvider wrapper + layout** — IconGroup is IconProvider plus a flex container. All child `<Icon>` elements auto-size via the provider. Don't pass size to nested Icons.
+- **IconGroup vs ButtonGroup-of-IconButtons:**
+  - IconGroup = static icon displays (legend rows, feature lists, decorative clusters). Not interactive.
+  - ButtonGroup of IconButtons = interactive toolbar where each icon is a button.
+  - If you want a formatting toolbar (interactive), use ButtonGroup or ToggleGroup, not IconGroup.
+- **Toolbar mode:** Set `role="toolbar"` + provide `label` to give the group a semantic role. Only then does `label` become `aria-label` on the container.
+- **Gap semantics:** tight=2px, default=4px, loose=8px — smaller values than ButtonGroup or Stack because icons are visually dense.
+
 ## Gotchas
 - Wraps children in an IconProvider — all child Icons inherit size/stroke from the group
 - `label` is only applied as `aria-label` when `role="toolbar"` is set

package/docs/components/ui/icon.md

@@ -30,6 +30,13 @@
 <Icon icon={IconPlus} state="success" />
 ```
 
+## Composability
+- **IconContext consumption** — Icon auto-reads `size` and `stroke` from the nearest IconProvider. Button, IconButton, IconGroup, Input (startSection/endSection), Badge, NumberInput, and more all wrap their children in IconProvider so nested Icons auto-size. Explicit props always override context.
+- **Use Tabler icon components** — the `icon` prop expects a ForwardRef SVG component (the shape Tabler React exports). Any icon lib following that shape works, but Tabler is the standard.
+- **Label for a11y:** Without `label`, Icon is `aria-hidden="true"` (decorative — appropriate inside labeled buttons). With `label`, renders `role="img"` + aria-label + `<title>` for standalone icons.
+- **State overrides animate:** When both are set, state wins. `state="loading"` renders a bare Spinner; success/error render animated glyphs via Framer Motion.
+- **Reduced motion:** All animations respect `prefers-reduced-motion` — animate props fall back to static render.
+
 ## Gotchas
 - Without `label`, the icon renders `aria-hidden="true"` (decorative)
 - With `label`, the icon renders `role="img"` with `aria-label` and a `<title>` element

package/docs/components/ui/input-otp.md

@@ -5,17 +5,32 @@
 - Category: ui
 
 ## Props
-    Standard input-otp props (maxLength, pattern, etc.)
+### InputOTP
+    maxLength: number (REQUIRED) — total number of slots
+    value: string (controlled value; defaults to empty string)
+    onChange: (value: string) => void
+    onComplete: (value: string) => void — fires when all slots filled
+    pattern: string | RegExp — restrict input (e.g. `REGEXP_ONLY_DIGITS`)
+    state: "default" | "error" (error adds red border; auto-inherits from FormField)
+    size: "sm" | "md" | "lg" (slot dimensions — propagates to InputOTPSlot via context)
+    disabled: boolean
+    containerClassName: string (on the outer group container — separate from inner input's className)
+
+### InputOTPSlot
+    index: number (REQUIRED, 0-based) — which position this slot renders
 
 ## Compound Components
-    InputOTP (root)
-      InputOTPGroup
-        InputOTPSlot (index: number, REQUIRED)
-      InputOTPSeparator
+    InputOTP (root — maxLength, value, onChange, size propagated via context)
+      InputOTPGroup (visual group of slots)
+        InputOTPSlot (index: number, REQUIRED — reads size from context)
+      InputOTPSeparator (visual separator, e.g. between two groups of 3)
+
+## Defaults
+    size="md", state="default"
 
 ## Example
 ```jsx
-<InputOTP maxLength={6}>
+<InputOTP maxLength={6} onComplete={verifyCode}>
   <InputOTPGroup>
     <InputOTPSlot index={0} />
     <InputOTPSlot index={1} />
@@ -30,8 +45,15 @@
 </InputOTP>
 ```
 
+## Composability
+- Size propagates from InputOTP → InputOTPSlot via `InputOTPSizeContext` — don't set size on individual slots.
+- Inside `<FormField>`: auto-inherits state, aria-describedby, aria-required from context. Explicit `state="error"` overrides.
+- Underlying library is `input-otp` (OTPInput) — all standard library props (pattern, inputMode, autoFocus, etc.) pass through.
+
 ## Gotchas
-- Each InputOTPSlot requires an `index` prop (0-based)
+- Each InputOTPSlot requires an `index` prop (0-based) matching its position
+- `onComplete` only fires when ALL slots are filled — use `onChange` for per-character reactivity
+- `containerClassName` (outer visual group) is distinct from `className` (the hidden input element itself)
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/input.md

@@ -32,6 +32,13 @@
 <Input endSection=".00" endSectionType="label" startSection={<Icon icon={IconCurrencyDollar} />} placeholder="0" />
 ```
 
+## Composability
+- **FormField auto-consumption:** Inside a `<FormField>`, Input auto-inherits `state`, `aria-describedby` (linked to FormHelperText), `aria-invalid` (when state="error"), `aria-required`. Explicit props on Input override context.
+- **IconProvider cascade:** Icons in `startSection` / `endSection` are auto-sized via IconProvider per the input's `size` (xs → sm icon, sm → sm icon, md → md icon, lg → md icon). Don't pass explicit size to nested `<Icon>`.
+- **Container-first architecture (v0.29.0+):** Border, background, focus ring all live on the wrapper div (accessed via `wrapperClassName`). The raw `<input>` inside is transparent. `className` goes to the input element; `wrapperClassName` goes to the wrapper.
+- **Section types:** Strings in startSection/endSection auto-render as `label` (tinted bg + border separator); React elements auto-render as `icon` (fixed-width centered cell). Override via `startSectionType` / `endSectionType`.
+- **Label pairing:** Always pair with `<Label htmlFor="x" />` + `<Input id="x" />` or wrap both in a `<label>` — FormField doesn't auto-wire the visual label to the input.
+
 ## Gotchas
 - HTML native "size" attribute is excluded — use CSS width instead
 - state="error" sets aria-invalid automatically