@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 +28 -22
- package/dist/focus.d.ts +1 -1
- package/dist/focus.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,38 +1,44 @@
|
|
|
1
1
|
# @weaveintel/a11y
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
5
|
+
## Why it exists
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
##
|
|
9
|
+
## When to reach for it
|
|
10
10
|
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
25
|
-
const key = captureFocusKey({ focusKey: el.getAttribute('data-focus-key'), id: el.id });
|
|
22
|
+
// ...re-render the DOM...
|
|
26
23
|
|
|
27
|
-
//
|
|
28
|
-
const sel =
|
|
29
|
-
if (sel) (
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
##
|
|
42
|
+
## License
|
|
37
43
|
|
|
38
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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": {
|