@jxsuite/ui 0.5.1 → 0.7.0

package/src/behaviors/toast.ts

@@ -45,9 +45,11 @@ export interface ToastState {
   timeout: number;
   /** `info`, `positive`, `negative` or `warning`. */
   variant: string;
-  [key: string]: unknown;
 }
 
+/** A `jx-toast` element, with the `open` accessor its document installs. */
+type ToastElement = HTMLElement & { open?: boolean };
+
 /** One toast's clock: what is left of it, when this run started, and what is holding it. */
 interface Clock {
   timer: ReturnType<typeof setTimeout> | null;
@@ -60,25 +62,25 @@ interface Clock {
 }
 
 /** Which hold an event asks for. Three channels, because they overlap and must not cancel. */
-const HOLD_REASON: Readonly<Record<string, string>> = {
-  focusin: "focus",
-  focusout: "focus",
-  [TOAST_PAUSE]: "stack",
-  [TOAST_RESUME]: "stack",
-  pointerenter: "pointer",
-  pointerleave: "pointer",
-  pointerout: "pointer",
-  pointerover: "pointer",
-};
+const HOLD_REASON: ReadonlyMap<string, "focus" | "pointer" | "stack"> = new Map([
+  ["focusin", "focus"],
+  ["focusout", "focus"],
+  [TOAST_PAUSE, "stack"],
+  [TOAST_RESUME, "stack"],
+  ["pointerenter", "pointer"],
+  ["pointerleave", "pointer"],
+  ["pointerout", "pointer"],
+  ["pointerover", "pointer"],
+]);
 
 /** Each scope's clock. */
-const clocks = new WeakMap<object, Clock>();
+const clocks = new WeakMap<ToastState, Clock>();
 
 /** The element each scope belongs to, learned at mount. */
-const hosts = new WeakMap<object, HTMLElement>();
+const hosts = new WeakMap<ToastState, HTMLElement>();
 
 /** This scope's clock, minted on first sight. */
-function clockOf(state: object): Clock {
+function clockOf(state: ToastState): Clock {
   const found = clocks.get(state);
   if (found) {
     return found;
@@ -106,7 +108,7 @@ function ownerOf(event: Event): HTMLElement | null {
  * @returns True when the destination is still inside the element the listener is bound to.
  */
 export function staysInside(event: Event): boolean {
-  const to = (event as { relatedTarget?: unknown }).relatedTarget;
+  const to = "relatedTarget" in event ? event.relatedTarget : null;
   const from = event.currentTarget;
   return to instanceof Node && from instanceof Node && from.contains(to);
 }
@@ -147,12 +149,11 @@ function schedule(state: ToastState): void {
  * @param host The `jx-toast` element.
  * @param reason Why it closed.
  */
-export function closeToast(host: HTMLElement, reason: ToastCloseReason): void {
-  const el = host as HTMLElement & { open?: boolean };
-  if (el.open !== true) {
+export function closeToast(host: ToastElement, reason: ToastCloseReason): void {
+  if (host.open !== true) {
     return;
   }
-  el.open = false;
+  host.open = false;
   host.dispatchEvent(new CustomEvent("close", { bubbles: true, detail: { reason } }));
 }
 
@@ -207,7 +208,7 @@ export function onToastUnmount(state: ToastState): void {
  */
 export function onToastHold(state: ToastState, event: Event): void {
   const clock = clockOf(state);
-  const reason = HOLD_REASON[event.type] ?? event.type;
+  const reason = HOLD_REASON.get(event.type) ?? event.type;
   if (clock.timer !== null) {
     clock.remaining = Math.max(1, clock.remaining - (Date.now() - clock.startedAt));
   }
@@ -225,7 +226,7 @@ export function onToastRelease(state: ToastState, event: Event): void {
   if (staysInside(event)) {
     return;
   }
-  clockOf(state).holds.delete(HOLD_REASON[event.type] ?? event.type);
+  clockOf(state).holds.delete(HOLD_REASON.get(event.type) ?? event.type);
   schedule(state);
 }
 

package/src/behaviors/toolbar.ts

@@ -63,7 +63,6 @@ const TEXT_TYPES = new Set(["", "text", "search", "url", "tel", "password", "ema
 export interface ToolbarState {
   orientation?: string;
   label?: string;
-  [key: string]: unknown;
 }
 
 /** A toolbar item: a control, or the kit element that wraps one. */
@@ -98,7 +97,7 @@ function itemFor(bar: HTMLElement, node: HTMLElement): ItemElement {
   let item: ItemElement = node;
   for (let el = node.parentElement; el && el !== bar; el = el.parentElement) {
     if (el.localName.includes("-")) {
-      item = el as ItemElement;
+      item = el;
     }
   }
   return item;
@@ -249,7 +248,7 @@ function atEdge(node: HTMLInputElement | HTMLTextAreaElement, forward: boolean):
     // A live selection is a gesture in progress; the arrow that collapses it is the control's.
     return false;
   }
-  return forward ? start >= String(node.value ?? "").length : start <= 0;
+  return forward ? start >= node.value.length : start <= 0;
 }
 
 /** Whether `node` is a control with a text caret the arrow keys move. */

package/src/behaviors/tooltip.ts

@@ -18,18 +18,18 @@
  * authors to prefer, and on Firefox and Safari it is the shape that shows nothing at all without
  * this module.
  *
- * "AN OLDER ENGINE" INCLUDES THE DESKTOP APP. Studio ships inside Electrobun's CEF, and the pinned
- * release is Chromium 147 (`vendor/electrobun/package/src/shared/cef-version.ts`) — five releases
- * short of the attribute. So until that bump reaches 152 the ONLY end-user path to Studio runs the
- * fallback for every hinted button in its chrome, several hundred of them, and this module is not a
- * corner for other people's browsers but the behaviour a user sees. Three consequences are designed
- * for rather than tolerated: focus opens the tip only when it is KEYBOARD focus, the way the
- * platform's interest-on-focus does, so a click does not pin a tip open; Escape is ONE listener per
- * root shared by every bound tip, not one per tip on the document, so a keystroke in Studio walks
- * one handler rather than one per button; and a tip that is MOVED — a keyed `$map` reordering its
- * rows, a button re-parented into a toolbar — keeps its binding, because the runtime fires
- * `disconnectedCallback` for a move and never re-runs `onMount`, so an unmount that disposed at
- * once would strip a reordered row of its tooltip for good.
+ * "AN OLDER ENGINE" INCLUDES THE DESKTOP APP. Studio ships inside Electron, whose bundled Chromium
+ * trails the stable channel and can sit releases short of the attribute. Until Electron's Chromium
+ * reaches it the ONLY end-user path to Studio runs the fallback for every hinted button in its
+ * chrome, several hundred of them, and this module is not a corner for other people's browsers but
+ * the behaviour a user sees. Three consequences are designed for rather than tolerated: focus opens
+ * the tip only when it is KEYBOARD focus, the way the platform's interest-on-focus does, so a click
+ * does not pin a tip open; Escape is ONE listener per root shared by every bound tip, not one per
+ * tip on the document, so a keystroke in Studio walks one handler rather than one per button; and a
+ * tip that is MOVED — a keyed `$map` reordering its rows, a button re-parented into a toolbar —
+ * keeps its binding, because the runtime fires `disconnectedCallback` for a move and never re-runs
+ * `onMount`, so an unmount that disposed at once would strip a reordered row of its tooltip for
+ * good.
  *
  * IT ADDS LISTENERS TO AN ELEMENT THE KIT DOES NOT OWN, and that is said out loud rather than left
  * to be discovered in review. specs/ui.md §2 principle 5 forbids WRITING ATTRIBUTES or styles on
@@ -51,8 +51,9 @@
  * @docs extending/ui-kit
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
+
 import { close, openAt, supportsAnchorPositioning } from "./popover.ts";
-import type { PopoverElement } from "./popover.ts";
 
 /** The reactive scope a `jx-tooltip` document hands its handlers. */
 export interface TooltipState {
@@ -66,9 +67,26 @@ export interface TooltipState {
   placement?: string;
   /** Whether the platform is placing the tip against the control it was shown from. */
   anchored?: boolean;
-  [key: string]: unknown;
+  /**
+   * The id of the control the tip is wired to, from the reflected `for` attribute; null when a host
+   * clears it.
+   */
+  for?: string | null;
+}
+
+/** The reactive scope a hinted kit control hands {@link mintHintId}. */
+export interface HintState {
+  /** The control's own id stem, minted at mount. */
+  uid?: string;
 }
 
+/**
+ * The root a tip's id lookups run against. An element's root node is the Document, the
+ * DocumentFragment or ShadowRoot holding it, or — while it is detached — its topmost ancestor
+ * element. Every one of them can be queried; only the first two can look an id up directly.
+ */
+type LookupRoot = ParentNode & { getElementById?: (elementId: string) => HTMLElement | null };
+
 /**
  * How long a tip stays up after the pointer leaves the control, in milliseconds.
  *
@@ -113,7 +131,7 @@ function watchEscape(root: Node, dismiss: () => void): () => void {
   if (!entry) {
     const set = new Set<() => void>();
     const listener = (event: Event): void => {
-      if ((event as KeyboardEvent).key !== "Escape") {
+      if (!(event instanceof KeyboardEvent) || event.key !== "Escape") {
         return;
       }
       for (const fn of set) {
@@ -197,7 +215,7 @@ const watchers = new WeakMap<object, () => void>();
  */
 export function supportsInterestInvokers(): boolean {
   return (
-    typeof HTMLButtonElement === "function" && "interestForElement" in HTMLButtonElement.prototype
+    isFunction(globalThis.HTMLButtonElement) && "interestForElement" in HTMLButtonElement.prototype
   );
 }
 
@@ -216,12 +234,12 @@ function platformOwns(tip: HTMLElement, trigger: Element): boolean {
 
 /** Show the tip from its control, so the platform knows what the hint belongs to. */
 function showTip(tip: HTMLElement, source: Element | null): void {
-  openAt(tip as PopoverElement, source);
+  openAt(tip, source);
 }
 
 /** Hide the tip. `open` and `data-open` follow from the platform's own toggle. */
 function hideTip(tip: HTMLElement): void {
-  close(tip as PopoverElement);
+  close(tip);
 }
 
 /**
@@ -291,7 +309,7 @@ export function bindTooltip(tip: HTMLElement, trigger: Element): () => void {
   };
   const showLater = (): void => {
     cancel();
-    const delay = Number((tip as { delay?: unknown }).delay) || 0;
+    const delay = "delay" in tip ? Number(tip.delay) || 0 : 0;
     showTimer = setTimeout(show, delay);
   };
   const hideLater = (): void => {
@@ -389,8 +407,10 @@ export function bindTooltip(tip: HTMLElement, trigger: Element): () => void {
  * miss.
  */
 function triggerOf(state: TooltipState, tip: HTMLElement): HTMLElement | null {
-  const root = tip.getRootNode() as Document | ShadowRoot;
-  const named = typeof state["for"] === "string" ? state["for"] : "";
+  /* SAFETY: `tip` is an Element, and the root node of an element is never a Text, Comment or Attr
+     node: it is a Document, a DocumentFragment or an Element, each of them a ParentNode. */
+  const root = tip.getRootNode() as LookupRoot;
+  const named = state.for ?? "";
   const byFor = named === "" ? null : (root.getElementById?.(named) ?? null);
   if (byFor) {
     return byFor;
@@ -414,7 +434,9 @@ function anchorOf(state: TooltipState, tip: HTMLElement): HTMLElement | null {
   if (wired) {
     return wired;
   }
-  const root = tip.getRootNode() as Document | ShadowRoot;
+  /* SAFETY: `tip` is an Element, and the root node of an element is never a Text, Comment or Attr
+     node: it is a Document, a DocumentFragment or an Element, each of them a ParentNode. */
+  const root = tip.getRootNode() as LookupRoot;
   const own = tip.id;
   if (!/^[\w-]+$/.test(own)) {
     return null;
@@ -464,7 +486,7 @@ export function placeTooltip(state: TooltipState, tip: HTMLElement): void {
       state.flipped = true;
     }
   };
-  if (typeof requestAnimationFrame === "function") {
+  if (isFunction(globalThis.requestAnimationFrame)) {
     requestAnimationFrame(measure);
   } else {
     measure();
@@ -516,7 +538,7 @@ export function measureAnchoredFlip(state: TooltipState, tip: HTMLElement): () =
     }
     state.flipped = own.bottom <= box.top;
   };
-  if (!anchor || typeof requestAnimationFrame !== "function") {
+  if (!anchor || !isFunction(globalThis.requestAnimationFrame)) {
     /* No control to be on a side of, or no frames to coalesce to: one synchronous reading, which
        is nothing at all in the first case, and no watch. */
     measure();
@@ -539,7 +561,7 @@ export function measureAnchoredFlip(state: TooltipState, tip: HTMLElement): () =
      listener before it scrolls. Removal keys on `capture` alone, which is why it is spelled twice. */
   window.addEventListener("scroll", schedule, { capture: true, passive: true });
   window.addEventListener("resize", schedule);
-  const observer = typeof ResizeObserver === "function" ? new ResizeObserver(schedule) : null;
+  const observer = isFunction(globalThis.ResizeObserver) ? new ResizeObserver(schedule) : null;
   if (observer) {
     observer.observe(tip);
     observer.observe(anchor);
@@ -576,8 +598,8 @@ export function onTooltipBeforeToggle(state: TooltipState, event: Event): void {
   if (!(tip instanceof HTMLElement)) {
     return;
   }
-  const opening = (event as { newState?: string }).newState === "open";
-  const { source } = event as Event & { source?: unknown };
+  const opening = "newState" in event && event.newState === "open";
+  const source = "source" in event ? event.source : null;
   const from = source instanceof Element ? source : anchorOf(state, tip);
   state.anchored = opening && from !== null;
   if (!opening) {
@@ -602,7 +624,7 @@ export function onTooltipToggle(state: TooltipState, event: Event): void {
   if (!(tip instanceof HTMLElement)) {
     return;
   }
-  const opening = (event as { newState?: string }).newState === "open";
+  const opening = "newState" in event && event.newState === "open";
   state.open = opening;
   if (!opening) {
     // A closed tip has no side, and the watch that was following it has nothing left to follow.
@@ -713,7 +735,7 @@ let mintedHints = 0;
  * @param state The control's reactive scope, whose `uid` this writes.
  * @param host The `jx-action-button`, `jx-button` or `jx-switch` element.
  */
-export function mintHintId(state: Record<string, unknown>, host: HTMLElement): void {
+export function mintHintId(state: HintState, host: HTMLElement): void {
   mintedHints += 1;
-  state["uid"] = `${host.localName}-${mintedHints}`;
+  state.uid = `${host.localName}-${mintedHints}`;
 }

package/src/behaviors/tree.ts

@@ -50,6 +50,8 @@
  * @docs extending/ui-kit
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
+
 /** The tag of the tree. */
 const TREE = "jx-tree";
 /** The tag of one row. */
@@ -100,7 +102,6 @@ export interface TreeState {
   anchor?: string;
   padtop?: number;
   padbottom?: number;
-  [key: string]: unknown;
 }
 
 /** A row element with the property accessors its own document installs. */
@@ -153,9 +154,7 @@ const handoffs = new WeakMap<HTMLElement, Handoff>();
 /** The tree an event's `currentTarget` is. */
 function hostOf(event: Event): TreeElement | null {
   const target = event.currentTarget;
-  return target instanceof HTMLElement && target.localName === TREE
-    ? (target as TreeElement)
-    : null;
+  return target instanceof HTMLElement && target.localName === TREE ? target : null;
 }
 
 /** Whether `tree` is the nearest tree around `node` — a key inside a nested tree is its own. */
@@ -209,7 +208,7 @@ function isDisabled(item: ItemElement): boolean {
  */
 function labelOf(item: ItemElement): string {
   const named = propOf(item, "label", "label");
-  return named === "" ? (item.textContent ?? "") : named;
+  return named === "" ? item.textContent : named;
 }
 
 /**
@@ -255,12 +254,12 @@ export function itemsOf(
  *
  * @param tree The `jx-tree` element.
  */
-export function syncTree(tree: HTMLElement): void {
+export function syncTree(tree: TreeElement): void {
   const items = itemsOf(tree, { includeDisabled: true });
   if (items.length === 0) {
     return;
   }
-  const current = String((tree as TreeElement).current ?? "");
+  const current = String(tree.current ?? "");
   const enabled = items.filter((item) => !isDisabled(item));
   const caret = enabled.find((item) => valueOf(item) === current) ?? enabled[0] ?? null;
   for (const item of items) {
@@ -425,8 +424,19 @@ function activeIndex(items: ItemElement[], target: EventTarget | null): number {
   );
 }
 
+/**
+ * What a tree event carries: a row's value for `change` and `activate`, else the event's own detail
+ * record.
+ */
+type TreeEventDetail =
+  | string
+  | TreeExpandDetail
+  | TreeMoveDetail
+  | TreeSelectDetail
+  | TreeTypeaheadDetail;
+
 /** Say a public thing, from the tree, so `e.target` is the element a host wrote. */
-function announce(host: HTMLElement, name: string, detail: unknown): void {
+function announce(host: HTMLElement, name: string, detail: TreeEventDetail): void {
   host.dispatchEvent(new CustomEvent(name, { bubbles: true, detail }));
 }
 
@@ -441,7 +451,7 @@ function moveTo(host: HTMLElement, scope: TreeState, item: ItemElement): void {
   scope.current = valueOf(item);
   syncTree(host);
   item.focus();
-  if (typeof item.scrollIntoView === "function") {
+  if (isFunction(item.scrollIntoView)) {
     item.scrollIntoView({ block: "nearest" });
   }
   announce(host, "change", valueOf(item));

package/src/color.ts

@@ -25,6 +25,9 @@
  * @docs extending/ui-kit
  */
 
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
 /** An sRGB colour. `r`, `g` and `b` are 0-255 and need not be integers; `a` is 0-1. */
 export interface Rgb {
   r: number;
@@ -65,6 +68,18 @@ export function clamp(value: number, min: number, max: number): number {
   return value < min ? min : value > max ? max : value;
 }
 
+/**
+ * Which way each arrow key moves a colour element's value: Up and Right increase, Down and Left
+ * decrease. `jx-color-area` measures its vertical axis upward from the bottom edge, so ArrowUp
+ * raising brightness is the same rule as ArrowUp raising a slider's value.
+ */
+export const ARROW_SIGN: ReadonlyMap<string, -1 | 1> = new Map([
+  ["ArrowDown", -1],
+  ["ArrowLeft", -1],
+  ["ArrowRight", 1],
+  ["ArrowUp", 1],
+]);
+
 /**
  * `value` snapped to the grid `step` describes, measured from `min` and held inside `[min, max]`.
  *
@@ -427,7 +442,7 @@ export function preferredInk(rgb: Rgb): "black" | "white" {
  * @param color The colour, as it was written.
  * @returns `"black"`, `"white"`, or `""`.
  */
-export function inkOn(color: unknown): string {
-  const parsed = typeof color === "string" ? parseColor(color) : null;
+export function inkOn(color: JsonValue | undefined): string {
+  const parsed = isString(color) ? parseColor(color) : null;
   return parsed ? preferredInk({ ...parsed, a: 1 }) : "";
 }

package/src/documents.ts

@@ -4,7 +4,7 @@
  * bytes the shell runs.
  */
 import { overlayScopeFor } from "@jxsuite/schema/overlays";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JsonPrimitive, JxDocument } from "@jxsuite/schema/types";
 import jxAccordion from "../components/jx-accordion.json";
 import jxAccordionItem from "../components/jx-accordion-item.json";
 import jxActionButton from "../components/jx-action-button.json";
@@ -44,48 +44,74 @@ import jxTreeItem from "../components/jx-tree-item.json";
 import jxToastHost from "../components/jx-toast-host.json";
 import jxToolbar from "../components/jx-toolbar.json";
 
+/**
+ * A value as TypeScript types a JSON module import. Under the root config's
+ * `exactOptionalPropertyTypes` that is always a `JsonValue`, but `packages/desktop` compiles this
+ * file without the flag, and there an array of differently shaped objects is normalised by giving
+ * each object the others' keys as `?: undefined`, which `JsonValue` refuses.
+ */
+type ImportedJson =
+  | JsonPrimitive
+  | undefined
+  | readonly ImportedJson[]
+  | { readonly [key: string]: ImportedJson };
+
+/**
+ * A bundled component file as the document the runtime defines it from.
+ *
+ * @param {Readonly<Record<string, ImportedJson>>} json - One of the `components/*.json` imports
+ *   above
+ * @returns {JxDocument} The same object, typed as the document it is
+ */
+function kitDocument(json: Readonly<Record<string, ImportedJson>>): JxDocument {
+  /* SAFETY: every argument is a `components/*.json` file of this package, and `conformance.test.ts`
+     validates each entry of `documents` against the Jx document schema (ui.md §3.2), so the JSON
+     is a JxDocument; TypeScript only sees the literal shape the JSON import infers. */
+  return json as JxDocument;
+}
+
 /** Tag name → document, in registration order (a document's `$elements` come before it). */
-export const documents: Readonly<Record<string, JxDocument>> = {
-  "jx-icon": jxIcon as unknown as JxDocument,
-  "jx-spinner": jxSpinner as unknown as JxDocument,
+export const documents = {
+  "jx-icon": kitDocument(jxIcon),
+  "jx-spinner": kitDocument(jxSpinner),
   // Before the buttons: each renders a `jx-tooltip` for its `hint`.
-  "jx-tooltip": jxTooltip as unknown as JxDocument,
-  "jx-button": jxButton as unknown as JxDocument,
-  "jx-action-button": jxActionButton as unknown as JxDocument,
-  "jx-menu-item": jxMenuItem as unknown as JxDocument,
-  "jx-menu": jxMenu as unknown as JxDocument,
-  "jx-popover": jxPopover as unknown as JxDocument,
-  "jx-textfield": jxTextfield as unknown as JxDocument,
-  "jx-checkbox": jxCheckbox as unknown as JxDocument,
-  "jx-switch": jxSwitch as unknown as JxDocument,
-  "jx-number-field": jxNumberField as unknown as JxDocument,
-  "jx-select": jxSelect as unknown as JxDocument,
-  "jx-option": jxOption as unknown as JxDocument,
-  "jx-listbox": jxListbox as unknown as JxDocument,
-  "jx-combobox": jxCombobox as unknown as JxDocument,
-  "jx-action-group": jxActionGroup as unknown as JxDocument,
-  "jx-toolbar": jxToolbar as unknown as JxDocument,
-  "jx-tab": jxTab as unknown as JxDocument,
-  "jx-tab-panel": jxTabPanel as unknown as JxDocument,
-  "jx-tabs": jxTabs as unknown as JxDocument,
-  "jx-tree-item": jxTreeItem as unknown as JxDocument,
-  "jx-tree": jxTree as unknown as JxDocument,
-  "jx-accordion-item": jxAccordionItem as unknown as JxDocument,
-  "jx-accordion": jxAccordion as unknown as JxDocument,
-  "jx-divider": jxDivider as unknown as JxDocument,
-  "jx-split": jxSplit as unknown as JxDocument,
-  "jx-kbd": jxKbd as unknown as JxDocument,
-  "jx-dot": jxDot as unknown as JxDocument,
-  "jx-field": jxField as unknown as JxDocument,
-  "jx-dialog": jxDialog as unknown as JxDocument,
-  "jx-toast": jxToast as unknown as JxDocument,
-  "jx-toast-host": jxToastHost as unknown as JxDocument,
-  "jx-color-area": jxColorArea as unknown as JxDocument,
-  "jx-color-slider": jxColorSlider as unknown as JxDocument,
-  "jx-swatch": jxSwatch as unknown as JxDocument,
-  "jx-swatch-group": jxSwatchGroup as unknown as JxDocument,
-  "jx-color-field": jxColorField as unknown as JxDocument,
-};
+  "jx-tooltip": kitDocument(jxTooltip),
+  "jx-button": kitDocument(jxButton),
+  "jx-action-button": kitDocument(jxActionButton),
+  "jx-menu-item": kitDocument(jxMenuItem),
+  "jx-menu": kitDocument(jxMenu),
+  "jx-popover": kitDocument(jxPopover),
+  "jx-textfield": kitDocument(jxTextfield),
+  "jx-checkbox": kitDocument(jxCheckbox),
+  "jx-switch": kitDocument(jxSwitch),
+  "jx-number-field": kitDocument(jxNumberField),
+  "jx-select": kitDocument(jxSelect),
+  "jx-option": kitDocument(jxOption),
+  "jx-listbox": kitDocument(jxListbox),
+  "jx-combobox": kitDocument(jxCombobox),
+  "jx-action-group": kitDocument(jxActionGroup),
+  "jx-toolbar": kitDocument(jxToolbar),
+  "jx-tab": kitDocument(jxTab),
+  "jx-tab-panel": kitDocument(jxTabPanel),
+  "jx-tabs": kitDocument(jxTabs),
+  "jx-tree-item": kitDocument(jxTreeItem),
+  "jx-tree": kitDocument(jxTree),
+  "jx-accordion-item": kitDocument(jxAccordionItem),
+  "jx-accordion": kitDocument(jxAccordion),
+  "jx-divider": kitDocument(jxDivider),
+  "jx-split": kitDocument(jxSplit),
+  "jx-kbd": kitDocument(jxKbd),
+  "jx-dot": kitDocument(jxDot),
+  "jx-field": kitDocument(jxField),
+  "jx-dialog": kitDocument(jxDialog),
+  "jx-toast": kitDocument(jxToast),
+  "jx-toast-host": kitDocument(jxToastHost),
+  "jx-color-area": kitDocument(jxColorArea),
+  "jx-color-slider": kitDocument(jxColorSlider),
+  "jx-swatch": kitDocument(jxSwatch),
+  "jx-swatch-group": kitDocument(jxSwatchGroup),
+  "jx-color-field": kitDocument(jxColorField),
+} as const satisfies Readonly<Record<string, JxDocument>>;
 
 /** Every tag the kit defines. */
 export const KIT_TAGS: readonly string[] = Object.keys(documents);
@@ -104,7 +130,7 @@ export const KIT_TAGS: readonly string[] = Object.keys(documents);
  * asks the same question of a project's `*.class.json` definitions, and two derivations of "what
  * makes a tag a popover" is two chances to disagree about one project.
  */
-const KIT_SCOPE = overlayScopeFor(Object.values(documents) as JxElement[]);
+const KIT_SCOPE = overlayScopeFor(Object.values(documents));
 
 /** Tags whose definition declares `popover`. */
 export const POPOVER_TAGS: ReadonlySet<string> = KIT_SCOPE.popoverTags ?? new Set();

package/src/icons.ts

@@ -5,6 +5,8 @@
  *
  * @docs extending/ui-kit
  */
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
 import manifest from "../icons/manifest.json";
 import { ICON_VIEW_BOX, ICON_WEIGHTS } from "./icons-build.ts";
 import type { IconManifest, IconWeight } from "./icons-build.ts";
@@ -12,7 +14,8 @@ import type { IconManifest, IconWeight } from "./icons-build.ts";
 export { ICON_VIEW_BOX, ICON_WEIGHTS } from "./icons-build.ts";
 export type { IconWeight } from "./icons-build.ts";
 
-const { icons } = manifest as IconManifest;
+const iconManifest: IconManifest = manifest;
+const { icons } = iconManifest;
 
 /** Every icon name the kit ships, sorted. */
 export const ICON_NAMES: readonly string[] = Object.keys(icons);
@@ -33,10 +36,11 @@ const warned = new Set<string>();
  * every listed icon carries; a name it lacks warns once and draws nothing, so a typo shows as a gap
  * rather than a crash or a wrong glyph.
  *
- * Called from the `jx-icon` document with the element's own `name` and `weight` state.
+ * Called from the `jx-icon` document with the element's own `name` and `weight` state. Both are
+ * declared strings, but a property write can store any value, so neither is trusted to be one.
  */
-export function iconPath(name: unknown, weight: unknown): string {
-  const key = typeof name === "string" ? name : "";
+export function iconPath(name: JsonValue | undefined, weight: JsonValue | undefined): string {
+  const key = isString(name) ? name : "";
   const entry = icons[key];
   if (!entry) {
     if (key && !warned.has(key)) {
@@ -45,11 +49,9 @@ export function iconPath(name: unknown, weight: unknown): string {
     }
     return "";
   }
-  const w = (ICON_WEIGHTS as readonly string[]).includes(String(weight))
-    ? (weight as IconWeight)
-    : "regular";
+  const w = ICON_WEIGHTS.find((candidate) => candidate === String(weight)) ?? "regular";
   return entry[w] ?? entry.regular ?? "";
 }
 
 /** The viewBox `jx-icon` draws on; the manifest's, so a rebuilt manifest cannot drift from it. */
-export const iconViewBox: string = (manifest as IconManifest).viewBox || ICON_VIEW_BOX;
+export const iconViewBox: string = iconManifest.viewBox || ICON_VIEW_BOX;

package/src/index.ts

@@ -10,6 +10,7 @@
  * @docs extending/ui-kit
  */
 import { defineElement, preloadDocument, preloadModule } from "@jxsuite/runtime";
+import type { JxScope } from "@jxsuite/runtime/types";
 import * as color from "./color.ts";
 import * as colorArea from "./behaviors/color-area.ts";
 import * as colorField from "./behaviors/color-field.ts";
@@ -50,8 +51,12 @@ export {
 /** The base every kit document resolves its references against. */
 export const KIT_BASE = "jx-ui:/components/";
 
-/** Behaviour modules, under the `$src` specifiers the documents use. */
-export const KIT_MODULES: Readonly<Record<string, Record<string, unknown>>> = {
+/**
+ * Behaviour modules, under the `$src` specifiers the documents use. The runtime reads each
+ * namespace's exports into scope, so every entry must be a `JxScope`: export name → value, narrowed
+ * where the runtime uses it.
+ */
+export const KIT_MODULES = {
   "jx-ui:/behaviors/color-area.ts": colorArea,
   "jx-ui:/behaviors/color-field.ts": colorField,
   "jx-ui:/behaviors/color-slider.ts": colorSlider,
@@ -74,7 +79,7 @@ export const KIT_MODULES: Readonly<Record<string, Record<string, unknown>>> = {
   "jx-ui:/behaviors/toast-host.ts": toastHost,
   "jx-ui:/color.ts": color,
   "jx-ui:/icons.ts": icons,
-};
+} as const satisfies Readonly<Record<string, JxScope>>;
 
 export interface RegisterUiOptions {
   /** Adopt the theme into the document as well. Default is true. */