@kitnai/chat 0.3.1 → 0.5.0

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

@@ -0,0 +1,71 @@
+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-checkpoint': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+/** Render the actual `<kitn-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('select', () => console.log('checkpoint selected'));
+  });
+  return <kitn-checkpoint ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-checkpoint label="Restore" tooltip="Restore this checkpoint" variant="outline" size="sm"></kitn-checkpoint>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const cp = document.querySelector('kitn-checkpoint');
+  // events are CustomEvents on the element (they do not bubble)
+  cp.addEventListener('select', () => console.log('restore checkpoint'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-checkpoint',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-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.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set `label`, `tooltip`, `variant` (`ghost` | `default` | `outline`), and `size` via attributes, and listen for the `select` **CustomEvent** on click.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} 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/kitn-code-block.stories.tsx

@@ -0,0 +1,82 @@
+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-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 `<kitn-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 (
+    <kitn-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 -->
+<kitn-code-block id="code" language="ts" code-theme="github-dark-dimmed"></kitn-code-block>
+
+<script type="module">
+  import '@kitnai/chat/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: 'Web Components/kitn-code-block',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-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.',
+          "**How to use:** register once with `import '@kitnai/chat/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.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} 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/kitn-context-meter.stories.tsx

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+interface ContextUsage {
+  usedTokens: number;
+  maxTokens: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cacheTokens?: number;
+  estimatedCost?: number;
+}
+
+// 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-context-meter': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const usage: ContextUsage = {
+  usedTokens: 48200,
+  maxTokens: 200000,
+  inputTokens: 31000,
+  outputTokens: 17200,
+  reasoningTokens: 4200,
+  cacheTokens: 8000,
+  estimatedCost: 0.42,
+};
+
+/** Render `<kitn-context-meter>` with the `context` set as a JS property. */
+function MeterElement(props: { context: ContextUsage }) {
+  let el: (HTMLElement & { context?: ContextUsage }) | undefined;
+  onMount(() => {
+    if (el) el.context = props.context;
+  });
+  return (
+    <kitn-context-meter ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-context-meter id="ctx"></kitn-context-meter>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.getElementById('ctx').context = {
+    usedTokens: 48200, maxTokens: 200000,
+    inputTokens: 31000, outputTokens: 17200,
+    reasoningTokens: 4200, cacheTokens: 8000,
+    estimatedCost: 0.42,
+  };
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-context-meter',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-context-meter>` is the framework-agnostic **web component** for a token/context-window usage meter — a compact gauge with a hover-card breakdown (input / output / reasoning / cache + estimated cost) — isolated in **Shadow DOM**.',
+          '**When to use:** showing how much of the context window a conversation is using, typically in a chat header. In SolidJS, compose the `Context` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `context` **property** with the usage object. Hover the meter to reveal the breakdown.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A meter at ~24% usage; hover to reveal the full breakdown. */
+export const Default: Story = {
+  render: () => <MeterElement context={usage} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

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

@@ -0,0 +1,110 @@
+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-empty': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-empty
+  empty-title="No conversations yet"
+  description="Start a new chat to see it appear here."
+>
+  <!-- Route 2 slots: your own icon and actions -->
+  <svg slot="media" width="28" height="28" viewBox="0 0 24 24" fill="none"
+       stroke="currentColor" stroke-width="2">
+    <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+  </svg>
+
+  <!-- Slotted actions are light DOM, so style them with your own page CSS
+       (a ghost button with a + icon, here styled inline for portability). -->
+  <button
+    style="display:inline-flex; align-items:center; gap:.45rem;
+           font:500 13.5px/1 system-ui,sans-serif; padding:.5rem .85rem;
+           border-radius:9px; border:1px solid var(--color-border, #e5e5e5);
+           background:transparent; color:inherit; cursor:pointer;"
+  >
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none"
+         stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M5 12h14" /><path d="M12 5v14" />
+    </svg>
+    New chat
+  </button>
+</kitn-empty>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-empty',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-empty>` is the framework-agnostic **web component** for an empty-state block — an icon, a title, a description, and actions — isolated in **Shadow DOM**.',
+          '**When to use:** placeholder UI for an empty list/thread in a non-Solid app. In SolidJS, compose the `Empty*` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set `empty-title` (note `empty-title`, not `title`) and `description` via attributes, and use the **slots** (\"Route 2\") to project your own icon (`slot=\"media\"`) and actions (the default slot).",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Render the actual `<kitn-empty>` custom element with slotted children. */
+function EmptyElement() {
+  let el: HTMLElement | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.setAttribute('empty-title', 'No conversations yet');
+    el.setAttribute('description', 'Start a new chat to see it appear here.');
+  });
+  return (
+    <kitn-empty ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px' }}>
+      <svg slot="media" width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+      </svg>
+      {/* Slotted actions are light DOM — style them with the host page's own
+          CSS. Here a ghost "+ New chat" button, styled inline so it renders
+          correctly in any context (mirrors the composable example's pill-btn). */}
+      <button
+        style={{
+          display: 'inline-flex',
+          'align-items': 'center',
+          gap: '0.45rem',
+          font: '500 13.5px/1 system-ui, sans-serif',
+          padding: '0.5rem 0.85rem',
+          'border-radius': '9px',
+          border: '1px solid var(--color-border, #e5e5e5)',
+          background: 'transparent',
+          color: 'inherit',
+          cursor: 'pointer',
+        }}
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M5 12h14" /><path d="M12 5v14" />
+        </svg>
+        New chat
+      </button>
+    </kitn-empty>
+  );
+}
+
+/** An empty state with a slotted icon and an action button. */
+export const Default: Story = {
+  render: () => <EmptyElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

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

@@ -0,0 +1,73 @@
+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-feedback-bar': JSX.HTMLAttributes<HTMLElement> & {
+        'bar-title'?: string;
+        'on:helpful'?: (e: CustomEvent) => void;
+        'on:nothelpful'?: (e: CustomEvent) => void;
+        'on:close'?: (e: CustomEvent) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-feedback-bar bar-title="Was this helpful?"></kitn-feedback-bar>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const bar = document.querySelector('kitn-feedback-bar');
+  bar.addEventListener('helpful', () => console.log('👍'));
+  bar.addEventListener('nothelpful', () => console.log('👎'));
+  bar.addEventListener('close', () => bar.remove());
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-feedback-bar',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-feedback-bar>` is the framework-agnostic **web component** for an inline thumbs up/down feedback banner with a dismiss button — isolated in **Shadow DOM**.',
+          '**When to use:** collecting a quick reaction after an answer or a completed task. In SolidJS, use the `FeedbackBar` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the label via the `bar-title` attribute (`title` is avoided — it's a global HTML attribute), and listen for the `helpful` / `nothelpful` / `close` **CustomEvents**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The default feedback prompt. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-feedback-bar
+        on:helpful={() => console.log('helpful')}
+        on:nothelpful={() => console.log('not helpful')}
+        on:close={() => console.log('closed')}
+      />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A custom label via the `bar-title` attribute. */
+export const CustomTitle: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-feedback-bar bar-title="Did this answer your question?" />
+    </div>
+  ),
+};

package/src/elements/kitn-file-upload.stories.tsx

@@ -0,0 +1,81 @@
+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-file-upload': JSX.HTMLAttributes<HTMLElement> & {
+        multiple?: boolean | string;
+        accept?: string;
+        disabled?: boolean | string;
+        label?: string;
+        'on:filesadded'?: (e: CustomEvent<{ files: File[] }>) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-file-upload accept="image/*" label="Drop images here"></kitn-file-upload>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.querySelector('kitn-file-upload')
+    .addEventListener('filesadded', (e) =>
+      console.log(e.detail.files.map((f) => f.name)));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-file-upload',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-file-upload>` is the framework-agnostic **web component** for a click / drag-and-drop file dropzone — isolated in **Shadow DOM**.',
+          '**When to use:** accepting file or image uploads in a non-Solid app. In SolidJS, compose the `FileUpload` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `accept` / `multiple` / `label` attributes, and listen for the `filesadded` **CustomEvent** (`e.detail.files` is a `File[]`). The default dropzone label can be replaced with your own markup via the default `<slot>`.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A dropzone accepting any files. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-file-upload
+        on:filesadded={(e: CustomEvent<{ files: File[] }>) =>
+          console.log(e.detail.files.map((f) => f.name))}
+      />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Restricted to images, single file, with a custom label. */
+export const ImagesOnly: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-file-upload accept="image/*" multiple={false} label="Click or drop an image" />
+    </div>
+  ),
+};
+
+/** A disabled dropzone (non-interactive). */
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-file-upload disabled label="Uploads are disabled" />
+    </div>
+  ),
+};

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

