@kromatv/sdk 0.1.40-canary.0

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

@@ -0,0 +1,122 @@
+import type { ImageStyle, TextStyle, ViewStyle } from 'react-native';
+import type { TextStyleProps } from '#ui/core/shorthand-resolve';
+import type { BoxStyleProps } from '#ui/core/shorthands';
+import type { SvState, SvStateName } from '#ui/core/states';
+import type { WebStyle } from '#ui/core/web-style';
+export type AnyStyle = ViewStyle & TextStyle & ImageStyle;
+/** What a painted slot accepts. A key both vocabularies name takes either
+ *  spelling: the shorthand adds to what React Native accepts, never subtracts,
+ *  so a slot handed a plain `TextStyle` is still a legal declaration. */
+declare const PAINTED: unique symbol;
+type Plain = Omit<AnyStyle, keyof BoxStyleProps | keyof WebStyle> & {
+    [K in keyof BoxStyleProps]?: BoxStyleProps[K] | (K extends keyof AnyStyle ? AnyStyle[K] : never) | (K extends keyof WebStyle ? WebStyle[K] : never);
+} & TextStyleProps & Omit<WebStyle, keyof BoxStyleProps>;
+/** A value stated per interaction state, `base` for the rest:
+ *  `bg: { base: 'accent', hover: 'accentHover' }`. */
+export type Conditional<V> = {
+    base?: V;
+} & {
+    [S in SvStateName]?: V;
+};
+export type StyleDecl = {
+    [K in keyof Plain]?: Plain[K] | Conditional<Plain[K]>;
+} & {
+    readonly [PAINTED]?: true;
+};
+export type Decl<T> = T & {
+    [K in SvStateName as `_${K}`]?: T;
+};
+/** The slots of a recipe and what each feeds, e.g.
+ *  `{ root: StyleDecl; icon: IconProps }`. Naming the props type is what makes a
+ *  typo in a glyph's colour a compile error. */
+export type SlotShapes = Record<string, object>;
+export interface HasRoot {
+    root: object;
+}
+export type Layer<P extends SlotShapes> = {
+    [K in keyof P]?: Decl<Partial<P[K]>>;
+};
+export type StyleSlots<S> = {
+    [K in keyof S]: StyleDecl;
+};
+export type VariantGroups<P extends SlotShapes> = Record<string, Record<string, Layer<P>>>;
+/**
+ * A group spelled `true`/`false` also accepts a real boolean, so a caller writes
+ * `active` rather than `active ? 'true' : 'false'`.
+ *
+ * Both spellings stay legal whichever options the group declares: one that names
+ * only `true` still has to take `false` from a caller, since the absent option
+ * is exactly what "off" resolves to.
+ */
+export type VariantPicks<V> = {
+    [K in keyof V]?: keyof V[K] extends 'true' | 'false' ? boolean | 'true' | 'false' : keyof V[K];
+};
+export interface CompoundVariant<V, L> {
+    when: VariantPicks<V>;
+    style: L;
+}
+export interface SvConfig<P extends SlotShapes, V extends VariantGroups<P>> {
+    slots: {
+        [K in keyof P]: Decl<P[K]>;
+    };
+    variants?: V;
+    compound?: readonly CompoundVariant<V, Layer<P>>[];
+    defaults?: VariantPicks<V>;
+}
+export type FlatLayer = Decl<Partial<StyleDecl>>;
+export type FlatVariantGroups = Record<string, Record<string, FlatLayer>>;
+/** The single-slot config. `base` is sugar for `slots: { root }` and lets every
+ *  layer drop the slot name; the result still comes back under `.root`. */
+export interface SvFlatConfig<V extends FlatVariantGroups> {
+    base: Decl<StyleDecl>;
+    variants?: V;
+    compound?: readonly CompoundVariant<V, FlatLayer>[];
+    defaults?: VariantPicks<V>;
+}
+type Out<T> = typeof PAINTED extends keyof T ? AnyStyle : T;
+export type Resolved<P extends SlotShapes> = {
+    readonly [K in keyof P]: Readonly<Out<P[K]>>;
+};
+export type SvFn<P extends SlotShapes, V> = ((variants?: VariantPicks<V>, state?: SvState) => Resolved<P>) & {
+    options: {
+        [K in keyof V]: (keyof V[K])[];
+    };
+    defaults: VariantPicks<V>;
+    slots: readonly (keyof P)[];
+};
+/**
+ * The variant props of a compiled recipe, cva-style:
+ *
+ *   interface ButtonProps extends VariantProps<typeof buttonVariants> { ... }
+ *
+ * Derived rather than retyped, so adding an option to the recipe updates every
+ * consumer's type with no second list to edit.
+ *
+ * A conditional with `infer`, not `Parameters<F>`: a function-typed constraint
+ * on `F` would make `Parameters` resolve against the constraint's `never`
+ * parameter rather than the recipe's own, and every option would collapse.
+ */
+export type VariantProps<F> = F extends (variants?: infer VP, state?: SvState) => unknown ? NonNullable<VP> : never;
+/** One group's option union, for the prop a component documents individually:
+ *  `Variant<typeof buttonVariants, 'size'>` is `'sm' | 'md' | 'lg' | 'tv'`. */
+export type Variant<F, G extends keyof VariantProps<F>> = NonNullable<VariantProps<F>[G]>;
+/** What the workbench reads to derive a story's controls, so the variant map is
+ *  the only source and there is no second list to keep in sync. */
+export interface VariantSource {
+    options: Record<string, readonly string[]>;
+    defaults: Record<string, PropertyKey | boolean | undefined>;
+}
+/**
+ * Any compiled recipe, for a component that takes one without knowing its slots.
+ *
+ * The parameter is `never` because a function is only assignable to another
+ * whose parameters are wider, and a recipe's own parameter is the narrow union
+ * of its option names. `root` is required: it is the slot a host component
+ * paints itself with, so a recipe without one is rejected where it is passed
+ * rather than painting nothing where it renders.
+ */
+export type AnySv = {
+    (variants?: never, state?: SvState): HasRoot & Record<string, object>;
+    slots: readonly string[];
+};
+export {};

