@devframes/plugin-a11y 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+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,85 @@
+# @devframes/plugin-a11y
+
+> [!WARNING] Experimental
+> This plugin is experimental and may change without a major version bump until
+> it stabilizes.
+
+An accessibility inspector built on [devframe](../../packages/devframe). It runs
+[axe-core](https://github.com/dequelabs/axe-core) against a host application,
+lists the WCAG A/AA violations in a [Solid](https://www.solidjs.com/) panel, and
+**highlights the offending element in the page when you hover a warning**.
+
+The scan + highlight loop works the same whether the plugin runs as a live dev
+server or as a baked static build.
+
+## How it works
+
+Three pieces, two of them browser-side:
+
+| Piece | Runs in | Role |
+|-------|---------|------|
+| **Agent** (`src/inject`) | the host app's page | runs axe-core, broadcasts the report, draws the highlight ring |
+| **Panel** (`src/spa`) | the devtools iframe | Solid SPA: lists violations, fires highlight/clear on hover |
+| **Node** (`src/index.ts`, `src/node`, `src/rpc`) | the devframe backend | `get-config` RPC (impact taxonomy) — live in dev, baked in a static build |
+
+The agent and panel talk over a same-origin
+[`BroadcastChannel`](src/shared/protocol.ts), not the devframe RPC backend. That
+is what keeps the live loop working in **both modes**: neither half needs a
+server to reach the other, only a shared browser origin (host page + panel
+iframe). devframe RPC carries the data model on top — `get-config` is a `static`
+function, so it resolves over WebSocket in dev and from the baked dump in a
+static build.
+
+devframe deliberately provides no access to the host application's DOM, so the
+agent is the author-provided bridge into the page being checked. In a hub, the
+agent is the a11y dock's **client script**: attach `a11yAgentBundlePath` as the
+dock's `clientScript` (resolved to an importable URL — `/@fs/…` under Vite, or a
+statically-served path) and the hub's client runtime (`createDevframeClientHost`
+from `@devframes/hub/client`) imports it into the host page and calls its
+default export with the client-script context. Booted that way, the agent also
+mirrors each scan into the hub's **messages feed** — a summary entry driven
+through the loading → idle lifecycle plus one entry per violated rule, carrying
+the impact-mapped level, WCAG tags as labels, and the first offending element's
+selector and bounding box (rendered by `@devframes/plugin-messages` when the
+hub mounts it). Both minimal hub examples do exactly this. Outside a hub, one
+`<script type="module">` for the same bundle does the job — the demo below
+shows it (no hub context, so the feed mirror simply stays off).
+
+## Run the demo
+
+The demo serves an intentionally-broken host page and the panel from **one
+origin** so they share the channel.
+
+```sh
+pnpm -C plugins/a11y build       # build the panel + the agent bundle
+pnpm -C plugins/a11y demo        # dev: live WebSocket RPC → http://localhost:4477/
+
+pnpm -C plugins/a11y cli:build   # bake the static deploy (dist/static)
+pnpm -C plugins/a11y demo:build  # static: baked RPC dump, no server
+```
+
+Open the URL, then hover any row in the panel — the matching element in the page
+gets a focus ring (and scrolls into view if it's off-screen). Both demo modes
+behave identically; the panel's `websocket` / `static` tag is the only tell.
+
+Standalone, without a host app:
+
+```sh
+pnpm -C plugins/a11y dev         # panel only, at /__devframe-a11y-inspector/
+```
+
+## File map
+
+| Path | Export | Purpose |
+|------|--------|---------|
+| `src/index.ts` | `.` | `createA11yDevframe()` + the default `DevframeDefinition`; `a11yAgentBundlePath` — the agent module a hub attaches as this dock's client script |
+| `src/node/index.ts` | `/node` | `setupA11y(ctx)` — registers the RPC functions |
+| `src/cli.ts` | `/cli` | `createA11yCli()` — backs the `devframe-a11y-inspector` bin |
+| `src/vite.ts` | `/vite` | `a11yVitePlugin()` — mounts the panel into a Vite host |
+| `src/client/index.ts` | `/client` | `connectA11y()` — typed browser RPC client wrapper |
+| `src/rpc/` | — | `get-config` static RPC + the type-safe client registry |
+| `src/shared/protocol.ts` | — | the agent ↔ panel `BroadcastChannel` contract |
+| `src/inject/` | — | the host-page agent (axe scan, highlight overlay, hub messages mirror) → `dist/inject/inject.js` |
+| `src/spa/` | — | the Solid panel SPA → `dist/spa` |
+| `demo/` | — | same-origin host page + server (dev + static modes) |
+| `tests/` | — | dev-server RPC + static-build dump |

package/bin.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import process from 'node:process'
+import { createA11yCli } from './dist/cli.mjs'
+
+async function main() {
+  const cli = createA11yCli()
+  await cli.parse()
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/dist/cli.d.mts

@@ -0,0 +1,12 @@
+import { CliHandle } from "devframe/adapters/cli";
+
+//#region src/cli.d.ts
+/**
+ * Build the standalone CLI for the a11y inspector — backs the package `bin`
+ * (`devframe-a11y-inspector`) and `npx @devframes/plugin-a11y`. Wraps the
+ * default {@link createA11yDevframe} definition with devframe's
+ * `dev` / `build` / `spa` command shell.
+ */
+declare function createA11yCli(): CliHandle;
+//#endregion
+export { createA11yCli };

package/dist/cli.mjs

@@ -0,0 +1,14 @@
+import { n as a11yDevframe } from "./src-D4BUVI3M.mjs";
+import { createCli } from "devframe/adapters/cli";
+//#region src/cli.ts
+/**
+* Build the standalone CLI for the a11y inspector — backs the package `bin`
+* (`devframe-a11y-inspector`) and `npx @devframes/plugin-a11y`. Wraps the
+* default {@link createA11yDevframe} definition with devframe's
+* `dev` / `build` / `spa` command shell.
+*/
+function createA11yCli() {
+	return createCli(a11yDevframe);
+}
+//#endregion
+export { createA11yCli };

package/dist/client/index.d.mts

@@ -0,0 +1,14 @@
+import { i as ViolationNode, n as ScanReport, r as Violation, t as Impact } from "../protocol-BptgJFLx.mjs";
+import { DevframeRpcClient, DevframeRpcClientOptions } from "devframe/client";
+
+//#region src/client/index.d.ts
+/**
+ * Connect to the a11y inspector's devframe backend. A thin, typed wrapper
+ * around devframe's {@link connectDevframe}; the panel derives its base from
+ * `document.baseURI`, so no options are required in the common case. The
+ * live scan/highlight loop itself rides a same-origin BroadcastChannel,
+ * independent of this connection.
+ */
+declare function connectA11y(options?: DevframeRpcClientOptions): Promise<DevframeRpcClient>;
+//#endregion
+export { type DevframeRpcClient, type Impact, type ScanReport, type Violation, type ViolationNode, connectA11y };

package/dist/client/index.mjs

@@ -0,0 +1,14 @@
+import { connectDevframe } from "devframe/client";
+//#region src/client/index.ts
+/**
+* Connect to the a11y inspector's devframe backend. A thin, typed wrapper
+* around devframe's {@link connectDevframe}; the panel derives its base from
+* `document.baseURI`, so no options are required in the common case. The
+* live scan/highlight loop itself rides a same-origin BroadcastChannel,
+* independent of this connection.
+*/
+function connectA11y(options) {
+	return connectDevframe(options);
+}
+//#endregion
+export { connectA11y };

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+import { i as ViolationNode, n as ScanReport, r as Violation, t as Impact } from "./protocol-BptgJFLx.mjs";
+import { DevframeDefinition } from "devframe/types";
+
+//#region src/index.d.ts
+/**
+ * Absolute path to the built in-page **agent** module (`dist/inject/inject.js`)
+ * — the dock **client script** the hub runtime imports into the host page to
+ * scan it (its default export boots the agent; importing it does too).
+ *
+ * A hub attaches this as the a11y dock's `clientScript`, resolved to a URL the
+ * page can import: `/@fs/${a11yAgentBundlePath}` for a Vite host, or a
+ * statically-served path for others (see the minimal hub examples). Resolves
+ * under `<pkg>/dist/inject/inject.js` from both the source and the published
+ * entry. Requires the built bundle (`pnpm -C plugins/a11y build`).
+ */
+declare const a11yAgentBundlePath: string;
+interface A11yDevframeOptions {
+  /** Override the devframe id (and the default CLI command / mount path). */
+  id?: string;
+  /** Override the display name shown in a host dock. */
+  name?: string;
+  /** Override the dock icon. */
+  icon?: string;
+  /**
+   * Override the mount path. Defaults to `/__devframe-a11y-inspector/` so the
+   * panel iframe shares an origin with the host page it scans.
+   */
+  basePath?: string;
+  /** Preferred standalone CLI port. */
+  port?: number;
+}
+/**
+ * Build a {@link DevframeDefinition} for the a11y inspector. The same
+ * definition runs standalone (`/cli`, `/build`) and mounts into a host
+ * (`/vite`, hub). The panel talks to the in-page agent over a same-origin
+ * BroadcastChannel, so the scan/highlight loop works identically in dev
+ * (live WebSocket RPC) and in a baked static build.
+ *
+ * @experimental This plugin is experimental and may change without a major
+ * version bump until it stabilizes.
+ */
+declare function createA11yDevframe(options?: A11yDevframeOptions): DevframeDefinition;
+/** The default a11y inspector devframe definition. */
+declare const a11yDevframe: DevframeDefinition;
+//#endregion
+export { A11yDevframeOptions, type Impact, type ScanReport, type Violation, type ViolationNode, a11yAgentBundlePath, createA11yDevframe, a11yDevframe as default };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as a11yDevframe, r as createA11yDevframe, t as a11yAgentBundlePath } from "./src-D4BUVI3M.mjs";
+export { a11yAgentBundlePath, createA11yDevframe, a11yDevframe as default };