@devalok/shilp-sutra 0.37.0 → 0.38.0

package/docs/components/composed/form-section.md

@@ -26,6 +26,12 @@
 </FormSection>
 ```
 
+## Composability
+- **Visual grouping of related FormFields.** Wraps its children with a title + description + horizontal rule separator. No state, no context.
+- **collapsible mode** wraps content in a Collapsible — useful for "Advanced settings" or optional form sections. `defaultOpen={false}` for initially-closed.
+- **Pairs with FormField:** Each form control inside should be a FormField for consistent label + helper text + validation. FormSection doesn't auto-wrap; you still structure each field yourself.
+- **Not a page-level header** — for a full form's main heading use PageHeader. FormSection is mid-form, between field groups.
+
 ## Gotchas
 - `defaultOpen` only applies when `collapsible={true}` — otherwise the section is always open
 - Renders a horizontal rule between the header and content automatically

package/docs/components/composed/global-loading.md

@@ -15,6 +15,12 @@
 <GlobalLoading isLoading={isNavigating} />
 ```
 
+## Composability
+- **Thin top-of-viewport progress bar** — for route-level navigation indicators (NProgress-style). Fixed at the top; z-toast layer.
+- **Wire to router events:** Pair with Next.js `useRouter` + navigation events, or react-router's `useNavigation`, or a custom global loading state in Redux/Zustand. Set `isLoading={true}` during transit, `false` when landed.
+- **Not for in-page loading** — use Spinner, Skeleton, or LoadingSkeleton for component-level loading states. GlobalLoading is strictly for cross-route / full-page transitions.
+- **Auto-unmounts when isLoading=false** — no need to manage visibility via classes or conditional rendering.
+
 ## Gotchas
 - Fixed-position bar at top of viewport (z-toast layer)
 - Renders nothing when `isLoading` is false

package/docs/components/composed/inline-edit.md

@@ -25,6 +25,14 @@
 />
 ```
 
+## Composability
+- **contentEditable-based** — the text IS the editor (Notion / Linear / Figma layer-name pattern). No separate input field appears.
+- **Keyboard contract:** Click to focus (auto-selects text, like Finder rename). Type to edit. Enter saves, Escape reverts. Paste strips rich content.
+- **Async save:** `onSave` can return a Promise — InlineEdit shows a spinner and disables editing while pending. On rejection, text reverts to the original value automatically.
+- **Accessibility:** Accepts `aria-label` and `aria-labelledby` (forwarded to the role="textbox" span) — required when the text isn't self-descriptive. Falls back to `placeholder` as label when neither is provided.
+- **Not inside FormField** — InlineEdit is for in-place editing of existing content (task title, project name); use regular FormField + Input for traditional forms.
+- **textClassName for typography control:** Pass `"text-ds-lg font-semibold"` to make it look like a heading without changing the underlying element.
+
 ## Gotchas
 - Uses contentEditable — the text IS the editor. No input field appears.
 - Click to focus → cursor appears in text. Type to edit. Enter saves. Escape reverts.

package/docs/components/composed/loading-skeleton.md

@@ -39,6 +39,13 @@ Exports: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton
 <ListSkeleton rows={10} showAvatar={false} />
 ```
 
+## Composability
+- **Pre-composed skeleton layouts** — CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton. Each mimics the shape of a common DS layout so users see meaningful loading placeholders.
+- **Built on ui/Skeleton** — for custom loading layouts, use Skeleton directly (rectangle/circle/text variants). These composed versions are just opinionated shape combinations.
+- **Server-safe** — use during SSR for initial-paint skeletons in Next.js app router (while server data streams in).
+- **Pairs with conditional rendering:** `{isLoading ? <TableSkeleton rows={8} /> : <DataTable data={rows} />}`.
+- **PageSkeletons (separate file)** provides full-page placeholders (DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton) — use those for route-level loading states.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - These are pre-composed skeleton layouts — for individual skeleton shapes, use the `Skeleton` UI component

package/docs/components/composed/markdown-viewer.md

@@ -20,6 +20,15 @@
 <MarkdownViewer content={trustedHtml} allowHtml />
 ```
 
+## Composability
+- **Read-only markdown renderer.** For editing, use RichTextEditor (TipTap-based). MarkdownViewer is strictly for display.
+- **Built on react-markdown + remark-gfm** — GFM tables, strikethrough, task lists supported out of the box.
+- **Syntax highlighting is lazy:** Code blocks with a language fence (```ts, ```python) lazy-load react-syntax-highlighter. First render shows a plain `<pre>` fallback. Don't pre-import.
+- **Security posture:** Raw HTML is stripped by default — `allowHtml={true}` must be explicit, and ONLY for trusted content (XSS vector otherwise).
+- **Links open external by default** (`target="_blank"` + `rel="noopener noreferrer"`). Override via `linkTarget`.
+- **compact mode** for inline use (comments, message bubbles). Default spacing is for article-body content.
+- **Pairs with Chat's Message.Body** — render markdown from user messages safely. Always keep `allowHtml={false}` for user-generated content.
+
 ## Gotchas
 - Code blocks with a language fence are syntax-highlighted via `react-syntax-highlighter` (lazy-loaded) — the first render shows a plain `<pre>` fallback
 - GFM (tables, strikethrough, task lists) is supported via `remark-gfm`

package/docs/components/composed/master-detail.md

@@ -42,6 +42,13 @@ MasterDetail (root), MasterDetail.List, MasterDetail.Detail, MasterDetail.ListIt
 </MasterDetail>
 ```
 
