@kitn.ai/ui 0.14.1

package/src/components/image.stories.tsx

@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { Image } from './image';
+import { componentDescription } from '../stories/docs/element-controls';
+
+// Compact SVG chat typing icon as base64
+const chatIconBase64 =
+  'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0OCIgaGVpZ2h0PSI0OCIgdmlld0JveD0iMCAwIDQ4IDQ4Ij48cmVjdCB3aWR0aD0iNDgiIGhlaWdodD0iNDgiIHJ4PSIxMCIgZmlsbD0iIzdjM2FlZCIvPjxjaXJjbGUgY3g9IjE2IiBjeT0iMjQiIHI9IjQiIGZpbGw9IiNmZmYiLz48Y2lyY2xlIGN4PSIyNCIgY3k9IjI0IiByPSI0IiBmaWxsPSIjZmZmIi8+PGNpcmNsZSBjeD0iMzIiIGN5PSIyNCIgcj0iNCIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg==';
+
+const meta = {
+  title: 'Solid (Advanced)/Elements/Image',
+  component: Image,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'Renders an image from a `base64` string or a `uint8Array`, building a data URL or object URL automatically; shows a pulsing placeholder until a source is available.',
+        '**When to use:** to display model-generated or attached images supplied as raw bytes / base64 (the `GeneratedImageLike` shape) rather than a remote URL.',
+        '**How to use:** pass `base64` + `mediaType` (or `uint8Array` + `mediaType`) and an `alt` description; size and style via `class`.',
+        '**Placement:** inside assistant messages, attachment previews, or anywhere a generated image needs to be shown.',
+      ]),
+    },
+  },
+  argTypes: {
+    base64: {
+      control: 'text',
+      description: 'Base64-encoded image data. Combined with `mediaType` to form a data URL.',
+    },
+    uint8Array: {
+      control: 'object',
+      description: 'Raw image bytes. Combined with `mediaType` to form an object URL.',
+    },
+    mediaType: {
+      control: 'text',
+      description: 'MIME type of the image data, e.g. `image/png` or `image/svg+xml`.',
+      table: { defaultValue: { summary: 'image/png' } },
+    },
+    alt: {
+      control: 'text',
+      description: 'Alternative text describing the image (also used on the placeholder).',
+    },
+    class: {
+      control: 'text',
+      description: 'Additional CSS classes for the image / placeholder element.',
+    },
+  },
+  args: {
+    base64: chatIconBase64,
+    mediaType: 'image/svg+xml',
+    alt: 'Compact gradient chat icon',
+    class: 'h-24 w-24 rounded-md',
+  },
+  render: (args) => <Image {...args} />,
+} satisfies Meta<typeof Image>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Image } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — swap the base64 data, media type, and sizing classes. */
+export const Playground: Story = {
+  ...src(`<Image
+  base64={chatIconBase64}
+  mediaType="image/svg+xml"
+  alt="Compact gradient chat icon"
+  class="h-24 w-24 rounded-md"
+/>`),
+};
+
+export const Basic: Story = {
+  args: { class: 'h-24 w-24 rounded-md' },
+  ...src(`<Image base64={chatIconBase64} mediaType="image/svg+xml" alt="Compact gradient chat icon" class="h-24 w-24 rounded-md" />`),
+};
+
+export const CustomSize: Story = {
+  args: { alt: 'Large preview', class: 'h-64 w-64 rounded-lg' },
+  ...src(`<Image base64={chatIconBase64} mediaType="image/svg+xml" alt="Large preview" class="h-64 w-64 rounded-lg" />`),
+};
+
+/** Placeholder state shown while no `base64`/`uint8Array` source is available (showcase). */
+export const Placeholder: Story = {
+  render: () => <Image alt="Loading image" class="h-24 w-24 rounded-md" />,
+  ...src(`<Image alt="Loading image" class="h-24 w-24 rounded-md" />`),
+};

package/src/components/image.tsx

@@ -0,0 +1,67 @@
+import { type JSX, splitProps, createSignal, createEffect, onCleanup, Show } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface GeneratedImageLike {
+  base64?: string;
+  uint8Array?: Uint8Array;
+  mediaType?: string;
+}
+
+export interface ImageProps extends GeneratedImageLike {
+  alt: string;
+  class?: string;
+}
+
+function getImageSrc(base64?: string, mediaType?: string): string | undefined {
+  if (base64 && mediaType) {
+    return `data:${mediaType};base64,${base64}`;
+  }
+  return undefined;
+}
+
+function Image(props: ImageProps) {
+  const [local, rest] = splitProps(props, ['base64', 'uint8Array', 'mediaType', 'class', 'alt']);
+  const [objectUrl, setObjectUrl] = createSignal<string | undefined>(undefined);
+
+  const mediaType = () => local.mediaType ?? 'image/png';
+
+  createEffect(() => {
+    const arr = local.uint8Array;
+    const mt = mediaType();
+    if (arr && mt) {
+      const blob = new Blob([arr as BlobPart], { type: mt });
+      const url = URL.createObjectURL(blob);
+      setObjectUrl(url);
+      onCleanup(() => URL.revokeObjectURL(url));
+    } else {
+      setObjectUrl(undefined);
+    }
+  });
+
+  const src = () => getImageSrc(local.base64, mediaType()) ?? objectUrl();
+
+  return (
+    <Show
+      when={src()}
+      fallback={
+        <div
+          aria-label={local.alt}
+          role="img"
+          class={cn(
+            'h-auto max-w-full animate-pulse overflow-hidden rounded-md bg-muted',
+            local.class
+          )}
+        />
+      }
+    >
+      <img
+        src={src()}
+        alt={local.alt}
+        class={cn('h-auto max-w-full overflow-hidden rounded-md', local.class)}
+        role="img"
+      />
+    </Show>
+  );
+}
+
+export { Image };

package/src/components/link-preview.tsx

