@flood-md/agent 0.2.9 → 0.2.10

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

@@ -0,0 +1,46 @@
+# TagInput
+
+Free-form text tokens with keyboard entry, removal and named form values.
+
+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, TagInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TagInput label="Topics" defaultValue={["Design", "React"]} name="topics" placeholder="Add a topic…" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use TagInput for values the user may create. Use MultiSelect for a fixed option collection.
+- Enter and configured delimiters commit trimmed, unique tags. Pasting separated text adds multiple tags. IME composition is preserved.
+- Each committed tag submits one entry under name. required applies to committed tags; a draft is not a submitted token. Form reset preserves controlled ownership.
+- Backspace on an empty draft removes the last token. Read only preserves copying and form values; disabled omits submission and removal. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `—` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `delimiters` | `readonly string[]` | `—` |
+| `removeLabel` | `string` | `"Remove"` |
+| `requiredMessage` | `string` | `"Add at least one tag."` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children" \| "size">` | `Forwarded` |

package/dist/materials/component-tag.md

@@ -0,0 +1,40 @@
+# Tag
+
+A compact label with an optional icon and a named removal action.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Tag } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Tag onRemove={() => { /* Update the host collection. */ }}>Design</Tag>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Tag is a label, not a status Badge or a selection toggle. The host owns removal; onRemove never hides the element automatically. Use ordinary noninteractive label content.
+- Plain text gets a default Remove label. Rich content needs explicit removeLabel. disabled prevents removal; size and decorative icon are independent. removeButtonProps customizes the nested native action while Tag owns type, name, disabled and removal.
+- Standalone removal is an ordinary Tab stop. MultiSelect supplies its composite keyboard model. Geometry uses relative Flood sizing; long labels wrap and touch targets remain distinct. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `icon` | `ReactNode` | `—` |
+| `disabled` | `boolean` | `false` |
+| `onRemove` | `() => void` | `—` |
+| `removeLabel` | `string` | `—` |
+| `removeButtonProps` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "type" \| "disabled" \| "onClick" \| "aria-label">` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLSpanElement>` | `Forwarded` |

package/dist/materials/component-text.md

@@ -0,0 +1,39 @@
+# Text
+
+Role-based interface text, from introductory copy to small supporting details.
+
+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, Stack, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+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>
+      </Stack>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use as="p" for paragraphs. The label size does not create a form association.
+- Subtle is a supplementary tone; evaluate small required instructions against the actual background and font size.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `as` | `"span" \| "p" \| "div"` | `"span"` |
+| `size` | `"lead" \| "body" \| "compact" \| "label" \| "helper"` | `"body"` |
+| `tone` | `"default" \| "subtle" \| "error" \| "success" \| "warning" \| "info"` | `"default"` |
+| `Native HTML props` | `HTMLAttributes<HTMLElement>` | `Forwarded` |

package/dist/materials/component-textarea.md

@@ -0,0 +1,38 @@
+# Textarea
+
+Native multiline input for notes and longer 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, Field, Textarea } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Project note" hint="Keep it short and useful.">
+        {(control) => <Textarea {...control} rows={3} maxLength={500} />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Rows, maxLength, value/defaultValue and form props remain native.
+- The default has no resize grip. Long text scrolls inside the field; a host can opt into native resizing with style={{ resize: "vertical" }}.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `Native HTML props` | `TextareaHTMLAttributes<HTMLTextAreaElement>` | `Forwarded` |

package/dist/materials/component-time-field.md

@@ -0,0 +1,56 @@
+# TimeField
+
+Segmented 24-hour time entry with canonical values, bounds and a seconds-based step.
+
+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, TimeField } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TimeField label="Start time" name="startTime" defaultValue="09:30" step={300} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use HH:mm with minute precision or HH:mm:ss with second precision. Values have no date or timezone.
+- step is expressed in seconds and anchored to min or midnight; minute precision requires a multiple of 60. Overnight ranges are not inferred.
+- In editable fields, incomplete, invalid, out-of-range, step-mismatched and refused controlled drafts block native submission. Readonly preserves accepted canonical time outside bounds/step alignment; it never accepts a partial or refused draft. Disabled values are excluded.
+- Click the control background to focus a missing or remembered segment. Keyboard steps, Home/End, paste and IME preserve host cancellation. Translate segmentLabels and messages. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `end` | `ReactNode` | `—` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `precision` | `"minute" \| "second"` | `"minute"` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `step` | `number` | `—` |
+| `required` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `segmentLabels` | `Partial<Record<"hour" \| "minute" \| "second", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string; stepMismatch?: string }` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

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

