@steerable/agent-ui 0.2.3 → 0.2.4

package/src/cards/icons.tsx

@@ -0,0 +1,249 @@
+/**
+ * Inline SVG icons used by `@steerable/agent-ui/cards`.
+ *
+ * Defined here rather than pulling in `react-icons` / `lucide-react` so the
+ * cards package stays at exactly one runtime dep (`@steerable/agent-protocol`).
+ * Each icon has a tiny stroke-only path, parametrised by `size` and the usual
+ * SVG props so consumers can re-style via Tailwind / CSS.
+ */
+import * as React from 'react';
+
+type IconProps = React.SVGProps<SVGSVGElement> & { size?: number };
+
+function base({ size = 16, ...rest }: IconProps) {
+  return {
+    width: size,
+    height: size,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 1.75,
+    strokeLinecap: 'round' as const,
+    strokeLinejoin: 'round' as const,
+    ...rest,
+  };
+}
+
+export function CheckIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+export function ChevronDownIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  );
+}
+
+export function ChevronRightIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polyline points="9 18 15 12 9 6" />
+    </svg>
+  );
+}
+
+export function ChevronUpIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polyline points="18 15 12 9 6 15" />
+    </svg>
+  );
+}
+
+export function AlertIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z" />
+      <line x1="12" y1="9" x2="12" y2="13" />
+      <line x1="12" y1="17" x2="12.01" y2="17" />
+    </svg>
+  );
+}
+
+export function LoaderIcon(props: IconProps) {
+  return (
+    <svg {...base(props)} className={[props.className, 'animate-spin'].filter(Boolean).join(' ')}>
+      <line x1="12" y1="2" x2="12" y2="6" />
+      <line x1="12" y1="18" x2="12" y2="22" />
+      <line x1="4.93" y1="4.93" x2="7.76" y2="7.76" />
+      <line x1="16.24" y1="16.24" x2="19.07" y2="19.07" />
+      <line x1="2" y1="12" x2="6" y2="12" />
+      <line x1="18" y1="12" x2="22" y2="12" />
+      <line x1="4.93" y1="19.07" x2="7.76" y2="16.24" />
+      <line x1="16.24" y1="7.76" x2="19.07" y2="4.93" />
+    </svg>
+  );
+}
+
+export function GitBranchIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <line x1="6" y1="3" x2="6" y2="15" />
+      <circle cx="18" cy="6" r="3" />
+      <circle cx="6" cy="18" r="3" />
+      <path d="M18 9a9 9 0 0 1-9 9" />
+    </svg>
+  );
+}
+
+export function ListChecksIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polyline points="3 7 5 9 9 5" />
+      <polyline points="3 17 5 19 9 15" />
+      <line x1="13" y1="7" x2="21" y2="7" />
+      <line x1="13" y1="17" x2="21" y2="17" />
+    </svg>
+  );
+}
+
+export function TargetIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <circle cx="12" cy="12" r="10" />
+      <circle cx="12" cy="12" r="6" />
+      <circle cx="12" cy="12" r="2" />
+    </svg>
+  );
+}
+
+export function GlobeIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <circle cx="12" cy="12" r="10" />
+      <line x1="2" y1="12" x2="22" y2="12" />
+      <path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z" />
+    </svg>
+  );
+}
+
+export function ExternalLinkIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+      <polyline points="15 3 21 3 21 9" />
+      <line x1="10" y1="14" x2="21" y2="3" />
+    </svg>
+  );
+}
+
+export function MessageQuestionIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z" />
+      <path d="M9.5 9.5a2.5 2.5 0 1 1 3 2.5v1" />
+      <line x1="12" y1="15" x2="12.01" y2="15" />
+    </svg>
+  );
+}
+
+export function ArchiveIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polyline points="21 8 21 21 3 21 3 8" />
+      <rect x="1" y="3" width="22" height="5" />
+      <line x1="10" y1="12" x2="14" y2="12" />
+    </svg>
+  );
+}
+
+export function ChartIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <line x1="18" y1="20" x2="18" y2="10" />
+      <line x1="12" y1="20" x2="12" y2="4" />
+      <line x1="6" y1="20" x2="6" y2="14" />
+    </svg>
+  );
+}
+
+export function FlameIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M8.5 14.5A2.5 2.5 0 0 0 11 17v-3a2.5 2.5 0 1 1 0-5V6a3 3 0 0 0-3 3 3 3 0 0 0 .5 2.5C7.5 13 6 14.5 6 17a6 6 0 0 0 12 0c0-4-3-7-5-9 1.5 4-.5 5.5-2 6.5z" />
+    </svg>
+  );
+}
+
+export function ShieldIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M12 2 4 5v6c0 5 3.4 9.4 8 11 4.6-1.6 8-6 8-11V5l-8-3z" />
+    </svg>
+  );
+}
+
+export function ClockIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <circle cx="12" cy="12" r="10" />
+      <polyline points="12 6 12 12 16 14" />
+    </svg>
+  );
+}
+
+export function PlayIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polygon points="5 3 19 12 5 21 5 3" />
+    </svg>
+  );
+}
+
+export function StopIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <rect x="6" y="6" width="12" height="12" />
+    </svg>
+  );
+}
+
+export function ZapIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2" />
+    </svg>
+  );
+}
+
+export function ClipboardIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <rect x="9" y="2" width="6" height="4" rx="1" />
+      <path d="M9 4H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2h-3" />
+    </svg>
+  );
+}
+
+export function BookIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20" />
+      <path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z" />
+    </svg>
+  );
+}
+
+export function ThumbsUpIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M14 9V5a3 3 0 0 0-3-3l-4 9v11h11.28a2 2 0 0 0 2-1.7l1.38-9A2 2 0 0 0 19.66 9H14z" />
+      <line x1="7" y1="22" x2="7" y2="11" />
+    </svg>
+  );
+}
+
+export function PencilIcon(props: IconProps) {
+  return (
+    <svg {...base(props)}>
+      <path d="M12 20h9" />
+      <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z" />
+    </svg>
+  );
+}