package/types/ui/src/core/use-breakpoint.d.ts

@@ -0,0 +1,16 @@
+import type { BreakpointName } from '#ui/core/tokens';
+/**
+ * The active breakpoint, live: re-renders the caller when the surface crosses
+ * one. For a decision a style cannot carry - a different tree, a different
+ * number of rails. A declaration that only CHANGES with the breakpoint says so
+ * in the value (`px={{ base: 16, md: 40 }}`) and needs no hook.
+ */
+export declare function useBreakpoint(): BreakpointName;
+/**
+ * The breakpoint a declaration naming `mask` resolves at, live.
+ *
+ * Masked, so a crossing the declaration cannot see re-renders nobody, and
+ * mounted only by the responsive half of <Box> and <Text>: a call site with no
+ * breakpoint object subscribes to nothing.
+ */
+export declare function useBreakpointStep(mask: number): number;

package/types/ui/src/core/use-theme.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+import { type Theme } from './theme';
+/** The active theme, live: re-renders the caller when it swaps. For reading a
+ *  token a STYLE cannot carry (an ActivityIndicator's colour prop, a chart's
+ *  series paint). Declarations don't need it, they re-resolve by themselves. */
+export declare function useTheme(): Theme;
+/**
+ * Follows the operating system's ground for as long as the stored choice is
+ * `system`. Mount once, at the app root; a browser needs nothing here, since
+ * `prefers-color-scheme` answers it live in the token sheet.
+ */
+export declare function useSystemGround(): void;
+interface ThemeProviderProps {
+    theme?: Theme;
+    children?: ReactNode;
+}
+/**
+ * Applies `theme` and re-renders the subtree whenever the active theme changes.
+ *
+ * The re-render is a REMOUNT (the version is the key): resolved styles are read
+ * during render, so every themed node must render again, and a keyed fragment is
+ * the one mechanism that reaches children this component did not create. Theme
+ * swaps are rare and deliberate; place the provider under whatever state must
+ * survive one.
+ *
+ * There is exactly one active theme per app: this is a switch, not a scope, so
+ * providers do not nest.
+ */
+export declare function ThemeProvider({ theme, children }: Readonly<ThemeProviderProps>): import("react").FunctionComponentElement<import("react").FragmentProps>;
+export {};

package/types/ui/src/core/web-style.d.ts

