@kitnai/chat 0.8.0 → 0.9.0

package/src/elements/resizable.tsx

@@ -1,9 +1,29 @@
-import { createSignal, onMount, onCleanup, For, Show, type JSX } from 'solid-js';
+import { createSignal, createEffect, on, onMount, onCleanup, For, Show, type JSX } from 'solid-js';
 import { defineWebComponent } from './define';
 import { ResizableHandle, normalizeSize } from '../ui/resizable';
 
 type Orientation = 'horizontal' | 'vertical';
 
+/** Bubbling, composed intent: a descendant asks the nearest enclosing
+ *  <kc-resizable> to maximize the item containing it (filling, hiding siblings)
+ *  or to restore. Any panel content may emit it — the protocol is zero-config. */
+export interface KcMaximizeIntentDetail {
+  /** true = maximize the item containing me; false = restore. */
+  requested: boolean;
+}
+
+/** Composed, non-bubbling notification the group dispatches DOWN onto the
+ *  affected <kc-resizable-item> (on maximize) or the group host + the formerly
+ *  maximized item (on restore) so descendant content can sync its affordance. */
+export interface KcMaximizeStateDetail {
+  /** Whether THIS subtree's item is the maximized one. */
+  maximized: boolean;
+}
+
+/** Event type names for the cross-element maximize protocol. */
+export const KC_MAXIMIZE_INTENT = 'kc-maximize-intent' as const;
+export const KC_MAXIMIZE_STATE = 'kc-maximize-state' as const;
+
 /** Parsed view of a `<kc-resizable-item>` light child. */
 interface ItemInfo {
   el: HTMLElement;
@@ -30,11 +50,15 @@ function boundAttrs(value: string | undefined): { pxAttr?: string; pctAttr?: str
 interface GroupProps extends Record<string, unknown> {
   /** Layout axis: `horizontal` (row, default) or `vertical` (column). */
   orientation?: Orientation;
+  /** Which item index is maximized (null = none). Declarative source of truth. */
+  maximizedIndex?: number | null;
 }
 
 interface GroupEvents extends Record<string, unknown> {
   /** Fired on drag-end / keyboard resize / visibility change. `detail.sizes` = panel sizes in percent. */
   change: { sizes: number[] };
+  /** Observe layout maximize state. */
+  maximizechange: { maximized: boolean; index: number | null };
 }
 
 /**
@@ -47,6 +71,7 @@ interface GroupEvents extends Record<string, unknown> {
  */
 defineWebComponent<GroupProps, GroupEvents>('kc-resizable', {
   orientation: 'horizontal',
+  maximizedIndex: null,
 }, (props, { element, dispatch }) => {
   const [items, setItems] = createSignal<ItemInfo[]>([]);
   const orientation = (): Orientation => (props.orientation === 'vertical' ? 'vertical' : 'horizontal');
@@ -111,11 +136,162 @@ defineWebComponent<GroupProps, GroupEvents>('kc-resizable', {
     dispatch('change', { sizes: currentSizes() });
   }
 
+  // --- Task 2: maximize/restore core ---
+
+  interface SavedItemState {
+    el: HTMLElement;
+    size: string | null;
+    hidden: boolean;
+    locked: boolean;
+  }
+  interface MaximizeStash {
+    /** The element that was maximized (identity anchor for re-target + events). */
+    item: HTMLElement;
+    /** Per-element stash keyed by element identity, not position. */
+    saved: SavedItemState[];
+  }
+  const [maximized, setMaximized] = createSignal<MaximizeStash | null>(null);
+  /** Re-entrancy guard: while we (un)apply maximize attributes, the observer must
+   *  NOT emit a mid-flight `change`. The final relayout emits the real one. */
+  let applyingMaximize = false;
+
+  /** Find the capped <kc-resizable-item> ancestor of an event target, if any. */
+  function findContainingItem(node: Node | null): HTMLElement | null {
+    let el = node instanceof Element ? node : node?.parentElement ?? null;
+    // The intent is composed; its target may be inside the artifact's shadow.
+    // Resolve to a direct light child <kc-resizable-item> of THIS group.
+    const capped = items().map((i) => i.el);
+    while (el) {
+      if (el instanceof HTMLElement && capped.includes(el)) return el;
+      el = el.parentElement ?? (el.getRootNode() as ShadowRoot).host ?? null;
+    }
+    return null;
+  }
+
+  function readAttrState(el: HTMLElement) {
+    return {
+      size: el.getAttribute('size'),
+      hidden: el.hidden || (el.hasAttribute('hidden') && el.getAttribute('hidden') !== 'false'),
+      locked: el.hasAttribute('locked') && el.getAttribute('locked') !== 'false',
+    };
+  }
+
+  function setBoolAttr(el: HTMLElement, name: string, on: boolean) {
+    if (on) el.setAttribute(name, '');
+    else el.removeAttribute(name);
+  }
+
+  function maximizeItem(item: HTMLElement) {
+    const list = items();
+    const index = list.findIndex((i) => i.el === item);
+    if (index < 0) return;
+    const current = maximized();
+    if (current) {
+      if (current.item === item) return;       // same item → no-op
+      restore();                               // different item → re-target
+    }
+    applyingMaximize = true;
+    // Capture the EFFECTIVE current % so a post-drag layout restores faithfully.
+    const live = currentSizes(); // visible-order percents (Playwright-verified)
+    let visIdx = 0;
+    const saved: SavedItemState[] = list.map((info) => {
+      const prev = readAttrState(info.el);
+      if (!prev.hidden) {
+        // Write the live % back as the stashed size baseline.
+        const pct = live[visIdx++];
+        if (Number.isFinite(pct) && pct > 0) info.el.setAttribute('size', `${pct}%`);
+      }
+      return { el: info.el, size: info.el.getAttribute('size'), hidden: prev.hidden, locked: prev.locked };
+    });
+    // Hide every other item; free the maximized one to fill.
+    list.forEach((info, i) => {
+      if (i === index) {
+        info.el.removeAttribute('size');
+        info.el.removeAttribute('locked');
+        setBoolAttr(info.el, 'hidden', false);
+      } else {
+        setBoolAttr(info.el, 'hidden', true);
+      }
+    });
+    setMaximized({ item, saved });
+    element.setAttribute('data-maximized', '');
+    item.setAttribute('data-maximized-panel', '');
+    readItems();
+    emitChange();
+    // Keep applyingMaximize = true until AFTER the MutationObserver microtask fires
+    // so its queueMicrotask(emitChange) sees the guard and skips (storm guard).
+    queueMicrotask(() => { applyingMaximize = false; });
+    // Tell the maximized subtree (and only it) it is now maximized.
+    item.dispatchEvent(new CustomEvent('kc-maximize-state', { detail: { maximized: true }, bubbles: false, composed: true }));
+    dispatch('maximizechange', { maximized: true, index });
+  }
+
+  function restore() {
+    const stash = maximized();
+    if (!stash) return;
+    applyingMaximize = true;
+    // Re-apply saved state keyed by element identity; items no longer in the DOM
+    // are simply skipped.  This is safe regardless of sibling additions/removals
+    // that happened while maximized (no index drift).
+    for (const s of stash.saved) {
+      if (!s.el.isConnected) continue;
+      if (s.size === null) s.el.removeAttribute('size');
+      else s.el.setAttribute('size', s.size);
+      setBoolAttr(s.el, 'hidden', s.hidden);
+      setBoolAttr(s.el, 'locked', s.locked);
+      s.el.removeAttribute('data-maximized-panel');
+    }
+    const prevItem = stash.item;
+    setMaximized(null);
+    element.removeAttribute('data-maximized');
+    readItems();
+    emitChange();
+    // Keep applyingMaximize = true until AFTER the MutationObserver microtask fires
+    // so its queueMicrotask(emitChange) sees the guard and skips (storm guard).
+    queueMicrotask(() => { applyingMaximize = false; });
+    // Broadcast restore on the host AND directly on the formerly-maximized item.
+    element.dispatchEvent(new CustomEvent('kc-maximize-state', { detail: { maximized: false }, bubbles: false, composed: true }));
+    prevItem?.dispatchEvent(new CustomEvent('kc-maximize-state', { detail: { maximized: false }, bubbles: false, composed: true }));
+    dispatch('maximizechange', { maximized: false, index: null });
+  }
+
   onMount(() => {
     readItems();
+    const onIntent = (e: Event) => {
+      const ce = e as CustomEvent<KcMaximizeIntentDetail>;
+      e.stopPropagation();                       // nearest group wins (nesting)
+      const item = findContainingItem(ce.target as Node);
+      if (!item) return;                         // outside any item → ignore
+      if (ce.detail.requested) maximizeItem(item);
+      else restore();
+    };
+    element.addEventListener('kc-maximize-intent', onIntent);
+
+    const onKeydown = (e: KeyboardEvent) => {
+      // Only act while maximized — the capture listener on the host already
+      // ensures the event originates within the group.
+      if (e.key !== 'Escape' || !maximized()) return;
+      e.stopPropagation();
+      restore();
+    };
+    element.addEventListener('keydown', onKeydown, true);
+
     const mo = new MutationObserver(() => {
       readItems();
-      // A childList / attribute change (e.g. show/hide) re-lays out → emit.
+      const stash = maximized();
+      if (stash) {
+        // Use element identity, not a positional index, to detect whether the
+        // maximized item is still present and visible.
+        const maximizedEl = stash.item;
+        const isConnected = maximizedEl.isConnected && element.contains(maximizedEl);
+        const isVisible = isConnected && !(maximizedEl.hidden || maximizedEl.hasAttribute('hidden'));
+        if (!isConnected || !isVisible) {
+          // The maximized item was removed or hidden out from under us → restore.
+          restore();
+          return;
+        }
+      }
+      if (applyingMaximize) return;              // our own writes — skip auto-emit
       queueMicrotask(emitChange);
     });
     mo.observe(element, {
@@ -127,7 +303,36 @@ defineWebComponent<GroupProps, GroupEvents>('kc-resizable', {
       attributes: true,
       attributeFilter: ['size', 'locked', 'min', 'max', 'hidden'],
     });
-    onCleanup(() => mo.disconnect());
+    onCleanup(() => {
+      mo.disconnect();
+      element.removeEventListener('kc-maximize-intent', onIntent);
+      element.removeEventListener('keydown', onKeydown, true);
+    });
+
+    // --- Task 3: imperative host methods + declarative maximizedIndex prop ---
+
+    // Imperative host API (assigned onto the element; typed by resizable.d.ts).
+    const host = element as unknown as { maximize(i: number): void; restore(): void };
+    host.maximize = (i: number) => {
+      const it = items()[i]?.el;
+      if (it) maximizeItem(it);
+    };
+    host.restore = () => restore();
+
+    // Declarative maximizedIndex → maximize/restore. Skip the initial null run.
+    createEffect(
+      on(
+        () => props.maximizedIndex,
+        (idx) => {
+          if (idx == null) restore();
+          else {
+            const it = items()[idx]?.el;
+            if (it) maximizeItem(it);
+          }
+        },
+        { defer: true },
+      ),
+    );
   });
 
   const isHoriz = () => orientation() === 'horizontal';

package/src/index.ts

@@ -29,6 +29,16 @@ export { CARD_EVENT_NAME, emitCardEvent, routeCardEvent, listenForCardEvents } f
 export { validateAgainstSchema } from './primitives/card-validate';
 export type { JsonSchema, ValidationResult } from './primitives/card-validate';
 
+// Card dispatcher (generative-UI host glue)
+export { CardRenderer, renderCard } from './components/card-renderer';
+export type { CardRendererProps } from './components/card-renderer';
+export { CardFallback } from './components/card-fallback';
+export type { CardFallbackProps } from './components/card-fallback';
+export {
+  BUILTIN_CARD_TAGS, BUILTIN_CARD_COMPONENTS, mergeCardTags, mergeCardComponents,
+} from './primitives/card-registry';
+export type { CardComponent, CardComponentMap, CardTagMap } from './primitives/card-registry';
+
 // Card: kc-card (base shell) + kc-form (JSON-Schema form renderer)
 export { Card } from './components/card';
 export type { CardProps } from './components/card';

package/src/primitives/card-registry.tsx

@@ -0,0 +1,58 @@
+// src/primitives/card-registry.tsx
+// One source of truth mapping a CardEnvelope.type to a renderer, for both layers:
+//   - CardComponentMap drives the Solid <CardRenderer>.
+//   - CardTagMap drives the <kc-cards> web component (child kc-* elements).
+// Built-ins cover the 5 contract card types; consumers extend/override via a `types`
+// prop (merged OVER the built-ins). kc-card (bare shell) is intentionally NOT a target.
+import type { Component } from 'solid-js';
+import type { CardEnvelope, CardHost } from './card-contract';
+import { Form } from '../components/form';
+import { ConfirmCard } from '../components/confirm-card';
+import { TaskListCard } from '../components/task-list-card';
+import { LinkCard } from '../components/link-card';
+import { Embed } from '../components/embed';
+
+/** Solid renderer for one envelope. `host` is the resolved CardHost so each wrapper
+ *  can bridge its card's emit convention (form/confirm/task-list take `host`;
+ *  link/embed take `onEmit`). */
+export type CardComponent = Component<{ envelope: CardEnvelope; host?: CardHost }>;
+export type CardComponentMap = Record<string, CardComponent>;
+
+/** Web-component layer: envelope type → kc-* tag name. */
+export type CardTagMap = Record<string, string>;
+
+export const BUILTIN_CARD_TAGS: CardTagMap = {
+  form: 'kc-form',
+  confirm: 'kc-confirm',
+  'task-list': 'kc-task-list',
+  link: 'kc-link-card',
+  embed: 'kc-embed',
+};
+
+export const BUILTIN_CARD_COMPONENTS: CardComponentMap = {
+  form: (p) => (
+    <Form data={p.envelope.data as never} cardId={p.envelope.id} heading={p.envelope.title} host={p.host} />
+  ),
+  confirm: (p) => (
+    <ConfirmCard data={p.envelope.data as never} cardId={p.envelope.id} heading={p.envelope.title} host={p.host} />
+  ),
+  'task-list': (p) => (
+    <TaskListCard data={p.envelope.data as never} cardId={p.envelope.id} heading={p.envelope.title} host={p.host} />
+  ),
+  // link/embed have no `heading` and emit via an onEmit callback (no context).
+  link: (p) => (
+    <LinkCard data={p.envelope.data as never} cardId={p.envelope.id} onEmit={(e) => p.host?.emit(e)} />
+  ),
+  embed: (p) => (
+    <Embed data={p.envelope.data as never} cardId={p.envelope.id} onEmit={(e) => p.host?.emit(e)} />
+  ),
+};
+
+/** Built-ins with the consumer's overrides merged on top (consumer wins). */
+export function mergeCardComponents(types?: CardComponentMap): CardComponentMap {
+  return types ? { ...BUILTIN_CARD_COMPONENTS, ...types } : { ...BUILTIN_CARD_COMPONENTS };
+}
+
+export function mergeCardTags(types?: CardTagMap): CardTagMap {
+  return types ? { ...BUILTIN_CARD_TAGS, ...types } : { ...BUILTIN_CARD_TAGS };
+}

package/src/stories/docs/generative-ui-overview.mdx

@@ -0,0 +1,59 @@
+{/* src/stories/docs/generative-ui-overview.mdx */}
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Generative UI/Overview" />
+
+# Generative UI
+
+Agents don't just reply with text — they ask the chat to **render typed, interactive
+cards**: a form to fill, an action to approve, a plan to pick from, a link to preview.
+`@kitnai/chat` does this with a small, typed **Card Contract** and a turnkey dispatcher.
+
+## The loop
+
+```
+agent/server ──CardEnvelope(s)──▶ host sets <kc-cards>.cards
+     ▲                                      │
+     │                              dispatcher renders the right kc-* by `type`
+     │                                      │
+     └── result / next envelopes ◀─ CardPolicy ◀─ kc-card event ◀─ user interacts
+```
+
+## The envelope
+
+Everything an agent sends is a `CardEnvelope`:
+
+```ts
+interface CardEnvelope { type: string; id: string; data: unknown; title?: string }
+```
+
+`type` selects the card (`form`, `confirm`, `task-list`, `link`, `embed`); `data` follows
+that type's **JSON Schema** (shipped in `dist/schemas`, so an agent/server can validate
+before sending); `id` correlates every event back to this card.
+
+## Turnkey: drop `<kc-cards>`
+
+```html
+<kc-cards></kc-cards>
+<script type="module">
+  import '@kitnai/chat/elements';
+  const cards = document.querySelector('kc-cards');
+  cards.cards = [{ type: 'confirm', id: 'deploy', title: 'Deploy?',
+    data: { body: 'Ship it?', actions: [{ id: 'go', label: 'Deploy', default: true }] } }];
+  cards.policy = { onAction: (id, action) => console.log(id, action) };
+</script>
+```
+
+`<kc-cards>` renders one card per envelope and routes every interaction through `policy`
+(or listen for the raw bubbling `kc-card` event). In SolidJS, use `renderCard(envelope)` /
+`<CardRenderer>` inside a `<CardProvider>`.
+
+## Streaming & follow-ups
+
+Swap the `cards` array to add, replace, or remove cards — e.g. replace a `confirm` with a
+result card once the user acts. For **live streaming into a single card**, the SolidJS
+`<CardRenderer>` re-renders reactively as its envelope's `data` changes, so an agent can
+stream into it as work progresses. (Keyed-by-`id` in-place updates within a `<kc-cards>`
+list are a planned refinement.)
+
+See **Cards** for each card type, and **SDK** for the dispatcher in action.

package/src/ui/resizable.tsx

@@ -1,4 +1,4 @@
-import { type JSX, splitProps, createSignal, createContext, useContext, For, Show, children as resolveChildren } from 'solid-js';
+import { type JSX, splitProps, createSignal, createEffect, createContext, useContext, For, Show, children as resolveChildren } from 'solid-js';
 import { cn } from '../utils/cn';
 
 // --- Types ---
@@ -426,6 +426,10 @@ export interface ResizableProps {
   /** Show a visible grip on each interactive handle. */
   withHandle?: boolean;
   class?: string;
+  /** Which panel index is maximized (null = none). Hides the others. */
+  maximizedIndex?: number | null;
+  /** Fired when the maximized panel changes (index, or null on restore). */
+  onMaximizeChange?: (index: number | null) => void;
   /** `ResizablePanel` children. */
   children: JSX.Element;
 }
@@ -438,7 +442,9 @@ export interface ResizableProps {
  * `ResizablePanelGroup` + explicit `ResizableHandle`s.
  */
 function Resizable(props: ResizableProps) {
-  const [local] = splitProps(props, ['orientation', 'onChange', 'withHandle', 'class', 'children']);
+  const [local] = splitProps(props, [
+    'orientation', 'onChange', 'withHandle', 'class', 'children', 'maximizedIndex', 'onMaximizeChange',
+  ]);
   const orientation = () => local.orientation ?? 'horizontal';
 
   // Resolve children to the actual panel elements so we can read their props.
@@ -455,6 +461,29 @@ function Resizable(props: ResizableProps) {
 
   const visible = () => panels().filter((p) => !p.hidden);
 
+  const maxIdx = () => local.maximizedIndex ?? null;
+  // When maximized, only the maximized panel is "visible" for layout; siblings drop
+  // (mirrors the web-component facade hiding siblings). Indices are over all panels.
+  // Note: stash/restore of sizes is handled by the panels' own defaultSize/flex —
+  // since the convenience re-renders from the unchanged ResizablePanel children on
+  // restore, sizes return to their declared values. The post-drag-live-size stash
+  // fidelity is a web-component-only concern; the Solid story uses declarative sizes.
+  const renderPanels = () => {
+    const all = panels();
+    const m = maxIdx();
+    if (m == null) return all.filter((p) => !p.hidden);
+    const target = all[m];
+    return target && !target.hidden ? [target] : all.filter((p) => !p.hidden);
+  };
+
+  // Notify on change of the maximized index (defer the initial null run).
+  let prevMax: number | null | undefined;
+  createEffect(() => {
+    const m = maxIdx();
+    if (prevMax === undefined) { prevMax = m; return; }
+    if (m !== prevMax) { prevMax = m; local.onMaximizeChange?.(m); }
+  });
+
   function emitChange() {
     if (!local.onChange) return;
     const sizes = visible().map((p) => {
@@ -477,13 +506,13 @@ function Resizable(props: ResizableProps) {
         )}
         data-orientation={orientation()}
       >
-        <For each={visible()}>
+        <For each={renderPanels()}>
           {(panel, i) => (
             <>
               <Show when={i() > 0}>
                 <ResizableHandle
                   withHandle={local.withHandle}
-                  static={panel.locked || visible()[i() - 1]?.locked}
+                  static={panel.locked || renderPanels()[i() - 1]?.locked}
                   onPanelResize={() => emitChange()}
                 />
               </Show>