package/src/cards/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `@steerable/agent-ui/cards`
+ *
+ * Subpath that bundles the 14 rich chat-block renderers used by deeppath /
+ * deeppath-agent / examples/web-shell. Every card consumes a typed `payload`
+ * sourced from the JSON schemas in `agent-protocol/spec/blocks/*.schema.json`
+ * (with TypeScript types generated by `pnpm gen`). All side-effects (submit,
+ * select, remediate, ...) flow through props -- apps stay in charge of state.
+ */
+export { OrchestrationPlanCard } from './OrchestrationPlanCard.js';
+export type {
+  OrchestrationPlanCardProps,
+  OrchestrationTaskStatus,
+} from './OrchestrationPlanCard.js';
+
+export { QuizCard } from './QuizCard.js';
+export type { QuizCardProps } from './QuizCard.js';
+
+export { CoverageReportCard } from './CoverageReportCard.js';
+export type { CoverageReportCardProps } from './CoverageReportCard.js';
+
+export { AnalysisDocumentCard } from './AnalysisDocumentCard.js';
+export type { AnalysisDocumentCardProps } from './AnalysisDocumentCard.js';
+
+export { ResearchPlanCard } from './ResearchPlanCard.js';
+export type { ResearchPlanCardProps } from './ResearchPlanCard.js';
+
+export { SuggestedRepliesCard } from './SuggestedRepliesCard.js';
+export type { SuggestedRepliesCardProps } from './SuggestedRepliesCard.js';
+
+export { AskUserQuestionsCard } from './AskUserQuestionsCard.js';
+export type { AskUserQuestionsCardProps } from './AskUserQuestionsCard.js';
+
+export { ThinkingProcessCard } from './ThinkingProcessCard.js';
+export type { ThinkingProcessCardProps } from './ThinkingProcessCard.js';
+
+export { PlanStepsCard } from './PlanStepsCard.js';
+export type { PlanStepsCardProps } from './PlanStepsCard.js';
+
+export { PlanSelectorCard } from './PlanSelectorCard.js';
+export type { PlanSelectorCardProps } from './PlanSelectorCard.js';
+
+export { SearchSourcesCard } from './SearchSourcesCard.js';
+export type { SearchSourcesCardProps } from './SearchSourcesCard.js';
+
+export { SummaryMessageCard } from './SummaryMessageCard.js';
+export type { SummaryMessageCardProps } from './SummaryMessageCard.js';
+
+export { ActionSegmentCard } from './ActionSegmentCard.js';
+export type { ActionSegmentCardProps } from './ActionSegmentCard.js';
+
+export { ToolExecutionCard } from './ToolExecutionCard.js';
+export type { ToolExecutionCardProps } from './ToolExecutionCard.js';

