@seed-design/lynx-react 0.3.1 → 0.4.1

package/src/components/KeyboardAvoidingScrollView/native-driver.test.ts

@@ -0,0 +1,223 @@
+import type { NodesRef } from "@lynx-js/types";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  lynxKeyboardAvoidingNativeDriver,
+  normalizeScrollMetrics,
+  resolveKeyboardOcclusionTop,
+} from "./native-driver";
+
+interface TestGlobal {
+  SystemInfo?: {
+    pixelHeight?: number;
+    pixelRatio?: number;
+    platform?: string;
+  };
+}
+
+const originalSystemInfo = (globalThis as TestGlobal).SystemInfo;
+
+afterEach(() => {
+  const global = globalThis as TestGlobal;
+  if (originalSystemInfo === undefined) {
+    delete global.SystemInfo;
+  } else {
+    global.SystemInfo = originalSystemInfo;
+  }
+});
+
+function createNode(onInvoke?: (options: Parameters<NodesRef["invoke"]>[0]) => void) {
+  const exec = vi.fn();
+  const query = { exec } as unknown as ReturnType<NodesRef["invoke"]>;
+  const invoke = vi.fn((options: Parameters<NodesRef["invoke"]>[0]) => {
+    onInvoke?.(options);
+    return query;
+  });
+  const setNativeProps = vi.fn(() => query);
+  const node = { invoke, setNativeProps } as unknown as NodesRef;
+
+  return { exec, invoke, node, setNativeProps };
+}
+
+describe("normalizeScrollMetrics", () => {
+  it("normalizes the Android default-path response", () => {
+    expect(
+      normalizeScrollMetrics(
+        {
+          scrollY: 120,
+          scrollRange: 560,
+        },
+        "Android",
+        400,
+      ),
+    ).toEqual({ offsetY: 120, maxOffsetY: 560 });
+  });
+
+  it("prefers the iOS maxScrollOffset over the legacy content-size range", () => {
+    expect(
+      normalizeScrollMetrics(
+        {
+          scrollY: 120,
+          scrollRange: 960,
+          maxScrollOffset: 560,
+        },
+        "iOS",
+        400,
+      ),
+    ).toEqual({ offsetY: 120, maxOffsetY: 560 });
+  });
+
+  it("derives an iOS max offset from a legacy content-size range", () => {
+    expect(
+      normalizeScrollMetrics(
+        {
+          scrollY: 120,
+          scrollRange: 960,
+        },
+        "iOS",
+        400,
+      ),
+    ).toEqual({ offsetY: 120, maxOffsetY: 560 });
+  });
+
+  it("normalizes the Android new-architecture response", () => {
+    expect(
+      normalizeScrollMetrics(
+        {
+          scrollTop: 120,
+          scrollHeight: 560,
+        },
+        "Android",
+        400,
+      ),
+    ).toEqual({ offsetY: 120, maxOffsetY: 560 });
+  });
+
+  it("derives an iOS max offset from new-architecture content height", () => {
+    expect(
+      normalizeScrollMetrics(
+        {
+          scrollTop: 120,
+          scrollHeight: 960,
+        },
+        "iOS",
+        400,
+      ),
+    ).toEqual({ offsetY: 120, maxOffsetY: 560 });
+  });
+
+  it("returns null for incomplete or non-finite responses", () => {
+    expect(normalizeScrollMetrics({ scrollY: 10 }, "Android", 400)).toBeNull();
+    expect(
+      normalizeScrollMetrics({ scrollY: Number.NaN, scrollRange: 10 }, "Android", 400),
+    ).toBeNull();
+  });
+
+  it("clamps negative offsets and ranges", () => {
+    expect(
+      normalizeScrollMetrics(
+        {
+          scrollY: -20,
+          scrollRange: -10,
+        },
+        "Android",
+        400,
+      ),
+    ).toEqual({ offsetY: 0, maxOffsetY: 0 });
+  });
+});
+
+describe("resolveKeyboardOcclusionTop", () => {
+  it("uses the Lynx root bottom for Android relative keyboard height", () => {
+    expect(
+      resolveKeyboardOcclusionTop({ visible: true, height: 280 }, "Android", 844, {
+        top: 44,
+        bottom: 800,
+      }),
+    ).toBe(520);
+  });
+
+  it("uses the physical screen height in CSS pixels for iOS", () => {
+    expect(
+      resolveKeyboardOcclusionTop({ visible: true, height: 280 }, "iOS", 844, {
+        top: 44,
+        bottom: 800,
+      }),
+    ).toBe(564);
+  });
+
+  it("returns null for hidden or invalid keyboard geometry", () => {
+    expect(
+      resolveKeyboardOcclusionTop({ visible: false, height: 280 }, "iOS", 844, {
+        top: 0,
+        bottom: 844,
+      }),
+    ).toBeNull();
+    expect(
+      resolveKeyboardOcclusionTop({ visible: true, height: 0 }, "Android", 844, {
+        top: 0,
+        bottom: 844,
+      }),
+    ).toBeNull();
+    expect(
+      resolveKeyboardOcclusionTop({ visible: true, height: 280 }, "Android", 844, null),
+    ).toBeNull();
+  });
+});
+
+describe("lynxKeyboardAvoidingNativeDriver", () => {
+  it("executes native spacer and absolute scroll mutations", () => {
+    const { exec, invoke, node, setNativeProps } = createNode();
+
+    lynxKeyboardAvoidingNativeDriver.setSpacerHeight(node, -10);
+    lynxKeyboardAvoidingNativeDriver.scrollTo(node, -20, false);
+
+    expect(setNativeProps).toHaveBeenCalledWith({ height: "0px" });
+    expect(invoke).toHaveBeenCalledWith({
+      method: "scrollTo",
+      params: {
+        offset: 0,
+        smooth: false,
+      },
+    });
+    expect(exec).toHaveBeenCalledTimes(2);
+  });
+
+  it("measures nodes in screen coordinates and executes the query", async () => {
+    const { exec, invoke, node } = createNode((options) => {
+      options.success?.({ top: 120, bottom: 280 });
+    });
+
+    await expect(lynxKeyboardAvoidingNativeDriver.measure(node)).resolves.toEqual({
+      top: 120,
+      bottom: 280,
+    });
+    expect(invoke).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: "boundingClientRect",
+        params: {
+          relativeTo: "screen",
+          androidEnableTransformProps: true,
+        },
+      }),
+    );
+    expect(exec).toHaveBeenCalledOnce();
+  });
+
+  it("normalizes getScrollInfo using the runtime platform", async () => {
+    (globalThis as TestGlobal).SystemInfo = {
+      platform: "iOS",
+      pixelHeight: 844,
+      pixelRatio: 1,
+    };
+    const { exec, node } = createNode((options) => {
+      options.success?.({ scrollY: 120, scrollRange: 960 });
+    });
+
+    await expect(lynxKeyboardAvoidingNativeDriver.getScrollMetrics(node, 400)).resolves.toEqual({
+      offsetY: 120,
+      maxOffsetY: 560,
+    });
+    expect(exec).toHaveBeenCalledOnce();
+  });
+});

