Repository navigation
feat(ecc-utils-design): attribute forwarding - #523
salihudickson wants to merge 7 commits into
Conversation
Reviewer's GuideData structuresIntroduce the shared controller and root-scoped state for forwarding host attributes and resolving ARIA ID references across shadow boundaries.
ImplementationConnect input and textarea components to the forwarding controller, including their supported native-attribute allowlists.
Request trigger updates when the collapsible's open state changes so aria-expanded stays synchronized.
ConfigurationAdd the accessibility API and test-runner plugin dependencies needed by the new forwarding tests.
TestsAdd broad coverage for forwarding attributes and ARIA references, including accessibility snapshots, fallback behavior, and lifecycle changes.
Verify collapsible trigger aria-expanded follows open-state transitions.
Use a synchronous fixture in the existing no-select test to avoid awaiting fixture setup.
Lock files and vendored codeUpdate the dependency lockfile to record the package changes.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## dev #523 +/- ##
==========================================
+ Coverage 75.31% 76.39% +1.08%
==========================================
Files 37 44 +7
Lines 9138 9932 +794
Branches 470 542 +72
==========================================
+ Hits 6882 7588 +706
- Misses 2245 2332 +87
- Partials 11 12 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
🟡 Changes recommended
Forwarded ARIA references do not resolve external labels or error descriptions across the shadow boundary, and forwarded attributes can remain stale after changes made while a component is detached.
2 open issues
What changed in this PR
This PR addresses issue #511 by adding attribute forwarding to the design package’s input controls and synchronizing collapsible trigger accessibility state.
Changes:
- Add a reusable controller to forward ARIA and allow-listed native attributes to internal inputs and textareas.
- Request trigger updates when a collapsible’s open state changes.
- Add tests for attribute forwarding, updates, removals, and
aria-expandedtoggling.
| File | Description |
|---|---|
packages/ecc-utils-design/src/components/textarea/textarea.ts |
Enable attribute forwarding for the internal textarea. |
packages/ecc-utils-design/src/components/input/input.ts |
Enable attribute forwarding for the internal input. |
packages/ecc-utils-design/src/components/input/input.test.ts |
Test forwarding behavior for both controls. |
packages/ecc-utils-design/src/components/collapsible/collapsible.ts |
Refresh triggers when the open state changes. |
packages/ecc-utils-design/src/components/collapsible/collapsible.test.ts |
Test trigger aria-expanded synchronization. |
packages/ecc-utils-design/src/attribute-forwarding.ts |
Implement shared attribute observation and synchronization. |
Review effort: Balanced
bae9690 to
57c077b
Compare
There was a problem hiding this comment.
Hey - I've found 8 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="packages/ecc-utils-design/package.json" line_range="61" />
<code_context>
"@web/dev-server": "*",
"@web/dev-server-esbuild": "^0.4.3",
"@web/test-runner": "^1.0.0",
+ "@web/test-runner-commands": "*",
"commander": "*",
"concurrently": "*",
</code_context>
<issue_to_address>
**Clean installs reject the dependency change**
When CI or a deployment runs `npm ci` from this revision, `npm ci` finds `@web/test-runner-commands` in the workspace manifest but not in the matching `packages/ecc-utils-design` entry in `package-lock.json`, so the clean install fails before tests or builds can run.
Regenerate and commit `package-lock.json` with the new workspace dependency.
</issue_to_address>
### Comment 2
<location path="packages/ecc-utils-design/src/components/input/input.ts" line_range="44" />
<code_context>
@property({ type: Boolean, reflect: true }) disabled = false;
+ private _aria = new AttrForwardingController(this, "input", [
+ "name",
+ "required",
+ "readonly",
</code_context>
<issue_to_address>
**Form values are omitted**
When a form submits one of these custom controls with a forwarded `name`, the forwarded `name` lands on a native control inside the component’s shadow root, but the custom-element host is not form-associated. The outer form therefore omits the control from its submitted data, so callers receive no value for that field.
Make the custom elements form-associated and submit their values through `ElementInternals`, or otherwise provide a form-participating control.
Also at `packages/ecc-utils-design/src/components/textarea/textarea.ts:27-35`.
</issue_to_address>
### Comment 3
<location path="packages/ecc-utils-design/src/attribute-forwarding.ts" line_range="6-9" />
<code_context>
+type Host = ReactiveControllerHost & HTMLElement;
+
+// ID references can't cross the shadow boundary, so they are resolved separately.
+const IDREFS: Record<string, string> = {
+ "aria-describedby": "ariaDescribedByElements",
+ "aria-labelledby": "ariaLabelledByElements",
+};
+
+export class AttrForwardingController implements ReactiveController {
</code_context>
<issue_to_address>
**Other ARIA references break**
When a host uses an ARIA ID-reference attribute other than `aria-describedby` or `aria-labelledby` to refer to an element outside the component's shadow root, `aria-controls`, `aria-errormessage`, and other ARIA ID-reference attributes are forwarded unchanged to the shadow-local control, but their IDs point outside its shadow root, so the referenced relationship is lost to assistive technology.
Resolve and forward all supported ARIA ID-reference attributes across the shadow boundary, or avoid forwarding unsupported reference attributes to the inner control.
Also at `packages/ecc-utils-design/src/attribute-forwarding.ts:29-32`.
</issue_to_address>
### Comment 4
<location path="packages/ecc-utils-design/src/attribute-forwarding.ts" line_range="36-37" />
<code_context>
+ }
+
+ hostConnected() {
+ this.observer = new MutationObserver(() => this.sync());
+ this.observer.observe(this.host, { attributes: true });
+ }
+
</code_context>
<issue_to_address>
**Late references stay unresolved**
When a referenced label or description is inserted, replaced, removed, or has its ID changed after the host synchronizes, `syncReferences` resolves IDs only during `sync()`, and the observers watch only the host and elements already resolved. No root mutation reruns synchronization, so the inner control keeps a missing or stale accessible name or description.
Observe the host’s root for reference insertions, removals, and ID changes, and rerun `sync()` when they occur.
Also at `packages/ecc-utils-design/src/attribute-forwarding.ts:71-83`, `packages/ecc-utils-design/src/attribute-forwarding.ts:100-104`.
</issue_to_address>
### Comment 5
<location path="packages/ecc-utils-design/src/attribute-forwarding.ts" line_range="71-81" />
<code_context>
+ }
+
+ private syncReferences(target: Element) {
+ const root = this.host.getRootNode() as Document | ShadowRoot;
+ const shadow = this.host.shadowRoot as ShadowRoot;
+
+ // disconnect stale observers
+ this.refObserver.disconnect();
+
+ Object.entries(IDREFS).forEach(([attr, prop]) => {
+ const refs = (this.host.getAttribute(attr) ?? "")
+ .split(/\s+/)
+ .filter(Boolean)
+ .map((id) => root.getElementById(id))
+ .filter((el): el is HTMLElement => el !== null);
+
</code_context>
<issue_to_address>
**Detached updates throw**
When a component is updated after it has been connected and then removed from the document, `host.getRootNode()` returns the host itself when it is detached, which has no `getElementById`; `syncReferences` then throws while a post-disconnection reactive update runs, causing that update to fail.
Guard reference resolution when the host is disconnected or its root does not provide `getElementById`.
</issue_to_address>
### Comment 6
<location path="packages/ecc-utils-design/src/attribute-forwarding.ts" line_range="85" />
<code_context>
+ .filter((el): el is HTMLElement => el !== null);
+
+ if (prop in target) {
+ Reflect.set(target, prop, refs.length ? refs : null);
+ return;
+ }
</code_context>
<issue_to_address>
**Unlabelled controls fail to update**
When a control without an `aria-labelledby` or `aria-describedby` reference runs in a browser where the corresponding element-reference property exists, `ariaLabelledByElements` and `ariaDescribedByElements` accept element lists, not `null`, so `Reflect.set` throws a `TypeError` when either reference list is empty and the target supports the property; the controller's `hostUpdated` then fails and the control does not complete its update.
Pass an empty array instead of `null` when clearing either element-reference property.
</issue_to_address>
### Comment 7
<location path="packages/ecc-utils-design/src/attribute-forwarding.ts" line_range="29-32" />
<code_context>
+ host.addController(this);
+ }
+
+ private isForwarded(name: string) {
+ return (
+ !(name in IDREFS) && (name.startsWith("aria-") || this.extra.has(name))
+ );
+ }
+
</code_context>
<issue_to_address>
**Existing labels stay disconnected**
When consumers use the existing label `for` and host `id` pattern, `isForwarded` excludes `id`, so labels using the repository’s existing `for="..."` pattern still point at the custom-element host rather than its inner input or textarea. Native labels do not associate with these non-labelable hosts across the shadow boundary, leaving the controls without the label’s accessible name or click-to-focus behavior.
Bridge the host ID to the inner control’s accessible labeling, or update the label/control association pattern so it works across the shadow boundary.
</issue_to_address>
### Comment 8
<location path="packages/ecc-utils-design/src/attribute-forwarding.ts" line_range="99" />
<code_context>
+ node.hidden = true;
+ shadow.append(node);
+ }
+ node.textContent = ref.textContent;
+ this.refObserver.observe(ref, {
+ characterData: true,
</code_context>
<issue_to_address>
**Fallback loses accessible text**
When the target lacks the element-reference property and a referenced element gets its accessible name or description from something other than its text content, the fallback copies only `ref.textContent`, so it omits text supplied by `aria-label`, image `alt`, or similar semantics. The inner control therefore gets a different or missing label or description.
Populate the fallback from the referenced element’s accessible text, including its non-text sources.
</issue_to_address>Linked issues
#511 fix(design): forward aria attributes to inputs · 4 of 4 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Forward aria-* attributes, including aria-invalid, aria-describedby, aria-label, and aria-required, from input-like component hosts to their inner controls. | ✅ Met | The controller is used by both input and textarea; it forwards ARIA attributes and resolves aria-labelledby and aria-describedby references across the shadow boundary. |
| 2 | Keep aria-expanded on the collapsible trigger in sync with its state. | ✅ Met | The collapsible requests an update on its trigger when open changes, and the trigger renders aria-expanded from the parent’s open state. |
| 3 | Add tests showing forwarded attributes on inner inputs and aria-expanded toggling. | ✅ Met | The added tests cover ARIA forwarding and external references for input and textarea, and verify aria-expanded changes with the collapsible state. |
| 4 | Make no public API changes other than the forwarding. | ✅ Met | The change adds internal forwarding behavior without changing the components’ public API. |
Sourcery assessment
Approval pending. 8 findings to address first.
Blocking findings: packages/ecc-utils-design/package.json:61, packages/ecc-utils-design/src/components/input/input.ts:44, packages/ecc-utils-design/src/attribute-forwarding.ts:9, packages/ecc-utils-design/src/attribute-forwarding.ts:37, packages/ecc-utils-design/src/attribute-forwarding.ts:81, and 3 more
|
Nice work on this! The forwarding approach and collapsible fix look good. I reproduced a few edge cases in Chromium that we should address:
Please add tests for these cases. Also, I couldn’t reproduce the bot’s warning about assigning |
|
@salihudickson Thanks a lot for this! However, this is becoming blocking for @AnonymousXC's work. Can you please give an ETA of when you think by when you'd be able address the issues raised by @anuragxxd, as well as the ones raised by Sourcery AI so that we get this over the line? Alternatively, you can give me permission to ask Claude to fix these issues. |
|
@uniqueg, I just have one more issue to workout. This one: Sorry for the delay. |
Linked issuesChecked at commit 7b07eeb #511 fix(design): forward aria attributes to inputs · 4 of 4 met
|
e453ac9 to
951a650
Compare
Documentation build overview
51 files changed ·
|
|
@anuragxxd, @uniqueg, I have addressed the pending issues. Please re-review. |
uniqueg
left a comment
There was a problem hiding this comment.
Thanks a lot @salihudickson, the controller handles a lot of edge cases, and the collapsible fix is good. A few things before this can go in:
-
Merge
devand integrate with #576. Since this branch was last updated, #576 addedinvalidanderrorproperties toecc-utils-design-inputand-textarea. They renderaria-invalidandaria-describedby="error"on the inner control, which overlaps directly with this PR (andinput.ts/textarea.tswill conflict). After merging, please make the two work together, with tests:- A host
aria-describedbyshould be added to the component's ownerrorreference, not replace it, so that both the consumer's description and the built-in error message are announced. SettingariaDescribedByElementsreplaces the reference (and, in Chromium, clears the content attribute that Lit set toerror). - Define what wins when the host's
aria-invalidand theinvalid/errorproperties disagree. I'd suggest that the control is invalid if either says so.
- A host
-
Removing an ID-reference attribute leaves the old reference. In
syncReferences, when the host attribute is gone (value === null), only the mirror nodes are removed. In the element-reference path (prop in target, which Chromium takes),target.ariaDescribedByElements(etc.) keeps the old elements. Please reset the property, and add a test that removesaria-describedbyfrom the host. -
name(andrequiredfor form validation) don't reach forms. The components aren't form-associated, so attributes on the native control inside the shadow root don't take part in a surrounding<form>.required,readonlyand the length limits still help assistive technology and:invalidstyling, so they're fine. But please either dropnameor state in the docs that it has no effect on form submission until the components useElementInternals. -
Changeset and docs. Please add a changeset (
.changeset/*.md, as the other design PRs do) and document which attributes are forwarded, wherever the components are documented. -
services.test.ts. The switch fromfixturetofixtureSyncin the service registry package looks unrelated. What does it fix? If it's a flaky test, please say so in the description. -
PR description. The body is still the template. Please fill in the Summary, Verification and Declined review findings sections.
-
Minor:
- Typo "sttributes" in a comment.
- One
MutationObserverper root watches the whole subtree, and every mutation re-syncs every registered controller (includingcomputeAccessibleNamein the fallback). That's fine for now, but batching to one sync per microtask would keep large pages cheap.
Covering select/multi-select too can be a follow-up issue; input and textarea are enough for this PR.

Summary
Closes #511
Verification
Declined review findings
Open questions
Checklist
pass.
Commits (at most 50 characters,
imperative mood, no trailing period).
Summary by Sourcery
Implement robust attribute and accessibility relationship forwarding for design-system form controls and keep collapsible trigger state synchronized.
New Features:
Bug Fixes:
Enhancements:
Build:
Tests: