@usableapp/cardds 0.2.2 → 0.4.0

package/cardds.js

@@ -1,337 +1,10 @@
-/* cardds.js — optional behaviour helpers (the CSS works without it).
-   Dropdown: clicking a .menu__item marks it current, copies its label into the
-   .dropdown__label of the enclosing .dropdown, closes the popover and fires
-   "change" (detail.value) on the .dropdown. */
-document.addEventListener('click', e => {
-  const item = e.target.closest('.menu__item');
-  if (!item) return;
-  const menu = item.closest('.menu');
-  const dd = menu && menu.closest('.dropdown');
-  if (!menu.classList.contains('menu--actions')) { /* an actions menu holds no value: nothing stays current */
-    menu.querySelectorAll('.menu__item').forEach(i => i.removeAttribute('aria-current'));
-    item.setAttribute('aria-current', 'true');
-  }
-  if (dd) {
-    const label = dd.querySelector('.dropdown__label');
-    const value = item.dataset.value ?? item.textContent.trim();
-    if (label) label.textContent = item.dataset.label ?? item.textContent.trim();
-    dd.dataset.value = value;
-    dd.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value } }));
-  }
-  if (menu.matches(':popover-open')) menu.hidePopover();
-});
+/* cardds.js — the little that is not (yet) a component's own code. Nothing here ties one component to another. */
 
