@flood-md/agent 0.2.8 → 0.2.10

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

@@ -0,0 +1,47 @@
+# NumberInput
+
+A native numeric field with integrated decrement and increment 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, Field, NumberInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Seats">
+        {(control) => <NumberInput {...control} name="seats" defaultValue={5} min={0} max={20} />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Values are finite numbers or null for an empty field. onValueChange reports edits and button/arrow steps; native min/max/step validity remains available. Out-of-bound typed values clamp on blur; a step mismatch remains native validation.
+- Ref and native form attributes target the input. Controlled value stays host-owned; uncontrolled form reset restores the initial value. Buttons use explicit accessible names, which can be translated.
+- Use Field for labels and feedback. Read-only remains selectable and prevents stepping. No currency/locale formatting or wheel interception is supplied. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `value` | `number \| null` | `—` |
+| `defaultValue` | `number \| null` | `0` |
+| `onValueChange` | `(value: number \| null) => void` | `—` |
+| `min` | `number` | `—` |
+| `max` | `number` | `—` |
+| `step` | `number` | `1` |
+| `decreaseLabel` | `string` | `"Decrease value"` |
+| `increaseLabel` | `string` | `"Increase value"` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "min" \| "max" \| "step" \| "children">` | `Forwarded` |

package/dist/materials/component-pagination.md

@@ -0,0 +1,44 @@
+# Pagination
+
+Controlled page navigation with bounded page windows, buttons or native links.
+
+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, Pagination } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Pagination page={1} pageCount={20} getHref={page => `?page=${page}`} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use getHref for native route links, onPageChange for local controlled data, or both for a navigation notification. Modifier clicks retain browser behavior.
+- Page and pageCount must be positive safe integers within range. Empty datasets can omit Pagination. siblingCount 0/1/2 controls compactness; endpoints are noninteractive when unavailable.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `page` | `number` | `Required` |
+| `pageCount` | `number` | `Required` |
+| `onPageChange` | `(page: number) => void` | `—` |
+| `getHref` | `(page: number) => string` | `—` |
+| `siblingCount` | `0 \| 1 \| 2` | `1` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"sm"` |
+| `disabled` | `boolean` | `false` |
+| `label` | `string` | `"Pagination"` |
+| `previousLabel` | `string` | `"Previous page"` |
+| `nextLabel` | `string` | `"Next page"` |
+| `pageLabel` | `(page: number) => string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "onChange">` | `Forwarded` |

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

@@ -0,0 +1,43 @@
+# PasswordInput
+
+A password field with one named visibility 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, Field, PasswordInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Password">
+        {control => <PasswordInput {...control} name="password-input" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use visible/onVisibleChange for controlled visibility or defaultVisible for an initial reveal. Translate showPasswordLabel/hidePasswordLabel. Read-only still permits inspection; disabled blocks actions. Native value/onChange, autocomplete, form and ref are preserved. Visibility does not change the value.
+- Composes Flood InputGroup, IconSlot and IconButton using existing semantic geometry and feedback states. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `visible` | `boolean` | `—` |
+| `defaultVisible` | `boolean` | `false` |
+| `onVisibleChange` | `(visible: boolean) => void` | `—` |
+| `showPasswordLabel` | `string` | `"Show password"` |
+| `hidePasswordLabel` | `string` | `"Hide password"` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "children">` | `Forwarded` |

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

@@ -0,0 +1,45 @@
+# PinInput
+
+One native code editor presented as a compact row of character slots.
+
+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, PinInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <PinInput label="Verification code" name="code" length={6} autoComplete="one-time-code" required />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- One real native input preserves mobile one-time-code autofill, clipboard, selection, forms and required validity; decorative slots are hidden from assistive technology. Use its native ref for focus. The host owns verification and authentication.
+- length is an integer from 1 to 12. mode numeric permits ASCII digits; alphanumeric also permits ASCII letters. Paste strips separators and invalid characters, then respects the selection and length. Backspace and arrow editing remain native. Use mask to visually conceal the code.
+- Use value/onValueChange or defaultValue. Native form reset restores the initial uncontrolled value. Pattern validity requires a complete code when nonempty; required also rejects an empty code. Translate label and preserve its accessible name with hideLabel. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `length` | `number` | `6` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `mode` | `"numeric" \| "alphanumeric"` | `"numeric"` |
+| `mask` | `boolean` | `false` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "children" \| "value" \| "defaultValue" \| "onChange" \| "pattern" \| "size">` | `Forwarded` |

package/dist/materials/component-popover.md

@@ -0,0 +1,47 @@
+# Popover
+
+A nonmodal contextual dialog in the native top layer.
+
+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, Popover, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Popover title="Project settings" trigger={trigger => <Button {...trigger}>Settings</Button>}>Project details.</Popover>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Forward all trigger props and ref.
+- Escape, outside pointer and focus leaving dismiss. Focus enters content and returns when appropriate; Tab is not trapped.
+- Closed content unmounts; keep persistent data in the host. Uses native Popover API within the existing DOM/theme scope.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `chrome` | `"default" \| "minimal"` | `—` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `children` | `ReactNode` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
+| `align` | `"start" \| "center" \| "end"` | `"start"` |
+| `closeLabel` | `string` | `"Close"` |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `positionReference` | `RefObject<HTMLElement \| null>` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "title" \| "role">` | `Forwarded` |

package/dist/materials/component-progress.md

@@ -0,0 +1,42 @@
+# Progress
+
+Completion of a task, with a determinate or unknown 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, Progress } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Progress label="Uploading files" value={60} valueText="60%" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Omit value for indeterminate progress. The accessible progressbar omits aria-valuenow in that state.
+- Max defaults to 100; values must be finite and inside 0..max. Invalid ranges throw instead of silently inventing a percentage.
+- hideLabel removes the caption visually while keeping the accessible name. valueText supplies human-readable units.
+- This is not a live region or a task manager. Native div props, className/style and ref target the wrapper. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `value` | `number` | `—` |
+| `max` | `number` | `100` |
+| `valueText` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `tone` | `"neutral" \| "accent" \| "error" \| "warning" \| "success" \| "info"` | `"accent"` |
+| `hideLabel` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | `Forwarded` |

package/dist/materials/component-radio-card.md

@@ -0,0 +1,43 @@
+# RadioCard
+
+A native radio choice presented as a selectable content card.
+
+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, Stack, RadioCard } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Fieldset legend="Plan">
+        <Stack gap="2">
+          <RadioCard name="plan" value="starter" label="Starter" description="For your next idea." metadata="Free" defaultChecked />
+          <RadioCard name="plan" value="team" label="Team" description="For working together." metadata="$12 / month" />
+        </Stack>
+      </Fieldset>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Group choices in a Fieldset and give them the same name.
+- Native arrow-key behavior, forms and reset remain available. Apply readOnly consistently to the whole group.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `icon` | `ReactNode` | `—` |
+| `metadata` | `ReactNode` | `—` |
+| `density` | `"compact" \| "comfortable"` | `—` |
+| `Native HTML props` | `Omit<Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size">, "label" \| "children">` | `Forwarded` |

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

@@ -0,0 +1,49 @@
+# RadioGroup
+
+A named single-choice group with native radio keyboard and 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, RadioGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <RadioGroup name="visibility" legend="Visibility" options={[{ value: "private", label: "Private" }, { value: "team", label: "Team" }]} defaultValue="private" />
+    </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.
+- RadioGroup supports native required. CheckboxGroup returns repeated name/value entries; validate minimum/maximum selections in the host and explain errors through 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` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` |
+| `required` | `boolean` | `—` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "defaultValue" \| "role">` | `Forwarded` |

package/dist/materials/component-radio.md

@@ -0,0 +1,39 @@
+# Radio
+
+A labeled native radio for one choice within a group.
+
+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, Radio } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <fieldset>
+        <legend>Visibility</legend>
+        <Radio label="Private" name="visibility" value="private" defaultChecked />
+        <Radio label="Public" name="visibility" value="public" />
+      </fieldset>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Radios in one group share a name. The host supplies fieldset and legend.
+- Native browser keyboard and form behavior remain available.
+- The control and visible label form one content-width unit with an 8px-at-16px-root internal gap. Use an explicit parent gap="4" (16px at that root) between units; the glyph keeps its token-defined size.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `ReactNode` | `Required` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | `Forwarded` |

package/dist/materials/component-range-calendar.md

@@ -0,0 +1,58 @@
+# RangeCalendar
+
+A Gregorian grid for selecting and previewing one continuous date interval.
+
+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, RangeCalendar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <RangeCalendar label="Choose travel dates" today="2026-10-26" defaultValue={{start:"2026-10-12",end:"2026-10-18"}} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The first activation chooses a start; the second completes a normalized ordered interval. Hover and focus can preview an unfinished interval without committing.
+- Controlled values include partial {start,end:""}; the host must accept that partial value to advance selection. onRangeSelect confirms an enabled completed interval.
+- isDateDisabled controls endpoints. isRangeDisabled validates the entire interval; interior blocked dates are not inferred by scanning arbitrary date spans.
+- Reuses the Calendar grid, month navigation, focus and localization contracts. Translate rangeLabels for instruction messages. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `showViewControls` | `boolean` | `—` |
+| `viewLabels` | `{month?:string;year?:string;previous?:string;next?:string}` | `—` |
+| `visibleMonth` | `string` | `—` |
+| `defaultVisibleMonth` | `string` | `—` |
+| `onVisibleMonthChange` | `(month: string) => void` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `isDateDisabled` | `(date: string) => boolean` | `—` |
+| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0` |
+| `locale` | `string` | `"en-US"` |
+| `autoFocus` | `boolean` | `false` |
+| `today` | `string` | `—` |
+| `previousMonthLabel` | `string` | `—` |
+| `nextMonthLabel` | `string` | `—` |
+| `value` | `DateRangeValue` | `—` |
+| `defaultValue` | `DateRangeValue` | `—` |
+| `onValueChange` | `(range: DateRangeValue) => void` | `—` |
+| `onRangeSelect` | `(range: DateRangeValue) => void` | `—` |
+| `isRangeDisabled` | `(range: DateRangeValue) => boolean` | `—` |
+| `rangeLabels` | `{ chooseStart?: string; chooseEnd?: string; unavailable?: string }` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">, "value" \| "defaultValue" \| "onValueChange" \| "onDateSelect" \| "granularity">` | `Forwarded` |

package/dist/materials/component-rating.md

@@ -0,0 +1,46 @@
+# Rating
+
+A compact star rating backed by a named native radio group.
+
+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, Rating } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Rating label="Your experience" name="experience" defaultValue={3} max={5} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Provide a nonempty name for native radio grouping and form submission. value/defaultValue are integers from zero (unselected) to max; max is an integer from 1 to 10. Uncontrolled native reset restores defaultValue. required uses native group validation.
+- Arrow keys follow logical direction, Home/End jump to the first/last value, and Space selects the focused radio. One radio is in Tab order. readOnly keeps the current selection focusable without allowing changes; disabled is native.
+- Use getValueLabel to localize each radio name. The stars are decorative; native named radios carry the value. hideLabel preserves the legend for assistive technology. No fractional values or review submission engine is included. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `value` | `number` | `—` |
+| `defaultValue` | `number` | `0` |
+| `max` | `number` | `5` |
+| `onValueChange` | `(value: number) => void` | `—` |
+| `getValueLabel` | `(value: number, max: number) => string` | `—` |
+| `readOnly` | `boolean` | `false` |
+| `required` | `boolean` | `—` |
+| `name` | `string` | `Required` |
+| `form` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "onChange" \| "defaultValue">` | `Forwarded` |

package/dist/materials/component-resizable-panels.md

@@ -0,0 +1,48 @@
+# ResizablePanels
+
+Two panels separated by an accessible pointer and keyboard resize control.
+
+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, ResizablePanels, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ResizablePanels label="Resize workspace" main={<Text>Navigation</Text>} secondary={<Text>Workspace</Text>} style={{height:"16rem"}} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Percentages describe the main pane and exclude the dedicated separator track. The host supplies content and scrolling.
+- Drag the separator or use logical arrow keys, Home/End and Shift for large steps. Horizontal resizing follows RTL direction.
+- value/onValueChange keeps the host in control. onValueCommit reports an accepted completed interaction; pointer cancellation restores the initial uncontrolled size.
+- The separator occupies space so its touch area does not overlap panel content. Persisting layout and larger panel graphs belong to the host. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `main` | `ReactNode` | `Required` |
+| `secondary` | `ReactNode` | `Required` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `value` | `number` | `—` |
+| `defaultValue` | `number` | `50` |
+| `onValueChange` | `(percent: number) => void` | `—` |
+| `onValueCommit` | `(percent: number) => void` | `—` |
+| `min` | `number` | `10` |
+| `max` | `number` | `90` |
+| `step` | `number` | `1` |
+| `largeStep` | `number` | `10` |
+| `disabled` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-scroll-area.md

@@ -0,0 +1,42 @@
+# ScrollArea
+
+Native scrolling with inset overlay scrollbars that preserve content width.
+
+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, ScrollArea, Stack, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ScrollArea aria-label="Recent activity" style={{ maxHeight: "12rem" }}>
+        <Stack gap="4">
+          <Text>Project created.</Text>
+          <Text>Workspace updated.</Text>
+        </Stack>
+      </ScrollArea>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Scrollbars overlay the viewport with an inset; they do not reserve a content gutter. Give the viewport an explicit height or maxHeight to produce vertical overflow.
+- The forwarded ref, className, style and native div props belong to the scrollable viewport. Supply a visible context or accessible label for keyboard users.
+- Wheel, touch and keyboard scrolling remain native. Default contentInset="scrollbar" keeps text and full-width rows clear of rails with inner padding, without shrinking the viewport. Explicit none allows edge-to-edge content when the host already provides safe padding. Rails automatically avoid rounded clipping corners.
+- Forced colors restores native scrollbars as an accessibility fallback. Verify horizontal and RTL content, resizing and zoom in the host composition.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `orientation` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` |
+| `contentInset` | `"none" \| "scrollbar"` | `"scrollbar"` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

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

@@ -0,0 +1,40 @@
+# SearchInput
+
+A native search field with a leading search icon and one clear 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, Field, SearchInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Search">
+        {control => <SearchInput {...control} name="search-input" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Native onChange, name, form, reset, ref and Field associations are preserved. clearable defaults to true; read-only hides the clear action. Translate clearLabel. Enter keeps native form submission; filtering belongs to the host.
+- Composes Flood InputGroup, IconSlot and IconButton using existing semantic geometry and feedback states. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `clearable` | `boolean` | `true` |
+| `clearLabel` | `string` | `"Clear search"` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "children">` | `Forwarded` |