@junoput01/junoui 0.7.0 → 0.8.0

package/src/css/touch-surfaces.mjs

@@ -0,0 +1,95 @@
+// ════════════════════════════════════════════════════════════════════════
+//  junoui — the tappable surfaces, declared once
+// ════════════════════════════════════════════════════════════════════════
+//  THE source of truth for "this is one of junoui's own tappable components".
+//  scripts/bundle-css.mjs generates the touch-default rules from it, so the
+//  class names exist in exactly one place and a member cannot be misspelled
+//  into silence.
+//
+//  WHY THIS FILE EXISTS. base.css used to carry two hand-maintained `:where()`
+//  lists, and both had drifted:
+//
+//    - from the CLASSES: `.juno-seg__option` (the shipped class is
+//      `.juno-seg__opt`) and `.juno-list__item` (it is `.juno-list__row`) sat
+//      in them. `:where()` matched nothing, the rule still parsed, every other
+//      member kept working — so every segmented control and every grouped list
+//      row in every consumer kept the ~300ms double-tap delay. Invisible to
+//      lint, to the build and to a screenshot (20260826-024).
+//    - from EACH OTHER: the tap-highlight list was a strict subset of the
+//      touch-action one, missing __overflow, __opt, chip and toggle-btn, with
+//      nothing recording whether that was a decision.
+//
+//  ONE SET, NOT TWO — the open question from docs/conformance-kit.md, decided
+//  on the rules' own rationales rather than by merging them for tidiness. The
+//  tap-highlight rule exists so a UA square "never flashes past a rounded
+//  control on tap"; every name the shorter list omitted is a rounded tappable
+//  (`.juno-chip` and `.juno-pillbar__overflow` are 999px pills,
+//  `.juno-seg__opt` and `.juno-toggle-btn` carry radius-3). The omission has no
+//  stated reason and the rationale covers them, so it was an omission and not a
+//  decision. Both properties answer the same question — "is this one of ours,
+//  and is it tapped?" — and now read the same answer.
+//
+//  Adding a component here is the whole opt-in: state the class once, get both
+//  defaults. test/classes.test.mjs asserts every member is a class some
+//  component file actually defines, so a typo fails the build rather than
+//  going quiet.
+// ════════════════════════════════════════════════════════════════════════
+
+export const TOUCH_SURFACES = [
+  'juno-btn',
+  'juno-chip',
+  'juno-dock__item',
+  'juno-list__row',
+  'juno-menu__item',
+  'juno-pillbar__item',
+  'juno-pillbar__overflow',
+  'juno-seg__opt',
+  'juno-tabs__tab',
+  'juno-toggle-btn',
+  'juno-tree__row',
+  'juno-gizmo__mark',
+  'juno-gizmo__center',
+  'juno-swatch--button',
+  'juno-palette__option',
+];
+
+/** The `:where()` selector list, formatted for the bundle. */
+export function whereList(indent = '') {
+  return `:where(\n${TOUCH_SURFACES.map((c) => `${indent}  .${c}`).join(',\n')}\n${indent})`;
+}
+
+/** The generated touch-default layer.
+ *
+ *  Two rules, one member list. `touch-action` is NOT inside the coarse block:
+ *  a hybrid device (touch laptop, iPad with a trackpad) reports a fine primary
+ *  pointer while still taking touch input, and the property is inert on a
+ *  mouse anyway. The tap highlight only exists on touch, so it is.
+ *
+ *  `:where()` contributes zero specificity by design — these are defaults a
+ *  component or a consumer overrides by simply declaring the property. */
+export function touchDefaultsCss() {
+  return `/* GENERATED from src/css/touch-surfaces.mjs — do not edit here.
+ *
+ * Tappable primitives opt out of double-tap-to-zoom. A browser that still
+ * recognises that gesture has to WAIT after the first tap to see whether a
+ * second one is coming, which reads as a late, mushy tap on exactly the
+ * surfaces a phone UI is built from. \`manipulation\` keeps panning and
+ * pinch-zoom (so the page stays zoomable — never \`none\` here, that would be an
+ * a11y regression) and drops only the double-tap.
+ * Community convention — no primary Apple/WebKit source names it; see
+ * docs/ios-conformance.md. Named components only, so a consumer's own elements
+ * are untouched. See 20260803-038. */
+${whereList()} {
+  touch-action: manipulation;
+}
+
+/* And on touch, kill the UA tap-highlight square so it never flashes past a
+ * rounded control. Consumers were adding this by hand per component; it is a
+ * first-class touch default. See 20260802-020. */
+@media (pointer: coarse) {
+${whereList('  ')} {
+    -webkit-tap-highlight-color: transparent;
+  }
+}
+`;
+}