-/* Pin (.pin, choice.css): one digit per cell. Typing a digit moves focus to
-   the next cell; Backspace in an empty cell moves it back (and clears that
-   one); a paste of the whole code fills the cells from the one it landed in.
-   Only digits stay. Delegated, so a Pin rendered by any host — the React
-   adapter, plain HTML — gets it; the cells stay ordinary inputs. */
-/* Postcard (.postcard, media.css): a tap on either face turns the card over.
-   Delegated; the faces are buttons, so Enter and Space arrive as clicks. */
-document.addEventListener('click', e => {
-  const face = e.target instanceof Element && e.target.closest('.postcard__face');
-  if (!face) return;
-  const card = face.closest('.postcard');
-  if (!card) return;
-  const flipped = card.classList.toggle('is-flipped');
-  card.dispatchEvent(new CustomEvent('cardds:flip', { bubbles: true, detail: { flipped } }));
-});
-
-/* Slider (.slider, choice.css): the knob's place along the rail, published on
-   the .slider as --slider-at (0..1) so the .slider__glyph can ride the knob.
-   Delegated, and run once for every slider already on the page. */
-function carddsSliderAt(range) {
-  const min = Number(range.min) || 0, max = Number(range.max) || 100;
-  const at = max > min ? (Number(range.value) - min) / (max - min) : 0;
-  range.closest('.slider')?.style.setProperty('--slider-at', String(Math.min(1, Math.max(0, at))));
-}
-document.addEventListener('input', e => {
-  if (e.target instanceof HTMLInputElement && e.target.classList.contains('slider__range')) carddsSliderAt(e.target);
-});
-document.addEventListener('input', e => {
-  const cell = e.target;
-  if (!(cell instanceof HTMLInputElement) || !cell.classList.contains('pin__cell')) return;
-  const cells = [...cell.closest('.pin').querySelectorAll('.pin__cell')];
-  const i = cells.indexOf(cell);
-  const digits = cell.value.replace(/\D/g, '');
-  // a paste (or a typed run) spills over the cells that follow
-  digits.split('').forEach((d, k) => { if (cells[i + k]) cells[i + k].value = d; });
-  if (!digits) cell.value = '';
-  else {
-    const next = cells[Math.min(i + digits.length, cells.length - 1)];
-    if (next !== cell) next.focus();
-    else if (cell.value !== digits.slice(-1)) cell.value = digits.slice(-1);
-  }
-  carddsPinPublish(cells);
-});
-/* "cardds:pin" (bubbles, detail.code = the digits so far, detail.complete)
-   after every change — the one thing a host listens to; the React adapter's
-   Pin turns it into onChange */
-function carddsPinPublish(cells) {
-  const code = cells.map(c => c.value).join('');
-  cells[0].closest('.pin').dispatchEvent(new CustomEvent('cardds:pin', { bubbles: true, detail: { code, complete: code.length === cells.length } }));
-}
-/* a cell holds one digit; typing into a full one replaces it — select the
-   digit before the insert lands (a paste of a whole code still spills over
-   the cells that follow, above). No maxlength on the cells: the browser
-   would truncate a pasted code before this ever saw it. */
-document.addEventListener('beforeinput', e => {
-  const cell = e.target;
-  if (!(cell instanceof HTMLInputElement) || !cell.classList.contains('pin__cell')) return;
-  if (e.inputType === 'insertText' && cell.value && cell.selectionStart === cell.selectionEnd) cell.select();
-});
-document.addEventListener('focusin', e => {
-  const cell = e.target;
-  if (cell instanceof HTMLInputElement && cell.classList.contains('pin__cell') && cell.value) cell.select();
-});
-document.addEventListener('keydown', e => {
-  const cell = e.target;
-  if (!(cell instanceof HTMLInputElement) || !cell.classList.contains('pin__cell')) return;
-  const cells = [...cell.closest('.pin').querySelectorAll('.pin__cell')];
-  const i = cells.indexOf(cell);
-  if (e.key === 'Backspace' && !cell.value && i > 0) {
-    e.preventDefault();
-    cells[i - 1].value = '';
-    cells[i - 1].focus();
-    carddsPinPublish(cells);
-  } else if (e.key === 'ArrowLeft' && i > 0) { e.preventDefault(); cells[i - 1].focus(); }
-  else if (e.key === 'ArrowRight' && i < cells.length - 1) { e.preventDefault(); cells[i + 1].focus(); }
-});
-
-/* Sheet stack (.sheet-stack--tap, stack.css): tap a peeked sheet to open it, its back
-   button returns it. Sheets are rigid material — they move in, move out, or
-   get covered, never morph — so the only animated property is translate;
-   see the --tap block in stack.css for the whole model.
-
-   This only ever toggles classes. Every card's resting slot, offset and
-   paint order is declared in CSS, so a stack still renders correctly with
-   this file absent — it just won't open. Works for any number of stacks on
-   a page, with no ids or per-page wiring. */
-const CARDDS_STACK_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. Normally the stack's direct children;
-   a host that wraps each child in one box of its own (a design tool's
-   per-component frame, a router's element) is tolerated: the first .card
-   inside each child then counts. Never deeper — a card inside a sheet's
-   content is content, not a sheet. */
-function carddsStackCards(stack) {
-  return [...stack.children]
-    .filter(c => !c.classList.contains('sheet-stack__base')) // the base is what shows behind the sheets, never a sheet (a Card in it is content)
-    .map(c => c.classList.contains('card') ? c : c.querySelector(':scope > .card')).filter(Boolean);
-}
-
-document.addEventListener('click', e => {
-  const stack = e.target.closest('.sheet-stack--tap');
-  if (!stack) return;
-  const cards = carddsStackCards(stack);
-  // the sheet this tap landed in: the member the target sits in, not the
-  // nearest .card (a content card inside an open sheet must not count)
-  const card = cards.find(c => c.contains(e.target));
-  if (e.target.closest('.card__back')) { carddsCloseStack(stack, card); return; }
-  if (card && !cards.some(c => c.classList.contains('is-open'))) {
-    carddsOpenStack(stack, card);
-  }
-});
-
-function carddsOpenStack(stack, card) {
-  const cards = carddsStackCards(stack);
-  const idx = cards.indexOf(card);
-  cards.forEach((c, i) => {
-    c.classList.remove('is-before', 'is-after');
-    c.style.setProperty('--stagger', 0); // only is-before overrides this
-    if (i < idx) {
-      // already behind the tapped card — tuck under the next card's strip,
-      // nearest one first, and let the opening card cover them
-      c.style.setProperty('--stagger', idx - 1 - i);
-      c.classList.add('is-before');
-    } else if (i > idx) {
-      c.classList.add('is-after'); // in front of it, so these must leave
-    }
-  });
-  card.classList.add('is-open');
-}
-
-/* close: the sheet whose back button was tapped, read from the tap itself
-   (a page with several stacks, or a re-render mid-animation, can leave a
-   stale .is-open elsewhere); without one, the stack's open sheet */
-function carddsCloseStack(stack, card) {
-  const cards = carddsStackCards(stack);
-  card = card && cards.includes(card) ? card : cards.find(c => c.classList.contains('is-open'));
-  if (!card) return;
-  const idx = cards.indexOf(card);
-  // phase 1: the after-pack moves back in from below while the opened card
-  // drops into its own slot, passing down over the still-covered before-pack
-  cards.filter((c, i) => i > idx).forEach(c => c.classList.remove('is-after'));
-  card.classList.remove('is-open'); // back button starts its own crop-out now
-  // phase 2: then the before-pack slides back up out from behind it, same
-  // order it tucked away — nearest to the card first
-  const before = cards.filter((c, i) => i < idx);
-  setTimeout(() => before.forEach(c => c.classList.remove('is-before')), CARDDS_STACK_PHASE);
-}
-
-/* ---- sheet (.sheet, sheet.css): peek / half / full ----
-   A sheet is rigid material, like a sheet in the stack (stack.css) — it never changes size, a
-   state is only how far it slid — so this, like the stack code, only ever
-   toggles classes and two custom properties. The CSS renders every state
-   without it; this adds the handle's click and drag, the focus raise, the
-   keyboard room, and one event. Delegated: any sheet on the page, no ids.
-
-   - click / Enter / Space on .sheet__handle TOGGLES the sheet between its
-     own state and peek (Lh 2026-09-16 — never a step-by-step climb). "Its
-     own state" is the last non-peek state it rested in (authored, dragged
-     to, or set), kept in data-sheet-home
-   - data-sheet-states (default "peek half 3q full") lists the states a
-     drag snaps to
-   - drag on the handle writes the offset to --_drag (the CSS adds it to the
-     state's translate) and on release snaps to the nearest state; a move
-     shorter than --sp-2 is a tap. The snap is the one place the sheet's
-     geometry is read, once per release: its height, and the two state
-     tokens — registered in tokens.css so they read back resolved
-   - focus inside a peeked sheet raises it to half (or full, if the sheet has
-     no half) and reveals the control — the sheet's own scroll-padding
-     already knows how much of it slid under the box's edge
-   - the visual viewport's height is published on :root as --kb, the height
-     the on-screen keyboard covers, so the bar (actions.css) and the step
-     (step.css) can stay above it on iOS
-   - "cardds:sheet" (bubbles, detail.state) after every state change
-
-   carddsSheetSet(sheet, state) is the one entry point; an app that sets
-   the state itself calls it rather than swapping classes, so listeners hear. */
-const CARDDS_SHEET_STATES = ['peek', 'half', '3q', 'full'];
-const CARDDS_SHEET_TAP_REM = 0.5; /* = --sp-2: a move shorter than this is a tap, not a drag */
-
-function carddsSheetStates(sheet) {
-  const list = (sheet.dataset.sheetStates || '').split(/\s+/).filter(s => CARDDS_SHEET_STATES.includes(s));
-  return list.length ? list : CARDDS_SHEET_STATES;
-}
-
-function carddsSheetState(sheet) {
-  if (sheet.classList.contains('sheet--away')) return 'away'; // a called sheet not on the screen — a state to set, never one to snap or tap to
-  return CARDDS_SHEET_STATES.find(s => sheet.classList.contains('sheet--' + s)) ?? 'half'; // the CSS default
-}
-
-function carddsSheetSet(sheet, state) {
-  if (state !== 'away' && !CARDDS_SHEET_STATES.includes(state)) return;
-  const was = carddsSheetState(sheet);
-  [...CARDDS_SHEET_STATES, 'away'].forEach(s => sheet.classList.toggle('sheet--' + s, s === state));
-  sheet.inert = state === 'away';
-  /* where a tap from peek returns to: the non-peek state it is going to, or the
-     one it is leaving (an authored state never passed through here before) */
-  const rests = s => s !== 'peek' && s !== 'away';
-  const home = rests(state) ? state : rests(was) ? was : null;
-  if (home) sheet.dataset.sheetHome = home;
-  if (was !== state) sheet.dispatchEvent(new CustomEvent('cardds:sheet', { bubbles: true, detail: { state } }));
-}
-
-/* the click that follows a drag on the same handle is not a tap — the drag
-   already chose the state. Cleared on the next frame, so a drag that ends
-   without a click (pointercancel) cannot eat a later, real one. */
-let carddsSheetSkipClick = null;
-
-document.addEventListener('click', e => {
-  const handle = e.target.closest('.sheet__handle');
-  if (!handle) return;
-  if (handle === carddsSheetSkipClick) { carddsSheetSkipClick = null; return; }
-  const sheet = handle.closest('.sheet');
-  if (!sheet) return;
-  carddsSheetSet(sheet, carddsSheetState(sheet) === 'peek' ? carddsSheetHome(sheet) : 'peek');
-});
-
-/* the state a tap from peek returns to: the last non-peek state it rested in,
-   else the authored one, else the first non-peek state it snaps to */
-function carddsSheetHome(sheet) {
-  const states = carddsSheetStates(sheet);
-  const home = sheet.dataset.sheetHome;
-  if (home && states.includes(home)) return home;
-  const now = carddsSheetState(sheet);
-  return now !== 'peek' ? now : states.find(s => s !== 'peek') ?? 'half';
-}
-
-/* how far the sheet has slid, in px: its rendered top against its resting top
-   at full (the box's padding edge + its own offset). Read from geometry, not
-   from the computed translate — that keeps percentages and calcs as text. */
-function carddsSheetY(sheet) {
-  const box = sheet.offsetParent ?? sheet.parentElement;
-  return sheet.getBoundingClientRect().top - (box.getBoundingClientRect().top + box.clientTop + sheet.offsetTop);
-}
-
-/* drag: where each state rests, in px from the sheet's top at full */
-function carddsSheetStops(sheet) {
-  const cs = getComputedStyle(sheet);
-  const height = sheet.getBoundingClientRect().height;
-  return {
-    full: 0,
-    half: height * (parseFloat(cs.getPropertyValue('--sheet-half')) || 0), // a share of the height
-    '3q': height * (parseFloat(cs.getPropertyValue('--sheet-3q')) || 0),
-    peek: height - (parseFloat(cs.getPropertyValue('--sheet-peek')) || 0),  // a length, resolved
-  };
-}
-
-let carddsSheetDrag = null;
-
-document.addEventListener('pointerdown', e => {
-  const handle = e.target.closest('.sheet__handle');
-  if (!handle || !e.isPrimary || e.button !== 0) return;
-  const sheet = handle.closest('.sheet');
-  if (!sheet) return;
-  const stops = carddsSheetStops(sheet);
-  const states = carddsSheetStates(sheet);
-  const y = carddsSheetY(sheet); // where it is now — mid-slide too, so a grab never jumps
-  carddsSheetDrag = {
-    sheet, handle, states, stops,
-    startY: e.clientY,
-    y0: y,
-    y,
-    min: Math.min(...states.map(s => stops[s])),
-    max: Math.max(...states.map(s => stops[s])),
-    tap: CARDDS_SHEET_TAP_REM * parseFloat(getComputedStyle(document.documentElement).fontSize),
-    moved: false,
-  };
-  handle.setPointerCapture(e.pointerId);
-});
-
-document.addEventListener('pointermove', e => {
-  const d = carddsSheetDrag;
-  if (!d || !e.isPrimary) return;
-  const dy = e.clientY - d.startY;
-  if (!d.moved) {
-    if (Math.abs(dy) < d.tap) return;
-    d.moved = true;
-    d.sheet.classList.add('is-dragging');
-  }
-  d.y = Math.min(Math.max(d.y0 + dy, d.min), d.max); // never above full, never below the lowest state
-  d.sheet.style.setProperty('--_drag', (d.y - d.y0) + 'px');
-});
-
-function carddsSheetRelease() {
-  const d = carddsSheetDrag;
-  if (!d) return;
-  carddsSheetDrag = null;
-  d.sheet.classList.remove('is-dragging');
-  if (!d.moved) return; // a tap: the click that follows cycles the state
-  d.sheet.style.removeProperty('--_drag');
-  const nearest = d.states.reduce((a, b) => Math.abs(d.stops[b] - d.y) < Math.abs(d.stops[a] - d.y) ? b : a);
-  carddsSheetSet(d.sheet, nearest); // same state: --_drag is gone, so it eases back on its own
-  carddsSheetSkipClick = d.handle;
-  requestAnimationFrame(() => { carddsSheetSkipClick = null; });
-}
-document.addEventListener('pointerup', carddsSheetRelease);
-document.addEventListener('pointercancel', carddsSheetRelease);
-
-/* focus in a peeked sheet: a control under the cut cannot be used, so raise
-   the sheet first — to its own state (the one a tap returns to) at least,
-   further if that one has no room for the control under the pinned head (a
-   small phone at a large text size). The browser's own reveal scrolled the body against the
-   peek strip before this fired; start over from the top and let the reveal,
-   with the raised state's scroll-padding, do the least. */
-document.addEventListener('focusin', e => {
-  const sheet = e.target.closest?.('.sheet');
-  if (!sheet || !sheet.classList.contains('sheet--peek') || e.target.closest('.sheet__handle')) return;
-  const body = sheet.querySelector(':scope > .sheet__body');
-  if (body) body.scrollTop = 0;
-  carddsSheetReveal(e.target, carddsSheetHome(sheet));
-});
+/* ---- the sheet is a React component now (src/sheets/Sheet.tsx, 2026-09-21) ----
+   cardds gives components; the app owns their state and wires them to each other. The handle's tap and
+   drag, the focus raise and the keyboard reveal are the Sheet's own behaviour and live in it; what one
+   component does to another — a button calling a sheet, a bar standing down beside one — is the app's.
+   What stays here is the environment: --kb. */
 
 /* --kb: the height of the viewport an on-screen keyboard covers. iOS keeps
    the layout viewport as it was and shrinks only the visual one, so a fixed
@@ -344,51 +17,12 @@ if (window.visualViewport) {
   const publish = () => {
     const covered = vv.scale > 1.01 ? 0 : Math.max(0, Math.round(window.innerHeight - vv.height - vv.offsetTop));
     document.documentElement.style.setProperty('--kb', covered + 'px');
-    /* the keyboard just moved the cut: a sheet's box shrank with the step (or
-       the viewport did), and the control being typed into may now sit under
-       it. Half was enough before the keyboard; it may not be now — raise the
-       sheet as far as its states go and reveal the control. This is the one
-       listener that reads layout, and it reads it after the change it made. */
-    carddsSheetReveal(document.activeElement);
   };
   vv.addEventListener('resize', publish);
   vv.addEventListener('scroll', publish);
   publish();
 }
 
