@usableapp/cardds 0.7.51 → 0.7.53

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 > 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.53 — 2026-10-05
+
+### Fixed
+- **`SheetStack` / `Home`: the pull down that asks `onRefresh` works with a finger** (Lh 2026-10-05). In 0.7.51 it only worked with a mouse: on a phone the browser took the touch for its own scroll and the content only jerked. A pull down from the top of the open content now follows the finger and asks; any other move still scrolls. Nothing to change in a screen.
+
+### Added
+- **`SheetStack` and `Home` take `refreshing`** — the index of the sheet you are reloading, or `null`. Set it in `onRefresh`, clear it when your data is in: `onRefresh={(i) => { setRefreshing(i); load(i).finally(() => setRefreshing(null)); }}` with `refreshing={refreshing}`. While it is the open sheet, its grip dots (below) fade up and down, the card is `aria-busy`, and a pull there does not ask again. Without `refreshing` nothing shows that a reload is running. Reload the pulled sheet alone or everything — that is yours; the stack does not fetch.
+
+### Changed
+- **Every sheet of a tap stack wears a grip: four small grey dots at the middle of its top edge** (Lh 2026-10-05) — a sign that the card slides up and down. A mark, not a control; nothing is added to the markup. Every `SheetStack` (tap mode) and `Home` shows it after the update — nothing to change in a screen, and there is no knob for it yet: if your screen needs it tuned or off, report it.
+
+## 0.7.52 — 2026-10-05
+
+### Changed
+- **A `StackSheet` tab's disc shows only while its sheet is open** (Lh 2026-10-04). On the home, every peeked sheet's tabs are the icon alone — none is filled. The chosen tab fills as the sheet rises (the one that was pressed, or the page the sheet opens on) and the fill leaves as the sheet folds. Which page is current is unchanged; only the paint waits. Nothing to change in a screen.
+
 ## 0.7.51 — 2026-10-04
 
 ### Added

package/README.md

@@ -181,12 +181,14 @@ the card is the material, the sheet is what it is in the stack.
   A tap, or a pull up, opens any sheet over it. The open title or its back
   button, tapped or pulled down, drops it home. A pull down in the open
   content, already at the top, asks `onRefresh` — omit it and that pull only
-  scrolls. A tab in the head stays a click.
+  scrolls. A tab in the head stays a click. Every sheet wears a grip — four
+  small dots at the middle of its top edge, a mark that it slides, not a
+  control.
 - **Five sheets max.** Slots are declared per `:nth-child` in `stack.css`; a
   sixth would render at slot 0, on top of the first.
 - **Every head needs its own `.sheet-stack__back`** if the stack is `--tap`. It stays
   hidden until that sheet is open, then slides into a reserved header slot.
-- **No ids, no wiring.** `SheetStack` holds which sheet is open (`open` + `onOpenChange`, or `defaultOpen`). A pull down in the open content asks `onRefresh(index)`. The stack does not fetch.
+- **No ids, no wiring.** `SheetStack` holds which sheet is open (`open` + `onOpenChange`, or `defaultOpen`). A pull down in the open content asks `onRefresh(index)`. The stack does not fetch: the app reloads (that sheet alone, or more — its call) and says so with `refreshing` (that index, then `null` when the data is in) — the sheet's grip dots fade up and down meanwhile, and a pull there does not ask again.
 - **`.card-stack` is gone.** That was this component's first name and the wrong
   one — the members are sheets and the stack is the menu, not a list of cards.
   Never bring it back, not even as an alias.

package/css/finish.css

@@ -65,6 +65,11 @@
     0 1px 2px color-mix(in srgb, var(--_shade) 20%, transparent),
     0 0.5rem 1rem -0.25rem color-mix(in srgb, var(--accent) 45%, transparent);
 }
