@reticular/speakable 1.5.0 → 1.7.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

@@ -1074,17 +1074,54 @@ function processChildNode(node, children, warnings) {
   }
 }
 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)) {
@@ -1177,15 +1214,7 @@ 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);
-    }
-  }
-  for (const child of Array.from(element.childNodes)) {
-    processChildNode(child, children, warnings);
-  }
+  const children = collectAccessibleChildren(element, warnings);
   const node = {
     role: roleResult.role,
     name: nameResult.name,
@@ -1198,15 +1227,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: "",