@varialkit/expandcollapse 0.1.0

package/docs.md

@@ -0,0 +1,99 @@
+# ExpandCollapse
+
+ExpandCollapse provides an accordion-style disclosure for revealing or hiding related content.
+Use ExpandCollapseGroup to coordinate multiple sections.
+
+## Why It Exists
+
+ExpandCollapse helps keep dense layouts readable by letting users reveal details only when needed.
+It is ideal for settings panels, sidebars, summaries, and advanced sections where the content should
+stay related but not always visible.
+
+## How It Works
+
+- Each section renders a header button and a body container.
+- Clicking the header toggles visibility of the body content.
+- Body expand/collapse is animated with JS-measured height for smoother motion and less jump.
+- ExpandCollapseGroup can manage multiple sections and optionally allow more than one open at a time.
+- The `size` prop adjusts header spacing and typography while respecting global density.
+
+## How to Use
+
+```tsx
+import { ExpandCollapse, ExpandCollapseGroup } from "@solara/expandcollapse";
+
+export function Example() {
+  return (
+    <ExpandCollapseGroup
+      defaultOpen={[0]}
+      showBottomBorder
+      showToggleAllButton
+      defaultExpandAll={false}
+      showAllLabel="Show all sections"
+      collapseAllLabel="Collapse all sections">
+      <ExpandCollapse title="Overview">Overview content</ExpandCollapse>
+      <ExpandCollapse title="Details">Detailed content</ExpandCollapse>
+    </ExpandCollapseGroup>
+  );
+}
+```
+
+## Group Toggle-All Behavior
+
+- Set `showToggleAllButton` to render a ghost button at the bottom-left of the group.
+- The button label switches between `showAllLabel` and `collapseAllLabel` based on current state.
+- `defaultExpandAll` initializes all sections as open.
+- If `defaultExpandAll` is `true`, it takes precedence over `defaultOpen`.
+
+## Icons
+
+You can render a leading icon before the title. Icons inherit the header text color.
+
+```tsx
+<ExpandCollapse title="Details" iconLeft="data_spreadsheet_search_24">
+  Content here
+</ExpandCollapse>
+```
+
+## Best Practices
+
+- Keep header titles short and scannable.
+- Use the right-side slot for metadata or counts.
+- Avoid nesting multiple accordion groups deeply.
+- Use `flush` when the accordion should align with surrounding container edges.
+- Use `paddingX` when the host layout needs a tighter or wider header row.
+- Use `iconLeft` to add contextual icons without replacing the chevron.
+
+## Props
+
+### ExpandCollapse
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | _Required_ | Header title content. |
+| `children` | `ReactNode` | _Required_ | Collapsible content. |
+| `isOpen` | `boolean` | | Controlled open state. |
+| `onToggle` | `(isOpen: boolean) => void` | | Open state callback. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Header size. |
+| `iconPosition` | `"left" \| "right"` | `"right"` | Chevron placement. |
+| `iconLeft` | `SolaraIconName \| IconProps` | | Optional leading icon before the title. |
+| `rightContent` | `ReactNode` | | Optional content on the right side. |
+| `paddingX` | `string \| number` | | Horizontal padding override. |
+| `flush` | `boolean` | `false` | Remove horizontal padding. |
+| `showBottomBorder` | `boolean` | `false` | Show a divider on the bottom edge of this item. |
+| `className` | `string` | | Custom class name. |
+
+### ExpandCollapseGroup
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `allowMultiple` | `boolean` | `false` | Allow multiple sections open at once. |
+| `defaultOpen` | `number[]` | `[]` | Indexes to open by default. |
+| `paddingX` | `string \| number` | | Shared horizontal padding override. |
+| `flush` | `boolean` | | Shared flush state. |
+| `showBottomBorder` | `boolean` | `false` | Show a divider under each item. |
+| `showToggleAllButton` | `boolean` | `false` | Show a ghost button at the bottom to expand/collapse all. |
+| `defaultExpandAll` | `boolean` | `false` | Start with all sections expanded. |
+| `showAllLabel` | `string` | `"Show all"` | Bottom button label when sections are collapsed. |
+| `collapseAllLabel` | `string` | `"Collapse all"` | Bottom button label when sections are expanded. |
+| `className` | `string` | | Custom class name. |

package/examples/index.tsx

@@ -0,0 +1 @@
+export { stories } from "../examples";

package/examples.tsx