-/* bring a control in a sheet into the visible part — the part of its body
-   between the pinned head and the cut (the box's bottom edge, or the keyboard
-   above it). The sheet goes to the lowest of its states, from the current one
-   (or `atLeast`) upward, whose visible body has room for the control; if none
-   has, to its highest; then the body scrolls the control into view. An app
-   that moves the cut itself (its own keyboard handling, a bar it shows late)
-   calls this with the control; the keyboard listener and the focus raise call
-   it. It reads layout — after the change that moved the cut — and reasons
-   from the resting offsets, so it is right mid-slide too. */
-function carddsSheetReveal(el, atLeast) {
-  const sheet = el?.closest?.('.sheet');
-  if (!sheet || el.closest('.sheet__handle')) return;
-  el = el.closest('.field') ?? el; // the control's box, not the bare input inside a .field
-  const states = carddsSheetStates(sheet);
-  const from = Math.max(states.indexOf(carddsSheetState(sheet)), states.indexOf(atLeast), 0);
-  const stops = carddsSheetStops(sheet);
-  const sheetRect = sheet.getBoundingClientRect();
-  const restTop = sheetRect.top - carddsSheetY(sheet); // where the sheet's top sits at full
-  const bodyTop = (sheet.querySelector(':scope > .sheet__body') ?? sheet).getBoundingClientRect().top - sheetRect.top; // the scrollport, from the sheet's top
-  const box = sheet.parentElement.getBoundingClientRect(); // the box that clips it: .step or .sheet-stage
-  const vv = window.visualViewport;
-  const cut = vv ? Math.min(box.bottom, vv.offsetTop + vv.height) : box.bottom;
-  const foot = sheet.querySelector(':scope > .card__foot'); // the sheet's own button stands on the cut (sheet.css): the control has to clear it too
-  const button = foot?.firstElementChild; // the foot is a layer as tall as the sheet: what the control must clear is its strip
-  const need = (el.closest('.field') ?? el).getBoundingClientRect().height + (button ? box.bottom - button.getBoundingClientRect().top : 0); // from the button's top to the box's bottom edge, where it stands
-  let to = states[states.length - 1];
-  for (let i = from; i < states.length; i++) {
-    if (cut - (restTop + stops[states[i]] + bodyTop) >= need) { to = states[i]; break; }
-  }
-  carddsSheetSet(sheet, to);
-  el.scrollIntoView({ block: 'nearest' });
-}
-
 /* .bleed track: .is-scrolling while it scrolls (and a beat after), so its
    hairline scrollbar shows only while hovered or moving (card.css). */
 const carddsScrollTimers = new WeakMap();
