@primitiv-ui/react 0.1.29 → 0.1.30

package/src/Slider/README.md

@@ -10,11 +10,11 @@ styles ship.
 ```tsx
 import { Slider } from "@primitiv-ui/react";
 
-<Slider.Root defaultValue={[40]} aria-label="Volume">
+<Slider.Root defaultValue={[40]}>
   <Slider.Track>
     <Slider.Range />
   </Slider.Track>
-  <Slider.Thumb />
+  <Slider.Thumb aria-label="Volume" />
 </Slider.Root>
 ```
 
@@ -56,12 +56,12 @@ Pass `defaultValue` (or omit it for a single thumb seeded at `min`). The
 component owns the value internally.
 
 ```tsx
-<Slider.Root defaultValue={[25, 75]} aria-label="Price range">
+<Slider.Root defaultValue={[25, 75]}>
   <Slider.Track>
     <Slider.Range />
   </Slider.Track>
-  <Slider.Thumb />
-  <Slider.Thumb />
+  <Slider.Thumb aria-label="Minimum" />
+  <Slider.Thumb aria-label="Maximum" />
 </Slider.Root>
 ```
 
@@ -92,10 +92,40 @@ only the final value.
   defaultValue={[40]}
   onValueCommit={(value) => save(value)}
 >
-  …
+  ...
 </Slider.Root>
 ```
 
+## Labelling
+
+**The accessible name goes on the `Thumb`, not the Root.** The Thumb is the
+`role="slider"`; the Root renders a plain `<span>` with no role, so an
+`aria-label` there is attached to nothing and announced nowhere. It is a silent
+failure — the slider still looks and behaves correctly — and the examples in this
+file used to model it.
+
+```tsx
+<Slider.Thumb aria-label="Volume" />
+```
+
+For a **visible** label, give it an id and point the thumb at it. A
+`<label htmlFor>` cannot associate with a `<span role="slider">`, and `Slider`
+does not read `FieldContext` (only `Input`, `Textarea` and `Select` do) — so a
+`Field.Label` does not reach the thumb on its own:
+
+```tsx
+<Field.Root>
+  <Field.Label id="volume-label">Volume</Field.Label>
+  <Slider.Root defaultValue={[40]}>
+    <Slider.Track><Slider.Range /></Slider.Track>
+    <Slider.Thumb aria-labelledby="volume-label" />
+  </Slider.Root>
+</Field.Root>
+```
+
+On a range, name each thumb separately — two thumbs sharing one label are
+announced identically, so you cannot tell by ear which end you are on.
+
 ## Keyboard interaction
 
 Each thumb is independently focusable.
@@ -141,7 +171,7 @@ surrounding `<form>`. Multi-thumb sliders suffix the name with `[]`
 ```tsx
 <form>
   <Slider.Root defaultValue={[10, 90]} name="price">
-    …
+    ...
   </Slider.Root>
 </form>
 ```

package/src/Slider/Slider.tsx

@@ -330,18 +330,24 @@ export type TSliderCompound = typeof SliderRoot & {
  * - {@link SliderRange | `Slider.Range`} — the filled portion of the track.
  * - {@link SliderThumb | `Slider.Thumb`} — a draggable handle; one per value.
  *
+ * The accessible name belongs on the **Thumb**, which is the `role="slider"`.
+ * The Root renders a plain `<span>` with no role, so an `aria-label` there is
+ * attached to nothing and announced nowhere — a silent failure, because the
+ * slider still looks and behaves correctly. This example used to put it on the
+ * Root.
+ *
  * @example
  * ```tsx
  * import { Slider } from "@primitiv-ui/react";
  *
- * <Slider.Root defaultValue={[40]} aria-label="Volume">
+ * <Slider.Root defaultValue={[40]}>
  *   <Slider.Track><Slider.Range /></Slider.Track>
