@flood-md/agent 0.2.12 → 0.2.13

package/dist/materials/component-scatter-chart.md

@@ -0,0 +1,48 @@
+# ScatterChart
+
+Paired numeric observations for inspecting how two measures vary together.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, ScatterChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ScatterChart label="Response time by traffic" xLabel="Requests / sec" yLabel="Response time (ms)" points={[
+        {id:"run-1", label:"Run 1", x:12, y:110},
+        {id:"run-2", label:"Run 2", x:52, y:162},
+        {id:"run-3", label:"Run 3", x:104, y:301}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Give each point a stable ID and finite x and y values. Label both axes with their units.
+- Use matching xDomain and yDomain to compare separate plots. Use formatX and formatY for localized values.
+- Inspect the nearest point with the pointer or traverse observations in supplied order with the keyboard.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `xLabel` | `string` | `Required` |
+| `yLabel` | `string` | `Required` |
+| `points` | `readonly ScatterChartPoint[]` | `Required` |
+| `xDomain` | `readonly [number, number]` | `—` |
+| `yDomain` | `readonly [number, number]` | `—` |
+| `formatX` | `(value: number) => string` | `—` |
+| `formatY` | `(value: number) => string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-sheet.md

@@ -44,6 +44,7 @@ export function Example() {
 | `closeLabel` | `string` | `—` |
 | `closeOnOutsideClick` | `boolean` | `—` |
 | `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `size` | `"sm" \| "md" \| "lg"` | `"md"` |
 | `footer` | `ReactNode` | `—` |
 | `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">, "side">` | `Forwarded` |

package/dist/materials/component-table.md

@@ -28,7 +28,7 @@ export function Example() {
 
 - Caption is required and remains the accessible table name with hideCaption. Supply table sections and correct native header/cell associations.
 - Native table props, className/style and HTMLTableElement ref target the actual table. Set style.minWidth when horizontal overflow is preferable to compressed columns.
-- Flood ScrollArea owns horizontal scrolling and keyboard access. scrollLabel can name its viewport independently; dir and hidden apply to the containing scroll area too.
+- Flood ScrollArea owns horizontal scrolling and keyboard access. Set maxViewportHeight for bounded vertical scrolling with stable clearance for the overlay rail. scrollLabel names the viewport independently.
 - Use data-numeric on headers/cells for end alignment and tabular figures; data-align=start/center/end gives logical alignment. No automatic sorting, selection, pagination or data access.
 - Striped and compact/comfortable density are opt-in presentation. Available in 0.2.4.
 

package/dist/materials/component-waterfall-chart.md

@@ -0,0 +1,47 @@
+# WaterfallChart
+
+Signed changes and checkpoints along a running total.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, WaterfallChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <WaterfallChart label="Net revenue (USD)" steps={[
+        {id:"gross", label:"Gross", value:32000, kind:"total"},
+        {id:"refunds", label:"Refunds", value:-4500},
+        {id:"fees", label:"Fees", value:-2500},
+        {id:"net", label:"Net", value:25000, kind:"total"}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- A change adds its signed value to the running total. A total is an absolute checkpoint that replaces the running total.
+- Use the same domain for charts you want to compare. It must contain zero and every intermediate total. Use formatValue to add units.
+- Hover, tap or use the keyboard to inspect exact changes and running totals. Decreases use a dashed outline.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `steps` | `readonly WaterfallChartStep[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `changeLabel` | `string` | `—` |
+| `totalLabel` | `string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/guide-agent-knowledge.md

@@ -7,11 +7,11 @@ The same package sources build the website, CLI results and agent instructions.
 ## Discover, then read
 
 ```sh
-npx @flood-md/cli@0.2.12 info --json
-npx @flood-md/cli@0.2.12 catalog --kind workflow --group foundations
-npx @flood-md/cli@0.2.12 catalog --kind component --search table
-npx @flood-md/cli@0.2.12 read recipe:table-bulk-actions
-npx @flood-md/cli@0.2.12 read component:data-table
+npx @flood-md/cli@0.2.13 info --json
+npx @flood-md/cli@0.2.13 catalog --kind workflow --group foundations
+npx @flood-md/cli@0.2.13 catalog --kind component --search table
+npx @flood-md/cli@0.2.13 read recipe:table-bulk-actions
+npx @flood-md/cli@0.2.13 read component:data-table
 ```
 
 These commands return JSON and do not install dependencies, edit files, execute

package/dist/materials/guide-agents.md

@@ -1,5 +1,9 @@
 # Using Flood with an agent
 
+Flood pairs a React design system with a workflow for agents building and
+reviewing interfaces. Each release connects component contracts, runnable
+recipes and focused skills through the same catalog.
+
 Start with the host's instructions, package.json, flood.json and installed
 flood/DESIGN.md. Use matching package/CLI versions and declarations. A newer
 website example does not add APIs to an older installation.
@@ -82,8 +86,37 @@ component pages. Before completion use verification. For a color-only change,
 load customization and the relevant token roles; unrelated guides stay unloaded.
 
 Clients supporting the skill-folder convention can discover it. Others can read
-it explicitly or link it from existing instructions. The installer preserves
-AGENTS.md; it does not configure clients or guarantee automatic discovery.
+it explicitly. For a client that reads project instructions such as `AGENTS.md`,
+add a short trigger to the existing instructions at the scope where Flood is used:
+
+```markdown
+For UI work in this project, read `.agents/skills/flood-ui/SKILL.md` first.
+Follow its routing for the screen or component you are changing. Check the
+installed component contract. For visible changes, use the visual review workflow
+to exercise the affected states and inspect screenshots from the running app.
+```
+
+Use the `installedEntry` path in `flood/manifest.json` if it differs. The
+installer preserves `AGENTS.md`; add this trigger yourself if it suits your client.
+
+## Review the running interface
+
+When composing a new flow, start from a nearby recipe, check the installed
+component contracts and apply the workflow for the task. For example, use the
+[record management recipe](recipes/record-management.md) to see how a collection
+preserves filters, scroll and focus around a detail Drawer and edit form.
+
+For a visual issue, exercise the actual state and inspect the captured evidence.
+If it repeats, check the smallest component or layout that can enforce the fix.
+Add a browser assertion when behavior can be measured. Use the relevant workflow
+or a runnable example for decisions that depend on the task, such as information
+hierarchy or which details should stay visible. Use clean runs to test whether
+agents discover and apply new guidance on another task.
+
+For a full-window AppShell route, use
+[`assertWorkspaceScroll`](../packages/agent/references/rendered-review.md#require-workspace-scroll-in-browser-tests)
+in the browser suite. Exercise both the populated and filtered states so
+document scrolling fails the test on either state.
 
 The rules index is data, not an executable policy engine. It cannot make an agent
 obey guidance or certify accessibility. Host checks and Flood's repository

package/dist/materials/guide-charts.md

@@ -0,0 +1,34 @@
+# Charts
+
+[Try the three latency charts](https://flood.md/docs/charts#latency-example)
+with one shared service filter, or pick a chart below and copy its React example.
+For setup in React or Next.js, see [Installation](installation.md).
+
+## Trends and comparisons
+
+- [LineChart](https://flood.md/components/line-chart) shows how a measure changes over time. Compare this week with last week on the same scale.
+- [Sparkline](https://flood.md/components/sparkline) shows a small trend beside a value in a table or summary.
+- [BarChart](https://flood.md/components/bar-chart) compares categories. Group series to compare actual and planned values, or use percent stacks to compare their shares.
+- [BarList](https://flood.md/components/bar-list) ranks named values, such as traffic sources, where the labels and counts matter as much as the bars.
+- [BulletChart](https://flood.md/components/bullet-chart) compares a single value with a target and optional reference bands.
+
+## Distributions and relationships
+
+- [Histogram](https://flood.md/components/histogram) shows how often values fall into intervals. Use it to see whether requests cluster near 100 ms or have a long tail.
+- [BoxPlot](https://flood.md/components/box-plot) compares the median, quartiles and endpoints across groups, such as latency by service.
+- [ScatterChart](https://flood.md/components/scatter-chart) shows the relationship between two measurements, such as throughput and response time.
+- [Heatmap](https://flood.md/components/heatmap) shows patterns across two dimensions, such as activity by day and hour.
+- [RangeChart](https://flood.md/components/range-chart) shows an interval for each item, such as a forecast range.
+
+## Parts of a whole and change
+
+- [DonutChart](https://flood.md/components/donut-chart) shows a few shares of one whole, such as spending by category.
+- [WaterfallChart](https://flood.md/components/waterfall-chart) explains how individual increases and decreases add up to a final value.
+- [DumbbellChart](https://flood.md/components/dumbbell-chart) compares two values for each category, such as before and after a rollout.
+
+## Inspecting values
+
+Give each chart a name that includes its measure. Keep units consistent across
+axis labels and value formatting. Hover or focus interactive plots to inspect
+values, then use the arrow keys to move through the data. Where readers need to
+scan or copy many exact values, provide the data in a table alongside the chart.

package/dist/materials/guide-foundations.md

@@ -1,6 +1,6 @@
-# Foundations tokens · 0.2.12 candidate
+# Foundations tokens · 0.2.13
 
-This guide describes the **0.2.12 candidate** foundation exports. Keep Flood packages at
+This guide describes the **0.2.13** foundation exports. Keep Flood packages at
 matching exact versions. Existing 0.1.1 installs use their earlier token contract.
 
 Foundations separates fixed reference values (`ref`) from semantic roles (`sys`).

package/dist/materials/guide-installation.md

@@ -1,6 +1,6 @@
-# Installation · 0.2.12
+# Installation · 0.2.13
 
-The commands below target version 0.2.12. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
+The commands below target version 0.2.13. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
 
 Use Node.js 22.12 or newer and an existing npm-based React/Next.js project.
 React 18.3/19 is supported; React 19 and Next.js App Router are integration targets.
@@ -15,8 +15,8 @@ repeat installation when you start using another component.
 ## Connect with the CLI
 
 ```sh
-npx @flood-md/cli@0.2.12 init --dry-run
-npx @flood-md/cli@0.2.12 init
+npx @flood-md/cli@0.2.13 init --dry-run
+npx @flood-md/cli@0.2.13 init
 ```
 
 The installer adds exact matching tokens, React and agent packages. It creates
@@ -40,7 +40,7 @@ No Tailwind configuration or font CDN is needed. The foundations profile is dark
 only; legacy theme behavior remains available outside `FloodRoot`.
 
 ```sh
-npx @flood-md/cli@0.2.12 doctor
+npx @flood-md/cli@0.2.13 doctor
 ```
 
 Doctor checks package versions and guide presence, not stylesheet imports or
@@ -50,7 +50,7 @@ reference `flood/DESIGN.md` from its existing instructions.
 ## Manual package installation
 
 ```sh
-npm install --save-exact @flood-md/tokens@0.2.12 @flood-md/react@0.2.12 @flood-md/agent@0.2.12
+npm install --save-exact @flood-md/tokens@0.2.13 @flood-md/react@0.2.13 @flood-md/agent@0.2.13
 ```
 
 Import the stylesheet and use `FloodRoot` as above. Manual installation does not

package/dist/materials/guide-introduction.md

@@ -16,6 +16,7 @@ them without a separate content service.
 | [Project UI](project-ui.md) | Optional semantic @/ui/button imports in your application |
 | [Layout](layout.md) | Intrinsic actions, responsive forms, choice sizing, gaps and hierarchy |
 | [Components](components.md) | Available controls, props and form composition |
+| [Charts](charts.md) | Choose a chart by the question it answers and try the live latency example |
 | [Base component inventory](base-components.md) | Available primitives and controls in the base release |
 | [Customization](theming.md) | Scoped dark foundations overrides and legacy theme boundaries |
 | [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.11 |
@@ -30,7 +31,7 @@ them without a separate content service.
 
 ## Versions
 
-This branch documents **version 0.2.11**; source availability does
+This branch documents **version 0.2.13**; source availability does
 not establish npm publication. Use matching exact versions of the Flood packages. Documentation on `main` can describe later work; the
 [release tags](https://github.com/tillwithered/flood.md/releases) preserve the
 source and docs for each release. Installed `flood/DESIGN.md` takes precedence

package/dist/materials/guide-motion.md

@@ -54,6 +54,18 @@ behavior of their children. State updates and focus take effect immediately.
 | `CodeSnippet`, `Card`, `DataList`, `DataListItem`, `FileItem`, `FileList`, `AvatarGroup` | Embedded actions and avatars own motion. Reading order and record layout remain stable. |
 | `Badge`, `DescriptionList`, `Table`, `Image`, `List`, `Figure`, `Metric`, `Timeline`, `ColorSwatch`, `FileMeta` | Static content. Changes to data, labels and supporting media render immediately. |
 | `Sparkline` | Hover briefly strengthens the latest point and area. Data changes render immediately. |
+| `LineChart` | Crosshair, markers and local line emphasis track the pointer continuously. The readout shows the nearest recorded sample and lifts clear of the marker near the trailing edge. On exit the readout and marks fade in place from their last pointer position. |
+| `BarList` | Uses Meter's value transition and the same fast highlight as chart inspection. Labels and values update immediately. |
+| `BarChart` | Uses the fast motion role to emphasize the inspected group while its neighbors dim. The readout updates with the active category and column geometry stays fixed. |
+| `DonutChart` | Uses the fast motion role for the inspected segment's outline. Category colors, fills and geometry stay fixed, and the center readout updates immediately. |
+| `Heatmap` | Moves the value tooltip immediately to the inspected cell and keeps the matrix fixed. Visual gutters share the adjacent cells' hit areas. |
+| `ScatterChart` | Highlights the inspected observation and presents its coordinates. Points keep their positions. |
+| `RangeChart` | Highlights the inspected interval while its exact bounds update immediately. |
+| `BulletChart` | Uses the Meter transition for the actual value. Target marks and exact values update immediately. |
+| `WaterfallChart` | Highlights the inspected step and shows the change and running balance. |
+| `Histogram` | Shows exact bin bounds and count as inspection moves. Bin geometry stays fixed. |
+| `BoxPlot` | Highlights the inspected distribution and anchors its summary to the median. The tooltip prefers the right side and flips when space runs out. |
+| `DumbbellChart` | Highlights the inspected comparison without moving its marks. The readout updates immediately. |
 | `Avatar` | Loaded image eases in within a fixed frame. Fallback text is immediately available. |
 | `DataTable` | Selected row paint, chevron rotation and a short height transition for row details. Sorting, pagination and column resize update geometry immediately. |
 | `Tooltip`, `Popover`, `Menu`, `ContextMenu`, `HoverCard`, `CommandPalette`, `Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `ImagePreview` | Anchored entrances follow placement. Modal and edge panels have their own timing. Sheet uses the bottom Drawer entrance. Controls, focus, close and positioning retain their native behavior. |

package/dist/materials/guide-skills.md

@@ -13,11 +13,19 @@ The hierarchy workflow covers task/group/field roles, common control tracks and
 relationship spacing. It complements editorial decisions and the spacing workflow;
 it does not prescribe one screen template.
 
+The screen composition workflow helps choose page structure and reading order
+for landing pages, workspaces, forms and documentation. Review it by running
+the user's find, compare or act task in the rendered screen.
+
 The records workflow covers list/detail information selection, stable scan
 positions and the distinction between category, lifecycle state, priority and
 time. It includes examples where those attributes should remain visible, rather
 than a universal rule to hide metadata or limit badge counts.
 
+Visual review exercises the running UI, captures the affected states and checks
+the screenshots before handoff. Use it for new UI, screenshot feedback and
+visible regressions. Keep browser evidence with the findings or the fix.
+
 Use [Agent knowledge](agent-knowledge.md) to discover these workflows by semantic
 group and read the installed version. The catalog separates prerequisites from
 optional related components; grouping is not a request to load every skill.
@@ -40,6 +48,7 @@ Layout and task recipes assembled from existing primitives.
 | --- | --- | --- |
 | flood-composition | Build or review Flood UI from existing library primitives before adding composites. Use for component, website, playground and host-interface work, especially when a layout fix risks replacing a reusable element with custom markup. | [Read skill](/agent/references/flood-composition/SKILL.md) |
 | flood-interface-content | Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents. | [Read skill](/agent/references/flood-interface-content/SKILL.md) |
+| flood-screen-composition | Choose the layout, reading order and first useful action for a Flood screen. Use for new screens or when an existing page is hard to scan, compare or act on. | [Read skill](/agent/references/flood-screen-composition/SKILL.md) |
 | flood-hierarchy | Establish visual hierarchy, shared form tracks and vertical rhythm in Flood screens, forms and overlays. Use when titles, groups and labels compete or a composed interface feels flat; not a fixed page template. | [Read skill](/agent/references/flood-hierarchy/SKILL.md) |
 | flood-spacing | Diagnose Flood spacing, density, nested radii and alignment from rendered geometry. Use for large gaps, crowded rows or shifting compositions. | [Read skill](/agent/references/flood-spacing/SKILL.md) |
 | flood-records | Compose record lists and detail views with a clear metadata hierarchy. Use for crowded status/category/priority/date rows, drifting scan positions or deciding between a list and a comparison table. | [Read skill](/agent/references/flood-records/SKILL.md) |
@@ -74,6 +83,7 @@ Accessibility, evidence and regression checks.
 | flood-interface-content | Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents. | [Read skill](/agent/references/flood-interface-content/SKILL.md) |
 | flood-accessibility | Review Flood interface names, keyboard flow, focus, perception and reflow in the actual host. Use for interaction or accessibility acceptance. | [Read skill](/agent/references/flood-accessibility/SKILL.md) |
 | flood-verification | Verify Flood component or composed-interface changes against applicable contracts and actual evidence. Use for stabilization, regression or completion review. | [Read skill](/agent/references/flood-verification/SKILL.md) |
+| flood-visual-review | Review rendered Flood UI with Playwright or equivalent browser tooling. Use for visual bugs, screenshot feedback, new or changed UI, and visual regressions across interaction states. | [Read skill](/agent/references/flood-visual-review/SKILL.md) |
 
 ## Motion
 

package/dist/materials/recipe-collection-views.md

@@ -239,6 +239,9 @@ defines reset scope and supplies canClear for any state held by quickFilters.
 At most two task-important quick properties remain inline; additional properties
 belong inside Filters. Summaries outside the panel name the property and preserve
 any-match meaning. Container width, rather than viewport size, governs reflow.
+When search and filters share a wide row with a status or view selector, use
+`align="end"` on CollectionToolbar. Check that the final control reaches the
+row's trailing content edge and that the row wraps with enlarged text.
 The Projects table places its Columns control in CollectionToolbar's `actions`
 slot via DataTable's `toolbar` render function. It shares the tool row with
 search and filters, and the commands wrap as a group in a narrow container.

package/dist/materials/recipe-navigation-workspace.md

@@ -62,6 +62,9 @@ embedded shell an explicit block size. Choose `scroll="page"` for natural
 document scrolling. Place a persistent top bar and footer in the shell slots,
 and PageHeader inside main. The shell has a skip target and owns the scroll
 boundary; the host owns routes and persisted choices.
+For a full-window workspace with a padded content edge, use
+`scrollContentInset="none"` when that padding already clears the overlay rail.
+Verify that the document width stays fixed as its collection grows and shrinks.
 
 For a single Sidebar, opt into `navigationDrawer` with a width threshold in CSS
 pixels and a `renderContent(close)` function. AppShell observes its own width.

package/dist/materials/recipe-record-management.md

@@ -2,22 +2,22 @@
 
 [Open the working composition](/playground/records).
 
-Search requests, narrow the list by status, open one request, and edit it in a
-Drawer. Saving applies the accepted changes and returns to the same list.
+Search requests, narrow the table by status, open one request, and edit it in a
+Drawer. Saving updates the request and returns to the same table.
 The example uses in-memory fixtures that reset on reload.
 
 ## Choose where details open
 
 Use a Drawer for a bounded inspection or edit that starts and ends in the same
 list. Use a destination page for details that need a stable URL, substantial
-room, or several independent tasks. This example uses a named Open button
-because opening its Drawer is an action on the current screen.
+room, or several independent tasks.
 
 When users compare several attributes, DataTable can use a `primaryAction`
 in the identity column. Pass the Drawer trigger handlers and ref to that
 action. Check the row background, title and description, checkbox and any
 secondary menu independently. Use `toolbar` and `inset="roomy"` for a heading
-and filters that share the table surface.
+and filters that share the table surface. Use the request title as the visible
+action and keep its ID beside it for disambiguation.
 
 ```tsx
 <Drawer title="Review workspace access" size="lg"
@@ -52,6 +52,10 @@ reading area. Compose the body from Section for separately named content,
 DescriptionList for facts and Fieldset for related controls. Check wrapping and
 scrolling with the longest title and a real footer action before selecting a size.
 Use the group heading size inside a detail Drawer to keep the record name prominent.
+Keep the request facts in one DescriptionList and use a compact, captioned Table
+for related records that have comparable columns, such as activity dates and events.
+Give that table its own heading when it identifies a distinct section. The Drawer
+body owns vertical scrolling and the footer keeps the next action within reach.
 
 When the detail contains line items and a total, use the Table footer to mark
 the summary and keep its amount aligned with the line-item amounts. A row header
@@ -69,13 +73,14 @@ labels the total, and the Table footer supplies the separator and emphasis.
 ## Keep browsing state and edit state separate
 
 Keep search, filter, accepted records and the open record ID in the host.
-Keep the list and its ScrollArea mounted while the Drawer is open. Reset the
+Keep the DataTable and its ScrollArea mounted while the Drawer is open. Reset the
 scroll position only when the user changes the query or filter.
 
 Entering edit mode copies the selected record. Cancel edit returns to details
 without changing accepted data. Saving replaces the record by stable ID.
-Recompute matches using the existing search and filter. If the updated record
-leaves the results, explain why and preserve the query. For a remote save, close
+Recompute matches using the existing search and filter. Use a floating ToastRegion
+for the save result so it cannot move the table. If the updated record leaves
+the results, explain why and preserve the query. For a remote save, close
 on accepted data and retain the draft with actionable feedback on failure.
 
 ## Restore focus to a useful place
@@ -83,8 +88,9 @@ on accepted data and retain the draft with actionable feedback on failure.
 Forward the Drawer trigger props from the single overlay to the row action
 that opens it. Focus Edit request when details open, Subject when editing starts,
 and Edit request after Cancel edit. On close, return focus to the same row
-action without scrolling. If the row left the results, focus Search requests
-without clearing it.
+action without scrolling. Drawer resolves `getFallbackFocus` after closing
+if the row left the results. The recipe returns Search requests and keeps
+the current query.
 
 Keep subject and ID together in the list. Status earns a stable trailing slot
 because users filter and compare by it. Put owner and the longer summary in the
@@ -105,9 +111,10 @@ Drawer's conditional detail content.
 
 import {useEffect, useId, useLayoutEffect, useRef, useState, type FormEvent} from "react";
 import {
-  Alert, Button, DataList, DataListItem, DescriptionList, Drawer, EmptyState,
-  Field, Grid, Heading, Inline, Input, ScrollArea, SearchInput, Select,
-  Stack, StatusIndicator, Surface,
+  Button, DataTable, DescriptionList, Drawer, EmptyState,
+  Field, Grid, Heading, Inline, Input, SearchInput, Section, Select,
+  Stack, StatusIndicator, Surface, Table, ToastRegion,
+  type DataTableColumn, type ToastItem,
 } from "@flood-md/react";
 
 const statuses = {
@@ -125,6 +132,24 @@ type RequestRecord = {
   summary: string;
 };
 
+const requestColumns: DataTableColumn[] = [
+  {id: "subject", label: "Subject", sortable: true},
+  {id: "status", label: "Status", sortable: true},
+];
+
+const activityByRequest: Record<string, readonly {date: string; activity: string}[]> = {
+  "REQ-105": [
+    {date: "2026-11-10", activity: "Access issue reported"},
+    {date: "2026-11-11", activity: "Identity verified"},
+    {date: "2026-11-12", activity: "Recovery link sent"},
+  ],
+  "REQ-117": [
+    {date: "2026-11-11", activity: "Permission review requested"},
+    {date: "2026-11-12", activity: "Regional roles exported"},
+  ],
+};
+const activityDate = new Intl.DateTimeFormat("en", {month: "short", day: "numeric", timeZone: "UTC"});
+
 const fixtures: RequestRecord[] = [
   {id: "REQ-104", title: "Update billing address", owner: "Mina Chen", status: "new", summary: "Use the new address on future invoices."},
   {id: "REQ-105", title: "Restore workspace access", owner: "Alex Morgan", status: "active", summary: "A teammate cannot sign in after changing email."},
@@ -157,25 +182,20 @@ export function RecordManagement() {
   const [status, setStatus] = useState<Status | "all">("all");
   const [recordId, setRecordId] = useState<string | null>(null);
   const [draft, setDraft] = useState<RequestRecord | null>(null);
-  const [notice, setNotice] = useState("");
+  const [notice, setNotice] = useState<ToastItem | null>(null);
   const search = useRef<HTMLInputElement>(null);
-  const list = useRef<HTMLDivElement>(null);
+  const table = useRef<HTMLDivElement>(null);
   const subject = useRef<HTMLInputElement>(null);
   const edit = useRef<HTMLButtonElement>(null);
-  const opener = useRef<HTMLButtonElement>(null);
-  const restore = useRef(false);
   const returnToEdit = useRef(false);
   const selected = records.find(record => record.id === recordId);
+  const activity = selected ? activityByRequest[selected.id] : undefined;
   const results = records.filter(record => matchesRequest(record, query, status));
   const editing = draft !== null;
   const open = selected !== undefined;
 
   useBrowserLayoutEffect(() => {
-    if (!open && restore.current) {
-      restore.current = false;
-      const target = opener.current?.isConnected ? opener.current : search.current;
-      target?.focus({preventScroll: true});
-    } else if (editing) {
+    if (editing) {
       subject.current?.focus({preventScroll: true});
     } else if (open && returnToEdit.current) {
       returnToEdit.current = false;
@@ -186,12 +206,11 @@ export function RecordManagement() {
   function changeQuery(nextQuery: string, nextStatus: Status | "all") {
     setQuery(nextQuery);
     setStatus(nextStatus);
-    setNotice("");
-    if (list.current) list.current.scrollTop = 0;
+    setNotice(null);
+    table.current?.querySelector('[role="region"][aria-label="Requests"]')?.scrollTo({top: 0});
   }
 
   function closeRecord() {
-    restore.current = true;
     returnToEdit.current = false;
     setDraft(null);
     setRecordId(null);
@@ -208,9 +227,12 @@ export function RecordManagement() {
     }
     const updated = {...draft, title, owner: draft.owner.trim()};
     setRecords(current => current.map(record => record.id === updated.id ? updated : record));
-    setNotice(matchesRequest(updated, query, status)
-      ? `${updated.id} updated.`
-      : `${updated.id} updated and no longer matches the current search or filter.`);
+    setNotice({
+      id: updated.id,
+      title: `${updated.id} updated`,
+      description: matchesRequest(updated, query, status) ? undefined : "It no longer matches your search or filter.",
+      status: "success",
+    });
     closeRecord();
   }
 
@@ -245,35 +267,37 @@ export function RecordManagement() {
         open={open}
         onOpenChange={open => { if (!open) closeRecord(); }}
         initialFocusRef={edit}
-        trigger={({ref, onClick, "aria-expanded": expanded, ...trigger}) =>
-          <Surface elevation="raised" padding="4">
-            <ScrollArea ref={list} role="region" aria-label="Request results" style={{maxBlockSize: "22rem"}}>
-              {results.length > 0
-                ? <DataList aria-label="Requests" className="request-results">
-                  {results.map(record => <DataListItem
-                    key={record.id}
-                    title={record.title}
-                    description={record.id}
-                    metadata={<StatusIndicator {...statuses[record.status]} size="sm" />}
-                    actions={<Button {...trigger} aria-expanded={Boolean(expanded && record.id === recordId)}
-                      aria-label={`Open ${record.id} ${record.title}`}
-                      variant="subtle" size="sm" onClick={event => {
-                        opener.current = event.currentTarget;
-                        ref(event.currentTarget);
-                        setRecordId(record.id);
-                        onClick?.(event);
-                      }}>Open</Button>}
-                  />)}
-                </DataList>
-                : <EmptyState title="No matching requests" actions={<Button variant="subtle" onClick={() => {
-                  search.current?.focus({preventScroll: true});
-                  changeQuery("", "all");
-                }}>Clear filters</Button>} />}
-            </ScrollArea>
+        getFallbackFocus={() => search.current}
+        trigger={({ref, onClick, ...trigger}) =>
+          <Surface elevation="raised" padding="0" className="request-table-frame">
+            <DataTable ref={table} caption="Requests" hideCaption inset="roomy" minWidth="min-content"
+              maxViewportHeight="26rem" stickyHeader pageSize={fixtures.length}
+              columns={requestColumns} rows={results.map(record => ({
+                id: record.id,
+                cells: {status: <StatusIndicator {...statuses[record.status]} size="sm" />},
+                sortValues: {status: statuses[record.status].label},
+                primaryAction: {
+                  column: "subject", title: record.title, description: record.id,
+                  buttonProps: {
+                    ...trigger,
+                    "aria-expanded": open && record.id === recordId,
+                    "aria-label": `${record.title}, ${record.id}`,
+                    onClick: event => {
+                      ref(event.currentTarget);
+                      setRecordId(record.id);
+                      onClick?.(event);
+                    },
+                  },
+                },
+              }))}
+              emptyContent={<EmptyState title="No matching requests" actions={<Button variant="subtle" onClick={() => {
+                search.current?.focus({preventScroll: true});
+                changeQuery("", "all");
+              }}>Clear filters</Button>} />} />
           </Surface>}
         footer={draft
-          ? <Inline gap="2"><Button type="submit" form={formId}>Save changes</Button>
-            <Button variant="subtle" onClick={cancelEdit}>Cancel edit</Button></Inline>
+          ? <Inline gap="2"><Button variant="subtle" onClick={cancelEdit}>Cancel edit</Button>
+            <Button type="submit" form={formId}>Save changes</Button></Inline>
           : <Button ref={edit} onClick={() => { if (selected) setDraft({...selected}); }}>Edit request</Button>}
       >
         {draft
@@ -297,13 +321,23 @@ export function RecordManagement() {
               </Field>
             </Stack>
           </form>
-          : selected && <DescriptionList items={[
+          : selected && <Stack gap="8"><DescriptionList items={[
               {id: "request-id", term: "Request ID", description: selected.id},
               {id: "owner", term: "Owner", description: selected.owner || "Unassigned"},
               {id: "status", term: "Status", description: <StatusIndicator {...statuses[selected.status]} />},
-            ]} />}
+            ]} />
+            {activity && <Section title="Activity" headingLevel={3} headingSize="group">
+              <Table caption="Request activity" hideCaption density="compact">
+                <thead><tr><th scope="col">Date</th><th scope="col">Event</th></tr></thead>
+                <tbody>{activity.map(item => <tr key={item.date}>
+                  <td><time dateTime={item.date}>{activityDate.format(new Date(item.date))}</time></td>
+                  <td>{item.activity}</td>
+                </tr>)}</tbody>
+              </Table>
+            </Section>}
+          </Stack>}
       </Drawer>
-      {notice && <Alert tone="success" announcement="polite">{notice}</Alert>}
+      <ToastRegion items={notice ? [notice] : []} onDismiss={() => setNotice(null)} />
     </Stack>
   </section>;
 }