capacitor-lottie-splash 0.1.0

package/dist/esm/definitions.d.ts

@@ -0,0 +1,65 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+export type SplashRenderer = 'ios' | 'android' | 'web';
+export type SplashPhase = 'preparing' | 'playing' | 'holding' | 'hiding' | 'hidden' | 'recovery';
+export type PlaybackOutcome = 'completed' | 'reduced-motion' | 'static-fallback';
+export type SplashTheme = 'light' | 'dark';
+export interface SplashAssets {
+    /** A local URL or path to a bundled Lottie composition. */
+    animationPath?: string;
+    /** Parsed composition data. Prefer this for browser bundlers. */
+    animationData?: Record<string, unknown>;
+    /** A bundled static poster used while the composition is unavailable. */
+    posterPath?: string;
+}
+export interface SplashShowOptions {
+    /** The host's already-resolved appearance preference for this presentation. */
+    darkMode: boolean;
+    assets?: SplashAssets;
+    /** Used by the app adapter when a web presentation is deliberately requested. */
+    renderer?: Extract<SplashRenderer, 'web'>;
+}
+/** Persist the launch appearance used by Android's system-owned starting window. */
+export interface SplashLaunchThemeOptions {
+    darkMode: boolean;
+}
+export interface Presentation {
+    presentationId: string;
+    renderer: SplashRenderer;
+    adopted: boolean;
+}
+export interface PlaybackResult {
+    presentationId: string;
+    outcome: PlaybackOutcome;
+    reason?: string;
+}
+export interface SplashState {
+    presentationId?: string;
+    phase: SplashPhase;
+    visible: boolean;
+    playbackSettled: boolean;
+    appReady: boolean;
+    theme: SplashTheme;
+}
+export interface SplashCapabilities {
+    apiVersion: 1;
+    pluginVersion: string;
+    assetSetVersion?: string;
+    coldStartInstalled: boolean;
+}
+export interface StateChangeEvent extends SplashState {
+    generation: number;
+}
+export interface LottieSplashPlugin {
+    show(options?: SplashShowOptions): Promise<Presentation>;
+    setLaunchTheme(options: SplashLaunchThemeOptions): Promise<void>;
+    waitForCompletion(options: {
+        presentationId: string;
+    }): Promise<PlaybackResult>;
+    hide(options: {
+        presentationId: string;
+    }): Promise<void>;
+    getState(): Promise<SplashState>;
+    getCapabilities(): Promise<SplashCapabilities>;
+    addListener(eventName: 'stateChange', listenerFunc: (event: StateChangeEvent) => void): Promise<PluginListenerHandle>;
+}
+//# sourceMappingURL=definitions.d.ts.map

package/dist/esm/definitions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+import type { LottieSplashPlugin } from './definitions';
+declare const LottieSplash: LottieSplashPlugin;
+export * from './definitions';
+export { LottieSplash };
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { registerPlugin } from '@capacitor/core';
+const LottieSplash = registerPlugin('LottieSplash', {
+    web: () => import('./web').then(module => new module.LottieSplashWeb())
+});
+export * from './definitions';
+export { LottieSplash };
+//# sourceMappingURL=index.js.map

package/dist/esm/state-machine.d.ts

@@ -0,0 +1,19 @@
+import type { PlaybackOutcome, PlaybackResult, SplashState, SplashTheme } from './definitions';
+export interface StateMachineSnapshot extends SplashState {
+    generation: number;
+}
+export declare class SplashStateMachine {
+    private generation;
+    private playbackResult?;
+    private snapshot;
+    start(presentationId: string, theme: SplashTheme): StateMachineSnapshot;
+    playing(presentationId: string): StateMachineSnapshot;
+    settlePlayback(presentationId: string, outcome: PlaybackOutcome, reason?: string): StateMachineSnapshot;
+    requestHide(presentationId: string): StateMachineSnapshot;
+    recovery(presentationId: string): StateMachineSnapshot;
+    hidden(presentationId: string): StateMachineSnapshot;
+    getPlaybackResult(presentationId: string): PlaybackResult | undefined;
+    current(): StateMachineSnapshot;
+    private requireCurrent;
+}
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/esm/state-machine.js

