@kromatv/sdk 0.1.40-canary.0

package/types/ui/src/lib/cursor.d.ts

@@ -0,0 +1,17 @@
+import type { ViewStyle } from 'react-native';
+/** A control the pointer can press. */
+declare const HAND: ViewStyle;
+/** Stated rather than inherited: a face inside a group of controls, or a
+ *  control that is disabled, would otherwise wear the group's hand. */
+declare const ARROW: ViewStyle;
+export { ARROW, HAND };
+/** How a control's colours travel between rest, hover and focus.
+ *
+ * Only the painted properties: the press scale is an `Animated` transform and
+ * the focus ring is an outline, and both should land at once rather than ease.
+ * A hover that snaps reads as a redraw; the same swap over `motion.duration.fast`
+ * reads as the control answering the pointer. Web only, since that is where a
+ * pointer is, and stated here because React Native has no transition of its own.
+ */
+declare const COLOUR_MOTION: ViewStyle;
+export { COLOUR_MOTION };

package/types/ui/src/lib/dismiss-backdrop.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The press-anywhere-out-there way out of an overlay, for the surface to place
+ * behind its panel.
+ *
+ * Web only: on a TV, Back/Menu is the platform's way out and an extra Pressable
+ * is one more thing for the D-pad to land on. Draws nothing without `onPress`.
+ */
+declare function DismissBackdrop({ onPress }: Readonly<{
+    onPress?: () => void;
+}>): import("react").JSX.Element | null;
+export { DismissBackdrop };

package/types/ui/src/lib/dom.d.ts

@@ -0,0 +1,12 @@
+/** The DOM document, or null on a target that has none. */
+export declare function webDocument(): Document | null;
+/**
+ * The DOM window, or null on a target that has none.
+ *
+ * `typeof window === 'undefined'` is the guard most reach for, and it is WRONG
+ * here: React Native defines `window` as an alias of `global`, so the check
+ * passes and `window.addEventListener` throws as "not a function" instead of
+ * being absent. This asks the question that actually separates the two
+ * worlds: does this window carry the DOM event API?
+ */
+export declare function webWindow(): Window | null;

package/types/ui/src/lib/drag-select.d.ts

@@ -0,0 +1 @@
+export declare function suppressSelection(): () => void;

package/types/ui/src/lib/drag-select.web.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stops the browser selecting text and images while a drag is in flight, and
+ * returns the undo.
+ *
+ * It has to go on the DOCUMENT, not the dragged element: a pointer held down on
+ * a scrub bar and moved leaves that element immediately, and the selection it
+ * then paints belongs to whatever it crosses. Any range already caught by the
+ * press that started the drag is cleared too.
+ *
+ * `webkitUserSelect` as well as `userSelect`: the legacy TV tier is Chromium 53,
+ * which only knows the prefixed form.
+ */
+export declare function suppressSelection(): () => void;

package/types/ui/src/lib/ease.d.ts

@@ -0,0 +1,13 @@
+import { type EasingFunction } from 'react-native';
+import { motion } from '#ui/core/tokens';
+type Curve = keyof typeof motion.bezier;
+/** One curve in both dialects: `css` for react-native-web's transition props,
+ * `native` for `Animated.timing({ easing })`. */
+export interface Ease {
+    css: string;
+    native: EasingFunction;
+}
+/** The kit's easing curves. `out` is the settle every focus move and fade uses;
+ * `spring` overshoots, for the capsule that chases a finger. */
+export declare const ease: Record<Curve, Ease>;
+export {};

package/types/ui/src/lib/escape-guard.d.ts

@@ -0,0 +1 @@
+export declare function armEscapeGuard(): void;

package/types/ui/src/lib/expo-image-backend.d.ts

@@ -0,0 +1,5 @@
+import type { ImageBackend } from './image-backend';
+/** <Img>'s decoder on the Expo targets. Adds the memory + disk cache and the
+ *  list recycling React Native's own <Image> lacks, so a rail does not
+ *  re-download and re-decode every poster on every navigation. */
+export declare const expoImageBackend: ImageBackend;

package/types/ui/src/lib/field-shell.d.ts

@@ -0,0 +1,140 @@
+import type { TextStyle } from 'react-native';
+import { type ColorValue, type RadiusToken } from '#ui/core';
+type ControlSize = 'sm' | 'md' | 'tv';
+interface ControlMetrics {
+    /** The well's fill. Every control wears it: a filled segmented control
+     *  beside a transparent select is the difference that reads as "these are
+     *  two different kinds of thing".
+     *
+     *  Translucent, so a control over artwork (the sign-in screens over their
+     *  splash) takes a hint of what is behind it. Every control that wears this
+     *  fill also lays a <Frost> under it, so what shows through is BLURRED: the
+     *  hint is depth, not a legible picture, and a grid of keys still reads as
+     *  one surface rather than one colour per key. */
+    bg: `${ControlFill}`;
+    /** Corner, by NAME: a px number baked in here at module load would not follow
+     *  a theme. Use {@link controlRadius} where the number itself is needed. */
+    radius: RadiusToken;
+    px: number;
+    py: number;
+    /** The content row's height: what a control's own content measures. */
+    line: number;
+    /** The control's outer height: the number every control on a row targets,
+     *  whatever it is made of (an entry's padding, a button's label, a square
+     *  icon button). Derived: border + py + line + py + border. */
+    height: number;
+    fontSize: number;
+    /** Gap between a leading glyph, the content and a trailing slot. */
+    gap: number;
+}
+declare const CONTROL_FILL: 'surface2/72';
+type ControlFill = typeof CONTROL_FILL;
+/** The shape of every input, per size. Read it rather than re-deriving it:
+ *  this table IS the design. */
+export declare const CONTROL: Record<ControlSize, ControlMetrics>;
+/** A control's corner in px, against the ACTIVE theme. Read it at render time:
+ *  a value copied out at module load keeps the theme it was read under. */
+export declare function controlRadius(metrics: ControlMetrics): number;
+/**
+ * One slot table per size, built from {@link CONTROL} rather than transcribed.
+ * A control that changes shape with `size` writes the mapping ONCE and gets
+ * every size, so adding a size is an entry in the table above and nothing else.
+ * Before this, `sm` and `md` were hand-copied into five recipes and the
+ * fourth size would have been five more clones.
+ */
+export declare function bySize<T>(build: (metrics: ControlMetrics) => T): Record<ControlSize, T>;
+/**
+ * The face every KEY wears: the keypad's and the on-screen keyboard's alike.
+ * A keyboard and a keypad are the same object at two scales, so the well, the
+ * edge, the lift, the cursor wash and the amber under focus are declared here
+ * once; a copy in each component is how the two grids drifted into a solid
+ * amber fill on one and a tint on the other. Each grid still owns its own
+ * geometry (the keypad's 88x72, the keyboard's per-size box and corner).
+ *
+ * It lives here rather than beside either component because <Keypad> is a
+ * molecule and <Key> an organism, so neither may import the other, the same
+ * reason lib/group-shape.ts exists.
+ */
+export declare const keyFace: {
+    readonly root: {
+        readonly center: true;
+        readonly bg: "surface2/72";
+        readonly border: 'border';
+        readonly _hover: {
+            readonly bg: 'surface3';
+        };
+        readonly _focus: {
+            readonly bg: 'accentSoft';
+        };
+        readonly _press: {
+            readonly bg: 'accentSoftHover';
+            readonly border: 'accentHover';
+        };
+    };
+    readonly label: {
+        readonly color: 'text';
+        readonly fontWeight: '700';
+        readonly _focus: {
+            readonly color: 'accentText';
+        };
+    };
+    readonly glyph: {
+        readonly color: 'text';
+        readonly thickness: 1.8;
+        readonly _focus: {
+            readonly color: 'accentText';
+        };
+    };
+};
+/** The field's edge, which focus does NOT recolour: the ring outside it already
+ * says where the focus is, and an amber edge under an amber ring reads as two
+ * rings around one control. Invalid still speaks, since it says something the
+ * ring does not. */
+export declare function edgeColor(_focused: boolean, invalid: boolean): string;
+export declare function fieldRing(): TextStyle;
+/**
+ * What an entry paints for itself, and what it drops when the shell belongs to
+ * something else: the well of an <InputGroup>, the row of a command palette.
+ * A flattened entry that kept drawing its own fill, edge, corner and ring
+ * paints a second set of all four over the parent's, and its rounded rectangle
+ * shows through as the seam where the addons begin and end.
+ *
+ * Both <TextField> and <TextArea> read it, so the answer to "what does flat
+ * mean" is in one place rather than two that drift.
+ */
+export declare function fieldShell(metrics: ControlMetrics, at: Readonly<{
+    flat: boolean;
+    focused: boolean;
+    invalid: boolean;
+}>): {
+    box: Record<string, unknown>;
+    edge: TextStyle | null;
+};
+/** The ink of a field that has not been filled in, as a token rather than a
+ *  resolved colour: a value taken at module load keeps the ground it was read
+ *  under, which on a native light theme is near-white on cream. */
+export declare const PLACEHOLDER: ColorValue;
+/** Shell-level defaults for the kit's inputs. Call once at startup. */
+export declare function setEntryDefaults(defaults: Readonly<{
+    physicalKeyboard?: boolean;
+    size?: ControlSize;
+}>): void;
+export declare function entryDefaultPhysicalKeyboard(): boolean;
+export declare function entryDefaultSize(): ControlSize;
+/** The metrics for a size, defaulting to the shell's. */
+export declare function controlMetrics(size?: ControlSize): ControlMetrics;
+/** The smallest ink a real text entry may carry. Under it, iOS Safari zooms the
+ *  page to the field the moment it takes focus. */
+export declare const NO_ZOOM_FONT_SIZE = 16;
+/**
+ * A field's ink size, floored at {@link NO_ZOOM_FONT_SIZE} on a handset: the
+ * `sm` shell reads at 13.5, which is under iOS Safari's zoom threshold.
+ */
+export declare function useEntryFontSize(fontSize: number): number;
+/** Web only, and `none` rather than width 0: Chrome's own focus ring is
+ * `outline-style: auto`, which ignores the width - the field kept its blue
+ * browser ring inside the kit's amber one until the STYLE was cleared. React
+ * Native's types don't know `none` (native has no outline at all), hence the
+ * cast. */
+export declare const NO_OUTLINE: TextStyle;
+export type { ControlMetrics, ControlSize };