@@ -0,0 +1,288 @@
+import React from "react";
+import type { ReactElement } from "react";
+import { iconNames } from "@solara/icons";
+import type { SolaraIconName } from "@solara/icons";
+import { ExpandCollapse, ExpandCollapseGroup } from "./src/ExpandCollapse";
+import type { ExpandCollapseSize } from "./src/ExpandCollapse.types";
+
+type StoryControlOption = {
+  label: string;
+  value: string;
+};
+
+type StoryControl = {
+  name: string;
+  label?: string;
+  type: "select" | "text" | "boolean" | "number";
+  options?: Array<string | StoryControlOption>;
+  min?: number;
+  max?: number;
+  step?: number;
+};
+
+type StoryDefinition = {
+  title: string;
+  description?: string;
+  render: (props: Record<string, unknown>) => ReactElement;
+  controls?: StoryControl[];
+  initialProps?: Record<string, unknown>;
+  showProps?: boolean;
+  applyPropsToPreview?: boolean;
+  code?: string;
+};
+
+export const stories: Record<string, StoryDefinition> = {
+  playground: {
+    title: "Playground",
+    description: "Expand or collapse sections with optional right-side metadata.",
+    render: (props) => (
+      <ExpandCollapse
+        title={(props.title as string) ?? "Project details"}
+        size={props.size as ExpandCollapseSize}
+        iconPosition={(props.iconPosition as "left" | "right") ?? "right"}
+        iconLeft={(props.iconLeft as SolaraIconName) || undefined}
+        rightContent={
+          props.showRightContent ? (
+            <span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>
+              Updated today
+            </span>
+          ) : null
+        }
+        flush={props.flush as boolean}>
+        <div style={{ display: "grid", gap: "0.5rem" }}>
+          <p style={{ margin: 0 }}>
+            Keep related metadata grouped so it is easy to scan when expanded.
+          </p>
+          <p style={{ margin: 0 }}>Add links, fields, or actions here.</p>
+        </div>
+      </ExpandCollapse>
+    ),
+    controls: [
+      { name: "title", label: "Title", type: "text" },
+      {
+        name: "size",
+        label: "Size",
+        type: "select",
+        options: ["sm", "md", "lg"],
+      },
+      {
+        name: "iconPosition",
+        label: "Icon Position",
+        type: "select",
+        options: ["left", "right"],
+      },
+      {
+        name: "iconLeft",
+        label: "Icon Left",
+        type: "select",
+        options: ["", ...iconNames],
+      },
+      { name: "showRightContent", label: "Right Content", type: "boolean" },
+      { name: "flush", label: "Flush", type: "boolean" },
+    ],
+    initialProps: {
+      title: "Project details",
+      size: "md",
+      iconPosition: "right",
+      showRightContent: true,
+      flush: false,
+      iconLeft: "",
+    },
+  },
+  group: {
+    title: "Group",
+    showProps: true,
+    render: (props) => (
+      <ExpandCollapseGroup
+        defaultOpen={[0]}
+        showBottomBorder={props.showBottomBorder as boolean}
+        showToggleAllButton={props.showToggleAllButton as boolean}
+        defaultExpandAll={props.defaultExpandAll as boolean}
+        showAllLabel={(props.showAllLabel as string) ?? "Show all"}
+        collapseAllLabel={(props.collapseAllLabel as string) ?? "Collapse all"}>
+        <ExpandCollapse title="Overview">
+          <p style={{ margin: 0 }}>High-level summary and status go here.</p>
+        </ExpandCollapse>
+        <ExpandCollapse title="Metrics">
+          <p style={{ margin: 0 }}>Show charts, KPIs, or tables in this section.</p>
+        </ExpandCollapse>
+        <ExpandCollapse title="Timeline">
+          <p style={{ margin: 0 }}>List milestones or upcoming events.</p>
+        </ExpandCollapse>
+      </ExpandCollapseGroup>
+    ),
+    controls: [
+      { name: "showBottomBorder", label: "Show Bottom Border", type: "boolean" },
+      { name: "showToggleAllButton", label: "Show Toggle All Button", type: "boolean" },
+      { name: "defaultExpandAll", label: "Default Expand All", type: "boolean" },
+      { name: "showAllLabel", label: "Show All Label", type: "text" },
+      { name: "collapseAllLabel", label: "Collapse All Label", type: "text" },
+    ],
+    initialProps: {
+      showBottomBorder: true,
+      showToggleAllButton: true,
+      defaultExpandAll: false,
+      showAllLabel: "Show all",
+      collapseAllLabel: "Collapse all",
+    },
+    code: `import { ExpandCollapse, ExpandCollapseGroup } from "@solara/expandcollapse";
+
+export function Example() {
+  return (
+    <ExpandCollapseGroup defaultOpen={[0]} showBottomBorder showToggleAllButton>
+      <ExpandCollapse title="Overview">
+        <p style={{ margin: 0 }}>High-level summary and status go here.</p>
+      </ExpandCollapse>
+      <ExpandCollapse title="Metrics">
+        <p style={{ margin: 0 }}>Show charts, KPIs, or tables in this section.</p>
+      </ExpandCollapse>
+      <ExpandCollapse title="Timeline">
+        <p style={{ margin: 0 }}>List milestones or upcoming events.</p>
+      </ExpandCollapse>
+    </ExpandCollapseGroup>
+  );
+}
+`,
+  },
+  toggleAll: {
+    title: "Toggle All",
+    description: "Show a bottom ghost button to expand/collapse all items.",
+    showProps: true,
+    render: (props) => (
+      <ExpandCollapseGroup
+        showToggleAllButton={props.showToggleAllButton as boolean}
+        defaultExpandAll={props.defaultExpandAll as boolean}
+        showBottomBorder={props.showBottomBorder as boolean}
+        showAllLabel={(props.showAllLabel as string) ?? "Show all"}
+        collapseAllLabel={(props.collapseAllLabel as string) ?? "Collapse all"}>
+        <ExpandCollapse title="Overview">
+          <p style={{ margin: 0 }}>High-level summary and status go here.</p>
+        </ExpandCollapse>
+        <ExpandCollapse title="Metrics">
+          <p style={{ margin: 0 }}>Show charts, KPIs, or tables in this section.</p>
+        </ExpandCollapse>
+        <ExpandCollapse title="Timeline">
+          <p style={{ margin: 0 }}>List milestones or upcoming events.</p>
+        </ExpandCollapse>
+      </ExpandCollapseGroup>
+    ),
+    controls: [
+      { name: "showBottomBorder", label: "Show Bottom Border", type: "boolean" },
+      { name: "showToggleAllButton", label: "Show Toggle All Button", type: "boolean" },
+      { name: "defaultExpandAll", label: "Default Expand All", type: "boolean" },
+      { name: "showAllLabel", label: "Show All Label", type: "text" },
+      { name: "collapseAllLabel", label: "Collapse All Label", type: "text" },
+    ],
+    initialProps: {
+      showBottomBorder: true,
+      showToggleAllButton: true,
+      defaultExpandAll: false,
+      showAllLabel: "Show all",
+      collapseAllLabel: "Collapse all",
+    },
+    code: `import { ExpandCollapse, ExpandCollapseGroup } from "@solara/expandcollapse";
+
+export function Example() {
+  return (
+    <ExpandCollapseGroup showToggleAllButton defaultExpandAll={false} showBottomBorder>
+      <ExpandCollapse title="Overview">
+        <p style={{ margin: 0 }}>High-level summary and status go here.</p>
+      </ExpandCollapse>
+      <ExpandCollapse title="Metrics">
+        <p style={{ margin: 0 }}>Show charts, KPIs, or tables in this section.</p>
+      </ExpandCollapse>
+      <ExpandCollapse title="Timeline">
+        <p style={{ margin: 0 }}>List milestones or upcoming events.</p>
+      </ExpandCollapse>
+    </ExpandCollapseGroup>
+  );
+}
+`,
+  },
+  metadata: {
+    title: "Metadata + Actions",
+    description: "Show related context in the header while keeping the details collapsed by default.",
+    showProps: false,
+    render: () => (
+      <ExpandCollapseGroup defaultOpen={[1]}>
+        <ExpandCollapse
+          title="Client summary"
+          rightContent={<span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>3 items</span>}
+        >
+          <p style={{ margin: 0 }}>Keep the overview short so the toggle remains scannable.</p>
+        </ExpandCollapse>
+        <ExpandCollapse
+          title="Next steps"
+          rightContent={
+            <span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>Due Friday</span>
+          }
+        >
+          <div style={{ display: "grid", gap: "0.5rem" }}>
+            <p style={{ margin: 0 }}>Schedule the follow-up call.</p>
+            <p style={{ margin: 0 }}>Share the revised estimate.</p>
+          </div>
+        </ExpandCollapse>
+        <ExpandCollapse title="Dependencies">
+          <p style={{ margin: 0 }}>List external blockers or required approvals here.</p>
+        </ExpandCollapse>
+      </ExpandCollapseGroup>
+    ),
+    code: `import { ExpandCollapse, ExpandCollapseGroup } from "@solara/expandcollapse";
+
+export function Example() {
+  return (
+    <ExpandCollapseGroup defaultOpen={[1]}>
+      <ExpandCollapse
+        title="Client summary"
+        rightContent={<span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>3 items</span>}
+      >
+        <p style={{ margin: 0 }}>Keep the overview short so the toggle remains scannable.</p>
+      </ExpandCollapse>
+      <ExpandCollapse
+        title="Next steps"
+        rightContent={<span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>Due Friday</span>}
+      >
+        <div style={{ display: "grid", gap: "0.5rem" }}>
+          <p style={{ margin: 0 }}>Schedule the follow-up call.</p>
+          <p style={{ margin: 0 }}>Share the revised estimate.</p>
+        </div>
+      </ExpandCollapse>
+      <ExpandCollapse title="Dependencies">
+        <p style={{ margin: 0 }}>List external blockers or required approvals here.</p>
+      </ExpandCollapse>
+    </ExpandCollapseGroup>
+  );
+}
+`,
+  },
+  icons: {
+    title: "Icons",
+    description: "Add leading icons for extra context.",
+    showProps: false,
+    render: () => (
+      <ExpandCollapseGroup defaultOpen={[0]}>
+        <ExpandCollapse title="Overview" iconLeft="data_spreadsheet_search_24">
+          <p style={{ margin: 0 }}>Use icons to reinforce section meaning.</p>
+        </ExpandCollapse>
+        <ExpandCollapse title="Security" iconLeft="arrow_line_up_16">
+          <p style={{ margin: 0 }}>Add compliance and audit details here.</p>
+        </ExpandCollapse>
+      </ExpandCollapseGroup>
+    ),
+    code: `import { ExpandCollapse, ExpandCollapseGroup } from "@solara/expandcollapse";
+
+export function Example() {
+  return (
+    <ExpandCollapseGroup defaultOpen={[0]}>
+      <ExpandCollapse title="Overview" iconLeft="data_spreadsheet_search_24">
+        <p style={{ margin: 0 }}>Use icons to reinforce section meaning.</p>
+      </ExpandCollapse>
+      <ExpandCollapse title="Security" iconLeft="arrow_line_up_16">
+        <p style={{ margin: 0 }}>Add compliance and audit details here.</p>
+      </ExpandCollapse>
+    </ExpandCollapseGroup>
+  );
+}
+`,
+  },
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@varialkit/expandcollapse",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples/index.tsx"
+  },
+  "dependencies": {
+    "@varialkit/icons": "0.1.0",
+    "@varialkit/button": "0.1.0"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0"
+  }
+}

