@devalok/shilp-sutra 0.28.0 → 0.30.0

package/llms.txt

@@ -4,6 +4,13 @@
 > Built on the same primitives as shadcn/ui but with key API differences.
 > Read this file BEFORE writing any UI code. Do NOT guess from shadcn/ui knowledge.
 
+## CHANGES (v0.30.0)
+- **RichTextEditor `toolbar` prop** — `toolbar?: ToolbarItem[]` whitelist of toolbar items to display. Omit to show all (default). `ToolbarItem` type exported.
+- **`@devalok/shilp-sutra-karm` removed** — Domain components moved to Karm app repo. npm package deprecated.
+- **Warning dark mode fixed** — `warning-*` tokens now have proper dark mode values (higher chroma than category amber).
+- **tailwind-merge fix** — All `text-ds-*` sizes now correctly registered. `cn('text-ds-lg', 'text-accent-11')` no longer strips the color.
+- **AvatarGroup fixes** — Overflow badge text matches avatar size, indicator dots scale with size, aria-labels added.
+
 ## BREAKING CHANGES (v0.27.0 — Externalized Dependencies)
 
 FilePreview and MarkdownViewer dependencies are now **external** (not bundled).
@@ -101,12 +108,11 @@ Same pattern for `border-surface-*`, `text-surface-*`, `ring-surface-*`.
 
 **Server safety changes:** EmptyState, StatusBadge, Spinner are NO LONGER server-safe (they now use Framer Motion). Remove from RSC imports.
 
-**Build:** `framer-motion` and `sonner` moved from `dependencies` to `devDependencies` (bundled at build time — no consumer install needed for core, but karm consumers must install `framer-motion` as peer dep).
+**Build:** `framer-motion` and `sonner` moved from `dependencies` to `devDependencies` (bundled at build time — no consumer install needed for core).
 
 **New APIs in v0.18.0:**
 - Combobox: `accessibleLabel?: string` — custom aria-label for trigger (falls back to placeholder)
 - Slider: multi-thumb support — pass array `defaultValue={[25, 75]}` for range sliders
-- StreamingText (karm): `isComplete?: boolean` — debounces aria-live, announces only on completion
 
 ## CHANGES (v0.16.0)
 - **DataTable server-side features**: `onSort` callback (manual sorting), `pagination` prop (server-side pagination with page/total/onPageChange), `selectedIds` + `selectableFilter` (controlled selection), `loading` shimmer, `emptyState` ReactNode, `singleExpand`, `stickyHeader`, `onRowClick`, `bulkActions` floating bar
@@ -243,7 +249,7 @@ pnpm add @devalok/shilp-sutra
 
 Add to next.config.js:
 ```js
-transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-karm", "@devalok/shilp-sutra-brand"]
+transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]
 ```
 
 // Import components (barrel):
@@ -254,6 +260,9 @@ import { Button } from '@devalok/shilp-sutra/ui/button'
 import { PageHeader } from '@devalok/shilp-sutra/composed/page-header'
 import { TopBar } from '@devalok/shilp-sutra/shell/top-bar'
 
+// Chat primitives (v0.29.0+):
+import { MessageList, Message, SystemMessage, MessageInput, DateSeparator, UnreadSeparator, TypingIndicator } from '@devalok/shilp-sutra/ui/chat'
+
 // AI command system (v0.25.0+):
 import { CommandBar, AIConversation, BlockRenderer, AICommandProvider, DevadootIcon } from '@devalok/shilp-sutra/ai'
 
@@ -278,7 +287,7 @@ If you have shadcn/ui knowledge, these are the differences that WILL trip you up
 | variant="destructive" | color="error" | Two-axis system: variant=shape, color=intent |
 | size="default" | size="md" | All sizes: sm, md, lg (never "default") |
 | <Select size="lg"> | <SelectTrigger size="lg"> | Size goes on trigger, NOT root |
