@reticular/speakable 1.6.0 → 1.8.0

package/dist/chunk-WYFXGXYU.js

@@ -0,0 +1,87 @@
+// src/browser/upgrade.ts
+var DEFAULT_UPGRADE_TIMEOUT_MS = 2e3;
+function withTimeout(promise, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        resolve(false);
+      }
+    }, timeoutMs);
+    promise.then(
+      () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          resolve(true);
+        }
+      },
+      () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          resolve(true);
+        }
+      }
+    );
+  });
+}
+function collectCustomElementTags(root) {
+  const tags = /* @__PURE__ */ new Set();
+  const rootEl = "documentElement" in root ? root.documentElement : root;
+  if (!rootEl) return [];
+  const consider = (el) => {
+    if (el.localName && el.localName.includes("-")) {
+      tags.add(el.localName);
+    }
+  };
+  consider(rootEl);
+  const all = rootEl.querySelectorAll("*");
+  all.forEach(consider);
+  return Array.from(tags);
+}
+function collectUpdateCompletables(root) {
+  const rootEl = "documentElement" in root ? root.documentElement : root;
+  if (!rootEl) return [];
+  const promises = [];
+  const consider = (el) => {
+    const uc = el.updateComplete;
+    if (uc && typeof uc.then === "function") {
+      promises.push(uc);
+    }
+  };
+  consider(rootEl);
+  rootEl.querySelectorAll("*").forEach(consider);
+  return promises;
+}
+async function awaitCustomElementsReady(root, timeoutMs = DEFAULT_UPGRADE_TIMEOUT_MS) {
+  const warnings = [];
+  const hasCustomElements = typeof customElements !== "undefined" && customElements !== null;
+  if (!hasCustomElements) {
+    return warnings;
+  }
+  const tags = collectCustomElementTags(root);
+  await Promise.all(
+    tags.map(async (tag) => {
+      if (customElements.get(tag)) return;
+      const defined = await withTimeout(customElements.whenDefined(tag), timeoutMs);
+      if (!defined) {
+        warnings.push({
+          tag,
+          message: `Custom element "${tag}" did not upgrade within ${timeoutMs}ms; analysis may reflect a pre-hydration state.`
+        });
+      }
+    })
+  );
+  const updateCompletables = collectUpdateCompletables(root);
+  if (updateCompletables.length > 0) {
+    await withTimeout(Promise.all(updateCompletables), timeoutMs);
+  }
+  return warnings;
+}
+
+export {
+  awaitCustomElementsReady
+};
+//# sourceMappingURL=chunk-WYFXGXYU.js.map

