@jxsuite/ui 0.0.0 → 0.2.0

package/src/behaviors/action-group.ts

@@ -0,0 +1,255 @@
+/**
+ * `jx-action-group`'s behaviour sidecar: the roving caret, and nothing else.
+ *
+ * The group owns focus movement because that is local state no store should hold, and because a
+ * button cannot write about its own position among its siblings. It does NOT own selection: every
+ * real call site keeps the selected value in the host, so in `selects="single"` an arrow does not
+ * write `checked` on a child — it CLICKS the child, exactly as `behaviors/menu.ts` does for Enter,
+ * and the host's own click handler then decides. That leaves one path for pointer and keyboard
+ * instead of two that can disagree.
+ *
+ * What it does beyond reading state is the allowed set (specs/ui.md §2): move focus, and write a
+ * child's own declared `tabindex` prop. It measures nothing, listens on no document, and calls no
+ * platform overlay API. The `tabindex` prop exists precisely so this module never has to reach into
+ * a child's internals to place the caret. The one observer it does own watches the group's OWN
+ * subtree, for the reason `watchRoving` gives.
+ *
+ * @docs extending/ui-kit
+ */
+
+const GROUP = "jx-action-group";
+const ITEM = "jx-action-button";
+
+/** The reactive scope a `jx-action-group` document hands its handlers. */
+export interface ActionGroupState {
+  selects?: string;
+  orientation?: string;
+  [key: string]: unknown;
+}
+
+/** A child action button, with the property accessors its own document installs. */
+type ItemElement = HTMLElement & {
+  tabindex?: string;
+  disabled?: boolean;
+  selected?: boolean;
+  checked?: string;
+};
+
+/** The group an event's `currentTarget` is. */
+function groupOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget;
+  return target instanceof HTMLElement && target.localName === GROUP ? target : null;
+}
+
+/** Whether `group` is the nearest group around `node` — a key inside a nested group is its own. */
+function ownsNode(group: HTMLElement, node: EventTarget | null): boolean {
+  return node instanceof Element && node.closest(GROUP) === group;
+}
+
+/**
+ * The action buttons of one group, in order, excluding those of any group nested inside it.
+ *
+ * A distributed child is a DIRECT child of the group — a `<slot>` leaves no node — but a surface
+ * may still wrap one, so this walks descendants and keeps the ones whose nearest group is this one.
+ * THE SEAM IS NARROWER: the segmented rules in `jx-action-group.json` are direct-child rules, so a
+ * button a surface has wrapped is roved but not joined, and a nested group's buttons are neither.
+ *
+ * @param group The `jx-action-group` element.
+ * @returns Its own action buttons, in document order.
+ */
+export function itemsOf(group: HTMLElement): ItemElement[] {
+  return [...group.querySelectorAll<ItemElement>(ITEM)].filter(
+    (item) => item.closest(GROUP) === group,
+  );
+}
+
+/**
+ * Whether a child cannot act.
+ *
+ * Read from the PROPERTY once the child has upgraded and from the attribute before it has, because
+ * the caret is placed from a lifecycle event and a slotted child's own `connectedCallback` is
+ * async: the group can legitimately be asked to rove either side of that moment. The property is
+ * consulted first where it exists, since a host that wrote `el.disabled = false` over an authored
+ * `disabled` attribute means the property.
+ */
+function isDisabled(item: ItemElement): boolean {
+  return item.disabled === undefined ? item.hasAttribute("disabled") : item.disabled === true;
+}
+
+/** Whether a child is the one the host currently considers chosen — either spelling, as above. */
+function isChosen(item: ItemElement): boolean {
+  if (item.selected === undefined && item.checked === undefined) {
+    return item.hasAttribute("selected") || item.getAttribute("checked") === "true";
+  }
+  return item.selected === true || item.checked === "true";
+}
+
+/** Put the caret ON a child: the focusable node is the button inside it, never the host. */
+function focusControl(item: ItemElement): void {
+  const control = item.querySelector<HTMLElement>('[part="control"]');
+  (control ?? item).focus();
+}
+
+/** Write the roving tabindex: `0` on `caret`, `-1` on every other child, disabled ones included. */
+function writeRoving(items: ItemElement[], caret: ItemElement | null): void {
+  for (const item of items) {
+    item.tabindex = item === caret ? "0" : "-1";
+  }
+}
+
+/**
+ * The child that should hold the caret: the one that already holds it and still can, else the
+ * chosen one, else the first that can act — and null when nothing in the group can.
+ */
+function caretFor(items: ItemElement[]): ItemElement | null {
+  const enabled = items.filter((item) => !isDisabled(item));
+  const held = enabled.find((item) => item.tabindex === "0");
+  return held ?? enabled.find((item) => isChosen(item)) ?? enabled[0] ?? null;
+}
+
+/**
+ * Move the caret to the enabled child at `index`, wrapping at both ends, and focus it.
+ *
+ * @param group The group whose caret is moving.
+ * @param index An index into the group's ENABLED children; negative counts from the end.
+ * @returns The child that took the caret, or null when the group has none that can.
+ */
+export function focusItem(group: HTMLElement, index: number): ItemElement | null {
+  const items = itemsOf(group);
+  const enabled = items.filter((item) => !isDisabled(item));
+  if (enabled.length === 0) {
+    return null;
+  }
+  const at = ((index % enabled.length) + enabled.length) % enabled.length;
+  const caret = enabled[at]!;
+  writeRoving(items, caret);
+  focusControl(caret);
+  return caret;
+}
+
+/**
+ * Give the group exactly one tab stop.
+ *
+ * Without this every child is its own tab stop, because a native `<button>` is focusable with no
+ * `tabindex` at all — so the collapse to one is a WRITE, not the absence of one, and it has to
+ * happen before the reader's first Tab rather than on their first arrow key. The caret stays where
+ * it already is when that child can still take it, else it goes to the chosen child, else to the
+ * first that can act.
+ *
+ * Idempotent, which is what lets it be called from a lifecycle event that may arrive more than
+ * once, and from the observer below on every change to the group.
+ *
+ * @param group The `jx-action-group` element.
+ */
+export function syncRoving(group: HTMLElement): void {
+  const items = itemsOf(group);
+  writeRoving(items, caretFor(items));
+}
+
+/** Whether the group's children already say what {@link syncRoving} would write. */
+function isSettled(group: HTMLElement): boolean {
+  const items = itemsOf(group);
+  const caret = caretFor(items);
+  return items.every((item) => item.tabindex === (item === caret ? "0" : "-1"));
+}
+
+/** Groups already being watched, so a second `jx-ready` does not observe them twice. */
+const watched = new WeakSet<HTMLElement>();
+
+/**
+ * Keep the one-tab-stop invariant as the group's children change.
+ *
+ * Placing the caret once at mount is not enough, and the failure is not cosmetic: a child appended
+ * afterwards arrives with no `tabindex` at all, which is a SECOND tab stop in an element whose
+ * whole purpose is to have one; removing or disabling the child that holds the caret leaves ZERO,
+ * so a toolbar of enabled, operable buttons cannot be reached by Tab at all. Both are the ordinary
+ * life of a Studio toolbar, whose buttons enable and disable with the selection and whose rows are
+ * built from `$switch` and mapped arrays.
+ *
+ * The observer is on the group's own subtree only. It cannot see a `disabled` written as a PROPERTY
+ * rather than an attribute — a mutation record is an attribute record — so a host that flips
+ * `el.disabled = true` on the caret-holder is still asked to let the group hear about it, which an
+ * arrow key, a click or a re-render all do.
+ *
+ * @param group The `jx-action-group` element.
+ */
+function watchRoving(group: HTMLElement): void {
+  if (watched.has(group)) {
+    return;
+  }
+  watched.add(group);
+  /* `isSettled` first, so the observer writes only when the invariant is actually broken: a
+     re-write would be a mutation of its own, and a callback that always writes is a loop. */
+  const observer = new MutationObserver(() => {
+    if (!isSettled(group)) {
+      syncRoving(group);
+    }
+  });
+  observer.observe(group, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["disabled"],
+  });
+}
+
+/**
+ * The group's keyboard contract: the arrow along its own axis moves the caret with wrap, Home and
+ * End go to the ends, and in `selects="single"` the child that takes the caret is CLICKED so the
+ * host hears the same event it would hear from a pointer.
+ *
+ * Enter, Space, the focus ring and `:disabled` are the platform's, on each child's own `<button>`.
+ *
+ * @param {ActionGroupState} state
+ * @param {KeyboardEvent} event
+ */
+export function onGroupKeydown(state: ActionGroupState, event: KeyboardEvent): void {
+  const group = groupOf(event);
+  if (!group || !ownsNode(group, event.target)) {
+    return;
+  }
+  const vertical = state.orientation === "vertical";
+  const enabled = itemsOf(group).filter((item) => !isDisabled(item));
+  const active = enabled.findIndex(
+    (item) =>
+      item === event.target || (event.target instanceof Node && item.contains(event.target)),
+  );
+  let caret: ItemElement | null = null;
+  if (event.key === (vertical ? "ArrowDown" : "ArrowRight")) {
+    caret = focusItem(group, active + 1);
+  } else if (event.key === (vertical ? "ArrowUp" : "ArrowLeft")) {
+    caret = focusItem(group, active === -1 ? -1 : active - 1);
+  } else if (event.key === "Home") {
+    caret = focusItem(group, 0);
+  } else if (event.key === "End") {
+    caret = focusItem(group, -1);
+  } else {
+    return;
+  }
+  event.preventDefault();
+  event.stopPropagation();
+  /* Arrow-to-select, and the reason it is a click rather than a write: `jx-action-button` emits
+     `change` only from inside its own click handler, so a group that wrote `checked` on a child
+     would move the selection with nothing announcing it — the host would never hear the key at
+     all. Clicking is the one path both a pointer and an arrow take. */
+  if (caret && state.selects === "single") {
+    caret.click();
+  }
+}
+
+/**
+ * Collapse the group to one tab stop once it has rendered, and keep it collapsed to one.
+ *
+ * `onMount` is handed the reactive scope and nothing else, so the element announces itself with
+ * `jx-ready` — the kit's existing readiness event — and this reads the host off that event.
+ *
+ * @param {ActionGroupState} _state
+ * @param {Event} event
+ */
+export function onGroupReady(_state: ActionGroupState, event: Event): void {
+  const group = groupOf(event);
+  if (group) {
+    syncRoving(group);
+    watchRoving(group);
+  }
+}