@@ -0,0 +1,91 @@
+import type { ImageStyle, TextStyle, ViewStyle } from 'react-native';
+type Native = ViewStyle & TextStyle & ImageStyle;
+type Wide<K extends string, T = string> = Exclude<K extends keyof Native ? Native[K] : never, undefined> | T;
+/**
+ * Browser-only properties a declaration may state beside React Native's, and
+ * the native ones a browser also reads as free CSS text (`62vh`, a `var()`).
+ * A native renderer has no spelling for the former and ignores them; the
+ * browser renderer compiles both to classes as it does the rest.
+ */
+export interface WebStyle {
+    animationKeyframes?: string | Record<string, object> | ReadonlyArray<string | Record<string, object>>;
+    animationDuration?: string;
+    animationTimingFunction?: string;
+    animationDelay?: string;
+    animationFillMode?: string;
+    animationIterationCount?: string | number;
+    transitionProperty?: Wide<'transitionProperty'>;
+    transitionDuration?: Wide<'transitionDuration'>;
+    transitionTimingFunction?: Wide<'transitionTimingFunction'>;
+    transitionDelay?: Wide<'transitionDelay'>;
+    transition?: string;
+    textShadow?: string;
+    textUnderlineOffset?: number | string;
+    objectFit?: Wide<'objectFit', 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'>;
+    objectPosition?: string;
+    backgroundImage?: string;
+    backgroundPosition?: string;
+    backgroundSize?: string;
+    maskImage?: string;
+    WebkitMaskImage?: string;
+    backdropFilter?: string;
+    WebkitBackdropFilter?: string;
+    boxShadow?: Wide<'boxShadow'>;
+    willChange?: string;
+    cursor?: Wide<'cursor'>;
+    scrollbarWidth?: 'auto' | 'thin' | 'none';
+    touchAction?: string;
+    userSelect?: Wide<'userSelect', 'none' | 'text' | 'auto'>;
+    whiteSpace?: 'normal' | 'nowrap' | 'pre' | 'pre-wrap';
+    display?: Wide<'display', 'flex' | 'none' | 'block' | 'inline' | 'inline-flex' | 'grid' | 'contents'>;
+    position?: Wide<'position', 'absolute' | 'relative' | 'static' | 'fixed' | 'sticky'>;
+    overflowX?: 'visible' | 'hidden' | 'scroll' | 'auto';
+    overflowY?: 'visible' | 'hidden' | 'scroll' | 'auto';
+    inset?: Wide<'inset'>;
+    width?: Wide<'width'>;
+    height?: Wide<'height'>;
+    minWidth?: Wide<'minWidth'>;
+    minHeight?: Wide<'minHeight'>;
+    maxWidth?: Wide<'maxWidth'>;
+    maxHeight?: Wide<'maxHeight'>;
+    top?: Wide<'top'>;
+    right?: Wide<'right'>;
+    bottom?: Wide<'bottom'>;
+    left?: Wide<'left'>;
+    paddingLeft?: Wide<'paddingLeft'>;
+    paddingRight?: Wide<'paddingRight'>;
+    paddingTop?: Wide<'paddingTop'>;
+    paddingBottom?: Wide<'paddingBottom'>;
+    borderRadius?: Wide<'borderRadius'>;
+    borderBottomStyle?: 'solid' | 'dashed' | 'dotted' | 'none';
+    marginLeft?: Wide<'marginLeft'>;
+    marginRight?: Wide<'marginRight'>;
+    marginTop?: Wide<'marginTop'>;
+    marginBottom?: Wide<'marginBottom'>;
+    marginBlock?: Wide<'marginBlock'>;
+    marginInline?: Wide<'marginInline'>;
+    paddingBlock?: Wide<'paddingBlock'>;
+    paddingInline?: Wide<'paddingInline'>;
+    fontSize?: Wide<'fontSize'>;
+    lineHeight?: Wide<'lineHeight'>;
+    overflowAnchor?: 'auto' | 'none';
+    scrollPadding?: number | string;
+    wordBreak?: 'normal' | 'break-all' | 'keep-all' | 'break-word';
+    listStyleType?: 'none' | 'disc' | 'decimal';
+    letterSpacing?: Wide<'letterSpacing'>;
+    fontVariantNumeric?: string;
+    backgroundClip?: 'text' | 'border-box' | 'padding-box' | 'content-box';
+    WebkitBackgroundClip?: 'text' | 'border-box' | 'padding-box' | 'content-box';
+    margin?: Wide<'margin'>;
+    padding?: Wide<'padding'>;
+    accentColor?: string;
+    gridTemplateColumns?: string;
+    gridColumn?: string;
+    columnGap?: number | string;
+    rowGap?: number | string;
+    backgroundRepeat?: string;
+    outlineStyle?: Wide<'outlineStyle', 'none' | 'solid' | 'dashed' | 'dotted'>;
+    outlineColor?: Exclude<ViewStyle['outlineColor'] | TextStyle['outlineColor'], undefined> | string;
+    filter?: Exclude<ViewStyle['filter'], undefined> | string;
+}
+export {};

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

