@kitn.ai/ui 0.25.2 → 0.27.0

package/src/ui/dropdown.tsx

@@ -37,6 +37,63 @@ const useDropdown = () => {
 // 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"])';
 
+/**
+ * The roving-focus set, in FLAT-TREE order.
+ *
+ * ★ NOT `querySelectorAll`, and the difference is the whole point: a `<slot>` in the
+ * shadow tree contains NONE of the light-DOM nodes it projects, so a plain query
+ * returns zero items for any facade whose rows are SLOTTED (`<kai-dropdown>`) and
+ * ArrowUp/Down, Home/End and typeahead all reach nothing. The items-tree facades
+ * (`kai-menu`, `kai-model-switcher`, `kai-scope-picker`) render their rows INTO the
+ * shadow tree, so both spellings agree for them — which is exactly why this went
+ * unnoticed until a slotted menu body existed.
+ *
+ * Same class as `hasFocusableChild` in ./hover-card.tsx, which asks the boolean
+ * version of this question. This one needs the ORDER as well, so it walks the tree
+ * and splices each slot's assigned elements in AT THE SLOT'S POSITION rather than
+ * appending them; a menu may mix rendered and slotted rows. `flatten: true` follows
+ * a slot assigned to another slot.
+ *
+ * Scope is unchanged: submenu content is portaled to a SIBLING node, so a parent's
+ * walk still never reaches sub items.
+ */
+function menuItems(root: HTMLElement | undefined): HTMLElement[] {
+  if (!root) return [];
+  const out: HTMLElement[] = [];
+  const collect = (el: Element): void => {
+    if (el.matches(ITEM_SELECTOR)) out.push(el as HTMLElement);
+    for (const child of Array.from(el.children)) visit(child);
+  };
+  const visit = (el: Element): void => {
+    if (el.localName === 'slot') {
+      for (const assigned of (el as HTMLSlotElement).assignedElements({ flatten: true })) collect(assigned);
+      return;
+    }
+    collect(el);
+  };
+  for (const child of Array.from(root.children)) visit(child);
+  return out;
+}
+
+/** The first roving-focus item, in flat-tree order. Replaces
+ *  `querySelector(ITEM_SELECTOR)` for the reason `menuItems` replaces the `All`. */
+const firstMenuItem = (root: HTMLElement | undefined): HTMLElement | undefined => menuItems(root)[0];
+
+/**
+ * The focused item, resolved across BOTH trees.
+ *
+ * Inside a Shadow DOM `document.activeElement` returns the HOST rather than the
+ * focused menu item, so the menu's own root node is asked first. But a SLOTTED row
+ * lives in the LIGHT DOM: focus is then outside the shadow tree, that root reports
+ * null, and the document's answer is the real one. Asking only the shadow root would
+ * leave `currentIndex()` at -1 for every slotted row, so ArrowDown would restart at
+ * the top instead of advancing.
+ */
+function activeMenuItem(root: HTMLElement | undefined): Element | null {
+  const tree = root?.getRootNode() as Document | ShadowRoot | undefined;
+  return (tree?.activeElement ?? document.activeElement) as Element | null;
+}
+
 /** 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; }
@@ -103,8 +160,8 @@ export function Dropdown(props: DropdownProps) {
       // 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) {
-        queueMicrotask(() => menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
-        menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus();
+        queueMicrotask(() => firstMenuItem(menu())?.focus());
+        firstMenuItem(menu())?.focus();
       }
     } else if (opts?.returnFocus !== false) {
       // Closing via keyboard/select: return focus to the trigger. The menu
@@ -179,23 +236,14 @@ export function DropdownContent(props: DropdownContentProps) {
     refs: () => [ctx.trigger(), ctx.menu(), ...ctx.subMenus()],
   });
 
-  const items = () => Array.from(ctx.menu()?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []);
+  const items = () => menuItems(ctx.menu());
   const focusIndex = (i: number) => {
     const list = items();
     if (!list.length) return;
     const idx = ((i % list.length) + list.length) % list.length;
     list[idx].focus();
   };
-  // Resolve the focused item via the menu's own root node. Inside a Shadow DOM
-  // (every kitn-* element), `document.activeElement` returns the host element,
-  // not the focused menu item, which would break ArrowUp/Down roving focus.
-  // `getRootNode().activeElement` correctly returns the active node within the
-  // same tree (ShadowRoot or Document).
-  const activeItem = () => {
-    const root = ctx.menu()?.getRootNode() as Document | ShadowRoot | undefined;
-    return (root?.activeElement ?? document.activeElement) as Element | null;
-  };
-  const currentIndex = () => items().findIndex((el) => el === activeItem());
+  const currentIndex = () => items().findIndex((el) => el === activeMenuItem(ctx.menu()));
 
   const onKeyDown = (e: KeyboardEvent) => {
     const list = items();
@@ -226,7 +274,7 @@ export function DropdownContent(props: DropdownContentProps) {
             // synchronously; this ref-time microtask re-asserts focus once the
             // menu node exists. Skip disabled items.
             if (ctx.openedViaKeyboard()) {
-              queueMicrotask(() => el.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
+              queueMicrotask(() => firstMenuItem(el)?.focus());
             }
           }}
           id={ctx.menuId}
@@ -424,8 +472,8 @@ export function DropdownSub(props: DropdownSubProps) {
     setOpenSig(v);
     if (v) {
       if (opts?.viaKeyboard) {
-        queueMicrotask(() => menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
-        menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus();
+        queueMicrotask(() => firstMenuItem(menu())?.focus());
+        firstMenuItem(menu())?.focus();
       }
     } else if (opts?.returnFocus !== false) {
       const el = trigger();
@@ -516,18 +564,14 @@ export function DropdownSubContent(props: DropdownSubContentProps) {
   // 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 items = () => menuItems(sub.menu());
   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 currentIndex = () => items().findIndex((el) => el === activeMenuItem(sub.menu()));
 
   const onKeyDown = (e: KeyboardEvent) => {
     const list = items();
@@ -559,7 +603,7 @@ export function DropdownSubContent(props: DropdownSubContentProps) {
             const unregister = parent.registerSubMenu(el);
             onCleanup(unregister);
             if (sub.openedViaKeyboard()) {
-              queueMicrotask(() => el.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
+              queueMicrotask(() => firstMenuItem(el)?.focus());
             }
           }}
           id={sub.menuId}

package/src/ui/hover-card.tsx

@@ -1,5 +1,5 @@
 import {
-  createContext, useContext, createSignal, Show, splitProps, onCleanup,
+  createContext, useContext, createSignal, createUniqueId, Show, splitProps, onCleanup,
   type JSX, type Accessor,
 } from 'solid-js';
 import { Portal } from 'solid-js/web';
@@ -17,6 +17,12 @@ interface HoverCardCtx {
   setContent: (el: HTMLElement) => void;
   trigger: Accessor<HTMLElement | undefined>;
   content: Accessor<HTMLElement | undefined>;
+  /** Ties a focused trigger to the card it reveals. Without it a keyboard tab
+   *  stop announces nothing, which is a focus stop that wastes the user's time. */
+  contentId: string;
+  /** Whether this card refuses to open. Read by the TRIGGER, not just by
+   *  `enter()`: a card that cannot open must not be in the tab order either. */
+  disabled: Accessor<boolean>;
 }
 const Ctx = createContext<HoverCardCtx>();
 const useHoverCard = () => {
@@ -45,6 +51,7 @@ export function HoverCardRoot(props: HoverCardRootProps) {
   const [open, setOpen] = createSignal(props.defaultOpen ?? false);
   const [trigger, setTrigger] = createSignal<HTMLElement>();
   const [content, setContent] = createSignal<HTMLElement>();
+  const contentId = createUniqueId();
   let timer: number | undefined;
   props.controllerRef?.({ open, setOpen });
 
@@ -73,25 +80,167 @@ export function HoverCardRoot(props: HoverCardRootProps) {
       open, enter, leave, close,
       setTrigger, setContent,
       trigger, content,
+      contentId,
+      disabled: () => props.disabled ?? false,
     }}>
       {props.children}
     </Ctx.Provider>
   );
 }
 
