@usableapp/cardds 0.7.58 → 0.7.59

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.59 — 2026-10-06
+
+### Fixed
+- **`SheetStack` / `Home`: a tap right after a fold opens the head you aimed at** (Lh 2026-10-06, reported by timebank). For about half a second after a sheet folded, the pile was still coming back: a tap where another head rests reopened the sheet that had just folded, did nothing, or opened a third sheet. While the pile comes back, a tap is now answered by where each head RESTS — the head that will stand under the finger opens. Nothing to change in a screen. A test that waited for `is-before` / `is-after` to leave before tapping still passes; it no longer has to wait. Still as before: a tap on a tab's place during that moment opens the sheet on its current tab, not that tab.
+
+### Added
+- **`SheetStack` and `Home` take `mark`** — the grip at the middle of every sheet's top edge: `dots` (default, the four dots) or `line` (one line, the single `Sheet`'s, at the same place — the title does not move). While a sheet is `refreshing`, the line changes colour the same way the dots do. One mark for the whole stack: `<Home mark="line" …>`. Omit it and nothing changes.
+
 ## 0.7.58 — 2026-10-06
 
 ### Changed

package/README.md

@@ -183,7 +183,11 @@ the card is the material, the sheet is what it is in the stack.
   content, already at the top, asks `onRefresh` — omit it and that pull only
   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.
+  control. `mark="line"` on the `SheetStack` (or `Home`) draws one line
+  there instead, as a single `Sheet`'s; while a sheet is `refreshing`, either
+  mark changes colour the same way. Right after a fold, while the
+  pile is still coming back, a tap is answered by where each head RESTS: the
+  head that will stand under the finger opens, whatever is passing there.
 - **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

package/css/stack.css

@@ -210,6 +210,18 @@
   animation: stack-grip-dissolve 0.4s ease-in-out infinite alternate;
 }
 @keyframes stack-grip-dissolve { from { --_grip: 0; } to { --_grip: 1; } }
+/* the grip as ONE LINE (`mark="line"`, Lh 2026-10-06): the single Sheet's line, at the same place and the same length. It reads the
+   same --_grip-ink, so while its sheet reloads it changes colour exactly as the dots do. A bar and two round ends; the resting
+   ink is mixed into the card's own colour (opaque), so the ends do not show darker where they lie on the bar. */
+.stack-card--line {
+  --_grip-w: calc(var(--sp-base) * 18);
+  --_grip-ink: color-mix(in srgb, currentColor 30%, var(--card-bg));
+  --_grip-bar: linear-gradient(var(--_grip-ink), var(--_grip-ink));
+  --_grip-end: calc((var(--_grip-w) - var(--_grip-dot)) / 2);
+  background-image: var(--_grip-img), var(--_grip-bar), var(--_grip-img);
+  background-size: var(--_grip-dot) var(--_grip-dot), calc(var(--_grip-w) - var(--_grip-dot)) var(--_grip-dot), var(--_grip-dot) var(--_grip-dot);
+  background-position: calc(50% - var(--_grip-end)) var(--_grip-y), 50% var(--_grip-y), calc(50% + var(--_grip-end)) var(--_grip-y);
+}
 @media (prefers-reduced-motion: reduce) {
   .stack-card.is-open.is-loading { animation: none; --_grip-ink: currentColor; }
 }

package/dist/cardds.css

@@ -1211,6 +1211,18 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   animation: stack-grip-dissolve 0.4s ease-in-out infinite alternate;
 }
 @keyframes stack-grip-dissolve { from { --_grip: 0; } to { --_grip: 1; } }
+/* the grip as ONE LINE (`mark="line"`, Lh 2026-10-06): the single Sheet's line, at the same place and the same length. It reads the
+   same --_grip-ink, so while its sheet reloads it changes colour exactly as the dots do. A bar and two round ends; the resting
+   ink is mixed into the card's own colour (opaque), so the ends do not show darker where they lie on the bar. */
+.stack-card--line {
+  --_grip-w: calc(var(--sp-base) * 18);
+  --_grip-ink: color-mix(in srgb, currentColor 30%, var(--card-bg));
+  --_grip-bar: linear-gradient(var(--_grip-ink), var(--_grip-ink));
+  --_grip-end: calc((var(--_grip-w) - var(--_grip-dot)) / 2);
+  background-image: var(--_grip-img), var(--_grip-bar), var(--_grip-img);
+  background-size: var(--_grip-dot) var(--_grip-dot), calc(var(--_grip-w) - var(--_grip-dot)) var(--_grip-dot), var(--_grip-dot) var(--_grip-dot);
+  background-position: calc(50% - var(--_grip-end)) var(--_grip-y), 50% var(--_grip-y), calc(50% + var(--_grip-end)) var(--_grip-y);
+}
 @media (prefers-reduced-motion: reduce) {
   .stack-card.is-open.is-loading { animation: none; --_grip-ink: currentColor; }
 }

