@seed-design/react 2.2.2 → 2.4.0

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

@@ -0,0 +1,270 @@
+import { fireEvent, render } from "@testing-library/react";
+import { describe, expect, it, mock, spyOn } from "bun:test";
+import type * as React from "react";
+import { BottomSheet } from "../BottomSheet";
+import { WheelPicker } from "./index";
+
+const options = [
+  { value: "a", label: "A" },
+  { value: "b", label: "B" },
+];
+
+function fireTouchPointer(type: string, element: HTMLElement, y: number) {
+  const event = new PointerEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    pointerId: 1,
+    pointerType: "touch",
+    clientX: 50,
+    clientY: y,
+  });
+  Object.defineProperty(event, "pageX", { value: 50 });
+  Object.defineProperty(event, "pageY", { value: y });
+  fireEvent(element, event);
+}
+
+describe("WheelPicker", () => {
+  it("공개 기본 geometry와 중립 스타일을 적용한다", () => {
+    const { container, getByRole } = render(
+      <WheelPicker.Root aria-label="휠 피커">
+        <WheelPicker.Column aria-label="문자" options={options} defaultValue="a" />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("group")).toHaveStyle({
+      "--seed-wheel-picker-public-item-size": "44px",
+      "--seed-wheel-picker-public-visible-item-count": "5",
+      "--seed-wheel-picker-public-viewport-size": "220px",
+      "--seed-wheel-picker-public-center-offset": "88px",
+      "--seed-wheel-picker-public-scroll-fog-max-height": "132px",
+    });
+    expect(getByRole("group")).toHaveClass(
+      "seed-wheel-picker-public__root",
+      "seed-wheel-picker-public__root--size_medium",
+    );
+    expect(getByRole("group")).not.toHaveClass("seed-wheel-picker__root");
+    expect(container.querySelector("[data-wheel-picker-scroll-fog]")).toHaveClass(
+      "seed-wheel-picker-public__scrollFog",
+    );
+    expect(container.querySelector("[data-wheel-picker-columns]")).toHaveClass(
+      "seed-wheel-picker-public__columns",
+    );
+    expect(getByRole("spinbutton")).toHaveClass("seed-wheel-picker-public__column");
+    expect(container.querySelector('[data-wheel-picker-value="a"]')).toHaveClass(
+      "seed-wheel-picker-public__item",
+    );
+    expect(container.querySelector("[data-wheel-picker-item-label]")).toHaveClass(
+      "seed-wheel-picker-public__itemLabel",
+    );
+    expect(container.querySelector("[data-wheel-picker-indicator]")).toHaveClass(
+      "seed-wheel-picker-public__selectionIndicator",
+    );
+    const scrollFog = container.querySelector<HTMLElement>("[data-wheel-picker-scroll-fog]");
+    expect(scrollFog?.style.getPropertyValue("--scroll-fog-size-top")).toBe(
+      "var(--seed-wheel-picker-public-scroll-fog-size)",
+    );
+    expect(scrollFog?.style.getPropertyValue("--scroll-fog-size-bottom")).toBe(
+      "var(--seed-wheel-picker-public-scroll-fog-size)",
+    );
+  });
+
+  it("Small 크기의 geometry와 타이포그래피 Variant를 적용한다", () => {
+    const { container, getByRole } = render(
+      <WheelPicker.Root aria-label="작은 휠 피커" size="small">
+        <WheelPicker.Column aria-label="문자" options={options} defaultValue="a" />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("group")).toHaveStyle({
+      "--seed-wheel-picker-public-item-size": "36px",
+      "--seed-wheel-picker-public-visible-item-count": "5",
+      "--seed-wheel-picker-public-viewport-size": "180px",
+      "--seed-wheel-picker-public-center-offset": "72px",
+      "--seed-wheel-picker-public-scroll-fog-max-height": "108px",
+    });
+    expect(getByRole("group")).toHaveClass("seed-wheel-picker-public__root--size_small");
+    expect(container.querySelector("[data-wheel-picker-item-label]")).toHaveClass(
+      "seed-wheel-picker-public__itemLabel--size_small",
+    );
+  });
+
+  it("itemSize를 지정하면 Size의 Item 높이와 Scroll Fog 최대 높이만 덮어쓴다", () => {
+    const { container, getByRole } = render(
+      <WheelPicker.Root
+        aria-label="사용자 지정 휠 피커"
+        size="small"
+        itemSize={56}
+        visibleItemCount={7}
+      >
+        <WheelPicker.Column aria-label="문자" options={options} defaultValue="a" />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("group")).toHaveStyle({
+      "--seed-wheel-picker-public-item-size": "56px",
+      "--seed-wheel-picker-public-visible-item-count": "7",
+      "--seed-wheel-picker-public-viewport-size": "392px",
+      "--seed-wheel-picker-public-center-offset": "168px",
+      "--seed-wheel-picker-public-scroll-fog-max-height": "168px",
+    });
+    expect(container.querySelector("[data-wheel-picker-item-label]")).toHaveClass(
+      "seed-wheel-picker-public__itemLabel--size_small",
+    );
+  });
+
+  it("Item을 9개 표시해도 Scroll Fog 최대 높이는 Item 3개 높이로 유지한다", () => {
+    const { getByRole } = render(
+      <WheelPicker.Root aria-label="긴 휠 피커" visibleItemCount={9}>
+        <WheelPicker.Column aria-label="문자" options={options} defaultValue="a" />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("group")).toHaveStyle({
+      "--seed-wheel-picker-public-viewport-size": "396px",
+      "--seed-wheel-picker-public-scroll-fog-max-height": "132px",
+    });
+  });
+
+  it("Root와 Column의 className을 허용한다", () => {
+    const { getByRole } = render(
+      <WheelPicker.Root aria-label="휠 피커" className="custom-root">
+        <WheelPicker.Column aria-label="문자" options={options} className="custom-column" />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("group")).toHaveClass("custom-root");
+    expect(getByRole("spinbutton")).toHaveClass("custom-column");
+  });
+
+  it("renderLabel로 기본 ItemLabel을 대체한다", () => {
+    const { container, getByText } = render(
+      <WheelPicker.Root aria-label="휠 피커" itemSize={56}>
+        <WheelPicker.Column
+          aria-label="문자"
+          options={options}
+          renderLabel={(option) => <span data-custom-label="">{option.label}</span>}
+        />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByText("A")).toHaveAttribute("data-custom-label");
+    expect(getByText("A").parentElement).toHaveClass("seed-wheel-picker-public__item");
+    expect(container.querySelector("[data-wheel-picker-item-label]")).not.toBeInTheDocument();
+  });
+
+  it("renderLabel에서 공개 ItemLabel을 재사용한다", () => {
+    const { getByText } = render(
+      <WheelPicker.Root aria-label="휠 피커">
+        <WheelPicker.Column
+          aria-label="문자"
+          options={options}
+          renderLabel={(option) => (
+            <WheelPicker.ItemLabel data-reused-label="">{option.label}</WheelPicker.ItemLabel>
+          )}
+        />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByText("A")).toHaveClass("seed-wheel-picker-public__itemLabel");
+    expect(getByText("A")).toHaveAttribute("data-wheel-picker-item-label");
+    expect(getByText("A")).toHaveAttribute("data-reused-label");
+  });
+
+  it("option의 ariaLabel을 기본 접근성 텍스트로 사용한다", () => {
+    const { getByRole } = render(
+      <WheelPicker.Root aria-label="배지 선택">
+        <WheelPicker.Column
+          aria-label="배지"
+          options={[{ value: "popular", label: <span>◆ 인기</span>, ariaLabel: "인기" }]}
+        />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("spinbutton", { name: "배지" })).toHaveAttribute("aria-valuetext", "인기");
+  });
+
+  it("숫자 label을 기본 접근성 텍스트로 변환한다", () => {
+    const { getByRole } = render(
+      <WheelPicker.Root aria-label="수량 선택">
+        <WheelPicker.Column aria-label="수량" options={[{ value: "one", label: 1 }]} />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("spinbutton", { name: "수량" })).toHaveAttribute("aria-valuetext", "1");
+  });
+
+  it("Root의 disabled 상태를 Column과 Item에 전파한다", () => {
+    const { container, getByRole } = render(
+      <WheelPicker.Root aria-label="비활성 휠 피커" disabled>
+        <WheelPicker.Column aria-label="문자" options={options} defaultValue="a" />
+      </WheelPicker.Root>,
+    );
+
+    expect(getByRole("group")).toHaveAttribute("data-disabled");
+    expect(getByRole("spinbutton")).toHaveAttribute("data-disabled");
+    expect(getByRole("spinbutton")).toHaveAttribute("aria-disabled", "true");
+    expect(container.querySelector('[data-wheel-picker-value="a"]')).toHaveAttribute(
+      "data-selected",
+    );
+  });
+
+  it("지원하지 않는 readOnly 값이 런타임에 전달되어도 읽기 전용으로 동작하지 않는다", () => {
+    const RootWithLegacyReadOnly = WheelPicker.Root as React.ComponentType<
+      WheelPicker.RootProps & { readOnly?: boolean }
+    >;
+    const { getByRole } = render(
+      <RootWithLegacyReadOnly aria-label="휠 피커" readOnly>
+        <WheelPicker.Column aria-label="문자" options={options} defaultValue="a" />
+      </RootWithLegacyReadOnly>,
+    );
+
+    expect(getByRole("group")).not.toHaveAttribute("data-readonly");
+    expect(getByRole("spinbutton")).not.toHaveAttribute("aria-readonly");
+  });
+
+  it("BottomSheet 안에서 컬럼을 스크롤할 때 시트 드래그를 시작하지 않는다", () => {
+    const originalSetPointerCapture = HTMLElement.prototype.setPointerCapture;
+    HTMLElement.prototype.setPointerCapture = mock(() => {});
+
+    try {
+      const { container, getByRole } = render(
+        <BottomSheet.Root defaultOpen modal={false} autoFocus={false} skipAnimation>
+          <BottomSheet.Content>
+            <BottomSheet.Title>값 선택</BottomSheet.Title>
+            <BottomSheet.Description>원하는 값을 선택하세요.</BottomSheet.Description>
+            <WheelPicker.Root aria-label="휠 피커">
+              <WheelPicker.Column aria-label="문자" options={options} defaultValue="b" />
+            </WheelPicker.Root>
+          </BottomSheet.Content>
+        </BottomSheet.Root>,
+      );
+      const content = container.ownerDocument.querySelector("[data-drawer]") as HTMLElement;
+      const column = getByRole("spinbutton");
+
+      content.style.transform = "matrix(1, 0, 0, 1, 0, 0)";
+      spyOn(content, "getBoundingClientRect").mockReturnValue({
+        x: 0,
+        y: 0,
+        width: 320,
+        height: 400,
+        top: 0,
+        left: 0,
+        right: 320,
+        bottom: 400,
+        toJSON: () => {},
+      });
+      Object.defineProperties(column, {
+        clientHeight: { value: 220, configurable: true },
+        scrollHeight: { value: 440, configurable: true },
+      });
+      column.scrollTop = 44;
+
+      fireTouchPointer("pointerdown", column, 100);
+      fireTouchPointer("pointermove", column, 130);
+
+      expect(content.style.transform).toBe("matrix(1, 0, 0, 1, 0, 0)");
+    } finally {
+      HTMLElement.prototype.setPointerCapture = originalSetPointerCapture;
+    }
+  });
+});

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 };
+}