-| <Chip>text</Chip> | <Chip label="text" /> | Chip uses label prop, NOT children |
+| <Chip> | <Badge onClick={...}> | Chip is deprecated, use Badge with onClick |
 | useToast() + toast({ variant }) | toast.success('msg') | Imperative API, no hook needed |
 | Badge variant="destructive" | Badge variant="solid" color="error" | Two-axis: variant + color |
 | Alert + AlertTitle + AlertDescription | <Alert title="..." color="error"> | Single component, not compound |
@@ -292,25 +301,27 @@ Many components use TWO props where shadcn uses one:
 - `color` controls INTENT/SEMANTICS: default, error, success, warning, info, etc.
 
 Examples:
-  <Button variant="solid" color="error">Delete</Button>     // red solid button
-  <Button variant="outline" color="error">Cancel</Button>    // red outline button
-  <Badge variant="solid" color="success">Active</Badge>      // green solid badge
-  <Alert variant="filled" color="warning">Warning!</Alert>   // yellow filled alert
+  <Button variant="solid" color="error">Delete</Button>       // red solid button
+  <Button variant="soft" color="warning">Pending</Button>     // amber tinted button
+  <Button variant="outline" color="success">Approve</Button>  // green outline button
+  <Badge variant="solid" color="success">Active</Badge>       // green solid badge
+  <Alert variant="filled" color="warning">Warning!</Alert>    // amber filled alert
 
-Components with two-axis system: Button, Badge, Alert, Chip, Banner, Progress, StatusBadge
+Components with two-axis system: Button, Badge, Alert, Banner, Progress, StatusBadge
 
 ## Component Quick Reference
 
 ### Inputs & Controls
-- Button: variant(solid|default|outline|ghost|link) color(default|error) size(xs|sm|md|lg|icon-xs|icon-sm|icon-md|icon-lg) + loading, startIcon, endIcon, asChild
+- Button: variant(solid|soft|outline|ghost|link) color(accent|error|success|warning|neutral) size(xs|sm|md|lg|compact-xs|compact-sm|compact-md|icon-xs|icon-sm|icon-md|icon-lg) shape(default|pill) weight(semibold|normal) + loading, startIcon, endIcon, asChild, processing?('ambient'|'working'|'urgent'|boolean — marching ants SVG border, forces soft variant), processingColor?('accent'|'error'|'success'|'warning'|'neutral'), processingDisabled?(boolean, default true — set false for cancel-by-click). onClickAsync auto-activates processing='working' during loading phase. Layout animation always on. Deprecated aliases still work: variant="default"→solid, variant="destructive"→solid+error, color="default"→accent
 - IconButton: icon(ReactNode, required) shape(square|circle) size(sm|md|lg) + aria-label required
