@seed-design/lynx-react 0.6.2 → 0.7.0

package/src/hooks/useScaleFeedback.ts

@@ -0,0 +1,199 @@
+import {
+  runOnMainThread,
+  runOnBackground,
+  useEffect,
+  useGlobalProps,
+  useMainThreadRef,
+  useRef,
+} from "@lynx-js/react";
+import type { RefObject } from "@lynx-js/react";
+import type { MainThread } from "@lynx-js/types";
+import {
+  feedbackScaleDuration,
+  feedbackScaleTimingFunction,
+} from "@seed-design/lynx-css/scale-feedback";
+
+import type { LynxViewProps } from "../types";
+import { calculateScaleFeedback, isReducedMotion } from "../utils/calculate-scale-feedback";
+
+type MainThreadLayoutChangeHandler = NonNullable<LynxViewProps["main-thread:bindlayoutchange"]>;
+type MainThreadTouchHandler = NonNullable<LynxViewProps["main-thread:bindtouchstart"]>;
+
+interface SeedMotionGlobalProps {
+  motion?: unknown;
+}
+
+interface ScaleFeedbackElement extends MainThread.Element {
+  getComputedStyleProperty(styleName: string): string;
+}
+
+export interface UseScaleFeedbackOptions {
+  /** Disables Scale Feedback while the target is not interactive. */
+  disabled?: boolean;
+  /** Runs on the Background Thread immediately after Main Thread touchstart. */
+  onTouchStart?: () => void;
+  /** Runs on the Background Thread immediately after Main Thread touchend. */
+  onTouchEnd?: () => void;
+  /** Runs on the Background Thread immediately after Main Thread touchcancel. */
+  onTouchCancel?: () => void;
+}
+
+export interface ScaleFeedbackTriggerProps {
+  "main-thread:bindtouchstart": MainThreadTouchHandler;
+  "main-thread:bindtouchend": MainThreadTouchHandler;
+  "main-thread:bindtouchcancel": MainThreadTouchHandler;
+}
+
+/** The target's transform is owned by Scale Feedback; use a separate layer for other transforms. */
+export interface ScaleFeedbackTargetProps {
+  flatten: false;
+  "main-thread:ref": NonNullable<LynxViewProps["main-thread:ref"]>;
+  "main-thread:bindlayoutchange": MainThreadLayoutChangeHandler;
+}
+
+export interface UseScaleFeedbackReturn {
+  /** Spread onto the element that receives touch events. */
+  scaleFeedbackTriggerProps: ScaleFeedbackTriggerProps;
+  /** Spread onto the element that is measured and scaled. */
+  scaleFeedbackTargetProps: ScaleFeedbackTargetProps;
+}
+
+function runScaleFeedback(
+  targetRef: RefObject<ScaleFeedbackElement | null>,
+  animationRef: RefObject<MainThread.Animation | null>,
+  scale: number,
+  duration: number,
+) {
+  "main thread";
+
+  const target = targetRef.current;
+  if (!target) return;
+
+  let currentTransform = "scale(1)";
+  try {
+    currentTransform = target.getComputedStyleProperty("transform") || currentTransform;
+  } catch {
+    // Some non-native runtimes expose the method but cannot evaluate it.
+  }
+
+  animationRef.current?.cancel();
+  animationRef.current = target.animate(
+    [{ transform: currentTransform }, { transform: `scale(${scale})` }],
+    {
+      duration,
+      easing: feedbackScaleTimingFunction,
+      fill: "forwards",
+    },
+  );
+}
+
+function readScaleFeedbackScale(target: ScaleFeedbackElement | null): number | null {
+  "main thread";
+
+  if (!target) return null;
+
+  let width = 0;
+  let height = 0;
+  try {
+    // Retry at touchstart when no valid layout measurement is cached,
+    // including targets that initially reported a 0x0 layout.
+    width = Number.parseFloat(target.getComputedStyleProperty("width"));
+    height = Number.parseFloat(target.getComputedStyleProperty("height"));
+  } catch {
+    return null;
+  }
+
+  if (width <= 0 || height <= 0 || Number.isNaN(width) || Number.isNaN(height)) return null;
+
+  return calculateScaleFeedback(width, height);
+}
+
+/**
+ * Applies SEED Scale Feedback on the Lynx Main Thread.
+ *
+ * Spread `scaleFeedbackTriggerProps` onto the element that receives touch
+ * events and `scaleFeedbackTargetProps` onto the element that should scale.
+ * Applying both objects to one element creates Self Scale; applying them to
+ * separate elements creates Content Scale.
+ *
+ * The target's transform is owned by this hook. Use a separate content layer
+ * when the element already uses translate, rotate, or another transform.
+ *
+ * Supported on Lynx Engine 3.9 and later. Missing or unknown
+ * `GlobalProps.motion` values preserve the default motion; only the exact
+ * `"reduced"` value disables scaling.
+ */
+export function useScaleFeedback(options: UseScaleFeedbackOptions = {}): UseScaleFeedbackReturn {
+  const { disabled = false, onTouchStart, onTouchEnd, onTouchCancel } = options;
+  const globalProps = useGlobalProps() as SeedMotionGlobalProps | undefined;
+  const reducedMotion = isReducedMotion(globalProps?.motion);
+  const targetRef = useMainThreadRef<ScaleFeedbackElement | null>(null);
+  const animationRef = useMainThreadRef<MainThread.Animation>(null);
+  const scaleRef = useMainThreadRef<number | null>(null);
+  const hasMountedRef = useRef(false);
+
+  function handleLayoutChange(event: MainThread.LayoutChangeEvent) {
+    "main thread";
+
+    targetRef.current = event.currentTarget as ScaleFeedbackElement;
+    const width = event.detail?.width ?? event.params?.width ?? 0;
+    const height = event.detail?.height ?? event.params?.height ?? 0;
+    if (width > 0 && height > 0) {
+      scaleRef.current = calculateScaleFeedback(width, height);
+    } else {
+      scaleRef.current = null;
+    }
+    targetRef.current?.setStyleProperty("transform-origin", "center center");
+  }
+
+  function handleTouchStart() {
+    "main thread";
+
+    if (!disabled && !reducedMotion) {
+      const scale = scaleRef.current ?? readScaleFeedbackScale(targetRef.current);
+      if (scale !== null) {
+        scaleRef.current = scale;
+        runScaleFeedback(targetRef, animationRef, scale, feedbackScaleDuration);
+      }
+    }
+    if (onTouchStart) runOnBackground(onTouchStart)();
+  }
+
+  function handleTouchEnd() {
+    "main thread";
+
+    runScaleFeedback(targetRef, animationRef, 1, feedbackScaleDuration);
+    if (onTouchEnd) runOnBackground(onTouchEnd)();
+  }
+
+  function handleTouchCancel() {
+    "main thread";
+
+    runScaleFeedback(targetRef, animationRef, 1, feedbackScaleDuration);
+    if (onTouchCancel) runOnBackground(onTouchCancel)();
+  }
+
+  useEffect(() => {
+    if (!hasMountedRef.current) {
+      hasMountedRef.current = true;
+      return;
+    }
+    if (!disabled && !reducedMotion) return;
+
+    runOnMainThread(runScaleFeedback)(targetRef, animationRef, 1, 0);
+  }, [disabled, reducedMotion]);
+
+  return {
+    scaleFeedbackTriggerProps: {
+      "main-thread:bindtouchstart": handleTouchStart,
+      "main-thread:bindtouchend": handleTouchEnd,
+      "main-thread:bindtouchcancel": handleTouchCancel,
+    },
+    scaleFeedbackTargetProps: {
+      // Preserve a native view for transform animations instead of allowing Lynx to flatten it.
+      flatten: false,
+      "main-thread:ref": targetRef,
+      "main-thread:bindlayoutchange": handleLayoutChange,
+    },
+  };
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./components";
+export * from "./contexts";
 export * from "./hooks";
 export type * from "./types";
 export * from "./utils";

package/src/utils/calculate-scale-feedback.ts

@@ -0,0 +1,12 @@
+/** Calculates SEED's fixed-distance scale ratio directly on the Main Thread. */
+export function calculateScaleFeedback(width: number, height: number): number {
+  "main thread";
+
+  const basis = Math.max(height, width / 4, 24);
+  return basis > 0 ? (basis - 2) / basis : 1;
+}
+
+/** Treats unknown values as default motion and matches only the exact reduced value. */
+export function isReducedMotion(value: unknown): boolean {
+  return value === "reduced";
+}

package/src/utils/compose-event-handlers.ts

@@ -0,0 +1,16 @@
+type Handler = (...args: any[]) => unknown;
+
+export function composeEventHandlers(first: Handler, second: Handler): Handler {
+  return (...args) => {
+    first(...args);
+    second(...args);
+  };
+}
+
+export function composeMainThreadEventHandlers(first: Handler, second: Handler): Handler {
+  return (...args) => {
+    "main thread";
+    first(...args);
+    second(...args);
+  };
+}

package/src/utils/create-slot-recipe-context.tsx

@@ -8,6 +8,7 @@ import type {
   RefAttributes,
 } from "@lynx-js/react";
 import clsx from "clsx";
+import { mergeProps } from "./merge-props";
 
 type SlotRecipe<
   Props extends Record<string, string | boolean | undefined>,
@@ -105,7 +106,7 @@ export function createSlotRecipeContext<
     const { defaultProps } = options ?? {};
 
     const StyledComponent = (innerProps: any) => {
-      const props = { ...(defaultProps ?? {}), ...useProps(), ...innerProps } as Props &
+      const props = mergeProps(defaultProps ?? {}, useProps() ?? {}, innerProps) as Props &
         Record<string, unknown>;
 
       restoreDefaultProps(props, defaultProps);
@@ -139,7 +140,7 @@ export function createSlotRecipeContext<
     const { defaultProps } = options ?? {};
 
     const StyledComponent = forwardRef<any, any>((innerProps, ref) => {
-      const props: any = { ...(defaultProps ?? {}), ...useProps(), ...innerProps };
+      const props: any = mergeProps(defaultProps ?? {}, useProps() ?? {}, innerProps);
 
       restoreDefaultProps(props, defaultProps);
 
@@ -152,8 +153,7 @@ export function createSlotRecipeContext<
         <ClassNamesProvider value={classNames}>
           <PropsProvider value={variantProps}>
             <Component
-              {...(ref ? { ref } : {})}
-              {...otherProps}
+              {...mergeProps(ref ? { ref } : {}, otherProps)}
               className={clsx(slotClassName, userClassName)}
             />
           </PropsProvider>
@@ -177,7 +177,7 @@ export function createSlotRecipeContext<
     const { defaultProps } = options ?? {};
 
     const StyledComponent = forwardRef<any, any>((innerProps, ref) => {
-      const props: any = { ...(defaultProps ?? {}), ...innerProps };
+      const props: any = mergeProps(defaultProps ?? {}, innerProps);
 
       restoreDefaultProps(props, defaultProps);
 
@@ -187,8 +187,7 @@ export function createSlotRecipeContext<
 
       return (
         <Component
-          {...(ref ? { ref } : {})}
-          {...props}
+          {...mergeProps(ref ? { ref } : {}, props)}
           className={clsx(slotClassName, userClassName)}
         />
       );

package/src/utils/index.ts

@@ -2,3 +2,4 @@ export * from "./create-slot-recipe-context";
 export * from "./get-seed-class-name";
 export * from "./resolve-recipe-token";
 export * from "./split-multiple-variants-props";
+export * from "./merge-props";

package/src/utils/merge-props.test.tsx

@@ -0,0 +1,152 @@
+import { createRef, runOnBackground, useMainThreadRef } from "@lynx-js/react";
+import { fireEvent, render, waitSchedule } from "@lynx-js/react/testing-library";
+import { describe, expect, it, vi } from "vitest";
+import { mergeProps } from "./merge-props";
+
+describe("mergeProps", () => {
+  it("preserves props and chains only identical event keys, user first", () => {
+    const calls: string[] = [];
+    const base = {
+      className: "seed",
+      style: { width: "10px", color: "red" },
+      bindtap: () => calls.push("base"),
+    };
+    const user = {
+      className: "user",
+      style: { color: "blue" },
+      bindtap: () => {
+        calls.push("user");
+        return false;
+      },
+    };
+    const props = mergeProps(base, user, { className: undefined });
+    props.bindtap();
+    expect(calls).toEqual(["user", "base"]);
+    expect(props.className).toBe("seed user");
+    expect(props.style).toEqual({ width: "10px", color: "blue" });
+    expect(base.style.color).toBe("red");
+    expect(mergeProps({ bindtap: base.bindtap }, { catchtap: user.bindtap })).toEqual({
+      bindtap: base.bindtap,
+      catchtap: user.bindtap,
+    });
+    expect(mergeProps({ ref: null })).toEqual({});
+    const ref = createRef();
+    expect(mergeProps({ ref }, { ref: null }).ref).toBe(ref);
+    expect(mergeProps({ "main-thread:ref": ref })["main-thread:ref"]).toBe(ref);
+  });
+
+  it("preserves three refs across replacement and unmount", async () => {
+    const ref = createRef<unknown>();
+    const cleanup = vi.fn();
+    const first = vi.fn(() => cleanup);
+    const next = vi.fn();
+    const observer = vi.fn();
+    function Example({ callback }: { callback: (value: unknown) => void | (() => void) }) {
+      return <view {...mergeProps({ ref }, { ref: callback }, { ref: observer })} />;
+    }
+    const { rerender, unmount } = render(<Example callback={first} />);
+    await waitSchedule();
+    expect(ref.current).toBeTruthy();
+    expect(first).toHaveBeenLastCalledWith(ref.current);
+    expect(observer).toHaveBeenLastCalledWith(ref.current);
+    rerender(<Example callback={next} />);
+    await waitSchedule();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(observer.mock.calls[1]).toEqual([null]);
+    expect(observer).toHaveBeenLastCalledWith(ref.current);
+    unmount();
+    await waitSchedule();
+    expect(ref.current).toBeNull();
+    expect(next).toHaveBeenLastCalledWith(null);
+    expect(observer).toHaveBeenLastCalledWith(null);
+    expect(observer).toHaveBeenCalledTimes(4);
+  });
+
+  it("composes compiled Main Thread handlers and refreshes captures", async () => {
+    function Example({ report }: { report: (value: string) => void }) {
+      function base() {
+        "main thread";
+        runOnBackground(report)("base");
+      }
+      function user() {
+        "main thread";
+        runOnBackground(report)("user");
+      }
+      return (
+        <view
+          id="target"
+          {...mergeProps(
+            { "main-thread:bindtouchstart": base },
+            { "main-thread:bindtouchstart": user },
+          )}
+        />
+      );
+    }
+    const report = vi.fn();
+    const next = vi.fn();
+    const { container, rerender } = render(<Example report={report} />, {
+      enableMainThread: true,
+      enableBackgroundThread: true,
+    });
+    await waitSchedule();
+    fireEvent.touchstart(container.querySelector("#target")!, {});
+    await waitSchedule();
+    expect(report.mock.calls).toEqual([["user"], ["base"]]);
+    rerender(<Example report={next} />);
+    await waitSchedule();
+    fireEvent.touchstart(container.querySelector("#target")!, {});
+    await waitSchedule();
+    expect(next.mock.calls).toEqual([["user"], ["base"]]);
+    expect(report).toHaveBeenCalledTimes(2);
+  });
+
+  it("composes three Main Thread refs and runs cleanup in source order", async () => {
+    function Example({ report, show = true }: { report: (value: string) => void; show?: boolean }) {
+      const target = useMainThreadRef(null);
+      const status = useMainThreadRef("initial");
+      function callback() {
+        "main thread";
+        status.current = target.current ? "attached" : "missing";
+        return () => {
+          status.current = target.current === null ? "cleaned" : "uncleared";
+        };
+      }
+      function inspect() {
+        "main thread";
+        runOnBackground(report)(status.current);
+      }
+      function observer(value: unknown) {
+        "main thread";
+        status.current += value ? ":observed" : ":detached";
+      }
+      return (
+        <view>
+          <view id="inspect" main-thread:bindtap={inspect} />
+          {show && (
+            <view
+              {...mergeProps(
+                { "main-thread:ref": target },
+                { "main-thread:ref": callback },
+                { "main-thread:ref": observer },
+              )}
+            />
+          )}
+        </view>
+      );
+    }
+    const report = vi.fn();
+    const { container, rerender } = render(<Example report={report} />, {
+      enableMainThread: true,
+      enableBackgroundThread: true,
+    });
+    await waitSchedule();
+    fireEvent.tap(container.querySelector("#inspect")!);
+    await waitSchedule();
+    expect(report.mock.calls).toEqual([["attached:observed"]]);
+    rerender(<Example report={report} show={false} />);
+    await waitSchedule();
+    fireEvent.tap(container.querySelector("#inspect")!);
+    await waitSchedule();
+    expect(report.mock.calls).toEqual([["attached:observed"], ["cleaned:detached"]]);
+  });
+});

package/src/utils/merge-props.ts

@@ -0,0 +1,62 @@
+import clsx from "clsx";
+import { composeEventHandlers, composeMainThreadEventHandlers } from "./compose-event-handlers";
+import { mergeRefs, mergeMainThreadRefs, type Ref } from "./merge-refs";
+
+type Props = Record<string, any>;
+type Merge<A, B> = Omit<A, keyof B> & {
+  [K in keyof B]: undefined extends B[K]
+    ? Exclude<B[K], undefined> | (K extends keyof A ? A[K] : undefined)
+    : B[K];
+};
+type Merged<T extends object[], Result = {}> = T extends [
+  infer First extends object,
+  ...infer Rest extends object[],
+]
+  ? Merged<Rest, Merge<Result, First>>
+  : Result;
+
+const nativeEvent = /^(?:main-thread:)?(?:(?:capture|global)-)?(?:bind|catch)[a-z]/;
+const callbackEvent = /^on[A-Z]/;
+
+/**
+ * Merges props without changing event threads or propagation modes.
+ * Same-key handlers run last-source first, matching SEED React. Return values
+ * and preventDefault do not cancel another handler. Ref cleanup is preserved.
+ */
+export function mergeProps<T extends object[]>(...sources: T): Merged<T> {
+  const result: Props = {};
+  const refs: Ref<unknown>[] = [];
+  const mainThreadRefs: Ref<unknown>[] = [];
+  for (const source of sources) {
+    for (const [key, value] of Object.entries(source)) {
+      if (value === undefined) continue;
+      const previous = result[key];
+      if (key === "ref" || key === "main-thread:ref") {
+        if (value == null) continue;
+        const targetRefs = key === "ref" ? refs : mainThreadRefs;
+        targetRefs.push(value as Ref<unknown>);
+      } else if (key === "className") {
+        result[key] = clsx(previous, value as string);
+      } else if (key === "style" && typeof value === "object" && value !== null) {
+        result[key] = { ...(typeof previous === "object" ? previous : {}), ...value };
+      } else if (nativeEvent.test(key) || callbackEvent.test(key)) {
+        if (previous && value) {
+          const compose = key.startsWith("main-thread:")
+            ? composeMainThreadEventHandlers
+            : composeEventHandlers;
+          result[key] = compose(value as any, previous);
+        } else {
+          result[key] = value;
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+  if (refs.length) result["ref"] = refs.length === 1 ? refs[0] : mergeRefs(...refs);
+  if (mainThreadRefs.length) {
+    result["main-thread:ref"] =
+      mainThreadRefs.length === 1 ? mainThreadRefs[0] : mergeMainThreadRefs(...mainThreadRefs);
+  }
+  return result as Merged<T>;
+}

package/src/utils/merge-refs.ts

@@ -0,0 +1,44 @@
+type Cleanup = void | (() => void);
+export type Ref<T> = { current: T | null } | ((value: T | null) => Cleanup);
+
+function setRef<T>(ref: Ref<T>, value: T | null): Cleanup {
+  if (typeof ref === "function") return ref(value);
+  ref.current = value;
+}
+
+function setMainThreadRef<T>(ref: Ref<T>, value: T | null): Cleanup {
+  "main thread";
+  if (typeof ref === "function") return ref(value);
+  ref.current = value;
+}
+
+export function mergeRefs<T>(...refs: Ref<T>[]): Ref<T> {
+  return (value) => {
+    const cleanups = refs.map((ref) => setRef(ref, value));
+    return () => {
+      refs.forEach((ref, index) => {
+        const cleanup = cleanups[index];
+        if (cleanup) cleanup();
+        else setRef(ref, null);
+      });
+    };
+  };
+}
+
+export function mergeMainThreadRefs<T>(...refs: Ref<T>[]): Ref<T> {
+  return (value) => {
+    "main thread";
+    const cleanups: Cleanup[] = [];
+    // Indexed access preserves the captured array in the Main Thread compiler.
+    for (let index = 0; index < refs.length; index++) {
+      cleanups.push(setMainThreadRef(refs[index], value));
+    }
+    return () => {
+      for (let index = 0; index < refs.length; index++) {
+        const cleanup = cleanups[index];
+        if (cleanup) cleanup();
+        else setMainThreadRef(refs[index], null);
+      }
+    };
+  };
+}