-export interface HoverCardTriggerProps { children: JSX.Element; class?: string; }
+export interface HoverCardTriggerProps {
+  children: JSX.Element;
+  class?: string;
+  /**
+   * Whether the trigger is its own tab stop. Omit for the automatic behaviour,
+   * which is right for every case in this repo: the trigger takes focus only
+   * when nothing inside it already can.
+   *
+   * Pass `false` to keep a trigger out of the tab order entirely, or `true` to
+   * force a stop. Both are escape hatches — reach for them when the automatic
+   * answer is wrong, not to restate it.
+   */
+  focusable?: boolean;
+}
+
+/** Anything the platform puts in the tab order by default, plus anything a
+ *  consumer opted in with `tabindex`. `tabindex="-1"` is deliberately excluded:
+ *  it is programmatically focusable but the Tab key skips it, so a trigger
+ *  containing only such an element still needs a stop of its own. */
+const FOCUSABLE_CHILD =
+  'a[href],button,input,select,textarea,summary,[contenteditable=""],[contenteditable="true"],[tabindex]:not([tabindex^="-"])';
+
+/** Does this subtree already offer the keyboard a way in? Slotted content is
+ *  checked through `assignedElements()`, because a `<slot>` in the shadow tree
+ *  contains none of the light-DOM nodes it projects — the `kai-hover-card`
+ *  facade wraps a bare `<slot />`, so without this branch every use of that
+ *  element would be told its children are inert.
+ *
+ *  ★ WHEN this runs is as load-bearing as what it asks. At ref time the facade's
+ *  trigger contains `<slot></slot>` with NOTHING assigned yet, so a single call
+ *  from the ref answers "inert" for a slot that is about to receive a focusable
+ *  `<a>` — and the trigger stamps a second tab stop on top of the child's. That
+ *  is the very regression the `assignedElements()` branch was added to prevent,
+ *  reintroduced by timing rather than by logic. Measured with a real Tab key:
+ *  4 stops across a 3-widget fixture. So the caller re-runs this on
+ *  `slotchange`; see `HoverCardTrigger`. */
+const hasFocusableChild = (root: HTMLElement): boolean => {
+  if (root.querySelector(FOCUSABLE_CHILD)) return true;
+  return Array.from(root.querySelectorAll('slot')).some((slot) =>
+    (slot as HTMLSlotElement).assignedElements().some(
+      (el) => el.matches(FOCUSABLE_CHILD) || el.querySelector(FOCUSABLE_CHILD),
+    ),
+  );
+};
 
