glchat-a2ui-react-renderer 0.2.7 → 0.3.0

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.
Files changed (110) hide show
  1. package/README.md +223 -178
  2. package/dist/index.d.ts +10 -4
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +13 -5
  5. package/dist/src/Provider.d.ts +21 -14
  6. package/dist/src/Provider.d.ts.map +1 -1
  7. package/dist/src/Provider.js +56 -42
  8. package/dist/src/SurfaceRenderer.d.ts +17 -0
  9. package/dist/src/SurfaceRenderer.d.ts.map +1 -0
  10. package/dist/src/SurfaceRenderer.js +28 -0
  11. package/dist/src/components/a2ui/Button/Button.d.ts +313 -3
  12. package/dist/src/components/a2ui/Button/Button.d.ts.map +1 -1
  13. package/dist/src/components/a2ui/Button/Button.js +29 -14
  14. package/dist/src/components/a2ui/{MultipleChoice → ChoicePicker}/CheckboxList.d.ts +1 -2
  15. package/dist/src/components/a2ui/ChoicePicker/CheckboxList.d.ts.map +1 -0
  16. package/dist/src/components/a2ui/{MultipleChoice → ChoicePicker}/CheckboxList.js +2 -13
  17. package/dist/src/components/a2ui/ChoicePicker/ChoicePicker.d.ts +9 -0
  18. package/dist/src/components/a2ui/ChoicePicker/ChoicePicker.d.ts.map +1 -0
  19. package/dist/src/components/a2ui/ChoicePicker/ChoicePicker.js +54 -0
  20. package/dist/src/components/a2ui/ChoicePicker/theme.d.ts +10 -0
  21. package/dist/src/components/a2ui/ChoicePicker/theme.d.ts.map +1 -0
  22. package/dist/src/components/a2ui/{MultipleChoice → ChoicePicker}/theme.js +12 -9
  23. package/dist/src/components/a2ui/TagInput/TagInput.d.ts +289 -3
  24. package/dist/src/components/a2ui/TagInput/TagInput.d.ts.map +1 -1
  25. package/dist/src/components/a2ui/TagInput/TagInput.js +44 -54
  26. package/dist/src/components/a2ui/TagInput/theme.d.ts +0 -9
  27. package/dist/src/components/a2ui/TagInput/theme.d.ts.map +1 -1
  28. package/dist/src/components/a2ui/TagInput/theme.js +1 -9
  29. package/dist/src/components/a2ui/Timeout/Timeout.d.ts +154 -3
  30. package/dist/src/components/a2ui/Timeout/Timeout.d.ts.map +1 -1
  31. package/dist/src/components/a2ui/Timeout/Timeout.js +40 -25
  32. package/dist/src/components/a2ui/common.d.ts +87 -0
  33. package/dist/src/components/a2ui/common.d.ts.map +1 -0
  34. package/dist/src/components/a2ui/common.js +23 -0
  35. package/dist/src/components/ui/Button/theme.d.ts +1 -1
  36. package/dist/src/components/ui/Button/theme.d.ts.map +1 -1
  37. package/dist/src/components/ui/Button/theme.js +11 -0
  38. package/dist/src/components/ui/MultiSelect/MultiSelect.d.ts +1 -1
  39. package/dist/src/components/ui/MultiSelect/MultiSelect.d.ts.map +1 -1
  40. package/dist/src/components/ui/Select/theme.d.ts.map +1 -1
  41. package/dist/src/components/ui/Select/theme.js +0 -1
  42. package/dist/src/utils/catalog.d.ts +16 -4
  43. package/dist/src/utils/catalog.d.ts.map +1 -1
  44. package/dist/src/utils/catalog.js +32 -23
  45. package/dist/src/utils/useSurfaces.d.ts +9 -0
  46. package/dist/src/utils/useSurfaces.d.ts.map +1 -0
  47. package/dist/src/utils/useSurfaces.js +28 -0
  48. package/json/README.md +36 -49
  49. package/json/a2ui-sample-messages.json +170 -315
  50. package/json/glchat_standard_catalog_definition.json +1236 -610
  51. package/package.json +11 -5
  52. package/styles/globals.css +196 -120
  53. package/dist/src/AllSurfacesRenderer.d.ts +0 -14
  54. package/dist/src/AllSurfacesRenderer.d.ts.map +0 -1
  55. package/dist/src/AllSurfacesRenderer.js +0 -18
  56. package/dist/src/SingleSurfaceRenderer.d.ts +0 -15
  57. package/dist/src/SingleSurfaceRenderer.d.ts.map +0 -1
  58. package/dist/src/SingleSurfaceRenderer.js +0 -9
  59. package/dist/src/components/a2ui/Button/theme.d.ts +0 -5
  60. package/dist/src/components/a2ui/Button/theme.d.ts.map +0 -1
  61. package/dist/src/components/a2ui/Button/theme.js +0 -5
  62. package/dist/src/components/a2ui/ButtonAsLink/ButtonAsLink.d.ts +0 -4
  63. package/dist/src/components/a2ui/ButtonAsLink/ButtonAsLink.d.ts.map +0 -1
  64. package/dist/src/components/a2ui/ButtonAsLink/ButtonAsLink.js +0 -42
  65. package/dist/src/components/a2ui/ButtonAsLink/theme.d.ts +0 -8
  66. package/dist/src/components/a2ui/ButtonAsLink/theme.d.ts.map +0 -1
  67. package/dist/src/components/a2ui/ButtonAsLink/theme.js +0 -8
  68. package/dist/src/components/a2ui/Card/theme.d.ts +0 -4
  69. package/dist/src/components/a2ui/Card/theme.d.ts.map +0 -1
  70. package/dist/src/components/a2ui/Card/theme.js +0 -15
  71. package/dist/src/components/a2ui/CheckBox/theme.d.ts +0 -4
  72. package/dist/src/components/a2ui/CheckBox/theme.d.ts.map +0 -1
  73. package/dist/src/components/a2ui/CheckBox/theme.js +0 -11
  74. package/dist/src/components/a2ui/DateTimeInput/theme.d.ts +0 -8
  75. package/dist/src/components/a2ui/DateTimeInput/theme.d.ts.map +0 -1
  76. package/dist/src/components/a2ui/DateTimeInput/theme.js +0 -11
  77. package/dist/src/components/a2ui/DestructiveButton/DestructiveButton.d.ts +0 -4
  78. package/dist/src/components/a2ui/DestructiveButton/DestructiveButton.d.ts.map +0 -1
  79. package/dist/src/components/a2ui/DestructiveButton/DestructiveButton.js +0 -22
  80. package/dist/src/components/a2ui/DestructiveButton/theme.d.ts +0 -8
  81. package/dist/src/components/a2ui/DestructiveButton/theme.d.ts.map +0 -1
  82. package/dist/src/components/a2ui/DestructiveButton/theme.js +0 -8
  83. package/dist/src/components/a2ui/MultipleChoice/CheckboxList.d.ts.map +0 -1
  84. package/dist/src/components/a2ui/MultipleChoice/MultipleChoice.d.ts +0 -4
  85. package/dist/src/components/a2ui/MultipleChoice/MultipleChoice.d.ts.map +0 -1
  86. package/dist/src/components/a2ui/MultipleChoice/MultipleChoice.js +0 -72
  87. package/dist/src/components/a2ui/MultipleChoice/theme.d.ts +0 -13
  88. package/dist/src/components/a2ui/MultipleChoice/theme.d.ts.map +0 -1
  89. package/dist/src/components/a2ui/TextField/theme.d.ts +0 -4
  90. package/dist/src/components/a2ui/TextField/theme.d.ts.map +0 -1
  91. package/dist/src/components/a2ui/TextField/theme.js +0 -9
  92. package/dist/src/components/a2ui/Timeout/theme.d.ts +0 -8
  93. package/dist/src/components/a2ui/Timeout/theme.d.ts.map +0 -1
  94. package/dist/src/components/a2ui/Timeout/theme.js +0 -12
  95. package/dist/src/components/a2ui/types.d.ts +0 -12
  96. package/dist/src/components/a2ui/types.d.ts.map +0 -1
  97. package/dist/src/components/a2ui/types.js +0 -1
  98. package/dist/src/components/ui/Button/ButtonAsLink.d.ts +0 -15
  99. package/dist/src/components/ui/Button/ButtonAsLink.d.ts.map +0 -1
  100. package/dist/src/components/ui/Button/ButtonAsLink.js +0 -17
  101. package/dist/src/components/ui/TextField/theme.d.ts +0 -4
  102. package/dist/src/components/ui/TextField/theme.d.ts.map +0 -1
  103. package/dist/src/components/ui/TextField/theme.js +0 -22
  104. package/dist/src/utils/href.d.ts +0 -11
  105. package/dist/src/utils/href.d.ts.map +0 -1
  106. package/dist/src/utils/href.js +0 -34
  107. package/dist/src/utils/theme.d.ts +0 -15
  108. package/dist/src/utils/theme.d.ts.map +0 -1
  109. package/dist/src/utils/theme.js +0 -93
  110. package/json/glchat_server_to_client_with_catalog.json +0 -1000
