@seed-design/lynx-react 0.3.1 → 0.4.1

package/src/components/KeyboardAvoidingScrollView/geometry.test.ts

@@ -0,0 +1,315 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  calculateSafeArea,
+  calculateSignedScrollDelta,
+  clampScrollOffset,
+  createFieldBodyRect,
+  hasMeaningfulGeometryChange,
+  selectLargestFittingTarget,
+  type VerticalRect,
+} from "./geometry";
+
+function rect(top: number, height: number): VerticalRect {
+  return { top, bottom: top + height };
+}
+
+describe("calculateSafeArea", () => {
+  it("calculates the safe area and spacer in screen coordinates", () => {
+    expect(
+      calculateSafeArea({
+        viewport: { top: 120, bottom: 720 },
+        keyboardOcclusionTop: 640,
+        toolbarHeight: 48,
+        keyboardGap: 24,
+      }),
+    ).toEqual({
+      safeTop: 120,
+      safeBottom: 568,
+      spacerHeight: 152,
+    });
+  });
+
+  it("does not add a spacer when the occlusion is below the viewport", () => {
+    expect(
+      calculateSafeArea({
+        viewport: { top: 120, bottom: 720 },
+        keyboardOcclusionTop: 900,
+        toolbarHeight: 48,
+        keyboardGap: 24,
+      }),
+    ).toEqual({
+      safeTop: 120,
+      safeBottom: 720,
+      spacerHeight: 0,
+    });
+  });
+
+  it("normalizes negative toolbar height and keyboard gap to zero", () => {
+    expect(
+      calculateSafeArea({
+        viewport: { top: 120, bottom: 720 },
+        keyboardOcclusionTop: 640,
+        toolbarHeight: -48,
+        keyboardGap: -24,
+      }),
+    ).toEqual({
+      safeTop: 120,
+      safeBottom: 640,
+      spacerHeight: 80,
+    });
+  });
+
+  it("normalizes non-finite toolbar height and keyboard gap to zero", () => {
+    expect(
+      calculateSafeArea({
+        viewport: { top: 120, bottom: 720 },
+        keyboardOcclusionTop: 640,
+        toolbarHeight: Number.POSITIVE_INFINITY,
+        keyboardGap: Number.NaN,
+      }),
+    ).toEqual({
+      safeTop: 120,
+      safeBottom: 640,
+      spacerHeight: 80,
+    });
+  });
+
+  it("clamps the safe bottom to the viewport top when the viewport is fully occluded", () => {
+    expect(
+      calculateSafeArea({
+        viewport: { top: 120, bottom: 720 },
+        keyboardOcclusionTop: 100,
+        toolbarHeight: 48,
+        keyboardGap: 24,
+      }),
+    ).toEqual({
+      safeTop: 120,
+      safeBottom: 120,
+      spacerHeight: 600,
+    });
+  });
+
+  it("normalizes an invalid viewport bottom to its top", () => {
+    expect(
+      calculateSafeArea({
+        viewport: { top: 720, bottom: 120 },
+        keyboardOcclusionTop: 640,
+        toolbarHeight: 48,
+        keyboardGap: 24,
+      }),
+    ).toEqual({
+      safeTop: 720,
+      safeBottom: 720,
+      spacerHeight: 0,
+    });
+  });
+});
+
+describe("selectLargestFittingTarget", () => {
+  const safeArea = { safeTop: 100, safeBottom: 500 };
+
+  it("selects the Field when it fits", () => {
+    const field = rect(0, 350);
+
+    expect(
+      selectLargestFittingTarget(
+        {
+          field,
+          control: rect(0, 100),
+          native: rect(0, 80),
+          anchor: rect(0, 20),
+        },
+        safeArea,
+      ),
+    ).toEqual({ kind: "field", rect: field });
+  });
+
+  it.each([
+    {
+      name: "Field body",
+      candidates: {
+        field: rect(0, 402),
+        fieldBody: rect(100, 350),
+        control: rect(0, 200),
+        native: rect(0, 80),
+        anchor: rect(0, 20),
+      },
+      expectedKind: "fieldBody",
+    },
+    {
+      name: "control",
+      candidates: {
+        field: rect(0, 402),
+        control: rect(0, 200),
+        native: rect(0, 80),
+        anchor: rect(0, 20),
+      },
+      expectedKind: "control",
+    },
+    {
+      name: "native control",
+      candidates: {
+        field: rect(0, 402),
+        control: rect(0, 402),
+        native: rect(0, 80),
+        anchor: rect(0, 20),
+      },
+      expectedKind: "native",
+    },
+    {
+      name: "anchor",
+      candidates: {
+        field: rect(0, 402),
+        control: rect(0, 402),
+        native: rect(0, 402),
+        anchor: rect(0, 20),
+      },
+      expectedKind: "anchor",
+    },
+  ])("falls back to the $name when larger targets do not fit", ({ candidates, expectedKind }) => {
+    expect(selectLargestFittingTarget(candidates, safeArea)?.kind).toBe(expectedKind);
+  });
+
+  it("allows a target to exceed the safe height by the 1px epsilon", () => {
+    expect(
+      selectLargestFittingTarget(
+        {
+          field: rect(0, 401),
+          control: rect(0, 200),
+        },
+        safeArea,
+      )?.kind,
+    ).toBe("field");
+  });
+
+  it("returns null when every target is oversized", () => {
+    expect(
+      selectLargestFittingTarget(
+        {
+          field: rect(0, 404),
+          control: rect(0, 403),
+          native: rect(0, 402),
+          anchor: rect(0, 401.01),
+        },
+        safeArea,
+      ),
+    ).toBeNull();
+  });
+
+  it("falls back to the Field bottom when every semantic target is oversized", () => {
+    expect(
+      selectLargestFittingTarget(
+        {
+          field: rect(-206, 789),
+          fieldBody: rect(-176, 759),
+          control: rect(-176, 732),
+          native: rect(-176, 732),
+        },
+        { safeTop: 124, safeBottom: 491 },
+      ),
+    ).toEqual({
+      kind: "fieldBottom",
+      rect: { top: 583, bottom: 583 },
+    });
+  });
+
+  it("prioritizes the Field bottom over a fitting control when the Field body is oversized", () => {
+    expect(
+      selectLargestFittingTarget(
+        {
+          field: rect(100, 407),
+          fieldBody: rect(130, 377),
+          control: rect(130, 350),
+          native: rect(130, 350),
+        },
+        { safeTop: 124, safeBottom: 491 },
+      ),
+    ).toEqual({
+      kind: "fieldBottom",
+      rect: { top: 507, bottom: 507 },
+    });
+  });
+});
+
+describe("createFieldBodyRect", () => {
+  it("creates a target from the control top through the Field footer", () => {
+    expect(createFieldBodyRect({ top: 100, bottom: 500 }, { top: 180, bottom: 460 })).toEqual({
+      top: 180,
+      bottom: 500,
+    });
+  });
+
+  it("allows native measurement differences within the 1px containment epsilon", () => {
+    expect(createFieldBodyRect({ top: 100, bottom: 500 }, { top: 99, bottom: 501 })).toEqual({
+      top: 99,
+      bottom: 501,
+    });
+  });
+
+  it.each([
+    {
+      name: "control starts outside the Field",
+      field: { top: 100, bottom: 500 },
+      control: { top: 98.99, bottom: 460 },
+    },
+    {
+      name: "control ends outside the Field",
+      field: { top: 100, bottom: 500 },
+      control: { top: 180, bottom: 501.01 },
+    },
+    {
+      name: "Field has an invalid height",
+      field: { top: 500, bottom: 100 },
+      control: { top: 180, bottom: 460 },
+    },
+  ])("returns null when $name", ({ field, control }) => {
+    expect(createFieldBodyRect(field, control)).toBeNull();
+  });
+});
+
+describe("calculateSignedScrollDelta", () => {
+  const safeArea = { safeTop: 100, safeBottom: 500 };
+
+  it("returns a negative delta for a target above the safe area", () => {
+    expect(calculateSignedScrollDelta({ top: 70, bottom: 90 }, safeArea)).toBe(-30);
+  });
+
+  it("returns a positive delta for a target below the safe area", () => {
+    expect(calculateSignedScrollDelta({ top: 510, bottom: 530 }, safeArea)).toBe(30);
+  });
+
+  it("returns zero for a visible target", () => {
+    expect(calculateSignedScrollDelta({ top: 200, bottom: 300 }, safeArea)).toBe(0);
+  });
+
+  it.each([
+    { target: { top: 99, bottom: 300 }, edge: "top" },
+    { target: { top: 200, bottom: 501 }, edge: "bottom" },
+  ])("treats a target within 1px of the $edge edge as visible", ({ target }) => {
+    expect(calculateSignedScrollDelta(target, safeArea)).toBe(0);
+  });
+});
+
+describe("clampScrollOffset", () => {
+  it.each([
+    { offset: -20, maxOffset: 300, expected: 0 },
+    { offset: 120, maxOffset: 300, expected: 120 },
+    { offset: 420, maxOffset: 300, expected: 300 },
+    { offset: 20, maxOffset: -1, expected: 0 },
+  ])("clamps $offset to $expected for max offset $maxOffset", ({ offset, maxOffset, expected }) => {
+    expect(clampScrollOffset(offset, maxOffset)).toBe(expected);
+  });
+});
+
+describe("hasMeaningfulGeometryChange", () => {
+  it("ignores changes within the 1px epsilon", () => {
+    expect(hasMeaningfulGeometryChange(100, 101)).toBe(false);
+    expect(hasMeaningfulGeometryChange(100, 99)).toBe(false);
+  });
+
+  it("detects changes beyond the 1px epsilon", () => {
+    expect(hasMeaningfulGeometryChange(100, 101.01)).toBe(true);
+    expect(hasMeaningfulGeometryChange(100, 98.99)).toBe(true);
+  });
+});

