@primitiv-ui/react 0.1.28 → 0.1.30

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");
+  });
+});

package/src/Collapsible/hooks/useCollapsibleTrigger.ts

@@ -9,7 +9,9 @@ export function useCollapsibleTrigger({
   ref,
   onClick,
   onKeyDown,
-  asChild = false,
+  // No default: the `CollapsibleTrigger` component always supplies a resolved
+  // `asChild` boolean, so a default here would be unreachable (dead) code.
+  asChild,
   ...rest
 }: Omit<CollapsibleTriggerProps, "children">) {
   const { open, disabled, toggle, triggerId, contentId } =

package/src/Collapsible/types.ts

@@ -1,68 +1,135 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
-/** Props common to both controlled and uncontrolled `Collapsible.Root` modes. */
+/**
+ * Shared base for both {@link CollapsibleRootProps} variants — the native
+ * `<div>` attributes (minus the conflicting `onChange`) plus the `disabled`
+ * flag common to both state modes.
+ */
 export type CollapsibleRootBaseProps = Omit<
   ComponentProps<"div">,
   "onChange"
 > & {
-  /** When `true`, disables the widget and short-circuits trigger activation. */
+  /**
+   * When `true`, disables the widget: the {@link CollapsibleTriggerProps |
+   * Trigger} renders `aria-disabled="true"` (staying focusable) and both
+   * click and keyboard activation are short-circuited. Mirrored as
+   * `data-disabled` onto Root, Trigger, and Content.
+   * @default false
+   */
   disabled?: boolean;
 };
 
 /**
- * Props for `Collapsible.Root` in uncontrolled mode — the component owns the
- * open state. Pass `defaultOpen` to set the initial value; `open` is forbidden.
+ * Uncontrolled variant of {@link CollapsibleRootProps}: the component owns
+ * the open state. Pass `defaultOpen` (or omit it); `open` is forbidden.
  */
 export type CollapsibleRootUncontrolledProps = CollapsibleRootBaseProps & {
-  /** Initial open state when uncontrolled. Defaults to `false`. */
+  /**
+   * Initial open state on first render. The component owns the value
+   * thereafter.
+   * @default false
+   */
   defaultOpen?: boolean;
-  /** Forbidden in uncontrolled mode. */
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
-  /** Called whenever the open state changes. */
+  /** Called with the new open state on every toggle. Optional in
+   * uncontrolled mode (Collapsible fires it in both modes). */
   onOpenChange?: (open: boolean) => void;
 };
 
 /**
- * Props for `Collapsible.Root` in controlled mode — the parent owns the open
- * value. Pass `open` and `onOpenChange` together; `defaultOpen` is forbidden.
+ * Controlled variant of {@link CollapsibleRootProps}: the parent owns the
+ * open value. Pass `open` and `onOpenChange` together; `defaultOpen` is
+ * forbidden.
  */
 export type CollapsibleRootControlledProps = CollapsibleRootBaseProps & {
-  /** The controlled open state. */
+  /** The controlled open state. Must be kept in sync by the parent via
+   * `onOpenChange`. */
   open: boolean;
-  /** Called whenever the component requests an open-state change. */
+  /** Called with the requested open state on every toggle. Required in
+   * controlled mode. */
   onOpenChange: (open: boolean) => void;
-  /** Forbidden in controlled mode. */
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
 };
 
-/** Props for `Collapsible.Root` — discriminated controlled/uncontrolled union. */
+/**
+ * Props for {@link CollapsibleRoot | `Collapsible.Root`}.
+ *
+ * Resolves to either {@link CollapsibleRootUncontrolledProps} or
+ * {@link CollapsibleRootControlledProps} — only one shape is accepted by
+ * TypeScript at a time.
+ */
 export type CollapsibleRootProps =
   | CollapsibleRootUncontrolledProps
   | CollapsibleRootControlledProps;
 
-/** Props for `Collapsible.Trigger`, the button that toggles the panel. */
+/**
+ * Props for {@link CollapsibleTrigger | `Collapsible.Trigger`}, the button
+ * that toggles the panel.
+ *
+ * Generic over the rendered element type so `asChild` consumers can type
+ * the forwarded `ref` (e.g. `Collapsible.Trigger<HTMLAnchorElement>`).
+ */
 export type CollapsibleTriggerProps<T extends HTMLElement = HTMLButtonElement> =
   Omit<ComponentProps<"button">, "ref"> & {
-    /** Trigger content (label, icon, etc.). */
+    /** Trigger content (label, and optionally a
+     * {@link CollapsibleTriggerIconProps | TriggerIcon}). */
     children: ReactNode;
-    /** Render the child element instead of the default `<button>`. */
+    /**
+     * Render a single consumer-supplied child element instead of the default
+     * `<button>`, merging the Trigger's ARIA, handlers, and ref onto it via
+     * the {@link Slot} pattern. When `asChild` and the Root is `disabled`,
+     * `role="button"` is injected so `aria-disabled` is semantically valid.
+     * @default false
+     */
     asChild?: boolean;
-    /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
-     * `asChild`, specify the child's element type (e.g. `HTMLAnchorElement`). */
+    /** Forwarded to the rendered element. Defaults to `HTMLButtonElement`;
+     * when using `asChild`, specify the child's element type (e.g.
+     * `HTMLAnchorElement`). Composed with the library's internal ref. */
     ref?: Ref<T>;
   };
 
-/** Props for `Collapsible.Content`, the panel revealed when open. */
+/**
+ * Props for {@link CollapsibleContent | `Collapsible.Content`}, the panel
+ * revealed when open.
+ */
 export type CollapsibleContentProps = ComponentProps<"div"> & {
   /** Panel content. */
   children: ReactNode;
-  /** Keep the panel mounted when closed so transitions can be CSS-driven. */
+  /**
+   * Keep the panel mounted (and in the DOM) even when closed, so open/close
+   * transitions can be CSS-driven. When closed under `forceMount`, the panel
+   * gets `aria-hidden="true"` instead of the `hidden` attribute. Consumers
+   * may override `aria-hidden` explicitly.
+   * @default false
+   */
   forceMount?: boolean;
+  /**
+   * Show a **clamped preview** of the panel while closed instead of hiding it
+   * entirely — the "collapsed height" / read-more pattern. A `number` is taken
+   * as pixels; a string is used verbatim as a CSS length (e.g. `"4rem"`,
+   * `"20cqi"`). When set:
+   *
+   * - the panel is always mounted and never gets the `hidden` attribute or
+   *   `aria-hidden` (the preview is real, readable content), so `forceMount` is
+   *   implied;
+   * - the value is emitted as the `--primitiv-collapsible-collapsed-height`
+   *   custom property on the panel, which the styling layer clamps the closed
+   *   height to (e.g. `max-block-size`) and anchors a bottom fade-shadow to,
+   *   keyed off `data-state="closed"`.
+   *
+   * Leave unset for the default fully-hidden / grid-collapse behaviour.
+   */
+  collapsedHeight?: number | string;
 };
 
-/** Props for `Collapsible.TriggerIcon`, the aria-hidden icon wrapper. */
+/**
+ * Props for {@link CollapsibleTriggerIcon | `Collapsible.TriggerIcon`}, the
+ * `aria-hidden` icon wrapper carrying an open/closed `data-state` hook.
+ */
 export type CollapsibleTriggerIconProps = ComponentProps<"span"> & {
-  /** The icon to render (inline SVG or icon component). */
+  /** The icon to render (inline SVG or an icon component). */
   children: ReactNode;
 };