@flood-md/agent 0.2.8 → 0.2.10

package/dist/materials/component-checkbox-group.md

@@ -0,0 +1,48 @@
+# CheckboxGroup
+
+A named multiple-choice group with a shared array value and native 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, CheckboxGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CheckboxGroup name="notifications" legend="Notifications" options={[{ value: "updates", label: "Product updates" }, { value: "releases", label: "Release notes" }]} defaultValue={["updates"]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes Fieldset and existing native choice controls. The ref targets HTMLFieldSetElement; options need unique values and visible labels.
+- value/onValueChange is controlled; defaultValue initializes an uncontrolled group. Native form reset restores uncontrolled defaults without firing onValueChange; controlled values remain owned by the host.
+- name belongs to the inputs. The form prop associates every input with an external form. Disabled options and groups follow native submission rules.
+- CheckboxGroup has no required/min/max shortcut: a required checkbox means that specific checkbox. Validate the selected array in the host and use group status/message.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `legend` | `ReactNode` | `Required` |
+| `legendSize · 0.2.10` | `"label" \| "section"` | `—` |
+| `hideLabel · 0.2.3` | `boolean` | `—` |
+| `hint` | `ReactNode` | `—` |
+| `error` | `ReactNode` | `—` |
+| `message` | `ReactNode` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `name` | `string` | `Required` |
+| `options` | `readonly ChoiceOption[]` | `Required` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `[]` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "defaultValue" \| "role">` | `Forwarded` |

package/dist/materials/component-checkbox.md

@@ -0,0 +1,37 @@
+# Checkbox
+
+A labeled native checkbox for independent choices.
+
+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, Checkbox } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Checkbox label="Send project updates" name="updates" defaultChecked />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use checked/onChange for controlled state or defaultChecked for native state.
+- Labels stay visible. Disabled does not mean read-only; explain unavailable choices outside the disabled control when needed.
+- 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.
+- indeterminate sets the native mixed state after hydration; checked still controls form submission. The host owns select-all aggregation and updates. Radio and Switch do not expose this prop.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `ReactNode` | `Required` |
+| `indeterminate` | `boolean` | `false` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | `Forwarded` |

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

@@ -0,0 +1,37 @@
+# CodeSnippet
+
+Selectable, wrapping code with an optional host-owned 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, CodeSnippet } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CodeSnippet code="git status --short" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- CodeSnippet escapes code content and uses the semantic system monospace font stack.
+- 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.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `code` | `string` | `Required` |
+| `codeDirection` | `"ltr" \| "rtl" \| "auto"` | `"ltr"` |
+| `action` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | `Forwarded` |

package/dist/materials/component-collapsible.md

@@ -0,0 +1,40 @@
+# Collapsible
+
+A named disclosure button and retained show/hide panel.
+
+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, Collapsible } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Collapsible title="Advanced settings">Additional project settings.</Collapsible>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use open/onOpenChange or defaultOpen. The panel stays mounted and hidden when closed; hidden form controls keep native form semantics.
+- Title is plain text for a stable button name. Content may be interactive. Disabled prevents trigger activation, not interaction inside an open panel.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "title" \| "onChange">` | `Forwarded` |

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

@@ -0,0 +1,49 @@
+# ColorPicker
+
+An RGB color editor with hex input, channel sliders and reusable presets.
+
+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, ColorPicker } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ColorPicker label="Accent color" defaultValue="#ff47a8" name="accent" presets={["#ff47a8", "#ffffff", "#78b8ff"]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses #rrggbb values without alpha or gradients.
+- The hex field owns native form validation; RGB controls provide an additional editing path.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `required` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg"` | `—` |
+| `presets` | `readonly string[]` | `—` |
+| `invalidMessage` | `string` | `—` |
+| `hexLabel` | `string` | `—` |
+| `channelLabels` | `readonly [string, string, string]` | `—` |
+| `presetsLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

package/dist/materials/component-color-swatch.md

@@ -0,0 +1,35 @@
+# ColorSwatch
+
+A named sample of an opaque RGB color.
+
+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, ColorSwatch } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ColorSwatch label="Flood pink" value="#ff47a8" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Opaque RGB colors only; keep a text label wherever color conveys meaning.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `value` | `string` | `Required` |
+| `label` | `string` | `Required` |
+| `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "color">` | `Forwarded` |

package/dist/materials/component-combobox.md

@@ -0,0 +1,50 @@
+# Combobox
+
+Search a defined collection and commit one option while focus stays in the input.
+
+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, Combobox } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Framework">
+        {(control) => <Combobox {...control} name="framework" options={[{value: "react", label: "React"}, {value: "vue", label: "Vue"}, {value: "svelte", label: "Svelte"}]} placeholder="Choose a framework" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Typing filters labels and optional keywords; labels remain presentation and only the selected option value is submitted. Enter commits the active option. Escape/Tab/outside interaction discard an uncommitted query. Emptying the input clears selection.
+- Native input ref, Field associations, required validity, controlled/uncontrolled value, forms/reset, read-only/disabled and IME editing are preserved. Options need unique nonempty values and labels. Disabled options remain discoverable and cannot be chosen.
+- Use clearable for the visible clear action; translate clearLabel/toggleLabel/listLabel/emptyMessage/invalidSelectionMessage. The popup reuses Flood ScrollArea and layer positioning. No arbitrary text, multiple selection, async fetching or virtualization engine is supplied. Available in 0.2.5.
+- Only the disclosure chevron is shown by default. Set clearable to opt into the extra clear-selection action; individual MultiSelect tags retain their removal buttons.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `options` | `readonly ComboboxOption[]` | `Required` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `""` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `clearable` | `boolean` | `false` |
+| `emptyMessage` | `string` | `"No results found."` |
+| `listLabel` | `string` | `"Options"` |
+| `toggleLabel` | `string` | `"Show options"` |
+| `clearLabel` | `string` | `"Clear selection"` |
+| `invalidSelectionMessage` | `string` | `"Select an option."` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

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-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,42 @@
+# 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"` |
+| `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,58 @@
+# 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"}]}
+        rows={[{id:"design",label:"Design system",cells:{name:"Design system",status:"Active"}}]} />
+    </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.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `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` | `—` |
+| `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` |