@kitn.ai/ui 0.17.0 → 0.18.0

package/src/ui/dropdown.tsx

@@ -1,8 +1,9 @@
 import {
-  createContext, useContext, createSignal, createUniqueId, Show,
+  createContext, useContext, createSignal, createUniqueId, Show, onCleanup, splitProps,
   type JSX, type Accessor,
 } from 'solid-js';
 import { Portal } from 'solid-js/web';
+import { ChevronRight, Check } from 'lucide-solid';
 import { cn } from '../utils/cn';
 import { useChatConfig } from '../primitives/chat-config';
 import { createPresence, usePosition, useDismiss, As, type AsTag } from './overlay';
@@ -17,6 +18,11 @@ interface DropdownCtx {
   trigger: Accessor<HTMLElement | undefined>;
   menu: Accessor<HTMLElement | undefined>;
   openedViaKeyboard: Accessor<boolean>;
+  /** Register a portaled submenu surface so outside-click dismissal treats it as
+   *  "inside" the menu tree (sub content lives in a sibling portal, not the menu DOM). */
+  registerSubMenu: (el: HTMLElement) => () => void;
+  /** Currently-mounted submenu surfaces, for the dismiss "inside" test. */
+  subMenus: Accessor<HTMLElement[]>;
 }
 const Ctx = createContext<DropdownCtx>();
 const useDropdown = () => {
@@ -25,12 +31,37 @@ const useDropdown = () => {
   return c;
 };
 
-export function Dropdown(props: { children: JSX.Element }) {
-  const [open, setOpenSig] = createSignal(false);
+// The roving-focus set: real menuitems AND checkbox/radio items, minus disabled.
+// A DropdownSubTrigger is a menuitem too, so it participates. Labels/separators
+// are intentionally excluded. Submenu content is portaled to a SIBLING node, so
+// a parent's querySelectorAll scoped to its own menu never reaches sub items.
+const ITEM_SELECTOR = '[role="menuitem"]:not([aria-disabled="true"]), [role="menuitemcheckbox"]:not([aria-disabled="true"]), [role="menuitemradio"]:not([aria-disabled="true"])';
+
+/** Imperative open controller, handed to a parent (e.g. the kai-menu facade) via
+ *  `controllerRef` so it can drive/observe the Dropdown's open state. */
+export interface DropdownController { open: Accessor<boolean>; setOpen: (v: boolean) => void; }
+
+export function Dropdown(props: {
+  children: JSX.Element;
+  /** Initial open state (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** When true, the trigger never opens the menu. */
+  disabled?: boolean;
+  /** Receive the open controller (open accessor + setOpen) once mounted. */
+  controllerRef?: (api: DropdownController) => void;
+}) {
+  const [open, setOpenSig] = createSignal(props.defaultOpen ?? false);
   const [viaKb, setViaKb] = createSignal(false);
   const [trigger, setTrigger] = createSignal<HTMLElement>();
   const [menu, setMenu] = createSignal<HTMLElement>();
+  const [subMenus, setSubMenus] = createSignal<HTMLElement[]>([]);
+  const registerSubMenu = (el: HTMLElement) => {
+    setSubMenus((prev) => [...prev, el]);
+    return () => setSubMenus((prev) => prev.filter((m) => m !== el));
+  };
   const setOpen = (v: boolean, opts?: { viaKeyboard?: boolean; returnFocus?: boolean }) => {
+    // Gate opening while disabled; closing always works.
+    if (v && props.disabled) return;
     setViaKb(!!opts?.viaKeyboard);
     setOpenSig(v);
     if (v) {
@@ -38,9 +69,8 @@ export function Dropdown(props: { children: JSX.Element }) {
       // attempt focus now and re-assert in the menu ref's microtask so it lands
       // once the node exists. Skip disabled items (roving-focus contract).
       if (opts?.viaKeyboard) {
-        const sel = '[role="menuitem"]:not([aria-disabled="true"])';
-        queueMicrotask(() => menu()?.querySelector<HTMLElement>(sel)?.focus());
-        menu()?.querySelector<HTMLElement>(sel)?.focus();
+        queueMicrotask(() => menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
+        menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus();
       }
     } else if (opts?.returnFocus !== false) {
       // Closing via keyboard/select: return focus to the trigger. The menu
@@ -51,10 +81,14 @@ export function Dropdown(props: { children: JSX.Element }) {
       queueMicrotask(() => el?.focus());
     }
   };
+  // Hand the open controller up to a facade (e.g. kai-menu) so it can drive +
+  // observe open state via wireDisclosure. Mirrors HoverCardRoot.controllerRef.
+  props.controllerRef?.({ open, setOpen: (v: boolean) => setOpen(v) });
   return (
     <Ctx.Provider value={{
       open, setOpen, triggerId: createUniqueId(), menuId: createUniqueId(),
       setTrigger, setMenu, trigger, menu, openedViaKeyboard: viaKb,
+      registerSubMenu, subMenus,
     }}>
       {props.children}
     </Ctx.Provider>
@@ -63,6 +97,10 @@ export function Dropdown(props: { children: JSX.Element }) {
 
 export function DropdownTrigger(props: { as?: AsTag; children?: JSX.Element; class?: string; [k: string]: any }) {
   const ctx = useDropdown();
+  // Forward extra attributes (e.g. aria-label for an icon-only trigger). The
+  // controlled wiring below (id/aria-*/onClick/onKeyDown/class/type) is applied
+  // AFTER the spread so it always wins over a caller-supplied duplicate.
+  const [, rest] = splitProps(props, ['as', 'children', 'class']);
   const onKeyDown = (e: KeyboardEvent) => {
     if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' || e.key === ' ') {
       e.preventDefault();
@@ -72,6 +110,7 @@ export function DropdownTrigger(props: { as?: AsTag; children?: JSX.Element; cla
   return (
     <As
       as={props.as ?? 'button'}
+      {...rest}
       ref={ctx.setTrigger}
       id={ctx.triggerId}
       aria-haspopup="menu"
@@ -91,14 +130,22 @@ export function DropdownContent(props: { children: JSX.Element; class?: string }
   const ctx = useDropdown();
   const config = useChatConfig();
   const presence = createPresence(ctx.open);
-  const position = usePosition(ctx.trigger, ctx.menu, { placement: 'bottom-start', gutter: 6 });
+  const position = usePosition(ctx.trigger, ctx.menu, {
+    placement: 'bottom-start',
+    gutter: 6,
+    // Trigger removed from the DOM -> close (no focus return; it's gone) so the
+    // menu portal doesn't orphan.
+    onDisconnect: () => ctx.setOpen(false, { returnFocus: false }),
+  });
   useDismiss({
     enabled: ctx.open,
     onDismiss: (reason) => ctx.setOpen(false, { returnFocus: reason === 'escape' }),
-    refs: () => [ctx.trigger(), ctx.menu()],
+    // Open submenus portal to a sibling node, so include them as "inside" — a
+    // click on a sub item must not be treated as an outside dismiss.
+    refs: () => [ctx.trigger(), ctx.menu(), ...ctx.subMenus()],
   });
 
-  const items = () => Array.from(ctx.menu()?.querySelectorAll<HTMLElement>('[role="menuitem"]:not([aria-disabled="true"])') ?? []);
+  const items = () => Array.from(ctx.menu()?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []);
   const focusIndex = (i: number) => {
     const list = items();
     if (!list.length) return;
@@ -145,7 +192,7 @@ export function DropdownContent(props: { children: JSX.Element; class?: string }
             // synchronously; this ref-time microtask re-asserts focus once the
             // menu node exists. Skip disabled items.
             if (ctx.openedViaKeyboard()) {
-              queueMicrotask(() => el.querySelector<HTMLElement>('[role="menuitem"]:not([aria-disabled="true"])')?.focus());
+              queueMicrotask(() => el.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
             }
           }}
           id={ctx.menuId}
@@ -174,23 +221,338 @@ export function DropdownContent(props: { children: JSX.Element; class?: string }
   );
 }
 
-export function DropdownItem(props: { children: JSX.Element; class?: string; onSelect?: () => void }) {
+export function DropdownItem(props: { children: JSX.Element; class?: string; onSelect?: () => void; disabled?: boolean }) {
   const ctx = useDropdown();
-  const activate = () => { props.onSelect?.(); ctx.setOpen(false); };
+  const activate = () => {
+    if (props.disabled) return;
+    props.onSelect?.();
+    ctx.setOpen(false);
+  };
   return (
     <div
       role="menuitem"
       tabindex={-1}
+      aria-disabled={props.disabled ? 'true' : undefined}
       onClick={activate}
       onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); activate(); } }}
-      onPointerMove={(e) => (e.currentTarget as HTMLElement).focus()}
+      onPointerMove={(e) => { if (!props.disabled) (e.currentTarget as HTMLElement).focus(); }}
+      class={cn(
+        'flex cursor-pointer items-center rounded-md px-2 py-1.5 text-sm outline-none transition-colors',
+        'hover:bg-muted focus:bg-muted',
+        props.disabled && 'opacity-50 pointer-events-none',
+        props.class,
+      )}
+    >
+      {props.children}
+    </div>
+  );
+}
+
+/**
+ * A thin, non-interactive divider between groups of items.
+ * a11y: `role="separator"` — exposed to AT as a group boundary; not in the
+ * roving-focus tab order (the `[role="menuitem"]` query skips it).
+ */
+export function DropdownSeparator(props: { class?: string }) {
+  return <div role="separator" class={cn('-mx-1 my-1 h-px bg-border', props.class)} />;
+}
+
+/**
+ * A non-interactive section header.
+ * a11y: a plain muted label — NOT a menuitem and NOT focusable, so roving focus
+ * skips it; it labels the items that follow visually only (`select-none`).
+ */
+export function DropdownLabel(props: { children: JSX.Element; class?: string }) {
+  return (
+    <div class={cn('select-none px-2 py-1.5 text-xs font-medium text-muted-foreground', props.class)}>
+      {props.children}
+    </div>
+  );
+}
+
+/**
+ * A togglable menu item.
+ * a11y: `role="menuitemcheckbox"` + `aria-checked`. Activating fires `onSelect`
+ * but KEEPS THE MENU OPEN (the consumer flips `checked`). The Check sits at the
+ * TRAILING edge (toggle-style) so the item's leading content — an icon when
+ * present — aligns with the plain items above it instead of being pushed in by a
+ * reserved leading check column.
+ */
+export function DropdownCheckboxItem(props: { children: JSX.Element; class?: string; checked?: boolean; onSelect?: () => void; disabled?: boolean }) {
+  const activate = () => {
+    if (props.disabled) return;
+    props.onSelect?.(); /* stay open — consumer owns `checked` */
+  };
+  return (
+    <div
+      role="menuitemcheckbox"
+      aria-checked={props.checked ? 'true' : 'false'}
+      tabindex={-1}
+      aria-disabled={props.disabled ? 'true' : undefined}
+      onClick={activate}
+      onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); activate(); } }}
+      onPointerMove={(e) => { if (!props.disabled) (e.currentTarget as HTMLElement).focus(); }}
+      class={cn(
+        'flex cursor-pointer items-center rounded-md px-2 py-1.5 text-sm outline-none transition-colors',
+        'hover:bg-muted focus:bg-muted',
+        props.disabled && 'opacity-50 pointer-events-none',
+        props.class,
+      )}
+    >
+      {props.children}
+      <span class="ml-auto flex size-4 shrink-0 items-center justify-center text-muted-foreground">
+        <Show when={props.checked}><Check class="size-4" aria-hidden="true" /></Show>
+      </span>
+    </div>
+  );
+}
+
+/**
+ * A single-select (radio) menu item.
+ * a11y: `role="menuitemradio"` + `aria-checked`. Behaves like the checkbox item —
+ * activating fires `onSelect` but KEEPS THE MENU OPEN (the consumer moves the
+ * selection within the group). The Check sits at the TRAILING edge so leading
+ * content aligns with plain items. Group membership is the consumer's concern;
+ * this primitive just renders the selected state and reports the click.
+ */
+export function DropdownRadioItem(props: { children: JSX.Element; class?: string; checked?: boolean; onSelect?: () => void; disabled?: boolean }) {
+  const activate = () => {
+    if (props.disabled) return;
+    props.onSelect?.(); /* stay open — consumer owns the group selection */
+  };
+  return (
+    <div
+      role="menuitemradio"
+      aria-checked={props.checked ? 'true' : 'false'}
+      tabindex={-1}
+      aria-disabled={props.disabled ? 'true' : undefined}
+      onClick={activate}
+      onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); activate(); } }}
+      onPointerMove={(e) => { if (!props.disabled) (e.currentTarget as HTMLElement).focus(); }}
       class={cn(
         'flex cursor-pointer items-center rounded-md px-2 py-1.5 text-sm outline-none transition-colors',
         'hover:bg-muted focus:bg-muted',
+        props.disabled && 'opacity-50 pointer-events-none',
         props.class,
       )}
     >
       {props.children}
+      <span class="ml-auto flex size-4 shrink-0 items-center justify-center text-muted-foreground">
+        <Show when={props.checked}><Check class="size-4" aria-hidden="true" /></Show>
+      </span>
     </div>
   );
 }
+
+// ── Submenus ────────────────────────────────────────────────────────────────
+
+interface DropdownSubCtx {
+  open: Accessor<boolean>;
+  setOpen: (v: boolean, opts?: { viaKeyboard?: boolean; returnFocus?: boolean }) => void;
+  triggerId: string;
+  menuId: string;
+  setTrigger: (el: HTMLElement) => void;
+  setMenu: (el: HTMLElement) => void;
+  trigger: Accessor<HTMLElement | undefined>;
+  menu: Accessor<HTMLElement | undefined>;
+  openedViaKeyboard: Accessor<boolean>;
+  /** clear any pending close timer (used when the pointer re-enters trigger or content) */
+  cancelClose: () => void;
+  /** schedule a deferred close, tolerating a pointer crossing the gap to the submenu */
+  scheduleClose: () => void;
+}
+const SubCtx = createContext<DropdownSubCtx>();
+const useDropdownSub = () => {
+  const c = useContext(SubCtx);
+  if (!c) throw new Error('DropdownSub parts must be used within <DropdownSub>');
+  return c;
+};
+
+/**
+ * A nested menu group. Mirrors the `Dropdown` context shape with its own open
+ * signal + trigger/content refs, plus a small close-delay so a pointer can cross
+ * the gap from the trigger to the submenu without it snapping shut.
+ *
+ * The submenu is tied to its PARENT open state: when the parent menu closes
+ * (Escape/outside-click/select), `useDismiss` on the parent unmounts the whole
+ * content tree, which tears this provider down and drops the sub with it.
+ */
+export function DropdownSub(props: { children: JSX.Element }) {
+  const [open, setOpenSig] = createSignal(false);
+  const [viaKb, setViaKb] = createSignal(false);
+  const [trigger, setTrigger] = createSignal<HTMLElement>();
+  const [menu, setMenu] = createSignal<HTMLElement>();
+  let closeTimer: ReturnType<typeof setTimeout> | undefined;
+  const cancelClose = () => { if (closeTimer) { clearTimeout(closeTimer); closeTimer = undefined; } };
+  const setOpen = (v: boolean, opts?: { viaKeyboard?: boolean; returnFocus?: boolean }) => {
+    cancelClose();
+    setViaKb(!!opts?.viaKeyboard);
+    setOpenSig(v);
+    if (v) {
+      if (opts?.viaKeyboard) {
+        queueMicrotask(() => menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
+        menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus();
+      }
+    } else if (opts?.returnFocus !== false) {
+      const el = trigger();
+      el?.focus();
+      queueMicrotask(() => el?.focus());
+    }
+  };
+  const scheduleClose = () => {
+    cancelClose();
+    closeTimer = setTimeout(() => setOpen(false), 120);
+  };
+  onCleanup(cancelClose);
+  return (
+    <SubCtx.Provider value={{
+      open, setOpen, triggerId: createUniqueId(), menuId: createUniqueId(),
+      setTrigger, setMenu, trigger, menu, openedViaKeyboard: viaKb,
+      cancelClose, scheduleClose,
+    }}>
+      {props.children}
+    </SubCtx.Provider>
+  );
+}
+
+/**
+ * The item that opens a submenu.
+ * a11y: `role="menuitem"` + `aria-haspopup="menu"` + `aria-expanded`, trailing
+ * ChevronRight. Opens on pointerenter, click, ArrowRight, and Enter/Space;
+ * keyboard-open also moves focus into the sub's first item. ArrowRight/Enter are
+ * swallowed so the parent menu doesn't also act on them.
+ */
+export function DropdownSubTrigger(props: { children: JSX.Element; class?: string }) {
+  const sub = useDropdownSub();
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'ArrowRight' || e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      e.stopPropagation();
+      sub.setOpen(true, { viaKeyboard: true });
+    }
+  };
+  return (
+    <div
+      ref={sub.setTrigger}
+      id={sub.triggerId}
+      role="menuitem"
+      tabindex={-1}
+      aria-haspopup="menu"
+      aria-expanded={sub.open()}
+      aria-controls={sub.open() ? sub.menuId : undefined}
+      onClick={() => sub.setOpen(!sub.open())}
+      onKeyDown={onKeyDown}
+      onPointerEnter={() => { sub.cancelClose(); sub.setOpen(true); }}
+      onPointerLeave={() => sub.scheduleClose()}
+      onPointerMove={(e) => (e.currentTarget as HTMLElement).focus()}
+      class={cn(
+        'flex cursor-pointer items-center rounded-md px-2 py-1.5 text-sm outline-none transition-colors',
+        'hover:bg-muted focus:bg-muted data-[expanded]:bg-muted',
+        props.class,
+      )}
+      data-expanded={sub.open() ? '' : undefined}
+    >
+      {props.children}
+      <ChevronRight class="ml-auto size-4 shrink-0 text-muted-foreground" aria-hidden="true" />
+    </div>
+  );
+}
+
+/**
+ * The submenu surface — same portal/positioning/roving-focus core as
+ * DropdownContent, anchored `right-start` off its trigger.
+ * a11y: ArrowLeft and Escape close the sub and RETURN FOCUS to the trigger;
+ * ArrowUp/Down/Home/End rove within; typeahead included (matches DropdownContent).
+ * Keyboard-open focuses the first item.
+ */
+export function DropdownSubContent(props: { children: JSX.Element; class?: string }) {
+  const sub = useDropdownSub();
+  const parent = useDropdown();
+  const config = useChatConfig();
+  const presence = createPresence(sub.open);
+  const position = usePosition(sub.trigger, sub.menu, {
+    placement: 'right-start',
+    gutter: 2,
+    // Sub trigger removed from the DOM -> close so the submenu portal doesn't orphan.
+    onDisconnect: () => sub.setOpen(false, { returnFocus: false }),
+  });
+  // Escape/ArrowLeft are handled by onKeyDown below (stopPropagation keeps them
+  // local to the sub). Outside-pointer dismiss is handled by the PARENT's
+  // useDismiss (whose refs include the registered submenu surface). A separate
+  // useDismiss here would double-fire Escape because document listeners run
+  // after stopPropagation on the element, not on the document.
+
+  const items = () => Array.from(sub.menu()?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []);
+  const focusIndex = (i: number) => {
+    const list = items();
+    if (!list.length) return;
+    const idx = ((i % list.length) + list.length) % list.length;
+    list[idx].focus();
+  };
+  const activeItem = () => {
+    const root = sub.menu()?.getRootNode() as Document | ShadowRoot | undefined;
+    return (root?.activeElement ?? document.activeElement) as Element | null;
+  };
+  const currentIndex = () => items().findIndex((el) => el === activeItem());
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    const list = items();
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); focusIndex(currentIndex() + 1); break;
+      case 'ArrowUp': e.preventDefault(); focusIndex(currentIndex() - 1); break;
+      case 'Home': e.preventDefault(); focusIndex(0); break;
+      case 'End': e.preventDefault(); focusIndex(list.length - 1); break;
+      case 'ArrowLeft': e.preventDefault(); e.stopPropagation(); sub.setOpen(false, { returnFocus: true }); break;
+      case 'Escape': e.preventDefault(); e.stopPropagation(); sub.setOpen(false, { returnFocus: true }); break;
+      default:
+        if (e.key.length === 1 && /\S/.test(e.key)) {
+          const start = currentIndex() + 1;
+          const lower = e.key.toLowerCase();
+          const match = list.findIndex((el, i) => i >= start && (el.textContent ?? '').trim().toLowerCase().startsWith(lower));
+          const found = match >= 0 ? match : list.findIndex((el) => (el.textContent ?? '').trim().toLowerCase().startsWith(lower));
+          if (found >= 0) { e.preventDefault(); focusIndex(found); }
+        }
+    }
+  };
+
+  return (
+    <Show when={presence.present()}>
+      <Portal mount={config.portalMount()}>
+        <div
+          ref={(el) => {
+            sub.setMenu(el); presence.setRef(el);
+            // Tell the parent menu this surface is part of its tree (outside-click).
+            const unregister = parent.registerSubMenu(el);
+            onCleanup(unregister);
+            if (sub.openedViaKeyboard()) {
+              queueMicrotask(() => el.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
+            }
+          }}
+          id={sub.menuId}
+          role="menu"
+          aria-labelledby={sub.triggerId}
+          tabindex={-1}
+          data-expanded={presence.state() === 'open' ? '' : undefined}
+          data-closed={presence.state() === 'closed' ? '' : undefined}
+          onKeyDown={onKeyDown}
+          // Keep the sub open while the pointer is over it (cancel a pending close
+          // scheduled by the trigger's pointerleave); re-arm the close on exit.
+          onPointerEnter={() => sub.cancelClose()}
+          onPointerLeave={() => sub.scheduleClose()}
+          style={{
+            position: 'fixed', left: `${position.pos().x}px`, top: `${position.pos().y}px`,
+            visibility: position.hidden() ? 'hidden' : 'visible',
+            'pointer-events': position.hidden() ? 'none' : undefined,
+          }}
+          class={cn(
+            'z-50 min-w-[8rem] rounded-lg bg-card p-1 kai-elevation',
+            'animate-in fade-in-0 zoom-in-95 data-[closed]:animate-out data-[closed]:fade-out-0 data-[closed]:zoom-out-95',
+            props.class,
+          )}
+        >
+          {props.children}
+        </div>
+      </Portal>
+    </Show>
+  );
+}

