@symbiote-native/splash-screen 0.1.1

package/src/react/hooks/use-hide-animation.ts

@@ -0,0 +1,40 @@
+// React lifecycle wiring over the framework-agnostic HideAnimationController + style
+// computation (core/) — mirrors the lifecycle-bucket naming convention of
+// adapters/react/src/hooks. Faithful port of react-native-bootsplash's own useHideAnimation:
+// the controller is constructed lazily ONCE (a useRef factory, never reconstructed across
+// re-renders), native constants are read once via useState's lazy initializer (they never
+// change), and an effect with NO dependency array re-syncs the controller's config after
+// EVERY render — intentional, since `ready` flipping true only gets picked up this way.
+//
+// No useMemo around the style computation: upstream lists ~15 individual primitive fields
+// (manifest.logo.width, backgroundColor, ...) as its memo's deps specifically so Object.is
+// compares by VALUE, not by the `config`/`manifest` object's reference — callers construct
+// that object fresh on every render (the normal way to call this hook), so keying a memo off
+// the whole object would recompute every render anyway while looking like it memoizes.
+// Reproducing the fine-grained list isn't worth it for a splash screen shown for a couple of
+// renders at boot; computing plainly is honest about the actual cost and simpler to read.
+import { useEffect, useRef, useState } from 'react';
+import {
+  computeHideAnimationStyles,
+  getHideAnimationConstants,
+  HideAnimationController,
+  type IHideAnimationConfig,
+  type IHideAnimationConstants,
+  type IHideAnimationResult,
+} from '../../core';
+
+export function useHideAnimation(config: IHideAnimationConfig): IHideAnimationResult {
+  const controllerRef = useRef<HideAnimationController | null>(null);
+  if (controllerRef.current == null) {
+    controllerRef.current = new HideAnimationController(config);
+  }
+  const controller = controllerRef.current;
+
+  const [constants] = useState<IHideAnimationConstants>(() => getHideAnimationConstants());
+
+  useEffect(() => {
+    controller.updateConfig(config);
+  });
+
+  return computeHideAnimationStyles(config, constants, controller);
+}

package/src/react/index.ts

@@ -0,0 +1,9 @@
+// @symbiote-native/splash-screen/react: the React entry over the framework-agnostic core.
+// hide/isVisible carry zero lifecycle and are re-exported verbatim; useHideAnimation wraps
+// HideAnimationController + computeHideAnimationStyles with React's own lifecycle
+// (hooks/use-hide-animation.ts) — mirrors the lifecycle-bucket naming convention of
+// adapters/react/src/hooks (never `composables`, that's Vue's term).
+
+export { hide, isVisible } from '../core';
+export { useHideAnimation } from './hooks/use-hide-animation';
+export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';

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

@@ -0,0 +1,199 @@
+// 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 './use-hide-animation';
+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();
+  });
+});

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

@@ -0,0 +1,32 @@
+// Vue lifecycle wiring over the framework-agnostic HideAnimationController + style
+// computation (core/). A Vue composable's setup body runs ONCE (unlike a React hook,
+// which re-runs every render), so this takes a config GETTER, not a plain value — Vue's
+// reactivity tracks whatever reactive refs the getter reads internally and re-runs the
+// watchEffect/computed below on their change, mirroring how a React consumer would pass a
+// fresh config object on every render.
+//
+// The controller is a plain local, not a Vue ref: nothing needs Vue to react to the
+// controller reference itself (only its methods are called), so wrapping it would only
+// add an unnecessary reactive Proxy — same identity discipline as
+// `use-color-scheme.ts`'s subscription handle.
+import { computed, watchEffect, type ComputedRef } from '@vue/runtime-core';
+import {
+  computeHideAnimationStyles,
+  getHideAnimationConstants,
+  HideAnimationController,
+  type IHideAnimationConfig,
+  type IHideAnimationResult,
+} from '../../core';
+
+export function useHideAnimation(
+  getConfig: () => IHideAnimationConfig,
+): ComputedRef<IHideAnimationResult> {
+  const controller = new HideAnimationController(getConfig());
+  const constants = getHideAnimationConstants();
+
+  watchEffect(() => {
+    controller.updateConfig(getConfig());
+  });
+
+  return computed(() => computeHideAnimationStyles(getConfig(), constants, controller));
+}

package/src/vue/index.ts