@@ -0,0 +1,79 @@
+export class SplashStateMachine {
+    generation = 0;
+    playbackResult;
+    snapshot = {
+        generation: 0,
+        phase: 'hidden',
+        visible: false,
+        playbackSettled: false,
+        appReady: false,
+        theme: 'light'
+    };
+    start(presentationId, theme) {
+        if (this.snapshot.visible)
+            return this.current();
+        this.generation += 1;
+        this.playbackResult = undefined;
+        this.snapshot = {
+            generation: this.generation,
+            presentationId,
+            phase: 'preparing',
+            visible: true,
+            playbackSettled: false,
+            appReady: false,
+            theme
+        };
+        return this.current();
+    }
+    playing(presentationId) {
+        this.requireCurrent(presentationId);
+        if (!this.snapshot.playbackSettled)
+            this.snapshot.phase = 'playing';
+        return this.current();
+    }
+    settlePlayback(presentationId, outcome, reason) {
+        this.requireCurrent(presentationId);
+        this.playbackResult = { presentationId, outcome, reason };
+        this.snapshot.playbackSettled = true;
+        this.snapshot.phase = this.snapshot.appReady ? 'hiding' : 'holding';
+        return this.current();
+    }
+    requestHide(presentationId) {
+        this.requireCurrent(presentationId);
+        this.snapshot.appReady = true;
+        if (this.snapshot.playbackSettled)
+            this.snapshot.phase = 'hiding';
+        return this.current();
+    }
+    recovery(presentationId) {
+        this.requireCurrent(presentationId);
+        if (!this.snapshot.appReady)
+            this.snapshot.phase = 'recovery';
+        return this.current();
+    }
+    hidden(presentationId) {
+        this.requireCurrent(presentationId);
+        this.snapshot = {
+            generation: this.generation,
+            phase: 'hidden',
+            visible: false,
+            playbackSettled: true,
+            appReady: true,
+            theme: this.snapshot.theme
+        };
+        return this.current();
+    }
+    getPlaybackResult(presentationId) {
+        this.requireCurrent(presentationId);
+        return this.playbackResult;
+    }
+    current() {
+        return { ...this.snapshot };
+    }
+    requireCurrent(presentationId) {
+        if (!this.snapshot.presentationId || this.snapshot.presentationId !== presentationId) {
+            throw new Error(`Stale splash presentation: ${presentationId}`);
+        }
+    }
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/esm/web.d.ts

@@ -0,0 +1,31 @@
+import { WebPlugin } from '@capacitor/core';
+import type { LottieSplashPlugin, PlaybackResult, Presentation, SplashCapabilities, SplashLaunchThemeOptions, SplashShowOptions, SplashState } from './definitions';
+export declare class LottieSplashWeb extends WebPlugin implements LottieSplashPlugin {
+    private readonly stateMachine;
+    private playbackPromise?;
+    private resolvePlayback?;
+    private overlay?;
+    private progressTimer?;
+    private recoveryTimer?;
+    show(options: SplashShowOptions): Promise<Presentation>;
+    setLaunchTheme(_options: SplashLaunchThemeOptions): Promise<void>;
+    waitForCompletion(options: {
+        presentationId: string;
+    }): Promise<PlaybackResult>;
+    hide(options: {
+        presentationId: string;
+    }): Promise<void>;
+    getState(): Promise<SplashState>;
+    getCapabilities(): Promise<SplashCapabilities>;
+    private createOverlay;
+    private playComposition;
+    private settle;
+    private showLoadingRail;
+    private showRecovery;
+    private removeOverlay;
+    private ensureCurrent;
+    private emitState;
+    private prefersReducedMotion;
+    private backgroundFor;
+}
+//# sourceMappingURL=web.d.ts.map

package/dist/esm/web.js

@@ -0,0 +1,175 @@
+import { WebPlugin } from '@capacitor/core';
+import { SplashStateMachine } from './state-machine';
+const RECOVERY_TIMEOUT_MS = 15_000;
+const PROGRESS_DELAY_MS = 1_000;
+export class LottieSplashWeb extends WebPlugin {
+    stateMachine = new SplashStateMachine();
+    playbackPromise;
+    resolvePlayback;
+    overlay;
+    progressTimer;
+    recoveryTimer;
+    async show(options) {
+        const state = this.stateMachine.current();
+        if (state.visible && state.presentationId)
+            return { presentationId: state.presentationId, renderer: 'web', adopted: true };
+        const presentationId = crypto.randomUUID();
+        this.stateMachine.start(presentationId, options.darkMode ? 'dark' : 'light');
+        this.emitState();
+        this.playbackPromise = new Promise(resolve => { this.resolvePlayback = resolve; });
+        this.createOverlay(options, presentationId);
+        return { presentationId, renderer: 'web', adopted: false };
+    }
+    async setLaunchTheme(_options) {
+        // Browser builds have no OS-owned launch window to configure.
+    }
+    async waitForCompletion(options) {
+        this.ensureCurrent(options.presentationId);
+        return this.playbackPromise ?? Promise.reject(new Error('No active splash playback'));
+    }
+    async hide(options) {
+        const state = this.stateMachine.requestHide(options.presentationId);
+        this.emitState();
+        if (!state.playbackSettled)
+            await this.waitForCompletion(options);
+        this.removeOverlay(options.presentationId);
+    }
+    async getState() {
+        const { generation: _generation, ...state } = this.stateMachine.current();
+        return state;
+    }
+    async getCapabilities() {
+        return { apiVersion: 1, pluginVersion: '0.1.0', coldStartInstalled: false };
+    }
+    createOverlay(options, presentationId) {
+        const overlay = document.createElement('section');
+        overlay.setAttribute('role', 'status');
+        overlay.setAttribute('aria-live', 'polite');
+        overlay.setAttribute('aria-label', 'Loading application');
+        overlay.dataset.presentationId = presentationId;
+        Object.assign(overlay.style, {
+            position: 'fixed', inset: '0', zIndex: '2147483647', display: 'grid', placeItems: 'center',
+            background: this.backgroundFor(this.stateMachine.current().theme), overflow: 'hidden'
+        });
+        document.body.append(overlay);
+        this.overlay = overlay;
+        // A generic package cannot ship HeadCount assets. The host supplies an approved local
+        // composition; absent or failed assets leave the opaque branded background in place.
+        if (!options.assets?.animationData && !options.assets?.animationPath) {
+            this.settle(presentationId, 'static-fallback', 'No local animation asset supplied');
+            return;
+        }
+        if (this.prefersReducedMotion()) {
+            this.settle(presentationId, 'reduced-motion', 'Reduced motion is enabled');
+            return;
+        }
+        this.stateMachine.playing(presentationId);
+        this.emitState();
+        void this.playComposition(options, presentationId);
+    }
+    async playComposition(options, presentationId) {
+        try {
+            const lottie = await import('lottie-web');
+            const stage = document.createElement('div');
+            stage.setAttribute('aria-hidden', 'true');
+            stage.style.cssText = 'position:relative;z-index:1;width:min(35vw,35vh);aspect-ratio:1/1;';
+            this.overlay?.append(stage);
+            const animation = lottie.default.loadAnimation({
+                container: stage,
+                renderer: 'svg',
+                loop: false,
+                autoplay: false,
+                path: options.assets?.animationPath,
+                animationData: options.assets?.animationData
+            });
+            // Host compositions begin at frame zero. Starting at a fixed legacy offset would
+            // bypass their opening motion (for example, HeadCount's scanner sequence).
+            animation.addEventListener('DOMLoaded', () => {
+                if (this.stateMachine.current().presentationId === presentationId)
+                    animation.goToAndPlay(0, true);
+            });
+            animation.addEventListener('complete', () => this.settle(presentationId, 'completed'));
+            animation.addEventListener('data_failed', () => this.settle(presentationId, 'static-fallback', 'Animation data failed to load'));
+        }
+        catch (error) {
+            this.settle(presentationId, 'static-fallback', error instanceof Error ? error.message : 'Animation renderer failed');
+        }
+    }
+    settle(presentationId, outcome, reason) {
+        try {
+            const state = this.stateMachine.settlePlayback(presentationId, outcome, reason);
+            const result = this.stateMachine.getPlaybackResult(presentationId);
+            if (result)
+                this.resolvePlayback?.(result);
+            this.emitState();
+            if (!state.appReady) {
+                this.progressTimer = window.setTimeout(() => this.showLoadingRail(presentationId), PROGRESS_DELAY_MS);
+                this.recoveryTimer = window.setTimeout(() => this.showRecovery(presentationId), RECOVERY_TIMEOUT_MS);
+            }
+        }
+        catch {
+            // A stale renderer callback is intentionally ignored.
+        }
+    }
+    showLoadingRail(presentationId) {
+        const state = this.stateMachine.current();
+        if (state.presentationId !== presentationId || state.appReady || state.phase !== 'holding')
+            return;
+        const rail = document.createElement('div');
+        rail.dataset.splashLoadingRail = 'true';
+        rail.setAttribute('aria-label', 'Application is still loading');
+        const trackColor = state.theme === 'dark' ? 'rgba(255,255,255,.18)' : 'rgba(0,0,0,.14)';
+        rail.style.cssText = `position:absolute;top:calc(50% + min(22vw,22vh));left:50%;width:104px;height:3px;overflow:hidden;border-radius:2px;transform:translate(-50%,-50%);background:${trackColor};`;
+        const segment = document.createElement('div');
+        segment.style.cssText = 'width:37px;height:100%;border-radius:inherit;background:rgba(255,77,77,.9);animation:capacitor-lottie-splash-rail 1.15s ease-in-out infinite;';
+        const style = document.createElement('style');
+        style.textContent = '@keyframes capacitor-lottie-splash-rail{from{transform:translateX(-37px)}to{transform:translateX(104px)}}';
+        rail.append(segment);
+        this.overlay?.append(style, rail);
+    }
+    showRecovery(presentationId) {
+        let state;
+        try {
+            state = this.stateMachine.recovery(presentationId);
+        }
+        catch {
+            return;
+        }
+        if (state.presentationId !== presentationId || state.appReady)
+            return;
+        this.overlay?.querySelector('[data-splash-loading-rail]')?.remove();
+        const recovery = document.createElement('div');
+        recovery.style.cssText = 'position:absolute;bottom:12%;display:grid;gap:12px;place-items:center;color:inherit;font:500 16px system-ui;';
+        recovery.textContent = 'Still starting…';
+        const retry = document.createElement('button');
+        retry.type = 'button';
+        retry.textContent = 'Try again';
+        retry.onclick = () => window.location.reload();
+        recovery.append(retry);
+        this.overlay?.append(recovery);
+        this.emitState();
+    }
+    removeOverlay(presentationId) {
+        window.clearTimeout(this.progressTimer);
+        window.clearTimeout(this.recoveryTimer);
+        this.overlay?.remove();
+        this.overlay = undefined;
+        this.stateMachine.hidden(presentationId);
+        this.emitState();
+    }
+    ensureCurrent(presentationId) {
+        const state = this.stateMachine.current();
+        if (state.presentationId !== presentationId)
+            throw new Error(`Stale splash presentation: ${presentationId}`);
+    }
+    emitState() {
+        this.notifyListeners('stateChange', this.stateMachine.current());
+    }
+    prefersReducedMotion() {
+        return window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+    }
+    backgroundFor(theme) {
+        return theme === 'dark' ? 'linear-gradient(to right,#1e1e1e,#252525)' : 'linear-gradient(to right,#f0f0f0,#f5f5f5)';
+    }
+}
+//# sourceMappingURL=web.js.map