@usableapp/cardds 0.7.22 → 0.7.23

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 > For: a project that consumes `@usableapp/cardds` and its AI — what changed between versions, written as before → after, so a screen can be brought up to date without reading the source. Newest first. A consumer never edits cardds; if something here leaves you without a way to do what you did before, report the gap.
 
+## 0.7.23 — 2026-09-29
+
+### Added
+- `IconBtnGroup` (Lh 2026-09-29): up to FOUR icon-only `IconBtn`s in ONE frame. They share its width, with a rule between them in the frame's colour. At home in a `CardFoot` (card or sheet), where it takes the row. More than 4 → a dev warning.
+  - Plain: commands, each on its own `onClick`. Pressing dims the button; it never shrinks.
+  - `select="one"`: one on at a time. `select="many"`: each on or off by itself. A pressed button STAYS filled (`aria-pressed`). Each child names itself with `value`. The group takes `value` + `onChange`, or `defaultValue`.
+  - Knobs: `--icon-btn-group-h` · `-border` · `-radius` · `-bg` · `-ink` · `-rule` · `-on-bg` · `-on-ink`. Gallery: `/IconBtnGroup`.
+
 ## 0.7.22 — 2026-09-29
 
 ### Changed

package/css/actions.css

@@ -93,6 +93,24 @@
 }
 .icon-btn--invert { background: var(--icon-btn-invert-bg, var(--accent)); color: var(--icon-btn-invert-ink, var(--on-accent)); border-color: transparent; }
 .icon-btn--sm { width: var(--icon-btn-sm-size, var(--tap-sm)); height: var(--icon-btn-sm-size, var(--tap-sm)); font-size: var(--fs-title); }
+/* ---- icon button group: up to four icon-only commands in ONE frame (Lh 2026-09-29) ----
+   <div class="icon-btn-group" role="group"><button class="icon-btn" aria-label="…">…</button>…</div>
+   One pill as tall as a button, the buttons share its width, a hairline between them; in a foot it takes the row. */
+.icon-btn-group {
+  display: flex; min-width: 0;
+  min-height: var(--icon-btn-group-h, var(--btn-h));
+  border: var(--border-w) solid var(--icon-btn-group-border, var(--outline));
+  border-radius: var(--icon-btn-group-radius, var(--r-chip));
+  background: var(--icon-btn-group-bg, var(--action-bg));
+  color: var(--icon-btn-group-ink, var(--action-ink));
+  overflow: clip;
+}
+.icon-btn-group > .icon-btn { flex: 1 1 0; min-width: 0; width: auto; height: auto; border: 0; border-radius: 0; background: transparent; color: inherit; box-shadow: none; }
+.icon-btn-group > .icon-btn + .icon-btn { border-inline-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
+.card__foot > .icon-btn-group { flex: 1 1 0; }
+.icon-btn-group > .icon-btn[aria-pressed="true"] { background: var(--icon-btn-group-on-bg, var(--accent)); color: var(--icon-btn-group-on-ink, var(--on-accent)); } /* `select`: a pressed button STAYS filled (Lh 2026-09-29) */
+.icon-btn-group > .icon-btn:active:not(:disabled) { scale: 1; opacity: var(--press-dim); } /* a part of one frame DIMS, it never shrinks inside it */
+
 /* fab: the square floating action, bottom-right of a stage or screen */
 .fab { width: var(--fab); height: var(--fab); border-radius: var(--r-card); position: absolute; right: var(--sp-4); bottom: calc(var(--sp-5) + var(--bar-h) + var(--sp-3) + var(--safe-bottom)); box-shadow: var(--shadow-float); z-index: var(--z-fab); }
 

package/dist/actions/IconBtnGroup.d.ts

@@ -0,0 +1,19 @@
+import { type ComponentProps } from 'react';
+type Picked = string | null | string[];
+export interface IconBtnGroupProps extends Omit<ComponentProps<'div'>, 'onChange' | 'defaultValue'> {
+    /** the group's accessible name (what these commands act on) */
+    label?: string;
+    /** buttons that STAY ON when pressed (Lh 2026-09-29): `one` — one on at a time, pressing another moves it (value: the on
+     *  button's `value`, or null) · `many` — each on or off by itself (value: the on ones' values). None = plain commands. */
+    select?: 'one' | 'many';
+    /** which are on — each child IconBtn names itself with its own `value` */
+    value?: Picked;
+    defaultValue?: Picked;
+    /** asks the app: `one` → the pressed value · `many` → the new list */
+    onChange?: (value: Picked) => void;
+}
+/** IconBtnGroup — a panel of up to FOUR icon-only buttons in ONE frame, sharing its width, a rule between them in the frame's
+ *  colour (Lh 2026-09-29). Each is an `IconBtn` (its `label` is its spoken name). Plain: each does its own thing on its onClick.
+ *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot. */
+export declare function IconBtnGroup({ label, select, value, defaultValue, onChange, className, children, ...rest }: IconBtnGroupProps): import("react").JSX.Element;
+export {};

package/dist/actions/IconBtnGroup.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement } from 'react';
+import { cx } from '../cx.js';
+import { useControlled, warnOnce } from '../state.js';
+/** IconBtnGroup — a panel of up to FOUR icon-only buttons in ONE frame, sharing its width, a rule between them in the frame's
+ *  colour (Lh 2026-09-29). Each is an `IconBtn` (its `label` is its spoken name). Plain: each does its own thing on its onClick.
+ *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot. */
+export function IconBtnGroup({ label, select, value, defaultValue, onChange, className, children, ...rest }) {
+    if (Children.count(children) > 4)
+        warnOnce('icon-btn-group', 'cardds IconBtnGroup: more than 4 buttons — keep 4, put the rest in a Menu behind one of them');
+    const [shown, request] = useControlled(value, defaultValue ?? (select === 'many' ? [] : null), onChange);
+    const on = (v) => (Array.isArray(shown) ? shown.includes(v) : shown === v);
+    const items = !select ? children : Children.map(children, (c) => {
+        if (!isValidElement(c))
+            return c;
+        const el = c;
+        const v = el.props.value;
+        if (v == null)
+            return c;
+        return cloneElement(el, {
+            'aria-pressed': on(v),
+            onClick: (e) => {
+                el.props.onClick?.(e);
+                if (select === 'one')
+                    request(v);
+                else {
+                    const list = Array.isArray(shown) ? shown : [];
+                    request(on(v) ? list.filter((x) => x !== v) : [...list, v]);
+                }
+            },
+        });
+    });
+    return _jsx("div", { role: "group", "aria-label": label, className: cx('icon-btn-group', className), ...rest, children: items });
+}

