@seed-design/lynx-react 0.2.0-alpha.2 → 0.2.0

package/src/hooks/useSafeArea.ts

@@ -0,0 +1,56 @@
+import { useMemo } from "@lynx-js/react";
+
+type SafeAreaEdge = "top" | "bottom";
+
+declare module "@lynx-js/types" {
+  interface GlobalProps {
+    safeAreaInsetTop?: number;
+    safeAreaInsetBottom?: number;
+  }
+}
+
+const safeAreaProp: Record<SafeAreaEdge, "safeAreaInsetTop" | "safeAreaInsetBottom"> = {
+  top: "safeAreaInsetTop",
+  bottom: "safeAreaInsetBottom",
+};
+
+function getSafeAreaEnvInset(edge: SafeAreaEdge): string {
+  return `env(safe-area-inset-${edge})`;
+}
+
+function normalizeSafeAreaValue(value: number | undefined): string | undefined {
+  if (typeof value !== "number" || value <= 0 || !Number.isFinite(value)) {
+    return undefined;
+  }
+
+  return `${value}px`;
+}
+
+function resolveSafeAreaInset(edge: SafeAreaEdge, value: number | undefined): string {
+  return normalizeSafeAreaValue(value) ?? getSafeAreaEnvInset(edge);
+}
+
+export interface UseSafeAreaReturn {
+  safeAreaInsetTop: string;
+  safeAreaInsetBottom: string;
+}
+
+/**
+ * Lynx 앱에서 top/bottom safe area inset 값을 반환합니다.
+ *
+ * `lynx.__globalProps.safeAreaInsetTop`과 `safeAreaInsetBottom`을 우선 사용하고,
+ * host가 값을 제공하지 않으면 Lynx CSS `env(safe-area-inset-*)` 값을 fallback으로
+ * 반환합니다.
+ */
+export function useSafeArea(): UseSafeAreaReturn {
+  const safeAreaInsetTop = lynx.__globalProps?.[safeAreaProp.top];
+  const safeAreaInsetBottom = lynx.__globalProps?.[safeAreaProp.bottom];
+
+  return useMemo(
+    () => ({
+      safeAreaInsetTop: resolveSafeAreaInset("top", safeAreaInsetTop),
+      safeAreaInsetBottom: resolveSafeAreaInset("bottom", safeAreaInsetBottom),
+    }),
+    [safeAreaInsetTop, safeAreaInsetBottom],
+  );
+}

package/src/index.ts

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

package/src/types.ts

