@usableapp/cardds 0.7.22 → 0.7.24

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 > 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.24 — 2026-09-29
+
+### Changed
+- `Sheet` ARRIVES and LEAVES by sliding, always (Lh 2026-09-29). A sheet that mounts already up starts `away` for one frame and slides in — so every sheet on a screen now slides in when the screen opens, and `{open && <Sheet state="full">}` slides in (before: it appeared at once).
+
+### Added
+- **One way in** (Lh 2026-09-29): `npx cardds init` (writes `theme.css` from the template, adds `npm run cardds:check`) and `npx cardds check [dir]` — the rules of how a project uses cardds: a cardds class written by hand = error (the look without the behaviour — import the component); `<Sheet state>` without `onStateChange`, or a `Sheet` on a condition without `onSettled` = warning; a bar after `</Screen>` / pinned by hand = error. The same rules for ESLint 9: `import cardds from '@usableapp/cardds/eslint'`, add `cardds.configs.recommended` (`cardds/check` errors · `cardds/advice` warnings). Skip one line on purpose: `// cardds-ignore-next-line`.
+- `Sheet onSettled(state)`: the sheet finished sliding. To take a sheet away: set `state="away"`, unmount it in `onSettled` when the state is `away` — it slides out. Unmounted while still up, it can only vanish: a dev warning says so. Gallery: `Sheet · MountedOnDemand` (the right way), `Sheet · UnmountedWhileUp` (the warning).
+
+## 0.7.23 — 2026-09-29
+
+### Added
+- `IconBtnGroup` (Lh 2026-09-29): up to FOUR icon-only `IconBtn`s in ONE frame. They share its width, with a rule between them in the frame's colour. At home in a `CardFoot` (card or sheet), where it takes the row. More than 4 → a dev warning.
+  - Plain: commands, each on its own `onClick`. Pressing dims the button; it never shrinks.
+  - `select="one"`: one on at a time. `select="many"`: each on or off by itself. A pressed button STAYS filled (`aria-pressed`). Each child names itself with `value`. The group takes `value` + `onChange`, or `defaultValue`.
+  - Knobs: `--icon-btn-group-h` · `-border` · `-radius` · `-bg` · `-ink` · `-rule` · `-on-bg` · `-on-ink`. Gallery: `/IconBtnGroup`.
+
 ## 0.7.22 — 2026-09-29
 
 ### Changed

package/README.md

@@ -92,8 +92,18 @@ npm i @usableapp/cardds
 ```tsx
 import { Card, CardHead, Btn } from '@usableapp/cardds';
 import '@usableapp/cardds/dist/cardds.css';   // the CSS, fonts resolve from the package
+import './theme.css';                          // the project's look, after cardds.css
 ```
 
+**One way in, one step** (2026-09-29): `npx cardds init` — writes the project's `theme.css` (a copy of the
+template), adds `npm run cardds:check`, and says what to import. Then a screen is a template (`Walkthrough` · `Home` ·
+`CallSheet` · `Splash`) or components composed — IMPORTED, never their markup copied: the behaviour lives in the
+component. `npx cardds check [dir]` runs the rules (`lint/rules.mjs`): a hand-written cardds class is an error; a
+`Sheet` that cannot move (`state` without `onStateChange`) or leaves by vanishing (on a condition without
+`onSettled`) is a warning; a bar after `</Screen>` or pinned by hand is an error. The same rules in ESLint (flat
+config): `import cardds from '@usableapp/cardds/eslint'` → `cardds.configs.recommended`. A deliberate exception:
+`// cardds-ignore-next-line`. Adjust from outside only: `theme.css` → knobs → props / slots.
+
 
 **เบราว์เซอร์** (เช็ก 2026-09-24): iPhone ตั้งแต่ **iOS 16.4** (มี.ค. 2023) ขึ้นไป
 
