twico-ui 1.43.0 → 1.45.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to Twico UI are documented here (newest first). This file is generated automatically on each release by [semantic-release](https://semantic-release.gitbook.io/) from [Conventional Commits](https://www.conventionalcommits.org/) — do not edit it by hand. The same notes appear on each [GitHub Release](https://github.com/EncryptionL/twico-ui/releases).
 
+# [1.45.0](https://github.com/EncryptionL/twico-ui/compare/v1.44.0...v1.45.0) (2026-10-16)
+
+
+### Bug Fixes
+
+* **datatable:** lift getRowStyle's background off the <tr> instead of copying it ([e54165e](https://github.com/EncryptionL/twico-ui/commit/e54165e918dad9d8f0f819890ebb718684bdfc07)), closes [#242](https://github.com/EncryptionL/twico-ui/issues/242) [#481](https://github.com/EncryptionL/twico-ui/issues/481)
+
+
+### Features
+
+* **datatable:** getRowStyle / getRowClassName — row-level style hooks ([56a80e8](https://github.com/EncryptionL/twico-ui/commit/56a80e8c7adeb293923b5f2e490cf62234df3a3a)), closes [#345](https://github.com/EncryptionL/twico-ui/issues/345) [#242](https://github.com/EncryptionL/twico-ui/issues/242)
+
+# [1.44.0](https://github.com/EncryptionL/twico-ui/compare/v1.43.0...v1.44.0) (2026-10-16)
+
+
+### Features
+
+* **cardgrid,datatable:** selection + batch actions on CardGrid, disabledReason on batch actions ([dac8b30](https://github.com/EncryptionL/twico-ui/commit/dac8b30a36ad3387e09678435803dfaf474e02dd)), closes [#478](https://github.com/EncryptionL/twico-ui/issues/478) [#479](https://github.com/EncryptionL/twico-ui/issues/479) [#322](https://github.com/EncryptionL/twico-ui/issues/322) [399/#419](https://github.com/EncryptionL/twico-ui/issues/419) [pre-#460](https://github.com/pre-/issues/460)
+
 # [1.43.0](https://github.com/EncryptionL/twico-ui/compare/v1.42.1...v1.43.0) (2026-10-07)
 
 

package/dist/index.cjs

@@ -7248,8 +7248,8 @@ function Currency({
 }
 function useFallbackName(ref, hasOwnName) {
   const [needsFallback, setNeedsFallback] = React54__namespace.default.useState(false);
-  const useIso3 = typeof document !== "undefined" ? React54__namespace.default.useLayoutEffect : React54__namespace.default.useEffect;
-  useIso3(() => {
+  const useIso2 = typeof document !== "undefined" ? React54__namespace.default.useLayoutEffect : React54__namespace.default.useEffect;
+  useIso2(() => {
     if (hasOwnName) {
       setNeedsFallback(false);
       return;
@@ -7265,7 +7265,6 @@ function useFallbackName(ref, hasOwnName) {
   });
   return !hasOwnName && needsFallback;
 }
-typeof document !== "undefined" ? React54__namespace.default.useLayoutEffect : React54__namespace.default.useEffect;
 var SELECT_CSS = `
 .twc-field { display: flex; flex-direction: column; gap: var(--space-1-5); font-family: var(--font-sans); }
 .twc-field__label { font-size: var(--text-sm); font-weight: var(--font-semibold); color: var(--color-text); display: flex; gap: 4px; align-items: center; }
@@ -9253,8 +9252,22 @@ var DT_CSS = `
 .twc-dt__row:hover .twc-dt__row-resizer::after { background: var(--color-border-strong); }
 .twc-dt__row-resizer:hover::after { background: var(--color-primary); }
 
+/* #481: the cell background reads --twc-dt-row-bg, which getRowStyle sets on the <tr>. It has to come
+   through a custom property rather than straight off the row, because this rule paints an OPAQUE
+   --color-surface on every cell: a background set on the <tr> would sit behind it and never show,
+   which would make the commonest use of a row-style hook silently do nothing. Cells in a pinned
+   COLUMN inherit it too, so a tinted row does not develop a hole where a sticky column scrolls over
+   it.
+   Layering: this rule is (0,1,0), the LOWEST specificity of any background in this sheet, so the
+   row tint is the bottom layer above the plain surface and every built-in state covers it - hover,
+   row selection, data-active, data-pinned-row, data-row-grabbed, the diff data-op washes, cell
+   selection/active, inline editing (each (0,3,0), (0,4,0) for the pinned-column twins, or (0,2,0)
+   for the cell-level ones) - and an inline per-cell cellStyle
+   covers them all. That is the intended rule, not an accident of ordering: a row tint is a
+   data-derived wash, and no data wash should be able to hide an interaction state. Consumers who
+   need a tint that outranks those use getRowClassName and a rule of their own. */
 .twc-dt__td { padding: 0 12px; height: var(--_rowh, 44px); border-bottom: var(--border-thin) solid var(--color-divider);
-  font-size: var(--text-sm); color: var(--color-text); background: var(--color-surface);
+  font-size: var(--text-sm); color: var(--color-text); background: var(--twc-dt-row-bg, var(--color-surface));
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 0; }
 /* Wrap-text columns: content flows onto multiple lines (the row grows down) instead of
    clipping to one line. height stays a per-row minimum, so single-line cells are unchanged. */
@@ -10021,6 +10034,8 @@ function Datatable({
   onColumnVisibilityChange,
   batchActions = [],
   onRowSelectionChange,
+  getRowStyle,
+  getRowClassName,
   showExport = false,
   showDensity = false,
   showPivot = false,
@@ -12596,7 +12611,17 @@ function Datatable({
     const rowActive = selectionMode === "row" && activeRowVal === k;
     const stickyStyle = pinSide === "top" ? { position: "sticky", top: headH, zIndex: 5 } : pinSide === "bottom" ? { position: "sticky", bottom: 0, zIndex: 5 } : void 0;
     const h = rowHeights[k];
-    const rowStyle = { ...stickyStyle || {}, ...h ? { height: h } : {} };
+    const userRowStyle = getRowStyle ? getRowStyle(row, ri) : void 0;
+    const userRowClass = getRowClassName ? getRowClassName(row, ri) : void 0;
+    const { background: _rowBgShorthand, backgroundColor: _rowBgColor, ...restRowStyle } = userRowStyle || {};
+    const usable = (v) => typeof v === "string" && v.trim() !== "" ? v : void 0;
+    const rowBg = usable(_rowBgShorthand) ?? usable(_rowBgColor);
+    const rowStyle = {
+      ...restRowStyle,
+      ...rowBg != null ? { "--twc-dt-row-bg": rowBg } : {},
+      ...stickyStyle || {},
+      ...h ? { height: h } : {}
+    };
     const reorderable = canReorderRows && !pinSide;
     const grabbed = rowGrab && rowGrab.key === k;
     const grabTarget = rowGrab && !grabbed && midIdx != null && rowGrab.index === midIdx ? rowGrab.index >= keyIndexMid.get(rowGrab.key) ? "after" : "before" : void 0;
@@ -12604,7 +12629,7 @@ function Datatable({
       /* @__PURE__ */ jsxRuntime.jsxs(
         "tr",
         {
-          className: "twc-dt__row",
+          className: userRowClass ? `twc-dt__row ${userRowClass}` : "twc-dt__row",
           role: "row",
           "aria-rowindex": treeSeqByKey ? treeSeqByKey.get(k) + 2 : (paginated && !serverMode ? pageVal * sizeVal : 0) + ri + 2,
           "aria-selected": (checkboxSelection ? sel : rowActive) || void 0,
@@ -12894,14 +12919,20 @@ function Datatable({
             const isHidden = typeof a.hidden === "function" ? a.hidden(selKeys, selectedRows) : !!a.hidden;
             if (isHidden) return null;
             const isDisabled = typeof a.disabled === "function" ? a.disabled(selKeys, selectedRows) : !!a.disabled;
-            return /* @__PURE__ */ jsxRuntime.jsxs(
+            const reason = isDisabled && a.disabledReason != null ? typeof a.disabledReason === "function" ? a.disabledReason(selKeys, selectedRows) : a.disabledReason : null;
+            const soft = isDisabled && reason != null;
+            const btn = /* @__PURE__ */ jsxRuntime.jsxs(
               "button",
               {
                 type: "button",
                 className: "twc-dt__batch-btn",
                 "data-danger": a.danger || void 0,
-                disabled: isDisabled,
-                onClick: (e) => a.onClick?.(selKeys, selectedRows, clearSelection, { anchorEl: e.currentTarget }),
+                disabled: isDisabled && !soft,
+                "aria-disabled": soft || void 0,
+                onClick: (e) => {
+                  if (isDisabled) return;
+                  a.onClick?.(selKeys, selectedRows, clearSelection, { anchorEl: e.currentTarget });
+                },
                 children: [
                   a.icon,
                   a.label
@@ -12909,6 +12940,7 @@ function Datatable({
               },
               i
             );
+            return reason != null ? /* @__PURE__ */ jsxRuntime.jsx(Tooltip, { label: reason, placement: "top", children: btn }, i) : btn;
           })
         ] })
       ] }) : null,
@@ -14339,6 +14371,42 @@ var CARDGRID_CSS = `
 .twc-cardgrid__footer { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: var(--space-2); }
 .twc-cardgrid__count { font-size: var(--text-sm); color: var(--color-text-muted); }
 .twc-cardgrid__perpage { display: inline-flex; align-items: center; gap: var(--space-2); font-size: var(--text-sm); color: var(--color-text-muted); }
+
+/* #478: selection. The card's selected state is a RING, not a background tint: a card is usually a
+   full-bleed thumbnail, so a tint is invisible behind the image. The ring is drawn with box-shadow on
+   a wrapper so it never participates in layout (no reflow when a card becomes selected) and it reads
+   in both themes, --color-primary clearing 3:1 against both surfaces as a non-text indicator. */
+.twc-cardgrid__item { position: relative; border-radius: var(--radius-lg); transition: box-shadow var(--duration-fast) var(--ease-standard); }
+.twc-cardgrid__item[data-selected="true"] { box-shadow: 0 0 0 var(--border-medium) var(--color-primary); }
+/* The overlay is the GRID's checkbox, not the card's: renderCard owns the whole body, so a
+   consumer-rendered checkbox would compete with the card's own click target and have to be positioned
+   against a thumbnail whose size only the consumer knows. Placement is configurable, and a consumer who
+   wants it inline instead uses the third renderCard argument and sets selectionPlacement="none". */
+.twc-cardgrid__pick { position: absolute; z-index: 2; display: inline-flex; padding: var(--space-1);
+  background: color-mix(in srgb, var(--color-surface) 82%, transparent); border-radius: var(--radius-md);
+  backdrop-filter: blur(4px); }
+.twc-cardgrid__item[data-place="top-start"] .twc-cardgrid__pick { top: var(--space-2); inset-inline-start: var(--space-2); }
+.twc-cardgrid__item[data-place="top-end"] .twc-cardgrid__pick { top: var(--space-2); inset-inline-end: var(--space-2); }
+.twc-cardgrid__item[data-place="bottom-start"] .twc-cardgrid__pick { bottom: var(--space-2); inset-inline-start: var(--space-2); }
+.twc-cardgrid__item[data-place="bottom-end"] .twc-cardgrid__pick { bottom: var(--space-2); inset-inline-end: var(--space-2); }
+.twc-cardgrid__batch { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-2);
+  padding: var(--space-2) var(--space-3); border: var(--border-thin) solid var(--color-primary-border);
+  background: var(--color-primary-subtle); border-radius: var(--radius-md); }
+.twc-cardgrid__batch-count { font-size: var(--text-sm); font-weight: var(--font-semibold); color: var(--color-primary-subtle-fg); }
+.twc-cardgrid__batch-actions { display: inline-flex; flex-wrap: wrap; align-items: center; gap: var(--space-2); margin-inline-start: auto; }
+.twc-cardgrid__batch-btn { display: inline-flex; align-items: center; gap: var(--space-2); height: var(--control-h-sm);
+  padding-inline: var(--space-3); border: var(--border-thin) solid var(--color-border); background: var(--color-surface);
+  color: var(--color-text); font-family: inherit; font-size: var(--text-xs); font-weight: var(--font-semibold);
+  border-radius: var(--radius-md); cursor: pointer; }
+.twc-cardgrid__batch-btn:hover:not(:disabled):not([aria-disabled="true"]) { border-color: var(--color-primary-subtle-fg); color: var(--color-primary-subtle-fg); }
+.twc-cardgrid__batch-btn:disabled, .twc-cardgrid__batch-btn[aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; }
+.twc-cardgrid__batch-btn[data-danger="true"] { color: var(--color-danger-subtle-fg); }
+.twc-cardgrid__batch-btn svg { width: 15px; height: 15px; }
+.twc-cardgrid__batch-x { display: inline-grid; place-items: center; width: 26px; height: 26px; flex: none;
+  border: none; background: transparent; color: var(--color-primary-subtle-fg); cursor: pointer; border-radius: var(--radius-sm); }
+.twc-cardgrid__batch-x:hover { background: color-mix(in srgb, var(--color-primary) 14%, transparent); }
+.twc-cardgrid__batch-x svg { width: 15px; height: 15px; }
+.twc-cardgrid__selall { display: inline-flex; align-items: center; gap: var(--space-2); font-size: var(--text-sm); color: var(--color-text-muted); }
 `;
 function CardGrid({
   rows = [],
@@ -14375,6 +14443,16 @@ function CardGrid({
   sortMinWidth,
   // slots / states
   toolbar,
+  // #478: selection + batch actions, deliberately the SAME vocabulary as Datatable rather than a new
+  // one - a card grid is the surface where "pick several of these and do one thing to them" is close to
+  // the whole point, and it was the only Datatable affordance CardGrid lacked.
+  checkboxSelection = false,
+  batchActions = [],
+  onRowSelectionChange,
+  selectionPlacement = "top-start",
+  selectionLabel,
+  showSelectAll = true,
+  retainSelectedRows = false,
   emptyState = "No results.",
   label,
   id,
@@ -14451,6 +14529,62 @@ function CardGrid({
     return () => clearTimeout(t);
   }, [serverMode, queryKey]);
   const keyOf = typeof rowKey === "function" ? rowKey : (r2) => r2 && r2[rowKey];
+  const [selected, setSelected] = React54__namespace.default.useState(() => /* @__PURE__ */ new Set());
+  const retainCap = retainSelectedRows === true ? 1e3 : retainSelectedRows || 0;
+  const retainedRef = React54__namespace.default.useRef(/* @__PURE__ */ new Map());
+  const selKeys = React54__namespace.default.useMemo(() => [...selected], [selected]);
+  const selectedRows = React54__namespace.default.useMemo(() => {
+    const onPage = new Map(pageRows.map((r2, i) => [keyOf(r2, i), r2]));
+    return selKeys.map((k) => onPage.get(k) ?? retainedRef.current.get(k)).filter((r2) => r2 !== void 0);
+  }, [selKeys, pageRows]);
+  const clearSelection = React54__namespace.default.useCallback(() => {
+    retainedRef.current.clear();
+    setSelected(/* @__PURE__ */ new Set());
+  }, []);
+  const toggleKey = React54__namespace.default.useCallback((key, row) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) {
+        next.delete(key);
+        retainedRef.current.delete(key);
+      } else {
+        next.add(key);
+        if (retainCap > 0 && row !== void 0 && retainedRef.current.size < retainCap) retainedRef.current.set(key, row);
+      }
+      return next;
+    });
+  }, [retainCap]);
+  const pageKeys = pageRows.map((r2, i) => keyOf(r2, i));
+  const pageSelectedCount = pageKeys.filter((k) => selected.has(k)).length;
+  const allPageSelected = pageKeys.length > 0 && pageSelectedCount === pageKeys.length;
+  const somePageSelected = pageSelectedCount > 0 && !allPageSelected;
+  const togglePage = () => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      pageRows.forEach((r2, i) => {
+        const k = keyOf(r2, i);
+        if (allPageSelected) {
+          next.delete(k);
+          retainedRef.current.delete(k);
+        } else {
+          next.add(k);
+          if (retainCap > 0 && retainedRef.current.size < retainCap) retainedRef.current.set(k, r2);
+        }
+      });
+      return next;
+    });
+  };
+  const onSelRef = React54__namespace.default.useRef(onRowSelectionChange);
+  onSelRef.current = onRowSelectionChange;
+  const prevSelSigRef = React54__namespace.default.useRef(null);
+  React54__namespace.default.useEffect(() => {
+    const cb = onSelRef.current;
+    if (!cb) return;
+    const sig = selKeys.join(",");
+    if (sig === prevSelSigRef.current) return;
+    prevSelSigRef.current = sig;
+    cb(selKeys, selectedRows);
+  }, [selKeys, selectedRows]);
   const from = total === 0 ? 0 : Math.min(shownPage * sizeVal + 1, total);
   const to = paginated ? Math.min((shownPage + 1) * sizeVal, total) : total;
   const rppOptions = Array.from(new Set([...pageSizeOptions || [], pageSize].filter((n) => n > 0))).sort((a, b) => a - b).map((n) => ({ value: String(n), label: String(n) }));
@@ -14503,6 +14637,64 @@ function CardGrid({
         )
       ] }) : null
     ] }) : null,
+    checkboxSelection && showSelectAll && pageRows.length > 0 && selected.size === 0 ? /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "twc-cardgrid__selall", children: [
+      /* @__PURE__ */ jsxRuntime.jsx(
+        Checkbox,
+        {
+          checked: allPageSelected,
+          indeterminate: somePageSelected,
+          onChange: togglePage,
+          "aria-label": "Select all on this page"
+        }
+      ),
+      "Select all on this page"
+    ] }) : null,
+    checkboxSelection && selected.size > 0 ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "twc-cardgrid__batch", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", className: "twc-cardgrid__batch-x", onClick: clearSelection, "aria-label": "Clear selection", children: /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.4", strokeLinecap: "round", strokeLinejoin: "round", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M18 6 6 18M6 6l12 12" }) }) }),
+      /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "twc-cardgrid__batch-count", children: [
+        selected.size,
+        " selected"
+      ] }),
+      showSelectAll && pageRows.length > 0 ? /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "twc-cardgrid__selall", children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          Checkbox,
+          {
+            checked: allPageSelected,
+            indeterminate: somePageSelected,
+            onChange: togglePage,
+            "aria-label": "Select all on this page"
+          }
+        ),
+        "This page"
+      ] }) : null,
+      /* @__PURE__ */ jsxRuntime.jsx("div", { className: "twc-cardgrid__batch-actions", children: batchActions.map((a, i) => {
+        const isHidden = typeof a.hidden === "function" ? a.hidden(selKeys, selectedRows) : !!a.hidden;
+        if (isHidden) return null;
+        const isDisabled = typeof a.disabled === "function" ? a.disabled(selKeys, selectedRows) : !!a.disabled;
+        const reason = isDisabled && a.disabledReason != null ? typeof a.disabledReason === "function" ? a.disabledReason(selKeys, selectedRows) : a.disabledReason : null;
+        const soft = isDisabled && reason != null;
+        const btn = /* @__PURE__ */ jsxRuntime.jsxs(
+          "button",
+          {
+            type: "button",
+            className: "twc-cardgrid__batch-btn",
+            "data-danger": a.danger || void 0,
+            disabled: isDisabled && !soft,
+            "aria-disabled": soft || void 0,
+            onClick: (e) => {
+              if (isDisabled) return;
+              a.onClick?.(selKeys, selectedRows, clearSelection, { anchorEl: e.currentTarget });
+            },
+            children: [
+              a.icon,
+              a.label
+            ]
+          },
+          i
+        );
+        return reason != null ? /* @__PURE__ */ jsxRuntime.jsx(Tooltip, { label: reason, placement: "top", children: btn }, i) : btn;
+      }) })
+    ] }) : null,
     /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "twc-cardgrid__body", "data-loading": loading || void 0, "aria-busy": loading || void 0, children: [
       loading ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "twc-cardgrid__overlay", children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "twc-cardgrid__spinner", role: "status", "aria-label": "Loading" }) }) : null,
       pageRows.length === 0 && !loading ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "twc-cardgrid__empty", children: emptyState }) : /* @__PURE__ */ jsxRuntime.jsx(
@@ -14514,7 +14706,31 @@ function CardGrid({
           gap,
           role: "list",
           "aria-labelledby": label ? `${fieldId}-label` : void 0,
-          children: pageRows.map((row, i) => /* @__PURE__ */ jsxRuntime.jsx("div", { role: "listitem", children: renderCard(row, i) }, keyOf(row, i) ?? i))
+          children: pageRows.map((row, i) => {
+            const k = keyOf(row, i);
+            const isSel = checkboxSelection && selected.has(k);
+            return /* @__PURE__ */ jsxRuntime.jsxs(
+              "div",
+              {
+                role: "listitem",
+                className: "twc-cardgrid__item",
+                "data-selected": isSel || void 0,
+                "data-place": checkboxSelection ? selectionPlacement : void 0,
+                children: [
+                  checkboxSelection && selectionPlacement !== "none" ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "twc-cardgrid__pick", children: /* @__PURE__ */ jsxRuntime.jsx(
+                    Checkbox,
+                    {
+                      checked: isSel,
+                      onChange: () => toggleKey(k, row),
+                      "aria-label": selectionLabel ? selectionLabel(row, i) : "Select item"
+                    }
+                  ) }) : null,
+                  renderCard(row, i, checkboxSelection ? { selected: isSel, toggle: () => toggleKey(k, row) } : void 0)
+                ]
+              },
+              k ?? i
+            );
+          })
         }
       )
     ] }),
