@overpunch/speechtype 1.0.11 → 1.1.0

package/dist/core.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Emphasise the word containing the span at activeIndex (every span of a word split by markup); dim the
+ * others. Pass -1 to reset all words to neutral. The emphasis is a heavier weight, larger optical size and
+ * wider tracking around the text's own values (explicit options are absolute).
+ *
+ * @param el          - Element previously prepared by prepareSpeechType
+ * @param activeIndex - Index of the word span to emphasise, -1 for none
+ * @param options     - SpeechTypeOptions (merged with defaults)
+ */
+export declare function applySpeechType(el: HTMLElement, activeIndex: number, options?: SpeechTypeOptions): void;
+
+/**
+ * The element's markup without speechType's word spans. Exact for a prepared element; for any other
+ * element, unwraps .st-word spans.
+ *
+ * @param el - Element to read clean HTML from
+ */
+export declare function getCleanHTML(el: HTMLElement): string;
+
+/**
+ * Wrap each visible word of el in a <span class="st-word">, in place: the element's markup, ids,
+ * listeners, form values and line breaks are kept, and hidden text, styles, scripts, form fields and SVG
+ * are left alone (and not spoken). The text stays readable to screen readers. Idempotent — calling again
+ * re-wraps from the original. Returns the word spans in document order.
+ *
+ * @param el      - Element whose text will be wrapped
+ * @param options - SpeechTypeOptions (transitionMs is used)
+ */
+export declare function prepareSpeechType(el: HTMLElement, options?: SpeechTypeOptions): HTMLElement[];
+
+/**
+ * Stop this element's speech (only if it is speaking), put the original text nodes back and delete the
+ * saved state. No-op if prepareSpeechType was never called.
+ *
+ * @param el - The element previously prepared by prepareSpeechType
+ */
+export declare function removeSpeechType(el: HTMLElement): void;
+
+/**
+ * CSS class names injected by speechType.
+ * Only `word` ('st-word') is used — there are no st-active or st-inactive classes.
+ * Emphasis is applied via inline styles (fontVariationSettings, letterSpacing, opacity),
+ * not via class toggles.
+ */
+export declare const SPEECH_CLASSES: {
+    readonly word: "st-word";
+};
+
+/**
+ * Options controlling how speechType emphasises spoken words.
+ *
+ * @remarks
+ * Visual options (activeTracking, activeWeight, activeOpsz, inactiveOpacity, transitionMs)
+ * are used by prepareSpeechType and applySpeechType.
+ * Speech options (rate, pitch, volume) are only used by startSpeechType and are ignored
+ * by applySpeechType, useSpeechType, and SpeechTypeText.
+ *
+ * activeWeight and activeOpsz are written directly into font-variation-settings. Ensure
+ * the values are within the wght/opsz axis ranges supported by your font — out-of-range
+ * values may cause some engines to silently ignore the entire declaration.
+ *
+ * inactiveOpacity: ensure the resulting contrast ratio remains at least 4.5:1 against
+ * your background colour to meet WCAG AA. The default of 0.45 may fail this threshold
+ * depending on your foreground/background pairing.
+ */
+export declare interface SpeechTypeOptions {
+    /** Letter-spacing on the active (currently spoken) word in em. Default: 0.06 */
+    activeTracking?: number;
+    /**
+     * wght axis value on the active word. Default: 700.
+     * Must be within the font's supported wght axis range (e.g. 100–900 for most variable fonts).
+     */
+    activeWeight?: number;
+    /**
+     * opsz axis value on the active word. Default: 24.
+     * Must be within the font's supported opsz axis range (e.g. 6–72 for many variable fonts).
+     */
+    activeOpsz?: number;
+    /**
+     * Opacity of inactive (not currently spoken) words. Default: 0.45.
+     * Values below ~0.5 may reduce contrast below WCAG AA (4.5:1) depending on your colours.
+     * Minimum recommended value: 0.3.
+     */
+    inactiveOpacity?: number;
+    /** CSS transition duration in ms for style changes. Default: 80 */
+    transitionMs?: number;
+    /** Speech rate (0.1–10). Used only by startSpeechType. Default: 0.9 */
+    rate?: number;
+    /** Speech pitch (0–2). Used only by startSpeechType. Default: 1 */
+    pitch?: number;
+    /** Speech volume (0–1). Used only by startSpeechType. Default: 1 */
+    volume?: number;
+    /**
+     * Called when speech synthesis is unavailable in the current browser.
+     * Used only by startSpeechType.
+     */
+    /**
+     * Language of the speech (BCP 47, e.g. 'ja'). Default: the element's own `lang` (nearest ancestor),
+     * else the document's. A voice for that language is chosen when the browser has one.
+     */
+    lang?: string;
+    /** Voice to use: a SpeechSynthesisVoice, or a voice name / voiceURI. Default: the language's voice. */
+    voice?: SpeechSynthesisVoice | string;
+    /** Called when a run ends: speech finished, stopped, cancelled by a newer run, or failed (after onError). */
+    onEnd?: () => void;
+    onUnsupported?: () => void;
+    /**
+     * Called when a real speech error occurs (any error code other than "interrupted",
+     * which is a normal cancellation). Receives the SpeechSynthesisErrorEvent.
+     * Used only by startSpeechType.
+     */
+    onError?: (event: SpeechSynthesisErrorEvent) => void;
+}
+
+/**
+ * Speak el's text, emphasising each word as the Web Speech API reaches it. Calls prepareSpeechType
+ * first. Earlier speech started by speechType is stopped (other speech on the page is left alone unless
+ * this run has to take over the speech engine). Returns a stop() function that stops this run and resets
+ * the emphasis; the words stay wrapped until removeSpeechType.
+ *
+ * @param el      - Element to speak and highlight
+ * @param options - SpeechTypeOptions (merged with defaults)
+ */
+export declare function startSpeechType(el: HTMLElement, options?: SpeechTypeOptions): () => void;
+
+export { }

