@jxsuite/ui 0.0.0 → 0.1.0

package/src/behaviors/listbox.ts

@@ -0,0 +1,118 @@
+/**
+ * `jx-listbox`'s sidecar: the two things a document body cannot say about a list whose keyboard
+ * belongs to somebody else.
+ *
+ * **The listbox is the single writer of every row's `selected`**, exactly as `jx-tabs` is of every
+ * tab's, and for the same reason: the flag has to be moved on a foreign element and specs/ui.md §2
+ * principle 5 forbids a sidecar writing an ATTRIBUTE on one. So the element observes a PROPERTY,
+ * this module writes the property, and the option's own document is what turns it into
+ * `aria-selected`. A consumer therefore moves the highlight by writing ONE string — the listbox's
+ * `active`, which is the id its owning field already points `aria-activedescendant` at — instead of
+ * re-deciding the question once per row.
+ *
+ * That is the whole of the duplication being closed. Studio's three palettes each carried
+ * `aria-selected="${$map.index === state.activeIndex ? 'true' : 'false'}"` and a `data-selected`
+ * beside it, in three files, with nothing keeping the three in agreement; the id reference is one
+ * answer that reaches both the field and the row, which is what a light DOM is for (§2 principle
+ * 2).
+ *
+ * **The active row is scrolled back into view**, which is the half no consumer could do at all: it
+ * is measurement and a method call on another element, both of which belong here. `block:
+ * "nearest"` is deliberate — it does nothing when the row is already visible, so a pointer moving
+ * over a list never scrolls it under the pointer.
+ *
+ * What this module does NOT do is take focus, and that is the element's whole contract rather than
+ * an omission. A `jx-listbox` has no `tabindex` and never calls `focus()`: one of its two owners is
+ * a field that must keep the caret (a palette), and the other is NOTHING AT ALL — Studio's slash
+ * menu filters for a caret sitting in the canvas, often in another realm, and every character typed
+ * after the `/` has to keep landing there. A menu owns DOM focus by contract, which is exactly why
+ * that surface is a listbox and not a menu.
+ *
+ * @docs extending/ui-kit
+ */
+
+/** A row element with the property accessors its own document installs. */
+type OptionElement = HTMLElement & { selected?: boolean; disabled?: boolean; value?: string };
+
+/** The reactive scope a `jx-listbox` document hands its handlers. */
+export interface ListboxState {
+  /** The id of the row the caret is on; the empty string when none is. */
+  active?: string;
+  [key: string]: unknown;
+}
+
+const ROW = "jx-option";
+const LIST = "jx-listbox";
+
+/**
+ * The rows of one listbox, in document order, excluding the rows of any listbox nested inside it.
+ *
+ * Rows sit inside the panel's emulated `<slot>` and inside whatever `role="group"` wrappers a
+ * consumer added for its headings, so this walks descendants and keeps the ones whose nearest
+ * listbox is this one — the same shape `rowsOf` has in the menu behaviour.
+ *
+ * @param host The `jx-listbox` element.
+ * @returns Its own rows.
+ */
+export function optionsOf(host: HTMLElement): OptionElement[] {
+  return [...host.querySelectorAll<OptionElement>(ROW)].filter((row) => row.closest(LIST) === host);
+}
+
+/**
+ * Bring every row's `selected` into agreement with the active id, and scroll the newly active one
+ * back into view.
+ *
+ * @param host The `jx-listbox` element.
+ * @param active The id of the row the caret is on; `""` for none.
+ * @returns The row that is now active, or null when nothing is.
+ */
+export function syncListbox(host: HTMLElement, active: string): OptionElement | null {
+  let landed: OptionElement | null = null;
+  let moved = false;
+  for (const row of optionsOf(host)) {
+    const wanted = active !== "" && row.id === active;
+    if (wanted) {
+      landed = row;
+      /* Only a row that was NOT already selected is scrolled to. A rows-changed mutation that
+         leaves the same row active must not yank the list under a reader's pointer. */
+      moved = row.selected !== true;
+    }
+    if (row.selected !== wanted) {
+      row.selected = wanted;
+    }
+  }
+  if (landed && moved && typeof landed.scrollIntoView === "function") {
+    landed.scrollIntoView({ block: "nearest" });
+  }
+  return landed;
+}
+
+/**
+ * Keep the rows in step with `active` for as long as the element lives.
+ *
+ * Two things move underneath this and neither produces the other's mutation record, so both are
+ * watched. The ROWS change when a filter re-runs, which is a `childList` record — and the row
+ * carrying the active id is then a different element, so its `selected` has to be re-asserted or
+ * the highlight simply disappears. The ACTIVE ID changes when a key moves the caret, which mutates
+ * no row at all; the document is what makes that write audible, by binding `data-active` to the
+ * same state, exactly as `jx-select`'s sidecar reads a host write of `value` through `data-value`.
+ *
+ * There is deliberately no `onUnmount`, for the reason `select.ts` sets out at length: the runtime
+ * initialises an element once, so a sidecar that disconnected on removal could never install
+ * another, and an ordinary re-parent would leave the element rendering, reactive and deaf.
+ *
+ * @param state The element's reactive scope.
+ * @param host The `jx-listbox` element.
+ */
+export function mountListbox(state: ListboxState, host: HTMLElement): void {
+  syncListbox(host, String(state.active ?? ""));
+  const observer = new MutationObserver(() => {
+    syncListbox(host, String(state.active ?? ""));
+  });
+  observer.observe(host, {
+    attributeFilter: ["data-active"],
+    attributes: true,
+    childList: true,
+    subtree: true,
+  });
+}

package/src/behaviors/menu.ts

@@ -11,8 +11,23 @@
  * A submenu is a child `jx-menu` slotted into a row (`slot="submenu"`), so it is a DOM descendant
  * of its parent panel and the platform treats the two as one popover hierarchy: opening the child
  * does not close the parent, and a click outside closes both.
+ *
+ * **Placement is the platform's for a menu that hangs from something, and the clamp's for a menu at
+ * a pointer.** A menu shown from a source has that source as its implicit anchor, exactly as
+ * `jx-popover` does (see `popover.ts`), but a menu's usual source is the element a CONTEXT menu was
+ * opened over — what gets the keyboard back, not where the panel hangs — so anchoring is opted into
+ * by `placement`, and a submenu opts in on its own with `inline-end span-block-end`, which is the
+ * "beside its row, flipped to the other side when it would overflow" the clamp used to compute by
+ * hand. {@link onMenuBeforeToggle} decides it before layout; a stack whose root has a floor is
+ * never anchored, because a floor is a limit the platform's fallbacks cannot express.
+ *
+ * @docs extending/ui-kit
  */
 
+import { anchorOf, clampIntoViewport, openAt, supportsAnchorPositioning } from "./popover.ts";
+
+export { clampIntoViewport } from "./popover.ts";
+
 const ROW = "jx-menu-item";
 const MENU = "jx-menu";
 
@@ -22,9 +37,18 @@ export interface MenuState {
   x?: number;
   y?: number;
   floor?: number;
+  /** A `position-area` value, or empty for placement by `x` and `y`. */
+  placement?: string;
+  /** The area the anchored rule reads: `placement`, else the submenu default, else empty. */
+  area?: string;
+  /** Whether the platform is placing this panel against the element it was shown from. */
+  anchored?: boolean;
   [key: string]: unknown;
 }
 
+/** Where a submenu sits when its document says nothing: beside its row, extending downward. */
+export const SUBMENU_PLACEMENT = "inline-end span-block-end";
+
 /** A row element with the property accessors its document installs. */
 type RowElement = HTMLElement & { expanded?: boolean; disabled?: boolean };
 /** A menu element with the property accessors its document installs. */
@@ -95,10 +119,22 @@ function isShowing(menu: MenuElement): boolean {
   return menu.open === true;
 }
 
