@usableapp/cardds 0.7.21 → 0.7.23

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 > 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
+- `StackSheet` (so `Home`): the open sheet's back button now stands at the head's far END, after the tabs, with a chevron pointing DOWN because the sheet folds down (Lh 2026-09-29). Before: at the start, chevron left. `backAt="start"` brings back the old place.
+- `StackBack end`: the same for a head written by hand (`.sheet-stack__back--end`). Without `end` nothing changes.
+
 ## 0.7.21 — 2026-09-29
 
 ### Fixed

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/css/stack.css

@@ -311,7 +311,13 @@
 /* ---- the back button, SMALL (Lh 2026-09-23: "give the sheet head more room" — and then "a glyph alone does not read as
    tappable"): a SMALL DISC — its ring kept, 32px instead of 44, the chevron in it at 20 — so the head gives it 32px + a gap
    (was 56px). Its tap target stays 44px: an invisible ::after around the disc. ---- */
-.sheet-stack--tap > .card.is-open > .card__head { padding-left: var(--stack-back-room, calc(var(--_back-size) + var(--sp-2))); }
+.sheet-stack--tap > .card.is-open > .card__head:has(> .sheet-stack__back:not(.sheet-stack__back--end)) { padding-left: var(--stack-back-room, calc(var(--_back-size) + var(--sp-2))); }
+/* AT THE END (Lh 2026-09-29, the home): after the tabs, chevron down — the open sheet folds down. The head's end gives it its room
+   while open; the last tab then sits on the inset (no reach into the padding) */
+.sheet-stack--tap .sheet-stack__back--end { left: auto; right: 0; }
+.sheet-stack--tap .card__head:has(> .sheet-stack__back--end) { transition: padding-right var(--motion-sheet) ease; }
+.sheet-stack--tap > .card.is-open > .card__head:has(> .sheet-stack__back--end) { padding-right: var(--stack-back-room, calc(var(--_back-size) + var(--sp-2))); }
+.sheet-stack--tap > .card.is-open > .card__head:has(> .sheet-stack__back--end) > .stack-sheet__tabs { margin-right: 0; }
 .sheet-stack--tap .sheet-stack__back > .icon { width: var(--stack-back-icon, calc(var(--tap-base) * 13 / 24)); height: var(--stack-back-icon, calc(var(--tap-base) * 13 / 24)); flex: none; } /* 26: the chevron fills the small disc (Lh 2026-09-23) */
 .sheet-stack--tap .sheet-stack__back::after { content: ""; position: absolute; inset: calc((var(--_back-size) - var(--tap-sm)) / 2); }
 

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

@@ -1268,7 +1268,13 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 /* ---- the back button, SMALL (Lh 2026-09-23: "give the sheet head more room" — and then "a glyph alone does not read as
    tappable"): a SMALL DISC — its ring kept, 32px instead of 44, the chevron in it at 20 — so the head gives it 32px + a gap
    (was 56px). Its tap target stays 44px: an invisible ::after around the disc. ---- */
-.sheet-stack--tap > .card.is-open > .card__head { padding-left: var(--stack-back-room, calc(var(--_back-size) + var(--sp-2))); }
+.sheet-stack--tap > .card.is-open > .card__head:has(> .sheet-stack__back:not(.sheet-stack__back--end)) { padding-left: var(--stack-back-room, calc(var(--_back-size) + var(--sp-2))); }
+/* AT THE END (Lh 2026-09-29, the home): after the tabs, chevron down — the open sheet folds down. The head's end gives it its room
+   while open; the last tab then sits on the inset (no reach into the padding) */
+.sheet-stack--tap .sheet-stack__back--end { left: auto; right: 0; }
+.sheet-stack--tap .card__head:has(> .sheet-stack__back--end) { transition: padding-right var(--motion-sheet) ease; }
+.sheet-stack--tap > .card.is-open > .card__head:has(> .sheet-stack__back--end) { padding-right: var(--stack-back-room, calc(var(--_back-size) + var(--sp-2))); }
+.sheet-stack--tap > .card.is-open > .card__head:has(> .sheet-stack__back--end) > .stack-sheet__tabs { margin-right: 0; }
 .sheet-stack--tap .sheet-stack__back > .icon { width: var(--stack-back-icon, calc(var(--tap-base) * 13 / 24)); height: var(--stack-back-icon, calc(var(--tap-base) * 13 / 24)); flex: none; } /* 26: the chevron fills the small disc (Lh 2026-09-23) */
 .sheet-stack--tap .sheet-stack__back::after { content: ""; position: absolute; inset: calc((var(--_back-size) - var(--tap-sm)) / 2); }
 
