dom-accessibility-api 0.6.3: computeAccessibleDescription, computeAccessibleName, getRole

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/dom-accessibility-api@0.6.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/dom-accessibility-api@0.6.3
Demonstrate these symbols/APIs:
  - computeAccessibleDescription
  - computeAccessibleName
  - getRole

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:00aab1ed985ea70f5ac9c24a3f78f9d375e60204595c241724c79a42ada739d5","contract":["getRole correctly computes implicit ARIA roles for standard HTML elements such as button, link, and heading","getRole prioritizes explicit role attribute over implicit role","computeAccessibleName resolves accessible name from aria-label with highest precedence","computeAccessibleName resolves accessible name from element subtree text and ignores prohibited naming roles","computeAccessibleName resolves accessible name referencing other elements via aria-labelledby","computeAccessibleDescription resolves accessible description via aria-describedby and aria-description attributes"],"goal":"verify pkg:npm/dom-accessibility-api@0.6.3","kind":"HOW","packages":["pkg:npm/dom-accessibility-api@0.6.3"],"schemaVersion":1,"symbols":["computeAccessibleDescription","computeAccessibleName","getRole"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/dom-accessibility-api@0.6.3"],"schemaVersion":1,"subject":"pkg:npm/dom-accessibility-api@0.6.3","symbols":["computeAccessibleDescription","computeAccessibleName","getRole"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-dom-accessibility-api",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-dom-accessibility-api",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "dom-accessibility-api": "0.6.3"
      }
    },
    "node_modules/dom-accessibility-api": {
      "version": "0.6.3",
      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.6.3.tgz",
      "integrity": "sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-dom-accessibility-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "description": "Clean-room verification for dom-accessibility-api",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "dom-accessibility-api": "0.6.3"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/dom-accessibility-api@0.6.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/dom-accessibility-api@0.6.3"
  ],
  "symbols": [
    "computeAccessibleDescription",
    "computeAccessibleName",
    "getRole"
  ]
}

import {
  computeAccessibleName,
  computeAccessibleDescription,
  getRole,
} from 'dom-accessibility-api';

/**
 * Creates a lightweight DOM Element node suitable for accessibility calculations in headless environments.
 * @param {string} tagName
 * @param {Record<string, string>} [attributes={}]
 * @param {Array<string | object>} [children=[]]
 * @param {Map<string, object>} [registry]
 * @returns {object}
 */
export function createMockElement(tagName, attributes = {}, children = [], registry = new Map()) {
  const attrs = new Map(Object.entries(attributes));

  const mockDoc = {
    defaultView: {
      getComputedStyle: () => ({
        getPropertyValue: () => '',
      }),
    },
    getElementById: (id) => registry.get(id) ?? null,
    querySelectorAll: () => [],
  };

  const element = {
    nodeType: 1, // ELEMENT_NODE
    ELEMENT_NODE: 1,
    TEXT_NODE: 3,
    tagName: tagName.toUpperCase(),
    localName: tagName.toLowerCase(),
    ownerDocument: mockDoc,
    childNodes: [],
    getAttribute(name) {
      return attrs.get(name) ?? null;
    },
    getAttributeNode(name) {
      if (!attrs.has(name)) return null;
      return { value: attrs.get(name) };
    },
    hasAttribute(name) {
      return attrs.has(name);
    },
    querySelectorAll() {
      return [];
    },
  };

  if (attributes.id) {
    registry.set(attributes.id, element);
  }

  element.childNodes = children.map((child) => {
    if (typeof child === 'string') {
      return {
        nodeType: 3, // TEXT_NODE
        ELEMENT_NODE: 1,
        TEXT_NODE: 3,
        textContent: child,
        ownerDocument: mockDoc,
        childNodes: [],
        parentNode: element,
      };
    }
    child.parentNode = element;
    return child;
  });

  return element;
}

/**
 * Computes the accessible name for an element.
 * @param {object} element
 * @param {object} [options]
 * @returns {string}
 */
export function getAccessibleName(element, options) {
  return computeAccessibleName(element, options);
}

/**
 * Computes the accessible description for an element.
 * @param {object} element
 * @param {object} [options]
 * @returns {string}
 */
export function getAccessibleDescription(element, options) {
  return computeAccessibleDescription(element, options);
}

/**
 * Resolves the computed accessibility role for an element.
 * @param {object} element
 * @returns {string | null}
 */
