@kitn.ai/ui 0.14.1

package/src/ui/avatar.stories.tsx

@@ -0,0 +1,103 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { Avatar } from './avatar';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Primitives/Avatar',
+  component: Avatar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'A small, rounded **avatar** that renders an image when `src` is provided and falls back to short initials otherwise.',
+        '**When to use:** to identify the author of a message, a conversation participant, or the current user in a header or list.',
+        '**How to use:** always pass a `fallback` (1–2 initials) and a `size`. Provide `src`/`alt` when you have an image; if the image is missing or fails, the `fallback` text shows instead.',
+        '**Placement:** message rows (next to assistant/user content), conversation list items, account menus, and headers.',
+      ]),
+    },
+  },
+  argTypes: {
+    src: {
+      control: 'text',
+      description: 'Image URL. When omitted, the `fallback` initials are shown.',
+    },
+    alt: {
+      control: 'text',
+      description: 'Alt text for the image. Defaults to `fallback` when not set.',
+    },
+    fallback: {
+      control: 'text',
+      description: 'Initials shown when there is no image (required).',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Avatar diameter preset.',
+      table: { defaultValue: { summary: 'md' } },
+    },
+  },
+  args: {
+    fallback: 'JD',
+    size: 'md',
+  },
+  render: (args) => <Avatar {...args} />,
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Avatar } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — tweak the controls to explore image vs. fallback and sizes. */
+export const Playground: Story = {
+  ...src(`<Avatar fallback="JD" size="md" />`),
+};
+
+export const WithFallback: Story = {
+  args: { fallback: 'JD', size: 'md' },
+  ...src(`<Avatar fallback="JD" size="md" />`),
+};
+
+export const WithImage: Story = {
+  args: {
+    src: 'https://api.dicebear.com/7.x/initials/svg?seed=JD',
+    alt: 'John Doe',
+    fallback: 'JD',
+  },
+  ...src(`<Avatar
+  src="https://api.dicebear.com/7.x/initials/svg?seed=JD"
+  alt="John Doe"
+  fallback="JD"
+/>`),
+};
+
+export const Small: Story = {
+  args: { size: 'sm', fallback: 'S' },
+  ...src(`<Avatar size="sm" fallback="S" />`),
+};
+
+export const Large: Story = {
+  args: { size: 'lg', fallback: 'LG' },
+  ...src(`<Avatar size="lg" fallback="LG" />`),
+};
+
+/** Every size side by side (showcase — not driven by controls). */
+export const AllSizes: Story = {
+  render: () => (
+    <div class="flex items-center gap-3">
+      <Avatar size="sm" fallback="SM" />
+      <Avatar size="md" fallback="MD" />
+      <Avatar size="lg" fallback="LG" />
+    </div>
+  ),
+  ...src(`<div class="flex items-center gap-3">
+  <Avatar size="sm" fallback="SM" />
+  <Avatar size="md" fallback="MD" />
+  <Avatar size="lg" fallback="LG" />
+</div>`),
+};

package/src/ui/avatar.tsx

@@ -0,0 +1,23 @@
+import { type JSX, splitProps, Show } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface AvatarProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  src?: string;
+  alt?: string;
+  fallback: string;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+const sizeClasses = { sm: 'h-6 w-6 text-[10px]', md: 'h-8 w-8 text-xs', lg: 'h-10 w-10 text-sm' };
+
+export function Avatar(props: AvatarProps) {
+  const [local, rest] = splitProps(props, ['src', 'alt', 'fallback', 'size', 'class']);
+  const size = () => local.size ?? 'md';
+  return (
+    <div class={cn('inline-flex items-center justify-center rounded-md bg-accent font-semibold text-accent-foreground flex-shrink-0', sizeClasses[size()], local.class)} {...rest}>
+      <Show when={local.src} fallback={<span>{local.fallback}</span>}>
+        <img src={local.src} alt={local.alt ?? local.fallback} class="h-full w-full rounded-md object-cover" />
+      </Show>
+    </div>
+  );
+}

