@devalok/shilp-sutra 0.37.0 → 0.38.0

package/docs/components/ui/banner.md

@@ -7,7 +7,6 @@
 ## Props
     color: "info" | "success" | "warning" | "error" | "neutral"
     actions: ReactNode (optional action slot for one or more buttons; wraps on narrow viewports)
-    action: ReactNode (DEPRECATED — use `actions` instead)
     onDismiss: () => void (optional, shows X button)
     children: ReactNode (message text)
 
@@ -21,12 +20,22 @@
 </Banner>
 ```
 
+## Composability
+- **Banner vs Alert vs Toast:** Banner is full-width, top-of-page / top-of-region announcements (maintenance, quota, trial-expiring). Alert is inline in-flow. Toast is transient floating notifications. Pick by where the message lives in the visual hierarchy.
+- **actions slot:** Pass one or more `<Button>` elements — the container flex-wraps on narrow viewports so actions drop below the message rather than squeezing horizontally.
+- **Role=alert** announces assertively. Same constraint as Alert — don't stack multiple Banners.
+- **Dismissal timing:** `onDismiss` fires AFTER the exit animation completes, not on click. Use it to remove the banner from state only after it's visually gone.
+- Works inside Shell layouts (TopBar / Sidebar / main content) — usually sits above main content, below the TopBar.
+
 ## Gotchas
 - Banner is full-width (spans container). Alert is inline.
 - Renders role="alert" automatically
 - `onDismiss` fires after the exit animation completes, not immediately on dismiss button click
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) deprecated singular `action` prop. Use `actions={[...]}` (plural).
+
 ### v0.20.0
 - **Added** `actions` prop (plural) for multiple action buttons with mobile-friendly flex-wrap
 - **Deprecated** `action` prop — use `actions` instead (both still work; `actions` takes priority)

package/docs/components/ui/breadcrumb.md

@@ -26,8 +26,16 @@
 </Breadcrumb>
 ```
 
+## Composability
+- **Compound structure only** — no context cascade, each part is standalone. The semantic shape (`<nav>` → `<ol>` → `<li>`) is what matters for a11y, not any internal state.
+- **BreadcrumbLink vs BreadcrumbPage:** Use BreadcrumbLink for everything except the current page; BreadcrumbPage for the current page (not clickable, renders without href, announced as "current page" via aria-current).
+- **Router integration:** Use `<BreadcrumbLink asChild><NextLink href="/x">...</NextLink></BreadcrumbLink>` (Radix Slot pattern).
+- **Truncation:** For long paths, use BreadcrumbEllipsis between the first and last items instead of showing all. Pair with a DropdownMenu (open the ellipsis to show hidden intermediate items) if you need to expose them.
+- **PageHeader (composed) auto-builds Breadcrumb** from its `breadcrumbs` prop — use that higher-level component for page-top breadcrumbs and save this component for inline or custom positioning.
+
 ## Gotchas
 - Use BreadcrumbPage for the current (non-clickable) page, BreadcrumbLink for navigable items
+- Don't wrap BreadcrumbPage in a link — it's the current location by definition
 
 ## Changes
 ### v0.18.0

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

@@ -5,24 +5,44 @@
 - Category: ui
 
 ## Props
-    variant: ButtonProps['variant'] (propagated to children)
+    variant: ButtonProps['variant'] (propagated to children via context)
     color: ButtonProps['color'] (propagated to children)
     size: ButtonProps['size'] (propagated to children)
-    orientation: "horizontal" | "vertical" (default: "horizontal")
+    weight: ButtonProps['weight'] (propagated to children)
+    shape: ButtonProps['shape'] (propagated to children)
+    disabled: boolean (propagates to all children)
+    orientation: "horizontal" | "vertical"
+    attached: boolean (true = buttons visually merge with shared borders; false = spaced apart via gap)
+    fullWidth: boolean (group stretches to parent width; children stretch equally)
 
 ## Defaults
