@flood-md/agent 0.2.10 → 0.2.12

package/dist/materials/recipe-collection-views.md

@@ -0,0 +1,670 @@
+# Collection filters and saved views
+
+[Open Projects and Files](/playground/collections).
+
+One set of controls serves a DataTable and a FileList. It demonstrates search,
+quick filters, staged conditions, applied tags, saved definitions and sorting from existing
+Flood primitives. CollectionViewControls is project-owned recipe code, not an
+export from @flood-md/react. The installed catalog contains these same typed
+sources. Keep model and controls together; adapt datasets and shell to the host.
+
+## Query ownership
+
+The wide layout has two control rows. View selection and its actions share the
+first row. Search and filter/reset actions share the second row. At most two
+secondary filter properties appear inline. With three or more properties, one
+Filters panel contains the choices, including currently inactive properties.
+Applied conditions remain visible with property names and remove actions.
+Groups wrap as space becomes constrained. Test both empty filters and longer
+selected values before adopting the host layout.
+
+Filters anchors to the inline end of the control row. A reserved Clear filters
+slot precedes it, so applying or clearing conditions does not shift the trigger.
+The inactive reset is visually hidden, disabled and absent from accessibility
+navigation. Applied chips stay in the search area and can wrap independently.
+
+A query contains search, a flat all/any group, enum conditions and sort. Search
+combines with the group using AND. Values within one condition mean any matching
+value; is-not excludes all of them. Missing record values do not match is and do
+match is-not. The host defines properties, values and record meaning.
+
+For inline simple filters, a named Menu applies one value per property immediately.
+The adjacent Tag shows the selected value and gets its property context from
+the menu beside it. Choose All or remove the Tag to clear that property. The Tag returns
+focus to its menu when removed. Projects and Files use the same controls with
+their own properties. Search and sort retain their current values.
+
+The collapsed panel stages its labelled choices until Apply filters. Cancel
+discards the changes. Advanced conditions switches the same panel to the full
+condition editor when exclusions, multiple values or Any logic are needed.
+
+Use the Filters editor for exclusion, multiple values per property or Any across
+properties. It has a separate draft. Apply validates and commits, while Cancel or
+outside dismissal discards it. Advanced conditions are summarized by removable
+tags with their All/Any logic visible when relevant. Clear filters removes search
+and conditions, retaining sort. Unknown properties, values, operators, sort
+columns and schema versions fail explicitly rather than silently broadening a view.
+
+An applied query change outside the editor closes its obsolete draft. Applying
+conditions never restores an old search/sort value from when the editor opened.
+
+DataTable receives the full locally filtered collection. The example resets page
+and selection on query/preset/sort changes. Saving or renaming a definition does
+not change the query or selection. FileList has its own host sort. Remote requests,
+permissions and server-wide selection remain host responsibilities.
+
+Table selection serves real status and archive commands for the chosen projects.
+Hosts without a selection operation should omit selectable rather than display
+checkboxes with no resulting action.
+
+## Selected records
+
+Selecting projects reveals one shared action bar floating at the viewport bottom. It shows the
+selected count, changes status, confirms archiving and clears the
+selection. DataTable uses `showSelection={false}` to keep its result range and
+pagination while announcing the selected count without displaying it again.
+Selection spans the filtered client collection across its pages.
+Changing the query resets it. Archiving captures IDs and names before opening
+the confirmation. Cancel keeps the selection and records intact.
+
+The host owns the update and accepted records. This example changes its in-memory
+records after the optional onUpdateStatus callback accepts the whole operation.
+Reload returns to the declared fixtures. A rejection keeps accepted records and
+selection intact. Retry uses the failed operation's captured IDs and status.
+Dismiss or a deliberate query/selection change abandons its feedback.
+Report results in a floating ToastRegion so the table stays in place.
+Use the default bottom-end placement. Success expires automatically. A failed
+update offers a persistent Retry action. While the selection rail is visible,
+raise the toast above it without changing the table's scroll clearance.
+
+Only one update can run at a time. Pending actions are disabled. If the user
+changes the query or selection while an update is pending, its result still
+belongs to the captured IDs. Success removes those IDs from current selection,
+preserving newly selected records, and returns pagination to the first page.
+The host callback must accept/reject atomically. A service allowing partial
+success needs a per-record result and reconciliation contract.
+
+Clear selection returns focus to the collection. A successful update moves focus
+there if the disappearing action bar held it. Confirmation renders outside the
+roving Toolbar so the dialog retains its own focus model.
+
+```tsx
+import { useState } from 'react';
+import { AlertDialog, BulkActionBar, VisuallyHidden } from '@flood-md/react';
+
+export type ProjectStatus = 'active' | 'paused' | 'archived';
+export interface SelectedProject { id: string; name: string }
+export interface ProjectStatusUpdate { ids: string[]; status: ProjectStatus }
+
+export function ProjectSelectionActions({ projects, pending, onUpdate, onClear }: {
+  projects: readonly SelectedProject[];
+  pending: boolean;
+  onUpdate: (update: ProjectStatusUpdate) => void;
+  onClear: () => void;
+}) {
+  const [archive, setArchive] = useState<SelectedProject[] | null>(null);
+
+  return <>
+    <BulkActionBar label="Selected projects" selectionCount={projects.length} pending={pending}
+      items={[
+        { id: 'archive', label: 'Archive', priority: 10 },
+        { id: 'paused', label: 'Pause', priority: 5 },
+        { id: 'active', label: 'Set active' },
+      ]}
+      onAction={action => {
+        if (action === 'archive') setArchive(projects.map(project => ({ ...project })));
+        else onUpdate({ ids: projects.map(project => project.id), status: action as ProjectStatus });
+      }}
+      onClear={onClear} />
+    <VisuallyHidden role="status">{pending ? 'Updating…' : ''}</VisuallyHidden>
+    {archive && <AlertDialog
+        title={`Archive ${archive.length} ${archive.length === 1 ? 'project' : 'projects'}?`}
+        description={`${archive.map(project => project.name).join(', ')}\n${archive.length === 1 ? 'It' : 'They'} will move to Archived.`}
+        confirmLabel="Archive projects"
+        cancelLabel="Keep projects"
+        open
+        onOpenChange={open => { if (!open) setArchive(null); }}
+        onConfirm={() => {
+          onUpdate({ ids: archive.map(project => project.id), status: 'archived' });
+        }}
+        trigger={() => null}
+      />}
+  </>;
+}
+```
+
+The panel uses the existing floating-surface tokens and a viewport-safe inset.
+It leaves normal document flow and stays centered when the document scrolls.
+Check the table header position and scroll dimensions with zero, one and
+several selected records. A collection that fits should keep fitting on selection.
+BulkActionBar keeps a single pill-shaped row with at most two visible commands
+by default. Lower-priority commands move into More as space shrinks; the host
+keeps the commands on one row. Budget bottom clearance in the base layout
+using the control height, the panel chrome and the viewport inset. At the end
+of a scroll, the final rows and pagination should be reachable above the panel.
+Keep the scroll area inside the bordered Surface and clip the frame at its
+rounded corners so the table footer cannot cover the outline.
+
+```css
+.collection-examples { padding-block:var(--flood-sys-space-8); min-inline-size:0; }
+.collection-view-controls { min-inline-size:0; }
+.flood-root .collection-filter-editor { inline-size:min(42rem,calc(100vw - 2rem)); }
+
+.collection-projects {
+  --collection-selection-inset: max(var(--flood-sys-space-4), env(safe-area-inset-bottom));
+  --collection-selection-control-height: var(--flood-sys-control-sm-height);
+  --collection-selection-height: calc(var(--collection-selection-control-height) + 2 * (var(--flood-sys-space-1) + var(--flood-sys-stroke-width)));
+  padding-block-end: calc(var(--collection-selection-inset) + var(--collection-selection-height) + var(--flood-sys-space-2));
+}
+
+@media (pointer: coarse) {
+  .collection-projects {
+    --collection-selection-control-height: max(var(--flood-sys-control-sm-height), var(--flood-sys-size-touch));
+  }
+}
+
+.collection-table-frame {
+  border: var(--flood-sys-stroke-width) solid var(--flood-sys-color-border-decorative);
+  overflow: clip;
+}
+
+.collection-selection-panel {
+  position: fixed;
+  inset-inline: 0;
+  inset-block-end: var(--collection-selection-inset);
+  margin-inline: auto;
+  inline-size: min(26rem, calc(100% - 2 * var(--flood-sys-space-4)));
+  max-inline-size: calc(100% - 2 * var(--flood-sys-space-4));
+  z-index: var(--flood-sys-layer-sticky);
+}
+
+.flood-root .collection-selection-panel + .flood-toast-region {
+  inset-block-end: calc(var(--collection-selection-inset) + var(--collection-selection-height) + var(--flood-sys-space-2));
+  max-block-size: calc(100dvh - var(--collection-selection-inset) - var(--collection-selection-height) - var(--flood-sys-space-6));
+}
+```
+
+## Working state and saved definitions
+
+Built-in presets are read-only. A saved view stores the query and supported sort,
+not record IDs or cached results. Dirty views offer Update and Reset. Save as new
+captures the current query; Rename changes only its name, even while filters are
+dirty. Deleting a definition leaves collection records unchanged.
+
+Working changes stay transient until saved. Reload starts at the default preset;
+saved definitions remain selectable. Choosing another view replaces the working
+query. URL sharing, remembered active views, nested groups, date/number operators,
+collaboration and cross-tab synchronization are not implemented here.
+
+Names are trimmed, at most 80 UTF-16 code units and unique after NFC/case
+normalization, including preset names. Equality ignores condition UI IDs, condition
+order and selected-value order; it is not general boolean equivalence.
+
+## Persistence and focus
+
+Two keys keep project/file definitions separate. Read occurs after mount to retain
+consistent initial server/client markup. Mount a separate keyed instance when
+changing collection schema. Browser storage is an example adapter, not production
+durability. A missing key means no custom definitions; malformed/refused reads
+preserve the available raw snapshot and block writes to that store. Independently
+loaded records remain usable. Retry/export/explicit replacement address the actual
+preferences failure; exported bytes do not guarantee automatic restoration.
+
+Refused writes retain accepted definitions and entered names. Cancel ends a name
+draft's error; Reset ends a failed update of the discarded query. Read failures
+have a separate lifetime. A real remote adapter needs pending/result ownership,
+reconciliation and migrations rather than this synchronous example.
+
+Existing overlay owners retain nested behaviour. Naming/deletion actions focus
+the persistent view selector before opening a modal so it remains a useful return
+target when an action disappears. Escape closes the value picker before the outer
+condition editor; closing the editor returns to Filters.
+
+## Reused owners
+
+FilterGroup composes FilterCondition rows for the flat advanced draft. It owns
+row addition/removal, duplicate-property choice policy, the all/any switch and
+accepted focus transitions. FilterCondition keeps equal control sizing and
+container-based reflow. Changing a property clears incompatible values only in
+the proposed draft. The collection form retains Apply/Cancel and query validation,
+so creating an incomplete row never changes accepted results.
+
+CollectionToolbar owns the shared query layout: search, accepted summaries,
+reserved Clear filters and end-aligned Filters. Its fieldset uses normal Tab
+navigation because it includes editable text. Keep saved-view controls outside
+this row. Supply the staged editor through filterContent; opening it copies the
+accepted query, Apply accepts it and Cancel abandons it. Reset and removal return
+focus to the persistent Filters trigger (search when no panel exists). The host
+defines reset scope and supplies canClear for any state held by quickFilters.
+At most two task-important quick properties remain inline; additional properties
+belong inside Filters. Summaries outside the panel name the property and preserve
+any-match meaning. Container width, rather than viewport size, governs reflow.
+The Projects table places its Columns control in CollectionToolbar's `actions`
+slot via DataTable's `toolbar` render function. It shares the tool row with
+search and filters, and the commands wrap as a group in a narrow container.
+
+CollectionViewSwitcher owns the separate accepted-view choice and adaptive
+commands. It reuses Field/Select and Button/OverflowActions with the same size.
+The recipe supplies applicable actions and retains all persistence, name-only
+rename, dirty query reset, confirmation and failure recovery. selectRef preserves
+the existing naming/deletion dialog return target; saving a definition does not
+reset result selection.
+
+SearchInput, Select, Menu, MultiSelect and SegmentedControl own input/choice behaviour;
+Popover contains the condition draft and Tag removes applied conditions. Button
+and IconButton perform actions. Several view commands use OverflowActions; a
+single command uses Button directly. Field/Fieldset, Grid/Stack/Inline, Dialog,
+AlertDialog and ToastRegion retain their own roles. DataTable/StatusIndicator and
+FileList/FileItem/FileMeta demonstrate two result structures. No owner is inserted
+merely to increase its usage count, and no new package atom is needed for layout.
+
+For a few mutually exclusive views of the same result table, use SegmentedControl
+with a controlled value. An option's `count` can show workload, such as pending
+items. Leave it unset when it repeats a total already visible beside the results.
+Use Tabs when each choice opens its own associated content panel.
+
+## Model
+
+```ts
+import type {ComboboxOption,DataTableSort} from '@flood-md/react';
+
+export interface FilterProperty {id:string;label:string;options:readonly ComboboxOption[];}
+export interface CollectionSchema {properties:readonly FilterProperty[];sortColumns:readonly string[];}
+export interface FilterCondition {id:string;property:string;operator:'is'|'is-not';values:string[];}
+export interface CollectionQuery {search:string;match:'all'|'any';conditions:FilterCondition[];sort:DataTableSort|null;}
+export interface CollectionView {id:string;name:string;query:CollectionQuery;}
+export type ViewStorage=Pick<Storage,'getItem'|'setItem'>;
+export type ViewRead={state:'ready';views:CollectionView[]}|{state:'error';views:[];raw:string|null};
+const object=(value:unknown):value is Record<string,unknown>=>Boolean(value)&&typeof value==='object'&&!Array.isArray(value);
+export const emptyCollectionQuery=():CollectionQuery=>({search:'',match:'all',conditions:[],sort:null});
+export const copyCollectionQuery=(query:CollectionQuery):CollectionQuery=>({...query,conditions:query.conditions.map(condition=>({...condition,values:[...condition.values]})),sort:query.sort?{...query.sort}:null});
+
+/** Validate persisted definitions instead of silently dropping unknown predicates. */
+export function parseCollectionQuery(value:unknown,schema:CollectionSchema):CollectionQuery {
+ if(!object(value)||typeof value.search!=='string'||(value.match!=='all'&&value.match!=='any')||!Array.isArray(value.conditions))throw Error('Unsupported view query');
+ const ids=new Set<string>(),properties=new Set<string>();
+ const conditions=value.conditions.map((condition:unknown):FilterCondition=>{
+  if(!object(condition)||typeof condition.id!=='string'||!condition.id.trim()||ids.has(condition.id)||typeof condition.property!=='string'||properties.has(condition.property)||(condition.operator!=='is'&&condition.operator!=='is-not')||!Array.isArray(condition.values)||!condition.values.length)throw Error('Unsupported view condition');
+  const property=schema.properties.find(property=>property.id===condition.property);
+  if(!property||new Set(condition.values).size!==condition.values.length||condition.values.some(value=>typeof value!=='string'||!property.options.some(option=>option.value===value)))throw Error('Unknown view values');
+  ids.add(condition.id);properties.add(condition.property);
+  return {id:condition.id,property:condition.property,operator:condition.operator as FilterCondition['operator'],values:[...condition.values] as string[]};
+ });
+ let sort:DataTableSort|null=null;
+ if(value.sort!==null){if(!object(value.sort)||typeof value.sort.column!=='string'||!schema.sortColumns.includes(value.sort.column)||(value.sort.direction!=='ascending'&&value.sort.direction!=='descending'))throw Error('Unsupported view sort');sort={column:value.sort.column,direction:value.sort.direction};}
+ return {search:value.search,match:value.match as CollectionQuery['match'],conditions,sort};
+}
+
+/** Row IDs and condition UI IDs do not define a saved query's meaning. */
+export function collectionQueryKey(query:CollectionQuery){return JSON.stringify({search:query.search.trim(),match:query.conditions.length>1?query.match:'all',conditions:query.conditions.map(({property,operator,values})=>({property,operator,values:[...values].sort()})).sort((a,b)=>a.property.localeCompare(b.property)),sort:query.sort});}
+
+export function matchesCollectionQuery(query:CollectionQuery,searchText:string,read:(property:string)=>string|readonly string[]|null){
+ if(!searchText.toLocaleLowerCase().includes(query.search.trim().toLocaleLowerCase()))return false;
+ const tests=query.conditions.map(condition=>{const raw=read(condition.property),values=raw===null?[]:typeof raw==='string'?[raw]:raw;const includes=condition.values.some(value=>values.includes(value));return condition.operator==='is'?includes:!includes;});
+ return !tests.length||(query.match==='all'?tests.every(Boolean):tests.some(Boolean));
+}
+
+export function readCollectionViews(key:string,schema:CollectionSchema,storage:ViewStorage,reservedNames:readonly string[]=[]):ViewRead {
+ let raw:string|null=null;
+ try{
+  raw=storage.getItem(key);if(raw===null)return {state:'ready',views:[]};
+  const value:unknown=JSON.parse(raw);
+  if(!object(value)||value.version!==1||!Array.isArray(value.views))throw Error('Unsupported saved views');
+  const ids=new Set<string>(),names=new Set(reservedNames.map(name=>name.normalize('NFC').toLowerCase()));
+  const views=value.views.map((view:unknown):CollectionView=>{
+   if(!object(view)||typeof view.id!=='string'||!view.id.startsWith('saved-')||ids.has(view.id)||typeof view.name!=='string'||!view.name.trim()||view.name.length>80||names.has(view.name.trim().normalize('NFC').toLowerCase()))throw Error('Unsupported saved view');
+   ids.add(view.id);names.add(view.name.trim().normalize('NFC').toLowerCase());
+   return {id:view.id,name:view.name.trim(),query:parseCollectionQuery(view.query,schema)};
+  });
+  return {state:'ready',views};
+ }catch{return {state:'error',views:[],raw};}
+}
+```
+
+## Shared controls
+
+```tsx
+"use client";
+import {useEffect,useRef,useState,type FormEvent,type ReactNode} from 'react';
+import {Alert,AlertDialog,Button,CollectionToolbar,CollectionViewSwitcher,Dialog,Field,FilterGroup,IconSlot,Inline,Input,Menu,Select,Stack,Tag,type OverflowAction} from '@flood-md/react';
+import {collectionQueryKey,copyCollectionQuery,parseCollectionQuery,readCollectionViews,type CollectionQuery,type CollectionSchema,type CollectionView,type FilterProperty,type ViewRead,type ViewStorage} from './collection-views-model';
+
+export function AppliedFilterControl({ property, value, onChange }: {
+  property: FilterProperty;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const trigger = useRef<HTMLButtonElement | null>(null);
+  const { id, label, options } = property;
+  const selected = options.find(option => option.value === value);
+
+  return (
+   <Inline gap="2" align="center">
+      <Menu
+        label={label}
+        trigger={({ ref, ...props }) => (
+          <Button {...props} ref={node => { trigger.current = node; ref(node); }} variant="subtle" size="sm">
+            {label} <IconSlot size="xs"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg></IconSlot>
+          </Button>
+        )}
+        items={[{ value: '', label: 'All', disabled: false }, ...options].map(option => ({
+          id: option.value ? `option-${option.value}` : 'all',
+          label: option.label,
+          type: 'radio',
+          group: id,
+          disabled: option.disabled,
+          checked: value === option.value,
+          closeOnSelect: true,
+          onCheckedChange: () => onChange(option.value),
+        }))}
+      />
+      {selected && (
+        <Tag size="md" removeLabel={`Remove ${label.toLowerCase()} filter: ${selected.label}`} onRemove={() => {
+          trigger.current?.focus({ preventScroll: true });
+          onChange('');
+        }}>
+          {selected.label}
+        </Tag>
+      )}
+    </Inline>
+  );
+}
+
+interface CollectionViewControlsProps {
+ label:string;schema:CollectionSchema;presets:readonly CollectionView[];
+ value:CollectionQuery;onValueChange:(query:CollectionQuery)=>void;storageKey:string;storage?:ViewStorage;toolbarActions?:ReactNode;
+}
+type NameDraft={kind:'create'|'rename';id?:string;name:string;snapshot:CollectionQuery;error?:string;invalid?:string};
+const inlineFilterLimit = 2;
+
+/** Host recipe: shared behaviour, not a second Flood component implementation. */
+export function CollectionViewControls({label,schema,presets,value,onValueChange,storageKey,storage,toolbarActions}:CollectionViewControlsProps){
+ const [saved,setSaved]=useState<ViewRead|{state:'loading';views:[]}>({state:'loading',views:[]}),[selectedId,setSelectedId]=useState(presets[0].id);
+ const [editing,setEditing]=useState(false),[draft,setDraft]=useState(()=>copyCollectionQuery(value)),[draftError,setDraftError]=useState('');
+ const [advancedEditor, setAdvancedEditor] = useState(false);
+ const editorPanel = useRef<HTMLDivElement>(null);
+ const [nameDraft,setNameDraft]=useState<NameDraft|null>(null),[confirmation,setConfirmation]=useState<{kind:'delete';id:string;name:string}|{kind:'replace'}|null>(null);
+ const [operationError,setOperationError]=useState<{kind:'update'|'delete'|'replace'|'export';message:string}|null>(null),[readAttempt,setReadAttempt]=useState(0);
+ const nameInput=useRef<HTMLInputElement>(null),viewInput=useRef<HTMLSelectElement>(null);
+ const schemaKey=JSON.stringify({properties:schema.properties.map(property=>[property.id,property.options.map(option=>option.value)]),sort:schema.sortColumns});
+ const appliedKey=collectionQueryKey(value);
+ const compactConditions = (value.match === 'all' || value.conditions.length < 2) &&
+   value.conditions.every(condition => condition.operator === 'is' && condition.values.length === 1);
+ const collapseFilters = schema.properties.length > inlineFilterLimit;
+ const canClearFilters = value.conditions.length > 0 || Boolean(value.search);
+ const simpleEditor = collapseFilters && compactConditions && !advancedEditor;
+
+ useEffect(() => {
+   if (advancedEditor) editorPanel.current?.focus({ preventScroll: true });
+ }, [advancedEditor]);
+
+ function changeSimpleDraft(property: string, option: string) {
+   setDraft(current => {
+     const existing = current.conditions.find(condition => condition.property === property);
+     const conditions = current.conditions.filter(condition => condition.property !== property);
+     if (option) conditions.push({ id: existing?.id ?? crypto.randomUUID(), property, operator: 'is', values: [option] });
+     return { ...current, match: 'all', conditions };
+   });
+ }
+
+ function changeQuickFilter(property: string, option: string) {
+   const existing = value.conditions.find(condition => condition.property === property);
+   const conditions = value.conditions.filter(condition => condition.property !== property);
+   if (option) conditions.push({ id: existing?.id ?? crypto.randomUUID(), property, operator: 'is', values: [option] });
+   onValueChange({ ...value, match: 'all', conditions });
+ }
+ useEffect(()=>setEditing(false),[appliedKey]);
+ useEffect(()=>{try{setSaved(readCollectionViews(storageKey,schema,storage??window.localStorage,presets.map(preset=>preset.name)));}catch{setSaved({state:'error',views:[],raw:null});}},[storageKey,storage,schemaKey,readAttempt]);
+ const views=[...presets,...saved.views],selected=views.find(view=>view.id===selectedId)??presets[0];
+ const dirty=collectionQueryKey(value)!==collectionQueryKey(selected.query),custom=saved.views.find(view=>view.id===selected.id);
+ function persist(views:CollectionView[]){
+  if(saved.state!=='ready')return false;
+  try{(storage??window.localStorage).setItem(storageKey,JSON.stringify({version:1,views}));setSaved({state:'ready',views});setOperationError(null);return true;}catch{return false;}
+ }
+ const requestEditor=(next:boolean)=>{if(next){setDraft(copyCollectionQuery(value));setDraftError('');setAdvancedEditor(false);}setEditing(next);};
+ function apply(event:FormEvent<HTMLFormElement>){event.preventDefault();try{onValueChange(parseCollectionQuery({...value,match:draft.match,conditions:draft.conditions},schema));setEditing(false);}catch{setDraftError('Choose a value for each condition.');}}
+ function saveName(event:FormEvent<HTMLFormElement>){
+  event.preventDefault();if(!nameDraft)return;const name=nameDraft.name.trim();
+  if(!name){setNameDraft({...nameDraft,invalid:'Enter a view name.'});return;}
+  if(views.some(view=>view.id!==nameDraft.id&&view.name.normalize('NFC').toLowerCase()===name.normalize('NFC').toLowerCase())){setNameDraft({...nameDraft,invalid:'A view with this name already exists.'});return;}
+  const id=nameDraft.kind==='create'?`saved-${crypto.randomUUID()}`:nameDraft.id!;
+  const next=nameDraft.kind==='create'?[...saved.views,{id,name,query:copyCollectionQuery(nameDraft.snapshot)}]:saved.views.map(view=>view.id===id?{...view,name}:view);
+  if(persist(next)){setNameDraft(null);setSelectedId(id);}else setNameDraft({...nameDraft,error:'The view could not be saved. Try again.'});
+ }
+ function action(id:string){
+  if(id==='reset'){onValueChange(copyCollectionQuery(selected.query));setOperationError(error=>error?.kind==='update'?null:error);return;}
+  if(id==='create'||id==='rename'||id==='delete')viewInput.current?.focus({preventScroll:true});
+  if(id==='create')setNameDraft({kind:'create',name:'',snapshot:copyCollectionQuery(value)});
+  else if(id==='rename'&&custom)setNameDraft({kind:'rename',id:custom.id,name:custom.name,snapshot:copyCollectionQuery(custom.query)});
+  else if(id==='update'&&custom){if(!persist(saved.views.map(view=>view.id===custom.id?{...view,query:copyCollectionQuery(value)}:view)))setOperationError({kind:'update',message:'The view could not be updated. Try again.'});}
+  else if(id==='delete'&&custom)setConfirmation({kind:'delete',id:custom.id,name:custom.name});
+ }
+ function confirm(){
+  const pending=confirmation;setConfirmation(null);if(!pending)return;
+  if(pending.kind==='delete'){
+   if(persist(saved.views.filter(view=>view.id!==pending.id))){setSelectedId(presets[0].id);onValueChange(copyCollectionQuery(presets[0].query));}
+   else setOperationError({kind:'delete',message:'The view could not be deleted. Try again.'});
+  }else{
+   try{(storage??window.localStorage).setItem(storageKey,JSON.stringify({version:1,views:[]}));setSaved({state:'ready',views:[]});setSelectedId(presets[0].id);setOperationError(null);}
+   catch{setOperationError({kind:'replace',message:'Saved views could not be replaced.'});}
+  }
+ }
+ function exportSnapshot(){
+  if(saved.state!=='error'||saved.raw===null)return;
+  try{const url=URL.createObjectURL(new Blob([saved.raw],{type:'application/json'})),link=document.createElement('a');link.href=url;link.download='saved-views-recovery.json';link.click();setTimeout(()=>URL.revokeObjectURL(url),0);}catch{setOperationError({kind:'export',message:'The snapshot could not be exported.'});}
+ }
+ const actions:OverflowAction[]=[
+  ...(custom&&dirty?[{id:'update',label:'Update view',priority:20,disabled:saved.state!=='ready'}]:[]),
+  {id:'create',label:'Save as new view',priority:10,disabled:saved.state!=='ready'},
+  ...(dirty?[{id:'reset',label:'Reset view'}]:[]),
+  ...(custom?[{id:'rename',label:'Rename',disabled:saved.state!=='ready'},{id:'delete',label:'Delete view',tone:'danger' as const,disabled:saved.state!=='ready'}]:[]),
+ ];
+ return <Stack gap="3" className="collection-view-controls" aria-label={`${label} collection controls`}>
+  <CollectionViewSwitcher label={`${label} view`} selectRef={viewInput} controlSize="sm"
+    views={views.map(view=>({id:view.id,name:view.name}))} value={selected.id}
+    onValueChange={id=>{const next=views.find(view=>view.id===id);if(next){setSelectedId(next.id);setOperationError(null);onValueChange(copyCollectionQuery(next.query));}}}
+    actions={actions} actionsLabel={`${label} view actions`} moreLabel="View actions" onAction={action}/>
+  {saved.state==='error'&&<Stack gap="3"><Alert tone="error">Saved views could not be read.</Alert><Inline gap="3"><Button size="sm" variant="subtle" onClick={()=>setReadAttempt(attempt=>attempt+1)}>Retry saved views</Button>{saved.raw!==null&&<Button size="sm" variant="subtle" onClick={exportSnapshot}>Export snapshot</Button>}<Button size="sm" variant="subtle" tone="danger" onClick={()=>{viewInput.current?.focus({preventScroll:true});setConfirmation({kind:'replace'});}}>Replace saved views</Button></Inline></Stack>}
+  {operationError&&<Alert tone="error" announcement="polite"><Inline gap="3">{operationError.message}<Button size="sm" variant="ghost" onClick={()=>setOperationError(null)}>Dismiss</Button></Inline></Alert>}
+  <CollectionToolbar label={label+' collection toolbar'} searchValue={value.search}
+    actions={toolbarActions}
+    onSearchValueChange={search=>onValueChange({...value,search})}
+    searchLabel={'Search '+label.toLowerCase()} searchPlaceholder={'Search '+label.toLowerCase()+'…'} clearSearchLabel={'Clear '+label.toLowerCase()+' search'}
+    appliedFiltersLabel={label+' applied filters'}
+    quickFilters={compactConditions&&!collapseFilters?schema.properties.map(property=><AppliedFilterControl key={property.id}
+      property={property} value={value.conditions.find(condition=>condition.property===property.id)?.values[0]??''}
+      onChange={option=>changeQuickFilter(property.id,option)} />):undefined}
+    appliedFilters={compactConditions&&!collapseFilters?[]:value.conditions.map(condition=>{
+      const property=schema.properties.find(property=>property.id===condition.property)!;
+      const labels=condition.values.map(id=>property.options.find(option=>option.value===id)!.label);
+      return {id:condition.id,label:property.label+(compactConditions?': ':condition.operator==='is'?' is ':' excludes ')+labels.join(condition.operator==='is'?' or ':', '),
+        removeLabel:'Remove '+property.label.toLowerCase()+' filter'+(compactConditions?': '+labels[0]:'')};
+    })}
+    summaryPrefix={!compactConditions&&value.conditions.length>1?(value.match==='all'?'All:':'Any:'):undefined}
+    onRemoveFilter={id=>onValueChange({...value,conditions:value.conditions.filter(condition=>condition.id!==id)})}
+    onClear={()=>onValueChange({...value,search:'',conditions:[]})} canClear={canClearFilters}
+    filterTitle={label+' filters'} filtersOpen={editing} onFiltersOpenChange={requestEditor}
+    filterPanelRef={editorPanel} filterPanelClassName={simpleEditor?undefined:'collection-filter-editor'}
+    filterContent={
+    <form onSubmit={apply}><Stack gap="4">
+     {simpleEditor ? <>
+       {schema.properties.map(property => (
+         <Field key={property.id} label={property.label}>{props => (
+           <Select {...props} controlSize="sm"
+             value={draft.conditions.find(condition => condition.property === property.id)?.values[0] ?? ''}
+             onChange={event => changeSimpleDraft(property.id, event.currentTarget.value)}>
+             <option value="">All</option>
+             {property.options.map(option => <option key={option.value} value={option.value} disabled={option.disabled}>{option.label}</option>)}
+           </Select>
+         )}</Field>
+       ))}
+       <Button variant="subtle" size="sm" onClick={() => setAdvancedEditor(true)}>Advanced conditions</Button>
+     </> : <>
+     <FilterGroup label={`${label} conditions`} properties={schema.properties}
+       value={{match:draft.match,conditions:draft.conditions}}
+       onValueChange={next=>{setDraft(current=>({...current,...next}));setDraftError('');}} />
+     </>}
+     {draftError&&<Alert tone="error" announcement="polite">{draftError}</Alert>}
+     <Inline gap="3"><Button type="submit">Apply filters</Button><Button variant="subtle" onClick={()=>setEditing(false)}>Cancel</Button></Inline>
+    </Stack></form>
+    } />
+  {nameDraft&&<Dialog title={nameDraft.kind==='create'?'Save view':'Rename view'} open onOpenChange={next=>{if(!next)setNameDraft(null);}} trigger={()=>null} initialFocusRef={nameInput}>
+   <form onSubmit={saveName}><Stack gap="6"><Field label="View name" required error={nameDraft.invalid}>{props=><Input {...props} ref={nameInput} maxLength={80} value={nameDraft.name} onChange={event=>setNameDraft({...nameDraft,name:event.target.value,invalid:undefined})}/>}</Field>{nameDraft.error&&<Alert tone="error" announcement="polite">{nameDraft.error}</Alert>}<Inline gap="3"><Button type="submit">{nameDraft.kind==='create'?'Save view':'Rename view'}</Button><Button variant="subtle" onClick={()=>setNameDraft(null)}>Cancel</Button></Inline></Stack></form>
+  </Dialog>}
+  {confirmation&&<AlertDialog open onOpenChange={next=>{if(!next)setConfirmation(null);}} trigger={()=>null} title={confirmation.kind==='delete'?`Delete “${confirmation.name}”?`:'Replace saved views?'} description={confirmation.kind==='delete'?'The saved view will be removed. Collection records are unchanged.':'Unreadable saved views will be replaced with an empty set. Export the snapshot first if you need it.'} confirmLabel={confirmation.kind==='delete'?'Delete view':'Replace saved views'} cancelLabel="Keep views" onConfirm={confirm}/>}
+ </Stack>;
+}
+```
+
+## Two consumers
+
+Projects keeps DataTable mounted when an accepted filter finds no rows. Its
+emptyContent composes EmptyState and Reset filters; the host clears search and
+conditions, retains sort, resets page/selection and returns focus to search.
+This is distinct from a read failure or loading state, which remain DataTable's
+Alert/retry and Spinner owners. Files uses EmptyState outside its native FileList.
+
+The last export is the website-only shell. Hosts need the model, controls and their
+chosen consumer with actual data and their own chrome.
+
+```tsx
+"use client";
+import {useRef,useState} from 'react';
+import {Button,DataTable,EmptyState,Field,FileItem,FileList,FloodRoot,Heading,Select,Stack,StatusIndicator,Surface,Tabs,ToastRegion,type ToastItem} from '@flood-md/react';
+import {SiteHeader} from './site-header';
+import {SiteFooter} from './site-footer';
+import {CollectionViewControls} from './recipes/collection-views';
+import {emptyCollectionQuery,matchesCollectionQuery,type CollectionQuery,type CollectionSchema,type CollectionView,type ViewStorage} from './recipes/collection-views-model';
+import './collections-playground.css';
+import {ProjectSelectionActions,type ProjectStatusUpdate} from './recipes/project-selection-actions';
+
+const owners=[{value:'maya',label:'Maya'},{value:'noah',label:'Noah'},{value:'sam',label:'Sam'}];
+const projectSchema:CollectionSchema={properties:[
+ {id:'status',label:'Status',options:[{value:'active',label:'Active'},{value:'paused',label:'Paused'},{value:'archived',label:'Archived'}]},
+ {id:'owner',label:'Owner',options:owners},
+ {id:'priority',label:'Priority',options:[{value:'urgent',label:'Urgent'},{value:'normal',label:'Normal'}]},
+],sortColumns:['name','owner','status','priority']};
+const projects=[
+ {id:'design',name:'Design system',status:'active',owner:'maya',priority:'urgent'},
+ {id:'checkout',name:'Checkout',status:'active',owner:'noah',priority:'urgent'},
+ {id:'help',name:'Help center',status:'paused',owner:'sam',priority:'normal'},
+ {id:'portal',name:'Customer portal',status:'active',owner:'maya',priority:'normal'},
+ {id:'analytics',name:'Analytics',status:'archived',owner:'noah',priority:'normal'},
+ {id:'onboarding',name:'Onboarding',status:'paused',owner:'maya',priority:'urgent'},
+ {id:'docs',name:'Documentation',status:'active',owner:'sam',priority:'normal'},
+ {id:'billing',name:'Billing',status:'archived',owner:'sam',priority:'normal'},
+];
+const projectPresets:CollectionView[]=[{id:'all',name:'All projects',query:emptyCollectionQuery()},{id:'active',name:'Active projects',query:{...emptyCollectionQuery(),conditions:[{id:'preset-active',property:'status',operator:'is',values:['active']}]}}];
+
+export function ProjectCollection({storage,onUpdateStatus}: {
+ storage?:ViewStorage;
+ onUpdateStatus?:(update:ProjectStatusUpdate)=>void|Promise<void>;
+}){
+ const [records, setRecords] = useState(projects);
+ const [query, setQuery] = useState(emptyCollectionQuery);
+ const [page, setPage] = useState(1);
+ const [selection, setSelection] = useState<readonly string[]>([]);
+ const [pending, setPending] = useState(false);
+ const [feedback, setFeedback] = useState<ToastItem | null>(null);
+ const feedbackSequence = useRef(0);
+ const inFlight = useRef(false);
+ const collection = useRef<HTMLElement>(null);
+ const selectionPanel = useRef<HTMLDivElement>(null);
+ const change = (query: CollectionQuery) => {
+   setQuery(query);
+   setPage(1);
+   setSelection([]);
+   setFeedback(null);
+ };
+ const rows=records.filter(project=>matchesCollectionQuery(query,`${project.name} ${owners.find(owner=>owner.value===project.owner)!.label}`,property=>project[property as 'status'|'owner'|'priority']));
+ const selectedProjects=rows.filter(project=>selection.includes(project.id));
+ const hasSelection = selectedProjects.length > 0;
+
+ async function updateStatus(proposal: ProjectStatusUpdate) {
+   if (inFlight.current) return;
+   const update = { ids: [...new Set(proposal.ids)], status: proposal.status };
+   if (!update.ids.length) return;
+   inFlight.current = true;
+   setPending(true);
+   setFeedback(null);
+   try {
+     await onUpdateStatus?.({ ids: [...update.ids], status: update.status });
+     const ids = new Set(update.ids);
+     setRecords(current => current.map(project => ids.has(project.id) ? { ...project, status: update.status } : project));
+     if (selectionPanel.current?.contains(collection.current?.ownerDocument.activeElement ?? null)) {
+       collection.current?.focus({ preventScroll: true });
+     }
+     setSelection(current => current.filter(id => !ids.has(id)));
+     setPage(1);
+     const result = update.status === 'active' ? 'set active' : update.status;
+     setFeedback({ id: String(++feedbackSequence.current), status: 'success', title: `${ids.size} ${ids.size === 1 ? 'project' : 'projects'} ${result}.` });
+   } catch {
+     setFeedback({
+       id: String(++feedbackSequence.current),
+       status: 'error',
+       title: `Couldn’t update ${update.ids.length} ${update.ids.length === 1 ? 'project' : 'projects'}.`,
+       action: { label: 'Retry update', onClick: () => {
+         collection.current?.focus({ preventScroll: true });
+         void updateStatus(update);
+       }},
+     });
+   } finally {
+     inFlight.current = false;
+     setPending(false);
+   }
+ }
+
+ return <section ref={collection} tabIndex={-1} className="collection-projects" aria-label="Projects collection"><Stack gap="6">
+  {hasSelection&&<div ref={selectionPanel} className="collection-selection-panel"><ProjectSelectionActions projects={selectedProjects} pending={pending} onUpdate={update=>{void updateStatus(update);}} onClear={()=>{
+   collection.current?.focus({preventScroll:true});setSelection([]);setFeedback(null);
+  }}/></div>}
+  <ToastRegion label="Project updates" items={feedback ? [feedback] : []}
+   onDismiss={id=>setFeedback(current=>current?.id===id?null:current)}/>
+  <Surface padding="0" className="collection-table-frame">
+   <DataTable caption="Projects" hideCaption minWidth="36rem" selectable showSelection={false} pageSize={5} page={page} onPageChange={setPage} selectedIds={selection} onSelectionChange={ids=>{setSelection(ids);setFeedback(null);}} sort={query.sort} onSortChange={sort=>change({...query,sort})}
+   inset="roomy" showColumnVisibility
+   toolbar={({columns}) => <CollectionViewControls label="Projects" schema={projectSchema} presets={projectPresets}
+     value={query} onValueChange={change} storageKey="flood-project-views-v1" storage={storage} toolbarActions={columns}/>}
+   emptyContent={<EmptyState title="No matching projects" actions={<Button variant="subtle" onClick={()=>{change({...query,search:'',conditions:[]});collection.current?.querySelector<HTMLInputElement>('.flood-collection-toolbar input')?.focus({preventScroll:true});}}>Reset filters</Button>}/>}
+   columns={[{id:'name',label:'Project',sortable:true,hideable:false},{id:'owner',label:'Owner',sortable:true},{id:'status',label:'Status',sortable:true},{id:'priority',label:'Priority',sortable:true}]}
+   rows={rows.map(project=>({id:project.id,label:project.name,cells:{name:project.name,owner:owners.find(owner=>owner.value===project.owner)!.label,status:<StatusIndicator label={projectSchema.properties[0].options.find(option=>option.value===project.status)!.label} tone={project.status==='active'?'success':project.status==='paused'?'warning':'neutral'}/>,priority:project.priority==='urgent'?'Urgent':'Normal'},sortValues:{name:project.name,owner:project.owner,status:project.status,priority:project.priority==='urgent'?1:0}}))}/>
+  </Surface>
+ </Stack></section>;
+}
+
+const teams=[{value:'design',label:'Design team'},{value:'product',label:'Product team'},{value:'finance',label:'Finance team'}];
+const fileSchema:CollectionSchema={properties:[
+ {id:'kind',label:'Format',options:[{value:'pdf',label:'PDF'},{value:'fig',label:'Figma'},{value:'png',label:'PNG'},{value:'csv',label:'CSV'}]},
+ {id:'team',label:'Team',options:teams},
+],sortColumns:['name','size']};
+const files=[
+ {id:'guidelines',name:'Brand guidelines.pdf',kind:'pdf',team:'design',size:2400000},
+ {id:'library',name:'Component library.fig',kind:'fig',team:'design',size:18400000},
+ {id:'research',name:'Research summary.pdf',kind:'pdf',team:'product',size:780000},
+ {id:'forecast',name:'Revenue forecast.csv',kind:'csv',team:'finance',size:28000},
+ {id:'cover',name:'Launch cover.png',kind:'png',team:'design',size:4100000},
+ {id:'feedback',name:'Customer feedback.csv',kind:'csv',team:'product',size:92000},
+];
+const fileDefault=():CollectionQuery=>({...emptyCollectionQuery(),sort:{column:'name',direction:'ascending'}});
+const filePresets:CollectionView[]=[{id:'all',name:'All files',query:fileDefault()},{id:'design',name:'Design files',query:{...fileDefault(),conditions:[{id:'preset-design',property:'team',operator:'is',values:['design']}]}}];
+export function FileCollection({storage}: {storage?:ViewStorage}){
+ const [query,setQuery]=useState(fileDefault);
+ const sort=query.sort??{column:'name',direction:'ascending'};
+ const rows=files.filter(file=>matchesCollectionQuery(query,file.name,property=>file[property as 'kind'|'team'])).sort((a,b)=>(sort.column==='size'?a.size-b.size:a.name.localeCompare(b.name))*(sort.direction==='ascending'?1:-1));
+ return <section aria-label="Files collection"><Stack gap="6">
+  <CollectionViewControls label="Files" schema={fileSchema} presets={filePresets} value={query} onValueChange={setQuery} storageKey="flood-file-views-v1" storage={storage}/>
+  <div style={{maxWidth:'16rem'}}><Field label="Sort files" hideLabel>{props=><Select {...props} value={`${sort.column}:${sort.direction}`} onChange={event=>{const[column,direction]=event.target.value.split(':');setQuery({...query,sort:{column,direction:direction as 'ascending'|'descending'}});}}><option value="name:ascending">Name A–Z</option><option value="name:descending">Name Z–A</option><option value="size:ascending">Size small–large</option><option value="size:descending">Size large–small</option></Select>}</Field></div>
+  {rows.length?<FileList label="Files">{rows.map(file=><FileItem key={file.id} name={file.name} size={file.size} format={file.kind.toUpperCase()} description={teams.find(team=>team.value===file.team)!.label}/>)}</FileList>:<EmptyState title="No matching files" actions={<Button variant="subtle" onClick={()=>setQuery({...query,search:'',conditions:[]})}>Reset filters</Button>}/>}
+ </Stack></section>;
+}
+
+export default function CollectionsPlayground(){return <FloodRoot className="site-root"><div className="site-shell"><SiteHeader path="/playground/collections"/><main id="main-content" className="collection-examples"><Stack gap="4"><Heading level={1} size="page">Collections</Heading><Tabs label="Collection examples" variant="line" items={[{value:'projects',label:'Projects',content:<ProjectCollection/>},{value:'files',label:'Files',content:<FileCollection/>}]}/></Stack></main><SiteFooter/></div></FloodRoot>;}
+```
+
+## Verification
+
+Exercise all/any, exclusion, incomplete drafts, Cancel/Escape, removal and no-results.
+Verify page/selection changes; save, rename while dirty, update, reset, delete and
+reload. Refuse reads/writes and preserve bytes/names. Check both consumers, nested
+focus, narrow/enlarged geometry and final scroll actions. These checks do not
+establish full UX, performance or assistive-technology certification.