@seed-design/lynx-react 0.1.0

package/src/components/TagGroup/TagGroup.tsx

@@ -0,0 +1,127 @@
+import * as React from "@lynx-js/react";
+import clsx from "clsx";
+import { tagGroup, type TagGroupVariantProps } from "@seed-design/lynx-css/recipes/tag-group";
+import {
+  tagGroupItem,
+  type TagGroupItemVariantProps,
+} from "@seed-design/lynx-css/recipes/tag-group-item";
+
+import type { LynxStyledElementProps, LynxTextRef, LynxViewRef } from "../../types";
+import { toArray } from "../../utils/children";
+import { createSlotRecipeContext } from "../../utils/create-slot-recipe-context";
+import { splitMultipleVariantsProps } from "../../utils/split-multiple-variants-props";
+import { useStyleProps, type StyleProps } from "../../utils/styled";
+
+const { PropsProvider, useProps, ClassNamesProvider, useClassNames } =
+  createSlotRecipeContext(tagGroupItem);
+
+////////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @platform Lynx
+ *
+ * 웹 대비 미지원 기능:
+ * - `truncate` prop: Lynx flex 모델에서는 item 단위 wrap만 가능해 웹 수준의
+ *   "한 줄 유지 + label ellipsis" 조합을 재현할 수 없음
+ * - `asChild` prop: Lynx Slot 미지원
+ * - 아이콘 slot: Lynx 3.7 SVG 지원 후 검토 (Tier B)
+ */
+export interface TagGroupRootProps
+  extends TagGroupVariantProps,
+    TagGroupItemVariantProps,
+    LynxStyledElementProps {
+  /**
+   * children 사이에 삽입되는 구분자. 기본값 `" · "`.
+   */
+  separator?: React.ReactNode;
+}
+
+export const TagGroupRoot = React.forwardRef<unknown, TagGroupRootProps>((props, ref) => {
+  const [{ tagGroup: tagGroupVariantProps, tagGroupItem: tagGroupItemVariantProps }, otherProps] =
+    splitMultipleVariantsProps(props, { tagGroup, tagGroupItem });
+  const { children, className, separator = " · ", ...nativeProps } = otherProps;
+  const classes = tagGroup(tagGroupVariantProps);
+
+  const visibleChildren = toArray(children);
+
+  return (
+    <PropsProvider value={tagGroupItemVariantProps}>
+      <view
+        {...(ref ? { ref: ref as LynxViewRef } : {})}
+        className={clsx(classes.root, className)}
+        {...nativeProps}
+      >
+        {visibleChildren.map((child, index) => {
+          if (index === 0) return child;
+          // Lynx <text> separator는 개별 flex item이라 wrap이 발동하면 separator가
+          // 이전 row 끝에 남는다. separator와 뒤따르는 item을 하나의 flex-row wrapper로
+          // 묶어 같은 wrap 단위로 함께 이동시킨다.
+          return (
+            <view
+              key={(child as React.ReactElement).key ?? index}
+              className={classes.separatorWrapper}
+            >
+              <text className={classes.separator}>{separator}</text>
+              {child}
+            </view>
+          );
+        })}
+      </view>
+    </PropsProvider>
+  );
+});
+TagGroupRoot.displayName = "TagGroupRoot";
+
+////////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @platform Lynx
+ *
+ * 웹 대비 미지원 기능:
+ * - `asChild` prop: Lynx Slot 미지원
+ */
+export interface TagGroupItemProps
+  extends TagGroupItemVariantProps,
+    Pick<StyleProps, "flexShrink">,
+    LynxStyledElementProps {}
+
+export const TagGroupItem = React.forwardRef<unknown, TagGroupItemProps>((props, ref) => {
+  const parentVariantProps = useProps();
+  const [localVariantProps, otherProps] = tagGroupItem.splitVariantProps(props);
+  const classes = tagGroupItem({ ...parentVariantProps, ...localVariantProps });
+  const { style, restProps } = useStyleProps(otherProps);
+  const { children, className, ...nativeProps } = restProps;
+
+  return (
+    <ClassNamesProvider value={classes}>
+      <view
+        {...(ref ? { ref: ref as LynxViewRef } : {})}
+        className={clsx(classes.root, className)}
+        style={style}
+        {...nativeProps}
+      >
+        {children}
+      </view>
+    </ClassNamesProvider>
+  );
+});
+TagGroupItem.displayName = "TagGroupItem";
+
+////////////////////////////////////////////////////////////////////////////////////
+
+export interface TagGroupItemLabelProps extends LynxStyledElementProps {}
+
+export const TagGroupItemLabel = React.forwardRef<unknown, TagGroupItemLabelProps>((props, ref) => {
+  const classes = useClassNames();
+  const { children, className, ...nativeProps } = props;
+  return (
+    <text
+      {...(ref ? { ref: ref as LynxTextRef } : {})}
+      className={clsx(classes.label, className)}
+      {...nativeProps}
+    >
+      {children}
+    </text>
+  );
+});
+TagGroupItemLabel.displayName = "TagGroupItemLabel";

