@shadow-garden/bapbong-a11y 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Le Phuoc Minh
+
+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,33 @@
+# @shadow-garden/bapbong-a11y
+
+Accessibility for the canvas-rendered editor. A `<canvas>` is **opaque to screen
+readers** — there is no text in the accessibility tree. `A11yMirror` keeps a
+parallel, visually-hidden DOM subtree that mirrors the document so assistive
+tech can read and navigate it.
+
+The mirror is built from the document's **own schema `toDOM`** (via
+ProseMirror's `DOMSerializer`), so it is faithfully semantic: paragraphs,
+lists, tables, and real `<a href>` links — the same structure the model would
+export.
+
+```ts
+import { A11yMirror } from '@shadow-garden/bapbong-a11y';
+
+const mirror = new A11yMirror(hostEl, { label: 'My document' });
+mirror.update(doc);   // call on each document change — debounced internally
+// …
+mirror.destroy();
+```
+
+Wired automatically by `RenderCore` (so both `@shadow-garden/bapbong-editor` and
+`@shadow-garden/bapbong-view` are accessible out of the box); you rarely
+construct it by hand.
+
+## Notes
+
+- **Visually hidden, AT-visible.** Uses the standard `sr-only` clip recipe — the
+  mirror never shows on screen but stays in the accessibility tree.
+- **Debounced.** `update()` coalesces rapid edits (200 ms by default) so typing
+  stays snappy; the mirror is for reading/navigation, not live keystroke echo.
+- **Light.** Inline-image `src` (base64 data-URLs) is stripped — assistive tech
+  reads the `alt`, and duplicating data-URLs would bloat the DOM.

package/dist/index.cjs