@@ -289,6 +299,9 @@ whose markup has rules, because the sheet's box is the step itself:
   onStateChange={setS}>` (controlled) or `<Sheet defaultState="half">` (it keeps its own). The sheet's own behaviour —
   the handle's tap and drag, the focus raise, the climb when the keyboard moves the cut — lives in the component and
   only ever ASKS through `onStateChange(state, reason)`; nothing outside the sheet is touched.
+  A sheet always ARRIVES and LEAVES by sliding: mounted already up, it starts `away` for one frame and slides in. To
+  take it off the screen set `state="away"` and unmount it in `onSettled` (`s === 'away'`) — unmounting it while it is up
+  only makes it vanish (dev warning). Story: `Sheet · MountedOnDemand`.
 
 ## Centred card markup
 

package/bin/cardds.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// `npx cardds init` — set a project up the ONE way (Lh 2026-09-29): the project's theme.css, the check script, the ESLint rules.
+// `npx cardds check [dir…]` — the rules of lint/rules.mjs over the project's source; exit 1 on an error.
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkSource } from '../lint/rules.mjs';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const [cmd, ...args] = process.argv.slice(2);
+const cwd = process.cwd();
+const SKIP = new Set(['node_modules', 'dist', 'build', '.git', '.next', 'coverage']);
+
+function* sources(dir) {
+  for (const name of readdirSync(dir)) {
+    if (SKIP.has(name) || name.startsWith('.')) continue;
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) yield* sources(p);
+    else if (/\.(jsx|tsx|js|ts)$/.test(name) && !/\.d\.ts$/.test(name)) yield p;
+  }
+}
+
+function check(dirs) {
+  const roots = (dirs.length ? dirs : ['src']).map((d) => join(cwd, d)).filter((d) => existsSync(d));
+  if (!roots.length) { console.error('cardds check: no such folder — `npx cardds check <dir>`'); return 2; }
+  let errors = 0, warns = 0;
+  for (const root of roots) for (const file of sources(root)) {
+    for (const f of checkSource(readFileSync(file, 'utf8'), relative(cwd, file))) {
+      f.level === 'error' ? errors++ : warns++;
+      console.log(`${f.file}:${f.line}  ${f.level === 'error' ? 'error' : 'warn '}  [${f.rule}] ${f.message}`);
+    }
+  }
+  console.log(errors + warns ? `\ncardds check: ${errors} error(s), ${warns} warning(s)` : 'cardds check: clean');
+  return errors ? 1 : 0;
+}
+
+function init() {
+  const say = (done, what) => console.log(`${done ? '✓' : '·'} ${what}`);
+  const src = existsSync(join(cwd, 'src')) ? 'src' : '.';
+
+  // 1 · the project's look: its own theme.css, a copy of the template (the defaults — nothing moves until a base is set)
+  const theme = join(cwd, src, 'theme.css');
+  if (existsSync(theme)) say(false, `${relative(cwd, theme)} is there — kept`);
+  else { mkdirSync(dirname(theme), { recursive: true }); copyFileSync(join(PKG, 'css', 'theme.template.css'), theme); say(true, `${relative(cwd, theme)} — the project's look: set the bases there, nothing else`); }
+
+  // 2 · the check, as a script the project (and its AI) runs before a screen is called done
+  const pkgFile = join(cwd, 'package.json');
+  if (existsSync(pkgFile)) {
+    const pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+    pkg.scripts ??= {};
+    if (pkg.scripts['cardds:check']) say(false, 'package.json "cardds:check" is there — kept');
+    else { pkg.scripts['cardds:check'] = `cardds check ${src === '.' ? '' : src}`.trim(); writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + '\n'); say(true, 'package.json "cardds:check" — run it before a screen is done'); }
+  }
+
+  // 3 · the same rules in the editor, where the project has ESLint (flat config)
+  const eslint = ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.ts'].map((f) => join(cwd, f)).find(existsSync);
+  if (eslint && /@usableapp\/cardds\/eslint/.test(readFileSync(eslint, 'utf8'))) say(false, `${relative(cwd, eslint)} has the cardds rules — kept`);
+  else if (eslint) say(false, `${relative(cwd, eslint)}: add  import cardds from '@usableapp/cardds/eslint'  and  cardds.configs.recommended  to its array`);
+  else say(false, 'no ESLint here — `npm run cardds:check` carries the same rules');
+
+  console.log(`
+In the app's entry, once:
+  import '@usableapp/cardds/dist/cardds.css';
+  import './theme.css';                       // after cardds.css
+
+Start a screen from a template (Walkthrough · Home · CallSheet · Splash) or compose the components —
+import them, never copy their markup: the behaviour lives in the component. Gallery: see README.`);
+  return 0;
+}
+
+const code = cmd === 'check' ? check(args) : cmd === 'init' ? init() : (console.log('usage: cardds init | cardds check [dir…]'), cmd ? 2 : 0);
+process.exit(code);

