@kitnai/chat 0.6.0 → 0.8.0

package/src/elements/resizable.tsx

@@ -0,0 +1,264 @@
+import { createSignal, onMount, onCleanup, For, Show, type JSX } from 'solid-js';
+import { defineWebComponent } from './define';
+import { ResizableHandle, normalizeSize } from '../ui/resizable';
+
+type Orientation = 'horizontal' | 'vertical';
+
+/** Parsed view of a `<kc-resizable-item>` light child. */
+interface ItemInfo {
+  el: HTMLElement;
+  size?: string;
+  min?: string;
+  max?: string;
+  locked: boolean;
+  hidden: boolean;
+}
+
+/** Max number of panels a single group lays out (nest for more). */
+const MAX_ITEMS = 3;
+
+/** Convert a px-or-% bound to `data-*` attribute values the handle understands. */
+function boundAttrs(value: string | undefined): { pxAttr?: string; pctAttr?: string } {
+  if (value === undefined || value === '') return {};
+  const t = value.trim();
+  if (t.endsWith('px')) return { pxAttr: String(parseFloat(t)) };
+  if (t.endsWith('%')) return { pctAttr: String(parseFloat(t)) };
+  if (Number.isFinite(Number(t))) return { pctAttr: t };
+  return {};
+}
+
+interface GroupProps extends Record<string, unknown> {
+  /** Layout axis: `horizontal` (row, default) or `vertical` (column). */
+  orientation?: Orientation;
+}
+
+interface GroupEvents extends Record<string, unknown> {
+  /** Fired on drag-end / keyboard resize / visibility change. `detail.sizes` = panel sizes in percent. */
+  change: { sizes: number[] };
+}
+
+/**
+ * `<kc-resizable>` — a composable, resizable multi-panel layout (up to 3 panels)
+ * with auto-inserted draggable dividers. It lays out its `<kc-resizable-item>`
+ * light children along an axis (`orientation`), reading each item's `size`,
+ * `min`, `max`, `locked` and `hidden` attributes via a `MutationObserver`. A
+ * divider is interactive only between two unlocked, visible panels. Emits a
+ * `change` event (`detail.sizes`, percent) on resize / visibility change.
+ */
+defineWebComponent<GroupProps, GroupEvents>('kc-resizable', {
+  orientation: 'horizontal',
+}, (props, { element, dispatch }) => {
+  const [items, setItems] = createSignal<ItemInfo[]>([]);
+  const orientation = (): Orientation => (props.orientation === 'vertical' ? 'vertical' : 'horizontal');
+
+  /** Read the current `<kc-resizable-item>` light children + their attributes. */
+  function readItems() {
+    const all = Array.from(element.children).filter(
+      (c): c is HTMLElement => c.tagName.toLowerCase() === 'kc-resizable-item',
+    );
+    if (all.length > MAX_ITEMS) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `<kc-resizable>: only the first ${MAX_ITEMS} <kc-resizable-item> children are laid out ` +
+        `(got ${all.length}). Nest <kc-resizable> for more.`,
+      );
+    }
+    const capped = all.slice(0, MAX_ITEMS);
+    const parsed: ItemInfo[] = capped.map((el) => ({
+      el,
+      size: el.getAttribute('size') ?? undefined,
+      min: el.getAttribute('min') ?? undefined,
+      max: el.getAttribute('max') ?? undefined,
+      locked: el.hasAttribute('locked') && el.getAttribute('locked') !== 'false',
+      // Honour both the `hidden` boolean attribute and the IDL property — Solid
+      // (and direct `el.hidden = true`) set the property, which doesn't reflect
+      // to the attribute on a custom element.
+      hidden: el.hidden || (el.hasAttribute('hidden') && el.getAttribute('hidden') !== 'false'),
+    }));
+
+    // Assign each visible item to its panel slot by visible order; clear the
+    // rest so hidden/extra items don't leak into a slot.
+    let visIdx = 0;
+    for (const info of parsed) {
+      if (info.hidden) {
+        info.el.removeAttribute('slot');
+      } else {
+        info.el.setAttribute('slot', `p${visIdx}`);
+        visIdx++;
+      }
+    }
+    for (const el of all.slice(MAX_ITEMS)) el.removeAttribute('slot');
+
+    setItems(parsed);
+  }
+
+  const visible = () => items().filter((i) => !i.hidden);
+
+  /** Compute current panel sizes (percent of container) from the rendered DOM. */
+  function currentSizes(): number[] {
+    return visible().map((info) => {
+      const panel = info.el.assignedSlot?.closest('[data-panel]') as HTMLElement | null;
+      const target = panel ?? info.el;
+      const parent = target.parentElement;
+      const dim = orientation() === 'horizontal' ? 'width' : 'height';
+      const total = parent ? parent.getBoundingClientRect()[dim] : 0;
+      const val = target.getBoundingClientRect()[dim];
+      return total > 0 ? Math.round((val / total) * 100) : 0;
+    });
+  }
+
+  function emitChange() {
+    dispatch('change', { sizes: currentSizes() });
+  }
+
+  onMount(() => {
+    readItems();
+    const mo = new MutationObserver(() => {
+      readItems();
+      // A childList / attribute change (e.g. show/hide) re-lays out → emit.
+      queueMicrotask(emitChange);
+    });
+    mo.observe(element, {
+      childList: true,
+      // Attribute changes happen on the <kc-resizable-item> *children*, so we
+      // must observe the subtree (filtered to the config attributes) — not just
+      // the host's own attributes.
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['size', 'locked', 'min', 'max', 'hidden'],
+    });
+    onCleanup(() => mo.disconnect());
+  });
+
+  const isHoriz = () => orientation() === 'horizontal';
+
+  return (
+    <>
+      {/* A resizable layout fills its container — default the host to a block
+          that stretches, so consumers only need to give a parent (or the element)
+          a height. Override with an explicit height on the element if needed. */}
+      <style>{':host{display:block;height:100%}'}</style>
+    <div
+      data-resizable-root
+      data-orientation={orientation()}
+      style={{
+        display: 'flex',
+        'flex-direction': isHoriz() ? 'row' : 'column',
+        width: '100%',
+        height: '100%',
+      }}
+    >
+      <For each={visible()}>
+        {(info, i) => {
+          const min = boundAttrs(info.min);
+          const max = boundAttrs(info.max);
+          const basis = normalizeSize(info.size);
+          const prev = () => visible()[i() - 1];
+          const isStatic = () => !!(info.locked || prev()?.locked);
+          return (
+            <>
+              <Show when={i() > 0}>
+                <ResizableHandle
+                  withHandle
+                  orientation={orientation()}
+                  static={isStatic()}
+                  onPanelResize={() => queueMicrotask(emitChange)}
+                />
+              </Show>
+              <div
+                data-panel
+                data-locked={info.locked ? '' : undefined}
+                data-min-size={min.pxAttr}
+                data-min-size-pct={min.pctAttr}
+                data-max-size={max.pxAttr}
+                data-max-size-pct={max.pctAttr}
+                style={{
+                  // The panel is a flex item of the root: `flex-basis` sizes its
+                  // MAIN axis (width when horizontal, height when vertical) and the
+                  // drag/keyboard handlers rewrite that basis — so the layout spine
+                  // stays a plain flex row/column (drag math unchanged).
+                  //
+                  // For the FILL, the panel is itself a `display:grid` with a single
+                  // `minmax(0,1fr)` cell on BOTH axes. A grid item (the slotted
+                  // `<kc-resizable-item>`) stretches to fill its cell on both axes by
+                  // default (`place-items:stretch`), and a `1fr` track inside a
+                  // definite-sized grid is a *definite* length — so content fills
+                  // height AND width whether or not it sets `height:100%`, in both
+                  // orientations. A flex panel only stretches the CROSS axis (which is
+                  // why the previous `display:flex` panel collapsed the main axis to
+                  // content height). This mirrors how Shoelace/Web Awesome
+                  // `<sl-split-panel>` lay panels out with grid for guaranteed fill,
+                  // adapted here to a per-panel grid cell (our double slot boundary
+                  // makes a slot-as-grid-item unusable — a slot with assigned nodes
+                  // has a zero box). min:0 on both axes enables shrink-to-scroll;
+                  // overflow clips (the item owns the scroll).
+                  ...(basis !== undefined
+                    ? { 'flex-basis': basis, 'flex-grow': '0', 'flex-shrink': '0' }
+                    : { flex: '1 1 0%' }),
+                  display: 'grid',
+                  'grid-template-rows': 'minmax(0, 1fr)',
+                  'grid-template-columns': 'minmax(0, 1fr)',
+                  'min-width': '0',
+                  'min-height': '0',
+                  overflow: 'hidden',
+                }}
+              >
+                <slot name={`p${i()}`} />
+              </div>
+            </>
+          );
+        }}
+      </For>
+    </div>
+    </>
+  );
+});
+
+interface ItemProps extends Record<string, unknown> {
+  /** Initial main-axis size: `"280px"` (fixed) or `"25%"`/`25` (percent). Omitted → flexible. */
+  size?: string;
+  /** Minimum size during resize (px or %). */
+  min?: string;
+  /** Maximum size during resize (px or %). */
+  max?: string;
+  /** Fix this panel's size; adjacent dividers become non-draggable. */
+  locked?: boolean;
+  /** Hide this panel; its divider is dropped and the rest reflow. */
+  hidden?: boolean;
+}
+
+/**
+ * `<kc-resizable-item>` — a passive config-carrier inside `<kc-resizable>`. It
+ * renders its own slotted light content (`<slot/>`); the parent `<kc-resizable>`
+ * reads its `size`/`min`/`max`/`locked`/`hidden` attributes to lay it out.
+ */
+defineWebComponent<ItemProps>('kc-resizable-item', {
+  size: undefined,
+  min: undefined,
+  max: undefined,
+  locked: false,
+  hidden: false,
+}, () => (
+  <>
+    {/* The item host fills the panel's single grid cell (the panel stretches it on
+        both axes) and OWNS the scroll: `display:block; width/height:100%;
+        overflow:auto`. min:0 enables shrink-to-scroll.
+
+        The FILL of the *slotted* content happens one level in: a `display:grid`
+        wrapper with a single `minmax(0,1fr)` cell whose ONLY child is the `<slot>`.
+        A grid item stretches to fill its cell on BOTH axes by default
+        (`place-items:stretch`) into a *definite* `1fr` track, so slotted content
+        fills width AND height whether or not it sets `height:100%`. The grid MUST
+        be its own element wrapping the slot — NOT the host — because the element
+        facade renders an empty portal-mount `<div>` (for overlays) as a sibling of
+        the facade output; if the host itself were the grid, that portal div would
+        become a second grid item and steal a track (collapsing content to the auto
+        row). Scoping the grid to a wrapper whose sole child is the slot keeps
+        exactly one grid item and is robust to the facade's portal sibling.
+        Mirrors how Shoelace/Web Awesome `<sl-split-panel>` use grid for fill. */}
+    <style>{':host{display:block;width:100%;height:100%;min-width:0;min-height:0;overflow:auto}'}</style>
+    <div style={{ display: 'grid', 'grid-template-rows': 'minmax(0, 1fr)', 'grid-template-columns': 'minmax(0, 1fr)', width: '100%', height: '100%', 'min-width': '0', 'min-height': '0' }}>
+      <slot />
+    </div>
+  </>
+) as unknown as JSX.Element);

package/src/elements/{kitn-response-stream.stories.tsx → response-stream.stories.tsx}

@@ -1,13 +1,14 @@
 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 {
-      'kitn-response-stream': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-response-stream': JSX.HTMLAttributes<HTMLElement> & {
         mode?: string;
         speed?: number;
       };
@@ -18,14 +19,14 @@ declare module 'solid-js' {
 const STREAM_TEXT =
   "This text reveals with a typewriter animation, streamed character by character — exactly how you'd render a live assistant reply.";
 
-/** Render `<kitn-response-stream>` with the `text` set as a JS property. */
+/** Render `<kc-response-stream>` with the `text` set as a JS property. */
 function StreamElement(props: { text: string; mode?: string; speed?: number }) {
   let el: (HTMLElement & { text?: string }) | undefined;
   onMount(() => {
     if (el) el.text = props.text;
   });
   return (
-    <kitn-response-stream
+    <kc-response-stream
       ref={(e) => (el = e as HTMLElement)}
       mode={props.mode}
       speed={props.speed}
@@ -35,7 +36,7 @@ function StreamElement(props: { text: string; mode?: string; speed?: number }) {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-response-stream id="stream" mode="typewriter" speed="20"></kitn-response-stream>
+<kc-response-stream id="stream" mode="typewriter" speed="20"></kc-response-stream>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -47,19 +48,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-response-stream',
+  title: 'Web Components/kc-response-stream',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-response-stream'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-response-stream>` is the framework-agnostic **web component** that reveals text with a typewriter or fade animation — the building block for streamed assistant replies, isolated in **Shadow DOM**.',
+      description: specDescription('kc-response-stream', [
+          '`<kc-response-stream>` is the framework-agnostic **web component** that reveals text with a typewriter or fade animation — the building block for streamed assistant replies, isolated in **Shadow DOM**.',
           '**When to use:** animating a response as it arrives. Pass a finished string to replay an animation, or an `AsyncIterable<string>` to drive it from a live stream. In SolidJS, use the `ResponseStream` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text` **property** (string or async iterable), tune `mode` (`typewriter` / `fade`) and `speed`, and listen for the `complete` **CustomEvent**.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;

package/src/elements/response-stream.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ResponseStream, type Mode } from '../components/response-stream';
 
 interface Props extends Record<string, unknown> {
@@ -13,17 +13,17 @@ interface Props extends Record<string, unknown> {
   as?: string;
 }
 
-/** Events fired by `<kitn-response-stream>`. */
+/** Events fired by `<kc-response-stream>`. */
 interface Events {
   /** Streaming finished. */
   complete: void;
 }
 
 /**
- * `<kitn-response-stream>` — reveals text with a typewriter or fade animation.
+ * `<kc-response-stream>` — reveals text with a typewriter or fade animation.
  * Text via the `text` property; `mode`/`speed` attributes; emits `complete`.
  */
-defineKitnElement<Props, Events>('kitn-response-stream', {
+defineWebComponent<Props, Events>('kc-response-stream', {
   text: '',
   mode: 'typewriter',
   speed: 20,

package/src/elements/{kitn-source-list.stories.tsx → source-list.stories.tsx}

@@ -1,13 +1,14 @@
 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 {
-      'kitn-source-list': JSX.HTMLAttributes<HTMLElement>;
+      'kc-sources': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -25,19 +26,19 @@ const sampleSources: SourceItem[] = [
   { href: 'https://solidjs.com', title: 'SolidJS', description: 'A reactive UI library.', showFavicon: true },
 ];
 
-/** Render the actual `<kitn-source-list>` custom element with a `sources` property. */
+/** Render the actual `<kc-sources>` custom element with a `sources` property. */
 function SourceListElement() {
   let el: (HTMLElement & { sources?: SourceItem[] }) | undefined;
   onMount(() => {
     if (el) el.sources = sampleSources;
   });
   return (
-    <kitn-source-list ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+    <kc-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 -->
-<kitn-source-list id="srcs" show-favicon></kitn-source-list>
+<kc-sources id="srcs" show-favicon></kc-sources>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -50,19 +51,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-source-list',
+  title: 'Web Components/kc-sources',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-sources'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-source-list>` 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 `<kitn-source>`; in SolidJS, compose `SourceList` + `Source`.',
+      description: specDescription('kc-sources', [
+          '`<kc-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 `<kc-source>`; in SolidJS, compose `SourceList` + `Source`.',
           "**How to use:** register once with `import '@kitnai/chat/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).",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;

package/src/elements/{kitn-source.stories.tsx → source.stories.tsx}

@@ -1,18 +1,19 @@
 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 {
-      'kitn-source': JSX.HTMLAttributes<HTMLElement>;
+      'kc-source': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
 
-/** Render the actual `<kitn-source>` custom element configured by attributes. */
+/** Render the actual `<kc-source>` custom element configured by attributes. */
 function SourceElement(props: {
   href: string;
   label?: string;
@@ -29,36 +30,35 @@ function SourceElement(props: {
     if (props.description) el.setAttribute('description', props.description);
     if (props.showFavicon) el.setAttribute('show-favicon', '');
   });
-  return <kitn-source ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+  return <kc-source ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-source
+<kc-source
   href="https://kitn.dev"
   label="kitn"
   headline="kitn — the kit"
   description="Composable SolidJS + web-component chat UI."
   show-favicon
-></kitn-source>
+></kc-source>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-source',
+  title: 'Web Components/kc-source',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-source'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-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 `<kitn-source-list>`; in SolidJS, compose the `Source` primitives.',
+      description: specDescription('kc-source', [
+          '`<kc-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 `<kc-sources>`; in SolidJS, compose the `Source` primitives.',
           "**How to use:** register once with `import '@kitnai/chat/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.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;

package/src/elements/source.tsx

@@ -1,8 +1,8 @@
 import { For, Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Source, SourceTrigger, SourceContent, SourceList } from '../components/source';
 
-// --- <kitn-source> — a single citation link with hover preview ---
+// --- <kc-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). */
@@ -18,7 +18,7 @@ interface SourceProps extends Record<string, unknown> {
   showFavicon?: boolean;
 }
 
-defineKitnElement<SourceProps>('kitn-source', {
+defineWebComponent<SourceProps>('kc-source', {
   href: '',
   label: undefined,
   headline: '',
@@ -33,7 +33,7 @@ defineKitnElement<SourceProps>('kitn-source', {
   </Show>
 ));
 
-// --- <kitn-source-list> — a wrapped list of citation links ---
+// --- <kc-sources> — a wrapped list of citation links ---
 
 interface SourceItem {
   href: string;
@@ -50,7 +50,7 @@ interface SourceListProps extends Record<string, unknown> {
   showFavicon?: boolean;
 }
 
-defineKitnElement<SourceListProps>('kitn-source-list', {
+defineWebComponent<SourceListProps>('kc-sources', {
   sources: [],
   showFavicon: false,
 }, (props, { flag }) => (