+/* a peeked stack tab is the icon alone: no sheen and no shadow until its sheet is open (the fill fades with the sheet) */
+[data-finish="lit"] .sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab {
+  background-image: none;
+  box-shadow: none;
+}
 [data-finish="lit"] :is(.btn:not(.btn--quiet), .icon-btn:not(.icon-btn-group > *, .stack-sheet__tab:not(.icon-btn--invert))):active:not(:disabled) {
   background-image: none;
   box-shadow: var(--finish-control-down);

package/css/stack.css

@@ -183,6 +183,29 @@
 }
 .sheet-stack > .card > .sheet__body.is-refreshing,
 .sheet-stack--tap > .card.is-open.is-refreshing:not(:has(> .sheet__body)) { transition: none; }
+/* the GRIP (Lh 2026-10-05): four small grey dots at the middle of every sheet's top edge — just enough of a sign that this card
+   slides up and down. A mark, not a control: nothing to press, nothing added to the sheet (the card's own background, in the
+   room above its head). While the app reloads the open sheet (.is-loading, from `refreshing`) the same four dots fade up and
+   down until it clears — nothing travels, nobody knows how long a reload takes. --_grip is their strength, private. */
+@property --_grip { syntax: "<number>"; inherits: false; initial-value: 0.35; }
+.sheet-stack--tap > .card {
+  --_grip-dot: var(--sp-1);
+  --_grip-step: calc(var(--sp-1) * 2.5);
+  --_grip-y: calc((var(--card-pad) - var(--_grip-dot)) / 2);
+  --_grip-ink: color-mix(in srgb, currentColor calc(var(--_grip) * 100%), transparent);
+  --_grip-img: radial-gradient(circle closest-side, var(--_grip-ink) 85%, transparent);
+  background-image: var(--_grip-img), var(--_grip-img), var(--_grip-img), var(--_grip-img);
+  background-repeat: no-repeat;
+  background-size: var(--_grip-dot) var(--_grip-dot);
+  background-position:
+    calc(50% - 1.5 * var(--_grip-step)) var(--_grip-y), calc(50% - 0.5 * var(--_grip-step)) var(--_grip-y),
+    calc(50% + 0.5 * var(--_grip-step)) var(--_grip-y), calc(50% + 1.5 * var(--_grip-step)) var(--_grip-y);
+}
+.sheet-stack--tap > .card.is-open.is-loading { animation: stack-grip-breath 0.8s ease-in-out infinite alternate; }
+@keyframes stack-grip-breath { from { --_grip: 0.2; } to { --_grip: 1; } }
+@media (prefers-reduced-motion: reduce) {
+  .sheet-stack--tap > .card.is-open.is-loading { animation: none; --_grip: 1; } /* no fade: the dots are simply full while it reloads */
+}
 /* the front sheet — the one open on arrival — never travels up (it is not
    tappable), so its resting offset would leave its last n steps below the
    screen forever, unreachable by any scroll (timebank home, 2026-09-13). It
@@ -285,7 +308,7 @@
 .sheet-stack > .card > .sheet__body { --_cover: 0rem; } /* nothing slid under here: the stack's sheet is always whole */
 
 /* ---- StackSheet's tabs (Lh 2026-09-23): the head's end is a row of small icon buttons, the sheet's pages — the chosen one
-   filled (.icon-btn--invert); a count is a small circle over the icon's top right corner ---- */
+   filled (.icon-btn--invert) only while the sheet is open; a count is a small circle over the icon's top right corner ---- */
 .stack-sheet__tabs { display: flex; gap: var(--stack-sheet-tabs-gap, var(--sp-2)); flex: none; } /* room between the tabs: with none, the chosen tab's disc touched its neighbour's (Lh 2026-09-24) */
 /* the head is ONE line, always (Lh 2026-09-24): the tabs keep their size, the TITLE gives — it never wraps, it runs sideways
    (StackSheet measures --_over, the width it overflows by, and sets .is-long), one way: it waits, runs to the end, waits, and starts again from the first letter — like a song title */
