@usableapp/cardds 0.7.83 → 0.7.84

package/dist/post/PostBox.d.ts

@@ -20,7 +20,7 @@ export interface PostBoxCardProps extends Omit<ComponentProps<'li'>, 'id'> {
     from: ReactNode;
     /** where and when — the edge's small line ("เชียงใหม่ · 3 ม.ค. 69") */
     when?: ReactNode;
-    /** the corner's stamp — a `Stamp` */
+    /** the corner's stamp — a `Stamp`, shown at the postcard's own size (72 × 90, `--post-corner-stamp-w`) */
     stamp?: ReactNode;
     /** the mark struck over the stamp — a `Postmark`; behind another card only its place shows */
     postmark?: ReactNode;

package/dist/post/PostDesk.d.ts

@@ -30,9 +30,9 @@ export interface PostDeskProps extends ComponentProps<'div'> {
     placeholder?: string;
     /** the address lines — `PostDeskLine`s; their values are the app's, like any input's */
     address?: ReactNode;
-    /** the sender's own stamps, shown under the card on the address half */
+    /** the sender's own stamps, shown under the card on the address half: each the standard size (96 × 120, `--stamp-size`), in one line that scrolls sideways when they outrun the screen */
     stamps?: PostDeskStamp[];
-    /** CONTROLLED: the `id` of the stamp in the stamp box, `null` = none — with `onStampChange` */
+    /** CONTROLLED: the `id` of the stamp in the stamp box, `null` = none — with `onStampChange`. The box and its stamp are the postcard's own size (72 × 90, `--post-corner-stamp-w`); the empty box shows its word */
     stamp?: string | null;
     /** UNCONTROLLED: the stamp it starts with */
     defaultStamp?: string | null;

package/dist/post/PostLetter.d.ts

@@ -24,7 +24,7 @@ export interface PostLetterProps extends ComponentProps<'div'> {
     kicker?: ReactNode;
     /** the address lines, top down: the first is the name, the rest where they live */
     to?: ReactNode[];
-    /** the corner's stamp — a `Stamp` */
+    /** the corner's stamp — a `Stamp`, shown at the postcard's own size (72 × 90, `--post-corner-stamp-w`) */
     stamp?: ReactNode;
     /** the mark struck over the stamp — a `Postmark` */
     postmark?: ReactNode;

package/dist/post/Postmark.d.ts

@@ -7,6 +7,6 @@ export interface PostmarkProps extends ComponentProps<'div'> {
 }
 /**
  * Postmark — the round mark the post strikes: where and when, two rings, turned a little, its cancel lines running on to the side.
- * On a card's corner (`postmark` of PostLetter · PostDesk · PostBoxCard) it lies over the edge of the stamp. Information: nothing to press.
+ * On a card's corner (`postmark` of PostLetter · PostDesk · PostBoxCard) it lies over the edge of the stamp, by 0.4 of its own size. Information: nothing to press.
  */
 export declare function Postmark({ place, date, className, ...rest }: PostmarkProps): import("react").JSX.Element;

package/dist/post/Postmark.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 /**
  * Postmark — the round mark the post strikes: where and when, two rings, turned a little, its cancel lines running on to the side.
- * On a card's corner (`postmark` of PostLetter · PostDesk · PostBoxCard) it lies over the edge of the stamp. Information: nothing to press.
+ * On a card's corner (`postmark` of PostLetter · PostDesk · PostBoxCard) it lies over the edge of the stamp, by 0.4 of its own size. Information: nothing to press.
  */
 export function Postmark({ place, date, className, ...rest }) {
     return (_jsxs("div", { className: cx('postmark', className), ...rest, children: [_jsx("span", { children: place }), date != null && _jsx("span", { children: date })] }));

package/dist/post/postCorner.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /* the corner of a card that proves the journey: the stamp (a `Stamp`, the app's), the postmark struck over its edge.
-   A part of the three post views, never exported: a stamp here shows its pictures only (stamp.css). */
+   A part of the three post views, never exported: a stamp here is the postcard's own size, `--post-corner-stamp-w` (72 × 90, outside the stamp's two sizes), and shows its pictures only (stamp.css, post.css). */
 export function PostCorner({ stamp, postmark, ...rest }) {
     if (stamp == null && postmark == null)
         return null;

package/dist/scaffold/LayerHistory.d.ts

@@ -41,6 +41,8 @@ export interface LayerApi {
  * `const way = useLayer('way')` → `<CallSheet open={way.value} onOpenChange={(up, i) => (up ? way.open(i!) : way.close())}>`.
  * A Modal: `open={ask.value !== null}` + the app's own `mounted` flag cleared in `onClosed`. Opened again a layer starts anew —
  * give what is inside a new `key` per opening.
+ * ONE LAYER PER TICK: `open` builds the new state from the layers read at render, so two layers opened in the same handler lose the
+ * first — `a.open(1); b.open(2)` gives `a.value` null and `b.value` 2, and two new entries. Open the second in a later tick.
  */
 export declare function useLayer(name: string): LayerApi;
 /** useOptionalLayer — the same layer as `useLayer`, or `null` when no `LayerHistory` is above. A missing provider does not warn. */

package/dist/scaffold/LayerHistory.js

@@ -58,6 +58,8 @@ const layerApi = (name, handle) => {
  * `const way = useLayer('way')` → `<CallSheet open={way.value} onOpenChange={(up, i) => (up ? way.open(i!) : way.close())}>`.
  * A Modal: `open={ask.value !== null}` + the app's own `mounted` flag cleared in `onClosed`. Opened again a layer starts anew —
  * give what is inside a new `key` per opening.
+ * ONE LAYER PER TICK: `open` builds the new state from the layers read at render, so two layers opened in the same handler lose the
+ * first — `a.open(1); b.open(2)` gives `a.value` null and `b.value` 2, and two new entries. Open the second in a later tick.
  */
 export function useLayer(name) {
     const handle = useHistory();

package/dist/sheets/Modal.d.ts

@@ -16,6 +16,9 @@ export interface ModalProps extends ComponentProps<'article'> {
  * A COMPONENT, not a wiring: it does not know its buttons. They are plain `IconBtn`s / `Btn`s with the app's `onClick` — the app
  * records the answer and sets `open={false}`; the modal's one behaviour is how it leaves. `onDismiss` asks to leave unanswered (a tap on
  * the scrim, Esc). When it has arrived, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the question — write no focus code.
+ * MOUNT IT ONLY WHEN IT IS TO SHOW. First mounted with `open={false}` it is drawn in place, then leaves, and calls `onClosed` after about 700ms
+ * (measured at 375, 2026-10-11). KNOWN FAULT, not fixed: under React StrictMode `onClosed` is never called for a Modal mounted that way — the
+ * effect's first run sets `shown` to false, its cleanup drops the wait, and the second run returns early.
  */
 export declare function Modal({ open, onClosed, onDismiss, className, ...rest }: ModalProps): import("react").JSX.Element;
 export interface ModalBodyProps extends ComponentProps<'div'> {

package/dist/sheets/Modal.js

@@ -9,6 +9,9 @@ import { cx } from '../cx.js';
  * A COMPONENT, not a wiring: it does not know its buttons. They are plain `IconBtn`s / `Btn`s with the app's `onClick` — the app
  * records the answer and sets `open={false}`; the modal's one behaviour is how it leaves. `onDismiss` asks to leave unanswered (a tap on
  * the scrim, Esc). When it has arrived, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the question — write no focus code.
+ * MOUNT IT ONLY WHEN IT IS TO SHOW. First mounted with `open={false}` it is drawn in place, then leaves, and calls `onClosed` after about 700ms
+ * (measured at 375, 2026-10-11). KNOWN FAULT, not fixed: under React StrictMode `onClosed` is never called for a Modal mounted that way — the
+ * effect's first run sets `shown` to false, its cleanup drops the wait, and the second run returns early.
  */
 export function Modal({ open = true, onClosed, onDismiss, className, ...rest }) {
     const ref = useRef(null);

package/dist/stamp/Stamp.d.ts

@@ -7,7 +7,7 @@ export interface StampProps extends Omit<ComponentProps<'span'>, 'onClick'> {
     tone?: StickyTone;
     /** the big line at the foot, on the picture — whose stamp it is */
     name?: ReactNode;
-    /** a small line above the name (the pictures' words); it goes when the stamp is tiny */
+    /** a small line above the name (the pictures' words). It shows only on a stamp WIDER than the standard size (`--stamp-size` set above 6rem): at 96 it would be under 5px, so it is not drawn and the name is larger */
     words?: ReactNode;
     /** the pictures alone: `name` and `words` are not drawn. For a stamp stuck on something (a postcard's corner); in a `StampOn` every stamp is bare already. The words are for the album */
     bare?: boolean;
@@ -18,7 +18,8 @@ export interface StampProps extends Omit<ComponentProps<'span'>, 'onClick'> {
 }
 /**
  * Stamp — a perforated paper stamp, 4:5: the pictures fill the inner frame on a tone, the words sit on the picture's foot.
- * It is sized by its column (up to `--stamp-max-w`) and every inner length follows its width, so it reads from a tray to a sheet.
+ * Every stamp is ONE size wherever it stands (`--stamp-size`, two taps wide: 96 × 120) — what holds it only places it; a holder narrower than that shows it whole, smaller.
+ * The one small stamp is a stamp stuck on something (`StampOn`). Every inner length follows the stamp's width.
  * The outer box holds the size and the shadow; the paper inside is the one whose edge is punched (a mask would cut the shadow too).
  */
 export declare function Stamp({ pictures, tone, name, words, bare, tilt, onClick, className, ...rest }: StampProps): import("react").JSX.Element;
@@ -29,7 +30,7 @@ export interface StampPlaceProps extends Omit<ComponentProps<'span'>, 'onClick'>
     onClick?: () => void;
 }
 /**
- * StampPlace — an empty place for a stamp: a 4:5 frame of round dots the size a Stamp would be, a word or an Icon inside.
+ * StampPlace — an empty place for a stamp: a 4:5 frame of round dots the size a Stamp is (`--stamp-size`), a word or an Icon inside.
  * The dots are a stroke, not a border: `--stamp-place-dot` is their width, `--stamp-place-gap` the distance from one centre to the next,
  * and a `--stamp-place-dash` above 0 stretches each dot into a dash.
  */

package/dist/stamp/Stamp.js

@@ -2,7 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 /**
  * Stamp — a perforated paper stamp, 4:5: the pictures fill the inner frame on a tone, the words sit on the picture's foot.
- * It is sized by its column (up to `--stamp-max-w`) and every inner length follows its width, so it reads from a tray to a sheet.
+ * Every stamp is ONE size wherever it stands (`--stamp-size`, two taps wide: 96 × 120) — what holds it only places it; a holder narrower than that shows it whole, smaller.
+ * The one small stamp is a stamp stuck on something (`StampOn`). Every inner length follows the stamp's width.
  * The outer box holds the size and the shadow; the paper inside is the one whose edge is punched (a mask would cut the shadow too).
  */
 export function Stamp({ pictures, tone = 'custard', name, words, bare, tilt, onClick, className, ...rest }) {
@@ -13,7 +14,7 @@ export function Stamp({ pictures, tone = 'custard', name, words, bare, tilt, onC
     return (_jsx(Box, { className: cx('stamp', `stamp--${shown.length}`, bare && 'stamp--bare', tilt && `stamp--tilt-${tilt}`, tap && 'stamp--tap', className), ...boxProps, children: _jsx("span", { className: "stamp__paper", children: _jsxs("span", { className: cx('stamp__pic', `sticky--${tone}`), children: [shown.map((picture, i) => _jsx("span", { className: "stamp__art", "aria-hidden": "true", children: picture }, i)), (name != null || words != null) && (_jsxs("span", { className: "stamp__cap", children: [words != null && _jsx("span", { className: "stamp__words", children: words }), name != null && _jsx("span", { className: "stamp__name", children: name })] }))] }) }) }));
 }
 /**
- * StampPlace — an empty place for a stamp: a 4:5 frame of round dots the size a Stamp would be, a word or an Icon inside.
+ * StampPlace — an empty place for a stamp: a 4:5 frame of round dots the size a Stamp is (`--stamp-size`), a word or an Icon inside.
  * The dots are a stroke, not a border: `--stamp-place-dot` is their width, `--stamp-place-gap` the distance from one centre to the next,
  * and a `--stamp-place-dash` above 0 stretches each dot into a dash.
  */

package/dist/stamp/StampBook.d.ts

@@ -2,12 +2,12 @@ import { type ComponentProps, type ReactNode } from 'react';
 export interface StampBookProps extends ComponentProps<'div'> {
     /** how many places the page shows: the ones no StampCell fills are drawn empty */
     places?: number;
-    /** ONE line of small stamps that scrolls sideways, no ground — the tray a member picks from */
+    /** ONE line of stamps that scrolls sideways, no ground — the tray a member picks from. Each stamp is its own size, as everywhere */
     strip?: boolean;
-    /** the page with NO ground — no fill, no padding, no round: three stamps across fill the whole width of what holds the book, each the full width of its third (the Stamp's width cap is lifted) with the least gap that keeps them apart. Put the name INSIDE the stamp (`Stamp name`), not under it */
+    /** the page with NO ground — no fill, no padding, no round: the stamps lie on what holds the book, three across, each its own size in the middle of its third. Put the name INSIDE the stamp (`Stamp name`), not under it */
     bare?: boolean;
 }
-/** StampBook — the album page: StampCells three across on an album ground, the free places drawn empty up to `places`. */
+/** StampBook — the album page: StampCells three across on an album ground, the free places drawn empty up to `places`. The book places its stamps and never sizes them: each is the one size of a stamp, in the middle of its third. */
 export declare function StampBook({ places, strip, bare, className, children, ...rest }: StampBookProps): import("react").JSX.Element;
 export interface StampCellProps extends Omit<ComponentProps<'span'>, 'onClick'> {
     /** a short line under the stamp — who it is from */

package/dist/stamp/StampBook.js

@@ -3,7 +3,7 @@ import { Children } from 'react';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
 import { StampPlace } from './Stamp.js';
-/** StampBook — the album page: StampCells three across on an album ground, the free places drawn empty up to `places`. */
+/** StampBook — the album page: StampCells three across on an album ground, the free places drawn empty up to `places`. The book places its stamps and never sizes them: each is the one size of a stamp, in the middle of its third. */
 export function StampBook({ places = 0, strip, bare, className, children, ...rest }) {
     const free = Math.max(0, places - Children.toArray(children).length); // toArray drops null / undefined / booleans: `{owned && <StampCell/>}` that is false holds no place (Children.count counts it)
     return (_jsxs("div", { className: cx('stamp-book', strip && 'stamp-book--strip', bare && 'stamp-book--bare', className), ...rest, children: [children, Array.from({ length: free }, (_, i) => _jsx(StampPlace, { faint: true, "aria-hidden": "true" }, i))] }));

package/dist/stamp/StampOn.d.ts

@@ -19,6 +19,7 @@ export interface StampOnProps extends ComponentProps<'div'> {
 /**
  * StampOn — a Stamp (the child) stuck on a surface at the place the member chose. The surface is the nearest positioned box:
  * a Sticky's `stuck`, a postcard's face. `at` is the stamp's middle as a share of that surface, so the note reads the same at any size.
+ * The stamp is the SMALL size: 48 × 60 on any surface, whatever the surface's size (`--stamp-sm-size`, one tap wide).
  * With `onAtChange` the member drags it (finger or mouse; the arrow keys move it too): while the finger holds, the stamp writes its
  * own place, and on letting go it ASKS — the app owns `at`. It never leaves the surface.
  */

package/dist/stamp/StampOn.js

@@ -19,6 +19,7 @@ const write = (el, at) => { el.style.setProperty('--stamp-on-x', String(at.x));
 /**
  * StampOn — a Stamp (the child) stuck on a surface at the place the member chose. The surface is the nearest positioned box:
  * a Sticky's `stuck`, a postcard's face. `at` is the stamp's middle as a share of that surface, so the note reads the same at any size.
+ * The stamp is the SMALL size: 48 × 60 on any surface, whatever the surface's size (`--stamp-sm-size`, one tap wide).
  * With `onAtChange` the member drags it (finger or mouse; the arrow keys move it too): while the finger holds, the stamp writes its
  * own place, and on letting go it ASKS — the app owns `at`. It never leaves the surface.
  */

package/package.json

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