@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/component-stack.md

@@ -0,0 +1,37 @@
+# Stack
+
+Vertical composition with spacing from the shared token 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, Stack, Heading, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Stack gap="4">
+        <Heading size="section">Project</Heading>
+        <Text as="p">One place for your work.</Text>
+      </Stack>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The parent owns the gap between its children.
+- Spacing keys are strings and use rem. Flood does not reset the host root font size.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `gap` | `"0" \| "1" \| "2" \| "3" \| "4" \| "6" \| "8" \| "12"` | `"4"` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-status-indicator.md

@@ -0,0 +1,38 @@
+# StatusIndicator
+
+A named state with a small decorative indicator, without a badge container.
+
+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, StatusIndicator } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <StatusIndicator tone="success" label="All systems operational" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The visible label carries meaning; the dot is decorative and color is never the only signal. Use announce to opt into a polite status live region for changing messages.
+- Static labels do not announce by default. Tone is independent of wording and size. Use Badge for categorical labels and Alert for a message requiring more explanation.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `tone` | `"neutral" \| "accent" \| "error" \| "warning" \| "success" \| "info"` | `"neutral"` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `announce` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | `Forwarded` |

package/dist/materials/component-steps.md

@@ -0,0 +1,40 @@
+# Steps
+
+An ordered progress sequence with explicit current, completed, upcoming and error states.
+
+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, Steps } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Steps label="Project setup" currentValue="access" items={[{value:"details",title:"Details"},{value:"access",title:"Access"},{value:"review",title:"Review"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Steps renders an ordered list, not tabs. currentValue identifies aria-current=step; preceding steps default to complete and later steps to upcoming. Item status may explicitly mark complete/upcoming/error. Omitted currentValue starts at the first step.
+- Without onStepChange, steps are informative content. Providing it renders native step buttons; the host owns navigation and currentValue updates. Disabled items only affect those actions. Every state has text through customizable statusLabels; color and icons are additional cues. Horizontal presentation stacks in narrow viewports.
+- Original compatible addition in the unpublished 0.2.5 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly StepItem[]` | `Required` |
+| `currentValue` | `string` | `—` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `onStepChange` | `(value: string) => void` | `—` |
+| `statusLabels` | `{complete: string; current: string; upcoming: string; error: string}` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLOListElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-surface.md

@@ -0,0 +1,37 @@
+# Surface
+
+A quiet container with semantic elevation and token-based padding.
+
+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, Surface, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Surface elevation="raised" padding="6">
+        <Text>Everything in its place.</Text>
+      </Surface>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Elevation describes appearance. Overlay does not create a dialog, portal or focus trap.
+- Prefer grouping and spacing before adding more nested containers.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `elevation` | `"default" \| "raised" \| "overlay"` | `"default"` |
+| `padding` | `"0" \| "1" \| "2" \| "3" \| "4" \| "6" \| "8" \| "12"` | `"6"` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-switch.md

@@ -0,0 +1,35 @@
+# Switch
+
+A labeled on/off setting with native checkbox form behavior.
+
+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, Switch } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Switch label="Email notifications" name="notifications" defaultChecked />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Switch uses a native checkbox with role="switch".
+- checked/defaultChecked, name/value, reset and disabled remain native. The component does not persist settings.
+- The control and visible label form one content-width unit with an 8px-at-16px-root internal gap. Use an explicit parent gap="4" (16px at that root) between units; the glyph keeps its token-defined size.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `ReactNode` | `Required` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | `Forwarded` |

package/dist/materials/component-table.md

@@ -0,0 +1,46 @@
+# Table
+
+A native data table with caption, density and a protected horizontal scroll area.
+
+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, Table } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Table caption="Projects">
+        <thead><tr><th scope="col">Project</th><th scope="col" data-numeric>Members</th></tr></thead>
+        <tbody><tr><th scope="row">Flood</th><td data-numeric>12</td></tr></tbody>
+      </Table>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- 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.
+- 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.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `caption` | `string` | `Required` |
+| `children` | `ReactNode` | `Required` |
+| `hideCaption` | `boolean` | `false` |
+| `density` | `"compact" \| "comfortable"` | `"comfortable"` |
+| `striped` | `boolean` | `false` |
+| `scrollLabel` | `string` | `—` |
+| `cellVerticalAlign` | `"top" \| "middle" \| "bottom"` | `"middle"` |
+| `Native HTML props` | `Omit<TableHTMLAttributes<HTMLTableElement>, "children">` | `Forwarded` |

package/dist/materials/component-tabs.md

@@ -0,0 +1,45 @@
+# Tabs
+
+Connected tab buttons and retained content panels with roving keyboard focus.
+
+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, Tabs } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Tabs label="Project sections" items={[{value:"overview",label:"Overview",content:"Project context."},{value:"activity",label:"Activity",content:"Recent updates."}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use variant="line" for page-level sections with an active marker beside the panel. The default contained variant joins tabs and content in one surface.
+- Arrow keys navigate enabled tabs; automatic activation is default, manual needs Enter/Space. Tab leaves the tablist. Horizontal direction follows RTL.
+- Inactive panels remain mounted but hidden. Keep form validation and persistent selection under host control. Invalid, missing or disabled selected values fall back to the first available item.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly TabItem[]` | `Required` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `activationMode` | `"automatic" \| "manual"` | `"automatic"` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `variant` | `"contained" \| "line"` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `disabled` | `boolean` | `false` |
+| `iconOnly` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-tag-input.md

@@ -0,0 +1,46 @@
+# TagInput
+
+Free-form text tokens with keyboard entry, removal and named form 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, TagInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TagInput label="Topics" defaultValue={["Design", "React"]} name="topics" placeholder="Add a topic…" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use TagInput for values the user may create. Use MultiSelect for a fixed option collection.
+- Enter and configured delimiters commit trimmed, unique tags. Pasting separated text adds multiple tags. IME composition is preserved.
+- Each committed tag submits one entry under name. required applies to committed tags; a draft is not a submitted token. Form reset preserves controlled ownership.
+- Backspace on an empty draft removes the last token. Read only preserves copying and form values; disabled omits submission and removal. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `—` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `delimiters` | `readonly string[]` | `—` |
+| `removeLabel` | `string` | `"Remove"` |
+| `requiredMessage` | `string` | `"Add at least one tag."` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children" \| "size">` | `Forwarded` |

package/dist/materials/component-tag.md

@@ -0,0 +1,40 @@
+# Tag
+
+A compact label with an optional icon and a named removal action.
+
+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, Tag } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Tag onRemove={() => { /* Update the host collection. */ }}>Design</Tag>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Tag is a label, not a status Badge or a selection toggle. The host owns removal; onRemove never hides the element automatically. Use ordinary noninteractive label content.
+- Plain text gets a default Remove label. Rich content needs explicit removeLabel. disabled prevents removal; size and decorative icon are independent. removeButtonProps customizes the nested native action while Tag owns type, name, disabled and removal.
+- Standalone removal is an ordinary Tab stop. MultiSelect supplies its composite keyboard model. Geometry uses relative Flood sizing; long labels wrap and touch targets remain distinct. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `icon` | `ReactNode` | `—` |
+| `disabled` | `boolean` | `false` |
+| `onRemove` | `() => void` | `—` |
+| `removeLabel` | `string` | `—` |
+| `removeButtonProps` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "type" \| "disabled" \| "onClick" \| "aria-label">` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLSpanElement>` | `Forwarded` |

package/dist/materials/component-text.md

@@ -0,0 +1,39 @@
+# Text
+
+Role-based interface text, from introductory copy to small supporting details.
+
+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, Stack, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Stack gap="3">
+        <Text as="p" size="lead">Quarterly revenue</Text>
+        <Text as="p" size="compact">Revenue increased by 8% this quarter.</Text>
+      </Stack>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use as="p" for paragraphs. The label size does not create a form association.
+- Subtle is a supplementary tone; evaluate small required instructions against the actual background and font size.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `as` | `"span" \| "p" \| "div"` | `"span"` |
+| `size` | `"lead" \| "body" \| "compact" \| "label" \| "helper"` | `"body"` |
+| `tone` | `"default" \| "subtle" \| "error" \| "success" \| "warning" \| "info"` | `"default"` |
+| `Native HTML props` | `HTMLAttributes<HTMLElement>` | `Forwarded` |

package/dist/materials/component-textarea.md

@@ -0,0 +1,38 @@
+# Textarea
+
+Native multiline input for notes and longer text.
+
+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, Field, Textarea } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Project note" hint="Keep it short and useful.">
+        {(control) => <Textarea {...control} rows={3} maxLength={500} />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Rows, maxLength, value/defaultValue and form props remain native.
+- The default has no resize grip. Long text scrolls inside the field; a host can opt into native resizing with style={{ resize: "vertical" }}.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `Native HTML props` | `TextareaHTMLAttributes<HTMLTextAreaElement>` | `Forwarded` |

package/dist/materials/component-time-field.md

@@ -0,0 +1,56 @@
+# TimeField
+
+Segmented 24-hour time entry with canonical values, bounds and a seconds-based step.
+
+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, TimeField } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TimeField label="Start time" name="startTime" defaultValue="09:30" step={300} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use HH:mm with minute precision or HH:mm:ss with second precision. Values have no date or timezone.
+- step is expressed in seconds and anchored to min or midnight; minute precision requires a multiple of 60. Overnight ranges are not inferred.
+- In editable fields, incomplete, invalid, out-of-range, step-mismatched and refused controlled drafts block native submission. Readonly preserves accepted canonical time outside bounds/step alignment; it never accepts a partial or refused draft. Disabled values are excluded.
+- Click the control background to focus a missing or remembered segment. Keyboard steps, Home/End, paste and IME preserve host cancellation. Translate segmentLabels and messages. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `end` | `ReactNode` | `—` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `precision` | `"minute" \| "second"` | `"minute"` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `step` | `number` | `—` |
+| `required` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `segmentLabels` | `Partial<Record<"hour" \| "minute" \| "second", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string; stepMismatch?: string }` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

package/dist/materials/component-time-picker.md

@@ -0,0 +1,60 @@
+# TimePicker
+
+A segmented time field with an anchored, keyboard-accessible list of clock times.
+
+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, TimePicker } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TimePicker label="Start time" name="time" defaultValue="09:30" min="08:00" max="18:00" interval={1800} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Interval and step use seconds; the list contains at most 1000 entries.
+- Manual entry remains available; this is wall-clock time without timezone conversion.
+- One flat list, with selected-time visibility and a trailing action aligned with DatePicker.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `precision` | `"minute" \| "second"` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `step` | `number` | `—` |
+| `required` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `segmentLabels` | `Partial<Record<"hour" \| "minute" \| "second", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string; stepMismatch?: string }` | `—` |
+| `interval` | `number` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `—` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `panelLabel` | `string` | `—` |
+| `openTimeLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">, "end">` | `Forwarded` |

