@usableapp/cardds 0.1.0

package/cardds.js

@@ -0,0 +1,473 @@
+/* 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');
+  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();
+});
+
+/* 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);
+}
+
+/* ---- card heading squeeze ----
+   A skeleton head's heading has a budget of two lines (card.css, "Skeleton
+   head"). When the words need more, step --squeeze down — the CSS multiplies
+   the level's own size by it — until it fits two lines, or stop at the floor
+   and let the CSS clamp hold it to three.
+
+   Stack heads are skipped: a peek is one line at its own size. stack.css opts
+   those same cards out of the clamp, so the two files agree on what a skeleton
+   head is — change one, change the other.
+
+   What causes a measure:
+   - a ResizeObserver on each heading. A heading only needs a different squeeze
+     when its WIDTH changes, so that is what is watched: window resize, a
+     container that moved, display:none -> shown, all arrive here. Our own
+     font-size change is not a width change, so it does not come back round.
+   - a MutationObserver that only REGISTERS headings added later. It reads
+     added nodes, never the layout, so a host app that re-renders constantly
+     pays a node scan instead of a measuring pass over the page.
+   - document.fonts.ready, once: a font swap changes glyph metrics at an
+     unchanged width, which is the one case the ResizeObserver cannot see.
+   - a "cardds:layout" event, listened for in the CAPTURE phase so it arrives
+     whether or not the app sets bubbles: true. */
+const CARDDS_SQUEEZE_STEPS = [0.94, 0.88, 0.82];
+const CARDDS_HEAD_SEL = '.card__head :is(h1, h2, h3)';
+
+/* a heading in a card's own head — not one in a sheet-stack peek (stack.css).
+   A sheet is read the way the stack reads it (carddsStackCards): a direct
+   child, or one wrapper down — a host that wraps each sheet must not turn its
+   one-line peek into a squeezed skeleton head. */
+function carddsIsSkeletonHead(h) {
+  const card = h.closest('.card__head')?.parentElement;
+  if (!card) return false;
+  const stack = card.parentElement?.closest('.sheet-stack');
+  return !stack || !carddsStackCards(stack).includes(card);
+}
+
+function carddsSqueezeOne(h) {
+  h.style.removeProperty('--squeeze');
+  if (h.getClientRects().length === 0) return; // not rendered — nothing to measure
+  /* line-height is read again at every step: --squeeze scales it too, so a
+     count taken against the unsqueezed value is out by exactly the step */
+  const lines = () => {
+    const lh = parseFloat(getComputedStyle(h).lineHeight);
+    return lh ? Math.round(h.scrollHeight / lh) : 0;
+  };
+  if (lines() <= 2) return;
+  for (const step of CARDDS_SQUEEZE_STEPS) {
+    h.style.setProperty('--squeeze', step);
+    if (lines() <= 2) break;
+  }
+}
+
+function carddsSqueeze(root = document) {
+  root.querySelectorAll(CARDDS_HEAD_SEL).forEach(h => {
+    if (carddsIsSkeletonHead(h)) carddsSqueezeOne(h);
+  });
+}
+
+/* measuring is batched into one frame, and the width we settle at is recorded
+   so the resize our own font-size change causes is recognised, not re-run */
+const carddsHeadWidth = new WeakMap();
+const carddsPending = new Set();
+let carddsRaf = 0;
+
+function carddsFlush() {
+  carddsRaf = 0;
+  const batch = [...carddsPending];
+  carddsPending.clear();
+  batch.forEach(carddsSqueezeOne);
+  batch.forEach(h => carddsHeadWidth.set(h, h.getBoundingClientRect().width));
+}
+
+const carddsHeadResize = new ResizeObserver(entries => {
+  for (const e of entries) {
+    const w = e.target.getBoundingClientRect().width;
+    if (Math.abs((carddsHeadWidth.get(e.target) ?? -1) - w) < 0.5) continue;
+    carddsHeadWidth.set(e.target, w);
+    carddsPending.add(e.target);
+  }
+  if (carddsPending.size && !carddsRaf) carddsRaf = requestAnimationFrame(carddsFlush);
+});
+
+function carddsWatch(root = document) {
+  root.querySelectorAll(CARDDS_HEAD_SEL).forEach(h => {
+    if (carddsIsSkeletonHead(h)) carddsHeadResize.observe(h);
+  });
+}
+
+carddsWatch();
+(document.fonts ? document.fonts.ready : Promise.resolve()).then(() => carddsSqueeze());
+
+new MutationObserver(records => {
+  for (const r of records) {
+    for (const n of r.addedNodes) {
+      if (n.nodeType !== 1) continue;
+      if (n.matches(CARDDS_HEAD_SEL) && carddsIsSkeletonHead(n)) carddsHeadResize.observe(n);
+      else carddsWatch(n);
+    }
+  }
+}).observe(document.documentElement, { childList: true, subtree: true });
+
+document.addEventListener('cardds:layout', e => {
+  const root = e.target instanceof Element ? e.target : document;
+  carddsWatch(root);
+  carddsSqueeze(root);
+}, true);
+
+/* ---- 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 cycles the states named in
+     data-sheet-states (default "peek half full"), wrapping round
+   - 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', '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) {
+  return CARDDS_SHEET_STATES.find(s => sheet.classList.contains('sheet--' + s)) ?? 'half'; // the CSS default
+}
+
+function carddsSheetSet(sheet, state) {
+  if (!CARDDS_SHEET_STATES.includes(state)) return;
+  const was = carddsSheetState(sheet);
+  CARDDS_SHEET_STATES.forEach(s => sheet.classList.toggle('sheet--' + s, s === state));
+  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;
+  const states = carddsSheetStates(sheet);
+  carddsSheetSet(sheet, states[(states.indexOf(carddsSheetState(sheet)) + 1) % states.length]);
+});
+
+/* 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
+    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 the state after peek 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 states = carddsSheetStates(sheet);
+  const body = sheet.querySelector(':scope > .sheet__body');
+  if (body) body.scrollTop = 0;
+  carddsSheetReveal(e.target, states[states.indexOf('peek') + 1] ?? states[states.length - 1]);
+});
+
+/* --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
+   bar and the sheet's control disappear behind the keyboard unless they
+   read this; Android with interactive-widget=resizes-content (set it in the
+   viewport meta) shrinks the layout viewport, and this stays 0. A pinch zoom
+   also shrinks the visual viewport, and is not a keyboard — ignored. */
+if (window.visualViewport) {
+  const vv = 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 need = el.getBoundingClientRect().height;
+  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' });
+}