@kitn.ai/ui 0.26.0 → 0.28.0

package/src/elements/composer.tsx

@@ -54,7 +54,10 @@ interface Props extends Record<string, unknown> {
 
 /** Events fired by `<kai-composer>`. */
 interface Events {
-  /** The user submitted the composer (Enter or programmatic submit). */
+  /** The user submitted the composer (Enter or programmatic submit). Note the
+   *  detail carries no `attachments`; `<kai-composer>` is the bare editing
+   *  surface: no send button, toolbar, or attachments. For a drop-in composer
+   *  row with all three, reach for `<kai-prompt-input>`, which is built on this. */
   'kai-submit': { doc: ComposerDoc; text: string; entities: EntityRef[] };
   /** The content changed (fires on every input event). */
   'kai-value-change': { doc: ComposerDoc; text: string; entities: EntityRef[] };
@@ -75,6 +78,14 @@ interface Events {
   'kai-blur': { originalEvent: FocusEvent };
 }
 
+/**
+ * `<kai-composer>` — the bare editing surface: rich text, entity pills,
+ * trigger menus, Enter-to-submit, and nothing else. No send button, no
+ * toolbar, no attachments — that division is deliberate. For a drop-in chat
+ * composer with a send button, toolbar, and attachment staging, reach for
+ * `<kai-prompt-input>`, which is built on this element. Keep `<kai-composer>`
+ * when you are composing the input row yourself and want to own those pieces.
+ */
 defineWebComponent<Props, Events>('kai-composer', {
   value: undefined,
   placeholder: undefined,

package/src/elements/conversation-item.tsx

@@ -2,48 +2,76 @@ import { createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
 import { readSlots, CONVERSATION_ITEM_SLOTS } from './slots';
 import { SlottedConversationItem } from '../components/conversation-item';
+import { isStandaloneConversationItem, readConversationItemId } from '../components/conversation-list';
 
 interface Props extends Record<string, unknown> {
-  /** The row's identity, handed to the container's selection contract. In the
-   *  element this is the `conversation-id` attribute (host `id` is the fallback). */
+  /** The row's identity: the `conversation-id` attribute (host `id` is the
+   *  fallback). Inside `<kai-conversations>` it is handed to the container's
+   *  selection contract (`kai-conversation-select`); standalone it is the `id`
+   *  in this element's own `kai-select` detail. */
   conversationId?: string;
   /** Selected state. Reflected as `aria-current` on the row body and a
-   *  `data-active` styling hook on the row; the container drives it from its
-   *  `activeId`. */
+   *  `data-active` styling hook on the row; inside a container the container
+   *  drives it from its `activeId`, standalone you set it yourself. */
   active?: boolean;
   /** Dense single-line row padding. */
   compact?: boolean;
 }
 
+interface Events {
+  /** STANDALONE activation only: the row was activated (click, Enter or Space on its body) while the item is NOT a
+   *  direct child of `<kai-conversations>`. `id` is the row's identity: the
+   *  `conversation-id` attribute, else the host `id`. Inside a container this
+   *  never fires: activation surfaces once, as `kai-conversation-select` on the
+   *  container. */
+  'kai-select': { id: string };
+}
+
 /**
  * `<kai-conversation-item>` — one composed row of a consumer-owned conversation
- * loop, slotted into `<kai-conversations>`' light DOM. The consumer owns the
- * loop (framework-native `map`, `<For>`, `v-for`); the container detects these
- * children, skips its data rendering, and runs the parent-item contract over
- * them: selection state flowing container to item, roving tabindex, and the
- * accessible list/row relationship (list rows with button bodies and
- * `aria-current` marking the active one; ratified 2026-08-20 — axe's
- * nested-interactive and aria-required-children rules are why this is not
- * listbox/option).
+ * loop. Two placements, one activation event each:
+ *
+ * SLOTTED into `<kai-conversations>`' light DOM (a direct child): the consumer
+ * owns the loop (framework-native `map`, `<For>`, `v-for`); the container
+ * detects these children, skips its data rendering, and runs the parent-item
+ * contract over them — selection state flowing container to item, roving
+ * tabindex, arrow-key traversal, and the accessible list/row relationship
+ * (list rows with button bodies and `aria-current` marking the active one;
+ * axe's nested-interactive and aria-required-children
+ * rules are why this is not listbox/option). Activation (click, Enter, Space)
+ * surfaces as `kai-conversation-select` on the container, and the item itself
+ * fires nothing — no double event.
+ *
+ * STANDALONE (anywhere else — a hand-composed rail, or wrapped in another
+ * element even inside a container, since the container manages only direct
+ * children): the row activates ITSELF.
+ * Its shadow body is a tabbable `role="button"`, and click / Enter / Space
+ * fire `kai-select` on this element with `{ id }` — non-bubbling, like every
+ * `kai-*` event, so listen on the item itself. What a standalone row does NOT
+ * have is the container's LIST story: roving tabindex across rows, arrow-key
+ * traversal, and the shared `role="list"` relationship — each standalone row
+ * is an ordinary tab stop, and a hand-composed rail brings its own list
+ * semantics (or slots the rows into `<kai-conversations>` and gets them for
+ * free).
  *
  * Slots: the default slot is the title; `leading`, `meta` and `menu` are the
  * named regions. The `menu` slot takes your OWN popover (rename, fork, archive
  * live there); the element provides only the region plus focus and ARIA
  * plumbing, never a declarative actions prop, and a click inside it never
- * selects the row.
- *
- * The item is presentational on its own: activation (click, Enter, Space)
- * surfaces as `kai-conversation-select` on the surrounding `<kai-conversations>`,
- * never as an event of this element.
+ * selects the row — in either placement.
  */
-defineWebComponent<Props>('kai-conversation-item', {
+defineWebComponent<Props, Events>('kai-conversation-item', {
   conversationId: undefined,
   active: undefined,
   compact: undefined,
-}, (props, { element, flag, reflectFlag }) => {
+}, (props, { element, flag, reflectFlag, dispatch }) => {
   // Which named regions the consumer has filled; drives the conditional
   // wrappers so an empty region leaves no stray box behind.
   const [slots, setSlots] = createSignal<Record<string, boolean>>({});
+  // Standalone vs container-managed, decided at mount (an item is not
+  // reparented in practice; the activation handler re-checks at event time so
+  // a row moved INTO a container can never double-fire).
+  const [standalone, setStandalone] = createSignal(false);
   onMount(() => {
     const read = () => setSlots(readSlots(element, CONVERSATION_ITEM_SLOTS));
     read();
@@ -51,15 +79,26 @@ defineWebComponent<Props>('kai-conversation-item', {
     observer.observe(element, { childList: true, attributes: true, subtree: true });
     onCleanup(() => observer.disconnect());
 
-    // The HOST is the row LISTITEM (sibling restructure, ratified 2026-08-20):
+    // The HOST is the row LISTITEM:
     // it wraps the activation body AND the consumer's tabbable menu, so it must
     // never be the activation control itself — axe nested-interactive bans
     // focusable descendants of a control. The button role, aria-current and the
-    // roving tabindex live on the shadow BODY (`data-kai-item-body`), which the
-    // container's controller targets. An authored role wins.
+    // tabindex live on the shadow BODY (`data-kai-item-body`): inside a
+    // container its controller stamps them; standalone the component renders
+    // them itself. An authored role wins.
     if (!element.hasAttribute('role')) element.setAttribute('role', 'listitem');
+
+    setStandalone(isStandaloneConversationItem(element));
   });
 
+  // Standalone activation → the per-item `kai-select` event. The re-check at
+  // event time keeps this dead the moment the item becomes a container's direct
+  // child, so the container's `kai-conversation-select` stays the only event.
+  const activate = () => {
+    if (!isStandaloneConversationItem(element)) return;
+    dispatch('kai-select', { id: readConversationItemId(element) });
+  };
+
   // Property and attribute stay in agreement for `active`; the body's
   // aria-current follows it reactively (nothing is written to the host).
   reflectFlag('active');
@@ -70,6 +109,7 @@ defineWebComponent<Props>('kai-conversation-item', {
       active={flag('active')}
       compact={flag('compact')}
       hostSemantics
+      onActivate={standalone() ? activate : undefined}
       leading={slots().leading ? <slot name="leading" /> : undefined}
       meta={slots().meta ? <slot name="meta" /> : undefined}
       menu={slots().menu ? <slot name="menu" /> : undefined}

package/src/elements/conversation-list.tsx

@@ -61,7 +61,7 @@ interface Events {
  *   - `id`       → ConversationSummary.id
  *   - `group-id` → ConversationSummary.groupId (optional)
  *   - textContent → ConversationSummary.title
- *  Fields not expressible as HTML attributes are NOT fabricated (F-10): the
+ *  Fields not expressible as HTML attributes are NOT fabricated: the
  *  optional `scope` and `lastMessageAt` stay absent, and the required
  *  `messageCount`/`updatedAt` get honest defaults — zero messages, and an empty
  *  `updatedAt` from which no trailing relative time is derived (the epoch it
@@ -88,7 +88,7 @@ defineWebComponent<Props, Events>('kai-conversations', {
   // Read declarative <kai-conversation> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
   const [slottedConversations, setSlottedConversations] = createSignal<ConversationSummary[]>([]);
-  // Item mode (spec 2026-08-20 § 2a): light-DOM <kai-conversation-item> children
+  // Item mode: light-DOM <kai-conversation-item> children
   // mean the CONSUMER owns the loop — the container skips its data rendering and
   // runs the parent-item contract over the hosts instead.
   const [itemHosts, setItemHosts] = createSignal<HTMLElement[]>([]);

package/src/elements/define-entry.ts

@@ -0,0 +1,12 @@
+/**
+ * @kitn.ai/ui/define — the facade seam, public.
+ *
+ * The construct engine's GENERATED projects (and any consumer who wants to wrap
+ * a pure-Solid interior as one self-registering element) import from here. Its
+ * own subpath rather than ./solid because define.tsx carries ELEMENT_CSS (the
+ * full compiled kit CSS) and solid-element — weight ./solid consumers must not
+ * pay. SSR-safe by construction: defineWebComponent no-ops without
+ * customElements (see define.tsx).
+ */
+export { defineWebComponent } from './define';
+export type { WebComponentContext } from './define';

package/src/elements/dock.tsx

@@ -28,6 +28,14 @@ interface Props extends Record<string, unknown> {
   unread?: boolean;
   /** Disable the launcher; `show()` and `toggle()` are gated on it. */
   disabled?: boolean;
+  /** Suppress the dock's own built-in mobile close X. Set this when your slotted
+   *  panel content supplies its own close affordance (e.g. a `<kai-chat
+   *  slot="header-end">` close button), otherwise the two stack. TRADEOFF: the
+   *  mobile panel reserves a padding band above its content so the built-in X
+   *  never paints over slotted content; that band stays reserved unless you set
+   *  this true, so only set it once your own control is actually in place.
+   *  Attribute: `hide-close`. */
+  hideClose?: boolean;
   /** Where focus lands on open: `content` (default, the first element you slotted),
    *  `panel`, or `none`. Attribute: `focus-on-open`. */
   focusOnOpen?: DockFocusOnOpen;
@@ -108,6 +116,7 @@ defineWebComponent<Props, Events>('kai-dock', {
   closeLabel: undefined,
   unread: undefined,
   disabled: undefined,
+  hideClose: undefined,
   focusOnOpen: 'content',
 }, (props, ctx) => {
   const { flag, element, expose, reflectFlag } = ctx;
@@ -128,6 +137,7 @@ defineWebComponent<Props, Events>('kai-dock', {
   reflectFlag('unread');
   reflectFlag('disabled');
   reflectFlag('defaultOpen');
+  reflectFlag('hideClose');
 
   // Seed the primitive from EITHER spelling, read once at upgrade.
   //
@@ -178,6 +188,7 @@ defineWebComponent<Props, Events>('kai-dock', {
       closeLabel={props.closeLabel as string | undefined}
       unread={flag('unread')}
       disabled={flag('disabled')}
+      hideClose={flag('hideClose')}
       focusOnOpen={props.focusOnOpen as DockFocusOnOpen}
       contentTarget={contentTarget}
       controllerRef={(a) => (api = a)}

package/src/elements/element-data-types.ts

@@ -36,6 +36,46 @@ export interface KaiSegmentedOption {
   icon?: string;
 }
 
+/** A single row of `<kai-radio-group>`.
+ *
+ *  Distinct from the Solid `RadioOption`, whose `label` and `description` are JSX
+ *  nodes: on the element both are plain strings, because an element property has to
+ *  survive being assigned from HTML/React/Vue/Svelte with no framework in between. */
+export interface KaiRadioOption {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+/** A single row of `<kai-checkbox-group>`.
+ *
+ *  Distinct from the Solid `CheckboxOption`, whose `value` is generic and whose
+ *  `label` and `description` are JSX nodes: on the element all three are plain
+ *  strings, because an element property has to survive being assigned from
+ *  HTML/React/Vue/Svelte with no framework in between. Structurally identical to
+ *  `KaiRadioOption`, and kept as its own name anyway: the two elements are free to
+ *  diverge, and a consumer typing a checkbox list should not have to import the radio
+ *  group's type to do it. */
+export interface KaiCheckboxOption {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+/** A single choice in `<kai-select>`.
+ *
+ *  Distinct from the Solid `SelectOption`, whose `value` is generic: on the element
+ *  it is a string, because a native `<option>`'s value is a string and an element
+ *  property has to survive being assigned from HTML/React/Vue/Svelte with no
+ *  framework in between. `label` defaults to `value`. */
+export interface KaiSelectOption {
+  value: string;
+  label?: string;
+  disabled?: boolean;
+}
+
 /** A single citation in `<kai-sources>`' `sources` property. Also the shape
  *  `<kai-source>` light-DOM children are parsed into. */
 export interface KaiSourceItem {

package/src/elements/element-manifest.json

@@ -45,6 +45,11 @@
     "kai-scroll-button": "scroll-button",
     "kai-popover": "popover",
     "kai-switch": "switch",
+    "kai-checkbox": "checkbox",
+    "kai-checkbox-group": "checkbox-group",
+    "kai-radio-group": "radio-group",
+    "kai-slider": "slider",
+    "kai-select": "select",
     "kai-button": "button",
     "kai-avatar": "avatar",
     "kai-badge": "badge",
@@ -75,6 +80,7 @@
     "kai-setting-item": "setting-item",
     "kai-pane": "pane",
     "kai-pane-group": "pane-group",
+    "kai-pane-grid": "pane-grid",
     "kai-agent-card": "agent-card",
     "kai-dialog": "dialog",
     "kai-dock": "dock",
@@ -215,6 +221,21 @@
     "switch": [
       "kai-switch"
     ],
+    "checkbox": [
+      "kai-checkbox"
+    ],
+    "checkbox-group": [
+      "kai-checkbox-group"
+    ],
+    "radio-group": [
+      "kai-radio-group"
+    ],
+    "slider": [
+      "kai-slider"
+    ],
+    "select": [
+      "kai-select"
+    ],
     "button": [
       "kai-button"
     ],
@@ -305,6 +326,9 @@
     "pane-group": [
       "kai-pane-group"
     ],
+    "pane-grid": [
+      "kai-pane-grid"
+    ],
     "agent-card": [
       "kai-agent-card"
     ],