@kitn.ai/ui 0.14.1

package/src/elements/chat.tsx

@@ -0,0 +1,80 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage } from '../components/chat-thread';
+import type { AttachmentData } from '../components/attachments';
+import type { SlashCommandItem } from '../components/slash-command';
+import type { ProseSize } from '../primitives/chat-config';
+import type { ModelOption } from '../types';
+
+type Props = Omit<ChatThreadProps,
+  'class' | 'onValueChange' | 'onSubmit' | 'onSuggestionClick' | 'onModelChange'
+  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'onSlashSelect'> & Record<string, unknown>;
+
+interface Events {
+  /** User submitted a message. */
+  'kai-submit': { value: string; attachments: AttachmentData[] };
+  /** Fired on every input change. */
+  'kai-value-change': { value: string };
+  /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
+  'kai-suggestion-click': { value: string };
+  /** An action button on a message was clicked. `action` is the built-in name or custom id. */
+  'kai-message-action': { messageId: string; action: string };
+  /** The header model switcher changed. */
+  'kai-model-change': { modelId: string };
+  /** A slash command was chosen from the palette. */
+  'kai-slash-select': { command: SlashCommandItem };
+  /** The Search button was clicked. */
+  'kai-search': Record<string, never>;
+  /** The Mic / voice button was clicked. */
+  'kai-voice': Record<string, never>;
+}
+
+defineWebComponent<Props, Events>('kai-chat', {
+  messages: [], value: undefined, placeholder: 'Send a message...', loading: false,
+  suggestions: undefined, suggestionMode: 'submit', persistSuggestions: false, proseSize: 'sm',
+  codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
+  models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
+  search: false, voice: false, slashCommands: undefined, slashActiveIds: undefined, slashCompact: false,
+  actionsReveal: 'always',
+}, (props, { dispatch, flag, element }) => {
+  // Detect consumer-projected header controls so the header opens for them even
+  // without a title/models/context. Mirrors the <kai-model> light-DOM read pattern.
+  const [hasHeaderStart, setHasHeaderStart] = createSignal(false);
+  const [hasHeaderEnd, setHasHeaderEnd] = createSignal(false);
+  onMount(() => {
+    const read = () => {
+      setHasHeaderStart(!!element.querySelector(':scope > [slot="header-start"]'));
+      setHasHeaderEnd(!!element.querySelector(':scope > [slot="header-end"]'));
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  return (
+  <ChatThread
+    messages={props.messages} value={props.value as string | undefined} placeholder={props.placeholder as string}
+    loading={flag('loading')} suggestions={props.suggestions as string[] | undefined}
+    suggestionMode={props.suggestionMode as 'submit' | 'fill'} persistSuggestions={flag('persistSuggestions')}
+    proseSize={props.proseSize as ProseSize}
+    codeTheme={props.codeTheme as string} codeHighlight={flag('codeHighlight')}
+    chatTitle={props.chatTitle as string | undefined} models={props.models as ModelOption[] | undefined}
+    currentModel={props.currentModel as string | undefined} context={props.context as ChatThreadContextUsage | undefined}
+    scrollButton={props.scrollButton !== false} search={flag('search')} voice={flag('voice')}
+    slashCommands={props.slashCommands as SlashCommandItem[] | undefined}
+    slashActiveIds={props.slashActiveIds as string[] | undefined} slashCompact={flag('slashCompact')}
+    actionsReveal={props.actionsReveal as 'always' | 'hover'}
+    onValueChange={(value) => dispatch('kai-value-change', { value })}
+    onSubmit={(detail) => dispatch('kai-submit', detail)}
+    onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
+    onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
+    onMessageAction={(detail) => dispatch('kai-message-action', detail)}
+    onSearch={() => dispatch('kai-search', {})}
+    onVoice={() => dispatch('kai-voice', {})}
+    onSlashSelect={(command) => dispatch('kai-slash-select', { command })}
+    headerStart={hasHeaderStart()}
+    headerEnd={hasHeaderEnd()}
+  />
+  );
+});

package/src/elements/checkpoint.stories.tsx

@@ -0,0 +1,72 @@
+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-checkpoint': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+/** Render the actual `<kai-checkpoint>` custom element configured by attributes. */
+function CheckpointElement(props: { label?: string; tooltip?: string; variant?: string; size?: string }) {
+  let el: HTMLElement | undefined;
+  onMount(() => {
+    if (!el) return;
+    if (props.label) el.setAttribute('label', props.label);
+    if (props.tooltip) el.setAttribute('tooltip', props.tooltip);
+    if (props.variant) el.setAttribute('variant', props.variant);
+    if (props.size) el.setAttribute('size', props.size);
+    el.addEventListener('kai-select', () => console.log('checkpoint selected'));
+  });
+  return <kai-checkpoint ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-checkpoint label="Restore" tooltip="Restore this checkpoint" variant="outline" size="sm"></kai-checkpoint>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const cp = document.querySelector('kai-checkpoint');
+  // events are CustomEvents on the element (they do not bubble)
+  cp.addEventListener('kai-select', () => console.log('restore checkpoint'));
+</script>`;
+
+const meta = {
+  title: 'Components/Checkpoint',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-checkpoint'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-checkpoint', [
+          '`<kai-checkpoint>` is the framework-agnostic **web component** for a bookmark/checkpoint button (with an optional tooltip and label), isolated in **Shadow DOM**.',
+          '**When to use:** marking a restore point in a conversation in a non-Solid app. In SolidJS, compose the `Checkpoint` primitives.',
+          '**Placement:** inline inside a message row (e.g. in the action bar) or in a chat toolbar; it is a compact `inline-block` button and does not need a dedicated row.',
+          "**How to use:** register once with `import '@kitn.ai/ui/elements'`, set `label`, `tooltip`, `variant` (`ghost` | `default` | `outline`), and `size` via attributes, and listen for the `kai-select` **CustomEvent** on click.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A labeled checkpoint button. (Add a `tooltip` attribute for a hover hint — see the Code tab.) */
+export const Labeled: Story = {
+  render: () => <CheckpointElement label="Restore" variant="outline" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Icon-only (no label), using an `icon` size. */
+export const IconOnly: Story = {
+  name: 'Icon Only',
+  render: () => <CheckpointElement size="icon-sm" />,
+};

package/src/elements/checkpoint.tsx

@@ -0,0 +1,47 @@
+import { Show } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Checkpoint, CheckpointIcon, CheckpointTrigger } from '../components/checkpoint';
+
+interface Props extends Record<string, unknown> {
+  /** Optional text beside the icon. */
+  label?: string;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Visual button style. */
+  variant?: 'ghost' | 'default' | 'outline';
+  /** Button size (use an `icon*` size for an icon-only checkpoint). */
+  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+}
+
+/** Events fired by `<kai-checkpoint>`. */
+interface Events {
+  /** The checkpoint was clicked. */
+  'kai-select': void;
+}
+
+/**
+ * `<kai-checkpoint>` — a bookmark/checkpoint button (optional tooltip + label).
+ * Emits `select`.
+ */
+defineWebComponent<Props, Events>('kai-checkpoint', {
+  label: undefined,
+  tooltip: undefined,
+  variant: 'ghost',
+  size: 'sm',
+}, (props, { dispatch }) => (
+  <Checkpoint>
+    <CheckpointTrigger
+      tooltip={props.tooltip}
+      // Icon-only (no visible label) needs an accessible name: prefer the
+      // tooltip text, else a sensible default. With a visible label, the text
+      // is the name — leave aria-label unset so it isn't duplicated.
+      aria-label={props.label ? undefined : (props.tooltip ?? 'Checkpoint')}
+      variant={props.variant}
+      size={props.size}
+      onClick={() => dispatch('kai-select')}
+    >
+      <CheckpointIcon />
+      <Show when={props.label}><span class="ml-1.5">{props.label}</span></Show>
+    </CheckpointTrigger>
+  </Checkpoint>
+));

package/src/elements/choice.stories.tsx

@@ -0,0 +1,240 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './choice';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { ChoiceCardData } from '../components/choice-card';
+import type { CardEvent } from '../primitives/card-contract';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-choice': JSX.HTMLAttributes<HTMLElement> & {
+        heading?: string;
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+type ChoiceEl = HTMLElement & { data?: ChoiceCardData; resolution?: Record<string, unknown> };
+
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ 'max-width': '460px' }}>{props.children}</div>;
+}
+
+/** Mounts a <kai-choice>, sets `.data`, logs the emitted CardEvent under the render. */
+function ChoiceDemo(props: { def: ChoiceCardData; cardId: string; heading?: string }) {
+  const [log, setLog] = createSignal<CardEvent[]>([]);
+  let el: ChoiceEl | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.data = props.def;
+    el.addEventListener('kai-card', (e) => {
+      const detail = (e as CustomEvent<CardEvent>).detail;
+      setLog((prev) => [...prev, detail]);
+    });
+  });
+  return (
+    <Frame>
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '12px' }}>
+        <kai-choice ref={(e) => (el = e as ChoiceEl)} card-id={props.cardId} heading={props.heading} />
+        <pre
+          style={{
+            margin: 0,
+            'max-height': '180px',
+            overflow: 'auto',
+            background: 'var(--color-muted, #f4f4f5)',
+            'border-radius': '8px',
+            padding: '8px',
+            'font-size': '12px',
+          }}
+        >
+          {log().length === 0 ? '// emitted CardEvents appear here' : JSON.stringify(log(), null, 2)}
+        </pre>
+      </div>
+    </Frame>
+  );
+}
+
+const PLANS: ChoiceCardData = {
+  prompt: 'Which plan fits your team?',
+  options: [
+    { id: 'free', label: 'Free', description: 'For trying things out', meta: '$0' },
+    {
+      id: 'pro',
+      label: 'Pro',
+      description: 'For growing teams',
+      meta: '$12/seat',
+      recommended: true,
+      payload: { plan: 'pro' },
+    },
+    { id: 'enterprise', label: 'Enterprise', description: 'SSO, audit log, SLA', meta: 'Contact us' },
+    { id: 'legacy', label: 'Legacy', description: 'No longer available', disabled: true },
+  ],
+};
+
+const TEMPLATES: ChoiceCardData = {
+  prompt: 'Pick a workspace template.',
+  submitLabel: 'Create workspace',
+  options: [
+    {
+      id: 'blank',
+      label: 'Blank',
+      description: 'Start from scratch',
+      media: { image: 'https://placehold.co/80x80/png?text=Blank', imageAlt: 'A blank canvas' },
+    },
+    {
+      id: 'kanban',
+      label: 'Kanban',
+      description: 'Board with columns',
+      recommended: true,
+      media: { image: 'https://placehold.co/80x80/png?text=Kanban', imageAlt: 'A kanban board' },
+      payload: { template: 'kanban' },
+    },
+    {
+      id: 'docs',
+      label: 'Docs',
+      description: 'Wiki-style pages',
+      media: { image: 'https://placehold.co/80x80/png?text=Docs', imageAlt: 'A document page' },
+    },
+  ],
+};
+
+const QUICK_REPLIES: ChoiceCardData = {
+  prompt: 'How did this answer land?',
+  options: [
+    { id: 'great', label: 'That solved it', payload: { sentiment: 'positive' } },
+    { id: 'partly', label: 'Partly — needs more', payload: { sentiment: 'neutral' } },
+    { id: 'no', label: 'Not what I meant', payload: { sentiment: 'negative' } },
+  ],
+  allowOther: { label: 'Something else…', placeholder: 'Tell me what you expected' },
+};
+
+const HEADING_MAP: Record<string, string | undefined> = {
+  'card-plans': 'Choose a plan',
+  'card-templates': 'New workspace',
+  'card-replies': undefined,
+};
+
+const HTML_SNIPPET = (def: ChoiceCardData, cardId: string) => {
+  const heading = HEADING_MAP[cardId];
+  return `<kai-choice${heading ? ` heading="${heading}"` : ''}></kai-choice>
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers the custom elements
+
+  const el = document.querySelector('kai-choice');
+  // \`data\` is the CardEnvelope.data (set as a property).
+  el.data = ${JSON.stringify(def, null, 2)};
+
+  // Cards bubble ONE \`kai-card\` CustomEvent carrying a typed CardEvent.
+  el.addEventListener('kai-card', (e) => {
+    const ev = e.detail; // { kind:'action', cardId, action, payload? } | { kind:'ready', ... } | ...
+    if (ev.kind === 'action') console.log('chose', ev.action, ev.payload);
+  });
+</script>`;
+};
+
+const meta = {
+  title: 'Generative UI/Cards/kai-choice',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-choice'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kai-choice', [
+        "`<kai-choice>` is a **single-select** 'pick one of N rich options' card (set via the `data` **property**): an optional prompt + a radiogroup of list rows + a **Submit** button. Clicking a row (or Space/Enter on the focused row) **selects** it locally — nothing is emitted. Submit then emits the Card contract's **`action`** verb up a bubbling **`kai-card`** CustomEvent of `{ kind:'action', cardId, action: option.id, payload? }`, then **resolves** the card (the chosen option shown read-only) so the same pick can't double-fire. The Submit label is `submitLabel` (default 'Submit').",
+        '**Rich-but-bounded options:** every field except `id`/`label` is optional — `description`, `media` (image + `imageAlt`, or a named `icon`), `meta` (trailing price/badge), `recommended` (a pill), `disabled` (inert + skipped in keyboard nav), and an opaque `payload` echoed back. A weaker model can just omit them.',
+        "**`allowOther`** (opt-in) appends a final 'Other…' row: selecting it reveals an inline text input. The single shared **Submit** stays disabled until the text is non-empty; submitting emits `{ kind:'action', action:'__other__', payload:{ text } }`.",
+        '**Accessibility:** the options are a WAI-ARIA `radiogroup` (`role="radio"` + `aria-checked`) with **roving tabindex** — one tab stop in, Arrow keys move focus (skipping disabled), Enter/Space select the focused row. Disabled options are `aria-disabled` and not focusable; option images carry alt text; the Other input has a label. **0 axe violations** (light + dark).',
+        '**Events** (all frozen Card-contract verbs): `ready` on mount, `action` on Submit, `error` for a malformed definition (renders the inline `kai-card` error). It **never invents events**, and — because it carries a registry entry — `<kai-cards>` / `renderCard` dispatch it automatically.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A list of plans with a `recommended` pill, `meta` prices, and a disabled legacy row.
+ *  Select a row, then click Submit to emit the `action`. */
+export const Plans: Story = {
+  render: () => <ChoiceDemo def={PLANS} cardId="card-plans" heading="Choose a plan" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(PLANS, 'card-plans'), language: 'html' } } },
+};
+
+/** Rows with leading images (each `media.image` carries `imageAlt`) and a custom `submitLabel`. */
+export const WithMedia: Story = {
+  render: () => <ChoiceDemo def={TEMPLATES} cardId="card-templates" heading="New workspace" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(TEMPLATES, 'card-templates'), language: 'html' } } },
+};
+
+/** Quick replies with the `allowOther` free-text escape: select Other, type, then Submit. */
+export const AllowOther: Story = {
+  render: () => <ChoiceDemo def={QUICK_REPLIES} cardId="card-replies" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(QUICK_REPLIES, 'card-replies'), language: 'html' } } },
+};
+
+const RESOLVED_CHOICE: ChoiceCardData = {
+  prompt: 'Which plan?',
+  options: [
+    { id: 'free', label: 'Free', meta: '$0' },
+    { id: 'pro', label: 'Pro', meta: '$20/mo' },
+  ],
+};
+
+/** The card after the user chose **Pro** — only the chosen option shown, no radiogroup or Submit. */
+export const Resolved: Story = {
+  name: 'Resolved (read-only)',
+  render: () => {
+    let el: ChoiceEl | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.data = RESOLVED_CHOICE;
+      el.resolution = { kind: 'action', action: 'pro' };
+    });
+    return (
+      <Frame>
+        <kai-choice ref={(e) => (el = e as ChoiceEl)} card-id="card-resolved-choice" heading="Choose a plan" />
+      </Frame>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `<kai-choice heading="Choose a plan"></kai-choice>
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const el = document.querySelector('kai-choice');
+  el.data = ${JSON.stringify(RESOLVED_CHOICE, null, 2)};
+  // Setting .resolution renders the chromed read-only view — no radiogroup or Submit.
+  el.resolution = { kind: 'action', action: 'pro' };
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};
+
+/** A malformed `data` (empty `options`) → the inline error state + an `error` event. */
+export const ErrorState: Story = {
+  render: () => <ChoiceDemo def={{ options: [] } as unknown as ChoiceCardData} cardId="card-bad" />,
+  parameters: {
+    docs: {
+      source: {
+        code: `<kai-choice></kai-choice>
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const el = document.querySelector('kai-choice');
+  // No options → inline error state + an \`error\` event.
+  el.data = { options: [] };
+  el.addEventListener('kai-card', (e) => {
+    if (e.detail.kind === 'error') console.warn('choice error:', e.detail.message);
+  });
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};

package/src/elements/choice.tsx

@@ -0,0 +1,48 @@
+import { defineWebComponent } from './define';
+import { ChoiceCard, type ChoiceCardData } from '../components/choice-card';
+import type { CardResolution } from '../primitives/card-contract';
+
+interface Props extends Record<string, unknown> {
+  /** The choice definition (the CardEnvelope.data). Set as a JS PROPERTY:
+   *  `el.data = { prompt, options:[…], allowOther?, submitLabel? }`. Import
+   *  `ChoiceCardData` from `@kitn.ai/ui` for the full shape. */
+  data?: Record<string, unknown>;
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Set when the user resolved this card; renders the read-only view. Property:
+   *  `el.resolution = { kind:'action', action:'…' }`. */
+  resolution?: Record<string, unknown>;
+}
+
+/**
+ * `<kai-choice>` — a single-select **"pick one of N rich options"** card (set via the
+ * `data` property): a prompt + a radiogroup of list rows. Clicking a row **selects** it
+ * (no emit); the **Submit** button below then emits the Card contract's **`action`** verb
+ * up a bubbling **`kai-card`** CustomEvent (`{ kind:'action', cardId, action: option.id,
+ * payload? }`) and resolves the card so the same pick can't double-fire. An optional
+ * `allowOther` free-text escape appends a selectable "Other…" row that reveals an inline
+ * input; the same Submit emits `action:'__other__'` with `{ text }`. Also emits `ready` on
+ * mount and `error` for a malformed definition (inline error). Routes through a
+ * `CardProvider` when present, else the bubbling `kai-card` event. Isolated in Shadow DOM;
+ * theme-aware via the shared tokens.
+ */
+defineWebComponent<Props>(
+  'kai-choice',
+  {
+    data: undefined,
+    cardId: undefined,
+    heading: undefined,
+    resolution: undefined,
+  },
+  (props, { element }) => (
+    <ChoiceCard
+      data={props.data as ChoiceCardData | undefined}
+      cardId={props.cardId ?? (element.id || 'kai-choice')}
+      heading={props.heading}
+      resolution={props.resolution as CardResolution | undefined}
+      hostElement={element}
+    />
+  ),
+);

package/src/elements/code-block.stories.tsx

@@ -0,0 +1,83 @@
+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-code-block': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleCode = `export function add(a: number, b: number): number {
+  return a + b;
+}`;
+
+const pythonCode = `def fib(n):
+    a, b = 0, 1
+    for _ in range(n):
+        a, b = b, a + b
+    return a`;
+
+/** Render the actual `<kai-code-block>` custom element with a `code` property. */
+function CodeBlockElement(props: { code: string; language?: string }) {
+  let el: (HTMLElement & { code?: string }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.code = props.code;
+      if (props.language) el.setAttribute('language', props.language);
+    }
+  });
+  return (
+    <kai-code-block
+      ref={(e) => (el = e as HTMLElement)}
+      style={{ display: 'block', padding: '16px', 'max-width': '720px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-code-block id="code" language="ts" code-theme="github-dark-dimmed"></kai-code-block>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const code = document.getElementById('code');
+  code.code = 'export function add(a, b) {\\n  return a + b;\\n}';
+</script>`;
+
+const meta = {
+  title: 'Components/CodeBlock',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-code-block'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-code-block', [
+          '`<kai-code-block>` is the framework-agnostic **web component** for a single syntax-highlighted code block, complete with a copy button, isolated in **Shadow DOM**.',
+          '**When to use:** dropping a highlighted snippet into a non-Solid app. In SolidJS, compose `CodeBlock` + `CodeBlockCode` directly.',
+          '**Placement:** as a block inside a message row, tutorial card, or documentation pane; it is `display: block` and fills container width, so set `max-width` on the parent or the element to control line lengths.',
+          "**How to use:** register once with `import '@kitn.ai/ui/elements'`, set the source via the `code` **property** (`el.code = '...'`), and pick a grammar with the `language` attribute (defaults to `tsx`). Tune highlighting with `code-theme` / `code-highlight`.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A TypeScript snippet (the default `tsx` grammar). */
+export const TypeScript: Story = {
+  render: () => <CodeBlockElement code={sampleCode} language="ts" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A different grammar via the `language` attribute. */
+export const Python: Story = {
+  render: () => <CodeBlockElement code={pythonCode} language="python" />,
+};

package/src/elements/code-block.tsx

@@ -0,0 +1,42 @@
+import { defineWebComponent } from './define';
+import { CodeBlock, CodeBlockCode } from '../components/code-block';
+import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
+
+interface Props extends Record<string, unknown> {
+  /** The source code to render. */
+  code: string;
+  /** Language grammar (e.g. `js`, `python`). Defaults to `tsx`. */
+  language?: string;
+  /** Shiki theme name. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (renders plain text, no Shiki). */
+  codeHighlight?: boolean;
+  /** Code text sizing. */
+  proseSize?: ProseSize;
+}
+
+/**
+ * `<kai-code-block>` — one syntax-highlighted code block (with a copy button).
+ * Code via the `code` property; `language`/`code-theme` via attributes.
+ */
+defineWebComponent<Props>('kai-code-block', {
+  code: '',
+  language: undefined,
+  codeTheme: 'github-dark-dimmed',
+  codeHighlight: true,
+  proseSize: 'sm',
+}, (props, { flag }) => {
+  const outer = useChatConfig();
+  return (
+    <ChatConfig
+      proseSize={props.proseSize}
+      codeTheme={props.codeTheme}
+      codeHighlight={flag('codeHighlight')}
+      portalMount={outer.portalMount()}
+    >
+      <CodeBlock>
+        <CodeBlockCode code={props.code} language={props.language} />
+      </CodeBlock>
+    </ChatConfig>
+  );
+});