@seed-design/lynx-react 0.6.2 → 0.7.0

package/src/components/private/Positioning.ts

@@ -0,0 +1,223 @@
+import {
+  arrow as arrowMiddleware,
+  computePosition as computeFloatingPosition,
+  flip,
+  limitShift,
+  offset,
+  shift,
+  size,
+  type Platform,
+  type Rect as FloatingRect,
+} from "@floating-ui/core";
+
+export type Side = "top" | "right" | "bottom" | "left";
+export type Placement = Side | `${Side}-${"start" | "end"}`;
+
+export interface Rect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+export interface Position {
+  /** 가용 크기는 콘텐츠 크기와 별개이며 0 이상입니다. */
+  availableWidth: number;
+  availableHeight: number;
+  /** 콘텐츠 내부 좌표입니다. 나머지 축은 placement의 반대쪽 가장자리에 붙입니다. */
+  arrow?: { left?: number; top?: number; centerOffset: number };
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  placement: Placement;
+  transformOrigin: string;
+}
+
+interface ReferenceElement {
+  rect: FloatingRect;
+}
+
+interface FloatingElement {
+  dimensions: {
+    width: number;
+    height: number;
+  };
+}
+
+export interface PositioningOptions {
+  placement: Placement;
+  gutter: number;
+  overflowPadding: number;
+  flip?:
+    | false
+    | {
+        fallbackStrategy?: "bestFit" | "initialPlacement";
+        fallbackPlacements?: Placement[];
+      };
+  shift?:
+    | false
+    | {
+        mainAxis?: boolean;
+        crossAxis?: boolean;
+        /** reference에서 완전히 떨어지지 않도록 이동을 제한합니다. */
+        limit?: boolean;
+      };
+  /** 생략하면 원래 높이를 보존합니다. 너비 제한은 호출자가 적용합니다. */
+  size?: {
+    order: "beforeFlip" | "afterShift";
+    minimumHeight?: number;
+  };
+  arrow?: {
+    /** 회전 가능한 정사각형 화살표 컨테이너의 한 변입니다. */
+    size: number;
+    /** 컨테이너 크기와 별개인 화살표 끝의 돌출 길이입니다. gutter에 더합니다. */
+    tipHeight: number;
+    padding: number;
+  };
+}
+
+export interface ComputePositionOptions extends PositioningOptions {
+  reference: Rect;
+  boundary: Rect;
+  width: number;
+  height: number;
+}
+
+function getTransformOrigin(placement: Placement) {
+  const [side, align] = placement.split("-") as [Side, "start" | "end" | undefined];
+  const crossOrigin = align === "start" ? "0%" : align === "end" ? "100%" : "50%";
+  return side === "top"
+    ? `${crossOrigin} 100%`
+    : side === "bottom"
+      ? `${crossOrigin} 0%`
+      : side === "left"
+        ? `100% ${crossOrigin}`
+        : `0% ${crossOrigin}`;
+}
+
+/**
+ * 모든 좌표와 크기는 동일한 화면 기준 논리 px입니다.
+ * boundary의 safe area 보정과 결과의 컨테이너 상대 좌표 변환은 호출자 책임입니다.
+ *
+ * availableWidth로 너비를 제한했다면 줄바꿈 후 실제 높이를 다시 측정해 호출합니다.
+ * native 측정·호출 주기·오래된 비동기 결과 폐기는 이 순수 계산에 포함하지 않습니다.
+ */
+export async function computePosition({
+  reference,
+  boundary,
+  width,
+  height,
+  placement,
+  gutter,
+  overflowPadding,
+  flip: flipOptions = {},
+  shift: shiftOptions = {},
+  size: sizeOptions,
+  arrow: arrowOptions,
+}: ComputePositionOptions): Promise<Position> {
+  const referenceElement: ReferenceElement = {
+    rect: {
+      x: reference.left,
+      y: reference.top,
+      width: reference.width,
+      height: reference.height,
+    },
+  };
+  const floatingElement: FloatingElement = {
+    dimensions: {
+      width: Math.max(0, width),
+      height: Math.max(0, height),
+    },
+  };
+  const arrowElement = arrowOptions
+    ? { width: arrowOptions.size, height: arrowOptions.size }
+    : undefined;
+  const clippingRect: FloatingRect = {
+    x: boundary.left,
+    y: boundary.top,
+    width: boundary.width,
+    height: boundary.height,
+  };
+  const maximumHeight = floatingElement.dimensions.height;
+  let availableWidth = 0;
+  let availableHeight = 0;
+  const platform: Platform = {
+    getElementRects: () => ({
+      reference: referenceElement.rect,
+      floating: {
+        x: 0,
+        y: 0,
+        ...floatingElement.dimensions,
+      },
+    }),
+    getClippingRect: () => clippingRect,
+    getDimensions: (element) =>
+      element === arrowElement && arrowElement ? arrowElement : floatingElement.dimensions,
+    isElement: () => true,
+    isRTL: () => false,
+  };
+  const heightMiddleware =
+    sizeOptions &&
+    size({
+      padding: overflowPadding,
+      apply({ availableHeight }) {
+        floatingElement.dimensions.height = Math.min(
+          maximumHeight,
+          Math.max(0, sizeOptions.minimumHeight ?? 0, availableHeight),
+        );
+      },
+    });
+
+  const result = await computeFloatingPosition(referenceElement, floatingElement, {
+    placement,
+    strategy: "absolute",
+    platform,
+    middleware: [
+      offset(gutter + (arrowOptions?.tipHeight ?? 0)),
+      sizeOptions?.order === "beforeFlip" && heightMiddleware,
+      flipOptions !== false &&
+        flip({
+          ...flipOptions,
+          padding: overflowPadding,
+        }),
+      shiftOptions !== false &&
+        shift({
+          mainAxis: shiftOptions.mainAxis,
+          crossAxis: shiftOptions.crossAxis,
+          padding: overflowPadding,
+          limiter: shiftOptions.limit ? limitShift() : undefined,
+        }),
+      sizeOptions?.order === "afterShift" && heightMiddleware,
+      arrowElement &&
+        arrowMiddleware({
+          element: arrowElement,
+          padding: arrowOptions?.padding,
+        }),
+      // flip·shift·arrow 보정 후의 제약을 반환하며, 여기서는 크기를 바꾸지 않습니다.
+      size({
+        padding: overflowPadding,
+        apply(available) {
+          availableWidth = Math.max(0, available.availableWidth);
+          availableHeight = Math.max(0, available.availableHeight);
+        },
+      }),
+    ],
+  });
+  const resolvedPlacement = result.placement as Placement;
+  const arrow = result.middlewareData.arrow;
+
+  return {
+    left: result.x,
+    top: result.y,
+    width: floatingElement.dimensions.width,
+    height: floatingElement.dimensions.height,
+    placement: resolvedPlacement,
+    transformOrigin: getTransformOrigin(resolvedPlacement),
+    availableWidth,
+    availableHeight,
+    ...(arrow && { arrow: { left: arrow.x, top: arrow.y, centerOffset: arrow.centerOffset } }),
+  };
+}

