@usableapp/cardds 0.6.7 → 0.6.9

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 > 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.6.9 — 2026-09-23
+
+### Walkthrough (Lh 2026-09-23)
+- **Swipe:** a sideways swipe turns the page (left = next, right = back). The walk still scrolls up and down; a drag must be mostly sideways and at least 48px to count.
+- **Page turn:** the new page slides in from the side as itself, unscrolled. There is no vertical glide, because the leaving and arriving pages now have two separate transition names (`centre-card-out` / `centre-card-in`, was one `centre-card`).
+- **Picture:** a page that opens on a picture shows it full width from the top edge, as tall as the lead (15%) + `--base-content-media-h`; the words start where they did.
+- **Width:** the walk's scroll box is the whole content, edge to edge. The words keep the screen's inset inside each `Page`.
+- **Scroll room:** each page's bottom padding is exactly the bottom layer's height (`--bottom-h`). A page scrolls only when the layer would cover words; at 100% text nothing scrolls.
+
+## 0.6.8 — 2026-09-23
+
+- **`Walkthrough`: a new page starts at its lead.** On a page turn (the pager, or the app changing `at`), the walk scrolls back to the top, so the next page never opens where the last one was scrolled to (Lh 2026-09-23).
+
 ## 0.6.7 — 2026-09-23
 
 ### A walk scrolls as one run (Lh 2026-09-23 — answers timebank #138)

package/css/card.css

@@ -236,21 +236,21 @@
      <section class="page" inert>…</section>
    </div></section> <div class="action-bar action-bar--pager">← →</div> */
 ::view-transition-old(root), ::view-transition-new(root) { animation: none; }
