@flood-md/agent 0.2.9 → 0.2.10

package/dist/materials/component-accordion.md

@@ -0,0 +1,42 @@
+# Accordion
+
+Related disclosure sections with optional single or multiple expansion.
+
+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, Accordion } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Accordion label="Questions" items={[{value:"install",title:"How do I install Flood?",content:"Install the packages and import the stylesheet."}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Headings contain native disclosure buttons. Set headingLevel for the surrounding document.
+- Enter/Space toggle. Tab visits available triggers and open panel contents. ArrowUp/Down and Home/End move among enabled top-level triggers without opening panels.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly AccordionItem[]` | `Required` |
+| `expansionMode` | `"single" \| "multiple"` | `"single"` |
+| `value` | `readonly string[]` | `—` |
+| `defaultValue` | `readonly string[]` | `[]` |
+| `onValueChange` | `(value: string[]) => void` | `—` |
+| `disabled` | `boolean` | `false` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "defaultValue" \| "onChange">` | `Forwarded` |

package/dist/materials/component-alert-dialog.md

@@ -0,0 +1,46 @@
+# AlertDialog
+
+A focused confirmation with explicit cancel and continue 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, AlertDialog, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AlertDialog title="Archive this project?" description="You can restore it from the archive." confirmLabel="Archive project" trigger={props => <Button {...props}>Archive project</Button>} onConfirm={() => { /* Archive in the host application. */ }} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses the original Flood Dialog modal layer with role=alertdialog, a required message and initial focus on Cancel. Tab stays inside the modal; Escape cancels and restores trigger focus. Outside clicks do not dismiss it. There is no extra close action competing with the explicit Cancel button.
+- onConfirm is a host callback followed by a close request. onCancel handles the Cancel button and Escape, not confirmation. Use open/onOpenChange for host-controlled state and confirmDisabled to prevent confirmation while unavailable. Async work/errors belong to the host; callbacks are not awaited.
+- Translate title, description, confirmLabel and cancelLabel. Use ordinary Dialog for forms and exploratory content. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `false` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `description` | `string` | `Required` |
+| `confirmLabel` | `string` | `"Continue"` |
+| `cancelLabel` | `string` | `"Cancel"` |
+| `confirmDisabled` | `boolean` | `false` |
+| `onConfirm` | `() => void` | `Required` |
+| `onCancel` | `() => void` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">, "children" \| "role" \| "description" \| "closeLabel" \| "closeOnOutsideClick" \| "initialFocusRef">` | `Forwarded` |

package/dist/materials/component-alert.md

@@ -0,0 +1,41 @@
+# Alert
+
+An inline message with a quiet boundary and explicit announcement priority.
+
+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, Alert } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Alert tone="warning" title="Storage is almost full">
+        Free some space before your next upload.
+      </Alert>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- announcement defaults off: a static message does not automatically interrupt a screen reader. Polite uses role=status; assertive uses role=alert.
+- Use assertive for newly inserted urgent messages, and verify with actual assistive technology. No focus movement, timeout or automatic dismissal is implemented.
+- Title is optional. Icons are original decorative glyphs; pass icon={null} to omit or supply noninteractive artwork. Meaning must remain in the text.
+- Native div props and ref target the message root. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `—` |
+| `tone` | `"neutral" \| "error" \| "warning" \| "success" \| "info"` | `"info"` |
+| `icon` | `ReactNode` | `—` |
+| `announcement` | `"off" \| "polite" \| "assertive"` | `"off"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "title" \| "role" \| "aria-live">` | `Forwarded` |

package/dist/materials/component-aspect-ratio.md

@@ -0,0 +1,36 @@
+# AspectRatio
+
+Reserved media proportions that respond to their containing 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, AspectRatio, Image } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AspectRatio ratio={16 / 9}><Image src="/flood-mark.png" alt="Flood logo" fit="contain" /></AspectRatio>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- ratio must be finite and positive. The root reserves media geometry before image loading.
+- Direct img/video/iframe children fill the reserved box. Content can overflow; the component does not clip focus, menus or arbitrarily tall text.
+- Host media owns alt, captions, controls and loading. Native props/ref target the outer div.
+- Available in 0.2.4; use matching installed declarations.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `ratio` | `number` | `16 / 9` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

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