package/src/components/TagGroup/index.ts

@@ -0,0 +1,10 @@
+export {
+  TagGroupRoot,
+  TagGroupItem,
+  TagGroupItemLabel,
+  type TagGroupRootProps,
+  type TagGroupItemProps,
+  type TagGroupItemLabelProps,
+} from "./TagGroup";
+
+export * as TagGroup from "./TagGroup.namespace";

package/src/components/Text/Text.tsx

@@ -0,0 +1,64 @@
+import { typography } from "@seed-design/lynx-css/vars/component";
+import type { CSSProperties } from "@lynx-js/types";
+import clsx from "clsx";
+import * as React from "@lynx-js/react";
+
+import {
+  handleColor,
+  handleFontSize,
+  handleFontWeight,
+  handleLineHeight,
+  type TextStyle,
+  type TextStyleProps,
+} from "../../utils/styled";
+import type { LynxStyledElementProps, LynxTextRef } from "../../types";
+
+function capitalize<T extends string>(value: T): Capitalize<T> {
+  return (value.charAt(0).toUpperCase() + value.slice(1)) as Capitalize<T>;
+}
+
+function getTypographyStyle(textStyle: TextStyle | undefined) {
+  const key = `textStyle${capitalize(textStyle ?? "t5Regular")}`;
+  const value = typography[key as keyof typeof typography];
+  return value.enabled.root;
+}
+
+export interface TextProps extends TextStyleProps, LynxStyledElementProps {}
+
+export const Text = React.forwardRef<unknown, TextProps>((props, ref) => {
+  const {
+    color,
+    textStyle,
+    fontSize,
+    lineHeight,
+    fontWeight,
+    align,
+    children,
+    className,
+    style,
+    ...nativeProps
+  } = props;
+  const typographyStyle = getTypographyStyle(textStyle);
+
+  return (
+    <text
+      {...(ref ? { ref: ref as LynxTextRef } : {})}
+      {...nativeProps}
+      className={clsx(className)}
+      style={
+        {
+          color: handleColor(color),
+          fontSize: handleFontSize(fontSize) ?? typographyStyle.fontSize,
+          lineHeight: handleLineHeight(lineHeight ?? fontSize) ?? typographyStyle.lineHeight,
+          fontWeight: handleFontWeight(fontWeight) ?? typographyStyle.fontWeight,
+          textAlign: align,
+          ...style,
+        } as CSSProperties
+      }
+    >
+      {children}
+    </text>
+  );
+});
+
+Text.displayName = "Text";

package/src/components/Text/index.ts

@@ -0,0 +1 @@
+export { Text, type TextProps } from "./Text";

package/src/components/index.ts

@@ -0,0 +1,11 @@
+export * from "./ActionButton";
+export * from "./Box";
+export * from "./BottomSheet";
+export * from "./Checkbox";
+export * from "./Icon";
+export * from "./ProgressCircle";
+export * from "./RadioGroup";
+export * from "./Stack";
+export * from "./Switch";
+export * from "./TagGroup";
+export * from "./Text";

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export * from "./useControllableState";
+export * from "./useIconColor";
+export * from "./usePressTap";
+export * from "./useSafeArea";

package/src/hooks/useControllableState.test.ts

