@usableapp/cardds 0.7.25 → 0.7.27

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.7.27 — 2026-09-29
+
+### Changed
+- `StackSheet` (so `Home`): the open sheet's back button (chevron down) is HIDDEN for now — Lh 2026-09-29: not used in real work yet. A tap on the open sheet's title still folds it. `backAt="end"` (or `"start"`) brings it back; `Home backAt` passes it through. New value `backAt="none"` = the default.
+
+## 0.7.26 — 2026-09-29
+
+### Fixed (`cardds check` / ESLint — two holes mailpool found, 2026-09-29)
+- `sheet-unmounted` now also catches a `Sheet` whose ANCESTOR is on a condition — `{cond && <SheetStage …><Sheet …/></SheetStage>}` vanishes the same way. Before: only a condition right on the `<Sheet>`.
+
+### Fixed
+- `SheetStage over` on a SCROLLING screen (a `Screen` without `fill`) now holds to the phone's window (`position: fixed`). Before: it covered the whole page, so scrolled down the sheet and the scrim were off screen (mailpool, 2026-09-29). Nothing to change in a screen.
+
 ## 0.7.25 — 2026-09-29
 
 ### Fixed

package/css/sheet.css

@@ -257,6 +257,9 @@
   background: transparent;
   --_top: 0rem;
 }
+/* …on a SCROLLING screen (no fill) the screen is taller than the phone: absolute would cover the whole page, and scrolled
+   down the sheet and the scrim are off screen (mailpool, 2026-09-29). There the stage holds to the phone's window. */
+.screen:not(.screen--fill) > .sheet-stage--over { position: fixed; }
 .appbar + .sheet-stage { margin-top: calc(-1 * (var(--header-h) + var(--header-gap, 0rem))); }
 .sheet-stage__bg { position: absolute; inset: 0; } /* map / previous cards behind */
 /* the hero: ONE thing shown in the band a half sheet leaves open (a postcard being made,

package/dist/cardds.css

@@ -1545,6 +1545,9 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   background: transparent;
   --_top: 0rem;
 }
+/* …on a SCROLLING screen (no fill) the screen is taller than the phone: absolute would cover the whole page, and scrolled
+   down the sheet and the scrim are off screen (mailpool, 2026-09-29). There the stage holds to the phone's window. */
+.screen:not(.screen--fill) > .sheet-stage--over { position: fixed; }
 .appbar + .sheet-stage { margin-top: calc(-1 * (var(--header-h) + var(--header-gap, 0rem))); }
 .sheet-stage__bg { position: absolute; inset: 0; } /* map / previous cards behind */
 /* the hero: ONE thing shown in the band a half sheet leaves open (a postcard being made,

package/dist/sheets/StackSheet.d.ts

@@ -26,8 +26,9 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
     foot?: ReactNode;
     /** the back button's label (shown once the sheet is open) */
     backLabel?: string;
-    /** where the back button stands: `end` (default — after the tabs, chevron DOWN: the sheet folds down, Lh 2026-09-29) or `start` (before the title, chevron left) */
-    backAt?: 'start' | 'end';
+    /** where the back button stands: `none` (default — hidden for now, Lh 2026-09-29: not used in real work yet; a tap on the open sheet's title folds it) ·
+     *  `end` (after the tabs, chevron DOWN: the sheet folds down) · `start` (before the title, chevron left) */
+    backAt?: 'none' | 'start' | 'end';
 }
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·

package/dist/sheets/StackSheet.js

@@ -17,7 +17,7 @@ import { Badge } from '../numbers/Badge.js';
  * a count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
-export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = 'Back', backAt = 'end', className, children, ...rest }) {
+export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = 'Back', backAt = 'none', className, children, ...rest }) {
     const [tab, pick] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id, onTabChange);
     // a title longer than its room does not wrap: it runs sideways, like a song title in a short slot — the room it overflows by
     // is measured here (the tabs may grow with the text size) and handed to the CSS as --_over

package/dist/templates/Home.d.ts

@@ -1,7 +1,7 @@
 import { type ComponentProps, type ReactNode } from 'react';
 import type { Tone } from '../cards/Card.js';
 import { Screen } from '../scaffold/Screen.js';
-import { type StackSheetTab } from '../sheets/StackSheet.js';
+import { type StackSheetTab, type StackSheetProps } from '../sheets/StackSheet.js';
 export interface HomeSheet {
     /** the sheet head's title — an h2 (the page's one h1 is in `base`) */
     title: ReactNode;
@@ -36,6 +36,8 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
     keep?: boolean;
     /** the open sheet's back button label */
     backLabel?: string;
+    /** the open sheet's back button — see `StackSheet backAt` (default `none`: hidden for now) */
+    backAt?: StackSheetProps['backAt'];
     /** layers over the screen (a SheetStage over + Modal) */
     children?: ReactNode;
 }
