@out-of-order/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bart Spaans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @out-of-order/core
+
+> ⚠️ **Under heavy development.** Released, but the API is still changing and may break between versions.
+
+Pure focus & keyboard-accessibility analyzer. Wraps [`tabbable`](https://github.com/focus-trap/tabbable) for the focus sequence and applies a rules layer to decide whether that sequence is _valid_: correct order, every stop reachable, visible, and announced. No test-runner or framework deps, just the DOM.
+
+> Runs in a real browser only. It reads CSS layout (visibility + bounding rects), which jsdom does not provide.
+
+```ts
+import { audit } from "@out-of-order/core";
+
+console.log(audit(document.body, { format: "text" }).violations);
+```
+
+## API
+
+`audit(root = document, options?) => AuditResult`
+
+Each rule carries a default severity (see the table below), and can be changed or turned off completely.
+
+```ts
+// e.g. demote a noisy rule, promote another, and turn one off:
+audit(document.body, {
+  rules: {
+    "visual-order-mismatch": "warning",
+    "redundant-tabindex": "error",
+    "prefer-native-element": "off",
+  },
+});
+```
+
+## Rules
+
+All rules are on by default. "Severity" is the default grade, overridable per `AuditOptions.rules`.
+
+| Rule                         | Severity | What it catches                                                        |
+| ---------------------------- | -------- | ---------------------------------------------------------------------- |
+| `no-positive-tabindex`       | error    | `tabindex > 0`, which hijacks natural order                            |
+| `visual-order-mismatch`      | warning  | tab order that doesn't follow top→bottom, left→right reading order     |
+| `missing-accessible-name`    | error    | focusable interactive elements with no accessible name                 |
+| `aria-hidden-focusable`      | error    | tabbable element inside `aria-hidden="true"`                           |
+| `hidden-while-focusable`     | error    | tabbable but invisible (opacity:0, zero size, off-screen, clipped)     |
+| `clickable-not-focusable`    | error    | mouse-only control (role/onclick) the keyboard can't reach             |
+| `composite-roving-tabindex`  | warning  | composite widget (toolbar, tablist, …) with one tab stop per item      |
+| `focus-escapes-modal`        | error    | background controls still tabbable while a modal is open               |
+| `tabindex-on-noninteractive` | error    | `tabindex="0"` on a role-less, non-interactive element                 |
+| `prefer-native-element`      | warning  | generic tag reimplementing a native control via an interactive role    |
+| `duplicate-autofocus`        | warning  | more than one focusable `autofocus` element (only the first ever wins) |
+| `autofocus-not-focusable`    | warning  | `autofocus` on a non-focusable element (a no-op on load)               |
+| `nested-interactive`         | error    | a focusable control nested inside another focusable element            |
+| `redundant-tabindex`         | warning  | `tabindex="0"` on an already-focusable native control (a no-op)        |
+
+Adding a rule is just a pure function `(sequence, ctx) => Finding[]` (a `Finding` is an `Issue` minus `severity`, which `audit` stamps on from the rule's default severity or the caller's override, then groups by element into `Violation`s); see `src/rules.ts`.
+
+## Live overlay
+
+The visual overlay (a numbered path through the tab sequence, every finding ringed in place, details on hover) lives in its own package, [`@out-of-order/trace`](../trace), built on this analyzer. Keeping it separate is deliberate: `audit` stays dependency-light apart from `tabbable`, so the core export remains easy to run inside `page.evaluate` (e.g. for a Playwright adapter).

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+/** Everything a rule may need beyond the sequence itself. */
+interface RuleContext {
+    /** The analyzed root element (lets rules look beyond the tab sequence). */
+    container: Element;
+    inSequence: Set<Element>;
+}
+/** One problem a rule reports, before grading. */
+interface Finding {
+    /** Human-readable description of what's wrong. */
+    message: string;
+    /** The element the finding points at. A {@link SequenceEntry} when it is a tab
+        stop (carries orderIndex and a selector), or a bare Element when it is not. */
+    target: SequenceEntry | Element;
+    /** Other elements with the same root cause. Ringed alongside `target` but not
+        reported as separate findings, so one missing fix doesn't become N violations. */
+    relatedElements?: Element[];
+}
+/** Takes the tab sequence (plus context) and returns any findings. Pure. */
+type RuleRun = (sequence: SequenceEntry[], ctx: RuleContext) => Finding[];
+interface Rule {
+    /** Stable rule identifier, surfaced on every Violation it produces. */
+    id: string;
+    /** Spec link the rule is grounded in (WCAG, WAI-ARIA, or ARIA APG). */
+    docs: string;
+    /** Severity the rule fires at unless overridden via `AuditOptions.rules`. */
+    defaultSeverity: Severity;
+    run: RuleRun;
+}
+declare const ALL_RULES: {
+    "no-positive-tabindex": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "visual-order-mismatch": {
+        docs: string;
+        defaultSeverity: "warning";
+        run: RuleRun;
+    };
+    "missing-accessible-name": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "aria-hidden-focusable": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "hidden-while-focusable": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "clickable-not-focusable": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "composite-roving-tabindex": {
+        docs: string;
+        defaultSeverity: "warning";
+        run: RuleRun;
+    };
+    "focus-escapes-modal": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "tabindex-on-noninteractive": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "prefer-native-element": {
+        docs: string;
+        defaultSeverity: "warning";
+        run: RuleRun;
+    };
+    "duplicate-autofocus": {
+        docs: string;
+        defaultSeverity: "warning";
+        run: RuleRun;
+    };
+    "autofocus-not-focusable": {
+        docs: string;
+        defaultSeverity: "warning";
+        run: RuleRun;
+    };
+    "nested-interactive": {
+        docs: string;
+        defaultSeverity: "error";
+        run: RuleRun;
+    };
+    "redundant-tabindex": {
+        docs: string;
+        defaultSeverity: "warning";
+        run: RuleRun;
+    };
+};
+declare const DEFAULT_SEVERITY: Record<RuleId, Severity>;
+
+type Severity = "error" | "warning";
+type RuleOverride = Severity | "off";
+/** Serialized shape `audit` returns when asked to format its result: the findings
+    grouped by element, or as a human-readable text block. */
+type AuditFormat = "by-element" | "text";
+/** A single rule failure on one element. */
+interface Issue {
+    /** Stable rule identifier. */
+    rule: RuleId | (string & {});
+    /** How serious this finding is. */
+    severity: Severity;
+    /** Human-readable description of what's wrong. */
+    message: string;
+    /** Spec link for the rule (WCAG, WAI-ARIA, or ARIA APG). */
+    docs?: string;
+    /** Other elements sharing this issue's root cause. */
+    relatedElements?: Element[];
+    /** Approved (silenced) by a `data-ooo-ignore` on the element */
+    ignored?: boolean;
+}
+/** One offending element and every rule it failed. */
+interface Violation {
+    /** The offending element. */
+    element: Element;
+    /** A CSS-ish path to the element, for messages and logs. */
+    selector: string;
+    /** Position in the tab sequence, when the element is a tab stop. */
+    orderIndex?: number;
+    /** The rules this element failed. */
+    issues: Issue[];
+}
+/** A rule failure with its element references flattened to selector strings, so it
+    survives serialization (e.g. `JSON.stringify`) unlike {@link Issue}, which holds
+    live `Element`s. The issue shape shared by the formatted views. */
+interface SerializedIssue {
+    rule: AnyRuleId;
+    severity: Severity;
+    message: string;
+    docs?: string;
+    /** Selectors of the elements sharing this issue's root cause. */
+    related?: string[];
+    /** Approved (silenced) by a `data-ooo-ignore` */
+    ignored?: boolean;
+}
+/** `"by-element"` format: one entry per offending element, its issues nested. The
+    serializable twin of {@link Violation}. */
+interface ByElement {
+    selector: string;
+    orderIndex?: number;
+    /** How many issues this element failed (`issues.length`). */
+    issueCount: number;
+    issues: SerializedIssue[];
+}
+/** The type of {@link AuditResult.violations} for a given `format`: a string for
+    `"text"`, the matching structured array for the others. */
+type Formatted<F extends AuditFormat> = F extends "text" ? string : F extends "by-element" ? ByElement[] : never;
+type RuleId = keyof typeof ALL_RULES;
+type AnyRuleId = RuleId | (string & {});
+interface SequenceEntry {
+    element: Element;
+    selector: string;
+    /** Zero-based position in the tab sequence. */
+    orderIndex: number;
+    /** Resolved tabindex (0 if unset but focusable). */
+    tabIndex: number;
+    /** Bounding rect at analysis time (real layout, browser only). */
+    rect: DOMRect;
+}
+interface AuditResult<V = Violation[]> {
+    /** True when no enabled rule produced an `error` severity finding. */
+    valid: boolean;
+    /** Elements in the exact order tabbing will reach them. */
+    sequence: SequenceEntry[];
+    /** One entry per offending element, each carrying its failed rules. When
+        `AuditOptions.format` is set these same findings are reshaped to that view:
+        a string for `"text"`, else a {@link Formatted} array. */
+    violations: V;
+}
+interface AuditOptions {
+    /** Per-rule overrides. Every rule runs at its default severity unless listed
+        here: set `"off"` to disable it, or `"error"`/`"warning"` to
+        re-grade it. See {@link RuleOverride}. */
+    rules?: Partial<Record<RuleId, RuleOverride>>;
+    /** Reshape the result's `violations` to this view. Omit to keep the structured
+        {@link Violation}`[]`. See {@link Formatted} for the type each one yields. */
+    format?: AuditFormat;
+}
+
+/**
+ * Compute the tab sequence for `root` and grade it against the enabled rules.
+ *
+ * Browser-only by design: `tabbable` uses real CSS layout to decide visibility and
+ * the visual-order rule reads bounding rects, neither meaningful under jsdom.
+ *
+ * Always returns an `AuditResult`; `options.format` only changes the type of its
+ * `violations`, from the structured `Violation[]` to the matching {@link Formatted}
+ * view (a string for `"text"`, an array of the named shape otherwise).
+ */
+declare function audit<F extends AuditFormat>(root: ParentNode | undefined, options: AuditOptions & {
+    format: F;
+}, customRules?: Rule[]): AuditResult<Formatted<F>>;
+declare function audit(root?: ParentNode, options?: AuditOptions, customRules?: Rule[]): AuditResult;
+
+/** Build a short, readable selector path for messages (not guaranteed unique). */
+declare function selectorFor(element: Element): string;
+declare function isInteractive(element: Element): boolean;
+/** Whether `element` opts out of `ruleId` via {@link IGNORE_ATTRIBUTE}. Element-scoped:
+    the attribute must sit on the flagged element itself, it is not inherited by
+    descendants, so approving one control never silences a whole subtree. */
+declare function isRuleIgnored(element: Element, ruleId: string): boolean;
+/** The intentional ".sr-only"/"visually-hidden" utility: tiny + clipped. We must
+    NOT flag it as a bug, since it's the standard way to expose text to screen readers. */
+declare function isScreenReaderOnly(element: Element, rect?: DOMRect): boolean;
+
+/** The overlay's CSS namespace; every class the overlay injects (ring, badge,
+    tooltip) starts with this, so analysis strips any matching class when building
+    selectors and never mistakes the overlay's own markup for page content. The
+    overlay package (@out-of-order/trace) redeclares the same prefix for the classes
+    it applies; the two must stay in sync. A side-effect-free leaf so the
+    page-evaluatable dom.ts can import it without pulling in any CSS. */
+declare const OVERLAY_CLASS_PREFIX = "ooo-";
+
+export { type AuditFormat, type AuditOptions, type AuditResult, type ByElement, DEFAULT_SEVERITY, type Finding, type Formatted, type Issue, OVERLAY_CLASS_PREFIX, type Rule, type RuleId, type RuleOverride, type SequenceEntry, type SerializedIssue, type Severity, type Violation, audit, isInteractive, isRuleIgnored, isScreenReaderOnly, selectorFor };