@flood-md/react 0.2.10 → 0.2.12

package/README.md

@@ -6,9 +6,203 @@ HTML semantics and refs, no third-party component library or Tailwind dependency
 Named imports support tree shaking in optimizing ES-module bundlers. Import the
 shared stylesheet explicitly; styles are not split by component.
 
-This package documents the **0.2.10** source API. Keep Flood package versions aligned and follow the guide matching
+Sheet is a bottom-aligned Drawer for short tasks, navigation and touch-friendly
+choices. It fits short content, caps long content to the viewport, and keeps
+Drawer dismissal, focus restoration, body scrolling and the optional footer.
+
+SegmentedControl options can display a `count` alongside the label, for example
+`{value: "pending", label: "Pending", count: 2}`. Use this for a small, mutually
+exclusive choice that updates one collection. The count is read with the visible
+label and does not change the submitted value.
+
+Version 0.2.12 adds opt-in DataTable column visibility. Set
+`showColumnVisibility` for the Columns menu, and supply `hiddenColumnIds` and
+`onHiddenColumnIdsChange` when the host saves preferences. The active sort and
+record-opening columns stay visible. See [DataTable](../../docs/components/data-table.md).
+Pass the Columns control from `toolbar={({ columns }) => …}` into
+`CollectionToolbar.actions` to keep it alongside search and filters.
+
+The 0.2.11 candidate adds optional DataTable row `primaryAction` for opening an
+in-place detail panel, plus `toolbar` and `inset="roomy"` for a shared table edge.
+The title is a native button and the rest of the row also responds to pointer
+activation. Nested controls keep their own actions.
+Set `numeric: true` on a DataTable column of comparable amounts or quantities
+for logical end alignment and tabular digits. An explicit `align` still applies.
+
+The 0.2.11 candidate adds optional compact NavigationTree item `flyout` settings
+for mouse-hover previews and a separate positioning reference. Click, keyboard
+and touch activation still work. Popover `focusOnOpen` defaults to true; use false
+for a pointer preview that preserves the current keyboard focus.
+
+In the 0.2.11 candidate, `NavigationItem.trailingAction` adds a named sibling
+control to an expanded row. `NavigationTree` items accept the same slot.
+Enable `branchGuides` on a tree or Sidebar group for visual depth cues.
+Choose `Sidebar.headerLayout="inline"` to put the identity and collapse button
+on one line while expanded. The stacked layout keeps the original toggle position.
+
+CommandPalette (0.2.11 candidate) provides modal search over pages or commands.
+It shares the CommandList item contract and supports grouped results, disabled
+items, loading and two densities. The host supplies actions and any shortcut.
+
+Tooltip trigger props are HTMLElement-safe: render the existing Link or Button
+directly and forward its ref, hover/focus handlers and aria-describedby. Tooltip
+does not add button type, popup or navigation semantics. Raw button triggers
+inside forms keep an explicit type="button". Popover/Menu retain button trigger
+contracts. When one control owns both Tooltip and Popover, compose both refs,
+handlers and descriptions, and disable the tooltip while the interactive layer
+is open so Escape and focus remain owned by that layer.
+
+IconButton iconSize (0.2.11 candidate) sizes its inner IconSlot independently of
+the interactive size. It defaults to size; shrinking a supporting glyph must
+not shrink its target or bypass IconSlot with a custom SVG width. Existing glyph
+roles at a 16px root are 2xs=14px, xs/sm=16px and md/lg=20px.
+
+This package documents the **0.2.12** source API. Keep Flood package versions aligned and follow the guide matching
 your installed declarations; source changes do not modify an existing npm release.
 