+## Composability
+- **Responsive list+detail layout.** Desktop: side-by-side panels. Mobile (below `breakpoint`): stacked, mutually exclusive (list OR detail, controlled by `selected`).
+- **Compound structure:** `MasterDetail.List` contains `MasterDetail.ListItem[]` (interactive). `MasterDetail.Detail` holds the currently-selected view.
+- **onBack is required for mobile** — renders the back button in Detail pane. Omitting it leaves users stranded once they drill into an item on mobile.
+- **SSR gotcha:** Uses `window.matchMedia` — initial SSR render picks desktop mode; hydrates to mobile mode if viewport is narrow. If that causes layout shift, consider rendering this only after mount (via `useState(false)` + `useEffect`).
+- **Pairs with EmptyState** — render EmptyState inside Detail when `selected === null` on desktop ("Pick an item to get started").
+
 ## Gotchas
 - On mobile (below breakpoint), List and Detail are mutually exclusive — selecting an item hides the list
 - The `onBack` callback is required for the mobile back button to appear in the Detail pane

package/docs/components/composed/member-picker.md

@@ -22,6 +22,13 @@
 </MemberPicker>
 ```
 
+## Composability
+- **Trigger + Popover + search list.** Pass any button/element as `children` to act as the trigger. Typical pairing: outline Button that says "Assign" or an IconButton with avatar overflow.
+- **Single vs multi:** `multiple={true}` allows multiple selections; `false` (default) replaces the previous selection. `selectedIds` is always an array in both modes — consumer controls semantics.
+- **onSelect with a single ID:** Fires once per click with one memberId. Toggle logic in multi mode is consumer responsibility (derive the new array from the click).
+- **Avatar display:** Uses ui/Avatar internally — supply `avatar` URL in the member object, fallback to initials from `name`.
+- **For general-purpose multi-select** (non-members), use MultiSelectPopover which has the same popover+search pattern without member-specific avatar rendering.
+
 ## Gotchas
 - `children` is used as the trigger element (e.g., a Button)
 - `onSelect` is called with a single `memberId` — toggle logic is up to the consumer

package/docs/components/composed/multi-select-popover.md

@@ -47,6 +47,17 @@
 </MultiSelectPopover>
 ```
 
+## Composability
+- **Generalized multi-select popover** — picks from a fixed list (items) or grouped list (groups), with search, async search, and custom rendering.
+- **Items vs groups (mutually exclusive):** Pass `items` for flat lists, `groups` for sectioned lists. Don't pass both.
+- **Async search via onSearch:** When provided, local filtering is disabled — the callback owns filtering and returns a new list. `searchDebounce` (default 300ms) throttles calls.
+- **renderItem escape hatch:** Pass `(item, selected) => ReactNode` for custom item rendering (avatar + multi-line descriptions, etc.). Built-in default renders image + label + description.
+- **maxSelections behavior:** At the limit, clicking a new item REPLACES the oldest selection (FIFO). `maxSelections={1}` effectively acts as single-select.
+- **MultiSelectPopover vs Combobox vs MemberPicker:**
+  - Combobox = form-field multi-select (typeahead + selection in place)
+  - MultiSelectPopover = button-triggered popup for bulk selection (good for "Assign to" / "Add tags" scenarios)
+  - MemberPicker = MultiSelectPopover specialized for team-member UI
+
 ## Gotchas
 - Supply either `items` (flat) or `groups` (sectioned), not both
 - When `onSearch` is provided, local filtering is disabled — the callback must return results

package/docs/components/composed/page-header.md

@@ -28,6 +28,13 @@
 />
 ```
 
+## Composability
+- **Server-safe page-top header** with title + subtitle + breadcrumbs + actions slot. Renders Breadcrumb internally from the `breadcrumbs` array.
+- **Auto-derived title:** If `title` is omitted, the last breadcrumb's `label` becomes the h1. Saves duplication when the page title matches the breadcrumb leaf.
+- **Breadcrumb contract:** Last item should NOT have an `href` (it's the current page — renders as BreadcrumbPage, not a link). Items with `href` render as BreadcrumbLink.
+- **actions slot:** Typically one to three buttons (Save, Cancel, More). For larger action groups, use ButtonGroup or a toolbar.
+- **Not for tabs / sub-navigation** — pair with Tabs rendered below PageHeader for that.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - If `title` is omitted, the last breadcrumb's `label` is used as the page title

package/docs/components/composed/page-skeletons.md

@@ -19,6 +19,16 @@ Exports: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton
 <TaskDetailSkeleton />
 ```
 
