@kromatv/sdk 0.1.40-canary.0

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

@@ -0,0 +1,21 @@
+/**
+ * Whether the current focus is one the viewer asked for, in the browser's
+ * `:focus-visible` sense: true for keys and the remote, false for a cursor that
+ * merely swept past.
+ *
+ * The spatial navigator focuses on mouse-enter once a pointer has moved and
+ * never blurs on leave, because its model keeps exactly one focus owner. Without
+ * this the amber ring parks on whatever the cursor passed last.
+ *
+ * `focus` identifies WHAT holds the focus, not merely that something does: a
+ * cluster whose selection moves between its own controls has to re-read the
+ * modality on every move, so passing a boolean there would answer for the first
+ * control and never again. A boolean is right where the control is its own
+ * focus owner.
+ *
+ * `<Focusable>` applies this to its ring and to a recipe's `_focus`. Anything
+ * resolving a recipe directly (a control whose focus visuals live on a parent,
+ * or on a `<Box>` that is not itself focusable) must ask here too, or `_focus`
+ * would mean two different things depending on how it was reached.
+ */
+export declare function useFocusVisible(focus: unknown): boolean;

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

@@ -0,0 +1,4 @@
+export { msg } from './message';
+export type { StandardSchemaV1 } from './standard-schema';
+export type { FieldErrors, Form, FormOptions, TextBinding, ToggleBinding } from './use-form';
+export { useForm } from './use-form';

package/types/ui/src/lib/form/message.d.ts

@@ -0,0 +1,10 @@
+import { type TVars } from '@kroma/i18n';
+type MessageLookup = (key: string, vars?: TVars) => string;
+/** Packs a message key and its interpolation vars into the single string a validator
+ *  can carry as its error, for `useForm` to unpack again through `t`. */
+declare function msg(key: string, vars?: TVars): string;
+/** Turns a validator's message into display copy: a catalog key when `t` knows it,
+ *  otherwise the message itself, and either way with `msg()`'s vars filled in. */
+declare function resolveMessage(message: string, t?: MessageLookup): string;
+export type { MessageLookup };
+export { msg, resolveMessage };

package/types/ui/src/lib/form/standard-schema.d.ts

@@ -0,0 +1,27 @@
+type StandardPathSegment = PropertyKey | {
+    readonly key: PropertyKey;
+};
+interface StandardIssue {
+    readonly message: string;
+    readonly path?: readonly StandardPathSegment[];
+}
+interface StandardResult<Output> {
+    readonly value?: Output;
+    readonly issues?: readonly StandardIssue[];
+}
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+/** The first path segment of an issue, which is the field it belongs to. A whole-object
+ *  check (zod's `.refine()` on the object) has no path and belongs to the form itself. */
+declare function issueField(issue: StandardIssue): string | undefined;
+export type { StandardIssue, StandardSchemaV1 };
+export { issueField };

package/types/ui/src/lib/form/use-form.d.ts

@@ -0,0 +1,59 @@
+import type { Translate } from '@kroma/core';
+import { type StandardSchemaV1 } from './standard-schema';
+type StringKeys<V> = {
+    [K in keyof V]-?: V[K] extends string ? K : never;
+}[keyof V] & string;
+type BooleanKeys<V> = {
+    [K in keyof V]-?: V[K] extends boolean ? K : never;
+}[keyof V] & string;
+type FieldErrors<V> = Partial<Record<keyof V & string, string>>;
+interface TextBinding<T> {
+    /** Spread onto `<Field.Root>`: the value it holds and the message it shows. */
+    root: {
+        value: T;
+        onValueChange: (next: T) => void;
+        error: string | undefined;
+    };
+    /** Spread onto `<Field.Input>` or `<Field.Textarea>`: the return key submits. */
+    input: {
+        onSubmit: () => void;
+    };
+}
+interface ToggleBinding<T> {
+    checked: T;
+    onCheckedChange: (next: T) => void;
+}
+interface FormOptions<Values, Output> {
+    schema: StandardSchemaV1<Values, Output>;
+    defaultValues: Values;
+    onSubmit?: (values: Output) => void | Promise<void>;
+    /** Without one a message is shown as the schema wrote it; with one it is looked
+     *  up as a catalog key first. Pass `useT()`. */
+    t?: Translate;
+}
+interface Form<Values> {
+    values: Values;
+    errors: FieldErrors<Values>;
+    /** A whole-form failure: a check with no field to blame, or a throw from `onSubmit`. */
+    error: string | undefined;
+    submitting: boolean;
+    submitted: boolean;
+    field: <K extends StringKeys<Values>>(name: K) => TextBinding<Values[K]>;
+    toggle: <K extends BooleanKeys<Values>>(name: K) => ToggleBinding<Values[K]>;
+    setValue: <K extends keyof Values & string>(name: K, next: Values[K]) => void;
+    setError: (name: keyof Values & string, message?: string) => void;
+    reset: (next?: Partial<Values>) => void;
+    submit: () => Promise<void>;
+}
+/**
+ * A form over any Standard Schema validator (zod, valibot, arktype): it holds the
+ * values, runs the schema and hands each control the props it needs, so a screen
+ * writes the schema and the layout and nothing in between.
+ *
+ * Errors stay quiet until the first submit, then track every keystroke. Each one
+ * is resolved through `t`, so a schema that says `msg('form.tooShort', { min: 8 })`
+ * is translated wherever it is shown.
+ */
+declare function useForm<Values extends Record<string, unknown>, Output>({ schema, defaultValues, onSubmit, t, }: FormOptions<Values, Output>): Form<Values>;
+export type { FieldErrors, Form, FormOptions, TextBinding, ToggleBinding };
+export { useForm };

package/types/ui/src/lib/fuzzy-search.d.ts

@@ -0,0 +1,20 @@
+/** The query as the matcher reads it: lower-cased, with the separators dropped.
+ * Empty means there is nothing to match on, and everything is a hit. */
+declare function fuzzyQuery(query: string): string;
+/** How well `query` matches `text`, higher being better, or `null` when the
+ * query's letters are not all present in order. Separators in the query are
+ * ignored, so `player pause` scores as `playerpause` does. An empty query
+ * scores 0 against anything. */
+declare function fuzzyScore(text: string, query: string): number | null;
+/** One candidate the query matched, and how well. */
+interface FuzzyHit<T extends string> {
+    text: T;
+    score: number;
+}
+/** The candidates `query` matches, best first: a contiguous run, a match on a
+ * word boundary and a match nearer the start all score higher. A tie goes to
+ * the shorter candidate, then to the order given. An empty query returns every
+ * candidate in the order given, each scoring 0. */
+declare function fuzzySearch<T extends string>(candidates: readonly T[], query: string): FuzzyHit<T>[];
+export type { FuzzyHit };
+export { fuzzyQuery, fuzzyScore, fuzzySearch };

package/types/ui/src/lib/genre-icon.d.ts

@@ -0,0 +1,4 @@
+import { type IconName } from '#ui/lib/glyph';
+/** The icon for a genre, or `undefined` when the table has none for it, or the
+ * build's glyph subset does not ship the one it names. */
+export declare function genreIcon(name: string): IconName | undefined;

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

