@flood-md/agent 0.2.8 → 0.2.10

package/dist/materials/component-inline-code.md

@@ -0,0 +1,36 @@
+# InlineCode
+
+A small monospace code fragment that participates in running text.
+
+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, Text, InlineCode } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Text as="p">Import <InlineCode>@/ui/button</InlineCode> in your project.</Text>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Native code semantics, bundled monospace stack and a quiet inline surface. Content is text; no HTML parsing or syntax highlighting is performed.
+- wrap defaults to true for long identifiers. wrap=false preserves the fragment on one line and the host must manage overflow. Use CodeSnippet for blocks of code and Kbd for keyboard input.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `wrap` | `boolean` | `true` |
+| `Native HTML props` | `HTMLAttributes<HTMLElement>` | `Forwarded` |

package/dist/materials/component-inline.md

@@ -0,0 +1,39 @@
+# Inline
+
+A wrapping horizontal group for related content and 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, Inline, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Inline gap="2" align="center">
+        <Button>Save changes</Button>
+        <Button variant="subtle">Cancel</Button>
+      </Inline>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Inline wraps when its children need more space.
+- Use the same control size for neighboring actions of the same level.
+- Rows center items by default. Use gap="4" between independent choices; gap="2" remains available for tightly related content.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `gap` | `"0" \| "1" \| "2" \| "3" \| "4" \| "6" \| "8" \| "12"` | `"2"` |
+| `align` | `"start" \| "center" \| "end" \| "baseline"` | `"center"` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

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

@@ -0,0 +1,43 @@
+# InputGroup
+
+One native text input with logical start/end content inside a shared perimeter.
+
+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, InputGroup, Field } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Website">
+        {control => <InputGroup {...control} start="https://" placeholder="example.com" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Ref, id, name, value, events and ARIA attributes target the real input. className/style customize the outer layout wrapper.
+- start/end are logical content slots. Adornments do not become the submitted value or an accessible label; use Field or Label and explain prefixes when needed.
+- The input has one shared field perimeter and accent focus. Interactive adornments keep their own focus indication and accessible names.
+- disabled/readOnly affect the input; host-owned addon actions need their own disabled policy. Use compatible action sizes. Text-like input types are supported; Textarea/Select are separate constructs.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `type` | `"text" \| "email" \| "password" \| "search" \| "tel" \| "url" \| "number"` | `—` |
+| `start` | `ReactNode` | `—` |
+| `end` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "children" \| "type">` | `Forwarded` |

package/dist/materials/component-input.md

@@ -0,0 +1,39 @@
+# Input
+
+A native input with semantic styling and independent visual sizing.
+
+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, Input } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Workspace name">
+        {(control) => <Input {...control} defaultValue="My project" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use Field or a native associated label; placeholder text is not a label.
+- controlSize changes appearance. The native numeric size attribute keeps its HTML meaning.
+- Default outlines use the quiet field.border role. field.boundary is a stronger opt-in; preserve the independent focus indicator when customizing colors.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `Native HTML props` | `InputHTMLAttributes<HTMLInputElement>` | `Forwarded` |

package/dist/materials/component-kbd.md

@@ -0,0 +1,34 @@
+# Kbd
+
+A quiet native keyboard-input label for keys and shortcut hints.
+
+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, Kbd } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Native kbd markup, not a button or a shortcut handler. The application implements and documents actual bindings.
+- Sizes sm/md/lg use relative keycap tokens. Native props/ref target the kbd element. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"sm"` |
+| `Native HTML props` | `HTMLAttributes<HTMLElement>` | `Forwarded` |

package/dist/materials/component-label.md

@@ -0,0 +1,37 @@
+# Label
+
+A native label that connects a visible name to a control.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Label, Stack, Input } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Stack gap="2">
+        <Label htmlFor="project-label">Project name</Label>
+        <Input id="project-label" defaultValue="My project" />
+      </Stack>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- htmlFor connects the label to a matching control ID; implicit nested controls also retain native behavior.
+- required adds a decorative marker only. Set required on the actual control as well. Field already composes Label.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `required` | `boolean` | `—` |
+| `Native HTML props` | `LabelHTMLAttributes<HTMLLabelElement>` | `Forwarded` |

package/dist/materials/component-link.md

@@ -0,0 +1,35 @@
+# Link
+
+A native anchor for navigation.
+
+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, Link } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Link href="/docs/installation">Install Flood</Link>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use a button for state-changing actions and a link for navigation.
+- Link forwards native anchor attributes. Its optional solid/subtle/outline/ghost variants share Flood Button geometry; text is the unchanged default. No asChild API.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `"text" \| "solid" \| "subtle" \| "outline" \| "ghost"` | `"text"` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `Native HTML props` | `AnchorHTMLAttributes<HTMLAnchorElement>` | `Forwarded` |

package/dist/materials/component-list-box.md

