@weaveintel/a11y 0.0.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 ADDED
@@ -0,0 +1,38 @@
1
+ # @weaveintel/a11y
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.
4
+
5
+ ## Why this exists
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.
8
+
9
+ ## What's in the box
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. |
18
+
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.
20
+
21
+ ```ts
22
+ import { captureFocusKey, focusSelector } from '@weaveintel/a11y';
23
+
24
+ // before re-render
25
+ const key = captureFocusKey({ focusKey: el.getAttribute('data-focus-key'), id: el.id });
26
+
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();
30
+ ```
31
+
32
+ ## Note on the raw-served web UI
33
+
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.
35
+
36
+ ## Status
37
+
38
+ `focus.ts` shipped with geneWeave Round 4 (focus & keyboard sweep). Pure + zero-dependency; positive / negative / stress / security unit tests in `focus.test.ts`.
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @weaveintel/a11y — Focus-trap math for modal dialogs.
3
+ *
4
+ * A modal (an accessible confirm/notice dialog, a settings panel) must TRAP keyboard focus: Tab from the
5
+ * last control wraps to the first, Shift+Tab from the first wraps to the last, and focus can never escape to
6
+ * the page behind the backdrop (WAI-ARIA APG "Dialog (Modal)"). The DOM part — finding the focusable
7
+ * elements and calling `.focus()` — belongs to the app; the PURE part is the index arithmetic, which is what
8
+ * actually has edge cases (empty trap, single element, wrap-around, focus currently outside the trap). That's
9
+ * here, so it's exhaustively testable.
10
+ *
11
+ * Pure + zero-dependency.
12
+ */
13
+ /**
14
+ * The standard selector for TABBABLE elements inside a container: links with an href, enabled form controls
15
+ * and buttons, and anything with an explicit non-negative tabindex. Excludes disabled controls and
16
+ * `tabindex="-1"` (programmatically-focusable-but-not-tabbable). The app queries a dialog with this.
17
+ */
18
+ export declare const FOCUSABLE_SELECTOR = "a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";
19
+ /**
20
+ * The index to focus when Tab / Shift+Tab is pressed inside a trap of `count` focusable elements, wrapping at
21
+ * the ends. `current` is the index the focus is on now (pass -1 when focus is not on a trap element — e.g.
22
+ * focus is on the dialog container itself). Returns -1 only when there is nothing focusable.
23
+ *
24
+ * Tab from the last (or off-trap) → 0 (first)
25
+ * Shift+Tab from the first (or off-trap) → count-1 (last)
26
+ */
27
+ export declare function nextTrapIndex(count: number, current: number, shift: boolean): number;
28
+ //# sourceMappingURL=focus-trap.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"focus-trap.d.ts","sourceRoot":"","sources":["../src/focus-trap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,gJAC8G,CAAC;AAE9I;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAQpF"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * @weaveintel/a11y — Focus-trap math for modal dialogs.
3
+ *
4
+ * A modal (an accessible confirm/notice dialog, a settings panel) must TRAP keyboard focus: Tab from the
5
+ * last control wraps to the first, Shift+Tab from the first wraps to the last, and focus can never escape to
6
+ * the page behind the backdrop (WAI-ARIA APG "Dialog (Modal)"). The DOM part — finding the focusable
7
+ * elements and calling `.focus()` — belongs to the app; the PURE part is the index arithmetic, which is what
8
+ * actually has edge cases (empty trap, single element, wrap-around, focus currently outside the trap). That's
9
+ * here, so it's exhaustively testable.
10
+ *
11
+ * Pure + zero-dependency.
12
+ */
13
+ /**
14
+ * The standard selector for TABBABLE elements inside a container: links with an href, enabled form controls
15
+ * and buttons, and anything with an explicit non-negative tabindex. Excludes disabled controls and
16
+ * `tabindex="-1"` (programmatically-focusable-but-not-tabbable). The app queries a dialog with this.
17
+ */
18
+ export const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
19
+ /**
20
+ * The index to focus when Tab / Shift+Tab is pressed inside a trap of `count` focusable elements, wrapping at
21
+ * the ends. `current` is the index the focus is on now (pass -1 when focus is not on a trap element — e.g.
22
+ * focus is on the dialog container itself). Returns -1 only when there is nothing focusable.
23
+ *
24
+ * Tab from the last (or off-trap) → 0 (first)
25
+ * Shift+Tab from the first (or off-trap) → count-1 (last)
26
+ */
27
+ export function nextTrapIndex(count, current, shift) {
28
+ const n = Number.isFinite(count) ? Math.floor(count) : 0;
29
+ if (n <= 0)
30
+ return -1;
31
+ // Clamp a stray current into [-1, n-1] so an out-of-range value can never yield an out-of-range result.
32
+ const raw = Number.isFinite(current) ? Math.floor(current) : -1;
33
+ const cur = raw < -1 ? -1 : raw > n - 1 ? n - 1 : raw;
34
+ if (shift)
35
+ return cur <= 0 ? n - 1 : cur - 1;
36
+ return cur >= n - 1 ? 0 : cur + 1;
37
+ }
38
+ //# sourceMappingURL=focus-trap.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"focus-trap.js","sourceRoot":"","sources":["../src/focus-trap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,2IAA2I,CAAC;AAE9I;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,OAAe,EAAE,KAAc;IAC1E,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC;IACtB,wGAAwG;IACxG,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACtD,IAAI,KAAK;QAAE,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;IAC7C,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;AACpC,CAAC"}
@@ -0,0 +1,44 @@
1
+ /**
2
+ * @weaveintel/a11y — Focus restoration across a full re-render.
3
+ *
4
+ * Framework-free UIs that rebuild the DOM on every state change (e.g. geneWeave's `root.innerHTML = ''`
5
+ * render) DESTROY keyboard focus: after any action a keyboard or screen-reader user is dumped back at the
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
+ * focused control; after the re-render, find the matching element and refocus it.
8
+ *
9
+ * This module is the pure, testable core of that: turn a description of the focused element into a stable
10
+ * string key, and turn a key back into a CSS selector to re-find it. The app supplies the DOM bits (reading
11
+ * `document.activeElement`, calling `.focus()`, restoring text selection).
12
+ *
13
+ * Design choices (deliberately conservative, so we NEVER focus the wrong thing):
14
+ * - Restore only for elements with an explicit `data-focus-key` (the app tags the controls that matter:
15
+ * the composer, nav items, list rows, menu triggers) OR a stable `id`. Anything else → no key → the app
16
+ * doesn't force focus (safe: focus falls back to the document, exactly as before, for un-keyed elements).
17
+ * - Selector values are escaped, so a key derived from user content can never break out of the attribute
18
+ * selector (no selector injection).
19
+ *
20
+ * Pure + zero-dependency.
21
+ */
22
+ export interface FocusDescriptor {
23
+ /** An explicit, app-assigned stable id for this control (from `data-focus-key`). Preferred. */
24
+ focusKey?: string | null;
25
+ /** The element's DOM id, used when there's no focus-key. */
26
+ id?: string | null;
27
+ }
28
+ /**
29
+ * Escape a string for safe use inside a double-quoted CSS attribute-selector value (`[attr="…"]`). Strips
30
+ * control characters, then escapes backslashes and double-quotes. Pure — no DOM, no `CSS.escape`.
31
+ */
32
+ export declare function cssEscapeValue(s: string): string;
33
+ /**
34
+ * Build a stable key for the focused control, or null when nothing stable is available (→ the caller should
35
+ * NOT try to restore focus). Prefers an explicit `data-focus-key` over a DOM `id`.
36
+ */
37
+ export declare function captureFocusKey(d: FocusDescriptor): string | null;
38
+ /**
39
+ * Turn a key from {@link captureFocusKey} back into a CSS selector that re-finds the element after a
40
+ * re-render. Returns null for an unrecognised / empty key. Values are escaped, so the returned selector is
41
+ * always a single, well-formed attribute match (injection-safe).
42
+ */
43
+ export declare function focusSelector(key: string): string | null;
44
+ //# sourceMappingURL=focus.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../src/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,MAAM,WAAW,eAAe;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAMjE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUxD"}
package/dist/focus.js ADDED
@@ -0,0 +1,65 @@
1
+ /**
2
+ * @weaveintel/a11y — Focus restoration across a full re-render.
3
+ *
4
+ * Framework-free UIs that rebuild the DOM on every state change (e.g. geneWeave's `root.innerHTML = ''`
5
+ * render) DESTROY keyboard focus: after any action a keyboard or screen-reader user is dumped back at the
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
+ * focused control; after the re-render, find the matching element and refocus it.
8
+ *
9
+ * This module is the pure, testable core of that: turn a description of the focused element into a stable
10
+ * string key, and turn a key back into a CSS selector to re-find it. The app supplies the DOM bits (reading
11
+ * `document.activeElement`, calling `.focus()`, restoring text selection).
12
+ *
13
+ * Design choices (deliberately conservative, so we NEVER focus the wrong thing):
14
+ * - Restore only for elements with an explicit `data-focus-key` (the app tags the controls that matter:
15
+ * the composer, nav items, list rows, menu triggers) OR a stable `id`. Anything else → no key → the app
16
+ * doesn't force focus (safe: focus falls back to the document, exactly as before, for un-keyed elements).
17
+ * - Selector values are escaped, so a key derived from user content can never break out of the attribute
18
+ * selector (no selector injection).
19
+ *
20
+ * Pure + zero-dependency.
21
+ */
22
+ // C0/C1 control chars + DEL, written via \u escapes so this source stays plain ASCII.
23
+ const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
24
+ /**
25
+ * Escape a string for safe use inside a double-quoted CSS attribute-selector value (`[attr="…"]`). Strips
26
+ * control characters, then escapes backslashes and double-quotes. Pure — no DOM, no `CSS.escape`.
27
+ */
28
+ export function cssEscapeValue(s) {
29
+ return String(s).replace(CONTROL_CHARS, '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
30
+ }
31
+ /**
32
+ * Build a stable key for the focused control, or null when nothing stable is available (→ the caller should
33
+ * NOT try to restore focus). Prefers an explicit `data-focus-key` over a DOM `id`.
34
+ */
35
+ export function captureFocusKey(d) {
36
+ const key = typeof d.focusKey === 'string' ? d.focusKey.trim() : '';
37
+ if (key)
38
+ return `k:${key}`;
39
+ const id = typeof d.id === 'string' ? d.id.trim() : '';
40
+ if (id)
41
+ return `i:${id}`;
42
+ return null;
43
+ }
44
+ /**
45
+ * Turn a key from {@link captureFocusKey} back into a CSS selector that re-finds the element after a
46
+ * re-render. Returns null for an unrecognised / empty key. Values are escaped, so the returned selector is
47
+ * always a single, well-formed attribute match (injection-safe).
48
+ */
49
+ export function focusSelector(key) {
50
+ if (typeof key !== 'string')
51
+ return null;
52
+ const sep = key.indexOf(':');
53
+ if (sep < 0)
54
+ return null;
55
+ const kind = key.slice(0, sep);
56
+ const val = key.slice(sep + 1);
57
+ if (!val)
58
+ return null;
59
+ if (kind === 'k')
60
+ return `[data-focus-key="${cssEscapeValue(val)}"]`;
61
+ if (kind === 'i')
62
+ return `[id="${cssEscapeValue(val)}"]`;
63
+ return null;
64
+ }
65
+ //# sourceMappingURL=focus.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"focus.js","sourceRoot":"","sources":["../src/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,sFAAsF;AACtF,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAS/C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,IAAI,GAAG;QAAE,OAAO,KAAK,GAAG,EAAE,CAAC;IAC3B,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,IAAI,EAAE;QAAE,OAAO,KAAK,EAAE,EAAE,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,oBAAoB,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;IACrE,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,QAAQ,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC"}
@@ -0,0 +1,4 @@
1
+ export { type FocusDescriptor, cssEscapeValue, captureFocusKey, focusSelector, } from './focus.js';
2
+ export { FOCUSABLE_SELECTOR, nextTrapIndex, } from './focus-trap.js';
3
+ export { type ScrollSnapshot, DEFAULT_AT_BOTTOM_THRESHOLD, isAtBottom, captureScroll, resolveScrollTop, } from './scroll.js';
4
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,cAAc,EACnB,2BAA2B,EAC3B,UAAU,EACV,aAAa,EACb,gBAAgB,GACjB,MAAM,aAAa,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,4 @@
1
+ export { cssEscapeValue, captureFocusKey, focusSelector, } from './focus.js';
2
+ export { FOCUSABLE_SELECTOR, nextTrapIndex, } from './focus-trap.js';
3
+ export { DEFAULT_AT_BOTTOM_THRESHOLD, isAtBottom, captureScroll, resolveScrollTop, } from './scroll.js';
4
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,2BAA2B,EAC3B,UAAU,EACV,aAAa,EACb,gBAAgB,GACjB,MAAM,aAAa,CAAC"}
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @weaveintel/a11y — Scroll-position preservation across a full re-render.
3
+ *
4
+ * A framework-free UI that rebuilds the DOM on every state change (`root.innerHTML = ''`) resets the scroll
5
+ * position of EVERY scroll container. For a reader that's jarring — the notes list, an admin table, the
6
+ * dashboard all jump to the top after any action (a layout-shift / CLS problem). The fix is the same one the
7
+ * chat transcript already uses: SNAPSHOT each container's scroll before the rebuild, then RESTORE it after —
8
+ * pinning to the bottom only if the reader was already there (so a growing/streaming list keeps following),
9
+ * otherwise putting them back at their exact place.
10
+ *
11
+ * This module is the pure arithmetic of that (the DOM reads/writes live in the app), so the edge cases —
12
+ * "were they at the bottom?", "clamp a stale offset to the new content height", non-finite inputs — are
13
+ * exhaustively testable. Pure + zero-dependency.
14
+ */
15
+ export interface ScrollSnapshot {
16
+ /** The scrollTop at capture time. */
17
+ top: number;
18
+ /** Was the container scrolled to (within `threshold` of) the bottom? Then restore should follow the bottom. */
19
+ atBottom: boolean;
20
+ }
21
+ /** How close to the bottom (px) still counts as "at the bottom" (so a near-bottom reader keeps following). */
22
+ export declare const DEFAULT_AT_BOTTOM_THRESHOLD = 24;
23
+ /** Is the container scrolled to (near) the bottom? Non-finite inputs → false (safe: don't force-follow). */
24
+ export declare function isAtBottom(scrollTop: number, scrollHeight: number, clientHeight: number, threshold?: number): boolean;
25
+ /** Snapshot a container's scroll state before a re-render. */
26
+ export declare function captureScroll(m: {
27
+ scrollTop: number;
28
+ scrollHeight: number;
29
+ clientHeight: number;
30
+ }, threshold?: number): ScrollSnapshot;
31
+ /**
32
+ * The scrollTop to set AFTER the re-render. Pins to the (new) bottom when the reader was at the bottom;
33
+ * otherwise clamps the saved offset into the new content's range (so a shorter list can't leave a blank gap).
34
+ * A missing snapshot → 0 (top).
35
+ */
36
+ export declare function resolveScrollTop(saved: ScrollSnapshot | null | undefined, scrollHeight: number, clientHeight: number): number;
37
+ //# sourceMappingURL=scroll.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../src/scroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,+GAA+G;IAC/G,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,8GAA8G;AAC9G,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAI9C,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,SAA8B,GAAG,OAAO,CAI1I;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,SAA8B,GAAG,cAAc,CAE3J;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAK7H"}
package/dist/scroll.js ADDED
@@ -0,0 +1,42 @@
1
+ /**
2
+ * @weaveintel/a11y — Scroll-position preservation across a full re-render.
3
+ *
4
+ * A framework-free UI that rebuilds the DOM on every state change (`root.innerHTML = ''`) resets the scroll
5
+ * position of EVERY scroll container. For a reader that's jarring — the notes list, an admin table, the
6
+ * dashboard all jump to the top after any action (a layout-shift / CLS problem). The fix is the same one the
7
+ * chat transcript already uses: SNAPSHOT each container's scroll before the rebuild, then RESTORE it after —
8
+ * pinning to the bottom only if the reader was already there (so a growing/streaming list keeps following),
9
+ * otherwise putting them back at their exact place.
10
+ *
11
+ * This module is the pure arithmetic of that (the DOM reads/writes live in the app), so the edge cases —
12
+ * "were they at the bottom?", "clamp a stale offset to the new content height", non-finite inputs — are
13
+ * exhaustively testable. Pure + zero-dependency.
14
+ */
15
+ /** How close to the bottom (px) still counts as "at the bottom" (so a near-bottom reader keeps following). */
16
+ export const DEFAULT_AT_BOTTOM_THRESHOLD = 24;
17
+ function finite(n) { return typeof n === 'number' && Number.isFinite(n) ? n : 0; }
18
+ /** Is the container scrolled to (near) the bottom? Non-finite inputs → false (safe: don't force-follow). */
19
+ export function isAtBottom(scrollTop, scrollHeight, clientHeight, threshold = DEFAULT_AT_BOTTOM_THRESHOLD) {
20
+ if (![scrollTop, scrollHeight, clientHeight].every((n) => typeof n === 'number' && Number.isFinite(n)))
21
+ return false;
22
+ const gap = scrollHeight - (scrollTop + clientHeight);
23
+ return gap <= Math.max(0, finite(threshold));
24
+ }
25
+ /** Snapshot a container's scroll state before a re-render. */
26
+ export function captureScroll(m, threshold = DEFAULT_AT_BOTTOM_THRESHOLD) {
27
+ return { top: Math.max(0, finite(m.scrollTop)), atBottom: isAtBottom(m.scrollTop, m.scrollHeight, m.clientHeight, threshold) };
28
+ }
29
+ /**
30
+ * The scrollTop to set AFTER the re-render. Pins to the (new) bottom when the reader was at the bottom;
31
+ * otherwise clamps the saved offset into the new content's range (so a shorter list can't leave a blank gap).
32
+ * A missing snapshot → 0 (top).
33
+ */
34
+ export function resolveScrollTop(saved, scrollHeight, clientHeight) {
35
+ const max = Math.max(0, finite(scrollHeight) - finite(clientHeight));
36
+ if (!saved)
37
+ return 0;
38
+ if (saved.atBottom)
39
+ return max;
40
+ return Math.max(0, Math.min(finite(saved.top), max));
41
+ }
42
+ //# sourceMappingURL=scroll.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"scroll.js","sourceRoot":"","sources":["../src/scroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,8GAA8G;AAC9G,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAE9C,SAAS,MAAM,CAAC,CAAU,IAAY,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnG,4GAA4G;AAC5G,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,YAAoB,EAAE,YAAoB,EAAE,SAAS,GAAG,2BAA2B;IAC/H,IAAI,CAAC,CAAC,SAAS,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrH,MAAM,GAAG,GAAG,YAAY,GAAG,CAAC,SAAS,GAAG,YAAY,CAAC,CAAC;IACtD,OAAO,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,CAAoE,EAAE,SAAS,GAAG,2BAA2B;IACzI,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,SAAS,CAAC,EAAE,CAAC;AACjI,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwC,EAAE,YAAoB,EAAE,YAAoB;IACnH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,GAAG,CAAC;IAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AACvD,CAAC"}
package/package.json ADDED
@@ -0,0 +1,33 @@
1
+ {
2
+ "name": "@weaveintel/a11y",
3
+ "version": "0.0.1",
4
+ "type": "module",
5
+ "description": "Framework-agnostic accessibility utilities for weaveIntel UIs — pure, dependency-free helpers (focus restoration across full re-renders, etc.).",
6
+ "exports": {
7
+ ".": {
8
+ "import": "./dist/index.js",
9
+ "types": "./dist/index.d.ts",
10
+ "default": "./dist/index.js"
11
+ }
12
+ },
13
+ "main": "./dist/index.js",
14
+ "types": "./dist/index.d.ts",
15
+ "scripts": {
16
+ "build": "tsc -b",
17
+ "typecheck": "tsc --noEmit",
18
+ "test": "vitest run",
19
+ "clean": "rm -rf dist"
20
+ },
21
+ "devDependencies": {
22
+ "typescript": "^5.7.0",
23
+ "vitest": "^3.2.6"
24
+ },
25
+ "publishConfig": {
26
+ "access": "public"
27
+ },
28
+ "files": [
29
+ "dist",
30
+ "!dist/**/*.test.*",
31
+ "!dist/**/*.spec.*"
32
+ ]
33
+ }