@usableapp/cardds 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 > 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.3 — 2026-09-24
+
+### New
+- `Modal onDismiss(reason)` — a tap on the scrim (anywhere outside the card) or Esc asks to leave unanswered
+  (`'scrim' | 'escape'`); the app sets `open={false}` and the modal leaves as usual. Without `onDismiss` the scrim does
+  nothing — a question that must be answered.
+
 ## 0.7.2 — 2026-09-24
 
 ### `Banner` is one light band (breaking)

package/dist/sheets/Drawer.d.ts

@@ -5,15 +5,19 @@ export interface ModalProps extends ComponentProps<'article'> {
     open?: boolean;
     /** the leaving has finished (at once, when motion is reduced) — unmount here */
     onClosed?: () => void;
+    /** the member asked to leave WITHOUT answering: a tap on the scrim (anywhere outside the card) or Esc. The modal only asks — the app
+     *  sets `open={false}`. Without it the scrim does nothing (a question that must be answered). */
+    onDismiss?: (reason: 'scrim' | 'escape') => void;
 }
 /**
  * Modal — the ask: ONE card at the centre of a `SheetStage dim`, two parts — a `Lift` (the thing being asked about, light, scrolls
  * when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above, then the drawer comes
  * out below while the lift moves up.
  * 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.
+ * 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).
  */
-export declare function Modal({ open, onClosed, className, ...rest }: ModalProps): import("react").JSX.Element;
+export declare function Modal({ open, onClosed, onDismiss, className, ...rest }: ModalProps): import("react").JSX.Element;
 export interface LiftProps extends ComponentProps<'div'> {
 }
 /** Lift — the light part of a `Modal`: the case, request or item the question is about (a CardHead, rows, a timeline); scrolls inside when tall. */

package/dist/sheets/Drawer.js

@@ -6,9 +6,10 @@ import { cx } from '../cx.js';
  * when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above, then the drawer comes
  * out below while the lift moves up.
  * 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.
+ * 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).
  */
-export function Modal({ open = true, onClosed, className, ...rest }) {
+export function Modal({ open = true, onClosed, onDismiss, className, ...rest }) {
     const ref = useRef(null);
     const closed = useRef(onClosed);
     closed.current = onClosed;
@@ -27,6 +28,21 @@ export function Modal({ open = true, onClosed, className, ...rest }) {
             closed.current?.(); });
         return () => { live = false; };
     }, [open]);
+    const dismiss = useRef(onDismiss);
+    dismiss.current = onDismiss;
+    const has = onDismiss !== undefined;
+    useEffect(() => {
+        const el = ref.current, stage = el?.parentElement;
+        if (!el || !stage || !has || !open)
+            return;
+        const tap = (e) => { if (!el.contains(e.target))
+            dismiss.current?.('scrim'); }; // the scrim is the stage's own ::after
+        const key = (e) => { if (e.key === 'Escape' && !e.defaultPrevented)
+            dismiss.current?.('escape'); };
+        stage.addEventListener('click', tap);
+        document.addEventListener('keydown', key);
+        return () => { stage.removeEventListener('click', tap); document.removeEventListener('keydown', key); };
+    }, [has, open]);
     return _jsx("article", { ref: ref, className: cx('card modal', className), ...rest });
 }
 /** Lift — the light part of a `Modal`: the case, request or item the question is about (a CardHead, rows, a timeline); scrolls inside when tall. */

package/package.json

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