@primitiv-ui/react 0.1.27 → 0.1.29

package/src/SegmentedControl/hooks/useSegmentedControlRoot.ts

@@ -0,0 +1,86 @@
+import { useCallback, useMemo } from "react";
+
+import { useCollection, useControllableState } from "../../hooks/index.ts";
+
+type UseSegmentedControlRootArgs = {
+  defaultValue?: string;
+  value?: string;
+  onValueChange?: (value: string) => void;
+};
+
+type ItemMeta = {
+  element: HTMLButtonElement;
+  disabled: boolean;
+};
+
+export function useSegmentedControlRoot({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+}: UseSegmentedControlRootArgs) {
+  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) re-runs the registrar
+  // effect, which updates the keys state and forces the recompute.
+  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 unchanged), so the memo re-runs whenever any item
+    // mounts, unmounts, or toggles disabled — exactly the trigger we want.
+    [itemValues, itemsRef],
+  );
+
+  const focusItem = useCallback(
+    (itemValue: string) => {
+      // `itemValue` is always sourced from `navigable` (the enabled subset of
+      // `itemValues`), and useCollection's register() writes `itemsRef` and
+      // the `itemValues` state together — so a value that appears here is
+      // guaranteed to already have a live entry in the map.
+      // Stryker disable next-line OptionalChaining: unreachable given that invariant.
+      itemsRef.current.get(itemValue)?.element.focus();
+    },
+    [itemsRef],
+  );
+
+  return {
+    value,
+    select,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+  };
+}

package/src/SegmentedControl/index.ts

@@ -0,0 +1,2 @@
+export * from "./SegmentedControl";
+export * from "./types";

package/src/SegmentedControl/types.ts

