@kitnai/chat 0.3.0 → 0.4.0

package/src/stories/typography.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { For, createSignal, onMount } from 'solid-js';
+
+const meta = {
+  title: 'Theming/Typography',
+  parameters: { layout: 'padded' },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+// The semantic type scale (defined in theme.css `@theme`). Each row is a token
+// that generates a Tailwind utility AND is an overridable CSS custom property.
+const SCALE = [
+  { token: '--text-caption', cls: 'text-caption', role: 'Micro labels, badges, sub-counts', used: 'token sub-totals · model provider · media-type subtitle' },
+  { token: '--text-meta', cls: 'text-meta', role: 'Controls, toggles, switchers, captions', used: 'reasoning / chain-of-thought triggers · model switcher · context · source' },
+  { token: '--text-body', cls: 'text-body', role: 'Primary reading text', used: 'messages · input · suggestions · markdown (also scales with the `proseSize` prop)' },
+  { token: '--text-title', cls: 'text-title', role: 'Emphasis / headers', used: 'section emphasis' },
+] as const;
+
+function TypographyScale() {
+  const [px, setPx] = createSignal<Record<string, string>>({});
+  onMount(() => {
+    const cs = getComputedStyle(document.documentElement);
+    const toPx = (rem: string) => {
+      const v = parseFloat(rem);
+      return rem.includes('rem') ? `${Math.round(v * 16)}px` : rem.trim();
+    };
+    setPx(Object.fromEntries(SCALE.map((s) => [s.token, toPx(cs.getPropertyValue(s.token))])));
+  });
+
+  return (
+    <div class="text-foreground max-w-3xl">
+      <h2 class="mb-1 text-lg font-semibold">Typography scale</h2>
+      <p class="text-muted-foreground mb-6 text-sm">
+        Defined once in <code class="text-code-foreground">theme.css</code>. Each token generates a Tailwind utility
+        (<code class="text-code-foreground">text-meta</code>, …). To restyle the kit's typography globally, override the
+        namespaced <code class="text-code-foreground">--kitn-text-*</code> token on <code class="text-code-foreground">:root</code> —
+        it pierces the Shadow&nbsp;DOM exactly like the <code class="text-code-foreground">--kitn-color-*</code> tokens. (The bare
+        <code class="text-code-foreground"> --text-*</code> names stay internal, so a host's own tokens can't collide.)
+      </p>
+
+      <div class="border-border divide-border divide-y rounded-xl border">
+        <For each={SCALE}>
+          {(s) => (
+            <div class="grid grid-cols-[170px_1fr] items-center gap-4 p-4">
+              <div class="min-w-0">
+                <div class="text-foreground font-mono text-xs">{s.token}</div>
+                <div class="text-muted-foreground mt-1 font-mono text-[11px]">{px()[s.token] ?? '…'}</div>
+                <div class="text-muted-foreground mt-2 text-xs">{s.role}</div>
+              </div>
+              <div class="min-w-0">
+                <div class={`${s.cls} text-foreground`}>The quick brown fox jumps over the lazy dog</div>
+                <div class="text-muted-foreground mt-1.5 text-[11px]">{s.used}</div>
+              </div>
+            </div>
+          )}
+        </For>
+      </div>
+
+      <h3 class="mt-8 mb-2 text-sm font-semibold">Override example</h3>
+      <pre class="bg-muted text-foreground overflow-auto rounded-lg p-3 font-mono text-xs">{`:root {
+  --kitn-text-body: 0.9375rem;   /* bump the reading size to 15px */
+  --kitn-text-meta: 0.8125rem;   /* and the control size to 13px */
+}`}</pre>
+      <p class="text-muted-foreground mt-2 text-xs">
+        Reading text in messages / input / markdown additionally scales with the
+        <code class="text-code-foreground"> proseSize</code> prop (<code class="text-code-foreground">xs · sm · base · lg</code>);
+        these tokens cover the fixed chrome &amp; controls.
+      </p>
+    </div>
+  );
+}
+
+/** The kit's semantic type scale — defined in theme.css, used everywhere, overridable. */
+export const Typography: Story = {
+  render: () => <TypographyScale />,
+};

package/src/ui/button.tsx

@@ -3,7 +3,7 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../utils/cn';
 
 const buttonVariants = cva(
-  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
       variant: {

package/src/ui/collapsible.tsx

@@ -1,14 +1,125 @@
-import { Collapsible as KCollapsible } from '@kobalte/core/collapsible';
-import { type JSX } from 'solid-js';
+import {
+  createContext,
+  useContext,
+  createSignal,
+  createUniqueId,
+  splitProps,
+  type JSX,
+  type Accessor,
+} from 'solid-js';
 import { cn } from '../utils/cn';
 
-export const Collapsible = KCollapsible;
-export const CollapsibleTrigger = KCollapsible.Trigger;
+// Extend SolidJS JSX to allow `bool:inert` (forces setAttribute so jsdom reflects it as an attribute).
+declare module 'solid-js' {
+  namespace JSX {
+    interface ExplicitBoolAttributes {
+      inert: boolean;
+    }
+  }
+}
+
+interface CollapsibleCtx {
+  open: Accessor<boolean>;
+  toggle: () => void;
+  contentId: string;
+}
+
+const Ctx = createContext<CollapsibleCtx>();
+
+const useCollapsible = () => {
+  const c = useContext(Ctx);
+  if (!c) throw new Error('Collapsible parts must be used within <Collapsible>');
+  return c;
+};
+
+export function Collapsible(props: {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children: JSX.Element;
+  class?: string;
+}) {
+  const [local, rest] = splitProps(props, ['open', 'defaultOpen', 'onOpenChange', 'children', 'class']);
+  const [uncontrolled, setUncontrolled] = createSignal(local.defaultOpen ?? false);
+  const isControlled = () => local.open !== undefined;
+  const open = () => (isControlled() ? !!local.open : uncontrolled());
+  const toggle = () => {
+    const next = !open();
+    if (!isControlled()) setUncontrolled(next);
+    local.onOpenChange?.(next);
+  };
+  const contentId = createUniqueId();
+  return (
+    <Ctx.Provider value={{ open, toggle, contentId }}>
+      <div
+        class={local.class}
+        {...rest}
+        data-expanded={open() ? '' : undefined}
+        data-closed={open() ? undefined : ''}
+        data-state={open() ? 'open' : 'closed'}
+      >
+        {local.children}
+      </div>
+    </Ctx.Provider>
+  );
+}
+
+export function CollapsibleTrigger(props: {
+  children?: JSX.Element;
+  class?: string;
+  as?: (props: Record<string, any>) => JSX.Element;
+  onClick?: JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent>;
+  [k: string]: any;
+}) {
+  const ctx = useCollapsible();
+  const [local, rest] = splitProps(props, ['children', 'class', 'as', 'onClick']);
+
+  const triggerProps = () => ({
+    type: 'button' as const,
+    'aria-expanded': ctx.open(),
+    'aria-controls': ctx.contentId,
+    'data-expanded': ctx.open() ? '' : undefined,
+    'data-closed': ctx.open() ? undefined : '',
+    'data-state': ctx.open() ? 'open' : 'closed',
+    onClick: (e: MouseEvent) => {
+      if (typeof local.onClick === 'function') {
+        (local.onClick as (e: MouseEvent) => void)(e);
+      }
+      ctx.toggle();
+    },
+    class: local.class,
+    ...rest,
+  });
+
+  return (
+    <>
+      {local.as
+        ? local.as(triggerProps() as any)
+        : (
+          <button {...triggerProps()}>
+            {local.children}
+          </button>
+        )}
+    </>
+  );
+}
 
-export function CollapsibleContent(props: { children: JSX.Element; class?: string }) {
+export function CollapsibleContent(props: { children?: JSX.Element; class?: string; [k: string]: any }) {
+  const ctx = useCollapsible();
+  const [local, rest] = splitProps(props, ['children', 'class']);
   return (
-    <KCollapsible.Content class={cn('overflow-hidden', props.class)}>
-      {props.children}
-    </KCollapsible.Content>
+    <div
+      {...rest}
+      id={ctx.contentId}
+      data-expanded={ctx.open() ? '' : undefined}
+      data-closed={ctx.open() ? undefined : ''}
+      class={cn(
+        'grid transition-[grid-template-rows] duration-200 ease-out',
+        ctx.open() ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+      )}
+      bool:inert={!ctx.open()}
+    >
+      <div class={cn('overflow-hidden', local.class)}>{local.children}</div>
+    </div>
   );
 }

package/src/ui/dropdown.tsx

@@ -1,26 +1,191 @@
-import { DropdownMenu as KDropdown } from '@kobalte/core/dropdown-menu';
-import { type JSX } from 'solid-js';
+import {
+  createContext, useContext, createSignal, createUniqueId, Show,
+  type JSX, type Accessor,
+} from 'solid-js';
+import { Portal } from 'solid-js/web';
 import { cn } from '../utils/cn';
 import { useChatConfig } from '../primitives/chat-config';
+import { createPresence, usePosition, useDismiss, As, type AsTag } from './overlay';
 
-export const Dropdown = KDropdown;
-export const DropdownTrigger = KDropdown.Trigger;
+interface DropdownCtx {
+  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>;
+}
+const Ctx = createContext<DropdownCtx>();
+const useDropdown = () => {
+  const c = useContext(Ctx);
+  if (!c) throw new Error('Dropdown parts must be used within <Dropdown>');
+  return c;
+};
+
+export function Dropdown(props: { children: JSX.Element }) {
+  const [open, setOpenSig] = createSignal(false);
+  const [viaKb, setViaKb] = createSignal(false);
+  const [trigger, setTrigger] = createSignal<HTMLElement>();
+  const [menu, setMenu] = createSignal<HTMLElement>();
+  const setOpen = (v: boolean, opts?: { viaKeyboard?: boolean; returnFocus?: boolean }) => {
+    setViaKb(!!opts?.viaKeyboard);
+    setOpenSig(v);
+    if (v) {
+      // Focus the first item on keyboard-open. The menu mounts via <Show>; we
+      // 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();
+      }
+    } else if (opts?.returnFocus !== false) {
+      // Closing via keyboard/select: return focus to the trigger. The menu
+      // unmounts on a microtask (createPresence) and that teardown blurs
+      // whatever is focused, so re-assert focus AFTER unmount too.
+      const el = trigger();
+      el?.focus();
+      queueMicrotask(() => el?.focus());
+    }
+  };
+  return (
+    <Ctx.Provider value={{
+      open, setOpen, triggerId: createUniqueId(), menuId: createUniqueId(),
+      setTrigger, setMenu, trigger, menu, openedViaKeyboard: viaKb,
+    }}>
+      {props.children}
+    </Ctx.Provider>
+  );
+}
+
+export function DropdownTrigger(props: { as?: AsTag; children?: JSX.Element; class?: string; [k: string]: any }) {
+  const ctx = useDropdown();
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      ctx.setOpen(true, { viaKeyboard: true });
+    }
+  };
+  return (
+    <As
+      as={props.as ?? 'button'}
+      ref={ctx.setTrigger}
+      id={ctx.triggerId}
+      aria-haspopup="menu"
+      aria-expanded={ctx.open()}
+      aria-controls={ctx.open() ? ctx.menuId : undefined}
+      onClick={() => ctx.setOpen(!ctx.open())}
+      onKeyDown={onKeyDown}
+      class={props.class}
+      {...(props.as ? {} : { type: 'button' })}
+    >
+      {props.children}
+    </As>
+  );
+}
 
 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 });
