@flood-md/agent 0.2.9 → 0.2.11

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

@@ -0,0 +1,62 @@
+# DateTimePicker
+
+A composed civil date and wall-clock time with separate 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, DateTimePicker } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DateTimePicker label="Schedule" dateName="date" timeName="time" defaultValue={{date:"2026-10-26",time:"09:30"}} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Date and time submit as separate fields. No timezone, UTC conversion or instant is inferred.
+- Date bounds and daily time bounds are independent. Use application validation for cross-field business rules.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `validationMessage` | `string` | `—` |
+| `timeInterval` | `number` | `—` |
+| `hideLabel` | `boolean` | `—` |
+| `hideFieldLabels` | `boolean` | `—` |
+| `value` | `DateTimeValue` | `—` |
+| `defaultValue` | `DateTimeValue` | `—` |
+| `onValueChange` | `(value: DateTimeValue) => void` | `—` |
+| `dateLabel` | `string` | `—` |
+| `timeLabel` | `string` | `—` |
+| `datePickerLabels` | `Pick<DatePickerProps, "calendarLabel" \| "openCalendarLabel" \| "previousMonthLabel" \| "nextMonthLabel" \| "viewLabels" \| "segmentLabels" \| "messages">` | `—` |
+| `timePickerLabels` | `Pick<TimePickerProps, "panelLabel" \| "openTimeLabel" \| "segmentLabels" \| "messages">` | `—` |
+| `dateName` | `string` | `—` |
+| `timeName` | `string` | `—` |
+| `form` | `string` | `—` |
+| `required` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `precision` | `"minute" \| "second"` | `—` |
+| `order` | `DateFieldProps["order"]` | `—` |
+| `locale` | `string` | `—` |
+| `minDate` | `string` | `—` |
+| `maxDate` | `string` | `—` |
+| `minTime` | `string` | `—` |
+| `maxTime` | `string` | `—` |
+| `step` | `number` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

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

@@ -0,0 +1,70 @@
+# DateTimeRangePicker
+
+An ordered civil date/time range with four 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, DateTimeRangePicker } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DateTimeRangePicker label="Booking" startDateName="startDate" startTimeName="startTime" endDateName="endDate" endTimeName="endTime"
+        defaultValue={{start:{date:"2026-10-27",time:"09:00"},end:{date:"2026-10-27",time:"18:00"}}} required />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Incomplete and reversed ranges do not contribute accepted values.
+- No timezone or timestamp inference. Server availability remains host owned.
+- Only range and endpoint headings are visible; individual field names remain accessible.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `DateTimeRangeValue` | `—` |
+| `defaultValue` | `DateTimeRangeValue` | `—` |
+| `onValueChange` | `(range: DateTimeRangeValue) => void` | `—` |
+| `startDateName` | `string` | `—` |
+| `startTimeName` | `string` | `—` |
+| `endDateName` | `string` | `—` |
+| `endTimeName` | `string` | `—` |
+| `startLabel` | `string` | `—` |
+| `endLabel` | `string` | `—` |
+| `startDateLabel` | `string` | `—` |
+| `startTimeLabel` | `string` | `—` |
+| `endDateLabel` | `string` | `—` |
+| `endTimeLabel` | `string` | `—` |
+| `startDatePickerLabels` | `DateTimePickerProps["datePickerLabels"]` | `—` |
+| `endDatePickerLabels` | `DateTimePickerProps["datePickerLabels"]` | `—` |
+| `startTimePickerLabels` | `DateTimePickerProps["timePickerLabels"]` | `—` |
+| `endTimePickerLabels` | `DateTimePickerProps["timePickerLabels"]` | `—` |
+| `form` | `string` | `—` |
+| `required` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `precision` | `"minute" \| "second"` | `—` |
+| `order` | `DateFieldProps["order"]` | `—` |
+| `locale` | `string` | `—` |
+| `minDate` | `string` | `—` |
+| `maxDate` | `string` | `—` |
+| `step` | `number` | `—` |
+| `interval` | `number` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `incompleteMessage` | `string` | `—` |
+| `reversedMessage` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

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

