@lightningtv/solid 3.1.4 → 3.1.6

package/docs/AI_CODING_GUIDELINES.md

@@ -1,165 +1,81 @@
-# AI Coding Guidelines for Lightning/Solid Framework
-
-This document outlines the specific constraints, properties, and layout systems available in the Lightning/Solid framework. AI agents should strictly adhere to these rules to generate correct and functional code.
-
-## Core Principles
-
-1.  **Positioning System**:
-
-    - All nodes are effectively `position: absolute`.
-    - Positioning is controlled via `x`, `y`, `width`, `height`.
-    - **Right / Bottom**: usage of `right` and `bottom` is supported for pinning elements to the parent's edges.
-      - Setting `right` automatically implies `mountX: 1`.
-      - Setting `bottom` automatically implies `mountY: 1`.
-    - **Mounting**:
-      - Default `mount` is **0, 0** (Top-Left corner).
-      - `mount` (0-1) determines the anchor point of the element itself (0.5 = center).
-      - **Avoid changing `mount` manually** unless specifically needed for centering (0.5) or specific anchor effects.
-    - There is no "flow" layout by default unless `display: 'flex'` is explicitly used.
-
-2.  **Dimensions**:
-
-    - **Explicit Dimensions**: It is **important** to give elements explicit `width` and `height` whenever possible.
-    - **Default Dimensions**: If `width` and `height` are **not** specified, the element will inherit the **parent's width and height**. This can lead to unexpected full-screen overlays if not managed carefully.
-
-3.  **Flexbox Layout**:
-
-    - **Must** set `display: 'flex'` on a container to enable flexbox.
-    - **Important**: `padding` is a _single number_ only. There is NO `paddingLeft`, `paddingRight`, `paddingTop`, or `paddingBottom`.
-    - **Margins**: Supported on flex items via `marginTop`, `marginBottom`, `marginLeft`, `marginRight`.
-    - **Gap**: `gap`, `rowGap`, `columnGap` are supported.
-    - **Alignment**: `justifyContent`, `alignItems`, `alignSelf` are strictly typed.
-
-4.  **Styling Restrictions**:
-
-    - **No** `background`. Use `color`.
-    - **Color Format**: **Prefer Hex Strings** (e.g., `'#ff0000ff'`). **NO** named colors.
-    - **No** `border-radius`. Use `borderRadius` (number).
-    - **No** `border`. Use `border` object: `{ width: number, color: string }`.
-    - **No** `box-shadow`. Use `shadow` object.
-    - **No** CSS class names.
-
-5.  **Props vs Styles**:
-    - **Prefer Props**: Pass properties directly to the component (e.g., `<View x={10} y={10} color="#ff0000ff" />`).
-    - Avoid using the `style` prop when possible.
-
-## Available Properties
-
-### Layout & Positioning
-
-| Property                    | Type     | Notes                                                        |
-| :-------------------------- | :------- | :----------------------------------------------------------- |
-| `x`, `y`                    | `number` | Absolute position coordinates.                               |
-| `right`                     | `number` | Distance from parent's right edge. **Implies `mountX: 1`**.  |
-| `bottom`                    | `number` | Distance from parent's bottom edge. **Implies `mountY: 1`**. |
-| `width` / `w`               | `number` | Explicit width. **Defaults to Parent Width** if unset.       |
-| `height` / `h`              | `number` | Explicit height. **Defaults to Parent Height** if unset.     |
-| `minWidth`, `minHeight`     | `number` | Minimum dimensions.                                          |
-| `maxWidth`, `maxHeight`     | `number` | Maximum dimensions.                                          |
-| `mount`, `mountX`, `mountY` | `number` | Anchor point. Default **0** (Top/Left).                      |
-| `pivot`, `pivotX`, `pivotY` | `number` | Pivot point.                                                 |
-| `rotation`                  | `number` | Rotation in radians.                                         |
-| `scale`, `scaleX`, `scaleY` | `number` | Scaling factor.                                              |
-| `alpha`                     | `number` | Opacity.                                                     |
-| `zIndex`, `zIndexLocked`    | `number` | Stacking order.                                              |
-
-### Flexbox Container Props
-
-_Requires `display: 'flex'`_
-
-| Property                     | Values / Type                                                                              | Notes                 |
-| :--------------------------- | :----------------------------------------------------------------------------------------- | :-------------------- |
-| `flexDirection`              | `'row' \| 'column'`                                                                        | Defaults to 'row'.    |
-| `flexWrap`                   | `'nowrap' \| 'wrap'`                                                                       |                       |
-| `justifyContent`             | `'flexStart' \| 'flexEnd' \| 'center' \| 'spaceBetween' \| 'spaceAround' \| 'spaceEvenly'` | Main axis alignment.  |
-| `alignItems`                 | `'flexStart' \| 'flexEnd' \| 'center'`                                                     | Cross axis alignment. |
-| `gap`, `rowGap`, `columnGap` | `number`                                                                                   | Space between items.  |
-| `padding`                    | `number`                                                                                   | **Uniform only**.     |
-
-### Flexbox Item Props
-
-| Property                       | Type                                   | Notes                   |
-| :----------------------------- | :------------------------------------- | :---------------------- |
-| `flexGrow`                     | `number`                               |                         |
-| `flexItem`                     | `boolean`                              | Set `false` to ignore.  |
-| `alignSelf`                    | `'flexStart' \| 'flexEnd' \| 'center'` | Overrides `alignItems`. |
-| `marginTop`, `marginBottom`... | `number`                               |                         |
-
-### Visual Styles
-
-| Property                     | Type                 | Notes                                                                    |
-| :--------------------------- | :------------------- | :----------------------------------------------------------------------- |
-| `color`                      | `string`             | **Hex String Preferred** (`'#ff0000ff'`).                                |
-| `colorTop`, `colorBottom`... | `string`             | Gradient-like vertex coloring in hex string.                             |
-| `linearGradient`             | `object`             | `{ angle?: number, colors: string[], stops?: number[] }`                 |
-| `radialGradient`             | `object`             | `{ radius?: number, colors: string[], stops?: number[], ... }`           |
-| `borderRadius`               | `number \| number[]` | Single radius or [tl, tr, br, bl].                                       |
-| `border`                     | `object`             | `{ width: number, color: string }`.                                      |
-| `shadow`                     | `object`             | `{ color: string, x: number, y: number, blur: number, spread: number }`. |
-
-### Text Properties
-
-| Property       | Type                             | Notes           |
-| :------------- | :------------------------------- | :-------------- |
-| `text`         | `string`                         | Content string. |
-| `fontSize`     | `number`                         |                 |
-| `fontFamily`   | `string`                         |                 |
-| `fontWeight`   | `number \| string`               |                 |
-| `lineHeight`   | `number`                         |                 |
-| `textAlign`    | `'left' \| 'center' \| 'right'`  |                 |
-| `wordWrap`     | `boolean`                        |                 |
-| `maxLines`     | `number`                         | truncate text.  |
-| `textOverflow` | `'clip' \| 'ellipsis' \| string` |                 |
-
-### Interaction & Focus
-
-| Property         | Type       | Notes                                                                    |
-| :--------------- | :--------- | :----------------------------------------------------------------------- |
-| `onFocus`        | `function` | Called when element gains focus.                                         |
-| `onBlur`         | `function` | Called when element loses focus.                                         |
-| `onFocusChanged` | `function` | **Preferred**. `(hasFocus: boolean) => void`. Combines focus/blur logic. |
-| `onEnter`        | `function` | Called on Enter key press.                                               |
-
-#### Focus Handling Best Practice
-
-When tracking focus state (e.g., for styling), prefer `onFocusChanged` over separate `onFocus`/`onBlur` handlers.
-
-**Preferred Pattern:**
+# Custom TV-UI Framework: Lightning + SolidJS
 
