@kitnai/chat 0.3.1 → 0.5.0

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.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { HoverCard } from './hover-card';
+import { Button } from './button';
+
+const meta = {
+  title: 'UI/HoverCard',
+  component: HoverCard,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: [
+          'A floating card that opens when its trigger is hovered or focused, built on the kit\'s DIY overlay core (positioning + dismiss + presence — no third-party dependency). Portals into the active shadow root so it never clips, and a transparent "safe bridge" keeps it open while the pointer travels from trigger to card.',
+          '**When to use:** to reveal supplementary, non-essential context on hover — a user/profile preview, a link or citation preview, an attachment summary. For an actionable menu use `Dropdown`; for a one-line label use `Tooltip`.',
+          '**How to use:** pass the trigger element as `trigger` and the card body as `children`. Tune `openDelay` / `closeDelay` (ms) to taste.',
+        ].join('\n\n'),
+      },
+    },
+  },
+  argTypes: {
+    trigger: { control: false, description: 'The element that opens the card on hover/focus.' },
+    children: { control: false, description: 'The card contents.' },
+    openDelay: { control: 'number', description: 'Delay (ms) before the card opens. Default 0.' },
+    closeDelay: { control: 'number', description: 'Delay (ms) before the card closes after the pointer leaves. Default 300.' },
+    class: { control: 'text', description: 'Extra classes applied to the card body.' },
+  },
+  args: {
+    trigger: <Button variant="outline">@ada</Button>,
+    children: (
+      <div class="flex gap-3">
+        <div class="flex size-10 shrink-0 items-center justify-center rounded-full bg-primary text-sm font-medium text-primary-foreground">AL</div>
+        <div class="space-y-1">
+          <p class="text-sm font-medium text-foreground">Ada Lovelace</p>
+          <p class="text-xs text-muted-foreground">Wrote the first algorithm intended for a machine. Joined in 1843.</p>
+        </div>
+      </div>
+    ),
+  },
+  render: (args) => <HoverCard {...args} />,
+} satisfies Meta<typeof HoverCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { HoverCard } from '@kitnai/chat';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Hover (or focus) the trigger to reveal a profile preview card. */
+export const Playground: Story = {
+  ...src(`<HoverCard trigger={<Button variant="outline">@ada</Button>}>
+  <ProfilePreview name="Ada Lovelace" />
+</HoverCard>`),
+};
+
+/** A link-preview card, the way it might appear inline in an assistant message. */
+export const LinkPreview: Story = {
+  render: () => (
+    <p class="max-w-md text-sm text-foreground">
+      See the{' '}
+      <HoverCard
+        trigger={<a href="#" class="font-medium text-primary underline underline-offset-2">MDN reference</a>}
+      >
+        <div class="space-y-1">
+          <p class="text-sm font-medium text-foreground">Custom elements — MDN</p>
+          <p class="text-xs text-muted-foreground">developer.mozilla.org</p>
+          <p class="text-xs text-muted-foreground">Define your own HTML elements with the CustomElementRegistry.</p>
+        </div>
+      </HoverCard>{' '}
+      for the full custom-elements API.
+    </p>
+  ),
+  ...src(`<HoverCard trigger={<a href="...">MDN reference</a>}>
+  <LinkCard title="Custom elements — MDN" host="developer.mozilla.org" />
+</HoverCard>`),
+};

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>
   );
 }

package/src/ui/overlay.stories.tsx