@@ -304,8 +327,19 @@
 @media (prefers-reduced-motion: reduce) {
   .stack-sheet__title.is-long .stack-sheet__run { animation: none; display: inline; } /* inline: an ellipsis cannot cut an inline-block */
   .stack-sheet__title.is-long { text-overflow: ellipsis; }
+  .stack-sheet__tab { transition: none; } /* the disc is simply there while open, and gone while closed */
+}
+.stack-sheet__tab {
+  position: relative;
+  /* the disc fades with the sheet: in as it rises, out as it folds, and across when another tab is pressed.
+     scale stays on the press (actions.css) so the give under a finger stays quick */
+  transition:
+    scale var(--motion-press) ease-out,
+    background-color var(--motion-sheet) ease,
+    color var(--motion-sheet) ease,
+    border-color var(--motion-sheet) ease,
+    box-shadow var(--motion-sheet) ease;
 }
-.stack-sheet__tab { position: relative; }
 .stack-sheet__tab > .stack-sheet__count { /* outranks .badge (numbers.css loads after this file) */
   position: absolute;
   top: calc(-1 * var(--stack-sheet-count-out, var(--sp-2))); /* how far it stands OUT of the tab's corner, up and to the right: at sp-1 it
@@ -323,6 +357,12 @@
 /* a tab not chosen is the icon alone — no ring, no ground (Lh 2026-09-23: "the circle around is not pretty"); the chosen one turns
    to the opposite colour (.icon-btn--invert). */
 .stack-sheet__tab:not(.icon-btn--invert) { border-color: transparent; background: transparent; box-shadow: none; color: inherit; } /* the sheet's own ink, on any paper */
+/* a CLOSED sheet shows no chosen disc either (Lh 2026-10-04): arriving on the home, every tab of every sheet is the icon
+   alone. The fill fades in with the rise — the tab that was pressed, or the one the sheet opens on — and fades out as the
+   sheet folds. The class stays (which page it is); only the paint waits for .is-open. */
+.sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab.icon-btn--invert {
+  border-color: transparent; background-color: transparent; box-shadow: none; color: inherit;
+}
 /* the last tab's ICON lines up with the inset, not its button's edge: an unchosen tab shows the glyph only, so the button's own
    margin around it reaches into the card's padding — and an open head (back · title · three tabs) keeps one line (Lh 2026-09-23) */
 .card__head > .stack-sheet__tabs { margin-right: calc(-1 * var(--sp-2)); }

package/dist/cardds.css

@@ -1184,6 +1184,29 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 }
 .sheet-stack > .card > .sheet__body.is-refreshing,
 .sheet-stack--tap > .card.is-open.is-refreshing:not(:has(> .sheet__body)) { transition: none; }
+/* the GRIP (Lh 2026-10-05): four small grey dots at the middle of every sheet's top edge — just enough of a sign that this card
+   slides up and down. A mark, not a control: nothing to press, nothing added to the sheet (the card's own background, in the
+   room above its head). While the app reloads the open sheet (.is-loading, from `refreshing`) the same four dots fade up and
+   down until it clears — nothing travels, nobody knows how long a reload takes. --_grip is their strength, private. */
+@property --_grip { syntax: "<number>"; inherits: false; initial-value: 0.35; }
+.sheet-stack--tap > .card {
+  --_grip-dot: var(--sp-1);
+  --_grip-step: calc(var(--sp-1) * 2.5);
+  --_grip-y: calc((var(--card-pad) - var(--_grip-dot)) / 2);
+  --_grip-ink: color-mix(in srgb, currentColor calc(var(--_grip) * 100%), transparent);
+  --_grip-img: radial-gradient(circle closest-side, var(--_grip-ink) 85%, transparent);
+  background-image: var(--_grip-img), var(--_grip-img), var(--_grip-img), var(--_grip-img);
+  background-repeat: no-repeat;
+  background-size: var(--_grip-dot) var(--_grip-dot);
+  background-position:
+    calc(50% - 1.5 * var(--_grip-step)) var(--_grip-y), calc(50% - 0.5 * var(--_grip-step)) var(--_grip-y),
+    calc(50% + 0.5 * var(--_grip-step)) var(--_grip-y), calc(50% + 1.5 * var(--_grip-step)) var(--_grip-y);
+}
+.sheet-stack--tap > .card.is-open.is-loading { animation: stack-grip-breath 0.8s ease-in-out infinite alternate; }
+@keyframes stack-grip-breath { from { --_grip: 0.2; } to { --_grip: 1; } }
+@media (prefers-reduced-motion: reduce) {
+  .sheet-stack--tap > .card.is-open.is-loading { animation: none; --_grip: 1; } /* no fade: the dots are simply full while it reloads */
+}
 /* the front sheet — the one open on arrival — never travels up (it is not
    tappable), so its resting offset would leave its last n steps below the
    screen forever, unreachable by any scroll (timebank home, 2026-09-13). It
@@ -1286,7 +1309,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .sheet-stack > .card > .sheet__body { --_cover: 0rem; } /* nothing slid under here: the stack's sheet is always whole */
 
 /* ---- StackSheet's tabs (Lh 2026-09-23): the head's end is a row of small icon buttons, the sheet's pages — the chosen one
-   filled (.icon-btn--invert); a count is a small circle over the icon's top right corner ---- */
+   filled (.icon-btn--invert) only while the sheet is open; a count is a small circle over the icon's top right corner ---- */
 .stack-sheet__tabs { display: flex; gap: var(--stack-sheet-tabs-gap, var(--sp-2)); flex: none; } /* room between the tabs: with none, the chosen tab's disc touched its neighbour's (Lh 2026-09-24) */
 /* the head is ONE line, always (Lh 2026-09-24): the tabs keep their size, the TITLE gives — it never wraps, it runs sideways
    (StackSheet measures --_over, the width it overflows by, and sets .is-long), one way: it waits, runs to the end, waits, and starts again from the first letter — like a song title */
