@primitiv-ui/react 0.1.0

package/src/Select/Select.tsx

@@ -0,0 +1,204 @@
+import { ChangeEvent, Children, isValidElement, ReactNode } from "react";
+
+import { useFieldProps } from "../Field/hooks";
+import { Slot } from "../Slot";
+
+import {
+  SelectGroupProps,
+  SelectOptionProps,
+  SelectPlaceholderProps,
+  SelectRootProps,
+} from "./types";
+
+const PLACEHOLDER_DISPLAY_NAME = "SelectPlaceholder";
+
+function hasPlaceholderChild(children: ReactNode): boolean {
+  return Children.toArray(children).some((child) => {
+    if (!isValidElement(child)) return false;
+    const type = child.type as { displayName?: string };
+    return type.displayName === PLACEHOLDER_DISPLAY_NAME;
+  });
+}
+
+/**
+ * The root of a Select — renders a native `<select>` element and passes
+ * all `SelectHTMLAttributes` through to the DOM.
+ *
+ * Browser-native behaviour is preserved: keyboard navigation (arrow keys,
+ * Home/End, typeahead), the platform popup, mobile UX, and form
+ * submission all work without additional JS.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultValue` (or omit it). The browser owns
+ *   the selection. `onValueChange` is optional.
+ * - **Controlled** — pass `value` and `onValueChange` together. Every
+ *   transition defers back through `onValueChange`.
+ *
+ * `onValueChange` receives the new selection as a plain string. The
+ * consumer's own `onChange` (the raw `ChangeEvent`) still fires alongside
+ * it.
+ *
+ * **Placeholder integration.** When a {@link Select.Placeholder} appears
+ * among the direct children and neither `value` nor `defaultValue` is
+ * set, Root infers `defaultValue=""` so the placeholder — not the first
+ * selectable option — is the initial selection.
+ *
+ * **Field integration.** When rendered inside a `<Field.Root>`, Select
+ * opts into `FieldContext` and inherits `id`, `aria-describedby`,
+ * `aria-invalid`, `disabled`, and `required` from the field. Any prop
+ * the consumer passes wins; `aria-describedby` is composed (consumer
+ * ids first, then field-supplied description / error ids). Outside a
+ * `<Field.Root>`, behaviour is unchanged.
+ */
+function SelectRoot({
+  children,
+  asChild = false,
+  onChange,
+  onValueChange,
+  value,
+  defaultValue,
+  ...consumer
+}: SelectRootProps) {
+  const merged = useFieldProps(consumer);
+
+  const handleChange = (event: ChangeEvent<HTMLSelectElement>) => {
+    onChange?.(event);
+    onValueChange?.(event.target.value);
+  };
+
+  const inferredDefaultValue =
+    !asChild &&
+    value === undefined &&
+    defaultValue === undefined &&
+    hasPlaceholderChild(children)
+      ? ""
+      : defaultValue;
+
+  const controlProps =
+    value !== undefined
+      ? { value }
+      : inferredDefaultValue !== undefined
+        ? { defaultValue: inferredDefaultValue }
+        : {};
+
+  const rootProps = {
+    ...merged,
+    ...controlProps,
+    "data-disabled": merged.disabled ? "" : undefined,
+    onChange: handleChange,
+  };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+  return <select {...rootProps}>{children}</select>;
+}
+
+SelectRoot.displayName = "SelectRoot";
+
+/**
+ * An individual choice inside a Select — renders a native `<option>`
+ * element and passes all `OptionHTMLAttributes` through to the DOM.
+ *
+ * Native `<option>` only renders text; rich content (icons, descriptions)
+ * is not supported.
+ */
+function SelectOption({ children, ...rest }: SelectOptionProps) {
+  return <option {...rest}>{children}</option>;
+}
+
+SelectOption.displayName = "SelectOption";
+
+/**
+ * Visually groups related options inside the Select popup — renders a
+ * native `<optgroup>` element. The `label` is shown by the browser as a
+ * non-selectable heading and is announced as the group's accessible name.
+ */
+function SelectGroup({ children, ...rest }: SelectGroupProps) {
+  return <optgroup {...rest}>{children}</optgroup>;
+}
+
+SelectGroup.displayName = "SelectGroup";
+
+/**
+ * A non-selectable hint shown as the initial selection of a Select.
+ * Renders a native `<option value="" disabled hidden>` so the browser
+ * displays it before the user picks anything but makes it unreachable
+ * from the dropdown afterwards. Render it as the first child of
+ * {@link Select.Root} (above any `Select.Option` or `Select.Group`).
+ *
+ * Pair with `required` on {@link Select.Root} to make the browser's
+ * native form validation catch an unchosen value at submission.
+ */
+function SelectPlaceholder({ children, ...rest }: SelectPlaceholderProps) {
+  return (
+    <option {...rest} value="" disabled hidden>
+      {children}
+    </option>
+  );
+}
+
+SelectPlaceholder.displayName = "SelectPlaceholder";
+
+type TSelectCompound = typeof SelectRoot & {
+  Root: typeof SelectRoot;
+  Option: typeof SelectOption;
+  Group: typeof SelectGroup;
+  Placeholder: typeof SelectPlaceholder;
+};
+
+/**
+ * Headless **Select** — a compound component wrapping the native
+ * `<select>` / `<option>` / `<optgroup>` elements. Zero styles ship.
+ *
+ * Because the underlying element is the real `<select>`, the browser
+ * owns the popup, keyboard interaction (arrow keys, Home/End,
+ * typeahead), mobile UX (wheel pickers), and form submission. No
+ * positioning JS or Portal is involved.
+ *
+ * `Select` is both callable (an alias of {@link SelectRoot | `Select.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link SelectRoot | `Select.Root`} — state owner, renders `<select>`.
+ * - {@link SelectOption | `Select.Option`} — renders `<option>`.
+ * - {@link SelectGroup | `Select.Group`} — renders `<optgroup label>`.
+ * - {@link SelectPlaceholder | `Select.Placeholder`} — disabled+hidden
+ *   first option used as the initial hint.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Select } from "@primitiv-ui/react";
+ *
+ * <Select.Root defaultValue="apple" aria-label="Pick a fruit">
+ *   <Select.Option value="apple">Apple</Select.Option>
+ *   <Select.Option value="banana">Banana</Select.Option>
+ * </Select.Root>
+ * ```
+ *
+ * @example With placeholder and groups
+ * ```tsx
+ * <Select.Root required aria-label="Pick a food">
+ *   <Select.Placeholder>Choose…</Select.Placeholder>
+ *   <Select.Group label="Fruits">
+ *     <Select.Option value="apple">Apple</Select.Option>
+ *   </Select.Group>
+ *   <Select.Group label="Vegetables">
+ *     <Select.Option value="carrot">Carrot</Select.Option>
+ *   </Select.Group>
+ * </Select.Root>
+ * ```
+ *
+ * @see {@link SelectRoot} for state modes, placeholder integration, and `asChild`.
+ * @see {@link SelectPlaceholder} for the placeholder + `defaultValue` interaction.
+ */
+const SelectCompound: TSelectCompound = Object.assign(SelectRoot, {
+  Root: SelectRoot,
+  Option: SelectOption,
+  Group: SelectGroup,
+  Placeholder: SelectPlaceholder,
+});
+
+SelectCompound.displayName = "Select";
+
+export { SelectCompound as Select };

