@celestia-island/hikari 0.43.0 → 0.43.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.43.0",
+  "version": "0.43.2",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/DemoApp.tsx

@@ -150,6 +150,8 @@ export default defineComponent({
         { key: "c", label: "Archived" },
       ],
     });
+    const centerAnchor = ref<HTMLElement | null>(null);
+    const centerPanelOpen = ref(false);
     function togglePanelOpt(key: string, v: boolean) {
       panel.value.checked = v
         ? [...panel.value.checked, key]
@@ -417,6 +419,26 @@ export default defineComponent({
                 >{opt.label}</HCheckbox>
               ))}
             </HSelectPanel>
+            <span style="align-self:center;color:var(--color-muted, gray)">center placement:</span>
+            <span ref={centerAnchor} style="display:inline-flex">
+              <HButton onClick={() => (centerPanelOpen.value = !centerPanelOpen.value)}>Engine {centerPanelOpen.value ? <ChevronUp size={14} /> : <ChevronDown size={14} />}</HButton>
+            </span>
+            <HSelectPanel
+              open={centerPanelOpen.value}
+              onUpdate:open={(v: boolean) => (centerPanelOpen.value = v)}
+              anchorRef={centerAnchor.value ?? null}
+              title="Engine"
+              placement="top-center"
+              matchAnchorWidth={false}
+            >
+              {panel.value.opts.map((opt) => (
+                <HCheckbox
+                  key={opt.key}
+                  modelValue={panel.value.checked.includes(opt.key)}
+                  onUpdate:modelValue={(v: boolean) => togglePanelOpt(opt.key, v)}
+                >{opt.label}</HCheckbox>
+              ))}
+            </HSelectPanel>
           </div>
         </section>
 

package/src/components/HkSelect.scss

@@ -106,14 +106,16 @@
   position: fixed;
   min-width: 180px;
 
-  /* Pop motion family — the popout grows out of the anchor edge it sits
-   * on (data-side/data-align are set by HkSelectPanel from the RESOLVED
-   * placement, including after an auto-flip) and retracts back into it.
-   * Same tokens as HkPopover/HkTooltip so every anchored surface moves
-   * with one curve. */
+  /* Pop motion family — the popout grows out of the anchor edge (or
+   * midpoint, for the -center placements) it sits on (data-side/data-align
+   * are set by HkSelectPanel from the RESOLVED placement, including after
+   * an auto-flip) and retracts back into it. Same tokens as
+   * HkPopover/HkTooltip so every anchored surface moves with one curve. */
   &[data-side="bottom"] { transform-origin: top left; }
+  &[data-side="bottom"][data-align="center"] { transform-origin: top center; }
   &[data-side="bottom"][data-align="end"] { transform-origin: top right; }
   &[data-side="top"] { transform-origin: bottom left; }
+  &[data-side="top"][data-align="center"] { transform-origin: bottom center; }
   &[data-side="top"][data-align="end"] { transform-origin: bottom right; }
 }
 