+/**
+ * ★ THE TRIGGER IS A TAB STOP WHEN, AND ONLY WHEN, ITS CHILDREN ARE NOT.
+ *
+ * `onFocusIn`/`onFocusOut` were here from the start and the focus-open path was
+ * plainly intended, but the span never set `tabindex`, so the Tab key could not
+ * land on it and neither handler could fire on a keyboard. It went unnoticed for
+ * as long as it did because `focusin` BUBBLES and every consumer at the time put
+ * something focusable inside the trigger — `source.tsx` an `<a>`, `context.tsx`
+ * a `<Button>` — so the card opened via the child and the span's own inertness
+ * never showed. The first trigger with inert children (an attachment tile: a
+ * div, an img, an svg) had no tab stop anywhere in it.
+ *
+ * Hence delegation rather than an unconditional `tabindex`: adding one always
+ * would give every existing consumer TWO stops for one card, which is a worse
+ * bug than the one being fixed. The check runs in the ref AND again on every
+ * `slotchange`, because slot assignment happens after the ref and a one-shot
+ * check calls a not-yet-filled `<slot>` inert (see `hasFocusableChild`).
+ *
+ * ★ THE FOCUS LISTENERS ARE NATIVE, NOT SOLID'S DELEGATED `onFocusIn`. Solid
+ * delegates a fixed set of events from the document and retargets them into
+ * component trees; inside these shadow roots that path runs for a PROGRAMMATIC
+ * `.focus()` and, in the deeper trees, not for a real Tab. Measured: tabbing to
+ * an attachment tile in a mounted `<kai-chat>` left the card shut and
+ * `aria-describedby` null while `.focus()` on the same element opened it — so
+ * every keyboard user got a tab stop that announced nothing and showed nothing,
+ * which is worse than no stop at all. `addEventListener` in the ref does not
+ * care how focus arrived. Anything in this kit relying on delegated focus
+ * events inside a shadow root is suspect for the same reason.
+ *
+ * `aria-describedby` is what makes the stop worth arriving at: the card is
+ * DESCRIPTIVE, not an action, so the trigger gets no `role="button"` — that
+ * would promise an activation that does not exist — and instead points at the
+ * content it reveals so a screen reader reads it out.
+ */
 export function HoverCardTrigger(props: HoverCardTriggerProps) {
   const ctx = useHoverCard();
+  const [detectedInert, setDetectedInert] = createSignal(false);
+  // `&& !disabled` last, and it beats an explicit `focusable` — a disabled card
+  // early-returns out of `enter()`, so a stop here could never open anything.
+  // Landing on it would announce nothing and reveal nothing, which is the dead
+  // stop the note above argues against; forcing one is not an escape hatch
+  // anybody should get.
+  const isFocusable = () => (props.focusable ?? detectedInert()) && !ctx.disabled();
+
   return (
     <As
       as="span"
-      class={cn('inline-block', props.class)}
-      ref={ctx.setTrigger}
+      class={cn(
+        'inline-block',
+        // A tab stop nobody can SEE is barely an improvement on no tab stop —
+        // WCAG 2.4.7. Only when this element is the stop; a delegating trigger
+        // must not draw a ring around its child's own focus state.
+        //
+        // AN OUTLINE, NOT A RING, and both halves of that were measured rather
+        // than assumed:
+        //
+        //  1. ★ A TAILWIND v4 UTILITY THAT ROUTES THROUGH `@property` IS INERT
+        //     INSIDE THESE SHADOW ROOTS, and that is a trap far wider than this
+        //     line. v4 gives `--tw-*` custom properties their defaults with
+        //     `@property`, and an `@property` rule delivered through a shadow
+        //     root's `adoptedStyleSheets` never registers — so the var resolves
+        //     to nothing, the declaration is invalid, and the property falls
+        //     back to its initial value. Measured in Chrome, twice:
+        //     `ring-2 ring-offset-1` set `--tw-ring-shadow` correctly and
+        //     computed `box-shadow: none`; `inset-ring-2` did the same; and
+        //     `outline-2` alone computed `outline-style: none` while width,
+        //     colour and offset all landed, because only the style goes
+        //     through `var(--tw-outline-style)`. Hence the literal
+        //     `[outline-style:solid]` — the one part that cannot be a var.
+        //  2. The offset is NEGATIVE so the outline lands inside the border
+        //     box. A trigger that fills its container (`block size-full` inside
+        //     the attachment tile's `overflow-hidden rounded-lg`) would
+        //     otherwise have its focus indicator painted straight into the
+        //     clip, and a trigger cannot know whether its container clips.
+        isFocusable() &&
+          'rounded-sm focus-visible:[outline-style:solid] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring',
+        props.class,
+      )}
+      ref={(el: HTMLElement) => {
+        ctx.setTrigger(el);
+
+        // Native listeners, deliberately — see the note above. `focusin` /
+        // `focusout` rather than `focus` / `blur` because these have to fire
+        // for a focusable CHILD too, and only the -in/-out pair bubbles.
+        const enter = () => ctx.enter();
+        const leave = () => ctx.leave();
+        el.addEventListener('focusin', enter);
+        el.addEventListener('focusout', leave);
+        onCleanup(() => {
+          el.removeEventListener('focusin', enter);
+          el.removeEventListener('focusout', leave);
+        });
+
+        // Ask now for the direct-children case, and again whenever a slot is
+        // filled or emptied. Both are needed: `slotchange` never fires for a
+        // trigger with no slot in it, and the ref-time answer is wrong for one
+        // that has.
+        const evaluate = () => setDetectedInert(!hasFocusableChild(el));
+        evaluate();
+        for (const slot of Array.from(el.querySelectorAll('slot'))) {
+          slot.addEventListener('slotchange', evaluate);
+          onCleanup(() => slot.removeEventListener('slotchange', evaluate));
+        }
+      }}
+      tabIndex={isFocusable() ? 0 : undefined}
+      aria-describedby={isFocusable() && ctx.open() ? ctx.contentId : undefined}
       onPointerEnter={ctx.enter}
       onPointerLeave={ctx.leave}
-      onFocusIn={ctx.enter}
-      onFocusOut={ctx.leave}
     >
       {props.children}
     </As>
@@ -166,6 +315,7 @@ export function HoverCardContent(props: HoverCardContentProps) {
         >
           {/* Inner card: all visual + animation classes and the presence state. */}
           <div
+            id={ctx.contentId}
             data-expanded={presence.state() === 'open' ? '' : undefined}
             data-closed={presence.state() === 'closed' ? '' : undefined}
             class={cn(

package/src/ui/icon.tsx

@@ -9,6 +9,16 @@ import {
   Archive, ArrowUp, Bookmark, Copy, Ellipsis, ExternalLink, Flag,
   GitBranch, GitPullRequest, ListFilter, RotateCw,
   Moon, Sun,
+  // Device / viewport glyphs.
+  Tablet, Smartphone, Laptop,
+  // Direction glyphs completing the chevron + arrow quartets.
+  ChevronRight, ChevronUp, ArrowRight, ArrowDown, PanelRight,
+  // Status glyphs (kai-notice / kai-toast / kai-tool render these already).
+  Check, Info, TriangleAlert, CircleCheck, CircleAlert, CircleX,
+  // Action glyphs the kit performs but could not be named.
+  Trash2, Download, Upload, Link, RotateCcw,
+  // Pane / media chrome.
+  Maximize2, Minimize2, Eye, EyeOff, Bell, Square, Minus, Play,
 } from 'lucide-solid';
 
 type IconComponent = Component<{ class?: string }>;
@@ -68,8 +78,51 @@ const NAMED_ICONS: Record<string, IconComponent> = {
   // Theme / appearance glyphs.
   moon: Moon,
   sun: Sun,
+  // Device / viewport glyphs. `desktop` and `mobile` are aliases onto the same
+  // components as `monitor`/`smartphone` — lucide's names are not the words a
+  // consumer reaches for, and an alias costs nothing in the bundle.
+  desktop: Monitor,
+  laptop: Laptop,
+  tablet: Tablet,
+  smartphone: Smartphone,
+  mobile: Smartphone,
+  // Direction glyphs — chevron-down/left and arrow-left/up were here without
+  // their opposites; both quartets are now complete.
+  'chevron-right': ChevronRight,
+  'chevron-up': ChevronUp,
+  'arrow-right': ArrowRight,
+  'arrow-down': ArrowDown,
+  'panel-right': PanelRight,
+  // Status glyphs. kai-notice / kai-toast / kai-tool already paint these, so a
+  // host building matching UI needs to be able to name them.
+  check: Check,
+  info: Info,
+  'triangle-alert': TriangleAlert,
+  'circle-check': CircleCheck,
+  'circle-alert': CircleAlert,
+  'circle-x': CircleX,
+  // Action glyphs. `trash`/`download`/`link` match the keys action-icons.ts
+  // already uses for message actions; `upload` is download's missing sibling.
+  trash: Trash2,
+  download: Download,
+  upload: Upload,
+  link: Link,
+  'rotate-ccw': RotateCcw,
+  // Pane / media chrome (kai-pane, kai-artifact, kai-embed, kai-agent-card).
+  'maximize-2': Maximize2,
+  'minimize-2': Minimize2,
+  eye: Eye,
+  'eye-off': EyeOff,
+  bell: Bell,
+  square: Square,
+  minus: Minus,
+  play: Play,
 };
 
+/** Every curated icon name, sorted. Derived from `NAMED_ICONS` so a gallery,
+ *  a story control or a test can never drift from the map itself. */
+export const ICON_NAMES: readonly string[] = Object.keys(NAMED_ICONS).sort();
+
 /** Render an item icon.
  *
  *  Resolution order: