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

package/src/geometry.ts

@@ -1,42 +1,186 @@
+/* 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;
   width: number;
   height: number;
+  /** Default for every corner without an explicit override. */
   radius: number;
+  topLeftRadius?: number;
+  topRightRadius?: number;
+  bottomRightRadius?: number;
+  bottomLeftRadius?: number;
+  curve?: ClipCurve;
 }>;
 
-export type ClipBounds = Readonly<{
+export type CanonicalClipGeometry = Readonly<{
+  x: number;
+  y: number;
   width: number;
   height: number;
+  /** Canonical all-corners value; zero when the corner radii differ. */
+  radius: number;
+  topLeftRadius: number;
+  topRightRadius: number;
+  bottomRightRadius: number;
+  bottomLeftRadius: number;
+  curve: ClipCurve;
 }>;
 
 export type SmoothClipPresentation = Readonly<{
   clip: ClipGeometry;
   contentTranslateX: number;
   contentTranslateY: number;
+  /** Defaults to 1 when omitted. */
+  contentScale?: number;
+  boxShadow?: ClipBoxShadow;
 }>;
 
-export function createClipPresentation(
-  clip: ClipGeometry,
-  contentTranslateX = 0,
-  contentTranslateY = 0
-): SmoothClipPresentation {
+export type CanonicalSmoothClipPresentation = Readonly<{
+  clip: CanonicalClipGeometry;
+  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';
+}
+
+function isFiniteOptionalNumber(value: number | undefined): boolean {
   'worklet';
-  return { clip, contentTranslateX, contentTranslateY };
+  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.radius) &&
+    Number.isFinite(geometry.x + width) &&
+    Number.isFinite(geometry.y + height) &&
+    isFiniteOptionalNumber(geometry.topLeftRadius) &&
+    isFiniteOptionalNumber(geometry.topRightRadius) &&
+    isFiniteOptionalNumber(geometry.bottomRightRadius) &&
+    isFiniteOptionalNumber(geometry.bottomLeftRadius) &&
+    isClipCurve(geometry.curve)
   );
 }
 
+function resolvedTopLeftRadius(geometry: ClipGeometry): number {
+  'worklet';
+  return geometry.topLeftRadius ?? geometry.radius;
+}
+
+function resolvedTopRightRadius(geometry: ClipGeometry): number {
+  'worklet';
+  return geometry.topRightRadius ?? geometry.radius;
+}
+
+function resolvedBottomRightRadius(geometry: ClipGeometry): number {
+  'worklet';
+  return geometry.bottomRightRadius ?? geometry.radius;
+}
+
+function resolvedBottomLeftRadius(geometry: ClipGeometry): number {
+  'worklet';
+  return geometry.bottomLeftRadius ?? geometry.radius;
+}
+
+function resolvedCurve(geometry: ClipGeometry): ClipCurve {
+  'worklet';
+  return geometry.curve ?? 'circular';
+}
+
 export function clipGeometryEquals(
   first: ClipGeometry | null,
   second: ClipGeometry
@@ -48,18 +192,33 @@ export function clipGeometryEquals(
     first.y === second.y &&
     first.width === second.width &&
     first.height === second.height &&
-    first.radius === second.radius
+    first.radius === second.radius &&
+    resolvedTopLeftRadius(first) === resolvedTopLeftRadius(second) &&
+    resolvedTopRightRadius(first) === resolvedTopRightRadius(second) &&
+    resolvedBottomRightRadius(first) === resolvedBottomRightRadius(second) &&
+    resolvedBottomLeftRadius(first) === resolvedBottomLeftRadius(second) &&
+    resolvedCurve(first) === resolvedCurve(second)
   );
 }
 
+function resolvedContentScale(presentation: SmoothClipPresentation): number {
+  'worklet';
+  return presentation.contentScale ?? 1;
+}
+
 export function isFiniteClipPresentation(
   presentation: SmoothClipPresentation
 ): 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(presentation.contentTranslateY) &&