package/src/Select/__tests__/Select.asChild.test.tsx

@@ -0,0 +1,36 @@
+import { ComponentProps, ReactNode } from "react";
+import { render, screen } from "@testing-library/react";
+
+import { Select } from "../Select";
+
+function StyledSelect({
+  children,
+  ...rest
+}: ComponentProps<"select"> & { children: ReactNode }) {
+  return (
+    <select {...rest} className="styled-select" data-testid="styled">
+      {children}
+    </select>
+  );
+}
+
+describe("Select asChild", () => {
+  it("delegates to a consumer-supplied <select> wrapper, merging Root's props onto it", () => {
+    // Arrange & Act
+    render(
+      <Select.Root asChild disabled>
+        <StyledSelect>
+          <Select.Option value="apple">Apple</Select.Option>
+        </StyledSelect>
+      </Select.Root>,
+    );
+
+    // Assert — the consumer's <select> is the rendered element, with
+    // Root's props merged in.
+    const select = screen.getByTestId("styled");
+    expect(select.tagName).toBe("SELECT");
+    expect(select).toHaveClass("styled-select");
+    expect(select).toHaveAttribute("data-disabled", "");
+    expect(select).toBeDisabled();
+  });
+});

package/src/Select/__tests__/Select.basic-rendering.test.tsx

