@seed-design/lynx-react 0.3.1 → 0.4.1

package/src/components/Field/index.ts

@@ -0,0 +1,21 @@
+export {
+  FieldCharacterCount,
+  FieldDescription,
+  FieldErrorMessage,
+  FieldFooter,
+  FieldHeader,
+  FieldIndicatorText,
+  FieldLabel,
+  FieldRequiredIndicator,
+  FieldRoot,
+  type FieldCharacterCountProps,
+  type FieldDescriptionProps,
+  type FieldErrorMessageProps,
+  type FieldFooterProps,
+  type FieldHeaderProps,
+  type FieldIndicatorTextProps,
+  type FieldLabelProps,
+  type FieldRootProps,
+} from "./Field";
+
+export * as Field from "./Field.namespace";

package/src/components/KeyboardAvoidingScrollView/KeyboardAvoidingScrollView.test.tsx

@@ -0,0 +1,267 @@
+import "@testing-library/jest-dom";
+import { act, fireEvent, render } from "@lynx-js/react/testing-library";
+import type { NodesRef } from "@lynx-js/types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+interface MockEngineOptions {
+  driver: unknown;
+  scheduler: unknown;
+  getScrollNode(): unknown;
+  getSpacerNode(): unknown;
+  getKeyboardGap(): number;
+  getToolbarHeight(): number;
+  getSmooth(): boolean;
+}
+
+const mocks = vi.hoisted(() => {
+  const engine = {
+    focus: vi.fn(),
+    blur: vi.fn(),
+    layoutChanged: vi.fn(),
+    unregister: vi.fn(),
+    keyboardChanged: vi.fn(),
+    viewportChanged: vi.fn(),
+    userScrollStarted: vi.fn(),
+    userScrollEnded: vi.fn(),
+    dispose: vi.fn(),
+  };
+  const unsubscribe = vi.fn();
+
+  return {
+    engine,
+    createEngine: vi.fn((_options: MockEngineOptions) => engine),
+    nativeDriver: {},
+    keyboardSource: {
+      listener: null as ((state: { visible: boolean; height: number }) => void) | null,
+      subscribe: vi.fn(),
+      unsubscribe,
+    },
+  };
+});
+
+vi.mock("./engine", () => ({
+  createKeyboardAvoidingEngine: mocks.createEngine,
+}));
+
+vi.mock("./native-driver", () => ({
+  lynxKeyboardAvoidingNativeDriver: mocks.nativeDriver,
+}));
+
+vi.mock("./keyboard-event-source", () => ({
+  lynxKeyboardEventSource: {
+    subscribe: mocks.keyboardSource.subscribe,
+  },
+}));
+
+import { useEffect } from "@lynx-js/react";
+
+import { useKeyboardAvoidanceActions, type KeyboardAvoidanceRegistration } from "./context";
+import {
+  KeyboardAvoidingScrollView,
+  type KeyboardAvoidingScrollViewProps,
+} from "./KeyboardAvoidingScrollView";
+
+function ContextConsumer({ registration }: { registration: KeyboardAvoidanceRegistration }) {
+  const actions = useKeyboardAvoidanceActions();
+
+  useEffect(() => {
+    if (!actions) {
+      throw new Error("KeyboardAvoidingScrollView context가 필요합니다.");
+    }
+
+    actions.focus(registration);
+    actions.layoutChanged(registration.owner);
+
+    return () => {
+      actions.blur(registration.owner);
+      actions.unregister(registration.owner);
+    };
+  }, [actions, registration]);
+
+  return <view />;
+}
+
+function getScrollView(container: HTMLElement): Element {
+  const scrollView = container.querySelector("scroll-view");
+  if (!scrollView) {
+    throw new Error("scroll-view가 렌더되어야 합니다.");
+  }
+  return scrollView;
+}
+
+function getEventTargetRef(ref: { current: NodesRef | null }): HTMLElement {
+  if (!ref.current) {
+    throw new Error("scroll-view NodesRef가 연결되어야 합니다.");
+  }
+  return ref.current as unknown as HTMLElement;
+}
+
+describe("KeyboardAvoidingScrollView", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.keyboardSource.listener = null;
+    mocks.keyboardSource.subscribe.mockImplementation((listener) => {
+      mocks.keyboardSource.listener = listener;
+      return mocks.keyboardSource.unsubscribe;
+    });
+  });
+
+  it("renders a forced vertical scroll-view and an internal native spacer", () => {
+    const conflictingNativeProps = {
+      flatten: true,
+      "scroll-orientation": "horizontal",
+    } as unknown as KeyboardAvoidingScrollViewProps;
+    const { container, getByText } = render(
+      <KeyboardAvoidingScrollView {...conflictingNativeProps} id="form" className="custom-scroll">
+        <text>Form content</text>
+      </KeyboardAvoidingScrollView>,
+    );
+
+    const scrollView = getScrollView(container);
+    const spacer = scrollView.lastElementChild;
+
+    expect(scrollView).toHaveAttribute("scroll-orientation", "vertical");
+    expect(scrollView).toHaveAttribute("id", "form");
+    expect(scrollView).toHaveClass("custom-scroll");
+    expect(scrollView).toContainElement(getByText("Form content") as HTMLElement);
+    expect(spacer?.tagName.toLowerCase()).toBe("view");
+    expect(spacer).toHaveAttribute("accessibility-elements-hidden", "true");
+  });
+
+  it("composes viewport and user-scroll event handlers", () => {
+    const bindlayoutchange = vi.fn();
+    const bindtouchstart = vi.fn();
+    const bindtouchend = vi.fn();
+    const bindtouchcancel = vi.fn();
+    const bindscroll = vi.fn();
+    const bindscrollend = vi.fn();
+    const scrollRef = { current: null as NodesRef | null };
+    render(
+      <KeyboardAvoidingScrollView
+        ref={scrollRef}
+        bindlayoutchange={bindlayoutchange}
+        bindtouchstart={bindtouchstart}
+        bindtouchend={bindtouchend}
+        bindtouchcancel={bindtouchcancel}
+        bindscroll={bindscroll}
+        bindscrollend={bindscrollend}
+      />,
+    );
+    const scrollView = getEventTargetRef(scrollRef);
+
+    act(() => {
+      fireEvent.layoutchange(scrollView, {});
+      fireEvent.touchstart(scrollView, {});
+      fireEvent.scroll(scrollView, {});
+      fireEvent.touchend(scrollView, {});
+    });
+
+    expect(bindlayoutchange).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.viewportChanged).toHaveBeenCalledTimes(1);
+    expect(bindtouchstart).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.userScrollStarted).toHaveBeenCalledTimes(1);
+    expect(bindscroll).toHaveBeenCalledTimes(1);
+    expect(bindtouchend).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.userScrollEnded).not.toHaveBeenCalled();
+
+    act(() => {
+      fireEvent.scrollend(scrollView, {});
+      fireEvent.touchstart(scrollView, {});
+      fireEvent.touchcancel(scrollView, {});
+    });
+
+    expect(bindscrollend).toHaveBeenCalledTimes(1);
+    expect(bindtouchcancel).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.userScrollStarted).toHaveBeenCalledTimes(2);
+    expect(mocks.engine.userScrollEnded).toHaveBeenCalledTimes(2);
+  });
+
+  it("ends a touch that did not scroll without waiting for scrollend", () => {
+    const scrollRef = { current: null as NodesRef | null };
+    render(<KeyboardAvoidingScrollView ref={scrollRef} />);
+    const scrollView = getEventTargetRef(scrollRef);
+
+    act(() => {
+      fireEvent.touchstart(scrollView, {});
+      fireEvent.touchend(scrollView, {});
+    });
+
+    expect(mocks.engine.userScrollStarted).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.userScrollEnded).toHaveBeenCalledTimes(1);
+  });
+
+  it("updates engine state before invoking the user handler", () => {
+    const bindlayoutchange = vi.fn();
+    const scrollRef = { current: null as NodesRef | null };
+    render(<KeyboardAvoidingScrollView ref={scrollRef} bindlayoutchange={bindlayoutchange} />);
+    const scrollView = getEventTargetRef(scrollRef);
+
+    fireEvent.layoutchange(scrollView, {});
+
+    expect(bindlayoutchange).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.viewportChanged).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.viewportChanged.mock.invocationCallOrder[0]).toBeLessThan(
+      bindlayoutchange.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+    );
+  });
+
+  it("keeps engine options live without recreating the engine", () => {
+    const { rerender } = render(
+      <KeyboardAvoidingScrollView keyboardGap={32} scrollBehavior="smooth" />,
+    );
+    const options = mocks.createEngine.mock.calls[0]?.[0];
+
+    expect(options?.driver).toBe(mocks.nativeDriver);
+    expect(options?.getKeyboardGap()).toBe(32);
+    expect(options?.getToolbarHeight()).toBe(0);
+    expect(options?.getSmooth()).toBe(true);
+
+    rerender(<KeyboardAvoidingScrollView keyboardGap={-8} scrollBehavior="instant" />);
+
+    expect(mocks.createEngine).toHaveBeenCalledTimes(1);
+    expect(options?.getKeyboardGap()).toBe(-8);
+    expect(options?.getSmooth()).toBe(false);
+    expect(mocks.engine.viewportChanged).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards private registration actions through a stable context", () => {
+    const registration: KeyboardAvoidanceRegistration = {
+      owner: {},
+      nativeRef: { current: null },
+    };
+    const { rerender, unmount } = render(
+      <KeyboardAvoidingScrollView keyboardGap={24}>
+        <ContextConsumer registration={registration} />
+      </KeyboardAvoidingScrollView>,
+    );
+
+    expect(mocks.engine.focus).toHaveBeenCalledWith(registration);
+    expect(mocks.engine.layoutChanged).toHaveBeenCalledWith(registration.owner);
+
+    rerender(
+      <KeyboardAvoidingScrollView keyboardGap={48}>
+        <ContextConsumer registration={registration} />
+      </KeyboardAvoidingScrollView>,
+    );
+    expect(mocks.engine.focus).toHaveBeenCalledTimes(1);
+
+    unmount();
+    expect(mocks.engine.blur).toHaveBeenCalledWith(registration.owner);
+    expect(mocks.engine.unregister).toHaveBeenCalledWith(registration.owner);
+  });
+
+  it("subscribes keyboard state and cleans up the shared source and engine", () => {
+    const { unmount } = render(<KeyboardAvoidingScrollView />);
+
+    expect(mocks.keyboardSource.subscribe).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      mocks.keyboardSource.listener?.({ visible: true, height: 320 });
+    });
+    expect(mocks.engine.keyboardChanged).toHaveBeenCalledWith({ visible: true, height: 320 });
+
+    unmount();
+    expect(mocks.keyboardSource.unsubscribe).toHaveBeenCalledTimes(1);
+    expect(mocks.engine.dispose).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/KeyboardAvoidingScrollView/KeyboardAvoidingScrollView.tsx

