@you-agent-factory/components 0.0.0

package/docs/graphs.md

@@ -0,0 +1,250 @@
+# Graph primitives (`@you-agent-factory/components/graphs`)
+
+Generic React Flow presentation primitives for graph nodes, edges, handles, and
+viewport chrome. The graph category is domain-free: it does not import factory,
+workstation, work-state, generated OpenAPI, dashboard API, or dashboard feature
+types.
+
+Host applications own graph data fetching, durable graph state, domain node
+renderers, layout projection, copy, and business workflows. Pass generic props
+and callbacks into these components; keep product-specific graph logic in host
+feature code.
+
+## Install and import
+
+Graph primitives import from the graphs category entrypoint:
+
+```ts
+import {
+  GraphNodeShell,
+  GraphNodeButton,
+  GraphEdge,
+  GRAPH_EDGE_TYPES,
+  GraphViewportSurface,
+  GraphNodeHandleBadge,
+  buildGraphEdgePathThroughWaypoints,
+  type GraphNodeHandle,
+  type GraphNodeState,
+} from "@you-agent-factory/components/graphs";
+```
+
+Import package styles once in the host application:
+
+```css
+@import "@you-agent-factory/components/styles.css";
+```
+
+## React Flow dependency
+
+`@xyflow/react` is a direct dependency of `@you-agent-factory/components`, not
+a dashboard-only peer. Graph primitives that integrate with React Flow resolve
+it from the component package dependency graph.
+
+| Package surface | React Flow boundary |
+| --- | --- |
+| `GraphNodeHandleBadge` | Wraps React Flow `Handle` for source/target affordances |
+| `GraphEdge` | Registered as a React Flow custom edge type (`graphEdge`) |
+| `GraphInteractiveExample` | Composes `ReactFlow`, `Controls`, and package node shells |
+| `GraphNodeShell`, `GraphNodeButton`, `GraphViewportSurface` | Plain React markup; mount inside React Flow node renderers or viewport chrome |
+
+When composing a full canvas, wrap node renderers in `ReactFlowProvider` and
+register `GRAPH_EDGE_TYPES` (or a host-specific alias that forwards to
+`GraphEdge`) on the `ReactFlow` instance. Import `@xyflow/react/dist/style.css`
+in components that render `ReactFlow` controls or backgrounds.
+
+## Component contracts
+
+### `GraphNodeShell`
+
+Presentation shell for a graph node body and handle rails.
+
+- **Props:** `handles` (required), `children`, optional `nodeKind`, `state`,
+  `stateLabel`, `showStateIndicator` (default `true`), and standard
+  `article` attributes.
+- **States:** `default`, `selected`, `disabled`, `loading`, `error`.
+- **Accessibility:** Selected shells expose `aria-selected`; error shells expose
+  `aria-invalid`; loading shells expose `aria-busy`; disabled shells expose
+  `aria-disabled`. Selected and error shells use border weight/style and shadow
+  in addition to color.
+- **Layout:** Loading and loaded shells reserve a fixed-height state indicator
+  row (`GRAPH_NODE_CONTENT_MIN_HEIGHT_CLASS`) to avoid layout shift.
+
+```tsx
+<GraphNodeShell
+  handles={[
+    { id: "in", label: "Input", side: "left", type: "target" },
+    { id: "out", label: "Output", side: "right", type: "source" },
+  ]}
+  nodeKind="example"
+  state="selected"
+  stateLabel="Selected node"
+>
+  <GraphNodeButton graphState="selected">Example node</GraphNodeButton>
+</GraphNodeShell>
+```
+
+### `GraphNodeButton`
+
+Interactive control inside a node shell. Uses `graphState` (not `state`) to
+avoid clashing with native button state.
+
+- **States:** same `GraphNodeState` union as the shell.
+- **Disabled behavior:** `disabled`, `loading`, and native `disabled` block
+  activation while preserving readable labels.
+- **Accessibility:** `aria-pressed` for selected buttons; `aria-busy`,
+  `aria-invalid`, and `aria-disabled` mirror shell semantics.
+
+```tsx
+<GraphNodeButton
+  graphState="loading"
+  stateLabel="Loading node"
+  onClick={() => activateNode()}
+>
+  Run step
+</GraphNodeButton>
+```
+
+Shared state helpers (`graphNodeShellStateClassName`,
+`graphNodeButtonStateAttributes`, `defaultGraphNodeStateLabel`, and related
+exports) are available when host wrappers need the same contract.
+
+### `GraphEdge`
+
+Custom React Flow edge renderer. Accepts standard `EdgeProps` plus optional
+`edgeClassName` and `labelClassName` for host styling.
+
+- **Data:** optional `label`, `alwaysShowLabel`, and `waypoints` on edge `data`.
+- **Geometry:** uses `buildGraphEdgePathThroughWaypoints` when waypoints are
+  present; otherwise falls back to React Flow `getBezierPath`.
+- **Registration:** export `GRAPH_EDGE_TYPES` or alias `graphEdge` in host edge
+  type maps.
+
+```tsx
+const edgeTypes = { graphEdge: GraphEdge };
+
+<ReactFlow edgeTypes={edgeTypes} /* ... */ />
+```
+
+### `GraphViewportSurface`
+
+Semantic viewport chrome (`section` with `role="region"` by default) for graph
+frames. Accepts children (typically `ReactFlow`) and standard section attributes.
+
+Pass an explicit height (`h-*`, `min-h-*`) for Storybook or standalone examples.
+Wrap interactive examples in an explicit width (`w-[48rem]`, `w-80`, etc.) when
+Storybook uses centered layout; `w-full` alone can collapse to a few pixels wide.
+Hosts that fill flex parents should add `h-full` (and usually `min-h-0`) via
+`className`; the primitive does not force `h-full` so explicit heights are not
+capped by a collapsed parent.
+
+```tsx
+<GraphViewportSurface className="h-[480px] border-outline">
+  <ReactFlow /* ... */ />
+</GraphViewportSurface>
+```
+
+### `GraphNodeHandleBadge`
+
+Renders a single source or target handle with accessible labels and tone-based
+dot styling. Usually composed by `GraphNodeShell`; import directly when building
+custom node layouts.
+
+- **Props:** `handle: GraphNodeHandle` with `id`, `label`, `side`, `type`, and
+  optional tone, variant, validation, and button interaction fields.
+- **Accessibility:** `aria-label` from `buttonAriaLabel` or `label`; invalid
+  handles expose `aria-invalid`.
+
+### `buildGraphEdgePathThroughWaypoints`
+
+Pure edge-path helper for waypoint-routed geometry. Returns `{ path, labelX,
+labelY }` for representative straight, stepped, curved, and bezier-fallback
+cases. Safe to call from host layout code without importing dashboard models.
+
+```ts
+const routed = buildGraphEdgePathThroughWaypoints({
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  waypoints: [{ x: 120, y: 80 }],
+});
+```
+
+## Storybook examples
+
+Package Storybook discovers stories under `src/graphs/*.stories.tsx` without
+dashboard providers. Run from `ui/packages/components`:
+
+```bash
+bun run build-storybook
+bunx http-server storybook-static -p 6017 -a 127.0.0.1 -s
+```
+
+Open `http://127.0.0.1:6017` and use the story IDs below.
+
+### Node states (`Graphs/GraphNodeStates`)
+
+| Story | Storybook ID | What it shows |
+| --- | --- | --- |
+| Selected | `graphs-graphnodestates--selected` | Selected shell and button affordances |
+| Disabled | `graphs-graphnodestates--disabled` | Non-activating disabled node |
+| Loading | `graphs-graphnodestates--loading` | Stable loading dimensions and `aria-busy` |
+| Loaded | `graphs-graphnodestates--loaded` | Default loaded node after loading |
+| Error | `graphs-graphnodestates--error-state` | Error border style and `aria-invalid` |
+
+### Edges and handles (`Graphs/GraphEdgesAndHandles`)
+
+| Story | Storybook ID | What it shows |
+| --- | --- | --- |
+| Bezier edge | `graphs-graphedgesandhandles--bezier-edge` | Default bezier edge path |
+| Waypoint edge | `graphs-graphedgesandhandles--waypoint-edge` | Routed path through waypoints |
+| Source/target handles | `graphs-graphedgesandhandles--source-target-handles` | Accessible handle labels |
+| Selected node handles | `graphs-graphedgesandhandles--selected-node-handles` | Handle placement on selected shell |
+| Desktop viewport | `graphs-graphedgesandhandles--desktop-viewport` | Desktop-width edge/handle layout |
+| Narrow viewport | `graphs-graphedgesandhandles--narrow-viewport` | Narrow-width readability |
+
+### Interactive and responsive (`Graphs/GraphInteractiveExamples`)
+
+| Story | Storybook ID | What it shows |
+| --- | --- | --- |
+| Interactive | `graphs-graphinteractiveexamples--interactive` | Pointer/keyboard node selection in a React Flow canvas |
+| Selected | `graphs-graphinteractiveexamples--selected` | Selected state panel |
+| Disabled | `graphs-graphinteractiveexamples--disabled` | Disabled state panel |
+| Loading | `graphs-graphinteractiveexamples--loading` | Visible loading state without hover |
+| Error | `graphs-graphinteractiveexamples--error-state` | Visible error state without hover |
+| Desktop viewport | `graphs-graphinteractiveexamples--desktop-viewport` | Desktop canvas with controls |
+| Narrow viewport | `graphs-graphinteractiveexamples--narrow-viewport` | Narrow canvas without horizontal overflow |
+
+Loading, error, disabled, and selected states are visible in the story canvas
+without opening addon panels.
+
+## Host responsibilities
+
+Keep these concerns in host application code, not in the graph package:
+
+- Fetching graph topology, work items, and runtime facts from APIs
+- Durable editor state, undo/redo, and save/discard workflows
+- Domain node renderers that map product models onto `GraphNodeShell` /
+  `GraphNodeButton` props
+- Layout projection, edge routing policy beyond generic waypoints, and product copy
+- React Flow `nodes`, `edges`, `onNodesChange`, and business interaction handlers
+
+The dashboard follows this boundary: `features/graphs/public/` re-exports package
+primitives and adds domain wrappers (for example activity-graph shells and
+factory edge class names) without forking generic presentation logic.
+
+## Development checks
+
+From `ui/packages/components`:
+
+```bash
+bun run typecheck
+bun run test
+bun run build-storybook
+bun run verify:storybook-browser
+```
+
+Graph tests use `ReactFlowProvider` and, for full-canvas cases,
+`installReactFlowTestShims()` from `@you-agent-factory/components/testing`.

