@usableapp/cardds 0.7.99 → 0.7.101

package/dist/post/PostDesk.d.ts

@@ -53,7 +53,8 @@ export interface PostDeskProps extends ComponentProps<'div'> {
 }
 /**
  * PostDesk — a postcard being WRITTEN, stamped and sent. The paper is landscape and twice the screen; the phone looks at one half:
- * the message on ruled lines (typing stops when the half is full — the paper is the limit), then the address with the stamp box.
+ * the message on ruled lines (typing stops when the half is full — the paper is the limit: an addition that would not fit is refused
+ * where it was typed, the caret stays, the app's `onMessageChange` never hears it and `onFull` is called; the same rule as a `StickyField` on a `Sticky`), then the address with the stamp box.
  * The other half's showing edge, or a sideways drag, slides the paper. The stamp box and the stamps under the card choose one of
  * the sender's own stamps. Sending is the SCREEN's button, never the desk's: the app sets `state="struck"` — the postmark lands,
  * the desk asks for `sent`, and the card leaves upward; `sent` stands in its place. Every state is the app's (`x` + `onXChange`, or `defaultX`).

package/dist/post/PostDesk.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef } from 'react';
 import { cx } from '../cx.js';
 import { reducedMotion, useControlled, useLatest, watchSize } from '../state.js';
+import { holdRoom } from '../room.js';
 import { word } from '../words.js';
 import { StampPlace } from '../stamp/Stamp.js';
 const STRIKE = 700; // ms the struck card is seen before it asks to leave
@@ -20,7 +21,8 @@ function linesOf(ta) {
 }
 /**
  * PostDesk — a postcard being WRITTEN, stamped and sent. The paper is landscape and twice the screen; the phone looks at one half:
- * the message on ruled lines (typing stops when the half is full — the paper is the limit), then the address with the stamp box.
+ * the message on ruled lines (typing stops when the half is full — the paper is the limit: an addition that would not fit is refused
+ * where it was typed, the caret stays, the app's `onMessageChange` never hears it and `onFull` is called; the same rule as a `StickyField` on a `Sticky`), then the address with the stamp box.
  * The other half's showing edge, or a sideways drag, slides the paper. The stamp box and the stamps under the card choose one of
  * the sender's own stamps. Sending is the SCREEN's button, never the desk's: the app sets `state="struck"` — the postmark lands,
  * the desk asks for `sent`, and the card leaves upward; `sent` stands in its place. Every state is the app's (`x` + `onXChange`, or `defaultX`).
@@ -46,10 +48,15 @@ export function PostDesk({ half, defaultHalf = 'message', onHalfChange, message,
         told.current = `${left}/${fits}`;
         lines.current?.(left, fits);
     };
-    useLayoutEffect(measure, [text]);
+    const full = useLatest(onFull);
+    const room = useRef(null);
+    useLayoutEffect(() => { measure(); room.current?.sync(); }, [text]);
     useEffect(() => {
+        const ta = paper.current;
+        room.current = holdRoom(ta.parentElement, () => paper.current, () => ta.scrollHeight > ta.clientHeight + 1, (refused) => refused && full.current?.());
         document.fonts?.ready.then(measure);
-        return watchSize([paper.current], measure);
+        const stop = watchSize([ta], measure);
+        return () => { room.current?.stop(); room.current = null; stop(); };
     }, []);
     useEffect(() => {
         if (at !== 'struck')
@@ -57,15 +64,6 @@ export function PostDesk({ half, defaultHalf = 'message', onHalfChange, message,
         const t = setTimeout(() => askState('sent'), reducedMotion() ? 0 : STRIKE);
         return () => clearTimeout(t);
     }, [at, askState]);
-    const write = (e) => {
-        const ta = e.currentTarget;
-        if (ta.scrollHeight > ta.clientHeight + 1 && ta.value.length >= text.length) {
-            ta.value = text;
-            onFull?.();
-            return;
-        } // taking words away is never refused
-        askText(ta.value);
-    };
     const from = useRef(null);
     const drop = (e) => {
         const dx = from.current == null ? 0 : e.clientX - from.current;
@@ -73,7 +71,7 @@ export function PostDesk({ half, defaultHalf = 'message', onHalfChange, message,
         if (writing && Math.abs(dx) >= SWIPE)
             askSide(dx < 0 ? 'address' : 'message');
     };
-    return (_jsxs("div", { className: cx('post-desk', `post-desk--${side}`, `post-desk--${at}`, className), ...rest, children: [_jsxs("div", { className: "post-desk__window", onPointerDown: (e) => { from.current = e.clientX; }, onPointerUp: drop, children: [_jsxs("div", { className: "post-desk__card post-paper", children: [_jsx("section", { className: "post-desk__half post-desk__half--message", "aria-label": word('message'), inert: !writing || side !== 'message', children: _jsx("textarea", { ref: paper, className: "post-desk__write", "aria-label": word('message'), placeholder: placeholder, value: text, onChange: write }) }), _jsxs("section", { className: "post-desk__half post-desk__half--address", "aria-label": word('address'), inert: !writing || side !== 'address', children: [_jsx("div", { className: "post-desk__corner", children: _jsxs("div", { className: "post-corner", children: [!writing && postmark, _jsx("button", { className: "post-corner__stamp post-desk__slot", type: "button", "aria-pressed": chosen != null, "aria-label": word(chosen ? 'stampOff' : 'stampOn'), onClick: () => askStamp(chosen ? null : stamps[0]?.id ?? null), children: chosen ? chosen.stamp : _jsx(StampPlace, { "aria-hidden": "true", children: word('stampOn') }) })] }) }), _jsx("div", { className: "post-desk__lines", children: address })] })] }), writing && _jsx("button", { className: `post-desk__reach post-desk__reach--${side === 'message' ? 'address' : 'message'}`, type: "button", "aria-label": word(side === 'message' ? 'toAddress' : 'toMessage'), onClick: () => askSide(side === 'message' ? 'address' : 'message') }), at === 'sent' && _jsx("div", { className: "post-desk__gone", children: sent })] }), _jsx("p", { className: "post-desk__note", "aria-live": "polite", children: note }), writing && side === 'address' && stamps.length > 0 && (_jsx("div", { className: "post-desk__stamps", role: "group", "aria-label": word('stamps'), children: stamps.map((s) => (_jsx("button", { className: "post-desk__pick", type: "button", "aria-pressed": s.id === stuck, "aria-label": s.label, onClick: () => askStamp(s.id), children: s.stamp }, s.id))) }))] }));
+    return (_jsxs("div", { className: cx('post-desk', `post-desk--${side}`, `post-desk--${at}`, className), ...rest, children: [_jsxs("div", { className: "post-desk__window", onPointerDown: (e) => { from.current = e.clientX; }, onPointerUp: drop, children: [_jsxs("div", { className: "post-desk__card post-paper", children: [_jsx("section", { className: "post-desk__half post-desk__half--message", "aria-label": word('message'), inert: !writing || side !== 'message', children: _jsx("textarea", { ref: paper, className: "post-desk__write", "aria-label": word('message'), placeholder: placeholder, value: text, onChange: (e) => askText(e.currentTarget.value) }) }), _jsxs("section", { className: "post-desk__half post-desk__half--address", "aria-label": word('address'), inert: !writing || side !== 'address', children: [_jsx("div", { className: "post-desk__corner", children: _jsxs("div", { className: "post-corner", children: [!writing && postmark, _jsx("button", { className: "post-corner__stamp post-desk__slot", type: "button", "aria-pressed": chosen != null, "aria-label": word(chosen ? 'stampOff' : 'stampOn'), onClick: () => askStamp(chosen ? null : stamps[0]?.id ?? null), children: chosen ? chosen.stamp : _jsx(StampPlace, { "aria-hidden": "true", children: word('stampOn') }) })] }) }), _jsx("div", { className: "post-desk__lines", children: address })] })] }), writing && _jsx("button", { className: `post-desk__reach post-desk__reach--${side === 'message' ? 'address' : 'message'}`, type: "button", "aria-label": word(side === 'message' ? 'toAddress' : 'toMessage'), onClick: () => askSide(side === 'message' ? 'address' : 'message') }), at === 'sent' && _jsx("div", { className: "post-desk__gone", children: sent })] }), _jsx("p", { className: "post-desk__note", "aria-live": "polite", children: note }), writing && side === 'address' && stamps.length > 0 && (_jsx("div", { className: "post-desk__stamps", role: "group", "aria-label": word('stamps'), children: stamps.map((s) => (_jsx("button", { className: "post-desk__pick", type: "button", "aria-pressed": s.id === stuck, "aria-label": s.label, onClick: () => askStamp(s.id), children: s.stamp }, s.id))) }))] }));
 }
 /** PostDeskLine — one address line of a PostDesk (`address`): a small word and a bare input on a rule. The value is the app's, like any input's. */
 export function PostDeskLine({ label, type = 'text', autoComplete = 'off', className, ...rest }) {

package/dist/room.d.ts

@@ -0,0 +1,12 @@
+/** A field that stops at its paper's room. An input that adds to the field's words while `over()` says they no longer fit is refused:
+ *  the words go back to what they were, the caret stays where it was, and the app's `onChange` never hears it. Taking words away is
+ *  never refused. `after(refused)` runs after every input on the paper, refused or not, so the holder can measure again.
+ *  The listeners sit on `paper`, an element round the field: a native listener there runs before React's own at the root, so stopping
+ *  the event keeps `onChange` from hearing it. A composition (Thai, Japanese) has reached the app already when it ends, so its words
+ *  are put back through the prototype's setter and an input is sent, which tells the app they went back.
+ *  Call `sync()` after the app sets the field's value itself (a cleared field after send); `stop()` takes the listeners off. */
+export interface Room {
+    sync(): void;
+    stop(): void;
+}
+export declare function holdRoom(paper: HTMLElement, fieldOf: () => HTMLTextAreaElement | null, over: () => boolean, after?: (refused: boolean) => void): Room;

package/dist/room.js

@@ -0,0 +1,38 @@
+export function holdRoom(paper, fieldOf, over, after = () => { }) {
+    let last = fieldOf()?.value ?? '', composing = false;
+    const refuse = (field, dropped) => {
+        const added = field.value.length - last.length, at = field.selectionStart - added;
+        if (dropped)
+            Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value').set.call(field, last);
+        else
+            field.value = last; // the prototype's setter, so React's value tracker sees the change and the input dispatched next reaches onChange
+        field.setSelectionRange(Math.max(0, at), Math.max(0, at));
+        if (dropped)
+            field.dispatchEvent(new Event('input', { bubbles: true }));
+    };
+    const check = (e, dropped) => {
+        const field = fieldOf();
+        if (!field || e.target !== field)
+            return after(false);
+        const refused = field.value.length >= last.length && over();
+        if (refused) {
+            if (!dropped)
+                e.stopPropagation();
+            refuse(field, dropped);
+        }
+        else
+            last = field.value;
+        after(refused);
+    };
+    const onInput = (e) => (e.isComposing ? after(false) : check(e, false));
+    const onComposing = () => { composing = true; };
+    const onComposed = (e) => { composing = false; check(e, true); };
+    paper.addEventListener('input', onInput);
+    paper.addEventListener('compositionstart', onComposing);
+    paper.addEventListener('compositionend', onComposed);
+    return {
+        sync() { const field = fieldOf(); if (field && !composing)
+            last = field.value; },
+        stop() { paper.removeEventListener('input', onInput); paper.removeEventListener('compositionstart', onComposing); paper.removeEventListener('compositionend', onComposed); },
+    };
+}

package/dist/sticky/Sticky.js

@@ -4,6 +4,7 @@ import { cx } from '../cx.js';
 import { pressable } from '../pressable.js';
 import { setRefs, watchSize } from '../state.js';
 import { word } from '../words.js';
+import { holdRoom } from '../room.js';
 import { fitSticky } from './fit.js';
 /**
  * Sticky — a paper note: a flat pastel SQUARE of one size (168, the knob `--sticky-size`), square corners, a soft shadow under it.
@@ -16,59 +17,25 @@ import { fitSticky } from './fit.js';
 export function Sticky({ tone = 'custard', flat, unreadLabel, head, date, tilt, foot, corner, stuck, onClick, className, children, ref, ...rest }) {
     const own = useRef(null);
     const [small, setSmall] = useState(false);
-    const last = useRef('');
-    const composing = useRef(false);
+    const room = useRef(null);
     const fieldOf = () => own.current?.querySelector('.sticky-field') ?? null;
     useLayoutEffect(() => {
         const note = own.current;
         if (!note)
             return;
         setSmall(fitSticky(note) !== 'full');
-        const field = fieldOf();
-        if (field && !composing.current)
-            last.current = field.value;
+        room.current?.sync();
     }, [children, head, date, foot]); // a chat re-renders every note on each keystroke in its answer field; only a note whose words changed is measured again (a field is an element, new every render)
     useEffect(() => {
         const note = own.current, paper = note?.querySelector('.sticky__paper');
         if (!note || !paper)
             return;
         const measure = () => setSmall(fitSticky(note) !== 'full');
-        /* A native listener on the paper runs before React's own at the root, so stopping the event here keeps the app's `onChange` from
-           hearing an input the note refused. `dropped` is for a composition: the app has heard it already, so it is told the words went back. */
-        const refuse = (field, dropped) => {
-            const added = field.value.length - last.current.length, at = field.selectionStart - added;
-            if (dropped)
-                Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value').set.call(field, last.current);
-            else
-                field.value = last.current; // the prototype's setter, so React's value tracker sees the change and the input dispatched next reaches onChange
-            field.setSelectionRange(Math.max(0, at), Math.max(0, at));
-            if (dropped)
-                field.dispatchEvent(new Event('input', { bubbles: true }));
-        };
-        const check = (e, dropped) => {
-            const field = fieldOf();
-            if (!field || e.target !== field)
-                return measure();
-            if (fitSticky(note) === 'over' && field.value.length > last.current.length) {
-                if (!dropped)
-                    e.stopPropagation();
-                refuse(field, dropped);
-                fitSticky(note);
-            }
-            else
-                last.current = field.value;
-            measure();
-        };
-        const onInput = (e) => (e.isComposing ? measure() : check(e, false));
-        const onComposing = () => { composing.current = true; };
-        const onComposed = (e) => { composing.current = false; check(e, true); };
-        paper.addEventListener('input', onInput);
-        paper.addEventListener('compositionstart', onComposing);
-        paper.addEventListener('compositionend', onComposed);
+        room.current = holdRoom(paper, fieldOf, () => fitSticky(note) === 'over', measure);
         const body = paper.querySelector('.sticky__body');
         const stop = watchSize([body], measure);
         document.fonts?.ready.then(measure);
-        return () => { paper.removeEventListener('input', onInput); paper.removeEventListener('compositionstart', onComposing); paper.removeEventListener('compositionend', onComposed); stop(); };
+        return () => { room.current?.stop(); room.current = null; stop(); };
     }, []);
     const notched = corner != null;
     const { tap, Box, boxProps } = pressable(notched ? undefined : onClick, 'div', rest);

