@kitn.ai/ui 0.17.0 → 0.18.1

package/src/elements/define.tsx

@@ -1,7 +1,7 @@
 import { customElement } from 'solid-element';
 import { ChatConfig } from '../primitives/chat-config';
 import { ELEMENT_CSS } from './css';
-import { createSignal, onCleanup, onMount, Show, type JSX } from 'solid-js';
+import { createSignal, onCleanup, Show, type JSX } from 'solid-js';
 
 /**
  * Shared constructable stylesheet, built once and adopted by every element's
@@ -67,6 +67,17 @@ export interface WebComponentContext<E = Record<string, unknown>> {
    * `name` is the camelCase prop name; the matching kebab attribute is derived.
    */
   flag: (name: string) => boolean;
+  /**
+   * Expose imperative methods on the host element instance — the input half of a
+   * component's interaction surface (`el.focus()`, `el.clear()`, `el.scrollToBottom()`,
+   * …), the counterpart to the events `dispatch` fires. Call once from the facade
+   * with closures over its internal state/refs; each entry is assigned to the host,
+   * so a consumer calls it directly: `document.querySelector('kai-prompt-input').focus()`.
+   * Overriding a native method name (e.g. `focus`) shadows it on the instance so it
+   * can target the right control inside the shadow root (the WebAwesome/Shoelace
+   * convention). Methods are attached when the facade renders (on element upgrade).
+   */
+  expose: (methods: Record<string, (...args: never[]) => unknown>) => void;
 }
 
 /** camelCase prop name → kebab-case attribute (`hoverCard` → `hover-card`). */
@@ -77,6 +88,8 @@ function toAttr(name: string): string {
 /** Underlying flag resolution; see `WebComponentContext.flag`. */
 function resolveFlag(element: HTMLElement, value: unknown, attribute: string): boolean {
   if (value === true) return true;
+  // An explicit JS false wins over a present attribute (see WebComponentContext.flag); this also prevents a feedback loop when an effect writes the attribute it reads.
+  if (value === false) return false;
   return element.hasAttribute(attribute) && element.getAttribute(attribute) !== 'false';
 }
 
@@ -124,13 +137,27 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
     }
   }
 
+  // Props that NAME a reflected global IDL accessor (today: only `role`, from
+  // ARIAMixin's Element.prototype.role). Unlike RESERVED (which throws), these are
+  // allowed as plain styling props, but they must NEVER reach the host as an
+  // attribute: kai-message uses role='user'|'assistant' to pick its layout, and
+  // those are not valid ARIA roles, so a reflected role="user" / role="assistant"
+  // fails axe's aria-roles rule. The native IDL setter reflects to an attribute
+  // whenever the property is set BEFORE connectedCallback (e.g. in a framework
+  // `ref`: `el.role = 'user'`), which is the window before component-register
+  // installs its own (non-reflecting) per-instance accessor in initializeProps. We
+  // shadow the native accessor on the element prototype with a plain non-reflecting
+  // one, so setting the property only STORES the value (component-register still
+  // reads it back for styling) and never touches a host attribute.
+  const NON_REFLECTING = ['role'];
+
   // Every element gets a `theme` property/attribute: 'light' | 'dark' | 'auto'
   // (default 'auto' = follow the OS `prefers-color-scheme`). It drives a `.dark`
   // class on an inner wrapper, which the injected kit CSS already styles — so dark
   // mode works in standalone Shadow-DOM usage with no token duplication.
   const defaults = { theme: 'auto', ...propDefaults };
 