- *   <Slider.Thumb />
+ *   <Slider.Thumb aria-label="Volume" />
  * </Slider.Root>
  * ```
  *
  * @see {@link SliderRoot} for state modes, form submission, and validation.
- * @see {@link SliderThumb} for keyboard interaction.
+ * @see {@link SliderThumb} for keyboard interaction and labelling.
  */
 const SliderCompound: TSliderCompound = Object.assign(SliderRoot, {
   Root: SliderRoot,

package/src/Slot/Slot.tsx

@@ -138,7 +138,7 @@ function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
  * data attributes, event handlers, and `ref` all still land on the
  * rendered DOM node, just not the node `Slot` itself would have created.
  * The pattern avoids an extra wrapper element in the DOM, which matters for
- * layout (no unwanted `<button><a>…</a></button>` nesting) and for CSS
+ * layout (no unwanted `<button><a>...</a></button>` nesting) and for CSS
  * selectors that expect a single element.
  *
  * **Usage shape** — every component using `Slot` follows the same
@@ -205,7 +205,7 @@ function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
  *     Settings
  *   </RouterLink>
  * </Button>
- * // Rendered DOM: a single <a class="…settings-link"> — trackClick and the
+ * // Rendered DOM: a single <a class="...settings-link"> — trackClick and the
  * // link's own onClick both fire; no wrapping <button>.
  * ```
  */

package/src/Slot/__tests__/Slot.test.tsx

