@devalok/shilp-sutra 0.28.0 → 0.29.0

package/docs/components/ui/chat.md

@@ -0,0 +1,214 @@
+# Chat
+
+- Import: @devalok/shilp-sutra/ui/chat
+- Server-safe: No (MessageList, Message, MessageInput, TypingIndicator use Framer Motion); DateSeparator and UnreadSeparator are server-safe
+- Category: ui
+
+Seven primitives for building chat interfaces: MessageList, Message (compound), SystemMessage, MessageInput, DateSeparator, UnreadSeparator, TypingIndicator.
+
+---
+
+## MessageList
+
+Scrollable container with auto-scroll, load-more, empty state, and "N new" floating pill.
+
+### Props
+    autoScroll: boolean — auto-scroll to bottom on new content (default: true)
+    newMessageCount: number — count shown in floating pill (default: 0)
+    onScrollToBottom: () => void — called when user clicks the "N new" pill
+    onLoadMore: () => void — called when user scrolls near top
+    isLoadingMore: boolean — shows spinner at top (default: false)
+    emptySlot: ReactNode — content when there are no children
+    headerSlot: ReactNode — content above the scroll container (e.g. channel name)
+    scrollToBottomSlot: ReactNode — reserved slot for custom scroll-to-bottom button
+    children: ReactNode (REQUIRED)
+
+### Example
+```jsx
+<MessageList autoScroll onLoadMore={loadMore} isLoadingMore={loading} newMessageCount={3} onScrollToBottom={markRead}>
+  {messages.map(m => <Message key={m.id}>...</Message>)}
+</MessageList>
+```
+
+---
+
+## Message (Compound)
+
+Compound component: `Message`, `Message.Avatar`, `Message.Content`, `Message.Author`, `Message.Body`, `Message.EditableBody`, `Message.Reactions`, `Message.Actions`, `Message.Action`.
+
+### Message (root) Props
+    variant: "flat" | "bubble" (default: "flat")
+    placement: "start" | "end" (default: "start")
+    highlight: "mention" | "internal"
+    grouped: boolean — hides avatar/author for consecutive messages (default: false)
+    deleted: boolean — renders deleted placeholder (default: false)
+    deletedText: string (default: "This message was deleted")
+
+### Message.Avatar Props
+    src: string | null — avatar image URL
+    fallback: string — initials text
+    icon: ReactNode — custom icon instead of avatar
+    size: "sm" | "md" (default: "md")
+    children: ReactNode — fully custom avatar slot
+
+### Message.Author Props
+    name: string (REQUIRED)
+    badge: ReactNode
+    timestamp: Date
+    formattedTimestamp: string — pre-formatted timestamp (overrides timestamp)
+    timestampFormat: (date: Date) => string — custom formatter
+
+### Message.Body Props
+    children: ReactNode (REQUIRED)
+
+### Message.EditableBody Props
+    content: string (REQUIRED)
+    onSave: (newContent: string) => void (REQUIRED)
+    onCancel: () => void
+    canEdit: boolean (default: false)
+    renderContent: (content: string) => ReactNode — custom render for display mode
+
+### Message.Reactions Props
+    reactions: { emoji: string; count: number; reacted: boolean }[] (REQUIRED)
+    onReact: (emoji: string) => void (REQUIRED)
+
+### Message.Content Props
+    children: ReactNode (REQUIRED)
+    className: string
+
+### Message.Actions Props
+    children: ReactNode (REQUIRED)
+    delay: number — hover reveal delay in ms (default: 100)
+
+### Message.Action Props
+    icon: IconProps["icon"] (REQUIRED) — pass the Tabler component reference, e.g. `IconReply` (not `<IconReply />`)
+    label: string (REQUIRED)
+    onClick: () => void (REQUIRED)
+    variant: "default" | "danger" (default: "default")
+
+### Example
+```jsx
+<Message variant="flat" highlight="mention">
+  <Message.Avatar src={user.photo} fallback="JD" />
+  <Message.Content>
+    <Message.Author name="Jane Doe" timestamp={new Date()} badge={<Badge>Admin</Badge>} />
+    <Message.Body>Hello, world!</Message.Body>
+    <Message.Reactions reactions={reactions} onReact={handleReact} />
+    <Message.Actions>
+      <Message.Action icon={IconReply} label="Reply" onClick={handleReply} />
+      <Message.Action icon={IconTrash} label="Delete" onClick={handleDelete} variant="danger" />
+    </Message.Actions>
+  </Message.Content>
+</Message>
+```
+
+---
+
+## SystemMessage
+
+Inline system event or alert message (e.g. "Alice joined the channel").
+
+### Props
+    icon: ReactNode — custom icon
+    timestamp: string — ISO timestamp string
+    variant: "event" | "alert" (default: "event")
+    children: ReactNode (REQUIRED)
+
+### Example
+```jsx
+<SystemMessage>Alice joined the channel</SystemMessage>
+<SystemMessage variant="alert" timestamp="2026-03-26T10:00:00Z">Connection lost</SystemMessage>
+```
+
+---
+
+## MessageInput
+
+Auto-resizing textarea with send/stop buttons, streaming support, and slot-based extensibility.
+
+### Props
+    onSubmit: (text: string) => void (REQUIRED)
+    placeholder: string (default: "Type a message...")
+    disabled: boolean (default: false)
+    isStreaming: boolean — shows stop button instead of send (default: false)
+    onCancel: () => void — called when stop button is clicked
+    leadingSlot: ReactNode — content before the textarea (e.g. attachment button)
+    trailingSlot: ReactNode — content after the send button
+    disclaimer: string — centered text below the input (e.g. "AI can make mistakes")
+    sendIcon: ReactNode — custom send icon
+
+### Example
+```jsx
+<MessageInput
+  onSubmit={handleSend}
+  isStreaming={streaming}
+  onCancel={handleStop}
+  disclaimer="AI can make mistakes"
+/>
+```
+
+---
+
+## DateSeparator
+
+Horizontal rule with a formatted date label.
+
+### Props
+    date: Date | string (REQUIRED)
+    format: (date: Date) => string — custom date formatter
+    className: string
+
+### Example
+```jsx
+<DateSeparator date={new Date()} />
+<DateSeparator date="2026-03-25" format={(d) => d.toLocaleDateString()} />
+```
+
+---
+
+## UnreadSeparator
+
+Accent-colored horizontal rule marking the unread boundary.
+
+### Props
+    label: string (default: "NEW")
+    count: number — prepended to label (e.g. "5 NEW")
+    className: string
+
+### Example
+```jsx
+<UnreadSeparator />
+<UnreadSeparator count={5} />
+```
+
+---
+
+## TypingIndicator
+
+Animated bouncing dots with a text description of who is typing.
+
+### Props
+    users: { name: string; image?: string }[] (REQUIRED)
+    className: string
+
+### Example
+```jsx
+<TypingIndicator users={[{ name: 'Alice' }]} />
+<TypingIndicator users={[{ name: 'Alice' }, { name: 'Bob' }]} />
+```
+
+---
+
+## 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
+- `grouped` hides avatar and author — use for consecutive messages from the same user
+- MessageInput sends on Enter (Shift+Enter for newline) — textarea auto-resizes up to 160px
+- TypingIndicator renders nothing when `users` is empty
+- Message.Actions toolbar is hidden by default (opacity-0) — it reveals on hover of the parent Message root via `group-hover/message`. Only works when Actions is inside a Message root.
+- Message.Content is the flex column wrapper for Author + Body — required for proper layout in flat variant
+- DateSeparator's default formatter shows "Today", "Yesterday", or "Mon DD" / "Mon DD, YYYY"
+
+## Changes
+### v0.29.0
+- **Added** Initial release — 7 chat primitives (MessageList, Message, SystemMessage, MessageInput, DateSeparator, UnreadSeparator, TypingIndicator)

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