-::view-transition-old(centre-card), ::view-transition-new(centre-card) {
+::view-transition-old(centre-card-out), ::view-transition-new(centre-card-in) {
   animation-duration: var(--motion-slide);
   animation-timing-function: ease-out;
   mix-blend-mode: normal;
 }
-:root[data-slide="next"]::view-transition-old(centre-card) { animation-name: centre-card-out-left; }
-:root[data-slide="next"]::view-transition-new(centre-card) { animation-name: centre-card-in-right; }
-:root[data-slide="back"]::view-transition-old(centre-card) { animation-name: centre-card-out-right; }
-:root[data-slide="back"]::view-transition-new(centre-card) { animation-name: centre-card-in-left; }
+:root[data-slide="next"]::view-transition-old(centre-card-out) { animation-name: centre-card-out-left; }
+:root[data-slide="next"]::view-transition-new(centre-card-in) { animation-name: centre-card-in-right; }
+:root[data-slide="back"]::view-transition-old(centre-card-out) { animation-name: centre-card-out-right; }
+:root[data-slide="back"]::view-transition-new(centre-card-in) { animation-name: centre-card-in-left; }
 @keyframes centre-card-out-left  { to   { translate: -100% 0; opacity: 0; } }
 @keyframes centre-card-out-right { to   { translate:  100% 0; opacity: 0; } }
 @keyframes centre-card-in-right  { from { translate:  100% 0; opacity: 0; } }
 @keyframes centre-card-in-left   { from { translate: -100% 0; opacity: 0; } }
 @media (prefers-reduced-motion: reduce) {
-  ::view-transition-old(centre-card), ::view-transition-new(centre-card) { animation: none; }
+  ::view-transition-old(centre-card-out), ::view-transition-new(centre-card-in) { animation: none; }
 }
 /* the page dots under the card sit centred under it — the indicator belongs
    with the page that changes, never in the bar (Lh, 2026-09-12) */

package/css/step.css

@@ -107,11 +107,12 @@
    (the picture is never pinned). Each page starts at the screen's lead and ends with the same room under it — the lead as
    padding above AND below — so the words begin near the middle and, when a big text size runs them long, scroll up clear.
    The walk shows no scrollbar. */
-.step > .pages { margin-top: 0; scrollbar-width: none; } /* the scrolling box starts at the step's top edge (Lh 2026-09-23) */
+.step > .pages { margin: 0; scrollbar-width: none; touch-action: pan-y; } /* pan-y: the walk scrolls itself up and down; a sideways swipe is the Walkthrough's (it turns the page) */ /* the scrolling box is the whole content: from the step's top edge, edge to edge — no margin (Lh 2026-09-23) */
+.step > .pages > .page { padding-inline: var(--screen-pad); } /* the words keep the inset INSIDE it */
 .step > .pages > .page { margin-top: var(--_lead, 0rem); } /* the lead is each PAGE's margin (15% with no top, the screen's gap under a bar): the words start there and scroll up to the box's edge */
 .step > .pages::-webkit-scrollbar { display: none; }
 .step > .pages > .page {
-  padding-bottom: calc(var(--screen-lead, 15cqh) + var(--bottom-h, 0rem)); /* + the bottom layer, measured by Screen: the last word scrolls clear of it */
+  padding-bottom: var(--bottom-h, 0rem); /* exactly the bottom layer (measured by Screen): a page scrolls ONLY when the layer would cover its words, and then just far enough to clear them — at 100% nothing scrolls (Lh 2026-09-23) */
 }
 
 /* ============================================================
@@ -143,3 +144,17 @@
    them — timebank #137); the words keep the screen's gap as their lead (--_lead, .appbar + .step above) */
 .screen--fill > .appbar:has(+ .step) { margin-bottom: calc(-1 * var(--screen-gap)); }
 .screen--fill > .appbar + .sheet-stage { margin-top: 0; }
+/* a walk page that OPENS on a picture (Lh 2026-09-23): the picture takes the lead's room — as wide as the content (edge to edge), from the top edge, as tall as
+   the lead + the picture's own height (--base-content-media-h), square — so the words start where they always did */
+.step > .pages > .page:has(> :is(img, .ph):first-child) { margin-top: 0; }
+.step > .pages > .page > :is(img, .ph):first-child {
+  width: calc(100% + 2 * var(--screen-pad)); /* the content's width: the page's inset given back */
+  max-width: none;
+  margin-inline: calc(-1 * var(--screen-pad));
+  height: calc(var(--_lead, 0rem) + var(--base-content-media-h, 14rem));
+  max-height: none;
+  border-radius: 0;
+  border-inline: 0;
+  border-top: 0;
+  object-fit: cover;
+}

package/dist/cardds.css

@@ -768,21 +768,21 @@ button { font: inherit; cursor: pointer; }
      <section class="page" inert>…</section>
    </div></section> <div class="action-bar action-bar--pager">← →</div> */
 ::view-transition-old(root), ::view-transition-new(root) { animation: none; }
-::view-transition-old(centre-card), ::view-transition-new(centre-card) {
+::view-transition-old(centre-card-out), ::view-transition-new(centre-card-in) {
   animation-duration: var(--motion-slide);
   animation-timing-function: ease-out;
   mix-blend-mode: normal;
 }
-:root[data-slide="next"]::view-transition-old(centre-card) { animation-name: centre-card-out-left; }
-:root[data-slide="next"]::view-transition-new(centre-card) { animation-name: centre-card-in-right; }
-:root[data-slide="back"]::view-transition-old(centre-card) { animation-name: centre-card-out-right; }
-:root[data-slide="back"]::view-transition-new(centre-card) { animation-name: centre-card-in-left; }
+:root[data-slide="next"]::view-transition-old(centre-card-out) { animation-name: centre-card-out-left; }
+:root[data-slide="next"]::view-transition-new(centre-card-in) { animation-name: centre-card-in-right; }
+:root[data-slide="back"]::view-transition-old(centre-card-out) { animation-name: centre-card-out-right; }
+:root[data-slide="back"]::view-transition-new(centre-card-in) { animation-name: centre-card-in-left; }
 @keyframes centre-card-out-left  { to   { translate: -100% 0; opacity: 0; } }
 @keyframes centre-card-out-right { to   { translate:  100% 0; opacity: 0; } }
 @keyframes centre-card-in-right  { from { translate:  100% 0; opacity: 0; } }
 @keyframes centre-card-in-left   { from { translate: -100% 0; opacity: 0; } }
 @media (prefers-reduced-motion: reduce) {
-  ::view-transition-old(centre-card), ::view-transition-new(centre-card) { animation: none; }
+  ::view-transition-old(centre-card-out), ::view-transition-new(centre-card-in) { animation: none; }
 }
 /* the page dots under the card sit centred under it — the indicator belongs
    with the page that changes, never in the bar (Lh, 2026-09-12) */
@@ -1633,11 +1633,12 @@ button { font: inherit; cursor: pointer; }
    (the picture is never pinned). Each page starts at the screen's lead and ends with the same room under it — the lead as
    padding above AND below — so the words begin near the middle and, when a big text size runs them long, scroll up clear.
    The walk shows no scrollbar. */
-.step > .pages { margin-top: 0; scrollbar-width: none; } /* the scrolling box starts at the step's top edge (Lh 2026-09-23) */
+.step > .pages { margin: 0; scrollbar-width: none; touch-action: pan-y; } /* pan-y: the walk scrolls itself up and down; a sideways swipe is the Walkthrough's (it turns the page) */ /* the scrolling box is the whole content: from the step's top edge, edge to edge — no margin (Lh 2026-09-23) */
+.step > .pages > .page { padding-inline: var(--screen-pad); } /* the words keep the inset INSIDE it */
 .step > .pages > .page { margin-top: var(--_lead, 0rem); } /* the lead is each PAGE's margin (15% with no top, the screen's gap under a bar): the words start there and scroll up to the box's edge */
 .step > .pages::-webkit-scrollbar { display: none; }
 .step > .pages > .page {
-  padding-bottom: calc(var(--screen-lead, 15cqh) + var(--bottom-h, 0rem)); /* + the bottom layer, measured by Screen: the last word scrolls clear of it */
+  padding-bottom: var(--bottom-h, 0rem); /* exactly the bottom layer (measured by Screen): a page scrolls ONLY when the layer would cover its words, and then just far enough to clear them — at 100% nothing scrolls (Lh 2026-09-23) */
 }
 
 /* ============================================================
@@ -1669,6 +1670,20 @@ button { font: inherit; cursor: pointer; }
    them — timebank #137); the words keep the screen's gap as their lead (--_lead, .appbar + .step above) */
 .screen--fill > .appbar:has(+ .step) { margin-bottom: calc(-1 * var(--screen-gap)); }
 .screen--fill > .appbar + .sheet-stage { margin-top: 0; }
+/* a walk page that OPENS on a picture (Lh 2026-09-23): the picture takes the lead's room — as wide as the content (edge to edge), from the top edge, as tall as
+   the lead + the picture's own height (--base-content-media-h), square — so the words start where they always did */
+.step > .pages > .page:has(> :is(img, .ph):first-child) { margin-top: 0; }
+.step > .pages > .page > :is(img, .ph):first-child {
+  width: calc(100% + 2 * var(--screen-pad)); /* the content's width: the page's inset given back */
+  max-width: none;
+  margin-inline: calc(-1 * var(--screen-pad));
+  height: calc(var(--_lead, 0rem) + var(--base-content-media-h, 14rem));
+  max-height: none;
+  border-radius: 0;
+  border-inline: 0;
+  border-top: 0;
+  object-fit: cover;
+}
 
 /* ---- css/forms.css — outlined fields, add-row ---- */
 /* ============================================================

package/dist/scaffold/Centre.js

@@ -41,11 +41,14 @@ export function slideTo(direction, update, scope = document) {
     const moving = () => scope.querySelector('.pages > [aria-current], .screen__centre > .card');
     const name = (el, v) => { if (el)
         el.style.viewTransitionName = v; };
+    /* the leaving page and the arriving one are TWO names, never one: one name makes the browser morph the box from where the old
+       page was (scrolled up) to where the new one is (at its top) — a vertical glide. Two names = each only slides sideways, the new
+       one arriving as itself, unscrolled (Lh 2026-09-23). */
     const before = moving();
-    name(before, 'centre-card');
+    name(before, 'centre-card-out');
     root.dataset.slide = direction;
     let after = null;
-    const transition = document.startViewTransition(() => { flushSync(update); name(before, ''); after = moving(); name(after, 'centre-card'); });
+    const transition = document.startViewTransition(() => { flushSync(update); name(before, ''); after = moving(); name(after, 'centre-card-in'); });
     void transition.finished.finally(() => {
         delete root.dataset.slide;
         name(after, '');

package/dist/templates/Walkthrough.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 import { Screen } from '../scaffold/Screen.js';
 import { Step } from '../sheets/Step.js';
 import { Page } from '../scaffold/Page.js';
@@ -19,6 +19,10 @@ export function Walkthrough({ pages, at: atProp, defaultAt = 0, onAtChange, cta,
     const [own, setOwn] = useState(defaultAt);
     const at = atProp ?? own;
     const step = useRef(null);
+    // a new page starts where a page starts — at its lead, not where the last one was scrolled to (Lh 2026-09-23). A LAYOUT effect:
+    // it runs inside the page turn's commit, before the view transition takes its picture — only the sideways slide shows, no scroll
+    useLayoutEffect(() => { const p = step.current?.querySelector(':scope > .pages'); if (p)
+        p.scrollTop = 0; }, [at]);
     const count = pages.length;
     const go = (to) => {
         if (to < 0 || to >= count || to === at)
@@ -26,10 +30,27 @@ export function Walkthrough({ pages, at: atProp, defaultAt = 0, onAtChange, cta,
         slideTo(to > at ? 'next' : 'back', () => { if (atProp === undefined)
             setOwn(to); onAtChange?.(to); }, step.current ?? document);
     };
+    /* a sideways SWIPE turns the page (Lh 2026-09-23): left = next, right = back. The walk still scrolls up and down itself
+       (touch-action: pan-y); a swipe must be mostly sideways and long enough, so a scroll never turns a page */
+    const start = useRef(null);
+    const swipe = {
+        onPointerDown: (e) => { start.current = { x: e.clientX, y: e.clientY }; },
+        onPointerUp: (e) => {
+            const s0 = start.current;
+            start.current = null;
+            if (!s0)
+                return;
+            const dx = e.clientX - s0.x, dy = e.clientY - s0.y;
+            if (Math.abs(dx) < 48 || Math.abs(dx) < 1.5 * Math.abs(dy))
+                return;
+            go(dx < 0 ? at + 1 : at - 1);
+        },
+        onPointerCancel: () => { start.current = null; },
+    };
     const row = typeof cta === 'function' ? cta({ at, count, go }) : cta;
     const custom = row !== undefined && row !== null;
     const pager = (_jsxs(_Fragment, { children: [_jsx(IconBtn, { icon: "arrow-left", label: backLabel, disabled: at === 0, onClick: () => go(at - 1) }), _jsx(IconBtn, { invert: true, icon: "arrow-right", label: nextLabel, disabled: at === count - 1, onClick: () => go(at + 1) })] }));
     const dots = count > 1 ? _jsx(PagerAt, { at: at + 1, of: count }) : null;
     const bottom = dots || controls.length || ctaLink != null ? (_jsxs(ActionBar, { variant: "tiers", children: [dots, controls.map((c, i) => _jsx(ActionBarTier, { children: c }, i)), _jsx(ActionBarTier, { pager: true, children: custom ? row : pager }), ctaLink != null && _jsx(ActionBarTier, { className: "action-bar__tier--link", children: ctaLink })] })) : (_jsx(ActionBar, { variant: "pager", children: custom ? row : pager }));
-    return (_jsxs(Screen, { fill: true, bottom: bottom, ...rest, children: [_jsx(Step, { ref: step, children: _jsx(Pages, { children: pages.map((p, i) => (_jsxs(Page, { "aria-current": i === at ? 'step' : undefined, inert: i !== at || undefined, children: [p.media, _jsx(CardHead, { level: "h1", heading: p.heading }), typeof p.body === 'string' ? _jsx(Text, { level: "body", children: p.body }) : p.body] }, i))) }) }), children] }));
+    return (_jsxs(Screen, { fill: true, bottom: bottom, ...rest, children: [_jsx(Step, { ref: step, children: _jsx(Pages, { ...swipe, children: pages.map((p, i) => (_jsxs(Page, { "aria-current": i === at ? 'step' : undefined, inert: i !== at || undefined, children: [p.media, _jsx(CardHead, { level: "h1", heading: p.heading }), typeof p.body === 'string' ? _jsx(Text, { level: "body", children: p.body }) : p.body] }, i))) }) }), children] }));
 }

package/package.json

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