@seed-design/lynx-react 0.1.0

package/src/hooks/useSafeArea.test.ts

@@ -0,0 +1,83 @@
+import { renderHook } from "@lynx-js/react/testing-library";
+import { describe, expect, it } from "vitest";
+
+import { useSafeArea } from "./useSafeArea";
+
+interface TestLynxGlobal {
+  lynx?: {
+    __globalProps?: {
+      safeAreaInsetTop?: number;
+      safeAreaInsetBottom?: number;
+    };
+  };
+  lynxTestingEnv?: {
+    backgroundThread: {
+      globalThis: TestLynxGlobal;
+    };
+    mainThread: {
+      globalThis: TestLynxGlobal;
+    };
+  };
+}
+
+function setGlobalProps(
+  globalProps: NonNullable<NonNullable<TestLynxGlobal["lynx"]>["__globalProps"]>,
+) {
+  const lynxTestingEnv = (globalThis as TestLynxGlobal).lynxTestingEnv;
+
+  if (!lynxTestingEnv) {
+    throw new Error("Expected Lynx testing environment globals to be available.");
+  }
+
+  const globals = [
+    globalThis as TestLynxGlobal,
+    lynxTestingEnv.backgroundThread.globalThis,
+    lynxTestingEnv.mainThread.globalThis,
+  ];
+
+  for (const global of globals) {
+    global.lynx = {
+      ...global.lynx,
+      __globalProps: globalProps,
+    };
+  }
+}
+
+describe("useSafeArea", () => {
+  it("falls back to Lynx env values when host flat global props are missing", () => {
+    const { result } = renderHook(() => useSafeArea());
+
+    expect(result.current).toEqual({
+      safeAreaInsetTop: "env(safe-area-inset-top)",
+      safeAreaInsetBottom: "env(safe-area-inset-bottom)",
+    });
+  });
+
+  it("uses flat globalProps values before env fallback", () => {
+    setGlobalProps({
+      safeAreaInsetTop: 48,
+      safeAreaInsetBottom: 35,
+    });
+
+    const { result } = renderHook(() => useSafeArea());
+
+    expect(result.current).toEqual({
+      safeAreaInsetTop: "48px",
+      safeAreaInsetBottom: "35px",
+    });
+  });
+
+  it("falls back to Lynx env values when host flat global props are zero", () => {
+    setGlobalProps({
+      safeAreaInsetTop: 0,
+      safeAreaInsetBottom: 0,
+    });
+
+    const { result } = renderHook(() => useSafeArea());
+
+    expect(result.current).toEqual({
+      safeAreaInsetTop: "env(safe-area-inset-top)",
+      safeAreaInsetBottom: "env(safe-area-inset-bottom)",
+    });
+  });
+});

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

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

package/src/types.ts

@@ -0,0 +1,45 @@
+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"];
+}

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

