@celestia-island/hikari 0.40.29 → 0.40.31

package/package.json

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

package/src/components/HkAffixPicker.scss

@@ -67,7 +67,9 @@
   max-width: 24rem;
 }
 
-/* One selected entry: [flag] label (meta) •active-dot   ×]
+/* One selected entry: [flag] value|label (meta) •active-dot   ×]
+ * With `tagValues` the primary text is the key's mapped value (italic
+ * muted "Not set" while empty); without it, the autonym label.
  * The × opens the shared confirm message box — the dialog's Confirm is
  * what actually erases; the × alone never does. */
 .hk-affix-tag {
@@ -126,6 +128,13 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+
+  /* Value-driven tags (HkLocalizedInput): the language is listed but
+   * holds no text yet — the italic muted "Not set" placeholder. */
+  &[data-unset] {
+    font-style: italic;
+    color: rgb(var(--color-muted));
+  }
 }
 
 .hk-affix-tag-meta {
@@ -167,12 +176,12 @@
 }
 
 /* ── option rows ────────────────────────────────────────────────────── */
-/* Positioned host for the overlay scrollbar tracks: wraps ONLY the
- * scrolling list viewport (the menu body also contains the header/
- * search band), carries the popup's width constraints so the geometry
- * is unchanged by the wrapper. */
+/* Width container for the option list — carries the popup's width
+ * constraints so the list block keeps its designed measure inside the
+ * hosting window (HkSelectPanel popout / mobile sheet). It is NOT a
+ * scroll region: the window owns THE single scrollbar and scrolls the
+ * whole popup content (tags + search + rows) as one. */
 .hk-affix-scroll {
-  position: relative;
   display: flex;
   flex-direction: column;
   min-width: 13rem;
@@ -189,20 +198,15 @@
   width: 100%;
 }
 
+/* NO max-height / overflow here — ONE SCROLLBAR PER WINDOW (2026-09-08
+ * user report: the language sheet showed two nested scrollbars, this
+ * list's 17rem cap + the sheet's own). The list grows with its content
+ * and the hosting window scrolls it. */
 .hk-affix-list {
   display: flex;
   flex-direction: column;
   gap: 1px;
   padding: 4px 6px 8px;
-  max-height: 17rem;
-  overflow-y: auto;
-  /* Overlay scrollbar (useOverlayScrollbar) — the native chrome is
-   * always hidden, never styled. */
-  scrollbar-width: none;
-
-  &::-webkit-scrollbar {
-    display: none;
-  }
 }
 
 .hk-affix-row {

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

@@ -0,0 +1,70 @@
+/**
+ * Source contract: ONE SCROLLBAR PER WINDOW (2026-09-08 user report —
+ * the localized input's language sheet showed two nested scrollbars:
+ * the HkSelectPanel sheet's own AND the affix picker's 17rem-capped row
+ * list scrolling inside it). Principle: every window has exactly ONE
+ * scrollbar serving the window's own content; a second scroll level
+ * belongs in a sub-window, never an inline embed. HkAffixPicker's popup
+ * therefore mounts no scroll region of its own — the window surface
+ * (desktop popout / mobile sheet) scrolls tags + search + rows as one.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkAffixPicker.scss"), "utf-8");
+const tsx = readFileSync(join(here, "HkAffixPicker.tsx"), "utf-8");
+
+/** Extract ONE balanced `{...}` declaration block following the given
+ *  selector — a naive `[^}]*` would stop at the first nested `}` and let
+ *  properties appended after a future nested block evade the pin. */
+function cssBlock(src: string, selector: string): string {
+  const at = src.indexOf(selector);
+  expect(at, `${selector} block exists`).toBeGreaterThanOrEqual(0);
+  const open = src.indexOf("{", at);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === "{") depth++;
+    else if (src[i] === "}") {
+      depth--;
+      if (depth === 0) return src.slice(open, i + 1);
+    }
+  }
+  return "";
+}
+
+function expectNoScroll(block: string, what: string): void {
+  expect(block, `${what} block exists`).toBeTruthy();
+  expect(block).not.toMatch(/max-height/);
+  expect(block).not.toMatch(/overflow/);
+  expect(block).not.toMatch(/scrollbar-width/);
+}
+
+describe("HkAffixPicker single-scrollbar-per-window contract", () => {
+  it("the row list carries no max-height and no overflow of its own", () => {
+    expectNoScroll(cssBlock(scss, ".hk-affix-list"), ".hk-affix-list");
+  });
+
+  it("the width container is neither a scroll region nor a track host", () => {
+    const block = cssBlock(scss, ".hk-affix-scroll");
+    expectNoScroll(block, ".hk-affix-scroll");
+    // The old overlay-rail host role is gone — nothing needs a
+    // positioning context anymore.
+    expect(block).not.toMatch(/position\s*:/);
+    // Defense in depth: the mobile-sheet descendant override (width/
+    // centering only) must never grow a scroll region either.
+    const sheetBlock = cssBlock(
+      scss.slice(scss.indexOf(".hk-select-sheet-panel .hk-affix-scroll")),
+      ".hk-affix-scroll",
+    );
+    expect(sheetBlock, "sheet descendant block exists").toBeTruthy();
+    expectNoScroll(sheetBlock, ".hk-select-sheet-panel .hk-affix-scroll");
+  });
+
+  it("the popup mounts no overlay scrollbar machinery", () => {
+    expect(tsx).not.toContain("attachOverlayScrollbars");
+    expect(tsx).not.toContain("OverlayScrollbarHandle");
+  });
+});

