@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/recipe-command-palette.md

@@ -0,0 +1,45 @@
+# Command palette
+
+Use CommandPalette for a workspace-wide page finder or a set of searchable
+commands. It shares filtering and keyboard behavior with CommandList and uses
+Dialog for modal focus and dismissal. CommandPalette is available in the
+unreleased 0.2.11 candidate.
+
+```tsx
+"use client";
+
+import { Button, CommandPalette, FloodRoot } from "@flood-md/react";
+
+export function WorkspaceSearch({ onNavigate }: { onNavigate: (id: string) => void }) {
+  return (
+    <FloodRoot>
+      <CommandPalette
+        title="Go to page"
+        searchLabel="Search pages"
+        placeholder="Search pages…"
+        emptyMessage="No matching pages."
+        trigger={props => <Button {...props} variant="subtle">Go to page</Button>}
+        items={[
+          { id: "projects", label: "All projects", group: "Projects" },
+          { id: "assigned", label: "Assigned to me", group: "Projects", keywords: ["mine"] },
+          { id: "inbox", label: "Inbox", group: "Workspace" },
+        ]}
+        onAction={onNavigate}
+      />
+    </FloodRoot>
+  );
+}
+```
+
+Import the Flood stylesheet once. Keep the trigger inside the existing FloodRoot.
+Translate the dialog title, search label, placeholder, close label and state
+messages. The title and search label remain available to assistive technology.
+Use comfortable density by default and compact density for denser workspaces.
+
+Opening focuses the search input. Arrow keys move through available results.
+Enter or click calls the host action and requests closure. Escape, the close
+button and optional outside dismissal close without invoking an action. Use
+open/onOpenChange when the host owns visibility. A local query starts from
+defaultQuery on each opening. For a controlled query, the host owns persistence
+and reset. Set loading while replacing results asynchronously. The application
+owns requests, permissions, actions, routing and any global shortcut.

package/dist/materials/recipe-filter-bar.md

@@ -0,0 +1,68 @@
+# Filter bar
+
+For staged conditions and persisted query definitions, see
+[Collection views](collection-views.md) and its two working consumers.
+
+Compose existing Field, SearchInput, Select and Button. Filtering belongs to the
+host collection, not to DataTable. This recipe filters the full local data set
+before handing it to the table and resets page and selection when filters change.
+
+```tsx
+"use client";
+import {useState} from "react";
+import {Button, DataTable, Field, Inline, SearchInput, Select, Stack} from "@flood-md/react";
+
+const projects = [
+  {id: "design", name: "Design system", status: "Active", members: 12},
+  {id: "website", name: "Website", status: "Active", members: 4},
+  {id: "research", name: "Research", status: "Draft", members: 2},
+];
+
+export function ProjectTable() {
+  const [query, setQuery] = useState("");
+  const [status, setStatus] = useState("all");
+  const [page, setPage] = useState(1);
+  const [selected, setSelected] = useState<readonly string[]>([]);
+  function resetResults() { setPage(1); setSelected([]); }
+  const visible = projects.filter(project =>
+    project.name.toLowerCase().includes(query.trim().toLowerCase()) &&
+    (status === "all" || project.status === status));
+
+  return <Stack gap="4">
+    <Inline gap="3" align="end">
+      <Field label="Search projects">{props => <SearchInput {...props}
+        value={query} onChange={event => {setQuery(event.currentTarget.value); resetResults();}} />}</Field>
+      <Field label="Status">{props => <Select {...props} value={status}
+        onChange={event => {setStatus(event.currentTarget.value); resetResults();}}>
+        <option value="all">All statuses</option>
+        <option value="Active">Active</option>
+        <option value="Draft">Draft</option>
+      </Select>}</Field>
+      {(query || status !== "all") && <Button variant="subtle"
+        onClick={() => {setQuery(""); setStatus("all"); resetResults();}}>Clear filters</Button>}
+    </Inline>
+    <DataTable caption="Projects" selectable pageSize={5}
+      page={page} onPageChange={setPage} selectedIds={selected} onSelectionChange={setSelected}
+      columns={[{id:"name",label:"Project",sortable:true},
+        {id:"status",label:"Status"}, {id:"members",label:"Members",sortable:true,align:"end"}]}
+      rows={visible.map(project => ({id:project.id,label:project.name,cells:{
+        name:project.name,status:project.status,members:project.members}}))} />
+  </Stack>;
+}
+```
+
+Place inside FloodRoot and import the shared stylesheet once. Keep visible labels
+for filters, including when defaults are active. A clear action resets actual
+values. Expose active filters as removable Tag components when the filter set
+gets larger; do not add a duplicate generic FilterBar component just for layout.
+
+For remote data, debounce or submit at the host boundary, cancel obsolete requests
+and map loading/error states explicitly. Use DataTable paginationMode="server" for an individual server page with explicit
+controlled page/sort and totalRows; do not interpret its select-page checkbox as
+server-wide selection. Table + Pagination remains available for a host-owned
+contract. Follow recipe:record-workspace for request generations and recovery.
+
+When reviewing a dense toolbar, compare the filled edges and the text inside
+each control. Shared edges and consistent heights can communicate grouping
+even with small gaps. Judge the applied criteria and the filter trigger with
+long values and at the width where the toolbar wraps.

