@kitn.ai/ui 0.16.0 → 0.18.0

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

package/src/elements/pane.tsx

@@ -0,0 +1,129 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Pane, type PaneStatus } from '../ui/pane';
+
+interface Props extends Record<string, unknown> {
+  /** The pane title (the agent / window name). Named `headline` because `title`
+   *  collides with the global `HTMLElement.title` attribute (it throws at
+   *  registration). Attribute: `headline`. */
+  headline?: string;
+  /** A role / label shown under the title (e.g. "Reviewer", "claude-sonnet").
+   *  Attribute: `subtitle`. */
+  subtitle?: string;
+  /** Show the restore glyph instead of maximize, and signal the maximized
+   *  view-state. Drive it yourself in response to `kai-maximize`. Attribute:
+   *  `maximized`. */
+  maximized?: boolean;
+  /** Highlight the frame with a ring/border to mark the ACTIVE pane. Attribute:
+   *  `focused`. */
+  focused?: boolean;
+  /** Show a split-pane window control that fires `kai-split`. Off by default.
+   *  Attribute: `show-split`. */
+  showSplit?: boolean;
+  /** Show a dock-to-side window control that fires `kai-dock`. Off by default.
+   *  Attribute: `show-dock`. */
+  showDock?: boolean;
+  /** A tone-colored status dot (+ optional label) in the header. An object
+   *  `{ tone, label?, pulse? }` set as a JS PROPERTY (not an attribute). */
+  status?: PaneStatus;
+}
+
+/** Events fired by `<kai-pane>`. All non-bubbling — listen on the element. */
+interface Events {
+  /** The maximize/restore control was clicked. `detail.maximized` is the
+   *  intended NEXT state — drive the `maximized` prop yourself from it. */
+  'kai-maximize': { maximized: boolean };
+  /** The close (×) control was clicked. */
+  'kai-close': void;
+  /** The split control was clicked (only present when `show-split`). */
+  'kai-split': void;
+  /** The dock control was clicked (only present when `show-dock`). */
+  'kai-dock': void;
+}
+
+/** Named slots whose occupancy gates a header/footer region. An empty `<slot>`
+ *  is always a truthy node, so the facade tracks which are actually filled and
+ *  only passes those regions to the primitive (no stray glyph slot / footer
+ *  divider when unfilled). */
+const SLOT_NAMES = ['leading', 'actions', 'footer'] as const;
+type SlotName = (typeof SLOT_NAMES)[number];
+
+/**
+ * `<kai-pane>` — a framed panel for a multi-agent workspace: a header (leading
+ * glyph + title/subtitle + status dot + extra actions + window controls), a
+ * scrolling body, and an optional pinned footer (e.g. a composer). Composable:
+ * slots + parts + events, not a config blob.
+ *
+ * Slots: `leading` (header glyph/avatar), `actions` (extra header controls,
+ * placed before the window controls), the DEFAULT slot (body), `footer`.
+ *
+ * Window controls (right of the header): maximize/restore and close are always
+ * present; split and dock appear only with `show-split` / `show-dock`. Each
+ * fires a `kai-*` event so the consumer drives state itself (uncontrolled-
+ * friendly): listen for `kai-maximize` and set `maximized` from
+ * `event.detail.maximized`.
+ *
+ * Parts: `::part(header|body|footer|controls)`.
+ *
+ * ```html
+ * <kai-pane headline="Reviewer" subtitle="claude-sonnet" focused show-split
+ *           onkai-maximize="this.maximized = event.detail.maximized">
+ *   <img slot="leading" src="…" alt="" />
+ *   <kai-button slot="actions" variant="ghost">Retry</kai-button>
+ *   <kai-message-thread>…</kai-message-thread>
+ *   <kai-prompt-input slot="footer"></kai-prompt-input>
+ * </kai-pane>
+ * <script>
+ *   const pane = document.querySelector('kai-pane');
+ *   pane.status = { tone: 'working', label: 'Running tests…', pulse: true };
+ * </script>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-pane', {
+  headline: '',
+  subtitle: undefined,
+  maximized: false,
+  focused: false,
+  showSplit: false,
+  showDock: false,
+  status: undefined,
+}, (props, { element, dispatch, flag }) => {
+  // Track which named slots are filled. Re-read on child mutations so streamed/
+  // late content lights up its region. An unfilled region is never rendered.
+  const [filled, setFilled] = createSignal<Record<SlotName, boolean>>({
+    leading: false, actions: false, footer: false,
+  });
+
+  onMount(() => {
+    const read = () => {
+      const next = {} as Record<SlotName, boolean>;
+      for (const name of SLOT_NAMES) next[name] = !!element.querySelector(`:scope > [slot="${name}"]`);
+      setFilled(next);
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, subtree: true, attributes: true, attributeFilter: ['slot'] });
+    onCleanup(() => observer.disconnect());
+  });
+
+  const region = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
+
+  return (
+    <Pane
+      title={props.headline as string}
+      subtitle={props.subtitle as string | undefined}
+      status={props.status as PaneStatus | undefined}
+      focused={flag('focused')}
+      maximized={flag('maximized')}
+      leading={region('leading')}
+      actions={region('actions')}
+      footer={region('footer')}
+      onMaximize={() => dispatch('kai-maximize', { maximized: !flag('maximized') })}
+      onClose={() => dispatch('kai-close')}
+      onSplit={flag('showSplit') ? () => dispatch('kai-split') : undefined}
+      onDock={flag('showDock') ? () => dispatch('kai-dock') : undefined}
+    >
+      <slot />
+    </Pane>
+  );
+});

package/src/elements/popover.tsx

@@ -1,5 +1,6 @@
 import { defineWebComponent } from './define';
-import { Popover } from '../ui/popover';
+import { Popover, type PopoverController } from '../ui/popover';
+import { wireDisclosure } from './disclosure';
 import type { Placement } from '@floating-ui/dom';
 
 interface Props extends Record<string, unknown> {
@@ -7,14 +8,20 @@ interface Props extends Record<string, unknown> {
   placement?: Placement;
   /** Gap in px between the trigger and the panel. */
   gutter?: number;
