@lightningtv/solid 3.0.0-0 → 3.0.0-10

package/src/primitives/announcer/announcer.ts

@@ -73,8 +73,9 @@ function onFocusChangeCore(focusPath: ElementNode[] = []) {
   prevFocusPath = focusPath.slice(0);
 
   const toAnnounceText: SpeechType[] = [];
-  const toAnnounce = focusDiff.reduce(
-    (acc: [string, string, SpeechType][], elm) => {
+  const toAnnounce = focusDiff
+    .reverse()
+    .reduce((acc: [string, string, SpeechType][], elm) => {
       if (elm.announce) {
         acc.push([getElmName(elm), 'Announce', elm.announce]);
         toAnnounceText.push(elm.announce);
@@ -85,9 +86,7 @@ function onFocusChangeCore(focusPath: ElementNode[] = []) {
         acc.push([getElmName(elm), 'No Announce', '']);
       }
       return acc;
-    },
-    [],
-  );
+    }, []);
 
   focusDiff.reverse().reduce((acc, elm) => {
     if (elm.announceContext) {
@@ -110,18 +109,19 @@ function onFocusChangeCore(focusPath: ElementNode[] = []) {
   }
 }
 
-function textToSpeech(toSpeak: SpeechType, lang: string) {
+function textToSpeech(toSpeak: SpeechType, lang: string, voice?: string) {
   if (voiceOutDisabled) {
     return;
   }
 
-  return (currentlySpeaking = SpeechEngine(toSpeak, lang));
+  return (currentlySpeaking = SpeechEngine(toSpeak, lang, voice));
 }
 
 export interface Announcer {
   debug: boolean;
   enabled: boolean;
   lang: string;
+  voice?: string;
   cancel: VoidFunction;
   clearPrevFocus: (depth?: number) => void;
   speak: (
@@ -147,14 +147,13 @@ export const Announcer: Announcer = {
     prevFocusPath = prevFocusPath.slice(0, depth);
     resetFocusPathTimer();
   },
-  speak: function (text, { append = false, notification = false} = {}) {
+  speak: function (text, { append = false, notification = false } = {}) {
     if (Announcer.onFocusChange && Announcer.enabled) {
-      Announcer.onFocusChange.flush();
       if (append && currentlySpeaking && currentlySpeaking.active) {
         currentlySpeaking.append(text);
       } else {
         Announcer.cancel();
-        textToSpeech(text, Announcer.lang);
+        textToSpeech(text, Announcer.lang, Announcer.voice);
       }
 
       if (notification) {

package/src/primitives/announcer/index.ts

@@ -2,9 +2,19 @@ import { createEffect, on } from 'solid-js';
 import { Announcer } from './announcer.js';
 import { focusPath } from '../useFocusManager.js';
 
-export const useAnnouncer = () => {
-  Announcer.setupTimers();
+let doOnce = false;
+export const useAnnouncer = (options?: {
+  focusDebounce?: number;
+  focusChangeTimeout?: number;
+}) => {
+  if (doOnce) {
+    return Announcer;
+  }
+  doOnce = true;
+  Announcer.setupTimers(options);
   createEffect(on(focusPath, Announcer.onFocusChange!, { defer: true }));
 
   return Announcer;
 };
+
+export { Announcer };

package/src/primitives/announcer/speech.ts

@@ -1,4 +1,8 @@
-type CoreSpeechType = string | (() => SpeechType) | SpeechType[];
+type CoreSpeechType =
+  | string
+  | (() => SpeechType)
+  | SpeechType[]
+  | SpeechSynthesisUtterance;
 export type SpeechType = CoreSpeechType | Promise<CoreSpeechType>;
 
 export interface SeriesResult {
@@ -48,11 +52,23 @@ function speak(
   phrase: string,
   utterances: SpeechSynthesisUtterance[],
   lang = 'en-US',
+  voiceName?: string,
 ) {
   const synth = window.speechSynthesis;
+
   return new Promise<void>((resolve, reject) => {
+    let selectedVoice;
+    if (voiceName) {
+      const availableVoices = synth.getVoices();
+      selectedVoice =
+        availableVoices.find((v) => v.name === voiceName) || availableVoices[0];
+    }
+
     const utterance = new SpeechSynthesisUtterance(phrase);
     utterance.lang = lang;
+    if (selectedVoice) {
+      utterance.voice = selectedVoice;
+    }
     utterance.onend = () => {
       resolve();
     };
@@ -67,6 +83,7 @@ function speak(
 function speakSeries(
   series: SpeechType,
   lang: string,
+  voice?: string,
   root = true,
 ): SeriesResult {
   const synth = window.speechSynthesis;
@@ -74,11 +91,6 @@ function speakSeries(
     Array.isArray(series) ? series : [series],
   );
   const nestedSeriesResults: SeriesResult[] = [];
-  /*
-    We hold this array of SpeechSynthesisUtterances in order to prevent them from being
-    garbage collected prematurely on STB hardware which can cause the 'onend' events of
-    utterances to not fire consistently.
-  */
   const utterances: SpeechSynthesisUtterance[] = [];
   let active: boolean = true;
 
@@ -87,24 +99,61 @@ function speakSeries(
       while (active && remainingPhrases.length) {
         const phrase = await Promise.resolve(remainingPhrases.shift());
         if (!active) {
-          // Exit
-          // Need to check this after the await in case it was cancelled in between
-          break;
-        } else if (typeof phrase === 'string' && phrase.includes('PAUSE-')) {
-          // Pause it
-          let pause = Number(phrase.split('PAUSE-')[1]) * 1000;
-          if (isNaN(pause)) {
-            pause = 0;
+          break; // Exit if canceled
+        }
+
+        if (typeof phrase === 'string' && phrase.includes('PAUSE-')) {
+          // Handle pauses
+          const pause = Number(phrase.split('PAUSE-')[1]) * 1000;
+          if (!isNaN(pause)) {
+            await delay(pause);
+          }
+        } else if (typeof phrase === 'string') {
+          if (!phrase) {
+            continue; // Skip empty strings
+          }
+          // Handle regular strings with retry logic
+          const totalRetries = 3;
+          let retriesLeft = totalRetries;
+
+          while (active && retriesLeft > 0) {
+            try {
+              await speak(phrase, utterances, lang, voice);
+              retriesLeft = 0; // Exit retry loop on success
+            } catch (e) {
+              if (e instanceof SpeechSynthesisErrorEvent) {
+                if (e.error === 'network') {
+                  retriesLeft--;
+                  console.warn(
+                    `Speech synthesis network error. Retries left: ${retriesLeft}`,
+                  );
+                  await delay(500 * (totalRetries - retriesLeft));
+                } else if (
+                  e.error === 'canceled' ||
+                  e.error === 'interrupted'
+                ) {
+                  // Cancel or interrupt error (ignore)
+                  retriesLeft = 0;
+                } else {
+                  throw new Error(`SpeechSynthesisErrorEvent: ${e.error}`);
+                }
+              } else {
+                throw e;
+              }
+            }
           }
-          await delay(pause);
-        } else if (typeof phrase === 'string' && phrase.length) {
-          // Speak it
+        } else if (phrase instanceof SpeechSynthesisUtterance) {
+          // Handle SpeechSynthesisUtterance objects with retry logic
           const totalRetries = 3;
           let retriesLeft = totalRetries;
+          const text = phrase.text;
+          const objectLang = phrase?.lang;
+          const objectVoice = phrase?.voice;
+
           while (active && retriesLeft > 0) {
             try {
-              await speak(phrase, utterances, lang);
-              retriesLeft = 0;
+              await speak(text, utterances, objectLang, objectVoice?.name);
+              retriesLeft = 0; // Exit retry loop on success
             } catch (e) {
               if (e instanceof SpeechSynthesisErrorEvent) {
                 if (e.error === 'network') {
@@ -128,12 +177,13 @@ function speakSeries(
             }
           }
         } else if (typeof phrase === 'function') {
-          const seriesResult = speakSeries(phrase(), lang, false);
+          // Handle functions
+          const seriesResult = speakSeries(phrase(), lang, voice, false);
           nestedSeriesResults.push(seriesResult);
           await seriesResult.series;
         } else if (Array.isArray(phrase)) {
-          // Speak it (recursively)
-          const seriesResult = speakSeries(phrase, lang, false);
+          // Handle nested arrays
+          const seriesResult = speakSeries(phrase, lang, voice, false);
           nestedSeriesResults.push(seriesResult);
           await seriesResult.series;
         }
@@ -142,6 +192,7 @@ function speakSeries(
       active = false;
     }
   })();
+
   return {
     series: seriesChain,
     get active() {
@@ -155,19 +206,22 @@ function speakSeries(
         return;
       }
       if (root) {
-        synth.cancel();
+        synth.cancel(); // Cancel all ongoing speech
       }
-      nestedSeriesResults.forEach((nestedSeriesResults) => {
-        nestedSeriesResults.cancel();
+      nestedSeriesResults.forEach((nestedSeriesResult) => {
+        nestedSeriesResult.cancel();
       });
       active = false;
     },
   };
 }
-
 let currentSeries: SeriesResult | undefined;
-export default function (toSpeak: SpeechType, lang: string = 'en-US') {
+export default function (
+  toSpeak: SpeechType,
+  lang: string = 'en-US',
+  voice?: string,
+) {
   currentSeries && currentSeries.cancel();
-  currentSeries = speakSeries(toSpeak, lang);
+  currentSeries = speakSeries(toSpeak, lang, voice);
   return currentSeries;
 }

package/src/primitives/index.ts

@@ -3,7 +3,6 @@ export * from './announcer/index.js';
 export * from './createInfiniteItems.js';
 export * from './useMouse.js';
 export * from './portal.jsx';
-export * from './LazyUp.jsx';
 export * from './Lazy.jsx';
 export * from './Visible.jsx';
 export * from './router.js';
@@ -11,9 +10,18 @@ export * from './Column.jsx';
 export * from './Row.jsx';
 export * from './Grid.jsx';
 export * from './FPSCounter.jsx';
+export * from './FadeInOut.jsx';
+export * from './Preserve.jsx';
+export * from './Suspense.jsx';
+export * from './Marquee.jsx';
 export * from './createFocusStack.jsx';
+export * from './useHold.js';
 export { withScrolling } from './utils/withScrolling.js';
-export { chainFunctions } from './utils/chainFunctions.js';
+export {
+  type AnyFunction,
+  chainFunctions,
+  chainRefs,
+} from './utils/chainFunctions.js';
 export { handleNavigation, onGridFocus } from './utils/handleNavigation.js';
 export { createSpriteMap, type SpriteDef } from './utils/createSpriteMap.js';
 

package/src/primitives/types.ts

@@ -1,5 +1,6 @@
 import type { ElementNode, NodeProps, NodeStyles } from '@lightningtv/solid';
 import type { KeyHandler } from '@lightningtv/core/focusManager';
+
 export type OnSelectedChanged = (
   this: NavigableElement,
   selectedIndex: number,
@@ -7,6 +8,7 @@ export type OnSelectedChanged = (
   active: ElementNode,
   lastSelectedIndex?: number,
 ) => void;
+
 export interface NavigableProps extends NodeProps {
   /** function to be called when the selected of the component changes */
   onSelectedChanged?: OnSelectedChanged;
@@ -40,6 +42,13 @@ export interface NavigableProps extends NodeProps {
    * Wrap the row so active goes back to the beginning of the row
    */
   wrap?: boolean;
+
+  /** function to be called when scrolled */
+  onScrolled?: (
+    elm: NavigableElement,
+    offset: number,
+    isInitial: boolean,
+  ) => void;
 }
 
 // @ts-expect-error animationSettings is not identical - weird

package/src/primitives/useHold.ts

@@ -0,0 +1,69 @@
+import { createMemo } from 'solid-js';
+
+export type UseHoldProps = {
+  onHold: () => void;
+  onEnter: () => void;
+  onRelease?: () => void;
+  holdThreshold?: number;
+  performOnEnterImmediately?: boolean;
+};
+
+/**
+ * @example
+ * const [holdRight, releaseRight] = useHold({
+ *   onHold: handleHoldRight,
+ *   onEnter: handleOnRight,
+ *   onRelease: handleReleaseHold,
+ *   holdThreshold: 200,
+ *   performOnEnterImmediately: true
+ * });
+ *
+ * <View
+ *   onRight={holdRight}
+ *   onRightRelease={releaseRight}
+ * />
+ *
+ * @param {UseHoldProps} props - The properties for configuring the hold behavior.
+ * @returns {[() => boolean, () => boolean]} A tuple containing `startHold` and `releaseHold` functions.
+ */
+
+export function useHold(props: UseHoldProps) {
+  const holdThreshold = createMemo(() => props.holdThreshold ?? 500);
+  const performOnEnterImmediately = createMemo(
+    () => props.performOnEnterImmediately ?? false,
+  );
+
+  let holdTimeout = -1;
+  let wasHeld = false;
+
+  const startHold = () => {
+    if (holdTimeout === -1) {
+      if (performOnEnterImmediately()) {
+        props.onEnter();
+      }
+      holdTimeout = setTimeout(() => {
+        wasHeld = true;
+        props.onHold();
+      }, holdThreshold()) as unknown as number;
+    }
+    return true;
+  };
+
+  const releaseHold = () => {
+    if (holdTimeout !== -1) {
+      clearTimeout(holdTimeout);
+      holdTimeout = -1;
+      if (!wasHeld) {
+        if (!performOnEnterImmediately()) props.onEnter();
+        return;
+      }
+      props.onRelease?.();
+      wasHeld = false;
+    }
+    return true;
+  };
+
+  return [startHold, releaseHold];
+}
+
+export default useHold;

package/src/primitives/utils/chainFunctions.ts

@@ -1,13 +1,29 @@
-type ChainableFunction = (...args: unknown[]) => unknown;
+import * as s from 'solid-js';
 
-export function chainFunctions(...args: ChainableFunction[]): ChainableFunction;
-export function chainFunctions<T>(...args: (ChainableFunction | T)[]): T;
+export type AnyFunction = (this: any, ...args: any[]) => any;
 
-// take an array of functions and if you return true from a function, it will stop the chain
-export function chainFunctions<T extends ChainableFunction>(
-  ...args: (ChainableFunction | T)[]
-) {
-  const onlyFunctions = args.filter((func) => typeof func === 'function');
+/**
+ * take an array of functions and if you return `true` from a function, it will stop the chain
+ * @param fns list of functions to chain together, can be `undefined`, `null`, or `false` to skip them
+ * @returns a function that will call each function in the list until one returns `true` or all functions are called.
+ * If no functions are provided, it will return `undefined`.
+ *
+ * @example
+ * ```tsx
+ * function Button (props: NodeProps) {
+ *   function onEnter (el: ElementNode) {...}
+ *   return <view onEnter={chainFunctions(props.onEnter, onEnter)} />
+ * }
+ * ```
+ */
+export function chainFunctions<T extends AnyFunction>(...fns: T[]): T;
+export function chainFunctions<T extends AnyFunction>(
+  ...fns: (T | undefined | null | false)[]
+): T | undefined;
+export function chainFunctions(
+  ...fns: (AnyFunction | undefined | null | false)[]
+): AnyFunction | undefined {
+  const onlyFunctions = fns.filter((func) => typeof func === 'function');
   if (onlyFunctions.length === 0) {
     return undefined;
   }
@@ -16,7 +32,7 @@ export function chainFunctions<T extends ChainableFunction>(
     return onlyFunctions[0];
   }
 
-  return function (this: unknown | T, ...innerArgs: unknown[]) {
+  return function (...innerArgs) {
     let result;
     for (const func of onlyFunctions) {
       result = func.apply(this, innerArgs);
@@ -27,3 +43,18 @@ export function chainFunctions<T extends ChainableFunction>(
     return result;
   };
 }
+
+/**
+ * Utility for chaining multiple `ref` assignments with `props.ref` forwarding.
+ * @param refs list of ref setters. Can be a `props.ref` prop for ref forwarding or a setter to a local variable (`el => ref = el`).
+ * @example
+ * ```tsx
+ * function Button (props: NodeProps) {
+ *    let localRef: ElementNode | undefined
+ *    return <view ref={chainRefs(props.ref, el => localRef = el)} />
+ * }
+ * ```
+ */
+export const chainRefs = chainFunctions as <T>(
+  ...refs: (s.Ref<T> | undefined)[]
+) => (el: T) => void;

package/src/primitives/utils/createSpriteMap.ts

@@ -1,4 +1,4 @@
-import { renderer, type TextureMap } from '@lightningtv/core';
+import { type TextureMap, renderer } from '@lightningtv/core';
 
 export interface SpriteDef {
   name: string | number;
@@ -26,7 +26,7 @@ export function createSpriteMap(
       y,
       width,
       height,
-    });
+    }) as InstanceType<TextureMap['SubTexture']>;
     return acc;
   }, {});
 }

package/src/primitives/utils/handleNavigation.ts

@@ -6,6 +6,15 @@ export function onGridFocus(onSelectedChanged: OnSelectedChanged | undefined) {
   return function (this: ElementNode) {
     if (!this || this.children.length === 0) return false;
 
+    // if a child already has focus, assume that should be selected
+    this.children.find((child, index) => {
+      if (child.states.has(Config.focusStateKey)) {
+        this.selected = index;
+        return true;
+      }
+      return false;
+    });
+
     this.selected = this.selected || 0;
     let child = this.selected
       ? this.children[this.selected]
@@ -73,8 +82,8 @@ export function handleNavigation(
         return false;
       }
     }
-    const active = this.children[this.selected || 0];
-    assertTruthy(active instanceof ElementNode);
+    const active = this.children[this.selected || 0] || this.children[0];
+    if (!(active instanceof ElementNode)) return false;
     const navigableThis = this as NavigableElement;
 
     navigableThis.onSelectedChanged &&

package/src/primitives/utils/withScrolling.ts

@@ -8,11 +8,18 @@ import type {
 // Adds properties expected by withScrolling
 export interface ScrollableElement extends ElementNode {
   scrollIndex?: number;
+  scroll?: 'always' | 'none' | 'edge' | 'auto' | 'center';
   selected: number;
   offset?: number;
   endOffset?: number;
+  onScrolled?: (
+    elm: ScrollableElement,
+    offset: number,
+    isInitial: boolean,
+  ) => void;
   _targetPosition?: number;
   _screenOffset?: number;
+  _initialPosition?: number;
 }
 
 // From the renderer, not exported
@@ -48,7 +55,11 @@ export function withScrolling(isRow: boolean) {
     )
       return;
 
-    const lng = componentRef.lng as INode;
+    if (componentRef._initialPosition === undefined) {
+      componentRef._initialPosition = componentRef[axis];
+    }
+
+    const lng = componentRef.lng as unknown as INode;
     const screenSize = isRow ? lng.stage.root.width : lng.stage.root.height;
     // Determine if movement is incremental or decremental
     const isIncrementing =
@@ -68,13 +79,21 @@ export function withScrolling(isRow: boolean) {
 
     const screenOffset = componentRef._screenOffset;
     const gap = componentRef.gap || 0;
-    const scroll = componentRef.scroll || 'auto';
+    // when creating we set scroll to always so we setup the right location for selected and scrollIndex
+    const scroll =
+      componentRef.scroll ||
+      (lastSelected === undefined
+        ? componentRef.scrollIndex
+          ? 'center'
+          : 'always'
+        : 'auto');
 
     // Allows manual position control
     const targetPosition = componentRef._targetPosition ?? componentRef[axis];
-    const rootPosition = isIncrementing
-      ? Math.min(targetPosition, componentRef[axis])
-      : Math.max(targetPosition, componentRef[axis]);
+    const rootPosition =
+      isIncrementing || scroll === 'auto'
+        ? Math.min(targetPosition, componentRef[axis])
+        : Math.max(targetPosition, componentRef[axis]);
     componentRef.offset = componentRef.offset ?? rootPosition;
     const offset = componentRef.offset;
     selectedElement =
@@ -156,6 +175,11 @@ export function withScrolling(isRow: boolean) {
 
     // Update position if it has changed
     if (componentRef[axis] !== nextPosition) {
+      if (componentRef.onScrolled) {
+        const isInitial = nextPosition === componentRef._initialPosition;
+        componentRef.onScrolled(componentRef, nextPosition, isInitial);
+      }
+
       componentRef[axis] = nextPosition;
       // Store the new position to keep track during animations
       componentRef._targetPosition = nextPosition;

package/src/render.ts

@@ -4,7 +4,6 @@ import {
   type NodeProps,
   type TextProps,
   startLightningRenderer,
-  type RendererMain,
   type RendererMainSettings,
 } from '@lightningtv/core';
 import nodeOpts from './solidOpts.js';
@@ -14,14 +13,15 @@ import {
   createRenderEffect,
   untrack,
   type JSXElement,
-  type ValidComponent,
+  createRoot,
+  type Component,
 } from 'solid-js';
 import type { SolidNode } from './types.js';
 import { activeElement, setActiveElement } from './activeElement.js';
 
 const solidRenderer = solidCreateRenderer<SolidNode>(nodeOpts);
 
-let renderer: RendererMain;
+let renderer;
 export const rootNode = nodeOpts.createElement('App');
 
 const render = function (code: () => JSXElement) {
@@ -71,11 +71,13 @@ type Task = () => void;
 const taskQueue: Task[] = [];
 let tasksEnabled = false;
 
-createRenderEffect(() => {
-  // should change whenever a keypress occurs, so we disable the task queue
-  // until the renderer is idle again.
-  activeElement();
-  tasksEnabled = false;
+createRoot(() => {
+  createRenderEffect(() => {
+    // should change whenever a keypress occurs, so we disable the task queue
+    // until the renderer is idle again.
+    activeElement();
+    tasksEnabled = false;
+  });
 });
 
 export function setTasksEnabled(enabled: boolean): void {
@@ -117,10 +119,8 @@ function processTasks(): void {
  * ```
  * @description https://www.solidjs.com/docs/latest/api#dynamic
  */
-export function Dynamic<T>(
-  props: T & {
-    component?: ValidComponent;
-  },
+export function Dynamic<T extends Record<string, any>>(
+  props: T & { component?: Component<T> | undefined | null },
 ): JSXElement {
   const [p, others] = splitProps(props, ['component']);