package/src/cards/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Version-agnostic helpers shared by the cards.
+ */
+import type * as React from 'react';
+
+/**
+ * Return type for `renderMarkdown` / `renderLabel` / etc. slots.
+ *
+ * We deliberately accept `unknown` so the prop type doesn't anchor consumers
+ * to a specific `@types/react` major (`React.ReactNode` is nominally
+ * different between v18 and v19 even though structurally compatible -- a
+ * consumer on React 19 cannot pass a function declared to return
+ * `React.ReactNode` (v19) into a framework prop that wants v18's
+ * `React.ReactNode`). The card then casts back to `React.ReactNode` at the
+ * render site, where TypeScript only cares about runtime shape and `unknown`
+ * widens harmlessly.
+ *
+ * For consumers, this just means: "return any valid React child".
+ */
+export type RenderSlotResult = unknown;
+
+/**
+ * Cast helper for use inside cards. Keeps render sites tidy.
+ */
+export function asReactNode(value: RenderSlotResult): React.ReactNode {
+  return value as React.ReactNode;
+}

package/src/components/AgentSelector.stories.tsx

@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import type { ChatAgent } from '@steerable/agent-protocol';
+import { AgentSelector } from './AgentSelector.js';
+
+const NOW = '2026-05-16T00:00:00Z';
+
+const baseAgents: ChatAgent[] = [
+  {
+    id: 'local-assistant',
+    name: 'Local Assistant',
+    icon: '🤖',
+    createdAt: NOW,
+    updatedAt: NOW,
+  },
+  {
+    id: 'researcher',
+    name: 'Researcher',
+    icon: '🔎',
+    createdAt: NOW,
+    updatedAt: NOW,
+  },
+  {
+    id: 'planner',
+    name: 'Planner',
+    icon: '🧭',
+    createdAt: NOW,
+    updatedAt: NOW,
+  },
+];
+
+const meta: Meta<typeof AgentSelector> = {
+  title: 'Components/AgentSelector',
+  component: AgentSelector,
+  parameters: {
+    layout: 'centered',
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    docs: {
+      description: {
+        component:
+          'Segmented selector for choosing the active chat agent. Supports keyboard navigation and custom rendering via `renderAgent`.',
+      },
+    },
+  },
+  args: {
+    agents: baseAgents,
+    selectedId: baseAgents[0].id,
+    onSelect: () => {},
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AgentSelector>;
+
+export const Default: Story = {};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+};
+
+export const SingleAgent: Story = {
+  args: {
+    agents: [baseAgents[0]],
+    selectedId: baseAgents[0].id,
+  },
+};
+
+export const LongNames: Story = {
+  args: {
+    agents: [
+      {
+        id: 'very-long',
+        name: 'This is a very long agent name that should truncate gracefully',
+        icon: '🧪',
+        createdAt: NOW,
+        updatedAt: NOW,
+      },
+      {
+        id: 'also-long',
+        name: 'Another very long and descriptive specialist agent name',
+        icon: '🛠️',
+        createdAt: NOW,
+        updatedAt: NOW,
+      },
+    ],
+    selectedId: 'very-long',
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    loading: true,
+    agents: [],
+  },
+};
+
+export const Interactive: Story = {
+  render: (args) => {
+    const InteractiveSelector = () => {
+      const [selectedId, setSelectedId] = useState(args.selectedId);
+      return (
+        <AgentSelector
+          {...args}
+          selectedId={selectedId}
+          onSelect={setSelectedId}
+        />
+      );
+    };
+    return <InteractiveSelector />;
+  },
+};

package/src/components/AgentSelector.test.tsx

@@ -0,0 +1,70 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { ChatAgent } from '@steerable/agent-protocol';
+import { AgentSelector } from './AgentSelector';
+
+const NOW = '2026-05-16T00:00:00Z';
+const AGENTS: ChatAgent[] = [
+  { id: 'a1', name: 'Alpha', createdAt: NOW, updatedAt: NOW },
+  { id: 'a2', name: 'Beta', createdAt: NOW, updatedAt: NOW },
+  { id: 'a3', name: 'Gamma', createdAt: NOW, updatedAt: NOW },
+];
+
+describe('AgentSelector', () => {
+  it('renders all agents and marks the selected radio', () => {
+    render(
+      <AgentSelector agents={AGENTS} selectedId="a2" onSelect={() => {}} />,
+    );
+
+    expect(
+      screen.getByRole('radio', { name: 'Alpha' }).getAttribute('aria-checked'),
+    ).toBe('false');
+    expect(
+      screen.getByRole('radio', { name: 'Beta' }).getAttribute('aria-checked'),
+    ).toBe('true');
+    expect(
+      screen.getByRole('radio', { name: 'Gamma' }).getAttribute('aria-checked'),
+    ).toBe('false');
+  });
+
+  it('calls onSelect on click', () => {
+    const onSelect = vi.fn();
+    render(<AgentSelector agents={AGENTS} selectedId="a1" onSelect={onSelect} />);
+
+    fireEvent.click(screen.getByRole('radio', { name: 'Gamma' }));
+    expect(onSelect).toHaveBeenCalledWith('a3');
+  });
+
+  it('supports keyboard navigation (Arrow, Home, End)', () => {
+    const onSelect = vi.fn();
+    render(<AgentSelector agents={AGENTS} selectedId="a2" onSelect={onSelect} />);
+
+    const beta = screen.getByRole('radio', { name: 'Beta' });
+    fireEvent.keyDown(beta, { key: 'ArrowRight' });
+    fireEvent.keyDown(beta, { key: 'ArrowLeft' });
+    fireEvent.keyDown(beta, { key: 'Home' });
+    fireEvent.keyDown(beta, { key: 'End' });
+
+    expect(onSelect).toHaveBeenNthCalledWith(1, 'a3');
+    expect(onSelect).toHaveBeenNthCalledWith(2, 'a1');
+    expect(onSelect).toHaveBeenNthCalledWith(3, 'a1');
+    expect(onSelect).toHaveBeenNthCalledWith(4, 'a3');
+  });
+
+  it('does not call onSelect when disabled', () => {
+    const onSelect = vi.fn();
+    render(
+      <AgentSelector
+        agents={AGENTS}
+        selectedId="a1"
+        onSelect={onSelect}
+        disabled
+      />,
+    );
+
+    const alpha = screen.getByRole('radio', { name: 'Alpha' });
+    fireEvent.click(alpha);
+    fireEvent.keyDown(alpha, { key: 'ArrowRight' });
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+});

package/src/components/AgentSelector.tsx

@@ -0,0 +1,147 @@
+import { useMemo } from 'react';
+import type { ChatAgent } from '@steerable/agent-protocol';
+import { cn } from './cn.js';
+
+export interface AgentSelectorProps {
+  agents: ChatAgent[];
+  selectedId: string;
+  onSelect: (id: string) => void;
+  renderAgent?: (agent: ChatAgent, state: { selected: boolean }) => React.ReactNode;
+  className?: string;
+  disabled?: boolean;
+  loading?: boolean;
+}
+
+function defaultRenderAgent(agent: ChatAgent) {
+  return (
+    <span className="inline-flex min-w-0 items-center gap-1.5">
+      {agent.icon ? (
+        <span aria-hidden className="text-sm leading-none">
+          {agent.icon}
+        </span>
+      ) : null}
+      <span className="truncate">{agent.name}</span>
+    </span>
+  );
+}
+
+/**
+ * AgentSelector
+ *
+ * Keyboard support:
+ * - ArrowLeft / ArrowUp: move selection to previous agent
+ * - ArrowRight / ArrowDown: move selection to next agent
+ * - Home / End: jump to first / last agent
+ * - Enter / Space: select focused agent (native button behavior)
+ */
+export function AgentSelector(props: AgentSelectorProps) {
+  const {
+    agents,
+    selectedId,
+    onSelect,
+    renderAgent = defaultRenderAgent,
+    className,
+    disabled = false,
+    loading = false,
+  } = props;
+
+  const selectedIndex = useMemo(
+    () => agents.findIndex((a) => a.id === selectedId),
+    [agents, selectedId],
+  );
+
+  if (loading) {
+    return (
+      <div
+        className={cn(
+          'inline-flex h-9 items-center rounded-agent-md border border-agent-border bg-agent-canvas px-3 text-sm text-agent-muted-foreground',
+          className,
+        )}
+        aria-live="polite"
+      >
+        Loading agents…
+      </div>
+    );
+  }
+
+  if (agents.length === 0) {
+    return (
+      <div
+        className={cn(
+          'inline-flex h-9 items-center rounded-agent-md border border-agent-border bg-agent-canvas px-3 text-sm text-agent-muted-foreground',
+          className,
+        )}
+      >
+        No agents
+      </div>
+    );
+  }
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label="Agent selector"
+      className={cn(
+        'inline-flex max-w-full items-center gap-1 rounded-agent-lg border border-agent-border bg-agent-canvas p-1',
+        className,
+      )}
+    >
+      {agents.map((agent, index) => {
+        const selected = agent.id === selectedId;
+        const tabIndex =
+          selected
+            ? 0
+            : selectedIndex >= 0
+              ? -1
+              : index === 0
+                ? 0
+                : -1;
+
+        return (
+          <button
+            key={agent.id}
+            type="button"
+            role="radio"
+            aria-checked={selected}
+            aria-label={agent.name}
+            tabIndex={tabIndex}
+            disabled={disabled}
+            onClick={() => onSelect(agent.id)}
+            onKeyDown={(event) => {
+              if (disabled) return;
+
+              let nextIndex = index;
+              if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+                nextIndex = Math.min(agents.length - 1, index + 1);
+              } else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+                nextIndex = Math.max(0, index - 1);
+              } else if (event.key === 'Home') {
+                nextIndex = 0;
+              } else if (event.key === 'End') {
+                nextIndex = agents.length - 1;
+              } else {
+                return;
+              }
+
+              if (nextIndex !== index) {
+                event.preventDefault();
+                const next = agents[nextIndex];
+                onSelect(next.id);
+              }
+            }}
+            className={cn(
+              'inline-flex h-7 min-w-0 max-w-[220px] items-center rounded-agent-md px-2.5 text-sm transition-colors',
+              selected
+                ? 'bg-agent-accent text-agent-accent-foreground'
+                : 'text-agent-foreground hover:bg-agent-muted',
+              disabled && 'cursor-not-allowed opacity-50',
+            )}
+            title={agent.name}
+          >
+            {renderAgent(agent, { selected })}
+          </button>
+        );
+      })}
+    </div>
+  );
+}