@kitn.ai/ui 0.14.1

package/src/components/thinking-bar.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { fn } from 'storybook/test';
+import { ThinkingBar } from './thinking-bar';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Elements/ThinkingBar',
+  component: ThinkingBar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'A status row that shows a shimmering "thinking" label, optionally clickable to expand reasoning, with an optional stop/cancel action.',
+        '**When to use:** while the assistant is generating or reasoning, to show live activity and give the user a way to interrupt or to open the reasoning trace.',
+        '**How to use:** set `text` for the label. Pass `onClick` to make the label a button (adds a chevron) — typically to toggle a reasoning panel. Pass `onStop` (with optional `stopLabel`) to render the interrupt action.',
+        '**Placement:** above or in place of a streaming message, or at the top of a reasoning/chain-of-thought block.',
+      ]),
+    },
+  },
+  argTypes: {
+    text: {
+      control: 'text',
+      description: 'Label shown with the shimmer effect.',
+      table: { defaultValue: { summary: 'Thinking' } },
+    },
+    stopLabel: {
+      control: 'text',
+      description: 'Label for the stop/cancel action (only shown when `onStop` is set).',
+      table: { defaultValue: { summary: 'Answer now' } },
+    },
+    class: {
+      control: 'text',
+      description: 'Additional CSS classes for the container.',
+    },
+    onClick: {
+      action: 'click',
+      description: 'When set, the label becomes a button (with chevron) and this fires on click.',
+      table: { category: 'Events' },
+    },
+    onStop: {
+      action: 'stop',
+      description: 'When set, renders the stop action and fires when it is clicked.',
+      table: { category: 'Events' },
+    },
+  },
+  args: {
+    text: 'Thinking',
+    stopLabel: 'Answer now',
+    onStop: fn(),
+  },
+  render: (args) => <ThinkingBar {...args} />,
+} satisfies Meta<typeof ThinkingBar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { ThinkingBar } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — tweak the controls to explore the thinking bar. */
+export const Playground: Story = {
+  ...src(`<ThinkingBar text="Thinking" onStop={() => stop()} />`),
+};
+
+export const Default: Story = {
+  args: { onStop: undefined } as never,
+  ...src(`<ThinkingBar />`),
+};
+
+export const WithStopButton: Story = {
+  args: { onStop: fn() },
+  ...src(`<ThinkingBar onStop={() => stopGeneration()} />`),
+};
+
+export const CustomText: Story = {
+  args: { text: 'Analyzing documents', stopLabel: 'Cancel', onStop: fn() },
+  ...src(`<ThinkingBar text="Analyzing documents" stopLabel="Cancel" onStop={() => cancel()} />`),
+};
+
+export const Clickable: Story = {
+  args: { text: 'Reasoning', onClick: fn(), onStop: fn() },
+  ...src(`<ThinkingBar\n  text="Reasoning"\n  onClick={() => toggleReasoning()}\n  onStop={() => stop()}\n/>`),
+};

package/src/components/thinking-bar.tsx

@@ -0,0 +1,50 @@
+import { type JSX, splitProps, Show } from 'solid-js';
+import { cn } from '../utils/cn';
+import { TextShimmer } from './text-shimmer';
+import { ChevronRight } from 'lucide-solid';
+
+export interface ThinkingBarProps {
+  class?: string;
+  text?: string;
+  onStop?: () => void;
+  stopLabel?: string;
+  onClick?: () => void;
+}
+
+function ThinkingBar(props: ThinkingBarProps) {
+  const [local] = splitProps(props, ['class', 'text', 'onStop', 'stopLabel', 'onClick']);
+
+  const text = () => local.text ?? 'Thinking';
+  const stopLabel = () => local.stopLabel ?? 'Answer now';
+
+  return (
+    <div class={cn('flex w-full items-center justify-between', local.class)}>
+      <Show
+        when={local.onClick}
+        fallback={
+          <TextShimmer class="cursor-default text-sm font-medium">{text()}</TextShimmer>
+        }
+      >
+        <button
+          type="button"
+          onClick={local.onClick}
+          class="flex items-center gap-1 text-sm transition-opacity hover:opacity-80"
+        >
+          <TextShimmer class="text-sm font-medium">{text()}</TextShimmer>
+          <ChevronRight class="text-muted-foreground size-4" />
+        </button>
+      </Show>
+      <Show when={local.onStop}>
+        <button
+          onClick={local.onStop}
+          type="button"
+          class="text-muted-foreground hover:text-foreground border-muted-foreground/50 hover:border-foreground border-b border-dotted text-sm transition-colors"
+        >
+          {stopLabel()}
+        </button>
+      </Show>
+    </div>
+  );
+}
+
+export { ThinkingBar };