@@ -0,0 +1,194 @@
+import {
+  type JSX,
+  splitProps,
+  createSignal,
+  createEffect,
+  createMemo,
+  on,
+  onMount,
+  onCleanup,
+  Show,
+} from 'solid-js';
+import { cn } from '../utils/cn';
+import { Link as LinkIcon } from 'lucide-solid';
+import type { CardEvent } from '../primitives/card-contract';
+import {
+  type LinkPreviewData,
+  deriveDomain,
+  isRenderableLink,
+  hasLinkPreviewFetcher,
+  resolveLinkMetadata,
+} from '../primitives/link-preview';
+
+export interface LinkPreviewProps {
+  /** The card id correlating every emitted event. */
+  cardId: string;
+  /** The link payload (data-down). */
+  data: LinkPreviewData;
+  /** Emit a contract CardEvent up (host routes it). */
+  onEmit?: (event: CardEvent) => void;
+  /** Extra classes for the card root. */
+  class?: string;
+}
+
+/** True when the payload already carries renderable metadata (the pure path). */
+function hasMetadata(data: LinkPreviewData): boolean {
+  return Boolean(data.title || data.description || data.image);
+}
+
+/**
+ * `LinkPreview` — a pure, themed, accessible rich link / OG preview. Renders from the
+ * supplied metadata; it never fetches the network itself. When the payload is a
+ * bare `{ url }` and an app has registered a `configureLinkPreview` fetcher, it
+ * shows a skeleton, calls the hook, merges the result, and renders. Activating the
+ * card (click / Enter / Space) emits the contract `open` verb (`target:'tab'`); the
+ * host policy performs the navigation so it can veto/redirect.
+ */
+export function LinkPreview(props: LinkPreviewProps): JSX.Element {
+  const [local] = splitProps(props, ['cardId', 'data', 'onEmit', 'class']);
+
+  const emit = (event: CardEvent) => local.onEmit?.(event);
+
+  // Bare-URL resolution state (only used when the payload lacks metadata + a fetcher exists).
+  const [fetched, setFetched] = createSignal<Partial<LinkPreviewData> | undefined>();
+  const [loading, setLoading] = createSignal(false);
+  const [imageBroken, setImageBroken] = createSignal(false);
+
+  const url = () => local.data.url;
+  const valid = createMemo(() => isRenderableLink(url()));
+
+  // The effective payload = supplied data merged with any fetched metadata.
+  const effective = createMemo<LinkPreviewData>(() => ({ ...local.data, ...fetched() }));
+
+  // Lifecycle `ready` once on mount.
+  onMount(() => emit({ kind: 'ready', cardId: local.cardId }));
+
+  // Invalid URL → emit a single `error` (belt-and-suspenders; host also rejects bad schemes on open).
+  createEffect(
+    on(valid, (ok) => {
+      if (!ok) emit({ kind: 'error', cardId: local.cardId, message: `Invalid link url: ${url()}` });
+    }),
+  );
+
+  // Bare-URL path: when there's no metadata AND a fetcher is configured, resolve once.
+  createEffect(
+    on(
+      () => [local.data, valid()] as const,
+      ([data, ok]) => {
+        setImageBroken(false);
+        if (!ok || hasMetadata(data) || !hasLinkPreviewFetcher()) return;
+        let cancelled = false;
+        // Cancel a stale in-flight fetch if `data` changes before it resolves.
+        onCleanup(() => {
+          cancelled = true;
+        });
+        setLoading(true);
+        resolveLinkMetadata(data.url)
+          .then((meta) => {
+            if (!cancelled) setFetched(meta);
+          })
+          .catch(() => {
+            // Reject → fall back to the bare link chip; the URL itself is still usable.
+            if (!cancelled) setFetched({});
+          })
+          .finally(() => {
+            if (!cancelled) setLoading(false);
+          });
+      },
+    ),
+  );
+
+  const domain = createMemo(() => effective().domain ?? deriveDomain(url()) ?? url());
+  const heading = createMemo(() => effective().siteName ?? domain());
+  const titleText = createMemo(() => effective().title ?? domain());
+  const showImage = createMemo(() => Boolean(effective().image) && !imageBroken());
+
+  const activate = () => {
+    if (!valid()) return;
+    emit({ kind: 'open', cardId: local.cardId, url: url(), target: 'tab' });
+  };
+
+  const onClick = (e: MouseEvent) => {
+    // Intercept the anchor's default navigation so it routes through host policy.
+    // (Middle-click / cmd-click still open the real href in a new tab — acceptable + safe.)
+    e.preventDefault();
+    activate();
+  };
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      activate();
+    }
+  };
+
+  // --- Invalid-link error chip ------------------------------------------
+  return (
+    <Show
+      when={valid()}
+      fallback={
+        <div
+          role="img"
+          aria-label="Invalid link"
+          class={cn(
+            'flex items-center gap-2 rounded-xl border border-destructive/40 bg-destructive/10 px-3 py-2 text-sm text-destructive dark:border-red-400/50 dark:bg-destructive/20 dark:text-red-400',
+            local.class,
+          )}
+        >
+          <LinkIcon size={16} aria-hidden="true" />
+          <span class="truncate">Invalid link</span>
+        </div>
+      }
+    >
+      <a
+        href={url()}
+        rel="noopener noreferrer"
+        aria-label={`Open ${titleText()} on ${domain()}`}
+        class={cn(
+          'group block overflow-hidden rounded-xl border border-border bg-card text-card-foreground no-underline outline-none transition-shadow',
+          'cursor-pointer hover:shadow-md focus-visible:ring-2 focus-visible:ring-ring',
+          local.class,
+        )}
+        onClick={onClick}
+        onKeyDown={onKeyDown}
+      >
+        <Show when={loading()}>
+          {/* Skeleton while the bare-URL fetcher resolves. */}
+          <div class="aspect-[16/9] w-full animate-pulse bg-muted" />
+          <div class="space-y-2 p-3">
+            <div class="h-3 w-1/3 animate-pulse rounded bg-muted" />
+            <div class="h-4 w-2/3 animate-pulse rounded bg-muted" />
+            <div class="h-3 w-full animate-pulse rounded bg-muted" />
+          </div>
+        </Show>
+        <Show when={!loading()}>
+          <Show when={showImage()}>
+            <img
+              src={effective().image}
+              alt={effective().imageAlt ?? ''}
+              role="img"
+              class="aspect-[16/9] w-full object-cover"
+              onError={() => setImageBroken(true)}
+            />
+          </Show>
+          <div class="space-y-1 p-3">
+            <div class="flex items-center gap-1.5 text-xs text-muted-foreground">
+              <Show
+                when={effective().favicon}
+                fallback={<LinkIcon size={12} class="shrink-0 opacity-70" aria-hidden="true" />}
+              >
+                <img src={effective().favicon} alt="" class="h-3.5 w-3.5 shrink-0 rounded-sm" />
+              </Show>
+              <span class="truncate">{heading()}</span>
+            </div>
+            <div class="line-clamp-2 text-sm font-semibold text-foreground">{titleText()}</div>
+            <Show when={effective().description}>
+              <div class="line-clamp-3 text-xs text-muted-foreground">{effective().description}</div>
+            </Show>
+          </div>
+        </Show>
+      </a>
+    </Show>
+  );
+}
+
+export type { LinkPreviewData } from '../primitives/link-preview';

package/src/components/loader.stories.tsx

