Skip to content

fix(lit): align basic catalog component behaviors with angular implementation - #2205

Draft
josemontespg wants to merge 2 commits into
lit-light-dom-migrationfrom
lit-align-angular-behaviors
Draft

fix(lit): align basic catalog component behaviors with angular implementation#2205
josemontespg wants to merge 2 commits into
lit-light-dom-migrationfrom
lit-align-angular-behaviors

Conversation

@josemontespg

@josemontespg josemontespg commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Overview

Aligns the @a2ui/lit Basic Catalog component implementations, styling contracts, and lifecycle behaviors with the @a2ui/angular reference implementation.

Motivation & Architectural Rationale

This PR is a foundational step in our cross-framework rendering architecture:

  1. Prerequisite for Universal Components (@a2ui/web_core):
    In the subsequent PRs of this stack, the Basic Catalog implementations will be extracted into unified, universal Web Components hosted in @a2ui/web_core and shared directly across @a2ui/lit, @a2ui/angular, and upcoming renderers (such as React). To ensure this migration produces zero behavioral drift or visual regressions, all renderers must first converge on a canonical DOM structure, CSS variable contract, and event model.

  2. Adopting the More Complete Reference Behaviors:
    Prior to this change, minor behavioral divergence existed between renderers where the Angular implementation provided a more robust and spec-complete contract:

    • Comprehensive Form Validation (TextField): The A2UI protocol specifies validationErrors as a string array (string[]). Angular renders all accumulated validation errors for the field, whereas Lit previously truncated output to validationErrors[0].
    • Cross-Platform Layout Distribution (Column): Angular columns define width: 100% on the flex container host to ensure consistent full-width item stretching across different nesting depths and container types.
    • Natural Media Sizing (Image): Removing forced width: 100% allows images to preserve intrinsic aspect ratios and respect explicit layout constraints without unintended stretching.
    • Consistent Dialog Lifecycle & Styling (Modal): Angular's modal architecture utilizes explicit boolean state tracking (isOpen) and standard overlay CSS classes/custom properties (.a2ui-modal-overlay, .a2ui-modal-content, --a2ui-modal-backdrop-bg). Aligning Lit to this pattern unifies CSS theming tokens and guarantees consistent event propagation and backdrop click handling across frameworks.
    • Semantic Typography (Text): Wrapping variant: 'caption' in <em> ensures captions render with standardized italic typography out of the box.

Changes Made

  • TextField: Renders all error strings in props.validationErrors instead of only the first index.
  • Column: Adds width: 100% to :host, a2ui-basic-column styles.
  • Image: Removes width: 100% from default img styling to prevent unwanted stretching.
  • Modal: Adopts explicit @state() accessor isOpen = false; state tracking and .a2ui-modal-overlay / .a2ui-modal-content DOM hierarchy.
  • Text: Wraps variant: 'caption' rendered markdown in <em> elements.
  • Tests: Updates component unit tests and explorer integration tests to verify these aligned behaviors.

Resolves #1270

@github-project-automation github-project-automation Bot moved this to Todo in A2UI Aug 7, 2026
@josemontespg
josemontespg marked this pull request as draft August 7, 2026 20:43

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request refactors the A2uiLitModal component to replace the native HTML <dialog> element with a custom overlay structure managed by Lit state, updating corresponding tests and the changelog. The review feedback focuses on enhancing the accessibility and layout of the new modal implementation, including adding keyboard navigation support to the trigger, using inset: 0 on the overlay to prevent layout issues, and adding proper ARIA roles and labels to the modal container and close button.

Comment thread renderers/lit/src/v0_9/catalogs/basic/components/Modal.ts
Comment thread renderers/lit/src/v0_9/catalogs/basic/components/Modal.ts
Comment thread renderers/lit/src/v0_9/catalogs/basic/components/Modal.ts Outdated
Comment thread renderers/lit/src/v0_9/catalogs/basic/components/Modal.ts Outdated
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from b3b3f3a to d86413c Compare August 7, 2026 20:54
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch 2 times, most recently from 0da145e to af9200b Compare August 7, 2026 21:52
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch 4 times, most recently from 551ff67 to fbeb8c4 Compare August 7, 2026 22:27
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch 2 times, most recently from ebab296 to b744832 Compare August 7, 2026 22:36
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from b744832 to 13f5e98 Compare August 12, 2026 17:23
@josemontespg
josemontespg marked this pull request as ready for review August 12, 2026 17:47
@sugoi-yuzuru
sugoi-yuzuru force-pushed the lit-align-angular-behaviors branch from 13f5e98 to ebe3294 Compare August 12, 2026 19:44
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from ebe3294 to 13f5e98 Compare August 12, 2026 20:38
@josemontespg
josemontespg marked this pull request as draft August 12, 2026 20:47
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from 13f5e98 to 8d19fdc Compare August 13, 2026 19:02
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from 8d19fdc to 9de4b2d Compare August 14, 2026 19:17
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch 2 times, most recently from 59dfe71 to 4d63c36 Compare August 17, 2026 19:33
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from 4d63c36 to 5d5c7d6 Compare August 17, 2026 20:31
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch 2 times, most recently from 56d2ad9 to a8faffb Compare August 17, 2026 20:57
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from a8faffb to a341911 Compare August 17, 2026 21:27
…entation

Aligns the @a2ui/lit Basic Catalog component implementations, styling
contracts, and lifecycle behaviors with the @a2ui/angular reference
implementation in preparation for extracting universal web components.

Architectural Rationale:
- Prerequisite for universal components in @a2ui/web_core: Both renderers
  must converge on identical DOM hierarchies, styling variables, and event
  lifecycles prior to consolidating implementations in PR 3.
- TextField: Renders all messages in validationErrors rather than truncating
  to validationErrors[0], matching protocol spec and Angular behavior.
- Column: Sets container width to 100% to ensure standard flex layout
  distribution across varying container nesting.
- Image: Removes default width: 100% constraint to preserve natural aspect
  ratios and allow explicit sizing constraints.
- Modal: Migrates to explicit isOpen state tracking and .a2ui-modal-overlay
  structure for consistent dialog lifecycle and theming tokens.
- Text: Wraps caption variant in <em> for standard italic styling.
@josemontespg
josemontespg force-pushed the lit-align-angular-behaviors branch from a341911 to f1a2386 Compare August 18, 2026 21:35
* theme changes by injecting the selected color into the message stream.
* In a standard A2UI renderer deployment, this is not needed as the renderer
* simply processes messages as received from the agent, which is responsible
* for providing the correct theme.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't remove this jsdoc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support "portable A2UI web Components" which can be installed in a Catalog for *any* framework adapter

1 participant