Flex-grid types

Types shared by several @roku-sdk/flex-grid exports, or used by none of them directly

import type {
    CardLayoutContext,
    CardPool,
    CellRenderProps,
    CellVAlign,
    FlexGridClippingConfig,
    FlexGridConfig,
    FlexGridConfigCore,
    FlexGridHandle,
    FocusConfig,
    FocusedRowAttachmentOptions,
    FocusHighlightConfig,
    FocusHighlightProps,
    FocusState,
    FocusStrategyBase,
    FocusStrategyPlugin,
    GridCapabilities,
    GridCapability,
    GridFocusInternals,
    GridKeyHolder,
    GridLayersInternals,
    GridPlugin,
    GridPluginEntry,
    GridPluginInternals,
    GridRowsInternals,
    GridScrollInternals,
    GridStore,
    GridViewport,
    HFocusStyleName,
    HorizontalFocusAxisConfig,
    HorizontalScrollHooks,
    InitGridPlugin,
    KeyDelegate,
    KeyValue,
    PerfGridPlugin,
    PerfHandle,
    PerfPlugin,
    PluginCellTemplate,
    PoolBufferConfig,
    PooledNodeVM,
    PoolOps,
    PoolSizeResult,
    Position,
    PositionValue,
    RemoteKey,
    RowCardsWrap,
    RowCardsWrapContext,
    RowYOffsetProvider,
    SmoothScrollConfig,
    TxCounts,
    VerticalFocusAxisConfig,
    VerticalFocusOptions,
    VerticalFocusState,
    VerticalFocusStrategyPlugin,
    VerticalScrollHooks,
    VerticalStrategyConfig,
    VFocusStyleName,
} from "@roku-sdk/flex-grid";
import type { FixedFocusYParams } from "@roku-sdk/flex-grid/geometry";
import type {
    HStrategyExtension,
    HStrategyFocusContext,
    HStrategyMatcher,
    HStrategyScrollContext,
} from "@roku-sdk/flex-grid/compose-h-strategy";

Each is documented here once and linked from every page that uses it.

Types

CardLayoutContext

Context passed to optional per-card layout callbacks (e.g. zoom-focus plugin).

CardPool

CellRenderProps

Props passed to the getCellComponent factory for each visible pool node.

CellRenderProps.setFocusBoundary

Register this cell's own FocusBoundary identity, for composite cells that would rather receive keys through the focus chain than through a KeyDelegate.

While this cell is the focused cell, the grid moves its own boundary's virtual focus to the identity registered here. Keys then reach the cell's boundary first, and the grid's navigation runs only when that boundary declines — a key the cell resolves internally (zone move, inner grid movement, Select) never reaches the grid, and a key it has no neighbour for falls through to move the grid. This inverts the KeyDelegate contract, where the delegate runs before navigation and has to return false to hand the key back.

Requires the grid to be in boundary mode (a focusId on the grid config); without one there is no boundary whose focus to move. Pass null to unregister.

The identity must be registered by a real FocusBoundary (or useFocusable) in the cell's subtree. Unlike CellRenderProps.setKeyDelegate, this registration is not cleared when the pool node is recycled: a pool node's subtree mounts once and is reused, so its boundary — and therefore its identity — is stable for the life of the grid, and clearing it would leave the cell unreachable after its first reuse. Register once and let it stand.

Because that boundary outlives the item it first mounted for, drive its contents from row / col / item rather than from mount-time values, and prefer rememberLastFocus={false} so sub-focus resets when the cell is reused. rememberLastFocus remembers per pool node, not per item, so a recycled node reopens on whatever the previous item last focused. To remember per item, store the last sub-focus on the item and derive initialFocus from it.

Shared pools are supported when all grids share the same root FocusBoundary. The grid rebinds the cell boundary's parent to the displaying grid before giving it focus.

CellRenderProps.setKeyDelegate

Register a KeyDelegate for this cell. The delegate is called before the grid's own navigation handler so the cell can intercept keys. Return false from handleKey to fall through to the grid. Set null to unregister (e.g., when the cell collapses). The delegate is automatically cleared when the pool node is recycled.

