@devalok/shilp-sutra 0.42.1 → 0.44.0

package/dist/ui/truncated-text.d.ts

@@ -0,0 +1,37 @@
+"use client";
+import * as React from 'react';
+type TruncateMode = 'end' | 'clamp' | 'middle';
+export interface TruncatedTextProps {
+    /** The full text. Always the accessible name, even when visually shortened. */
+    children: string;
+    /**
+     * `end` (default) single-line "…end"; `clamp` multi-line (`lines`); `middle`
+     * keeps both ends (filenames, emails) — `name…end.pdf`.
+     */
+    mode?: TruncateMode;
+    /** Lines for `mode="clamp"`. @default 2 */
+    lines?: number;
+    /** Element to render. @default 'span' */
+    as?: 'span' | 'p' | 'div';
+    /** Show the full text in a tooltip when (and only when) actually truncated. @default true */
+    tooltip?: boolean;
+    className?: string;
+    /** Override the full-text accessible name / tooltip (defaults to `children`). */
+    title?: string;
+}
+/**
+ * Text that truncates and recovers. CSS handles `end`/`clamp` (full text stays in the
+ * DOM, screen-reader safe); `middle` measures + JS-shortens but keeps the full string as
+ * the accessible name. A tooltip appears ONLY when the text is actually clipped.
+ *
+ * Note: for `end`/`middle` in a flex/grid row, the shrinking item still needs `min-w-0`
+ * (CSS gotcha) — apply it at the call site.
+ *
+ * @example
+ * <TruncatedText>{user.name}</TruncatedText>
+ * <TruncatedText mode="middle">{fileName}</TruncatedText>      // report…v2.pdf
+ * <TruncatedText mode="clamp" lines={2}>{description}</TruncatedText>
+ */
+export declare const TruncatedText: React.ForwardRefExoticComponent<TruncatedTextProps & React.RefAttributes<HTMLElement>>;
+export {};
+//# sourceMappingURL=truncated-text.d.ts.map

package/dist/ui/truncated-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncated-text.d.ts","sourceRoot":"","sources":["../../src/ui/truncated-text.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,KAAK,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE9C,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,KAAK,CAAA;IACzB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAYD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,wFA2FzB,CAAA"}

package/dist/ui/truncated-text.js

@@ -0,0 +1,53 @@
+"use client";
+import { cn as e } from "./lib/utils.js";
+import { Tooltip as t, TooltipContent as n, TooltipTrigger as r } from "./tooltip.js";
+import * as i from "react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+//#region src/ui/truncated-text.tsx
+function s(e, t, n = "…") {
+	if (t >= e.length || t < 2) return e;
+	let r = t - n.length, i = Math.ceil(r / 2), a = Math.floor(r / 2);
+	return e.slice(0, i) + n + (a > 0 ? e.slice(-a) : "");
+}
+var c = i.forwardRef(({ children: c, mode: l = "end", lines: u = 2, as: d = "span", tooltip: f = !0, className: p, title: m }, h) => {
+	let g = c, [_, v] = i.useState(!1), [y, b] = i.useState(g), x = i.useRef(null), S = /* @__PURE__ */ a(d, {
+		ref: i.useCallback((e) => {
+			if (typeof h == "function" ? h(e) : h && (h.current = e), x.current?.disconnect(), !e) return;
+			let t = () => {
+				if (l === "middle") {
+					if (e.textContent = g, e.clientWidth === 0 || e.scrollWidth <= e.clientWidth) {
+						b(g), v(!1);
+						return;
+					}
+					let t = 2, n = g.length, r = 2;
+					for (; t <= n;) {
+						let i = t + n >> 1;
+						e.textContent = s(g, i), e.scrollWidth <= e.clientWidth ? (r = i, t = i + 1) : n = i - 1;
+					}
+					b(s(g, r)), v(!0);
+				} else v(l === "clamp" ? e.scrollHeight > e.clientHeight + 1 : e.scrollWidth > e.clientWidth + 1);
+			};
+			t(), x.current = new ResizeObserver(t), x.current.observe(e);
+		}, [
+			g,
+			l,
+			u,
+			h
+		]),
+		className: e(l === "end" && "block truncate", l === "middle" && "block overflow-hidden whitespace-nowrap", l === "clamp" && "overflow-hidden", p),
+		style: l === "clamp" ? {
+			display: "-webkit-box",
+			WebkitBoxOrient: "vertical",
+			WebkitLineClamp: u
+		} : void 0,
+		"aria-label": _ ? m ?? g : void 0,
+		children: l === "middle" ? y : g
+	});
+	return f && _ ? /* @__PURE__ */ o(t, { children: [/* @__PURE__ */ a(r, {
+		asChild: !0,
+		children: S
+	}), /* @__PURE__ */ a(n, { children: m ?? g })] }) : S;
+});
+c.displayName = "TruncatedText";
+//#endregion
+export { c as TruncatedText };