@@ -0,0 +1,20 @@
+export * from './components/organisms/player';
+export type { UseAiSuggestOptions, UseAiSuggestResult } from './services/aiSuggest';
+export { useAiSuggest } from './services/aiSuggest';
+export type { ActivateResult, AuthSession } from './services/auth';
+export { useAuthSession } from './services/auth';
+export type { Cast, CastProviderProps } from './services/cast';
+export { CastProvider, useCast } from './services/cast';
+export { type Format, useFormat } from './services/format';
+export type { I18nProviderProps } from './services/i18n';
+export { I18nProvider, useI18n, useLocale, useLocaleDefault, useScopedT, useSetLocale, useT, } from './services/i18n';
+export type { LocaleProviderProps } from './services/locale';
+export { LocaleProvider } from './services/locale';
+export type { PlaybackHeartbeatParams } from './services/playback';
+export { usePlaybackHeartbeat } from './services/playback';
+export type { Storyboard, StoryboardTile } from './services/storyboard';
+export { useStoryboard } from './services/storyboard';
+export type { SubtitleGenerationsOptions, SubtitleGenerationsResult, } from './services/subtitleGenerations';
+export { useSubtitleGenerations } from './services/subtitleGenerations';
+export type { ThemeAudio } from './services/themeAudio';
+export { useThemeAudio } from './services/themeAudio';

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