package/README.md CHANGED
@@ -1,83 +1,59 @@
1
1
  # glchat-a2ui-react-renderer
2
2
 
3
- [`@a2ui/react`](https://www.npmjs.com/package/@a2ui/react) with GLChat-specific styling and component overrides.
3
+ GLChat styling and component extensions for [`@a2ui/react`](https://www.npmjs.com/package/@a2ui/react) (**A2UI v0.9**). This package wraps the standard A2UI renderer pipeline with a registered catalog, design tokens, and GLChat-specific UI components.
4
4
 
5
- This package provides:
5
+ ## Overview
6
6
 
7
- * **`Provider`** – `A2UIProvider` wrapper that automatically registers GLChat's custom components.
8
- * **`SingleSurfaceRenderer`** – thin wrapper around `A2UIRenderer` for a single `surfaceId`. Must be used inside `Provider`.
9
- * **`AllSurfacesRenderer`** – convenience wrapper that renders every active `surfaceId`. Must be used inside `Provider`.
10
- * **Tailwind theming** – `styles/globals.css`, `styles/theme-v4.css`, and `tailwind-config.cjs` for default tokens and utilities.
11
-
12
- This library provides **GLChat-specific components and styling** while remaining fully compatible with the upstream A2UI renderer.
13
-
14
- ---
15
-
16
- # Prerequisites
7
+ | Export | Description |
8
+ |---|---|
9
+ | `Provider` | Owns the `MessageProcessor`, surface group state, and GLChat catalog |
10
+ | `SurfaceRenderer` | Renders one or all active surfaces (requires `Provider`) |
11
+ | Design tokens | `styles/globals.css`, `styles/theme-v4.css`, `tailwind-config.cjs` |
17
12
 
18
- * **React 18+**
19
- * **Tailwind CSS v3 or v4**
20
- * **Material Symbols Outlined font** (required for `Icon` components — see [Icons](#icons))
13
+ ## Requirements
21
14
 
22
- ---
15
+ - React 18+
16
+ - Tailwind CSS v3 or v4
17
+ - [Material Symbols Outlined](https://fonts.google.com/icons) — required only for string-based `Icon` components (see [Icons](#icons))
23
18
 
24
- # Install
19
+ ## Installation
25
20
 
26
21
  ```bash
27
22
  npm install glchat-a2ui-react-renderer
28
23
  ```
29
24
 
30
- ---
31
-
32
- # Quick Start
33
-
34
- Use the GLChat-aware wrappers:
25
+ ## Quick start
35
26
 
36
27
  ```tsx
37
- import {
38
- Provider,
39
- SingleSurfaceRenderer,
40
- AllSurfacesRenderer,
41
- } from 'glchat-a2ui-react-renderer';
28
+ import { Provider, SurfaceRenderer } from 'glchat-a2ui-react-renderer';
42
29
  import type { A2UIMessage, ActionPayload } from 'glchat-a2ui-react-renderer';
43
30
 
44
31
  function App() {
45
- const messages: A2UIMessage[] = [
46
- // A2UI messages from your backend
47
- ];
32
+ const messages: A2UIMessage[] = [/* A2UI v0.9 messages from the backend */];
48
33
 
49
34
  const handleAction = (action: ActionPayload) => {
50
- console.log('Action received:', action);
35
+ // { name, surfaceId, sourceComponentId, timestamp, context }
36
+ console.log('Action:', action);
51
37
  };
52
38
 
53
39
  return (
54
40
  <Provider messages={messages} onAction={handleAction}>
55
- <AllSurfacesRenderer />
41
+ <SurfaceRenderer />
56
42
  </Provider>
57
43
  );
58
44
  }
59
-
60
- ```
61
-
62
- To render a single surface explicitly:
63
-
64
- ```tsx
65
- <Provider messages={messages} onAction={handleAction}>
66
- <SingleSurfaceRenderer surfaceId="main" />
67
- </Provider>
68
45
  ```
69
46
 
70
- > **Note:** `onAction` is configured on `Provider`. Both `SingleSurfaceRenderer` and `AllSurfacesRenderer` must be rendered inside a `Provider`.
71
-
72
- ---
73
-
74
- # Icons
47
+ **Configuration notes:**
75
48
 
76
- The upstream A2UI `Icon` component renders [Material Symbols Outlined](https://fonts.google.com/icons) via the `.g-icon` CSS class. This package does **not** bundle the font — you must load it in your app.
49
+ - `SurfaceRenderer` accepts an optional `surfaceId` to render a single surface.
50
+ - The `fallback` prop controls the loading UI (default: `"Waiting for agent..."`).
51
+ - `Provider` configures markdown rendering for `Text` via `@a2ui/markdown-it`.
52
+ - `onAction` receives v0.9 `A2uiClientAction` payloads from interactive components.
77
53
 
78
- ## Load the font
54
+ ## Icons
79
55
 
80
- Add one of the following to your app shell (e.g. Next.js `layout.tsx`, `index.html`):
56
+ The upstream `Icon` component renders [Material Symbols Outlined](https://fonts.google.com/icons) when `name` is a string. This package does not bundle the font; consumers must load it in the application shell:
81
57
 
82
58
  ```html
83
59
  <link
@@ -86,54 +62,142 @@ Add one of the following to your app shell (e.g. Next.js `layout.tsx`, `index.ht
86
62
  />
87
63
  ```
88
64
 
89
- Or import it in your global CSS (before or alongside the GLChat styles):
65
+ Alternatively, import it in global CSS before other stylesheets:
90
66
 
91
67
  ```css
92
68
  @import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&display=swap');
93
69
  ```
94
70
 
95
- Use **`display=swap`** so the browser repaints icons once the font finishes loading.
71
+ Icons specified with an SVG path object (`{ "svgPath": "..." }`) render as inline SVG and do not require the font.
96
72
 
97
- ---
73
+ ## Typography
74
+
75
+ The default typeface is Inter, exposed through the `--font-sans` token. This package does not `@import` Google Fonts from `globals.css` to remain compatible with Next.js stylesheet merging.
76
+
77
+ Consumers may use an existing application font by overriding the token on `.a2ui-surface`:
98
78
 
99
- # Custom Components (optional)
79
+ ```css
80
+ .a2ui-surface {
81
+ --font-sans: var(--your-app-font);
82
+ }
83
+ ```
100
84
 
101
- `Provider` automatically registers GLChat's standard component overrides — no extra setup needed:
85
+ To adopt Inter explicitly:
102
86
 
103
- | Component | Description |
87
+ - **Next.js:** configure `next/font/google` with `variable: '--font-sans'` on the root element.
88
+ - **Plain CSS:** `@import` Inter before `globals.css`.
89
+
90
+ ## GLChat catalog
91
+
92
+ `Provider` registers the extended catalog automatically. All other components use the upstream A2UI v0.9 basic catalog.
93
+
94
+ | Component | Role |
104
95
  |---|---|
105
- | `Button` | GLChat-styled button with `primary` / `outline` variants |
106
- | `ButtonAsLink` | Button-styled anchor link with `href` and optional `target` |
107
- | `DestructiveButton` | Destructive-styled button |
108
- | `MultipleChoice` | Enhanced multiple-choice field (checkbox list / select) |
109
- | `TagInput` | Tag input field with add/remove support |
110
- | `Timeout` | Countdown to a target UTC time |
96
+ | `Button` | Override — GLChat styling; adds `destructive` variant |
97
+ | `ChoicePicker` | Override — select, multi-select, and checkbox list |
98
+ | `TagInput` | Extension |
99
+ | `Timeout` | Extension |
100
+
101
+ See [Custom components](#custom-components) to register additional components on top of this catalog. Component schemas are documented in [`json/README.md`](json/README.md).
111
102
 
112
- `Card`, `CheckBox`, `TextField`, and other upstream components use **theme-only** overrides (no custom React wrapper).
103
+ ## Custom components (Optional)
113
104
 
114
- To add your own node types on top, register them on the singleton `ComponentRegistry` before rendering:
105
+ Custom components are defined with a Zod schema and a React renderer, then registered in a `Catalog` passed to `Provider`.
106
+
107
+ **1. Define the component API**
115
108
 
116
109
  ```tsx
117
- import { ComponentRegistry, Types, type A2UIComponentProps } from 'glchat-a2ui-react-renderer';
110
+ import { z } from 'zod';
111
+ import {
112
+ createComponentImplementation,
113
+ DynamicStringSchema,
114
+ AccessibilityAttributesSchema,
115
+ } from 'glchat-a2ui-react-renderer';
118
116
 
119
- function MyNodeComponent({ node }: Readonly<A2UIComponentProps<Types.CustomNode>>) {
120
- const label = (node.properties as any).label as string | undefined;
121
- return <div>{label}</div>;
122
- }
117
+ export const BadgeApi = {
118
+ name: 'Badge',
119
+ schema: z
120
+ .object({
121
+ accessibility: AccessibilityAttributesSchema.optional(),
122
+ weight: z.number().optional(),
123
+ label: DynamicStringSchema.describe('Text shown in the badge.'),
124
+ })
125
+ .strict()
126
+ .describe('A simple label badge.'),
127
+ };
128
+ ```
123
129
 
124
- // GLChat's standard components are already included by Provider.
125
- // Just register your own additional node types here.
126
- const registry = ComponentRegistry.getInstance();
127
- registry.register('MyNodeType', { component: MyNodeComponent as any });
130
+ **2. Implement the renderer**
131
+
132
+ `createComponentImplementation` binds resolved props from the data model (e.g. `props.label`, `props.action`, `props.value`, `props.setValue` for interactive fields):
133
+
134
+ ```tsx
135
+ export const BadgeComponent = createComponentImplementation(BadgeApi, ({ props }) => (
136
+ <span className="inline-flex rounded-md bg-muted px-2 py-0.5 text-sm">{props.label}</span>
137
+ ));
128
138
  ```
129
139
 
130
- ---
140
+ For child components, use `buildChild`:
141
+
142
+ ```tsx
143
+ createComponentImplementation(MyApi, ({ props, buildChild }) => (
144
+ <div>{props.child ? buildChild(props.child) : null}</div>
145
+ );
146
+ ```
147
+
148
+ **3. Build a catalog**
149
+
150
+ Start from `createGlchatCatalog()` and append the new component. Reuse `GLCHAT_CATALOG_ID` so existing `createSurface` messages remain valid:
131
151
 
132
- # Tailwind Setup
152
+ ```tsx
153
+ import {
154
+ Catalog,
155
+ createGlchatCatalog,
156
+ GLCHAT_CATALOG_ID,
157
+ } from 'glchat-a2ui-react-renderer';
133
158
 
134
- ## Tailwind v4
159
+ const glchat = createGlchatCatalog();
160
+ const catalog = new Catalog(
161
+ GLCHAT_CATALOG_ID,
162
+ [...glchat.components.values(), BadgeComponent],
163
+ [...glchat.functions.values()],
164
+ );
165
+ ```
135
166
 
136
- Add the following to your main CSS file (`globals.css`):
167
+ **4. Pass the catalog to `Provider`**
168
+
169
+ ```tsx
170
+ <Provider messages={messages} catalog={catalog} onAction={handleAction}>
171
+ <SurfaceRenderer />
172
+ </Provider>
173
+ ```
174
+
175
+ ## Custom layout
176
+
177
+ For explicit control over surface layout, use `useSurfaceGroup`, `useSurfaces`, and `A2uiSurface` instead of `SurfaceRenderer`:
178
+
179
+ ```tsx
180
+ import { useSurfaceGroup, useSurfaces, A2uiSurface } from 'glchat-a2ui-react-renderer';
181
+
182
+ function CustomLayout() {
183
+ const model = useSurfaceGroup();
184
+ const surfaces = useSurfaces(model);
185
+
186
+ if (surfaces.length === 0) return <Spinner />;
187
+
188
+ return surfaces.map((surface) => (
189
+ <div key={surface.id} className="a2ui-surface">
190
+ <A2uiSurface surface={surface} />
191
+ </div>
192
+ ));
193
+ }
194
+ ```
195
+
196
+ ## Tailwind setup
197
+
198
+ ### Tailwind v4
199
+
200
+ Add the following to the application CSS entry point:
137
201
 
138
202
  ```css
139
203
  @import "tailwindcss";
@@ -167,24 +231,13 @@ module.exports = {
167
231
  };
168
232
  ```
169
233
 
170
- Import the tokens in your main CSS:
171
-
172
- ```css
173
- @import "glchat-a2ui-react-renderer/styles/globals.css";
174
-
175
- @tailwind base;
176
- @tailwind components;
177
- @tailwind utilities;
178
- ```
179
-
180
- ---
234
+ Import `styles/globals.css` before the `@tailwind` directives.
181
235
 
182
- # Customizing Colors (optional)
236
+ ## Theming
183
237
 
184
- The package tokens are declared as plain (unlayered) `:root` rules. To override them, place a plain `:root` block **after** the `globals.css` import in your CSS file. Source order determines the winner when both are unlayered, so your override must come later.
238
+ Components are styled with CSS custom properties. Override `:root` tokens in application CSS **after** importing `globals.css`:
185
239
 
186
240
  ```css
187
- /* ✅ Works in both Tailwind v3 and v4 */
188
241
  :root {
189
242
  --primary: 220 90% 45%;
190
243
  --background: 0 0% 99%;
@@ -195,105 +248,97 @@ The package tokens are declared as plain (unlayered) `:root` rules. To override
195
248
  }
196
249
  ```
197
250
 
198
- Button variants use design tokens by default:
199
-
200
- - **`Button`** (`primary: true`): `--primary`, `--primary-foreground`, `--ring`
201
- - **`Button`** (default / outline): `--background`, `--background-alternate`, `--foreground`, `--border`, `--ring`
202
- - **`DestructiveButton`**: `--destructive`, `--destructive-foreground`, `--ring`
203
- - **`ButtonAsLink`**: same outline styling as `Button`, rendered as an anchor
204
-
205
- Override per-component inline styles via the `theme` prop on `Provider`:
206
-
207
- ```tsx
208
- <Provider
209
- theme={{
210
- additionalStyles: {
211
- Button: { padding: '12px 20px' },
212
- DestructiveButton: { borderRadius: '8px' },
213
- },
214
- }}
215
- >
216
- <AllSurfacesRenderer />
217
- </Provider>
218
- ```
219
-
220
- UI primitives apply base and variant styles internally; `additionalStyles` values are theme **deltas** layered on top.
221
-
222
- You may also extend the theme via:
223
-
224
- * `tailwind.config.js` (v3)
225
- * `@theme` (v4)
226
-
227
- ---
251
+ ## JSON schemas
228
252
 
229
- # JSON Catalog & Schemas
253
+ Published for agent catalog registration and reference:
230
254
 
231
- GLChat extends the official A2UI v0.8 catalog with additional components and publishes JSON schema files for validation and LLM structured output.
232
-
233
- | File | Export path |
255
+ | File | Description |
234
256
  |---|---|
235
- | GLChat catalog definition | `glchat-a2ui-react-renderer/json/glchat_standard_catalog_definition.json` |
236
- | Full server-to-client schema | `glchat-a2ui-react-renderer/json/glchat_server_to_client_with_catalog.json` |
237
- | Sample messages (all components) | `glchat-a2ui-react-renderer/json/a2ui-sample-messages.json` |
238
-
239
- ```ts
240
- import catalog from 'glchat-a2ui-react-renderer/json/glchat_standard_catalog_definition.json';
241
- ```
242
-
243
- See [`json/README.md`](json/README.md) for a full component reference.
244
-
245
- ---
257
+ | `json/glchat_standard_catalog_definition.json` | GLChat catalog definition |
258
+ | `json/a2ui-sample-messages.json` | Sample message sequence |
246
259
 
247
- # Exports
260
+ ## Public API
248
261
 
249
- ## Components
262
+ ### Components and hooks
250
263
 
251
- * `Provider`
252
- * `SingleSurfaceRenderer`
253
- * `AllSurfacesRenderer`
254
-
255
- ## Types
256
-
257
- * `ProviderProps`
258
- * `SingleSurfaceRendererProps`
259
- * `AllSurfacesRendererProps`
260
- * `A2UIMessage`
261
- * `ActionPayload`
262
- * `ActionHandler`
263
-
264
- ## Re-exports from `@a2ui/react`
265
-
266
- * `Types`
267
- * `ComponentRegistry`
268
- * `ComponentNode`
269
- * `useA2UIComponent`
270
- * `useA2UI`
271
- * `classMapToString`
272
- * `stylesToObject`
273
- * `A2UIComponentProps`
274
- * `Theme`
275
- * `AnyComponentNode`
276
- * `StringValue`
277
- * `NumberValue`
278
- * `BooleanValue`
279
-
280
- ## Styles
264
+ | Export | Description |
265
+ |---|---|
266
+ | `Provider` | Message processor, surface group, and GLChat catalog |
267
+ | `SurfaceRenderer` | Renders one or all surfaces |
268
+ | `useSurfaceGroup` | Subscribes to the surface group model from `Provider` |
269
+ | `useSurfaces` | Returns active surfaces from a surface group model |
281
270
 
282
- * `styles/globals.css`
283
- * `styles/theme-v4.css`
284
- * `tailwind-config.cjs`
271
+ ### Types
285
272
 
286
- ## JSON
273
+ | Export | Description |
274
+ |---|---|
275
+ | `ProviderProps` | Props for `Provider` |
276
+ | `SurfaceRendererProps` | Props for `SurfaceRenderer` |
277
+ | `A2UIMessage` | Server-to-client message type |
278
+ | `ActionPayload` | Normalized action payload passed to `onAction` |
279
+ | `ActionHandler` | `(action: ActionPayload) => void` |
280
+ | `MessageErrorHandler` | `(error: Error) => void` |
281
+ | `ReactComponentImplementation` | Catalog component implementation type |
282
+ | `ReactA2uiComponentProps` | Props passed to custom component renderers |
283
+ | `ComponentApi` | Zod schema definition for a catalog component |
284
+ | `A2uiMessage` | Upstream message type (`@a2ui/web_core`) |
285
+ | `A2uiClientAction` | Upstream client action type (`@a2ui/web_core`) |
286
+
287
+ ### Catalog (GLChat)
288
+
289
+ | Export | Description |
290
+ |---|---|
291
+ | `createGlchatCatalog` | Builds the GLChat extended v0.9 catalog |
292
+ | `GLCHAT_CATALOG_ID` | Catalog URI for `createSurface` messages |
293
+ | `GlchatButtonComponent` | GLChat `Button` implementation |
294
+ | `GlchatButtonApi` | Extended `Button` schema (includes `destructive` variant) |
295
+ | `GlchatChoicePickerComponent` | GLChat `ChoicePicker` implementation |
296
+ | `GlchatTagInputComponent` | `TagInput` implementation |
297
+ | `TagInputApi` | `TagInput` schema |
298
+ | `GlchatTimeoutComponent` | `Timeout` implementation |
299
+ | `TimeoutApi` | `Timeout` schema |
300
+
301
+ ### Re-exports (`@a2ui/react` v0.9)
302
+
303
+ | Export | Description |
304
+ |---|---|
305
+ | `A2uiSurface` | Low-level surface renderer |
306
+ | `createComponentImplementation` | Factory for catalog-bound components |
307
+ | `createBinderlessComponentImplementation` | Factory for components without data binding |
308
+ | `MarkdownContext` | Markdown renderer context |
309
+ | `useMarkdownRenderer` | Hook for custom markdown rendering |
287
310
 
288
- * `json/glchat_standard_catalog_definition.json`
289
- * `json/glchat_server_to_client_with_catalog.json`
290
- * `json/a2ui-sample-messages.json`
311
+ ### Re-exports (`@a2ui/web_core` v0.9)
291
312
 
292
- Upstream documentation:
293
- [https://a2ui.org/renderers/](https://a2ui.org/renderers/)
313
+ | Export | Description |
314
+ |---|---|
315
+ | `Catalog` | Catalog container (components + functions) |
316
+ | `MessageProcessor` | Processes A2UI message streams |
317
+ | `SurfaceModel` | Single-surface state model |
318
+ | `SurfaceGroupModel` | Multi-surface state model |
319
+ | `ComponentIdSchema` | Component ID validator |
320
+ | `ChildListSchema` | Child list validator |
321
+ | `ActionSchema` | Action validator |
322
+ | `DynamicStringSchema` | Dynamic string value validator |
323
+ | `DynamicNumberSchema` | Dynamic number value validator |
324
+ | `DynamicBooleanSchema` | Dynamic boolean value validator |
325
+ | `DynamicStringListSchema` | Dynamic string list validator |
326
+ | `DynamicValueSchema` | Dynamic value validator |
327
+ | `CheckableSchema` | Validation rules validator |
328
+ | `AccessibilityAttributesSchema` | Accessibility attributes validator |
329
+
330
+ ### Package assets
331
+
332
+ | Export | Description |
333
+ |---|---|
334
+ | `styles/globals.css` | Design tokens and A2UI surface overrides |
335
+ | `styles/theme-v4.css` | Tailwind v4 theme bridge |
336
+ | `tailwind-config.cjs` | Tailwind v3 preset |
337
+ | `json/glchat_standard_catalog_definition.json` | GLChat catalog JSON |
338
+ | `json/a2ui-sample-messages.json` | Sample messages JSON |
294
339
 
295
- ---
340
+ Refer to [A2UI renderer documentation](https://a2ui.org/renderers/) for upstream API details.
296
341
 
297
- # License
342
+ ## License
298
343
 
299
344
  MIT
package/dist/index.d.ts CHANGED
@@ -1,5 +1,11 @@
1
- export { Provider, type ProviderProps, type A2UIMessage, type ActionPayload, type ActionHandler, type MessageErrorHandler, } from './src/Provider.js';
2
- export { SingleSurfaceRenderer, type SingleSurfaceRendererProps, } from './src/SingleSurfaceRenderer.js';
3
- export { AllSurfacesRenderer, type AllSurfacesRendererProps } from './src/AllSurfacesRenderer.js';
4
- export { Types, ComponentRegistry, ComponentNode, useA2UIComponent, useA2UI, classMapToString, stylesToObject, type A2UIComponentProps, type Theme, type AnyComponentNode, type StringValue, type NumberValue, type BooleanValue, } from '@a2ui/react';
1
+ export { Provider, useSurfaceGroup, type ProviderProps, type A2UIMessage, type ActionPayload, type ActionHandler, type MessageErrorHandler, } from './src/Provider.js';
2
+ export { SurfaceRenderer, type SurfaceRendererProps } from './src/SurfaceRenderer.js';
3
+ export { useSurfaces } from './src/utils/useSurfaces.js';
4
+ export { createGlchatCatalog, GLCHAT_CATALOG_ID } from './src/utils/catalog.js';
5
+ export { GlchatButtonComponent, GlchatButtonApi } from './src/components/a2ui/Button/Button.js';
6
+ export { GlchatChoicePickerComponent } from './src/components/a2ui/ChoicePicker/ChoicePicker.js';
7
+ export { GlchatTagInputComponent, TagInputApi } from './src/components/a2ui/TagInput/TagInput.js';
8
+ export { GlchatTimeoutComponent, TimeoutApi } from './src/components/a2ui/Timeout/Timeout.js';
9
+ export { A2uiSurface, createComponentImplementation, createBinderlessComponentImplementation, MarkdownContext, useMarkdownRenderer, type ReactComponentImplementation, type ReactA2uiComponentProps, } from '@a2ui/react/v0_9';
10
+ export { Catalog, MessageProcessor, SurfaceModel, SurfaceGroupModel, ComponentIdSchema, ChildListSchema, ActionSchema, DynamicStringSchema, DynamicNumberSchema, DynamicBooleanSchema, DynamicStringListSchema, DynamicValueSchema, CheckableSchema, AccessibilityAttributesSchema, type ComponentApi, type A2uiMessage, type A2uiClientAction, } from '@a2ui/web_core/v0_9';
5
11
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,mBAAmB,EAAE,KAAK,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAGlG,OAAO,EACL,KAAK,EACL,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,OAAO,EACP,gBAAgB,EAChB,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEtF,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhF,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAChG,OAAO,EAAE,2BAA2B,EAAE,MAAM,oDAAoD,CAAC;AACjG,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAC;AAClG,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAG9F,OAAO,EACL,WAAW,EACX,6BAA6B,EAC7B,uCAAuC,EACvC,eAAe,EACf,mBAAmB,EACnB,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,eAAe,EACf,6BAA6B,EAC7B,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC"}
package/dist/index.js CHANGED
@@ -1,5 +1,13 @@
1
- export { Provider, } from './src/Provider.js';
2
- export { SingleSurfaceRenderer, } from './src/SingleSurfaceRenderer.js';
3
- export { AllSurfacesRenderer } from './src/AllSurfacesRenderer.js';
4
- // Re-exports from the official `@a2ui/react`
5
- export { Types, ComponentRegistry, ComponentNode, useA2UIComponent, useA2UI, classMapToString, stylesToObject, } from '@a2ui/react';
1
+ export { Provider, useSurfaceGroup, } from './src/Provider.js';
2
+ export { SurfaceRenderer } from './src/SurfaceRenderer.js';
3
+ export { useSurfaces } from './src/utils/useSurfaces.js';
4
+ export { createGlchatCatalog, GLCHAT_CATALOG_ID } from './src/utils/catalog.js';
5
+ // GLChat custom component implementations and their schemas
6
+ export { GlchatButtonComponent, GlchatButtonApi } from './src/components/a2ui/Button/Button.js';
7
+ export { GlchatChoicePickerComponent } from './src/components/a2ui/ChoicePicker/ChoicePicker.js';
8
+ export { GlchatTagInputComponent, TagInputApi } from './src/components/a2ui/TagInput/TagInput.js';
9
+ export { GlchatTimeoutComponent, TimeoutApi } from './src/components/a2ui/Timeout/Timeout.js';
10
+ // Re-exports from the official `@a2ui/react` (v0.9), for authoring components.
11
+ export { A2uiSurface, createComponentImplementation, createBinderlessComponentImplementation, MarkdownContext, useMarkdownRenderer, } from '@a2ui/react/v0_9';
12
+ // Re-exports from `@a2ui/web_core` (v0.9)
13
+ export { Catalog, MessageProcessor, SurfaceModel, SurfaceGroupModel, ComponentIdSchema, ChildListSchema, ActionSchema, DynamicStringSchema, DynamicNumberSchema, DynamicBooleanSchema, DynamicStringListSchema, DynamicValueSchema, CheckableSchema, AccessibilityAttributesSchema, } from '@a2ui/web_core/v0_9';
@@ -1,23 +1,30 @@
1
- import type { ReactNode } from 'react';
2
- import { ComponentRegistry, type ServerToClientMessage } from '@a2ui/react';
3
- import type { UserAction } from '@a2ui/web_core/types/client-event';
4
- import type { Theme } from '@a2ui/web_core/types/types';
5
- export type A2UIMessage = ServerToClientMessage;
6
- export type ActionPayload = UserAction;
7
- export type ActionHandler = (action: UserAction) => void | Promise<void>;
1
+ import type { PropsWithChildren } from 'react';
2
+ import { type ReactComponentImplementation } from '@a2ui/react/v0_9';
3
+ import { type Catalog, type A2uiClientAction, type A2uiMessage, type SurfaceGroupModel } from '@a2ui/web_core/v0_9';
4
+ export type A2UIMessage = A2uiMessage;
5
+ export type ActionPayload = A2uiClientAction;
6
+ export type ActionHandler = (action: A2uiClientAction) => void | Promise<void>;
8
7
  export type MessageErrorHandler = (error: unknown) => void;
9
8
  export type ProviderProps = {
9
+ /**
10
+ * A2UI messages to process. Only **new** messages appended since the last
11
+ * render are fed to the processor (append-only). To replace the full batch,
12
+ * remount `Provider` (e.g. change `key`) or send `deleteSurface` before
13
+ * `createSurface`.
14
+ */
10
15
  messages?: A2UIMessage[];
11
- theme?: Theme;
12
16
  onAction?: ActionHandler;
13
17
  onError?: MessageErrorHandler;
14
- children: ReactNode;
15
18
  /**
16
- * Optional registry override.
17
- * If not provided, the official singleton registry is used.
19
+ * Optional catalog override. If not provided, the GLChat extended A2UI v0.9
20
+ * catalog is used.
18
21
  */
19
- registry?: ComponentRegistry;
22
+ catalog?: Catalog<ReactComponentImplementation>;
20
23
  };
21
- export declare function Provider(props: Readonly<ProviderProps>): import("react/jsx-runtime").JSX.Element;
22
- export declare function useA2UIRegistry(): ComponentRegistry;
24
+ export declare function Provider({ messages, onAction, onError, catalog, children, }: Readonly<PropsWithChildren<ProviderProps>>): import("react").JSX.Element;
25
+ /**
26
+ * Returns the `SurfaceGroupModel` owned by the nearest `Provider`.
27
+ * Used by the surface renderers to read and subscribe to active surfaces.
28
+ */
29
+ export declare function useSurfaceGroup(): SurfaceGroupModel<ReactComponentImplementation>;
23
30
  //# sourceMappingURL=Provider.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Provider.d.ts","sourceRoot":"","sources":["../../src/Provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,EAEL,iBAAiB,EAGjB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAKxD,MAAM,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC;AACvC,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzE,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAE3D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B,CAAC;AA8BF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,2CAsCtD;AAED,wBAAgB,eAAe,IAAI,iBAAiB,CAInD"}
1
+ {"version":3,"file":"Provider.d.ts","sourceRoot":"","sources":["../../src/Provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAG/C,OAAO,EAAmB,KAAK,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAM7B,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC;AAEtC,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAC7C,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAE3D,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,4BAA4B,CAAC,CAAC;CACjD,CAAC;AAMF,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,QAAQ,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,+BA8D5C;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,CAAC,4BAA4B,CAAC,CAIjF"}