package/dist/core.js

@@ -0,0 +1,196 @@
+const x = {
+  word: "st-word"
+}, b = /* @__PURE__ */ new Set(["SCRIPT", "STYLE", "TEXTAREA", "NOSCRIPT", "TEMPLATE", "SVG", "MATH", "SELECT", "OPTION", "CANVAS", "IFRAME", "OBJECT", "VIDEO", "AUDIO", "INPUT", "BUTTON"]), R = /* @__PURE__ */ new Set(["BR", "HR", "P", "DIV", "LI", "UL", "OL", "DL", "DT", "DD", "H1", "H2", "H3", "H4", "H5", "H6", "BLOCKQUOTE", "PRE", "SECTION", "ARTICLE", "ASIDE", "HEADER", "FOOTER", "NAV", "FIGURE", "FIGCAPTION", "TABLE", "TR", "TD", "TH", "CAPTION", "IMG", "ADDRESS", "MAIN", "DETAILS", "SUMMARY"]), k = /[฀-໿က-႟ក-៿぀-ヿ㐀-䶿一-鿿豈-﫿]/, U = 80, F = 1e4, V = 1e3, D = typeof Intl < "u" && "Segmenter" in Intl ? new Intl.Segmenter(void 0, { granularity: "word" }) : null, H = /* @__PURE__ */ new Set();
+function P(t) {
+  H.has(t) || (H.add(t), console.warn(t));
+}
+function y(t, e, r, n, s) {
+  return t === void 0 ? e : typeof t == "number" && Number.isFinite(t) ? Math.min(n, Math.max(r, t)) : (P(`[speechType] ${s} must be a finite number; got ${String(t)}, using ${e}`), e);
+}
+function _() {
+  var t, e;
+  return typeof window < "u" && !!((e = (t = window.matchMedia) == null ? void 0 : t.call(window, "(prefers-reduced-motion: reduce)")) != null && e.matches);
+}
+const A = /* @__PURE__ */ new WeakMap();
+function z(t) {
+  if (t.getAttribute("aria-hidden") === "true" || t.hasAttribute("hidden")) return !0;
+  if (!t.isConnected) return !1;
+  const e = getComputedStyle(t);
+  return e.display === "none" || e.visibility === "hidden";
+}
+function $(t) {
+  for (const e of t.wrapped) {
+    const r = e.produced.find((n) => n.parentNode);
+    r != null && r.parentNode && r.parentNode.insertBefore(e.original, r), e.produced.forEach((n) => {
+      var s;
+      return (s = n.parentNode) == null ? void 0 : s.removeChild(n);
+    });
+  }
+}
+function B(t, e = {}) {
+  var T;
+  if (typeof window > "u" || !t) return [];
+  const r = A.get(t);
+  r && ((T = r.run) == null || T.stop(), $(r), A.delete(t));
+  const n = t.innerHTML, s = [], o = [], u = [], i = [];
+  let a = "", p = -1, g = !0;
+  const h = (c) => {
+    Array.from(c.childNodes).forEach((f) => {
+      if (f.nodeType === Node.TEXT_NODE) {
+        I(f);
+        return;
+      }
+      if (f.nodeType !== Node.ELEMENT_NODE) return;
+      const d = f, l = d.nodeName.toUpperCase();
+      R.has(l) && (g = !0), !(b.has(l) || d.isContentEditable || z(d)) && (h(d), R.has(l) && (g = !0));
+    });
+  }, I = (c) => {
+    const f = c.data;
+    if (!f || !c.parentNode) return;
+    if (!/\S/.test(f)) {
+      g = !0;
+      return;
+    }
+    const d = [];
+    for (const w of f.split(/(\s+)/)) {
+      if (!w) continue;
+      if (/^\s+$/.test(w)) {
+        d.push(document.createTextNode(w)), g = !0;
+        continue;
+      }
+      (D && k.test(w) ? Array.from(D.segment(w), (C) => C.segment) : [w]).forEach((C, m) => {
+        (g || m > 0) && (a && (a += " "), p++, i[p] = a.length), g = !1;
+        const E = document.createElement("span");
+        E.className = x.word, E.textContent = C, d.push(E), o.push(E), u.push(p), a += C;
+      });
+    }
+    const l = document.createDocumentFragment();
+    d.forEach((w) => l.appendChild(w)), c.parentNode.replaceChild(l, c), s.push({ original: c, produced: d });
+  };
+  h(t);
+  const S = y(e.transitionMs, 80, 0, 1e4, "transitionMs");
+  return S > 0 && !_() && o.forEach((c) => {
+    c.style.transition = `font-variation-settings ${S}ms ease, letter-spacing ${S}ms ease, opacity ${S}ms ease`;
+  }), A.set(t, { originalHTML: n, wrapped: s, wordSpans: o, wordOf: u, text: a, wordStart: i, run: null, activeIndex: -1 }), o;
+}
+function G(t) {
+  if (!t || t === "normal") return [];
+  const e = [];
+  for (const r of t.matchAll(/["']([^"']{4})["']\s+(-?[\d.]+(?:e[+-]?\d+)?)/gi)) e.push([r[1], parseFloat(r[2])]);
+  return e;
+}
+function W(t, e) {
+  var T;
+  const r = t.parentElement ?? t, n = getComputedStyle(r), s = G(((T = n.getPropertyValue) == null ? void 0 : T.call(n, "font-variation-settings")) || n.fontVariationSettings || ""), o = (c) => {
+    var f;
+    return (f = s.find(([d]) => d === c)) == null ? void 0 : f[1];
+  }, u = parseFloat(n.fontSize) || 16, i = o("wght") ?? (parseFloat(n.fontWeight) || 400), a = o("opsz") ?? u, p = y(e.activeWeight, Math.min(1e3, i + 300), 1, 1e3, "activeWeight"), g = y(e.activeOpsz, a * 1.5, 1, 1e3, "activeOpsz"), h = y(e.activeTracking, 0.06, -1, 1, "activeTracking"), I = s.filter(([c]) => c !== "wght" && c !== "opsz").map(([c, f]) => `"${c}" ${f}`), S = parseFloat(n.letterSpacing) || 0;
+  return {
+    fvs: [...I, `"wght" ${+p.toFixed(1)}`, `"opsz" ${+g.toFixed(1)}`].join(", "),
+    // Added to the text's own letter-spacing.
+    ls: S ? `calc(${S}px + ${h}em)` : `${h}em`
+  };
+}
+function v(t, e, r = {}) {
+  if (typeof window > "u") return;
+  const n = A.get(t);
+  if (!n) return;
+  const s = Number.isInteger(e) && e >= 0 && e < n.wordSpans.length ? e : -1, o = y(r.inactiveOpacity, 0.45, 0, 1, "inactiveOpacity"), u = s >= 0 ? n.wordOf[s] : -1;
+  n.activeIndex = s, n.wordSpans.forEach((i, a) => {
+    if (u >= 0 && n.wordOf[a] === u) {
+      const p = W(i, r);
+      i.setAttribute("aria-current", "true"), i.style.fontVariationSettings = p.fvs, i.style.letterSpacing = p.ls, i.style.opacity = "1";
+    } else
+      i.removeAttribute("aria-current"), i.style.fontVariationSettings = "", i.style.letterSpacing = "", i.style.opacity = u === -1 ? "1" : String(o);
+  });
+}
+let N = null;
+function K(t, e) {
+  var s, o;
+  const r = ((o = (s = window.speechSynthesis).getVoices) == null ? void 0 : o.call(s)) ?? [];
+  if (e && typeof e == "object") return e;
+  if (typeof e == "string") {
+    const u = r.find((i) => i.name === e || i.voiceURI === e);
+    if (u) return u;
+    P(`[speechType] no voice named ${JSON.stringify(e)}; using the language's default`);
+  }
+  if (!t) return null;
+  const n = t.toLowerCase();
+  return r.find((u) => u.lang.toLowerCase() === n) ?? r.find((u) => u.lang.toLowerCase().split("-")[0] === n.split("-")[0]) ?? null;
+}
+function Y(t, e = {}) {
+  var M, C;
+  if (typeof window > "u" || !t || !("speechSynthesis" in window) || typeof SpeechSynthesisUtterance > "u")
+    return (M = e.onUnsupported) == null || M.call(e), () => {
+    };
+  const r = y(e.rate, 0.9, 0.1, 10, "rate"), n = y(e.pitch, 1, 0, 2, "pitch"), s = y(e.volume, 1, 0, 1, "volume"), o = window.speechSynthesis, u = o.speaking || o.pending;
+  B(t, e);
+  const i = A.get(t);
+  if (!i || !i.text) return () => {
+  };
+  const a = new SpeechSynthesisUtterance(i.text);
+  a.rate = r, a.pitch = n, a.volume = s;
+  const p = e.lang ?? ((C = t.closest("[lang]")) == null ? void 0 : C.lang) ?? document.documentElement.lang ?? "";
+  p && (a.lang = p);
+  const g = K(p, e.voice);
+  g && (a.voice = g);
+  let h = !1, I = !1, S = null, T = null, c = null, f = !1;
+  const d = () => {
+    var m;
+    h || (h = !0, S && clearInterval(S), T && clearInterval(T), c && clearTimeout(c), N === l && (N = null), i.run === l && (i.run = null), v(t, -1, e), (m = e.onEnd) == null || m.call(e));
+  };
+  a.onstart = () => {
+    f = !0;
+  }, a.onboundary = (m) => {
+    if (h || m.name !== "word") return;
+    f = !0;
+    let E = -1;
+    for (let O = 0; O < i.wordStart.length && i.wordStart[O] <= m.charIndex; O++)
+      E = O;
+    const L = i.wordOf.indexOf(E);
+    L !== -1 && v(t, L, e);
+  }, a.onend = () => d(), a.onerror = (m) => {
+    var E;
+    m.error !== "interrupted" && !(I && m.error === "canceled") && ((E = e.onError) == null || E.call(e, m)), d();
+  };
+  const l = {
+    utterance: a,
+    stop: () => {
+      h || (N === l && (I = !0, o.cancel()), d());
+    }
+  };
+  N ? N.stop() : u && o.cancel(), N = l, i.run = l;
+  const w = () => {
+    c = null, !h && (o.speak(a), /Chrome\//.test(navigator.userAgent) && (S = setInterval(() => {
+      o.speaking && !o.paused && (o.pause(), o.resume());
+    }, F)), T = setInterval(() => {
+      f && !o.speaking && !o.pending && d();
+    }, V));
+  };
+  return u ? c = setTimeout(w, U) : w(), l.stop;
+}
+function j(t) {
+  var r;
+  const e = A.get(t);
+  e && ((r = e.run) == null || r.stop(), v(t, -1), $(e), A.delete(t));
+}
+function q(t) {
+  const e = A.get(t);
+  if (e) return e.originalHTML;
+  const r = t.cloneNode(!0);
+  return r.querySelectorAll(`.${x.word}`).forEach((n) => {
+    const s = n.parentNode;
+    if (s) {
+      for (; n.firstChild; ) s.insertBefore(n.firstChild, n);
+      s.removeChild(n);
+    }
+  }), r.querySelectorAll("[data-st-live]").forEach((n) => n.remove()), r.normalize(), r.innerHTML;
+}
+export {
+  x as SPEECH_CLASSES,
+  v as applySpeechType,
+  q as getCleanHTML,
+  B as prepareSpeechType,
+  j as removeSpeechType,
+  Y as startSpeechType
+};

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("react"),b=require("react/jsx-runtime"),v={word:"st-word"},w=new WeakMap;function C(t,e={}){if(typeof window>"u")return[];const r=window.scrollY,n=w.get(t),l=(n==null?void 0:n.originalHTML)??t.innerHTML;t.innerHTML=l;const d=(t.textContent??"").split(/(\s+)/);t.innerHTML=d.map(i=>!i||/^\s+$/.test(i)?i:`<span class="${v.word}" aria-hidden="true">${i}</span>`).join("");const u=Array.from(t.querySelectorAll(`.${v.word}`)),o=e.transitionMs??80;u.forEach(i=>{i.style.display="inline",i.style.transition=[`font-variation-settings ${o}ms ease`,`letter-spacing ${o}ms ease`,`opacity ${o}ms ease`].join(", ")});let c=t.querySelector("[data-st-live]");return c||(c=document.createElement("span"),c.setAttribute("data-st-live",""),c.setAttribute("aria-live","polite"),c.setAttribute("aria-atomic","true"),c.style.cssText="position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0",t.appendChild(c)),w.set(t,{originalHTML:l,wordSpans:u,utterance:null,activeIndex:-1}),requestAnimationFrame(()=>{Math.abs(window.scrollY-r)>2&&window.scrollTo({top:r,behavior:"instant"})}),u}function y(t,e,r={}){var c;if(typeof window>"u")return;const n=w.get(t);if(!n)return;const l=r.activeTracking??.06,s=r.activeWeight??700,d=r.activeOpsz??24,u=r.inactiveOpacity??.45;n.activeIndex=e;const o=t.querySelector("[data-st-live]");o&&(o.textContent=e>=0?((c=n.wordSpans[e])==null?void 0:c.textContent)??"":""),n.wordSpans.forEach((i,S)=>{S===e?(i.setAttribute("aria-current","true"),i.style.fontVariationSettings=`"wght" ${s}, "opsz" ${d}`,i.style.letterSpacing=`${l}em`,i.style.opacity="1"):(i.removeAttribute("aria-current"),i.style.fontVariationSettings="",i.style.letterSpacing="",i.style.opacity=e===-1?"1":String(u))})}function L(t,e={}){var m;if(typeof window>"u"||!("speechSynthesis"in window))return(m=e.onUnsupported)==null||m.call(e),()=>{};const r=C(t,e),n=w.get(t);if(!n)return()=>{};window.speechSynthesis.cancel();const l=r.map(a=>a.textContent??"").join(" "),s=new SpeechSynthesisUtterance(l);s.rate=e.rate??.9,s.pitch=e.pitch??1,s.volume=e.volume??1;const d=e.activeTracking??.06,u=e.activeWeight??700,o=e.activeOpsz??24,c={...e,activeTracking:d,activeWeight:u,activeOpsz:o};let i=0;const S=r.map(a=>{var h;const p=i;return i+=(((h=a.textContent)==null?void 0:h.length)??0)+1,p});let f=!1;return s.onboundary=a=>{if(f||a.name!=="word")return;const p=S.findIndex((h,x)=>{const T=S[x+1]??1/0;return a.charIndex>=h&&a.charIndex<T});p!==-1&&y(t,p,c)},s.onend=()=>{f||(y(t,-1,c),n.utterance=null)},s.onerror=a=>{var p;a.error!=="interrupted"&&((p=e.onError)==null||p.call(e,a)),f||(y(t,-1,c),n.utterance=null)},n.utterance=s,window.speechSynthesis.speak(s),()=>{f||(f=!0,window.speechSynthesis.cancel(),y(t,-1,c),n.utterance=null)}}function M(t){const e=w.get(t);e&&(typeof window<"u"&&"speechSynthesis"in window&&window.speechSynthesis.cancel(),t.innerHTML=e.originalHTML,w.delete(t))}function A(t){const e=t.cloneNode(!0);return e.querySelectorAll(`.${v.word}`).forEach(r=>{const n=r.parentNode;if(n){for(;r.firstChild;)n.insertBefore(r.firstChild,r);n.removeChild(r)}}),e.innerHTML}function E(t,e,r){g.useEffect(()=>{const n=t.current;if(n)return C(n,r),()=>M(n)},[r==null?void 0:r.transitionMs]),g.useEffect(()=>{const n=t.current;n&&y(n,e,r)},[e])}const $=g.forwardRef(function({activeWordIndex:e,as:r="p",children:n,style:l,className:s,activeTracking:d,activeWeight:u,activeOpsz:o,inactiveOpacity:c,transitionMs:i,rate:S,pitch:f,volume:m,onUnsupported:a,onError:p,...h},x){const T=g.useRef(null);g.useImperativeHandle(x,()=>T.current),E(T,e,{activeTracking:d,activeWeight:u,activeOpsz:o,inactiveOpacity:c,transitionMs:i});const H=r;return b.jsx(H,{ref:T,style:l,className:s,...h,children:n})});exports.SPEECH_CLASSES=v;exports.SpeechTypeText=$;exports.applySpeechType=y;exports.getCleanHTML=A;exports.prepareSpeechType=C;exports.removeSpeechType=M;exports.startSpeechType=L;exports.useSpeechType=E;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("./core.cjs"),y=require("react"),H=require("react/jsx-runtime");function T(s,u,e){const c=y.useRef(null),r=y.useRef(e);r.current=e;const f=JSON.stringify([e==null?void 0:e.activeTracking,e==null?void 0:e.activeWeight,e==null?void 0:e.activeOpsz,e==null?void 0:e.inactiveOpacity]);y.useEffect(()=>{const t=s.current,p=c.current;if(!p||p.el!==t||p.transitionMs!==(e==null?void 0:e.transitionMs)){if(p&&p.el!==t&&n.removeSpeechType(p.el),c.current=null,!t)return;n.prepareSpeechType(t,r.current),c.current={el:t,transitionMs:e==null?void 0:e.transitionMs},n.applySpeechType(t,u,r.current)}}),y.useEffect(()=>{const t=s.current;t&&n.applySpeechType(t,u,r.current)},[u,f]),y.useEffect(()=>()=>{c.current&&n.removeSpeechType(c.current.el),c.current=null},[])}function O(s){const u=[],e=c=>{y.Children.forEach(c,r=>{if(!(r==null||typeof r=="boolean")){if(typeof r=="string"||typeof r=="number"){u.push(String(r));return}if(y.isValidElement(r)){const f=typeof r.type=="string"?r.type:r.type.displayName??r.type.name??"C",t=r.props,p=Object.keys(t).filter(a=>a!=="children"&&["string","number","boolean"].includes(typeof t[a])).sort().map(a=>`${a}=${String(t[a])}`);u.push(`<${f}${r.key!=null?"#"+r.key:""} ${p.join(" ")}>`),e(t.children),u.push(`</${f}>`)}}})};return e(s),u.join("\0")}const L=y.forwardRef(function({activeWordIndex:u,as:e="p",children:c,style:r,className:f,activeTracking:t,activeWeight:p,activeOpsz:a,inactiveOpacity:i,transitionMs:h,rate:m,pitch:E,volume:g,onUnsupported:v,onError:C,onEnd:$,lang:l,voice:b,...M},R){const S=y.useRef(null);y.useImperativeHandle(R,()=>S.current),T(S,u,{activeTracking:t,activeWeight:p,activeOpsz:a,inactiveOpacity:i,transitionMs:h,rate:m,pitch:E,volume:g,onUnsupported:v,onError:C,onEnd:$,lang:l,voice:b});const j=e;return H.jsx(j,{ref:S,style:r,className:f,lang:l,...M,children:c},`${typeof e=="string"?e:"C"}|${O(c)}`)});exports.SPEECH_CLASSES=n.SPEECH_CLASSES;exports.applySpeechType=n.applySpeechType;exports.getCleanHTML=n.getCleanHTML;exports.prepareSpeechType=n.prepareSpeechType;exports.removeSpeechType=n.removeSpeechType;exports.startSpeechType=n.startSpeechType;exports.SpeechTypeText=L;exports.useSpeechType=T;

