docs: design system integration + custom components guides#824
docs: design system integration + custom components guides#824zeroasterisk wants to merge 6 commits intogoogle:mainfrom
Conversation
…be component - New guide: design-system-integration.md — step-by-step for adding A2UI to an existing Material Angular application - Rewritten guide: custom-components.md — complete walkthrough for YouTube, Maps, and Charts custom components (replaces TODO skeleton) - New sample component: YouTube embed for rizzcharts catalog - Updated rizzcharts catalog.ts to include YouTube component - Friction log documenting 8 friction points (P2/P3) encountered during development, with recommendations - Added Design System Integration to mkdocs nav
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation for design system integration and custom components, which are crucial for onboarding new developers to A2UI. The new guides are well-structured and provide clear, step-by-step examples. I've included a few suggestions to enhance the accuracy of the documentation and a security recommendation for the new YouTube sample component to ensure agent-provided data is properly validated.
| const id = this.resolvedVideoId(); | ||
| if (!id) return null; | ||
| const autoplay = this.resolvedAutoplay() ? '1' : '0'; | ||
| const url = `https://www.youtube.com/embed/${encodeURIComponent(id)}?autoplay=${autoplay}&rel=0`; | ||
| return this.sanitizer.bypassSecurityTrustResourceUrl(url); |
There was a problem hiding this comment.
The videoId received from the agent is not validated before being used in the YouTube embed URL. While it is URI-encoded, a malicious agent could provide a value that is not a valid YouTube video ID. This could lead to unexpected behavior or attempts to load content from unintended paths on youtube.com. As a security best practice, you should validate that the videoId conforms to the expected format (e.g., using a regular expression).
const id = this.resolvedVideoId();
if (!id) return null;
// Validate the video ID to ensure it's in the expected format.
const youtubeIdRegex = /^[a-zA-Z0-9_-]{11}$/;
if (!youtubeIdRegex.test(id)) {
console.error('Invalid YouTube video ID received from agent:', id);
return null;
}
const autoplay = this.resolvedAutoplay() ? '1' : '0';
const url = `https://www.youtube.com/embed/${encodeURIComponent(id)}?autoplay=${autoplay}&rel=0`;
return this.sanitizer.bypassSecurityTrustResourceUrl(url);There was a problem hiding this comment.
sure, we should do this
docs/guides/custom-components.md
Outdated
| @@ -1,83 +1,409 @@ | |||
| # Custom Component Catalogs | |||
| # Custom Components | |||
There was a problem hiding this comment.
Custom Component Catalogs
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
docs/guides/custom-components.md
Outdated
| # Custom Components | ||
|
|
||
| Extend A2UI by defining **custom catalogs** that include your own components alongside standard A2UI components. | ||
| Extend A2UI with your own components — maps, charts, video players, or anything your application needs. |
There was a problem hiding this comment.
with a catalog of your own components
docs/guides/custom-components.md
Outdated
| ## Why Custom Components? | ||
|
|
||
| The A2UI Standard Catalog provides common UI elements (buttons, text fields, etc.), but your application might need specialized components: | ||
| The A2UI Standard Catalog covers common UI elements (text, buttons, inputs, layout), but real applications need specialized components: |
There was a problem hiding this comment.
your application might need is better here
docs/guides/custom-components.md
Outdated
| - **Brand-specific components**: Custom date pickers, product cards, dashboards | ||
| - **Maps**: Google Maps, Mapbox, Leaflet | ||
| - **Charts**: Chart.js, D3, Recharts | ||
| - **Media**: YouTube embeds, audio visualizers, 3D viewers |
There was a problem hiding this comment.
put media at the top of the list
docs/guides/custom-components.md
Outdated
| 2. **Validate properties**: Always validate component properties from agent messages | ||
| 3. **Sanitize user input**: If components accept user input, sanitize it before processing | ||
| 4. **Limit API access**: Don't expose sensitive APIs or credentials to custom components | ||
| - `...DEFAULT_CATALOG` — spread the standard catalog so agents can use standard components too |
There was a problem hiding this comment.
A2UI ships with a basic catalog to get you started quickly, you do not need to use it if you already have the components you want to render
docs/guides/custom-components.md
Outdated
|
|
||
| The agent knows about your custom components through the catalog configuration in its prompt or system instructions. | ||
|
|
||
| ## More Examples |
There was a problem hiding this comment.
i don't think we need a heading here... YouTube and Maps are both examples of adding custom components
| }; | ||
| ``` | ||
|
|
||
| The `DEFAULT_CATALOG` includes all standard A2UI components: Text, Button, TextField, Image, Card, Row, Column, Tabs, Modal, Slider, CheckBox, MultipleChoice, DateTimeInput, Divider, Icon, Video, and AudioPlayer. |
There was a problem hiding this comment.
Add suffix that the basic components are entirely optional if your design system supports A2UI you can expose only your own components, or a mix of basic and custom components
| // ... your existing providers (Material, Router, etc.) | ||
| configureChatCanvasFeatures( | ||
| usingA2aService(MyA2aService), | ||
| usingA2uiRenderers(DEFAULT_CATALOG, theme), |
There was a problem hiding this comment.
not DEFAULT, but custom from material
| @@ -0,0 +1,121 @@ | |||
| # Friction Log: Adding Custom Components to A2UI | |||
There was a problem hiding this comment.
this shouldn't be a file in this PR and should instead be it's own issue. remove
| const id = this.resolvedVideoId(); | ||
| if (!id) return null; | ||
| const autoplay = this.resolvedAutoplay() ? '1' : '0'; | ||
| const url = `https://www.youtube.com/embed/${encodeURIComponent(id)}?autoplay=${autoplay}&rel=0`; | ||
| return this.sanitizer.bypassSecurityTrustResourceUrl(url); |
There was a problem hiding this comment.
sure, we should do this
- Remove friction log file (content already in issue google#825) - YouTube component: add video ID regex validation (security) - custom-components.md: rename to 'Custom Component Catalogs', reorder examples (media first), clarify basic catalog is optional, remove redundant heading, fix Maps input.required consistency, add encodeURIComponent to docs example - design-system-integration.md: rewrite to focus on wrapping Material components as A2UI components (not using DEFAULT_CATALOG), show custom catalog without basic components, add mixed catalog example - s/standard/basic/ throughout
| import { Catalog } from '@a2ui/angular'; | ||
| import { inputBinding } from '@angular/core'; | ||
|
|
||
| // No DEFAULT_CATALOG spread — your Material components ARE the catalog |
There was a problem hiding this comment.
Comment for reviewer --- we should probably make this easier for developers
1 participant
What
Two new developer guides and a sample component for the most common A2UI onboarding paths:
Guide 1: Design System Integration
docs/guides/design-system-integration.mdStep-by-step guide for adding A2UI to an existing Angular Material application. Covers:
Guide 2: Custom Components (rewritten)
docs/guides/custom-components.mdComplete rewrite replacing the TODO skeleton. Covers:
New Sample Component
samples/client/angular/projects/rizzcharts/src/a2ui-catalog/youtube.tsYouTube embed as a custom A2UI component:
DomSanitizerfor safe iframe URLsvideoId,title,autoplaypropertiesFriction Log
docs/guides/friction-log-custom-components.md8 friction points encountered during development:
resolvePrimitive()undocumentedTODO (before removing draft)
ng build rizzcharts