agent-canvas 0.1.16 → 0.1.18

package/skills/canvas/components.md

@@ -1,403 +0,0 @@
-# Component Reference
-
-All components are available globally in canvas JSX — no imports needed.
-For inline styling use `style={{ ... }}`. Tailwind classes are NOT available.
-
-## Theming
-
-**Never hardcode hex colors** — canvas supports light/dark themes. Use CSS variables in `style={{ }}`:
-
-- **Text:** `--color-text-primary`, `--color-text-secondary`, `--color-text-tertiary`, `--color-text-code`, `--color-text-inverse`
-- **Backgrounds:** `--color-bg-base`, `--color-bg-surface`, `--color-bg-elevated`, `--color-bg-code`, `--color-bg-input`
-- **Accents:** `--color-accent-{green,amber,red,blue}`, `--color-accent-{green,amber,red,blue}-muted`
-- **Borders:** `--color-border-subtle`, `--color-border-medium`, `--color-border-hover`
-- **Fonts:** `--font-heading`, `--font-body`, `--font-mono`
-
-```jsx
-<span style={{ color: 'var(--color-text-tertiary)', fontSize: '0.75rem' }}>meta text</span>
-```
-
----
-
-## Layout
-
-### `<Section title="string">`
-
-Top-level grouping. Rendered as a serif heading with generous spacing.
-Collapsible (chevron appears on hover). Children are the section body.
-
-```jsx
-<Section title="Phase 1: Data Migration">
-  A brief description of this section.
-  
-  {/* Items, callouts, code blocks, diagrams, etc. */}
-</Section>
-```
-
-**Props:**
-- `title` (string, required) — section heading, rendered in Instrument Serif
-- `collapsed` (boolean, default false) — start collapsed
-
----
-
-### `<Item id="string" label="string">`
-
-The primary content block. A flexible card-like row used for tasks, findings, requirements, observations, options — anything that has a title and details.
-
-Previously called "Task" — Item is the generalized version. It's a labeled sub-section with an optional status dot, badge, and children for details.
-
-```jsx
-{/* As a plan task */}
-<Item id="migrate-db" label="Run database migration" badge="todo">
-  Execute the migration script against staging first.
-  <CodeBlock language="bash">npm run migrate:staging</CodeBlock>
-</Item>
-
-{/* As a review finding */}
-<Item id="finding-1" label="Missing null check in auth handler" badge="critical" badgeVariant="danger">
-  The handler doesn't check for missing tokens.
-  <FilePreview path="src/auth.ts" lines={[42, 48]} />
-</Item>
-
-{/* As a requirement */}
-<Item id="req-auth" label="JWT authentication" badge="must-have" badgeVariant="danger">
-  All API endpoints must require a valid JWT token.
-</Item>
-
-{/* As an architecture component */}
-<Item label="API Gateway" badge="core" badgeVariant="info">
-  Routes requests to downstream services. Handles rate limiting.
-</Item>
-```
-
-**Props:**
-- `id` (string) — unique ID. Required if the item should be individually addressable in feedback. Optional for informational items.
-- `label` (string, required) — item title, rendered in Inter 600
-- `badge` (string) — short label shown as a small tag. Freeform text.
-- `badgeVariant` ("default" | "success" | "warning" | "danger" | "info") — badge color. Default is neutral gray.
-- `status` ("todo" | "done" | "blocked" | "in-progress") — shows a colored dot. Alternative to badge for plan-style items.
-
-**Badge vs Status**: Use `status` for things with a workflow state (tasks in a plan). Use `badge` for categorical labels (requirement priority, review severity, component type). You can use both on the same Item if needed.
-
-**Children**: Any content — text, components, code blocks, file previews, nested items. Rendered indented under the label.
-
----
-
-## Code & Files
-
-### `<FilePreview path="string">`
-
-Shows a syntax-highlighted preview of a project file. The daemon serves the file content from the project root.
-
-```jsx
-<FilePreview path="src/auth/middleware.ts" />
-<FilePreview path="src/auth/middleware.ts" lines={[42, 87]} />
-```
-
-**Props:**
-- `path` (string, required) — relative to project root
-- `lines` ([number, number]) — line range to show. Omit for full file.
-
-### `<CodeBlock language="string">`
-
-Inline code block with syntax highlighting. For code that's part of the narrative, not from a file on disk.
-
-```jsx
-<CodeBlock language="typescript">
-  interface User {
-    id: string;
-    email: string;
-  }
-</CodeBlock>
-```
-
-**Props:**
-- `language` (string) — syntax highlighting language
-
-### `<Markdown>`
-
-Renders markdown content with full GFM support (headings, lists, tables, code blocks, links, etc.). Two modes:
-
-**Inline source** — markdown as children:
-```jsx
-<Markdown>{`
-# Summary
-
-This is **bold** and *italic*. Here's a list:
-
-- First item
-- Second item
-  - Nested item
-
-\`\`\`typescript
-const x = 42;
-\`\`\`
-`}</Markdown>
-```
-
-**File reference** — loads file content at compile time:
-```jsx
-<Markdown file="docs/architecture.md" />
-<Markdown file="CHANGELOG.md" />
-```
-
-**Props:**
-- `file` (string) — path relative to project root. Content is resolved at compile time.
-- Children (string) — inline markdown source. Used when `file` is not specified.
-
-### `<ImageView src="string">`
-
-Displays an image from the project directory.
-
-```jsx
-<ImageView src="docs/architecture.png" />
-<ImageView src="screenshots/before.png" alt="Before refactor" caption="Current state" width={600} />
-```
-
-### `<Diff before="string" after="string">`
-
-Shows a diff view between two code snippets.
-
-```jsx
-<Diff language="typescript"
-  before={`function auth(req) {\n  return true;\n}`}
-  after={`function auth(req) {\n  const token = req.headers.authorization;\n  if (!token) throw new Error('Unauthorized');\n  return verify(token);\n}`}
-/>
-```
-
-**Props:**
-- `before` (string, required) — original code
-- `after` (string, required) — modified code
-- `language` (string) — syntax highlighting language
-
----
-
-## Content
-
-### `<Callout type="string">`
-
-Highlighted information block. Background-tinted, no border.
-
-```jsx
-<Callout type="warning">
-  This will invalidate all existing sessions. Plan a maintenance window.
-</Callout>
-```
-
-**Props:**
-- `type` ("info" | "warning" | "danger" | "tip") — determines color and icon
-
-### `<Note>`
-
-Softer than Callout. For asides, context, non-critical info.
-
-```jsx
-<Note>
-  This pattern is also used in the payment service — see src/payments/auth.ts.
-</Note>
-```
-
-### `<Priority level="string" />`
-
-Inline badge. Use inside Item labels or body text.
-
-```jsx
-<Item label="Fix the race condition">
-  <Priority level="high" /> This causes data corruption under load.
-</Item>
-```
-
-**Props:**
-- `level` ("high" | "medium" | "low")
-
----
-
-## Data Display
-
-### `<Table headers={[...]} rows={[[...], ...]} />`
-
-Simple data table.
-
-```jsx
-<Table 
-  headers={["Endpoint", "Method", "Auth"]} 
-  rows={[
-    ["/users", "GET", "Required"],
-    ["/users/:id", "PUT", "Owner only"],
-    ["/health", "GET", "None"],
-  ]} 
-/>
-```
-
-### `<Checklist items={[...]} />`
-
-Visual checklist. Read-only display (feedback via annotations).
-
-```jsx
-<Checklist items={[
-  { label: "Run migration on staging", checked: true },
-  { label: "Verify data integrity", checked: false },
-  { label: "Update API docs", checked: false },
-]} />
-```
-
-### `<Mermaid>`
-
-Renders a Mermaid diagram. Supports flowchart, sequence, ER, gantt, pie, etc.
-The daemon bundles mermaid.js with a custom dark theme matching Canvas colors.
-
-```jsx
-<Mermaid>{`
-  graph TD
-    A[Client] -->|HTTP| B(API Gateway)
-    B --> C{Auth?}
-    C -->|Valid| D[Service]
-    C -->|Invalid| E[401 Response]
-`}</Mermaid>
-```
-
-For complex diagrams, prefer Mermaid over raw SVG. Use raw `<svg>` only when Mermaid can't express what you need (custom visual layouts, non-standard diagrams).
-
----
-
-## Interactive (User Input)
-
-Interactive components collect structured responses. They appear in feedback as `[component-id]: value`. Each has an optional "Add note" affordance for extra context.
-
-### `<Choice id="string" label="string" options={[...]} />`
-
-Single-select radio group.
-
-```jsx
-<Choice id="db-choice" label="Which database?" required
-  options={["PostgreSQL", "SQLite", "MongoDB"]} />
-```
-
-### `<MultiChoice id="string" label="string" options={[...]} />`
-
-Multi-select checkboxes.
-
-```jsx
-<MultiChoice id="affected-areas" label="Which areas need changes?" required
-  options={["Models", "API", "Frontend", "Tests"]} />
-```
-
-### `<UserInput id="string" label="string" />`
-
-Free text input.
-
-```jsx
-<UserInput id="constraints" label="Any constraints I should know about?" 
-  placeholder="e.g. must work with existing Redis setup" required />
-```
-
-### `<RangeInput id="string" label="string" />`
-
-Slider for numeric ranges or scales.
-
-```jsx
-<RangeInput id="effort-tolerance" label="How much refactoring is acceptable?"
-  min={1} max={5} minLabel="Minimal changes" maxLabel="Full rewrite OK" required />
-```
-
-**Common props for all interactive components:**
-- `id` (string, required) — unique, used as key in feedback
-- `label` (string, required) — question text
-- `required` (boolean) — prevents submit until answered
-- `placeholder` (string) — hint text (UserInput only)
-
----
-
-## Programmatic Feedback — `useFeedback`
-
-Hook for custom components to contribute computed/derived data to the feedback response. Use when built-in interactive components (`Choice`, `UserInput`, etc.) don't cover your needs.
-
-```jsx
-useFeedback(id: string, markdown: string, options?: { label?: string; required?: boolean })
-```
-
-**Props:**
-- `id` (string, required) — unique feedback entry identifier
-- `markdown` (string, required) — markdown included in feedback, re-evaluated each render
-- `options.label` — display label in feedback preview
-- `options.required` — blocks submit while markdown is empty
-
-Registers on mount, updates on change, unregisters on unmount.
-
-```jsx
-function ProConList() {
-  const [pros, setPros] = React.useState(["Fast builds"]);
-  const [cons, setCons] = React.useState(["New runtime"]);
-
-  useFeedback(
-    "pro-con",
-    `**Pros:** ${pros.join(", ")}\n**Cons:** ${cons.join(", ")}`,
-    { label: "Pro/Con Analysis" },
-  );
-
-  return <div>{/* UI for managing pros/cons */}</div>;
-}
-```
-
----
-
-## Custom Components
-
-When you use the full module format (`export default function Canvas()`), you can define custom helper components:
-
-```jsx
-function Metric({ label, value, trend }) {
-  const color = trend === 'up' ? 'var(--color-accent-green)' : trend === 'down' ? 'var(--color-accent-red)' : 'var(--color-text-secondary)';
-  return (
-    <div style={{ display: 'flex', gap: 12, alignItems: 'baseline' }}>
-      <span style={{ color: 'var(--color-text-tertiary)', fontSize: '0.75rem' }}>{label}</span>
-      <span style={{ color, fontSize: '1.25rem', fontWeight: 600 }}>{value}</span>
-    </div>
-  );
-}
-
-export default function Canvas() {
-  return (
-    <Section title="Performance Summary">
-      <Metric label="P95 Latency" value="42ms" trend="down" />
-      <Metric label="Error Rate" value="0.3%" trend="up" />
-      <Metric label="Throughput" value="1.2k rps" trend="up" />
-    </Section>
-  );
-}
-```
-
-Standard components remain available without import even in full module format.
-
----
-
-## Diagrams with Raw SVG
-
-For custom visuals that Mermaid can't express, write `<svg>` directly.
-Use CSS variables for colors to match the theme automatically:
-
-```jsx
-<svg viewBox="0 0 400 200" style={{ width: '100%', maxWidth: 400 }}>
-  <rect x="10" y="10" width="120" height="50" rx="8"
-        fill="var(--color-accent-blue-muted)" stroke="var(--color-accent-blue)" strokeOpacity="0.3" />
-  <text x="70" y="40" textAnchor="middle" fill="var(--color-text-primary)" fontSize="13"
-        fontFamily="var(--font-body)">API Gateway</text>
-
-  <line x1="130" y1="35" x2="180" y2="35" stroke="var(--color-text-tertiary)" strokeWidth="1.5"
-        markerEnd="url(#arrow)" />
-
-  <rect x="180" y="10" width="120" height="50" rx="8"
-        fill="var(--color-accent-green-muted)" stroke="var(--color-accent-green)" strokeOpacity="0.3" />
-  <text x="240" y="40" textAnchor="middle" fill="var(--color-text-primary)" fontSize="13"
-        fontFamily="var(--font-body)">Auth Service</text>
-
-  <defs>
-    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6"
-            orient="auto-start-reverse">
-      <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--color-text-tertiary)" />
-    </marker>
-  </defs>
-</svg>
-```
-
-Keep SVG diagrams simple. For anything with more than ~5 nodes, prefer Mermaid.