glchat-a2ui-react-renderer 0.2.6 → 0.2.8

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 (108) hide show
  1. package/README.md +251 -124
  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 +31 -24
  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/ChoicePicker/CheckboxList.js +34 -0
  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 +15 -12
  23. package/dist/src/components/a2ui/TagInput/TagInput.d.ts +290 -0
  24. package/dist/src/components/a2ui/TagInput/TagInput.d.ts.map +1 -0
  25. package/dist/src/components/a2ui/TagInput/TagInput.js +110 -0
  26. package/dist/src/components/a2ui/TagInput/theme.d.ts +13 -0
  27. package/dist/src/components/a2ui/TagInput/theme.d.ts.map +1 -0
  28. package/dist/src/components/a2ui/TagInput/theme.js +74 -0
  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/Button.d.ts +15 -0
  36. package/dist/src/components/ui/Button/Button.d.ts.map +1 -0
  37. package/dist/src/components/ui/Button/Button.js +16 -0
  38. package/dist/src/components/ui/Button/theme.d.ts +5 -0
  39. package/dist/src/components/ui/Button/theme.d.ts.map +1 -0
  40. package/dist/src/components/{a2ui → ui}/Button/theme.js +13 -10
  41. package/dist/src/components/ui/Checkbox/Checkbox.js +2 -2
  42. package/dist/src/components/ui/Checkbox/theme.d.ts +3 -3
  43. package/dist/src/components/ui/Checkbox/theme.d.ts.map +1 -1
  44. package/dist/src/components/ui/Checkbox/theme.js +3 -3
  45. package/dist/src/components/ui/MultiSelect/MultiSelect.d.ts +1 -1
  46. package/dist/src/components/ui/MultiSelect/MultiSelect.d.ts.map +1 -1
  47. package/dist/src/components/ui/MultiSelect/MultiSelect.js +12 -12
  48. package/dist/src/components/ui/MultiSelect/theme.d.ts +12 -12
  49. package/dist/src/components/ui/MultiSelect/theme.d.ts.map +1 -1
  50. package/dist/src/components/ui/MultiSelect/theme.js +13 -13
  51. package/dist/src/components/ui/Select/Select.js +8 -8
  52. package/dist/src/components/ui/Select/theme.d.ts +8 -8
  53. package/dist/src/components/ui/Select/theme.d.ts.map +1 -1
  54. package/dist/src/components/ui/Select/theme.js +8 -9
  55. package/dist/src/utils/catalog.d.ts +16 -4
  56. package/dist/src/utils/catalog.d.ts.map +1 -1
  57. package/dist/src/utils/catalog.js +32 -27
  58. package/dist/src/utils/useSurfaces.d.ts +9 -0
  59. package/dist/src/utils/useSurfaces.d.ts.map +1 -0
  60. package/dist/src/utils/useSurfaces.js +28 -0
  61. package/json/README.md +61 -0
  62. package/json/a2ui-sample-messages.json +193 -0
  63. package/json/glchat_standard_catalog_definition.json +1470 -0
  64. package/package.json +15 -6
  65. package/styles/globals.css +232 -38
  66. package/dist/src/AllSurfacesRenderer.d.ts +0 -14
  67. package/dist/src/AllSurfacesRenderer.d.ts.map +0 -1
  68. package/dist/src/AllSurfacesRenderer.js +0 -18
  69. package/dist/src/SingleSurfaceRenderer.d.ts +0 -15
  70. package/dist/src/SingleSurfaceRenderer.d.ts.map +0 -1
  71. package/dist/src/SingleSurfaceRenderer.js +0 -9
  72. package/dist/src/components/a2ui/Button/theme.d.ts +0 -14
  73. package/dist/src/components/a2ui/Button/theme.d.ts.map +0 -1
  74. package/dist/src/components/a2ui/Card/Card.d.ts +0 -4
  75. package/dist/src/components/a2ui/Card/Card.d.ts.map +0 -1
  76. package/dist/src/components/a2ui/Card/Card.js +0 -16
  77. package/dist/src/components/a2ui/Card/theme.d.ts +0 -10
  78. package/dist/src/components/a2ui/Card/theme.d.ts.map +0 -1
  79. package/dist/src/components/a2ui/Card/theme.js +0 -21
  80. package/dist/src/components/a2ui/CheckBox/CheckBox.d.ts +0 -4
  81. package/dist/src/components/a2ui/CheckBox/CheckBox.d.ts.map +0 -1
  82. package/dist/src/components/a2ui/CheckBox/CheckBox.js +0 -26
  83. package/dist/src/components/a2ui/CheckBox/theme.d.ts +0 -11
  84. package/dist/src/components/a2ui/CheckBox/theme.d.ts.map +0 -1
  85. package/dist/src/components/a2ui/CheckBox/theme.js +0 -17
  86. package/dist/src/components/a2ui/DateTimeInput/theme.d.ts +0 -8
  87. package/dist/src/components/a2ui/DateTimeInput/theme.d.ts.map +0 -1
  88. package/dist/src/components/a2ui/DateTimeInput/theme.js +0 -11
  89. package/dist/src/components/a2ui/MultipleChoice/CheckboxList.d.ts.map +0 -1
  90. package/dist/src/components/a2ui/MultipleChoice/CheckboxList.js +0 -45
  91. package/dist/src/components/a2ui/MultipleChoice/MultipleChoice.d.ts +0 -4
  92. package/dist/src/components/a2ui/MultipleChoice/MultipleChoice.d.ts.map +0 -1
  93. package/dist/src/components/a2ui/MultipleChoice/MultipleChoice.js +0 -72
  94. package/dist/src/components/a2ui/MultipleChoice/theme.d.ts +0 -13
  95. package/dist/src/components/a2ui/MultipleChoice/theme.d.ts.map +0 -1
  96. package/dist/src/components/a2ui/TextField/TextField.d.ts +0 -4
  97. package/dist/src/components/a2ui/TextField/TextField.d.ts.map +0 -1
  98. package/dist/src/components/a2ui/TextField/TextField.js +0 -54
  99. package/dist/src/components/a2ui/TextField/theme.d.ts +0 -28
  100. package/dist/src/components/a2ui/TextField/theme.d.ts.map +0 -1
  101. package/dist/src/components/a2ui/TextField/theme.js +0 -82
  102. package/dist/src/components/a2ui/Timeout/theme.d.ts +0 -8
  103. package/dist/src/components/a2ui/Timeout/theme.d.ts.map +0 -1
  104. package/dist/src/components/a2ui/Timeout/theme.js +0 -12
  105. package/dist/src/utils/theme.d.ts +0 -4
  106. package/dist/src/utils/theme.d.ts.map +0 -1
  107. package/dist/src/utils/theme.js +0 -92
  108. package/patches/@a2ui+web_core+0.10.0.patch +0 -55