@@ -0,0 +1,90 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/a11y/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  A11yMirror: () => A11yMirror
+});
+module.exports = __toCommonJS(index_exports);
+
+// packages/a11y/src/lib/a11y-mirror.ts
+var import_prosemirror_model = require("prosemirror-model");
+var SR_ONLY = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:normal;";
+var A11yMirror = class {
+  el;
+  debounceMs;
+  pending = null;
+  timer = null;
+  constructor(host, opts = {}) {
+    this.debounceMs = opts.debounceMs ?? 200;
+    const el = host.ownerDocument.createElement("div");
+    el.setAttribute("role", "document");
+    el.setAttribute("aria-label", opts.label ?? "Document content");
+    el.style.cssText = SR_ONLY;
+    host.appendChild(el);
+    this.el = el;
+  }
+  /** Re-render the mirror from `doc` (debounced). Safe to call on every change. */
+  update(doc) {
+    this.pending = doc;
+    if (this.debounceMs <= 0) {
+      this.flush();
+      return;
+    }
+    if (this.timer != null) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.flush();
+    }, this.debounceMs);
+  }
+  /** Render any pending document immediately (cancelling a scheduled flush). */
+  flush() {
+    if (this.timer != null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    const doc = this.pending;
+    if (!doc) return;
+    this.pending = null;
+    const serializer = import_prosemirror_model.DOMSerializer.fromSchema(doc.type.schema);
+    const fragment = serializer.serializeFragment(doc.content, {
+      document: this.el.ownerDocument
+    });
+    this.el.replaceChildren(fragment);
+    for (const img of Array.from(this.el.querySelectorAll("img"))) {
+      img.removeAttribute("src");
+      if (!img.getAttribute("alt")) img.setAttribute("alt", "image");
+    }
+  }
+  /** The mirror container (e.g. to wire `aria-describedby`). */
+  get element() {
+    return this.el;
+  }
+  destroy() {
+    if (this.timer != null) clearTimeout(this.timer);
+    this.timer = null;
+    this.pending = null;
+    this.el.remove();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A11yMirror
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/a11y-mirror.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,63 @@
+// packages/a11y/src/lib/a11y-mirror.ts
+import { DOMSerializer } from "prosemirror-model";
+var SR_ONLY = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:normal;";
+var A11yMirror = class {
+  el;
+  debounceMs;
+  pending = null;
+  timer = null;
+  constructor(host, opts = {}) {
+    this.debounceMs = opts.debounceMs ?? 200;
+    const el = host.ownerDocument.createElement("div");
+    el.setAttribute("role", "document");
+    el.setAttribute("aria-label", opts.label ?? "Document content");
+    el.style.cssText = SR_ONLY;
+    host.appendChild(el);
+    this.el = el;
+  }
+  /** Re-render the mirror from `doc` (debounced). Safe to call on every change. */
+  update(doc) {
+    this.pending = doc;
+    if (this.debounceMs <= 0) {
+      this.flush();
+      return;
+    }
+    if (this.timer != null) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.flush();
+    }, this.debounceMs);
+  }
+  /** Render any pending document immediately (cancelling a scheduled flush). */
+  flush() {
+    if (this.timer != null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    const doc = this.pending;
+    if (!doc) return;
+    this.pending = null;
+    const serializer = DOMSerializer.fromSchema(doc.type.schema);
+    const fragment = serializer.serializeFragment(doc.content, {
+      document: this.el.ownerDocument
+    });
+    this.el.replaceChildren(fragment);
+    for (const img of Array.from(this.el.querySelectorAll("img"))) {
+      img.removeAttribute("src");
+      if (!img.getAttribute("alt")) img.setAttribute("alt", "image");
+    }
+  }
+  /** The mirror container (e.g. to wire `aria-describedby`). */
+  get element() {
+    return this.el;
+  }
+  destroy() {
+    if (this.timer != null) clearTimeout(this.timer);
+    this.timer = null;
+    this.pending = null;
+    this.el.remove();
+  }
+};
+export {
+  A11yMirror
+};

package/dist/lib/a11y-mirror.d.ts

@@ -0,0 +1,38 @@
+import { type Node as ProseMirrorNode } from 'prosemirror-model';
+export interface A11yMirrorOptions {
+    /** `aria-label` for the mirrored document region. */
+    label?: string;
+    /** Debounce (ms) before re-serializing after `update()` — coalesces rapid
+     *  edits so typing stays snappy (the mirror is for reading/navigation, not
+     *  live keystroke echo). Default 200. Set 0 to update synchronously. */
+    debounceMs?: number;
+}
+/**
+ * An **ARIA shadow-DOM mirror** of a bapbong document. The canvas the editor /
+ * viewer paints into is opaque to screen readers; this keeps a parallel,
+ * visually-hidden DOM subtree — built from the schema's own `toDOM` via
+ * {@link DOMSerializer} — so assistive tech can read and navigate the content
+ * (headings/paragraphs/lists/tables and real `<a href>` links).
+ *
+ *   const mirror = new A11yMirror(hostEl);
+ *   mirror.update(doc);   // re-serialise on each doc change (debounced)
+ *   mirror.destroy();
+ *
+ * It only needs the document `Node` (the schema rides on `doc.type.schema`), so
+ * it works for both the editable and read-only tiers.
+ */
+export declare class A11yMirror {
+    private readonly el;
+    private readonly debounceMs;
+    private pending;
+    private timer;
+    constructor(host: HTMLElement, opts?: A11yMirrorOptions);
+    /** Re-render the mirror from `doc` (debounced). Safe to call on every change. */
+    update(doc: ProseMirrorNode): void;
+    /** Render any pending document immediately (cancelling a scheduled flush). */
+    flush(): void;
+    /** The mirror container (e.g. to wire `aria-describedby`). */
+    get element(): HTMLElement;
+    destroy(): void;
+}
+//# sourceMappingURL=a11y-mirror.d.ts.map

package/dist/lib/a11y-mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y-mirror.d.ts","sourceRoot":"","sources":["../../src/lib/a11y-mirror.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,IAAI,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEhF,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;4EAEwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,KAAK,CAA8C;gBAE/C,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,iBAAsB;IAU3D,iFAAiF;IACjF,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAalC,8EAA8E;IAC9E,KAAK,IAAI,IAAI;IAqBb,8DAA8D;IAC9D,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,OAAO,IAAI,IAAI;CAMhB"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@shadow-garden/bapbong-a11y",
+  "version": "0.1.0",
+  "description": "bapbong — accessibility: a visually-hidden ARIA DOM mirror of the canvas document so screen readers can read it (the canvas itself is opaque to assistive tech).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shadowgarden-app/bapbong.git",
+    "directory": "packages/a11y"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@shadow-garden/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "tags": [
+      "scope:a11y"
+    ],
+    "targets": {
+      "build": {
+        "executor": "@nx/esbuild:esbuild",
+        "outputs": [
+          "{options.outputPath}"
+        ],
+        "options": {
+          "outputPath": "packages/a11y/dist",
+          "main": "packages/a11y/src/index.ts",
+          "tsConfig": "packages/a11y/tsconfig.lib.json",
+          "format": [
+            "esm",
+            "cjs"
+          ],
+          "declarationRootDir": "packages/a11y/src",
+          "external": []
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "prosemirror-model": "^1.25.7"
+  }
+}