Skip to content

fix(web_core)!: namespace the basic catalog custom element tags - #2648

Draft
josemontespg wants to merge 1 commit into
web-core-tabs-controller-less-lifecyclefrom
web-core-namespace-basic-catalog-tags
Draft

josemontespg wants to merge 1 commit into
web-core-tabs-controller-less-lifecyclefrom
web-core-namespace-basic-catalog-tags

Conversation

@josemontespg

@josemontespg josemontespg commented Sep 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

Namespaces the 13 remaining basic catalog custom element tags to a2ui-basic-* (such as renaming a2ui-card to a2ui-basic-card). This completes the namespace migration for the basic catalog and prevents global custom element registration collisions.

Problem

Custom element tag names share a single global browser registry (window.customElements).

When an application imports @a2ui/web_core/v0_9/basic_catalog, components eagerly register their custom element tags. Thirteen components previously used short, un-namespaced tags like a2ui-card, a2ui-icon, a2ui-modal, and a2ui-audioplayer.

If a host application or another library on the page already registered an element with any of those names, the browser throws an error during module evaluation:

NotSupportedError: Failed to execute 'define' on 'CustomElementRegistry':
the name "a2ui-audioplayer" has already been used with this registry

Because registration occurs at import time, this error blocks the host application from loading.

Additionally, five basic catalog components (Text, Button, TextField, Row, and Column) had already been migrated to a2ui-basic-* in earlier releases. The remaining thirteen components were left un-namespaced, creating an inconsistent naming scheme across the catalog.

Solution

  • Rename the remaining 13 custom element tags to a2ui-basic-*:
    Both the @customElement decorator and the exported WebComponentImplementation.tagName are updated together across all 13 components:

    Old Tag New Tag
    a2ui-audioplayer a2ui-basic-audioplayer
    a2ui-card a2ui-basic-card
    a2ui-checkbox a2ui-basic-checkbox
    a2ui-choicepicker a2ui-basic-choicepicker
    a2ui-datetimeinput a2ui-basic-datetimeinput
    a2ui-divider a2ui-basic-divider
    a2ui-icon a2ui-basic-icon
    a2ui-image a2ui-basic-image
    a2ui-list a2ui-basic-list
    a2ui-modal a2ui-basic-modal
    a2ui-slider a2ui-basic-slider
    a2ui-tabs a2ui-basic-tabs
    a2ui-video a2ui-basic-video
  • Update CSS selectors and tests: Updates internal tag selectors in component stylesheets (a2ui-basic-card { ... }), component unit tests, and Lit explorer integration tests.

  • Enforce naming and type safety in tests: In catalog.test.ts, tests assert that every component in basicCatalog has a tagName prefixed with a2ui-basic- and resolves to an instanceof A2uiLitElement.

  • Add missing type annotations: Explicitly types A2uiModal and A2uiTextField with WebComponentImplementation to ensure compile-time verification of tagName.

  • Preserve CSS class names: CSS class names (such as .a2ui-card and .a2ui-icon) are intentionally left unchanged, preserving the shared styling and theming contract used across the Web Core, Lit, React, and Angular renderers.

Verification

  • yarn --cwd renderers/web_core test passes (563 tests).
  • Lit explorer integration suite passes (138 of 138 tests).
  • yarn --cwd renderers/lit test:unit, yarn --cwd renderers/react test, and full renderer topological build pass.

Pre-launch Checklist

@josemontespg
josemontespg added this pull request to stack #2649 September 14, 2026 19:14
@github-project-automation github-project-automation Bot moved this to Todo in A2UI Sep 14, 2026

@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 renames the custom element tag names in the basic catalog to use the a2ui-basic- prefix (e.g., renaming a2ui-icon to a2ui-basic-icon), updating the components, their tests, and the explorer tests accordingly. It also adds a test in catalog.test.ts to verify that all basic catalog components are registered and correctly namespaced. The review feedback suggests importing and applying the WebComponentImplementation type to the A2uiModal export in Modal.ts for consistency and type safety.

Comment thread renderers/web_core/src/v0_9/basic_catalog/components/Modal.ts
Comment thread renderers/web_core/src/v0_9/basic_catalog/components/Modal.ts Outdated
@josemontespg
josemontespg force-pushed the web-core-namespace-basic-catalog-tags branch from 30cd5b0 to 2f4b8cc Compare September 14, 2026 19:16
Comment thread renderers/web_core/src/v0_9/basic_catalog/components/Card.ts
Comment thread renderers/web_core/src/v0_9/basic_catalog/catalog.test.ts
@josemontespg
josemontespg removed this pull request from stack #2649 September 14, 2026 19:58
@josemontespg
josemontespg force-pushed the web-core-namespace-basic-catalog-tags branch from 2f4b8cc to bd68bc3 Compare September 14, 2026 20:01
@josemontespg
josemontespg added this pull request to stack #2654 September 14, 2026 20:02
@josemontespg
josemontespg removed this pull request from stack #2654 September 14, 2026 20:24
Importing the basic catalog registers 18 custom elements, and only 5 of them
were namespaced. The other 13 squatted short, generic names, so a host page that
already owned one — `a2ui-audioplayer`, say — took the application down at
module-evaluation time with `NotSupportedError: the name "a2ui-audioplayer" has
already been used with this registry`.

Rename the remaining 13 to `a2ui-basic-*`, finishing the migration. The
`@customElement` argument and the `WebComponentImplementation.tagName` move in
lockstep, because the catalog instantiates elements by `tagName` and a
decorator-only rename compiles cleanly and then fails in the browser; a new test
iterates the catalog and asserts every `tagName` resolves to a registered
element, which catches a partial rename.

CSS class names such as `.a2ui-card` are a separate contract shared with the
React and Angular basic catalogs and are left alone. Registration stays eager
and still throws on collision: now that the tags are namespaced, a remaining
`NotSupportedError` is a genuine duplicate-registration bug and should stay loud.

This branch has not been deployed

No deployments
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.

1 participant