@flood-md/agent 0.2.8 → 0.2.10

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

@@ -0,0 +1,66 @@
+# 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` | `—` |
+| `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,72 @@
+# 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` | `—` |
+| `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` |

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

@@ -0,0 +1,60 @@
+# 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` | `—` |
+| `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,66 @@
+# 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` | `—` |
+| `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,50 @@
+# 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.
+- 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` |