-- Input: size(xs|sm|md|lg) state(InputState) + startIcon, endIcon. Type: InputState = 'default' | 'error' | 'warning' | 'success'
-- SearchInput: size(xs|sm|md|lg) + loading, onClear
+- Icon: `<Icon icon={IconPlus} />` — context-aware wrapper for Tabler icons. Size tiers: xs(14px) sm(16px) md(18px) lg(20px) xl(24px) 2xl(32px). Default: md. Stroke: light(1.5) regular(2) bold(2.5). Default: regular. Scales per size tier. Reads size from parent Button/IconGroup via IconContext. Explicit props override. Accessibility: aria-hidden by default. Pass label="Add item" for accessible icons. Animation: animate="spin|pulse|bounce|draw". `draw` renders SVG path-draw animation (check/X icons draw progressively via pathLength; other icons fall back to static). State machine: state="idle|loading|success|error". Button integration: startIcon={<Icon icon={IconPlus} />} (NOT raw <IconPlus />). IconGroup: <IconGroup size="sm" gap="tight"> for toolbar patterns.
+- Input: size(xs|sm|md|lg) state(InputState) + startSection(ReactNode), endSection(ReactNode), startSectionClickable(bool), endSectionClickable(bool), startSectionType('icon'|'label'), endSectionType('icon'|'label'), wrapperClassName(string). Container-level focus ring wraps input + sections as one unit. Sections are pointer-events-none by default; use *SectionClickable for interactive content (clear buttons, toggles). Section type auto-inferred: strings→'label' (tinted bg + border separator), React elements→'icon' (fixed-width centered). Override with *SectionType. Flexbox section layout. Icons auto-size via IconProvider per input size. className targets <input>, wrapperClassName targets wrapper div. Deprecated aliases: startIcon→startSection, endIcon→endSection, inputVariants→inputWrapperVariants. Type: InputState = 'default' | 'error' | 'warning' | 'success'
+- SearchInput: size(xs|sm|md|lg) + loading, onClear. Delegates to Input v2 sections internally.
 - NumberInput: value + onValueChange, min, max, step (controlled only)
 - Textarea: size(xs|sm|md|lg) state(default|error|warning|success)
 - ColorInput: value(hex string) onChange(value) presets({hex,label}[]|string[]|false, default: 10 named colors) variant('default'|'inline') showPicker(boolean, default:true) defaultFormat('hex'|'rgb'|'hsl') align('start'|'center'|'end') disabled. Popover trigger opens interactive picker (react-colorful) + format switcher + preset swatches + undo/reset. Inline variant renders entire trigger as the color with contrast-aware text.
 - Checkbox: checked, onCheckedChange, error(boolean), indeterminate(boolean)
-- Switch: checked, onCheckedChange, error(boolean)
+- Switch: checked, onCheckedChange, error(boolean), size(sm|md|lg), color(accent|success|warning), thumbIcon(ReactNode)
 - RadioGroup > RadioGroupItem(value)
 - Select > SelectTrigger(size: xs|sm|md|lg) > SelectValue; SelectContent > SelectItem(value)
 - Toggle: variant(default|outline) size(sm|md|lg)
@@ -323,7 +334,7 @@ Components with two-axis system: Button, Badge, Alert, Chip, Banner, Progress, S
 - Banner: color(info|success|warning|error|neutral) + actions?(ReactNode), onDismiss. `action` (singular) deprecated, use `actions`. Mobile flex-wrap for multiple buttons.
 - Toast: imperative API via toast.success/error/warning/info/loading/message/undo/promise/upload/custom — REQUIRES <Toaster> at layout root
 - Spinner: size(sm|md|lg) — renders with role="status"
-- Progress: track size(sm|md|lg), indicator color(default|success|warning|error)
+- Progress: track size(sm|md|lg), indicator color(default|success|warning|error), autoColor(boolean, auto-shifts color by value: 0-59=default, 60-84=warning, 85-100=success, >100=error)
 
 NOTIFICATION SELECTION GUIDE:
   - Alert: inline contextual feedback within a form or page section
@@ -331,8 +342,8 @@ NOTIFICATION SELECTION GUIDE:
   - Toast: transient notification triggered by user action (needs <Toaster>, then call toast.success() etc.)
 
 ### Data Display
