@devalok/shilp-sutra 0.28.0 → 0.29.0

package/dist/ui/toggle.js

@@ -2,7 +2,7 @@
 import { jsx as i } from "react/jsx-runtime";
 import * as n from "react";
 import { aI as e } from "../_chunks/primitives.js";
-import { c as d } from "../_chunks/vendor-utils.js";
+import { a as d } from "../_chunks/vendor-utils.js";
 import { springs as m, motionProps as c } from "./lib/motion.js";
 import { cn as f } from "./lib/utils.js";
 import { m as l } from "../_chunks/framer.js";
@@ -25,14 +25,14 @@ const p = l.create(e), g = d(
       size: "md"
     }
   }
-), u = n.forwardRef(({ className: t, variant: s, size: o, ...r }, a) => /* @__PURE__ */ i(
+), u = n.forwardRef(({ className: t, variant: s, size: o, ...a }, r) => /* @__PURE__ */ i(
   p,
   {
-    ref: a,
+    ref: r,
     whileTap: { scale: 0.95 },
     transition: m.snappy,
     className: f(g({ variant: s, size: o }), t),
-    ...c(r)
+    ...c(a)
   }
 ));
 u.displayName = e.displayName;

package/dist/ui/tooltip.js

@@ -1,69 +1,69 @@
 "use client";
-import { jsx as t, Fragment as y } from "react/jsx-runtime";
+import { jsx as e, Fragment as h } from "react/jsx-runtime";
 import * as o from "react";
-import { aL as P, aM as p, aN as h, aO as u, aP as T } from "../_chunks/primitives.js";
-import { cn as C } from "./lib/utils.js";
-import { tweens as g, springs as N } from "./lib/motion.js";
-import { A as b, m as w } from "../_chunks/framer.js";
+import { aL as y, aM as f, aN as C, aO as u, aP as g } from "../_chunks/primitives.js";
+import { cn as P } from "./lib/utils.js";
+import { tweens as T, springs as O } from "./lib/motion.js";
+import { A as N, m as b } from "../_chunks/framer.js";
 const d = o.createContext(!1), F = ({
-  children: e,
-  ...i
-}) => /* @__PURE__ */ t(d.Provider, { value: !0, children: /* @__PURE__ */ t(u, { ...i, children: e }) });
-function M({ children: e }) {
-  return o.useContext(d) ? /* @__PURE__ */ t(y, { children: e }) : /* @__PURE__ */ t(d.Provider, { value: !0, children: /* @__PURE__ */ t(u, { delayDuration: 300, children: e }) });
+  children: t,
+  ...r
+}) => /* @__PURE__ */ e(d.Provider, { value: !0, children: /* @__PURE__ */ e(u, { ...r, children: t }) });
+function w({ children: t }) {
+  return o.useContext(d) ? /* @__PURE__ */ e(h, { children: t }) : /* @__PURE__ */ e(d.Provider, { value: !0, children: /* @__PURE__ */ e(u, { delayDuration: 300, children: t }) });
 }
