@kitnai/chat 0.7.0 → 0.8.0

package/src/components/confirm-card.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import { ConfirmCard, type ConfirmCardData } from './confirm-card';
+import { componentDescription } from '../stories/docs/element-controls';
+import type { CardEvent, CardHost, CardContext } from '../primitives/card-contract';
+
+const ctx: CardContext = { theme: { mode: 'light' }, locale: 'en' };
+
+/** Renders the Solid <ConfirmCard> with a capturing `host`, logging emitted events. */
+function Demo(props: { def: ConfirmCardData; heading?: string; cardId: string }) {
+  const [log, setLog] = createSignal<CardEvent[]>([]);
+  const host: CardHost = { context: () => ctx, emit: (e) => setLog((p) => [...p, e]) };
+  return (
+    <div style={{ 'max-width': '460px', display: 'flex', 'flex-direction': 'column', gap: '12px' }}>
+      <ConfirmCard host={host} data={props.def} heading={props.heading} cardId={props.cardId} />
+      <pre
+        style={{
+          margin: 0,
+          'max-height': '180px',
+          overflow: 'auto',
+          background: 'var(--color-muted, #f4f4f5)',
+          'border-radius': '8px',
+          padding: '8px',
+          'font-size': '12px',
+        }}
+      >
+        {log().length === 0 ? '// emitted CardEvents appear here' : JSON.stringify(log(), null, 2)}
+      </pre>
+    </div>
+  );
+}
+
+const APPROVE: ConfirmCardData = {
+  body: 'This will apply 3 pending migrations to production. This cannot be undone.',
+  tone: 'warning',
+  actions: [
+    { id: 'approve', label: 'Run migration', style: 'primary', default: true },
+    { id: 'reject', label: 'Cancel' },
+  ],
+};
+
+const DESTRUCTIVE: ConfirmCardData = {
+  body: 'Permanently delete 12 files? This cannot be undone.',
+  tone: 'danger',
+  actions: [
+    { id: 'delete', label: 'Delete files', style: 'destructive', default: true },
+    { id: 'cancel', label: 'Keep them' },
+  ],
+};
+
+const meta = {
+  title: 'Components/ConfirmCard',
+  component: ConfirmCard,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'The SolidJS layer behind `<kc-confirm>`. Pass a `host` (a `CardHost`) to receive the emitted `CardEvent`s directly (the native-host path), or wrap in a `CardProvider`. Activating an action emits the `action` verb and resolves the card.',
+      ]),
+    },
+  },
+} satisfies Meta<typeof ConfirmCard>;
+
+export default meta;
+type Story = StoryObj<typeof ConfirmCard>;
+
+export const ApproveReject: Story = {
+  render: () => <Demo def={APPROVE} heading="Run database migration?" cardId="card-approve" />,
+};
+
+export const Destructive: Story = {
+  render: () => <Demo def={DESTRUCTIVE} heading="Delete files?" cardId="card-delete" />,
+};

package/src/components/confirm-card.tsx

@@ -0,0 +1,299 @@
+import {
+  type JSX,
+  For,
+  Show,
+  splitProps,
+  mergeProps,
+  createSignal,
+  createMemo,
+  createEffect,
+  on,
+  ErrorBoundary,
+} from 'solid-js';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+import { Card } from './card';
+import type { CardEnvelope, CardEvent, CardHost } from '../primitives/card-contract';
+import { emitCardEvent } from '../primitives/card-routing';
+import { useCardHost } from '../primitives/card-host';
+import { AlertTriangle, Check, X } from 'lucide-solid';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types (confirm.schema.json) — see src/primitives/card-schemas/confirm.schema.json
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ConfirmActionStyle = 'primary' | 'default' | 'destructive';
+export type ConfirmTone = 'default' | 'warning' | 'danger';
+
+export interface ConfirmAction {
+  id: string;
+  label: string;
+  style?: ConfirmActionStyle;
+  payload?: unknown;
+  default?: boolean;
+}
+
+export interface ConfirmCardData {
+  heading?: string;
+  body?: string;
+  tone?: ConfirmTone;
+  actions: ConfirmAction[]; // 1..4
+  dismissible?: boolean;
+}
+
+export type ConfirmCardEnvelope = CardEnvelope<'confirm', ConfirmCardData>;
+
+export const CONFIRM_CARD_TYPE = 'confirm' as const;
+
+const VALID_STYLES = new Set<ConfirmActionStyle>(['primary', 'default', 'destructive']);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure helpers (unit-tested in isolation).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Map an action's `style` to a Button variant (falls back + warns on unknown). */
+export function buttonVariantForStyle(
+  style: ConfirmActionStyle | undefined,
+): 'default' | 'outline' | 'destructive' {
+  switch (style) {
+    case 'primary':
+      return 'default';
+    case 'destructive':
+      return 'destructive';
+    case 'default':
+    case undefined:
+      return 'outline';
+    default:
+      // eslint-disable-next-line no-console
+      console.warn(`[kc-confirm] unknown action style "${style as string}"; using default`);
+      return 'outline';
+  }
+}
+
+/** De-dupe actions by id (first wins) and validate their shape. Returns the usable
+ *  list + an optional error message when there's nothing renderable. */
+export function normalizeActions(actions: unknown): {
+  actions: ConfirmAction[];
+  error?: string;
+} {
+  if (!Array.isArray(actions) || actions.length === 0) {
+    return { actions: [], error: "This card couldn't be displayed." };
+  }
+  const seen = new Set<string>();
+  const out: ConfirmAction[] = [];
+  for (const a of actions) {
+    if (!a || typeof a !== 'object') continue;
+    const action = a as Partial<ConfirmAction>;
+    if (typeof action.id !== 'string' || action.id.length === 0) continue;
+    if (typeof action.label !== 'string' || action.label.length === 0) continue;
+    if (seen.has(action.id)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[kc-confirm] duplicate action id "${action.id}" ignored`);
+      continue;
+    }
+    seen.add(action.id);
+    const style = VALID_STYLES.has(action.style as ConfirmActionStyle)
+      ? (action.style as ConfirmActionStyle)
+      : undefined;
+    if (action.style !== undefined && style === undefined) {
+      // eslint-disable-next-line no-console
+      console.warn(`[kc-confirm] unknown action style "${String(action.style)}"; using default`);
+    }
+    out.push({
+      id: action.id,
+      label: action.label,
+      style,
+      payload: action.payload,
+      default: action.default === true,
+    });
+  }
+  if (out.length === 0) return { actions: [], error: "This card couldn't be displayed." };
+  return { actions: out };
+}
+
+/** The id of the default action (first with `default:true`), if any. */
+export function defaultActionId(actions: ConfirmAction[]): string | undefined {
+  return actions.find((a) => a.default)?.id;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The <ConfirmCard> component.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ConfirmCardProps {
+  /** The confirm definition (CardEnvelope.data). */
+  data?: ConfirmCardData;
+  /** The card id used to correlate every emitted CardEvent. */
+  cardId?: string;
+  /** The envelope title rendered in the card chrome. */
+  heading?: string;
+  /** Optional explicit CardHost (otherwise read from a CardProvider, otherwise the
+   *  bubbling `kc-card` CustomEvent off `hostElement`). */
+  host?: CardHost;
+  /** The custom-element host node, for the bubbling `kc-card` fallback emit. */
+  hostElement?: HTMLElement;
+  /** Focus the default action on mount. Default OFF (no focus-stealing mid-stream). */
+  autofocus?: boolean;
+  class?: string;
+}
+
+/**
+ * `ConfirmCard` — a named-intent approval card. Renders a title + body + a small
+ * set of action buttons inside `Card` chrome. Activating an action emits the Card
+ * contract's `action` verb (`{ kind:'action', cardId, action, payload }`) and
+ * resolves the card (other actions disabled, the chosen one marked) so the same
+ * approval can't double-fire. Emits `ready` on mount, `dismiss` for the optional
+ * close affordance, and `error` for an unusable definition (inline error state).
+ */
+export function ConfirmCard(props: ConfirmCardProps): JSX.Element {
+  const merged = mergeProps({ cardId: 'kc-confirm', autofocus: false }, props);
+  const [local] = splitProps(merged, [
+    'data',
+    'cardId',
+    'heading',
+    'host',
+    'hostElement',
+    'autofocus',
+    'class',
+  ]);
+
+  const ctxHost = useCardHost();
+
+  const emit = (event: CardEvent): void => {
+    const h = local.host ?? ctxHost;
+    if (h) h.emit(event);
+    else if (local.hostElement) emitCardEvent(local.hostElement, event);
+  };
+
+  const normalized = createMemo(() => normalizeActions(local.data?.actions));
+  const valid = createMemo(() => normalized().error === undefined);
+  const errorMessage = createMemo(() => normalized().error ?? '');
+  const actions = createMemo(() => normalized().actions);
+  const tone = (): ConfirmTone => local.data?.tone ?? 'default';
+  const isDanger = () => tone() === 'danger';
+  const defaultId = createMemo(() => defaultActionId(actions()));
+
+  const [resolved, setResolved] = createSignal<string | undefined>(undefined);
+
+  // Reset resolved state whenever a NEW definition arrives.
+  createEffect(on(() => local.data, () => setResolved(undefined)));
+
+  // ready / error lifecycle emits.
+  createEffect(
+    on(valid, (ok) => {
+      if (ok) emit({ kind: 'ready', cardId: local.cardId });
+      else emit({ kind: 'error', cardId: local.cardId, message: errorMessage() });
+    }),
+  );
+
+  const onAction = (action: ConfirmAction): void => {
+    if (resolved() !== undefined) return; // single-shot
+    emit({
+      kind: 'action',
+      cardId: local.cardId,
+      action: action.id,
+      ...(action.payload !== undefined ? { payload: action.payload } : {}),
+    });
+    setResolved(action.id);
+  };
+
+  const onDismiss = (): void => emit({ kind: 'dismiss', cardId: local.cardId });
+
+  let bodyRef: HTMLDivElement | undefined;
+
+  // Surface the resolved action id for host styling.
+  createEffect(() => {
+    const el = local.hostElement;
+    if (!el) return;
+    const id = resolved();
+    if (id !== undefined) el.setAttribute('data-kc-resolved', id);
+    else el.removeAttribute('data-kc-resolved');
+  });
+
+  return (
+    <Show when={valid()} fallback={<Card heading={local.heading} errorMessage={errorMessage()} />}>
+      <ErrorBoundary
+        fallback={() => {
+          emit({ kind: 'error', cardId: local.cardId, message: 'The card failed to render.' });
+          return <Card heading={local.heading} errorMessage="The card failed to render." />;
+        }}
+      >
+        <Card
+          heading={local.heading}
+          actions={
+            <div class="flex w-full flex-wrap items-center justify-between gap-2">
+              <Show when={local.data?.dismissible === true}>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-sm"
+                  aria-label="Dismiss"
+                  onClick={onDismiss}
+                >
+                  <X size={16} aria-hidden="true" />
+                </Button>
+              </Show>
+              <div class="ml-auto flex flex-wrap items-center gap-2">
+                <For each={actions()}>
+                  {(action) => {
+                    const isChosen = () => resolved() === action.id;
+                    return (
+                      <Button
+                        type="button"
+                        variant={buttonVariantForStyle(action.style)}
+                        disabled={resolved() !== undefined && !isChosen()}
+                        aria-pressed={isChosen() ? 'true' : undefined}
+                        data-action-id={action.id}
+                        data-kc-default={action.default ? 'true' : undefined}
+                        ref={(el) => {
+                          if (local.autofocus && action.id === defaultId()) {
+                            queueMicrotask(() => el.focus());
+                          }
+                        }}
+                        onClick={() => onAction(action)}
+                      >
+                        <Show when={isChosen()}>
+                          <Check size={16} aria-hidden="true" />
+                        </Show>
+                        {action.label}
+                      </Button>
+                    );
+                  }}
+                </For>
+              </div>
+            </div>
+          }
+        >
+          <div
+            ref={bodyRef}
+            class={cn('flex flex-col gap-2', local.class)}
+            onKeyDown={(e) => {
+              // Enter on the card body (not on a focused button) invokes the default action.
+              if (e.key !== 'Enter') return;
+              const target = e.target as HTMLElement;
+              if (target.tagName === 'BUTTON') return;
+              const id = defaultId();
+              if (id === undefined) return;
+              const action = actions().find((a) => a.id === id);
+              if (action) onAction(action);
+            }}
+            tabindex={defaultId() !== undefined ? 0 : undefined}
+          >
+            <Show when={isDanger()}>
+              <div class="flex items-center gap-2 text-sm font-medium text-destructive dark:text-red-400">
+                <AlertTriangle size={16} class="shrink-0" aria-hidden="true" />
+                <span>Heads up</span>
+              </div>
+            </Show>
+            <Show when={local.data?.heading}>
+              <p class="text-sm font-semibold text-foreground">{local.data?.heading}</p>
+            </Show>
+            <Show when={local.data?.body}>
+              <p class="text-sm text-foreground">{local.data?.body}</p>
+            </Show>
+          </div>
+        </Card>
+      </ErrorBoundary>
+    </Show>
+  );
+}

package/src/components/context.stories.tsx

@@ -11,6 +11,7 @@ import {
   ContextReasoningUsage,
   ContextCacheUsage,
 } from './context';
+import { componentDescription } from '../stories/docs/element-controls';
 
 /**
  * Story for the compound `Context` family. `Context` is the root provider that
@@ -25,14 +26,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A model context-window usage indicator: a hover-card trigger showing the used-percent ring, with a popover breaking down token usage (input / output / reasoning / cache) and estimated cost.',
-          '**When to use:** to surface how much of a model\'s context window a conversation has consumed and roughly what it costs — near the prompt input or in a chat header.',
-          '**How to use:** wrap the composition in `<Context>` and pass `usedTokens` / `maxTokens` (plus optional `inputTokens`, `outputTokens`, `reasoningTokens`, `cacheTokens`, `estimatedCost`). Compose `ContextTrigger`, `ContextContent` (with `Header`/`Body`/`Footer`), and the usage rows.',
-          '**Placement:** chat toolbars, prompt-input action bars, and conversation headers.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A model context-window usage indicator: a hover-card trigger showing the used-percent ring, with a popover breaking down token usage (input / output / reasoning / cache) and estimated cost.',
+        '**When to use:** to surface how much of a model\'s context window a conversation has consumed and roughly what it costs — near the prompt input or in a chat header.',
+        '**How to use:** wrap the composition in `<Context>` and pass `usedTokens` / `maxTokens` (plus optional `inputTokens`, `outputTokens`, `reasoningTokens`, `cacheTokens`, `estimatedCost`). Compose `ContextTrigger`, `ContextContent` (with `Header`/`Body`/`Footer`), and the usage rows.',
+        '**Placement:** chat toolbars, prompt-input action bars, and conversation headers.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },

package/src/components/conversation-item.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { ConversationItem } from './conversation-item';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const baseConversation = {
   id: '1',
@@ -22,14 +23,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A single conversation row — shows the title and message count, truncating long titles, with a highlighted active state.',
-          '**When to use:** as the leaf item inside a chat history sidebar. Usually rendered for you by `ConversationList`; use it directly to build a custom list.',
-          '**How to use:** pass a `conversation` summary, an `isActive` flag, and an `onSelect(id)` handler fired when the row is clicked.',
-          '**Placement:** inside a conversation/chat history sidebar list.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A single conversation row — shows the title and message count, truncating long titles, with a highlighted active state.',
+        '**When to use:** as the leaf item inside a chat history sidebar. Usually rendered for you by `ConversationList`; use it directly to build a custom list.',
+        '**How to use:** pass a `conversation` summary, an `isActive` flag, and an `onSelect(id)` handler fired when the row is clicked.',
+        '**Placement:** inside a conversation/chat history sidebar list.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },

package/src/components/conversation-item.tsx

@@ -9,8 +9,8 @@ export function ConversationItem(props: ConversationItemProps) {
   return (
     <button data-conversation-id={local.conversation.id} onClick={() => local.onSelect(local.conversation.id)}
       class={cn('w-full text-left rounded-lg px-2.5 py-2 transition-colors', local.isActive ? 'bg-muted' : 'hover:bg-muted/50', local.class)}>
-      <div class={cn('truncate text-sm', local.isActive ? 'text-foreground font-medium' : 'text-muted-foreground')}>{local.conversation.title}</div>
-      <div class="text-muted-foreground truncate mt-0.5 text-xs">{local.conversation.messageCount} messages</div>
+      <div class={cn('truncate text-sm', local.isActive ? 'text-foreground font-medium' : 'text-foreground/80')}>{local.conversation.title}</div>
+      <div class={cn('truncate mt-0.5 text-xs', local.isActive ? 'text-foreground/70' : 'text-muted-foreground')}>{local.conversation.messageCount} messages</div>
     </button>
   );
 }

package/src/components/conversation-list.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { ConversationList, type ConversationListProps } from './conversation-list';
 import type { ConversationSummary, ConversationGroup } from '../types';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const scope = { type: 'document' as const };
 
@@ -31,14 +32,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A full chat-history sidebar: header (sidebar toggle + new chat), a built-in search box that filters by title, and conversations bucketed into collapsible, count-badged groups.',
-          '**When to use:** as the left-hand navigation for a chat app — browsing, searching, and switching between past conversations.',
-          '**How to use:** pass `groups` and `conversations` arrays, the `activeId`, and handlers `onSelect(id)` / `onNewChat()` (plus optional `onToggleSidebar()`). Give it a sized, overflow-hidden container.',
-          '**Placement:** the persistent left sidebar of a chat layout.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A full chat-history sidebar: header (sidebar toggle + new chat), a built-in search box that filters by title, and conversations bucketed into collapsible, count-badged groups.',
+        '**When to use:** as the left-hand navigation for a chat app — browsing, searching, and switching between past conversations.',
+        '**How to use:** pass `groups` and `conversations` arrays, the `activeId`, and handlers `onSelect(id)` / `onNewChat()` (plus optional `onToggleSidebar()`). Give it a sized, overflow-hidden container.',
+        '**Placement:** the persistent left sidebar of a chat layout.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },

package/src/components/conversation-list.tsx

@@ -83,7 +83,7 @@ function GroupSection(props: { name: string; count: number; conversations: Conve
   const [open, setOpen] = createSignal(true);
   return (
     <Collapsible open={open()} onOpenChange={setOpen}>
-      <CollapsibleTrigger class="flex items-center gap-1.5 w-full px-1.5 py-1 rounded-md bg-muted/30 text-[13px] text-muted-foreground font-medium hover:bg-muted/50 transition-colors cursor-pointer mt-1.5">
+      <CollapsibleTrigger class="flex items-center gap-1.5 w-full px-1.5 py-1 rounded-md bg-muted text-[13px] text-foreground/80 font-medium hover:bg-muted/70 transition-colors cursor-pointer mt-1.5">
         <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
           class={cn('transition-transform', !open() && '-rotate-90')}><polyline points="6 9 12 15 18 9"/></svg>
         <span>{props.name}</span>