@kitn.ai/ui 0.14.1

package/src/elements/image.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
+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-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 `<kai-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 <kai-image ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-image id="img" media-type="image/png" alt="A chart"></kai-image>
+
+<script type="module">
+  import '@kitn.ai/ui/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: 'Components/Image',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-image'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-image', [
+          '`<kai-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.',
+          '**Placement:** inside a message bubble, card body, or artifact preview panel; size it via the parent container — the element is `display: inline-block` and the image fills to the parent\'s width.',
+          "**How to use:** register once with `import '@kitn.ai/ui/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.',
+        ]),
+    },
+  },
+} 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/image.tsx

@@ -0,0 +1,32 @@
+import { defineWebComponent } from './define';
+import { Image } from '../components/image';
+
+interface Props extends Record<string, unknown> {
+  /** Base64-encoded image data (pair with `media-type`). */
+  base64?: string;
+  /** Raw image bytes (set as a JS property). */
+  bytes?: Uint8Array;
+  /** Alt text. */
+  alt?: string;
+  /** MIME type (default `image/png`). */
+  mediaType?: string;
+}
+
+/**
+ * `<kai-image>` — renders a base64 or byte-array image with a skeleton
+ * fallback while it resolves. `base64`/`alt`/`media-type` via attributes;
+ * `bytes` via property.
+ */
+defineWebComponent<Props>('kai-image', {
+  base64: undefined,
+  bytes: undefined,
+  alt: '',
+  mediaType: undefined,
+}, (props) => (
+  <Image
+    alt={props.alt ?? ''}
+    base64={props.base64}
+    uint8Array={props.bytes}
+    mediaType={props.mediaType}
+  />
+));

package/src/elements/link-preview.stories.tsx

