@usableapp/cardds 0.7.60 → 0.7.62

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.62 — 2026-10-06
+
+### Added
+- **`Sheet` takes `refreshing`** (Lh 2026-10-06) — a boolean, off unless you set it. While `true`, the sheet's grab mark (the line, or the dots with `mark="dots"`) changes colour the way a stack sheet's does, and the sheet is `aria-busy`. Set it when you start reloading what the sheet shows, clear it when the data is in: `<Sheet refreshing={loading} …>`. The single sheet has no pull to refresh of its own and does not fetch — when to reload is yours. Omit it and nothing changes.
+
+## 0.7.61 — 2026-10-06
+
+### Changed
+- **A sheet's grab line is 1px** (Lh 2026-10-06) — it was 2px. On a single `Sheet` (the default mark) and on a stack sheet with `mark="line"`. Same length, same place. The thickness is one root token, `--hairline-w` (1px): set it on `:root` in your `theme.css` to tune it (`2px` gives the old line back). Nothing to change in a screen; a test that measured the handle's height reads 1.
+- **A `paper` stack sheet's head band is slimmer** (Lh 2026-10-06) — the white starts 8px (`--sp-2`) under the head, not a whole `--card-gap` (20px): the coloured band of an open sheet is 77.5px tall at the defaults, it was 89.5. `SheetStack` / `Home` sheets with `paper` only; a single paper `Sheet`, a stack sheet without `paper`, and the peeked heads are unchanged. Nothing to change in a screen; a test that measured where the white body starts under the head must expect 8px.
+
 ## 0.7.60 — 2026-10-06
 
 ### Fixed

package/README.md

@@ -278,7 +278,9 @@ whose markup has rules, because the sheet's box is the step itself:
   `.sheet__body` with what the member acts on. The handle and the head are
   pinned; the body is the one thing that scrolls, to the card's own edges. The
   handle is a line, or four dots (`mark="dots"`): both sit in the card's top
-  padding, the same distance from the edge, so the title stays put. `paper` makes
+  padding, the same distance from the edge, so the title stays put. `refreshing`
+  (off unless the app sets it) changes the mark's colour while the app reloads
+  what the sheet shows, as a stack sheet's does; the sheet does not fetch. `paper` makes
   the content white while the head keeps the sheet's colour (`tone`, as a card).
   The same prop on a `StackSheet`, or on a `Card` in a stack: the head keeps the
   tone, the body and the foot are white, and the gap under the head stays the tone.

package/css/sheet.css

@@ -90,7 +90,7 @@
 /* --sheet-peek is declared on the BOX the sheet slides in, not on the sheet: the words behind a peeked sheet
    have to read it too (step.css keeps that much room under them), and a token only flows down. The sheet
    inherits it. A sheet whose head is taller retunes it on the box. */
-:is(.step, .sheet-stage) { --_handle: var(--sp-0); --sheet-peek: calc(var(--card-pad-rest) + var(--sheet-head-h) + var(--card-gap-rest) + var(--safe-bottom)); } /* + the gesture bar: the peeked head stands above it. The handle sits IN the card's top padding, so the strip is that padding, the title row and the gap under it */
+:is(.step, .sheet-stage) { --_handle: var(--hairline-w); --sheet-peek: calc(var(--card-pad-rest) + var(--sheet-head-h) + var(--card-gap-rest) + var(--safe-bottom)); } /* + the gesture bar: the peeked head stands above it. The handle sits IN the card's top padding, so the strip is that padding, the title row and the gap under it */
 /* the head's floor: a tap, or an h2 line with its Thai-mark padding when the type is bigger than that (a large text-size
    setting on a narrow phone) — the strip and the head read the same number, so the title row is always inside the strip */
 :root { --sheet-head-h: max(var(--tap), calc(var(--fs-h2) * 1.25 + var(--sp-2))); }
@@ -231,6 +231,22 @@
   background-size: var(--_dot) var(--_dot);
   background-position: 0 0, var(--_step) 0, calc(2 * var(--_step)) 0, calc(3 * var(--_step)) 0;
 }
+/* the app reloads what the sheet shows (`refreshing`, off unless set): the mark changes colour exactly as a stack sheet's grip
+   does — white → black and back, so a light sheet and a dark one each get a moment it stands out. --_grip and the keyframes are
+   the stack's (stack.css): one sign for both. Nothing travels. */
+.sheet.is-loading > .sheet__handle {
+  opacity: 1;
+  background-color: color-mix(in srgb, black calc(var(--_grip) * 100%), white);
+  animation: stack-grip-dissolve 0.4s ease-in-out infinite alternate;
+}
+.sheet.is-loading > .sheet__handle--dots {
+  --_ink: color-mix(in srgb, black calc(var(--_grip) * 100%), white);
+  background-color: transparent;
+}
+@media (prefers-reduced-motion: reduce) {
+  .sheet.is-loading > .sheet__handle { animation: none; background-color: currentColor; }
+  .sheet.is-loading > .sheet__handle--dots { --_ink: currentColor; background-color: transparent; }
+}
 .sheet__handle::before {
   content: "";
   position: absolute;

package/css/stack.css

@@ -211,14 +211,14 @@
 }
 @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. As thin as the Sheet's (--sp-0, half a