package/README.md CHANGED
@@ -1,99 +1,203 @@
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 (`Button`, `Card`, `Timeout`).
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.
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` |
11
12
 
12
- This library provides **GLChat-specific components and styling** while remaining fully compatible with the upstream A2UI renderer.
13
+ ## Requirements
13
14
 
14
- ---
15
-
16
- # Prerequisites
17
-
18
- * **React 18+**
19
- * **Tailwind CSS v3 or v4**
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))
20
18
 
21
- ---
22
-
23
- # Install
19
+ ## Installation
24
20
 
25
21
  ```bash
26
22
  npm install glchat-a2ui-react-renderer
27
23
  ```
28
24
 
29
- ---
30
-
31
- # Quick Start
32
-
33
- Use the GLChat-aware wrappers:
25
+ ## Quick start
34
26
 
35
27
  ```tsx
36
- import {
37
- Provider,
38
- SingleSurfaceRenderer,
39
- AllSurfacesRenderer,
40
- } from 'glchat-a2ui-react-renderer';
28
+ import { Provider, SurfaceRenderer } from 'glchat-a2ui-react-renderer';
41
29
  import type { A2UIMessage, ActionPayload } from 'glchat-a2ui-react-renderer';
42
30
 
43
31
  function App() {
44
- const messages: A2UIMessage[] = [
45
- // A2UI messages from your backend
46
- ];
32
+ const messages: A2UIMessage[] = [/* A2UI v0.9 messages from the backend */];
47
33
 
48
34
  const handleAction = (action: ActionPayload) => {
49
- console.log('Action received:', action);
35
+ // { name, surfaceId, sourceComponentId, timestamp, context }
36
+ console.log('Action:', action);
50
37
  };
51
38
 
52
39
  return (
53
40
  <Provider messages={messages} onAction={handleAction}>
54
- <AllSurfacesRenderer />
41
+ <SurfaceRenderer />
55
42
  </Provider>
56
43
  );
57
44
  }
45
+ ```
46
+
47
+ **Configuration notes:**
58
48
 
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.
53
+
54
+ ## Icons
55
+
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:
57
+
58
+ ```html
59
+ <link
60
+ href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&display=swap"
61
+ rel="stylesheet"
62
+ />
59
63
  ```
60
64
 
61
- To render a single surface explicitly:
65
+ Alternatively, import it in global CSS before other stylesheets:
66
+
67
+ ```css
68
+ @import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&display=swap');
69
+ ```
70
+
71
+ Icons specified with an SVG path object (`{ "svgPath": "..." }`) render as inline SVG and do not require the font.
72
+
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`:
78
+
79
+ ```css
80
+ .a2ui-surface {
81
+ --font-sans: var(--your-app-font);
82
+ }
83
+ ```
84
+
85
+ To adopt Inter explicitly:
86
+
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 |
95
+ |---|---|
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).
102
+
103
+ ## Custom components (Optional)
104
+
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**
62
108
 
63
109
  ```tsx
64
- <Provider messages={messages} onAction={handleAction}>
65
- <SingleSurfaceRenderer surfaceId="main" />
66
- </Provider>
110
+ import { z } from 'zod';
111
+ import {
112
+ createComponentImplementation,
113
+ DynamicStringSchema,
114
+ AccessibilityAttributesSchema,
115
+ } from 'glchat-a2ui-react-renderer';
116
+
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
+ };
67
128
  ```
68
129
 
69
- > **Note:** `onAction` is configured on `Provider`. Both `SingleSurfaceRenderer` and `AllSurfacesRenderer` must be rendered inside a `Provider`.
130
+ **2. Implement the renderer**
70
131
 
71
- # Custom Components (optional)
132
+ `createComponentImplementation` binds resolved props from the data model (e.g. `props.label`, `props.action`, `props.value`, `props.setValue` for interactive fields):
72
133
 
73
- `Provider` automatically registers GLChat's `Button`, `Card`, and `Timeout` overrides — no extra setup needed.
74
- To add your own node types on top, register them on the singleton `ComponentRegistry` before rendering:
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
+ ));
138
+ ```
139
+
140
+ For child components, use `buildChild`:
75
141
 
76
142
  ```tsx
