@usableapp/cardds 0.7.7 → 0.7.8

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.8 — 2026-09-25
+
+### Changed
+- `Pin error` (the app's answer, a refused OTP): before — the red digits stayed until the next one was typed. After — the Pin
+  shakes red, then EMPTIES itself (`onChange('', false)`), the cursor in the first cell, on the same step — as a `match` miss.
+  Give a new `error` value per refusal (a counter) so a second one shakes again.
+
+### Added
+- `WaitLink` — a Link that waits: `until` (ms time) → counts down ("ขอรหัสใหม่ได้ใน 0:27", `waiting={(t) => …}`), takes no
+  tap until then. The app owns the rule (30 s, +30 s per ask) and sets the next `until` in its onClick. `Link disabled`
+  (muted, knob `--link-disabled-ink`). Stories `WaitLink · Resend`, `SheetSteps · Errors` (ask for a new code).
+- `SheetSteps reached` — controlled progress: how many steps are done. Before: the steps remembered the furthest step reached,
+  so after the app sent `at` back (the server refused the code at the end) the later steps still showed ✓ and their summary.
+  After: `reached={1}` with `at={1}` → the steps after it are "next" again. Once set the app owns it — keep
+  `reached = max(reached, at)` beside `at`. Without it: as before. Story `SheetSteps · Reached` (timebank card 142).
+
 ## 0.7.7 — 2026-09-25
 
 ### Changed (breaking for a confirm PIN)

package/css/lists.css

@@ -206,4 +206,6 @@
 .link--sm { position: relative; font-size: var(--link-sm-font-size, var(--fs-2xs)); min-height: var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)); }
 .link--sm::after { content: ""; position: absolute; inset: calc((var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)) - var(--tap-sm)) / 2) 0; }
 .link--muted { color: var(--link-muted-ink, var(--card-muted)); }
+.link:disabled { color: var(--link-disabled-ink, var(--card-muted)); cursor: default; } /* inactive = muted (a WaitLink counting down) */
+.link--wait { font-variant-numeric: tabular-nums; } /* the countdown's digits keep their width: the words do not jiggle each second */
 .card--3 .link--muted { color: var(--card-3-muted); }

package/dist/actions/Link.d.ts

@@ -9,9 +9,13 @@ export interface LinkProps extends ComponentProps<'a'> {
     sm?: boolean;
     /** without an href it renders as a button */
     href?: string;
+    /** a button link that takes no taps now (reads inactive: muted) — `WaitLink` while it counts down */
+    disabled?: boolean;
 }
 /** Link — an inline text action big enough to tap (40px): "See all ↗" in a card head, "Skip" between pager buttons. */
 export declare function Link({ muted, sm, icon, href, className, children, ...rest }: LinkProps): import("react").DetailedReactHTMLElement<{
+    /** a button link that takes no taps now (reads inactive: muted) — `WaitLink` while it counts down */
+    disabled?: boolean;
     ref?: import("react").Ref<HTMLAnchorElement> | undefined;
     key?: import("react").Key | null | undefined;
     download?: any;

package/dist/actions/WaitLink.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import { type LinkProps } from './Link.js';
+export interface WaitLinkProps extends Omit<LinkProps, 'href'> {
+    /** CONTROLLED: when it may be pressed again (a time in ms, `Date.now()` based). Before that it counts down and takes no taps;
+     *  null / past = ready. The APP owns the rule — 30 s, +30 s each time — and sets a new `until` in its onClick. */
+    until?: number | null;
+    /** the words while it waits, given the time left as "0:27" (default: the children, then the time) */
+    waiting?: (left: string) => ReactNode;
+}
+/**
+ * WaitLink — a Link that waits: "ขอรหัสใหม่ได้ใน 0:27", counting down each second, then "ขอรหัสใหม่" to press (a new OTP, a retry).
+ * A link, not a button: it is the step's second way, under its control; in a SheetStep it stands centred on its own row.
+ */
+export declare function WaitLink({ until, waiting, children, className, disabled, ...rest }: WaitLinkProps): import("react").JSX.Element;

package/dist/actions/WaitLink.js

@@ -0,0 +1,22 @@
+import { Fragment as _Fragment, jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { cx } from '../cx.js';
+import { Link } from './Link.js';
+/**
+ * WaitLink — a Link that waits: "ขอรหัสใหม่ได้ใน 0:27", counting down each second, then "ขอรหัสใหม่" to press (a new OTP, a retry).
+ * A link, not a button: it is the step's second way, under its control; in a SheetStep it stands centred on its own row.
+ */
+export function WaitLink({ until, waiting, children, className, disabled, ...rest }) {
+    const [now, setNow] = useState(() => Date.now());
+    const left = until != null ? Math.ceil((until - now) / 1000) : 0;
+    useEffect(() => {
+        if (until == null || until <= Date.now())
+            return;
+        setNow(Date.now());
+        const t = setInterval(() => { setNow(Date.now()); if (Date.now() >= until)
+            clearInterval(t); }, 250);
+        return () => clearInterval(t);
+    }, [until]);
+    const time = `${Math.floor(Math.max(left, 0) / 60)}:${String(Math.max(left, 0) % 60).padStart(2, '0')}`;
+    return (_jsx(Link, { className: cx('link--wait', className), disabled: left > 0 || disabled, ...rest, children: left > 0 ? (waiting ? waiting(time) : _jsxs(_Fragment, { children: [children, " ", time] })) : children }));
+}

package/dist/cardds.css

@@ -3123,6 +3123,8 @@ button { font: inherit; cursor: pointer; }
 .link--sm { position: relative; font-size: var(--link-sm-font-size, var(--fs-2xs)); min-height: var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)); }
 .link--sm::after { content: ""; position: absolute; inset: calc((var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)) - var(--tap-sm)) / 2) 0; }
 .link--muted { color: var(--link-muted-ink, var(--card-muted)); }
