@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/component-calendar.md

@@ -0,0 +1,59 @@
+# Calendar
+
+One calendar with day, month and year views, without nested popups.
+
+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, Calendar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Calendar label="Choose a date" defaultValue="2026-10-26" today="2026-10-26" weekStartsOn={1} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Calendar is a standalone visual collection. DateField handles text entry and DatePicker composes the field and calendar layer.
+- Values use canonical YYYY-MM-DD and visibleMonth uses YYYY-MM. Locale formats Gregorian month/day names; weekStartsOn is explicit.
+- Arrows move dates; Home/End move within a week and PageUp/PageDown navigate months. Controlled month refusal preserves a real focused day. Disabled dates remain discoverable but cannot select.
+- The host owns selected values, availability and side effects. Provide today for a deterministic clock in tests or rendering. Min/max bound navigation; readonly prevents selection while allowing browsing. Introduced in 0.2.7.
+- Month and year controls replace the content of this calendar. Selecting a navigation period returns to days without changing the selected date.
+- granularity="day" | "month" | "year" chooses YYYY-MM-DD, YYYY-MM or YYYY.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `granularity` | `"day" \| "month" \| "year"` | `—` |
+| `showViewControls` | `boolean` | `—` |
+| `viewLabels` | `{month?:string;year?:string;previous?:string;next?:string}` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(date: string) => void` | `—` |
+| `onDateSelect` | `(date: string) => void` | `—` |
+| `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` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

package/dist/materials/component-card.md

@@ -0,0 +1,46 @@
+# Card
+
+A structured surface for a heading, supporting content and independent 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, Card, Button, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Card title="Project details" description="Release on 12 November"
+        footer={<Button variant="subtle">Open project</Button>}>
+        <Text as="p" size="compact">Homepage and checkout</Text>
+      </Card>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Card composes Surface with optional title, description, header actions, children and footer. Missing slots add no empty wrapper or reserved space.
+- Use Surface for unstructured containment; use Card when its header/body/footer structure is useful. Card is a noninteractive div, not a button or link. Put named actions inside.
+- Title uses Heading at headingLevel (2 by default); choose the level according to the page. Supply phrasing content for the title. Description accepts supporting React content.
+- Density compact/comfortable controls padding and section rhythm using existing semantic spacing. Header actions wrap naturally; content is never clipped to the radius.
+- Root HTMLDivElement ref and native div props/style/className target the surface. The title prop is content, not the native HTML tooltip attribute. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `ReactNode` | `—` |
+| `description` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
+| `footer` | `ReactNode` | `—` |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` |
+| `density` | `"compact" \| "comfortable"` | `"comfortable"` |
+| `elevation` | `"default" \| "raised"` | `"default"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "title">` | `Forwarded` |

package/dist/materials/component-center.md

@@ -0,0 +1,39 @@
+# Center
+
+Center a constrained piece of content in both axes of an available region.
+
+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, Center, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Center minHeight="12rem" maxWidth="24rem">
+        <Text as="p">A focused message.</Text>
+      </Center>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Center supplies two-axis alignment with an inner content wrapper. minHeight sets the available vertical region; maxWidth constrains the content rather than the entire parent. Values are ordinary CSS lengths, preferably rem.
+- inline opts into inline-grid for centering within text or an inline composition. It adds no content semantics, surface, spacing between siblings or viewport positioning. Use Stack/Inline for collections and Container for page gutters.
+- Original compatible addition in the unpublished 0.2.5 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `inline` | `boolean` | `false` |
+| `maxWidth` | `string` | `—` |
+| `minHeight` | `string` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-character-count.md