@@ -0,0 +1,24 @@
+import type { ColorToken } from '#ui/core/tokens';
+import { type Glyph, type IconName } from '#ui/lib/icons/glyphs';
+export type { Glyph, IconName } from '#ui/lib/icons/glyphs';
+export { hasGlyph, iconNames } from '#ui/lib/icons/glyphs';
+export interface IconProps {
+    name: IconName;
+    size?: number;
+    /** Explicit because React Native has no `currentColor` to inherit. */
+    color?: ColorToken | (string & {});
+    /** Outline weight in px, constant across sizes. Defaults to 2. */
+    thickness?: number;
+}
+export interface ResolvedIcon {
+    Glyph: Glyph;
+    size: number;
+    /** Always OPAQUE; any alpha the token carried is in `opacity`. */
+    color: string;
+    /** A custom property where the ground decides the alpha (see `CSS_FADED`). */
+    opacity: number | string;
+    thickness: number;
+}
+export declare const DEFAULT_ICON_SIZE = 24;
+export declare const DEFAULT_ICON_THICKNESS = 2;
+export declare function resolveIcon({ name, size, color, thickness, }: Readonly<IconProps>): ResolvedIcon;

package/types/ui/src/lib/group-shape.d.ts

@@ -0,0 +1,44 @@
+import type { ViewStyle } from 'react-native';
+import type { ControlSize } from '#ui/lib/field-shell';
+type GroupOrientation = 'horizontal' | 'vertical';
+type GroupPosition = 'only' | 'first' | 'middle' | 'last';
+interface GroupSlot {
+    orientation: GroupOrientation;
+    position: GroupPosition;
+    radius: number;
+    size: ControlSize;
+}
+interface GroupMember {
+    grouped: boolean;
+    style: ViewStyle | null;
+    size: ControlSize | null;
+    onFocus: () => void;
+    onBlur: () => void;
+}
+declare const GroupSlotContext: import("react").Context<GroupSlot | null>;
+/** The same slot object for the same values, so a group hands a child a context
+ *  value whose identity survives the group's own re-render. */
+declare function groupSlot(orientation: GroupOrientation, position: GroupPosition, radius: number, size: ControlSize): GroupSlot;
+/** What the surrounding <ButtonGroup> published for this child, or null outside
+ *  one. For a part that needs more than the shape: a separator's axis, a size to
+ *  fall back on. */
+declare function useGroupSlot(): GroupSlot | null;
+/**
+ * The style a member of a <ButtonGroup> applies to its own root: the corners its
+ * position keeps, and the leading border zeroed so it shares one line with the
+ * member before it rather than stacking a second against it.
+ *
+ * Null outside a group, so a control that does not read this hook simply keeps
+ * its own shape. Pass `focused` to lift the member over its neighbours for as
+ * long as it wears the ring.
+ */
+declare function useGroupShape(focused?: boolean): ViewStyle | null;
+/**
+ * `useGroupShape` for a control that takes focus: the same style, the size the
+ * group falls back to, and focus handlers that lift the control while it is
+ * focused. The handlers compose the caller's own; outside a group they touch no
+ * state, so an ungrouped control still does not re-render when focus arrives.
+ */
+declare function useGroupMember(onFocus?: () => void, onBlur?: () => void): GroupMember;
+export type { GroupMember, GroupOrientation, GroupPosition, GroupSlot };
+export { GroupSlotContext, groupSlot, useGroupMember, useGroupShape, useGroupSlot };

package/types/ui/src/lib/hover-passthrough.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Keep this control's hover from cancelling its ancestors'. Returns a ref to put
+ * on the host: a CALLBACK ref, not an effect, because <Focusable> swaps its host
+ * element when it is disabled, and an effect keyed on the ref object would bind
+ * once to whatever the first commit happened to hold.
+ *
+ * Web-only, and inert everywhere else: React Native has no such event.
+ */
+export declare function useHoverPassthrough<T>(): (node: T | null) => void;

package/types/ui/src/lib/icon-catalog.d.ts