-   dot), from the dots' top, as the Sheet's line starts there too. A bar and two round ends; the resting
+   same --_grip-ink, so while its sheet reloads it changes colour exactly as the dots do. As thin as the Sheet's (--hairline-w),
+   from the dots' top, as the Sheet's line starts there too. 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-h: var(--sp-0);
+  --_grip-h: var(--hairline-w);
   --_grip-end: calc((var(--_grip-w) - var(--_grip-h)) / 2);
   background-image: var(--_grip-img), var(--_grip-bar), var(--_grip-img);
   background-size: var(--_grip-h) var(--_grip-h), calc(var(--_grip-w) - var(--_grip-h)) var(--_grip-h), var(--_grip-h) var(--_grip-h);
@@ -335,7 +335,11 @@
    into the stack the card colour fades in quickly (--motion-quick) and that fade ends with the
    sheet's own slide (--motion-sheet, plus the same stagger), so the corner is the head colour
    at the moment the sheet stops. Rising, the body is white at once. */
+/* the head's band is as slim as it can be (Lh 2026-10-06: 20 over · 48 head · 20 under read as a heavy bar): the white starts
+   --sp-2 under the head, not a whole --card-gap. The body is pulled up by the difference — the card's gap is left alone, the
+   stack's step and the body's own rows read it. */
 .sheet-stack > .card.sheet--paper > .sheet__body {
+  margin-top: calc(var(--sp-2) - var(--card-gap));
   padding-top: calc(var(--sp-6) + var(--_refresh, 0px));
   transition: padding-top var(--motion-sheet) ease, background-color 0s linear;
 }

package/css/tokens.css

@@ -86,6 +86,7 @@
 
   /* ---- borders / rules / elevation (px on purpose: crisp at any scale) ---- */
   --border-w: 1.5px;
+  --hairline-w: 1px;                               /* the thinnest mark: a sheet's grab line (Lh 2026-10-06) */
   --rule-w: 2px;                                   /* dotted connectors, picker rules */
   --scroll-w: 1px;                                 /* the scrollbar of a .bleed track: a hairline of ink */
   --focus: 2px solid currentColor;                 /* :focus-visible ring */

package/dist/cardds.css

@@ -127,6 +127,7 @@
 
   /* ---- borders / rules / elevation (px on purpose: crisp at any scale) ---- */
   --border-w: 1.5px;
+  --hairline-w: 1px;                               /* the thinnest mark: a sheet's grab line (Lh 2026-10-06) */
   --rule-w: 2px;                                   /* dotted connectors, picker rules */
   --scroll-w: 1px;                                 /* the scrollbar of a .bleed track: a hairline of ink */
   --focus: 2px solid currentColor;                 /* :focus-visible ring */
@@ -1212,14 +1213,14 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 }
 @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. As thin as the Sheet's (--sp-0, half a
-   dot), from the dots' top, as the Sheet's line starts there too. A bar and two round ends; the resting
+   same --_grip-ink, so while its sheet reloads it changes colour exactly as the dots do. As thin as the Sheet's (--hairline-w),
+   from the dots' top, as the Sheet's line starts there too. 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-h: var(--sp-0);
+  --_grip-h: var(--hairline-w);
   --_grip-end: calc((var(--_grip-w) - var(--_grip-h)) / 2);
   background-image: var(--_grip-img), var(--_grip-bar), var(--_grip-img);
   background-size: var(--_grip-h) var(--_grip-h), calc(var(--_grip-w) - var(--_grip-h)) var(--_grip-h), var(--_grip-h) var(--_grip-h);
@@ -1336,7 +1337,11 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
    into the stack the card colour fades in quickly (--motion-quick) and that fade ends with the
    sheet's own slide (--motion-sheet, plus the same stagger), so the corner is the head colour
    at the moment the sheet stops. Rising, the body is white at once. */
+/* the head's band is as slim as it can be (Lh 2026-10-06: 20 over · 48 head · 20 under read as a heavy bar): the white starts
+   --sp-2 under the head, not a whole --card-gap. The body is pulled up by the difference — the card's gap is left alone, the
+   stack's step and the body's own rows read it. */
 .sheet-stack > .card.sheet--paper > .sheet__body {
+  margin-top: calc(var(--sp-2) - var(--card-gap));
   padding-top: calc(var(--sp-6) + var(--_refresh, 0px));
   transition: padding-top var(--motion-sheet) ease, background-color 0s linear;
 }
@@ -1540,7 +1545,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 /* --sheet-peek is declared on the BOX the sheet slides in, not on the sheet: the words behind a peeked sheet
    have to read it too (step.css keeps that much room under them), and a token only flows down. The sheet
    inherits it. A sheet whose head is taller retunes it on the box. */