@@ -132,8 +132,8 @@ describe("Slot tests", () => {
       const baseElement = React.createElement("div", null, "text");
       const react18Element = {
         ...baseElement,
-        ref: childRef, // React ≤18: ref lives here …
-        props: { children: "text" }, // … not in props
+        ref: childRef, // React ≤18: ref lives here ...
+        props: { children: "text" }, // ... not in props
       } as unknown as React.ReactElement;
       const SlotWithRef = React.forwardRef<HTMLElement>((_props, ref) => (
         <Slot ref={ref}>{react18Element}</Slot>

package/src/Slot/types.ts

@@ -2,7 +2,7 @@ import { HTMLAttributes, ReactNode } from "react";
 
 /**
  * Props for {@link Slot} — all native `HTMLAttributes` (event handlers,
- * `style`, `className`, `aria-*`, `data-*`, …), merged onto the single
+ * `style`, `className`, `aria-*`, `data-*`, ...), merged onto the single
  * child element rather than rendered onto an element `Slot` creates
  * itself. See {@link Slot} for the exact prop-merging rules (event
  * handlers compose child-first, `style` shallow-merges child-wins,

package/src/SplitButton/README.md

@@ -0,0 +1,225 @@
+# SplitButton
+
+One primary action paired with a menu of related alternatives, bound into
+a single `role="group"` widget. Zero styles ship.
+
+```tsx
+import { SplitButton, VisuallyHidden } from "@primitiv-ui/react";
+
+<SplitButton>
+  <SplitButton.Action onClick={squashAndMerge}>
+    Squash and merge
+  </SplitButton.Action>
+  <SplitButton.Trigger>
+    <ChevronDown aria-hidden="true" />
+    <VisuallyHidden>More merge options</VisuallyHidden>
+  </SplitButton.Trigger>
+  <SplitButton.Menu>
+    <SplitButton.Item onSelect={mergeCommit}>
+      Create a merge commit
+    </SplitButton.Item>
+    <SplitButton.Item onSelect={rebase}>Rebase and merge</SplitButton.Item>
+  </SplitButton.Menu>
+</SplitButton>;
+```
+
+## Split button, not select
+
+A `Select` answers *"which option is currently selected?"* — picking an
+item changes a **value**. A split button is an **actions** control: the
+left half runs the default action immediately, and the right half opens a
+menu of alternatives. Those alternatives may run their own action, or
+re-point what the primary half does next; either way nothing about the
+widget models a selected value.
+
+If you want a value picker, use [`Select`](../Select/README.md). If you
+want a plain menu button with no default action, use
+[`Dropdown`](../Dropdown/README.md) on its own.
+
+## Sub-components
+
+| Export                   | Element                    | Role         | Notes                                                                   |
+| ------------------------ | -------------------------- | ------------ | ----------------------------------------------------------------------- |
+| `SplitButton` / `.Root`  | `<div>`                    | `group`      | Owns the menu's open state; uncontrolled (`defaultOpen`) or controlled   |
+| `SplitButton.Action`     | `<button type="button">`   | `button`     | The primary action; `ArrowDown` opens the menu                          |
+| `SplitButton.Trigger`    | `<button type="button">`   | `button`     | `aria-haspopup="menu"`; name derived from the action                    |
+| `SplitButton.Menu`       | `<menu popover="auto">`    | `menu`       | The panel of alternatives                                               |
+| `SplitButton.Item`       | `<div>`                    | `menuitem`   | One alternative action, with `onSelect`                                 |
+| `SplitButton.Separator`  | `<div>`                    | `separator`  | Divider between groups of alternatives                                  |
+
+`Root`, `Action` and the group accept `asChild`; `Trigger`, `Menu`,
+`Item` and `Separator` inherit `asChild` from the Dropdown parts they
+delegate to.
+
+## Anatomy and styling hooks
+
+| Part          | Hook                                                   |
+| ------------- | ------------------------------------------------------ |
+| Root          | `data-split-button=""`, `data-state="open" \| "closed"` |
+| Action        | `data-split-button-action=""`                          |
+| Trigger       | `data-split-button-trigger=""`                          |
+| Menu          | `data-split-button-menu=""`                            |
+| Any disabled  | `data-disabled=""`                                     |
+
+`data-state` on the **root** tracks the menu, which is what makes the
+seam between the two halves styleable while the menu is open (a pressed
+chevron, a joined border) without reaching for `:has()`.
+
+## What this component adds over `Dropdown`
+
+The menu half *is* a `Dropdown` — Root renders a `Dropdown.Root`, and
+`Menu` / `Item` / `Separator` delegate to `Dropdown.Content` / `.Item` /
+`.Separator`. All the arrow-key navigation, typeahead, Escape handling,
+light dismiss and focus restoration are Dropdown's, tested once over
+there.
+
+What `SplitButton` owns is the coordination **between the two halves**,
+which is the whole reason it exists as a primitive rather than a styled
+recipe:
+
+1. **The `role="group"` boundary** — assistive technology reads two
+   buttons as one widget rather than two unrelated commands.
+2. **The trigger's accessible name, derived from the action** — see
+   below. This is the thing hand-rolled split buttons get wrong most
+   often.
+3. **`disabled` propagation** — one prop on the group disables both
+   halves; it is OR-ed with each half's own `disabled`, so a part can
+   never override the group back to enabled.
+4. **`ArrowDown` on the action opens the menu** — the action is *not*
+   the menu trigger, so nothing in `Dropdown` wires this. Note this
+   affordance is specific to `SplitButton`; `Dropdown.Trigger` itself
+   opens on click/Enter/Space only.
+
+## The derived accessible name
+
+A chevron-only control has no text of its own. Unless you pass
+`aria-label` or `aria-labelledby`, `SplitButton.Trigger` defaults to:
+
+```
+aria-labelledby="<the trigger's own id> <the action's id>"
+```
+
+Self-reference is valid in `aria-labelledby` and resolves to the
+element's own contents, so putting visually-hidden text inside the
+trigger produces *"More merge options, Squash and merge"*:
+
+```tsx
+<SplitButton.Trigger>
+  <ChevronDown aria-hidden="true" />
+  <VisuallyHidden>More merge options</VisuallyHidden>
+</SplitButton.Trigger>
+```
+
+With no text inside the trigger at all, the name falls back to just the
+action's label — ambiguous, but still better than an unlabelled button.
+Passing either ARIA attribute yourself opts out of the derivation
+completely:
+
+```tsx
+<SplitButton.Trigger aria-label="More merge options">
+  <ChevronDown aria-hidden="true" />
+</SplitButton.Trigger>
+```
+
+Because the derivation depends on both ids, **`id` is component-owned on
+`Action` and `Trigger`** and is `Omit`-ted from their prop types. Each
+id is derived from the root's `useId()` with a stable `-split-button-action`
+/ `-split-button-trigger` suffix.
+
+## Keyboard interaction
+
+| Key                     | On                | Behaviour                                        |
+| ----------------------- | ----------------- | ------------------------------------------------ |
+| `Enter` / `Space`       | Action            | Runs the primary action (native button)          |
+| `ArrowDown`             | Action            | Opens the menu, focusing its first item          |
+| `Enter` / `Space`       | Trigger           | Toggles the menu                                 |
+| `ArrowDown` / `ArrowUp` | Menu              | Moves between items (wraps)                      |
+| `Home` / `End`          | Menu              | First / last enabled item                        |
+| printable characters    | Menu              | Typeahead                                        |
+| `Escape`                | Menu              | Closes and returns focus to the trigger          |
+
+**Both halves are separate tab stops.** They are two genuinely distinct
+commands, so each is independently tabbable — this is deliberately *not*
+a roving-tabindex widget, and shouldn't become one. (Contrast
+`NavigationMenu`, which uses the roving-tabindex hook for its keymap only,
+for the same underlying reason.)
+
+## State modes
+
+Identical to `Dropdown.Root`'s, and statically discriminated at the type
+level:
+
+- **Uncontrolled** — pass `defaultOpen` (or omit it to start closed).
+  Optional `onOpenChange` observes user-driven transitions.
+- **Controlled** — pass `open` and `onOpenChange` together.
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<SplitButton open={open} onOpenChange={setOpen}>
+  ...
+</SplitButton>;
+```
+
+## Disabled
+
+```tsx
+{/* Both halves disabled */}
+<SplitButton disabled>...</SplitButton>
+
+{/* Only the action — alternatives stay reachable */}
+<SplitButton.Action disabled>Squash and merge</SplitButton.Action>
+
+{/* Only the menu — the default action still works */}
+<SplitButton.Trigger disabled aria-label="More merge options" />
+```
+
+## Richer menus
+
+`SplitButton` re-exports only the two menu parts a split button almost
+always needs. Root provides the same Dropdown context, so every other
+`Dropdown` part composes inside `SplitButton.Menu` directly:
+
+```tsx
+import { Dropdown, SplitButton } from "@primitiv-ui/react";
+
+<SplitButton.Menu>
+  <Dropdown.Group>
+    <Dropdown.Label>Merge strategy</Dropdown.Label>
+    <SplitButton.Item onSelect={mergeCommit}>
+      Create a merge commit
+    </SplitButton.Item>
+  </Dropdown.Group>
+  <SplitButton.Separator />
+  <Dropdown.Sub>
+    <Dropdown.SubTrigger>Advanced</Dropdown.SubTrigger>
+    <Dropdown.SubContent>
+      <SplitButton.Item onSelect={rebase}>Rebase and merge</SplitButton.Item>
+    </Dropdown.SubContent>
+  </Dropdown.Sub>
+</SplitButton.Menu>;
+```
+
+`dir` on `SplitButton.Root` is forwarded to the Dropdown, so submenus
+invert their open/close arrow keys in RTL.
+
+## `asChild`
+
+```tsx
+{/* The group is a <section> */}
+<SplitButton asChild>
+  <section aria-label="Merge">...</section>
+</SplitButton>
+
+{/* The primary action navigates instead of firing a handler.
+    type="button" is not forwarded in asChild mode. */}
+<SplitButton.Action asChild>
+  <a href="/merge">Squash and merge</a>
+</SplitButton.Action>
+```
+
+## Positioning
+
+Like `Dropdown`, the menu is a native `popover="auto"` element in the top
+layer — placement is the consumer's CSS concern (CSS anchor positioning,
+as the registry `dropdown` component does).