@you-agent-factory/components 0.0.0

package/docs/charts.md

@@ -0,0 +1,325 @@
+# Charts
+
+Domain-neutral chart presentation primitives built on [Recharts](https://recharts.org/).
+Import chart components from `@you-agent-factory/components/charts`. The package
+owns markup, tokens, accessible chart chrome, tooltip and legend content, and
+generic state panels. Host applications own data fetching, domain series
+generation, localized copy, and semantic color mapping.
+
+## Install and imports
+
+Recharts is a regular dependency of `@you-agent-factory/components`. Host apps
+that render charts should also depend on `recharts` so TypeScript can resolve
+Recharts child components (`LineChart`, `Line`, `XAxis`, and so on).
+
+```ts
+import {
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartStatePanel,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+  type ChartPresentation,
+  type ChartStatePanelProps,
+  type ChartStateStatus,
+} from "@you-agent-factory/components/charts";
+import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
+```
+
+Import package styles once in your host CSS before rendering charts:
+
+```css
+@import "@you-agent-factory/components/styles.css";
+```
+
+## Minimal Recharts composition
+
+`ChartContainer` wraps a Recharts chart, exposes an accessible chart region,
+and injects CSS color variables from your config. Series strokes and fills
+reference those variables.
+
+```tsx
+const chartConfig: ChartConfig = {
+  alpha: { color: "#3366cc", label: "Alpha series" },
+  beta: { color: "#cc6633", label: "Beta series" },
+};
+
+const chartData = [
+  { alpha: 4, beta: 2, tick: 1 },
+  { alpha: 6, beta: 3, tick: 2 },
+  { alpha: 5, beta: 4, tick: 3 },
+];
+
+function ThroughputChart() {
+  return (
+    <ChartContainer config={chartConfig} title="Sample throughput chart">
+      <LineChart data={chartData}>
+        <CartesianGrid vertical={false} />
+        <XAxis dataKey="tick" />
+        <YAxis />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Line dataKey="alpha" stroke="var(--color-alpha)" type="monotone" />
+        <Line dataKey="beta" stroke="var(--color-beta)" type="monotone" />
+      </LineChart>
+    </ChartContainer>
+  );
+}
+```
+
+The container renders `role="img"` with `aria-label` set from the required
+`title` prop. Recharts children read `--color-<seriesKey>` variables that
+`ChartContainer` derives from `config` entries.
+
+## Chart config
+
+`ChartConfig` is a record of series keys to `ChartConfigEntry` objects:
+
+| Field   | Purpose |
+| ------- | ------- |
+| `color` | Hex or CSS color used for the `--color-<key>` variable and legend swatches |
+| `label` | Human-readable series name shown in tooltips and legends |
+
+```ts
+const chartConfig: ChartConfig = {
+  queued: { color: "#5c6bc0", label: "Queued work" },
+  completed: { color: "#43a047", label: "Completed work" },
+};
+```
+
+Map domain data into `ChartConfig` in the host app. The chart package does not
+import work, session, provider, outcome, dashboard, or generated API types.
+Dashboard work-outcome charts, for example, keep semantic role definitions and
+series generation in dashboard feature code and pass a prepared config into
+`ChartContainer`.
+
+## Presentation: standalone versus embedded
+
+`ChartPresentation` is `"standalone"` (default) or `"embedded"`.
+
+- **Standalone** — Fixed-height bordered card (`h-[18rem]`) suited to docs,
+  Storybook, and full-width dashboard panels.
+- **Embedded** — Flex child that fills available height and width inside a
+  parent layout (for example an information card or split pane).
+
+```tsx
+<ChartContainer
+  config={chartConfig}
+  presentation="embedded"
+  title="Embedded throughput chart"
+>
+  {/* Recharts children */}
+</ChartContainer>
+```
+
+Both presentations set `data-chart-presentation` on the root element for
+testing and layout hooks.
+
+## Tooltip and legend content
+
+`ChartTooltip` is the Recharts `Tooltip` export. Pass `ChartTooltipContent` as
+the `content` render prop so labels and swatches resolve from `ChartConfig`:
+
+```tsx
+<ChartTooltip content={<ChartTooltipContent />} />
+```
+
+`ChartLegend` is the Recharts `Legend` export. For a compact footer legend
+outside the Recharts tree, render `ChartLegendContent` in `ChartContainer`'s
+`footer` prop and supply `payload` yourself:
+
+```tsx
+<ChartContainer
+  config={chartConfig}
+  footer={
+    <ChartLegendContent
+      payload={[
+        {
+          color: chartConfig.alpha.color,
+          dataKey: "alpha",
+          type: "line",
+          value: chartConfig.alpha.label,
+        },
+      ]}
+    />
+  }
+  title="Chart with footer legend"
+>
+  {/* Recharts children */}
+</ChartContainer>
+```
+
+Optional `ChartContainer` props:
+
+| Prop | Purpose |
+| ---- | ------- |
+| `footer` | Content below the chart surface (typical home for `ChartLegendContent`) |
+| `overlay` | Non-interactive overlay inside the chart region |
+| `interactionAttributes` | Extra attributes on the chart root (for example drag-to-zoom handlers owned by the host) |
+| `rootAttributes` | Additional `data-*` or `aria-*` attributes on the chart root |
+| `className` / `style` | Host styling overrides |
+
+## Caller-owned legend state
+
+Legend toggles are optional. When `onToggleSeries` is provided,
+`ChartLegendContent` renders keyboard-focusable buttons with `aria-pressed`
+reflecting visibility. The package does not store hidden-series state; the host
+owns a `Set<string>` (or equivalent) and updates it in the toggle callback.
+
+```tsx
+import { useState } from "react";
+
+function InteractiveLegendChart() {
+  const [hiddenSeries, setHiddenSeries] = useState<ReadonlySet<string>>(
+    () => new Set(),
+  );
+
+  const handleToggleSeries = (key: string) => {
+    setHiddenSeries((current) => {
+      const next = new Set(current);
+      if (next.has(key)) {
+        next.delete(key);
+      } else {
+        next.add(key);
+      }
+      return next;
+    });
+  };
+
+  return (
+    <ChartContainer
+      config={chartConfig}
+      footer={
+        <ChartLegendContent
+          getToggleLabel={(label, hidden) =>
+            hidden ? `Show ${label}` : `Hide ${label}`
+          }
+          hiddenSeries={hiddenSeries}
+          onToggleSeries={handleToggleSeries}
+          payload={legendPayload}
+        />
+      }
+      title="Interactive legend chart"
+    >
+      <LineChart data={chartData}>
+        {!hiddenSeries.has("alpha") ? (
+          <Line dataKey="alpha" stroke="var(--color-alpha)" type="monotone" />
+        ) : null}
+        {!hiddenSeries.has("beta") ? (
+          <Line dataKey="beta" stroke="var(--color-beta)" type="monotone" />
+        ) : null}
+      </LineChart>
+    </ChartContainer>
+  );
+}
+```
+
+Filter Recharts series in the host based on `hiddenSeries`. Use
+`getToggleLabel` for accessible toggle names when the default label is not
+sufficient.
+
+## Chart state panels
+
+Use `ChartStatePanel` when data is not ready for a chart. The `status` prop is
+one of `"loading"`, `"empty"`, `"error"`, or `"success"`. Titles,
+descriptions, and optional actions are caller-supplied; the package does not
+ship product copy.
+
+| Prop | Purpose |
+| ---- | ------- |
+| `status` | Panel state (`loading`, `empty`, `error`, `success`) |
+| `title` | Heading text (`<h3>`) |
+| `description` | Supporting copy |
+| `action` | Optional retry or navigation control |
+| `presentation` | `"standalone"` (dashed bordered shell) or `"embedded"` (fits inside a parent card) |
+
+Accessibility:
+
+- `error` uses `role="alert"` and `aria-live="assertive"`.
+- Other states use `role="status"` and `aria-live="polite"`.
+- `loading` sets `aria-busy` and shows a skeleton without relying on color
+  alone.
+
+### Loading
+
+```tsx
+<ChartStatePanel
+  description="Waiting for chart data to load."
+  status="loading"
+  title="Loading chart data"
+/>
+```
+
+### Empty
+
+```tsx
+<ChartStatePanel
+  description="No data points are available for this range."
+  status="empty"
+  title="No chart data"
+/>
+```
+
+### Error
+
+```tsx
+<ChartStatePanel
+  action={<button type="button">Retry chart load</button>}
+  description="The chart request failed. Try again later."
+  status="error"
+  title="Unable to load chart"
+/>
+```
+
+### Success
+
+```tsx
+<ChartStatePanel
+  description="The chart finished loading successfully."
+  status="success"
+  title="Chart ready"
+/>
+```
+
+### Embedded state in a narrow layout
+
+```tsx
+<div className="w-64 rounded-2xl border border-outline p-4">
+  <ChartStatePanel
+    description="No data points are available for this range."
+    presentation="embedded"
+    status="empty"
+    title="No chart data"
+  />
+</div>
+```
+
+Render a state panel instead of `ChartContainer` when the host determines data
+is loading, empty, invalid, or failed. Do not embed domain fetching logic inside
+the chart package.
+
+## Host application responsibilities
+
+The chart package is presentation-only. Host applications own:
+
+| Responsibility | Examples |
+| -------------- | -------- |
+| Data fetching | API calls, caching, refresh, and error handling |
+| Domain series generation | Aggregating work outcomes, time ranges, and metric keys into `chartData` rows |
+| Localized copy | Titles, descriptions, axis labels, and toggle labels passed as props |
+| Semantic styling | Mapping domain roles (queued, completed, failed, and so on) to colors and Recharts class names before building `ChartConfig` |
+
+The dashboard work-outcome feature keeps `chart-contract.ts` and
+`buildWorkChartData` for semantic colors and deterministic series mapping, then
+imports generic primitives from `@you-agent-factory/components/charts` for
+rendering. Follow the same boundary in other apps: prepare config and data in
+feature code, render with package chart components.
+
+## Storybook and tests
+
+Domain-neutral Storybook examples live under `src/charts/*.stories.tsx`.
+Package tests in `src/charts/chart.test.tsx` and
+`chart-state-panel.test.tsx` render charts and state panels without dashboard
+providers or fixtures. See those files for copy-paste-friendly neutral data
+(`chart-story-fixtures.ts`).

package/docs/data-display-code-panel.md

@@ -0,0 +1,120 @@
+# CodePanel
+
+Contained `<pre>` surface for generated scripts, logs, and diagnostic output.
+`CodePanel` keeps long single-line and multi-line content inside the panel
+without causing page-level horizontal overflow or overlapping header controls.
+
+## Import
+
+```ts
+import { CodePanel } from "@you-agent-factory/components";
+```
+
+Category entrypoint:
+
+```ts
+import { CodePanel } from "@you-agent-factory/components/data-display";
+```
+
+## Long-content containment
+
+`CodePanel` applies layout classes that bound width and overflow at the panel
+boundary:
+
+- `min-w-0 w-full max-w-full` — shrink inside flex/grid parents instead of
+  forcing page overflow
+- `overflow-x-auto` — horizontal scroll for unbreakable tokens when wrapping is
+  insufficient
+- `whitespace-pre-wrap` and `[overflow-wrap:anywhere]` — wrap long single lines
+  inside the panel
+- `font-mono text-code-medium text-code` — package code typography tokens
+
+Place labels and action buttons in a sibling header row with `flex min-w-0` and
+`shrink-0` on controls so long code does not overlap panel chrome.
+
+## Vertical scrolling
+
+Set `maxHeight` when multi-line blocks should scroll inside the panel instead
+of expanding the page:
+
+| `maxHeight` | Behavior |
+| --- | --- |
+| `none` (default) | Grows with content; no vertical scroll region |
+| `sm` | `max-h-48 overflow-y-auto` |
+| `md` | `max-h-72 overflow-y-auto` |
+| `lg` | `max-h-96 overflow-y-auto` |
+
+Scrollable panels receive `tabIndex={0}` by default so keyboard users can
+focus the code region and scroll with arrow keys. Focus rings use
+`focus-visible:outline-primary`.
+
+## Surface and padding
+
+| Prop | Values | Purpose |
+| --- | --- | --- |
+| `surface` | `high` (default), `low` | `bg-surface-container-high` vs `bg-surface-container-low` |
+| `padding` | `compact` (default), `default` | `p-2` vs `p-3` |
+
+## Responsive expectations
+
+- At narrow widths, long single-line JSON or shell output wraps inside the
+  panel; horizontal scroll remains available for unbreakable segments.
+- At desktop widths, combine `maxHeight="lg"` with a `max-w-*` parent when code
+  blocks should stay readable beside side panels.
+- Header labels should use `min-w-0 shrink` so truncated titles do not push
+  action buttons off-screen.
+
+## Usage examples
+
+Short snippet:
+
+```tsx
+<CodePanel>const value = 1;</CodePanel>
+```
+
+Long single line inside a bounded column:
+
+```tsx
+<div className="w-full max-w-md">
+  <CodePanel>{longSingleLineString}</CodePanel>
+</div>
+```
+
+Long multi-line log with vertical scroll:
+
+```tsx
+<CodePanel maxHeight="md" padding="default" surface="low">
+  {longMultiLineOutput}
+</CodePanel>
+```
+
+Header row with copy action (controls stay visible):
+
+```tsx
+<div className="grid w-full max-w-md gap-2">
+  <div className="flex min-w-0 items-center justify-between gap-2">
+    <span className="min-w-0 shrink text-body-medium text-on-surface">
+      Generated script
+    </span>
+    <button className="shrink-0" type="button">
+      Copy
+    </button>
+  </div>
+  <CodePanel maxHeight="md" padding="default" surface="low">
+    {code}
+  </CodePanel>
+</div>
+```
+
+## Storybook
+
+Package Storybook stories under **Data Display/CodePanel**:
+
+- `data-display-codepanel--short-code`
+- `data-display-codepanel--long-single-line`
+- `data-display-codepanel--long-multi-line`
+- `data-display-codepanel--long-code` — narrow viewport with header controls
+- `data-display-codepanel--desktop-long-code` — desktop viewport with taller
+  scroll region
+
+Stories use package imports and token fixture styles only.

package/docs/feedback-alert-panel.md

@@ -0,0 +1,117 @@
+# AlertPanel
+
+Semantic feedback panels for neutral, informational, success, warning, danger,
+error, loading, and empty states. Use `AlertPanel` when a surface needs a
+contained message with token-backed tone, accessible roles, and optional status
+labels — without dashboard routes, providers, or feature state.
+
+## Import
+
+```ts
+import {
+  AlertPanel,
+  AlertPanelText,
+  AlertPanelTitle,
+  type AlertPanelSemanticVariant,
+} from "@you-agent-factory/components";
+```
+
+Category entrypoint:
+
+```ts
+import {
+  AlertPanel,
+  AlertPanelText,
+  AlertPanelTitle,
+} from "@you-agent-factory/components/feedback";
+```
+
+Import `@you-agent-factory/components/styles.css` once in the host application so
+semantic container and border tokens resolve correctly.
+
+## Semantic variants
+
+Prefer the `semantic` prop for reviewer-visible, all-in-one feedback states.
+Each variant resolves tone, layout, default `role`, optional status labels, and
+loading placeholders through package-owned semantics.
+
+| `semantic` | When to use | Default `role` | Status label | Visual treatment |
+| --- | --- | --- | --- | --- |
+| `neutral` | General copy without urgency | `status` | — | `border-outline`, `bg-surface-container-low`, `text-on-surface-variant` |
+| `info` | Helpful context or guidance | `status` | — | `border-af-info-border`, `bg-info-container`, `text-on-info-container` |
+| `success` | Completed or healthy outcomes | `status` | — | `border-af-success-border`, `bg-success-container`, `text-on-success-container` |
+| `warning` | Caution before continuing | `alert` | — | `border-af-warning-border`, `bg-warning-container`, `text-on-warning-container` |
+| `danger` | Destructive or high-risk actions | `alert` | — | `border-af-danger-border`, `bg-error-container`, `text-on-error-container` |
+| `error` | Failed requests or blocking faults | `alert` | `Error` | Same tokens as `danger` with explicit error label |
+| `loading` | In-flight work without final copy | `status` | `Loading` | Neutral tone, built-in skeleton placeholders, `aria-busy` |
+| `empty` | No data yet, dashed empty surface | `status` | `Empty` | Neutral tone, dashed border layout |
+
+Legacy `tone` and `variant` props remain for migration compatibility. New
+consumers should use `semantic` so roles, labels, and loading placeholders stay
+consistent.
+
+## Design token mapping
+
+Alert tones map to semantic role tokens defined in
+`src/styles/color-role-tokens.css`:
+
+- **Neutral** — `--color-outline`, `--color-surface-container-low`,
+  `--color-on-surface-variant`
+- **Info** — `--color-info-container`, `--color-on-info-container`,
+  `--color-af-info-border`
+- **Success** — `--color-success-container`, `--color-on-success-container`,
+  `--color-af-success-border`
+- **Warning** — `--color-warning-container`, `--color-on-warning-container`,
+  `--color-af-warning-border`
+- **Danger / error** — `--color-error-container`, `--color-on-error-container`,
+  `--color-af-danger-border`
+
+Typography uses package role utilities (`text-body-medium`,
+`text-body-small`) rather than dashboard-only aliases.
+
+## Accessibility
+
+- Warning, danger, and error variants default to `role="alert"`; neutral, info,
+  success, loading, and empty default to `role="status"`.
+- `error`, `loading`, and `empty` render an uppercase status label so state is
+  not communicated by color alone.
+- `loading` sets `aria-busy="true"` and renders skeleton placeholders when no
+  children are provided.
+- Compose titles with `AlertPanelTitle` and body copy with `AlertPanelText`.
+
+## Usage examples
+
+Neutral guidance:
+
+```tsx
+<AlertPanel semantic="neutral">
+  <AlertPanelTitle>Factory session idle</AlertPanelTitle>
+  <AlertPanelText>Submit work to start orchestration.</AlertPanelText>
+</AlertPanel>
+```
+
+Loading without custom markup:
+
+```tsx
+<AlertPanel semantic="loading" />
+```
+
+Empty state with dashed layout:
+
+```tsx
+<AlertPanel semantic="empty">
+  <AlertPanelTitle>No dispatches yet</AlertPanelTitle>
+  <AlertPanelText>Run a workflow to populate this list.</AlertPanelText>
+</AlertPanel>
+```
+
+## Storybook
+
+Package Storybook exposes each semantic variant under **Feedback/AlertPanel**:
+
+- `feedback-alertpanel--semantic-variants` — all eight states in one grid
+- `feedback-alertpanel--neutral`, `--info`, `--success`, `--warning`,
+  `--danger`, `--error-state`, `--loading`, `--empty`
+
+Stories use package imports and the package token fixture decorator only; they
+do not mount dashboard providers.

package/docs/feedback-skeleton.md

@@ -0,0 +1,54 @@
+# Skeleton
+
+Non-interactive loading placeholders for feedback and layout surfaces. Use
+`Skeleton` for pulse affordances inside busy regions; pair it with
+`aria-busy="true"` on a parent when the surrounding surface is still loading.
+
+## Import
+
+```ts
+import { Skeleton } from "@you-agent-factory/components";
+```
+
+Category entrypoint:
+
+```ts
+import { Skeleton } from "@you-agent-factory/components/feedback";
+```
+
+## Behavior
+
+- Renders a `div` with `aria-hidden="true"` so assistive technology does not
+  treat placeholder bars as content.
+- Uses package overlay token `bg-af-overlay` with `animate-pulse` and
+  `rounded-xl` for consistent loading chrome.
+- Accepts standard `className` sizing (`h-*`, `w-*`, `max-w-*`) so consumers
+  can mirror dashboard panel layouts.
+
+## Loading and empty feedback
+
+- **Panel loading** — wrap multiple skeleton bars in a parent with
+  `aria-busy="true"`. Hide decorative skeleton groups with `aria-hidden="true"`
+  on the wrapper when the parent already exposes busy state.
+- **Alert loading** — prefer `<AlertPanel semantic="loading" />` when the whole
+  feedback surface should show a standardized loading state with status label
+  and skeleton placeholders.
+- **Empty states** — use `<AlertPanel semantic="empty" />` for intentional empty
+  feedback; do not use `Skeleton` alone to imply emptiness.
+
+## Usage example
+
+```tsx
+<div aria-busy="true" className="grid gap-3">
+  <Skeleton className="h-4 w-32" />
+  <Skeleton className="h-28 w-full" />
+</div>
+```
+
+## Storybook
+
+Package Storybook stories under **Feedback/Skeleton**:
+
+- `feedback-skeleton--compact` — short placeholder bars
+- `feedback-skeleton--full-width` — wide block placeholder
+- `feedback-skeleton--panel-loading-layout` — dashboard-style panel loading