@@ -0,0 +1,19 @@
+/** One glyph's place in Tabler's own catalogue. */
+interface IconEntry {
+    category: string;
+    tags: readonly string[];
+}
+/** Tabler's entries, keyed by Tabler's own glyph name. */
+type IconCatalog = Readonly<Record<string, IconEntry>>;
+/** Loads the catalogue the icon browser reads. A workbench calls this once at
+ * startup; everywhere else it is never called and every lookup answers `null`. */
+declare function setIconCatalog(catalog: IconCatalog): void;
+/** Tabler's entry for a glyph. A `-filled` variant inherits its base glyph's
+ * entry, since the catalogue lists only the outline. `null` when the catalogue
+ * is not loaded, or for the few names Tabler has since renamed. */
+declare function iconEntry(name: string): IconEntry | null;
+/** Every category in the catalogue, sorted. Empty when it is not loaded, which
+ * is what a caller checks to know whether to offer the filter at all. */
+declare function iconCategories(): readonly string[];
+export type { IconCatalog, IconEntry };
+export { iconCategories, iconEntry, setIconCatalog };

package/types/ui/src/lib/icon-search.d.ts

@@ -0,0 +1,18 @@
+/** A glyph the query reached, and the tags that carried it there - empty when
+ * the name itself matched. */
+interface IconHit<T extends string> {
+    name: T;
+    tags: readonly string[];
+}
+interface IconSearchOptions {
+    /** One of `iconCategories()`; absent searches every category. */
+    category?: string;
+}
+/**
+ * The glyphs a query reaches, best first: the ones whose NAME it matches, and
+ * the ones only a TAG matched, merged by how well each matched. Tags need the
+ * catalogue (`setIconCatalog`); without it this is the name search alone.
+ */
+declare function searchIcons<T extends string>(names: readonly T[], query: string, { category }?: IconSearchOptions): IconHit<T>[];
+export type { IconHit, IconSearchOptions };
+export { searchIcons };

package/types/ui/src/lib/icons/every-glyph.d.ts

@@ -0,0 +1,4 @@
+import type { GlyphExports } from './glyphs';
+/** All of Tabler, fetched on demand. Null where the platform cannot fetch. */
+declare const everyGlyph: (() => Promise<GlyphExports>) | null;
+export { everyGlyph };

package/types/ui/src/lib/icons/every-glyph.web.d.ts

@@ -0,0 +1,4 @@
+import type { GlyphExports } from './glyphs';
+/** All of Tabler, fetched on demand. Null where the platform cannot fetch. */
+declare const everyGlyph: (() => Promise<GlyphExports>) | null;
+export { everyGlyph };

package/types/ui/src/lib/icons/glyph-source.d.ts

@@ -0,0 +1,3 @@
+import * as Tabler from '@tabler/icons-react-native';
+export declare const FALLBACK: Tabler.Icon;
+export * as EXPORTS from '@tabler/icons-react-native';

package/types/ui/src/lib/icons/glyphs.d.ts

@@ -0,0 +1,34 @@
+import type * as Tabler from '@tabler/icons-react-native';
+import type { ComponentType } from 'react';
+import { FALLBACK } from './glyph-source';
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type IsUpper<C extends string> = C extends Lowercase<C> ? false : true;
+type NeedsDash<Prev extends string, C extends string> = Prev extends '' ? false : IsUpper<C> extends true ? IsUpper<Prev> extends true ? false : true : C extends Digit ? Prev extends Digit ? false : true : false;
+type Kebab<S extends string, Prev extends string = '', Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? Kebab<Rest, C, `${Acc}${NeedsDash<Prev, C> extends true ? '-' : ''}${Lowercase<C>}`> : Acc;
+type IconExport = Extract<keyof typeof Tabler, `Icon${string}`>;
+type Glyph = ComponentType<{
+    size?: number;
+    color?: string;
+    style?: object;
+    className?: string;
+}>;
+/** Glyphs keyed by Tabler's own export name (`IconWaveSine`): a namespace of the
+ * package, or any part of one. */
+type GlyphExports = Readonly<Record<string, unknown>>;
+/** Every glyph name the kit can draw, in the design's own spelling. Strict:
+ * a typo fails to compile; a name from data crosses in through `hasGlyph`. */
+type IconName = IconExport extends `Icon${infer Rest}` ? Kebab<Rest> : never;
+declare function exportName(slug: string): string;
+/** Takes a plain `string`: an unknown name gets the fallback rather than an exception. */
+declare function glyphFor(name: string): Glyph;
+declare function hasGlyph(name: string): name is IconName;
+/** Two boundaries: lower-to-upper, and letter-to-digit (`IconVolume2` -> `volume-2`).
+ * A digit followed by a letter stays joined (`IconBadge4k`). */
+declare function slugOf(name: string): string;
+declare function iconNames(): IconName[];
+/** Widens the set every lookup here answers from, past the glyphs the build
+ * kept. Only a workbench browsing all of Tabler fetches them: see
+ * `lib/icons/library`. */
+declare function addGlyphs(more: GlyphExports): void;
+export type { Glyph, GlyphExports, IconName };
+export { addGlyphs, exportName, FALLBACK, glyphFor, hasGlyph, iconNames, slugOf };