package/types/ui/src/lib/focus-entry.d.ts

@@ -0,0 +1,20 @@
+/** Something has the focus now. Called by every `<Focusable>` on focus. */
+declare function markFocusSettled(): void;
+/** True once this screen has a focus owner, so a late arrival must not steal it. */
+declare function focusSettled(): boolean;
+/** A new screen is deciding where to open. Called by `useFocusNav`. */
+declare function resetFocusEntry(): void;
+/**
+ * A fresh navigator scope has nothing focused yet, so its entry point wins.
+ * `<FocusScope>` calls this; every app root and every test render mounts one.
+ *
+ * Resets while the scope RENDERS, not in an effect: a child's mount effect is
+ * where an entry point asks for focus, and children's effects run before their
+ * parent's, so an effect here would arrive too late.
+ *
+ * `entryKey` is for a scope that OUTLIVES its screen - persistent chrome
+ * wrapping a swapping section, say - which must still re-decide focus on every
+ * arrival despite never remounting. Omit it and the scope behaves as before.
+ */
+declare function useFocusEntryScope(entryKey?: string | number): void;
+export { focusSettled, markFocusSettled, resetFocusEntry, useFocusEntryScope };

package/types/ui/src/lib/focus-here.d.ts

@@ -0,0 +1,11 @@
+/** The focused control's screen box, in the units the platform reports. */
+export interface FocusBox {
+    top: number;
+    left: number;
+    height: number;
+}
+/** Called by `<Focusable>` as it takes the focus. */
+export declare function noteFocus(_view: unknown): void;
+/** Bumped by every focus, so a caller can tell a move from a refusal. */
+export declare function focusSeq(): number;
+export declare function focusBox(): FocusBox | null;