package/dist/materials/recipe-form-submission.md

@@ -0,0 +1,39 @@
+# Form submission
+
+Keep validation, pending state and recovery explicit. Native validity runs
+before submit. Application or server errors belong to the form and its fields.
+
+```tsx
+"use client";
+import {useRef, useState} from "react";
+import {Alert, Button, Field, Input, Stack} from "@flood-md/react";
+
+export function ProjectForm({save}: {save: (data: FormData) => Promise<void>}) {
+  const locked = useRef(false);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState("");
+  const [saved, setSaved] = useState(false);
+  return <form onSubmit={async event => {
+    event.preventDefault();
+    if (locked.current) return;
+    const data = new FormData(event.currentTarget);
+    locked.current = true;
+    setPending(true); setError(""); setSaved(false);
+    try { await save(data); setSaved(true); }
+    catch { setError("Could not save. Your changes are still here. Try again."); }
+    finally { locked.current = false; setPending(false); }
+  }} aria-busy={pending}>
+    <Stack gap="4">
+      <Field label="Project name">{props => <Input {...props} name="name" required readOnly={pending} />}</Field>
+      {error && <Alert tone="error" announcement="assertive">{error}</Alert>}
+      {saved && <Alert tone="success" announcement="polite">Project saved.</Alert>}
+      <Button type="submit" loading={pending}>Save project</Button>
+    </Stack>
+  </form>;
+}
+```
+
+Capture FormData before disabling any native fields. This example preserves user
+input after failure. Map returned field errors to Field and optionally ErrorSummary;
+never pretend the request succeeded. The host supplies persistence, cancellation,
+authentication and navigation. Place inside FloodRoot and import its CSS once.

package/dist/materials/recipe-grouped-form.md