package/types/ui/src/lib/icons/library.d.ts

@@ -0,0 +1,19 @@
+import { type IconCatalog } from '#ui/lib/icon-catalog';
+/** Fetches Tabler's categories and tags. Only a workbench has them: they are
+ * read at build time by `kromaIconCatalog()` (`@kroma/ui/vite/icon-catalog`). */
+type IconCatalogLoader = () => Promise<IconCatalog>;
+/** Registers the catalogue, without reading it: a workbench calls this once at
+ * startup and the fetch waits for the page that searches by meaning. */
+declare function setIconCatalogLoader(loader: IconCatalogLoader): void;
+/** Whether every glyph this target can draw is drawable now. True wherever
+ * there is nothing left to fetch, which is every product build. */
+declare function iconLibraryReady(): boolean;
+/** Widens the drawable set to all of Tabler and loads the catalogue, once per
+ * session. Never rejects: a chunk that fails to arrive leaves the glyphs the
+ * build kept, which is a smaller gallery rather than a page that never opens. */
+declare function loadIconLibrary(): Promise<void>;
+/** The library's arrival, for a page that has to wait for it. The fetch starts
+ * on the first render that asks. */
+declare function useIconLibrary(): boolean;
+export type { IconCatalogLoader };
+export { iconLibraryReady, loadIconLibrary, setIconCatalogLoader, useIconLibrary };

package/types/ui/src/lib/icons/stroke-prop.d.ts

@@ -0,0 +1,2 @@
+declare const STROKE_PROP = "strokeWidth";
+export { STROKE_PROP };

package/types/ui/src/lib/icons/stroke-prop.web.d.ts

@@ -0,0 +1,2 @@
+declare const STROKE_PROP = "stroke";
+export { STROKE_PROP };

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

@@ -0,0 +1,26 @@
+import type { ReactElement } from 'react';
+import { type ImageStyle, type StyleProp } from 'react-native';
+export interface ImageBackendProps {
+    uri: string;
+    fit: 'cover' | 'contain' | 'stretch';
+    style: StyleProp<ImageStyle>;
+    fadeMs: number;
+    accessibilityLabel?: string;
+    onLoad?: (size: {
+        width: number;
+        height: number;
+    } | null) => void;
+    onError?: () => void;
+}
+export interface ImageBackend {
+    /** True when the backend animates its own load-in; <Img> then leaves opacity
+     *  alone instead of cross-fading a component it does not control. */
+    fades: boolean;
+    render: (props: ImageBackendProps) => ReactElement;
+}
+declare const reactNativeImage: ImageBackend;
+/** Call once at the app root: the value is read per render, so a mid-session
+ * swap takes effect but restarts every in-flight load. */
+export declare function setImageBackend(backend: ImageBackend): void;
+export declare function imageBackend(): ImageBackend;
+export { reactNativeImage };

package/types/ui/src/lib/input-gate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Take the remote for as long as something is over the app.
+ *
+ * Returns the release, which is idempotent (safe to call from a React cleanup
+ * that runs twice under StrictMode).
+ */
+export declare function holdInput(): () => void;
+/** True while an overlay owns the remote and the app must stay inert. */
+export declare function inputHeld(): boolean;
+/** Test seam: drop every hold. */
+export declare function clearInputHolds(): void;

