Skip to content

feat(config): allow suppressing reserved public name warning#6389

Merged
johnjenkins merged 3 commits intostenciljs:mainfrom
deleonio:feature/add-config-option-to-disable-build-warnings
Sep 23, 2025
Merged

feat(config): allow suppressing reserved public name warning#6389
johnjenkins merged 3 commits intostenciljs:mainfrom
deleonio:feature/add-config-option-to-disable-build-warnings

Conversation

@deleonio
Copy link
Copy Markdown
Contributor

@deleonio deleonio commented Sep 19, 2025 •
edited
Loading

What is the current behavior?

Currently, our accessible WebComponents provide atomic building blocks (e.g., input, button, link) but without full propagation of the native public API from the underlying HTML element.
This limits seamless interoperability with other frameworks and libraries, as not all native methods and properties are exposed through the WebComponent.

GitHub Issue Number: N/A

What is the new behavior?

  • Introduces an optional configuration that enables full propagation of the native public API of the primary interactive element (e.g., input, button, a) inside the Shadow DOM.
  • This makes the accessible WebComponent effectively a 1:1 API representation of the native HTML element.
  • Benefits:
    • Maximum reusability and interoperability with any framework or library.
    • Native methods such as focus(), blur(), checkValidity(), etc., become directly accessible.
    • Ensures seamless integration with existing patterns that rely on standard HTML5 APIs.
  • The new configuration is optional and backwards compatible — existing implementations remain unaffected.

Documentation

  • Updated developer documentation with instructions on how to enable and use the new configuration.
  • Added examples for input and button components with API propagation.

Does this introduce a breaking change?

  • Yes
  • No

Testing

  • Unit Tests:
    • Verified that native methods (focus, blur, checkValidity) are correctly available on the WebComponent.
    • Confirmed that the option is disabled by default to preserve backward compatibility.
  • Integration Tests:
    • Validated usage in React and Vue setups to ensure API compatibility.
    • Accessibility tests with screen readers to confirm correct label and tooltip propagation.
  • Manual Tests:
    • Compared input and button components with the option enabled and disabled.
    • Cross-browser validation (Chrome, Firefox, Safari, Edge).

Other information

  • Developer Tools inspection screenshots demonstrate that native properties and methods are directly callable.

@deleonio deleonio marked this pull request as ready for review September 19, 2025 18:26
@deleonio deleonio requested a review from a team as a code owner September 19, 2025 18:26
@johnjenkins
Copy link
Copy Markdown
Contributor

johnjenkins commented Sep 19, 2025

hey @deleonio - thanks for your work on this!
Can you do me a favour and add a few tests against this to src/compiler/config/test/validate-config.spec.ts - thanks!

@deleonio deleonio marked this pull request as draft September 22, 2025 21:43
@deleonio deleonio marked this pull request as ready for review September 22, 2025 21:44
johnjenkins
johnjenkins approved these changes Sep 23, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@johnjenkins johnjenkins left a comment

Choose a reason for hiding this comment

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

LGTM!

@johnjenkins johnjenkins added this pull request to the merge queue Sep 23, 2025
Merged via the queue into stenciljs:main with commit 341fec4 Sep 23, 2025
69 checks passed
@johnjenkins johnjenkins mentioned this pull request Sep 23, 2025
Closed
@danielleroux
Copy link
Copy Markdown
Contributor

danielleroux commented Oct 6, 2025 •
edited
Loading

@johnjenkins @deleonio

Hey folks, just checked the latest release a found this PR which makes it possible to define "suppressing reserved public name". In general I do like the idea but it feels a little bit strange if I have classic extending in mind.

without stencil:

class MyComponent extends HTMLElement {
 
    override focus(): void {
        // do your focus logic in sync!        
    }

}

stencil:

class MyComponent {
   
   @Method() // @Method must be async https://stenciljs.com/docs/methods#public-methods-must-be-async
   async focus(): Promise<void> {
         // do your focus logic async
   }
}

We see we have changed the signature of focus from focus(): void => focus(): Promise<void>. So we make focus async and a "user" of my-component will not know if the project is build with the suppress flag and maybe expect that focus is executed sync.

Anybody thoughts on this point?

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

Reviewers

@johnjenkins johnjenkins johnjenkins approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@deleonio @johnjenkins @danielleroux