@@ -0,0 +1,138 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+/**
+ * Layout axis of the control. `"horizontal"` (default) binds the
+ * Arrow Left/Right pair; `"vertical"` binds Arrow Up/Down. Also
+ * reflected as `aria-orientation` and `data-orientation` on the root.
+ */
+export type SegmentedControlOrientation = "horizontal" | "vertical";
+
+/** Reading direction — swaps the horizontal arrow pair when `"rtl"`. */
+export type SegmentedControlReadingDirection = "ltr" | "rtl";
+
+/**
+ * Shared base for both {@link SegmentedControlRootProps} variants — the
+ * native `<div>` attributes (minus the component-owned `role` and the
+ * narrowed `dir`) plus the `asChild` escape hatch, orientation, reading
+ * direction, group-level `disabled`, and a typed `ref`.
+ */
+export type SegmentedControlRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "role" | "dir" | "defaultValue"
+> & {
+  /** The control's segments — {@link SegmentedControlItemProps | `SegmentedControl.Item`}
+   * elements. */
+  children?: ReactNode;
+  /** Forwarded to the underlying `HTMLDivElement`. */
+  ref?: Ref<HTMLDivElement>;
+  /**
+   * When `true`, Root delegates rendering to a single consumer-supplied
+   * element via the {@link Slot} pattern instead of the default `<div>`;
+   * `role="radiogroup"`, `aria-orientation`, `data-orientation`,
+   * `data-disabled`, `dir`, and remaining props are merged onto it.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * Which arrow-key pair moves focus and selection through the segments,
+   * and the visual axis. `"horizontal"` binds Arrow Left/Right;
+   * `"vertical"` binds Arrow Up/Down. Reflected as `aria-orientation` and
+   * `data-orientation` on the root.
+   * @default "horizontal"
+   */
+  orientation?: SegmentedControlOrientation;
+  /**
+   * Reading direction. In `"rtl"` the horizontal arrow pair is swapped so
+   * Arrow Left moves forward. When omitted, it is inherited from the
+   * nearest {@link DirectionProvider}, falling back to `"ltr"`.
+   */
+  dir?: SegmentedControlReadingDirection;
+  /**
+   * Disables the entire control — every segment is non-interactive and
+   * excluded from arrow-key navigation, and `data-disabled=""` is set on
+   * the root. Individual segments can also be disabled via the Item's own
+   * `disabled` prop.
+   * @default false
+   */
+  disabled?: boolean;
+};
+
+/**
+ * Uncontrolled variant of {@link SegmentedControlRootProps}: the component
+ * owns the selected value. Pass `defaultValue` (or omit it); `onValueChange`
+ * is optional and `value` is forbidden.
+ */
+export type SegmentedControlRootUncontrolledProps =
+  SegmentedControlRootBaseProps & {
+    /** Value of the segment selected on first render. Omit for nothing
+     * selected on mount. */
+    defaultValue?: string;
+    /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
+    value?: never;
+    /** Called with the new value whenever the selection changes. Optional
+     * in uncontrolled mode. */
+    onValueChange?: (value: string) => void;
+  };
+
+/**
+ * Controlled variant of {@link SegmentedControlRootProps}: the parent owns
+ * the selected value. Pass `value` and `onValueChange` together;
+ * `defaultValue` is forbidden.
+ */
+export type SegmentedControlRootControlledProps =
+  SegmentedControlRootBaseProps & {
+    /** Forbidden in controlled mode — use `value` instead. */
+    defaultValue?: never;
+    /** The currently selected value. Must be kept in sync by the parent
+     * via `onValueChange`. */
+    value: string;
+    /** Called with the new value whenever the selection changes. Required
+     * in controlled mode. */
+    onValueChange: (value: string) => void;
+  };
+
+/**
+ * Props for {@link SegmentedControlRoot | `SegmentedControl.Root`}. A
+ * discriminated union of {@link SegmentedControlRootUncontrolledProps} and
+ * {@link SegmentedControlRootControlledProps}, so TypeScript accepts exactly
+ * one state mode.
+ */
+export type SegmentedControlRootProps =
+  | SegmentedControlRootUncontrolledProps
+  | SegmentedControlRootControlledProps;
+
+/**
+ * Props for {@link SegmentedControlItem | `SegmentedControl.Item`} — the
+ * segment button. `value` identifies the option; all native `<button>`
+ * attributes (minus the component-owned `type`, `role`, `aria-checked`, and
+ * `value`) plus the `asChild` escape hatch and a typed `ref` pass through.
+ */
+export type SegmentedControlItemProps = Omit<
+  ComponentProps<"button">,
+  "type" | "role" | "aria-checked" | "value"
+> & {
+  /** Uniquely identifies this segment within the control and is reported to
+   * `onValueChange` / matched against Root's `value` when selected. Required. */
+  value: string;
+  /** The segment's visible content — typically its text label. */
+  children?: ReactNode;
+  /** Forwarded to the underlying `HTMLButtonElement`. */
+  ref?: Ref<HTMLButtonElement>;
+  /**
+   * Disables just this segment: forwards the native `disabled` attribute,
+   * removes it from arrow-key navigation and the roving-tabindex home base,
+   * and sets `data-disabled=""`. The whole control can also be disabled via
+   * Root's `disabled` prop.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * When `true`, renders the single child element via the {@link Slot}
+   * pattern instead of the default `<button>`; ARIA, `data-state`,
+   * `data-disabled`, `tabIndex`, `onClick`, `onKeyDown`, `disabled`, and
+   * `ref` are merged onto it. A non-focusable child must be made focusable
+   * by the consumer.
+   * @default false
+   */
+  asChild?: boolean;
+};

package/src/Select/README.md

@@ -1,203 +1,168 @@
 # Select
 