-  customElement(tag, defaults, (props: typeof defaults, options: { element: object }) => {
+  const Ctor = customElement(tag, defaults, (props: typeof defaults, options: { element: object }) => {
     const element = options.element as HTMLElement;
     let portalNode!: HTMLDivElement;
 
@@ -144,17 +171,45 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
     const flag = (name: string) =>
       resolveFlag(element, (props as Record<string, unknown>)[name], toAttr(name));
 
+    // Attach imperative methods onto the host instance. See WebComponentContext.expose.
+    // Uses defineProperty so a method can shadow an inherited getter-only accessor
+    // (e.g. `focus`/`blur`) which a plain assignment would throw on. A method name
+    // must NOT collide with a declared prop (the prop's accessor would be clobbered)
+    // — pick a distinct verb (e.g. `send()` next to a `submit` prop). Failures warn
+    // and skip rather than breaking the element's render.
+    const expose: WebComponentContext<E>['expose'] = (methods) => {
+      for (const [name, fn] of Object.entries(methods)) {
+        try {
+          Object.defineProperty(element, name, { value: fn, writable: true, configurable: true });
+        } catch (err) {
+          console.warn(`defineWebComponent(${tag}): could not expose method "${name}"`, err);
+        }
+      }
+    };
+
     const isDark = createDarkMode(() => props.theme as string | undefined);
 
     // Prefer a single shared stylesheet adopted into this shadow root; only emit
     // an inline <style> when Constructable Stylesheets aren't supported.
+    //
+    // Adopt SYNCHRONOUSLY, before solid-element inserts the rendered content into
+    // the shadow root. component-register attaches the shadow root lazily on first
+    // `renderRoot` access — which happens during that insert, AFTER this facade
+    // function returns. So we pre-attach the shadow root here (with the same
+    // `mode: 'open'` the renderRoot getter would use, making it a no-op for
+    // solid-element) and adopt the sheet now. If we deferred to onMount instead,
+    // the content would paint UNSTYLED and then animate from that bare state to
+    // its resting style once the sheet landed — every `transition-colors` button
+    // and menu/dropdown trigger flashing as if hovered-then-un-hovered on first
+    // render. Adopting first means the very first computed style of every node is
+    // already the resting style, so no transition can fire on load.
     const sheet = getSharedSheet();
-    onMount(() => {
-      const root = element.shadowRoot;
-      if (sheet && root && 'adoptedStyleSheets' in root) {
+    if (sheet) {
+      const root = element.shadowRoot ?? element.attachShadow({ mode: 'open' });
+      if ('adoptedStyleSheets' in root && !root.adoptedStyleSheets.includes(sheet)) {
         root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
       }
-    });
+    }
 
     return (
       <>
@@ -168,10 +223,35 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
         <div classList={{ dark: isDark() }} style={{ display: 'contents', color: 'var(--color-foreground)' }}>
           <div ref={portalNode} />
           <ChatConfig portalMount={portalNode}>
-            {Facade(props as unknown as P, { element, dispatch, flag })}
+            {Facade(props as unknown as P, { element, dispatch, flag, expose })}
           </ChatConfig>
         </div>
       </>
     );
   });
+
+  // Shadow any reflected native IDL accessor this element re-uses as a prop (see
+  // NON_REFLECTING) with a plain, non-reflecting store on the element prototype.
+  // This must live on the prototype (not the instance) so it is already in place
+  // when the value is set before connectedCallback, the window in which the native
+  // setter would otherwise reflect it to a host attribute. component-register reads
+  // the property back during initializeProps to seed the styling prop, and later
+  // shadows this with its own (also non-reflecting) per-instance accessor.
+  const proto = (Ctor as unknown as { prototype?: object } | undefined)?.prototype;
+  if (proto) {
+    for (const key of NON_REFLECTING) {
+      if (!(key in defaults)) continue;
+      const store = Symbol(`kai-prop:${key}`);
+      Object.defineProperty(proto, key, {
+        get(this: Record<symbol, unknown>) {
+          return this[store];
+        },
+        set(this: Record<symbol, unknown>, value: unknown) {
+          this[store] = value;
+        },
+        enumerable: true,
+        configurable: true,
+      });
+    }
+  }
 }

package/src/elements/dialog.tsx

@@ -0,0 +1,98 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Dialog, type DialogController } from '../ui/dialog';
+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 on Escape/backdrop). Set
+   *  `el.open = true`, or `<kai-dialog open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+}
+
+/** Events fired by `<kai-dialog>`. */
+interface Events {
+  /** The dialog opened or closed (Escape, backdrop click, a driven `open`, or a method). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-dialog>` — a centered modal: a dimmed backdrop over the page with a
+ * centered panel of arbitrary content. It is the real primitive behind the kind
+ * of modal that settings panels and broadcast composers reach for.
+ *
+ * **How to use** — slot the body, and optionally a `header` and `footer`:
+ * ```html
+ * <kai-dialog open>
+ *   <h2 slot="header">Broadcast a message</h2>
+ *   <textarea placeholder="What's on your mind?"></textarea>
+ *   <div slot="footer">
+ *     <button onclick="this.closest('kai-dialog').hide()">Cancel</button>
+ *     <button>Send</button>
+ *   </div>
+ * </kai-dialog>
+ * ```
+ *
+ * The default slot is the body; `header`/`footer` are optional regions with
+ * dividers. The backdrop dims the page; clicking it (or pressing Escape) closes
+ * the dialog. Focus moves into the panel on open and is restored on close, and a
+ * basic Tab focus trap keeps keyboard focus inside while open.
+ *
+ * Open state is the standard disclosure surface: settable+reflecting `open`,
+ * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`.
+ * It also exposes `focus()` to move focus to the panel. Parts: `backdrop` ·
+ * `panel` · `header` · `body` · `footer`.
+ */
+defineWebComponent<Props, Events>('kai-dialog', {
+  open: undefined,
+  defaultOpen: undefined,
+}, (props, ctx) => {
+  const { flag, element, expose } = ctx;
+  let api: DialogController | undefined;
+  let panel: HTMLElement | undefined;
+
+  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle. See ./disclosure. The SOLE emitter of kai-open-change — the
+  // primitive's onOpenChange is intentionally NOT wired here to avoid a double
+  // dispatch.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  // Only render the header/footer chrome (border + padding) when the consumer has
+  // actually projected content for that slot — otherwise an empty bordered region
+  // would show. Tracked off the host's light-DOM children.
+  const [hasHeader, setHasHeader] = createSignal(false);
+  const [hasFooter, setHasFooter] = createSignal(false);
+  const recompute = () => {
+    setHasHeader(!!element.querySelector(':scope > [slot="header"]'));
+    setHasFooter(!!element.querySelector(':scope > [slot="footer"]'));
+  };
+  onMount(() => {
+    recompute();
+    if (typeof MutationObserver === 'function') {
+      const obs = new MutationObserver(recompute);
+      obs.observe(element, { childList: true });
+      onCleanup(() => obs.disconnect());
+    }
+  });
+
+  // focus() shadows the host's native focus so it targets the dialog panel inside
+  // the shadow root (the WebAwesome/Shoelace convention).
+  expose({
+    /** Move focus to the dialog panel (no-op while closed). */
+    focus: (options?: FocusOptions) => panel?.focus(options),
+  });
+
+  return (
+    <Dialog
+      defaultOpen={flag('defaultOpen')}
+      header={hasHeader() ? <slot name="header" /> : undefined}
+      footer={hasFooter() ? <slot name="footer" /> : undefined}
+      controllerRef={(a) => (api = a)}
+      panelRef={(el) => (panel = el)}
+    >
+      <slot />
+    </Dialog>
+  );
+});

package/src/elements/disclosure.ts

@@ -0,0 +1,73 @@
+import { createEffect, untrack, type Accessor } from 'solid-js';
+import type { WebComponentContext } from './define';
+
+/** The open controller a primitive hands up via `controllerRef` so a facade can
+ *  drive + observe its open/closed state. */
+export interface OpenController {
+  open: Accessor<boolean>;
+  setOpen: (v: boolean) => void;
+}
+
+/**
+ * Wire the standard Shoelace/WebAwesome-style overlay surface onto an internal
+ * open controller — the kit's convention for every open/close element (hover-card,
+ * tooltip, popover, menu, model-switcher, scope-picker, collapsibles, …). NOT
+ * React-controlled: the element keeps self-managing; this layers the host-facing
+ * conveniences on top.
+ *
+ * Given the primitive's `{ open, setOpen }` controller, it provides:
+ *  - **`open` reflects** to the host `[open]` attribute (for `:host([open])` CSS),
+ *    and is **settable** — `el.open = true` / `<el open>` drives it;
+ *  - **`kai-open-change` `{ open }`** fires once per change (a guarded reflect
+ *    avoids the attribute⇄prop feedback loop);
+ *  - **`show()` / `hide()` / `toggle()`** instance methods, gated by `disabled`.
+ *
+ * The facade still:
+ *  - declares the `open` / `defaultOpen` / `disabled` props (defaults `undefined`),
+ *  - seeds the primitive from `defaultOpen` (e.g. via the primitive's own prop),
+ *  - includes `'kai-open-change': { open: boolean }` in its `Events` map.
+ *
+ * @param ctx      the facade's WebComponentContext (its Events must include kai-open-change).
+ * @param getApi   returns the open controller once the primitive has handed it up (may be undefined early).
+ * @param openProp reads the raw reactive `open` prop (e.g. `() => props.open`) — used to tell
+ *                 "consumer explicitly set open" from "unset" so a `defaultOpen` seed isn't clobbered.
+ */
+export function wireDisclosure<E extends { 'kai-open-change': { open: boolean } }>(
+  ctx: WebComponentContext<E>,
+  getApi: () => OpenController | undefined,
+  openProp: () => unknown,
+): void {
+  const { element, dispatch, flag, expose } = ctx;
+  let prev: boolean | undefined;
+
+  // Reflect internal open → the `[open]` host attribute + fire kai-open-change.
+  createEffect(() => {
+    const api = getApi();
+    if (!api) return;
+    const o = api.open();
+    element.toggleAttribute('open', o);
+    if (prev !== undefined && prev !== o) dispatch('kai-open-change', { open: o } as E['kai-open-change']);
+    prev = o;
+  });
+
+  // External `open` prop/attr → drive internal state. Only when the consumer has
+  // EXPLICITLY set it (so a defaultOpen seed survives mount); the equality guard
+  // keeps the reflect above from looping back through the prop.
+  createEffect(() => {
+    const api = getApi();
+    if (!api) return;
+    const explicit = openProp() !== undefined || element.hasAttribute('open');
+    if (!explicit) return;
+    const desired = flag('open');
+    if (desired !== untrack(api.open)) api.setOpen(desired);
+  });
+
+  expose({
+    /** Open it programmatically (no-op while disabled). */
+    show: () => { if (!flag('disabled')) getApi()?.setOpen(true); },
+    /** Close it programmatically. */
+    hide: () => getApi()?.setOpen(false),
+    /** Flip the open state (closes while disabled). */
+    toggle: () => { const api = getApi(); if (api) api.setOpen(flag('disabled') ? false : !api.open()); },
+  });
+}

package/src/elements/editable-label.tsx

@@ -0,0 +1,125 @@
+import { createEffect, createSignal, untrack } from 'solid-js';
+import { defineWebComponent } from './define';
+import { EditableLabel } from '../ui/editable-label';
+
+interface Props extends Record<string, unknown> {
+  /** The label text — settable and reflected to the `value` attribute. Read
+   *  `el.value` for live state. */
+  value?: string;
+  /** Controlled edit state. `el.editing = true` opens the field; reflected to the
+   *  `editing` attribute. */
+  editing?: boolean;
+  /** Placeholder shown while editing / when the value is empty. */
+  placeholder?: string;
+  /** Disable entering edit mode. */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kai-editable-label>`. */
+interface Events {
+  /** Committed a changed value (Enter / blur). */
+  'kai-rename': { value: string };
+  /** Edit was cancelled (Esc); the text is restored. */
+  'kai-cancel': Record<string, never>;
+}
+
+/**
+ * `<kai-editable-label>` — inline rename, built on `kai-input`. Shows `value` as
+ * text; double-click (or `el.edit()`, or `editing`) swaps in an autofocused
+ * field. Enter or blur commits → `kai-rename` (only when the value changed); Esc
+ * cancels → `kai-cancel` (the text is restored).
+ *
+ * ```html
+ * <kai-editable-label value="Project Alpha"></kai-editable-label>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const label = document.querySelector('kai-editable-label');
+ *   label.addEventListener('kai-rename', (e) => save(e.detail.value));
+ *   label.edit(); // open the field programmatically
+ * </script>
+ * ```
+ *
+ * Methods: `edit()`, `commit()`, `cancel()`. Restyle via `::part(text)` and
+ * `::part(input)`.
+ */
+defineWebComponent<Props, Events>('kai-editable-label', {
+  value: undefined,
+  editing: false,
+  placeholder: undefined,
+  disabled: false,
+}, (props, ctx) => {
+  const { element, dispatch, flag, expose } = ctx;
+
+  // Controlled value, mirrored to the `value` attribute (the kai-segmented pattern).
+  const [value, setValue] = createSignal(
+    (props.value as string | undefined) ?? element.getAttribute('value') ?? '',
+  );
+  const coerce = (v: unknown): string =>
+    v == null ? (element.getAttribute('value') ?? '') : String(v);
+  Object.defineProperty(element, 'value', {
+    get: () => value(),
+    set: (v: unknown) => { const next = coerce(v); if (untrack(value) !== next) setValue(next); },
+    configurable: true,
+    enumerable: true,
+  });
+  createEffect(() => {
+    const v = value();
+    if (v) {
+      if (element.getAttribute('value') !== v) element.setAttribute('value', v);
+    } else if (element.hasAttribute('value')) {
+      element.removeAttribute('value');
+    }
+  });
+
+  // Edit state lives in the facade and drives the primitive. The methods map to
+  // the primitive's own gestures so every commit / cancel flows through its guarded
+  // Enter/Esc/blur handlers (no double-fire). Controlled `editing` rides the native
+  // solid-element prop/attribute: we follow it (so `el.editing = true` /
+  // `<kai-editable-label editing>` opens the field) and reflect it, but never
+  // override the property with a side-effecting `Object.defineProperty` — doing so
+  // fires the setter during solid-element's upgrade and corrupts the signal.
+  const [editing, setEditing] = createSignal(flag('editing'));
+  createEffect(() => setEditing(flag('editing')));
+  createEffect(() => {
+    if (editing()) {
+      if (!element.hasAttribute('editing')) element.setAttribute('editing', '');
+    } else if (element.hasAttribute('editing')) {
+      element.removeAttribute('editing');
+    }
+  });
+
+  const getInput = (): HTMLInputElement | null =>
+    element.shadowRoot?.querySelector<HTMLInputElement>('input') ?? null;
+
+  const enter = () => { if (!flag('disabled')) setEditing(true); };
+  // Blur drives the primitive's blur-commit; Escape drives its cancel.
+  const commit = () => { getInput()?.blur(); };
+  const cancel = () => {
+    const input = getInput();
+    if (input) {
+      input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, composed: true }));
+    } else if (untrack(editing)) {
+      setEditing(false);
+      dispatch('kai-cancel', {});
+    }
+  };
+
+  expose({ edit: enter, commit, cancel });
+
+  return (
+    <>
+      <style>{':host{display:inline-flex}'}</style>
+      <EditableLabel
+        value={value()}
+        editing={editing()}
+        placeholder={props.placeholder as string | undefined}
+        disabled={flag('disabled')}
+        onRename={(next) => {
+          setEditing(false);
+          if (next !== untrack(value)) { setValue(next); dispatch('kai-rename', { value: next }); }
+        }}
+        onCancel={() => { setEditing(false); dispatch('kai-cancel', {}); }}
+      />
+    </>
+  );
+});

package/src/elements/element-manifest.json

@@ -27,6 +27,13 @@
     "kai-sources": "source",
     "kai-response-stream": "response-stream",
     "kai-empty": "empty",
+    "kai-status": "status",
+    "kai-nav": "nav",
+    "kai-progress-bar": "progress-bar",
+    "kai-coachmark": "coachmark",
+    "kai-tabs": "tabs",
+    "kai-voice-output": "voice-output",
+    "kai-screen": "screen",
     "kai-chain-of-thought": "chain-of-thought",
     "kai-resizable": "resizable",
     "kai-resizable-item": "resizable",
@@ -35,6 +42,16 @@
     "kai-scroll-button": "scroll-button",
     "kai-popover": "popover",
     "kai-switch": "switch",
+    "kai-button": "button",
+    "kai-avatar": "avatar",
+    "kai-badge": "badge",
+    "kai-tooltip": "tooltip",
+    "kai-notice": "notice",
+    "kai-icon": "icon",
+    "kai-separator": "separator",
+    "kai-scroll-area": "scroll-area",
+    "kai-hover-card": "hover-card",
+    "kai-skeleton": "skeleton",
     "kai-toast-region": "toast",
     "kai-card": "card",
     "kai-form": "form",
@@ -44,7 +61,22 @@
     "kai-tasks": "tasks",
     "kai-choice": "choice",
     "kai-cards": "cards",