package/dist/ui/truncated-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncated-text.js","names":[],"sources":["../../src/ui/truncated-text.tsx"],"sourcesContent":["'use client'\n\nimport * as React from 'react'\n\nimport { cn } from './lib/utils'\nimport { Tooltip, TooltipContent, TooltipTrigger } from './tooltip'\n\ntype TruncateMode = 'end' | 'clamp' | 'middle'\n\nexport interface TruncatedTextProps {\n  /** The full text. Always the accessible name, even when visually shortened. */\n  children: string\n  /**\n   * `end` (default) single-line \"…end\"; `clamp` multi-line (`lines`); `middle`\n   * keeps both ends (filenames, emails) — `name…end.pdf`.\n   */\n  mode?: TruncateMode\n  /** Lines for `mode=\"clamp\"`. @default 2 */\n  lines?: number\n  /** Element to render. @default 'span' */\n  as?: 'span' | 'p' | 'div'\n  /** Show the full text in a tooltip when (and only when) actually truncated. @default true */\n  tooltip?: boolean\n  className?: string\n  /** Override the full-text accessible name / tooltip (defaults to `children`). */\n  title?: string\n}\n\n/** Keep `keep` chars total, ellipsis in the middle. */\nfunction truncateMiddle(str: string, keep: number, ellipsis = '…'): string {\n  if (keep >= str.length || keep < 2) return str\n  const budget = keep - ellipsis.length\n  const head = Math.ceil(budget / 2)\n  const tail = Math.floor(budget / 2)\n  // slice(-0) returns the whole string, so guard the tail explicitly.\n  return str.slice(0, head) + ellipsis + (tail > 0 ? str.slice(-tail) : '')\n}\n\n/**\n * Text that truncates and recovers. CSS handles `end`/`clamp` (full text stays in the\n * DOM, screen-reader safe); `middle` measures + JS-shortens but keeps the full string as\n * the accessible name. A tooltip appears ONLY when the text is actually clipped.\n *\n * Note: for `end`/`middle` in a flex/grid row, the shrinking item still needs `min-w-0`\n * (CSS gotcha) — apply it at the call site.\n *\n * @example\n * <TruncatedText>{user.name}</TruncatedText>\n * <TruncatedText mode=\"middle\">{fileName}</TruncatedText>      // report…v2.pdf\n * <TruncatedText mode=\"clamp\" lines={2}>{description}</TruncatedText>\n */\nexport const TruncatedText = React.forwardRef<HTMLElement, TruncatedTextProps>(\n  ({ children, mode = 'end', lines = 2, as = 'span', tooltip = true, className, title }, forwardedRef) => {\n    const full = children\n    const [overflowing, setOverflowing] = React.useState(false)\n    const [display, setDisplay] = React.useState(full)\n    const roRef = React.useRef<ResizeObserver | null>(null)\n\n    // Callback ref owns the ResizeObserver so it always tracks the CURRENT node.\n    // Wrapping in a Tooltip remounts the element when `overflowing` flips — a one-shot\n    // layout effect would leave a stale observer on the detached node (which then fires\n    // with size 0 and resets the measurement). Reconnecting here avoids that loop.\n    const attachRef = React.useCallback(\n      (node: HTMLElement | null) => {\n        if (typeof forwardedRef === 'function') forwardedRef(node)\n        else if (forwardedRef) (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = node\n\n        roRef.current?.disconnect()\n        if (!node) return\n\n        const measure = () => {\n          if (mode === 'middle') {\n            node.textContent = full\n            if (node.clientWidth === 0 || node.scrollWidth <= node.clientWidth) {\n              setDisplay(full)\n              setOverflowing(false)\n              return\n            }\n            // Largest middle-truncated string that fits, via binary search.\n            let lo = 2\n            let hi = full.length\n            let best = 2\n            while (lo <= hi) {\n              const midKeep = (lo + hi) >> 1\n              node.textContent = truncateMiddle(full, midKeep)\n              if (node.scrollWidth <= node.clientWidth) {\n                best = midKeep\n                lo = midKeep + 1\n              } else {\n                hi = midKeep - 1\n              }\n            }\n            setDisplay(truncateMiddle(full, best))\n            setOverflowing(true)\n          } else if (mode === 'clamp') {\n            setOverflowing(node.scrollHeight > node.clientHeight + 1)\n          } else {\n            setOverflowing(node.scrollWidth > node.clientWidth + 1)\n          }\n        }\n\n        measure()\n        roRef.current = new ResizeObserver(measure)\n        roRef.current.observe(node)\n      },\n      // eslint-disable-next-line react-hooks/exhaustive-deps\n      [full, mode, lines, forwardedRef],\n    )\n\n    const Tag = as as React.ElementType\n    const content = (\n      <Tag\n        ref={attachRef}\n        className={cn(\n          mode === 'end' && 'block truncate',\n          mode === 'middle' && 'block overflow-hidden whitespace-nowrap',\n          mode === 'clamp' && 'overflow-hidden',\n          className,\n        )}\n        style={\n          mode === 'clamp'\n            ? ({ display: '-webkit-box', WebkitBoxOrient: 'vertical', WebkitLineClamp: lines } as React.CSSProperties)\n            : undefined\n        }\n        // When clipped, the visible text may be shortened (middle mode) — keep the full\n        // string as the accessible name so screen readers always read it in full.\n        aria-label={overflowing ? (title ?? full) : undefined}\n      >\n        {mode === 'middle' ? display : full}\n      </Tag>\n    )\n\n    if (tooltip && overflowing) {\n      return (\n        <Tooltip>\n          <TooltipTrigger asChild>{content}</TooltipTrigger>\n          <TooltipContent>{title ?? full}</TooltipContent>\n        </Tooltip>\n      )\n    }\n    return content\n  },\n)\nTruncatedText.displayName = 'TruncatedText'\n"],"mappings":";;;;;;AA6BA,SAAS,EAAe,GAAa,GAAc,IAAW,KAAa;AACzE,KAAI,KAAQ,EAAI,UAAU,IAAO,EAAG,QAAO;CAC3C,IAAM,IAAS,IAAO,EAAS,QACzB,IAAO,KAAK,KAAK,IAAS,EAAE,EAC5B,IAAO,KAAK,MAAM,IAAS,EAAE;AAEnC,QAAO,EAAI,MAAM,GAAG,EAAK,GAAG,KAAY,IAAO,IAAI,EAAI,MAAM,CAAC,EAAK,GAAG;;AAgBxE,IAAa,IAAgB,EAAM,YAChC,EAAE,aAAU,UAAO,OAAO,WAAQ,GAAG,QAAK,QAAQ,aAAU,IAAM,cAAW,YAAS,MAAiB;CACtG,IAAM,IAAO,GACP,CAAC,GAAa,KAAkB,EAAM,SAAS,GAAM,EACrD,CAAC,GAAS,KAAc,EAAM,SAAS,EAAK,EAC5C,IAAQ,EAAM,OAA8B,KAAK,EAsDjD,IACJ,kBAFU,GAEV;EACE,KAlDc,EAAM,aACrB,MAA6B;AAK5B,OAJI,OAAO,KAAiB,aAAY,EAAa,EAAK,GACjD,MAAe,EAA4D,UAAU,IAE9F,EAAM,SAAS,YAAY,EACvB,CAAC,EAAM;GAEX,IAAM,UAAgB;AACpB,QAAI,MAAS,UAAU;AAErB,SADA,EAAK,cAAc,GACf,EAAK,gBAAgB,KAAK,EAAK,eAAe,EAAK,aAAa;AAElE,MADA,EAAW,EAAK,EAChB,EAAe,GAAM;AACrB;;KAGF,IAAI,IAAK,GACL,IAAK,EAAK,QACV,IAAO;AACX,YAAO,KAAM,IAAI;MACf,IAAM,IAAW,IAAK,KAAO;AAE7B,MADA,EAAK,cAAc,EAAe,GAAM,EAAQ,EAC5C,EAAK,eAAe,EAAK,eAC3B,IAAO,GACP,IAAK,IAAU,KAEf,IAAK,IAAU;;AAInB,KADA,EAAW,EAAe,GAAM,EAAK,CAAC,EACtC,EAAe,GAAK;WAEpB,EADS,MAAS,UACH,EAAK,eAAe,EAAK,eAAe,IAExC,EAAK,cAAc,EAAK,cAAc,EAAE;;AAM3D,GAFA,GAAS,EACT,EAAM,UAAU,IAAI,eAAe,EAAQ,EAC3C,EAAM,QAAQ,QAAQ,EAAK;KAG7B;GAAC;GAAM;GAAM;GAAO;GAAa,CAClC;EAMG,WAAW,EACT,MAAS,SAAS,kBAClB,MAAS,YAAY,2CACrB,MAAS,WAAW,mBACpB,EACD;EACD,OACE,MAAS,UACJ;GAAE,SAAS;GAAe,iBAAiB;GAAY,iBAAiB;GAAO,GAChF,KAAA;EAIN,cAAY,IAAe,KAAS,IAAQ,KAAA;YAE3C,MAAS,WAAW,IAAU;EAC3B,CAAA;AAWR,QARI,KAAW,IAEX,kBAAC,GAAD,EAAA,UAAA,CACE,kBAAC,GAAD;EAAgB,SAAA;YAAS;EAAyB,CAAA,EAClD,kBAAC,GAAD,EAAA,UAAiB,KAAS,GAAsB,CAAA,CACxC,EAAA,CAAA,GAGP;EAEV;AACD,EAAc,cAAc"}

package/docs/components/ui/card.md

@@ -9,11 +9,14 @@
     color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" (border accent color)
     size: "sm" | "md" | "lg" (padding — propagated to CardHeader/CardContent/CardFooter via context)
     interactive: boolean (enables hover shadow lift + pointer cursor)
-    accent: "left" | "top" | "right" | "bottom" (render a colored accent bar on the specified edge)
-    accentColor: "default" | "accent" | "error" | "success" | "warning" | "info" (color of the accent bar; default maps to accent-9)
+
+### CardAction
+    placement: "top-right" (default) | "top-left" | "bottom-right" | "bottom-left"
+    tuck: boolean (pull a step toward the corner so an icon button's glyph aligns to the content edge)
 
 ## Compound Components
     Card (root)
+      CardAction      ← absolutely-positioned corner slot (badge, icon button, menu)
       CardHeader      ← inherits size from Card context
         CardTitle
         CardDescription
@@ -37,15 +40,21 @@
 ## Composability
 - **Size cascades through context** — Card's `size` prop sets padding on CardHeader, CardContent, and CardFooter via `CardSizeContext`. Don't set padding classes on sub-components directly; override via `className` if needed.
 - **Not a compound state machine** — Card, CardHeader, CardTitle, etc. are purely structural. No open/close state.
-- **Accent bar is independent:** The `accent` / `accentColor` props render a decorative colored edge bar (absolutely positioned, `aria-hidden`). Works alongside `color` (which tints the border) — the two can stack for layered emphasis.
+- **Corner slots via `CardAction`:** Pin a badge, icon button, or menu to any corner (`placement`), inset to match the card's content padding. `tuck` pulls an icon button so its glyph (not its padding box) aligns to the content edge. Replaces the removed `accent` decorative bar — composition, not a bespoke prop. Card is `relative` to anchor it.
+- **`color` paints the border, never a stacked rail:** `color` tints the 1px edge (semantic accent/error/success/…). The DS never stacks a border + drop shadow or a colored rail on top (make-kit rule #6 — that reads as an AI tell).
 - **Interactive cards:** Set `interactive={true}` + `onClick` for clickable cards (entire surface becomes the button). Add `aria-label` on the Card root when there's no visible heading. For complex multi-action cards, prefer standard Card with explicit buttons inside.
-- **ContentCard (composed)** is a higher-level wrapper with built-in header/footer slots and title/actions — use it for list-row-style cards; use Card directly for custom layouts.
+- **ContentCard (composed) is deprecated** — compose `Card` + `CardHeader`/`CardContent`/`CardAction` directly instead.
 
 ## Gotchas
 - Use `interactive` prop for clickable cards — adds hover lift and pointer cursor
 - Don't override CardHeader/CardContent/CardFooter padding via className if you want the size cascade to work — set size on Card instead
 
 ## Changes
+### v0.44.0
+- **BREAKING** Removed `accent` / `accentColor` (the colored edge-bar / left-rail). Use `<CardAction>` for corner content, or `color` for a tinted border. The DS no longer ships a stacked rail (make-kit rule #6).
+- **Added** `<CardAction>` compound — composable corner slot (4 placements, `tuck`).
+- **Changed** Gap-model padding: the container owns vertical `py` + inter-slot `gap`; slots own only horizontal `px`. Adding/removing a slot can't unbalance the bottom edge. Card is now `relative`.
+
 ### v0.31.0
 - **Added** `color` prop: semantic border color (accent, error, success, warning, info, neutral)
 - **Added** `size` prop: `sm | md | lg` — padding propagated to sub-components via React context

package/docs/components/ui/stat-card.md

@@ -11,12 +11,17 @@
     prefix: string (before value, e.g. "$")
     suffix: string (after value, e.g. "users")
     delta: { value: string, direction: "up" | "down" | "neutral" }
+    deltaPlacement: "block" | "inline" (block = below value [default]; inline = on the value's baseline)
     icon: ReactNode | ComponentType<{ className?: string }>
     loading: boolean (renders skeleton)
     comparisonLabel: string (shown after delta, e.g. "vs last month")
     secondaryLabel: string (below main value, e.g. "of $50,000 target")
     progress: number (0-100, renders thin progress bar below value)
-    accent: "default" | "success" | "warning" | "error" | "info" (left border color)
+    variant: "default" | "elevated" | "outline" | "flat" (default = ring-in-shadow, no border; elevated = stronger shadow; outline = border, no shadow; flat = filled, no edge) — delegated to Card
+    accentStyle: "none" | "icon" | "tint" (none [default]; icon = accent chip around icon; tint = accent surface wash + accent value)
+    iconFill: "soft" | "solid" (chip style when accentStyle="icon"; default soft)
+    flash: "up" | "down" | "goal" | "record" | "alert" | "live" | { tone, icon } (opt-in entrance flash; requires icon)
+    flashSpeed: "fast" | "normal" | "slow" (default normal)
     sparkline: number[] (renders mini SVG line chart)
     onClick: () => void (makes card clickable with hover state)
     href: string (makes card a link via LinkContext)
@@ -34,7 +39,8 @@
   delta={{ value: "+12%", direction: "up" }}
   comparisonLabel="vs last month"
   icon={<IconCurrencyDollar />}
-  accent="success"
+  accentStyle="icon"
+  flash="up"
 />
 
 <StatCard
@@ -51,7 +57,8 @@
 - **High-density metric card** — optimized for dashboards. Everything optional except `value`. Mix and match features (delta, sparkline, progress, secondary label, footer) per metric's needs.
 - **Router integration via href:** Internally uses `LinkContext` to resolve framework-specific Link components (Next.js, react-router). Set `href` in a LinkProvider-wrapped tree to get seamless client-side navigation without custom asChild wiring.
 - **Interactive modes:** `onClick` makes the entire card a button; `href` makes it a link. Mutually exclusive — href wins if both are set.
-- **Accent bar semantic:** Use `accent` to signal metric health at a glance (success for positive, warning for at-risk, error for over-target). Combine with delta.direction for layered emphasis.
+- **Accent (composable, opt-in):** `accentStyle="icon"` wraps `icon` in an accent chip (`iconFill="soft" | "solid"`); `accentStyle="tint"` applies a subtle accent surface wash + accent value. `variant` picks edge-vs-elevation. No colored rail — the DS never stacks a border + drop shadow (make-kit rule #6). Trend health reads from `delta.direction` (up=green, down=red).
+- **Flash motion (opt-in):** `flash` mounts a toned state glyph (`up`/`down`/`goal`/`record`/`alert`/`live`, or `{ tone, icon }`) that settles to `icon`; `flashSpeed` tunes timing. Reuses the standalone `StatFlash` primitive. Honors `prefers-reduced-motion`.
 - **Sparkline:** Pure SVG, lightweight — no chart library. For rich charts use Chart components. Minimum 2 data points.
 - **Icon auto-sizing:** Accepts `ComponentType<{ className }>` OR `ReactNode`. The component prop (e.g. `icon={IconBolt}`) is preferred — icon is rendered at a consistent size.
 - **Loading state:** `loading={true}` renders the full card skeleton — use during initial data fetch.
@@ -63,6 +70,14 @@
 - `sparkline` needs at least 2 data points to render
 
 ## Changes
+### v0.44.0
+- **BREAKING** Renamed `surface` → `variant`, widened to a 4-way scale (`default` | `elevated` | `outline` | `flat`). StatCard now composes `<Card>`, so surface, gap-model padding, and elevation all live in one place. Migration: `surface="raised"` → `variant="default"`, `surface="flat"` → `variant="outline"`.
+- **Added** `deltaPlacement` (`"block"` [default] | `"inline"`) — inline rides the value's baseline for compact dashboards.
+
+### v0.43.0
+- **BREAKING** Removed `accent` (colored left-rail). Use `accentStyle` (`"icon"` | `"tint"`) or rely on `delta` for trend colour.
+- **Added** `surface`, `accentStyle`, `iconFill`, `flash`, `flashSpeed`. New standalone `StatFlash` primitive. Base no longer stacks border + shadow.
+
 ### v0.2.0
 - **Added** `icon` prop now accepts `React.ComponentType` (e.g., `icon={IconBolt}`) in addition to `ReactNode`
 

package/docs/components/ui/stat-flash.md

@@ -0,0 +1,44 @@
+# StatFlash
+
+- Import: @devalok/shilp-sutra/ui/stat-flash
+- Server-safe: No
+- Category: ui
+
+## Props
+    icon: ReactNode | ComponentType<{ className?: string }> (REQUIRED — settled identity glyph)
+    flash: "up" | "down" | "goal" | "record" | "alert" | "live" | { tone, icon } (REQUIRED — the entrance state)
+    fill: "soft" | "solid" (resting chip style; default soft)
+    speed: "fast" | "normal" | "slow" (coarse motion preset; default normal)
+    holdMs: number (override how long the flash holds before settling)
+    settleTransition: Transition (override the icon scale-in transition)
+    flashTransition: Transition (override the flash enter/exit fade)
+
+## Defaults
+    fill="soft", speed="normal"
+
+## Example
+```jsx
+// Preset: green up-arrow flashes, then settles to the folder icon
+<StatFlash icon={<IconFolder />} flash="up" />
+
+// Explicit tone + glyph
+<StatFlash icon={<IconActivity />} flash={{ tone: "info", icon: <IconBolt /> }} fill="solid" />
+
+// Composable speed: coarse preset + fine override
+<StatFlash icon={<IconFolder />} flash="up" speed="fast" holdMs={300} />
+```
+
+## Composability
+- **State → identity primitive:** the chip mounts showing a transient *state* (a toned glyph — up-arrow on green, check, alert…) then settles into the stable *identity* icon. Used by `StatCard`'s `flash` prop, but standalone too (list rows, badges, toasts).
+- **Tone slot:** six named presets (`up`/`down`/`goal`/`record`/`alert`/`live`) map to DS semantic tones (success/error/warning/info/accent) + a glyph. Pass `{ tone, icon }` for anything else.
+- **Composable motion:** `speed` is a coarse preset built from the DS motion tokens; `holdMs` / `settleTransition` / `flashTransition` each override one slice and fall back to the preset.
+- **Accessible by default:** honors `prefers-reduced-motion` — renders the settled identity directly, no flash. The chip is `aria-hidden` (decorative; the metric's text carries meaning).
+
+## Gotchas
+- `flash` and `icon` are both required — the flash settles *to* the icon.
+- Fine overrides win over `speed`.
+- Decorative only — never the sole carrier of meaning (it's `aria-hidden`).
+
+## Changes
+### v0.43.0
+- **Added** Initial release. Powers `StatCard`'s `flash` prop.

package/docs/components/ui/truncated-text.md

@@ -0,0 +1,49 @@
+# TruncatedText
+
+- Import: @devalok/shilp-sutra/ui/truncated-text
+- Server-safe: No
+- Category: ui
+
+## Props
+    children: string (REQUIRED — the full text; always the accessible name, even when shortened)
+    mode: "end" | "clamp" | "middle" (end [default] = single-line ellipsis; clamp = multi-line; middle = keep both ends)
+    lines: number (lines to show in mode="clamp"; default 2)
+    as: "span" | "p" | "div" (element to render; default "span")
+    tooltip: boolean (show the full text in a tooltip when — and only when — actually clipped; default true)
+    title: string (override the full-text accessible name / tooltip; defaults to children)
+    className: string
+
+## Defaults
+    mode="end", lines=2, as="span", tooltip=true
+
+## Example
+```jsx
+<TruncatedText>{user.name}</TruncatedText>
+
+// Filenames / emails — keep the extension / domain:
+<TruncatedText mode="middle">{fileName}</TruncatedText>     // report…v7.pdf
+
+// Multi-line description with a 2-line clamp:
+<TruncatedText as="p" mode="clamp" lines={2}>{description}</TruncatedText>
+
+// In a flex row, the shrinking item still needs min-w-0:
+<div className="flex items-center gap-ds-03">
+  <Avatar … />
+  <TruncatedText className="min-w-0 flex-1">{user.name}</TruncatedText>
+</div>
+```
+
+## Composability
+- **Truncates AND recovers in one place:** `end`/`clamp` are pure CSS (full text stays in the DOM → screen-reader safe). `middle` measures the element and JS-shortens the visible string but keeps the full string as the accessible name. A tooltip appears only when `scrollWidth`/`scrollHeight` actually exceeds the box (measured via ResizeObserver) — no tooltip noise on text that fits.
+- **`mode="middle"` for identifiers:** filenames (extension), emails (domain), paths, hashes — end-ellipsis destroys the meaningful tail; middle keeps both ends. Middle is not native CSS, so it's measured + recomputed on resize.
+- **The flexbox gotcha:** `truncate` (and `middle`) do nothing on a flex/grid child unless that item has `min-w-0` (or an explicit width). TruncatedText can't set that on its parent — add `min-w-0` at the call site.
+- **Don't truncate everything:** page titles/H1, toast bodies, validation messages, and numbers must show fully (a truncated number is a wrong number). Use this for bounded list/nav/metadata text.
+
+## Gotchas
+- `children` must be a string (it's measured + used as the accessible name) — not arbitrary ReactNode.
+- In a flex row, add `min-w-0` to the TruncatedText (or its column) or nothing truncates.
+- `mode="middle"` clips to the largest middle-truncated string that fits; the last glyph may be sub-pixel-clipped by overflow-hidden — the tooltip + aria-label always carry the full string.
+
+## Changes
+### v0.44.0
+- **Added** Initial release — end/clamp/middle truncation with overflow-aware tooltip recovery.

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.42.1
+> Version: 0.44.0
 >
 > **If you are an AI agent reading this file top-to-bottom:** the Setup
 > section below is authoritative. If any later per-component doc or a
@@ -1096,11 +1096,14 @@ See `Button` docs for the public API.
     color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" (border accent color)
     size: "sm" | "md" | "lg" (padding — propagated to CardHeader/CardContent/CardFooter via context)
     interactive: boolean (enables hover shadow lift + pointer cursor)
-    accent: "left" | "top" | "right" | "bottom" (render a colored accent bar on the specified edge)
-    accentColor: "default" | "accent" | "error" | "success" | "warning" | "info" (color of the accent bar; default maps to accent-9)
+
+### CardAction
+    placement: "top-right" (default) | "top-left" | "bottom-right" | "bottom-left"
+    tuck: boolean (pull a step toward the corner so an icon button's glyph aligns to the content edge)
 
 ## Compound Components
     Card (root)
+      CardAction      ← absolutely-positioned corner slot (badge, icon button, menu)
       CardHeader      ← inherits size from Card context
         CardTitle
         CardDescription
@@ -1124,15 +1127,21 @@ See `Button` docs for the public API.
 ## Composability
 - **Size cascades through context** — Card's `size` prop sets padding on CardHeader, CardContent, and CardFooter via `CardSizeContext`. Don't set padding classes on sub-components directly; override via `className` if needed.
 - **Not a compound state machine** — Card, CardHeader, CardTitle, etc. are purely structural. No open/close state.
-- **Accent bar is independent:** The `accent` / `accentColor` props render a decorative colored edge bar (absolutely positioned, `aria-hidden`). Works alongside `color` (which tints the border) — the two can stack for layered emphasis.
+- **Corner slots via `CardAction`:** Pin a badge, icon button, or menu to any corner (`placement`), inset to match the card's content padding. `tuck` pulls an icon button so its glyph (not its padding box) aligns to the content edge. Replaces the removed `accent` decorative bar — composition, not a bespoke prop. Card is `relative` to anchor it.
+- **`color` paints the border, never a stacked rail:** `color` tints the 1px edge (semantic accent/error/success/…). The DS never stacks a border + drop shadow or a colored rail on top (make-kit rule #6 — that reads as an AI tell).
 - **Interactive cards:** Set `interactive={true}` + `onClick` for clickable cards (entire surface becomes the button). Add `aria-label` on the Card root when there's no visible heading. For complex multi-action cards, prefer standard Card with explicit buttons inside.
-- **ContentCard (composed)** is a higher-level wrapper with built-in header/footer slots and title/actions — use it for list-row-style cards; use Card directly for custom layouts.
+- **ContentCard (composed) is deprecated** — compose `Card` + `CardHeader`/`CardContent`/`CardAction` directly instead.
 
 ## Gotchas
 - Use `interactive` prop for clickable cards — adds hover lift and pointer cursor
 - Don't override CardHeader/CardContent/CardFooter padding via className if you want the size cascade to work — set size on Card instead
 
 ## Changes
+### v0.44.0
+- **BREAKING** Removed `accent` / `accentColor` (the colored edge-bar / left-rail). Use `<CardAction>` for corner content, or `color` for a tinted border. The DS no longer ships a stacked rail (make-kit rule #6).
+- **Added** `<CardAction>` compound — composable corner slot (4 placements, `tuck`).
+- **Changed** Gap-model padding: the container owns vertical `py` + inter-slot `gap`; slots own only horizontal `px`. Adding/removing a slot can't unbalance the bottom edge. Card is now `relative`.
+
 ### v0.31.0
 - **Added** `color` prop: semantic border color (accent, error, success, warning, info, neutral)
 - **Added** `size` prop: `sm | md | lg` — padding propagated to sub-components via React context
@@ -4041,12 +4050,17 @@ import { SplitButton } from '@devalok/shilp-sutra'
     prefix: string (before value, e.g. "$")
     suffix: string (after value, e.g. "users")
     delta: { value: string, direction: "up" | "down" | "neutral" }
+    deltaPlacement: "block" | "inline" (block = below value [default]; inline = on the value's baseline)
     icon: ReactNode | ComponentType<{ className?: string }>
     loading: boolean (renders skeleton)
     comparisonLabel: string (shown after delta, e.g. "vs last month")
     secondaryLabel: string (below main value, e.g. "of $50,000 target")
     progress: number (0-100, renders thin progress bar below value)
-    accent: "default" | "success" | "warning" | "error" | "info" (left border color)
+    variant: "default" | "elevated" | "outline" | "flat" (default = ring-in-shadow, no border; elevated = stronger shadow; outline = border, no shadow; flat = filled, no edge) — delegated to Card
+    accentStyle: "none" | "icon" | "tint" (none [default]; icon = accent chip around icon; tint = accent surface wash + accent value)
+    iconFill: "soft" | "solid" (chip style when accentStyle="icon"; default soft)
+    flash: "up" | "down" | "goal" | "record" | "alert" | "live" | { tone, icon } (opt-in entrance flash; requires icon)
+    flashSpeed: "fast" | "normal" | "slow" (default normal)
     sparkline: number[] (renders mini SVG line chart)
     onClick: () => void (makes card clickable with hover state)
     href: string (makes card a link via LinkContext)
@@ -4064,7 +4078,8 @@ import { SplitButton } from '@devalok/shilp-sutra'
   delta={{ value: "+12%", direction: "up" }}
   comparisonLabel="vs last month"
   icon={<IconCurrencyDollar />}
-  accent="success"
+  accentStyle="icon"
+  flash="up"
 />
 
 <StatCard
@@ -4081,7 +4096,8 @@ import { SplitButton } from '@devalok/shilp-sutra'
 - **High-density metric card** — optimized for dashboards. Everything optional except `value`. Mix and match features (delta, sparkline, progress, secondary label, footer) per metric's needs.
 - **Router integration via href:** Internally uses `LinkContext` to resolve framework-specific Link components (Next.js, react-router). Set `href` in a LinkProvider-wrapped tree to get seamless client-side navigation without custom asChild wiring.
 - **Interactive modes:** `onClick` makes the entire card a button; `href` makes it a link. Mutually exclusive — href wins if both are set.
-- **Accent bar semantic:** Use `accent` to signal metric health at a glance (success for positive, warning for at-risk, error for over-target). Combine with delta.direction for layered emphasis.
+- **Accent (composable, opt-in):** `accentStyle="icon"` wraps `icon` in an accent chip (`iconFill="soft" | "solid"`); `accentStyle="tint"` applies a subtle accent surface wash + accent value. `variant` picks edge-vs-elevation. No colored rail — the DS never stacks a border + drop shadow (make-kit rule #6). Trend health reads from `delta.direction` (up=green, down=red).
+- **Flash motion (opt-in):** `flash` mounts a toned state glyph (`up`/`down`/`goal`/`record`/`alert`/`live`, or `{ tone, icon }`) that settles to `icon`; `flashSpeed` tunes timing. Reuses the standalone `StatFlash` primitive. Honors `prefers-reduced-motion`.
 - **Sparkline:** Pure SVG, lightweight — no chart library. For rich charts use Chart components. Minimum 2 data points.
 - **Icon auto-sizing:** Accepts `ComponentType<{ className }>` OR `ReactNode`. The component prop (e.g. `icon={IconBolt}`) is preferred — icon is rendered at a consistent size.
 - **Loading state:** `loading={true}` renders the full card skeleton — use during initial data fetch.
@@ -4093,11 +4109,63 @@ import { SplitButton } from '@devalok/shilp-sutra'
 - `sparkline` needs at least 2 data points to render
 
 ## Changes
+### v0.44.0
+- **BREAKING** Renamed `surface` → `variant`, widened to a 4-way scale (`default` | `elevated` | `outline` | `flat`). StatCard now composes `<Card>`, so surface, gap-model padding, and elevation all live in one place. Migration: `surface="raised"` → `variant="default"`, `surface="flat"` → `variant="outline"`.
+- **Added** `deltaPlacement` (`"block"` [default] | `"inline"`) — inline rides the value's baseline for compact dashboards.
+
+### v0.43.0
+- **BREAKING** Removed `accent` (colored left-rail). Use `accentStyle` (`"icon"` | `"tint"`) or rely on `delta` for trend colour.
+- **Added** `surface`, `accentStyle`, `iconFill`, `flash`, `flashSpeed`. New standalone `StatFlash` primitive. Base no longer stacks border + shadow.
+
 ### v0.2.0
 - **Added** `icon` prop now accepts `React.ComponentType` (e.g., `icon={IconBolt}`) in addition to `ReactNode`
 
 ### v0.1.0
 - **Added** Initial release
+# StatFlash
+
+- Import: @devalok/shilp-sutra/ui/stat-flash
+- Server-safe: No
+- Category: ui
+
+## Props
+    icon: ReactNode | ComponentType<{ className?: string }> (REQUIRED — settled identity glyph)
+    flash: "up" | "down" | "goal" | "record" | "alert" | "live" | { tone, icon } (REQUIRED — the entrance state)
+    fill: "soft" | "solid" (resting chip style; default soft)
+    speed: "fast" | "normal" | "slow" (coarse motion preset; default normal)
+    holdMs: number (override how long the flash holds before settling)
+    settleTransition: Transition (override the icon scale-in transition)
+    flashTransition: Transition (override the flash enter/exit fade)
+
+## Defaults
+    fill="soft", speed="normal"
+
+## Example
+```jsx
+// Preset: green up-arrow flashes, then settles to the folder icon
+<StatFlash icon={<IconFolder />} flash="up" />
+
+// Explicit tone + glyph
+<StatFlash icon={<IconActivity />} flash={{ tone: "info", icon: <IconBolt /> }} fill="solid" />
+
+// Composable speed: coarse preset + fine override
+<StatFlash icon={<IconFolder />} flash="up" speed="fast" holdMs={300} />
+```
+
+## Composability
+- **State → identity primitive:** the chip mounts showing a transient *state* (a toned glyph — up-arrow on green, check, alert…) then settles into the stable *identity* icon. Used by `StatCard`'s `flash` prop, but standalone too (list rows, badges, toasts).
+- **Tone slot:** six named presets (`up`/`down`/`goal`/`record`/`alert`/`live`) map to DS semantic tones (success/error/warning/info/accent) + a glyph. Pass `{ tone, icon }` for anything else.
+- **Composable motion:** `speed` is a coarse preset built from the DS motion tokens; `holdMs` / `settleTransition` / `flashTransition` each override one slice and fall back to the preset.
+- **Accessible by default:** honors `prefers-reduced-motion` — renders the settled identity directly, no flash. The chip is `aria-hidden` (decorative; the metric's text carries meaning).
+
+## Gotchas
+- `flash` and `icon` are both required — the flash settles *to* the icon.
+- Fine overrides win over `speed`.
+- Decorative only — never the sole carrier of meaning (it's `aria-hidden`).
+
+## Changes
+### v0.43.0
+- **Added** Initial release. Powers `StatCard`'s `flash` prop.
 # StatusDot
 
 - Import: @devalok/shilp-sutra/ui/status-dot
@@ -4806,6 +4874,55 @@ export default function RootLayout({ children }) {
 
 ### v0.1.0
 - **Added** Initial release
+# TruncatedText
+
+- Import: @devalok/shilp-sutra/ui/truncated-text
+- Server-safe: No
+- Category: ui
+
+## Props
+    children: string (REQUIRED — the full text; always the accessible name, even when shortened)
+    mode: "end" | "clamp" | "middle" (end [default] = single-line ellipsis; clamp = multi-line; middle = keep both ends)
+    lines: number (lines to show in mode="clamp"; default 2)
+    as: "span" | "p" | "div" (element to render; default "span")
+    tooltip: boolean (show the full text in a tooltip when — and only when — actually clipped; default true)
+    title: string (override the full-text accessible name / tooltip; defaults to children)
+    className: string
+
+## Defaults
+    mode="end", lines=2, as="span", tooltip=true
+
+## Example
+```jsx
+<TruncatedText>{user.name}</TruncatedText>
+
+// Filenames / emails — keep the extension / domain:
+<TruncatedText mode="middle">{fileName}</TruncatedText>     // report…v7.pdf
+
+// Multi-line description with a 2-line clamp:
+<TruncatedText as="p" mode="clamp" lines={2}>{description}</TruncatedText>
+
+// In a flex row, the shrinking item still needs min-w-0:
+<div className="flex items-center gap-ds-03">
+  <Avatar … />
+  <TruncatedText className="min-w-0 flex-1">{user.name}</TruncatedText>
+</div>
+```
+
+## Composability
+- **Truncates AND recovers in one place:** `end`/`clamp` are pure CSS (full text stays in the DOM → screen-reader safe). `middle` measures the element and JS-shortens the visible string but keeps the full string as the accessible name. A tooltip appears only when `scrollWidth`/`scrollHeight` actually exceeds the box (measured via ResizeObserver) — no tooltip noise on text that fits.
+- **`mode="middle"` for identifiers:** filenames (extension), emails (domain), paths, hashes — end-ellipsis destroys the meaningful tail; middle keeps both ends. Middle is not native CSS, so it's measured + recomputed on resize.
+- **The flexbox gotcha:** `truncate` (and `middle`) do nothing on a flex/grid child unless that item has `min-w-0` (or an explicit width). TruncatedText can't set that on its parent — add `min-w-0` at the call site.
+- **Don't truncate everything:** page titles/H1, toast bodies, validation messages, and numbers must show fully (a truncated number is a wrong number). Use this for bounded list/nav/metadata text.
+
+## Gotchas
+- `children` must be a string (it's measured + used as the accessible name) — not arbitrary ReactNode.
+- In a flex row, add `min-w-0` to the TruncatedText (or its column) or nothing truncates.
+- `mode="middle"` clips to the largest middle-truncated string that fits; the last glyph may be sub-pixel-clipped by overflow-hidden — the tooltip + aria-label always carry the full string.
+
+## Changes
+### v0.44.0
+- **Added** Initial release — end/clamp/middle truncation with overflow-aware tooltip recovery.
 # VisuallyHidden
 
 - Import: @devalok/shilp-sutra/ui/visually-hidden

package/make-kit/components/card.md

@@ -5,6 +5,7 @@ The default container for any panel-style content that sits **on** the page.
 ```tsx
 import {
   Card,
+  CardAction,
   CardHeader,
   CardTitle,
   CardDescription,
@@ -65,8 +66,13 @@ Card (root)
 | Prop | Type | Notes |
 |---|---|---|
 | `interactive` | `boolean` | Adds hover lift + `cursor-pointer`. Make the whole card clickable. Provide `onClick` and `aria-label`. |
-| `accent` | `'left'\|'top'\|'right'\|'bottom'` | Decorative colored bar on the named edge. |
-| `accentColor` | `'default'\|'accent'\|'error'\|'success'\|'warning'\|'info'` | Color of the accent bar. |
+
+### CardAction (corner slot)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `placement` | `'top-right'` (default) `\| 'top-left' \| 'bottom-right' \| 'bottom-left'` | Which corner. Inset matches the card's content padding. |
+| `tuck` | `boolean` | Pull a step toward the corner so an icon button's glyph (not its padding box) aligns to the content edge. |
 
 ## Examples
 
@@ -107,13 +113,17 @@ Card (root)
 </Card>
 ```
 
-**Accent bar — pipeline state:**
+**Corner slot — status badge / overflow action:**
 ```tsx
-<Card accent="left" accentColor="success">
+<Card>
+  <CardAction><Badge color="success" size="xs">DEPLOYED</Badge></CardAction>
   <CardHeader>
     <CardTitle>Deploy succeeded</CardTitle>
     <CardDescription>main · 2 min ago</CardDescription>
   </CardHeader>
+  <CardAction placement="bottom-right" tuck>
+    <Button variant="ghost" size="sm">View logs</Button>
+  </CardAction>
 </Card>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.42.1",
+  "version": "0.44.0",
   "description": "Devalok Design System — accessible React components, OKLCH design tokens, and Tailwind 4 CSS-first setup. Ships with AI-agent setup recipes.",
   "license": "MIT",
   "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: shilp-sutra
 description: Add, configure, and use components from Devalok's shilp-sutra design system (@devalok/shilp-sutra) — a Tailwind 4 + React 19 + CVA library with 110+ accessible components, OKLCH design tokens, framer-motion animations, and per-component RSC-safe entry points. Use this skill whenever the user mentions shilp-sutra, Devalok, the @devalok npm scope, or asks to install/add/style/theme UI in any React project that already depends on the package — even if they don't name it explicitly. Use it instead of generic shadcn/ui, MUI, or Chakra knowledge when shilp-sutra is in the project. Covers Next.js (App + Pages), Vite, Astro, Remix, TanStack Start setup playbooks; component API and variant reference; brand token customization; Server Component import patterns; and a troubleshoot tree for the thirteen most common breakages.
 license: MIT
 metadata:
-  version: "0.42.1"
+  version: "0.44.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra