@kitn.ai/ui 0.14.1

package/src/elements/scroll-button.stories.tsx

@@ -0,0 +1,202 @@
+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-scroll-button': JSX.HTMLAttributes<HTMLElement> & {
+        for?: string;
+        variant?: string;
+        size?: string;
+        'on:kai-scroll'?: (e: CustomEvent) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<div id="my-chat" style="height:300px; overflow-y:auto; border:1px solid #eee; padding:16px">
+  <!-- scrollable content -->
+</div>
+
+<!-- Button targets the scroll container by id -->
+<kai-scroll-button for="my-chat"></kai-scroll-button>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const btn = document.querySelector('kai-scroll-button');
+  btn.addEventListener('kai-scroll', () => console.log('scrolled to bottom'));
+</script>`;
+
+const meta = {
+  title: 'Components/ScrollButton',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-scroll-button'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-scroll-button', [
+        '`<kai-scroll-button>` is the framework-agnostic **web component** for a floating "scroll to bottom" button — visible when the target container is scrolled up, hidden when already at the bottom. Isolated in **Shadow DOM**.',
+        '**When to use:** placing a scroll-to-bottom affordance next to any long scrollable list or chat thread outside SolidJS. In SolidJS, use the `ScrollButton` primitive inside a `ChatContainerRoot`.',
+        '**Wiring the scroll target:** set the `for` attribute to the `id` of the scrollable container (mirrors the `<label for="...">` convention). When `for` is omitted the element walks upward to the nearest scrollable ancestor — useful when it is nested inside the container.',
+        '**Emitted events:** `kai-scroll` (no detail) fires each time the button is clicked and `scrollToBottom()` is called.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Scroll-to-bottom button controlled by a sibling scrollable container via `for`. */
+export const Default: Story = {
+  render: () => {
+    const items = Array.from({ length: 30 }, (_, i) => `Message ${i + 1}`);
+    return (
+      <div style={{ padding: '24px', position: 'relative', width: '360px' }}>
+        <div
+          id="scroll-demo"
+          tabindex="0"
+          role="region"
+          aria-label="Messages"
+          style={{
+            height: '300px',
+            'overflow-y': 'auto',
+            border: '1px solid var(--color-border, #e2e8f0)',
+            'border-radius': '8px',
+            padding: '12px',
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '8px',
+          }}
+        >
+          {items.map((msg) => (
+            <div
+              style={{
+                padding: '8px 12px',
+                background: 'var(--color-muted, #f1f5f9)',
+                'border-radius': '6px',
+                'font-size': '14px',
+              }}
+            >
+              {msg}
+            </div>
+          ))}
+        </div>
+        {/* Positioned overlay in the bottom-right of the container */}
+        <div
+          style={{
+            position: 'absolute',
+            bottom: '36px',
+            right: '36px',
+            'pointer-events': 'none',
+          }}
+        >
+          <div style={{ 'pointer-events': 'auto' }}>
+            <kai-scroll-button
+              for="scroll-demo"
+              on:kai-scroll={() => console.log('kai-scroll fired')}
+            />
+          </div>
+        </div>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Nested inside the scroll container — no `for` needed; ancestor walk finds it. */
+export const AncestorWalk: Story = {
+  render: () => {
+    const items = Array.from({ length: 30 }, (_, i) => `Entry ${i + 1}`);
+    return (
+      <div style={{ padding: '24px', width: '360px' }}>
+        <div
+          style={{
+            height: '300px',
+            'overflow-y': 'auto',
+            border: '1px solid var(--color-border, #e2e8f0)',
+            'border-radius': '8px',
+            padding: '12px',
+            position: 'relative',
+          }}
+        >
+          {items.map((entry) => (
+            <div
+              style={{
+                padding: '8px 12px',
+                background: 'var(--color-muted, #f1f5f9)',
+                'border-radius': '6px',
+                'font-size': '14px',
+                'margin-bottom': '8px',
+              }}
+            >
+              {entry}
+            </div>
+          ))}
+          {/* No `for` — element is a child of the scrollable container */}
+          <div
+            style={{
+              position: 'sticky',
+              bottom: '8px',
+              display: 'flex',
+              'justify-content': 'center',
+            }}
+          >
+            <kai-scroll-button />
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** Variant and size showcase. */
+export const Variants: Story = {
+  render: () => {
+    const items = Array.from({ length: 20 }, (_, i) => `Row ${i + 1}`);
+    return (
+      <div
+        style={{
+          display: 'flex',
+          gap: '32px',
+          padding: '24px',
+          'align-items': 'flex-start',
+          'flex-wrap': 'wrap',
+        }}
+      >
+        {(['outline', 'ghost', 'default'] as const).map((variant) => (
+          <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px', 'align-items': 'center' }}>
+            <div
+              tabindex="0"
+              role="region"
+              aria-label={`${variant} scroll demo`}
+              style={{
+                height: '200px',
+                width: '200px',
+                'overflow-y': 'auto',
+                border: '1px solid var(--color-border, #e2e8f0)',
+                'border-radius': '8px',
+                padding: '8px',
+                position: 'relative',
+              }}
+              id={`variant-demo-${variant}`}
+            >
+              {items.map((r) => (
+                <div style={{ padding: '4px 8px', 'font-size': '13px' }}>{r}</div>
+              ))}
+            </div>
+            <kai-scroll-button for={`variant-demo-${variant}`} variant={variant} />
+            <code style={{ 'font-size': '11px', opacity: 0.6 }}>{variant}</code>
+          </div>
+        ))}
+      </div>
+    );
+  },
+};

package/src/elements/scroll-button.test.tsx

@@ -0,0 +1,148 @@
+/**
+ * Unit tests for the `kai-scroll-button` scroll-target resolution logic.
+ *
+ * Strategy: `defineWebComponent` requires a real browser environment
+ * (Constructable Stylesheets, shadow roots) and is not suitable for jsdom.
+ * Instead we:
+ *   1. Test the `findScrollableAncestor` helper in isolation — it only uses
+ *      DOM APIs that jsdom provides.
+ *   2. Test the Solid `Button` + visibility-toggle logic that drives the
+ *      show/hide animation, using the underlying component directly (mirrors
+ *      the pattern in `prompt-suggestions.declarative.test.tsx`).
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, cleanup, fireEvent } from '@solidjs/testing-library';
+import { createSignal } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+import { ChevronDown } from 'lucide-solid';
+
+afterEach(cleanup);
+
+// ---------------------------------------------------------------------------
+// findScrollableAncestor — re-implemented inline so we can test without
+// importing the full element (which would call defineWebComponent).
+// ---------------------------------------------------------------------------
+
+function findScrollableAncestor(startEl: HTMLElement): HTMLElement | null {
+  let el: HTMLElement | null = startEl.parentElement;
+  while (el && el !== document.documentElement) {
+    const style = getComputedStyle(el);
+    const overflow = style.overflow + style.overflowY;
+    if (/auto|scroll/.test(overflow) && el.scrollHeight > el.clientHeight) {
+      return el;
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
+describe('findScrollableAncestor', () => {
+  it('returns null when no scrollable ancestor exists', () => {
+    const wrapper = document.createElement('div');
+    const child = document.createElement('span');
+    wrapper.appendChild(child);
+    document.body.appendChild(wrapper);
+    expect(findScrollableAncestor(child)).toBeNull();
+    document.body.removeChild(wrapper);
+  });
+
+  it('returns the first scrollable ancestor', () => {
+    const scrollable = document.createElement('div');
+    scrollable.style.overflow = 'auto';
+    // jsdom doesn't do layout, so scrollHeight === clientHeight by default.
+    // Force a difference by mocking.
+    Object.defineProperty(scrollable, 'scrollHeight', { value: 500, configurable: true });
+    Object.defineProperty(scrollable, 'clientHeight', { value: 300, configurable: true });
+
+    const child = document.createElement('div');
+    scrollable.appendChild(child);
+    document.body.appendChild(scrollable);
+
+    expect(findScrollableAncestor(child)).toBe(scrollable);
+    document.body.removeChild(scrollable);
+  });
+
+  it('skips non-scrollable ancestors', () => {
+    const nonScrollable = document.createElement('div');
+    const scrollable = document.createElement('div');
+    scrollable.style.overflowY = 'scroll';
+    Object.defineProperty(scrollable, 'scrollHeight', { value: 500, configurable: true });
+    Object.defineProperty(scrollable, 'clientHeight', { value: 300, configurable: true });
+
+    const child = document.createElement('span');
+    nonScrollable.appendChild(child);
+    scrollable.appendChild(nonScrollable);
+    document.body.appendChild(scrollable);
+
+    expect(findScrollableAncestor(child)).toBe(scrollable);
+    document.body.removeChild(scrollable);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Visibility toggle logic — ScrollButtonUI mirrors the render logic inside
+// kai-scroll-button's facade.
+// ---------------------------------------------------------------------------
+
+/** Minimal SolidJS component that mirrors the button render in scroll-button.tsx. */
+function ScrollButtonUI(props: {
+  isAtBottom: () => boolean;
+  onClick: () => void;
+}) {
+  return (
+    <Button
+      variant="outline"
+      size="icon"
+      aria-label="Scroll to bottom"
+      class={cn(
+        'rounded-full transition-all duration-150 ease-out',
+        !props.isAtBottom()
+          ? 'translate-y-0 scale-100 opacity-100'
+          : 'pointer-events-none translate-y-4 scale-95 opacity-0',
+      )}
+      onClick={props.onClick}
+    >
+      <ChevronDown class="h-5 w-5" />
+    </Button>
+  );
+}
+
+describe('scroll button visibility logic', () => {
+  it('is visually hidden when at bottom (has opacity-0 class)', () => {
+    const { getByRole } = render(() => (
+      <ScrollButtonUI isAtBottom={() => true} onClick={() => {}} />
+    ));
+    const btn = getByRole('button', { name: /scroll to bottom/i });
+    expect(btn.className).toMatch(/opacity-0/);
+  });
+
+  it('is visible when not at bottom (has opacity-100 class)', () => {
+    const { getByRole } = render(() => (
+      <ScrollButtonUI isAtBottom={() => false} onClick={() => {}} />
+    ));
+    const btn = getByRole('button', { name: /scroll to bottom/i });
+    expect(btn.className).toMatch(/opacity-100/);
+  });
+
+  it('calls onClick when the button is clicked', () => {
+    const onClick = vi.fn();
+    const { getByRole } = render(() => (
+      <ScrollButtonUI isAtBottom={() => false} onClick={onClick} />
+    ));
+    fireEvent.click(getByRole('button', { name: /scroll to bottom/i }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('reacts to isAtBottom signal changes', () => {
+    const [atBottom, setAtBottom] = createSignal(false);
+    const { getByRole } = render(() => (
+      <ScrollButtonUI isAtBottom={atBottom} onClick={() => {}} />
+    ));
+    const btn = getByRole('button', { name: /scroll to bottom/i });
+    expect(btn.className).toMatch(/opacity-100/);
+    setAtBottom(true);
+    expect(btn.className).toMatch(/opacity-0/);
+  });
+});

package/src/elements/scroll-button.tsx

@@ -0,0 +1,126 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+import { ChevronDown } from 'lucide-solid';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** CSS id of the scroll container to control. When omitted the element
+   *  walks up the DOM (outside its own shadow root) to find the nearest
+   *  scrollable ancestor. Mirrors the `for` convention of `<label for="...">`. */
+  for?: string;
+  /** Button visual variant: `'outline' | 'ghost' | 'default'`. Defaults to
+   *  `'outline'`. */
+  variant?: 'outline' | 'ghost' | 'default';
+  /** Button size token. Defaults to `'icon'` (square). */
+  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+}
+
+/** Events fired by `<kai-scroll-button>`. */
+interface Events {
+  /** Emitted when the user clicks the button and `scrollToBottom()` is
+   *  called. Carries no detail — consumers use it to know a manual scroll
+   *  occurred. */
+  'kai-scroll': void;
+}
+
+const SCROLL_THRESHOLD = 50;
+
+/** Walk the composed tree upwards from `startEl` (outside shadow roots) to
+ *  find the nearest scrollable ancestor. */
+function findScrollableAncestor(startEl: HTMLElement): HTMLElement | null {
+  let el: HTMLElement | null = startEl.parentElement;
+  while (el && el !== document.documentElement) {
+    const style = getComputedStyle(el);
+    const overflow = style.overflow + style.overflowY;
+    if (/auto|scroll/.test(overflow) && el.scrollHeight > el.clientHeight) {
+      return el;
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/**
+ * `<kai-scroll-button>` — a floating "scroll to bottom" button for any
+ * scrollable container. It is visible when the container is scrolled up
+ * (hidden when at the bottom) and scrolls the container to the bottom on
+ * click.
+ *
+ * **Wiring the scroll target** — use the `for` attribute to point at the
+ * container by its DOM `id`:
+ * ```html
+ * <div id="my-chat" style="overflow:auto; height:400px">...</div>
+ * <kai-scroll-button for="my-chat"></kai-scroll-button>
+ * ```
+ * When `for` is omitted the element walks upward from its host to the nearest
+ * scrollable ancestor — useful when it is slotted or nested inside the
+ * container.
+ *
+ * Emits `kai-scroll` (no detail) each time the button is clicked.
+ */
+defineWebComponent<Props, Events>('kai-scroll-button', {
+  for: undefined,
+  variant: 'outline',
+  size: 'icon',
+}, (props, { element, dispatch }) => {
+  const [isAtBottom, setIsAtBottom] = createSignal(true);
+  let containerEl: HTMLElement | null = null;
+  let cleanupFns: (() => void)[] = [];
+
+  function checkIfAtBottom() {
+    if (!containerEl) return;
+    const { scrollTop, scrollHeight, clientHeight } = containerEl;
+    setIsAtBottom(scrollHeight - scrollTop - clientHeight < SCROLL_THRESHOLD);
+  }
+
+  function scrollToBottom() {
+    if (!containerEl) return;
+    containerEl.scrollTo({ top: containerEl.scrollHeight, behavior: 'smooth' });
+    setIsAtBottom(true);
+  }
+
+  function attach(el: HTMLElement) {
+    containerEl = el;
+    el.addEventListener('scroll', checkIfAtBottom, { passive: true });
+    checkIfAtBottom();
+    cleanupFns.push(() => el.removeEventListener('scroll', checkIfAtBottom));
+  }
+
+  function detach() {
+    cleanupFns.forEach((fn) => fn());
+    cleanupFns = [];
+    containerEl = null;
+  }
+
+  onMount(() => {
+    // Resolve the scroll container: `for` id → nearest scrollable ancestor.
+    const target = props.for
+      ? document.getElementById(props.for)
+      : findScrollableAncestor(element);
+
+    if (target) attach(target);
+  });
+
+  onCleanup(detach);
+
+  return (
+    <Button
+      variant={props.variant ?? 'outline'}
+      size={props.size ?? 'icon'}
+      aria-label="Scroll to bottom"
+      class={cn(
+        'rounded-full transition-all duration-150 ease-out',
+        !isAtBottom()
+          ? 'translate-y-0 scale-100 opacity-100'
+          : 'pointer-events-none translate-y-4 scale-95 opacity-0',
+      )}
+      onClick={() => {
+        scrollToBottom();
+        dispatch('kai-scroll');
+      }}
+    >
+      <ChevronDown class="h-5 w-5" />
+    </Button>
+  );
+});

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

@@ -0,0 +1,143 @@
+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-sources': JSX.HTMLAttributes<HTMLElement>;
+      'kai-source': JSX.HTMLAttributes<HTMLElement> & { href?: string; label?: string; headline?: string; description?: string; 'show-favicon'?: boolean | '' };
+    }
+  }
+}
+
+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 `<kai-sources>` custom element with a `sources` property. */
+function SourceListElement() {
+  let el: (HTMLElement & { sources?: SourceItem[] }) | undefined;
+  onMount(() => {
+    if (el) el.sources = sampleSources;
+  });
+  return (
+    <kai-sources 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-sources id="srcs" show-favicon></kai-sources>
+
+<script type="module">
+  import '@kitn.ai/ui/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: 'Components/Sources',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-sources'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-sources', [
+          '`<kai-sources>` 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 `<kai-source>`; in SolidJS, compose `SourceList` + `Source`.',
+          '**Placement:** below an assistant message, above the prompt input — rendered as a wrapping row of citation chips that spans the full message column width.',
+          "**How to use:** register once with `import '@kitn.ai/ui/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).",
+          '**Anatomy:** a wrapping flex row of **citation chips** — each chip is a `<kai-source>` (or a `sources`-property item): a **trigger button** (domain label or `numbered` index, optional favicon) + a **hover-card** (headline + description, shown on hover/focus). Declarative `<kai-source href="…" headline="…">` children are invisible data carriers merged after the `sources` property list.',
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} 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' } } },
+};
+
+const DECLARATIVE_HTML_SNIPPET = `<!-- Works in any framework or plain HTML — no JS wiring needed -->
+<kai-sources show-favicon>
+  <kai-source
+    href="https://kitn.dev"
+    label="kitn"
+    headline="kitn — the kit"
+    description="Composable SolidJS + web-component chat UI."
+    show-favicon
+  ></kai-source>
+  <kai-source
+    href="https://solidjs.com"
+    headline="SolidJS"
+    description="A reactive UI library."
+    show-favicon
+  ></kai-source>
+</kai-sources>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+</script>`;
+
+/** Declarative sources — `<kai-source>` light-DOM children instead of a `sources`
+ *  property. Each child carries `href`, `label`, `headline`, `description`, and the
+ *  `show-favicon` flag as HTML attributes. Great for plain HTML with no JS wiring. */
+export const DeclarativeSources: Story = {
+  name: 'Declarative Sources (kai-source)',
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.setAttribute('show-favicon', '');
+    });
+    return (
+      <kai-sources
+        ref={(e) => (el = e as HTMLElement)}
+        style={{ display: 'block', padding: '16px', 'max-width': '720px' }}
+      >
+        <kai-source
+          href="https://kitn.dev"
+          label="kitn"
+          headline="kitn — the kit"
+          description="Composable SolidJS + web-component chat UI."
+          show-favicon
+        ></kai-source>
+        <kai-source
+          href="https://solidjs.com"
+          headline="SolidJS"
+          description="A reactive UI library."
+          show-favicon
+        ></kai-source>
+      </kai-sources>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: DECLARATIVE_HTML_SNIPPET,
+        language: 'html',
+      },
+    },
+  },
+};