+## Composability
+- **Full-page skeleton layouts** for route-level loading states. Each mimics a common page shape (dashboard tiles, project list with filters, task detail with sidebar).
+- **Server-safe** — use in Next.js app router `loading.tsx` files for instant route-transition feedback while data streams.
+- **Built on LoadingSkeleton + ui/Skeleton** — these just assemble the pre-built regional skeletons into page-shaped layouts.
+- **When to use which skeleton tier:**
+  - `<Skeleton>` (ui) — single shape for a single element
+  - `<CardSkeleton>` / `<TableSkeleton>` (LoadingSkeleton) — individual region shape
+  - `<DashboardSkeleton>` / etc. (PageSkeletons) — full page placeholder
+- **Fixed layout structure** — the className prop adjusts the outer container, but internal layout isn't customizable. For custom page skeletons, compose LoadingSkeleton pieces yourself.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - These are full-page skeleton layouts — for smaller skeleton sections, use LoadingSkeleton components

package/docs/components/composed/priority-indicator.md

@@ -19,6 +19,13 @@ Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'u
 <PriorityIndicator priority="low" display="compact" />
 ```
 
+## Composability
+- **Server-safe priority label** — icon + color + text for task / issue priority.
+- **Composes inside list rows, DataTable cells, Card headers, task panels** — anywhere a priority flag fits.
+- **display="compact"** shows only the icon (with priority text as title attribute for tooltip). Use in tight cells; use `display="full"` (default) in free space.
+- **Case-insensitive priority** — accepts both UPPERCASE (LOW/MEDIUM/HIGH/URGENT) and lowercase. Designed to match both backend conventions without manual coercion.
+- Color semantics: LOW=success, MEDIUM=warning, HIGH=error, URGENT=error with bolder icon.
+
 ## Gotchas
 - Case-insensitive — "low" and "LOW" both work
 - Server-safe: can be imported directly in Next.js Server Components

package/docs/components/composed/rich-chat-input.md

@@ -67,6 +67,18 @@ SlashCommandGroup: { label: string; commands: SlashCommand[] }
 />
 ```
 
+## Composability
+- **Chat-specific TipTap editor** — purpose-built for AI + human messaging. Built on RichTextEditor primitives but pre-configured for the chat UX (auto-resize, Enter-to-send, inline toolbar).
+- **Variant drives the UX envelope:**
+  - `compact` — 2-3 line inline (chat bubble composer)
+  - `expanded` — 5+ lines with always-visible toolbar (AI prompt input)
+  - `minimal` — single line, toolbar on focus (reply composer, quick comment)
+- **Toolbar is opt-in per feature:** Icons only appear when their corresponding handler/prop is set. `onFileUpload` → attach button appears. `slashCommands` → slash button appears. `mentions` or `onMentionSearch` → @ button appears.
+- **Composes with Message from ui/chat:** RichChatInput is the composer; Message is the read-only render of the message after send. Use them together for a complete chat UX (RichChatInput at the bottom, MessageList above).
+- **TipTap is bundled** — no need to install `@tiptap/*` directly.
+- **For general rich text editing** (not chat — long-form docs, notes), use RichTextEditor instead.
+- **isStreaming + onCancel** — when the receiving side is streaming a response, show a stop button in place of send. Standard AI chat pattern.
+
 ## Gotchas
 - Tiptap is bundled — no need to install `@tiptap/*` packages separately
 - Enter sends by default; use `enterBehavior="newline"` for long-form composition (Cmd/Ctrl+Enter always sends)

package/docs/components/composed/rich-text-editor.md