package/dist/materials/component-timeline.md

@@ -0,0 +1,38 @@
+# Timeline
+
+An ordered sequence of events with state, context and optional time labels.
+
+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, Timeline } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Timeline label="Project activity" items={[{id:"created",title:"Project created",state:"complete"},{id:"review",title:"Design review",state:"current"},{id:"release",title:"Release",state:"upcoming"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The native ordered list is read in the supplied order; the component does not sort or group events. IDs/titles are nonempty, IDs are unique and at most one event may be current.
+- Each state has a visually hidden text equivalent; localize stateLabels. timeLabel is user-facing text and dateTime, when supplied, is the machine-readable time. Both are host-owned.
+- Markers and optional artwork are decorative. This is an event display, not a wizard or navigation control. Long descriptions and times wrap without changing marker alignment.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly TimelineItem[]` | `Required` |
+| `stateLabels` | `{complete?: string; current?: string; upcoming?: string}` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLOListElement>, "children">` | `Forwarded` |

package/dist/materials/component-toast-region.md

@@ -0,0 +1,42 @@
+# ToastRegion
+
+A host-controlled notification queue with timed, pausable messages and actions.
+
+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, ToastRegion } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ToastRegion items={[{id:"saved",title:"Changes saved",status:"success",duration:0}]} onDismiss={id => { /* Remove the item from host state. */ }} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The host owns items and removes them onDismiss. IDs must be unique/nonempty. limit controls visible items; queued timers start only when visible. Ordinary messages default to five seconds; error/action messages persist unless duration is explicit. duration=0 persists.
+- Timers pause on hover, focus and hidden documents. F8 focuses the first visible region without interrupting initial task focus; hotkey=false disables it. Use a single main region per document. Localize label/closeLabel and message/action text. Error messages announce as alerts; others use polite status.
+- placement is logical start/end. inline embeds the region in a host container; fixed mode uses ordinary document stacking, so place a contextual region inside a modal if needed. Action callbacks do not dismiss automatically. No global notification store or promise API. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `items` | `readonly ToastItem[]` | `Required` |
+| `onDismiss` | `(id: string) => void` | `Required` |
+| `label` | `string` | `"Notifications"` |
+| `closeLabel` | `string` | `"Dismiss notification"` |
+| `placement` | `"top-start" \| "top-end" \| "bottom-start" \| "bottom-end"` | `"bottom-end"` |
+| `limit` | `number` | `3` |
+| `inline` | `boolean` | `false` |
+| `hotkey` | `boolean` | `true` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | `Forwarded` |