@kyralabs/m3e-motion 1.3.0 → 1.4.0

package/dist/index.d.ts

@@ -75,6 +75,142 @@ declare const fabMenuItemVisible: (index: number, itemCount: number, stagger: nu
  */
 declare function menuNavigationTarget(key: string, count: number, current: number): number | null;
 
+type ToolbarOrientation = 'horizontal' | 'vertical';
+/**
+ * The item index `key` moves focus to from `current` (−1: none focused) among `count` items, or
+ * null when the key does not navigate. At either end the index stays put (no wrapping).
+ */
+declare function toolbarNavigationTarget(key: string, count: number, current: number, orientation?: ToolbarOrientation, rtl?: boolean): number | null;
+
+/** Where a floating toolbar leaves the screen (FloatingToolbarExitDirection), logical. */
+type FloatingToolbarExitDirection = 'bottom' | 'top' | 'start' | 'end';
+interface FloatingToolbarScrollState {
+    /** Most negative offset: minus the distance that takes the toolbar off its container. */
+    readonly offsetLimit: number;
+    /** Current offset, between offsetLimit and 0. */
+    readonly offset: number;
+    /** Total content scrolled under the toolbar (sum of the deltas). */
+    readonly contentOffset: number;
+}
+/** rememberFloatingToolbarState() defaults: no limit known yet, fully shown. */
+declare function floatingToolbarScrollState(offsetLimit?: number, offset?: number, contentOffset?: number): FloatingToolbarScrollState;
+/** FloatingToolbarState.offset setter: coerced between offsetLimit and 0. */
+declare function withToolbarOffset(state: FloatingToolbarScrollState, offset: number): FloatingToolbarScrollState;
+/**
+ * The offset limit from the toolbar's layout (onGloballyPositioned): `distance` is how far the
+ * toolbar must travel along its exit direction to leave its container, i.e. its size plus its gap
+ * to that edge, measured without the current offset. The offset stays in range.
+ */
+declare function withToolbarOffsetLimit(state: FloatingToolbarScrollState, distance: number): FloatingToolbarScrollState;
+/** exitAlways onPostScroll: the content offset and the toolbar offset both move by `delta`. */
+declare function scrollFloatingToolbar(state: FloatingToolbarScrollState, delta: number): FloatingToolbarScrollState;
+/** 0 = fully shown, 1 = fully hidden (FloatingToolbarState.collapsedFraction()). */
+declare function toolbarCollapsedFraction(state: FloatingToolbarScrollState): number;
+/**
+ * Where a partly hidden toolbar snaps when scrolling stops (settleFloatingToolbar): shown below
+ * half, hidden from half, or null when it is already (within 1%) settled. The decision is the
+ * same as the top app bar's settleAppBar, so it reuses that port.
+ */
+declare function toolbarSettleTarget(state: FloatingToolbarScrollState): number | null;
+/**
+ * floatingToolbarVerticalNestedScroll: collapses the toolbar after scrolling down by the collapse
+ * threshold and expands it after scrolling up by the expand threshold (both
+ * FloatingToolbarDefaults.ScrollDistanceThreshold by default).
+ */
+interface ToolbarExpansionScroll {
+    readonly contentOffset: number;
+    /** The content offset that triggers the next change. */
+    readonly threshold: number;
+}
+/** A tracker for a toolbar that is `expanded` (updateThreshold). */
+declare function toolbarExpansionScroll(expanded: boolean, collapseThreshold: number, expandThreshold: number, contentOffset?: number): ToolbarExpansionScroll;
+/**
+ * onPostScroll: moves the content offset by `delta`; returns the new tracker and `'collapse'` /
+ * `'expand'` when a threshold was crossed (Compose calls onCollapse / onExpand then).
+ */
+declare function scrollToolbarExpansion(state: ToolbarExpansionScroll, delta: number, collapseThreshold: number, expandThreshold: number): {
+    state: ToolbarExpansionScroll;
+    change: 'collapse' | 'expand' | null;
+};
+
+type Easing = (fraction: number) => number;
+/** `cubic-bezier(a, b, c, d)` as an easing function. */
+declare const cubicBezier: (a: number, b: number, c: number, d: number) => Easing;
+/** Parses a resolved CSS `cubic-bezier(a, b, c, d)` (e.g. a motion easing token); null otherwise. */
+declare function parseCubicBezier(css: string): Easing | null;
+
+interface LinearIndeterminateTiming {
+    /** `LinearAnimationDuration`: one cycle. */
+    readonly durationMillis: number;
+    /** `[delay, duration]` of each keyframe pair. */
+    readonly firstHead: readonly [number, number];
+    readonly firstTail: readonly [number, number];
+    readonly secondHead: readonly [number, number];
+    readonly secondTail: readonly [number, number];
+    /** `LinearIndeterminateProgressEasing`. */
+    readonly easing: Easing;
+}
+/**
+ * The indeterminate linear indicator's fractions at `elapsedMillis`, in the order the wavy indicator
+ * draws them (`getProgressFractions`): first tail, first head, second tail, second head (0–1 each).
+ */
+declare function linearIndeterminateFractions(elapsedMillis: number, timing: LinearIndeterminateTiming): [number, number, number, number];
+interface CircularIndeterminateTiming {
+    /** `CircularAnimationProgressDuration`: one cycle. */
+    readonly durationMillis: number;
+    /** `CircularGlobalRotationDegreesTarget`: linear rotation per cycle (degrees). */
+    readonly rotation: number;
+    /** `CircularAdditionalRotationDegreesTarget`: the steps' total per cycle (degrees). */
+    readonly additionalRotation: number;
+    /** `CircularAnimationAdditionalRotationDelay`: a step starts every this. */
+    readonly additionalDelayMillis: number;
+    /** `CircularAnimationAdditionalRotationDuration`: and moves for this. */
+    readonly additionalDurationMillis: number;
+    /** `CircularIndeterminateMinProgress` / `MaxProgress`: the sweep range (0–1). */
+    readonly minProgress: number;
+    readonly maxProgress: number;
+    /** `CircularProgressEasing`: the shrinking half of the sweep. */
+    readonly easing: Easing;
+}
+interface CircularIndeterminateFrame {
+    /** Global + additional rotation, degrees clockwise. */
+    rotation: number;
+    /** Sweep, 0–1 of a full turn. */
+    sweep: number;
+}
+/** The indeterminate circular indicator at `elapsedMillis`. */
+declare function circularIndeterminateFrame(elapsedMillis: number, timing: CircularIndeterminateTiming): CircularIndeterminateFrame;
+/**
+ * The wave offset tween's duration: `((wavelength / waveSpeed) * 1000 * vertexCount)` rounded and
+ * floored at `minMillis`; `Infinity` (the offset holds at 0) when either is not positive.
+ */
+declare function waveTravelMillis(wavelength: number, waveSpeed: number, minMillis: number, vertexCount?: number): number;
+/** The wave offset (0–1) after `elapsedMillis` of a tween of `travelMillis`. */
+declare const waveOffset: (elapsedMillis: number, travelMillis: number) => number;
+/** `WavyProgressIndicatorDefaults.indicatorAmplitude`: no wave near the start and the end. */
+declare const indicatorAmplitude: (progress: number, minProgress: number, maxProgress: number) => number;
+interface AmplitudeTween {
+    readonly durationMillis: number;
+    readonly easing: Easing;
+}
+/**
+ * The amplitude Animatable of the wavy modifiers: starts at its first target without animating;
+ * a new target tweens with `increase` or `decrease` (by direction), but only once the running
+ * tween has finished (`amplitudeAnimationJob == null || isCompleted`); a target set meanwhile is
+ * ignored, as in Compose, until the next `update` after it finishes.
+ */
+declare class AmplitudeAnimation {
+    #private;
+    constructor(initial: number);
+    get value(): number;
+    get target(): number;
+    get isRunning(): boolean;
+    /** Advances to `now` (ms). */
+    sample(now: number): number;
+    /** Requests `target` at `now`; returns true when a tween started. */
+    update(target: number, now: number, increase: AmplitudeTween, decrease: AmplitudeTween): boolean;
+}
+
 interface LoadingIndicatorTiming {
     /** `MorphIntervalMillis`: how often a morph starts. */
     readonly morphIntervalMillis: number;
@@ -210,7 +346,7 @@ declare function menuTransformOrigin(anchor: MenuRect, menu: MenuRect): {
 declare function menuPosition(input: MenuPositionInput): MenuPositionResult;
 
 /** How the bar reacts to its scroll container (TopAppBarDefaults.*ScrollBehavior). */
-type AppBarScrollBehavior = 'pinned' | 'enter-always';
+type AppBarScrollBehavior = 'pinned' | 'enter-always' | 'exit-until-collapsed';
 interface AppBarScrollState {
     /** Most negative height offset: minus the bar's full height (adjustHeightOffsetLimit). */
     readonly heightOffsetLimit: number;
@@ -242,6 +378,13 @@ declare function isScrolledUnder(state: AppBarScrollState): boolean;
  * - pinned: only the content offset moves (PinnedScrollBehavior.onPostScroll).
  * - enter-always: the bar also collapses/expands by the same amount
  *   (EnterAlwaysScrollBehavior.onPreScroll: `heightOffset += available.y`).
+ * - exit-until-collapsed: scrolling down collapses the bar by the same amount
+ *   (ExitUntilCollapsedScrollBehavior.onPreScroll); scrolling up expands it only by what the
+ *   content cannot take (onPostScroll: `heightOffset += available.y` once the content is at its
+ *   start). On the web the content scrolls by the whole delta, so the part of an upward scroll
+ *   that lies within the collapsed distance of the top (scroll position below -heightOffset) is
+ *   the part Compose hands to the bar: the bar is fully expanded when the content reaches its
+ *   start, and a bar that collapsed together with the content stays attached to it.
  */
 declare function scrollAppBar(state: AppBarScrollState, behavior: AppBarScrollBehavior, scrollTop: number, delta: number): AppBarScrollState;
 /**
@@ -249,6 +392,177 @@ declare function scrollAppBar(state: AppBarScrollState, behavior: AppBarScrollBe
  * half, fully collapsed from half, or null when it is already (within 1%) settled.
  */
 declare function settleTarget(state: AppBarScrollState): number | null;
+/** TopTitleAlphaEasing (AppBar.kt L3604): CubicBezierEasing(.8f, 0f, .8f, .15f). */
+declare const TOP_TITLE_ALPHA_EASING: readonly [0.8, 0, 0.8, 0.15];
+/** FastOutLinearInEasing (Easing.kt L66): CubicBezierEasing(0.4f, 0.0f, 1.0f, 1.0f). */
+declare const FAST_OUT_LINEAR_IN_EASING: readonly [0.4, 0, 1, 1];
+/** What a two-rows bar (medium / large flexible, TwoRowsTopAppBar) draws at a collapsed fraction. */
+interface TwoRowsFrame {
+    /** Alpha of the collapsed (top row) title and subtitle: TopTitleAlphaEasing(fraction). */
+    readonly collapsedTitleAlpha: number;
+    /** Alpha of the expanded (bottom row) title and subtitle: 1 - fraction. */
+    readonly expandedTitleAlpha: number;
+    /** Container → scrolled container color mix (TopAppBarColors.containerColor): FastOutLinearIn. */
+    readonly containerColorFraction: number;
+    /** Below 0.5 the collapsed title is hidden from accessibility, from 0.5 the expanded one. */
+    readonly collapsedTitleHidden: boolean;
+}
+/** TwoRowsTopAppBar (L2818-2836): the color, both title alphas and semantics follow the fraction. */
+declare function twoRowsFrame(fraction: number): TwoRowsFrame;
+
+/** SearchBarState.currentValue is Expanded above this (L1535, "tolerance for spring anim"). */
+declare const SEARCH_BAR_EXPANDED_THRESHOLD = 0.02;
+/** ExpandedDockedSearchBarWithGap shows its results once progress passes this (L3667). */
+declare const SEARCH_DROPDOWN_VISIBLE_PROGRESS = 0.1;
+/** A Compose `tween(durationMillis, delayMillis, easing)`. */
+interface TweenSpec {
+    readonly duration: number;
+    readonly delay: number;
+    readonly easing: Easing;
+}
+/**
+ * A float with Compose `Animatable.animateTo(tween)` semantics: each target starts a tween from the
+ * current value (velocity is not carried), held for `delay`, then eased over `duration`. A null
+ * spec is Compose's `snap()`: the value jumps.
+ */
+declare class TweenAnimatable {
+    #private;
+    constructor(value: number);
+    get value(): number;
+    get target(): number;
+    get isRunning(): boolean;
+    snapTo(value: number): void;
+    animateTo(target: number, spec: TweenSpec | null, now: number): void;
+    sample(now: number): number;
+}
+/** The four animation specs of a SearchBarState (null springs / tweens jump, as `snap()`). */
+interface SearchBarSpecs {
+    readonly expand: SpringSpec | null;
+    readonly collapse: SpringSpec | null;
+    readonly contentFadeIn: TweenSpec | null;
+    readonly contentFadeOut: TweenSpec | null;
+}
+/** One sampled frame of a {@link SearchBarAnimation}. */
+interface SearchBarSample {
+    /** `animatable.value`: may overshoot 1 (expressive spatial springs). */
+    readonly value: number;
+    /** `progress`: the value clamped to [0, 1]. */
+    readonly progress: number;
+    /** `contentProgress` (the contained / with-gap results' alpha). */
+    readonly contentProgress: number;
+    /** The with-gap drop-down's slide offset in px (0 at rest, minus half its height hidden). */
+    readonly slide: number;
+    /** Whether the with-gap drop-down is shown (AnimatedVisibility is entering, visible or exiting). */
+    readonly dropdownShown: boolean;
+}
+/**
+ * SearchBarState's animation: `animateToExpanded` / `animateToCollapsed` run the progress spring
+ * and the content tween together; a new target starts from the current value and velocity
+ * (Animatable). Optionally (ExpandedDockedSearchBarWithGap) it also runs the drop-down's
+ * slide-in / slide-out on the same springs, from progress 0.1.
+ */
+declare class SearchBarAnimation {
+    #private;
+    constructor(expanded?: boolean);
+    /** SearchBarState.targetValue. */
+    get isTargetExpanded(): boolean;
+    /** SearchBarState.currentValue: expanded until the value drops to the 0.02 tolerance. */
+    get isExpanded(): boolean;
+    get isRunning(): boolean;
+    /** animateToExpanded() at `now` (ms). */
+    expand(specs: SearchBarSpecs, now: number): void;
+    /** animateToCollapsed() at `now` (ms). */
+    collapse(specs: SearchBarSpecs, now: number): void;
+    /** Jumps to collapsed (0) or expanded (1), stopping every animation. */
+    snapTo(expanded: boolean): void;
+    /**
+     * Advances to `now`. `dropdownHeight` (px, the drop-down's full height) enables the with-gap
+     * slide: AnimatedVisibility(visible = progress > 0.1 && target == Expanded) slides in from minus
+     * half the height on the expand spring and out to it on the collapse spring.
+     */
+    sample(now: number, dropdownHeight?: number): SearchBarSample;
+}
+/** The expanded views Compose offers for a SearchBarState. */
+type SearchViewVariant = 'full-screen' | 'full-screen-contained' | 'docked' | 'docked-with-gap';
+interface SearchRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** The SearchBar.kt measurements the layouts read (px; search-defaults.css). */
+interface SearchViewMetrics {
+    /** SearchBarVerticalPadding (8dp). */
+    readonly verticalPadding: number;
+    /** AppBarWithSearchVerticalPadding (4dp): the contained view's top padding. */
+    readonly containedTopPadding: number;
+    /** FullScreenExpandedHorizontalPadding (8dp). */
+    readonly containedHorizontalPadding: number;
+    /** SearchBarCornerRadius = InputFieldHeight / 2 (28dp). */
+    readonly cornerRadius: number;
+    /** DockedExpandedTableMinHeight (240dp). */
+    readonly dockedMinHeight: number;
+    /** DockedExpandedTableMaxHeightScreenRatio (2/3). */
+    readonly dockedMaxHeightRatio: number;
+    /** DockedExpandedWithGapTableMaxHeightScreenRatio (1/2). */
+    readonly withGapMaxHeightRatio: number;
+    /** dockedDropdownGapSize (2dp). */
+    readonly dropdownGap: number;
+}
+interface SearchViewInput {
+    readonly variant: SearchViewVariant;
+    /** The collapsed search bar (`collapsedBounds`), viewport px. */
+    readonly collapsed: SearchRect;
+    /** The window (viewport) size. */
+    readonly window: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** The unconsumed top window inset (safe area). */
+    readonly insetTop: number;
+    readonly sample: Pick<SearchBarSample, 'value' | 'progress'>;
+    readonly metrics: SearchViewMetrics;
+}
+/** Where everything of an expanded view goes in one frame (viewport px). */
+interface SearchViewFrame {
+    /**
+     * The surface: full-screen, the growing container (with `radius`); contained, the window,
+     * faded in by `alpha`; docked, the panel holding field and results (height between `minHeight`
+     * and `maxHeight`); with gap, the scrim (drawn at `alpha` × the scrim opacity).
+     */
+    readonly surface: SearchRect & {
+        readonly radius: number;
+        readonly alpha: number;
+        readonly minHeight: number;
+        readonly maxHeight: number;
+    };
+    /** The input field (collapsed height). */
+    readonly field: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+    };
+    /** The results: top-left, width and the height they may take. */
+    readonly results: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly maxHeight: number;
+    };
+}
+/**
+ * The layout of an expanded view at one animation frame: FullScreenSearchBarLayout (`isContained`
+ * false / true), DockedSearchBarLayoutImpl (docked) and the with-gap popup. Predictive back is not
+ * ported (the web has no back gesture progress).
+ */
+declare function searchViewFrame(input: SearchViewInput): SearchViewFrame;
+/**
+ * The combobox's next active option for a key (React Aria / APG list autocomplete): ArrowDown
+ * from the input goes to the first option and then down, stopping at the last; ArrowUp from the
+ * input goes to the last option and then up, and from the first option back to the input (-1).
+ * Returns null for keys it does not handle or an empty list. `enabled` filters disabled options.
+ */
+declare function searchNavigationTarget(key: string, enabled: readonly boolean[], active: number): number | null;
 
 interface ButtonGroupItemSize {
     /** Resting width (Compose: the item's max intrinsic width). */
@@ -277,4 +591,4 @@ declare function buttonGroupVisibleCount(widths: readonly number[], spacing: num
  */
 declare function buttonGroupWidths(items: readonly ButtonGroupItemSize[], pressed: readonly number[], expandedRatio: number, visibleCount?: number): number[];
 
-export { type AppBarScrollBehavior, type AppBarScrollState, type ButtonGroupItemSize, DEFAULT_DISPLACEMENT_THRESHOLD, type IndeterminateFrame, type LinearEasing, type LinearEasingOptions, type LoadingIndicatorTiming, type MenuAnchorPosition, type MenuPositionInput, type MenuPositionResult, type MenuRect, type Motion, SpringAnimatable, SpringSimulation, type SpringSpec, animatedInt, appBarScrollState, buttonGroupVisibleCount, buttonGroupWidths, collapsedFraction, dampingCoefficient, dampingRatioFromCoefficient, estimateAnimationDurationMillis, estimateAnimationDurationMillisDouble, fabMenuItemVisible, indeterminateFrame, initialIndeterminateFrame, isScrolledUnder, menuNavigationTarget, menuPosition, menuTransformOrigin, morphSpringDurationMillis, overlappedFraction, scrollAppBar, settleTarget, springDurationMillis, springToLinear, springValue, springVelocity, withHeight, withHeightOffset };
+export { AmplitudeAnimation, type AmplitudeTween, type AppBarScrollBehavior, type AppBarScrollState, type ButtonGroupItemSize, type CircularIndeterminateFrame, type CircularIndeterminateTiming, DEFAULT_DISPLACEMENT_THRESHOLD, type Easing, FAST_OUT_LINEAR_IN_EASING, type FloatingToolbarExitDirection, type FloatingToolbarScrollState, type IndeterminateFrame, type LinearEasing, type LinearEasingOptions, type LinearIndeterminateTiming, type LoadingIndicatorTiming, type MenuAnchorPosition, type MenuPositionInput, type MenuPositionResult, type MenuRect, type Motion, SEARCH_BAR_EXPANDED_THRESHOLD, SEARCH_DROPDOWN_VISIBLE_PROGRESS, SearchBarAnimation, type SearchBarSample, type SearchBarSpecs, type SearchRect, type SearchViewFrame, type SearchViewInput, type SearchViewMetrics, type SearchViewVariant, SpringAnimatable, SpringSimulation, type SpringSpec, TOP_TITLE_ALPHA_EASING, type ToolbarExpansionScroll, type ToolbarOrientation, TweenAnimatable, type TweenSpec, type TwoRowsFrame, animatedInt, appBarScrollState, buttonGroupVisibleCount, buttonGroupWidths, circularIndeterminateFrame, collapsedFraction, cubicBezier, dampingCoefficient, dampingRatioFromCoefficient, estimateAnimationDurationMillis, estimateAnimationDurationMillisDouble, fabMenuItemVisible, floatingToolbarScrollState, indeterminateFrame, indicatorAmplitude, initialIndeterminateFrame, isScrolledUnder, linearIndeterminateFractions, menuNavigationTarget, menuPosition, menuTransformOrigin, morphSpringDurationMillis, overlappedFraction, parseCubicBezier, scrollAppBar, scrollFloatingToolbar, scrollToolbarExpansion, searchNavigationTarget, searchViewFrame, settleTarget, springDurationMillis, springToLinear, springValue, springVelocity, toolbarCollapsedFraction, toolbarExpansionScroll, toolbarNavigationTarget, toolbarSettleTarget, twoRowsFrame, waveOffset, waveTravelMillis, withHeight, withHeightOffset, withToolbarOffset, withToolbarOffsetLimit };