@flood-md/agent 0.2.5 → 0.2.8

package/DESIGN.md

@@ -1,17 +1,46 @@
-# Flood design system · 0.2.5
+# Flood design system · 0.2.8
+
+ListBox owns native required validation for accepted selection. Use its
+description/message/status props rather than duplicating feedback markup. Visual
+invalid/status flags alone do not block submission; validationMessage supplies a
+host-owned blocking constraint. Readonly retains values and bypasses validity;
+disabled excludes submission. TimePicker keeps its plain manual-selection list.
+
+Use TimePicker for civil time suggestions and DateTimeRangePicker for complete,
+ordered civil endpoints. Calendar switches day/month/year views in place. Resolve
+timezones and DST in the host. These are source APIs; check the installed version.
+
+## Composition is built from library primitives
+
+Use existing Flood components inside larger components, the website and playgrounds.
+Do not replace them with ordinary text or custom markup to fix a visual issue.
+When a small capability is missing, improve or create that reusable primitive
+first, then compose it. Preserve component anatomy and semantics. The manifest
+ships the composition skill from `references/flood-composition/SKILL.md` to
+project-root `.agents/skills/flood-ui/references/flood-composition/SKILL.md`.
+Apply that skill. Native semantic markup and neutral structural wrappers remain
+valid inside their proper owners.
+
+
+Readonly date/time entry bypasses native validity constraints while retaining
+accepted canonical values, including values outside current bounds, time steps or
+range availability. Do not silently clear those values. Partial, reversed ranges
+and refused controlled drafts never become accepted by setting readonly. Disabled
+values remain excluded from submission.
 
 Read project-root flood.json and installed declarations with this contract.
-The source bundle's SKILL.md routes to focused composition, accessibility,
-customization and verification references. Its routing matrix names prerequisites
-and sources of truth; flood/rules.json indexes observable checks. Read only the
-relevant reference. This expanded bundle belongs to 0.2.5; existing installations
-keep their matching guide set.
+The installed entry is .agents/skills/flood-ui/SKILL.md; its references live under
+.agents/skills/flood-ui/references/. Read only the relevant composition, spacing,
+accessibility, customization or verification reference. flood/manifest.json maps
+package sources to those installed paths; flood/rules.json indexes observable
+checks. In the Flood repository the corresponding sources are packages/agent/.
+This bundle belongs to 0.2.7; older installations keep their matching guide set.
 
 React + TypeScript and Next.js App Router. Use this guide with matching installed
 Flood packages and flood.json. The source repository's release status does not
 grant permission to publish or assume a version is available on npm.
 
-This guide covers the supported exports in 0.2.5 and their layout refinements. Confirm
+This guide covers the supported exports in 0.2.7 and their layout refinements. Confirm
 the matching installed declarations before using APIs absent from older versions.
 
 ## Connect
@@ -30,6 +59,9 @@ child. Keep server data fetching in server components.
   does not associate a form control; use Field.
 - Reserve display for a marketing headline; preserve normal page/section sizes
   inside product UI. Hosts own responsive composition.
+- Use Tree for application-object selection and NavigationTree for nested URLs.
+  Their expansion and selection/current-location contracts are separate. Do not
+  turn ordinary website navigation into an ARIA tree or treat Tree as a form field.
 - Use CodeSnippet with a code string and optional action slot for commands or
   short examples. The host owns clipboard permission, feedback and errors;
   selectable wrapped code remains available when copying fails.
