@kitnai/chat 0.6.0 → 0.8.0

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

@@ -1,14 +1,15 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
-import './register'; // side effect: registers <kitn-chat>, <kitn-conversation-list>, <kitn-prompt-input>
+import './register'; // side effect: registers <kc-chat>, <kc-conversations>, <kc-prompt-input>
 import type { ConversationGroup, ConversationSummary } from '../types';
+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-conversation-list': JSX.HTMLAttributes<HTMLElement>;
+      'kc-conversations': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -56,32 +57,41 @@ const sampleConversations: ConversationSummary[] = [
   },
 ];
 
-/** Live demo of the actual `<kitn-conversation-list>` custom element (Shadow DOM and all). */
-function ConversationListElement() {
-  let el:
-    | (HTMLElement & {
-        groups?: ConversationGroup[];
-        conversations?: ConversationSummary[];
-        activeId?: string;
-      })
-    | undefined;
+type ConversationListEl = HTMLElement & {
+  groups?: ConversationGroup[];
+  conversations?: ConversationSummary[];
+  activeId?: string;
+};
+
+/** Live demo of the actual `<kc-conversations>` custom element (Shadow DOM and all). */
+function ConversationListElement(props: { args?: Record<string, unknown> }) {
+  let el: ConversationListEl | undefined;
   onMount(() => {
     if (el) {
+      // Fixed array data
       el.groups = sampleGroups;
       el.conversations = sampleConversations;
       el.activeId = 'c-1';
+      // Scalar args from Controls
+      const args = props.args;
+      if (args) {
+        const scalarNames = ['activeId'];
+        for (const name of scalarNames) {
+          if (name in args) (el as unknown as Record<string, unknown>)[name] = args[name];
+        }
+      }
     }
   });
   return (
-    <kitn-conversation-list
-      ref={(e) => (el = e as HTMLElement)}
+    <kc-conversations
+      ref={(e) => (el = e as ConversationListEl)}
       style={{ display: 'block', width: '300px', height: '560px' }}
     />
   );
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-conversation-list id="list" style="display:block; width:300px; height:100vh;"></kitn-conversation-list>
+<kc-conversations id="list" style="display:block; width:300px; height:100vh;"></kc-conversations>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -131,7 +141,7 @@ function Sidebar() {
     el.activeId = 'c-1';
   });
   return (
-    <kitn-conversation-list
+    <kc-conversations
       ref={el}
       style={{ display: 'block', width: '300px', height: '100vh' }}
       on:select={(e) => console.log('opened:', e.detail.id)}
@@ -142,20 +152,19 @@ function Sidebar() {
 }`;
 
 const meta = {
-  title: 'Web Components/kitn-conversation-list',
+  title: 'Web Components/kc-conversations',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-conversations'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-conversation-list>` is the framework-agnostic **web component** version of the chat sidebar — a searchable, grouped list of conversations with a "new chat" button, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
+      description: specDescription('kc-conversations', [
+          '`<kc-conversations>` is the framework-agnostic **web component** version of the chat sidebar — a searchable, grouped list of conversations with a "new chat" button, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
           '**When to use:** adding a conversation switcher to a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts. If you *are* in SolidJS and want fine-grained control, compose the `ConversationList` primitive instead.',
           '**How to use:** register once with `import \'@kitnai/chat/elements\'`, set rich data as JS **properties** (`el.groups = [...]`, `el.conversations = [...]`, `el.activeId = \'c-1\'`), and listen for **CustomEvents** (`select`, `newchat`, `togglesidebar`) directly on the element.',
           '**Placement:** as a fixed-width side panel next to the chat surface. Give it an explicit width and height (e.g. `width: 300px; height: 100vh`).',
           'See the **Code** tab below for the HTML usage; the *SolidJS* story shows the same element inside a Solid component.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -165,7 +174,10 @@ type Story = StoryObj;
 
 /** The element used the plain-HTML / any-framework way. */
 export const Default: Story = {
-  render: () => <ConversationListElement />,
+  args: {
+    activeId: 'c-1',
+  },
+  render: (args: Record<string, unknown>) => <ConversationListElement args={args} />,
   parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
 };
 
@@ -175,3 +187,4 @@ export const InSolidJS: Story = {
   render: () => <ConversationListElement />,
   parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
 };
+

package/src/elements/conversation-list.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ConversationList } from '../components/conversation-list';
 import type { ConversationGroup, ConversationSummary } from '../types';
 
@@ -14,7 +14,16 @@ interface Props extends Record<string, unknown> {
   activeId?: string;
 }
 
-defineKitnElement<Props>('kitn-conversation-list', {
+interface Events {
+  /** A conversation was selected. */
+  select: { id: string };
+  /** The "New chat" button was clicked. */
+  newchat: Record<string, never>;
+  /** The sidebar toggle was clicked. */
+  togglesidebar: Record<string, never>;
+}
+
+defineWebComponent<Props, Events>('kc-conversations', {
   groups: [],
   conversations: [],
   activeId: undefined,

package/src/elements/css.ts

@@ -2,4 +2,4 @@
 // injected into custom-element shadow roots. Run `npm run build:css` first.
 import compiled from './compiled.css?inline';
 
-export const KITN_CSS: string = compiled;
+export const ELEMENT_CSS: string = compiled;

package/src/elements/define.tsx

@@ -1,6 +1,6 @@
 import { customElement } from 'solid-element';
 import { ChatConfig } from '../primitives/chat-config';
-import { KITN_CSS } from './css';
+import { ELEMENT_CSS } from './css';
 import { createSignal, onCleanup, onMount, Show, type JSX } from 'solid-js';
 
 /**
@@ -17,7 +17,7 @@ function getSharedSheet(): CSSStyleSheet | null {
   try {
     if (typeof CSSStyleSheet === 'undefined') throw new Error('no CSSStyleSheet');
     const sheet = new CSSStyleSheet();
-    sheet.replaceSync(KITN_CSS);
+    sheet.replaceSync(ELEMENT_CSS);
     sharedSheet = sheet;
   } catch {
     sharedSheet = null;
@@ -47,7 +47,7 @@ function createDarkMode(getTheme: () => string | undefined) {
  * `{ eventName: detailType }` — which types `dispatch` so a facade can only fire
  * its declared events with the right `detail` shape.
  */
-export interface KitnElementContext<E = Record<string, unknown>> {
+export interface WebComponentContext<E = Record<string, unknown>> {
   /** The custom-element host node. */
   element: HTMLElement;
   /** Fire a non-bubbling, non-composed CustomEvent off the host. Consumers
@@ -74,13 +74,13 @@ function toAttr(name: string): string {
   return name.replace(/([A-Z])/g, '-$1').toLowerCase();
 }
 
-/** Underlying flag resolution; see `KitnElementContext.flag`. */
+/** Underlying flag resolution; see `WebComponentContext.flag`. */
 function resolveFlag(element: HTMLElement, value: unknown, attribute: string): boolean {
   if (value === true) return true;
   return element.hasAttribute(attribute) && element.getAttribute(attribute) !== 'false';
 }
 
-type FacadeComponent<P, E> = (props: P, ctx: KitnElementContext<E>) => JSX.Element;
+type FacadeComponent<P, E> = (props: P, ctx: WebComponentContext<E>) => JSX.Element;
 
 /**
  * Register a Solid facade as a Shadow-DOM custom element.
@@ -94,7 +94,7 @@ type FacadeComponent<P, E> = (props: P, ctx: KitnElementContext<E>) => JSX.Eleme
  *   the element, so bubbling/composed would only cause consumer collisions).
  * - Idempotent: redefining an already-registered tag is a no-op.
  */
-export function defineKitnElement<P extends Record<string, unknown>, E = Record<string, unknown>>(
+export function defineWebComponent<P extends Record<string, unknown>, E = Record<string, unknown>>(
   tag: string,
   propDefaults: P,
   Facade: FacadeComponent<P, E>,
@@ -111,7 +111,7 @@ export function defineKitnElement<P extends Record<string, unknown>, E = Record<
   for (const key of Object.keys(propDefaults)) {
     if (RESERVED.includes(key)) {
       throw new Error(
-        `defineKitnElement(${tag}): prop "${key}" collides with a global HTMLElement ` +
+        `defineWebComponent(${tag}): prop "${key}" collides with a global HTMLElement ` +
         `attribute and will break the element constructor. Rename it (e.g. ` +
         `"bar-title" → barTitle, a source title → headline).`,
       );
@@ -131,10 +131,10 @@ export function defineKitnElement<P extends Record<string, unknown>, E = Record<
     const dispatch = ((type: string, detail?: unknown) =>
       element.dispatchEvent(
         new CustomEvent(type, { detail, bubbles: false, composed: false }),
-      )) as KitnElementContext<E>['dispatch'];
+      )) as WebComponentContext<E>['dispatch'];
 
     // Reads `props[name]` (reactive) and falls back to attribute presence so
-    // bare boolean attributes behave like normal HTML. See KitnElementContext.
+    // bare boolean attributes behave like normal HTML. See WebComponentContext.
     const flag = (name: string) =>
       resolveFlag(element, (props as Record<string, unknown>)[name], toAttr(name));
 
@@ -153,7 +153,7 @@ export function defineKitnElement<P extends Record<string, unknown>, E = Record<
     return (
       <>
         <Show when={!sheet}>
-          <style>{KITN_CSS}</style>
+          <style>{ELEMENT_CSS}</style>
         </Show>
         {/* display:contents — no layout box; carries the .dark token scope and
             re-roots the inherited `color` to the active mode's foreground, so text