@@ -0,0 +1,120 @@
+import { act, renderHook } from "@lynx-js/react/testing-library";
+import { describe, expect, it, vi } from "vitest";
+import { useControllableState } from "./useControllableState";
+
+describe("useControllableState", () => {
+  describe("uncontrolled mode", () => {
+    it("initializes with defaultValue", () => {
+      const { result } = renderHook(() => useControllableState({ defaultValue: "initial" }));
+
+      expect(result.current[0]).toBe("initial");
+    });
+
+    it("updates value on setValue", () => {
+      const { result } = renderHook(() => useControllableState({ defaultValue: 0 }));
+
+      act(() => {
+        result.current[1](42);
+      });
+
+      expect(result.current[0]).toBe(42);
+    });
+
+    it("calls onChange when value changes", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useControllableState({ defaultValue: "a", onChange }));
+
+      act(() => {
+        result.current[1]("b");
+      });
+
+      expect(onChange).toHaveBeenCalledWith("b");
+      expect(onChange).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not call onChange when value is unchanged", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useControllableState({ defaultValue: "a", onChange }));
+
+      act(() => {
+        result.current[1]("a");
+      });
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("calls onChange only once per unique value", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useControllableState({ defaultValue: 0, onChange }));
+
+      act(() => {
+        result.current[1](1);
+      });
+      act(() => {
+        result.current[1](1);
+      });
+      act(() => {
+        result.current[1](2);
+      });
+
+      expect(onChange).toHaveBeenCalledTimes(2);
+      expect(onChange).toHaveBeenNthCalledWith(1, 1);
+      expect(onChange).toHaveBeenNthCalledWith(2, 2);
+    });
+  });
+
+  describe("controlled mode", () => {
+    it("uses the provided value", () => {
+      const { result } = renderHook(() =>
+        useControllableState({ value: "external", defaultValue: "default" }),
+      );
+
+      expect(result.current[0]).toBe("external");
+    });
+
+    it("calls onChange on setValue but does not update internal state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() =>
+        useControllableState({
+          value: "controlled",
+          defaultValue: "default",
+          onChange,
+        }),
+      );
+
+      act(() => {
+        result.current[1]("next");
+      });
+
+      expect(onChange).toHaveBeenCalledWith("next");
+      expect(result.current[0]).toBe("controlled");
+    });
+
+    it("reflects external value changes on rerender", () => {
+      const { result, rerender } = renderHook(
+        (props: { value: string }) =>
+          useControllableState({
+            value: props.value,
+            defaultValue: "default",
+          }),
+        { initialProps: { value: "first" } },
+      );
+
+      expect(result.current[0]).toBe("first");
+
+      rerender({ value: "second" });
+
+      expect(result.current[0]).toBe("second");
+    });
+  });
+
+  it("returns a stable setValue reference", () => {
+    const { result, rerender } = renderHook(() => useControllableState({ defaultValue: 0 }));
+
+    const setValueFirst = result.current[1];
+    rerender();
+    const setValueSecond = result.current[1];
+
+    expect(setValueFirst).toBe(setValueSecond);
+  });
+});

package/src/hooks/useControllableState.ts

@@ -0,0 +1,38 @@
+import { useRef, useState } from "@lynx-js/react";
+import { useMemoizedFn } from "@lynx-js/lynx-ui-common";
+
+export interface UseControllableStateProps<T> {
+  value?: T;
+  defaultValue: T;
+  onChange?: (value: T) => void;
+}
+
+/**
+ * Controlled/uncontrolled state pattern for Lynx components.
+ *
+ * - When `value` is provided, the component is controlled.
+ * - When `value` is `undefined`, the component manages its own state
+ *   starting from `defaultValue`.
+ * - `onChange` fires in both modes.
+ */
+export function useControllableState<T>(
+  props: UseControllableStateProps<T>,
+): [T, (value: T) => void] {
+  const { value, defaultValue, onChange } = props;
+  const isControlled = value !== undefined;
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+  const currentValue = isControlled ? value : uncontrolledValue;
+  const prevValueRef = useRef(currentValue);
+
+  const setValue = useMemoizedFn((nextValue: T) => {
+    if (!isControlled) {
+      setUncontrolledValue(nextValue);
+    }
+    if (nextValue !== prevValueRef.current) {
+      onChange?.(nextValue);
+      prevValueRef.current = nextValue;
+    }
+  });
+
+  return [currentValue, setValue];
+}

package/src/hooks/useIconColor.test.ts

@@ -0,0 +1,13 @@
+import { renderHook } from "@lynx-js/react/testing-library";
+import { describe, expect, it } from "vitest";
+
+import { useIconColor } from "./useIconColor";
+
+describe("useIconColor", () => {
+  it("returns icon tint sync props", () => {
+    const { result } = renderHook(() => useIconColor([]));
+
+    expect(result.current).toHaveProperty("ref");
+    expect(result.current["main-thread:binduiappear"]).toBeDefined();
+  });
+});

package/src/hooks/useIconColor.ts

@@ -0,0 +1,67 @@
+import { runOnMainThread, useEffect, useMainThreadRef } from "@lynx-js/react";
+import type { MainThread } from "@lynx-js/types";
+import type { DependencyList, RefObject } from "@lynx-js/react";
+
+type IconElement = MainThread.Element & {
+  getComputedStyleProperty?: (name: string) => string;
+  getComputedCssProperty?: (name: string) => string;
+};
+
+export interface UseIconColorOptions {
+  sourceRef?: RefObject<MainThread.Element>;
+}
+
+// Lynx `<image>` 의 `tint-color` attribute 에 CSS variable 문자열을 직접 넣는 경로는
+// 안정적으로 동작하지 않는다. CSS `color` 는 computed style 로 resolved color 를 읽을 수
+// 있으므로 main-thread 에서 한 번 읽어 `tint-color` 로 mirror 한다.
+function syncTintColor(targetRef: RefObject<IconElement>, sourceRef?: RefObject<IconElement>) {
+  "main thread";
+
+  const target = targetRef.current;
+  if (!target) return;
+
+  const source = sourceRef?.current ?? target;
+
+  let color: string | undefined;
+  if (typeof source.getComputedStyleProperty === "function") {
+    color = source.getComputedStyleProperty("color");
+  } else if (typeof source.getComputedCssProperty === "function") {
+    color = source.getComputedCssProperty("color");
+  }
+
+  if (color) {
+    target.setAttribute("tint-color", color);
+  }
+}
+
+/**
+ * Lynx `<image>` 의 tint color 를 recipe 의 CSS `color` 로부터 main-thread 에서 읽어
+ * `tint-color` attribute 로 mirror. `deps` 가 바뀌면 재동기화.
+ *
+ * ```tsx
+ * const iconColorProps = useIconColor([variant, disabled, loading]);
+ * return cloneElement(iconChild, iconColorProps);
+ * ```
+ */
+export function useIconColor(
+  deps: DependencyList,
+  options?: UseIconColorOptions,
+): {
+  ref: RefObject<MainThread.Element>;
+  "main-thread:binduiappear": () => void;
+} {
+  const ref = useMainThreadRef<IconElement>(null);
+  const sourceRef = options?.sourceRef as RefObject<IconElement> | undefined;
+
+  function syncOnUiAppear() {
+    "main thread";
+    syncTintColor(ref, sourceRef);
+  }
+
+  // deps 는 caller 가 책임.
+  useEffect(() => {
+    runOnMainThread(syncTintColor)(ref, sourceRef);
+  }, deps);
+
+  return { ref, "main-thread:binduiappear": syncOnUiAppear };
+}

package/src/hooks/usePressTap.test.ts

