@lightningtv/solid 3.0.0-2 → 3.0.0-20

package/src/primitives/index.ts

@@ -4,6 +4,7 @@ export * from './createInfiniteItems.js';
 export * from './useMouse.js';
 export * from './portal.jsx';
 export * from './Lazy.jsx';
+export * from './Image.jsx';
 export * from './Visible.jsx';
 export * from './router.js';
 export * from './Column.jsx';
@@ -11,11 +12,24 @@ 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 { withScrolling } from './utils/withScrolling.js';
-export { chainFunctions } from './utils/chainFunctions.js';
-export { handleNavigation, onGridFocus } from './utils/handleNavigation.js';
+export * from './useHold.js';
+export * from './KeepAlive.jsx';
+export * from './VirtualGrid.jsx';
+export * from './Virtual.jsx';
+export * from './utils/withScrolling.js';
+export * from './createTag.jsx';
+export {
+  type AnyFunction,
+  chainFunctions,
+  chainRefs,
+} from './utils/chainFunctions.js';
+export * from './utils/handleNavigation.js';
 export { createSpriteMap, type SpriteDef } from './utils/createSpriteMap.js';
+export { createBlurredImage } from './utils/createBlurredImage.js';
 
 export type * from './types.js';
 export type { KeyHandler } from '@lightningtv/core/focusManager';

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,11 +42,19 @@ 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
 export interface NavigableElement extends ElementNode, NavigableProps {
   selected: number;
+  scrollToIndex: (this: NavigableElement, index: number) => void;
 }
 
 export interface NavigableStyleProperties {

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/useMouse.ts

@@ -1,16 +1,65 @@
-import type { ElementText, INode, TextNode } from '@lightningtv/core';
+import type { ElementText, TextNode } from '@lightningtv/core';
 import {
+  Config,
   ElementNode,
   activeElement,
   isElementNode,
+  isFunc,
   isTextNode,
   rootNode,
-  Config,
 } from '@lightningtv/solid';
 import { makeEventListener } from '@solid-primitives/event-listener';
 import { useMousePosition } from '@solid-primitives/mouse';
 import { createScheduled, throttle } from '@solid-primitives/scheduled';
-import { createEffect } from 'solid-js';
+import { createEffect, getOwner, runWithOwner } from 'solid-js';
+
+type CustomState = `$${string}`;
+
+type RenderableNode = ElementNode | ElementText | TextNode;
+
+interface MouseStateOptions {
+  hoverState: CustomState;
+  pressedState: CustomState;
+  pressedStateDuration?: number;
+}
+
+type UseMouseOptions =
+  | { customStates: MouseStateOptions }
+  | { customStates: undefined };
+
+declare module '@lightningtv/core' {
+  interface ElementNode {
+    /** function to be called on mouse click */
+    onMouseClick?: (
+      this: ElementNode,
+      event: MouseEvent,
+      active: ElementNode,
+    ) => void;
+  }
+}
+
+const DEFAULT_PRESSED_STATE_DURATION = 150;
+
+export function addCustomStateToElement(
+  element: RenderableNode,
+  state: CustomState,
+): void {
+  element.states?.add(state);
+}
+
+export function removeCustomStateFromElement(
+  element: RenderableNode,
+  state: CustomState,
+): void {
+  element?.states?.remove(state);
+}
+
+export function hasCustomState(
+  element: RenderableNode,
+  state: CustomState,
+): boolean {
+  return element.states?.has(state);
+}
 
 function createKeyboardEvent(
   key: string,
@@ -29,6 +78,7 @@ function createKeyboardEvent(
   });
 }
 
