@devalok/shilp-sutra 0.37.0 → 0.37.1

package/dist/composed/inline-edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inline-edit.d.ts","sourceRoot":"","sources":["../../src/composed/inline-edit.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAU9B,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC3F,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAUD,QAAA,MAAM,UAAU,wFAgJd,CAAA;AAGF,OAAO,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"inline-edit.d.ts","sourceRoot":"","sources":["../../src/composed/inline-edit.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAU9B,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC3F,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAUD,QAAA,MAAM,UAAU,wFAyJd,CAAA;AAGF,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/composed/inline-edit.js

@@ -6,86 +6,88 @@ import * as r from "react";
 import { jsx as i, jsxs as a } from "react/jsx-runtime";
 import { IconPencil as o } from "@tabler/icons-react";
 //#region src/composed/inline-edit.tsx
-var s = r.forwardRef(({ value: s, onSave: c, placeholder: l = "Click to edit", textClassName: u, readOnly: d = !1, maxLength: f, saving: p = !1, className: m, ...h }, g) => {
-	let [_, v] = r.useState(!1), [y, b] = r.useState(!1), x = r.useRef(null), S = r.useRef(s), C = p || _, w = !s;
+var s = r.forwardRef(({ value: s, onSave: c, placeholder: l = "Click to edit", textClassName: u, readOnly: d = !1, maxLength: f, saving: p = !1, className: m, "aria-label": h, "aria-labelledby": g, ..._ }, v) => {
+	let [y, b] = r.useState(!1), [x, S] = r.useState(!1), C = r.useRef(null), w = r.useRef(s), T = p || y, E = !s;
 	r.useEffect(() => {
-		!y && x.current && (x.current.textContent = s);
-	}, [s, y]);
-	function T() {
-		d || C || (b(!0), S.current = s, requestAnimationFrame(() => {
-			if (!x.current) return;
+		!x && C.current && (C.current.textContent = s);
+	}, [s, x]);
+	function D() {
+		d || T || (S(!0), w.current = s, requestAnimationFrame(() => {
+			if (!C.current) return;
 			let e = document.createRange();
-			e.selectNodeContents(x.current);
+			e.selectNodeContents(C.current);
 			let t = window.getSelection();
 			t?.removeAllRanges(), t?.addRange(e);
 		}));
 	}
-	async function E() {
-		if (!x.current) return;
-		b(!1);
-		let e = (x.current.textContent ?? "").trim(), t = f ? e.slice(0, f) : e;
-		if (x.current.textContent = t || s, t === s) return;
+	async function O() {
+		if (!C.current) return;
+		S(!1);
+		let e = (C.current.textContent ?? "").trim(), t = f ? e.slice(0, f) : e;
+		if (C.current.textContent = t || s, t === s) return;
 		let n = c(t);
 		if (n instanceof Promise) {
-			v(!0);
+			b(!0);
 			try {
 				await n;
 			} catch {
-				x.current && (x.current.textContent = s);
+				C.current && (C.current.textContent = s);
 			} finally {
-				v(!1);
+				b(!1);
 			}
 		}
 	}
-	function D() {
-		x.current && (x.current.textContent = S.current, b(!1), x.current.blur());
+	function k() {
+		C.current && (C.current.textContent = w.current, S(!1), C.current.blur());
 	}
-	function O(e) {
-		e.key === "Escape" ? (e.preventDefault(), D()) : e.key === "Enter" && (e.preventDefault(), E());
+	function A(e) {
+		e.key === "Escape" ? (e.preventDefault(), k()) : e.key === "Enter" && (e.preventDefault(), O());
 	}
-	function k() {
-		if (!x.current || !f) return;
-		let e = x.current.textContent ?? "";
+	function j() {
+		if (!C.current || !f) return;
+		let e = C.current.textContent ?? "";
 		if (e.length > f) {
-			x.current.textContent = e.slice(0, f);
+			C.current.textContent = e.slice(0, f);
 			let t = document.createRange();
-			t.selectNodeContents(x.current), t.collapse(!1);
+			t.selectNodeContents(C.current), t.collapse(!1);
 			let n = window.getSelection();
 			n?.removeAllRanges(), n?.addRange(t);
 		}
 	}
-	function A(e) {
+	function M(e) {
 		e.preventDefault();
 		let t = e.clipboardData.getData("text/plain");
 		document.execCommand("insertText", !1, t);
 	}
 	return /* @__PURE__ */ a("div", {
-		ref: g,
+		ref: v,
 		className: e("group inline-flex items-center gap-ds-02", m),
-		...h,
+		..._,
 		children: [
 			/* @__PURE__ */ i("span", {
-				ref: x,
+				ref: C,
 				role: d ? void 0 : "textbox",
-				contentEditable: !d && !C,
+				contentEditable: !d && !T,
 				suppressContentEditableWarning: !0,
 				tabIndex: d ? void 0 : 0,
-				onFocus: T,
-				onBlur: E,
-				onKeyDown: O,
-				onInput: k,
-				onPaste: A,
-				spellCheck: y,
-				className: e("font-sans text-surface-fg outline-hidden", u, !d && !y && "cursor-text rounded-ds-sm -mx-ds-01 px-ds-01 hover:bg-surface-raised-hover transition-colors duration-fast-01", y && "rounded-ds-sm -mx-ds-01 px-ds-01 bg-surface-raised-hover ring-1 ring-accent-7", w && !y && "text-surface-fg-subtle italic", d && "cursor-default"),
+				"aria-label": d ? void 0 : h ?? (g ? void 0 : l),
+				"aria-labelledby": d ? void 0 : g,
+				onFocus: D,
+				onBlur: O,
+				onKeyDown: A,
+				onInput: j,
+				onPaste: M,
+				spellCheck: x,
+				className: e("font-sans text-surface-fg outline-hidden", u, !d && !x && "cursor-text rounded-ds-sm -mx-ds-01 px-ds-01 hover:bg-surface-raised-hover transition-colors duration-fast-01", x && "rounded-ds-sm -mx-ds-01 px-ds-01 bg-surface-raised-hover ring-1 ring-accent-7", E && !x && "text-surface-fg-subtle italic", d && "cursor-default"),
 				"data-placeholder": l,
-				children: s || (y ? "" : l)
+				children: s || (x ? "" : l)
 			}),
-			!d && !y && !C && /* @__PURE__ */ i(n, {
+			!d && !x && !T && /* @__PURE__ */ i(n, {
 				icon: o,
 				size: "xs",
 				className: "text-surface-fg-subtle opacity-0 group-hover:opacity-100 transition-opacity duration-fast-01 shrink-0"
 			}),
-			C && /* @__PURE__ */ i(t, { size: "sm" })
+			T && /* @__PURE__ */ i(t, { size: "sm" })
 		]
 	});
 });

package/dist/composed/inline-edit.js.map

@@ -1 +1 @@
-{"version":3,"file":"inline-edit.js","names":[],"sources":["../../src/composed/inline-edit.tsx"],"sourcesContent":["'use client'\n\nimport { IconPencil } from '@tabler/icons-react'\nimport * as React from 'react'\n\nimport { Icon } from '../ui/icon'\nimport { cn } from '../ui/lib/utils'\nimport { Spinner } from '../ui/spinner'\n\n// ============================================================\n// Types\n// ============================================================\n\nexport interface InlineEditProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSave'> {\n  value: string\n  onSave: (newValue: string) => void | Promise<void>\n  placeholder?: string\n  /** CSS class applied to the editable text (e.g. 'text-ds-lg font-semibold') */\n  textClassName?: string\n  readOnly?: boolean\n  maxLength?: number\n  /** External saving state — shows spinner */\n  saving?: boolean\n}\n\n// ============================================================\n// InlineEdit — contentEditable approach\n//\n// No mode switch. No input field. The text IS the editor.\n// Click → cursor appears in the text. Type. Enter saves. Escape reverts.\n// Like Notion, Linear, Figma layer names.\n// ============================================================\n\nconst InlineEdit = React.forwardRef<HTMLDivElement, InlineEditProps>(({\n  value,\n  onSave,\n  placeholder = 'Click to edit',\n  textClassName,\n  readOnly = false,\n  maxLength,\n  saving: savingProp = false,\n  className,\n  ...props\n}, ref) => {\n  const [saving, setSaving] = React.useState(false)\n  const [focused, setFocused] = React.useState(false)\n  const editRef = React.useRef<HTMLSpanElement>(null)\n  const snapshotRef = React.useRef(value)\n\n  const isSaving = savingProp || saving\n  const isEmpty = !value\n\n  // Sync DOM text when value changes externally (and not focused)\n  React.useEffect(() => {\n    if (!focused && editRef.current) {\n      editRef.current.textContent = value\n    }\n  }, [value, focused])\n\n  function handleFocus() {\n    if (readOnly || isSaving) return\n    setFocused(true)\n    snapshotRef.current = value\n\n    // Select all text on focus (like clicking a file name in Finder)\n    requestAnimationFrame(() => {\n      if (!editRef.current) return\n      const range = document.createRange()\n      range.selectNodeContents(editRef.current)\n      const sel = window.getSelection()\n      sel?.removeAllRanges()\n      sel?.addRange(range)\n    })\n  }\n\n  async function commit() {\n    if (!editRef.current) return\n    setFocused(false)\n    const raw = editRef.current.textContent ?? ''\n    const trimmed = raw.trim()\n\n    // Enforce maxLength\n    const final = maxLength ? trimmed.slice(0, maxLength) : trimmed\n\n    // Reset DOM to clean value\n    editRef.current.textContent = final || value\n\n    if (final === value) return\n    const result = onSave(final)\n    if (result instanceof Promise) {\n      setSaving(true)\n      try {\n        await result\n      } catch {\n        // Revert on error\n        if (editRef.current) editRef.current.textContent = value\n      } finally {\n        setSaving(false)\n      }\n    }\n  }\n\n  function cancel() {\n    if (!editRef.current) return\n    editRef.current.textContent = snapshotRef.current\n    setFocused(false)\n    editRef.current.blur()\n  }\n\n  function handleKeyDown(e: React.KeyboardEvent) {\n    if (e.key === 'Escape') {\n      e.preventDefault()\n      cancel()\n    } else if (e.key === 'Enter') {\n      e.preventDefault()\n      commit()\n    }\n  }\n\n  function handleInput() {\n    if (!editRef.current || !maxLength) return\n    const text = editRef.current.textContent ?? ''\n    if (text.length > maxLength) {\n      editRef.current.textContent = text.slice(0, maxLength)\n      // Move cursor to end\n      const range = document.createRange()\n      range.selectNodeContents(editRef.current)\n      range.collapse(false)\n      const sel = window.getSelection()\n      sel?.removeAllRanges()\n      sel?.addRange(range)\n    }\n  }\n\n  // Prevent paste from inserting rich content\n  function handlePaste(e: React.ClipboardEvent) {\n    e.preventDefault()\n    const text = e.clipboardData.getData('text/plain')\n    document.execCommand('insertText', false, text)\n  }\n\n  return (\n    <div ref={ref} className={cn('group inline-flex items-center gap-ds-02', className)} {...props}>\n      <span\n        ref={editRef}\n        role={readOnly ? undefined : 'textbox'}\n        contentEditable={!readOnly && !isSaving}\n        suppressContentEditableWarning\n        tabIndex={readOnly ? undefined : 0}\n        onFocus={handleFocus}\n        onBlur={commit}\n        onKeyDown={handleKeyDown}\n        onInput={handleInput}\n        onPaste={handlePaste}\n        spellCheck={focused}\n        className={cn(\n          'font-sans text-surface-fg outline-hidden',\n          textClassName,\n          // Idle: subtle hover hint\n          !readOnly && !focused && 'cursor-text rounded-ds-sm -mx-ds-01 px-ds-01 hover:bg-surface-raised-hover transition-colors duration-fast-01',\n          // Focused: subtle underline to indicate editing\n          focused && 'rounded-ds-sm -mx-ds-01 px-ds-01 bg-surface-raised-hover ring-1 ring-accent-7',\n          // Empty: show placeholder styling\n          isEmpty && !focused && 'text-surface-fg-subtle italic',\n          // Read-only\n          readOnly && 'cursor-default',\n        )}\n        data-placeholder={placeholder}\n      >\n        {value || (focused ? '' : placeholder)}\n      </span>\n      {!readOnly && !focused && !isSaving && (\n        <Icon icon={IconPencil} size=\"xs\" className=\"text-surface-fg-subtle opacity-0 group-hover:opacity-100 transition-opacity duration-fast-01 shrink-0\" />\n      )}\n      {isSaving && <Spinner size=\"sm\" />}\n    </div>\n  )\n})\nInlineEdit.displayName = 'InlineEdit'\n\nexport { InlineEdit }\n"],"mappings":"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"}
+{"version":3,"file":"inline-edit.js","names":[],"sources":["../../src/composed/inline-edit.tsx"],"sourcesContent":["'use client'\n\nimport { IconPencil } from '@tabler/icons-react'\nimport * as React from 'react'\n\nimport { Icon } from '../ui/icon'\nimport { cn } from '../ui/lib/utils'\nimport { Spinner } from '../ui/spinner'\n\n// ============================================================\n// Types\n// ============================================================\n\nexport interface InlineEditProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSave'> {\n  value: string\n  onSave: (newValue: string) => void | Promise<void>\n  placeholder?: string\n  /** CSS class applied to the editable text (e.g. 'text-ds-lg font-semibold') */\n  textClassName?: string\n  readOnly?: boolean\n  maxLength?: number\n  /** External saving state — shows spinner */\n  saving?: boolean\n}\n\n// ============================================================\n// InlineEdit — contentEditable approach\n//\n// No mode switch. No input field. The text IS the editor.\n// Click → cursor appears in the text. Type. Enter saves. Escape reverts.\n// Like Notion, Linear, Figma layer names.\n// ============================================================\n\nconst InlineEdit = React.forwardRef<HTMLDivElement, InlineEditProps>(({\n  value,\n  onSave,\n  placeholder = 'Click to edit',\n  textClassName,\n  readOnly = false,\n  maxLength,\n  saving: savingProp = false,\n  className,\n  // aria-label / aria-labelledby apply to the editable textbox (the inner\n  // span), not the outer wrapper div. Intercept them from ...props so they\n  // land on the role=\"textbox\" element that actually needs the name.\n  'aria-label': ariaLabel,\n  'aria-labelledby': ariaLabelledBy,\n  ...props\n}, ref) => {\n  const [saving, setSaving] = React.useState(false)\n  const [focused, setFocused] = React.useState(false)\n  const editRef = React.useRef<HTMLSpanElement>(null)\n  const snapshotRef = React.useRef(value)\n\n  const isSaving = savingProp || saving\n  const isEmpty = !value\n\n  // Sync DOM text when value changes externally (and not focused)\n  React.useEffect(() => {\n    if (!focused && editRef.current) {\n      editRef.current.textContent = value\n    }\n  }, [value, focused])\n\n  function handleFocus() {\n    if (readOnly || isSaving) return\n    setFocused(true)\n    snapshotRef.current = value\n\n    // Select all text on focus (like clicking a file name in Finder)\n    requestAnimationFrame(() => {\n      if (!editRef.current) return\n      const range = document.createRange()\n      range.selectNodeContents(editRef.current)\n      const sel = window.getSelection()\n      sel?.removeAllRanges()\n      sel?.addRange(range)\n    })\n  }\n\n  async function commit() {\n    if (!editRef.current) return\n    setFocused(false)\n    const raw = editRef.current.textContent ?? ''\n    const trimmed = raw.trim()\n\n    // Enforce maxLength\n    const final = maxLength ? trimmed.slice(0, maxLength) : trimmed\n\n    // Reset DOM to clean value\n    editRef.current.textContent = final || value\n\n    if (final === value) return\n    const result = onSave(final)\n    if (result instanceof Promise) {\n      setSaving(true)\n      try {\n        await result\n      } catch {\n        // Revert on error\n        if (editRef.current) editRef.current.textContent = value\n      } finally {\n        setSaving(false)\n      }\n    }\n  }\n\n  function cancel() {\n    if (!editRef.current) return\n    editRef.current.textContent = snapshotRef.current\n    setFocused(false)\n    editRef.current.blur()\n  }\n\n  function handleKeyDown(e: React.KeyboardEvent) {\n    if (e.key === 'Escape') {\n      e.preventDefault()\n      cancel()\n    } else if (e.key === 'Enter') {\n      e.preventDefault()\n      commit()\n    }\n  }\n\n  function handleInput() {\n    if (!editRef.current || !maxLength) return\n    const text = editRef.current.textContent ?? ''\n    if (text.length > maxLength) {\n      editRef.current.textContent = text.slice(0, maxLength)\n      // Move cursor to end\n      const range = document.createRange()\n      range.selectNodeContents(editRef.current)\n      range.collapse(false)\n      const sel = window.getSelection()\n      sel?.removeAllRanges()\n      sel?.addRange(range)\n    }\n  }\n\n  // Prevent paste from inserting rich content\n  function handlePaste(e: React.ClipboardEvent) {\n    e.preventDefault()\n    const text = e.clipboardData.getData('text/plain')\n    document.execCommand('insertText', false, text)\n  }\n\n  return (\n    <div ref={ref} className={cn('group inline-flex items-center gap-ds-02', className)} {...props}>\n      <span\n        ref={editRef}\n        role={readOnly ? undefined : 'textbox'}\n        contentEditable={!readOnly && !isSaving}\n        suppressContentEditableWarning\n        tabIndex={readOnly ? undefined : 0}\n        // Fall back to the placeholder when no explicit label is supplied —\n        // screen readers need _something_ on role=\"textbox\".\n        aria-label={readOnly ? undefined : (ariaLabel ?? (ariaLabelledBy ? undefined : placeholder))}\n        aria-labelledby={readOnly ? undefined : ariaLabelledBy}\n        onFocus={handleFocus}\n        onBlur={commit}\n        onKeyDown={handleKeyDown}\n        onInput={handleInput}\n        onPaste={handlePaste}\n        spellCheck={focused}\n        className={cn(\n          'font-sans text-surface-fg outline-hidden',\n          textClassName,\n          // Idle: subtle hover hint\n          !readOnly && !focused && 'cursor-text rounded-ds-sm -mx-ds-01 px-ds-01 hover:bg-surface-raised-hover transition-colors duration-fast-01',\n          // Focused: subtle underline to indicate editing\n          focused && 'rounded-ds-sm -mx-ds-01 px-ds-01 bg-surface-raised-hover ring-1 ring-accent-7',\n          // Empty: show placeholder styling\n          isEmpty && !focused && 'text-surface-fg-subtle italic',\n          // Read-only\n          readOnly && 'cursor-default',\n        )}\n        data-placeholder={placeholder}\n      >\n        {value || (focused ? '' : placeholder)}\n      </span>\n      {!readOnly && !focused && !isSaving && (\n        <Icon icon={IconPencil} size=\"xs\" className=\"text-surface-fg-subtle opacity-0 group-hover:opacity-100 transition-opacity duration-fast-01 shrink-0\" />\n      )}\n      {isSaving && <Spinner size=\"sm\" />}\n    </div>\n  )\n})\nInlineEdit.displayName = 'InlineEdit'\n\nexport { InlineEdit }\n"],"mappings":"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"}

package/dist/test-utils/conformance.d.ts

@@ -0,0 +1,37 @@
+"use client";
+import * as React from 'react';
+/**
+ * Shared conformance test suite for design-system components.
+ *
+ * Runs the orthogonal checks that every component must satisfy (ref forwarding,
+ * className merging, HTML attribute spread, axe audit, variant/size/color smoke
+ * checks). Replaces per-file repetition of the same tests.
+ *
+ * Modelled on Base UI's `describeConformance` and Mantine's
+ * `itSupportsSystemProps` — one helper call per component instead of N tests per
+ * prop per file.
+ */
+export interface ConformanceOptions {
+    /** Smoke-test that each variant renders without throwing. Pass the exact list from CVA. */
+    variants?: readonly string[];
+    /** Smoke-test that each size renders without throwing. */
+    sizes?: readonly string[];
+    /** Smoke-test that each color/intent renders without throwing. */
+    colors?: readonly string[];
+    /** Skip specific checks when they don't apply (e.g. `['ref']` for components that don't forwardRef). */
+    skip?: ReadonlyArray<'ref' | 'className' | 'attrs' | 'axe' | 'variants' | 'sizes' | 'colors'>;
+}
+type RenderFn = (props?: Record<string, unknown>) => React.ReactElement;
+/**
+ * Registers a `describe('conformance')` block in the caller's test file.
+ *
+ * @example
+ * describeConformance('Button', (props) => <Button {...props}>hi</Button>, {
+ *   variants: ['solid', 'soft', 'outline', 'ghost', 'link'],
+ *   sizes: ['xs', 'sm', 'md', 'lg'],
+ *   colors: ['accent', 'error', 'success', 'warning', 'neutral'],
+ * })
+ */
+export declare function describeConformance(name: string, renderComponent: RenderFn, options?: ConformanceOptions): void;
+export {};
+//# sourceMappingURL=conformance.d.ts.map

package/dist/test-utils/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/test-utils/conformance.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,kBAAkB;IACjC,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,kEAAkE;IAClE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,wGAAwG;IACxG,IAAI,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,WAAW,GAAG,OAAO,GAAG,KAAK,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,CAAA;CAC9F;AAED,KAAK,QAAQ,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,KAAK,CAAC,YAAY,CAAA;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,QAAQ,EACzB,OAAO,GAAE,kBAAuB,QAoEjC"}

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

@@ -35,6 +35,12 @@
 ## Exported Utilities
     groupItemsByTime(items: ActivityItem[], labels?: GroupLabels) — pure function that buckets items into time groups; returns { label: string, items: ActivityItem[] }[]
 
+## Composability
+- **Built from ui primitives:** Avatar (actor), Button (Load more), Skeleton (loading), Text (body). Override via `renderItem` to use your own primitives per row.
+- **renderItem** is the composition hook — return your own JSX or `undefined` to fall back to default ActivityEntry. Timeline dot + layout wrapper stay consistent.
+- **groupBy="time"** wraps items in Today/Yesterday/This Week/Older buckets; `groupItemsByTime()` export reusable for custom renderers.
+- **Pagination is consumer-driven** — `hasMore` + `onLoadMore` for server-side, or `maxInitialItems` + "Show all" toggle for client-side truncation.
+
 ## Gotchas
 - `items` is required — passing an empty array renders the `emptyState` content
 - `color` on each item controls the timeline dot color

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

@@ -38,6 +38,14 @@
 />
 ```
 
+## Composability
+- **Built on ui/Avatar** — each slot is an Avatar with overlap + border + optional Tooltip.
+- **Wraps TooltipProvider internally** — don't add another.
+- **renderAvatar** escape hatch for custom shapes. Wrapper handles overlap/border positioning; your renderer sets size + shape.
+- **borderColor** must match the surface the group sits on (`surface-raised` on Card, `surface-base` on page bg). Mismatch = visible seam.
+- **Overflow:** +N badge with optional `onOverflowClick` → pair with a Popover/Sheet for "show all members".
+- Per-user `ring` (lead/admin/client) surfaces Avatar's ring semantic at group level — use for role/presence hints.
+
 ## Gotchas
 - Wraps TooltipProvider internally — no need to add one yourself
 - Users beyond `max` are collapsed into a "+N" overflow badge

package/docs/components/composed/bulk-action-bar.md

@@ -34,6 +34,12 @@
 />
 ```
 
+## Composability
+- **Standalone floating toolbar** — use with DataTable, TreeView, or any selection-capable UI.
+- **DataTable auto-integration:** DataTable's `bulkActions` prop renders this internally — typically you don't render BulkActionBar directly when using DataTable.
+- **Data-driven actions:** `{ label, icon, onClick, color, disabled }[]`. For destructive confirmation, call ConfirmDialog from the onClick handler.
+- **Portal to body + fixed bottom-center z-50** — independent of parent layout. Check for other fixed elements that might overlap.
+
 ## Gotchas
 - Renders via `createPortal` into `document.body` — will not appear during SSR (mounts only client-side)
 - Positioned fixed at bottom-center with `z-50`; ensure no other fixed elements conflict

package/docs/components/composed/command-palette.md

@@ -25,6 +25,13 @@ CommandItem shape: { id, label, description?, icon?, shortcut?, onSelect: () =>
 />
 ```
 
+## Composability
+- **Built on Dialog (portal) + cmdk-style fuzzy matching.** Global Ctrl+K / Cmd+K by default; customize via `keybinding`.
+- **Groups + items are data-driven.** Each item: `{ id, label, icon?, shortcut?, description?, onSelect }`. Labels accept ReactNode for rich rendering; pair with `filterValue` for typeahead matching against a text representation.
+- **renderLabel hook** lets you highlight matched characters in query (`(query) => ReactNode`).
+- **Controlled / uncontrolled** via `open`+`onOpenChange` or `defaultOpen`.
+- **AppCommandPalette (shell)** is the app-wide variant with CommandRegistry — use that for global palettes with dynamically registered commands.
+
 ## Gotchas
 - Opens with Ctrl+K / Cmd+K by default
 - Items animate in with staggered slide-up (30ms delay cascade); groups fade in; active item icon/shortcut highlight in interactive color (v0.15.0)

package/docs/components/composed/confirm-dialog.md

@@ -33,6 +33,12 @@ const [open, setOpen] = useState(false)
 />
 ```
 
+## Composability
+- **Built on AlertDialog** — non-dismissible (no click-outside, Cancel-first focus), portal-rendered.
+- **Controlled-only.** Parent owns `open` + `onOpenChange`.
+- **onConfirm can be async.** `loading=true` replaces confirm text with "Processing..." and disables both buttons. Typical: setLoading(true) → await action() → setLoading(false) + setOpen(false).
+- **Stays open after confirm** — close via onOpenChange. Keeps the modal up on errors or for chained confirmations.
+
 ## Gotchas
 - Dialog stays open after confirm — consumer must close it via `onOpenChange`
 - Built on AlertDialog internally

package/docs/components/composed/content-card.md

@@ -23,6 +23,12 @@
 </ContentCard>
 ```
 
+## Composability
+- **Server-safe higher-level Card** — wraps ui/Card with conventional header/title/actions/footer slots.
+- **When to use:** List rows, dashboard tiles, any "card with title + optional actions + body + optional footer" pattern. Use raw ui/Card for custom layouts or when you need accent bars.
+- **Slot precedence:** `header` beats `headerTitle`. Use `headerTitle` for simple strings, `header` for rich content.
+- **padding variants** (default/compact/spacious/none) set once on ContentCard; the underlying Card size cascade propagates.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - Use `headerTitle` for simple text headers; use `header` for custom header content

package/docs/components/composed/date-picker.md

@@ -111,6 +111,16 @@ PresetKey: 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisMonth' | 'l
 <TimePicker value={time} onChange={setTime} format="24h" minuteStep={15} />
 ```
 
+## Composability
+- **7 sub-components in one kit:** DatePicker, DateRangePicker, DateTimePicker, TimePicker, CalendarGrid, MonthPicker, YearPicker, Presets. Built on Popover (trigger + calendar content) + date-fns.
+- **Layered abstractions:**
+  - High-level: DatePicker / DateRangePicker / DateTimePicker / TimePicker (use these 95% of the time — Popover-wrapped, single-field pickers with formatted value display).
+  - Low-level: CalendarGrid / MonthPicker / YearPicker (use for custom picker layouts, inline calendars, dashboards with embedded date selection).
+- **useCalendar hook** manages month navigation state — use it when building custom picker UI (e.g. inline calendar with custom header).
+- **Presets component** is standalone — drop it next to a DateRangePicker's calendar for quick-select sidebars (Today / Last 7 days / This month / etc.).
+- **Events on calendar:** CalendarGrid accepts `events: { date, color, label }[]` — renders up to 3 colored dots per day cell. Useful for availability / booked-days highlights.
+- **min/max/disabledDates** are shared contract across the whole family — pass the same bounds config to any date picker variant.
+
 ## Gotchas
 - TimePicker stores time inside a Date object — only hours/minutes/seconds are meaningful
 - CalendarGrid is a low-level building block — prefer DatePicker/DateRangePicker for most use cases

package/docs/components/composed/deadline-indicator.md

@@ -21,6 +21,13 @@
 <DeadlineIndicator deadline={task.dueDate} warningThreshold={2880} criticalThreshold={480} />
 ```
 
+## Composability
+- **Server-safe inline status** — renders a colored text label ("2d left" / "3h left" / "Overdue by 1d") with optional clock icon prefix.
+- **Threshold-driven color:** `warningThreshold` + `criticalThreshold` drive the green→yellow→red progression. Tune per use case (billing deadlines vs. task due dates have different urgency cadences).
+- **Composes inside Card, StatusBadge, DataTable cells** — anywhere a short inline deadline string fits.
+- **Doesn't live-update** — uses `Date.now()` at render time. For ticking timestamps, re-render via a parent interval or use a dedicated "time ago" library.
+- For static absolute timestamps (not relative), set `format="absolute"` — useful when you want the exact date rendered with semantic color coding.
+
 ## Gotchas
 - Color is semantic: green (on-track) -> yellow (warning threshold) -> red (critical/overdue)
 - Overdue deadlines show bold red text with "Overdue by Xd/h/m"

package/docs/components/composed/emoji-picker.md

@@ -37,6 +37,14 @@ EmojiPicker, EmojiPickerPopover
 <EmojiPicker onSelect={handleEmoji} theme="dark" />
 ```
 
+## Composability
+- **Two exports:** `EmojiPicker` (inline grid, no trigger) and `EmojiPickerPopover` (trigger + popover wrapper). Use EmojiPickerPopover 95% of the time — trigger-on-click is the standard UX.
+- **Wraps @emoji-mart/react**, lazy-loaded with a Skeleton placeholder while the ~200KB bundle fetches. Don't pre-import unless you need it eagerly.
+- **Trigger composition:** EmojiPickerPopover's `children` is the trigger — wrap any Button/IconButton. Typical pairing is an icon-only IconButton with a 😀 label.
+- **TipTap integration:** Use `createEmojiSuggestion(set?)` factory to create a TipTap suggestion plugin that opens the picker on typing `:emoji`. Works with RichChatInput and RichTextEditor.
+- **Theme matching:** `theme="auto"` reads the `.dark` class on `<html>` — matches the DS dark mode toggle automatically. Override with explicit light/dark.
+- **Emoji sets:** Pass `set="apple" | "google" | ...` for consistent cross-platform emoji art (defaults to native OS glyphs).
+
 ## Gotchas
 - Wraps `@emoji-mart/react` which is lazy-loaded — shows a Skeleton placeholder while loading
 - `theme="auto"` reads the `.dark` class on `<html>` to pick light/dark

package/docs/components/composed/empty-state.md

@@ -27,6 +27,14 @@ Note: EmptyState was server-safe prior to v0.18.0 but is NO LONGER server-safe d
 />
 ```
 
+## Composability
+- **Centered block for "no data" / "no results" states.** Renders icon + title + description + optional action slot.
+- **Icon composition:** Accepts both JSX (`<IconFolder />`) and component references (`IconFolder`). Component refs auto-instantiate with correct sizing. Default icon is the Devalok chakra.
+- **DataTable integration:** Pass an EmptyState component to DataTable's `emptyState` prop; takes precedence over `noResultsText` string.
+- **compact mode** for embedding inside Cards, sidebars, narrow sections. Defaults iconSize to 'sm' in compact mode automatically.
+- **Action slot** typically holds a single primary Button ("Create your first task", "Invite members"). For multi-action, use a div + flex with gap.
+- No longer server-safe (Framer Motion entrance animation).
+
 ## Gotchas
 - `icon` accepts both JSX elements (`<IconFolder />`) and component references (`IconFolder`). Component references are auto-instantiated with correct sizing classes.
 - `iconSize` controls icon dimensions regardless of icon type. When `compact=true` and no `iconSize`, defaults to `'sm'`.

package/docs/components/composed/error-boundary.md

@@ -16,6 +16,13 @@
 <ErrorDisplay error={error} onReset={() => refetch()} />
 ```
 
+## Composability
+- **ErrorDisplay, not ErrorBoundary** — confusingly, the import path is `error-boundary` but the component is `ErrorDisplay`. It renders an error UI; it does NOT catch errors. Pair it with your own ErrorBoundary (from react-error-boundary, Next.js error.tsx, etc.) as the fallback UI.
+- **Auto-detects HTTP status codes** (404, 403, 500) when the `error` object has a `status` field — shows appropriate icon + message.
+- **Dev-only stack trace:** Renders the stack trace only when `process.env.NODE_ENV !== 'production'`. Production users see a clean error page.
+- **onReset for retry:** Pass a callback that re-fetches / resets state. Commonly wired to a react-query `refetch` or router `replace(...)`.
+- Composes with EmptyState for "no data" states (which aren't really errors) — use EmptyState for empty, ErrorDisplay for failed.
+
 ## Gotchas
 - Auto-detects HTTP status codes (404, 403, 500) and shows appropriate icon/message
 - Shows stack trace in development mode only

package/docs/components/composed/file-preview.md

@@ -32,6 +32,14 @@
 <FilePreview url="https://youtube.com/watch?v=..." />
 ```
 
+## Composability
+- **Type-auto-detection** from URL + mimeType routes to the right renderer (image / pdf / video / audio / embed). For ambiguous URLs, pass `type` explicitly.
+- **Heavy deps are lazy-loaded** — react-pdf (PDF), react-zoom-pan-pinch (Image zoom) are only fetched when first needed. Skeleton placeholder while loading. Don't pre-import.
+- **Composes inside Dialog/Sheet** — common pattern: thumbnail in a list → click to open a Dialog with `<FilePreview>` filling it.
+- **Embed URL normalization:** YouTube/Vimeo/Figma/Loom URLs auto-convert to embed format. Pass the original share URL; FilePreview handles it.
+- **PDF worker from unpkg CDN** — for offline apps, override `pdfjs.GlobalWorkerOptions.workerSrc` in your app entry.
+- **Download + error fallback** built in — if the file fails to load, users still get a download link.
+
 ## Gotchas
 - Image/PDF lazy-loaded (Skeleton on first render)
 - PDF worker from unpkg CDN — configure workerSrc for offline apps

package/docs/components/composed/filter-bar.md

@@ -51,6 +51,14 @@ FilterBar, FilterSelect, FilterMultiSelect
 </FilterBar>
 ```
 
+## Composability
+- **FilterBar + FilterSelect + FilterMultiSelect** — three-part kit. FilterBar is the toolbar container; FilterSelect/FilterMultiSelect are the individual filter controls.
+- **size propagates via context** from FilterBar to every FilterSelect/FilterMultiSelect child. Don't set size on individual filters.
+- **Children MUST be direct** — the size cascade breaks if filters are wrapped in extra divs. Use React fragments or let them be direct children.
+- **Active filter highlight:** FilterSelect/FilterMultiSelect auto-show an accent border when their value is set (non-empty array for multi, non-"all" for single).
+- **Pair with DataTable or any list:** FilterBar sits above a DataTable/list; `searchValue` + `onSearchChange` drive global filter; individual filters drive column filters via your own state management.
+- **"Clear all" convention:** Passing `onClearAll` renders a Reset button that's your escape hatch — implement it to clear all filter state in one call.
+
 ## Gotchas
 - FilterSelect and FilterMultiSelect must be direct children of FilterBar to inherit the size context
 - FilterSelect uses `"all"` as the sentinel value for "no filter" — do not use `"all"` as a real option value

package/docs/components/composed/form-section.md

@@ -26,6 +26,12 @@
 </FormSection>
 ```
 
+## Composability
+- **Visual grouping of related FormFields.** Wraps its children with a title + description + horizontal rule separator. No state, no context.
+- **collapsible mode** wraps content in a Collapsible — useful for "Advanced settings" or optional form sections. `defaultOpen={false}` for initially-closed.
+- **Pairs with FormField:** Each form control inside should be a FormField for consistent label + helper text + validation. FormSection doesn't auto-wrap; you still structure each field yourself.
+- **Not a page-level header** — for a full form's main heading use PageHeader. FormSection is mid-form, between field groups.
+
 ## Gotchas
 - `defaultOpen` only applies when `collapsible={true}` — otherwise the section is always open
 - Renders a horizontal rule between the header and content automatically

package/docs/components/composed/global-loading.md

@@ -15,6 +15,12 @@
 <GlobalLoading isLoading={isNavigating} />
 ```
 
+## Composability
+- **Thin top-of-viewport progress bar** — for route-level navigation indicators (NProgress-style). Fixed at the top; z-toast layer.
+- **Wire to router events:** Pair with Next.js `useRouter` + navigation events, or react-router's `useNavigation`, or a custom global loading state in Redux/Zustand. Set `isLoading={true}` during transit, `false` when landed.
+- **Not for in-page loading** — use Spinner, Skeleton, or LoadingSkeleton for component-level loading states. GlobalLoading is strictly for cross-route / full-page transitions.
+- **Auto-unmounts when isLoading=false** — no need to manage visibility via classes or conditional rendering.
+
 ## Gotchas
 - Fixed-position bar at top of viewport (z-toast layer)
 - Renders nothing when `isLoading` is false

package/docs/components/composed/inline-edit.md

@@ -25,6 +25,14 @@
 />
 ```
 
+## Composability
+- **contentEditable-based** — the text IS the editor (Notion / Linear / Figma layer-name pattern). No separate input field appears.
+- **Keyboard contract:** Click to focus (auto-selects text, like Finder rename). Type to edit. Enter saves, Escape reverts. Paste strips rich content.
+- **Async save:** `onSave` can return a Promise — InlineEdit shows a spinner and disables editing while pending. On rejection, text reverts to the original value automatically.
+- **Accessibility:** Accepts `aria-label` and `aria-labelledby` (forwarded to the role="textbox" span) — required when the text isn't self-descriptive. Falls back to `placeholder` as label when neither is provided.
+- **Not inside FormField** — InlineEdit is for in-place editing of existing content (task title, project name); use regular FormField + Input for traditional forms.
+- **textClassName for typography control:** Pass `"text-ds-lg font-semibold"` to make it look like a heading without changing the underlying element.
+
 ## Gotchas
 - Uses contentEditable — the text IS the editor. No input field appears.
 - Click to focus → cursor appears in text. Type to edit. Enter saves. Escape reverts.

package/docs/components/composed/loading-skeleton.md

@@ -39,6 +39,13 @@ Exports: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton
 <ListSkeleton rows={10} showAvatar={false} />
 ```
 
+## Composability
+- **Pre-composed skeleton layouts** — CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton. Each mimics the shape of a common DS layout so users see meaningful loading placeholders.
+- **Built on ui/Skeleton** — for custom loading layouts, use Skeleton directly (rectangle/circle/text variants). These composed versions are just opinionated shape combinations.
+- **Server-safe** — use during SSR for initial-paint skeletons in Next.js app router (while server data streams in).
+- **Pairs with conditional rendering:** `{isLoading ? <TableSkeleton rows={8} /> : <DataTable data={rows} />}`.
+- **PageSkeletons (separate file)** provides full-page placeholders (DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton) — use those for route-level loading states.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - These are pre-composed skeleton layouts — for individual skeleton shapes, use the `Skeleton` UI component

package/docs/components/composed/markdown-viewer.md

@@ -20,6 +20,15 @@
 <MarkdownViewer content={trustedHtml} allowHtml />
 ```
 
+## Composability
+- **Read-only markdown renderer.** For editing, use RichTextEditor (TipTap-based). MarkdownViewer is strictly for display.
+- **Built on react-markdown + remark-gfm** — GFM tables, strikethrough, task lists supported out of the box.
+- **Syntax highlighting is lazy:** Code blocks with a language fence (```ts, ```python) lazy-load react-syntax-highlighter. First render shows a plain `<pre>` fallback. Don't pre-import.
+- **Security posture:** Raw HTML is stripped by default — `allowHtml={true}` must be explicit, and ONLY for trusted content (XSS vector otherwise).
+- **Links open external by default** (`target="_blank"` + `rel="noopener noreferrer"`). Override via `linkTarget`.
+- **compact mode** for inline use (comments, message bubbles). Default spacing is for article-body content.
+- **Pairs with Chat's Message.Body** — render markdown from user messages safely. Always keep `allowHtml={false}` for user-generated content.
+
 ## Gotchas
 - Code blocks with a language fence are syntax-highlighted via `react-syntax-highlighter` (lazy-loaded) — the first render shows a plain `<pre>` fallback
 - GFM (tables, strikethrough, task lists) is supported via `remark-gfm`

package/docs/components/composed/master-detail.md

@@ -42,6 +42,13 @@ MasterDetail (root), MasterDetail.List, MasterDetail.Detail, MasterDetail.ListIt
 </MasterDetail>
 ```
 
+## Composability
+- **Responsive list+detail layout.** Desktop: side-by-side panels. Mobile (below `breakpoint`): stacked, mutually exclusive (list OR detail, controlled by `selected`).
+- **Compound structure:** `MasterDetail.List` contains `MasterDetail.ListItem[]` (interactive). `MasterDetail.Detail` holds the currently-selected view.
+- **onBack is required for mobile** — renders the back button in Detail pane. Omitting it leaves users stranded once they drill into an item on mobile.
+- **SSR gotcha:** Uses `window.matchMedia` — initial SSR render picks desktop mode; hydrates to mobile mode if viewport is narrow. If that causes layout shift, consider rendering this only after mount (via `useState(false)` + `useEffect`).
+- **Pairs with EmptyState** — render EmptyState inside Detail when `selected === null` on desktop ("Pick an item to get started").
+
 ## Gotchas
 - On mobile (below breakpoint), List and Detail are mutually exclusive — selecting an item hides the list
 - The `onBack` callback is required for the mobile back button to appear in the Detail pane

package/docs/components/composed/member-picker.md

@@ -22,6 +22,13 @@
 </MemberPicker>
 ```
 
+## Composability
+- **Trigger + Popover + search list.** Pass any button/element as `children` to act as the trigger. Typical pairing: outline Button that says "Assign" or an IconButton with avatar overflow.
+- **Single vs multi:** `multiple={true}` allows multiple selections; `false` (default) replaces the previous selection. `selectedIds` is always an array in both modes — consumer controls semantics.
+- **onSelect with a single ID:** Fires once per click with one memberId. Toggle logic in multi mode is consumer responsibility (derive the new array from the click).
+- **Avatar display:** Uses ui/Avatar internally — supply `avatar` URL in the member object, fallback to initials from `name`.
+- **For general-purpose multi-select** (non-members), use MultiSelectPopover which has the same popover+search pattern without member-specific avatar rendering.
+
 ## Gotchas
 - `children` is used as the trigger element (e.g., a Button)
 - `onSelect` is called with a single `memberId` — toggle logic is up to the consumer

package/docs/components/composed/multi-select-popover.md

@@ -47,6 +47,17 @@
 </MultiSelectPopover>
 ```
 
+## Composability
+- **Generalized multi-select popover** — picks from a fixed list (items) or grouped list (groups), with search, async search, and custom rendering.
+- **Items vs groups (mutually exclusive):** Pass `items` for flat lists, `groups` for sectioned lists. Don't pass both.
+- **Async search via onSearch:** When provided, local filtering is disabled — the callback owns filtering and returns a new list. `searchDebounce` (default 300ms) throttles calls.
+- **renderItem escape hatch:** Pass `(item, selected) => ReactNode` for custom item rendering (avatar + multi-line descriptions, etc.). Built-in default renders image + label + description.
+- **maxSelections behavior:** At the limit, clicking a new item REPLACES the oldest selection (FIFO). `maxSelections={1}` effectively acts as single-select.
+- **MultiSelectPopover vs Combobox vs MemberPicker:**
+  - Combobox = form-field multi-select (typeahead + selection in place)
+  - MultiSelectPopover = button-triggered popup for bulk selection (good for "Assign to" / "Add tags" scenarios)
+  - MemberPicker = MultiSelectPopover specialized for team-member UI
+
 ## Gotchas
 - Supply either `items` (flat) or `groups` (sectioned), not both
 - When `onSearch` is provided, local filtering is disabled — the callback must return results

package/docs/components/composed/page-header.md

@@ -28,6 +28,13 @@
 />
 ```
 
+## Composability
+- **Server-safe page-top header** with title + subtitle + breadcrumbs + actions slot. Renders Breadcrumb internally from the `breadcrumbs` array.
+- **Auto-derived title:** If `title` is omitted, the last breadcrumb's `label` becomes the h1. Saves duplication when the page title matches the breadcrumb leaf.
+- **Breadcrumb contract:** Last item should NOT have an `href` (it's the current page — renders as BreadcrumbPage, not a link). Items with `href` render as BreadcrumbLink.
+- **actions slot:** Typically one to three buttons (Save, Cancel, More). For larger action groups, use ButtonGroup or a toolbar.
+- **Not for tabs / sub-navigation** — pair with Tabs rendered below PageHeader for that.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - If `title` is omitted, the last breadcrumb's `label` is used as the page title

package/docs/components/composed/page-skeletons.md

@@ -19,6 +19,16 @@ Exports: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton
 <TaskDetailSkeleton />
 ```
 
+## Composability
+- **Full-page skeleton layouts** for route-level loading states. Each mimics a common page shape (dashboard tiles, project list with filters, task detail with sidebar).
+- **Server-safe** — use in Next.js app router `loading.tsx` files for instant route-transition feedback while data streams.
+- **Built on LoadingSkeleton + ui/Skeleton** — these just assemble the pre-built regional skeletons into page-shaped layouts.
+- **When to use which skeleton tier:**
+  - `<Skeleton>` (ui) — single shape for a single element
+  - `<CardSkeleton>` / `<TableSkeleton>` (LoadingSkeleton) — individual region shape
+  - `<DashboardSkeleton>` / etc. (PageSkeletons) — full page placeholder
+- **Fixed layout structure** — the className prop adjusts the outer container, but internal layout isn't customizable. For custom page skeletons, compose LoadingSkeleton pieces yourself.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - These are full-page skeleton layouts — for smaller skeleton sections, use LoadingSkeleton components

package/docs/components/composed/priority-indicator.md

@@ -19,6 +19,13 @@ Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'u
 <PriorityIndicator priority="low" display="compact" />
 ```
 
+## Composability
+- **Server-safe priority label** — icon + color + text for task / issue priority.
+- **Composes inside list rows, DataTable cells, Card headers, task panels** — anywhere a priority flag fits.
+- **display="compact"** shows only the icon (with priority text as title attribute for tooltip). Use in tight cells; use `display="full"` (default) in free space.
+- **Case-insensitive priority** — accepts both UPPERCASE (LOW/MEDIUM/HIGH/URGENT) and lowercase. Designed to match both backend conventions without manual coercion.
+- Color semantics: LOW=success, MEDIUM=warning, HIGH=error, URGENT=error with bolder icon.
+
 ## Gotchas
 - Case-insensitive — "low" and "LOW" both work
 - Server-safe: can be imported directly in Next.js Server Components