docs: add Lit custom component registration guide for v0.9 and v0.8#1428
docs: add Lit custom component registration guide for v0.9 and v0.8#1428shahabl wants to merge 4 commits into
Conversation
Document how to register custom components with the Lit renderer in both protocol versions. The v0.9 path (Catalog + MessageProcessor + catalogId) is documented as the primary approach. The v0.8 path (componentRegistry + enableCustomElements) is documented as legacy. The enableCustomElements property on Surface was easy to discover as a footgun — custom components silently don't render if the flag is not set before the surface/processor properties.
![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 updates the 'authoring-components.md' guide to include instructions for registering components with the Lit Renderer, covering both the recommended v0.9 protocol and the legacy v0.8 protocol. The review feedback suggests several improvements to the documentation's code snippets, including removing an unused import and adding clarifying comments for variables that are referenced but not defined within the examples.
- Remove unused A2uiLitElement import from v0.9 snippet - Add clarifying comment that MyChartElement is the user's Lit component class - Add inline comments for surface and processor variables in v0.8 snippet
Add a '### Angular renderer' subheading so that the registration section has a symmetric three-subsection structure as suggested by @ditman. The Lit subsections are promoted from level-4 (####) to level-3 (###) to match, and the section heading is updated to the plural 'Renderers'. A one-sentence intro is added to the section.
ditman
left a comment
ditman
left a comment
There was a problem hiding this comment.
This is looking great! Can you extend the Lit v0.9 a little bit to demonstrate how the message processor is used? Also other small comments.
Thanks again for your contribution!
| // 3. Register it with the MessageProcessor alongside any other catalogs you support | ||
| const processor = new MessageProcessor<LitComponentApi>([basicCatalog, myCatalog]); |
There was a problem hiding this comment.
Can you add a "4." illustrating how the "processor" is used? I think that's the final piece of the puzzle.
|
|
||
| ### Lit v0.9 (recommended) | ||
|
|
||
| With `@a2ui/lit/v0_9`, catalog registration is handled at the protocol level. Define a `Catalog` object with your components and pass it to the `MessageProcessor`. When the agent sends a `createSurface` message with a matching `catalogId`, the processor automatically resolves and binds your catalog — no client-side flags required. |
There was a problem hiding this comment.
... no client-side flags required.
I think that bit was referencing the v0.8 "enableCustomElement", but now that this shows up earlier in the document I think it doesn't make sense.
|
|
||
| The `A2uiSurface` element in v0.9 receives a fully-resolved `SurfaceModel` (with catalog already bound), so custom components render automatically alongside standard ones. | ||
|
|
||
| ### Lit v0.8 (legacy) |
There was a problem hiding this comment.
I'm tempted to use the "tabs" widget that we have to hide the Lit v0.8 behind a tab, like we do here:
A2UI/docs/concepts/overview.md
Lines 29 to 50 in 0e03757
That way the page doesn't grow too tall, and you only see the things about the framework you care about; what do you think?
2 participants
Adds documentation for registering custom components with the
@a2ui/litrenderer, covering both protocol versions. This addresses a gap noted in
#506 — the original PR was
closed because its docs targeted a file that no longer exists in the
updated structure.
The new section is added to
docs/guides/authoring-components.mdunderstep 3 (Registering with the Renderer), as a Lit-specific counterpart to
the existing Angular example.
v0.9 (primary path): Define a
Catalogwith a Zod schema, pass itto
MessageProcessoralongside other supported catalogs, and let theagent select it via
createSurface.catalogId. No client-side flagsneeded.
v0.8 (legacy): Register components in
componentRegistry, then setenableCustomElements = trueon the<a2ui-surface>element beforeassigning
surfaceandprocessor. Without this flag the componentssilently don't render even if correctly registered — a footgun worth
calling out explicitly.
Pre-launch Checklist