Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · animation

Published foldkit-ui API declarations for animation.

./animation

@wsagency/wseffect-foldkit-ui · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit-ui@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit-ui/animation'

Exported declarations

defaultLeaveCommand

Creates the standard leave Command for the Model's current transition. Use this when handling `StartedLeaveAnimating` unless the component needs its own settlement strategy.

defaultLeaveCommand: (model: Model) => Command.Command<Message>

Hid

export type Hid = typeof Message.Hid.Type;

hide

Programmatically starts the leave lifecycle.

hide: (model: Model) => Update.Return<Model, Message>

init

Creates an initial animation model from a config. Defaults to hidden.

init: (config: InitConfig) => Model

InitConfig

Configuration for creating an animation model with `init`.

export type InitConfig = Readonly<{
    id: string;
    isShowing?: boolean;
}>;

Message

export type Message = typeof Message.Type;

Message

Union of all messages the animation component can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly Showed: {};
    readonly Hid: {};
    readonly CompletedWaitForPaint: {
        generation: Schema.Number;
    };
    readonly EndedAnimation: {
        generation: Schema.Number;
    };
}>

Model

export type Model = typeof Model.Type;

Model

Schema for Animation state, including the transition generation used to reject stale Command results.

Model: Schema.Struct<{
    readonly id: Schema.String;
    readonly isShowing: Schema.Boolean;
    readonly transitionState: Schema.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>;
    readonly transitionGeneration: Schema.Number;
}>

OutMessage

export type OutMessage = typeof OutMessage.Type;

OutMessage

Union of the facts Animation reports to its parent.

OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly StartedLeaveAnimating: {
        generation: Schema.Number;
    };
    readonly TransitionedOut: {};
}>

show

Programmatically starts the enter lifecycle.

show: (model: Model) => Update.Return<Model, Message>

Showed

export type Showed = typeof Message.Showed.Type;

toggle

Toggles the animation between its shown and hidden states.

toggle: (model: Model) => Update.Return<Model, Message>

TransitionState

export type TransitionState = typeof TransitionState.Type;

TransitionState

Schema for the animation lifecycle state, tracking enter/leave phases.

TransitionState: Schema.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>

update

export declare function update(model: Model, message: Message): UpdateReturn;

update

Processes an Animation Message and returns the next Model, optional Commands, and an optional OutMessage. `Showed` and `Hid` start a transition but cannot finish one, so direct calls with either Message return a plain update result. Results from an earlier transition generation leave the Model unchanged.

export declare function update(model: Model, message: Showed | Hid): Update.Return<Model, Message>;

view

Renders a headless animation wrapper that coordinates CSS transitions and CSS keyframe animations via data attributes. Data attributes reflect the current lifecycle phase: - `data-closed`: element is in its hidden/initial state - `data-enter`: enter animation is active - `data-leave`: leave animation is active - `data-transition`: any animation is active

view: import("@wsagency/wseffect-foldkit/submodel").View<{
    readonly id: string;
    readonly isShowing: boolean;
    readonly transitionState: "EnterAnimating" | "EnterStart" | "Idle" | "LeaveAnimating" | "LeaveStart";
    readonly transitionGeneration: number;
}, {
    readonly _tag: "CompletedWaitForPaint";
    readonly generation: number;
} | {
    readonly _tag: "EndedAnimation";
    readonly generation: number;
} | {
    readonly _tag: "Hid";
} | {
    readonly _tag: "Showed";
}, Readonly<{
    content: Html;
    className?: string;
    attributes?: ReadonlyArray<ChildAttribute>;
    element?: Exclude<TagName, 'textarea'>;
    /** When true, wraps content in a CSS grid container that smoothly animates
     *  height via `grid-template-rows: 0fr → 1fr`. The element stays in the DOM
     *  when hidden (collapsed to zero height) instead of being removed. */
    animateSize?: boolean;
}>>

ViewInputs

Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field.

export type ViewInputs = Readonly<{
    content: Html;
    className?: string;
    attributes?: ReadonlyArray<ChildAttribute>;
    element?: Exclude<TagName, 'textarea'>;
    /** When true, wraps content in a CSS grid container that smoothly animates
     *  height via `grid-template-rows: 0fr → 1fr`. The element stays in the DOM
     *  when hidden (collapsed to zero height) instead of being removed. */
    animateSize?: boolean;
}>;

WaitForAnimationSettled

Waits for all CSS transitions and keyframe animations on the element to settle, then reports the transition generation that scheduled the wait.

WaitForAnimationSettled: Command.CommandDefinitionWithArgs<"WaitForAnimationSettled", {
    id: Schema.String;
    generation: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "EndedAnimation";
    readonly generation: number;
}, never, never>>

WaitForPaint

Waits for paint via double-rAF, then reports the transition generation that scheduled the wait.

WaitForPaint: Command.CommandDefinitionWithArgs<"WaitForPaint", {
    generation: Schema.Number;
}, Effect.Effect<{
    readonly _tag: "CompletedWaitForPaint";
    readonly generation: number;
}, never, never>>