+    Number.isFinite(contentScale) &&
+    contentScale > 0 &&
+    shadow !== null
   );
 }
 
@@ -72,51 +231,140 @@ export function clipPresentationEquals(
     first !== null &&
     clipGeometryEquals(first.clip, second.clip) &&
     first.contentTranslateX === second.contentTranslateX &&
-    first.contentTranslateY === second.contentTranslateY
+    first.contentTranslateY === second.contentTranslateY &&
+    resolvedContentScale(first) === resolvedContentScale(second) &&
+    clipBoxShadowEquals(first.boxShadow, second.boxShadow)
   );
 }
 
+function createCanonicalClipGeometry(
+  geometry: ClipGeometry,
+  x: number,
+  y: number,
+  width: number,
+  height: number
+): CanonicalClipGeometry {
+  'worklet';
+  const topLeftRadius = Math.max(0, resolvedTopLeftRadius(geometry));
+  const topRightRadius = Math.max(0, resolvedTopRightRadius(geometry));
+  const bottomRightRadius = Math.max(0, resolvedBottomRightRadius(geometry));
+  const bottomLeftRadius = Math.max(0, resolvedBottomLeftRadius(geometry));
+
+  // CSS corner-overlap reduction uses one common factor so all four corners
+  // retain their proportions when either pair exceeds the available edge.
+  let scale = 1;
+  const top = topLeftRadius + topRightRadius;
+  const right = topRightRadius + bottomRightRadius;
+  const bottom = bottomLeftRadius + bottomRightRadius;
+  const left = topLeftRadius + bottomLeftRadius;
+
+  if (top > 0) scale = Math.min(scale, width / top);
+  if (right > 0) scale = Math.min(scale, height / right);
+  if (bottom > 0) scale = Math.min(scale, width / bottom);
+  if (left > 0) scale = Math.min(scale, height / left);
+  scale = Math.max(0, Math.min(1, scale));
+
+  const canonicalTopLeftRadius = topLeftRadius * scale;
+  const canonicalTopRightRadius = topRightRadius * scale;
+  const canonicalBottomRightRadius = bottomRightRadius * scale;
+  const canonicalBottomLeftRadius = bottomLeftRadius * scale;
+  const radius =
+    canonicalTopLeftRadius === canonicalTopRightRadius &&
+    canonicalTopRightRadius === canonicalBottomRightRadius &&
+    canonicalBottomRightRadius === canonicalBottomLeftRadius
+      ? canonicalTopLeftRadius
+      : 0;
+
+  return {
+    x,
+    y,
+    width,
+    height,
+    radius,
+    topLeftRadius: canonicalTopLeftRadius,
+    topRightRadius: canonicalTopRightRadius,
+    bottomRightRadius: canonicalBottomRightRadius,
+    bottomLeftRadius: canonicalBottomLeftRadius,
+    curve: resolvedCurve(geometry),
+  };
+}
+
 /**
- * Mirrors the native geometry contract for tests and non-native fallbacks.
- * Native remains authoritative because its bounds are the actual rendered size.
+ * Expands presentation defaults and applies CSS proportional corner scaling.
  */
