axe-core 4.2.4 → 4.3.0

package/doc/accessibility-supported.md

@@ -1,37 +0,0 @@
-# How we make decisions on rules
-
-In order to adhere to the manifesto and at the same time be useful to developers and content creators, we evaluate all rules according to strict normative WCAG 2 interpretation. We also pay very strong attention to the normative portion of WCAG 2 known as [accessibility supported](https://www.w3.org/TR/WCAG20/#accessibility-supporteddef).
-
-## Accessibility supported
-
-Accessibility supported means that in order for a technique to pass, it must work in some predefined set of browsers and assistive technologies. For axe-core this means that for a screen reader, browser, or environment to be added to the list of supported combinations, the following two criteria must be met:
-
-1. Be used by more than 1% of users (currently extrapolated from the [WebAims Screen Reader User Survey](https://webaim.org/projects/screenreadersurvey8/#browsercombos))
-1. Introduce new coverage for a screen reader, browser, or environment not currently accessibility supported
-
-We currently test the following AT combinations for support
-
-1. VoiceOver and Safari on OS X
-1. VoiceOver and Safari on iOS
-1. JAWS and IE11 on Windows
-1. JAWS and Chrome on Windows
-1. NVDA and Firefox on Windows
-1. Talkback and Chrome on Android
-1. Dragon and Firefox on Windows
-
-## Impact on ARIA
-
-For some technologies, like ARIA, we have a dilemma in that the spec is approved before supported and we have to weigh a balance between something that conforms to the spec, but does not yet work. When we do this, we favor the accessibility supported principle over the spec but we temper this with the impact of using an unsupported feature. Here is how we do this:
-
-1. If the feature's use is supported by all platforms: allow, else
-1. If the feature's use does not have a negative impact on accessibility: allow, else
-1. If we can detect a fallback: allow, else
-1. disallow the feature's use until it is supported
-
-In addition, we disallow invalid attributes starting with `aria-` and invalid attribute values as these are highly likely to have a negative impact on accessibility because of the scenarios under which these are likely to occur (this is so we can act as a useful linting tool for developers).
-
-## Best practices
-
-We recognize that there are best practices that significantly improve the usability of application, even though they are not strictly required in order to conform with WCAG 2. We develop the best practice rules to help content developers to identify these and adhere to them.
-
-We recognize that this topic is somewhat controversial and the rules we have represent Deque's opinion on what constitutes a best practice.

package/doc/act-rules-format.md

@@ -1,37 +0,0 @@
-# W3C Standardized Rules
-
-Deque Systems is one of leading organizations in the development of standardized accessibility conformance testing rules. The [axe-core rules proposal format](./rule-proposal.md) is an adaptation of the [Accessibility Conformance Testing Rules Format](https://www.w3.org/TR/act-rules-format/).
-
-There are two ways a rule written in the axe-core rule format can be transformed into the ACT Rules format:
-
-## Method 1: Create a single rule
-
-This method is useful for rules with a small number of checks.
-
-1. Add the test input type to it: `rendered page`
-2. Add an `assumptions` section, add possible assumptions to it
-3. Add an `outcomes` section, describing the different possible outcomes of the rule
-4. Add a `Validation Tests` section, that links to the integration tests
-5. Update the check to return pass/fail/cantTell instead of true/false/undefined
-6. Add control flow to the checks:
-
-- `any` checks should only return `fail` in the last step. All steps leading up to it either return `pass` or say `continue to the next step`.
-- `all` and `none` checks should only return `pass` in the last step. All steps leading up to it either return `fail` or say `continue to the next step`.
-
-7. Rename `checks` to `steps` and add a `step X` (where X is the step number) to the heading with the check name.
-8. Replace the `tags` section with a `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags.
-
-## Method 2: Create a rule group
-
-This method is useful for larger rules with `any` checks. This effectively turns every check into its own rule, and turns the rule into a rule group.
-
-1. Copy each check into a new document
-2. Add a `steps` heading
-3. Add the test input type to it: `rendered page`
-4. Add an `assumptions` section, add possible assumptions to it
-5. Add an `outcomes` section, describing the different possible outcomes of the rule
-6. Copy the `selector` section from the original rule into the new rule documents
-7. Update the check to return pass/fail/cantTell instead of true/false/undefined
-8. Add a `Validation Tests` section, that links to only those integration tests relevant for this check (now a new rule).
-9. Indicate that the new rule is part of a group, using the original axe-core rule ID as the group name.
-10. Replace the `tags` section with a `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags.

package/doc/aria-supported.md

@@ -1,13 +0,0 @@
-# ARIA Roles and Attributes unsupported in axe-core.
-
-It can be difficult to know which features of web technologies are accessible across different platforms, and with different screen readers and other assistive technologies. Axe-core does some of this work for you, by raising issues when accessibility features are used that are known to cause problems.
-
-This page contains a list of ARIA 1.1 features that axe-core raises as unsupported. For more information, read [We’ve got your back with “Accessibility Supported” in axe](https://www.deque.com/blog/weve-got-your-back-with-accessibility-supported-in-axe/).
-
-For a detailed description about how accessibility support is decided, see [How we make decisions on rules](accessibility-supported.md).
-
-## Attributes
-
-| aria-attribute   | axe-core support |
-| ---------------- | ---------------- |
-| aria-describedat | No               |

package/doc/backwards-compatibility-doc.md

@@ -1,94 +0,0 @@
-# Backwards Compatibility in axe-core
-
-## What is part of the public axe-core API?
-
-The axe-core API includes:
-
-- Any APIs documented here: [https://github.com/dequelabs/axe-core/blob/develop/doc/API.md](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md)
-- The selectors generated and included in the node information in the results arrays for any given HTML page
-- The JSON structures passed into and out of any API functions
-- Any functions in the `axe.utils` and `axe.commons` collections that are used by one of our standard rules (this document refers to these as the “Public Utils”). This includes use in any of the “matches”, “eval” and “after” functions.
-- The implicit function signature of the matches, eval and after functions (the names of the parameters that are passed-to the functions and the values returned by them)
-
-## What is not included in the public axe-core API?
-
-Any other function or attribute on the axe object is not considered part of the public API and is therefore not covered by the guarantee in this document.
-
-## What do we guarantee for the public axe-core API?
-
-We guarantee that the API signatures and the return values of functions will not break in patch or minor release versions except that we may add items to JSON structures in minor releases or override parameters. We will not remove items from JSON structures.
-
-In a minor release, we may change the implementation of Public Utils to fix bugs or improve performance. This means that a call to a Public Util may return a different value across patch versions.
-
-We will not add or remove rules in a patch release. We will not add support for new technologies in a patch release. We will endeavour to return the exact same results across patch releases with the exception of changes that are due to bug fixes. This means that the likelihood of a patch release finding issues on a page that was clean in a previous release is very close to zero but not zero.
-
-In a minor release, we may add support for new technologies in the Public Utils or in existing rules and we may add or disable rules. We may also change an experimental rule to become a standard rule (essentially equivalent to adding rule). This means that pages that did not return violations in a particular minor release may return violations in a subsequent release. Rule tags, including the "wcag\*" tags, and whether or not something is reported as best-practice can be changed in minor releases.
-
-If the HTML page is unchanged, calls to the analysis function(s) when compared across minor or patch releases will return the same exact selector for the nodes in any of the result arrays. If the HTML page has changed, it is possible for the selector to be different but it is not guaranteed that the selector will be different.
-
-APIs may be deprecated in a major or minor release. APIs that have been deprecated for 6 months or more will be removed in the next major release.
-
-A major or a minor release may introduce new Public Utils.
-
-Major releases may remove rules.
-
-### Table: Summary of What Deque Guarantees with Public axe-core API
-
-|                                               | Major                                                   | Minor                 | Patch                      |
-| :-------------------------------------------- | :------------------------------------------------------ | :-------------------- | :------------------------- |
-| **New Technologies**                          |                                                         |                       |                            |
-| Support for new technologies\*                | May add support                                         | May add support       | Will not add support       |
-| **APIS**                                      |                                                         |                       |                            |
-| API signatures and return values of functions | May break                                               | Will not break        | Will not break             |
-| APIs deprecated                               | May be deprecated                                       | May be deprecated     | Will not be deprecated     |
-| APIs removed                                  | May be removed (will remove previously deprecated APIs) | Will not be removed   | Will not be removed        |
-| **Public Utils**                              |                                                         |                       |                            |
-| Implementation of Public Utils                | May change                                              | May change            | Will not change            |
-| New public Utils                              | May add                                                 | May add               | Will not add               |
-| **Rules**                                     |                                                         |                       |                            |
-| Add rules                                     | May add                                                 | May add               | Will not add               |
-| Disable or remove rules                       | May remove (will remove previously deprecated rules)    | May disable or remove | Will not disable or remove |
-| Rule tags                                     | May add or remove                                       | May add or remove     | Will not change            |
-| Deprecate rules                               | May deprecate                                           | May deprecate         | Will not deprecate         |
-
-\*_New OSes, Browsers, ATs, new standards (e.g. introduction of ARIA), new versions of standards (e.g. WCAG 2.1)_
-
-## Implications
-
-### Breaking Builds
-
-Patch release upgrades can be applied in CI environments with a high degree of certainty that breakages will not be due to changes in the release. The chance is, however, not zero.
-
-### Custom Rules
-
-A custom rule configuration (with-or-without custom rules) is guaranteed to run on any newer version that shares the same major version number as the version for which it was created. A custom rule configuration (with-or-without custom rules) is not guaranteed to work with an older version of axe-core than the version for which it was created.
-
-You can write custom rules that utilize the Public Utils and the parameters that are passed to a check function, secure in the knowledge that the API will not change unless a major version is released.
-
-However, because we can introduce new rules, it is possible that a custom rule configuration will return additional results when run against a new minor release and may return different results when run against a newer patch release.
-
-A custom rule configuration may return different results (more or fewer) when run on a newer patch release due to bug fixes.
-
-A major release may completely break a custom rule or even all custom rules because of a change to any of the APIs.
-
-### Table: Implication of axe-core Updates on Custom Rule Function
-
-| Axe-core Release Semantic Version              | Example | Simple Custom Rules    | Complex Custom Rules   |
-| :--------------------------------------------- | :------ | :--------------------- | :--------------------- |
-| Prior release (different major release number) | 1.3.4   | Not guaranteed to work | Not guaranteed to work |
-| Release used to create custom rules            | 2.0.0   | Guaranteed to work     | Guaranteed to work     |
-| Next release (minor release)                   | 2.1.0   | Guaranteed to work\*   | Guaranteed to work\*   |
-| Next +1 release (patch release)                | 2.1.1   | Guaranteed to work\*   | Guaranteed to work\*   |
-| Next +2 release (major release)                | 3.0.0   | Not guaranteed to work | Not guaranteed to work |
-
-\*_Minor and patch releases will not break custom rules, but testing results may vary from those tests performed with previous minor and patch releases of axe-core. There may be inconsistencies between what Attest reports and what Comply reports._
-
-Please note that with even small changes in versions for simple custom rules, there may be inconsistencies between what Attest reports and what Comply reports. For best results, in both cases, versions should match exactly.
-
-### Tracking Issues Over Time
-
-Many systems attempt to identify unique issues using a combination of the page and state, the rule-id and the selector to track an issue across time and across calls to the analysis functions. This will work reliably across patch releases. This could break if a rule is removed or split up across minor releases. In a major release, this could break for the additional reason of a possible change in the selector generation (this did happen in the changes between 2.6.x and 3.x).
-
-### Comply
-
-Comply has the ability to add labels and comments to issues and to mark issues as ignored. Comply will lose this information when it is not able to track issues across time. This means that historical issue information may be lost when upgrading to a newer major version of axe-core.

package/doc/check-message-template.md

@@ -1,124 +0,0 @@
-# Check Message Template
-
-Axe-core uses a custom template to handle dynamic check messages (messages that use the `data` property to output values or to determine which message to display). The structure for the messages is as follows:
-
-## Simple Message
-
-A simple message is just a string that doesn't use the `data` property. Most checks uses this format.
-
-```json
-{
-  "messages": {
-    "pass": "Simple message for a passing check"
-  }
-}
-```
-
-## Message with Data
-
-A message can also use the `data` property to output information from the check. If `data` is a String, Boolean, or Number, you can use the syntax `${data}` to have the message output the value of the `data` property.
-
-```js
-// check.js
-this.data(10);
-
-// check.json
-{
-    "messages": {
-        "pass": "Passed with a value of ${data}"
-        // => "Passed with a value of 10"
-    }
-}
-```
-
-If `data` is an object, you can access properties of the object using the syntax `${data.propName}`.
-
-```js
-// check.js
-this.data({
-  contrast: '3:1',
-  fontSize: '12px'
-});
-
-// check.json
-{
-    "messages": {
-        "fail": "Color-contrast failed with a contrast of ${data.contrast} and font size of ${data.fontSize}"
-        // => "Color-contrast failed with a contrast of 3:1 and font size of 12px"
-    }
-}
-```
-
-## Singular and Plural Messages
-
-If the message needs to to know how many items are in the `data` property to determine the type of language to use (singular or plural), you can structure the message to use `singular` and `plural` properties. Use the syntax `${data.values}` to have the message output a comma-separated list of the items (`data.values` is provided by the template code for you).
-
-```js
-// check.js
-this.data(['item1', 'item2']);
-
-// check.json
-{
-    "messages": {
-        "fail": {
-            "singular": "Attribute ${data.values} is not allowed",
-            "plural": "Attributes: ${data.values} are not allowed"
-        }
-        // => Attributes: item1, item2 are not allowed
-    }
-}
-```
-
-## Message Determined by Data
-
-Lastly, a message can use the `data` property to determine which message to display. Structure the message to use properties whose keys are the possible values of `data.messageKey`. You should also provide a `default` message that will be displayed if `messageKey` is not set.
-
-```js
-// check.js
-this.data({
-    messageKey: 'imgNode'
-});
-
-// check.json
-{
-    "messages": {
-        "incomplete": {
-            "default": "Color-contrast could not be determined"
-            "bgImage": "Element's background color could not be determined due to a background image",
-            "imgNode": "Element's background color could not be determined because element contains an image node"
-        }
-        // => Element's background color could not be determined because element contains an image node
-    }
-}
-```
-
-The messages can still use the syntax `${data.propName}` to access other properties on the `data` property.
-
-## Migrating From doT.js Template in Translations
-
-Axe-core use to use doT.js for it's temple library. To migrate from doT.js in a translation file, do the following:
-
-- If the message used `{{=it.data}}` or `{{=it.data.propName}}`, change the message to use the syntax `${data}` or `${data.propName}`.
-
-```diff
-{
-    "messages": {
--       "incomplete": "Check that the <label> does not need be part of the ARIA {{=it.data}} field's name"
-+       "incomplete": "Check that the <label> does not need be part of the ARIA ${data} field's name"
-    }
-}
-```
-
-- If the message used `{{=it.data && it.data.length` to determine using singular or plural language, change the message structure of the message to instead use the `singular` and `plural` properties. Replace `{{=it.data.join(', ')}}` with `${data.values}`.
-
-```diff
-{
-    "messages": {
--       "fail": "Attribute{{=it.data && it.data.length > 1 ? 's' : ''}} {{=it.data.join(', ')}} {{=it.data && it.data.length > 1 ? 'are' : ' is'}} not allowed
-+       "fail": {
-+           "singular": "Attribute ${data.values} is not allowed",
-+           "plural": "Attributes: ${data.values} are not allowed"
-+       }
-    }
-}
-```