package/src/components/KeyboardAvoidingScrollView/native-driver.ts

@@ -0,0 +1,248 @@
+import type { NodesRef, PlatformType } from "@lynx-js/types";
+
+import type { VerticalRect } from "./geometry";
+
+export type KeyboardAvoidingPlatform = Extract<PlatformType, "Android" | "iOS">;
+
+export interface RawKeyboardState {
+  visible: boolean;
+  height: number;
+}
+
+export interface KeyboardOcclusion {
+  visible: boolean;
+  topInScreenPx: number;
+}
+
+export interface ScrollMetrics {
+  offsetY: number;
+  maxOffsetY: number;
+}
+
+export interface RawScrollInfo {
+  scrollY?: number;
+  scrollRange?: number;
+  maxScrollOffset?: number;
+  scrollTop?: number;
+  scrollHeight?: number;
+}
+
+interface SystemInfoLike {
+  pixelHeight?: number;
+  pixelRatio?: number;
+  platform?: string;
+}
+
+export interface KeyboardAvoidingNativeDriver {
+  measure(node: NodesRef): Promise<VerticalRect | null>;
+  resolveKeyboardOcclusion(state: RawKeyboardState): Promise<KeyboardOcclusion | null>;
+  setSpacerHeight(node: NodesRef, height: number): void;
+  waitForLayout(): Promise<void>;
+  getScrollMetrics(node: NodesRef, viewportHeight: number): Promise<ScrollMetrics | null>;
+  scrollTo(node: NodesRef, offset: number, smooth: boolean): void;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function normalizeNonNegative(value: number): number {
+  return Math.max(0, value);
+}
+
+function normalizeRect(value: unknown): VerticalRect | null {
+  if (typeof value !== "object" || value === null) return null;
+
+  const rect = value as { top?: unknown; bottom?: unknown };
+  if (!isFiniteNumber(rect.top) || !isFiniteNumber(rect.bottom)) return null;
+
+  return {
+    top: rect.top,
+    bottom: Math.max(rect.top, rect.bottom),
+  };
+}
+
+export function normalizeScrollMetrics(
+  raw: RawScrollInfo,
+  platform: KeyboardAvoidingPlatform,
+  viewportHeight: number,
+): ScrollMetrics | null {
+  const offsetY = isFiniteNumber(raw.scrollY)
+    ? raw.scrollY
+    : isFiniteNumber(raw.scrollTop)
+      ? raw.scrollTop
+      : null;
+
+  if (offsetY === null) return null;
+
+  const normalizedViewportHeight = normalizeNonNegative(viewportHeight);
+  let maxOffsetY: number | null = null;
+
+  if (isFiniteNumber(raw.maxScrollOffset)) {
+    maxOffsetY = raw.maxScrollOffset;
+  } else if (isFiniteNumber(raw.scrollRange)) {
+    maxOffsetY = platform === "iOS" ? raw.scrollRange - normalizedViewportHeight : raw.scrollRange;
+  } else if (isFiniteNumber(raw.scrollHeight)) {
+    maxOffsetY =
+      platform === "iOS" ? raw.scrollHeight - normalizedViewportHeight : raw.scrollHeight;
+  }
+
+  if (maxOffsetY === null) return null;
+
+  return {
+    offsetY: normalizeNonNegative(offsetY),
+    maxOffsetY: normalizeNonNegative(maxOffsetY),
+  };
+}
+
+export function resolveKeyboardOcclusionTop(
+  state: RawKeyboardState,
+  platform: KeyboardAvoidingPlatform,
+  screenHeight: number,
+  rootRect: VerticalRect | null,
+): number | null {
+  if (!state.visible || !isFiniteNumber(state.height) || state.height <= 0) return null;
+
+  if (platform === "Android") {
+    return rootRect ? rootRect.bottom - state.height : null;
+  }
+
+  return isFiniteNumber(screenHeight) && screenHeight > 0 ? screenHeight - state.height : null;
+}
+
+function getSystemInfo(): {
+  platform: KeyboardAvoidingPlatform;
+  screenHeight: number;
+} | null {
+  const value = (globalThis as typeof globalThis & { SystemInfo?: SystemInfoLike }).SystemInfo;
+  if (value?.platform !== "Android" && value?.platform !== "iOS") return null;
+  if (!isFiniteNumber(value.pixelHeight) || !isFiniteNumber(value.pixelRatio)) return null;
+  if (value.pixelHeight <= 0 || value.pixelRatio <= 0) return null;
+
+  return {
+    platform: value.platform,
+    screenHeight: value.pixelHeight / value.pixelRatio,
+  };
+}
+
+function measureNode(node: NodesRef): Promise<VerticalRect | null> {
+  "background only";
+
+  return new Promise((resolve) => {
+    try {
+      node
+        .invoke({
+          method: "boundingClientRect",
+          params: {
+            relativeTo: "screen",
+            androidEnableTransformProps: true,
+          },
+          success: (value) => resolve(normalizeRect(value)),
+          fail: () => resolve(null),
+        })
+        .exec();
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+function measureRoot(): Promise<VerticalRect | null> {
+  "background only";
+
+  try {
+    return measureNode(lynx.createSelectorQuery().selectRoot());
+  } catch {
+    return Promise.resolve(null);
+  }
+}
+
+function getScrollMetrics(
+  node: NodesRef,
+  platform: KeyboardAvoidingPlatform,
+  viewportHeight: number,
+): Promise<ScrollMetrics | null> {
+  "background only";
+
+  return new Promise((resolve) => {
+    try {
+      node
+        .invoke({
+          method: "getScrollInfo",
+          success: (value) => {
+            if (typeof value !== "object" || value === null) {
+              resolve(null);
+              return;
+            }
+
+            resolve(normalizeScrollMetrics(value as RawScrollInfo, platform, viewportHeight));
+          },
+          fail: () => resolve(null),
+        })
+        .exec();
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+export const lynxKeyboardAvoidingNativeDriver: KeyboardAvoidingNativeDriver = {
+  measure: measureNode,
+  async resolveKeyboardOcclusion(state) {
+    "background only";
+
+    const systemInfo = getSystemInfo();
+    if (!systemInfo || !state.visible) return null;
+
+    const rootRect = systemInfo.platform === "Android" ? await measureRoot() : null;
+    const topInScreenPx = resolveKeyboardOcclusionTop(
+      state,
+      systemInfo.platform,
+      systemInfo.screenHeight,
+      rootRect,
+    );
+
+    return topInScreenPx === null
+      ? null
+      : {
+          visible: true,
+          topInScreenPx,
+        };
+  },
+  setSpacerHeight(node, height) {
+    "background only";
+
+    // 동기 실행 실패는 engine까지 전달한다. engine이 transaction을 중단하되
+    // 적용 상태를 확정하지 않아 다음 invalidation에서 재시도할 수 있다.
+    node.setNativeProps({ height: `${normalizeNonNegative(height)}px` }).exec();
+  },
+  waitForLayout() {
+    "background only";
+
+    return new Promise((resolve) => {
+      requestAnimationFrame(() => resolve());
+    });
+  },
+  async getScrollMetrics(node, viewportHeight) {
+    "background only";
+
+    const systemInfo = getSystemInfo();
+    if (!systemInfo) return null;
+
+    return getScrollMetrics(node, systemInfo.platform, viewportHeight);
+  },
+  scrollTo(node, offset, smooth) {
+    "background only";
+
+    // 동기 실행 실패는 engine의 transaction 경계에서 fail-soft 처리한다.
+    node
+      .invoke({
+        method: "scrollTo",
+        params: {
+          offset: normalizeNonNegative(offset),
+          smooth,
+        },
+      })
+      .exec();
+  },
+};

package/src/components/ProgressCircle/ProgressCircle.test.tsx

@@ -0,0 +1,58 @@
+import "@testing-library/jest-dom";
+import { render } from "@lynx-js/react/testing-library";
+import { describe, expect, it, vi } from "vitest";
+
+import { ProgressCircle } from "./index";
+
+vi.mock("@lynx-js/react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@lynx-js/react")>();
+
+  return {
+    ...actual,
+    runOnMainThread: () => () => undefined,
+  };
+});
+
+function getRenderedRoot() {
+  const root = elementTree.root;
+
+  if (!root) {
+    throw new Error("Expected Lynx render root to exist.");
+  }
+
+  return root;
+}
+
+describe("ProgressCircle", () => {
+  it("renders a visible indeterminate range before the main-thread animation starts", () => {
+    render(
+      <ProgressCircle.Root>
+        <ProgressCircle.Range />
+      </ProgressCircle.Root>,
+    );
+
+    const root = getRenderedRoot();
+    const range = root.querySelector<HTMLElement>(".seed-progress-circle__range");
+    const caps = root.querySelectorAll<HTMLElement>(".seed-progress-circle__cap");
+    const animationContainer = range?.parentElement;
+
+    expect(range).toBeInTheDocument();
+    expect(animationContainer?.style.transform).not.toBe("rotate(0deg)");
+    expect(range?.style.clipPath).toMatch(/^path\("M 20 20 L 20 -1 A 21 21/);
+    expect(caps).toHaveLength(2);
+    expect(caps[1]?.style.left).not.toBe(caps[0]?.style.left);
+    expect(caps[1]?.style.top).not.toBe(caps[0]?.style.top);
+  });
+
+  it("keeps the determinate range at the requested initial value", () => {
+    render(
+      <ProgressCircle.Root minValue={0} maxValue={100} value={40}>
+        <ProgressCircle.Range />
+      </ProgressCircle.Root>,
+    );
+
+    const range = getRenderedRoot().querySelector<HTMLElement>(".seed-progress-circle__range");
+
+    expect(range?.style.clipPath).toMatch(/^path\("M 20 20 L 20 -1 A 21 21/);
+  });
+});

package/src/components/ProgressCircle/ProgressCircle.tsx

@@ -45,6 +45,37 @@ function computeRingGeometry(numSize: number) {
   return { halfSize, innerR, ringCenterR, capSize };
 }
 
+function bgCubicBezier(rawT: number, x1: number, y1: number, x2: number, y2: number): number {
+  const t = Math.max(0, Math.min(1, rawT));
+  const cx = 3 * x1;
+  const bx = 3 * (x2 - x1) - cx;
+  const ax = 1 - cx - bx;
+  let currentT = t;
+  for (let i = 0; i < 8; i++) {
+    const currentX = ((ax * currentT + bx) * currentT + cx) * currentT - t;
+    const currentDx = (3 * ax * currentT + 2 * bx) * currentT + cx;
+    if (Math.abs(currentDx) < 1e-6) break;
+    currentT = currentT - currentX / currentDx;
+  }
+  const cy = 3 * y1;
+  const by = 3 * (y2 - y1) - cy;
+  const ay = 1 - cy - by;
+  return ((ay * currentT + by) * currentT + cy) * currentT;
+}
+
+function bgSampleIndeterminate(t: number) {
+  const containerEased = bgCubicBezier(t, 0.35, 0.25, 0.65, 0.75);
+  const headEased = bgCubicBezier(t, 0.35, 0, 0.65, 1);
+  const tailEased = bgCubicBezier(t, 0.35, 0, 0.65, 0.6);
+
+  const headLength = headEased <= 0.75 ? (headEased / 0.75) * 360 : 360;
+  const tailOffset = tailEased <= 1 / 3 ? 0 : ((tailEased - 1 / 3) / (2 / 3)) * 360;
+  const arcLength = Math.max(0, headLength - tailOffset);
+  const containerDeg = containerEased * 360 + tailOffset;
+
+  return { containerDeg, arcLength };
+}
+
 function bgPieClipPath(size: number, angleDeg: number): string | undefined {
   if (angleDeg >= 360) return undefined;
   if (angleDeg <= 0) return 'path("M 0 0 Z")';
@@ -113,6 +144,7 @@ function sampleIndeterminate(t: number) {
 // --- Animation constants ---
 
 const INDETERMINATE_DURATION = 1200;
+const INDETERMINATE_INITIAL_PHASE = 1 / 6;
 const TRANSITION_DURATION = 300;
 
 ////////////////////////////////////////////////////////////////////////////////////
@@ -335,7 +367,10 @@ function IndeterminateRange({ numSize, classes }: { numSize: number; classes: Cl
       if (!startTs) startTs = Number(ts);
 
       const elapsed = ts - startTs;
-      const t = (elapsed % INDETERMINATE_DURATION) / INDETERMINATE_DURATION;
+      const t =
+        ((elapsed + INDETERMINATE_DURATION * INDETERMINATE_INITIAL_PHASE) %
+          INDETERMINATE_DURATION) /
+        INDETERMINATE_DURATION;
       const state = sampleIndeterminate(t);
 
       containerEl?.setStyleProperty("transform", `rotate(${state.containerDeg}deg)`);
@@ -373,7 +408,9 @@ function IndeterminateRange({ numSize, classes }: { numSize: number; classes: Cl
     };
   }, [numSize]);
 
-  const initialClipPath = 'path("M 0 0 Z")';
+  const initialState = bgSampleIndeterminate(INDETERMINATE_INITIAL_PHASE);
+  const initialClipPath = bgPieClipPath(numSize, initialState.arcLength);
+  const initialHeadRad = (initialState.arcLength * Math.PI) / 180;
 
   return (
     <view
@@ -382,7 +419,7 @@ function IndeterminateRange({ numSize, classes }: { numSize: number; classes: Cl
         position: "absolute",
         width: `${numSize}px`,
         height: `${numSize}px`,
-        transform: "rotate(0deg)",
+        transform: `rotate(${initialState.containerDeg}deg)`,
       }}
     >
       <view
@@ -412,8 +449,8 @@ function IndeterminateRange({ numSize, classes }: { numSize: number; classes: Cl
         style={{
           width: `${capSize}px`,
           height: `${capSize}px`,
-          left: `${halfSize - capSize / 2}px`,
-          top: `${halfSize - ringCenterR - capSize / 2}px`,
+          left: `${halfSize + ringCenterR * Math.sin(initialHeadRad) - capSize / 2}px`,
+          top: `${halfSize - ringCenterR * Math.cos(initialHeadRad) - capSize / 2}px`,
         }}
       />
     </view>

package/src/components/Stack/Stack.test.tsx

@@ -0,0 +1,67 @@
+import "@testing-library/jest-dom";
+import { render } from "@lynx-js/react/testing-library";
+import { describe, expect, it } from "vitest";
+
+import { HStack, VStack } from "./Stack";
+
+function getRenderedRoot() {
+  const root = elementTree.root;
+
+  if (!root) {
+    throw new Error("Expected Lynx render root to exist.");
+  }
+
+  const stack = root.querySelector<HTMLElement>("view");
+
+  if (!stack) {
+    throw new Error("Expected Stack root view to exist.");
+  }
+
+  return stack;
+}
+
+describe("Stack", () => {
+  it("maps a VStack gap token to row-gap", () => {
+    render(<VStack gap="x3" />);
+
+    expect(getRenderedRoot()).toHaveStyle({
+      rowGap: "var(--seed-dimension-x3)",
+    });
+    expect(getRenderedRoot().style.getPropertyValue("gap")).toBe("");
+    expect(getRenderedRoot().style.getPropertyValue("column-gap")).toBe("");
+  });
+
+  it("maps an HStack gap token to column-gap", () => {
+    render(<HStack gap="x4" />);
+
+    expect(getRenderedRoot()).toHaveStyle({
+      columnGap: "var(--seed-dimension-x4)",
+    });
+    expect(getRenderedRoot().style.getPropertyValue("gap")).toBe("");
+    expect(getRenderedRoot().style.getPropertyValue("row-gap")).toBe("");
+  });
+
+  it("keeps a numeric zero gap value", () => {
+    render(<VStack gap={0} />);
+
+    expect(getRenderedRoot()).toHaveStyle({ rowGap: "0px" });
+  });
+
+  it("keeps an arbitrary string gap value", () => {
+    render(<HStack gap="1.5rem" />);
+
+    expect(getRenderedRoot()).toHaveStyle({ columnGap: "1.5rem" });
+  });
+
+  it("keeps style gap precedence over the gap prop", () => {
+    render(<VStack gap="x3" style={{ gap: "20px" }} />);
+
+    expect(getRenderedRoot()).toHaveStyle({ rowGap: "20px" });
+  });
+
+  it("keeps an axis longhand in style above the gap prop", () => {
+    render(<VStack gap="x3" style={{ rowGap: "24px" }} />);
+
+    expect(getRenderedRoot()).toHaveStyle({ rowGap: "24px" });
+  });
+});

package/src/components/Stack/Stack.tsx

@@ -54,11 +54,25 @@ function getStackProps(props: StackProps) {
 }
 
 function useStackStyleProps(props: StackProps, flexDirection: "column" | "row") {
-  return useStyleProps({
+  const stackStyleProps = useStyleProps({
     display: "flex",
     flexDirection,
     ...getStackProps(props),
   });
+  // Lynx의 gap 단축 속성 파서는 var(...)를 0px로 확정하므로 축별 longhand를 사용합니다.
+  const { gap, ...style } = stackStyleProps.style;
+
+  if (gap == null) {
+    return stackStyleProps;
+  }
+
+  return {
+    ...stackStyleProps,
+    style: {
+      [flexDirection === "column" ? "rowGap" : "columnGap"]: gap,
+      ...style,
+    },
+  };
 }
 
 function renderStackView(