package/css/actions.css

@@ -93,6 +93,24 @@
 }
 .icon-btn--invert { background: var(--icon-btn-invert-bg, var(--accent)); color: var(--icon-btn-invert-ink, var(--on-accent)); border-color: transparent; }
 .icon-btn--sm { width: var(--icon-btn-sm-size, var(--tap-sm)); height: var(--icon-btn-sm-size, var(--tap-sm)); font-size: var(--fs-title); }
+/* ---- icon button group: up to four icon-only commands in ONE frame (Lh 2026-09-29) ----
+   <div class="icon-btn-group" role="group"><button class="icon-btn" aria-label="…">…</button>…</div>
+   One pill as tall as a button, the buttons share its width, a hairline between them; in a foot it takes the row. */
+.icon-btn-group {
+  display: flex; min-width: 0;
+  min-height: var(--icon-btn-group-h, var(--btn-h));
+  border: var(--border-w) solid var(--icon-btn-group-border, var(--outline));
+  border-radius: var(--icon-btn-group-radius, var(--r-chip));
+  background: var(--icon-btn-group-bg, var(--action-bg));
+  color: var(--icon-btn-group-ink, var(--action-ink));
+  overflow: clip;
+}
+.icon-btn-group > .icon-btn { flex: 1 1 0; min-width: 0; width: auto; height: auto; border: 0; border-radius: 0; background: transparent; color: inherit; box-shadow: none; }
+.icon-btn-group > .icon-btn + .icon-btn { border-inline-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
+.card__foot > .icon-btn-group { flex: 1 1 0; }
+.icon-btn-group > .icon-btn[aria-pressed="true"] { background: var(--icon-btn-group-on-bg, var(--accent)); color: var(--icon-btn-group-on-ink, var(--on-accent)); } /* `select`: a pressed button STAYS filled (Lh 2026-09-29) */
+.icon-btn-group > .icon-btn:active:not(:disabled) { scale: 1; opacity: var(--press-dim); } /* a part of one frame DIMS, it never shrinks inside it */
+
 /* fab: the square floating action, bottom-right of a stage or screen */
 .fab { width: var(--fab); height: var(--fab); border-radius: var(--r-card); position: absolute; right: var(--sp-4); bottom: calc(var(--sp-5) + var(--bar-h) + var(--sp-3) + var(--safe-bottom)); box-shadow: var(--shadow-float); z-index: var(--z-fab); }
 

package/dist/actions/IconBtnGroup.d.ts

@@ -0,0 +1,19 @@
+import { type ComponentProps } from 'react';
+type Picked = string | null | string[];
+export interface IconBtnGroupProps extends Omit<ComponentProps<'div'>, 'onChange' | 'defaultValue'> {
+    /** the group's accessible name (what these commands act on) */
+    label?: string;
+    /** buttons that STAY ON when pressed (Lh 2026-09-29): `one` — one on at a time, pressing another moves it (value: the on
+     *  button's `value`, or null) · `many` — each on or off by itself (value: the on ones' values). None = plain commands. */
+    select?: 'one' | 'many';
+    /** which are on — each child IconBtn names itself with its own `value` */
+    value?: Picked;
+    defaultValue?: Picked;
+    /** asks the app: `one` → the pressed value · `many` → the new list */
+    onChange?: (value: Picked) => void;
+}
+/** IconBtnGroup — a panel of up to FOUR icon-only buttons in ONE frame, sharing its width, a rule between them in the frame's
+ *  colour (Lh 2026-09-29). Each is an `IconBtn` (its `label` is its spoken name). Plain: each does its own thing on its onClick.
+ *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot. */
+export declare function IconBtnGroup({ label, select, value, defaultValue, onChange, className, children, ...rest }: IconBtnGroupProps): import("react").JSX.Element;
+export {};

package/dist/actions/IconBtnGroup.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement } from 'react';
+import { cx } from '../cx.js';
+import { useControlled, warnOnce } from '../state.js';
+/** IconBtnGroup — a panel of up to FOUR icon-only buttons in ONE frame, sharing its width, a rule between them in the frame's
+ *  colour (Lh 2026-09-29). Each is an `IconBtn` (its `label` is its spoken name). Plain: each does its own thing on its onClick.
+ *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot. */
+export function IconBtnGroup({ label, select, value, defaultValue, onChange, className, children, ...rest }) {
+    if (Children.count(children) > 4)
+        warnOnce('icon-btn-group', 'cardds IconBtnGroup: more than 4 buttons — keep 4, put the rest in a Menu behind one of them');
+    const [shown, request] = useControlled(value, defaultValue ?? (select === 'many' ? [] : null), onChange);
+    const on = (v) => (Array.isArray(shown) ? shown.includes(v) : shown === v);
+    const items = !select ? children : Children.map(children, (c) => {
+        if (!isValidElement(c))
+            return c;
+        const el = c;
+        const v = el.props.value;
+        if (v == null)
+            return c;
+        return cloneElement(el, {
+            'aria-pressed': on(v),
+            onClick: (e) => {
+                el.props.onClick?.(e);
+                if (select === 'one')
+                    request(v);
+                else {
+                    const list = Array.isArray(shown) ? shown : [];
+                    request(on(v) ? list.filter((x) => x !== v) : [...list, v]);
+                }
+            },
+        });
+    });
+    return _jsx("div", { role: "group", "aria-label": label, className: cx('icon-btn-group', className), ...rest, children: items });
+}