+  useDismiss({
+    enabled: ctx.open,
+    onDismiss: (reason) => ctx.setOpen(false, { returnFocus: reason === 'escape' }),
+    refs: () => [ctx.trigger(), ctx.menu()],
+  });
+
+  const items = () => Array.from(ctx.menu()?.querySelectorAll<HTMLElement>('[role="menuitem"]:not([aria-disabled="true"])') ?? []);
+  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 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 'Tab': ctx.setOpen(false, { returnFocus: false }); 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 (
-    <KDropdown.Portal mount={config.portalMount()}>
-      <KDropdown.Content class={cn('z-50 min-w-[8rem] rounded-lg bg-card p-1 shadow-lg animate-in fade-in-0 zoom-in-95', props.class)}>
-        {props.children}
-      </KDropdown.Content>
-    </KDropdown.Portal>
+    <Show when={presence.present()}>
+      <Portal mount={config.portalMount()}>
+        <div
+          ref={(el) => {
+            ctx.setMenu(el); presence.setRef(el);
+            // Keyboard-open focuses the first item. setOpen() also attempts this
+            // 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());
+            }
+          }}
+          id={ctx.menuId}
+          role="menu"
+          aria-labelledby={ctx.triggerId}
+          tabindex={-1}
+          data-expanded={presence.state() === 'open' ? '' : undefined}
+          data-closed={presence.state() === 'closed' ? '' : undefined}
+          onKeyDown={onKeyDown}
+          style={{ position: 'fixed', left: `${position.pos().x}px`, top: `${position.pos().y}px` }}
+          class={cn(
+            'z-50 min-w-[8rem] rounded-lg bg-card p-1 shadow-lg',
+            '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>
   );
 }
 