package/types/ui/src/lib/input-source.d.ts

@@ -0,0 +1,3 @@
+/** True when the last input was the pointer (mouse move, wheel or press), false
+ * the moment a key is pressed. Always false off the web. */
+export declare function pointerDriving(): boolean;

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

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+export declare const PageMain: ({ children }: {
+    children: ReactNode;
+}) => import("react").JSX.Element;

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

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+export declare const PageMain: ({ children }: {
+    children: ReactNode;
+}) => import("react").JSX.Element;

package/types/ui/src/lib/lockup-paths.d.ts

@@ -0,0 +1,10 @@
+export declare const KROMA_KR_PATH = "M19.32 90.2H0V11H19.32V45.68C23.24 43.92 26.88 41.72 30.24 39.08C33.6 36.44 36.58 33.56 39.18 30.44C41.78 27.32 43.94 24.1 45.66 20.78C47.38 17.46 48.64 14.2 49.44 11H71.76C70.8 14.68 69.24 18.42 67.08 22.22C64.92 26.02 62.32 29.66 59.28 33.14C56.24 36.62 52.98 39.72 49.5 42.44C46.02 45.16 42.48 47.32 38.88 48.92V50.72C42.56 50.72 45.82 51.12 48.66 51.92C51.5 52.72 54.02 53.96 56.22 55.64C58.42 57.32 60.34 59.42 61.98 61.94C63.62 64.46 65.04 67.48 66.24 71L73.08 90.2H51.12L46.68 74.48C45.72 70.96 44.44 68.18 42.84 66.14C41.24 64.1 39.12 62.62 36.48 61.7C33.84 60.78 30.44 60.32 26.28 60.32H19.32V90.2ZM101.28 90.2H81.96V11H115.68C120.08 11 124.08 11.34 127.68 12.02C131.28 12.7 134.46 13.7 137.22 15.02C139.98 16.34 142.32 17.94 144.24 19.82C146.16 21.7 147.6 23.86 148.56 26.3C149.52 28.74 150 31.44 150 34.4C150 37.2 149.56 39.72 148.68 41.96C147.8 44.2 146.46 46.16 144.66 47.84C142.86 49.52 140.6 50.88 137.88 51.92C135.16 52.96 132 53.72 128.4 54.2V56C132.96 56.48 136.5 57.5 139.02 59.06C141.54 60.62 143.48 62.68 144.84 65.24C146.2 67.8 147.4 70.88 148.44 74.48L153 90.2H131.52L128.04 75.68C127.32 72.48 126.34 70 125.1 68.24C123.86 66.48 122.28 65.26 120.36 64.58C118.44 63.9 116.04 63.56 113.16 63.56H101.28V90.2ZM101.28 25.64V49.28H114.36C119.24 49.28 123.04 48.32 125.76 46.4C128.48 44.48 129.84 41.48 129.84 37.4C129.84 33.4 128.6 30.44 126.12 28.52C123.64 26.6 119.88 25.64 114.84 25.64H101.28Z";
+export declare const KROMA_MA_PATH = "M287 90.2H269V11H297.92L318.56 68H319.16L339.32 11H366.92V90.2H348.68L349.76 30.68H348.44L325.52 90.2H309.68L287.24 30.68H285.92L287 90.2ZM396.44 90.2H375.32L402.2 11H430.52L457.4 90.2H436.28L431.84 75.32H400.88L396.44 90.2ZM404.72 62.36H428L417.32 26.12H415.4L404.72 62.36Z";
+export declare const KROMA_LOCKUP: {
+    readonly height: 100;
+    readonly krWidth: 153;
+    readonly maX: 269;
+    readonly maWidth: 188.4;
+    readonly gapLeft: 6;
+    readonly gapRight: 10;
+};

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