Only movement / RemoteKey.Select keys claimed by the grid reach the delegate — see KeyDelegate.handleKey.

CellVAlign

Vertical alignment for cells with per-item heights within a row.

type CellVAlign = "top" | "center" | "bottom";

FixedFocusYParams

Describes viewport and row geometry for a fixed vertical focus strategy.

Row indices are zero-based integers and all dimensions are in pixels. Empty content uses a zero row count; row accessors are not called for it.

Also exported as FixedFocusYParams from @roku-sdk/flex-grid (deprecated).

Deprecated: FixedFocusYParams. Import from @roku-sdk/flex-grid/geometry instead. The root export will be removed in the next major version.

Example

const geometry: FixedFocusYParams = {
    containerY: 50, viewportHeight: 200, numRows: 4,
    getRowY: row => row * 100, getRowHeight: () => 100
};

FlexGridClippingConfig

Clipping options — when enabled, width and height are required.

type FlexGridClippingConfig = { enableClipping: false; height: number; width: number } | { enableClipping: true; height: number; width: number };

FlexGridConfig

type FlexGridConfig<T> = FlexGridConfigCore<T> & FlexGridClippingConfig;

FlexGridConfigCore

Configuration fields shared by clipped and unclipped grids.

FlexGridConfigCore.captureKeyPress

Boundary mode only (focusId set). When true, a key this grid consumed on the key-down is bound to the grid, so its key-up is delivered here no matter where focus has moved in the meantime.

Smooth scroll is the reason it exists. The grid arms its hold timer on the press and only settles when it sees the release, but a glide moves virtual focus as it travels: cross a row whose cell registered its own boundary via setFocusBoundary, and the key-up is offered to that cell first. A cell that owns the key on both edges consumes it there, the grid never learns the hold ended, and the glide runs to the end of the data.

This is not limited to the directions. Capture keys off "the grid consumed this press", so it covers every key the grid's boundary claims: the four directions, Select (OK), Fwd / Rev, and everything in FlexGridConfigCore.handleAdditionalKeyEvents. For those, the visible effect is that if focus moved between the press and the release, the release comes back to the grid rather than descending to the newly focused cell. With FlexGridConfigCore.declineUnhandledNavigation on, a press the grid declined is not captured, so only keys it actually acted on are bound.

A cell that declines the key-up does not need this — that path already works, and is what the in-repo examples rely on. Turn it on when the grid holds rows whose cells claim movement keys, or when you would rather not depend on every cell template getting the decline right.

A bound key is released when the grid loses focus, so handing focus to another region mid-hold does not leave the key claimed — which also bounds the case where the key-up never arrives at all. Nothing is synthesized either way.

Implemented by captureKeyPress on the boundary the grid renders; see IFocusBoundaryProps.captureKeyPress in @roku-sdk/navigation for the exact semantics.

FlexGridConfigCore.declineUnhandledNavigation

Boundary mode only (focusId set). When true, keys the grid's navigation did not act on are declined instead of swallowed, so they bubble to whatever encloses the grid — a parent cell's own FocusBoundary, or the app's root boundary.

A grid's boundary otherwise consumes every movement key it claims, whether or not focus moved, which leaves an inner grid unable to hand its top / bottom / right edges to the grid around it: onEdgeReached fires, but the key is already gone. Declining removes the need for the out-of-band edge flag that pattern otherwise requires.

Consumption is judged the same way as bare mode's forwardKeyEvent: true when the focused cell's delegate consumed the key, when focus moved, or when onItemSelected returned true. That includes OK — with this on, an onItemSelected returning false reaches the enclosing region instead of being dropped.

Off by default: a top-level grid that declines its edge keys would start handing them to the app's root boundary, which is a behaviour change for existing apps.

FlexGridConfigCore.focusId

Identity object registering this grid as a nested FocusBoundary focusable inside an enclosing (root) FocusBoundary. When provided, the grid owns its movement keys (up/down/left/right/OK) through that boundary and hands region focus back to siblings via FlexGridConfigCore.onEdgeReached + setFocus.