@@ -0,0 +1,74 @@
+export * from './components/atoms';
+export * from './components/common';
+export * from './components/molecules';
+export * from './components/organisms';
+export * from './components/templates';
+export type { AnySv, BoxStyleProps, Breakpoints, ColorValue, Resolved, Responsive, RingToken, StyleDecl, SvState, TextLayoutProps, Theme, ThemeMode, ThemeOverrides, ThemeTokens, Variant, VariantProps, VariantSource, } from './core';
+export { activeTheme, applyMode, applyTheme, boxStyle, color, createTheme, currentBreakpoint, groundShade, KROMA, KROMA_LIGHT, onPaper, onThemeChange, pinDesignWidth, readMode, registered, setTheme, sharedStyle, style, styles, sv, svFor, ThemeProvider, themed, themeVersion, useBreakpoint, useSystemGround, useTheme, writeMode, } from './core';
+export * from './core/tokens';
+export type { AnchorPlacement, AnchorRect, AnchorViewport } from './lib/anchor';
+export { placeUnder } from './lib/anchor';
+export type { ListKeysAt, PanelKeyEvent, PanelScroll } from './lib/anchored-keys';
+export { useListKeys, useRowInView } from './lib/anchored-keys';
+export { PANEL_BACKDROP, PANEL_SHELL, useAnchoredPlacement, useTriggerFocus, } from './lib/anchored-panel';
+export { classes } from './lib/classed';
+export type { Rect } from './lib/cover-rect';
+export { coverRect, parsePosition } from './lib/cover-rect';
+export { backdropBlur, bgPosition, bgSize, gradient, promote } from './lib/css';
+export { ARROW, HAND } from './lib/cursor';
+export { webDocument, webWindow } from './lib/dom';
+export { armEscapeGuard } from './lib/escape-guard';
+export type { ControlMetrics, ControlSize } from './lib/field-shell';
+export { CONTROL, controlMetrics, entryDefaultSize, setEntryDefaults } from './lib/field-shell';
+export { useFocusNav } from './lib/focus-nav';
+export type { FocusDirection, FocusOwner } from './lib/focus-platform';
+export { usePlatformFocus } from './lib/focus-platform';
+export { configureRemote, postRemoteDirection, useHardwareKeys } from './lib/focus-remote';
+export type { FocusScopeProps, ScreenScopeProps } from './lib/focus-scope';
+export { FocusColumn, FocusRegion, FocusScope } from './lib/focus-scope';
+export type { FocusScrollProps } from './lib/focus-scroll';
+export { FocusLine, FocusRail, FocusScroll, FocusSlot } from './lib/focus-scroll';
+export type { FocusNavHandlers } from './lib/focus-types';
+export { useFocusVisible } from './lib/focus-visible';
+export type { FieldErrors, Form, FormOptions, StandardSchemaV1, TextBinding, ToggleBinding, } from './lib/form';
+export { msg, useForm } from './lib/form';
+export { genreIcon } from './lib/genre-icon';
+export { DEFAULT_ICON_SIZE, DEFAULT_ICON_THICKNESS, hasGlyph, iconNames, } from './lib/glyph';
+export type { IconCatalog, IconEntry } from './lib/icon-catalog';
+export { iconCategories, iconEntry, setIconCatalog } from './lib/icon-catalog';
+export type { IconCatalogLoader } from './lib/icons/library';
+export { setIconCatalogLoader } from './lib/icons/library';
+export type { ImageBackend, ImageBackendProps } from './lib/image-backend';
+export { imageBackend, reactNativeImage, setImageBackend } from './lib/image-backend';
+export { clearInputHolds, holdInput, inputHeld } from './lib/input-gate';
+export { PageMain } from './lib/landmark';
+export type { LoopKind } from './lib/loop';
+export { useLoop } from './lib/loop';
+export { OverlayHost } from './lib/overlay-host';
+export type { PerfReport } from './lib/perf';
+export { perfReport, perfRunning, resetPerf, startPerf, stopPerf } from './lib/perf';
+export { Portal, PortalHost } from './lib/portal';
+export { armPressGuard, clearPressGuard, PRESS_GUARD_MS, pressGuardActive, } from './lib/press-guard';
+export type { ReportCategoryMeta } from './lib/report-categories';
+export { REPORT_CATEGORIES } from './lib/report-categories';
+export type { RingGeometry, RingProps } from './lib/ring';
+export { RING_ROTATION, ringGeometry } from './lib/ring';
+export { ringRoomBlock, ringRoomInline } from './lib/ring-room';
+export { RingScopeProvider } from './lib/ring-scope';
+export { useShake } from './lib/shake';
+export type { SlotProps } from './lib/slot';
+export { Slot } from './lib/slot';
+export { SORT_ICON } from './lib/sort-icon';
+export { useStableCallback } from './lib/stable-callback';
+export type { SurfacePresentation } from './lib/surface-presentation';
+export { setSurfacePresentation } from './lib/surface-presentation';
+export type { SurfaceWidth } from './lib/surface-shell';
+export { DIALOG_PAD, SURFACE_WIDTH } from './lib/surface-shell';
+export { SvgXml } from './lib/svg';
+export type { CopyState } from './lib/use-copy';
+export { useCopy } from './lib/use-copy';
+export type { GrowingCount } from './lib/use-growing-count';
+export { useGrowingCount } from './lib/use-growing-count';
+export { useSettledValue } from './lib/use-settled-value';
+export type { WheelSpin } from './lib/wheel-paths';
+export { KROMA_WHEEL_COLORS, KROMA_WHEEL_SEGMENTS, WHEEL_SPIN_MS, WHEEL_VIEWBOX, } from './lib/wheel-paths';

package/types/ui/src/lib/a11y-props.d.ts