-    "kai-compare": "compare"
+    "kai-compare": "compare",
+    "kai-composer": "composer",
+    "kai-menu": "menu",
+    "kai-command": "command",
+    "kai-prompt-dock": "prompt-dock",
+    "kai-segmented": "segmented",
+    "kai-settings-group": "settings-group",
+    "kai-setting-item": "setting-item",
+    "kai-pane": "pane",
+    "kai-pane-group": "pane-group",
+    "kai-agent-card": "agent-card",
+    "kai-dialog": "dialog",
+    "kai-input": "input",
+    "kai-search": "search",
+    "kai-kbd": "kbd",
+    "kai-editable-label": "editable-label"
   },
   "files": {
     "conversation-list": [
@@ -126,6 +158,27 @@
     "empty": [
       "kai-empty"
     ],
+    "status": [
+      "kai-status"
+    ],
+    "nav": [
+      "kai-nav"
+    ],
+    "progress-bar": [
+      "kai-progress-bar"
+    ],
+    "coachmark": [
+      "kai-coachmark"
+    ],
+    "tabs": [
+      "kai-tabs"
+    ],
+    "voice-output": [
+      "kai-voice-output"
+    ],
+    "screen": [
+      "kai-screen"
+    ],
     "chain-of-thought": [
       "kai-chain-of-thought"
     ],
@@ -148,6 +201,36 @@
     "switch": [
       "kai-switch"
     ],
+    "button": [
+      "kai-button"
+    ],
+    "avatar": [
+      "kai-avatar"
+    ],
+    "badge": [
+      "kai-badge"
+    ],
+    "tooltip": [
+      "kai-tooltip"
+    ],
+    "notice": [
+      "kai-notice"
+    ],
+    "icon": [
+      "kai-icon"
+    ],
+    "separator": [
+      "kai-separator"
+    ],
+    "scroll-area": [
+      "kai-scroll-area"
+    ],
+    "hover-card": [
+      "kai-hover-card"
+    ],
+    "skeleton": [
+      "kai-skeleton"
+    ],
     "toast": [
       "kai-toast-region"
     ],
@@ -177,6 +260,51 @@
     ],
     "compare": [
       "kai-compare"
+    ],
+    "composer": [
+      "kai-composer"
+    ],
+    "menu": [
+      "kai-menu"
+    ],
+    "command": [
+      "kai-command"
+    ],
+    "prompt-dock": [
+      "kai-prompt-dock"
+    ],
+    "segmented": [
+      "kai-segmented"
+    ],
+    "settings-group": [
+      "kai-settings-group"
+    ],
+    "setting-item": [
+      "kai-setting-item"
+    ],
+    "pane": [
+      "kai-pane"
+    ],
+    "pane-group": [
+      "kai-pane-group"
+    ],
+    "agent-card": [
+      "kai-agent-card"
+    ],
+    "dialog": [
+      "kai-dialog"
+    ],
+    "input": [
+      "kai-input"
+    ],
+    "search": [
+      "kai-search"
+    ],
+    "kbd": [
+      "kai-kbd"
+    ],
+    "editable-label": [
+      "kai-editable-label"
     ]
   }
 }