@@ -2111,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/dist/sheets/StackBack.d.ts

@@ -2,7 +2,10 @@ import type { ComponentProps } from 'react';
 export interface StackBackProps extends ComponentProps<'button'> {
     /** accessible name */
     label?: string;
+    /** at the head's END (after its tabs / icons), chevron DOWN — the open sheet folds down (Lh 2026-09-29, the home);
+     *  default: at its start, chevron left */
+    end?: boolean;
 }
 /** StackBack — the back button a tapped stack sheet reveals in its head; first child of that sheet's CardHead. Hidden until the sheet is open.
  * A SMALL disc (Lh 2026-09-23): 32px with a chevron — the head keeps its room for the title and the tabs; the 44px tap target stays. */
-export declare function StackBack({ label, className, ...rest }: StackBackProps): import("react").JSX.Element;
+export declare function StackBack({ label, end, className, ...rest }: StackBackProps): import("react").JSX.Element;

package/dist/sheets/StackBack.js

@@ -4,6 +4,6 @@ import { Icon } from '../type/Icon.js';
 import { IconBtn } from '../actions/IconBtn.js';
 /** StackBack — the back button a tapped stack sheet reveals in its head; first child of that sheet's CardHead. Hidden until the sheet is open.
  * A SMALL disc (Lh 2026-09-23): 32px with a chevron — the head keeps its room for the title and the tabs; the 44px tap target stays. */
-export function StackBack({ label = 'Back', className, ...rest }) {
-    return _jsx(IconBtn, { sm: true, label: label, className: cx('sheet-stack__back', className), ...rest, children: _jsx(Icon, { name: "chevron-left" }) });
+export function StackBack({ label = 'Back', end, className, ...rest }) {
+    return _jsx(IconBtn, { sm: true, label: label, className: cx('sheet-stack__back', end && 'sheet-stack__back--end', className), ...rest, children: _jsx(Icon, { name: end ? 'chevron-down' : 'chevron-left' }) });
 }

package/dist/sheets/StackSheet.d.ts

@@ -26,6 +26,8 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
     foot?: ReactNode;
     /** the back button's label (shown once the sheet is open) */
     backLabel?: string;
+    /** where the back button stands: `end` (default — after the tabs, chevron DOWN: the sheet folds down, Lh 2026-09-29) or `start` (before the title, chevron left) */
+    backAt?: 'start' | 'end';
 }
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·
@@ -33,4 +35,4 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
  * a count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
-export declare function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;
+export declare function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, backAt, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;

package/dist/sheets/StackSheet.js

@@ -17,7 +17,7 @@ import { Badge } from '../numbers/Badge.js';
  * a count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
-export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = 'Back', className, children, ...rest }) {
+export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = 'Back', backAt = 'end', className, children, ...rest }) {
     const [tab, pick] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id, onTabChange);
     // a title longer than its room does not wrap: it runs sideways, like a song title in a short slot — the room it overflows by
     // is measured here (the tabs may grow with the text size) and handed to the CSS as --_over
@@ -35,5 +35,5 @@ export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab,
         measure();
         return watchSize([h, run], measure);
     }, [title]);
-    return (_jsxs(Card, { tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [_jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: "stack-sheet__title", children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs(IconBtn, { sm: true, invert: t.id === tab, role: "tab", "aria-selected": t.id === tab, label: t.label, className: "stack-sheet__tab", onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
+    return (_jsxs(Card, { tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [backAt === 'start' && _jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: "stack-sheet__title", children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs(IconBtn, { sm: true, invert: t.id === tab, role: "tab", "aria-selected": t.id === tab, label: t.label, className: "stack-sheet__tab", onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon, backAt === 'end' && _jsx(StackBack, { end: true, label: backLabel })] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.21",
+  "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.",