diff --git a/.github/workflows/accname.yml b/.github/workflows/accname.yml index 93b00717f..69783dff4 100644 --- a/.github/workflows/accname.yml +++ b/.github/workflows/accname.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/accname/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -52,7 +52,7 @@ jobs: repository: w3c/accname ref: gh-pages path: accname - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: accname diff --git a/.github/workflows/core-aam.yml b/.github/workflows/core-aam.yml index 3d1780130..8cfe9080b 100644 --- a/.github/workflows/core-aam.yml +++ b/.github/workflows/core-aam.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/core-aam/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -53,7 +53,7 @@ jobs: repository: w3c/core-aam ref: gh-pages path: core-aam - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: core-aam diff --git a/.github/workflows/dpub-aam.yml b/.github/workflows/dpub-aam.yml index 3431cd7a9..cc87e6c46 100644 --- a/.github/workflows/dpub-aam.yml +++ b/.github/workflows/dpub-aam.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/dpub-aam/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -52,7 +52,7 @@ jobs: repository: w3c/dpub-aam ref: gh-pages path: dpub-aam - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: dpub-aam diff --git a/.github/workflows/dpub-aria.yml b/.github/workflows/dpub-aria.yml index 8c5d4f9e7..f6557e4f3 100644 --- a/.github/workflows/dpub-aria.yml +++ b/.github/workflows/dpub-aria.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/dpub-aria/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -52,7 +52,7 @@ jobs: repository: w3c/dpub-aria ref: gh-pages path: dpub-aria - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: dpub-aria diff --git a/.github/workflows/graphics-aam.yml b/.github/workflows/graphics-aam.yml index 216a7e3e2..d9f0a604e 100644 --- a/.github/workflows/graphics-aam.yml +++ b/.github/workflows/graphics-aam.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/graphics-aam/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -43,7 +43,7 @@ jobs: repository: w3c/graphics-aam ref: gh-pages path: graphics-aam - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: graphics-aam diff --git a/.github/workflows/html-amm.yml b/.github/workflows/html-amm.yml index 3c3912431..bc6734db0 100644 --- a/.github/workflows/html-amm.yml +++ b/.github/workflows/html-amm.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/html-aam/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -53,7 +53,7 @@ jobs: repository: w3c/html-aam ref: gh-pages path: html-aam - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: html-aam diff --git a/.github/workflows/mathml-aam.yml b/.github/workflows/mathml-aam.yml index 0d5c7b832..fe9fb94b3 100644 --- a/.github/workflows/mathml-aam.yml +++ b/.github/workflows/mathml-aam.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/mathml-aam/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -43,7 +43,7 @@ jobs: repository: w3c/mathml-aam ref: gh-pages path: mathml-aam - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: mathml-aam diff --git a/.github/workflows/pdf-aam.yml b/.github/workflows/pdf-aam.yml index 6826d8e24..320b99ccf 100644 --- a/.github/workflows/pdf-aam.yml +++ b/.github/workflows/pdf-aam.yml @@ -16,7 +16,7 @@ jobs: run: | curl -L -X POST \ -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{secrets.ARIA_EDITOR_DRAFTS}}" \ + -H "Authorization: Bearer ${{secrets.W3CGRUNTBOT_TOKEN}}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/w3c/pdf-aam/actions/workflows/build-from-monorepo.yaml/dispatches \ -d '{"ref":"gh-pages"}' @@ -52,13 +52,13 @@ jobs: repository: w3c/pdf-aam ref: gh-pages path: pdf-aam - token: ${{ secrets.ARIA_EDITOR_DRAFTS }} + token: ${{ secrets.W3CGRUNTBOT_TOKEN }} - uses: actions/download-artifact@v4 with: name: pdf-aam - name: Copy files run: | - cp -r aria/pdf-aam/** pdf-aam/ + cp -r aria.common/aria/pdf-aam/** pdf-aam/ - name: Push new files to child repo run: | git config user.name "github-actions[bot]" diff --git a/accname/index.html b/accname/index.html index 773fac4fa..9d0a72a6d 100644 --- a/accname/index.html +++ b/accname/index.html @@ -8,6 +8,7 @@ + + @@ -130,7 +131,7 @@ REC: "https://www.w3.org/TR/accname-1.2/", }, - preProcess: [linkCrossReferences], + preProcess: [linkCrossReferences, getParticipants], postProcess: [addPlatformMaintainers], xref: ["dom", "accname", "wai-aria", "infra"], }; @@ -4320,6 +4321,9 @@ >
Object Attribute: xml-roles:searchbox
+ Object Attribute: text-input-type:search + +
Interface: EditableText if aria-readonly is not "true" @@ -4338,6 +4342,109 @@ +

sectionfooter

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
ARIA Specification + sectionfooter +
Computed Role +

sectionfooter

+
MSAA + IAccessible2 + Role: ROLE_SYSTEM_GROUPING
+ Object Attribute: xml-roles:sectionfooter +
UIA + Control Type: Group
+ Localized Control Type: section footer +
ATK/AT-SPI + Role: ROLE_FOOTER
+
+ AX API[Note 1] + + AXRole: AXGroup
+ AXSubrole: AXSectionFooter
+ AXRoleDescription: section footer +
+

sectionheader

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
ARIA Specification + sectionheader +
Computed Role +

sectionheader

+
MSAA + IAccessible2 + Role: ROLE_SYSTEM_GROUPING
+ Object Attribute: xml-roles:sectionheader +
UIA + Control Type: Group
+ Localized Control Type: section header +
ATK/AT-SPI + Role: ROLE_HEADER +
+ AX API[Note 1] + + AXRole: AXGroup
+ AXSubrole: AXSectionHeader
+ AXRoleDescription: section header +

separator (non-focusable)

@@ -11145,7 +11252,12 @@

Acknowledgments

-
+
+

ARIA WG participants at the time of publication

+ +
diff --git a/documentation/archive/1.2/1.2 Non editorial features and other changes.md b/documentation/archive/1.2/1.2 Non editorial features and other changes.md new file mode 100644 index 000000000..820982b78 --- /dev/null +++ b/documentation/archive/1.2/1.2 Non editorial features and other changes.md @@ -0,0 +1,178 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/1.2-Non-editorial-features-and-other-changes, last edited Apr 1, 2021. + +# 1.2 Non editorial features and other changes + + +Note: We have a https://github.com/w3c/aria/wiki/Plans-regarding-role-parity[dedicated page] for work on achieving role parity with HTML5. Other non-editorial features and changes should be added here _after they have landed in the ARIA Editor's Draft_. + +## In Progress + +### Combobox value calculation (needs CoreAAM, implementations) +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/51ef35c +** Working Draft: TODO +* Core AAM: https://github.com/w3c/core-aam/issues/76 +** Editor's Draft: TODO +** Working Draft: TODO +* AccName: N/A +* Authoring Practices: https://github.com/w3c/aria-practices/issues/1476 +* WPT: Done (in local branch; merge request pending) +* Implementations: +** WebKit: TODO +** Gecko: TODO +** Blink: TODO +* Test Results: TODO + +### Adds missing implicit values for progressbar (Needs: implementations) +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/43a80b42331351a72992d539ef8a1d8f2a828352 +** Working Draft: TODO +* Core AAM: https://github.com/w3c/core-aam/issues/77 +** Editor's Draft: N/A +** Working Draft: N/A +* AccName: N/A +* Authoring Practices: N/A +* WPT: Done (in local branch; merge request pending) +* Implementations: +** WebKit: TODO (Link to issue until implemented) +** Gecko: TODO (Link to issue until implemented) +** Blink: TODO (Link to issue until implemented) +* Test Results: TODO + +### Name from contents is no longer supported on `rowgroup` (Needs implementations) +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/bc4aa34 +** Working Draft: TODO +* Core AAM: +** Editor's Draft: n/a +** Working Draft: n/a +* AccName: n/a +* Authoring Practices: DONE (https://w3c.github.io/aria-practices/#naming_role_guidance - see "rowgroup" in the table) +* WPT: Done (in local branch; merge request pending) +* Implementations: +** WebKit: TODO (Link to issue until implemented) +** Gecko: TODO (Link to issue until implemented) +** Blink: TODO (Link to issue until implemented) +* Test Results: TODO + +### Default value of aria-valuenow on spinbutton is now "there is no current value" (Needs: Core-AAM, tests, implementations) - at risk +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/d6a99dec +** Working Draft: TODO +* Core AAM: +** Editor's Draft: n/a +** Working Draft: n/a +* AccName: n/a +* Authoring Practices: n/a +* WPT: TODO +* Implementations: +** WebKit: TODO (Link to issue until implemented) +** Gecko: TODO (Link to issue until implemented) +** Blink: TODO (Link to issue until implemented) +* Test Results: TODO + +### Remove aria-level on tablist (Needs Implementations, Needs tests, Editor's note) +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/f391cf62a0609e9d691ebd7df40d0ed9cdb5285b +** Working Draft: TODO +* Core AAM: +** Editor's Draft: n/a +** Working Draft: n/a +* AccName: n/a +* Authoring Practices: n/a +* WPT: TODO +* Implementations: +** WebKit: TODO (Link to issue until implemented) +** Gecko: TODO (Link to issue until implemented) +** Blink: TODO (Link to issue until implemented) +* Test Results: TODO + +### Prohibit aria-roledescription on generic (Needs Implementations) +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/f41f707 +** Working Draft: TODO +* Core AAM: +** Editor's Draft: n/a +** Working Draft: n/a +* AccName: n/a +* Authoring Practices: n/a +* WPT: Done (in local branch; merge request pending) +* Implementations: +** WebKit: TODO (Link to issue until implemented) +** Gecko: TODO (Link to issue until implemented) +** Blink: TODO (Link to issue until implemented) +* Test Results: TODO + + +### Make aria-disabled, aria-errormessage, aria-invalid and aria-haspopup deprecated as globals. + +Adds back to roles as noted in https://github.com/w3c/aria/commit/5b971a1 - make sure to also allow on subclasses during implementation. + +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/5b971a1 +** Working Draft: TODO +* Core AAM: +** Editor's Draft: TODO +** Working Draft: TODO +* AccName: n/a +* Authoring Practices: n/a +* WPT: n/a (right??) +* Implementations: +** WebKit: TODO (Link to issue until implemented) +** Gecko: TODO (Link to issue until implemented) +** Blink: TODO (Link to issue until implemented) +* Test Results: TODO + +### Implicit value removed for aria-expanded on combobox + +### Implicit value removed for aria-level on heading + +### remove superclass of checkbox from menuitemcheckbox & radio from menuitemradio + +### Menuitemradio language change (editorial - needs merging) + +### Editorial + +* 4eed8b541e23e160788e7236d710bd6751f991ee +* 2714fd041862f873fb3ce8a6a82305d74c847f64 + + + + + + +## Done + +* Remove children-presentational=true from `math` role +* Add support for `aria-expanded` for `application` and `checkbox` +* Add support for aria-posinset and aria-setsize on row +* Add support for `aria-required` to `checkbox` and `switch` +* Allow menuitemcheckbox as child of group +* Prohibit label on certain roles + +## Done (modulo APG) + +* Allow group as child of listbox (APG in process) +* Remove accessible name required from log and timer + +## Template for Adding New Items + +The following template should be used for all non-editorial changes which are subject to the ARIA Working Group's https://www.w3.org/WAI/ARIA/workflow[work flow] for inclusion into Working Drafts. + +``` +### Feature/Change Summary +* ARIA: +** Editor's Draft: TODO +** Working Draft: TODO +* Core AAM: +** Editor's Draft: TODO +** Working Draft: TODO +* AccName: TODO +* Authoring Practices: TODO +* WPT: TODO +* Implementations: +** WebKit: TODO +** Gecko: TODO +** Blink: TODO +* Test Results: TODO +``` diff --git a/documentation/archive/1.2/ARIA annotations draft proposal.md b/documentation/archive/1.2/ARIA annotations draft proposal.md new file mode 100644 index 000000000..726fd1bb2 --- /dev/null +++ b/documentation/archive/1.2/ARIA annotations draft proposal.md @@ -0,0 +1,399 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/ARIA-annotations-draft-proposal, last edited Jan 10, 2019. + +# ARIA annotations draft proposal + +# ARIA Annotation use cases, markup and more + + +## Definitions + +Annotations as they relate to ARIA: + +* An _annotation_ is the combination of annotated content and its related annotation body. +* The _annotated content_ is the range of text or other object which the _annotation body_ is "about". Note: [In the Web Annotations Data Model](https://www.w3.org/TR/annotation-model/#motivation-and-purpose), this is known as the _annotation target_. However, because the term "target" has a specific meaning in accessibility APIs as the end (and not beginning) of a relation, the term annotated content is preferred here, in order to avoid confusion with the actual directionality of aria-details in ARIA annotation markup. +* The _annotation body_ is visible information within a page which is connected to annotated content for a related purpose. +* The _annotation purpose_ is the role the _annotation body_ plays in relation to the _annotation target_, e.g. commentary vs. a footnote. + + +## How do ARIA annotations relate to the Web Annotations Data Model? + +ARIA annotations are more limited than what can be expressed in the Web Annotations Data Model. +* They cannot point to information external to the web page +* They must point to additional information within that web the page (e.g. a simple "highlight" does not do this). + +In addition, ARIA annotations do not contain as much information. It only contains what is necessary for the identified use cases. + +For more information, please see the [Addendum on mapping Web Annotations Data Model to accessible web content](#addendum-mapping-from-the-web-annotations-data-model). + +## Web content use cases + + + +* Document editor +* Code editor +* Published content + + +## Assistive technology use cases + +* AT user issues command to navigate to previous/next annotated content (e.g. next commented text) +* AT user issues command to navigate to previous/next annotation body (e.g. next comment) +* AT user issues one of the above commands, but filtered by annotation purpose (e.g. commentary only) +* AT user issues command to navigate from annotation body to the annotated content, or vice-versa +* Screen reader provides viewing options for reading annotation purposes, where the purpose is shortened, e.g. "commentary" becomes "*ct" + +### Proposed Markup + + +* **aria-details** (required, IDREF) + * Goes on the annotated content, and points to the in-page annotation body. + * Example: `This is commented text` + * No specific tag or role is required. However, it may be desirable to prefer `` over a generic element such as `` when there is a visible highlight +* **role** (optional, NMTOKENS) on the annotation body + * Goes on the annotation body, describing the annotation purpose. See below for a list of roles and more details. + * Example: `
`. + * As is always the case, multiple roles are supported: if more than one role is provided then the first recognized role may be mapped through accessibility APIs. The most important or specific role should always go first. For example, `
` would indicate that there is a suggestion with comments, but some APIs may only expose it as a "suggestion". +* **``**/**``** (required for the "revision" and "suggestion" annotation purposes) + * Provided as children of the annotated content, and define a past change or proposed future change to the document. [TBD] @aleventhal: Alternatively, if/when ARIA provides roles for insertion and deletion, the role attribute could be used instead. + * Example: `

Everyone is encouraged to bring a side dishbeverage to share.

.` + * Ordering: the ARIA spec should define whether the order is important for these 1-2 children. I suggest the AT should handle all permutations in the ordering. + +In addition, the following markup may be helpful but is not really part of the annotations spec: + + + +* **aria-label**/**aria-labelledby/aria-describedby** (optional) + * If this is found on the annotation body, it could provides a useful label or description for the annotation, that could be presented by a screen reader in a mode where the user wanted to understand more about the annotation bodies in context but the annotation bodies themselves would be too long. + + +## Roles for annotation purposes + +These go on the annotation body, not the annotated content. + +All annotation- prefixed roles would inherit from an abstract role of "annotation", which would inherit from "structure". If the role is not provided, then the annotation is simply treated as a description, as it would already be via aria-details usage. + + +* **annotation-attribution**— authoring information for the annotated content. [TBD] @mck we may want to choose a better name as this name may ultimately just be used by screen readers and most users might not know what to make of it. [TBD#2] @aleventhal: recommend we make this redundant with annotation-revision, and remove this one. +* **annotation-commentary**— one or more comments, or a comment thread +* **annotation-description** — generic description. This is also the default if the annotation purpose is unspecified. [TBD] @aleventhal: rather than add an extra role here, how about the author simply not use any of the other annotation roles. +* **annotation-revision** — this is a historical change that has already been accepted. The source annotated content will contain 1-2 children for the insertion and/or deletion. +* **annotation-suggestion** — proposed edit. The source annotation will contain 1-2 children for the proposed insertion and/or deletion. +* **annotation-presence** — similar to attribution, but relates to editing that is happening right now. For example, "Mr. Smith is editing nearby". +* **doc-footnote**/**doc-endnote** for footnotes and endnotes. When using DPUB roles, the annotated content will be the referencing note number. The author may choose to leave out the **doc-noteref** role on the annotated content, as that will be exposed as a link to ATs (see DPUB-AAM), and it may not be a link. In addition, the fact that it is a note reference number is implied by the relation with the annotation body, which will have the doc-footnote or doc-endnote role. + +Use the singular form: for consistency, all of the annotation purposes are in the singular form of the word, even though in some cases the plural could have made sense, as in "suggestion" where there may be multiple suggestions. + + +## Rejected annotation purposes + +For now, the following annotation purposes have not been assigned new roles: + + +* **highlight** — this does not fit the proposed definition of an annotation in that it does not point to additional info. Therefore, ARIA WG should consider adding something like role=mark (would need to be added for role parity), or the author can use HTML via // +* **error** — in code in code editor: use the already supported aria-invalid="true" + aria-errormessage=id +* **warning**— in code editor: may want to add aria-invalid="warning" as possible value (and like error, can use aria-errormessage=id) +* **bookmark** — similar to "annotation-presence"; would need more info on this use case in order to support it. [TBD] @aleventhal: Suggest that the author can use `` for a good experience. +* **breakpoint**— does not always come with additional visible information, so it would be difficult to shoehorn into this use case. [TBD] @aleventhal: For this one, perhaps a `` or role="mark" or a new role="breakpoint" could be used, along with aria-label. Or, a visible button could be used on the line with the breakpoint, that is labelled as a breakpoint button. + + +## Platform Accessibility mappings + + + +* [UI Automation has built-in support for annotations](https://docs.microsoft.com/en-us/windows/desktop/winauto/uiauto-annotation-type-identifiers) — note that a perfect 1 to 1 mapping is not expected here. For example, a grammar error is an annotation in UIA, but in ARIA is aria-invalid="grammar". An important difference with UIA annotations is that ARIA annotations always link to visible in-page content. +* Most of the markup is reused — there are already known ways for exposing aria-details, aria-label, aria-labelledby, aria-describedby, `` and ``. +* For aria-annotation, this should be exposed as an object attribute called "annotation" in ATK/IA2 + + + +## Addendum: Mapping from the Web Annotations Data Model + +An important use case is to convert annotation data from the Web Annotations Data Model (typically in JSON format) into accessible content, with the goal of enabling AT support. The following are non-normative suggestions for accomplishing this. + +### Example 1: Describing a relationship to in-page visible content + +Translating a “commenting” motivation in the data model to the appropriate ARIA and HTML markup: + +```html +

