@kitn.ai/ui 0.17.0 → 0.18.0

package/src/elements/menu.tsx

@@ -0,0 +1,217 @@
+import { For, Show } from 'solid-js';
+import { MoreHorizontal } from 'lucide-solid';
+import {
+  Dropdown, DropdownTrigger, DropdownContent, DropdownItem,
+  DropdownSeparator, DropdownLabel, DropdownCheckboxItem, DropdownRadioItem,
+  DropdownSub, DropdownSubTrigger, DropdownSubContent,
+  type DropdownController,
+} from '../ui/dropdown';
+import { renderIcon } from '../ui/icon';
+import { Kbd } from '../ui/kbd';
+import { cn } from '../utils/cn';
+import { defineWebComponent } from './define';
+import { wireDisclosure } from './disclosure';
+
+export interface KaiMenuItem {
+  /** Emitted in `kai-select` for actionable items. */
+  id?: string;
+  label?: string;
+  /** Named icon (e.g. "paperclip"), image URL / data-URI, or plain text. */
+  icon?: string;
+  /** e.g. '⌘U' — shown right-aligned, muted. */
+  shortcut?: string;
+  /** Presence ⇒ a checkbox item (role=menuitemcheckbox). With `radioGroup` set,
+   *  marks the SELECTED radio item in that group instead. */
+  checked?: boolean;
+  /** Membership in a single-select group (role=menuitemradio). Items sharing a
+   *  `radioGroup` are mutually exclusive — the one with `checked: true` shows the
+   *  checkmark; selecting one emits `{ id, radioGroup }` so the consumer moves
+   *  the checkmark (the consumer owns state, like checkbox items). */
+  radioGroup?: string;
+  disabled?: boolean;
+  /** A divider (ignores other fields). */
+  separator?: boolean;
+  /** A non-interactive section label (uses `label`). */
+  heading?: boolean;
+  /** ⇒ a submenu. */
+  items?: KaiMenuItem[];
+}
+
+interface Props extends Record<string, unknown> {
+  /** Tree of menu items. Set as a JS property — not an HTML attribute. */
+  items?: KaiMenuItem[];
+  /** Optional placement hint (unused by the underlying Dropdown which always
+   *  positions bottom-start, kept for future extension). */
+  placement?: string;
+  /** Built-in trigger: leading icon (a named icon like `"plus"`, an image
+   *  URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for
+   *  the common case — a slotted trigger overrides it. */
+  triggerIcon?: string;
+  /** Built-in trigger: a text label (e.g. `"High"`). */
+  triggerLabel?: string;
+  /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
+  triggerIconTrailing?: string;
+  /** Accessible name for an icon-only trigger (no visible label). */
+  label?: string;
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute, the menu still self-manages on click/keyboard). Set `el.open = true`,
+   *  or `<kai-menu open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Disable the trigger — click/keyboard and `show()` no longer open the menu. */
+  disabled?: boolean;
+}
+
+interface Events {
+  /**
+   * Fired when the user selects a leaf item.
+   * - Plain items: `{ id }`.
+   * - Checkbox items: `{ id, checked }` where `checked` is the NEW state.
+   * - Radio items: `{ id, radioGroup }` — the consumer marks `id` as the selected
+   *   one in `radioGroup` and clears the others.
+   */
+  'kai-select': { id: string; checked?: boolean; radioGroup?: string };
+  /** The menu opened or closed (by click, keyboard, Escape, outside-click, or a method). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-menu>` — a cascading action menu driven by a JSON items-tree.
+ *
+ * Set the `items` property in JavaScript (array, not attribute). The trigger
+ * is slotted — put your icon/button content in `slot="trigger"`:
+ *
+ * ```html
+ * <kai-menu>
+ *   <button slot="trigger" aria-label="Open menu">+</button>
+ * </kai-menu>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const menu = document.querySelector('kai-menu');
+ *   menu.items = [
+ *     { heading: true, label: 'Actions' },
+ *     { id: 'attach', label: 'Add files', icon: 'paperclip', shortcut: 'Mod+U' },
+ *   ];
+ *   menu.addEventListener('kai-select', (e) => console.log(e.detail));
+ * </script>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-menu', {
+  items: undefined,
+  placement: undefined,
+  triggerIcon: undefined,
+  triggerLabel: undefined,
+  triggerIconTrailing: undefined,
+  label: undefined,
+  open: undefined,
+  defaultOpen: undefined,
+  disabled: undefined,
+}, (props, ctx) => {
+  const { dispatch, flag } = ctx;
+  let api: DropdownController | undefined;
+
+  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle, disabled-gating. See ./disclosure.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  function renderItems(items: KaiMenuItem[]) {
+    return (
+      <For each={items}>
+        {(item) => {
+          if (item.separator) {
+            return <DropdownSeparator />;
+          }
+          if (item.heading) {
+            return <DropdownLabel>{item.label}</DropdownLabel>;
+          }
+          if (item.items && item.items.length > 0) {
+            return (
+              <DropdownSub>
+                <DropdownSubTrigger>
+                  <Show when={item.icon}>{renderIcon(item.icon, { imgClass: 'mr-2 size-4 shrink-0', spanClass: 'mr-2 flex h-4 w-4 shrink-0 items-center justify-center text-sm' })}</Show>
+                  {item.label}
+                </DropdownSubTrigger>
+                <DropdownSubContent>
+                  {renderItems(item.items)}
+                </DropdownSubContent>
+              </DropdownSub>
+            );
+          }
+          if (item.radioGroup !== undefined) {
+            return (
+              <DropdownRadioItem
+                checked={item.checked}
+                disabled={item.disabled}
+                onSelect={() => {
+                  if (item.id) dispatch('kai-select', { id: item.id, radioGroup: item.radioGroup });
+                }}
+              >
+                <Show when={item.icon}>{renderIcon(item.icon, { imgClass: 'mr-2 size-4 shrink-0', spanClass: 'mr-2 flex h-4 w-4 shrink-0 items-center justify-center text-sm' })}</Show>
+                {item.label}
+              </DropdownRadioItem>
+            );
+          }
+          if (item.checked !== undefined) {
+            return (
+              <DropdownCheckboxItem
+                checked={item.checked}
+                disabled={item.disabled}
+                onSelect={() => {
+                  if (item.id) dispatch('kai-select', { id: item.id, checked: !item.checked });
+                }}
+              >
+                <Show when={item.icon}>{renderIcon(item.icon, { imgClass: 'mr-2 size-4 shrink-0', spanClass: 'mr-2 flex h-4 w-4 shrink-0 items-center justify-center text-sm' })}</Show>
+                {item.label}
+              </DropdownCheckboxItem>
+            );
+          }
+          return (
+            <DropdownItem
+              disabled={item.disabled}
+              onSelect={() => { if (item.id) dispatch('kai-select', { id: item.id }); }}
+            >
+              <Show when={item.icon}>{renderIcon(item.icon, { imgClass: 'mr-2 size-4 shrink-0', spanClass: 'mr-2 flex h-4 w-4 shrink-0 items-center justify-center text-sm' })}</Show>
+              {item.label}
+              <Show when={item.shortcut}>
+                <span part="shortcut" class="ml-auto pl-4 text-muted-foreground">
+                  <Kbd keys={item.shortcut!} platform="auto" size="sm" />
+                </span>
+              </Show>
+            </DropdownItem>
+          );
+        }}
+      </For>
+    );
+  }
+
+  return (
+    <Dropdown
+      defaultOpen={flag('defaultOpen')}
+      disabled={flag('disabled')}
+      controllerRef={(a) => (api = a)}
+    >
+      <DropdownTrigger
+        class={cn(
+          'inline-flex items-center rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          props.triggerLabel
+            ? 'gap-1.5 px-2 py-1.5 text-sm font-medium text-muted-foreground hover:bg-accent hover:text-foreground'
+            : 'justify-center p-1.5 text-foreground hover:bg-muted',
+        )}
+        aria-label={props.label ?? (props.triggerLabel ? undefined : 'Open menu')}
+      >
+        {/* Slotted trigger wins; otherwise build one from the trigger* props;
+            otherwise fall back to a "more" glyph. */}
+        <slot name="trigger">
+          <Show when={props.triggerIcon}>{renderIcon(props.triggerIcon, { class: 'size-4 shrink-0' })}</Show>
+          <Show when={props.triggerLabel}>{props.triggerLabel}</Show>
+          <Show when={props.triggerIconTrailing}>{renderIcon(props.triggerIconTrailing, { class: 'size-3.5 shrink-0 opacity-60' })}</Show>
+          <Show when={!props.triggerIcon && !props.triggerLabel}><MoreHorizontal class="size-4" /></Show>
+        </slot>
+      </DropdownTrigger>
+      <DropdownContent class="min-w-[15rem]">
+        {renderItems((props.items as KaiMenuItem[] | undefined) ?? [])}
+      </DropdownContent>
+    </Dropdown>
+  );
+});

package/src/elements/message.tsx

@@ -1,5 +1,6 @@
 import { Show, createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
+import { readSlots, MESSAGE_SLOTS } from './slots';
 import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
 import { Message, MessageAvatar, MessageBody } from '../components/message';
 import { createMessageFeedback } from '../primitives/message-feedback';
@@ -27,6 +28,11 @@ interface Props extends Record<string, unknown> {
   avatarSrc?: string;
   /** Convenience avatar fallback text (used when `message.avatar` is not set). */
   avatarFallback?: string;
+  /** Avatar rail mode. `'none'` omits the avatar rail entirely so the body spans
+   *  the full row (predictable layout when you never show avatars). Any other
+   *  value keeps the default behaviour: the built-in avatar when one resolves, or
+   *  your `slot="avatar"` content when projected (which REPLACES the built-in). */
+  avatar?: 'none' | string;
 }
 
 /** Events fired by `<kai-message>`. */
@@ -54,7 +60,8 @@ defineWebComponent<Props, Events>('kai-message', {
   actionsReveal: 'always',
   avatarSrc: undefined,
   avatarFallback: undefined,
-}, (props, { dispatch, flag, element }) => {
+  avatar: undefined,
+}, (props, { dispatch, flag, element, expose }) => {
   const outer = useChatConfig();
   const msg = (): ChatMessage =>
     props.message ?? { id: 'message', role: props.role ?? 'assistant', content: props.content ?? '' };
@@ -62,12 +69,27 @@ defineWebComponent<Props, Events>('kai-message', {
   // re-render when the host swaps in a fresh `message` object during streaming.
   const feedback = createMessageFeedback({
     emit: (detail) => dispatch('kai-message-action', detail),
-    target: () => element,
+    // No `target`: a STANDALONE <kai-message> must not anchor its copy/feedback
+    // toast to the individual message (that lands mid-thread in a compose-your-own
+    // list). Let them route to the global region (top of the viewport), which is
+    // where a confirmation belongs across a hand-built thread. (Inside <kai-chat>
+    // the chat owns feedback and targets ITSELF, so in-chat toasts still stay in-chat.)
+  });
+
+  // Imperative method API — `copy()` runs the exact path of the built-in copy
+  // action (`feedback.handleAction(msg, 'copy')`): writes the content to the
+  // clipboard, shows the transient copied-check on the bar, and emits
+  // `kai-message-action{action:'copy'}`.
+  expose({
+    /** Copy the message content to the clipboard and show the copied check. */
+    copy: () => feedback.handleAction(msg(), 'copy'),
   });
 
   // Read declarative <kai-action> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
   const [slottedActions, setSlottedActions] = createSignal<import('../elements/chat-types').CustomAction[]>([]);
+  // Which composition slots (before-body / after-body / avatar) the consumer filled.
+  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
   onMount(() => {
     const read = () => {
       const nodes = [...element.querySelectorAll('kai-action')];
@@ -77,6 +99,7 @@ defineWebComponent<Props, Events>('kai-message', {
         icon: n.getAttribute('icon') ?? undefined,
         tooltip: n.getAttribute('tooltip') ?? undefined,
       })));
+      setSlots(readSlots(element, MESSAGE_SLOTS));
     };
     read();
     const observer = new MutationObserver(read);
@@ -89,6 +112,12 @@ defineWebComponent<Props, Events>('kai-message', {
     (props.avatarSrc || props.avatarFallback
       ? { src: props.avatarSrc as string | undefined, fallback: props.avatarFallback as string | undefined }
       : undefined);
+  // Avatar rail state. `avatar="none"` omits the rail; a filled `slot="avatar"`
+  // REPLACES the built-in; otherwise the built-in renders when one resolves.
+  const noAvatar = () => props.avatar === 'none';
+  const hasAvatarSlot = () => !!slots()['avatar'];
+  // The rail shows when not suppressed and there's either a slot or a resolved avatar.
+  const showRail = () => !noAvatar() && (hasAvatarSlot() || !!avatar());
   const reveal = () => (props.actionsReveal === 'hover' ? 'hover' : 'always');
   // markdown: explicit prop/attribute wins; otherwise default by role.
   const markdownExplicit = () =>
@@ -109,12 +138,32 @@ defineWebComponent<Props, Events>('kai-message', {
       activeFeedback={feedback.resolveFeedback(msg())}
       copied={feedback.isCopied(msg().id)}
       onAction={(action) => feedback.handleAction(msg(), action)}
+      beforeBody={slots()['before-body'] ? <slot name="before-body" /> : undefined}
+      afterBody={slots()['after-body'] ? <slot name="after-body" /> : undefined}
     />
   );
 
   // Row carries `group` so a hover-revealed action bar fades in on row hover.
   const rowGroup = () => (reveal() === 'hover' ? 'group ' : '');
 
+  // The avatar rail: a filled `slot="avatar"` REPLACES the built-in MessageAvatar
+  // (the consumer owns that node, wrapped in `part="avatar"` so it's still
+  // styleable + consistent with the built-in part name).
+  const avatarRail = () => (
+    <Show
+      when={hasAvatarSlot()}
+      fallback={
+        <Show when={avatar()}>
+          {(av) => <MessageAvatar src={av().src ?? ''} alt={av().alt ?? ''} fallback={av().fallback} />}
+        </Show>
+      }
+    >
+      <div part="avatar" class="shrink-0">
+        <slot name="avatar" />
+      </div>
+    </Show>
+  );
+
   return (
     <ChatConfig
       proseSize={props.proseSize}
@@ -123,21 +172,19 @@ defineWebComponent<Props, Events>('kai-message', {
       portalMount={outer.portalMount()}
     >
       <Show
-        when={avatar()}
+        when={showRail()}
         fallback={
           <Message class={`${rowGroup()}${isUser() ? 'flex-col items-end' : 'flex-col items-start'}`}>
             {body()}
           </Message>
         }
       >
-        {(av) => (
-          <Message class={rowGroup()}>
-            <MessageAvatar src={av().src ?? ''} alt={av().alt ?? ''} fallback={av().fallback} />
-            <div class={`flex min-w-0 flex-1 flex-col ${isUser() ? 'items-end' : 'items-start'}`}>
-              {body()}
-            </div>
-          </Message>
-        )}
+        <Message class={rowGroup()}>
+          {avatarRail()}
+          <div class={`flex min-w-0 flex-1 flex-col ${isUser() ? 'items-end' : 'items-start'}`}>
+            {body()}
+          </div>
+        </Message>
       </Show>
     </ChatConfig>
   );

package/src/elements/model-switcher.tsx

@@ -1,6 +1,8 @@
 import { createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
 import { ModelSwitcher } from '../components/model-switcher';
+import { wireDisclosure } from './disclosure';
+import type { DropdownController } from '../ui/dropdown';
 import type { ModelOption } from '../types';
 
 interface Props extends Record<string, unknown> {
@@ -8,12 +10,22 @@ interface Props extends Record<string, unknown> {
   models: ModelOption[];
   /** The currently-selected model id. Defaults to the first model. */
   currentModel?: string;
+  /** Drive/observe the dropdown's open state (Shoelace-style: settable + reflected
+   *  to the `open` attribute, the dropdown still self-manages on click/keyboard).
+   *  Set `el.open = true`, or `<kai-model-switcher open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Disable the trigger — click/keyboard and `show()` no longer open the dropdown. */
+  disabled?: boolean;
 }
 
 /** Events fired by `<kai-model-switcher>`. */
 interface Events {
   /** A model was selected. */
   'kai-model-change': { modelId: string };
+  /** The model dropdown opened or closed (by click, keyboard, Escape, outside-click, or a method). */
+  'kai-open-change': { open: boolean };
 }
 
 /**
@@ -65,7 +77,18 @@ export function parseKaiModelElement(n: Element): ModelOption {
 defineWebComponent<Props, Events>('kai-model-switcher', {
   models: [],
   currentModel: undefined,
-}, (props, { dispatch, element }) => {
+  open: undefined,
+  defaultOpen: undefined,
+  disabled: undefined,
+}, (props, ctx) => {
+  const { dispatch, element, flag } = ctx;
+  let api: DropdownController | undefined;
+
+  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle, disabled-gating. See ./disclosure. When <=1 model the inner
+  // Dropdown never mounts, so `api` stays undefined and these methods no-op.
+  wireDisclosure(ctx, () => api, () => props.open);
+
   // Read declarative <kai-model> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
   const [slottedModels, setSlottedModels] = createSignal<ModelOption[]>([]);
@@ -88,6 +111,9 @@ defineWebComponent<Props, Events>('kai-model-switcher', {
       models={allModels()}
       currentModelId={props.currentModel ?? allModels()[0]?.id ?? ''}
       onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
+      defaultOpen={flag('defaultOpen')}
+      disabled={flag('disabled')}
+      controllerRef={(a) => (api = a)}
     />
   );
 });

package/src/elements/nav.tsx

@@ -0,0 +1,87 @@
+import { createSignal } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Nav, type KaiNavItem } from '../ui/nav';
+
+interface Props extends Record<string, unknown> {
+  /** The nav items. Set as a JS property (array, not an attribute). Each item may
+   *  carry `children` (a collapsible group), a `status` dot, and trailing `meta`
+   *  text. */
+  items?: KaiNavItem[];
+  /** Active item id (controlled). */
+  value?: string;
+  /** Initial active id when uncontrolled. */
+  defaultValue?: string;
+  /** Ids of group items collapsed on first render (groups default to expanded).
+   *  Set as a JS property (array). */
+  defaultCollapsed?: string[];
+}
+
+interface Events {
+  /** A nav item was activated. */
+  'kai-nav-select': { id: string };
+  /** A row's trailing `action` button was activated (not a select). `value` is
+   *  the item id; `action` echoes the item's `{ icon, label }`. */
+  'kai-nav-item-action': { value: string; action?: { icon: string; label: string } };
+  /** A `closable` row's trailing close button was activated (not a select).
+   *  `value` is the item id. */
+  'kai-nav-item-close': { value: string };
+}
+
+/**
+ * `<kai-nav>` — a vertical navigation list driven by a JSON `items` tree
+ * (id + label + optional leading `icon`, a trailing text `badge`, a trailing
+ * icon). Items may nest via `children` (a collapsible group with a disclosure
+ * chevron), carry a `status` dot (`{ tone, label?, pulse? }`), and a trailing
+ * `meta` string (e.g. a relative time). The active item is `value`; selecting a
+ * leaf fires `kai-nav-select` (group rows toggle expand/collapse instead).
+ *
+ * Items may also carry an `action` (`{ icon, label }`) or `closable: true`, which
+ * render a trailing button — firing `kai-nav-item-action` `{ value, action }` or
+ * `kai-nav-item-close` `{ value }` (never `kai-nav-select`). Style it via
+ * `::part(item-action)`.
+ *
+ * ```html
+ * <kai-nav default-value="home"></kai-nav>
+ * <script type="module">
+ *   const nav = document.querySelector('kai-nav');
+ *   nav.items = [
+ *     { id: 'home', label: 'New task', icon: 'plus', trailing: 'pencil' },
+ *     { id: 'acme', label: 'Acme', icon: 'folder', children: [
+ *       { id: 't1', label: 'Refactor auth', status: { tone: 'info', label: 'Working', pulse: true }, meta: '2m' },
+ *       { id: 't2', label: 'Landing page', status: { tone: 'success', label: 'Done' }, meta: '1d' },
+ *     ] },
+ *     { id: 'dispatch', label: 'Dispatch', icon: 'share', badge: 'Beta' },
+ *   ];
+ *   nav.addEventListener('kai-nav-select', (e) => console.log(e.detail.id));
+ * </script>
+ * ```
+ * Restyle via `::part(nav)` / `::part(item)` (active items carry `aria-current`),
+ * plus `::part(group)` / `::part(chevron)` / `::part(status)` / `::part(meta)`.
+ */
+defineWebComponent<Props, Events>('kai-nav', {
+  items: undefined,
+  value: undefined,
+  defaultValue: undefined,
+  defaultCollapsed: undefined,
+}, (props, { dispatch, expose }) => {
+  const [internal, setInternal] = createSignal(props.defaultValue as string | undefined);
+  const value = () => (props.value as string | undefined) ?? internal();
+  const select = (id: string) => { setInternal(id); dispatch('kai-nav-select', { id }); };
+
+  expose({
+    /** Activate an item by id (fires kai-nav-select). */
+    select: (id: string) => select(id),
+  });
+
+  return (
+    <Nav
+      items={props.items as KaiNavItem[] | undefined}
+      value={value()}
+      defaultCollapsed={props.defaultCollapsed as string[] | undefined}
+      onItemSelect={select}
+      onItemAction={(id, action) => dispatch('kai-nav-item-action', { value: id, action })}
+      onItemClose={(id) => dispatch('kai-nav-item-close', { value: id })}
+      part="nav"
+    />
+  );
+});

