# HTML-Validate W3C data

This project contains scraped data from W3C specifications:

- WAI-ARIA

This package is not meant for public consumption and breaking changes can occur between any version.
Use at your own risk!

## WAI-ARIA

The package provides machine-readable data about WAI-ARIA roles, properties, and states scraped from the W3C specification.

### Usage

You can access ARIA data in two ways.

Use the factory function to get ARIA data for a specific version:

```ts
import { getAriaData } from "@html-validate/w3c-data/aria";

// Get data for a specific version
const { getRoleData } = getAriaData("latest"); // "latest", "1.3" or "1.2"

// Use the data
const alert = getRoleData("alert");
console.log(alert?.category); // "live"
```

Or import specific ARIA versions directly for better tree-shaking:

```ts
// Import latest ARIA data
import { getRoleData } from "@html-validate/w3c-data/aria-latest";
```

```ts
// Or import specific versions
import { getRoleData } from "@html-validate/w3c-data/aria-1.3";
```

### Available versions

- `"latest"` - Latest editor's draft from W3C (https://w3c.github.io/aria/)
- `"1.3"` - WAI-ARIA 1.3 (https://www.w3.org/TR/wai-aria-1.3/)
- `"1.2"` - WAI-ARIA 1.2 (https://www.w3.org/TR/wai-aria-1.2/)

### Data structure

The `getRoleData()` helper returns a `NormalizedRole` object:

```ts
const alert = getRoleData("alert");
console.log(alert?.category); // "live"
console.log(alert?.superclasses); // ["section"]
console.log(alert?.properties["aria-atomic"]); // { inherited: true, required: false, deprecated: false, default: "true" }
```

Each role contains:

- `role` - Role name
- `category` - Role category (`abstract`, `widget`, `structure`, `landmark`, `live`, or `window`)
- `superclasses` - List of roles this role inherits from
- `subclasses` - List of roles that inherit from this role
- `properties` - Available ARIA properties for this role
- `states` - Available ARIA states for this role
- `name` - Accessible name requirements
  - `fromAuthor` - Name can be set from author
  - `fromContents` - Name can be set from content
  - `prohibited` - Name must not be set
  - `required` - Name is required
- `requiredParent` - List of required parent roles
- `allowedChildren` - List of allowed child roles
- `childrenPresentational` - Whether DOM descendants are presentational

Each property and state in the `properties` and `states` objects contains:

- `inherited` (boolean) - Whether the attribute is inherited from a superclass role
- `required` (boolean) - Whether the attribute is required for this role
- `deprecated` (boolean) - Whether the attribute is deprecated
- `default` (string | undefined) - The default value of the attribute, if any

Note: All property and state keys include the `aria-` prefix (e.g., `"aria-atomic"`, `"aria-expanded"`).

### Helper functions and types

The package provides helper functions and types for working with ARIA roles:

- `isValidRole(role: string): role is AriaRole`: checks if a string is a valid ARIA role name.
- `getRoleData(role: AriaRole): NormalizedRole`: get ARIA role metadata for given role.
- `getRoleData(role: string): NormalizedRole | null`: get ARIA role metadata for given role.

## Versioning

This package does **not** follow semantic versioning but rather the date of the last time it was scraped.
Breaking changes can occur between any changes.