package/dist/cardds.css

@@ -2117,6 +2117,24 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 }
 .icon-btn--invert { background: var(--icon-btn-invert-bg, var(--accent)); color: var(--icon-btn-invert-ink, var(--on-accent)); border-color: transparent; }
 .icon-btn--sm { width: var(--icon-btn-sm-size, var(--tap-sm)); height: var(--icon-btn-sm-size, var(--tap-sm)); font-size: var(--fs-title); }
+/* ---- icon button group: up to four icon-only commands in ONE frame (Lh 2026-09-29) ----
+   <div class="icon-btn-group" role="group"><button class="icon-btn" aria-label="…">…</button>…</div>
+   One pill as tall as a button, the buttons share its width, a hairline between them; in a foot it takes the row. */
+.icon-btn-group {
+  display: flex; min-width: 0;
+  min-height: var(--icon-btn-group-h, var(--btn-h));
+  border: var(--border-w) solid var(--icon-btn-group-border, var(--outline));
+  border-radius: var(--icon-btn-group-radius, var(--r-chip));
+  background: var(--icon-btn-group-bg, var(--action-bg));
+  color: var(--icon-btn-group-ink, var(--action-ink));
+  overflow: clip;
+}
+.icon-btn-group > .icon-btn { flex: 1 1 0; min-width: 0; width: auto; height: auto; border: 0; border-radius: 0; background: transparent; color: inherit; box-shadow: none; }
+.icon-btn-group > .icon-btn + .icon-btn { border-inline-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
+.card__foot > .icon-btn-group { flex: 1 1 0; }
+.icon-btn-group > .icon-btn[aria-pressed="true"] { background: var(--icon-btn-group-on-bg, var(--accent)); color: var(--icon-btn-group-on-ink, var(--on-accent)); } /* `select`: a pressed button STAYS filled (Lh 2026-09-29) */
+.icon-btn-group > .icon-btn:active:not(:disabled) { scale: 1; opacity: var(--press-dim); } /* a part of one frame DIMS, it never shrinks inside it */
+
 /* fab: the square floating action, bottom-right of a stage or screen */
 .fab { width: var(--fab); height: var(--fab); border-radius: var(--r-card); position: absolute; right: var(--sp-4); bottom: calc(var(--sp-5) + var(--bar-h) + var(--sp-3) + var(--safe-bottom)); box-shadow: var(--shadow-float); z-index: var(--z-fab); }
 

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export * from './sheets/SheetSteps.js';
 export * from './sheets/Drawer.js';
 export * from './actions/Btn.js';
 export * from './actions/IconBtn.js';
+export * from './actions/IconBtnGroup.js';
 export * from './actions/Chip.js';
 export * from './actions/Dot.js';
 export * from './actions/Dropdown.js';

package/dist/index.js

@@ -37,6 +37,7 @@ export * from './sheets/SheetSteps.js';
 export * from './sheets/Drawer.js';
 export * from './actions/Btn.js';
 export * from './actions/IconBtn.js';
+export * from './actions/IconBtnGroup.js';
 export * from './actions/Chip.js';
 export * from './actions/Dot.js';
 export * from './actions/Dropdown.js';

package/dist/sheets/Sheet.d.ts

@@ -14,6 +14,9 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
     /** the sheet ASKS to move — the handle was tapped or dragged, a field in a peeked sheet took focus, the keyboard moved the cut.
      *  Controlled: set your state to it (or don't — the sheet stays). This is where an app ties a sheet to its router / back button. */
     onStateChange?: (state: SheetState, reason: SheetChangeReason) => void;
+    /** the sheet has FINISHED sliding to `state` (its transition ended; at once where motion is off). To leave the screen: set `away`, and take the
+     *  sheet out of the tree here — `onSettled={(s) => s === 'away' && setMounted(false)}` — so it slides out instead of vanishing */
+    onSettled?: (state: SheetState) => void;
     /** the states a drag snaps to and a reveal may climb through — "peek half full", or an array (default all four) */
     states?: string | readonly Resting[];
     /** the grab handle; `false` for a sheet with no handle, a string sets its accessible name */
@@ -30,6 +33,10 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
  * Its own behaviour stays inside it and only ever ASKS (`onStateChange`): a tap on the handle toggles its own state ↔ peek,
  * a drag snaps to the nearest of `states`, focus in a peeked sheet raises it, and when the cut moves (the keyboard) it
  * climbs until the focused control has room above the foot.
+ *
+ * It ARRIVES and LEAVES by sliding, always: a sheet that mounts already up starts `away` for one frame and slides to its state, so
+ * `{open && <Sheet state="full">}` slides in. Leaving is the app's beat: set `away`, and unmount on `onSettled('away')` — unmount it
+ * while it is still up and it can only vanish (a dev warning says so).
  */
-export declare function Sheet({ state, defaultState, onStateChange, states, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
+export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
 export {};

package/dist/sheets/Sheet.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef } from 'react';
-import { useControlled, watchSize } from '../state.js';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useControlled, useLatest, warnOnce, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
 const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
+const ms = (t) => Math.max(0, ...t.split(',').map((v) => parseFloat(v) * (v.trim().endsWith('ms') ? 1 : 1000) || 0)); // a computed `0.35s, 0s` list → its longest, in ms
 /**
  * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
  * box — a Step or a SheetStage — a state is only how far it slid (translate; the material never changes size).
@@ -15,19 +16,67 @@ const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
  * Its own behaviour stays inside it and only ever ASKS (`onStateChange`): a tap on the handle toggles its own state ↔ peek,
  * a drag snaps to the nearest of `states`, focus in a peeked sheet raises it, and when the cut moves (the keyboard) it
  * climbs until the focused control has room above the foot.
+ *
+ * It ARRIVES and LEAVES by sliding, always: a sheet that mounts already up starts `away` for one frame and slides to its state, so
+ * `{open && <Sheet state="full">}` slides in. Leaving is the app's beat: set `away`, and unmount on `onSettled('away')` — unmount it
+ * while it is still up and it can only vanish (a dev warning says so).
  */
-export function Sheet({ state, defaultState = 'half', onStateChange, states, handle = true, className, children, onFocus, ...rest }) {
+export function Sheet({ state, defaultState = 'half', onStateChange, onSettled, states, handle = true, className, children, onFocus, ...rest }) {
     const [current, request] = useControlled(state, defaultState, onStateChange);
     const ref = useRef(null);
     const handleRef = useRef(null);
     const home = useRef(current !== 'peek' && current !== 'away' ? current : 'half'); // where a tap from peek returns to
     const was = useRef(current);
     const skipClick = useRef(false);
+    const [entered, setEntered] = useState(false); // false for the first frame: the class says `away`, so a sheet mounted up has somewhere to slide from
+    const shown = entered ? current : 'away';
+    const latest = useLatest({ current, onSettled });
     const drag = useRef(null);
     const allowed = useCallback(() => {
         const list = (typeof states === 'string' ? states.split(/\s+/) : [...(states ?? [])]).filter((s) => ORDER.includes(s));
         return list.length ? ORDER.filter((s) => list.includes(s)) : [...ORDER];
     }, [states]);
+    useLayoutEffect(() => {
+        void ref.current?.offsetHeight; // the browser styles the `away` frame first, or there is no transition to run
+        setEntered(true);
+    }, []);
+    /* it has finished moving: the transition ended (or at once where there is none) — say so once per move; a move cut short by another says nothing */
+    const last = useRef(shown);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || last.current === shown)
+            return;
+        last.current = shown;
+        const cs = getComputedStyle(el);
+        let done = false;
+        const end = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(t);
+            el.removeEventListener('transitionend', onEnd);
+            latest.current.onSettled?.(latest.current.current);
+        };
+        const onEnd = (e) => { if (e.target === el && e.propertyName === 'translate')
+            end(); };
+        el.addEventListener('transitionend', onEnd);
+        const t = setTimeout(end, ms(cs.transitionDuration) + ms(cs.transitionDelay) + 100); // no transition (motion off) or none came: settled anyway
+        return () => { done = true; clearTimeout(t); el.removeEventListener('transitionend', onEnd); };
+    }, [shown, latest]);
+    /* taken out of the tree while it is still up — the box stays, the sheet goes: nothing to slide, so it vanishes. Said once in dev.
+       (A whole screen leaving takes the box too; StrictMode's trial unmount is over by the time the timer looks.) */
+    const alive = useRef(false);
+    useEffect(() => {
+        alive.current = true;
+        const box = ref.current?.parentElement;
+        return () => {
+            alive.current = false;
+            setTimeout(() => {
+                if (!alive.current && box?.isConnected && latest.current.current !== 'away')
+                    warnOnce('sheet-unmount', 'cardds Sheet: unmounted while on the screen, so it vanished instead of sliding out. Set state="away" and unmount it in onSettled (state === "away").');
+            });
+        };
+    }, [latest]);
     useEffect(() => {
         if (current !== 'peek' && current !== 'away')
             home.current = current;
@@ -182,5 +231,5 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, han
         skipClick.current = true;
         requestAnimationFrame(() => { skipClick.current = false; });
     };
-    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${current}`, className), inert: current === 'away' || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : 'Resize', onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${shown}`, className), inert: current === 'away' || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : 'Resize', onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
 }

