@seed-design/react-field-button 0.0.0-alpha-20260414104312

package/lib/index.js

@@ -0,0 +1,14 @@
+import { F as FieldButtonButton, a as FieldButtonClearButton, b as FieldButtonDescription, c as FieldButtonErrorMessage, d as FieldButtonHiddenInput, e as FieldButtonRoot } from './FieldButton-12s-BzczO8x6.js';
+export { u as useFieldButtonContext } from './FieldButton-12s-BzczO8x6.js';
+
+var FieldButton_namespace = {
+  __proto__: null,
+  Button: FieldButtonButton,
+  ClearButton: FieldButtonClearButton,
+  Description: FieldButtonDescription,
+  ErrorMessage: FieldButtonErrorMessage,
+  HiddenInput: FieldButtonHiddenInput,
+  Root: FieldButtonRoot
+};
+
+export { FieldButton_namespace as FieldButton, FieldButtonButton, FieldButtonClearButton, FieldButtonDescription, FieldButtonErrorMessage, FieldButtonHiddenInput, FieldButtonRoot };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@seed-design/react-field-button",
+  "version": "0.0.0-alpha-20260414104312",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daangn/seed-design.git",
+    "directory": "packages/react-headless/field-button"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./lib/index.cjs",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rm -rf lib",
+    "build": "bunchee",
+    "lint:publish": "bun publint"
+  },
+  "dependencies": {
+    "@radix-ui/react-compose-refs": "^1.1.2",
+    "@radix-ui/react-use-controllable-state": "^1.2.2",
+    "@seed-design/dom-utils": "1.0.0",
+    "@seed-design/react-primitive": "0.0.0-alpha-20260414104312",
+    "@seed-design/react-supports": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/FieldButton.namespace.ts

@@ -0,0 +1,14 @@
+export {
+  FieldButtonButton as Button,
+  FieldButtonClearButton as ClearButton,
+  FieldButtonDescription as Description,
+  FieldButtonErrorMessage as ErrorMessage,
+  FieldButtonHiddenInput as HiddenInput,
+  FieldButtonRoot as Root,
+  type FieldButtonButtonProps as ButtonProps,
+  type FieldButtonClearButtonProps as ClearButtonProps,
+  type FieldButtonDescriptionProps as DescriptionProps,
+  type FieldButtonErrorMessageProps as ErrorMessageProps,
+  type FieldButtonHiddenInputProps as HiddenInputProps,
+  type FieldButtonRootProps as RootProps,
+} from "./FieldButton";

package/src/FieldButton.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+import { composeRefs } from "@radix-ui/react-compose-refs";
+import { mergeProps } from "@seed-design/dom-utils";
+import { Primitive, type PrimitiveProps } from "@seed-design/react-primitive";
+import React, { forwardRef, type ButtonHTMLAttributes, type HTMLAttributes } from "react";
+import { useFieldButton, type UseFieldButtonProps } from "./useFieldButton";
+import { FieldButtonProvider, useFieldButtonContext } from "./useFieldButtonContext";
+
+export interface FieldButtonRootProps
+  extends UseFieldButtonProps,
+    PrimitiveProps,
+    HTMLAttributes<HTMLDivElement> {}
+
+export const FieldButtonRoot = forwardRef<HTMLDivElement, FieldButtonRootProps>(
+  ({ disabled, readOnly, invalid, name, values, onValuesChange, ...otherProps }, ref) => {
+    const api = useFieldButton({ disabled, readOnly, invalid, name, values, onValuesChange });
+    const mergedProps = mergeProps(api.rootProps, otherProps);
+
+    return (
+      <FieldButtonProvider value={api}>
+        <Primitive.div ref={ref} {...mergedProps} />
+      </FieldButtonProvider>
+    );
+  },
+);
+FieldButtonRoot.displayName = "FieldButtonRoot";
+
+export interface FieldButtonButtonProps
+  extends PrimitiveProps,
+    ButtonHTMLAttributes<HTMLButtonElement> {}
+
+export const FieldButtonButton = forwardRef<HTMLButtonElement, FieldButtonButtonProps>(
+  (props, ref) => {
+    const { buttonProps } = useFieldButtonContext();
+    const mergedProps = mergeProps(buttonProps, props);
+
+    return <Primitive.button ref={ref} {...mergedProps} />;
+  },
+);
+FieldButtonButton.displayName = "FieldButtonButton";
+
+export interface FieldButtonDescriptionProps
+  extends PrimitiveProps,
+    HTMLAttributes<HTMLSpanElement> {}
+
+export const FieldButtonDescription = forwardRef<HTMLSpanElement, FieldButtonDescriptionProps>(
+  (props, ref) => {
+    const { refs, descriptionProps } = useFieldButtonContext();
+    const mergedProps = mergeProps(descriptionProps, props);
+
+    return <Primitive.span ref={composeRefs(refs.description, ref)} {...mergedProps} />;
+  },
+);
+FieldButtonDescription.displayName = "FieldButtonDescription";
+
+export interface FieldButtonErrorMessageProps
+  extends PrimitiveProps,
+    HTMLAttributes<HTMLDivElement> {}
+
+export const FieldButtonErrorMessage = forwardRef<HTMLDivElement, FieldButtonErrorMessageProps>(
+  (props, ref) => {
+    const { refs, errorMessageProps } = useFieldButtonContext();
+    const mergedProps = mergeProps(errorMessageProps, props);
+
+    return <Primitive.div ref={composeRefs(refs.errorMessage, ref)} {...mergedProps} />;
+  },
+);
+FieldButtonErrorMessage.displayName = "FieldButtonErrorMessage";
+
+export interface FieldButtonHiddenInputProps
+  extends PrimitiveProps,
+    React.InputHTMLAttributes<HTMLInputElement> {
+  valueIndex: number;
+}
+
+export const FieldButtonHiddenInput = forwardRef<HTMLInputElement, FieldButtonHiddenInputProps>(
+  ({ valueIndex, ...props }, ref) => {
+    const { getHiddenInputProps } = useFieldButtonContext();
+    const hiddenInputProps = getHiddenInputProps(valueIndex);
+
+    if (!hiddenInputProps) return null;
+
+    return <Primitive.input ref={ref} {...mergeProps(hiddenInputProps, props)} />;
+  },
+);
+FieldButtonHiddenInput.displayName = "FieldButtonHiddenInput";
+
+export interface FieldButtonClearButtonProps
+  extends PrimitiveProps,
+    ButtonHTMLAttributes<HTMLButtonElement> {}
+
+export const FieldButtonClearButton = forwardRef<HTMLButtonElement, FieldButtonClearButtonProps>(
+  (props, ref) => {
+    const { clearButtonProps } = useFieldButtonContext();
+    const mergedProps = mergeProps(clearButtonProps, props);
+
+    return <Primitive.button ref={ref} {...mergedProps} />;
+  },
+);
+FieldButtonClearButton.displayName = "FieldButtonClearButton";

package/src/dom.ts

@@ -0,0 +1,2 @@
+export const getDescriptionId = (id: string) => `field-button:${id}:description`;
+export const getErrorMessageId = (id: string) => `field-button:${id}:error-message`;

package/src/index.ts

@@ -0,0 +1,19 @@
+export {
+  FieldButtonButton,
+  FieldButtonClearButton,
+  FieldButtonDescription,
+  FieldButtonErrorMessage,
+  FieldButtonHiddenInput,
+  FieldButtonRoot,
+  type FieldButtonButtonProps,
+  type FieldButtonClearButtonProps,
+  type FieldButtonDescriptionProps,
+  type FieldButtonErrorMessageProps,
+  type FieldButtonHiddenInputProps,
+  type FieldButtonRootProps,
+} from "./FieldButton";
+
+export { useFieldButtonContext, type UseFieldButtonContext } from "./useFieldButtonContext";
+export type { UseFieldButtonProps } from "./useFieldButton";
+
+export * as FieldButton from "./FieldButton.namespace";

package/src/useFieldButton.test.tsx

@@ -0,0 +1,276 @@
+import { fireEvent, render } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, mock } from "bun:test";
+
+import type { ReactElement } from "react";
+
+import {
+  FieldButtonButton,
+  FieldButtonClearButton,
+  FieldButtonDescription,
+  FieldButtonErrorMessage,
+  FieldButtonHiddenInput,
+  FieldButtonRoot,
+  type FieldButtonRootProps,
+} from "./FieldButton";
+
+function setUp(jsx: ReactElement) {
+  return {
+    user: userEvent.setup(),
+    ...render(jsx),
+  };
+}
+
+function FieldButton(props: FieldButtonRootProps) {
+  return (
+    <FieldButtonRoot {...props}>
+      <FieldButtonButton>Click me</FieldButtonButton>
+      <FieldButtonClearButton>Clear</FieldButtonClearButton>
+      <FieldButtonDescription>Description text</FieldButtonDescription>
+      <FieldButtonErrorMessage>Error message</FieldButtonErrorMessage>
+      {props.values?.map((_, index) => (
+        <FieldButtonHiddenInput key={index} valueIndex={index} />
+      ))}
+    </FieldButtonRoot>
+  );
+}
+
+describe("useFieldButton", () => {
+  it("should render the field button correctly", () => {
+    const { getByRole } = setUp(<FieldButton />);
+    const button = getByRole("button", { name: "Click me" });
+
+    expect(button).toBeInTheDocument();
+  });
+
+  it("should render with initial values", () => {
+    const { container } = setUp(<FieldButton values={["value1", "value2"]} />);
+    const hiddenInputs = container.querySelectorAll('input[type="hidden"]');
+
+    expect(hiddenInputs).toHaveLength(2);
+    expect(hiddenInputs[0]).toHaveValue("value1");
+    expect(hiddenInputs[1]).toHaveValue("value2");
+  });
+
+  it("should have hover state when pointer moves over root", async () => {
+    const { container, user } = setUp(<FieldButton />);
+    const root = container.firstElementChild;
+
+    if (!root) throw new Error("root not found");
+
+    await user.hover(root);
+    expect(root).toHaveAttribute("data-hover");
+
+    await user.unhover(root);
+    expect(root).not.toHaveAttribute("data-hover");
+  });
+
+  it("should have active state when button is pressed", () => {
+    const { getByRole } = setUp(<FieldButton />);
+    const button = getByRole("button", { name: "Click me" });
+
+    fireEvent.pointerDown(button);
+    expect(button).toHaveAttribute("data-active");
+
+    fireEvent.pointerUp(button);
+    expect(button).not.toHaveAttribute("data-active");
+  });
+
+  it("should have focus state when button is focused", async () => {
+    const { getByRole, user } = setUp(<FieldButton />);
+    const button = getByRole("button", { name: "Click me" });
+
+    await user.tab();
+    expect(button).toHaveFocus();
+    expect(button).toHaveAttribute("data-focus");
+    expect(button).toHaveAttribute("data-focus-visible");
+
+    await user.click(document.body);
+    expect(button).not.toHaveFocus();
+    expect(button).not.toHaveAttribute("data-focus");
+    expect(button).not.toHaveAttribute("data-focus-visible");
+  });
+
+  it("should have disabled state when disabled prop is true", () => {
+    const { getByRole } = setUp(<FieldButton disabled />);
+    const button = getByRole("button", { name: "Click me" });
+
+    expect(button).toBeDisabled();
+    expect(button).toHaveAttribute("data-disabled");
+    expect(button).toHaveAttribute("aria-disabled", "true");
+  });
+
+  it("should have readOnly state when readOnly prop is true", () => {
+    const { getByRole } = setUp(<FieldButton readOnly />);
+    const button = getByRole("button", { name: "Click me" });
+
+    expect(button).toBeDisabled();
+    expect(button).toHaveAttribute("data-readonly");
+    expect(button).toHaveAttribute("aria-disabled", "true");
+  });
+
+  it("should have invalid state when invalid prop is true", () => {
+    const { getByRole } = setUp(<FieldButton invalid />);
+    const button = getByRole("button", { name: "Click me" });
+
+    expect(button).toHaveAttribute("data-invalid");
+  });
+
+  it("should have aria-describedby with description id", () => {
+    const { getByRole, getByText } = setUp(<FieldButton />);
+    const button = getByRole("button", { name: "Click me" });
+    const description = getByText("Description text");
+
+    expect(button).toHaveAttribute("aria-describedby");
+    const describedBy = button.getAttribute("aria-describedby");
+    expect(describedBy).toContain(description.id);
+  });
+
+  it("should have aria-describedby with error message id ", () => {
+    const { getByRole, getByText } = setUp(<FieldButton />);
+    const button = getByRole("button", { name: "Click me" });
+    const errorMessage = getByText("Error message");
+
+    expect(button).toHaveAttribute("aria-describedby");
+    const describedBy = button.getAttribute("aria-describedby");
+    expect(describedBy).toContain(errorMessage.id);
+  });
+
+  it("should have aria-live on error message", () => {
+    const { getByText } = setUp(<FieldButton />);
+    const errorMessage = getByText("Error message");
+
+    expect(errorMessage).toHaveAttribute("aria-live", "polite");
+  });
+
+  it("should use custom name for hidden inputs", () => {
+    const { container } = setUp(<FieldButton name="custom-name" values={["value1"]} />);
+    const hiddenInput = container.querySelector('input[type="hidden"]');
+
+    expect(hiddenInput).toHaveAttribute("name", "custom-name");
+  });
+
+  it("should clear active state when pointer leaves", () => {
+    const { getByRole, container } = setUp(<FieldButton />);
+    const button = getByRole("button", { name: "Click me" });
+    const root = container.firstElementChild;
+
+    if (!root) throw new Error("root not found");
+
+    fireEvent.pointerDown(button);
+    expect(button).toHaveAttribute("data-active");
+
+    fireEvent.pointerLeave(root);
+    expect(button).not.toHaveAttribute("data-active");
+  });
+
+  it("should not disable hidden inputs when readOnly (unlike disabled)", () => {
+    const { container } = setUp(<FieldButton readOnly values={["value1", "value2"]} />);
+    const hiddenInputs = container.querySelectorAll('input[type="hidden"]');
+
+    expect(hiddenInputs).toHaveLength(2);
+    expect(hiddenInputs[0]).not.toBeDisabled();
+    expect(hiddenInputs[1]).not.toBeDisabled();
+    expect(hiddenInputs[0]).toHaveValue("value1");
+    expect(hiddenInputs[1]).toHaveValue("value2");
+  });
+
+  it("should disable hidden inputs when disabled", () => {
+    const { container } = setUp(<FieldButton disabled values={["value1", "value2"]} />);
+    const hiddenInputs = container.querySelectorAll('input[type="hidden"]');
+
+    expect(hiddenInputs).toHaveLength(2);
+    expect(hiddenInputs[0]).toBeDisabled();
+    expect(hiddenInputs[1]).toBeDisabled();
+  });
+
+  it("should render without description and errorMessage", () => {
+    function MinimalFieldButton(props: FieldButtonRootProps) {
+      return (
+        <FieldButtonRoot {...props}>
+          <FieldButtonButton>Click me</FieldButtonButton>
+          {props.values?.map((_, index) => (
+            <FieldButtonHiddenInput key={index} valueIndex={index} />
+          ))}
+        </FieldButtonRoot>
+      );
+    }
+
+    const { getByRole } = setUp(<MinimalFieldButton />);
+    const button = getByRole("button", { name: "Click me" });
+
+    expect(button).not.toHaveAttribute("aria-describedby");
+  });
+
+  it("should only include rendered elements in aria-describedby", () => {
+    function FieldButtonWithDescription(props: FieldButtonRootProps) {
+      return (
+        <FieldButtonRoot {...props}>
+          <FieldButtonButton>Click me</FieldButtonButton>
+          <FieldButtonDescription>Description text</FieldButtonDescription>
+          {props.values?.map((_, index) => (
+            <FieldButtonHiddenInput key={index} valueIndex={index} />
+          ))}
+        </FieldButtonRoot>
+      );
+    }
+
+    const { getByRole, getByText } = setUp(<FieldButtonWithDescription />);
+    const button = getByRole("button", { name: "Click me" });
+    const description = getByText("Description text");
+
+    const describedBy = button.getAttribute("aria-describedby");
+    expect(describedBy).toBe(description.id);
+  });
+
+  describe("clear button", () => {
+    it("should call onValuesChange when clear button is clicked", async () => {
+      const handleValuesChange = mock(() => {});
+      const { getByRole, user } = setUp(
+        <FieldButton values={["value1"]} onValuesChange={handleValuesChange} />,
+      );
+      const clearButton = getByRole("button", { name: "Clear" });
+
+      await user.click(clearButton);
+      expect(handleValuesChange).toHaveBeenCalledWith([]);
+    });
+
+    it("should hide clear button when disabled", async () => {
+      const handleValuesChange = mock(() => {});
+      const { getByText, user } = setUp(
+        <FieldButton disabled values={["value1"]} onValuesChange={handleValuesChange} />,
+      );
+      const clearButton = getByText("Clear");
+
+      expect(clearButton).toHaveAttribute("hidden");
+
+      await user.click(clearButton);
+      expect(handleValuesChange).not.toHaveBeenCalled();
+    });
+
+    it("should hide clear button when readOnly", async () => {
+      const handleValuesChange = mock(() => {});
+      const { getByText, user } = setUp(
+        <FieldButton readOnly values={["value1"]} onValuesChange={handleValuesChange} />,
+      );
+      const clearButton = getByText("Clear");
+
+      expect(clearButton).toHaveAttribute("hidden");
+
+      await user.click(clearButton);
+      expect(handleValuesChange).not.toHaveBeenCalled();
+    });
+
+    it("should not have active state when clear button is pressed", () => {
+      const { getByRole } = setUp(<FieldButton />);
+      const button = getByRole("button", { name: "Click me" });
+      const clearButton = getByRole("button", { name: "Clear" });
+
+      fireEvent.pointerDown(clearButton);
+      expect(button).not.toHaveAttribute("data-active");
+
+      fireEvent.pointerUp(clearButton);
+      expect(button).not.toHaveAttribute("data-active");
+    });
+  });
+});

