@kitnai/chat 0.7.0 → 0.8.1

package/src/components/card.tsx

@@ -0,0 +1,110 @@
+import { type JSX, Show, splitProps, mergeProps, createUniqueId } from 'solid-js';
+import { cn } from '../utils/cn';
+import { AlertTriangle } from 'lucide-solid';
+
+export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  /** Heading rendered in the card chrome (the contract's CardEnvelope.title).
+   *  NB: NOT `title` — `title` is a reserved IDL attr (see define.tsx RESERVED). */
+  heading?: string;
+  /** Optional supporting text under the heading. */
+  description?: string;
+  /** Media region (image/icon) rendered above the heading. */
+  media?: JSX.Element;
+  /** Footer action region (buttons). */
+  actions?: JSX.Element;
+  /** When set, the card renders its standard inline error state INSTEAD of body. */
+  errorMessage?: string;
+  /** Compact spacing for dense lists of cards. */
+  dense?: boolean;
+  /** Stable id for the heading (so composing cards can `aria-labelledby` it).
+   *  Auto-generated when omitted. */
+  headingId?: string;
+}
+
+/**
+ * `Card` — the shared presentational chrome every native card composes from:
+ * an optional media region, a heading + description, a body (default slot), an
+ * actions footer, and one consistent inline **error** state (the contract's
+ * "never a broken/partial card" rule). It is intentionally chrome-only: it reads
+ * no `CardContext` and emits no `CardEvent` — the cards that compose it (e.g.
+ * `kc-form`) own the contract interaction.
+ */
+export function Card(props: CardProps): JSX.Element {
+  const merged = mergeProps({ dense: false }, props);
+  const [local, rest] = splitProps(merged, [
+    'heading',
+    'description',
+    'media',
+    'actions',
+    'errorMessage',
+    'dense',
+    'headingId',
+    'class',
+    'children',
+  ]);
+
+  const autoId = createUniqueId();
+  const headingId = () => local.headingId ?? `kc-card-heading-${autoId}`;
+  const hasError = () => local.errorMessage !== undefined && local.errorMessage !== '';
+  const hasHeader = () => Boolean(local.heading) || Boolean(local.description);
+
+  return (
+    <div
+      class={cn(
+        'flex flex-col rounded-xl border border-border bg-card text-card-foreground shadow-sm',
+        local.dense ? 'gap-2.5 p-3.5' : 'gap-4 p-5',
+        local.class,
+      )}
+      {...rest}
+    >
+      <Show when={local.media}>
+        <div class="overflow-hidden rounded-lg">{local.media}</div>
+      </Show>
+
+      <Show when={hasHeader()}>
+        <div
+          class={cn(
+            'flex flex-col border-b border-border',
+            local.dense ? 'gap-0.5 pb-2.5' : 'gap-1 pb-4',
+          )}
+        >
+          <Show when={local.heading}>
+            <h3
+              id={headingId()}
+              class="text-[1.0625rem] font-semibold leading-snug tracking-tight text-foreground"
+            >
+              {local.heading}
+            </h3>
+          </Show>
+          <Show when={local.description}>
+            <p class="text-[0.8125rem] leading-relaxed text-muted-foreground">{local.description}</p>
+          </Show>
+        </div>
+      </Show>
+
+      <Show
+        when={hasError()}
+        fallback={
+          <>
+            <Show when={local.children}>
+              <div class="text-sm text-foreground">{local.children}</div>
+            </Show>
+            <Show when={local.actions}>
+              <div class="flex flex-wrap items-center justify-end gap-2 pt-1">
+                {local.actions}
+              </div>
+            </Show>
+          </>
+        }
+      >
+        <div
+          role="alert"
+          class="flex items-start gap-2 rounded-lg border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive dark:bg-destructive/15 dark:text-red-400"
+        >
+          <AlertTriangle size={16} class="mt-0.5 shrink-0" aria-hidden="true" />
+          <span>{local.errorMessage}</span>
+        </div>
+      </Show>
+    </div>
+  );
+}

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

@@ -6,6 +6,7 @@ import {
   ChainOfThoughtContent,
   ChainOfThoughtItem,
 } from './chain-of-thought';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/ChainOfThought',
