@jxsuite/ui 0.0.0 → 0.1.0

package/src/behaviors/combobox.ts

@@ -0,0 +1,474 @@
+/**
+ * `jx-combobox`'s sidecar: the keyboard a field owns over a list it does not contain, and the two
+ * measurements that place the panel.
+ *
+ * The element is the composed half of the pair `jx-listbox` and `jx-option` are the primitive half
+ * of. It brings one native `<input role="combobox">`, a `jx-popover` holding a `jx-listbox` of its
+ * own rows, and the APG's editable-combobox contract over the two — reaching the list only through
+ * `aria-controls` and `aria-activedescendant`, which are id references and therefore only resolve
+ * because the kit is light DOM (specs/ui.md §2 principle 2).
+ *
+ * Four decisions here are decisions rather than defaults, and each is a thing a second answer would
+ * be worse at:
+ *
+ * 1. **The element filters NOTHING.** `options` is the list that will be drawn, not a corpus to match
+ *    against. Studio's palettes rank with a fuzzy scorer that knows about modes, recents and
+ *    chords; `ai-credentials-form` shows a catalogue fetched from a provider. An element with its
+ *    own opinion about matching would be a second ranking every one of them had to defeat, so the
+ *    host re-answers `options` on `input` and this module never reads the text to decide a row.
+ * 2. **Typing highlights nothing.** After a keystroke `activeIndex` is `-1`, so Enter commits what the
+ *    READER typed until they arrow onto a row. That is what makes `allowsCustomValue` mean
+ *    something — the reported gap is a model id field whose catalogue is "a set of suggestions,
+ *    never a whitelist" — and it is equally right for a closed list, which refuses the text on
+ *    commit rather than silently answering a different question.
+ * 3. **Home and End are left alone.** They belong to the text caret in the field, which is where the
+ *    reader's cursor actually is. The APG gives them to the list only in the variant where the
+ *    LISTBOX has focus, and this one never does.
+ * 4. **A refused value is refused ON THE COMMIT, and the native `change` never escapes.** Reverting
+ *    after letting the input's own `change` bubble would deliver two committed edits for one
+ *    gesture — the same defect `jx-textfield`'s clear button cancels a `pointerdown` to avoid. So
+ *    the refusal stops the inner event at the input and dispatches one `change` from the HOST, and
+ *    a host reading `e.target.value` reads the value that stands either way.
+ *
+ * Two more are about a list that arrives LATE, which is what a fetched catalogue is:
+ *
+ * 5. **A list opened by a gesture lands on the row the field already holds.** The chevron and
+ *    Alt+ArrowDown put the caret on the row whose value the field holds, so a catalogue that
+ *    arrived after the reader typed `gpt-4o` shows it as THEIR row when they open the list, rather
+ *    than a list with nothing chosen. A plain arrow still enters at an end, and a keystroke still
+ *    lands on nothing (decision 2).
+ * 6. **An empty list is not shown.** With no rows there is nothing to open: the chevron is not drawn
+ *    (`data-empty`), and neither typing nor an arrow shows the panel, so a field whose catalogue
+ *    has not arrived is a text field until it does — and Escape reaches the dialog around it
+ *    instead of closing a panel nobody could see. The cost is stated: a host that re-answers
+ *    `options` on `input` and whose PREVIOUS answer was empty sees the list on the keystroke after
+ *    the one that produced rows, because the sidecar's own `input` handler runs before the host's;
+ *    a host that wants it sooner calls {@link openList} itself once it has answered.
+ *
+ * @docs extending/ui-kit
+ */
+
+import { close, openAt } from "./popover.ts";
+
+/** A row as the element draws it. */
+export interface ComboboxRow {
+  /** What the row commits; also what it draws, unless it carries a `label`. */
+  value: string;
+  /** What the row draws. */
+  label?: string;
+  /** A muted note at the end of the row. */
+  description?: string;
+  /** A row that cannot be picked. */
+  disabled?: boolean;
+  /** The face the row's label draws in. */
+  face?: string;
+  /** A colour chip before the label. */
+  swatch?: string;
+  /** A border-style rule before the label. */
+  line?: string;
+  weight?: string;
+  slant?: string;
+  variant?: string;
+  transform?: string;
+  decoration?: string;
+}
+
+/** The reactive scope a `jx-combobox` document hands its handlers. */
+export interface ComboboxState {
+  value?: string;
+  committed?: string;
+  options?: ComboboxRow[];
+  open?: boolean;
+  activeIndex?: number;
+  allowsCustomValue?: boolean;
+  disabled?: boolean;
+  readonly?: boolean;
+  uid?: string;
+  [key: string]: unknown;
+}
+
+const HOST = "jx-combobox";
+
+/** How many stems have been minted, so no two instances share one. */
+let minted = 0;
+
+/** The `jx-combobox` an event is being handled inside, whichever node bound the handler. */
+function comboboxOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget;
+  return target instanceof Element ? target.closest<HTMLElement>(HOST) : null;
+}
+
+/** The element's own text control. */
+export function inputOf(host: HTMLElement): HTMLInputElement | null {
+  return host.querySelector<HTMLInputElement>('input[part="input"]');
+}
+
+/** The element's own panel. */
+function panelOf(host: HTMLElement): HTMLElement | null {
+  return host.querySelector<HTMLElement>('[part="popup"]');
+}
+
+/** The rows the element was handed, whatever it was handed. */
+function rowsOf(state: ComboboxState): ComboboxRow[] {
+  return Array.isArray(state.options) ? state.options : [];
+}
+
+/** Dispatch the element's own events, so `e.target` is the element and `e.target.value` its value. */
+function announce(host: HTMLElement, ...names: string[]): void {
+  for (const name of names) {
+    host.dispatchEvent(new Event(name, { bubbles: true }));
+  }
+}
+
+/** Whether the element may open its list at all. */
+function operable(state: ComboboxState): boolean {
+  return state.disabled !== true && state.readonly !== true;
+}
+
+/**
+ * Show the panel under the field.
+ *
+ * The coordinates are written before the panel is shown, which is what `jx-popover` asks of whoever
+ * opens it: its own toggle handler then clamps a real position into the viewport rather than the
+ * origin.
+ *
+ * The source is the HOST rather than the inner input, and both halves of that matter. `matchWidth`
+ * measures whatever the toggle names as its source, and the list has to be as wide as the FIELD —
+ * the text box plus the chevron beside it — rather than as wide as the text box alone. And light
+ * dismissal treats a popover's invoker subtree as part of the panel, so naming the host is what
+ * keeps a press on the input, or on the chevron, from dismissing the list it just opened.
+ *
+ * @param host The `jx-combobox` element.
+ */
+export function openList(host: HTMLElement): void {
+  const panel = panelOf(host);
+  if (!panel) {
+    return;
+  }
+  const box = host.getBoundingClientRect();
+  const placed = panel as HTMLElement & { x: number; y: number };
+  placed.x = Math.round(box.left);
+  placed.y = Math.round(box.bottom);
+  openAt(panel, host);
+}
+
+/** Hide the panel. `open` follows the platform's own toggle, never a write. */
+export function closeList(host: HTMLElement): void {
+  const panel = panelOf(host);
+  if (panel) {
+    close(panel);
+  }
+}
+
+/**
+ * Show the list, if there is anything to list.
+ *
+ * Every opener the element owns goes through here rather than {@link openList}: a list with no rows
+ * is a bordered box with nothing in it, and an `aria-expanded` field over an empty listbox is a
+ * panel a reader would have to Escape out of without ever seeing it.
+ *
+ * @param state The element's reactive scope.
+ * @param host The `jx-combobox` element.
+ * @returns Whether the list was shown.
+ */
+function showList(state: ComboboxState, host: HTMLElement): boolean {
+  if (!operable(state) || rowsOf(state).length === 0) {
+    return false;
+  }
+  openList(host);
+  return true;
+}
+
+/**
+ * The row a list opened by a GESTURE lands on: the one the field's value already names, or none.
+ *
+ * Compared through {@link rowFor}, so the row is found in whatever case the reader typed it, and a
+ * disabled row is not a landing — the caret could not have arrowed onto it either.
+ *
+ * @param state The element's reactive scope.
+ * @returns The index of that row, or -1.
+ */
+export function landingIndex(state: ComboboxState): number {
+  const rows = rowsOf(state);
+  const row = rowFor(rows, String(state.value ?? ""));
+  return row && row.disabled !== true ? rows.indexOf(row) : -1;
+}
+
+/**
+ * The next row a caret may land on, stepping over disabled rows and wrapping at both ends.
+ *
+ * `-1` in means "nothing is highlighted", and the first step from there lands on an end rather than
+ * beside one: down goes to the first row, up to the last. `-1` out means there is nowhere to go.
+ *
+ * @param rows The rows as they are drawn.
+ * @param from The index the caret is on, or -1.
+ * @param step +1 or -1.
+ * @returns The index to move to, or -1 when no row can take the caret.
+ */
+export function nextIndex(rows: ComboboxRow[], from: number, step: number): number {
+  const start = from < 0 ? (step > 0 ? -1 : 0) : from;
+  for (const offset of rows.keys()) {
+    const at = (((start + step * (offset + 1)) % rows.length) + rows.length) % rows.length;
+    if (rows[at]?.disabled !== true) {
+      return at;
+    }
+  }
+  return -1;
+}
+
+/**
+ * The row a piece of text names, compared without case.
+ *
+ * A picker normalises what the reader typed to the row's own spelling — `GPT-4O` commits as the
+ * catalogue's `gpt-4o` — because the row is what the value means and the casing is not the reader's
+ * to decide. Only `value` is compared: `label` is what a row DRAWS, and a list whose labels were
+ * also accepted would make two strings commit the same row and neither of them what is stored.
+ *
+ * @param rows The rows as they are drawn.
+ * @param text The text in the field.
+ * @returns The row, or null when no row holds that value.
+ */
+export function rowFor(rows: ComboboxRow[], text: string): ComboboxRow | null {
+  const wanted = text.toLowerCase();
+  return rows.find((row) => String(row.value).toLowerCase() === wanted) ?? null;
+}
+
+/**
+ * Take a row: its value into the field, the list closed, the caret back where the reader was, and
+ * one `input`/`change` pair from the element.
+ *
+ * @param state The element's reactive scope.
+ * @param host The `jx-combobox` element.
+ * @param row The row to commit.
+ */
+function commitRow(state: ComboboxState, host: HTMLElement, row: ComboboxRow): void {
+  const value = String(row.value);
+  state.value = value;
+  state.committed = value;
+  state.activeIndex = -1;
+  closeList(host);
+  inputOf(host)?.focus();
+  announce(host, "input", "change");
+}
+
+/**
+ * Mint the element's id stem and record the value it starts out holding.
+ *
+ * The stem is what every id reference in the document is built from — the panel's, the listbox's
+ * and one per row — so a consumer writes none of them and two comboboxes on one surface cannot
+ * collide. A document cannot mint it: the closed operator set has no counter and no identity, which
+ * is the sidecar case specs/ui.md §3.2 sanctions.
+ *
+ * @param state The element's reactive scope.
+ * @param _host The `jx-combobox` element.
+ */
+export function mountCombobox(state: ComboboxState, _host: HTMLElement): void {
+  minted += 1;
+  state.uid = `jx-combobox-${minted}`;
+  state.committed = String(state.value ?? "");
+}
+
+/**
+ * The reader typing: the text becomes the value, nothing is highlighted, and the list opens.
+ *
+ * @param state The element's reactive scope.
+ * @param event The control's own `input`, which goes on to bubble out of the element unchanged.
+ */
+export function onComboboxInput(state: ComboboxState, event: Event): void {
+  const host = comboboxOf(event);
+  const control = event.target;
+  if (!host || !(control instanceof HTMLInputElement)) {
+    return;
+  }
+  state.value = control.value;
+  state.activeIndex = -1;
+  showList(state, host);
+}
+
+/**
+ * The panel's own toggle: the one source of truth for `open`.
+ *
+ * A list light-dismissed by a click outside, or closed with Escape, moves this exactly as a call to
+ * {@link closeList} does — which is why `open` is mirrored rather than written.
+ *
+ * @param state The element's reactive scope.
+ * @param event The platform's ToggleEvent, from the panel.
+ */
+export function onComboboxToggle(state: ComboboxState, event: Event): void {
+  const opening = (event as { newState?: string }).newState === "open";
+  state.open = opening;
+  if (!opening) {
+    state.activeIndex = -1;
+  }
+}
+
+/**
+ * The chevron: open the list on the row the field already holds, or close it when it is already
+ * open.
+ *
+ * @param state The element's reactive scope.
+ * @param event The click.
+ */
+export function onComboboxButton(state: ComboboxState, event: Event): void {
+  const host = comboboxOf(event);
+  if (!host || !operable(state)) {
+    return;
+  }
+  if (state.open === true) {
+    closeList(host);
+    return;
+  }
+  if (showList(state, host)) {
+    state.activeIndex = landingIndex(state);
+  }
+  inputOf(host)?.focus();
+}
+
+/**
+ * A row was activated — by a click, or by Enter through {@link onComboboxKeydown}.
+ *
+ * @param state The element's reactive scope.
+ * @param event The row's own bubbling `select`, whose detail is its value.
+ */
+export function onComboboxPick(state: ComboboxState, event: Event): void {
+  const host = comboboxOf(event);
+  const picked = String((event as CustomEvent<unknown>).detail ?? "");
+  const row = rowFor(rowsOf(state), picked);
+  if (!host || !row) {
+    return;
+  }
+  commitRow(state, host, row);
+}
+
+/**
+ * The commit: what the reader typed either stands or is refused, and a closed list is what refuses
+ * it.
+ *
+ * Bound to the CONTROL's own `change`, which the platform fires on blur and on Enter. When the
+ * value is accepted the event bubbles out of the element as itself, exactly as `jx-textfield`'s
+ * does, so `e.target` is the inner input and its `validity` and `form` are live. When it is refused
+ * the event stops at the control and the element dispatches one of its own instead — never both,
+ * because two `change` events for one edit are two undo entries for one gesture.
+ *
+ * @param state The element's reactive scope.
+ * @param event The control's `change`.
+ */
+export function onComboboxCommit(state: ComboboxState, event: Event): void {
+  const host = comboboxOf(event);
+  if (!host) {
+    return;
+  }
+  /* The CONTROL's text, not the scope's: they agree whenever `input` preceded this `change`, which
+     is every keystroke and every paste, but a `change` that arrives on its own — an engine or a
+     test that set the control and reported only the commit — is still the reader's text, and the
+     scope catching up here is what keeps the element's `value` from contradicting its own box. */
+  const control = event.target instanceof HTMLInputElement ? event.target : null;
+  const text = control ? control.value : String(state.value ?? "");
+  const row = rowFor(rowsOf(state), text);
+  if (state.allowsCustomValue === true || text === "" || row) {
+    /* A listed value commits in the ROW's spelling, so a picker normalises the case the reader
+       typed; a custom value commits verbatim. The list closes with the commit: a value that stands
+       has nothing left to suggest, and a `change` that arrived without Enter — a blur onto
+       something light dismissal does not count as outside — would otherwise leave it open. */
+    state.value = row ? String(row.value) : text;
+    state.committed = String(state.value);
+    closeList(host);
+    return;
+  }
+  event.stopPropagation();
+  state.value = String(state.committed ?? "");
+  announce(host, "change");
+}
+
+/**
+ * The combobox keyboard, on the field that owns it.
+ *
+ * @param {ComboboxState} state
+ * @param {KeyboardEvent} event
+ */
+export function onComboboxKeydown(state: ComboboxState, event: KeyboardEvent): void {
+  const host = comboboxOf(event);
+  if (!host || event.ctrlKey || event.metaKey) {
+    return;
+  }
+  const rows = rowsOf(state);
+  const at = Number(state.activeIndex ?? -1);
+  switch (event.key) {
+    case "ArrowDown": {
+      if (!operable(state)) {
+        return;
+      }
+      if (state.open !== true) {
+        /* Nothing to list is the platform's own key, not a cancelled one. */
+        if (!showList(state, host)) {
+          return;
+        }
+        state.activeIndex = event.altKey ? landingIndex(state) : nextIndex(rows, -1, 1);
+      } else if (!event.altKey) {
+        state.activeIndex = nextIndex(rows, at, 1);
+      }
+      break;
+    }
+    case "ArrowUp": {
+      if (!operable(state)) {
+        return;
+      }
+      if (event.altKey) {
+        closeList(host);
+        break;
+      }
+      if (state.open !== true) {
+        if (!showList(state, host)) {
+          return;
+        }
+        state.activeIndex = nextIndex(rows, -1, -1);
+      } else {
+        state.activeIndex = nextIndex(rows, at, -1);
+      }
+      break;
+    }
+    case "Enter": {
+      const row = state.open === true && at >= 0 ? rows[at] : undefined;
+      if (!row) {
+        /* Nothing highlighted: the platform's Enter, uncancelled, so the control's own `change`
+           follows and commits what the reader typed. The list closes here all the same — a
+           browser found it standing open over the rows below after the reader had committed with
+           Enter, because the commit is `change`'s and `change` does not fire when the text is what
+           it already was. */
+        if (state.open === true) {
+          closeList(host);
+        }
+        return;
+      }
+      commitRow(state, host, row);
+      break;
+    }
+    case "Tab": {
+      /* The one key that commits WITHOUT being cancelled: the reader is leaving, and taking the row
+         they had highlighted with them is the APG's answer for a list-autocomplete combobox. The
+         list closes either way — a browser found it still standing over the fields below once
+         focus had moved on, because light dismissal answers a press outside and not a Tab. */
+      const row = state.open === true && at >= 0 ? rows[at] : undefined;
+      if (row) {
+        commitRow(state, host, row);
+      } else {
+        closeList(host);
+      }
+      return;
+    }
+    case "Escape": {
+      if (state.open !== true) {
+        return;
+      }
+      closeList(host);
+      /* Stopped as well as cancelled: a combobox inside a dialog must not close the dialog with the
+         same press that closed its own list. */
+      event.stopPropagation();
+      break;
+    }
+    default: {
+      return;
+    }
+  }
+  event.preventDefault();
+}