-  /** Controlled open state. Set as a JS property (`el.open = true`) to drive the
-   *  popover from your app; omit for the default click-to-toggle behaviour. */
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute, the element still self-manages on click). Set `el.open = true`,
+   *  or `<kai-popover open>`; listen for `kai-open-change`. */
   open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Turn the popover off while keeping the trigger mounted (clicks and `show()`
+   *  no longer open it). */
+  disabled?: boolean;
 }
 
 /** Events fired by `<kai-popover>`. */
 interface Events {
-  /** The popover wants to open or close (click, Escape, or outside-click). */
+  /** The popover opened or closed (click, Escape, outside-click, or a method). */
   'kai-open-change': { open: boolean };
 }
 
@@ -39,21 +46,36 @@ interface Events {
  * The default slot is the panel; the `trigger` slot is the control. Clicking the
  * trigger toggles the panel; Escape or an outside click closes it (clicks inside
  * the panel do not). It fires `kai-open-change` with `{ open }` on every change,
- * and accepts an `open` JS property for controlled use.
+ * accepts an `open`/`defaultOpen` JS property, can be `disabled`, and exposes
+ * `show()`/`hide()`/`toggle()` instance methods.
  */
 defineWebComponent<Props, Events>('kai-popover', {
   placement: 'bottom-start',
   gutter: 6,
   open: undefined,
-}, (props, { dispatch, element }) => (
-  <Popover
-    trigger={<slot name="trigger" />}
-    placement={props.placement as Placement}
-    gutter={props.gutter}
-    open={props.open}
-    boundary={() => element}
-    onOpenChange={(open) => dispatch('kai-open-change', { open })}
-  >
-    <slot />
-  </Popover>
-));
+  defaultOpen: undefined,
+  disabled: undefined,
+}, (props, ctx) => {
+  const { flag, element } = ctx;
+  let api: PopoverController | undefined;
+
+  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle, disabled-gating. The sole source of kai-open-change — the
+  // primitive's onOpenChange is intentionally NOT wired here to avoid a double
+  // dispatch. See ./disclosure.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  return (
+    <Popover
+      trigger={<slot name="trigger" />}
+      placement={props.placement as Placement}
+      gutter={props.gutter}
+      defaultOpen={flag('defaultOpen')}
+      disabled={flag('disabled')}
+      controllerRef={(a) => (api = a)}
+      boundary={() => element}
+    >
+      <slot />
+    </Popover>
+  );
+});

package/src/elements/progress-bar.tsx