@@ -399,80 +33,3 @@ document.addEventListener('scroll', e => {
   clearTimeout(carddsScrollTimers.get(t));
   carddsScrollTimers.set(t, setTimeout(() => t.classList.remove('is-scrolling'), 700));
 }, true);
-
-/* ---- Modal (layover.css, .sheet-stage--ask): a click on any button in the
-   drawer closes the modal by playing its open animations backwards —
-   Animation.reverse() on every animation in the card, the same keyframes, no
-   closing keyframes to keep in step — then fires "cardds:modal" on the stage
-   (bubbles, detail.answer = the button's data-answer) so the app removes the
-   stage. Reduced motion (no animations): the event fires at once. */
-document.addEventListener('click', e => {
-  const btn = e.target.closest('.modal__drawer button');
-  if (!btn) return;
-  const stage = btn.closest('.sheet-stage--ask');
-  const modal = btn.closest('.modal');
-  if (!stage || !modal || stage.classList.contains('is-closing')) return;
-  stage.classList.add('is-closing');
-  const anims = modal.getAnimations({ subtree: true });
-  anims.forEach(a => a.reverse());
-  Promise.all(anims.map(a => a.finished)).then(() => {
-    stage.dispatchEvent(new CustomEvent('cardds:modal', { bubbles: true, detail: { answer: btn.dataset.answer ?? null } }));
-  });
-});
-
-/* the two calls an app makes are on window: a bundler loads this file as a module, where a top-level
-   function is not a global — and README has always said "call carddsSheetSet(sheet, state)". */
-if (typeof window !== 'undefined') Object.assign(window, { carddsSheetSet, carddsSheetReveal });
-
-/* ---- called sheets (sheet.css): a button in a step's words names a sheet with aria-controls ----
-   (The base offers ways in — sign in · new phone · join — each sheet holds that way's whole form and
-   its own submit on its foot.) A tap on it sends every other sheet of that step away and raises its own to the top state it snaps
-   to (full) — from away, and from peek alike. The step then publishes --sheet-room, the strip the
-   sheet keeps at peek, so the words can scroll their buttons clear of it (step.css); the buttons say
-   aria-expanded. */
-function carddsSheetCall(sheet) {
-  const step = sheet.parentElement;
-  step.querySelectorAll(':scope > .sheet').forEach(s => { if (s !== sheet && carddsSheetState(s) !== 'away') carddsSheetSet(s, 'away'); });
-  const states = carddsSheetStates(sheet);
-  const top = states.includes('full') ? 'full' : states[states.length - 1];
-  const was = carddsSheetState(sheet);
-  if (was !== top) carddsSheetSet(sheet, top);
-  if (was === 'away') sheet.querySelector(':scope > .sheet__handle')?.focus({ preventScroll: true });
-}
-function carddsStepSync(step) {
-  const callers = [...step.querySelectorAll('[aria-controls]')].filter(b => document.getElementById(b.getAttribute('aria-controls'))?.matches('.step > .sheet'));
-  if (!callers.length) return; // a plain step: one sheet, nothing calls it, nothing to publish
-  const on = [...step.querySelectorAll(':scope > .sheet')].find(s => carddsSheetState(s) !== 'away');
-  if (on) step.style.setProperty('--sheet-room', getComputedStyle(on).getPropertyValue('--sheet-peek')); // registered: reads back in px
-  else step.style.removeProperty('--sheet-room');
-  callers.forEach(b => b.setAttribute('aria-expanded', String(carddsSheetState(document.getElementById(b.getAttribute('aria-controls'))) !== 'away')));
-}
-document.addEventListener('click', e => {
-  const caller = e.target.closest('[aria-controls]');
-  const sheet = caller && document.getElementById(caller.getAttribute('aria-controls'));
-  if (sheet && sheet.matches('.step > .sheet')) carddsSheetCall(sheet);
-});
-document.addEventListener('cardds:sheet', e => { const step = e.target.closest?.('.step'); if (step) carddsStepSync(step); });
-
-/* ---- bar guard: a bar is the base's, never in front of a sheet (actions.css, Lh 2026-09-20) ----
-   A sheet on the screen covers the bar and CSS takes the pointer away; `inert` takes the keyboard and
-   the accessibility tree too. Re-checked when a sheet changes state and when the page changes. */
-function carddsPagerGuard() {
-  document.querySelectorAll('.action-bar').forEach((bar) => {
-    const host = bar.parentElement;
-    bar.inert = !!(host && host.querySelector('.step > .sheet:not(.sheet--away)'));
-  });
-}
-if (typeof document !== 'undefined') {
-  document.addEventListener('cardds:sheet', carddsPagerGuard);
-  const start = () => {
-    carddsPagerGuard();
-    let queued = false;
-    new MutationObserver(() => {
-      if (queued) return;
-      queued = true;
-      requestAnimationFrame(() => { queued = false; carddsPagerGuard(); });
-    }).observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['class'] });
-  };
-  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start); else start();
-}

