@seed-design/react 2.3.0 → 2.4.0

package/src/components/WheelPicker/WheelPicker.tsx

@@ -0,0 +1,210 @@
+"use client";
+
+import {
+  wheelPickerPublic,
+  type WheelPickerPublicVariantProps,
+} from "@seed-design/css/recipes/wheel-picker-public";
+import { Primitive, type PrimitiveProps } from "@seed-design/react-primitive";
+import {
+  WheelPicker as WheelPickerPrimitive,
+  type WheelPickerOption,
+} from "@seed-design/react-wheel-picker";
+import clsx from "clsx";
+import * as React from "react";
+import { createSlotRecipeContext } from "../../utils/createSlotRecipeContext";
+import { ScrollFog } from "../ScrollFog/ScrollFog";
+
+const DEFAULT_ITEM_SIZE = {
+  small: 36,
+  medium: 44,
+} as const;
+const DEFAULT_VISIBLE_ITEM_COUNT = 5;
+const { ClassNamesProvider, useClassNames } = createSlotRecipeContext(wheelPickerPublic);
+
+type WheelPickerCssProperties = React.CSSProperties & {
+  "--seed-wheel-picker-public-item-size"?: string;
+  "--seed-wheel-picker-public-visible-item-count"?: number;
+  "--seed-wheel-picker-public-viewport-size"?: string;
+  "--seed-wheel-picker-public-center-offset"?: string;
+  "--seed-wheel-picker-public-scroll-fog-max-height"?: string;
+};
+
+export interface WheelPickerRootProps
+  extends WheelPickerPublicVariantProps,
+    Omit<
+      WheelPickerPrimitive.RootProps,
+      "asChild" | "children" | "disabled" | "itemSize" | "readOnly" | "visibleItemCount"
+    > {
+  /** Wheel Picker를 구성하는 `WheelPicker.Column` 목록입니다. */
+  children: React.ReactNode;
+
+  /** 모든 컬럼의 포커스와 값 변경을 막습니다. */
+  disabled?: boolean;
+
+  /**
+   * 한 항목의 높이입니다. 지정하지 않으면 `size`의 기본 높이를 사용합니다.
+   */
+  itemSize?: number;
+
+  /**
+   * 화면에 보이는 항목 수입니다. 5 이상의 홀수를 권장합니다.
+   * @default 5
+   */
+  visibleItemCount?: number;
+}
+
+export const WheelPickerRoot = React.forwardRef<HTMLDivElement, WheelPickerRootProps>(
+  (props, ref) => {
+    const [variantProps, otherProps] = wheelPickerPublic.splitVariantProps(props);
+    const {
+      children,
+      className,
+      itemSize: itemSizeProp,
+      style,
+      visibleItemCount = DEFAULT_VISIBLE_ITEM_COUNT,
+      ...rootProps
+    } = otherProps;
+    const size = variantProps.size ?? "medium";
+    const itemSize = itemSizeProp ?? DEFAULT_ITEM_SIZE[size];
+    const centerOffset = ((visibleItemCount - 1) / 2) * itemSize;
+    const classNames = wheelPickerPublic({ size });
+    const wheelPickerStyle: WheelPickerCssProperties = {
+      ...style,
+      "--seed-wheel-picker-public-item-size": `${itemSize}px`,
+      "--seed-wheel-picker-public-visible-item-count": visibleItemCount,
+      "--seed-wheel-picker-public-viewport-size": `${itemSize * visibleItemCount}px`,
+      "--seed-wheel-picker-public-center-offset": `${centerOffset}px`,
+      "--seed-wheel-picker-public-scroll-fog-max-height": `${itemSize * 3}px`,
+    };
+
+    return (
+      <ClassNamesProvider value={classNames}>
+        <WheelPickerPrimitive.Root
+          ref={ref}
+          className={clsx(classNames.root, className)}
+          itemSize={itemSize}
+          style={wheelPickerStyle}
+          visibleItemCount={visibleItemCount}
+          {...rootProps}
+          readOnly={false}
+        >
+          <Primitive.div
+            aria-hidden
+            className={classNames.selectionIndicator}
+            data-wheel-picker-indicator=""
+          />
+          <ScrollFog
+            className={classNames.scrollFog}
+            placement={["top", "bottom"]}
+            size="var(--seed-wheel-picker-public-scroll-fog-size)"
+            hideScrollBar
+            data-wheel-picker-scroll-fog=""
+          >
+            <Primitive.div className={classNames.columns} data-wheel-picker-columns="">
+              {children}
+            </Primitive.div>
+          </ScrollFog>
+        </WheelPickerPrimitive.Root>
+      </ClassNamesProvider>
+    );
+  },
+);
+WheelPickerRoot.displayName = "WheelPickerRoot";
+
+export interface WheelPickerItemLabelProps
+  extends PrimitiveProps,
+    React.HTMLAttributes<HTMLDivElement> {}
+
+/** Wheel Picker 항목의 기본 여백과 타이포그래피를 적용합니다. */
+export const WheelPickerItemLabel = React.forwardRef<HTMLDivElement, WheelPickerItemLabelProps>(
+  ({ className, ...props }, ref) => {
+    const classNames = useClassNames();
+
+    return (
+      <Primitive.div
+        ref={ref}
+        className={clsx(classNames.itemLabel, className)}
+        {...props}
+        data-wheel-picker-item-label=""
+      />
+    );
+  },
+);
+WheelPickerItemLabel.displayName = "WheelPickerItemLabel";
+
+export interface WheelPickerColumnProps
+  extends Omit<
+    WheelPickerPrimitive.ColumnProps,
+    | "asChild"
+    | "defaultValue"
+    | "getAriaValueText"
+    | "loop"
+    | "onIndexChange"
+    | "onValueChange"
+    | "options"
+    | "renderOption"
+    | "value"
+    | "valueChangeBehavior"
+  > {
+  /** 컬럼에 표시할 선택 항목입니다. 하나 이상의 항목을 제공해야 합니다. */
+  options: readonly WheelPickerOption[];
+
+  /** 제어 상태에서 현재 선택된 항목의 값입니다. */
+  value?: string;
+
+  /** 비제어 상태에서 처음 선택할 항목의 값입니다. */
+  defaultValue?: string;
+
+  /** 선택 값이 바뀔 때 호출됩니다. */
+  onValueChange?: WheelPickerPrimitive.ColumnProps["onValueChange"];
+
+  /** 사용자 조작으로 중앙 항목이 바뀔 때마다 호출됩니다. */
+  onIndexChange?: WheelPickerPrimitive.ColumnProps["onIndexChange"];
+
+  /**
+   * 마지막 항목과 첫 항목을 이어 반복해서 탐색할지 여부입니다.
+   * @default false
+   */
+  loop?: boolean;
+
+  /**
+   * 외부에서 `value`가 변경되었을 때 새 값으로 이동하는 스크롤 방식입니다.
+   * @default "auto"
+   */
+  valueChangeBehavior?: ScrollBehavior;
+
+  /** 현재 값에 대응하는 접근성 텍스트를 반환합니다. */
+  getAriaValueText?: (value: string) => string;
+
+  /**
+   * 기본 `ItemLabel` 대신 항목에 표시할 요소를 반환합니다.
+   * 반환한 요소는 항목의 선택·비활성 색상을 적용할 수 있도록 `currentColor`를 상속해야 합니다.
+   */
+  renderLabel?: (option: WheelPickerOption) => React.ReactNode;
+}
+
+export const WheelPickerColumn = React.forwardRef<HTMLDivElement, WheelPickerColumnProps>(
+  ({ className, renderLabel, ...props }, ref) => {
+    const classNames = useClassNames();
+
+    return (
+      <WheelPickerPrimitive.Column
+        ref={ref}
+        className={clsx(classNames.column, className)}
+        {...props}
+        renderOption={(option, optionProps) => (
+          <Primitive.div className={classNames.item} {...optionProps}>
+            {renderLabel ? (
+              renderLabel(option)
+            ) : (
+              <WheelPickerItemLabel>{option.label}</WheelPickerItemLabel>
+            )}
+          </Primitive.div>
+        )}
+      />
+    );
+  },
+);
+WheelPickerColumn.displayName = "WheelPickerColumn";
+
+export type { WheelPickerOption };

package/src/components/WheelPicker/index.ts

@@ -0,0 +1,11 @@
+export {
+  WheelPickerRoot,
+  WheelPickerColumn,
+  WheelPickerItemLabel,
+  type WheelPickerRootProps,
+  type WheelPickerColumnProps,
+  type WheelPickerItemLabelProps,
+  type WheelPickerOption,
+} from "./WheelPicker";
+
+export * as WheelPicker from "./WheelPicker.namespace";

package/src/components/index.ts

@@ -84,3 +84,4 @@ export * from "./TextField";
 export * from "./TimePicker";
 export * from "./ToggleButton";
 export * from "./VisuallyHidden";
+export * from "./WheelPicker";

package/src/components/private/WheelPicker.test.tsx

@@ -49,6 +49,7 @@ describe("InternalWheelPicker", () => {
     expect(columns).toHaveClass("seed-wheel-picker__columns", "columns");
     expect(getAllByRole("spinbutton")).toHaveLength(2);
     expect(firstColumn).toHaveClass("seed-wheel-picker__column");
+    expect(firstColumn).not.toHaveClass("seed-wheel-picker-public__column");
     expect(firstColumn.firstElementChild).toHaveClass("seed-wheel-picker__item");
   });
 });

package/src/components/private/WheelPicker.tsx

