@devalok/shilp-sutra 0.28.0 → 0.30.0

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.28.0
+> Version: 0.30.0
 
 ---
 
@@ -54,15 +54,15 @@ Color tokens use OKLCH (perceptually uniform) with 12 functional steps per palet
 Semantic layer:
 - Accent (swappable): --color-accent-{1-12} + --color-accent-fg
 - Secondary: --color-secondary-{1-12} + --color-secondary-fg
-- Surface: --color-surface-{1-4} + --color-surface-fg / fg-muted / fg-subtle / border / border-strong
-  - Border mapping: light mode border=step5, border-strong=step6; dark mode border=step3, border-strong=step4
-  - Shell chrome (sidebar, topbar, bottom nav) uses surface-2 for elevation above surface-1 app background
+- Surface: --color-surface-{base,raised,sunken} + --color-surface-fg / fg-muted / fg-subtle / border / border-subtle
+  - Border mapping: light mode border=step5, border-subtle=step3; dark mode border=step3, border-subtle=step2
+  - Shell chrome (sidebar, topbar, bottom nav) uses surface-sunken with brand tint for recessed chrome
 - Status: --color-{error,success,warning,info}-{3,7,9,11}
 - Category: --color-category-{teal,amber,slate,indigo,cyan,orange,emerald}
 
 Consumer rebranding: Override accent scale CSS vars or use generateScale(options) utility.
 
-Tailwind utilities: accent-1..12, secondary-1..12, surface-1..4, plus fg/border variants.
+Tailwind utilities: accent-1..12, secondary-1..12, surface-base/raised/sunken, plus fg/border variants.
 
 ### Toast Setup Pattern
 
@@ -108,11 +108,11 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## Compound Components
     Accordion (root)
       AccordionItem (value: string, REQUIRED)
-        AccordionTrigger (clickable header, chevron auto-renders)
+        AccordionTrigger (clickable header, chevron auto-renders; chevronPosition: "left" | "right")
         AccordionContent (collapsible body)
 
 ## Defaults
-    none (type is required)
+    none (type is required); AccordionTrigger: chevronPosition="right"
 
 ## Example
 ```jsx
@@ -129,6 +129,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - collapsible only works with type="single"
 
 ## Changes
+### v0.29.0
+- **Added** `chevronPosition` prop on AccordionTrigger: `"left"` | `"right"` (default: `"right"`) — controls which side the chevron icon renders
+
 ### v0.18.0
 - **Changed** Accordion content fade animation migrated to Framer Motion (height animation still uses CSS keyframes)
 
@@ -380,13 +383,25 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Category: ui
 
 ## Props
-    variant: "subtle" | "solid" | "outline" | "secondary" (alias->subtle) | "destructive" (alias->solid+error)
-    color: "default" | "info" | "success" | "error" | "warning" | "brand" | "accent" | "teal" | "amber" | "slate" | "indigo" | "cyan" | "orange" | "emerald"
+    variant: "subtle" | "solid" | "outline" | "soft"
+    color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" | "teal" | "amber" | "slate" | "indigo" | "cyan" | "orange" | "emerald" | "custom"
     size: "xs" | "sm" | "md" | "lg"
-    dot: boolean (shows leading dot indicator)
-    onDismiss: () => void (shows X button when provided)
+    startIcon: ReactElement | null
+    endIcon: ReactElement | null
+    dot: boolean (shows animated leading dot indicator)
+    onClick: () => void (makes badge interactive as button)
+    selected: boolean (toggle state — shows check icon when true)
+    disabled: boolean
+    onDismiss: () => void (shows dismiss X button)
+    maxWidth: number (enables truncation with title tooltip)
+    circle: boolean (square aspect-ratio, centered content)
+    asChild: boolean
     children: ReactNode
 
+## Compound Components
+    Badge.Indicator — status indicator sub-component
+    Badge.Group — layout wrapper for badge collections
+
 ## Defaults
     variant="subtle", color="default", size="md"
 
@@ -394,13 +409,32 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ```jsx
 <Badge variant="solid" color="success">Active</Badge>
 <Badge color="teal" onDismiss={() => removeFilter('teal')}>Teal team</Badge>