package/src/components/KeyboardAvoidingScrollView/geometry.ts

@@ -0,0 +1,194 @@
+export const KEYBOARD_AVOIDANCE_EPSILON_PX = 1;
+
+export interface VerticalRect {
+  top: number;
+  bottom: number;
+}
+
+export interface SafeArea {
+  safeTop: number;
+  safeBottom: number;
+  spacerHeight: number;
+}
+
+export interface CalculateSafeAreaOptions {
+  viewport: VerticalRect;
+  keyboardOcclusionTop: number;
+  toolbarHeight: number;
+  keyboardGap: number;
+}
+
+export type AvoidanceTargetKind =
+  | "field"
+  | "fieldBody"
+  | "control"
+  | "native"
+  | "anchor"
+  | "fieldBottom";
+
+export interface AvoidanceTarget {
+  kind: AvoidanceTargetKind;
+  rect: VerticalRect;
+}
+
+export interface AvoidanceTargetCandidates {
+  field?: VerticalRect | null;
+  fieldBody?: VerticalRect | null;
+  control?: VerticalRect | null;
+  native?: VerticalRect | null;
+  anchor?: VerticalRect | null;
+}
+
+function normalizeNonNegativeFinite(value: number): number {
+  return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+/**
+ * screen 좌표계에서 키보드와 툴바가 가리지 않는 세로 영역을 계산한다.
+ */
+export function calculateSafeArea({
+  viewport,
+  keyboardOcclusionTop,
+  toolbarHeight,
+  keyboardGap,
+}: CalculateSafeAreaOptions): SafeArea {
+  const normalizedToolbarHeight = normalizeNonNegativeFinite(toolbarHeight);
+  const normalizedKeyboardGap = normalizeNonNegativeFinite(keyboardGap);
+  const normalizedViewportBottom = Math.max(viewport.top, viewport.bottom);
+  const safeBottom = Math.min(
+    normalizedViewportBottom,
+    Math.max(viewport.top, keyboardOcclusionTop - normalizedToolbarHeight - normalizedKeyboardGap),
+  );
+
+  return {
+    safeTop: viewport.top,
+    safeBottom,
+    spacerHeight: normalizedViewportBottom - safeBottom,
+  };
+}
+
+/**
+ * Field의 header를 제외하고 control부터 footer까지 포함하는 영역을 만든다.
+ */
+export function createFieldBodyRect(
+  field: VerticalRect | null,
+  control: VerticalRect | null,
+  epsilon = KEYBOARD_AVOIDANCE_EPSILON_PX,
+): VerticalRect | null {
+  if (field === null || control === null) return null;
+
+  const normalizedEpsilon = Math.max(0, epsilon);
+  const fieldHeight = field.bottom - field.top;
+  const controlHeight = control.bottom - control.top;
+  if (
+    fieldHeight < 0 ||
+    controlHeight < 0 ||
+    control.top < field.top - normalizedEpsilon ||
+    control.bottom > field.bottom + normalizedEpsilon
+  ) {
+    return null;
+  }
+
+  return { top: control.top, bottom: Math.max(field.bottom, control.bottom) };
+}
+
+/**
+ * 화면에 온전히 들어오는 가장 큰 의미 단위를 선택한다.
+ * 우선순위는 Field, Field body, Field bottom, control, native control, 정밀 anchor 순이다.
+ * Field body가 너무 크면 autoresize Field의 footer를 추적할 수 있도록
+ * control보다 먼저 Field body의 하단점을 사용한다.
+ */
+export function selectLargestFittingTarget(
+  candidates: AvoidanceTargetCandidates,
+  safeArea: Pick<SafeArea, "safeTop" | "safeBottom">,
+  epsilon = KEYBOARD_AVOIDANCE_EPSILON_PX,
+): AvoidanceTarget | null {
+  const availableHeight = Math.max(0, safeArea.safeBottom - safeArea.safeTop);
+  const normalizedEpsilon = Math.max(0, epsilon);
+  const fieldCandidates: readonly (readonly [
+    AvoidanceTargetKind,
+    VerticalRect | null | undefined,
+  ])[] = [
+    ["field", candidates.field],
+    ["fieldBody", candidates.fieldBody],
+  ];
+  const fallbackCandidates: readonly (readonly [
+    AvoidanceTargetKind,
+    VerticalRect | null | undefined,
+  ])[] = [
+    ["control", candidates.control],
+    ["native", candidates.native],
+    ["anchor", candidates.anchor],
+  ];
+
+  for (const [kind, rect] of fieldCandidates) {
+    if (!rect) {
+      continue;
+    }
+
+    const targetHeight = rect.bottom - rect.top;
+    if (targetHeight >= 0 && targetHeight <= availableHeight + normalizedEpsilon) {
+      return { kind, rect };
+    }
+  }
+
+  const fieldBody = candidates.fieldBody;
+  const fieldBodyHeight = fieldBody ? fieldBody.bottom - fieldBody.top : -1;
+  if (
+    fieldBody &&
+    Number.isFinite(fieldBody.top) &&
+    Number.isFinite(fieldBody.bottom) &&
+    fieldBodyHeight > availableHeight + normalizedEpsilon
+  ) {
+    return {
+      kind: "fieldBottom",
+      rect: { top: fieldBody.bottom, bottom: fieldBody.bottom },
+    };
+  }
+
+  for (const [kind, rect] of fallbackCandidates) {
+    if (!rect) {
+      continue;
+    }
+
+    const targetHeight = rect.bottom - rect.top;
+    if (targetHeight >= 0 && targetHeight <= availableHeight + normalizedEpsilon) {
+      return { kind, rect };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 양수는 아래로, 음수는 위로 이동해야 하는 scroll offset 변화량이다.
+ */
+export function calculateSignedScrollDelta(
+  target: VerticalRect,
+  safeArea: Pick<SafeArea, "safeTop" | "safeBottom">,
+  epsilon = KEYBOARD_AVOIDANCE_EPSILON_PX,
+): number {
+  const normalizedEpsilon = Math.max(0, epsilon);
+
+  if (target.top < safeArea.safeTop - normalizedEpsilon) {
+    return target.top - safeArea.safeTop;
+  }
+
+  if (target.bottom > safeArea.safeBottom + normalizedEpsilon) {
+    return target.bottom - safeArea.safeBottom;
+  }
+
+  return 0;
+}
+
+export function clampScrollOffset(offset: number, maxOffset: number): number {
+  return Math.min(Math.max(0, offset), Math.max(0, maxOffset));
+}
+
+export function hasMeaningfulGeometryChange(
+  previous: number,
+  next: number,
+  epsilon = KEYBOARD_AVOIDANCE_EPSILON_PX,
+): boolean {
+  return Math.abs(next - previous) > Math.max(0, epsilon);
+}

package/src/components/KeyboardAvoidingScrollView/index.ts

@@ -0,0 +1,5 @@
+export {
+  KeyboardAvoidingScrollView,
+  type KeyboardAvoidingScrollBehavior,
+  type KeyboardAvoidingScrollViewProps,
+} from "./KeyboardAvoidingScrollView";

package/src/components/KeyboardAvoidingScrollView/keyboard-event-source.test.ts

@@ -0,0 +1,122 @@
+import type { GlobalEventEmitter } from "@lynx-js/types";
+import { describe, expect, it, vi } from "vitest";
+
+import { createKeyboardEventSource } from "./keyboard-event-source";
+
+function createEmitter() {
+  let listener: ((...args: unknown[]) => void) | null = null;
+  const emitter = {
+    addListener: vi.fn((_eventName: string, nextListener: (...args: unknown[]) => void) => {
+      listener = nextListener;
+    }),
+    removeListener: vi.fn(),
+  } as unknown as GlobalEventEmitter;
+
+  return {
+    emitter,
+    emit(...args: unknown[]) {
+      listener?.(...args);
+    },
+  };
+}
+
+describe("createKeyboardEventSource", () => {
+  it("shares one native subscription across subscribers", () => {
+    const { emitter, emit } = createEmitter();
+    const source = createKeyboardEventSource(() => emitter);
+    const first = vi.fn();
+    const second = vi.fn();
+
+    const unsubscribeFirst = source.subscribe(first);
+    const unsubscribeSecond = source.subscribe(second);
+
+    expect(emitter.addListener).toHaveBeenCalledTimes(1);
+    expect(first).toHaveBeenLastCalledWith({ visible: false, height: 0 });
+    expect(second).toHaveBeenLastCalledWith({ visible: false, height: 0 });
+
+    emit("on", 320);
+
+    expect(first).toHaveBeenLastCalledWith({ visible: true, height: 320 });
+    expect(second).toHaveBeenLastCalledWith({ visible: true, height: 320 });
+
+    unsubscribeFirst();
+    expect(emitter.removeListener).not.toHaveBeenCalled();
+
+    unsubscribeSecond();
+    expect(emitter.removeListener).not.toHaveBeenCalled();
+  });
+
+  it("replays the latest state to a late subscriber", () => {
+    const { emitter, emit } = createEmitter();
+    const source = createKeyboardEventSource(() => emitter);
+    const first = vi.fn();
+    const second = vi.fn();
+
+    source.subscribe(first);
+    emit("on", 280);
+    source.subscribe(second);
+
+    expect(second).toHaveBeenCalledWith({ visible: true, height: 280 });
+  });
+
+  it("tracks duplicate listener subscriptions independently", () => {
+    const { emitter, emit } = createEmitter();
+    const source = createKeyboardEventSource(() => emitter);
+    const listener = vi.fn();
+
+    const unsubscribeFirst = source.subscribe(listener);
+    const unsubscribeSecond = source.subscribe(listener);
+    listener.mockClear();
+
+    unsubscribeFirst();
+    emit("on", 280);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(emitter.removeListener).not.toHaveBeenCalled();
+
+    unsubscribeSecond();
+    expect(emitter.removeListener).not.toHaveBeenCalled();
+  });
+
+  it("keeps tracking keyboard state while there are no component subscribers", () => {
+    const { emitter, emit } = createEmitter();
+    const source = createKeyboardEventSource(() => emitter);
+    const first = vi.fn();
+    const second = vi.fn();
+
+    const unsubscribe = source.subscribe(first);
+    unsubscribe();
+    emit("on", 280);
+    source.subscribe(second);
+
+    expect(emitter.addListener).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledWith({ visible: true, height: 280 });
+  });
+
+  it("fails softly when the native emitter is unavailable", () => {
+    const source = createKeyboardEventSource(() => {
+      throw new Error("unsupported");
+    });
+    const listener = vi.fn();
+
+    const unsubscribe = source.subscribe(listener);
+
+    expect(listener).toHaveBeenCalledWith({ visible: false, height: 0 });
+    expect(unsubscribe).not.toThrow();
+  });
+
+  it("normalizes invalid or off payloads", () => {
+    const { emitter, emit } = createEmitter();
+    const source = createKeyboardEventSource(() => emitter);
+    const listener = vi.fn();
+
+    source.subscribe(listener);
+    emit("on", -10);
+    emit("off", 320);
+    emit("unexpected", 320);
+
+    expect(listener).toHaveBeenNthCalledWith(2, { visible: true, height: 0 });
+    expect(listener).toHaveBeenNthCalledWith(3, { visible: false, height: 0 });
+    expect(listener).toHaveBeenNthCalledWith(4, { visible: false, height: 0 });
+  });
+});

package/src/components/KeyboardAvoidingScrollView/keyboard-event-source.ts

@@ -0,0 +1,75 @@
+import type { GlobalEventEmitter } from "@lynx-js/types";
+
+import type { RawKeyboardState } from "./native-driver";
+
+export type KeyboardEventListener = (state: RawKeyboardState) => void;
+
+export interface KeyboardEventSource {
+  subscribe(listener: KeyboardEventListener): () => void;
+}
+
+type GetGlobalEventEmitter = () => GlobalEventEmitter;
+
+export function createKeyboardEventSource(getEmitter: GetGlobalEventEmitter): KeyboardEventSource {
+  const subscriptions = new Set<{ listener: KeyboardEventListener }>();
+  let emitter: GlobalEventEmitter | null = null;
+  let currentState: RawKeyboardState = { visible: false, height: 0 };
+
+  const handleNativeKeyboardEvent = (...args: unknown[]) => {
+    "background only";
+
+    const status = args[0];
+    const height = args[1];
+    currentState = {
+      visible: status === "on",
+      height:
+        status === "on" && typeof height === "number" && Number.isFinite(height)
+          ? Math.max(0, height)
+          : 0,
+    };
+
+    for (const subscription of subscriptions) {
+      subscription.listener(currentState);
+    }
+  };
+
+  return {
+    subscribe(listener) {
+      "background only";
+
+      const subscription = { listener };
+      subscriptions.add(subscription);
+
+      if (emitter === null) {
+        try {
+          const nextEmitter = getEmitter();
+          nextEmitter.addListener("keyboardstatuschanged", handleNativeKeyboardEvent);
+          emitter = nextEmitter;
+        } catch {
+          // GlobalEventEmitter가 없는 host에서는 기본 닫힘 상태로 fail-soft 처리한다.
+        }
+      }
+
+      listener(currentState);
+
+      let subscribed = true;
+
+      return () => {
+        "background only";
+
+        if (!subscribed) return;
+        subscribed = false;
+        subscriptions.delete(subscription);
+
+        // Lynx의 keyboard detection은 listener별 ref-count가 아니다. 모듈 수명 동안
+        // 단일 native listener를 유지해 다른 구독자와 간섭하지 않고 최신 상태도 보존한다.
+      };
+    },
+  };
+}
+
+export const lynxKeyboardEventSource = createKeyboardEventSource(() => {
+  "background only";
+
+  return lynx.getJSModule("GlobalEventEmitter");
+});