+NavigationItem (0.2.11 candidate) is the shared small row for destinations,
+commands and disclosures. Supply label and either href for a native Link or
+onAction for a Button command. disclosure supplies expanded, onExpandedChange,
+label and optional controls/disabled. With disclosure alone, the full primary
+row toggles the branch; with href or onAction, disclosure is a separate sibling
+IconButton. The row shares its visual surface across both controls, without
+nested interactive elements or making a link click toggle expansion. Current,
+ancestorCurrent, focus and disclosure expansion are separate states. icon,
+reserveIcon, trailing and description are optional anatomy, not required filler.
+Compact rows keep their accessible label and optional Tooltip; NavigationTree
+owns any branch hierarchy and compact Popover, not NavigationItem itself.
+Raw compact NavigationItem cannot combine a separate primary destination/action
+and disclosure: use the NavigationTree branch composition, which retains the
+parent destination alongside children in its flyout. trailing is noninteractive
+metadata; independent controls belong in their own sibling action anatomy.
+
+NavigationGroup (0.2.11 candidate) composes related children with optional label,
+hideLabel, headingAction and separator. collapsible uses the existing Collapsible;
+expanded/onExpandedChange or defaultExpanded control only the group disclosure.
+defaultExpanded is true. A collapsible group requires a nonempty label; hideLabel
+omits the visual title while preserving the toggle name. collapseDisabled disables
+only that disclosure, not arbitrary child destinations or heading actions.
+Compact presentation keeps children available and preserves the accepted expanded
+choice for return to expanded navigation. Heading actions remain available on the
+compact axis. Collapsible headerAction supplies a sibling action in its own header,
+so a group command need not be nested in the disclosure button or moved elsewhere.
+
+Sidebar (0.2.11 candidate) composes grouped NavigationTree destinations and a
+bounded ScrollArea between fixed header/footer slots. NavigationGroup owns each
+section's optional presentation; NavigationTree composes NavigationItem rows.
+Supply label
+and choose variant="quiet" (default) for restrained inactive navigation and
+rectangular current rows, or standard for the stronger pill recipe. This is a
+scoped component recipe using existing roles, not a global theme change.
+Supply groups `{id,label,items}` and currentValue; item values must be globally unique. Set a
+height on the host. Expanded width defaults to 16rem; collapsed rail is 4.5rem (5rem for coarse pointers).
+collapsed/defaultCollapsed/onCollapsedChange are independent of the route and
+expandedValues/defaultExpandedValues/onExpandedValuesChange. Controlled refusal
+preserves accepted state. side is logical start/end; size matches NavigationTree.
+Header/footer accept ReactNode or `({collapsed}) => ReactNode`; adapt their content
+explicitly. collapsible=false omits the toggle. Localize collapseLabel,
+expandLabel and expandItemLabel; group/item labels supply the navigation names.
+The component does not add preference storage, routing, a mobile drawer or shortcuts.
+Groups can set hideLabel to omit redundant visible section titles while retaining
+nav names. headingAction, separator and collapsible/expanded group configuration
+are independent of branch expandedValues. headerSeparator/footerSeparator are
+independent opt-in shell choices and default false. Header/footer content must
+follow the mode contract: common icon/text tracks when expanded and one full-rail
+axis for the actual brand, toggle, destinations and account target when compact.
+currentKind defaults to page; location identifies a current global
+module. Compose a flat compact Sidebar as a GlobalRail and another Sidebar as
+its ContextBar, keeping route, module, expansion and visibility in the host.
+
+Sidebar places its overlay scrollbar inside the existing outer edge spacing.
+Header, body and footer keep the same tracks without an additional reserved
+column, whether navigation overflows or not.
+NavigationTree rows share NavigationItem's space-3 start inset, icon/text tracks
+and deliberate columns for actual trailing anatomy. Iconless descendants begin at the parent text track; missing
+peer icons reserve a slot. Header content should use the same icon size and gap.
+
+NavigationTree rows use space-1 between peers and before an expanded branch;
+group separation remains owned by Sidebar.
+
+NavigationTree compact (0.2.11 candidate) exposes an icon rail: leaf destinations
+remain links, disabled items remain unavailable, branches use Popover with full
+navigation. flyoutSide controls its physical placement; Sidebar resolves its own
+side and RTL direction. Branch selection closes the flyout and preserves current
+destination/expanded state independently. trailing composes meaningful metadata
+such as Badge in expanded rows. Flood tooltips identify compact destinations on
+hover and focus while preserving the actual link/button; an open branch flyout
+suppresses its hint. Missing icons use a neutral fallback glyph. Current ancestor styling does not
+claim aria-current on a non-current parent.
+
+DataTable emptyContent (0.2.11 candidate) accepts a composed EmptyState and
+applicable actions inside the existing full-width body cell. It renders only
+when state="ready" has no visible rows; loading/error retain Spinner/Alert and
+retry ownership. Omitting it preserves labels.empty. Keep header/sort context
+and distinguish an empty collection from no matching results in host content.
+Reset filters in the host and return focus to a persistent query control.
+
+CollectionViewSwitcher (0.2.11 candidate) composes a hidden-label Select and
+applicable view commands. Supply views `{id,name,disabled?}`, controlled value
+and onValueChange. Optional actions/onAction use the OverflowActions contract:
+one command renders Button directly, multiple commands adapt through overflow.
+The host owns saved queries, persistence, naming, confirmation and recovery.
+Keep it separate from CollectionToolbar; selectRef gives host dialogs a stable
+focus destination. controlSize defaults to sm; disabled blocks choice/commands.
+Localize label, actionsLabel, moreLabel, view names and supplied action labels.
+Its multi-action rail uses OverflowActions containerVariant="plain" to match
+the adjacent field height. Toolbar variant="plain" removes its material and
+outer inset; contained remains the default for standalone rails. Button variant
+and toolbar containerVariant remain independent in OverflowActions.
+
+CollectionToolbar (0.2.11 candidate) composes a named search field, applied Tag
+summaries, reserved Clear filters action and end-aligned Filters Popover. Supply
+controlled searchValue/onSearchValueChange; appliedFilters and onRemoveFilter
+describe accepted conditions. filterContent supplies the host's staged editor.
+The host owns Apply/Cancel, query execution, validation and saved views. Omit
+filterContent for search/summary-only use. onClear is optional; canClear describes
+whether the host has anything to reset, including slot-owned quickFilters.
+Clearing and tag removal focus Filters (or search without a panel). The root is
+a fieldset with ordinary Tab navigation, not an action-only roving toolbar.
+Use summaryPrefix for meaningful all/any context, localized labels for controls,
+and keep saved-view management outside this query row. Narrow containers move
+summaries below search/actions; no material surface is added.
+
+FilterGroup (0.2.11 candidate) composes FilterCondition rows and SegmentedControl
+for a flat finite-choice draft. Supply label, properties, controlled value
+`{match:"all"|"any", conditions:[{id,property,operator,values}]}` and onValueChange.
+Rows keep stable IDs. All/any appears at two conditions; an empty group offers
+Add condition without extra explanatory chrome. New rows use an available
+enabled property and empty values. Duplicate properties are prevented for new
+choices by default; allowDuplicateProperties and maxConditions can change that
+policy. Existing accepted rows are preserved when constraints change.
+Accepted additions/removals restore useful focus; refused proposals retain state
+and focus. The host owns application, validation, persistence and query semantics.
+controlSize defaults to sm; labels and conditionLabels localize group/row text.
+
+FilterCondition (0.2.11 candidate) composes Fieldset, Field, Grid, two Selects,
+MultiSelect and an optional removal IconButton. Supply a named label, properties
+with finite options, controlled value `{property, operator: "is" | "is-not", values}`
+and onValueChange. Property changes propose an empty values array; operator
+changes preserve values. Empty values remain a draft for host validation.
+No query execution or Apply/Cancel state is built in. controlSize defaults to sm;
+labels localizes names/operator text and hideLabel defaults to true for a named
+row. disabled blocks all interaction; onRemove is optional. A wide host gets one
+row with a larger value track; container queries reflow narrow rows. Hosts own
+duplicate-property policy and focus after removal.
+MultiSelect shows its placeholder only while no values are selected. With chips
+and an empty query, the editor reserves only its real action/caret budget;
+typing expands the search area. A needless placeholder row must not enlarge the
+control, while actual chip overflow can still wrap without clipping values.
+
+Toolbar supports shape="rounded" (default) or "pill". OverflowActions uses
+shape="pill" by default and forwards that capability to Toolbar; choose rounded
+for the earlier geometry. A horizontal pill toolbar stays on one scrollable rail.
+Read-only text controls retain keyboard focus and copying while preventing edits
+and picker activation; they are not disabled controls.
+
+Tabs uses `variant="contained"` by default. Choose `variant="line"` for page
+sections with a selection marker along the edge next to the panel. Both variants
+support horizontal and vertical orientation and the same keyboard behavior.
+
 Version 0.2.10 adds Fieldset legendSize="label" | "section"
 (default label). Independent section legends use a 1rem/600 role; named fields
 retain their 13px-equivalent label size with a .25rem inner gap. Dialog task