+<Badge onClick={() => toggle()} selected={isSelected}>Filterable</Badge>
+<Badge color="custom" style={{ '--badge-color': '#8b5cf6' }}>Custom</Badge>
 ```
 
 ## Gotchas
 - DO NOT use variant="destructive" — use variant="solid" color="error"
-- Badge is display-only; for interactive tags use Chip
+- Badge is now interactive when `onClick` is provided (renders as `<button>`)
+- When both `onClick` and `onDismiss` are provided, renders as `div[role="button"]` to avoid nested buttons
+- Chip is deprecated — use Badge with `onClick` for interactive tags
+- `color="custom"` requires `--badge-color` CSS variable (and optionally `--badge-fg-color` for solid variant)
 
 ## Changes
+### v0.29.0
+- **Changed** (BREAKING) v2 rewrite — Badge is now a full interactive component
+- **Added** `soft` variant (tinted bg, no border — completes the 4-variant set: subtle/solid/outline/soft)
+- **Added** `custom` color with CSS variable `--badge-color` (and `--badge-fg-color` for solid)
+- **Added** Interactive mode: `onClick` makes Badge a clickable button, `selected` shows animated check icon
+- **Added** `disabled` prop with reduced opacity and pointer-events-none
+- **Added** `startIcon` / `endIcon` props (auto-sized per badge size)
+- **Added** `maxWidth` prop for truncation with title tooltip
+- **Added** `circle` prop for square aspect-ratio badges
+- **Added** `asChild` prop for Slot composition
+- **Added** `Badge.Indicator` and `Badge.Group` compound sub-components
+- **Deprecated** Chip component — use Badge with `onClick` instead
+- **Changed** Dot animation now uses Framer Motion spring entrance + continuous pulse
+
 ### v0.18.0
 - **Changed** Pulse-ring animation migrated to Framer Motion
 - **Fixed** Accent color variants — `text-accent-9` changed to `text-accent-11`, `border-accent-9` changed to `border-accent-7`
@@ -421,6 +455,84 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 
 ### v0.1.0
 - **Added** Initial release
+# BadgeGroup
+
+- Import: @devalok/shilp-sutra/ui (as Badge.Group)
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    max: number — Show at most N badges, rest collapsed into "+N" overflow
+    gap: "tight" | "default" | "loose" (default: "default")
+    size: BadgeProps["size"] — Size passed to the overflow "+N" badge
+    onOverflowClick: () => void — Click handler for the overflow "+N" badge
+    className: string
+    children: ReactNode (REQUIRED)
+
+## Defaults
+    gap="default", max=undefined (show all), size="sm" (overflow badge)
+
+## Example
+```jsx
+<Badge.Group max={3} size="sm" onOverflowClick={() => setShowAll(true)}>
+  <Badge>React</Badge>
+  <Badge>TypeScript</Badge>
+  <Badge>Tailwind</Badge>
+  <Badge>Vite</Badge>
+  <Badge>Vitest</Badge>
+</Badge.Group>
+{/* Renders: React, TypeScript, Tailwind, +2 */}
+```
+
+## Gotchas
+- Overflow badge is always `variant="outline" color="neutral"`
+- `size` only applies to the overflow badge — child badges keep their own size
+- Gap values: tight=4px, default=6px, loose=8px
+- Without `onOverflowClick`, the overflow badge is not interactive
+
+## Changes
+### v0.29.0
+- **Added** Initial release — badge grouping with overflow collapse and click handler
+# BadgeIndicator
+
+- Import: @devalok/shilp-sutra/ui (as Badge.Indicator)
+- Server-safe: No
+- Category: ui
+
+## Props
+    count: number — Numeric value to display
+    max: number (default: 99) — Cap display at this value, shows "99+" when exceeded
+    dot: boolean (default: false) — Show a small dot instead of count
+    color: "error" | "success" | "warning" | "accent" | "info" (default: "error")
+    invisible: boolean (default: false) — Hide the indicator while keeping layout
+    showZero: boolean (default: false) — Show indicator when count is 0
+    placement: "top-right" | "top-left" | "bottom-right" | "bottom-left" (default: "top-right")
+    className: string
+    children: ReactNode (REQUIRED) — The element to attach the indicator to
+
+## Defaults
+    max=99, dot=false, color="error", invisible=false, showZero=false, placement="top-right"
+
+## Example
+```jsx
+<Badge.Indicator count={5}>
+  <IconButton icon={IconBell} variant="ghost" />
+</Badge.Indicator>
+
+<Badge.Indicator dot color="success">
+  <Avatar src={user.avatar} fallback={user.name} />
+</Badge.Indicator>
+```
+
+## Gotchas
+- Wraps children in `position: relative` span — the indicator is absolutely positioned
+- Animation uses spring physics, respects `prefers-reduced-motion`
+- When `count > max`, displays `${max}+` (e.g., "99+")
+- `invisible` keeps the layout but hides the dot/count (useful for transitions)
+
+## Changes
+### v0.29.0
+- **Added** Initial release — animated notification indicator with count, dot, placement, and color
 # Banner
 
 - Import: @devalok/shilp-sutra/ui/banner
@@ -507,37 +619,66 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Category: ui
 
 ## Props
-    variant: "solid" | "default" (alias->solid) | "outline" | "ghost" | "link" | "destructive" (alias->solid+error)
-    color: "default" | "error"
-    size: "sm" | "md" | "lg" | "icon" | "icon-sm" | "icon-md" | "icon-lg"
-    startIcon: ReactNode
-    endIcon: ReactNode
+    variant: "solid" | "soft" | "outline" | "ghost" | "link" | "default" (alias->solid) | "destructive" (alias->solid+error)
+    color: "accent" | "error" | "success" | "warning" | "neutral" | "default" (alias->accent)
+    size: "xs" | "sm" | "md" | "lg" | "compact-xs" | "compact-sm" | "compact-md" | "icon" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg"
+    weight: "semibold" | "normal"
+    shape: "default" | "pill"
+    startIcon: ReactElement (use <Icon icon={...} />) | null
+    endIcon: ReactElement (use <Icon icon={...} />) | null
     loading: boolean (disables button, shows spinner)
     loadingPosition: "start" | "end" | "center" (default: "start")
     fullWidth: boolean
     asChild: boolean
-    onClickAsync: (e: MouseEvent) => Promise<void> (auto loading->success/error->idle)
+    processing: boolean | 'ambient' | 'working' | 'urgent' (marching ants SVG border)
+    processingColor: 'accent' | 'error' | 'success' | 'warning' | 'neutral' (override animation color)
+    processingDisabled: boolean (disable button during processing, default: true)
+    onClickAsync: (e: MouseEvent) => Promise<void> (auto loading->success/error->idle, auto-activates processing)
     asyncFeedbackDuration: number (ms, default 1500)
 
 ## Defaults
-    variant="solid", color="default", size="md"
+    variant="solid", color="accent", weight="semibold", size="md", shape="default"
 
 ## Example
 ```jsx