package/tools/gizmo.mjs

@@ -0,0 +1,144 @@
+// ════════════════════════════════════════════════════════════════════════
+//  junoui/gizmo — bearing language and keyboard traversal for .juno-gizmo
+// ════════════════════════════════════════════════════════════════════════
+//  Two things a stylesheet cannot do, and both are the reason the component
+//  belongs upstream rather than in each app:
+//
+//  1. SAYING THE BEARING. "N" is a letter, not an accessible name, and
+//     "37deg" is a number a screen-reader user has to convert. `bearingLabel`
+//     turns an angle into the words a person would use.
+//  2. ONE FOCUS STOP. The gizmo is a composite widget: Tab reaches it once,
+//     arrow keys move between marks (wrapping, because a compass ring wraps),
+//     Enter activates. Eight separate tab stops for eight compass points is
+//     the thing apps ship and the thing that makes the widget unusable by
+//     keyboard.
+//
+//  Stateless, like junoui/tree: the app owns the camera. This moves focus and
+//  lets the marks' own click handlers fire; it never writes an angle.
+// ════════════════════════════════════════════════════════════════════════
+
+const MARK = '.juno-gizmo__mark';
+
+/** The 16 compass points, as words rather than letters. */
+const POINTS = [
+  'north',
+  'north-north-east',
+  'north-east',
+  'east-north-east',
+  'east',
+  'east-south-east',
+  'south-east',
+  'south-south-east',
+  'south',
+  'south-south-west',
+  'south-west',
+  'west-south-west',
+  'west',
+  'west-north-west',
+  'north-west',
+  'north-north-west',
+];
+
+/** Normalise any angle into [0, 360). */
+export const normalizeBearing = (deg) => ((Number(deg) % 360) + 360) % 360;
+
+/**
+ * A bearing as a person would say it: `37` → `"north-east"`.
+ *
+ * Sixteen points, nearest wins, and the boundaries are half a sector wide so
+ * 348.75..360 and 0..11.25 are both "north" — a naive `Math.round(deg / 22.5)`
+ * yields index 16 near 360 and reads off the end of the table.
+ */
+export function bearingLabel(deg) {
+  const d = normalizeBearing(deg);
+  return POINTS[Math.round(d / 22.5) % 16];
+}
+
+/**
+ * The full spoken description: direction, degrees, and the tilt when there is
+ * one. This is what goes in the live region — the ring itself is decoration to
+ * a screen reader, and a rotating needle announces nothing.
+ */
+export function orientationLabel(heading, pitch = null) {
+  const d = Math.round(normalizeBearing(heading));
+  const base = `Facing ${bearingLabel(d)}, ${d} degrees`;
+  return pitch === null || pitch === undefined
+    ? `${base}.`
+    : `${base}. Tilted ${Math.round(Number(pitch))} degrees.`;
+}
+
+/**
+ * Wire the gizmo as one focus stop. Returns a teardown function.
+ *
+ * Idempotent — enhancing twice replaces the first listener rather than
+ * stacking two, so a framework re-running an effect does not double-move focus
+ * on every keypress.
+ */
+export function enhanceGizmo(root) {
+  if (!root) throw new Error('enhanceGizmo: no root element');
+  root._junoGizmoTeardown?.();
+
+  const marks = () => [...root.querySelectorAll(MARK)].filter((m) => !m.disabled);
+
+  // Seed the roving tabindex: the mark the app marks current, else the first.
+  const seed = () => {
+    const list = marks();
+    if (!list.length) return;
+    for (const m of list) m.tabIndex = -1;
+    (list.find((m) => m.getAttribute('aria-current') === 'true') ?? list[0]).tabIndex = 0;
+  };
+  seed();
+
+  const onKeyDown = (event) => {
+    const list = marks();
+    const at = list.indexOf(event.target.closest(MARK));
+    if (at < 0) return;
+
+    // WRAPPING, because a compass ring wraps. Clamping at the ends is the
+    // behaviour of a slider, and it would make west unreachable from north by
+    // the short way round.
+    const move = (next) => {
+      event.preventDefault();
+      const target = list[(next + list.length) % list.length];
+      for (const m of list) m.tabIndex = -1;
+      target.tabIndex = 0;
+      target.focus();
+    };
+
+    switch (event.key) {
+      case 'ArrowRight':
+      case 'ArrowDown':
+        return move(at + 1);
+      case 'ArrowLeft':
+      case 'ArrowUp':
+        return move(at - 1);
+      case 'Home':
+        return move(0);
+      case 'End':
+        return move(list.length - 1);
+      default:
+        // Enter and Space are the button's own; intercepting them would mean
+        // reimplementing activation, and a <button> already does it right.
+        return;
+    }
+  };
+
+  const onFocusIn = (event) => {
+    const mark = event.target.closest(MARK);
+    if (!mark || !root.contains(mark)) return;
+    // The pointer path: a click focuses a mark without passing through the
+    // keyboard move above, and the invariant has to hold for both.
+    for (const m of marks()) m.tabIndex = -1;
+    mark.tabIndex = 0;
+  };
+
+  root.addEventListener('keydown', onKeyDown);
+  root.addEventListener('focusin', onFocusIn);
+  const teardown = () => {
+    root.removeEventListener('keydown', onKeyDown);
+    root.removeEventListener('focusin', onFocusIn);
+    delete root._junoGizmoTeardown;
+  };
+  root._junoGizmoTeardown = teardown;
+  return teardown;
+}

