@kitn.ai/ui 0.14.1

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: 'Solid (Advanced)/Elements/ConfirmCard',
+  component: ConfirmCard,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'The SolidJS layer behind `<kai-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,315 @@
+import {
+  type JSX,
+  For,
+  Show,
+  splitProps,
+  mergeProps,
+  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, CardResolution } from '../primitives/card-contract';
+import { useCardResolution } from './use-card-resolution';
+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(`[kai-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(`[kai-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(`[kai-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 `kai-card` CustomEvent off `hostElement`). */
+  host?: CardHost;
+  /** The custom-element host node, for the bubbling `kai-card` fallback emit. */
+  hostElement?: HTMLElement;
+  /** Focus the default action on mount. Default OFF (no focus-stealing mid-stream). */
+  autofocus?: boolean;
+  class?: string;
+  /** When set, render the chromed read-only view instead of the buttons. */
+  resolution?: CardResolution;
+}
+
+/**
+ * `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: 'kai-confirm', autofocus: false }, props);
+  const [local] = splitProps(merged, [
+    'data',
+    'cardId',
+    'heading',
+    'host',
+    'hostElement',
+    'autofocus',
+    'class',
+    'resolution',
+  ]);
+
+  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 res = useCardResolution({ prop: () => local.resolution, data: () => local.data });
+
+  const resolvedAction = createMemo(() => {
+    const r = res.resolution();
+    if (!r || r.kind !== 'action') return undefined;
+    const found = actions().find((a) => a.id === r.action);
+    return { label: found?.label ?? r.action };
+  });
+
+  // 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 (res.isResolved()) return; // single-shot
+    emit({
+      kind: 'action',
+      cardId: local.cardId,
+      action: action.id,
+      ...(action.payload !== undefined ? { payload: action.payload } : {}),
+    });
+    res.setLocal({
+      kind: 'action',
+      action: action.id,
+      ...(action.payload !== undefined ? { payload: action.payload } : {}),
+    });
+  };
+
+  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 r = res.resolution();
+    if (r && r.kind === 'action') el.setAttribute('data-kai-resolved', r.action);
+    else el.removeAttribute('data-kai-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={
+            <Show
+              when={!res.isResolved()}
+              fallback={
+                <div
+                  class="ml-auto flex items-center gap-2 text-sm font-medium text-foreground"
+                  role={res.isOptimistic() ? 'status' : undefined}
+                >
+                  <Check size={16} aria-hidden="true" />
+                  <span>{resolvedAction()?.label}</span>
+                </div>
+              }
+            >
+              <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) => (
+                      <Button
+                        type="button"
+                        variant={buttonVariantForStyle(action.style)}
+                        data-action-id={action.id}
+                        data-kai-default={action.default ? 'true' : undefined}
+                        ref={(el) => {
+                          if (local.autofocus && action.id === defaultId()) {
+                            queueMicrotask(() => el.focus());
+                          }
+                        }}
+                        onClick={() => onAction(action)}
+                      >
+                        {action.label}
+                      </Button>
+                    )}
+                  </For>
+                </div>
+              </div>
+            </Show>
+          }
+        >
+          <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