@@ -248,6 +442,10 @@ edge-to-edge content when the host already provides safe padding. The default
 padding can wrap text and change content height. Native
 fallback scrollbars retain their platform behavior.
 
+AppShell content mode uses the same ScrollArea. For a workspace whose layout
+already provides clearance, `scrollContentInset="none"` keeps the content
+width stable when rails appear. The default protects edge-to-edge content.
+
 ```tsx
 <ScrollArea aria-label="Activity" style={{ maxHeight: "12rem" }}>
   <Stack gap="4">{/* Long activity content */}</Stack>
@@ -421,8 +619,9 @@ Available in 0.2.3. Import Flood CSS and use FloodRoot for dark foundations.
 
 Disclosure corner geometry: Accordion headers have square internal seams. Only
 the first header has upper shell corners, and only a closed last header has lower
-shell corners. An open Collapsible header has square lower corners where its
-panel begins. Hover backgrounds follow that same shape without clipping focus.
+shell corners. A standalone Collapsible has an inset, rounded trigger and a
+separate gap before the revealed content. The trigger label and panel share
+an inline edge.
 
 
 ## Tooltip, Popover and Dialog
@@ -621,7 +820,12 @@ assertive uses role=alert. Choose urgency deliberately for dynamically inserted
 content. Announcements depend on actual assistive technology; initial static
 markup is not guaranteed to be read aloud. No focus movement, auto-dismiss,
 timeout or built-in close/action button is supplied. Compose named host actions
-inside children when needed. Alert is separate from Dialog and future Toast.
+inside children when needed. A titleless Alert centers its glyph alongside a
+single Inline row. Subtle and ghost actions inherit the feedback tint on
+interactive states. Use a floating ToastRegion for brief operation results.
+ToastRegion defaults to `placement="bottom-end"`. Choose `bottom-start`,
+`top-end` or `top-start` for a different logical corner, or `inline` to
+embed it in a layout. New floating cards enter from their placement edge.
 
 See the [WAI Meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/),
 [Alert pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) and
@@ -755,11 +959,37 @@ See [WAI Menu Button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and
 
 ### Toolbar and Kbd (0.2.4)
 
+BulkActionBar (0.2.11 candidate) composes Toolbar and OverflowActions for selected
+records. Supply label, selectionCount, items and onClear; onAction receives the
+command ID. A zero count renders nothing. selectionLabel is the complete
+localized count. The pill rail stays in one row, with two visible commands by
+default; maxVisibleActions accepts 1, 2 or 3 and available width can reduce it
+further. Remaining commands use More. pending disables all commands and clearing.
+counter="label" (default) shows the summary, "number" shows only the number with
+the full accessible label, and "none" removes the counter slot. Label/number
+slots reserve 7rem/3rem respectively, bounded on narrow rails, and use tabular
+digits so changing selection does not move commands. counterWidth customizes
+that reservation for translations or larger counts; long summaries truncate
+visually while retaining their full text/title. A hidden counter frees its slot.
+The host owns accepted changes, captured IDs, confirmation and focus after the
+bar disappears. Positioning is host-owned: use a stable bounded width for a
+floating rail, plus viewport safe-area spacing and measured scroll clearance.
+For table selection, place the rail at the viewport's bottom center. Set
+`showSelection={false}` on DataTable to keep its count available to assistive
+technology while BulkActionBar displays the visible count.
+
+OverflowActions also accepts leading/trailing slots and maxVisibleActions. Slot
+width is reserved before measuring commands; use action owners in those slots
+and retain a stable containing width. Do not add form inputs to the Toolbar.
+
 Toolbar groups Button, IconButton, Toggle, native buttons/links and Menu triggers
 under one named action panel. After hydration it uses one Tab entry, directional
 arrows, Home/End and optional looping. Disabled/hidden actions are skipped. Arrows
 move focus, not activation. Horizontal order follows writing direction. In vertical
 toolbars open Menu with Enter/Space; horizontal menus retain Up/Down opening.
+A vertical pill centers its actions on a single axis. Use same-size icon controls
+with accessible names for a compact rail. Use a rounded toolbar for a vertical
+group of labeled actions.
 Keep text inputs and independent selection widgets outside this action-only API.
 Native child handlers and refs remain attached; Toolbar owns their tabIndex while
 mounted and restores original attributes on cleanup. Without JavaScript, native
@@ -906,6 +1136,7 @@ relative path, without reading their contents. Single mode replaces its selectio
 
 AlertDialog (0.2.5) is a concise confirmation, composed from Flood's
 native modal layer and Button. Supply title, description, trigger and onConfirm.
+Line breaks in the description separate distinct thoughts while allowing each line to wrap.
 Cancel receives initial focus; Escape cancels; outside clicks do not dismiss.
 Tab containment, background inertness, scroll lock and return focus reuse Dialog.
 Translate confirmLabel/cancelLabel. onConfirm runs before requesting close, while
@@ -942,7 +1173,8 @@ The CSS build assembles the original component styles into the shared stylesheet
 
 
 Section headingLevel controls native h2–h6 semantics. Its independent headingSize
-uses the existing Heading roles (section/page/large/display), defaulting to section.
+uses the Heading roles (group/section/page/large/display), defaulting to section.
+Choose group for a compact section inside a Drawer or another constrained panel.
 Keep document hierarchy meaningful when changing visual emphasis.
 
 ## Editable and TagInput · 0.2.7
@@ -962,3 +1194,41 @@ Popover positionReference optionally supplies a connected same-document element
 DateRangeField, RangeCalendar and DateRangePicker (0.2.7) share ordered range values and the original Calendar grid. ResizablePanels adds real pointer/keyboard geometry above static Split. ErrorSummary links host validation to native controls. See each generated catalog page and its guide under docs/components/. DateField validationMessage adds an external native constraint after the field's own date validity.
 
 Menu (0.2.7) supports recursive submenu items and ContextMenu reuses its native layer engine. Context triggers preserve the actual pointer/keyboard source; nested searches stay scoped, Escape unwinds one level and Tab exits through the root. See docs/components/menu.md and context-menu.md.
+
+## Collection contracts in 0.2.11
+
+Autocomplete submits free text, including strings outside its suggestions.
+Combobox and MultiSelect continue submitting IDs. Search controls accept local
+filtering (default) or manual filtering with controlled query/value and
+optionsQuery identifying the result. A mismatched result stays nonselectable.
+loadState distinguishes ready/loading/error; onRetry is an optional host action.
+Use selectedOptions to retain a selected record's presentation while results
+change. Query cancellation and transport stay with the host. Options may have
+group labels; option IDs remain globally unique.
+
+OverflowActions takes named command items, an onAction callback, optional priority,
+size/variant and a localized moreLabel. It preserves source order and moves lower
+priorities to an existing Menu. It is not a navigation-link container. Menubar
+coordinates menus with controlled/uncontrolled openValue and roving triggers;
+child commands reuse Menu. Use native links for destinations. Button/IconButton
+tone="danger" uses existing semantic colors within FloodRoot, independently of
+prominence. Tone itself does not confirm a destructive operation.
+
+DataTable paginationMode="server" renders supplied rows without sorting/slicing.
+Provide page/onPageChange and nonnegative totalRows; sortable columns also require
+controlled sort (null when absent) and onSortChange. Reconcile an out-of-range page
+when a query changes; ready rows must match pageSize/totalRows. Selection defaults
+to the supplied page in server mode and the full collection in client mode.
+Server selectionScope="dataset" requires controlled selectedIds/onSelectionChange;
+the host validates IDs outside the page. Checkboxes only select the current page.
+The host owns request execution and cancellation, remote query selection and
+virtualization. DataTable supports optional column visibility, width preferences,
+logical edge pinning and expandable record details. Use Sparkline for a compact
+trend cell. See [DataTable](../../docs/components/data-table.md) and
+[Sparkline](../../docs/components/sparkline.md).
+
+DatePicker and DateRangePicker pass viewLabels to their calendars. Calendar panels
+use minimal Popover chrome, with Escape/selection/trigger dismissal; there is no
+separate hidden close-button API. DateTimePicker datePickerLabels/timePickerLabels
+forward popup labels plus segmentLabels and validation messages. DateTimeRangePicker
+exposes corresponding start/end label objects; outer field labels remain distinct.

package/dist/app-shell.d.ts

@@ -0,0 +1,3 @@
+import { type AppShellProps, type AppTopBarProps } from "./index.js";
+export declare const ApplicationTopBar: import("react").ForwardRefExoticComponent<AppTopBarProps & import("react").RefAttributes<HTMLElement>>;
+export declare const ApplicationShell: import("react").ForwardRefExoticComponent<AppShellProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/app-shell.js

@@ -0,0 +1,66 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { AppTopBar, Button, Drawer, Inline, ScrollArea, SkipLink } from "./index.js";
+const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+export const ApplicationTopBar = /* @__PURE__ */ forwardRef(function ApplicationTopBar({ start, end, bordered, className, ...props }, ref) {
+    return _jsxs("header", { ...props, ref: ref, className: ["flood-app-top-bar", className].filter(Boolean).join(" "), "data-bordered": bordered || undefined, children: [start != null && _jsx(Inline, { align: "center", gap: "2", className: "flood-app-top-bar__start", children: start }), end != null && _jsx(Inline, { align: "center", gap: "2", className: "flood-app-top-bar__end", children: end })] });
+});
+export const ApplicationShell = /* @__PURE__ */ forwardRef(function ApplicationShell({ navigation, navigationSide, navigationDrawer, topBar, footer, scroll, mainId, mainAs: Main = "main", mainLabel, mainRef, scrollLabel, scrollOrientation = "both", scrollContentInset = "scrollbar", skipLabel, children, className, ...props }, ref) {
+    const generatedId = useId();
+    const contentId = mainId ?? `flood-app-${generatedId}`;
+    const root = useRef(null);
+    const dock = useRef(null);
+    const trigger = useRef(null);
+    const drawer = useRef(null);
+    const focusAfterResize = useRef(false);
+    const [narrow, setNarrow] = useState(false);
+    const [open, setOpen] = useState(false);
+    const below = navigationDrawer?.below;
+    const useDrawer = Boolean(navigationDrawer && narrow);
+    useImperativeHandle(ref, () => root.current, []);
+    useBrowserLayoutEffect(() => {
+        const node = root.current;
+        if (!node || below === undefined) {
+            setNarrow(false);
+            setOpen(false);
+            return;
+        }
+        const update = () => {
+            const width = node.getBoundingClientRect().width;
+            if (!width)
+                return;
+            const next = width < below;
+            if (next === narrow)
+                return;
+            const active = node.ownerDocument.activeElement;
+            focusAfterResize.current = Boolean(next ? dock.current?.contains(active) : trigger.current === active || drawer.current?.contains(active));
+            if (!next)
+                setOpen(false);
+            setNarrow(next);
+        };
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, [below, narrow]);
+    useBrowserLayoutEffect(() => {
+        if (!focusAfterResize.current)
+            return;
+        focusAfterResize.current = false;
+        const target = useDrawer ? trigger.current : root.current?.ownerDocument.getElementById(contentId);
+        target?.focus({ preventScroll: true });
+    }, [contentId, useDrawer]);
+    const navigationSlot = !useDrawer && navigation != null && navigation !== false
+        ? _jsx("div", { ref: dock, className: "flood-app-shell__navigation", children: navigation })
+        : null;
+    const navigationTrigger = useDrawer && navigationDrawer ? _jsx(Drawer, { ref: drawer, title: navigationDrawer.title, side: navigationSide, size: navigationDrawer.size ?? "sm", open: open, onOpenChange: setOpen, trigger: ({ ref: drawerTrigger, ...buttonProps }) => _jsx(Button, { ...buttonProps, ref: node => {
+                trigger.current = node;
+                drawerTrigger(node);
+            }, variant: "subtle", size: "sm", children: navigationDrawer.triggerLabel ?? "Navigation" }), children: open && navigationDrawer.renderContent(() => setOpen(false)) }) : null;
+    const chrome = typeof topBar === "function"
+        ? topBar(navigationTrigger)
+        : _jsxs(_Fragment, { children: [navigationTrigger && _jsx(AppTopBar, { start: navigationTrigger }), topBar] });
+    return _jsxs("div", { ...props, ref: root, className: ["flood-app-shell", className].filter(Boolean).join(" "), "data-scroll": scroll, children: [_jsx(SkipLink, { href: `#${contentId}`, children: skipLabel }), navigationSide === "start" && navigationSlot, _jsxs("div", { className: "flood-app-shell__workspace", children: [chrome, _jsx(Main, { ref: mainRef, id: contentId, "aria-label": mainLabel, tabIndex: -1, className: "flood-app-shell__main", children: scroll === "content"
+                            ? _jsx(ScrollArea, { orientation: scrollOrientation, contentInset: scrollContentInset, "aria-label": scrollLabel, className: "flood-app-shell__scroll", children: children })
+                            : children }), footer] }), navigationSide === "end" && navigationSlot] });
+});