The following cats have been deemed uncooperative.

+
+

Comment by Ruff Finkledog

+

Wouldn’t it be simpler to list the cooperative cats?

+
+``` + +### Example 2: Describing a Web Annotation that does not have a relationship to other content + +This example is useful for the "highlighting" motivation. + +```html +

The word cat is highlighted

+``` + +### Example 3: Describing a Web Annotation that is related to external content only + +This example is useful for the "identifying" motivation. + +```html +

A cat is one of our favorite quirky pets.

+``` + +### Proposed Mapping Table +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

Web Annotations Data Model Concept

+ 		+

Proposed  additional markup on annotation

+ 		+

Proposed markup on annotated content

+ 		+

Description

+
+

Assessing motivation

+ 		+

role=”annotation-commentary”

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to assess the target resource in some way, rather than simply make a comment about it. For example to write a review or assessment of a book, assess the quality of a dataset, or provide an assessment of a student's work.

+
+

Bookmarking motivation

+ 		+

none

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to create a bookmark to the Target or part thereof. For example an Annotation that bookmarks the point in a text where the reader finished reading.

+
+

Classifying motivation

+ 		+

role=”annotation-description”

+ 		+

aria-details=[id] (if classifications visible in page)

+ 		+

The motivation for when the user intends to classify the Target as something. For example to classify an image as a portrait.

+
+

Commenting motivation

+ 		+

role=”annotation-commentary”

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to comment about the Target. For example to provide a commentary about a particular PDF document.

+
+

Describing motivation

+ 		+

role=”annotation-description”

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to describe the Target, as opposed to (for example) a comment about it. For example describing the above PDF's contents, rather than commenting on their accuracy.

+
+

Editing motivation

+ 		+

role=”annotation-suggestion”

+ 		+

aria-details=[id]

+

Must also have <ins>, <del> child or both

+ 		+

The motivation for when the user intends to request a change or edit to the Target resource. For example an Annotation that requests a typo to be corrected.

+
+

Highlighting motivation

+ 		+

none

+ 		+

Use <mark> or appropriate ARIA role from role parity work once available

+ 		+

The motivation for when the user intends to highlight the Target resource or segment of it. For example to draw attention to the selected text that the annotator disagrees with.

+
+

Identifying motivation

+ 		+

none

+ 		+

<a href=[IRI]>external link</a>

+ 		+

The motivation for when the user intends to assign an identity to the Target. For example to associate the IRI that identifies a city with a mention of the city in a web page.

+
+

Linking motivation

+ 		+

none

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to link to a resource related to the Target.

+
+

Moderating motivation

+ 		+

role=”annotation-commentary”

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to assign some value or quality to the Target. For example annotating an Annotation to moderate it up in a trust network or threaded discussion.

+
+

Questioning motivation

+ 		+

role=”annotation-commentary”

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to ask a question about the Target. For example, to ask for assistance with a particular section of text, or question its veracity.

+
+

Replying motivation

+ 		+

role=”annotation-commentary”

+ 		+

aria-details=[id]

+ 		+

The motivation for when the user intends to reply to a previous statement, either an Annotation or another resource. For example providing the assistance requested in the above.

+
+

Tagging motivation

+ 		+

role=”note”, e.g. <div role=”note”>Tags: cats, pets</div>

+ 		+

aria-details=[id] (if tags are visible in content)

+ 		+

The motivation for when the user intends to associate a tag with the Target.

+
+

Attribution from provenance chunk

+ 		+

role=”annotation-attribution”

+ 		+

aria-details=[id] (if attribution is visible in content)

+ 		+

Authoring information for the annotated content

+
+

Does not currently exist in Web Annotations Data Model

+ 		+

role=”annotation-revision”

+ 		+

aria-details=[id]

+

Must also have <ins>, <del>; child or both

+ 		+

This is a historical change that has already been accepted. The source annotated content will contain 1-2 children for the insertion and/or deletion

+
+

Does not currently exist in Web Annotations Data Model

+ 		+

role=”annotation-presence”

+ 		+

aria-details=[id]

+ 		+ +
+

Does not currently exist in Web Annotations Data Model

+ 		+

role=”doc-footnote” | “doc-endnote” | “doc-biblioentry”

+ 		+

aria-details

+ 		+

In-page links for footnotes, endnotes, bibliographical information in a document

+
diff --git a/documentation/archive/1.2/Generic Role End to End.md b/documentation/archive/1.2/Generic Role End to End.md new file mode 100644 index 000000000..f60990df6 --- /dev/null +++ b/documentation/archive/1.2/Generic Role End to End.md @@ -0,0 +1,234 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Generic-Role-End-to-End, last edited May 23, 2019. + +# Generic Role End to End + +## Current DIV Mapping + + +
WAI-ARIANo corresponding role
MSAA + IAccessible2 +
+ May not have an accessible object if has no semantic meaning. Otherwise, +
+
+ Roles: ROLE_SYSTEM_GROUPING; IA2_ROLE_SECTION +
+
+ Interfaces: + IAccessibleText2; IAccessibleHypertext2; +
+
UIA +
+ May not have an accessible object if has no semantic meaning. Otherwise, +
+
Control Type: Group
+
ATK +
+ May not have an accessible object if has no semantic meaning. Otherwise +
+
+ Role: + ATK_ROLE_SECTION +
+
+ Interfaces: AtkText; AtkHypertext +
+
AX +
+ AXRole: AXGroup +
+
+ AXSubrole: (nil) +
+
+ AXRoleDescription: "group" +
+
Comments
+ +## Current SPAN Mapping + +
span
WAI-ARIANo corresponding role
MSAA + IAccessible2
Not mapped
UIA +
+ Control Type: Group +
+
ATK
Not mapped
AX +
+ AXRole: AXGroup +
+
+ AXSubrole: (nil) +
+
+ AXRoleDescription: "group" +
+
Comments
+ +### Actual Mapping today +The above is sometimes true but is dependent on the CSS applied to the DIV or SPAN +inline -> acts like SPAN +block -> acts like DIV + +Other CSS display styles to be evaluated. + + + + +## Proposed Generic Role + +### generic (role) + +A nameless container element that has no semantic meaning on its own, but can provide accessible states and properties for its descendants. + +Contrast with group, which semantically groups its descendants in a named container. + +The aria-textseparation attribute of a generic indicates how its text content is separated from adjacent text content of adjacent generic elements. + +Characteristics: + +Superclass Role: structure + +Related Concepts: HTML div, HTML span + +Supported States and Properties: aria-textseparation + +Inherited States and Properties: + aria-atomic + aria-busy (state) + aria-controls + aria-current (state) + aria-describedby + aria-details + aria-disabled (state) + aria-dropeffect + aria-errormessage + aria-flowto + aria-grabbed (state) + aria-haspopup + aria-hidden (state) + aria-invalid (state) + aria-keyshortcuts + aria-label? + aria-labelledby? + aria-live + aria-owns + aria-relevant + aria-roledescription + +Name From: contents none? undefined? prohibited? N/A (i.e. not in table)? + + +*** + + +### aria-textseparation (property) + +Defines how text content of a generic element is separated from text content of adjacent generic elements. + +Specifically, aria-textseparation only applies to text nodes at the boundaries of a generic; it has no effect on separation between text nodes inside the generic, or on other types of elements. + +The value of the aria-textseparation property is a token list of size 1 or 2. The first value represents the type of text separation before the element, and the second value represents the type of text separation after the element. If a single value is given, it represents the type of text separation before and after the element. Any value not recognized in the list of allowed tokens SHOULD be treated by assistive technologies as if the default value style had been provided. If the attribute is not present or its value is an empty string or undefined, the default value of style applies. + +For example, if the badge class in the following markup renders a circle around the "12" so that it is visually separated from the word "Notifications", then aria-textseparation="style space" ensures that AT render a space between the spans. + +EXAMPLE +``` + + Notifications12 + +``` + +NOTE +If adjacent generics have space separation, spaces will be collapsed to a single space. + +NOTE +In the event of conflicting text separation between adjacent generics, paragraphbreak has precedence over linebreak, which has precedence over space, which has precedence over none, which has precedence over style. + +Characteristics: + +Related Concepts: String concatenation, text content, CSS rendering + +Used in Roles: generic + +Value: token list + +style (default) Indicates that the element's text is separated from neighboring element text according to the element's display style. + +linebreak Indicates that the element's text is separated from neighboring element text by a line break. + +none Indicates that the element's text is not separated from neighboring element text; it is rendered as a continuous whole, without any delineation. + +paragraphbreak Indicates that the element's text is separated from neighboring element text by a paragraph break. + +space Indicates that the element's text is separated from neighboring element text by a space. + + +### Proposed mapping of generic + +Generic + style -> acts like Div & Span today - depends on CSS applied for mapping + +Generic + linebreak -> like DIV + +generic + none -> like SPAN + +generic + paragraphbreak -> like DIV (do we need this?) + +generic + space - > like SPAN but add a space in the ACCNAME calculation + +### Naming DIV/SPAN/generic + +https://github.com/w3c/aria/issues/833 + +Proposal - remove aria-label,labelledby from global states and properties. +Add to widget, window, application, landmark, document, list, figure, group, img, range, table, tabpanel + +Following non-abstract roles are no longer labelable - note we can add some of these if we decide to. +* alert +* blockquote +* caption +* cell +* definition (** This needs to be added - should we allow ONLY aria-labelledby?) +* deletion +* heading +* insertion +* label +* legend +* listitem +* log +* marquee +* math?? +* none +* note +* paragraph +* presentation +* rowgroup +* status +* subscript +* superscript +* term +* time +* timer +* tooltip + + +Note - this change has a **major** impact to role presentation conflict resolution section. +Prior to this change +``` + +``` +Would be exposed as a list. After this change it would NOT be exposed as a list. +We need to check browser implementations of this. + +Other Questions +is aria-describedby the same or should that be left as global? +See: https://w3c.github.io/using-aria/#label-support + +Heading states the following: +> Often, heading elements will be referenced with the aria-labelledby attribute of the section for which they serve as a heading. If headings are organized into a logical outline, the aria-level attribute is used to indicate the nesting level. + +This implies that sections should be labelled and should be changed + +Branch created with these changes +https://raw.githack.com/w3c/aria/NonGlobalLabelLabelledBy/index.html#roles +Draft PR https://github.com/w3c/aria/pull/967 + diff --git a/documentation/archive/1.2/Plans regarding role parity.md b/documentation/archive/1.2/Plans regarding role parity.md new file mode 100644 index 000000000..44215d9cd --- /dev/null +++ b/documentation/archive/1.2/Plans regarding role parity.md @@ -0,0 +1,165 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Plans-regarding-role-parity, last edited Apr 1, 2022. + +# Plans regarding role parity + +## Parity not planned + +These elements are not mapped and thus no parity is planned for them: `base`, `body`, `br`, `col`, `colgroup`, `data`, `head`, `html` `input` (`type=hidden`), `link`, `map` (when used as an imagemap), `meta`, `noscript`, `param`, `picture`, `script`, `source`, `style`, `template`, `title`, `track`, `wbr`. + +These elements are currently a WONTFIX due to an inability to achieve proper, accessible parity: `audio`, `video`. + +## Parity Achieved in ARIA <= 1.2 + +These ARIA roles provide parity for the elements listed. + +* `article`: `article` +* `blockquote`: `blockquote` +* `button`: `button`, `input` (`type` is `button`, `image`, `reset`, `submit`) +* `caption`: `caption`, `figcaption` +* `cell`: `td` and `th` (in a `table` that is not a `grid`) +* `checkbox`: `input` (`type` is `checkbox`, parent is not `menu`) +* `code`: `code` +* `columnheader`: `th` (when it is a column header) +* `combobox`: `input` (`type` is `text`, `email`, `search`, `telephone`, `url` with suggestions source element) (https://github.com/w3c/aria/issues/962[An additional attribute may be created in 1.3]) +* `definition`: `dd` +* `deletion`: `del` +* `dialog`: `dialog` +* `emphasis`: `em` +* `figure`: `figure` +* `form`: `form` (with an accessible name) +* `generic` (with no additional attribute): `div`, `span`, `cite`, `footer` and `header` (not scoped to `body`), `form` and `section` (without accessible name), `tfoot`, `thead`, `details` +* `generic` (https://github.com/w3c/aria/issues/960[an additional attribute may be created in 1.3]): `abbr`, `address`, `b`, `i`, `kbd`, `mark`, `pre`, `q`, `s`, `samp`, `small`, `u`, `var` +* `gridcell`: `td` and `th` (in a `table` that is a `grid`) +* `group`: `optgroup` +* `heading`: `h1`, `h2`, `h3`, `h4`, `h5`, `h6` +* `img`: `img`, `area` (no `href`) +* `insertion`: `ins` +* `link`: `a` and `area` (when they represent a hyperlink) +* `list`: `ol` and `ul` (https://github.com/w3c/aria/issues/961[an additional attribute may be created in 1.3]) +* `listitem`: `li` (parent is `ol` or `ul`) +* `listbox`: `datalist` (when represents pre-defined options for input element), `keygen`, `select` (with `multiple` attribute or `size` > 1) +* `main`: `main` +* `math`: `math` +* `menuitem`: `a` (when it represents a hyperlink and parent is a `menu`), `input` (`type` is `button` or `image`, parent is `menu`), `menu` (`type` is `context`), `menuitem` (`type` is `command`) +* `menuitemcheckbox`: `input` (`type` is `checkbox`, parent is `menu`), `menuitem` (`type` is `checkbox`) +* `menuitemradio`: `input` (`type` is `radio`, parent is `menu`), `menuitem` (`type` is `radio`) +* `meter`: `meter` +* `navigation`: `nav` +* `none`/`presentation`: `img` (empty alt value) +* `option`: `option` (in a list of options or represents a suggestion in a `datalist`) +* `paragraph`: `p` +* `progressbar`: `progress` +* `radio`: `input` (`type` is `radio`, parent is not `menu`) +* `region`: `section` (with accessible name) +* `rowgroup`: `tbody` +* `rowheader`: `th` (when it is a row header) +* `separator`: `hr` +* `searchbox`: `input` (`type` is `search`, no suggestions source element) +* `slider`: `input` (`type` is `range`) +* `spinbutton`: `input` (`type` is `number`) +* `status`: `output` (Is this sufficient for all of output's potential semantics?) +* `strong`: `strong` +* `subscript`: `sub` +* `summary`: `button` role with `aria-expanded` +* `superscript`: `sup` +* `table`: `table` +* `textbox`: `input` (`type` is `text`, `email`, `search`, `telephone`, `url` and no suggestions source element) (https://github.com/w3c/aria/issues/962[An additional attribute may be created in 1.3]) +* `textbox` + `aria-multiline` is `true`: `textarea` +* `term`: `dfn` +* `time`: `time` + +## Originally planned but moved out of 1.2, potentially to 1.3 + +### `label` - `label` role (Needs: APG, AccName, 2 implementations) + +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/78b9178 +** Working Draft: TODO +* Core AAM: +** Editor's Draft: https://github.com/w3c/core-aam/commit/8691f89 +** Working Draft: TODO +* AccName: https://github.com/w3c/accname/issues/54 +* Authoring Practices: https://github.com/w3c/aria-practices/issues/1108 +* WPT: TODO +* Implementations: +** WebKit: TODO +** Gecko: TODO +** Blink: TODO +* Results: TODO + +### `fieldset`, `legend` - `legend` role (Needs: APG, AccName, 2 implementations) +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/71d5024 (plus a https://github.com/w3c/aria/commit/8194d29[typo fix]) +** Working Draft: TODO +* Core AAM: +** Editor's Draft: https://github.com/w3c/core-aam/commit/a5f1673 +** Working Draft: TODO +* AccName: https://github.com/w3c/accname/issues/54 +* Authoring Practices: https://github.com/w3c/aria-practices/issues/1108 +* WPT: TODO +* Implementations: +** WebKit: TODO +** Gecko: TODO +** Blink: TODO +* Results: TODO + +### `dl`, `dt`, `dd` - `associationlist`, `associationlistitemkey`, `associationlistitemvalue` roles (Needs: Core-AAM, 2 implementations) +* ARIA: +** Editor's Draft: https://github.com/w3c/aria/commit/b371203c +** Working Draft: TODO +* Core AAM: +** Editor's Draft: https://github.com/w3c/core-aam/issues/56 +** Working Draft: TODO +* AccName: TODO +* Authoring Practices: Done (https://github.com/w3c/aria-practices/issues/1106) +* WPT: TODO +* Implementations: +** WebKit: TODO +** Gecko: TODO +** Blink: TODO +* Results: TODO + +## TODO - 1.3 + +See also: https://github.com/w3c/aria/projects/8 + +* a (no href) - triage needed +* bdi - triage needed +* bdo - triage needed +* canvas (https://github.com/w3c/aria/issues/927[#927]) +* embed, object (https://github.com/w3c/aria/issues/929[#929]) - Assigned to Scott +* iframe (https://github.com/w3c/aria/issues/879[#879]) - Assigned to Peter +* input (type=color) (https://github.com/w3c/aria/issues/930[#930]) +* input (type=date) (https://github.com/w3c/aria/issues/931[#931]) +* input (type=datetime-local) (https://github.com/w3c/aria/issues/932[#932]) +* input (type=file) (https://github.com/w3c/aria/issues/933[#933]) +* input (type=month) (https://github.com/w3c/aria/issues/934[#934]) +* input (type=password) (https://github.com/w3c/aria/issues/935[#935]) +* input (type=time) (https://github.com/w3c/aria/issues/936[#936]) +* input (type=week) (https://github.com/w3c/aria/issues/937[#937]) +* rp, rt, ruby (also check with i18n) (https://github.com/w3c/aria/issues/488[#488]) +* aria-textattribute for role parity with generic (https://github.com/w3c/aria/issues/960[#960]) +* aria-listtype for role parity with ul and ol (https://github.com/w3c/aria/issues/961[#961]) - Assigned to Harris +* aria-inputtype for role parity (https://github.com/w3c/aria/issues/962[#962]) + +## Template for Adding New Items + +The following template should be used for all items whose role parity is being achieved by an addition to ARIA: + +``` +### $HTML_ELEMENT - $NEW_ROLE role +* ARIA: +** Editor's Draft: TODO +** Working Draft: TODO +* Core AAM: +** Editor's Draft: TODO +** Working Draft: TODO +* AccName: TODO +* Authoring Practices: TODO +* WPT: TODO +* Implementations: +** WebKit: TODO +** Gecko: TODO +** Blink: TODO +* Results: TODO +``` diff --git a/documentation/archive/1.2/Required Properties with Default Values.md b/documentation/archive/1.2/Required Properties with Default Values.md new file mode 100644 index 000000000..25c58ada7 --- /dev/null +++ b/documentation/archive/1.2/Required Properties with Default Values.md @@ -0,0 +1,32 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Required-Properties-with-Default-Values, last edited Sep 28, 2018. + +# Required Properties with Default Values + +For issue #787 this is a list of all required properties that have default values defined + +Moved meta comment back into https://github.com/w3c/aria/issues/787 so that discussion can take place. + +Role | State/Property | Current Default Value | Notes +--- | --- | --- | --- +[checkbox](http://w3c.github.io/aria/#checkbox) | aria-checked | false | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[combobox](http://w3c.github.io/aria/#combobox) | aria-expanded | false | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[heading](http://w3c.github.io/aria/#heading) | aria-level | 2 | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[menuitemcheckbox](http://w3c.github.io/aria/#menuitemcheckbox) | aria-checked | false | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[menuitemradio](http://w3c.github.io/aria/#menuitemradio) | aria-checked | false | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[option](http://w3c.github.io/aria/#option) | aria-selected | false | Supported. No default. [PR #799](https://github.com/w3c/aria/pull/799) +[radio](http://w3c.github.io/aria/#radio) | aria-checked | false | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[scrollbar](http://w3c.github.io/aria/#scrollbar) | aria-orientation | vertical | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +scrollbar | aria-valuemin | 0 | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +scrollbar | aria-valuemax | 100 | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +scrollbar | aria-valuenow | halfway between valuemax and valuemin | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. **Consider changing default value to aria-valuemin.** +[separator (focusable)](http://w3c.github.io/aria/#separator) | aria-valuemin | 0 | Supported. Default in ARIA and needs to be added to [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +separator (focusable) | aria-valuemax | 100 | Supported. Default in ARIA and needs to be added to [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +separator (focusable) | aria-valuenow | 50 | Required. Default needs to be removed from ARIA and added to [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) as "(aria-valuemax - aria-valuemin) / 2". +[slider](http://w3c.github.io/aria/#slider) | aria-valuemin | 0 | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +slider | aria-valuemax | 100 | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +slider | aria-valuenow | halfway between valuemax and valuemin | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[spinbutton](http://w3c.github.io/aria/#spinbutton) | aria-valuemin | no minimum value | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +spinbutton | aria-valuemax | no maximum value | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). +spinbutton | aria-valuenow | 0 | Supported. Default in ARIA and [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable). **Consider changing default value to empty.** See [#797](https://github.com/w3c/aria/issues/797) and [PR#813](https://github.com/w3c/aria/pull/813). +[switch](http://w3c.github.io/aria/#switch) | aria-checked | false | Required. Default in [Core AAM Default Values Table](https://w3c.github.io/core-aam/#authorErrorDefaultValuesTable) only. +[treeitem](http://w3c.github.io/aria/#treeitem) | aria-selected | false | Supported. No default. [PR #799](https://github.com/w3c/aria/pull/799) diff --git a/documentation/archive/1.2/Resolving ARIA 1.1 Combobox Issues.md b/documentation/archive/1.2/Resolving ARIA 1.1 Combobox Issues.md new file mode 100644 index 000000000..cb465a6b8 --- /dev/null +++ b/documentation/archive/1.2/Resolving ARIA 1.1 Combobox Issues.md @@ -0,0 +1,228 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Resolving-ARIA-1.1-Combobox-Issues, last edited Jul 20, 2023. + +# Resolving ARIA 1.1 Combobox Issues + +## Goal + +resolve all open combobox-related issues in ARIA 1.2. + +## Terms for describing ARIA 1.1 combobox structure + +First, here are some terms to make describing problems easier. + +The ARIA 1.1 combobox has 3 primary parts: +1. Input: This is an element that conveys the value of the combobox. ARIA 1.1 requires it to be a textbox. +2. Popup: This is a single-select widget that presents a collection of values the user may choose for the input. The popup is displayed when the combobox is expanded and hidden when the combobox is collapsed. ARIA 1.1 allows the popup to be a listbox, grid, tree, or dialog. +3. Container: a wrapper `div` that has role `combobox` and contains or owns the input and the popup. + +Many comboboxes also have a down arrow icon or button that serves as a control for display of the popup for mouse and touch users. That button is not part of the definition of the combobox. If it is inside the container, the authoring practices advise excluding it from the page tab sequence. + +Combobox example from ARIA 1.1: + +``` +
+ +
+ +``` + +You can view an [example of an ARIA 1.1 combobox here](https://www.w3.org/TR/2019/NOTE-wai-aria-practices-1.1-20190814/examples/combobox/aria1.1pattern/listbox-combo.html). + +## ARIA 1.0 Combobox Problem + +To understand the ARIA 1.1 combobox issues, it is helpful to first understand what problems we experienced with the ARIA 1.0 combobox. + +ARIA 1.0 specifies two parts for the combobox -- the input and the popup. ARIA 1.0 says authors should specify the relationship between the input and the popup with `aria-owns`. + +``` + + + +``` + +You can view an [example of the ARIA 1.0 combobox here](https://www.w3.org/TR/2019/NOTE-wai-aria-practices-1.1-20190814/examples/combobox/aria1.0pattern/combobox-autocomplete-both.html). + +Because the input-popup relationship is specified with `aria-owns` in an ARIA 1.0 combobox, in accessibility trees, the popup is a child of the input. In other words, The accessibility tree for an ARIA 1.0 combobox has a textbox with a listbox inside of it. While the role of the textbox is `combobox`, it still functions as a textbox where users can edit text. In a sense, an ARIA 1.0 combobox input is also a container. + +Of course, on the screen, the textbox input and listbox popup are two separate things. So, the accessibility tree for an ARIA 1.0 combobox does not accurately represent the semantics of the user interface. + +This creates problems for screen reader users when using reading or touch modes. They cannot perceive a popup inside of an edit field. The popup is simply not present in the reading order. This is because a textbox cannot serve both as an edit field and a container for other widgets. A textbox supports editable text. The popup for a combobox is not editable text. It is not even part of the value; the popup is a separate widget that helps the user choose a value to put into the textbox. + +That is, instead of perceiving a textbox input with a listbox next to it, which is what sighted users perceive, people using a screen reader in reading or touch modes can only perceive an element called a combobox that acts like a textbox. The only way screen reader users can perceive the content of the popup in an ARIA 1.0 combobox is via keyboard navigation with the screen reader in interaction mode, e.g., JAWS forms mode. + +This structural issue that put a popup widget inside of a text field and thereby severely limited perception of the popup was the primary driver of changes to the ARIA 1.0 combobox. + +## ARIA 1.1 problems + +As described above, ARIA 1.1 specifies the combobox structure to be a combobox composite container with two widgets inside -- an input and a popup. The addition of the container element fixed the problem of the popup being inside the input. But, unfortunately, it has created many other issues. + +More detail is provided about each of the following problems in sections below. Each of these problems has spawned multiple issues against the ARIA spec. + +1. Naming: In code, there are 3 parts that can be named -- the combobox, the input, and the popup. On the screen, there is only one thing rendered that needs an accessible name -- the input. The spec says to name only the container. But, the spec does not require the browser to compute a name for the input from the container, which leads to an unlabeled input fieled, violating WCAG. Thus, authors tend to name all three parts, which creates verbosity problems that are difficult for screen reader developers to mitigate. +2. Screen reader presentation of the container: The container is sometimes being partially rendered by screen readers as a group. This adds elements to the screen reader experience that do not exist on screen and do not add value. In fact, it can be confusing for screen reader users because these extra grouping elements have never previously been part of how screen readers present comboboxes. +3. Screen reader presentation of the input: The ARIA spec says the wrapper has the `combobox` role but does not state what the role of the input should be. This is critical because the input is what gets focused. The spec needs to tell screen readers how the input should be conveyed to users. +4. Lack of `select` support: There is a type of combobox that does not include a textbox. HTML:select@size=1 is one example of this. This type of control cannot be created using the ARIA 1.1 combobox definition. +5. Author confusion: Because the container does not correspond to anything displayed on screen, it is difficult for authors to understand which ARIA attributes belong on the container and which belong on the input. As a result, author errors that cause problems for screen reader developers are a significant problem. + +## ARIA 1.2 Proposal to eliminate container + +One way to fix all these problems is to eliminate the container and make the combobox more like a menubutton. This is essentially returning to the 1.0 pattern with one small modification -- use `aria-controls` to specify the input-popup relationship instead of `aria-owns`. + +``` + + + +``` + +You can view an [example implementation of the proposed ARIA 1.2 combobox here](https://raw.githack.com/w3c/aria-practices/aria1.2-combobox-proposal/examples/combobox/combobox-autocomplete-list.html). +The proposed specification changes are in [ARIA pull request 1051](https://github.com/w3c/aria/pull/1051). + +In this proposal, the combobox has only one part -- the input. The popup is a related widget but is not technically part of the combobox. This is analogous to a menu button. The button controls the menu, and the menu itself is not part of the button. + +Semantically, this matches what is on the screen. There is an input element that displays a value. In some cases, that input is an edit field where users can type a value and typing may or may not open a popup that suggests possible values for the input. In other cases, the input is not an edit field; users must open the popup to change its value. + +How does this proposal fix the problems? + +1. Naming: There is only one thing that can be named. While it would be technically possible to name the popup, naming the popup would have no impact on the combobox itself. +2. Screen reader presentation of the container: Since there is no container, there is no chance that screen readers will render superfluous group elements that clutter the interface. +3. Screen reader presentation of the input: The input is unambiguously a combobox; it has role combobox. +4. No `select` support: The `input` in the above code can be replaced with a `div` or `span` whose content displays the current value. This exactly replicates the functionality of combobox widgets that do not have a textbox. +5. Author confusion: There is only one place to put all attributes. There is no room for confusion about where to put required states and properties. + +The best part of this proposal to eliminate the container is that it is already functional using any screen reader on any desktop platform. There is no need for modification to current screen reader or browser implementations. It even enables access to popup elements that are grids, trees, and dialogs without additional work by screen reader developers. + +The ARIA 1.1 pattern is not yet fully functional with any screen reader on any platform. +If this proposal to eliminate the container is not adopted in ARIA 1.2, other changes would need to be made to the ARIA specification to resolve the problems with the ARIA 1.1 pattern before screen reader developers can make comboboxes reliably functional. + +## Alternative resolution paths + +The following sections explore alternative approaches to resolving the 5 issues with the ARIA 1.1 combobox. +That is, if ARIA 1.2 keeps the combobox container, these sections attempt to answer the question of how ARIA 1.2 might otherwise resolve the above 5 problems. + +### Resolving issues with naming an ARIA 1.1 combobox + +There are two critical questions: +1. Should authors be required to name the container or the input? +2. Should authors be allowed to name both the container and the input? + +From the perspective of screen reader users, the second question is easy to answer. Only one name is necessary. Multiple names for a single widget do not add clarity for assistive technology users. + +There is only one name on the screen. That is the name that needs to be conveyed to assistive technology users. + +Because a collapsed combobox is a single element, and expanding a combobox reveals only a single adjacent element, a distinctly named grouping element is not helpful. In this way, a combobox is similar to a menu button and completely dissimilar from composites, such as radio group, menubar, and grid. + +Regardless of where authors specify the name, they do not need to specify names for both the container and the input. If they do, one should take precedence over the other. + +Currently the spec requires a name on the container. ARIA 1.1 does not clearly specify whether a name is required on the input. The textbox role requires a name. However, when a textbox is inside of a combobox, it is not clear whether or not it is still a textbox; it should probably be considered a combo edit box. + +ARIA 1.1 does not require browsers to calculate a name for the input from the container. + +An alternative approach to resolving naming problems is to: +1. Prohibit naming of the combobox container. +2. Require authors to name the input; this is already required if the input is a textbox. + +### Resolving problems with Screen reader presentation of ARIA 1.1 combobox containers + +While the container in the ARIA 1.1 combobox specification is a coding construct for ensuring the popup is adjacent to the input in the reading order, exposing the container itself does not add semantic value for assistive technology users. +Ideal reading order can be achieved without a container that has a semantic role. + +Arguably, exposing the container to screen reader users detracts from the screen reader experience by adding verbosity that does not serve an important purpose. +A collapsed combobox is a single input element; it does not need any type of grouping. +An expanded combobox renders only two elements that are intrinsically related by context, and potentially by name. +This is similar to other ARIA widgets that conditionally display a secondary element, such as disclosures and menu buttons. +Those patterns do not superimpose a semantic grouping container; doing so would add authoring complexity without improving the experience for end users. + +If ARIA 1.2 does not eliminate the container from the combobox specification, then it could help resolve this problem by adding a normative statement that says assistive technologies SHOULD NOT expose the container to users. This would align with prohibitting accessible names on the container. + +### Resolving problems with Screen reader presentation of ARIA 1.1 combobox input + +The ARIA spec says the wrapper has role `combobox`. And, it requires the input to be a textbox. When a screen reader reads the textbox, what should the screen reader convey for the role of the textbox? The computed role is simply textbox. + +Historically, screen readers announce the input as a combobox if it does not support editable text and a combo edit box if it supports editable text. Screen readers could look up the tree for all single-line edit fields to assess whether or not to announce them as a combo edit box. While feasible, this is inconsistent with the rest of ARIA. In other composites, the role of a composite ancestor does not change the role of the element with focus. + +Alternatively, another valid screen reader behavior would be to convey the textbox as a textbox and not expose the combobox role to end users. Instead, the screen reader could announce the availability of specific behaviors, such as auto completion and value suggestions. + +In practice, screen readers need to convey a role but are not bound to the ARIA lexicon. ARIA does not prescribe screen reader rendering. + +Nonetheless, a valid concern is that the ARIA 1.1 combobox definition and structure create ambiguity for screen reader developers. This increases the likelihood that multiple screen readers running on the same platform and in the same browser will render the same combobox in meaningfully different ways. While it is expressly not the goal of ARIA to dictate assistive technology experiences, it is not helpful to authors or end users when ARIA needlessly promotes variation. + +If ARIA 1.2 were to keep the container element, then one way of promoting consistency would be to add a role for the textbox, e.g., comboboxinput. This would be consistent with the structure of other composite widgets, e.g., a `menu` contains `menuitem` elements, a `radiogroup` includes `radio` elements, and a `grid` contains `gridcell` elements. + +### Resolving lack of `select` support + +There is a type of combobox that does not include a textbox. HTML:select@size=1 is one example of this. This is an input that has an associated drop down list. The value of the input must be chosen from the list. The input itself does not support editable text. + +This type of widget cannot be created using the ARIA 1.1 combobox pattern. It is possible to create a similar widget by adding `readonly` to an `input@type="text"` in a `combobox`, but that method of implementation is limiting for authors and troublesome for users. + +Ideally, authors would be able to create a widget that is semantically identical to an HTML select. They could use an element for the input that they can style any way they like and that is not treated by screen readers as a text field. For example, they could use a `span` or `div` for the input as follows: + +``` +
+ Zoom +
+ +``` + +In this case, the `span` with `aria-autocomplete` is the input element that displays the current value. When it receives focus, it should be announced as a `combobox`. + +One significant problem with this pattern is that the focusable element does not have a role. + +If ARIA 1.2 were to keep the container element, then one possible solution is to add the above suggested "comboboxinput" role. The specification could advise screen readers to render elements with role `comboboxinput` as `combobox`. + +### Reducing author Confusion + +The ARIA 1.1 combobox pattern is relatively complex due to the fact that there are two places to place relevant attributes -- the container and the input. +This has been a source of author errors. +At least one screen reader developer is identifying such errors as a significant concern. + +Short of eliminating the container, there is no clear way to mitigate this other than to encourage browsers to correct author errors when populating the accessibility tree. Of course, checkers can help prevent the errors from getting out in the wild. But, that will not remove the necessaty of robust error correction. + +## Summary of resolution options + +* Option 1: Remove the container and change combobox from composite to input -- [See pull request 1051](https://github.com/w3c/aria/pull/1051). +* Option 2: + * Add a role for the input, e.g., comboboxinput. + * Require a name on elements with role comboboxinput. + * Advise screen readers to present elements with role `comboboxinput` as `combobox`. + * Prohibit naming the container. + * Add a normative statement that says assistive technologies SHOULD NOT expose the container to users. + * Advise user agents to align the accessibility tree with the combobox pattern when authors misplace required or supported attributes. + +## Responses to other objections to removing the container + +One objection to making yet another change is that it will create churn for authors. +In practice, we have seen very little use of the ARIA 1.1 pattern because it does not work well with assistive technologies. +In addition, converting the 1.1 pattern to match the 1.2 proposal is very simple: move the combobox role, `aria-expanded`, and the accessible name from the container to the input. + +## Related GitHub issues + +### aria-controls vs aria-owns +* [998: Combobox 1.0 pattern incorrectly includes aria-owns instead of aria-controls](https://github.com/w3c/aria/issues/998) +* [776: aria-controls a required property for Combobox?](https://github.com/w3c/aria/issues/776) +* [716: aria-controls or owns should be on input, not on combobox element](https://github.com/w3c/aria/issues/716) +### Naming +* [893: 1.1 Combobox pattern endorses unlabelled form fields](https://github.com/w3c/aria/issues/893) +* [909: Clarify combobox label placement](https://github.com/w3c/aria/issues/909) +* [1046: Does combobox require an accessible name?](https://github.com/w3c/aria/issues/1046) +### Other inconsistencies +* 853: Combobox has aria-expanded required, but there is a default value +* 742: combobox incorrect regarding searchbox? +### HTML select +* 817: Update combobox spec as per html spec +* w3c/html-aam#46: select should map to listbox regardless of presentation +* 721: Add aria-valuetext to listbox +* 722: Add aria-expanded to listbox diff --git a/documentation/archive/1.2/Testing aria-hidden.md b/documentation/archive/1.2/Testing aria-hidden.md new file mode 100644 index 000000000..cb27960f5 --- /dev/null +++ b/documentation/archive/1.2/Testing aria-hidden.md @@ -0,0 +1,44 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Testing-aria-hidden, last edited May 8, 2020. + +#### Notes: +This is a refresh of [@stevefaulkner's aria-hidden tests](https://developer.paciellogroup.com/blog/2013/11/html5-accessibility-chops-hidden-aria-hidden-support/) and [test data](https://www.html5accessibility.com/tests/hidden2013.html) from 2013. +Added a couple of new tests for visibility:hidden, and one new test for aria-hidden=false on descendant of aria-hidden=true. + +#### Test cases used for testing: +https://carmacleod.github.io/playground/aria-hidden-tests.html + +#### Software used for testing: +* Windows 10 +* Chrome 81 +* Edge 81 +* Firefox 76 +* Internet Explorer 11 +* Safari 13.1 +* JAWS 2019 +* NVDA 2019.3.1 +* VoiceOver on iOS 13.3.1 (iPhone SE) +* VoiceOver on macOS Catalina 10.15.4 +* ChromeVox on Chrome OS ? +* Orca ? on Epiphany (Webkit) ? +* Orca ? on Chromium ? Ubuntu ? +* Orca ? on Firefox ? Ubuntu ? +* Talkback ? on Android ? Chrome ? +* Talkback ? on Android ? Firefox ? + +#### Results: +screen reader support for various methods of hiding content + +test | JAWS + Chrome | JAWS + Edge | JAWS + Firefox | JAWS + IE | NVDA + Chrome | NVDA + Edge | NVDA + Firefox | NVDA + IE | VoiceOver macOS + Safari | VoiceOver iOS + Safari | ChromeVox + Chrome OS | Orca + Epiphany (Webkit) | Orca + Chromium Ubuntu | Orca + Firefox Ubuntu | Talkback + Android Chrome | Talkback + Android Firefox | +--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +`1.` aria-hidden=true | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? +`2.` html hidden | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? +`3.` CSS display:none | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? +`4.` CSS visibility:hidden | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? +`5.` CSS off screen | read | read | read | read | read | read | read | read | read | read | ? | ? | ? | ? | ? | ? +`6.` CSS off screen aria-hidden=true | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? +`7.` HTML hidden aria-hidden=false | ignored | ignored | ignored | read | ignored | ignored | ignored | ignored | read | read | ? | ? | ? | ? | ? | ? +`8.` CSS display:none aria-hidden=false | ignored | ignored | ignored | read | ignored | ignored | ignored | ignored | read | read | ? | ? | ? | ? | ? | ? +`9.` CSS visibility:hidden aria-hidden=false | ignored | ignored | ignored | read | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? +`10.` HTML hidden with aria-hidden=false child | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? +`11.` aria-hidden=true with aria-hidden=false child | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ignored | ? | ? | ? | ? | ? | ? + diff --git a/documentation/archive/modules/On the ARIA DPUB impasse listing of the options.md b/documentation/archive/modules/On the ARIA DPUB impasse listing of the options.md new file mode 100644 index 000000000..d7c43c3cf --- /dev/null +++ b/documentation/archive/modules/On the ARIA DPUB impasse listing of the options.md @@ -0,0 +1,127 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/On-the-ARIA---DPUB-impasse-listing-of-the-options, last edited Oct 17, 2019. + +# On the ARIA DPUB impasse listing of the options + +This is an attempt list the various possibilities potentially solving the current impasse around +DPUB-ARIA. In view of the invested time and energy, as well as the relatively urgent needs of the +publishing community on the matter this may help in reaching a solution soon. This write-up tries to avoid +taking sides, just lists the various options that seem to be available. It is up to the PF WG and the DPUB-ARIA Task Force to choose among these options (or come up with a variant or a new one). + +Note that this text looks at the issues from the point of view of DPUB-ARIA, primarily because +it is this work that is now stalled. However, the real issues reveal a more +general set of questions on the exact role (sic!) of the `@role` attribute in general, and this writeup could be +used as a test case to address those in general. + +Some preliminaries that should be taken into account, ie, which should influence the final choice: + +* Adding a new `@role` attribute to a browser/validator is an expensive operation. There is a set +of constraints imposed by the combination of the values of `@role` and the corresponding `@aria-*` +attributes which have to be checked, and that requires, essentially, a case-by-case check. +In other words, each new `@role` value has a "price" that must be taken into +account when adding new values. + +> (It is unclear, when writing this note, whether the role hierarchies introduce yet another level of difficulties or not. Any comment/update on that would be welcome. @iherman) + +* Additionally to the constraint checking issue, ARIA `@role` values have mappings to the +Accessibility APIs. In practice, these calls to the API are performed by the user agent and have to be defined one-by-one. + +* The (e-)publishing community has been using a number of "structural semantics" terms to +characterize the structure of a document for a long time. As specifications or usage patterns evolve, +terms are added to the existing vocabulary. Most (if not all) of the terms ("abstract", "index", +"glossary", etc.) are part of the traditions of the publishing community, going back to, +possibly, centuries. These values have several possible usages for user agents: it can be used to +influence the user interface (e.g., a pop up window when clicking on a term that is marked as +"footnote") but they have obvious importance for accessibility, too, adding information that is not +conveyed by the bare HTML tag names. At the moment, some of the publishing communities use +(prefixed) `@class` values (e.g., in magazine publishing using terms defined by the PRISM +consortium) others have introduced namespaced XML attributes (`@epub:type` in EPUB3). None of these +solutions are satisfactory. The goal of the DPUB-ARIA work was/is to provide an alternative that would work well with HTML5 *and* which would also be beneficial for accessibility of digital documents. + +* When adding new `@role` values there is a danger of ending up with name clashes. There may be +different solutions to solve this (the usage of "hyphenspaces", a specific `@aria-vocab` attribute +on the same element, or a global `@role-vocab` have been mentioned). This summary does not deal +with this issue, acknowledging, however, that it may have to be solved depending on which direction +the work proceeds. In some cases, the details of solving this may add new "Con"-s to the +discussions below. + +* (Just to clean up a misconception) The term "structural *semantics*" is used by the publishing +community, but this is **not** semantics in the Semantic Web sense. We are not talking about RDF, OWL, etc. +This misunderstanding did come up in some of the comments, hence the necessity to clear this up.) + +With these preliminaries in mind, the following approaches seem to be possible. + +## 1. Minimal ARIA @role values for DPUB + +This solution is based on the approach that an ARIA `@role` value is acceptable *if and only if* +there is a clear and direct mapping on Accessibility APIs. I.e., the second bullet item above is +reinforced by, conceptually, saying that "*every `@role` value MUST have a mapping to an Accessibility APIs*". +If a specific `@role` value does not have an obvious mapping, or it is "covered" by another, +already existing value of ARIA `@role`, then the new value is not acceptable. + +* **Pro:** This approach minimizes the number of possible `@role` values, thereby minimizing the +"costs" on user agents (which include validators) as well as on mappings. +* **Con:** A number of issues raised so far, based on this approach on `@role`, showed that this would lead to a +dramatic reduction of the number of acceptable DPUB-ARIA terms. As a consequence, DPUB-ARIA +would *not* solve the problems of the DPUB community, because most of the structural semantic +terms would be missing. + +## 2. Permissive ARIA @role values for DPUB + +This solution is based on a more general approach on the possible values of `@role`: while some +values have a clear and direct mapping on Accessibility APIs, some others may rely on +the inheritance of `@role` values only and would not map directly to Accessibility APIs. + +* **Pro:** This makes it possible to map all the structural semantics terms of DPUB on ARIA `@role` +values. (Provided the name clash issue is solved without raising additional problems.) +* **Con:** The extra complexity on user agents would become significant (see the first bullet item above) for a potentially large number of new values. Furthermore, deciding on which value is mapped on Accessibility APIs or not is an extra burden. + +## 3. *Partially* de-associating @role from ARIA + +This solution, in some sense, goes back to the history of the `@role` attribute, when it +was not yet closely related to ARIA. What it means it that `@role` MAY have values that are *not* +associated to ARIA *at all* although, in contrast to the original `@role` recommendation, the +possible values are strictly specified and not open ended (and therefore can be checked by a validator). + +Although there *is* an extra complexity on user agents, because they have to separate +the ARIA `@role` values from the non-ARIA ones, once the separation is done validators can just check the values against a simple list of acceptable values, and other user agents may simply ignore those values as far as +Assistive Technologies are concerned. + +* **Pro:** The DPUB structural semantic terms could be mapped onto `@role` without restriction +(provided the name clash issue is solved without raising additional problems). Some +of these values would have no relationships to ARIA `@role` in sense of assistive +technologies; others would be bona fide ARIA `@role` values. +* **Con:** The extra complexity on user agents in separating the various `@role` values, though manageable, is real. +* **Con:** It is, conceptually, fairly messy, and not a clean design to have a "dual" behavior for an attribute. +* **Con:** On a social level, this line of thoughts may re-start old discussions with the HTML WG, and would therefore tear up old scars... + +## 4. Use a separate HTML5 extension + +This solution means that the DPUB community defines a *separate* attribute (let us use the term `@pub-type` hereafter, although a the exact term can change) as an official extension to HTML5. This means the possible values of the attribute would be defined in a separate specification (whether it is specified by a W3C group or an IDPF group has to be agreed with the HTML5 Working Group). This solution bypasses ARIA altogether. + +* **Pro:** The DPUB structural semantics gets a clear syntax, compatible with HTML5. It solves the +DPUB community's main original problem. +* **Con:** Cutting the ties with ARIA means that there would be no automatic relationships of the structural +semantics terms with accessibility. User agents would have to deal with the accessibility aspects of structural +semantics separately. + +## 5. Use a separate HTML5 extension with extra AT mapping + +This is a slight extension to the previous (#4) solution. Whilst the bulk of the structural semantics +terms would be defined for `@pub-type` only, an extra step would be taken to identify those terms +that may have a reasonable mapping on Accessibility APIs and formally define those. This means that user agents, aware of the `@pub-type` attribute, can make the mapping. + +* **Pro:** Like before, DPUB structural semantics gets a clear syntax, and the accessibility +consideration are also taken into account (at least partially) +* **Con:** User agents would have to recognize an extra attribute for some of the values to execute the mapping on the Accessibility APIs; the probability that being implemented by all browsers is probably low (although dedicated ebook readers would probably do it). + +## 6. Use a separate HTML5 extension with @role mapping + +This is a slight extension to the previous (#5) solution: instead of defining Accessibility API mapping, a +dedicated values are also defined in ARIA 1.1 as `@role` values (but not as a separate module). This would also include a mapping to the Accessibility APIs. + +* **Pro:** Like before, DPUB structural semantics gets a clear syntax, and the accessibility +consideration are also taken into account (at least partially). +* **Pro:** Enriching the ARIA 1.1 terms would be beneficial for the Web user community at large, and that is always a good thing. User agents would not have to do anything special, because all values would fall under the general ARIA 1.1 set. +* **Con:** DPUB authors would be expected to duplicate the information, e.g., +`...`; this is prone to errors and not +clear whether authors would do this in practice. diff --git a/documentation/archive/process/Monorepo Project.md b/documentation/archive/process/Monorepo Project.md new file mode 100644 index 000000000..51423e5ab --- /dev/null +++ b/documentation/archive/process/Monorepo Project.md @@ -0,0 +1,65 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Monorepo-Project, last edited May 21, 2024. + +# Monorepo Project + +Moving specifications into a monorepo, which repos -- all of them? +* [Accessible Name and Description Computation (aka "accname")](https://github.com/w3c/accame) +* [CORE-AAM](https://github.com/w3c/core-aam) +* [HTML-AAM](https://github.com/w3c/html-aam) +* [DPUB-ARIA](https://github.com/w3c/dpub-aria) +* [DPUB-AAM](https://github.com/w3c/dpub-aam) +* [MathML-AAM](https://github.com/w3c/mathml-aam) +* [Graphics-ARIA](https://github.com/w3c/graphics-aria) +* [Graphics-AAM](https://github.com/w3c/graphics-aam) +* [SVG-AAM](https://github.com/w3c/svg-aam) + +We will move after the recharter: +* [HTML-ARIA](https://github.com/w3c/html-aria) + +ARIA [Monorepo](https://github.com/w3c/aria/tree/monorepo) branch starts off with a basic structure + some demo GitHub workflows for publication. +Open questions: +* What other specs use a monorepo, what is their insight on this proposal? + * [ePub Working Group](https://github.com/w3c/epub-specs) is currently using a "monorepo" approach. Publlishing ever-green specs is doable with current [specprod options](https://w3c.github.io/spec-prod/#options). Daniel will set up a proposal for handling our specs. +* How to publish the different specifications from one repo + * How to publish evergreen vs versioned specifications + * Daniel suggests that we use automated publication for ever-green specs but we keep using manual publication for versioned specs. Most transition requests need to happen manually anyway. +* How to maintain old URLs (like github.io editor's drafts) +* What URL to use for editor's drafts +* How to modify ARIA process +* Whether to leave repositories open for issue tracking +* Are modifications necessary for pr-preview? +* What will we do with open PRs? +* Do we want to take the time to change some old branch mnaming and usage? HTML-aam still uses gh-pages as the main branch. + +Example of monorepos: +* https://github.com/w3c/epub-specs + + +## notes + +### merging git repositories + +Based on https://build5nines.com/git-merge-repositories-with-history/ + +Terminology: 'source' repository (e.g., accname) getting merged into 'target' repo (as a subfolder, e.g., aria). + +Strategy: use `git-filter-repo` to rewrite source repository, moving its content into a subfolder. Then merge that rewritten repository into the target repository. + +- install https://github.com/newren/git-filter-repo/ +- Clone source + - `$ git clone https://github.com/w3c/source.git source` + - `$ cd source` +- Use 'git-filter-repo' to rewrite 'source' repo to subfolder named 'Foo' (maintaining history) + - `$ git filter-repo -f --to-subdirectory-filter Foo --tag-rename :foo-` + - After running the root '/' contents of 'source' repo will be located in '/Foo/' subfolder +- Clone target + - `$ git clone https://github.com/build5nines/target-repo.git target` +- Prep 'target' repo: + - `$ cd target` + - `$ git checkout -b merged-repos` +- Add source as (local folder) git remote to 'target' + - `$ git remote add -f source ../source` +- merge source repo into target, allowing unrelated history + `$ git merge --allow-unrelated-histories -m 'merge source repository with history' source/main` +- Push branch to remote / GitHub + `$ git push --set-upstream origin merged-repos` diff --git a/documentation/archive/unresolved/CSS AAM Potential Features.md b/documentation/archive/unresolved/CSS AAM Potential Features.md new file mode 100644 index 000000000..38ada140c --- /dev/null +++ b/documentation/archive/unresolved/CSS AAM Potential Features.md @@ -0,0 +1,116 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/CSS-AAM-Potential-Features, last edited Feb 26, 2018. + + +# CSS-AAM Potential Features and Potential CSS WCAG Techniques +The goal of this document is to provide a *preliminary* list the CSS Modules under development that have impacts on accessibility. Some of these require documenting how the CSS features should be mapped to Accessibility APIs on various platforms. Some need authoring advice, in the form of WCAG Techniques and Failures and/or CSS Best Practices. Others are potentially useful for accessibility scenarios, and should be further explored. Some were too long or complex for a cursory read to determine their accessibility implications, and need additional review. + +Finally, there are two broad categories of issues where there is no consensus on how to proceed. These are areas where we hope that frank and open discussion among experts from the CSS and APA working groups can yield deeper understanding and new approaches. These are: + +1. Order and Flow for screen-readers and sequential navigation on pages where visual layout and DOM order are not in synch. +2. Whether and how to use CSS and media queries to create experiences optimized for accessibility scenarios and users. + +The list below is a *first attempt* at slotting the various CSS modules into these categories for further exploration and discussion. It is an early draft intended to stimulate further discussion among members of both APA and CSS. + +## CSS-AAM Candidates +### Possibly related to reading/navigation order question + +* [CSS Flexible Box Layout](https://drafts.csswg.org/css-flexbox-1/) +* [CSS Grid Layout Level 1](http://www.w3.org/TR/css-grid-1) +* [CSS Positioned Layout Level 3](http://www.w3.org/TR/css3-positioning/) + +#### The specs below are less clearly related, but are worth a look while thinking about holistic solutions +* [CSS Multi-column Layout](http://www.w3.org/TR/css3-multicol) +* [CSS Fragmentation Level 3](http://www.w3.org/TR/css3-break) +* [CSS Box Alignment Module Level 3](http://www.w3.org/TR/2016/WD-css-align-3-20160614/) +* [CSS Basic Box Model Level 3](http://www.w3.org/TR/css3-box) +* [CSS Paged Media Level 3](http://www.w3.org/TR/css3-page) +* [CSS Intrinsic & Extrinsic Sizing Module Level 3](http://www.w3.org/TR/css3-sizing/) +* [CSS Template Layout](http://www.w3.org/TR/css-template-3) +* [CSS Regions](http://www.w3.org/TR/css3-regions) +* [CSS Round Display Level 1](http://www.w3.org/TR/css-round-display-1/) +* [CSS Basic User Interface Module Level 4](http://www.w3.org/TR/css3-ui) (resize section) + +### Document existing mappings and implementation consensus + +* [CSS Display Level 3](http://www.w3.org/TR/css-display-3/): Display:none changes the AAPI tree. Document that and any other features that do. +* [CSS Generated Content Module Level 3](http://www.w3.org/TR/css-content-3/): Document how generated content should be exposed in AAPI +* [CSS Generated Content for Paged Media](http://www.w3.org/TR/css3-gcpm): Document how generated content should be exposed in AAPI +* [CSS Counter Styles Level 3](http://www.w3.org/TR/css-counter-styles-3/): Document how to expose generated list numbers and bullets in AAPI +* [CSS Lists Level 3](http://www.w3.org/TR/css3-lists): Document how to expose lists in AAPI, including numbers and order +* [CSS Tables Level 3](http://dev.w3.org/csswg/css3-tables/): Document how it impacts mappings of HTML tables +* [CSS Basic User Interface Module Level 4](http://www.w3.org/TR/css3-ui): Document how caret and keyboard direction maps to AAPI +* [CSS Image Values and Replaced Content Level 3](http://www.w3.org/TR/css3-images): How does this interact with name calculation? Does it impact the accessibility tree structure? +* [CSS Writing Modes Level 3](http://www.w3.org/TR/css3-writing-modes): Text Direction exposed in AAPI. Discuss with bidi AT developers about what needs they have, if any. +* [CSS Ruby Level 1](http://www.w3.org/TR/css3-ruby): Document how to expose Ruby in AAPI. Get input from international AT vendors, especially in Japan. +* [CSS Backgrounds and Borders Level 3](http://www.w3.org/TR/css3-background): The way IE did high contrast caused some problems. Consider documenting how high contrast, themes, color inversion should be handled by browsers with respect to backgrounds and borders. +* [CSS Masking Level 1](http://www.w3.org/TR/css-masking/), [CSS Overflow Level 3](http://www.w3.org/TR/css-overflow-3/): +Should masking and clipping impact what text is in AAPI? If so, when and how. Document consensus. +* [CSS Values and Units Level 3](http://www.w3.org/TR/css3-values): Document how zooming and text sizing should impact each unit, to avoid situations like the differences in handling of pt and px in IE and Firefox. +* [CSSOM View](http://www.w3.org/TR/cssom-view), [CSS Object Model](http://www.w3.org/TR/cssom), [CSS Typed OM Level 1](http://www.w3.org/TR/css-typed-om-1/): Document relationship between CSSOM and AAPI +* [CSS Pseudo-Elements Module Level 4](http://www.w3.org/TR/css-pseudo-4): Should any pseudo-element styling be reflected in AAPI? +* [Filter Effects](http://www.w3.org/TR/filter-effects/): Document interactions with high contrast, color inversion, etc. + +# Authoring Advice Needed + +## WCAG techniques/failures and CSS Best Practices for how to use feature + +The CSS WCAG techniques are very old, and don't cover many features of CSS that have known accessibility utility and pitfalls. Some of these are covered in the CSS Best Practices. The following specs could benefit from coordination between CSS and WCAG to develop techniques and define the relationship between CSS Best Practices and WCAG techniques. + +* [CSS Fonts Level 3](http://www.w3.org/TR/css3-fonts): Techniques on how to do UI glyphs accessibly. (may not be directly related to this spec) +* [CSS Values and Units Level 3](http://www.w3.org/TR/css3-values): There are known issues with resizing and re-layout when mixing different types of units. +* [CSS Animations](http://www.w3.org/TR/css3-animations), [Web Animations 1.0](http://www.w3.org/TR/web-animations/), [CSS Transitions](http://www.w3.org/TR/css3-transitions), [Motion Path Module Level 1](http://www.w3.org/TR/motion-1/): look into techniques for animations related to WCAG requirements for stopping/pausing motion, seizures, and improving understanding for user with cognitive disabilities. +* [Non-element Selectors](http://www.w3.org/TR/selectors-nonelement-1): WCAG technique for using role and aria-* attributes as selectors +* [CSS Color Module Level 4](https://www.w3.org/tr/css-color-4/): Look into techniques and failures related to contrast + +### Older WCAG ideas for CSS techniques +These are links to lists of ideas the WCAG working group had for CSS techniques a few years ago. They were last reviewed in 2015, so should not be taken as definitive. +* [Techniques to do](https://www.w3.org/WAI/GL/wiki/Techniques/ToDo#CSS) +* [Techniques/CSS](https://www.w3.org/WAI/GL/wiki/Techniques/CSS) + +### Might be useful for other WCAG techniques +These specs have features that could be leveraged in WCAG techniques, particularly WCAG techniques related to cognitive accessibility optimizations. Have the WCAG and COGA teams take a look at these for technique ideas. +* [CSS Text Decoration Module Level 3](http://www.w3.org/TR/css-text-decor-3/) +* [CSS Text Level 3](http://www.w3.org/TR/css3-text) +* [CSS Shapes Level 1](http://www.w3.org/TR/css-shapes-1/) + +## Using CSS to optimize for Accessibility + +APA has been interested in ways that CSS can be used for accessibility-optimized views. The CSS working group has a particular view on the intentions of these features and how they interact with accessibility. This is an area where a joint task force can be useful to understand the different viewpoints and seek common ground. This work should start with examining design goals of these features and accessibility use cases. It might results in new CSS features, CSS-AAM mappings, authoring guidance or some combination, and has a fairly long time horizon. + +* [Media Queries](http://www.w3.org/TR/css3-mediaqueries) +* [Media Queries level 4](http://www.w3.org/TR/2016/WD-mediaqueries-4-20160706/) +* [CSS Conditional Rules Level 3](http://www.w3.org/TR/css3-conditional) +* [CSS Device Adaptation](http://www.w3.org/TR/css3-conditional): Should accessibility views (e.g. magnification, symbol replacement for users with cognitive disabilities) be treated as devices? + + +## Do further review +* [CSS Level 1](http://www.w3.org/TR/CSS22/) (largely covered by existing WCAG techniques) +* [CSS Level 2](http://www.w3.org/TR/CSS22/): Look for areas that are not covered by reviews of later modules +* [CSS Speech](http://www.w3.org/TR/css3-speech): Has much potential for accessibility enhancements +* [Compositing and Blending Level 1](http://www.w3.org/TR/compositing-1/): Look at interaction with SVG-AAM +* [CSS Transforms](http://www.w3.org/TR/css3-transforms): Look at interaction with SVG-AAM and whether this has any relationship to the order issue. +* [CSS Painting API Level 1](http://www.w3.org/TR/css-paint-api-1/): Is there a mechanism for text alternatives? +* [CSS Properties and Values API Level 1](http://www.w3.org/TR/2016/WD-css-properties-values-api-1-20160607/): Extensibility mechanism for CSS. How will this impact AAPI construction? Will there be a way to reflect these new things in AAPI? +* [Worklets Level 1](http://www.w3.org/TR/2016/WD-worklets-1-20160607/): Will this impact AAPI construction? + +## Out of Scope +These are CSS specs that, on first review, don't seem to have accessibility impact. +* [CSS Snapshot 2015](http://www.w3.org/TR/css-2015) +* [CSS Snapshot 2010](http://www.w3.org/TR/css-2010) +* [CSS Snapshot 2007](http://www.w3.org/TR/css-beijing) +* [CSS Color Level 3](http://www.w3.org/TR/css3-color) +* [CSS Namespaces](http://www.w3.org/TR/css3-namespace) +* [Selectors Level 3](http://www.w3.org/TR/selectors) +* [CSS Print Profile](http://www.w3.org/TR/css-print) +* [CSS Style Attributes](http://www.w3.org/TR/css-style-attr) +* [CSS Cascading and Inheritance Level 3](http://www.w3.org/TR/css3-cascade) +* [CSS Syntax Level 3](http://www.w3.org/TR/css3-syntax) +* [Geometry Interfaces Module Level 1 ](http://www.w3.org/TR/geometry-1) +* [CSS Cascading and Inheritance Level 4](http://www.w3.org/TR/css-cascade-4) +* [Cascading Variables](http://www.w3.org/TR/css-variables) +* [CSS Will Change Level 1](http://www.w3.org/TR/css-will-change-1/) +* [Selectors Level 4](http://www.w3.org/TR/selectors4) +* [CSS Scroll Snap Points Module Level 1](http://www.w3.org/TR/css-snappoints-1) +* [CSS Line Grid](http://www.w3.org/TR/css-line-grid-1/) +* [CSS Font Loading](http://www.w3.org/TR/css-font-loading-3/) +* [CSS Scoping Level 1](http://www.w3.org/TR/css-scoping-1/) diff --git a/documentation/archive/unresolved/Plans regarding attribute parity.md b/documentation/archive/unresolved/Plans regarding attribute parity.md new file mode 100644 index 000000000..8232e0891 --- /dev/null +++ b/documentation/archive/unresolved/Plans regarding attribute parity.md @@ -0,0 +1,95 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Plans-regarding-attribute-parity, last edited Jan 24, 2022. + +# Plans regarding attribute parity + +## Introduction + +This triage is based on what is in the HTML-AAM. Joanie did not go through the HTML spec looking for attributes that are in there, but not in the HTML-AAM. It would be great if someone could do that. + +## Parity not planned + +These are not mapped on any platform: `accept`, `accept-charset`, `action`, `allow`, `allowfullscreen`, `allowpaymentrequest`, `as`, `async`, `autocapitalize`, `autofocus`, `autoplay`, `charset`, `class`, `color`, `content`, `crossorigin`, `data`, `decoding`, `default`, `defer`, `dirname`, `download`, `enctype`, `form`, `formaction`, `formenctype`, `formmethod`, `formnovalidate`, `formtarget`, `href` (on `link`), `hreflang`, `http-equiv`, `id`, `ismap`, `kind`, `loop`, `media`, `method`, `multiple` (on `input`), `muted`, `name`, `novalidate`, `ping`, `playsinline`, `poster`, `preload`, `referrerpolicy`, `rel`, `rows`, `sandbox`, `shape`, `sizes` (on `link`), `slot`, `srcdoc`, `srclang`, `target`, `title` (on `link`, `style`), `translate`, `type`, `usemap`, `value` (on `button`, `option`, `param`, `data`), `wrap` + +In addition, these will not be done for the stated reason: + +. `controls` on `audio`, `video`: We are not creating `audio` and `video` roles at this time. See https://github.com/w3c/aria/issues/517. Therefore attribute parity for roles which do not exist makes no sense. + +## Already done via AccName + +`alt`, `label`, `title` + +## Already done via ARIA + +. `checked`: `aria-checked` +. `colspan`: `aria-colspan` +. `disabled`: `aria-disabled` +. `hidden`: `aria-hidden` +. `indeterminate`: `aria-checked=mixed` +. `max`: `aria-valuemax` +. `min`: `aria-valuemin` +. `multiple` (on `select`): `aria-multiselectable` +. `selected`: `aria-selected` +. `placeholder`: `aria-placeholder` +. `readonly`: `aria-readonly` +. `required`: `aria-required` +. `rowspan`: `aria-rowspan` +. `scope=col`: `columnheader` role +. `scope=row`: `rowheader` role +. `value` (on `meter`, `progress`): `aria-valuenow` + +## Already "done" via exposure of rendered result + +. `coords` on `area`: Exposure to ATs should come from rendered object; not the property. +. `height` on `canvas`, `embed`, `iframe`, `img`, `input`, `object`, `video`: Exposure to ATs should come from rendered object; not the property. +. `reversed` on `ol`: Exposure comes via the text exposed for the list item markers. +. `size` on `input`: Exposure based on bounding box rendered widget. +. `size` on `select`: Exposure based on rendered widget (similar to type on input). +. `sizes` on `img`, `source`: Exposure to ATs should come from rendered object; not the property. +. `start` on `ol`: Exposure comes via the text exposed for the list item markers. +. `style`: Exposure to ATs should come from the rendered/calculated styles. +. `tabindex`: Exposure mostly done via focusability (when not -1). We also have coverage by managing keyboard focus spec contents. +. `type` on `ol`: Exposure comes via the text exposed for the list item markers. +. `width` on `canvas`, `embed`, `iframe`, `img`, `input`, `object`, `video`: Exposure to ATs should come from rendered object; not the property. + +## TODO + +. `high` on `meter` +. `low` on `meter` +. `optimum` on `meter` + +https://github.com/w3c/aria/issues/1336 + +## Candidates (Mapped on at least one platform) + +Do ATs really need these? If so, can we get mappings for all platforms? + +. `abbr` on `th` +. `cite` on `blockquote`, `del`, `ins`, `q` +. `cols` on `textarea` +. `contenteditable` +. `datetime` on `del` and `ins` +. `datetime` on `time` +. `dir` +. `headers` on `td` and `th` +. `href` on `a`, `area` +. `list` on `input` https://github.com/w3c/aria/issues/472 [closed / rejected (for now)] +. `lang` +. `open` on `details` +. `pattern` on `input` (current mapping is for the presence of error; not the pattern itself) +. `spellcheck` on `input` (current mapping is for the presence of error; not if checking is enabled) +. `span` (on `colgroup`) +. `src` on `img` +. `step` on `input` https://github.com/w3c/aria/issues/471 [closed / rejected (for now)] +. `value` on `li` + +These need further discussion: + +. `accesskey`: Do we have sufficient parity through aria-keyshortcuts? +. `autocomplete`: Need to get/update mappings for UIA, AXAPI. In addition, in HTML values are on/off. ARIA lacks these. +. `draggable`: not mapped. Question: Do we want to deal with drag and drop during 1.3? +. `for` on `label` and `output`: Can this be covered via `aria-labelledby`? +. `maxlength` on `input`, `textarea`: not mapped. But maybe it should be? https://github.com/w3c/aria/issues/1119[Joanie thinks so]. +. `minlength` on `input`, `textarea`: not mapped. Also maybe it should be? +. `type` on `button`: Exposure mainly based on label. But see also https://github.com/w3c/aria/issues/842 +. `type` on `input`: Exposure based on rendered widget. But see also https://github.com/w3c/aria/issues/962 +. `value` on `input`: Exposure comes via the text/value exposed as the content of the `input`. diff --git a/documentation/archive/unresolved/Text Separation attribute proposals.md b/documentation/archive/unresolved/Text Separation attribute proposals.md new file mode 100644 index 000000000..0f81ae164 --- /dev/null +++ b/documentation/archive/unresolved/Text Separation attribute proposals.md @@ -0,0 +1,32 @@ +**Editors Note.** Archived wiki page https://github.com/w3c/aria/wiki/Text-Separation-attribute-proposals, last edited Dec 5, 2018. + + +# Text Separation attribute proposals + +From #699 These are the current text separation proposals + +## aria-textseparation - https://github.com/w3c/aria/issues/699#issuecomment-415951739 +* none +* textnode +* space +* leadingspace +* trailingspace +* inline +* block + +## aria-whitespace - https://github.com/w3c/aria/issues/699#issuecomment-416096296 +* space +* line-break +* paragraph-break +* none +* inherit + +## aria-textseparation - https://github.com/w3c/aria/issues/699#issuecomment-420878301 +* + +## Add on wrapper rather than node - https://github.com/w3c/aria/issues/699#issuecomment-425131510 + +## 2 token value? - https://github.com/w3c/aria/issues/699#issuecomment-427040820 + + + diff --git a/dpub-aam/index.html b/dpub-aam/index.html index d8f2359b5..577d7c563 100644 --- a/dpub-aam/index.html +++ b/dpub-aam/index.html @@ -5,6 +5,7 @@ + + @@ -109,7 +110,7 @@ CRD: "https://www.w3.org/TR/wai-aria-practices-1.2/", REC: "https://www.w3.org/TR/wai-aria-practices-1.2/", }, - preProcess: [linkCrossReferences], + preProcess: [linkCrossReferences, getParticipants], postProcess: [ariaAttributeReferences], definitionMap: [], xref: ["core-aam", "accname", "wai-aria", "dom", "infra"], @@ -4466,25 +4467,15 @@

Substantive changes since the Acknowledgments

The following people contributed to the development of this document:

- -