@kitnai/chat 0.8.0 → 0.9.0

package/src/elements/element-meta.json

@@ -53,6 +53,96 @@
         "scalar": true,
         "description": "Accessible title for the preview iframe.",
         "displayType": "undefined | string"
+      },
+      {
+        "name": "maximized",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Reflects the artifact's own maximized view-state (usually driven by the protocol).",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "expandable",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Show the expand-to-fill button (OPT-IN).",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "openInTab",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Show the open-in-new-tab button (OPT-IN).",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "noNav",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Hide back/forward.",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "noReload",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Hide reload.",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "noHome",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Hide home.",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "noPathField",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Hide the address field.",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "noTabs",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Hide the Preview|Code toggle.",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "standalone",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Standalone chrome: rounded corners + border (else square, borderless in-panel).",
+        "default": "false",
+        "displayType": "undefined | false | true"
+      },
+      {
+        "name": "readonlyPath",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Show the address but make it read-only (visible, nav-tracking, non-editable).",
+        "default": "false",
+        "displayType": "undefined | false | true"
       }
     ],
     "events": [
@@ -62,6 +152,12 @@
         "description": "Fired when a file is selected. `detail.path`.",
         "displayDetail": "{ path: string }"
       },
+      {
+        "name": "maximizechange",
+        "detail": "{ maximized: false | true }",
+        "description": "Artifact's own maximize button toggled (consumer-observable; non-bubbling).",
+        "displayDetail": "{ maximized: false | true }"
+      },
       {
         "name": "navigate",
         "detail": "{ url: string }",
@@ -247,6 +343,45 @@
     ],
     "tokens": []
   },