@@ -2,7 +2,7 @@
 
 import { wheelPicker } from "@seed-design/css/recipes/wheel-picker";
 import { Primitive } from "@seed-design/react-primitive";
-import * as HeadlessWheelPicker from "@seed-design/react-wheel-picker";
+import { WheelPicker as WheelPickerPrimitive } from "@seed-design/react-wheel-picker";
 import clsx from "clsx";
 import * as React from "react";
 import { ScrollFog, type ScrollFogProps } from "../ScrollFog/ScrollFog";
@@ -17,7 +17,7 @@ type WheelPickerCssProperties = React.CSSProperties & {
 };
 
 export interface InternalWheelPickerRootProps
-  extends Omit<HeadlessWheelPicker.WheelPickerRootProps, "asChild" | "children"> {
+  extends Omit<WheelPickerPrimitive.RootProps, "asChild" | "children"> {
   children: React.ReactNode;
   columnsClassName?: string;
   scrollFogClassName?: string;
@@ -54,7 +54,7 @@ export const InternalWheelPickerRoot = React.forwardRef<
     };
 
     return (
-      <HeadlessWheelPicker.WheelPickerRoot
+      <WheelPickerPrimitive.Root
         ref={ref}
         itemSize={itemSize}
         visibleItemCount={visibleItemCount}
@@ -81,14 +81,14 @@ export const InternalWheelPickerRoot = React.forwardRef<
             {children}
           </Primitive.div>
         </ScrollFog>
-      </HeadlessWheelPicker.WheelPickerRoot>
+      </WheelPickerPrimitive.Root>
     );
   },
 );
 InternalWheelPickerRoot.displayName = "InternalWheelPickerRoot";
 
 export interface InternalWheelPickerColumnProps