package/src/components/tool.stories.tsx

@@ -0,0 +1,153 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { Tool } from './tool';
+import type { ToolPart } from './tool';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const streamingPart: ToolPart = {
+  type: 'search_documents',
+  state: 'input-streaming',
+  input: { query: 'SolidJS reactive primitives' },
+  toolCallId: 'call_abc123',
+};
+
+const readyPart: ToolPart = {
+  type: 'search_documents',
+  state: 'input-available',
+  input: { query: 'SolidJS reactive primitives', limit: 10 },
+  toolCallId: 'call_abc123',
+};
+
+const completedPart: ToolPart = {
+  type: 'search_documents',
+  state: 'output-available',
+  input: { query: 'SolidJS reactive primitives', limit: 10 },
+  output: { results: [{ title: 'Signals', score: 0.95 }, { title: 'Effects', score: 0.87 }] },
+  toolCallId: 'call_abc123',
+};
+
+const errorPart: ToolPart = {
+  type: 'search_documents',
+  state: 'output-error',
+  input: { query: 'SolidJS reactive primitives' },
+  errorText: 'Connection timeout: unable to reach the search service after 30 seconds.',
+  toolCallId: 'call_abc123',
+};
+
+const meta = {
+  title: 'Solid (Advanced)/Elements/Tool',
+  component: Tool,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'A collapsible panel that visualizes a single tool call — its name, state (processing / ready / completed / error), input, output, error, and call ID.',
+        '**When to use:** to surface assistant tool/function calls in the conversation, so users can inspect what was run and what came back.',
+        '**How to use:** pass a `toolPart` describing the call (`type`, `state`, optional `input`, `output`, `errorText`, `toolCallId`). State drives the icon and badge automatically. Set `defaultOpen` to start expanded.',
+        '**Placement:** inline within an assistant message, typically between text segments where the tool was invoked.',
+      ]),
+    },
+  },
+  argTypes: {
+    toolPart: {
+      control: 'object',
+      description: 'The tool call to render — `type`, `state`, and optional `input`/`output`/`errorText`/`toolCallId`.',
+    },
+    defaultOpen: {
+      control: 'boolean',
+      description: 'Whether the panel starts expanded.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    class: {
+      control: 'text',
+      description: 'Additional CSS classes for the container.',
+    },
+  },
+  args: {
+    toolPart: completedPart,
+    defaultOpen: true,
+  },
+  render: (args) => <Tool {...args} />,
+} satisfies Meta<typeof Tool>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Tool } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — edit the `toolPart` object to explore every state. */
+export const Playground: Story = {
+  ...src(`<Tool
+  toolPart={{
+    type: 'search_documents',
+    state: 'output-available',
+    input: { query: 'SolidJS reactive primitives', limit: 10 },
+    output: { results: [{ title: 'Signals', score: 0.95 }] },
+    toolCallId: 'call_abc123',
+  }}
+  defaultOpen
+/>`),
+};
+
+export const Processing: Story = {
+  args: { toolPart: streamingPart, defaultOpen: true },
+  ...src(`<Tool
+  toolPart={{
+    type: 'search_documents',
+    state: 'input-streaming',
+    input: { query: 'SolidJS reactive primitives' },
+    toolCallId: 'call_abc123',
+  }}
+  defaultOpen
+/>`),
+};
+
+export const Ready: Story = {
+  args: { toolPart: readyPart, defaultOpen: true },
+  ...src(`<Tool
+  toolPart={{
+    type: 'search_documents',
+    state: 'input-available',
+    input: { query: 'SolidJS reactive primitives', limit: 10 },
+    toolCallId: 'call_abc123',
+  }}
+  defaultOpen
+/>`),
+};
+
+export const Completed: Story = {
+  args: { toolPart: completedPart, defaultOpen: true },
+  ...src(`<Tool
+  toolPart={{
+    type: 'search_documents',
+    state: 'output-available',
+    input: { query: 'SolidJS reactive primitives', limit: 10 },
+    output: { results: [{ title: 'Signals', score: 0.95 }, { title: 'Effects', score: 0.87 }] },
+    toolCallId: 'call_abc123',
+  }}
+  defaultOpen
+/>`),
+};
+
+export const Error: Story = {
+  args: { toolPart: errorPart, defaultOpen: true },
+  ...src(`<Tool
+  toolPart={{
+    type: 'search_documents',
+    state: 'output-error',
+    input: { query: 'SolidJS reactive primitives' },
+    errorText: 'Connection timeout: unable to reach the search service after 30 seconds.',
+    toolCallId: 'call_abc123',
+  }}
+  defaultOpen
+/>`),
+};
+
+export const Collapsed: Story = {
+  args: { toolPart: completedPart, defaultOpen: false },
+  ...src(`<Tool toolPart={toolPart} />`),
+};

