@reticular/speakable 1.5.0 → 1.7.0

package/dist/storybook/dist/upgrade-5GL42JH4.js

@@ -0,0 +1,7 @@
+import {
+  awaitCustomElementsReady
+} from "./chunk-3SVI6IQE.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  awaitCustomElementsReady
+};

package/dist/types-Blh0EnZF.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Transport-agnostic static accessibility analysis.
+ *
+ * Wraps the core Speakable engine (tree-builder + per-reader renderers +
+ * audit) to produce differentiated screen reader output predictions from a
+ * live DOM element. This is the single source of truth consumed by the
+ * Storybook addon, the iframe harness, and the browser extension.
+ */
+interface AuditFinding {
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    selector: string;
+}
+interface AnalysisResult {
+    nvda: string[];
+    jaws: string[];
+    voiceover: string[];
+    narrator: string[];
+    audit: AuditFinding[];
+    stats: {
+        totalElements: number;
+        interactiveElements: number;
+        landmarks: number;
+        headings: number;
+    };
+    /** Tree-build and upgrade warnings surfaced to the user. */
+    warnings: string[];
+}
+/**
+ * Analyze a live DOM element using the core Speakable engine.
+ *
+ * Reuses buildAccessibilityTree + the four renderers + generateAuditReport.
+ * Never throws on empty or detached input — returns a well-formed empty result.
+ *
+ * @param root - DOM element to analyze
+ * @param extraWarnings - Optional warnings to fold in (e.g. upgrade timeouts)
+ * @returns Differentiated per-reader analysis result
+ */
+declare function analyzeElement(root: Element | null | undefined, extraWarnings?: string[]): AnalysisResult;
+/**
+ * Analyze a live DOM element after awaiting custom-element upgrade.
+ *
+ * Waits for web components under `root` to upgrade/render (bounded by
+ * `upgradeTimeoutMs`), then runs `analyzeElement`, folding any upgrade
+ * warnings into `result.warnings`. Use this in real-browser surfaces
+ * (harness, extension, addon) where components may hydrate asynchronously.
+ */
+declare function analyzeElementWithUpgrade(root: Element | null | undefined, upgradeTimeoutMs?: number): Promise<AnalysisResult>;
+
+/**
+ * Runtime Accessibility Timeline - Type System
+ *
+ * Normalized event structures for representing accessibility-relevant
+ * changes during component interaction. All events use a discriminated
+ * union via the `kind` field on payloads and the `type` field on actions.
+ */
+/**
+ * Classification of accessibility-relevant events observed during runtime.
+ */
+type EventType = 'FOCUS_CHANGED' | 'ANNOUNCEMENT' | 'DOM_MUTATION' | 'ROLE_CHANGED' | 'ACCESSIBLE_NAME_CHANGED' | 'STATE_CHANGED' | 'KEYBOARD_ACTION' | 'DIALOG_OPENED' | 'DIALOG_CLOSED' | 'WARNING' | 'REGRESSION';
+/**
+ * Identifies the DOM element targeted by an accessibility event.
+ */
+interface EventTarget {
+    /** ARIA role of the target element */
+    role: string;
+    /** Computed accessible name */
+    accessibleName: string;
+    /** Stable CSS selector path for element identification */
+    selector: string;
+}
+interface FocusChangedPayload {
+    kind: 'focus_changed';
+    previousTarget: EventTarget | null;
+}
+interface AnnouncementPayload {
+    kind: 'announcement';
+    politeness: 'polite' | 'assertive';
+    text: string;
+}
+interface RoleChangedPayload {
+    kind: 'role_changed';
+    previousRole: string;
+    newRole: string;
+}
+interface AccessibleNameChangedPayload {
+    kind: 'accessible_name_changed';
+    previousName: string;
+    newName: string;
+}
+interface StateChangedPayload {
+    kind: 'state_changed';
+    attribute: string;
+    previousValue: string | boolean | null;
+    newValue: string | boolean | null;
+}
+interface DialogOpenedPayload {
+    kind: 'dialog_opened';
+    dialogName: string;
+    isModal: boolean;
+}
+interface DialogClosedPayload {
+    kind: 'dialog_closed';
+    dialogName: string;
+}
+interface KeyboardActionPayload {
+    kind: 'keyboard_action';
+    key: string;
+    modifiers: string[];
+}
+interface WarningPayload {
+    kind: 'warning';
+    message: string;
+    relatedEvent?: AccessibilityEvent;
+}
+/**
+ * Discriminated union of all event payload types.
+ * Use the `kind` field to narrow the type.
+ */
+type EventPayload = FocusChangedPayload | AnnouncementPayload | RoleChangedPayload | AccessibleNameChangedPayload | StateChangedPayload | DialogOpenedPayload | DialogClosedPayload | KeyboardActionPayload | WarningPayload;
+/**
+ * A normalized event representing a single accessibility-relevant change.
+ * Contains common fields for classification, timing, targeting, and
+ * type-specific payload data.
+ */
+interface AccessibilityEvent {
+    /** Event classification */
+    type: EventType;
+    /** Milliseconds elapsed since session start */
+    timestamp: number;
+    /** Target element information */
+    target: EventTarget;
+    /** Type-specific payload data */
+    payload: EventPayload;
+}
+/**
+ * Discriminated union of interaction actions.
+ * Use the `type` field to narrow the action kind.
+ */
+type InteractionAction = {
+    type: 'click';
+    selector: string;
+} | {
+    type: 'tab';
+} | {
+    type: 'shiftTab';
+} | {
+    type: 'escape';
+} | {
+    type: 'enter';
+} | {
+    type: 'space';
+} | {
+    type: 'arrowUp';
+} | {
+    type: 'arrowDown';
+} | {
+    type: 'arrowLeft';
+} | {
+    type: 'arrowRight';
+} | {
+    type: 'key';
+    combo: string;
+} | {
+    type: 'wait';
+    ms: number;
+};
+/**
+ * An ordered sequence of user actions to perform during timeline capture.
+ */
+interface InteractionSequence {
+    /** Human-readable description of the interaction */
+    description: string;
+    /** Ordered list of actions to perform */
+    actions: InteractionAction[];
+}
+/**
+ * Metadata captured alongside an accessibility timeline session.
+ */
+interface TimelineMetadata {
+    /** ISO timestamp of when the timeline was captured */
+    capturedAt: string;
+    /** Speakable package version used for capture */
+    speakableVersion: string;
+    /** The URL that was analyzed */
+    sourceUrl: string;
+    /** Browser context identifier (e.g., "jsdom/23.0.0") */
+    userAgent: string;
+}
+/**
+ * A complete accessibility timeline captured during an interaction session.
+ * Contains the ordered event sequence, session metadata, and extracted warnings.
+ */
+interface AccessibilityTimeline {
+    /** Timeline format version string (e.g., "1.0") */
+    version: string;
+    /** Component name */
+    component: string;
+    /** Story or variant name */
+    story: string | null;
+    /** Human-readable description of the interaction sequence performed */
+    interactionSequence: string;
+    /** Total session duration in milliseconds */
+    duration: number;
+    /** All accessibility events in chronological order */
+    events: AccessibilityEvent[];
+    /** WARNING-type events extracted for quick reference */
+    warnings: AccessibilityEvent[];
+    /** Session capture metadata */
+    metadata: TimelineMetadata;
+}
+
+export { type AccessibilityTimeline as A, type InteractionSequence as I, type AnalysisResult as a, type AuditFinding as b, analyzeElement as c, analyzeElementWithUpgrade as d };