@@ -47,6 +47,15 @@ MentionItem: { id: string; label: string; avatar?: string }
 <RichTextViewer content={savedHtml} />
 ```
 
+## Composability
+- **Two exports — editor + viewer.** RichTextEditor for composition; RichTextViewer for read-only rendering of saved HTML. Both share the same prose styling so round-trip display matches the editor.
+- **TipTap v3 bundled** — no `@tiptap/*` install needed. Consumers can't mix in arbitrary TipTap extensions without forking.
+- **Toolbar whitelist via `toolbar` prop:** Pass an array of ToolbarItem names to show only those buttons. Omit to show all. Dividers auto-collapse between empty groups.
+- **Image upload:** Without `onImageUpload`, pasted/dropped images are inlined as base64 (HTML bloats fast). Provide the handler to upload and return a URL.
+- **Mentions:** Static `mentions` array OR async `onMentionSearch` (which takes precedence). The viewer always renders mentions correctly from saved HTML — no mention props needed on the viewer side.
+- **For chat composition specifically** (AI + team chat with streaming / slash commands), use RichChatInput — it's built on the same foundation but pre-configured for chat UX.
+- **Pairs with MarkdownViewer** — many teams use RichTextEditor for compose (WYSIWYG), but render saved content as markdown for simpler serialization. Convert HTML ↔ markdown at the storage boundary.
+
 ## Gotchas
 - Tiptap is bundled — no need to install `@tiptap/*` packages separately
 - Emoji picker requires `@emoji-mart/react` + `@emoji-mart/data` peers

package/docs/components/composed/schedule-view.md

@@ -29,6 +29,14 @@ Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
 />
 ```
 
+## Composability
+- **Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.
+- **Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.
+- **Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).
+- **Color vocabulary matches the DS** — `primary/success/warning/error/info/neutral`. Map your event types to these at the data layer.
+- **endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.
+- **Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`.
+
 ## Gotchas
 - `endHour` is exclusive — `endHour=18` means the last visible slot starts at 17:30 (with default 30min slots)
 - `onSlotClick` fires when clicking an empty time slot — useful for creating new events

package/docs/components/composed/simple-tooltip.md

@@ -21,6 +21,13 @@
 </SimpleTooltip>
 ```
 
+## Composability
+- **One-liner Tooltip** — wraps TooltipProvider + Tooltip + TooltipTrigger + TooltipContent so consumers don't have to manually compose them for a simple label.
+- **When to use:** 90% of tooltip use cases (icon-only button labels, abbreviated text expansions, secondary info). Use the ui/Tooltip compound for advanced cases (controlled open, nested triggers, custom animations).
+- **Auto-provides its own TooltipProvider** — safe to drop anywhere. You can still wrap a broader TooltipProvider at layout level for shared `delayDuration`; SimpleTooltip respects it if present.
+- **Content must be inert** — same rule as ui/Tooltip. For interactive popped content, use Popover or HoverCard.
+- **Pairs with IconButton** — the canonical pattern for labeled icon buttons.
+
 ## Gotchas
 - Wraps the full Tooltip compound (Provider + Tooltip + Trigger + Content) into one component — no need for TooltipProvider
 - Unlike the low-level Tooltip, SimpleTooltip does not require wrapping in a TooltipProvider

package/docs/components/composed/status-badge.md

@@ -28,6 +28,16 @@ Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe
 <StatusBadge status="active" onClick={() => openStatusPicker()} />
 ```
 
+## Composability
+- **Semantic pill for workflow status.** Built on ui/Badge but with opinionated status → color mapping (active=success, pending=warning, rejected=error, etc.).
+- **status vs color discriminated union:** Pass either `status` (auto-mapped color) or `color` (explicit). Don't pass both — `color` wins if you do.
+- **Interactive mode:** Passing `onClick` renders as a `<button>` with a trailing chevron — common pattern for opening a status picker dropdown. Pair with a Popover or DropdownMenu for the status selector.
+- **Pairs with DataTable, Card headers, activity feeds** — anywhere an inline status pill fits. Use `size="sm"` for dense rows.
+- **StatusBadge vs ui/Badge vs StatusDot:**
+  - StatusBadge = workflow status pill with built-in status semantics
+  - ui/Badge = generic badge with full color/variant/shape control
+  - StatusDot = tiny presence indicator (no label pill)
+
 ## Gotchas
 - When `color` is set, it takes priority over `status` for styling
 - Props use a discriminated union — pass either `status` or `color`, not both

package/docs/components/shell/app-command-palette.md

@@ -31,6 +31,14 @@ AppCommandPaletteUser: { name: string, role?: string }
 />
 ```
 
+## Composability
+- **Shell-level wrapper around composed/CommandPalette** — adds opinionated app conventions: user-aware admin command groups, search result integration, navigation dispatch.
+- **Required setup:** Place inside `<CommandRegistryProvider>` (which owns the list of page items). Typically at app root next to TopBar.
+- **Router integration via onNavigate:** Pass `(path) => router.push(path)` (Next.js) or equivalent for your framework. All page command clicks funnel through this callback.
+- **Server-search integration:** Pass `onSearch` + `searchResults` + `onSearchResultSelect` for async search (API calls). `isSearching` drives a loading state. When these props are omitted, AppCommandPalette falls back to local filtering of registered pages.
+- **Admin gating:** `isAdmin=true` surfaces `adminPages` from CommandRegistry. Takes precedence over `user.role`-based detection so you can force admin mode during testing / impersonation.
+- **For scoped, non-app-wide palettes** (per-page command trees, custom popups), use composed/CommandPalette directly without the Registry layer.
+
 ## Gotchas
 - Uses CommandRegistry context for page navigation items (see CommandRegistryProvider)
 - `isAdmin` takes precedence over `user.role` for showing admin command groups

package/docs/components/shell/bottom-navbar.md

@@ -28,6 +28,18 @@ BottomNavbarUser: { name: string, role?: string }
 />
 ```
 
+## Composability
+- **Mobile-only bottom nav** — fixed to bottom of viewport. Desktop should use AppSidebar instead.
+- **Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render AppSidebar (desktop) or BottomNavbar (mobile). Example:
+  ```jsx
+  const isMobile = useIsMobile()
+  return isMobile ? <BottomNavbar ... /> : <AppSidebar ... />
+  ```
+- **Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a "More" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.
+- **Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.
+- **Badge numbers** cap at 99+ (same as BadgeIndicator pattern).
+- **Not for desktop:** The viewport-fixed positioning + touch-optimized sizing don't translate well to desktop. Hide behind `md:hidden`.
+
 ## Gotchas
 - Designed for mobile viewports — fixed to bottom of screen
 - Max 4 `primaryItems` recommended; overflow goes in `moreItems` shown in a "More" sheet

package/docs/components/shell/command-registry.md

@@ -38,6 +38,13 @@ CommandPageItem: { id: string, label: string, icon: ReactNode, path: string, key
 </CommandRegistryProvider>
 ```
 
+## Composability
+- **Context provider for AppCommandPalette.** Registers page-level navigation items that the command palette surfaces as commands.
+- **Place at app root** — wrap both AppCommandPalette and the rest of the app inside `<CommandRegistryProvider>`. Positioning matters: any AppCommandPalette outside the provider gets `useCommandRegistry() === null` and falls back to minimal functionality.
+- **Separation of pages vs adminPages** — the palette filters based on user role / `isAdmin` flag. Keep admin-only routes in the adminPages array to avoid leaking them to regular users.
+- **useCommandRegistry()** is the consumer hook — returns the full registry or null. Use in your own command-aware components (e.g. a Spotlight-style keyboard-search embed elsewhere in the app).
+- **Works with LinkProvider** — CommandPaletteItems navigate via `onNavigate` prop on AppCommandPalette, which routes to your framework's Link component.
+
 ## Gotchas
 - Provides the command registry context consumed by AppCommandPalette
 - Place at app root, wrapping both AppCommandPalette and the rest of the app

package/docs/components/shell/link-context.md

@@ -28,6 +28,21 @@ import Link from 'next/link'
 </LinkProvider>
 ```
 
+## Composability
+- **The framework router bridge for all shell components.** Without LinkProvider, AppSidebar / BottomNavbar / TopBar.UserMenu / AppCommandPalette render plain `<a>` tags — that means full page reloads instead of client-side navigation.
+- **Required setup:**
+  ```tsx
+  // Next.js
+  import Link from 'next/link'
+  <LinkProvider component={Link}>
+    <App />
+  </LinkProvider>
+  ```
+- **Place at app root** — above every shell component that renders nav links.
+- **component must be forwardRef** (Next.js Link, Remix Link, react-router Link all qualify). Custom components need to forward ref + forward className + forward all anchor props.
+- **Consumer components use `useLink()`** — returns the registered component or falls back to plain `<a>`. Your own components can consume this hook to integrate with the same router abstraction.
+- **ui-category components don't consume LinkProvider** — they use `asChild` for router integration (e.g. `<Button asChild><NextLink ...>...</NextLink></Button>`). LinkProvider is shell-specific because shell components embed link arrays (can't use asChild per-item without breaking the data-driven API).
+
 ## Gotchas
 - Without LinkProvider, shell components render plain `<a>` tags (full page reloads)
 - Place at app root, wrapping all shell components that render navigation links

package/docs/components/shell/notification-center.md

@@ -44,6 +44,16 @@ NotificationAction: { label: string, variant?: 'primary' | 'default' | 'danger',
 />
 ```
 
+## Composability
+- **Bell + Popover + notification list** — renders the bell button with unread count badge and a popover list on click.
+- **Typical placement:** Inside `<TopBar.Right>` — common pattern is `<TopBar.IconButton>` for utility actions PLUS `<NotificationCenter>` for the bell.
+- **No hardcoded routes** — `getNotificationRoute` is the consumer's routing decision. Return the correct path per notification type (task → `/tasks/:id`, comment → `/threads/:id`, etc.) or null for non-routable notifications.
+- **onNavigate** fires when a notification with a route is clicked — wire to your router's push/navigate call.
+- **Pagination:** Pass `hasMore` + `onFetchMore` for infinite-scroll of older notifications.
+- **emptySlot + footerSlot + headerActions** are content slots for customization — keep the bell+popover shell, swap the inside.
+- **Pairs with NotificationPreferences** (separate page component) for letting users configure which notification tiers/channels they want to receive.
+- **onDismiss** is optional — when provided, per-notification X buttons appear. Otherwise mark-as-read is the only dismissal mechanism.
+
 ## Gotchas
 - Typically rendered inside TopBar's `notificationSlot` prop
 - `getNotificationRoute` must be provided for clickable notifications — no hardcoded routes

package/docs/components/shell/notification-preferences.md

@@ -32,6 +32,13 @@ NotificationProject: { id: string, title: string }
 />
 ```
 
+## Composability
+- **Full-page preferences UI** — typically rendered on a settings page (`/settings/notifications`). Not an overlay; not a dropdown.
+- **Per-project preferences** — each preference is tied to a project + channel + tier. Users can mute/unmute and adjust tier (INFO / IMPORTANT / CRITICAL threshold) per project-channel combo.
+- **All callback props support Promise<void>** — integrate with server actions / fetch calls without manual loading state management.
+- **Pairs with NotificationCenter** — NotificationCenter shows notifications in real time (driven by these preferences); NotificationPreferences lets users tune the rules.
+- **Data ownership is consumer-side** — you pass `preferences` + `projects`; NotificationPreferences renders. No built-in persistence or sync.
+
 ## Gotchas
 - Manages per-project notification preferences (channel, tier, mute)
 - All callback props support async (Promise<void>) for server-side operations

package/docs/components/shell/sidebar.md

@@ -48,6 +48,17 @@ SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?:
 />
 ```
 
+## Composability
+- **Opinionated app sidebar** — data-driven via `navGroups`, with user profile header, navigation groups (with optional labels + group actions), and a configurable footer (links + version + optional promo banner).
+- **Required setup (three providers):**
+  - `SidebarProvider` (from ui/sidebar) — owns expanded/collapsed state + cookie persistence
+  - `LinkProvider` — framework router integration for nav item links
+  - `CommandRegistryProvider` (if pairing with AppCommandPalette) — registers the same navGroups so keyboard search finds them
+- **renderItem escape hatch:** Custom per-item rendering (e.g. custom icons per item type, status decorations, hover previews). Return `null` to fall back to default.
+- **Nested navigation:** NavItem's `children: NavSubItem[]` renders a collapsible subsection. Auto-opens if a child matches the current path.
+- **Footer as slot:** `footer` can include links, version info, a ReactNode slot (e.g. theme toggle), and a dismissable promo banner — structure it once, compose.
+- **Pairs with TopBar + BottomNavbar:** Desktop layout = AppSidebar + TopBar. Mobile layout = hide AppSidebar, show BottomNavbar.
+
 ## Gotchas
 - Must be wrapped in SidebarProvider (from ui/sidebar)
 - Requires LinkProvider for framework-specific link components

package/docs/components/shell/top-bar.md

@@ -111,6 +111,17 @@ UserMenuItem fields:
 </TopBar>
 ```
 
+## Composability
+- **Composition-based, NOT data-driven.** Use dot-notation subcomponents (`TopBar.Left`, `TopBar.Center`, `TopBar.Right`, `TopBar.Section`, `TopBar.IconButton`, `TopBar.Title`, `TopBar.UserMenu`) to assemble. No "props config" — explicit JSX.
+- **Two-zone vs three-zone layout** — adding `TopBar.Center` flips the root from `flex` to CSS grid (`1fr auto 1fr`) for true centering. Standard apps are two-zone (Left + Right); dashboards with prominent search are three-zone.
+- **Required providers:**
+  - `SidebarProvider` — for SidebarTrigger inside `TopBar.Left` to work
+  - `LinkProvider` — for TopBar.UserMenu's menu items that use `href`
+- **NotificationCenter lives inside TopBar.Right** — it's a complete bell+popover component. Drop it in a TopBar.Section next to other icon buttons.
+- **UserMenu is composable:** `userMenuItems` inserts custom items between the built-in Profile and the color-mode toggle. Each item can navigate (href), run an action (onClick), or show a separator/badge/color decoration.
+- **Responsive hiding:** Actions that shouldn't appear on mobile use `className="hidden md:flex"` on the IconButton — the component doesn't enforce mobile hiding; that's layout responsibility.
+- **Pairs with AppSidebar** — desktop app shell is typically `<TopBar>` + `<AppSidebar>` + main content region.
+
 ## Gotchas
 - Without `TopBar.Center`, layout is flex (two-zone). With it, layout switches to CSS grid `1fr auto 1fr` for true centering.
 - `TopBar.IconButton` renders any number of action buttons — no artificial limit. Use responsive hiding (`className="hidden md:flex"`) for mobile.

package/docs/components/ui/accordion.md

@@ -30,9 +30,19 @@
 </Accordion>
 ```
 
+## Composability
+- Built on Radix Accordion — accepts `value`/`defaultValue`/`onValueChange` matching the `type` discriminated union.
+- **`type="single"`** — value is a string (which item is open). Only one item open at a time. Pair with `collapsible` to allow closing the current item by re-clicking it.
+- **`type="multiple"`** — value is a string[] (which items are open). Multiple can be open at once.
+- **AccordionTrigger chevron:** Inline SVG that auto-rotates via the `data-state` attribute Radix sets (`open` / `closed`). The `chevronPosition` prop controls render order inside the trigger (left / right) — rotation still works from either position.
+- **AccordionContent:** Uses Radix CSS custom properties (`--radix-accordion-content-height`) for open/close height animation. Framer Motion handles the fade. Don't wrap AccordionContent children in additional motion components — doubles the animation.
+- **Inline, not portalled** — parent `overflow: hidden` WILL clip an open accordion. Keep accordions out of tight overflow contexts or use `overflow-visible` on the container.
+
 ## Gotchas
 - type is REQUIRED — omitting it causes runtime error
 - collapsible only works with type="single"
+- Each AccordionItem needs a unique `value` — duplicates silently break toggling
+- Don't put focusable elements inside AccordionTrigger — the trigger IS the focusable button, nested focusables break screen reader navigation
 
 ## Changes
 ### v0.29.0

package/docs/components/ui/alert-dialog.md

@@ -42,8 +42,17 @@
 </AlertDialog>
 ```
 
+## Composability
+- Built on Radix AlertDialog — like Dialog but **non-dismissible** by clicking outside or pressing Escape. The user must choose Cancel or Action.
+- Same portal + trigger + asChild pattern as Dialog.
+- `AlertDialogAction` and `AlertDialogCancel` are semantically distinct from generic buttons: they auto-close the dialog on click. Use them even if you wrap them around a styled Button via `asChild` so the close behavior stays wired.
+- **Focus management:** Initial focus lands on `AlertDialogCancel` (the safe default) — destructive confirmation is always one tab away.
+- Use AlertDialog for destructive / irreversible actions; use Dialog for everything else.
+
 ## Gotchas
-- AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button
+- AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button with `asChild`
+- Do NOT add a close-on-outside-click handler — the non-dismissible behavior is the whole point
+- AlertDialogCancel receives initial focus; don't flip the convention
 
 ## Changes
 ### v0.19.1

package/docs/components/ui/alert.md

@@ -5,14 +5,15 @@
 - Category: ui
 
 ## Props
-    variant: "subtle" | "filled" | "outline"
+    variant: "subtle" | "solid" | "outline"
     color: "info" | "success" | "warning" | "error" | "neutral"
+    size: "sm" | "md" | "lg"
     title: string (optional)
     onDismiss: () => void (optional, shows X button when provided)
     children: ReactNode (body text)
 
 ## Defaults
-    variant="subtle", color="info"
+    variant="subtle", color="info", size="md"
 
 ## Example
 ```jsx
@@ -21,6 +22,13 @@
 </Alert>
 ```
 
+## Composability
+- **Flat, not compound** — unlike Dialog/Card, there's no `<AlertTitle>` / `<AlertDescription>`. Use the `title` prop for the heading and `children` for the body text. This simplifies the API and prevents composition traps (missing title, out-of-order header parts).
+- **Auto-icon by color:** Icon is selected automatically from color (info→circle, success→check, warning→triangle, error→alert). Pass a custom `icon` prop to override.
+- **Role=alert:** Announces assertively to screen readers. Don't stack multiple Alerts in a row — the last one wins.
+- **Dismissal pattern:** Pass `onDismiss` for user-dismissable alerts; the library tracks the exit animation before calling back. For persistent alerts (system state), omit `onDismiss`.
+- **Not for transient messages** — use Toast for transient/time-limited notifications and Banner for page-level announcements. Alert is inline, in-flow, block-level.
+
 ## Gotchas
 - NOT a compound component — use title prop, NOT <AlertTitle>
 - DO NOT use variant="destructive" — use color="error"
@@ -28,6 +36,9 @@
 - Icon is auto-selected by color (info=circle, success=check, warning=triangle, error=alert)
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) `variant="filled"` deprecated alias. Use `variant="solid"`.
+
 ### v0.31.0
 - **Added** `size` prop: `sm | md | lg`. Default `md` (non-breaking).
 

package/docs/components/ui/aspect-ratio.md

@@ -17,8 +17,15 @@
 </AspectRatio>
 ```
 
+## Composability
+- Radix AspectRatio primitive — pure layout wrapper, no context, no cascade.
+- **Child fill pattern:** Its child is absolutely positioned to fill. Pair with `object-cover` / `object-contain` on `<img>`/`<video>` and `w-full h-full` for anything else.
+- Useful as a responsive-image container, a chart area (pair with Chart components), or a placeholder frame for media skeletons.
+- Works inside Card, any layout component, or flex/grid containers — nothing to configure.
+
 ## Gotchas
 - ratio is a number, not a string — use `16/9` not `"16/9"`
+- The child must be size-fluid (`w-full h-full` or absolutely positioned) — elements with intrinsic size escape the aspect-ratio box
 
 ## Changes
 ### v0.1.0

package/docs/components/ui/autocomplete.md

@@ -27,6 +27,13 @@
 />
 ```
 
+## Composability
+- **Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list. Pick by whether "off-list" values are valid (e.g. city field that accepts typos → Autocomplete; tag picker from a fixed vocabulary → Combobox).
+- **Value shape is an object** (`{ value, label }`), not a plain string — this preserves label/value decoupling for display-vs-storage.
+- **FormField:** Does NOT auto-consume FormField state. Set explicit error styling via className if needed.
+- **Portal rendering:** Dropdown portals to body with z-popover (1400) — stacks above Dialog/Sheet.
+- **Keyboard:** ArrowDown/Up navigate suggestions, Enter selects, Esc closes. Typeahead is the input's native filtering.
+
 ## Gotchas
 - Allows free-text input (no forced selection) — use Combobox for forced selection
 - value is an object { value, label }, NOT just a string

package/docs/components/ui/avatar.md

@@ -31,10 +31,20 @@
 </Avatar>
 ```
 
+## Composability
+- **Two internal contexts cascade to AvatarFallback:**
+  - `AvatarSizeContext` — carries the Avatar's `size` so AvatarFallback's font size scales without re-specifying (xs → `text-[9px]`, sm → `text-ds-xs`, md → `text-ds-sm`, lg → `text-ds-md`, xl → `text-ds-lg`)
+  - `AvatarShapeContext` — carries `shape` so AvatarFallback inherits the same border-radius (critical for `shape="square"` / `shape="rounded"` — without context the fallback would always be `rounded-ds-full` regardless of parent)
+- **Status + Ring + Badge are independent** — you can stack all three on one Avatar. They render in separate layers so they don't conflict visually.
+- **Use with AvatarGroup:** AvatarGroup applies its own `size` to children. If your Avatar has an explicit `size`, it overrides AvatarGroup's default — keep it consistent across the group.
+- **AvatarFallback colorSeed:** Deterministic background color from the seed string — identical user IDs produce identical backgrounds across renders. Useful for user-identifying avatars without photos.
+- **Ring offset color:** The ring renders with `ring-offset` matching the current surface — it assumes the Avatar sits on `bg-surface-raised`. On other backgrounds, add a ring-offset className to compensate.
+
 ## Gotchas
 - Status dot renders with role="img" and aria-label (accessible, not decorative)
 - Dot size scales automatically with avatar size
 - AvatarFallback font size scales automatically with avatar size (via AvatarSizeContext)
+- AvatarFallback shape inherits from Avatar (via AvatarShapeContext) — setting `rounded-*` on AvatarFallback directly conflicts with the context
 - Ring offset color matches the surface context — ensure it sits on the expected background
 - Badge is hidden when value is `0` (falsy); use `"dot"` for presence without a count
 - Online status dot pulses with a CSS animation

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

@@ -27,6 +27,13 @@
 {/* Renders: React, TypeScript, Tailwind, +2 */}
 ```
 
+## Composability
+- **Wrapper for Badge children** — doesn't style children, just lays them out and optionally collapses overflow into a "+N" indicator.
+- **Server-safe** — can render in RSC trees (children still need to be server-safe themselves).
+- **Overflow indicator is a Badge** — picks `variant="outline" color="neutral"` and the `size` prop on BadgeGroup. Child badges keep their own variant/color/size.
+- **Click-to-reveal pattern:** Pair `onOverflowClick` with a Popover / Sheet / Dialog that shows the full list. Without the handler, the overflow badge is inert (decorative count).
+- Doesn't accept arbitrary children — only Badges. Non-Badge children render but may look off (no gap rhythm matching).
+
 ## Gotchas
 - Overflow badge is always `variant="outline" color="neutral"`
 - `size` only applies to the overflow badge — child badges keep their own size

package/docs/components/ui/badge-indicator.md

@@ -29,6 +29,13 @@
 </Badge.Indicator>
 ```
 
