@kitnai/chat 0.8.0 → 0.9.0

package/src/elements/artifact.stories.tsx

@@ -16,6 +16,16 @@ declare module 'solid-js' {
         sandbox?: string;
         'iframe-title'?: string;
         ref?: (el: HTMLElement) => void;
+        // toolbar composition flags (all boolean attrs)
+        expandable?: boolean | string;
+        'open-in-tab'?: boolean | string;
+        'no-nav'?: boolean | string;
+        'no-reload'?: boolean | string;
+        'no-home'?: boolean | string;
+        'no-path-field'?: boolean | string;
+        'no-tabs'?: boolean | string;
+        standalone?: boolean | string;
+        'readonly-path'?: boolean | string;
       };
     }
   }
@@ -289,3 +299,207 @@ export const WithEvents: Story = {
     );
   },
 };
+
+const CONFIGURABLE_TOOLBAR_SNIPPET = `<!-- All toolbar affordances are individually opt-in/out via attributes. -->
+
+<!-- The five default-shown items each have a "no-*" flag to hide them: -->
+<kc-artifact
+  src="…"
+  no-nav
+  no-reload
+  no-home
+></kc-artifact>
+
+<!-- Two new buttons are OPT-IN (hidden by default): -->
+<kc-artifact
+  src="…"
+  expandable
+  open-in-tab
+></kc-artifact>
+
+<!-- Standalone chrome: rounded corners + border (default is square/borderless in-panel): -->
+<kc-artifact src="…" standalone></kc-artifact>
+
+<!-- Read-only path: visible, nav-tracking, non-editable: -->
+<kc-artifact src="…" readonly-path></kc-artifact>`;
+
+/**
+ * Every toolbar affordance is individually configurable.
+ *
+ * **Default-shown (`no-*` flags hide):** back/forward (`no-nav`), reload (`no-reload`),
+ * home (`no-home`), address field (`no-path-field`), Preview|Code toggle (`no-tabs`).
+ *
+ * **Opt-in (hidden by default; positive attr enables):** expand-to-fill (`expandable`),
+ * open-in-new-tab (`open-in-tab`).
+ *
+ * **Chrome:** `standalone` adds rounded corners + border (default = square/borderless
+ * for in-panel use). `readonly-path` makes the address field visible but non-editable.
+ *
+ * When ALL affordances are hidden the toolbar bar is omitted entirely (zero height).
+ */
+export const ConfigurableToolbar: Story = {
+  name: 'Configurable toolbar',
+  render: (args: {
+    expandable?: boolean;
+    openInTab?: boolean;
+    noNav?: boolean;
+    noReload?: boolean;
+    noHome?: boolean;
+    noPathField?: boolean;
+    noTabs?: boolean;
+    standalone?: boolean;
+    readonlyPath?: boolean;
+  }) => {
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => { if (el) el.files = FILES; });
+    return (
+      <Frame>
+        <kc-artifact
+          ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+          src={`${BASE}/index.html`}
+          iframe-title="Starboard artifact preview"
+          expandable={args.expandable || undefined}
+          open-in-tab={args.openInTab || undefined}
+          no-nav={args.noNav || undefined}
+          no-reload={args.noReload || undefined}
+          no-home={args.noHome || undefined}
+          no-path-field={args.noPathField || undefined}
+          no-tabs={args.noTabs || undefined}
+          standalone={args.standalone || undefined}
+          readonly-path={args.readonlyPath || undefined}
+        />
+      </Frame>
+    );
+  },
+  args: {
+    expandable: false,
+    openInTab: false,
+    noNav: false,
+    noReload: false,
+    noHome: false,
+    noPathField: false,
+    noTabs: false,
+    standalone: false,
+    readonlyPath: false,
+  },
+  argTypes: {
+    expandable: { control: 'boolean', description: 'Show the expand-to-fill button (opt-in).' },
+    openInTab: { control: 'boolean', name: 'open-in-tab', description: 'Show the open-in-new-tab button (opt-in).' },
+    noNav: { control: 'boolean', name: 'no-nav', description: 'Hide the back/forward buttons.' },
+    noReload: { control: 'boolean', name: 'no-reload', description: 'Hide the reload button.' },
+    noHome: { control: 'boolean', name: 'no-home', description: 'Hide the home button.' },
+    noPathField: { control: 'boolean', name: 'no-path-field', description: 'Hide the address field.' },
+    noTabs: { control: 'boolean', name: 'no-tabs', description: 'Hide the Preview|Code toggle.' },
+    standalone: { control: 'boolean', description: 'Standalone chrome (rounded + border).' },
+    readonlyPath: { control: 'boolean', name: 'readonly-path', description: 'Address field is visible but non-editable.' },
+  },
+  parameters: { docs: { source: { code: CONFIGURABLE_TOOLBAR_SNIPPET, language: 'html' } } },
+};
+
+const MINIMAL_SNIPPET = `<!-- Minimal: only the preview iframe, no toolbar at all. -->
+<kc-artifact
+  src="…"
+  no-nav
+  no-reload
+  no-home
+  no-path-field
+  no-tabs
+></kc-artifact>`;
+
+/**
+ * All five default-shown toolbar affordances suppressed — the toolbar bar
+ * disappears entirely (zero height), leaving just the preview iframe.
+ * Useful for an embedded, chrome-free artifact tile.
+ */
+export const MinimalPreview: Story = {
+  name: 'Minimal (preview-only)',
+  render: () => (
+    <Frame>
+      <kc-artifact
+        src={`${BASE}/index.html`}
+        iframe-title="Starboard artifact preview"
+        no-nav
+        no-reload
+        no-home
+        no-path-field
+        no-tabs
+      />
+    </Frame>
+  ),
+  parameters: { docs: { source: { code: MINIMAL_SNIPPET, language: 'html' } } },
+};
+
+const OPEN_IN_TAB_SNIPPET = `<!-- open-in-tab: adds a button that opens the current URL in a new tab.
+     The button is disabled while the src is blank. -->
+<kc-artifact
+  src="https://your-backend.example/artifacts/abc/index.html"
+  open-in-tab
+></kc-artifact>`;
+
+/**
+ * The **open-in-tab** button (opt-in via `open-in-tab`) opens the current
+ * preview URL in a new browser tab (`window.open`, `noopener,noreferrer`).
+ * It is disabled while the URL is empty / `about:blank` and follows the live
+ * navigation state — clicking it after the user has navigated to a sub-page
+ * opens that sub-page, not the original `src`.
+ */
+export const OpenInTab: Story = {
+  name: 'Open in new tab',
+  render: () => {
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => { if (el) el.files = FILES; });
+    return (
+      <Frame>
+        <kc-artifact
+          ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+          src={`${BASE}/index.html`}
+          iframe-title="Starboard artifact preview"
+          open-in-tab
+        />
+      </Frame>
+    );
+  },
+  parameters: { docs: { source: { code: OPEN_IN_TAB_SNIPPET, language: 'html' } } },
+};
+
+const STANDALONE_SNIPPET = `<!-- standalone: adds rounded corners + a border (like a card).
+     Suppresses the expand button even when expandable is set.
+     Use for an artifact rendered outside any panel layout. -->
+<kc-artifact
+  src="…"
+  standalone
+  style="display:block;height:520px"
+></kc-artifact>`;
+
+/**
+ * `standalone` adds rounded corners and a border — the "card" chrome for an
+ * artifact rendered outside any panel layout (e.g. as a modal or inline tile).
+ * In the default in-panel mode the element is square and borderless so it fits
+ * flush inside a `<kc-resizable>` panel without double-borders.
+ *
+ * `standalone` also suppresses the expand button (there is no enclosing resizable
+ * to maximize into) regardless of `expandable`.
+ *
+ * `readonly-path` keeps the address field visible and navigation-tracking but
+ * non-editable — useful when the consumer drives the URL programmatically.
+ */
+export const StandaloneChrome: Story = {
+  name: 'Standalone chrome + read-only path',
+  render: () => {
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => { if (el) el.files = FILES; });
+    return (
+      <div style={{ padding: '16px', 'max-width': '900px' }}>
+        <kc-artifact
+          ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+          src={`${BASE}/index.html`}
+          iframe-title="Starboard artifact preview"
+          standalone
+          readonly-path
+          style={{ display: 'block', height: '480px' }}
+        />
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: STANDALONE_SNIPPET, language: 'html' } } },
+};

package/src/elements/artifact.tsx

@@ -1,3 +1,4 @@
+import { createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import { Artifact, type ArtifactFile, type ArtifactTab } from '../components/artifact';
 
@@ -14,6 +15,26 @@ interface Props extends Record<string, unknown> {
   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;
 }
 
 interface Events extends Record<string, unknown> {
@@ -23,6 +44,8 @@ interface Events extends Record<string, unknown> {
   tabchange: { tab: ArtifactTab };
   /** Fired when a file is selected. `detail.path`. */
   fileselect: { path: string };
+  /** Artifact's own maximize button toggled (consumer-observable; non-bubbling). */
+  maximizechange: { maximized: boolean };
 }
 
 /**
@@ -40,33 +63,75 @@ defineWebComponent<Props, Events>('kc-artifact', {
   activeFile: undefined,
   sandbox: 'allow-scripts allow-forms',
   iframeTitle: undefined,
-}, (props, { dispatch }) => (
-  <>
-    {/* The artifact fills its container; the internal column flex (toolbar
-        flex-shrink:0, body flex:1/min-height:0) is in the Solid component. Wrap
-        in a definite `1fr` grid cell (NOT :host) so the facade's sibling
-        portal-mount div can't steal a grid track — see resizable.tsx. */}
-    <style>{':host{display:block;height:100%;min-height:0}'}</style>
-    <div
-      style={{
-        display: 'grid',
-        'grid-template-rows': 'minmax(0, 1fr)',
-        'grid-template-columns': 'minmax(0, 1fr)',
-        height: '100%',
-        'min-height': '0',
-      }}
-    >
-      <Artifact
-        src={props.src}
-        files={props.files}
-        tab={props.tab}
-        activeFile={props.activeFile}
-        sandbox={props.sandbox}
-        iframeTitle={props.iframeTitle}
-        onNavigate={(url) => dispatch('navigate', { url })}
-        onTabChange={(tab) => dispatch('tabchange', { tab })}
-        onFileSelect={(path) => dispatch('fileselect', { path })}
-      />
-    </div>
-  </>
-));
+  maximized: false,
+  expandable: false,
+  openInTab: false,
+  noNav: false,
+  noReload: false,
+  noHome: false,
+  noPathField: false,
+  noTabs: false,
+  standalone: false,
+  readonlyPath: false,
+}, (props, { element, dispatch, flag }) => {
+  const [maximized, setMaximized] = createSignal(flag('maximized'));
+
+  const onMaximizeChange = (next: boolean) => {
+    setMaximized(next);
+    // 1) The PROTOCOL intent — raw, bubbling + composed (NOT via dispatch()).
+    element.dispatchEvent(
+      new CustomEvent('kc-maximize-intent', { detail: { requested: next }, bubbles: true, composed: true }),
+    );
+    // 2) The PUBLIC observable event (non-bubbling, on the host).
+    dispatch('maximizechange', { maximized: next });
+  };
+
+  // Authoritative reconcile: the resizable tells us the effective state.
+  onMount(() => {
+    const onState = (e: Event) => setMaximized((e as CustomEvent<{ maximized: boolean }>).detail.maximized);
+    element.addEventListener('kc-maximize-state', onState);
+    onCleanup(() => element.removeEventListener('kc-maximize-state', onState));
+  });
+
+  return (
+    <>
+      {/* The artifact fills its container; the internal column flex (toolbar
+          flex-shrink:0, body flex:1/min-height:0) is in the Solid component. Wrap
+          in a definite `1fr` grid cell (NOT :host) so the facade's sibling
+          portal-mount div can't steal a grid track — see resizable.tsx. */}
+      <style>{':host{display:block;height:100%;min-height:0}'}</style>
+      <div
+        style={{
+          display: 'grid',
+          'grid-template-rows': 'minmax(0, 1fr)',
+          'grid-template-columns': 'minmax(0, 1fr)',
+          height: '100%',
+          'min-height': '0',
+        }}
+      >
+        <Artifact
+          src={props.src}
+          files={props.files}
+          tab={props.tab}
+          activeFile={props.activeFile}
+          sandbox={props.sandbox}
+          iframeTitle={props.iframeTitle}
+          maximized={maximized()}
+          expandable={flag('expandable')}
+          openInTab={flag('openInTab')}
+          showNav={!flag('noNav')}
+          showReload={!flag('noReload')}
+          showHome={!flag('noHome')}
+          showPathField={!flag('noPathField')}
+          showTabs={!flag('noTabs')}
+          standalone={flag('standalone')}
+          readonlyPath={flag('readonlyPath')}
+          onMaximizeChange={onMaximizeChange}
+          onNavigate={(url) => dispatch('navigate', { url })}
+          onTabChange={(tab) => dispatch('tabchange', { tab })}
+          onFileSelect={(path) => dispatch('fileselect', { path })}
+        />
+      </div>
+    </>
+  );
+});

package/src/elements/cards.stories.tsx

@@ -0,0 +1,54 @@
+// src/elements/cards.stories.tsx
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount } from 'solid-js';
+import './register'; // registers all kc-* incl. kc-cards
+import type { CardEnvelope, CardEvent } from '../primitives/card-contract';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements { 'kc-cards': JSX.HTMLAttributes<HTMLElement>; }
+  }
+}
+
+const CARDS: CardEnvelope[] = [
+  { type: 'confirm', id: 'deploy', title: 'Deploy to production?',
+    data: { body: 'Apply 3 migrations and deploy?', tone: 'warning',
+      actions: [{ id: 'go', label: 'Deploy', style: 'primary', default: true }, { id: 'no', label: 'Cancel' }] } },
+  { type: 'task-list', id: 'plan', title: 'Pick the steps',
+    data: { tasks: [{ id: 'a', label: 'Run tests', checked: true }, { id: 'b', label: 'Tag release' }], confirmLabel: 'Run selected' } },
+  { type: 'link', id: 'doc', data: { url: 'https://kitn.dev', title: 'kitn.dev', description: 'Generative UI cards', domain: 'kitn.dev' } },
+];
+
+/** A host renders a stream of envelopes via <kc-cards> and handles events via `.policy`. */
+function Demo() {
+  let el: HTMLElement | undefined;
+  const [log, setLog] = createSignal<string[]>([]);
+  onMount(() => {
+    if (!el) return;
+    (el as unknown as { cards: CardEnvelope[] }).cards = CARDS;
+    (el as unknown as { policy: unknown }).policy = {
+      onAction: (id: string, action: string) => setLog((l) => [`action: ${id} → ${action}`, ...l]),
+      onSubmitData: (id: string, data: unknown) => setLog((l) => [`submit-data: ${id} → ${JSON.stringify(data)}`, ...l]),
+      onOpen: (url: string) => setLog((l) => [`open: ${url}`, ...l]),
+      onError: (id: string, msg: string) => setLog((l) => [`error: ${id} → ${msg}`, ...l]),
+    };
+  });
+  return (
+    <div style={{ display: 'grid', 'grid-template-columns': '1fr 18rem', gap: '1rem', padding: '1rem' }}>
+      <kc-cards ref={(e) => (el = e as HTMLElement)} />
+      <pre style={{ 'font-size': '12px', background: '#f4f4f5', padding: '8px', 'border-radius': '6px', 'min-height': '6rem' }}>
+        {log().join('\n') || 'events appear here…'}
+      </pre>
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Generative UI/SDK/kc-cards',
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta;
+export default meta;
+type Story = StoryObj;
+
+export const CardStream: Story = { render: () => <Demo /> };

package/src/elements/cards.tsx

@@ -0,0 +1,91 @@
+// src/elements/cards.tsx
+// <kc-cards> — the web-component list dispatcher. Renders one child kc-* element per
+// envelope (by type→tag), propagates its theme, and routes children's bubbling
+// `kc-card` events through an optional `policy`. The raw events keep bubbling past
+// <kc-cards> (composed) so document-level listeners still work. Unknown types render
+// the Solid CardFallback inline and emit a contract `error`.
+import { For, Show, createEffect, onCleanup, onMount, type JSX } from 'solid-js';
+import { Dynamic } from 'solid-js/web';
+import { defineWebComponent } from './define';
+import type { CardEnvelope, CardEvent, CardPolicy } from '../primitives/card-contract';
+import { CARD_EVENT_NAME, emitCardEvent, routeCardEvent } from '../primitives/card-routing';
+import { mergeCardTags } from '../primitives/card-registry';
+import { CardFallback } from '../components/card-fallback';
+// Register the built-in child card elements so that importing <kc-cards> is self-contained.
+import './form';
+import './confirm-card';
+import './task-list-card';
+import './link-card';
+import './embed';
+
+interface Props extends Record<string, unknown> {
+  /** The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. */
+  cards?: CardEnvelope[];
+  /** 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?: CardPolicy;
+}
+
+/** A single resolved child: a known kc-* tag (props set imperatively) or the fallback. */
+function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string; emit: (e: CardEvent) => void }): JSX.Element {
+  let ref: HTMLElement | undefined;
+  // Set object/string props as DOM properties on the custom element (reactive).
+  createEffect(() => {
+    if (!ref) return;
+    (ref as unknown as { data: unknown }).data = props.envelope.data;
+    (ref as unknown as { cardId: string }).cardId = props.envelope.id;
+    if (props.envelope.title != null) (ref as unknown as { heading: string }).heading = props.envelope.title;
+    ref.setAttribute('theme', props.theme);
+  });
+  // Hoist the unknown-type error emit to onMount to avoid side-effect-in-JSX lint issue
+  // and to ensure exactly one error fires.
+  onMount(() => {
+    if (!props.tag) {
+      props.emit({ kind: 'error', cardId: props.envelope.id, message: `Unsupported card type: ${props.envelope.type}` });
+    }
+  });
+  return (
+    <Show
+      when={props.tag}
+      fallback={<CardFallback type={props.envelope.type} cardId={props.envelope.id} />}
+    >
+      {(tag) => <Dynamic component={tag()} ref={ref} />}
+    </Show>
+  );
+}
+
+defineWebComponent<Props>(
+  'kc-cards',
+  { cards: undefined, types: undefined, policy: undefined },
+  (props, { element }) => {
+    // Route children's bubbling kc-card events through the policy. Attached to the host
+    // element so composed events from each child's shadow root are caught as they bubble.
+    // The handler reads `props.policy` at EVENT time (not mount time) so setting
+    // `el.policy` after the element is in the DOM — the standard host pattern — works.
+    onMount(() => {
+      const handler = (e: Event) =>
+        routeCardEvent(props.policy ?? {}, (e as CustomEvent<CardEvent>).detail);
+      element.addEventListener(CARD_EVENT_NAME, handler as EventListener);
+      onCleanup(() => element.removeEventListener(CARD_EVENT_NAME, handler as EventListener));
+    });
+    const theme = () => (element.getAttribute('theme') ?? 'auto');
+    const tags = () => mergeCardTags(props.types);
+    return (
+      <div class="flex flex-col gap-3">
+        <For each={props.cards ?? []}>
+          {(env) => (
+            <CardSlot
+              envelope={env}
+              tag={tags()[env.type]}
+              theme={theme()}
+              emit={(e) => emitCardEvent(element, e)}
+            />
+          )}
+        </For>
+      </div>
+    );
+  },
+);

package/src/elements/checkpoint.tsx

@@ -32,6 +32,10 @@ defineWebComponent<Props, Events>('kc-checkpoint', {
   <Checkpoint>
     <CheckpointTrigger
       tooltip={props.tooltip}
+      // Icon-only (no visible label) needs an accessible name: prefer the
+      // tooltip text, else a sensible default. With a visible label, the text
+      // is the name — leave aria-label unset so it isn't duplicated.
+      aria-label={props.label ? undefined : (props.tooltip ?? 'Checkpoint')}
       variant={props.variant}
       size={props.size}
       onClick={() => dispatch('select')}