@@ -0,0 +1,76 @@
+import type { ReactNode, Ref } from "@lynx-js/react";
+import type {
+  CSSProperties,
+  IntrinsicElements,
+  MainThread,
+  NodesRef,
+  TextProps,
+  ViewProps,
+} from "@lynx-js/types";
+
+export type LynxViewProps = IntrinsicElements["view"] & ViewProps;
+export type LynxTextProps = IntrinsicElements["text"] & TextProps;
+export type LynxViewRef = Ref<NodesRef>;
+export type LynxTextRef = Ref<NodesRef>;
+export type LynxMainThreadRef = Ref<MainThread.Element>;
+export type LynxStyle = CSSProperties;
+
+export interface LynxElementProps {
+  children?: ReactNode;
+  className?: LynxViewProps["className"];
+}
+
+export interface LynxStyledElementProps extends LynxElementProps {
+  style?: LynxStyle;
+}
+
+export interface LynxPressableProps {
+  bindtap?: LynxViewProps["bindtap"];
+  "main-thread:bindtap"?: LynxViewProps["main-thread:bindtap"];
+}
+
+export interface LynxTouchProps {
+  bindtap?: LynxViewProps["bindtap"];
+  bindtouchstart?: LynxViewProps["bindtouchstart"];
+  bindtouchend?: LynxViewProps["bindtouchend"];
+  bindtouchcancel?: LynxViewProps["bindtouchcancel"];
+  "main-thread:bindtap"?: LynxViewProps["main-thread:bindtap"];
+}
+
+export interface LynxIconElementProps {
+  className?: IntrinsicElements["image"]["className"];
+  style?: LynxStyle;
+  ref?: LynxMainThreadRef;
+  "main-thread:binduiappear"?: IntrinsicElements["image"]["main-thread:binduiappear"];
+}
+
+/**
+ * @platform Lynx
+ *
+ * native element(`<view>`/`<text>`/`<image>` 등)가 공유하는 접근성 속성 모음.
+ * `@lynx-js/types`의 StandardProps 접근성 속성을 표준화한 타입으로, 컴포넌트가
+ * 확장해 native element에 패스스루한다. 모든 native tag가 동일한 공통 속성을
+ * 가지며 tag별 차이는 없다.
+ *
+ * web ARIA 대응:
+ * - `accessibility-label` ← `aria-label`
+ * - `accessibility-role-description` ← `role` (switch/checkbox/progressbar)
+ * - `accessibility-value` ← `aria-checked` / `aria-valuenow`
+ * - `accessibility-elements-hidden` ← `aria-hidden`
+ *
+ * `accessibility-traits`는 단일 값이라 `selected`+`disabled` 동시 표현이 안 된다.
+ * 역할은 `accessibility-role-description`, 상태는 `accessibility-value`로 분담한다.
+ */
+export type LynxAccessibilityProps = Pick<
+  LynxViewProps,
+  | "accessibility-label"
+  | "accessibility-traits"
+  | "accessibility-element"
+  | "accessibility-value"
+  | "accessibility-role-description"
+  | "accessibility-elements-hidden"
+  | "accessibility-heading"
+  | "accessibility-actions"
+  | "accessibility-exclusive-focus"
+  | "ios-platform-accessibility-id"
+>;

package/src/utils/children.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "@lynx-js/react";
+
+export function toArray(children: ReactNode): ReactNode[] {
+  if (children == null || typeof children === "boolean") {
+    return [];
+  }
+
+  if (Array.isArray(children)) {
+    return children.flatMap(toArray);
+  }
+
+  return [children];
+}

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

@@ -0,0 +1,96 @@
+import { forwardRef } from "@lynx-js/react";
+import { render } from "@lynx-js/react/testing-library";
+import { describe, expect, it } from "vitest";
+
+import { createSlotRecipeContext } from "./create-slot-recipe-context";
+
+type MockVariantProps = {
+  variant?: "a" | "b";
+};
+
+type MockClassnames = {
+  root: string;
+  label: string;
+};
+
+const mockSlotRecipe = Object.assign(
+  (props?: MockVariantProps): MockClassnames => ({
+    root: `root-${props?.variant ?? "a"}`,
+    label: `label-${props?.variant ?? "a"}`,
+  }),
+  {
+    splitVariantProps: <T extends MockVariantProps>(props: T) => {
+      const { variant, ...rest } = props;
+      return [{ variant }, rest] as [MockVariantProps, Omit<T, keyof MockVariantProps>];
+    },
+  },
+);
+
+type MockProps = {
+  children?: unknown;
+  className?: string;
+};
+
+type MockReceived = { props?: MockProps };
+
+function createMock(name: string) {
+  const received: MockReceived = {};
+  const Mock = forwardRef<{ tag: "mock" }, MockProps>((props) => {
+    received.props = props;
+    return <>{props.children as never}</>;
+  });
+  Mock.displayName = name;
+  return { Mock, received };
+}
+
+describe("createSlotRecipeContext", () => {
+  it("rejects intrinsic native tags to avoid Lynx BackgroundSnapshot errors", () => {
+    const { withRootProvider, withProvider, withContext } = createSlotRecipeContext(mockSlotRecipe);
+
+    expect(() => withRootProvider<MockVariantProps>("view")).toThrow(
+      /literal JSX.*BackgroundSnapshot/,
+    );
+    expect(() => withProvider<unknown, MockVariantProps>("view", "root")).toThrow(
+      /literal JSX.*BackgroundSnapshot/,
+    );
+    expect(() => withContext<unknown, Record<string, unknown>>("text", "label")).toThrow(
+      /literal JSX.*BackgroundSnapshot/,
+    );
+  });
+
+  it("injects root classnames into context without applying className on the root element", () => {
+    const { Mock: Root, received: rootReceived } = createMock("Root");
+    const { Mock: Child, received: childReceived } = createMock("Child");
+    const { withRootProvider, withContext } = createSlotRecipeContext(mockSlotRecipe);
+
+    const StyledRoot = withRootProvider<MockVariantProps & MockProps>(Root);
+    const StyledLabel = withContext<{ tag: "mock" }, MockProps>(Child, "label");
+
+    render(
+      <StyledRoot variant="b">
+        <StyledLabel />
+      </StyledRoot>,
+    );
+
+    expect(rootReceived.props).not.toHaveProperty("className");
+    expect(childReceived.props?.className).toBe("label-b");
+  });
+
+  it("applies and merges provider slot classnames", () => {
+    const { Mock: Root, received: rootReceived } = createMock("Root");
+    const { Mock: Child, received: childReceived } = createMock("Child");
+    const { withProvider, withContext } = createSlotRecipeContext(mockSlotRecipe);
+
+    const StyledRoot = withProvider<{ tag: "mock" }, MockVariantProps & MockProps>(Root, "root");
+    const StyledLabel = withContext<{ tag: "mock" }, MockProps>(Child, "label");
+
+    render(
+      <StyledRoot variant="a" className="extra">
+        <StyledLabel className="child-extra" />
+      </StyledRoot>,
+    );
+
+    expect(rootReceived.props?.className).toBe("root-a extra");
+    expect(childReceived.props?.className).toBe("label-a child-extra");
+  });
+});

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

