diff --git a/exportid-explainer.md b/exportid-explainer.md index 6d8e194..2e01ea1 100644 --- a/exportid-explainer.md +++ b/exportid-explainer.md @@ -1,5 +1,5 @@ > [!CAUTION] -> The Export ID proposal is no longer planned. It has been replaced by the [Reference Target](reference-target-explainer.md) proposal. +> The Export ID proposal is no longer planned. It has been replaced by the [Reference Target](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/reference-target-explainer.md) proposal. # Exporting IDs from shadow roots for cross-root ARIA diff --git a/reference-target-explainer.md b/reference-target-explainer.md index 076e0dc..0733aba 100644 --- a/reference-target-explainer.md +++ b/reference-target-explainer.md @@ -1,608 +1,6 @@ # Reference Target for Cross-Root ARIA -Author: [Ben Howell](https://github.com/behowell) - -## Introduction - -Reference Target is a feature to enable using IDREF attributes such as `for` and `aria-labelledby` to refer to elements inside a component's shadow DOM, while maintaining encapsulation of the internal details of the shadow DOM. The main goal of this feature is to enable ARIA to work across shadow root boundaries. - -This proposal is based on [@Westbrook](https://github.com/Westbrook)'s [Cross-root ARIA Reflection API](https://github.com/Westbrook/cross-root-aria-reflection/blob/main/cross-root-aria-reflection.md) proposal, as well as borrowing ideas from [@alice](https://github.com/alice)'s [Semantic Delegate](https://github.com/alice/aom/blob/gh-pages/semantic-delegate.md) proposal. - -## Background - -### Cross-Root ARIA - -For an in-depth description the cross-root ARIA problem, see [@alice](https://github.com/alice)'s article [How Shadow DOM and accessibility are in conflict](https://alice.pages.igalia.com/blog/how-shadow-dom-and-accessibility-are-in-conflict/). The article describes the two main problems that need to be solved: - -#### 1. Referring from Shadow DOM outwards - -The existing [ARIAMixin IDL attributes](https://w3c.github.io/aria/#ARIAMixin) (such as `ariaLabelledbyElements` and `ariaActiveDescendantElement`) unlock part of the solution to the cross-root ARIA problem. They allow for an element inside a shadow DOM to create an ARIA link to an element outside that shadow DOM. However, they are limited in that they can't reference an element inside another component's shadow DOM. The specifics of this limitation are described in more detail in _How Shadow DOM and accessibility are in conflict_. - -#### 2. Referring into Shadow DOM - -The "missing piece" to solving the cross-root ARIA problem is the ability to refer into Shadow DOM. The Reference Target feature described in this explainer intends to solve this problem in a way that is compatible with the ARIAMixin attributes. - -When Reference Target is used in conjunction with ARIAMixin, it is possible to create references between elements in sibling shadow DOMs, or between any two unrelated shadow DOMs on the page, as long as the components have provided the API to do so, through reference targets and custom attributes. - -### Web components as drop-in replacements for builtin elements - -Web components have an increasing number of features that allow them to work and act like builtin elements. For example: - -- [Form-Associated Custom Elements](https://html.spec.whatwg.org/dev/custom-elements.html#form-associated-custom-element) can participate in forms like a builtin input. -- [delegatesFocus](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/delegatesFocus) allows a component to work better with keyboard navigation. - -However, there are still missing pieces that prevent a web component from truly being a drop-in replacement for a built-in, including: - -1. Can't create ID reference links to elements inside a [shadow tree](https://dom.spec.whatwg.org/#shadow-trees). -2. Can't use built-in attributes like `aria-label` or `role` on the host and have them apply to an element inside the shadow root. -3. Non-trivial amount of code required to hook up custom attributes on the host to ARIAMixin attributes on an element inside the shadow root. -4. Can't get form-association for "free" by delegating to an input inside. - -This proposal solves only the first problem: referring into the shadow DOM. It leaves the other problems to be solved by other features. While all of the problems may seem related, they can be designed separately. - -## Proposal: Reference Target - -Reference Target is a new feature that enables creating ARIA links to elements inside a component's shadow DOM, while maintaining encapsulation of the internal details of the shadow DOM. - -#### Goals - -- Solve only the "missing piece" of cross-root ARIA: how to handle IDREF attributes referring into the shadow DOM. Avoid scope creep. -- Create a mechanism for ID reference attributes like `aria-activedescendant` and `for` to refer to an element inside a component's shadow DOM. -- Should work the same for both closed and open shadow roots. -- Shadow DOM encapsulation should be preserved: No direct access to any elements inside the shadow tree, and no implementation details leaked into a web component's API. -- Should allow creating references into multiple nested shadow roots, and across "sibling" shadow roots that don't have a direct parent/child relationship. -- The solution should be serializable, i.e. support declarative syntax that is expressible in HTML without needing JavaScript. - -#### Non-Goals - -- This is scoped to only solve the problem of referring _into_ the shadow DOM. It relies on ARIAMixin to refer _out_ of the shadow DOM. -- This feature does not solve the [bottleneck effect](https://alice.pages.igalia.com/blog/how-shadow-dom-and-accessibility-are-in-conflict/#limitations-of-these-apis). It is difficult to find a compelling real-world example where this is a problem. -- This does not affect how attributes set on the host element work. For example, this does not tackle the problem of forwarding `role` or `aria-label`, etc. from the host element to an element inside. - -#### Phases - -This proposal is broken into two phases: - -- [Phase 1](#phase-1) adds the ability to designate a single element as the target for _all_ IDREF properties that refer to the host. -- [Phase 2](#phase-2) adds a way to re-target specific properties (like `aria-activedescendant`) to refer a separate element. - -The goal of breaking it into phases is to get the simpler syntax and simpler use cases working first. The solutions to Phase 2 are more complex and may need more discussion before they are ready. - -### Phase 1: ShadowRoot `referenceTarget` attribute - -A component can specify an element in its shadow tree to act as its "reference target". When the host component is the target of a IDREF like a label's `for` attribute, the referenceTarget becomes the effective target of the label. - -The shadow root specifies the ID of the target element inside the shadow DOM. This is done either in JavaScript with the `referenceTarget` attribute on the `ShadowRoot` object, or in HTML markup using the `shadowrootreferencetarget` attribute on the `