-export function DropdownItem(props: { children: JSX.Element; class?: string; onSelect?: () => void; }) {
+export function DropdownItem(props: { children: JSX.Element; class?: string; onSelect?: () => void }) {
+  const ctx = useDropdown();
+  const activate = () => { props.onSelect?.(); ctx.setOpen(false); };
   return (
-    <KDropdown.Item class={cn('flex cursor-pointer items-center rounded-md px-2 py-1.5 text-sm outline-none hover:bg-muted transition-colors', props.class)} onSelect={props.onSelect}>
+    <div
+      role="menuitem"
+      tabindex={-1}
+      onClick={activate}
+      onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); activate(); } }}
+      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',
+        props.class,
+      )}
+    >
       {props.children}
-    </KDropdown.Item>
+    </div>
   );
 }

package/src/ui/hover-card.tsx

@@ -1,48 +1,169 @@
-import { HoverCard as KHoverCard } from '@kobalte/core/hover-card';
-import { type JSX, splitProps } from 'solid-js';
+import {
+  createContext, useContext, createSignal, Show, splitProps, onCleanup,
+  type JSX, type Accessor,
+} from 'solid-js';
+import { Portal } from 'solid-js/web';
 import { cn } from '../utils/cn';
 import { useChatConfig } from '../primitives/chat-config';
