@flood-md/agent 0.2.9 → 0.2.11

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

@@ -0,0 +1,48 @@
+# CommandList
+
+Search and invoke commands with grouped results and keyboard navigation.
+
+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, CommandList } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CommandList label="Search commands" items={[{id:"new",label:"New project",group:"Projects"},{id:"settings",label:"Open settings",group:"Workspace"}]} onAction={id => console.log(id)} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- CommandList invokes actions; Combobox and MultiSelect edit form values. A command list has no submitted name or persistent selected value.
+- Typing filters labels, descriptions, group names and keywords. Arrow keys, Home/End and Enter navigate and invoke enabled commands. Escape remains available to a host Dialog.
+- Use query/onQueryChange for host ownership or defaultQuery for local filtering. Loading blocks stale invocation and exposes an announcement; the host owns asynchronous work and cancellation.
+- The ref targets the native search input. Native div props target the wrapper. Translate labels, placeholder, emptyMessage and loadingMessage; hideLabel preserves the search name. No modal, global shortcut or router integration is implied. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `items` | `readonly CommandListItem[]` | `Required` |
+| `query` | `string` | `—` |
+| `defaultQuery` | `string` | `—` |
+| `onQueryChange` | `(query: string) => void` | `—` |
+| `onAction` | `(id: string) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `loading` | `boolean` | `false` |
+| `placeholder` | `string` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

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

@@ -0,0 +1,53 @@
+# CommandPalette
+
+A modal search surface for navigating pages or running commands.
+
+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, CommandPalette, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CommandPalette title="Go to page" searchLabel="Search pages" trigger={props => <Button {...props}>Go to page</Button>} items={[{id:"projects",label:"All projects"}]} onAction={id => console.log(id)} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Choose comfortable or compact density. Items can be grouped, described or disabled.
+- Opening focuses search. Enter or click runs an enabled action and requests closure. Escape and the close button return focus to the trigger.
+- Use controlled query and loading for asynchronous search. The application owns requests, navigation and any global shortcut.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `closeLabel` | `string` | `—` |
+| `closeOnOutsideClick` | `boolean` | `—` |
+| `searchLabel` | `string` | `Required` |
+| `items` | `readonly CommandListItem[]` | `Required` |
+| `density` | `"comfortable" \| "compact"` | `"comfortable"` |
+| `query` | `string` | `—` |
+| `defaultQuery` | `string` | `—` |
+| `onQueryChange` | `(query: string) => void` | `—` |
+| `onAction` | `(id: string) => void` | `Required` |
+| `loading` | `boolean` | `—` |
+| `placeholder` | `string` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">, "children" \| "description" \| "initialFocusRef">` | `Forwarded` |

package/dist/materials/component-container.md

@@ -0,0 +1,36 @@
+# Container
+
+Centered content with token widths and logical gutters.
+
+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, Container, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Container size="md" gutter="6"><Text as="p">Content stays within a readable width.</Text></Container>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Max width includes gutters (border-box). Sizes sm/md/lg use relative semantic roles; full removes the maximum.
+- Native div props/ref target the container. Gutter uses Space; it does not add vertical spacing or breakpoints.
+- Available in 0.2.4; use matching installed declarations.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg" \| "full"` | `"lg"` |
+| `gutter` | `"0" \| "1" \| "2" \| "3" \| "4" \| "6" \| "8" \| "12"` | `"6"` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-context-menu.md