-:is(.step, .sheet-stage) { --_handle: var(--sp-0); --sheet-peek: calc(var(--card-pad-rest) + var(--sheet-head-h) + var(--card-gap-rest) + var(--safe-bottom)); } /* + the gesture bar: the peeked head stands above it. The handle sits IN the card's top padding, so the strip is that padding, the title row and the gap under it */
+:is(.step, .sheet-stage) { --_handle: var(--hairline-w); --sheet-peek: calc(var(--card-pad-rest) + var(--sheet-head-h) + var(--card-gap-rest) + var(--safe-bottom)); } /* + the gesture bar: the peeked head stands above it. The handle sits IN the card's top padding, so the strip is that padding, the title row and the gap under it */
 /* the head's floor: a tap, or an h2 line with its Thai-mark padding when the type is bigger than that (a large text-size
    setting on a narrow phone) — the strip and the head read the same number, so the title row is always inside the strip */
 :root { --sheet-head-h: max(var(--tap), calc(var(--fs-h2) * 1.25 + var(--sp-2))); }
@@ -1681,6 +1686,22 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   background-size: var(--_dot) var(--_dot);
   background-position: 0 0, var(--_step) 0, calc(2 * var(--_step)) 0, calc(3 * var(--_step)) 0;
 }
+/* the app reloads what the sheet shows (`refreshing`, off unless set): the mark changes colour exactly as a stack sheet's grip
+   does — white → black and back, so a light sheet and a dark one each get a moment it stands out. --_grip and the keyframes are
+   the stack's (stack.css): one sign for both. Nothing travels. */
+.sheet.is-loading > .sheet__handle {
+  opacity: 1;
+  background-color: color-mix(in srgb, black calc(var(--_grip) * 100%), white);
+  animation: stack-grip-dissolve 0.4s ease-in-out infinite alternate;
+}
+.sheet.is-loading > .sheet__handle--dots {
+  --_ink: color-mix(in srgb, black calc(var(--_grip) * 100%), white);
+  background-color: transparent;
+}
+@media (prefers-reduced-motion: reduce) {
+  .sheet.is-loading > .sheet__handle { animation: none; background-color: currentColor; }
+  .sheet.is-loading > .sheet__handle--dots { --_ink: currentColor; background-color: transparent; }
+}
 .sheet__handle::before {
   content: "";
   position: absolute;

package/dist/sheets/Sheet.d.ts

@@ -23,6 +23,8 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
     handle?: boolean | string;
     /** the grab mark. `line` (default) or `dots`: both sit in the card's top padding, the same distance from the edge, so the title does not move */
     mark?: 'line' | 'dots';
+    /** the app is reloading what this sheet shows: while `true` the grab mark (line or dots) changes colour, as a stack sheet's does, and the sheet is `aria-busy`. Off unless the app sets it — the sheet does not fetch and has no pull to refresh of its own */
+    refreshing?: boolean;
     /** the card tone slot, as `Card tone` — 2 and up add `card--N`. The head shows it; with `paper` the content does not */
     tone?: 1 | 2 | 3 | 4 | 5;
     /** the content is white paper and the head keeps the sheet's colour. The same prop on a `StackSheet` or a `Card` in a stack. Omit it and the content is the same colour as the head */
@@ -49,4 +51,4 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
  * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
  * first's `onSettled`) — the app adds no timer.
  */
-export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, mark, tone, paper, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
+export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, mark, refreshing, tone, paper, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;

package/dist/sheets/Sheet.js

@@ -38,7 +38,7 @@ function markLong(node, long) {
  * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
  * first's `onSettled`) — the app adds no timer.
  */
-export function Sheet({ state, defaultState = 'half', onStateChange, onSettled, states, handle = true, mark = 'line', tone, paper, className, children, onFocus, ...rest }) {
+export function Sheet({ state, defaultState = 'half', onStateChange, onSettled, states, handle = true, mark = 'line', refreshing, tone, paper, className, children, onFocus, ...rest }) {
     const [current, request] = useControlled(state, defaultState, onStateChange);
     const ref = useRef(null);
     const handleRef = useRef(null);
@@ -131,5 +131,5 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
             return; // the click that follows a drag is not a tap
         request(current === 'peek' ? (allowed().includes(home.current) ? home.current : allowed().find((s) => s !== 'peek') ?? 'half') : 'peek', 'tap');
     };
-    return (_jsxs("article", { ref: ref, className: cx('card sheet', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', `sheet--${shown}`, className), inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: cx('sheet__handle', mark === 'dots' && 'sheet__handle--dots'), type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), Children.map(children, (node) => markLong(node, titleLong))] }));
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', `sheet--${shown}`, refreshing && 'is-loading', className), "aria-busy": refreshing || undefined, inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: cx('sheet__handle', mark === 'dots' && 'sheet__handle--dots'), type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), Children.map(children, (node) => markLong(node, titleLong))] }));
 }

package/package.json

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