package/dist/index.d.ts

@@ -1,41 +1,42 @@
+import { default as default_2 } from 'react';
 import { ElementType } from 'react';
-import { ForwardRefExoticComponent } from 'react';
-import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 
 /**
- * Apply typographic emphasis to the word at activeIndex.
- * All other words receive the inactive style. Pass -1 to reset all words to neutral.
+ * Emphasise the word containing the span at activeIndex (every span of a word split by markup); dim the
+ * others. Pass -1 to reset all words to neutral. The emphasis is a heavier weight, larger optical size and
+ * wider tracking around the text's own values (explicit options are absolute).
  *
  * @param el          - Element previously prepared by prepareSpeechType
- * @param activeIndex - Index of the word to emphasise, -1 for none
+ * @param activeIndex - Index of the word span to emphasise, -1 for none
  * @param options     - SpeechTypeOptions (merged with defaults)
  */
 export declare function applySpeechType(el: HTMLElement, activeIndex: number, options?: SpeechTypeOptions): void;
 
 /**
- * Return a clean copy of el's innerHTML with all speechType spans unwrapped.
- * Does not modify el itself.
+ * The element's markup without speechType's word spans. Exact for a prepared element; for any other
+ * element, unwraps .st-word spans.
  *
  * @param el - Element to read clean HTML from
  */
 export declare function getCleanHTML(el: HTMLElement): string;
 