package/src/components/tool.tsx

@@ -0,0 +1,184 @@
+import { type JSX, splitProps, createSignal, Show, For } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '../ui/collapsible';
+import { Button } from '../ui/button';
+import { CheckCircle, ChevronDown, Loader2, Settings, XCircle } from 'lucide-solid';
+
+export interface ToolPart {
+  type: string;
+  state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
+  input?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+  toolCallId?: string;
+  errorText?: string;
+}
+
+export interface ToolProps {
+  toolPart: ToolPart;
+  defaultOpen?: boolean;
+  class?: string;
+}
+
+function formatValue(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'object') return JSON.stringify(value, null, 2);
+  return String(value);
+}
+
+function ToolStateIcon(props: { state: ToolPart['state'] }) {
+  return (
+    <>
+      <Show when={props.state === 'input-streaming'}>
+        <Loader2 class="size-4 animate-spin text-blue-500" />
+      </Show>
+      <Show when={props.state === 'input-available'}>
+        <Settings class="size-4 text-orange-500" />
+      </Show>
+      <Show when={props.state === 'output-available'}>
+        <CheckCircle class="size-4 text-green-500" />
+      </Show>
+      <Show when={props.state === 'output-error'}>
+        <XCircle class="size-4 text-red-500" />
+      </Show>
+    </>
+  );
+}
+
+// Status chips: a hue as text over a 15% translucent fill of the same hue
+// (mirroring the inline-code chip). The TEXT color comes from a theme token
+// (--color-tool-*) whose light value is darkened so it reaches WCAG AA (4.5:1)
+// on the faint fill, while dark mode keeps a brighter hue for AA on the dark
+// surface — both modes resolve via the token's `.dark` override. The FILL keeps
+// a fixed bright hue so the chip's colored tint looks the same in both modes.
+const STATE_TOKEN: Record<ToolPart['state'], string> = {
+  'input-streaming': 'var(--color-tool-blue)',
+  'input-available': 'var(--color-tool-amber)',
+  'output-available': 'var(--color-tool-green)',
+  'output-error': 'var(--color-tool-red)',
+};
+const STATE_FILL: Record<ToolPart['state'], string> = {
+  'input-streaming': 'hsl(217 91% 60%)', // blue
+  'input-available': 'hsl(38 92% 50%)', // amber
+  'output-available': 'hsl(142 71% 45%)', // green
+  'output-error': 'hsl(0 84% 60%)', // red
+};
+
+function stateChip(state: ToolPart['state']): JSX.CSSProperties {
+  return {
+    color: STATE_TOKEN[state],
+    background: `color-mix(in oklab, ${STATE_FILL[state]} 15%, transparent)`,
+  };
+}
+
+function ToolStateBadge(props: { state: ToolPart['state'] }) {
+  const baseClasses = 'px-2 py-1 rounded-full text-xs font-medium';
+  return (
+    <>
+      <Show when={props.state === 'input-streaming'}>
+        <span class={baseClasses} style={stateChip('input-streaming')}>
+          Processing
+        </span>
+      </Show>
+      <Show when={props.state === 'input-available'}>
+        <span class={baseClasses} style={stateChip('input-available')}>
+          Ready
+        </span>
+      </Show>
+      <Show when={props.state === 'output-available'}>
+        <span class={baseClasses} style={stateChip('output-available')}>
+          Completed
+        </span>
+      </Show>
+      <Show when={props.state === 'output-error'}>
+        <span class={baseClasses} style={stateChip('output-error')}>
+          Error
+        </span>
+      </Show>
+    </>
+  );
+}
+
+function Tool(props: ToolProps) {
+  const [local, rest] = splitProps(props, ['toolPart', 'defaultOpen', 'class']);
+  const [isOpen, setIsOpen] = createSignal(local.defaultOpen ?? false);
+
+  const state = () => local.toolPart.state;
+  const input = () => local.toolPart.input;
+  const output = () => local.toolPart.output;
+
+  return (
+    <div class={cn('mt-3 overflow-hidden rounded-lg bg-muted/30', local.class)}>
+      <Collapsible open={isOpen()} onOpenChange={setIsOpen}>
+        <CollapsibleTrigger
+          as={(triggerProps: JSX.HTMLAttributes<HTMLButtonElement>) => (
+            <Button
+              variant="ghost"
+              class="h-auto w-full justify-between rounded-b-none px-3 py-2 font-normal"
+              {...triggerProps}
+            >
+              <div class="flex items-center gap-2">
+                <ToolStateIcon state={state()} />
+                <span class="font-mono text-sm font-medium">{local.toolPart.type}</span>
+                <ToolStateBadge state={state()} />
+              </div>
+              <ChevronDown class={cn('size-4 transition-transform', isOpen() && 'rotate-180')} />
+            </Button>
+          )}
+        />
+        <CollapsibleContent
+          class="data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down overflow-hidden"
+        >
+          <div class="space-y-3 p-3">
+            <Show when={input() && Object.keys(input()!).length > 0}>
+              <div>
+                <h4 class="text-muted-foreground mb-2 text-sm font-medium">Input</h4>
+                <div class="rounded bg-muted/50 p-2 font-mono text-sm">
+                  <For each={Object.entries(input()!)}>
+                    {([key, value]) => (
+                      <div class="mb-1">
+                        <span class="text-muted-foreground">{key}:</span>{' '}
+                        <span>{formatValue(value)}</span>
+                      </div>
+                    )}
+                  </For>
+                </div>
+              </div>
+            </Show>
+
+            <Show when={output()}>
+              <div>
+                <h4 class="text-muted-foreground mb-2 text-sm font-medium">Output</h4>
+                <div tabindex={0} class="max-h-60 overflow-auto rounded bg-muted/50 p-2 font-mono text-sm">
+                  <pre class="whitespace-pre-wrap">{formatValue(output())}</pre>
+                </div>
+              </div>
+            </Show>
+
+            <Show when={state() === 'output-error' && local.toolPart.errorText}>
+              <div>
+                <h4 class="mb-2 text-sm font-medium text-red-600 dark:text-red-400">Error</h4>
+                <div class="rounded bg-red-500/10 p-2 text-sm">
+                  {local.toolPart.errorText}
+                </div>
+              </div>
+            </Show>
+
+            <Show when={state() === 'input-streaming'}>
+              <div class="text-muted-foreground text-sm">Processing tool call...</div>
+            </Show>
+
+            <Show when={local.toolPart.toolCallId}>
+              <div class="text-muted-foreground pt-2 text-xs">
+                <span class="font-mono">Call ID: {local.toolPart.toolCallId}</span>
+              </div>
+            </Show>
+          </div>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  );
+}
+
+export { Tool };