@@ -46,4 +48,4 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
  * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
-export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, base, keep, backLabel, children, ...rest }: HomeProps): import("react").JSX.Element;
+export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;

package/dist/templates/Home.js

@@ -14,7 +14,7 @@ const LEAVE = 800; // ms: a closing sheet keeps its body until it has slid home
  * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
-export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, base, keep, backLabel = 'Back', children, ...rest }) {
+export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, base, keep, backLabel = 'Back', backAt, children, ...rest }) {
     const [open, change] = useControlled(openProp, defaultOpen, onOpenChange);
     const [leaving, setLeaving] = useState(null);
     const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
@@ -34,5 +34,5 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
     }, [leaving]);
     const [tabs, setTabs] = useState(() => Object.fromEntries(sheets.map((x, i) => [i, x.defaultTab ?? x.tabs?.[0]?.id])));
     const shows = (i) => i === open || i === leaving || (keep && seen.has(i));
-    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: open, onOpenChange: change, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
+    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: open, onOpenChange: change, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, backAt: backAt, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
 }

package/lint/rules.mjs

@@ -42,6 +42,21 @@ function tagAt(text, start) {
   return text.slice(start);
 }
 
+/** a whole JSX element from its `<Name`: to its matching `</Name>` (same-name nesting counted), or the opening tag if self-closing */
+function elementAt(text, start) {
+  const open = tagAt(text, start);
+  if (open.endsWith('/>')) return open;
+  const name = text.slice(start + 1).match(/^[\w.]+/)[0];
+  const re = new RegExp(`<${name}\\b|</${name}>`, 'g');
+  re.lastIndex = start + open.length;
+  let depth = 1, m;
+  while ((m = re.exec(text))) {
+    if (m[0].startsWith('</')) { if (--depth === 0) return text.slice(start, m.index + m[0].length); }
+    else if (!tagAt(text, m.index).endsWith('/>')) depth++;
+  }
+  return text.slice(start);
+}
+
 /** the expression of a `{…}` attribute value from its opening brace */
 function braceAt(text, start) {
   let depth = 0, quote = null;
@@ -88,14 +103,22 @@ export function checkSource(source, file, { classes = carddsClasses() } = {}) {
     if (hit.length) add('raw-class', 'error', m.index, `cardds class written by hand (${hit.map((w) => '.' + w).join(' ')}): the look without the behaviour — use the cardds component (its props pick the classes), or a knob / theme.css for the look.`);
   }
 
-  // 2 · Sheet: controlled with no way to move · put in the tree on a condition with no slide out
+  // 2 · Sheet: controlled with no way to move · put in the tree on a condition (its own, or an ancestor's — a SheetStage, a div) with no slide out
   for (const m of text.matchAll(/<Sheet\b/g)) {
     const tag = tagAt(text, m.index);
     if (/\sstate\s*=/.test(tag) && !/\sonStateChange\s*=/.test(tag))
       add('sheet-frozen', 'warn', m.index, '<Sheet state> without onStateChange: the handle, the drag and the keyboard climb only ASK — nothing answers, the sheet cannot move. Add onStateChange, or use defaultState.');
-    const before = text.slice(Math.max(0, m.index - 40), m.index);
-    if (/(?:&&|\?|:)\s*\(?\s*$/.test(before) && !/\sonSettled\s*=/.test(tag))
-      add('sheet-unmounted', 'warn', m.index, '<Sheet> rendered on a condition without onSettled: taken out of the tree it vanishes instead of sliding out. Set state="away" and unmount it in onSettled (state === "away") — or keep it mounted and switch its state.');
+  }
+  const flagged = new Set();
+  for (const c of text.matchAll(/(?:&&|\?|:)\s*\(?\s*(?=<[A-Za-z])/g)) {
+    const start = c.index + c[0].length;
+    const el = elementAt(text, start);
+    for (const s of el.matchAll(/<Sheet\b/g)) {
+      const at = start + s.index;
+      if (flagged.has(at) || /\sonSettled\s*=/.test(tagAt(text, at))) continue;
+      flagged.add(at);
+      add('sheet-unmounted', 'warn', at, `<Sheet> rendered on a condition${s.index ? ' (around its ' + el.match(/^<([\w.]+)/)[1] + ')' : ''} without onSettled: taken out of the tree it vanishes instead of sliding out. Set state="away" and unmount it in onSettled (state === "away") — or keep it mounted and switch its state.`);
+    }
   }
 
   // 3 · the screen: the bar is the Screen's bottom, never after it, never pinned; a sheet finishes on its own foot

package/package.json

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