@primitiv-ui/react 0.1.0

package/src/Tabs/hooks/useTabsTrigger.ts

@@ -0,0 +1,111 @@
+import {
+  useRef,
+  useEffect,
+  useCallback,
+  MouseEvent,
+} from "react";
+
+import { useRovingTabindex } from "../../hooks";
+
+import { TabsTriggerProps } from "../types";
+import { getTriggerAndPanelIds } from "../utils";
+
+import { useTabsContext } from "./useTabsContext";
+
+export function useTabsTrigger({
+  value,
+  onClick,
+  disabled,
+}: Pick<TabsTriggerProps, "value" | "onClick" | "disabled">) {
+  const {
+    orientation,
+    dir,
+    activationMode,
+    activeValue,
+    isControlled,
+    setActiveValue,
+    onValueChange,
+    onChange,
+    tabsId,
+    registerTrigger,
+    triggerValues,
+    disabledTriggerValues,
+    focusTrigger,
+  } = useTabsContext();
+  const isActive = activeValue === value;
+  const { triggerId, panelId } = getTriggerAndPanelIds(tabsId, value);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const state = isActive ? "active" : "inactive";
+  // When no tab is active (no defaultValue/value provided), the first registered
+  // trigger acts as the roving-tabindex home base so the tablist stays reachable
+  // via keyboard Tab navigation.
+  const isFirst = triggerValues[0] === value;
+  const tabIndex = isActive || (activeValue === undefined && isFirst) ? 0 : -1;
+
+  useEffect(() => {
+    registerTrigger(value, buttonRef.current, disabled);
+    return () => registerTrigger(value, null);
+  }, [value, disabled, registerTrigger]);
+
+  const activateTab = useCallback(
+    (newValue: string, index: number) => {
+      if (activeValue === newValue) return;
+      if (isControlled) {
+        onValueChange?.(newValue);
+      } else {
+        setActiveValue(newValue);
+      }
+      onChange?.({ index, name: newValue });
+    },
+    [activeValue, isControlled, onValueChange, setActiveValue, onChange],
+  );
+
+  // Note: this composition is deliberately bespoke and does NOT use the
+  // shared composeEventHandlers from ../../Slot. It runs the library's
+  // activation BEFORE the consumer's onClick, and offers no preventDefault
+  // veto path — both differ from the shared util's contract. Switching to
+  // composeEventHandlers here would be an observable behaviour change for
+  // consumers (handler ordering and preventDefault semantics).
+  function handleClick(e: MouseEvent<HTMLButtonElement>) {
+    const index = triggerValues.indexOf(value);
+    if (!disabled) {
+      activateTab(value, index);
+    }
+    onClick?.(e);
+  }
+
+  // Tabs deliberately leaves disabled values in `navigable` so arrow keys
+  // *land* on disabled tabs (focus moves there) without activating them —
+  // that's the Tabs-specific keyboard contract, distinct from RadioGroup
+  // and Accordion which both skip disabled siblings entirely.
+  const { handleKeyDown } = useRovingTabindex<string>({
+    orientation,
+    dir,
+    navigable: triggerValues,
+    currentKey: value,
+    includeHomeEnd: true,
+    includeActivate: true,
+    onNavigate: (targetValue, action) => {
+      const isDisabled = disabledTriggerValues.has(targetValue);
+      const shouldActivate =
+        !isDisabled &&
+        (activationMode === "automatic" ||
+          (activationMode === "manual" && action === "activate"));
+      if (shouldActivate) {
+        activateTab(targetValue, triggerValues.indexOf(targetValue));
+      }
+      focusTrigger(targetValue);
+    },
+  });
+  return {
+    buttonRef,
+    triggerId,
+    panelId,
+    isActive,
+    orientation,
+    state,
+    tabIndex,
+    handleClick,
+    handleKeyDown,
+  };
+}

package/src/Tabs/index.ts