@@ -19531,7 +19747,7 @@ function Tag({
     }, "aria-label": _removeLabel, type: "button", children: /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.4", strokeLinecap: "round", strokeLinejoin: "round", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M18 6 6 18M6 6l12 12" }) }) }) : null
   ] });
 }
-var useIso2 = typeof document !== "undefined" ? React54__namespace.default.useLayoutEffect : React54__namespace.default.useEffect;
+var useIso = typeof document !== "undefined" ? React54__namespace.default.useLayoutEffect : React54__namespace.default.useEffect;
 var TEXTAREA_CSS = `
 .twc-field { display: flex; flex-direction: column; gap: var(--space-1-5); font-family: var(--font-sans); }
 .twc-field__label { font-size: var(--text-sm); font-weight: var(--font-semibold); color: var(--color-text); display: flex; gap: 4px; align-items: center; }
@@ -19630,7 +19846,7 @@ var Textarea = React54__namespace.default.forwardRef(function Textarea2({
     el.style.height = `${next}px`;
     el.style.overflowY = el.scrollHeight + vBorder > maxH ? "auto" : "hidden";
   };
-  useIso2(() => {
+  useIso(() => {
     if (autosize && innerRef.current) resize();
   }, [autosize, rest.value, minRows, maxRows, rows]);
   const handleInput = (e) => {