@flood-md/agent 0.2.10 → 0.2.11

package/dist/materials/component-app-shell.md

@@ -0,0 +1,47 @@
+# AppShell
+
+A workspace layout with optional navigation, top bar and footer, plus a keyboard skip target.
+
+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, AppShell, AppTopBar, PageHeader, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AppShell topBar={<AppTopBar start={<Text>Workspace</Text>} />}><PageHeader title="Projects" /></AppShell>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Content scrolling keeps navigation, top bar and footer outside the work scrollport. Use scroll="page" for a document that scrolls as a whole.
+- Supply Sidebar for docked navigation. Set navigationDrawer with a shell-width threshold and Drawer content to swap automatically. Share accepted route and branch state between the two presentations.
+- Use mainAs="section" only when embedding a shell inside an existing main landmark.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `navigation` | `ReactNode` | `—` |
+| `navigationSide` | `"start" \| "end"` | `"start"` |
+| `navigationDrawer` | `AppShellNavigationDrawer` | `—` |
+| `topBar` | `ReactNode \| (navigationTrigger: ReactNode) => ReactNode` | `—` |
+| `footer` | `ReactNode` | `—` |
+| `scroll` | `"content" \| "page"` | `"content"` |
+| `mainId` | `string` | `—` |
+| `mainAs` | `"main" \| "section"` | `"main"` |
+| `mainLabel` | `string` | `—` |
+| `mainRef` | `Ref<HTMLElement>` | `—` |
+| `scrollLabel` | `string` | `—` |
+| `scrollOrientation` | `ScrollAreaProps["orientation"]` | `—` |
+| `skipLabel` | `string` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-app-top-bar.md

@@ -0,0 +1,36 @@
+# AppTopBar
+
+Application context and global actions in two independent, wrapping 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, AppTopBar, Text, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AppTopBar start={<Text>Workspace</Text>} end={<Button size="sm">Search</Button>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use in AppShell or in a host-owned layout. Use PageHeader for the current page's title and actions.
+- The start and end groups wrap on narrow hosts without changing keyboard order. Use bordered only where the toolbar needs a visible boundary.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `start` | `ReactNode` | `—` |
+| `end` | `ReactNode` | `—` |
+| `bordered` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children">` | `Forwarded` |

package/dist/materials/component-autocomplete.md

@@ -0,0 +1,54 @@
+# Autocomplete
+
+A free text field with optional suggestions; accepts values outside the list.
+
+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, Autocomplete } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Team">{control => <Autocomplete {...control} name="team" options={[{value:"design",label:"Design",group:"Product"},{value:"engineering",label:"Engineering",group:"Product"},{value:"operations",label:"Operations",group:"Business"}]} />}</Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The submitted value is text, not an option ID. Use Combobox for fixed choices.
+- Manual suggestions use controlled value and optionsQuery; stale results cannot be chosen. Network ownership remains with the host.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `options` | `readonly ComboboxOption[]` | `Required` |
+| `clearable` | `boolean` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `listLabel` | `string` | `—` |
+| `toggleLabel` | `string` | `—` |
+| `clearLabel` | `string` | `—` |
+| `invalidSelectionMessage` | `string` | `—` |
+| `filtering` | `"local" \| "manual"` | `—` |
+| `optionsQuery` | `string` | `—` |
+| `loadState` | `"ready" \| "loading" \| "error"` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `errorMessage` | `string` | `—` |
+| `onRetry` | `() => void` | `—` |
+| `retryLabel` | `string` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `""` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `onOptionSelect` | `(option: ComboboxOption) => void` | `—` |
+| `Native HTML props` | `Omit<Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children">, "query" \| "onQueryChange" \| "selectedOptions" \| "value" \| "defaultValue" \| "onValueChange">` | `Forwarded` |

package/dist/materials/component-bulk-action-bar.md

