@usableapp/cardds 0.2.2 → 0.4.0

package/dist/sheets/SheetStack.d.ts

@@ -1,7 +1,14 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface SheetStackProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface SheetStackProps extends ComponentProps<'div'> {
     /** `tap` (default): a tapped head brings its sheet to the front, its back button returns it · `display`: the giant title is the peek (recents, a library) · `static`: peeks only, the last sheet open */
     mode?: 'tap' | 'display' | 'static';
+    /** CONTROLLED (tap mode): which sheet is open — its index among the children, first = 0 — or `null` for none. The app owns it (a route, a
+     *  button anywhere, the back button): pair it with `onOpenChange`, or the stack cannot move. */
+    open?: number | null;
+    /** UNCONTROLLED: the sheet open on arrival (default none); the stack then keeps its own */
+    defaultOpen?: number | null;
+    /** the stack ASKS: a peeked head was tapped (its index), or the open sheet's `CardBack` (`null`) */
+    onOpenChange?: (open: number | null) => void;
     /** wider peeks so more of each title shows (display stacks) */
     fanned?: boolean;
     /** nothing open on arrival (tap mode): every sheet, the front one too, peeks at the stack's bottom; the room above is the base's (`base`). A tap opens any sheet over it */
@@ -17,5 +24,10 @@ export interface SheetStackProps extends ComponentPropsWithoutRef<'div'> {
  * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
+ *
+ * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
+ * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, the open
+ * sheet's CardBack. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export declare function SheetStack({ mode, fanned, closed, base, className, children, ...rest }: SheetStackProps): import("react").JSX.Element;
+export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }: SheetStackProps): import("react").JSX.Element;

package/dist/sheets/SheetStack.js

