@primitiv-ui/react 0.1.0

package/src/RadioGroup/__tests__/RadioGroup.roving-tabindex.test.tsx

@@ -0,0 +1,105 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { RadioGroup } from "../RadioGroup";
+
+describe("RadioGroup roving tabindex", () => {
+  it("puts only the first item in the tab sequence when nothing is selected", () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="green">Green</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+    expect(screen.getByRole("radio", { name: "Green" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+    expect(screen.getByRole("radio", { name: "Blue" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+  });
+
+  it("puts only the selected item in the tab sequence when one is selected", () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour" defaultValue="green">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="green">Green</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+    expect(screen.getByRole("radio", { name: "Green" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+    expect(screen.getByRole("radio", { name: "Blue" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+  });
+
+  it("moves the tab stop to a newly selected item", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="green">Green</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+    const red = screen.getByRole("radio", { name: "Red" });
+    const green = screen.getByRole("radio", { name: "Green" });
+    expect(red).toHaveAttribute("tabindex", "0");
+
+    // Act
+    await user.click(green);
+
+    // Assert
+    expect(red).toHaveAttribute("tabindex", "-1");
+    expect(green).toHaveAttribute("tabindex", "0");
+  });
+
+  it("tabs into the single home-base item and not the others", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <>
+        <button type="button">Before</button>
+        <RadioGroup.Root aria-label="Colour">
+          <RadioGroup.Item value="red">Red</RadioGroup.Item>
+          <RadioGroup.Item value="green">Green</RadioGroup.Item>
+          <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+        </RadioGroup.Root>
+        <button type="button">After</button>
+      </>,
+    );
+    screen.getByRole("button", { name: "Before" }).focus();
+
+    // Act
+    await user.tab();
+
+    // Assert: focus lands on the first radio (the home base)
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveFocus();
+
+    // Tabbing again escapes the group entirely — the other radios are
+    // skipped because their tabindex is -1.
+    await user.tab();
+    expect(screen.getByRole("button", { name: "After" })).toHaveFocus();
+  });
+});

package/src/RadioGroup/__tests__/RadioGroup.uncontrolled-state.test.tsx

@@ -0,0 +1,96 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { RadioGroup } from "../RadioGroup";
+
+describe("RadioGroup uncontrolled state", () => {
+  it("reflects defaultValue on mount", () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour" defaultValue="blue">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+    expect(screen.getByRole("radio", { name: "Blue" })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+    expect(screen.getByRole("radio", { name: "Blue" })).toHaveAttribute(
+      "data-state",
+      "checked",
+    );
+  });
+
+  it("selects an item on click and un-selects the previous one", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <RadioGroup.Root aria-label="Colour" defaultValue="red">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+    const red = screen.getByRole("radio", { name: "Red" });
+    const blue = screen.getByRole("radio", { name: "Blue" });
+    expect(red).toHaveAttribute("aria-checked", "true");
+
+    // Act
+    await user.click(blue);
+
+    // Assert
+    expect(red).toHaveAttribute("aria-checked", "false");
+    expect(blue).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("fires onValueChange with the new value on every distinct selection", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioGroup.Root aria-label="Colour" onValueChange={onValueChange}>
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Red" }));
+    await user.click(screen.getByRole("radio", { name: "Blue" }));
+
+    // Assert
+    expect(onValueChange).toHaveBeenNthCalledWith(1, "red");
+    expect(onValueChange).toHaveBeenNthCalledWith(2, "blue");
+  });
+
+  it("does not re-fire onValueChange when the already-selected item is clicked again", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioGroup.Root
+        aria-label="Colour"
+        defaultValue="red"
+        onValueChange={onValueChange}
+      >
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Red" }));
+    await user.click(screen.getByRole("radio", { name: "Red" }));
+
+    // Assert: the selection is already "red"; onValueChange should
+    // stay quiet because nothing actually changed.
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+});

package/src/RadioGroup/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useRadioGroupContext } from "./useRadioGroupContext";
+export { useRadioGroupItemContext } from "./useRadioGroupItemContext";
+export { useRadioGroupRoot } from "./useRadioGroupRoot";

package/src/RadioGroup/hooks/useRadioGroupContext.ts

@@ -0,0 +1 @@
+export { useRadioGroupContext } from "../RadioGroupContext";

package/src/RadioGroup/hooks/useRadioGroupItemContext.ts

@@ -0,0 +1 @@
+export { useRadioGroupItemContext } from "../RadioGroupItemContext";

package/src/RadioGroup/hooks/useRadioGroupRoot.ts

@@ -0,0 +1,87 @@
+import { useCallback, useMemo } from "react";
+
+import { useCollection, useControllableState } from "../../hooks";
+
+type UseRadioGroupRootArgs = {
+  defaultValue?: string;
+  value?: string;
+  onValueChange?: (value: string) => void;
+};
+
+type ItemMeta = {
+  element: HTMLButtonElement;
+  disabled: boolean;
+};
+
+export function useRadioGroupRoot({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+}: UseRadioGroupRootArgs) {
+  const [value, setValue] = useControllableState<string>(
+    controlledValue,
+    defaultValue,
+    onValueChange,
+  );
+
+  const select = useCallback(
+    (next: string) => {
+      if (value === next) return;
+      setValue(next);
+    },
+    [value, setValue],
+  );
+
+  // Track registered item metadata in a ref (for focus handling) and
+  // their ordered values as state — required for the roving-tabindex
+  // home base. Disabled values are derived per render from itemsRef:
+  // any change that affects the set (mount, unmount, disabled toggle)
+  // already re-runs the registrar effect, which updates the keys state
+  // and forces the re-render that recomputes the memo.
+  const {
+    register: registerItemBase,
+    itemsRef,
+    keys: itemValues,
+  } = useCollection<string, ItemMeta>();
+
+  const registerItem = useCallback(
+    (
+      itemValue: string,
+      element: HTMLButtonElement | null,
+      disabled = false,
+    ) => {
+      registerItemBase(itemValue, element ? { element, disabled } : null);
+    },
+    [registerItemBase],
+  );
+
+  const disabledValues = useMemo(
+    () =>
+      new Set(
+        Array.from(itemsRef.current.entries())
+          .filter(([, meta]) => meta.disabled)
+          .map(([v]) => v),
+      ),
+    // itemValues is a fresh array on every register call (new identity even
+    // when the keys are the same), so the memo re-runs whenever any item
+    // mounts, unmounts, or toggles disabled — which is exactly the trigger
+    // we want for re-deriving disabledValues.
+    [itemValues, itemsRef],
+  );
+
+  const focusItem = useCallback(
+    (itemValue: string) => {
+      itemsRef.current.get(itemValue)?.element.focus();
+    },
+    [itemsRef],
+  );
+
+  return {
+    value,
+    select,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+  };
+}

package/src/RadioGroup/index.ts

@@ -0,0 +1 @@
+export * from "./RadioGroup";

package/src/RadioGroup/types.ts

@@ -0,0 +1,51 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+/**
+ * Which arrow keys navigate the group. `"both"` (default) accepts all
+ * four; `"horizontal"` only Arrow Left/Right; `"vertical"` only Arrow
+ * Up/Down.
+ */
+export type RadioGroupOrientation = "horizontal" | "vertical" | "both";
+
+/** Reading direction — swaps the horizontal arrow pair when `"rtl"`. */
+export type RadioGroupReadingDirection = "ltr" | "rtl";
+
+type RadioGroupRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
+  asChild?: boolean;
+  orientation?: RadioGroupOrientation;
+  dir?: RadioGroupReadingDirection;
+};
+
+type RadioGroupRootUncontrolledProps = RadioGroupRootBaseProps & {
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: (value: string) => void;
+};
+
+type RadioGroupRootControlledProps = RadioGroupRootBaseProps & {
+  defaultValue?: never;
+  value: string;
+  onValueChange: (value: string) => void;
+};
+
+export type RadioGroupRootProps =
+  | RadioGroupRootUncontrolledProps
+  | RadioGroupRootControlledProps;
+
+export type RadioGroupItemProps = Omit<
+  ComponentProps<"button">,
+  "type" | "role" | "aria-checked" | "value"
+> & {
+  value: string;
+  children?: ReactNode;
+  ref?: Ref<HTMLButtonElement>;
+  asChild?: boolean;
+};
+
+export type RadioGroupIndicatorProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+  forceMount?: boolean;
+  asChild?: boolean;
+};

