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

package/src/components/TagGroup/TagGroup.tsx

@@ -0,0 +1,125 @@
+import * as React from "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 { createSlotRecipeContext } from "../../utils/create-slot-recipe-context";
+import { splitMultipleVariantsProps } from "../../utils/split-multiple-variants-props";
+
+const { PropsProvider, useProps, ClassNamesProvider, useClassNames } =
+  createSlotRecipeContext(tagGroupItem);
+
+/**
+ * @platform Lynx
+ *
+ * 웹 대비 미지원 기능:
+ * - `truncate` prop: Lynx flex 모델에서는 item 단위 wrap만 가능해 웹 수준의
+ *   "한 줄 유지 + label ellipsis" 조합을 재현할 수 없음
+ * - `asChild` prop: Lynx Slot 미지원
+ * - `flexShrink` prop: CSS variable 동적 주입 제한
+ * - 아이콘 slot: Lynx 3.7 SVG 지원 후 검토 (Tier B)
+ */
+export interface TagGroupRootProps extends TagGroupVariantProps, TagGroupItemVariantProps {
+  children?: React.ReactNode;
+  className?: string;
+  /**
+   * 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 = React.Children.toArray(children);
+
+  return (
+    <PropsProvider value={tagGroupItemVariantProps}>
+      <view
+        {...(ref ? { ref: ref as React.Ref<SVGViewElement> } : {})}
+        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}
+              style={{
+                display: "flex",
+                flexDirection: "row",
+                alignItems: "center",
+                flexShrink: 0,
+              }}
+            >
+              <text className={classes.separator}>{separator}</text>
+              {child}
+            </view>
+          );
+        })}
+      </view>
+    </PropsProvider>
+  );
+});
+TagGroupRoot.displayName = "TagGroupRoot";
+
+/**
+ * @platform Lynx
+ *
+ * 웹 대비 미지원 기능:
+ * - `asChild` prop: Lynx Slot 미지원
+ * - `flexShrink` prop: CSS variable 동적 주입 제한
+ */
+export interface TagGroupItemProps extends TagGroupItemVariantProps {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+export const TagGroupItem = React.forwardRef<unknown, TagGroupItemProps>((props, ref) => {
+  const parentVariantProps = useProps();
+  const [localVariantProps, otherProps] = tagGroupItem.splitVariantProps(props);
+  const classes = tagGroupItem({ ...parentVariantProps, ...localVariantProps });
+  const { children, className, ...nativeProps } = otherProps;
+
+  return (
+    <ClassNamesProvider value={classes}>
+      <view
+        {...(ref ? { ref: ref as React.Ref<SVGViewElement> } : {})}
+        className={clsx(classes.root, className)}
+        {...nativeProps}
+      >
+        {children}
+      </view>
+    </ClassNamesProvider>
+  );
+});
+TagGroupItem.displayName = "TagGroupItem";
+
+export interface TagGroupItemLabelProps {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+export const TagGroupItemLabel = React.forwardRef<unknown, TagGroupItemLabelProps>((props, ref) => {
+  const classes = useClassNames();
+  const { children, className, ...nativeProps } = props;
+  return (
+    <text
+      {...(ref ? { ref: ref as React.Ref<SVGTextElement> } : {})}
+      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/__tests__/ProgressCircle.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const progressCircleSource = readFileSync(
+  join(currentDir, "..", "ProgressCircle", "ProgressCircle.tsx"),
+  "utf8",
+);
+
+function readEffectDependencies(marker: string): string {
+  const markerIndex = progressCircleSource.indexOf(marker);
+  expect(markerIndex).toBeGreaterThanOrEqual(0);
+
+  const dependencyStart = progressCircleSource.indexOf("}, [", markerIndex);
+  expect(dependencyStart).toBeGreaterThanOrEqual(0);
+
+  const dependencyEnd = progressCircleSource.indexOf("]);", dependencyStart);
+  expect(dependencyEnd).toBeGreaterThanOrEqual(0);
+
+  return progressCircleSource.slice(dependencyStart, dependencyEnd);
+}
+
+describe("ProgressCircle", () => {
+  it("restarts indeterminate animation when size changes", () => {
+    expect(readEffectDependencies("runOnMainThread(startLoop)")).toContain("numSize");
+  });
+
+  it("restarts determinate transition when size changes", () => {
+    expect(readEffectDependencies("runOnMainThread(startAnimation)")).toContain("numSize");
+  });
+});

package/src/components/__tests__/exports.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const componentsDir = join(currentDir, "..");
+
+function readComponentFile(componentName: string, fileName: string): string {
+  return readFileSync(join(componentsDir, componentName, fileName), "utf8");
+}
+
+describe("components public exports", () => {
+  it("exposes compound components through namespace exports", () => {
+    for (const componentName of ["Switch", "Checkbox", "RadioGroup", "TagGroup"]) {
+      expect(readComponentFile(componentName, "index.ts")).toContain(
+        `export * as ${componentName} from "./${componentName}.namespace";`,
+      );
+      expect(readComponentFile(componentName, `${componentName}.namespace.ts`)).toContain(
+        " as Root",
+      );
+    }
+  });
+
+  it("keeps ProgressCircle namespace usage while exposing flat slots", () => {
+    const index = readComponentFile("ProgressCircle", "index.ts");
+    const implementation = readComponentFile("ProgressCircle", "ProgressCircle.tsx");
+    const namespace = readComponentFile("ProgressCircle", "ProgressCircle.namespace.ts");
+
+    expect(index).toContain('export * as ProgressCircle from "./ProgressCircle.namespace";');
+    expect(index).toContain("ProgressCircleRoot");
+    expect(index).toContain("ProgressCircleRange");
+    expect(namespace).toContain("ProgressCircleRoot as Root");
+    expect(namespace).toContain("ProgressCircleRange as Range");
+    expect(implementation).toContain("export const ProgressCircleRoot");
+    expect(implementation).toContain("export const ProgressCircleRange");
+  });
+});

package/src/components/__tests__/switch.test.ts

@@ -0,0 +1,34 @@
+import { switchmark } from "@seed-design/lynx-css/recipes/switchmark";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const lynxCssRecipesDir = join(currentDir, "..", "..", "..", "..", "lynx-css", "recipes");
+const switchCss = readFileSync(join(lynxCssRecipesDir, "switch.css"), "utf8");
+const switchmarkCss = readFileSync(join(lynxCssRecipesDir, "switchmark.css"), "utf8");
+
+describe("Switch", () => {
+  it.each(["16", "24", "32"] as const)(
+    "includes selected thumb class for size %s",
+    (size) => {
+      const classNames = switchmark({
+        tone: "brand",
+        size,
+        checked: true,
+        disabled: false,
+      });
+
+      expect(classNames.thumb.split(" ")).toContain(
+        `seed-switchmark__thumb--size_${size}-checked_true`,
+      );
+    },
+  );
+
+  it("aligns Lynx switch content with flex center instead of margin compensation", () => {
+    expect(switchCss).toContain("align-items: center");
+    expect(switchCss).not.toContain("--switchmark-margin-top");
+    expect(switchmarkCss).not.toContain("--switchmark-margin-top");
+  });
+});

package/src/components/index.ts

@@ -0,0 +1,7 @@
+export * from "./ActionButton";
+export * from "./BottomSheet";
+export * from "./Checkbox";
+export * from "./ProgressCircle";
+export * from "./RadioGroup";
+export * from "./Switch";
+export * from "./TagGroup";

package/src/hooks/__tests__/use-controllable-state.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 "../use-controllable-state";
+
+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/__tests__/use-press-tap.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 "../use-press-tap";
+
+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/index.ts

@@ -0,0 +1,3 @@
+export * from "./use-controllable-state";
+export * from "./use-icon-color";
+export * from "./use-press-tap";

package/src/hooks/use-controllable-state.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/use-icon-color.ts

@@ -0,0 +1,51 @@
+import { runOnMainThread, useEffect, useMainThreadRef } from "@lynx-js/react";
+import type { MainThread } from "@lynx-js/types";
+import type { DependencyList, RefObject } from "react";
+
+type IconElement = MainThread.Element & {
+  getComputedStyleProperty?: (name: string) => string;
+  getComputedCssProperty?: (name: string) => string;
+};
+
+// Lynx `<image>` 의 `tint-color` attribute 는 concrete color(hex/rgb) 만 받는다. CSS
+// `color: var(--seed-color-...)` 를 slot 에 걸면 `getComputedStyleProperty("color")` 가
+// resolved hex 를 돌려주므로 main-thread 에서 한번 읽어 `tint-color` 로 mirror 한다.
+function syncTintColor(ref: RefObject<IconElement>) {
+  "main thread";
+
+  const el = ref.current;
+  if (!el) return;
+
+  let color: string | undefined;
+  if (typeof el.getComputedStyleProperty === "function") {
+    color = el.getComputedStyleProperty("color");
+  } else if (typeof el.getComputedCssProperty === "function") {
+    color = el.getComputedCssProperty("color");
+  }
+
+  if (color) {
+    el.setAttribute("tint-color", color);
+  }
+}
+
+/**
+ * Lynx `<image>` 의 tint color 를 recipe 의 CSS `color` 로부터 main-thread 에서 읽어
+ * `tint-color` attribute 로 mirror. `deps` 가 바뀌면 재동기화.
+ *
+ * ```tsx
+ * const { ref } = useIconColor([variant, disabled, loading]);
+ * return cloneElement(iconChild, { ref });
+ * ```
+ */
+export function useIconColor(deps: DependencyList): {
+  ref: RefObject<MainThread.Element>;
+} {
+  const ref = useMainThreadRef<IconElement>(null);
+
+  // deps 는 caller 가 책임.
+  useEffect(() => {
+    runOnMainThread(syncTintColor)(ref);
+  }, deps);
+
+  return { ref };
+}

package/src/hooks/use-press-tap.ts

@@ -0,0 +1,54 @@
+import { useState } from "@lynx-js/react";
+import type { TouchEvent } from "@lynx-js/types";
+import { useMemoizedFn } from "@lynx-js/lynx-ui-common";
+
+export interface UsePressTapOptions {
+  disabled?: boolean;
+  onTap?: () => void;
+  mainThreadOnTap?: () => void;
+}
+
+export interface UsePressTapReturn {
+  pressed: boolean;
+  bindtap: (e: TouchEvent) => void;
+  bindtouchstart: (e: TouchEvent) => void;
+  bindtouchend: (e: TouchEvent) => void;
+  bindtouchcancel: (e: TouchEvent) => void;
+  "main-thread:bindtap"?: () => void;
+}
+
+/**
+ * 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(() => {
+    if (disabled) return;
+    onTap?.();
+  });
+
+  return {
+    pressed,
+    bindtap: handleTap,
+    bindtouchstart: press,
+    bindtouchend: reset,
+    bindtouchcancel: reset,
+    ...(!disabled && mainThreadOnTap ? { "main-thread:bindtap": mainThreadOnTap } : {}),
+  };
+}

package/src/index.ts

@@ -1,4 +1,3 @@
-export { ActionButton, type ActionButtonProps } from "./components/ActionButton";
-export { ProgressCircle, type ProgressCircleProps } from "./components/ProgressCircle";
-export { dynamicStyle } from "./utils/dynamic-style";
-export { getSeedClassName } from "./get-seed-class-name";
+export * from "./components";
+export * from "./hooks";
+export * from "./utils";