@@ -65,6 +65,9 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 - Use defaultDensity="compact" for Karm-style h-9 rows
 
 ## Changes
+### v0.29.0
+- **Fixed** Controlled selection infinite re-render loop — inline `getRowId` callback caused `onSelectionChange` effect to fire every render, creating a setState cycle with `selectedIds`. Now uses a stable ref for `getRowId`.
+
 ### v0.16.1
 - **Fixed** `serverPagination` object reference in `useCallback` dependency caused stale closure — now uses stable ref for `onPageChange`
 - **Fixed** `onSelectionChange` effect fired every render due to `table` in dependency array — now derives selected rows directly

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

@@ -0,0 +1,55 @@
+# DevalokGrain
+
+- Import: @devalok/shilp-sutra/ui/devalok-grain
+- Server-safe: No
+- Category: ui
+
+## Props
+    intensity: "subtle" | "medium" | "heavy" — grain intensity level
+    surface: "solid" | "soft" — affects noise opacity ('solid' for filled backgrounds, 'soft' for tinted/muted)
+    sheen: boolean — inner highlight (top-lit emboss) for premium 3D feel
+    animated: boolean — fade-in entrance animation on mount
+    hoverIntensify: boolean — increase grain visibility on parent hover (requires parent `group` class)
+    tint: string — CSS color for the directional gradient (e.g. "oklch(0.55 0.19 360)", "var(--color-accent-9)")
+
+## Defaults
+    intensity: "subtle"
+    surface: "solid"
+    sheen: false
+    animated: false
+    hoverIntensify: false
+    tint: undefined (no gradient, noise texture only)
+
+## Example
+```jsx
+{/* Inside a Button (Button already has relative/overflow-hidden/isolate): */}
+<Button>
+  <DevalokGrain />
+  Save changes
+</Button>
+
+{/* Inside a Card: */}
+<Card className="relative overflow-hidden isolate">
+  <DevalokGrain surface="soft" />
+  Card content
+</Card>
+
+{/* Heavy grain with tint on a hero section: */}
+<div className="relative overflow-hidden isolate rounded-ds-lg bg-accent-9 p-8">
+  <DevalokGrain intensity="heavy" tint="oklch(0.55 0.19 360)" />
+  <h1 className="relative z-[2]">Hero</h1>
+</div>
+```
+
+## 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
+- Uses `rounded-[inherit]` to match parent border-radius automatically
+- Renders `aria-hidden="true"` — purely decorative
+- Without `tint`, only the noise texture renders (no directional gradient)
+- `hoverIntensify` requires the parent to have a `group` class for `group-hover:` to work
+- Respects `prefers-reduced-motion` — entrance animation disabled when user prefers reduced motion
+
+## Changes
+### v0.29.0
+- **Added** Initial release — brand noise texture with directional gradient, sheen, animation, and hover intensification

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

