@agnosticui/a2ui-react 0.0.0-stage → 2.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,52 @@
1
- # Temporary Holding Version
1
+ # `@agnosticui/a2ui-react`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Spec-compliant **A2UI `v1.0`** React 18/19 renderer (`<AgA2uiSurface>`) and `useA2uiSurface()` hook backed by `@agnosticui/a2ui-lit`.
4
+
5
+ ## Quick Usage
6
+
7
+ ```tsx
8
+ import 'agnosticui-core/styles/tokens.css';
9
+ import 'agnosticui-core/styles/tokens-dark.css';
10
+ import {
11
+ AgA2uiSurface,
12
+ useA2uiSurface,
13
+ type A2uiWireMessage,
14
+ } from '@agnosticui/a2ui-react';
15
+
16
+ export function SupportPanel({ messages }: { messages: A2uiWireMessage[] }) {
17
+ const { surface, surfaceRef, processMessages } = useA2uiSurface({
18
+ validateOnAction: true,
19
+ onAction: (detail) => console.log('Validated A2UI action:', detail),
20
+ });
21
+
22
+ React.useEffect(() => {
23
+ processMessages(messages);
24
+ }, [messages, processMessages]);
25
+
26
+ return <AgA2uiSurface ref={surfaceRef} surface={surface} />;
27
+ }
28
+ ```
29
+
30
+ ## Local Development Workflow
31
+
32
+ `@agnosticui/a2ui-react` depends on compiled types and runtime re-exports from `@agnosticui/a2ui-lit` (`../lit/dist`). Always build `renderers/lit` first when testing or building from the **repository root**:
33
+
34
+ ```bash
35
+ # Build lit first, then test and build react
36
+ (cd v2/a2ui/renderers/lit && npm test && npm run build) && \
37
+ (cd v2/a2ui/renderers/react && npm test && npm run build)
38
+ ```
39
+
40
+ ### Monorepo Deduplication (`vitest.shared.mts`)
41
+
42
+ Vitest uses `v2/a2ui/vitest.shared.mts` (`sharedA2uiResolve(['react', 'react-dom'])`) so `lit` and `@lit-labs/signals` resolve to a single runtime instance across `file:../lit` during local test runs.
43
+
44
+ ### Updating `agnosticui-core` Local Tarball
45
+
46
+ If you modify components in `v2/lib`, rebuild and re-pack `v2/lib`, then reinstall in both `lit` and `react`:
47
+
48
+ ```bash
49
+ (cd v2/lib && npm run build && npm pack)
50
+ (cd v2/a2ui/renderers/lit && npm install && npm run build)
51
+ (cd v2/a2ui/renderers/react && npm install && npm test && npm run build)
52
+ ```
@@ -0,0 +1,53 @@
1
+ /**
2
+ * @file index.tsx
3
+ * @description React 18/19 renderer and hook bindings (@agnosticui/a2ui-react)
4
+ * for AgnosticUI's A2UI v1.0 catalog and Light-DOM <a2ui-surface>.
5
+ */
6
+ import * as React from 'react';
7
+ import { type EventName } from '@lit/react';
8
+ import { A2uiSurface, AGNOSTICUI_CATALOG_ID, AgnosticUICatalog, registerAgnosticUICatalog, runSurfaceValidation, createMockA2uiStream, type LitComponentApi, type SurfaceModel, type A2uiWireMessage } from '@agnosticui/a2ui-lit';
9
+ /**
10
+ * Idempotently registers all 25 AgnosticUI A2UI v1.0 custom elements.
11
+ * Safe to call multiple times under React 18/19 StrictMode.
12
+ */
13
+ export declare function ensureAgnosticUICatalog(): void;
14
+ export type A2uiActionEvent = CustomEvent<Record<string, unknown>>;
15
+ /**
16
+ * React wrapper around Light-DOM <a2ui-surface> generated via @lit/react.
17
+ * Renders any A2UI v1.0 SurfaceModel backed by AgnosticUICatalog.
18
+ */
19
+ declare const BaseA2uiSurface: import("@lit/react").ReactWebComponent<A2uiSurface, {
20
+ onA2uiAction: EventName<A2uiActionEvent>;
21
+ }>;
22
+ export interface AgA2uiSurfaceProps extends React.ComponentPropsWithoutRef<typeof BaseA2uiSurface> {
23
+ surface?: SurfaceModel<LitComponentApi>;
24
+ }
25
+ /**
26
+ * React 18/19 wrapper around Light-DOM <a2ui-surface>.
27
+ * Explicitly assigns the complex SurfaceModel JS property onto the custom element
28
+ * so React 19 never serializes it as an HTML attribute.
29
+ */
30
+ export declare const AgA2uiSurface: React.ForwardRefExoticComponent<AgA2uiSurfaceProps & React.RefAttributes<A2uiSurface>>;
31
+ export interface UseA2uiSurfaceOptions {
32
+ /** Surface ID matching createSurface.surfaceId (default: 'support_surface'). */
33
+ surfaceId?: string;
34
+ /** Optional callback invoked when an A2UI action fires on the surface. */
35
+ onAction?: (detail: Record<string, unknown>) => void;
36
+ /** Automatically run FACE reportValidity() before invoking onAction (default: true). */
37
+ validateOnAction?: boolean;
38
+ }
39
+ export interface UseA2uiSurfaceResult {
40
+ surface: SurfaceModel<LitComponentApi> | undefined;
41
+ surfaceRef: React.RefObject<A2uiSurface | null>;
42
+ processMessages: (messages: A2uiWireMessage[]) => void;
43
+ streamMessages: (messages: A2uiWireMessage[], delayMs?: number) => Promise<void>;
44
+ resetSurface: () => void;
45
+ validate: (report?: boolean) => boolean;
46
+ getDataModel: () => unknown;
47
+ }
48
+ /**
49
+ * Manages an A2UI v1.0 MessageProcessor bound to AgnosticUICatalog,
50
+ * exposing reactive SurfaceModel state, FACE validation, and action handling.
51
+ */
52
+ export declare function useA2uiSurface(options?: UseA2uiSurfaceOptions): UseA2uiSurfaceResult;
53
+ export { AGNOSTICUI_CATALOG_ID, AgnosticUICatalog, registerAgnosticUICatalog, runSurfaceValidation, createMockA2uiStream, type A2uiWireMessage, };
package/dist/index.js ADDED
@@ -0,0 +1,156 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ /**
3
+ * @file index.tsx
4
+ * @description React 18/19 renderer and hook bindings (@agnosticui/a2ui-react)
5
+ * for AgnosticUI's A2UI v1.0 catalog and Light-DOM <a2ui-surface>.
6
+ */
7
+ import * as React from 'react';
8
+ import { createComponent } from '@lit/react';
9
+ import { A2uiSurface, MessageProcessor, AGNOSTICUI_CATALOG_ID, AgnosticUICatalog, registerAgnosticUICatalog, runSurfaceValidation, createMockA2uiStream, } from '@agnosticui/a2ui-lit';
10
+ let catalogRegistered = false;
11
+ /**
12
+ * Idempotently registers all 25 AgnosticUI A2UI v1.0 custom elements.
13
+ * Safe to call multiple times under React 18/19 StrictMode.
14
+ */
15
+ export function ensureAgnosticUICatalog() {
16
+ if (catalogRegistered)
17
+ return;
18
+ registerAgnosticUICatalog();
19
+ catalogRegistered = true;
20
+ }
21
+ /**
22
+ * React wrapper around Light-DOM <a2ui-surface> generated via @lit/react.
23
+ * Renders any A2UI v1.0 SurfaceModel backed by AgnosticUICatalog.
24
+ */
25
+ const BaseA2uiSurface = createComponent({
26
+ tagName: 'a2ui-surface',
27
+ elementClass: A2uiSurface,
28
+ react: React,
29
+ events: {
30
+ onA2uiAction: 'a2uiaction',
31
+ },
32
+ });
33
+ /**
34
+ * React 18/19 wrapper around Light-DOM <a2ui-surface>.
35
+ * Explicitly assigns the complex SurfaceModel JS property onto the custom element
36
+ * so React 19 never serializes it as an HTML attribute.
37
+ */
38
+ export const AgA2uiSurface = React.forwardRef(function AgA2uiSurface({ surface, ...rest }, forwardedRef) {
39
+ const innerRef = React.useRef(null);
40
+ React.useLayoutEffect(() => {
41
+ if (innerRef.current && innerRef.current.surface !== surface) {
42
+ innerRef.current.surface = surface;
43
+ }
44
+ }, [surface]);
45
+ const setRefs = React.useCallback((node) => {
46
+ innerRef.current = node;
47
+ if (node && surface !== undefined) {
48
+ node.surface = surface;
49
+ }
50
+ if (typeof forwardedRef === 'function') {
51
+ forwardedRef(node);
52
+ }
53
+ else if (forwardedRef) {
54
+ forwardedRef.current = node;
55
+ }
56
+ }, [forwardedRef, surface]);
57
+ return _jsx(BaseA2uiSurface, { ref: setRefs, ...rest });
58
+ });
59
+ /**
60
+ * Manages an A2UI v1.0 MessageProcessor bound to AgnosticUICatalog,
61
+ * exposing reactive SurfaceModel state, FACE validation, and action handling.
62
+ */
63
+ export function useA2uiSurface(options = {}) {
64
+ const { surfaceId = 'support_surface', onAction, validateOnAction = true, } = options;
65
+ ensureAgnosticUICatalog();
66
+ const [processorEpoch, setProcessorEpoch] = React.useState(0);
67
+ const processorRef = React.useRef(null);
68
+ if (!processorRef.current) {
69
+ processorRef.current = new MessageProcessor([
70
+ AgnosticUICatalog,
71
+ ]);
72
+ }
73
+ const surfaceRef = React.useRef(null);
74
+ const [, forceRender] = React.useReducer((c) => c + 1, 0);
75
+ const onActionRef = React.useRef(onAction);
76
+ onActionRef.current = onAction;
77
+ const resetSurface = React.useCallback(() => {
78
+ processorRef.current = new MessageProcessor([
79
+ AgnosticUICatalog,
80
+ ]);
81
+ setProcessorEpoch((e) => e + 1);
82
+ forceRender();
83
+ }, []);
84
+ const processMessages = React.useCallback((messages) => {
85
+ const processor = processorRef.current;
86
+ if (!processor)
87
+ return;
88
+ for (const msg of messages) {
89
+ const envelope = msg;
90
+ const targetId = envelope.createSurface?.surfaceId;
91
+ if (targetId && processor.model.getSurface(targetId)) {
92
+ processor.processMessages([
93
+ { version: '1.0', deleteSurface: { surfaceId: targetId } },
94
+ ]);
95
+ }
96
+ processor.processMessages([msg]);
97
+ }
98
+ if (surfaceRef.current) {
99
+ surfaceRef.current.requestUpdate();
100
+ }
101
+ forceRender();
102
+ }, []);
103
+ const streamMessages = React.useCallback(async (messages, delayMs = 0) => {
104
+ for await (const msg of createMockA2uiStream(messages, delayMs)) {
105
+ processMessages([msg]);
106
+ }
107
+ }, [processMessages]);
108
+ const validate = React.useCallback((report = true) => {
109
+ if (!surfaceRef.current)
110
+ return true;
111
+ return runSurfaceValidation(surfaceRef.current, report);
112
+ }, []);
113
+ const getDataModel = React.useCallback(() => {
114
+ const current = processorRef.current?.model.getSurface(surfaceId);
115
+ if (!current)
116
+ return {};
117
+ return current.dataModel.get('') ?? current.dataModel.get('/') ?? {};
118
+ }, [surfaceId]);
119
+ const surface = processorRef.current.model.getSurface(surfaceId);
120
+ React.useEffect(() => {
121
+ const processor = processorRef.current;
122
+ if (!processor)
123
+ return;
124
+ const handleResolvedAction = (detail) => {
125
+ const el = surfaceRef.current;
126
+ if (el && validateOnAction && !runSurfaceValidation(el, true)) {
127
+ return;
128
+ }
129
+ onActionRef.current?.(detail);
130
+ };
131
+ const sub = processor.model.onAction.subscribe((action) => {
132
+ const detail = action;
133
+ handleResolvedAction(detail);
134
+ });
135
+ const el = surfaceRef.current;
136
+ const domListener = (evt) => {
137
+ const detail = evt.detail ?? {};
138
+ handleResolvedAction(detail);
139
+ };
140
+ el?.addEventListener('a2uiaction', domListener);
141
+ return () => {
142
+ sub.unsubscribe();
143
+ el?.removeEventListener('a2uiaction', domListener);
144
+ };
145
+ }, [processorEpoch, validateOnAction, surface]);
146
+ return {
147
+ surface,
148
+ surfaceRef,
149
+ processMessages,
150
+ streamMessages,
151
+ resetSurface,
152
+ validate,
153
+ getDataModel,
154
+ };
155
+ }
156
+ export { AGNOSTICUI_CATALOG_ID, AgnosticUICatalog, registerAgnosticUICatalog, runSurfaceValidation, createMockA2uiStream, };
package/package.json CHANGED
@@ -1,6 +1,67 @@
1
1
  {
2
2
  "name": "@agnosticui/a2ui-react",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "2.0.0-alpha.1",
4
+ "description": "A2UI v1.0 React renderer and surface bindings for AgnosticUI",
5
+ "author": "AgnosticUI",
6
+ "license": "Apache-2.0",
7
+ "homepage": "https://agnosticui.com",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "https://github.com",
11
+ "directory": "v2/a2ui/renderers/react"
12
+ },
13
+ "keywords": [
14
+ "a2ui",
15
+ "a2ui-v1",
16
+ "agnosticui",
17
+ "generative-ui",
18
+ "react",
19
+ "web-components"
20
+ ],
21
+ "type": "module",
22
+ "main": "dist/index.js",
23
+ "types": "dist/index.d.ts",
24
+ "files": [
25
+ "dist",
26
+ "README.md"
27
+ ],
28
+ "exports": {
29
+ ".": {
30
+ "types": "./dist/index.d.ts",
31
+ "import": "./dist/index.js"
32
+ }
33
+ },
34
+ "scripts": {
35
+ "test": "vitest run",
36
+ "typecheck": "tsc --noEmit",
37
+ "build": "tsc"
38
+ },
39
+ "peerDependencies": {
40
+ "@a2ui/lit": "^0.15.0",
41
+ "@a2ui/web_core": "^0.15.0",
42
+ "@agnosticui/a2ui-lit": ">=2.0.0-alpha.1",
43
+ "agnosticui-core": ">=2.0.0-alpha.31",
44
+ "lit": "^3.0.0",
45
+ "react": ">=18",
46
+ "react-dom": ">=18"
47
+ },
48
+ "dependencies": {
49
+ "@lit/react": "^1.0.8"
50
+ },
51
+ "devDependencies": {
52
+ "@a2ui/lit": "^0.15.0",
53
+ "@a2ui/web_core": "^0.15.0",
54
+ "@agnosticui/a2ui-lit": "^2.0.0-alpha.1",
55
+ "@testing-library/react": "^16.3.0",
56
+ "@types/node": "^26.6.6",
57
+ "@types/react": "^19.1.10",
58
+ "@types/react-dom": "^19.1.9",
59
+ "agnosticui-core": "^2.0.0-alpha.31",
60
+ "jsdom": "^26.1.0",
61
+ "lit": "^3.3.3",
62
+ "react": "^19.1.1",
63
+ "react-dom": "^19.1.1",
64
+ "typescript": "^7.0.2",
65
+ "vitest": "^5.1.0"
66
+ }
67
+ }