@@ -14,14 +15,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A vertical, collapsible timeline that reveals an agent\'s reasoning as a series of connected steps. Composed of `ChainOfThought` (root) wrapping `ChainOfThoughtStep` items, each with a `ChainOfThoughtTrigger`, `ChainOfThoughtContent`, and one or more `ChainOfThoughtItem`s.',
-          '**When to use:** to surface multi-step reasoning, tool calls, or research progress behind an assistant response, letting users expand each step on demand.',
-          '**How to use:** map each reasoning step to a `ChainOfThoughtStep` (mark the final one with `isLast`); put the summary in `ChainOfThoughtTrigger` and the detail inside `ChainOfThoughtContent` / `ChainOfThoughtItem`.',
-          '**Placement:** above or within an assistant message, typically before the final answer.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A vertical, collapsible timeline that reveals an agent\'s reasoning as a series of connected steps. Composed of `ChainOfThought` (root) wrapping `ChainOfThoughtStep` items, each with a `ChainOfThoughtTrigger`, `ChainOfThoughtContent`, and one or more `ChainOfThoughtItem`s.',
+        '**When to use:** to surface multi-step reasoning, tool calls, or research progress behind an assistant response, letting users expand each step on demand.',
+        '**How to use:** map each reasoning step to a `ChainOfThoughtStep` (mark the final one with `isLast`); put the summary in `ChainOfThoughtTrigger` and the detail inside `ChainOfThoughtContent` / `ChainOfThoughtItem`.',
+        '**Placement:** above or within an assistant message, typically before the final answer.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },

package/src/components/chat-container.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { For } from 'solid-js';
 import { ChatContainerRoot, ChatContainerContent, ChatContainerScrollAnchor } from './chat-container';
 import { Message, MessageAvatar, MessageContent } from './message';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const sampleMessages = [
   { role: 'user', content: 'What is SolidJS?' },
@@ -40,14 +41,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A scrollable message viewport that automatically sticks to the bottom as new content streams in. Composed of `ChatContainerRoot` (the scroll region), `ChatContainerContent` (the message stack), and `ChatContainerScrollAnchor` (the stick-to-bottom target).',
-          '**When to use:** as the conversation transcript region of a chat UI, where messages append over time and the view should follow the latest output unless the user scrolls up.',
-          '**How to use:** wrap your message list in `ChatContainerRoot`, place messages inside `ChatContainerContent`, and end with `ChatContainerScrollAnchor`. Give the root a fixed height so it can scroll.',
-          '**Placement:** the central pane of a chat layout, between the header and the prompt input.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A scrollable message viewport that automatically sticks to the bottom as new content streams in. Composed of `ChatContainerRoot` (the scroll region), `ChatContainerContent` (the message stack), and `ChatContainerScrollAnchor` (the stick-to-bottom target).',
+        '**When to use:** as the conversation transcript region of a chat UI, where messages append over time and the view should follow the latest output unless the user scrolls up.',
+        '**How to use:** wrap your message list in `ChatContainerRoot`, place messages inside `ChatContainerContent`, and end with `ChatContainerScrollAnchor`. Give the root a fixed height so it can scroll.',
+        '**Placement:** the central pane of a chat layout, between the header and the prompt input.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },

package/src/components/chat-container.tsx

@@ -30,6 +30,10 @@ function ChatContainerRoot(props: ChatContainerRootProps) {
         ref={ref}
         class={cn('flex flex-col overflow-y-auto', local.class)}
         role="log"
+        // Keyboard users must be able to scroll the conversation even when no
+        // message contains a focusable control (WCAG 2.1.1 — axe
+        // `scrollable-region-focusable`).
+        tabindex={0}
         {...rest}
       >
         {local.children}

package/src/components/checkpoint.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { Checkpoint, CheckpointIcon, CheckpointTrigger } from './checkpoint';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/Checkpoint',
@@ -9,14 +10,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'An inline marker that lets a user restore the conversation to a saved point. Composed of `Checkpoint` (row + separator) wrapping a `CheckpointIcon` and a `CheckpointTrigger` button.',
-          '**When to use:** to mark a restorable state in a transcript — e.g. before an edit or a branching action — so the user can revert to it.',
-          '**How to use:** place a `CheckpointIcon` and a `CheckpointTrigger` inside `Checkpoint`. Give the trigger an `onClick` handler and an optional `tooltip`; pass custom SVG children to `CheckpointIcon` to override the default flag.',
-          '**Placement:** between messages in a chat transcript, as a thin separator-style row.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'An inline marker that lets a user restore the conversation to a saved point. Composed of `Checkpoint` (row + separator) wrapping a `CheckpointIcon` and a `CheckpointTrigger` button.',
+        '**When to use:** to mark a restorable state in a transcript — e.g. before an edit or a branching action — so the user can revert to it.',
+        '**How to use:** place a `CheckpointIcon` and a `CheckpointTrigger` inside `Checkpoint`. Give the trigger an `onClick` handler and an optional `tooltip`; pass custom SVG children to `CheckpointIcon` to override the default flag.',
+        '**Placement:** between messages in a chat transcript, as a thin separator-style row.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },

package/src/components/checkpoint.tsx

@@ -50,6 +50,8 @@ export function CheckpointIcon(props: CheckpointIconProps) {
 
 export interface CheckpointTriggerProps {
   tooltip?: string;
+  /** Accessible name for the button — required when it has no visible text (icon-only). */
+  'aria-label'?: string;
   onClick?: () => void;
   children?: JSX.Element;
   class?: string;
@@ -70,6 +72,7 @@ export function CheckpointTrigger(props: CheckpointTriggerProps) {
       variant={variant()}
       size={size()}
       type="button"
+      aria-label={props['aria-label']}
       onClick={props.onClick}
       class={props.class}
     >

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { CodeBlock, CodeBlockCode, CodeBlockGroup } from './code-block';
 import { Button } from '../ui/button';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const tsCode = `interface User {
   id: string;
@@ -48,14 +49,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A bordered code card with optional syntax highlighting. `CodeBlock` is the container, `CodeBlockCode` renders the (Shiki-)highlighted source, and `CodeBlockGroup` is a flex row for a header/footer (filename + copy button).',
-          '**When to use:** to display code snippets in chat messages, documentation, or anywhere fenced code appears — typically emitted by the Markdown renderer for ``` blocks.',
-          '**How to use:** wrap one or more children in `<CodeBlock>`. Pass the source string and a `language` to `<CodeBlockCode>`; optionally override the `theme`. Add a `<CodeBlockGroup>` for a filename row and copy action.',
-          '**Placement:** inside assistant message content, README/docs panes, and tool-output views.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A bordered code card with optional syntax highlighting. `CodeBlock` is the container, `CodeBlockCode` renders the (Shiki-)highlighted source, and `CodeBlockGroup` is a flex row for a header/footer (filename + copy button).',
+        '**When to use:** to display code snippets in chat messages, documentation, or anywhere fenced code appears — typically emitted by the Markdown renderer for ``` blocks.',
+        '**How to use:** wrap one or more children in `<CodeBlock>`. Pass the source string and a `language` to `<CodeBlockCode>`; optionally override the `theme`. Add a `<CodeBlockGroup>` for a filename row and copy action.',
+        '**Placement:** inside assistant message content, README/docs panes, and tool-output views.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },
@@ -130,7 +129,7 @@ export const WithHeader: Story = {
       <CodeBlock>
         <CodeBlockGroup class="border-b border-border px-4 py-2">
           <span class="text-xs text-muted-foreground font-mono">user.ts</span>
-          <Button variant="ghost" size="icon-sm">
+          <Button variant="ghost" size="icon-sm" aria-label="Copy code">
             <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
               <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
               <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" />

package/src/components/code-block.tsx

@@ -65,15 +65,18 @@ function CodeBlockCode(props: CodeBlockCodeProps) {
     );
 
   return (
+    // `tabindex={0}` makes the horizontally-scrollable region reachable by
+    // keyboard (axe `scrollable-region-focusable`); `{...rest}` lets a consumer
+    // override it. No `role="region"` — that would demand an accessible name.
     <Show
       when={highlighted()}
       fallback={
-        <div class={classNames()} {...rest}>
+        <div class={classNames()} tabindex={0} {...rest}>
           <pre><code>{local.code}</code></pre>
         </div>
       }
     >
-      <div class={classNames()} innerHTML={highlighted()} {...rest} />
+      <div class={classNames()} tabindex={0} innerHTML={highlighted()} {...rest} />
     </Show>
   );
 }