@kromatv/sdk 0.1.39-canary.3579809

package/types/ui/src/services/cast-lan.d.ts

@@ -0,0 +1,21 @@
+import type { DiscoveredTv, LanDiscoveryBridge } from '@kromatv/core';
+export interface LanCastOptions {
+    /** This device's DNS-SD stack, when it has one. Absent everywhere else, and
+     * everything below then reports nothing. */
+    lan?: LanDiscoveryBridge;
+    /** Gates on being signed in, like the roster it accelerates. */
+    enabled: boolean;
+    /** Called when a signed-in television is heard that the roster has not
+     * listed. The provider answers by refetching. */
+    onUnknownReceiver: () => void;
+    /** Whether the roster already knows a receiver id. Read at call time, so a
+     * roster change does not restart the browse. */
+    knowsReceiver: (receiverId: string) => boolean;
+}
+/** The signed-out televisions in the room, and a nudge to refetch when a
+ * signed-in one turns up that the server has not mentioned yet.
+ *
+ * Listens only while the app is in front: the browse is a multicast listener,
+ * and on Android a worker thread with it, so a phone in a pocket would
+ * otherwise pay for it for the whole signed-in session. */
+export declare function useLanCast(opts: LanCastOptions): DiscoveredTv[];

package/types/ui/src/services/cast-position.d.ts

@@ -0,0 +1,14 @@
+import type { CastReceiver } from '@kromatv/client/cast';
+/** What a receiver last reported, and when this sender heard it. */
+interface PositionBase {
+    id: string;
+    positionMs: number;
+    playing: boolean;
+    at: number;
+}
+/** Where the TV is *now*: what it last told us, plus the wall time since. The
+ * roster snapshot and the position event race, so the fresher of the two wins,
+ * and the result never runs past the title's own duration. */
+declare function livePosition(active: CastReceiver | null, base: PositionBase | null, playing: boolean): number;
+export type { PositionBase };
+export { livePosition };

package/types/ui/src/services/cast.d.ts

@@ -0,0 +1,20 @@
+import { type KromaClient } from '@kromatv/client';
+import type { LanDiscoveryBridge } from '@kromatv/core';
+import { type ReactNode } from 'react';
+export interface CastProviderProps {
+    /** Null while a shell is still resolving its session; treated as "not yet". */
+    client: KromaClient | null;
+    /** Gates everything on being signed in - the roster needs a session. */
+    enabled: boolean;
+    /** What this device calls itself on the TV's list of remotes ("iPhone",
+     * "Chrome"). Shown across the room, so it should be a thing, not a session id. */
+    deviceName: string;
+    /** This device's DNS-SD stack, when the shell has one. It makes a television
+     * appear the moment it is heard rather than on the next beat, and surfaces
+     * the ones with no account at all. */
+    lan?: LanDiscoveryBridge;
+    children: ReactNode;
+}
+export declare function CastProvider({ client, enabled, deviceName, lan, children, }: Readonly<CastProviderProps>): import("react").JSX.Element;
+export type { Cast, CastFailure } from './cast-context';
+export { useCast } from './cast-context';

package/types/ui/src/services/format.d.ts

@@ -0,0 +1,25 @@
+export interface Format {
+    /** A byte size in the locale's units: `1,5 Go` / `1.5 GB`. */
+    bytes: (bytes: number) => string;
+    /** A fixed-point number with the locale's separator. One decimal by default. */
+    decimal: (n: number, digits?: number) => string;
+    /** How long ago a timestamp was, in words, from an ISO string or epoch
+     *  milliseconds. Null reads as "never". */
+    elapsed: (at: string | number | null | undefined) => string;
+    /** A timestamp in full, date and time of day, for a log where "2 days ago"
+     *  would collapse rows a reader needs to tell apart. Null where there is no
+     *  readable timestamp, so a caller picks its own dash. */
+    stamp: (at: string | number | null | undefined) => string | null;
+    /** Uptime at the coarsest useful scale, from seconds. */
+    uptime: (seconds: number) => string;
+    /** Watch time to the minute, from milliseconds. */
+    duration: (ms: number) => string;
+    /** Hours with one decimal for a chart axis, from milliseconds. */
+    hours: (ms: number) => string;
+    /** A throughput figure, one decimal, no unit. */
+    mbps: (n: number) => string;
+    /** A scrub-bar timecode, from milliseconds. */
+    timecode: (ms: number) => string;
+}
+/** Every value formatter, bound to the locale on screen. */
+export declare function useFormat(): Format;

