@usableapp/cardds 0.7.101 → 0.7.102

package/dist/cards/Card.d.ts

@@ -2,13 +2,17 @@ import { type ComponentProps, type MouseEvent, type ReactNode } from 'react';
 import { type CardHeadProps } from './CardHead.js';
 import { type StackPlace } from '../sheets/stackCard.js';
 export type { StackPlace };
+/** which side of a two-faced card shows */
+export type CardFace = 'front' | 'back';
 /** a card's paper: 1 (default, light) · 2 (tinted) · 3 (dark / accent — controls invert) · 4 · 5 (more colours, from the palette) */
 export type Tone = 1 | 2 | 3 | 4 | 5;
 export interface CardProps extends ComponentProps<'article'> {
     /** the tone slot — see `Tone` */
     tone?: Tone;
-    /** the content is white paper and the head keeps the card's colour. The same look as `Sheet paper`. Omit it and the content matches the head */
-    paper?: boolean;
+    /** `true`: the content is white paper and the head keeps the card's colour (the look of `Sheet paper`). `'bands'`: the opposite, two-tone —
+     *  the head and the foot are white paper bands edge to edge, the middle between them keeps the card's tone, lightened (knob `--card-middle-bg`).
+     *  Omit it and the content matches the head */
+    paper?: boolean | 'bands';
     /** compact: a small card inside a card or a sheet body (a note, a promo) */
     sm?: boolean;
     /** a list row that is its own card: thumb · body · end, in a CardList. Its corner is the big card's PROPORTION, not its size (`--r-card-row`, 13; knob `--card-row-radius`).
@@ -53,6 +57,22 @@ export interface CardProps extends ComponentProps<'article'> {
      *  things; its touch target stays 44). A touch on it calls this and never picks the row. The app takes the row out of its own list. Knobs
      *  `--card-remove-size` · `--card-remove-inset` · `--card-remove-ink` · `--card-remove-bg` */
     onRemove?: () => void;
+    /** THE BACK — the card has two faces and the member turns the WHOLE card over: a tap anywhere on it that is not on a control asks for the other
+     *  face. The head and the foot (`heading`/`caption`/`end` or a CardHead child, `foot`) are given once and drawn on BOTH faces, so they read the same
+     *  either way; the children are the front's middle, `back` the back's. The middle is one fixed height on both faces (knob `--card-middle-h`), so the
+     *  card never changes height when it turns. The hidden face is `inert`; an `id` in the head or the foot would be drawn twice, so give it none.
+     *  Not on a `row`, `sm` or `stack` card */
+    back?: ReactNode;
+    /** CONTROLLED: the face that shows — pair it with `onFaceChange`. The app owns it */
+    face?: CardFace;
+    /** UNCONTROLLED: the face it starts on (default `'front'`) */
+    defaultFace?: CardFace;
+    /** a tap asked for the other face */
+    onFaceChange?: (face: CardFace) => void;
+    /** the spoken name of the front's hidden turn-over button (default: the words' `turnToBack`) */
+    toBackLabel?: string;
+    /** the spoken name of the back's hidden turn-over button (default: the words' `turnToFront`) */
+    toFrontLabel?: string;
     /** the cross's spoken name (default: the words' `remove`) — name what goes: "Remove 'buy medicine'" */
     removeLabel?: string;
 }
