@kitn.ai/ui 0.14.1

package/src/elements/source.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 { 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-source': JSX.HTMLAttributes<HTMLElement> & { href?: string; label?: string; headline?: string; description?: string; 'show-favicon'?: boolean | '' };
+    }
+  }
+}
+
+/** Render the actual `<kai-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 <kai-source ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-source
+  href="https://kitn.dev"
+  label="kitn"
+  headline="kitn — the kit"
+  description="Composable SolidJS + web-component chat UI."
+  show-favicon
+></kai-source>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Components/Source',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-source'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-source', [
+          '`<kai-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 `<kai-sources>`; in SolidJS, compose the `Source` primitives.',
+          '**Placement:** inline within message text (beside a sentence or at the end of a paragraph) or as a standalone citation chip below a message; it is an `inline-block` element that fits naturally within flow content.',
+          "**How to use:** register once with `import '@kitn.ai/ui/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.',
+        ]),
+    },
+  },
+} 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/source.tsx

@@ -0,0 +1,120 @@
+import { createSignal, For, onCleanup, onMount, Show } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Source, SourceTrigger, SourceContent, SourceList } from '../components/source';
+
+// --- <kai-source> — a single citation link with hover preview ---
+
+interface SourceProps extends Record<string, unknown> {
+  /** The URL this citation links to (the domain also seeds the default label/favicon). */
+  href?: string;
+  /** Trigger label (defaults to the domain). */
+  label?: string;
+  /** Hover-card headline. Attribute: `headline` (`title` is avoided — it's a
+   *  global HTML attribute that reflects in a CE constructor and breaks it). */
+  headline?: string;
+  /** Hover-card body text describing the source. */
+  description?: string;
+  /** Show the source's favicon next to the trigger label. */
+  showFavicon?: boolean;
+}
+
+defineWebComponent<SourceProps>('kai-source', {
+  href: '',
+  label: undefined,
+  headline: '',
+  description: '',
+  showFavicon: false,
+}, (props, { flag }) => (
+  <Show when={props.href}>
+    <Source href={props.href!}>
+      <SourceTrigger label={props.label} showFavicon={flag('showFavicon')} />
+      <SourceContent title={props.headline ?? ''} description={props.description ?? ''} />
+    </Source>
+  </Show>
+));
+
+// --- <kai-sources> — a wrapped list of citation links ---
+
+interface SourceItem {
+  href: string;
+  title?: string;
+  description?: string;
+  label?: string;
+  showFavicon?: boolean;
+}
+
+interface SourceListProps extends Record<string, unknown> {
+  /** The sources to render. Set as a JS property. */
+  sources: SourceItem[];
+  /** Show favicons on all items (per-item `showFavicon` overrides). */
+  showFavicon?: boolean;
+  /**
+   * When true, each citation chip is labelled with its 1-based index in the
+   * merged (prop + declarative-children) list (`[1]`, `[2]`, …) instead of the
+   * per-item `label` or domain fallback.
+   *
+   * HTML attribute: `numbered` (boolean — bare attribute or `numbered="true"`).
+   * JS property:   `el.numbered = true`.
+   */
+  numbered?: boolean;
+}
+
+/** Parse a single light-DOM `<kai-source>` element into a `SourceItem` descriptor.
+ *  Attribute mapping:
+ *   - `href`        → SourceItem.href
+ *   - `label`       → SourceItem.label
+ *   - `headline`    → SourceItem.title  (matches kai-source's prop name; "title" is a
+ *                       reserved HTMLElement attribute so kai-source uses "headline")
+ *   - `description` → SourceItem.description
+ *   - `show-favicon`→ SourceItem.showFavicon (bare boolean attribute)
+ */
+export function parseKaiSourceElement(n: Element): SourceItem {
+  return {
+    href: n.getAttribute('href') ?? '',
+    label: n.getAttribute('label') ?? undefined,
+    title: n.getAttribute('headline') ?? undefined,
+    description: n.getAttribute('description') ?? undefined,
+    showFavicon: n.hasAttribute('show-favicon') && n.getAttribute('show-favicon') !== 'false',
+  };
+}
+
+defineWebComponent<SourceListProps>('kai-sources', {
+  sources: [],
+  showFavicon: false,
+  numbered: false,
+}, (props, { element, flag }) => {
+  // Read declarative <kai-source> children from light DOM.
+  // The shadow root has no <slot> for them, so they are invisible — pure data carriers.
+  const [slottedSources, setSlottedSources] = createSignal<SourceItem[]>([]);
+  onMount(() => {
+    const read = () => {
+      const nodes = [...element.querySelectorAll('kai-source')];
+      setSlottedSources(nodes.map(parseKaiSourceElement));
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, attributes: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  // Prop sources take precedence; slotted children are appended after.
+  const allSources = () => [...props.sources, ...slottedSources()];
+
+  const isNumbered = () => flag('numbered');
+
+  return (
+    <SourceList>
+      <For each={allSources()}>
+        {(s, i) => (
+          <Source href={s.href}>
+            <SourceTrigger
+              label={isNumbered() ? i() + 1 : s.label}
+              showFavicon={s.showFavicon ?? flag('showFavicon')}
+            />
+            <SourceContent title={s.title ?? ''} description={s.description ?? ''} />
+          </Source>
+        )}
+      </For>
+    </SourceList>
+  );
+});

package/src/elements/styles.css

@@ -0,0 +1,199 @@
+/* Element-bundle stylesheet. Compiled to compiled.css and injected into each
+   custom element's shadow root. Mirrors .storybook/styles.css but scans src/. */
+@import "tailwindcss";
+@import "../../theme.css";
+@plugin "@tailwindcss/typography";
+
+@source "../";
+
+@layer base {
+  /* Base typography is token-driven so a theme can restyle it. --kai-font-base is
+     the family for ALL text/UI (named "base", not "sans", so a serif body works);
+     --kai-tracking is global letter-spacing. Both pierce the Shadow DOM via the
+     var() fallback, exactly like the --kai-color-* tokens. */
+  :host {
+    display: block;
+    font-family: var(--kai-font-base, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);
+    letter-spacing: var(--kai-tracking, normal);
+  }
+  /* Code/monospace surfaces use --kai-font-code (named for its ROLE — code — not
+     "mono", so any family works). Covers inline code, <pre>, and code blocks. */
+  code, kbd, samp, pre {
+    font-family: var(--kai-font-code, ui-monospace, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace);
+  }
+  * { border-color: var(--color-border); }
+
+  /* Native controls (date/time pickers, <select>, number spinners, the
+     checkbox/radio fallbacks, scrollbars) must follow the kit's light/dark
+     mode — NOT the OS — so e.g. the native calendar icon never renders black
+     on a dark surface. `color-scheme` drives that native rendering; we set it
+     from the resolved mode (the `.dark` scope the element factory toggles). */
+  :host { color-scheme: light; }
+  .dark { color-scheme: dark; }
+
+  /* One token-driven focus ring for EVERY focusable element in the shadow root.
+     Blue by default (via --color-ring), consistent in light + dark, and
+     overridable through --kai-color-ring. Uses `outline` (not a box-shadow
+     ring) so it never clips on overflow and follows the element's radius;
+     `:focus-visible` so it only appears for keyboard navigation, never on a
+     mouse click. Components that render their own ring set
+     `focus-visible:outline-none` (a utility in a later cascade layer) and win
+     over this — so there's no double ring, just a guaranteed blue fallback for
+     the many controls that have no explicit focus style. */
+  :focus-visible {
+    outline: 2px solid var(--color-ring);
+    outline-offset: 2px;
+  }
+
+  /* Consistent cross-platform scrollbars for EVERY scroll region inside the
+     shadow root (message list, conversation list, menus, hover cards, code
+     blocks, the prompt textarea …). Thin + rounded + subtle, themed via tokens
+     for light/dark, thumb stronger on hover. Track stays transparent and
+     overflow is untouched, so no scrollbar is forced where none is needed.
+     Scoped to the shadow root, so it never restyles the host page. */
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: var(--color-scrollbar-thumb) transparent;
+  }
+  *::-webkit-scrollbar { width: 8px; height: 8px; }
+  *::-webkit-scrollbar-track { background: transparent; }
+  *::-webkit-scrollbar-thumb {
+    background-color: var(--color-scrollbar-thumb);
+    border-radius: 9999px;
+    border: 2px solid transparent;
+    background-clip: padding-box;
+  }
+  *::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }
+  *::-webkit-scrollbar-corner { background: transparent; }
+}
+
+@layer components {
+  /* Designed radio + checkbox (appearance-none) so the form controls read as
+     intentional, theme correctly in light/dark, and have comfortable targets —
+     replacing the weak native defaults. Used via `.kai-radio` / `.kai-checkbox`. */
+  .kai-radio,
+  .kai-checkbox {
+    appearance: none;
+    -webkit-appearance: none;
+    inline-size: 1.125rem;
+    block-size: 1.125rem;
+    margin: 0;
+    flex-shrink: 0;
+    cursor: pointer;
+    border: 1.5px solid var(--color-input);
+    background-color: var(--color-background);
+    display: inline-grid;
+    place-content: center;
+    box-shadow: 0 1px 2px rgb(0 0 0 / 0.04);
+    transition: border-color 0.18s ease, background-color 0.18s ease, box-shadow 0.18s ease,
+      transform 0.1s ease;
+  }
+  .kai-radio { border-radius: 9999px; }
+  .kai-checkbox { border-radius: 0.3rem; }
+  .kai-radio::after {
+    content: "";
+    inline-size: 0.5rem;
+    block-size: 0.5rem;
+    border-radius: 9999px;
+    background-color: var(--color-primary);
+    transform: scale(0);
+    transition: transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+  }
+  .kai-radio:checked { border-color: var(--color-primary); }
+  .kai-radio:checked::after { transform: scale(1); }
+  .kai-checkbox:checked {
+    background-color: var(--color-primary);
+    border-color: var(--color-primary);
+  }
+  .kai-checkbox::after {
+    content: "";
+    inline-size: 0.8rem;
+    block-size: 0.8rem;
+    background-color: var(--color-primary-foreground);
+    transform: scale(0);
+    transition: transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+    -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E") center / contain no-repeat;
+    mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E") center / contain no-repeat;
+  }
+  .kai-checkbox:checked::after { transform: scale(1); }
+  .kai-radio:hover:not(:disabled),
+  .kai-checkbox:hover:not(:disabled) {
+    border-color: var(--color-primary);
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--color-primary) 9%, transparent);
+  }
+  .kai-radio:active:not(:disabled),
+  .kai-checkbox:active:not(:disabled) { transform: scale(0.92); }
+  .kai-checkbox:checked {
+    box-shadow: 0 1px 4px color-mix(in srgb, var(--color-primary) 26%, transparent);
+  }
+  .kai-radio:disabled,
+  .kai-checkbox:disabled { opacity: 0.5; cursor: not-allowed; }
+
+  /* Custom range slider: a filled track (--kai-range-fill set by the widget) and a
+     refined thumb that scales on hover/press with a focus halo — no native chrome. */
+  .kai-range {
+    appearance: none;
+    -webkit-appearance: none;
+    inline-size: 100%;
+    block-size: 1.25rem;
+    background: transparent;
+    cursor: pointer;
+    margin: 0;
+  }
+  .kai-range::-webkit-slider-runnable-track {
+    block-size: 0.375rem;
+    border-radius: 9999px;
+    border: none;
+    box-shadow: none;
+    background: linear-gradient(
+      to right,
+      var(--color-primary) var(--kai-range-fill, 0%),
+      var(--color-muted) var(--kai-range-fill, 0%)
+    );
+  }
+  .kai-range::-moz-range-track {
+    block-size: 0.375rem;
+    border-radius: 9999px;
+    border: none;
+    box-shadow: none;
+    background: var(--color-muted);
+  }
+  .kai-range::-moz-range-progress {
+    block-size: 0.375rem;
+    border-radius: 9999px;
+    background: var(--color-primary);
+  }
+  .kai-range::-webkit-slider-thumb {
+    appearance: none;
+    -webkit-appearance: none;
+    inline-size: 1.125rem;
+    block-size: 1.125rem;
+    border-radius: 9999px;
+    background: var(--color-background);
+    border: 2px solid var(--color-primary);
+    box-shadow: 0 1px 3px rgb(0 0 0 / 0.18);
+    margin-block-start: -0.375rem;
+    transition: transform 0.12s ease, box-shadow 0.12s ease;
+  }
+  .kai-range::-moz-range-thumb {
+    inline-size: 1.125rem;
+    block-size: 1.125rem;
+    border-radius: 9999px;
+    background: var(--color-background);
+    border: 2px solid var(--color-primary);
+    box-shadow: 0 1px 3px rgb(0 0 0 / 0.18);
+    transition: transform 0.12s ease, box-shadow 0.12s ease;
+  }
+  .kai-range:hover::-webkit-slider-thumb { transform: scale(1.12); }
+  .kai-range:hover::-moz-range-thumb { transform: scale(1.12); }
+  .kai-range:focus-visible { outline: none; }
+  .kai-range:focus-visible::-webkit-slider-thumb,
+  .kai-range:active::-webkit-slider-thumb {
+    box-shadow: 0 0 0 6px color-mix(in srgb, var(--color-primary) 14%, transparent);
+  }
+  .kai-range:focus-visible::-moz-range-thumb,
+  .kai-range:active::-moz-range-thumb {
+    box-shadow: 0 0 0 6px color-mix(in srgb, var(--color-primary) 14%, transparent);
+  }
+  .kai-range:disabled { opacity: 0.5; cursor: not-allowed; }
+}