package/types/ui/src/services/i18n-instance.d.ts

@@ -0,0 +1,8 @@
+import type { I18n, Locale, Messages, Translate } from '@kromatv/i18n';
+/** An instance the kit's chrome can translate through, as `createI18n` builds
+ *  one. */
+export type KitI18n = I18n<Locale, Messages>;
+/** The standalone translator uses this repo's catalogs unless an instance is supplied. */
+export declare function translatorFor(locale: Locale, instance?: KitI18n): Translate;
+export declare function fallbackLocale(): Locale;
+export declare function providerI18n(): KitI18n;

package/types/ui/src/services/i18n-instance.published.d.ts

@@ -0,0 +1,8 @@
+import type { I18n, Locale, Messages, Translate } from '@kromatv/i18n';
+/** An instance the kit's chrome can translate through, as `createI18n` builds
+ *  one. `createI18n` is re-exported from this package, so a consumer needs no
+ *  other install to make one. */
+export type KitI18n = I18n<Locale, Messages>;
+export declare function translatorFor(locale: Locale, instance?: KitI18n): Translate;
+export declare function fallbackLocale(): Locale;
+export declare function providerI18n(): KitI18n | undefined;

package/types/ui/src/services/i18n.d.ts

@@ -0,0 +1,21 @@
+import type { Locale, Translate } from '@kromatv/i18n';
+import { type ReactNode } from 'react';
+import { type KitI18n } from './i18n-instance';
+export { useI18n, useLocale, useScopedT, useSetLocale, useT } from '@kromatv/i18n/react';
+export interface I18nProviderProps {
+    /** The instance owned by this app root; defaults to KROMA within this repo. */
+    i18n?: KitI18n;
+    locale: Locale;
+    onLocaleChange?: (locale: Locale) => void;
+    children: ReactNode;
+}
+export declare function I18nProvider({ i18n, locale, onLocaleChange, children, }: Readonly<I18nProviderProps>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+/** Like `useLocale`, but standing alone: outside an <I18nProvider> it is the
+ * default locale rather than a throw. What a kit component formatting a number
+ * reaches for, and the reason knowing the locale must not drag the catalogs in. */
+export declare function useLocaleDefault(): Locale;
+/** Like `useT`, but standing alone: outside an <I18nProvider> it speaks the
+ * default locale instead of throwing. For the kit's own chrome (an overlay
+ * backdrop's accessible name), which must not make the provider a mount
+ * requirement for every consumer of a dialog. */
+export declare function useTDefault(): Translate;

package/types/ui/src/services/locale.d.ts

@@ -0,0 +1,18 @@
+import { type KromaClient } from '@kromatv/client';
+import type { Locale } from '@kromatv/i18n';
+import { type ReactNode } from 'react';
+export interface LocaleProviderProps {
+    /** API client whose Accept-Language is kept in sync. Null before a server is reached. */
+    client: KromaClient | null;
+    /** The signed-in account's language preference, or null/undefined when signed out. */
+    accountLanguage?: string | null;
+    /** Persist a manual change to the signed-in account. Omit when signed out. */
+    onAccountChange?: (locale: Locale) => void;
+    /** Mirror the locale onto `<html lang>`. Every DOM target wants this, the
+     * browser TVs included: `lang` is what a set's screen reader reads to decide
+     * how to PRONOUNCE the interface. No-ops where there is no document, so a
+     * native target may pass it harmlessly. */
+    syncHtmlLang?: boolean;
+    children: ReactNode;
+}
+export declare function LocaleProvider({ client, accountLanguage, onAccountChange, syncHtmlLang, children, }: Readonly<LocaleProviderProps>): import("react").JSX.Element;

package/types/ui/src/services/playback.d.ts

@@ -0,0 +1,49 @@
+import { type KromaClient } from '@kromatv/client';
+import type { ItemId } from '@kromatv/client/media';
+import { type RefObject } from 'react';
+export interface PlaybackHeartbeatParams {
+    client: KromaClient;
+    /** Gates pinging (web: signed-in; TV: `client.hasAuth`). */
+    enabled: boolean;
+    itemId: ItemId;
+    durationMs: number | null;
+    /** Absolute current position in seconds (offset-aware on the web seamless stream). */
+    getPosition: () => number;
+    /** Absolute position the surface has buffered up to, in seconds, where it can
+     * say. Omitted from the ping when absent or undefined. */
+    getBuffered?: () => number | undefined;
+    /** The current transport state (`buffering` = playing but stalled/rebuffering). */
+    getState: () => 'playing' | 'paused' | 'buffering';
+    /** Label of the audio track the viewer has selected (omit → keep server default). */
+    getAudio?: () => string | undefined;
+    /** Label of the selected subtitle track, or an "off" label (omit → unchanged). */
+    getSubtitle?: () => string | undefined;
+    mode: 'direct' | 'remux' | 'transcode';
+    player: string;
+    device: string;
+    /** Base URL for the live-events stream (web: apiBase(); TV: client.baseUrl). */
+    eventsBaseUrl: string;
+    /** Where the event socket reads its bearer, when the shared in-memory session
+     * is not the right source. The TV keeps its bearer on its client (it is
+     * multi-server), so it passes that; web and phone leave this unset. Without it
+     * the TV's socket handshake carries no credential and is refused - which left
+     * the admin-stop event relying entirely on its 410-on-ping fallback. */
+    eventsToken?: () => string | undefined;
+    /** Session-id platform prefix, e.g. `'web'` | `'tv'`. */
+    idPrefix: string;
+    /** Fired the first time the session is terminated (admin stop, or a 410). */
+    onTerminated: (message: string) => void;
+    /** Element whose play/pause events trigger a prompt heartbeat (TV). */
+    videoRef?: RefObject<HTMLVideoElement | null>;
+    /** A value that, when it changes, triggers a prompt heartbeat (web passes its
+     * React `playing` state). Omit to rely solely on `videoRef`. */
+    pingSignal?: unknown;
+}
+/**
+ * A session id keys ONE row in the server's live "now playing" registry. It is
+ * never an auth token: `/playback/stop` only ends a session the requesting
+ * account owns, so the id needs uniqueness, not unpredictability. Clock plus a
+ * React-owned mount identity gives that on every target without sharing a
+ * counter between roots.
+ */
+export declare function usePlaybackHeartbeat(params: PlaybackHeartbeatParams): void;

package/types/ui/src/services/storyboard.d.ts

@@ -0,0 +1,33 @@
+import type { KromaClient } from '@kromatv/client';
+import type { ItemId } from '@kromatv/client/media';
+/**
+ * One preview tile, scaled to a requested display width, expressed as geometry
+ * rather than CSS `background-position`: React Native's `experimental_backgroundImage`
+ * takes gradients, not `url()`, so that spelling renders nothing on Apple TV.
+ */
+export interface StoryboardTile {
+    width: number;
+    height: number;
+    sheet: string;
+    /** The sheet's own pixel size - draw at this size and scale by `scale`; asking
+     *  the decoder for `sheetWidth * scale` pixels can exceed the GPU's texture
+     *  limit and the thumbnail comes out empty. */
+    sheetWidth: number;
+    sheetHeight: number;
+    /** Offset to bring this tile into the window (<= 0). */
+    offsetX: number;
+    offsetY: number;
+    /** Display size over source size: `width / tileW`. */
+    scale: number;
+}
+export interface Storyboard {
+    ready: boolean;
+    tile: (sec: number, displayW: number) => StoryboardTile | null;
+}
+/**
+ * Loads an item's scrub-bar storyboard for the seek preview. `generate: false`
+ * (dashboard thumbnails) does a single fetch and never awaits lazy generation.
+ */
+export declare function useStoryboard(client: KromaClient, itemId: ItemId, { generate }?: {
+    generate?: boolean;
+}): Storyboard;

package/types/ui/src/services/subtitleGenerations.d.ts

@@ -0,0 +1,13 @@
+import type { KromaClient } from '@kromatv/client';
+import type { ItemId } from '@kromatv/client/media';
+import type { GenerationId, SubtitleGeneration, SubtitleId } from '@kromatv/client/subtitles';
+export interface SubtitleGenerationsOptions {
+    active?: boolean;
+    onComplete: (subId: SubtitleId) => void;
+}
+export interface SubtitleGenerationsResult {
+    generations: SubtitleGeneration[];
+    cancel: (genId: GenerationId) => void;
+    refresh: () => void;
+}
+export declare function useSubtitleGenerations(client: KromaClient, itemId: ItemId, { active, onComplete }: SubtitleGenerationsOptions): SubtitleGenerationsResult;

package/types/ui/src/services/themeAudio.d.ts

@@ -0,0 +1,19 @@
+/** Same shape as the native half, so callers need no platform branch. */
+export interface ThemeAudio {
+    /** Whether a theme is available gates whether the mute toggle renders. */
+    active: boolean;
+    muted: boolean;
+    toggle: () => void;
+}
+/**
+ * Plex-style theme playback for a detail page: loops `themeUrl` at a low volume,
+ * fading in once it can play and fading out + stopping on unmount (i.e. when the
+ * user hits Play or navigates away).
+ *
+ * Browsers gate autoplay-with-sound behind a user gesture arriving on this page
+ * via a click usually satisfies that, and a one-shot pointer/key fallback covers
+ * the rest. The mute preference is persisted per device so it survives the trip
+ * between pages; React state mirrors it only for the toggle icon (kept SSR-safe
+ * by starting unmuted and syncing on mount).
+ */
+export declare function useThemeAudio(themeUrl: string | null | undefined): ThemeAudio;

package/types/ui/src/services/themeAudio.native.d.ts

@@ -0,0 +1,8 @@
+/** Same shape as the web half, so callers need no platform branch. */
+export interface ThemeAudio {
+    active: boolean;
+    muted: boolean;
+    toggle: () => void;
+}
+/** Loops `themeUrl` quietly, fading in once it can play and out on the way out. */
+export declare function useThemeAudio(themeUrl: string | null | undefined): ThemeAudio;

package/types/ui/src/ssr.d.ts

@@ -0,0 +1,22 @@
+type Fetch = (request: Request) => Response | Promise<Response>;
+/**
+ * Stamps the visitor's stored ground on `<html>` before the document leaves the
+ * server, so a page that will be light never paints dark first.
+ *
+ * `system` is left unstamped on purpose: the token sheet resolves it through
+ * `prefers-color-scheme`, live and without a line of script.
+ */
+export declare function withTheme(handler: Fetch): Fetch;
+/**
+ * Puts the kit's compiled stylesheet in the document the server sends, since
+ * react-native-web otherwise only injects its atomic CSS on hydration.
+ *
+ * The response is buffered rather than streamed: a recipe compiles on its first
+ * render, so the rules a page needs exist only after `</head>` would have been
+ * flushed. The element carries the WHOLE sheet under the id react-native-web
+ * looks for, or the client adopts an empty one and mints every rule again. It
+ * opens the head, ahead of the token sheet, so a compiled class outranks the
+ * reset react-native-web gives every view and text.
+ */
+export declare function withKitStyles(handler: Fetch): Fetch;
+export {};

package/types/ui/src/styles/css.d.ts

@@ -0,0 +1 @@
+export {};

package/types/ui/src/styles/motion.d.ts

@@ -0,0 +1,2 @@
+import { type SheetEntry } from './sheet.ts';
+export declare const MOTION: readonly SheetEntry[];

package/types/ui/src/styles/page.d.ts

@@ -0,0 +1,2 @@
+import { type SheetEntry } from './sheet.ts';
+export declare const PAGE: readonly SheetEntry[];

package/types/ui/src/styles/reset.d.ts

@@ -0,0 +1,2 @@
+import { type SheetEntry } from './sheet.ts';
+export declare const RESET: readonly SheetEntry[];

package/types/ui/src/styles/sheet.d.ts

@@ -0,0 +1,18 @@
+/** A declaration's value. A number is written verbatim, so a unit is a string. */
+type StyleValue = string | number;
+type Declarations = Readonly<Record<string, StyleValue>>;
+export interface StyleRule {
+    readonly select: readonly string[];
+    readonly declare: Declarations;
+}
+export interface GroupRule {
+    readonly at: string;
+    readonly rules: readonly StyleRule[];
+}
+export type SheetEntry = StyleRule | GroupRule;
+export declare const rule: (select: string | readonly string[], declare: Declarations) => StyleRule;
+export declare const atMedia: (query: string, rules: readonly StyleRule[]) => GroupRule;
+/** An animation, its steps written as rules whose selector is the offset. */
+export declare const keyframes: (name: string, steps: readonly StyleRule[]) => GroupRule;
+export declare const sheetCss: (entries: readonly SheetEntry[]) => string;
+export {};

package/types/ui/src/testing-input.d.ts

@@ -0,0 +1,17 @@
+import { type RenderHookOptions, type RenderHookResult, type RenderOptions, type RenderResult } from '@testing-library/react';
+import { type ComponentType, type ReactNode } from 'react';
+import { type InputGate } from './lib/input-gate';
+export type InputTestHost = InputGate & {
+    render(ui: ReactNode, options?: RenderOptions): RenderResult;
+    renderHook<Result, Props>(callback: (props: Props) => Result, options?: RenderHookOptions<Props>): RenderHookResult<Result, Props>;
+    inputGate: InputGate;
+    Host: ComponentType<{
+        children: ReactNode;
+    }>;
+};
+/** Bind test controls to the same real gate the rendered controls read. */
+export declare function createInputTestHost(options?: {
+    wrapper?: ComponentType<{
+        children?: ReactNode;
+    }>;
+}): InputTestHost;

package/types/ui/src/testing-style.d.ts

@@ -0,0 +1,47 @@
+import { type RenderHookOptions, type RenderHookResult, type RenderOptions, type RenderResult } from '@testing-library/react';
+import { type ReactNode } from 'react';
+import { currentBreakpoint as readCurrentBreakpoint } from './core/breakpoint';
+import { color as resolveColor } from './core/color';
+import { normalize as normalizeDecl } from './core/normalize';
+import { sv as defineRecipe } from './core/recipe';
+import { boxStyle as resolveBox, textStyle as resolveText } from './core/shorthand-resolve';
+import { type StyleRuntime, type StyleRuntimeOptions } from './core/style-runtime';
+import { sharedStyle as resolveSharedStyle, type Styles } from './core/styles';
+import { groundShade as shade, onPaper as paper } from './core/ground-shade';
+import { radiusValue as radius, scaledRadius as scaled } from './core/radius-value';
+import { themedCache as memoCache, themed as memoTheme } from './core/theme';
+import { type ThemeMode } from './core/theme-mode';
+import type { StyleDecl } from './core/types';
+export interface StyleTestHost {
+    runtime: StyleRuntime;
+    Host(props: Readonly<{
+        children?: ReactNode;
+    }>): ReactNode;
+    render(ui: ReactNode, options?: RenderOptions): RenderResult;
+    renderHook<Result, Props>(callback: (props: Props) => Result, options?: RenderHookOptions<Props>): RenderHookResult<Result, Props>;
+    setTheme: StyleRuntime['theme']['setTheme'];
+    applyTheme: StyleRuntime['theme']['applyTheme'];
+    activeTheme: StyleRuntime['theme']['activeTheme'];
+    themeVersion: StyleRuntime['theme']['themeVersion'];
+    onThemeChange: StyleRuntime['theme']['onThemeChange'];
+    pinDesignWidth: StyleRuntime['breakpoints']['pinDesignWidth'];
+    currentBreakpoint(): ReturnType<typeof readCurrentBreakpoint>;
+    breakpointIndex(): number;
+    styles<const S extends Record<string, StyleDecl>>(decls: S): Styles<S>;
+    sv: typeof defineRecipe;
+    color: typeof resolveColor;
+    normalize: typeof normalizeDecl;
+    boxStyle: typeof resolveBox;
+    textStyle: typeof resolveText;
+    sharedStyle: typeof resolveSharedStyle;
+    groundShade: typeof shade;
+    onPaper: typeof paper;
+    radiusValue: typeof radius;
+    scaledRadius: typeof scaled;
+    themed: typeof memoTheme;
+    themedCache: typeof memoCache;
+    applyMode(mode: ThemeMode): void;
+    writeMode(mode: ThemeMode): void;
+}
+/** A test owns the same style stores as its rendered root; no process-wide setters. */
+export declare function createStyleTestHost(options?: StyleRuntimeOptions): StyleTestHost;