package/src/components/use-card-resolution.ts

@@ -0,0 +1,28 @@
+// Shared resolution controller for interactive cards. Precedence:
+//   props.resolution  (host-driven / re-hydrated)   >   local optimistic flip   >   none
+// A new `data` identity clears the local flip (a fresh card definition is interactive
+// again), but an explicit prop keeps it resolved. `isOptimistic` is true only for a
+// flip made this session (used to announce via role="status"; silent on re-hydrate).
+import { createSignal, createMemo, createEffect, on, type Accessor } from 'solid-js';
+import type { CardResolution } from '../primitives/card-contract';
+
+export interface ResolutionController {
+  resolution: Accessor<CardResolution | undefined>;
+  isResolved: Accessor<boolean>;
+  isOptimistic: Accessor<boolean>;
+  setLocal: (r: CardResolution) => void;
+}
+
+export function useCardResolution(opts: {
+  prop: Accessor<CardResolution | undefined>;
+  data: Accessor<unknown>;
+}): ResolutionController {
+  const [local, setLocal] = createSignal<CardResolution | undefined>(undefined);
+  // Reset the optimistic flip when a NEW data identity arrives (deferred so mount
+  // doesn't clobber an initial prop). The prop still wins via the memo below.
+  createEffect(on(opts.data, () => setLocal(undefined), { defer: true }));
+  const resolution = createMemo(() => opts.prop() ?? local());
+  const isResolved = createMemo(() => resolution() !== undefined);
+  const isOptimistic = createMemo(() => opts.prop() === undefined && local() !== undefined);
+  return { resolution, isResolved, isOptimistic, setLocal };
+}

