@markuplint/ml-spec 3.0.0-alpha.2 → 3.0.0-alpha.27

package/README.md

@@ -1,13 +1,18 @@
 # @markuplint/ml-spec
 
 [![npm version](https://badge.fury.io/js/%40markuplint%2Fml-spec.svg)](https://www.npmjs.com/package/@markuplint/ml-spec)
-[![Build Status](https://travis-ci.org/markuplint/markuplint.svg?branch=main)](https://travis-ci.org/markuplint/markuplint)
-[![Coverage Status](https://coveralls.io/repos/github/markuplint/markuplint/badge.svg?branch=main)](https://coveralls.io/github/markuplint/markuplint?branch=main)
 
 ## Install
 
-```sh
+[`markuplint`](https://www.npmjs.com/package/markuplint) package includes this package.
+
+<details>
+<summary>If you are installing purposely, how below:</summary>
+
+```shell
 $ npm install @markuplint/ml-spec
 
 $ yarn add @markuplint/ml-spec
 ```
+
+</details>

package/lib/dom-traverse/get-computed-aria-props.d.ts

@@ -0,0 +1,12 @@
+import type { ARIAVersion, MLMLSpec } from '../types';
+type ARIAProps = Record<string, ARIAProp>;
+type ARIAProp = {
+    name: string;
+    value: string | undefined;
+    required: boolean;
+    deprecated: boolean;
+    from: ARIAPropReferenceType;
+};
+type ARIAPropReferenceType = 'default' | 'html-attr' | 'aria-attr';
+export declare function getComputedAriaProps(specs: Readonly<MLMLSpec>, el: Element, version: ARIAVersion): ARIAProps;
+export {};

package/lib/dom-traverse/get-computed-aria-props.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getComputedAriaProps = void 0;
+const aria_specs_1 = require("../specs/aria-specs");
+const get_computed_role_1 = require("./get-computed-role");
+function getComputedAriaProps(specs, el, version) {
+    const ariaSpecs = (0, aria_specs_1.ariaSpecs)(specs, version);
+    const { role } = (0, get_computed_role_1.getComputedRole)(specs, el, version);
+    if (!role) {
+        return {};
+    }
+    const props = {};
+    role.ownedProperties.forEach(ownedProp => {
+        var _a;
+        const spec = ariaSpecs.props.find(propSpec => propSpec.name === ownedProp.name);
+        if (!spec) {
+            return;
+        }
+        if (el.hasAttribute(spec.name)) {
+            const attrValue = el.getAttribute(spec.name);
+            if (attrValue && isValidAriaValue(spec, role.name, attrValue, spec.enum)) {
+                props[ownedProp.name] = {
+                    name: ownedProp.name,
+                    value: attrValue,
+                    deprecated: !!spec.deprecated,
+                    required: !!ownedProp.required,
+                    from: 'aria-attr',
+                };
+                return;
+            }
+        }
+        const equivalentHtmlAttr = (_a = spec.equivalentHtmlAttrs) === null || _a === void 0 ? void 0 : _a[0];
+        if (equivalentHtmlAttr && el.hasAttribute(equivalentHtmlAttr.htmlAttrName)) {
+            const value = equivalentHtmlAttr.value === null
+                ? el.getAttribute(equivalentHtmlAttr.htmlAttrName)
+                : equivalentHtmlAttr.value;
+            if (value != null) {
+                props[ownedProp.name] = {
+                    name: ownedProp.name,
+                    value,
+                    deprecated: !!spec.deprecated,
+                    required: !!ownedProp.required,
+                    from: 'html-attr',
+                };
+                return;
+            }
+        }
+        let defaultValue = spec.defaultValue;
+        /**
+         * @see https://www.w3.org/TR/html-aria/#el-h1-h6
+         */
+        if (ownedProp.name === 'aria-level' && /^H[1-6]$/.test(el.nodeName)) {
+            defaultValue = el.nodeName.replace('H', '');
+        }
+        props[ownedProp.name] = {
+            name: ownedProp.name,
+            value: defaultValue,
+            deprecated: !!spec.deprecated,
+            required: !!ownedProp.required,
+            from: 'default',
+        };
+    });
+    return props;
+}
+exports.getComputedAriaProps = getComputedAriaProps;
+function isValidAriaValue(spec, role, value, enumList) {
+    let type = spec.value;
+    if (spec.conditionalValue) {
+        for (const cond of spec.conditionalValue) {
+            if (cond.role.includes(role)) {
+                type = cond.value;
+            }
+        }
+    }
+    value = (value !== null && value !== void 0 ? value : '').trim();
+    switch (type) {
+        case 'string': {
+            return true;
+        }
+        case 'ID reference':
+        case 'ID reference list':
+        case 'URI': {
+            return !!value;
+        }
+        case 'integer':
+        case 'number': {
+            return !isNaN(parseFloat(value));
+        }
+        case 'token':
+        case 'token list': {
+            if (!enumList.length) {
+                throw new Error('Need an enum list in token and token list types');
+            }
+            return enumList.includes(value.toLowerCase());
+        }
+        case 'tristate': {
+            return ['true', 'false', 'mixed'].includes(value.toLowerCase());
+        }
+        case 'true/false': {
+            return ['true', 'false'].includes(value.toLowerCase());
+        }
+        case 'true/false/undefined': {
+            return ['true', 'false', 'undefined'].includes(value.toLowerCase());
+        }
+    }
+}

package/lib/dom-traverse/get-explicit-role.js

@@ -13,7 +13,7 @@ function getExplicitRole(specs, el, version) {
     /**
      * Resolve from values and **Handling Author Errors**
      *
-     * @see https://w3c.github.io/aria/#document-handling_author-errors_roles
+     * @see https://w3c.github.io/aria/#document-handling_author-errors
      */
     for (const roleName of roleNames) {
         const spec = (0, get_role_spec_1.getRoleSpec)(specs, roleName, namespaceURI, version);

package/lib/dom-traverse/is-exposed.d.ts

@@ -0,0 +1,11 @@
+import type { ARIAVersion, MLMLSpec } from '../types';
+/**
+ * Detect including/excluding from the Accessibility Tree
+ *
+ * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
+ *
+ * @param specs
+ * @param el
+ * @param version
+ */
+export declare function isExposed(el: Element, specs: Readonly<MLMLSpec>, version: ARIAVersion): boolean;

package/lib/dom-traverse/is-exposed.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExposed = void 0;
+const aria_specs_1 = require("../specs/aria-specs");
+const is_palpable_elements_1 = require("../specs/is-palpable-elements");
+const is_presentational_1 = require("../specs/is-presentational");
+const get_computed_role_1 = require("./get-computed-role");
+/**
+ * Detect including/excluding from the Accessibility Tree
+ *
+ * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
+ *
+ * @param specs
+ * @param el
+ * @param version
+ */
+function isExposed(el, specs, version) {
+    // According to WAI-ARIA
+    if (isExcluding(el, specs, version)) {
+        return false;
+    }
+    // According to HTML and SVG Specs with **the author's interpretation**
+    {
+        if (!(0, is_palpable_elements_1.isPalpableElement)(el, specs, { extendsSvg: true, extendsExposableElements: true })) {
+            return false;
+        }
+    }
+    // According to WAI-ARIA
+    {
+        const exposable = isIncluding(el, specs, version);
+        if (exposable) {
+            return true;
+        }
+    }
+    // Default
+    return true;
+}
+exports.isExposed = isExposed;
+/**
+ * Excluding Elements from the Accessibility Tree
+ *
+ * @see https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion
+ *
+ * @param specs
+ * @param el
+ * @param version
+ */
+function isExcluding(el, specs, version) {
+    /**
+     * The following elements are not exposed via the accessibility API and
+     * user agents MUST NOT include them in the accessibility tree:
+     * - Elements, including their descendent elements,
+     *   that have host language semantics specifying
+     *   that the element is not displayed, such as CSS display:none,
+     *   visibility:hidden, or the HTML hidden attribute.
+     */
+    {
+        let currentEl = el;
+        while (currentEl) {
+            if (hasDisplayNodeOrVisibilityHidden(currentEl) || currentEl.hasAttribute('hidden')) {
+                return true;
+            }
+            currentEl = currentEl.parentElement;
+        }
+    }
+    /**
+     * - Elements with none or presentation as the first role in the role attribute.
+     *   However, their exclusion is conditional. In addition,
+     *   the element's descendants and text content are generally included.
+     *   These exceptions and conditions are documented in the presentation (role)
+     *   section.
+     */
+    if ((0, is_presentational_1.isPresentational)((el.getAttribute('role') || '').split(/\s+/)[0])) {
+        return true;
+    }
+    /**
+     * If not already excluded from the accessibility tree per the above rules,
+     * user agents SHOULD NOT include the following elements
+     * in the accessibility tree:
+     * - Elements, including their descendants, that have aria-hidden set to true.
+     *   In other words, aria-hidden="true" on a parent overrides aria-hidden="false"
+     *   on descendants.
+     */
+    {
+        let currentEl = el;
+        while (currentEl) {
+            if (currentEl.getAttribute('aria-hidden') === 'true') {
+                return true;
+            }
+            currentEl = currentEl.parentElement;
+        }
+    }
+    /**
+     * - Any descendants of elements that have the characteristic
+     *   "Children Presentational: True" unless the descendant
+     *   is not allowed to be presentational because it meets one of
+     *   the conditions for exception described in
+     *   Presentational Roles Conflict Resolution.
+     *   However, the text content of any excluded descendants is included.
+     */
+    {
+        let currentEl = el.parentElement;
+        while (currentEl) {
+            const { role } = (0, get_computed_role_1.getComputedRole)(specs, currentEl, version);
+            if (role === null || role === void 0 ? void 0 : role.childrenPresentational) {
+                return true;
+            }
+            currentEl = currentEl.parentElement;
+        }
+    }
+    return false;
+}
+/**
+ * Including Elements in the Accessibility Tree
+ *
+ * If not excluded from or marked as hidden in the accessibility tree
+ * per the rules above in Excluding Elements in the Accessibility Tree,
+ * user agents MUST provide an accessible object in the accessibility tree
+ * for DOM elements that meet any of the following criteria:
+ *
+ * @see https://www.w3.org/TR/wai-aria-1.2/#tree_inclusion
+ *
+ * @param specs
+ * @param el
+ * @param version
+ */
+function isIncluding(el, specs, version) {
+    /**
+     * > **meet any** of the following criteria:
+     */
+    const results = [];
+    /**
+     * Elements that are not hidden and may fire an accessibility API event,
+     * including:
+     * - Elements that are currently focused, even if the element or one of
+     *   its ancestor elements has its aria-hidden attribute set to true.
+     */
+    // 🚫 Can't detect the element is focused.
+    // results.push(true);
+    /**
+     * - Elements that are a valid target of an aria-activedescendant attribute.
+     */
+    // TODO: Compute aria-activedescendant.
+    // results.push(true);
+    /**
+     * Elements that have an explicit role or a global WAI-ARIA attribute and
+     * do not have aria-hidden set to true.
+     * (See Excluding Elements in the Accessibility Tree for
+     * additional guidance on aria-hidden.)
+     */
+    if (el.getAttribute('aria-hidden') !== 'true') {
+        const globalAria = (0, aria_specs_1.ariaSpecs)(specs, version).props.filter(prop => prop.isGlobal);
+        const { role } = (0, get_computed_role_1.getComputedRole)(specs, el, version);
+        // Has an explicit role
+        if (role && !role.isImplicit) {
+            results.push(true);
+        }
+        // Has a global WAI-ARIA attribute
+        for (const attr of Array.from(el.attributes)) {
+            if (globalAria.some(aria => aria.name === attr.localName)) {
+                results.push(true);
+                break;
+            }
+        }
+    }
+    /**
+     * Elements that are not hidden and have an ID that is referenced
+     * by another element via a WAI-ARIA property.
+     */
+    // TODO: Compute refering ID.
+    // results.push(true);
+    return results.includes(true);
+}
+function hasDisplayNodeOrVisibilityHidden(el) {
+    const style = el.getAttribute('style');
+    if (!style) {
+        return false;
+    }
+    // TODO: Improve accuracy
+    return /display\s*:\s*none|visibility\s*:\s*hidden/gi.test(style);
+}

package/lib/index.d.ts

@@ -1,16 +1,21 @@
 export * from './dom-traverse/accname-computation';
 export * from './dom-traverse/get-attr-specs';
+export * from './dom-traverse/get-computed-aria-props';
 export * from './dom-traverse/get-computed-role';
 export * from './dom-traverse/get-content-model';
 export * from './dom-traverse/get-implicit-role';
 export * from './dom-traverse/get-permitted-roles';
 export * from './dom-traverse/get-spec';
 export * from './dom-traverse/has-required-owned-elements';
+export * from './dom-traverse/is-exposed';
 export * from './dom-traverse/may-be-focusable';
 export * from './specs/aria-specs';
 export * from './specs/content-model-category-to-tag-names';
 export * from './specs/get-role-spec';
 export * from './specs/get-spec-by-tag-name';
+export * from './specs/is-nothing-content-model';
+export * from './specs/is-palpable-elements';
+export * from './specs/is-void-element';
 export * from './specs/schema-to-spec';
 export * from './types';
 export * from './types/aria';

package/lib/index.js

@@ -3,17 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./dom-traverse/accname-computation"), exports);
 tslib_1.__exportStar(require("./dom-traverse/get-attr-specs"), exports);
+tslib_1.__exportStar(require("./dom-traverse/get-computed-aria-props"), exports);
 tslib_1.__exportStar(require("./dom-traverse/get-computed-role"), exports);
 tslib_1.__exportStar(require("./dom-traverse/get-content-model"), exports);
 tslib_1.__exportStar(require("./dom-traverse/get-implicit-role"), exports);
 tslib_1.__exportStar(require("./dom-traverse/get-permitted-roles"), exports);
 tslib_1.__exportStar(require("./dom-traverse/get-spec"), exports);
 tslib_1.__exportStar(require("./dom-traverse/has-required-owned-elements"), exports);
+tslib_1.__exportStar(require("./dom-traverse/is-exposed"), exports);
 tslib_1.__exportStar(require("./dom-traverse/may-be-focusable"), exports);
 tslib_1.__exportStar(require("./specs/aria-specs"), exports);
 tslib_1.__exportStar(require("./specs/content-model-category-to-tag-names"), exports);
 tslib_1.__exportStar(require("./specs/get-role-spec"), exports);
 tslib_1.__exportStar(require("./specs/get-spec-by-tag-name"), exports);
+tslib_1.__exportStar(require("./specs/is-nothing-content-model"), exports);
+tslib_1.__exportStar(require("./specs/is-palpable-elements"), exports);
+tslib_1.__exportStar(require("./specs/is-void-element"), exports);
 tslib_1.__exportStar(require("./specs/schema-to-spec"), exports);
 tslib_1.__exportStar(require("./types"), exports);
 tslib_1.__exportStar(require("./types/aria"), exports);

package/lib/specs/get-attr-specs.d.ts

@@ -1,7 +1,7 @@
 import type { MLMLSpec, Attribute } from '../types';
 import type { NamespaceURI } from '@markuplint/ml-ast';
 export declare function getAttrSpecs(localName: string, namespace: NamespaceURI | null, schema: MLMLSpec): Attribute[] | null;
-declare type HasName = {
+type HasName = {
     name: string;
 };
 export declare function nameCompare(a: HasName | string, b: HasName | string): 1 | -1 | 0;

package/lib/specs/is-nothing-content-model.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @see https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model
+ * @see https://html.spec.whatwg.org/multipage/indices.html#elements-3
+ */
+export declare function isNothingContentModel(el: Element): boolean;

package/lib/specs/is-nothing-content-model.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNothingContentModel = void 0;
+const is_void_element_1 = require("./is-void-element");
+/**
+ * @see https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model
+ * @see https://html.spec.whatwg.org/multipage/indices.html#elements-3
+ */
+function isNothingContentModel(el) {
+    return (0, is_void_element_1.isVoidElement)(el) || ['iframe', 'template'].includes(el.localName);
+}
+exports.isNothingContentModel = isNothingContentModel;

package/lib/specs/is-palpable-elements.d.ts

@@ -0,0 +1,5 @@
+import type { MLMLSpec } from '../types';
+export declare function isPalpableElement(el: Element, specs: Readonly<MLMLSpec>, options?: {
+    extendsSvg?: boolean;
+    extendsExposableElements?: boolean;
+}): boolean;

package/lib/specs/is-palpable-elements.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPalpableElement = void 0;
+/**
+ * Exposable content models and elements
+ *
+ * **WARNING**:
+ * This implementation is through the author's interpretation.
+ * Want a issue request.
+ * https://github.com/markuplint/markuplint/issues/new
+ *
+ * @see https://html.spec.whatwg.org/multipage/indices.html#elements-3
+ */
+const exposableElementsThatAreNoBelongingAModel = [
+    'body',
+    'dd',
+    'dt',
+    'figcaption',
+    'html',
+    'legend',
+    'li',
+    'optgroup',
+    'option',
+    'rp',
+    'rt',
+    'summary',
+    'tbody',
+    'td',
+    'tfoot',
+    'th',
+    'thead',
+    'tr',
+];
+function isPalpableElement(el, specs, options) {
+    var _a, _b;
+    const conditions = [((_a = specs.def['#contentModels']['#palpable']) === null || _a === void 0 ? void 0 : _a.join(',')) || ''];
+    if ((options === null || options === void 0 ? void 0 : options.extendsSvg) !== false /* default true */) {
+        conditions.push(((_b = specs.def['#contentModels']['#SVGRenderable']) === null || _b === void 0 ? void 0 : _b.join(',')) || '');
+    }
+    if (options === null || options === void 0 ? void 0 : options.extendsExposableElements /* default false */) {
+        conditions.push(exposableElementsThatAreNoBelongingAModel.join(','));
+    }
+    return conditions.some(condition => {
+        return el.matches(condition);
+    });
+}
+exports.isPalpableElement = isPalpableElement;

package/lib/specs/is-void-element.d.ts

@@ -0,0 +1 @@
+export declare function isVoidElement(el: Element): boolean;

package/lib/specs/is-void-element.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVoidElement = void 0;
+/**
+ * @see https://html.spec.whatwg.org/multipage/syntax.html#void-elements
+ */
+const voidElements = [
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'source',
+    'track',
+    'wbr',
+];
+function isVoidElement(el) {
+    return voidElements.includes(el.localName);
+}
+exports.isVoidElement = isVoidElement;

package/lib/specs/schema-to-spec.d.ts

@@ -2,7 +2,7 @@ import type { ElementSpec, ExtendedSpec, MLMLSpec } from '../types';
 /**
  * Merging HTML-spec schema and extended spec schemas
  *
- * Ex: `@markuplint/html-spec` + `{ specs: ["@markuplint/vue-spec"] }` in configure files.
+ * Ex: `@markuplint/html-spec` + `{ specs: { "\\.vue$": "@markuplint/vue-spec" } }` in configure files.
  *
  * @param schemas `MLDocument.schemas`
  */

package/lib/specs/schema-to-spec.js

@@ -5,7 +5,7 @@ const merge_array_1 = require("../utils/merge-array");
 /**
  * Merging HTML-spec schema and extended spec schemas
  *
- * Ex: `@markuplint/html-spec` + `{ specs: ["@markuplint/vue-spec"] }` in configure files.
+ * Ex: `@markuplint/html-spec` + `{ specs: { "\\.vue$": "@markuplint/vue-spec" } }` in configure files.
  *
  * @param schemas `MLDocument.schemas`
  */

package/lib/types/aria.d.ts

@@ -6,11 +6,11 @@
 /**
  * If `false`, this mean is "No corresponding role".
  */
-export declare type ImplicitRole = false | string;
+export type ImplicitRole = false | string;
 /**
  * If `true`, this mean is "Any". If `false`, this mean is "No".
  */
-export declare type PermittedRoles = boolean | (string | {
+export type PermittedRoles = boolean | (string | {
     name: string;
     deprecated?: true;
     [k: string]: unknown;
@@ -22,7 +22,7 @@ export declare type PermittedRoles = boolean | (string | {
  * If set false:
  * > No role or aria-* attributes
  */
-export declare type PermittedARIAProperties = false | {
+export type PermittedARIAProperties = false | {
     global?: true;
     /**
      * Set true if the spec says "and any aria-* attributes applicable to the allowed roles."