@usableapp/cardds 0.7.52 → 0.7.53

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 > 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

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/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

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

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/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.52",
+  "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.",