@devalok/shilp-sutra 0.37.0 → 0.37.1

package/docs/components/ui/text.md

@@ -5,12 +5,9 @@
 - Category: ui
 
 ## Props
-    variant: TextVariant
+    variant: "heading-2xl" | "heading-xl" | "heading-lg" | "heading-md" | "heading-sm" | "heading-xs" | "body-lg" | "body-md" | "body-sm" | "body-xs" | "label-lg" | "label-md" | "label-sm" | "label-xs" | "label-plain-lg" | "label-plain-md" | "label-plain-sm" | "caption" | "overline" | "code"
     as: ElementType (override the auto-selected HTML element)
 
-## Types
-    TextVariant = 'heading-2xl' | 'heading-xl' | 'heading-lg' | 'heading-md' | 'heading-sm' | 'heading-xs' | 'body-lg' | 'body-md' | 'body-sm' | 'body-xs' | 'label-lg' | 'label-md' | 'label-sm' | 'label-xs' | 'caption' | 'overline'
-
 ## Defaults
     variant: "body-md"
 
@@ -25,9 +22,17 @@
 <Text variant="label-sm" className="text-text-secondary">SECTION LABEL</Text>
 ```
 
+## Composability
+- **Server-safe** (one of few components in the library that is). Can render in RSC trees without `"use client"`.
+- No context consumption, no context cascade — pure typography primitive.
+- **Semantic HTML by default:** Each variant maps to a meaningful HTML element (h1 through p, span, code). The `as` prop overrides for visual-only demotion: e.g. `<Text variant="heading-xl" as="div">` renders h2-sized text inside a div, useful when the element already has a heading ancestor but you want the visual weight.
+- **Underpins many components:** Card's CardTitle, Alert's title, PageHeader, EmptyState, SectionHeader all render Text internally with specific variants. Don't wrap another Text inside them — variants cascade structurally, not via context.
+- Pairs with Code for inline code spans inside body text: `<Text>Call <Code>onClick</Code> to...</Text>`.
+
 ## Gotchas
 - label-* and overline variants are automatically uppercase
 - Use "as" prop to override the HTML element when needed
+- Don't use Text inside headings that already have semantic meaning (e.g. CardTitle) — the double-element wraps are redundant and break screen-reader heading navigation
 
 ## Changes
 ### v0.2.0

package/docs/components/ui/textarea.md

@@ -5,7 +5,7 @@
 - Category: ui
 
 ## Props
-    size: "sm" | "md" | "lg"
+    size: "xs" | "sm" | "md" | "lg"
     state: "default" | "error" | "warning" | "success"
     (plus standard textarea attributes except native "size")
 
@@ -17,6 +17,12 @@
 <Textarea size="lg" state="error" placeholder="Describe the issue..." />
 ```
 
+## Composability
+- **FormField auto-consumption:** Same pattern as Input — inside `<FormField>`, Textarea inherits `state`, `aria-describedby`, `aria-invalid`, `aria-required`. Explicit props override.
+- **Resize:** Vertically resizable by default (`resize-y`); override with `className="resize-none"` if needed.
+- **Label pairing:** Manual — `<Label htmlFor="x" />` + `<Textarea id="x" />`. FormField doesn't auto-wire.
+- No IconProvider cascade (no icon slots — different from Input).
+
 ## Gotchas
 - state="error" sets aria-invalid automatically; all sizes are vertically resizable
 - Inside FormField: auto-inherits state, aria-describedby, aria-required from context (explicit props override)

package/docs/components/ui/toast.md

@@ -41,6 +41,15 @@ toast.error('Upload failed', { description: 'File too large' })
 toast.undo('Task deleted', { onUndo: () => restoreTask(id) })
 ```
 
+## Composability
+- **Imperative API only** — `toast.success(...)`, `toast.error(...)`, etc. NO JSX invocation. This is by design (Sonner-based) — you call from event handlers, not render.
+- **Requires Toaster mounted once** at app root. Without it, `toast.*` calls are no-ops. Render `<Toaster />` in the root layout, not inside route components.
+- **toast.promise** orchestrates async flows: `toast.promise(fetch(...), { loading: 'Saving', success: 'Saved', error: 'Failed' })`. One toast, three states. Beats manually calling `.loading()` + `.success()`/`.error()`.
+- **toast.undo** adds an inline Undo button with 8s default duration — pair with state management that supports reversal (soft-delete with restore, last-action redo).
+- **toast.upload** is specifically for file-upload progress — per-file progress bars, retry on error, remove from list. Replaces the old `UploadProgress` composed component.
+- **toast.custom** is the escape hatch — render arbitrary JSX. Use sparingly; prefer the typed methods for consistency.
+- **Distinction from Alert/Banner:** Toast = transient, auto-dismissing, non-interactive-dismissible floating notification. Alert = inline in-flow announcement. Banner = page-level strip. Pick by persistence + position.
+
 ## Gotchas
 - DO NOT use useToast() hook — it is deprecated, use imperative toast.* methods
 - DO NOT use toast({ title, color }) object syntax — use toast.success('message') etc.

package/docs/components/ui/toaster.md

@@ -33,9 +33,17 @@ export default function RootLayout({ children }) {
 }
 ```
 