package/src/ui/editable-label.tsx

@@ -0,0 +1,112 @@
+import { type JSX, Show, createSignal, createEffect, untrack } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Input } from './input';
+
+export interface EditableLabelProps {
+  /** The label text. */
+  value: string;
+  /** Controlled edit state. When it flips true the field opens; double-click and
+   *  the host's `edit()` open it too. */
+  editing?: boolean;
+  /** Placeholder shown while editing (and as muted text when the value is empty). */
+  placeholder?: string;
+  /** Disable entering edit mode. */
+  disabled?: boolean;
+  /** Fires on commit (Enter / blur) with the new value — ONLY when it changed. */
+  onRename?: (value: string) => void;
+  /** Fires on Esc (cancel); the text is restored. */
+  onCancel?: () => void;
+  class?: string;
+}
+
+/**
+ * `EditableLabel`: inline rename. Shows `value` as text; double-click (or the
+ * `editing` prop, or a host `edit()`) swaps in an autofocused `Input` with the
+ * text pre-selected. Enter or blur commits (fires `onRename` only when the value
+ * changed); Esc cancels (fires `onCancel`, restores the text). Both exit editing.
+ *
+ * Parts: `text` (the read view), `input` (the field while editing).
+ */
+export function EditableLabel(props: EditableLabelProps): JSX.Element {
+  // `editing` is seeded from the controlled prop and follows it; double-click /
+  // commit / cancel toggle it locally without touching the prop (no feedback loop).
+  const [editing, setEditing] = createSignal(!!props.editing);
+  createEffect(() => setEditing(!!props.editing));
+
+  // The displayed text. Seeded from `value`, kept in sync with it, and updated
+  // optimistically on a successful rename so the read view shows the new label.
+  const [text, setText] = createSignal(props.value);
+  createEffect(() => setText(props.value));
+
+  let root: HTMLElement | undefined;
+  // Set before an Enter/Esc unmounts the field so its teardown blur does not
+  // double-commit (mirrors the AMUX inline-rename guard).
+  let suppressBlur = false;
+
+  const focusSelect = () => {
+    const input = root?.querySelector('input');
+    if (input) { input.focus(); input.select(); }
+  };
+  createEffect(() => { if (editing()) queueMicrotask(focusSelect); });
+
+  const enterEdit = () => { if (!props.disabled) setEditing(true); };
+
+  const commit = (next: string) => {
+    if (!untrack(editing)) return; // idempotent: a teardown blur after Enter is a no-op
+    setEditing(false);
+    if (next !== untrack(text)) { setText(next); props.onRename?.(next); }
+  };
+
+  const cancel = () => {
+    if (!untrack(editing)) return;
+    setEditing(false);
+    props.onCancel?.();
+  };
+
+  const onFieldKeyDown = (e: KeyboardEvent) => {
+    const el = e.currentTarget as HTMLInputElement;
+    if (e.key === 'Enter') { e.preventDefault(); suppressBlur = true; commit(el.value); }
+    else if (e.key === 'Escape') { e.preventDefault(); suppressBlur = true; cancel(); }
+  };
+
+  const onFieldBlur = (v: string) => {
+    if (suppressBlur) { suppressBlur = false; return; }
+    commit(v);
+  };
+
+  return (
+    <span ref={root} class={cn('inline-flex max-w-full items-center', props.class)}>
+      <Show
+        when={editing()}
+        fallback={
+          <span
+            part="text"
+            tabindex={props.disabled ? undefined : 0}
+            class={cn(
+              'inline-block max-w-full truncate rounded px-1 py-0.5 text-sm text-foreground',
+              props.disabled ? 'cursor-default opacity-60' : 'cursor-text hover:bg-muted',
+              !text() && 'text-muted-foreground',
+            )}
+            onDblClick={enterEdit}
+            onKeyDown={(e) => {
+              if (!props.disabled && (e.key === 'Enter' || e.key === 'F2')) { e.preventDefault(); enterEdit(); }
+            }}
+          >
+            {text() || props.placeholder || ''}
+          </span>
+        }
+      >
+        <Input
+          value={text()}
+          placeholder={props.placeholder}
+          disabled={props.disabled}
+          size="sm"
+          class="h-7 py-0"
+          aria-label={props.placeholder ?? 'Edit label'}
+          onKeyDown={onFieldKeyDown}
+          onValueChange={onFieldBlur}
+        />
+      </Show>
+    </span>
+  );
+}

package/src/ui/hover-card.tsx

@@ -25,13 +25,28 @@ const useHoverCard = () => {
   return c;
 };
 
-export interface HoverCardRootProps { children: JSX.Element; openDelay?: number; closeDelay?: number; }
+/** Imperative open controller, handed to a parent (e.g. the kai-hover-card facade)
+ *  via `controllerRef` so it can drive/observe open state. */
+export interface HoverCardController { open: Accessor<boolean>; setOpen: (v: boolean) => void; }
+
+export interface HoverCardRootProps {
+  children: JSX.Element;
+  openDelay?: number;
+  closeDelay?: number;
+  /** Initial open state (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** When true, hover/focus never opens the card. */
+  disabled?: boolean;
+  /** Receive the open controller (open accessor + setOpen) once mounted. */
+  controllerRef?: (api: HoverCardController) => void;
+}
 
 export function HoverCardRoot(props: HoverCardRootProps) {
-  const [open, setOpen] = createSignal(false);
+  const [open, setOpen] = createSignal(props.defaultOpen ?? false);
   const [trigger, setTrigger] = createSignal<HTMLElement>();
   const [content, setContent] = createSignal<HTMLElement>();
   let timer: number | undefined;
+  props.controllerRef?.({ open, setOpen });
 
   // ONE shared timer drives both trigger and content. Entering either cancels
   // any pending close and schedules an open; leaving either cancels any pending
@@ -40,6 +55,7 @@ export function HoverCardRoot(props: HoverCardRootProps) {
   // before it can run, so the card never flickers and there are no stale-timer
   // sporadics (the HC-1 fix).
   const enter = () => {
+    if (props.disabled) return;
     clearTimeout(timer);
     timer = window.setTimeout(() => setOpen(true), props.openDelay ?? 0);
   };
@@ -70,7 +86,7 @@ export function HoverCardTrigger(props: HoverCardTriggerProps) {
   return (
     <As
       as="span"
-      class={props.class}
+      class={cn('inline-block', props.class)}
       ref={ctx.setTrigger}
       onPointerEnter={ctx.enter}
       onPointerLeave={ctx.leave}
@@ -117,8 +133,15 @@ export function HoverCardContent(props: HoverCardContentProps) {
   // gutter: 0 places the outer shell flush with the trigger; the visual gap is
   // recreated by transparent padding (gapPaddingStyle) so the hit area bridges
   // it and a straight trigger->content transit never leaves a hot zone.
-  const position = usePosition(ctx.trigger, ctx.content, { placement: props.placement ?? 'bottom', gutter: 0 });
-  useDismiss({ enabled: ctx.open, onDismiss: (reason) => (reason === 'escape' ? ctx.close() : ctx.leave()), refs: () => [ctx.trigger(), ctx.content()] });
+  const position = usePosition(ctx.trigger, ctx.content, {
+    placement: props.placement ?? 'bottom',
+    gutter: 0,
+    // Trigger removed from the DOM -> close so the card portal doesn't orphan.
+    onDisconnect: () => ctx.close(),
+  });
+  // Escape OR an outside click closes immediately — an outside click is a
+  // deliberate dismiss, not a hover-out (which uses leave()'s grace delay).
+  useDismiss({ enabled: ctx.open, onDismiss: () => ctx.close(), refs: () => [ctx.trigger(), ctx.content()] });
 
   return (
     <Show when={presence.present()}>