Skip to content

feat(ecc-utils-design): attribute forwarding - #523

Open
salihudickson wants to merge 7 commits into
devfrom
feat/attr-forwarding
Open

salihudickson wants to merge 7 commits into
devfrom
feat/attr-forwarding

Conversation

@salihudickson

@salihudickson salihudickson commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #511

Verification

Declined review findings

Open questions

Checklist

  • Tests are added or updated where the change affects behaviour, and
    pass.
  • The documentation is updated where the change affects it.
  • The title follows Conventional
    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:

  • Add attribute forwarding for ARIA attributes, accessible relationships, and selected native form attributes from custom input and textarea elements to their internal controls.

Bug Fixes:

  • Keep forwarded attributes and accessibility relationships synchronized through host updates, DOM changes, detachment, reconnection, and reference replacement.
  • Ensure collapsible triggers update their aria-expanded state when the collapsible opens or closes.

Enhancements:

  • Provide shadow-DOM-aware handling for ID-based ARIA references, including accessible-text fallbacks when element reference properties are unavailable.

Build:

  • Add accessibility and attribute-forwarding runtime dependencies and test tooling.

Tests:

  • Add comprehensive input and textarea forwarding tests, including accessibility snapshot coverage and lifecycle edge cases.
  • Add collapsible trigger accessibility state coverage.
  • Use synchronous fixture setup for the affected service test.

@salihudickson
salihudickson requested a balanced review from Copilot October 31, 2026 22:19
@sourcery-ai

sourcery-ai Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Data structures

Introduce the shared controller and root-scoped state for forwarding host attributes and resolving ARIA ID references across shadow boundaries.

  • packages/ecc-utils-design/src/attribute-forwarding.ts L1-328

Implementation

Connect input and textarea components to the forwarding controller, including their supported native-attribute allowlists.

  • packages/ecc-utils-design/src/components/input/input.ts L6, L46-58
  • packages/ecc-utils-design/src/components/textarea/textarea.ts L6, L30-38

Request trigger updates when the collapsible's open state changes so aria-expanded stays synchronized.

  • packages/ecc-utils-design/src/components/collapsible/collapsible.ts L53-55

Configuration

Add the accessibility API and test-runner plugin dependencies needed by the new forwarding tests.

  • packages/ecc-utils-design/package.json L49, L62
  • web-test.runner-config.mjs L4, L39

Tests

Add broad coverage for forwarding attributes and ARIA references, including accessibility snapshots, fallback behavior, and lifecycle changes.

  • packages/ecc-utils-design/src/components/input/input.test.ts L1-502

Verify collapsible trigger aria-expanded follows open-state transitions.

  • packages/ecc-utils-design/src/components/collapsible/collapsible.test.ts L1-35

Use a synchronous fixture in the existing no-select test to avoid awaiting fixture setup.

  • packages/ecc-client-ga4gh-service-registry/src/components/services/tests/services.test.ts L2-8, L545

Lock files and vendored code

Update the dependency lockfile to record the package changes.

  • package-lock.json L12635-12640, L36730, L36743

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@salihudickson salihudickson changed the title attribute forwarding for input elements feat(ecc-utils-design): attribute forwarding for input elements Oct 31, 2026
@codecov

codecov Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.05634% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.39%. Comparing base (68ff6ea) to head (7b07eeb).

Files with missing lines Patch % Lines
...kages/ecc-utils-design/src/attribute-forwarding.ts 95.73% 13 Missing and 1 partial ⚠️
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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 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-expanded toggling.
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

@salihudickson salihudickson changed the title feat(ecc-utils-design): attribute forwarding for input elements feat(ecc-utils-design): attribute forwarding Nov 1, 2026
@salihudickson
salihudickson marked this pull request as ready for review November 1, 2026 14:28
@uniqueg uniqueg mentioned this pull request Nov 1, 2026
3 tasks

@sourcery-ai sourcery-ai 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.

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


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread packages/ecc-utils-design/package.json Resolved
@anuragxxd

Copy link
Copy Markdown
Member

Nice work on this! The forwarding approach and collapsible fix look good. I reproduced a few edge cases in Chromium that we should address:

  • Updating a detached control with aria-describedby throws root.getElementById is not a function. Please guard reference resolution while detached.
  • Changing attributes while detached leaves the inner input stale after reattaching. Calling sync() on reconnect should cover this.
  • Error messages inserted or replaced after rendering aren’t picked up by aria-describedby. Please handle changes to the referenced elements.
  • Other reference attributes, such as aria-errormessage, still get copied as plain IDs and don’t resolve across the shadow boundary.

Please add tests for these cases. Also, I couldn’t reproduce the bot’s warning about assigning null to the ARIA reference properties—it worked in Chromium.

@uniqueg

uniqueg commented Nov 14, 2026

Copy link
Copy Markdown
Member

@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.

@salihudickson

Copy link
Copy Markdown
Contributor Author

@uniqueg, I just have one more issue to workout. This one: Error messages inserted or replaced after rendering aren’t picked up by aria-describedby. I'm using AI to work through it so I should be able to get through it pretty quickly, I'm just not satisfied with the architecture as it's setup and I need to make some tweaks. I'll have it ready sometime tomorrow.

Sorry for the delay.

@sourcery-ai

sourcery-ai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Linked issues

Checked at commit 7b07eeb

#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, to the inner controls. ✅ Met The forwarding controller is used by both input and textarea, and the tests cover direct ARIA forwarding and cross-shadow-root relationships.
2 Keep aria-expanded on the collapsible trigger in sync with its state. ✅ Met The collapsible requests trigger updates when open changes, and the test checks both open and closed states.
3 Add tests showing forwarded attributes on inner inputs and aria-expanded toggling. ✅ Met Tests cover forwarded attributes for input and textarea and aria-expanded transitions for the collapsible trigger.
4 Make no public API changes other than forwarding. ✅ Met The forwarding controller is internal to the package’s source and is not added to its public exports.

@salihudickson

Copy link
Copy Markdown
Contributor Author

@anuragxxd, @uniqueg, I have addressed the pending issues. Please re-review.

@uniqueg uniqueg left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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:

  1. Merge dev and integrate with #576. Since this branch was last updated, #576 added invalid and error properties to ecc-utils-design-input and -textarea. They render aria-invalid and aria-describedby="error" on the inner control, which overlaps directly with this PR (and input.ts/textarea.ts will conflict). After merging, please make the two work together, with tests:

    • A host aria-describedby should be added to the component's own error reference, not replace it, so that both the consumer's description and the built-in error message are announced. Setting ariaDescribedByElements replaces the reference (and, in Chromium, clears the content attribute that Lit set to error).
    • Define what wins when the host's aria-invalid and the invalid/error properties disagree. I'd suggest that the control is invalid if either says so.
  2. 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 removes aria-describedby from the host.

  3. name (and required for 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, readonly and the length limits still help assistive technology and :invalid styling, so they're fine. But please either drop name or state in the docs that it has no effect on form submission until the components use ElementInternals.

  4. 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.

  5. services.test.ts. The switch from fixture to fixtureSync in the service registry package looks unrelated. What does it fix? If it's a flaky test, please say so in the description.

  6. PR description. The body is still the template. Please fill in the Summary, Verification and Declined review findings sections.

  7. Minor:

    • Typo "sttributes" in a comment.
    • One MutationObserver per root watches the whole subtree, and every mutation re-syncs every registered controller (including computeAccessibleName in 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.

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.

fix(design): forward aria attributes to inputs

4 participants