+import { createPresence, usePosition, useDismiss, As } from './overlay';
 
-export interface HoverCardProps { trigger: JSX.Element; children: JSX.Element; class?: string; openDelay?: number; closeDelay?: number; }
-
-export function HoverCard(props: HoverCardProps) {
-  const [local] = splitProps(props, ['trigger', 'children', 'class', 'openDelay', 'closeDelay']);
-  const config = useChatConfig();
-  return (
-    <KHoverCard openDelay={local.openDelay} closeDelay={local.closeDelay}>
-      <KHoverCard.Trigger as="span">{local.trigger}</KHoverCard.Trigger>
-      <KHoverCard.Portal mount={config.portalMount()}>
-        <KHoverCard.Content class={cn('z-50 w-64 rounded-lg bg-card p-4 shadow-lg animate-in fade-in-0 zoom-in-95', local.class)}>
-          <KHoverCard.Arrow />
-          {local.children}
-        </KHoverCard.Content>
-      </KHoverCard.Portal>
-    </KHoverCard>
-  );
+interface HoverCardCtx {
+  open: Accessor<boolean>;
+  enter: () => void;
+  leave: () => void;
+  close: () => void;
+  setTrigger: (el: HTMLElement) => void;
+  setContent: (el: HTMLElement) => void;
+  trigger: Accessor<HTMLElement | undefined>;
+  content: Accessor<HTMLElement | undefined>;
 }
+const Ctx = createContext<HoverCardCtx>();
+const useHoverCard = () => {
+  const c = useContext(Ctx);
+  if (!c) throw new Error('HoverCard parts must be used within <HoverCardRoot>');
+  return c;
+};
 
-// Compound primitives for custom layouts (e.g. Source component)
 export interface HoverCardRootProps { children: JSX.Element; openDelay?: number; closeDelay?: number; }
 
 export function HoverCardRoot(props: HoverCardRootProps) {
-  return <KHoverCard openDelay={props.openDelay} closeDelay={props.closeDelay}>{props.children}</KHoverCard>;
+  const [open, setOpen] = createSignal(false);
+  const [trigger, setTrigger] = createSignal<HTMLElement>();
+  const [content, setContent] = createSignal<HTMLElement>();
+  let timer: number | undefined;
+
+  // ONE shared timer drives both trigger and content. Entering either cancels
+  // any pending close and schedules an open; leaving either cancels any pending
+  // open and schedules a close. Because the pointer transit trigger -> content
+  // fires leave() then enter() against the SAME timer, the close is cancelled
+  // before it can run, so the card never flickers and there are no stale-timer
+  // sporadics (the HC-1 fix).
+  const enter = () => {
+    clearTimeout(timer);
+    timer = window.setTimeout(() => setOpen(true), props.openDelay ?? 0);
+  };
+  const leave = () => {
+    clearTimeout(timer);
+    // closeDelay default is 300ms (Radix-style) as a belt-and-suspenders fallback
+    // for diagonal pointer escapes that miss the transparent safe bridge.
+    timer = window.setTimeout(() => setOpen(false), props.closeDelay ?? 300);
+  };
+  const close = () => { clearTimeout(timer); setOpen(false); };
+  onCleanup(() => clearTimeout(timer));
+
+  return (
+    <Ctx.Provider value={{
+      open, enter, leave, close,
+      setTrigger, setContent,
+      trigger, content,
+    }}>
+      {props.children}
+    </Ctx.Provider>
+  );
 }
 
 export interface HoverCardTriggerProps { children: JSX.Element; }
 
 export function HoverCardTrigger(props: HoverCardTriggerProps) {
-  return <KHoverCard.Trigger as="span">{props.children}</KHoverCard.Trigger>;
+  const ctx = useHoverCard();
+  return (
+    <As
+      as="span"
+      ref={ctx.setTrigger}
+      onPointerEnter={ctx.enter}
+      onPointerLeave={ctx.leave}
+      onFocusIn={ctx.enter}
+      onFocusOut={ctx.leave}
+    >
+      {props.children}
+    </As>
+  );
 }
 
 export interface HoverCardContentProps { children: JSX.Element; class?: string; }
 
+// Visual gap between trigger and the visible card. Also the depth of the
+// transparent safe bridge so the pointer never crosses "empty" space.
+const GUTTER = 8;
+
+/**
+ * Returns the CSS padding property that, set to `gutter`px on the OUTER floating
+ * shell, recreates the visual gap as a transparent safe area on the
+ * trigger-facing side. The outer shell is placed flush (gutter: 0) so the
+ * padding bridges the gap while keeping the inner card the same distance away.
+ *
+ * Placement strings from @floating-ui/dom (post flip/shift) may carry a
+ * '-start'/'-end' alignment suffix; we split on '-' and key on the side.
+ *   bottom* -> padding-top, top* -> padding-bottom,
+ *   left*   -> padding-right, right* -> padding-left
+ */
+function gapPaddingStyle(placement: string, gutter: number): JSX.CSSProperties {
+  const side = placement.split('-')[0];
+  const prop: Record<string, keyof JSX.CSSProperties> = {
+    bottom: 'padding-top',
+    top: 'padding-bottom',
+    left: 'padding-right',
+    right: 'padding-left',
+  };
+  return { [prop[side] ?? 'padding-top']: `${gutter}px` };
+}
+
 export function HoverCardContent(props: HoverCardContentProps) {
+  const ctx = useHoverCard();
   const config = useChatConfig();
+  const presence = createPresence(ctx.open);
+  // 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: 'bottom', gutter: 0 });
+  useDismiss({ enabled: ctx.open, onDismiss: (reason) => (reason === 'escape' ? ctx.close() : ctx.leave()), refs: () => [ctx.trigger(), ctx.content()] });
+
+  return (
+    <Show when={presence.present()}>
+      <Portal mount={config.portalMount()}>
+        {/* Outer shell: positioning + the transparent safe bridge + hot zone. */}
+        <div
+          ref={(el) => { ctx.setContent(el); presence.setRef(el); }}
+          data-hovercard-content
+          onPointerEnter={ctx.enter}
+          onPointerLeave={ctx.leave}
+          onFocusIn={ctx.enter}
+          onFocusOut={ctx.leave}
+          style={{
+            position: 'fixed',
+            left: `${position.pos().x}px`,
+            top: `${position.pos().y}px`,
+            background: 'transparent',
+            ...gapPaddingStyle(position.pos().placement, GUTTER),
+          }}
+          class="z-50"
+        >
+          {/* Inner card: all visual + animation classes and the presence state. */}
+          <div
+            data-expanded={presence.state() === 'open' ? '' : undefined}
+            data-closed={presence.state() === 'closed' ? '' : undefined}
+            class={cn(
+              'rounded-lg bg-card shadow-lg',
+              '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>
+        </div>
+      </Portal>
+    </Show>
+  );
+}
+
+export interface HoverCardProps { trigger: JSX.Element; children: JSX.Element; class?: string; openDelay?: number; closeDelay?: number; }
+
+export function HoverCard(props: HoverCardProps) {
+  const [local] = splitProps(props, ['trigger', 'children', 'class', 'openDelay', 'closeDelay']);
   return (
-    <KHoverCard.Portal mount={config.portalMount()}>
-      <KHoverCard.Content class={cn('z-50 rounded-lg bg-card shadow-lg animate-in fade-in-0 zoom-in-95', props.class)}>
-        {props.children}
-      </KHoverCard.Content>
-    </KHoverCard.Portal>
+    <HoverCardRoot openDelay={local.openDelay} closeDelay={local.closeDelay}>
+      <HoverCardTrigger>{local.trigger}</HoverCardTrigger>
+      <HoverCardContent class={cn('w-64 p-4', local.class)}>{local.children}</HoverCardContent>
+    </HoverCardRoot>
   );
 }