@jxsuite/ui 0.1.0 → 0.3.0

package/components/jx-action-button.json

@@ -455,9 +455,15 @@
       "color": "var(--jx-accent-fg)"
     },
     "&[data-size=\"sm\"] > [part=\"control\"]": {
+      "$description": "The small action button is the kit's most packed control — Studio's toolbars, block action bar and inspector rows declare it some four hundred times — and it draws 4px under the kit's control height, which is the WCAG 2.2 SC 2.5.8 floor (ui.md §4.3). The `::before` is the hit area, jx-tab's close-button technique: an empty pseudo-element that reaches 2px past the drawn box on every side, so the region that accepts the pointer is exactly `--jx-control-h` square while the picture stays 20px. The inset is -3px and not -2px because an absolutely positioned box is offset from its containing block's PADDING edge, and this control draws a 1px border: the border width comes first, then half of the 4px the box is under (jx-tab's close button is borderless, so -4px was exact there). The control is already `position: relative` for the badge, so the pseudo-element needs nothing more. A 4px gap (jx-toolbar's) lets two extended neighbours abut; a compact jx-action-group packs its members touching, and its sheet zeroes the extension on that axis, because an extension over a neighbour's box would take the neighbour's clicks, and the criterion gives an overlapped strip to the target on top rather than to both; a default group's 2px gap leaves every member but the last at 22px on that axis, which ui.md §11 names as a non-claim. Held by target-size.test.ts and the conformance gate, both of which read the border and subtract it.",
       "minWidth": "calc(var(--jx-control-h) - 4px)",
       "minHeight": "calc(var(--jx-control-h) - 4px)",
-      "padding": "0 var(--jx-space-1)"
+      "padding": "0 var(--jx-space-1)",
+      "::before": {
+        "content": "\"\"",
+        "position": "absolute",
+        "inset": "-3px"
+      }
     },
     "&[data-size=\"lg\"] > [part=\"control\"]": {
       "minWidth": "calc(var(--jx-control-h) + 8px)",

package/components/jx-action-group.json

@@ -113,6 +113,14 @@
     },
     "&[data-compact] > jx-action-button > [part=\"control\"]:focus-visible": {
       "zIndex": "1"
+    },
+    "&[data-compact] > jx-action-button[data-size=\"sm\"] > [part=\"control\"]::before": {
+      "$description": "A small action button carries a `::before` that extends its hit area 2px past its drawn box on every side (an inset of -3px: the button's 1px border, then half the 4px it is under, because an absolutely positioned box is offset from the padding edge), so that a 20px picture accepts the pointer over the kit's 24px control height (WCAG 2.2 SC 2.5.8, ui.md §4.3). In a compact group the boxes TOUCH on the packed axis — no gap, and each border drawn over the last — so an extension there could reach nothing but the neighbour's own box, and the later sibling paints above the earlier one: the last 2px of every button but the last would activate the button after it. The criterion gives an overlapped area to the target on TOP, so the extension would buy the earlier button nothing and cost it a stolen strip. The default 2px gap is the other case: two extensions overlap by 2px there, the later member keeps the strip, and every small member but the last counts 22px on the packed axis, which is under the floor and which ui.md §11 names beside this one. The packed axis is therefore zeroed here — `0` is the padding edge, 1px inside the drawn border, and the button's own box accepts the pointer over that pixel — and the cross axis keeps its 2px past the drawn box, which reaches only the gap around the group: a compact group's small members are 24px tall and as wide as they draw, which ui.md §11 records as the one thing the technique cannot reach. The vertical variant swaps the axes, and its inline value is the button's own -3px for the same reason.",
+      "insetInline": "0"
+    },
+    "&[data-compact][data-orientation=\"vertical\"] > jx-action-button[data-size=\"sm\"] > [part=\"control\"]::before": {
+      "insetInline": "-3px",
+      "insetBlock": "0"
     }
   },
   "children": [

package/components/jx-button.json

@@ -297,9 +297,16 @@
       }
     },
     "&[data-size=\"sm\"] > [part=\"control\"]": {
+      "$description": "A small button draws 4px under the kit's control height, and the control height is the WCAG 2.2 SC 2.5.8 floor (ui.md §4.3), so the drawn box alone would be a 20px pointer target at the default density. The `::before` is the hit area: an empty pseudo-element that reaches 2px past the drawn box on every side, so what accepts the pointer is exactly `--jx-control-h` square while the picture stays small — jx-tab's close button's technique, and the criterion measures the region that accepts the pointer, not the paint. The inset is -3px and not -2px because an absolutely positioned box is offset from its containing block's PADDING edge, and this control draws a 1px border: the border width comes first, then half of the 4px the box is under. jx-tab's close button is borderless, which is why -4px was exact there, and why the number did not carry over unchanged. In a jx-toolbar (a 4px gap) two extended neighbours abut and neither loses a pixel; jx-action-group's own sheet zeroes the packed axis in a compact group, where the boxes touch and an extension could only steal a strip of the neighbour. Held by target-size.test.ts and the conformance gate, both of which read the border and subtract it.",
+      "position": "relative",
       "minHeight": "calc(var(--jx-control-h) - 4px)",
       "padding": "0 var(--jx-space-3)",
-      "fontSize": "var(--jx-text-sm)"
+      "fontSize": "var(--jx-text-sm)",
+      "::before": {
+        "content": "\"\"",
+        "position": "absolute",
+        "inset": "-3px"
+      }
     },
     "&[data-size=\"lg\"] > [part=\"control\"]": {
       "minHeight": "calc(var(--jx-control-h) + 8px)",

package/components/jx-checkbox.json

@@ -146,9 +146,16 @@
       "color": "var(--jx-fg-dim)"
     },
     "&[data-size=\"sm\"] > [part=\"control\"]": {
+      "$description": "The control is the `<label>` wrapping the input, and the label is the pointer target: a click anywhere on it toggles the box. At `sm` it draws 4px under the kit's control height, the WCAG 2.2 SC 2.5.8 floor (ui.md \u00a74.3), so the `::before` extends the hit area 2px beyond the box on every side — jx-tab's close-button technique, the same shape jx-button carries — and the region that accepts the pointer is `--jx-control-h` tall while the row stays 20px. -2px is exact here where jx-button needs -3px: an absolutely positioned box is offset from the PADDING edge, and the label draws no border, so its padding edge is its drawn edge. The label needs `position: relative` here for the pseudo-element to measure against; the input inside is 14px and needs nothing of its own, because the label around it is the target. Held by target-size.test.ts and the conformance gate.",
+      "position": "relative",
       "minHeight": "calc(var(--jx-control-h) - 4px)",
       "fontSize": "var(--jx-text-sm)",
-      "lineHeight": "var(--jx-leading-sm)"
+      "lineHeight": "var(--jx-leading-sm)",
+      "::before": {
+        "content": "\"\"",
+        "position": "absolute",
+        "inset": "-2px"
+      }
     },
     "&[data-size=\"sm\"] [part=\"input\"]": {
       "width": "calc(var(--jx-icon-size) - 2px)",

package/components/jx-combobox.json

@@ -321,6 +321,8 @@
       "fontSize": "var(--jx-text-lg)"
     },
     "& [part=\"toggle\"]": {
+      "$description": "The toggle sits inside the field's border, so it draws 2px under the field's height: 22px in a 24px field, 18px in an `sm` one. The `::before` is its hit area (WCAG 2.2 SC 2.5.8, ui.md \u00a74.3), the same shape as jx-textfield's clear button: an empty pseudo-element inset by half the difference between the drawn box and the kit's control height, -1px on a default field and -3px on a small one, so the region that accepts the pointer is `--jx-control-h` square at every size while the caret and its box stay where they were; on a large field the inset is positive and the pseudo-element is an invisible box inside a button already over the floor. `position: relative` is what the pseudo-element measures against, and it is new here: the toggle is a flex item of the field, not an absolutely placed one. The rotation the open state applies turns the pseudo-element with the button, which a square does not mind.",
+      "position": "relative",
       "display": "inline-flex",
       "alignItems": "center",
       "justifyContent": "center",
@@ -338,6 +340,11 @@
       "cursor": "pointer",
       "outline": "none",
       "transition": "rotate var(--jx-dur-1) var(--jx-ease-out)",
+      "::before": {
+        "content": "\"\"",
+        "position": "absolute",
+        "inset": "calc((var(--jx-combobox-h) - 2px - var(--jx-control-h)) / 2)"
+      },
       ":hover": {
         "color": "var(--jx-fg)"
       },

package/components/jx-menu-item.json

@@ -31,7 +31,7 @@
       "type": "string",
       "default": "",
       "attribute": "requires",
-      "description": "The one-sentence reason a disabled row cannot act, printed as its tooltip."
+      "description": "The one-sentence reason a DISABLED row cannot act, drawn as the row's native title while it is disabled and nowhere at all while it is not. The title is the whole contract here, and deliberately not the tooltip hybrid jx-button, jx-action-button and jx-switch ship: a disabled row can open no tip, so the hybrid collapses to its disabled half, and an ENABLED row never carries a requires — every Studio projection fills it from the registry's disabledReason, which is undefined for a command that can run, and a reason on a row that can act is a contradiction rather than a hint. Studio's menu surface also prints the same sentence as the row's visible description (`Needs …`), so a keyboard reader hears it without the title."
     },
     "checked": {
       "type": "string",

package/components/jx-switch.json

@@ -12,6 +12,11 @@
     "name",
     "size"
   ],