Omit for a nested/bare grid (e.g. a grid inside another grid's cell): no boundary is created and keys arrive only via FlexGridHandle.forwardKeyEvent (driven by the parent cell's KeyDelegate).

FlexGridConfigCore.handleAdditionalKeyEvents

Extra keys to route into the grid's key pipeline, on top of the built-in movement and selection keys (BOUNDARY_KEYS: RemoteKey.Left / Right / Up / Down / Select / Fwd / Rev).

Listed keys are added to the grid's nested FocusBoundary claimed-key set and are offered to the focused cell's KeyDelegate first, matching the normal pipeline order. The grid itself never navigates on these keys.

If the delegate declines (returns false), the key is re-thrown to the enclosing boundary via FlexGridConfigCore.onUnhandledAdditionalKey so opting a key in never traps it.

Also honored by FlexGridHandle.forwardKeyEvent so nested/bare grids get the same behavior.

Treat this as static configuration. The claimed-key set is fixed when the grid's FocusBoundary is created. Via defineFlexGrid the array participates in the remount dependency list, so a content change remounts the grid; calling createFlexGrid directly there is no remount machinery at all and a later change has no effect. If the set needs to vary, opt in to the union of every key you might need and decide per-event inside the KeyDelegate.

FlexGridConfigCore.jumpTo

Declarative focus/scroll target. Reactive when passed as an Accessor. First application to a non-(0,0) position snaps (no tween); later changes animate. Supersedes initialFocus when both are set.

Dedup: the internal jump effect skips when the clamped target equals the last successfully applied declarative jump. Re-setting the same [row, col] after the user navigates away with the D-pad is a no-op. Use FlexGridHandle.jumpTo for unconditional re-jumps, or clear the accessor to undefined before re-assigning.

FlexGridConfigCore.onUnhandledAdditionalKey

Called when a key listed in FlexGridConfigCore.handleAdditionalKeyEvents was claimed by the grid's boundary but declined by the focused cell's KeyDelegate.

Because the grid's boundary claims these keys, they no longer reach the enclosing boundary's onUnhandledKey on their own. Use this hook to run the app-level fallback (the behavior the key would have had if it were never opted in).

Only fires in top-level (focusId) mode. In bare/nested mode the same condition is surfaced by FlexGridHandle.forwardKeyEvent returning false.

Fires for both press and release, mirroring the raw boundary events — guard on press if the action should run once per keypress.

Captured once at creation (like FlexGridConfigCore.onEdgeReached and FlexGridConfigCore.onItemSelected), so a later identity change is not picked up. Read changing state from a signal inside the callback rather than closing over it.

FlexGridConfigCore.plugins

Tree-shakeable grid plugins — bob, row-titles, focus-highlight, perf, and custom extensions.

Scale-on-focus is a template concern — wrap cell templates with withZoomFocus from @roku-sdk/flex-grid/zoom-focus instead of a plugin.

FlexGridConfigCore.viewportBuffer

Viewport buffer for row/column windowing (all values in pixels).

• top: extra pixels to render above viewport (default: 500)
• bottom: extra pixels to render below viewport (default: 500)
• left: extra pixels to render left of viewport (default: 500)
• right: extra pixels to render right of viewport (default: 500)

FlexGridHandle

FlexGridHandle.store

Direct reference to the underlying store. Reading is always safe.

Writing to store.rows bypasses the emptiness bookkeeping behind the loaded-empty row collapse, so a row published that way keeps its full height even when set to []. Publish through FlexGridHandle.updateRows / FlexGridHandle.setNumRows instead.

FocusConfig

Focus and scroll behavior for both axes — pass on createFlexGrid({ focus }).

FocusedRowAttachmentOptions

Options for GridRowsInternals.attachToFocusedRow.

FocusHighlightConfig (@roku-sdk/flex-grid)

Deprecated.

Legacy root type; import FocusHighlightConfig from @roku-sdk/flex-grid/focus-highlight instead. Will be removed from the public exports in the next major version.

Legacy focus-highlight configuration retained for compatibility.

FocusHighlightProps

FocusState

State passed to horizontal strategy functions on each focus update.

FocusStrategyBase