@@ -0,0 +1,60 @@
+# TimePicker
+
+A segmented time field with an anchored, keyboard-accessible list of clock times.
+
+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, TimePicker } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TimePicker label="Start time" name="time" defaultValue="09:30" min="08:00" max="18:00" interval={1800} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Interval and step use seconds; the list contains at most 1000 entries.
+- Manual entry remains available; this is wall-clock time without timezone conversion.
+- One flat list, with selected-time visibility and a trailing action aligned with DatePicker.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `precision` | `"minute" \| "second"` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `step` | `number` | `—` |
+| `required` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `description` | `string` | `—` |
+| `segmentLabels` | `Partial<Record<"hour" \| "minute" \| "second", string>>` | `—` |
+| `messages` | `{ required?: string; invalid?: string; outOfRange?: string; stepMismatch?: string }` | `—` |
+| `interval` | `number` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `—` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `panelLabel` | `string` | `—` |
+| `openTimeLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">, "end">` | `Forwarded` |

package/dist/materials/component-timeline.md

@@ -0,0 +1,38 @@
+# Timeline
+
+An ordered sequence of events with state, context and optional time labels.
+
+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, Timeline } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Timeline label="Project activity" items={[{id:"created",title:"Project created",state:"complete"},{id:"review",title:"Design review",state:"current"},{id:"release",title:"Release",state:"upcoming"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The native ordered list is read in the supplied order; the component does not sort or group events. IDs/titles are nonempty, IDs are unique and at most one event may be current.
+- Each state has a visually hidden text equivalent; localize stateLabels. timeLabel is user-facing text and dateTime, when supplied, is the machine-readable time. Both are host-owned.
+- Markers and optional artwork are decorative. This is an event display, not a wizard or navigation control. Long descriptions and times wrap without changing marker alignment.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly TimelineItem[]` | `Required` |
+| `stateLabels` | `{complete?: string; current?: string; upcoming?: string}` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLOListElement>, "children">` | `Forwarded` |

package/dist/materials/component-toast-region.md

@@ -0,0 +1,42 @@
+# ToastRegion
+
+A host-controlled notification queue with timed, pausable messages 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, ToastRegion } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ToastRegion items={[{id:"saved",title:"Changes saved",status:"success",duration:0}]} onDismiss={id => { /* Remove the item from host state. */ }} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The host owns items and removes them onDismiss. IDs must be unique/nonempty. limit controls visible items; queued timers start only when visible. Ordinary messages default to five seconds; error/action messages persist unless duration is explicit. duration=0 persists.
+- Timers pause on hover, focus and hidden documents. F8 focuses the first visible region without interrupting initial task focus; hotkey=false disables it. Use a single main region per document. Localize label/closeLabel and message/action text. Error messages announce as alerts; others use polite status.
+- placement is logical start/end. inline embeds the region in a host container; fixed mode uses ordinary document stacking, so place a contextual region inside a modal if needed. Action callbacks do not dismiss automatically. No global notification store or promise API. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `items` | `readonly ToastItem[]` | `Required` |
+| `onDismiss` | `(id: string) => void` | `Required` |
+| `label` | `string` | `"Notifications"` |
+| `closeLabel` | `string` | `"Dismiss notification"` |
+| `placement` | `"top-start" \| "top-end" \| "bottom-start" \| "bottom-end"` | `"bottom-end"` |
+| `limit` | `number` | `3` |
+| `inline` | `boolean` | `false` |
+| `hotkey` | `boolean` | `true` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | `Forwarded` |

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

@@ -0,0 +1,44 @@
+# ToggleGroup
+
+Optional single or multiple selections exposed as pressed buttons.
+
+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, ToggleGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ToggleGroup label="Text formatting" defaultValue={["bold"]} options={[{value: "bold", label: "Bold"}, {value: "italic", label: "Italic"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Tab reaches each enabled action. Arrows/Home/End move focus without selecting. Single selection can be cleared.
+- Use RadioGroup for form choices and tabs for switching panels. ToggleGroup does not submit form values.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `options` | `readonly ToggleOption[]` | `Required` |
+| `selectionMode` | `"single" \| "multiple"` | `"multiple"` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `[]` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `disabled` | `boolean` | `false` |
+| `iconOnly` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role" \| "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-toggle.md

@@ -0,0 +1,39 @@
+# Toggle
+
+A native button with a persistent pressed 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, Toggle } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Toggle defaultPressed>Bold</Toggle>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Keep the accessible name stable; Enter/Space toggle pressed. Supports controlled pressed/onPressedChange or defaultPressed.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `loading` | `boolean` | `—` |
+| `pressed` | `boolean` | `—` |
+| `defaultPressed` | `boolean` | `false` |
+| `onPressedChange` | `(pressed: boolean) => void` | `—` |
+| `iconOnly` | `boolean` | `false` |
+| `Native HTML props` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-pressed" \| "type" \| "role" \| "defaultValue">` | `Forwarded` |

package/dist/materials/component-toolbar.md

@@ -0,0 +1,42 @@
+# Toolbar
+
+A compact action panel with one Tab entry and directional keyboard 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, Toolbar, Button, Toggle } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Toolbar label="Editor actions">
+        <Button variant="ghost">Undo</Button>
+        <Toggle variant="ghost">Bold</Toggle>
+        <Button variant="ghost">Share</Button>
+      </Toolbar>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use Button, IconButton, Toggle, native buttons/links and Menu triggers. Keep inputs, Select, Tabs and ToggleGroup outside this action-only toolbar.
+- Arrows move focus without activation; Home/End jump to the ends. Disabled and hidden actions are skipped. One Tab entry is established after hydration; before JavaScript native child tab order remains.
+- Horizontal arrows follow writing direction. Vertical arrows move between actions; open a vertical toolbar Menu with Enter/Space. Horizontal menus retain ArrowUp/Down opening.
+- loop defaults to true. Native div props/ref target the toolbar; preserve a meaningful label. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `loop` | `boolean` | `true` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | `Forwarded` |

package/dist/materials/component-tooltip.md

@@ -0,0 +1,40 @@
+# Tooltip
+
+Brief text help on hover or focus, with collision-aware placement.
+
+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, Tooltip, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Tooltip content="Additional context" trigger={trigger => <Button {...trigger}>Hover or focus</Button>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Requires native Popover API.
+- Forward trigger props and ref to one actual button. Tooltip is text-only; interactive content belongs in Popover.
+- Escape dismisses. Hover can move onto the tooltip; focus stays on the trigger. Do not use it as the only accessible name or essential instruction.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `content` | `string` | `Required` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` |
+| `align` | `"start" \| "center" \| "end"` | `"center"` |
+| `delay` | `number` | `300` |
+| `disabled` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "content" \| "title" \| "role">` | `Forwarded` |

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

@@ -0,0 +1,56 @@
+# TreeSelect
+
+Single selection from a hierarchical collection inside a popup.
+
+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, TreeSelect } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <TreeSelect label="Destination" name="destination" items={[{value:"design",label:"Design",selectable:false,children:[{value:"foundations",label:"Foundations"},{value:"components",label:"Components"}]}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- This first version selects one item; Tree provides standalone multiple selection.
+- Values are globally unique and expansion remains independent of selection.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `items` | `readonly TreeItem[]` | `Required` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `placeholder` | `string` | `—` |
+| `name` | `string` | `—` |
+| `form` | `string` | `—` |
+| `required` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `invalid` | `boolean` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `—` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `expandedValues` | `readonly string[]` | `—` |
+| `defaultExpandedValues` | `readonly string[]` | `—` |
+| `onExpandedValuesChange` | `(values: string[]) => void` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `invalidSelectionMessage` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onChange" \| "defaultValue">` | `Forwarded` |

package/dist/materials/component-tree.md

@@ -0,0 +1,52 @@
+# Tree
+
+A selectable application hierarchy with independent expansion and keyboard focus.
+
+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, Tree } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Tree label="Project files" items={[{value:"source",label:"Source",children:[{value:"button",label:"Button.tsx"}]}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Tree uses tree/treeitem/group semantics, logical arrows, Home/End and typeahead. Moving focus does not select an item. Enter/Space explicitly selects; multiple selection does not cascade.
+- Items have globally unique values. Expansion uses expandedValues/defaultExpandedValues/onExpandedValuesChange; selection uses value/defaultValue/onValueChange. Controlled refusal preserves the host state.
+- Read-only allows browsing without selecting. Disabled items remain discoverable but cannot select or expand. hasChildren/loading represent host-owned deferred branches; no fetching or virtualization is built in.
+- Application selection writes no form values. Use NavigationTree for ordinary native links. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `—` |
+| `items` | `readonly TreeItem[]` | `Required` |
+| `value` | `string \| readonly string[]` | `—` |
+| `defaultValue` | `string \| readonly string[]` | `—` |
+| `onValueChange` | `(value: string \| string[]) => void` | `—` |
+| `multiple` | `boolean` | `—` |
+| `expandedValues` | `readonly string[]` | `—` |
+| `defaultExpandedValues` | `readonly string[]` | `—` |
+| `onExpandedValuesChange` | `(values: string[]) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `emptyMessage` | `string` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `unloadedMessage` | `string` | `—` |
+| `readOnlyMessage` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onSelect" \| "defaultValue" \| "onChange">` | `Forwarded` |