@@ -0,0 +1,39 @@
+# AvatarGroup
+
+A compact collection of avatars with an accessible overflow count.
+
+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, AvatarGroup } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <AvatarGroup label="Project collaborators" items={[{id:"alex",name:"Alex Morgan"},{id:"sam",name:"Sam Lee"},{id:"june",name:"June Park"}]} max={2} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The native list composes Flood Avatar. IDs and names must be nonempty and unique IDs remain stable. max is a positive integer; the default shows four people.
+- Overflow is a static count, not a hidden interactive menu. Translate overflowLabel when needed; visible avatars retain their individual accessible names. Size follows Avatar. Intentional overlap never applies to interactive targets.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `items` | `readonly AvatarGroupItem[]` | `Required` |
+| `label` | `string` | `Required` |
+| `max` | `number` | `4` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `overflowLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLUListElement>, "children">` | `Forwarded` |

package/dist/materials/component-avatar.md

@@ -0,0 +1,40 @@
+# Avatar
+
+A stable identity image with initials or an explicit text fallback.
+
+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, Avatar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Avatar name="Alex Morgan" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Name supplies the accessible image name; decorative suppresses duplicate naming next to an equivalent visible name.
+- Fallback remains visible until the image loads and after a load error. Changing src starts a fresh load lifecycle.
+- Native span props and ref target the root. Size and shape do not change during loading. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `name` | `string` | `Required` |
+| `src` | `string` | `—` |
+| `fallback` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `shape` | `"circle" \| "rounded"` | `"circle"` |
+| `decorative` | `boolean` | `false` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "role" \| "aria-label" \| "aria-hidden">` | `Forwarded` |

package/dist/materials/component-badge.md

@@ -0,0 +1,37 @@
+# Badge
+
+A compact, noninteractive label for status and metadata.
+
+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, Badge } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Badge tone="success">Active</Badge>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use text to communicate status; color is supplementary.
+- Tone, size and visual variant are independent. This is not a selectable or removable chip.
+- Available in 0.2.4. Use FloodRoot for the neutral dark recipe.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `tone` | `"neutral" \| "accent" \| "error" \| "warning" \| "success" \| "info"` | `"neutral"` |
+| `variant` | `"subtle" \| "outline"` | `"subtle"` |
+| `Native HTML props` | `HTMLAttributes<HTMLSpanElement>` | `Forwarded` |

package/dist/materials/component-blockquote.md

@@ -0,0 +1,35 @@
+# Blockquote
+
+A quoted passage with an optional compact attribution.
+
+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, Blockquote } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Blockquote attribution="The Flood team">Good interfaces make room for what matters.</Blockquote>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses native blockquote; cite remains a source URL, while attribution is visible host-authored credit. Rich quote content and attribution are supported.
+- The logical leading rule follows RTL. Supply quotation punctuation as part of your actual content; the component does not invent a quotation or source.
+- Compatible addition in 0.2.5. Uses existing Flood semantic tokens and relative geometry.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `attribution` | `ReactNode` | `—` |
+| `Native HTML props` | `BlockquoteHTMLAttributes<HTMLQuoteElement>` | `Forwarded` |

package/dist/materials/component-breadcrumb.md

@@ -0,0 +1,36 @@
+# Breadcrumb
+
+A wrapping hierarchy of native links with an explicit current page.
+
+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, Breadcrumb } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Breadcrumb items={[{label:"Workspace",href:"/"},{label:"Projects",href:"/projects"},{label:"Flood"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- The last item is current, with or without an href. Separators are decorative and not focusable.
+- Links keep browser navigation semantics. The host owns actual routes and client routing.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `items` | `readonly BreadcrumbItem[]` | `Required` |
+| `label` | `string` | `"Breadcrumb"` |
+| `separator` | `string` | `"/"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children">` | `Forwarded` |

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

