@flood-md/agent 0.2.9 → 0.2.11

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-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,51 @@
+# 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.
+- 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
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `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-number-input.md

@@ -0,0 +1,47 @@
+# NumberInput
+
+A native numeric field with integrated decrement and increment 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, Field, NumberInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Seats">
+        {(control) => <NumberInput {...control} name="seats" defaultValue={5} min={0} max={20} />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Values are finite numbers or null for an empty field. onValueChange reports edits and button/arrow steps; native min/max/step validity remains available. Out-of-bound typed values clamp on blur; a step mismatch remains native validation.
+- Ref and native form attributes target the input. Controlled value stays host-owned; uncontrolled form reset restores the initial value. Buttons use explicit accessible names, which can be translated.
+- Use Field for labels and feedback. Read-only remains selectable and prevents stepping. No currency/locale formatting or wheel interception is supplied. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `value` | `number \| null` | `—` |
+| `defaultValue` | `number \| null` | `0` |
+| `onValueChange` | `(value: number \| null) => void` | `—` |
+| `min` | `number` | `—` |
+| `max` | `number` | `—` |
+| `step` | `number` | `1` |
+| `decreaseLabel` | `string` | `"Decrease value"` |
+| `increaseLabel` | `string` | `"Increase value"` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "min" \| "max" \| "step" \| "children">` | `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-pagination.md

@@ -0,0 +1,44 @@
+# Pagination
+
+Controlled page navigation with bounded page windows, buttons or native links.
+
+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, Pagination } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Pagination page={1} pageCount={20} getHref={page => `?page=${page}`} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use getHref for native route links, onPageChange for local controlled data, or both for a navigation notification. Modifier clicks retain browser behavior.
+- Page and pageCount must be positive safe integers within range. Empty datasets can omit Pagination. siblingCount 0/1/2 controls compactness; endpoints are noninteractive when unavailable.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `page` | `number` | `Required` |
+| `pageCount` | `number` | `Required` |
+| `onPageChange` | `(page: number) => void` | `—` |
+| `getHref` | `(page: number) => string` | `—` |
+| `siblingCount` | `0 \| 1 \| 2` | `1` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"sm"` |
+| `disabled` | `boolean` | `false` |
+| `label` | `string` | `"Pagination"` |
+| `previousLabel` | `string` | `"Previous page"` |
+| `nextLabel` | `string` | `"Next page"` |
+| `pageLabel` | `(page: number) => string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "onChange">` | `Forwarded` |

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

