wow-view-engine reference

On npm since Wow 9.2.0

@ahoo-wang/wow-view-engine is on npm since Wow 9.2.0, released from the same tag and with the same version as Wow. A patch release never breaks the exports (the ViewStore port among them), the CSS contract, the message keys and issue codes, or the wow-view-engine command; a minor release lists every break in its release notes (compatibility). The design documents are the source of truth for the model. The symbols a host uses most are described by hand in the topic pages below; every name each entry exports is in the generated symbol index.

For what the engine does, read the View Engine guide; for a walkthrough that wires one business object from zero, Getting Started with the View Engine.

Entries

Entry	Exports
@ahoo-wang/wow-view-engine	Model types, pure kernels (validate*, compile*, project*), runtime, the ViewStore port, MemoryViewStore, localStorageSnapshot
/react	useViewEngine, useOpenView, useViewRuntime, useViewList, useViewManager, useWorkbench, useLeaveGuard, useFilterEditor, useRecordTable, useAnalysisEditor, useAnalysisResult, useDashboard, useSaveCommands, useRecordActions, RecordActionSlots
/ui	Workbenches (DataWorkbench, DashboardWorkbench), embeds (EmbeddedView, EmbeddedDashboard), the host's wiring (ViewHost, bind, useViewNavigation, useColorMode), view management (ViewHeader, SaveActions, ViewManager, LeaveDialog), editing and results (FilterPanel, RecordTable, RecordCards, RecordPagination, AnalysisTable, AnalysisChart, DashboardGrid), content panels, and MessagesProvider
/testing	For a host's tests: memorySource and matches (an in-memory ViewSource with Wow's query semantics), resolveNavigation, admit, actionHarness
/react-router	useReactRouter: React Router as the router port a host hands its ViewHost
/styles.css	The theme. Import it explicitly; no JavaScript entry imports CSS
/themes.css	Optional presets, selected by data-fve-preset
/themes/<name>.css	One optional preset alone
/shadcn-bridge.css	Optional: a host's shadcn tokens read into the view's variables, except input, ring, the status and the chart colours

The root entry has no React or DOM dependency. react and react-dom are peer dependencies needed only by /react and /ui; react-router only by /react-router, and mingo only by /testing; all four are optional peers. The package's command, wow-view-engine theme-check, checks a host's theme against the registry (checking a theme).

Concepts

What each type does and where it lives — code, data, the store or memory — together with system, shared and personal views, revisions and conflicts: View Engine Core Concepts.

Built-in field kinds: string, number, boolean, date, datetime, enum, reference, array, elementMatch, search, and the kinds backed by Wow's metadata filters: documentId, aggregateId, tenantId, ownerId, spaceId, and deletion.

Persistence

ViewStore is the only port a backend must satisfy:

interface ViewStore {
  list(definitionId: string, signal?: AbortSignal): Promise<ViewInstanceSummary[]>;
  get(id: string, signal?: AbortSignal): Promise<ViewInstance>;
  create(input: Omit<ViewInstance, 'id' | 'revision'>, ctx: WriteContext): Promise<ViewInstance>;
  save(id: string, config: ViewConfig, revision: string, ctx: WriteContext): Promise<ViewInstance>;
  rename(id: string, title: string, revision: string, ctx: WriteContext): Promise<ViewInstance>;
  delete(id: string, revision: string, ctx: WriteContext): Promise<void>;
  // Optional: without it the view manager offers no "Make shared" / "Make personal".
  changeAudience?(id: string, audience: ViewAudience, revision: string, ctx: WriteContext): Promise<ViewInstance>;
  getPreferences(definitionId: string, signal?: AbortSignal): Promise<ViewPreferences>;
  setPreferences(definitionId: string, prefs: ViewPreferences, ctx: WriteContext): Promise<ViewPreferences>;
  permissions?(definitionId: string): ViewPermissions;
}

Rule	Behavior
Optimistic revision	Writes carry the expected revision; a mismatch throws ViewStoreError with code CONFLICT, and the UI offers reload, overwrite, or save as
Idempotent requestId	Each logical write gets one requestId in WriteContext; a retry after a timeout reuses it and the server deduplicates
Permissions	permissions only drives button availability. Authorization, visibility filtering, and deduplication are server responsibilities
Changing the audience	changeAudience moves a saved view between personal and shared in place, keeping its id, under the same two rules. A request for the audience the view already has answers it unchanged; a view a shared dashboard shows cannot become personal (INVALID, the dashboards' titles in boards)

What each method must do, the six ViewStoreError codes, and ViewPermissions with editSystem are on the persistence port page.

MemoryViewStore is for tests, examples, and query-only use. On a Wow server, use WowViewStore from @ahoo-wang/wow-view-store, over the view store server; only a backend that is not Wow implements the port itself.

Layering

Architecture tests enforce the dependency rules: model imports nothing; filter imports only model; record, analysis, and dashboard import only model and filter; runtime never imports react or ui; store imports only model; react never imports ui. Only the non-deprecated FilterExpression APIs of wow-client are used.

Extension points

Axis	Mechanism
Field type	Register a FieldKind: operators, validation, compile to FilterExpression, and an editor descriptor that names one of the built-in value inputs
Data source	Each entry of resources pairs a definition with its source, a wow-client query client
Persistence	WowViewStore on a Wow server; implement ViewStore for any other backend
Actions	Declare them with actions() and bind them (bind(id, { actions })): the engine places, confirms, runs and reports them; slots (global, bulk, row render functions) are the escape hatch. They are code and are never saved
Appearance	CSS variables, presets and the shadcn bridge (see Theming the View Engine); replace components by composing the /react hooks
Wording	en and zhCN catalogues, merged through the messages prop or MessagesProvider

Topics

Topic	Covers
Engine and Resources	ViewEngine, its options and resources, ViewSource, RuntimeEnvironment
Definitions and Field Kinds	defineView and its spec, rowFields, text keys, FieldKind and the registry
Host Wiring	ViewHost, bind, the router port and useReactRouter, declared actions with actions(), MessagesProvider and wording
Workbenches and Embeds	The props of DataWorkbench, DashboardWorkbench, EmbeddedView, EmbeddedDashboard
React Hooks	The /react hooks
Persistence Port	ViewStore, the ViewStoreError codes, ViewPermissions, MemoryViewStore, localStorageSnapshot
Testing Helpers	/testing's admit, actionHarness, memorySource, resolveNavigation, and the port conformance suite
Issue Codes	Every code the engine can raise with its default wording, generated from the public surface list
Symbol Index	Every name each entry exports, its kind and the first sentence of its TSDoc, generated from the built declarations

Source

typescript/wow-view-engine · README · Design documents · Storybook