@kitn.ai/ui 0.14.1

package/src/elements/chain-of-thought.declarative.test.tsx

@@ -0,0 +1,153 @@
+/**
+ * Unit tests for the declarative `<kai-step>` light-DOM API of
+ * `<kai-chain-of-thought>`.
+ *
+ * Strategy: the `defineWebComponent` call registers a real Shadow-DOM custom
+ * element which requires a full browser environment (Constructable Stylesheets,
+ * shadow roots, etc.) and is therefore not suitable for jsdom unit tests.
+ * Instead we:
+ *   1. Test the exported `parseKaiStepElement` helper in isolation — it has no
+ *      DOM dependencies beyond `Element`, which jsdom provides perfectly.
+ *   2. Test that the merged list of prop + slotted steps renders correctly via
+ *      the `ChainOfThoughtStep`/`ChainOfThoughtTrigger` primitives, mirroring
+ *      the pattern used in `prompt-suggestions.declarative.test.tsx`.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, cleanup } from '@solidjs/testing-library';
+import { For, Show } from 'solid-js';
+import { parseKaiStepElement } from './chain-of-thought';
+
+afterEach(cleanup);
+
+// ---------------------------------------------------------------------------
+// parseKaiStepElement — pure helper
+// ---------------------------------------------------------------------------
+
+describe('parseKaiStepElement', () => {
+  function makeEl(label: string | null, textContent?: string): Element {
+    const el = document.createElement('kai-step');
+    if (label !== null) el.setAttribute('label', label);
+    if (textContent !== undefined) el.textContent = textContent;
+    return el;
+  }
+
+  it('maps label attribute to Step.label', () => {
+    const step = parseKaiStepElement(makeEl('Searching docs', 'Found 3 hits'));
+    expect(step.label).toBe('Searching docs');
+  });
+
+  it('maps trimmed textContent to Step.content', () => {
+    const step = parseKaiStepElement(makeEl('Step', '  Found 3 hits  '));
+    expect(step.content).toBe('Found 3 hits');
+  });
+
+  it('returns undefined for content when textContent is empty', () => {
+    const step = parseKaiStepElement(makeEl('Build & verify', ''));
+    expect(step.content).toBeUndefined();
+  });
+
+  it('returns undefined for content when textContent is whitespace only', () => {
+    const step = parseKaiStepElement(makeEl('Build & verify', '   '));
+    expect(step.content).toBeUndefined();
+  });
+
+  it('falls back to empty string for label when attribute is absent', () => {
+    const step = parseKaiStepElement(makeEl(null, 'some detail'));
+    expect(step.label).toBe('');
+  });
+
+  it('returns a well-formed Step for a heading-only element', () => {
+    const step = parseKaiStepElement(makeEl('Understand the request'));
+    expect(step).toEqual({ label: 'Understand the request', content: undefined });
+  });
+
+  it('returns a well-formed Step for a step with detail', () => {
+    const step = parseKaiStepElement(makeEl('Searching docs', 'Found 3 hits'));
+    expect(step).toEqual({ label: 'Searching docs', content: 'Found 3 hits' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Merge + render: prop steps + slotted steps combine correctly
+// ---------------------------------------------------------------------------
+
+interface Step {
+  label: string;
+  content?: string;
+}
+
+/**
+ * Minimal test harness that renders a list of Steps as labelled divs,
+ * mirroring the merge logic in chain-of-thought.tsx. We render plain divs
+ * rather than the full Shadow DOM component to stay within jsdom.
+ */
+function StepList(props: { items: Step[] }) {
+  return (
+    <div>
+      <For each={props.items}>
+        {(step) => (
+          <div data-testid="step">
+            <span data-testid="step-label">{step.label}</span>
+            <Show when={step.content}>
+              <span data-testid="step-content">{step.content}</span>
+            </Show>
+          </div>
+        )}
+      </For>
+    </div>
+  );
+}
+
+describe('Step list rendering', () => {
+  it('renders one entry per step', () => {
+    const steps: Step[] = [
+      { label: 'Understand the request', content: 'The user wants composable web components.' },
+      { label: 'Design the API', content: 'Route 1: variant + flags.' },
+      { label: 'Build & verify' },
+    ];
+    const { getAllByTestId } = render(() => <StepList items={steps} />);
+    expect(getAllByTestId('step')).toHaveLength(3);
+  });
+
+  it('renders the label for each step', () => {
+    const steps: Step[] = [{ label: 'Searching docs' }, { label: 'Synthesising' }];
+    const { getAllByTestId } = render(() => <StepList items={steps} />);
+    const labels = getAllByTestId('step-label').map((el) => el.textContent);
+    expect(labels).toEqual(['Searching docs', 'Synthesising']);
+  });
+
+  it('renders content only when present', () => {
+    const steps: Step[] = [
+      { label: 'With detail', content: 'Found 3 hits' },
+      { label: 'No detail' },
+    ];
+    const { getAllByTestId, queryAllByTestId } = render(() => <StepList items={steps} />);
+    const contents = queryAllByTestId('step-content');
+    expect(contents).toHaveLength(1);
+    expect(contents[0]).toHaveTextContent('Found 3 hits');
+    expect(getAllByTestId('step')).toHaveLength(2);
+  });
+
+  it('renders prop steps before declarative (slotted) steps', () => {
+    const propSteps: Step[] = [{ label: 'Prop step' }];
+    const slottedSteps: Step[] = [{ label: 'Slotted step' }];
+    const merged = [...propSteps, ...slottedSteps];
+
+    const { getAllByTestId } = render(() => <StepList items={merged} />);
+    const labels = getAllByTestId('step-label').map((el) => el.textContent);
+    expect(labels).toEqual(['Prop step', 'Slotted step']);
+  });
+
+  it('parseKaiStepElement produces steps that render with the correct label and content', () => {
+    const el = document.createElement('kai-step');
+    el.setAttribute('label', 'Searching docs');
+    el.textContent = 'Found 3 hits';
+
+    const step = parseKaiStepElement(el);
+    const { getByTestId } = render(() => <StepList items={[step]} />);
+
+    expect(getByTestId('step-label')).toHaveTextContent('Searching docs');
+    expect(getByTestId('step-content')).toHaveTextContent('Found 3 hits');
+  });
+});

