@primitiv-ui/react 0.1.28 → 0.1.30

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>
@@ -159,5 +159,115 @@ describe("Slot tests", () => {
       // Assert
       expect(screen.getByText("text")).toHaveClass("slot-class", "child-class");
     });
+
+    it("drops a falsy className from either side (no stray whitespace)", () => {
+      // Arrange — child provides an empty className; the filter must remove it.
+      const { container } = render(
+        <Slot className="slot-class">
+          <span className="">text</span>
+        </Slot>,
+      );
+
+      // Assert — exactly "slot-class", not "slot-class " with a trailing space
+      expect((container.firstChild as HTMLElement).getAttribute("class")).toBe(
+        "slot-class",
+      );
+    });
+  });
+
+  describe("ref composition (exercised through the component)", () => {
+    it("calls a function ref forwarded through the Slot with the element", () => {
+      // Arrange
+      const fnRef = vi.fn();
+
+      // Act — a function ref on the Slot is composed onto the child element
+      render(
+        <Slot ref={fnRef}>
+          <button type="button">Click me</button>
+        </Slot>,
+      );
+
+      // Assert
+      expect(fnRef).toHaveBeenCalledWith(screen.getByRole("button"));
+    });
+
+    it("populates an object ref and tolerates a child with no ref of its own", () => {
+      // Arrange — the Slot's object ref composes with the child's (absent) ref;
+      // the absent side must be skipped, not dereferenced.
+      const objRef = createRef<HTMLElement>();
+
+      // Act
+      render(
+        <Slot ref={objRef}>
+          <button type="button">Click me</button>
+        </Slot>,
+      );
+
+      // Assert
+      expect(objRef.current).toBe(screen.getByRole("button"));
+    });
+  });
+
+  describe("mergeProps — event handlers (both sides)", () => {
+    it("composes handlers when both provide one — child first, then slot", async () => {
+      // Arrange
+      const user = userEvent.setup();
+      const calls: string[] = [];
+      const slotClick = vi.fn(() => calls.push("slot"));
+      const childClick = vi.fn(() => calls.push("child"));
+      render(
+        <Slot onClick={slotClick}>
+          <button type="button" onClick={childClick}>
+            Click me
+          </button>
+        </Slot>,
+      );
+
+      // Act
+      await user.click(screen.getByRole("button"));
+
+      // Assert — both fire, child's handler first
+      expect(childClick).toHaveBeenCalledTimes(1);
+      expect(slotClick).toHaveBeenCalledTimes(1);
+      expect(calls).toEqual(["child", "slot"]);
+    });
+  });
+
+  describe("mergeProps — other props", () => {
+    it("keeps non-special props, child winning over the slot on collision", () => {
+      // Arrange
+      const { container } = render(
+        <Slot id="slot-id" data-origin="slot">
+          <span id="child-id">text</span>
+        </Slot>,
+      );
+      const el = container.firstChild as HTMLElement;
+
+      // Assert — child's id wins; the slot-only prop still passes through
+      expect(el.id).toBe("child-id");
+      expect(el.getAttribute("data-origin")).toBe("slot");
+    });
+
+    it("does not treat a prop merely containing on[A-Z] as an event handler", () => {
+      // Arrange — "iconOnly" contains "onO" but is not a handler; only a
+      // start-anchored /^on[A-Z]/ correctly excludes it, so the child value must
+      // win by the default merge rather than being composed into a function.
+      // "iconOnly" is not a real DOM attribute, hence the spread casts.
+      const { container } = render(
+        <Slot {...({ iconOnly: "slot" } as object)}>
+          <span {...({ iconOnly: "child" } as object)}>text</span>
+        </Slot>,
+      );
+
+      // Assert
+      expect((container.firstChild as HTMLElement).getAttribute("icononly")).toBe(
+        "child",
+      );
+    });
+  });
+
+  it('sets displayName to "Slot" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Slot.displayName).toBe("Slot");
   });
 });

package/src/Slot/composeEventHandlers.ts

@@ -5,8 +5,25 @@
  *
  * This is the standard composition pattern used throughout headless
  * components to let consumers attach their own listeners onto a
- * sub-component without clobbering the component's own behaviour, while
- * still giving them an opt-out via `preventDefault()`.
+ * sub-component's *own* native event props (e.g. `Tabs.Trigger`'s
+ * `onClick`, `Modal.Overlay`'s `onClick`) without clobbering the
+ * component's own behaviour, while still giving them an opt-out via
+ * `preventDefault()`. Wrap it around the component's internal handler at
+ * the point the prop is consumed:
+ *
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, () => {
+ *   // the component's own behaviour, e.g. activating a tab
+ * });
+ * ```
+ *
+ * **Not the same mechanism as {@link Slot}.** `Slot`'s own prop-merging
+ * (used for the `asChild` pattern) also composes event handlers, but with
+ * the *opposite* order (child fires first, then Slot) and *no*
+ * `preventDefault()` opt-out — both handlers always run there. Reach for
+ * `composeEventHandlers` when a component owns a native DOM prop directly;
+ * reach for `Slot` when delegating rendering to a consumer-supplied
+ * element via `asChild`. The two are never used together on the same prop.
  *
  * @example Consumer logs every click; component still closes the modal
  * afterwards:
@@ -20,6 +37,13 @@
  *   if (formIsDirty) e.preventDefault(); // don't close
  * }} />
  * ```
+ *
+ * @example Opting out of the veto — always run our handler too
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, ourHandler, {
+ *   checkForDefaultPrevented: false,
+ * });
+ * ```
  */
 export function composeEventHandlers<E>(
   theirHandler: ((event: E) => void) | undefined,

package/src/Slot/types.ts

@@ -1,5 +1,21 @@
 import { HTMLAttributes, ReactNode } from "react";
 
+/**
+ * Props for {@link Slot} — all native `HTMLAttributes` (event handlers,
+ * `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,
+ * `className` concatenates, everything else defaults to the child).
+ *
+ * @extends HTMLElement
+ */
 export type SlotProps = HTMLAttributes<HTMLElement> & {
+  /**
+   * The element to clone `Slot`'s props onto. Must be exactly one valid
+   * React element that accepts a `ref` — passing zero children, more than
+   * one, or a non-element (e.g. a plain string) throws
+   * `"Slot requires exactly one React element child."`.
+   */
   children?: ReactNode;
 };

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).