+## Composability
+- **Mount once, use everywhere.** Render `<Toaster />` in the root layout file once. Every `toast.*` call anywhere in the tree routes to this single container.
+- **Global config lives here.** Set `position`, `duration`, `visibleToasts` on Toaster to control default behavior for all toasts. Individual `toast.*` calls can override `duration` per toast.
+- **Keyboard shortcut:** `hotkey` prop sets a global shortcut to focus the toast region (default: Alt+T). Useful for keyboard users to review recent notifications.
+- **Next.js / App Router:** Mount inside your root `app/layout.tsx`'s `<body>`. It's marked `'use client'` so it doesn't render on the server (Toaster is client-only).
+- **Portal rendering:** z-toast (highest layer) — Toaster content appears above Dialog, Popover, everything. Don't wrap it in a stacking context.
+
 ## Gotchas
 - Must be mounted once at the layout root for toast notifications to work
 - Use the `toast` import from `@devalok/shilp-sutra/ui/toast` to trigger toasts
+- NOT server-safe — mounts with 'use client'; rendering during SSR has no visual effect
 
 ## Changes
 ### v0.18.0

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

@@ -16,8 +16,11 @@
     value: string
 
 ## Compound Components
-    ToggleGroup (root)
-      ToggleGroupItem (value: string)
+    ToggleGroup (root — variant, size propagated to items via context)
+      ToggleGroupItem (value: string — reads variant/size from context)
+
+## Defaults
+    variant="default", size="md"
 
 ## Example
 ```jsx
@@ -28,9 +31,15 @@
 </ToggleGroup>
 ```
 
+## Composability
+- ToggleGroup passes `variant` and `size` to every ToggleGroupItem via `ToggleGroupContext`. Items read both from context; explicit props on a child override.
+- `type="single"` enforces one-selected-at-a-time (value: string); `type="multiple"` allows many (value: string[]). Radix Toggle Group underpins this — it's the same role + keyboard model as Radix.
+- Built on top of the plain `Toggle` component's CVA — the `variant` and `size` axes of ToggleGroupItem match Toggle exactly (`default | outline`, `sm | md | lg`).
+
 ## Gotchas
-- type is required — "single" or "multiple"
-- variant and size propagate from ToggleGroup to items
+- `type` is required — "single" or "multiple" — and drives the value shape
+- variant and size propagate from ToggleGroup to items; setting them on a ToggleGroupItem overrides that item only
+- Unlike Tabs (where TabsList is the styling surface), ToggleGroup itself is the styling surface — there's no intermediate List component
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/toggle.md

@@ -7,13 +7,13 @@
 ## Props
     variant: "default" | "outline"
     size: "sm" | "md" | "lg"
+    color: "accent" | "error" | "success" | "neutral" (pressed-state bg + text color)
     pressed: boolean
     onPressedChange: (pressed: boolean) => void
     defaultPressed: boolean
 
 ## Defaults
-    variant: "default"
-    size: "md"
+    variant="default", size="md", color="accent"
 
 ## Example
 ```jsx
@@ -22,8 +22,16 @@
 </Toggle>
 ```
 
