@primitiv-ui/react 0.1.0

package/src/InputGroup/InputGroup.tsx

@@ -0,0 +1,228 @@
+import { Slot } from "../Slot";
+import { InputGroupAdornmentProps, InputGroupRootProps } from "./types";
+
+/**
+ * The root of an InputGroup — a stateless `<div>` wrapper that frames a
+ * single form control alongside optional leading and trailing adornments.
+ *
+ * `InputGroup` is intentionally **layout-and-anatomy only**. It owns no
+ * state, provides no context, and does not know which control sits
+ * inside it. Use CSS `:focus-within` and `:has(input:disabled)` /
+ * `:has(input[aria-invalid="true"])` to style the frame in response to
+ * the inner control's state — no JS coordination required.
+ *
+ * **Styling hook.** `data-input-group=""` on the root.
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's
+ * element instead of `<div>` — e.g. a `<label>` so a click anywhere on
+ * the frame focuses the wrapped input.
+ *
+ * @example Basic frame with no adornments
+ * ```tsx
+ * <InputGroup>
+ *   <Input aria-label="Search" type="search" />
+ * </InputGroup>
+ * ```
+ *
+ * @example Frame rendered as a <label> so the whole frame is clickable
+ * ```tsx
+ * <InputGroup asChild>
+ *   <label>
+ *     <InputGroup.LeadingAdornment><SearchIcon /></InputGroup.LeadingAdornment>
+ *     <Input type="search" />
+ *   </label>
+ * </InputGroup>
+ * ```
+ */
+function InputGroupRoot({
+  asChild = false,
+  children,
+  ref,
+  ...rest
+}: InputGroupRootProps) {
+  const rootProps = {
+    ...rest,
+    ref,
+    "data-input-group": "",
+  };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return <div {...rootProps}>{children}</div>;
+}
+
+InputGroupRoot.displayName = "InputGroupRoot";
+
+/**
+ * A leading adornment slot — a `<span>` positioned at the start of the
+ * frame for icons, currency symbols, prefix text, or interactive
+ * buttons.
+ *
+ * **Styling hook.** `data-input-group-adornment="leading"` on the
+ * adornment element.
+ *
+ * **Accessibility.** No `aria-hidden` is set automatically — the
+ * adornment is just a positioned slot. Mark decorative icons
+ * `aria-hidden="true"` yourself (or wrap with `AccessibleIcon`), and
+ * give interactive children a proper accessible name.
+ *
+ * **`asChild` composition.** Pass `asChild` to render an interactive
+ * element such as `<button>` — for a clickable icon that triggers a
+ * search, opens a colour picker, or any other action. Event handlers
+ * compose (child runs first); refs forward to the consumer element.
+ *
+ * @example Decorative leading icon
+ * ```tsx
+ * <InputGroup.LeadingAdornment>
+ *   <SearchIcon aria-hidden="true" />
+ * </InputGroup.LeadingAdornment>
+ * ```
+ *
+ * @example Interactive leading button via asChild
+ * ```tsx
+ * <InputGroup.LeadingAdornment asChild>
+ *   <button type="button" aria-label="Open colour picker" onClick={open}>
+ *     <ColourSwatch />
+ *   </button>
+ * </InputGroup.LeadingAdornment>
+ * ```
+ */
+function InputGroupLeadingAdornment({
+  asChild = false,
+  children,
+  ref,
+  ...rest
+}: InputGroupAdornmentProps) {
+  const adornmentProps = {
+    ...rest,
+    ref,
+    "data-input-group-adornment": "leading" as const,
+  };
+
+  if (asChild) {
+    return <Slot {...adornmentProps}>{children}</Slot>;
+  }
+
+  return <span {...adornmentProps}>{children}</span>;
+}
+
+InputGroupLeadingAdornment.displayName = "InputGroupLeadingAdornment";
+
+/**
+ * A trailing adornment slot — a `<span>` positioned at the end of the
+ * frame for icons, suffix text, clear buttons, or password-reveal
+ * toggles.
+ *
+ * **Styling hook.** `data-input-group-adornment="trailing"` on the
+ * adornment element.
+ *
+ * **Accessibility.** No `aria-hidden` is set automatically — the
+ * adornment is just a positioned slot. Mark decorative icons
+ * `aria-hidden="true"` yourself (or wrap with `AccessibleIcon`), and
+ * give interactive children a proper accessible name.
+ *
+ * **`asChild` composition.** Pass `asChild` to render an interactive
+ * element such as `<button>`. Event handlers compose (child runs
+ * first); refs forward to the consumer element.
+ *
+ * @example Trailing clear button via asChild
+ * ```tsx
+ * <InputGroup.TrailingAdornment asChild>
+ *   <button type="button" aria-label="Clear" onClick={clear}>
+ *     <XIcon aria-hidden="true" />
+ *   </button>
+ * </InputGroup.TrailingAdornment>
+ * ```
+ */
+function InputGroupTrailingAdornment({
+  asChild = false,
+  children,
+  ref,
+  ...rest
+}: InputGroupAdornmentProps) {
+  const adornmentProps = {
+    ...rest,
+    ref,
+    "data-input-group-adornment": "trailing" as const,
+  };
+
+  if (asChild) {
+    return <Slot {...adornmentProps}>{children}</Slot>;
+  }
+
+  return <span {...adornmentProps}>{children}</span>;
+}
+
+InputGroupTrailingAdornment.displayName = "InputGroupTrailingAdornment";
+
+type TInputGroupCompound = typeof InputGroupRoot & {
+  Root: typeof InputGroupRoot;
+  LeadingAdornment: typeof InputGroupLeadingAdornment;
+  TrailingAdornment: typeof InputGroupTrailingAdornment;
+};
+
+/**
+ * Headless, accessible **InputGroup** — a stateless compound that frames
+ * a single form control alongside optional leading and trailing
+ * adornments. Zero styles ship.
+ *
+ * `InputGroup` is intentionally **not** input-specific. It maps directly
+ * to the `framed-control/*` design-token anatomy (height,
+ * padding-inline, gap, icon-size, radius) and works just as well around
+ * a `<Textarea>`, a future `NumberInput.Control`, or any other framed
+ * control — the only thing tying it to `<Input>` is the name.
+ *
+ * `InputGroup` is both callable (an alias of `InputGroup.Root`) and
+ * carries its sub-components as static properties:
+ *
+ * - {@link InputGroupRoot | `InputGroup.Root`} — the wrapping `<div>`,
+ *   `data-input-group=""` styling hook.
+ * - {@link InputGroupLeadingAdornment | `InputGroup.LeadingAdornment`} —
+ *   leading slot, `data-input-group-adornment="leading"`.
+ * - {@link InputGroupTrailingAdornment | `InputGroup.TrailingAdornment`} —
+ *   trailing slot, `data-input-group-adornment="trailing"`.
+ *
+ * **State coordination.** None. CSS handles disabled / invalid /
+ * focus-within styling via `:has()` and `:focus-within`. When `Field`
+ * lands it will sit *outside* `InputGroup` and own label / error /
+ * description wiring without InputGroup needing to change.
+ *
+ * @example Leading search icon
+ * ```tsx
+ * import { InputGroup, Input } from "@primitiv-ui/react";
+ *
+ * <InputGroup>
+ *   <InputGroup.LeadingAdornment>
+ *     <SearchIcon aria-hidden="true" />
+ *   </InputGroup.LeadingAdornment>
+ *   <Input aria-label="Search" type="search" />
+ * </InputGroup>
+ * ```
+ *
+ * @example Trailing clear button
+ * ```tsx
+ * <InputGroup>
+ *   <Input value={q} onChange={onChange} aria-label="Search" />
+ *   <InputGroup.TrailingAdornment asChild>
+ *     <button type="button" aria-label="Clear" onClick={clear}>
+ *       <XIcon aria-hidden="true" />
+ *     </button>
+ *   </InputGroup.TrailingAdornment>
+ * </InputGroup>
+ * ```
+ *
+ * @see {@link InputGroupRoot} for frame anatomy and `asChild` on Root.
+ * @see {@link InputGroupLeadingAdornment} for leading-slot semantics.
+ * @see {@link InputGroupTrailingAdornment} for trailing-slot semantics.
+ */
+const InputGroupCompound: TInputGroupCompound = Object.assign(InputGroupRoot, {
+  Root: InputGroupRoot,
+  LeadingAdornment: InputGroupLeadingAdornment,
+  TrailingAdornment: InputGroupTrailingAdornment,
+});
+
+InputGroupCompound.displayName = "InputGroup";
+
+export { InputGroupCompound as InputGroup };

