@weaveintel/a11y 0.0.1 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,38 +1,44 @@
1
1
  # @weaveintel/a11y
2
2
 
3
- Framework-agnostic **accessibility utilities** for weaveIntel UIs — pure, dependency-free helpers you can unit-test exhaustively and reuse across the web app, desktop, and mobile.
3
+ **Tiny, dependency-free DOM helpers for the accessibility problems that break when a UI re-renders — focus restoration, focus trapping, and scroll preservation.**
4
4
 
5
- ## Why this exists
5
+ ## Why it exists
6
6
 
7
- geneWeave's web UI is framework-free: it rebuilds the DOM on every state change (`root.innerHTML = ''`). That's simple and fast, but it **destroys keyboard focus** — after any action, a keyboard or screen-reader user is dumped back at the top of the page (WCAG 2.4.3 *Focus Order*). The fix is to snapshot the focused control *before* the re-render and restore it *after*. This package is the pure core of that.
7
+ When a live agent UI redraws itself, small courtesies quietly break: the button you were tabbed to vanishes and your keyboard focus falls back to the top of the page; the chat you'd scrolled to the bottom of jumps somewhere else. It's like a librarian reshelving the whole room while you're mid-sentence — you lose your finger on the page. These helpers are pure functions that let you *remember where the reader was* before the re-render and *put them back* after: which element had focus, whether the log was pinned to the bottom, where to scroll to. They touch no framework and pull in no dependencies.
8
8
 
9
- ## What's in the box
9
+ ## When to reach for it
10
10
 