package/css/actions.css

@@ -3,6 +3,14 @@
    topbar, chips, buttons, selects, bottom CTA pack
    ============================================================ */
 
+/* KNOBS (Lh 2026-09-21) — cardds is a framework: a project adjusts ONE component from outside, without touching this file.
+   A knob is a custom property a rule reads WITH ITS DEFAULT AS THE FALLBACK — `padding-inline: var(--btn-pad-x, var(--sp-6))` —
+   so it is declared nowhere: unset, nothing moves (tests/style-snapshot proves it); set in the project's theme.css it retunes
+   that component everywhere; set on any element it retunes the components inside that element only. Names: --<component>-<what>
+   (--btn-pad-x, --chip-bg, --icon-btn-size, --appbar-pad-x); a variant says so (--btn-primary-bg, --chip-on-ink, --icon-btn-sm-size).
+   The sizes that already were root tokens (--btn-h, --chip-h, --bar-h, --header-h, --fab…) are knobs too — set them the same way.
+   Prefer a BASE when the whole system should move (tokens.css); reach for a knob when ONE component should. `npm run knobs` lists them all. */
+
 /* ---- the bars across the top of a screen: one height, whatever they carry ----
    .topbar (screen title) and .appbar (app context) are the same bar with
    different contents, so the height is declared here once rather than left to
@@ -13,8 +21,8 @@
 .topbar, .appbar {
   display: flex;
   align-items: center;
-  gap: var(--sp-3);
-  padding-block: var(--sp-2);
+  gap: var(--bar-gap, var(--sp-3));
+  padding-block: var(--bar-pad-y, var(--sp-2));
   min-height: var(--header-h);
 }
 
@@ -43,9 +51,9 @@
   top: 0;
   max-width: var(--screen-w);
   margin-inline: auto;
-  padding-inline: var(--screen-pad); /* fixed + full-bleed: the screen's own inset, so the bar's contents line up with the title bar under it (Lh 2026-09-15) */
+  padding-inline: var(--appbar-pad-x, var(--screen-pad)); /* fixed + full-bleed: the screen's own inset, so the bar's contents line up with the title bar under it (Lh 2026-09-15) */
   z-index: 40; /* topmost — card animations never cover it */