package/dist/cardds.css

@@ -2117,6 +2117,24 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 }
 .icon-btn--invert { background: var(--icon-btn-invert-bg, var(--accent)); color: var(--icon-btn-invert-ink, var(--on-accent)); border-color: transparent; }
 .icon-btn--sm { width: var(--icon-btn-sm-size, var(--tap-sm)); height: var(--icon-btn-sm-size, var(--tap-sm)); font-size: var(--fs-title); }
+/* ---- icon button group: up to four icon-only commands in ONE frame (Lh 2026-09-29) ----
+   <div class="icon-btn-group" role="group"><button class="icon-btn" aria-label="…">…</button>…</div>
+   One pill as tall as a button, the buttons share its width, a hairline between them; in a foot it takes the row. */
+.icon-btn-group {
+  display: flex; min-width: 0;
+  min-height: var(--icon-btn-group-h, var(--btn-h));
+  border: var(--border-w) solid var(--icon-btn-group-border, var(--outline));
+  border-radius: var(--icon-btn-group-radius, var(--r-chip));
+  background: var(--icon-btn-group-bg, var(--action-bg));
+  color: var(--icon-btn-group-ink, var(--action-ink));
+  overflow: clip;
+}
+.icon-btn-group > .icon-btn { flex: 1 1 0; min-width: 0; width: auto; height: auto; border: 0; border-radius: 0; background: transparent; color: inherit; box-shadow: none; }
+.icon-btn-group > .icon-btn + .icon-btn { border-inline-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
+.card__foot > .icon-btn-group { flex: 1 1 0; }
+.icon-btn-group > .icon-btn[aria-pressed="true"] { background: var(--icon-btn-group-on-bg, var(--accent)); color: var(--icon-btn-group-on-ink, var(--on-accent)); } /* `select`: a pressed button STAYS filled (Lh 2026-09-29) */
+.icon-btn-group > .icon-btn:active:not(:disabled) { scale: 1; opacity: var(--press-dim); } /* a part of one frame DIMS, it never shrinks inside it */
+
 /* fab: the square floating action, bottom-right of a stage or screen */
 .fab { width: var(--fab); height: var(--fab); border-radius: var(--r-card); position: absolute; right: var(--sp-4); bottom: calc(var(--sp-5) + var(--bar-h) + var(--sp-3) + var(--safe-bottom)); box-shadow: var(--shadow-float); z-index: var(--z-fab); }
 

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export * from './sheets/SheetSteps.js';
 export * from './sheets/Drawer.js';
 export * from './actions/Btn.js';
 export * from './actions/IconBtn.js';
+export * from './actions/IconBtnGroup.js';
 export * from './actions/Chip.js';
 export * from './actions/Dot.js';
 export * from './actions/Dropdown.js';

package/dist/index.js

@@ -37,6 +37,7 @@ export * from './sheets/SheetSteps.js';
 export * from './sheets/Drawer.js';
 export * from './actions/Btn.js';
 export * from './actions/IconBtn.js';
+export * from './actions/IconBtnGroup.js';
 export * from './actions/Chip.js';
 export * from './actions/Dot.js';
 export * from './actions/Dropdown.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.22",
+  "version": "0.7.23",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",