# Kanban component

`KanbanBoard` is the optional Folio Docs canvas for a Folio Board, with filtering,
staged drag-and-drop, and a progressive public workspace.

## API

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `compact` | `boolean` | `false` | Hides the filter bar, card detail dialog, staging card, and URL parameter syncing. For embedding boards in documentation pages. |
| `maxCardsPerColumn` | `number` | — | Caps the number of cards shown per column in embeds. |

## Example

```mdx
<KanbanBoard compact maxCardsPerColumn={2} />
```

The standalone CLI reads the board configured by `board.source` in
`agents.yaml`. The optional Folio Docs adapter reads `kanban.source` in
`docs.yaml`. Folio's own operational board lives on its independent `board`
branch, so this release documentation shows the invocation without coupling
the code release to that board's update cycle.

## Progressive workspace

Filters start collapsed and open from the filter button. On wide screens, the
public board places the selected card beside the canvas and its artifact after
the card. Below `1536px` wide or `480px` high, the card opens over the board at
the full viewport height. Its header stays visible while the card body and the
artifact reader each scroll inside their own frame; the page itself does not
scroll. The board behind the card cannot scroll or receive focus. Escape closes
the reader first, then the card, and returns focus to the opener. Resizing
preserves the open artifact and its scroll position.

Each hairline between surfaces is a resizer. Drag it, use its arrow keys, or
double-click it to restore the default. Closing the artifact returns to the
card; closing the card also closes its artifact. Filters close independently.
The URL carries `?card=` and `?artifact=`, and a readable artifact can enter and
leave the browser's native full-screen mode.

Open context is reading space, not a preview. The card starts at `760px` in its
active dimension and the artifact at `1040px` wide or `900px` high. Resizing
cannot reduce the card below `440px` wide or `420px` high, nor the artifact
below `560px` wide or `480px` high. These sizes apply to inline surfaces;
the full-screen card fits the current viewport. The inline artifact continues
below through `2559px`, and larger viewports use all surfaces in one row.

Boards embedded inside documentation keep the modal card and artifact drawer.

Card tiles show completed/total acceptance criteria when criteria exist. This counter describes the checklist, not the card status; completing every criterion does not move the card. Cards without criteria show no counter.

## Folio components in card descriptions

The published board page and the generated Docs board compile component-bearing
descriptions with the site's MDX component registry. Tabs, callouts, before/after
comparisons, diagrams, and project components registered in `docs.yaml` render
inside the selected card. Client components retain their interactions.

Write the component directly in the card body before its acceptance criteria,
comments, or trail:

````md
Track the behavior change and its evidence here.

## Before and after

<Tabs>
<TabItem label="Before">

The current implementation rewrites every output.

</TabItem>
<TabItem label="After">

Only affected outputs change. Measurements are still pending.

</TabItem>
</Tabs>

## Acceptance criteria
- [ ] record comparable measurements
````

Folio compiles these descriptions during the site build; the browser receives
React content rather than evaluating Markdown or copying an HTML snapshot.
The raw card remains readable by `folio-agents board`, which needs neither a
Docs build nor Node to load or edit it. Ordinary descriptions retain their
existing renderer. `./` links keep their card-relative artifact behavior.

Editing a local source board during `folio-agents serve` refreshes compiled descriptions.
An open reader for a card-owned Markdown artifact also refreshes after its
compiled page changes. The adapter derives a revision from the generated MDX,
so the reader does not refetch during the earlier source-change notification.
If that refresh fails, the reader retains the last successfully loaded body for
the same artifact; an initial load failure keeps the existing error state.
Changing a custom component's registration still requires restarting the server.
Invalid MDX reports a build error, as it does in an ordinary Folio page.

The public/generated board composes rich descriptions on the server; a manually
embedded client `KanbanBoard` or a compact preview keeps the lightweight
Markdown renderer. Rich descriptions contribute to the board's initial page
payload, so large report collections are better kept as attached documents.

Mermaid blocks in fetched documents render as interactive SVG diagrams inside the board reader.

## Theming

Every structural node carries a `data-slot` attribute for styling. Additional attributes mark dynamic state.

| Attribute | Target |
|-----------|--------|
| `data-slot="kanban"` | Root container. |
| `data-slot="kanban-filters"` | Filter bar. |
| `data-slot="kanban-filter-panel"` | Filter composer rail or drawer. |
| `data-slot="kanban-workspace"` | Responsive layout owner for the public canvas. |
| `data-slot="kanban-workspace-divider"` | Keyboard- and pointer-resizable separator between workspace surfaces. |
| `data-slot="kanban-canvas-shell"` | Toolbar and board canvas surface. |
| `data-slot="kanban-board"` | Board canvas holding all columns. |
| `data-slot="kanban-column"` | Single column container. |
| `data-slot="kanban-column-header"` | Column title and count. |
| `data-slot="kanban-card-list"` | List of cards within a column. |
| `data-slot="kanban-card"` | Individual card tile. |
| `data-slot="kanban-card-dialog"` | Card detail dialog. |
| `data-slot="kanban-card-panel"` | Selected card in the public workspace. |
| `data-slot="kanban-card-workspace"` | Inline card container. Saved panel dimensions apply here; full-screen overlays keep their viewport height. |
| `data-slot="kanban-rich-description"` | Compiled Folio content inside the selected card. |
| `data-slot="kanban-artifact-drawer"` | Reading drawer for a published artifact, inside the card dialog. |
| `data-slot="kanban-artifact-reader"` | Selected artifact in the public workspace. |
| `data-slot="kanban-staging"` | Move staging card shown when moves are pending. |
| `data-workspace-surface` | Surface identity (`canvas`, `card`, or `artifact`) in the public workspace. |
| `data-column` | Column identifier on column nodes. |
| `data-card` | Card identifier on card nodes. |
| `data-dragging` | Present on cards during drag operations. |

The staging card appears on a static board only. A live board, one whose
`docs.yaml` sets `kanban.api`, commits each move and edit through the board
server instead; see [Edit the board in the browser](/docs/guides/live). Its slots:

| Attribute | Target |
|-----------|--------|
| `data-slot="kanban-live-status"` | The `live` or `read-only` mark in the filter bar. |
| `data-slot="kanban-live-message"` | What the last save did, beside the card's `Esc` hint. |
| `data-slot="kanban-live-description-actions"` | The description's Edit, Cancel and Save row. |
| `data-slot="kanban-live-tiptap"` | The rich description editor. |
| `data-slot="kanban-live-textarea"` | The Markdown source editor used instead of the rich one. |
| `data-slot="kanban-live-plain-notice"` | The line that says why the source editor is shown. |
| `data-slot="kanban-live-artifact-add"` | The tile that attaches an artifact. |

The board page renders on pure white in light mode. Dark mode and every preset keep their own background.