Merge pull request #85 from kleros/feat/expand-button-custom-accordion

feat: custom-accordion-expand-button

Author: tractorss

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kleros/ui-components-library",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "UI components library which implements the Kleros design system.",
   "source": "./src/lib/index.ts",
   "main": "./dist/index.js",

src/lib/accordion/accordion-item.tsx

@@ -1,56 +1,94 @@
-import React, { ReactNode } from "react";
+import React, { ReactNode, useMemo } from "react";
 import { useElementSize } from "../../hooks/useElementSize";
 import Plus from "../../assets/svgs/accordion/plus.svg";
 import Minus from "../../assets/svgs/accordion/minus.svg";
 
 import { Button } from "react-aria-components";
 import { cn } from "../../utils";
 
-interface AccordionItemProps {
+export interface AccordionItemProps {
   setExpanded: React.Dispatch<React.SetStateAction<number>>;
   index: number;
+  /**
+   * The title displayed in the accordion header.
+   *
+   * This is usually text, but can be any ReactNode.
+   */
   title: ReactNode;
+  /**
+   * The body/content of the accordion section.
+   * This is only visible when the item is expanded.
+   */
   body: ReactNode;
-  expanded?: boolean;
+  /**
+   * Custom render function for the expand/collapse button.
+   *
+   * This function receives:
+   *  - `expanded`: boolean => whether the item is currently expanded
+   *  - `toggle`: function => expands/collapses this item when called
+   *
+   * Example:
+   * ```
+   * expandButton={({ expanded, toggle }) => (
+   *   <button onClick={toggle}>
+   *     {expanded ? "-" : "+"}
+   *   </button>
+   * )}
+   * ```
+   *
+   * If not provided, a default + or − icon will be shown.
+   *
+   * This button does NOT need to manage its own state — calling `toggle()`
+   * properly expands/collapses the item.
+   */
+  expandButton?: (options: {
+    expanded: boolean;
+    toggle: () => void;
+  }) => ReactNode;
+  expanded: boolean;
 }
 
 const AccordionItem: React.FC<AccordionItemProps> = ({
   title,
   body,
+  expandButton,
   index,
   expanded,
   setExpanded,
 }) => {
   const [ref, { height }] = useElementSize();
+  const ExpandButton = useMemo(() => {
+    if (expandButton) {
+      return expandButton({
+        expanded,
+        toggle: () => setExpanded(expanded ? -1 : index),
+      });
+    }
+    const IconComponent = expanded ? Minus : Plus;
+    return (
+      <IconComponent className="fill-klerosUIComponentsPrimaryText size-4 shrink-0" />
+    );
+  }, [expanded, expandButton, index, setExpanded]);
+
   return (
     <div className="my-2">
       <Button
         id="expand-button"
+        aria-expanded={expanded}
         className={cn(
           "bg-klerosUIComponentsWhiteBackground border-klerosUIComponentsStroke border",
           "hover-medium-blue hover-short-transition hover:cursor-pointer",
           "rounded-[3px] px-4 py-[11.5px] md:px-8",
-          "flex w-full items-center justify-between",
+          "flex w-full items-center justify-between gap-4",
         )}
         onPress={() => setExpanded(expanded ? -1 : index)}
       >
         {title}
-        {expanded ? (
-          <Minus
-            className={cn("fill-klerosUIComponentsPrimaryText size-4 shrink-0")}
-          />
-        ) : (
-          <Plus
-            className={cn("fill-klerosUIComponentsPrimaryText size-4 shrink-0")}
-          />
-        )}
+        {ExpandButton}
       </Button>
       <div
         style={{ height: expanded ? `${height.toString()}px` : 0 }}
-        className={cn(
-          expanded ? `overflow-visible` : "overflow-hidden",
-          "transition-[height] duration-(--klerosUIComponentsTransitionSpeed) ease-initial",
-        )}
+        className="overflow-hidden transition-[height] duration-(--klerosUIComponentsTransitionSpeed) ease-in-out"
       >
         <div className="p-4 md:p-8" id="body-wrapper" ref={ref}>
           {body}

src/lib/accordion/custom.tsx

@@ -1,30 +1,69 @@
-import React, { ReactNode, useState } from "react";
-import AccordionItem from "./accordion-item";
+import React, { useState } from "react";
+import AccordionItem, { AccordionItemProps } from "./accordion-item";
 import { cn, isUndefined } from "../../utils";
 
-interface AccordionItem {
-  title: ReactNode;
-  body: ReactNode;
-}
+export interface CustomAccordionProps {
+  /**
+   * Array of accordion items.
+   *
+   * Each item can optionally define its own `expandButton`.
+   * If omitted, the parent-level `expandButton` (if provided) is used.
+   */
 
-interface AccordionProps {
-  items: AccordionItem[];
+  items: Pick<AccordionItemProps, "title" | "body" | "expandButton">[];
   className?: string;
+
+  /**
+   * Index of the item to expand by default.
+   *
+   * - Set to a number (0-based index) to expand an item on mount
+   * - Leave undefined to start with all items collapsed
+   */
+
   defaultExpanded?: number;
+  /**
+   * A global expand/collapse button renderer applied to every item
+   * **unless that item provides its own expandButton**.
+   *
+   * Signature:
+   * ```
+   * expandButton?: ({ expanded, toggle }) => ReactNode;
+   * ```
+   *
+   * Example:
+   * ```
+   * expandButton={({ expanded, toggle }) => (
+   *   <Button onPress={toggle}>
+   *     {expanded ? <ChevronUp /> : <ChevronDown />}
+   *   </Button>
+   * )}
+   * ```
+   */
+  expandButton?: AccordionItemProps["expandButton"];
 }
 
-const CustomAccordion: React.FC<AccordionProps> = ({
+/**
+ * @description This component manages a list of collapsible accordion items,
+ * where only one item can be expanded at a time.
+ * @param props - CustomAccordionProps
+ * @returns JSX.Element
+ */
+function CustomAccordion({
   items,
   className,
   defaultExpanded,
+  expandButton,
   ...props
-}) => {
+}: Readonly<CustomAccordionProps>) {
   const [expanded, setExpanded] = useState(
-    !isUndefined(defaultExpanded) ? defaultExpanded : -1,
+    isUndefined(defaultExpanded) ? -1 : defaultExpanded,
   );
   return (
     <div
-      className={cn("box-border flex w-[1000px] flex-col", className)}
+      className={cn(
+        "box-border flex w-full max-w-[1000px] flex-col",
+        className,
+      )}
       {...props}
     >
       {items.map((item, index) => (
@@ -33,12 +72,13 @@ const CustomAccordion: React.FC<AccordionProps> = ({
           index={index}
           title={item.title}
           body={item.body}
+          expandButton={item.expandButton ?? expandButton}
           setExpanded={setExpanded}
           expanded={expanded === index}
         />
       ))}
     </div>
   );
-};
+}
 
 export default CustomAccordion;

src/lib/accordion/index.tsx

@@ -2,38 +2,56 @@ import React, { ReactNode, useState } from "react";
 import AccordionItem from "./accordion-item";
 import { cn, isUndefined } from "../../utils";
 
-interface AccordionItem {
+export interface AccordionItemProps {
   title: string;
   body: ReactNode;
   Icon?: React.FC<React.SVGAttributes<SVGElement>>;
   icon?: ReactNode;
 }
 
-interface AccordionProps {
-  items: AccordionItem[];
+export interface AccordionProps {
+  /**
+   * Array of accordion items.
+   */
+  items: AccordionItemProps[];
+  /**
+   * Index of the item to expand by default.
+   *
+   * - Set to a number (0-based index) to expand an item on mount
+   * - Leave undefined to start with all items collapsed
+   */
   defaultExpanded?: number;
   className?: string;
 }
 
-const DefaultTitle: React.FC<{ item: AccordionItem }> = ({ item }) => (
+const DefaultTitle: React.FC<{ item: AccordionItemProps }> = ({ item }) => (
   <>
     {item.icon ?? (item.Icon && <item.Icon />)}
     <p className="w-fit text-center text-base font-semibold">{item.title}</p>
   </>
 );
 
-const Accordion: React.FC<AccordionProps> = ({
+/**
+ * @description This component manages a list of collapsible accordion items,
+ * where only one item can be expanded at a time.
+ * @param props - AccordionProps
+ * @returns JSX.Element
+ */
+function Accordion({
   items,
   defaultExpanded,
   className,
   ...props
-}) => {
+}: Readonly<AccordionProps>) {
   const [expanded, setExpanded] = useState(
-    !isUndefined(defaultExpanded) ? defaultExpanded : -1,
+    isUndefined(defaultExpanded) ? -1 : defaultExpanded,
   );
   return (
     <div
-      className={cn("box-border flex w-[1000px] flex-col", className)}
+      className={cn(
+        "box-border flex w-full max-w-[1000px] flex-col",
+        className,
+      )}
       {...props}
     >
       {items.map((item, index) => (
@@ -48,6 +66,6 @@ const Accordion: React.FC<AccordionProps> = ({
       ))}
     </div>
   );
-};
+}
 
 export default Accordion;

src/stories/accordion.stories.tsx

@@ -3,19 +3,19 @@ import type { Meta, StoryObj } from "@storybook/react";
 
 import { IPreviewArgs } from "./utils";
 
-import Accordion from "../lib/accordion/index";
+import AccordionComponent from "../lib/accordion/index";
 
 const meta = {
-  component: Accordion,
+  component: AccordionComponent,
   title: "Accordion",
   tags: ["autodocs"],
-} satisfies Meta<typeof Accordion>;
+} satisfies Meta<typeof AccordionComponent>;
 
 export default meta;
 
 type Story = StoryObj<typeof meta> & IPreviewArgs;
 
-export const DarkTheme: Story = {
+export const Accordion: Story = {
   args: {
     className: "max-w-[80dvw]",