package/src/ui/badge.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { Badge } from './badge';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Primitives/Badge',
+  component: Badge,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'A compact pill **badge** for short status text, counts, or citation markers, rendered as an inline `<span>`.',
+        '**When to use:** to annotate a count (unread, results), tag a status/label, or mark an inline source citation in assistant output.',
+        '**How to use:** choose a `variant` (`default` label, `count` numeric pill, `citation` clickable source marker) and pass the text or number as children.',
+        '**Placement:** inline with message text (citations), next to titles or list items (labels), and on toolbar/icon buttons (counts).',
+      ]),
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'count', 'citation'],
+      description: 'Visual style: neutral label, numeric count pill, or clickable citation marker.',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    children: {
+      control: 'text',
+      description: 'Badge content — short text or a number.',
+    },
+  },
+  args: {
+    variant: 'default',
+    children: 'Default badge',
+  },
+  render: (args) => <Badge {...args} />,
+} satisfies Meta<typeof Badge>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Badge } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — switch the variant and edit the content. */
+export const Playground: Story = {
+  ...src(`<Badge variant="default">Default badge</Badge>`),
+};
+
+export const Default: Story = {
+  args: { variant: 'default', children: 'Default badge' },
+  ...src(`<Badge variant="default">Default badge</Badge>`),
+};
+
+export const Count: Story = {
+  args: { variant: 'count', children: '12' },
+  ...src(`<Badge variant="count">12</Badge>`),
+};
+
+export const Citation: Story = {
+  args: { variant: 'citation', children: '1' },
+  ...src(`<Badge variant="citation">1</Badge>`),
+};
+
+/** All variants side by side (showcase — not driven by controls). */
+export const AllVariants: Story = {
+  render: () => (
+    <div class="flex items-center gap-3">
+      <Badge variant="default">Default</Badge>
+      <Badge variant="count">5</Badge>
+      <Badge variant="citation">1</Badge>
+      <Badge variant="citation">2</Badge>
+      <Badge variant="citation">3</Badge>
+    </div>
+  ),
+  ...src(`<div class="flex items-center gap-3">
+  <Badge variant="default">Default</Badge>
+  <Badge variant="count">5</Badge>
+  <Badge variant="citation">1</Badge>
+  <Badge variant="citation">2</Badge>
+  <Badge variant="citation">3</Badge>
+</div>`),
+};

package/src/ui/badge.tsx

@@ -0,0 +1,21 @@
+import { type JSX, splitProps } from 'solid-js';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '../utils/cn';
+
+const badgeVariants = cva('inline-flex items-center justify-center rounded-full text-xs font-medium min-h-5 min-w-5', {
+  variants: {
+    variant: {
+      default: 'bg-muted text-muted-foreground px-2 py-0.5',
+      count: 'bg-muted text-muted-foreground h-5 px-1.5',
+      citation: 'bg-primary text-primary-foreground px-1.5 py-0.5 cursor-pointer',
+    },
+  },
+  defaultVariants: { variant: 'default' },
+});
+
+export interface BadgeProps extends JSX.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {}
+
+export function Badge(props: BadgeProps) {
+  const [local, rest] = splitProps(props, ['variant', 'class', 'children']);
+  return <span class={cn(badgeVariants({ variant: local.variant }), local.class)} {...rest}>{local.children}</span>;
+}

package/src/ui/button.stories.tsx