+  "$elements": [
+    {
+      "$ref": "./jx-tooltip.json"
+    }
+  ],
   "state": {
     "checked": {
       "type": "boolean",
@@ -23,13 +28,13 @@
       "type": "boolean",
       "default": false,
       "attribute": "disabled",
-      "description": "Cannot be flipped or focused. Disabled, never absent."
+      "description": "Cannot be flipped or focused. Disabled, never absent, and the hint moves from the tip to the row's title while it is: a disabled control cannot open a tip, and why the setting cannot be changed is exactly what the reader hovers to find out."
     },
     "hint": {
       "type": "string",
       "default": "",
       "attribute": "hint",
-      "description": "The tooltip on the row: why the setting is off, or what turning it on does. Empty removes the title rather than writing a blank one."
+      "description": "The tooltip on the row: what turning the setting on does, or why it cannot be changed. The same hybrid jx-button and jx-action-button ship. While the switch is ENABLED it is drawn as a jx-tooltip child of this element — shown on keyboard focus at once and on hover after the tip's delay, hoverable and dismissible with Escape (SC 1.4.13) — and the control names it in aria-describedby, so it is a description beside the name and never the name itself. While the switch is DISABLED it is the native title of the wrapping label instead, because a disabled control receives no focus and no pointer event and could never open a tip, while the platform still shows a title on hover. Never both at once; empty draws neither. ONE difference from the buttons, and it is the platform's rather than the kit's: the tip is wired by `for` alone and the row declares NO `interestfor`. Interest invokers are supported on `a`, `area` and `button` only — never on a label or an input — so the attribute here would show nothing on Chrome 152 while telling the tooltip sidecar the platform had the pair, which is the one combination that draws no tip on any engine. The sidecar binds the label on every engine instead, and that is what the switch pays for a tooltip: six listeners on the row and two on the tip, always, where a button pays them only where the platform lacks the attribute."
     },
     "label": {
       "type": "string",
@@ -66,6 +71,47 @@
       "default": "",
       "description": "Forwarded to the inner control as its tabindex, which is what makes a roving caret possible: the focusable node is the input inside, not the host and not the label that wraps it, so a jx-toolbar moving focus writes this rather than reaching into a child's internals. It is a PROPERTY ONLY (el.tabindex = \"0\") and deliberately not an observed attribute: written as an attribute it would land on the host as well, and a host carrying tabindex is itself focusable, so the one control would become two tab stops."
     },
+    "uid": {
+      "type": "string",
+      "default": "",
+      "description": "This row's own id stem, minted on mount by the tooltip sidecar. The label's id, the tip's id and the two attributes that wire one to the other are all built from it, so a consumer writes none of them and two hinted switches on one panel cannot collide. Empty until the mount microtask, which is why every binding that reads it guards on it."
+    },
+    "hasTip": {
+      "$expression": {
+        "operator": "&&",
+        "target": {
+          "operator": "!",
+          "target": {
+            "operator": "!",
+            "target": {
+              "$ref": "#/state/hint"
+            }
+          }
+        },
+        "value": {
+          "operator": "&&",
+          "target": {
+            "operator": "!",
+            "target": {
+              "$ref": "#/state/disabled"
+            }
+          },
+          "value": {
+            "operator": "!==",
+            "target": {
+              "$ref": "#/state/uid"
+            },
+            "value": ""
+          }
+        }
+      }
+    },
+    "onMount": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/tooltip.ts",
+      "$export": "mintHintId",
+      "description": "Mints the id stem the hint's tooltip is wired by. A document cannot: the closed operator set has no counter and no identity."
+    },
     "onChange": {
       "$prototype": "Function",
       "body": [
@@ -178,6 +224,9 @@
     "& [part=\"label\"]:empty": {
       "display": "none"
     },
+    "& > [part=\"tooltip\"]": {
+      "display": "contents"
+    },
     "@(forced-colors: active)": {
       "& [part=\"input\"]": {
         "forcedColorAdjust": "none",
@@ -208,7 +257,8 @@
       "tagName": "label",
       "attributes": {
         "part": "control",
-        "title": "${state.hint || null}"
+        "id": "${state.uid || null}",
+        "title": "${state.disabled && state.hint ? state.hint : null}"
       },
       "children": [
         {
@@ -219,7 +269,7 @@
             "role": "switch",
             "aria-label": "${state.label || null}",
             "aria-labelledby": "${state.labelledby || null}",
-            "aria-describedby": "${state.describedby || null}",
+            "aria-describedby": "${[state.hasTip ? state.uid + '-tip' : null, state.describedby || null].filter(Boolean).join(' ') || null}",
             "tabindex": "${state.tabindex || null}",
             "name": "${state.name || null}",
             "disabled": {
@@ -248,6 +298,34 @@
           ]
         }
       ]
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "tooltip"
+      },
+      "$switch": {
+        "$ref": "#/state/hasTip"
+      },
+      "cases": {
+        "true": {
+          "tagName": "jx-tooltip",
+          "attributes": {
+            "part": "tip",
+            "id": "${state.uid}-tip",
+            "for": "${state.uid}"
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "attributes": {
+                "part": "tip-text"
+              },
+              "textContent": "${state.hint}"
+            }
+          ]
+        }
+      }
     }
   ]
 }

