Remove Children.map usage and implement alternative approach

Co-authored-by: morganney <848178+morganney@users.noreply.github.com>

Author: Copilot

packages/tts-react/__tests__/hook.tsx

@@ -321,4 +321,60 @@ describe('useTts', () => {
     global.dispatchEvent(new Event('beforeunload'))
     expect(global.speechSynthesis.cancel).toHaveBeenCalled()
   })
+
+  it('accepts text prop as an alternative to children', async () => {
+    const testText = 'This is direct text for TTS'
+    const { result } = renderHook(
+      ({ text }) => useTts({ text }),
+      {
+        initialProps: {
+          text: testText
+        }
+      }
+    )
+
+    expect(result.current.spokenText).toBe(testText)
+    expect(result.current.ttsChildren).toBe(testText)
+  })
+
+  it('prefers text prop over children when both are provided', async () => {
+    const testText = 'Direct text prop'
+    const childrenText = 'Children text'
+    const { result } = renderHook(
+      ({ text, children }) => useTts({ text, children }),
+      {
+        initialProps: {
+          text: testText,
+          children: <p>{childrenText}</p>
+        }
+      }
+    )
+
+    expect(result.current.spokenText).toBe(testText)
+  })
+
+  it('supports render prop for custom highlighting', async () => {
+    const testText = 'Test text for highlighting'
+    const mockRender = jest.fn((params) => params.children)
+    
+    const { result } = renderHook(
+      ({ text, render, markTextAsSpoken }) => useTts({ text, render, markTextAsSpoken }),
+      {
+        initialProps: {
+          text: testText,
+          render: mockRender,
+          markTextAsSpoken: true
+        }
+      }
+    )
+
+    expect(result.current.spokenText).toBe(testText)
+    expect(mockRender).toHaveBeenCalledWith({
+      children: testText,
+      boundary: expect.any(Object),
+      markTextAsSpoken: true,
+      markColor: undefined,
+      markBackgroundColor: undefined
+    })
+  })
 })

packages/tts-react/__tests__/utils.ts

@@ -1,9 +1,49 @@
-import { describe } from '@jest/globals'
+import { describe, test } from '@jest/globals'
+import { createElement } from 'react'
 
-import { isPunctuation } from '../src/utils.js'
+import { isPunctuation, extractTextFromChildren } from '../src/utils.js'
 
 describe('utils', () => {
   it('has isPunctuation', () => {
     expect(isPunctuation('?')).toBe(true)
   })
+
+  describe('extractTextFromChildren', () => {
+    test('extracts text from string children', () => {
+      expect(extractTextFromChildren('hello world')).toBe('hello world')
+    })
+
+    test('extracts text from number children', () => {
+      expect(extractTextFromChildren(42)).toBe('42')
+    })
+
+    test('extracts text from array of children', () => {
+      expect(extractTextFromChildren(['hello', ' ', 'world'])).toBe('hello   world')
+    })
+
+    test('extracts text from React elements', () => {
+      const element = createElement('p', {}, 'Hello from element')
+      expect(extractTextFromChildren(element)).toBe('Hello from element')
+    })
+
+    test('extracts text from nested React elements', () => {
+      const nested = createElement('span', {}, 'nested text')
+      const element = createElement('p', {}, 'Hello ', nested, ' world')
+      expect(extractTextFromChildren(element)).toBe('Hello  nested text  world')
+    })
+
+    test('handles null and undefined children', () => {
+      expect(extractTextFromChildren(null)).toBe('')
+      expect(extractTextFromChildren(undefined)).toBe('')
+    })
+
+    test('handles boolean children', () => {
+      expect(extractTextFromChildren(true)).toBe('')
+      expect(extractTextFromChildren(false)).toBe('')
+    })
+
+    test('handles empty array', () => {
+      expect(extractTextFromChildren([])).toBe('')
+    })
+  })
 })

packages/tts-react/src/hook.tsx

@@ -4,17 +4,14 @@ import {
   useReducer,
   useCallback,
   useEffect,
-  Children,
-  cloneElement,
   createElement,
-  isValidElement,
   Fragment
 } from 'react'
 import type { ReactNode } from 'react'
 
 import { Controller, ControllerStub, Events } from './controller.js'
 import type { ControllerOptions, TTSBoundaryUpdate, TTSEvent } from './controller.js'