@@ -0,0 +1,39 @@
+import { ProgressBar, type ProgressTone } from '../ui/progress-bar';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Current progress value (0..max). Attribute: `value`. */
+  value?: number;
+  /** The value `value` runs to (default 100). Attribute: `max`. */
+  max?: number;
+  /** Optional caption above the track. Attribute: `label`. */
+  label?: string;
+  /** Fill color: `primary` (default), `success`, `warning`, `error`, `info`. Attribute: `tone`. */
+  tone?: string;
+}
+
+/**
+ * `<kai-progress-bar>` — a thin determinate progress bar: a rounded track with a
+ * `bg-primary` fill whose width is `value / max` (clamped to 0..100%). Set `tone`
+ * for a semantic fill hue. Scalar attributes only.
+ *
+ * ```html
+ * <kai-progress-bar value="66"></kai-progress-bar>
+ * <kai-progress-bar value="3" max="5" label="Setup"></kai-progress-bar>
+ * <kai-progress-bar value="60" tone="success"></kai-progress-bar>
+ * ```
+ * Restyle via `::part(track)` / `::part(fill)`.
+ */
+defineWebComponent<Props>('kai-progress-bar', {
+  value: undefined,
+  max: undefined,
+  label: undefined,
+  tone: 'primary',
+}, (props) => (
+  <ProgressBar
+    value={props.value != null ? Number(props.value) : 0}
+    max={props.max != null ? Number(props.max) : undefined}
+    label={props.label as string | undefined}
+    tone={props.tone as ProgressTone | undefined}
+  />
+));

package/src/elements/prompt-dock.tsx

@@ -0,0 +1,81 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { PromptDock, type PromptDockAppearance, type PromptDockFrame } from '../ui/prompt-dock';
+
+interface Props extends Record<string, unknown> {
+  /** How the tray frames the input — the SPATIAL inset axis: `inset` (default,
+   *  the classic recessed frame on every side) | `edge` (top/bottom inset only;
+   *  the input sits flush left/right so the lips span the full width) | `none`
+   *  (no inset; the lips attach directly as a plain stack). Attribute: `frame`. */
+  frame?: PromptDockFrame;
+  /** How the tray surface looks — the VISUAL axis, orthogonal to `frame`:
+   *  `soft` (default, sunken surface + border + radius) | `outlined`
+   *  (transparent + border + radius) | `filled` (sunken, no border, + radius) |
+   *  `plain` (bare). Attribute: `appearance`. */
+  appearance?: PromptDockAppearance;
+}
+
+/** The named slots whose occupancy gates a dock lip. An empty `<slot>` is always
+ *  a truthy node, so the facade tracks which are actually filled and only passes
+ *  those regions to the primitive (which renders top/bottom only when truthy). */
+const SLOT_NAMES = ['top', 'bottom'] as const;
+type SlotName = (typeof SLOT_NAMES)[number];
+
+/**
+ * `<kai-prompt-dock>` — a recessed tray that frames a prompt input and can extend
+ * with optional "lip" regions above and/or below it. The input is the raised card
+ * that floats on the tray; the lips sit in a slightly darker recessed band sharing
+ * the tray's rounding, so the whole thing reads as one cohesive control.
+ *
+ * Slots: the DEFAULT slot is the prompt input (the raised card). `slot="top"` is a
+ * recessed band ABOVE the input (a notice, a hint); `slot="bottom"` is a band BELOW
+ * it (a mode / control row). A lip renders only when its slot is filled — an empty
+ * dock shows just the input, no stray band.
+ *
+ * Styling splits into two orthogonal variant attributes: `frame` (the spatial inset)
+ * and `appearance` (the surface). `::part(tray)` / `::part(top)` / `::part(bottom)`
+ * expose the three regions for outside styling; four `--kai-prompt-dock-*` tokens
+ * tune the chrome (surface / border / radius / inset).
+ *
+ * ```html
+ * <kai-prompt-dock frame="edge" appearance="soft">
+ *   <div slot="top">Working in the docs branch</div>
+ *   <kai-prompt-input></kai-prompt-input>
+ *   <div slot="bottom">Claude Opus 4.8 · 200k context</div>
+ * </kai-prompt-dock>
+ * ```
+ */
+defineWebComponent<Props>('kai-prompt-dock', {
+  frame: 'inset',
+  appearance: 'soft',
+}, (props, { element }) => {
+  // Track which named lip slots are filled. Re-read on child mutations so streamed
+  // / late content lights up its band. An unfilled lip is never rendered (the
+  // primitive gates on a truthy top/bottom, and a bare <slot> is always truthy).
+  const [filled, setFilled] = createSignal<Record<SlotName, boolean>>({ top: false, bottom: false });
+
+  onMount(() => {
+    const read = () => {
+      const next = {} as Record<SlotName, boolean>;
+      for (const name of SLOT_NAMES) next[name] = !!element.querySelector(`:scope > [slot="${name}"]`);
+      setFilled(next);
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  const lip = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
+
+  return (
+    <PromptDock
+      frame={props.frame as PromptDockFrame}
+      appearance={props.appearance as PromptDockAppearance}
+      top={lip('top')}
+      bottom={lip('bottom')}
+    >
+      <slot />
+    </PromptDock>
+  );
+});