@@ -0,0 +1,9 @@
+// @symbiote-native/splash-screen/vue: the Vue entry over the framework-agnostic core.
+// hide/isVisible carry zero lifecycle and are re-exported verbatim; useHideAnimation
+// wraps HideAnimationController + computeHideAnimationStyles with Vue's own reactivity
+// (composables/use-hide-animation.ts) — mirrors the lifecycle-bucket naming convention
+// of adapters/vue/src/composables (never `hooks/`, that's React's term).
+
+export { hide, isVisible } from '../core';
+export { useHideAnimation } from './composables/use-hide-animation';
+export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';

package/symbiote-splash-screen.podspec

@@ -0,0 +1,64 @@
+require 'json'
+require 'fileutils'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+native_splash_screen_package_json = `node --print "require.resolve('react-native-bootsplash/package.json', { paths: [process.argv[1]] })" "#{__dir__}"`.strip
+native_splash_screen_root = File.dirname(native_splash_screen_package_json)
+
+# CocoaPods' file glob never crosses a symlink (Sandbox::PathList#read_file_system walks the
+# pod dir with ONE recursive Dir.glob, and Ruby's `**` never descends into a symlinked
+# subdirectory it meets mid-walk). Under pnpm, react-native-bootsplash always sits behind a
+# .pnpm-store symlink, so pointing source_files at it in place silently produces zero matched
+# files -> CocoaPods downgrades the pod to an empty PBXAggregateTarget -> a runtime
+# NSClassFromString crash on first launch, not a build error. Fix: vendor (copy) the native iOS
+# sources into a gitignored folder next to this podspec on every `pod install`, and point
+# source_files at that copy (a purely-downward relative pattern).
+vendored_dir = File.join(__dir__, '.rn-bootsplash')
+
+FileUtils.rm_rf(vendored_dir)
+FileUtils.mkdir_p(vendored_dir)
+FileUtils.cp_r(File.join(native_splash_screen_root, 'ios'), File.join(vendored_dir, 'ios'))
+
+Pod::Spec.new do |s|
+  s.name         = 'symbiote-splash-screen'
+  s.version      = package['version']
+  s.summary      = 'Symbiote wrapper for the react-native-bootsplash native splash-screen module.'
+  s.license      = package['license'] || 'MIT'
+  s.authors      = package['author'] || 'symbiote'
+  s.homepage     = package['homepage'] || 'https://github.com/symbiote/symbiote'
+  s.platforms    = { :ios => '13.4' }
+  s.source       = { :git => 'https://github.com/symbiote/symbiote.git', :tag => "v#{s.version}" }
+
+  # react-native-bootsplash's own docs have callers `import RNBootSplash` directly in
+  # AppDelegate.swift — that import name is the Clang MODULE name, which CocoaPods derives
+  # from the pod's `s.name` unless told otherwise. Since this proxy pod is deliberately
+  # named after this package (`symbiote-splash-screen`, one-dependency-proxy pattern), the
+  # module would default to `symbiote_splash_screen` and break that import. Pin it back to
+  # the name upstream's native init instructions expect.
+  s.module_name  = 'RNBootSplash'
+
+  s.source_files = '.rn-bootsplash/ios/**/*.{h,m,mm}'
+
+  if defined?(install_modules_dependencies)
+    install_modules_dependencies(s)
+  else
+    s.dependency 'React-Core'
+    s.compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32 -DRCT_NEW_ARCH_ENABLED=1'
+    s.pod_target_xcconfig = {
+      'HEADER_SEARCH_PATHS' => '"$(PODS_ROOT)/boost"',
+      'OTHER_CPLUSPLUSFLAGS' => '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1',
+      'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17'
+    }
+    s.dependency 'ReactCommon/turbomodule/core'
+  end
+
+  # `module_name` alone only picks the NAME of the Clang module — it does not make CocoaPods
+  # generate one. For a static-library pod (no use_frameworks!), a module map is only emitted
+  # when DEFINES_MODULE is YES, and install_modules_dependencies(s) does not set it for us.
+  # Without this, `import RNBootSplash` in AppDelegate.swift fails with "no such module".
+  # `pod_target_xcconfig` has a DSL writer but no plain reader, so read the raw value back
+  # through `attributes_hash` (what install_modules_dependencies(s) already wrote into)
+  # instead of `s.pod_target_xcconfig`, which raises NoMethodError.
+  s.pod_target_xcconfig = (s.attributes_hash['pod_target_xcconfig'] || {}).merge('DEFINES_MODULE' => 'YES')
+end