package/src/InputGroup/README.md

@@ -0,0 +1,178 @@
+# InputGroup
+
+A headless, accessible compound that frames a single form control
+alongside optional leading and trailing adornments — icons, currency
+symbols, clear buttons, password-reveal toggles. Zero styles ship.
+
+```tsx
+import { InputGroup, Input } from "@primitiv-ui/react";
+
+<InputGroup>
+  <InputGroup.LeadingAdornment>
+    <SearchIcon aria-hidden="true" />
+  </InputGroup.LeadingAdornment>
+  <Input aria-label="Search" type="search" />
+</InputGroup>
+```
+
+## Anatomy
+
+| Part                              | Element  | Styling hook                                  |
+| --------------------------------- | -------- | --------------------------------------------- |
+| `InputGroup` / `InputGroup.Root`  | `<div>`  | `data-input-group=""`                         |
+| `InputGroup.LeadingAdornment`     | `<span>` | `data-input-group-adornment="leading"`        |
+| `InputGroup.TrailingAdornment`    | `<span>` | `data-input-group-adornment="trailing"`       |
+
+`InputGroup` is intentionally **not** input-specific. The wrapper maps
+to the `framed-control/*` design-token anatomy (height, padding-inline,
+gap, icon-size, radius) and works around `<Input>`, `<Textarea>`, or any
+future framed control — the only thing tying it to `<Input>` is the
+name.
+
+## State coordination — there is none
+
+`InputGroup` owns no state, provides no context, and accepts no
+`disabled` / `invalid` props. State-dependent styling on the frame
+delegates to CSS:
+
+```css
+[data-input-group] {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--frame-gap);
+  padding-inline: var(--frame-padding-inline);
+  border: 1px solid var(--frame-border);
+  border-radius: var(--frame-radius);
+}
+
+/* Focus ring around the whole frame */
+[data-input-group]:focus-within {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 1px;
+}
+
+/* Disabled-frame styling — driven by the inner input */
+[data-input-group]:has(input:disabled) {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Invalid-frame styling — same idea */
+[data-input-group]:has(input[aria-invalid="true"]) {
+  border-color: var(--danger);
+}
+```
+
+When `Field` lands it will sit *outside* `InputGroup` and own label /
+description / error-text wiring; `InputGroup` will not need to change.
+
+## Adornments
+
+### Decorative
+
+A decorative icon — give the icon `aria-hidden="true"` (or wrap with
+`AccessibleIcon`). The default `<span>` adornment has no automatic ARIA
+semantics — that's the consumer's call.
+
+```tsx
+<InputGroup>
+  <InputGroup.LeadingAdornment>
+    <MailIcon aria-hidden="true" />
+  </InputGroup.LeadingAdornment>
+  <Input type="email" aria-label="Email" />
+</InputGroup>
+```
+
+### Interactive — `asChild` + `<button>`
+
+For a clear button, password-reveal toggle, or any clickable adornment,
+pass `asChild` and supply the `<button>` directly. The data attribute
+and ref merge onto the button; event handlers compose (child runs
+first).
+
+```tsx
+<InputGroup>
+  <Input value={q} onChange={onChange} aria-label="Search" />
+  <InputGroup.TrailingAdornment asChild>
+    <button type="button" aria-label="Clear" onClick={() => onChange("")}>
+      <XIcon aria-hidden="true" />
+    </button>
+  </InputGroup.TrailingAdornment>
+</InputGroup>
+```
+
+### Leading and trailing together
+
+JSX order matches visual order — put `LeadingAdornment` before the
+control, `TrailingAdornment` after.
+
+```tsx
+<InputGroup>
+  <InputGroup.LeadingAdornment><MailIcon aria-hidden="true" /></InputGroup.LeadingAdornment>
+  <Input type="email" aria-label="Email" />
+  <InputGroup.TrailingAdornment asChild>
+    <button type="button" aria-label="Clear">
+      <XIcon aria-hidden="true" />
+    </button>
+  </InputGroup.TrailingAdornment>
+</InputGroup>
+```
+
+## `asChild` on Root
+
+Pass `asChild` on `InputGroup.Root` to render the frame as a `<label>`
+so clicking anywhere on the frame focuses the wrapped input:
+
+```tsx
+<InputGroup asChild>
+  <label>
+    <InputGroup.LeadingAdornment><SearchIcon aria-hidden="true" /></InputGroup.LeadingAdornment>
+    <Input type="search" />
+  </label>
+</InputGroup>
+```
+
+## With react-hook-form
+
+`InputGroup` doesn't get in the way — spread `register` onto the inner
+`<Input>` as usual:
+
+```tsx
+import { useForm } from "react-hook-form";
+
+const { register, formState: { errors } } = useForm();
+
+<label htmlFor="email">Email</label>
+<InputGroup>
+  <InputGroup.LeadingAdornment><MailIcon aria-hidden="true" /></InputGroup.LeadingAdornment>
+  <Input
+    id="email"
+    type="email"
+    required
+    {...register("email")}
+    aria-invalid={!!errors.email}
+    aria-describedby="email-error"
+  />
+</InputGroup>
+{errors.email && <span id="email-error">{errors.email.message}</span>}
+```
+
+## Ref forwarding
+
+Every part accepts a `ref` prop:
+
+```tsx
+const groupRef = useRef<HTMLDivElement>(null);
+const inputRef = useRef<HTMLInputElement>(null);
+
+<InputGroup ref={groupRef}>
+  <Input ref={inputRef} aria-label="Search" />
+</InputGroup>
+```
+
+## Coming next
+
+- **Field** — the label / description / error-text coordinator that
+  wraps an `InputGroup` (or any other control) and auto-wires `id`,
+  `aria-describedby`, and the `invalid` cascade. Until it ships, do that
+  wiring manually.

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