package/src/behaviors/dialog.ts

@@ -0,0 +1,137 @@
+/**
+ * `jx-dialog`'s behaviour sidecar: the one place the element calls the platform's own `showModal()`
+ * and `close()`, and the handlers that mirror the platform's events back onto the element's state
+ * and out to the host.
+ *
+ * Nothing here traps focus, listens on the document or decides what Escape means. A modal
+ * `<dialog>` makes the rest of the page inert, restores focus when it closes, and answers Escape
+ * and light dismissal through `closedby`; the sidecar's job is only to say so in the element's own
+ * vocabulary — `open` on the state, `confirm`, `secondary`, `cancel` and `close` on the host.
+ *
+ * @docs extending/ui-kit
+ */
+
+export interface DialogState {
+  open: boolean;
+  dismissible: boolean;
+}
+
+/** The `jx-dialog` an event belongs to. */
+function hostOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget;
+  return target instanceof Element ? target.closest<HTMLElement>("jx-dialog") : null;
+}
+
+/** The element's own native dialog. */
+function innerOf(host: HTMLElement): HTMLDialogElement | null {
+  return host.querySelector<HTMLDialogElement>('dialog[part="dialog"]');
+}
+
+function emit(host: HTMLElement | null, name: string): void {
+  host?.dispatchEvent(new CustomEvent(name, { bubbles: true }));
+}
+
+/**
+ * A `toggle` event, dispatched by hand where the platform does not fire one for dialogs.
+ *
+ * Chrome fires `beforetoggle`/`toggle` on a dialog since 2024; the test DOM does not, and the
+ * element's `open` state is read from that event. Dispatched only when the platform's own is not
+ * coming, so a browser never sees two.
+ */
+function syntheticToggle(dialog: HTMLDialogElement, newState: "open" | "closed"): void {
+  if (typeof ToggleEvent !== "undefined") {
+    return;
+  }
+  const event = new Event("toggle", { bubbles: false });
+  Object.assign(event, { newState, oldState: newState === "open" ? "closed" : "open" });
+  dialog.dispatchEvent(event);
+}
+
+/**
+ * Open the dialog modally. The host's door in: Studio's dialog surface calls it once the element is
+ * ready, and a `--show` invoker command reaches it through {@link onCommand}.
+ *
+ * @param host The `jx-dialog` element.
+ */
+export function showModal(host: HTMLElement): void {
+  const dialog = innerOf(host);
+  if (!dialog || dialog.open) {
+    return;
+  }
+  dialog.showModal();
+  syntheticToggle(dialog, "open");
+}
+
+/**
+ * Close the dialog, with an optional return value the platform records on the native element.
+ *
+ * @param host The `jx-dialog` element.
+ * @param returnValue What closed it, for `dialog.returnValue`.
+ */
+export function close(host: HTMLElement, returnValue?: string): void {
+  const dialog = innerOf(host);
+  if (!dialog?.open) {
+    return;
+  }
+  dialog.close(returnValue);
+  syntheticToggle(dialog, "closed");
+}
+
+/** The platform's `toggle` on the inner dialog: the one source of truth for `open`. */
+export function onToggle(state: DialogState, event: Event): void {
+  state.open = (event as { newState?: string }).newState === "open";
+}
+
+/**
+ * The platform's `cancel` on the inner dialog — Escape, or a light dismissal `closedby` allows. The
+ * platform closes the dialog itself after this; the element only says so.
+ */
+export function onNativeCancel(state: DialogState, event: Event): void {
+  state.open = false;
+  emit(hostOf(event), "cancel");
+}
+
+/** The platform's `close` on the inner dialog, whatever closed it. */
+export function onNativeClose(state: DialogState, event: Event): void {
+  state.open = false;
+  emit(hostOf(event), "close");
+}
+
+/**
+ * An invoker command aimed at the host: `--show` opens the dialog modally, `--close` closes it.
+ *
+ * Custom commands are the only ones the platform delivers to an element that is not itself a
+ * `<dialog>`, which the host of an inner one is not; so `<button command="--show"
+ * commandfor="my-dialog">` is how a page opens a `jx-dialog` with no script.
+ */
+export function onCommand(_state: DialogState, event: Event): void {
+  const host = hostOf(event);
+  const command = (event as { command?: string }).command ?? "";
+  if (!host) {
+    return;
+  }
+  if (command === "--show") {
+    showModal(host);
+  } else if (command === "--close") {
+    close(host);
+  }
+}
+
+/** The confirm button. The host decides whether the dialog closes: a refused value keeps it open. */
+export function onConfirm(_state: DialogState, event: Event): void {
+  emit(hostOf(event), "confirm");
+}
+
+/** The secondary button, the dialog's third answer (Save · Discard · Cancel). */
+export function onSecondary(_state: DialogState, event: Event): void {
+  emit(hostOf(event), "secondary");
+}
+
+/** The cancel button: says so, then closes, so the platform's `close` follows. */
+export function onCancelClick(_state: DialogState, event: Event): void {
+  const host = hostOf(event);
+  emit(host, "cancel");
+  if (host) {
+    close(host, "cancel");
+  }
+}