+  {
+    "tag": "kc-cards",
+    "className": "KcCardsElement",
+    "props": [
+      {
+        "name": "cards",
+        "type": "undefined | { type: string; id: string; data: unknown; title?: undefined | string }[]",
+        "optional": true,
+        "scalar": false,
+        "description": "The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`.",
+        "displayType": "undefined | { type: string; id: string; data: unknown; title?: undefined | string }[]"
+      },
+      {
+        "name": "types",
+        "type": "undefined | Record<string, string>",
+        "optional": true,
+        "scalar": false,
+        "description": "Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type.",
+        "displayType": "undefined | Record<string, string>"
+      },
+      {
+        "name": "policy",
+        "type": "undefined | { onSubmitData?: undefined | (cardId: string, data: unknown) => void; onAction?: undefined | (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: undefined | (text: string, opts: { mode: \"compose\" | \"send\"; context?: unknown; }) => void; onOpen?: undefined | (url: string, target: \"tab\" | \"artifact\") => void; onState?: undefined | (cardId: string, patch: unknown) => void; onDismiss?: undefined | (cardId: string) => void; onError?: undefined | (cardId: string, message: string) => void; maxSendPromptMode?: undefined | \"compose\" | \"send\" }",
+        "optional": true,
+        "scalar": false,
+        "description": "Optional CardPolicy handling child events. Property: `el.policy`.",
+        "displayType": "undefined | { onSubmitData?: undefined | (cardId: string, data: unknown) => void; onAction?: undefined | (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: undefined | (text: string, opts: { mode: \"compose\" | \"send\"; context?: unknown; }) => void; onOpen?: undefined | (url: string, target: \"tab\" | \"artifact\") => void; onState?: undefined | (cardId: string, patch: unknown) => void; onDismiss?: undefined | (cardId: string) => void; onError?: undefined | (cardId: string, message: string) => void; maxSendPromptMode?: undefined | \"compose\" | \"send\" }"
+      }
+    ],
+    "events": [],
+    "composedFrom": [
+      {
+        "name": "CardFallback",
+        "group": "Components",
+        "storyId": "components-cardfallback--docs"
+      }
+    ],
+    "tokens": []
+  },
   {
     "tag": "kc-chain-of-thought",
     "className": "KcChainOfThoughtElement",
@@ -1693,6 +1828,15 @@
         "description": "Layout axis: `horizontal` (row, default) or `vertical` (column).",
         "default": "'horizontal'",
         "displayType": "undefined | \"horizontal\" | \"vertical\""
+      },
+      {
+        "name": "maximizedIndex",
+        "type": "undefined | null | number",
+        "optional": true,
+        "scalar": false,
+        "description": "Which item index is maximized (null = none). Declarative source of truth.",
+        "default": "null",
+        "displayType": "undefined | null | number"
       }
     ],
     "events": [
@@ -1701,6 +1845,12 @@
         "detail": "{ sizes: number[] }",
         "description": "Fired on drag-end / keyboard resize / visibility change. `detail.sizes` = panel sizes in percent.",
         "displayDetail": "{ sizes: number[] }"
+      },
+      {
+        "name": "maximizechange",
+        "detail": "{ maximized: false | true; index: null | number }",
+        "description": "Observe layout maximize state.",
+        "displayDetail": "{ maximized: false | true; index: null | number }"
       }
     ],
     "composedFrom": [
@@ -1765,6 +1915,12 @@
         "detail": "unknown",
         "description": "",
         "displayDetail": "unknown"
+      },
+      {
+        "name": "maximizechange",
+        "detail": "unknown",
+        "description": "",
+        "displayDetail": "unknown"
       }
     ],
     "composedFrom": [

package/src/elements/element-types.d.ts

@@ -23,6 +23,26 @@ export interface KcArtifactElement extends HTMLElement {
   sandbox?: string;
   /** Accessible title for the preview iframe. */
   iframeTitle?: string;
+  /** Reflects the artifact's own maximized view-state (usually driven by the protocol). */
+  maximized?: boolean;
+  /** Show the expand-to-fill button (OPT-IN). */
+  expandable?: boolean;
+  /** Show the open-in-new-tab button (OPT-IN). */
+  openInTab?: boolean;
+  /** Hide back/forward. */
+  noNav?: boolean;
+  /** Hide reload. */
+  noReload?: boolean;
+  /** Hide home. */
+  noHome?: boolean;
+  /** Hide the address field. */
+  noPathField?: boolean;
+  /** Hide the Preview|Code toggle. */
+  noTabs?: boolean;
+  /** Standalone chrome: rounded corners + border (else square, borderless in-panel). */
+  standalone?: boolean;
+  /** Show the address but make it read-only (visible, nav-tracking, non-editable). */
+  readonlyPath?: boolean;
 }
 
 export interface KcAttachmentsElement extends HTMLElement {
@@ -55,6 +75,17 @@ export interface KcCardElement extends HTMLElement {
   dense?: boolean;
 }
 
+export interface KcCardsElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. */
+  cards?: { type: string; id: string; data: unknown; title?: string }[];
+  /** Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  types?: Record<string, string>;
+  /** Optional CardPolicy handling child events. Property: `el.policy`. */
+  policy?: { onSubmitData?: (cardId: string, data: unknown) => void; onAction?: (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: (text: string, opts: { mode: "compose" | "send"; context?: unknown; }) => void; onOpen?: (url: string, target: "tab" | "artifact") => void; onState?: (cardId: string, patch: unknown) => void; onDismiss?: (cardId: string) => void; onError?: (cardId: string, message: string) => void; maxSendPromptMode?: "compose" | "send" };
+}
+
 export interface KcChainOfThoughtElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
@@ -347,6 +378,8 @@ export interface KcResizableElement extends HTMLElement {
   theme?: 'light' | 'dark' | 'auto';
   /** Layout axis: `horizontal` (row, default) or `vertical` (column). */
   orientation?: "horizontal" | "vertical";
+  /** Which item index is maximized (null = none). Declarative source of truth. */
+  maximizedIndex?: null | number;
 }
 
 export interface KcResizableItemElement extends HTMLElement {
@@ -531,6 +564,7 @@ declare global {
     'kc-artifact': KcArtifactElement;
     'kc-attachments': KcAttachmentsElement;
     'kc-card': KcCardElement;
+    'kc-cards': KcCardsElement;
     'kc-chain-of-thought': KcChainOfThoughtElement;
     'kc-chat': KcChatElement;
     'kc-checkpoint': KcCheckpointElement;

package/src/elements/register.ts

@@ -45,6 +45,7 @@ import './link-card';
 import './embed';
 import './confirm-card';
 import './task-list-card';
+import './cards';
 
 export type { ChatMessage, ChatMessageAction } from './chat-types';
 export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';

package/src/elements/resizable.d.ts

@@ -0,0 +1,27 @@
+// src/elements/resizable.d.ts
+// Hand-authored ambient types for <kc-resizable>'s maximize capability. The
+// generated element-types.d.ts emits prop/event interfaces only (not methods),
+// so the imperative host API + the cross-element protocol events live here.
+// NOT regenerated by `npm run build`.
+import type { KcMaximizeIntentDetail, KcMaximizeStateDetail } from './resizable';
+
+declare global {
+  interface KcResizableElement extends HTMLElement {
+    /** Which item index is maximized (null = none). Setting it maximizes that
+     *  item (or restores when set to null) — the declarative source of truth. */
+    maximizedIndex: number | null;
+    /** Imperatively maximize the item at `index` (thin wrapper over maximizedIndex). */
+    maximize(index: number): void;
+    /** Imperatively restore from the maximized layout. */
+    restore(): void;
+  }
+  interface HTMLElementTagNameMap {
+    'kc-resizable': KcResizableElement;
+  }
+  interface HTMLElementEventMap {
+    'kc-maximize-intent': CustomEvent<KcMaximizeIntentDetail>;
+    'kc-maximize-state': CustomEvent<KcMaximizeStateDetail>;
+  }
+}
+
+export {};

package/src/elements/resizable.stories.tsx

@@ -1,7 +1,10 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
-import { createSignal, type JSX } from 'solid-js';
+import { createSignal, onMount, type JSX } from 'solid-js';
 import './register'; // side effect: registers the custom elements
 import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import { Resizable, ResizablePanel } from '../ui/resizable';
+import type { ArtifactFile } from '../components/artifact';
+import { Artifact } from '../components/artifact';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
@@ -12,10 +15,23 @@ declare module 'solid-js' {
       'kc-resizable-item': JSX.HTMLAttributes<HTMLElement> & {
         size?: string; min?: string; max?: string; locked?: boolean | string; hidden?: boolean | string;
       };
+      // `kc-artifact` JSX type is augmented (with the full attr set) in
+      // artifact.stories.tsx — declaring it again here with a different shape
+      // would trip TS2717 (module-augmentation merges must match). Reuse that one.
     }
   }
 }
 
+// Fixture base URL (served by Storybook staticDirs from examples/artifact-fixtures).
+const BASE = '/artifact-fixtures';
+
+const ARTIFACT_FILES: ArtifactFile[] = [
+  { path: 'index.html', url: `${BASE}/index.html`, type: 'html', language: 'html',
+    code: `<!DOCTYPE html><html lang="en"><head><title>Preview</title></head><body><h1>Starboard</h1></body></html>` },
+  { path: 'about.html', url: `${BASE}/about.html`, type: 'html', language: 'html',
+    code: `<!DOCTYPE html><html lang="en"><head><title>About</title></head><body><h1>About</h1></body></html>` },
+];
+
 /** A labelled placeholder pane so the layout is visible in stories. */
 function Pane(props: { label: string; tone?: 'muted' | 'plain' }) {
   return (
@@ -198,3 +214,212 @@ export const HiddenToggle: Story = {
     );
   },
 };
+
+const EXPAND_TO_FILL_SNIPPET = `<!-- The artifact's "Expand" button (opt-in: expandable) fires a bubbling
+     kc-maximize-intent event. The nearest enclosing <kc-resizable> catches it
+     automatically and hides siblings so the preview panel fills the container.
+     No wiring needed between the two elements — the protocol is zero-config. -->
+
+<kc-resizable orientation="horizontal" style="display:block;height:480px">
+  <kc-resizable-item size="20%" min="120px"> …list… </kc-resizable-item>
+  <kc-resizable-item> …chat… </kc-resizable-item>
+  <kc-resizable-item size="35%" min="200px">
+    <!-- expandable opt-in: adds the Expand/Collapse button -->
+    <kc-artifact
+      src="…/index.html"
+      expandable
+    ></kc-artifact>
+  </kc-resizable-item>
+</kc-resizable>
+
+<script type="module">
+  import '@kitnai/chat/elements';
+
+  // Optional: observe the layout events.
+  document.querySelector('kc-resizable')
+    .addEventListener('change', (e) => console.log('change', e.detail.sizes));
+  document.querySelector('kc-resizable')
+    .addEventListener('maximizechange', (e) => console.log('maximizechange', e.detail));
+  document.querySelector('kc-artifact')
+    .addEventListener('maximizechange', (e) => console.log('artifact maximizechange', e.detail));
+</script>
+
+<!-- Cross-element protocol (hand-authored; not generated):
+  • kc-maximize-intent  — CustomEvent, bubbles:true, composed:true
+      Fired by <kc-artifact> when the Expand/Collapse button is clicked.
+      detail: { requested: boolean }  (true = maximize, false = restore)
+  • kc-maximize-state   — CustomEvent, bubbles:false, composed:true
+      Dispatched by <kc-resizable> back DOWN onto the maximized <kc-resizable-item>
+      (on maximize) or the group host + the formerly-maximized item (on restore)
+      so the artifact can reconcile its button label.
+      detail: { maximized: boolean }
+  These protocol events are NOT listed in the generated web-components.md because
+  they are cross-element — the generator only documents per-element dispatch events. -->`;
+
+/**
+ * **Expand to fill** — the headline integration: the artifact's expand button
+ * fills the preview panel to the full container width. No wiring between the
+ * two elements is needed — clicking **Expand** fires a `kc-maximize-intent` event
+ * that bubbles up to the nearest enclosing `<kc-resizable>`, which hides siblings
+ * and lets the preview panel fill. **Collapse** (or **Escape**) restores the
+ * original layout.
+ *
+ * **Cross-element protocol (hand-authored docs):**
+ * - `kc-maximize-intent` — `bubbles:true, composed:true`; fired by `<kc-artifact>`
+ *   when Expand/Collapse is toggled. `detail: { requested: boolean }`.
+ * - `kc-maximize-state` — `bubbles:false, composed:true`; dispatched by
+ *   `<kc-resizable>` back down to the affected `<kc-resizable-item>` so the
+ *   artifact can reconcile its button. `detail: { maximized: boolean }`.
+ *
+ * These protocol events are NOT in the generated `web-components.md`
+ * (the generator only documents per-element `dispatch` events — resolved decision #1).
+ */
+export const ExpandToFill: Story = {
+  name: 'Expand to fill',
+  render: () => {
+    const [log, setLog] = createSignal<string[]>([]);
+    let artifactEl: HTMLElement & { files?: ArtifactFile[] };
+    let resizableEl: HTMLElement;
+    onMount(() => {
+      if (artifactEl) artifactEl.files = ARTIFACT_FILES;
+      if (resizableEl) {
+        resizableEl.addEventListener('change', (e: Event) =>
+          setLog((l) => [`change → ${JSON.stringify((e as CustomEvent).detail.sizes)}`, ...l].slice(0, 6)),
+        );
+        resizableEl.addEventListener('maximizechange', (e: Event) =>
+          setLog((l) => [`maximizechange → ${JSON.stringify((e as CustomEvent).detail)}`, ...l].slice(0, 6)),
+        );
+      }
+      if (artifactEl) {
+        artifactEl.addEventListener('maximizechange', (e: Event) =>
+          setLog((l) => [`artifact maximizechange → ${JSON.stringify((e as CustomEvent).detail)}`, ...l].slice(0, 6)),
+        );
+      }
+    });
+    return (
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <div
+          style={{
+            height: '480px',
+            width: '100%',
+            'max-width': '900px',
+            border: '1px solid var(--color-border, #e4e4e7)',
+            'border-radius': '8px',
+            overflow: 'hidden',
+          }}
+        >
+          <kc-resizable
+            ref={(e) => (resizableEl = e as HTMLElement)}
+            orientation="horizontal"
+          >
+            <kc-resizable-item size="20%" min="120px">
+              <Pane label="List" />
+            </kc-resizable-item>
+            <kc-resizable-item min="140px">
+              <Pane label="Chat" tone="plain" />
+            </kc-resizable-item>
+            <kc-resizable-item size="35%" min="200px">
+              <kc-artifact
+                ref={(e) => (artifactEl = e as HTMLElement & { files?: ArtifactFile[] })}
+                src={`${BASE}/index.html`}
+                iframe-title="Starboard artifact preview"
+                expandable
+              />
+            </kc-resizable-item>
+          </kc-resizable>
+        </div>
+        <pre
+          style={{
+            'font-size': '12px',
+            'max-width': '900px',
+            padding: '10px 12px',
+            'border-radius': '8px',
+            background: 'var(--color-muted, #f4f4f5)',
+            color: 'var(--color-muted-foreground, #71717a)',
+            'min-height': '72px',
+            margin: '0',
+          }}
+        >
+          {log().length ? log().join('\n') : '(click the ⤢ Expand button in the preview toolbar…)'}
+        </pre>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: EXPAND_TO_FILL_SNIPPET, language: 'html' } } },
+};
+
+const SOLID_PARITY_SNIPPET = `// SolidJS — Artifact inside Resizable with maximizedIndex/onMaximizeChange.
+// No web components needed; works in a pure-Solid app.
+import { createSignal } from 'solid-js';
+import { Artifact } from '@kitnai/chat/components';
+import { Resizable, ResizablePanel } from '@kitnai/chat/ui';
+
+function App() {
+  const [maximizedIndex, setMaximizedIndex] = createSignal<number | null>(null);
+  return (
+    <Resizable
+      maximizedIndex={maximizedIndex()}
+      onMaximizeChange={setMaximizedIndex}
+      style="height:480px"
+    >
+      <ResizablePanel defaultSize="20%" minSize="120px">…list…</ResizablePanel>
+      <ResizablePanel minSize="140px">…chat…</ResizablePanel>
+      <ResizablePanel defaultSize="35%" minSize="200px">
+        <Artifact
+          src="…"
+          expandable
+          maximized={maximizedIndex() === 2}
+          onMaximizeChange={(m) => setMaximizedIndex(m ? 2 : null)}
+        />
+      </ResizablePanel>
+    </Resizable>
+  );
+}`;
+
+/**
+ * **SolidJS parity** — the same `list | chat | artifact` layout using the Solid
+ * `Resizable` convenience and the `Artifact` component directly (no web components).
+ * `maximizedIndex` / `onMaximizeChange` on `Resizable` mirror the web-component
+ * protocol at the Solid level. Wire `Artifact`'s `onMaximizeChange` to set the
+ * index and pass `maximized` back down to drive the button.
+ */
+export const SolidParity: Story = {
+  name: 'SolidJS parity (Resizable + Artifact)',
+  render: () => {
+    const [maximizedIndex, setMaximizedIndex] = createSignal<number | null>(null);
+    return (
+      <div
+        style={{
+          height: '480px',
+          width: '100%',
+          'max-width': '900px',
+          border: '1px solid var(--color-border, #e4e4e7)',
+          'border-radius': '8px',
+          overflow: 'hidden',
+        }}
+      >
+        <Resizable
+          maximizedIndex={maximizedIndex()}
+          onMaximizeChange={setMaximizedIndex}
+        >
+          <ResizablePanel defaultSize="20%" minSize="120px">
+            <Pane label="List" />
+          </ResizablePanel>
+          <ResizablePanel minSize="140px">
+            <Pane label="Chat" tone="plain" />
+          </ResizablePanel>
+          <ResizablePanel defaultSize="35%" minSize="200px">
+            <Artifact
+              src={`${BASE}/index.html`}
+              iframeTitle="Starboard artifact preview"
+              expandable
+              maximized={maximizedIndex() === 2}
+              onMaximizeChange={(m) => setMaximizedIndex(m ? 2 : null)}
+            />
+          </ResizablePanel>
+        </Resizable>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: SOLID_PARITY_SNIPPET, language: 'tsx' } } },
+};