package/lint/eslint.mjs

@@ -0,0 +1,28 @@
+// `@usableapp/cardds/eslint` — the ESLint front door of lint/rules.mjs (the same rules `npx cardds check` runs).
+//   // eslint.config.js
+//   import cardds from '@usableapp/cardds/eslint';
+//   export default [ …, cardds.configs.recommended ];
+// It reads the file's TEXT, so it works with whatever parser the project already has for .tsx.
+import { checkSource } from './rules.mjs';
+
+// two rules = the two levels of rules.mjs: `check` reports its errors, `advice` its warnings
+const rule = (level, description) => ({
+  meta: { type: level === 'error' ? 'problem' : 'suggestion', docs: { description }, schema: [] },
+  create(context) {
+    const source = context.sourceCode ?? context.getSourceCode();
+    return {
+      'Program:exit'() {
+        for (const f of checkSource(source.text, context.filename ?? context.getFilename()))
+          if (f.level === level) context.report({ loc: { line: f.line, column: 0 }, message: `[${f.rule}] ${f.message}` });
+      },
+    };
+  },
+});
+const check = rule('error', 'cardds used through its components: no hand-written cardds class; the bar is the Screen\'s bottom');
+const advice = rule('warn', 'cardds behaviour kept: a Sheet that can move and slides out; no bar in front of a sheet');
+
+const plugin = { meta: { name: '@usableapp/cardds/eslint' }, rules: { check, advice } };
+plugin.configs = {
+  recommended: { files: ['**/*.{js,jsx,ts,tsx}'], plugins: { cardds: plugin }, rules: { 'cardds/check': 'error', 'cardds/advice': 'warn' } },
+};
+export default plugin;

