@zuilib/apps

The standard ZUI package for view creation and governed applications.

@zuilib/apps owns both layers because they are one system:

• ViewSpec describes a page as inert JSON rendered through a typed component registry. It supports datasets, bindings, actions, expressions, responsive layout, validation, streaming AI generation, user customization and inline editing.
• AppSpec composes those views into a product with pages, resources, shared state, governed actions, policies, environments, publish targets, host adapters and telemetry.

A view is the page-sized building block of an app. View APIs and presets are exported from Apps directly, so the first analytics screen can grow into a product without changing contracts.

Render a view

import ViewRenderer, {createViewRegistry, defineDataset} from '@zuilib/apps'
import {coreViewTypes} from '@zuilib/apps/core'
import {analyticsViewTypes} from '@zuilib/apps/analytics'

const registry = createViewRegistry(coreViewTypes, analyticsViewTypes)
const orders = defineDataset({
  name: 'orders',
  columns: [
    {field: 'region', dataType: 'string'},
    {field: 'total', dataType: 'number', format: 'currency:USD'},
  ],
})

<ViewRenderer
  spec={view}
  registry={registry}
  datasets={{orders: rows}}
  datasetSchemas={[orders]}
  actions={{openOrder}}
  onFiltersChange={persistFilters}
/>

The renderer is defensive: unknown types become placeholders, node failures are contained by error boundaries, and onIssue reports both. Specs carry no credentials, functions or styles; the host supplies live data and handlers, and the token contract supplies the theme.

Registry components are ordinary React element types. They can be browser elements or components from your application, another design system, or a third-party library; they do not need to use ZUI primitives. A registry can be entirely application-owned—coreViewTypes is optional:

import {DataTable} from '@acme/ui'

const registry = createViewRegistry([
  {
    type: 'section',
    description: 'A native section.',
    component: 'section',
    children: 'nodes',
  },
  {
    type: 'accounts-table',
    description: 'The application account table.',
    component: DataTable,
    props: {
      rows: {valueType: 'data', required: true},
      onRowClick: {valueType: 'action'},
    },
  },
])

const view = {
  version: 2,
  root: {
    type: 'accounts-table',
    props: {
      rows: {$bind: 'accounts'},
      onRowClick: {$action: 'open-account'},
    },
  },
}

The props metadata remains the serializable view contract used by validation, the editor, and generation; it is independent of how the React component is implemented. The renderer resolves live $bind data, $action callbacks, state, loading, authorization, and responsive placement before invoking the component. The same definitions appear in the visual builder's component catalog and properties inspector.

Flat component APIs work directly. Use a definition's render function as a small adapter for compound libraries or when view prop names need translating. The component library remains responsible for its own provider, theme, CSS, and fonts. The optional ZUI presets are only needed when the registry uses them; the prebuilt editor and @zuilib/builder still use ZUI for their own authoring chrome, without imposing it on the components rendered in the canvas.

Run an app

import {AppRuntimeProvider, PublishedApp, defineApp} from '@zuilib/apps'

const app = defineApp({
  version: 1,
  id: 'revenue-ops',
  name: 'Revenue operations',
  pages: [{id: 'overview', path: '/', title: 'Overview', view}],
  resources,
  variables,
  actions,
  policies,
  environments,
  publishTargets,
})

<AppRuntimeProvider
  app={app}
  adapters={hostAdapters}
  subject={currentUser}
  environment="production"
>
  <PublishedApp registry={registry} />
</AppRuntimeProvider>

Runtime adapters are the executable boundary. They connect resources, actions, authoritative policy checks, state persistence, confirmations, transitions and telemetry without putting backend implementations in the app document.

Author and generate

• ViewEditor from @zuilib/apps/editor turns the rendered view into an inline editing surface. Drag, insert, hide, duplicate and prop edits all emit minimal ViewPatch[] operations with undo and redo.
• ViewWorkbench from @zuilib/apps/workbench adds Edit, Preview and Code modes plus an assistant that previews model-proposed patches before apply.
• registryPrompt, viewJsonSchema, parsePartialViewSpec, editPrompt, patchJsonSchema and validateViewPatches ground models in the same registry used for rendering and validation.
• App AI helpers from @zuilib/apps/ai create prompt context and schemas for reviewable AppPatch transactions.

Use @zuilib/builder when you want the complete app library, creation flow, four-region authoring workspace, permission simulator and publishing UI.

Entry points

| Import | Purpose | | --- | --- | | @zuilib/apps | View renderer, registry, schemas, filters, patches and AI helpers plus AppSpec, runtime, validation and telemetry. | | @zuilib/apps/editor | Inline ViewEditor, prop editors, insert and editor-patch helpers. | | @zuilib/apps/workbench | Complete view workbench and assistant panel. | | @zuilib/apps/core | Core layout, typography, surface, feedback, form and data-display view types. | | @zuilib/apps/charts | Chart view types. | | @zuilib/apps/analytics | Analytics view types including pivot, map, drilldown, comparison, forecast and insight. | | @zuilib/apps/data-grid | Data-grid view types. | | @zuilib/apps/ai | AI view types and app AI helpers. | | @zuilib/apps/text-editor | Markdown-editor view types. | | @zuilib/apps/view-spec | View document types. | | @zuilib/apps/view-runtime | View runtime context and binding access. | | @zuilib/apps/spec | App document types and defineApp. | | @zuilib/apps/runtime | App provider and published runtime. | | @zuilib/apps/validation | App validation and publish gates. | | @zuilib/apps/patches | App patch, diff and composition helpers. | | @zuilib/apps/telemetry | Runtime telemetry and health computation. |

Install

pnpm add @zuilib/apps

# Optional presets—install only what your registry uses
pnpm add @zuilib/charts
pnpm add @zuilib/data-grid
pnpm add @zuilib/ai
pnpm add @zuilib/text-editor

React and React DOM are the required peers. For Tailwind v4, register only the packages whose rendered view types you use:

@import "tailwindcss";
@import "@zuilib/primitives/tailwind.css";
@import "@zuilib/apps/tailwind.css";

An application-owned registry that does not import @zuilib/apps/core does not need the primitives stylesheet for its rendered view. Include it when using the core preset or the prebuilt builder UI.

Documentation and interactive examples: https://zuilib.com/apps