@@ -0,0 +1,42 @@
+# CharacterCount
+
+Supporting character or remaining-length feedback with an explicit over-limit message.
+
+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, CharacterCount } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CharacterCount value="Make room for a clear idea." max={80} htmlFor="project-note" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Pass text through value or supply an explicit nonnegative integer count for a host-defined counting rule. The default text count uses Unicode code points, not UTF-16 code units or grapheme clusters. max is advisory and does not truncate or validate an editor.
+- mode remaining displays max minus count; count displays the current count and optional limit. An over-limit message is visible in addition to its semantic color. Translate label/overLimitLabel; lang formats the number.
+- Use htmlFor to associate supporting output with its editor and aria-describedby on the editor when appropriate. Live announcements default off to avoid announcing every keystroke; the host may opt into aria-live. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `value` | `string` | `—` |
+| `count` | `number` | `—` |
+| `max` | `number` | `—` |
+| `mode` | `"count" \| "remaining"` | `"count"` |
+| `label` | `string` | `"Characters"` |
+| `overLimitLabel` | `string` | `"Over limit"` |
+| `htmlFor` | `string` | `—` |
+| `form` | `string` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLOutputElement>` | `Forwarded` |

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

@@ -0,0 +1,39 @@
+# CheckCard
+
+A native checkbox 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, CheckCard } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CheckCard label="Product updates" description="A monthly summary of new features." name="updates" value="product" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses native checkbox semantics, including mixed state, required and form reset.
+- Content is noninteractive: do not nest links or actions inside a card label.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `indeterminate` | `boolean` | `—` |
+| `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-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,41 @@
+# 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` |
+| `headerAction` | `ReactNode` | `—` |
+| `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-collection-toolbar.md

@@ -0,0 +1,68 @@
+# CollectionToolbar
+
+Search, applied filter summaries and filter disclosure in one collection query row.
+
+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, CollectionToolbar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CollectionToolbar label="Project collection" searchValue="" onSearchValueChange={(search) => console.log(search)}
+        searchLabel="Search projects" appliedFilters={[{id:"status",label:"Status: Active"}]}
+        onRemoveFilter={(id) => console.log(id)} onClear={() => console.log("clear")} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes Fieldset, Field, SearchInput, Inline, Tag, Popover, Button and IconSlot. Uses normal Tab order rather than the action-only Toolbar roving model. No additional material, title or result count is invented.
+- searchValue and accepted appliedFilters are host-owned. onSearchValueChange, onRemoveFilter and onClear request changes; callbacks do not imply acceptance. Summaries need meaningful labels and unique IDs.
+- filterContent supplies the existing filter editor, including FilterGroup or a project-specific form. The host retains draft validation, Apply/Cancel, query evaluation, persistence and saved views. filtersOpen/onFiltersOpenChange optionally control the existing Popover; filterPanelRef and filterPanelClassName support real panel focus and sizing.
+- Clear keeps its space immediately before the right-anchored Filters trigger while inactive. Removing a summary or clearing returns focus to Filters, or Search when no panel exists. Filter disclosure is omitted when no filterContent is supplied.
+- quickFilters is an optional slot for at most two task-important properties; larger property sets belong inside filterContent. The host owns the threshold and slot behavior. Supply canClear when active state is not represented by searchValue/appliedFilters, such as controls in that slot.
+- Search, accepted summaries and commands share a responsive row; long summaries can wrap without clipping and the filter action remains at the logical end. Saved-view selectors and save/rename actions stay outside this query row.
+- controlSize defaults to sm; action/field sizes and chip typography follow the shared family. disabled applies to the complete fieldset, including native quick-filter controls and panel descendants. Labels and summaries remain host-localizable.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `legendSize · 0.2.10` | `"label" \| "section"` | `—` |
+| `hideLabel · 0.2.3` | `boolean` | `—` |
+| `hint` | `ReactNode` | `—` |
+| `error` | `ReactNode` | `—` |
+| `message` | `ReactNode` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `label` | `string` | `Required` |
+| `searchValue` | `string` | `Required` |
+| `onSearchValueChange` | `(value: string) => void` | `Required` |
+| `searchLabel` | `string` | `—` |
+| `searchPlaceholder` | `string` | `—` |
+| `clearSearchLabel` | `string` | `—` |
+| `appliedFilters` | `readonly CollectionFilterSummary[]` | `—` |
+| `onRemoveFilter` | `(id: string) => void` | `—` |
+| `appliedFiltersLabel` | `string` | `—` |
+| `summaryPrefix` | `ReactNode` | `—` |
+| `quickFilters` | `ReactNode` | `—` |
+| `filterContent` | `ReactNode` | `—` |
+| `filtersLabel` | `string` | `—` |
+| `filterTitle` | `string` | `—` |
+| `filtersOpen` | `boolean` | `—` |
+| `onFiltersOpenChange` | `(open: boolean) => void` | `—` |
+| `filterPanelRef` | `Ref<HTMLDivElement>` | `—` |
+| `filterPanelClassName` | `string` | `—` |
+| `onClear` | `() => void` | `—` |
+| `canClear` | `boolean` | `—` |
+| `clearLabel` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "legend" \| "onChange">` | `Forwarded` |

package/dist/materials/component-collection-view-switcher.md

@@ -0,0 +1,49 @@
+# CollectionViewSwitcher
+
+A controlled view selector with adaptive commands, separate from the active filter query.
+
+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, CollectionViewSwitcher } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CollectionViewSwitcher label="Project view" views={[{id:"all",name:"All projects"},{id:"active",name:"Active projects"}]} value="all" onValueChange={(id) => console.log(id)} actions={[{id:"create",label:"Save as new view"}]} onAction={(id) => console.log(id)} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Compose Field, Select, Button, IconSlot, Inline and OverflowActions. controlSize defaults to sm; no extra surface surrounds the selector and commands.
+- value and onValueChange represent the accepted view ID. Commands request onAction(id); the component does not create, rename, delete, persist or execute queries. Keep application errors and confirmation in their existing host owners.
+- The host supplies only applicable actions: save a new definition, update an editable changed definition, reset a dirty query, rename or delete an editable definition. A dirty working query does not silently modify the selected definition.
+- One action uses Button directly. Multiple actions use priority-based OverflowActions with View actions disclosure at constrained widths. Source order remains meaningful; destructive actions belong last.
+- label names the hidden Field label. actionsLabel and moreLabel localize command names; views supply localized names. selectRef exposes the Select focus target for host-owned dialogs. disabled blocks selection and commands; per-view and per-action disabled flags remain supported.
+- Keep this row outside CollectionToolbar. Changing the selected view may reset the host query and selection, but saving or renaming a definition must not reset unrelated result selection.
+- The command rail uses the shared plain Toolbar variant so its outer height matches the adjacent Select, without a second container around the actions.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `views` | `readonly CollectionViewOption[]` | `Required` |
+| `value` | `string` | `Required` |
+| `onValueChange` | `(id:string)=>void` | `Required` |
+| `actions` | `readonly OverflowAction[]` | `—` |
+| `onAction` | `(id:string)=>void` | `—` |
+| `actionsLabel` | `string` | `—` |
+| `moreLabel` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `disabled` | `boolean` | `—` |
+| `selectRef` | `Ref<HTMLSelectElement>` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "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,60 @@
+# 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."` |
+| `query` | `string` | `—` |
+| `onQueryChange` | `(query: string) => void` | `—` |
+| `filtering` | `"local" \| "manual"` | `—` |
+| `optionsQuery` | `string` | `—` |
+| `selectedOptions` | `readonly ComboboxOption[]` | `—` |
+| `loadState` | `"ready" \| "loading" \| "error"` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `errorMessage` | `string` | `—` |
+| `onRetry` | `() => void` | `—` |
+| `retryLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children">` | `Forwarded` |