+## Composability
+- **Overlay wrapper** — takes any child and overlays a positioned count/dot at the specified corner. The child must be inline-friendly (anything that renders in a span-wrapped position: relative context).
+- **Common pairings:** IconButton (notification bell with count), Avatar (online presence dot), Button (cart with item count), tabs (unread indicator).
+- **Invisible for layout stability:** Use `invisible={true}` to keep the child's position consistent when the badge should disappear — avoids layout shift as counts appear/disappear.
+- **showZero vs hide-on-zero:** By default `count={0}` hides the indicator. Set `showZero={true}` for use cases where "zero" is meaningful (scores, pending items that should display 0 explicitly).
+- **Dot vs count:** `dot={true}` is a presence-only pulse indicator (online, new activity); count is a numeric badge. They're mutually exclusive — setting both uses dot.
+
 ## Gotchas
 - Wraps children in `position: relative` span — the indicator is absolutely positioned
 - Animation uses spring physics, respects `prefers-reduced-motion`

package/docs/components/ui/badge.md

@@ -36,6 +36,18 @@
 <Badge color="custom" style={{ '--badge-color': '#8b5cf6' }}>Custom</Badge>
 ```
 
+## Composability
+- **Badge.Group** (BadgeGroup) wraps a set of badges with overflow collapse (`max` + "+N" indicator) and gap control. Use it for filter chips, tag lists, user cluster avatars-equivalent.
+- **Badge.Indicator** (BadgeIndicator) attaches a count / dot overlay to ANY child (icons, avatars, buttons). It's positioning-only — doesn't style the child.
+- **Interactive modes:**
+  - `onClick` alone → renders as `<button>` (standard interactive badge)
+  - `onDismiss` alone → renders as `<span>` with an inner X button
+  - Both → renders as `<div role="button">` (avoids invalid nested buttons) — the X button inside handles its own click isolation
+- **asChild:** Use with router Links for nav-style badges (`<Badge asChild><Link href="/tags/react">React</Link></Badge>`).
+- **Custom colors via CSS variables:** Set `color="custom"` + inline style `style={{ '--badge-color': '#...' }}`. For solid variant, also set `--badge-fg-color` for the foreground.
+- **Icon slots auto-size via IconProvider** — same cascade as Button. Don't set explicit size on nested `<Icon>`.
+- **Chip (deprecated)** was merged into Badge — use Badge with `onClick` and `selected` for the old Chip use case.
+
 ## Gotchas
 - DO NOT use variant="destructive" — use variant="solid" color="error"
 - Badge is now interactive when `onClick` is provided (renders as `<button>`)