-/** Show a menu panel through the platform, if it is not already showing. */
-export function showMenu(menu: MenuElement): void {
-  if (!isShowing(menu) && typeof menu.showPopover === "function") {
-    menu.showPopover();
+/**
+ * Show a menu panel through the platform, if it is not already showing.
+ *
+ * `source` is the element the panel was opened from, and it is not decoration: HTML relocates a
+ * popover's sequential focus position and restores focus relative to its INVOKER, which is
+ * established either by a `popovertarget` button or by `showPopover({ source })`. A bare
+ * `showPopover()` — which is what this did — leaves the panel with no invoker at all, so closing a
+ * submenu returned the caret to wherever the document happened to leave it, and a mousedown on the
+ * row a submenu hangs off light-dismissed the submenu as an outside click.
+ *
+ * @param menu The panel to show.
+ * @param source The element it is being opened from, if any.
+ */
+export function showMenu(menu: MenuElement, source?: Element | null): void {
+  if (!isShowing(menu)) {
+    openAt(menu, source ?? null);
   }
 }
 
@@ -143,7 +179,7 @@ export function openSubmenu(
   sub.x = Math.round(box.right) - 2;
   sub.y = Math.round(box.top) - 4;
   row.expanded = true;
-  showMenu(sub);
+  showMenu(sub, row);
   if (options.focus) {
     focusRow(rowsOf(sub), 0);
   }
@@ -269,9 +305,34 @@ export function onMenuKeydown(_state: MenuState, event: KeyboardEvent): void {
 }
 
 /**
- * Mirror the platform's toggle into state; on show, clamp into the viewport once laid out and move
- * the caret to the first row; on hide, close whatever submenus were open and clear the parent row's
- * expanded state.
+ * The platform's `beforetoggle`: where `area` and `anchored` are decided, before the panel is laid
+ * out, so the first frame is already the anchored one and nothing jumps.
+ *
+ * `area` is `placement` when the document set one, else the submenu default for a menu inside a
+ * row, else empty; `anchored` is an opening with an area, a source the platform or `openAt` named,
+ * and no floor on the stack's root. A closing `beforetoggle` clears `anchored`, so the coordinate
+ * rule is back in force for whatever shows the panel next.
+ *
+ * @param {MenuState} state
+ * @param {Event} event The platform's ToggleEvent
+ */
+export function onMenuBeforeToggle(state: MenuState, event: Event): void {
+  const menu = menuOf(event);
+  if (!menu) {
+    return;
+  }
+  const opening = (event as { newState?: string }).newState === "open";
+  const area = String(state.placement ?? "") || (parentRowOf(menu) ? SUBMENU_PLACEMENT : "");
+  state.area = area;
+  const { source } = event as Event & { source?: unknown };
+  const from = source instanceof Element ? source : anchorOf(menu);
+  state.anchored = opening && area !== "" && from !== null && !hasFloor(menu);
+}
+
+/**
+ * Mirror the platform's toggle into state; on show, clamp into the viewport once laid out — unless
+ * the platform is placing the panel by anchor — and move the caret to the first row; on hide, close
+ * whatever submenus were open and clear the parent row's expanded state.
  *
  * @param {MenuState} state
  * @param {Event} event The platform's ToggleEvent
@@ -291,57 +352,28 @@ export function onMenuToggle(state: MenuState, event: Event): void {
     }
     return;
   }
-  clampIntoViewport(state, menu);
+  if (!(state.anchored === true && supportsAnchorPositioning())) {
+    clampIntoViewport(state, menu, {
+      flipAgainst: parent?.closest<HTMLElement>(MENU) ?? null,
+      floor: floorOf(menu),
+    });
+  }
   if (!menu.contains(document.activeElement)) {
     focusRow(rowsOf(menu), 0);
   }
 }
 
+/** Whether the stack's root declares a floor at all. */
+function hasFloor(menu: HTMLElement): boolean {
+  return Number((rootMenuOf(menu) as MenuElement).floor ?? 0) > 0;
+}
+
 /** The lowest edge a stack may reach: the root menu's `floor`, else the viewport's bottom. */
 function floorOf(menu: HTMLElement): number {
   const floor = Number((rootMenuOf(menu) as MenuElement).floor ?? 0);
   return floor > 0 ? floor : window.innerHeight;
 }
 
-/**
- * Keep a shown panel inside its area. Measured after a frame, because an unlaid-out panel is zero
- * wide and would never appear to overflow anything; a zero-size box (a test DOM) is left where it
- * is.
- *
- * A submenu that would leave the viewport on the right FLIPS to its parent menu's left rather than
- * sliding over the parent; a root menu slides. Both are floored at the stack's `floor` — the root
- * menu's, so one floor holds for every level.
- *
- * @param {MenuState} state
- * @param {HTMLElement} menu
- */
-export function clampIntoViewport(state: MenuState, menu: HTMLElement): void {
-  const measure = (): void => {
-    const box = menu.getBoundingClientRect();
-    if (box.width === 0 && box.height === 0) {
-      return;
-    }
-    const margin = 4;
-    const bottom = floorOf(menu);
-    if (box.right > window.innerWidth - margin) {
-      const parent = parentRowOf(menu)?.closest<HTMLElement>(MENU) ?? null;
-      const flipped = parent ? Math.round(parent.getBoundingClientRect().left) - box.width + 2 : -1;
-      state.x =
-        flipped >= margin
-          ? flipped
-          : Math.max(margin, Math.round(window.innerWidth - box.width - margin));
-    }
-    if (box.bottom > bottom) {
-      state.y = Math.max(margin, Math.round(bottom - box.height));
-    }
-  };
-  if (typeof requestAnimationFrame === "function") {
-    requestAnimationFrame(measure);
-  } else {
-    measure();
-  }
-}
-
 /**
  * Put the caret somewhere after the rows changed under it: when focus is no longer inside `menu`,
  * the first row of the deepest open submenu takes it — and a submenu left with no rows at all is

package/src/behaviors/number-field.ts

@@ -0,0 +1,161 @@
+/**
+ * `jx-number-field`'s behaviour sidecar: the stepping a document cannot express, and the mirror
+ * that follows a value the platform wrote without telling anyone.
+ *
+ * Everything here goes through the element's OWN inner `<input type="number">` and its own value
+ * API. `HTMLInputElement.stepUp(n)` / `stepDown(n)` take a multiplier, clamp to `min` and `max`,
+ * and snap to the step grid measured from `min` — hand-rolled `value ± step` diverges the moment
+ * the value is off that grid (min 0, step 0.3, value 0.5: `stepUp(1)` is 0.6 and `value + step` is
+ * 0.8). They are unreachable from a document body, because the expression evaluator's `calleeOwner`
+ * has no `event#/` branch and a `call` on `event#/target/stepUp` would invoke with an undefined
+ * receiver. That is why this module exists, and it is the amendment to specs/ui.md §2 principle 5:
+ * a native form control's own value-stepping API, on the element's own inner control.
+ *
+ * WHO WROTE THE VALUE DECIDES WHO SAYS SO.
+ *
+ * When the READER wrote it, the platform has already said so and nothing here touches that: the
+ * native `input` and `change` bubble out of `[part="input"]` unstopped and un-re-sent, so a host's
+ * `e.target` is the live control and `e.target.valueAsNumber` (NaN when empty), `.validity`,
+ * `.checkValidity()` and `.form` all read. `jx-textfield`'s sidecar leaves the same pair alone, so
+ * one ported `(e.target as HTMLInputElement)` cast is right for both kit fields.
+ *
+ * When the ELEMENT wrote it — the two stepper buttons, and Shift+Arrow — the platform fires nothing
+ * at all for a programmatic value write, so the same two NAMES are dispatched from the HOST, whose
+ * own `value` is that same string. No new names, and no `detail`: an event is how a host is told
+ * that the value moved, not where the element keeps its state.
+ *
+ * SO `badInput` RIDES THE ELEMENT, NOT AN EVENT. `<input type="number">` runs a value sanitization
+ * algorithm and discards what it cannot parse, so a half-typed "1e" reads as an empty value with
+ * `validity.badInput` true. A host that deletes a key when the field goes empty must tell that from
+ * a clear, and it asks the element: `host.badInput`, written here before the event bubbles past,
+ * and mirrored to `data-bad-input` on the host for a selector. From a handler holding only the
+ * event that is `(event.target as Element).closest("jx-number-field")` — which works on both paths,
+ * because the control is inside the host and the host is itself.
+ *
+ * @docs extending/ui-kit
+ */
+
+/** The reactive scope a `jx-number-field` document hands its handlers. */
+export interface NumberFieldState {
+  /** The field's text, as a string — empty is empty, never 0. */
+  value: string;
+  /** Whether the control is holding something it cannot parse as a number. */
+  badInput: boolean;
+  [key: string]: unknown;
+}
+
+const HOST = "jx-number-field";
+
+/** The `jx-number-field` an event belongs to. */
+function hostOf(event: Event): HTMLElement | null {
+  const target = event.currentTarget;
+  return target instanceof Element ? target.closest<HTMLElement>(HOST) : null;
+}
+
+/** The element's own native control. */
+function controlOf(host: HTMLElement): HTMLInputElement | null {
+  return host.querySelector<HTMLInputElement>('input[part="input"]');
+}
+
+/**
+ * Read the control back into state.
+ *
+ * `badInput` is the third case between empty and zero, and this is where a host reads it from: the
+ * element, synchronously, before any event this write precedes has finished bubbling.
+ */
+function mirror(state: NumberFieldState, control: HTMLInputElement): void {
+  state.value = control.value;
+  state.badInput = control.validity?.badInput === true;
+}
+
+/**
+ * Say that a value the ELEMENT wrote moved and was committed, in the platform's own two names, from
+ * the host — the platform fires neither for a programmatic write.
+ */
+function announce(host: HTMLElement): void {
+  host.dispatchEvent(new Event("input", { bubbles: true }));
+  host.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+/**
+ * Step the control by `n` steps — negative steps down — through the control's own API, then mirror
+ * and announce.
+ *
+ * @param state The element's reactive scope.
+ * @param event The event whose `currentTarget` sits inside the field.
+ * @param n How many steps, signed.
+ */
+export function stepBy(state: NumberFieldState, event: Event, n: number): void {
+  const host = hostOf(event);
+  const control = host ? controlOf(host) : null;
+  if (!host || !control) {
+    return;
+  }
+  try {
+    if (n < 0) {
+      control.stepDown(-n);
+    } else {
+      control.stepUp(n);
+    }
+  } catch {
+    /* A control whose value cannot be converted to a number throws InvalidStateError: there is
+       nothing to step from, and the reader's half-typed text is not ours to replace. */
+    return;
+  }
+  mirror(state, control);
+  announce(host);
+}
+
+/**
+ * The inner control's `keydown`: Shift+ArrowUp / Shift+ArrowDown move ten steps.
+ *
+ * A plain Arrow is left alone — the platform already steps by one, clamps and snaps. The shifted
+ * pair is cancelled so the platform's own single step does not run on top of the ten.
+ *
+ * @param state The element's reactive scope.
+ * @param event The keyboard event.
+ */
+export function onNumberKeydown(state: NumberFieldState, event: Event): void {
+  const key = event as KeyboardEvent;
+  if (!key.shiftKey) {
+    return;
+  }
+  if (key.key === "ArrowUp") {
+    key.preventDefault();
+    stepBy(state, event, 10);
+  } else if (key.key === "ArrowDown") {
+    key.preventDefault();
+    stepBy(state, event, -10);
+  }
+}
+
+/** The step-up button: one step, the same way an ArrowUp does it. */
+export function onStepUp(state: NumberFieldState, event: Event): void {
+  stepBy(state, event, 1);
+}
+
+/** The step-down button: one step down. */
+export function onStepDown(state: NumberFieldState, event: Event): void {
+  stepBy(state, event, -1);
+}
+
+/**
+ * The inner control's `change`: the reader committed an edit.
+ *
+ * This only reads the control back into state. The native event is neither stopped nor re-sent — it
+ * goes on bubbling from `[part="input"]`, which is the whole reason a host can still reach
+ * `e.target.valueAsNumber` and `e.target.validity`. The mirror lives here as well as on `input`
+ * because a `change` can arrive without one: a host that writes the control's value itself gets no
+ * `input` from the platform either.
+ *
+ * @param state The element's reactive scope.
+ * @param event The native change event.
+ */
+export function onNumberChange(state: NumberFieldState, event: Event): void {
+  const host = hostOf(event);
+  const control = host ? controlOf(host) : null;
+  if (!host || !control) {
+    return;
+  }
+  mirror(state, control);
+}