Lightning Framework

Lightning provides built-in support for three primary input methods. Depending on your target hardware and user interface requirements, you can implement:

• Remote / Keyboard Controls: For traditional TV remote navigation or standard keyboard input.
• Mouse: For pointer-based interaction.
• Touch: For touch-screen enabled devices.

Refer to the specific documentation for each method to implement specialized input handling logic.

You can control an element's presence and visual state using several categories of properties:

• Positioning: Set coordinates, dimensions, and mountpoints. All positioning is relative to its parent.
• Transform: Use transform properties to scale or rotate an element.
• Rendering: Use rendering properties to define if and how the element is rendered.
• Children: Use children properties to modify the configuration of child nodes.

Setting the clipping property to true prevents anything outside the element's dimensions from being rendered (similar to CSS overflow:hidden). This can improve performance by detecting and skipping descendants outside the clipping region.

Limitations:

• Clipping is implemented using the WebGL scissor operation and only works for rectangular areas.
• If an element (or any of its ancestors) is rotated, clipping will not be applied.
• For non-rectangular clipping or rotated elements, use renderToTexture instead.

To handle key events, Lightning identifies an active component through a concept called the focus path. The focus path is a hierarchy consisting of the active component and its descendants (including the App itself).

Lightning determines the focus path by recursively calling the _getFocused() method starting from the App object:

1. If _getFocused() returns undefined, the focus path stops at the current component.
2. If _getFocused() returns a child component, that child is added to the path, and its own _getFocused() method is invoked.
3. This recursion continues until a component returns undefined or the end of the tree is reached.

The focus path is only recalculated when:

• A component's state changes.
• A key is pressed.
• _refocus() is called on any component.

If you need to opt-out of strict type safety—for example, to allow arbitrary properties or child keys not explicitly declared in your spec—you can create a Loose Component.

To do this, extend your Template Spec from Lightning.Component.TemplateSpecLoose instead of Lightning.Component.TemplateSpec.

By default, any component that does not define its own Template Spec is considered a Loose Component. This is useful when integrating third-party libraries that may not have TypeScript support.

export interface MyComponentTemplateSpec extends Lightning.Component.TemplateSpecLoose {
  // Properties and children defined here are still typed,
  // but additional arbitrary keys are allowed.
}

The Lightning Render Tree is the structure used to define, position, and render elements in a Lightning application. While it shares conceptual similarities with the HTML DOM Render Tree (such as defining elements and setting properties to change display), it is fundamentally different in implementation:

• JavaScript-based: The entire tree is written in JavaScript.
• Basic API: It uses a more fundamental and minimal set of methods compared to the DOM.
• Template-driven: The tree is defined using Templates.
• Dynamic: It is designed to be highly dynamic during runtime.

To define and use specific elements within this tree, refer to the Elements documentation.

Lightning supports zIndex to alter the order in which textures are rendered, similar to CSS.

A z-index context is created when you use:

• A non-zero zIndex value.
• The forceZIndexContext property (useful when combined with zIndex: 0).
• renderToTexture.

By default, if no Type Config is provided, Lightning uses a Loose Type Config, which allows any Event or Signal to be handled with any parameters.

If you want the benefit of type-checking for specific events/signals while still allowing arbitrary ones, you can extend Lightning.Component.TypeConfigLoose instead of the standard TypeConfig.

export interface TypeConfigLoose extends Lightning.Component.TypeConfigLoose {
  SignalMapType: MyComponentSignalMap,
  EventMapType: MyComponentEventMap
}

The Lightning Render Engine implements several strategies to maintain high performance, especially in large applications:

• Incremental Updates: By tagging changed branches with hasUpdates, the engine only recalculates coordinates for modified sections, avoiding a full tree traversal.
• Visibility Culling: The engine does not render invisible parts of the tree.
• Out-of-screen Detection: Branches that are off-screen are detected and skipped, which enables high-performance, nearly infinite scrolling lists.
• Zero-change Idling: If no changes are detected in the Render Tree, no re-rendering occurs, which minimizes resource usage and power consumption.

In Lightning, the Render Tree is composed of Elements (of type lng.Element). An element acts as a render primitive that determines how a texture is displayed.

Crucial Note: An element will only be visible on screen if it has a texture attached to it (e.g., text, an image, a solid color, or a gradient).

The withAnnouncer mixin automates speech announcements by inspecting the component hierarchy during focus changes. It follows a two-step process:

1. Information Collection: It travels through the _focusPath looking for properties in this specific order of precedence:

   • component.announce
   • component.title
   • component.label

2. Contextualization: After collecting the properties, it reverses the _focusPath to look for component.announceContext properties.

This mechanism allows developers to provide both the primary identity of a component (e.g., a movie title) and the contextual information (e.g., "1 of 5 items") to create a coherent spoken experience.