@kitn.ai/ui 0.14.1

package/src/components/context.test.tsx

@@ -0,0 +1,133 @@
+import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, cleanup, fireEvent, screen } from '@solidjs/testing-library';
+import {
+  Context,
+  ContextTrigger,
+  ContextContent,
+  ContextContentHeader,
+  ContextContentBody,
+  ContextContentFooter,
+  computeSeverity,
+  DEFAULT_WARN_THRESHOLD,
+  DEFAULT_DANGER_THRESHOLD,
+} from './context';
+
+// jsdom does not implement PointerEvent — shim it so fireEvent.pointerEnter works.
+if (typeof (globalThis as unknown as Record<string, unknown>).PointerEvent === 'undefined') {
+  (globalThis as unknown as Record<string, unknown>).PointerEvent = class PointerEvent extends MouseEvent {
+    constructor(type: string, params?: PointerEventInit) { super(type, params); }
+  };
+}
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => {
+  vi.useRealTimers();
+  cleanup();
+});
+
+// ---------------------------------------------------------------------------
+// computeSeverity — pure function unit tests
+// ---------------------------------------------------------------------------
+
+describe('computeSeverity', () => {
+  it('returns ok below the warn threshold (defaults)', () => {
+    expect(computeSeverity(0)).toBe('ok');
+    expect(computeSeverity(0.5)).toBe('ok');
+    expect(computeSeverity(DEFAULT_WARN_THRESHOLD)).toBe('ok'); // exactly at threshold → still ok
+  });
+
+  it('returns warn when usage exceeds the warn threshold but not the danger threshold', () => {
+    expect(computeSeverity(0.71)).toBe('warn');
+    expect(computeSeverity(DEFAULT_WARN_THRESHOLD + 0.001)).toBe('warn');
+    expect(computeSeverity(DEFAULT_DANGER_THRESHOLD)).toBe('warn'); // exactly at danger threshold → still warn
+  });
+
+  it('returns danger when usage exceeds the danger threshold', () => {
+    expect(computeSeverity(0.91)).toBe('danger');
+    expect(computeSeverity(1.0)).toBe('danger');
+  });
+
+  it('respects custom warnThreshold', () => {
+    expect(computeSeverity(0.49, 0.5, 0.9)).toBe('ok');
+    expect(computeSeverity(0.51, 0.5, 0.9)).toBe('warn');
+    expect(computeSeverity(0.91, 0.5, 0.9)).toBe('danger');
+  });
+
+  it('respects custom dangerThreshold', () => {
+    expect(computeSeverity(0.49, 0.5, 0.75)).toBe('ok');
+    expect(computeSeverity(0.6, 0.5, 0.75)).toBe('warn');
+    expect(computeSeverity(0.76, 0.5, 0.75)).toBe('danger');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Context component — color class flips at configured thresholds
+//
+// HoverCardRoot uses openDelay={0} inside Context, so after a pointerEnter
+// the card opens immediately; we advance fake timers by 0 to flush it.
+// ---------------------------------------------------------------------------
+
+function FullMeter(props: {
+  usedTokens: number;
+  maxTokens: number;
+  warnThreshold?: number;
+  dangerThreshold?: number;
+}) {
+  return (
+    <Context {...props}>
+      <ContextTrigger />
+      <ContextContent>
+        <ContextContentHeader />
+        <ContextContentBody />
+        <ContextContentFooter />
+      </ContextContent>
+    </Context>
+  );
+}
+
+/** Open the hover card so ContextContentHeader is in the DOM. */
+function openCard() {
+  // ContextTrigger renders HoverCardTrigger; the host wrapper is the parent of the button.
+  const btn = screen.getByRole('button');
+  fireEvent.pointerEnter(btn.parentElement!);
+  vi.advanceTimersByTime(0); // openDelay=0 → card opens immediately
+}
+
+describe('Context color thresholds', () => {
+  it('renders bg-primary bar below default warn threshold (< 70%)', () => {
+    render(() => <FullMeter usedTokens={69000} maxTokens={100000} />);
+    openCard();
+    expect(document.querySelector('.bg-primary')).toBeInTheDocument();
+  });
+
+  it('renders bg-yellow-400 bar between default warn (70%) and danger (90%) thresholds', () => {
+    render(() => <FullMeter usedTokens={80000} maxTokens={100000} />);
+    openCard();
+    expect(document.querySelector('.bg-yellow-400')).toBeInTheDocument();
+  });
+
+  it('renders bg-red-400 bar above default danger threshold (> 90%)', () => {
+    render(() => <FullMeter usedTokens={91000} maxTokens={100000} />);
+    openCard();
+    expect(document.querySelector('.bg-red-400')).toBeInTheDocument();
+  });
+
+  it('flips to warn colour at a custom warnThreshold of 0.5', () => {
+    render(() => <FullMeter usedTokens={51000} maxTokens={100000} warnThreshold={0.5} dangerThreshold={0.9} />);
+    openCard();
+    expect(document.querySelector('.bg-yellow-400')).toBeInTheDocument();
+  });
+
+  it('flips to danger colour at custom thresholds (warn 0.5, danger 0.75)', () => {
+    render(() => <FullMeter usedTokens={76000} maxTokens={100000} warnThreshold={0.5} dangerThreshold={0.75} />);
+    openCard();
+    expect(document.querySelector('.bg-red-400')).toBeInTheDocument();
+  });
+
+  it('stays green at 50% when custom warnThreshold is 0.6', () => {
+    render(() => <FullMeter usedTokens={50000} maxTokens={100000} warnThreshold={0.6} />);
+    openCard();
+    expect(document.querySelector('.bg-primary')).toBeInTheDocument();
+  });
+});

package/src/components/context.tsx

@@ -0,0 +1,363 @@
+import { type JSX, Show, createContext, createMemo, useContext } from 'solid-js';
+import { HoverCardRoot, HoverCardTrigger, HoverCardContent } from '../ui/hover-card';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+
+const ICON_RADIUS = 10;
+const ICON_VIEWBOX = 24;
+const ICON_CENTER = 12;
+const ICON_STROKE_WIDTH = 2;
+const PERCENT_MAX = 100;
+
+/** Default fraction (0–1) at which the meter transitions to the warning colour. */
+export const DEFAULT_WARN_THRESHOLD = 0.7;
+/** Default fraction (0–1) at which the meter transitions to the danger colour. */
+export const DEFAULT_DANGER_THRESHOLD = 0.9;
+
+/**
+ * Compute the severity level for a given usage fraction and thresholds.
+ * `pct` is a 0–1 fraction (e.g. `usedTokens / maxTokens`).
+ */
+export function computeSeverity(
+  pct: number,
+  warnThreshold = DEFAULT_WARN_THRESHOLD,
+  dangerThreshold = DEFAULT_DANGER_THRESHOLD,
+): ContextSeverity {
+  if (pct > dangerThreshold) return 'danger';
+  if (pct > warnThreshold) return 'warn';
+  return 'ok';
+}
+
+export type ContextSeverity = 'ok' | 'warn' | 'danger';
+
+interface ContextSchema {
+  usedTokens: number;
+  maxTokens: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cacheTokens?: number;
+  estimatedCost?: number;
+  /** Fraction (0–1) above which the meter turns yellow. Default 0.7. */
+  warnThreshold: number;
+  /** Fraction (0–1) above which the meter turns red. Default 0.9. */
+  dangerThreshold: number;
+}
+
+const ContextCtx = createContext<ContextSchema>();
+
+function useContextValue(): ContextSchema {
+  const ctx = useContext(ContextCtx);
+  if (!ctx) {
+    throw new Error('Context components must be used within Context');
+  }
+  return ctx;
+}
+
+const fmtCompact = new Intl.NumberFormat('en-US', { notation: 'compact' });
+const fmtPercent = new Intl.NumberFormat('en-US', { maximumFractionDigits: 1, style: 'percent' });
+const fmtCurrency = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' });
+
+// --- Root provider ---
+
+export interface ContextProps {
+  usedTokens: number;
+  maxTokens: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cacheTokens?: number;
+  estimatedCost?: number;
+  /**
+   * Fraction (0–1) above which the progress bar turns yellow.
+   * Defaults to `0.7` (70%).
+   */
+  warnThreshold?: number;
+  /**
+   * Fraction (0–1) above which the progress bar turns red.
+   * Defaults to `0.9` (90%).
+   */
+  dangerThreshold?: number;
+  children?: JSX.Element;
+}
+
+export function Context(props: ContextProps) {
+  const value = createMemo<ContextSchema>(() => ({
+    usedTokens: props.usedTokens,
+    maxTokens: props.maxTokens,
+    inputTokens: props.inputTokens,
+    outputTokens: props.outputTokens,
+    reasoningTokens: props.reasoningTokens,
+    cacheTokens: props.cacheTokens,
+    estimatedCost: props.estimatedCost,
+    warnThreshold: props.warnThreshold ?? DEFAULT_WARN_THRESHOLD,
+    dangerThreshold: props.dangerThreshold ?? DEFAULT_DANGER_THRESHOLD,
+  }));
+
+  return (
+    <ContextCtx.Provider value={value()}>
+      <HoverCardRoot openDelay={0}>
+        {props.children}
+      </HoverCardRoot>
+    </ContextCtx.Provider>
+  );
+}
+
+// --- Icon (internal) ---
+
+function ContextIcon() {
+  const ctx = useContextValue();
+  const circumference = 2 * Math.PI * ICON_RADIUS;
+  const usedPercent = createMemo(() => ctx.usedTokens / ctx.maxTokens);
+  const dashOffset = createMemo(() => circumference * (1 - usedPercent()));
+
+  return (
+    <svg
+      aria-label="Model context usage"
+      height="20"
+      role="img"
+      style={{ color: 'currentcolor' }}
+      viewBox={`0 0 ${ICON_VIEWBOX} ${ICON_VIEWBOX}`}
+      width="20"
+    >
+      <circle
+        cx={ICON_CENTER}
+        cy={ICON_CENTER}
+        fill="none"
+        opacity="0.25"
+        r={ICON_RADIUS}
+        stroke="currentColor"
+        stroke-width={ICON_STROKE_WIDTH}
+      />
+      <circle
+        cx={ICON_CENTER}
+        cy={ICON_CENTER}
+        fill="none"
+        opacity="0.7"
+        r={ICON_RADIUS}
+        stroke="currentColor"
+        stroke-dasharray={`${circumference} ${circumference}`}
+        stroke-dashoffset={dashOffset()}
+        stroke-linecap="round"
+        stroke-width={ICON_STROKE_WIDTH}
+        style={{ transform: 'rotate(-90deg)', 'transform-origin': 'center' }}
+      />
+    </svg>
+  );
+}
+
+// --- Trigger ---
+
+export interface ContextTriggerProps {
+  children?: JSX.Element;
+  class?: string;
+}
+
+export function ContextTrigger(props: ContextTriggerProps) {
+  const ctx = useContextValue();
+  const usedPercent = createMemo(() => ctx.usedTokens / ctx.maxTokens);
+  const renderedPercent = createMemo(() => fmtPercent.format(usedPercent()));
+
+  return (
+    <HoverCardTrigger>
+      <Show
+        when={!props.children}
+        fallback={props.children}
+      >
+        <Button type="button" variant="ghost" class={props.class}>
+          <span class="font-medium text-muted-foreground">{renderedPercent()}</span>
+          <ContextIcon />
+        </Button>
+      </Show>
+    </HoverCardTrigger>
+  );
+}
+
+// --- Content ---
+
+export interface ContextContentProps {
+  class?: string;
+  children?: JSX.Element;
+}
+
+export function ContextContent(props: ContextContentProps) {
+  return (
+    <HoverCardContent
+      class={cn(
+        'min-w-60 divide-y divide-border overflow-hidden',
+        props.class
+      )}
+    >
+      {props.children}
+    </HoverCardContent>
+  );
+}
+
+// --- Content Header ---
+
+export interface ContextContentHeaderProps {
+  class?: string;
+  children?: JSX.Element;
+}
+
+export function ContextContentHeader(props: ContextContentHeaderProps) {
+  const ctx = useContextValue();
+  const usedPercent = createMemo(() => ctx.usedTokens / ctx.maxTokens);
+  const displayPct = createMemo(() => fmtPercent.format(usedPercent()));
+  const used = createMemo(() => fmtCompact.format(ctx.usedTokens));
+  const total = createMemo(() => fmtCompact.format(ctx.maxTokens));
+  const barWidth = createMemo(() => `${Math.min(usedPercent() * PERCENT_MAX, PERCENT_MAX)}%`);
+
+  const severity = createMemo<ContextSeverity>(() => {
+    const pct = usedPercent();
+    if (pct > ctx.dangerThreshold) return 'danger';
+    if (pct > ctx.warnThreshold) return 'warn';
+    return 'ok';
+  });
+
+  const colorClass = createMemo(() => {
+    const s = severity();
+    if (s === 'danger') return 'bg-red-400';
+    if (s === 'warn') return 'bg-yellow-400';
+    return 'bg-primary';
+  });
+
+  return (
+    <div class={cn('w-full space-y-2 p-3', props.class)}>
+      <Show when={!props.children} fallback={props.children}>
+        <div class="flex items-center justify-between gap-3 text-xs">
+          <p>{displayPct()}</p>
+          <p class="font-mono text-muted-foreground">
+            {used()} / {total()}
+          </p>
+        </div>
+        <div class="space-y-2">
+          <div class="h-1.5 w-full rounded-full bg-muted overflow-hidden">
+            <div
+              class={cn('h-full rounded-full transition-all', colorClass())}
+              style={{ width: barWidth() }}
+            />
+          </div>
+        </div>
+      </Show>
+    </div>
+  );
+}
+
+// --- Content Body ---
+
+export interface ContextContentBodyProps {
+  class?: string;
+  children?: JSX.Element;
+}
+
+export function ContextContentBody(props: ContextContentBodyProps) {
+  return (
+    <div class={cn('w-full p-3', props.class)}>
+      {props.children}
+    </div>
+  );
+}
+
+// --- Content Footer ---
+
+export interface ContextContentFooterProps {
+  class?: string;
+  children?: JSX.Element;
+}
+
+export function ContextContentFooter(props: ContextContentFooterProps) {
+  const ctx = useContextValue();
+  const totalCost = createMemo(() =>
+    fmtCurrency.format(ctx.estimatedCost ?? 0)
+  );
+
+  return (
+    <div
+      class={cn(
+        'flex w-full items-center justify-between gap-3 bg-muted p-3 text-xs',
+        props.class
+      )}
+    >
+      <Show when={!props.children} fallback={props.children}>
+        <span class="text-muted-foreground">Total cost</span>
+        <span>{totalCost()}</span>
+      </Show>
+    </div>
+  );
+}
+
+// --- Token row helper ---
+
+function TokensDisplay(props: { tokens?: number }) {
+  return (
+    <span>
+      {props.tokens === undefined
+        ? '\u2014'
+        : fmtCompact.format(props.tokens)}
+    </span>
+  );
+}
+
+// --- Specialized usage rows ---
+
+export interface ContextUsageRowProps {
+  class?: string;
+  children?: JSX.Element;
+}
+
+export function ContextInputUsage(props: ContextUsageRowProps) {
+  const ctx = useContextValue();
+  return (
+    <Show when={props.children || ctx.inputTokens}>
+      <Show when={!props.children} fallback={props.children}>
+        <div class={cn('flex items-center justify-between text-xs', props.class)}>
+          <span class="text-muted-foreground">Input</span>
+          <TokensDisplay tokens={ctx.inputTokens} />
+        </div>
+      </Show>
+    </Show>
+  );
+}
+
+export function ContextOutputUsage(props: ContextUsageRowProps) {
+  const ctx = useContextValue();
+  return (
+    <Show when={props.children || ctx.outputTokens}>
+      <Show when={!props.children} fallback={props.children}>
+        <div class={cn('flex items-center justify-between text-xs', props.class)}>
+          <span class="text-muted-foreground">Output</span>
+          <TokensDisplay tokens={ctx.outputTokens} />
+        </div>
+      </Show>
+    </Show>
+  );
+}
+
+export function ContextReasoningUsage(props: ContextUsageRowProps) {
+  const ctx = useContextValue();
+  return (
+    <Show when={props.children || ctx.reasoningTokens}>
+      <Show when={!props.children} fallback={props.children}>
+        <div class={cn('flex items-center justify-between text-xs', props.class)}>
+          <span class="text-muted-foreground">Reasoning</span>
+          <TokensDisplay tokens={ctx.reasoningTokens} />
+        </div>
+      </Show>
+    </Show>
+  );
+}
+
+export function ContextCacheUsage(props: ContextUsageRowProps) {
+  const ctx = useContextValue();
+  return (
+    <Show when={props.children || ctx.cacheTokens}>
+      <Show when={!props.children} fallback={props.children}>
+        <div class={cn('flex items-center justify-between text-xs', props.class)}>
+          <span class="text-muted-foreground">Cache</span>
+          <TokensDisplay tokens={ctx.cacheTokens} />
+        </div>
+      </Show>
+    </Show>
+  );
+}

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

@@ -0,0 +1,125 @@
+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',
+  title: 'How to use SolidJS signals',
+  messageCount: 8,
+  lastMessageAt: '2026-04-10T12:00:00Z',
+  updatedAt: '2026-04-10T12:00:00Z',
+  scope: { type: 'document' as const },
+};
+
+/**
+ * A single selectable row in a conversation/chat list: title plus a message
+ * count, with an active (selected) state.
+ */
+const meta = {
+  title: 'Solid (Advanced)/Elements/ConversationItem',
+  component: ConversationItem,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      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'] },
+    },
+  },
+  argTypes: {
+    conversation: {
+      control: 'object',
+      description: 'The conversation summary (id, title, messageCount, scope, timestamps).',
+    },
+    isActive: {
+      control: 'boolean',
+      description: 'Whether this row is the currently selected conversation.',
+    },
+    onSelect: {
+      action: 'select',
+      description: 'Fired with the conversation id when the row is clicked.',
+      table: { category: 'Events' },
+    },
+  },
+  args: {
+    conversation: baseConversation,
+    isActive: false,
+    onSelect: fn(),
+  },
+  render: (args) => (
+    <div class="w-64">
+      <ConversationItem {...args} />
+    </div>
+  ),
+} satisfies Meta<typeof ConversationItem>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { ConversationItem } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — toggle `isActive` and edit the conversation object. */
+export const Playground: Story = {
+  ...src(`<ConversationItem conversation={conversation} isActive={false} onSelect={(id) => {}} />`),
+};
+
+export const Active: Story = {
+  args: { isActive: true },
+  ...src(`<ConversationItem conversation={conversation} isActive onSelect={(id) => {}} />`),
+};
+
+export const Inactive: Story = {
+  args: { isActive: false },
+  ...src(`<ConversationItem conversation={conversation} isActive={false} onSelect={(id) => {}} />`),
+};
+
+export const LongTitle: Story = {
+  args: {
+    conversation: {
+      ...baseConversation,
+      title: 'This is a very long conversation title that should be truncated with an ellipsis',
+    },
+  },
+  ...src(`<ConversationItem
+  conversation={{ ...conversation, title: 'A very long title…' }}
+  isActive={false}
+  onSelect={(id) => {}}
+/>`),
+};
+
+/** Several items stacked, one active — showcase. */
+export const MultipleItems: Story = {
+  render: (args: { onSelect: (id: string) => void }) => (
+    <div class="w-64 space-y-0.5">
+      <ConversationItem
+        conversation={{ ...baseConversation, id: '1', title: 'SolidJS reactive primitives' }}
+        isActive={true}
+        onSelect={args.onSelect}
+      />
+      <ConversationItem
+        conversation={{ ...baseConversation, id: '2', title: 'TypeScript generics guide', messageCount: 12 }}
+        isActive={false}
+        onSelect={args.onSelect}
+      />
+      <ConversationItem
+        conversation={{ ...baseConversation, id: '3', title: 'Tailwind CSS tips and tricks', messageCount: 3 }}
+        isActive={false}
+        onSelect={args.onSelect}
+      />
+    </div>
+  ),
+  ...src(`<div class="space-y-0.5">
+  <ConversationItem conversation={c1} isActive onSelect={onSelect} />
+  <ConversationItem conversation={c2} isActive={false} onSelect={onSelect} />
+  <ConversationItem conversation={c3} isActive={false} onSelect={onSelect} />
+</div>`),
+};

package/src/components/conversation-item.tsx

@@ -0,0 +1,16 @@
+import { splitProps } from 'solid-js';
+import { cn } from '../utils/cn';
+import type { ConversationSummary } from '../types';
+
+export interface ConversationItemProps { conversation: ConversationSummary; isActive: boolean; onSelect: (id: string) => void; class?: string; }
+
+export function ConversationItem(props: ConversationItemProps) {
+  const [local] = splitProps(props, ['conversation', 'isActive', 'onSelect', 'class']);
+  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-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>
+  );
+}