package/components/jx-textfield.json

@@ -447,9 +447,15 @@
       "fontSize": "var(--jx-text-lg)"
     },
     "& [part=\"clear\"]": {
+      "$description": "The clear button sits inside the field's border, so it draws 2px under the field's height: 22px in a 24px field, and 18px in an `sm` one. The `::before` is its hit area (WCAG 2.2 SC 2.5.8, ui.md \u00a74.3): an empty pseudo-element inset by half the difference between the drawn box and the kit's control height, which is -1px on a default field and -3px on a small one, so the region that accepts the pointer is `--jx-control-h` square at every size while the glyph and its hover box stay where they were. On a large field the difference is positive and the pseudo-element is an invisible box INSIDE a button that is already over the floor, which changes nothing. jx-tab's close button is the technique; the button is absolutely positioned already, so it is its own containing block. The extension lies over the input it clears, which was true of the drawn button too, and 2px past the field's edge at `sm`, where a neighbour at the kit's 4px gap extends 2px back and the two abut.",
       "position": "absolute",
       "insetBlockStart": "1px",
       "insetInlineEnd": "1px",
+      "::before": {
+        "content": "\"\"",
+        "position": "absolute",
+        "inset": "calc((var(--jx-textfield-h) - 2px - var(--jx-control-h)) / 2)"
+      },
       "display": "inline-flex",
       "alignItems": "center",
       "justifyContent": "center",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/ui",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The Jx UI kit: interface elements authored as Jx documents, with their theme and icons",
   "license": "MIT",
   "repository": {
@@ -58,7 +58,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/runtime": "^4.0.0",
+    "@jxsuite/runtime": "^4.0.1",
     "@jxsuite/schema": "^2.2.0"
   },
   "devDependencies": {

package/src/behaviors/listbox.ts

@@ -106,8 +106,30 @@ export function syncListbox(host: HTMLElement, active: string): OptionElement |
  */
 export function mountListbox(state: ListboxState, host: HTMLElement): void {
   syncListbox(host, String(state.active ?? ""));
+  /* One sync per frame, not one per mutation record. The palette opens by constructing its row
+     set: dozens of `childList` records in one task, and a sync per record is a querySelectorAll
+     walk plus a flush-baiting read each — the DevTools timeline billed every one of them. The
+     LAST record of a task settles the same active id the task started with (a filter's rows land
+     whole, and a caret move never changes rows), so reading `active` at frame time is the same
+     answer once, with one style pass for the burst instead of one per record. */
+  let frameId: number | null = null;
+  const scheduleSync = (): void => {
+    if (frameId !== null) {
+      return;
+    }
+    frameId = requestAnimationFrame(() => {
+      frameId = null;
+      if (host.isConnected) {
+        syncListbox(host, String(state.active ?? ""));
+      }
+    });
+  };
   const observer = new MutationObserver(() => {
-    syncListbox(host, String(state.active ?? ""));
+    if (typeof requestAnimationFrame === "function") {
+      scheduleSync();
+    } else {
+      syncListbox(host, String(state.active ?? ""));
+    }
   });
   observer.observe(host, {
     attributeFilter: ["data-active"],

package/src/behaviors/split.ts

@@ -202,11 +202,37 @@ function coordOf(vertical: boolean, event: { clientX: number; clientY: number })
  * realm cannot see through — walking past it costs a frame's work once per gesture and is the only
  * thing that makes the pane grid's two nested `display: contents` rows measurable at all.
  *
+ * The ancestor that resolved as the track is MEMOIZED per host and re-read per call. Only its
+ * identity is cached; the length is measured fresh every time, so a window resize answers the new
+ * track width with no listener anywhere. Re-measuring one element's box instead of walking with a
+ * computed-style test per ancestor is what profiling pointed at: every gesture during a shell rep
+ * forced the dirty-tree flush and the DevTools timeline charged the recalc to the read, five times
+ * per boot with a document open. The cache re-walks when the remembered track no longer contains
+ * the host (reparenting, teardown) — containment and connectivity are node walks, not layout — and
+ * when the remembered track measures zero, because an unlaid-out track resolving later (the first
+ * frame after a pane opens) is the case the walk exists for.
+ *
  * @param host The element.
  * @param vertical Whether the drag is along x.
  * @returns The length in pixels, or 0 when nothing above the splitter has one.
  */
-function trackOf(host: HTMLElement, vertical: boolean): number {
+const trackCache = new WeakMap<HTMLElement, { element: HTMLElement; vertical: boolean }>();
+
+export function trackOf(host: HTMLElement, vertical: boolean): number {
+  const cached = trackCache.get(host);
+  if (
+    cached &&
+    cached.vertical === vertical &&
+    cached.element.isConnected &&
+    host.isConnected &&
+    cached.element.contains(host)
+  ) {
+    const box = cached.element.getBoundingClientRect();
+    const length = vertical ? box.width : box.height;
+    if (length > 0) {
+      return length;
+    }
+  }
   for (let node = host.parentElement; node; node = node.parentElement) {
     if (globalThis.getComputedStyle(node).display === "contents") {
       continue;
@@ -214,6 +240,7 @@ function trackOf(host: HTMLElement, vertical: boolean): number {
     const box = node.getBoundingClientRect();
     const length = vertical ? box.width : box.height;
     if (length > 0) {
+      trackCache.set(host, { element: node, vertical });
       return length;
     }
   }

package/src/behaviors/tooltip.ts

@@ -689,17 +689,21 @@ let mintedHints = 0;
  * Mint the id stem a control that draws its `hint` as a `jx-tooltip` needs, and write it into
  * `uid`.
  *
- * `jx-action-button` and `jx-button` render their tip as a child of their own element, and the pair
- * is wired by id in both directions: `interestfor` on the control naming the tip, which is what
- * shows it with nothing bound on an engine that has interest invokers (Chrome 152 — and NOT the
- * desktop app's Chromium 147, which is on the fallback path until the CEF bump reaches it); `for`
- * on the tip naming the control, which is what {@link onTooltipReady} resolves by id rather than by
- * an attribute scan of the document; and `aria-describedby` on the control naming the tip again,
- * which is what makes the hint a DESCRIPTION beside the name rather than the name itself. So a
- * consumer writes none of the three, and two hinted buttons in one toolbar cannot collide. A
- * document cannot mint the stem: the closed operator set has no counter and no identity, which is
- * the sidecar case specs/ui.md §3.2 sanctions. The stem carries the host's own tag, so an id read
- * off the inspector says what it belongs to.
+ * `jx-action-button`, `jx-button` and `jx-switch` render their tip as a child of their own element,
+ * and the pair is wired by id in both directions: `interestfor` on the control naming the tip,
+ * which is what shows it with nothing bound on an engine that has interest invokers (Chrome 152 —
+ * and NOT the desktop app's Chromium 147, which is on the fallback path until the CEF bump reaches
+ * it); `for` on the tip naming the control, which is what {@link onTooltipReady} resolves by id
+ * rather than by an attribute scan of the document; and `aria-describedby` on the control naming
+ * the tip again, which is what makes the hint a DESCRIPTION beside the name rather than the name
+ * itself. So a consumer writes none of the three, and two hinted controls in one toolbar cannot
+ * collide. The switch writes only the last two: its trigger is the `<label>` wrapping the input,
+ * and interest invokers are supported on `a`, `area` and `button` alone, so an `interestfor` there
+ * would show nothing on Chrome 152 while telling {@link bindTooltip} the platform had the pair — it
+ * is wired by `for` and bound on every engine instead. A document cannot mint the stem: the closed
+ * operator set has no counter and no identity, which is the sidecar case specs/ui.md §3.2
+ * sanctions. The stem carries the host's own tag, so an id read off the inspector says what it
+ * belongs to.
  *
  * The write lands after the first render, because `onMount` runs a microtask after it — so the tip
  * and the three attributes appear on the second pass, and every binding that reads the stem guards
@@ -707,7 +711,7 @@ let mintedHints = 0;
  * `title` until it is enabled.
  *
  * @param state The control's reactive scope, whose `uid` this writes.
- * @param host The `jx-action-button` or `jx-button` element.
+ * @param host The `jx-action-button`, `jx-button` or `jx-switch` element.
  */
 export function mintHintId(state: Record<string, unknown>, host: HTMLElement): void {
   mintedHints += 1;