export function getAccessibleRole(element) {
  return getRole(element);
}

export { computeAccessibleName, computeAccessibleDescription, getRole };

import assert from 'node:assert/strict';
import {
  computeAccessibleName,
  computeAccessibleDescription,
  getRole,
  createMockElement,
  getAccessibleName,
  getAccessibleDescription,
  getAccessibleRole,
} from '../src/index.js';

// 1. getRole correctly computes implicit ARIA roles for standard HTML elements such as button, link, and heading
const buttonEl = createMockElement('button', {}, ['Click']);
assert.equal(getAccessibleRole(buttonEl), 'button', 'button element must have implicit role button');

const linkEl = createMockElement('a', { href: 'https://example.com' }, ['Link Text']);
assert.equal(getAccessibleRole(linkEl), 'link', 'anchor with href must have implicit role link');

const linkWithoutHref = createMockElement('a', {}, ['Plain anchor']);
assert.equal(getAccessibleRole(linkWithoutHref), null, 'anchor without href must have null role');

const headingEl = createMockElement('h1', {}, ['Main Heading']);
assert.equal(getAccessibleRole(headingEl), 'heading', 'h1 element must have implicit role heading');

const navEl = createMockElement('nav', {}, ['Navigation']);
assert.equal(getAccessibleRole(navEl), 'navigation', 'nav element must have implicit role navigation');

// 2. getRole prioritizes explicit role attribute over implicit role
const customRoleEl = createMockElement('div', { role: 'tab' }, ['Tab Item']);
assert.equal(getAccessibleRole(customRoleEl), 'tab', 'explicit role tab must be returned');

const overriddenButton = createMockElement('button', { role: 'menuitem' }, ['Item']);
assert.equal(getAccessibleRole(overriddenButton), 'menuitem', 'explicit role must override default button role');

// 3. computeAccessibleName resolves accessible name from aria-label with highest precedence
const ariaLabelBtn = createMockElement('button', { 'aria-label': 'Close Window' }, ['X']);
assert.equal(getAccessibleName(ariaLabelBtn), 'Close Window', 'aria-label must take precedence over text content');

const ariaLabelInput = createMockElement('input', { type: 'text', 'aria-label': 'Search Query' });
assert.equal(getAccessibleName(ariaLabelInput), 'Search Query', 'aria-label on input must be returned');

// 4. computeAccessibleName resolves accessible name from element subtree text and ignores prohibited naming roles
const textButton = createMockElement('button', {}, [
  createMockElement('span', {}, ['Save']),
  ' ',
  createMockElement('span', {}, ['Document']),
]);
assert.equal(getAccessibleName(textButton), 'Save Document', 'accessible name must accumulate subtree text');

const genericWithAriaLabel = createMockElement('div', { role: 'generic', 'aria-label': 'Forbidden Name' });
assert.equal(getAccessibleName(genericWithAriaLabel), '', 'generic role element prohibits naming and must return empty string');

// 5. computeAccessibleName resolves accessible name referencing other elements via aria-labelledby
const registry = new Map();
const labelPart1 = createMockElement('span', { id: 'lbl-first' }, ['John'], registry);
const labelPart2 = createMockElement('span', { id: 'lbl-last' }, ['Doe'], registry);
const labeledContainer = createMockElement('div', { role: 'region', 'aria-labelledby': 'lbl-first lbl-last' }, [], registry);

assert.equal(getAccessibleName(labeledContainer), 'John Doe', 'aria-labelledby must resolve referenced elements separated by space');

// 6. computeAccessibleDescription resolves accessible description via aria-describedby and aria-description attributes
const descRegistry = new Map();
const descNode = createMockElement('p', { id: 'help-text' }, ['Password must be at least 8 characters'], descRegistry);
const inputWithDesc = createMockElement('input', { type: 'password', 'aria-describedby': 'help-text' }, [], descRegistry);

assert.equal(
  getAccessibleDescription(inputWithDesc),
  'Password must be at least 8 characters',
  'aria-describedby must resolve text from target element'
);

const buttonWithDirectDesc = createMockElement('button', {
  'aria-label': 'Submit',
  'aria-description': 'Sends form data securely',
});
assert.equal(
  getAccessibleDescription(buttonWithDirectDesc),
  'Sends form data securely',
  'aria-description attribute must be resolved as accessible description'
);

console.log('All contract assertions passed successfully.');