@flood-md/agent 0.2.11 → 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,8 @@ 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.
 
@@ -43,5 +44,6 @@ export function Example() {
 | `mainRef` | `Ref<HTMLElement>` | `—` |
 | `scrollLabel` | `string` | `—` |
 | `scrollOrientation` | `ScrollAreaProps["orientation"]` | `—` |
+| `scrollContentInset` | `ScrollAreaProps["contentInset"]` | `—` |
 | `skipLabel` | `string` | `—` |
 | `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

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

@@ -30,7 +30,8 @@ export function Example() {
 - filterContent supplies the existing filter editor, including FilterGroup or a project-specific form. The host retains draft validation, Apply/Cancel, query evaluation, persistence and saved views. filtersOpen/onFiltersOpenChange optionally control the existing Popover; filterPanelRef and filterPanelClassName support real panel focus and sizing.
 - 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; long summaries can wrap without clipping and the filter action remains at the logical end. Saved-view selectors and save/rename actions stay outside this query row.
+- 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,7 +54,9 @@ export function Example() {
 | `onRemoveFilter` | `(id: string) => void` | `—` |
 | `appliedFiltersLabel` | `string` | `—` |
 | `summaryPrefix` | `ReactNode` | `—` |
+| `align` | `"stretch" \| "end"` | `—` |
 | `quickFilters` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
 | `filterContent` | `ReactNode` | `—` |
 | `filtersLabel` | `string` | `—` |
 | `filterTitle` | `string` | `—` |

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-data-table.md

@@ -1,6 +1,6 @@
 # DataTable
 
-A native data table with local sorting, page-scoped selection and pagination.
+A native data table with sorting, selection, pagination, column layout and expandable records.
 
 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.
 
@@ -25,10 +25,15 @@ export function Example() {
 
 ## Design notes
 
-- Supply the complete client collection; remote/server pagination and virtualization are not part of this API.
+- Supply the complete collection in client mode. Server mode accepts one page with controlled page and totalRows, and controlled sort when enabled.
+- Offer Columns when users need different subsets of fields. Pass its toolbar control into CollectionToolbar.actions alongside search and filters. Reset restores initial visibility and widths.
+- Opt in to resizable columns and logical start/end pinning for wider tables. Persist width and visibility preferences by column ID.
+- Keep headers short and use the optional column unit badge for values such as USD or kg. A constrained header remains on one line with its full accessible name.
+- Use expandedContent for short related details and a captioned Flood Table for nested line items. Use Sparkline for compact trend cells with a shared domain when comparing magnitudes.
 - Select all affects selectable rows on the current page and preserves selection on other pages.
 - Use sortValues for rich React cells; missing values sort last in both directions.
 - Use showResults={false} to omit a redundant result range. Selection feedback and pagination remain, and the footer disappears when it has no other content.
+- Use showSelection={false} when a floating BulkActionBar displays the selected count. The table retains its accessible selection status.
 - Set column.numeric for comparable amounts and quantities. Header and cells align to the logical end with tabular figures, while explicit align takes precedence. Keep numeric identifiers as text and provide raw sortValues for localized amounts.
 - For in-place record details, supply row.primaryAction with the identity column, title, optional description and native button props. Pointer activation extends across the row, while keyboard focus lands on the title button. Secondary controls retain their own behavior.
 - Use toolbar for the heading and filters that share the table surface. Set inset to roomy for a shared outer inset on toolbar, table cells and footer.
@@ -38,16 +43,28 @@ export function Example() {
 
 | Prop | Values | Default |
 | --- | --- | --- |
-| `toolbar` | `ReactNode` | `—` |
+| `toolbar` | `ReactNode \| (controls: { columns: ReactNode }) => ReactNode` | `—` |
 | `inset` | `"standard" \| "roomy"` | `—` |
 | `emptyContent` | `ReactNode` | `—` |
 | `caption` | `string` | `Required` |
 | `hideCaption` | `boolean` | `—` |
 | `columns` | `readonly DataTableColumn[]` | `Required` |
+| `showColumnVisibility` | `boolean` | `—` |
+| `hiddenColumnIds` | `readonly string[]` | `—` |
+| `defaultHiddenColumnIds` | `readonly string[]` | `—` |
+| `onHiddenColumnIdsChange` | `(ids: string[]) => void` | `—` |
+| `columnWidths` | `Readonly<Record<string, number>>` | `—` |
+| `defaultColumnWidths` | `Readonly<Record<string, number>>` | `—` |
+| `onColumnWidthsChange` | `(widths: Record<string, number>) => void` | `—` |
 | `rows` | `readonly DataTableRow[]` | `Required` |
+| `expandedIds` | `readonly string[]` | `—` |
+| `defaultExpandedIds` | `readonly string[]` | `—` |
+| `onExpandedChange` | `(ids: string[]) => void` | `—` |
 | `density` | `"compact" \| "comfortable"` | `—` |
 | `striped` | `boolean` | `—` |
 | `minWidth` | `CSSProperties["minWidth"]` | `—` |
+| `maxViewportHeight` | `CSSProperties["maxBlockSize"]` | `—` |
+| `stickyHeader` | `boolean` | `—` |
 | `sort` | `DataTableSort \| null` | `—` |
 | `defaultSort` | `DataTableSort \| null` | `—` |
 | `onSortChange` | `(sort: DataTableSort \| null) => void` | `—` |
@@ -61,6 +78,7 @@ export function Example() {
 | `pageSize` | `number` | `—` |
 | `onPageChange` | `(page: number) => void` | `—` |
 | `showResults` | `boolean` | `—` |
+| `showSelection` | `boolean` | `—` |
 | `paginationMode` | `"client" \| "server"` | `—` |
 | `totalRows` | `number` | `—` |
 | `selectionScope` | `"page" \| "dataset"` | `—` |

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-editable.md

@@ -42,6 +42,10 @@ export function Example() {
 | `onEditingChange` | `(editing: boolean) => void` | `—` |
 | `onCommit` | `(value: string) => void` | `—` |
 | `onCancel` | `() => void` | `—` |
+| `validate` | `(value: string) => string \| undefined` | `—` |
+| `inputMode` | `InputHTMLAttributes<HTMLInputElement>["inputMode"]` | `—` |
+| `previewVariant` | `"subtle" \| "ghost"` | `—` |
+| `editorOverlayWidth` | `CSSProperties["inlineSize"]` | `—` |
 | `blurAction` | `"commit" \| "cancel" \| "none"` | `"commit"` |
 | `readOnly` | `boolean` | `—` |
 | `disabled` | `boolean` | `—` |

package/dist/materials/component-heading.md

@@ -34,5 +34,5 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` |
-| `size` | `"display" \| "large" \| "page" \| "section"` | `"page"` |
+| `size` | `"display" \| "large" \| "page" \| "section" \| "group"` | `"page"` |
 | `Native HTML props` | `HTMLAttributes<HTMLHeadingElement>` | `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` |