@@ -0,0 +1,39 @@
+# ButtonGroup
+
+Connected actions with shared edges and ordinary 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, ButtonGroup, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ButtonGroup label="Editing actions">
+        <Button variant="subtle">Undo</Button>
+        <Button variant="subtle">Redo</Button>
+      </ButtonGroup>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use direct Button/IconButton children with compatible sizes. The group owns connected radii and single separators; actions keep their props and handlers.
+- label names the group. Tab follows normal button order; this is not a toolbar, menu or selection group.
+- Horizontal is default; vertical stacks actions. Content can wrap within a button. Conditional/hidden actions preserve the visible end corners. No clipping masks focus.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | `Forwarded` |

package/dist/materials/component-button.md

@@ -0,0 +1,43 @@
+# Button
+
+Native actions with a clear prominence, size and interaction 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, Inline, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Inline gap="2">
+        <Button>Save changes</Button>
+        <Button variant="subtle">Cancel</Button>
+        <Button loading>Saving</Button>
+      </Inline>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Button defaults to type="button". Set submit or reset deliberately inside forms.
+- Loading disables activation and sets aria-busy. The host owns completion announcements.
+- Prefer subtle for standalone secondary actions; ghost belongs in a clear parent context.
+- Buttons use content width, including inside Stack. Opt into a full-width action with style={{ inlineSize: "100%" }} only when the composition calls for it.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"solid"` |
+| `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
+| `loading` | `boolean` | `false` |
+| `type` | `Inherited native HTML prop` | `"button"` |
+| `Native HTML props` | `ButtonHTMLAttributes<HTMLButtonElement>` | `Forwarded` |

package/dist/materials/component-calendar.md

@@ -0,0 +1,59 @@
+# Calendar
+
+One calendar with day, month and year views, without nested popups.
+
+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, Calendar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Calendar label="Choose a date" defaultValue="2026-10-26" today="2026-10-26" weekStartsOn={1} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Calendar is a standalone visual collection. DateField handles text entry and DatePicker composes the field and calendar layer.
+- Values use canonical YYYY-MM-DD and visibleMonth uses YYYY-MM. Locale formats Gregorian month/day names; weekStartsOn is explicit.
+- Arrows move dates; Home/End move within a week and PageUp/PageDown navigate months. Controlled month refusal preserves a real focused day. Disabled dates remain discoverable but cannot select.
+- The host owns selected values, availability and side effects. Provide today for a deterministic clock in tests or rendering. Min/max bound navigation; readonly prevents selection while allowing browsing. Introduced in 0.2.7.
+- Month and year controls replace the content of this calendar. Selecting a navigation period returns to days without changing the selected date.
+- granularity="day" | "month" | "year" chooses YYYY-MM-DD, YYYY-MM or YYYY.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `granularity` | `"day" \| "month" \| "year"` | `—` |
+| `showViewControls` | `boolean` | `—` |
+| `viewLabels` | `{month?:string;year?:string;previous?:string;next?:string}` | `—` |
+| `value` | `string` | `—` |
+| `defaultValue` | `string` | `—` |
+| `onValueChange` | `(date: string) => void` | `—` |
+| `onDateSelect` | `(date: string) => void` | `—` |
+| `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` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange" \| "children">` | `Forwarded` |

package/dist/materials/component-card.md