@@ -1,5 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
+const PHASE = 380; // ms before the before-pack un-tucks on close, so the after-pack is clear first
+/* the stack's sheets, in slot order: its direct children — or, where a host wraps each child in one box of its own, the first .card in
+   each. Never deeper: a card inside a sheet's content is content. The base is what shows behind the sheets, never a sheet. */
+const sheetsOf = (stack) => [...stack.children]
+    .filter((c) => !c.classList.contains('sheet-stack__base'))
+    .map((c) => (c.classList.contains('card') ? c : c.querySelector(':scope > .card')))
+    .filter((c) => c instanceof HTMLElement);
 /**
  * SheetStack — the MENU: sheets stacked like paper at the middle of the home screen, every one a main section.
  * Children are Cards, direct children only, at most five: first = the back of the stack, last = the front (open) sheet.
@@ -8,7 +16,71 @@ import { cx } from '../cx.js';
  * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
+ *
+ * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
+ * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, the open
+ * sheet's CardBack. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export function SheetStack({ mode = 'tap', fanned, closed, base, className, children, ...rest }) {
-    return (_jsxs("div", { className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, children: [children, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
+export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }) {
+    const [inner, setInner] = useState(defaultOpen);
+    const current = open !== undefined ? open : inner;
+    const ref = useRef(null);
+    const was = useRef(null);
+    const untuck = useRef(null);
+    const request = (next) => {
+        if (next === current)
+            return;
+        if (open === undefined)
+            setInner(next);
+        onOpenChange?.(next);
+    };
+    /* paint the state onto the sheets — after every render, so a re-rendered Card never loses its place */
+    useLayoutEffect(() => {
+        const stack = ref.current;
+        if (!stack || mode !== 'tap')
+            return;
+        const sheets = sheetsOf(stack);
+        const prev = was.current;
+        was.current = current;
+        if (current != null) {
+            if (untuck.current) {
+                clearTimeout(untuck.current);
+                untuck.current = null;
+            }
+            sheets.forEach((c, i) => {
+                c.classList.toggle('is-open', i === current);
+                c.classList.toggle('is-before', i < current); // already behind it — tuck under the next strip and get covered…
+                c.classList.toggle('is-after', i > current); // in front of it — these leave below
+                c.style.setProperty('--stagger', String(i < current ? current - 1 - i : 0)); // …nearest one first
+            });
+            return;
+        }
+        if (prev != null && prev !== current) {
+            // beat 1: the after-pack comes back in while the opened sheet drops into its slot, over the still-covered before-pack
+            sheets.forEach((c) => c.classList.remove('is-open', 'is-after'));
+            // beat 2: then the before-pack slides back up from behind it, the same order it tucked away
+            untuck.current = setTimeout(() => { untuck.current = null; if (ref.current)
+                sheetsOf(ref.current).forEach((c) => c.classList.remove('is-before')); }, PHASE);
+            return;
+        }
+        if (!untuck.current)
+            sheets.forEach((c) => c.classList.remove('is-open', 'is-before', 'is-after'));
+    });
+    const click = (e) => {
+        onClick?.(e);
+        const stack = ref.current;
+        if (!stack || mode !== 'tap')
+            return;
+        const target = e.target;
+        const sheets = sheetsOf(stack);
+        const at = sheets.findIndex((c) => c.contains(target)); // the sheet the tap landed in — not the nearest .card: a content card inside an open sheet must not count
+        if (target.closest('.card__back')) {
+            request(null);
+            return;
+        }
+        if (at >= 0 && current == null)
+            request(at);
+    };
+    return (_jsxs("div", { ref: ref, onClick: click, className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, children: [children, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
 }

package/dist/sheets/SheetStage.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface SheetStageProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface SheetStageProps extends ComponentProps<'div'> {
     /** what sits behind the sheet: a map, previous cards, page copy */
     bg?: ReactNode;
     /** ONE thing shown in the band a half sheet leaves open (a postcard being made), centred there */

package/dist/sheets/Step.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface StepProps extends ComponentPropsWithoutRef<'section'> {
+import type { ComponentProps } from 'react';
+export interface StepProps extends ComponentProps<'section'> {
 }
 /**
  * Step — one screen, one task. Children: a BaseContent first (what the member READS — words on the base, not a card), an optional Sheet last

package/dist/type/Icon.d.ts

@@ -1,16 +1,31 @@
-import { type IconName } from './icons.js';
-export type { IconName };
-export interface IconProps extends Omit<React.ComponentPropsWithoutRef<'svg'>, 'children'> {
-    /** one of the 57 Lucide symbols in icons.svg (arrow-left, bell, check, chevron-down, id-card, plus, x, …) */
-    name: IconName;
+import type { ReactNode } from 'react';
+import { type IconName as StockIconName } from './icons.js';
+/** an icon's name: one of the stock symbols (autocompleted) — or any name a project registered with `registerIcons` */
+export type IconName = StockIconName | (string & {});
+/**
+ * registerIcons — a project's OWN icons, by name: after this, `icon="map-pin"` works on every component that takes an icon (Icon, IconBtn,
+ * Field, MenuItem, Tile…), exactly like a stock one. Call it once at startup. A drawing is the INSIDE of the `<svg>` as a string (paths on a
+ * 24×24 box, drawn with the shared stroke), or `{ body, attrs }` to bring its own viewBox / fill. A registered name wins over a stock one —
+ * that is how a project swaps a symbol for its own. Returns nothing; safe to call again (later drawings replace earlier ones).
+ */
+export declare function registerIcons(icons: Record<string, string | {
+    body: string;
+    attrs?: Record<string, string>;
+}>): void;
+export interface IconProps extends Omit<React.ComponentProps<'svg'>, 'children' | 'name'> {
+    /** a stock symbol (arrow-left, bell, check, chevron-down, id-card, plus, x, …) or a name the project registered (`registerIcons`). Omit it to draw with `children`. */
+    name?: IconName;
+    /** a ONE-OFF drawing: the svg's own children (`<path d="…" />`), on a 24×24 box with the shared stroke — for an icon not worth registering */
+    children?: ReactNode;
     /** xs = 16px, inside captions, chips and links · sm = in a small icon button or a field (28px today — one size everywhere, tokens.css) · md (default) = the 28px icon · lg = 32px, empty states */
     size?: 'xs' | 'sm' | 'md' | 'lg';
     /** an accessible name makes the icon meaningful (role="img"); without one it is decorative and hidden from assistive tech */
     label?: string;
 }
 /**
- * Icon — a Lucide stroke icon from the cardds sprite, inlined (no icons.svg file needed at runtime).
+ * Icon — a stroke icon, inlined (no sprite file at runtime): one of the stock Lucide symbols, one of the project's OWN (`registerIcons`), or a
+ * one-off drawn with `children`. The set is open — a project never comes to cardds for an icon.
  * Sizes are the tokens the CSS defines: `.icon` 28px, `--sm` 28px (a semantic size, same as md today), `--xs` 16px, `--lg` 32px.
  * Keep it big: inside a button or a row the default 28px icon is the norm; xs only sits in text.
  */
-export declare function Icon({ name, size, label, className, ...rest }: IconProps): import("react").JSX.Element;
+export declare function Icon({ name, children, size, label, className, ...rest }: IconProps): import("react").JSX.Element;

package/dist/type/Icon.js

@@ -1,12 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 import { ICONS } from './icons.js';
+/* the stroke style every stock symbol shares (Lucide): a project's drawing takes it unless it brings its own attrs */
+const STROKE = { viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: '2', strokeLinecap: 'round', strokeLinejoin: 'round' };
+const OWN = new Map();
 /**
- * Icon — a Lucide stroke icon from the cardds sprite, inlined (no icons.svg file needed at runtime).
+ * registerIcons — a project's OWN icons, by name: after this, `icon="map-pin"` works on every component that takes an icon (Icon, IconBtn,
+ * Field, MenuItem, Tile…), exactly like a stock one. Call it once at startup. A drawing is the INSIDE of the `<svg>` as a string (paths on a
+ * 24×24 box, drawn with the shared stroke), or `{ body, attrs }` to bring its own viewBox / fill. A registered name wins over a stock one —
+ * that is how a project swaps a symbol for its own. Returns nothing; safe to call again (later drawings replace earlier ones).
+ */
+export function registerIcons(icons) {
+    for (const [name, d] of Object.entries(icons))
+        OWN.set(name, typeof d === 'string' ? { attrs: STROKE, body: d } : { attrs: { ...STROKE, ...d.attrs }, body: d.body });
+}
+const warned = new Set();
+/**
+ * Icon — a stroke icon, inlined (no sprite file at runtime): one of the stock Lucide symbols, one of the project's OWN (`registerIcons`), or a
+ * one-off drawn with `children`. The set is open — a project never comes to cardds for an icon.
  * Sizes are the tokens the CSS defines: `.icon` 28px, `--sm` 28px (a semantic size, same as md today), `--xs` 16px, `--lg` 32px.
  * Keep it big: inside a button or a row the default 28px icon is the norm; xs only sits in text.
  */
-export function Icon({ name, size = 'md', label, className, ...rest }) {
-    const icon = ICONS[name];
-    return (_jsx("svg", { ...icon.attrs, className: cx('icon', size !== 'md' && `icon--${size}`, className), role: label ? 'img' : undefined, "aria-label": label, "aria-hidden": label ? undefined : true, dangerouslySetInnerHTML: { __html: icon.body }, ...rest }));
+export function Icon({ name, children, size = 'md', label, className, ...rest }) {
+    const icon = name === undefined ? undefined : OWN.get(name) ?? ICONS[name];
+    if (name !== undefined && !icon && !warned.has(name)) {
+        warned.add(name);
+        console.warn(`cardds Icon: no icon named "${name}" — a stock name is misspelt, or the project has not registered it (registerIcons)`);
+    }
+    const shared = { className: cx('icon', size !== 'md' && `icon--${size}`, className), role: label ? 'img' : undefined, 'aria-label': label, 'aria-hidden': label ? undefined : true };
+    // an unknown name draws nothing but keeps its box — a missing icon never takes a screen down
+    if (!icon)
+        return _jsx("svg", { ...STROKE, ...shared, ...rest, children: children });
+    return _jsx("svg", { ...icon.attrs, ...shared, dangerouslySetInnerHTML: { __html: icon.body }, ...rest });
 }

package/dist/type/Text.d.ts

@@ -1,5 +1,7 @@
 export type TextLevel = 'display' | 'h1' | 'h2' | 'title' | 'body' | 'label' | 'caption' | 'overline' | 'stat';
 export interface TextProps extends React.HTMLAttributes<HTMLElement> {
+    /** the element it renders (React 19 passes `ref` as a prop) */
+    ref?: React.Ref<HTMLElement>;
     /** the type level: display (hero words) · h1 · h2 (a card's heading) · title · body · label · caption · overline (small caps above a heading) · stat (a big number) */
     level: TextLevel;
     /** stat only: the one giant number on a sheet (`.t-stat--xl`) */
@@ -8,6 +10,8 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
     mono?: boolean;
     /** muted ink — follows the card it sits in */
     muted?: boolean;
+    /** takes the remaining room of a row (a heading beside a chip in a flex head) */
+    grow?: boolean;
     /** uppercase */
     caps?: boolean;
     /** the element; defaults per level (h2 for display/h1/h2, p for title/body/stat, span for the rest) */
@@ -18,7 +22,9 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
  * Headings inside a card head are h2 by default; a screen title in a TopBar is h1.
  * Everything scales from the root font-size, so there are no pixel sizes to pick.
  */
-export declare function Text({ level, xl, mono, muted, caps, as, className, ...rest }: TextProps): import("react").DetailedReactHTMLElement<{
+export declare function Text({ level, xl, mono, muted, caps, grow, as, className, ...rest }: TextProps): import("react").DetailedReactHTMLElement<{
+    /** the element it renders (React 19 passes `ref` as a prop) */
+    ref?: React.Ref<HTMLElement>;
     defaultChecked?: boolean | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
     suppressContentEditableWarning?: boolean | undefined;

package/dist/type/Text.js

@@ -8,9 +8,9 @@ const DEFAULT_AS = {
  * Headings inside a card head are h2 by default; a screen title in a TopBar is h1.
  * Everything scales from the root font-size, so there are no pixel sizes to pick.
  */
-export function Text({ level, xl, mono, muted, caps, as, className, ...rest }) {
+export function Text({ level, xl, mono, muted, caps, grow, as, className, ...rest }) {
     return createElement(as ?? DEFAULT_AS[level] ?? 'span', {
-        className: cx(`t-${level}`, level === 'stat' && xl && 't-stat--xl', level === 'stat' && mono && 't-stat--mono', muted && 't-muted', caps && 't-caps', className),
+        className: cx(`t-${level}`, level === 'stat' && xl && 't-stat--xl', level === 'stat' && mono && 't-stat--mono', muted && 't-muted', caps && 't-caps', grow && 'grow', className),
         ...rest,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "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.",
@@ -13,7 +13,8 @@
     "build": "node scripts/build-icons.mjs && tsc -p tsconfig.json && node scripts/flatten-css.mjs",
     "test": "playwright test",
     "validate:inbox": "node scripts/validate-inbox.mjs",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "knobs": "node scripts/knobs.mjs"
   },
   "devDependencies": {
     "@playwright/test": "1.58.2",