@@ -0,0 +1,129 @@
+import { act, renderHook } from "@lynx-js/react/testing-library";
+import { describe, expect, it, vi } from "vitest";
+import { usePressTap } from "./usePressTap";
+
+const fakeEvent = {} as Parameters<ReturnType<typeof usePressTap>["bindtap"]>[0];
+
+describe("usePressTap", () => {
+  describe("pressed state", () => {
+    it("starts as false", () => {
+      const { result } = renderHook(() => usePressTap());
+      expect(result.current.pressed).toBe(false);
+    });
+
+    it("becomes true on bindtouchstart", () => {
+      const { result } = renderHook(() => usePressTap());
+
+      act(() => {
+        result.current.bindtouchstart(fakeEvent);
+      });
+
+      expect(result.current.pressed).toBe(true);
+    });
+
+    it("becomes false on bindtouchend", () => {
+      const { result } = renderHook(() => usePressTap());
+
+      act(() => {
+        result.current.bindtouchstart(fakeEvent);
+      });
+      act(() => {
+        result.current.bindtouchend(fakeEvent);
+      });
+
+      expect(result.current.pressed).toBe(false);
+    });
+
+    it("becomes false on bindtouchcancel", () => {
+      const { result } = renderHook(() => usePressTap());
+
+      act(() => {
+        result.current.bindtouchstart(fakeEvent);
+      });
+      act(() => {
+        result.current.bindtouchcancel(fakeEvent);
+      });
+
+      expect(result.current.pressed).toBe(false);
+    });
+  });
+
+  describe("onTap", () => {
+    it("is called when bindtap fires", () => {
+      const onTap = vi.fn();
+      const { result } = renderHook(() => usePressTap({ onTap }));
+
+      act(() => {
+        result.current.bindtap(fakeEvent);
+      });
+
+      expect(onTap).toHaveBeenCalledTimes(1);
+    });
+
+    it("can be omitted without error", () => {
+      const { result } = renderHook(() => usePressTap());
+
+      expect(() => {
+        act(() => {
+          result.current.bindtap(fakeEvent);
+        });
+      }).not.toThrow();
+    });
+  });
+
+  describe("disabled", () => {
+    it("does not update pressed on bindtouchstart", () => {
+      const { result } = renderHook(() => usePressTap({ disabled: true }));
+
+      act(() => {
+        result.current.bindtouchstart(fakeEvent);
+      });
+
+      expect(result.current.pressed).toBe(false);
+    });
+
+    it("does not call onTap on bindtap", () => {
+      const onTap = vi.fn();
+      const { result } = renderHook(() => usePressTap({ disabled: true, onTap }));
+
+      act(() => {
+        result.current.bindtap(fakeEvent);
+      });
+
+      expect(onTap).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("main-thread:bindtap", () => {
+    it("is included when enabled and mainThreadOnTap is provided", () => {
+      const mainThreadOnTap = () => {};
+      const { result } = renderHook(() => usePressTap({ mainThreadOnTap }));
+
+      expect(result.current["main-thread:bindtap"]).toBe(mainThreadOnTap);
+    });
+
+    it("is not included when mainThreadOnTap is omitted", () => {
+      const { result } = renderHook(() => usePressTap());
+
+      expect(result.current).not.toHaveProperty("main-thread:bindtap");
+    });
+
+    it("is not included when disabled is true", () => {
+      const mainThreadOnTap = () => {};
+      const { result } = renderHook(() => usePressTap({ disabled: true, mainThreadOnTap }));
+
+      expect(result.current).not.toHaveProperty("main-thread:bindtap");
+    });
+  });
+
+  it("returns stable handler references across renders", () => {
+    const { result, rerender } = renderHook(() => usePressTap());
+
+    const firstBindtap = result.current.bindtap;
+    const firstBindtouchstart = result.current.bindtouchstart;
+    rerender();
+
+    expect(result.current.bindtap).toBe(firstBindtap);
+    expect(result.current.bindtouchstart).toBe(firstBindtouchstart);
+  });
+});

package/src/hooks/usePressTap.ts

@@ -0,0 +1,58 @@
+import { useState } from "@lynx-js/react";
+import { useMemoizedFn } from "@lynx-js/lynx-ui-common";
+import type { BaseTouchEvent, EventHandler, Target } from "@lynx-js/types";
+
+import type { LynxTouchProps } from "../types";
+
+type TouchHandler = EventHandler<BaseTouchEvent<Target>>;
+
+export interface UsePressTapOptions {
+  disabled?: boolean;
+  onTap?: TouchHandler;
+  mainThreadOnTap?: LynxTouchProps["main-thread:bindtap"];
+}
+
+export interface UsePressTapReturn {
+  pressed: boolean;
+  bindtap: TouchHandler;
+  bindtouchstart: TouchHandler;
+  bindtouchend: TouchHandler;
+  bindtouchcancel: TouchHandler;
+  "main-thread:bindtap"?: LynxTouchProps["main-thread:bindtap"];
+}
+
+/**
+ * Hook that provides press/tap interaction state for Lynx elements.
+ *
+ * - Tracks `pressed` state via touch events.
+ * - When `disabled` is true, the element cannot become active and no tap fires.
+ * - If the element becomes disabled during a press, the active state is cleared.
+ * - `main-thread:bindtap` is conditionally included (only when enabled and provided).
+ */
+export function usePressTap(options: UsePressTapOptions = {}): UsePressTapReturn {
+  const { disabled = false, onTap, mainThreadOnTap } = options;
+  const [pressed, setPressed] = useState(false);
+
+  const press = useMemoizedFn(() => {
+    if (disabled) return;
+    setPressed(true);
+  });
+
+  const reset = useMemoizedFn(() => {
+    setPressed(false);
+  });
+
+  const handleTap = useMemoizedFn((...args: Parameters<TouchHandler>) => {
+    if (disabled) return;
+    onTap?.(...args);
+  });
+
+  return {
+    pressed,
+    bindtap: handleTap,
+    bindtouchstart: press,
+    bindtouchend: reset,
+    bindtouchcancel: reset,
+    ...(!disabled && mainThreadOnTap ? { "main-thread:bindtap": mainThreadOnTap } : {}),
+  };
+}