@@ -0,0 +1,17 @@
+import { render, screen } from "@testing-library/react";
+
+import { Select } from "../Select";
+
+describe("Select basic rendering", () => {
+  it("renders an <option> for each Select.Option child so the value is in the DOM", () => {
+    // Arrange & Act
+    render(
+      <Select.Root>
+        <Select.Option value="apple">Apple</Select.Option>
+      </Select.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("option", { name: "Apple" })).toBeInTheDocument();
+  });
+});

package/src/Select/__tests__/Select.controlled-state.test.tsx

@@ -0,0 +1,69 @@
+import { useState } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Select } from "../Select";
+
+describe("Select controlled state", () => {
+  it("calls onValueChange with the new value string when the user selects a different option", async () => {
+    // Arrange
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+
+    function Wrapper() {
+      const [value, setValue] = useState("apple");
+      const handle = (next: string) => {
+        onValueChange(next);
+        setValue(next);
+      };
+      return (
+        <Select.Root value={value} onValueChange={handle}>
+          <Select.Option value="apple">Apple</Select.Option>
+          <Select.Option value="banana">Banana</Select.Option>
+        </Select.Root>
+      );
+    }
+
+    render(<Wrapper />);
+
+    // Act
+    await user.selectOptions(screen.getByRole("combobox"), "banana");
+
+    // Assert
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledWith("banana");
+  });
+
+  it("invokes the consumer's own onChange handler alongside onValueChange", async () => {
+    // Arrange
+    const onChange = vi.fn();
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+
+    function Wrapper() {
+      const [value, setValue] = useState("apple");
+      return (
+        <Select.Root
+          value={value}
+          onChange={(event) => {
+            onChange(event.target.value);
+            setValue(event.target.value);
+          }}
+          onValueChange={onValueChange}
+        >
+          <Select.Option value="apple">Apple</Select.Option>
+          <Select.Option value="banana">Banana</Select.Option>
+        </Select.Root>
+      );
+    }
+
+    render(<Wrapper />);
+
+    // Act
+    await user.selectOptions(screen.getByRole("combobox"), "banana");
+
+    // Assert
+    expect(onChange).toHaveBeenCalledWith("banana");
+    expect(onValueChange).toHaveBeenCalledWith("banana");
+  });
+});