-declare type HTMLForwardProps = Omit<React.HTMLAttributes<HTMLElement>, keyof SpeechTypeOptions | 'children' | 'style' | 'className'>;
+declare type HTMLForwardProps = Omit<default_2.HTMLAttributes<HTMLElement>, keyof SpeechTypeOptions | 'children' | 'style' | 'className'>;
 
 /**
- * Wrap the text content of el in per-word <span> elements with the SPEECH_CLASSES.word
- * class. Saves the original innerHTML for cleanup. Idempotent — calling again re-wraps
- * from the saved original. Returns the array of word span elements.
+ * Wrap each visible word of el in a <span class="st-word">, in place: the element's markup, ids,
+ * listeners, form values and line breaks are kept, and hidden text, styles, scripts, form fields and SVG
+ * are left alone (and not spoken). The text stays readable to screen readers. Idempotent — calling again
+ * re-wraps from the original. Returns the word spans in document order.
  *
  * @param el      - Element whose text will be wrapped
- * @param options - SpeechTypeOptions (merged with defaults)
+ * @param options - SpeechTypeOptions (transitionMs is used)
  */
 export declare function prepareSpeechType(el: HTMLElement, options?: SpeechTypeOptions): HTMLElement[];
 
 /**
- * Remove speechType from el — cancel any active speech, restore original innerHTML,
- * and delete all saved state. No-op if prepareSpeechType was never called.
+ * Stop this element's speech (only if it is speaking), put the original text nodes back and delete the
+ * saved state. No-op if prepareSpeechType was never called.
  *
  * @param el - The element previously prepared by prepareSpeechType
  */