@@ -0,0 +1,57 @@
+# ListBox
+
+A named single or multiple selection list with native validation and semantic feedback.
+
+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, ListBox } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ListBox label="Framework" name="framework" defaultValue="react" options={[{value:"react",label:"React"},{value:"vue",label:"Vue"},{value:"svelte",label:"Svelte"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use a scalar value/defaultValue in single mode and an array in multiple mode. onValueChange returns the matching shape. Stable, unique nonempty option IDs are submitted as repeated hidden native form fields when name is supplied. Uncontrolled reset restores the initial selection.
+- The list owns one Tab stop and aria-activedescendant. Arrows/Home/End move through enabled options; single selection follows navigation. Space/Enter selects or toggles. Typing searches option-label prefixes. Disabled options cannot be selected; readOnly retains navigation and copying without changing the value.
+- Provide a clear label or use hideLabel with the accessible label preserved. Use disabled on the composite to remove its Tab stop. The list is not virtualized and does not fetch options. Available in 0.2.5.
+- required validates accepted selection; readonly bypasses validation and disabled excludes form values.
+- description/message and status share the field feedback contract. validationMessage is a host-owned blocking constraint.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `required` | `boolean` | `—` |
+| `requiredMessage` | `string` | `—` |
+| `validationMessage` | `string` | `—` |
+| `description` | `string` | `—` |
+| `message` | `string` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `options` | `readonly ComboboxOption[]` | `Required` |
+| `value` | `string \| readonly string[]` | `—` |
+| `defaultValue` | `string \| readonly string[]` | `—` |
+| `onValueChange` | `(value: string \| string[]) => void` | `—` |
+| `multiple` | `boolean` | `false` |
+| `selectionBehavior` | `"automatic" \| "manual"` | `—` |
+| `appearance` | `"surface" \| "plain"` | `—` |
+| `disabled` | `boolean` | `false` |
+| `readOnly` | `boolean` | `false` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-list.md

@@ -0,0 +1,40 @@
+# List
+
+Native ordered or unordered content with token spacing and optional markers.
+
+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, List } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <List><li>Install the matching packages.</li><li>Import the stylesheet.</li><li>Compose with Flood.</li></List>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Supply native li children. ordered chooses ol; start/reversed apply only to ordered lists. start must be a safe integer.
+- Hiding markers retains an explicit list role for browser/assistive-technology consistency. Content may include links or controls without changing its content-list semantics.
+- This is not ListBox, a selection model or a keyboard-navigation engine.
+- Available in 0.2.4; use matching installed declarations.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `ordered` | `boolean` | `false` |
+| `start` | `number` | `—` |
+| `reversed` | `boolean` | `—` |
+| `marker` | `boolean` | `true` |
+| `gap` | `"0" \| "1" \| "2" \| "3" \| "4" \| "6" \| "8" \| "12"` | `"2"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLUListElement \| HTMLOListElement>, "role">` | `Forwarded` |

package/dist/materials/component-menu.md

@@ -0,0 +1,54 @@
+# Menu
+
+An action and preference menu with keyboard navigation and controlled checkbox/radio items.
+
+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, Menu, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Menu label="Project actions"
+        trigger={props => <Button {...props}>Project actions</Button>}
+        items={[{id:"rename",label:"Rename…"},{id:"divider",type:"separator"},{id:"delete",label:"Delete project",tone:"danger"}]}
+        onAction={id => console.log(id)}
+      />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Forward all supplied trigger props and ref to one native button or Flood Button/IconButton. Label names the menu; action labels remain visible.
+- Enter/Space and ArrowDown open at the first item; ArrowUp opens at the last. Inside use arrows, Home/End and label-prefix typeahead.
+- Disabled items stay keyboard-focusable with aria-disabled but cannot activate. Separators are noninteractive; action IDs must be unique and nonempty. At least one action is required.
+- Escape closes and restores trigger focus. Tab moves to the next control after the trigger; Shift+Tab returns to the trigger. Outside interaction dismisses without stealing deliberately moved focus.
+- Shortcut text is a visual hint, not an implemented key binding. No href or asynchronous task manager is included. Nested items use type="submenu" and a nonempty items array. Checkbox/radio items are controlled preferences, available in 0.2.7.
+- Controlled open needs host updates; onAction requests closure before calling the host. Modern native Popover API required. Native div props/ref target the popup. Available in 0.2.4.
+- Checkbox items take checked (boolean or mixed) and onCheckedChange. Radio items take a nonempty group label, checked and onCheckedChange; the host keeps one selected item per group. Keep each radio group contiguous. Preference items stay open by default; closeOnSelect opts into dismissal. They do not call onAction or submit form values.
+- Submenus open by logical arrow, click/tap or cancellable mouse hover intent. Escape closes one level; Tab leaves the entire tree through the root trigger. IDs are unique across the tree and nested keyboard searches stay inside their own menu.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `items` | `readonly MenuItem[]` | `Required` |
+| `onAction` | `(id: string) => void` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
+| `align` | `"start" \| "center" \| "end"` | `"start"` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"sm"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | `Forwarded` |

package/dist/materials/component-meter.md

@@ -0,0 +1,43 @@
+# Meter
+
+A measured value within a meaningful, finite range.
+
+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, Meter } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Meter label="Storage used" value={75} valueText="75 of 100 GB" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use Meter for storage, battery or other bounded measurements; use Progress for task completion.
+- Value is required. Min defaults to 0 and max to 100; require min < max and min <= value <= max. Invalid values throw.
+- Use valueText for meaningful units; hideLabel keeps the accessible name. Tone is host-owned and does not calculate warning thresholds.
+- Native div props, className/style and ref target the wrapper. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `max` | `number` | `100` |
+| `valueText` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `tone` | `"neutral" \| "accent" \| "error" \| "warning" \| "success" \| "info"` | `"neutral"` |
+| `hideLabel` | `boolean` | `false` |
+| `value` | `number` | `Required` |
+| `min` | `number` | `0` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">, "value">` | `Forwarded` |

package/dist/materials/component-metric.md

@@ -0,0 +1,39 @@
+# Metric
+
+A labeled value with optional contextual trend and supporting text.
+
+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, Metric } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Metric label="Monthly revenue" value="$24,580" trend={{direction:"up",label:"12.8% higher",tone:"success"}} hint="Compared with the previous month." />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Native definition-list semantics associate the label with its value, trend and hint. Values may be rich content; the host owns currency, number and locale formatting.
+- Trend direction and semantic tone are independent: a decreasing failure rate can be good. Its label must communicate the change without relying on the decorative arrow or color. No automatic percentage calculation is performed.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `value` | `ReactNode` | `Required` |
+| `hint` | `ReactNode` | `—` |
+| `trend` | `MetricTrend` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDListElement>, "children">` | `Forwarded` |

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

@@ -0,0 +1,52 @@
+# MultiSelect
+
+Search a collection, choose multiple values and manage them as removable tags.
+
+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, MultiSelect } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Frameworks">
+        {control => <MultiSelect {...control} name="frameworks" options={[{value:"react",label:"React"},{value:"vue",label:"Vue"},{value:"svelte",label:"Svelte"}]} defaultValue={["react"]} placeholder="Search frameworks" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- value/defaultValue are arrays of unique nonempty option IDs; onValueChange returns a new array. Native forms submit repeated entries with the same name, never typed query text. Uncontrolled reset restores initial values.
+- The shared Combobox search/layer model keeps focus in the input. Enter toggles the active option and the list stays open. Backspace in an empty input removes the last editable tag; a logical backward arrow at the start enters tag actions. Tag arrows, Delete/Backspace, Enter and Escape support keyboard editing.
+- Disabled selected options cannot be individually removed or cleared globally. Read-only permits copying but blocks selection and removal. Required means at least one valid selected ID. Translate removeItemLabel and the shared action/empty/validation messages.
+- No freeform values, remote fetching, virtualization or arbitrary tag selection 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` |
+| `clearable` | `boolean` | `false` |
+| `emptyMessage` | `string` | `"No results found."` |
+| `listLabel` | `string` | `"Options"` |
+| `toggleLabel` | `string` | `"Show options"` |
+| `clearLabel` | `string` | `"Clear selection"` |
+| `invalidSelectionMessage` | `string` | `"Select at least one option."` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `[]` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `removeItemLabel` | `string` | `"Remove"` |
+| `Native HTML props` | `Omit<Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children">, "value" \| "defaultValue" \| "onValueChange">` | `Forwarded` |

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