77
- import { ComponentRegistry, Types, type A2UIComponentProps } from 'glchat-a2ui-react-renderer';
143
+ createComponentImplementation(MyApi, ({ props, buildChild }) => (
144
+ <div>{props.child ? buildChild(props.child) : null}</div>
145
+ );
146
+ ```
78
147
 
79
- function MyNodeComponent({ node }: Readonly<A2UIComponentProps<Types.CustomNode>>) {
80
- const label = (node.properties as any).label as string | undefined;
81
- return <div>{label}</div>;
82
- }
148
+ **3. Build a catalog**
83
149
 
84
- // GLChat's standard components are already included by Provider.
85
- // Just register your own additional node types here.
86
- const registry = ComponentRegistry.getInstance();
87
- registry.register('MyNodeType', { component: MyNodeComponent as any });
150
+ Start from `createGlchatCatalog()` and append the new component. Reuse `GLCHAT_CATALOG_ID` so existing `createSurface` messages remain valid:
151
+
152
+ ```tsx
153
+ import {
154
+ Catalog,
155
+ createGlchatCatalog,
156
+ GLCHAT_CATALOG_ID,
157
+ } from 'glchat-a2ui-react-renderer';
158
+
159
+ const glchat = createGlchatCatalog();
160
+ const catalog = new Catalog(
161
+ GLCHAT_CATALOG_ID,
162
+ [...glchat.components.values(), BadgeComponent],
163
+ [...glchat.functions.values()],
164
+ );
88
165
  ```
89
166
 
90
- ---
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
91
176
 
92
- # Tailwind Setup
177
+ For explicit control over surface layout, use `useSurfaceGroup`, `useSurfaces`, and `A2uiSurface` instead of `SurfaceRenderer`:
93
178
 
94
- ## Tailwind v4
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
+ ```
95
195
 
96
- Add the following to your main CSS file (`globals.css`):
196
+ ## Tailwind setup
197
+
198
+ ### Tailwind v4
199
+
200
+ Add the following to the application CSS entry point:
97
201
 
98
202
  ```css
99
203
  @import "tailwindcss";
@@ -127,24 +231,13 @@ module.exports = {
127
231
  };
128
232
  ```
129
233
 
130
- Import the tokens in your main CSS:
131
-
132
- ```css
133
- @import "glchat-a2ui-react-renderer/styles/globals.css";
134
-
135
- @tailwind base;
136
- @tailwind components;
137
- @tailwind utilities;
138
- ```
139
-
140
- ---
234
+ Import `styles/globals.css` before the `@tailwind` directives.
141
235
 
142
- # Customizing Colors (optional)
236
+ ## Theming
143
237
 
144
- 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`:
145
239
 
146
240
  ```css
147
- /* ✅ Works in both Tailwind v3 and v4 */
148
241
  :root {
149
242
  --primary: 220 90% 45%;
150
243
  --background: 0 0% 99%;
@@ -155,63 +248,97 @@ The package tokens are declared as plain (unlayered) `:root` rules. To override
155
248
  }
156
249
  ```
157
250
 
158
- Button (core variants) uses these tokens by default:
159
-
160
- - `primary`: `--primary`, `--primary-foreground`, `--ring`
161
- - `destructive`: `--destructive`, `--destructive-foreground`, `--ring`
162
- - `outline`: `--background`, `--background-alternate`, `--foreground`, `--border`, `--ring`
163
-
164
- You may also extend the theme via:
165
-
166
- * `tailwind.config.js` (v3)
167
- * `@theme` (v4)
168
-
169
- ---
170
-
171
- # Exports
172
-
173
- ## Components
174
-
175
- * `Provider`
176
- * `SingleSurfaceRenderer`
177
- * `AllSurfacesRenderer`
178
-
179
- ## Types
180
-
181
- * `ProviderProps`
182
- * `SingleSurfaceRendererProps`
183
- * `AllSurfacesRendererProps`
184
- * `A2UIMessage`
185
- * `ActionPayload`
186
- * `ActionHandler`
187
-
188
- ## Re-exports from `@a2ui/react`
189
-
190
- * `Types`
191
- * `ComponentRegistry`
192
- * `ComponentNode`
193
- * `useA2UIComponent`
194
- * `useA2UI`
195
- * `classMapToString`
196
- * `stylesToObject`
197
- * `A2UIComponentProps`
198
- * `Theme`
199
- * `AnyComponentNode`
200
- * `StringValue`
201
- * `NumberValue`
202
- * `BooleanValue`
203
-
204
- ## Styles
205
-
206
- * `styles/globals.css`
207
- * `styles/theme-v4.css`
208
- * `tailwind-config.cjs`
209
-
210
- Upstream documentation:
211
- [https://a2ui.org/renderers/](https://a2ui.org/renderers/)
212
-
213
- ---
214
-
215
- # License
251
+ ## JSON schemas
252
+
253
+ Published for agent catalog registration and reference:
254
+
255
+ | File | Description |
256
+ |---|---|
257
+ | `json/glchat_standard_catalog_definition.json` | GLChat catalog definition |
258
+ | `json/a2ui-sample-messages.json` | Sample message sequence |
259
+
260
+ ## Public API
261
+
262
+ ### Components and hooks
263
+
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 |
270
+
271
+ ### Types
272
+
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 |
310
+
311
+ ### Re-exports (`@a2ui/web_core` v0.9)
312
+
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 |
339
+
340
+ Refer to [A2UI renderer documentation](https://a2ui.org/renderers/) for upstream API details.
341
+
342
+ ## License
216
343
 
217
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"}
@@ -1,56 +1,70 @@
1
1
  'use client';
2
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
- import { createContext, useCallback, useContext, useEffect, useMemo, useRef } from 'react';
4
- import { A2UIProvider, ComponentRegistry, useA2UI, } from '@a2ui/react';
5
- import { ensureGlchatComponentsRegistered } from './utils/catalog.js';
6
- import { mergeGlchatTheme } from './utils/theme.js';
7
- const A2UIRegistryContext = createContext(null);
8
- function MessagesProcessor({ messages, onError, }) {
9
- const { processMessages } = useA2UI();
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { createContext, useContext, useEffect, useRef, useState } from 'react';
4
+ import { MarkdownContext } from '@a2ui/react/v0_9';
5
+ import { MessageProcessor, } from '@a2ui/web_core/v0_9';
6
+ import { injectBasicCatalogStyles } from '@a2ui/web_core/v0_9/basic_catalog';
7
+ import { renderMarkdown } from '@a2ui/markdown-it';
8
+ import { createGlchatCatalog } from './utils/catalog.js';
9
+ const SurfaceGroupContext = createContext(null);
10
+ export function Provider({ messages, onAction, onError, catalog, children, }) {
11
+ const onActionRef = useRef(onAction);
12
+ const onErrorRef = useRef(onError);
10
13
  useEffect(() => {
11
- if (!messages)
14
+ onActionRef.current = onAction;
15
+ }, [onAction]);
16
+ useEffect(() => {
17
+ onErrorRef.current = onError;
18
+ }, [onError]);
19
+ const [processor] = useState(() => {
20
+ const resolvedCatalog = catalog ?? createGlchatCatalog();
21
+ return new MessageProcessor([resolvedCatalog]);
22
+ });
23
+ const processedCountRef = useRef(0);
24
+ useEffect(() => {
25
+ const subscription = processor.model.onAction.subscribe((action) => {
26
+ onActionRef.current?.(action);
27
+ });
28
+ return () => subscription.unsubscribe();
29
+ }, [processor]);
30
+ useEffect(() => {
31
+ if (typeof document !== 'undefined' && document.adoptedStyleSheets) {
32
+ injectBasicCatalogStyles();
33
+ }
34
+ }, []);
35
+ useEffect(() => {
36
+ if (!messages?.length)
37
+ return;
38
+ // Shorter list means the consumer reset the stream — reprocess from the start.
39
+ if (messages.length < processedCountRef.current) {
40
+ processedCountRef.current = 0;
41
+ }
42
+ if (processedCountRef.current >= messages.length)
12
43
  return;
44
+ const pending = messages.slice(processedCountRef.current);
45
+ processedCountRef.current = messages.length;
13
46
  try {
14
- processMessages(messages);
47
+ processor.processMessages(pending);
15
48
  }
16
49
  catch (error) {
17
- if (onError) {
18
- onError(error);
50
+ if (onErrorRef.current) {
51
+ onErrorRef.current(error);
19
52
  }
20
53
  else {
21
54
  // eslint-disable-next-line no-console
22
55
  console.error('[glchat-a2ui] Failed to process messages:', error);
23
56
  }
24
57
  }
25
- }, [messages, processMessages, onError]);
26
- return null;
27
- }
28
- export function Provider(props) {
29
- const registry = useMemo(() => props.registry ?? ComponentRegistry.getInstance(), [props.registry]);
30
- const providerOnActionRef = useRef(props.onAction);
31
- useEffect(() => {
32
- providerOnActionRef.current = props.onAction;
33
- }, [props.onAction]);
34
- const onAction = useCallback((event) => {
35
- const userAction = event?.userAction;
36
- if (!userAction)
37
- return;
38
- const handler = providerOnActionRef.current;
39
- if (!handler)
40
- return;
41
- handler(userAction);
42
- }, []);
43
- // Register (or override) components after `@a2ui/react` has initialized its defaults.
44
- // This avoids the official default catalog overwriting our custom component registrations.
45
- useEffect(() => {
46
- ensureGlchatComponentsRegistered(registry);
47
- }, [registry]);
48
- const theme = useMemo(() => mergeGlchatTheme(props.theme), [props.theme]);
49
- return (_jsx(A2UIRegistryContext.Provider, { value: registry, children: _jsxs(A2UIProvider, { onAction: onAction, theme: theme, children: [_jsx(MessagesProcessor, { messages: props.messages, onError: props.onError }), props.children] }) }));
58
+ }, [messages, processor]);
59
+ return (_jsx(SurfaceGroupContext.Provider, { value: processor.model, children: _jsx(MarkdownContext.Provider, { value: renderMarkdown, children: children }) }));
50
60
  }
51
- export function useA2UIRegistry() {
52
- const registry = useContext(A2UIRegistryContext);
53
- if (!registry)
54
- throw new Error('useA2UIRegistry must be used inside Provider');
55
- return registry;
61
+ /**
62
+ * Returns the `SurfaceGroupModel` owned by the nearest `Provider`.
63
+ * Used by the surface renderers to read and subscribe to active surfaces.
64
+ */
65
+ export function useSurfaceGroup() {
66
+ const model = useContext(SurfaceGroupContext);
67
+ if (!model)
68
+ throw new Error('useSurfaceGroup must be used inside Provider');
69
+ return model;
56
70
  }