package/lint/rules.mjs

@@ -0,0 +1,111 @@
+// lint/rules.mjs — how a PROJECT uses cardds, as code. ONE rule set, two front doors (Lh 2026-09-29, "one standard"):
+//   • `npx cardds check [dir]` (bin/cardds.mjs) — no dependency, runs anywhere
+//   • the ESLint plugin (lint/eslint.mjs, `@usableapp/cardds/eslint`) — the same findings in the editor and CI
+// cardds's own tests run it on the gallery's stories (tests/lint.spec.js) and on the screens (tests/composition.spec.js).
+// Plain text in, findings out: { rule, level: 'error' | 'warn', file, line, message }. No parser — any .tsx/.jsx/.ts/.js.
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CSS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'css');
+
+const lineOf = (text, idx) => text.slice(0, idx).split('\n').length;
+
+/** every class cardds's CSS styles — read from the package's own css/, so the list is never copied by hand */
+let classes;
+export function carddsClasses(dir = CSS_DIR) {
+  if (classes && dir === CSS_DIR) return classes;
+  const set = new Set();
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.css') || f.startsWith('theme.')) continue;
+    const css = readFileSync(join(dir, f), 'utf8')
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/url\([^)]*\)/g, '')
+      .replace(/"[^"]*"|'[^']*'/g, '');
+    for (const m of css.matchAll(/(?<![\w\\-])\.(-?[a-zA-Z_][\w-]*)/g)) if (!/^(is|has)-/.test(m[1])) set.add(m[1]); // a bare state word (`is-open`) is every project's too — it only matters beside a cardds class, which is caught
+  }
+  if (dir === CSS_DIR) classes = set;
+  return set;
+}
+
+/** the whole of a JSX opening tag from `<Name` — attributes may hold `=>` and nested braces, so a `[^>]*` regex is not enough */
+function tagAt(text, start) {
+  let depth = 0, quote = null;
+  for (let i = start + 1; i < text.length; i++) {
+    const c = text[i];
+    if (quote) { if (c === quote && text[i - 1] !== '\\') quote = null; continue; }
+    if (c === '"' || c === "'" || c === '`') quote = c;
+    else if (c === '{') depth++;
+    else if (c === '}') depth--;
+    else if (c === '>' && depth === 0) return text.slice(start, i + 1);
+  }
+  return text.slice(start);
+}
+
+/** the expression of a `{…}` attribute value from its opening brace */
+function braceAt(text, start) {
+  let depth = 0, quote = null;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (quote) { if (c === quote && text[i - 1] !== '\\') quote = null; continue; }
+    if (c === '"' || c === "'" || c === '`') quote = c;
+    else if (c === '{') depth++;
+    else if (c === '}' && --depth === 0) return text.slice(start, i + 1);
+  }
+  return text.slice(start);
+}
+
+/** the static words a className holds: its string, or every string / template text inside its `{…}` */
+function classWords(text, at) {
+  const rest = text.slice(at);
+  const lit = rest.match(/^\s*=\s*(?:"([^"]*)"|'([^']*)')/);
+  if (lit) return (lit[1] ?? lit[2]).split(/\s+/);
+  const open = rest.match(/^\s*=\s*\{/);
+  if (!open) return [];
+  const expr = braceAt(text, at + open[0].length - 1);
+  const words = [];
+  for (const m of expr.matchAll(/"([^"]*)"|'([^']*)'|`([^`]*)`/g)) words.push(...(m[1] ?? m[2] ?? m[3].replace(/\$\{[^}]*\}/g, ' ')).split(/\s+/));
+  return words;
+}
+
+/**
+ * @param {string} text  a source file
+ * @param {string} file  its name, for the findings
+ * @param {{ classes?: Set<string> }} [opts]
+ */
+export function checkSource(source, file, { classes = carddsClasses() } = {}) {
+  const findings = [];
+  const lines = source.split('\n');
+  const text = source.replace(/\/\*[\s\S]*?\*\/|(?<![:'"`\\])\/\/[^\n]*/g, (c) => c.replace(/[^\n]/g, ' ')); // comments out, lines kept
+  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)
+  };
+
+  // 1 · a cardds class written by hand: the look comes without the behaviour — import the component
+  for (const m of text.matchAll(/\bclass(?:Name)?(?=\s*=)/g)) {
+    const hit = [...new Set(classWords(text, m.index + m[0].length).filter((w) => classes.has(w)))];
+    if (hit.length) add('raw-class', 'error', m.index, `cardds class written by hand (${hit.map((w) => '.' + w).join(' ')}): the look without the behaviour — use the cardds component (its props pick the classes), or a knob / theme.css for the look.`);
+  }
+
+  // 2 · Sheet: controlled with no way to move · put in the tree on a condition with no slide out
+  for (const m of text.matchAll(/<Sheet\b/g)) {
+    const tag = tagAt(text, m.index);
+    if (/\sstate\s*=/.test(tag) && !/\sonStateChange\s*=/.test(tag))
+      add('sheet-frozen', 'warn', m.index, '<Sheet state> without onStateChange: the handle, the drag and the keyboard climb only ASK — nothing answers, the sheet cannot move. Add onStateChange, or use defaultState.');
+    const before = text.slice(Math.max(0, m.index - 40), m.index);
+    if (/(?:&&|\?|:)\s*\(?\s*$/.test(before) && !/\sonSettled\s*=/.test(tag))
+      add('sheet-unmounted', 'warn', m.index, '<Sheet> rendered on a condition without onSettled: taken out of the tree it vanishes instead of sliding out. Set state="away" and unmount it in onSettled (state === "away") — or keep it mounted and switch its state.');
+  }
+
+  // 3 · the screen: the bar is the Screen's bottom, never after it, never pinned; a sheet finishes on its own foot
+  for (const m of text.matchAll(/<\/Screen>\s*(?:\{[^}]*\}\s*)*<(ActionBar|FloatBar)\b/g)) add('screen.bar-outside', 'error', m.index, `${m[1]} after </Screen>: pass it as <Screen bottom={…}> — the screen's column lays it.`);
+  for (const m of text.matchAll(/<(ActionBar|FloatBar)\b[^>]*style=\{\{[^}]*\bposition\b/g)) add('screen.bar-pinned', 'error', m.index, `${m[1]} with a hand-set position: the screen's flex column places the bar.`);
+  const fns = [...text.matchAll(/export (?:default )?function (\w+)/g)];
+  fns.forEach((m, i) => {
+    const body = text.slice(m.index, fns[i + 1]?.index ?? text.length);
+    if (/<Sheet\b/.test(body) && /<ActionBar\b/.test(body)) add('screen.bar-with-sheet', 'warn', m.index, `${m[1]}: a Sheet and an ActionBar — a screen with a sheet finishes on the sheet's CardFoot, no bar.`);
+  });
+
+  return findings.sort((a, b) => a.line - b.line);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.22",
+  "version": "0.7.24",
   "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.",
@@ -17,7 +17,8 @@
     "knobs": "node scripts/knobs.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p gallery/tsconfig.json --noEmit",
     "snapshot:write": "CARDDS_SNAPSHOT=write playwright test tests/style-snapshot.spec.js",
-    "snapshot:check": "CARDDS_SNAPSHOT=check playwright test tests/style-snapshot.spec.js"
+    "snapshot:check": "CARDDS_SNAPSHOT=check playwright test tests/style-snapshot.spec.js",
+    "check": "node bin/cardds.mjs check .design-sync/previews gallery/src"
   },
   "devDependencies": {
     "@playwright/test": "1.58.2",
@@ -33,6 +34,9 @@
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "cardds": "bin/cardds.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -42,10 +46,13 @@
     "./dist/cardds.css": "./dist/cardds.css",
     "./css/*": "./css/*",
     "./cardds.js": "./cardds.js",
-    "./icons.svg": "./icons.svg"
+    "./icons.svg": "./icons.svg",
+    "./eslint": "./lint/eslint.mjs"
   },
   "files": [
     "dist",
+    "lint",
+    "bin",
     "css",
     "fonts",
     "cardds.css",
@@ -56,12 +63,18 @@
   ],
   "peerDependencies": {
     "react": ">=19",
-    "react-dom": ">=19"
+    "react-dom": ">=19",
+    "eslint": ">=9"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@oddbird/popover-polyfill": "^0.7.2"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    }
   }
 }