-```tsx
-const [focused, setFocused] = createSignal(false);
+**System Role:** You are an expert frontend engineer working with a custom TV-UI framework called **Lightning**, built on **SolidJS**.
 
-return (
-  <View
-    width={180}
-    height={100}
-    color={focused() ? '#ffff00ff' : '#333333ff'}
-    onFocusChanged={setFocused}
-  />
-);
-```
+## 1. Core Architecture & Runtime
+
+- **Environment:** TV app development over WebGL (not the DOM). No pointer input; interaction is directional (Up/Down/Left/Right).
+- **Reactivity:** Uses SolidJS primitives (`createSignal`, `createEffect`, `createMemo`).
+- **Primitives:** UI is built using custom components like `<View>`, `<Text>`, `<Row>`, `<Column>`.
+- **Patterns:** Always use functional components and modern TypeScript/JSX. Avoid classes.
+- **Assumption:** Always frame answers within the context of Lightning + SolidJS TV environment.
+
+## 2. Layout & Positioning
+
+- **Absolute by Default:** All nodes are naturally `position: absolute`.
+- **Positioning:** Controlled explicitly via `x`, `y`, `width`, `height`.
+- **Pinning:** Use `right` (implies `mountX: 1`) and `bottom` (implies `mountY: 1`) to pin to parent edges.
+- **Mounting:** Default `mount` is `0, 0` (Top-Left). Value `0` to `1` determines anchor point. Avoid manual changes unless centering (`0.5`).
+- **Dimensions:** Explicit `width` and `height` are crucial. Unspecified dimensions will inherit parent size (causing unintended overlays).
+
+## 3. Flexbox Engine
+
+- **Activation:** Set `display: "flex"` on containers to enable flex layout.
+- **Padding:** Supports ONLY a single overall `padding` number. (NO `paddingLeft`, `paddingTop`, etc.).
+- **Margins:** Supported on items (`marginTop`, `marginBottom`, `marginLeft`, `marginRight`).
+- **Gap:** `gap`, `rowGap`, and `columnGap` are supported.
+- **Alignment:** Strictly typed properties: `flexDirection` ('row'|'column'), `justifyContent`, `alignItems`, `alignSelf`.
+
+## 4. Styling Strict Rules
+
+- **Colors:** MUST use hex strings (e.g., `"#ff0000ff"`). NO named colors (e.g., `'red'`) or CSS variables.
+- **Backgrounds:** DO NOT use `background`. Use `color` instead.
+- **Borders/Shadows:** Use object structures (`border={{ width: 1, color: "#000000ff" }}`). NO CSS `border` or `box-shadow` strings.
+- **Radii:** Use numeric `borderRadius` (single number or array `[tl, tr, br, bl]`).
+- **Classes/Styles:** CSS classes and inline `style={{}}` props are NOT supported. Pass props directly to the component.
+
+## 5. Focus & Interaction
+
+- **Navigation:** Navigation is handled via a remote control with arrow keys. Use `onUp`, `onDown`, `onLeft`, and `onRight` to handle directional input on components.
+- **Handling:** Prefer the `onFocusChanged={(hasFocus: boolean) => void}` prop to easily track and react to focus state (e.g. for hover styles).
+- **Events:** `onFocus`, `onBlur`, and `onEnter` are available for direct actions.
+- **Auto-Focus:** Exactly one item should include the `autofocus` prop (`autofocus={true}`) when a page loads.
+- **Forwarding Focus:** Use `forwardFocus` to set focus on a child element. It can take a number (e.g., `forwardFocus={1}`) to focus a specific descendant by index.
+- **Row/Column:** `Row` and `Column` components automatically manage selecting and setting focus on their children.
 
-## Strict "Do Not Use" List
+## 6. Property Reference
 
-| Invalid Property      | Correct Alternative                                    |
-| :-------------------- | :----------------------------------------------------- |
-| `background`          | Use `color`.                                           |
-| Named colors          | Use hex strings (`'#ff0000ff'`).                       |
-| `textColor`           | Use `color` on the Text node itself.                   |
-| `paddingLeft`...      | Use `padding` (uniform) or `margin` props on children. |
-| `border-style` string | Use `border` object.                                   |
-| `display: 'grid'`     | Not supported. Use nested Flexboxes.                   |
-| `className`           | Not supported.                                         |
-| `style={{ ... }}`     | **Avoid**. Pass props directly to the component.       |
+### Positioning & Transformation
 
-## Example Usage
+`x`, `y`, `right`, `bottom`, `width` (w), `height` (h), `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, `mount`, `mountX`, `mountY`, `pivot`, `pivotX`, `pivotY`, `rotation`, `scale`, `scaleX`, `scaleY`, `alpha`, `zIndex`, `zIndexLocked`
 
-### Incorrect ❌
+### Container Flexbox
+
+`display: "flex"`, `flexDirection`, `flexWrap`, `justifyContent`, `alignItems`, `gap`, `rowGap`, `columnGap`, `padding`
+
+### Item Flexbox
+
+`flexGrow`, `flexItem`, `alignSelf`, `marginTop`, `marginBottom`, `marginLeft`, `marginRight`
+
+### Visual & Text
+
+`color`, `colorTop`, `colorBottom`, `linearGradient`, `radialGradient`, `borderRadius`, `border`, `shadow`, `text`, `fontSize`, `fontFamily`, `fontWeight`, `lineHeight`, `textAlign`, `wordWrap`, `maxLines`, `textOverflow`
+
+## 7. DO NOT USE 🚫
+
+- Standard DOM Elements (`<div>`, `<span>`, etc.)
+- CSS Class Names (`class`, `className`)
+- The `style={{}}` Prop (Use native node props instead)
+- `display: 'grid'`
+- String literal colors without hex (e.g. `'red'`, `'#F00'`) - Use full hex codes like `'#ff0000ff'`
+- Directional paddings (e.g., `paddingLeft`)
+
+## 8. Code Examples
+
+**❌ Incorrect:**
 
 ```tsx