@@ -1305,8 +1328,19 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 @media (prefers-reduced-motion: reduce) {
   .stack-sheet__title.is-long .stack-sheet__run { animation: none; display: inline; } /* inline: an ellipsis cannot cut an inline-block */
   .stack-sheet__title.is-long { text-overflow: ellipsis; }
+  .stack-sheet__tab { transition: none; } /* the disc is simply there while open, and gone while closed */
+}
+.stack-sheet__tab {
+  position: relative;
+  /* the disc fades with the sheet: in as it rises, out as it folds, and across when another tab is pressed.
+     scale stays on the press (actions.css) so the give under a finger stays quick */
+  transition:
+    scale var(--motion-press) ease-out,
+    background-color var(--motion-sheet) ease,
+    color var(--motion-sheet) ease,
+    border-color var(--motion-sheet) ease,
+    box-shadow var(--motion-sheet) ease;
 }
-.stack-sheet__tab { position: relative; }
 .stack-sheet__tab > .stack-sheet__count { /* outranks .badge (numbers.css loads after this file) */
   position: absolute;
   top: calc(-1 * var(--stack-sheet-count-out, var(--sp-2))); /* how far it stands OUT of the tab's corner, up and to the right: at sp-1 it
@@ -1324,6 +1358,12 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 /* a tab not chosen is the icon alone — no ring, no ground (Lh 2026-09-23: "the circle around is not pretty"); the chosen one turns
    to the opposite colour (.icon-btn--invert). */
 .stack-sheet__tab:not(.icon-btn--invert) { border-color: transparent; background: transparent; box-shadow: none; color: inherit; } /* the sheet's own ink, on any paper */
+/* a CLOSED sheet shows no chosen disc either (Lh 2026-10-04): arriving on the home, every tab of every sheet is the icon
+   alone. The fill fades in with the rise — the tab that was pressed, or the one the sheet opens on — and fades out as the
+   sheet folds. The class stays (which page it is); only the paint waits for .is-open. */
+.sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab.icon-btn--invert {
+  border-color: transparent; background-color: transparent; box-shadow: none; color: inherit;
+}
 /* the last tab's ICON lines up with the inset, not its button's edge: an unchosen tab shows the glyph only, so the button's own
    margin around it reaches into the card's padding — and an open head (back · title · three tabs) keeps one line (Lh 2026-09-23) */
 .card__head > .stack-sheet__tabs { margin-right: calc(-1 * var(--sp-2)); }
@@ -4136,6 +4176,11 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
     0 1px 2px color-mix(in srgb, var(--_shade) 20%, transparent),
     0 0.5rem 1rem -0.25rem color-mix(in srgb, var(--accent) 45%, transparent);
 }