@@ -0,0 +1,38 @@
+# NavigationList
+
+A grouped list of native navigation links with a clear current destination.
+
+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, NavigationList } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <NavigationList label="Project navigation" currentValue="overview" items={[{value:"overview",label:"Overview",href:"/overview",group:"Workspace"},{value:"activity",label:"Activity",href:"/activity",group:"Workspace"},{value:"settings",label:"Settings",href:"/settings",group:"Manage"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- NavigationList renders nav, lists and native anchors; it is not an ARIA menu or tablist. The host supplies unique stable item values, destinations and currentValue. Browser modifier/target navigation is preserved through item.linkProps.
+- Optional group names label contiguous item groups. Icons are decorative IconSlot content; descriptions remain associated link text. Size controls compact row density while coarse pointer targets remain usable. No routing engine, URL inference or disabled navigation simulation is supplied.
+- Original compatible addition in the unpublished 0.2.5 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly NavigationListItem[]` | `Required` |
+| `currentValue` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

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

@@ -0,0 +1,43 @@
+# NavigationTree
+
+Nested native navigation links with separate disclosure 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, NavigationTree } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <NavigationTree label="Documentation" defaultExpandedValues={["start"]} items={[{value:"start",label:"Getting started",children:[{value:"installation",label:"Installation",href:"/docs/installation"}]}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Native nav, lists and anchors preserve ordinary Tab order and browser modifier navigation. This component does not use ARIA tree/menu/tab roles.
+- 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.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly NavigationTreeItem[]` | `Required` |
+| `currentValue` | `string` | `—` |
+| `expandedValues` | `readonly string[]` | `—` |
+| `defaultExpandedValues` | `readonly string[]` | `—` |
+| `onExpandedValuesChange` | `(values: string[]) => void` | `—` |
+| `expandLabel` | `(item: NavigationTreeItem, expanded: boolean) => string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "onChange">` | `Forwarded` |