@@ -1,4 +1,12 @@
 import { createContext, forwardRef, useContext } from "@lynx-js/react";
+import type {
+  ElementType,
+  ForwardRefExoticComponent,
+  PropsWithoutRef,
+  ReactElement,
+  ReactNode,
+  RefAttributes,
+} from "@lynx-js/react";
 import clsx from "clsx";
 
 type SlotRecipe<
@@ -8,24 +16,53 @@ type SlotRecipe<
   splitVariantProps: <T extends Props>(props: T) => [Props, Omit<T, keyof Props>];
 };
 
+function assertNotIntrinsicComponent(Component: ElementType<any>, caller: string) {
+  if (typeof Component !== "string") return;
+
+  throw new Error(
+    `${caller} cannot wrap intrinsic tag "${Component}" in Lynx. Native <view>/<text> slots must be rendered as literal JSX in the component file; passing intrinsic strings through createSlotRecipeContext can cause BackgroundSnapshot not found errors.`,
+  );
+}
+
 export function createSlotRecipeContext<
   Props extends Record<string, string | boolean | undefined>,
   Classnames extends Record<string, string>,
->(recipe: SlotRecipe<Props, Classnames>) {
+>(
+  recipe: SlotRecipe<Props, Classnames>,
+): {
+  ClassNamesProvider: (props: { children: ReactNode; value: Classnames }) => ReactElement;
+  PropsProvider: (props: { children: ReactNode; value: Props }) => ReactElement;
+  useClassNames: () => Classnames;
+  useProps: () => Props | null;
+  withRootProvider: <P>(
+    Component: ElementType<any>,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ) => ForwardRefExoticComponent<PropsWithoutRef<P>>;
+  withProvider: <T, P>(
+    Component: ElementType<any>,
+    slot: keyof Classnames,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ) => ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>;
+  withContext: <T, P>(
+    Component: ElementType<any>,
+    slot?: keyof Classnames,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ) => ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>;
+} {
   const ClassNamesContext = createContext<Classnames | null>(null);
   const PropsContext = createContext<Props | null>(null);
 
-  const ClassNamesProvider = ({
-    children,
-    value,
-  }: {
-    children: React.ReactNode;
-    value: Classnames;
-  }) => {
+  const ClassNamesProvider = ({ children, value }: { children: ReactNode; value: Classnames }) => {
     return <ClassNamesContext.Provider value={value}>{children}</ClassNamesContext.Provider>;
   };
 
-  const PropsProvider = ({ children, value }: { children: React.ReactNode; value: Props }) => {
+  const PropsProvider = ({ children, value }: { children: ReactNode; value: Props }) => {
     return <PropsContext.Provider value={value}>{children}</PropsContext.Provider>;
   };
 
@@ -45,11 +82,12 @@ export function createSlotRecipeContext<
   }
 
   const withRootProvider = <P,>(
-    Component: React.ElementType<any>,
+    Component: ElementType<any>,
     options?: {
       defaultProps?: Partial<P>;
     },
-  ): React.ForwardRefExoticComponent<React.PropsWithoutRef<P>> => {
+  ): ForwardRefExoticComponent<PropsWithoutRef<P>> => {
+    assertNotIntrinsicComponent(Component, "withRootProvider");
     const { defaultProps } = options ?? {};
 
     const StyledComponent = (innerProps: any) => {
@@ -74,12 +112,13 @@ export function createSlotRecipeContext<
   };
 
   const withProvider = <T, P>(
-    Component: React.ElementType<any>,
+    Component: ElementType<any>,
     slot: keyof Classnames,
     options?: {
       defaultProps?: Partial<P>;
     },
-  ): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>> => {
+  ): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>> => {
+    assertNotIntrinsicComponent(Component, "withProvider");
     const { defaultProps } = options ?? {};
 
     const StyledComponent = forwardRef<any, any>((innerProps, ref) => {
@@ -108,12 +147,13 @@ export function createSlotRecipeContext<
   };
 
   const withContext = <T, P>(
-    Component: React.ElementType<any>,
+    Component: ElementType<any>,
     slot?: keyof Classnames,
     options?: {
       defaultProps?: Partial<P>;
     },
-  ): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>> => {
+  ): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>> => {
+    assertNotIntrinsicComponent(Component, "withContext");
     const { defaultProps } = options ?? {};
 
     const StyledComponent = forwardRef<any, any>((innerProps, ref) => {

package/src/utils/get-seed-class-name.ts

@@ -4,17 +4,16 @@ declare const lynx: {
   __globalProps?: Record<string, unknown>;
 };
 
-declare const SystemInfo: {
-  platform?: "Android" | "iOS" | "Harmony" | "windows" | "macOS";
-};
+export type ColorMode = "system" | "light-only" | "dark-only";
 
-type ColorMode = "system" | "light-only" | "dark-only";
+export interface GetSeedClassNameOptions {
+  colorMode?: ColorMode;
+}
 
 /**
  * Lynx 앱의 root `<page>` 요소에 적용할 SEED Design className을 반환한다.
  *
- * 테마(dark/light)와 플랫폼(iOS/Android)을 자동 감지하여
- * 렌더링 전에 올바른 CSS 변수가 적용되도록 한다.
+ * 테마(dark/light)를 자동 감지하여 렌더링 전에 올바른 CSS 변수가 적용되도록 한다.
  *
  * @example
  * ```tsx
@@ -27,7 +26,7 @@ type ColorMode = "system" | "light-only" | "dark-only";
  * );
  * ```
  */
-export function getSeedClassName(options?: { colorMode?: ColorMode }): string {
+export function getSeedClassName(options?: GetSeedClassNameOptions): string {
   const { colorMode = "system" } = options ?? {};
 
   // Theme — lynx.__globalProps.theme에서 시스템 테마 읽기
@@ -44,9 +43,5 @@ export function getSeedClassName(options?: { colorMode?: ColorMode }): string {
         : "seed-user-color-scheme-light";
   }
 
-  // Platform — SystemInfo.platform에서 디바이스 플랫폼 읽기
-  const platform = SystemInfo?.platform;
-  const platformClass = platform === "iOS" ? "seed-platform-ios" : "seed-platform-android";
-
-  return `${themeClass} ${platformClass}`;
+  return themeClass;
 }

package/src/utils/{__tests__/split-multiple-variants-props.test.ts → split-multiple-variants-props.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { splitMultipleVariantsProps } from "../split-multiple-variants-props";
+import { splitMultipleVariantsProps } from "./split-multiple-variants-props";
 
 function makeRecipe<V extends Record<string, unknown>>(variantKeys: (keyof V)[]) {
   return {