Base config shared by all horizontal focus strategies.

FocusStrategyPlugin

Plugin interface for horizontal focus strategies. Each strategy is a separate module; only imported strategies end up in the bundle.

GridCapabilities

Checks statically declared behavior before a plugin mounts duplicate chrome. The lookup includes every plugin's provides declarations, including the caller. It is fixed at grid construction and is not a reactive accessor.

GridCapability

Behaviour a plugin declares it owns, so other plugins can stand down instead of drawing the same thing twice. Declared statically via provides on the plugin object (read before any init runs, so it never depends on plugin order).

• focusVisual; a plugin draws the focused cell's visual treatment.
  createFocusHighlightPlugin suppresses its own node when something else provides it.

No first-party plugin declares focusVisual today: this is a third-party extension point for plugins that draw their own focus chrome. Cell templates cannot declare capabilities, so a template that owns the visual (via withZoomFocus, say) has the app pass renderNode: false to createFocusHighlightPlugin instead. Both routes reach the same outcome; the highlight still feeds per-cell focused to the engine, it just does not draw.

type GridCapability = "focusVisual";

GridFocusInternals

Provides the focused item and geometry for focus-following plugin visuals. Read position, item and size accessors inside effects or JSX so visuals update as focus moves; values read once during init are only snapshots.

GridKeyHolder

Mutable holder so external pools can bind gridKey after warmup.

type GridKeyHolder = {
    current?: object;
};

GridLayersInternals

Mounts plugin-owned components above, below or alongside the grid's content. Use scroll layers for content-space visuals and mountOverlay for an overlay outside scrolling content. Read refs and other grid accessors inside effects or JSX; the viewport object contains fixed construction-time geometry.

GridPlugin

Plugin entry accepted by FlexGridConfig.plugins. Holds two kinds:

• Lifecycle (InitGridPlugin<T>) — bob, row-titles, focus-highlight, custom plugins.
  Implement init(internals) to mount UI or register scroll hooks.
  When writing custom plugins, extend or return InitGridPlugin<T>,
  not GridPlugin<T> — GridPlugin is the array-element union type.

• Perf (PerfPlugin) — pass createPerfPlugin().
  Extracted before engine/nav creation by resolveGridPlugins.

Scale-on-focus is a template concern — use withZoomFocus from @roku-sdk/flex-grid/zoom-focus on cell templates instead of a plugin.

Example

// Implementing a custom init plugin:
import type { InitGridPlugin, GridPluginInternals } from "@roku-sdk/flex-grid";

function createMyPlugin<T>(): InitGridPlugin<T> {
  return {
    init(internals: GridPluginInternals<T>) { ... }
  };
}

// Passing plugin kinds:
plugins: [
  createPerfPlugin({ output: "both" }),
  createMyPlugin(),
]

type GridPlugin<T> = GridPluginEntry<T>;

GridPluginEntry

All plugin kinds accepted in FlexGridConfig.plugins.

type GridPluginEntry<T = unknown> = InitGridPlugin<T> | PerfGridPlugin;

GridPluginInternals

Grid state and registration hooks supplied to InitGridPlugin.init. Use these namespaces to register chrome, follow focus or coordinate animation without accessing the engine implementation. The engine exists during init, but engineReady() becomes true only after every plugin has initialized. All accessors are reactive; read them inside effects or JSX props. The namespace objects themselves are stable, so const { rows, focus } = internals at the top of init is safe.

GridRowsInternals

Provides row geometry and registration hooks for row chrome or custom layout. Read reactive accessors such as count, rowYOffset and snapping inside effects or JSX. Row renderers receive a recycled slot's reactive row accessor; do not cache its current value when registering the renderer.

GridRowsInternals.registerCardLayout

Register a per-card layout callback; invoked by the engine on every layout pass after position/focus updates. Handlers run in registration order (call order during init).

Call this synchronously from init (not from createEffect, queueMicrotask, or other deferred work), or the first layout pass may run before your handler is registered.

GridRowsInternals.registerRowChrome