package/src/Select/__tests__/Select.data-attributes.test.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from "@testing-library/react";
+
+import { Select } from "../Select";
+
+describe("Select data attributes", () => {
+  it("renders data-disabled='' on the root <select> when disabled is true so CSS can style the disabled state", () => {
+    // Arrange & Act
+    render(
+      <Select.Root disabled>
+        <Select.Option value="apple">Apple</Select.Option>
+      </Select.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox")).toHaveAttribute("data-disabled", "");
+  });
+
+  it("omits data-disabled entirely when disabled is false or absent so the enabled state has nothing to override", () => {
+    // Arrange & Act
+    render(
+      <Select.Root>
+        <Select.Option value="apple">Apple</Select.Option>
+      </Select.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox")).not.toHaveAttribute("data-disabled");
+  });
+});

package/src/Select/__tests__/Select.field-integration.test.tsx

@@ -0,0 +1,150 @@
+import { render, screen } from "@testing-library/react";
+
+import { Field } from "../../Field";
+import { Select } from "../Select";
+
+function renderSelect(children?: React.ReactNode) {
+  return (
+    <>
+      {children}
+      <Select.Option value="apple">Apple</Select.Option>
+      <Select.Option value="banana">Banana</Select.Option>
+    </>
+  );
+}
+
+describe("Select — Field integration", () => {
+  it("inherits the field id when no id prop is passed", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit">
+        <Select.Root aria-label="Fruit">{renderSelect()}</Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox", { name: "Fruit" })).toHaveAttribute(
+      "id",
+      "fruit",
+    );
+  });
+
+  it("consumer-supplied id wins over the field id", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit">
+        <Select.Root id="my-fruit" aria-label="Fruit">
+          {renderSelect()}
+        </Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox", { name: "Fruit" })).toHaveAttribute(
+      "id",
+      "my-fruit",
+    );
+  });
+
+  it("inherits aria-describedby pointing at the field's descriptionId", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit">
+        <Select.Root aria-label="Fruit">{renderSelect()}</Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox", { name: "Fruit" })).toHaveAttribute(
+      "aria-describedby",
+      "fruit-description",
+    );
+  });
+
+  it("includes the errorId in aria-describedby when the field is invalid", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit" invalid>
+        <Select.Root aria-label="Fruit">{renderSelect()}</Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(
+      screen
+        .getByRole("combobox", { name: "Fruit" })
+        .getAttribute("aria-describedby"),
+    ).toBe("fruit-description fruit-error");
+  });
+
+  it("appends consumer-supplied aria-describedby to the field-supplied ids", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit">
+        <Select.Root aria-label="Fruit" aria-describedby="extra-hint">
+          {renderSelect()}
+        </Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(
+      screen
+        .getByRole("combobox", { name: "Fruit" })
+        .getAttribute("aria-describedby"),
+    ).toBe("extra-hint fruit-description");
+  });
+
+  it("inherits aria-invalid='true' when the field is invalid", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit" invalid>
+        <Select.Root aria-label="Fruit">{renderSelect()}</Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox", { name: "Fruit" })).toHaveAttribute(
+      "aria-invalid",
+      "true",
+    );
+  });
+
+  it("inherits disabled from the field", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit" disabled>
+        <Select.Root aria-label="Fruit">{renderSelect()}</Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox", { name: "Fruit" })).toBeDisabled();
+  });
+
+  it("inherits required from the field", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="fruit" required>
+        <Select.Root aria-label="Fruit">{renderSelect()}</Select.Root>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("combobox", { name: "Fruit" })).toBeRequired();
+  });
+
+  it("Select outside Field.Root behaves identically to before — no field-derived attributes", () => {
+    // Arrange & Act
+    render(
+      <Select.Root aria-label="Fruit">{renderSelect()}</Select.Root>,
+    );
+    const select = screen.getByRole("combobox", { name: "Fruit" });
+
+    // Assert
+    expect(select).not.toHaveAttribute("aria-describedby");
+    expect(select).not.toHaveAttribute("aria-invalid");
+    expect(select).not.toHaveAttribute("disabled");
+    expect(select).not.toHaveAttribute("required");
+  });
+});

package/src/Select/__tests__/Select.group.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+
+import { Select } from "../Select";
+
+describe("Select group", () => {
+  it("renders an <optgroup> with the given label so options can be visually grouped", () => {
+    // Arrange & Act
+    render(
+      <Select.Root>
+        <Select.Group label="Fruits">
+          <Select.Option value="apple">Apple</Select.Option>
+          <Select.Option value="banana">Banana</Select.Option>
+        </Select.Group>
+        <Select.Group label="Vegetables">
+          <Select.Option value="carrot">Carrot</Select.Option>
+        </Select.Group>
+      </Select.Root>,
+    );
+
+    // Assert — native <optgroup> has implicit role="group" with the
+    // label attribute as its accessible name.
+    expect(screen.getByRole("group", { name: "Fruits" })).toBeInTheDocument();
+    expect(
+      screen.getByRole("group", { name: "Vegetables" }),
+    ).toBeInTheDocument();
+  });
+
+  it("nests its Option children inside the rendered <optgroup>", () => {
+    // Arrange & Act
+    render(
+      <Select.Root>
+        <Select.Group label="Fruits">
+          <Select.Option value="apple">Apple</Select.Option>
+        </Select.Group>
+      </Select.Root>,
+    );
+
+    // Assert
+    const option = screen.getByRole("option", { name: "Apple" });
+    expect(option.parentElement?.tagName).toBe("OPTGROUP");
+  });
+});

package/src/Select/__tests__/Select.placeholder.test.tsx