+let scrollTimeout: ReturnType<typeof setTimeout>;
 const handleScroll = throttle((e: WheelEvent): void => {
   const deltaY = e.deltaY;
   if (deltaY < 0) {
@@ -36,30 +86,148 @@ const handleScroll = throttle((e: WheelEvent): void => {
   } else if (deltaY > 0) {
     document.body.dispatchEvent(createKeyboardEvent('ArrowDown', 40));
   }
+
+  // clear the last timeout if the user is still scrolling
+  clearTimeout(scrollTimeout);
+  // after 250ms of no scroll events, we send a keyup event to stop the scrolling
+  scrollTimeout = setTimeout(() => {
+    document.body.dispatchEvent(createKeyboardEvent('ArrowUp', 38, 'keyup'));
+    document.body.dispatchEvent(createKeyboardEvent('ArrowDown', 40, 'keyup'));
+  }, 250);
 }, 250);
 
-const handleClick = (e: MouseEvent): void => {
+function findElementWithCustomState<TApp extends ElementNode>(
+  myApp: TApp,
+  x: number,
+  y: number,
+  customState: CustomState,
+): ElementNode | undefined {
+  const result = getChildrenByPosition(myApp, x, y).filter((el) =>
+    hasCustomState(el, customState),
+  );
+
+  if (result.length === 0) {
+    return undefined;
+  }
+
+  let element: ElementNode | undefined = result[result.length - 1];
+
+  while (element) {
+    const elmParent = element.parent;
+    if (elmParent?.forwardStates && hasCustomState(elmParent, customState)) {
+      element = elmParent;
+    } else {
+      break;
+    }
+  }
+
+  return element;
+}
+
+function findElementByActiveElement(e: MouseEvent): ElementNode | null {
   const active = activeElement();
   const precision = Config.rendererOptions?.deviceLogicalPixelRatio || 1;
+
   if (
     active instanceof ElementNode &&
     testCollision(
       e.clientX,
       e.clientY,
-      (active.lng.absX as number) || 0 * precision,
-      (active.lng.absY as number) || 0 * precision,
-      active.width || 0 * precision,
-      active.height || 0 * precision,
+      ((active.lng.absX as number) || 0) * precision,
+      ((active.lng.absY as number) || 0) * precision,
+      (active.width || 0) * precision,
+      (active.height || 0) * precision,
     )
   ) {
+    return active;
+  }
+
+  let parent = active?.parent;
+  while (parent) {
+    if (
+      isFunc(parent.onMouseClick) &&
+      active &&
+      testCollision(
+        e.clientX,
+        e.clientY,
+        ((parent.lng.absX as number) || 0) * precision,
+        ((parent.lng.absY as number) || 0) * precision,
+        (parent.width || 0) * precision,
+        (parent.height || 0) * precision,
+      )
+    ) {
+      return parent;
+    }
+    parent = parent.parent;
+  }
+
+  return null;
+}
+
+function applyPressedState(
+  element: ElementNode,
+  pressedState: CustomState,
+  pressedStateDuration: number = DEFAULT_PRESSED_STATE_DURATION,
+): void {
+  addCustomStateToElement(element, pressedState);
+  setTimeout(() => {
+    removeCustomStateFromElement(element, pressedState);
+  }, pressedStateDuration);
+}
+
+function handleElementClick(
+  clickedElement: ElementNode,
+  e: MouseEvent,
+  customStates?: MouseStateOptions,
+): void {
+  if (customStates?.pressedState) {
+    applyPressedState(
+      clickedElement,
+      customStates.pressedState,
+      customStates.pressedStateDuration,
+    );
+  }
+
+  if (isFunc(clickedElement.onMouseClick)) {
+    clickedElement.onMouseClick(e, clickedElement);
+    return;
+  } else if (isFunc(clickedElement.onEnter)) {
+    clickedElement.onEnter();
+    return;
+  }
+
+  clickedElement.setFocus();
+  setTimeout(() => {
     document.dispatchEvent(createKeyboardEvent('Enter', 13));
     setTimeout(
       () =>
         document.body.dispatchEvent(createKeyboardEvent('Enter', 13, 'keyup')),
       1,
     );
-  }
-};
+  }, 1);
+}
+
+function createHandleClick<TApp extends ElementNode>(
+  myApp: TApp,
+  customStates?: MouseStateOptions,
+) {
+  return (e: MouseEvent): void => {
+    const clickedElement = customStates
+      ? findElementWithCustomState(
+          myApp,
+          e.clientX,
+          e.clientY,
+          customStates.hoverState,
+        )
+      : findElementByActiveElement(e);
+
+    if (!clickedElement) {
+      return;
+    }
+
+    handleElementClick(clickedElement, e, customStates);
+  };
+}
 
 function testCollision(
   px: number,
@@ -72,106 +240,155 @@ function testCollision(
   return px >= cx && px <= cx + cw && py >= cy && py <= cy + ch;
 }
 
-function getChildrenByPosition(
-  node: ElementNode,
+function isNodeAtPosition(
+  node: ElementNode | ElementText | TextNode,
   x: number,
   y: number,
-): ElementNode[] {
-  const result: ElementNode[] = [];
-  const precision = Config.rendererOptions?.deviceLogicalPixelRatio || 1;
+  precision: number,
+): node is ElementNode {
+  if (!isElementNode(node)) {
+    return false;
+  }
+
+  return (
+    node.alpha !== 0 &&
+    !node.skipFocus &&
+    testCollision(
+      x,
+      y,
+      ((node.lng.absX as number) || 0) * precision,
+      ((node.lng.absY as number) || 0) * precision,
+      (node.width || 0) * precision,
+      (node.height || 0) * precision,
+    )
+  );
+}
+
+function findHighestZIndexNode(nodes: ElementNode[]): ElementNode | undefined {
+  if (nodes.length === 0) {
+    return undefined;
+  }
+
+  if (nodes.length === 1) {
+    return nodes[0];
+  }
+
+  let maxZIndex = -1;
+  let highestNode: ElementNode | undefined = undefined;
+
+  for (const node of nodes) {
+    const zIndex = node.zIndex ?? -1;
+    if (zIndex >= maxZIndex) {
+      maxZIndex = zIndex;
+      highestNode = node;
+    }
+  }
 
+  return highestNode;
+}
+
+function getChildrenByPosition<TElement extends ElementNode = ElementNode>(
+  node: TElement,
+  x: number,
+  y: number,
+): TElement[] {
+  const result: TElement[] = [];
+  const precision = Config.rendererOptions?.deviceLogicalPixelRatio || 1;
   // Queue for BFS
+
   let queue: (ElementNode | ElementText | TextNode)[] = [node];
 
   while (queue.length > 0) {
     // Process nodes at the current level
-    const currentLevelNodes: ElementNode[] = [];
-
-    for (const currentNode of queue) {
-      if (
-        isElementNode(currentNode) &&
-        currentNode.alpha !== 0 &&
-        !currentNode.skipFocus &&
-        testCollision(
-          x,
-          y,
-          (currentNode.lng.absX as number) || 0 * precision,
-          (currentNode.lng.absY as number) || 0 * precision,
-          (currentNode.width || 0) * precision,
-          (currentNode.height || 0) * precision,
-        )
-      ) {
-        currentLevelNodes.push(currentNode);
-      }
-    }
+    const currentLevelNodes = queue.filter((currentNode) =>
+      isNodeAtPosition(currentNode, x, y, precision),
+    );
 
-    const size = currentLevelNodes.length;
-    if (size === 0) {
+    if (currentLevelNodes.length === 0) {
       break;
     }
 
-    let highestZIndexNode = null;
-    if (size === 1) {
-      highestZIndexNode = currentLevelNodes[0];
-    } else {
-      let maxZIndex = -1;
-
-      for (const node of currentLevelNodes) {
-        const zIndex = node.zIndex ?? -1;
-        if (zIndex > maxZIndex) {
-          maxZIndex = zIndex;
-          highestZIndexNode = node;
-        } else if (zIndex === maxZIndex) {
-          highestZIndexNode = node;
-        }
-      }
-    }
+    const highestZIndexNode = findHighestZIndexNode(currentLevelNodes);
 
-    if (highestZIndexNode && !isTextNode(highestZIndexNode)) {
-      result.push(highestZIndexNode);
-      queue = highestZIndexNode.children;
-    } else {
-      queue = [];
+    if (!highestZIndexNode || isTextNode(highestZIndexNode)) {
+      break;
     }
+
+    result.push(highestZIndexNode as TElement);
+    queue = highestZIndexNode.children;
   }
 
   return result;
 }
 
-export function useMouse(
-  myApp: ElementNode = rootNode,
+export function useMouse<TApp extends ElementNode = ElementNode>(
+  myApp: TApp = rootNode as TApp,
   throttleBy: number = 100,
+  options?: UseMouseOptions,
 ): void {
   const pos = useMousePosition();
   const scheduled = createScheduled((fn) => throttle(fn, throttleBy));
+  let previousElement: ElementNode | null = null;
+  const customStates = options?.customStates;
+  const hoverState = customStates?.hoverState;
+  const handleClick = createHandleClick(myApp, customStates);
+  const owner = getOwner();
+  const handleClickContext = (e: MouseEvent) => {
+    runWithOwner(owner, () => handleClick(e));
+  };
+
   makeEventListener(window, 'wheel', handleScroll);
-  makeEventListener(window, 'click', handleClick);
+  makeEventListener(window, 'click', handleClickContext);
   createEffect(() => {
     if (scheduled()) {
       const result = getChildrenByPosition(myApp, pos.x, pos.y).filter(
-        (el) => el.focus || el.onFocus || el.onEnter,
+        (el) =>
+          !!(
+            el.onEnter ||
+            el.onMouseClick ||
+            el.onFocus ||
+            el[Config.focusStateKey] ||
+            (hoverState ? el[hoverState] : false)
+          ),
       );
 
       if (result.length) {
-        let activeElm = result[result.length - 1];
+        let activeElm: ElementNode | undefined = result[result.length - 1];
 
         while (activeElm) {
           const elmParent = activeElm.parent;
           if (elmParent?.forwardStates) {
-            activeElm = activeElm.parent;
+            activeElm = elmParent;
           } else {
             break;
           }
         }
 
+        if (!activeElm) {
+          return;
+        }
+
         // Update Row & Column Selected property
-        const activeElmParent = activeElm?.parent;
-        if (activeElm && activeElmParent?.selected !== undefined) {
+        const activeElmParent = activeElm.parent;
+        if (activeElmParent?.selected !== undefined) {
           activeElmParent.selected =
             activeElmParent.children.indexOf(activeElm);
         }
 
-        activeElm?.setFocus();
+        if (previousElement && previousElement !== activeElm && hoverState) {
+          removeCustomStateFromElement(previousElement, hoverState);
+        }
+
+        if (hoverState) {
+          addCustomStateToElement(activeElm, hoverState);
+        } else {
+          activeElm.setFocus();
+        }
+
+        previousElement = activeElm;
+      } else if (previousElement && hoverState) {
+        removeCustomStateFromElement(previousElement, hoverState);
+        previousElement = null;
       }
     }
   });

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;