-import { isStringOrNumber, stripPunctuation, noop } from './utils.js'
+import { stripPunctuation, noop, extractTextFromChildren } from './utils.js'
 import { Highlighter } from './highlighter.js'
 
 /**
@@ -78,9 +75,24 @@ interface MarkStyles {
   /** Background color of the currently marked word. */
   markBackgroundColor?: string
 }
+/**
+ * Render prop function type for custom text highlighting
+ */
+type TTSRenderProp = (params: {
+  children: ReactNode
+  boundary: TTSBoundaryUpdate
+  markTextAsSpoken: boolean
+  markColor?: string
+  markBackgroundColor?: string
+}) => ReactNode
+
 interface TTSHookProps extends MarkStyles {
   /** The spoken text is extracted from here. */
-  children: ReactNode
+  children?: ReactNode
+  /** Direct text to be spoken - alternative to children. */
+  text?: string
+  /** Render prop for custom highlighting - receives highlighting parameters */
+  render?: TTSRenderProp
   /** The `SpeechSynthesisUtterance.lang` to use. */
   lang?: ControllerOptions['lang']
   /** The `SpeechSynthesisUtterance.voice` to use. */
@@ -175,82 +187,61 @@ interface TTSHookResponse {
   /** The original children with a possible <mark> included if using `markTextAsSpoken`. */
   ttsChildren: ReactNode
 }
-interface TextBuffer {
-  text: string
-}
-interface ParseChildrenProps extends MarkStyles {
-  children: ReactNode
-  buffer: TextBuffer
-  boundary: TTSBoundaryUpdate
-  markTextAsSpoken: boolean
-}
+/**
+ * Creates highlighted text using render prop pattern instead of Children.map
+ */
+const createHighlightedContent = (
+  children: ReactNode,
+  text: string,
+  boundary: TTSBoundaryUpdate,
+  markTextAsSpoken: boolean,
+  markColor?: string,
+  markBackgroundColor?: string,
+  renderProp?: TTSRenderProp
+): ReactNode => {
+  // If a render prop is provided, use it
+  if (renderProp) {
+    return renderProp({
+      children,
+      boundary,
+      markTextAsSpoken,
+      markColor,
+      markBackgroundColor
+    })
+  }
 
-const isObjectReactNode = (value: unknown): value is Record<string, ReactNode> =>
-  typeof value === 'object' && value !== null
-const parseChildrenRecursively = ({
-  children,
-  buffer,
-  boundary,
-  markColor,
-  markBackgroundColor,
-  markTextAsSpoken
-}: ParseChildrenProps): ReactNode => {
-  return Children.map(children, (child) => {
-    let currentChild = child
-
-    if (isValidElement(child)) {
-      const childProps = isObjectReactNode(child.props) ? child.props : {}
-
-      currentChild = cloneElement(child, {
-        ...childProps,
-        // @ts-expect-error - `children` is not a valid prop for ReactElement
-        children: parseChildrenRecursively({
-          buffer,
-          boundary,
-          markColor,
-          markBackgroundColor,
-          markTextAsSpoken,
-          children: childProps.children
-        })
-      })
-    }
+  // If not marking text as spoken or no boundary word, return original children
+  if (!markTextAsSpoken || !boundary.word || !children) {
+    return children
+  }
 
-    if (isStringOrNumber(child)) {
-      const text = (child as string | number).toString()
-      const { word, startChar, endChar } = boundary
-      const bufferTextLength = buffer.text.length
-
-      buffer.text += `${text} `
-
-      if (markTextAsSpoken && word) {
-        const start = startChar - bufferTextLength
-        const end = endChar - bufferTextLength
-        const prev = text.substring(0, start)
-        const found = text.substring(start, end)
-        const after = text.substring(end, text.length)
-
-        if (found) {
-          const Highlight = createElement(Highlighter, {
-            text: found,
-            mark: stripPunctuation(found),
-            color: markColor,
-            backgroundColor: markBackgroundColor
-          })
-          const Highlighted = createElement(
-            Fragment,
-            { key: `tts-${start}-${end}` },
-            prev,
-            Highlight,
-            after
-          )
-
-          return Highlighted
-        }
-      }
+  // For simple text content, apply highlighting directly
+  if (typeof children === 'string') {
+    const { word, startChar, endChar } = boundary
+    const prev = text.substring(0, startChar)
+    const found = text.substring(startChar, endChar)
+    const after = text.substring(endChar)
+
+    if (found && stripPunctuation(found) === stripPunctuation(word)) {
+      const Highlight = createElement(Highlighter, {
+        text: found,
+        mark: stripPunctuation(found),
+        color: markColor,
+        backgroundColor: markBackgroundColor
+      })
+      
+      return createElement(
+        Fragment,
+        { key: `tts-${startChar}-${endChar}` },
+        prev,
+        Highlight,
+        after
+      )
     }
+  }
 
-    return currentChild
-  })
+  // For complex content, return as-is (highlighting would need custom render prop)
+  return children
 }
 const defaultBoundary = { word: '', startChar: 0, endChar: 0 }
 const reducer = (state: TTSHookState, action: Action): TTSHookState => {
@@ -305,6 +296,8 @@ const useTts = ({
   volume,
   voice,
   children,
+  text,
+  render,
   markColor,
   markBackgroundColor,
   onStart,
@@ -334,20 +327,24 @@ const useTts = ({
     isReady: isSynthSupported && typeof fetchAudioData === 'undefined'
   })
   const [ttsChildren, spokenText] = useMemo(() => {
-    const buffer: TextBuffer = { text: '' }
-    const parsed = parseChildrenRecursively({
-      children,
-      buffer,
+    // Use text prop if provided, otherwise extract from children
+    const extractedText = text || (children ? extractTextFromChildren(children) : '')
+    
+    // Create highlighted content using the new approach
+    const highlightedContent = createHighlightedContent(
+      children || extractedText,
+      extractedText,
+      state.boundary,
+      markTextAsSpoken,
       markColor,
       markBackgroundColor,
-      markTextAsSpoken,
-      boundary: state.boundary
-    })
+      render
+    )
 
-    spokenTextRef.current = buffer.text.trim()
+    spokenTextRef.current = extractedText.trim()
 
-    return [parsed, spokenTextRef.current]
-  }, [children, state.boundary, markColor, markBackgroundColor, markTextAsSpoken])
+    return [highlightedContent, spokenTextRef.current]
+  }, [children, text, state.boundary, markColor, markBackgroundColor, markTextAsSpoken, render])
   const controller = useMemo(
     () =>
       isSynthSupported
@@ -674,5 +671,6 @@ export type {
   TTSEventHandler,
   TTSErrorHandler,
   TTSBoundaryHandler,
-  TTSAudioChangeHandler
+  TTSAudioChangeHandler,
+  TTSRenderProp
 }

packages/tts-react/src/utils.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react'
+import { isValidElement } from 'react'
 
 const punctuationRgx = /[^\P{P}'/-]+/gu
 const isStringOrNumber = (value: ReactNode): boolean => {
@@ -14,4 +15,33 @@ const isPunctuation = (text: string): boolean => {
 }
 const noop = (): void => {}
 
-export { isStringOrNumber, stripPunctuation, isPunctuation, noop, punctuationRgx }
+/**
+ * Extracts text content from React children without using Children.map
+ * This is an alternative to the legacy Children.map API
+ */
+const extractTextFromChildren = (children: ReactNode): string => {
+  if (!children) {
+    return ''
+  }
+
+  // Handle string and number primitives
+  if (typeof children === 'string' || typeof children === 'number') {
+    return children.toString()
+  }
+
+  // Handle arrays of children
+  if (Array.isArray(children)) {
+    return children.map((child: ReactNode) => extractTextFromChildren(child)).join(' ')
+  }
+
+  // Handle React elements
+  if (isValidElement(children) && children.props && 'children' in children.props) {
+    // For React elements, recursively extract text from their children
+    return extractTextFromChildren(children.props.children as ReactNode)
+  }
+
+  // Handle other types (null, undefined, boolean, etc.)
+  return ''
+}
+
+export { isStringOrNumber, stripPunctuation, isPunctuation, noop, punctuationRgx, extractTextFromChildren }