@@ -0,0 +1,43 @@
+# ContextMenu
+
+Context actions at the pointer or keyboard target, sharing the Menu interaction engine.
+
+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, ContextMenu, Surface } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ContextMenu label="Project actions" items={[{id:"rename",label:"Rename"},{id:"duplicate",label:"Duplicate"}]} onAction={id => console.log(id)}><Surface padding="6">Right-click or use Shift+F10.</Surface></ContextMenu>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Right click opens at the pointer; ContextMenu or Shift+F10 opens near the actual focused target. The wrapper is keyboard-focusable and named.
+- Uses the same Menu items, preferences, nested layers, typeahead and keyboard navigation. Leaf commands close the tree; Escape unwinds one level and restores the real source focus.
+- disabled preserves the native browser context menu. Controlled open and onAction remain host-owned. Provide a visible Menu action as a primary alternative on touch devices. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly MenuItem[]` | `Required` |
+| `onAction` | `(id: string) => void` | `—` |
+| `children` | `ReactNode` | `Required` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"sm"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | `Forwarded` |

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

@@ -0,0 +1,43 @@
+# CopyButton
+
+A clipboard action with stable geometry and localized result feedback.
+
+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, CopyButton } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CopyButton value="npm install @flood-md/react" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- 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.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `tone` | `"default" \| "danger"` | `—` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `value` | `string` | `Required` |
+| `copyLabel` | `string` | `"Copy"` |
+| `copiedLabel` | `string` | `"Copied"` |
+| `errorLabel` | `string` | `"Failed"` |
+| `resetDelay` | `number` | `2000` |
+| `onCopied` | `() => void` | `—` |
+| `onCopyError` | `(error: unknown) => void` | `—` |
+| `Native HTML props` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "value" \| "type" \| "onClick" \| "loading">` | `Forwarded` |

package/dist/materials/component-data-list-item.md

@@ -0,0 +1,40 @@
+# DataListItem
+
+A structured list row with media, supporting text, metadata 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, DataList, DataListItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DataList>
+        <DataListItem title="Design system" description="Foundations and components" metadata="Updated today" />
+      </DataList>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Render inside DataList or another native list.
+- The row is not clickable; supply a Link as title when navigation is needed.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `ReactNode` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `media` | `ReactNode` | `—` |
+| `metadata` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLLIElement>, "title" \| "children">` | `Forwarded` |

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

@@ -0,0 +1,38 @@
+# DataList
+
+A native list of structured rows with independent links 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, DataList, DataListItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DataList>
+        <DataListItem title="Design system" description="Foundations and components" metadata="Updated today" />
+        <DataListItem title="Website" description="Documentation and examples" metadata="Updated yesterday" />
+      </DataList>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- This is a ul/li list, not a listbox or data grid.
+- Keep navigation in the title link and actions in their own buttons.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `density` | `"compact" \| "comfortable"` | `"comfortable"` |
+| `dividers` | `boolean` | `true` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLUListElement>, "role">` | `Forwarded` |

package/dist/materials/component-data-table.md