@@ -0,0 +1,229 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import {
+  Context,
+  ContextTrigger,
+  ContextContent,
+  ContextContentHeader,
+  ContextContentBody,
+  ContextContentFooter,
+  ContextInputUsage,
+  ContextOutputUsage,
+  ContextReasoningUsage,
+  ContextCacheUsage,
+} from './context';
+import { componentDescription } from '../stories/docs/element-controls';
+
+/**
+ * Story for the compound `Context` family. `Context` is the root provider that
+ * holds the token-usage values; the trigger/content/usage-row subcomponents read
+ * from it. The controllable props all live on the `Context` root, so `Playground`
+ * drives the root and composes a full hover-card breakdown.
+ */
+const meta = {
+  title: 'Solid (Advanced)/Elements/Context',
+  component: Context,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      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'] },
+    },
+  },
+  argTypes: {
+    usedTokens: {
+      control: 'number',
+      description: 'Tokens consumed so far. Drives the ring fill and progress bar.',
+    },
+    maxTokens: {
+      control: 'number',
+      description: 'Total context window size.',
+    },
+    inputTokens: {
+      control: 'number',
+      description: 'Prompt/input tokens (shown by `ContextInputUsage`).',
+    },
+    outputTokens: {
+      control: 'number',
+      description: 'Generated/output tokens (shown by `ContextOutputUsage`).',
+    },
+    reasoningTokens: {
+      control: 'number',
+      description: 'Reasoning tokens (shown by `ContextReasoningUsage`).',
+    },
+    cacheTokens: {
+      control: 'number',
+      description: 'Cached tokens (shown by `ContextCacheUsage`).',
+    },
+    estimatedCost: {
+      control: 'number',
+      description: 'Estimated cost in USD (shown by `ContextContentFooter`).',
+    },
+    warnThreshold: {
+      control: 'number',
+      description: 'Fraction (0–1) above which the bar turns yellow. Default `0.7`.',
+    },
+    dangerThreshold: {
+      control: 'number',
+      description: 'Fraction (0–1) above which the bar turns red. Default `0.9`.',
+    },
+  },
+  args: {
+    usedTokens: 85000,
+    maxTokens: 128000,
+    inputTokens: 60000,
+    outputTokens: 15000,
+    reasoningTokens: 8000,
+    cacheTokens: 2000,
+    estimatedCost: 0.45,
+  },
+  render: (args) => (
+    <Context {...args}>
+      <ContextTrigger />
+      <ContextContent>
+        <ContextContentHeader />
+        <ContextContentBody>
+          <div class="space-y-1">
+            <ContextInputUsage />
+            <ContextOutputUsage />
+            <ContextReasoningUsage />
+            <ContextCacheUsage />
+          </div>
+        </ContextContentBody>
+        <ContextContentFooter />
+      </ContextContent>
+    </Context>
+  ),
+} satisfies Meta<typeof Context>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import {
+  Context, ContextTrigger, ContextContent, ContextContentHeader,
+  ContextContentBody, ContextContentFooter,
+  ContextInputUsage, ContextOutputUsage, ContextReasoningUsage, ContextCacheUsage,
+} from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+const usage = `<Context usedTokens={85000} maxTokens={128000} inputTokens={60000} outputTokens={15000} reasoningTokens={8000} cacheTokens={2000} estimatedCost={0.45}>
+  <ContextTrigger />
+  <ContextContent>
+    <ContextContentHeader />
+    <ContextContentBody>
+      <div class="space-y-1">
+        <ContextInputUsage />
+        <ContextOutputUsage />
+        <ContextReasoningUsage />
+        <ContextCacheUsage />
+      </div>
+    </ContextContentBody>
+    <ContextContentFooter />
+  </ContextContent>
+</Context>`;
+
+/** Interactive playground — tweak token counts to watch the ring, bar color, and breakdown update. */
+export const Playground: Story = {
+  ...src(usage),
+};
+
+export const LowUsage: Story = {
+  args: {
+    usedTokens: 12000,
+    maxTokens: 128000,
+    inputTokens: 8000,
+    outputTokens: 4000,
+    reasoningTokens: undefined,
+    cacheTokens: undefined,
+    estimatedCost: 0.02,
+  },
+  ...src(usage),
+};
+
+export const MediumUsage: Story = {
+  args: {
+    usedTokens: 85000,
+    maxTokens: 128000,
+    inputTokens: 60000,
+    outputTokens: 15000,
+    reasoningTokens: 8000,
+    cacheTokens: 2000,
+    estimatedCost: 0.45,
+  },
+  ...src(usage),
+};
+
+export const HighUsage: Story = {
+  args: {
+    usedTokens: 122000,
+    maxTokens: 128000,
+    inputTokens: 90000,
+    outputTokens: 22000,
+    reasoningTokens: 10000,
+    cacheTokens: undefined,
+    estimatedCost: 1.85,
+  },
+  ...src(usage),
+};
+
+export const WithCost: Story = {
+  args: {
+    usedTokens: 50000,
+    maxTokens: 200000,
+    inputTokens: 35000,
+    outputTokens: 10000,
+    reasoningTokens: 5000,
+    cacheTokens: undefined,
+    estimatedCost: 0.32,
+  },
+  ...src(usage),
+};
+
+const customThresholdUsage = `<Context
+  usedTokens={110000}
+  maxTokens={200000}
+  inputTokens={70000}
+  outputTokens={40000}
+  estimatedCost={0.65}
+  warnThreshold={0.5}
+  dangerThreshold={0.75}
+>
+  <ContextTrigger />
+  <ContextContent>
+    <ContextContentHeader />
+    <ContextContentBody>
+      <div class="space-y-1">
+        <ContextInputUsage />
+        <ContextOutputUsage />
+      </div>
+    </ContextContentBody>
+    <ContextContentFooter />
+  </ContextContent>
+</Context>`;
+
+/**
+ * Custom thresholds — `warnThreshold=0.5` / `dangerThreshold=0.75` so the bar
+ * turns yellow at 50% and red at 75%. At 55% (110 000 / 200 000) the bar renders
+ * yellow even though the defaults would show green at this level.
+ */
+export const CustomThresholds: Story = {
+  args: {
+    usedTokens: 110000,
+    maxTokens: 200000,
+    inputTokens: 70000,
+    outputTokens: 40000,
+    reasoningTokens: undefined,
+    cacheTokens: undefined,
+    estimatedCost: 0.65,
+    warnThreshold: 0.5,
+    dangerThreshold: 0.75,
+  },
+  ...src(customThresholdUsage),
+};