+/* a peeked stack tab is the icon alone: no sheen and no shadow until its sheet is open (the fill fades with the sheet) */
+[data-finish="lit"] .sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab {
+  background-image: none;
+  box-shadow: none;
+}
 [data-finish="lit"] :is(.btn:not(.btn--quiet), .icon-btn:not(.icon-btn-group > *, .stack-sheet__tab:not(.icon-btn--invert))):active:not(:disabled) {
   background-image: none;
   box-shadow: var(--finish-control-down);

package/dist/sheets/SheetStack.d.ts

@@ -11,6 +11,8 @@ export interface SheetStackProps extends ComponentProps<'div'> {
     onOpenChange?: (open: number | null) => void;
     /** the open sheet's scroller was already at the top and the finger pulled down past the commit. The stack asks with that index. It does not fetch. Omit it and a pull in the body only scrolls */
     onRefresh?: (index: number) => void;
+    /** the sheet the app is reloading (its index), or `null`: while it is the open one its four grip dots fade up and down, at rest again when the app clears it, and a pull there does not ask again. The app sets it in `onRefresh` and clears it when its data is in */
+    refreshing?: number | null;
     /** wider peeks so more of each title shows (display stacks) */
     fanned?: boolean;
     /** nothing open on arrival (tap mode): every sheet, the front one too, peeks at the stack's bottom; the room above is the base's (`base`). A tap opens any sheet over it */
@@ -30,7 +32,7 @@ export interface SheetStackProps extends ComponentProps<'div'> {
  * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
  * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, or a pull up on
  * that head (the title, the back button, or the head itself — not a tab), opens it. The open sheet's StackBack or its title, tapped or pulled
- * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold; `refreshing` fades that sheet's four grip dots up and down while the app reloads. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
  * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }: SheetStackProps): import("react").JSX.Element;
+export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, refreshing, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }: SheetStackProps): import("react").JSX.Element;

package/dist/sheets/SheetStack.js

@@ -44,10 +44,10 @@ const pullsHead = (target, head) => {
  * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
  * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, or a pull up on
  * that head (the title, the back button, or the head itself — not a tab), opens it. The open sheet's StackBack or its title, tapped or pulled
- * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold; `refreshing` fades that sheet's four grip dots up and down while the app reloads. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
  * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }) {
+export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, refreshing = null, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }) {
     const [current, request] = useControlled(open, defaultOpen, onOpenChange);
     const ref = useRef(null);
     const was = useRef(null);
@@ -56,6 +56,7 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
     const bodyPull = useRef(null);
     const swallow = useRef(false);
     const refreshRef = useLatest(onRefresh);
+    const loadingRef = useLatest(refreshing);
     /* paint the state onto the sheets — after every render, so a re-rendered Card never loses its place */
     useLayoutEffect(() => {
         const stack = ref.current;
@@ -74,6 +75,14 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
             if (title)
                 title.tabIndex = current == null || i === current ? 0 : -1;
         });
+        sheets.forEach((c, i) => {
+            const loading = refreshing === i && current === i;
+            c.classList.toggle('is-loading', loading);
+            if (loading)
+                c.setAttribute('aria-busy', 'true');
+            else
+                c.removeAttribute('aria-busy');
+        });
         const prev = was.current;
         was.current = current;
         if (current != null) {
@@ -194,7 +203,7 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
             listen(onMove, onUp, onCancel);
         };
         const onBodyDown = (e) => {
-            if (!primary(e) || headPull.current || bodyPull.current || !refreshRef.current)
+            if (!primary(e) || headPull.current || bodyPull.current || !refreshRef.current || loadingRef.current === index)
                 return;
             if (scroller.scrollTop > 0)
                 return;
@@ -262,9 +271,32 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
             };
             listen(onMove, onUp, onCancel);
         };