@@ -0,0 +1,43 @@
+# PasswordInput
+
+A password field with one named visibility 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, Field, PasswordInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Password">
+        {control => <PasswordInput {...control} name="password-input" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use visible/onVisibleChange for controlled visibility or defaultVisible for an initial reveal. Translate showPasswordLabel/hidePasswordLabel. Read-only still permits inspection; disabled blocks actions. Native value/onChange, autocomplete, form and ref are preserved. Visibility does not change the value.
+- Composes Flood InputGroup, IconSlot and IconButton using existing semantic geometry and feedback states. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `visible` | `boolean` | `—` |
+| `defaultVisible` | `boolean` | `false` |
+| `onVisibleChange` | `(visible: boolean) => void` | `—` |
+| `showPasswordLabel` | `string` | `"Show password"` |
+| `hidePasswordLabel` | `string` | `"Hide password"` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "children">` | `Forwarded` |

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

@@ -0,0 +1,45 @@
+# PinInput
+
+One native code editor presented as a compact row of character 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, PinInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <PinInput label="Verification code" name="code" length={6} autoComplete="one-time-code" required />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- One real native input preserves mobile one-time-code autofill, clipboard, selection, forms and required validity; decorative slots are hidden from assistive technology. Use its native ref for focus. The host owns verification and authentication.
+- length is an integer from 1 to 12. mode numeric permits ASCII digits; alphanumeric also permits ASCII letters. Paste strips separators and invalid characters, then respects the selection and length. Backspace and arrow editing remain native. Use mask to visually conceal the code.
+- Use value/onValueChange or defaultValue. Native form reset restores the initial uncontrolled value. Pattern validity requires a complete code when nonempty; required also rejects an empty code. Translate label and preserve its accessible name with hideLabel. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `length` | `number` | `6` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `mode` | `"numeric" \| "alphanumeric"` | `"numeric"` |
+| `mask` | `boolean` | `false` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "children" \| "value" \| "defaultValue" \| "onChange" \| "pattern" \| "size">` | `Forwarded` |

package/dist/materials/component-popover.md

@@ -0,0 +1,48 @@
+# Popover
+
+A nonmodal contextual dialog in the native top layer.
+
+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, Popover, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Popover title="Project settings" trigger={trigger => <Button {...trigger}>Settings</Button>}>Project details.</Popover>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Forward all trigger props and ref.
+- Escape, outside pointer and focus leaving dismiss. Focus enters content and returns when appropriate; Tab is not trapped.
+- Closed content unmounts; keep persistent data in the host. Uses native Popover API within the existing DOM/theme scope.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `chrome` | `"default" \| "minimal" \| "title-only"` | `—` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `children` | `ReactNode` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
+| `align` | `"start" \| "center" \| "end"` | `"start"` |
+| `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-progress.md

@@ -0,0 +1,42 @@
+# Progress
+
+Completion of a task, with a determinate or unknown value.
+
+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, Progress } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Progress label="Uploading files" value={60} valueText="60%" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Omit value for indeterminate progress. The accessible progressbar omits aria-valuenow in that state.
+- Max defaults to 100; values must be finite and inside 0..max. Invalid ranges throw instead of silently inventing a percentage.
+- hideLabel removes the caption visually while keeping the accessible name. valueText supplies human-readable units.
+- This is not a live region or a task manager. Native div props, className/style and ref target the wrapper. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `value` | `number` | `—` |
+| `max` | `number` | `100` |
+| `valueText` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `tone` | `"neutral" \| "accent" \| "error" \| "warning" \| "success" \| "info"` | `"accent"` |
+| `hideLabel` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | `Forwarded` |

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

@@ -0,0 +1,43 @@
+# RadioCard
+
+A native radio choice presented as a selectable content card.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Fieldset, Stack, RadioCard } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Fieldset legend="Plan">
+        <Stack gap="2">
+          <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>
+  );
+}
+```
+
+## Design notes
+
+- Group choices in a Fieldset and give them the same name.
+- Native arrow-key behavior, forms and reset remain available. Apply readOnly consistently to the whole group.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `icon` | `ReactNode` | `—` |
+| `metadata` | `ReactNode` | `—` |
+| `density` | `"compact" \| "comfortable"` | `—` |
+| `Native HTML props` | `Omit<Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size">, "label" \| "children">` | `Forwarded` |

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

@@ -0,0 +1,49 @@
+# RadioGroup
+
+A named single-choice group with native radio keyboard and form behavior.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, RadioGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <RadioGroup name="visibility" legend="Visibility" options={[{ value: "private", label: "Private" }, { value: "team", label: "Team" }]} defaultValue="private" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes Fieldset and existing native choice controls. The ref targets HTMLFieldSetElement; options need unique values and visible labels.
+- value/onValueChange is controlled; defaultValue initializes an uncontrolled group. Native form reset restores uncontrolled defaults without firing onValueChange; controlled values remain owned by the host.
+- name belongs to the inputs. The form prop associates every input with an external form. Disabled options and groups follow native submission rules.
+- RadioGroup supports native required. CheckboxGroup returns repeated name/value entries; validate minimum/maximum selections in the host and explain errors through status/message.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `legend` | `ReactNode` | `Required` |
+| `legendSize · 0.2.10` | `"label" \| "section"` | `—` |
+| `hideLabel · 0.2.3` | `boolean` | `—` |
+| `hint` | `ReactNode` | `—` |
+| `error` | `ReactNode` | `—` |
+| `message` | `ReactNode` | `—` |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `name` | `string` | `Required` |
+| `options` | `readonly ChoiceOption[]` | `Required` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` |
+| `required` | `boolean` | `—` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "defaultValue" \| "role">` | `Forwarded` |

package/dist/materials/component-radio.md

@@ -0,0 +1,39 @@
+# Radio
+
+A labeled native radio for one choice within a group.
+
+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, Radio } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <fieldset>
+        <legend>Visibility</legend>
+        <Radio label="Private" name="visibility" value="private" defaultChecked />
+        <Radio label="Public" name="visibility" value="public" />
+      </fieldset>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Radios in one group share a name. The host supplies fieldset and legend.
+- Native browser keyboard and form behavior remain available.
+- The control and visible label form one content-width unit with an 8px-at-16px-root internal gap. Use an explicit parent gap="4" (16px at that root) between units; the glyph keeps its token-defined size.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `ReactNode` | `Required` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | `Forwarded` |