@@ -0,0 +1,71 @@
+# Grouped form
+
+Use a shared outer grid for peer groups, with the same surface padding and field
+spacing. Each group owns its title and reading order. Two short fields stack
+inside each group; the next row reuses the same tracks instead of inventing a
+new four-column or uneven grid. This recipe illustrates workspace preferences,
+not an invoice-specific screen or a universal two-column requirement.
+
+Choose the number of tracks from the task and declared viewport. A long-address
+group may span the row; a short field does not need its own column. Keep related
+fields together in DOM order, including when an optional field disappears.
+Use Grid, Fieldset, Surface and Field rather than recreating their recipes.
+
+Import the shared stylesheet once and render inside FloodRoot. onApply receives
+native FormData in the host; this recipe implements no persistence or permissions.
+Those limits belong here in documentation, not as repeated captions in the form.
+
+## Source
+
+```tsx
+"use client";
+import type {FormEvent} from 'react';
+import {Button,Field,Fieldset,Grid,Input,Select,Stack,Surface} from '@flood-md/react';
+
+/** Shared outer tracks; groups retain their own reading order and field ownership. */
+export function GroupedForm({showBillingEmail=true,onApply}:{showBillingEmail?:boolean;onApply?:(values:FormData)=>void}) {
+  function submit(event:FormEvent<HTMLFormElement>){event.preventDefault();onApply?.(new FormData(event.currentTarget));}
+  return <form aria-label="Workspace settings" onSubmit={submit}>
+    <Stack gap="8">
+      <Grid columns={2} gap="6">
+        <Surface padding="6"><Fieldset legendSize="section" legend="Identity"><Stack gap="6">
+          <Field label="Workspace name" required>{props=><Input {...props} name="workspace" required />}</Field>
+          <Field label="Reference">{props=><Input {...props} name="reference" />}</Field>
+        </Stack></Fieldset></Surface>
+        <Surface padding="6"><Fieldset legendSize="section" legend="Locale"><Stack gap="6">
+          <Field label="Language">{props=><Select {...props} name="language" defaultValue="en"><option value="en">English</option><option value="ru">Русский</option></Select>}</Field>
+          <Field label="Time zone">{props=><Select {...props} name="timezone" defaultValue="UTC"><option value="UTC">UTC</option><option value="Asia/Almaty">Almaty</option></Select>}</Field>
+        </Stack></Fieldset></Surface>
+        <Surface padding="6"><Fieldset legendSize="section" legend="Primary contact"><Stack gap="6">
+          <Field label="Contact name">{props=><Input {...props} name="contact" />}</Field>
+          <Field label="Contact email">{props=><Input {...props} name="contactEmail" type="email" />}</Field>
+        </Stack></Fieldset></Surface>
+        <Surface padding="6"><Fieldset legendSize="section" legend="Billing contact"><Stack gap="6">
+          <Field label="Billing name">{props=><Input {...props} name="billing" />}</Field>
+          {showBillingEmail&&<Field label="Billing email">{props=><Input {...props} name="billingEmail" type="email" />}</Field>}
+        </Stack></Fieldset></Surface>
+      </Grid>
+      <Button type="submit">Apply settings</Button>
+    </Stack>
+  </form>;
+}
+```
+
+## Review
+
+Compare left/right edges and gutters in both rows, label/control associations,
+native required submission and omitted optional content. Inspect long labels and
+enlarged text at the host's declared widths. Do not judge a form by zero page
+overflow alone. Read the [forms workflow](/agent/references/flood-forms/SKILL.md)
+and [content workflow](/agent/references/flood-interface-content/SKILL.md) before
+adapting it. A useful form does not need a helper paragraph under every title.
+
+Independent sections use Fieldset legendSize="section" and keep one shared outer
+Grid across peer groups. Field labels retain the compact inner gap; Stack owns
+row separation. The hierarchy workflow explains why section titles and choice
+captions are different roles.
+
+Compare a short and a wrapped legend with the same fields. Check the visible
+gap from the legend to its first field and from the previous group to the
+legend. Use the [visible weight review](../layout.md#review-visible-weight)
+before changing the shared grid or a group gap.

package/dist/materials/recipe-navigation-workspace.md

@@ -0,0 +1,222 @@
+# Navigation workspace
+
+[Open the working workspace](/playground/navigation).
+
+The workspace compares a standalone Sidebar with a GlobalRail + ContextBar
+composition. Both use the same Sidebar and NavigationTree owners. GlobalRail and
+ContextBar describe their responsibilities here; they are not additional package
+exports. The example's project, inbox and file records live in memory.
+Use the account menu in the footer to switch between Flood Studio and Flood Labs.
+The navigation header shares the height of the workspace toolbar. The expanded
+Sidebar puts the service mark at the start and the collapse control at the end.
+On the compact rail, the toggle replaces the mark on hover or keyboard focus.
+On touch, the toggle stays visible.
+Labs adds nested project collections for testing long labels and scrolling.
+The host remembers the last route and expanded branches per workspace during
+the session. It validates a remembered route against the target workspace and
+falls back to the project overview if that destination is unavailable.
+The **Go to page** action uses CommandPalette. It searches the
+current workspace and expands the selected destination's parent branches.
+On navigation, the host moves focus to the destination heading.
+
+## Choose the hierarchy
+
+If the sidebar has one group whose title repeats the app or workspace context,
+use `hideLabel` and keep the group's accessible name. When showing a group title,
+align it with the labels of its destinations.
+
+Use one Sidebar when the application has a small destination hierarchy. Separate
+global and contextual navigation when switching domains changes the available
+destinations. The global rail stays flat and stable; its active module is a
+location, while the contextual destination is a page. An open ContextBar replaces
+the need for a second copy of its destinations in a global flyout.
+
+On narrow hosts, limit the expanded pane to a share of available width and keep
+the working heading and primary controls reachable. The playground condenses
+the toolbar and keeps wide table content in the table's own scroll area.
+
+Keep module, route, expansion and context visibility independent. Anchor the
+visibility control in the persistent rail header. When the context is hidden,
+hover a rail module to preview its contextual links in a flyout that fills the
+available rail height with top and bottom insets, even for short lists.
+The preview preserves focus and stays open while the pointer crosses into the
+panel. Click or use the keyboard to open it for interaction. Escape returns
+focus to the module when it owned focus. Choosing a destination closes the flyout and keeps the
+context docked or hidden as the user last set it. Browser Back restores the route.
+Use real links and host routing. A modified click must remain a browser action
+rather than changing the current tab's module through an unconditional handler.
+
+## Compose the panes
+
+| Region or behavior | Flood owner |
+| --- | --- |
+| Workspace landmarks, skip target and scroll boundary | AppShell, SkipLink and ScrollArea |
+| Shared identity, breadcrumbs and global commands | AppTopBar, Breadcrumb, Button and CommandPalette |
+| Current page title and page actions | PageHeader |
+| Docked rail and grouped destinations | Sidebar, NavigationGroup and NavigationTree |
+| Temporary navigation on a narrow host | Drawer with the same destination definitions |
+| Account commands and identity | Menu, Avatar and Button |
+
+Use AppShell's default content scrolling for a bounded workspace. Give an
+embedded shell an explicit block size. Choose `scroll="page"` for natural
+document scrolling. Place a persistent top bar and footer in the shell slots,
+and PageHeader inside main. The shell has a skip target and owns the scroll
+boundary; the host owns routes and persisted choices.
+
+For a single Sidebar, opt into `navigationDrawer` with a width threshold in CSS
+pixels and a `renderContent(close)` function. AppShell observes its own width.
+The playground uses 480 px for the classic Sidebar profile. Pass a `topBar`
+render function to place the named trigger with the existing toolbar controls.
+The Rail + Context example keeps its separate pane visibility and hover flyout.
+
+Share accepted route and branch state between Sidebar and Drawer. Close the
+Drawer on an accepted destination and focus the destination heading. Escape
+or explicit dismissal restores focus to the trigger. When a resize removes
+the focused dock or Drawer, AppShell transfers focus to the new trigger or
+the work region, respectively.
+
+This host-owned layout uses Flood components. In the 0.2.11 source candidate,
+NavigationItem owns the shared row, NavigationGroup owns related items and their
+optional heading, and NavigationTree composes rows into a destination hierarchy.
+Sidebar places these owners between its fixed header and footer. The caller
+supplies icons, identity controls and accepted route state; keep layout CSS in the
+host and import the matching Flood stylesheet once. These candidate APIs require
+matching installed declarations and are not added to an older npm release by
+reading this recipe.
+
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import { AppShell, AppTopBar, FloodRoot, Sidebar, type SidebarProps } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+type Props = {
+  global: SidebarProps;
+  context: SidebarProps;
+  contextVisible: boolean;
+  header: ReactNode;
+  children: ReactNode;
+};
+
+export function NavigationWorkspace({
+  global, context, contextVisible, header, children,
+}: Props) {
+  return (
+    <FloodRoot>
+      <AppShell
+        navigation={<>
+          <Sidebar {...global} collapsed collapsible={false} currentKind="location" />
+          {contextVisible && <Sidebar {...context} currentKind="page" />}
+        </>}
+        topBar={<AppTopBar start={header} />}
+        scrollOrientation="vertical"
+      >
+        {children}
+      </AppShell>
+    </FloodRoot>
+  );
+}
+```
+
+A bounded parent can supply the height instead of `100dvh`. Reserve remaining
+height with flex/grid rather than subtracting an assumed toolbar height: labels
+and tooling can wrap at enlarged text. Sidebar owns the middle navigation scroll
+viewport; AppShell owns the main content viewport. Table overflow remains inside
+the table's owner. Header and footer do not scroll with their navigation lists.
+
+## Compose the row before the shell
+
+Use NavigationItem for a destination, command or disclosure rather than a local
+button-shaped row. A destination has an href and keeps native Link behavior. A
+command has onAction and uses Button. A branch without a destination uses one
+full-row disclosure target; a destination with children keeps the link and the
+disclosure as separate sibling controls inside one coherent row surface. Clicking
+the link must not also change the branch's expansion. A disclosure must not be
+nested inside the link.
+
+Current destination, ancestor of the current destination, accepted expansion and
+keyboard focus are distinct states. The row owns its visual surface across the
+label and disclosure; do not paint a shorter selected pill only behind the link
+or add the trailing inset twice. Leading art, label and real trailing anatomy
+share deliberate tracks. A supporting chevron can use a smaller IconButton
+iconSize while retaining the normal control target.
+
+NavigationTree remains the recursive owner: it composes NavigationItem, manages
+the accepted expandedValues set and presents compact branches through Popover.
+The popup can include a branch's own destination and its children. A standalone
+compact NavigationItem does not create a hidden child hierarchy on its own.
+
+## Configure groups and fixed regions
+
+NavigationGroup can omit its label, hide a supplied visual label, add a meaningful
+headingAction, show a separator or expose its own disclosure. Its expanded state
+is independent of NavigationTree branch expansion and Sidebar width. A collapsible
+group needs a nonempty label; hideLabel keeps the toggle's accessible name even
+when the visual title is omitted. collapseDisabled affects that group disclosure,
+not arbitrary child links or actions.
+
+In compact presentation, group contents stay reachable and the group toggle is
+hidden. This presentation does not overwrite the accepted expanded state: returning
+to expanded navigation restores the group's prior choice. A supplied heading
+action remains available on the compact axis rather than disappearing with text.
+
+SidebarGroup exposes the group label, hideLabel, headingAction, separator and
+collapsible/expanded configuration when Sidebar assembles the hierarchy. Start
+these optional additions empty. Use a section title only when it distinguishes
+related destinations; a title already provided by the pane need not be repeated.
+Use branchGuides within a group when several levels of nesting need a visible
+guide. Use trailingAction for an independent action alongside row metadata.
+headerSeparator and footerSeparator are independent, opt-in Sidebar choices,
+not mandatory lines around every fixed region.
+
+Header and footer content must follow the same mode contract as the body. In
+expanded navigation, identity and utility rows use the agreed icon/text tracks.
+In compact navigation, measure the actual brand, toggle, destination and account
+hit-area centers against the full rail center. A centered footer wrapper is not
+proof that its Menu trigger or Avatar is centered. Adapt the identity content
+deliberately while preserving its accessible name and useful recognition cue.
+
+## Presentation and content
+
+Sidebar's quiet recipe uses restrained inactive text and rectangular current
+rows; standard retains stronger pill geometry. Compare these against the main
+work area, not only in isolation. Preserve explicit icon sizes, shared inline
+tracks and a common top anchor across adjacent panes. Omitting a collapse button
+must not shorten one header and lift its entire navigation above the other.
+
+Use `SidebarGroup.hideLabel` when the pane header already names the only group.
+Its navigation landmark keeps its label. Add badges only for meaningful counts or
+states, not to fill every destination. Account utilities and workspace settings
+belong in deliberate fixed slots rather than a second contextual destination list.
+
+## State and focus ownership
+
+Keep search and filters in their applicable module. An inactive Projects filter
+must not create a Clear filters action in Inbox, and clearing Inbox search must
+not modify the accepted Projects query. Validate the entire route, including
+extra or missing path segments, before deriving a title or current destination.
+
+Preserve surviving focus. When a focused record, action or pane disappears and
+focus falls to the document body, the host restores it to an intentional stable
+destination, such as the main heading. Do not refocus the heading on every data
+render or steal focus from another surviving control. A visibility toggle can
+keep focus on itself before removing its pane. A dialog whose original trigger
+disappeared needs the same explicit fallback when it closes.
+
+## Verify the workspace
+
+Check both layouts, module/page current semantics, hidden context through module
+changes and Back, modified links, branch disclosure and independent scrolling.
+Exercise both a full-row branch toggle and a destination-plus-disclosure row;
+include a host refusing an expansion request. Configure group headings, actions,
+separators and collapse independently, then switch compact mode without losing
+the accepted group choice or destinations. Compare actual header/footer trigger
+centers with body controls, including the account trigger, rather than inspecting
+the middle list alone. Check current/hover/focus surfaces across the complete row.
+Compare visible glyphs as well as their slots. If the same glyph reads off-axis
+across several states, review its artwork before moving the shared hit area.
+Exercise a filter in one module followed by search in another; remove the focused
+row; close a dialog after its original row disappears. Review normal desktop,
+short desktop windows, 1280 px with a 24 px root, RTL and forced colors. Visual
+review and executed checks are separate evidence; the guidance itself is not a
+pass certificate.