@@ -0,0 +1,181 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { For } from 'solid-js';
+import { Loader, type LoaderVariant, type LoaderSize } from './loader';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Elements/Loader',
+  component: Loader,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'A loading indicator with twelve animated **variants** (spinners, dots, bars, terminal, and text-based) in three **sizes**.',
+        '**When to use:** while waiting on an async operation — a streaming response, a tool call, or any pending state.',
+        '**How to use:** pick a `variant` and `size`. Text variants (`text-blink`, `text-shimmer`, `loading-dots`) display the `text` prop (defaults to "Thinking").',
+        '**Placement:** inside assistant message bubbles, send-button states, empty states, or anywhere an in-progress signal is needed.',
+      ]),
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: [
+        'circular', 'classic', 'pulse', 'pulse-dot', 'dots', 'typing',
+        'wave', 'bars', 'terminal', 'text-blink', 'text-shimmer', 'loading-dots',
+      ],
+      description: 'Animation style of the loader.',
+      table: { defaultValue: { summary: 'circular' } },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Loader size preset.',
+      table: { defaultValue: { summary: 'md' } },
+    },
+    text: {
+      control: 'text',
+      description: 'Label shown by the text variants (`text-blink`, `text-shimmer`, `loading-dots`).',
+      table: { defaultValue: { summary: 'Thinking' } },
+    },
+    class: {
+      control: 'text',
+      description: 'Additional CSS classes for the loader element.',
+    },
+  },
+  args: {
+    variant: 'circular',
+    size: 'md',
+    text: 'Thinking',
+  },
+  render: (args) => <Loader {...args} />,
+} satisfies Meta<typeof Loader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Loader } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — switch variant, size, and text to explore every loader. */
+export const Playground: Story = {
+  ...src(`<Loader variant="circular" size="md" />`),
+};
+
+export const Classic: Story = {
+  args: { variant: 'classic' },
+  ...src(`<Loader variant="classic" size="md" />`),
+};
+
+export const Pulse: Story = {
+  args: { variant: 'pulse' },
+  ...src(`<Loader variant="pulse" size="md" />`),
+};
+
+export const PulseDot: Story = {
+  args: { variant: 'pulse-dot' },
+  ...src(`<Loader variant="pulse-dot" size="md" />`),
+};
+
+export const Dots: Story = {
+  args: { variant: 'dots' },
+  ...src(`<Loader variant="dots" size="md" />`),
+};
+
+export const Typing: Story = {
+  args: { variant: 'typing' },
+  ...src(`<Loader variant="typing" size="md" />`),
+};
+
+export const Wave: Story = {
+  args: { variant: 'wave' },
+  ...src(`<Loader variant="wave" size="md" />`),
+};
+
+export const Bars: Story = {
+  args: { variant: 'bars' },
+  ...src(`<Loader variant="bars" size="md" />`),
+};
+
+export const Terminal: Story = {
+  args: { variant: 'terminal' },
+  ...src(`<Loader variant="terminal" size="md" />`),
+};
+
+export const TextBlink: Story = {
+  args: { variant: 'text-blink', text: 'Thinking' },
+  ...src(`<Loader variant="text-blink" text="Thinking" size="md" />`),
+};
+
+export const TextShimmer: Story = {
+  args: { variant: 'text-shimmer', text: 'Analyzing' },
+  ...src(`<Loader variant="text-shimmer" text="Analyzing" size="md" />`),
+};
+
+export const LoadingDots: Story = {
+  args: { variant: 'loading-dots', text: 'Processing' },
+  ...src(`<Loader variant="loading-dots" text="Processing" size="md" />`),
+};
+
+const allVariants: LoaderVariant[] = [
+  'circular', 'classic', 'pulse', 'pulse-dot', 'dots', 'typing',
+  'wave', 'bars', 'terminal', 'text-blink', 'text-shimmer', 'loading-dots',
+];
+
+const allSizes: LoaderSize[] = ['sm', 'md', 'lg'];
+
+/** Every variant across every size (showcase — not driven by controls). */
+export const AllVariantsGrid: Story = {
+  render: () => (
+    <div class="space-y-6">
+      <For each={allVariants}>
+        {(variant) => (
+          <div class="flex items-center gap-6">
+            <span class="w-28 text-sm text-muted-foreground font-mono">{variant}</span>
+            <For each={allSizes}>
+              {(size) => (
+                <div class="flex items-center justify-center w-24 h-10">
+                  <Loader
+                    variant={variant}
+                    size={size}
+                    text={['text-blink', 'text-shimmer', 'loading-dots'].includes(variant) ? 'Loading' : undefined}
+                  />
+                </div>
+              )}
+            </For>
+          </div>
+        )}
+      </For>
+    </div>
+  ),
+  ...src(`<Loader variant="circular" size="sm" />
+<Loader variant="circular" size="md" />
+<Loader variant="circular" size="lg" />`),
+};
+
+/** A single variant rendered at all three sizes (showcase). */
+export const AllSizes: Story = {
+  render: () => (
+    <div class="flex items-end gap-6">
+      <div class="text-center space-y-2">
+        <Loader variant="circular" size="sm" />
+        <p class="text-xs text-muted-foreground">Small</p>
+      </div>
+      <div class="text-center space-y-2">
+        <Loader variant="circular" size="md" />
+        <p class="text-xs text-muted-foreground">Medium</p>
+      </div>
+      <div class="text-center space-y-2">
+        <Loader variant="circular" size="lg" />
+        <p class="text-xs text-muted-foreground">Large</p>
+      </div>
+    </div>
+  ),
+  ...src(`<Loader variant="circular" size="sm" />
+<Loader variant="circular" size="md" />
+<Loader variant="circular" size="lg" />`),
+};