A2UI surface

Renders A2UI 1.0 surfaces with the installed ndigo-ui custom elements.

Primitive · agent · behaviour

Install

npx shadcn@latest add https://ndigo.dev/r/a2ui-surface.json

To use the shorter @ndigo/a2ui-surface form, configure the namespace in components.json.

Files

Source	Target	Type
registry/ui/a2ui-surface/nd-a2ui-surface.ts	@ui/nd-a2ui-surface/nd-a2ui-surface.ts	registry:ui
registry/ui/a2ui-surface/component-map.ts	@ui/nd-a2ui-surface/component-map.ts	registry:ui

Live example

See this component rendered live on the live examples page.

Dependencies

Registry: Ndigo element foundation. Packages: @a2ui/web_core@~0.15.0 (installed automatically).

Documentation

<nd-a2ui-surface> delegates protocol handling to @a2ui/web_core (MessageProcessor, SurfaceModel, DataModel, node resolution) and owns only the DOM projection: A2UI component names become the installed <nd-*> elements, props become attributes/properties, child references become children, and actions become event listeners.

Usage

<nd-a2ui-surface></nd-a2ui-surface>

const surface = document.querySelector('nd-a2ui-surface');
surface.messages = [
    { version: '1.0', createSurface: { surfaceId: 'orders', catalogId: 'ndigo-ui' } },
    {
        version: '1.0',
        updateComponents: {
            surfaceId: 'orders',
            components: [
                { id: 'root', component: 'Switch', checked: true },
                { id: 'label', component: 'Switch', label: 'Notifications' },
            ],
        },
    },
];

The allowlist

The installed component-map.ts maps A2UI names to nd-* tags. At render time the surface keeps only entries whose custom element is defined by the page, so the A2UI vocabulary is the installed set. Native-first styling items (button, input, card, …) have no custom element and are not A2UI components.

An unknown or uninstalled component does not render: the surface sets data-error and emits nd-a2ui-error with { message }.

Properties and events

Member	Type	Description
messages	A2UI 1.0 message payload	Renders (or re-renders) the surface

Event	Detail	Description
nd-a2ui-error	{ message }	A message failed validation or named an unknown component

The protocol version is pinned to A2UI 1.0 (SpecVersion.V1_0). The component map is generated by pnpm ui:a2ui-map:build from registry.json; never edit it by hand.