@@ -0,0 +1,115 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, Show } from 'solid-js';
+import { Portal } from 'solid-js/web';
+import { createPresence, usePosition, useDismiss } from './overlay';
+import { buttonVariants } from './button';
+
+/**
+ * `overlay.tsx` is not a component — it's the small DIY toolkit that every
+ * floating surface in the kit (Tooltip, HoverCard, Dropdown) is built from,
+ * replacing the former third-party UI dependency. Three primitives:
+ *
+ * - `usePosition(ref, floating, opts)` — anchors `floating` to `ref` via
+ *   @floating-ui/dom with flip/shift, tracking it on scroll/resize.
+ * - `createPresence(open)` — keeps a node mounted through its CSS exit
+ *   animation, then unmounts on `animationend`.
+ * - `useDismiss({ enabled, onDismiss, refs })` — Escape + outside-pointerdown
+ *   dismissal (no scroll lock).
+ *
+ * Plus an `As` polymorphic helper for trigger elements.
+ */
+const meta: Meta = {
+  title: 'UI/Overlay Core',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: [
+          "The shared, dependency-free foundation behind every floating surface in the kit — `Tooltip`, `HoverCard`, and `Dropdown` are all assembled from these primitives. It's a toolkit of hooks, not a renderable component.",
+          '**`usePosition(ref, floating, opts)`** anchors a floating node to a trigger via `@floating-ui/dom` (flip/shift, fixed strategy, tracks on scroll/resize). **`createPresence(open)`** keeps the node mounted through its CSS exit animation. **`useDismiss({ enabled, onDismiss, refs })`** handles Escape + outside-click. An **`As`** helper renders a polymorphic trigger.',
+          '**When to use:** only when you need a floating surface the prebuilt components don\'t cover. Reach for `Tooltip` / `HoverCard` / `Dropdown` first — they already wire these together with the correct ARIA and focus behavior.',
+          'The demo below composes all three into a minimal popover; everything portals into the active shadow root via `ChatConfig`.',
+        ].join('\n\n'),
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function PopoverDemo() {
+  const [open, setOpen] = createSignal(false);
+  const [trigger, setTrigger] = createSignal<HTMLElement>();
+  const [content, setContent] = createSignal<HTMLElement>();
+  const presence = createPresence(open);
+  const position = usePosition(trigger, content, { placement: 'bottom-start', gutter: 6 });
+  useDismiss({ enabled: open, onDismiss: () => setOpen(false), refs: () => [trigger(), content()] });
+
+  return (
+    <>
+      <button
+        ref={setTrigger}
+        type="button"
+        class={buttonVariants({ variant: 'outline' })}
+        onClick={() => setOpen(!open())}
+      >
+        {open() ? 'Close' : 'Open'} popover
+      </button>
+      <Show when={presence.present()}>
+        <Portal>
+          <div
+            ref={(el) => { setContent(el); presence.setRef(el); }}
+            data-expanded={presence.state() === 'open' ? '' : undefined}
+            data-closed={presence.state() === 'closed' ? '' : undefined}
+            style={{ position: 'fixed', left: `${position.pos().x}px`, top: `${position.pos().y}px` }}
+            class="z-50 w-64 rounded-lg bg-card p-3 text-sm text-foreground shadow-lg animate-in fade-in-0 zoom-in-95 data-[closed]:animate-out data-[closed]:fade-out-0 data-[closed]:zoom-out-95"
+          >
+            Positioned by <code class="text-xs">usePosition</code>, kept mounted through its
+            exit animation by <code class="text-xs">createPresence</code>, and closed on
+            Escape / outside-click by <code class="text-xs">useDismiss</code>.
+          </div>
+        </Portal>
+      </Show>
+    </>
+  );
+}
+
+/** A minimal popover hand-built from the three overlay primitives. Click to toggle; click outside or press Escape to dismiss. */
+export const MinimalPopover: Story = {
+  render: () => <PopoverDemo />,
+  parameters: {
+    docs: {
+      source: {
+        code: `import { createPresence, usePosition, useDismiss } from '@kitnai/chat';
+
+function PopoverDemo() {
+  const [open, setOpen] = createSignal(false);
+  const [trigger, setTrigger] = createSignal<HTMLElement>();
+  const [content, setContent] = createSignal<HTMLElement>();
+  const presence = createPresence(open);
+  const position = usePosition(trigger, content, { placement: 'bottom-start', gutter: 6 });
+  useDismiss({ enabled: open, onDismiss: () => setOpen(false), refs: () => [trigger(), content()] });
+
+  return (
+    <>
+      <button ref={setTrigger} onClick={() => setOpen(!open())}>Toggle</button>
+      <Show when={presence.present()}>
+        <Portal>
+          <div
+            ref={(el) => { setContent(el); presence.setRef(el); }}
+            style={{ position: 'fixed', left: \`\${position.pos().x}px\`, top: \`\${position.pos().y}px\` }}
+          >
+            …content…
+          </div>
+        </Portal>
+      </Show>
+    </>
+  );
+}`,
+        language: 'tsx',
+      },
+    },
+  },
+};