-- Badge: variant(subtle|solid|outline) color(default|info|success|error|warning|brand|accent + 7 category colors) size(xs|sm|md|lg) + onDismiss
-- Chip: variant(subtle|outline) color(default|primary|success|error|warning|info + 7 category) size(sm|md|lg) label(string, REQUIRED) + onDismiss, onClick
+- Badge: variant(subtle|solid|outline|soft) color(default|accent|error|success|warning|info|neutral + 7 category colors + custom) size(xs|sm|md|lg) + onClick, onDismiss, selected, disabled, dot, startIcon, endIcon, maxWidth, circle, asChild. Compound: Badge.Indicator(count, max, dot, color, invisible, showZero, placement, children), Badge.Group(max, gap, size, onOverflowClick, children). Custom colors: color="custom" + style={{'--badge-color':'#hex'}}. Grain-ready (has relative/overflow-hidden/isolate).
+- Chip: DEPRECATED — Use `<Badge onClick={...}>` instead. Chip wrapper maps label prop to children for backward compat.
 - Avatar: size(xs|sm|md|lg|xl) shape(circle|square|rounded) status?(AvatarStatus) ring?('lead'|'admin'|'client') badge?(number|'dot'|ReactNode) loading?(boolean) > AvatarImage + AvatarFallback(colorSeed?). Types: AvatarStatus = 'online'|'offline'|'busy'|'away', AvatarRing = 'none'|'lead'|'admin'|'client'. Fallback colors are deterministic from name hash (8 categorical). Online dot pulses. Badge pops in with MotionPop.
 - Card: variant(default|elevated|outline|flat) interactive(boolean) accent?(left|top|right|bottom) accentColor?(default|secondary|error|success|warning|info) > CardHeader > CardTitle, CardDescription; CardContent; CardFooter
 - Table > TableHeader > TableRow > TableHead; TableBody > TableRow > TableCell; TableFooter; TableCaption
@@ -343,6 +354,17 @@ NOTIFICATION SELECTION GUIDE:
 - ColorSwatch: color(CSS string) size(sm|md|lg) shape(circle|square|rounded) ring(boolean) — for dynamic runtime colors
 - StatusDot: status(healthy|warning|critical|neutral|inactive) size(sm|md|lg) pulse?(boolean, default true for healthy) label?(string)
 - ProgressRing: value(number) max?(100) size(sm|md|lg) color(default|success|warning|error|info) showValue?(boolean) label?(string). Also: MultiProgressRing for concentric Activity Ring style
+- DevalokGrain: Brand texture overlay — drop inside any element with `relative overflow-hidden isolate`. Props: intensity('subtle'|'medium'|'heavy'), surface('solid'|'soft'), sheen(boolean, inner highlight), animated(boolean, fade-in on mount), hoverIntensify(boolean, parent needs `group` class), tint(CSS color string for directional gradient). No gradient rendered without tint.
+
+### Chat Primitives (ui/chat/)
+Import: `@devalok/shilp-sutra/ui/chat`
+- MessageList: children, autoScroll?(true), newMessageCount?(number, shows floating "N new" pill), onScrollToBottom?(), onLoadMore?(), isLoadingMore?(boolean), emptySlot?(ReactNode), headerSlot?(ReactNode). role="log" aria-live="polite".
+- Message: COMPOUND — variant('flat'|'bubble') placement('start'|'end') highlight?('mention'|'internal') grouped?(boolean) deleted?(boolean) deletedText?(string). Sub-parts: Message.Avatar(src?, fallback?, icon?, size?('sm'|'md')), Message.Content, Message.Author(name, badge?, timestamp?, formattedTimestamp?, timestampFormat?), Message.Body, Message.EditableBody(content, onSave, onCancel?, canEdit?, renderContent?), Message.Reactions(reactions[{emoji,count,reacted}], onReact), Message.Actions(children, delay?), Message.Action(icon, label, onClick, variant?('default'|'danger'))
+- SystemMessage: variant('event'|'alert') icon?(ReactNode) timestamp?(string) children
+- MessageInput: onSubmit(text=>void), placeholder?, disabled?, isStreaming?(boolean, shows stop button), onCancel?(), leadingSlot?, trailingSlot?, disclaimer?(string), sendIcon?(ReactNode). Enter to send, Shift+Enter for newline.
+- DateSeparator: date(Date|string), format?((date)=>string). Shows "Today", "Yesterday", or "Mar 15".
+- UnreadSeparator: label?('NEW'), count?(number). Accent-colored horizontal rule.
+- TypingIndicator: users({name, image?}[]). Shows animated bouncing dots + "Alice is typing..." / "Alice and Bob are typing..." / "Several people are typing..."
 
 ### Overlays
 - Dialog > DialogTrigger; DialogContent > DialogHeader > DialogTitle, DialogDescription; [content]; DialogFooter