package/types/ui/src/lib/focus-here.web.d.ts

@@ -0,0 +1,7 @@
+import type { FocusBox } from './focus-here';
+export type { FocusBox };
+/** Called by `<Focusable>` as it takes the focus. */
+export declare function noteFocus(view: unknown): void;
+/** Bumped by every focus, so a caller can tell a move from a refusal. */
+export declare function focusSeq(): number;
+export declare function focusBox(): FocusBox | null;

package/types/ui/src/lib/focus-lift.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode, type Ref } from 'react';
+import { type StyleProp, View, type ViewStyle } from 'react-native';
+type Report = (focused: boolean) => void;
+/** Report focus to the enclosing <FocusLift>; <Focusable> calls this. */
+export declare function useFocusLift(): Report | null;
+/** One layer clear of a sibling, the same step <Focusable> and <ButtonGroup>
+ *  use, so a control sitting in several of these cannot fight itself. */
+export declare const LIFTED: ViewStyle;
+/** The resting half of <LIFTED>, and never `null`: on Fabric a `zIndex` that
+ *  appears and disappears flattens and unflattens the native view under it, and
+ *  the mount operations aimed at the tag it just dropped are discarded
+ *  ("Unable to find viewState for tag"), which loses the row's layout. */
+export declare const GROUNDED: ViewStyle;
+/**
+ * Makes its subtree's focus visible to a container, so the container can lift
+ * ITSELF above its siblings while it holds the focus.
+ *
+ * Renders no element of its own, and that is the point: putting a wrapper view
+ * inside a flex row turns N children into one and collapses the row.
+ *
+ * ```tsx
+ * <FocusLiftHost>
+ *   {(held) => <View style={[style, held ? LIFTED : GROUNDED]}>{children}</View>}
+ * </FocusLiftHost>
+ * ```
+ */
+export declare function FocusLiftHost({ children }: Readonly<{
+    children: (held: boolean) => ReactNode;
+}>): import("react").JSX.Element;
+/**
+ * A view that rises above its siblings while anything inside it holds the
+ * focus, and reports the same edge to the container around it.
+ */
+export declare function FocusLiftView({ style, ref, children, }: Readonly<{
+    style?: StyleProp<ViewStyle>;
+    ref?: Ref<View>;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+export {};

package/types/ui/src/lib/focus-nav.d.ts

@@ -0,0 +1,3 @@
+import type { FocusNavHandlers } from './focus-types';
+declare function useFocusNav({ onBack, onPlayPause, resetKey }: FocusNavHandlers): void;
+export { useFocusNav };

package/types/ui/src/lib/focus-nav.web.d.ts

@@ -0,0 +1,2 @@
+import type { FocusNavHandlers } from './focus-types';
+export declare function useFocusNav({ onBack, onPlayPause, resetKey }: FocusNavHandlers): void;

package/types/ui/src/lib/focus-platform.d.ts

@@ -0,0 +1,30 @@
+/** Which engine holds the ring: the television's own, or the navigator. */
+type FocusOwner = 'platform' | 'app';
+/** A direction the navigator handled with nowhere to move. */
+type FocusDirection = 'up' | 'down' | 'left' | 'right';
+type EdgeHandler = (direction: FocusDirection) => void;
+interface PlatformFocusHost {
+    claim: (owner: FocusOwner | null) => void;
+    listen: (handler: EdgeHandler | null) => void;
+}
+/** Wrap a screen's children in this via <FocusScope>; never directly. */
+declare const PlatformFocusProvider: import("react").Provider<PlatformFocusHost | null>;
+/**
+ * Declared by a platform chrome drawn inside a scope. `owner` is who holds the
+ * television's focus right now, null while no chrome is up. `onEdge` hears the
+ * directions the navigator could not act on, which is how a chrome takes the
+ * focus back when the ring is already against its side of the screen.
+ */
+declare function usePlatformFocus(owner: FocusOwner | null, onEdge?: EdgeHandler): void;
+interface PlatformFocusState {
+    owner: FocusOwner | null;
+    /** For <NavigatorRoot>, whose directions are wider than the four a
+     *  chrome is told about. */
+    onEdge: (direction: string) => void;
+    host: PlatformFocusHost;
+}
+/** The <FocusScope> half: what the scope renders around, and the value it
+ * provides to whatever chrome is drawn inside it. */
+declare function usePlatformFocusHost(): PlatformFocusState;
+export type { FocusDirection, FocusOwner };
+export { PlatformFocusProvider, usePlatformFocus, usePlatformFocusHost };

package/types/ui/src/lib/focus-presence.d.ts

@@ -0,0 +1,5 @@
+/** Wrap a screen's children in this via <FocusScope>; never directly. */
+declare const FocusPresenceProvider: import("react").Provider<boolean>;
+/** True when a <FocusScope> (and so a navigator root) is above this component. */
+declare function useInsideFocusScope(): boolean;
+export { FocusPresenceProvider, useInsideFocusScope };

package/types/ui/src/lib/focus-remote.d.ts

@@ -0,0 +1,39 @@
+import type { RemoteKey } from '@kroma/core';
+import { type Direction } from '@kroma/spatial-nav';
+import { type NativeSyntheticEvent, type TVKeyEvent } from 'react-native';
+/** Call once at startup, before the first screen renders; a navigator mounted
+ * first never subscribes. Calling it twice is harmless. */
+export declare function configureRemote(): void;
+/**
+ * Posts a direction the app never heard as a press. One caller: a platform
+ * chrome that answered the press itself and is handing the focus over (see
+ * lib/focus-platform), where the navigator has to pick the ring up in the
+ * direction the viewer was already moving.
+ */
+export declare function postRemoteDirection(direction: Direction): void;
+/** Mounted by <FocusScope>. `on` lets a scope nested inside another opt out:
+ * this posts to EVERY registered navigator, so two live bridges would deliver
+ * each press twice. See <FocusScope>'s `bridge` prop. */
+export declare function useRemoteBridge(on?: boolean): void;
+/** Empty off Android, where `useTVEventHandler` above is the whole story. */
+export interface RemoteHostProps {
+    onKeyDown?: (event: NativeSyntheticEvent<TVKeyEvent>) => void;
+}
+/** Spread by <FocusRoot>. `on` takes <FocusScope>'s `bridge`: the key events
+ * BUBBLE, so a scope nested inside another must not carry a second host or one
+ * press walks the ring twice. */
+export declare function useRemoteHostProps(on?: boolean): RemoteHostProps;
+/**
+ * Delivers hardware-keyboard keystrokes (e.g. a Bluetooth keyboard on Android TV)
+ * to whoever is collecting text; directions are consumed above and never reach
+ * here. Deliberately not wired to the `physicalKeyboard` capability, which swaps
+ * in a native `TextInput` and would summon the platform IME over the on-screen
+ * keyboard the remote still needs.
+ */
+export declare function useHardwareKeys(handle: (key: string) => void): void;
+/**
+ * Delivers d-pad presses to a chrome driving its own virtual focus (the
+ * player): the Android mirror of the `useTVEventHandler` the player reads on
+ * tvOS. Same effect-event identity trick as {@link useHardwareKeys}.
+ */
+export declare function useRemoteKeys(handle: (key: RemoteKey) => void): void;

package/types/ui/src/lib/focus-remote.web.d.ts

@@ -0,0 +1,16 @@
+import { type Direction } from '@kroma/spatial-nav';
+export declare function configureRemote(): void;
+/**
+ * Posts a direction the app never heard as a press. One caller: a platform
+ * chrome that answered the press itself and is handing the focus over (see
+ * lib/focus-platform), where the navigator has to pick the ring up in the
+ * direction the viewer was already moving.
+ */
+export declare function postRemoteDirection(direction: Direction): void;
+/** Nothing to mount: the listener above is not tied to a screen. Kept so
+ * <FocusScope> can call it on every target. */
+export declare function useRemoteBridge(_on?: boolean): void;
+/** Nothing to subscribe to: a browser shell already reads its hardware keyboard
+ * from `document` (see @kroma/tv's `usePhysicalTyping`). Kept so the on-screen
+ * keyboard can call the same hook on every target. */
+export declare function useHardwareKeys(_handle: (key: string) => void): void;

package/types/ui/src/lib/focus-report.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+type Report = () => void;
+/** Called by `<Focusable>` when it takes the focus. */
+declare function useFocusReport(): Report | null;
+type ReporterProps = Readonly<{
+    children: ReactNode;
+} & ({
+    onFocus: Report;
+    index?: undefined;
+} | {
+    onFocus: (index: number) => void;
+    index: number;
+})>;
+/** Wrap one row item so its focus is reported without passing an index down.
+ *  With `index`, the handler is shared by every item and the reporter binds it,
+ *  so the context value stays put across re-renders of the row. */
+declare function FocusReporter(props: ReporterProps): import("react").JSX.Element;
+export { FocusReporter, useFocusReport };

package/types/ui/src/lib/focus-root.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface FocusRootProps {
+    children: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    /** Whether this navigator answers the remote at all. False for a scope that
+     *  is mounted but not in play - a parked sheet, say - whose nodes must stay
+     *  registered, in the order they registered, without taking presses meant for
+     *  something else. */
+    active?: boolean;
+    /** Whether to draw the key host below. False while a platform chrome owns the
+     *  television's focus, which is Apple TV's search screen and nothing else
+     *  (see focus-platform), and false wherever `bridge` is. */
+    keyHost?: boolean;
+    /** Whether this root carries the Android key transport. Default true; false
+     *  for a scope that reuses another root's, whose second host would deliver
+     *  each press again on the way up. See {@link ScreenScopeProps.bridge}. */
+    bridge?: boolean;
+    /** A direction the navigator handled with nothing to move to. */
+    onEdge?: (direction: string) => void;
+}
+export declare function FocusRoot({ children, style, active, keyHost, bridge, onEdge, }: Readonly<FocusRootProps>): import("react").JSX.Element;

package/types/ui/src/lib/focus-root.web.d.ts

@@ -0,0 +1,3 @@
+import type { FocusRootProps } from './focus-root';
+export type { FocusRootProps };
+export declare function FocusRoot({ children, active, onEdge }: Readonly<FocusRootProps>): import("react").JSX.Element;

package/types/ui/src/lib/focus-scope.d.ts

@@ -0,0 +1,59 @@
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+interface FocusScopeProps {
+    children: ReactNode;
+    /** Applied to the screen's own box; the web root renders no element (see focus-root). */
+    style?: StyleProp<ViewStyle>;
+}
+interface ScreenScopeProps extends FocusScopeProps {
+    /** Names the SCREEN inside a scope that outlives it (e.g. persistent nav
+     *  chrome), so it re-decides where focus opens on each arrival instead of on
+     *  its own mount. Omit for the usual case: one scope per screen. */
+    entryKey?: string | number;
+    /**
+     * Mount this scope's remote transports. Default true; a scope that reuses
+     * another root's passes `false`: the event bridge fans to every registered
+     * navigator, so a second one would deliver each press twice. An
+     * `<OverlayHost>` dialog reuses the screen's, a `<Modal>`-backed one is in
+     * its own view controller and needs its own. Reusing means leaving the
+     * platform focus behind as well; see {@link FocusRootProps.keyHost}.
+     */
+    bridge?: boolean;
+    /** Whether this scope answers the remote. See {@link FocusRootProps.active}. */
+    active?: boolean;
+}
+interface FocusColumnProps extends FocusScopeProps {
+    grid?: boolean;
+}
+/**
+ * Also what a DIALOG mounts, over the screen that opened it, paired with
+ * {@link useLockFocusBehind} on the screen: that locks the screen's navigator
+ * out of the remote, leaving this root the only one listening. Its
+ * `useFocusEntryScope` runs during render (not an effect) so the dialog's
+ * `autoFocus` claims the ring before the screen underneath decides; on the
+ * browser targets it also resets device-type to remote-keys mode regardless
+ * of where the pointer was left.
+ */
+declare function FocusScope({ children, style, entryKey, bridge, active, }: Readonly<ScreenScopeProps>): import("react").JSX.Element;
+/**
+ * Locks the navigator this component sits in out of the remote while `active`.
+ * Called from OUTSIDE the scope it protects, so it locks the screen rather
+ * than the dialog opened over it.
+ */
+declare function useLockFocusBehind(active: boolean): void;
+/**
+ * A group of controls that belong together on one line: the nav bar, a
+ * hero's buttons, a rail. The navigator moves between groups vertically and
+ * inside a group horizontally; nothing measures anything, the shape comes
+ * from the tree.
+ */
+declare function FocusRegion({ children, style }: Readonly<FocusScopeProps>): import("react").JSX.Element;
+/**
+ * A group of controls stacked one above the other: a list of servers, an
+ * on-screen keyboard. `grid` makes a stack of `<FocusRegion>` rows behave as a
+ * grid: without it, moving down lands on each row's last-focused key (Down
+ * from T lands on A); with it, the navigator keeps the column position.
+ */
+declare function FocusColumn({ children, style, grid }: Readonly<FocusColumnProps>): import("react").JSX.Element;
+export type { FocusColumnProps, FocusScopeProps, ScreenScopeProps };
+export { FocusColumn, FocusRegion, FocusScope, useLockFocusBehind };

package/types/ui/src/lib/focus-scroll.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode, type RefObject } from 'react';
+import { type StyleProp, type View, type ViewStyle } from 'react-native';
+type Anchor = RefObject<View | null>;
+interface PageMetrics {
+    top: number;
+    offsetFromStart: number;
+    viewport: number;
+    content: number;
+}
+declare function pageOffset({ top, offsetFromStart, viewport, content }: PageMetrics): number;
+interface NearestMetrics {
+    top: number;
+    size: number;
+    current: number;
+    margin: number;
+    viewport: number;
+    content: number;
+}
+/** The offset that shows a row whole with `margin` to spare, moving the page
+ *  only when the row is not already there. */
+declare function nearestOffset({ top, size, current, margin, viewport, content }: NearestMetrics): number;
+type Reveal = 'start' | 'nearest';
+interface FocusScrollProps {
+    children: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    contentStyle?: StyleProp<ViewStyle>;
+    /** Under `start`, where a revealed row rests below the top edge. Under
+     *  `nearest`, the room kept between the row and whichever edge it came in
+     *  from. */
+    offsetFromStart?: number;
+    /** `start` (the default) is a television's page: every revealed row comes to
+     *  rest at the same height. `nearest` is a list: the page moves only as far
+     *  as showing the row whole takes. */
+    reveal?: Reveal;
+}
+declare function FocusScroll(props: Readonly<FocusScrollProps>): import("react").JSX.Element;
+/**
+ * One rail, scrolled sideways by the focus. A rail inside a page leaves both
+ * live at once, and a control asks both (see {@link useRevealOnFocus}).
+ */
+declare function FocusRail(props: Readonly<FocusScrollProps>): import("react").JSX.Element;
+/**
+ * One row of a page: a place in the navigator's order fixed at first render
+ * (rows mount out of visual order), and what the page scrolls to.
+ */
+declare function FocusSlot({ children, onActive, }: Readonly<{
+    children: ReactNode;
+    onActive?: () => void;
+}>): import("react").JSX.Element;
+/**
+ * One line of a taller row, wrapped in a line-sized scroll anchor inside the
+ * slot: no navigator node, no change to the order, finer scroll granularity.
+ */
+declare function FocusLine({ children, style, }: Readonly<{
+    children: ReactNode;
+    style?: StyleProp<ViewStyle>;
+}>): import("react").JSX.Element;
+/**
+ * What a control uses to ask to be shown when it takes the focus: the page
+ * reveals its row (or the control when it is in none), the rail the control.
+ */
+declare function useRevealOnFocus(self: Anchor): () => void;
+/**
+ * The anchor of a row whose focus is a prop rather than the navigator's (a
+ * player panel's rows): the page reveals it the moment `focused` turns true.
+ */
+declare function useRevealWhenFocused(focused: boolean): Anchor;
+export type { Anchor, FocusScrollProps, NearestMetrics, PageMetrics, Reveal };
+export { FocusLine, FocusRail, FocusScroll, FocusSlot, nearestOffset, pageOffset, useRevealOnFocus, useRevealWhenFocused, };

package/types/ui/src/lib/focus-tab.d.ts

@@ -0,0 +1,12 @@
+import { type Direction } from '@kroma/spatial-nav';
+import type { FocusBox } from './focus-here';
+/** How the walk watches the focus: a counter to tell a move from a refusal, and
+ *  a box to tell one line from the next. */
+export interface FocusProbe {
+    seq: () => number;
+    box: () => FocusBox | null;
+}
+type Send = (direction: Direction) => void;
+/** Move the focus one control along reading order; `back` for Shift+Tab. */
+export declare function walkTab(send: Send, probe: FocusProbe, back?: boolean): void;
+export {};

package/types/ui/src/lib/focus-transition.d.ts

@@ -0,0 +1,11 @@
+import { type PressScale } from '#ui/lib/press-dip';
+/** An animated `transform: scale()` that eases to `to` while focused. */
+export declare function useFocusScale(focused: boolean, to: number): Record<string, unknown>;
+/**
+ * The design's press dip (`motion.pressScale`): the control shrinks under the
+ * finger, then springs back with a touch of overshoot on release. The touch
+ * half of the focus scale above - a phone PRESSES where a television FOCUSES -
+ * wired by the kit's pressable paths so every control answers the finger the
+ * same way.
+ */
+export declare function usePressScale(): PressScale;

package/types/ui/src/lib/focus-transition.web.d.ts

@@ -0,0 +1,3 @@
+import { type PressScale } from '#ui/lib/press-dip';
+export declare function useFocusScale(focused: boolean, to: number): Record<string, unknown>;
+export declare function usePressScale(): PressScale;

package/types/ui/src/lib/focus-types.d.ts

@@ -0,0 +1,18 @@
+export interface FocusNavHandlers {
+    /** Remote Back / Escape. Return `false` to say "not handled, keep the
+     *  default"; returning nothing counts as handled. */
+    onBack?: () => void | boolean;
+    /** Remote Play / Pause / PlayPause. */
+    onPlayPause?: () => void;
+    /** Re-run the mount behaviour when this changes (e.g. a view switch). */
+    resetKey?: unknown;
+}
+/** What a control that opts out of platform focus tells the PLATFORM focus
+ * engines: skip me. react-native-tvos gates a Pressable's focusability on
+ * exactly these two (`focusable !== false && isTVSelectable !== false`);
+ * `isTVSelectable` is the tvOS spelling and not in mainline RN's types - see
+ * components/organisms/player/lib/virtual-focus.ts for the bug this prevents. */
+export declare const UNFOCUSABLE: {
+    readonly focusable: false;
+    readonly isTVSelectable: false;
+};