@usableapp/cardds 0.7.35 → 0.7.36

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.36 — 2026-10-01
+
+### Added
+- **`Screen ready` — one outcome, drawn once** (Lh 2026-10-01). A screen that can come out more than one way (signed in or not, a list or its empty state, a redirect) showed one outcome and then turned into another. Now: `<Screen ready={known}>` — `false` while the app is still finding out. Nothing of the screen is drawn (no top, content, bottom; `data-pending`, `aria-busy`), and when it is reached through `slideScreen` or the back button (`installScreenSlide`) the screen BEFORE stays until it is ready — at most 3 s — then the right one slides in. Default `true`: nothing changes until a screen sets it. Every template passes it through (`Home`, `CallSheet`, `Walkthrough`). To do in an app: every screen that decides after its first paint (a check in an effect, a redirect) gets `ready`; on the first load hold `Splash done` until the first screen is known.
+
 ## 0.7.35 — 2026-10-01
 
 ### Fixed

package/README.md

@@ -355,6 +355,11 @@ between at 40% down the screen (see *Anatomy*, "Where the centre is"):
     one height, the round pager turns them (`slideTo()`), the words slide like a page. No sheet there.
     ONE SCREEN TO THE NEXT (a route change) slides the WHOLE screen the same way: `slideScreen(() => navigate(to), 'next' | 'back')`,
     and `installScreenSlide()` once at app start for the back button (story `Step · WalksOn`). `data-slide="off"` on a Screen = no slide.
+    ONE OUTCOME, DRAWN ONCE (Lh 2026-10-01): a screen that can come out more than one way (signed in or not, a list or
+    its empty state, a redirect) is NOT drawn until the app knows which — `<Screen ready={known}>`. Not ready = nothing of it
+    is drawn; arrived at through `slideScreen` / the back button, the screen before stays until it is ready (at most 3 s), then
+    the right one slides in. Never one outcome first and another after (story `Step · ArrivesReady`). On a first load there is
+    no screen before: hold the `Splash` (`done`) until the first screen is known.
   - *Sheets the app calls:* the base offers WAYS IN — sign in · new phone · join — as buttons (`.cta-pack`); each
     way has a sheet that holds its WHOLE form and its own submit on its foot, starting `.sheet--away` (not on the
     screen: slid out, hidden once gone, `inert`). **The wiring is the app's, not cardds's**: a `useState` of which

package/dist/scaffold/Screen.d.ts

@@ -11,15 +11,21 @@ export interface ScreenProps extends ComponentProps<'div'> {
     /** BOTTOM: an `ActionBar` (or a `FloatBar`) — a LAYER over the content's foot, as tall as its rows need.
      *  Never with a `Sheet` in the content: a sheet finishes on its own foot (warns once). */
     bottom?: ReactNode;
+    /** `false` while the app does not yet know WHICH screen this is (signed in or not, a member with or without a request…):
+     *  nothing of it is drawn — no top, content or bottom — so a screen never shows one outcome and then turns into another.
+     *  Arrived at through `slideScreen`, the screen before stays until this turns true (at most 3 s). Default true. */
+    ready?: boolean;
 }
 /**
  * Screen — the mobile screen in THREE parts: **top** and **content** (the children) in one flex column, the content down to the
  * screen's foot; **bottom** a LAYER over it there (Lh 2026-09-23). Top = `TopBar` / `AppBar`, or `top="lead"` (no bar, the words start
  * 15% down). Content = a box of components one after another — a `Step` (`Pages` of `Page`s / a `Page` [+ `Sheet`]), a `Centre`, a
- * `SheetStack`… Bottom = an `ActionBar` (the walk's `PagerAt` its first row) or a `FloatBar`, covering the content's foot on purpose. Max 25rem wide, the standard inset, no vertical padding. A plain Screen (no `fill`) scrolls.
+ * `SheetStack`… Bottom = an `ActionBar` (the walk's `PagerAt` its first row) or a `FloatBar`, covering the content's foot on purpose. Max 30rem wide, the standard inset, no vertical padding. A plain Screen (no `fill`) scrolls.
+ * ONE OUTCOME, DRAWN ONCE (Lh 2026-10-01): a screen that can come out more than one way is not drawn until the app knows which —
+ * `ready={false}` until then.
  * The slots set the order; children laid by hand in the same order still work.
  */