@@ -0,0 +1,209 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './link-preview'; // side effect: registers <kai-link-preview>
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { LinkPreviewData } from '../primitives/link-preview';
+import { configureLinkPreview } from '../primitives/link-preview';
+import type { CardEvent } from '../primitives/card-contract';
+
+// Custom DOM element — declare the tag for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-link-preview': JSX.HTMLAttributes<HTMLElement> & {
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+type LinkPreviewEl = HTMLElement & { cardId?: string; data?: LinkPreviewData };
+
+/** A sized box the card sits in (cards expand to their container width). */
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ width: '100%', 'max-width': '420px' }}>{props.children}</div>;
+}
+
+/** Mounts a <kai-link-preview>, sets `.data`, logs emitted CardEvents under the render. */
+function LinkPreviewDemo(props: { cardId: string; data: LinkPreviewData }) {
+  const [log, setLog] = createSignal<CardEvent[]>([]);
+  let el: LinkPreviewEl | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.cardId = props.cardId;
+    el.data = props.data;
+    el.addEventListener('kai-card', (e) => {
+      const detail = (e as CustomEvent<CardEvent>).detail;
+      setLog((prev) => [...prev, detail]);
+      if (detail.kind === 'open' && detail.target === 'tab') {
+        window.open(detail.url, '_blank', 'noopener,noreferrer');
+      }
+    });
+  });
+  return (
+    <Frame>
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '12px' }}>
+        <kai-link-preview ref={(e) => (el = e as LinkPreviewEl)} card-id={props.cardId} />
+        <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 FULL_ENVELOPE = {
+  type: 'link',
+  id: 'card-link-1',
+  title: 'Shared link',
+  data: {
+    url: 'https://example.com/blog/generative-ui',
+    title: 'Generative UI, explained',
+    description:
+      'How agents render typed, themed cards in the chat — across native components and provider iframes.',
+    image: 'https://placehold.co/1200x630/6366f1/ffffff/png?text=Generative+UI',
+    imageAlt: 'Diagram of the card contract',
+    favicon: 'https://example.com/favicon.ico',
+    siteName: 'Example Blog',
+    domain: 'example.com',
+  },
+} satisfies { type: string; id: string; title: string; data: LinkPreviewData };
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-link-preview id="lc"></kai-link-preview>
+
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers the custom elements
+
+  const lc = document.getElementById('lc');
+  lc.cardId = 'card-link-1';
+  // \`data\` is a JS property (the CardEnvelope \`data\`):
+  lc.data = ${JSON.stringify(FULL_ENVELOPE.data, null, 2).replace(/\n/g, '\n  ')};
+
+  // Cards bubble a composed \`kai-card\` event carrying a typed CardEvent.
+  // kai-link-preview emits: ready (on mount), open (on click), error (invalid/broken url).
+  lc.addEventListener('kai-card', (e) => {
+    const ev = e.detail; // CardEvent
+    if (ev.kind === 'open' && ev.target === 'tab') {
+      window.open(ev.url, '_blank', 'noopener,noreferrer');
+    }
+  });
+</script>`;
+
+const meta = {
+  title: 'Generative UI/Cards/kai-link-preview',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-link-preview'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kai-link-preview', [
+        '`<kai-link-preview>` is a themed, accessible **rich link / Open-Graph preview** card for the generative-UI feature. It speaks the **Card Contract**: data down (a `link` `CardEnvelope`), events up (only the `open` verb, plus lifecycle `ready` / failure `error`).',
+        '**Pure by default:** the card renders from the metadata you supply (`title`, `description`, `image`, `favicon`, `siteName`, `domain`) — it **never fetches**. For the bare-`{ url }` case, an app may opt in to a resolver with `configureLinkPreview({ fetchMetadata })` (CORS means OG scraping needs YOUR backend; there is no built-in network call).',
+        '**Interaction:** the whole card is one link target. Activating it (click / Enter / Space) dispatches the bubbling, composed **`kai-card`** event with `{ kind: \'open\', url, target: \'tab\' }` so a host-level listener routes it through `CardPolicy` (which performs the navigation, after scheme validation).',
+        '**Graceful degradation:** a missing/broken image drops the image region (not an error); an invalid url renders a non-clickable "Invalid link" chip and emits one `error`.',
+        'See the **Code** tab for the `CardEnvelope` JSON + HTML wiring.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Full OG metadata — image, site name, title, description. Click the card to see the emitted `open` event. */
+export const FullPreview: Story = {
+  name: 'Full preview',
+  render: () => <LinkPreviewDemo cardId={FULL_ENVELOPE.id} data={FULL_ENVELOPE.data} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** No image — the card degrades gracefully to the text + domain layout. */
+export const NoImage: Story = {
+  name: 'No image',
+  render: () => (
+    <LinkPreviewDemo
+      cardId="card-link-2"
+      data={{
+        url: 'https://docs.example.com/guide',
+        title: 'API Guide',
+        description: 'Reference for the public endpoints, auth, and rate limits.',
+        siteName: 'Example Docs',
+      }}
+    />
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: JSON.stringify(
+          {
+            type: 'link',
+            id: 'card-link-2',
+            data: {
+              url: 'https://docs.example.com/guide',
+              title: 'API Guide',
+              description: 'Reference for the public endpoints, auth, and rate limits.',
+              siteName: 'Example Docs',
+            },
+          },
+          null,
+          2,
+        ),
+        language: 'json',
+      },
+    },
+  },
+};
+
+/** Bare URL + a configured fetcher — shows the skeleton → merged render path. */
+export const BareUrlWithFetcher: Story = {
+  name: 'Bare URL + fetcher',
+  render: () => {
+    // Demo only: an app would point this at its own backend/proxy.
+    configureLinkPreview({
+      fetchMetadata: async (url) => {
+        await new Promise((r) => setTimeout(r, 900)); // show the skeleton
+        return {
+          title: 'Resolved by your backend',
+          description: `Metadata for ${url} fetched via configureLinkPreview.`,
+          siteName: 'example.com',
+        };
+      },
+    });
+    return <LinkPreviewDemo cardId="card-link-3" data={{ url: 'https://example.com/bare' }} />;
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `import { configureLinkPreview } from '@kitn.ai/ui';
+
+// Opt in once (points at YOUR backend/proxy — there is no built-in network call):
+configureLinkPreview({
+  fetchMetadata: (url) => fetch('/api/og?url=' + encodeURIComponent(url)).then((r) => r.json()),
+});
+
+// Then a bare { url } envelope resolves to a full preview:
+lc.data = { url: 'https://example.com/bare' };`,
+        language: 'ts',
+      },
+    },
+  },
+};
+
+/** Invalid link — a non-clickable error chip; one `error` event is emitted (visible in the log below). */
+export const InvalidLink: Story = {
+  name: 'Invalid link',
+  render: () => <LinkPreviewDemo cardId="card-link-4" data={{ url: 'not-a-valid-url' }} />,
+};

package/src/elements/link-preview.tsx

@@ -0,0 +1,34 @@
+import { defineWebComponent } from './define';
+import { LinkPreview } from '../components/link-preview';
+import type { LinkPreviewData } from '../primitives/link-preview';
+import { emitCardEvent } from '../primitives/card-routing';
+
+interface Props extends Record<string, unknown> {
+  /** Stable card id correlating every emitted event. Set as an attribute or property. */
+  cardId?: string;
+  /** The link payload (OG metadata). Set as a JS **property** (object). */
+  data?: LinkPreviewData;
+}
+
+/**
+ * `<kai-link-preview>` — a themed, accessible rich link / Open-Graph preview card. It
+ * renders from the supplied `data` (it never fetches; an app may register a
+ * `configureLinkPreview` fetcher for the bare-`{ url }` path). Activating the card
+ * dispatches the bubbling, composed **`kai-card`** CustomEvent with the contract
+ * `open` verb (`{ kind:'open', url, target:'tab' }`) so a host-level listener
+ * routes it through CardPolicy. Set `data` as a JS property; `card-id` via attribute.
+ */
+defineWebComponent<Props>(
+  'kai-link-preview',
+  {
+    cardId: undefined,
+    data: undefined,
+  },
+  (props, { element }) => (
+    <LinkPreview
+      cardId={props.cardId ?? ''}
+      data={props.data ?? ({ url: '' } as LinkPreviewData)}
+      onEmit={(event) => emitCardEvent(element, event)}
+    />
+  ),
+);

