@primitiv-ui/react 0.1.28 → 0.1.29

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

@@ -76,4 +76,18 @@ describe("Checkbox basic rendering", () => {
       "unchecked",
     );
   });
+
+  it("sets a displayName on the compound and the Indicator", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "Checkbox".
+    expect(Checkbox.displayName).toBe("Checkbox");
+    expect(Checkbox.Indicator.displayName).toBe("CheckboxIndicator");
+  });
+
+  it("throws a helpful error when a sub-component renders outside Checkbox.Root", () => {
+    // Assert — the strict-context guard names the required parent.
+    expect(() => render(<Checkbox.Indicator />)).toThrow(
+      "Checkbox sub-components must be rendered inside a <Checkbox.Root>.",
+    );
+  });
 });

package/src/Checkbox/hooks/useCheckboxInput.ts

@@ -37,6 +37,10 @@ export function useCheckboxInput({
     onChange?.(event);
     if (event.defaultPrevented) return;
     const next = event.target.checked;
+    // Stryker disable next-line ConditionalExpression: in controlled mode
+    // `inputStateProps` reads controlledChecked, never `mirror`, so setting
+    // mirror here (the mutant's always-run form) has no observable effect —
+    // equivalent.
     if (!isControlled) setMirror(next);
     onCheckedChange?.(next);
   };

package/src/Checkbox/types.ts

@@ -10,7 +10,16 @@ export type CheckedState = boolean | "indeterminate";
  * `:indeterminate` state.
  */
 export type CheckboxIndicatorProps = ComponentProps<"span"> & {
+  /** Custom mark content. Omit to let the shipped CSS draw the tick/bar off the
+   * input's native `:checked` / `:indeterminate` state; provide your own (an
+   * icon, glyph, or nested element) to override it. */
   children?: ReactNode;
+  /**
+   * When `true`, render `children` as the indicator element itself
+   * (via the {@link Slot} pattern) instead of wrapping them in a `<span>`.
+   * `data-state` and `aria-hidden` are merged onto that element.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -38,7 +47,11 @@ export type CheckboxRootBaseProps = Omit<
  * `defaultChecked` may be `"indeterminate"` for a mixed-on-mount checkbox.
  */
 export type CheckboxRootUncontrolledProps = CheckboxRootBaseProps & {
+  /** Checked value on first render; the component owns it thereafter. May be
+   * `"indeterminate"` for a mixed-on-mount checkbox. Omit for an initially
+   * unchecked box. */
   defaultChecked?: CheckedState;
+  /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
   checked?: never;
 };
 
@@ -48,8 +61,14 @@ export type CheckboxRootUncontrolledProps = CheckboxRootBaseProps & {
  * forbidden.
  */
 export type CheckboxRootControlledProps = CheckboxRootBaseProps & {
+  /** Forbidden in controlled mode — use `checked` instead. */
   defaultChecked?: never;
+  /** The current checked value, owned by the parent. May be `"indeterminate"`
+   * for the tri-state; clicking a mixed checkbox resolves it to `true`. Keep it
+   * in sync via `onCheckedChange`. */
   checked: CheckedState;
+  /** Called with the new boolean checked value on every user toggle. Required
+   * in controlled mode so the parent can keep `checked` in sync. */
   onCheckedChange: (checked: boolean) => void;
 };
 

package/src/CheckboxCard/CheckboxCard.tsx

@@ -40,8 +40,11 @@ function dataStateOf(checked: CheckedState) {
  * on the root, plus `data-disabled=""` when disabled.
  *
  * **`asChild` prop.** Pass `asChild` to render any consumer-supplied element
- * with the checkbox's ARIA attributes, data-state, composed onClick, and ref
- * merged in.
+ * with the checkbox's ARIA attributes, `data-state`, composed `onClick`, and
+ * `ref` merged in via the {@link Slot} pattern. See
+ * {@link CheckboxCardRootBaseProps}.
+ *
+ * @extends HTMLButtonElement
  *
  * @example Uncontrolled
  * ```tsx
@@ -106,7 +109,11 @@ export function CheckboxCardRoot(props: CheckboxCardRootProps): ReactElement {
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "CheckboxCard" at load, so the value is never observable.
+// The assignment stays because it declares `displayName` on
+// `typeof CheckboxCardRoot`, which TCheckboxCardCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 CheckboxCardRoot.displayName = "CheckboxCardRoot";
 
 /**
@@ -124,7 +131,9 @@ CheckboxCardRoot.displayName = "CheckboxCardRoot";
  *
  * **`forceMount` prop.** Pass `forceMount` to keep the indicator in the DOM
  * while unchecked so a CSS exit animation can play against
- * `data-state="unchecked"`.
+ * `data-state="unchecked"`. See {@link CheckboxCardIndicatorProps}.
+ *
+ * @extends HTMLSpanElement
  *
  * @example
  * ```tsx

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

@@ -55,4 +55,11 @@ describe("CheckboxCard basic rendering", () => {
     expect(screen.getByTestId("icon")).toBeInTheDocument();
     expect(screen.getByText("Feature name")).toBeInTheDocument();
   });
+
+  it("sets a displayName on the compound and the Indicator", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "CheckboxCard".
+    expect(CheckboxCard.displayName).toBe("CheckboxCard");
+    expect(CheckboxCard.Indicator.displayName).toBe("CheckboxCardIndicator");
+  });
 });

package/src/CheckboxCard/types.ts

@@ -1,49 +1,97 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 import type { CheckedState } from "../Checkbox/types";
 
-/** Props for `CheckboxCard.Indicator` — the visual marker shown when the card
- * is checked. By default it renders only while checked; set `forceMount` to
- * keep it mounted for exit transitions. */
+/**
+ * Props for {@link CheckboxCardIndicator | `CheckboxCard.Indicator`} — the
+ * decorative visual marker (typically a tick icon) shown while the card is
+ * checked or indeterminate. All `HTMLSpanElement` attributes, plus the
+ * `forceMount` and `asChild` escape hatches.
+ */
 export type CheckboxCardIndicatorProps = ComponentProps<"span"> & {
+  /** The indicator content — typically an `<svg>` tick or check glyph. */
   children?: ReactNode;
+  /**
+   * Keep the indicator mounted while the card is **unchecked** so a CSS exit
+   * animation can play against `data-state="unchecked"`. By default the
+   * indicator unmounts as soon as the card is unchecked.
+   * @default false
+   */
   forceMount?: boolean;
+  /**
+   * When `true`, render the consumer's own element (typically an `<svg>`) as
+   * the indicator instead of the default `<span>`, merging `aria-hidden` and
+   * `data-state` onto it via the {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 
-/** Props shared by both controlled and uncontrolled `CheckboxCard.Root` usage.
- * Extends the native `<button>` props (minus the checkbox-managed ones). */
+/**
+ * Shared base for both {@link CheckboxCardRootProps} variants — the native
+ * `<button>` attributes (minus the ones the component owns: `type`, `role`,
+ * `aria-checked`, and `defaultChecked`), plus the `asChild` escape hatch and a
+ * typed `ref`.
+ */
 export type CheckboxCardRootBaseProps = Omit<
   ComponentProps<"button">,
   "type" | "role" | "aria-checked" | "defaultChecked"
 > & {
-  /** Render the child element instead of the default `<button>`. */
+  /**
+   * When `true`, render the consumer's own element instead of the default
+   * `<button type="button">`, merging `role`, `aria-checked`, `data-state`,
+   * the composed `onClick`, `disabled`, and `ref` onto it via the
+   * {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
-  /** Ref to the rendered element. */
+  /** Forwarded to the rendered element (the `<button>` by default). */
   ref?: Ref<HTMLButtonElement>;
 };
 
-/** Uncontrolled `CheckboxCard.Root` props: the component owns the checked
- * state, seeded by an optional `defaultChecked`. */
+/**
+ * Uncontrolled variant of {@link CheckboxCardRootProps}: the component owns the
+ * checked state, seeded by an optional `defaultChecked`. Pass `defaultChecked`
+ * (or omit it); `checked` is forbidden.
+ */
 export type CheckboxCardRootUncontrolledProps = CheckboxCardRootBaseProps & {
-  /** Checked state on first render. */
+  /** Tri-state checked value on first render (`true` / `false` /
+   * `"indeterminate"`). Defaults to `false` when omitted.
+   * @default false */
   defaultChecked?: CheckedState;
+  /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
   checked?: never;
-  /** Called with the new boolean checked state when it changes. */
+  /** Called with the new **boolean** checked state whenever the card toggles.
+   * An indeterminate card resolves to `true` on first click. Optional in
+   * uncontrolled mode. */
   onCheckedChange?: (checked: boolean) => void;
 };
 
-/** Controlled `CheckboxCard.Root` props: the caller owns the checked state via
- * `checked` and is notified through the required `onCheckedChange`. */
+/**
+ * Controlled variant of {@link CheckboxCardRootProps}: the caller owns the
+ * checked state via `checked` and is notified through the required
+ * `onCheckedChange`. Pass both together; `defaultChecked` is forbidden.
+ */
 export type CheckboxCardRootControlledProps = CheckboxCardRootBaseProps & {
+  /** Forbidden in controlled mode — use `checked` instead. */
   defaultChecked?: never;
-  /** Current checked state. */
+  /** The controlled tri-state checked value (`true` / `false` /
+   * `"indeterminate"`). Must be kept in sync by the parent via
+   * `onCheckedChange`. */
   checked: CheckedState;
-  /** Called with the new boolean checked state when the user toggles. */
+  /** Called with the new **boolean** checked state when the user toggles. An
+   * indeterminate card resolves to `true` on click. Required in controlled
+   * mode. */
   onCheckedChange: (checked: boolean) => void;
 };
 
-/** Props for `CheckboxCard.Root` — resolves to either the controlled or
- * uncontrolled prop shape. */
+/**
+ * Props for {@link CheckboxCardRoot | `CheckboxCard.Root`}.
+ *
+ * Resolves to either {@link CheckboxCardRootUncontrolledProps} or
+ * {@link CheckboxCardRootControlledProps} — only one shape is accepted by
+ * TypeScript at a time. Both accept the tri-state {@link CheckedState}
+ * (`boolean | "indeterminate"`).
+ */
 export type CheckboxCardRootProps =
   | CheckboxCardRootUncontrolledProps
   | CheckboxCardRootControlledProps;

package/src/Collapsible/Collapsible.tsx

@@ -1,5 +1,5 @@
 import { Ref } from "react";
-import type { ReactElement } from "react";
+import type { CSSProperties, ReactElement } from "react";
 
 import { Slot } from "../Slot/index.ts";
 
@@ -39,9 +39,18 @@ import type {
  * mirrored onto Root, Trigger, and Content so a single selector covers
  * every sub-component.
  *
+ * **Context.** Root establishes {@link CollapsibleContext}, from which
+ * {@link CollapsibleTrigger}, {@link CollapsibleContent}, and
+ * {@link CollapsibleTriggerIcon} read the open state, the `disabled` flag,
+ * the `toggle` action, and the generated `triggerId` / `contentId` that
+ * wire the Trigger's `aria-controls` to the Content's `id`. Rendering any
+ * sub-component outside a Root throws.
+ *
  * **Styling hooks.** `data-state="open" | "closed"` and
  * `data-disabled="true" | "false"` are emitted on the rendered container.
  *
+ * @extends HTMLDivElement
+ *
  * @example Uncontrolled
  * ```tsx
  * <Collapsible.Root defaultOpen>
@@ -89,6 +98,7 @@ export function CollapsibleRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 CollapsibleRoot.displayName = "CollapsibleRoot";
 
 /**
@@ -133,6 +143,8 @@ CollapsibleRoot.displayName = "CollapsibleRoot";
  * - `data-state="open" | "closed"` on the rendered element.
  * - `data-disabled="true" | "false"`.
  *
+ * @extends HTMLButtonElement
+ *
  * @example Basic
  * ```tsx
  * <Collapsible.Trigger>Toggle</Collapsible.Trigger>
@@ -206,10 +218,21 @@ CollapsibleTrigger.displayName = "CollapsibleTrigger";
  * this by passing `aria-hidden` explicitly (it appears after the
  * automatic value in the spread).
  *
+ * **`collapsedHeight` prop.** Pass `collapsedHeight` to show a **clamped
+ * preview** of the panel while closed (the read-more pattern) instead of
+ * hiding it. A number is pixels; a string is a verbatim CSS length. When set,
+ * the panel is always mounted and never `hidden` / `aria-hidden` (the preview
+ * is real content), and the value is published as the
+ * `--primitiv-collapsible-collapsed-height` custom property for the styling
+ * layer to clamp the closed height to and anchor a bottom fade-shadow, keyed
+ * off `data-state="closed"`.
+ *
  * **Styling hooks.**
  * - `data-state="open" | "closed"` on the rendered element.
  * - `data-disabled="true" | "false"`.
  *
+ * @extends HTMLDivElement
+ *
  * @example Default (hidden attribute)
  * ```tsx
  * <Collapsible.Content>Hidden content</Collapsible.Content>
@@ -225,17 +248,38 @@ CollapsibleTrigger.displayName = "CollapsibleTrigger";
 export function CollapsibleContent({
   children,
   forceMount = false,
+  collapsedHeight,
+  style,
   ...rest
 }: CollapsibleContentProps): ReactElement {
   const { open, disabled, contentId } = useCollapsibleContext();
 
+  // A clamped preview keeps real, readable content on screen while closed, so
+  // it is always mounted (forceMount is implied) and never `hidden` /
+  // `aria-hidden`. The height it clamps to is published as a custom property
+  // the styling layer consumes.
+  const clamped = collapsedHeight != null;
+  const mounted = forceMount || clamped;
+  // Always publish the custom property; an `undefined` value (no
+  // `collapsedHeight`) is dropped by React, so there is no redundant guard to
+  // go stale. `clamped` gates only the mount / aria behaviour, where it is
+  // observable.
+  const mergedStyle = {
+    "--primitiv-collapsible-collapsed-height":
+      typeof collapsedHeight === "number"
+        ? `${collapsedHeight}px`
+        : collapsedHeight,
+    ...style,
+  } as CSSProperties;
+
   return (
     <div
       id={contentId}
-      hidden={forceMount ? undefined : !open}
-      aria-hidden={forceMount && !open ? true : undefined}
+      hidden={mounted ? undefined : !open}
+      aria-hidden={forceMount && !open && !clamped ? true : undefined}
       data-state={open ? "open" : "closed"}
       data-disabled={disabled}
+      style={mergedStyle}
       {...rest}
     >
       {children}
@@ -261,6 +305,8 @@ CollapsibleContent.displayName = "CollapsibleContent";
  * - `data-state="open" | "closed"` on the rendered `<span>`.
  * - `aria-hidden="true"` on the rendered `<span>`.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Inline SVG
  * ```tsx
  * <Collapsible.Trigger>

package/src/Collapsible/README.md

@@ -97,6 +97,46 @@ is applied automatically so assistive technology skips the off-screen
 content. It is removed when the panel opens. Consumers can override this
 by passing `aria-hidden` explicitly.
 
+## `collapsedHeight` — clamped preview (read-more)
+
+Pass `collapsedHeight` to `Collapsible.Content` to show a **clamped preview**
+of the panel while closed instead of hiding it — the read-more / "show more"
+pattern. A number is pixels; a string is a verbatim CSS length (`"4rem"`,
+`"20cqi"`).
+
+```tsx
+<Collapsible.Content collapsedHeight={96} className="preview">
+  A long passage whose first 96px stays visible while collapsed…
+</Collapsible.Content>
+```
+
+When set, the panel is **always mounted** and never receives `hidden` /
+`aria-hidden` (the preview is real, readable content — so `forceMount` is
+implied), and the value is published as the
+`--primitiv-collapsible-collapsed-height` custom property. The styling layer
+clamps the closed height to it and anchors a bottom fade-shadow, keyed off
+`data-state="closed"`:
+
+```css
+.preview {
+  overflow: hidden;
+  max-block-size: var(--primitiv-collapsible-collapsed-height);
+  transition: max-block-size 250ms;
+}
+.preview[data-state="open"] {
+  max-block-size: 100vh; /* or a large enough clamp */
+}
+/* Bottom fade over the clamped preview, gone once open. */
+.preview[data-state="closed"]::after {
+  content: "";
+  position: absolute;
+  inset-inline: 0;
+  inset-block-end: 0;
+  block-size: 2rem;
+  background: linear-gradient(to bottom, transparent, var(--surface));
+}
+```
+
 ## `asChild` composition
 
 `Collapsible.Trigger` accepts an `asChild` prop to render any child

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

@@ -119,6 +119,95 @@ describe("Collapsible asChild and keyboard tests", () => {
     expect(content).toBeVisible();
   });
 
+  // A plain <div> (no native button semantics and no role) never fires a
+  // synthetic click on Enter/Space, so these isolate the Trigger's own
+  // keydown handler — the anchor tests above can toggle via native activation
+  // even when the handler does nothing, masking mutations in it.
+  it("toggles on Enter for a non-native asChild element", async () => {
+    const user = userEvent.setup();
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger asChild>
+          <div tabIndex={0} data-testid="trigger">
+            Toggle
+          </div>
+        </Collapsible.Trigger>
+        <Collapsible.Content data-testid="content">Content</Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    screen.getByTestId("trigger").focus();
+    await user.keyboard("{Enter}");
+    expect(screen.getByTestId("content")).toBeVisible();
+  });
+
+  it("toggles on Space for a non-native asChild element", async () => {
+    const user = userEvent.setup();
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger asChild>
+          <div tabIndex={0} data-testid="trigger">
+            Toggle
+          </div>
+        </Collapsible.Trigger>
+        <Collapsible.Content data-testid="content">Content</Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    screen.getByTestId("trigger").focus();
+    await user.keyboard(" ");
+    expect(screen.getByTestId("content")).toBeVisible();
+  });
+
+  it("does not toggle on a non-activation key", async () => {
+    const user = userEvent.setup();
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger asChild>
+          <div tabIndex={0} data-testid="trigger">
+            Toggle
+          </div>
+        </Collapsible.Trigger>
+        <Collapsible.Content data-testid="content">Content</Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    screen.getByTestId("trigger").focus();
+    await user.keyboard("a");
+    expect(screen.getByTestId("content")).not.toBeVisible();
+  });
+
+  it("does not toggle on Enter when disabled (non-native asChild)", async () => {
+    const user = userEvent.setup();
+    render(
+      <Collapsible.Root disabled>
+        <Collapsible.Trigger asChild>
+          <div tabIndex={0} data-testid="trigger">
+            Toggle
+          </div>
+        </Collapsible.Trigger>
+        <Collapsible.Content data-testid="content">Content</Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    screen.getByTestId("trigger").focus();
+    await user.keyboard("{Enter}");
+    expect(screen.getByTestId("content")).not.toBeVisible();
+  });
+
+  it("does not toggle on Space when disabled (non-native asChild)", async () => {
+    const user = userEvent.setup();
+    render(
+      <Collapsible.Root disabled>
+        <Collapsible.Trigger asChild>
+          <div tabIndex={0} data-testid="trigger">
+            Toggle
+          </div>
+        </Collapsible.Trigger>
+        <Collapsible.Content data-testid="content">Content</Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    screen.getByTestId("trigger").focus();
+    await user.keyboard(" ");
+    expect(screen.getByTestId("content")).not.toBeVisible();
+  });
+
   it("should NOT toggle on Enter or Space when disabled (asChild)", async () => {
     // Arrange
     const user = userEvent.setup();

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

@@ -58,6 +58,33 @@ describe("Collapsible basic rendering tests", () => {
     expect(content.id).not.toBe("");
   });
 
+  it("gives the Trigger a '-trigger' suffixed id distinct from the Content id", () => {
+    // Arrange
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content data-testid="content">Content</Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Toggle" });
+    const content = screen.getByTestId("content");
+
+    // Assert — a derived, non-empty id that cannot collide with the content's.
+    expect(trigger.id).toMatch(/-trigger$/);
+    expect(trigger.id).not.toBe(content.id);
+  });
+
+  it("sets a displayName on the compound and each sub-component", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `Collapsible`, `Collapsible.Root`, and the underlying function are one
+    // object (Object.assign compound), so the compound's "Collapsible" alias is
+    // the observable Root displayName; the sub-components are distinct objects.
+    expect(Collapsible.displayName).toBe("Collapsible");
+    expect(Collapsible.Trigger.displayName).toBe("CollapsibleTrigger");
+    expect(Collapsible.Content.displayName).toBe("CollapsibleContent");
+    expect(Collapsible.TriggerIcon.displayName).toBe("CollapsibleTriggerIcon");
+  });
+
   it("should hide Content when closed", () => {
     // Arrange
     render(

package/src/Collapsible/__tests__/Collapsible.collapsedHeight.test.tsx

@@ -0,0 +1,140 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Collapsible } from "../Collapsible";
+
+const VAR = "--primitiv-collapsible-collapsed-height";
+
+describe("Collapsible collapsedHeight (clamped preview)", () => {
+  it("keeps the closed panel mounted and un-hidden (a visible preview)", () => {
+    // Arrange & Act
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content collapsedHeight={64} data-testid="content">
+          Content
+        </Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    const content = screen.getByTestId("content");
+
+    // Assert — visible preview, not hidden, not aria-hidden
+    expect(content).toBeInTheDocument();
+    expect(content).not.toHaveAttribute("hidden");
+    expect(content).not.toHaveAttribute("aria-hidden");
+    expect(content).toHaveAttribute("data-state", "closed");
+  });
+
+  it("publishes a numeric collapsedHeight as a pixel custom property", () => {
+    // Arrange & Act
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content collapsedHeight={64} data-testid="content">
+          Content
+        </Collapsible.Content>
+      </Collapsible.Root>,
+    );
+
+    // Assert
+    expect(
+      screen.getByTestId("content").style.getPropertyValue(VAR),
+    ).toBe("64px");
+  });
+
+  it("uses a string collapsedHeight verbatim as a CSS length", () => {
+    // Arrange & Act
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content collapsedHeight="4rem" data-testid="content">
+          Content
+        </Collapsible.Content>
+      </Collapsible.Root>,
+    );
+
+    // Assert
+    expect(
+      screen.getByTestId("content").style.getPropertyValue(VAR),
+    ).toBe("4rem");
+  });
+
+  it("toggles data-state open/closed while staying mounted", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content collapsedHeight={64} data-testid="content">
+          Content
+        </Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    const content = screen.getByTestId("content");
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Toggle" }));
+
+    // Assert — opened, still no hidden/aria-hidden, var still present
+    expect(content).toHaveAttribute("data-state", "open");
+    expect(content).not.toHaveAttribute("hidden");
+    expect(content).not.toHaveAttribute("aria-hidden");
+    expect(content.style.getPropertyValue(VAR)).toBe("64px");
+  });
+
+  it("merges the custom property with a consumer style", () => {
+    // Arrange & Act
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content
+          collapsedHeight={64}
+          style={{ color: "rgb(1, 2, 3)" }}
+          data-testid="content"
+        >
+          Content
+        </Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    const content = screen.getByTestId("content");
+
+    // Assert — both the private var and the consumer's declaration survive
+    expect(content.style.getPropertyValue(VAR)).toBe("64px");
+    expect(content.style.color).toBe("rgb(1, 2, 3)");
+  });
+
+  it("does not aria-hide a clamped panel even when forceMount is also set", () => {
+    // Arrange & Act — clamped wins: the preview stays readable, so no
+    // aria-hidden despite forceMount being present.
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content
+          forceMount
+          collapsedHeight={64}
+          data-testid="content"
+        >
+          Content
+        </Collapsible.Content>
+      </Collapsible.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("content")).not.toHaveAttribute("aria-hidden");
+  });
+
+  it("does not set the custom property when collapsedHeight is omitted", () => {
+    // Arrange & Act
+    render(
+      <Collapsible.Root>
+        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+        <Collapsible.Content data-testid="content">Content</Collapsible.Content>
+      </Collapsible.Root>,
+    );
+    const content = screen.getByTestId("content");
+
+    // Assert — default fully-hidden behaviour is untouched
+    expect(content.style.getPropertyValue(VAR)).toBe("");
+    expect(content).toHaveAttribute("hidden");
+  });
+});