@@ -0,0 +1,3 @@
+export * from './Tabs';
+export * from './TabsContext';
+export * from './types';

package/src/Tabs/types.ts

@@ -0,0 +1,99 @@
+import { ComponentProps, Ref } from "react";
+
+export type TabsOrientation = "horizontal" | "vertical";
+
+export type TabsReadingDirection = "ltr" | "rtl";
+
+export type TabsActivationMode = "automatic" | "manual";
+
+/**
+ * Payload delivered to the {@link BaseTabsRootProps.onChange | `onChange`} callback
+ * on every user-driven tab activation.
+ *
+ * - `index` — zero-based position of the activated trigger in registration order.
+ * - `name`  — the programmatic **value** string passed to `Tabs.Trigger` (e.g.
+ *   `"settings"`), **not** the human-readable label text rendered inside the
+ *   trigger. Use the `children` of the trigger for the visible label.
+ */
+export type TabMetadata = { index: number; name: string };
+
+export type BaseTabsRootProps = {
+  onChange?: ({ index, name }: TabMetadata) => void;
+};
+
+export type UncontrolledTabsRootProps = {
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: never;
+};
+
+type ControlledTabsRootProps = {
+  value: string;
+  onValueChange: (value: string) => void;
+  defaultValue?: never;
+};
+
+export type TabsRootProps = Omit<ComponentProps<"div">, "onChange"> & {
+  orientation?: TabsOrientation;
+  dir?: TabsReadingDirection;
+  activationMode?: TabsActivationMode;
+  /** When `true`, a panel's children are not rendered until that tab is first
+   * activated. Once mounted they remain in the DOM across subsequent tab
+   * switches (lazy mount, not unmount-on-hide). Useful for panels that own
+   * expensive initialisation — e.g. a scroll-snap carousel whose initial
+   * scroll position must be set while the panel is visible. */
+  lazyMount?: boolean;
+} & BaseTabsRootProps &
+  (UncontrolledTabsRootProps | ControlledTabsRootProps);
+
+export type TabsContextValue = {
+  orientation: TabsOrientation;
+  dir: TabsReadingDirection;
+  activationMode: TabsActivationMode;
+  activeValue: string | undefined;
+  isControlled: boolean;
+  setActiveValue: (next: string) => void;
+  onValueChange?: (value: string) => void;
+  onChange?: ({ index, name }: TabMetadata) => void;
+  tabsId: string;
+  lazyMount: boolean;
+  registerTrigger: (
+    value: string,
+    element: HTMLButtonElement | null,
+    disabled?: boolean,
+  ) => void;
+  triggerValues: string[];
+  disabledTriggerValues: Set<string>;
+  focusTrigger: (value: string) => void;
+};
+
+export type TabsListProps = Omit<
+  ComponentProps<"div">,
+  "label" | "aria-labelledby"
+> &
+  (
+    | { label: string; ariaLabelledBy?: never }
+    | { label?: never; ariaLabelledBy: string }
+  );
+export type TabsTriggerProps<T extends HTMLElement = HTMLButtonElement> = Omit<
+  ComponentProps<"button">,
+  "ref"
+> & {
+  disabled?: boolean;
+  value: string;
+  /** Render the child element instead of the default `<button>`. All tab
+   * ARIA attributes and event handlers are merged onto the child. The child
+   * must accept a `ref`. Useful for routing links that need tab semantics. */
+  asChild?: boolean;
+  /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
+   * `asChild`, specify the child's element type (e.g. `HTMLAnchorElement`). */
+  ref?: Ref<T>;
+};
+
+export type TabsContentProps = ComponentProps<"div"> & {
+  value: string;
+};
+
+export type TabsImperativeApi = {
+  setActiveTab: (value: string) => void;
+};

package/src/Tabs/utils.ts

@@ -0,0 +1,8 @@
+import { deriveId } from "../utils";
+
+export function getTriggerAndPanelIds(tabsId: string, value: string) {
+  return {
+    triggerId: deriveId(tabsId, "trigger", value),
+    panelId: deriveId(tabsId, "panel", value),
+  };
+}