-  background: var(--surface); /* solid: sliding cards never show through */
+  background: var(--appbar-bg, var(--surface)); /* solid: sliding cards never show through */
 }
 /* fixed, so it covers the top of the screen it sits in — reserve its height
    there, from the same token, the way the bottom bars reserve theirs. The
@@ -62,19 +70,19 @@
 
 /* ---- icon button (round) ---- */
 .icon-btn {
-  width: var(--tap); height: var(--tap);
+  width: var(--icon-btn-size, var(--tap)); height: var(--icon-btn-size, var(--tap));
   flex: none;
-  border-radius: var(--r-chip);
-  border: var(--border-w) solid var(--outline); /* see .btn — same reason */
-  background: var(--action-bg);
-  color: var(--action-ink);
+  border-radius: var(--icon-btn-radius, var(--r-chip));
+  border: var(--border-w) solid var(--icon-btn-border, var(--outline)); /* see .btn — same reason */
+  background: var(--icon-btn-bg, var(--action-bg));
+  color: var(--icon-btn-ink, var(--action-ink));
   display: grid;
   place-items: center;
   font-size: var(--fs-lg);
   line-height: 1;
 }
-.icon-btn--invert { background: var(--accent); color: var(--on-accent); border-color: transparent; }
-.icon-btn--sm { width: var(--tap-sm); height: var(--tap-sm); font-size: var(--fs-title); }
+.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); }
 /* 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)); box-shadow: var(--shadow-float); z-index: 31; }
 
@@ -83,21 +91,21 @@
   /* --outline, not --action-border: same reason as .chip — on a palette where
      --card-1-bg equals --action-bg a transparent border makes a plain button
      invisible on a white card. --primary and --quiet set their own edge. */