-    orientation="horizontal"
+    orientation="horizontal", attached=true
 
 ## Example
 ```jsx
 <ButtonGroup variant="outline" size="sm">
   <Button>Bold</Button>
   <Button>Italic</Button>
+  <Button>Underline</Button>
+</ButtonGroup>
+
+{/* Spaced, not attached */}
+<ButtonGroup attached={false} variant="soft">
+  <Button>Save</Button>
+  <Button>Cancel</Button>
 </ButtonGroup>
 ```
 
+## Composability
+- Every Button child reads variant/color/size/weight/shape/disabled from ButtonGroup context. Explicit props on individual children override context.
+- **Position-aware border radius:** Child Buttons read their position in the group (first / middle / last) and apply appropriate corner radii inline. Works for both horizontal and vertical orientations.
+- **Focus z-index isolation:** The focused button rises above its siblings so the focus ring isn't clipped by adjacent borders.
+- **Tonal dividers:** For solid/soft/ghost variants without visible borders, ButtonGroup injects subtle divider elements between children.
+- **Works with SplitButton:** `<SplitButton>` inside a `<ButtonGroup>` inherits the same context and position rules.
+
 ## Gotchas
-- Children can override variant/size individually
+- Children can override variant/size individually — context is a default, not a lock
+- `attached={false}` disables the position-aware border radius (children use their default corners)
 
 ## Changes
 ### v0.33.0

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

@@ -10,6 +10,11 @@ Internal component that renders the processing animation overlay for Button. Con
 
 See `Button` docs for the public API.
 
+## Composability
+- **Internal only — do NOT import or use directly.** The Button component owns the lifecycle of this overlay.
+- Drives Button's `processing` prop rendering. If you're building a custom button and want similar marching-ants feedback, copy the SVG/animation pattern — don't reach into this component.
+- Listed here for reference so consumers grep'ing for "processing" find the behavior origin.
+
 ## Changes
 ### v0.29.0
 - **Added** Initial release — marching ants processing overlay (SVG dashed rect with animated stroke-dashoffset). Speed tiers: ambient (3s), working (2s), urgent (1s). Color maps to step-11 tokens for visibility on all variants.

package/docs/components/ui/button.md

@@ -34,6 +34,15 @@
 <Button variant="soft" color="warning" size="compact-sm" shape="pill">Overdue</Button>
 ```
 
+## Composability
+- **ButtonGroup context consumption:** When nested inside `<ButtonGroup>`, Button auto-inherits variant/color/size/weight/shape/disabled. Explicit props on the individual Button override. The context also drives position-aware border-radius (first/middle/last within an attached group).
+- **IconProvider cascade:** Icons in `startIcon`/`endIcon` auto-size via IconProvider per the button size (xs→sm, sm→sm, md→md, lg→md, icon-xs→xs, icon-lg→lg). Don't pass explicit `size` to `<Icon>` inside Button.
+- **asChild for router links:** `<Button asChild><Link href="/foo">...</Link></Button>` transfers Button's styling to the Link while preserving navigation semantics. Required for Next.js `<Link>` / react-router `<Link>`.
+- **onClickAsync state machine:** Overrides onClick. Auto-cycles `idle → loading (aria-busy, spinner) → success (checkmark) → idle` on resolve; `loading → error (X mark) → idle` on reject. Duration controlled by `asyncFeedbackDuration` (1500ms default). Auto-activates `processing='working'` during loading — marching-ants border keeps users visually aware.
+- **Processing vs loading:** `loading` is a short async state (shows spinner, blocks clicks). `processing` is a longer-running state (marching ants border, may or may not block clicks based on `processingDisabled`). Use onClickAsync for simple request cases; use processing explicitly for long-running background operations.
+- **DevalokGrain children:** Grain elements are auto-extracted and rendered as direct button children for absolute positioning — lets you layer grain texture on solid-variant buttons without breaking layout.
+- **Prefer `variant="soft"` over `variant="outline"` for secondary actions** (see Gotchas for details). This is a design-system-wide convention.
+
 ## Gotchas
 - **Prefer `variant="soft"` over `variant="outline"` for secondary actions.** Soft (tinted step-3 bg, step-11 text) is the Devalok-recommended default — it feels warmer and brand-consistent. Use `outline` only when soft's tint would disappear (on colored/surface-raised bg), in toolbar/icon-dense contexts, or when you need outline's stronger hierarchy next to a primary action.
 - DO NOT use variant="destructive" — use variant="solid" color="error"

package/docs/components/ui/card.md

@@ -6,18 +6,22 @@
 
 ## Props
     variant: "default" | "elevated" | "outline" | "flat"
+    color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" (border accent color)
+    size: "sm" | "md" | "lg" (padding — propagated to CardHeader/CardContent/CardFooter via context)
     interactive: boolean (enables hover shadow lift + pointer cursor)
+    accent: "left" | "top" | "right" | "bottom" (render a colored accent bar on the specified edge)
+    accentColor: "default" | "accent" | "error" | "success" | "warning" | "info" (color of the accent bar; default maps to accent-9)
 
 ## Compound Components
     Card (root)
-      CardHeader
+      CardHeader      ← inherits size from Card context
         CardTitle
         CardDescription
-      CardContent
-      CardFooter
+      CardContent     ← inherits size from Card context
+      CardFooter      ← inherits size from Card context
 
 ## Defaults
-    variant="default"
+    variant="default", color="default", size="md"
 
 ## Example
 ```jsx