@@ -0,0 +1,70 @@
+# DataTable
+
+A native data table with local sorting, page-scoped selection and pagination.
+
+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, DataTable } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DataTable caption="Projects" selectable pageSize={5}
+        columns={[{id:"name",label:"Project",sortable:true},{id:"status",label:"Status"},{id:"members",label:"Members",numeric:true}]}
+        rows={[{id:"design",label:"Design system",cells:{name:"Design system",status:"Active",members:12}}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Supply the complete client collection; remote/server pagination and virtualization are not part of this API.
+- 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.
+- 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.
+- emptyContent renders a host-composed EmptyState/actions only for ready with no visible rows, preserving headers. Loading/error retain their Spinner and Alert/retry owners. Omit it to keep labels.empty. Distinguish an empty collection from no matching results and restore focus when an empty-state action disappears.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `toolbar` | `ReactNode` | `—` |
+| `inset` | `"standard" \| "roomy"` | `—` |
+| `emptyContent` | `ReactNode` | `—` |
+| `caption` | `string` | `Required` |
+| `hideCaption` | `boolean` | `—` |
+| `columns` | `readonly DataTableColumn[]` | `Required` |
+| `rows` | `readonly DataTableRow[]` | `Required` |
+| `density` | `"compact" \| "comfortable"` | `—` |
+| `striped` | `boolean` | `—` |
+| `minWidth` | `CSSProperties["minWidth"]` | `—` |
+| `sort` | `DataTableSort \| null` | `—` |
+| `defaultSort` | `DataTableSort \| null` | `—` |
+| `onSortChange` | `(sort: DataTableSort \| null) => void` | `—` |
+| `locale` | `string` | `—` |
+| `selectable` | `boolean` | `—` |
+| `selectedIds` | `readonly string[]` | `—` |
+| `defaultSelectedIds` | `readonly string[]` | `—` |
+| `onSelectionChange` | `(ids: string[]) => void` | `—` |
+| `page` | `number` | `—` |
+| `defaultPage` | `number` | `—` |
+| `pageSize` | `number` | `—` |
+| `onPageChange` | `(page: number) => void` | `—` |
+| `showResults` | `boolean` | `—` |
+| `paginationMode` | `"client" \| "server"` | `—` |
+| `totalRows` | `number` | `—` |
+| `selectionScope` | `"page" \| "dataset"` | `—` |
+| `state` | `"ready" \| "loading" \| "error"` | `—` |
+| `onRetry` | `() => void` | `—` |
+| `labels` | `DataTableLabels` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | `Forwarded` |

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

@@ -0,0 +1,57 @@
+# DateField
+
+Segmented Gregorian date entry with canonical form values and explicit date validation.
+
+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, DateField } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DateField label="Start date" name="start" defaultValue="2026-10-26" order="day-month-year" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses three native text segments rather than an operating-system calendar popup. Calendar and DatePicker are separate contracts.
+- Values are canonical YYYY-MM-DD dates from 0001 through 9999, or an empty string. min/max and leap years use civil date arithmetic without timezones.
+- Arrow keys adjust segments. Left/Right move at segment boundaries; IME and modifier shortcuts remain available. Use explicit order and localized segmentLabels/messages.
+- In editable fields, incomplete or invalid drafts block native submission; the hidden named field contains no stale previous date. Controlled values and form resets preserve host ownership.
+- Read only retains copying and accepted canonical submission, even outside current bounds or application constraints. It bypasses native validity without accepting partial or refused drafts. Disabled fields and fieldsets remain excluded. Introduced in the unpublished 0.2.7 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `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` | `—` |
+| `order` | `"month-day-year" \| "day-month-year" \| "year-month-day"` | `"month-day-year"` |
+| `segmentLabels` | `Partial<Record<"day" \| "month" \| "year", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string }` | `—` |
+| `validationMessage` | `string` | `—` |
+| `end` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

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

@@ -0,0 +1,67 @@
+# DatePicker
+
+A segmented date field with an integrated calendar picker and shared form value.
+
+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, DatePicker } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DatePicker label="Start date" name="start" defaultValue="2026-10-26" today="2026-10-26" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes Flood DateField, Calendar and Popover; text input and visual selection share one canonical value and form bridge.
+- Activate the calendar icon or Alt+ArrowDown in a segment. Escape/outside dismissal returns or preserves intended focus through the existing overlay engine. Selecting a day closes the calendar.
+- Read only and disabled prevent opening or date changes; native disabled fieldsets remain inert. Invalid/incomplete drafts retain native DateField validation.
+- Controlled value and open state are independently host-owned. Native form reset restores the initial uncontrolled date and preserves cancelled resets. Translate calendarLabel/openCalendarLabel, month navigation, segment labels and messages.
+- DateField remains the keyboard-entry primitive; Calendar remains independently usable. Introduced in the unpublished 0.2.7 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `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` | `—` |
+| `order` | `"month-day-year" \| "day-month-year" \| "year-month-day"` | `—` |
+| `segmentLabels` | `Partial<Record<"day" \| "month" \| "year", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string }` | `—` |
+| `validationMessage` | `string` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `calendarLabel` | `string` | `—` |
+| `openCalendarLabel` | `string` | `—` |
+| `viewLabels` | `CalendarProps["viewLabels"]` | `—` |
+| `locale` | `string` | `—` |
+| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `—` |
+| `today` | `string` | `—` |
+| `previousMonthLabel` | `string` | `—` |
+| `nextMonthLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">, "end">` | `Forwarded` |

package/dist/materials/component-date-range-field.md

