@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/component-range-calendar.md

@@ -0,0 +1,58 @@
+# RangeCalendar
+
+A Gregorian grid for selecting and previewing one continuous date interval.
+
+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, RangeCalendar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <RangeCalendar label="Choose travel dates" today="2026-10-26" defaultValue={{start:"2026-10-12",end:"2026-10-18"}} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The first activation chooses a start; the second completes a normalized ordered interval. Hover and focus can preview an unfinished interval without committing.
+- Controlled values include partial {start,end:""}; the host must accept that partial value to advance selection. onRangeSelect confirms an enabled completed interval.
+- isDateDisabled controls endpoints. isRangeDisabled validates the entire interval; interior blocked dates are not inferred by scanning arbitrary date spans.
+- Reuses the Calendar grid, month navigation, focus and localization contracts. Translate rangeLabels for instruction messages. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `showViewControls` | `boolean` | `—` |
+| `viewLabels` | `{month?:string;year?:string;previous?:string;next?:string}` | `—` |
+| `visibleMonth` | `string` | `—` |
+| `defaultVisibleMonth` | `string` | `—` |
+| `onVisibleMonthChange` | `(month: string) => void` | `—` |
+| `min` | `string` | `—` |
+| `max` | `string` | `—` |
+| `disabled` | `boolean` | `—` |
+| `readOnly` | `boolean` | `—` |
+| `isDateDisabled` | `(date: string) => boolean` | `—` |
+| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0` |
+| `locale` | `string` | `"en-US"` |
+| `autoFocus` | `boolean` | `false` |
+| `today` | `string` | `—` |
+| `previousMonthLabel` | `string` | `—` |
+| `nextMonthLabel` | `string` | `—` |
+| `value` | `DateRangeValue` | `—` |
+| `defaultValue` | `DateRangeValue` | `—` |
+| `onValueChange` | `(range: DateRangeValue) => void` | `—` |
+| `onRangeSelect` | `(range: DateRangeValue) => void` | `—` |
+| `isRangeDisabled` | `(range: DateRangeValue) => boolean` | `—` |
+| `rangeLabels` | `{ chooseStart?: string; chooseEnd?: string; unavailable?: string }` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">, "value" \| "defaultValue" \| "onValueChange" \| "onDateSelect" \| "granularity">` | `Forwarded` |

package/dist/materials/component-rating.md

@@ -0,0 +1,46 @@
+# Rating
+
+A compact star rating backed by a named native radio 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, Rating } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Rating label="Your experience" name="experience" defaultValue={3} max={5} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Provide a nonempty name for native radio grouping and form submission. value/defaultValue are integers from zero (unselected) to max; max is an integer from 1 to 10. Uncontrolled native reset restores defaultValue. required uses native group validation.
+- Arrow keys follow logical direction, Home/End jump to the first/last value, and Space selects the focused radio. One radio is in Tab order. readOnly keeps the current selection focusable without allowing changes; disabled is native.
+- Use getValueLabel to localize each radio name. The stars are decorative; native named radios carry the value. hideLabel preserves the legend for assistive technology. No fractional values or review submission engine is included. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `hideLabel` | `boolean` | `false` |
+| `value` | `number` | `—` |
+| `defaultValue` | `number` | `0` |
+| `max` | `number` | `5` |
+| `onValueChange` | `(value: number) => void` | `—` |
+| `getValueLabel` | `(value: number, max: number) => string` | `—` |
+| `readOnly` | `boolean` | `false` |
+| `required` | `boolean` | `—` |
+| `name` | `string` | `Required` |
+| `form` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "onChange" \| "defaultValue">` | `Forwarded` |

package/dist/materials/component-resizable-panels.md

@@ -0,0 +1,48 @@
+# ResizablePanels
+
+Two panels separated by an accessible pointer and keyboard resize 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, ResizablePanels, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ResizablePanels label="Resize workspace" main={<Text>Navigation</Text>} secondary={<Text>Workspace</Text>} style={{height:"16rem"}} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Percentages describe the main pane and exclude the dedicated separator track. The host supplies content and scrolling.
+- Drag the separator or use logical arrow keys, Home/End and Shift for large steps. Horizontal resizing follows RTL direction.
+- value/onValueChange keeps the host in control. onValueCommit reports an accepted completed interaction; pointer cancellation restores the initial uncontrolled size.
+- The separator occupies space so its touch area does not overlap panel content. Persisting layout and larger panel graphs belong to the host. Introduced in 0.2.7.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `main` | `ReactNode` | `Required` |
+| `secondary` | `ReactNode` | `Required` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `value` | `number` | `—` |
+| `defaultValue` | `number` | `50` |
+| `onValueChange` | `(percent: number) => void` | `—` |
+| `onValueCommit` | `(percent: number) => void` | `—` |
+| `min` | `number` | `10` |
+| `max` | `number` | `90` |
+| `step` | `number` | `1` |
+| `largeStep` | `number` | `10` |
+| `disabled` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-scroll-area.md

@@ -0,0 +1,42 @@
+# ScrollArea
+
+Native scrolling with inset overlay scrollbars that preserve content width.
+
+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, ScrollArea, Stack, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ScrollArea aria-label="Recent activity" style={{ maxHeight: "12rem" }}>
+        <Stack gap="4">
+          <Text>Project created.</Text>
+          <Text>Workspace updated.</Text>
+        </Stack>
+      </ScrollArea>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Scrollbars overlay the viewport with an inset; they do not reserve a content gutter. Give the viewport an explicit height or maxHeight to produce vertical overflow.
+- The forwarded ref, className, style and native div props belong to the scrollable viewport. Supply a visible context or accessible label for keyboard users.
+- Wheel, touch and keyboard scrolling remain native. Default contentInset="scrollbar" keeps text and full-width rows clear of rails with inner padding, without shrinking the viewport. Explicit none allows edge-to-edge content when the host already provides safe padding. Rails automatically avoid rounded clipping corners.
+- Forced colors restores native scrollbars as an accessibility fallback. Verify horizontal and RTL content, resizing and zoom in the host composition.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `orientation` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` |
+| `contentInset` | `"none" \| "scrollbar"` | `"scrollbar"` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

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

@@ -0,0 +1,40 @@
+# SearchInput
+
+A native search field with a leading search icon and one clear 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, SearchInput } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Search">
+        {control => <SearchInput {...control} name="search-input" />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Native onChange, name, form, reset, ref and Field associations are preserved. clearable defaults to true; read-only hides the clear action. Translate clearLabel. Enter keeps native form submission; filtering belongs to the host.
+- 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"` |
+| `clearable` | `boolean` | `true` |
+| `clearLabel` | `string` | `"Clear search"` |
+| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "children">` | `Forwarded` |

package/dist/materials/component-section.md

@@ -0,0 +1,42 @@
+# Section
+
+A named document section with a compact heading, supporting description and optional 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, Section, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Section title="Project settings" description="Manage details your team shares." headingLevel={2}>
+        <Text as="p">Section content.</Text>
+      </Section>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Section renders a native section and heading. A generated heading ID labels the region; explicit id creates a deterministic heading ID. headingLevel follows the host document hierarchy.
+- The title and description share a close text column; actions align separately and wrap when necessary. It adds no surface or border. Compose Surface or another container inside when content needs its own background.
+- Original compatible addition in the unpublished 0.2.5 source candidate.
+- headingLevel chooses h2–h6 for the document outline; it does not set the visual scale. headingSize independently selects the existing Heading typography role (section by default).
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` |
+| `headingSize` | `"display" \| "large" \| "page" \| "section"` | `"section"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "title">` | `Forwarded` |

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

@@ -0,0 +1,53 @@
+# SegmentedControl
+
+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.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, SegmentedControl } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <SegmentedControl label="Claims view" name="claims-view" defaultValue="pending" options={[{value: "pending", label: "Pending", count: 2}, {value: "reviewed", label: "Reviewed"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- 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.
+- 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
+
+| 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"` | `—` |
+| `name` | `string` | `Required` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(value: string) => void` | `—` |
+| `orientation` | `"vertical" \| "horizontal"` | `"horizontal"` |
+| `required` | `boolean` | `—` |
+| `label` | `string` | `Required` |
+| `options` | `readonly SegmentedControlOption[]` | `Required` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `iconOnly` | `boolean` | `false` |
+| `fullWidth` | `boolean` | `false` |
+| `Native HTML props` | `Omit<Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "children" \| "defaultValue" \| "role">, "legend" \| "options">` | `Forwarded` |

package/dist/materials/component-select.md

@@ -0,0 +1,45 @@
+# Select
+
+A Flood choice field with its own popup and native form integration.
+
+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, Select } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Field label="Visibility">
+        {(control) => (
+          <Select {...control} name="visibility" defaultValue="private">
+            <option value="private">Private</option>
+            <option value="team">Team</option>
+          </Select>
+        )}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Single selection uses a Flood trigger and listbox, including the popup. Native options and optgroups supply the choices; disabled choices cannot be selected.
+- Use arrows, Home/End and typing to navigate; Enter or Space confirms, Escape cancels. The popup scrolls active choices into view.
+- Select fills its Field; constrain the form or field wrapper. Multiple and numeric size greater than one use a native inline listbox rather than a popup.
+- A native form bridge preserves name, value/defaultValue, required, disabled, onChange and HTMLSelectElement ref. Inspect the matching guide for the visible focus contract.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
+| `invalid` | `boolean` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `Native HTML props` | `SelectHTMLAttributes<HTMLSelectElement>` | `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-skeleton.md

@@ -0,0 +1,42 @@
+# Skeleton
+
+A decorative placeholder that reserves space for loading content.
+
+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, Skeleton } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Stack gap="2">
+        <Skeleton width="65%" />
+        <Skeleton />
+        <Skeleton width="80%" />
+      </Stack>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Always hidden from assistive technology. The host owns loading announcements and aria-busy on the relevant region.
+- Width and height accept CSS dimensions; style overrides them. Match the final content geometry.
+- Animation can be disabled; reduced motion and forced colors disable the pulse. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `shape` | `"text" \| "rounded" \| "circle"` | `"text"` |
+| `width` | `CSSProperties["width"]` | `—` |
+| `height` | `CSSProperties["height"]` | `—` |
+| `animate` | `boolean` | `true` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "role" \| "tabIndex" \| "aria-label" \| "aria-hidden">` | `Forwarded` |

package/dist/materials/component-skip-link.md

@@ -0,0 +1,37 @@
+# SkipLink
+
+A native skip-navigation link revealed on focus and aimed at a page content target.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, SkipLink } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <SkipLink href="#main-content" />
+      <main id="main-content" tabIndex={-1}>Page content</main>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Place SkipLink early in DOM order and point href at a nonempty same-page fragment. The target should have tabIndex=-1 (or already be focusable). Native fragment navigation updates the URL; the component then focuses and reveals the target.
+- It stays visually hidden until focused. The click handler respects prevented events, modifier navigation and new-window targets. Reduced motion uses immediate scrolling. It does not create a focus trap or change the target tabindex.
+- Original compatible addition in the unpublished 0.2.5 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `href` | `string` | `Required` |
+| `children` | `Inherited native HTML prop` | `"Skip to content"` |
+| `Native HTML props` | `Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">` | `Forwarded` |

package/dist/materials/component-slider.md

@@ -0,0 +1,51 @@
+# Slider
+
+One value or an ordered range with native keyboard controls on a shared rail.
+
+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, Slider } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Slider label="Price range" name="price" defaultValue={[25, 75]} min={0} max={100} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- value/defaultValue contain one number or an ordered pair. onValueChange returns a new array. Values snap to min-based steps and thumbs cannot cross; Tab order stays stable. Supply thumbLabels to translate or explain each handle.
+- Horizontal only. Direction follows the host, including RTL. Native range inputs retain keyboard behavior; pointer selection chooses the nearest handle. Names submit one or two entries; uncontrolled reset restores defaults.
+- hideLabel preserves the accessible legend; showValue only controls the visible numeric readout. Read-only prevents edits while keeping focus. Use hint/message/error for meaning beyond color. Touch assistive technology needs device testing. Available in 0.2.5.
+
+## 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` |
+| `value` | `readonly number[]` | `—` |
+| `defaultValue` | `readonly number[]` | `[50]` |
+| `onValueChange` | `(value: number[]) => void` | `—` |
+| `min` | `number` | `0` |
+| `max` | `number` | `100` |
+| `step` | `number` | `1` |
+| `thumbLabels` | `readonly string[]` | `—` |
+| `showValue` | `boolean` | `true` |
+| `readOnly` | `boolean` | `false` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `Native HTML props` | `Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "legend" \| "children" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-spinner.md

@@ -0,0 +1,37 @@
+# Spinner
+
+A sized loading indicator with an optional accessible status label.
+
+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, Spinner } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Spinner label="Loading workspace" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Standalone indicators expose a status with a localizable label. Decorative indicators are hidden from assistive technology.
+- Button loading uses this indicator decoratively and keeps the button name. Do not announce every spinner in a busy area.
+- Use Progress when completion is measurable. Reduced motion stops rotation. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `label` | `string` | `"Loading"` |
+| `decorative` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "role" \| "aria-label" \| "aria-hidden">` | `Forwarded` |

package/dist/materials/component-split.md

@@ -0,0 +1,40 @@
+# Split
+
+A responsive main-and-supporting layout with logical pane placement and container-based collapse.
+
+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, Split, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Split side="end" ratio="main" collapseAt="md" main={<Text as="p">Main content</Text>} aside={<Text as="p">Supporting content</Text>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- main and aside are content slots in generic div panes; they do not introduce duplicate main landmarks. side places the supporting pane at logical start/end and preserves the same DOM reading order. ratio chooses equal panes or a 2:1 emphasis on main/aside.
+- Container queries collapse at sm=30rem, md=48rem or lg=64rem; never retains two columns. gap uses the spacing scale. This is layout composition, with no resizing gesture, saved pane sizes or splitter keyboard model.
+- Original compatible addition in the unpublished 0.2.5 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `main` | `ReactNode` | `Required` |
+| `aside` | `ReactNode` | `Required` |
+| `side` | `"start" \| "end"` | `"end"` |
+| `ratio` | `"balanced" \| "main" \| "aside"` | `"main"` |
+| `collapseAt` | `"sm" \| "md" \| "lg" \| "never"` | `"md"` |
+| `gap` | `"0" \| "1" \| "2" \| "3" \| "4" \| "6" \| "8" \| "12"` | `"6"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | `Forwarded` |