@@ -0,0 +1,145 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { fn } from 'storybook/test';
+import { Button } from './button';
+import { componentDescription } from '../stories/docs/element-controls';
+
+/**
+ * Convention exemplar — every component story should follow this shape:
+ * `component`, a description, `argTypes` (controls), `args` (defaults incl.
+ * `fn()` for events), a `Playground` story rendered from args, plus showcase
+ * stories for notable variations.
+ */
+const meta = {
+  title: 'Solid (Advanced)/Primitives/Button',
+  component: Button,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'A clickable button with style **variants** and **sizes**, built on a native `<button>` (all standard button attributes pass through).',
+        '**When to use:** any user-triggered action — submitting input, toolbar/icon actions, confirming or dismissing. Use `default` for the primary action, `ghost`/`outline` for secondary or low-emphasis actions.',
+        '**How to use:** set `variant` and `size`, pass label or an icon as children, and wire `onClick`. For icon-only buttons use `size="icon"` / `"icon-sm"` and include an `aria-label`.',
+        '**Placement:** prompt action bars, message action rows, dialogs, toolbars, and empty-state CTAs.',
+      ]),
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'ghost', 'outline'],
+      description: 'Visual emphasis of the button.',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'icon', 'icon-sm'],
+      description: 'Height/padding preset. `icon` / `icon-sm` are square for icon-only buttons.',
+      table: { defaultValue: { summary: 'md' } },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables interaction and dims the button.',
+    },
+    children: {
+      control: 'text',
+      description: 'Button content — text or an icon element.',
+    },
+    onClick: {
+      action: 'click',
+      description: 'Fired when the button is clicked.',
+      table: { category: 'Events' },
+    },
+  },
+  args: {
+    variant: 'default',
+    size: 'md',
+    disabled: false,
+    children: 'Click me',
+    onClick: fn(),
+  },
+  render: (args) => <Button {...args} />,
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Attach a clean, copy-paste-ready SolidJS snippet to a story. SolidJS stories
+ * can't auto-serialize an args-spread render (it shows `{}`), so we provide real
+ * usage code (with the import line, so it's truly paste-ready) that the docs
+ * "Show code" / "Copy code" buttons surface. `language: 'tsx'` labels it as SolidJS.
+ *
+ * Note: `Button` is a SolidJS *component* (a scoped import), not a global custom
+ * element, so the unprefixed name can't conflict with anything — alias on import
+ * if a host already has a `Button`. Only the web components (`<kai-chat>`, …)
+ * are prefixed, because those claim global custom-element tag names.
+ */
+const IMPORT = `import { Button } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — tweak the controls to explore every combination. */
+export const Playground: Story = {
+  ...src(`<Button variant="default" size="md" onClick={() => {}}>Click me</Button>`),
+};
+
+export const Ghost: Story = {
+  args: { variant: 'ghost', children: 'Ghost' },
+  ...src(`<Button variant="ghost">Ghost</Button>`),
+};
+
+export const Outline: Story = {
+  args: { variant: 'outline', children: 'Outline' },
+  ...src(`<Button variant="outline">Outline</Button>`),
+};
+
+export const Small: Story = {
+  args: { size: 'sm', children: 'Small' },
+  ...src(`<Button size="sm">Small</Button>`),
+};
+
+export const Large: Story = {
+  args: { size: 'lg', children: 'Large' },
+  ...src(`<Button size="lg">Large</Button>`),
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, children: 'Disabled' },
+  ...src(`<Button disabled>Disabled</Button>`),
+};
+
+const PlusIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+    <line x1="12" y1="5" x2="12" y2="19" />
+    <line x1="5" y1="12" x2="19" y2="12" />
+  </svg>
+);
+
+export const Icon: Story = {
+  args: { size: 'icon', children: <PlusIcon />, 'aria-label': 'Add' } as never,
+  ...src(`<Button size="icon" aria-label="Add">\n  <PlusIcon />\n</Button>`),
+};
+
+/** All variants and sizes side by side (showcase — not driven by controls). */
+export const AllVariants: Story = {
+  render: () => (
+    <div class="flex flex-wrap items-center gap-3">
+      <Button variant="default">Default</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="default" size="sm">Small</Button>
+      <Button variant="default" size="lg">Large</Button>
+      <Button variant="default" size="icon" aria-label="Add"><PlusIcon /></Button>
+    </div>
+  ),
+  ...src(`<div class="flex flex-wrap items-center gap-3">
+  <Button variant="default">Default</Button>
+  <Button variant="ghost">Ghost</Button>
+  <Button variant="outline">Outline</Button>
+  <Button size="sm">Small</Button>
+  <Button size="lg">Large</Button>
+  <Button size="icon" aria-label="Add"><PlusIcon /></Button>
+</div>`),
+};

package/src/ui/button.tsx

@@ -0,0 +1,38 @@
+import { type JSX, splitProps } from 'solid-js';
+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-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        ghost: 'hover:bg-muted text-foreground',
+        outline: 'bg-muted/50 text-foreground hover:bg-muted',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+      },
+      size: {
+        sm: 'h-8 px-3 text-xs rounded-md',
+        md: 'h-9 px-4 text-sm',
+        lg: 'h-10 px-6 text-sm',
+        icon: 'h-9 w-9',
+        'icon-sm': 'h-7 w-7',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'md' },
+  }
+);
+
+export interface ButtonProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}
+
+export function Button(props: ButtonProps) {
+  const [local, rest] = splitProps(props, ['variant', 'size', 'class', 'children']);
+  return (
+    <button class={cn(buttonVariants({ variant: local.variant, size: local.size }), local.class)} {...rest}>
+      {local.children}
+    </button>
+  );
+}
+
+export { buttonVariants };

package/src/ui/collapsible.stories.tsx

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from './collapsible';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Primitives/Collapsible',
+  component: Collapsible,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'A two-state disclosure that expands and collapses a region of content, animating height via a CSS `grid-template-rows` `0fr` → `1fr` transition (no JS measurement, no layout thrash). The trigger carries `aria-expanded`/`aria-controls` and the collapsed content is `inert`, so it is removed from tab order and the accessibility tree. Works controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`).',
+        '**When to use:** to hide secondary detail behind a toggle — a reasoning/"chain of thought" panel, a tool-call payload, an expandable conversation group, an FAQ row.',
+        '**How to use:** wrap `CollapsibleTrigger` and `CollapsibleContent` in a `Collapsible`. The trigger renders a `<button>` by default; pass `as` to render a custom element.',
+      ]),
+    },
+  },
+  render: () => <CollapsibleDemo defaultOpen />,
+} satisfies Meta<typeof Collapsible>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+function CollapsibleDemo(props: { defaultOpen?: boolean }) {
+  return (
+    <Collapsible defaultOpen={props.defaultOpen} class="w-80 rounded-lg border border-border">
+      <CollapsibleTrigger class="group flex w-full items-center justify-between px-3 py-2 text-sm font-medium text-foreground">
+        <span>Reasoning</span>
+        <svg
+          class="size-4 text-muted-foreground transition-transform duration-200 group-data-[expanded]:rotate-180"
+          viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
+        >
+          <polyline points="6 9 12 15 18 9" />
+        </svg>
+      </CollapsibleTrigger>
+      <CollapsibleContent>
+        <p class="px-3 pb-3 text-sm text-muted-foreground">
+          First I parsed the request, then checked the available tools, and finally
+          composed the answer. This panel is removed from the tab order while collapsed.
+        </p>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+/** Toggle the trigger to expand/collapse. The chevron rotates via the `data-expanded` attribute. */
+export const Playground: Story = {
+  ...src(`<Collapsible defaultOpen>
+  <CollapsibleTrigger>Reasoning</CollapsibleTrigger>
+  <CollapsibleContent>
+    <p>First I parsed the request, then checked the available tools…</p>
+  </CollapsibleContent>
+</Collapsible>`),
+};
+
+/** Starts collapsed. */
+export const InitiallyClosed: Story = {
+  render: () => <CollapsibleDemo />,
+  ...src(`<Collapsible>
+  <CollapsibleTrigger>Reasoning</CollapsibleTrigger>
+  <CollapsibleContent>…</CollapsibleContent>
+</Collapsible>`),
+};

package/src/ui/collapsible.tsx

@@ -0,0 +1,125 @@
+import {
+  createContext,
+  useContext,
+  createSignal,
+  createUniqueId,
+  splitProps,
+  type JSX,
+  type Accessor,
+} from 'solid-js';
+import { cn } from '../utils/cn';
+
+// 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; [k: string]: any }) {
+  const ctx = useCollapsible();
+  const [local, rest] = splitProps(props, ['children', 'class']);
+  return (
+    <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.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from './dropdown';
+import { buttonVariants } from './button';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Primitives/Dropdown',
+  component: Dropdown,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'An accessible menu that opens from a trigger, built on the kit\'s DIY overlay core (no third-party dependency). Implements the WAI-ARIA menu-button pattern: `aria-haspopup`/`aria-expanded` wiring, roving focus with Arrow/Home/End, type-ahead, Escape/outside-click dismissal, and focus return to the trigger. Portals into the active shadow root and resolves focus through `getRootNode()` so roving focus works inside web components.',
+        '**When to use:** for a list of *actions* or single-choice options triggered by a button — overflow "⋯" menus, model pickers, scope selectors. For hover-only context use `HoverCard`; for a label use `Tooltip`.',
+        '**How to use:** compose `Dropdown` › `DropdownTrigger` (the button) + `DropdownContent` › one `DropdownItem` per action. Give each item an `onSelect` handler — selecting also closes the menu.',
+      ]),
+    },
+  },
+  render: () => <DropdownDemo />,
+} satisfies Meta<typeof Dropdown>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+function DropdownDemo() {
+  const [last, setLast] = createSignal<string>();
+  return (
+    <div class="space-y-3">
+      <Dropdown>
+        <DropdownTrigger class={buttonVariants({ variant: 'outline' })}>Actions ▾</DropdownTrigger>
+        <DropdownContent>
+          <DropdownItem onSelect={() => setLast('Rename')}>Rename</DropdownItem>
+          <DropdownItem onSelect={() => setLast('Duplicate')}>Duplicate</DropdownItem>
+          <DropdownItem onSelect={() => setLast('Archive')}>Archive</DropdownItem>
+        </DropdownContent>
+      </Dropdown>
+      <p class="text-xs text-muted-foreground">Last selected: {last() ?? '—'}</p>
+    </div>
+  );
+}
+
+/** Click the trigger (or focus it and press ↓ / Enter) to open the menu; Arrow keys move, Escape closes. */
+export const Playground: Story = {
+  ...src(`<Dropdown>
+  <DropdownTrigger class={buttonVariants({ variant: 'outline' })}>Actions ▾</DropdownTrigger>
+  <DropdownContent>
+    <DropdownItem onSelect={() => rename()}>Rename</DropdownItem>
+    <DropdownItem onSelect={() => duplicate()}>Duplicate</DropdownItem>
+    <DropdownItem onSelect={() => archive()}>Archive</DropdownItem>
+  </DropdownContent>
+</Dropdown>`),
+};