@kahitsan/ksui 0.37.0 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "ksui is a standalone set of SolidJS UI components for KahitSan/Hilinga and any SolidJS app. Published to the public npm registry and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with only solid-js externalized; it depends on nothing but solid-js + lucide-solid and injects its own CSS.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/base/AddAttachmentTile.tsx

@@ -3,6 +3,8 @@
 
 import { createSignal, onCleanup, onMount, Show } from "solid-js";
 import { Portal } from "solid-js/web";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 import Plus from "lucide-solid/icons/plus";
 import Camera from "lucide-solid/icons/camera";
 import FileIcon from "lucide-solid/icons/file";
@@ -14,6 +16,7 @@ interface Props {
 }
 
 export default function AddAttachmentTile(props: Props) {
+  const popoverMount = usePopoverMount();
   const [open, setOpen] = createSignal(false);
   const [pos, setPos] = createSignal({ top: 0, left: 0 });
   let btn: HTMLButtonElement | undefined;
@@ -60,9 +63,12 @@ export default function AddAttachmentTile(props: Props) {
         <span class="text-[10px] uppercase tracking-wider">{props.uploading ? "Uploading" : "Add"}</span>
       </button>
       <Show when={open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={menu}
+            ref={(el) => {
+              menu = el;
+              onCleanup(useTopLayer(el));
+            }}
             style={{ top: `${pos().top}px`, left: `${pos().left}px` }}
             class="fixed z-[60] min-w-[160px] rounded-lg border border-[var(--ks-border-strong,#3f3f46)] bg-[var(--ks-surface-raised,#1a1a1a)] shadow-2xl p-1 ks-hud-clip-top-left-bottom-right"
           >

package/src/components/base/BadgeSelect.tsx

@@ -1,5 +1,7 @@
 import { createEffect, createMemo, createSignal, For, onCleanup, Show, type JSX } from "solid-js";
 import { Portal } from "solid-js/web";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 
 export interface BadgeSelectOption {
   /** Stable identity of the option (what `value` matches and `onChange` emits). */
@@ -54,6 +56,7 @@ const DEFAULT_SEARCH_THRESHOLD = 5;
 // not a form-control picker. Kept separate so neither component grows a
 // trigger-shape/styling switch; do not merge them.
 export default function BadgeSelect(props: BadgeSelectProps): JSX.Element {
+  const popoverMount = usePopoverMount();
   const [open, setOpen] = createSignal(false);
   const [busy, setBusy] = createSignal(false);
   const [query, setQuery] = createSignal("");
@@ -172,9 +175,12 @@ export default function BadgeSelect(props: BadgeSelectProps): JSX.Element {
         {busy() ? "…" : currentLabel()}
       </button>
       <Show when={open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popupRef}
+            ref={(el) => {
+              popupRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             role="listbox"
             class="z-[100] rounded-md border border-[var(--ks-border-strong,#3f3f46)] bg-[color-mix(in_srgb,var(--ks-surface-raised,#1a1a1a)_95%,transparent)] backdrop-blur shadow-xl overflow-hidden flex flex-col"
             style={popupStyle()}

package/src/components/base/DatePicker.test.tsx

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { render, screen, fireEvent } from "@solidjs/testing-library";
 import { createSignal } from "solid-js";
-import DatePicker from "./DatePicker";
+import DatePicker, { type DateRangeValue } from "./DatePicker";
 
 // DatePicker is the shared calendar popover used by every plugin's date input
 // and by DataTable's date filter. The key behaviors: renders a trigger button
@@ -48,4 +48,61 @@ describe("DatePicker", () => {
     const trigger = screen.getByText("Pick date").closest("button")!;
     expect(trigger.disabled).toBe(true);
   });
+
+  // Regression: a completed selection must close the popover, or the
+  // top-layer-promoted panel keeps intercepting clicks meant for whatever's
+  // underneath (e.g. a modal's submit button) after the user is done with it.
+  it("closes the popover and refocuses the trigger after a day is clicked", async () => {
+    const onChange = vi.fn();
+    render(() => <DatePicker value="2026-06-15" onChange={onChange} />);
+    const trigger = screen.getByText("Jun 15").closest("button")!;
+    await fireEvent.click(trigger);
+    expect(screen.getByTestId("datepicker-popover")).toBeTruthy();
+
+    const day20 = screen.getByText("20", { exact: true });
+    await fireEvent.click(day20);
+
+    expect(onChange).toHaveBeenCalledWith("2026-06-20");
+    expect(screen.queryByTestId("datepicker-popover")).toBeNull();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it("closes the popover after a quick-pick button is clicked", async () => {
+    const onChange = vi.fn();
+    render(() => <DatePicker value={null} onChange={onChange} />);
+    await fireEvent.click(screen.getByText("Pick date"));
+    expect(screen.getByTestId("datepicker-popover")).toBeTruthy();
+
+    await fireEvent.click(screen.getByText("Yesterday"));
+
+    expect(onChange).toHaveBeenCalledOnce();
+    expect(screen.queryByTestId("datepicker-popover")).toBeNull();
+  });
+
+  it("keeps the popover open after the first pick in active range mode", async () => {
+    const [range, setRange] = createSignal<DateRangeValue>({ start: null, end: null });
+    render(() => <DatePicker range value={range()} onChange={setRange} />);
+    await fireEvent.click(screen.getByText("Pick date"));
+    // Range mode needs two clicks (start, then end); turning the toggle on
+    // is what puts the calendar into that two-click mode.
+    await fireEvent.click(screen.getByTestId("datepicker-end-date-toggle"));
+
+    const day20 = screen.getByText("20", { exact: true });
+    await fireEvent.click(day20);
+
+    // Only one bound is set so far — the popover must stay open for the second pick.
+    expect(screen.getByTestId("datepicker-popover")).toBeTruthy();
+  });
+
+  it("closes the popover after a range quick-pick button (atomic, both bounds set)", async () => {
+    const [range, setRange] = createSignal<DateRangeValue>({ start: null, end: null });
+    render(() => <DatePicker range value={range()} onChange={setRange} />);
+    await fireEvent.click(screen.getByText("Pick date"));
+    expect(screen.getByTestId("datepicker-popover")).toBeTruthy();
+
+    await fireEvent.click(screen.getByText("Yesterday"));
+
+    expect(range().start).toBe(range().end);
+    expect(screen.queryByTestId("datepicker-popover")).toBeNull();
+  });
 });

package/src/components/base/DatePicker.tsx

@@ -43,6 +43,8 @@ import {
   type ParsedDate,
 } from "../../utils/parse-date";
 import { injectCSS } from "../../utils/inject-css";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 
 // ---------------------------------------------------------------------------
 // Injected CSS
@@ -249,6 +251,7 @@ const QUICK_OPTIONS_RANGE: RangeQuickOption[] = [
 
 export default function DatePicker(props: DatePickerProps) {
   ensureDatePickerStyle();
+  const popoverMount = usePopoverMount();
 
   const isRange = (): boolean => (props as DatePickerProps).range === true;
 
@@ -378,6 +381,9 @@ export default function DatePicker(props: DatePickerProps) {
     emitSingle(dateStr);
     setInputValue(formatDateEditable(dateStr));
     setPreview(null);
+    // withTime needs the popover to stay open so the user can still edit the
+    // time field below; otherwise the day pick IS the whole selection.
+    if (!props.withTime) closePicker();
   }
 
   function selectDateRange(dateStr: string) {
@@ -416,6 +422,10 @@ export default function DatePicker(props: DatePickerProps) {
     setInputValue(nextStart ? formatDateEditable(nextStart) : "");
     setEndInputValue(nextEnd ? formatDateEditable(nextEnd) : "");
     setPreview(null);
+    // Deliberately does NOT close: range mode picks two dates across two
+    // clicks (start, then end), so the popover must stay open between them.
+    // Closing here would strand the user after the first click with no way
+    // to pick the second bound.
   }
 
   /**
@@ -428,6 +438,10 @@ export default function DatePicker(props: DatePickerProps) {
     emitRange({ start: dateStr, end: dateStr });
     setInputValue(formatDateEditable(dateStr));
     setPreview(null);
+    // The End-date toggle is off, so this click IS a completed single-day
+    // pick (no withTime row exists in range mode — see the `!isRange()` guard
+    // on the time section below), unlike selectDateSingle's withTime check.
+    closePicker();
   }
 
   function selectDate(dateStr: string) {
@@ -444,6 +458,9 @@ export default function DatePicker(props: DatePickerProps) {
     setInputValue(range.start ? formatDateEditable(range.start) : "");
     setEndInputValue(range.end ? formatDateEditable(range.end) : "");
     setPreview(null);
+    // A quick-range preset sets both bounds atomically in one click, unlike a
+    // day-cell pick in selectDateRange — there's no second date left to pick.
+    closePicker();
   }
 
   function clear(e?: MouseEvent) {
@@ -516,6 +533,18 @@ export default function DatePicker(props: DatePickerProps) {
     });
   }
 
+  /**
+   * Closes the popover after a completed selection and returns focus to the
+   * trigger. Distinct from the outside-click/Escape close paths (which stay
+   * untouched): those close in response to the user looking elsewhere, so
+   * stealing focus back to the trigger there would fight whatever they just
+   * clicked (e.g. a modal's submit button) — the exact bug this fixes.
+   */
+  function closePicker() {
+    setOpen(false);
+    triggerRef?.focus();
+  }
+
   // ── Text input handling ────────────────────────────────────────────────────
 
   function handleInput(e: InputEvent, field: "start" | "end") {
@@ -712,12 +741,16 @@ export default function DatePicker(props: DatePickerProps) {
         </button>
       </Show>
 
-      {/* Popover — portaled to document.body so ancestor clip-path / overflow
+      {/* Popover — portaled to document.body (or the ancestor dialog's
+          element, see modal-layer.ts) so ancestor clip-path / overflow
           (sheet modals use clip-path corners) doesn't clip the calendar. */}
       <Show when={open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popoverPanelRef}
+            ref={(el) => {
+              popoverPanelRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             data-testid="datepicker-popover"
             class="ksui-datepicker-popover"
             style={{

package/src/components/base/Modal.tsx

@@ -18,6 +18,7 @@
 import { JSX, onCleanup, onMount, splitProps } from "solid-js";
 import { autoFocusOnMount, lockPullToRefresh, unlockPullToRefresh, useFocusTrap } from "../../utils/dom";
 import { injectCSS } from "../../utils/inject-css";
+import { ModalLayerProvider } from "../../utils/modal-layer";
 
 export type ModalSize = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "5xl" | "7xl";
 export type ModalTone = "default" | "danger";
@@ -145,7 +146,10 @@ function DialogModal(local: LocalProps): JSX.Element {
         class={`ksui-modal-card${local.tone === "danger" ? " danger" : ""}`}
         style={{ "max-width": SIZE_MAX_WIDTH[local.size ?? "lg"] }}
       >
-        {local.children}
+        {/* Value is a closure over dialogEl, not its value at Provider-creation
+            time — dialogEl is still undefined here (ref hasn't fired yet), but
+            every popover reads this accessor lazily, well after mount. */}
+        <ModalLayerProvider value={() => dialogEl ?? null}>{local.children}</ModalLayerProvider>
       </div>
     </dialog>
   );
@@ -170,6 +174,10 @@ function SheetModal(local: LocalProps, size?: ModalSize): JSX.Element {
     local.onClose();
   };
 
+  // No ModalLayerProvider here: a sheet is a plain <div>, never showModal()'d,
+  // so it introduces no inertness barrier of its own — children keep whatever
+  // ModalLayerContext value is already ambient (an outer DialogModal's
+  // dialogEl if nested inside one, otherwise the default null/document.body).
   return (
     <div class="ksui-modal-sheet-overlay">
       {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions */}

package/src/components/composite/ComboBox.tsx

@@ -20,7 +20,9 @@
 //     and `lockedIds` anchors specific chips.
 
 import { Portal } from "solid-js/web";
-import { createEffect, createSignal, For, onMount, Show, type JSX } from "solid-js";
+import { createEffect, createSignal, For, onCleanup, onMount, Show, type JSX } from "solid-js";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 import { highlightMatch } from "../../utils/highlight";
 import UserPlus from "lucide-solid/icons/user-plus";
 import Search from "lucide-solid/icons/search";
@@ -108,6 +110,7 @@ export default function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
 // Single-select — button trigger + popup with its own search input.
 // ---------------------------------------------------------------------------
 function SingleComboBox<T>(props: ComboBoxSingleProps<T>): JSX.Element {
+  const popoverMount = usePopoverMount();
   let triggerRef: HTMLButtonElement | undefined;
   let popupRef: HTMLDivElement | undefined;
   let inputRef: HTMLInputElement | undefined;
@@ -201,9 +204,12 @@ function SingleComboBox<T>(props: ComboBoxSingleProps<T>): JSX.Element {
       </button>
 
       <Show when={eng.open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popupRef}
+            ref={(el) => {
+              popupRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             data-testid={tid("popup")}
             class="z-[10000] rounded-md border border-[var(--ks-border-strong,#3f3f46)] bg-[color-mix(in_srgb,var(--ks-overlay-surface,#18181b)_95%,transparent)] backdrop-blur shadow-xl overflow-hidden flex flex-col"
             style={eng.popupStyle()}
@@ -316,6 +322,7 @@ function SingleComboBox<T>(props: ComboBoxSingleProps<T>): JSX.Element {
 type DisplayOption<T> = { create: true; name: string } | { create: false; item: T };
 
 function MultiComboBox<T>(props: ComboBoxMultiProps<T>): JSX.Element {
+  const popoverMount = usePopoverMount();
   let wrapperRef: HTMLDivElement | undefined;
   let popupRef: HTMLDivElement | undefined;
   let inputRef: HTMLInputElement | undefined;
@@ -545,9 +552,12 @@ function MultiComboBox<T>(props: ComboBoxMultiProps<T>): JSX.Element {
       </div>
 
       <Show when={eng.open() && !props.disabled}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popupRef}
+            ref={(el) => {
+              popupRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             data-testid={tid("popup")}
             role="listbox"
             aria-label={`${props.noun} search results`}

package/src/components/composite/MentionTextarea.tsx

@@ -7,6 +7,8 @@
 // still works as a plain notes editor.
 
 import { Portal } from "solid-js/web";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 import { createEffect, createSignal, createUniqueId, For, onCleanup, onMount, Show, type JSX } from "solid-js";
 import UserRound from "lucide-solid/icons/user-round";
 import Loader2 from "lucide-solid/icons/loader-2";
@@ -122,6 +124,7 @@ function findTrigger(
 }
 
 export default function MentionTextarea(props: MentionTextareaProps): JSX.Element {
+  const popoverMount = usePopoverMount();
   const listboxId = createUniqueId();
   const optionId = (clientId: number) => `${listboxId}-option-${clientId}`;
   const [open, setOpen] = createSignal(false);
@@ -426,9 +429,12 @@ export default function MentionTextarea(props: MentionTextareaProps): JSX.Elemen
       </div>
 
       <Show when={open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popupRef}
+            ref={(el) => {
+              popupRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             data-testid="mention-popup"
             class="z-[120] rounded-md border border-[var(--ks-border-strong,#3f3f46)] bg-[color-mix(in_srgb,var(--ks-overlay-surface,#18181b)_95%,transparent)] backdrop-blur shadow-xl overflow-hidden flex flex-col"
             style={popupStyle()}

package/src/components/composite/PaymentAccountPicker.tsx

@@ -1,4 +1,6 @@
 import { Portal } from "solid-js/web";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 import {
   createEffect,
   createMemo,
@@ -65,6 +67,7 @@ function groupAndSort(accounts: PaymentAccountOption[]): Array<[string, PaymentA
 }
 
 export default function PaymentAccountPicker(props: PaymentAccountPickerProps): JSX.Element {
+  const popoverMount = usePopoverMount();
   const [open, setOpen] = createSignal(false);
   const [accounts, setAccounts] = createSignal<PaymentAccountOption[]>([]);
   const [loading, setLoading] = createSignal(true);
@@ -238,9 +241,12 @@ export default function PaymentAccountPicker(props: PaymentAccountPickerProps):
       </button>
 
       <Show when={open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popupRef}
+            ref={(el) => {
+              popupRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             data-testid="payment-account-picker-popup"
             class="z-[100] rounded-md border border-[var(--ks-border-strong,#3f3f46)] bg-[color-mix(in_srgb,var(--ks-surface-raised,#1a1a1a)_95%,transparent)] backdrop-blur shadow-xl overflow-hidden flex flex-col"
             style={popupStyle()}

package/src/components/composite/SearchableSelect.tsx

@@ -1,5 +1,7 @@
 import { createEffect, createMemo, createSignal, For, onCleanup, Show, type JSX } from "solid-js";
 import { Portal } from "solid-js/web";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 import ChevronsUpDown from "lucide-solid/icons/chevrons-up-down";
 import X from "lucide-solid/icons/x";
 
@@ -38,6 +40,7 @@ const POPUP_FLIP_THRESHOLD = 200;
 // with `overflow: hidden` (e.g. the rounded table cards) and flip upward when
 // there's not enough room below the trigger.
 export default function SearchableSelect(props: SearchableSelectProps): JSX.Element {
+  const popoverMount = usePopoverMount();
   const [open, setOpen] = createSignal(false);
   const [query, setQuery] = createSignal("");
   const [busy, setBusy] = createSignal(false);
@@ -166,9 +169,12 @@ export default function SearchableSelect(props: SearchableSelectProps): JSX.Elem
         <ChevronsUpDown size={12} class="text-[var(--ks-fg-subtle,#71717a)] shrink-0" />
       </button>
       <Show when={open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popupRef}
+            ref={(el) => {
+              popupRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             class="z-[10000] rounded-md border border-[var(--ks-input-border,#3f3f46)] bg-[color-mix(in_srgb,var(--ks-overlay-surface,#18181b)_95%,transparent)] backdrop-blur shadow-xl overflow-hidden flex flex-col"
             style={popupStyle()}
           >

package/src/components/composite/VoucherPicker.tsx

@@ -8,6 +8,8 @@
 // vouchers through a peer proxy route instead (same response shape required).
 
 import { Portal } from "solid-js/web";
+import { useTopLayer } from "../../utils/top-layer";
+import { usePopoverMount } from "../../utils/modal-layer";
 import { createEffect, createMemo, createSignal, For, onCleanup, Show, type JSX } from "solid-js";
 import Ticket from "lucide-solid/icons/ticket";
 import X from "lucide-solid/icons/x";
@@ -98,6 +100,7 @@ function formatVoucherDescription(v: VoucherOption): string {
 }
 
 export default function VoucherPicker(props: VoucherPickerProps): JSX.Element {
+  const popoverMount = usePopoverMount();
   const [open, setOpen] = createSignal(false);
   const [vouchers, setVouchers] = createSignal<VoucherOption[]>([]);
   const [loading, setLoading] = createSignal(false);
@@ -264,9 +267,12 @@ export default function VoucherPicker(props: VoucherPickerProps): JSX.Element {
       </button>
 
       <Show when={open()}>
-        <Portal>
+        <Portal mount={popoverMount()}>
           <div
-            ref={popupRef}
+            ref={(el) => {
+              popupRef = el;
+              onCleanup(useTopLayer(el));
+            }}
             data-testid="voucher-picker-popup"
             class="z-[100] rounded-md border border-[var(--ks-input-border,#3f3f46)] bg-[color-mix(in_srgb,var(--ks-overlay-surface,#18181b)_95%,transparent)] backdrop-blur shadow-xl overflow-hidden flex flex-col"
             style={popupStyle()}

package/src/utils/modal-layer.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext, type Accessor } from "solid-js";
+
+// A Portal-based popover (DatePicker, ComboBox, ...) must mount as a DOM
+// DESCENDANT of an ancestor dialog-variant Modal's <dialog> element, not
+// document.body. dialogEl.showModal() marks everything OUTSIDE the dialog's
+// flat-tree subtree inert, and inertness is computed on the flat tree —
+// independent of the Popover API's top-layer PAINT order (useTopLayer only
+// fixes painting). A popover portaled straight to document.body from inside
+// an open <dialog> paints above it but is excluded from hit-testing, so real
+// clicks never reach it even though it's visibly on top.
+//
+// Default is `null`: no ancestor dialog (standalone usage), or the sheet
+// variant (a plain <div>, no showModal(), so no inertness barrier exists) —
+// both mean "mount to document.body", today's behavior.
+const ModalLayerContext = createContext<Accessor<HTMLElement | null>>(() => null);
+
+export const ModalLayerProvider = ModalLayerContext.Provider;
+
+/**
+ * Mount target for a Portal-based popover: the nearest ancestor dialog's
+ * element when rendered inside a dialog-variant Modal, else document.body.
+ * Called once per popover-open (the Portal itself only reads `mount` at
+ * creation), so a plain `Node` accessor — not a reactive signal — is enough.
+ */
+export function usePopoverMount(): () => Node {
+  const layer = useContext(ModalLayerContext);
+  return () => layer() ?? document.body;
+}

package/src/utils/top-layer.ts

@@ -0,0 +1,66 @@
+import { onMount } from "solid-js";
+import { injectCSS } from "./inject-css";
+
+const STYLE_ID = "ksui-toplayer-style";
+// UA is the lowest cascade priority, so any author rule (background, border,
+// padding, width, sizing, ...) already beats [popover]'s UA defaults without
+// help — resetting those was the bug (this stylesheet injects AFTER each
+// component's own CSS, so a same-specificity reset would win by source order
+// and strip the component's real chrome). Only inset and margin are genuine
+// POSITIONING conflicts: UA's inset:0 leaves right/bottom pinned to 0 even
+// after a component's inline `top`/`left` override the top/left portion, and
+// UA's margin:auto re-centers inside that box — both fight the fixed
+// coordinates each popup computes itself.
+const STYLE_CSS = `
+[data-ksui-toplayer]{inset:auto;margin:0;}
+`;
+
+/**
+ * Promotes `el` into the browser's top layer via the Popover API so it
+ * paints above a native <dialog> (Modal's default variant) regardless of
+ * z-index — an ordinary element can never out-paint a top-layer one.
+ * `"manual"` disables the API's own light-dismiss/Escape handling; every
+ * ksui popup keeps its own mousedown/Escape listeners unchanged.
+ *
+ * Call from the portaled panel's ref, mirroring useFocusTrap's shape:
+ *   ref={(el) => { popupRef = el; onCleanup(useTopLayer(el)); }}
+ *
+ * showPopover() is deferred to onMount, not called inline here: this
+ * function runs synchronously inside <Portal>'s ref callback, which fires
+ * while the node is still detached (Portal appends its container to
+ * document.body *after* building the subtree) — el.isConnected is false
+ * and el.ownerDocument !== document at that point, so an inline call
+ * always throws InvalidStateError. onMount queues onto Solid's render-effect
+ * list, which only flushes once the whole synchronous render pass —
+ * including Portal's appendChild — has finished, so by the time it runs
+ * the node is guaranteed connected. (Same fix shape as Modal's DialogModal,
+ * which calls showModal() in onMount rather than in dialogEl's ref.)
+ */
+export function useTopLayer(el: HTMLElement | undefined): () => void {
+  if (!el) return () => {};
+  injectCSS(STYLE_ID, STYLE_CSS);
+  el.setAttribute("popover", "manual");
+  el.setAttribute("data-ksui-toplayer", "");
+  onMount(() => {
+    // No Popover API (e.g. jsdom in unit tests) — nothing to promote, not an error.
+    if (typeof el.showPopover !== "function") return;
+    try {
+      el.showPopover();
+    } catch (err) {
+      // showPopover() throws if already open (rapid re-open); that's the only
+      // benign case left once we're guaranteed connected, and it's detectable
+      // because the element really is :popover-open despite the throw. Any
+      // other failure is real and must surface, not vanish into a no-op.
+      if (!el.matches(":popover-open")) {
+        console.error("[ksui] useTopLayer: showPopover() failed to promote element", err);
+      }
+    }
+  });
+  return () => {
+    try {
+      el.hidePopover();
+    } catch {
+      // already hidden, disconnected first, or API unavailable — harmless.
+    }
+  };
+}