Fetcher View Engine

Fetcher View Engine

Read references/api.md before composing or changing public APIs. Verify exports against packages/view-engine/src/index.ts and src/react.ts and reuse the package's examples and Storybook scenarios.

Choose the composition boundary

• For a complete workbench with saved-view navigation and management, use ViewPage. It owns the engine lifecycle; keep scopeKey stable for the same user/tenant/access scope and recreate it when that identity changes.
• For a caller-owned ViewEngine, use RecordView for the record workbench or ViewPageContent for the navigation/management shell. The caller disposes its engine.
• For a controlled table with externally owned data, use RecordTable. For an isolated buffered filter editor, use FilterPanel; its caller handles onApply and any requests or saving. Use FieldFilter for a fixed field and FilterSelect for controlled labels/values.
• Import headless contracts, ViewEngine and MemoryViewHost from the core entry, React components from /react, and compiled styles from /styles.css.

Connect a record workbench

1. Describe the actual response with ViewDefinition: source ID, own-property rowKey/field navigation paths, field metadata and allowed operators. Store columns and their renderer references in ViewInstance.config.presentation.table.columns, alongside the instance’s filter, sort and pagination configuration. Response property names exclude dots; dots in configured paths only navigate objects/arrays. Definitions and saved ViewInstance configurations are JSON; runtime functions belong in extensions.
2. Implement the applicable ViewHost services: definition, instance, preference, permission, plus resolveSource for business queries. The host provides metadata, persistence, current-user authorization and request identity/CAS guarantees. Reuse Fetcher/Wow query clients and existing storage APIs.
3. Let the engine coordinate selection, filter drafts/applied/saved state, paged/cursor navigation, queries, summaries, saving and recovery. Complete workbenches use engine commands for these operations. Instance lists supply defaultInstanceId: null or a returned ID. Saved operators must satisfy both definition-wide and field-level restrictions.
4. Persist config.filters component properties and references. The registered component owns pure compilation to a Wow filter; Query/Enter applies the draft. Preserve unset controls and opaque custom props. In React, register each component and compiler together through extensions.filters; directly owned headless engines use filterCompilers.
5. Use extensions.globalActions, toolbarActions, rowActions, filters and cells for the five extension points. Table actions handle current-page batch selection. Reuse built-in filters and cell renderers before adding custom components; report invalid editor buffers through onValidityChange.
6. Respect the current capability/permission snapshot and system-view name/delete restrictions. Keep drafts after failures. Use retryQuery for record failures, refreshSummary for aggregate failures, and reloadInstance for instance/write reconciliation. Unknown creations keep their original request ID/body; source-less recovery contexts remain in pendingCreates. These are local recovery entries, not ordinary queryable or saveable views. See the reference for conflict and idempotent-replay contracts.

Verify delivery

• Use IndexedDBViewHost for real browser persistence; use MemoryViewHost and the existing development HTTP fixtures for Node/in-process state to verify saved JSON through a fresh host/engine back into components, including extension props, permissions and uncertain-write recovery. Business records stay outside view storage.
• Reuse the shadcn components in src/components/ui. Preserve Base UI behavior, fve: utilities, --fve-* tokens, scoped portal themes and accessibility.
• Run affected package tests/builds; include Storybook interaction checks for UI changes and the existing package/host acceptance commands for delivery-contract changes. Repository commits require the full pnpm test:unit check. Read exact commands from package scripts and the API reference.