@@ -0,0 +1,26 @@
+import type { AccessibilityState, AccessibilityValue } from 'react-native';
+/** What a control claims about itself. `pressed` is a toggle button's on state,
+ *  which ARIA spells `aria-pressed` and React Native does not have: its
+ *  platforms read `selected`, which VoiceOver and TalkBack both announce for a
+ *  control that is switched on. */
+export interface A11yFlags extends AccessibilityState {
+    pressed?: boolean;
+}
+/** Spread onto the control. Only one platform's half is ever filled in; the
+ *  type carries both because a caller compiles against whichever resolves. */
+export interface A11yProps {
+    accessibilityState?: AccessibilityState;
+    accessibilityValue?: AccessibilityValue;
+    'aria-busy'?: boolean;
+    /** Browser targets only: React Native has no equivalent claim. */
+    'aria-current'?: 'page' | 'step';
+    'aria-checked'?: boolean | 'mixed';
+    'aria-disabled'?: boolean;
+    'aria-expanded'?: boolean;
+    'aria-pressed'?: boolean;
+    'aria-selected'?: boolean;
+    'aria-valuemax'?: number;
+    'aria-valuemin'?: number;
+    'aria-valuenow'?: number;
+    'aria-valuetext'?: string;
+}

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

@@ -0,0 +1,8 @@
+import type { AccessibilityValue } from 'react-native';
+import type { A11yFlags, A11yProps } from './a11y-props';
+export type { A11yFlags, A11yProps };
+/** Spread onto the control that HAS the state, never onto a face inside it. */
+export declare function a11yState({ pressed, ...state }: A11yFlags): A11yProps;
+/** Spread onto an `adjustable` control: where its value sits in its range, and
+ *  optionally how to say that in words. */
+export declare function a11yValue(value: AccessibilityValue): A11yProps;

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

@@ -0,0 +1,32 @@
+/** A trigger's box, in viewport coordinates: what `getBoundingClientRect` and
+ *  `measureInWindow` both report. */
+export interface AnchorRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface AnchorViewport {
+    width: number;
+    height: number;
+}
+export interface AnchorPlacement {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+    width: number;
+    maxWidth?: number;
+    maxHeight: number;
+}
+export declare const ANCHOR_GAP = 6;
+/** `view` is null where nothing has been measured yet (a server render, a
+ *  target that reports no window): the panel then sits against the trigger
+ *  with nothing clamped. */
+export declare function placeUnder(trigger: AnchorRect, view: AnchorViewport | null, at: {
+    minWidth: number;
+    matchWidth?: boolean;
+    maxHeight: number;
+    align?: 'start' | 'end';
+    grow?: boolean;
+}): AnchorPlacement;

package/types/ui/src/lib/anchored-keys.d.ts

@@ -0,0 +1,41 @@
+import { type RefObject } from 'react';
+import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent, ScrollView } from 'react-native';
+export interface ListKeysAt {
+    count: number;
+    active: number;
+    setActive: (index: number) => void;
+    disabledAt?: (index: number) => boolean;
+    labelAt?: (index: number) => string;
+    onPick: (index: number) => void;
+    onClose: () => void;
+}
+export interface PanelKeyEvent {
+    nativeEvent: {
+        key: string;
+    };
+    preventDefault: () => void;
+    stopPropagation?: () => void;
+}
+/**
+ * The roving-highlight keyboard of the aria-activedescendant pattern: arrows
+ * move (skipping disabled rows), Home/End jump, Enter/Space pick, printable
+ * keys type ahead, Esc/Tab close - with the Escape keyup swallowed so a
+ * <Dialog> under the panel does not close with it.
+ */
+export declare function useListKeys(at: ListKeysAt): {
+    move: (from: number, delta: -1 | 1) => void;
+    onKeyDown: (event: PanelKeyEvent) => void;
+};
+export interface PanelScroll {
+    ref: RefObject<ScrollView | null>;
+    onLayout: (event: LayoutChangeEvent) => void;
+    onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+}
+/**
+ * Keeps the active row in sight as the keyboard walks a scrolling panel. Rows
+ * report their own box through `onRowLayout`; `scroll` goes on <AnchoredPopup>.
+ */
+export declare function useRowInView(active: number): {
+    scroll: PanelScroll;
+    onRowLayout: (index: number, y: number, height: number) => void;
+};

package/types/ui/src/lib/anchored-panel.d.ts

@@ -0,0 +1,42 @@
+import { type RefObject } from 'react';
+import { type AnchorPlacement } from '#ui/lib/anchor';
+import type { PanelKeyEvent } from '#ui/lib/anchored-keys';
+export declare const PANEL_BACKDROP: import("../core/types").AnyStyle;
+export declare const PANEL_SHELL: import("../core/types").AnyStyle;
+/**
+ * Where an anchored panel goes, kept current while it is open: re-placed when
+ * the window changes size, and on any scroll a browser reports (capture - the
+ * scroll that moves the trigger can happen in any container), coalesced to one
+ * measure per frame.
+ */
+export declare function useAnchoredPlacement(anchor: RefObject<unknown>, at: {
+    minWidth: number;
+    matchWidth?: boolean;
+    maxHeight: number;
+    align?: 'start' | 'end';
+    grow?: boolean;
+}): AnchorPlacement | null;
+/** Keeps the focus on the trigger for the panel's whole life: the trigger owns
+ *  the keyboard and names the active row, so a portalled panel never fights a
+ *  <Modal>'s focus trap for it. */
+export declare function useTriggerFocus(anchor: RefObject<unknown>): void;
+/** Takes the focus back, for a panel that outlives the press that moved it onto
+ *  a row: a pointer focuses what it presses, and the trigger owns the keyboard
+ *  for as long as the panel is open. */
+export declare function focusTrigger(anchor: RefObject<unknown>): void;
+/**
+ * Wires the trigger to a panel it does not contain: its keys reach the panel's
+ * keyboard, and `aria-controls`/`aria-haspopup` say what it opens. The trigger
+ * keeps the focus (see {@link useTriggerFocus}), so it is where the keys arrive.
+ *
+ * Browser targets only, since that is where a focus can be virtual; elsewhere
+ * the platform's own focus engine walks the rows.
+ */
+export declare function useTriggerKeys(anchor: RefObject<unknown>, at: {
+    listId: string;
+    haspopup: string;
+    onKeyDown: (event: PanelKeyEvent) => void;
+}): void;
+/** Names the active row on the trigger, which is what holds the focus. Browser
+ *  targets only, for the same reason as {@link useTriggerKeys}. */
+export declare function useActiveDescendant(anchor: RefObject<unknown>, rowId: string): void;

package/types/ui/src/lib/anchored-popup.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import { type Role } from 'react-native';
+import type { AnchorPlacement } from '#ui/lib/anchor';
+import type { PanelScroll } from '#ui/lib/anchored-keys';
+interface AnchoredPopupProps {
+    at: AnchorPlacement;
+    role: Role;
+    label: string | undefined;
+    multiselectable?: boolean;
+    listId: string;
+    onDismiss: () => void;
+    scroll?: PanelScroll;
+    children: ReactNode;
+}
+declare function AnchoredPopup({ at, role, label, multiselectable, listId, onDismiss, scroll, children, }: Readonly<AnchoredPopupProps>): import("react").JSX.Element;
+export type { AnchoredPopupProps };
+export { AnchoredPopup };

package/types/ui/src/lib/box-layers.d.ts

@@ -0,0 +1,10 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+/**
+ * One authored control style as the two views it has to drive on native.
+ * `box` is undefined when the style is pure paint, which is the common case and
+ * lets the caller leave the outer view unstyled.
+ */
+export declare function splitBoxLayers(style: StyleProp<ViewStyle>): {
+    box?: ViewStyle;
+    face: StyleProp<ViewStyle>;
+};

package/types/ui/src/lib/box-style.d.ts

@@ -0,0 +1,16 @@
+import { type ViewStyle } from 'react-native';
+import type { BoxStyleProps } from '#ui/core/shorthands';
+/**
+ * The same style, by identity, for the same shorthand props.
+ *
+ * `boxStyle` is pure but returns a fresh object every call, and on the browser
+ * targets that is the most expensive habit in the kit. styleq caches compiled
+ * styles in a WeakMap keyed on each leaf style OBJECT, so a new object per
+ * render per <Box> is a guaranteed miss for every box on the screen. Handing
+ * back the same object makes it a hit, and going through `StyleSheet.create`
+ * compiles it to atomic classes rather than re-walking the declarations.
+ *
+ * The engine's `sharedStyle` is the same thing for a declaration in the kit's
+ * own vocabulary; this one takes <Box>'s prop bag.
+ */
+export declare function sharedBoxStyle(key: string, p: Readonly<BoxStyleProps>): ViewStyle;

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

