@usableapp/cardds 0.7.61 → 0.7.62

package/CHANGELOG.md

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

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

@@ -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/dist/cardds.css

@@ -1686,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.61",
+  "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.",