docs: restructure navigation, add v0.8/v0.9 content tabs, ecosystem renderers#769
docs: restructure navigation, add v0.8/v0.9 content tabs, ecosystem renderers#769zeroasterisk wants to merge 18 commits intogoogle:mainfrom
Conversation
- surfaceUpdate vs updateComponents with schema/example differences - dataModelUpdate vs updateDataModel (typed contents vs JSON Pointer) - deleteSurface tabs (identical structure, v0.9 adds version field) - Validation section split by version
…tions - React added as v0.8-only stable renderer - Flutter/Lit/Angular show v0.9 support - New 'Component Catalogs' section explaining flexibility - New 'Shared Web Library' section about @a2ui/web-lib foundation - Both renderers.md and client-setup.md updated consistently
- catalogId is REQUIRED in createSurface (not optional)
- usageHint → variant in v0.9 Text component
- Data binding is {"path": ...} not {"$data": ...}
- updateDataModel: path and value are both OPTIONAL
- v0.9 requires id="root" component (convention, not message field)
- Omitting value in updateDataModel = delete semantics
Human-readable formatting across all pages with content tabs: - concepts/data-flow.md (message format + restaurant booking lifecycle) - concepts/components.md (adjacency list, component basics, children) - concepts/data-binding.md (literal vs path, dynamic lists, best practices) - introduction/what-is-a2ui.md (booking example) - reference/messages.md (beginRendering, createSurface, deleteSurface, ordering)
- createSurface had invalid 'root' property (v0.8 concept) - surfaceUpdate with nested component format → updateComponents with flat format - Added version field to all messages
- Catalogs, Transports, Client-to-Server Actions → Concepts - Renderers, Agents → Reference - How Can I Use It? → Getting Started - Ecosystem now focused on community: Agent UI Ecosystem, Where Used, Community - Redirects plugin configured for future file moves - Concepts before Guides (learn concepts, then follow guides)
- Every component now has v0.8 and v0.9 examples side by side - Fixed 'Standard Catalog' → 'Basic Catalog' for v0.9 - Added missing components: Slider, DateTimeInput, ChoicePicker - Noted MultipleChoice → ChoicePicker rename in v0.9 - All JSON properly formatted with indentation - Nav: renamed 'Component Reference' to 'Component Gallery'
- Shared descriptions, properties, and prose OUTSIDE tabs - Only JSON code blocks are tabbed - Same property names shown, noting version differences inline - Added version differences summary table - Consistent formatting between versions
…xamples - Properties list moved back inside tabs to show version-specific names - JSON schema links wrapped in admonition with :material-code-json: icon - v0.8/v0.9 examples kept structurally parallel (same properties, same order) - Added layout alignment rename (distribution/alignment → justify/align) - Added action format and TextField value rename to summary table - Image example expanded to show fit + variant/usageHint
- Merge status into v0.8/v0.9 columns, remove separate Status column - Rename 'Available Renderers' → 'Maintained Renderers' - Add Planned Q2 to SwiftUI/Jetpack Compose v0.9 columns - Add Ecosystem Renderers section with TODO for community renderers - Add ecosystem/renderers.md page and nav entry
- Remove community React renderers (covered in ecosystem page) - Add Vercel json-render as top ecosystem highlight - Keep Android and React Native community renderers
zeroasterisk
requested review from
ava-cassiopeia,
ditman,
dmandar,
gspencergoog,
jacobsimionato,
nan-yu,
paullewis and
yjbanov
as code owners
|
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 is a significant and valuable update to the documentation, restructuring the navigation and adding versioned content tabs to clarify the differences between A2UI v0.8 and v0.9. The introduction of a new v0.9 JSON schema, along with conformance tests and Storybook examples, is a great step forward. My review focuses on a few potential issues: an incorrect enum value in the new JSON schema, a broken file path in a test script, an unreleased package version in the new package.json files, and a couple of minor code quality suggestions.
Note: Security Review did not run due to the size of the PR.
| const repoRoot = join(__dirname, '../..'); | ||
|
|
||
| // 1. Get spec components from standard_catalog.json | ||
| const catalog = JSON.parse(readFileSync(join(repoRoot, 'specification/v0_10/json/standard_catalog.json'), 'utf8')); |
There was a problem hiding this comment.
This script is hardcoded to read from specification/v0_10/json/standard_catalog.json, but this pull request focuses on v0.9. This path seems incorrect as the v0.10 file does not exist in this PR, which will likely cause the script to fail. It should probably point to the v0.9 catalog file instead.
| console.log('╠══════════════════╬═════════╬═════════╬═══════════╬═════════╣'); | ||
|
|
||
| const allComponents = [...new Set([...specComponents, ...litComponents, ...angularComponents])].sort(); | ||
| let missingFromSpec = []; |
There was a problem hiding this comment.
The variable missingFromSpec is declared but never used. It seems like it was intended for tracking components present in renderers but not in the spec. Consider either using it or removing it to improve code clarity.
1 participant
Summary
Alternative approach to #622 for updating docs to cover both v0.8 and v0.9 — using content tabs instead of duplicating entire pages per version.
🔗 Live Preview: a2ui-docs.pages.dev
Approach
Instead of maintaining separate v0.8 and v0.9 copies of each doc page, this PR uses pymdownx content tabs (
=== "v0.8"/=== "v0.9") for version-specific examples while keeping shared concepts, guides, and reference material in single pages.Why? Less duplication, easier maintenance, readers see both versions side-by-side and can compare.
Changes
Navigation restructure:
Content tabs (v0.8 / v0.9):
Schema accuracy (validated against
specification/v0_9/json/):catalogIdis REQUIRED in v0.9createSurfaceusageHint→variantin v0.9 Text component{"path": ...}not{"$data": ...}updateDataModel: onlysurfaceIdis requiredchildren: [...]format (notchildren: {explicitList: [...]})Renderer pages:
Other:
Relation to #622
This PR takes a different approach to the same problem. #622 duplicates pages per version; this PR uses inline content tabs. Both are valid — happy to discuss which direction the team prefers.