-export function normalizeClipGeometry(
-  geometry: ClipGeometry,
-  bounds: ClipBounds
-): ClipGeometry | null {
+export function canonicalizeClipGeometry(
+  geometry: ClipGeometry
+): CanonicalClipGeometry | null {
   'worklet';
-  const values = [
+  if (!isFiniteClipGeometry(geometry)) return null;
+
+  const width = Math.max(0, geometry.width);
+  const height = Math.max(0, geometry.height);
+  return createCanonicalClipGeometry(
+    geometry,
     geometry.x,
     geometry.y,
-    geometry.width,
-    geometry.height,
-    geometry.radius,
-    bounds.width,
-    bounds.height,
-  ];
-
-  if (!values.every(Number.isFinite)) 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)
+    width,
+    height
   );
-  const width = Math.max(0, right - left);
-  const height = Math.max(0, bottom - top);
+}
+
+export function canonicalizeClipPresentation(
+  presentation: SmoothClipPresentation
+): CanonicalSmoothClipPresentation | null {
+  'worklet';
+  if (!isFiniteClipPresentation(presentation)) return null;
+
+  const clip = canonicalizeClipGeometry(presentation.clip);
+  if (clip === null) return null;
+  const boxShadow = canonicalizeClipBoxShadow(presentation.boxShadow);
+  if (boxShadow === null) return null;
 
   return {
-    x: left,
-    y: top,
-    width,
-    height,
-    radius: Math.min(Math.max(0, geometry.radius), Math.min(width, height) / 2),
+    clip,
+    contentTranslateX: presentation.contentTranslateX,
+    contentTranslateY: presentation.contentTranslateY,
+    contentScale: resolvedContentScale(presentation),
+    ...(boxShadow === undefined ? {} : { boxShadow }),
+  };
+}
+
+// Keep this below the canonicalization helpers so the worklet never closes
+// over a helper declared later in this module.
+export function createClipPresentation(
+  clip: ClipGeometry,
+  contentTranslateX = 0,
+  contentTranslateY = 0,
+  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.
+    clip: canonicalClip ?? {
+      x: clip.x,
+      y: clip.y,
+      width: clip.width,
+      height: clip.height,
+      radius: clip.radius,
+      topLeftRadius: resolvedTopLeftRadius(clip),
+      topRightRadius: resolvedTopRightRadius(clip),
+      bottomRightRadius: resolvedBottomRightRadius(clip),
+      bottomLeftRadius: resolvedBottomLeftRadius(clip),
+      curve: resolvedCurve(clip),
+    },
+    contentTranslateX,
+    contentTranslateY,
+    contentScale,
+    ...(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,
+        }),
   };
 }

package/src/groupTypes.ts

@@ -0,0 +1,53 @@
+import type {
+  SmoothClipAnimation,
+  SmoothClipCompletion,
+  SmoothClipReactRun,
+  SmoothClipRef,
+  SmoothClipRunHandle,
+} from './controllerTypes';
+import type {
+  CanonicalSmoothClipPresentation,
+  SmoothClipPresentation,
+} from './geometry';
+
+export type SmoothClipGroupFrame = Readonly<{
+  clip: SmoothClipRef;
+  frame: SmoothClipPresentation;
+}>;
+
+export type SmoothClipGroupTarget = Readonly<{
+  clip: SmoothClipRef;
+  target: SmoothClipPresentation;
+}>;
+
+export type SmoothClipGroupSnapshot = Readonly<{
+  clip: SmoothClipRef;
+  frame: CanonicalSmoothClipPresentation;
+  ready: boolean;
+}>;
+
+export type SmoothClipGroupOptions = Readonly<{
+  /** Stable React-runtime callback for UI- and React-runtime transactions. */
+  onAnimationComplete?: (result: SmoothClipCompletion) => void;
+}>;
+
+export type SmoothClipGroup = Readonly<{
+  ui: Readonly<{
+    setFrames(entries: readonly SmoothClipGroupFrame[]): void;
+    beginInteraction(
+      clips: readonly SmoothClipRef[]
+    ): readonly SmoothClipGroupSnapshot[];
+    animateTo(
+      entries: readonly SmoothClipGroupTarget[],
+      animation: SmoothClipAnimation,
+      completionTag?: number
+    ): SmoothClipRunHandle | null;
+    cancel(run: SmoothClipRunHandle): readonly SmoothClipGroupSnapshot[];
+  }>;
+  react: Readonly<{
+    animateTo(
+      entries: readonly SmoothClipGroupTarget[],
+      animation: SmoothClipAnimation
+    ): SmoothClipReactRun;
+  }>;
+}>;

package/src/groups.android.ts

@@ -0,0 +1 @@
+export { useSmoothClipGroup } from './groups.native';

package/src/groups.ios.ts

@@ -0,0 +1 @@
+export { useSmoothClipGroup } from './groups.native';