package/src/elements/switch.stories.tsx

@@ -0,0 +1,56 @@
+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';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-switch': JSX.HTMLAttributes<HTMLElement> & { checked?: boolean | string; disabled?: boolean | string; label?: string };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<kai-switch checked label="Temporary chat"></kai-switch>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+  document.querySelector('kai-switch')
+    .addEventListener('kai-change', (e) => console.log('checked:', e.detail.checked));
+</script>`;
+
+const meta = {
+  title: 'Components/Switch',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-switch'),
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: specDescription('kai-switch', [
+        '`<kai-switch>` is the framework-agnostic **web component** toggle — a `role="switch"` control isolated in **Shadow DOM**. In SolidJS, use the `Switch` primitive.',
+        '**When to use:** an immediate on/off setting (e.g. "Temporary chat") in a header menu, settings row, or preference panel.',
+        '**How to use:** set the initial state with the `checked` attribute and read changes from the `kai-change` **CustomEvent** (payload `{ checked }`). The element self-manages its state.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A self-managing toggle; logs each change. */
+export const Default: Story = {
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => el?.addEventListener('kai-change', (e) => console.log('kai-change', (e as CustomEvent<{ checked: boolean }>).detail.checked)));
+    return <kai-switch ref={(e) => (el = e as HTMLElement)} label="Temporary chat" style={{ display: 'inline-block', padding: '40px' }} />;
+  },
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Starts on via the bare `checked` attribute. */
+export const On: Story = {
+  render: () => <kai-switch checked label="Notifications" style={{ display: 'inline-block', padding: '40px' }} />,
+};

package/src/elements/switch.tsx

@@ -0,0 +1,43 @@
+import { defineWebComponent } from './define';
+import { Switch } from '../ui/switch';
+
+interface Props extends Record<string, unknown> {
+  /** Initial checked state. Bare attribute (`<kai-switch checked>`) turns it on. */
+  checked?: boolean;
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Accessible label. */
+  label?: string;
+}
+
+/** Events fired by `<kai-switch>`. */
+interface Events {
+  /** The toggle changed. */
+  'kai-change': { checked: boolean };
+}
+
+/**
+ * `<kai-switch>` — a toggle switch. Self-manages its on/off state; set the initial
+ * state with the `checked` attribute and read changes from `kai-change`.
+ *
+ * ```html
+ * <kai-switch checked label="Temporary chat"></kai-switch>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   document.querySelector('kai-switch')
+ *     .addEventListener('kai-change', (e) => console.log(e.detail.checked));
+ * </script>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-switch', {
+  checked: undefined,
+  disabled: undefined,
+  label: undefined,
+}, (props, { dispatch, flag }) => (
+  <Switch
+    defaultChecked={flag('checked')}
+    disabled={flag('disabled')}
+    label={props.label as string | undefined}
+    onChange={(checked) => dispatch('kai-change', { checked })}
+  />
+));