@@ -0,0 +1,32 @@
+import { render, screen } from "@testing-library/react";
+
+import { Select } from "../Select";
+
+describe("Select placeholder", () => {
+  it("renders a non-selectable placeholder option that holds the initial selection until the user picks something", () => {
+    // Arrange & Act
+    const { container } = render(
+      <Select.Root>
+        <Select.Placeholder>Choose a fruit…</Select.Placeholder>
+        <Select.Option value="apple">Apple</Select.Option>
+      </Select.Root>,
+    );
+
+    // Assert — placeholder is in the DOM with the attributes that make it
+    // unreachable from the dropdown after the first selection. The
+    // `hidden` attribute also pulls it out of the ARIA tree, so query the
+    // DOM directly rather than via getByRole.
+    const placeholder = container.querySelector(
+      "option[hidden]",
+    ) as HTMLOptionElement | null;
+    expect(placeholder).not.toBeNull();
+    expect(placeholder).toBeDisabled();
+    expect(placeholder).toHaveAttribute("value", "");
+    expect(placeholder).toHaveTextContent("Choose a fruit…");
+
+    // …and is the initial selection because it's the first option with an
+    // empty value.
+    const select = screen.getByRole("combobox") as HTMLSelectElement;
+    expect(select.value).toBe("");
+  });
+});

package/src/Select/index.ts

@@ -0,0 +1,2 @@
+export { Select } from "./Select";
+export * from "./types";

package/src/Select/types.ts

@@ -0,0 +1,89 @@
+import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
+
+type SelectRootBaseProps = Omit<
+  ComponentProps<"select">,
+  "value" | "defaultValue" | "multiple" | "onChange"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLSelectElement>;
+  /**
+   * Native `change` handler. Fires alongside `onValueChange` whenever the
+   * user picks a different option. Use this when you want the raw
+   * `ChangeEvent` (e.g. to inspect `event.target.validity`).
+   */
+  onChange?: ChangeEventHandler<HTMLSelectElement>;
+  /**
+   * When `true`, Root delegates to a single consumer-supplied element
+   * (expected to render a `<select>`) and merges its own props onto it
+   * via the {@link Slot} pattern. The placeholder-detection inside Root
+   * walks direct children only, so placeholder + `asChild` requires the
+   * consumer to set `defaultValue=""` explicitly.
+   */
+  asChild?: boolean;
+};
+
+type SelectRootUncontrolledProps = SelectRootBaseProps & {
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: (value: string) => void;
+};
+
+type SelectRootControlledProps = SelectRootBaseProps & {
+  defaultValue?: never;
+  value: string;
+  onValueChange: (value: string) => void;
+};
+
+/**
+ * Props for {@link Select.Root}.
+ *
+ * Two state modes are statically discriminated at the type level so only
+ * one shape is accepted by TypeScript:
+ *
+ * - **Uncontrolled** — pass `defaultValue` (or omit it). The browser owns
+ *   the selection state. `onValueChange` is optional.
+ * - **Controlled** — pass `value` and `onValueChange` together. The
+ *   parent owns the selection; the component defers every transition
+ *   back through the callback.
+ *
+ * Native `multiple`-selection mode is not supported in v1.
+ */
+export type SelectRootProps =
+  | SelectRootUncontrolledProps
+  | SelectRootControlledProps;
+
+/**
+ * Props for {@link Select.Option} — all `OptionHTMLAttributes` on the
+ * underlying `<option>` element, plus a typed `ref`.
+ */
+export type SelectOptionProps = ComponentProps<"option"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLOptionElement>;
+};
+
+/**
+ * Props for {@link Select.Group} — all `OptgroupHTMLAttributes` on the
+ * underlying `<optgroup>` element, plus a typed `ref`. `label` is
+ * required by the native element and is what assistive technology
+ * announces for the group.
+ */
+export type SelectGroupProps = ComponentProps<"optgroup"> & {
+  label: string;
+  children?: ReactNode;
+  ref?: Ref<HTMLOptGroupElement>;
+};
+
+/**
+ * Props for {@link Select.Placeholder}.
+ *
+ * `value`, `disabled`, and `hidden` are owned by the component — the
+ * placeholder always has `value=""`, is always disabled, and is always
+ * hidden from the dropdown — so they can't be set by the consumer.
+ */
+export type SelectPlaceholderProps = Omit<
+  ComponentProps<"option">,
+  "value" | "disabled" | "hidden"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLOptionElement>;
+};