Register a per-row chrome renderer. render receives a reactive row accessor; read it inside JSX props or effects, never destructure at the top level. The output is mounted into every row slot's back or front chrome container and re-used as slots are recycled (the row accessor updates reactively). Must be called synchronously from init, exactly once per layer; calling it multiple times for the same layer adds additional chrome without removing previous mounts. layer: "front" (default) renders in front of cards; "back" renders behind them.

GridRowsInternals.registerRowYOffset

Register a reactive per-row Y offset; the engine adds it to each row's target Y, and the per-row Y tween glides rows to the new pitch when the offset changes. Use it to open space between rows (e.g. a metadata block below the focused row).

Drive it from a reactive scope: read the plugin's own createMemo inside the provider so the engine re-lays-out when the offset changes. See RowYOffsetProvider for the purity requirement. Returns a dispose function; also disposed on plugin cleanup.

GridScrollInternals

Coordinates plugin animation with navigation, smooth scrolling and settling. Read scroll-state accessors inside effects or JSX. Register lifecycle callbacks synchronously in init; callbacks run on events rather than as reactive effects.

GridStore

Flat mutable data store for the grid.

• rows[rowIndex] holds the items for that row.
  • T[] → row has data, renders cells normally
  • undefined → row is loading; placeholder/skeleton shown; height preserved
  • [] → row has no items; collapses to zero height
• dirtyRows tracks which rows changed since the last engine tick.
• version is bumped on every mutation and drives the monolithic reactive memo.
• forceFullRelayout is set by setNumRows so the engine cannot take the
  data-only short-circuit until the next full layout pass clears it.

GridViewport

The grid's viewport, in the coordinates config.translation is given in.

HFocusStyleName

type HFocusStyleName = "fixedFocus" | "floatingFocus" | "fixedFocusWrap" | "zoomFocus";

HorizontalFocusAxisConfig

Horizontal focus axis: strategy plugin plus its tunables.

HorizontalScrollHooks

Horizontal scroll lifecycle callbacks that plugins can register.

HStrategyExtension

Partial override applied on top of a base horizontal focus strategy. Provide only the hooks you need; unmatched states delegate to the base.

HStrategyFocusContext

H Strategy Focus Context configuration and callbacks.

HStrategyMatcher

Returns true when an extension applies to the current focus state.

type HStrategyMatcher = (state: FocusState) => boolean;

HStrategyScrollContext

H Strategy Scroll Context configuration and callbacks.

InitGridPlugin

Registers custom grid chrome and behavior through GridPluginInternals.

Pass a plugin object in createFlexGrid({ plugins: [plugin] }). The grid reads static contributions (cellTemplate, reservedRowTop, wrapRowCards and provides) during construction, before the pool and row slots are created. It calls init once per mounted grid, in plugins array order, after creating the engine and navigation controller. engineReady() is still false during init and becomes true after all plugins have initialized.

Register layout and scroll hooks synchronously inside init, before the first layout pass. init returns nothing: returning a disposer does not register cleanup. Use onCleanup from @roku-sdk/solid for subscriptions, timers and disposers returned by registration or mounting methods. Effects created in init belong to the grid's reactive owner and stop when that owner is disposed. Mounted components also unmount with the grid. Calling a returned disposer removes that registration or mount earlier; register it with onCleanup when you want explicit teardown. Shared external pools remain caller-owned.

Capabilities describe behavior supplied by the complete plugin set, not permission to access internals. Declare ownership statically with provides; the grid collects all declarations before calling any init. Query internals.capabilities.has("focusVisual") to avoid duplicate focus chrome, regardless of plugin order. focusVisual is currently the only capability. A plugin querying its own declared capability also receives true. It does not enforce exclusive ownership: cooperating plugins decide whether to stand down.

Read accessors inside effects or JSX properties to track changes. Namespace objects are stable, but caching focus.row() in init captures only its initial value. This example draws an outline in content coordinates so it inherits scrolling; it adds any plugin-provided row offset to the highlight position.

Example

import { Rectangle } from "@roku-sdk/components";
import { onCleanup } from "@roku-sdk/solid";
import { createFlexGrid, fixedFocusStrategy, type InitGridPlugin } from "@roku-sdk/flex-grid";