-export declare function Screen({ fill, palette, as, top, bottom, className, children, ref, ...rest }: ScreenProps): import("react").DetailedReactHTMLElement<{
+export declare function Screen({ fill, palette, as, top, bottom, ready, className, children, ref, ...rest }: ScreenProps): import("react").DetailedReactHTMLElement<{
     key?: import("react").Key | null | undefined;
     defaultChecked?: boolean | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
@@ -80,7 +86,7 @@ export declare function Screen({ fill, palette, as, top, bottom, className, chil
     "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
     "aria-braillelabel"?: string | undefined;
     "aria-brailleroledescription"?: string | undefined;
-    "aria-busy"?: (boolean | "true" | "false") | undefined;
+    "aria-busy": (boolean | "true" | "false") | undefined;
     "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
     "aria-colcount"?: number | undefined;
     "aria-colindex"?: number | undefined;
@@ -301,5 +307,6 @@ export declare function Screen({ fill, palette, as, top, bottom, className, chil
     onTransitionStartCapture?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
     className: string;
     'data-palette': Palette | undefined;
+    'data-pending': string | undefined;
     ref: Ref<HTMLDivElement>;
 }, HTMLDivElement>;

package/dist/scaffold/Screen.js

@@ -5,10 +5,12 @@ import { cx } from '../cx.js';
  * Screen — the mobile screen in THREE parts: **top** and **content** (the children) in one flex column, the content down to the
  * screen's foot; **bottom** a LAYER over it there (Lh 2026-09-23). Top = `TopBar` / `AppBar`, or `top="lead"` (no bar, the words start
  * 15% down). Content = a box of components one after another — a `Step` (`Pages` of `Page`s / a `Page` [+ `Sheet`]), a `Centre`, a
- * `SheetStack`… Bottom = an `ActionBar` (the walk's `PagerAt` its first row) or a `FloatBar`, covering the content's foot on purpose. Max 25rem wide, the standard inset, no vertical padding. A plain Screen (no `fill`) scrolls.
+ * `SheetStack`… Bottom = an `ActionBar` (the walk's `PagerAt` its first row) or a `FloatBar`, covering the content's foot on purpose. Max 30rem wide, the standard inset, no vertical padding. A plain Screen (no `fill`) scrolls.
+ * ONE OUTCOME, DRAWN ONCE (Lh 2026-10-01): a screen that can come out more than one way is not drawn until the app knows which —
+ * `ready={false}` until then.
  * The slots set the order; children laid by hand in the same order still work.
  */
-export function Screen({ fill, palette, as = 'div', top, bottom, className, children, ref, ...rest }) {
+export function Screen({ fill, palette, as = 'div', top, bottom, ready = true, className, children, ref, ...rest }) {
     const own = useRef(null);
     useEffect(() => {
         const el = own.current;
@@ -25,7 +27,7 @@ export function Screen({ fill, palette, as = 'div', top, bottom, className, chil
             return;
         }
         return watchSize([bar], () => el.style.setProperty('--bottom-h', `${bar.offsetHeight}px`));
-    }, [bottom]);
+    }, [bottom, ready]);
     const setRef = (node) => {
         own.current = node;
         if (typeof ref === 'function')
@@ -33,5 +35,5 @@ export function Screen({ fill, palette, as = 'div', top, bottom, className, chil
         else if (ref)
             ref.current = node;
     };
-    return createElement(as, { className: cx('screen', fill && 'screen--fill', top === 'lead' && 'screen--lead', className), 'data-palette': palette, ref: setRef, ...rest }, top !== 'lead' ? top : null, children, bottom);
+    return createElement(as, { className: cx('screen', fill && 'screen--fill', top === 'lead' && 'screen--lead', className), 'data-palette': palette, 'data-pending': ready ? undefined : '', 'aria-busy': ready ? undefined : true, ref: setRef, ...rest }, ready && top !== 'lead' ? top : null, ready ? children : null, ready ? bottom : null);
 }

package/dist/scaffold/slideScreen.d.ts

@@ -3,6 +3,7 @@ import type { SlideDirection } from './Centre.js';
  * slideScreen — go to the NEXT SCREEN (a route change) with the whole screen sliding, as a walk's pages do. Wrap the app's
  * navigate in it: `slideScreen(() => navigate('/download'))` — `back` for a way back: `slideScreen(() => navigate(-1), 'back')`.
  * The update may render at once or later (a route's chunk loading): the slide waits for the new Screen (at most 0.8 s).
+ * A new Screen that is not `ready` is waited for (at most 3 s) — the old screen stays until then.
  * A Screen with `data-slide="off"` (or none at all) is not slid. `scope`: where the one Screen is (default the document — an
  * app has one). Without view transitions (the browser floor) it just runs the update.
  */

package/dist/scaffold/slideScreen.js

@@ -3,16 +3,31 @@
    transition named for the move only: the leaving `.screen` is `screen-out`, the arriving one `screen-in`. */
 const screenIn = (scope) => scope.querySelector('.screen:not(.screen .screen)');
 /** wait until the screen in `scope` CHANGED — another element, or new content in the same one (React may keep the element when
-    both routes render a Screen in the same place) — a route rendered, sync or not; at most `ms` */
-function newScreen(scope, old, ms = 800) {
+    both routes render a Screen in the same place) — a route rendered, sync or not; at most `ms`. A new Screen that is not
+    `ready` yet (`data-pending`) is waited for too, at most `hold`: the old screen stays until the new one knows what it is. */
+function newScreen(scope, old, ms = 800, hold = 3000) {
     return new Promise((done) => {
+        const pending = (el) => !!el?.hasAttribute('data-pending');
         const now = screenIn(scope);
-        if (now !== old)
+        if (now !== old && !pending(now))
             return done(now);
         const root = scope instanceof Document ? scope.documentElement : scope;
-        const mo = new MutationObserver(() => { mo.disconnect(); clearTimeout(t); done(screenIn(scope)); });
-        mo.observe(root, { childList: true, subtree: true });
-        const t = setTimeout(() => { mo.disconnect(); done(screenIn(scope)); }, ms);
+        const end = () => { mo.disconnect(); clearTimeout(t); done(screenIn(scope)); };
+        let held = false;
+        const look = () => {
+            if (!pending(screenIn(scope)))
+                return end();
+            if (!held) {
+                held = true;
+                clearTimeout(t);
+                t = setTimeout(end, hold);
+            }
+        };
+        const mo = new MutationObserver(look);
+        mo.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-pending'] });
+        let t = setTimeout(end, ms);
+        if (pending(now))
+            look();
     });
 }
 let running = false;
@@ -20,6 +35,7 @@ let running = false;
  * slideScreen — go to the NEXT SCREEN (a route change) with the whole screen sliding, as a walk's pages do. Wrap the app's
  * navigate in it: `slideScreen(() => navigate('/download'))` — `back` for a way back: `slideScreen(() => navigate(-1), 'back')`.
  * The update may render at once or later (a route's chunk loading): the slide waits for the new Screen (at most 0.8 s).
+ * A new Screen that is not `ready` is waited for (at most 3 s) — the old screen stays until then.
  * A Screen with `data-slide="off"` (or none at all) is not slid. `scope`: where the one Screen is (default the document — an
  * app has one). Without view transitions (the browser floor) it just runs the update.
  */

package/package.json

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