-const m = o.createContext({ open: !1 }), A = ({
-  open: e,
-  defaultOpen: i,
-  onOpenChange: r,
-  ...n
+const m = o.createContext({ open: !1 }), M = ({
+  open: t,
+  defaultOpen: r,
+  onOpenChange: i,
+  ...a
 }) => {
-  const [l, c] = o.useState(i ?? !1), a = e !== void 0, s = a ? e : l, v = o.useCallback(
-    (f) => {
-      a || c(f), r == null || r(f);
+  const [l, c] = o.useState(r ?? !1), s = t !== void 0, n = s ? t : l, v = o.useCallback(
+    (p) => {
+      s || c(p), i?.(p);
     },
-    [a, r]
-  ), x = o.useMemo(() => ({ open: s }), [s]);
-  return /* @__PURE__ */ t(M, { children: /* @__PURE__ */ t(m.Provider, { value: x, children: /* @__PURE__ */ t(T, { open: s, onOpenChange: v, ...n }) }) });
+    [s, i]
+  ), x = o.useMemo(() => ({ open: n }), [n]);
+  return /* @__PURE__ */ e(w, { children: /* @__PURE__ */ e(m.Provider, { value: x, children: /* @__PURE__ */ e(g, { open: n, onOpenChange: v, ...a }) }) });
 };
-A.displayName = "Tooltip";
-const L = h, R = {
+M.displayName = "Tooltip";
+const L = C, A = {
   top: { y: 4 },
   bottom: { y: -4 },
   left: { x: 4 },
   right: { x: -4 }
-}, I = o.forwardRef(({ className: e, sideOffset: i = 4, side: r = "top", children: n, ...l }, c) => {
-  const { open: a } = o.useContext(m), s = R[r] ?? {};
-  return /* @__PURE__ */ t(b, { children: a && /* @__PURE__ */ t(P, { forceMount: !0, children: /* @__PURE__ */ t(
-    p,
+}, R = o.forwardRef(({ className: t, sideOffset: r = 4, side: i = "top", children: a, ...l }, c) => {
+  const { open: s } = o.useContext(m), n = A[i] ?? {};
+  return /* @__PURE__ */ e(N, { children: s && /* @__PURE__ */ e(y, { forceMount: !0, children: /* @__PURE__ */ e(
+    f,
     {
       ref: c,
       forceMount: !0,
-      sideOffset: i,
-      side: r,
+      sideOffset: r,
+      side: i,
       ...l,
       asChild: !0,
-      children: /* @__PURE__ */ t(
-        w.div,
+      children: /* @__PURE__ */ e(
+        b.div,
         {
-          initial: { opacity: 0, scale: 0.95, ...s },
+          initial: { opacity: 0, scale: 0.95, ...n },
           animate: { opacity: 1, scale: 1, x: 0, y: 0 },
-          exit: { opacity: 0, scale: 0.95, ...s },
-          transition: { ...N.snappy, opacity: g.fade },
-          className: C(
+          exit: { opacity: 0, scale: 0.95, ...n },
+          transition: { ...O.snappy, opacity: T.fade },
+          className: P(
             "z-tooltip overflow-hidden rounded-ds-md bg-surface-inverted px-ds-04 py-ds-02b text-ds-sm text-surface-inverted-fg shadow-floating",
-            e
+            t
           ),
-          children: n
+          children: a
         }
       )
     }
   ) }) });
 });
-I.displayName = p.displayName;
+R.displayName = f.displayName;
 export {
-  A as Tooltip,
-  I as TooltipContent,
+  M as Tooltip,
+  R as TooltipContent,
   F as TooltipProvider,
   L as TooltipTrigger
 };

package/dist/ui/tree-view/tree-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree-item.d.ts","sourceRoot":"","sources":["../../../src/ui/tree-view/tree-item.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAM9B,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,4BAA4B;IAC5B,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,uDAAuD;IACvD,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAChC,oDAAoD;IACpD,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,QAAA,MAAM,QAAQ,qFAoMb,CAAA;AAGD,OAAO,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"tree-item.d.ts","sourceRoot":"","sources":["../../../src/ui/tree-view/tree-item.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAO9B,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,4BAA4B;IAC5B,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,uDAAuD;IACvD,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAChC,oDAAoD;IACpD,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,QAAA,MAAM,QAAQ,qFAqMb,CAAA;AAGD,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/docs/components/_header.md

@@ -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
 

package/docs/components/composed/activity-feed.md

@@ -14,6 +14,7 @@
     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'
@@ -41,8 +42,14 @@
 - `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

package/docs/components/composed/avatar-group.md

@@ -9,7 +9,7 @@
     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
@@ -19,9 +19,10 @@
     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
@@ -32,7 +33,7 @@
   ]}
   max={3}
   size="md"
-  borderColor="surface-1"
+  borderColor="surface-base"
   onOverflowClick={() => setShowAll(true)}
 />
 ```
@@ -42,10 +43,13 @@
 - 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
@@ -54,7 +58,6 @@
 - **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
 

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

@@ -7,11 +7,13 @@
 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
@@ -20,15 +22,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
 

package/docs/components/ui/accordion.md

@@ -14,11 +14,11 @@
 ## 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
@@ -35,6 +35,9 @@
 - 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)
 

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

@@ -0,0 +1,38 @@
+# 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

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

@@ -0,0 +1,40 @@
+# 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

package/docs/components/ui/badge.md

@@ -5,13 +5,25 @@
 - 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"
 
@@ -19,13 +31,32 @@
 ```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`

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

@@ -0,0 +1,15 @@
+# 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.

package/docs/components/ui/button.md

@@ -5,37 +5,66 @@
 - 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]`.