@@ -0,0 +1,8 @@
+export declare const BLINK_MS = 1100;
+export interface CaretProps {
+    height: number;
+    absolute?: boolean;
+}
+/** Blinks through `useLoop` - a CSS keyframe on the browser TVs - rather than
+ * paying a JS frame callback for as long as the field is on screen. */
+export declare function Caret({ height, absolute }: Readonly<CaretProps>): import("react").JSX.Element;

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

@@ -0,0 +1,3 @@
+type Layer = object | null | undefined | false;
+export declare function classes(...layers: Layer[]): string | undefined;
+export {};

package/types/ui/src/lib/cover-rect.d.ts

@@ -0,0 +1,26 @@
+/** A CSS position string (`'50% 28%'`, `'50%'`, `'center top'`) as fractions. */
+export declare function parsePosition(value: string): {
+    x: number;
+    y: number;
+};
+export interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * The rectangle to draw `source` at so it covers `box` with its focal point at
+ * `position`, mirroring `object-fit: cover` + `object-position`. Null when either
+ * size is not known yet, which callers treat as a plain centred cover.
+ */
+export declare function coverRect(box: {
+    width: number;
+    height: number;
+} | null, source: {
+    width: number;
+    height: number;
+} | null, position: {
+    x: number;
+    y: number;
+}): Rect | null;

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

@@ -0,0 +1,19 @@
+import type { ViewStyle } from 'react-native';
+export declare function gradient(css: string): ViewStyle;
+export declare function bgPosition(value: string): ViewStyle;
+export declare function bgSize(value: string): ViewStyle;
+/** A CSS `mask-image` value, and a NO-OP on native: React Native has no mask at
+ * any prefix, so a caller that wants a masked edge needs its own answer there
+ * (see `rail-edge.tsx`, which paints the page colour over the row instead). */
+export declare function maskImage(_css: string): ViewStyle;
+/** A CSS `backdrop-filter: blur(...)`, and a NO-OP on native: React Native has
+ * no backdrop filter at any prefix, and a platform blur view is a dependency the
+ * kit stays free of (old Tizen also composites blur on the CPU). */
+export declare function backdropBlur(_px: number): ViewStyle;
+/** A CSS `field-sizing: content`, and a NO-OP on native: React Native has no
+ * such property, so <TextArea> measures itself through `onContentSizeChange`. */
+export declare function fieldSizing(): ViewStyle;
+/** Promote a view to its own compositing layer; a no-op on native, where the OS
+ * compositor already decides layers. Use it only where measured - a promoted
+ * layer costs GPU memory. */
+export declare function promote(): ViewStyle;

package/types/ui/src/lib/css.web.d.ts

@@ -0,0 +1,25 @@
+import type { ViewStyle } from 'react-native';
+export declare function gradient(css: string): ViewStyle;
+export declare function bgPosition(value: string): ViewStyle;
+export declare function bgSize(value: string): ViewStyle;
+/** A CSS `mask-image` value, e.g. `linear-gradient(to right, transparent, #000 32px)`.
+ *  react-native-web writes it out with the `-webkit-` / `-moz-` / `-ms-` prefixes
+ *  as well, which is what makes it land on the 2019 WebKits the TV shells run.
+ *
+ *  A masked element ISOLATES its backdrop: every `backdrop-filter` beneath it
+ *  samples the mask's own layer instead of the page and renders as a flat wash.
+ *  Do not mask an ancestor of a <Frost>; see the table above. */
+export declare function maskImage(css: string): ViewStyle;
+/** A CSS `field-sizing: content`: the engine sizes the entry to its content, so
+ *  a growing textarea costs neither a measure nor a re-render. Chromium has it;
+ *  an older TV WebKit simply ignores it and the field keeps the height `rows`
+ *  gave it. See css.ts for the native half. */
+export declare function fieldSizing(): ViewStyle;
+/** Give this view its own GPU layer, so an animation near it does not force it
+ * to re-rasterize. `translateZ(0)` is the portable "own texture"; `willChange`
+ * keeps the layer alive between animations instead of paying to rebuild it. See
+ * css.ts for when this is worth it (and when it is not). */
+export declare function promote(): ViewStyle;
+/** A CSS `backdrop-filter: blur(Npx)`, with the `-webkit-` spelling alongside
+ * for the older TV WebKits. See css.ts for why native gets nothing. */
+export declare function backdropBlur(px: number): ViewStyle;