From 1bd9a4c535ed84f886db4dcbb670db694eb54215 Mon Sep 17 00:00:00 2001
From: Harman-singh-waraich <Waraichharman68@gmail.com>
Date: Thu, 11 Dec 2025 17:19:18 +0530
Subject: [PATCH 1/3] feat: custom-accordion-expand-button

---
 src/lib/accordion/accordion-item.tsx     |  77 +++++++++---
 src/lib/accordion/custom.tsx             |  64 ++++++++--
 src/lib/accordion/index.tsx              |  34 ++++--
 src/stories/accordion.stories.tsx        |   8 +-
 src/stories/custom-accordion.stories.tsx | 148 +++++++++++++++++++++++
 5 files changed, 290 insertions(+), 41 deletions(-)
 create mode 100644 src/stories/custom-accordion.stories.tsx

diff --git a/src/lib/accordion/accordion-item.tsx b/src/lib/accordion/accordion-item.tsx
index 7df4461..1b30424 100644
--- a/src/lib/accordion/accordion-item.tsx
+++ b/src/lib/accordion/accordion-item.tsx
@@ -1,4 +1,4 @@
-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";
@@ -6,51 +6,94 @@ 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(
+    () =>
+      expandButton ? (
+        expandButton({
+          expanded,
+          toggle: () => setExpanded(expanded ? -1 : index),
+        })
+      ) : expanded ? (
+        <Minus
+          className={cn("fill-klerosUIComponentsPrimaryText size-4 shrink-0")}
+        />
+      ) : (
+        <Plus
+          className={cn("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}
diff --git a/src/lib/accordion/custom.tsx b/src/lib/accordion/custom.tsx
index 3a5d75c..88c8b47 100644
--- a/src/lib/accordion/custom.tsx
+++ b/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,
   );
   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;
diff --git a/src/lib/accordion/index.tsx b/src/lib/accordion/index.tsx
index 2d3ea2a..c8f209b 100644
--- a/src/lib/accordion/index.tsx
+++ b/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,
   );
   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;
diff --git a/src/stories/accordion.stories.tsx b/src/stories/accordion.stories.tsx
index a1db66b..736d440 100644
--- a/src/stories/accordion.stories.tsx
+++ b/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]",
 
diff --git a/src/stories/custom-accordion.stories.tsx b/src/stories/custom-accordion.stories.tsx
new file mode 100644
index 0000000..85c90e6
--- /dev/null
+++ b/src/stories/custom-accordion.stories.tsx
@@ -0,0 +1,148 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { IPreviewArgs } from "./utils";
+
+import CustomAccordion from "../lib/accordion/custom";
+import Button from "../lib/button/index";
+
+const meta = {
+  component: CustomAccordion,
+  title: "CustomAccordion",
+  tags: ["autodocs"],
+} satisfies Meta<typeof CustomAccordion>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta> & IPreviewArgs;
+
+/** CustomAccordion provides the ability to render custom title, body and expandButton. */
+export const Accordion: Story = {
+  args: {
+    className: "max-w-[80dvw]",
+
+    items: [
+      {
+        title: (
+          <div className="text-klerosUIComponentsPrimaryText font-semibold">
+            How it works?
+          </div>
+        ),
+        body: (
+          <small className="text-klerosUIComponentsPrimaryText">
+            {"hello\nhello\n\n\n\n\nhello"}
+          </small>
+        ),
+        expandButton: ({ expanded, toggle }) => {
+          return expanded ? (
+            <Button text="Close" variant="secondary" onPress={toggle} />
+          ) : (
+            <Button text="Expand" onPress={toggle} />
+          );
+        },
+      },
+      {
+        title: (
+          <div className="text-klerosUIComponentsPrimaryText font-semibold">
+            How it works?
+          </div>
+        ),
+        body: (
+          <small className="text-klerosUIComponentsPrimaryText">hello</small>
+        ),
+      },
+    ],
+
+    themeUI: "dark",
+    backgroundUI: "light",
+  },
+};
+
+/** You can provide an expand button at Parent level for all Accordion Items */
+export const GlobalExpandButton: Story = {
+  args: {
+    className: "max-w-[80dvw]",
+
+    items: [
+      {
+        title: (
+          <div className="text-klerosUIComponentsPrimaryText font-semibold">
+            How it works?
+          </div>
+        ),
+        body: (
+          <small className="text-klerosUIComponentsPrimaryText">
+            {"hello\nhello\n\n\n\n\nhello"}
+          </small>
+        ),
+      },
+      {
+        title: (
+          <div className="text-klerosUIComponentsPrimaryText font-semibold">
+            How it works?
+          </div>
+        ),
+        body: (
+          <small className="text-klerosUIComponentsPrimaryText">hello</small>
+        ),
+      },
+    ],
+    expandButton: ({ expanded, toggle }) => {
+      return expanded ? (
+        <Button text="Close" variant="secondary" onPress={toggle} />
+      ) : (
+        <Button text="Expand" onPress={toggle} />
+      );
+    },
+    themeUI: "dark",
+    backgroundUI: "light",
+  },
+};
+
+/** Parent Expand Button can be ovverrided at Item level if required */
+export const ItemExpandButton: Story = {
+  args: {
+    className: "max-w-[80dvw]",
+
+    items: [
+      {
+        title: (
+          <div className="text-klerosUIComponentsPrimaryText font-semibold">
+            How it works?
+          </div>
+        ),
+        body: (
+          <small className="text-klerosUIComponentsPrimaryText">
+            {"hello\nhello\n\n\n\n\nhello"}
+          </small>
+        ),
+        expandButton: ({ expanded, toggle }) => {
+          return expanded ? (
+            <Button text="Item Close" variant="secondary" onPress={toggle} />
+          ) : (
+            <Button text="Item Expand" onPress={toggle} />
+          );
+        },
+      },
+      {
+        title: (
+          <div className="text-klerosUIComponentsPrimaryText font-semibold">
+            How it works?
+          </div>
+        ),
+        body: (
+          <small className="text-klerosUIComponentsPrimaryText">hello</small>
+        ),
+      },
+    ],
+    expandButton: (expanded) => {
+      return expanded ? (
+        <Button text="Close" variant="secondary" />
+      ) : (
+        <Button text="Expand" />
+      );
+    },
+    themeUI: "dark",
+    backgroundUI: "light",
+  },
+};

From 76cb79606005c9b3b02bd853a2ed3c7df870e804 Mon Sep 17 00:00:00 2001
From: Harman-singh-waraich <Waraichharman68@gmail.com>
Date: Thu, 11 Dec 2025 17:50:56 +0530
Subject: [PATCH 2/3] chore: rabbit-review

---
 src/lib/accordion/accordion-item.tsx     | 31 ++++++++++--------------
 src/lib/accordion/custom.tsx             |  4 +--
 src/lib/accordion/index.tsx              |  2 +-
 src/stories/custom-accordion.stories.tsx |  6 ++---
 4 files changed, 19 insertions(+), 24 deletions(-)

diff --git a/src/lib/accordion/accordion-item.tsx b/src/lib/accordion/accordion-item.tsx
index 1b30424..a0b4915 100644
--- a/src/lib/accordion/accordion-item.tsx
+++ b/src/lib/accordion/accordion-item.tsx
@@ -57,24 +57,19 @@ const AccordionItem: React.FC<AccordionItemProps> = ({
   setExpanded,
 }) => {
   const [ref, { height }] = useElementSize();
-  const ExpandButton = useMemo(
-    () =>
-      expandButton ? (
-        expandButton({
-          expanded,
-          toggle: () => setExpanded(expanded ? -1 : index),
-        })
-      ) : expanded ? (
-        <Minus
-          className={cn("fill-klerosUIComponentsPrimaryText size-4 shrink-0")}
-        />
-      ) : (
-        <Plus
-          className={cn("fill-klerosUIComponentsPrimaryText size-4 shrink-0")}
-        />
-      ),
-    [expanded, expandButton, index, setExpanded],
-  );
+  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
diff --git a/src/lib/accordion/custom.tsx b/src/lib/accordion/custom.tsx
index 88c8b47..8b96453 100644
--- a/src/lib/accordion/custom.tsx
+++ b/src/lib/accordion/custom.tsx
@@ -35,7 +35,7 @@ export interface CustomAccordionProps {
    * expandButton={({ expanded, toggle }) => (
    *   <Button onPress={toggle}>
    *     {expanded ? <ChevronUp /> : <ChevronDown />}
-   *   <Button>
+   *   </Button>
    * )}
    * ```
    */
@@ -56,7 +56,7 @@ function CustomAccordion({
   ...props
 }: Readonly<CustomAccordionProps>) {
   const [expanded, setExpanded] = useState(
-    !isUndefined(defaultExpanded) ? defaultExpanded : -1,
+    isUndefined(defaultExpanded) ? -1 : defaultExpanded,
   );
   return (
     <div
diff --git a/src/lib/accordion/index.tsx b/src/lib/accordion/index.tsx
index c8f209b..3a7aafd 100644
--- a/src/lib/accordion/index.tsx
+++ b/src/lib/accordion/index.tsx
@@ -44,7 +44,7 @@ function Accordion({
   ...props
 }: Readonly<AccordionProps>) {
   const [expanded, setExpanded] = useState(
-    !isUndefined(defaultExpanded) ? defaultExpanded : -1,
+    isUndefined(defaultExpanded) ? -1 : defaultExpanded,
   );
   return (
     <div
diff --git a/src/stories/custom-accordion.stories.tsx b/src/stories/custom-accordion.stories.tsx
index 85c90e6..578ea53 100644
--- a/src/stories/custom-accordion.stories.tsx
+++ b/src/stories/custom-accordion.stories.tsx
@@ -135,11 +135,11 @@ export const ItemExpandButton: Story = {
         ),
       },
     ],
-    expandButton: (expanded) => {
+    expandButton: ({ expanded, toggle }) => {
       return expanded ? (
-        <Button text="Close" variant="secondary" />
+        <Button text="Close" variant="secondary" onPress={toggle} />
       ) : (
-        <Button text="Expand" />
+        <Button text="Expand" onPress={toggle} />
       );
     },
     themeUI: "dark",

From 9c4fff81bd39d407cad5b828beeec6aade5868b3 Mon Sep 17 00:00:00 2001
From: Harman-singh-waraich <Waraichharman68@gmail.com>
Date: Fri, 12 Dec 2025 11:06:06 +0530
Subject: [PATCH 3/3] chore: release 3.7.0

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 342a1a0..d9b407f 100644
--- a/package.json
+++ b/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",