package/src/components/private/TrackPositioning.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { getTrackPosition } from "./TrackPositioning";
+
+const dimensions = { trackWidth: 300, thumbWidth: 24, labelWidth: 100 };
+
+describe("getTrackPosition", () => {
+  it("sticks the label to track edges while its arrow follows the thumb", () => {
+    expect(getTrackPosition({ ...dimensions, progress: 0 })).toEqual({
+      thumbCenter: 12,
+      labelLeft: 0,
+      arrowCenter: 12,
+    });
+    expect(getTrackPosition({ ...dimensions, progress: 0.5 })).toEqual({
+      thumbCenter: 150,
+      labelLeft: 100,
+      arrowCenter: 50,
+    });
+    expect(getTrackPosition({ ...dimensions, progress: 1 })).toEqual({
+      thumbCenter: 288,
+      labelLeft: 200,
+      arrowCenter: 88,
+    });
+  });
+
+  it("mirrors both label and arrow in RTL for independently sized indicators", () => {
+    const ltr = getTrackPosition({ ...dimensions, progress: 0.2, labelWidth: 160 });
+    const rtl = getTrackPosition({
+      ...dimensions,
+      progress: 0.2,
+      labelWidth: 160,
+      direction: "rtl",
+    });
+
+    expect(rtl.thumbCenter).toBeCloseTo(300 - ltr.thumbCenter);
+    expect(rtl.labelLeft).toBeCloseTo(300 - 160 - ltr.labelLeft);
+    expect(rtl.arrowCenter).toBeCloseTo(160 - ltr.arrowCenter);
+    expect(rtl.labelLeft + rtl.arrowCenter).toBeCloseTo(rtl.thumbCenter);
+  });
+
+  it("centers an oversized label without losing its arrow target", () => {
+    expect(getTrackPosition({ ...dimensions, progress: 0, labelWidth: 400 })).toEqual({
+      thumbCenter: 12,
+      labelLeft: -50,
+      arrowCenter: 62,
+    });
+  });
+
+  it("clamps an out-of-range value even when the thumb is wider than the track", () => {
+    expect(
+      getTrackPosition({ progress: 2, trackWidth: 20, thumbWidth: 24, labelWidth: 10 }),
+    ).toEqual({
+      thumbCenter: 10,
+      labelLeft: 5,
+      arrowCenter: 5,
+    });
+  });
+});