+.link:disabled { color: var(--link-disabled-ink, var(--card-muted)); cursor: default; } /* inactive = muted (a WaitLink counting down) */
+.link--wait { font-variant-numeric: tabular-nums; } /* the countdown's digits keep their width: the words do not jiggle each second */
 .card--3 .link--muted { color: var(--card-3-muted); }
 
 /* ---- css/media.css — cover card, quote, tile grid, fold, mosaic, wave ---- */

package/dist/forms/Pin.d.ts

@@ -10,8 +10,10 @@ export interface PinProps extends Omit<ComponentProps<'div'>, 'onChange' | 'defa
     label?: string;
     /** the code so far, after every change; `complete` once every cell holds a digit */
     onChange?: (code: string, complete: boolean) => void;
-    /** the code is wrong: the digits stay in sight in `--signal-error` (words, no fill) with red edges, the cursor goes back to the
-     *  first cell, and the next digit typed starts a new code. The words are the step's (`SheetStep error`). */
+    /** the code is wrong (the app's answer — an OTP the server refused): the Pin SHAKES with red edges and its digits in sight,
+     *  then empties itself (`onChange('', false)`) and the cursor waits in the first cell for a new try — the same as a `match`
+     *  miss (Lh 2026-09-25; the red digits used to stay until the next one was typed). Give a NEW value for each refusal (a
+     *  counter) so a second one shakes again. The words are the step's (`SheetStep error`): the app keeps them until it clears `error`. */
     error?: unknown;
     /** a FORMAT check on the client: the code it must equal (the first PIN, when this one confirms it). Once every cell is filled
      *  and it differs, the Pin SHAKES with red edges and its digits in sight, the step shows `formatError` under it, then the Pin

package/dist/forms/Pin.js

@@ -14,6 +14,23 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
     const [inner, setInner] = useState(defaultValue);
     const code = (value ?? inner).replace(/\D/g, '').slice(0, length);
     const cell = (i) => ref.current?.querySelectorAll('.pin__cell')[i];
+    /* a miss — a match that failed, or the app's error: shake, red, then the cells empty for a new try on the same step */
+    const latest = useRef({ value, onChange, error });
+    latest.current = { value, onChange, error };
+    const miss = () => {
+        restart.current = true;
+        setShake(true);
+        clearTimeout(reset.current);
+        reset.current = setTimeout(() => {
+            setBad(false);
+            setCleared(latest.current.error);
+            restart.current = false;
+            if (latest.current.value === undefined)
+                setInner('');
+            latest.current.onChange?.('', false);
+            cell(0)?.focus();
+        }, RESET_MS);
+    };
     const set = (next) => {
         next = next.slice(0, length);
         if (bad || said.current) {
@@ -22,20 +39,12 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
             said.current = false;
         }
         clearTimeout(reset.current);
+        setCleared(error); // typed before the cells emptied: the new try has begun, the red goes
         if (match != null && next.length === length && next !== match) {
             setBad(true);
             say(words);
             said.current = true;
-            restart.current = true;
-            setShake(true);
-            reset.current = setTimeout(() => {
-                setBad(false);
-                restart.current = false;
-                if (value === undefined)
-                    setInner('');
-                onChange?.('', false);
-                cell(0)?.focus();
-            }, RESET_MS);
+            miss();
         }
         if (value === undefined)
             setInner(next);
@@ -64,15 +73,21 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
         }
         return null;
     }, () => cell(Math.min(code.length, length - 1))?.focus());