package/src/elements/loader.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+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-loader': JSX.HTMLAttributes<HTMLElement> & {
+        variant?: string;
+        size?: string;
+        text?: string;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-loader variant="dots" size="md"></kai-loader>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Components/Loader',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-loader'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-loader', [
+          '`<kai-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.',
+          '**Placement:** inline anywhere a busy state is needed — centered inside a button, floated in a toolbar corner, or as a standalone skeleton in an empty panel; it is `display: inline-flex` by default so it follows normal inline flow.',
+          "**How to use:** register once with `import '@kitn.ai/ui/elements'`, then set `variant`, `size`, and (for text variants) `text` as plain HTML attributes.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} 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' }}>
+      <kai-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' }}>
+          <kai-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' }}>
+          <kai-loader variant="dots" size={s} />
+          <code style={{ 'font-size': '11px', opacity: 0.6 }}>{s}</code>
+        </div>
+      ))}
+    </div>
+  ),
+};

package/src/elements/loader.tsx

@@ -0,0 +1,25 @@
+import { defineWebComponent } 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;
+}
+
+/**
+ * `<kai-loader>` — an animated loader. `variant` selects the style (circular,
+ * dots, wave, text-shimmer, …); `size` and `text` are attributes.
+ */
+defineWebComponent<Props>('kai-loader', {
+  variant: 'circular',
+  size: 'md',
+  text: undefined,
+}, (props) => (
+  <Loader variant={props.variant} size={props.size} text={props.text} />
+));

package/src/elements/markdown.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
+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-markdown': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleMarkdown = `### Markdown
+Renders **bold**, _italic_, \`code\`, and lists:
+- one
+- two
+
+> and blockquotes.
+
+\`\`\`ts
+export function add(a: number, b: number): number {
+  return a + b;
+}
+\`\`\``;
+
+/** Render the actual `<kai-markdown>` custom element with a `content` property. */
+function MarkdownElement(props: { content: string }) {
+  let el: (HTMLElement & { content?: string }) | undefined;
+  onMount(() => {
+    if (el) el.content = props.content;
+  });
+  return (
+    <kai-markdown 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-markdown id="md" code-theme="github-dark-dimmed"></kai-markdown>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const md = document.getElementById('md');
+  md.content = '### Hello\\nRenders **bold**, _italic_, and \\\`code\\\`.';
+  // md.setAttribute('code-highlight', 'false'); // skip Shiki entirely
+</script>`;
+
+const meta = {
+  title: 'Components/Markdown',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-markdown'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-markdown', [
+          '`<kai-markdown>` is the framework-agnostic **web component** that renders a markdown string (with fenced-code syntax highlighting via Shiki) as a standalone element, isolated in **Shadow DOM**.',
+          '**When to use:** showing model output or any markdown in a non-Solid app without pulling in a markdown stack. In SolidJS, use the `Markdown` primitive directly.',
+          '**Placement:** as a block inside a message row, doc viewer, or standalone content pane; it is `display: block` and expands to fill its container width, so constrain width on the parent.',
+          "**How to use:** register once with `import '@kitn.ai/ui/elements'`, set the source via the `content` **property** (`el.content = '...'`), and tune rendering with the `prose-size`, `code-theme`, and `code-highlight` attributes.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Headings, emphasis, lists, a blockquote, and a highlighted code fence. */
+export const Default: Story = {
+  render: () => <MarkdownElement content={sampleMarkdown} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/markdown.tsx

@@ -0,0 +1,38 @@
+import { defineWebComponent } from './define';
+import { Markdown } from '../components/markdown';
+import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
+
+interface Props extends Record<string, unknown> {
+  /** The markdown source to render. */
+  content: string;
+  /** Text/markdown sizing. */
+  proseSize?: ProseSize;
+  /** Shiki theme for fenced code blocks. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (no Shiki loads). */
+  codeHighlight?: boolean;
+}
+
+/**
+ * `<kai-markdown>` — renders markdown (with fenced-code syntax highlighting) as
+ * a standalone element. Content via the `content` property; sizing/highlighting
+ * via attributes.
+ */
+defineWebComponent<Props>('kai-markdown', {
+  content: '',
+  proseSize: 'sm',
+  codeTheme: 'github-dark-dimmed',
+  codeHighlight: true,
+}, (props, { flag }) => {
+  const outer = useChatConfig();
+  return (
+    <ChatConfig
+      proseSize={props.proseSize}
+      codeTheme={props.codeTheme}
+      codeHighlight={flag('codeHighlight')}
+      portalMount={outer.portalMount()}
+    >
+      <Markdown content={props.content} />
+    </ChatConfig>
+  );
+});