package/dist/sheets/SheetStack.d.ts

@@ -13,6 +13,8 @@ export interface SheetStackProps extends ComponentProps<'div'> {
     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;
+    /** the grip every sheet wears at the middle of its top edge: `dots` (default, four small dots) or `line` (one line, as a `Sheet`'s). Either one changes colour the same way while its sheet is `refreshing` */
+    mark?: 'dots' | 'line';
     /** 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 */
@@ -34,4 +36,4 @@ export interface SheetStackProps extends ComponentProps<'div'> {
  * the place classes, the grip, the pull. The stack only says which index. Sheets are rigid — the open 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); never a size.
  */
-export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, refreshing, fanned, closed, base, className, children, ...rest }: SheetStackProps): import("react").JSX.Element;
+export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, refreshing, mark, fanned, closed, base, className, children, onClickCapture, onPointerDownCapture, ref: passed, ...rest }: SheetStackProps): import("react").JSX.Element;

package/dist/sheets/SheetStack.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, cloneElement, isValidElement, useEffect, useRef, useState } from 'react';
+import { Children, cloneElement, isValidElement, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { useControlled, warnOnce } from '../state.js';
 import { cx } from '../cx.js';
 import { Card } from '../cards/Card.js';
@@ -7,6 +7,24 @@ import { StackSheet } from './StackSheet.js';
 const PHASE = 380; // ms before the before-pack un-tucks on close, so the after-pack is clear first
 const UNTUCK = 700; // the stagger stays for the return: the delay is read when is-before leaves, and a later render must not take it away mid-move
 const SHEET = new Set([Card, StackSheet]);
+const cardsIn = (stack) => [...stack.children]
+    .filter((c) => !c.classList.contains('sheet-stack__base'))
+    .map((c) => (c.classList.contains('card') ? c : c.querySelector(':scope > .card')))
+    .filter((c) => c instanceof HTMLElement);
+function measureRests(stack) {
+    const box = stack.getBoundingClientRect();
+    const cards = cardsIn(stack);
+    const tops = cards.map((c) => c.getBoundingClientRect().top - box.top);
+    return {
+        height: box.height,
+        strips: cards.map((c, i) => {
+            const head = c.querySelector(':scope > .card__head')?.getBoundingClientRect();
+            const own = head ? head.bottom - box.top + (head.top - box.top - tops[i]) : tops[i];
+            return { top: tops[i], end: i < cards.length - 1 ? tops[i + 1] : own };
+        }),
+    };
+}
+const SLOP = 8; // px a pointer may travel and still be a tap
 /* one wrapper around a sheet is fine (a host's own box). The props land on the Card or StackSheet inside it, so the card renders them. */
 function stamp(child, place) {
     if (SHEET.has(child.type))
@@ -37,7 +55,7 @@ function stamp(child, place) {
  * the place classes, the grip, the pull. The stack only says which index. Sheets are rigid — the open 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); never a size.
  */
-export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, refreshing = null, fanned, closed, base, className, children, ...rest }) {
+export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, refreshing = null, mark = 'dots', fanned, closed, base, className, children, onClickCapture, onPointerDownCapture, ref: passed, ...rest }) {
     const [current, request] = useControlled(open, defaultOpen, onOpenChange);
     const prev = useRef(current);
     const [closingFrom, setClosingFrom] = useState(null);
@@ -73,6 +91,51 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         }, Math.max(0, held.until - performance.now()));
         return () => clearTimeout(t);
     });