package/src/components/private/TrackPositioning.ts

@@ -0,0 +1,37 @@
+export interface TrackPositioningOptions {
+  /** 최솟값이 0, 최댓값이 1인 값의 비율입니다. 범위 밖이면 양 끝에 고정합니다. */
+  progress: number;
+  trackWidth: number;
+  thumbWidth: number;
+  labelWidth: number;
+  direction?: "ltr" | "rtl";
+}
+
+/**
+ * 트랙 왼쪽 기준 논리 px로 thumb 중심과 label 왼쪽 좌표를 계산합니다.
+ * arrowCenter는 label 왼쪽 기준이며 화살표 너비의 절반을 빼서 배치합니다.
+ * 트랙보다 넓은 label은 중앙에 두고 양쪽으로 넘치게 합니다.
+ *
+ * 각 thumb에 대해 호출하며, 측정값을 재사용할 수 있는 동기식 계산입니다.
+ * MTS에서는 이 모듈을 runtime: 'shared'로 import하고 native 측정은 별도로 수행합니다.
+ */
+export function getTrackPosition({
+  progress,
+  trackWidth,
+  thumbWidth,
+  labelWidth,
+  direction = "ltr",
+}: TrackPositioningOptions) {
+  const track = Math.max(0, trackWidth);
+  const thumb = Math.min(track, Math.max(0, thumbWidth));
+  const label = Math.max(0, labelWidth);
+  const value = Math.max(0, Math.min(1, progress));
+  const physicalProgress = direction === "rtl" ? 1 - value : value;
+  const thumbCenter = thumb / 2 + physicalProgress * (track - thumb);
+  const labelLeft =
+    label > track
+      ? (track - label) / 2
+      : Math.max(0, Math.min(track - label, thumbCenter - label / 2));
+
+  return { thumbCenter, labelLeft, arrowCenter: thumbCenter - labelLeft };
+}

package/src/contexts/ScaleFeedbackContentContext.ts

@@ -0,0 +1,4 @@
+import { createContext, type Context } from "@lynx-js/react";
+
+/** @internal Prevents controls inside an animated content layer from binding a second target. */
+export const ScaleFeedbackContentContext: Context<boolean> = createContext(false);

package/src/contexts/index.ts

@@ -0,0 +1 @@
+export * from "./ScaleFeedbackContentContext";

package/src/hooks/index.ts

@@ -1,5 +1,6 @@
 export * from "./useControllableState";
 export * from "./useIconColor";
 export * from "./usePressTap";
+export * from "./useScaleFeedback";
 export * from "./useSafeArea";
 export * from "./useSeedClassName";

package/src/hooks/useIconColor.test.ts

