@celestia-island/hikari 0.55.134 → 0.55.135

package/package.json

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

package/src/components/HkMenu.tsx

@@ -157,6 +157,17 @@ export default defineComponent({
      * length, applied on the `dvh`-capable branch, never sanitized.
      */
     maxHeight: { type: String, default: undefined },
+    /**
+     * Forwarded to the desktop popout panels' `autoFlip` (HkSelectPanel):
+     * whether a panel whose placed side cannot host it migrates to the
+     * opposite vertical side. Default true — every existing consumer
+     * keeps the flip. Hosts that must keep the popup on its placed side
+     * (the fill-template field's vocabulary panel anchors DIRECTLY BELOW
+     * its field, user direction 2026-10-10) pass `false`; the viewport
+     * clamp then absorbs the overflow instead. Mobile sheets have no
+     * flip to make — the prop never reaches them.
+     */
+    autoFlip: { type: Boolean, default: true },
     /**
      * Sidebar variant only: every collapsible group renders EXPANDED
      * until the user collapses it — nav sidebars that read as a table of
@@ -606,6 +617,7 @@ export default defineComponent({
           offset={cfg.offset}
           matchAnchorWidth={cfg.match}
           maxHeight={props.maxHeight}
+          autoFlip={props.autoFlip}
           onUpdate:open={(v: boolean) => {
             if (!v) onRootCloseRequest();
           }}
@@ -634,6 +646,7 @@ export default defineComponent({
               placement="bottom-start"
               offset={0}
               maxHeight={props.maxHeight}
+              autoFlip={props.autoFlip}
               onUpdate:open={(v: boolean) => {
                 if (!v) onSubCloseRequest(level);
               }}

package/src/components/HkSelectPanel.test.tsx

@@ -431,6 +431,38 @@ describe("HkSelectPanel custom invocation", () => {
       window.innerHeight = prevHeight;
     }
   });
+
+  it("autoFlip: false keeps a starved bottom popout below its anchor (clamped)", async () => {
+    // The below-first rule (HkTemplateField's vocabulary panel): an
+    // anchor near the viewport bottom with room only ABOVE must not
+    // migrate the panel above — with autoFlip off the placed side holds
+    // (data-side stays "bottom", so the pop motion still grows the panel
+    // out of the anchor's bottom edge) and the clamp slides the panel up
+    // only as far as full visibility requires. The default flips the
+    // same rig top-side — that direction is pinned by the tall-popout
+    // clamp test above.
+    const prevHeight = window.innerHeight;
+    window.innerHeight = 800;
+    try {
+      const { container, open } = mountPanel({ placement: "bottom-start", autoFlip: false });
+      await nextTick();
+
+      const anchor = container.querySelector<HTMLButtonElement>("button")!;
+      anchor.getBoundingClientRect = () =>
+        ({ top: 760, bottom: 780, left: 40, right: 140, width: 100, 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");
+      // Raw top 780 + offset 4 = 784 overflows on an 800px viewport
+      // (happy-dom measures the panel at the 200px fallback): the clamp
+      // pins it to 800 - 200 - 16 = 584 instead of flipping.
+      expect(Number.parseInt(host.style.top, 10)).toBe(584);
+    } finally {
+      window.innerHeight = prevHeight;
+    }
+  });
 });
 
 describe("HkSelectPanel back-guard (window-first back priority)", () => {

package/src/components/HkSelectPanel.tsx

@@ -91,6 +91,19 @@ export default defineComponent({
       type: String as PropType<SelectPanelPlacement>,
       default: "bottom-start",
     },
+    /**
+     * Auto-flip to the opposite vertical side when the placed side cannot
+     * host the panel. Default true — plain dropdowns read better flipped
+     * than clamped over their trigger. Surfaces whose popup must stay
+     * anchored BELOW their field regardless of how the viewport happens
+     * to be filled (the fill-template field's vocabulary panel: user
+     * direction 2026-10-10 — it opens in the flow under the input, never
+     * migrating above it) pass `false`: the panel keeps the placed side
+     * and the viewport clamp absorbs the overflow instead (an oversized
+     * panel slides up over the anchor only as far as full visibility
+     * requires).
+     */
+    autoFlip: { type: Boolean, default: true },
     /** Gap between anchor and popout, in px. */
     offset: { type: Number, default: 4 },
     /** Popout min-width follows the anchor width (select parity). */
@@ -557,13 +570,17 @@ export default defineComponent({
         side === "top"
           ? r.top - props.offset - ph
           : r.bottom + props.offset;
-      // Auto-flip when the chosen side cannot host the panel.
-      if (side === "bottom" && top + ph > frame.y + frame.height - pad) {
-        side = "top";
-        top = r.top - props.offset - ph;
-      } else if (side === "top" && top < frame.y + pad) {
-        side = "bottom";
-        top = r.bottom + props.offset;
+      // Auto-flip when the chosen side cannot host the panel (opt-out
+      // via autoFlip: false keeps the placed side; the clamp below then
+      // absorbs an overflow instead of migrating the panel).
+      if (props.autoFlip) {
+        if (side === "bottom" && top + ph > frame.y + frame.height - pad) {
+          side = "top";
+          top = r.top - props.offset - ph;
+        } else if (side === "top" && top < frame.y + pad) {
+          side = "bottom";
+          top = r.bottom + props.offset;
+        }
       }
       const align = props.placement.endsWith("-center")
         ? "center"

package/src/components/HkTemplateField.scss

@@ -75,7 +75,19 @@
   min-height: calc(1.5rem + var(--space-4, 4px));
   display: flex;
   flex-wrap: wrap;
-  align-items: center;
+  // Baseline alignment (user direction 2026-10-10): the chip's smaller
+  // monospace text must share the literal text's BASELINE, not its box
+  // midpoint — `center` centered the chip's box, which floats the chip's
+  // baseline a fraction above the surrounding text's (smaller font,
+  // same-height line) and read as the chip riding high. Baseline is the
+  // flex-native fix: text runs and chips (inline-flex, whose baseline
+  // is its content text's) align on one shared baseline with no pixel
+  // nudges. `align-content: center` keeps the single-line read
+  // vertically centered inside the min-height box — the line sizes to
+  // its content and the LINE centers, where plain `baseline` alone
+  // would top-align it in the stretched line.
+  align-items: baseline;
+  align-content: center;
   gap: 2px 3px;
   font-size: var(--text-base, 0.875rem);
   line-height: 1.5;

package/src/components/HkTemplateField.styles.test.ts

@@ -17,7 +17,12 @@ import { describe, expect, it } from "vitest";
  *      mobile sheet must keep the panel as the ONE scroll region;
  *   2. the scroll host is a positioning context (`position: relative`)
  *      for the overlay rails;
- *   3. a curated class list checks TSX→CSS (no unstyled element) and a
+ *   3. the edit's children align on the shared text BASELINE
+ *      (`align-items: baseline` + `align-content: center`) and no chip
+ *      rule carries a manual vertical nudge — the flex alignment IS the
+ *      fix for the chip-rides-high report, a pixel hack would be a
+ *      regression;
+ *   4. a curated class list checks TSX→CSS (no unstyled element) and a
  *      reverse scan flags any `hk-tpl-*`/`hk-template-*` selector in the
  *      sheet that no source file renders (no dead rule).
  */
@@ -109,6 +114,41 @@ describe("HkTemplateField stylesheet contract", () => {
     expect(css).toMatch(/\.hk-tpl-editor-scroll\s*\{[^}]*position:\s*relative/s);
   });
 
+  it("aligns the edit's children on the shared text baseline, never box centers", () => {
+    // The chip's smaller monospace text must share the literal text's
+    // BASELINE (flex-native `align-items: baseline`), not the box
+    // midpoint — centering the box floats the chip's baseline a fraction
+    // above the surrounding text's and reads as the chip riding high
+    // (user report 2026-10-10). Restoring `center` must fail here.
+    expect(css).toMatch(/\.hk-template-field-edit\s*\{[^}]*align-items:\s*baseline/s);
+    expect(css).not.toMatch(/\.hk-template-field-edit\s*\{[^}]*align-items:\s*center/s);
+    // The single-line read stays vertically centered in the min-height
+    // box via the LINE centering (align-content) — plain baseline alone
+    // would top-align it in the stretched line.
+    expect(css).toMatch(/\.hk-template-field-edit\s*\{[^}]*align-content:\s*center/s);
+    // The chip editor's current-token line (static chip + description)
+    // has been baseline-aligned since introduction — it predates the
+    // edit-container fix and stays that way (an R1 review round caught
+    // a mutation-recovery slip that had silently flipped it).
+    expect(css).toMatch(/\.hk-tpl-editor-current\s*\{[^}]*align-items:\s*baseline/s);
+  });
+
+  it("aligns chips by flex baseline, never by pixel nudges", () => {
+    // The baseline contract is the alignment layout itself: no manual
+    // vertical offsets on the chip inside the edit (a margin/translate
+    // hack would re-introduce the drift the alignment fixes, tuned to
+    // one font size). The dark-mode and unknown variants ride the same
+    // box, so the whole chip block must stay offset-free.
+    const chipRules = [...css.matchAll(/([^{}]*\.hk-tpl-chip[^{}]*)\{([^}]*)\}/g)];
+    // Extraction sanity (never trust a 0-hit scan): the chip is styled.
+    expect(chipRules.length).toBeGreaterThan(0);
+    for (const [, selector, body] of chipRules) {
+      expect(body, `chip rule ${(selector ?? "").trim()} must not nudge vertically`).not.toMatch(
+        /margin-(top|bottom)|translate[XY]|\btop:|\bbottom:|vertical-align/,
+      );
+    }
+  });
+
   it("styles every editor class the TSX renders", () => {
     const emitted = classTokensFrom(tsx);
     for (const cls of ["hk-template-field", "hk-template-field-edit", "hk-template-field-box",

package/src/components/HkTemplateField.test.tsx

@@ -774,3 +774,85 @@ describe("HkTemplateField vocabulary semantics guards", () => {
     expect(active[0]!.textContent).toContain("username");
   });
 });
+
+describe("HkTemplateField popup direction (below-first)", () => {
+  /** Fixed visual rect (the rootzoom rig's shape). */
+  function rect(x: number, y: number, w: number, h: number): DOMRect {
+    return {
+      x, y, width: w, height: h, top: y, left: x, right: x + w, bottom: y + h,
+      toJSON: () => ({}),
+    } as DOMRect;
+  }
+
+  async function flushFrames() {
+    await nextTick();
+    for (let i = 0; i < 3; i++) {
+      await new Promise((r) => setTimeout(r, 0));
+      await new Promise((r) => requestAnimationFrame(() => r(null)));
+    }
+  }
+
+  it("the vocabulary panel stays below a field anchored near the viewport bottom", async () => {
+    // Below-first (user direction 2026-10-10): a low field with room only
+    // ABOVE must not migrate the panel above the field — the panel keeps
+    // the placed bottom side (data-side drives the pop motion's origin)
+    // and the viewport clamp absorbs the overflow. The default-flip
+    // behavior for plain panels is pinned over in HkSelectPanel's own
+    // suite; this pins the field's opt-out through the HkMenu wiring.
+    const prevHeight = window.innerHeight;
+    window.innerHeight = 800;
+    try {
+      const el = mount({ modelValue: "" });
+      await nextTick();
+      const edit = editable(el);
+      edit.getBoundingClientRect = () => rect(40, 760, 300, 20);
+      await openTrigger(el, "{{ us");
+
+      const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+      expect(host).toBeTruthy();
+      expect(host.dataset.side).toBe("bottom");
+      // Raw top 780 + menu offset 6 = 786 overflows the 800px viewport
+      // (the panel measures at the 200px happy-dom fallback): clamped to
+      // 800 - 200 - 16 = 584 instead of flipping.
+      expect(Number.parseInt(host.style.top, 10)).toBe(584);
+    } finally {
+      window.innerHeight = prevHeight;
+    }
+  });
+
+  it("the chip editor popover stays below a chip anchored near the viewport bottom", async () => {
+    // Same below-first rule for the chip editor (autoFlip off on the
+    // HPopover): without it, a 300px-tall panel beside a chip with 20px
+    // of room below flips top-side — exactly the overlap the user
+    // reported. The panel's rect is faked at the prototype (the
+    // rootzoom rig's approach) so the flip comparison has real numbers.
+    const prevHeight = window.innerHeight;
+    window.innerHeight = 800;
+    const gBCR = vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(
+      function (this: HTMLElement) {
+        if (this.classList.contains("hk-tpl-chip")) return rect(40, 760, 120, 20);
+        if (this.classList.contains("hk-popover-panel")) return rect(0, 0, 220, 300);
+        return rect(0, 0, 0, 0);
+      },
+    );
+    try {
+      const el = mount({ modelValue: "https://g.com/{{username}}.png" });
+      await nextTick();
+      editable(el).querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+      await flushFrames();
+
+      const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+      expect(panel).toBeTruthy();
+      // No flip: the resolved placement keeps the bottom side.
+      expect(panel.className).toContain("hk-popover-bottom-start");
+      expect(panel.className).not.toContain("hk-popover-top-start");
+      // And the position: raw top 780 + offset 4 = 784, clamped to
+      // 800 - 300 - 16 = 484 (full visibility beats the anchor gap).
+      const host = panel.parentElement!;
+      expect(host.style.top).toBe("484px");
+    } finally {
+      gBCR.mockRestore();
+      window.innerHeight = prevHeight;
+    }
+  });
+});

package/src/components/HkTemplateField.tsx

@@ -59,12 +59,14 @@ function isSubsequence(query: string, text: string): boolean {
  * the styled form of the exact template it serializes to — Gutenberg
  * style, without any block chrome:
  *
- * - typing `{{` opens the vocabulary panel (desktop: anchored under the
- *   caret's field; phone: the standard bottom sheet) and picking a row
- *   inserts the chip; typing a full `{{ name }}` by hand converts it
- *   just the same;
- * - clicking a chip opens the chip editor (desktop: a popover beside
- *   the chip; phone: a bottom sheet) whose form owns the concrete
+ * - typing `{{` opens the vocabulary panel (desktop: anchored DIRECTLY
+ *   BELOW the field — below-first by user direction 2026-10-10, the
+ *   viewport clamp absorbs a short viewport instead of a flip; phone:
+ *   the standard bottom sheet) and picking a row inserts the chip;
+ *   typing a full `{{ name }}` by hand converts it just the same;
+ * - clicking a chip opens the chip editor (desktop: a popover directly
+ *   below the chip, same below-first rule; phone: a bottom sheet) whose
+ *   form owns the concrete
  *   editing — swap the placeholder for another vocabulary entry, read
  *   what it fills from, or remove it — and FOCUS MOVES INTO the form so
  *   the next keystroke lands there;
@@ -1015,9 +1017,13 @@ export const HkTemplateField = defineComponent({
         {props.hint && !props.error && <p class="hk-template-field-hint">{props.hint}</p>}
         {props.error && <p class="hk-template-field-error">{props.error}</p>}
 
-        {/* Vocabulary panel — anchored under the field on desktop, the
-            standard bottom sheet on phone. The editable keeps focus;
-            rows click through, arrows/Enter ride the editable keydown. */}
+        {/* Vocabulary panel — anchored DIRECTLY BELOW the field on
+            desktop (autoFlip off, user direction 2026-10-10: the panel
+            opens in the flow under the input it completes; when the
+            viewport below is too short the clamp slides it up only as
+            far as full visibility requires), the standard bottom sheet
+            on phone. The editable keeps focus; rows click through,
+            arrows/Enter ride the editable keydown. */}
         <HkMenu
           variant="popup"
           items={[]}
@@ -1029,6 +1035,7 @@ export const HkTemplateField = defineComponent({
           placement="bottom-start"
           matchAnchorWidth
           maxHeight="min(18rem, 45dvh)"
+          autoFlip={false}
           title={t("hikari::templateField.suggestTitle", "Placeholders")}
         >
           {filteredTokens.value.length > 0 ? (
@@ -1053,8 +1060,10 @@ export const HkTemplateField = defineComponent({
           )}
         </HkMenu>
 
-        {/* Chip editor — a popover beside the chip on desktop, a bottom
-            sheet on phone; the form inside owns the concrete editing. */}
+        {/* Chip editor — a popover directly below the chip on desktop
+            (autoFlip off, same below-first rule as the vocabulary panel:
+            user direction 2026-10-10), a bottom sheet on phone; the form
+            inside owns the concrete editing. */}
         <HPopover
           modelValue={editorOpen.value}
           onUpdate:modelValue={(v: boolean) => {
@@ -1073,6 +1082,7 @@ export const HkTemplateField = defineComponent({
           anchorRef={editorChip.value}
           sheetOnMobile
           placement="bottom-start"
+          autoFlip={false}
           title={t("hikari::templateField.chipEditorTitle", "Edit placeholder")}
         >
           <div class="hk-tpl-editor" onFocusin={() => { editorHoldsFocus.value = true; }}>