package/src/useFieldButton.ts

@@ -0,0 +1,210 @@
+import { ariaAttr, buttonProps, dataAttr, elementProps, inputProps } from "@seed-design/dom-utils";
+import { useCallback, useId, useState } from "react";
+import { getDescriptionId, getErrorMessageId } from "./dom";
+import { useSupports } from "@seed-design/react-supports";
+
+interface UseFieldButtonStateProps {
+  values?: string[];
+  onValuesChange?: (values: string[]) => void;
+}
+
+function useFieldButtonState({ values = [], onValuesChange = () => {} }: UseFieldButtonStateProps) {
+  const [isHovered, setIsHovered] = useState(false);
+  const [isActive, setIsActive] = useState(false);
+  const [isFocused, setIsFocused] = useState(false);
+  const [isFocusVisible, setIsFocusVisible] = useState(false);
+
+  const [isDescriptionRendered, setIsDescriptionRendered] = useState(false);
+  const descriptionRef = useCallback((node: HTMLElement | null) => {
+    setIsDescriptionRendered(!!node);
+  }, []);
+  const [isErrorMessageRendered, setIsErrorMessageRendered] = useState(false);
+  const errorMessageRef = useCallback((node: HTMLElement | null) => {
+    setIsErrorMessageRendered(!!node);
+  }, []);
+
+  return {
+    values,
+    isHovered,
+    isActive,
+    isFocused,
+    isFocusVisible,
+
+    refs: {
+      description: descriptionRef,
+      errorMessage: errorMessageRef,
+    },
+    renderedElements: {
+      description: isDescriptionRendered,
+      errorMessage: isErrorMessageRendered,
+    },
+
+    setValues: onValuesChange,
+    setIsHovered,
+    setIsActive,
+    setIsFocused,
+    setIsFocusVisible,
+  };
+}
+
+export interface UseFieldButtonProps extends UseFieldButtonStateProps {
+  /**
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * @default false
+   */
+  invalid?: boolean;
+
+  /**
+   * @default false
+   */
+  readOnly?: boolean;
+
+  name?: string;
+}
+
+export type UseFieldButtonReturn = ReturnType<typeof useFieldButton>;
+
+export function useFieldButton({
+  values: propValues,
+  onValuesChange,
+  disabled = false,
+  invalid = false,
+  readOnly = false,
+  name,
+}: UseFieldButtonProps) {
+  const id = useId();
+  const isFocusVisibleSupported = useSupports("selector(:focus-visible)");
+
+  const {
+    values: stateValues,
+    isHovered,
+    isActive,
+    isFocused,
+    isFocusVisible,
+    refs,
+    renderedElements,
+    setValues,
+    setIsHovered,
+    setIsActive,
+    setIsFocused,
+    setIsFocusVisible,
+  } = useFieldButtonState({ values: propValues, onValuesChange });
+
+  const ariaDescribedBy =
+    [
+      renderedElements.description ? getDescriptionId(id) : false,
+      renderedElements.errorMessage ? getErrorMessageId(id) : false,
+    ]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  const stateProps = elementProps({
+    "data-hover": dataAttr(isHovered),
+    "data-active": dataAttr(isActive),
+    "data-focus": dataAttr(isFocused),
+    "data-focus-visible": dataAttr(isFocusVisible),
+    "data-disabled": dataAttr(disabled),
+    "data-invalid": dataAttr(invalid),
+    "data-readonly": dataAttr(readOnly),
+  });
+
+  return {
+    values: stateValues,
+    active: isActive,
+    focused: isFocused,
+    invalid,
+    disabled,
+    readOnly,
+
+    setIsFocused,
+    setIsFocusVisible,
+
+    refs,
+
+    stateProps,
+
+    rootProps: elementProps({
+      ...stateProps,
+
+      onPointerMove() {
+        setIsHovered(true);
+      },
+      onPointerLeave() {
+        setIsHovered(false);
+        setIsActive(false);
+      },
+    }),
+
+    buttonProps: buttonProps({
+      ...stateProps,
+
+      type: "button",
+      disabled: disabled || readOnly,
+
+      "aria-disabled": ariaAttr(disabled || readOnly),
+      "aria-describedby": ariaDescribedBy,
+
+      // note that pointerdown and pointerup are attached to the button, not the root
+      // this is for preventing setting isActive to true when the clear button is pressed
+      onPointerDown() {
+        setIsActive(true);
+      },
+      onPointerUp() {
+        setIsActive(false);
+      },
+
+      onBlur() {
+        setIsFocused(false);
+        if (isFocusVisibleSupported) {
+          setIsFocusVisible(false);
+        }
+      },
+      onFocus(event) {
+        setIsFocused(true);
+        if (isFocusVisibleSupported) {
+          setIsFocusVisible(event.target.matches(":focus-visible"));
+        }
+      },
+    }),
+
+    clearButtonProps: buttonProps({
+      type: "button",
+      disabled: disabled || readOnly,
+
+      onClick: useCallback(() => setValues([]), [setValues]),
+
+      hidden: disabled || readOnly,
+    }),
+
+    getHiddenInputProps: useCallback(
+      (index: number) => {
+        const value = stateValues[index];
+
+        if (value === undefined) return null;
+
+        return inputProps({
+          type: "hidden",
+          value,
+          disabled, // disabled field button should not submit values, while readonly field button should submit values
+          name: name || id,
+        });
+      },
+      [stateValues, name, id, disabled],
+    ),
+
+    descriptionProps: elementProps({
+      ...stateProps,
+      id: getDescriptionId(id),
+    }),
+
+    errorMessageProps: elementProps({
+      ...stateProps,
+      id: getErrorMessageId(id),
+      "aria-live": "polite",
+    }),
+  };
+}