@@ -0,0 +1,15 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+/** `spin` rotates a full turn; `sweep` travels a segment across its parent and
+ *  carries its own width; `pulse` breathes the opacity down and back; `blink` is
+ *  the caret's hard on/off; `halo` swells past the box it sits behind as it
+ *  fades away. */
+export type LoopKind = 'spin' | 'sweep' | 'pulse' | 'blink' | 'halo';
+/**
+ * A style that loops for as long as it is mounted, or `null` when `active` is
+ * false (nothing is animated and nothing is scheduled).
+ *
+ * The result belongs on an `Animated.View`: it carries an `Animated.Value`,
+ * which is why it is cast rather than typed - a driven value is not a `number`,
+ * and `Animated.View` is the component that knows the difference.
+ */
+export declare function useLoop(kind: LoopKind, ms: number, active?: boolean): StyleProp<ViewStyle>;

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

@@ -0,0 +1,5 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+export type LoopKind = 'spin' | 'sweep' | 'pulse' | 'blink' | 'halo';
+/** A style that loops for as long as it is mounted, or `null` when `active` is
+ * false. Plain styles, so it rides on the `Animated.View` the native half needs. */
+export declare function useLoop(kind: LoopKind, ms: number, active?: boolean): StyleProp<ViewStyle>;

package/types/ui/src/lib/modal-portal.d.ts

@@ -0,0 +1,3 @@
+/** No-op off the web. See `modal-portal.web.ts` for what this repairs. */
+declare function useModalPortalRepair(_mounted: boolean): void;
+export { useModalPortalRepair };

package/types/ui/src/lib/modal-portal.web.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Call from the component that renders the `<Modal>` - the repair is a re-render
+ * of the Modal's PARENT, since that is what re-runs ModalPortal's render. Repairs
+ * when `mounted` turns true, so a dialog that opens later is fixed on open, not
+ * only on first mount.
+ */
+declare function useModalPortalRepair(mounted: boolean): void;
+export { useModalPortalRepair };

package/types/ui/src/lib/name-of.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+/**
+ * The first plain text under a node, at whatever depth it sits: what a compound
+ * reads off its children to name itself to assistive tech. Deliberately not a
+ * type check against a Label part: a component composing the row writes a label
+ * part of its own (<ChoiceList.Label>), and the row still has to name itself.
+ */
+declare function nameOf(node: ReactNode): string | undefined;
+export { nameOf };

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

@@ -0,0 +1,5 @@
+import type { NavigatorViewProps } from '@kroma/spatial-nav/react';
+import type { StyleProp, ViewStyle } from 'react-native';
+type NavigatorStyle = NavigatorViewProps['style'];
+export declare const flat: (style: StyleProp<ViewStyle>[] | StyleProp<ViewStyle>) => NavigatorStyle;
+export {};