@@ -0,0 +1,299 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type ForwardRefExoticComponent,
+  type PropsWithoutRef,
+  type RefAttributes,
+} from "@lynx-js/react";
+import type { IntrinsicElements, NodesRef } from "@lynx-js/types";
+
+import type {
+  LynxAccessibilityProps,
+  LynxStyledElementProps,
+  LynxTouchProps,
+  LynxViewProps,
+  LynxViewRef,
+} from "../../types";
+import { KeyboardAvoidanceActionsContext, type KeyboardAvoidanceActions } from "./context";
+import { createKeyboardAvoidingEngine, type KeyboardAvoidingScheduler } from "./engine";
+import { lynxKeyboardEventSource } from "./keyboard-event-source";
+import { lynxKeyboardAvoidingNativeDriver } from "./native-driver";
+
+type NativeScrollViewProps = IntrinsicElements["scroll-view"];
+type LayoutChangeHandler = NonNullable<NativeScrollViewProps["bindlayoutchange"]>;
+type ScrollHandler = NonNullable<NativeScrollViewProps["bindscroll"]>;
+type ScrollEndHandler = NonNullable<NativeScrollViewProps["bindscrollend"]>;
+type TouchStartHandler = NonNullable<NativeScrollViewProps["bindtouchstart"]>;
+type TouchEndHandler = NonNullable<NativeScrollViewProps["bindtouchend"]>;
+type TouchCancelHandler = NonNullable<NativeScrollViewProps["bindtouchcancel"]>;
+type LynxForwardRefComponent<T, P> = ForwardRefExoticComponent<
+  PropsWithoutRef<P> & RefAttributes<T>
+>;
+
+export type KeyboardAvoidingScrollBehavior = "smooth" | "instant";
+
+const lynxKeyboardAvoidingScheduler: KeyboardAvoidingScheduler = {
+  scheduleFrame(callback) {
+    "background only";
+
+    const frame = requestAnimationFrame(() => {
+      "background only";
+      void callback();
+    });
+
+    return () => {
+      "background only";
+      cancelAnimationFrame(frame);
+    };
+  },
+  scheduleTimer(callback, delayMs) {
+    "background only";
+
+    const timer = setTimeout(() => {
+      "background only";
+      void callback();
+    }, delayMs);
+
+    return () => {
+      "background only";
+      clearTimeout(timer);
+    };
+  },
+};
+
+const spacerProps = {
+  "accessibility-elements-hidden": true,
+  flatten: false,
+} satisfies LynxViewProps;
+
+/**
+ * @platform Lynx
+ *
+ * 세로 `<scroll-view>` 안의 활성 입력 요소가 키보드에 가려지지 않도록 한다.
+ * `TextField.Input`과 `TextField.Textarea`는 focus 시 자동으로 이 컴포넌트에 등록된다.
+ *
+ * 현재 미지원 기능:
+ * - 가로 스크롤과 중첩 스크롤
+ * - 키보드 툴바 높이 반영
+ * - 큰 Textarea의 caret 단위 회피
+ */
+export interface KeyboardAvoidingScrollViewProps
+  extends LynxStyledElementProps,
+    LynxAccessibilityProps,
+    LynxTouchProps {
+  id?: NativeScrollViewProps["id"];
+  hidden?: NativeScrollViewProps["hidden"];
+  focusable?: NativeScrollViewProps["focusable"];
+  bounces?: NativeScrollViewProps["bounces"];
+  "enable-scroll"?: NativeScrollViewProps["enable-scroll"];
+  "scroll-bar-enable"?: NativeScrollViewProps["scroll-bar-enable"];
+  "upper-threshold"?: NativeScrollViewProps["upper-threshold"];
+  "lower-threshold"?: NativeScrollViewProps["lower-threshold"];
+  "initial-scroll-offset"?: NativeScrollViewProps["initial-scroll-offset"];
+  "initial-scroll-to-index"?: NativeScrollViewProps["initial-scroll-to-index"];
+  bindlayoutchange?: NativeScrollViewProps["bindlayoutchange"];
+  bindscrolltoupper?: NativeScrollViewProps["bindscrolltoupper"];
+  bindscrolltolower?: NativeScrollViewProps["bindscrolltolower"];
+  bindscroll?: NativeScrollViewProps["bindscroll"];
+  bindscrollend?: NativeScrollViewProps["bindscrollend"];
+  bindcontentsizechanged?: NativeScrollViewProps["bindcontentsizechanged"];
+  /** 키보드와 활성 입력 요소 사이에 확보할 간격(px). @defaultValue 24 */
+  keyboardGap?: number;
+  /** 회피 위치로 이동할 때 사용할 스크롤 방식. @defaultValue "smooth" */
+  scrollBehavior?: KeyboardAvoidingScrollBehavior;
+}
+
+export const KeyboardAvoidingScrollView: LynxForwardRefComponent<
+  NodesRef,
+  KeyboardAvoidingScrollViewProps
+> = forwardRef<NodesRef, KeyboardAvoidingScrollViewProps>((props, forwardedRef) => {
+  const {
+    children,
+    keyboardGap = 24,
+    scrollBehavior = "smooth",
+    bindlayoutchange: userBindLayoutChange,
+    bindscroll: userBindScroll,
+    bindscrollend: userBindScrollEnd,
+    bindtouchstart: userBindTouchStart,
+    bindtouchend: userBindTouchEnd,
+    bindtouchcancel: userBindTouchCancel,
+    ...nativeProps
+  } = props;
+  const scrollRef = useRef<NodesRef>(null);
+  const spacerRef = useRef<NodesRef>(null);
+  const keyboardGapRef = useRef(keyboardGap);
+  const committedKeyboardGapRef = useRef(keyboardGap);
+  const scrollBehaviorRef = useRef(scrollBehavior);
+  const touchActiveRef = useRef(false);
+  const didScrollDuringTouchRef = useRef(false);
+
+  keyboardGapRef.current = keyboardGap;
+  scrollBehaviorRef.current = scrollBehavior;
+
+  const engine = useMemo(
+    () =>
+      createKeyboardAvoidingEngine({
+        driver: lynxKeyboardAvoidingNativeDriver,
+        scheduler: lynxKeyboardAvoidingScheduler,
+        getScrollNode: () => scrollRef.current,
+        getSpacerNode: () => spacerRef.current,
+        getKeyboardGap: () => keyboardGapRef.current,
+        getToolbarHeight: () => 0,
+        getSmooth: () => scrollBehaviorRef.current === "smooth",
+      }),
+    [],
+  );
+
+  const mergedRef = useCallback(
+    (node: NodesRef | null) => {
+      "background only";
+
+      scrollRef.current = node;
+      if (typeof forwardedRef === "function") {
+        forwardedRef(node);
+      } else if (forwardedRef) {
+        forwardedRef.current = node;
+      }
+    },
+    [forwardedRef],
+  );
+
+  const actions = useMemo<KeyboardAvoidanceActions>(
+    () => ({
+      focus(registration) {
+        "background only";
+        engine.focus(registration);
+      },
+      blur(owner) {
+        "background only";
+        engine.blur(owner);
+      },
+      layoutChanged(owner) {
+        "background only";
+        engine.layoutChanged(owner);
+      },
+      unregister(owner) {
+        "background only";
+        engine.unregister(owner);
+      },
+    }),
+    [engine],
+  );
+
+  useEffect(() => {
+    const unsubscribe = lynxKeyboardEventSource.subscribe((state) => {
+      "background only";
+      engine.keyboardChanged(state);
+    });
+
+    return () => {
+      unsubscribe();
+      engine.dispose();
+    };
+  }, [engine]);
+
+  useEffect(() => {
+    if (Object.is(committedKeyboardGapRef.current, keyboardGap)) return;
+
+    committedKeyboardGapRef.current = keyboardGap;
+    engine.viewportChanged();
+  }, [engine, keyboardGap]);
+
+  const handleLayoutChange = useCallback<LayoutChangeHandler>(
+    (...args) => {
+      "background only";
+
+      engine.viewportChanged();
+      userBindLayoutChange?.(...args);
+    },
+    [engine, userBindLayoutChange],
+  );
+
+  const handleTouchStart = useCallback<TouchStartHandler>(
+    (...args) => {
+      "background only";
+
+      touchActiveRef.current = true;
+      didScrollDuringTouchRef.current = false;
+      engine.userScrollStarted();
+      userBindTouchStart?.(...args);
+    },
+    [engine, userBindTouchStart],
+  );
+
+  const handleScroll = useCallback<ScrollHandler>(
+    (...args) => {
+      "background only";
+
+      if (touchActiveRef.current) {
+        didScrollDuringTouchRef.current = true;
+      }
+      userBindScroll?.(...args);
+    },
+    [userBindScroll],
+  );
+
+  const handleTouchEnd = useCallback<TouchEndHandler>(
+    (...args) => {
+      "background only";
+
+      touchActiveRef.current = false;
+      if (!didScrollDuringTouchRef.current) {
+        engine.userScrollEnded();
+      }
+      userBindTouchEnd?.(...args);
+    },
+    [engine, userBindTouchEnd],
+  );
+
+  const handleTouchCancel = useCallback<TouchCancelHandler>(
+    (...args) => {
+      "background only";
+
+      touchActiveRef.current = false;
+      didScrollDuringTouchRef.current = false;
+      engine.userScrollEnded();
+      userBindTouchCancel?.(...args);
+    },
+    [engine, userBindTouchCancel],
+  );
+
+  const handleScrollEnd = useCallback<ScrollEndHandler>(
+    (...args) => {
+      "background only";
+
+      touchActiveRef.current = false;
+      didScrollDuringTouchRef.current = false;
+      engine.userScrollEnded();
+      userBindScrollEnd?.(...args);
+    },
+    [engine, userBindScrollEnd],
+  );
+
+  return (
+    <KeyboardAvoidanceActionsContext.Provider value={actions}>
+      <scroll-view
+        {...nativeProps}
+        ref={mergedRef}
+        scroll-orientation="vertical"
+        flatten={false}
+        bindlayoutchange={handleLayoutChange}
+        bindtouchstart={handleTouchStart}
+        bindtouchend={handleTouchEnd}
+        bindtouchcancel={handleTouchCancel}
+        bindscroll={handleScroll}
+        bindscrollend={handleScrollEnd}
+      >
+        {children}
+        <view
+          {...({ ref: spacerRef as LynxViewRef } as Record<string, unknown>)}
+          {...spacerProps}
+        />
+      </scroll-view>
+    </KeyboardAvoidanceActionsContext.Provider>
+  );
+});
+KeyboardAvoidingScrollView.displayName = "KeyboardAvoidingScrollView";

package/src/components/KeyboardAvoidingScrollView/context.ts

@@ -0,0 +1,24 @@
+import { createContext, useContext, type Context } from "@lynx-js/react";
+import type { NodesRef } from "@lynx-js/types";
+
+import type { KeyboardAvoidanceRegistration as EngineRegistration } from "./engine";
+
+export type KeyboardAvoidanceRegistration = EngineRegistration<NodesRef>;
+
+export interface KeyboardAvoidanceActions {
+  focus(registration: KeyboardAvoidanceRegistration): void;
+  blur(owner: object): void;
+  layoutChanged(owner: object): void;
+  unregister(owner: object): void;
+}
+
+export const KeyboardAvoidanceActionsContext: Context<KeyboardAvoidanceActions | null> =
+  createContext<KeyboardAvoidanceActions | null>(null);
+
+/**
+ * Lynx TextField가 선택적으로 소비하는 내부 연결점이다.
+ * Provider 밖에서는 `null`을 반환해 TextField 자체 동작을 방해하지 않는다.
+ */
+export function useKeyboardAvoidanceActions(): KeyboardAvoidanceActions | null {
+  return useContext(KeyboardAvoidanceActionsContext);
+}