@@ -0,0 +1,52 @@
+# BulkActionBar
+
+A single-row selection command capsule with adaptive overflow.
+
+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, BulkActionBar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <BulkActionBar label="Selected projects" selectionCount={2}
+        items={[{id:"archive",label:"Archive",priority:10},{id:"pause",label:"Pause"},{id:"activate",label:"Set active"}]}
+        onAction={(id) => console.log(id)} onClear={() => console.log("clear")} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The default is a pill-shaped single row with at most two visible commands. maxVisibleActions accepts 1, 2 or 3; available space can reduce that number further.
+- Lower-priority commands move to More. selectionLabel, clearLabel and moreLabel support localized content; selectionCount=0 renders nothing.
+- pending disables commands and clearing. The host owns selected IDs, accepted updates, confirmation and focus after removal.
+- The component is inline by default. A floating host supplies bounded viewport positioning, safe-area spacing and scroll clearance. Use a stable width so adaptive measurement does not depend on the currently visible commands.
+- counter accepts label (default), number or none. Visible counters reserve a stable width across digit changes; counterWidth adapts that reservation to a localized label. Numeric mode retains the complete accessible selectionLabel. Hidden mode removes the slot.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `selectionCount` | `number` | `Required` |
+| `selectionLabel` | `string` | `—` |
+| `counter` | `"label" \| "number" \| "none"` | `—` |
+| `counterWidth` | `CSSProperties["inlineSize"]` | `—` |
+| `items` | `readonly OverflowAction[]` | `Required` |
+| `onAction` | `(id: string) => void` | `—` |
+| `onClear` | `() => void` | `Required` |
+| `clearLabel` | `string` | `—` |
+| `moreLabel` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `maxVisibleActions` | `1 \| 2 \| 3` | `—` |
+| `disabled` | `boolean` | `—` |
+| `pending` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onAction">` | `Forwarded` |

package/dist/materials/component-button.md

@@ -37,6 +37,7 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"solid"` |
+| `tone` | `"default" \| "danger"` | `"default"` |
 | `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
 | `loading` | `boolean` | `false` |
 | `type` | `Inherited native HTML prop` | `"button"` |

package/dist/materials/component-card.md