package/src/components/HkAffixPicker.test.tsx

@@ -29,6 +29,7 @@ interface MountOptions {
   closeOnSelect?: boolean;
   confirmRemove?: boolean;
   disabled?: boolean;
+  tagValues?: Record<string, string>;
 }
 
 function mountPicker(opts: MountOptions = {}) {
@@ -52,6 +53,7 @@ function mountPicker(opts: MountOptions = {}) {
         closeOnSelect: opts.closeOnSelect,
         confirmRemove: opts.confirmRemove,
         disabled: opts.disabled ?? false,
+        tagValues: opts.tagValues,
         onSelect: (key: string) => events.select.push(key),
         onRemove: (key: string) => events.remove.push(key),
         onCustom: (q: string) => events.custom.push(q),
@@ -213,12 +215,12 @@ describe("HkAffixPicker", () => {
     const { container } = mountPicker();
     await openPopup(container);
     // A no-match query swaps the default slot to the empty branch —
-    // the scrolling list (and its overlay-scrollbar host) unmounts.
+    // the list block unmounts.
     await typeQuery("zzz-none");
     expect(document.querySelector(".hk-affix-empty")).toBeTruthy();
     expect(document.querySelector(".hk-affix-scroll")).toBeNull();
     // Clearing the query remounts a FRESH list — the row list must come
-    // back and the overlay host must be remounted for the scrollbar.
+    // back inside its width container.
     await typeQuery("");
     expect(document.querySelector(".hk-affix-empty")).toBeNull();
     expect(rows().map((r) => r.textContent)).toEqual([
@@ -380,4 +382,66 @@ describe("HkAffixPicker", () => {
     await openPopup(container);
     expect(rows()).toHaveLength(0);
   });
+
+  it("tagValues swaps the tag primary text to each key's value", async () => {
+    const { container } = mountPicker({
+      mode: "multi",
+      selected: ["cn", "jp"],
+      tagValues: { cn: "China's stored text", jp: "  " },
+    });
+    await openPopup(container);
+    const texts = tags().map(
+      (t) => t.querySelector(".hk-affix-tag-text")?.textContent,
+    );
+    // cn carries its stored value; jp (whitespace-only = unfilled) shows
+    // the italic unset placeholder.
+    expect(texts).toEqual(["China's stored text", "Not set"]);
+    expect(tags()[0].querySelector(".hk-affix-tag-text")?.hasAttribute("data-unset")).toBe(false);
+    expect(tags()[1].querySelector(".hk-affix-tag-text")?.hasAttribute("data-unset")).toBe(true);
+    // The autonym survives as the tag's identity in the title (and the
+    // confirm dialog / aria naming, asserted in the dialog tests).
+    expect(
+      tags()[0].querySelector<HTMLButtonElement>(".hk-affix-tag-body")?.title,
+    ).toContain("China");
+    // The pick rows are untouched — they keep the autonym labels.
+    expect(rows().map((r) => r.textContent)).toEqual([
+      expect.stringContaining("中华人民共和国"),
+      expect.stringContaining("United States"),
+    ]);
+  });
+
+  it("a tagValues key missing from the map renders the unset placeholder", async () => {
+    const { container } = mountPicker({
+      mode: "multi",
+      selected: ["us"],
+      tagValues: {},
+    });
+    await openPopup(container);
+    const text = tags()[0].querySelector(".hk-affix-tag-text")!;
+    expect(text.textContent).toBe("Not set");
+    expect(text.hasAttribute("data-unset")).toBe(true);
+  });
+
+  it("without tagValues the tags keep the autonym labels (no unset state)", async () => {
+    const { container } = mountPicker({ mode: "multi", selected: ["cn"] });
+    await openPopup(container);
+    const text = tags()[0].querySelector(".hk-affix-tag-text")!;
+    expect(text.textContent).toBe("China");
+    expect(text.hasAttribute("data-unset")).toBe(false);
+  });
+
+  it("mounts NO inner scroll region — the window owns the one scrollbar", async () => {
+    const { container } = mountPicker({
+      mode: "multi",
+      selected: ["cn", "jp", "us"],
+    });
+    await openPopup(container);
+    expect(
+      document.querySelector<HTMLElement>(".hk-affix-list"),
+      "row list renders",
+    ).toBeTruthy();
+    // No overlay-scroll chrome of the list's own inside the popup — the
+    // CSS/text half of the contract is pinned by the contract test.
+    expect(document.querySelector(".hk-affix-list .hk-scrollbar-track")).toBeNull();
+  });
 });

package/src/components/HkAffixPicker.tsx

@@ -1,8 +1,6 @@
 import {
   computed,
   defineComponent,
-  nextTick,
-  onBeforeUnmount,
   ref,
   watch,
   type PropType,
@@ -12,10 +10,6 @@ import {
 import { ChevronDown, Plus, Search, X } from "lucide-vue-next";
 
 import { useI18n } from "../i18n/context";
-import {
-  attachOverlayScrollbars,
-  type OverlayScrollbarHandle,
-} from "../composables/useOverlayScrollbar";
 
 import HkInput from "./HkInput";
 import HkListTransition from "./HkListTransition";
@@ -71,6 +65,23 @@ function isSubsequence(query: string, text: string): boolean {
  *     without leaving the keyboard flow (Enter picks the first row, or
  *     the custom row when nothing matches).
  *
+ * ONE SCROLLBAR PER WINDOW: the popup mounts NO scroll region of its
+ * own — the window surface it opens as (the desktop popout or the
+ * mobile bottom sheet, both provided by HkSelectPanel) owns THE single
+ * scrollbar and scrolls the whole popup content (tags + search + rows)
+ * as one. The row list deliberately carries no max-height/overflow; a
+ * nested second scrollbar inside the same window is a contract
+ * violation (2026-09-08 user report: the language sheet scrolled twice).
+ *
+ * With `tagValues`, the multi picker's TAG LIST switches to
+ * value-driven primary text: a selected key renders its mapped value
+ * (trimmed), and a key with no value renders `tagUnsetText` in an
+ * italic muted state (`data-unset`) — "the language is listed but
+ * nothing typed yet". The autonym label stays in the tag's title /
+ * aria naming and the confirm dialog, which identify the LANGUAGE, not
+ * the current text. Hosts that don't pass `tagValues` keep the
+ * autonym-label tags.
+ *
  * The picker owns ZERO field semantics: selection state lives with the
  * host (`selected` key(s) in, events out), and the chip visuals come
  * from the host through the scoped `chip` slot — the same component
@@ -103,6 +114,18 @@ export const HkAffixPicker = defineComponent({
     /** Gate tag deletion behind a confirm message box (multi mode).
      *  Default true; pass false when the host runs its own guard. */
     confirmRemove: { type: Boolean, default: true },
+    /** Per-key value text replacing the tag list's primary label (multi
+     *  mode). Provided = value-driven tags: a key mapping to a non-empty
+     *  string renders that string; an empty/missing key renders
+     *  `tagUnsetText` italic (`data-unset`). Left undefined = the
+     *  autonym-label tags. Does not affect the pick rows. */
+    tagValues: {
+      type: Object as PropType<Record<string, string>>,
+      default: undefined,
+    },
+    /** Text shown (italic) for a tag whose `tagValues` entry is empty;
+     *  defaulted from the i18n bundle. */
+    tagUnsetText: { type: String, default: undefined },
     /** Override the default close-on-pick (single: true, multi: false).
      *  E.g. a multi picker that should close after each add passes
      *  true; a single picker that should stay open passes false. */
@@ -141,58 +164,17 @@ export const HkAffixPicker = defineComponent({
      *  are outside THIS popup, and the panel's outside-close must not
      *  tear the tag list down mid-decision. */
     const confirmHeld = ref(false);
-    /** The scrolling option list and its overlay-scrollbar host (see the
-     *  default slot — the host wraps ONLY the list viewport, not the
-     *  header/search band). */
-    const listRef = ref<HTMLElement | null>(null);
-    const scrollHostRef = ref<HTMLElement | null>(null);
-    /** Live overlay-scrollbar handle for the open popup; null when the
-     *  popup is closed (content not mounted). */
-    let scrollbar: OverlayScrollbarHandle | null = null;
-    /** The viewport element `scrollbar` is currently attached to, so a
-     *  remounted list (the empty-state swap) can be told apart from the
-     *  same in-flight list across content-size updates. */
-    let scrollbarViewport: HTMLElement | null = null;
 
-    function detachScrollbar() {
-      scrollbar?.detach();
-      scrollbar = null;
-      scrollbarViewport = null;
-    }
-
-    function attachScrollbar() {
-      detachScrollbar();
-      if (listRef.value && scrollHostRef.value) {
-        scrollbarViewport = listRef.value;
-        scrollbar = attachOverlayScrollbars(listRef.value, {
-          axis: "vertical",
-          host: scrollHostRef.value,
-        });
-      }
-    }
-
-    // A fresh open starts calm: empty filter.
+    // A fresh open starts calm: empty filter. (The popup mounts no
+    // scroll machinery of its own — the window surface owns the one
+    // scrollbar — so there is nothing to attach/detach on open/close.)
     watch(open, (v) => {
       if (!v) {
         query.value = "";
       }
-      if (v) {
-        // The list mounts on this very render — attach the overlay
-        // scrollbar once the DOM has landed. A same-tick open→close
-        // must not arm it on the leaving popup (the close branch
-        // already detached it).
-        void nextTick(() => {
-          if (!open.value) return;
-          attachScrollbar();
-        });
-      } else {
-        detachScrollbar();
-      }
       emit("update:open", v);
     });
 
-    onBeforeUnmount(detachScrollbar);
-
     const selectedKeys = computed<readonly string[]>(() =>
       Array.isArray(props.selected) ? props.selected : props.selected ? [props.selected] : [],
     );
@@ -232,29 +214,6 @@ export const HkAffixPicker = defineComponent({
       });
     });
 
-    // Content-size changes from the search filter change the thumb
-    // geometry without resizing the viewport — keep it in sync on the
-    // live scrollbar (no-op while the popup is closed). Post-flush so
-    // the DOM (esp. a remounted list after the empty-state swap) has
-    // landed and the template refs point at the live nodes before we
-    // decide whether to attach, re-attach or update.
-    watch(
-      [filteredRows, query],
-      () => {
-        if (!open.value) return;
-        if (!listRef.value) {
-          detachScrollbar();
-          return;
-        }
-        if (listRef.value !== scrollbarViewport) {
-          attachScrollbar();
-          return;
-        }
-        scrollbar?.update();
-      },
-      { flush: "post" },
-    );
-
     /** Exact label match suppresses the custom row while the user is
      *  simply re-typing an existing entry. */
     const exactMatch = computed(
@@ -351,6 +310,14 @@ export const HkAffixPicker = defineComponent({
         props.searchPlaceholder ?? t("hikari::affixPicker.search", "Search");
       const emptyText = props.emptyText ?? t("hikari::affixPicker.empty", "No matches");
       const removeLabel = t("hikari::affixPicker.remove", "Remove");
+      // Value-driven tags (tagValues provided): each tag's primary text
+      // is its mapped value, or the italic unset text when empty. The
+      // autonym stays the tag's identity in title/aria and the dialog.
+      const valueDriven = props.tagValues !== undefined;
+      const unsetText =
+        props.tagUnsetText ?? t("hikari::affixPicker.unset", "Not set");
+      const tagValue = (key: string): string =>
+        (props.tagValues?.[key] ?? "").trim();
       const placement = props.side === "suffix" ? "bottom-end" : "bottom-start";
       return (
         <>
@@ -420,6 +387,7 @@ export const HkAffixPicker = defineComponent({
                         class="hk-affix-tag-list"
                       >
                         {tags.map((tag) => {
+                          const value = tagValue(tag.key);
                           return (
                             <div
                               key={tag.key}
@@ -429,7 +397,9 @@ export const HkAffixPicker = defineComponent({
                               <button
                                 type="button"
                                 class="hk-affix-tag-body"
-                                title={`${tag.label}${tag.meta ? ` (${tag.meta})` : ""}`}
+                                title={`${tag.label}${tag.meta ? ` (${tag.meta})` : ""}${
+                                  valueDriven ? `: ${value || unsetText}` : ""
+                                }`}
                                 aria-label={`${t("hikari::affixPicker.switchTo", "Switch to")} ${tag.label}`}
                                 onClick={(e: MouseEvent) => {
                                   e.stopPropagation();
@@ -441,7 +411,12 @@ export const HkAffixPicker = defineComponent({
                                     {tag.flag}
                                   </span>
                                 )}
-                                <span class="hk-affix-tag-text">{tag.label}</span>
+                                <span
+                                  class="hk-affix-tag-text"
+                                  data-unset={valueDriven && !value ? "" : undefined}
+                                >
+                                  {valueDriven ? value || unsetText : tag.label}
+                                </span>
                                 {tag.meta && (
                                   <span class="hk-affix-tag-meta">{tag.meta}</span>
                                 )}
@@ -499,8 +474,12 @@ export const HkAffixPicker = defineComponent({
               ),
               default: () =>
                 rows.length > 0 || customVisible.value ? (
-                  <div class="hk-affix-scroll" ref={scrollHostRef}>
-                    <div class="hk-affix-list" ref={listRef}>
+                  /* Width container only — the window surface (HkSelectPanel
+                   * popout / sheet) owns THE single scrollbar and scrolls this
+                   * list with the rest of the popup content; no inner
+                   * max-height/overflow here, ever. */
+                  <div class="hk-affix-scroll">
+                    <div class="hk-affix-list">
                       {rows.map((option) => {
                       const active =
                         props.mode === "single"

package/src/components/HkErrorBoundary.tsx

@@ -30,8 +30,9 @@ function formatError(err: CapturedError): string {
  * Captures descendant errors via `onErrorCaptured` and stops propagation.
  * The built-in fallback is the same HkErrorLanding card the family's
  * full-page takeovers use (inline variant): tone icon, headline, the error
- * name as the code chip, the message as the description, the raw
- * name/message/stack in a collapsible JSON tree, plus retry / copy actions.
+ * name as the tone-matched HkBadge chip, the message as the description,
+ * the raw name/message/stack in the fixed-height JSON tree pane, plus
+ * retry / copy actions.
  */
 export default defineComponent({
   name: "HkErrorBoundary",