@@ -0,0 +1,109 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { InputGroup } from "../InputGroup";
+
+describe("InputGroup asChild composition", () => {
+  it("Root asChild renders the consumer element with data-input-group merged on", () => {
+    // Arrange & Act
+    render(
+      <InputGroup.Root asChild data-testid="group">
+        <label />
+      </InputGroup.Root>,
+    );
+    const root = screen.getByTestId("group");
+
+    // Assert
+    expect(root.tagName).toBe("LABEL");
+    expect(root).toHaveAttribute("data-input-group", "");
+  });
+
+  it("LeadingAdornment asChild renders the consumer element with the leading data attribute", () => {
+    // Arrange & Act
+    render(
+      <InputGroup.Root>
+        <InputGroup.LeadingAdornment asChild data-testid="lead">
+          <button type="button">Search</button>
+        </InputGroup.LeadingAdornment>
+      </InputGroup.Root>,
+    );
+    const lead = screen.getByTestId("lead");
+
+    // Assert
+    expect(lead.tagName).toBe("BUTTON");
+    expect(lead).toHaveAttribute("data-input-group-adornment", "leading");
+  });
+
+  it("TrailingAdornment asChild renders the consumer element with the trailing data attribute", () => {
+    // Arrange & Act
+    render(
+      <InputGroup.Root>
+        <InputGroup.TrailingAdornment asChild data-testid="trail">
+          <button type="button">Clear</button>
+        </InputGroup.TrailingAdornment>
+      </InputGroup.Root>,
+    );
+    const trail = screen.getByTestId("trail");
+
+    // Assert
+    expect(trail.tagName).toBe("BUTTON");
+    expect(trail).toHaveAttribute("data-input-group-adornment", "trailing");
+  });
+
+  it("composes onClick when an adornment wraps a button via asChild", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const order: string[] = [];
+    render(
+      <InputGroup.Root>
+        <InputGroup.TrailingAdornment
+          asChild
+          onClick={() => order.push("adornment")}
+        >
+          <button type="button" onClick={() => order.push("child")}>
+            Clear
+          </button>
+        </InputGroup.TrailingAdornment>
+      </InputGroup.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Clear" }));
+
+    // Assert
+    expect(order).toEqual(["child", "adornment"]);
+  });
+
+  it("forwards a ref through Slot on the Root", () => {
+    // Arrange
+    const ref = createRef<HTMLLabelElement>();
+
+    // Act
+    render(
+      <InputGroup.Root asChild data-testid="group" ref={ref}>
+        <label />
+      </InputGroup.Root>,
+    );
+
+    // Assert
+    expect(ref.current).toBe(screen.getByTestId("group"));
+  });
+
+  it("forwards a ref through Slot on an Adornment", () => {
+    // Arrange
+    const ref = createRef<HTMLButtonElement>();
+
+    // Act
+    render(
+      <InputGroup.Root>
+        <InputGroup.TrailingAdornment asChild ref={ref}>
+          <button type="button">Clear</button>
+        </InputGroup.TrailingAdornment>
+      </InputGroup.Root>,
+    );
+
+    // Assert
+    expect(ref.current).toBe(screen.getByRole("button", { name: "Clear" }));
+  });
+});

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