package/src/behaviors/color-area.ts

@@ -0,0 +1,303 @@
+/**
+ * `jx-color-area`'s behaviour sidecar: the pointer maths, the second axis's arrow keys, and the one
+ * place the family's event contract is written from.
+ *
+ * WHY THERE ARE TWO NATIVE RANGES INSIDE A SQUARE. A saturation/brightness field is a `slider` in
+ * two dimensions, and ARIA has no such role: the APG's answer, and the platform's, is TWO sliders.
+ * So the element is two real `<input type="range">`s — one per axis — and everything a slider owes
+ * a reader comes from them rather than from an authored imitation: `role="slider"`, the focus, the
+ * tab stops, `aria-valuemin`/`max`/`now` derived from the control's own `min`, `max` and `value`,
+ * the announcement when the value moves, form-control disabled semantics, and the along-axis arrow
+ * keys with their Home, End, PageUp and PageDown. They are transparent and `pointer-events: none`
+ * rather than `display: none`, because a control the platform has hidden is a control the
+ * accessibility tree does not have.
+ *
+ * WHAT IS LEFT FOR THIS FILE IS EXACTLY WHAT A SLIDER CANNOT KNOW.
+ *
+ * 1. **The other axis.** A range knows one dimension, so ArrowUp on the saturation control is the
+ *    platform stepping SATURATION — which, to a reader looking at one square with one thumb in it,
+ *    is the thumb moving sideways when they pressed up. The cross-axis keys are cancelled here and
+ *    applied to the axis the reader meant. The along-axis keys are NOT touched: those are the
+ *    platform's, they already clamp and snap, and two implementations of one key is two answers.
+ * 2. **Ten steps.** `Shift`+Arrow is the kit's coarse step, as it is on `jx-number-field`, and the
+ *    platform has no such gesture on a range.
+ * 3. **The pointer.** A square has no native drag, so pointerdown, move and up are read against the
+ *    track's own box. WCAG 2.5.7 is met by the ranges rather than by the drag: every value the
+ *    pointer can reach is reachable with the arrow keys, and a single click with no movement sets
+ *    the value outright, so no dragging motion is REQUIRED for any of it.
+ *
+ * THE ELEMENT IS THE SINGLE SOURCE OF EVENTS, and this is the one place in the kit where a native
+ * control's own `input` and `change` are stopped. `jx-number-field` lets them bubble because its
+ * control's value IS its value; here the two controls hold half a coordinate each, so a host that
+ * heard them would read `e.target.value` as `"64"` and have no way to know which axis it was. Every
+ * path — a key, a drag, a click — therefore dispatches `input` and `change` FROM THE HOST, whose
+ * own `hue`, `saturation` and `brightness` props are the whole answer. One `e.target`, one
+ * reading.
+ *
+ * @docs extending/ui-kit
+ */
+
+import { snapToStep } from "../color.ts";
+
+/** The tag this sidecar belongs to. */
+const HOST = "jx-color-area";
+
+/** The reactive scope a `jx-color-area` document hands its handlers. */
+export interface ColorAreaState {
+  /** The hue the square is drawn under, 0-360. Read, never written here. */
+  hue: number;
+  /** The horizontal axis, 0-100. */
+  saturation: number;
+  /** The vertical axis, 0-100, measured upward from the bottom edge. */
+  brightness: number;
+  /** The grid both axes move on. */
+  step: number;
+  /** Whether the element refuses to move. */
+  disabled: boolean;
+  [key: string]: unknown;
+}
+
+/** Which state key each axis writes. `x` is saturation and `y` is brightness. */
+const AXIS_KEY = { x: "saturation", y: "brightness" } as const;
+
+/** The axis a key belongs to when nothing cancels it. */
+const KEY_AXIS: Readonly<Record<string, "x" | "y">> = {
+  ArrowDown: "y",
+  ArrowLeft: "x",
+  ArrowRight: "x",
+  ArrowUp: "y",
+};
+
+/** Which way each arrow moves its axis. Up and Right increase; the square's y is measured upward. */
+const KEY_SIGN: Readonly<Record<string, number>> = {
+  ArrowDown: -1,
+  ArrowLeft: -1,
+  ArrowRight: 1,
+  ArrowUp: 1,
+};
+
+/** The hosts with a pointer down on them. Off to the side, because a drag is not element state. */
+const dragging = new WeakSet<HTMLElement>();
+
+/** The `jx-color-area` an event is being handled on. */
+function hostOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget;
+  return target instanceof HTMLElement && target.localName === HOST ? target : null;
+}
+
+/** The element's own gradient box, which is what a pointer coordinate is measured against. */
+function trackOf(host: HTMLElement): HTMLElement | null {
+  return host.querySelector<HTMLElement>('[part="track"]');
+}
+
+/** The axis a node is, read off its own `part`; null for anything that is neither range. */
+function axisOf(node: EventTarget | null): "x" | "y" | null {
+  if (!(node instanceof Element)) {
+    return null;
+  }
+  const part = node.getAttribute("part");
+  return part === "x" || part === "y" ? part : null;
+}
+
+/** The step, never zero: a zero step would snap every coordinate onto the minimum. */
+function stepOf(state: ColorAreaState): number {
+  const step = Number(state.step);
+  return Number.isFinite(step) && step > 0 ? step : 1;
+}
+
+/**
+ * Say the value moved, from the HOST, in the platform's own names.
+ *
+ * @param host The element.
+ * @param names Which of `input` and `change` to dispatch, in order.
+ */
+function announce(host: HTMLElement, ...names: string[]): void {
+  for (const name of names) {
+    host.dispatchEvent(new Event(name, { bubbles: true }));
+  }
+}
+
+/**
+ * Write one axis, snapped to the grid and held inside 0-100.
+ *
+ * @param state The element's reactive scope.
+ * @param axis Which axis.
+ * @param value The value before snapping.
+ * @returns Whether the write moved anything, so a no-op key dispatches nothing.
+ */
+function writeAxis(state: ColorAreaState, axis: "x" | "y", value: number): boolean {
+  const key = AXIS_KEY[axis];
+  const next = snapToStep(value, stepOf(state), 0, 100);
+  if (state[key] === next) {
+    return false;
+  }
+  state[key] = next;
+  return true;
+}
+
+/**
+ * The inner range's `input`: mirror the axis it holds, and re-say it from the host.
+ *
+ * The native event is stopped here. See the file's header: two controls holding half a coordinate
+ * each cannot both be `e.target` for one value.
+ *
+ * @param state The element's reactive scope.
+ * @param event The range's own input event.
+ */
+export function onAreaAxisInput(state: ColorAreaState, event: Event): void {
+  const host = hostOf(event);
+  const axis = axisOf(event.target);
+  if (!host || !axis) {
+    return;
+  }
+  event.stopPropagation();
+  writeAxis(state, axis, Number((event.target as HTMLInputElement).value));
+  announce(host, "input");
+}
+
+/**
+ * The inner range's `change`: the same stop, and the commit re-said from the host.
+ *
+ * @param state The element's reactive scope.
+ * @param event The range's own change event.
+ */
+export function onAreaAxisChange(state: ColorAreaState, event: Event): void {
+  const host = hostOf(event);
+  const axis = axisOf(event.target);
+  if (!host || !axis) {
+    return;
+  }
+  event.stopPropagation();
+  writeAxis(state, axis, Number((event.target as HTMLInputElement).value));
+  announce(host, "change");
+}
+
+/**
+ * The two keyboard jobs a range cannot do for itself: the OTHER axis, and ten steps.
+ *
+ * An along-axis arrow with no Shift returns untouched, so the platform's own step, clamp and
+ * announcement run exactly as they would on any range. Everything this does handle is cancelled, so
+ * the two never both act on one press.
+ *
+ * @param state The element's reactive scope.
+ * @param event The keydown, from either range.
+ */
+export function onAreaKeydown(state: ColorAreaState, event: KeyboardEvent): void {
+  const host = hostOf(event);
+  const focused = axisOf(event.target);
+  if (!host || !focused || state.disabled === true) {
+    return;
+  }
+  const axis = KEY_AXIS[event.key];
+  if (!axis) {
+    return;
+  }
+  if (axis === focused && !event.shiftKey) {
+    return;
+  }
+  event.preventDefault();
+  event.stopPropagation();
+  const delta = stepOf(state) * (event.shiftKey ? 10 : 1) * (KEY_SIGN[event.key] ?? 0);
+  if (writeAxis(state, axis, Number(state[AXIS_KEY[axis]]) + delta)) {
+    /* Both names: a keystroke on a slider is a move AND a commit, which is what the platform's own
+       arrow does on the axis it owns. A key that changed nothing says nothing. */
+    announce(host, "input", "change");
+  }
+}
+
+/**
+ * Read a pointer coordinate into both axes.
+ *
+ * @param state The element's reactive scope.
+ * @param host The element.
+ * @param event The pointer event.
+ * @returns Whether anything moved.
+ */
+function fromPointer(state: ColorAreaState, host: HTMLElement, event: PointerEvent): boolean {
+  const track = trackOf(host);
+  if (!track) {
+    return false;
+  }
+  const box = track.getBoundingClientRect();
+  if (box.width <= 0 || box.height <= 0) {
+    /* An unlaid-out box would put every coordinate at the origin, which is a colour the reader did
+       not ask for. Saying nothing is the right answer to a question with no geometry in it. */
+    return false;
+  }
+  const x = writeAxis(state, "x", ((event.clientX - box.left) / box.width) * 100);
+  const y = writeAxis(state, "y", (1 - (event.clientY - box.top) / box.height) * 100);
+  return x || y;
+}
+
+/**
+ * A pointer went down on the square: take the value, take the capture, and put the caret on the
+ * horizontal range so the keyboard carries on from where the pointer stopped.
+ *
+ * @param state The element's reactive scope.
+ * @param event The pointer event.
+ */
+export function onAreaPointerDown(state: ColorAreaState, event: PointerEvent): void {
+  const host = hostOf(event);
+  if (!host || state.disabled === true) {
+    return;
+  }
+  event.preventDefault();
+  dragging.add(host);
+  const track = trackOf(host);
+  if (track && typeof track.setPointerCapture === "function") {
+    /* Capture on the TRACK, so a drag that leaves the square keeps arriving here rather than
+       stopping wherever the pointer crossed the edge. */
+    try {
+      track.setPointerCapture(event.pointerId);
+    } catch {
+      /* A synthetic pointer has nothing to capture and Chrome throws; see split.ts. */
+    }
+  }
+  host.querySelector<HTMLElement>('[part="x"]')?.focus();
+  if (fromPointer(state, host, event)) {
+    announce(host, "input");
+  }
+}
+
+/**
+ * The drag itself. Nothing happens without a pointer down first, so a hover moves no colour.
+ *
+ * @param state The element's reactive scope.
+ * @param event The pointer event.
+ */
+export function onAreaPointerMove(state: ColorAreaState, event: PointerEvent): void {
+  const host = hostOf(event);
+  if (!host || !dragging.has(host)) {
+    return;
+  }
+  if (fromPointer(state, host, event)) {
+    announce(host, "input");
+  }
+}
+
+/**
+ * The pointer came up, or the gesture was taken away: the value is committed once.
+ *
+ * `change` is dispatched even when the last move changed nothing, because the commit is about the
+ * gesture ending rather than about the final pixel — a click that lands exactly on the current
+ * value is still the reader choosing it. Nothing is read out of the scope: every value the gesture
+ * produced was written on the way here.
+ *
+ * @param _state The element's reactive scope, unread.
+ * @param event The pointer event.
+ */
+export function onAreaPointerUp(_state: ColorAreaState, event: PointerEvent): void {
+  const host = hostOf(event);
+  if (!host || !dragging.delete(host)) {
+    return;
+  }
+  const track = trackOf(host);
+  if (
+    track &&
+    typeof track.releasePointerCapture === "function" &&
+    track.hasPointerCapture?.(event.pointerId)
+  ) {
+    track.releasePointerCapture(event.pointerId);
+  }
+  announce(host, "change");
+}