@@ -64,8 +84,10 @@ export interface CardProps extends ComponentProps<'article'> {
  * A page with one feature and one CTA may be a single card. Keep everything big.
  * PRESSED WHOLE: a card whose ONLY control is its foot's button, or a row card's end button, is pressed anywhere — a touch off the
  * button runs that button's own action once, and the card dims under the finger. The app writes nothing; any other card is only read.
+ * TWO FACES (`back`): the whole card turns over on a tap off a control (the flip mechanic it shares with Postcard); the head and the foot
+ * read the same on both faces, the middle is one fixed height. `paper="bands"`: white head and foot bands edge to edge, the tint between.
  */
-export declare function Card({ tone, paper, sm, row, cover, fold, centre, band, as, heading, caption, end, level, foot, footLink, stack, leave, onLeft, onRemove, removeLabel, className, style, children, onClick, ref, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
+export declare function Card({ tone, paper, sm, row, cover, fold, centre, band, as, heading, caption, end, level, foot, footLink, stack, leave, onLeft, onRemove, removeLabel, back, face, defaultFace, onFaceChange, toBackLabel, toFrontLabel, className, style, children, onClick, ref, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
     onClick: (e: MouseEvent<HTMLElement>) => void;
     inert?: boolean | undefined;
     "aria-busy"?: (boolean | "true" | "false") | undefined;

package/dist/cards/Card.js

@@ -1,10 +1,10 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Children, createElement, isValidElement, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
-import { useLatest, warnOnce } from '../state.js';
+import { useControlled, useLatest, warnOnce } from '../state.js';
 import { CardHead } from './CardHead.js';
 import { CardFoot } from './CardFoot.js';
-import { goControl } from './cardGo.js';
+import { goControl, onControl } from './cardGo.js';
 import { Icon } from '../type/Icon.js';
 import { word } from '../words.js';
 import { StackHeadCtx, StackPullCtx, ownHead, stackPaint, useStackCard } from '../sheets/stackCard.js';
@@ -16,10 +16,17 @@ import { StackHeadCtx, StackPullCtx, ownHead, stackPaint, useStackCard } from '.
  * A page with one feature and one CTA may be a single card. Keep everything big.
  * PRESSED WHOLE: a card whose ONLY control is its foot's button, or a row card's end button, is pressed anywhere — a touch off the
  * button runs that button's own action once, and the card dims under the finger. The app writes nothing; any other card is only read.
+ * TWO FACES (`back`): the whole card turns over on a tap off a control (the flip mechanic it shares with Postcard); the head and the foot
+ * read the same on both faces, the middle is one fixed height. `paper="bands"`: white head and foot bands edge to edge, the tint between.
  */
-export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, stack, leave, onLeft, onRemove, removeLabel, className, style, children, onClick, ref, ...rest }) {
+export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, stack, leave, onLeft, onRemove, removeLabel, back, face, defaultFace = 'front', onFaceChange, toBackLabel, toFrontLabel, className, style, children, onClick, ref, ...rest }) {
     if (onRemove && !row)
         warnOnce('card-remove-row', 'cardds Card: `onRemove` draws its cross on a `row` card only');
+    if (back != null && (row || sm || stack))
+        warnOnce('card-back-kind', 'cardds Card: `back` turns a whole card — not a `row`, `sm` or `stack` card; the back is ignored');
+    const turns = back != null && !row && !sm && !stack;
+    const [shown, ask] = useControlled(face, defaultFace, onFaceChange);
+    const flipped = turns && shown === 'back';
     const head = heading != null || caption != null || end != null;
     const tail = foot != null || footLink != null;
     if (head || tail) {
@@ -55,7 +62,7 @@ export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'ar
         return () => { live = false; };
     }, [away]);
     const [go, setGo] = useState(false);
-    useLayoutEffect(() => { setGo(own.current != null && goControl(own.current) != null); }); // every render: what the card holds is its children's
+    useLayoutEffect(() => { setGo(!turns && own.current != null && goControl(own.current) != null); }); // every render: what the card holds is its children's
     const pressing = useRef(false);
     const click = (e) => {
         if (pressing.current)
@@ -63,6 +70,11 @@ export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'ar
         onClick?.(e);
         const target = e.target;
         const card = own.current;
+        if (turns) {
+            if (!e.defaultPrevented && card && !onControl(card, target))
+                ask(flipped ? 'front' : 'back');
+            return;
+        }
         if (!e.defaultPrevented && card?.contains(target)) {
             const control = goControl(card);
             if (control && !control.contains(target)) {
@@ -94,13 +106,21 @@ export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'ar
     const props = {
         ...rest,
         ref: setRef,
-        className: cx('card', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', go && 'card--go', leaver && 'card--leaver', away && 'card--away', painted.className, className),
+        className: cx('card', tone && tone !== 1 && `card--${tone}`, paper === true && 'sheet--paper', paper === 'bands' && 'card--bands', turns && 'card--turns flip', flipped && 'is-flipped', sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', go && 'card--go', leaver && 'card--leaver', away && 'card--away', painted.className, className),
         style: painted.style || style ? { ...painted.style, ...style } : undefined,
         ...(stack ? { 'aria-busy': painted.busy } : {}),
         ...(away ? { inert: true } : {}),
         onClick: click,
     };
     const cross = row && onRemove ? (_jsx("button", { type: "button", className: "card__remove", "aria-label": removeLabel ?? word('remove'), onClick: (e) => { e.preventDefault(); e.stopPropagation(); onRemove(); }, children: _jsx(Icon, { name: "x" }) }, "remove")) : null;
+    if (turns) {
+        const kids = Children.toArray(children);
+        const ownHeadKid = kids.find((c) => isValidElement(c) && c.type === CardHead);
+        const ownFootKid = kids.find((c) => isValidElement(c) && c.type === CardFoot);
+        const front = kids.filter((c) => c !== ownHeadKid && c !== ownFootKid);
+        const side = (which, middle) => (_jsxs("div", { className: cx('card__face flip__face', `flip__face--${which}`), ...((which === 'back') !== flipped ? { inert: true } : {}), children: [_jsx("button", { type: "button", className: "card__turn", "aria-label": which === 'front' ? toBackLabel ?? word('turnToBack') : toFrontLabel ?? word('turnToFront'), onClick: () => ask(which === 'front' ? 'back' : 'front') }), head ? _jsx(CardHead, { heading: heading, caption: caption, end: end, level: level }) : ownHeadKid, _jsx("div", { className: "card__middle", children: which === 'front' ? front : middle }), tail ? _jsx(CardFoot, { link: footLink, children: foot }) : ownFootKid] }, which));
+        return createElement(as, props, inner(_jsxs(_Fragment, { children: [side('front', null), side('back', back)] })));
+    }
     if (!head && !tail)
         return createElement(as, props, inner(_jsxs(_Fragment, { children: [children, cross] })));
     return createElement(as, props, inner(_jsxs(_Fragment, { children: [head && _jsx(CardHead, { heading: heading, caption: caption, end: end, level: level }, "head"), Children.toArray(children), tail && _jsx(CardFoot, { link: footLink, children: foot }, "foot"), cross] })));

package/dist/cards/cardGo.d.ts

@@ -1,2 +1,4 @@
 /** the control this card presses when it is touched off that control, or null: the card is only read */
 export declare function goControl(card: HTMLElement): HTMLElement | null;
+/** the press landed on something the member presses inside this card (a Card with a `back` turns only when it did not) */
+export declare function onControl(card: HTMLElement, target: Element): boolean;

package/dist/cards/cardGo.js

@@ -27,3 +27,8 @@ export function goControl(card) {
     const atRowEnd = card.matches('.card--row') && card.lastElementChild === control && !control.matches('.card__remove'); // a row's cross takes it off its list: never pressed by a touch elsewhere
     return inFoot || atRowEnd ? control : null;
 }
+/** the press landed on something the member presses inside this card (a Card with a `back` turns only when it did not) */
+export function onControl(card, target) {
+    const control = target.closest(CONTROLS);
+    return control != null && control !== card && card.contains(control);
+}