@@ -99,6 +100,15 @@ export declare interface SpeechTypeOptions {
      * Called when speech synthesis is unavailable in the current browser.
      * Used only by startSpeechType.
      */
+    /**
+     * Language of the speech (BCP 47, e.g. 'ja'). Default: the element's own `lang` (nearest ancestor),
+     * else the document's. A voice for that language is chosen when the browser has one.
+     */
+    lang?: string;
+    /** Voice to use: a SpeechSynthesisVoice, or a voice name / voiceURI. Default: the language's voice. */
+    voice?: SpeechSynthesisVoice | string;
+    /** Called when a run ends: speech finished, stopped, cancelled by a newer run, or failed (after onError). */
+    onEnd?: () => void;
     onUnsupported?: () => void;
     /**
      * Called when a real speech error occurs (any error code other than "interrupted",
@@ -114,7 +124,7 @@ export declare interface SpeechTypeOptions {
  * Forwards a ref to the underlying DOM element for imperative startSpeechType access.
  * All aria-*, data-*, role, lang, and other HTML attributes are forwarded to the DOM element.
  */
-export declare const SpeechTypeText: ForwardRefExoticComponent<SpeechTypeTextProps & RefAttributes<HTMLElement>>;
+export declare const SpeechTypeText: default_2.ForwardRefExoticComponent<SpeechTypeTextProps & default_2.RefAttributes<HTMLElement>>;
 
 /** Props accepted by SpeechTypeText */
 declare interface SpeechTypeTextProps extends SpeechTypeOptions, HTMLForwardProps {
@@ -123,17 +133,18 @@ declare interface SpeechTypeTextProps extends SpeechTypeOptions, HTMLForwardProp
     /** HTML element tag to render. Default: 'p' */
     as?: ElementType;
     /** React children (text content to highlight) */
-    children: React.ReactNode;
+    children: default_2.ReactNode;
     /** Inline styles forwarded to the rendered element */
-    style?: React.CSSProperties;
+    style?: default_2.CSSProperties;
     /** Class name forwarded to the rendered element */
     className?: string;
 }
 
 /**
- * Start speech synthesis on el's text content, syncing word emphasis to Web Speech API
- * boundary events. Calls prepareSpeechType first. Cancels any existing speech.
- * Returns a stop() function that cancels speech and resets all styles.
+ * Speak el's text, emphasising each word as the Web Speech API reaches it. Calls prepareSpeechType
+ * first. Earlier speech started by speechType is stopped (other speech on the page is left alone unless
+ * this run has to take over the speech engine). Returns a stop() function that stops this run and resets
+ * the emphasis; the words stay wrapped until removeSpeechType.
  *
  * @param el      - Element to speak and highlight
  * @param options - SpeechTypeOptions (merged with defaults)
@@ -141,11 +152,11 @@ declare interface SpeechTypeTextProps extends SpeechTypeOptions, HTMLForwardProp
 export declare function startSpeechType(el: HTMLElement, options?: SpeechTypeOptions): () => void;
 
 /**
- * Prepare word spans on mount and apply emphasis when activeWordIndex changes.
- * Cleans up by restoring original innerHTML on unmount.
+ * Prepare word spans on mount (and again when the element or transitionMs changes) and apply emphasis for
+ * activeWordIndex. Restores the element on unmount; speech is only cancelled if this element is speaking.
  *
  * @param ref             - Ref to the element containing text to highlight
- * @param activeWordIndex - Index of the currently active word (-1 = none)
+ * @param activeWordIndex - Index of the currently active word span (-1 = none)
  * @param options         - SpeechTypeOptions (merged with defaults)
  */
 export declare function useSpeechType(ref: RefObject<HTMLElement | null>, activeWordIndex: number, options?: SpeechTypeOptions): void;