@@ -0,0 +1,62 @@
+# DateRangeField
+
+Two segmented date fields with one ordered range and atomic 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, DateRangeField } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DateRangeField label="Travel dates" startName="start" endName="end" defaultValue={{start:"2026-10-12",end:"2026-10-18"}} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The value is {start,end}, with canonical YYYY-MM-DD dates or empty endpoints. Editable partial, reversed, unavailable and refused ranges block native submission. Readonly submits a complete ordered accepted pair despite current bounds/availability; partial, reversed and refused pairs stay atomic empty values.
+- Both named bridges represent one range contract. The group owns relationship validation while each DateField preserves its calendar validity and keyboard behavior.
+- Start/end names and labels are explicit; min/max, readonly/disabled, status and form reset follow the field contracts.
+- Use DateRangePicker for visual interval selection. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `hideLabel` | `boolean` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `required` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `form` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `order` | `"month-day-year" \| "day-month-year" \| "year-month-day"` | `"month-day-year"` |
+| `segmentLabels` | `Partial<Record<"day" \| "month" \| "year", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string }` | `—` |
+| `validationMessage` | `string` | `—` |
+| `label` | `string` | `Required` |
+| `value` | `DateRangeValue` | `—` |
+| `defaultValue` | `DateRangeValue` | `—` |
+| `onValueChange` | `(range: DateRangeValue) => void` | `—` |
+| `startName` | `string` | `—` |
+| `endName` | `string` | `—` |
+| `startLabel` | `string` | `"Start date"` |
+| `endLabel` | `string` | `"End date"` |
+| `end` | `ReactNode` | `—` |
+| `isDateDisabled` | `(date: string) => boolean` | `—` |
+| `isRangeDisabled` | `(range: DateRangeValue) => boolean` | `—` |
+| `rangeMessages` | `{ incomplete?: string; reversed?: string; unavailable?: string }` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">, "value" \| "defaultValue" \| "onValueChange" \| "name" \| "label" \| "end">` | `Forwarded` |

package/dist/materials/component-date-range-picker.md

@@ -0,0 +1,73 @@
+# DateRangePicker
+
+Paired date entry with one calendar popup for continuous interval selection.
+
+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, DateRangePicker } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DateRangePicker label="Travel dates" startName="start" endName="end" today="2026-10-26" defaultValue={{start:"2026-10-12",end:"2026-10-18"}} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes DateRangeField, RangeCalendar and the existing Popover engine. One popup selects start and end; it closes after an enabled complete interval.
+- The popup follows the whole fields region width and clamps to the viewport. Text and calendar editing share the same partial/complete range contract.
+- Controlled range/open state and availability remain host-owned. Escape/outside dismissal does not turn an incomplete range into a valid submission.
+- Translate endpoint, calendar and range instruction labels. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `hideLabel` | `boolean` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `required` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `form` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `order` | `"month-day-year" \| "day-month-year" \| "year-month-day"` | `—` |
+| `segmentLabels` | `Partial<Record<"day" \| "month" \| "year", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string }` | `—` |
+| `validationMessage` | `string` | `—` |
+| `label` | `string` | `Required` |
+| `value` | `DateRangeValue` | `—` |
+| `defaultValue` | `DateRangeValue` | `—` |
+| `onValueChange` | `(range: DateRangeValue) => void` | `—` |
+| `startName` | `string` | `—` |
+| `endName` | `string` | `—` |
+| `startLabel` | `string` | `—` |
+| `endLabel` | `string` | `—` |
+| `isDateDisabled` | `(date: string) => boolean` | `—` |
+| `isRangeDisabled` | `(range: DateRangeValue) => boolean` | `—` |
+| `rangeMessages` | `{ incomplete?: string; reversed?: string; unavailable?: string }` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `calendarLabel` | `string` | `—` |
+| `openCalendarLabel` | `string` | `—` |
+| `viewLabels` | `CalendarProps["viewLabels"]` | `—` |
+| `locale` | `string` | `—` |
+| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `—` |
+| `today` | `string` | `—` |
+| `previousMonthLabel` | `string` | `—` |
+| `nextMonthLabel` | `string` | `—` |
+| `rangeLabels` | `RangeCalendarProps["rangeLabels"]` | `—` |
+| `Native HTML props` | `Omit<Omit<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">, "value" \| "defaultValue" \| "onValueChange" \| "name" \| "label" \| "end">, "end">` | `Forwarded` |