-  border: var(--border-w) solid var(--outline);
-  background: var(--action-bg);
-  color: var(--action-ink);
-  border-radius: var(--r-chip);
-  padding: var(--sp-4) var(--sp-6);
+  border: var(--border-w) solid var(--btn-border, var(--outline));
+  background: var(--btn-bg, var(--action-bg));
+  color: var(--btn-ink, var(--action-ink));
+  border-radius: var(--btn-radius, var(--r-chip));
+  padding: var(--btn-pad-y, var(--sp-4)) var(--btn-pad-x, var(--sp-6));
   font: var(--type-label);
-  font-size: var(--fs-md);
+  font-size: var(--btn-font-size, var(--fs-md));
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: var(--sp-2);
+  gap: var(--btn-gap, var(--sp-2));
   min-height: var(--btn-h);
   text-decoration: none; /* .btn works as <a> too */
 }
-.btn--primary { background: var(--accent); color: var(--on-accent); border-color: transparent; }
+.btn--primary { background: var(--btn-primary-bg, var(--accent)); color: var(--btn-primary-ink, var(--on-accent)); border-color: transparent; }
 /* quiet keeps a faint outline so it still reads as a button on colored palettes;
    it is ink on whatever it sits on — inherit, or on the dark slot (card--3) it
    would take the light-card action ink and vanish */
@@ -117,25 +125,25 @@
 .chip {
   display: inline-flex;
   align-items: center;
-  gap: var(--sp-2);
-  border-radius: var(--r-chip);
+  gap: var(--chip-gap, var(--sp-2));
+  border-radius: var(--chip-radius, var(--r-chip));
   /* --outline, not --action-border: a chip is a control, and on a palette
      where --card-1-bg == --action-bg (field, roast, hydro) a transparent
      border makes it invisible on a white card. Same edge fields, checks,
      toggles, tiles and the dropdown already use. */
-  border: var(--border-w) solid var(--outline);
-  background: var(--action-bg);
-  color: var(--action-ink);
-  padding: var(--sp-2) var(--sp-3);
+  border: var(--border-w) solid var(--chip-border, var(--outline));
+  background: var(--chip-bg, var(--action-bg));
+  color: var(--chip-ink, var(--action-ink));
+  padding: var(--chip-pad-y, var(--sp-2)) var(--chip-pad-x, var(--sp-3));
   font: var(--type-label);
-  font-size: var(--fs-sm);
+  font-size: var(--chip-font-size, var(--fs-sm));
   min-height: var(--chip-h);
   text-decoration: none;
   justify-self: start; /* as a grid child it hugs its text, never stretches */
 }
 .dot { width: var(--dot); height: var(--dot); flex: none; border-radius: 50%; background: var(--dot-a); } /* signal dot: chips, legends */
 .dot--b { background: var(--dot-b); }
-.chip--on { background: var(--accent); color: var(--on-accent); border-color: transparent; }
+.chip--on { background: var(--chip-on-bg, var(--accent)); color: var(--chip-on-ink, var(--on-accent)); border-color: transparent; }
 /* dark-slot inversion lives in card.css (.card--3 :is(...)) */
 
 .chip-row { display: flex; gap: var(--sp-2); flex-wrap: wrap; }
@@ -239,14 +247,9 @@
      <button class="icon-btn icon-btn--invert" aria-label="ถัดไป">…</button>
    </div>   — or the same two in an .action-bar__tier--pager under a control  */
 .action-bar--pager { align-items: center; }
-/* The bar belongs to the BASE (Lh, 2026-09-20): it is the move of a page of words — a pager turning
-   them, or one wide button. It is never in front of a sheet: a sheet that is on the screen covers it
-   (step.css, "layers"), a peeking one included, and the button that finishes a sheet is the sheet's own
-   foot (sheet.css). So a pager never works beside a sheet — that screen has work that cannot be walked
-   past — and neither does any other bar: while a sheet is on (only .sheet--away, a sheet not called yet,
-   is not), the bar takes no pointer here and cardds.js makes it inert, so the keyboard cannot reach what
-   the eye cannot see. */
-:has(.step > .sheet:not(.sheet--away)) > .action-bar { pointer-events: none; }
+/* The bar belongs to the BASE: the move of a page of words — a pager turning them, or one wide button. A screen
+   with a sheet finishes on the sheet's own foot instead (sheet.css). Guidance for composing, not a rule the
+   CSS enforces: a component never changes because another one is there. */
 /* the page dots: under the card in a .screen__centre group; tight gaps */
 .pager__at { flex: 0 1 auto; min-width: 0; overflow: hidden; display: flex; align-items: center; gap: var(--sp-1); }
 .pager__at > * {
@@ -276,6 +279,9 @@
 
 /* the first round button sits at the left edge, the last at the right; a skip link between them stays centred */
 :is(.action-bar--pager, .action-bar__tier--pager) > .icon-btn:first-child { margin-right: auto; }
+/* …and whatever goes BETWEEN the two (a "skip" link) stands in the middle: the bar places it, never the link itself */
+:is(.action-bar--pager, .action-bar__tier--pager) > :not(.icon-btn):not(:first-child):not(:last-child) { margin-inline: auto; }
+:is(.action-bar--pager, .action-bar__tier--pager):has(> :nth-child(3)) > .icon-btn:first-child { margin-right: 0; }
 
 /* .screen's default bottom padding is a constant; derive the reserve from the
    bar instead, so a taller button (a longer label, a script with more leading)