package/src/ExpandCollapse.scss

@@ -0,0 +1,147 @@
+.solara-expand-collapse {
+  overflow: hidden;
+  font-family: var(--font-body);
+  color: var(--color-text-primary);
+  border-radius: var(--radius-2);
+}
+
+.solara-expand-collapse--bottom-border {
+  border-bottom: 1px solid var(--color-divider-secondary);
+}
+
+.solara-expand-collapse__header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+  background-color: transparent;
+  border: none;
+  padding: calc(var(--space-2) * var(--spacing-multiplier))
+    calc(var(--expand-collapse-px, var(--space-3)) * var(--spacing-multiplier));
+  cursor: pointer;
+  text-align: left;
+  font-size: var(--font-size-caption-scaled);
+  line-height: var(--line-height-caption-scaled);
+  border-radius: inherit;
+  transition: background-color 0.2s ease;
+  box-sizing: border-box;
+
+  &:hover {
+    background-color: var(--color-surface-100);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px var(--color-focus-halo);
+  }
+}
+
+.solara-expand-collapse__title {
+  font-weight: 500;
+  flex-grow: 1;
+  color: var(--color-text-primary);
+}
+
+.solara-expand-collapse__leading {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: currentColor;
+  margin-right: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-expand-collapse__leading .solara-icon [stroke]:not([stroke="none"]) {
+  stroke: currentColor;
+}
+
+.solara-expand-collapse__leading .solara-icon [fill]:not([fill="none"]) {
+  fill: currentColor;
+}
+
+.solara-expand-collapse__right {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  margin-left: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-expand-collapse__icon {
+  transition: transform 0.2s ease-in-out;
+  flex-shrink: 0;
+  color: var(--color-text-secondary);
+}
+
+.solara-expand-collapse__icon--open {
+  transform: rotate(90deg);
+}
+
+.solara-expand-collapse__header--icon-left {
+  justify-content: flex-start;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-expand-collapse__header--icon-left .solara-expand-collapse__leading {
+  margin-right: 0;
+}
+
+.solara-expand-collapse__content {
+  padding: calc(var(--space-2) * var(--spacing-multiplier))
+    calc(var(--expand-collapse-px, var(--space-3)) * var(--spacing-multiplier));
+  border-top: 1px solid var(--color-divider-secondary);
+  color: var(--color-text-secondary);
+}
+
+.solara-expand-collapse__panel {
+  overflow: hidden;
+  transition:
+    height 240ms cubic-bezier(0.22, 1, 0.36, 1),
+    opacity 180ms ease;
+  will-change: height, opacity;
+}
+
+.solara-expand-collapse--size-sm .solara-expand-collapse__header {
+  padding: calc(var(--space-1) * var(--spacing-multiplier))
+    calc(var(--expand-collapse-px, var(--space-2)) * var(--spacing-multiplier));
+  font-size: var(--font-size-footnote-scaled);
+  line-height: var(--line-height-footnote-scaled);
+}
+
+.solara-expand-collapse--size-sm .solara-expand-collapse__content {
+  padding: calc(var(--space-2) * var(--spacing-multiplier))
+    calc(var(--expand-collapse-px, var(--space-2)) * var(--spacing-multiplier));
+}
+
+.solara-expand-collapse--size-lg .solara-expand-collapse__header {
+  padding: calc(var(--space-3) * var(--spacing-multiplier))
+    calc(var(--expand-collapse-px, var(--space-4)) * var(--spacing-multiplier));
+  font-size: var(--font-size-body-scaled);
+  line-height: var(--line-height-body-scaled);
+}
+
+.solara-expand-collapse--size-lg .solara-expand-collapse__content {
+  padding: calc(var(--space-3) * var(--spacing-multiplier))
+    calc(var(--expand-collapse-px, var(--space-4)) * var(--spacing-multiplier));
+}
+
+.solara-expand-collapse--flush {
+  border-radius: 0;
+}
+
+.solara-expand-collapse--flush .solara-expand-collapse__header,
+.solara-expand-collapse--flush .solara-expand-collapse__content {
+  padding-left: 0;
+  padding-right: 0;
+}
+
+.solara-expand-collapse-group__toggle-all {
+  display: flex;
+  justify-content: flex-start;
+  margin-top: calc(var(--space-1) * var(--spacing-multiplier));
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .solara-expand-collapse__panel,
+  .solara-expand-collapse__icon {
+    transition: none;
+  }
+}

package/src/ExpandCollapse.tsx

@@ -0,0 +1,255 @@
+import React, { Children, cloneElement, useLayoutEffect, useRef, useState } from "react";
+import { Button } from "@solara/button";
+import { Icon } from "@solara/icons";
+import type { IconProps } from "@solara/icons";
+import type { ExpandCollapseProps, ExpandCollapseGroupProps } from "./ExpandCollapse.types";
+import "./ExpandCollapse.scss";
+
+type ExpandCollapseIcon = IconProps | IconProps["name"];
+
+const normalizeIconProps = (icon: ExpandCollapseIcon): IconProps =>
+  typeof icon === "string" ? { name: icon } : icon;
+
+const resolveIconProps = (icon: ExpandCollapseIcon): IconProps => {
+  const iconProps = normalizeIconProps(icon);
+
+  return {
+    ...iconProps,
+    style: {
+      ...iconProps.style,
+      color: "currentColor",
+    },
+  };
+};
+
+const ChevronIcon = ({ open }: { open: boolean }) => (
+  <svg
+    viewBox="0 0 20 20"
+    width="16"
+    height="16"
+    className={[
+      "solara-expand-collapse__icon",
+      open ? "solara-expand-collapse__icon--open" : null,
+    ]
+      .filter(Boolean)
+      .join(" ")}
+    aria-hidden="true">
+    <path
+      d="M7 4.5l6 5.5-6 5.5"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+export const ExpandCollapse: React.FC<ExpandCollapseProps> = ({
+  title,
+  children,
+  isOpen: controlledIsOpen,
+  onToggle,
+  size = "md",
+  className,
+  iconPosition = "right",
+  iconLeft,
+  rightContent,
+  paddingX,
+  flush = false,
+  showBottomBorder = false,
+}) => {
+  const [internalIsOpen, setInternalIsOpen] = useState(false);
+  const isOpen = controlledIsOpen ?? internalIsOpen;
+  const contentPanelRef = useRef<HTMLDivElement>(null);
+  const [panelHeight, setPanelHeight] = useState<number | "auto">(isOpen ? "auto" : 0);
+  const [isAnimating, setIsAnimating] = useState(false);
+
+  const handleToggle = () => {
+    const next = !isOpen;
+    if (controlledIsOpen === undefined) {
+      setInternalIsOpen(next);
+    }
+    onToggle?.(next);
+  };
+
+  useLayoutEffect(() => {
+    const panel = contentPanelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    const nextHeight = panel.scrollHeight;
+
+    if (isOpen) {
+      // Opening: animate to measured height, then switch to auto after transition.
+      if (panelHeight !== "auto") {
+        setIsAnimating(true);
+        setPanelHeight(nextHeight);
+      }
+      return;
+    }
+
+    if (panelHeight === 0) {
+      return;
+    }
+
+    // Closing from auto requires one frame at a fixed height before collapsing.
+    if (panelHeight === "auto") {
+      setPanelHeight(nextHeight);
+      requestAnimationFrame(() => {
+        setIsAnimating(true);
+        setPanelHeight(0);
+      });
+      return;
+    }
+
+    setIsAnimating(true);
+    setPanelHeight(0);
+  }, [isOpen, panelHeight, children]);
+
+  const handlePanelTransitionEnd: React.TransitionEventHandler<HTMLDivElement> = (event) => {
+    if (event.propertyName !== "height") {
+      return;
+    }
+
+    if (isOpen) {
+      setPanelHeight("auto");
+    }
+    setIsAnimating(false);
+  };
+
+  const headerStyle =
+    paddingX !== undefined && !flush
+      ? {
+          "--expand-collapse-px":
+            typeof paddingX === "number" ? `${paddingX}px` : paddingX,
+        }
+      : undefined;
+
+  const rootClasses = [
+    "solara-expand-collapse",
+    `solara-expand-collapse--size-${size}`,
+    flush ? "solara-expand-collapse--flush" : null,
+    showBottomBorder ? "solara-expand-collapse--bottom-border" : null,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const headerClasses = [
+    "solara-expand-collapse__header",
+    iconPosition === "left" ? "solara-expand-collapse__header--icon-left" : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const leadingIcon = iconLeft ? (
+    <span className="solara-expand-collapse__leading" aria-hidden="true">
+      <Icon {...resolveIconProps(iconLeft)} />
+    </span>
+  ) : null;
+
+  const panelStyle = {
+    height: panelHeight === "auto" ? "auto" : `${panelHeight}px`,
+    opacity: isOpen ? 1 : 0,
+  };
+
+  return (
+    <div className={rootClasses}>
+      <button
+        type="button"
+        className={headerClasses}
+        style={headerStyle}
+        onClick={handleToggle}
+        aria-expanded={isOpen}>
+        {iconPosition === "left" ? <ChevronIcon open={isOpen} /> : null}
+        {leadingIcon}
+        <span className="solara-expand-collapse__title">{title}</span>
+        <span className="solara-expand-collapse__right">
+          {rightContent}
+          {iconPosition === "right" ? <ChevronIcon open={isOpen} /> : null}
+        </span>
+      </button>
+      <div
+        ref={contentPanelRef}
+        className="solara-expand-collapse__panel"
+        style={panelStyle}
+        onTransitionEnd={handlePanelTransitionEnd}
+        aria-hidden={!isOpen && !isAnimating}>
+        <div className="solara-expand-collapse__content">{children}</div>
+      </div>
+    </div>
+  );
+};
+
+ExpandCollapse.displayName = "ExpandCollapse";
+
+export const ExpandCollapseGroup: React.FC<ExpandCollapseGroupProps> = ({
+  children,
+  allowMultiple = false,
+  defaultOpen = [],
+  className,
+  paddingX,
+  flush,
+  showBottomBorder = false,
+  showToggleAllButton = false,
+  defaultExpandAll = false,
+  showAllLabel = "Show all",
+  collapseAllLabel = "Collapse all",
+}) => {
+  const childrenArray = Children.toArray(children);
+  const allIndexes = childrenArray.map((_, index) => index);
+
+  const [openIndexes, setOpenIndexes] = useState<number[]>(
+    defaultExpandAll ? allIndexes : defaultOpen,
+  );
+
+  const handleToggle = (index: number) => {
+    setOpenIndexes((prevOpenIndexes) => {
+      if (allowMultiple) {
+        return prevOpenIndexes.includes(index)
+          ? prevOpenIndexes.filter((item) => item !== index)
+          : [...prevOpenIndexes, index];
+      }
+      return prevOpenIndexes.includes(index) ? [] : [index];
+    });
+  };
+
+  const isAllExpanded = allIndexes.length > 0 && openIndexes.length === allIndexes.length;
+
+  const handleToggleAll = () => {
+    // Global toggle uses current group state to either open every section or collapse all.
+    setOpenIndexes(isAllExpanded ? [] : allIndexes);
+  };
+
+  const items = Children.map(childrenArray, (child, index) => {
+    if (React.isValidElement<ExpandCollapseProps>(child)) {
+      return cloneElement(child, {
+        isOpen: openIndexes.includes(index),
+        onToggle: () => handleToggle(index),
+        paddingX: child.props.paddingX ?? paddingX,
+        flush: child.props.flush ?? flush,
+        showBottomBorder: child.props.showBottomBorder ?? showBottomBorder,
+      });
+    }
+    return child;
+  });
+
+  return (
+    <div className={className}>
+      {items}
+      {showToggleAllButton ? (
+        <div className="solara-expand-collapse-group__toggle-all">
+          <Button
+            type="button"
+            variant="ghost"
+            size="small"
+            label={isAllExpanded ? collapseAllLabel : showAllLabel}
+            onClick={handleToggleAll}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+};

package/src/ExpandCollapse.types.ts

@@ -0,0 +1,56 @@
+import type React from "react";
+import type { IconProps } from "@solara/icons";
+
+export type ExpandCollapseSize = "sm" | "md" | "lg";
+
+export interface ExpandCollapseProps {
+  /** Title content for the trigger row. */
+  title: React.ReactNode;
+  /** Collapsible body content. */
+  children: React.ReactNode;
+  /** Controlled open state. */
+  isOpen?: boolean;
+  /** Called when the open state changes. */
+  onToggle?: (isOpen: boolean) => void;
+  /** Size of the trigger row. */
+  size?: ExpandCollapseSize;
+  /** Root class name. */
+  className?: string;
+  /** Icon placement. */
+  iconPosition?: "left" | "right";
+  /** Optional leading icon displayed before the title. */
+  iconLeft?: IconProps | IconProps["name"];
+  /** Optional content on the right side of the header. */
+  rightContent?: React.ReactNode;
+  /** Horizontal padding override (number is px). */
+  paddingX?: string | number;
+  /** Remove horizontal padding + border radius. */
+  flush?: boolean;
+  /** Show a divider on the bottom edge of this item. */
+  showBottomBorder?: boolean;
+}
+
+export interface ExpandCollapseGroupProps {
+  /** ExpandCollapse children. */
+  children: React.ReactNode;
+  /** Allow multiple sections open simultaneously. */
+  allowMultiple?: boolean;
+  /** Indexes of sections that start open. */
+  defaultOpen?: number[];
+  /** Group class name. */
+  className?: string;
+  /** Shared horizontal padding override. */
+  paddingX?: string | number;
+  /** Shared flush setting. */
+  flush?: boolean;
+  /** Show a border under each item. */
+  showBottomBorder?: boolean;
+  /** Render a bottom button that toggles all sections open/closed. */
+  showToggleAllButton?: boolean;
+  /** Start with all sections expanded. */
+  defaultExpandAll?: boolean;
+  /** Label used when all sections are collapsed. */
+  showAllLabel?: string;
+  /** Label used when all sections are expanded. */
+  collapseAllLabel?: string;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { ExpandCollapse, ExpandCollapseGroup } from "./ExpandCollapse";
+export type {
+  ExpandCollapseProps,
+  ExpandCollapseGroupProps,
+  ExpandCollapseSize,
+} from "./ExpandCollapse.types";