@kitn.ai/ui 0.17.0 → 0.18.0

package/src/elements/prompt-suggestions.tsx

@@ -2,7 +2,7 @@ import { For, createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import { PromptSuggestion } from '../components/prompt-suggestion';
 
-type Item = string | { label: string; value?: string };
+type Item = string | { label: string; value?: string; icon?: string };
 
 interface Props extends Record<string, unknown> {
   /** The suggestions. Strings, or `{ label, value }` when the displayed text
@@ -10,9 +10,13 @@ interface Props extends Record<string, unknown> {
   suggestions: Item[];
   /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
   variant?: 'outline' | 'ghost' | 'default';
-  /** Size preset for each chip. Defaults to the pill default (`'lg'`); pass
-   *  `'sm'` for smaller pills (or `'md'`). */
-  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+  /** Row height for `layout="list"`: `'md'` (default) or `'lg'` for taller rows.
+   *  Chips are unaffected. */
+  size?: 'md' | 'lg';
+  /** Layout: `'chips'` (default) renders a wrapping row of rounded pills;
+   *  `'list'` renders a vertical, full-width "Ideas for you" list — each row
+   *  is left-aligned with a leading `icon`, a label, and a hover background. */
+  layout?: 'chips' | 'list';
   /** Full-width left-aligned rows instead of pills. */
   block?: boolean;
   /** Substring to highlight within each suggestion. */
@@ -27,18 +31,20 @@ interface Events {
 
 const labelOf = (s: Item) => (typeof s === 'string' ? s : s.label);
 const valueOf = (s: Item) => (typeof s === 'string' ? s : s.value ?? s.label);
+const iconOf = (s: Item) => (typeof s === 'string' ? undefined : s.icon);
 
 /** Parse a single `<kai-suggestion>` node into an `Item` descriptor. */
 export function parseSuggestionNode(n: Element): Item {
   const text = n.textContent?.trim() ?? '';
   const value = n.getAttribute('value') ?? text;
-  return { label: text, value };
+  return { label: text, value, icon: n.getAttribute('icon') ?? undefined };
 }
 
 /**
  * `<kai-suggestions>` — a row/list of suggestion chips. Data via the
- * `suggestions` property; `variant`/`block`/`highlight` attributes; emits
- * `select`.
+ * `suggestions` property; `variant`/`layout`/`block`/`highlight` attributes;
+ * emits `select`. `layout="list"` renders the vertical "Ideas for you" list
+ * (leading icon + label + hover background) instead of pills.
  *
  * Alternatively, declare chips as `<kai-suggestion>` child elements
  * (light-DOM data carriers — hidden by the Shadow DOM):
@@ -53,7 +59,8 @@ export function parseSuggestionNode(n: Element): Item {
 defineWebComponent<Props, Events>('kai-suggestions', {
   suggestions: [],
   variant: 'outline',
-  size: undefined,
+  size: 'md',
+  layout: 'chips',
   block: false,
   highlight: undefined,
 }, (props, { dispatch, flag, element }) => {
@@ -74,14 +81,23 @@ defineWebComponent<Props, Events>('kai-suggestions', {
   // Merge prop suggestions (first) with declarative children (after).
   const allSuggestions = () => [...(props.suggestions ?? []), ...slottedSuggestions()];
 
+  const isList = () => props.layout === 'list';
+
+  const containerClass = () =>
+    isList() ? 'flex flex-col gap-0.5'
+      : flag('block') ? 'flex flex-col gap-2'
+        : 'flex flex-wrap gap-2';
+
   return (
-    <div class={flag('block') ? 'flex flex-col gap-2' : 'flex flex-wrap gap-2'}>
+    <div class={containerClass()}>
       <For each={allSuggestions()}>
         {(s) => (
           <PromptSuggestion
             variant={props.variant}
             size={props.size}
+            icon={iconOf(s)}
             block={flag('block')}
+            list={isList()}
             highlight={props.highlight}
             onClick={() => dispatch('kai-select', { value: valueOf(s) })}
           >

package/src/elements/reasoning.tsx

@@ -1,46 +1,67 @@
 import { defineWebComponent } from './define';
-import { Reasoning, ReasoningTrigger, ReasoningContent } from '../components/reasoning';
+import { Reasoning, ReasoningTrigger, ReasoningContent, type ReasoningController } from '../components/reasoning';
 import { ChatConfig, useChatConfig } from '../primitives/chat-config';
+import { wireDisclosure } from './disclosure';
 
 interface Props extends Record<string, unknown> {
   /** The reasoning text to display. */
   text: string;
   /** Trigger label. */
   label?: string;
-  /** Controlled open state — set as a property (`el.open = true`). Omit for
-   *  uncontrolled (the trigger toggles it). */
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute; the element still self-manages on trigger click + while
+   *  streaming). Set `el.open = true`; listen for `kai-open-change`. */
   open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
   /** While true, auto-expands (and re-collapses when it flips false). */
   streaming?: boolean;
   /** Render `text` as markdown. */
   markdown?: boolean;
+  /** Gate the disclosure trigger — programmatic `show()/hide()/toggle()` still
+   *  work, but the trigger click no longer toggles. */
+  disabled?: boolean;
 }
 
 /** Events fired by `<kai-reasoning>`. */
 interface Events {
-  /** Open state changed (via the trigger or streaming auto-open). */
+  /** The reasoning block expanded or collapsed (via the trigger, streaming
+   *  auto-open, or a method). */
   'kai-open-change': { open: boolean };
 }
 
 /**
  * `<kai-reasoning>` — a collapsible reasoning/thinking block that auto-expands
- * while `streaming`. Text via the `text` property; `markdown`/`streaming` flags;
- * `open` is a controlled property; emits `kai-open-change`.
+ * while `streaming`. Text via the `text` property; `markdown`/`streaming` flags.
+ * Open state is the standard disclosure surface: settable+reflecting `open`,
+ * `kai-open-change`, and `show()`/`hide()`/`toggle()` (gated by `disabled`);
+ * seed with `defaultOpen`.
  */
 defineWebComponent<Props, Events>('kai-reasoning', {
   text: '',
   label: 'Reasoning',
   open: undefined,
+  defaultOpen: undefined,
   streaming: false,
   markdown: true,
-}, (props, { dispatch, flag }) => {
+  disabled: undefined,
+}, (props, ctx) => {
+  const { flag } = ctx;
   const outer = useChatConfig();
+  let api: ReasoningController | undefined;
+
+  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle, disabled-gating. See ./disclosure. This is the SOLE emitter
+  // of kai-open-change — we no longer dispatch it from Reasoning's onOpenChange.
+  wireDisclosure(ctx, () => api, () => props.open);
+
   return (
     <ChatConfig portalMount={outer.portalMount()}>
       <Reasoning
-        open={props.open}
+        defaultOpen={flag('defaultOpen')}
         isStreaming={flag('streaming')}
-        onOpenChange={(open) => dispatch('kai-open-change', { open })}
+        disabled={flag('disabled')}
+        controllerRef={(a) => (api = a)}
       >
         <ReasoningTrigger>{props.label}</ReasoningTrigger>
         <ReasoningContent markdown={flag('markdown')}>{props.text}</ReasoningContent>

package/src/elements/register-impl.ts

@@ -22,9 +22,6 @@ import './context-meter';
 import './feedback-bar';
 import './chat-scope-picker';
 // Phase 3 — input ecosystem
-// (NB: SlashCommand is context-bound to PromptInput — it observes the input
-//  value via usePromptInput() — so it is NOT a standalone element. It will fold
-//  into <kai-prompt-input> as a `slash-commands` property in a later pass.)
 import './prompt-suggestions';
 import './file-upload';
 import './voice-input';
@@ -37,6 +34,13 @@ import './message-skills';
 import './source';
 import './response-stream';
 import './empty';
+import './status';
+import './nav';
+import './progress-bar';
+import './coachmark';
+import './tabs';
+import './voice-output';
+import './screen';
 import './chain-of-thought';
 import './resizable';
 import './file-tree';
@@ -44,6 +48,16 @@ import './artifact';
 import './scroll-button';
 import './popover';
 import './switch';
+import './button';
+import './avatar';
+import './badge';
+import './tooltip';
+import './notice';
+import './icon';
+import './separator';
+import './scroll-area';
+import './hover-card';
+import './skeleton';
 import './toast';
 // Generative-UI cards (Card Contract)
 import './card';
@@ -56,3 +70,24 @@ import './choice';
 import './cards';
 // Dual-response comparison (preference capture)
 import './compare';
+// Rich text composer with entity pills, trigger menus, and keyword highlighting
+import './composer';
+// W3 phase 2: cascading action menu from a JSON items-tree
+import './menu';
+// W4 phase 1: grouped filterable command/mention palette
+import './command';
+// Prompt dock + settings building blocks (graduated from SolidJS prototypes)
+import './prompt-dock';
+import './segmented';
+import './settings-group';
+import './setting-item';
+// Multi-agent workspace primitives (graduated from SolidJS prototypes)
+import './pane';
+import './pane-group';
+import './agent-card';
+import './dialog';
+// Input & search field family
+import './input';
+import './search';
+import './kbd';
+import './editable-label';

package/src/elements/register.ts

@@ -13,9 +13,17 @@
 // Registration is async (a microtask after this module loads). Consumers that
 // need the upgraded element (e.g. the React runtime) guard with
 // customElements.whenDefined(), which resolves once the impl chunk has run.
-if (typeof window !== 'undefined' && typeof customElements !== 'undefined') {
-  void import('./register-impl');
-}
+/** Resolves once the kai-* elements are registered (browser); inert on the server.
+ *  Await this instead of customElements.whenDefined for a single ready signal.
+ *
+ *  NOTE: this MUST stay an exported binding. A bare `void import('./register-impl')`
+ *  is a result-unused dynamic import that the single-entry register-all build
+ *  (vite.config.ts → dist/kai.es.js) tree-shakes away as dead code, leaving the
+ *  bundle with NOTHING registered. Exporting the promise keeps the import live. */
+export const elementsReady: Promise<unknown> =
+  typeof window !== 'undefined' && typeof customElements !== 'undefined'
+    ? import('./register-impl')
+    : Promise.resolve();
 
 export type { ChatMessage, ChatMessageAction } from './chat-types';
 export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';

package/src/elements/resizable.tsx

@@ -1,6 +1,6 @@
 import { createSignal, createEffect, on, onMount, onCleanup, For, Show, type JSX } from 'solid-js';
 import { defineWebComponent } from './define';
-import { ResizableHandle, normalizeSize } from '../ui/resizable';
+import { ResizableHandle, normalizeSize, clampBasis } from '../ui/resizable';
 
 type Orientation = 'horizontal' | 'vertical';
 
@@ -34,6 +34,7 @@ interface ItemInfo {
   max?: string;
   locked: boolean;
   hidden: boolean;
+  collapsed: boolean;
 }
 
 /** Max number of panels a single group lays out (nest for more). */
@@ -100,6 +101,13 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         el.setAttribute('data-kai-default-size', el.getAttribute('size') ?? '');
       }
       const defaultSize = el.getAttribute('data-kai-default-size') || undefined;
+      // The `collapsed` boolean prop is reflected to a `collapsed` attribute by the
+      // item facade (see kai-resizable-item), so reading the attribute here works
+      // at INITIAL render from any framework — unlike the bare `hidden` boolean,
+      // whose JSX form sets neither the attribute nor the IDL property on a custom
+      // element. Treated as hidden-for-layout, independently of `hidden` so the
+      // back-compat hidden path (and maximize, which drives `hidden`) is untouched.
+      const collapsed = el.hasAttribute('collapsed') && el.getAttribute('collapsed') !== 'false';
       return {
         el,
         size: el.getAttribute('size') ?? undefined,
@@ -111,14 +119,15 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         // (and direct `el.hidden = true`) set the property, which doesn't reflect
         // to the attribute on a custom element.
         hidden: el.hidden || (el.hasAttribute('hidden') && el.getAttribute('hidden') !== 'false'),
+        collapsed,
       };
     });
 
     // Assign each visible item to its panel slot by visible order; clear the
-    // rest so hidden/extra items don't leak into a slot.
+    // rest so hidden/extra/collapsed items don't leak into a slot.
     let visIdx = 0;
     for (const info of parsed) {
-      if (info.hidden) {
+      if (info.hidden || info.collapsed) {
         info.el.removeAttribute('slot');
       } else {
         info.el.setAttribute('slot', `p${visIdx}`);
@@ -153,12 +162,12 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
       const b = next[i];
       if (a.el !== b.el) return true;
       if (a.size !== b.size || a.min !== b.min || a.max !== b.max) return true;
-      if (a.locked !== b.locked || a.hidden !== b.hidden) return true;
+      if (a.locked !== b.locked || a.hidden !== b.hidden || a.collapsed !== b.collapsed) return true;
     }
     return false;
   }
 
-  const visible = () => items().filter((i) => !i.hidden);
+  const visible = () => items().filter((i) => !i.hidden && !i.collapsed);
 
   /** Compute current panel sizes (percent of container) from the rendered DOM. */
   function currentSizes(): number[] {
@@ -358,9 +367,11 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         // maximized item is still present and visible.
         const maximizedEl = stash.item;
         const isConnected = maximizedEl.isConnected && element.contains(maximizedEl);
-        const isVisible = isConnected && !(maximizedEl.hidden || maximizedEl.hasAttribute('hidden'));
+        const isVisible = isConnected
+          && !(maximizedEl.hidden || maximizedEl.hasAttribute('hidden'))
+          && !(maximizedEl.hasAttribute('collapsed') && maximizedEl.getAttribute('collapsed') !== 'false');
         if (!isConnected || !isVisible) {
-          // The maximized item was removed or hidden out from under us → restore.
+          // The maximized item was removed or hidden/collapsed out from under us → restore.
           restore();
           return;
         }
@@ -375,7 +386,7 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
       // the host's own attributes.
       subtree: true,
       attributes: true,
-      attributeFilter: ['size', 'locked', 'min', 'max', 'hidden'],
+      attributeFilter: ['size', 'locked', 'min', 'max', 'hidden', 'collapsed'],
     });
     onCleanup(() => {
       mo.disconnect();
@@ -432,7 +443,9 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
           const min = boundAttrs(info.min);
           const max = boundAttrs(info.max);
           const def = boundAttrs(info.defaultSize);
-          const basis = normalizeSize(info.size);
+          // Clamp the INITIAL basis into [min, max] so a % size on a wide
+          // container never paints past a px max and then snaps on first drag.
+          const basis = clampBasis(normalizeSize(info.size), normalizeSize(info.min), normalizeSize(info.max));
           const prev = () => visible()[i() - 1];
           const isStatic = () => !!(info.locked || prev()?.locked);
           return (
@@ -514,6 +527,16 @@ interface ItemProps extends Record<string, unknown> {
   locked?: boolean;
   /** Hide this panel; its divider is dropped and the rest reflow. */
   hidden?: boolean;
+  /**
+   * Collapse this panel — same layout effect as `hidden` (divider dropped, the
+   * rest reflow), but it WORKS as a bare boolean from framework JSX. A plain
+   * `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel
+   * at the first render; `hidden` does not, because a JSX boolean sets neither the
+   * `hidden` attribute nor the IDL property on a custom element, so the parent never
+   * sees it. The facade reflects `collapsed` to a `collapsed` attribute the parent
+   * reads. Prefer this over `hidden` for declarative collapse.
+   */
+  collapsed?: boolean;
 }
 
 /**
@@ -527,7 +550,20 @@ defineWebComponent<ItemProps>('kai-resizable-item', {
   max: undefined,
   locked: false,
   hidden: false,
-}, () => (
+  collapsed: false,
+}, (_props, { element, flag }) => {
+  // Reflect the reactive `collapsed` prop to the `collapsed` ATTRIBUTE the parent
+  // <kai-resizable> reads (and observes). This is what makes a bare JSX boolean
+  // collapse the panel at INITIAL render from any framework: component-register
+  // parses `<kai-resizable-item collapsed>` to `undefined` (not `true`), and a JSX
+  // boolean sets neither `hidden` nor the IDL property — so `flag('collapsed')`
+  // (which also honours the attribute) is the reliable source, and toggleAttribute
+  // mirrors it back so the parent's readItems()/MutationObserver lay it out. Same
+  // pattern as <kai-chat>'s `loading` reflection. We touch only `collapsed`, never
+  // `hidden`, so the back-compat hidden path and maximize (which drive `hidden`)
+  // are untouched.
+  createEffect(() => { element.toggleAttribute('collapsed', flag('collapsed')); });
+  return (
   <>
     {/* The item host fills the panel's single grid cell (the panel stretches it on
         both axes) and OWNS the scroll: `display:block; width/height:100%;
@@ -550,4 +586,5 @@ defineWebComponent<ItemProps>('kai-resizable-item', {
       <slot />
     </div>
   </>
-) as unknown as JSX.Element);
+  ) as unknown as JSX.Element;
+});

package/src/elements/screen.tsx

@@ -0,0 +1,90 @@
+import { defineWebComponent } from './define';
+import { Screen, type ScreenController } from '../components/screen';
+import { wireDisclosure } from './disclosure';
+
+interface Props extends Record<string, unknown> {
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute; the element still self-manages). Set `el.open = true`, or
+   *  `<kai-screen open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Header title text. A projected `title` slot overrides it. (Named `headline`
+   *  because `title` collides with the global `HTMLElement.title` attribute.) */
+  headline?: string;
+  /** Show the back button (default true). */
+  back?: boolean;
+  /** Opt out of marking sibling elements inert/aria-hidden while open (for unusual layouts). */
+  noInert?: boolean;
+}
+
+/** Events fired by `<kai-screen>`. */
+interface Events {
+  /** Back navigation intent: the back button or Escape. The consumer flips their
+   *  own routing in response (the screen knows nothing about the trigger). */
+  'kai-back': Record<string, never>;
+  /** The screen opened or closed (a method, `Escape` close, or driven `open`). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-screen>` is a developer-swapped, full-bleed overlay destination: the
+ * push/drill-in surface that takes over its mount point under a back-header. The
+ * developer owns the swap (their own routing flips `open` in response to their
+ * trigger button and the screen's `kai-back`); the screen owns being the takeover.
+ *
+ * It fills whatever it is mounted in (mount at the app root for a full takeover,
+ * in a positioned region for a scoped one), marks sibling elements `inert` while
+ * open (the standard modal pattern; opt out with `no-inert`), moves focus in on
+ * open and restores it on close, and runs an enter/exit transition that honors
+ * `prefers-reduced-motion`. `Escape` fires `kai-back`.
+ *
+ * ```html
+ * <kai-screen headline="Design">
+ *   <button slot="actions"><kai-avatar></kai-avatar></button>
+ *   <div>…your surface…</div>
+ * </kai-screen>
+ * ```
+ *
+ * Open state is the standard disclosure surface: settable+reflecting `open`,
+ * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`.
+ * Parts: `header` · `back` · `title` · `body`.
+ */
+defineWebComponent<Props, Events>('kai-screen', {
+  open: undefined,
+  defaultOpen: undefined,
+  headline: undefined,
+  back: undefined,
+  noInert: undefined,
+}, (props, ctx) => {
+  const { flag, element, dispatch, expose } = ctx;
+  let api: ScreenController | undefined;
+  let surface: HTMLElement | undefined;
+
+  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle. See ./disclosure. This is the SOLE emitter of kai-open-change.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  // focus() shadows the host's native focus so it targets the screen surface
+  // inside the shadow root (the WebAwesome/Shoelace convention).
+  expose({
+    /** Move focus to the screen surface (no-op while closed). */
+    focus: (options?: FocusOptions) => surface?.focus(options),
+  });
+
+  return (
+    <Screen
+      defaultOpen={flag('defaultOpen')}
+      back={!(props.back === false || element.getAttribute('back') === 'false')}
+      noInert={flag('noInert')}
+      host={() => element}
+      titleSlot={<slot name="title">{props.headline as string | undefined}</slot>}
+      actions={<slot name="actions" />}
+      onBack={() => { dispatch('kai-back', {}); }}
+      controllerRef={(a) => (api = a)}
+      surfaceRef={(el) => (surface = el)}
+    >
+      <slot />
+    </Screen>
+  );
+});

package/src/elements/scroll-area.tsx

@@ -0,0 +1,33 @@
+import { ScrollArea, type ScrollOrientation } from '../ui/scroll-area';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Which axis scrolls. `vertical` (default) · `horizontal` · `both`. The cross
+   *  axis is clamped so content can't overflow it. */
+  orientation?: ScrollOrientation;
+}
+
+/**
+ * `<kai-scroll-area>` — a scroll container with a themed, thin, cross-browser
+ * scrollbar and a keyboard-reachable region. Project the scrollable content as
+ * light-DOM children and give the element a bounded size in your layout; the
+ * content then scrolls inside. Use `orientation` to pick the axis. Restyle the
+ * container via `::part(viewport)`; the scrollbar follows the
+ * `--color-scrollbar-thumb` token.
+ *
+ * ```html
+ * <kai-scroll-area style="height: 16rem">…long content…</kai-scroll-area>
+ * <kai-scroll-area orientation="horizontal" style="max-width: 24rem">…wide row…</kai-scroll-area>
+ * ```
+ */
+defineWebComponent<Props>('kai-scroll-area', {
+  orientation: 'vertical',
+}, (props) => (
+  <>
+    {/* The element is a block box; the consumer sets its size, the viewport fills it. */}
+    <style>{':host{display:block;min-height:0}'}</style>
+    <ScrollArea class="h-full max-h-full w-full max-w-full" part="viewport" orientation={props.orientation as ScrollOrientation}>
+      <slot />
+    </ScrollArea>
+  </>
+));