package/src/components/voice-input.stories.tsx

@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { fn } from 'storybook/test';
+import { VoiceInput } from './voice-input';
+import { componentDescription } from '../stories/docs/element-controls';
+
+/** Sample transcription handler — resolves the recorded audio to text. */
+const transcribe = async (_audio: Blob): Promise<string> => {
+  await new Promise((r) => setTimeout(r, 1200));
+  return 'Hello from the microphone';
+};
+
+const meta = {
+  title: 'Solid (Advanced)/Elements/VoiceInput',
+  component: VoiceInput,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'A microphone button that records audio, shows recording (pulse rings) and processing (spinner) states, then hands the audio off for transcription.',
+        '**When to use:** to let users dictate input by voice instead of typing — speech-to-text for the prompt field.',
+        '**How to use:** provide `onTranscribe(audio)` returning a `Promise<string>` (your STT call) and `onTranscription(text)` to receive the result. Click toggles recording; transcription runs automatically on stop. Set `disabled` to block input.',
+        '**Placement:** inside the prompt input action bar, next to send and other input actions.',
+      ]),
+    },
+  },
+  argTypes: {
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the button (also disabled while transcribing).',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    class: {
+      control: 'text',
+      description: 'Additional CSS classes for the container.',
+    },
+    onTranscribe: {
+      action: 'transcribe',
+      description: 'Receives the recorded audio `Blob` and must resolve to the transcribed text.',
+      table: { category: 'Events' },
+    },
+    onTranscription: {
+      action: 'transcription',
+      description: 'Called with the final transcribed text (trimmed, non-empty).',
+      table: { category: 'Events' },
+    },
+  },
+  args: {
+    disabled: false,
+    onTranscribe: transcribe,
+    onTranscription: fn(),
+  },
+  render: (args) => <VoiceInput {...args} />,
+} satisfies Meta<typeof VoiceInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { VoiceInput } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — click the mic to record (requires mic permission). */
+export const Playground: Story = {
+  ...src(`<VoiceInput
+  onTranscribe={async (audio) => {
+    const res = await transcribeAudio(audio); // your STT call
+    return res.text;
+  }}
+  onTranscription={(text) => setInput((v) => v + text)}
+/>`),
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+  ...src(`<VoiceInput
+  disabled
+  onTranscribe={transcribe}
+  onTranscription={(text) => setInput(text)}
+/>`),
+};