@@ -30,8 +34,16 @@
 </Card>
 ```
 
+## Composability
+- **Size cascades through context** — Card's `size` prop sets padding on CardHeader, CardContent, and CardFooter via `CardSizeContext`. Don't set padding classes on sub-components directly; override via `className` if needed.
+- **Not a compound state machine** — Card, CardHeader, CardTitle, etc. are purely structural. No open/close state.
+- **Accent bar is independent:** The `accent` / `accentColor` props render a decorative colored edge bar (absolutely positioned, `aria-hidden`). Works alongside `color` (which tints the border) — the two can stack for layered emphasis.
+- **Interactive cards:** Set `interactive={true}` + `onClick` for clickable cards (entire surface becomes the button). Add `aria-label` on the Card root when there's no visible heading. For complex multi-action cards, prefer standard Card with explicit buttons inside.
+- **ContentCard (composed)** is a higher-level wrapper with built-in header/footer slots and title/actions — use it for list-row-style cards; use Card directly for custom layouts.
+
 ## Gotchas
 - Use `interactive` prop for clickable cards — adds hover lift and pointer cursor
+- Don't override CardHeader/CardContent/CardFooter padding via className if you want the size cascade to work — set size on Card instead
 
 ## Changes
 ### v0.31.0

package/docs/components/ui/charts.md

@@ -28,9 +28,18 @@ import { BarChart } from '@devalok/shilp-sutra/ui/charts'
 <BarChart data={salesData} />
 ```
 
+## Composability
+- **ChartContainer wraps all chart primitives** — provides responsive sizing (fills parent width, configurable aspect ratio) and a consistent background/padding. Always render charts inside a ChartContainer unless you're building a custom container.
+- **Legend is a sibling, not a child** — render `<Legend items={...} />` next to your chart (above/below), not nested. Use `onHover` / `onClick` handlers in Legend + chart to sync hover highlights.
+- **Data shape is chart-specific** — BarChart wants `[{ label, value }]`, LineChart wants `[{ x, y, series }]`, etc. Each chart's props doc spells out the shape; don't assume cross-chart compatibility.
+- **Sparkline is the only chart safe to use inline** — it's a minimal 1-line SVG, no axes, no legend. Use it inside StatCard, tables, tight cells. For anything larger, reach for the full chart types.
+- **Entrance animations** — all charts use Framer Motion spring-based entry. Animations respect `prefers-reduced-motion`.
+- **Accessibility:** Charts render role="img" with aria-label from the chart title. For dense data, provide a hidden accessible table fallback manually (WCAG requirement for complex charts).
+
 ## Gotchas
 - Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/charts`, NOT the `ui` barrel
 - Requires D3 as an optional peer dependency
+- Chart components do NOT auto-generate accessible data tables — add one manually for WCAG compliance on complex charts
 
 ## Changes
 ### v0.18.0

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