@@ -5,12 +5,12 @@
 - Category: ui
 
 ## Props
-    icon: ReactNode (REQUIRED)
+    icon: ReactElement (REQUIRED — use <Icon icon={...} />)
     aria-label: string (REQUIRED — WCAG AA mandatory)
     shape: "square" | "circle"
     size: "sm" | "md" | "lg"
-    variant: same as Button (solid, outline, ghost, link)
-    color: same as Button (default, error)
+    variant: same as Button (solid, soft, outline, ghost, link)
+    color: same as Button (accent, error, success, warning, neutral)
     loading: boolean
     disabled: boolean
 
@@ -20,14 +20,21 @@
 
 ## Example
 ```jsx
-<IconButton icon={<IconEdit />} variant="ghost" aria-label="Edit item" />
-<IconButton icon={<IconX />} shape="circle" variant="ghost" size="sm" aria-label="Close" />
+<IconButton icon={<Icon icon={IconEdit} />} variant="ghost" aria-label="Edit item" />
+<IconButton icon={<Icon icon={IconX} />} shape="circle" variant="ghost" size="sm" aria-label="Close" />
+<IconButton icon={<Icon icon={IconTrash} />} variant="solid" color="error" aria-label="Delete" />
 ```
 
 ## Gotchas
 - aria-label is enforced by TypeScript — you MUST provide it
 - Prefer IconButton over Button with size="icon-*" for icon-only buttons