const outline: InitGridPlugin<string> = {
    provides: ["focusVisual"],
    init(internals) {
        const { focus, rows, layers } = internals;
        const dispose = layers.mountScrollLayerContent("front", () => (
            <Rectangle
                translation={[
                    focus.highlightLocalX(),
                    focus.highlightLocalY() + rows.rowYOffset(focus.row())
                ]}
                width={focus.cellWidth()}
                height={4}
                color="0xffffffff"
            />
        ));
        onCleanup(dispose);
    }
};

const grid = createFlexGrid<string>({
    numRows: 1,
    numCols: 2,
    cellSize: [240, 160],
    width: 1280,
    height: 720,
    focus: {
        horizontal: { strategy: fixedFocusStrategy },
        vertical: { strategy: fixedFocusStrategy }
    },
    plugins: [outline],
    getCellComponent: () => () => <Rectangle width={240} height={160} />
});
grid.updateRows(0, [["One", "Two"]]);
// Render grid.element inside your app's reactive component.

KeyDelegate

KeyValue

A firmware key name as delivered by onKeyEvent(). Prefer the RemoteKey enum over string literals — its members are RCButton-aligned and its values are the runtime strings (notably RemoteKey.Select === "OK"). Plain strings remain assignable for forward compatibility with keys the enum does not name.

type KeyValue = RemoteKeyName;

PerfGridPlugin

Perf instrumentation plugin; discovered by kind before engine/pool creation.

type PerfGridPlugin = PerfPlugin;

PerfHandle

PerfPlugin

PluginCellTemplate

A cell template contributed by a plugin.

The grid folds these into cell routing ahead of the app's own getCellTemplateId, so the template gets a real pool key: nodes recycle per template and poolBuffer[id] warms them like any app template. Resolved before createPool, since the pool needs the component lookup at construction time.

PluginCellTemplate.matches

Decides whether this template owns a given cell. Called on every layout pass for every visible cell, so keep it cheap and free of side effects. Returning false defers to the next contributed template, and then to the app's getCellTemplateId.

row and col are the resolved data indices for the cell being laid out; col is the wrapped/virtualised column, matching the index used to read the item, so it is safe to route on. When several plugins contribute templates, the first match in plugins[] order wins.

PoolBufferConfig

Per-template pool warmup counts. Each key is a template ID; value is the number of nodes to pre-allocate.

type PoolBufferConfig = Record<string, number>;

PooledNodeVM

Reusable cell instance and setters supplied by a card pool to the grid.

PoolOps

PoolSizeResult

Deprecated.

Pool sizing is managed by the grid implementation. The root export will be removed in the next major version.

Position

A boundary of the grid. Reported by FlexGridConfigCore.onEdgeReached when the user was already at that boundary and pressed further, which is the usual cue to hand focus to a neighbouring region.

Member values are the raw strings the callback has always received, so Position.Top === "top".

PositionValue

The type FlexGridConfigCore.onEdgeReached reports, named separately for handlers that annotate their parameter. An alias of Position, so a received value works either way: edge === Position.Top and edge === "top" both compile and both match, and a handler annotated (edge: "top" | "bottom" | "left" | "right") stays assignable. The one direction that does not typecheck is passing a bare literal into a parameter of this type — use the member.

type PositionValue = Position;

RemoteKey

RCButton-aligned remote key names delivered by the firmware via onKeyEvent().

Enum member names follow the firmware RCButton identifiers. Enum values are the runtime key strings the app receives — NOT the ECP wire names used by tooling (e.g. ECP sends "Rev" but the app receives "rewind").

Note: Home is excluded because it is not delivered to the app.

Example

// Enum members (RCButton-aligned names):
onKey: { [RemoteKey.Select]: onPress(() => select()) }

// Legacy runtime string literals remain valid:
onKey: { OK: onPress(() => select()) }

RowCardsWrap

Wraps a row slot's cards in a plugin-owned node; the one place a plugin can put a node that is an ancestor of the cards, and so does not travel with the row's horizontal scroll.