-Headless **Select** — a compound component wrapping the native
-`<select>` / `<option>` / `<optgroup>` elements. Zero styles ship.
+Headless **Select** — a single-select compound with two render paths chosen
+by the `native` prop:
+
+- **Rich** (`native={false}`, the default) — a fully-styleable Popover-API
+  listbox (`Select.Trigger` / `Select.Value` / `Select.Content` /
+  `Select.Item` / `Select.ItemIndicator`). Items carry arbitrary content
+  (icons, badges, indicators).
+- **Native** (`native={true}`) — a thin wrapper over a real `<select>` /
+  `<option>` / `<optgroup>` for flat, OS-native cases (mobile wheel pickers,
+  maximum-compatibility forms).
+
+Both modes share the same `value` / `onValueChange` / `disabled` / `name`
+(form) API. 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>
+// Rich (default)
+<Select.Root value={framework} onValueChange={setFramework}>
+  <Select.Trigger>
+    <Select.Value placeholder="Pick a framework…" />
+  </Select.Trigger>
+  <Select.Content>
+    <Select.Item value="react">
+      <ReactIcon />
+      React
+      <Select.ItemIndicator>✓</Select.ItemIndicator>
+    </Select.Item>
+    <Select.Item value="vue">
+      <VueIcon />
+      Vue
+      <Select.ItemIndicator>✓</Select.ItemIndicator>
+    </Select.Item>
+  </Select.Content>
 </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`            | —         |
+| Export                 | Rich element             | Native element | Notes                                          |
+| ---------------------- | ------------------------ | -------------- | ---------------------------------------------- |
+| `Select.Root`          | context boundary + hidden `<select>` | `<select>` | owns value + open state                        |
+| `Select.Trigger`       | `<button>`               | —              | `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`; `asChild` |
+| `Select.Value`         | `<span>`                 | —              | mirrors the selected item's content            |
+| `Select.Content`       | `<div role="listbox">` (`popover="auto"`) | — | keyboard nav; `asChild`                        |
+| `Select.Item`          | `<div role="option">`    | `<option>`     | `value` (required), `disabled`                 |
+| `Select.ItemIndicator` | `<span>`                 | —              | selected-only; `forceMount`, `asChild`         |
+| `Select.Group`         | `<div role="group">`     | `<optgroup>`   | `label` (required string)                      |
+| `Select.Separator`     | `<div role="separator">` | —              | rich-only divider; skipped by keyboard nav; `asChild` |
+| `Select.Placeholder`   | —                        | `<option value="" hidden disabled>` | native-only initial hint      |
 
-## State modes
+## State
 
-### Uncontrolled
+**Selection** — controlled (`value` + `onValueChange`) or uncontrolled
+(`defaultValue`, or omit for none), discriminated at the type level so only
+one shape is accepted. `onValueChange` receives the new value as a string.
 
-Pass `defaultValue` (or omit it). The browser owns the selection.
-`onValueChange` is optional.
+**Open** (rich only) — controlled (`open` + `onOpenChange`) or uncontrolled
+(`defaultOpen`). The trigger toggles it; selection, Escape, and light-dismiss
+close it.
 
-```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>
-```
+## Rich mode
 
-### Controlled
+### Value mirroring
 
-Pass `value` and `onValueChange` together. The parent owns the
-selection; the component defers every transition back through the
-callback.
+`Select.Value` **automatically mirrors the selected `Select.Item`'s
+children** into the trigger — write the icon + label once, on the item, and
+it shows up in the closed trigger. `Select.ItemIndicator` is **excluded** from
+the mirror (the checkmark answers "which row is selected" — redundant on the
+trigger it already represents). `placeholder` shows when nothing is selected.
 
-```tsx
-const [fruit, setFruit] = useState("apple");
+The exclusion works **through your own wrappers**: the mirror doesn't test the
+element's type (a wrapper component would be opaque to that, and a styled layer
+always wraps), it publishes its intent through context and each indicator opts
+itself out — at any nesting depth, `forceMount` included. Every other child
+carries through untouched, so a trailing badge on the selected item shows up in
+the trigger too; style it there if it needs different spacing from the row.
 
-<Select.Root value={fruit} onValueChange={setFruit} aria-label="…">
-  <Select.Option value="apple">Apple</Select.Option>
-  <Select.Option value="banana">Banana</Select.Option>
-</Select.Root>;
-```
+### Item indicator
 
-`onValueChange` receives the new selection as a plain string. The
-consumer's own `onChange` (the raw `ChangeEvent`) still fires alongside
-it if provided.
+`Select.ItemIndicator`, nested in a `Select.Item`, renders **only when that
+item is selected** and exposes `data-state="checked" | "unchecked"`. Pass
+`forceMount` to keep it in the DOM (as `unchecked`) for CSS enter/exit
+animation.
 
-## Placeholder
+### Keyboard
 
-`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.
+While the listbox is open:
 