-// 1. Missing dimensions (might default to full screen)
-// 2. Using named colors
-// 3. Using style object
+// Missing dimensions, invalid colors, using styles, directional padding
 <View
   style={{
     backgroundColor: 'red',
@@ -172,20 +88,21 @@ return (
 </View>
 ```
 
-### Correct ✅
+**✅ Correct:**
 
 ```tsx
-// 1. Explicit dimensions
-// 2. Direct Props
-// 3. Hex Strings
+const [focused, setFocused] = createSignal(false);
+
+// Uses direct props, hex colors, clear dimensions, and focus tracking
 <View
-  width={400} // Explicit Width
-  height={200} // Explicit Height
-  color="#ff0000ff" // Hex string
-  padding={20} // Uniform padding
-  borderRadius={10} // Number
-  display="flex" // defaults to flexDirection row
+  width={400}
+  height={200}
+  color={focused() ? '#ffff00ff' : '#ff0000ff'}
+  padding={20}
+  borderRadius={10}
+  display="flex"
+  onFocusChanged={setFocused}
 >
   <Text color="#ffffffff">Hello</Text>
-</View>
+</View>;
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningtv/solid",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "description": "Lightning Renderer for Solid Universal",
   "type": "module",
   "exports": {

package/src/core/elementNode.ts

@@ -61,6 +61,8 @@ import {
 } from './focusManager.js';
 import simpleAnimation, { SimpleAnimationSettings } from './animation.js';
 
+let nextActiveElement: ElementNode | null = null;
+let focusQueued: boolean = false;
 let layoutRunQueued = false;
 const layoutQueue = new Set<ElementNode>();
 
@@ -835,7 +837,10 @@ export class ElementNode extends Object {
       const animationSettings =
         this.transition === true || this.transition[name] === true
           ? undefined
-          : (this.transition[name] as undefined | AnimationSettings);
+          : this.transition[name] ||
+            (this.transition[getPropertyAlias(name)] as
+              | undefined
+              | AnimationSettings);
 
       if (Config.simpleAnimationsEnabled) {
         simpleAnimation.add(
@@ -957,7 +962,15 @@ export class ElementNode extends Object {
         }
       }
       // Delay setting focus so children can render (useful for Row + Column)
-      queueMicrotask(() => setActiveElement(this));
+      nextActiveElement = this;
+      if (focusQueued === false) {
+        focusQueued = true;
+        queueMicrotask(() => {
+          if (nextActiveElement) setActiveElement(nextActiveElement);
+          nextActiveElement = null;
+          focusQueued = false;
+        });
+      }
     } else {
       this._autofocus = true;
     }

package/src/core/focusManager.ts

@@ -173,11 +173,13 @@ const propagateKeyPress = (
     }
     lastGlobalKeyPressTime = currentTime;
   }
-  let finalFocusElm: ElementNode | undefined;
-  let handlerAvailable: ElementNode | undefined;
   const numItems = focusPath.length;
-  const captureEvent =
-    `onCapture${mappedEvent || e.key}` + isUp ? 'Release' : '';
+  if (numItems === 0) return false;
+
+  let handlerAvailable: ElementNode | undefined;
+  const finalFocusElm = focusPath[0]!;
+  const keyBase = mappedEvent || (e.key as string);
+  const captureEvent = `onCapture${keyBase}${isUp ? 'Release' : ''}`;
   const captureKey = isUp ? 'onCaptureKeyRelease' : 'onCaptureKey';
 
   for (let i = numItems - 1; i >= 0; i--) {
@@ -205,12 +207,10 @@ const propagateKeyPress = (
   }
 
   let eventHandlerKey: string | undefined;
-  let releaseEventHandlerKey: string | undefined;
   let fallbackHandlerKey: 'onKeyHold' | 'onKeyPress' | undefined;
 
   if (mappedEvent) {
-    eventHandlerKey = `on${mappedEvent}`;
-    releaseEventHandlerKey = `on${mappedEvent}Release`;
+    eventHandlerKey = isUp ? `on${mappedEvent}Release` : `on${mappedEvent}`;
   }
 
   if (!isUp) {
@@ -219,9 +219,6 @@ const propagateKeyPress = (
 
   for (let i = 0; i < numItems; i++) {
     const elm = focusPath[i]!;
-    if (!finalFocusElm) {
-      finalFocusElm = elm;
-    }
 
     // Check throttle for bubbling phase
     if (elm.throttleInput) {
@@ -236,21 +233,13 @@ const propagateKeyPress = (
 
     let handled = false;
 
-    // Check for the release event handler if isUp is true and the key is defined
-    if (isUp && releaseEventHandlerKey) {
-      const eventHandler = elm[releaseEventHandlerKey];
-      if (isFunction(eventHandler)) {
-        handlerAvailable = elm;
-        if (eventHandler.call(elm, e, elm, finalFocusElm) === true)
-          handled = true;
-      }
-    } else if (!isUp && eventHandlerKey) {
-      // Check for the regular event handler if isUp is false and the key is defined
+    if (eventHandlerKey) {
       const eventHandler = elm[eventHandlerKey];
       if (isFunction(eventHandler)) {
         handlerAvailable = elm;
-        if (eventHandler.call(elm, e, elm, finalFocusElm) === true)
+        if (eventHandler.call(elm, e, elm, finalFocusElm) === true) {
           handled = true;
+        }
       }
     }
 
@@ -261,8 +250,9 @@ const propagateKeyPress = (
         handlerAvailable = elm;
         if (
           fallbackHandler.call(elm, e, mappedEvent, elm, finalFocusElm) === true
-        )
+        ) {
           handled = true;
+        }
       }
     }
 

package/src/primitives/Grid.tsx

@@ -1,5 +1,5 @@
-import { For, createSignal, createMemo, createEffect, JSX } from "solid-js";
-import { type NodeProps, ElementNode, NewOmit } from "@lightningtv/solid";
+import { For, createSignal, createMemo, createEffect, JSX, untrack, Index } from "solid-js";
+import { type NodeProps, ElementNode, NewOmit, hasFocus } from "@lightningtv/solid";
 import { chainRefs } from "./utils/chainFunctions.js";
 
 export interface GridItemProps<T> {
@@ -20,6 +20,7 @@ export interface GridProps<T> extends NewOmit<NodeProps, 'children'> {
   columns?: number;
   looping?: boolean;
   scroll?: "auto" | "none";
+  selected?: number;
   onSelectedChanged?: (index: number, grid: ElementNode, elm?: ElementNode) => void;
 }
 
@@ -28,16 +29,25 @@ export function Grid<T>(props: GridProps<T>): JSX.Element {
   const [focusedIndex, setFocusedIndex] = createSignal(0);
   const baseColumns = 4;
 
+  createEffect(() => {
+    const currentIndex = untrack(focusedIndex);
+    if (props.selected === currentIndex) return;
+    if (props.selected !== undefined && props.items?.length > props.selected) {
+      moveFocus(props.selected! - currentIndex);
+    }
+  });
+
   const itemWidth = () => props.itemWidth ?? 300
   const itemHeight = () => props.itemHeight ?? 300
 
   const columns = createMemo(() => props.columns || baseColumns);
   const totalWidth = createMemo(() => itemWidth() + (props.itemOffset ?? 0));
   const totalHeight = createMemo(() => itemHeight() + (props.itemOffset ?? 0));
+  const rows = createMemo(() => Math.ceil(props.items.length / columns()));
 
   function focus() {
     const focusedElm = gridRef.children[focusedIndex()];
-    if (focusedElm instanceof ElementNode && !focusedElm.states.has('$focus')) {
+    if (focusedElm instanceof ElementNode && !hasFocus(focusedElm)) {
       focusedElm.setFocus();
       props.onSelectedChanged?.call(gridRef, focusedIndex(), gridRef, focusedElm);
       return true;
@@ -99,27 +109,27 @@ export function Grid<T>(props: GridProps<T>): JSX.Element {
     <view
       {...props}
       ref={chainRefs(el => gridRef = el, props.ref)}
-      transition={{ y: true }}
+      transition={/* @once */ { y: true }}
+      height={totalHeight() * rows()}
       onUp={() => moveFocus(-columns())}
       onDown={() => moveFocus(columns())}
       onLeft={() => handleHorizontalFocus(-1)}
       onRight={() => handleHorizontalFocus(1)}
       onFocus={() => handleHorizontalFocus(0)}
-      strictBounds={false}
       y={scrollY()}
     >
-      <For each={props.items}>
+      <Index each={props.items}>
         {(item, index) => (
           <props.children
-            item={item}
-            index={index()}
+            item={item()}
+            index={index}
             width={itemWidth()}
             height={itemHeight()}
-            x={(index() % columns()) * totalWidth()}
-            y={Math.floor(index() / columns()) * totalHeight()}
+            x={(index % columns()) * totalWidth()}
+            y={Math.floor(index / columns()) * totalHeight()}
           />
         )}
-      </For>
+      </Index>
     </view>
   );
 };