@@ -0,0 +1,42 @@
+# DescriptionList
+
+Related terms and descriptions with native list semantics and responsive grouping.
+
+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, DescriptionList } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <DescriptionList items={[
+        {id:"project",term:"Project",description:"Flood"},
+        {id:"version",term:"Version",description:"0.2.4"},
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Renders native dl/dt/dd groups. IDs are stable React keys, not generated DOM anchors; require unique nonempty IDs.
+- Inline layout becomes stacked when the component container is narrow. Stacked layout is always one column.
+- Density and dividers affect presentation. Values may contain React content; the host owns formatting and missing-value text.
+- Native dl props, className/style and HTMLDListElement ref target the list. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `items` | `readonly DescriptionItem[]` | `Required` |
+| `layout` | `"inline" \| "stacked"` | `"inline"` |
+| `density` | `"compact" \| "comfortable"` | `"compact"` |
+| `dividers` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDListElement>, "children">` | `Forwarded` |

package/dist/materials/component-dialog.md

@@ -0,0 +1,45 @@
+# Dialog
+
+A named native modal dialog with inert background and managed 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, Dialog, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Dialog title="Create a project" trigger={trigger => <Button {...trigger}>Open dialog</Button>}>Project details.</Dialog>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses native showModal, not a simulated modal div.
+- Escape closes the top layer; outside closing can be disabled independently. Tab remains inside the dialog.
+- Closed content unmounts. Forward trigger props/ref; initialFocusRef can select a safe initial control. Modern native dialog support is required.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `string` | `—` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `children` | `ReactNode` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `closeLabel` | `string` | `"Close"` |
+| `closeOnOutsideClick` | `boolean` | `true` |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">` | `Forwarded` |

package/dist/materials/component-divider.md

@@ -0,0 +1,37 @@
+# Divider
+
+A semantic separator with a low-emphasis visual line.
+
+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, Divider } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Stack gap="4">
+        <Text>Workspace</Text>
+        <Divider />
+        <Text>Account</Text>
+      </Stack>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The line is decorative in contrast terms: content grouping must remain understandable without seeing it.
+- Divider renders a native hr; it has no orientation prop.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `Native HTML props` | `HTMLAttributes<HTMLHRElement>` | `Forwarded` |

package/dist/materials/component-drawer.md

@@ -0,0 +1,51 @@
+# Drawer
+
+A modal edge panel with a steady header, scrollable body and optional footer.
+
+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, Drawer, Button, Field, Input } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Drawer title="Project settings" description="Keep the details close." trigger={props => <Button {...props}>Open settings</Button>}>
+        <Field label="Project name">{control => <Input {...control} defaultValue="Flood" />}</Field>
+      </Drawer>
+    </FloodRoot>
+  );
+}
+```
+
+## 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.
+- 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.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `string` | `—` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `children` | `ReactNode` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `closeLabel` | `string` | `"Close"` |
+| `closeOnOutsideClick` | `boolean` | `true` |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `side` | `"start" \| "end" \| "top" \| "bottom"` | `"end"` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `footer` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">` | `Forwarded` |

package/dist/materials/component-dropzone.md

@@ -0,0 +1,45 @@
+# Dropzone
+
+A file drop target composed with the native Flood FileInput.
+
+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, Dropzone } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Dropzone label="Project attachments" name="attachments" multiple accept=".pdf,image/*" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The existing FileInput remains the real chooser and successful native form control. Dropping files dispatches the same selection flow: multiple appends and deduplicates; single selection keeps the first dropped file. Native form reset and per-file removal remain intact.
+- The zone responds only to file drags and prevents navigation on file drop. Disabled fields reject drops. Translate label/description and FileInput action labels. The chooser remains keyboard accessible; dropping is an additional pointer workflow.
+- accept guides the native chooser; the host must validate dropped file types, size and contents. Directories, remote transfer, progress, server upload and image processing are outside this control. No file contents are read. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `clearable` | `boolean` | `—` |
+| `clearLabel` | `string` | `—` |
+| `selectionLabel` | `string` | `—` |
+| `removeFileLabel` | `string` | `—` |
+| `onFilesChange` | `(files: readonly File[]) => void` | `—` |
+| `label` | `string` | `Required` |
+| `description` | `string` | `"Drop files here or choose from your device."` |
+| `multiple` | `Inherited native HTML prop` | `true` |
+| `Native HTML props` | `Omit<Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "children" \| "readOnly">, "onDragEnter" \| "onDragLeave" \| "onDragOver" \| "onDrop">` | `Forwarded` |

package/dist/materials/component-editable.md

@@ -0,0 +1,57 @@
+# Editable
+
+Inline editing with explicit save/cancel and a committed 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, Editable } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Editable label="Project name" defaultValue="Flood workspace" name="project" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Preview and edit modes keep a separate draft. Enter commits and Escape cancels; IME composition does not submit.
+- Use blurAction to commit, cancel or preserve the draft on outside focus. Moving focus to the save/cancel actions is internal to the editor.
+- The host owns controlled value and editing props; callbacks request changes. The hidden named form field contains only the committed value.
+- readOnly keeps a copyable field; disabled prevents editing. Localized action labels and inputRef are available. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `editing` | `boolean` | `—` |
+| `defaultEditing` | `boolean` | `—` |
+| `onEditingChange` | `(editing: boolean) => void` | `—` |
+| `onCommit` | `(value: string) => void` | `—` |
+| `onCancel` | `() => void` | `—` |
+| `blurAction` | `"commit" \| "cancel" \| "none"` | `"commit"` |
+| `readOnly` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `placeholder` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `showActions` | `boolean` | `true` |
+| `editLabel` | `string` | `—` |
+| `saveLabel` | `string` | `—` |
+| `cancelLabel` | `string` | `—` |
+| `inputRef` | `Ref<HTMLInputElement>` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

package/dist/materials/component-empty-state.md

