react-native-smooth-clip-view 0.3.0 → 0.4.0

package/src/capabilities.native.ts

@@ -1,68 +1,18 @@
 import NativeSmoothClipModule from './smoothClipNative';
-import {
-  SMOOTH_CLIP_V1_CAPABILITIES,
-  type SmoothClipCapabilities,
-} from './capabilityTypes';
-
-type VersionedModule = typeof NativeSmoothClipModule & {
-  getPresentationProtocolVersion?: () => number;
-  supportsAutonomousComplexPathAnimation?: () => boolean;
-};
+import type { SmoothClipCapabilities } from './capabilityTypes';
 
 let cached: SmoothClipCapabilities | undefined;
 
 export function getSmoothClipCapabilities(): SmoothClipCapabilities {
   if (cached) return cached;
-  const module = NativeSmoothClipModule as VersionedModule;
-  let version = 1;
-  try {
-    version = module.getPresentationProtocolVersion?.() === 2 ? 2 : 1;
-  } catch {
-    version = 1;
-  }
-  if (version !== 2) {
-    cached = SMOOTH_CLIP_V1_CAPABILITIES;
-    return cached;
-  }
   let autonomousComplexPathAnimation = false;
   try {
     autonomousComplexPathAnimation =
-      module.supportsAutonomousComplexPathAnimation?.() === true;
+      NativeSmoothClipModule.supportsAutonomousComplexPathAnimation() === true;
   } catch {
     autonomousComplexPathAnimation = false;
   }
-  const groups =
-    typeof (
-      module as Partial<{
-        beginGroupInteractionV2: unknown;
-        snapshotGroupV2: unknown;
-        setClipPresentationBatchV2: unknown;
-        animateTimingGroupV2: unknown;
-        animateSpringGroupV2: unknown;
-        animateKeyframesGroupV2: unknown;
-        cancelAnimationGroupV2: unknown;
-      }>
-    ).beginGroupInteractionV2 === 'function' &&
-    typeof (module as Partial<{ snapshotGroupV2: unknown }>).snapshotGroupV2 ===
-      'function' &&
-    typeof (module as Partial<{ setClipPresentationBatchV2: unknown }>)
-      .setClipPresentationBatchV2 === 'function' &&
-    typeof (module as Partial<{ animateTimingGroupV2: unknown }>)
-      .animateTimingGroupV2 === 'function' &&
-    typeof (module as Partial<{ animateSpringGroupV2: unknown }>)
-      .animateSpringGroupV2 === 'function' &&
-    typeof (module as Partial<{ animateKeyframesGroupV2: unknown }>)
-      .animateKeyframesGroupV2 === 'function' &&
-    typeof (module as Partial<{ cancelAnimationGroupV2: unknown }>)
-      .cancelAnimationGroupV2 === 'function' &&
-    typeof (module as Partial<{ onClipGroupAnimationComplete: unknown }>)
-      .onClipGroupAnimationComplete === 'function';
   cached = {
-    presentationProtocolVersion: 2,
-    groups,
-    perCornerRadii: true,
-    continuousCurve: true,
-    contentScale: true,
     autonomousComplexPathAnimation,
   };
   return cached;

package/src/capabilityTypes.ts

@@ -1,17 +1,3 @@
 export type SmoothClipCapabilities = Readonly<{
-  presentationProtocolVersion: 1 | 2;
-  groups: boolean;
-  perCornerRadii: boolean;
-  continuousCurve: boolean;
-  contentScale: boolean;
   autonomousComplexPathAnimation: boolean;
 }>;
-
-export const SMOOTH_CLIP_V1_CAPABILITIES: SmoothClipCapabilities = {
-  presentationProtocolVersion: 1,
-  groups: false,
-  perCornerRadii: false,
-  continuousCurve: false,
-  contentScale: false,
-  autonomousComplexPathAnimation: false,
-};

package/src/controllerInternals.ts

@@ -0,0 +1,52 @@
+import type { SmoothClipController, SmoothClipRef } from './controllerTypes';
+import type { CanonicalSmoothClipPresentation } from './geometry';
+
+export type InternalSmoothClipController = Readonly<{
+  ref: SmoothClipRef;
+  initialFrame: CanonicalSmoothClipPresentation;
+}>;
+
+export type InternalSmoothClipRef = SmoothClipRef & Readonly<{ id: number }>;
+
+const controllers = new WeakMap<
+  SmoothClipController,
+  InternalSmoothClipController
+>();
+
+export function setControllerRef(
+  controller: SmoothClipController,
+  value: InternalSmoothClipController
+): void {
+  controllers.set(controller, value);
+}
+
+export function getControllerRef(
+  controller: SmoothClipController
+): InternalSmoothClipController {
+  const value = controllers.get(controller);
+  if (!value) {
+    throw new Error(
+      '[SmoothClipView] Controllers must be created by useSmoothClipController.'
+    );
+  }
+  return value;
+}
+
+export function unwrapSmoothClipRef(
+  ref: SmoothClipRef | undefined
+): InternalSmoothClipRef | undefined {
+  'worklet';
+  const internal = ref as InternalSmoothClipRef | undefined;
+  if (
+    internal === undefined ||
+    !Number.isSafeInteger(internal.id) ||
+    internal.id <= 0
+  ) {
+    return undefined;
+  }
+  return internal;
+}
+
+export function createSmoothClipRef(id: number): SmoothClipRef {
+  return { id } as InternalSmoothClipRef;
+}

package/src/controllerLifecycle.ts

@@ -0,0 +1,6 @@
+import NativeSmoothClipModule from './NativeSmoothClipModule';
+
+/** Destroy from the React Native runtime; native forwards to the UI thread. */
+export function destroyController(controllerId: number): void {
+  NativeSmoothClipModule.destroyDriver(controllerId);
+}

package/src/controllerTypes.ts

@@ -0,0 +1,87 @@
+import type {
+  CanonicalSmoothClipPresentation,
+  ClipGeometry,
+  SmoothClipPresentation,
+} from './geometry';
+
+export type ClipReduceMotion = 'system' | 'always' | 'never';
+
+type SmoothClipAnimationBase = Readonly<{
+  /** Resolved per transaction; it is never retained by the controller. */
+  reduceMotion?: ClipReduceMotion;
+}>;
+
+export type TimingClipAnimation = SmoothClipAnimationBase &
+  Readonly<{
+    type: 'timing';
+    duration: number;
+    controlPoints: readonly [number, number, number, number];
+  }>;
+
+export type SpringClipAnimation = SmoothClipAnimationBase &
+  Readonly<{
+    type: 'spring';
+    mass?: number;
+    stiffness?: number;
+    damping?: number;
+    /** Normalized progress velocity in inverse seconds. */
+    velocity?: number;
+    /** Relative mechanical energy used to determine settlement. */
+    energyThreshold?: number;
+  }>;
+
+export type SmoothClipAnimation = TimingClipAnimation | SpringClipAnimation;
+
+declare const smoothClipRefBrand: unique symbol;
+/** Opaque, worklet-safe identity for one mounted clip host. */
+export type SmoothClipRef = Readonly<{
+  readonly [smoothClipRefBrand]: true;
+}>;
+
+declare const smoothClipRunBrand: unique symbol;
+/** Opaque identity for a native transaction started on the UI runtime. */
+export type SmoothClipRunHandle = Readonly<{
+  readonly [smoothClipRunBrand]: true;
+}>;
+
+export type SmoothClipCompletion = Readonly<{
+  finished: boolean;
+  /** Present only when supplied by the UI-runtime caller. */
+  completionTag?: number;
+}>;
+
+export type SmoothClipReactRun = Readonly<{
+  finished: Promise<boolean>;
+  cancel(): void;
+}>;
+
+export type SmoothClipControllerOptions = Readonly<{
+  /** Stable React-runtime callback for UI- and React-runtime transactions. */
+  onAnimationComplete?: (result: SmoothClipCompletion) => void;
+}>;
+
+export type SmoothClipControllerUI = Readonly<{
+  beginInteraction(): CanonicalSmoothClipPresentation;
+  setFrame(frame: SmoothClipPresentation): void;
+  animateTo(
+    target: SmoothClipPresentation,
+    animation: SmoothClipAnimation,
+    completionTag?: number
+  ): SmoothClipRunHandle | null;
+  cancel(run: SmoothClipRunHandle): CanonicalSmoothClipPresentation;
+}>;
+
+export type SmoothClipControllerReact = Readonly<{
+  animateTo(
+    target: SmoothClipPresentation,
+    animation: SmoothClipAnimation
+  ): SmoothClipReactRun;
+}>;
+
+export type SmoothClipController = Readonly<{
+  ref: SmoothClipRef;
+  ui: SmoothClipControllerUI;
+  react: SmoothClipControllerReact;
+}>;
+
+export type SmoothClipInitialFrame = ClipGeometry | SmoothClipPresentation;

package/src/controllers.android.ts

@@ -0,0 +1 @@
+export { useSmoothClipController } from './controllers.native';

package/src/controllers.ios.ts

@@ -0,0 +1 @@
+export { useSmoothClipController } from './controllers.native';

package/src/controllers.native.ts

@@ -0,0 +1,104 @@
+import { useEffect, useRef } from 'react';
+import { scheduleOnUI } from 'react-native-worklets';
+import type {
+  SmoothClipController,
+  SmoothClipControllerOptions,
+  SmoothClipInitialFrame,
+} from './controllerTypes';
+import { createSmoothClipRef, setControllerRef } from './controllerInternals';
+import { destroyController } from './controllerLifecycle';
+import { allocateSmoothClipId } from './ids';
+import {
+  canonicalizeClipPresentation,
+  createClipPresentation,
+  type CanonicalSmoothClipPresentation,
+} from './geometry';
+import { useSmoothClipGroup } from './groups.native';
+import { presentationPacket } from './presentationCodec';
+import NativeSmoothClipModule from './smoothClipNative';
+
+const setClipPresentationHostFunction =
+  NativeSmoothClipModule.setClipPresentation;
+
+export function useSmoothClipController(
+  initialValue: SmoothClipInitialFrame,
+  options: SmoothClipControllerOptions = {}
+): SmoothClipController {
+  // A controller is intentionally a one-member transaction group. This keeps
+  // validation, native dispatch, cancellation, completion, and lifecycle races
+  // on the same path as multi-member transitions.
+  const group = useSmoothClipGroup(options);
+  const initialRequested =
+    'clip' in initialValue
+      ? initialValue
+      : createClipPresentation(initialValue);
+  const canonicalInitial = canonicalizeClipPresentation(initialRequested);
+  if (canonicalInitial === null) {
+    throw new Error('[SmoothClipView] Initial presentation must be finite.');
+  }
+  const initialFrameRef = useRef<CanonicalSmoothClipPresentation | null>(null);
+  initialFrameRef.current ??= canonicalInitial;
+  const initialFrame = initialFrameRef.current;
+
+  const idRef = useRef(0);
+  const controllerRef = useRef<SmoothClipController | null>(null);
+  if (idRef.current === 0) idRef.current = allocateSmoothClipId();
+  const controllerId = idRef.current;
+
+  if (controllerRef.current === null) {
+    const ref = createSmoothClipRef(controllerId);
+    const controller: SmoothClipController = {
+      ref,
+      ui: {
+        beginInteraction() {
+          'worklet';
+          return group.ui.beginInteraction([ref])[0]?.frame ?? initialFrame;
+        },
+        setFrame(frame) {
+          'worklet';
+          group.ui.setFrames([{ clip: ref, frame }]);
+        },
+        animateTo(target, animation, completionTag = 0) {
+          'worklet';
+          return group.ui.animateTo(
+            [{ clip: ref, target }],
+            animation,
+            completionTag
+          );
+        },
+        cancel(run) {
+          'worklet';
+          return group.ui.cancel(run)[0]?.frame ?? initialFrame;
+        },
+      },
+      react: {
+        animateTo(target, animation) {
+          return group.react.animateTo([{ clip: ref, target }], animation);
+        },
+      },
+    };
+    setControllerRef(controller, { ref, initialFrame });
+    controllerRef.current = controller;
+  }
+
+  useEffect(() => {
+    scheduleOnUI(
+      (id: number, frame: CanonicalSmoothClipPresentation) => {
+        'worklet';
+        setClipPresentationHostFunction(
+          id,
+          presentationPacket(frame),
+          true,
+          false
+        );
+      },
+      controllerId,
+      initialFrame
+    );
+    return () => {
+      destroyController(controllerId);
+    };
+  }, [controllerId, initialFrame]);
+
+  return controllerRef.current;
+}

package/src/controllers.ts

@@ -0,0 +1 @@
+export { useSmoothClipController } from './controllers.native';

package/src/geometry.ts

@@ -1,5 +1,28 @@
+/* eslint-disable no-bitwise -- React Native colors are converted to RRGGBBAA */
+import type { ColorValue } from 'react-native';
+import { processColor } from 'react-native-reanimated';
+
 export type ClipCurve = 'circular' | 'continuous';
 
+/** One numeric outset shadow following React Native's `boxShadow` field names. */
+export type ClipBoxShadow = Readonly<{
+  color?: ColorValue;
+  offsetX: number;
+  offsetY: number;
+  /** CSS box-shadow blur radius. iOS converts this to CALayer radius / 2. */
+  blurRadius?: number;
+  spreadDistance?: number;
+}>;
+
+export type CanonicalClipBoxShadow = Readonly<{
+  /** React Native numeric RRGGBBAA color; canonicalization is idempotent. */
+  color: ColorValue;
+  offsetX: number;
+  offsetY: number;
+  blurRadius: number;
+  spreadDistance: number;
+}>;
+
 export type ClipGeometry = Readonly<{
   x: number;
   y: number;
@@ -19,7 +42,7 @@ export type CanonicalClipGeometry = Readonly<{
   y: number;
   width: number;
   height: number;
-  /** Normalized legacy all-corners value retained for V1 compatibility. */
+  /** Canonical all-corners value; zero when the corner radii differ. */
   radius: number;
   topLeftRadius: number;
   topRightRadius: number;
@@ -28,17 +51,13 @@ export type CanonicalClipGeometry = Readonly<{
   curve: ClipCurve;
 }>;
 
-export type ClipBounds = Readonly<{
-  width: number;
-  height: number;
-}>;
-
 export type SmoothClipPresentation = Readonly<{
   clip: ClipGeometry;
   contentTranslateX: number;
   contentTranslateY: number;
   /** Defaults to 1 when omitted. */
   contentScale?: number;
+  boxShadow?: ClipBoxShadow;
 }>;
 
 export type CanonicalSmoothClipPresentation = Readonly<{
@@ -46,8 +65,11 @@ export type CanonicalSmoothClipPresentation = Readonly<{
   contentTranslateX: number;
   contentTranslateY: number;
   contentScale: number;
+  boxShadow?: CanonicalClipBoxShadow;
 }>;
 
+const DEFAULT_SHADOW_COLOR = '#000000ff';
+
 function isClipCurve(curve: ClipCurve | undefined): boolean {
   'worklet';
   return curve === undefined || curve === 'circular' || curve === 'continuous';
@@ -58,14 +80,74 @@ function isFiniteOptionalNumber(value: number | undefined): boolean {
   return value === undefined || Number.isFinite(value);
 }
 
+function canonicalizeClipBoxShadow(
+  shadow: ClipBoxShadow | undefined
+): CanonicalClipBoxShadow | null | undefined {
+  'worklet';
+  if (shadow === undefined) return undefined;
+  const { offsetX, offsetY } = shadow;
+  const blurRadius = shadow.blurRadius ?? 0;
+  const spreadDistance = shadow.spreadDistance ?? 0;
+  if (
+    !Number.isFinite(offsetX) ||
+    !Number.isFinite(offsetY) ||
+    !Number.isFinite(blurRadius) ||
+    !Number.isFinite(spreadDistance)
+  ) {
+    return null;
+  }
+  const processedColor =
+    shadow.color === undefined
+      ? processColor(DEFAULT_SHADOW_COLOR)
+      : processColor(shadow.color);
+  // Platform and dynamic colors cannot be represented by the scalar native
+  // animation protocol. Callers can resolve those colors before presenting.
+  if (typeof processedColor !== 'number') return null;
+  const unsignedProcessedColor = processedColor >>> 0;
+  const color =
+    ((unsignedProcessedColor << 8) | (unsignedProcessedColor >>> 24)) >>> 0;
+  return {
+    color: color as unknown as ColorValue,
+    offsetX,
+    offsetY,
+    blurRadius: Math.max(0, blurRadius),
+    spreadDistance,
+  };
+}
+
+function clipBoxShadowEquals(
+  first: ClipBoxShadow | undefined,
+  second: ClipBoxShadow | undefined
+): boolean {
+  'worklet';
+  if (first === undefined || second === undefined) return first === second;
+  const canonicalFirst = canonicalizeClipBoxShadow(first);
+  const canonicalSecond = canonicalizeClipBoxShadow(second);
+  return (
+    canonicalFirst !== null &&
+    canonicalFirst !== undefined &&
+    canonicalSecond !== null &&
+    canonicalSecond !== undefined &&
+    canonicalFirst.color === canonicalSecond.color &&
+    canonicalFirst.offsetX === canonicalSecond.offsetX &&
+    canonicalFirst.offsetY === canonicalSecond.offsetY &&
+    canonicalFirst.blurRadius === canonicalSecond.blurRadius &&
+    canonicalFirst.spreadDistance === canonicalSecond.spreadDistance
+  );
+}
+
 export function isFiniteClipGeometry(geometry: ClipGeometry): boolean {
   'worklet';
+  const width = Math.max(0, geometry.width);
+  const height = Math.max(0, geometry.height);
   return (
     Number.isFinite(geometry.x) &&
     Number.isFinite(geometry.y) &&
     Number.isFinite(geometry.width) &&
     Number.isFinite(geometry.height) &&
     Number.isFinite(geometry.radius) &&
+    Number.isFinite(geometry.x + width) &&
+    Number.isFinite(geometry.y + height) &&
     isFiniteOptionalNumber(geometry.topLeftRadius) &&
     isFiniteOptionalNumber(geometry.topRightRadius) &&
     isFiniteOptionalNumber(geometry.bottomRightRadius) &&
@@ -129,12 +211,14 @@ export function isFiniteClipPresentation(
 ): boolean {
   'worklet';
   const contentScale = resolvedContentScale(presentation);
+  const shadow = canonicalizeClipBoxShadow(presentation.boxShadow);
   return (
     isFiniteClipGeometry(presentation.clip) &&
     Number.isFinite(presentation.contentTranslateX) &&
     Number.isFinite(presentation.contentTranslateY) &&
     Number.isFinite(contentScale) &&
-    contentScale > 0
+    contentScale > 0 &&
+    shadow !== null
   );
 }
 
@@ -148,7 +232,8 @@ export function clipPresentationEquals(
     clipGeometryEquals(first.clip, second.clip) &&
     first.contentTranslateX === second.contentTranslateX &&
     first.contentTranslateY === second.contentTranslateY &&
-    resolvedContentScale(first) === resolvedContentScale(second)
+    resolvedContentScale(first) === resolvedContentScale(second) &&
+    clipBoxShadowEquals(first.boxShadow, second.boxShadow)
   );
 }
 
@@ -179,15 +264,15 @@ function createCanonicalClipGeometry(
   if (left > 0) scale = Math.min(scale, height / left);
   scale = Math.max(0, Math.min(1, scale));
 
-  const normalizedTopLeftRadius = topLeftRadius * scale;
-  const normalizedTopRightRadius = topRightRadius * scale;
-  const normalizedBottomRightRadius = bottomRightRadius * scale;
-  const normalizedBottomLeftRadius = bottomLeftRadius * scale;
+  const canonicalTopLeftRadius = topLeftRadius * scale;
+  const canonicalTopRightRadius = topRightRadius * scale;
+  const canonicalBottomRightRadius = bottomRightRadius * scale;
+  const canonicalBottomLeftRadius = bottomLeftRadius * scale;
   const radius =
-    normalizedTopLeftRadius === normalizedTopRightRadius &&
-    normalizedTopRightRadius === normalizedBottomRightRadius &&
-    normalizedBottomRightRadius === normalizedBottomLeftRadius
-      ? normalizedTopLeftRadius
+    canonicalTopLeftRadius === canonicalTopRightRadius &&
+    canonicalTopRightRadius === canonicalBottomRightRadius &&
+    canonicalBottomRightRadius === canonicalBottomLeftRadius
+      ? canonicalTopLeftRadius
       : 0;
 
   return {
@@ -196,10 +281,10 @@ function createCanonicalClipGeometry(
     width,
     height,
     radius,
-    topLeftRadius: normalizedTopLeftRadius,
-    topRightRadius: normalizedTopRightRadius,
-    bottomRightRadius: normalizedBottomRightRadius,
-    bottomLeftRadius: normalizedBottomLeftRadius,
+    topLeftRadius: canonicalTopLeftRadius,
+    topRightRadius: canonicalTopRightRadius,
+    bottomRightRadius: canonicalBottomRightRadius,
+    bottomLeftRadius: canonicalBottomLeftRadius,
     curve: resolvedCurve(geometry),
   };
 }
@@ -232,12 +317,15 @@ export function canonicalizeClipPresentation(
 
   const clip = canonicalizeClipGeometry(presentation.clip);
   if (clip === null) return null;
+  const boxShadow = canonicalizeClipBoxShadow(presentation.boxShadow);
+  if (boxShadow === null) return null;
 
   return {
     clip,
     contentTranslateX: presentation.contentTranslateX,
     contentTranslateY: presentation.contentTranslateY,
     contentScale: resolvedContentScale(presentation),
+    ...(boxShadow === undefined ? {} : { boxShadow }),
   };
 }
 
@@ -247,10 +335,12 @@ export function createClipPresentation(
   clip: ClipGeometry,
   contentTranslateX = 0,
   contentTranslateY = 0,
-  contentScale = 1
+  contentScale = 1,
+  boxShadow?: ClipBoxShadow
 ): CanonicalSmoothClipPresentation {
   'worklet';
   const canonicalClip = canonicalizeClipGeometry(clip);
+  const canonicalShadow = canonicalizeClipBoxShadow(boxShadow);
   return {
     // Keep invalid input observably invalid so downstream validation remains
     // atomic instead of accidentally sanitizing a required scalar.
@@ -269,58 +359,12 @@ export function createClipPresentation(
     contentTranslateX,
     contentTranslateY,
     contentScale,
-  };
-}
-
-/**
- * Mirrors the native geometry contract for tests and non-native fallbacks.
- * Native remains authoritative because its bounds are the actual rendered size.
- */
-export function normalizeClipGeometry(
-  geometry: ClipGeometry,
-  bounds: ClipBounds
-): CanonicalClipGeometry | null {
-  'worklet';
-  if (
-    !isFiniteClipGeometry(geometry) ||
-    !Number.isFinite(bounds.width) ||
-    !Number.isFinite(bounds.height)
-  ) {
-    return null;
-  }
-
-  const boundsWidth = Math.max(0, bounds.width);
-  const boundsHeight = Math.max(0, bounds.height);
-  const requestedWidth = Math.max(0, geometry.width);
-  const requestedHeight = Math.max(0, geometry.height);
-
-  const left = Math.min(boundsWidth, Math.max(0, geometry.x));
-  const top = Math.min(boundsHeight, Math.max(0, geometry.y));
-  const right = Math.min(boundsWidth, Math.max(0, geometry.x + requestedWidth));
-  const bottom = Math.min(
-    boundsHeight,
-    Math.max(0, geometry.y + requestedHeight)
-  );
-  const width = Math.max(0, right - left);
-  const height = Math.max(0, bottom - top);
-
-  return createCanonicalClipGeometry(geometry, left, top, width, height);
-}
-
-export function normalizeClipPresentation(
-  presentation: SmoothClipPresentation,
-  bounds: ClipBounds
-): CanonicalSmoothClipPresentation | null {
-  'worklet';
-  if (!isFiniteClipPresentation(presentation)) return null;
-
-  const clip = normalizeClipGeometry(presentation.clip, bounds);
-  if (clip === null) return null;
-
-  return {
-    clip,
-    contentTranslateX: presentation.contentTranslateX,
-    contentTranslateY: presentation.contentTranslateY,
-    contentScale: resolvedContentScale(presentation),
+    ...(canonicalShadow === undefined
+      ? {}
+      : {
+          // Match the geometry constructor's invalid-input behavior: retain the
+          // bad source value so the driver's atomic validation rejects it.
+          boxShadow: (canonicalShadow ?? boxShadow) as CanonicalClipBoxShadow,
+        }),
   };
 }