@@ -0,0 +1,106 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+
+import { InputGroup } from "../InputGroup";
+
+describe("InputGroup basic rendering", () => {
+  it("renders a <div> wrapper element", () => {
+    // Arrange & Act
+    render(<InputGroup.Root data-testid="group" />);
+
+    // Assert
+    expect(screen.getByTestId("group").tagName).toBe("DIV");
+  });
+
+  it("sets data-input-group on the root as a CSS styling hook", () => {
+    // Arrange & Act
+    render(<InputGroup.Root data-testid="group" />);
+
+    // Assert
+    expect(screen.getByTestId("group")).toHaveAttribute(
+      "data-input-group",
+      "",
+    );
+  });
+
+  it("InputGroup is callable as an alias of InputGroup.Root", () => {
+    // Arrange & Act
+    render(<InputGroup data-testid="group" />);
+
+    // Assert
+    expect(screen.getByTestId("group").tagName).toBe("DIV");
+  });
+
+  it("forwards a ref to the root element", () => {
+    // Arrange
+    const ref = createRef<HTMLDivElement>();
+
+    // Act
+    render(<InputGroup.Root data-testid="group" ref={ref} />);
+
+    // Assert
+    expect(ref.current).toBe(screen.getByTestId("group"));
+  });
+
+  it("renders LeadingAdornment as a <span> with data-input-group-adornment='leading'", () => {
+    // Arrange & Act
+    render(
+      <InputGroup.Root>
+        <InputGroup.LeadingAdornment data-testid="lead" />
+      </InputGroup.Root>,
+    );
+    const span = screen.getByTestId("lead");
+
+    // Assert
+    expect(span.tagName).toBe("SPAN");
+    expect(span).toHaveAttribute("data-input-group-adornment", "leading");
+  });
+
+  it("renders TrailingAdornment as a <span> with data-input-group-adornment='trailing'", () => {
+    // Arrange & Act
+    render(
+      <InputGroup.Root>
+        <InputGroup.TrailingAdornment data-testid="trail" />
+      </InputGroup.Root>,
+    );
+    const span = screen.getByTestId("trail");
+
+    // Assert
+    expect(span.tagName).toBe("SPAN");
+    expect(span).toHaveAttribute("data-input-group-adornment", "trailing");
+  });
+
+  it("renders children inside the wrapper", () => {
+    // Arrange & Act
+    render(
+      <InputGroup.Root>
+        <input aria-label="Search" />
+      </InputGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Search" })).toBeInTheDocument();
+  });
+
+  it("passes through className on the root", () => {
+    // Arrange & Act
+    render(<InputGroup.Root className="frame" data-testid="g" />);
+
+    // Assert
+    expect(screen.getByTestId("g")).toHaveClass("frame");
+  });
+
+  it("passes through className on adornments", () => {
+    // Arrange & Act
+    render(
+      <InputGroup.Root>
+        <InputGroup.LeadingAdornment className="lead" data-testid="lead" />
+        <InputGroup.TrailingAdornment className="trail" data-testid="trail" />
+      </InputGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("lead")).toHaveClass("lead");
+    expect(screen.getByTestId("trail")).toHaveClass("trail");
+  });
+});

package/src/InputGroup/index.ts

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

package/src/InputGroup/types.ts

@@ -0,0 +1,13 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+export type InputGroupRootProps = ComponentProps<"div"> & {
+  asChild?: boolean;
+  ref?: Ref<HTMLDivElement>;
+  children?: ReactNode;
+};
+
+export type InputGroupAdornmentProps = ComponentProps<"span"> & {
+  asChild?: boolean;
+  ref?: Ref<HTMLSpanElement>;
+  children?: ReactNode;
+};