package/dist/bulk-action-bar.d.ts

@@ -0,0 +1,3 @@
+import { type BulkActionBarProps } from "./index.js";
+/** Selection owns the count; the host owns accepted record updates and focus after removal. */
+export declare const SelectionActionBar: import("react").ForwardRefExoticComponent<BulkActionBarProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/bulk-action-bar.js

@@ -0,0 +1,17 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { IconButton, OverflowActions, Text, VisuallyHidden } from "./index.js";
+/** Selection owns the count; the host owns accepted record updates and focus after removal. */
+export const SelectionActionBar = /* @__PURE__ */ forwardRef(function SelectionActionBar({ label, selectionCount, selectionLabel = `${selectionCount} selected`, items, onAction, onClear, counter = "label", counterWidth, clearLabel = "Clear selection", moreLabel = "More", size = "sm", maxVisibleActions = 2, disabled = false, pending = false, className, ...props }, ref) {
+    if (!Number.isSafeInteger(selectionCount) || selectionCount < 0)
+        throw new Error("Flood BulkActionBar selectionCount must be a nonnegative safe integer");
+    if (!selectionLabel.trim() || !clearLabel.trim())
+        throw new Error("Flood BulkActionBar requires named selection and clear action");
+    if (![1, 2, 3].includes(maxVisibleActions))
+        throw new Error("Flood BulkActionBar keeps one to three commands visible");
+    if (!["label", "number", "none"].includes(counter))
+        throw new Error("Flood BulkActionBar counter must be label, number or none");
+    if (selectionCount === 0)
+        return null;
+    return _jsx(OverflowActions, { ...props, ref: ref, label: label, items: items, onAction: onAction, moreLabel: moreLabel, size: size, variant: "subtle", shape: "pill", maxVisibleActions: maxVisibleActions, disabled: disabled || pending, "aria-busy": pending || undefined, className: ["flood-bulk-action-bar", className].filter(Boolean).join(" "), leading: counter === "none" ? undefined : _jsx(Text, { size: "compact", className: "flood-bulk-action-bar__selection", "data-counter": counter, style: counterWidth === undefined ? undefined : { inlineSize: counterWidth }, title: selectionLabel, children: counter === "number" ? _jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", children: selectionCount }), _jsx(VisuallyHidden, { children: selectionLabel })] }) : selectionLabel }), trailing: _jsx(IconButton, { label: clearLabel, size: size, variant: "subtle", disabled: disabled || pending, onClick: onClear, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", "aria-hidden": "true", children: _jsx("path", { d: "m6 6 12 12M18 6 6 18" }) }) }) });
+});