+## Composability
+- Radix Toggle primitive — `pressed` / `onPressedChange` / `defaultPressed`. Not the same as Switch (boolean value doesn't map to on/off semantically — Toggle is "this action is currently active").
+- **Pairs with ToggleGroup** for mutually-exclusive or multi-select toggle clusters — ToggleGroupItem inherits variant + size from ToggleGroup via context. Don't set variant on a ToggleGroupItem directly.
+- **No context consumption as a standalone** — when rendered outside a ToggleGroup, Toggle is fully independent.
+- **Icon content:** Commonly wraps a single `<Icon>` for formatting toolbar toggles (Bold, Italic, AlignLeft). Pair with IconGroup for a horizontal cluster of independent toggles (vs. ToggleGroup for related state).
+- **aria-label is required** — icon-only toggles need an accessible name.
+
 ## Gotchas
 - Always provide aria-label for accessibility
+- Toggle is not Switch — Toggle means "this action is active right now"; Switch means "this setting is on"
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/tooltip.md

@@ -20,8 +20,18 @@
 </TooltipProvider>
 ```
 
+## Composability
+- Built on Radix Tooltip — accepts `delayDuration`, `skipDelayDuration` (on TooltipProvider), and `open`/`onOpenChange`/`defaultOpen` (on Tooltip root).
+- **Auto-provider (v0.22.0+):** If no ancestor TooltipProvider exists, `<Tooltip>` auto-wraps itself with one. Explicit TooltipProvider is still recommended at layout root for shared `delayDuration` tuning.
+- **Trigger:** `<TooltipTrigger asChild>` around the element that should show the tooltip on hover/focus. Icon-only buttons are the canonical use case.
+- **Not interactive:** TooltipContent is for non-interactive text labels — don't put buttons/links inside. Use HoverCard or Popover when the popped content needs interaction.
+- **Positioning:** TooltipContent accepts `side`, `align`, `sideOffset`, and arrow via `<TooltipArrow>` (optional).
+- **Portal rendering:** z-index is `z-tooltip` (highest in the stack — above Popover and Dialog).
+
 ## Gotchas
-- TooltipProvider is REQUIRED — without it, tooltips won't show
+- TooltipProvider is REQUIRED at the layout level OR auto-created per-tooltip — but having a single root provider is better for consistent delays
+- Don't use Tooltip for critical information — hover-triggered UI is invisible to touch users. Pair with a visible label or aria-description
+- TooltipContent children must be inert — no buttons, no links, no focusable elements
 
 ## Changes
 ### v0.22.0

package/docs/components/ui/tree-view.md

@@ -51,8 +51,20 @@
 </TreeView>
 ```
 
+## Composability
+- **Two rendering modes:**
+  - **Data-driven:** Pass `items: TreeNode[]` with nested `children`. Good for server-fetched or programmatic trees.
+  - **Declarative:** Use `<TreeItem>` children directly. Good for hardcoded nav, readable JSX.
+  - Don't mix — pick one per TreeView instance.
+- **useTree hook** lets you drive TreeView state externally (e.g. sync with URL, persist expanded state, drive from Redux). Pass `defaultExpanded`/`defaultSelected` initially OR manage state via the hook's return value.
+- **TreeItem composability:** Each TreeItem has `icon`, `label`, `secondaryLabel`, and `actions` slots — rich rows without custom render props. `actions` reveals on row hover (same pattern as Message.Actions).
+- **multiSelect + checkboxes:** Set both to turn TreeView into a file-picker style tree with checkboxes instead of single-select highlighting.
+- **Keyboard navigation:** Full `role="tree"` spec — Arrow Up/Down to move, Right to expand/descend, Left to collapse/ascend, Enter to select. Pre-wired; no manual key handling needed.
+
 ## Gotchas
 - Supports both data-driven (items prop) and declarative (children) modes
+- Don't mix data-driven and declarative in the same TreeView — pick one
+- For a simple flat checkbox list, use RadioGroup/Checkbox + Stack — TreeView is overkill for non-hierarchical data
 
 ## Changes
 ### v0.4.2

package/docs/components/ui/visually-hidden.md

@@ -12,9 +12,16 @@
 <VisuallyHidden>Screen reader only text</VisuallyHidden>
 ```
 
+## Composability
+- Server-safe. Works anywhere — no context, no cascade.
+- Canonical use: wrap a DialogTitle / SheetTitle that must exist for a11y but shouldn't show visually (`<DialogTitle asChild><VisuallyHidden>...</VisuallyHidden></DialogTitle>`).
+- Also useful inside IconButton to provide a text alternative when the icon already has an aria-label (redundant label is harmless and helps some screen readers).
+- Uses the `sr-only` CSS pattern under the hood — content is in the DOM, just positioned off-screen.
+
 ## Gotchas
 - Content is visually hidden but accessible to screen readers
 - Useful for providing accessible labels without visual UI
+- Don't use for content you want hidden entirely — that's `hidden` or conditional rendering
 
 ## Changes
 ### v0.1.0