@@ -15,9 +15,9 @@ import "@flood-md/react/styles.css";
 export function Example() {
   return (
     <FloodRoot>
-      <Card title="Project details" description="Keep your team in sync."
+      <Card title="Project details" description="Release on 12 November"
         footer={<Button variant="subtle">Open project</Button>}>
-        <Text as="p" size="compact">A calm place for the next idea.</Text>
+        <Text as="p" size="compact">Homepage and checkout</Text>
       </Card>
     </FloodRoot>
   );

package/dist/materials/component-collapsible.md

@@ -31,6 +31,7 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `title` | `string` | `Required` |
+| `headerAction` | `ReactNode` | `—` |
 | `open` | `boolean` | `—` |
 | `defaultOpen` | `boolean` | `false` |
 | `onOpenChange` | `(open: boolean) => void` | `—` |

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-combobox.md

@@ -47,4 +47,14 @@ export function Example() {
 | `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` |

package/dist/materials/component-command-palette.md

@@ -0,0 +1,53 @@
+# CommandPalette
+
+A modal search surface for navigating pages or running commands.
+
+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, CommandPalette, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CommandPalette title="Go to page" searchLabel="Search pages" trigger={props => <Button {...props}>Go to page</Button>} items={[{id:"projects",label:"All projects"}]} onAction={id => console.log(id)} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Choose comfortable or compact density. Items can be grouped, described or disabled.
+- Opening focuses search. Enter or click runs an enabled action and requests closure. Escape and the close button return focus to the trigger.
+- Use controlled query and loading for asynchronous search. The application owns requests, navigation and any global shortcut.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `closeLabel` | `string` | `—` |
+| `closeOnOutsideClick` | `boolean` | `—` |
+| `searchLabel` | `string` | `Required` |
+| `items` | `readonly CommandListItem[]` | `Required` |
+| `density` | `"comfortable" \| "compact"` | `"comfortable"` |
+| `query` | `string` | `—` |
+| `defaultQuery` | `string` | `—` |
+| `onQueryChange` | `(query: string) => void` | `—` |
+| `onAction` | `(id: string) => void` | `Required` |
+| `loading` | `boolean` | `—` |
+| `placeholder` | `string` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">, "children" \| "description" \| "initialFocusRef">` | `Forwarded` |

package/dist/materials/component-copy-button.md

@@ -31,6 +31,7 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `tone` | `"default" \| "danger"` | `—` |
 | `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
 | `value` | `string` | `Required` |
 | `copyLabel` | `string` | `"Copy"` |

package/dist/materials/component-data-table.md

@@ -16,8 +16,8 @@ export function Example() {
   return (
     <FloodRoot>
       <DataTable caption="Projects" selectable pageSize={5}
-        columns={[{id:"name",label:"Project",sortable:true},{id:"status",label:"Status"}]}
-        rows={[{id:"design",label:"Design system",cells:{name:"Design system",status:"Active"}}]} />
+        columns={[{id:"name",label:"Project",sortable:true},{id:"status",label:"Status"},{id:"members",label:"Members",numeric:true}]}
+        rows={[{id:"design",label:"Design system",cells:{name:"Design system",status:"Active",members:12}}]} />
     </FloodRoot>
   );
 }
@@ -28,11 +28,19 @@ export function Example() {
 - Supply the complete client collection; remote/server pagination and virtualization are not part of this API.
 - Select all affects selectable rows on the current page and preserves selection on other pages.
 - Use sortValues for rich React cells; missing values sort last in both directions.
+- Use showResults={false} to omit a redundant result range. Selection feedback and pagination remain, and the footer disappears when it has no other content.
+- Set column.numeric for comparable amounts and quantities. Header and cells align to the logical end with tabular figures, while explicit align takes precedence. Keep numeric identifiers as text and provide raw sortValues for localized amounts.
+- For in-place record details, supply row.primaryAction with the identity column, title, optional description and native button props. Pointer activation extends across the row, while keyboard focus lands on the title button. Secondary controls retain their own behavior.
+- Use toolbar for the heading and filters that share the table surface. Set inset to roomy for a shared outer inset on toolbar, table cells and footer.
+- emptyContent renders a host-composed EmptyState/actions only for ready with no visible rows, preserving headers. Loading/error retain their Spinner and Alert/retry owners. Omit it to keep labels.empty. Distinguish an empty collection from no matching results and restore focus when an empty-state action disappears.
 
 ## API reference
 
 | Prop | Values | Default |
 | --- | --- | --- |
+| `toolbar` | `ReactNode` | `—` |
+| `inset` | `"standard" \| "roomy"` | `—` |
+| `emptyContent` | `ReactNode` | `—` |
 | `caption` | `string` | `Required` |
 | `hideCaption` | `boolean` | `—` |
 | `columns` | `readonly DataTableColumn[]` | `Required` |
@@ -52,6 +60,10 @@ export function Example() {
 | `defaultPage` | `number` | `—` |
 | `pageSize` | `number` | `—` |
 | `onPageChange` | `(page: number) => void` | `—` |
+| `showResults` | `boolean` | `—` |
+| `paginationMode` | `"client" \| "server"` | `—` |
+| `totalRows` | `number` | `—` |
+| `selectionScope` | `"page" \| "dataset"` | `—` |
 | `state` | `"ready" \| "loading" \| "error"` | `—` |
 | `onRetry` | `() => void` | `—` |
 | `labels` | `DataTableLabels` | `—` |

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

@@ -58,6 +58,7 @@ export function Example() {
 | `onOpenChange` | `(open: boolean) => void` | `—` |
 | `calendarLabel` | `string` | `—` |
 | `openCalendarLabel` | `string` | `—` |
+| `viewLabels` | `CalendarProps["viewLabels"]` | `—` |
 | `locale` | `string` | `—` |
 | `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `—` |
 | `today` | `string` | `—` |

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

@@ -63,6 +63,7 @@ export function Example() {
 | `onOpenChange` | `(open: boolean) => void` | `—` |
 | `calendarLabel` | `string` | `—` |
 | `openCalendarLabel` | `string` | `—` |
+| `viewLabels` | `CalendarProps["viewLabels"]` | `—` |
 | `locale` | `string` | `—` |
 | `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `—` |
 | `today` | `string` | `—` |

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

@@ -40,6 +40,8 @@ export function Example() {
 | `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` | `—` |

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

@@ -47,6 +47,10 @@ export function Example() {
 | `startTimeLabel` | `string` | `—` |
 | `endDateLabel` | `string` | `—` |
 | `endTimeLabel` | `string` | `—` |
+| `startDatePickerLabels` | `DateTimePickerProps["datePickerLabels"]` | `—` |
+| `endDatePickerLabels` | `DateTimePickerProps["datePickerLabels"]` | `—` |
+| `startTimePickerLabels` | `DateTimePickerProps["timePickerLabels"]` | `—` |
+| `endTimePickerLabels` | `DateTimePickerProps["timePickerLabels"]` | `—` |
 | `form` | `string` | `—` |
 | `required` | `boolean` | `—` |
 | `disabled` | `boolean` | `—` |

package/dist/materials/component-drawer.md

@@ -27,6 +27,7 @@ export function Example() {
 
 - 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

package/dist/materials/component-figure.md

@@ -15,7 +15,7 @@ import "@flood-md/react/styles.css";
 export function Example() {
   return (
     <FloodRoot>
-      <Figure caption="A calm foundation for the next idea."><Surface padding="6">Project preview</Surface></Figure>
+      <Figure caption="Homepage, desktop layout"><Surface padding="6">Project preview</Surface></Figure>
     </FloodRoot>
   );
 }

package/dist/materials/component-filter-condition.md

@@ -0,0 +1,53 @@
+# FilterCondition
+
+One controlled filter predicate composed from property, operator and value controls.
+
+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, FilterCondition } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <FilterCondition label="Condition 1"
+        properties={[{id:"status",label:"Status",options:[{value:"active",label:"Active"},{value:"paused",label:"Paused"}]}]}
+        value={{property:"status",operator:"is",values:["active"]}}
+        onValueChange={(condition) => console.log(condition)} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Compose one finite-choice condition from Fieldset, Field, Grid, Select, MultiSelect and IconButton. sm is the default; all controls share controlSize.
+- value and onValueChange are controlled. Changing the property proposes an empty values array; changing the operator preserves selected values. Empty values are an incomplete draft, never an instruction to match every record.
+- The host owns query evaluation, duplicate-property policy, Apply/Cancel, validation and focus after removing the row. onRemove is optional; no removal slot is reserved when omitted.
+- label names the condition group. hideLabel defaults to true; property/operator/value controls retain their accessible names. labels customizes control names, operator text, placeholder and removal text.
+- A wide host uses one row with a wider value track. Container-based reflow follows the space available to this row, including inside a popup or drawer. No extra background or border is added.
+- This version supports finite enumerated values and is/is-not predicates. Date, text, numeric operators, nested groups, remote fetching and query execution are not part of this component.
+
+## 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` |
+| `properties` | `readonly FilterConditionProperty[]` | `Required` |
+| `value` | `FilterConditionValue` | `Required` |
+| `onValueChange` | `(value: FilterConditionValue) => void` | `Required` |
+| `onRemove` | `() => void` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `labels` | `Partial<Record<"property" \| "operator" \| "values" \| "include" \| "exclude" \| "placeholder" \| "remove", string>>` | `—` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "legend" \| "onChange">` | `Forwarded` |

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

@@ -0,0 +1,55 @@
+# FilterGroup
+
+A flat controlled group of filter conditions with matching and row management.
+
+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, FilterGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <FilterGroup label="Project conditions"
+        properties={[{id:"status",label:"Status",options:[{value:"active",label:"Active"},{value:"paused",label:"Paused"}]}]}
+        value={{match:"all",conditions:[]}} onValueChange={(filters) => console.log(filters)} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes FilterCondition, SegmentedControl, Fieldset, Stack, Inline, Button and IconSlot. The group adds no separate material or decorative nested container.
+- value and onValueChange are controlled. Stable condition IDs survive row edits and removals; new rows propose an enabled available property and empty values. Empty values remain an incomplete draft.
+- All/any is shown only with at least two conditions. Removing rows preserves the selected match value. An empty group offers Add condition; it does not invent an onboarding message.
+- Duplicate properties are prevented for new choices by default. allowDuplicateProperties enables them; maxConditions optionally limits additions. Existing accepted rows are never silently deleted when constraints change. Add remains visible and disabled when no additions are available.
+- Accepted additions focus the new property control. Accepted removal focuses a surviving neighbour or Add. Refused controlled proposals do not move focus or mutate accepted conditions; delayed acceptance must not steal focus from a different target.
+- label names the group, hideLabel defaults to true, labels localizes group controls, and conditionLabels localizes each row. controlSize defaults to sm; disabled blocks all edits.
+- The host owns Apply/Cancel, accepted query evaluation, persistence, validation and server semantics. This is a flat finite-choice editor, not a nested query engine.
+
+## 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` |
+| `properties` | `readonly FilterConditionProperty[]` | `Required` |
+| `value` | `FilterGroupValue` | `Required` |
+| `onValueChange` | `(value: FilterGroupValue) => void` | `Required` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `allowDuplicateProperties` | `boolean` | `—` |
+| `maxConditions` | `number` | `—` |
+| `labels` | `Partial<Record<"match" \| "all" \| "any" \| "add" \| "condition", string>>` | `—` |
+| `conditionLabels` | `FilterConditionProps["labels"]` | `—` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "legend" \| "onChange">` | `Forwarded` |