@@ -175,9 +177,24 @@
   /* Menu/switcher panels overflow a bare 240px cap even on tall viewports
      (user feedback 2026-08-30: identity header + rows ≈ 320px+). Keep 240px
      as the floor for select lists on short viewports, otherwise let the
-     panel size to its content up to a viewport-relative ceiling. */
+     panel size to its content up to a viewport-relative ceiling — plain-vh
+     first, dvh second, so an engine without dvh drops the dvh twin at PARSE
+     time and keeps the vh cap (the HkModal/HkDrawer/HkImageLightbox rule).
+     A consumer that needs a tighter surface (HkTagInput's catalog) publishes
+     --hk-select-panel-max-height through HkSelectPanel's `maxHeight` prop;
+     that hook rides the dvh-capable branch below, because a dvh value
+     reaching a dvh-less engine through var() would not be parse-dropped but
+     invalid at COMPUTED-value time — which resolves to `max-height: none`,
+     losing the cap entirely. Such an engine keeps the plain-vh ceiling
+     instead, exactly as it does today. */
   max-height: max(240px, min(36rem, calc(100vh - 32px)));
   max-height: max(240px, min(36rem, calc(100dvh - 32px)));
+  @supports (height: 1dvh) {
+    max-height: var(
+      --hk-select-panel-max-height,
+      max(240px, min(36rem, calc(100dvh - 32px)))
+    );
+  }
   display: flex;
   flex-direction: column;
   gap: var(--space-2);
@@ -369,6 +386,17 @@
   min-height: 0;
   overflow-y: auto;
   overscroll-behavior: contain;
+  /* The same consumer-tunable cap the popout reads, applied to the band
+     that actually scrolls: the sheet header keeps its place and the
+     catalog scrolls inside it. `none` (the fallback) is exactly today's
+     behaviour, so an untouched consumer's sheet is unchanged.
+     DELIBERATELY not wrapped in the popout's `@supports (height: 1dvh)`
+     guard: this band's fallback already IS the property's initial value,
+     so a value the engine cannot use resolves to the same `none` the
+     guard would produce — the asymmetry is a no-op, not an oversight.
+     The sheet PANEL above keeps its own plain-vh/dvh family cap either
+     way, so a hidden cap can never leave the sheet unbounded. */
+  max-height: var(--hk-select-panel-max-height, none);
   /* Side insets so the option blocks (full-row hover pills) read as
      cards inside the sheet instead of an edge-to-edge strip glued to
      both screen sides — matching the popover family's breathing room.

package/src/components/HkSelectPanel.test.tsx

@@ -301,6 +301,94 @@ describe("HkSelectPanel custom invocation", () => {
     expect(flipped).toBeGreaterThan(8);
   });
 
+  it("balances a top-center popout on the anchor's horizontal midpoint", async () => {
+    // happy-dom lays nothing out, so the panel measures at the
+    // max(anchor, 180) fallback width — anchor spanning 200..360 (midpoint
+    // 280, fallback width 180) puts the balanced left edge at
+    // 280 - 180/2 = 190.
+    const { container, open } = mountPanel({ placement: "top-center" });
+    await nextTick();
+
+    const anchor = container.querySelector<HTMLButtonElement>("button")!;
+    anchor.getBoundingClientRect = () =>
+      ({ top: 500, bottom: 520, left: 200, right: 360, width: 160, height: 20 }) as DOMRect;
+    open.value = true;
+    await nextTick();
+
+    const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+    expect(host.style.left).toBe("190px");
+    // Top-side still honored (anchor bottom 520 → panel above it), and the
+    // resolved alignment drives the pop motion's transform origin.
+    expect(Number.parseInt(host.style.top, 10)).toBeLessThan(520);
+    expect(host.dataset.align).toBe("center");
+    expect(host.dataset.side).toBe("top");
+
+    // A centered panel poking past the left edge clamps to the viewport
+    // pad instead of mirroring the overflow to both sides: anchor
+    // 0..40 → raw left (20 - 180/2) = -70 → clamped to 8.
+    anchor.getBoundingClientRect = () =>
+      ({ top: 500, bottom: 520, left: 0, right: 40, width: 40, height: 20 }) as DOMRect;
+    window.dispatchEvent(new Event("resize"));
+    await nextTick();
+    expect(host.style.left).toBe("8px");
+  });
+
+  it("reports center alignment through an auto-flip so the pop origin follows", async () => {
+    // mountPanel's rig anchor sits at the very top of the test layout, so
+    // a top-center panel cannot fit above and flips bottom-side — the
+    // flip must carry data-side/data-align with it (transform origin).
+    const { container, open } = mountPanel({ placement: "top-center" });
+    await nextTick();
+    open.value = true;
+    await nextTick();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await nextTick();
+
+    const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+    expect(host.dataset.side).toBe("bottom");
+    expect(host.dataset.align).toBe("center");
+  });
+
+  it("opens an unflipped bottom-center popout below the anchor", async () => {
+    // The bottom-center twin: same balance math, opposite side, and no
+    // flip here (the faked anchor sits low with room below).
+    const { container, open } = mountPanel({ placement: "bottom-center" });
+    await nextTick();
+
+    const anchor = container.querySelector<HTMLButtonElement>("button")!;
+    anchor.getBoundingClientRect = () =>
+      ({ top: 100, bottom: 120, left: 200, right: 360, width: 160, height: 20 }) as DOMRect;
+    open.value = true;
+    await nextTick();
+
+    const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+    expect(host.dataset.side).toBe("bottom");
+    expect(host.dataset.align).toBe("center");
+    // Anchor top 100 + offset 4 → the panel hangs below 104.
+    expect(Number.parseInt(host.style.top, 10)).toBeGreaterThan(120);
+    expect(host.style.left).toBe("190px");
+  });
+
+  it("clamps a centered popout at the right viewport pad near the right edge", async () => {
+    // Anchor hugging the right edge: raw balanced left 1100 + (80 - 180)/2
+    // = 1050 would poke past 1200 - 8 - 180 = 1012 → pinned at the pad.
+    // The expected left edge is viewport arithmetic, so pin the width here
+    // (happy-dom's bare default is 1024 — the afterEach reset only helps
+    // full-file runs, not -t filtering; afterEach re-asserts 1200 anyway).
+    setViewport(1200);
+    const { container, open } = mountPanel({ placement: "bottom-center" });
+    await nextTick();
+
+    const anchor = container.querySelector<HTMLButtonElement>("button")!;
+    anchor.getBoundingClientRect = () =>
+      ({ top: 100, bottom: 120, left: 1100, right: 1180, width: 80, height: 20 }) as DOMRect;
+    open.value = true;
+    await nextTick();
+
+    const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+    expect(host.style.left).toBe("1012px");
+  });
+
   it("clamps a tall flipped popout into the viewport instead of going negative", async () => {
     // The taller viewport-relative CSS cap admits ~576px panels: anchored
     // mid-viewport (top 380 / bottom 424 on an 800px-tall viewport), a

package/src/components/HkSelectPanel.tsx

@@ -47,6 +47,15 @@ import "./HkSelect.scss";
  * events on the panel surface are forwarded (`keydown`) so owners that own
  * an option model (like HkSelect) can run their own arrow/enter navigation.
  *
+ * Geometry is the surface's to decide: `matchAnchorWidth` (default true,
+ * select parity) ties the popout's minimum width to the trigger, and the
+ * optional `maxHeight` caps whichever element scrolls (the desktop popout,
+ * the mobile sheet's list band). Both are opt-outs — a consumer that passes
+ * neither gets the historic panel, which is what every existing caller
+ * does; a consumer whose content should scroll inside a hugged surface
+ * (a tag catalog, a long filter list) sets them and relies on the panel's
+ * ONE scrollbar.
+ *
  * Mobile sheets also run a duplicate-title filter: content that opens with
  * a non-interactive heading exactly repeating the panel `title` is hidden
  * (`.hk-sheet-dup-title`) — the sheet header already names the sheet, and
@@ -56,8 +65,10 @@ import "./HkSelect.scss";
 
 export type SelectPanelPlacement =
   | "bottom-start"
+  | "bottom-center"
   | "bottom-end"
   | "top-start"
+  | "top-center"
   | "top-end";
 
 const VIEWPORT_PAD = 8;
@@ -71,7 +82,10 @@ export default defineComponent({
     anchorRef: { type: Object as PropType<HTMLElement | null>, default: null },
     /** Sheet header on mobile / a11y name for the panel. */
     title: { type: String, default: "" },
-    /** Base placement of the popout relative to the anchor (auto-flips). */
+    /** Base placement of the popout relative to the anchor (auto-flips).
+     *  The `-center` variants center the popout on the anchor's horizontal
+     *  midpoint (footer-center triggers whose menus would otherwise read
+     *  as lopsided off a narrow pill). */
     placement: {
       type: String as PropType<SelectPanelPlacement>,
       default: "bottom-start",
@@ -80,6 +94,23 @@ export default defineComponent({
     offset: { type: Number, default: 4 },
     /** Popout min-width follows the anchor width (select parity). */
     matchAnchorWidth: { type: Boolean, default: true },
+    /** Cap for the surface that scrolls — the desktop popout or the
+     *  mobile sheet's list band — as ANY CSS length (`min(18rem, 45dvh)`,
+     *  `24rem`, `calc(50vh - 3rem)`).
+     *
+     *  Undefined (the default) keeps the stylesheet's own ceilings, so
+     *  every existing consumer is untouched; a consumer whose content
+     *  should scroll instead of stretching the panel to the viewport sets
+     *  it, and the panel's ONE scrollbar (never a second region) does the
+     *  rest. Applied through the `--hk-select-panel-max-height` hook
+     *  HkSelect.scss reads, inside its `@supports (height: 1dvh)` branch —
+     *  a value an engine cannot use is therefore IGNORED rather than
+     *  clamped: the popout keeps the plain-vh ceiling it has today.
+     *  A MALFORMED value (a typo, a bare number) is likewise not sanitized:
+     *  the substituted declaration becomes invalid at computed-value time
+     *  and resolves to `max-height: none`, i.e. the surface is UNCAPPED —
+     *  the type gate is a CSS length, the value gate is the consumer's. */
+    maxHeight: { type: String, default: undefined },
     /** Dock as a bottom sheet on phone-width viewports. */
     sheetOnMobile: { type: Boolean, default: true },
   },
@@ -315,6 +346,14 @@ export default defineComponent({
     const sheetBodyRef = ref<HTMLElement>();
     const coords = ref<{ top?: string; left?: string; minWidth?: string }>({});
 
+    /** Host-tunable surface cap (the `maxHeight` prop): published as the
+     *  custom property HkSelect.scss reads on whichever element scrolls,
+     *  so the stylesheet keeps today's ceiling as its fallback and a
+     *  consumer that passes nothing renders exactly as before. */
+    const surfaceCap = computed<Record<string, string> | undefined>(() =>
+      props.maxHeight ? { "--hk-select-panel-max-height": props.maxHeight } : undefined,
+    );
+
     // ── overlay scrollbar (shared chrome) ─────────────────────────
     // Attached per open on whichever surface scrolls — the desktop
     // popout or the mobile sheet list — and detached on close/unmount
@@ -474,9 +513,10 @@ export default defineComponent({
     // again after the DOM settles, when the panel's real box is known and
     // flip/clamp decisions can use actual numbers.
     /** Resolved popout orientation — drives the pop transition's
-     *  transform-origin (grow from the anchor edge, data-side/align on
-     *  the host). Updated by positionPanel on every reposition. */
-    const resolved = ref<{ side: "top" | "bottom"; align: "start" | "end" }>({
+     *  transform-origin (grow from the anchor edge or midpoint,
+     *  data-side/align on the host). Updated by positionPanel on every
+     *  reposition. */
+    const resolved = ref<{ side: "top" | "bottom"; align: "start" | "center" | "end" }>({
       side: "bottom",
       align: "start",
     });
@@ -501,10 +541,12 @@ export default defineComponent({
         side = "bottom";
         top = r.bottom + props.offset;
       }
-      resolved.value = {
-        side,
-        align: props.placement.endsWith("-end") ? "end" : "start",
-      };
+      const align = props.placement.endsWith("-center")
+        ? "center"
+        : props.placement.endsWith("-end")
+          ? "end"
+          : "start";
+      resolved.value = { side, align };
       // One flip never re-checks: taller menu panels (the viewport-relative
       // CSS cap) made this band reachable — a mid-viewport anchor flips
       // bottom→top into a negative top that was applied verbatim. Clamp so
@@ -512,7 +554,15 @@ export default defineComponent({
       // the panel's own internal scroll takes over.
       const maxTop = Math.max(VIEWPORT_PAD, window.innerHeight - VIEWPORT_PAD - ph);
       top = Math.min(Math.max(top, VIEWPORT_PAD), maxTop);
-      let left = props.placement.endsWith("-end") ? r.right - pw : r.left;
+      // -center balances the panel on the anchor's horizontal midpoint
+      // (still clamped, so a half-off-screen anchor keeps the panel
+      // readable instead of mirroring the overflow to both edges).
+      let left =
+        align === "center"
+          ? r.left + (r.width - pw) / 2
+          : props.placement.endsWith("-end")
+            ? r.right - pw
+            : r.left;
       const maxLeft = Math.max(VIEWPORT_PAD, window.innerWidth - VIEWPORT_PAD - pw);
       left = Math.min(Math.max(left, VIEWPORT_PAD), maxLeft);
       coords.value = {
@@ -616,7 +666,11 @@ export default defineComponent({
                     </HIconButton>
                   </div>
                   <div class="hk-select-sheet-body" ref={sheetBodyRef}>
-                    <div class="hk-select-sheet-list" ref={sheetListRef}>
+                    <div
+                      class="hk-select-sheet-list"
+                      ref={sheetListRef}
+                      style={surfaceCap.value}
+                    >
                       <div class="hk-select-sheet-content" ref={sheetContentRef}>
                         {slots.default?.()}
                       </div>
@@ -647,6 +701,7 @@ export default defineComponent({
                 <div
                   ref={panelRef}
                   class="hk-select-popout"
+                  style={surfaceCap.value}
                   aria-label={props.title || undefined}
                   onKeydown={forwardKeydown}
                 >

package/src/components/HkTagInput.scss

@@ -3,7 +3,10 @@
  * HkInput's box (border, radius, rhythm, focus ring) so a tag field sits
  * flush beside plain inputs in the same form; the panel chrome mirrors
  * HkAffixPicker's popup (search on top, rows below, NO inner scroll
- * region — the HkSelectPanel window owns the single scrollbar). */
+ * region — the HkSelectPanel window owns the single scrollbar, capped by
+ * the component's `maxHeight` so a long catalog scrolls there instead of
+ * stretching the panel). Chips and selected rows are reorderable; the
+ * drag states (`data-dragging` / `data-drop`) live at the bottom. */
 
 .hk-tag-input-wrapper {
   display: block;
@@ -78,6 +81,15 @@
 
 .hk-tag-input-tag {
   max-width: 100%;
+  /* Reorder affordance: the chip BODY is the handle. */
+  cursor: grab;
+  /* A press that becomes a drag must not paint a text selection, and a
+   * touch that starts scrolling vertically belongs to the page (the
+   * browser takes the gesture back with a pointercancel; a horizontal
+   * drag is ours — see usePointerReorder). */
+  user-select: none;
+  -webkit-user-select: none;
+  touch-action: pan-y;
 }
 
 .hk-tag-input-tag-text {
@@ -87,6 +99,14 @@
   white-space: nowrap;
 }
 
+/* A disabled field reorders nothing: the chips drop the grab affordance
+ * (and the gesture reservation with it) — the box's own not-allowed
+ * cursor takes over. */
+.hk-tag-input-box[data-disabled] .hk-tag-input-tag {
+  cursor: default;
+  touch-action: auto;
+}
+
 /* ── inline typing input / placeholder ────────────────────────────── */
 .hk-tag-input-element {
   /* Auto-growing: the element's width is published inline in `ch`
@@ -171,6 +191,12 @@
 .hk-tag-input-panel {
   display: flex;
   flex-direction: column;
+  /* A FIXED measure, not a content-driven one: the popout is positioned
+   * once when it opens, so a panel that grew with its content would shift
+   * its own left edge mid-interaction — toggling a row adds a check glyph,
+   * and a query changes which rows (and how much meta text) survive.
+   * min/max stay as the bounds a narrow viewport imposes on that width. */
+  width: min(19rem, calc(100vw - 2rem));
   min-width: 13rem;
   max-width: min(19rem, calc(100vw - 2rem));
 }
@@ -291,6 +317,62 @@
   font-variant-numeric: tabular-nums;
 }
 
+/* ── reordering ───────────────────────────────────────────────────── */
+/* Live drag (both lists): the item being moved dims, the slot it would
+ * land in is ringed. Chips carry the state as classes (HkTag takes no
+ * arbitrary attributes), panel rows as data attributes — both are
+ * assertable hooks that never collide with the pointer/hover faces. */
+.hk-tag-input-tag-dragging,
+.hk-tag-input-row[data-dragging] {
+  opacity: 0.55;
+  cursor: grabbing;
+}
+
+.hk-tag-input-tag-drop {
+  outline: 1px dashed rgb(var(--color-focused-border));
+  outline-offset: 1px;
+}
+
+.hk-tag-input-row[data-drop] {
+  box-shadow: inset 0 0 0 1px rgb(var(--color-focused-border));
+}
+
+/* Drag handle of a SELECTED panel row — the one element that claims the
+ * touch gesture outright, so the sheet keeps scrolling under the rest of
+ * the row. Only selected rows render one: an unselected row is not
+ * draggable and is never a drop target. */
+.hk-tag-input-grip {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  /* The largest target the row rhythm allows: the row's content box is the
+     2.25rem row minus its 4px block padding, so the handle grows to that
+     without changing the option rows' height (the 44px touch guidance
+     cannot fit in a list row — the sheet scrolls through them instead). */
+  width: 1.5rem;
+  height: 1.75rem;
+  margin-inline-end: -4px;
+  color: rgb(var(--color-muted));
+  opacity: 0.6;
+  cursor: grab;
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+  transition: opacity 0.12s ease, color 0.12s ease;
+
+  &:active {
+    cursor: grabbing;
+  }
+}
+
+.hk-tag-input-row:hover .hk-tag-input-grip,
+.hk-tag-input-row[data-dragging] .hk-tag-input-grip,
+.hk-tag-input-grip:focus-visible {
+  opacity: 1;
+  color: rgb(var(--color-text));
+}
+
 .hk-tag-input-empty {
   padding: 14px 12px;
   color: rgb(var(--color-muted));
@@ -301,6 +383,7 @@
 @media (prefers-reduced-motion: reduce) {
   .hk-tag-input-box,
   .hk-tag-input-chevron,
+  .hk-tag-input-grip,
   .hk-tag-input-row {
     transition: none;
   }

package/src/components/HkTagInput.singleScroll.contract.test.ts

@@ -6,6 +6,14 @@
  * `max-height: 17rem; overflow: auto` row region. It has none: the
  * HkSelectPanel window surface (desktop popout / mobile sheet) owns THE
  * single scrollbar and scrolls the search field with the rows as one.
+ *
+ * The 2026-09-11 geometry wave leans on the same contract from the other
+ * side: the field used to hand the panel its own width (`matchAnchorWidth`,
+ * a full-width settings column) while the catalog caps at 19rem, leaving an
+ * empty band and a scrollbar parked far from the rows. The panel now hugs
+ * its own measure, and the catalog scrolls because the SURFACE is capped
+ * (`maxHeight` → the --hk-select-panel-max-height hook) — never because the
+ * row list grew a scroll region of its own.
  */
 import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
@@ -34,6 +42,14 @@ function cssBlock(src: string, selector: string): string {
   return "";
 }
 
+/** The JSX opening tag that carries `marker` (attributes only, no
+ *  children) — the pin below is about what ONE element declares. */
+function jsxOpeningTag(src: string, marker: string): string {
+  const at = src.indexOf(marker);
+  expect(at, `${marker} is rendered`).toBeGreaterThanOrEqual(0);
+  return src.slice(src.lastIndexOf("<", at), src.indexOf(">", at) + 1);
+}
+
 function expectNoScroll(block: string, what: string): void {
   expect(block, `${what} block exists`).toBeTruthy();
   expect(block).not.toMatch(/max-height/);
@@ -61,13 +77,70 @@ describe("HkTagInput single-scrollbar-per-window contract", () => {
     expectNoScroll(block, ".hk-select-sheet-panel .hk-tag-input-panel");
   });
 
-  it("the component mounts no overlay scrollbar machinery", () => {
+  it("the component mounts no overlay scrollbar machinery and clamps no row region", () => {
     expect(tsx).not.toContain("attachOverlayScrollbars");
     expect(tsx).not.toContain("OverlayScrollbarHandle");
-    // No inline clamp on the row list either (the prose in the file
-    // mentions `max-height` in the contract comment, so this pins the
-    // style property spelling instead of the words).
-    expect(tsx).not.toContain("maxHeight");
     expect(tsx).not.toContain("overflowY");
+    // The ONLY max-height in the file belongs to the panel SURFACE prop
+    // (the very next test): the listbox element itself stays unpinned, so
+    // the window keeps the one scroll region.
+    const listEl = jsxOpeningTag(tsx, 'class="hk-tag-input-list"');
+    expect(listEl.startsWith("<div")).toBe(true);
+    expect(listEl).not.toMatch(/style=/);
+    expect(listEl).not.toMatch(/maxHeight|max-height|overflow/);
+  });
+
+  it("hugs its own measure, and scrolls by capping the SURFACE (an additive prop)", () => {
+    const panel = jsxOpeningTag(tsx, "<HkSelectPanel");
+    // The field's width is not the panel's width any more…
+    expect(panel).toContain("matchAnchorWidth={false}");
+    // …and the catalog scrolls inside a capped surface instead of growing
+    // to the stylesheet ceiling.
+    expect(panel).toContain('maxHeight="min(18rem, 45dvh)"');
+    // The cap is the shared panel's own hook, and it is ADDITIVE: the
+    // historic ceiling stays the fallback, so every other consumer of
+    // HkSelectPanel renders exactly as before.
+    const panelScss = readFileSync(join(here, "HkSelect.scss"), "utf-8");
+    // The hook rides the dvh-capable branch: on an engine without dvh the
+    // plain-vh ceiling above it stays the cap — a var()-substituted dvh
+    // value would be invalid at computed-value time and mean "no cap".
+    const popout = panelScss.slice(
+      panelScss.indexOf(".hk-select-popout {"),
+      panelScss.indexOf(".hk-select-option"),
+    );
+    // …and the block's POSITION is load-bearing: the hook must come after
+    // both literal ceilings, or the dvh-capable branch would override them
+    // with its own fallback and the consumer cap would never apply.
+    expect(popout).toContain("@supports (height: 1dvh)");
+    expect(popout.indexOf("@supports")).toBeGreaterThan(
+      popout.indexOf("max-height: max(240px, min(36rem, calc(100vh - 32px)));"),
+    );
+    expect(popout.indexOf("@supports")).toBeGreaterThan(
+      popout.lastIndexOf("max-height: max(240px, min(36rem, calc(100dvh - 32px)));"),
+    );
+    expect(popout).toMatch(
+      /max-height:\s*var\(\s*--hk-select-panel-max-height,\s*max\(240px, min\(36rem, calc\(100dvh - 32px\)\)\)\s*\)/,
+    );
+    expect(popout).toContain("max-height: max(240px, min(36rem, calc(100vh - 32px)));");
+    // The sheet band the same prop caps falls back to being uncapped — the
+    // property's own initial value, i.e. today's behaviour.
+    expect(panelScss).toMatch(
+      /max-height:\s*var\(--hk-select-panel-max-height,\s*none\)/,
+    );
+    const panelTsx = readFileSync(join(here, "HkSelectPanel.tsx"), "utf-8");
+    expect(panelTsx).toContain("maxHeight: { type: String, default: undefined }");
+  });
+
+  it("animates both lists through the shared list transition (FLIP move)", () => {
+    const groups = [...tsx.matchAll(/<HkListTransition\b[^>]*>/g)].map((m) => m[0]);
+    expect(groups, "the chips and the rows are both transition groups").toHaveLength(2);
+    for (const group of groups) {
+      expect(group).toContain('variant="reveal"');
+      expect(group).toMatch(/\bmove\b/);
+      // A fragment tag: the group adds no wrapper element, so the chips
+      // stay the field's own flex items and the rows stay the listbox's
+      // own children.
+      expect(group).toContain('tag=""');
+    }
   });
 });