+    /* a tap while the pile comes back from a fold (Lh 2026-10-06). The sheets are not where they rest yet — the folded one is passing,
+       the tucked ones stand a step low — so what is under the finger is not what the eye aimed at. The tap is answered by the RESTING
+       place: the head that will stand there opens. The places are measured while the pile is still. */
+    const ref = useRef(null);
+    const setRef = (node) => {
+        ref.current = node;
+        if (typeof passed === 'function')
+            passed(node);
+        else if (passed)
+            passed.current = node;
+    };
+    const rests = useRef(null);
+    const down = useRef(null);
+    const settling = mode === 'tap' && current == null && (closingFrom != null || back.current != null);
+    const still = mode === 'tap' && current == null && !settling;
+    useLayoutEffect(() => {
+        if (still && ref.current)
+            rests.current = measureRests(ref.current);
+    });
+    const pointerDownCapture = (e) => {
+        onPointerDownCapture?.(e);
+        down.current = { x: e.clientX, y: e.clientY };
+    };
+    const clickCapture = (e) => {
+        onClickCapture?.(e);
+        const stack = ref.current;
+        const at = rests.current;
+        const from = down.current;
+        if (!settling || !stack || !at || e.detail === 0)
+            return; // detail 0: the keyboard's click has no place
+        if (from && Math.hypot(e.clientX - from.x, e.clientY - from.y) > SLOP)
+            return; // a pull that sprang back, not a tap
+        const box = stack.getBoundingClientRect();
+        if (Math.abs(box.height - at.height) > 1)
+            return; // the stack changed size since it was still: the places are stale
+        const y = e.clientY - box.top;
+        const i = at.strips.findIndex((s) => y >= s.top && y < s.end);
+        if (i < 0)
+            return;
+        const cards = cardsIn(stack);
+        if (cards[i]?.contains(e.target) && !cards[i].classList.contains('is-before'))
+            return; // already home: its own tap, a tab's too
+        e.stopPropagation();
+        request(i);
+    };
     const closing = current == null && closingFrom != null;
     const anchor = current ?? closingFrom;
     const items = Children.toArray(children);
@@ -85,6 +148,7 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         const place = {
             open: !closing && current === i,
             refreshing: refreshing === i,
+            mark,
             before,
             after: !closing && current != null && i > current,
             stagger: before && anchor != null ? anchor - 1 - i : returning != null && i < returning ? returning - 1 - i : 0,
@@ -94,5 +158,5 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         };
         return stamp(child, place);
     }) : items;
-    return (_jsxs("div", { className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, children: [stamped, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
+    return (_jsxs("div", { className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, ref: setRef, onClickCapture: clickCapture, onPointerDownCapture: pointerDownCapture, children: [stamped, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
 }

package/dist/sheets/stackCard.d.ts

@@ -5,6 +5,8 @@ export interface StackPlace {
     open: boolean;
     /** the app is reloading this sheet */
     refreshing: boolean;
+    /** the grip at the card's top edge: four dots, or one line */
+    mark: 'dots' | 'line';
     /** tucked under the open sheet. Stays through the first beat of a close */
     before: boolean;
     /** in front of the open sheet, leaving below */

package/dist/sheets/stackCard.js

@@ -14,7 +14,7 @@ export function stackPaint(place, pulling = false) {
     if (!place)
         return {};
     const loading = place.open && place.refreshing;
-    const className = ['stack-card', place.open && 'is-open', place.before && 'is-before', place.after && 'is-after', loading && 'is-loading', pulling && 'is-refreshing'].filter(Boolean).join(' ');
+    const className = ['stack-card', place.mark === 'line' && 'stack-card--line', place.open && 'is-open', place.before && 'is-before', place.after && 'is-after', loading && 'is-loading', pulling && 'is-refreshing'].filter(Boolean).join(' ');
     return {
         className,
         style: place.stagger > 0 ? { '--stagger': String(place.stagger) } : undefined,

package/dist/templates/Home.d.ts

@@ -35,6 +35,8 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
     onRefresh?: (index: number) => void;
     /** the sheet the app is reloading (its index), or `null` — as `SheetStack refreshing` */
     refreshing?: number | null;
+    /** the grip on every sheet: `dots` (default) or `line` — as `SheetStack mark` */
+    mark?: 'dots' | 'line';
     /** 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;
@@ -54,4 +56,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. With a LayerHistory above and no `open` prop, that open sheet is one history entry named `home`. 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, refreshing, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;
+export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, onRefresh, refreshing, mark, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;

package/dist/templates/Home.js

@@ -16,7 +16,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. With a LayerHistory above and no `open` prop, that open sheet is one history entry named `home`. 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, refreshing, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
+export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, onRefresh, refreshing, mark, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
     const layer = useOptionalLayer('home');
     const [local, change] = useControlled(openProp, defaultOpen, onOpenChange);
     // A passed `open` is the parent's. With no LayerHistory the index stays local, so a story without a router still opens sheets.
@@ -50,5 +50,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 === shown || 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: shown, onOpenChange: request, onRefresh: onRefresh, refreshing: refreshing, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], paper: s.paper, 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: shown, onOpenChange: request, onRefresh: onRefresh, refreshing: refreshing, mark: mark, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], paper: s.paper, 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.58",
+  "version": "0.7.59",
   "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.",