@@ -355,7 +377,7 @@ NOTIFICATION SELECTION GUIDE:
 
 ### Navigation
 - Tabs > TabsList(variant: line|contained) > TabsTrigger(value); TabsContent(value) — variant propagates via context
-- Accordion(type: single|multiple) > AccordionItem(value) > AccordionTrigger; AccordionContent
+- Accordion(type: single|multiple) > AccordionItem(value) > AccordionTrigger(chevronPosition?: 'left'|'right', default 'right'); AccordionContent
 - Breadcrumb > BreadcrumbList > BreadcrumbItem > BreadcrumbLink | BreadcrumbPage; BreadcrumbSeparator
 - PaginationRoot > PaginationContent > PaginationItem > PaginationLink(isActive) | PaginationPrevious | PaginationNext | PaginationEllipsis
 - DropdownMenu > DropdownMenuTrigger; DropdownMenuContent > DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuCheckboxItem, DropdownMenuRadioGroup > DropdownMenuRadioItem
@@ -378,8 +400,8 @@ NOTIFICATION SELECTION GUIDE:
 ### Composed Components
 - ConfirmDialog: open, onOpenChange, title, description, onConfirm + confirmText, cancelText, color(default|error), loading
 - PageHeader: title, subtitle, breadcrumbs[], actions(ReactNode)
-- AvatarGroup: users(AvatarUser[]), max?(number), size?(xs|sm|md|lg|xl), showTooltip?, borderColor?('surface-base'|'surface-raised'), onOverflowClick?(), renderAvatar?((user,index)=>ReactNode), expandDirection?('left'|'right'), expandAmount?('compact'|'default'|'wide'). Type: AvatarUser = { name, image?, ring? }. GPU-composited hover expand via translateX. Use expandDirection="left" for right-aligned groups.
-- StatusBadge: DISCRIMINATED UNION — pass status OR color, not both. status(active|pending|approved|rejected|completed|blocked|cancelled|draft) color(success|warning|error|info|neutral) size(sm|md)
+- AvatarGroup: users(AvatarUser[]), max?(number), size?(xs|sm|md|lg|xl), showTooltip?, borderColor?('surface-base'|'surface-raised'), onOverflowClick?(), renderAvatar?((user,index)=>ReactNode), expandDirection?('left'|'right'), expandAmount?('compact'|'default'|'wide'). Type: AvatarUser = { name, image?, ring?, indicator?('lead'|'admin'|ReactNode) }. GPU-composited hover expand via translateX. Use expandDirection="left" for right-aligned groups. indicator renders a small dot on avatar: 'lead'=warning-9, 'admin'=accent-9, or custom ReactNode.
+- StatusBadge: DISCRIMINATED UNION — pass status OR color, not both. status(active|pending|approved|rejected|completed|blocked|in-progress|review|cancelled|draft) color(success|warning|error|info|neutral) size(sm|md) onClick?(() => void, renders as button with auto chevron-down icon) icon?(ReactNode, custom trailing icon)
 - ContentCard: variant(default|outline|ghost) padding(default|compact|spacious|none)
 - EmptyState: icon(ReactNode or ComponentType), title(required), description, action(ReactNode), compact
 - PriorityIndicator: priority(Priority) display(compact|full). Type: Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'urgent'
@@ -394,7 +416,7 @@ NOTIFICATION SELECTION GUIDE:
 - (UploadProgress REMOVED — upload tracking is now built into toast.upload())
 - RichTextEditor: Tiptap editor — bold/italic/underline/strike/highlight, headings, blockquote, lists (bullet/ordered/task), code, links, images (paste/drop/upload), file attachments, @mentions, emoji picker + :shortcode:, text alignment, HR. Props: onImageUpload?, onFileUpload?, mentions?, onMentionSearch?, onMentionSelect?(item: MentionItem)
 - RichTextViewer: read-only renderer for RichTextEditor HTML content (renders all above content types)