-  extends Omit<HeadlessWheelPicker.WheelPickerColumnProps, "asChild" | "renderOption"> {
+  extends Omit<WheelPickerPrimitive.ColumnProps, "asChild" | "renderOption"> {
   itemClassName?: string;
 }
 
@@ -96,7 +96,7 @@ export const InternalWheelPickerColumn = React.forwardRef<
   HTMLDivElement,
   InternalWheelPickerColumnProps
 >(({ className, itemClassName, ...props }, ref) => (
-  <HeadlessWheelPicker.WheelPickerColumn
+  <WheelPickerPrimitive.Column
     ref={ref}
     className={clsx(classNames.column, className)}
     renderOption={(option, optionProps) => (

package/src/index.ts

@@ -5,6 +5,8 @@ export type { ResponsiveValue, UnwrapResponsive, BreakpointThreshold } from "./t
 export { useBreakpoint } from "./hooks/useBreakpoint";
 export type { UseBreakpointOptions } from "./hooks/useBreakpoint";
 export { useBreakpointValue } from "./hooks/useBreakpointValue";
+export { useScaleFeedback, ScaleFeedback } from "./utils/scaleFeedback";
+export type { ScaleFeedbackProps } from "./utils/scaleFeedback";
 export { BreakpointProvider } from "./providers/BreakpointProvider";
 export type { BreakpointProviderProps } from "./providers/BreakpointProvider";
 

package/src/utils/elementSizeVars.tsx

@@ -0,0 +1,112 @@
+import * as React from "react";
+
+/**
+ * Publishes an element's rendered size as CSS custom properties.
+ *
+ * The size is a plain fact about the element rather than a feature, so this
+ * util keeps unitless `--seed-element-width` / `--seed-element-height` in sync
+ * on the element and stops there. Whatever needs the size derives its own
+ * values from those vars in CSS.
+ *
+ * The names must stay in sync with `@seed-design/qvism-preset`
+ * (utils/scale-feedback.ts), which owns the formula that consumes them. Press
+ * detection stays in CSS (`:active` gates), so nothing here tracks interaction;
+ * without JS the vars are simply never set and consumers fall back to scale 1.
+ */
+
+// One observer for every measured element; created lazily so the module stays
+// importable during SSR.
+let sharedObserver: ResizeObserver | null = null;
+
+function getSharedObserver() {
+  sharedObserver ??= new ResizeObserver((entries) => {
+    // `borderBoxSize` is absent before Safari 15.4, inside the range SEED
+    // supports, so the `offsetWidth` / `offsetHeight` fallback is a live path
+    // rather than a formality. Reading every entry before writing any property
+    // is what keeps it free: layout is already clean when observations are
+    // broadcast, so the reads force nothing, while a write interleaved between
+    // them would dirty layout and make every later read reflow.
+    const measurements = entries.map((entry) => {
+      const element = entry.target as HTMLElement;
+      const size = entry.borderBoxSize?.[0];
+
+      return {
+        element,
+        width: size ? size.inlineSize : element.offsetWidth,
+        height: size ? size.blockSize : element.offsetHeight,
+      };
+    });
+
+    for (const { element, width, height } of measurements) {
+      element.style.setProperty("--seed-element-width", String(width));
+      element.style.setProperty("--seed-element-height", String(height));
+    }
+  });
+
+  return sharedObserver;
+}
+
+/**
+ * Returns a callback ref that keeps the size vars in sync on the element it is
+ * attached to. Compose it with the element's other refs however you like: being
+ * handed an element it already watches is a no-op, so the observation survives a
+ * ref whose identity changes every render and the vars are republished on resize
+ * rather than on render.
+ *
+ * Teardown still runs when the ref genuinely leaves an element — it is unobserved
+ * and its vars removed — so an element that keeps the class but loses the ref
+ * falls back to a ratio of 1 instead of holding a stale one.
+ */
+export function useElementSizeVars() {
+  // What React last handed the ref, against what the observer is watching. The
+  // two disagree for exactly one commit whenever a ref identity changes, because
+  // React detaches with `null` before re-attaching the very same element.
+  const attachedRef = React.useRef<HTMLElement | null>(null);
+  const observedRef = React.useRef<HTMLElement | null>(null);
+
+  const release = React.useCallback(() => {
+    const observed = observedRef.current;
+    if (!observed) return;
+
+    observedRef.current = null;
+    getSharedObserver().unobserve(observed);
+    observed.style.removeProperty("--seed-element-width");
+    observed.style.removeProperty("--seed-element-height");
+  }, []);
+
+  const sizeVarsRef = React.useCallback(
+    (node: HTMLElement | null) => {
+      attachedRef.current = node;
+
+      if (!node) {
+        // A commit runs to completion synchronously, so this cannot land before
+        // the re-attach that an identity change performs within the same commit.
+        // By the time it runs, the two refs tell a detached element apart from
+        // one that never actually left.
+        queueMicrotask(() => {
+          if (attachedRef.current === observedRef.current) return;
+
+          release();
+        });
+        return;
+      }
+
+      if (observedRef.current === node) return;
+
+      release();
+      observedRef.current = node;
+      // `box` selects which box change marks the element active — it does not
+      // decide which sizes the entry carries (all of them are always present).
+      // Observing the content box would miss a border-box change that leaves the
+      // content box untouched, e.g. a variant that only alters padding.
+      //
+      // Before Safari 15.4 `observe` declares no options at all, so this argument
+      // is dropped and that miss is exactly what happens there. Bounded: the ratio
+      // stays valid, only derived from the last size whose content box moved.
+      getSharedObserver().observe(node, { box: "border-box" });
+    },
+    [release],
+  );
+
+  return { sizeVarsRef };
+}

package/src/utils/scaleFeedback.tsx

@@ -0,0 +1,128 @@
+import { SCALE_FEEDBACK_CLASS_NAME } from "@seed-design/css/scale-feedback";
+import { useComposedRefs } from "@radix-ui/react-compose-refs";
+import { createSlot } from "@radix-ui/react-slot";
+import clsx from "clsx";
+import * as React from "react";
+import { useElementSizeVars } from "./elementSizeVars";
+
+/**
+ * Opts an element into scale feedback: put `scaleFeedbackRef` and
+ * `scaleFeedbackClassName` on the same element, and it publishes
+ * `--seed-feedback-scale`, a ratio that shrinks it by a fixed 2px when consumed.
+ * `ScaleFeedback` pairs them up for an element you render; reach for the hook when
+ * you can't wrap one, such as inside a component already assembling its own
+ * `ref` and `className`.
+ *
+ * The two halves belong together — the size vars `useElementSizeVars` publishes,
+ * and the class that derives the ratio from them — so the hook hands them back
+ * as a pair. If one goes missing the derivation stays guaranteed-invalid and
+ * `--seed-feedback-scale` resolves to 1: a mistake costs the effect rather than
+ * producing a wrong scale.
+ *
+ * Applying the ratio is yours, because the selector that scales the element is
+ * usually the same one that changes its background, and splitting them across
+ * two rules lets them fire under different conditions:
+ *
+ *   .my-button {
+ *     transition: background-color 0.2s, var(--seed-feedback-scale-transition);
+ *   }
+ *   .my-button:active {
+ *     background-color: ...;
+ *     scale: var(--seed-feedback-scale);
+ *   }
+ *
+ * The resting `scale: 1` comes with the class rather than with the rule above:
+ * it keeps the element a stacking context throughout, instead of becoming one
+ * mid-press and dragging `position: fixed` descendants with it.
+ */
+export function useScaleFeedback() {
+  const { sizeVarsRef } = useElementSizeVars();
+
+  return { scaleFeedbackRef: sizeVarsRef, scaleFeedbackClassName: SCALE_FEEDBACK_CLASS_NAME };
+}
+
+const ScaleFeedbackSlot = createSlot("ScaleFeedback");
+
+export interface ScaleFeedbackProps {
+  children: React.ReactElement;
+}
+
+/**
+ * Opts its child into scale feedback, so the ref and the class can no longer
+ * land on different elements or go missing one at a time. The child keeps its own
+ * `ref` and `className`, and applying the ratio is still yours — see
+ * `useScaleFeedback` for the rule this expects you to write.
+ *
+ * There is no `asChild` prop because rendering an element of our own is never the
+ * right answer: that element would be the one measured, and a block wrapper around
+ * an inline-block button reports the container's width, so the ratio would come
+ * out wrong rather than absent. The resting `scale: 1` would settle on the wrapper
+ * too, leaving the child to become a stacking context mid-press.
+ */
+export const ScaleFeedback = React.forwardRef<HTMLElement, ScaleFeedbackProps>(
+  ({ children }, ref) => {
+    const { scaleFeedbackRef, scaleFeedbackClassName } = useScaleFeedback();
+
+    const childRef = React.useRef<HTMLElement | null>(null);
+    const composedRef = useComposedRefs(scaleFeedbackRef, childRef, ref);
+
+    React.useEffect(() => {
+      if (process.env.NODE_ENV === "production") return;
+
+      // Slot throws on children it can't slot onto, but a Fragment child is a valid
+      // element it silently declines to hand a ref to, and a component child is free
+      // to drop what it is handed. Both leave a ratio of 1 and no other trace.
+      const node = childRef.current;
+      if (!node) {
+        console.warn(
+          "ScaleFeedback: the child never forwarded `ref` to a DOM element, so its size is never measured. A Fragment cannot receive one.",
+        );
+        return;
+      }
+
+      if (!node.classList.contains(SCALE_FEEDBACK_CLASS_NAME)) {
+        console.warn(
+          "ScaleFeedback: the child dropped the `className` it was handed, so no ratio is derived. Forward `className` to the element that takes `ref`.",
+        );
+      }
+    }, []);
+
+    return (
+      <ScaleFeedbackSlot ref={composedRef} className={scaleFeedbackClassName}>
+        {children}
+      </ScaleFeedbackSlot>
+    );
+  },
+);
+
+ScaleFeedback.displayName = "ScaleFeedback";
+
+/**
+ * Wraps a component so its element opts into scale feedback — for one-liner
+ * factory components (`withContext`/`withProvider` results). Hand-written
+ * forwardRef components call `useScaleFeedback` directly instead.
+ */
+export function withScaleFeedback<P>(
+  Component: React.ForwardRefExoticComponent<P>,
+): React.ForwardRefExoticComponent<P>;
+export function withScaleFeedback(
+  Component: React.ForwardRefExoticComponent<
+    React.RefAttributes<HTMLElement> & { className?: string }
+  >,
+): React.ForwardRefExoticComponent<React.RefAttributes<HTMLElement> & { className?: string }> {
+  const Pressable = React.forwardRef<HTMLElement, { className?: string }>((props, ref) => {
+    const { scaleFeedbackRef, scaleFeedbackClassName } = useScaleFeedback();
+    const composedRef = useComposedRefs(scaleFeedbackRef, ref);
+
+    return (
+      <Component
+        {...props}
+        ref={composedRef}
+        className={clsx(scaleFeedbackClassName, props.className)}
+      />
+    );
+  });
+
+  Pressable.displayName = Component.displayName;
+  return Pressable;
+}