-    const wrong = (error != null && error !== false && error !== '') || bad;
+    const errOn = error != null && error !== false && error !== '';
+    const [cleared, setCleared] = useState(undefined); // the app's error whose miss has played out (its cells emptied)
+    const wrong = (errOn && error !== cleared) || bad;
     const restart = useRef(false);
     useEffect(() => {
-        if (!wrong)
+        if (!errOn) {
+            setCleared(undefined);
+            return;
+        }
+        if (error === cleared)
             return;
-        restart.current = true; // the wrong code stays in sight (red); the next digit typed starts a new one from the first cell
         cell(0)?.focus();
+        miss(); // each new error, once
         // eslint-disable-next-line react-hooks/exhaustive-deps -- each new error, once
-    }, [wrong, error]);
+    }, [error]);
     /* the app emptied the code (a new try: it went back after a mismatch): the red goes with it */
     useEffect(() => {
         if (code || !bad)

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export * from './actions/Segment.js';
 export * from './actions/Fab.js';
 export * from './actions/BtnRow.js';
 export * from './actions/Link.js';
+export * from './actions/WaitLink.js';
 export * from './forms/Field.js';
 export * from './forms/FileBtn.js';
 export * from './forms/AddRow.js';

package/dist/index.js

@@ -42,6 +42,7 @@ export * from './actions/Segment.js';
 export * from './actions/Fab.js';
 export * from './actions/BtnRow.js';
 export * from './actions/Link.js';
+export * from './actions/WaitLink.js';
 export * from './forms/Field.js';
 export * from './forms/FileBtn.js';
 export * from './forms/AddRow.js';

package/dist/sheets/SheetSteps.d.ts

@@ -9,6 +9,12 @@ export interface SheetStepsProps extends ComponentProps<'div'> {
      *  work is really finished (the code checked by the server, the two PINs match), `setAt(at + 1)`; after the last step the app sends. `at = count` = every step done —
      *  the app then closes its Sheet (`state="away"`, a beat after the fold) and says so on the page: the steps never close it themselves. */
     at?: number;
+    /** CONTROLLED progress: how many steps are DONE (0-based: the steps before this one show ✓). Without it the steps remember the
+     *  furthest step reached — a step once passed stays done when `at` goes back. Set it when that progress is GONE: the server
+     *  refused the code at the end, the app sends `at` back to the code step and clears the PINs → `reached={1}`, and the steps
+     *  after it are "next" again, no ✓, no summary. Once set, the APP owns it: raise it as the member goes on (keep
+     *  `reached = max(reached, at)` beside `at`), or a tap back in a `reversible` walk forgets what is after. Read as at least `at`. Lh 2026-09-25 */
+    reached?: number;
     /** UNCONTROLLED: the step it starts on (default 0) */
     defaultAt?: number;
     /** the steps ASK to move — a tap on another step, a swipe, a skip. Controlled: set `at` to it (or don't). */
@@ -24,7 +30,7 @@ export interface SheetStepsProps extends ComponentProps<'div'> {
  * steps on the last one. Goes in a `SheetBody`.
  * The sheet may be dragged down to peek and back — the body keeps where it was scrolled.
  */
-export declare function SheetSteps({ at, defaultAt, onAtChange, reversible, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }: SheetStepsProps): import("react").JSX.Element;
+export declare function SheetSteps({ at, reached, defaultAt, onAtChange, reversible, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }: SheetStepsProps): import("react").JSX.Element;
 export interface SheetStepProps extends Omit<ComponentProps<'li'>, 'title'> {
     /** the step's name — always shown: over the open step, on the folded line of a done one */
     title: ReactNode;

package/dist/sheets/SheetSteps.js

@@ -16,7 +16,7 @@ const StepCtx = createContext(null);
  * steps on the last one. Goes in a `SheetBody`.
  * The sheet may be dragged down to peek and back — the body keeps where it was scrolled.
  */
-export function SheetSteps({ at, defaultAt = 0, onAtChange, reversible = false, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }) {
+export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible = false, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }) {
     const [inner, setInner] = useState(defaultAt);
     const current = at ?? inner;
     const steps = Children.toArray(children).filter(isValidElement);
@@ -25,7 +25,9 @@ export function SheetSteps({ at, defaultAt = 0, onAtChange, reversible = false,
     const [furthest, setFurthest] = useState(current);
     if (current > furthest)
         setFurthest(current);
-    const reach = Math.max(furthest, current);
+    if (reached != null && furthest !== Math.max(reached, current))
+        setFurthest(Math.max(reached, current)); // the app's word wins, and is remembered from there
+    const reach = reached != null ? Math.max(reached, current) : Math.max(furthest, current);
     const ref = useRef(null);
     const first = useRef(true);
     const holderRef = useRef(null);

package/package.json

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