@@ -0,0 +1,41 @@
+# EmptyState
+
+A quiet explanation and optional next action when content is absent.
+
+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, EmptyState, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <EmptyState title="No projects yet" description="Create a project to get started." actions={<Button>Create project</Button>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes Stack, Heading, Text, IconSlot and Inline. Optional icon is decorative; title and description explain the missing content.
+- Static by default, without status/alert announcements or automatic focus. Host owns whether a result change should be announced.
+- Choose headingLevel for the page hierarchy. Density controls relative padding. Host actions remain ordinary named controls; no loading, fetching or error recovery engine is supplied.
+- Available in 0.2.4; use matching installed declarations.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `icon` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` |
+| `density` | `"compact" \| "comfortable"` | `"comfortable"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "title" \| "children">` | `Forwarded` |

package/dist/materials/component-error-summary.md

@@ -0,0 +1,40 @@
+# ErrorSummary
+
+A linked validation summary that focuses host-owned invalid fields.
+
+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, ErrorSummary } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ErrorSummary title="Review the form" errors={[{id:"project",fieldId:"project",message:"Enter a project name."}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The host supplies errors; ErrorSummary does not infer validation or submit a form. Each entry links to an exact field ID.
+- Normal activation focuses the target while modifier navigation remains native. onSelect can cancel the action before focus moves.
+- announcement defaults to off. autoFocus opts into focus on appearance, not on every error update, and suppresses duplicate live announcements. Empty errors render nothing. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `errors` | `readonly ErrorSummaryItem[]` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `announcement` | `"off" \| "polite" \| "assertive"` | `"off"` |
+| `autoFocus` | `boolean` | `false` |
+| `onSelect` | `(error: ErrorSummaryItem, event: ReactMouseEvent<HTMLAnchorElement>) => void` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "title" \| "onSelect" \| "role" \| "aria-live">` | `Forwarded` |

package/dist/materials/component-field.md

@@ -0,0 +1,46 @@
+# Field
+
+The association between a visible label, its input and supporting messages.
+
+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, Input } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Project name" required hint="Visible to your team.">
+        {(control) => <Input {...control} name="project" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Spread the supplied control props onto one Input or Textarea.
+- Field merges describedBy with hint/error IDs and forwards native required through its function child.
+- The host owns validation rules. Compose Field in a client component in Next.js.
+- Field is not a generic native div wrapper and does not forward a ref.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `message` | `ReactNode` | `—` |
+| `id` | `string` | `—` |
+| `label` | `ReactNode` | `Required` |
+| `hideLabel · 0.2.3` | `boolean` | `false` |
+| `hint` | `ReactNode` | `—` |
+| `error` | `ReactNode` | `—` |
+| `required` | `boolean` | `—` |
+| `describedBy` | `string` | `—` |
+| `children` | `(props: FieldControlProps) => ReactNode` | `Required` |

package/dist/materials/component-fieldset.md

@@ -0,0 +1,46 @@
+# Fieldset
+
+A native group with a legend, shared descriptions and disabled 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, Fieldset, Checkbox } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Fieldset legend="Notifications" hint="Choose the updates you want.">
+        <Checkbox label="Product updates" name="updates" defaultChecked />
+        <Checkbox label="Release notes" name="releases" />
+      </Fieldset>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses a real fieldset and legend, with a ref to HTMLFieldSetElement. Disabled descendants retain native form semantics.
+- The browser exempts controls in the first legend from inherited disabling. Avoid interactive legend contents unless this is intentional.
+- hint, message, error and external aria-describedby IDs are merged without duplicates. Error takes precedence over an advisory status.
+- Group status describes the group; it does not mark every child invalid, manage selected values or implement a RadioGroup/CheckboxGroup.
+- legendSize="section" gives an independent form section a 1rem semibold title and a 1rem body inset. The default "label" remains a compact choice caption; neither option changes native group semantics.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `legend` | `ReactNode` | `Required` |
+| `legendSize · 0.2.10` | `"label" \| "section"` | `"label"` |
+| `hideLabel · 0.2.3` | `boolean` | `false` |
+| `hint` | `ReactNode` | `—` |
+| `error` | `ReactNode` | `—` |
+| `message` | `ReactNode` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `Native HTML props` | `FieldsetHTMLAttributes<HTMLFieldSetElement>` | `Forwarded` |

package/dist/materials/component-figure.md

@@ -0,0 +1,36 @@
+# Figure
+
+A native figure that keeps media and its caption together.
+
+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, Figure, Surface } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Figure caption="Homepage, desktop layout"><Surface padding="6">Project preview</Surface></Figure>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes native figure and figcaption. The host supplies the image, chart, code or other self-contained content, including its own alt text or accessible name.
+- captionPosition controls DOM reading order as well as placement. Caption content may contain links. Native hidden, dir, lang, style and ref target the figure.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `caption` | `ReactNode` | `—` |
+| `captionPosition` | `"before" \| "after"` | `"after"` |
+| `Native HTML props` | `HTMLAttributes<HTMLElement>` | `Forwarded` |