UI builder
@xngui/ui-builder@xngui/ui-builderHeadless composition engine — document model, validation, operations, and Angular rendering.
Overview
Package overview
The UI builder package is a headless engine. Showcase tools and custom editors consume it for palette, canvas, and inspector UIs.
The showcase tool at /tools/ui-builder is a thin host around @xngui/ui-builder/editor. Custom editors can reuse the same engine, validation, and export pipeline without adopting the showcase canvas.
Architecture
Model
@xngui/ui-builder/modelEngine
@xngui/ui-builder/engineRender
@xngui/ui-builder/renderEditor
@xngui/ui-builder/editorDocument model
Documents are versioned trees of typed nodes — elements, components, forms, conditionals, and repeaters — with layout, style, and binding metadata on every node.
example.tsimport type { XUiDocument, XUiNode } from '@xngui/ui-builder/model';import { createEmptyDocument } from '@xngui/ui-builder/model';const document: XUiDocument = createEmptyDocument('Home');Engine
XUiDocumentEngine applies validated operations with undo/redo, security limits, and structured diagnostics.
example.tsimport { XUiDocumentEngine } from '@xngui/ui-builder/engine';import { createNodeId, defaultNodeBase } from '@xngui/ui-builder/model';const engine = new XUiDocumentEngine();engine.apply({ id: createNodeId('op'), kind: 'insert', parentId: engine.document().root[0]?.id ?? null, index: 0, node: { ...defaultNodeBase('component'), type: 'component', componentId: 'button', inputs: { variant: 'primary' }, slotAssignments: {}, },});Rendering
Use the render entry point for live preview and code export. Responsive overrides export as @media blocks keyed by data-ui-node-id. Entry points:
@xngui/ui-builder/engineDocument store, operations facade, undo/redo@xngui/ui-builder/modelNode types and tree helpers@xngui/ui-builder/documentInsert, move, wrap, and update operations@xngui/ui-builder/validationMulti-level validation and a11y rules@xngui/ui-builder/renderAngular preview renderer and export helpers@xngui/ui-builder/formForm container and field node factories@xngui/ui-builder/bindingBinding context and resolution@xngui/ui-builder/actionAction registry and execution@xngui/ui-builder/templateTemplate library and linked instances@xngui/ui-builder/editorCanvas editor shell and inspector
Validation
Validation runs at element, component, binding, and document tiers. Diagnostics aggregate errors and warnings without mutating the document tree.
Bindings & actions
Bindings resolve literal, state, form-field, route, i18n, token, and expression sources. Node events dispatch registered actions through the action runtime.
Templates
Template libraries instantiate reusable node subtrees. Linked instances store overrides on the document and tag nodes with templateInstanceId metadata.
Security
Security limits cap tree depth, node count, and binding expression complexity. The engine rejects operations that would violate constraints.
Phase 1 smoke checklist
Manual checks before calling Phase 1 done — run on /tools/ui-builder:
- Drop a flex column layout, nest a grid, and reorder children with drag-and-drop.
- Insert a Card, add text nodes to Header and Content slots, and confirm slot zones update.
- Select a component, change an input in the Options tab, and verify the preview updates.
- Open Share → HTML and confirm slotted card markup includes projection attributes (xHeader, xContent).
- Open Share → TypeScript and confirm component imports match palette entries.
- Make a change, undo, and redo — canvas and inspector stay in sync.
- Reload the page and confirm the last session restores from local storage.
- Insert a Gallery, add gallery-item children, and confirm the stage updates when selecting thumbnails.
- Insert an Image, add nodes to Placeholder and Fallback slots, and verify projection in HTML export.