package/tools/tree.mjs

@@ -0,0 +1,178 @@
+// ════════════════════════════════════════════════════════════════════════
+//  junoui/tree — keyboard traversal for .juno-tree
+// ════════════════════════════════════════════════════════════════════════
+//  A tree without arrow-key traversal and a roving tabindex is a list of
+//  buttons wearing tree roles. That part is behaviour, so no stylesheet can
+//  ship it — and it is also the part apps get wrong, so junoui ships it
+//  rather than only describing it.
+//
+//    import { enhanceTree } from 'junoui/tree';
+//    const stop = enhanceTree(document.querySelector('.juno-tree'));
+//
+//  STATELESS, which is what keeps it inside junoui's "no stateful widgets"
+//  line: it stores nothing. Expansion lives in `aria-expanded` and selection
+//  in `aria-selected`, both on the DOM, both owned by your app — this reads
+//  them, moves focus, and asks you to change them by dispatching events.
+//  Unmount and remount the tree and nothing here needs to know.
+//
+//  WHAT IT DOES NOT DO: it does not expand, collapse, select or reorder. It
+//  dispatches `juno-tree-toggle` and `juno-tree-select` (bubbling, cancelable,
+//  `detail.item`) and leaves the decision to you, because in a real outliner
+//  expanding a node may need to load it.
+//
+//  WAI-ARIA Authoring Practices, Tree View pattern. See
+//  docs/components/tree.md for the full contract and the markup.
+// ════════════════════════════════════════════════════════════════════════
+
+const ITEM = '[role="treeitem"]';
+
+/** Is this item's subtree currently shown? Absent aria-expanded = a leaf. */
+const isExpanded = (el) => el.getAttribute('aria-expanded') === 'true';
+const isBranch = (el) => el.hasAttribute('aria-expanded');
+
+/** Every treeitem the user can currently reach, in visual order.
+ *
+ *  Derived from the DOM each time rather than cached: a tree's shape changes
+ *  under it (lazy children, filtering, a reorder), and a cached list is a
+ *  stale list the moment it does. Cheap — this only runs on a keypress. */
+function visibleItems(root) {
+  return [...root.querySelectorAll(ITEM)].filter((el) => {
+    for (let p = el.parentElement?.closest(ITEM); p; p = p.parentElement?.closest(ITEM)) {
+      if (!isExpanded(p)) return false;
+    }
+    return true;
+  });
+}
+
+/** The row inside an item — the thing that actually takes focus. */
+const rowOf = (item) => item.querySelector(':scope > .juno-tree__row') ?? item;
+
+/** Move the roving tabindex, and focus. Exactly one row is tabbable at a
+ *  time; that is the difference between one Tab stop and one per node.
+ *
+ *  The reset here and the one in `onFocusIn` are REDUNDANT ON PURPOSE, and
+ *  mutation testing is what turned that into a decision: removing either alone
+ *  leaves the invariant holding, because `row.focus()` below fires focusin.
+ *  They cover different entrances — this one the keyboard, that one a pointer
+ *  click, which never passes through here — so neither is dead, and a single
+ *  edit to either cannot leave two rows tabbable. */
+function focusItem(root, item) {
+  for (const other of root.querySelectorAll(ITEM)) rowOf(other).tabIndex = -1;
+  const row = rowOf(item);
+  row.tabIndex = 0;
+  row.focus();
+}
+
+const ask = (item, type) =>
+  item.dispatchEvent(new CustomEvent(type, { bubbles: true, cancelable: true, detail: { item } }));
+
+/**
+ * Wire keyboard traversal on a `.juno-tree`. Returns a teardown function.
+ *
+ * Idempotent: enhancing the same root twice replaces the first listener
+ * rather than stacking two, so a framework that re-runs an effect does not
+ * double-fire every keypress.
+ */
+export function enhanceTree(root) {
+  if (!root) throw new Error('enhanceTree: no root element');
+  root._junoTreeTeardown?.();
+
+  // Seed the roving tabindex: the selected item if there is one, else the
+  // first. Without this every row is tabbable (0) or none is (-1), and both
+  // are wrong.
+  const items = visibleItems(root);
+  if (items.length) {
+    for (const el of root.querySelectorAll(ITEM)) rowOf(el).tabIndex = -1;
+    const seed = items.find((el) => el.getAttribute('aria-selected') === 'true') ?? items[0];
+    rowOf(seed).tabIndex = 0;
+  }
+
+  const onKeyDown = (event) => {
+    const item = event.target.closest(ITEM);
+    if (!item || !root.contains(item)) return;
+
+    const list = visibleItems(root);
+    const at = list.indexOf(item);
+    const go = (next) => {
+      if (!next) return;
+      event.preventDefault();
+      focusItem(root, next);
+    };
+
+    switch (event.key) {
+      case 'ArrowDown':
+        return go(list[at + 1]);
+      case 'ArrowUp':
+        return go(list[at - 1]);
+
+      case 'ArrowRight':
+        // Closed branch → open it. Open branch → into its first child. Leaf →
+        // nothing, which is the pattern's answer and not an oversight.
+        if (isBranch(item) && !isExpanded(item)) {
+          event.preventDefault();
+          ask(item, 'juno-tree-toggle');
+        } else if (isExpanded(item)) {
+          go(list[at + 1]);
+        }
+        return;
+
+      case 'ArrowLeft': {
+        // Open branch → close it. Anything else → out to the parent. This is
+        // what makes a deep tree navigable without a mouse.
+        if (isBranch(item) && isExpanded(item)) {
+          event.preventDefault();
+          ask(item, 'juno-tree-toggle');
+          return;
+        }
+        return go(item.parentElement?.closest(ITEM));
+      }
+
+      case 'Home':
+        return go(list[0]);
+      case 'End':
+        return go(list[list.length - 1]);
+
+      case 'Enter':
+        event.preventDefault();
+        return void ask(item, 'juno-tree-select');
+
+      case ' ':
+        // Space selects; it must not scroll the page out from under the tree.
+        event.preventDefault();
+        return void ask(item, 'juno-tree-select');
+
+      case '*':
+        // Expand every sibling at this level — the pattern's one bulk action.
+        event.preventDefault();
+        for (const sib of item.parentElement?.children ?? []) {
+          if (sib.matches?.(ITEM) && isBranch(sib) && !isExpanded(sib)) {
+            ask(sib, 'juno-tree-toggle');
+          }
+        }
+        return;
+
+      default:
+        return;
+    }
+  };
+
+  // Clicking a row moves the roving tabindex there too, or the next arrow key
+  // jumps back to wherever focus notionally was.
+  const onFocusIn = (event) => {
+    const item = event.target.closest(ITEM);
+    if (item && root.contains(item)) {
+      for (const other of root.querySelectorAll(ITEM)) rowOf(other).tabIndex = -1;
+      rowOf(item).tabIndex = 0;
+    }
+  };
+
+  root.addEventListener('keydown', onKeyDown);
+  root.addEventListener('focusin', onFocusIn);
+  const teardown = () => {
+    root.removeEventListener('keydown', onKeyDown);
+    root.removeEventListener('focusin', onFocusIn);
+    delete root._junoTreeTeardown;
+  };
+  root._junoTreeTeardown = teardown;
+  return teardown;
+}