@kitnai/chat 0.3.1 → 0.5.0

package/src/elements/kitn-reasoning.stories.tsx

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-reasoning': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleText =
+  'First I parse the request, then I plan the steps, then I execute and verify each one before responding.';
+
+/** Render the actual `<kitn-reasoning>` custom element with a `text` property. */
+function ReasoningElement(props: { text: string; streaming?: boolean }) {
+  let el: (HTMLElement & { text?: string; streaming?: boolean }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.text = props.text;
+      if (props.streaming) el.streaming = true;
+    }
+  });
+  return (
+    <kitn-reasoning ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-reasoning id="reason" label="Reasoning"></kitn-reasoning>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const reason = document.getElementById('reason');
+  reason.text = 'First I parse the request, then I plan the steps, then I execute.';
+  // reason.streaming = true;  // auto-expands while a thought streams in
+
+  // events are CustomEvents on the element (they do not bubble)
+  reason.addEventListener('openchange', (e) => console.log('open:', e.detail.open));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-reasoning',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-reasoning>` is the framework-agnostic **web component** for a collapsible reasoning/thinking block that auto-expands while a thought is `streaming`, isolated in **Shadow DOM**.',
+          '**When to use:** surfacing model chain-of-thought in a non-Solid app. In SolidJS, compose the `Reasoning` primitives directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the body via the `text` **property**, set the `streaming` flag while it streams in, optionally drive the controlled `open` property, and listen for the `openchange` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A collapsed reasoning block (the trigger toggles it). */
+export const Default: Story = {
+  render: () => <ReasoningElement text={sampleText} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** With `streaming` set, the block auto-expands. */
+export const Streaming: Story = {
+  render: () => <ReasoningElement text={sampleText} streaming />,
+};

package/src/elements/kitn-response-stream.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-response-stream': JSX.HTMLAttributes<HTMLElement> & {
+        mode?: string;
+        speed?: number;
+      };
+    }
+  }
+}
+
+const STREAM_TEXT =
+  "This text reveals with a typewriter animation, streamed character by character — exactly how you'd render a live assistant reply.";
+
+/** Render `<kitn-response-stream>` with the `text` set as a JS property. */
+function StreamElement(props: { text: string; mode?: string; speed?: number }) {
+  let el: (HTMLElement & { text?: string }) | undefined;
+  onMount(() => {
+    if (el) el.text = props.text;
+  });
+  return (
+    <kitn-response-stream
+      ref={(e) => (el = e as HTMLElement)}
+      mode={props.mode}
+      speed={props.speed}
+      style={{ display: 'block', padding: '24px', 'max-width': '640px', 'line-height': 1.6 }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-response-stream id="stream" mode="typewriter" speed="20"></kitn-response-stream>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const stream = document.getElementById('stream');
+  // text can be a string, or an AsyncIterable<string> for live streaming
+  stream.text = "Hello, this reveals one character at a time…";
+  stream.addEventListener('complete', () => console.log('done'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-response-stream',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-response-stream>` is the framework-agnostic **web component** that reveals text with a typewriter or fade animation — the building block for streamed assistant replies, isolated in **Shadow DOM**.',
+          '**When to use:** animating a response as it arrives. Pass a finished string to replay an animation, or an `AsyncIterable<string>` to drive it from a live stream. In SolidJS, use the `ResponseStream` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text` **property** (string or async iterable), tune `mode` (`typewriter` / `fade`) and `speed`, and listen for the `complete` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Typewriter reveal (the default). */
+export const Typewriter: Story = {
+  render: () => <StreamElement text={STREAM_TEXT} mode="typewriter" speed={20} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Fade-in reveal, segment by segment. */
+export const Fade: Story = {
+  render: () => <StreamElement text={STREAM_TEXT} mode="fade" speed={10} />,
+};

package/src/elements/kitn-source-list.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-source-list': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+interface SourceItem {
+  href: string;
+  title?: string;
+  description?: string;
+  label?: string;
+  showFavicon?: boolean;
+}
+
+const sampleSources: SourceItem[] = [
+  { href: 'https://kitn.dev', title: 'kitn — the kit', description: 'Composable SolidJS + web-component chat UI.', showFavicon: true },
+  { href: 'https://solidjs.com', title: 'SolidJS', description: 'A reactive UI library.', showFavicon: true },
+];
+
+/** Render the actual `<kitn-source-list>` custom element with a `sources` property. */
+function SourceListElement() {
+  let el: (HTMLElement & { sources?: SourceItem[] }) | undefined;
+  onMount(() => {
+    if (el) el.sources = sampleSources;
+  });
+  return (
+    <kitn-source-list ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-source-list id="srcs" show-favicon></kitn-source-list>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const srcs = document.getElementById('srcs');
+  srcs.sources = [
+    { href: 'https://kitn.dev', title: 'kitn — the kit', description: 'Composable chat UI.' },
+    { href: 'https://solidjs.com', title: 'SolidJS', description: 'A reactive UI library.' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-source-list',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-source-list>` is the framework-agnostic **web component** for a wrapped row of citation links (each with its own hover-card preview), isolated in **Shadow DOM**.',
+          '**When to use:** showing the sources behind an assistant answer in a non-Solid app. For a single citation, use `<kitn-source>`; in SolidJS, compose `SourceList` + `Source`.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the data via the `sources` **property** (each item: `href`, `title`, `description`, `label`, `showFavicon`), and set `show-favicon` to enable favicons for all items (a per-item `showFavicon` overrides it).",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Two citations rendered as a wrapped list with favicons. */
+export const Default: Story = {
+  render: () => <SourceListElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-source.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-source': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+/** Render the actual `<kitn-source>` custom element configured by attributes. */
+function SourceElement(props: {
+  href: string;
+  label?: string;
+  headline?: string;
+  description?: string;
+  showFavicon?: boolean;
+}) {
+  let el: HTMLElement | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.setAttribute('href', props.href);
+    if (props.label) el.setAttribute('label', props.label);
+    if (props.headline) el.setAttribute('headline', props.headline);
+    if (props.description) el.setAttribute('description', props.description);
+    if (props.showFavicon) el.setAttribute('show-favicon', '');
+  });
+  return <kitn-source ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-source
+  href="https://kitn.dev"
+  label="kitn"
+  headline="kitn — the kit"
+  description="Composable SolidJS + web-component chat UI."
+  show-favicon
+></kitn-source>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-source',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-source>` is the framework-agnostic **web component** for a single citation link with a hover-card preview, isolated in **Shadow DOM**.',
+          '**When to use:** inlining a single source citation in a non-Solid app. For multiple sources, use `<kitn-source-list>`; in SolidJS, compose the `Source` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set `href` (the link, also the default label/favicon source), `label`, `headline` (the hover headline — note `headline`, not `title`), `description`, and the `show-favicon` flag via attributes.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A citation with a custom label, hover headline/description, and favicon. */
+export const Default: Story = {
+  render: () => (
+    <SourceElement
+      href="https://kitn.dev"
+      label="kitn"
+      headline="kitn — the kit"
+      description="Composable SolidJS + web-component chat UI."
+      showFavicon
+    />
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** With no `label`, the trigger falls back to the domain. */
+export const DomainLabel: Story = {
+  name: 'Domain Label',
+  render: () => <SourceElement href="https://solidjs.com" description="A reactive UI library." />,
+};

package/src/elements/kitn-text-shimmer.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-text-shimmer': JSX.HTMLAttributes<HTMLElement> & {
+        text?: string;
+        duration?: number;
+        spread?: number;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-text-shimmer text="Thinking…" duration="3" spread="20"></kitn-text-shimmer>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-text-shimmer',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-text-shimmer>` is the framework-agnostic **web component** for animated shimmering text — a gradient sweep across a label, isolated in **Shadow DOM**.',
+          '**When to use:** signalling a quiet, in-progress state ("Thinking…", "Generating…") inline. In SolidJS, use the `TextShimmer` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text` attribute, and tune `duration` (seconds) and `spread` (gradient width, 5–45).",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Default shimmer. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'font-size': '18px' }}>
+      <kitn-text-shimmer text="Thinking…" />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Faster sweep with a wider gradient spread. */
+export const Tuned: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'font-size': '18px' }}>
+      <kitn-text-shimmer text="Generating response…" duration={2} spread={35} />
+    </div>
+  ),
+};

package/src/elements/kitn-thinking-bar.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-thinking-bar': JSX.HTMLAttributes<HTMLElement> & {
+        text?: string;
+        stoppable?: boolean | string;
+        'stop-label'?: string;
+        'on:stop'?: (e: CustomEvent) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-thinking-bar text="Thinking" stoppable stop-label="Answer now"></kitn-thinking-bar>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.querySelector('kitn-thinking-bar')
+    .addEventListener('stop', () => console.log('user asked to stop'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-thinking-bar',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-thinking-bar>` is the framework-agnostic **web component** for an animated "thinking" indicator with an optional stop affordance — a pure leaf element isolated in **Shadow DOM**. (`<kitn-chat>` does not surface this; compose it yourself.)',
+          '**When to use:** showing that the assistant is reasoning, optionally letting the user interrupt with "Answer now". In SolidJS, use the `ThinkingBar` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text`/`stop-label` attributes, add the `stoppable` flag to show the stop button, and listen for the `stop` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A plain thinking indicator. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px' }}>
+      <kitn-thinking-bar text="Thinking" />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Stoppable — shows an "Answer now" affordance that fires a `stop` event. */
+export const Stoppable: Story = {
+  render: () => (
+    <div style={{ padding: '24px' }}>
+      <kitn-thinking-bar
+        text="Reasoning"
+        stoppable
+        stop-label="Answer now"
+        on:stop={() => console.log('stop')}
+      />
+    </div>
+  ),
+};

package/src/elements/kitn-tool.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import type { ToolPart } from '../components/tool';
+
+// 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 {
+      'kitn-tool': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const completedTool: ToolPart = {
+  type: 'database_query',
+  state: 'output-available',
+  input: { table: 'users', limit: 10 },
+  output: { rows: 10, ms: 42 },
+};
+
+const runningTool: ToolPart = {
+  type: 'search',
+  state: 'input-available',
+  input: { query: 'kitn docs' },
+};
+
+/** Render the actual `<kitn-tool>` custom element with a `tool` property. */
+function ToolElement(props: { tool: ToolPart; open?: boolean }) {
+  let el: (HTMLElement & { tool?: ToolPart; open?: boolean }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.tool = props.tool;
+      if (props.open) el.open = true;
+    }
+  });
+  return (
+    <kitn-tool ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-tool id="tool" open></kitn-tool>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const tool = document.getElementById('tool');
+  tool.tool = {
+    type: 'database_query',
+    state: 'output-available',
+    input: { table: 'users', limit: 10 },
+    output: { rows: 10, ms: 42 },
+  };
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-tool',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-tool>` is the framework-agnostic **web component** for a single tool-call panel — a collapsible input/output inspector with a state badge — isolated in **Shadow DOM**.',
+          '**When to use:** rendering an agent/tool-call trace in a non-Solid app. In SolidJS, use the `Tool` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the call via the `tool` **property** (`el.tool = {...}`), and add the `open` flag to start it expanded.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A completed call with input and output, started expanded. */
+export const Completed: Story = {
+  render: () => <ToolElement tool={completedTool} open />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A call still awaiting output (collapsed). */
+export const Running: Story = {
+  render: () => <ToolElement tool={runningTool} />,
+};

package/src/elements/kitn-voice-input.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-voice-input': JSX.HTMLAttributes<HTMLElement> & {
+        disabled?: boolean | string;
+      };
+    }
+  }
+}
+
+/** Render `<kitn-voice-input>` with a stub `transcribe` function-property. */
+function VoiceElement(props: { disabled?: boolean }) {
+  let el: (HTMLElement & { transcribe?: (audio: Blob) => Promise<string> }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    // transcribe MUST be set as a JS property — a value-returning callback
+    // can't be modelled as an attribute.
+    el.transcribe = async () => {
+      await new Promise((r) => setTimeout(r, 400));
+      return 'transcribed text';
+    };
+    el.addEventListener('transcription', (e) => {
+      const ev = e as CustomEvent<{ text: string }>;
+      console.log('transcription', ev.detail.text);
+    });
+  });
+  return (
+    <kitn-voice-input
+      ref={(e) => (el = e as HTMLElement)}
+      disabled={props.disabled ? true : undefined}
+      style={{ display: 'inline-block', padding: '40px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-voice-input id="voice"></kitn-voice-input>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const voice = document.getElementById('voice');
+  // transcribe is a FUNCTION property — your async transcriber
+  voice.transcribe = async (blob) => {
+    const text = await myTranscriptionApi(blob);
+    return text;
+  };
+  voice.addEventListener('transcription', (e) => console.log(e.detail.text));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-voice-input',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-voice-input>` is the framework-agnostic **web component** for a mic button that records and transcribes audio — isolated in **Shadow DOM**. It is the canonical **function-property** element.',
+          '**When to use:** adding voice dictation to an input in a non-Solid app. In SolidJS, use the `VoiceInput` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `transcribe` **function property** (`el.transcribe = async blob => '...'`) — a value-returning callback can't be modelled as an event. It also emits `audiocaptured` (raw blob) and `transcription` (text) **CustomEvents**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A working mic button wired to a stub transcriber. */
+export const Default: Story = {
+  render: () => <VoiceElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A disabled mic button (non-interactive). */
+export const Disabled: Story = {
+  render: () => <VoiceElement disabled />,
+};

package/src/elements/loader.tsx

@@ -0,0 +1,25 @@
+import { defineKitnElement } from './define';
+import { Loader, type LoaderVariant, type LoaderSize } from '../components/loader';
+
+interface Props extends Record<string, unknown> {
+  /** The animation style: `'circular' | 'classic' | 'pulse' | 'pulse-dot' |
+   *  'dots' | 'typing' | 'wave' | 'bars' | 'terminal' | 'text-blink' |
+   *  'text-shimmer' | 'loading-dots'`. Defaults to `'circular'`. */
+  variant?: LoaderVariant;
+  /** Loader size: `'sm' | 'md' | 'lg'`. Defaults to `'md'`. */
+  size?: LoaderSize;
+  /** Label for the text-based variants. */
+  text?: string;
+}
+
+/**
+ * `<kitn-loader>` — an animated loader. `variant` selects the style (circular,
+ * dots, wave, text-shimmer, …); `size` and `text` are attributes.
+ */
+defineKitnElement<Props>('kitn-loader', {
+  variant: 'circular',
+  size: 'md',
+  text: undefined,
+}, (props) => (
+  <Loader variant={props.variant} size={props.size} text={props.text} />
+));