@copilotkit/angular 0.5.1 → 0.5.3

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
@@ -143,6 +143,8 @@ export interface CopilotKitConfig {
143
143
  It is disabled by default so missing renderers remain visible integration
144
144
  errors rather than silently changing the experience.
145
145
  - `a2ui`: Theme, catalog, schema, loading UI, and recovery policy for A2UI.
146
+ Surfaces render with the catalog from `@copilotkit/angular/a2ui` (see
147
+ below); without one, A2UI stays off.
146
148
  - `openGenerativeUI`: Sandboxed UI functions and optional design guidance.
147
149
 
148
150
  ### Injection helpers
@@ -425,6 +427,135 @@ take precedence over optional built-ins.
425
427
  server URL. The renderer uses the same inline `srcdoc` sandbox, sandbox
426
428
  permissions, and resource-domain CSP as the React SDK.
427
429
 
430
+ ### A2UI with Angular components
431
+
432
+ `@copilotkit/angular/a2ui` renders A2UI with ordinary standalone Angular
433
+ components. A2UI needs a catalog: without one it stays off, even when the
434
+ runtime enables it, and CopilotKit logs a warning. `basicCatalog`
435
+ implements the A2UI basic components (Text, Row, Column, Card, Button,
436
+ TextField, and the rest):
437
+
438
+ ```ts
439
+ import { basicCatalog } from "@copilotkit/angular/a2ui";
440
+
441
+ provideCopilotKit({
442
+ runtimeUrl: "/api/copilotkit",
443
+ a2ui: { catalog: basicCatalog },
444
+ });
445
+ ```
446
+
447
+ For your own components, build a catalog with `createAngularCatalog`. It
448
+ contains exactly the components you register unless you pass
449
+ `includeBasicCatalog: true`, which adds the basic components; a definition
450
+ with the same name replaces the basic one. A component receives the resolved
451
+ props through a single `props` input, or through inputs named after the
452
+ schema keys. Props the agent has not sent yet arrive as `undefined`, so put
453
+ defaults in the template (`label() ?? "…"`) rather than in `input("…")`.
454
+ Containers render children with `<copilot-a2ui-child>`.
455
+
456
+ ```ts
457
+ import {
458
+ ActionSchema,
459
+ ChildListSchema,
460
+ CopilotA2UIChild,
461
+ DynamicStringSchema,
462
+ createAngularCatalog,
463
+ type A2UICatalogDefinitions,
464
+ type A2UIProps,
465
+ } from "@copilotkit/angular/a2ui";
466
+
467
+ const definitions = {
468
+ Column: { props: z.object({ children: ChildListSchema }) },
469
+ Card: {
470
+ props: z.object({
471
+ title: DynamicStringSchema,
472
+ child: z.string().optional(),
473
+ }),
474
+ },
475
+ PrimaryButton: {
476
+ props: z.object({ label: z.string(), action: ActionSchema.optional() }),
477
+ },
478
+ } satisfies A2UICatalogDefinitions;
479
+
480
+ @Component({
481
+ selector: "app-a2ui-card",
482
+ imports: [CopilotA2UIChild],
483
+ template: `
484
+ <article>
485
+ <h3>{{ props().title }}</h3>
486
+ <copilot-a2ui-child [child]="props().child" />
487
+ </article>
488
+ `,
489
+ })
490
+ export class CardComponent {
491
+ readonly props = input.required<A2UIProps<typeof definitions, "Card">>();
492
+ }
493
+
494
+ export const catalog = createAngularCatalog(
495
+ definitions,
496
+ {
497
+ Column: ColumnComponent,
498
+ Card: CardComponent,
499
+ PrimaryButton: PrimaryButtonComponent,
500
+ },
501
+ { catalogId: "copilotkit://dashboard-catalog", includeBasicCatalog: true },
502
+ );
503
+
504
+ provideCopilotKit({ runtimeUrl: "/api/copilotkit", a2ui: { catalog } });
505
+ ```
506
+
507
+ Props declared with `ActionSchema` arrive as callable closures, and dynamic
508
+ props gain `set*` setters that write back to the data model. Inject
509
+ `injectA2UIComponentContext()` to dispatch custom actions or write data-model
510
+ paths directly. `<copilot-a2ui-surface>` renders operations outside the chat
511
+ with the same catalog. `Icon` renders Material Symbols ligatures, so load that
512
+ font if the agent uses icons.
513
+
514
+ A catalog entry can also be a Custom Element, such as an existing design
515
+ system's web component: pass `{ tagName, element }` instead of an Angular
516
+ component. CopilotKit registers the element, renders it in place of the node,
517
+ and assigns the node's A2UI `ComponentContext` to its `context` property on
518
+ every update; the element reads its props and dispatches actions from there.
519
+
520
+ ```ts
521
+ createAngularCatalog(
522
+ { Badge: { props: z.object({ label: z.string() }) } },
523
+ { Badge: { tagName: "acme-badge", element: AcmeBadge } },
524
+ );
525
+ ```
526
+
527
+ The basic catalog and the surface are styled with CSS variables. Set them on
528
+ any ancestor; the CopilotKit stylesheet switches the colors in dark mode. The
529
+ agent's `primaryColor` theme sets `--a2ui-color-primary` for its surface.
530
+
531
+ | Variable | Default | Used for |
532
+ | ----------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------- |
533
+ | `--a2ui-color-primary` | `#007bff` | primary buttons, active tabs, selected chips |
534
+ | `--a2ui-color-on-primary` | `#fff` | text on the primary color |
535
+ | `--a2ui-color-surface` | `#fff` | cards, buttons, chips, dialogs |
536
+ | `--a2ui-color-border` | `#ccc` | borders and dividers |
537
+ | `--a2ui-color-muted` | `#666` | captions and secondary text |
538
+ | `--a2ui-color-error` | `red` | validation errors |
539
+ | `--a2ui-color-input`, `--a2ui-color-on-input` | system field colors | text inputs |
540
+ | `--a2ui-color-placeholder`, `--a2ui-color-placeholder-highlight` | `#f3f4f6`, `#e5e7eb` | loading and pending placeholders |
541
+ | `--a2ui-spacing-m` | `8px` | component margins and gaps |
542
+ | `--a2ui-row-gap`, `--a2ui-column-gap`, `--a2ui-list-gap` | `--a2ui-spacing-m` | space between children |
543
+ | `--a2ui-border-radius` | `8px` | cards, inputs, dialogs |
544
+ | `--a2ui-font-size-s`, `--a2ui-font-size-xs` | `14px`, `12px` | labels, captions |
545
+ | `--a2ui-card-padding`, `--a2ui-card-shadow` | `16px`, subtle shadow | Card |
546
+ | `--a2ui-button-padding`, `--a2ui-button-border-radius` | `8px 16px`, `4px` | Button, tabs |
547
+ | `--a2ui-input-padding` | `8px` | TextField, DateTimeInput |
548
+ | `--a2ui-chip-border-radius` | `16px` | ChoicePicker chips |
549
+ | `--a2ui-icon-size` | `24px` | Icon |
550
+ | `--a2ui-modal-backdrop`, `--a2ui-modal-padding`, `--a2ui-modal-z-index` | `rgba(0, 0, 0, 0.5)`, `24px`, `1000` | Modal |
551
+
552
+ `--a2ui-primary-color`, which the React and Vue renderers use, still works as
553
+ a fallback for `--a2ui-color-primary`.
554
+
555
+ As in the A2UI renderers, Row, Column and List space their children with a gap
556
+ rather than margins on each component, and a component's `weight` becomes its
557
+ `flex` grow factor inside a Row or Column.
558
+
428
559
  ## Lifecycle and cleanup
429
560
 
430
561
  Call `injectAgentStore`, `connectAgentContext`, `registerFrontendTool`,
package/dist/README.md CHANGED
@@ -143,6 +143,8 @@ export interface CopilotKitConfig {
143
143
  It is disabled by default so missing renderers remain visible integration
144
144
  errors rather than silently changing the experience.
145
145
  - `a2ui`: Theme, catalog, schema, loading UI, and recovery policy for A2UI.
146
+ Surfaces render with the catalog from `@copilotkit/angular/a2ui` (see
147
+ below); without one, A2UI stays off.
146
148
  - `openGenerativeUI`: Sandboxed UI functions and optional design guidance.
147
149
 
148
150
  ### Injection helpers
@@ -425,6 +427,135 @@ take precedence over optional built-ins.
425
427
  server URL. The renderer uses the same inline `srcdoc` sandbox, sandbox
426
428
  permissions, and resource-domain CSP as the React SDK.
427
429
 
430
+ ### A2UI with Angular components
431
+
432
+ `@copilotkit/angular/a2ui` renders A2UI with ordinary standalone Angular
433
+ components. A2UI needs a catalog: without one it stays off, even when the
434
+ runtime enables it, and CopilotKit logs a warning. `basicCatalog`
435
+ implements the A2UI basic components (Text, Row, Column, Card, Button,
436
+ TextField, and the rest):
437
+
438
+ ```ts
439
+ import { basicCatalog } from "@copilotkit/angular/a2ui";
440
+
441
+ provideCopilotKit({
442
+ runtimeUrl: "/api/copilotkit",
443
+ a2ui: { catalog: basicCatalog },
444
+ });
445
+ ```
446
+
447
+ For your own components, build a catalog with `createAngularCatalog`. It
448
+ contains exactly the components you register unless you pass
449
+ `includeBasicCatalog: true`, which adds the basic components; a definition
450
+ with the same name replaces the basic one. A component receives the resolved
451
+ props through a single `props` input, or through inputs named after the
452
+ schema keys. Props the agent has not sent yet arrive as `undefined`, so put
453
+ defaults in the template (`label() ?? "…"`) rather than in `input("…")`.
454
+ Containers render children with `<copilot-a2ui-child>`.
455
+
456
+ ```ts
457
+ import {
458
+ ActionSchema,
459
+ ChildListSchema,
460
+ CopilotA2UIChild,
461
+ DynamicStringSchema,
462
+ createAngularCatalog,
463
+ type A2UICatalogDefinitions,
464
+ type A2UIProps,
465
+ } from "@copilotkit/angular/a2ui";
466
+
467
+ const definitions = {
468
+ Column: { props: z.object({ children: ChildListSchema }) },
469
+ Card: {
470
+ props: z.object({
471
+ title: DynamicStringSchema,
472
+ child: z.string().optional(),
473
+ }),
474
+ },
475
+ PrimaryButton: {
476
+ props: z.object({ label: z.string(), action: ActionSchema.optional() }),
477
+ },
478
+ } satisfies A2UICatalogDefinitions;
479
+
480
+ @Component({
481
+ selector: "app-a2ui-card",
482
+ imports: [CopilotA2UIChild],
483
+ template: `
484
+ <article>
485
+ <h3>{{ props().title }}</h3>
486
+ <copilot-a2ui-child [child]="props().child" />
487
+ </article>
488
+ `,
489
+ })
490
+ export class CardComponent {
491
+ readonly props = input.required<A2UIProps<typeof definitions, "Card">>();
492
+ }
493
+
494
+ export const catalog = createAngularCatalog(
495
+ definitions,
496
+ {
497
+ Column: ColumnComponent,
498
+ Card: CardComponent,
499
+ PrimaryButton: PrimaryButtonComponent,
500
+ },
501
+ { catalogId: "copilotkit://dashboard-catalog", includeBasicCatalog: true },
502
+ );
503
+
504
+ provideCopilotKit({ runtimeUrl: "/api/copilotkit", a2ui: { catalog } });
505
+ ```
506
+
507
+ Props declared with `ActionSchema` arrive as callable closures, and dynamic
508
+ props gain `set*` setters that write back to the data model. Inject
509
+ `injectA2UIComponentContext()` to dispatch custom actions or write data-model
510
+ paths directly. `<copilot-a2ui-surface>` renders operations outside the chat
511
+ with the same catalog. `Icon` renders Material Symbols ligatures, so load that
512
+ font if the agent uses icons.
513
+
514
+ A catalog entry can also be a Custom Element, such as an existing design
515
+ system's web component: pass `{ tagName, element }` instead of an Angular
516
+ component. CopilotKit registers the element, renders it in place of the node,
517
+ and assigns the node's A2UI `ComponentContext` to its `context` property on
518
+ every update; the element reads its props and dispatches actions from there.
519
+
520
+ ```ts
521
+ createAngularCatalog(
522
+ { Badge: { props: z.object({ label: z.string() }) } },
523
+ { Badge: { tagName: "acme-badge", element: AcmeBadge } },
524
+ );
525
+ ```
526
+
527
+ The basic catalog and the surface are styled with CSS variables. Set them on
528
+ any ancestor; the CopilotKit stylesheet switches the colors in dark mode. The
529
+ agent's `primaryColor` theme sets `--a2ui-color-primary` for its surface.
530
+
531
+ | Variable | Default | Used for |
532
+ | ----------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------- |
533
+ | `--a2ui-color-primary` | `#007bff` | primary buttons, active tabs, selected chips |
534
+ | `--a2ui-color-on-primary` | `#fff` | text on the primary color |
535
+ | `--a2ui-color-surface` | `#fff` | cards, buttons, chips, dialogs |
536
+ | `--a2ui-color-border` | `#ccc` | borders and dividers |
537
+ | `--a2ui-color-muted` | `#666` | captions and secondary text |
538
+ | `--a2ui-color-error` | `red` | validation errors |
539
+ | `--a2ui-color-input`, `--a2ui-color-on-input` | system field colors | text inputs |
540
+ | `--a2ui-color-placeholder`, `--a2ui-color-placeholder-highlight` | `#f3f4f6`, `#e5e7eb` | loading and pending placeholders |
541
+ | `--a2ui-spacing-m` | `8px` | component margins and gaps |
542
+ | `--a2ui-row-gap`, `--a2ui-column-gap`, `--a2ui-list-gap` | `--a2ui-spacing-m` | space between children |
543
+ | `--a2ui-border-radius` | `8px` | cards, inputs, dialogs |
544
+ | `--a2ui-font-size-s`, `--a2ui-font-size-xs` | `14px`, `12px` | labels, captions |
545
+ | `--a2ui-card-padding`, `--a2ui-card-shadow` | `16px`, subtle shadow | Card |
546
+ | `--a2ui-button-padding`, `--a2ui-button-border-radius` | `8px 16px`, `4px` | Button, tabs |
547
+ | `--a2ui-input-padding` | `8px` | TextField, DateTimeInput |
548
+ | `--a2ui-chip-border-radius` | `16px` | ChoicePicker chips |
549
+ | `--a2ui-icon-size` | `24px` | Icon |
550
+ | `--a2ui-modal-backdrop`, `--a2ui-modal-padding`, `--a2ui-modal-z-index` | `rgba(0, 0, 0, 0.5)`, `24px`, `1000` | Modal |
551
+
552
+ `--a2ui-primary-color`, which the React and Vue renderers use, still works as
553
+ a fallback for `--a2ui-color-primary`.
554
+
555
+ As in the A2UI renderers, Row, Column and List space their children with a gap
556
+ rather than margins on each component, and a component's `weight` becomes its
557
+ `flex` grow factor inside a Row or Column.
558
+
428
559
  ## Lifecycle and cleanup
429
560
 
430
561
  Call `injectAgentStore`, `connectAgentContext`, `registerFrontendTool`,