@generative-a11y/dom 0.2.0 → 0.3.0

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.
Files changed (8) hide show
  1. package/README.md +57 -32
  2. package/dist/index.cjs +69 -11
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +34 -16
  5. package/dist/index.d.ts +34 -16
  6. package/dist/index.js +66 -9
  7. package/dist/index.js.map +1 -1
  8. package/package.json +2 -2
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { PresetName, PolicyOverrides, AnnouncementIntent, GenerativeA11yRuntime } from '@generative-a11y/core';
1
+ import { Runtime, PresetName, PolicyOverrides, AnnouncementIntent } from '@generative-a11y/core';
2
2
 
3
3
  interface ExternalStore<T> {
4
4
  subscribe(listener: () => void): () => void;
@@ -31,6 +31,16 @@ interface AttentionIntersectionObserver {
31
31
  type AttentionIntersectionObserverFactory = (callback: IntersectionObserverCallback, options?: IntersectionObserverInit) => AttentionIntersectionObserver;
32
32
  declare function createAttentionStore(options?: AttentionStoreOptions): AttentionStore;
33
33
 
34
+ interface AttentionBindingOptions {
35
+ readonly runtime: Runtime;
36
+ readonly attentionStore: AttentionStore;
37
+ }
38
+ interface AttentionBinding {
39
+ dispose(): void;
40
+ }
41
+ /** Borrow a store and runtime, forwarding observations without changing overrides. */
42
+ declare function bindAttention({ runtime, attentionStore, }: AttentionBindingOptions): AttentionBinding;
43
+
34
44
  interface FocusCapture {
35
45
  readonly document: Document | null;
36
46
  readonly target: Element | null;
@@ -111,12 +121,12 @@ declare function createPreferenceStore(options?: PreferenceStoreOptions): Prefer
111
121
  declare function normalizePreferences(value: PreferenceSchemaV1): PreferenceSchemaV1;
112
122
  declare function samePreferences(left: PreferenceSchemaV1, right: PreferenceSchemaV1): boolean;
113
123
 
114
- type DOMAnnouncementMode = "auto" | "aria-notify" | "live-region";
115
- interface DOMLiveRegions {
124
+ type DeliveryMode = "auto" | "live-region";
125
+ interface LiveRegions {
116
126
  polite: HTMLElement;
117
127
  assertive: HTMLElement;
118
128
  }
119
- interface DOMDeliveryResult {
129
+ interface DeliveryResult {
120
130
  status: "notified" | "mutated" | "unavailable" | "disposed";
121
131
  method: "aria-notify" | "live-region" | "none";
122
132
  channel: AnnouncementIntent["channel"];
@@ -127,27 +137,35 @@ interface DOMDeliveryResult {
127
137
  responseId?: string;
128
138
  toolId?: string;
129
139
  interactionId?: string;
140
+ /** Stable logical run identity associated with the delivered intent. */
141
+ runId?: string;
142
+ /** Stable run attempt identity associated with the delivered intent. */
143
+ runInstanceId?: string;
144
+ /** Stable logical step identity associated with the delivered intent. */
145
+ stepId?: string;
146
+ /** Stable step attempt identity associated with the delivered intent. */
147
+ stepInstanceId?: string;
130
148
  error?: {
131
149
  name: string;
132
150
  message: string;
133
151
  };
134
152
  }
135
- interface DOMAnnouncerOptions {
153
+ interface AnnouncerOptions {
136
154
  document?: Document;
137
- mode?: DOMAnnouncementMode;
138
- regions?: DOMLiveRegions;
139
- onDiagnostic?: (result: DOMDeliveryResult) => void;
155
+ mode?: DeliveryMode;
156
+ regions?: LiveRegions;
157
+ onDelivery?: (result: DeliveryResult) => void;
140
158
  }
141
- interface DOMAnnouncer {
142
- announce(intent: AnnouncementIntent): DOMDeliveryResult;
143
- getRegions(): DOMLiveRegions | undefined;
159
+ interface Announcer {
160
+ announce(intent: AnnouncementIntent): DeliveryResult;
161
+ getRegions(): LiveRegions | undefined;
144
162
  dispose(): void;
145
163
  }
146
- interface DOMRuntimeBinding {
147
- announcer: DOMAnnouncer;
164
+ interface RuntimeBinding {
165
+ announcer: Announcer;
148
166
  dispose(): void;
149
167
  }
150
- declare function createDOMAnnouncer(options?: DOMAnnouncerOptions): DOMAnnouncer;
151
- declare function connectRuntimeToDOM(runtime: GenerativeA11yRuntime, options?: DOMAnnouncerOptions): DOMRuntimeBinding;
168
+ declare function createAnnouncer(options?: AnnouncerOptions): Announcer;
169
+ declare function bindRuntime(runtime: Runtime, options?: AnnouncerOptions): RuntimeBinding;
152
170
 
153
- export { type AttentionIntersectionObserver, type AttentionIntersectionObserverFactory, type AttentionSnapshot, type AttentionStore, type AttentionStoreOptions, type CorePreferenceConfiguration, type DOMAnnouncementMode, type DOMAnnouncer, type DOMAnnouncerOptions, type DOMDeliveryResult, type DOMLiveRegions, type DOMRuntimeBinding, type ExternalStore, type FocusCapture, type FocusElementOptions, type FocusResult, type FocusSkippedReason, type PreferenceDiagnostic, type PreferenceDiagnosticCode, type PreferenceDiagnosticSource, type PreferencePersistence, type PreferenceSchemaV1, type PreferenceStorage, type PreferenceStorageEvent, type PreferenceStorageEventSource, type PreferenceStore, type PreferenceStoreOptions, type RestoreFocusOptions, type StreamingVerbosity, type ToolVerbosity, captureFocus, connectRuntimeToDOM, createAttentionStore, createDOMAnnouncer, createPreferenceStore, defaultPreferences, focusElement, normalizePreferences, preferencesToCoreConfiguration, restoreFocus, samePreferences };
171
+ export { type Announcer, type AnnouncerOptions, type AttentionBinding, type AttentionBindingOptions, type AttentionIntersectionObserver, type AttentionIntersectionObserverFactory, type AttentionSnapshot, type AttentionStore, type AttentionStoreOptions, type CorePreferenceConfiguration, type DeliveryMode, type DeliveryResult, type ExternalStore, type FocusCapture, type FocusElementOptions, type FocusResult, type FocusSkippedReason, type LiveRegions, type PreferenceDiagnostic, type PreferenceDiagnosticCode, type PreferenceDiagnosticSource, type PreferencePersistence, type PreferenceSchemaV1, type PreferenceStorage, type PreferenceStorageEvent, type PreferenceStorageEventSource, type PreferenceStore, type PreferenceStoreOptions, type RestoreFocusOptions, type RuntimeBinding, type StreamingVerbosity, type ToolVerbosity, bindAttention, bindRuntime, captureFocus, createAnnouncer, createAttentionStore, createPreferenceStore, defaultPreferences, focusElement, normalizePreferences, preferencesToCoreConfiguration, restoreFocus, samePreferences };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { PresetName, PolicyOverrides, AnnouncementIntent, GenerativeA11yRuntime } from '@generative-a11y/core';
1
+ import { Runtime, PresetName, PolicyOverrides, AnnouncementIntent } from '@generative-a11y/core';
2
2
 
3
3
  interface ExternalStore<T> {
4
4
  subscribe(listener: () => void): () => void;
@@ -31,6 +31,16 @@ interface AttentionIntersectionObserver {
31
31
  type AttentionIntersectionObserverFactory = (callback: IntersectionObserverCallback, options?: IntersectionObserverInit) => AttentionIntersectionObserver;
32
32
  declare function createAttentionStore(options?: AttentionStoreOptions): AttentionStore;
33
33
 
34
+ interface AttentionBindingOptions {
35
+ readonly runtime: Runtime;
36
+ readonly attentionStore: AttentionStore;
37
+ }
38
+ interface AttentionBinding {
39
+ dispose(): void;
40
+ }
41
+ /** Borrow a store and runtime, forwarding observations without changing overrides. */
42
+ declare function bindAttention({ runtime, attentionStore, }: AttentionBindingOptions): AttentionBinding;
43
+
34
44
  interface FocusCapture {
35
45
  readonly document: Document | null;
36
46
  readonly target: Element | null;
@@ -111,12 +121,12 @@ declare function createPreferenceStore(options?: PreferenceStoreOptions): Prefer
111
121
  declare function normalizePreferences(value: PreferenceSchemaV1): PreferenceSchemaV1;
112
122
  declare function samePreferences(left: PreferenceSchemaV1, right: PreferenceSchemaV1): boolean;
113
123
 
114
- type DOMAnnouncementMode = "auto" | "aria-notify" | "live-region";
115
- interface DOMLiveRegions {
124
+ type DeliveryMode = "auto" | "live-region";
125
+ interface LiveRegions {
116
126
  polite: HTMLElement;
117
127
  assertive: HTMLElement;
118
128
  }
119
- interface DOMDeliveryResult {
129
+ interface DeliveryResult {
120
130
  status: "notified" | "mutated" | "unavailable" | "disposed";
121
131
  method: "aria-notify" | "live-region" | "none";
122
132
  channel: AnnouncementIntent["channel"];
@@ -127,27 +137,35 @@ interface DOMDeliveryResult {
127
137
  responseId?: string;
128
138
  toolId?: string;
129
139
  interactionId?: string;
140
+ /** Stable logical run identity associated with the delivered intent. */
141
+ runId?: string;
142
+ /** Stable run attempt identity associated with the delivered intent. */
143
+ runInstanceId?: string;
144
+ /** Stable logical step identity associated with the delivered intent. */
145
+ stepId?: string;
146
+ /** Stable step attempt identity associated with the delivered intent. */
147
+ stepInstanceId?: string;
130
148
  error?: {
131
149
  name: string;
132
150
  message: string;
133
151
  };
134
152
  }
135
- interface DOMAnnouncerOptions {
153
+ interface AnnouncerOptions {
136
154
  document?: Document;
137
- mode?: DOMAnnouncementMode;
138
- regions?: DOMLiveRegions;
139
- onDiagnostic?: (result: DOMDeliveryResult) => void;
155
+ mode?: DeliveryMode;
156
+ regions?: LiveRegions;
157
+ onDelivery?: (result: DeliveryResult) => void;
140
158
  }
141
- interface DOMAnnouncer {
142
- announce(intent: AnnouncementIntent): DOMDeliveryResult;
143
- getRegions(): DOMLiveRegions | undefined;
159
+ interface Announcer {
160
+ announce(intent: AnnouncementIntent): DeliveryResult;
161
+ getRegions(): LiveRegions | undefined;
144
162
  dispose(): void;
145
163
  }
146
- interface DOMRuntimeBinding {
147
- announcer: DOMAnnouncer;
164
+ interface RuntimeBinding {
165
+ announcer: Announcer;
148
166
  dispose(): void;
149
167
  }
150
- declare function createDOMAnnouncer(options?: DOMAnnouncerOptions): DOMAnnouncer;
151
- declare function connectRuntimeToDOM(runtime: GenerativeA11yRuntime, options?: DOMAnnouncerOptions): DOMRuntimeBinding;
168
+ declare function createAnnouncer(options?: AnnouncerOptions): Announcer;
169
+ declare function bindRuntime(runtime: Runtime, options?: AnnouncerOptions): RuntimeBinding;
152
170
 
153
- export { type AttentionIntersectionObserver, type AttentionIntersectionObserverFactory, type AttentionSnapshot, type AttentionStore, type AttentionStoreOptions, type CorePreferenceConfiguration, type DOMAnnouncementMode, type DOMAnnouncer, type DOMAnnouncerOptions, type DOMDeliveryResult, type DOMLiveRegions, type DOMRuntimeBinding, type ExternalStore, type FocusCapture, type FocusElementOptions, type FocusResult, type FocusSkippedReason, type PreferenceDiagnostic, type PreferenceDiagnosticCode, type PreferenceDiagnosticSource, type PreferencePersistence, type PreferenceSchemaV1, type PreferenceStorage, type PreferenceStorageEvent, type PreferenceStorageEventSource, type PreferenceStore, type PreferenceStoreOptions, type RestoreFocusOptions, type StreamingVerbosity, type ToolVerbosity, captureFocus, connectRuntimeToDOM, createAttentionStore, createDOMAnnouncer, createPreferenceStore, defaultPreferences, focusElement, normalizePreferences, preferencesToCoreConfiguration, restoreFocus, samePreferences };
171
+ export { type Announcer, type AnnouncerOptions, type AttentionBinding, type AttentionBindingOptions, type AttentionIntersectionObserver, type AttentionIntersectionObserverFactory, type AttentionSnapshot, type AttentionStore, type AttentionStoreOptions, type CorePreferenceConfiguration, type DeliveryMode, type DeliveryResult, type ExternalStore, type FocusCapture, type FocusElementOptions, type FocusResult, type FocusSkippedReason, type LiveRegions, type PreferenceDiagnostic, type PreferenceDiagnosticCode, type PreferenceDiagnosticSource, type PreferencePersistence, type PreferenceSchemaV1, type PreferenceStorage, type PreferenceStorageEvent, type PreferenceStorageEventSource, type PreferenceStore, type PreferenceStoreOptions, type RestoreFocusOptions, type RuntimeBinding, type StreamingVerbosity, type ToolVerbosity, bindAttention, bindRuntime, captureFocus, createAnnouncer, createAttentionStore, createPreferenceStore, defaultPreferences, focusElement, normalizePreferences, preferencesToCoreConfiguration, restoreFocus, samePreferences };
package/dist/index.js CHANGED
@@ -1,3 +1,53 @@
1
+ // src/attention-binding.ts
2
+ var boundRuntimes = /* @__PURE__ */ new WeakSet();
3
+ function bindAttention({
4
+ runtime,
5
+ attentionStore
6
+ }) {
7
+ if (boundRuntimes.has(runtime)) {
8
+ throw new Error("Runtime already has an attention binding");
9
+ }
10
+ boundRuntimes.add(runtime);
11
+ let active = true;
12
+ let unsubscribe;
13
+ let lastMode;
14
+ let revision = 0;
15
+ const update = () => {
16
+ if (!active) return;
17
+ const readRevision = ++revision;
18
+ const mode = attentionStore.getSnapshot().mode;
19
+ if (!active || revision !== readRevision || mode === lastMode) return;
20
+ lastMode = mode;
21
+ runtime.dispatch({ type: "attention.changed", mode });
22
+ };
23
+ const dispose = () => {
24
+ if (!active) return;
25
+ active = false;
26
+ try {
27
+ try {
28
+ unsubscribe?.();
29
+ } catch {
30
+ }
31
+ if (lastMode !== void 0) {
32
+ runtime.dispatch({ type: "attention.changed", mode: "unknown" });
33
+ }
34
+ } finally {
35
+ boundRuntimes.delete(runtime);
36
+ }
37
+ };
38
+ try {
39
+ unsubscribe = attentionStore.subscribe(update);
40
+ update();
41
+ } catch (error) {
42
+ try {
43
+ dispose();
44
+ } catch {
45
+ }
46
+ throw error;
47
+ }
48
+ return { dispose };
49
+ }
50
+
1
51
  // src/composed-tree.ts
2
52
  function deepActiveElement(document2) {
3
53
  let active = document2.activeElement;
@@ -145,7 +195,7 @@ function createAttentionStore(options = {}) {
145
195
  update();
146
196
  };
147
197
  };
148
- const createObserver = (registration, target) => {
198
+ const createChatObserver = (registration, target) => {
149
199
  const factory = options.createIntersectionObserver ?? defaultIntersectionObserverFactory(selectedWindow);
150
200
  if (!factory) return void 0;
151
201
  let created;
@@ -195,7 +245,7 @@ function createAttentionStore(options = {}) {
195
245
  stopObserver(newestTarget);
196
246
  newestTarget = element;
197
247
  newestResult = "unknown";
198
- observer = createObserver(registration, element);
248
+ observer = createChatObserver(registration, element);
199
249
  update();
200
250
  let registered = true;
201
251
  return () => {
@@ -763,7 +813,9 @@ function serializeError(cause) {
763
813
  }
764
814
 
765
815
  // src/index.ts
766
- function createDOMAnnouncer(options = {}) {
816
+ function createAnnouncer(options = {}) {
817
+ if (options.mode !== void 0 && options.mode !== "auto" && options.mode !== "live-region")
818
+ throw new TypeError('mode must be "auto" or "live-region"');
767
819
  validateSuppliedRegions(options);
768
820
  const selectedDocument = options.document ?? options.regions?.polite.ownerDocument ?? (typeof document === "undefined" ? void 0 : document);
769
821
  const ownsRegions = options.regions === void 0;
@@ -776,7 +828,7 @@ function createDOMAnnouncer(options = {}) {
776
828
  let disposed = false;
777
829
  const report = (result) => {
778
830
  try {
779
- options.onDiagnostic?.(result);
831
+ options.onDelivery?.(result);
780
832
  } catch {
781
833
  }
782
834
  return result;
@@ -855,7 +907,11 @@ function deliveryContext(intent) {
855
907
  ...intent.sourceEventId !== void 0 ? { sourceEventId: intent.sourceEventId } : {},
856
908
  ...intent.responseId !== void 0 ? { responseId: intent.responseId } : {},
857
909
  ...intent.toolId !== void 0 ? { toolId: intent.toolId } : {},
858
- ...intent.interactionId !== void 0 ? { interactionId: intent.interactionId } : {}
910
+ ...intent.interactionId !== void 0 ? { interactionId: intent.interactionId } : {},
911
+ ...intent.runId !== void 0 ? { runId: intent.runId } : {},
912
+ ...intent.runInstanceId !== void 0 ? { runInstanceId: intent.runInstanceId } : {},
913
+ ...intent.stepId !== void 0 ? { stepId: intent.stepId } : {},
914
+ ...intent.stepInstanceId !== void 0 ? { stepInstanceId: intent.stepInstanceId } : {}
859
915
  };
860
916
  }
861
917
  function validateSuppliedRegions(options) {
@@ -950,8 +1006,8 @@ function applyLocale(region, locale) {
950
1006
  if (locale === void 0) region.removeAttribute("lang");
951
1007
  else region.setAttribute("lang", locale);
952
1008
  }
953
- function connectRuntimeToDOM(runtime, options = {}) {
954
- const announcer = createDOMAnnouncer(options);
1009
+ function bindRuntime(runtime, options = {}) {
1010
+ const announcer = createAnnouncer(options);
955
1011
  let disposed = false;
956
1012
  let unsubscribe;
957
1013
  try {
@@ -976,10 +1032,11 @@ function connectRuntimeToDOM(runtime, options = {}) {
976
1032
  };
977
1033
  }
978
1034
  export {
1035
+ bindAttention,
1036
+ bindRuntime,
979
1037
  captureFocus,
980
- connectRuntimeToDOM,
1038
+ createAnnouncer,
981
1039
  createAttentionStore,
982
- createDOMAnnouncer,
983
1040
  createPreferenceStore,
984
1041
  defaultPreferences,
985
1042
  focusElement,