@flood-md/agent 0.2.10 → 0.2.12

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` |

package/dist/materials/component-heading.md

@@ -34,5 +34,5 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` |
-| `size` | `"display" \| "large" \| "page" \| "section"` | `"page"` |
+| `size` | `"display" \| "large" \| "page" \| "section" \| "group"` | `"page"` |
 | `Native HTML props` | `HTMLAttributes<HTMLHeadingElement>` | `Forwarded` |

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

@@ -35,7 +35,9 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `tone` | `"default" \| "danger"` | `—` |
 | `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
 | `loading` | `boolean` | `—` |
 | `label` | `string` | `Required` |
+| `iconSize` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `size` |
 | `Native HTML props` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label">` | `Forwarded` |

package/dist/materials/component-menubar.md

@@ -0,0 +1,41 @@
+# Menubar
+
+Coordinated desktop application command menus with roving triggers and shared open state.
+
+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, Menubar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Menubar label="Editor commands" menus={[{id:"file",label:"File",items:[{id:"new",label:"New document"},{id:"export",label:"Export"}]},{id:"edit",label:"Edit",items:[{id:"undo",label:"Undo"},{id:"redo",label:"Redo",disabled:true}]}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Arrow keys coordinate enabled menu triggers; child menus reuse Menu focus and dismissal.
+- Use native links and NavigationList for destinations, not Menubar. Controlled openValue may refuse transitions.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `menus` | `readonly MenubarMenu[]` | `Required` |
+| `openValue` | `string \| null` | `—` |
+| `defaultOpenValue` | `string \| null` | `—` |
+| `onOpenValueChange` | `(id: string \| null) => void` | `—` |
+| `onAction` | `(menuId: string, actionId: string) => void` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `disabled` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onAction">` | `Forwarded` |

package/dist/materials/component-multi-select.md

@@ -45,6 +45,16 @@ export function Example() {
 | `toggleLabel` | `string` | `"Show options"` |
 | `clearLabel` | `string` | `"Clear selection"` |
 | `invalidSelectionMessage` | `string` | `"Select at least one 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` | `—` |
 | `value` | `readonly string[]` | `—` |
 | `defaultValue` | `readonly string[]` | `[]` |
 | `onValueChange` | `(value: string[]) => void` | `—` |

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

@@ -0,0 +1,51 @@
+# NavigationGroup
+
+Related navigation with optional headings, section actions, separators and disclosure.
+
+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, NavigationGroup, NavigationItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <NavigationGroup label="Projects">
+        <NavigationItem label="Design system" href="/projects/design" />
+        <NavigationItem label="Website" href="/projects/website" />
+      </NavigationGroup>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Groups related navigation without inventing routes or application-menu semantics. Compose actual NavigationItem destinations or NavigationTree children.
+- label, hideLabel, headingAction and separator are independent optional presentation choices. Keep headings and separators only when they clarify real relationships.
+- collapsible uses Flood Collapsible and independent expanded/defaultExpanded/onExpandedChange state; an unaccepted request does not hide accepted content.
+- Compact mode keeps destinations reachable while removing redundant heading text; compare section actions and body rows on the same rail axis.
+- Original compatible addition in the unpublished 0.2.11 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `—` |
+| `hideLabel` | `boolean` | `—` |
+| `headingAction` | `ReactNode` | `—` |
+| `separator` | `boolean` | `—` |
+| `collapsible` | `boolean` | `—` |
+| `expanded` | `boolean` | `—` |
+| `defaultExpanded` | `boolean` | `—` |
+| `onExpandedChange` | `(expanded: boolean) => void` | `—` |
+| `compact` | `boolean` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `collapseDisabled` | `boolean` | `—` |
+| `children` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "title" \| "onChange">` | `Forwarded` |

package/dist/materials/component-navigation-item.md

@@ -0,0 +1,59 @@
+# NavigationItem
+
+One shared navigation row for destinations, commands and independent disclosure.
+
+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, NavigationItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <NavigationItem label="Projects" href="/projects" current />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses Flood Link or Button; navigation links remain native anchors with host handlers. Commands and destination clicks do not silently toggle a branch.
+- disclosure without a destination makes the complete row a disclosure button. href plus disclosure creates separate link and disclosure targets in one shared surface; expanded is controlled by the host.
+- compact leaf rows retain names through Tooltip. Use NavigationTree for compact branches and link-plus-branch items so the full navigation remains reachable in a Popover.
+- IconSlot owns leading artwork; IconButton keeps the disclosure target with smaller supporting artwork. trailing is noninteractive metadata, not a place to nest another button inside a link.
+- trailingAction is an independent sibling control in expanded rows. It is visible alongside any trailing metadata. Use a named IconButton and apply its own disabled state.
+- Original compatible addition in the unpublished 0.2.11 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `description` | `string` | `—` |
+| `icon` | `ReactNode` | `—` |
+| `reserveIcon` | `boolean` | `—` |
+| `trailing` | `ReactNode` | `—` |
+| `trailingAction` | `ReactNode` | `—` |
+| `href` | `string` | `—` |
+| `linkProps` | `Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' \| 'children' \| 'aria-current'>` | `—` |
+| `onAction` | `()=>void` | `—` |
+| `actionProps` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>` | `—` |
+| `disclosure` | `NavigationItemDisclosure` | `—` |
+| `current` | `boolean` | `—` |
+| `currentKind` | `'page' \| 'location'` | `—` |
+| `ancestorCurrent` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `size` | `'sm' \| 'md' \| 'lg'` | `—` |
+| `compact` | `boolean` | `—` |
+| `variant` | `'quiet' \| 'standard'` | `—` |
+| `tooltip` | `boolean` | `—` |
+| `tooltipSide` | `'left' \| 'right'` | `—` |
+| `controlRef` | `Ref<HTMLElement>` | `—` |
+| `disclosureRef` | `Ref<HTMLButtonElement>` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, 'children' \| 'onChange'>` | `Forwarded` |

package/dist/materials/component-navigation-tree.md

@@ -27,6 +27,9 @@ export function Example() {
 - A branch may have both href and children: its native link navigates while a separate disclosure button expands. currentValue marks the matching destination; ancestors are expanded explicitly by the host.
 - Expansion is controlled or uncontrolled through expandedValues/defaultExpandedValues/onExpandedValuesChange. Translate disclosure names with expandLabel; content can render host-owned loading or empty branch content.
 - Item values must be globally unique and children acyclic. Disabled destinations have no active href; parent disability does not propagate to children. Introduced in 0.2.7.
+- compact creates an icon rail with real leaf links and full Popover navigation for branches. flyoutSide controls placement; current descendant styling is separate from aria-current. trailing accepts metadata in expanded rows. Compact labels remain accessible and have native title hints.
+- currentKind defaults to page. Use location when the active value identifies a broader global navigation context rather than the exact current page.
+- Enable branchGuides for dense nested lists. Item trailingAction uses the shared NavigationItem slot in expanded rows and on destinations inside branch flyouts.
 
 ## API reference
 
@@ -35,9 +38,14 @@ export function Example() {
 | `label` | `string` | `Required` |
 | `items` | `readonly NavigationTreeItem[]` | `Required` |
 | `currentValue` | `string` | `—` |
+| `currentKind` | `"page" \| "location"` | `—` |
 | `expandedValues` | `readonly string[]` | `—` |
 | `defaultExpandedValues` | `readonly string[]` | `—` |
 | `onExpandedValuesChange` | `(values: string[]) => void` | `—` |
 | `expandLabel` | `(item: NavigationTreeItem, expanded: boolean) => string` | `—` |
 | `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `variant` | `"quiet" \| "standard"` | `—` |
+| `compact` | `boolean` | `—` |
+| `flyoutSide` | `"left" \| "right"` | `—` |
+| `branchGuides` | `boolean` | `—` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "onChange">` | `Forwarded` |

package/dist/materials/component-overflow-actions.md

@@ -0,0 +1,47 @@
+# OverflowActions
+
+A priority-based action row that moves commands into a More menu when space is limited.
+
+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, OverflowActions } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <OverflowActions label="Document actions" shape="pill" items={[{id:"save",label:"Save",priority:10},{id:"duplicate",label:"Duplicate"},{id:"archive",label:"Archive"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Compose commands rather than links. Higher priority remains visible longer; source order is preserved.
+- Uses existing Toolbar, Button, IconSlot and Menu; hidden measurements are inert and excluded from the accessibility tree.
+- shape defaults to pill; rounded restores the field-radius Toolbar shell. Available width excludes Toolbar padding.
+- containerVariant="plain" delegates a surface-free rail to Toolbar, keeping peer control heights aligned; contained is the default. variant still styles the actions themselves.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly OverflowAction[]` | `Required` |
+| `onAction` | `(id: string) => void` | `—` |
+| `moreLabel` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `variant` | `ButtonProps["variant"]` | `—` |
+| `shape` | `ToolbarProps["shape"]` | `—` |
+| `containerVariant` | `ToolbarProps["variant"]` | `—` |
+| `disabled` | `boolean` | `—` |
+| `leading` | `ReactNode` | `—` |
+| `trailing` | `ReactNode` | `—` |
+| `maxVisibleActions` | `number` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onAction">` | `Forwarded` |

package/dist/materials/component-page-header.md

@@ -0,0 +1,40 @@
+# PageHeader
+
+The main page heading with optional supporting text and page 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, PageHeader, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <PageHeader title="Projects" actions={<Button>New project</Button>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use inside main for the page's h1. An embedded preview can choose headingLevel={2}. Use Section for titled content within the page.
+- Add a description only when it supplies context the title cannot. Keep filters in the collection toolbar.
+- Actions wrap below the title when the header's own container narrows. The heading stays first in reading and keyboard order.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
+| `headingId` | `string` | `—` |
+| `headingLevel` | `1 \| 2` | `1` |
+| `headingSize` | `"page" \| "large" \| "display"` | `"large"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "title" \| "children">` | `Forwarded` |

package/dist/materials/component-popover.md

@@ -32,7 +32,7 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `title` | `string` | `Required` |
-| `chrome` | `"default" \| "minimal"` | `—` |
+| `chrome` | `"default" \| "minimal" \| "title-only"` | `—` |
 | `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
 | `children` | `ReactNode` | `—` |
 | `open` | `boolean` | `—` |
@@ -44,4 +44,5 @@ export function Example() {
 | `closeLabel` | `string` | `"Close"` |
 | `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
 | `positionReference` | `RefObject<HTMLElement \| null>` | `—` |
+| `focusOnOpen` | `boolean` | `—` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "title" \| "role">` | `Forwarded` |

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

@@ -17,8 +17,8 @@ export function Example() {
     <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" />
+          <RadioCard name="plan" value="starter" label="Starter" description="1 project, up to 3 members" metadata="Free" defaultChecked />
+          <RadioCard name="plan" value="team" label="Team" description="Unlimited projects, up to 25 members" metadata="$12 / month" />
         </Stack>
       </Fieldset>
     </FloodRoot>

package/dist/materials/component-section.md

@@ -38,5 +38,5 @@ export function Example() {
 | `description` | `ReactNode` | `—` |
 | `actions` | `ReactNode` | `—` |
 | `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` |
-| `headingSize` | `"display" \| "large" \| "page" \| "section"` | `"section"` |
+| `headingSize` | `HeadingProps["size"]` | `"section"` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "title">` | `Forwarded` |

package/dist/materials/component-segmented-control.md

@@ -1,6 +1,6 @@
 # SegmentedControl
 
-A compact single-value choice with native radio semantics and a shared inset surface.
+A compact single-value choice or collection view switcher with native radio semantics.
 
 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.
 
@@ -15,7 +15,7 @@ import "@flood-md/react/styles.css";
 export function Example() {
   return (
     <FloodRoot>
-      <SegmentedControl label="Time range" name="period" defaultValue="day" options={[{value: "day", label: "Day"}, {value: "week", label: "Week"}, {value: "month", label: "Month"}]} />
+      <SegmentedControl label="Claims view" name="claims-view" defaultValue="pending" options={[{value: "pending", label: "Pending", count: 2}, {value: "reviewed", label: "Reviewed"}]} />
     </FloodRoot>
   );
 }
@@ -25,7 +25,9 @@ export function Example() {
 
 - Uses original RadioGroup behavior and native inputs.
 - Arrow keys move focus and select; Home/End select endpoints, skipping disabled segments. Selecting the current value does not clear it.
-- Native name/form/required, reset and controlled values are preserved. Use actual tabs for tab panels, ToggleGroup for optional pressed actions.
+- Use SegmentedControl to switch a shared collection between mutually exclusive views. Use Tabs for associated content panels and ToggleGroup for optional pressed actions.
+- An option count can communicate workload without a nested badge or a second control. Counts are read with visible labels, preserve zero, and are omitted in icon-only mode. Format localized counts before passing them.
+- Native name/form/required, reset and controlled values are preserved.
 
 ## API reference
 
@@ -44,7 +46,7 @@ export function Example() {
 | `orientation` | `"vertical" \| "horizontal"` | `"horizontal"` |
 | `required` | `boolean` | `—` |
 | `label` | `string` | `Required` |
-| `options` | `readonly ToggleOption[]` | `Required` |
+| `options` | `readonly SegmentedControlOption[]` | `Required` |
 | `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
 | `iconOnly` | `boolean` | `false` |
 | `fullWidth` | `boolean` | `false` |

package/dist/materials/component-sheet.md

@@ -0,0 +1,49 @@
+# Sheet
+
+A bottom-aligned modal for short tasks, navigation and touch-friendly 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, Sheet, Button, Field, Input } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Sheet title="Project settings" trigger={props => <Button {...props}>Open settings</Button>}>
+        <Field label="Project name">{control => <Input {...control} defaultValue="Flood" />}</Field>
+      </Sheet>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Sheet shares Drawer's modal semantics, dismissal, focus restoration, scrollable body and optional footer. Its scrollbar fits in the panel padding. Placement is always bottom.
+- The panel grows with content up to its size limit. Keep actions that must remain visible in the footer and use ListBox for selectable options.
+- Use a sheet for touch navigation or short choices that benefit from a wider target. Anchored popovers and selects remain useful on desktop. Available in 0.2.12.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `string` | `—` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `children` | `ReactNode` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `—` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `closeLabel` | `string` | `—` |
+| `closeOnOutsideClick` | `boolean` | `—` |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `footer` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">, "side">` | `Forwarded` |

package/dist/materials/component-sidebar.md

@@ -0,0 +1,64 @@
+# Sidebar
+
+A bounded workspace sidebar with grouped destinations, a compact rail and nested navigation flyouts.
+
+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, Sidebar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <div style={{height:"32rem"}}><Sidebar label="Workspace navigation" groups={[{id:"workspace",label:"Workspace",items:[{value:"overview",label:"Overview",href:"#overview"},{value:"projects",label:"Projects",children:[{value:"design",label:"Design system",href:"#design"}]}]}]} currentValue="overview" /></div>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes NavigationTree, ScrollArea, IconButton, Stack and Text. Host controls height; header/footer remain fixed while the navigation body scrolls with reserved scrollbar clearance.
+- collapsed/defaultCollapsed/onCollapsedChange control the full-width versus compact rail. Controlled refusals preserve accepted geometry. side supports logical start/end; width affects expanded mode only. collapsible=false omits the toggle.
+- groups need unique IDs and globally unique item values. Destinations retain real links; expansion and currentValue are independent. Disabled items cannot navigate or open a branch.
+- expandedValues/defaultExpandedValues/onExpandedValuesChange retain branch disclosure across width changes. In compact mode a top-level branch opens a Popover with full navigation; choosing a destination closes that flyout. No route is inferred or persisted.
+- header/footer accept content or a ({collapsed}) render function. Adapt meaningful content using that state, rather than hiding arbitrary descendants with CSS. The host owns workspace/account menus and their actions.
+- The inline headerLayout puts the expanded identity and toggle on one row. The stacked default keeps the toggle in its original place across states. Enable branchGuides per group for dense nesting.
+- Item icons use IconSlot; trailing content can compose Badge or other meaningful metadata in expanded mode. Compact destinations retain accessible names and native title labels; missing icons have a neutral fallback glyph.
+- No automatic mobile drawer, routing, resizing, keyboard shortcut or preference storage is added. Check the bounded host, enlarged text, RTL, final scroll item, real destinations and focus across collapse/flyout transitions.
+- groups can hide a redundant visual label with hideLabel while preserving the navigation name. currentKind="location" marks a global module; page is the default contextual destination. The workspace playground composes Sidebar profiles into GlobalRail plus ContextBar without duplicate flyouts.
+- variant defaults to quiet in the 0.2.11 candidate: muted inactive content, normal control weight and restrained rectangular selection through existing semantic roles. standard retains the stronger pill recipe. Both compose the same primitive anatomy and behavior; inspect them in the full-width navigation workspace.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `groups` | `readonly SidebarGroup[]` | `Required` |
+| `currentValue` | `string` | `—` |
+| `currentKind` | `NavigationTreeProps["currentKind"]` | `—` |
+| `collapsed` | `boolean` | `—` |
+| `defaultCollapsed` | `boolean` | `—` |
+| `onCollapsedChange` | `(collapsed:boolean)=>void` | `—` |
+| `collapsible` | `boolean` | `—` |
+| `collapseLabel` | `string` | `—` |
+| `expandLabel` | `string` | `—` |
+| `expandedValues` | `readonly string[]` | `—` |
+| `defaultExpandedValues` | `readonly string[]` | `—` |
+| `onExpandedValuesChange` | `(values:string[])=>void` | `—` |
+| `expandItemLabel` | `NavigationTreeProps["expandLabel"]` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `variant` | `"quiet" \| "standard"` | `—` |
+| `side` | `"start" \| "end"` | `—` |
+| `width` | `CSSProperties["width"]` | `—` |
+| `header` | `ReactNode \| (state:SidebarSlotState)=>ReactNode` | `—` |
+| `headerLayout` | `"stacked" \| "inline"` | `—` |
+| `footer` | `ReactNode \| (state:SidebarSlotState)=>ReactNode` | `—` |
+| `footerSeparator` | `boolean` | `—` |
+| `headerSeparator` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "onChange">` | `Forwarded` |

package/dist/materials/component-sparkline.md

@@ -0,0 +1,41 @@
+# Sparkline
+
+A compact line or area chart for trends in a table cell, list or metric.
+
+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, Sparkline } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Sparkline label="Revenue rose from $8,000 to $12,000" values={[8000, 8200, null, 9500, 11000, 12000]} domain={[0, 15000]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Give the graphic a label that communicates the metric and the trend. Set showLabel to make that label visible.
+- Use a shared domain for comparing magnitudes across rows. Null and nonfinite samples leave gaps in both the stroke and area.
+- The default area uses an accent stroke with a gradient below it. Choose variant line for stroke only and use semantic tones only when the data has a known interpretation.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `values` | `readonly (number \| null)[]` | `Required` |
+| `label` | `string` | `Required` |
+| `showLabel` | `boolean` | `false` |
+| `domain` | `readonly [number, number]` | `—` |
+| `size` | `"sm" \| "md"` | `"md"` |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "error"` | `"accent"` |
+| `variant` | `"line" \| "area"` | `"area"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label" \| "aria-labelledby">` | `Forwarded` |

package/dist/materials/component-table.md

@@ -42,5 +42,7 @@ export function Example() {
 | `density` | `"compact" \| "comfortable"` | `"comfortable"` |
 | `striped` | `boolean` | `false` |
 | `scrollLabel` | `string` | `—` |
+| `maxViewportHeight` | `CSSProperties["maxBlockSize"]` | `—` |
+| `stickyHeader` | `boolean` | `false` |
 | `cellVerticalAlign` | `"top" \| "middle" \| "bottom"` | `"middle"` |
 | `Native HTML props` | `Omit<TableHTMLAttributes<HTMLTableElement>, "children">` | `Forwarded` |

package/dist/materials/component-tabs.md

@@ -23,6 +23,7 @@ export function Example() {
 
 ## Design notes
 
+- Use variant="line" for page-level sections with an active marker beside the panel. The default contained variant joins tabs and content in one surface.
 - Arrow keys navigate enabled tabs; automatic activation is default, manual needs Enter/Space. Tab leaves the tablist. Horizontal direction follows RTL.
 - Inactive panels remain mounted but hidden. Keep form validation and persistent selection under host control. Invalid, missing or disabled selected values fall back to the first available item.
 
@@ -37,6 +38,7 @@ export function Example() {
 | `onValueChange` | `(value: string) => void` | `—` |
 | `activationMode` | `"automatic" \| "manual"` | `"automatic"` |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `variant` | `"contained" \| "line"` | `—` |
 | `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
 | `disabled` | `boolean` | `false` |
 | `iconOnly` | `boolean` | `false` |

package/dist/materials/component-text.md

@@ -16,8 +16,8 @@ export function Example() {
   return (
     <FloodRoot>
       <Stack gap="3">
-        <Text as="p" size="lead">A calm foundation for your next idea.</Text>
-        <Text as="p" size="compact">Use the space to make it yours.</Text>
+        <Text as="p" size="lead">Quarterly revenue</Text>
+        <Text as="p" size="compact">Revenue increased by 8% this quarter.</Text>
       </Stack>
     </FloodRoot>
   );

package/dist/materials/component-toggle.md

@@ -30,6 +30,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"` |
 | `loading` | `boolean` | `—` |
 | `pressed` | `boolean` | `—` |