package/src/elements/chain-of-thought.stories.tsx

@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+interface Step {
+  label: string;
+  content?: string;
+}
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-chain-of-thought': JSX.HTMLAttributes<HTMLElement>;
+      /** Light-DOM data carrier for declarative steps inside `<kai-chain-of-thought>`. */
+      'kai-step': JSX.HTMLAttributes<HTMLElement> & { label?: string };
+    }
+  }
+}
+
+const steps: Step[] = [
+  { label: 'Understand the request', content: 'The user wants a composable set of web components.' },
+  { label: 'Design the API', content: 'Route 1: variant + flags + events; rich data via properties.' },
+  { label: 'Build & verify' },
+];
+
+/** Render `<kai-chain-of-thought>` with the `steps` set as a JS property. */
+function CotElement(props: { steps: Step[] }) {
+  let el: (HTMLElement & { steps?: Step[] }) | undefined;
+  onMount(() => {
+    if (el) el.steps = props.steps;
+  });
+  return (
+    <kai-chain-of-thought ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px', 'max-width': '560px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-chain-of-thought id="cot"></kai-chain-of-thought>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  document.getElementById('cot').steps = [
+    { label: 'Understand the request', content: 'The user wants a composable set.' },
+    { label: 'Design the API', content: 'Route 1: variant + flags + events.' },
+    { label: 'Build & verify' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Components/ChainOfThought',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-chain-of-thought'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-chain-of-thought', [
+        '`<kai-chain-of-thought>` is the framework-agnostic **web component** for step-by-step reasoning — a connected list of steps, each with optional collapsible detail — isolated in **Shadow DOM**. The compound primitive collapses to a single `steps` data model (Route 1).',
+        '**When to use:** surfacing an agent\'s plan or reasoning trace in a non-Solid app. In SolidJS, compose the `ChainOfThought` primitives for finer control.',
+        '**Placement:** as a block above or below a message, or in a dedicated reasoning panel; it is `display: block` and sizes to content height, so no fixed height is required.',
+        "**How to use:** register once with `import '@kitn.ai/ui/elements'`. **Property API:** set the `steps` **property** — an array of `{ label, content? }` objects; steps with `content` become expandable. **Declarative API:** compose `<kai-step label=\"…\">…detail…</kai-step>` child elements directly in the HTML — the `label` attribute becomes the heading, `textContent` the optional expandable detail. Declarative children are merged after any prop steps.",
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A three-step reasoning trace; the last step has no detail. */
+export const Default: Story = {
+  render: () => <CotElement steps={steps} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+const DECLARATIVE_HTML_SNIPPET = `<!-- Works in any framework or plain HTML — no JS property assignment needed -->
+<kai-chain-of-thought>
+  <kai-step label="Understand the request">The user wants a composable set of web components.</kai-step>
+  <kai-step label="Design the API">Route 1: variant + flags + events; rich data via properties.</kai-step>
+  <kai-step label="Build &amp; verify"></kai-step>
+</kai-chain-of-thought>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+</script>`;
+
+/**
+ * Declare each reasoning step as a `<kai-step>` child element — no `steps`
+ * property or JS array wiring needed. The `label` attribute becomes the
+ * step heading; `textContent` becomes the optional expandable detail.
+ * Children are light-DOM data carriers hidden by the Shadow DOM — pure data,
+ * no visible output of their own.
+ * Mix with the `steps` prop: prop items render first, declarative children after.
+ */
+export const DeclarativeSteps: Story = {
+  name: 'Declarative Steps (kai-step)',
+  render: () => (
+    <kai-chain-of-thought style={{ display: 'block', padding: '24px', 'max-width': '560px' }}>
+      <kai-step label="Understand the request">The user wants a composable set of web components.</kai-step>
+      <kai-step label="Design the API">Route 1: variant + flags + events; rich data via properties.</kai-step>
+      <kai-step label="Build &amp; verify"></kai-step>
+    </kai-chain-of-thought>
+  ),
+  parameters: {
+    docs: {
+      source: { code: DECLARATIVE_HTML_SNIPPET, language: 'html' },
+    },
+  },
+};

package/src/elements/chain-of-thought.tsx

@@ -0,0 +1,92 @@
+import { For, Show, createSignal, onMount, onCleanup } from 'solid-js';
+import { defineWebComponent } from './define';
+import {
+  ChainOfThought,
+  ChainOfThoughtStep,
+  ChainOfThoughtTrigger,
+  ChainOfThoughtContent,
+  ChainOfThoughtItem,
+} from '../components/chain-of-thought';
+
+interface Step {
+  /** The step's heading (the always-visible trigger). */
+  label: string;
+  /** Optional expandable detail. */
+  content?: string;
+}
+
+interface Props extends Record<string, unknown> {
+  /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to
+   *  this one data model (Route 1). */
+  steps: Step[];
+}
+
+/** Parse a single light-DOM `<kai-step>` element into a `Step` descriptor.
+ *  Attribute mapping:
+ *   - `label`       → Step.label   (the always-visible heading)
+ *   - textContent   → Step.content (optional expandable detail)
+ */
+export function parseKaiStepElement(n: Element): Step {
+  return {
+    label: n.getAttribute('label') ?? '',
+    content: n.textContent?.trim() || undefined,
+  };
+}
+
+/**
+ * `<kai-chain-of-thought>` — step-by-step reasoning with connectors and
+ * per-step collapsible detail.
+ *
+ * **Route 1 — JS property:** set the `steps` property to an array of
+ * `{ label, content? }` objects.
+ *
+ * **Route 2 — declarative children:** compose `<kai-step>` child elements in
+ * light DOM (hidden by the Shadow DOM — pure data carriers). The `label`
+ * attribute becomes the step heading; `textContent` becomes the expandable
+ * detail. Children are merged after any prop steps.
+ *
+ * ```html
+ * <kai-chain-of-thought>
+ *   <kai-step label="Understand the request">The user wants composable web components.</kai-step>
+ *   <kai-step label="Design the API">Route 1: variant + flags; rich data via properties.</kai-step>
+ *   <kai-step label="Build & verify"></kai-step>
+ * </kai-chain-of-thought>
+ * ```
+ */
+defineWebComponent<Props>('kai-chain-of-thought', {
+  steps: [],
+}, (props, { element }) => {
+  // Read declarative <kai-step> children from light DOM.
+  // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
+  const [slottedSteps, setSlottedSteps] = createSignal<Step[]>([]);
+  onMount(() => {
+    const read = () => {
+      const nodes = [...element.querySelectorAll('kai-step')];
+      setSlottedSteps(nodes.map(parseKaiStepElement));
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, attributes: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  // Prop steps first; declarative children appended after.
+  const allSteps = () => [...props.steps, ...slottedSteps()];
+
+  return (
+    <ChainOfThought>
+      <For each={allSteps()}>
+        {(step, i) => (
+          <ChainOfThoughtStep isLast={i() === allSteps().length - 1}>
+            <ChainOfThoughtTrigger>{step.label}</ChainOfThoughtTrigger>
+            <Show when={step.content}>
+              <ChainOfThoughtContent>
+                <ChainOfThoughtItem>{step.content}</ChainOfThoughtItem>
+              </ChainOfThoughtContent>
+            </Show>
+          </ChainOfThoughtStep>
+        )}
+      </For>
+    </ChainOfThought>
+  );
+});

package/src/elements/chat-scope-picker.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-scope-picker': JSX.HTMLAttributes<HTMLElement> & {
+        'current-label'?: string;
+      };
+    }
+  }
+}
+
+/** Render `<kai-scope-picker>` with author/tag options set as properties. */
+function ScopePickerElement(props: { authors: string[]; tags: string[] }) {
+  let el: (HTMLElement & { availableAuthors?: string[]; availableTags?: string[] }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.availableAuthors = props.authors;
+    el.availableTags = props.tags;
+    el.addEventListener('kai-scope-change', (e) => {
+      const ev = e as CustomEvent<{ filters: unknown }>;
+      console.log('kai-scope-change', ev.detail.filters ?? 'all');
+    });
+  });
+  return (
+    <kai-scope-picker ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-scope-picker id="scope"></kai-scope-picker>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const scope = document.getElementById('scope');
+  scope.availableAuthors = ['Rob', 'Alex'];
+  scope.availableTags = ['design', 'api'];
+  // undefined filters means "All Content"
+  scope.addEventListener('kai-scope-change', (e) => console.log(e.detail.filters ?? 'all'));
+</script>`;
+
+const meta = {
+  title: 'Components/ScopePicker',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-scope-picker'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-scope-picker', [
+          '`<kai-scope-picker>` is the framework-agnostic **web component** for scoping a chat by author or tag — a dropdown that emits the chosen filters — isolated in **Shadow DOM**.',
+          '**When to use:** letting users narrow a conversation/search to a subset of content. In SolidJS, use the `ChatScopePicker` primitive.',
+          '**Placement:** in the chat header or above the conversation list, beside the search input; it is a compact `inline-block` dropdown trigger that pairs naturally with `<kai-model-switcher>` or other header controls.',
+          "**How to use:** register once with `import '@kitn.ai/ui/elements'`, set the `availableAuthors` / `availableTags` **properties** (and optionally `current-label`), and listen for the `kai-scope-change` **CustomEvent** (`undefined` filters = \"All Content\").",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Authors and tags available as scope filters. */
+export const Default: Story = {
+  render: () => <ScopePickerElement authors={['Rob', 'Alex']} tags={['design', 'api']} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/chat-scope-picker.tsx

@@ -0,0 +1,36 @@
+import { defineWebComponent } from './define';
+import { ChatScopePicker } from '../components/chat-scope-picker';
+import type { SearchFilters } from '../types';
+
+interface Props extends Record<string, unknown> {
+  /** Authors to offer as scope filters. Set as a JS property. */
+  availableAuthors: string[];
+  /** Tags to offer as scope filters. Set as a JS property. */
+  availableTags: string[];
+  /** The label shown on the trigger for the active scope. */
+  currentLabel?: string;
+}
+
+/** Events fired by `<kai-scope-picker>`. */
+interface Events {
+  /** A scope was chosen (`undefined` filters = "All Content"). */
+  'kai-scope-change': { filters: SearchFilters | undefined };
+}
+
+/**
+ * `<kai-scope-picker>` — a dropdown to scope a chat by author or tag.
+ * Options via `available-authors`/`available-tags` properties; emits
+ * `kai-scope-change`.
+ */
+defineWebComponent<Props, Events>('kai-scope-picker', {
+  availableAuthors: [],
+  availableTags: [],
+  currentLabel: 'All Content',
+}, (props, { dispatch }) => (
+  <ChatScopePicker
+    currentLabel={props.currentLabel ?? 'All Content'}
+    availableAuthors={props.availableAuthors}
+    availableTags={props.availableTags}
+    onScopeChange={(filters) => dispatch('kai-scope-change', { filters })}
+  />
+));

package/src/elements/chat-types.ts

@@ -0,0 +1,42 @@
+import type { ToolPart } from '../components/tool';
+import type { AttachmentData } from '../components/attachments';
+
+/** The five built-in action buttons (each carries its own curated icon + label). */
+export type ChatMessageAction = 'copy' | 'like' | 'dislike' | 'regenerate' | 'edit';
+
+/** A host-defined action button. `icon` is a curated registry name (see
+ *  `src/ui/action-icons.ts`); unknown/absent icons render label-only. */
+export interface CustomAction {
+  /** Emitted as the `kai-message-action` detail `action` when clicked. */
+  id: string;
+  /** Visible/`aria-label` text. */
+  label: string;
+  /** A curated icon name from the action-icon registry. */
+  icon?: string;
+  /** Tooltip text shown on hover. Defaults to `label` when omitted. */
+  tooltip?: string;
+}
+
+/** The speaker avatar for a message row. (Mirrors the `…Data` convention of
+ *  `AttachmentData`; named to avoid clashing with the `MessageAvatar` component.) */
+export interface AvatarData {
+  /** Image URL. When present, renders an `<img>`. */
+  src?: string;
+  /** Initials/short text shown when there is no `src`. */
+  fallback?: string;
+  /** Alt text for the image. */
+  alt?: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  reasoning?: { text: string; label?: string };
+  tools?: ToolPart[];
+  attachments?: AttachmentData[];
+  /** Action buttons under the message — built-in names and/or custom descriptors. */
+  actions?: (ChatMessageAction | CustomAction)[];
+  /** Optional speaker avatar shown to the left of the message column. */
+  avatar?: AvatarData;
+}