package/docs/layout-display-primitives.md

@@ -0,0 +1,211 @@
+# Layout and display primitives
+
+Domain-free layout and key-value display primitives for panels, action toolbars,
+and description lists. Use these components when you need bordered surfaces,
+responsive action rows, and scan-friendly metadata layouts without dashboard
+routes, providers, API clients, or generated OpenAPI types.
+
+The package ships three primitives:
+
+| Component | Role |
+| --- | --- |
+| `SurfacePanel` | Bordered container with semantic surface, padding, radius, and tone options. |
+| `ActionRow` | Responsive row for status chips and action controls. |
+| `DescriptionList` | Semantic `<dl>` scaffold for label/value rows supplied by the host. |
+
+These components are **presentation layout**. They provide structure, spacing,
+and responsive wrapping. They do not fetch data, orchestrate workflows, or embed
+product copy.
+
+## Required setup
+
+Import package styles once in your host application before rendering layout
+primitives:
+
+```css
+@import "@you-agent-factory/components/styles.css";
+```
+
+Layout primitives depend on package semantic tokens such as `border-outline`,
+`surface-container-high`, and `primary-container`. They do not require
+dashboard `styles.css`, dashboard providers, generated OpenAPI types, React
+Query, or Zustand.
+
+## Import paths
+
+Prefer category entrypoints for explicit boundaries:
+
+```ts
+import {
+  ActionRow,
+  SurfacePanel,
+  surfacePanelVariants,
+  type ActionRowProps,
+  type SurfacePanelProps,
+} from "@you-agent-factory/components/layout";
+
+import {
+  DescriptionList,
+  type DescriptionListProps,
+} from "@you-agent-factory/components/data-display";
+```
+
+The same exports are also available from the package root:
+
+```ts
+import {
+  ActionRow,
+  DescriptionList,
+  SurfacePanel,
+} from "@you-agent-factory/components";
+```
+
+Compose layout primitives with typography from `@you-agent-factory/components`
+or `@you-agent-factory/components/primitives` for headings, labels, and body
+copy inside panels and description lists.
+
+## Surface panel structure
+
+`SurfacePanel` renders a bordered container with token-backed surface styling.
+Use it to group related content, headings, and action rows.
+
+### Variants
+
+| Prop | Values | Purpose |
+| --- | --- | --- |
+| `padding` | `default`, `compact`, `none` | Inner spacing (`p-3`, `p-2`, or none). |
+| `radius` | `lg`, `xl`, `2xl`, `3xl`, `full` | Corner radius. |
+| `surface` | `high`, `low` | `bg-surface-container-high` or `bg-surface-container-low`. |
+| `tone` | `default`, `accent`, `selected` | Border and fill emphasis for accent or selected states. |
+
+```tsx
+import { Heading, Text } from "@you-agent-factory/components";
+import { SurfacePanel } from "@you-agent-factory/components/layout";
+
+<SurfacePanel padding="default" radius="xl" surface="high">
+  <Heading level="section">Panel title supplied by the host</Heading>
+  <Text>Panel body copy supplied by the host</Text>
+</SurfacePanel>
+```
+
+Use `surfacePanelVariants` when you need the same class bundle on a non-panel
+element. `asChild` merges panel styles onto a single child through Radix Slot;
+verify your host bundler deduplicates React and Radix dependencies when using
+`asChild`.
+
+The package owns border, padding, radius, and surface tokens. Host applications
+own headings, body copy, footer actions, and when a panel is accent or selected
+in product context.
+
+## Action row wrapping
+
+`ActionRow` lays out optional `statuses` and `actions` sections in a responsive
+flex row:
+
+- Root: `flex flex-wrap items-center gap-2 max-md:justify-start`
+- Sections (`data-action-row-section`): `flex min-w-0 flex-wrap items-center gap-2`
+
+Statuses render before actions when both are provided. The row returns `null`
+when neither slot has content.
+
+```tsx
+import { ActionRow } from "@you-agent-factory/components/layout";
+
+<ActionRow
+  statuses={<span>Status copy supplied by the host</span>}
+  actions={
+    <>
+      <button type="button">Secondary action</button>
+      <button type="button">Primary action</button>
+    </>
+  }
+/>
+```
+
+### Responsive behavior
+
+On wide viewports, action groups stay aligned in a single row when space allows.
+On narrow viewports (`max-md`), the row uses `justify-start` so wrapped controls
+remain reachable without clipping focus rings.
+
+Long host labels inside action sections should use typography `truncate` or live
+inside width-constrained parents so wrapping does not create horizontal page
+overflow. Pass custom section classes through `statusesClassName` and
+`actionsClassName` when a host layout needs tighter gaps or alignment overrides.
+
+The package owns flex structure, `min-w-0` overflow guards, and section
+ordering. Host applications own button labels, click handlers, disabled and
+loading state, and which actions appear in each section.
+
+## Description list layout
+
+`DescriptionList` renders a semantic `<dl>` with:
+
+- `grid min-w-0 gap-1.5` on the root
+- `BODY_TEXT_CLASS` defaults for readable values
+- `[&_div]:grid [&_div]:min-w-0` so each row can define its own column template
+
+Host applications supply row structure, labels, values, and empty placeholders:
+
+```tsx
+import { DescriptionList } from "@you-agent-factory/components/data-display";
+import { Label, Text } from "@you-agent-factory/components";
+
+<DescriptionList className="[&_div]:grid-cols-[8.5rem_minmax(0,1fr)]">
+  <div>
+    <Label as="dt">Status</Label>
+    <Text as="dd">{statusLabel}</Text>
+  </div>
+  <div>
+    <Label as="dt">Owner</Label>
+    <Text as="dd">{ownerName ?? emptyPlaceholder}</Text>
+  </div>
+</DescriptionList>
+```
+
+### Layout guidance
+
+| Scenario | Host pattern |
+| --- | --- |
+| Compact metadata rows | `className="gap-1 [&_div]:grid-cols-[7rem_minmax(0,1fr)]"` plus `Text variant="dense"`. |
+| Wide or multi-column lists | `className="md:grid-cols-2 [&_div]:grid-cols-[8.5rem_minmax(0,1fr)]"` on `DescriptionList`. |
+| Long labels | `Label truncate` inside a width-constrained parent. |
+| Long values | `Text wrap` on `dd` elements. |
+| Missing values | Host supplies placeholder copy such as `"—"`; the package does not invent empty text. |
+
+The root and `dd` elements include `min-w-0` so nested grids shrink inside narrow
+panels without forcing horizontal overflow.
+
+## Host application responsibilities
+
+The component package owns presentation markup, semantic structure, responsive
+flex and grid defaults, and token-backed borders and surfaces.
+
+Host applications own:
+
+| Concern | Owner |
+| --- | --- |
+| Panel headings, body copy, and footer actions | Host |
+| Status chips, badges, and action button labels | Host |
+| Description-list labels, values, and empty placeholders | Host |
+| Multi-column layouts and custom grid templates via `className` | Host |
+| Loading, empty, error, and success states around layout primitives | Host |
+| Click handlers, routing, and workflow orchestration for actions | Host |
+| When a surface is accent, selected, or compact in product context | Host |
+
+Pass content, callbacks, and layout overrides into primitives as props. Do not
+expect the package to read from your routers, stores, or API layers.
+
+## Storybook examples
+
+Package Storybook stories demonstrate layout behavior with package imports only:
+
+- `Layout/ActionRow` — default, dense, long-label, wrapped, wide, and mobile or
+  desktop viewport examples.
+- `Layout/SurfacePanel` — default, dense, structured heading or content or
+  footer, and mobile or desktop viewport examples.
+- `Data Display/DescriptionList` — default, compact, wide, long-label,
+  long-value, empty-value, narrow, and mobile or desktop viewport examples.
+
+Run `bun run storybook` from `ui/packages/components` or inspect the static
+build with `bun run build-storybook`.