package/dist/upgrade-53M5VYGH.js

@@ -0,0 +1,7 @@
+import {
+  awaitCustomElementsReady
+} from "./chunk-WYFXGXYU.js";
+export {
+  awaitCustomElementsReady
+};
+//# sourceMappingURL=upgrade-53M5VYGH.js.map

package/dist/upgrade-53M5VYGH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,10 +1,25 @@
 {
   "name": "@reticular/speakable",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "CLI tool for analyzing HTML accessibility announcements",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.js"
+    },
+    "./harness": {
+      "types": "./dist/harness/index.d.ts",
+      "import": "./dist/harness/index.js"
+    },
+    "./storybook": "./dist/storybook/preset.js"
+  },
   "files": [
     "dist"
   ],
@@ -13,12 +28,13 @@
     "speakable-mcp": "dist/mcp.js"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && npm run build:addon",
+    "build:addon": "npm run build --prefix addon-speakable && cp -r addon-speakable/dist dist/storybook",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "storybook": "storybook dev -p 6006",
+    "storybook": "npm run build --prefix addon-speakable && concurrently -n addon,storybook -c blue,magenta \"npm run dev --prefix addon-speakable\" \"storybook dev -p 6006\"",
     "build-storybook": "storybook build",
     "test:a11y": "node --loader ts-node/esm stories/speakable-test.ts",
     "test:a11y:ci": "vitest run tests/multiselect-a11y.test.ts"
@@ -50,6 +66,7 @@
     "@types/jsdom": "^28.0.1",
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^3.1.0",
+    "concurrently": "^10.0.4",
     "fast-check": "^3.15.0",
     "storybook": "^8.6.18",
     "tsup": "^8.5.0",
@@ -62,5 +79,13 @@
     "jsdom": "^23.0.0",
     "picocolors": "^1.1.1",
     "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "storybook": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "storybook": {
+      "optional": true
+    }
   }
 }