-```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>
-```
+| Key                     | Behaviour                                          |
+| ----------------------- | -------------------------------------------------- |
+| `ArrowDown` / `ArrowUp` | Move focus to next / previous option (wraps)       |
+| `Home` / `End`          | First / last option                                |
+| `Enter` / `Space`       | Select the focused option and close                |
+| `Escape`                | Close and return focus to the trigger              |
+| printable character     | Typeahead — focus the next option matching prefix  |
 
-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.
+Disabled options are skipped by arrows and typeahead. On open, focus moves to
+the selected option (or the first enabled one).
 
-`asChild` on Root walks direct children only for this detection, so the
-`asChild` + Placeholder combination requires the consumer to set
-`defaultValue=""` explicitly.
+### Popup placement
 
-## Groups
+`Select.Content` uses the native Popover API (`popover="auto"`) for the top
+layer and light-dismiss — no Portal, no positioning JS. Consumers place the
+popup themselves via CSS (the component ships no anchor positioning).
 
-`Select.Group` wraps options in a native `<optgroup>` with a labelled,
-non-selectable heading.
+## Native mode
+
+Pass `native` to render a real `<select>`. `Select.Item` becomes an
+`<option>` — keeping **only its string/number children** as the option text
+and **dropping element children** (icons, indicators don't render). An
+icon-only item with no text renders an empty, unlabelled `<option>`.
 
 ```tsx
-<Select.Root aria-label="Pick a food">
+<Select.Root native defaultValue="apple" aria-label="Pick a fruit">
+  <Select.Placeholder>Choose a fruit…</Select.Placeholder>
   <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.Item value="apple">Apple</Select.Item>
+    <Select.Item value="banana">Banana</Select.Item>
   </Select.Group>
 </Select.Root>
 ```
 
-The `label` is announced as the group's accessible name by assistive
-technology.
-
-## Disabled
+`Select.Placeholder` (native-only) renders `<option value="" disabled hidden>`.
+When present with no `value`/`defaultValue`, Root infers `defaultValue=""` so
+the placeholder is the initial selection; pair with `required` for native form
+validation. `Select.Group` renders `<optgroup label>`.
 
-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.
+## Forms
 
-```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>
-```
+Pass `name` and place the Select in a `<form>`. In native mode the `<select>`
+submits directly; in rich mode Root renders a visually-hidden native
+`<select name>` that carries the value, so submission works identically. Pair
+with `required` for browser validation.
 
 ## 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
+Inside a [`<Field.Root>`](../Field/README.md), `Select.Root` reads
+`FieldContext` and inherits `id`, `aria-describedby`, `aria-invalid`,
+`disabled`, and `required` (consumer props win). In native mode these apply to
+the `<select>`; in rich mode `disabled` / `required` / `name` flow to the
+hidden form `<select>`.
 
-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.
+## `asChild`
 
-```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>
-```
+- `Select.Root` (native mode) — delegate to a styled `<select>` wrapper.
+- `Select.Trigger` / `Select.Content` / `Select.ItemIndicator` (rich mode) —
+  compose the merged props onto a consumer element.
 
 ## Styling hooks
 
-| Attribute       | Values                       | Set on        |
-| --------------- | ---------------------------- | ------------- |
-| `data-disabled` | `""` (present when disabled) | `Select.Root` |
+| Attribute       | Values                          | Set on                 |
+| --------------- | ------------------------------- | ---------------------- |
+| `aria-expanded` | `"true"` / `"false"`            | `Select.Trigger`       |
+| `aria-selected` | `"true"` / `"false"`            | rich `Select.Item`     |
+| `data-state`    | `"checked"` / `"unchecked"`     | rich `Select.Item`, `Select.ItemIndicator` |
+| `data-disabled` | `""` (present when disabled)    | rich `Select.Item`, native `Select.Root` |
+| `data-placeholder` | `""` (present while nothing is selected) | `Select.Value` |
+
+`data-placeholder` is what a styled layer keys the muted placeholder colour
+off — it disappears the moment an item's content is mirrored into the trigger.
 
-## Limitations
+## Future work
 
-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).
+A Combobox with filtering is planned — see
+[Future work](../../../../docs/select-future-work.md).