-- ActivityFeed: items(ActivityItem[]), onLoadMore, loading, hasMore, emptyState, compact, maxInitialItems, groupBy?('time'|'none'), groupLabels?({ today, yesterday, thisWeek, older }). Type: ActivityItem = { id, actor?, action, timestamp, icon?, color?, detail? }. Utility: groupItemsByTime(items, labels) exported.
+- ActivityFeed: items(ActivityItem[]), onLoadMore, loading, hasMore, emptyState, compact, maxInitialItems, groupBy?('time'|'none'), groupLabels?({ today, yesterday, thisWeek, older }), renderItem?((item, index) => ReactNode|undefined, custom renderer per item — return ReactNode for custom, undefined for default). Type: ActivityItem = { id, actor?, action, timestamp, icon?, color?, detail? }. Utility: groupItemsByTime(items, labels) exported.
 - CommandPalette: open, defaultOpen, onOpenChange (controlled/uncontrolled), keybinding(string|string[]|false), maxHeight, emptyState(ReactNode), footerHints(FooterHint[]|false). CommandItem: label(string|ReactNode), description(string|ReactNode), renderLabel(query=>ReactNode), filterValue(string), shortcut(rendered as keycap badges). Keyboard shortcuts rendered per-key with platform-aware Cmd/Ctrl. Reduced-motion support via MotionProvider.
 - MemberPicker: thin wrapper around MultiSelectPopover with Avatar rendering
 - MultiSelectPopover: items/groups, value, onValueChange, searchPlaceholder, onSearch?(async), renderItem?, emptyMessage, maxSelections. Generic multi-select popover with search + checkmarks.
@@ -468,11 +490,14 @@ DO NOT use barrel imports in Server Components — they include "use client" com
 - DO NOT use variant="destructive" — use color="error"
 - DO NOT use size="default" — use size="md" (or sm, lg)
 - DO NOT put size on <Select> — put it on <SelectTrigger size="md">
-- DO NOT use <Chip>text</Chip> — use <Chip label="text" />
+- DO NOT use <Chip> — Chip is deprecated. Use <Badge onClick={...}> instead
 - DO NOT use useToast() hook — use import { toast } from '@devalok/shilp-sutra/ui/toast' (imperative)
 - DO NOT use toast({ title, color }) object syntax — use toast.success('message'), toast.error('message'), etc.
 - DO NOT call toast() without <Toaster /> mounted at your layout root
 - DO NOT use <Alert><AlertTitle>...</AlertTitle></Alert> — use <Alert title="..." />
 - DO NOT import from barrel in Next.js Server Components — use per-component imports
 - DO NOT use variant="secondary" on Button — use variant="outline" or variant="ghost"
+- DO NOT use variant="default" on Button — use variant="solid" (deprecated alias, still works)
+- DO NOT use variant="destructive" on Button — use variant="solid" color="error" (deprecated alias, still works)
+- DO NOT use color="default" on Button — use color="accent" (deprecated alias, still works)
 - DO NOT put variant on individual TabsTrigger — put it on TabsList (propagates via context)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Devalok Design System — tokens, components, and patterns for Next.js",
   "license": "MIT",
   "type": "module",
@@ -363,6 +363,11 @@
       "default": "./dist/ui/tree-view/index.js",
       "types": "./dist/ui/tree-view/index.d.ts"
     },
+    "./ui/chat": {
+      "import": "./dist/ui/chat/index.js",
+      "default": "./dist/ui/chat/index.js",
+      "types": "./dist/ui/chat/index.d.ts"
+    },
     "./composed": {
       "import": "./dist/composed/index.js",
       "default": "./dist/composed/index.js",
@@ -815,7 +820,7 @@
     "tailwind-merge": "^3.0.1"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   },
   "packageManager": "pnpm@10.0.0"
 }