html-standard 0.0.6 → 0.0.8

package/README.md

@@ -1,19 +1,90 @@
 # html-standard
 
-`html-standard` is a **work-in-progress** JavaScript/TypeScript library that provides structured data from the [HTML Living Standard](https://html.spec.whatwg.org/).
+A TypeScript library that provides utilities for working with the HTML Living Standard specification.
+
+> ⚠️ **Experimental**: This project is currently in an experimental stage and may introduce breaking changes frequently.
+
+## Features
+
+### Element API
+
+Create an element instance to access various HTML standard utilities:
+
+```typescript
+import { element } from "html-standard";
+
+// Basic usage without attributes
+const button = element("button");
+button.accessibility.implicitRole(); // 'button'
+
+const nav = element("nav");
+nav.accessibility.implicitRole(); // 'navigation'
+
+// Elements with attributes
+const anchor = element("a", {
+  attributes: {
+    get: (key) => (key === "href" ? "https://example.com" : null),
+  },
+});
+anchor.accessibility.implicitRole(); // 'link'
+
+const anchorWithoutHref = element("a");
+anchorWithoutHref.accessibility.implicitRole(); // 'generic'
+
+const checkbox = element("input", {
+  attributes: {
+    get: (key) => (key === "type" ? "checkbox" : null),
+  },
+});
+checkbox.accessibility.implicitRole(); // 'checkbox'
+```
+
+### Accessibility API
+
+Access accessibility utilities directly:
+
+```typescript
+import { accessibility } from "html-standard";
+
+const buttonA11y = accessibility("button", {
+  attributes: {
+    get: () => null,
+  },
+});
+buttonA11y.implicitRole(); // 'button'
+```
+
+**Key Features:**
+
+- **Implicit ARIA Roles**: Get the default ARIA role for HTML elements according to the [HTML-ARIA specification](https://www.w3.org/TR/html-aria/)
+- **Attribute-Dependent Roles**: Supports roles that vary based on element attributes (e.g., `<a>`, `<input>`, `<img>`, `<select>`)
+- **Case-Insensitive**: Element names are handled case-insensitively
 
 ## Installation
 
-```console
+```bash
 npm install html-standard
 ```
 
-## Usage
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
 
-```js
-import { getElementSpec } from "html-standard";
+# Run tests with UI
+npm run test:ui
 
-const divSpec = getElementSpec("div");
+# Type check
+npm run ts
 
-divSpec.attributes.has("id"); // true
+# Build
+npm run build
 ```
+
+## License
+
+MIT