-<Button variant="solid" color="error" startIcon={<IconTrash />} loading={isDeleting}>
+<Button variant="solid" color="error" startIcon={<Icon icon={IconTrash} />} loading={isDeleting}>
   Delete project
 </Button>
+<Button variant="soft" color="success" startIcon={<Icon icon={IconCheck} />}>Approved</Button>
+<Button variant="soft" color="warning" size="compact-sm" shape="pill">Overdue</Button>
 ```
 
 ## Gotchas
 - DO NOT use variant="destructive" — use variant="solid" color="error"
 - DO NOT use variant="secondary" — use variant="outline" or variant="ghost"
 - DO NOT use size="default" — use size="md"
-- DO NOT use color="danger" — use color="error"
-- Inherits variant/color/size from ButtonGroup context if present
-- onClickAsync overrides onClick and loading when active
+- DO NOT use color="danger" or color="default" — use color="error" or color="accent"
+- startIcon/endIcon now expect `<Icon icon={...} />` wrapper, not bare icon components
+- Inherits variant/color/size/weight/shape from ButtonGroup context if present
+- onClickAsync overrides onClick and loading when active; also auto-activates processing='working' during loading phase
+- processing forces soft variant so marching ants pop against the background
+- processingDisabled=true (default) makes button aria-disabled and pointer-events-none during processing
+- Grain children (DevalokGrain) are auto-separated and rendered as direct button children for absolute positioning
 
 ## Changes
+### v0.29.0
+- **Added** `soft` variant — tinted background, colored text (new middle ground between solid and ghost)
+- **Added** 5 color options: `accent` (default), `error`, `success`, `warning`, `neutral` (replaces old `default`/`error`-only axis)
+- **Added** `shape` prop: `"default"` | `"pill"` (rounded-full with extra horizontal padding)
+- **Added** compact sizes: `compact-xs`, `compact-sm`, `compact-md` (height-less inline buttons)
+- **Added** `xs` size and `icon-xs` size
+- **Added** `weight` prop: `"semibold"` (default) | `"normal"` for lighter labels
+- **Changed** `startIcon`/`endIcon` now accept `<Icon icon={...} />` wrapper (auto-sized via IconProvider context per button size)
+- **Changed** Default color is now `"accent"` (was `"default"`)
+- **Changed** Solid hover adds tinted shadows per color (e.g., `hover:shadow-brand`, `hover:shadow-error`)
+- **Changed** Icon slots get negative-margin inset to tighten padding against button edges
+- **Added** DevalokGrain support — grain children are auto-separated and rendered for texture overlays
+- **Added** `processing` prop — marching ants SVG border while content stays visible (`"ambient"` (3s) | `"working"` (2s) | `"urgent"` (1s) | boolean). Forces soft variant so ants pop.
+- **Added** `processingColor` — override processing animation color independently of button color
+- **Added** `processingDisabled` — disable button during processing (default: true). Set false for cancel-by-click patterns.
+- **Added** Auto-processing during `onClickAsync` — loading phase auto-activates `processing='working'` when no explicit `processing` prop is set
+- **Added** Always-on layout animation — smooth width/height transitions via Framer Motion FLIP
+
 ### v0.22.0
 - **Changed** Active/pressed scale from `0.97` to `0.95` for snappier press feedback.
 - **Fixed** Ghost/outline hover not fading — `transition-transform` in base overrode `transition-colors` from variant. Combined into single `transition-[color,background-color,border-color,box-shadow,transform]`.
@@ -592,6 +733,21 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 
 ### v0.1.0
 - **Added** Initial release
+# ButtonProcessing (Internal)
+
+- Import: Internal — not exported from barrel. Used only by Button.
+- Server-safe: No
+- Category: ui
+
+## Description
+
+Internal component that renders the processing animation overlay for Button. Consumers use the `processing` prop on Button, not this component directly.
+
+See `Button` docs for the public API.
+
+## 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.
 # Card
 
 - Import: @devalok/shilp-sutra/ui/card
@@ -683,6 +839,220 @@ import { BarChart } from '@devalok/shilp-sutra/ui/charts'
 
 ### v0.1.0
 - **Added** Initial release
+# 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)
 # Checkbox
 
 - Import: @devalok/shilp-sutra/ui/checkbox
@@ -1140,6 +1510,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
@@ -1208,6 +1581,61 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 
 ### v0.1.0
 - **Added** Initial release
+# 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
 # Dialog
 
 - Import: @devalok/shilp-sutra/ui/dialog
@@ -1434,6 +1862,53 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 
 ### v0.1.0
 - **Added** Initial release
+# 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`.
 # IconButton
 
 - Import: @devalok/shilp-sutra/ui/icon-button
@@ -1441,12 +1916,12 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 - 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
 
@@ -1456,17 +1931,98 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 
 ## 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
+# 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
+# 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
 # Input
 
 - Import: @devalok/shilp-sutra/ui/input
@@ -1474,10 +2030,17 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 - 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
@@ -1488,17 +2051,36 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 
 ## 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
@@ -1835,6 +2417,7 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
     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
 
@@ -1850,8 +2433,12 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 
 ## 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
 # ProgressRing
@@ -2362,6 +2949,9 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 - 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'
@@ -2565,16 +3155,29 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
     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
@@ -3108,6 +3711,7 @@ export default function RootLayout({ children }) {
     maxInitialItems: number — truncate with "Show all (N)" toggle
     groupBy?: 'time' | 'none' — group items by time buckets (today, yesterday, this week, older)
     groupLabels?: GroupLabels — custom labels for time groups: { today?, yesterday?, thisWeek?, older? }
+    renderItem?: (item: ActivityItem, index: number) => ReactNode | undefined — custom renderer per item; return undefined to fall back to default ActivityEntry
 
 ## Defaults
     loading=false, compact=false, hasMore=false, groupBy='none'
@@ -3135,8 +3739,14 @@ export default function RootLayout({ children }) {
 - `maxInitialItems` truncates with a "Show all (N)" toggle button
 - `maxInitialItems` applies to the flat list BEFORE grouping — items are sliced first, then grouped
 - Empty time groups are automatically skipped
+- `renderItem` receives the item and index; return `undefined` to use the default ActivityEntry rendering
+- Custom `renderItem` content is wrapped in the same dot + layout container as default entries for consistent vertical rhythm
 
 ## Changes
+### v0.29.0
+- **Added** `renderItem` prop — custom render function per item; return ReactNode for custom rendering, return `undefined` to fall back to default ActivityEntry
+- **Added** Internal `CustomEntry` wrapper that keeps dot + layout consistent with default entries
+
 ### v0.20.0
 - **Added** `groupBy="time"` prop — groups items into Today, Yesterday, This Week, Older with section headers
 - **Added** `groupLabels` prop for custom group label text
@@ -3158,7 +3768,7 @@ export default function RootLayout({ children }) {
     max: number (default: 4, overflow shows "+N" badge)
     size: "xs" | "sm" | "md" | "lg" | "xl"
     showTooltip: boolean (default: true)
-    borderColor: "surface-1" | "surface-2" (default: "surface-2") — overlap border color
+    borderColor: "surface-base" | "surface-raised" (default: "surface-raised") — overlap border color
     onOverflowClick: () => void — makes the "+N" badge interactive (button)
     renderAvatar: (user: AvatarUser, index: number) => ReactNode — custom avatar render
     expandDirection: "left" | "right" (default: "right") — direction group expands on hover
@@ -3168,9 +3778,10 @@ export default function RootLayout({ children }) {
     name: string (REQUIRED)
     image?: string | null
     ring?: "none" | "lead" | "admin" | "client" — role ring per user in group
+    indicator?: "lead" | "admin" | ReactNode — small dot indicator at top-right of avatar
 
 ## Defaults
-    size="md", max=4, showTooltip=true, borderColor="surface-2", expandDirection="right", expandAmount="default"
+    size="md", max=4, showTooltip=true, borderColor="surface-raised", expandDirection="right", expandAmount="default"
 
 ## Example
 ```jsx
@@ -3181,7 +3792,7 @@ export default function RootLayout({ children }) {
   ]}
   max={3}
   size="md"
-  borderColor="surface-1"
+  borderColor="surface-base"
   onOverflowClick={() => setShowAll(true)}
 />
 ```
@@ -3191,10 +3802,13 @@ export default function RootLayout({ children }) {
 - Users beyond `max` are collapsed into a "+N" overflow badge
 - Missing `image` falls back to initials derived from `name`
 - Hover expand animation uses CSS `group-hover` — parent must not clip overflow
-- `borderColor` should match the surface context the group sits on (e.g., `surface-1` on cards)
+- `borderColor` should match the surface the group sits on (`surface-base` on page bg, `surface-raised` on cards)
 - `renderAvatar` wrapper is positioning-only — pass `size` directly to your Avatar (do NOT use `className="h-full w-full"`)
 
 ## Changes
+### v0.29.0
+- **Added** `indicator` prop on AvatarUser: `"lead"` (warning dot) | `"admin"` (accent dot) | ReactNode (custom indicator) — animated dot at the top-right corner of each avatar
+
 ### v0.22.3
 - **Fixed** `renderAvatar` wrapper no longer clips consumer Avatar content (removed overflow-hidden, border, and size classes from wrapper)
 - **Fixed** Removed redundant text-size classes from wrapper — Avatar handles font scaling internally
@@ -3203,7 +3817,6 @@ export default function RootLayout({ children }) {
 - **Added** `xs` and `xl` size variants
 - **Added** `borderColor` prop for overlap border matching surface context
 - **Added** `onOverflowClick` prop making the overflow badge an interactive button
-- **Added** `overflowContent` prop for popover content on overflow click
 - **Added** `renderAvatar` prop for custom per-avatar rendering
 - **Added** `AvatarUser.ring` field for per-user role rings in groups
 
@@ -4225,8 +4838,11 @@ Exports: RichTextEditor, RichTextViewer
     onFileUpload?: (file: File) => Promise<{ url: string; name: string; size: number }> — enables file attachments
     mentions?: MentionItem[] — static list for @mention autocomplete
     onMentionSearch?: (query: string) => Promise<MentionItem[]> — async search, takes precedence over static mentions
+    toolbar?: ToolbarItem[] — whitelist of toolbar items to show. Omit to show all.
     onMentionSelect?: (item: MentionItem) => void — called when a mention is selected
 
+ToolbarItem: 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'h2' | 'h3' | 'blockquote' | 'bulletList' | 'orderedList' | 'taskList' | 'codeBlock' | 'link' | 'image' | 'file' | 'hr' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'emoji' | 'undo' | 'redo'
+
 MentionItem: { id: string; label: string; avatar?: string }
 
 ### RichTextViewer
@@ -4259,6 +4875,9 @@ MentionItem: { id: string; label: string; avatar?: string }
 - Features: bold, italic, underline, strikethrough, highlight, headings, blockquote, lists, task lists, code, links, images, file attachments, mentions, emoji, text alignment, horizontal rule
 
 ## Changes
+### v0.30.0
+- **Added** `toolbar` prop — whitelist of `ToolbarItem` names to control which toolbar buttons appear. Dividers render only between groups that have visible items. `ToolbarItem` type exported from barrel.
+
 ### v0.18.0
 - **Fixed** Use ref to track internal changes, prevent update loop
 
@@ -4357,11 +4976,13 @@ Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
 Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe due to Framer Motion dependency.
 
 ## Props
-    status: "active" | "pending" | "approved" | "rejected" | "completed" | "blocked" | "cancelled" | "draft"
+    status: "active" | "pending" | "approved" | "rejected" | "completed" | "blocked" | "in-progress" | "review" | "cancelled" | "draft"
     color: "success" | "warning" | "error" | "info" | "neutral" (overrides status styling when set)
     size: "sm" | "md"
     label: string (auto-derived from status/color if omitted)
     hideDot: boolean (default: false)
+    onClick: () => void (makes badge clickable — renders as button with chevron)
+    icon: ReactNode (custom trailing icon — replaces default chevron when clickable)
 
 ## Defaults
     size="md", hideDot=false
@@ -4370,15 +4991,26 @@ Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe
 ## Example
 ```jsx
 <StatusBadge status="active" />
+<StatusBadge status="in-progress" />
+<StatusBadge status="review" label="Needs Review" />
 <StatusBadge color="warning" label="In Review" size="sm" />
+<StatusBadge status="active" onClick={() => openStatusPicker()} />
 ```
 
 ## Gotchas
 - When `color` is set, it takes priority over `status` for styling
 - Props use a discriminated union — pass either `status` or `color`, not both
 - As of v0.18.0, StatusBadge is NOT server-safe (Framer Motion dependency)
+- When `onClick` is provided, badge renders as a `<button>` with a trailing chevron icon
+- Pass `icon` to replace the default chevron with a custom trailing icon
 
 ## Changes
+### v0.29.0
+- **Added** `in-progress` status (accent/blue styling)
+- **Added** `review` status (info styling)
+- **Added** `onClick` prop — renders as a `<button>` with trailing chevron and hover opacity
+- **Added** `icon` prop — custom trailing icon (replaces the default chevron when clickable)
+
 ### v0.18.0
 - **Changed** No longer server-safe due to Framer Motion dependency