@@ -160,7 +192,10 @@ export function Profile() {
 ```
 
 
-0.2.5 adds Badge, Spinner, Skeleton and Avatar. Read references/composition.md and references/accessibility.md for status announcements, fallback geometry and decorative naming. Button loading reuses Spinner. These APIs are not present in 0.2.3.
+0.2.5 adds Badge, Spinner, Skeleton and Avatar. Read the installed composition and
+accessibility references under .agents/skills/flood-ui/references/ for status
+announcements, fallback geometry and decorative naming. Button loading reuses
+Spinner. These APIs are not present in 0.2.3.
 
 Progress, Meter and Alert are also available in 0.2.5. Distinguish task completion from bounded measurements, preserve names/units, and select alert announcement priority explicitly.
 
@@ -271,3 +306,137 @@ original OFL notices. Color alone never communicates validation or progress.
 CodeSnippet codeDirection defaults to ltr independently of RTL parent action layout; choose rtl/auto explicitly for content that needs it. Native dir still applies to the wrapper. Protected ScrollArea reveals focused descendants fully when needed, composes the host focus handler and avoids scrolling to nested top-layer controls.
 
 Checkbox, Radio and Switch apply native hidden/dir/lang to their visible label wrapper as well as the input, so a component-local language/direction applies to its whole choice.
+
+## Base capabilities · 0.2.7
+
+The added exports are Editable, TagInput, CommandList, DateField, TimeField,
+Calendar, DatePicker, RangeCalendar, DateRangeField, DateRangePicker,
+ResizablePanels, ErrorSummary, ContextMenu, Tree and NavigationTree. Menu preference
+items and submenus extend Menu; a command palette is Dialog + CommandList
+composition, not a separate export. Use the matching installed declarations.
+
+### Editing and commands
+
+Editable separates draft and committed value. Enter commits, Escape cancels and
+blurAction selects commit/cancel/none. Controlled value/editing require host
+acceptance; only committed text submits. TagInput accepts free-form tokens while
+MultiSelect selects known option IDs. Only committed tags submit repeated named
+entries. Preserve IME, reset cancellation, required and readonly/disabled behavior.
+
+CommandList filters and invokes commands without a submitted selection or modal
+lifecycle. The host owns effects, routing, shortcuts and closure. Compose Dialog
+around it for a command palette; preserve input naming, active-option semantics,
+disabled/loading states and existing Escape ownership.
+
+Menu preferences expose controlled aria-checked states and labelled radio groups;
+the host owns exclusivity. Preference activation stays open unless closeOnSelect
+requests dismissal; commands dismiss and call onAction. Nested submenus and
+ContextMenu reuse this action engine. ContextMenu opens from pointer context or
+ContextMenu/Shift+F10; provide a visible Menu alternative for touch. None is a
+native form-selection control or a data-fetching service.
+
+### Civil dates, time and ranges
+
+DateField owns canonical Gregorian YYYY-MM-DD dates, not timestamps or time zones.
+Keep labelled text segments, explicit order and native required/bounds validity.
+Invalid drafts cannot submit an old canonical date. validationMessage adds a host
+native constraint without overriding own calendar errors. TimeField uses 24-hour
+HH:mm or HH:mm:ss precision and seconds-based steps; do not invent AM/PM,
+overnight bounds, zone conversion or combined date-time semantics.
+
+Calendar owns a single-date grid. DatePicker composes DateField, Calendar and
+Popover, keeping native forms, controlled state and focus ownership intact.
+onDateSelect confirms allowed activation even when the value is unchanged.
+Translate calendar labels, segment names and validation messages. Calendar Intl
+formatting is explicitly Gregorian UTC, weekStartsOn remains explicit and today
+can provide deterministic rendering.
+
+RangeCalendar selects one inclusive interval start then end; hover/focus previews
+are uncommitted. DateRangeField owns paired text entry and atomic startName/endName
+bridges; DateRangePicker composes the pair with one popup. Values are {start,end}
+with empty strings for empty/partial endpoints. Controlled hosts must accept
+partial starts to advance calendar selection. Calendar gestures normalize earlier
+endpoints; typed reversed drafts stay editable and invalid. Partial, reversed,
+unavailable or refused pairs never submit one new endpoint beside an old one.
+isDateDisabled blocks endpoints; interior blocked dates are allowed unless
+isRangeDisabled rejects the interval. Apply the same predicates to typed entry.
+Escape/outside dismissal may leave an accepted partial range; do not manufacture
+completion to make the form valid. Preserve reset cancellation and return focus.
+
+### Hierarchy, layout and error ownership
+
+Tree selects application objects through independent value and expandedValues
+contracts. Keep globally unique item values and noninteractive icons/descriptions.
+Descriptions participate in each row's accessible name; descendant labels do not.
+Arrows/Home/End/typeahead move focus independently from selection. Collapsing
+retains known selected descendants; removed/nonselectable values are excluded
+from later selection requests. Deferred hasChildren/loading branches belong to
+the host; no fetching or virtualization is implied.
+
+Tree readonly prevents selection while retaining browse/expand behavior. Translate
+readOnlyMessage for the associated explanation; tree/treeitem do not support
+aria-readonly. Disabled rows remain discoverable but cannot select/expand; item
+restrictions do not implicitly cascade. Tree submits no form values and does not
+automatically inherit a native fieldset's disabled state.
+
+NavigationTree uses native nav/list/links and normal Tab order. A destination and
+its disclosure are separate controls, so expansion does not navigate. The host
+owns currentValue, hrefs and expanded ancestors. Preserve linkProps, modifier
+navigation, localized disclosure labels and distinct disabled states.
+
+ResizablePanels owns constrained pointer/keyboard geometry and separator keys;
+its value is the main pane's percentage after the separator. The host supplies
+vertical height, content scrolling and persistence. Preserve RTL, cancellation,
+focus transfer and inert zero-sized panes. Use static Split when resizing is not
+needed. ErrorSummary receives host errors with exact field IDs. It links/focuses
+those controls without validating, expanding sections or submitting. Opt into
+autofocus/announcement deliberately for the host's submission lifecycle.
+
+Required, status, loading, empty and readonly contracts are component-specific.
+Preserve native validity and cancelled resets where supported; do not infer a
+form contract from Tree/Menu/CommandList selection or active state. Package source
+availability and focused examples do not prove registry publication, deployment
+or accessibility of the host application.
+
+## Extended controls in 0.2.8
+
+HoverCard opens a named interactive preview on hover or focus and supports explicit
+activation. Use Tooltip for short noninteractive descriptions. ColorSwatch and
+ColorPicker use opaque RGB hex colors; they do not imply alpha, gradients or a
+contrast guarantee. TreeSelect provides single hierarchical selection; Tree
+remains the standalone single/multiple control. DateTimePicker composes civil
+date and clock time with separate form values and no inferred timezone. Use
+application validation for relationships between the parts. Recipes for Select
+all, split actions and form submission live in the public user documentation.
+
+DataList/DataListItem are native list content, not selection widgets. Keep links
+in the title and actions separate; do not turn the whole row into a button.
+CheckCard/RadioCard compose the native choice primitives into clickable labels.
+Keep their description, icon and metadata noninteractive. Use one radio name and
+an enclosing Fieldset for exclusive choices; derive aggregate checkbox state
+in the host. Read-only choice cards preserve submission and block editing; apply
+readOnly to an entire radio group consistently.
+
+DataTable pages and sorts one complete client-side collection. It is not a
+server query engine or a virtualized grid. Rich cells require explicit sortValues
+when they are sortable. Select all affects the current page only and preserves
+other pages; permission-restricted rows use selectionDisabled. Native links and
+actions in cells remain independent. Compose search and filters at the host
+boundary, reset page deliberately and specify the intended selection lifetime.
+Use Table + Pagination for remote pagination rather than passing one remote page
+into the client-paginated DataTable.
+
+FileItem/FileList display host-owned attachment metadata; UploadItem/UploadList
+display explicit queued/uploading/success/error/cancelled states. Cancel and retry
+callbacks are intents, not an upload engine. Do not show success merely because
+bytes reach100%; wait for the host confirmation. Use stable IDs, not filenames,
+for identity. FileInput retains native form ownership; removing a display row
+does not alter its FileList. ImagePreview reuses Dialog; the host owns trusted
+URLs, blob URL lifetime, download permissions and image alt text. No built-in
+network, file reading or object URL creation is implied by these components.
+
+FileMeta combines a display format label and byte size in one quiet chip. FileItem
+and UploadItem place it with the filename, reserving the next line for status or
+supporting text. Filename extensions are display hints only, never validation.
+Override with format or hide the format using format=null; do not infer upload
+safety or MIME permissions from a visible chip.

package/README.md

@@ -1,7 +1,7 @@
 # @flood-md/agent
 
 Version-matched guidance for Flood React/Next.js projects. Read the installed
-contract before composing screens. The 0.2.5 reference bundle includes spacing
+contract before composing screens. The 0.2.8 reference bundle includes spacing
 guidance, routing and observable rules. These files grant
 no authority to modify external services.
 
@@ -11,6 +11,7 @@ no authority to modify external services.
 | SKILL.md | Short entry and task router |
 | references/routing.md | Applicability, audience, prerequisites and governing source |
 | references/composition.md | Screen/form composition workflow |
+| references/flood-composition/SKILL.md | Full primitives-first composition skill routed from flood-ui |
 | references/spacing.md | Measured spacing, density, nested geometry and hit areas |
 | references/accessibility.md | Interaction and perception checks |
 | references/customization.md | Scoped semantic customization |

package/SKILL.md

@@ -19,6 +19,7 @@ invented as a package API. No external component library or parallel token syste
 
 | Work | Read next | Required result |
 | --- | --- | --- |
+| Component, composite, website or playground UI | [Composition skill](references/flood-composition/SKILL.md) | Reused primitives; missing small capabilities implemented before composites |
 | New screen, layout or form | [Composition](references/composition.md) | Existing primitives, correct host width and form ownership |
 | Spacing, density, nested geometry or shifting previews | [Spacing](references/spacing.md) | Measured visual relationships and nonoverlapping interactive areas |
 | Keyboard, validation, names or states | [Accessibility](references/accessibility.md) | Real interaction and associations preserved |

package/manifest.json

@@ -51,9 +51,14 @@
       "source": "references/spacing.md",
       "target": ".agents/skills/flood-ui/references/spacing.md",
       "kind": "reference"
+    },
+    {
+      "source": "references/flood-composition/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-composition/SKILL.md",
+      "kind": "skill"
     }
   ],
-  "version": "0.2.5",
+  "version": "0.2.8",
   "installedEntry": ".agents/skills/flood-ui/SKILL.md",
   "pathBase": "source is package-relative; target is relative to the host project root"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flood-md/agent",
-  "version": "0.2.5",
+  "version": "0.2.8",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",

package/references/composition.md

@@ -1,5 +1,15 @@
 # Compose an interface
 
+Apply the [Flood composition skill](flood-composition/SKILL.md) before building
+or changing UI. Reuse the existing semantic primitive, including inside library
+components. Fix its layout or extend its API instead of substituting custom markup.
+
+Use Tree for hierarchical application selection, with explicit value and expansion
+ownership. Use NavigationTree for nested destinations: preserve native links and
+their browser behavior rather than forcing a website sidebar into tree/menu roles.
+Do not infer cascading selection, lazy fetching, form submission or expansion of
+current-page ancestors. Keep item values globally unique and text labels present.
+
 For spacing, density or nested-geometry decisions, read [Spacing](spacing.md).
 Measure the complete row geometry before adding a gap to repeated controls.
 
@@ -267,3 +277,5 @@ host-owned. No third-party component implementation was introduced.
 Section headingLevel controls native h2–h6 semantics. Its independent headingSize
 uses the existing Heading roles (section/page/large/display), defaulting to section.
 Keep document hierarchy meaningful when changing visual emphasis.
+
+For a command palette, compose Dialog and CommandList. The host owns commands, permissions, query reset and shortcuts; keep Escape available to the dialog. Avoid a duplicate modal or command-search engine. The project recipe lives in docs/recipes/command-palette.md in the source repository.

package/references/flood-composition/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: flood-composition
+description: Build or review Flood UI from existing library primitives before adding composites. Use for component, website, playground and host-interface work, especially when a layout fix risks replacing a reusable element with custom markup.
+---
+
+# Compose Flood from its primitives
+
+Existing Flood components are the building blocks, including inside other Flood
+components. Preserve their anatomy and behavior when improving a composition.
+Read the governing project instructions, matching declarations and relevant
+component guide first. This skill grants no additional permissions.
+
+## Choose the smallest existing owner
+
+Before changing JSX, identify the visible roles and their existing owners:
+StatusIndicator for a named state, Progress for progress, Badge/FileMeta for
+metadata, IconButton for an icon action, Dialog for modal behavior, Text/Heading
+for typography, and the appropriate form, list or table primitive for semantics.
+Check the actual installed exports and props; do not invent APIs from newer docs.
+
+- Reuse the matching component with its supported props and tokens.
+- If spacing or alignment is wrong, inspect both the primitive and the parent
+  composition. Fix the owner of the relationship. Keep the primitive intact.
+- If a primitive lacks a real reusable capability, improve that primitive first,
+  with an intentional API/variant and the matching docs and checks, then compose it.
+- If no primitive exists, build the small reusable component before the larger
+  composition. Define its semantics, anatomy, states and size before exposing it.
+
+In the Flood library, add public primitives through the source API, catalog,
+declarations, guidance and current version decision. In a consuming application,
+do not pretend that an uninstalled export exists: use the supported primitives or
+an explicitly project-owned adapter, and identify any upstream gap.
+
+## Do not bypass a component to fix its appearance
+
+Do not replace StatusIndicator with a styled span, Badge with a handmade chip,
+Progress with a local track, or Dialog with a parallel modal merely to make one
+example fit. Do not hide a component's glyph, label, focus state or other anatomy
+through descendant CSS and reproduce it beside the component. Intentional variants
+belong in the primitive's API, not in a consumer-specific imitation.
+
+For example, an upload row keeps StatusIndicator and Progress as separate reused
+components. Its parent aligns their centers and controls the gap; it does not
+remove the status dot or replace the status with ordinary text. Fix internal dot
+alignment in StatusIndicator only if the primitive itself is wrong.
+
+Native semantic markup is necessary inside primitive implementations. Content
+strings and neutral structural wrappers are also valid in compositions. They must
+not introduce a competing visual or behavioral component. A wrapper that starts
+owning a reusable role should become a named small component instead.
+
+## Review the composed result
+
+Check the reused component and its neighboring elements in the real host: wide
+and narrow layout, enlarged text, long labels, optional content and relevant
+interaction states. Measure the visible glyph/text/control centers when alignment
+is the issue. Keep focus, accessible names, callbacks and native form semantics.
+
+If changing a shared primitive, check another consumer of it. Report which
+components were reused, which primitive changed or was added, and what remains
+unverified. A new wrapper name alone is not evidence of reuse. Use the project's
+verification scope; this guidance does not require a full release run for every
+local design adjustment.

package/references/routing.md

@@ -6,6 +6,7 @@ override user authority or grant permission for unrelated operations.
 
 | Question / when | Audience | Prerequisite | Source of truth | Verify with |
 | --- | --- | --- | --- | --- |
+| Which primitive owns this role? Component/composite UI work | Developer / agent / reviewer | Matching catalog and component anatomy | flood-composition/SKILL.md | Reuse existing primitives; extend small capabilities first |
 | Which API can I import? Every component edit | Developer / agent | Installed exact versions | Installed @flood-md/react declarations; flood.json | Type-check host imports; CLI doctor for alignment |
 | What does this release mean? Setup / upgrade | Developer / agent | Matching guide | flood/DESIGN.md, package changelog | Compare version and declarations; preserve host edits |
 | How should a screen fit together? Screen / form work | Designer / developer / agent | Scope, content and current API | composition.md; host layout requirements | Narrow/wide rendered screen and native form interaction |

package/rules.json

@@ -181,6 +181,28 @@
         "Check fine/coarse pointers and nonoverlapping interactive targets",
         "Preserve keyboard focus and label activation"
       ]
+    },
+    {
+      "id": "composition.reuse",
+      "when": "Building or reviewing Flood components, composites, website or host UI",
+      "for": [
+        "designer",
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed exports and component contracts",
+        "Existing component anatomy and current composition"
+      ],
+      "sourceOfTruth": "DESIGN.md and the Flood composition skill",
+      "guide": "references/flood-composition/SKILL.md",
+      "verify": [
+        "Existing semantic primitives remain present in the rendered composition",
+        "Missing reusable capabilities are implemented in a small primitive before the larger composite",
+        "No replacement markup or hidden anatomy used to bypass a primitive",
+        "Alignment checked within each row and in the real host"
+      ]
     }
   ],
   "guideResolution": "Match guide to source in manifest.files; use its target relative to the host project root."