@@ -0,0 +1,46 @@
+# Card
+
+A structured surface for a heading, supporting content and independent 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, Card, Button, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Card title="Project details" description="Keep your team in sync."
+        footer={<Button variant="subtle">Open project</Button>}>
+        <Text as="p" size="compact">A calm place for the next idea.</Text>
+      </Card>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Card composes Surface with optional title, description, header actions, children and footer. Missing slots add no empty wrapper or reserved space.
+- Use Surface for unstructured containment; use Card when its header/body/footer structure is useful. Card is a noninteractive div, not a button or link. Put named actions inside.
+- Title uses Heading at headingLevel (2 by default); choose the level according to the page. Supply phrasing content for the title. Description accepts supporting React content.
+- Density compact/comfortable controls padding and section rhythm using existing semantic spacing. Header actions wrap naturally; content is never clipped to the radius.
+- Root HTMLDivElement ref and native div props/style/className target the surface. The title prop is content, not the native HTML tooltip attribute. Available in 0.2.4.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `ReactNode` | `—` |
+| `description` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
+| `footer` | `ReactNode` | `—` |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` |
+| `density` | `"compact" \| "comfortable"` | `"comfortable"` |
+| `elevation` | `"default" \| "raised"` | `"default"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "title">` | `Forwarded` |

package/dist/materials/component-center.md

@@ -0,0 +1,39 @@
+# Center
+
+Center a constrained piece of content in both axes of an available region.
+
+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, Center, Text } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Center minHeight="12rem" maxWidth="24rem">
+        <Text as="p">A focused message.</Text>
+      </Center>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Center supplies two-axis alignment with an inner content wrapper. minHeight sets the available vertical region; maxWidth constrains the content rather than the entire parent. Values are ordinary CSS lengths, preferably rem.
+- inline opts into inline-grid for centering within text or an inline composition. It adds no content semantics, surface, spacing between siblings or viewport positioning. Use Stack/Inline for collections and Container for page gutters.
+- Original compatible addition in the unpublished 0.2.5 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `inline` | `boolean` | `false` |
+| `maxWidth` | `string` | `—` |
+| `minHeight` | `string` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLDivElement>` | `Forwarded` |

package/dist/materials/component-character-count.md

@@ -0,0 +1,42 @@
+# CharacterCount
+
+Supporting character or remaining-length feedback with an explicit over-limit message.
+
+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, CharacterCount } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CharacterCount value="Make room for a clear idea." max={80} htmlFor="project-note" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Pass text through value or supply an explicit nonnegative integer count for a host-defined counting rule. The default text count uses Unicode code points, not UTF-16 code units or grapheme clusters. max is advisory and does not truncate or validate an editor.
+- mode remaining displays max minus count; count displays the current count and optional limit. An over-limit message is visible in addition to its semantic color. Translate label/overLimitLabel; lang formats the number.
+- Use htmlFor to associate supporting output with its editor and aria-describedby on the editor when appropriate. Live announcements default off to avoid announcing every keystroke; the host may opt into aria-live. Available in 0.2.5.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `value` | `string` | `—` |
+| `count` | `number` | `—` |
+| `max` | `number` | `—` |
+| `mode` | `"count" \| "remaining"` | `"count"` |
+| `label` | `string` | `"Characters"` |
+| `overLimitLabel` | `string` | `"Over limit"` |
+| `htmlFor` | `string` | `—` |
+| `form` | `string` | `—` |
+| `Native HTML props` | `HTMLAttributes<HTMLOutputElement>` | `Forwarded` |

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

@@ -0,0 +1,39 @@
+# CheckCard
+
+A native checkbox 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, CheckCard } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <CheckCard label="Product updates" description="A monthly summary of new features." name="updates" value="product" />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses native checkbox semantics, including mixed state, required and form reset.
+- Content is noninteractive: do not nest links or actions inside a card label.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `indeterminate` | `boolean` | `—` |
+| `label` | `string` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `icon` | `ReactNode` | `—` |
+| `metadata` | `ReactNode` | `—` |
+| `density` | `"compact" \| "comfortable"` | `—` |
+| `Native HTML props` | `Omit<Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size">, "label" \| "children">` | `Forwarded` |