package/dist/chunk-WYFXGXYU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser/upgrade.ts"],"sourcesContent":["/**\n * Custom-element upgrade awaiting.\n *\n * Runs in a real browser (needs `customElements`). Waits for custom elements\n * under a root to be defined and, where supported, to finish rendering\n * (Lit's `updateComplete`) before analysis/capture proceeds. Bounded by a\n * timeout so it never blocks indefinitely; unresolved tags become warnings.\n */\n\nexport interface UpgradeWarning {\n  message: string;\n  tag: string;\n}\n\nconst DEFAULT_UPGRADE_TIMEOUT_MS = 2000;\n\n/**\n * Resolve a promise, or resolve with a sentinel when the timeout elapses.\n * Returns true if the promise resolved in time, false on timeout.\n */\nfunction withTimeout(promise: Promise<unknown>, timeoutMs: number): Promise<boolean> {\n  return new Promise<boolean>(resolve => {\n    let settled = false;\n    const timer = setTimeout(() => {\n      if (!settled) {\n        settled = true;\n        resolve(false);\n      }\n    }, timeoutMs);\n\n    promise.then(\n      () => {\n        if (!settled) {\n          settled = true;\n          clearTimeout(timer);\n          resolve(true);\n        }\n      },\n      () => {\n        // A rejected upgrade promise still means \"no longer pending\".\n        if (!settled) {\n          settled = true;\n          clearTimeout(timer);\n          resolve(true);\n        }\n      }\n    );\n  });\n}\n\n/**\n * Collect distinct custom-element tag names present under a root.\n * A custom element tag always contains a hyphen.\n */\nfunction collectCustomElementTags(root: Document | Element): string[] {\n  const tags = new Set<string>();\n  const rootEl: Element | null =\n    'documentElement' in root ? (root as Document).documentElement : (root as Element);\n  if (!rootEl) return [];\n\n  const consider = (el: Element) => {\n    if (el.localName && el.localName.includes('-')) {\n      tags.add(el.localName);\n    }\n  };\n\n  consider(rootEl);\n  const all = rootEl.querySelectorAll('*');\n  all.forEach(consider);\n\n  return Array.from(tags);\n}\n\n/**\n * Collect elements that expose an `updateComplete` thenable (e.g. Lit).\n */\nfunction collectUpdateCompletables(root: Document | Element): Promise<unknown>[] {\n  const rootEl: Element | null =\n    'documentElement' in root ? (root as Document).documentElement : (root as Element);\n  if (!rootEl) return [];\n\n  const promises: Promise<unknown>[] = [];\n  const consider = (el: Element) => {\n    const uc = (el as unknown as { updateComplete?: unknown }).updateComplete;\n    if (uc && typeof (uc as Promise<unknown>).then === 'function') {\n      promises.push(uc as Promise<unknown>);\n    }\n  };\n\n  consider(rootEl);\n  rootEl.querySelectorAll('*').forEach(consider);\n  return promises;\n}\n\n/**\n * Wait for custom elements under `root` to upgrade and render.\n *\n * - Awaits `customElements.whenDefined(tag)` for each custom tag (bounded).\n * - Awaits any `updateComplete` promises found (bounded).\n * - On timeout, resolves anyway and returns a warning per unresolved tag.\n * - Never blocks indefinitely. No-op when `customElements` is unavailable.\n */\nexport async function awaitCustomElementsReady(\n  root: Document | Element,\n  timeoutMs: number = DEFAULT_UPGRADE_TIMEOUT_MS\n): Promise<UpgradeWarning[]> {\n  const warnings: UpgradeWarning[] = [];\n\n  const hasCustomElements =\n    typeof customElements !== 'undefined' && customElements !== null;\n\n  if (!hasCustomElements) {\n    return warnings;\n  }\n\n  const tags = collectCustomElementTags(root);\n\n  // Await definitions.\n  await Promise.all(\n    tags.map(async tag => {\n      // Already defined — nothing to wait for.\n      if (customElements.get(tag)) return;\n      const defined = await withTimeout(customElements.whenDefined(tag), timeoutMs);\n      if (!defined) {\n        warnings.push({\n          tag,\n          message: `Custom element \"${tag}\" did not upgrade within ${timeoutMs}ms; analysis may reflect a pre-hydration state.`,\n        });\n      }\n    })\n  );\n\n  // Await render completion where components expose it (Lit et al.).\n  const updateCompletables = collectUpdateCompletables(root);\n  if (updateCompletables.length > 0) {\n    await withTimeout(Promise.all(updateCompletables), timeoutMs);\n  }\n\n  return warnings;\n}\n"],"mappings":";AAcA,IAAM,6BAA6B;AAMnC,SAAS,YAAY,SAA2B,WAAqC;AACnF,SAAO,IAAI,QAAiB,aAAW;AACrC,QAAI,UAAU;AACd,UAAM,QAAQ,WAAW,MAAM;AAC7B,UAAI,CAAC,SAAS;AACZ,kBAAU;AACV,gBAAQ,KAAK;AAAA,MACf;AAAA,IACF,GAAG,SAAS;AAEZ,YAAQ;AAAA,MACN,MAAM;AACJ,YAAI,CAAC,SAAS;AACZ,oBAAU;AACV,uBAAa,KAAK;AAClB,kBAAQ,IAAI;AAAA,QACd;AAAA,MACF;AAAA,MACA,MAAM;AAEJ,YAAI,CAAC,SAAS;AACZ,oBAAU;AACV,uBAAa,KAAK;AAClB,kBAAQ,IAAI;AAAA,QACd;AAAA,MACF;AAAA,IACF;AAAA,EACF,CAAC;AACH;AAMA,SAAS,yBAAyB,MAAoC;AACpE,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,SACJ,qBAAqB,OAAQ,KAAkB,kBAAmB;AACpE,MAAI,CAAC,OAAQ,QAAO,CAAC;AAErB,QAAM,WAAW,CAAC,OAAgB;AAChC,QAAI,GAAG,aAAa,GAAG,UAAU,SAAS,GAAG,GAAG;AAC9C,WAAK,IAAI,GAAG,SAAS;AAAA,IACvB;AAAA,EACF;AAEA,WAAS,MAAM;AACf,QAAM,MAAM,OAAO,iBAAiB,GAAG;AACvC,MAAI,QAAQ,QAAQ;AAEpB,SAAO,MAAM,KAAK,IAAI;AACxB;AAKA,SAAS,0BAA0B,MAA8C;AAC/E,QAAM,SACJ,qBAAqB,OAAQ,KAAkB,kBAAmB;AACpE,MAAI,CAAC,OAAQ,QAAO,CAAC;AAErB,QAAM,WAA+B,CAAC;AACtC,QAAM,WAAW,CAAC,OAAgB;AAChC,UAAM,KAAM,GAA+C;AAC3D,QAAI,MAAM,OAAQ,GAAwB,SAAS,YAAY;AAC7D,eAAS,KAAK,EAAsB;AAAA,IACtC;AAAA,EACF;AAEA,WAAS,MAAM;AACf,SAAO,iBAAiB,GAAG,EAAE,QAAQ,QAAQ;AAC7C,SAAO;AACT;AAUA,eAAsB,yBACpB,MACA,YAAoB,4BACO;AAC3B,QAAM,WAA6B,CAAC;AAEpC,QAAM,oBACJ,OAAO,mBAAmB,eAAe,mBAAmB;AAE9D,MAAI,CAAC,mBAAmB;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,OAAO,yBAAyB,IAAI;AAG1C,QAAM,QAAQ;AAAA,IACZ,KAAK,IAAI,OAAM,QAAO;AAEpB,UAAI,eAAe,IAAI,GAAG,EAAG;AAC7B,YAAM,UAAU,MAAM,YAAY,eAAe,YAAY,GAAG,GAAG,SAAS;AAC5E,UAAI,CAAC,SAAS;AACZ,iBAAS,KAAK;AAAA,UACZ;AAAA,UACA,SAAS,mBAAmB,GAAG,4BAA4B,SAAS;AAAA,QACtE,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAAA,EACH;AAGA,QAAM,qBAAqB,0BAA0B,IAAI;AACzD,MAAI,mBAAmB,SAAS,GAAG;AACjC,UAAM,YAAY,QAAQ,IAAI,kBAAkB,GAAG,SAAS;AAAA,EAC9D;AAEA,SAAO;AACT;","names":[]}

package/dist/cli.js

@@ -526,6 +526,12 @@ var SUPPORTED_ROLES = [
   "meter",
   "progressbar",
   "status",
+  "switch",
+  "slider",
+  "spinbutton",
+  "tab",
+  "tablist",
+  "tabpanel",
   "document",
   "application",
   "separator"
@@ -622,7 +628,10 @@ var INPUT_TYPE_ROLE_MAP = {
   "search": "textbox",
   "tel": "textbox",
   "url": "textbox",
-  "number": "textbox"
+  // Per ARIA, <input type="number"> has an implicit role of spinbutton
+  // (VoiceOver announces it as "stepper").
+  "number": "spinbutton",
+  "range": "slider"
 };
 function computeRole(element) {
   const warnings = [];
@@ -655,6 +664,11 @@ function computeImplicitRole(element, _warnings) {
   if (tagName === "input") {
     return computeInputRole(element);
   }
+  if (tagName === "select") {
+    const multiple = element.hasAttribute("multiple");
+    const size = parseInt(element.getAttribute("size") || "0", 10);
+    return multiple || size > 1 ? "listbox" : "combobox";
+  }
   if (tagName === "a") {
     return element.hasAttribute("href") ? "link" : null;
   }
@@ -1064,6 +1078,7 @@ function processChildNode(node, children, warnings) {
   if (node.nodeType === 1) {
     const element = node;
     if (isHidden(element)) return;
+    if (isConsumedLabel(element)) return;
     if (!isAccessible(element)) {
       const grandchildren = collectChildrenFromRolelessElement(element, warnings);
       children.push(...grandchildren);
@@ -1073,18 +1088,74 @@ function processChildNode(node, children, warnings) {
     if (childNode) children.push(childNode);
   }
 }
+function isConsumedLabel(element) {
+  if (element.tagName.toLowerCase() !== "label") return false;
+  const forId = element.getAttribute("for");
+  if (forId) {
+    const doc = element.ownerDocument;
+    const target = doc?.getElementById(forId);
+    if (target && isLabelableControl(target)) return true;
+  }
+  const wrapped = element.querySelector("input, select, textarea, button, meter, progress");
+  if (wrapped && isLabelableControl(wrapped)) return true;
+  return false;
+}
+function isLabelableControl(element) {
+  const tag = element.tagName.toLowerCase();
+  if (tag === "input") {
+    return (element.getAttribute("type") || "text").toLowerCase() !== "hidden";
+  }
+  return tag === "select" || tag === "textarea" || tag === "button" || tag === "meter" || tag === "progress";
+}
 function collectChildrenFromRolelessElement(element, warnings) {
+  return collectAccessibleChildren(element, warnings);
+}
+function collectAccessibleChildren(element, warnings) {
   const children = [];
   if (element.shadowRoot) {
     for (const child of Array.from(element.shadowRoot.childNodes)) {
-      processChildNode(child, children, warnings);
+      processShadowNode(child, children, warnings);
     }
+    return children;
+  }
+  if (element.localName && element.localName.includes("-") && element.childNodes.length === 0) {
+    warnings.push({
+      message: `Custom element <${element.localName}> has no accessible children and may have a closed shadow root; its content could not be analyzed.`,
+      element
+    });
   }
   for (const child of Array.from(element.childNodes)) {
     processChildNode(child, children, warnings);
   }
   return children;
 }
+function processShadowNode(node, children, warnings) {
+  if (node.nodeType === 1) {
+    const element = node;
+    if (element.localName === "slot") {
+      const slot = element;
+      let assigned = [];
+      if (typeof slot.assignedNodes === "function") {
+        try {
+          assigned = Array.from(slot.assignedNodes({ flatten: true }));
+        } catch {
+          assigned = [];
+        }
+      }
+      if (assigned.length > 0) {
+        for (const assignedNode of assigned) {
+          processChildNode(assignedNode, children, warnings);
+        }
+      } else {
+        for (const child of Array.from(slot.childNodes)) {
+          processShadowNode(child, children, warnings);
+        }
+      }
+      return;
+    }
+  }
+  processChildNode(node, children, warnings);
+}
 function buildAccessibilityTree(rootElement, sourceHash) {
   const warnings = [];
   if (isHidden(rootElement)) {
@@ -1141,6 +1212,30 @@ function buildAccessibilityTreeWithSelector(rootElement, selector, sourceHash) {
   }
   return results;
 }
+var SET_MEMBER_ROLES = /* @__PURE__ */ new Set([
+  "radio",
+  "option",
+  "listitem",
+  "tab"
+]);
+function assignImplicitSetPosition(children) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const child of children) {
+    if (SET_MEMBER_ROLES.has(child.role)) {
+      totals.set(child.role, (totals.get(child.role) ?? 0) + 1);
+    }
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const child of children) {
+    if (!SET_MEMBER_ROLES.has(child.role)) continue;
+    const total = totals.get(child.role);
+    if (total < 2) continue;
+    const pos = (seen.get(child.role) ?? 0) + 1;
+    seen.set(child.role, pos);
+    if (child.state.posinset === void 0) child.state.posinset = pos;
+    if (child.state.setsize === void 0) child.state.setsize = total;
+  }
+}
 function buildNodeRecursive(element, warnings) {
   if (isHidden(element)) {
     return null;
@@ -1177,15 +1272,15 @@ function buildNodeRecursive(element, warnings) {
     element: w.element
   })));
   const focusInfo = extractFocusInfo(element);
-  const children = [];
-  if (element.shadowRoot) {
-    for (const child of Array.from(element.shadowRoot.childNodes)) {
-      processChildNode(child, children, warnings);
+  let children = collectAccessibleChildren(element, warnings);
+  const isNativeSelect = element.tagName.toLowerCase() === "select";
+  if (isNativeSelect && roleResult.role === "combobox") {
+    children = [];
+    if (stateResult.state.expanded === void 0) {
+      stateResult.state.expanded = false;
     }
   }
-  for (const child of Array.from(element.childNodes)) {
-    processChildNode(child, children, warnings);
-  }
+  assignImplicitSetPosition(children);
   const node = {
     role: roleResult.role,
     name: nameResult.name,
@@ -1198,15 +1293,7 @@ function buildNodeRecursive(element, warnings) {
   return node;
 }
 function createGenericContainer(rootElement, warnings) {
-  const children = [];
-  if (rootElement.shadowRoot) {
-    for (const child of Array.from(rootElement.shadowRoot.childNodes)) {
-      processChildNode(child, children, warnings);
-    }
-  }
-  for (const child of Array.from(rootElement.childNodes)) {
-    processChildNode(child, children, warnings);
-  }
+  const children = collectAccessibleChildren(rootElement, warnings);
   return {
     role: "generic",
     name: "",
@@ -1828,8 +1915,45 @@ function renderNodeVoiceOver(node, announcements, c) {
     renderNodeVoiceOver(child, announcements, c);
   }
 }
+function isValueFirstWidget(role) {
+  return role === "slider" || role === "spinbutton" || role === "combobox";
+}
+function isValueBeforeRoleWidget(role) {
+  return role === "progressbar" || role === "meter";
+}
+function isSilentContainerVoiceOver(node) {
+  if (node.role !== "list" && node.role !== "status") return false;
+  if (node.name) return false;
+  return node.children.length > 0;
+}
 function formatNodeVoiceOver(node, c) {
+  if (isSilentContainerVoiceOver(node)) {
+    return "";
+  }
   const parts = [];
+  const valueFirst = isValueFirstWidget(node.role) && node.value !== void 0;
+  if (valueFirst) {
+    const valueText = node.value.text || String(node.value.current);
+    if (valueText) parts.push(valueText);
+    if (node.name) parts.push(c.elementName(node.name));
+    const roleText = formatRoleVoiceOver(node);
+    if (roleText) parts.push(c.roleName(roleText));
+    const stateText2 = formatStatesVoiceOver(node);
+    if (stateText2) parts.push(c.stateName(stateText2));
+    if (node.description) parts.push(c.description(node.description));
+    return parts.join(", ");
+  }
+  if (isValueBeforeRoleWidget(node.role) && node.value !== void 0) {
+    if (node.name) parts.push(c.elementName(node.name));
+    const valueText = node.value.text || String(node.value.current);
+    if (valueText) parts.push(valueText);
+    const roleText = formatRoleVoiceOver(node);
+    if (roleText) parts.push(c.roleName(roleText));
+    const stateText2 = formatStatesVoiceOver(node);
+    if (stateText2) parts.push(c.stateName(stateText2));
+    if (node.description) parts.push(c.description(node.description));
+    return parts.join(", ");
+  }
   const roleFirst = shouldAnnounceRoleFirst(node.role);
   if (roleFirst) {
     const roleText = formatRoleVoiceOver(node);
@@ -1858,6 +1982,9 @@ function formatNodeVoiceOver(node, c) {
       parts.push(valueText);
     }
   }
+  if (node.state.posinset !== void 0 && node.state.setsize !== void 0) {
+    parts.push(`${node.state.posinset} of ${node.state.setsize}`);
+  }
   if (node.description) {
     parts.push(c.description(node.description));
   }
@@ -1893,7 +2020,7 @@ function formatRoleVoiceOver(node) {
     case "list":
       return "list";
     case "listitem":
-      return "item";
+      return "";
     case "navigation":
       return "navigation";
     case "main":
@@ -1949,6 +2076,18 @@ function formatRoleVoiceOver(node) {
       return "progress indicator";
     case "status":
       return "status";
+    case "switch":
+      return "switch";
+    case "slider":
+      return "slider";
+    case "spinbutton":
+      return "stepper";
+    case "tab":
+      return "tab";
+    case "tablist":
+      return node.name ? "tab group" : "tab group";
+    case "tabpanel":
+      return "tab panel";
     case "group":
       return node.name ? "group" : "";
     case "document":
@@ -1969,6 +2108,10 @@ function formatStatesVoiceOver(node) {
   if (node.state.checked !== void 0) {
     if (node.state.checked === "mixed") {
       states.push("mixed");
+    } else if (node.role === "switch") {
+      states.push(node.state.checked ? "on" : "off");
+    } else if (node.role === "radio") {
+      if (node.state.checked) states.push("selected");
     } else {
       states.push(node.state.checked ? "checked" : "unchecked");
     }
@@ -1977,10 +2120,10 @@ function formatStatesVoiceOver(node) {
     if (node.state.pressed === "mixed") {
       states.push("mixed");
     } else {
-      states.push(node.state.pressed ? "pressed" : "not pressed");
+      states.push(node.state.pressed ? "selected" : "unselected");
     }
   }
-  if (node.state.selected !== void 0) {
+  if (node.state.selected !== void 0 && node.role !== "tab") {
     states.push(node.state.selected ? "selected" : "unselected");
   }
   if (node.state.disabled) {