@jxsuite/ui 0.5.1 → 0.7.1

package/src/behaviors/popover.ts

@@ -45,6 +45,8 @@
  * @docs extending/ui-kit
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
+
 /** The reactive scope a popover-shaped document hands its handlers. */
 export interface PopoverState {
   open?: boolean;
@@ -56,7 +58,6 @@ export interface PopoverState {
   x?: number;
   y?: number;
   floor?: number;
-  [key: string]: unknown;
 }
 
 /**
@@ -66,28 +67,23 @@ export interface PopoverState {
  * stub it either way.
  */
 export function supportsAnchorPositioning(): boolean {
-  const css = (globalThis as { CSS?: { supports?: (property: string, value: string) => boolean } })
-    .CSS;
-  return typeof css?.supports === "function" && css.supports("position-area", "block-end");
-}
-
-/**
- * The popover API as this module calls it.
- *
- * Declared here rather than reached for through the DOM types because an engine may not have it at
- * all — the kit publishes to site authors, and every call site guards on `typeof`.
- */
-interface PopoverApi {
-  showPopover?: (options?: { source?: HTMLElement }) => void;
-  hidePopover?: () => void;
+  return (
+    typeof CSS !== "undefined" &&
+    isFunction(CSS.supports) &&
+    CSS.supports("position-area", "block-end")
+  );
 }
 
-/** An element that may be a popover: every method the behaviour calls is optional. */
-export type PopoverElement = HTMLElement;
+/** A `jx-popover` element, with the `x` and `y` coordinates its document declares as props. */
+export type PlacedPopover = HTMLElement & { x: number; y: number };
 
-/** The popover API of an element, whether or not this engine implements it. */
-function apiOf(host: HTMLElement): PopoverApi {
-  return host as unknown as PopoverApi;
+/** Run `callback` in the next frame, or now on an engine with no frames to wait for. */
+function inFrame(callback: () => void): void {
+  if (isFunction(globalThis.requestAnimationFrame)) {
+    requestAnimationFrame(callback);
+  } else {
+    callback();
+  }
 }
 
 /**
@@ -126,13 +122,12 @@ export function anchorOf(host: HTMLElement): Element | null {
  * @param host The panel element.
  * @param anchor The element the panel was opened from, if any.
  */
-export function openAt(host: PopoverElement, anchor?: Element | null): void {
-  const api = apiOf(host);
-  if (typeof api.showPopover !== "function") {
+export function openAt(host: HTMLElement, anchor?: Element | null): void {
+  if (!isFunction(host.showPopover)) {
     return;
   }
   if (!anchor) {
-    api.showPopover();
+    host.showPopover();
     return;
   }
   /* BEFORE the call, because `beforetoggle` fires inside it and {@link onBeforeToggle} reads the
@@ -141,7 +136,7 @@ export function openAt(host: PopoverElement, anchor?: Element | null): void {
      open. */
   anchors.set(host, anchor);
   try {
-    show(api, anchor);
+    show(host, anchor);
   } catch (error) {
     anchors.delete(host);
     throw error;
@@ -157,16 +152,16 @@ export function openAt(host: PopoverElement, anchor?: Element | null): void {
  * that one bare throws the same error a second time, out of `openAt` and into whatever bound the
  * handler. So it is re-raised from the FIRST call, unswallowed.
  */
-function show(api: PopoverApi, anchor: Element): void {
+function show(host: HTMLElement, anchor: Element): void {
   try {
-    /* `ShowPopoverOptions.source` is typed `HTMLElement`, but any element can be a
+    /* SAFETY: `ShowPopoverOptions.source` is typed `HTMLElement`, but any element can be a
        trigger and the platform only reads it as a focus origin. */
-    api.showPopover?.({ source: anchor as HTMLElement });
+    host.showPopover({ source: anchor as HTMLElement });
   } catch (error) {
     if (!(error instanceof TypeError)) {
       throw error;
     }
-    api.showPopover?.();
+    host.showPopover();
   }
 }
 
@@ -175,10 +170,9 @@ function show(api: PopoverApi, anchor: Element): void {
  *
  * @param host The panel element.
  */
-export function close(host: PopoverElement): void {
-  const api = apiOf(host);
-  if (typeof api.hidePopover === "function") {
-    api.hidePopover();
+export function close(host: HTMLElement): void {
+  if (isFunction(host.hidePopover)) {
+    host.hidePopover();
   }
 }
 
@@ -210,7 +204,7 @@ function invokerOf(host: HTMLElement): Element | null {
  * {@link openAt} recorded, then the invoker that names the panel.
  */
 function toggleSourceOf(host: HTMLElement, event: Event): Element | null {
-  const { source } = event as Event & { source?: unknown };
+  const source = "source" in event ? event.source : null;
   if (source instanceof Element) {
     return source;
   }
@@ -250,16 +244,12 @@ export function measureAnchor(
  */
 function clearWhenStill(state: PopoverState, host: HTMLElement): void {
   const settle = (): void => {
-    if (typeof host.getAnimations === "function" && host.getAnimations().length > 0) {
+    if (isFunction(host.getAnimations) && host.getAnimations().length > 0) {
       return;
     }
     state.settling = false;
   };
-  if (typeof requestAnimationFrame === "function") {
-    requestAnimationFrame(settle);
-  } else {
-    settle();
-  }
+  inFrame(settle);
 }
 
 /**
@@ -278,7 +268,7 @@ export function onBeforeToggle(state: PopoverState, event: Event): void {
   if (!host) {
     return;
   }
-  const opening = (event as { newState?: string }).newState === "open";
+  const opening = "newState" in event && event.newState === "open";
   const floor = Number(state.floor ?? 0);
   state.anchored = opening && floor <= 0 && toggleSourceOf(host, event) !== null;
 }
@@ -297,7 +287,7 @@ export function onToggle(state: PopoverState, event: Event): void {
   if (!host) {
     return;
   }
-  const opening = (event as { newState?: string }).newState === "open";
+  const opening = "newState" in event && event.newState === "open";
   state.open = opening;
   state.settling = true;
   if (opening) {
@@ -391,9 +381,5 @@ export function clampIntoViewport(
       state.y = Math.max(margin, Math.round(floor - box.height - blockOffsetOf(panel)));
     }
   };
-  if (typeof requestAnimationFrame === "function") {
-    requestAnimationFrame(measure);
-  } else {
-    measure();
-  }
+  inFrame(measure);
 }

package/src/behaviors/select.ts

@@ -38,12 +38,25 @@
  * @docs extending/ui-kit
  */
 
-/** A row as the element draws it. Only `value` and `label` are ever read here. */
-interface UnlistedRow {
+/**
+ * A row as the element draws it: the value the control reports back, and the label the reader sees.
+ * Only `value` and `label` are ever read here.
+ */
+export interface SelectRow {
   value: string;
   label: string;
 }
 
+/** The reactive scope a `jx-select` document hands its sidecar. */
+export interface SelectState {
+  /** The value the element holds; null when a host clears the reflected `value` attribute. */
+  value?: string | null;
+  /** The stand-in row for a value no listed row holds: empty, or exactly one row. */
+  unlisted?: SelectRow[];
+  /** This element's own id stem, minted at mount. */
+  uid?: string;
+}
+
 /** How many stems have been minted, so no two instances share one. */
 let minted = 0;
 
@@ -89,17 +102,17 @@ function isListed(sel: HTMLSelectElement, want: string): boolean {
  * @param state The element's reactive scope.
  * @param sel The element's own `<select>`.
  */
-export function syncSelect(state: Record<string, unknown>, sel: HTMLSelectElement): void {
-  const want = String(state["value"] ?? "");
-  const rows = (state["unlisted"] as UnlistedRow[] | undefined) ?? [];
+export function syncSelect(state: SelectState, sel: HTMLSelectElement): void {
+  const want = String(state.value ?? "");
+  const rows = state.unlisted ?? [];
   /* The empty string is a legal value — the inherit row — rather than absence, so it is never
      stood in for: a blank row labelled with a blank value would say nothing about what is held. */
   if (want !== "" && !isListed(sel, want)) {
     if (rows.length !== 1 || rows[0]?.value !== want) {
-      state["unlisted"] = [{ label: want, value: want }];
+      state.unlisted = [{ label: want, value: want }];
     }
   } else if (rows.length > 0) {
-    state["unlisted"] = [];
+    state.unlisted = [];
   }
   if ([...sel.options].some((option) => option.value === want)) {
     if (sel.value !== want || sel.selectedIndex < 0) {
@@ -120,9 +133,9 @@ export function syncSelect(state: Record<string, unknown>, sel: HTMLSelectElemen
  * @param state The element's reactive scope, whose `uid` and `unlisted` this writes.
  * @param host The `jx-select` element.
  */
-export function mountSelect(state: Record<string, unknown>, host: HTMLElement): void {
+export function mountSelect(state: SelectState, host: HTMLElement): void {
   minted += 1;
-  state["uid"] = `jx-select-${minted}`;
+  state.uid = `jx-select-${minted}`;
   const sel = controlOf(host);
   if (!sel) {
     return;

package/src/behaviors/split.ts

@@ -49,6 +49,9 @@
  * @docs extending/ui-kit
  */
 
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
 /** The tag this sidecar belongs to. */
 const HOST = "jx-split";
 
@@ -79,7 +82,6 @@ export interface SplitState {
   dragging: boolean;
   /** The position the toggle returns to; negative until a collapse has recorded one. */
   restore: number;
-  [key: string]: unknown;
 }
 
 /**
@@ -101,14 +103,16 @@ const NO_MODIFIERS: Readonly<SplitModifiers> = Object.freeze({
   shiftKey: false,
 });
 
-/** The four modifier flags off an event, each `true` only when it is exactly `true`. */
-function modifiersOf(event: object): SplitModifiers {
-  const flags = event as Partial<Record<keyof SplitModifiers, unknown>>;
+/**
+ * The four modifier flags off a pointer or key event, each `true` only when it is exactly `true`,
+ * because a synthetic event a test or a driver builds may carry none of them.
+ */
+function modifiersOf(event: Partial<SplitModifiers>): SplitModifiers {
   return {
-    altKey: flags.altKey === true,
-    ctrlKey: flags.ctrlKey === true,
-    metaKey: flags.metaKey === true,
-    shiftKey: flags.shiftKey === true,
+    altKey: event.altKey === true,
+    ctrlKey: event.ctrlKey === true,
+    metaKey: event.metaKey === true,
+    shiftKey: event.shiftKey === true,
   };
 }
 
@@ -123,20 +127,34 @@ function modifiersOf(event: object): SplitModifiers {
  * @param event The `input` or `change`.
  */
 export function splitModifiersOf(event: Event): SplitModifiers {
-  const { detail } = event as { detail?: unknown };
-  return detail !== null && typeof detail === "object" ? modifiersOf(detail) : { ...NO_MODIFIERS };
+  const detail = "detail" in event ? event.detail : undefined;
+  if (!isNonNullObject(detail)) {
+    return { ...NO_MODIFIERS };
+  }
+  /* A detail is whatever its dispatcher put there, so each flag is probed by name rather than
+     trusted to be a boolean: only an exact `true` counts, as it does off an event. */
+  return {
+    altKey: "altKey" in detail && detail.altKey === true,
+    ctrlKey: "ctrlKey" in detail && detail.ctrlKey === true,
+    metaKey: "metaKey" in detail && detail.metaKey === true,
+    shiftKey: "shiftKey" in detail && detail.shiftKey === true,
+  };
+}
+
+/** The range the value may take, and the track length it was converted against. */
+interface SplitBounds {
+  /** The track's length along the dragged axis, in pixels. */
+  length: number;
+  lo: number;
+  hi: number;
 }
 
-/** One live gesture: where it started, and the bounds it was measured against. */
-interface Drag {
+/** One live gesture: where it started, and the bounds it was measured against, once. */
+interface Drag extends SplitBounds {
   /** The pointer coordinate at `pointerdown`, along the dragged axis. */
   origin: number;
   /** The value at `pointerdown`. */
   start: number;
-  /** The track's length along that axis, measured once. */
-  length: number;
-  lo: number;
-  hi: number;
 }
 
 /**
@@ -167,13 +185,13 @@ function announce(host: HTMLElement, modifiers: SplitModifiers, ...names: string
 }
 
 /** A number, or the fallback when the scope holds something that is not one. */
-function finiteOr(value: unknown, fallback: number): number {
+function finiteOr(value: JsonValue | undefined, fallback: number): number {
   const n = Number(value);
   return Number.isFinite(n) ? n : fallback;
 }
 
 /** A POSITIVE number, or the fallback. A step of zero is a key that does nothing. */
-function positiveOr(value: unknown, fallback: number): number {
+function positiveOr(value: JsonValue | undefined, fallback: number): number {
   const n = Number(value);
   return Number.isFinite(n) && n > 0 ? n : fallback;
 }
@@ -262,10 +280,7 @@ export function trackOf(host: HTMLElement, vertical: boolean): number {
  * @param state The element's reactive scope.
  * @param host The element.
  */
-function boundsOf(
-  state: SplitState,
-  host: HTMLElement,
-): { lo: number; hi: number; length: number } {
+function boundsOf(state: SplitState, host: HTMLElement): SplitBounds {
   const length = trackOf(host, isVertical(state));
   const min = finiteOr(state.min, 0);
   const max = finiteOr(state.max, 1);
@@ -373,7 +388,7 @@ export function onSplitPointerDown(state: SplitState, event: PointerEvent): void
     origin: coordOf(isVertical(state), event),
     start: Number(state.value),
   });
-  if (typeof host.setPointerCapture === "function") {
+  if (isFunction(host.setPointerCapture)) {
     /* Capture on the HOST, which is also the element the listener is on: a drag that runs off the
        end of the splitter keeps arriving here instead of stopping at whatever it crossed. */
     try {
@@ -436,8 +451,9 @@ export function onSplitPointerUp(state: SplitState, event: PointerEvent): void {
   }
   state.dragging = false;
   if (
-    typeof host.releasePointerCapture === "function" &&
-    host.hasPointerCapture?.(event.pointerId)
+    isFunction(host.releasePointerCapture) &&
+    isFunction(host.hasPointerCapture) &&
+    host.hasPointerCapture(event.pointerId)
   ) {
     host.releasePointerCapture(event.pointerId);
   }

package/src/behaviors/swatch-group.ts

@@ -38,7 +38,6 @@ export interface SwatchGroupState {
   value?: string;
   /** The group's accessible name. */
   label?: string;
-  [key: string]: unknown;
 }
 
 /** A swatch element with the property accessors its own document installs. */
@@ -67,9 +66,7 @@ const watched = new WeakMap<HTMLElement, MutationObserver>();
 /** The group an event's `currentTarget` is. */
 function hostOf(event: Event): GroupElement | null {
   const target = event.currentTarget;
-  return target instanceof HTMLElement && target.localName === GROUP
-    ? (target as GroupElement)
-    : null;
+  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. */
@@ -147,12 +144,12 @@ export function focusSwatch(group: HTMLElement, index: number): SwatchElement |
  *
  * @param group The `jx-swatch-group` element.
  */
-export function syncSwatches(group: HTMLElement): void {
+export function syncSwatches(group: GroupElement): void {
   const swatches = swatchesOf(group);
   if (swatches.length === 0) {
     return;
   }
-  const value = String((group as GroupElement).value ?? "");
+  const value = String(group.value ?? "");
   const enabled = swatches.filter((swatch) => !isDisabled(swatch));
   const chosen = enabled.find((swatch) => valueOf(swatch) === value);
   const caret = chosen ?? enabled[0] ?? null;
@@ -233,7 +230,7 @@ export function onSwatchGroupSelect(scope: SwatchGroupState, event: Event): void
     return;
   }
   event.stopPropagation();
-  const value = String((event as CustomEvent<unknown>).detail ?? "");
+  const value = "detail" in event ? String(event.detail ?? "") : "";
   if (value === String(scope.value ?? "")) {
     return;
   }

package/src/behaviors/tabs.ts

@@ -33,7 +33,6 @@ export interface TabsState {
   label?: string;
   activation?: string;
   orientation?: string;
-  [key: string]: unknown;
 }
 
 /** A tab element with the property accessors its document installs. */
@@ -87,9 +86,7 @@ function watchTabs(host: HTMLElement): void {
 /** The tablist an event's `currentTarget` is. */
 function hostOf(event: Event): TabsElement | null {
   const target = event.currentTarget;
-  return target instanceof HTMLElement && target.localName === TABS
-    ? (target as TabsElement)
-    : null;
+  return target instanceof HTMLElement && target.localName === TABS ? target : null;
 }
 
 /** Whether `host` is the nearest tablist around `node` — a nested strip owns its own keys. */
@@ -146,12 +143,12 @@ export function focusTab(tabs: TabElement[], index: number): TabElement | null {
  *
  * @param host The `jx-tabs` element.
  */
-export function syncTabs(host: HTMLElement): void {
+export function syncTabs(host: TabsElement): void {
   const tabs = tabsOf(host);
   if (tabs.length === 0) {
     return;
   }
-  const selected = String((host as TabsElement).selected ?? "");
+  const selected = String(host.selected ?? "");
   const found = tabs.findIndex((tab) => valueOf(tab) === selected);
   const caret = found === -1 ? 0 : found;
   for (const [at, tab] of tabs.entries()) {
@@ -228,7 +225,7 @@ export function onTabsSelect(scope: TabsState, event: Event): void {
     return;
   }
   event.stopPropagation();
-  const value = String((event as CustomEvent<unknown>).detail ?? "");
+  const value = "detail" in event ? String(event.detail ?? "") : "";
   if (value === String(scope.selected ?? "")) {
     return;
   }

package/src/behaviors/textfield.ts

@@ -12,6 +12,23 @@
  * @docs extending/ui-kit
  */
 
+/** The reactive scope a `jx-textfield` document hands its sidecar. */
+export interface TextfieldState {
+  /** The field's text. */
+  value?: string;
+  /** This element's own id stem, minted at mount. */
+  uid?: string;
+}
+
+/** The reactive scope a `jx-field` row hands its sidecar. */
+export interface FieldRowState {
+  /** This row's own id stem, minted at mount. */
+  uid?: string;
+}
+
+/** A kit control a `jx-field` row names, through the properties its definition observes. */
+type NameableControl = Element & { labelledby?: string; describedby?: string };
+
 /** The element's own native control. */
 function controlOf(host: HTMLElement): HTMLInputElement | HTMLTextAreaElement | null {
   return host.querySelector<HTMLInputElement | HTMLTextAreaElement>('[part="input"]');
@@ -63,12 +80,12 @@ function hostOf(event: Event): HTMLElement | null {
  * @param state The element's reactive scope, whose `value` this empties.
  * @param event The click on the clear button.
  */
-export function clearField(state: Record<string, unknown>, event: Event): void {
+export function clearField(state: TextfieldState, event: Event): void {
   const host = hostOf(event);
   if (!host) {
     return;
   }
-  state["value"] = "";
+  state.value = "";
   focusField(host);
   host.dispatchEvent(new Event("input", { bubbles: true }));
   host.dispatchEvent(new Event("change", { bubbles: true }));
@@ -85,19 +102,24 @@ let minted = 0;
  *
  * @param state The element's reactive scope, whose `uid` this writes.
  */
-export function mintFieldId(state: Record<string, unknown>): void {
+export function mintFieldId(state: TextfieldState): void {
   minted += 1;
-  state["uid"] = `jx-tf-${minted}`;
+  state.uid = `jx-tf-${minted}`;
 }
 
 let namedRows = 0;
 
 /** Whether an element's DEFINITION says it can be named — that it observes `labelledby`. */
 function observesNaming(el: Element): boolean {
-  const def = customElements.get(el.localName) as
-    | { observedAttributes?: readonly string[] }
-    | undefined;
-  return def?.observedAttributes?.includes("labelledby") === true;
+  const def = customElements.get(el.localName);
+  /* `observedAttributes` is a static member the platform reads off the constructor, which the DOM
+     types do not declare, so it is probed by name and shape. */
+  return (
+    def !== undefined &&
+    "observedAttributes" in def &&
+    Array.isArray(def.observedAttributes) &&
+    def.observedAttributes.includes("labelledby")
+  );
 }
 
 /**
@@ -141,24 +163,23 @@ function observesNaming(el: Element): boolean {
  * @param state The row's reactive scope, whose `uid` this writes.
  * @param host The `jx-field` element, whose slotted control this names.
  */
-export function nameFieldControl(state: Record<string, unknown>, host: HTMLElement): void {
+export function nameFieldControl(state: FieldRowState, host: HTMLElement): void {
   namedRows += 1;
   const uid = `jx-field-${namedRows}`;
-  state["uid"] = uid;
+  state.uid = uid;
 
   /* The row's OWN parts, found among its children rather than by a descendant query. Both spellings
      return the same node for a rendered row — the row's own parts precede everything slotted, so
      nothing in the suite can tell them apart — but a `[part]` lookup that may descend is one
      refactor away from reaching into a nested row's parts. */
   const own = (name: string) => [...host.children].find((el) => el.getAttribute("part") === name);
-  const control = own("control")?.firstElementChild;
+  const control: NameableControl | null | undefined = own("control")?.firstElementChild;
   if (!control || !observesNaming(control)) {
     return;
   }
-  const target = control as unknown as Record<string, unknown>;
-  target["labelledby"] ||= `${uid}-label`;
+  control.labelledby ||= `${uid}-label`;
   const help = own("help");
   if (help && (help.firstElementChild !== null || help.textContent !== "")) {
-    target["describedby"] ||= `${uid}-help`;
+    control.describedby ||= `${uid}-help`;
   }
 }

package/src/behaviors/toast-host.ts

@@ -42,11 +42,13 @@ const FOCUSABLE =
 
 /** The reactive scope a `jx-toast-host` document hands its handlers. */
 export interface ToastHostState {
-  /** The key that moves focus into the stack. Empty turns the gesture off. */
-  hotkey: string;
+  /**
+   * The key that moves focus into the stack. Empty turns the gesture off, and so does null, which
+   * is what a host clearing the reflected `hotkey` attribute leaves.
+   */
+  hotkey: string | null;
   /** `polite`, `assertive` or `off`. */
   live: string;
-  [key: string]: unknown;
 }
 
 /** Where focus was when the reader entered the stack, so it can be given back. */
@@ -208,13 +210,14 @@ export function onStackClose(_state: ToastHostState, event: Event): void {
  * @param host The element itself.
  */
 export function onHostMount(state: ToastHostState, host: HTMLElement): void {
-  const root = host.getRootNode() as Document | ShadowRoot;
-  const onKeydown = (event: Event): void => {
-    const press = event as KeyboardEvent;
-    if (press.altKey || press.ctrlKey || press.metaKey) {
+  /* The document, the shadow root, or — for a detached host — its topmost ancestor: every one of
+     them is a node a keydown from inside it reaches. */
+  const root = host.getRootNode();
+  const onKeydown = (press: Event): void => {
+    if (!(press instanceof KeyboardEvent) || press.altKey || press.ctrlKey || press.metaKey) {
       return;
     }
-    const wanted = typeof state.hotkey === "string" ? state.hotkey : "";
+    const wanted = state.hotkey ?? "";
     if (wanted !== "" && press.key === wanted) {
       if (focusStack(host)) {
         press.preventDefault();