package/src/elements/notice.tsx

@@ -0,0 +1,53 @@
+import { Notice, noticeIconNode } from '../ui/notice';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** `neutral` (default) · `info` · `warning` · `error` · `success`. Drives the
+   *  leading icon's color and the a11y role (`alert` for errors, else `status`). */
+  severity?: 'neutral' | 'info' | 'warning' | 'error' | 'success';
+  /** Leading icon: omit for the severity default, `"none"` to hide it, or a named
+   *  icon to override. */
+  icon?: string;
+  /** Show a dismiss (×) that hides the notice and emits `kai-dismiss`. */
+  dismissible?: boolean;
+}
+
+/** Events fired by `<kai-notice>`. */
+interface Events {
+  /** The notice was dismissed via its × (it also hides itself). */
+  'kai-dismiss': void;
+}
+
+/**
+ * `<kai-notice>` — a self-contained inline notice / alert. Put the message as
+ * light-DOM text and an optional `slot="action"` (e.g. a link); it carries the
+ * severity icon, the right a11y role, and an optional self-dismissing ×.
+ *
+ * It owns the notice box, not its placement — you position it in your own layout
+ * (above a composer, at the top of a panel, …).
+ *
+ * For a custom leading icon, slot any inline SVG via `slot="icon"` (it wins over
+ * the severity/`icon` default — the same escape hatch as `kai-button`).
+ *
+ * ```html
+ * <kai-notice severity="warning" dismissible>
+ *   Claude Fable 5 is currently unavailable.
+ *   <a slot="action" href="#">Learn more</a>
+ * </kai-notice>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-notice', {
+  severity: 'neutral',
+  icon: undefined,
+  dismissible: false,
+}, (props, { dispatch, flag }) => (
+  <Notice
+    severity={props.severity ?? 'neutral'}
+    iconSlot={<slot name="icon">{noticeIconNode(props.severity ?? 'neutral', props.icon)}</slot>}
+    dismissible={flag('dismissible')}
+    onDismiss={() => dispatch('kai-dismiss')}
+    action={<slot name="action" />}
+  >
+    <slot />
+  </Notice>
+));

package/src/elements/pane-group.tsx

@@ -0,0 +1,119 @@
+import { createSignal, createEffect, Show } from 'solid-js';
+import { defineWebComponent } from './define';
+import { PaneGroup, type PaneTab } from '../ui/pane-group';
+
+interface Props extends Record<string, unknown> {
+  /** The tabs to render. An array of `{ id, name, status?, needsAttention?, number? }`
+   *  set as a JS PROPERTY (not an HTML attribute). */
+  tabs?: PaneTab[];
+  /** The active tab id (controlled, and reflected to the `active` ATTRIBUTE so
+   *  `::part`/`[active]` selectors and the per-tab named slot follow it). Set it as
+   *  the `active` attribute or drive it from `kai-tab-change`; omit for uncontrolled
+   *  (the first tab). */
+  active?: string;
+  /** Highlight the frame as the ACTIVE group in a multi-group layout. Attribute:
+   *  `focused`. */
+  focused?: boolean;
+}
+
+/** Events fired by `<kai-pane-group>`. All non-bubbling — listen on the element. */
+interface Events {
+  /** A tab was selected (click, Enter/Space, or arrow-key move). `detail.id` is
+   *  the tab's id. */
+  'kai-tab-change': { id: string };
+  /** A tab's close (×) was clicked. Drop the tab from `tabs` yourself. */
+  'kai-tab-close': { id: string };
+  /** A tab's "…" overflow was clicked. Open your own menu from `detail.id`. */
+  'kai-tab-menu': { id: string };
+}
+
+/**
+ * `<kai-pane-group>` — an editor group: a TAB STRIP (numbered-status-badge tabs)
+ * over the active tab's pane content. The reusable "one column = a group of agents
+ * shown as tabs" primitive from the Multi-Agent Workspace. Composable: a `tabs`
+ * property + slots + parts + events, not a config blob — the group owns the tab UX,
+ * you own the pane content.
+ *
+ * Each tab leads with a tone-colored NUMBERED BADGE (color = status, digit = the
+ * keyboard ⌥-jump number), then the name, the status word (on the active tab / on
+ * hover / always for needs-attention), a "…" overflow, and a close "×".
+ *
+ * Set the `tabs` property in JavaScript (array, not attribute):
+ *
+ * ```html
+ * <kai-pane-group active="atlas">
+ *   <!-- one named slot per tab id; the group shows the active one -->
+ *   <div slot="atlas">…Atlas pane…</div>
+ *   <div slot="otto">…Otto pane…</div>
+ * </kai-pane-group>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const group = document.querySelector('kai-pane-group');
+ *   group.tabs = [
+ *     { id: 'atlas', name: 'Atlas', status: { tone: 'working', label: 'Running', pulse: true } },
+ *     { id: 'otto',  name: 'Otto',  status: { tone: 'blocked', label: 'Needs input' }, needsAttention: true },
+ *   ];
+ *   group.addEventListener('kai-tab-change', (e) => console.log(e.detail.id));
+ * </script>
+ * ```
+ *
+ * Pane content — TWO composable patterns:
+ *  - NAMED SLOT PER TAB: give each pane `slot="<tab id>"`; the group projects the
+ *    active tab's slot and swaps it itself on selection (no consumer JS needed).
+ *  - DEFAULT SLOT: put one body in the default slot and swap it yourself in
+ *    response to `kai-tab-change`. Both work; pick whichever fits.
+ *
+ * Methods: `el.select(id)` selects a tab (fires `kai-tab-change`); `el.focus()`
+ * focuses the active tab. Parts: `::part(tabs|tab|body)` (also `::part(menu|close)`).
+ */
+defineWebComponent<Props, Events>('kai-pane-group', {
+  tabs: undefined,
+  active: undefined,
+  focused: false,
+}, (props, { element, dispatch, flag, expose }) => {
+  const tabs = () => (props.tabs as PaneTab[] | undefined) ?? [];
+  // Controlled/uncontrolled: the `active` prop/attribute wins; otherwise the
+  // element manages its own, falling back to the first tab. `change` always writes
+  // the internal value AND emits `kai-tab-change` so a controlling app can react.
+  const [internal, setInternal] = createSignal<string | undefined>(props.active as string | undefined);
+  const active = () => (props.active as string | undefined) ?? internal() ?? tabs()[0]?.id;
+  const change = (id: string) => {
+    setInternal(id);
+    dispatch('kai-tab-change', { id });
+  };
+
+  // Reflect the resolved active id to the `active` attribute so `[active="…"]` /
+  // `::part` selectors and the consumer's per-tab named slot follow selection.
+  // Writing the same value is idempotent, so no feedback loop with the prop.
+  createEffect(() => {
+    const a = active();
+    if (a != null) element.setAttribute('active', a);
+  });
+
+  expose({
+    /** Select a tab by id (fires `kai-tab-change`). Ignores unknown ids. */
+    select: (id: string) => {
+      if (tabs().some((t) => t.id === id)) change(id);
+    },
+    /** Focus the active tab in the strip. */
+    focus: () => {
+      element.shadowRoot?.querySelector<HTMLElement>('[part="tab"][tabindex="0"]')?.focus();
+    },
+  });
+
+  return (
+    <PaneGroup
+      tabs={tabs()}
+      active={active()}
+      focused={flag('focused')}
+      onTabChange={change}
+      onTabClose={(id) => dispatch('kai-tab-close', { id })}
+      onTabMenu={(id) => dispatch('kai-tab-menu', { id })}
+    >
+      {/* Active tab's content: the per-tab named slot, plus the default slot for the
+          swap-it-yourself pattern. A consumer uses one or the other. */}
+      <Show when={active()}>{(a) => <slot name={a()} />}</Show>
+      <slot />
+    </PaneGroup>
+  );
+});