+- `icon` prop should use `<Icon icon={...} />` wrapper (auto-sized via Button's IconProvider)
 
 ## Changes
+### v0.29.0
+- **Changed** `icon` prop now expects `<Icon icon={...} />` wrapper (auto-sized via Button's IconProvider context)
+- **Changed** Inherits all new Button v2 colors: `accent`, `error`, `success`, `warning`, `neutral` (was `default`/`error` only)
+- **Changed** Inherits Button v2 variants including new `soft` variant
+
 ### v0.1.0
 - **Added** Initial release

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

@@ -0,0 +1,38 @@
+# IconContext
+
+- Import: @devalok/shilp-sutra/ui (barrel export)
+- Server-safe: No
+- Category: ui
+
+## Exports
+    IconContext — React.Context<IconContextValue>
+    IconProvider — Provider component (props: size?, stroke?, children)
+    useIconContext() — Hook returning { size?, stroke? }
+    IconSize — Type: "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+    IconStroke — Type: "light" | "regular" | "bold"
+
+## IconProvider Props
+    size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+    stroke: "light" | "regular" | "bold"
+    children: ReactNode (REQUIRED)
+
+## Example
+```jsx
+import { IconProvider, useIconContext } from '@devalok/shilp-sutra/ui'
+
+<IconProvider size="sm" stroke="bold">
+  <MyCustomIconComponent />
+</IconProvider>
+
+// Inside MyCustomIconComponent:
+const { size, stroke } = useIconContext()
+```
+
+## Gotchas
+- Used internally by IconGroup and Button to propagate icon sizing to children
+- If no provider is present, `useIconContext()` returns `{}` (empty object) — consumers should fall back to defaults
+- Value is memoized — safe for frequent re-renders
+
+## Changes
+### v0.29.0
+- **Added** Initial release — React context for propagating icon size and stroke weight

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

@@ -0,0 +1,36 @@
+# IconGroup
+
+- Import: @devalok/shilp-sutra/ui (barrel export)
+- Server-safe: No
+- Category: ui
+
+## Props
+    size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" — propagated to children via IconContext
+    stroke: "light" | "regular" | "bold" — propagated to children via IconContext
+    gap: "tight" | "default" | "loose" — flex gap between icons
+    label: string — accessible label (used as aria-label when role="toolbar")
+    role: "toolbar" — optional, set for toolbar patterns
+    className: string
+    children: ReactNode (REQUIRED)
+
+## Defaults
+    gap: "default"
+    role: undefined (no ARIA role)
+
+## Example
+```jsx
+<IconGroup size="sm" gap="tight" role="toolbar" label="Formatting">
+  <Icon icon={IconBold} label="Bold" />
+  <Icon icon={IconItalic} label="Italic" />
+  <Icon icon={IconUnderline} label="Underline" />
+</IconGroup>
+```
+
+## Gotchas
+- Wraps children in an IconProvider — all child Icons inherit size/stroke from the group
+- `label` is only applied as `aria-label` when `role="toolbar"` is set
+- Gap values: tight=2px, default=4px, loose=8px
+
+## Changes
+### v0.29.0
+- **Added** Initial release — icon grouping with shared context, toolbar ARIA support

package/docs/components/ui/icon.md

@@ -0,0 +1,47 @@
+# Icon
+
+- Import: @devalok/shilp-sutra/ui (barrel export)
+- Server-safe: No
+- Category: ui
+
+## Props
+    icon: ForwardRefExoticComponent (REQUIRED — Tabler icon or any ForwardRef SVG icon component)
+    size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" — reads from IconContext if not set
+    stroke: "light" | "regular" | "bold" — reads from IconContext if not set
+    label: string — accessible label (renders <title> + sets aria-label; without it, icon is aria-hidden)
+    animate: "spin" | "pulse" | "bounce" | "draw" | "none" | { rotate?: number; scale?: number }
+    state: "idle" | "loading" | "success" | "error" — delegates to Spinner (bare variant)
+    className: string
+
+## Defaults
+    size: "md" (from context or fallback)
+    stroke: "regular" (from context or fallback)
+    state: undefined (no state machine)
+    animate: undefined (static render)
+
+## Example
+```jsx
+<Icon icon={IconPlus} />
+<Icon icon={IconPlus} size="xs" stroke="light" />
+<Icon icon={IconPlus} label="Add item" />
+<Icon icon={IconPlus} animate="spin" />
+<Icon icon={IconCheck} animate="draw" />
+<Icon icon={IconPlus} state="loading" />
+<Icon icon={IconPlus} state="success" />
+```
+
+## Gotchas
+- Without `label`, the icon renders `aria-hidden="true"` (decorative)
+- With `label`, the icon renders `role="img"` with `aria-label` and a `<title>` element
+- **Priority rule:** If both `state` and `animate` are set, `state` wins
+- `state="loading"` renders a bare Spinner; `state="success"` / `state="error"` render animated checkmark/cross
+- Size tiers map to pixel values: xs=14, sm=16, md=18, lg=20, xl=24, 2xl=32
+- Stroke weight varies by size tier (lighter strokes on smaller icons)
+- Reads size/stroke from IconContext (provided by Button, IconGroup, etc.); explicit props override context
+- `animate="draw"` works with IconCheck, IconX, and CircleCheck only — other icons fall back to static render
+- Respects `prefers-reduced-motion` — animations disabled when user prefers reduced motion
+
+## Changes
+### v0.29.0
+- **Added** Initial release — context-aware Icon wrapper with size tiers, stroke weights, accessibility, animations, state machine
+- **Added** `animate="draw"` — SVG path-draw animation using `pathLength`. Draws check/X strokes progressively (0.35s easeOut). Respects `prefers-reduced-motion`.

package/docs/components/ui/input.md

@@ -5,10 +5,17 @@
 - Category: ui
 
 ## Props
-    size: "sm" | "md" | "lg"
+    size: "xs" | "sm" | "md" | "lg"
     state: InputState
-    startIcon: ReactNode
-    endIcon: ReactNode
+    startSection: ReactNode (icon or content in the leading slot)
+    endSection: ReactNode (icon or content in the trailing slot)
+    startSectionClickable: boolean (enables pointer events on start section)
+    endSectionClickable: boolean (enables pointer events on end section)
+    startSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
+    endSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
+    wrapperClassName: string (classes for the wrapper div — border, bg, ring)
+    startIcon: ReactNode (@deprecated — use startSection)
+    endIcon: ReactNode (@deprecated — use endSection)
     (plus all standard HTML input attributes except native "size")
 
 ## Types
@@ -19,17 +26,36 @@
 
 ## Example
 ```jsx
-<Input type="email" placeholder="you@example.com" state="error" startIcon={<IconMail />} />
+<Input type="email" placeholder="you@example.com" state="error" startSection={<Icon icon={IconMail} />} />
+<Input size="xs" placeholder="Quick search" startSection={<Icon icon={IconSearch} />} />
+<Input startSection="https://" startSectionType="label" placeholder="example.com" />
+<Input endSection=".00" endSectionType="label" startSection={<Icon icon={IconCurrencyDollar} />} placeholder="0" />
 ```
 
 ## Gotchas
 - HTML native "size" attribute is excluded — use CSS width instead
 - state="error" sets aria-invalid automatically
 - Inside FormField: auto-inherits state, aria-describedby, aria-required from context (explicit props override)
-- Resting border is border-subtle (soft); focus ring is `ring-1 ring-accent-7` (v0.12.0)
-- All sizes (sm, md, lg) use text-ds-md (14px) font — size only affects height and padding (v0.15.0)
+- `className` targets the `<input>` element; use `wrapperClassName` for border/bg/ring overrides
+- Focus ring is on the wrapper container (focus-within), not the input itself
+- Icons in startSection/endSection are auto-sized via IconProvider per input size
+- Sections are `pointer-events-none` by default — set `startSectionClickable`/`endSectionClickable` for interactive sections
+- Section type is auto-inferred: strings default to `'label'` (tinted bg + border), React elements default to `'icon'` (fixed-width centered). Override with `startSectionType`/`endSectionType`.
 
 ## Changes
+### v0.29.0
+- **Changed** v2 rewrite: container-first architecture with wrapper div holding focus ring
+- **Added** `xs` size (28px height)
+- **Added** `startSection` / `endSection` props replacing `startIcon` / `endIcon` (deprecated but still work)
+- **Added** `startSectionClickable` / `endSectionClickable` props for interactive sections
+- **Added** `wrapperClassName` prop for styling the wrapper div (border, bg, ring)
+- **Changed** Focus ring now on wrapper via `focus-within` (container-level ring, not input-level)
+- **Changed** Icons auto-sized via `IconProvider` context per input size
+- **Deprecated** `startIcon` / `endIcon` — use `startSection` / `endSection`
+- **Added** `startSectionType` / `endSectionType` props — `'icon'` (fixed-width centered cell) or `'label'` (tinted background with border separator). Auto-inferred from content type (strings → label, React elements → icon).
+- **Changed** Sections use flexbox layout for consistent alignment
+- **Deprecated** `inputVariants` export — use `inputWrapperVariants` (semantics changed to target wrapper)
+
 ### v0.15.0
 - **Changed** `lg` size font changed from `text-ds-lg` (18px) to `text-ds-md` (14px) — all input sizes now use 14px for consistency
 - **Changed** `md` size font standardized to `text-ds-md` (14px) from mixed values

package/docs/components/ui/progress.md

@@ -8,6 +8,7 @@
     value: number (0-100) — omit for indeterminate
     size: "sm" | "md" | "lg" (track height)
     color: "default" | "success" | "warning" | "error" (indicator color)
+    autoColor: boolean (auto-shifts color by value: 0-59=default, 60-84=warning, 85-100=success, >100=error)
     showLabel: boolean (shows percentage text)
     indicatorClassName: string
 
@@ -23,7 +24,11 @@
 
 ## Gotchas
 - Omit value (or pass undefined) for indeterminate animation
+- `autoColor` overrides `color` when `value` is set — do not pass both unless you want autoColor to win
 
 ## Changes
+### v0.29.0
+- **Added** `autoColor` prop — automatically shifts indicator color based on value thresholds (0-59 default, 60-84 warning, 85-100 success, >100 error)
+
 ### v0.1.0
 - **Added** Initial release with `size`, `color`, `indeterminate` variants and optional label slot

package/docs/components/ui/spinner.md

@@ -32,6 +32,9 @@
 - No longer server-safe as of v0.18.0 (uses Framer Motion)
 
 ## Changes
+### v0.29.0
+- **Changed** `bare` variant spinning state now uses `currentColor` instead of `var(--color-accent-9)` — inherits text color from parent for seamless embedding in buttons/toolbars
+
 ### v0.18.0
 - **Changed** (BREAKING) Complete rewrite with Framer Motion arc animation and state transitions
 - **Added** `state` prop: 'spinning' | 'success' | 'error'

package/docs/components/ui/switch.md

@@ -9,16 +9,29 @@
     onCheckedChange: (checked: boolean) => void
     error: boolean (shows red border/bg)
     disabled: boolean
+    size: "sm" | "md" | "lg"
+    color: "accent" | "success" | "warning"
+    thumbIcon: ReactNode (icon rendered inside the thumb)
+
+## Defaults
+    size="md", color="accent"
 
 ## Example
 ```jsx
 <Switch checked={enabled} onCheckedChange={setEnabled} />
+<Switch size="lg" color="success" thumbIcon={<IconCheck size={14} />} />
 ```
 
 ## Gotchas
 - Use error prop for validation states (matches Checkbox API)
+- `error` overrides `color` — when error is true, checked state always uses error-9
 
 ## Changes
+### v0.29.0
+- **Added** `size` prop: `"sm"` (18px track) | `"md"` (24px, default) | `"lg"` (28px track)
+- **Added** `color` prop: `"accent"` (default) | `"success"` | `"warning"` for checked-state color
+- **Added** `thumbIcon` prop — renders any ReactNode inside the thumb circle (e.g., check icon)
+
 ### v0.18.0
 - **Changed** Migrated to Framer Motion spring thumb animation
 - **Fixed** Added visible border on unchecked state (`border-surface-border-strong`) — was borderless, making unchecked state hard to see