@primitiv-ui/react 0.1.0

package/src/Collapsible/Collapsible.tsx

@@ -0,0 +1,316 @@
+import { Ref } from "react";
+
+import { Slot } from "../Slot";
+
+import { CollapsibleContext, useCollapsibleContext } from "./CollapsibleContext";
+import { useCollapsibleRoot, useCollapsibleTrigger } from "./hooks";
+
+import type {
+  CollapsibleRootProps,
+  CollapsibleTriggerProps,
+  CollapsibleContentProps,
+  CollapsibleTriggerIconProps,
+} from "./types";
+
+/**
+ * The root of a Collapsible widget — owns the open/closed state, provides
+ * context to descendants, and renders a plain `<div>`.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultOpen` (or omit it to start closed).
+ *   The component owns and updates the open state internally; consumers
+ *   may still observe transitions by passing `onOpenChange`.
+ * - **Controlled** — pass `open` *and* `onOpenChange` together. The parent
+ *   owns the open value; the component defers every state change back
+ *   through the callback. Passing `defaultOpen` alongside `open` is a type
+ *   error.
+ *
+ * Unlike Accordion in this library, Collapsible fires `onOpenChange` in
+ * **both** uncontrolled and controlled modes.
+ *
+ * **Disabled.** Pass `disabled` to render `aria-disabled="true"` on the
+ * Trigger and short-circuit click and keyboard activation. The Trigger
+ * remains focusable so keyboard users can discover it. `data-disabled` is
+ * mirrored onto Root, Trigger, and Content so a single selector covers
+ * every sub-component.
+ *
+ * **Styling hooks.** `data-state="open" | "closed"` and
+ * `data-disabled="true" | "false"` are emitted on the rendered container.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Collapsible.Root defaultOpen>
+ *   <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ *   <Collapsible.Content>Hidden content</Collapsible.Content>
+ * </Collapsible.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Collapsible.Root open={open} onOpenChange={setOpen}>
+ *   <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ *   <Collapsible.Content>Hidden content</Collapsible.Content>
+ * </Collapsible.Root>
+ * ```
+ */
+export function CollapsibleRoot({
+  children,
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+  disabled = false,
+  ...rest
+}: CollapsibleRootProps) {
+  const { contextValue } = useCollapsibleRoot(
+    controlledOpen,
+    defaultOpen,
+    onOpenChange,
+    disabled,
+  );
+
+  return (
+    <CollapsibleContext.Provider value={contextValue}>
+      <div
+        data-state={contextValue.open ? "open" : "closed"}
+        data-disabled={disabled}
+        {...rest}
+      >
+        {children}
+      </div>
+    </CollapsibleContext.Provider>
+  );
+}
+
+CollapsibleRoot.displayName = "CollapsibleRoot";
+
+/**
+ * The button that toggles the collapsible open or closed. Renders
+ * `<button type="button">` by default and wires up all required ARIA
+ * attributes, click handling, and keyboard activation automatically.
+ *
+ * **Disabled behaviour.** When the parent `Collapsible.Root` is `disabled`
+ * the Trigger is rendered with `aria-disabled="true"` and
+ * `data-disabled="true"` instead of the native HTML `disabled` attribute.
+ * This keeps the button focusable so keyboard users can discover it,
+ * while preventing toggle activation. Click handlers and keyboard
+ * activation are short-circuited entirely — no toggle, no consumer
+ * `onClick`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render an arbitrary child element
+ * instead of the default `<button>`. All ARIA attributes, event handlers,
+ * and the internal ref are merged onto the child following the standard
+ * composition rules:
+ * - Event handlers compose — child's handler runs first, then the trigger's.
+ * - `style` is shallow-merged (child wins on collisions).
+ * - `className` strings are concatenated.
+ * - Refs from both sides are composed via `composeRefs`.
+ *
+ * When `asChild` is `true` and the parent is `disabled`, `role="button"`
+ * is automatically injected so that `aria-disabled` is semantically valid
+ * on non-button elements (e.g. `<a>`, `<div>`). Without a button role the
+ * `aria-disabled` attribute has no defined meaning in the ARIA spec.
+ *
+ * **Keyboard activation.** Native `<button>` activates on `Enter` and
+ * `Space` for free. Under `asChild`, the rendered element may not (e.g.
+ * `<div role="button">`), so the Trigger handles `Enter` and `Space`
+ * explicitly: `preventDefault` suppresses any native activation (such as
+ * an anchor following its `href`) and the toggle is dispatched directly.
+ *
+ * **Ref forwarding.** A `ref` prop (React 19 ref-as-prop style) is
+ * forwarded to the underlying DOM element — useful for imperative focus
+ * management. The generic defaults to `HTMLButtonElement`; supply a
+ * different type when using `asChild` with a non-button element.
+ *
+ * **Styling hooks.**
+ * - `data-state="open" | "closed"` on the rendered element.
+ * - `data-disabled="true" | "false"`.
+ *
+ * @example Basic
+ * ```tsx
+ * <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+ * ```
+ *
+ * @example asChild — render an anchor with collapsible semantics
+ * ```tsx
+ * <Collapsible.Trigger<HTMLAnchorElement> asChild>
+ *   <a href="#section">Toggle</a>
+ * </Collapsible.Trigger>
+ * ```
+ */
+export function CollapsibleTrigger<
+  T extends HTMLElement = HTMLButtonElement,
+>({
+  ref,
+  children,
+  onClick,
+  onKeyDown,
+  asChild = false,
+  ...rest
+}: CollapsibleTriggerProps<T>) {
+  const { triggerProps } = useCollapsibleTrigger({
+    ref: ref as Ref<HTMLButtonElement>,
+    onClick,
+    onKeyDown,
+    asChild,
+    ...rest,
+  });
+
+  if (asChild) {
+    return <Slot {...triggerProps}>{children}</Slot>;
+  }
+
+  return (
+    <button type="button" {...triggerProps}>
+      {children}
+    </button>
+  );
+}
+
+CollapsibleTrigger.displayName = "CollapsibleTrigger";
+
+/**
+ * The panel that is revealed when the associated `Collapsible.Trigger` is
+ * activated. Renders a `<div>` whose visibility is controlled by the
+ * `hidden` attribute and whose `id` is automatically wired to the
+ * Trigger's `aria-controls`.
+ *
+ * **`forceMount` prop.** By default the panel is removed from the visual
+ * and accessibility trees with `hidden` when closed. Pass `forceMount` to
+ * keep the panel in the DOM at all times so consumers can drive open /
+ * close transitions with CSS — for instance with CSS Grid:
+ *
+ * ```css
+ * .panel {
+ *   display: grid;
+ *   grid-template-rows: 0fr;
+ *   transition: grid-template-rows 250ms;
+ * }
+ * .panel[data-state="open"] {
+ *   grid-template-rows: 1fr;
+ * }
+ * .panel > * {
+ *   overflow: hidden;
+ * }
+ * ```
+ *
+ * When `forceMount` is `true` and the panel is closed, `aria-hidden="true"`
+ * is set automatically so assistive technology ignores the off-screen
+ * content. It is removed when the panel opens. Consumers can override
+ * this by passing `aria-hidden` explicitly (it appears after the
+ * automatic value in the spread).
+ *
+ * **Styling hooks.**
+ * - `data-state="open" | "closed"` on the rendered element.
+ * - `data-disabled="true" | "false"`.
+ *
+ * @example Default (hidden attribute)
+ * ```tsx
+ * <Collapsible.Content>Hidden content</Collapsible.Content>
+ * ```
+ *
+ * @example With forceMount for CSS-driven animation
+ * ```tsx
+ * <Collapsible.Content forceMount className="panel">
+ *   Content that animates open and closed.
+ * </Collapsible.Content>
+ * ```
+ */
+export function CollapsibleContent({
+  children,
+  forceMount = false,
+  ...rest
+}: CollapsibleContentProps) {
+  const { open, disabled, contentId } = useCollapsibleContext();
+
+  return (
+    <div
+      id={contentId}
+      hidden={forceMount ? undefined : !open}
+      aria-hidden={forceMount && !open ? true : undefined}
+      data-state={open ? "open" : "closed"}
+      data-disabled={disabled}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}
+
+CollapsibleContent.displayName = "CollapsibleContent";
+
+/**
+ * A wrapper that hides its icon child from the accessibility tree and
+ * provides a `data-state` hook for open/close animations. Accepts any
+ * renderable React content as a child — an inline `<svg>`, a component
+ * from a third-party icon library (lucide-react, react-icons, etc.), or
+ * any custom icon component.
+ *
+ * Renders a `<span>` with `aria-hidden="true"` around the child so the
+ * icon is hidden from assistive technology regardless of whether the
+ * child component forwards unknown props or emits its own ARIA surface.
+ *
+ * **Styling hooks.**
+ * - `data-state="open" | "closed"` on the rendered `<span>`.
+ * - `aria-hidden="true"` on the rendered `<span>`.
+ *
+ * @example Inline SVG
+ * ```tsx
+ * <Collapsible.Trigger>
+ *   Toggle
+ *   <Collapsible.TriggerIcon>
+ *     <svg viewBox="0 0 24 24"><path d="M6 9l6 6 6-6" /></svg>
+ *   </Collapsible.TriggerIcon>
+ * </Collapsible.Trigger>
+ * ```
+ *
+ * @example Third-party icon component
+ * ```tsx
+ * import { ChevronDown } from "lucide-react";
+ *
+ * <Collapsible.Trigger>
+ *   Toggle
+ *   <Collapsible.TriggerIcon>
+ *     <ChevronDown />
+ *   </Collapsible.TriggerIcon>
+ * </Collapsible.Trigger>
+ * ```
+ */
+export function CollapsibleTriggerIcon({
+  children,
+  ...rest
+}: CollapsibleTriggerIconProps) {
+  const { open } = useCollapsibleContext();
+
+  return (
+    <span
+      aria-hidden="true"
+      data-state={open ? "open" : "closed"}
+      {...rest}
+    >
+      {children}
+    </span>
+  );
+}
+
+CollapsibleTriggerIcon.displayName = "CollapsibleTriggerIcon";
+
+type CollapsibleCompound = typeof CollapsibleRoot & {
+  Root: typeof CollapsibleRoot;
+  Trigger: typeof CollapsibleTrigger;
+  Content: typeof CollapsibleContent;
+  TriggerIcon: typeof CollapsibleTriggerIcon;
+};
+
+const CollapsibleCompound: CollapsibleCompound = Object.assign(CollapsibleRoot, {
+  Root: CollapsibleRoot,
+  Trigger: CollapsibleTrigger,
+  Content: CollapsibleContent,
+  TriggerIcon: CollapsibleTriggerIcon,
+});
+
+CollapsibleCompound.displayName = "Collapsible";
+
+export { CollapsibleCompound as Collapsible };

package/src/Collapsible/CollapsibleContext.ts

@@ -0,0 +1,7 @@
+import { createStrictContext } from "../utils";
+import { CollapsibleContextValue } from "./types";
+
+export const [CollapsibleContext, useCollapsibleContext] =
+  createStrictContext<CollapsibleContextValue>(
+    "Collapsible sub-components must be rendered inside a <Collapsible.Root>.",
+  );

package/src/Collapsible/README.md

@@ -0,0 +1,174 @@
+# Collapsible
+
+A compound component for showing and hiding a single panel of content.
+The single-item analogue of [Accordion](../Accordion/README.md).
+
+```tsx
+import { Collapsible } from "@primitiv-ui/react";
+
+<Collapsible.Root defaultOpen>
+  <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+  <Collapsible.Content>
+    The content revealed by the trigger.
+  </Collapsible.Content>
+</Collapsible.Root>;
+```
+
+## Sub-components
+
+| Export                    | Role          | Notes                                                                                                              |
+| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `Collapsible.Root`        | State owner   | Uncontrolled (`defaultOpen`) or controlled (`open` + `onOpenChange`); `disabled` short-circuits Trigger activation |
+| `Collapsible.Trigger`     | Toggle button | Supports `asChild`, ref forwarding, explicit Enter/Space handling                                                  |
+| `Collapsible.Content`     | Hidden panel  | Hidden via the `hidden` attribute; supports `forceMount` for CSS animation                                         |
+| `Collapsible.TriggerIcon` | Icon wrapper  | Injects `aria-hidden` and `data-state` onto a decorative icon                                                      |
+
+## Keyboard interaction
+
+| Key               | Behaviour              |
+| ----------------- | ---------------------- |
+| `Enter` / `Space` | Toggle the collapsible |
+
+`<button>` activates on `Enter` and `Space` natively. The Trigger also
+handles both keys explicitly so that `asChild` rendering on non-button
+elements (anchors, divs, custom components) still toggles correctly.
+`preventDefault` suppresses native activation (e.g. an anchor following
+its `href`) so the toggle never double-fires.
+
+## State modes
+
+- **Uncontrolled** — pass `defaultOpen` (or omit to start closed).
+  `onOpenChange` is optional and fires on every toggle.
+- **Controlled** — pass `open` and `onOpenChange` together. The parent
+  owns the value; the component defers every state change back through
+  the callback.
+
+The two shapes are discriminated at the type level: passing `defaultOpen`
+alongside `open` is a type error.
+
+Unlike `Accordion`, `Collapsible` fires `onOpenChange` in **both** modes.
+
+## Disabled
+
+Pass `disabled` on `Collapsible.Root` to render `aria-disabled="true"` on
+the Trigger (without the native `disabled` attribute, so it remains
+focusable for keyboard discovery) and short-circuit click and keyboard
+activation:
+
+```tsx
+<Collapsible.Root disabled>
+  <Collapsible.Trigger>Toggle</Collapsible.Trigger>
+  <Collapsible.Content>Currently unavailable.</Collapsible.Content>
+</Collapsible.Root>
+```
+
+`data-disabled` is mirrored onto Root, Trigger, and Content so a single
+`[data-disabled="true"]` selector covers every sub-component.
+
+## `forceMount` for CSS animations
+
+By default the content panel is removed from accessibility and visual
+rendering via the `hidden` attribute. Pass `forceMount` to keep it in the
+DOM and drive open/close visually with CSS. The recommended pattern uses
+CSS Grid so consumers don't have to measure content height in JavaScript:
+
+```tsx
+<Collapsible.Content forceMount className="panel">
+  Content that animates open and closed.
+</Collapsible.Content>
+```
+
+```css
+.panel {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 250ms ease;
+}
+.panel[data-state="open"] {
+  grid-template-rows: 1fr;
+}
+.panel > * {
+  overflow: hidden;
+}
+```
+
+When `forceMount` is active and the panel is closed, `aria-hidden="true"`
+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.
+
+## `asChild` composition
+
+`Collapsible.Trigger` accepts an `asChild` prop to render any child
+element with full collapsible semantics. All ARIA attributes, event
+handlers, and the internal ref are merged onto the child (child handler
+runs first, then the trigger's):
+
+```tsx
+<Collapsible.Trigger<HTMLAnchorElement> asChild>
+  <a href="#section">Toggle</a>
+</Collapsible.Trigger>
+```
+
+`Enter` and `Space` are handled in `onKeyDown` so non-button elements
+(e.g. `<a>`, `<div>`) toggle correctly without relying on native click
+behaviour. `preventDefault` suppresses native activation so an anchor
+doesn't follow its `href` while toggling.
+
+When `asChild` is combined with `disabled`, `role="button"` is injected
+automatically so that `aria-disabled` is semantically valid on non-button
+elements:
+
+```tsx
+<Collapsible.Root disabled>
+  <Collapsible.Trigger asChild>
+    <a href="#section">Toggle</a>
+    {/* rendered with role="button" aria-disabled="true" */}
+  </Collapsible.Trigger>
+  <Collapsible.Content>…</Collapsible.Content>
+</Collapsible.Root>
+```
+
+## Trigger icon
+
+Wrap a decorative icon in `Collapsible.TriggerIcon` to hide it from
+assistive technology and expose a `data-state` hook for rotation
+animations. The child can be any renderable React content — an inline
+`<svg>`, a component from a third-party icon library (lucide-react,
+react-icons, etc.), or a custom icon component. `aria-hidden` and
+`data-state` are placed on a wrapping `<span>`, so they work regardless
+of whether the icon component forwards unknown props.
+
+```tsx
+import { ChevronDown } from "lucide-react";
+
+<Collapsible.Trigger>
+  Toggle
+  <Collapsible.TriggerIcon>
+    <ChevronDown />
+  </Collapsible.TriggerIcon>
+</Collapsible.Trigger>;
+```
+
+## Styling hooks
+
+```css
+/* Trigger open/closed — rotate a chevron icon */
+[data-state="open"] .chevron {
+  transform: rotate(180deg);
+}
+
+/* Content panel — animate via CSS Grid (see forceMount above) */
+.panel[data-state="closed"] {
+  grid-template-rows: 0fr;
+}
+
+/* Disabled trigger */
+[aria-disabled="true"] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+`data-state` (`"open"` | `"closed"`) and `data-disabled` (`"true"` |
+`"false"`) are available on every rendered sub-component.