package/lint/rules.mjs

@@ -12,7 +12,7 @@ const CSS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'css');
 /** the props whose default is cardds's own word (src/words.ts), per component — a `label` that is a control's required accessible name (IconBtn, Fab, Pin…) is not here */
 export const CONTROL_NAMES = {
   Sheet: ['handle'], CallSheet: ['handle'], StackSheet: ['backLabel'], Home: ['backLabel'], Walkthrough: ['backLabel', 'nextLabel'],
-  Calendar: ['prevLabel', 'nextLabel'], SheetStep: ['skipLabel'], Sticky: ['unreadLabel'], StampOn: ['removeLabel'], PostLetter: ['backLabel', 'pictureLabel', 'playLabel', 'pauseLabel', 'toLabel'],
+  Calendar: ['prevLabel', 'nextLabel'], SheetStep: ['skipLabel'], Sticky: ['unreadLabel'], StampOn: ['removeLabel'], Card: ['removeLabel'], PostLetter: ['backLabel', 'pictureLabel', 'playLabel', 'pauseLabel', 'toLabel'],
 };
 
 const lineOf = (text, idx) => text.slice(0, idx).split('\n').length;
@@ -119,7 +119,8 @@ function* styleEntries(body, at, sep) {
 export function checkSource(source, file, { classes = carddsClasses() } = {}) {
   const findings = [];
   const lines = source.split('\n');
-  let text = source.replace(/\/\*[\s\S]*?\*\/|(?<![:'"`\\])\/\/[^\n]*/g, (c) => c.replace(/[^\n]/g, ' ')); // comments out, lines kept
+  // comments out, lines kept; a string is stepped over whole, so `accept="image/*"` opens no comment
+  let text = source.replace(/"[^"\n]*"|'[^'\n]*'|`[^`]*`|\/\*[\s\S]*?\*\/|(?<![:'"`\\])\/\/[^\n]*/g, (c) => /^["'`]/.test(c) ? c : c.replace(/[^\n]/g, ' '));
   const add = (rule, level, idx, message) => {
     const line = lineOf(text, idx);
     if (!/cardds-ignore-next-line/.test(lines[line - 2] ?? '')) findings.push({ rule, level, file, line, message }); // `// cardds-ignore-next-line` — a deliberate case (a story that shows the wrong way)
@@ -229,25 +230,38 @@ export function checkSource(source, file, { classes = carddsClasses() } = {}) {
 
   // 10 · the sheet is the paper the member fills in (Lh 2026-10-18): every control the member fills or picks stands on a Sheet's body, a SheetStep
   //      or a stack sheet; a card is for reading and pressing buttons. A Card that is a sheet of a SheetStack IS a sheet (the stack's material)
-  const span = (re) => [...text.matchAll(re)].map((m) => ({ at: m.index, body: m.index + tagAt(text, m.index).length, end: m.index + elementAt(text, m.index).length }));
+  // a `<` right after a name is a type argument (`Record<Step, string>`, `useState<Step>`), not a tag; an element that never closes holds nothing
+  const span = (re) => [...text.matchAll(re)].filter((m) => !/[\w$)\].]/.test(text[m.index - 1] ?? '')).map((m) => {
+    const open = tagAt(text, m.index), el = elementAt(text, m.index), closed = open.endsWith('/>') || el.endsWith(`</${m[0].slice(1).match(/^[\w.]+/)[0]}>`);
+    return { at: m.index, body: m.index + open.length, end: m.index + (closed ? el : open).length };
+  });
   const stacks = span(/<SheetStack\b(?![\w.])/g), cards = span(/<Card\b(?![\w.])/g);
   const within = (at, el) => at > el.at && at < el.end;
   const innermost = (at) => cards.filter((c) => within(at, c)).at(-1);
   // a form is never on the ground (Lh 2026-10-18, timebank's ask steps on a bare Page): the control's nearest container written in this file decides.
   // None in the file (a step component's fragment) is not judged here — the file that places it is
   const places = [
-    ...span(/<(?:Sheet|SheetBody|SheetStep|StackSheet|SheetStack)\b(?![\w.])/g).map((p) => ({ ...p, ground: false })),
+    ...span(/<(?:Sheet|SheetBody|SheetStep|StackSheet|SheetStack|CallSheet|Modal|ModalAsk)\b(?![\w.])/g).map((p) => ({ ...p, ground: false })), // a modal is a surface over the screen too
     ...span(/<(?:ActionBarTier|FilterRow|TopBar|AppBar)\b(?![\w.])/g).map((p) => ({ ...p, ground: false })), // a bar's control: a Slider in a control tier, a Dropdown in a filter row or a top bar's actions, a Toggle in an app bar
     ...span(/<(?:Page|Pages|Step|Screen)\b(?![\w.])/g).map((p) => ({ ...p, ground: true })),
     ...cards.map((p) => ({ ...p, ground: false })), // a card round it is field-in-card's finding
   ].sort((a, b) => a.at - b.at);
-  const onGround = (at) => places.filter((p) => within(at, p)).at(-1)?.ground;
+  // true on a sheet, false on the ground, null when this file cannot tell. A component of this file is where it is placed: the ask steps' <Page>,
+  // in a function rendered inside a <SheetBody> further up the file, slides inside that sheet
+  const componentAt = (at) => [...text.slice(0, at).matchAll(/(?:function\s+|const\s+)([A-Z]\w*)/g)].at(-1)?.[1];
+  const onSheet = (at, depth = 0) => {
+    const place = places.filter((p) => within(at, p)).at(-1);
+    if (place && !place.ground) return true;
+    const name = depth < 5 && componentAt(at);
+    if (name) for (const u of text.matchAll(new RegExp(`(?<![\\w$)\\].])<${name}\\b(?![\\w.])`, 'g'))) if (onSheet(u.index, depth + 1)) return true;
+    return place ? false : null;
+  };
   for (const c of text.matchAll(/<(Field|Composer|ComposerArea|Pin|Dropdown|Slider|Toggle|Check|ChipPick|Calendar|DayStrip|Day|Picker|Mood|AvatarPick|FileBtn|AddRow|MapPick|Tile)\b(?![\w.])/g)) {
     const kind = c[1] === 'Tile' ? tagAt(text, c.index).match(/\s(pick|upload)\b(?!\s*=\s*\{\s*false)/)?.[1] : null;
     if (c[1] === 'Tile' && !kind) continue; // a plain or stat Tile is read, not filled
     const card = innermost(c.index);
     if (!card) {
-      if (onGround(c.index)) add('field-off-sheet', 'error', c.index, `<${kind ? `Tile ${kind}` : c[1]}> on the ground: a form is never on the ground, it sits only on a sheet (Lh 2026-10-18). A Page, Pages, Step or Screen is the base, not a sheet. Put the control on a Sheet's <SheetBody>, in a <SheetStep>, or on a stack sheet — a form over a screen is a <Sheet> in a <SheetStage over dim> (Home/AskSheet).`);
+      if (onSheet(c.index) === false) add('field-off-sheet', 'error', c.index, `<${kind ? `Tile ${kind}` : c[1]}> on the ground: a form is never on the ground, it sits only on a sheet (Lh 2026-10-18). A Page, Pages, Step or Screen is the base, not a sheet. Put the control on a Sheet's <SheetBody>, in a <SheetStep>, or on a stack sheet — a form over a screen is a <Sheet> in a <SheetStage over dim> (Home/AskSheet).`);
       continue;
     }
     const stack = stacks.filter((s) => card.at >= s.body && card.at < s.end).at(-1);

package/package.json

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