package/dist/collection-toolbar.d.ts

@@ -0,0 +1,3 @@
+import { type CollectionToolbarProps } from './index.js';
+/** Query chrome only: the host supplies filter drafts, accepted query and saved views. */
+export declare const CollectionQueryBar: import("react").ForwardRefExoticComponent<CollectionToolbarProps & import("react").RefAttributes<HTMLFieldSetElement>>;

package/dist/collection-toolbar.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId, useImperativeHandle, useRef } from 'react';
+import { Button, Field, Fieldset, IconSlot, Inline, Popover, SearchInput, Tag, Text } from './index.js';
+/** Query chrome only: the host supplies filter drafts, accepted query and saved views. */
+export const CollectionQueryBar = /* @__PURE__ */ forwardRef(function CollectionQueryBar({ label, searchValue, onSearchValueChange, searchLabel = 'Search', searchPlaceholder = 'Search…', clearSearchLabel = 'Clear search', appliedFilters = [], onRemoveFilter, appliedFiltersLabel = 'Applied filters', summaryPrefix, quickFilters, actions, filterContent, filtersLabel = 'Filters', filterTitle = filtersLabel, filtersOpen, onFiltersOpenChange, filterPanelRef, filterPanelClassName, onClear, canClear = Boolean(searchValue || appliedFilters.length), clearLabel = 'Clear filters', controlSize = 'sm', disabled = false, hideLabel = true, className, ...props }, forwardedRef) {
+    const root = useRef(null);
+    useImperativeHandle(forwardedRef, () => root.current, []);
+    const generated = useId(), triggerId = `flood-collection-filters-${generated}`, searchId = `flood-collection-search-${generated}`;
+    if (![label, searchLabel, clearSearchLabel, appliedFiltersLabel, filtersLabel, filterTitle, clearLabel].every(text => text.trim()) ||
+        new Set(appliedFilters.map(filter => filter.id)).size !== appliedFilters.length || appliedFilters.some(filter => !filter.id.trim() || !filter.label.trim()))
+        throw new Error('Flood CollectionToolbar requires named controls and unique applied filter IDs');
+    const hasPanel = filterContent !== undefined && filterContent !== null && filterContent !== false;
+    const hasSummary = Boolean(quickFilters) || appliedFilters.length > 0;
+    function focusPersistent() {
+        const document = root.current?.ownerDocument;
+        document?.getElementById(hasPanel ? triggerId : searchId)?.focus({ preventScroll: true });
+    }
+    return _jsx(Fieldset, { ...props, ref: root, legend: label, hideLabel: hideLabel, disabled: disabled, className: ['flood-collection-toolbar', className].filter(Boolean).join(' '), children: _jsxs(Inline, { gap: "3", align: "center", className: "flood-collection-toolbar__row", children: [_jsx("div", { className: "flood-collection-toolbar__search", children: _jsx(Field, { id: searchId, label: searchLabel, hideLabel: true, children: field => _jsx(SearchInput, { ...field, controlSize: controlSize, value: searchValue, placeholder: searchPlaceholder, clearLabel: clearSearchLabel, disabled: disabled, onChange: event => { if (!disabled)
+                                onSearchValueChange(event.currentTarget.value); } }) }) }), hasSummary && _jsxs(Inline, { gap: "2", align: "center", role: "group", "aria-label": appliedFiltersLabel, className: "flood-collection-toolbar__summaries", children: [quickFilters, summaryPrefix && _jsx(Text, { size: "compact", tone: "subtle", children: summaryPrefix }), appliedFilters.map(filter => _jsx(Tag, { size: controlSize === 'xl' ? 'lg' : 'md', disabled: disabled || filter.disabled, removeLabel: filter.removeLabel ?? `Remove ${filter.label}`, onRemove: onRemoveFilter ? () => {
+                                if (disabled || filter.disabled)
+                                    return;
+                                focusPersistent();
+                                onRemoveFilter(filter.id);
+                            } : undefined, children: filter.label }, filter.id))] }), (onClear || hasPanel || actions) && _jsxs(Inline, { gap: "2", align: "center", className: "flood-collection-toolbar__commands", children: [onClear && _jsx(Button, { size: controlSize, variant: "outline", className: "flood-collection-toolbar__clear", "data-visible": canClear, disabled: disabled || !canClear, "aria-hidden": !canClear || undefined, onClick: () => { if (disabled || !canClear)
+                                return; focusPersistent(); onClear(); }, children: clearLabel }), hasPanel && _jsx(Popover, { title: filterTitle, ref: filterPanelRef, className: filterPanelClassName, open: filtersOpen, onOpenChange: onFiltersOpenChange, disabled: disabled, align: "end", trigger: trigger => _jsxs(Button, { ...trigger, id: triggerId, variant: "outline", size: controlSize, children: [_jsx(IconSlot, { size: controlSize, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", "aria-hidden": "true", children: _jsx("path", { d: "M4 6h16M7 12h10m-7 6h4" }) }) }), filtersLabel] }), children: filterContent }), actions] })] }) });
+});

package/dist/collection-view-switcher.d.ts

@@ -0,0 +1,3 @@
+import { type CollectionViewSwitcherProps } from './index.js';
+/** Presentation of accepted definitions; the host owns their queries and persistence. */
+export declare const CollectionViewSelector: import("react").ForwardRefExoticComponent<CollectionViewSwitcherProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/collection-view-switcher.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { Button, Field, IconSlot, Inline, OverflowActions, Select } from './index.js';
+/** Presentation of accepted definitions; the host owns their queries and persistence. */
+export const CollectionViewSelector = /* @__PURE__ */ forwardRef(function CollectionViewSelector({ label, views, value, onValueChange, actions = [], onAction, actionsLabel = `${label} actions`, moreLabel = 'View actions', controlSize = 'sm', disabled = false, selectRef, className, ...props }, ref) {
+    if (!label.trim() || !actionsLabel.trim() || !moreLabel.trim() || new Set(views.map(view => view.id)).size !== views.length ||
+        views.some(view => !view.id.trim() || !view.name.trim()) || new Set(actions.map(action => action.id)).size !== actions.length ||
+        actions.some(action => !action.id.trim() || !action.label.trim()))
+        throw new Error('Flood CollectionViewSwitcher requires unique named views and actions');
+    const single = actions.length === 1 ? actions[0] : undefined;
+    return _jsxs(Inline, { ...props, ref: ref, role: "group", "aria-label": `${label} controls`, gap: "3", align: "center", className: ['flood-collection-view-switcher', className].filter(Boolean).join(' '), children: [_jsx("div", { className: "flood-collection-view-switcher__select", children: _jsx(Field, { label: label, hideLabel: true, children: field => _jsx(Select, { ...field, ref: selectRef, controlSize: controlSize, disabled: disabled, value: value, onChange: event => {
+                            const next = views.find(view => view.id === event.currentTarget.value);
+                            if (!disabled && next && !next.disabled)
+                                onValueChange(next.id);
+                        }, children: views.map(view => _jsx("option", { value: view.id, disabled: view.disabled, children: view.name }, view.id)) }) }) }), actions.length > 0 && _jsx("div", { className: "flood-collection-view-switcher__actions", children: single ?
+                    _jsxs(Button, { size: controlSize, variant: "subtle", tone: single.tone, disabled: disabled || single.disabled, onClick: () => { if (!disabled && !single.disabled)
+                            onAction?.(single.id); }, children: [single.icon && _jsx(IconSlot, { size: controlSize, children: single.icon }), single.label] }) : _jsx(OverflowActions, { label: actionsLabel, moreLabel: moreLabel, size: controlSize, items: actions, containerVariant: "plain", disabled: disabled, onAction: id => { if (!disabled)
+                        onAction?.(id); } }) })] });
+});

package/dist/combobox.d.ts

@@ -1,9 +1,14 @@
-import { type ComboboxProps } from "./index.js";
+import { type ComboboxProps, type ComboboxOption } from "./index.js";
 interface SearchSelectionProps extends Omit<ComboboxProps, "value" | "defaultValue" | "onValueChange"> {
     selectedValues?: readonly string[];
     initialValues: readonly string[];
     onSelectionChange?: (value: string[]) => void;
     multiple?: boolean;
+    freeText?: boolean;
+    textValue?: string;
+    initialText?: string;
+    onTextChange?: (text: string) => void;
+    onOptionSelect?: (option: ComboboxOption) => void;
     removeItemLabel?: string;
 }
 /** Shared search/layer model. Public single and multiple value contracts stay distinct. */