package/src/Select/README.md

@@ -0,0 +1,203 @@
+# Select
+
+Headless **Select** — a compound component wrapping the native
+`<select>` / `<option>` / `<optgroup>` elements. Zero styles ship.
+
+```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.Option value="cherry">Cherry</Select.Option>
+</Select.Root>;
+```
+
+Because the underlying element is the real `<select>`, the browser owns
+the popup, the keyboard interaction (arrow keys, Home/End, typeahead),
+the mobile UX (iOS/Android wheel pickers), and form submission. No
+positioning JS, no Portal, no anchor positioning.
+
+## Sub-components
+
+| Export                | Element      | ARIA / data hooks                                  | `asChild` |
+| --------------------- | ------------ | -------------------------------------------------- | --------- |
+| `Select.Root`         | `<select>`   | implicit `role="combobox"`, `data-disabled`        | yes       |
+| `Select.Option`       | `<option>`   | implicit `role="option"`                           | —         |
+| `Select.Group`        | `<optgroup>` | implicit `role="group"`, `label` as accessible name | —         |
+| `Select.Placeholder`  | `<option>`   | always `value=""`, `disabled`, `hidden`            | —         |
+
+## State modes
+
+### Uncontrolled
+
+Pass `defaultValue` (or omit it). The browser owns the selection.
+`onValueChange` is optional.
+
+```tsx
+<Select.Root defaultValue="banana" aria-label="Pick a fruit">
+  <Select.Option value="apple">Apple</Select.Option>
+  <Select.Option value="banana">Banana</Select.Option>
+</Select.Root>
+```
+
+### Controlled
+
+Pass `value` and `onValueChange` together. The parent owns the
+selection; the component defers every transition back through the
+callback.
+
+```tsx
+const [fruit, setFruit] = useState("apple");
+
+<Select.Root value={fruit} onValueChange={setFruit} aria-label="…">
+  <Select.Option value="apple">Apple</Select.Option>
+  <Select.Option value="banana">Banana</Select.Option>
+</Select.Root>;
+```
+
+`onValueChange` receives the new selection as a plain string. The
+consumer's own `onChange` (the raw `ChangeEvent`) still fires alongside
+it if provided.
+
+## Placeholder
+
+`Select.Placeholder` renders a non-selectable hint that holds the
+initial selection. The underlying option is rendered with `value=""`,
+`disabled`, and `hidden`, so it shows in the closed Select's display
+but is unreachable from the dropdown after the user picks something.
+
+```tsx
+<Select.Root required aria-label="Pick a fruit">
+  <Select.Placeholder>Choose a fruit…</Select.Placeholder>
+  <Select.Option value="apple">Apple</Select.Option>
+  <Select.Option value="banana">Banana</Select.Option>
+</Select.Root>
+```
+
+When a `Select.Placeholder` is among Root's direct children and neither
+`value` nor `defaultValue` is set, Root infers `defaultValue=""` so the
+placeholder — not the first selectable option — is the initial
+selection. Pair with `required` on Root to make the browser's native
+form validation catch an unchosen value at submit time.
+
+`asChild` on Root walks direct children only for this detection, so the
+`asChild` + Placeholder combination requires the consumer to set
+`defaultValue=""` explicitly.
+
+## Groups
+
+`Select.Group` wraps options in a native `<optgroup>` with a labelled,
+non-selectable heading.
+
+```tsx
+<Select.Root aria-label="Pick a food">
+  <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>
+```
+
+The `label` is announced as the group's accessible name by assistive
+technology.
+
+## Disabled
+
+Pass `disabled` on Root to disable the whole control, or on an
+individual `Select.Option` to disable that single choice. The native
+`disabled` attribute does the work; `data-disabled=""` is mirrored on
+the root `<select>` for CSS targeting.
+
+```tsx
+<Select.Root disabled aria-label="Pick a fruit">
+  <Select.Option value="apple">Apple</Select.Option>
+</Select.Root>
+
+<Select.Root aria-label="Pick a fruit">
+  <Select.Option value="apple">Apple</Select.Option>
+  <Select.Option value="durian" disabled>Durian (sold out)</Select.Option>
+</Select.Root>
+```
+
+## Field integration
+
+When rendered inside a [`<Field.Root>`](../Field/README.md),
+`Select.Root` reads `FieldContext` and inherits:
+
+- `id` (from `field.id`)
+- `aria-describedby` (composed: consumer ids first, then the field's
+  `descriptionId`, then `errorId` when invalid)
+- `aria-invalid` (`"true"` when the field is invalid)
+- `disabled`
+- `required`
+
+Consumer-supplied props always win — pass an explicit value on the
+`Select.Root` to override any field-derived one. Outside a `<Field.Root>`,
+behaviour is unchanged.
+
+```tsx
+<Field.Root invalid={!!errors.fruit}>
+  <Field.Label>Fruit</Field.Label>
+  <Select.Root {...register("fruit")}>
+    <Select.Placeholder>Choose a fruit…</Select.Placeholder>
+    <Select.Option value="apple">Apple</Select.Option>
+    <Select.Option value="banana">Banana</Select.Option>
+  </Select.Root>
+  <Field.ErrorText>{errors.fruit?.message}</Field.ErrorText>
+</Field.Root>
+```
+
+## Form integration
+
+Native `<select>` is a form-associated element. Pass `name` and
+`required`, place the Select inside a `<form>`, and submission carries
+the selected value with no extra wiring.
+
+```tsx
+<form onSubmit={…}>
+  <label>
+    Fruit
+    <Select.Root name="fruit" required>
+      <Select.Placeholder>Choose a fruit…</Select.Placeholder>
+      <Select.Option value="apple">Apple</Select.Option>
+    </Select.Root>
+  </label>
+  <button type="submit">Submit</button>
+</form>
+```
+
+## `asChild` composition
+
+Root accepts `asChild`. The consumer supplies a single element that
+renders a `<select>` (typically a styled wrapper). Root's `onChange`,
+`data-disabled`, `value` / `defaultValue`, and other native attributes
+are merged onto it.
+
+```tsx
+function StyledSelect(props: ComponentProps<"select">) {
+  return <select {...props} className="ds-select" />;
+}
+
+<Select.Root asChild value={fruit} onValueChange={setFruit}>
+  <StyledSelect>
+    <Select.Option value="apple">Apple</Select.Option>
+  </StyledSelect>
+</Select.Root>
+```
+
+## Styling hooks
+
+| Attribute       | Values                       | Set on        |
+| --------------- | ---------------------------- | ------------- |
+| `data-disabled` | `""` (present when disabled) | `Select.Root` |
+
+## Limitations
+
+Native `<select>` only renders text inside `<option>`. Rich item content
+(icons, descriptions, indicators) is not supported. A richer Select and
+a Combobox with filtering are planned — see [Future
+work](../../../../docs/select-future-work.md).