@flood-md/agent 0.2.12 → 0.2.13

package/dist/materials/component-alert-dialog.md

@@ -37,6 +37,7 @@ export function Example() {
 | `defaultOpen` | `boolean` | `false` |
 | `onOpenChange` | `(open: boolean) => void` | `—` |
 | `disabled` | `boolean` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `description` | `string` | `Required` |
 | `confirmLabel` | `string` | `"Continue"` |
 | `cancelLabel` | `string` | `"Cancel"` |

package/dist/materials/component-app-shell.md

@@ -23,7 +23,7 @@ export function Example() {
 
 ## Design notes
 
-- Content scrolling keeps navigation, top bar and footer outside the work scrollport. Use scroll="page" for a document that scrolls as a whole.
+- Use content scrolling for a full-window application, including record queues whose row count changes. It keeps the navigation, top bar and footer outside the work scrollport. Use scroll="page" for a document that scrolls as a whole.
 - Content mode uses Flood ScrollArea. Set scrollContentInset="none" when existing workspace padding clears the overlay rails and the content width needs to stay fixed.
 - Supply Sidebar for docked navigation. Set navigationDrawer with a shell-width threshold and Drawer content to swap automatically. Share accepted route and branch state between the two presentations.
 - Use mainAs="section" only when embedding a shell inside an existing main landmark.

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

@@ -0,0 +1,52 @@
+# BarChart
+
+Grouped or stacked columns for comparing values across categories on a shared zero baseline.
+
+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, BarChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <BarChart label="Hours by team" categories={["Product", "Design", "Growth"]}
+        series={[
+          {id:"actual", label:"Actual", values:[38, 29, 46]},
+          {id:"plan", label:"Plan", values:[32, 36, 40]}
+        ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use layout stacked for additive series. Positive and negative values accumulate independently on either side of zero. A custom domain must contain the cumulative bounds.
+- Use layout percent for nonnegative shares on a fixed 0–100% scale. The readout shows each share of the observed total and its raw value. A zero total leaves the column empty and shows raw zeros. Supply formatShare to localize percentages.
+- Series names appear in the inspection readout. Set showLegend when the key needs to be visible before interaction.
+- Pass up to four series in display order with one value per category. Put the primary series first to give it the accent fill. Comparison series use outline and dash styling as well as color.
+- Grouped columns start at zero and reserve empty slots for missing observations. In stacks, zero and missing observations take no space and remain distinguishable in the readout. Use the same domain to compare separate charts.
+- Explore exact values by hovering, tapping, or using arrow keys, Home and End. Supply formatValue and translated empty, missing and navigation labels for other locales.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `categories` | `readonly string[]` | `Required` |
+| `layout` | `"grouped" \| "stacked" \| "percent"` | `—` |
+| `series` | `readonly ChartSeries[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `showLegend` | `boolean` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `formatShare` | `(share: number) => string` | `—` |
+| `emptyLabel` | `string` | `"No data"` |
+| `missingLabel` | `string` | `"No value"` |
+| `navigationLabel` | `string` | `"Use the arrow keys to explore categories, or Home and End to jump."` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-bar-list.md

@@ -0,0 +1,41 @@
+# BarList
+
+A compact ranked list of named values on one scale.
+
+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, BarList } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <BarList label="Visits by page" items={[
+        {id:"overview", label:"Overview", value:214},
+        {id:"components", label:"Components", value:136}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Sort items before passing them in. The list preserves display order and uses a shared zero baseline. Pass the same max to compare separate lists.
+- Each item uses a proportional background bar from Flood Meter. Labels and exact values share one row and stay aligned across the list. Supply valueText for units or localized formatting.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly BarListItem[]` | `Required` |
+| `max` | `number` | `—` |
+| `tone` | `"neutral" \| "accent" \| "error" \| "warning" \| "success" \| "info"` | `"accent"` |
+| `emptyLabel` | `string` | `"No data"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-box-plot.md

@@ -0,0 +1,46 @@
+# BoxPlot
+
+Compare the median, quartiles and spread across groups, such as request latency by service.
+
+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, BoxPlot } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <BoxPlot label="Request latency (ms)" items={[
+        {id:"api", label:"API", summary:{low:42, q1:74, median:96, q3:128, high:176}, outliers:[203]},
+        {id:"search", label:"Search", summary:{low:32, q1:58, median:88, q3:154, high:210}}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Supply a five-number summary for each group. The box spans Q1 to Q3 and the white line marks the median. Supply whiskers and outliers using the same statistical convention across groups.
+- Use null for a missing summary. Use the same domain across related charts and include all observations, including outliers.
+- Hover, tap or use the arrow keys to inspect the summary and outlier count. Use formatAxisValue for shorter ticks when units are already visible. Set --flood-chart-plot-height on a shared parent to align plot heights with Histogram.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly BoxPlotItem[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `formatAxisValue` | `(value: number) => string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `missingLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `statisticLabels` | `Partial<Record<keyof BoxPlotSummary \| "outliers" \| "whiskers", string>>` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

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

@@ -0,0 +1,43 @@
+# BulletChart
+
+Actual values and targets on the same horizontal scale.
+
+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, BulletChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <BulletChart label="Resolved requests" max={100} items={[
+        {id:"web", label:"Web", value:74, target:80},
+        {id:"email", label:"Email", value:56, target:50}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Supply finite nonnegative actuals and targets in the same unit. Use a shared max to compare separate charts.
+- The fill shows the actual value and the vertical marker shows the target. Both exact values are visible without interaction.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly BulletChartItem[]` | `Required` |
+| `max` | `number` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `valueLabel` | `string` | `—` |
+| `targetLabel` | `string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-code-snippet.md

@@ -15,7 +15,7 @@ import "@flood-md/react/styles.css";
 export function Example() {
   return (
     <FloodRoot>
-      <CodeSnippet code="git status --short" />
+      <CodeSnippet prompt="$" code="git status --short" />
     </FloodRoot>
   );
 }
@@ -24,6 +24,7 @@ export function Example() {
 ## Design notes
 
 - CodeSnippet escapes code content and uses the semantic system monospace font stack.
+- Use prompt for a decorative shell marker. Pass the original code to the copy action.
 - The host implements copy behavior, failure handling and feedback. No clipboard or network API runs inside the component.
 - Code text defaults to LTR independently of parent layout. codeDirection can be ltr/rtl/auto; native dir still controls the wrapper and action layout.
 
@@ -33,5 +34,6 @@ export function Example() {
 | --- | --- | --- |
 | `code` | `string` | `Required` |
 | `codeDirection` | `"ltr" \| "rtl" \| "auto"` | `"ltr"` |
+| `prompt · 0.2.13` | `string` | `—` |
 | `action` | `ReactNode` | `—` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | `Forwarded` |

package/dist/materials/component-collection-toolbar.md

@@ -31,6 +31,7 @@ export function Example() {
 - Clear keeps its space immediately before the right-anchored Filters trigger while inactive. Removing a summary or clearing returns focus to Filters, or Search when no panel exists. Filter disclosure is omitted when no filterContent is supplied.
 - quickFilters is an optional slot for at most two task-important properties; larger property sets belong inside filterContent. The host owns the threshold and slot behavior. Supply canClear when active state is not represented by searchValue/appliedFilters, such as controls in that slot.
 - Search, accepted summaries and commands share a responsive row. The actions slot places table commands, such as Columns, next to Filters. Saved-view selectors and save/rename actions stay outside this query row.
+- Use align="end" when a sibling such as a view selector or status switcher occupies the start of the row. Search, quick filters, summaries and commands form an end-aligned group and wrap in their original order as space runs out.
 - controlSize defaults to sm; action/field sizes and chip typography follow the shared family. disabled applies to the complete fieldset, including native quick-filter controls and panel descendants. Labels and summaries remain host-localizable.
 
 ## API reference
@@ -53,6 +54,7 @@ export function Example() {
 | `onRemoveFilter` | `(id: string) => void` | `—` |
 | `appliedFiltersLabel` | `string` | `—` |
 | `summaryPrefix` | `ReactNode` | `—` |
+| `align` | `"stretch" \| "end"` | `—` |
 | `quickFilters` | `ReactNode` | `—` |
 | `actions` | `ReactNode` | `—` |
 | `filterContent` | `ReactNode` | `—` |

package/dist/materials/component-command-palette.md

@@ -39,6 +39,7 @@ export function Example() {
 | `disabled` | `boolean` | `—` |
 | `closeLabel` | `string` | `—` |
 | `closeOnOutsideClick` | `boolean` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `searchLabel` | `string` | `Required` |
 | `items` | `readonly CommandListItem[]` | `Required` |
 | `density` | `"comfortable" \| "compact"` | `"comfortable"` |

package/dist/materials/component-copy-button.md

@@ -25,6 +25,7 @@ export function Example() {
 
 - Copies only on a user click. Requires a secure context and Clipboard API; onCopyError receives unavailable/denied errors. The host owns any manual-copy fallback. Native button ref and disabled semantics are preserved.
 - Localize copyLabel/copiedLabel/errorLabel. resetDelay restores the idle state after success. Labels reserve their common width and a live status announces the result. No remote data transfer is built in. Available in 0.2.5.
+- Use iconOnly for a square IconButton when the nearby content makes the copy target clear. The button keeps its accessible name and success or failure feedback.
 
 ## API reference
 
@@ -34,6 +35,7 @@ export function Example() {
 | `tone` | `"default" \| "danger"` | `—` |
 | `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
 | `value` | `string` | `Required` |
+| `iconOnly · 0.2.13` | `boolean` | `—` |
 | `copyLabel` | `string` | `"Copy"` |
 | `copiedLabel` | `string` | `"Copied"` |
 | `errorLabel` | `string` | `"Failed"` |

package/dist/materials/component-dialog.md

@@ -25,6 +25,7 @@ export function Example() {
 
 - Uses native showModal, not a simulated modal div.
 - Escape closes the top layer; outside closing can be disabled independently. Tab remains inside the dialog.
+- Use getFallbackFocus to resolve a surviving focus target when the opener disappears or becomes unavailable on close.
 - Closed content unmounts. Forward trigger props/ref; initialFocusRef can select a safe initial control. Modern native dialog support is required.
 
 ## API reference
@@ -42,4 +43,5 @@ export function Example() {
 | `closeLabel` | `string` | `"Close"` |
 | `closeOnOutsideClick` | `boolean` | `true` |
 | `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">` | `Forwarded` |

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

@@ -0,0 +1,46 @@
+# DonutChart
+
+Shares of a whole with an in-ring total and exact values on inspection.
+
+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, DonutChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DonutChart label="Traffic sources" totalLabel="Visits" items={[
+        {id:"direct", label:"Direct", value:6420},
+        {id:"search", label:"Search", value:3720},
+        {id:"referrals", label:"Referrals", value:1960}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Pass up to six mutually exclusive categories in display order. Values must be finite and nonnegative. The ring uses their sum as the whole.
+- Hover, tap or use arrow keys, Home and End to inspect a category. Its name, exact value and share appear inside the ring. Enable showLegend when readers need the category names before interacting.
+- An empty list displays the empty label. All-zero data displays a total of zero and omits percentages. Supply formatValue and formatShare for localized output.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly DonutChartItem[]` | `Required` |
+| `totalLabel` | `string` | `"Total"` |
+| `emptyLabel` | `string` | `"No data"` |
+| `navigationLabel` | `string` | `"Use the arrow keys to explore segments, or Home and End to jump."` |
+| `showLegend` | `boolean` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `formatShare` | `(share: number) => string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-drawer.md

@@ -26,6 +26,7 @@ export function Example() {
 ## Design notes
 
 - Uses Flood native Dialog focus containment, scroll lock, background inertness, nested layers and return focus. Escape and the named close IconButton dismiss it; closeOnOutsideClick defaults to true. Controlled open/onOpenChange and initialFocusRef match Dialog.
+- Drawer inherits getFallbackFocus from Dialog. Use it when saving or deleting can remove the opening row from a collection.
 - side is logical start/end or physical top/bottom. size sets 20/26/34rem for sm/md/lg, capped to the viewport. Vertical drawers occupy the viewport height; horizontal drawers occupy its width. Entry motion respects reduced motion; closing is immediate.
 - Choose width against a populated record. For longer messages and several controls, compare md and lg. Use the description slot for short context and compose independent body groups with Section or Fieldset. Keep persistent actions in footer.
 - The body scrolls with Flood ScrollArea while the header and optional footer remain visible when space allows. Responsive padding and full-width narrow descriptions preserve the reading area at enlarged text; if the chrome cannot fit, the whole panel can scroll rather than clipping the body. Footer actions are host-owned, without implicit save or close. No swipe/drag gesture or nested navigation engine is included. Available in 0.2.5.
@@ -45,6 +46,7 @@ export function Example() {
 | `closeLabel` | `string` | `"Close"` |
 | `closeOnOutsideClick` | `boolean` | `true` |
 | `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `side` | `"start" \| "end" \| "top" \| "bottom"` | `"end"` |
 | `size` | `"sm" \| "md" \| "lg"` | `"md"` |
 | `footer` | `ReactNode` | `—` |

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

@@ -0,0 +1,46 @@
+# DumbbellChart
+
+Paired values on one scale for comparing before and after across groups.
+
+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, DumbbellChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DumbbellChart label="Response time before and after" items={[
+        {id:"api", label:"API", before:242, after:164},
+        {id:"billing", label:"Billing", before:153, after:190}
+      ]} formatValue={(value) => `${value} ms`} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The hollow point marks Before and the filled point marks After. Equal values share a position. A null endpoint leaves the other point visible.
+- Compare the same measure in the same units. Supply a shared domain when comparing separate charts and use formatValue to include units.
+- Hover, tap or use the arrow keys to read both values. Rename beforeLabel and afterLabel when comparing other paired conditions.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly DumbbellChartItem[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `beforeLabel` | `string` | `—` |
+| `afterLabel` | `string` | `—` |
+| `missingLabel` | `string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-heatmap.md

@@ -0,0 +1,45 @@
+# Heatmap
+
+A two-axis matrix that shows intensity and reveals exact cell values.
+
+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, Heatmap } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Heatmap label="Requests by hour" columns={["08:00", "10:00", "12:00"]}
+        rows={[
+          {id:"mon", label:"Mon", values:[4, 13, 23]},
+          {id:"tue", label:"Tue", values:[7, null, 32]}
+        ]} max={40} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Supply a value for each column. Values are finite and nonnegative; null represents a missing observation and gets a dashed tile. Zero is an observed value.
+- Use the same max across matrices that should be compared. Hover, tap or use arrow keys to inspect exact values in a tooltip beside the cell. Home and End move within a row.
+- Keep axis labels short at the target width. Provide formatValue and localized labels when needed.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `columns` | `readonly string[]` | `Required` |
+| `rows` | `readonly { id: string; label: string; values: readonly (number \| null)[] }[]` | `Required` |
+| `max` | `number` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `missingLabel` | `string` | `"No data"` |
+| `emptyLabel` | `string` | `"No observations"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | `Forwarded` |

package/dist/materials/component-histogram.md

@@ -0,0 +1,46 @@
+# Histogram
+
+Show how often values such as request latency fall into equal-width intervals.
+
+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, Histogram } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Histogram label="Request latency distribution" xLabel="Latency (ms)" countLabel="Requests" start={0} binWidth={50} counts={[5, 16, 34, 49, 41, 28, 17, 9, 4, 0]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Supply precomputed nonnegative integer counts in ascending bin order. Every bin shares binWidth. Keep interior zero bins so the numeric scale stays continuous.
+- Count each observation in exactly one interval. A typical convention includes the lower boundary and excludes the upper boundary, with the last upper boundary included if needed.
+- Compare histograms on the same numeric boundaries and maxCount. Set showXAxisLabel to false when the title already supplies the unit. Hover, tap or use the keyboard to inspect an interval and its exact count.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `xLabel` | `string` | `Required` |
+| `showXAxisLabel` | `boolean` | `—` |
+| `start` | `number` | `Required` |
+| `binWidth` | `number` | `Required` |
+| `counts` | `readonly number[]` | `Required` |
+| `maxCount` | `number` | `—` |
+| `countLabel` | `string` | `—` |
+| `formatBoundary` | `(value: number) => string` | `—` |
+| `formatCount` | `(count: number) => string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-image-preview.md

@@ -40,6 +40,7 @@ export function Example() {
 | `closeLabel` | `string` | `—` |
 | `closeOnOutsideClick` | `boolean` | `—` |
 | `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `src` | `string` | `Required` |
 | `alt` | `string` | `Required` |
 | `caption` | `ReactNode` | `—` |

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

@@ -0,0 +1,50 @@
+# LineChart
+
+A line or area chart for comparing trends on a shared scale.
+
+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, LineChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <LineChart label="Daily visits" categories={["Mon", "Tue", "Wed"]}
+        series={[{id:"this-week", label:"This week", values:[38, 55, 48]}]}
+        domain={[0, 60]} variant="area" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The chart shows dates and a quiet dot grid by default. Enable showYAxis when numeric levels need to be visible at a glance.
+- Series names appear in the inspection readout. Set showLegend when the key needs to be visible before interaction.
+- Supply equally spaced categories in reading order and up to four named series with the same number of values. Null and nonfinite values leave gaps. Zero is an observation.
+- Use a shared domain containing all observations when comparing separate charts. Area shading belongs to the first series. Line styles distinguish the series independently of color. Set curve to linear for straight segments.
+- Explore values by hovering, tapping, or using arrow keys, Home and End. The default number format is English; supply formatValue and translated empty, missing and navigation labels for other locales.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `categories` | `readonly string[]` | `Required` |
+| `series` | `readonly LineChartSeries[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `variant` | `"line" \| "area"` | `"area"` |
+| `curve` | `"linear" \| "smooth"` | `"smooth"` |
+| `showYAxis` | `boolean` | `false` |
+| `showLegend` | `boolean` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `emptyLabel` | `string` | `"No data"` |
+| `missingLabel` | `string` | `"No value"` |
+| `navigationLabel` | `string` | `"Use the arrow keys to explore values, or Home and End to jump."` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-menu.md

@@ -31,6 +31,7 @@ export function Example() {
 - Enter/Space and ArrowDown open at the first item; ArrowUp opens at the last. Inside use arrows, Home/End and label-prefix typeahead.
 - Disabled items stay keyboard-focusable with aria-disabled but cannot activate. Separators are noninteractive; action IDs must be unique and nonempty. At least one action is required.
 - Escape closes and restores trigger focus. Tab moves to the next control after the trigger; Shift+Tab returns to the trigger. Outside interaction dismisses without stealing deliberately moved focus.
+- Use getFallbackFocus when an action can remove or disable its opener. Resolve the surviving control from the committed interface.
 - Shortcut text is a visual hint, not an implemented key binding. No href or asynchronous task manager is included. Nested items use type="submenu" and a nonempty items array. Checkbox/radio items are controlled preferences, available in 0.2.7.
 - Controlled open needs host updates; onAction requests closure before calling the host. Modern native Popover API required. Native div props/ref target the popup. Available in 0.2.4.
 - Checkbox items take checked (boolean or mixed) and onCheckedChange. Radio items take a nonempty group label, checked and onCheckedChange; the host keeps one selected item per group. Keep each radio group contiguous. Preference items stay open by default; closeOnSelect opts into dismissal. They do not call onAction or submit form values.
@@ -47,6 +48,7 @@ export function Example() {
 | `open` | `boolean` | `—` |
 | `defaultOpen` | `boolean` | `false` |
 | `onOpenChange` | `(open: boolean) => void` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `disabled` | `boolean` | `false` |
 | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
 | `align` | `"start" \| "center" \| "end"` | `"start"` |

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

@@ -0,0 +1,46 @@
+# RangeChart
+
+Low and high values by category, with an optional midpoint.
+
+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, RangeChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <RangeChart label="Response time (ms)" lowLabel="P10" highLabel="P90" midpointLabel="Median" items={[
+        {id:"mon", label:"Mon", low:84, high:162, midpoint:119},
+        {id:"tue", label:"Tue", low:92, high:176, midpoint:125}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use a shared scale to compare intervals. Supply a midpoint only when it adds information, such as a measured median.
+- Use null bounds for missing observations and give the bounds meaningful labels with units. Inspect a category to read its exact values.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly RangeChartItem[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `lowLabel` | `string` | `—` |
+| `highLabel` | `string` | `—` |
+| `midpointLabel` | `string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `missingLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |