@symbiote-native/splash-screen 3.0.3-canary-20260724095331 → 3.0.3

package/README.md

@@ -130,6 +130,42 @@ const { container, logo } = useHideAnimation({
 See the docs-site package page (`docs/packages/splash-screen`) for the full config surface and
 the Vue/Angular equivalents.
 
+## API
+
+The core entry point (`@symbiote-native/splash-screen`) is framework-agnostic — `hide`/`isVisible`
+re-exported verbatim from `react-native-bootsplash`, plus the readiness gate and style computation
+each adapter's lifecycle wrapper drives:
+
+```ts
+hide(config?: IHideConfig): Promise<void>              // dismisses the native splash, optional fade
+isVisible(): boolean                                    // is the native splash still up
+getHideAnimationConstants(): IHideAnimationConstants    // darkModeEnabled + logo/status-bar/nav-bar metrics,
+                                                        // read off the RNBootSplash native module
+new HideAnimationController(config: IHideAnimationConfig)
+// readiness gate — onContainerLayout / onLogoLoadEnd / onBrandLoadEnd / updateConfig(config);
+// hide() fires exactly once, after layout + both images + the caller's own `ready` all report in.
+computeHideAnimationStyles(config, constants, controller): IHideAnimationResult
+// the { container, logo, brand } prop bags, recomputed from the current config.
+```
+
+Plus `IHideConfig`, `IManifest`, `IHideAnimationConfig`, `IHideAnimationContainerProps`,
+`IHideAnimationImageProps`, `IHideAnimationResult`, `IHideAnimationConstants`.
+
+Each adapter entry point re-exports `hide`/`isVisible` (and the `IHideConfig`/`IManifest`/
+`IHideAnimationConfig`/`IHideAnimationResult` types) unchanged, and adds one lifecycle wrapper
+over the controller — the only per-framework difference is how the config is read:
+
+```ts
+// @symbiote-native/splash-screen/react — re-runs every render, so a plain value
+useHideAnimation(config: IHideAnimationConfig): IHideAnimationResult
+
+// @symbiote-native/splash-screen/vue — setup runs once, so a getter
+useHideAnimation(getConfig: () => IHideAnimationConfig): ComputedRef<IHideAnimationResult>
+
+// @symbiote-native/splash-screen/angular — inject(HideAnimationService), connect() once
+connect(getConfig: () => IHideAnimationConfig): Signal<IHideAnimationResult>
+```
+
 ## Test it
 
 Headless hook/composable tests live next to each adapter entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/splash-screen",
-  "version": "3.0.3-canary-20260724095331",
+  "version": "3.0.3",
   "description": "Third-party splash-screen native module wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, and Angular adapters.",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,10 @@
     "codegen-specs",
     "cli.cjs",
     "react-native.config.cjs",
-    "symbiote-splash-screen.podspec"
+    "symbiote-splash-screen.podspec",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
   ],
   "publishConfig": {
     "access": "public"
@@ -71,7 +74,7 @@
     "react": ">=19.0.0",
     "react-native": ">=0.86",
     "vue": ">=3.5.0",
-    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/angular": "0.6.2",
     "@symbiote-native/react": "0.2.8",
     "@symbiote-native/vue": "0.3.8"
   },
@@ -107,7 +110,7 @@
     "@vue/runtime-core": "^3.5.13",
     "react": "19.2.3",
     "typescript": "~6.0.0",
-    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/angular": "0.6.2",
     "@symbiote-native/engine": "0.1.7",
     "@symbiote-native/react": "0.2.8",
     "@symbiote-native/test-utils": "0.1.6",

package/src/angular/services/hide-animation.service/hide-animation.service.test.ts

@@ -1,205 +0,0 @@
-// Co-located Angular-driven test (ADR 0025) for HideAnimationService. Mounts a real host
-// component through @symbiote-native/angular so `connect()` runs the same way an app would call
-// it — inside the component's own injection context — and drives the returned signal through a
-// full mount/unmount lifecycle rather than poking the service in isolation.
-
-import '@angular/compiler';
-import { Component, inject, signal, type Signal } from '@angular/core';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { mount, unmount } from '@symbiote-native/angular';
-import { flattenStyle } from '@symbiote-native/engine';
-import { installFabric } from '@symbiote-native/test-utils';
-import type { IImageSourceProp } from '@symbiote-native/components';
-import { hide as mockedHide } from 'react-native-bootsplash';
-import type { IHideAnimationResult } from '../../../core';
-import { HideAnimationService } from './index';
-
-vi.mock('react-native-bootsplash', () => ({
-  hide: vi.fn(() => Promise.resolve()),
-  isVisible: vi.fn(() => true),
-}));
-
-function isPresent<T>(value: unknown): value is T {
-  return value !== null && value !== undefined;
-}
-
-const FAKE_NATIVE_MODULE = {
-  getConstants: () => ({ darkModeEnabled: false }),
-  hide: vi.fn(() => Promise.resolve()),
-  isVisible: () => true,
-};
-
-const registeredNativeModules: Record<string, unknown> = { RNBootSplash: FAKE_NATIVE_MODULE };
-
-const ROOT_TAG = 940;
-const fabric = installFabric();
-const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
-const settle = async (): Promise<void> => {
-  await tick();
-  await tick();
-};
-
-const MANIFEST = {
-  background: '#ffffff',
-  logo: { width: 100, height: 100 },
-  brand: { bottom: 40, width: 80, height: 20 },
-};
-
-const LOGO_SOURCE: IImageSourceProp = { uri: 'logo.png' };
-const BRAND_SOURCE: IImageSourceProp = { uri: 'brand.png' };
-
-let capturedResult: Signal<IHideAnimationResult> | undefined;
-let capturedAnimate: ReturnType<typeof vi.fn> | undefined;
-let capturedReady: ReturnType<typeof signal<boolean>> | undefined;
-
-@Component({
-  selector: 'symbiote-hide-animation-host',
-  standalone: true,
-  template: '',
-})
-class HideAnimationHost {
-  readonly ready = signal(true);
-  readonly animate = vi.fn();
-
-  readonly hideAnimation = inject(HideAnimationService).connect(() => ({
-    manifest: MANIFEST,
-    ready: this.ready(),
-    logo: LOGO_SOURCE,
-    brand: BRAND_SOURCE,
-    animate: this.animate,
-  }));
-
-  constructor() {
-    capturedResult = this.hideAnimation;
-    capturedAnimate = this.animate;
-    capturedReady = this.ready;
-  }
-}
-
-@Component({
-  selector: 'symbiote-hide-animation-no-logo-host',
-  standalone: true,
-  template: '',
-})
-class HideAnimationNoLogoHost {
-  readonly animate = vi.fn();
-
-  readonly hideAnimation = inject(HideAnimationService).connect(() => ({
-    manifest: MANIFEST,
-    logo: undefined,
-    brand: undefined,
-    animate: this.animate,
-  }));
-
-  constructor() {
-    capturedResult = this.hideAnimation;
-    capturedAnimate = this.animate;
-  }
-}
-
-beforeEach(() => {
-  globalThis.__turboModuleProxy = <T>(name: string): T | null => {
-    const module = registeredNativeModules[name];
-    return isPresent<T>(module) ? module : null;
-  };
-  capturedResult = undefined;
-  capturedAnimate = undefined;
-  capturedReady = undefined;
-});
-
-afterEach(() => {
-  unmount(ROOT_TAG);
-  fabric.reset();
-  globalThis.__turboModuleProxy = undefined;
-  vi.clearAllMocks();
-});
-
-describe('HideAnimationService.connect', () => {
-  it('reports the container/logo/brand shapes for a config with both logo and brand', async () => {
-    mount(ROOT_TAG, HideAnimationHost);
-    await settle();
-
-    const result = capturedResult?.();
-    if (result === undefined) throw new Error('hideAnimation signal was not captured');
-
-    expect(flattenStyle(result.container.style).backgroundColor).toBe(MANIFEST.background);
-    expect(result.container.onLayout).toBeTypeOf('function');
-
-    expect(result.logo.source).toBe(LOGO_SOURCE);
-    expect(flattenStyle(result.logo.style)).toEqual({
-      width: MANIFEST.logo.width,
-      height: MANIFEST.logo.height,
-    });
-    expect(result.logo.onLoadEnd).toBeTypeOf('function');
-
-    expect(result.brand.source).toBe(BRAND_SOURCE);
-    expect(flattenStyle(result.brand.style)).toMatchObject({
-      bottom: MANIFEST.brand.bottom,
-      width: MANIFEST.brand.width,
-      height: MANIFEST.brand.height,
-    });
-    expect(result.brand.onLoadEnd).toBeTypeOf('function');
-  });
-
-  it('fires hide() exactly once, only after layout + logo + brand + ready are all satisfied', async () => {
-    mount(ROOT_TAG, HideAnimationHost);
-    await settle();
-
-    const result = capturedResult;
-    if (result === undefined || capturedAnimate === undefined) {
-      throw new Error('hideAnimation signal was not captured');
-    }
-
-    result().container.onLayout();
-    expect(mockedHide).not.toHaveBeenCalled();
-
-    result().logo.onLoadEnd?.();
-    expect(mockedHide).not.toHaveBeenCalled();
-
-    // Brand is the last gate: only once it reports load-end does hide() fire.
-    result().brand.onLoadEnd?.();
-    await settle();
-
-    expect(mockedHide).toHaveBeenCalledOnce();
-    expect(mockedHide).toHaveBeenCalledWith({ fade: false });
-    expect(capturedAnimate).toHaveBeenCalledOnce();
-  });
-
-  it('does not fire hide() again after it has already fired', async () => {
-    mount(ROOT_TAG, HideAnimationHost);
-    await settle();
-
-    const result = capturedResult;
-    if (result === undefined || capturedReady === undefined) {
-      throw new Error('hideAnimation signal was not captured');
-    }
-
-    result().container.onLayout();
-    result().logo.onLoadEnd?.();
-    result().brand.onLoadEnd?.();
-    await settle();
-    expect(mockedHide).toHaveBeenCalledOnce();
-
-    // A later config change (ready flips off then back on) re-runs the effect's updateConfig,
-    // but the controller's own animateHasBeenCalled guard keeps hide() from firing twice.
-    capturedReady.set(false);
-    await settle();
-    capturedReady.set(true);
-    await settle();
-
-    expect(mockedHide).toHaveBeenCalledOnce();
-  });
-
-  it('reports source -1 and no onLoadEnd when config.logo is omitted', async () => {
-    mount(ROOT_TAG, HideAnimationNoLogoHost);
-    await settle();
-
-    const result = capturedResult?.();
-    if (result === undefined) throw new Error('hideAnimation signal was not captured');
-
-    expect(result.logo.source).toBe(-1);
-    expect(result.logo.onLoadEnd).toBeUndefined();
-    expect(result.brand.source).toBe(-1);
-    expect(result.brand.onLoadEnd).toBeUndefined();
-  });
-});

package/src/react/hooks/use-hide-animation/use-hide-animation.test.tsx

@@ -1,114 +0,0 @@
-// Co-located React-driven test (ADR 0025) for useHideAnimation. Mocks react-native-bootsplash's
-// hide()/isVisible() (imported straight from the npm package by core/hide.ts) and installs a
-// fake __turboModuleProxy so getHideAnimationConstants() resolves without a real native host.
-
-import { createElement, type ReactElement } from 'react';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { mount, unmount, View } from '@symbiote-native/react';
-import { installFabric } from '@symbiote-native/test-utils';
-import { useHideAnimation } from './index';
-import type { IHideAnimationConfig, IHideAnimationResult, IManifest } from '../../../core';
-
-vi.mock('react-native-bootsplash', () => ({
-  hide: vi.fn(() => Promise.resolve()),
-  isVisible: vi.fn(() => true),
-}));
-
-const ROOT_TAG = 900;
-
-const FAKE_NATIVE_MODULE = { getConstants: () => ({ darkModeEnabled: false }) };
-
-function isPresent<T>(value: unknown): value is T {
-  return value !== null && value !== undefined;
-}
-
-Object.assign(globalThis, {
-  __turboModuleProxy: <T,>(name: string): T | null =>
-    name === 'RNBootSplash' && isPresent<T>(FAKE_NATIVE_MODULE) ? FAKE_NATIVE_MODULE : null,
-});
-
-const MANIFEST: IManifest = { background: '#fff', logo: { width: 100, height: 100 } };
-
-const results: IHideAnimationResult[] = [];
-
-function Probe(props: { config: IHideAnimationConfig }): ReactElement {
-  results.push(useHideAnimation(props.config));
-  return createElement(View);
-}
-
-const fabric = installFabric();
-
-beforeEach(() => {
-  fabric.reset();
-  results.length = 0;
-  vi.clearAllMocks();
-});
-
-afterEach(() => unmount(ROOT_TAG));
-
-describe('useHideAnimation', () => {
-  it('reports the skip sentinel and no onLoadEnd when logo is omitted', () => {
-    mount(ROOT_TAG, createElement(Probe, { config: { manifest: MANIFEST, animate: () => {} } }));
-
-    const last = results[results.length - 1];
-    expect(last.logo.source).toBe(-1);
-    expect(last.logo.onLoadEnd).toBeUndefined();
-  });
-
-  it('returns the full logo/brand shape when both are provided', () => {
-    const config: IHideAnimationConfig = {
-      manifest: { ...MANIFEST, brand: { bottom: 20, width: 60, height: 20 } },
-      logo: 123,
-      brand: 456,
-      animate: () => {},
-    };
-
-    mount(ROOT_TAG, createElement(Probe, { config }));
-
-    const last = results[results.length - 1];
-    expect(last.logo.source).toBe(123);
-    expect(last.logo.resizeMode).toBe('contain');
-    expect(last.brand.source).toBe(456);
-    expect(last.brand.resizeMode).toBe('contain');
-  });
-
-  it('hides exactly once, only after layout + logo load-end both resolve', async () => {
-    const { hide } = await import('react-native-bootsplash');
-    let animateCalls = 0;
-    const config: IHideAnimationConfig = {
-      manifest: MANIFEST,
-      logo: 1,
-      ready: true,
-      animate: () => {
-        animateCalls += 1;
-      },
-    };
-
-    mount(ROOT_TAG, createElement(Probe, { config }));
-    const result = results[results.length - 1];
-
-    expect(hide).not.toHaveBeenCalled();
-    result.container.onLayout();
-    expect(hide).not.toHaveBeenCalled();
-
-    result.logo.onLoadEnd?.();
-
-    expect(hide).toHaveBeenCalledTimes(1);
-    expect(hide).toHaveBeenCalledWith({ fade: false });
-    await vi.waitFor(() => expect(animateCalls).toBe(1));
-  });
-
-  it('does not hide again once already triggered', async () => {
-    const { hide } = await import('react-native-bootsplash');
-    const config: IHideAnimationConfig = { manifest: MANIFEST, ready: true, animate: () => {} };
-
-    mount(ROOT_TAG, createElement(Probe, { config }));
-    const result = results[results.length - 1];
-
-    result.container.onLayout();
-    await vi.waitFor(() => expect(hide).toHaveBeenCalledTimes(1));
-
-    result.container.onLayout();
-    expect(hide).toHaveBeenCalledTimes(1);
-  });
-});

package/src/vue/composables/use-hide-animation/use-hide-animation.test.ts

@@ -1,199 +0,0 @@
-// Co-located Vue-driven test (ADR 0025) for useHideAnimation. react-native-bootsplash's
-// TurboModule is faked (both its public JS API and the RNBootSplash native constants
-// module HideAnimationController/computeHideAnimationStyles reach through), so no real
-// native call fires. Proves the composable wires the framework-agnostic core's readiness
-// gate + style computation onto Vue's own reactivity: a getter-driven `ready` ref reactively
-// re-runs the watchEffect, hide() fires exactly once, and the returned computed reflects the
-// core's container/logo/brand shapes faithfully — including the "no logo" skip case.
-
-import { effectScope, nextTick, ref, type EffectScope, type Ref } from '@vue/runtime-core';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { hide } from 'react-native-bootsplash';
-import type { IStyleProp, IViewStyle } from '@symbiote-native/engine';
-import { useHideAnimation } from './index';
-import type { IHideAnimationConfig, IManifest } from '../../../core';
-
-vi.mock('react-native-bootsplash', () => ({
-  hide: vi.fn(() => Promise.resolve()),
-  isVisible: vi.fn(() => true),
-}));
-
-const FAKE_NATIVE_MODULE = {
-  getConstants: vi.fn(() => ({ darkModeEnabled: false })),
-  hide: vi.fn(() => Promise.resolve()),
-  isVisible: () => true,
-};
-
-const registeredNativeModules: Record<string, unknown> = { RNBootSplash: FAKE_NATIVE_MODULE };
-
-function isPresent<T>(value: unknown): value is T {
-  return value !== null && value !== undefined;
-}
-
-beforeEach(() => {
-  globalThis.__turboModuleProxy = <T>(name: string): T | null => {
-    const module = registeredNativeModules[name];
-    return isPresent<T>(module) ? module : null;
-  };
-});
-
-afterEach(() => {
-  globalThis.__turboModuleProxy = undefined;
-  vi.clearAllMocks();
-});
-
-const MANIFEST: IManifest = {
-  background: '#ffffff',
-  logo: { width: 100, height: 100 },
-  brand: { bottom: 40, width: 80, height: 20 },
-};
-
-// container.style is IStyleProp<IViewStyle> (union with the falsy/array style-composition
-// shapes), but computeHideAnimationStyles always hands back a plain object here — narrow it
-// once so the assertions can read .backgroundColor without an `as` cast.
-function isPlainViewStyle(style: IStyleProp<IViewStyle>): style is IViewStyle {
-  return typeof style === 'object' && style !== null && !Array.isArray(style);
-}
-
-function asViewStyle(style: IStyleProp<IViewStyle>): IViewStyle {
-  if (!isPlainViewStyle(style)) {
-    throw new Error('expected a plain view-style object');
-  }
-  return style;
-}
-
-function runInScope<T>(fn: () => T): { value: T; stop: () => void } {
-  const scope: EffectScope = effectScope();
-  const value = scope.run(fn);
-  if (value === undefined) {
-    throw new Error('effectScope.run() returned undefined');
-  }
-  return { value, stop: () => scope.stop() };
-}
-
-describe('useHideAnimation (Vue)', () => {
-  it('fires hide exactly once, only after layout + logo load + ready all become true', async () => {
-    const readyRef: Ref<boolean> = ref(false);
-    const animate = vi.fn();
-    const getConfig = (): IHideAnimationConfig => ({
-      manifest: MANIFEST,
-      logo: 1,
-      animate,
-      ready: readyRef.value,
-    });
-
-    const { value: result, stop } = runInScope(() => useHideAnimation(getConfig));
-
-    expect(hide).not.toHaveBeenCalled();
-
-    result.value.container.onLayout();
-    expect(hide, 'layout alone must not hide').not.toHaveBeenCalled();
-
-    expect(typeof result.value.logo.onLoadEnd).toBe('function');
-    result.value.logo.onLoadEnd?.();
-    expect(hide, 'layout + logo alone must not hide (ready still false)').not.toHaveBeenCalled();
-
-    readyRef.value = true;
-    await nextTick();
-    expect(hide).toHaveBeenCalledTimes(1);
-    expect(hide).toHaveBeenCalledWith({ fade: false });
-
-    stop();
-  });
-
-  it('does not fire hide again once it already fired', async () => {
-    const readyRef: Ref<boolean> = ref(true);
-    const getConfig = (): IHideAnimationConfig => ({
-      manifest: MANIFEST,
-      logo: 1,
-      animate: vi.fn(),
-      ready: readyRef.value,
-    });
-
-    const { value: result, stop } = runInScope(() => useHideAnimation(getConfig));
-
-    result.value.container.onLayout();
-    result.value.logo.onLoadEnd?.();
-    await nextTick();
-    expect(hide).toHaveBeenCalledTimes(1);
-
-    // Toggling ready off and back on must not re-run the already-fired animation.
-    readyRef.value = false;
-    await nextTick();
-    readyRef.value = true;
-    await nextTick();
-    expect(hide).toHaveBeenCalledTimes(1);
-
-    stop();
-  });
-
-  it('returns the container/logo/brand shapes for a config with both logo and brand', () => {
-    const getConfig = (): IHideAnimationConfig => ({
-      manifest: MANIFEST,
-      logo: 1,
-      brand: 2,
-      animate: vi.fn(),
-      ready: true,
-    });
-
-    const { value: result, stop } = runInScope(() => useHideAnimation(getConfig));
-    const { container, logo, brand } = result.value;
-
-    expect(asViewStyle(container.style).backgroundColor).toBe('#ffffff');
-    expect(typeof container.onLayout).toBe('function');
-
-    expect(logo.source).toBe(1);
-    expect(logo.style).toEqual({ width: 100, height: 100 });
-    expect(typeof logo.onLoadEnd).toBe('function');
-
-    expect(brand.source).toBe(2);
-    expect(brand.style).toEqual({
-      position: 'absolute',
-      bottom: 40,
-      width: 80,
-      height: 20,
-    });
-    expect(typeof brand.onLoadEnd).toBe('function');
-
-    stop();
-  });
-
-  it('skips the logo (source -1, no onLoadEnd) when config.logo is omitted', () => {
-    const getConfig = (): IHideAnimationConfig => ({
-      manifest: MANIFEST,
-      animate: vi.fn(),
-      ready: true,
-    });
-
-    const { value: result, stop } = runInScope(() => useHideAnimation(getConfig));
-    const { logo } = result.value;
-
-    expect(logo.source).toBe(-1);
-    expect('onLoadEnd' in logo).toBe(false);
-
-    stop();
-  });
-
-  it('reads the native constants exactly once, not on every recompute', () => {
-    const readyRef: Ref<boolean> = ref(false);
-    const getConfig = (): IHideAnimationConfig => ({
-      manifest: MANIFEST,
-      logo: 1,
-      animate: vi.fn(),
-      ready: readyRef.value,
-    });
-
-    const { value: result, stop } = runInScope(() => useHideAnimation(getConfig));
-
-    // Force several recomputes of the returned computed.
-    void result.value;
-    readyRef.value = true;
-    void result.value;
-    readyRef.value = false;
-    void result.value;
-
-    expect(FAKE_NATIVE_MODULE.getConstants).toHaveBeenCalledTimes(1);
-
-    stop();
-  });
-});