11
- | Primitive | What it does |
12
- |---|---|
13
- | `captureFocusKey(descriptor)` | Turn a description of the focused element (`{ focusKey?, id? }`) into a **stable string key**, or `null` when nothing dependable is available. Prefers an explicit app-assigned `data-focus-key` over a DOM `id`. Returning `null` is deliberate — the app then does **not** force focus, so it can never focus the *wrong* thing. |
14
- | `focusSelector(key)` | Turn a key back into a **CSS selector** that re-finds the element after the re-render (`[data-focus-key="…"]` / `[id="…"]`). |
15
- | `cssEscapeValue(s)` | Escape a value for safe use inside a double-quoted attribute selector (strips control chars, escapes `\` and `"`) — so a key derived from user content can never **break out of the selector** (no injection). |
16
- | `nextTrapIndex(count, current, shift)` / `FOCUSABLE_SELECTOR` | **Focus-trap math** for modal dialogs (WAI-ARIA "Dialog"): given the number of focusable elements and the current index, where does Tab / Shift+Tab go (wrapping at the ends, clamping strays)? `FOCUSABLE_SELECTOR` is the standard query for tabbable elements. The app queries the dialog + calls `.focus()`; this owns the edge cases (empty trap → -1, single element, wrap-around, focus outside the trap). Used by geneWeave's accessible confirm/notice dialog. |
17
- | `captureScroll()` / `resolveScrollTop()` / `isAtBottom()` | **Scroll preservation** across a full re-render (a `root.innerHTML=''` UI resets every scroll container → the notes list / admin tables / dashboard jump to the top, a layout-shift/CLS problem). Snapshot a container's `{top, atBottom}` before the wipe; `resolveScrollTop` computes where to put it back — pinned to the (new) bottom if the reader was following the bottom, else the exact offset **clamped into the new content height** (so a shorter list leaves no blank gap). Pure arithmetic (the app does the DOM reads/writes); handles non-finite sizes + stale offsets. |
11
+ Reach for it when you're hand-rolling a UI (vanilla DOM, or a framework where you manage focus/scroll yourself) and need correct, testable accessibility behaviour across re-renders. Because these are low-level primitives, you wire them into your own event handlers. If a framework already gives you focus management you trust, you may not need this. For UI *event* builders (approvals, widgets), see `@weaveintel/ui-primitives`.
18
12
 
19
- The **DOM bits stay in the app** (reading `document.activeElement`, calling `.focus()`, restoring the text caret) — this package is pure, so it has zero browser dependency and is trivial to test.
13
+ ## How to use it
20
14
 
21
15
  ```ts
22
- import { captureFocusKey, focusSelector } from '@weaveintel/a11y';
16
+ import { captureFocusKey, focusSelector, captureScroll, isAtBottom, resolveScrollTop } from '@weaveintel/a11y';
17
+
18
+ // Before a re-render: remember focus + the scroll position.
19
+ const focusKey = captureFocusKey({ focusKey: el.getAttribute('data-focus-key'), id: el.id });
20
+ const scroll = captureScroll(logEl);
23
21
 
24
- // before re-render
25
- const key = captureFocusKey({ focusKey: el.getAttribute('data-focus-key'), id: el.id });
22
+ // ...re-render the DOM...
26
23
 
27
- // after re-render
28
- const sel = key && focusSelector(key); // e.g. '[data-focus-key="composer"]'
29
- if (sel) (root.querySelector(sel) as HTMLElement | null)?.focus();
24
+ // After: restore focus, and put scroll back (pinned to bottom if the reader was following it).
25
+ const sel = focusKey && focusSelector(focusKey);
26
+ if (sel) (logEl.querySelector(sel) as HTMLElement | null)?.focus();
27
+ logEl.scrollTop = resolveScrollTop(scroll, logEl.scrollHeight, logEl.clientHeight);
30
28
  ```
31
29
 
32
- ## Note on the raw-served web UI
30
+ ## What's in the box
31
+
32
+ | Export | What it does |
33
+ | --- | --- |
34
+ | `captureFocusKey`, `focusSelector`, `cssEscapeValue` | Remember the focused element and rebuild a safe selector to restore it |
35
+ | `FocusDescriptor` | The type describing a captured focus target |
36
+ | `FOCUSABLE_SELECTOR`, `nextTrapIndex` | Focus-trap wrap-around math for modal dialogs |
37
+ | `captureScroll`, `resolveScrollTop`, `isAtBottom`, `DEFAULT_AT_BOTTOM_THRESHOLD` | Preserve scroll position and detect "pinned to bottom" |
38
+ | `ScrollSnapshot` | The type describing a captured scroll position |
33
39
 
34
- geneWeave's browser modules are served as raw ESM (only the notes editor is bundled), so they can't `import` a workspace package directly. The web app therefore **mirrors** this pure logic in `apps/geneweave-ui/src/ui/focus.ts`; the tests here are the spec — keep the two in sync. A **bundled** app (desktop/mobile) can depend on this package directly.
40
+ The DOM reads and writes (reading `document.activeElement`, calling `.focus()`, restoring the caret) stay in your app — this package is pure arithmetic and string logic, so it has zero browser dependency and is trivial to test.
35
41
 
36
- ## Status
42
+ ## License
37
43
 
38
- `focus.ts` shipped with geneWeave Round 4 (focus & keyboard sweep). Pure + zero-dependency; positive / negative / stress / security unit tests in `focus.test.ts`.
44
+ MIT.
package/dist/focus.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @weaveintel/a11y — Focus restoration across a full re-render.
3
3
  *
4
- * Framework-free UIs that rebuild the DOM on every state change (e.g. geneWeave's `root.innerHTML = ''`
4
+ * Framework-free UIs that rebuild the DOM on every state change (e.g. a `root.innerHTML = ''`
5
5
  * render) DESTROY keyboard focus: after any action a keyboard or screen-reader user is dumped back at the
6
6
  * top of the page (WCAG 2.4.3 Focus Order). The fix is: before the re-render, capture a STABLE key for the
7
7
  * focused control; after the re-render, find the matching element and refocus it.
package/dist/focus.js CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @weaveintel/a11y — Focus restoration across a full re-render.
3
3
  *
4
- * Framework-free UIs that rebuild the DOM on every state change (e.g. geneWeave's `root.innerHTML = ''`
4
+ * Framework-free UIs that rebuild the DOM on every state change (e.g. a `root.innerHTML = ''`
5
5
  * render) DESTROY keyboard focus: after any action a keyboard or screen-reader user is dumped back at the
6
6
  * top of the page (WCAG 2.4.3 Focus Order). The fix is: before the re-render, capture a STABLE key for the
7
7
  * focused control; after the re-render, find the matching element and refocus it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@weaveintel/a11y",
3
- "version": "0.0.1",
3
+ "version": "0.1.1",
4
4
  "type": "module",
5
5
  "description": "Framework-agnostic accessibility utilities for weaveIntel UIs — pure, dependency-free helpers (focus restoration across full re-renders, etc.).",
6
6
  "exports": {