+        /* a FINGER: the browser takes a touch for its own scroll at the first move and cancels the pointer — unless that first move is
+           refused. So the first move decides, once: down and at the top = the pull's (refused, no scroll); anything else = the scroll's */
+        let touch = null;
+        const onTouchStart = (e) => {
+            const t = e.touches[0];
+            const inHead = e.target instanceof Element && !!e.target.closest('.card__head');
+            touch = e.touches.length === 1 && t && refreshRef.current && loadingRef.current !== index && scroller.scrollTop <= 0 && !inHead ? { x: t.clientX, y: t.clientY, ours: null } : null;
+        };
+        const onTouchMove = (e) => {
+            const t = e.touches[0];
+            if (!touch || !t)
+                return;
+            const dx = t.clientX - touch.x;
+            const dy = t.clientY - touch.y;
+            if (touch.ours == null)
+                touch.ours = dy > 0 && dy >= Math.abs(dx) && scroller.scrollTop <= 0;
+            if (touch.ours && e.cancelable)
+                e.preventDefault();
+        };
         head?.addEventListener('pointerdown', onHeadDown);
         scroller.addEventListener('pointerdown', onBodyDown);
+        scroller.addEventListener('touchstart', onTouchStart, { passive: true });
+        scroller.addEventListener('touchmove', onTouchMove, { passive: false });
         return () => {
+            scroller.removeEventListener('touchstart', onTouchStart);
+            scroller.removeEventListener('touchmove', onTouchMove);
             stopDoc();
             const held = headPull.current;
             headPull.current = null;

package/dist/sheets/StackSheet.d.ts

@@ -32,8 +32,9 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
 }
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·
- * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons, the chosen one filled;
- * 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
+ * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons. The chosen one is filled
+ * only while this sheet is open — a closed home shows every icon plain; the disc fades in with the rise and out with the fold.
+ * 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, backAt, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;

package/dist/sheets/StackSheet.js

@@ -14,8 +14,9 @@ import { Badge } from '../numbers/Badge.js';
 import { word } from '../words.js';
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·
- * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons, the chosen one filled;
- * 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
+ * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons. The chosen one is filled
+ * only while this sheet is open — a closed home shows every icon plain; the disc fades in with the rise and out with the fold.
+ * 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 = word('back'), backAt = 'none', className, children, ...rest }) {

package/dist/templates/Home.d.ts

@@ -31,6 +31,8 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
     onOpenChange?: (open: number | null) => void;
     /** the open sheet's scroller was already at the top and the finger pulled down past the commit. The stack asks with that index. It does not fetch. Omit it and a pull in the body only scrolls */
     onRefresh?: (index: number) => void;
+    /** the sheet the app is reloading (its index), or `null` — as `SheetStack refreshing` */
+    refreshing?: number | null;
     /** CONTENT above the sheet heads — one `Page`: a welcome, the news, a picture. It reads
      *  from the top; a sheet coming up covers it */
     base?: ReactNode;
@@ -50,4 +52,4 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
  * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
-export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, onRefresh, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;
+export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, onRefresh, refreshing, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;

package/dist/templates/Home.js

@@ -15,7 +15,7 @@ const LEAVE = 800; // ms: a closing sheet keeps its body until it has slid home
  * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
-export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, onRefresh, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
+export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, onRefresh, refreshing, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
     const [open, change] = useControlled(openProp, defaultOpen, onOpenChange);
     const [leaving, setLeaving] = useState(null);
     const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
@@ -35,5 +35,5 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
     }, [leaving]);
     const [tabs, setTabs] = useState(() => Object.fromEntries(sheets.map((x, i) => [i, x.defaultTab ?? x.tabs?.[0]?.id])));
     const shows = (i) => i === open || i === leaving || (keep && seen.has(i));
-    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: open, onOpenChange: change, onRefresh: onRefresh, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, backAt: backAt, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
+    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: open, onOpenChange: change, onRefresh: onRefresh, refreshing: refreshing, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, backAt: backAt, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
 }

package/package.json

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