@apliteni/apliteni-ui 0.89.0 → 0.91.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.89.0",
+  "version": "0.91.0",
   "workspaces": [
     "react"
   ],

package/react/dist/index.js

@@ -433,6 +433,7 @@ import {
   useRef as useRef3,
   useState as useState2
 } from "react";
+import { transitionMs } from "@apliteni/apliteni-ui";
 var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), details > summary:first-of-type';
 function tabbable(el) {
   const tabindex = el.getAttribute("tabindex");
@@ -453,17 +454,6 @@ var dismissOnScrim = (onClose) => (e) => {
   onClose();
 };
 var useIsoLayoutEffect = typeof document === "undefined" ? useEffect2 : useLayoutEffect3;
-function transitionMs(el) {
-  const cs = getComputedStyle(el);
-  const times = (list) => list.split(",").map((t) => {
-    const n = Number.parseFloat(t);
-    if (!Number.isFinite(n)) return 0;
-    return t.trim().endsWith("ms") ? n : n * 1e3;
-  });
-  const durations = times(cs.transitionDuration);
-  const delays = times(cs.transitionDelay);
-  return Math.max(0, ...durations.map((d, i) => d + delays[i % delays.length]));
-}
 var DialogScope = createContext(null);
 var stack = [];
 var leaving = /* @__PURE__ */ new Set();
@@ -1928,8 +1918,19 @@ import {
   useRef as useRef11,
   useState as useState7
 } from "react";
-import { icon as icon3, dropdownMatch, dropdownFiltering } from "@apliteni/apliteni-ui";
+import {
+  icon as icon3,
+  dropdownMatch,
+  dropdownFiltering,
+  filterPanelFit,
+  transitionMs as transitionMs2
+} from "@apliteni/apliteni-ui";
 import { Fragment as Fragment5, jsx as jsx20, jsxs as jsxs16 } from "react/jsx-runtime";
+var EXIT_SLACK_MS2 = 50;
+var inPanel = (node) => {
+  const el = node?.nodeType === 1 ? node : node?.parentElement ?? null;
+  return !!el?.closest("[data-dropdown-panel]");
+};
 var cx6 = (...a) => a.filter(Boolean).join(" ");
 var isRow = (it) => Boolean(it) && it !== "---" && !it.separator;
 var Glyph2 = ({ name, className, hidden }) => /* @__PURE__ */ jsx20(
@@ -2002,6 +2003,84 @@ function Dropdown({
   useIsoLayoutEffect(() => {
     close.current = setOpen;
   });
+  useIsoLayoutEffect(() => {
+    const el = panel.current;
+    if (!el || !open) return;
+    const fit = () => {
+      const got = filterPanelFit(root.current);
+      if (!got) return;
+      let moved = false;
+      for (const prop of ["room", "shift", "floor"]) {
+        const name2 = `--ui-filter-panel-${prop}`;
+        const next = `${got[prop]}px`;
+        if (el.style.getPropertyValue(name2) === next) continue;
+        el.style.setProperty(name2, next);
+        moved = true;
+      }
+      if (!moved) return;
+      if (!el.style.minWidth) return;
+      el.style.minWidth = "";
+      if (el.offsetWidth) el.style.minWidth = `${el.offsetWidth}px`;
+    };
+    fit();
+    const view = root.current?.ownerDocument?.defaultView;
+    const row2 = root.current?.closest(".ui-filter-bar__chip")?.closest(".ui-filter-bar");
+    if (!row2 || !view) return;
+    const stop = [];
+    let ro = null;
+    if (typeof view.ResizeObserver === "function") {
+      ro = new view.ResizeObserver(() => fit());
+      ro.observe(row2);
+      for (const kid of Array.from(row2.children)) ro.observe(kid);
+      stop.push(() => ro?.disconnect());
+    } else {
+      view.addEventListener("resize", fit);
+      stop.push(() => view.removeEventListener("resize", fit));
+    }
+    if (typeof view.MutationObserver === "function") {
+      const mo = new view.MutationObserver((records) => {
+        if (records.every((m) => inPanel(m.target))) return;
+        if (ro && records.some((m) => m.type === "childList")) {
+          for (const kid of Array.from(row2.children)) ro.observe(kid);
+        }
+        fit();
+      });
+      mo.observe(row2, { subtree: true, childList: true, attributes: true, characterData: true });
+      stop.push(() => mo.disconnect());
+    }
+    return () => {
+      stop.forEach((off) => off());
+    };
+  }, [open]);
+  const opened = useRef11(false);
+  useIsoLayoutEffect(() => {
+    const el = panel.current;
+    if (open) {
+      opened.current = true;
+      return;
+    }
+    if (!opened.current || !el || !root.current?.closest(".ui-filter-bar__chip")) return;
+    el.classList.add("is-closing");
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      el.classList.remove("is-closing");
+      el.style.minWidth = "";
+      for (const prop of ["room", "shift", "floor"]) el.style.removeProperty(`--ui-filter-panel-${prop}`);
+    };
+    const onEnd = (e) => {
+      if (e.target === el && e.propertyName === "opacity") finish();
+    };
+    el.addEventListener("transitionend", onEnd);
+    const timer = setTimeout(finish, transitionMs2(el) + EXIT_SLACK_MS2);
+    return () => {
+      done = true;
+      el.removeEventListener("transitionend", onEnd);
+      clearTimeout(timer);
+      el.classList.remove("is-closing");
+    };
+  }, [open]);
   const sx = search ? { ...SEARCH_DEFAULTS, ...strip(search === true ? {} : search) } : null;
   const entries = sections?.length ? sections.flatMap((s) => s.items || []) : items || [];
   const rows = entries.filter(isRow);
@@ -2056,7 +2135,12 @@ function Dropdown({
   useIsoLayoutEffect(() => {
     const want = landOn.current;
     landOn.current = null;
-    if (!open) return;
+    if (!open) {
+      if (panel.current?.style && root.current?.closest(".ui-filter-bar") && !root.current.closest(".ui-filter-bar__chip")) {
+        panel.current.style.minWidth = "";
+      }
+      return;
+    }
     if (sx) {
       setQuery("");
       const enabled = rows.filter((it) => !it.disabled);
@@ -2412,7 +2496,7 @@ function Segmented({ options, value, onChange, label, appearance = "pill", disab
 
 // src/FilterBar.tsx
 import { useRef as useRef12, useState as useState8 } from "react";
-import { filterChipText, filterChipName, filterChipUnset, focusNextStop } from "@apliteni/apliteni-ui";
+import { filterChipText, filterChipName, filterChipUnset, filterChipItems, focusNextStop } from "@apliteni/apliteni-ui";
 import { jsx as jsx24, jsxs as jsxs19 } from "react/jsx-runtime";
 function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters", disabled = false, busy = false, onRemove, onClear, onChange }) {
   const bar = useRef12(null);
@@ -2459,7 +2543,7 @@ function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters
               /* @__PURE__ */ jsx24(
                 Dropdown,
                 {
-                  items: filter.items,
+                  items: filterChipItems(filter),
                   variant: "select",
                   ariaLabel: filterChipName(filter),
                   triggerContent: /* @__PURE__ */ jsx24("span", { className: filterChipUnset(filter) ? "ui-dropdown__value is-placeholder" : "ui-dropdown__value", children: filterChipText(filter) }),

package/src/components/dropdown.js

@@ -16,6 +16,8 @@ export { dropdownMatch, dropdownFiltering } from '../logic/dropdown.js';
 //   wireDropdown(container);   // or let wireTopbar() do it
 import { esc, icon } from './index.js';
 import { safeUrl } from '../html.js';
+// The fade's own length, read off the stylesheet rather than copied. why: src/motion.js
+import { transitionMs } from '../motion.js';
 const cx = (...a) => a.filter(Boolean).join(' ');
 
 // A trailing status badge. `badge` is the text shown, in the case it is written
@@ -325,6 +327,215 @@ function ddResetSearch(dd, panel, search) {
   if (panel.offsetWidth) panel.style.minWidth = `${panel.offsetWidth}px`;
 }
 
+/* The kit's menu floor, the one `.ui-dropdown__panel` writes. The stylesheets
+ * carry the same number; stories/filter-bar-fit.test.js reads all of them and
+ * fails when one drifts. why: src/styles/dropdown.css */
+export const DD_MENU_FLOOR = 240;
+
+/**
+ * Where a filter chip's menu may sit. #484 bounds the panel to its trigger, so a
+ * chip printing its value alone (#536) left a 48px menu breaking words
+ * mid-letter — #549. An OPEN panel takes the floor instead and slides along the
+ * row when the room on the side it opens from is short; shut, it keeps the
+ * trigger's width, which is why #467 needs no measuring at all.
+ *
+ * A panel is anchored at one edge of its dropdown — its inline end when it
+ * carries `is-end` — so room is measured from that edge and the slide goes the
+ * other way. Measuring an end-anchored panel forwards put one off the page.
+ * why: docs/specification.md#a-filter-row-holds-its-panels
+ *
+ * @param {Element} dd a `.ui-dropdown` that may be inside a filter row
+ * @param {number} [floor] the width to reach for
+ * @returns {{room: number, shift: number, floor: number, end: boolean}|null}
+ */
+export function filterPanelFit(dd, floor = DD_MENU_FLOOR) {
+  /* A chip's menu, not any menu in a filter row: the slide below is measured from
+   * the trigger's offset along the row, so a panel anchored to the row itself is
+   * not this function's subject and must size itself. why: src/styles/filter-bar.css */
+  const chip = typeof dd?.closest === 'function' ? dd.closest('.ui-filter-bar__chip') : null;
+  const bar = chip ? chip.closest('.ui-filter-bar') : null;
+  if (!bar || typeof bar.getBoundingClientRect !== 'function') return null;
+  const row = bar.getBoundingClientRect();
+  const box = dd.getBoundingClientRect();
+  const panel = typeof dd.querySelector === 'function' ? dd.querySelector('.ui-dropdown__panel') : null;
+  const end = !!panel?.classList?.contains('is-end');
+  // A row narrower than the floor decides the width; nothing may leave the row.
+  const want = Math.min(floor, row.width);
+  const ahead = end
+    ? Math.max(0, box.right - row.left)    // an end-anchored panel grows backwards
+    : Math.max(0, row.right - box.left);
+  const slack = end
+    ? Math.max(0, row.right - box.right)   // …and slides towards the row's end
+    : Math.max(0, box.left - row.left);
+  const shift = Math.min(slack, Math.max(0, want - ahead));
+  return { room: ahead + shift, shift, floor: want, end };
+}
+
+/** Write the fit onto the panel, and say whether any of the three numbers moved.
+ *  All three, because the stylesheet reads all three; it falls back to the
+ *  trigger's width when they are unset, so a panel opened before this runs is
+ *  bounded rather than unbounded.
+ *
+ *  A number that has not changed is not written again, which is what stops the
+ *  observers below from answering their own writes: a fit landing on the same
+ *  three numbers mutates nothing, so it reports nothing. */
+function ddWriteFit(panel, fit) {
+  let moved = false;
+  for (const prop of ['room', 'shift', 'floor']) {
+    const name = `--ui-filter-panel-${prop}`;
+    const next = `${fit[prop]}px`;
+    if (panel.style.getPropertyValue(name) === next) continue;
+    panel.style.setProperty(name, next);
+    moved = true;
+  }
+  return moved;
+}
+
+/** Fit a panel just opened, or leave it alone outside a filter row. */
+function ddFitFilterPanel(dd, panel) {
+  const fit = filterPanelFit(dd);
+  if (!fit || !panel?.style) return false;
+  return ddWriteFit(panel, fit);
+}
+
+/** Measure an open menu again where its row now puts it. The fit it was opened
+ *  with can describe a row that no longer exists — a menu opened at 1280 and left
+ *  open at 390 kept a 1102px room and stood 11px off the page — or a place in that
+ *  row the chip has since left. A search panel's inline `min-width` was read at
+ *  the old width too, and inline beats the sheet, so it is read again off the
+ *  newly bounded box; only when the fit moved, because re-reading it is itself a
+ *  write.
+ *  why: docs/specification.md#a-filter-row-holds-its-panels */
+function ddRefitFilterPanel(dd, panel) {
+  const fit = panel?.style ? filterPanelFit(dd) : null;
+  if (!fit || !ddWriteFit(panel, fit)) return;
+  if (!panel.style.minWidth) return;
+  panel.style.minWidth = '';
+  if (panel.offsetWidth) panel.style.minWidth = `${panel.offsetWidth}px`;
+}
+
+/** The row this chip's menu is fitted to, or null outside one. */
+function ddRowOf(dd) {
+  return dd?.closest?.('.ui-filter-bar__chip')?.closest('.ui-filter-bar') || null;
+}
+
+/** Is this node inside some dropdown panel? The fit writes to a panel and to
+ *  nothing else, so a change inside one is never news — and a panel is
+ *  `position: absolute`, so nothing in it can move a chip along its row. Any
+ *  panel, not only the one being fitted: two open menus in one row would
+ *  otherwise answer each other a mutation at a time.
+ *  why: docs/specification.md#a-filter-row-holds-its-panels */
+function ddOurs(node) {
+  const el = node?.nodeType === 1 ? node : node?.parentElement;
+  return !!el?.closest?.('[data-dropdown-panel]');
+}
+
+/**
+ * Watch what the fit is measured from, and fit the menu again when it changes.
+ *
+ * Two inputs, two watchers. The row's width is one, observed rather than taken
+ * from `resize`, which fires before an animating row has settled. Where the chip
+ * sits along the row is the other, and it moves while the row keeps both of its
+ * dimensions: re-labelling the chip in front of an open menu at 390px slid this
+ * one 27.97px and took the menu 27.97px out of its row. So the boxes laid out in
+ * the row are observed too — a chip is moved by the size of the ones in front of
+ * it — and the mutation that moved it is watched for the frame before any of it
+ * is laid out.
+ *
+ * Why those two cover the arithmetic, and the one case they do not:
+ * why: docs/specification.md#a-filter-row-holds-its-panels
+ */
+function ddWatchRow(dd, panel) {
+  ddUnwatchRow(dd);
+  const row = ddRowOf(dd);
+  const view = dd.ownerDocument?.defaultView;
+  if (!row) return;
+  const refit = () => { if (dd.classList.contains('open')) ddRefitFilterPanel(dd, panel); };
+  if (typeof view?.ResizeObserver === 'function') {
+    // observe() reports each current box at once, which the fit was just written
+    // from, so the first round writes nothing.
+    const ro = new view.ResizeObserver(refit);
+    ro.observe(row);
+    for (const kid of row.children) ro.observe(kid);
+    dd.__ddRowFit = ro;
+  }
+  if (typeof view?.MutationObserver !== 'function') return;
+  const mo = new view.MutationObserver((records) => {
+    if (records.every((m) => ddOurs(m.target))) return;
+    // A chip added or removed brings a box the observer above is not watching yet.
+    if (dd.__ddRowFit && records.some((m) => m.type === 'childList')) {
+      for (const kid of row.children) dd.__ddRowFit.observe(kid);
+    }
+    refit();
+  });
+  /* characterData as well as the two structural kinds: a chip's printed value
+     replaced is a text node changed, with no child list and no attribute moving
+     with it — which is what a React re-render of that value arrives as too.
+     Attributes, because a class is how a chip changes shape; subtree, because the
+     text that sets a chip's width is inside it. */
+  mo.observe(row, { subtree: true, childList: true, attributes: true, characterData: true });
+  dd.__ddRowMo = mo;
+}
+
+function ddUnwatchRow(dd) {
+  dd.__ddRowFit?.disconnect();
+  dd.__ddRowFit = null;
+  dd.__ddRowMo?.disconnect();
+  dd.__ddRowMo = null;
+}
+
+/* A few frames past the sheet's own end, so the timer never cuts the fade's last
+ * frame. The number the dialogs' exit uses. */
+const DD_EXIT_SLACK_MS = 50;
+
+/**
+ * Hold a closing chip menu's open geometry until its fade has finished.
+ *
+ * `.open` stops matching in the frame the menu closes; the fade does not — the
+ * panel transitions opacity over --dur-med. Dropping the width there left a 240px
+ * menu painted as a 48px column of single letters: #549 on the way out. The timer
+ * is the way out of a transitionend that never comes.
+ * why: src/styles/filter-bar.css
+ */
+function ddHoldClose(dd, panel) {
+  ddCancelClose(dd, panel);
+  panel.classList.add('is-closing');
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    dd.__ddClosing = null;
+    panel.classList.remove('is-closing');
+    panel.style.minWidth = '';
+    for (const prop of ['room', 'shift', 'floor']) {
+      panel.style.removeProperty(`--ui-filter-panel-${prop}`);
+    }
+  };
+  // Only the panel's own fade: a row's background transition bubbles here too.
+  const onEnd = (e) => { if (e.target === panel && e.propertyName === 'opacity') stop(); };
+  const timer = setTimeout(() => stop(), transitionMs(panel) + DD_EXIT_SLACK_MS);
+  function stop() {
+    panel.removeEventListener('transitionend', onEnd);
+    clearTimeout(timer);
+    finish();
+  }
+  panel.addEventListener('transitionend', onEnd);
+  // Re-opened mid-fade: the wait is abandoned, so it cannot clear a fit the new
+  // open has already written.
+  dd.__ddClosing = () => {
+    done = true;
+    dd.__ddClosing = null;
+    panel.removeEventListener('transitionend', onEnd);
+    clearTimeout(timer);
+    panel.classList.remove('is-closing');
+  };
+}
+
+function ddCancelClose(dd, panel) {
+  if (dd.__ddClosing) dd.__ddClosing();
+  else panel?.classList?.remove('is-closing');
+}
+
 // `auto` is the only direction the wiring decides; `up` and the default are the
 // panel's own class, set once at render. Flip only when below is too tight AND
 // above is roomier, so a panel that fits nowhere still opens the way it says.
@@ -373,7 +584,17 @@ function sweepOrphanPanels(host) {
 function closeDropdown(dd) {
   if (!dd.classList.contains('open')) return;
   dd.classList.remove('open');
-  ddPanelOf(dd)?.classList.remove('is-open');
+  const panel = ddPanelOf(dd);
+  panel?.classList.remove('is-open');
+  ddUnwatchRow(dd);
+  /* A search panel carries the width it was opened at as an inline `min-width`,
+   * and inline beats any sheet. Inside a filter row that leaves a SHUT panel wider
+   * than its trigger, which is #467. Cleared here, and ddResetSearch() writes it
+   * again on the next open — except for a chip's menu, which gives the pin and the
+   * fit back at the END of its fade, both being its open geometry. A portalled
+   * panel is never fitted, so it has none to hold. why: ddHoldClose() */
+  if (panel?.style && !dd.__ddPanel && ddRowOf(dd)) ddHoldClose(dd, panel);
+  else if (panel?.style && dd.closest?.('.ui-filter-bar')) panel.style.minWidth = '';
   dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'false');
 }
 
@@ -396,12 +617,21 @@ function openDropdown(dd, focusIdx) {
   closeAllDropdowns(dd);
   const panel = ddPanelOf(dd);
   const search = ddSearchOf(dd);
-  if (panel && search) ddResetSearch(dd, panel, search);
   if (panel) {
+    // An earlier close may still be holding its geometry; this open owns it now.
+    ddCancelClose(dd, panel);
     ddResolveDirection(dd, panel);
     if (dd.__ddPanel) { positionPortalPanel(dd, panel); panel.classList.add('is-open'); }
+    else { ddFitFilterPanel(dd, panel); ddWatchRow(dd, panel); }
   }
   dd.classList.add('open');
+  /* After `open`, and after the fit: ddResetSearch() pins the width it reads off
+   * the panel, and the rule that widens a filter menu only applies once the
+   * panel is open. Reading first pinned 50px inline, which beats any stylesheet
+   * — a searchable chip in a filter row kept the 74px menu #549 reported, while
+   * React, whose effects already ran in this order, gave 240px for the same
+   * markup. why: src/styles/filter-bar.css */
+  if (panel && search) ddResetSearch(dd, panel, search);
   dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'true');
   // With search, focus goes to the field however the panel was opened, and
   // the selected row (or the first) is the one Enter would pick.
@@ -451,10 +681,21 @@ function ddListen(doc) {
       if (dd.classList.contains('open') && dd.__ddPanel) positionPortalPanel(dd, dd.__ddPanel);
     }
   };
+  /* The fallback re-fit, for a view with no ResizeObserver. Not taken as well where
+   * ddWatchRow() is watching: a `resize` event is the worse measurement of the two.
+   * why: docs/specification.md#a-filter-row-holds-its-panels */
+  const refit = () => {
+    for (const dd of ddLive()) {
+      if (dd.classList.contains('open') && !dd.__ddPanel && !dd.__ddRowFit) {
+        ddRefitFilterPanel(dd, ddPanelOf(dd));
+      }
+    }
+  };
   const view = doc.defaultView;
   if (!view) return;
   view.addEventListener('scroll', reposition, true);
   view.addEventListener('resize', reposition);
+  view.addEventListener('resize', refit);
 }
 
 export function wireDropdown(root = document) {
@@ -489,6 +730,15 @@ export function wireDropdown(root = document) {
       }
     }
 
+    // A panel rendered already-open never passes through openDropdown(), so its
+    // fit has to be taken here too — otherwise a story or a server-rendered bar
+    // keeps the fallback width and #549 survives in exactly the place a
+    // default-open menu makes most visible.
+    if (panel && !dd.__ddPanel && dd.classList.contains('open')) {
+      ddFitFilterPanel(dd, panel);
+      ddWatchRow(dd, panel);
+    }
+
     trigger.addEventListener('click', (e) => {
       e.stopPropagation();
       if (dd.classList.contains('open')) closeDropdown(dd);

package/src/components/filter-bar.js

@@ -1,13 +1,13 @@
 import { button, esc } from './index.js';
 import { dropdown, wireDropdown } from './dropdown.js';
-import { filterChipText, filterChipName, filterChipUnset, focusNextStop } from '../logic/filter-bar.js';
+import { filterChipText, filterChipName, filterChipUnset, filterChipItems, focusNextStop } from '../logic/filter-bar.js';
 
 export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear all filters', disabled = false, busy = false } = {}) {
   return `<fieldset class="ui-filter-bar" data-filter-bar${disabled || busy ? ' disabled' : ''}${busy ? ' aria-busy="true"' : ''}>`
     + `<legend class="ui-filter-bar__legend">${esc(label)}</legend>`
     + filters.map(filter => `<fieldset class="ui-filter-bar__chip" data-filter-id="${esc(filter.id)}"${filter.disabled ? ' disabled' : ''}>`
       + `<legend class="ui-filter-bar__legend">${esc(filter.label)}</legend>`
-      + dropdown({ items: filter.items || [], variant: 'select',
+      + dropdown({ items: filterChipItems(filter), variant: 'select',
         // The chip prints one line; the field's name reaches a reader through the
         // trigger's name and the chip's own legend. why: docs/specification.md#dense-financial-tables
         triggerContent: `<span class="${filterChipUnset(filter) ? 'ui-dropdown__value is-placeholder' : 'ui-dropdown__value'}">${esc(filterChipText(filter))}</span>`,

package/src/index.d.ts

@@ -12,6 +12,12 @@ export declare function filterChipName(filter?: { label?: string; value?: string
 export declare function filterChipUnset(filter?: { value?: string }): boolean;
 export declare function nextFocusStop(host: Element | null | undefined): HTMLElement | null;
 export declare function focusNextStop(host: Element | null | undefined): HTMLElement | null;
+/** The chip's items with the chip's own `value` marked `selected`, so the line the chip
+ *  prints and the row its menu marks cannot disagree. A row is matched by `value`, or by
+ *  `label` where it has none. Every row's flag is written, so a chip that is unset or
+ *  whose value is in no row marks nothing rather than leaving a `selected` the caller
+ *  set standing. The caller's array and objects are not written to. */
+export declare function filterChipItems<T>(filter?: { value?: string; items?: T[] }): T[];
 export declare function segmentedNextIndex(key: string, index: number, length: number): number | null;
 export declare function icon(name: string, className?: string): string;
 export declare function snippet(opts?: Record<string, unknown>): string;
@@ -28,6 +34,18 @@ export declare function wireDropdown(root?: Document | Element): void;
 /** The kit's own match, asked rather than re-implemented by <Dropdown>. */
 export declare function dropdownMatch(label: unknown, query: unknown): boolean;
 export declare function dropdownFiltering(query: unknown): boolean;
+/** The kit's menu floor, the width `.ui-dropdown__panel` writes. */
+export declare const DD_MENU_FLOOR: number;
+/** Where a filter chip's open menu can sit: the room from the edge it is
+ *  anchored at to the far side of its row once slid, how far it had to slide,
+ *  the width it reached for, and whether it is anchored at its inline end.
+ *  `null` unless the dropdown is inside a `.ui-filter-bar__chip`: the slide is a
+ *  chip's offset along its row, so a panel anchored to the row itself is not this
+ *  function's subject and sizes itself. why: docs/library.md */
+export declare function filterPanelFit(
+  dd: Element | null | undefined,
+  floor?: number,
+): { room: number; shift: number; floor: number; end: boolean } | null;
 export declare function backLink(opts?: Record<string, unknown>): string;
 export declare function statBand(opts?: Record<string, unknown>): string;
 export declare function commandPalette(opts?: Record<string, unknown>): string;

package/src/index.js

@@ -30,7 +30,7 @@ export * from './components/filter-bar.js';
 export { dropdownMatch, dropdownFiltering } from './logic/dropdown.js';
 export { SCORE, rankGroups, rankCommands, scoreCommand, paletteHotkey } from './logic/command-palette.js';
 export { segmentedNextIndex } from './logic/segmented.js';
-export { filterChipText, filterChipName, filterChipUnset, nextFocusStop, focusNextStop } from './logic/filter-bar.js';
+export { filterChipText, filterChipName, filterChipUnset, filterChipItems, nextFocusStop, focusNextStop } from './logic/filter-bar.js';
 export { PAGE_SIZES, DEFAULT_PAGE_SIZE } from './logic/pagination.js';
 export { calloutIcons } from './logic/callout.js';
 export { formatNumericValue, formatDeltaValue } from './logic/table-values.js';

package/src/logic/filter-bar.js

@@ -103,3 +103,23 @@ export function focusNextStop(host) {
   }
   return null;
 }
+
+/** The chip's menu with the chip's own value marked, so the line the chip prints
+ *  and the row the menu marks cannot disagree. A row is identified the way the
+ *  dropdown identifies it when it reports a pick: by `value`, or by `label` where
+ *  it carries none.
+ *
+ *  Every row's flag is written, not only the chosen one's, so a chip with nothing
+ *  chosen or a value in no row marks no row. Handing those items back as the
+ *  consumer wrote them left whatever they had marked standing — a menu checking
+ *  `All`, `aria-selected="true"` on it, under a chip printing `Asia`. The
+ *  consumer's own array and objects are not written to. #550
+ *  why: docs/specification.md#a-filter-row-holds-its-panels */
+export function filterChipItems(filter = {}) {
+  const items = filter.items || [];
+  const chosen = text(filter.value);
+  const row = (it) => !!it && it !== '---' && !it.separator;
+  const key = (it) => text(it.value != null ? it.value : it.label);
+  const inForce = !filterChipUnset(filter) && items.some((it) => row(it) && key(it) === chosen);
+  return items.map((it) => (row(it) ? { ...it, selected: inForce && key(it) === chosen } : it));
+}

package/src/motion.d.ts

@@ -4,3 +4,5 @@ export declare function initReveal(root?: Document | Element): IntersectionObser
 export declare const ENTRANCE_FALLBACK_MS: number;
 export declare function playEntrance(element: Element | null, className?: string): void;
 export declare function replay(element: HTMLElement | null): void;
+/** How long the stylesheet says this element's transition lasts, in ms; 0 off-DOM. */
+export declare function transitionMs(element: Element | null | undefined): number;

package/src/motion.js

@@ -100,6 +100,33 @@ export function playEntrance(el, className = 'is-entering') {
   entering.set(el, () => done());
 }
 
+/**
+ * How long the stylesheet says this element's transition lasts — the longest
+ * duration plus its own delay, in ms, and 0 off-DOM or for no element at all.
+ *
+ * What a backstop timer beside a `transitionend` listener is sized from, so the
+ * duration stays the sheet's rather than a copy of --dur-med. The event does not
+ * come for a transition that did not run, and jsdom never fires it at all.
+ */
+export function transitionMs(el) {
+  // getComputedStyle throws a TypeError for a non-element, and the view below
+  // falls back to the global window, so a missing ref took its caller down.
+  if (el?.nodeType !== 1) return 0;
+  const view = el.ownerDocument?.defaultView
+    || (typeof window === 'undefined' ? null : window);
+  const cs = view?.getComputedStyle?.(el);
+  if (!cs) return 0;
+  // A delay list shorter than the duration list repeats, as the spec says.
+  const times = (list) => String(list || '').split(',').map((t) => {
+    const n = Number.parseFloat(t);
+    if (!Number.isFinite(n)) return 0;
+    return t.trim().endsWith('ms') ? n : n * 1000;
+  });
+  const durations = times(cs.transitionDuration);
+  const delays = times(cs.transitionDelay);
+  return Math.max(0, ...durations.map((d, i) => d + delays[i % delays.length]));
+}
+
 /** Restart the CSS animation on an element (for a "replay" control). */
 export function replay(el) {
   if (!el || !el.style) return;

package/src/styles/filter-bar.css

@@ -12,16 +12,9 @@
    take. `:enabled` leaves a disabled chip its own ink. why: guidelines/labels-and-titles.md */
 .ui-filter-bar button:enabled .ui-dropdown__value.is-placeholder { /* muted-ink: placeholder — a filter chip with nothing chosen */ color: var(--muted); }
 
-/* A chip's panel is as wide as the chip's trigger, never the 240px floor
-   .ui-dropdown__panel gives a standalone dropdown. A panel is positioned at its
-   trigger's inline start, so on a narrow row a later chip put its panel past the
-   screen — shut as well as open, a `visibility: hidden` box still being laid out.
-   The percentage resolves against .ui-dropdown, the panel's containing block,
-   which is the trigger's width because the trigger is its one in-flow child.
-   `overflow-wrap` keeps that a bound rather than a clip: a panel is
-   `overflow: visible`, so a value with no break opportunity would run out of it
-   and off the page. It inherits, reaching an option's label and description.
-   why: docs/specification.md#a-filter-row-holds-its-panels */
+/* Shut, a panel is the trigger's width, never the 240px floor a standalone
+   dropdown gets: it is laid out while hidden, so a wider one widened the page
+   (#467). why: docs/specification.md#a-filter-row-holds-its-panels */
 .ui-filter-bar .ui-dropdown__panel { min-width: 100%; max-width: 100%; overflow-wrap: anywhere; }
 /* The clear action takes the kit's bordered skin minus its fill: words belong on
    the page, not on a grey block, in any state — Artur, round r28. Rest stays at
@@ -39,3 +32,55 @@
    measures on every ground. The edge stays the kit's --disabled-border. */
 .ui-filter-bar [data-filter-clear] button:disabled,
 .ui-filter-bar [data-filter-clear] button[aria-disabled="true"] { /* muted-ink: state — the clear action is off and its words sit on the page */ color: var(--disabled-ink-bare); }
+
+/* Open, a chip's menu takes the kit's menu floor, measured and slid by
+   filterPanelFit(); `is-closing` holds that geometry through the fade. #549
+   why: docs/specification.md#a-filter-row-holds-its-panels */
+.ui-filter-bar__chip .ui-dropdown.open .ui-dropdown__panel,
+.ui-filter-bar__chip .ui-dropdown__panel.is-closing {
+  min-width: min(var(--ui-filter-panel-floor, 240px), var(--ui-filter-panel-room, 100%));
+  max-width: var(--ui-filter-panel-room, 100%);
+  margin-inline-start: calc(-1 * var(--ui-filter-panel-shift, 0px));
+}
+/* An end-aligned panel is pinned by its right edge, so the slide pushes it. */
+.ui-filter-bar__chip .ui-dropdown.open .ui-dropdown__panel.is-end,
+.ui-filter-bar__chip .ui-dropdown__panel.is-end.is-closing {
+  margin-inline-start: 0;
+  margin-inline-end: calc(-1 * var(--ui-filter-panel-shift, 0px));
+}
+
+/* A 16px tick and an 11px gap do not fit the 48px trigger a chip printing `All`
+   gives its SHUT panel, and overflow-wrap cannot break a mark; the clip is what
+   shrinks the glyph and not just its box.
+
+   Shut is the whole of it. Written for every panel in a chip, this reached the
+   open menu too and left 9.8px of the check in a 240px menu — a chevron, not a
+   tick. Open the menu is at the floor with room for the mark, and `is-closing`
+   holds the open geometry through the fade, so it is open for this as well. #550
+   why: docs/specification.md#a-filter-row-holds-its-panels */
+.ui-filter-bar__chip .ui-dropdown:not(.open) .ui-dropdown__panel:not(.is-closing) .ui-dropdown__tick {
+  flex-shrink: 1;
+  min-width: 0;
+  overflow: hidden;
+}
+
+/* The chosen value takes --glow-purple, the wash .ui-nav--tabs.is-pill gives the
+   tab you are on, and keeps the kit's 16px check. The wash is a 1.2:1 tint, so the
+   check is what identifies the state under WCAG 1.4.1; Apple, Material, Carbon,
+   Primer and Radix all tick a chosen menu row. #549
+   why: docs/specification.md#a-filter-row-holds-its-panels */
+.ui-filter-bar .ui-dropdown__item.is-selected { background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+/* Kit-wide a chosen label steps down to --text, which left the row in force the
+   faintest in the panel. Under the wash it holds --strong. */
+.ui-filter-bar .ui-dropdown__item.is-selected .ui-dropdown__label { color: var(--strong); }
+/* The keyboard cursor and focus each set an opaque --surface, which would take the
+   wash off; restated here so the guarantee is one declaration a reader and
+   filter-selected-mark.test.js can both find, and each still reads by its own paint.
+   why: guidelines/accessibility-floor.md#measurable-pairs */
+.ui-filter-bar .ui-dropdown__item.is-selected:focus-visible,
+.ui-filter-bar .ui-dropdown__item.is-selected.is-active { background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+/* Hover's other paint is a 1px edge, 1.06:1 on the wash, which left the row in force
+   the one row a pointer got no answer from. Selection is a background highlight, so
+   hover deepens it: 9% more accent, the step .ui-table--zebra gives a hovered row.
+   why: docs/specification.md#a-filter-row-holds-its-panels */
+.ui-filter-bar .ui-dropdown__item.is-selected:hover { background: color-mix(in srgb, var(--glow-purple), var(--accent) 9%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }

package/src/styles/nav.css

@@ -12,11 +12,11 @@
 /* The rail's two widths, and the one place they are written. --ui-nav-col is the
    open column. --ui-nav-strip is twice a row's own glyph centre — the row's
    padding plus half a glyph — so a strip that wide has the glyph standing in the
-   middle of it, exactly where it stood in the open rail. That is what lets the
-   fold animate: the column keeps --ui-nav-col and is clipped to the strip, so
-   the width travels and nothing inside it is laid out again. layout.css adds the
-   shell rail's own inset to both. stories/apps/shell-states.test.js derives the
-   strip from the resolved cascade and refuses a number that has drifted from it.
+   middle of it, exactly where it stood in the open rail. The fold travels that
+   width on the rail and on the boxes inside it, so a folded rail is only as wide
+   as it draws and has nothing to clip. layout.css adds the shell rail's own
+   inset to both. stories/apps/shell-states.test.js derives the strip from the
+   resolved cascade and refuses a number that has drifted from it.
    Declared for the shell as well as the nav, because the shell's rail is this
    nav with an inset around it, and two copies of 41 is the drift itself. */
 .ui-nav--side,
@@ -31,14 +31,20 @@
      been a second scroll box cutting the rows off at the rail's height. */
   transition: width var(--dur-med) var(--ease);
 }
-/* Every block keeps the open column while the nav clips to the strip. Without
-   this each one stretches to whatever the nav is wide and every row inside it is
-   laid out again on each frame of the fold. */
-.ui-nav--side > * { width: var(--ui-nav-col); flex: none; }
+/* A block takes a width of its own rather than the rail's travelling one, and travels
+   it on the RAIL's clock. Declared here, not beside the fold, so the way OUT carries it:
+   a block with no clock snapped open while the rail was still a strip wide. */
+.ui-nav--side > * {
+  width: var(--ui-nav-col); flex: none;
+  transition: width var(--dur-med) var(--ease);
+}
 .ui-nav__section + .ui-nav__section { margin-top: 14px; }
 .ui-nav__list { display: flex; flex-direction: column; gap: 2px; }
 .ui-nav__cap {
   /* rank: label */
+  /* Words, never a control, at BOTH widths — as __label, __badge and __caret below.
+     why: docs/specification.md#a-folded-rail-takes-the-pointer-only-where-it-draws */
+  pointer-events: none;
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
   color: var(--text);
@@ -101,6 +107,7 @@
 .ui-nav__item.is-current .ui-nav__ic svg { opacity: 1; stroke: currentColor; } /* motion: still — the glyph brightens with its row, whose own highlight already transitions */
 .ui-nav__label {
   flex: 1 1 auto; min-width: 0;
+  pointer-events: none; /* words, not a control — see .ui-nav__cap */
   overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
   /* The words go before the closing edge reaches them, which is most of why the
      fold is worth animating — a label cut through by that edge reads as the rail
@@ -129,6 +136,7 @@
 /* Per-item badge / counter */
 .ui-nav__badge {
   flex: none;
+  pointer-events: none; /* a count, not a control — see .ui-nav__cap */
   min-width: 20px;
   height: 19px;
   padding: 0 6px;
@@ -163,6 +171,7 @@
 .ui-nav__group { display: flex; flex-direction: column; }
 .ui-nav__caret {
   flex: none;
+  pointer-events: none; /* a mark on the toggle, not a control — see .ui-nav__cap */
   width: 7px; height: 7px;
   border-right: 1.6px solid var(--muted);
   border-bottom: 1.6px solid var(--muted);
@@ -223,53 +232,52 @@
     border-inline-start-width var(--dur-med) var(--ease);
 }
 
-/* Collapsed (icon-only) rail — the same fold the shell's rail makes, drawn once
-   rather than pressed: the column keeps its width and the nav clips to the
-   strip, so no row is laid out again and no glyph moves. A group's children stay
-   rows here, because wireNav() toggles the list's `hidden` attribute and nothing
-   else, so folding .ui-nav__sub away left the toggle announcing a list it could
-   not open. What goes is the indent and the words, and sidebarNav({ collapsed })
-   hands each row its name as a `title` so a pointer can still read it. The
-   shell's rail draws a chip of its own instead, on keyboard focus as well — see
-   layout.css. */
-.ui-nav--side.is-collapsed {
-  width: var(--ui-nav-strip);
-  /* clip, not hidden: a standalone rail has nothing around it to clip for it,
-     and `hidden` would make this a scroll box in both axes and cut the rows off
-     at whatever height it was given. `clip` across leaves `visible` down alone,
-     which is the one pair that does. */
-  overflow-x: clip;
-  overflow-y: visible;
+/* Collapsed (icon-only) rail — the same fold the shell's rail makes. A group's
+   children stay rows here, because wireNav() toggles the list's `hidden` attribute
+   and nothing else, so folding .ui-nav__sub away left the toggle announcing a list it
+   could not open. What goes is the indent and the words, and sidebarNav({ collapsed })
+   hands each row its name as a `title` so a pointer can still read it. The shell's
+   rail draws a chip of its own instead, on keyboard focus as well — see layout.css. */
+.ui-nav--side.is-collapsed { width: var(--ui-nav-strip); }
+/* Every box in the rail closes with it, whether it paints or not. A block that keeps
+   the open column paints nothing and still takes the pointer off 175px of the page
+   beside a positioned rail (#588); clipping it instead cut the rows' ring (#575).
+   why: docs/specification.md#a-folded-rail-takes-the-pointer-only-where-it-draws */
+.ui-nav--side.is-collapsed > * { width: var(--ui-nav-strip); }
+.ui-nav--side.is-collapsed .ui-nav__item { width: var(--ui-nav-strip); }
+/* The heading is the one box that keeps the open column: its line breaks are the rail's
+   height. Inert at both widths, so the column draws and takes nothing; the 175px it adds
+   to a page's scrollable width is the one thing this rail does not promise. */
+.ui-nav--side.is-collapsed .ui-nav__cap { width: var(--ui-nav-col); }
+/* The row takes the rail's clock too, so its box IS the rail's box in every frame and
+   not only at either end. Waiting out the words on a --dur-fast delay left the open
+   column's hit area inside a half-shut rail. (Restates the base it replaces.) */
+.ui-nav--side.is-collapsed .ui-nav__item {
+  transition: background var(--dur-fast) var(--ease), color var(--dur-fast) var(--ease),
+    width var(--dur-med) var(--ease);
 }
+/* What that delay was protecting, kept without it: the words hold their own width
+   instead of being squeezed out by the closing row. They overflow it and cost nothing —
+   inert at either width, and painting nothing at opacity 0. */
+.ui-nav--side.is-collapsed .ui-nav__label { min-width: max-content; }
 .ui-nav--side.is-collapsed .ui-nav__cap,
 .ui-nav--side.is-collapsed .ui-nav__label,
 .ui-nav--side.is-collapsed .ui-nav__badge,
-.ui-nav--side.is-collapsed .ui-nav__caret { opacity: 0; pointer-events: none; }
+.ui-nav--side.is-collapsed .ui-nav__caret { opacity: 0; }
 .ui-nav--side.is-collapsed .ui-nav__sub {
   margin-inline-start: 0; padding-inline-start: 0; border-inline-start-width: 0;
 }
 .ui-nav--side.is-collapsed .ui-nav__item:not(:has(.ui-nav__ic))::after { opacity: 0.62; }
 
-/* The current row on a folded rail: ONE plate on the glyph column, and nothing
-   else. The open rail's marker is a 3px bar standing in the row's own left
-   padding; on the strip that padding is the rail's edge, so the bar reads as a
-   tick on the rail rather than a mark on a row — and a nested row puts it
-   --space-3 further out again, outside the rail altogether. The hairline cannot
-   close either: a row keeps the open column and the rail clips it, so its right
-   edge is drawn off the strip.
-
-   The plate is the strip. --ui-nav-strip is twice a row's own glyph centre, so a
-   box that wide standing at the row's edge is centred on the glyph, and the mark
-   lands where the reader is already looking. --surface-3 is the kit's quiet
-   non-text fill — a step off the rail in both themes, carrying a glyph and never
-   a word. The references mark current the same way and with no hue at all:
-   Cloudflare's docs rail paints a flat plate, and lessly-ui's rail is "a plate and
-   the weight step, no hue". Here the glyph's own step from 0.66 to full ink is the
-   second half of that pair. See #429.
-
-   `isolation` is what puts the plate behind the glyph: a positioned ::before paints
-   over its row's content, and a negative z-index with no stacking context of its
-   own would drop it behind the rail instead. */
+/* The current row on a folded rail: one plate on the glyph column, and nothing else.
+   The open rail's 3px marker would stand in the rail's edge at this width, and a
+   nested row would put it outside the rail; the hairline would be the same mark said
+   twice. The plate is the strip, so it is centred on the glyph, and --surface-3 is the
+   kit's quiet non-text fill — a step off the rail in both themes. The glyph's own step
+   from 0.66 to full ink is the second half of that pair. `isolation` is what puts the
+   plate behind the glyph: a positioned ::before paints over its row's content, and a
+   negative z-index with no stacking context of its own would drop it behind the rail.
+   why: #429 */
 .ui-nav--side.is-collapsed .ui-nav__item.is-active { isolation: isolate; background: none; }
 /* At rest only — box-shadow carries the hairline AND the focus ring (WCAG 2.4.7). */
 .ui-nav--side.is-collapsed .ui-nav__item.is-active:not(:focus-visible) { box-shadow: none; }
@@ -281,10 +289,9 @@
   background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   z-index: -1;
 }
-/* Hover's hairline is an outline on a row that keeps the open column, so on the
-   strip it too is drawn with no right edge. A folded rail answers a pointer with
-   the row's own ink and the name beside it, which is the whole readout at this
-   width. At rest only, so the focus ring is left standing. */
+/* A folded rail answers a pointer with the row's own ink and the name beside it,
+   which is the whole readout at this width — the hover wash stands, the edge
+   around it does not. At rest only, so the focus ring is left standing. */
 .ui-nav--side.is-collapsed .ui-nav__item:hover:not(:focus-visible) { outline: none; }
 
 /* -- Horizontal tabs ----------------------------------------------------- */

package/src/styles/topbar.css

@@ -191,7 +191,7 @@
    src/styles/dropdown.css:176 `.ui-dropdown__item:hover`.
    why: docs/specification.md#elevation */
 .vopt:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
-/* The row is a keyboard stop: src/components/dropdown.js:554
+/* The row is a keyboard stop: src/components/dropdown.js:804
    `items[next < 0 ? 0 : next]?.focus()` moves focus onto a `[data-dd-item]` with
    the arrow keys, and this is one. It takes the ring on its own 10px radius, the
    same way `.amenu a` above does. #482 */