@@ -0,0 +1,70 @@
+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-image': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+// A small inline SVG, base64-encoded — the same trick the composable example uses.
+const sampleSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96"><rect width="96" height="96" rx="16" fill="#7c3aed"/><text x="48" y="62" font-size="44" text-anchor="middle" fill="white">★</text></svg>';
+const sampleBase64 = btoa(unescape(encodeURIComponent(sampleSvg)));
+
+/** Render the actual `<kitn-image>` custom element with base64 + media-type. */
+function ImageElement() {
+  let el: (HTMLElement & { base64?: string; alt?: string }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.base64 = sampleBase64;
+      el.alt = 'A purple star';
+      el.setAttribute('media-type', 'image/svg+xml');
+    }
+  });
+  return <kitn-image ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-image id="img" media-type="image/png" alt="A chart"></kitn-image>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const img = document.getElementById('img');
+  img.base64 = '<...base64 image data...>';
+  // or set raw bytes as a property:
+  // img.bytes = new Uint8Array([...]);
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-image',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-image>` is the framework-agnostic **web component** that renders a base64 or byte-array image, showing a skeleton fallback while it resolves, isolated in **Shadow DOM**.',
+          '**When to use:** displaying model-generated or in-memory images (without a hosted URL) in a non-Solid app. In SolidJS, use the `Image` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set `base64` (paired with the `media-type` attribute) or set raw `bytes` as a **property**, and add `alt` text.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A base64-encoded SVG with a media type and alt text. */
+export const Default: Story = {
+  render: () => <ImageElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

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

@@ -0,0 +1,87 @@
+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-loader': JSX.HTMLAttributes<HTMLElement> & {
+        variant?: string;
+        size?: string;
+        text?: string;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-loader variant="dots" size="md"></kitn-loader>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-loader',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-loader>` is the framework-agnostic **web component** for an animated busy indicator — a dozen styles (circular, dots, wave, bars, text-shimmer, …) selected via the `variant` attribute, isolated in **Shadow DOM**.',
+          '**When to use:** showing a small "working" indicator anywhere outside the chat thread (toolbars, buttons, panels). In SolidJS, use the `Loader` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set `variant`, `size`, and (for text variants) `text` as plain HTML attributes.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+const VARIANTS = [
+  'circular', 'classic', 'pulse', 'pulse-dot', 'dots', 'typing',
+  'wave', 'bars', 'terminal', 'text-blink', 'text-shimmer', 'loading-dots',
+];
+
+/** The default circular spinner. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px' }}>
+      <kitn-loader variant="circular" size="md" />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Every variant at the medium size, side by side. */
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', 'flex-wrap': 'wrap', gap: '32px', 'align-items': 'center', padding: '24px' }}>
+      {VARIANTS.map((v) => (
+        <div style={{ display: 'flex', 'flex-direction': 'column', 'align-items': 'center', gap: '8px', 'min-width': '90px' }}>
+          <kitn-loader variant={v} size="md" text="Loading" />
+          <code style={{ 'font-size': '11px', opacity: 0.6 }}>{v}</code>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/** The three sizes (`sm` / `md` / `lg`) of the dots variant. */
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '32px', 'align-items': 'center', padding: '24px' }}>
+      {['sm', 'md', 'lg'].map((s) => (
+        <div style={{ display: 'flex', 'flex-direction': 'column', 'align-items': 'center', gap: '8px' }}>
+          <kitn-loader variant="dots" size={s} />
+          <code style={{ 'font-size': '11px', opacity: 0.6 }}>{s}</code>
+        </div>
+      ))}
+    </div>
+  ),
+};