@@ -15,7 +15,7 @@ vi.mock("@lynx-js/react", async (importOriginal) => {
   return {
     ...actual,
     runOnMainThread:
-      (_worklet: (...args: never[]) => unknown) =>
+      () =>
       (...args: unknown[]) => {
         testState.workletCalls.push(args.length);
       },
@@ -36,14 +36,14 @@ describe("useIconColor", () => {
     expect(result.current["main-thread:binduiappear"]).toBeDefined();
   });
 
-  it("schedules tint color synchronization when the system theme changes", () => {
+  it("avoids cross-thread calls on mount and resynchronizes after theme changes", () => {
     const { rerender } = renderHook(() => useIconColor([]));
 
-    expect(testState.workletCalls).toEqual([3]);
+    expect(testState.workletCalls).toEqual([]);
 
     testState.theme = "dark";
     rerender();
 
-    expect(testState.workletCalls).toEqual([3, 1, 3]);
+    expect(testState.workletCalls).toEqual([3]);
   });
 });

package/src/hooks/useIconColor.ts

@@ -1,4 +1,4 @@
-import { runOnMainThread, useEffect, useGlobalProps, useMainThreadRef } from "@lynx-js/react";
+import { runOnMainThread, useEffect, useGlobalProps, useMainThreadRef, useRef } from "@lynx-js/react";
 import type { MainThread } from "@lynx-js/types";
 import type { DependencyList, RefObject } from "@lynx-js/react";
 
@@ -47,15 +47,16 @@ function scheduleTintColorSync(
     frameRef.current = 0;
   }
 
-  // ReactLynx는 effect worklet을 native class patch flush보다 먼저 실행할 수 있다.
-  // 다음 frame에서 class patch가 반영된 computed color를 읽는다.
+  // WebLynx는 effect 시점에 class patch가 반영되어 있으므로 즉시 동기화해
+  // 불필요한 한 프레임 지연을 없앤다. Native는 patch flush가 늦을 수 있어
+  // 다음 frame에 한 번 더 읽는다.
+  syncTintColorOnce(targetRef, sourceRef);
+
   if (typeof requestAnimationFrame === "function") {
     frameRef.current = requestAnimationFrame(() => {
       frameRef.current = 0;
       syncTintColorOnce(targetRef, sourceRef);
     });
-  } else {
-    syncTintColorOnce(targetRef, sourceRef);
   }
 }
 
@@ -90,14 +91,20 @@ export function useIconColor(
   const enabled = options?.enabled ?? true;
   const frameRef = useMainThreadRef<number>(0);
   const theme = (useGlobalProps() as { theme?: unknown } | undefined)?.theme;
+  const hasMountedRef = useRef(false);
 
   function syncOnUiAppear() {
     "main thread";
     if (!enabled) return;
-    syncTintColorOnce(ref, sourceRef);
+    scheduleTintColorSync(ref, sourceRef, frameRef);
   }
 
   useEffect(() => {
+    if (!hasMountedRef.current) {
+      hasMountedRef.current = true;
+      return;
+    }
+
     if (!enabled) return;
 
     runOnMainThread(scheduleTintColorSync)(ref, sourceRef, frameRef);

package/src/hooks/usePressTap.ts

@@ -5,6 +5,7 @@ import type { BaseTouchEvent, EventHandler, Target } from "@lynx-js/types";
 import type { LynxTouchProps } from "../types";
 
 type TouchHandler = EventHandler<BaseTouchEvent<Target>>;
+type PressStateHandler = TouchHandler & (() => void);
 
 export interface UsePressTapOptions {
   disabled?: boolean;
@@ -15,9 +16,9 @@ export interface UsePressTapOptions {
 export interface UsePressTapReturn {
   pressed: boolean;
   bindtap: TouchHandler;
-  bindtouchstart: TouchHandler;
-  bindtouchend: TouchHandler;
-  bindtouchcancel: TouchHandler;
+  bindtouchstart: PressStateHandler;
+  bindtouchend: PressStateHandler;
+  bindtouchcancel: PressStateHandler;
   "main-thread:bindtap"?: LynxTouchProps["main-thread:bindtap"];
 }
 

package/src/hooks/useScaleFeedback.integration.test.tsx

@@ -0,0 +1,85 @@
+import { fireEvent, render, waitSchedule } from "@lynx-js/react/testing-library";
+import { describe, expect, it, vi } from "vitest";
+import { runOnBackground, useMainThreadRef } from "@lynx-js/react";
+import { mergeProps } from "../utils/merge-props";
+import { ActionButton } from "../components/ActionButton";
+
+import { useScaleFeedback } from "./useScaleFeedback";
+
+function ScaleFeedbackTarget({ onTouchStart }: { onTouchStart: () => void }) {
+  const { scaleFeedbackTriggerProps, scaleFeedbackTargetProps } = useScaleFeedback({
+    onTouchStart,
+  });
+
+  return <view id="spread-target" {...scaleFeedbackTriggerProps} {...scaleFeedbackTargetProps} />;
+}
+
+describe("useScaleFeedback Main Thread integration", () => {
+  it("keeps ActionButton's pressed state and user Main Thread handler together", async () => {
+    function Example({ report }: { report: () => void }) {
+      function handleTouch() {
+        "main thread";
+        runOnBackground(report)();
+      }
+      return <ActionButton main-thread:bindtouchstart={handleTouch}>Press</ActionButton>;
+    }
+    const report = vi.fn();
+    const { container } = render(<Example report={report} />, {
+      enableMainThread: true,
+      enableBackgroundThread: true,
+    });
+    await waitSchedule();
+    const target = container.querySelector(".seed-action-button__root")!;
+    fireEvent.touchstart(target, {});
+    await waitSchedule();
+    expect(report).toHaveBeenCalledTimes(1);
+    expect(target.className).toContain("pressed_true");
+    fireEvent.touchend(target, {});
+    await waitSchedule();
+    expect(target.className).not.toContain("pressed_true");
+  });
+
+  it("preserves user Main Thread handlers and refs alongside feedback callbacks", async () => {
+    function Example({ report }: { report: (value: string) => void }) {
+      const userRef = useMainThreadRef(null);
+      const feedback = useScaleFeedback({ onTouchStart: () => report("feedback") });
+      function userTouch() {
+        "main thread";
+        runOnBackground(report)(userRef.current ? "user-attached" : "missing-ref");
+      }
+      return (
+        <view
+          id="combined"
+          {...mergeProps(feedback.scaleFeedbackTriggerProps, feedback.scaleFeedbackTargetProps, {
+            "main-thread:ref": userRef,
+            "main-thread:bindtouchstart": userTouch,
+          })}
+        />
+      );
+    }
+    const report = vi.fn();
+    const { container } = render(<Example report={report} />, {
+      enableMainThread: true,
+      enableBackgroundThread: true,
+    });
+    await waitSchedule();
+    fireEvent.touchstart(container.querySelector("#combined")!, {});
+    await waitSchedule();
+    expect(report.mock.calls).toEqual([["user-attached"], ["feedback"]]);
+  });
+  it("runs the exact Background Thread callback from its Main Thread handler", async () => {
+    const onTouchStart = vi.fn();
+    const { container } = render(<ScaleFeedbackTarget onTouchStart={onTouchStart} />, {
+      enableMainThread: true,
+      enableBackgroundThread: true,
+    });
+    await waitSchedule();
+
+    const target = container.querySelector("#spread-target");
+    expect(target).not.toBeNull();
+    fireEvent.touchstart(target!, {});
+    await waitSchedule();
+
+    expect(onTouchStart).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useScaleFeedback.test.ts

@@ -0,0 +1,50 @@
+import { runOnMainThread } from "@lynx-js/react";
+import { renderHook, waitSchedule } from "@lynx-js/react/testing-library";
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import { calculateScaleFeedback, isReducedMotion } from "../utils/calculate-scale-feedback";
+import { useScaleFeedback, type UseScaleFeedbackOptions } from "./useScaleFeedback";
+
+describe("useScaleFeedback", () => {
+  it("keeps the animation target from being flattened", () => {
+    const { result } = renderHook(() => useScaleFeedback());
+
+    expect(result.current.scaleFeedbackTargetProps.flatten).toBe(false);
+  });
+
+  it("uses exact touch event callbacks", () => {
+    expectTypeOf<UseScaleFeedbackOptions>().toMatchTypeOf<{
+      onTouchStart?: () => void;
+      onTouchEnd?: () => void;
+      onTouchCancel?: () => void;
+    }>();
+    expectTypeOf<UseScaleFeedbackOptions>().not.toHaveProperty("onPressStart");
+    expectTypeOf<UseScaleFeedbackOptions>().not.toHaveProperty("onPressEnd");
+    expectTypeOf<UseScaleFeedbackOptions>().not.toHaveProperty("onPressCancel");
+  });
+});
+
+describe("calculateScaleFeedback", () => {
+  it.each([
+    { width: 32, height: 32, expected: 30 / 32 },
+    { width: 120, height: 48, expected: 46 / 48 },
+    { width: 343, height: 48, expected: (343 / 4 - 2) / (343 / 4) },
+    { width: 22, height: 22, expected: 22 / 24 },
+  ])("calculates the scale for $width x $height", async ({ width, height, expected }) => {
+    renderHook(() => undefined);
+    await waitSchedule();
+    const scale = runOnMainThread(calculateScaleFeedback)(width, height);
+    await waitSchedule();
+    expect(await scale).toBeCloseTo(expected);
+  });
+});
+
+describe("isReducedMotion", () => {
+  it("only disables motion for the exact reduced value", () => {
+    expect(isReducedMotion("reduced")).toBe(true);
+    expect(isReducedMotion("preferred")).toBe(false);
+    expect(isReducedMotion(undefined)).toBe(false);
+    expect(isReducedMotion(null)).toBe(false);
+    expect(isReducedMotion("unknown")).toBe(false);
+  });
+});