@@ -0,0 +1,187 @@
+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<
+  Props extends Record<string, string | boolean | undefined>,
+  Classnames extends Record<string, string>,
+> = ((props?: Props) => Classnames) & {
+  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>,
+): {
+  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: ReactNode; value: Classnames }) => {
+    return <ClassNamesContext.Provider value={value}>{children}</ClassNamesContext.Provider>;
+  };
+
+  const PropsProvider = ({ children, value }: { children: ReactNode; value: Props }) => {
+    return <PropsContext.Provider value={value}>{children}</PropsContext.Provider>;
+  };
+
+  function useClassNames() {
+    const context = useContext(ClassNamesContext);
+    if (context === null) {
+      throw new Error(
+        "useClassNames must be used within a ClassNamesProvider. Did you forget to wrap your component in a ClassNamesProvider?",
+      );
+    }
+
+    return context;
+  }
+
+  function useProps() {
+    return useContext(PropsContext);
+  }
+
+  const withRootProvider = <P,>(
+    Component: ElementType<any>,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ): ForwardRefExoticComponent<PropsWithoutRef<P>> => {
+    assertNotIntrinsicComponent(Component, "withRootProvider");
+    const { defaultProps } = options ?? {};
+
+    const StyledComponent = (innerProps: any) => {
+      const props = { ...(defaultProps ?? {}), ...useProps(), ...innerProps } as Props &
+        Record<string, unknown>;
+      const [variantProps, otherProps] = recipe.splitVariantProps(props);
+      const classNames = recipe(variantProps);
+
+      return (
+        <ClassNamesProvider value={classNames}>
+          <PropsProvider value={variantProps}>
+            <Component {...otherProps} />
+          </PropsProvider>
+        </ClassNamesProvider>
+      );
+    };
+
+    // @ts-expect-error — assigning displayName to a plain function component
+    StyledComponent.displayName = Component.displayName || Component.name;
+
+    return StyledComponent as any;
+  };
+
+  const withProvider = <T, P>(
+    Component: ElementType<any>,
+    slot: keyof Classnames,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>> => {
+    assertNotIntrinsicComponent(Component, "withProvider");
+    const { defaultProps } = options ?? {};
+
+    const StyledComponent = forwardRef<any, any>((innerProps, ref) => {
+      const props: any = { ...(defaultProps ?? {}), ...useProps(), ...innerProps };
+      const [variantProps, otherProps] = recipe.splitVariantProps(props as Props);
+      const classNames = recipe(variantProps);
+      const slotClassName: string | undefined = classNames[slot];
+      const userClassName: string | undefined = props["className"];
+
+      return (
+        <ClassNamesProvider value={classNames}>
+          <PropsProvider value={variantProps}>
+            <Component
+              {...(ref ? { ref } : {})}
+              {...otherProps}
+              className={clsx(slotClassName, userClassName)}
+            />
+          </PropsProvider>
+        </ClassNamesProvider>
+      );
+    });
+
+    StyledComponent.displayName = (Component as any).displayName || (Component as any).name;
+
+    return StyledComponent as any;
+  };
+
+  const withContext = <T, P>(
+    Component: ElementType<any>,
+    slot?: keyof Classnames,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>> => {
+    assertNotIntrinsicComponent(Component, "withContext");
+    const { defaultProps } = options ?? {};
+
+    const StyledComponent = forwardRef<any, any>((innerProps, ref) => {
+      const props: any = { ...(defaultProps ?? {}), ...innerProps };
+      const classNames = useClassNames();
+      const slotClassName: string | undefined = slot ? classNames[slot] : undefined;
+      const userClassName: string | undefined = props["className"];
+
+      return (
+        <Component
+          {...(ref ? { ref } : {})}
+          {...props}
+          className={clsx(slotClassName, userClassName)}
+        />
+      );
+    });
+
+    StyledComponent.displayName = (Component as any).displayName || (Component as any).name;
+    return StyledComponent as any;
+  };
+
+  return {
+    ClassNamesProvider,
+    PropsProvider,
+    useClassNames,
+    useProps,
+    withRootProvider,
+    withProvider,
+    withContext,
+  };
+}

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

@@ -0,0 +1,47 @@
+// Lynx 런타임 전역 변수 타입 선언
+// 실제 런타임에서는 Lynx 엔진이 제공하며, 빌드 시에는 @lynx-js/types가 정의함
+declare const lynx: {
+  __globalProps?: Record<string, unknown>;
+};
+
+export type ColorMode = "system" | "light-only" | "dark-only";
+
+export interface GetSeedClassNameOptions {
+  colorMode?: ColorMode;
+}
+
+/**
+ * Lynx 앱의 root `<page>` 요소에 적용할 SEED Design className을 반환한다.
+ *
+ * 테마(dark/light)를 자동 감지하여 렌더링 전에 올바른 CSS 변수가 적용되도록 한다.
+ *
+ * @example
+ * ```tsx
+ * import { getSeedClassName } from "@seed-design/lynx-react";
+ *
+ * root.render(
+ *   <page className={getSeedClassName({ colorMode: "system" })}>
+ *     <App />
+ *   </page>
+ * );
+ * ```
+ */
+export function getSeedClassName(options?: GetSeedClassNameOptions): string {
+  const { colorMode = "system" } = options ?? {};
+
+  // Theme — lynx.__globalProps.theme에서 시스템 테마 읽기
+  const systemTheme = lynx?.__globalProps?.["theme"] as string | undefined;
+  let themeClass: string;
+  if (colorMode === "light-only") {
+    themeClass = "seed-user-color-scheme-light";
+  } else if (colorMode === "dark-only") {
+    themeClass = "seed-user-color-scheme-dark";
+  } else {
+    themeClass =
+      systemTheme?.toLowerCase() === "dark"
+        ? "seed-user-color-scheme-dark"
+        : "seed-user-color-scheme-light";
+  }
+
+  return themeClass;
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./create-slot-recipe-context";
+export * from "./get-seed-class-name";
+export * from "./resolve-recipe-token";
+export * from "./split-multiple-variants-props";

package/src/utils/resolve-recipe-token.ts

@@ -0,0 +1,47 @@
+/**
+ * Rootage vars 객체에서 `path` 를 따라 token 값(주로 `"var(--seed-...)"` 스트링)을 꺼낸다.
+ *
+ * 쓰임새: Lynx `<image>` 의 `tint-color` / `width` / `height` 처럼 CSS 만으로는
+ * override 할 수 없거나(아이콘 패키지가 inline style 을 박는 경우 등) React 가
+ * recipe 와 같은 소스에서 꺼내 inline attribute 로 주입해야 하는 속성을 다룰 때.
+ *
+ * ```ts
+ * import { actionButton as actionButtonVars } from "@seed-design/lynx-css/vars/component";
+ * import { capitalize, resolveRecipeToken } from "@seed-design/lynx-react/utils/resolve-recipe-token";
+ *
+ * // variant × state × slot → color
+ * const color = resolveRecipeToken(actionButtonVars, [
+ *   `variant${capitalize(variant)}`,
+ *   state,          // "enabled" | "disabled" | "loading" | "pressed"
+ *   "prefixIcon",
+ *   "color",
+ * ]);
+ *
+ * // size × layout → icon size
+ * const size = resolveRecipeToken(actionButtonVars, [
+ *   `size${capitalize(size)}Layout${capitalize(layout)}`,
+ *   "enabled",
+ *   "prefixIcon",
+ *   "size",
+ * ]);
+ * ```
+ *
+ * recipe token 경로가 컴포넌트마다 조금씩 다르므로(variant/size/layout 조합 여부 등)
+ * 이 유틸은 "vars + path" 조합만 제공하고, 각 컴포넌트가 자기 path 를 만들어 호출한다.
+ */
+export function resolveRecipeToken(vars: unknown, path: readonly string[]): string | undefined {
+  let cursor: unknown = vars;
+  for (const key of path) {
+    if (cursor == null || typeof cursor !== "object") return undefined;
+    cursor = (cursor as Record<string, unknown>)[key];
+  }
+  return typeof cursor === "string" ? cursor : undefined;
+}
+
+/**
+ * 첫 글자 대문자. recipe variant key 조립용
+ * (e.g. `variant` + `brandSolid` → `variantBrandSolid`).
+ */
+export function capitalize<T extends string>(value: T): Capitalize<T> {
+  return (value.charAt(0).toUpperCase() + value.slice(1)) as Capitalize<T>;
+}

package/src/utils/split-multiple-variants-props.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { splitMultipleVariantsProps } from "./split-multiple-variants-props";
+
+function makeRecipe<V extends Record<string, unknown>>(variantKeys: (keyof V)[]) {
+  return {
+    splitVariantProps: (props: Record<string, unknown>) => {
+      const variantProps: Record<string, unknown> = {};
+      const rest: Record<string, unknown> = {};
+      for (const key in props) {
+        if (variantKeys.includes(key as keyof V)) {
+          variantProps[key] = props[key];
+        } else {
+          rest[key] = props[key];
+        }
+      }
+      return [variantProps, rest] as [V, Omit<Record<string, unknown>, keyof V>];
+    },
+  };
+}
+
+describe("splitMultipleVariantsProps", () => {
+  it("splits props across disjoint recipes", () => {
+    const a = makeRecipe<{ size: string }>(["size"]);
+    const b = makeRecipe<{ tone: string }>(["tone"]);
+
+    const [{ a: av, b: bv }, rest] = splitMultipleVariantsProps(
+      { size: "32", tone: "brand", onTap: () => {}, children: "x" },
+      { a, b },
+    );
+
+    expect(av).toEqual({ size: "32" });
+    expect(bv).toEqual({ tone: "brand" });
+    expect(rest).toEqual({ onTap: expect.any(Function), children: "x" });
+  });
+
+  it("puts shared variant keys into every recipe bucket", () => {
+    const a = makeRecipe<{ size: string }>(["size"]);
+    const b = makeRecipe<{ size: string; tone: string }>(["size", "tone"]);
+
+    const [{ a: av, b: bv }, rest] = splitMultipleVariantsProps(
+      { size: "32", tone: "brand", disabled: true },
+      { a, b },
+    );
+
+    expect(av).toEqual({ size: "32" });
+    expect(bv).toEqual({ size: "32", tone: "brand" });
+    expect(rest).toEqual({ disabled: true });
+  });
+
+  it("returns empty variant buckets when no recipe claims a prop", () => {
+    const a = makeRecipe<{ size: string }>(["size"]);
+
+    const [{ a: av }, rest] = splitMultipleVariantsProps(
+      { onTap: () => {}, className: "x" },
+      { a },
+    );
+
+    expect(av).toEqual({});
+    expect(rest).toEqual({ onTap: expect.any(Function), className: "x" });
+  });
+});