package/types/ui/src/lib/overlay-host.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+export declare function OverlayHost({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/**
+ * Is there a host above this? Answerable before the node exists, which is what
+ * lets a caller decide what to BUILD from it - a dialog's panel behaves
+ * differently in a host than in the <Modal> it otherwise falls back to.
+ *
+ * `false` is not a failure: an app with no host (the browser client, a phone)
+ * has no reason for one, and the caller keeps whatever it did before.
+ */
+export declare function useOverlayHost(): boolean;
+/**
+ * Render `node` in the nearest <OverlayHost>, and say whether there was one.
+ *
+ * The node renders in the HOST's position in the React tree, so it reads the
+ * context the host sits in rather than the caller's. Everything app-wide (the
+ * client, the locale, the theme) is above the host and therefore still there; a
+ * context opened by a single screen is not, which is the one thing to know
+ * before putting a screen's own provider around a dialog's content.
+ */
+export declare function useOverlay(node: ReactNode | null): boolean;

package/types/ui/src/lib/part-context.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The context a compound's Root publishes, and the hook its parts read it with.
+ * `owner` is the part that provides it, written as a caller would: under
+ * `partContext<SelectState>('Select.Root')`, `useSelect('Label')` outside a Root
+ * throws `<Select.Label> must be used inside <Select.Root>`.
+ */
+declare function partContext<T>(owner: string): readonly [import("react").Context<T | null>, (part: string) => T];
+export { partContext };

package/types/ui/src/lib/perf-memory.d.ts

@@ -0,0 +1,12 @@
+export interface MemoryReading {
+    /** JS heap in use, MB. */
+    usedMb: number;
+    /** What the engine will let the heap grow to, MB, or 0 when it will not say. */
+    limitMb: number;
+}
+/** The JS heap right now, or null where the engine does not report one.
+ *
+ * Hermes keeps no `performance.memory`, and the numbers a native app would want
+ * (RSS, the image cache, the texture pool) are not the JS heap anyway, so this
+ * says nothing rather than something misleading. */
+export declare function readMemory(): MemoryReading | null;

package/types/ui/src/lib/perf-memory.web.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryReading } from './perf-memory';
+/** The JS heap right now, or null where the engine does not report one. */
+export declare function readMemory(): MemoryReading | null;
+export type { MemoryReading };

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

@@ -0,0 +1,35 @@
+/** Idempotent. */
+export declare function startPerf(): void;
+export declare function stopPerf(): void;
+export declare function perfRunning(): boolean;
+export declare function markPress(): void;
+/** Called by every focusable; only the first one after a press counts, the rest
+ * of the render is not the viewer's wait. */
+export declare function markFocus(): void;
+/** Called by <VirtualGrid> as focus lands on a tile. */
+export declare function markGridFocus(row: number, col: number): void;
+export interface PerfReport {
+    fps: number;
+    worstFrame: number;
+    jankyFrames: number;
+    frameCount: number;
+    responseP50: number;
+    responseWorst: number;
+    responseCount: number;
+    /** The most recent `CHART_FRAMES` durations, oldest first, for the HUD's
+     *  chart. An average hides the shape of a stall; this is what shows whether
+     *  the last second was evenly slow or one long hitch. */
+    frames: readonly number[];
+    /** Focused grid cell as `row,col`, or `-` when no grid has the focus. */
+    gridCell: string;
+    /** JS heap in use, MB, or 0 where the engine reports none. */
+    heapMb: number;
+    /** What the heap may grow to, MB, or 0 where the engine reports none. */
+    heapLimitMb: number;
+}
+/** How many of the ring's samples a report carries: what the HUD's chart draws.
+ *  The rest of the window is only ever read as an average, and copying it out
+ *  twice a second is work on the device being measured. */
+export declare const CHART_FRAMES = 48;
+export declare function perfReport(): PerfReport;
+export declare function resetPerf(): void;

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

@@ -0,0 +1,3 @@
+/** True on the browser targets (Vite: web, Tizen, webOS, desktop, workbench),
+ *  false under Metro (Apple TV, Android TV, iOS, Android). */
+export declare const WEB = false;

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

@@ -0,0 +1,2 @@
+/** True on the browser targets; this file IS the web resolution. */
+export declare const WEB = true;

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+declare function Portal({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/** Web-only: see `portal.web.tsx`. Native draws in place either way. */
+declare function PortalHost({ children }: Readonly<{
+    container: Element | null;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+export { Portal, PortalHost };

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

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+declare function Portal({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/**
+ * Send the portals opened under it into `container` instead of `<body>`.
+ *
+ * For a React root that is not the app's: a tool mounted beside the page in its
+ * own element stacks above it, and a popover that left for `<body>` would be
+ * painted underneath the thing that opened it. `null` is the document, which is
+ * what every shell wants and what a portal does with no host above it.
+ */
+declare function PortalHost({ container, children, }: Readonly<{
+    container: Element | null;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+export { Portal, PortalHost };