Declared statically on the plugin, because row slots are allocated while the grid is constructed, before any init runs. Applied in plugins[] order, first entry outermost.

type RowCardsWrap = (context: RowCardsWrapContext) => JSX.Element;

RowCardsWrapContext

What RowCardsWrap is handed for one row slot.

RowYOffsetProvider

Extra Y (px) a plugin adds to a row's slot position, on top of its natural layout Y. Called for each row in the live window on every layout pass, and on each probe of the variable-row-height binary search, so it must be cheap.

Must be a pure function of (row, focusedRow) plus the plugin's own reactive reserve accessor. Reading any other grid signal (scroll position, column, ...) widens the dependency set of the row-window memos and the layout effect, causing extra relayouts.

type RowYOffsetProvider = (row: number, focusedRow: number) => number;

SmoothScrollConfig

TxCounts

VerticalFocusAxisConfig

Vertical focus axis: strategy plugin plus its tunables.

VerticalFocusOptions

Tunables for a vertical focus axis.

VerticalFocusState

State passed to vertical strategy functions on each focus update.

⚠️ This object is a shared mutable scratch instance reused across calls. Implementations must NOT retain a reference to it — read all needed values synchronously within the callback and discard the reference.

VerticalFocusStrategyPlugin

Customizes vertical scrolling and the focus highlight's screen position.

Set this object as focus.vertical.strategy; it is not an InitGridPlugin entry in plugins. Call geometry helpers with the same content coordinates used by the row accessors. Strategy state is reused by the engine, so consume it synchronously rather than retaining it. This strategy starts the focused row at the viewport top until the final rows need end-zone clamping.

Example

import type { VerticalFocusStrategyPlugin, VerticalFocusState,
    VerticalStrategyConfig } from "@roku-sdk/flex-grid";
import { computeScrollYForRow } from "@roku-sdk/flex-grid/geometry";

const rowY = (row: number, config: VerticalStrategyConfig) =>
    config.getRowY?.(row) ?? row * (config.rowPitch ?? 0);
const scrollY = (state: VerticalFocusState, config: VerticalStrategyConfig) =>
    computeScrollYForRow(state.row, {
        containerY: config.viewportTop ?? 0,
        viewportHeight: config.viewportHeight,
        numRows: state.numRows,
        getRowY: row => rowY(row, config),
        getRowHeight: row => config.getRowHeight?.(row) ?? config.rowPitch ?? 0
    });

const topAlignedStrategy: VerticalFocusStrategyPlugin = {
    name: "topAligned",
    computeScrollY: scrollY,
    computeFocusY: (state, config) => rowY(state.row, config) + scrollY(state, config)
};
// Pass { strategy: topAlignedStrategy } as focus.vertical.

VerticalScrollHooks

Vertical scroll lifecycle callbacks that plugins can register.

VerticalStrategyConfig

Layout geometry forwarded by the engine to vertical strategy methods on every call. Mirrors the role focus.horizontal.options plays for horizontal strategies.

VerticalStrategyConfig.focusOffset

Screen Y where the focused row is pinned (fixedFocusY) or top of grid (floatingFocusY).

Unlike the horizontal focusOffset, which is relative to the grid's container, this one is in the grid's parent space: the engine adds translation[1] before calling the strategy. That is because computeScrollY returns the scroll group's own Y translation, and the scroll group sits at translation[1] when unscrolled. Horizontally the scroll group stays at translation[0] and rows scroll inside it, so computeScrollX works relative to it. Changing either convention would break existing custom strategies, so viewportTop is passed instead to reconcile this value with viewportHeight.

VerticalStrategyConfig.viewportTop

Screen Y of the top of the viewport: the grid's own translation[1]. Defaults to 0, which is what an untranslated grid has and what a strategy written before this field existed effectively assumed.

focusOffset is in screen space and viewportHeight is a size, so a strategy needs this to put the two in one space — the space of the available room below the focus line is viewportTop + viewportHeight - focusOffset. Reading viewportHeight as if it were the bottom edge is what made a translated grid scroll its rows above its own clip rect and render blank.

VFocusStyleName

type VFocusStyleName = "fixedFocus" | "floatingFocus";