package/src/Textarea/README.md

@@ -0,0 +1,98 @@
+# Textarea
+
+A headless, accessible multi-line text input. Zero styles ship — apply
+whatever design system you use.
+
+```tsx
+import { Textarea } from "@primitiv-ui/react";
+
+<label htmlFor="bio">Bio</label>
+<Textarea id="bio" rows={4} placeholder="Tell us about yourself" />
+```
+
+## Props
+
+| Prop       | Type                         | Default | Notes                                                            |
+| ---------- | ---------------------------- | ------- | ---------------------------------------------------------------- |
+| `disabled` | `boolean`                    | —       | Native `disabled` + `data-disabled=""` styling hook              |
+| `asChild`  | `boolean`                    | `false` | Delegate rendering to the child element via Slot                 |
+| `ref`      | `Ref<HTMLTextAreaElement>`   | —       | Forwarded to the underlying textarea element                     |
+| `...rest`  | `ComponentProps<"textarea">` | —       | All other `<textarea>` props (`value`, `rows`, `aria-*`, etc.)   |
+
+## Labelling
+
+A `<textarea>` has no implicit accessible name. Give it one of:
+
+- a `<label>` whose `htmlFor` matches the textarea's `id`,
+- an `aria-label`, or
+- an `aria-labelledby` pointing at visible label text.
+
+```tsx
+<label htmlFor="notes">Notes</label>
+<Textarea id="notes" />
+```
+
+## Disabled
+
+Passing `disabled` forwards the native `disabled` attribute (removing the
+field from the tab order and blocking input) **and** sets
+`data-disabled=""` so CSS can target `[data-disabled]` without relying on
+the `:disabled` pseudo-class:
+
+```tsx
+<Textarea aria-label="Bio" disabled />
+```
+
+```css
+textarea[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+## `asChild` composition
+
+Pass `asChild` to render any consumer-supplied element instead of
+`<textarea>`. All props (`aria-*`, `data-*`, event handlers, `ref`) are
+merged onto the child via the `Slot` utility — event handlers compose
+(child runs first), `style` is shallow-merged, `className` is concatenated.
+
+This is the escape hatch for wrapping a third-party autosizing textarea
+while keeping the same prop contract:
+
+```tsx
+<Textarea asChild aria-label="Bio">
+  <AutosizeTextarea />
+</Textarea>
+```
+
+## Ref forwarding
+
+```tsx
+const ref = useRef<HTMLTextAreaElement>(null);
+<Textarea ref={ref} aria-label="Bio" />
+```
+
+## Field integration
+
+When rendered inside a [`<Field.Root>`](../Field/README.md), `Textarea`
+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
+`Textarea` to override any field-derived one. Outside a `<Field.Root>`,
+behaviour is unchanged.
+
+```tsx
+<Field.Root invalid={!!errors.bio}>
+  <Field.Label>Bio</Field.Label>
+  <Textarea rows={4} required {...register("bio")} />
+  <Field.ErrorText>{errors.bio?.message}</Field.ErrorText>
+</Field.Root>
+```

package/src/Textarea/Textarea.tsx

@@ -0,0 +1,93 @@
+import { useFieldProps } from "../Field/hooks";
+import { Slot } from "../Slot";
+import { TextareaProps } from "./types";
+
+/**
+ * A headless, accessible multi-line text input.
+ *
+ * Renders a native `<textarea>` and passes every standard textarea
+ * attribute straight through to the DOM — `value` / `defaultValue`,
+ * `rows`, `cols`, `placeholder`, `readOnly`, `required`, `name`,
+ * `maxLength`, and so on. No styles ship with the component.
+ *
+ * **Labelling.** A `<textarea>` has no implicit accessible name. Pair it
+ * with a `<label>` (`htmlFor` → the textarea's `id`), or pass `aria-label`
+ * / `aria-labelledby` for the control to be announced correctly.
+ *
+ * **Field integration.** When rendered inside a `<Field.Root>`, Textarea
+ * 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.
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLTextAreaElement` directly:
+ *
+ * ```tsx
+ * const ref = useRef<HTMLTextAreaElement>(null);
+ * <Textarea ref={ref} aria-label="Bio" />
+ * ```
+ *
+ * **Disabled.** Sets native `disabled` (removing the field from the tab
+ * order and blocking input) plus `data-disabled=""` so CSS can target
+ * `[data-disabled]` without relying on the `:disabled` pseudo-class:
+ *
+ * ```css
+ * textarea[data-disabled] { opacity: 0.5; cursor: not-allowed; }
+ * ```
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * `<textarea>`, merging all props (aria-*, data-*, event handlers, ref)
+ * via the {@link Slot} utility. Use it to wrap an autosizing textarea
+ * implementation while keeping this component's prop contract.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <label htmlFor="bio">Bio</label>
+ * <Textarea id="bio" rows={4} placeholder="Tell us about yourself" />
+ * ```
+ *
+ * @example Inside a Field — id and aria wired automatically
+ * ```tsx
+ * <Field.Root invalid={!!errors.bio}>
+ *   <Field.Label>Bio</Field.Label>
+ *   <Textarea rows={4} {...register("bio")} />
+ *   <Field.ErrorText>{errors.bio?.message}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Textarea aria-label="Bio" disabled />
+ * ```
+ *
+ * @example asChild — wrap an autosizing textarea
+ * ```tsx
+ * <Textarea asChild aria-label="Bio">
+ *   <AutosizeTextarea />
+ * </Textarea>
+ * ```
+ */
+export function Textarea({
+  asChild = false,
+  children,
+  ref,
+  ...consumer
+}: TextareaProps) {
+  const merged = useFieldProps(consumer);
+
+  const rootProps = {
+    ...merged,
+    ref,
+    "data-disabled": merged.disabled ? "" : undefined,
+  };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return <textarea {...rootProps} />;
+}
+
+Textarea.displayName = "Textarea";

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

@@ -0,0 +1,85 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Textarea } from "../Textarea";
+
+describe("Textarea asChild composition", () => {
+  it("renders the consumer's element instead of its own <textarea>", () => {
+    // Arrange & Act
+    render(
+      <Textarea asChild aria-label="Bio">
+        <textarea data-testid="autosize" />
+      </Textarea>,
+    );
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Bio" })).toHaveAttribute(
+      "data-testid",
+      "autosize",
+    );
+  });
+
+  it("renders exactly one textarea — the child, not an extra wrapper", () => {
+    // Arrange & Act
+    render(
+      <Textarea asChild aria-label="Bio">
+        <textarea />
+      </Textarea>,
+    );
+
+    // Assert
+    expect(screen.getAllByRole("textbox")).toHaveLength(1);
+  });
+
+  it("merges aria-* props onto the child element", () => {
+    // Arrange & Act
+    render(
+      <Textarea asChild aria-label="Bio" aria-invalid>
+        <textarea />
+      </Textarea>,
+    );
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Bio" })).toHaveAttribute(
+      "aria-invalid",
+      "true",
+    );
+  });
+
+  it("composes onChange — child handler fires first, then Textarea's", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const order: string[] = [];
+    render(
+      <Textarea
+        asChild
+        aria-label="Bio"
+        onChange={() => order.push("textarea")}
+      >
+        <textarea onChange={() => order.push("child")} />
+      </Textarea>,
+    );
+
+    // Act
+    await user.type(screen.getByRole("textbox", { name: "Bio" }), "x");
+
+    // Assert
+    expect(order).toEqual(["child", "textarea"]);
+  });
+
+  it("forwards a ref to the child element", () => {
+    // Arrange
+    const ref = createRef<HTMLTextAreaElement>();
+
+    // Act
+    render(
+      <Textarea asChild aria-label="Bio" ref={ref}>
+        <textarea />
+      </Textarea>,
+    );
+
+    // Assert
+    expect(ref.current).toBe(screen.getByRole("textbox", { name: "Bio" }));
+  });
+});

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

@@ -0,0 +1,107 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Textarea } from "../Textarea";
+
+describe("Textarea basic rendering", () => {
+  it("renders a <textarea> element", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" />);
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Notes" }).tagName).toBe(
+      "TEXTAREA",
+    );
+  });
+
+  it("forwards a ref to the underlying textarea element (object ref)", () => {
+    // Arrange
+    const ref = createRef<HTMLTextAreaElement>();
+
+    // Act
+    render(<Textarea aria-label="Notes" ref={ref} />);
+
+    // Assert
+    expect(ref.current).toBe(screen.getByRole("textbox", { name: "Notes" }));
+  });
+
+  it("forwards a ref to the underlying textarea element (function ref)", () => {
+    // Arrange
+    const received: (HTMLTextAreaElement | null)[] = [];
+    const functionRef = (node: HTMLTextAreaElement | null) => {
+      received.push(node);
+    };
+
+    // Act
+    render(<Textarea aria-label="Notes" ref={functionRef} />);
+
+    // Assert
+    expect(received).toContain(
+      screen.getByRole("textbox", { name: "Notes" }),
+    );
+  });
+
+  it("reflects a defaultValue", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" defaultValue="hello" />);
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Notes" })).toHaveValue(
+      "hello",
+    );
+  });
+
+  it("passes through textarea attributes (rows, placeholder)", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" rows={6} placeholder="Type here" />);
+    const textarea = screen.getByRole("textbox", { name: "Notes" });
+
+    // Assert
+    expect(textarea).toHaveAttribute("rows", "6");
+    expect(textarea).toHaveAttribute("placeholder", "Type here");
+  });
+
+  it("passes through aria-* attributes", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" aria-invalid />);
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Notes" })).toHaveAttribute(
+      "aria-invalid",
+      "true",
+    );
+  });
+
+  it("passes through data-* attributes", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" data-testid="bio" />);
+
+    // Assert
+    expect(screen.getByTestId("bio")).toBeInTheDocument();
+  });
+
+  it("passes through className", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" className="field" />);
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Notes" })).toHaveAttribute(
+      "class",
+      "field",
+    );
+  });
+
+  it("passes through event handlers (onChange)", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<Textarea aria-label="Notes" onChange={onChange} />);
+
+    // Act
+    await user.type(screen.getByRole("textbox", { name: "Notes" }), "hi");
+
+    // Assert
+    expect(onChange).toHaveBeenCalledTimes(2);
+  });
+});

package/src/Textarea/__tests__/Textarea.disabled.test.tsx

@@ -0,0 +1,49 @@
+import { render, screen } from "@testing-library/react";
+
+import { Textarea } from "../Textarea";
+
+describe("Textarea disabled state", () => {
+  it("sets the native disabled attribute", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" disabled />);
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Notes" })).toBeDisabled();
+  });
+
+  it('sets data-disabled="" as a CSS styling hook', () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" disabled />);
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Notes" })).toHaveAttribute(
+      "data-disabled",
+      "",
+    );
+  });
+
+  it("does not set data-disabled when not disabled", () => {
+    // Arrange & Act
+    render(<Textarea aria-label="Notes" />);
+
+    // Assert
+    expect(
+      screen.getByRole("textbox", { name: "Notes" }),
+    ).not.toHaveAttribute("data-disabled");
+  });
+
+  it("sets data-disabled on the child element when asChild and disabled", () => {
+    // Arrange & Act
+    render(
+      <Textarea asChild aria-label="Notes" disabled>
+        <textarea />
+      </Textarea>,
+    );
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Notes" })).toHaveAttribute(
+      "data-disabled",
+      "",
+    );
+  });
+});