From cfde69dd30cbf3aa8e0ba764f7ac3086d43ee8fb Mon Sep 17 00:00:00 2001
From: Ashish Kankal <akankal@eightfold.ai>
Date: Thu, 4 Dec 2025 20:35:33 +0530
Subject: [PATCH] Table caption support

---
 src/components/Table/Internal/OcTable.tsx     | 19 +++++++++++++++++++
 .../Table/Internal/OcTable.types.ts           | 14 ++++++++++++++
 .../Table/Internal/octable.module.scss        |  4 ++++
 src/components/Table/Table.stories.tsx        | 18 ++++++++++++++++++
 4 files changed, 55 insertions(+)

diff --git a/src/components/Table/Internal/OcTable.tsx b/src/components/Table/Internal/OcTable.tsx
index f1932eafd..fa59684da 100644
--- a/src/components/Table/Internal/OcTable.tsx
+++ b/src/components/Table/Internal/OcTable.tsx
@@ -95,6 +95,9 @@ function OcTable<RecordType extends DefaultRecordType>(
   const {
     alternateRowColor,
     bordered,
+    caption,
+    captionClassName,
+    captionSide = 'top',
     classNames,
     rowClassName,
     style,
@@ -609,6 +612,14 @@ function OcTable<RecordType extends DefaultRecordType>(
               tableLayout: mergedTableLayout,
             }}
           >
+            {caption && (
+              <caption
+                className={mergeClasses([styles.tableCaption, captionClassName])}
+                style={{ captionSide }}
+              >
+                {caption}
+              </caption>
+            )}
             {bodyColGroup}
             {bodyTable}
             {!fixFooter && summaryNode && (
@@ -718,6 +729,14 @@ function OcTable<RecordType extends DefaultRecordType>(
             tableLayout: mergedTableLayout,
           }}
         >
+          {caption && (
+            <caption
+              className={mergeClasses([styles.tableCaption, captionClassName])}
+              style={{ captionSide }}
+            >
+              {caption}
+            </caption>
+          )}
           {bodyColGroup}
           {showHeader !== false && (
             <Header {...headerProps} {...columnContext} />
diff --git a/src/components/Table/Internal/OcTable.types.ts b/src/components/Table/Internal/OcTable.types.ts
index 6165d2161..25a854999 100644
--- a/src/components/Table/Internal/OcTable.types.ts
+++ b/src/components/Table/Internal/OcTable.types.ts
@@ -494,6 +494,20 @@ export interface OcTableProps<RecordType = unknown> {
    * Show all Table borders.
    */
   bordered?: boolean;
+  /**
+   * The Table caption content.
+   * Renders a native HTML caption element for accessibility.
+   */
+  caption?: React.ReactNode;
+  /**
+   * The custom class name of the Table caption.
+   */
+  captionClassName?: string;
+  /**
+   * The Table caption position.
+   * @default 'top'
+   */
+  captionSide?: 'top' | 'bottom';
   /**
    * The Table custom class names.
    */
diff --git a/src/components/Table/Internal/octable.module.scss b/src/components/Table/Internal/octable.module.scss
index 7c2fd414a..baf2765fb 100644
--- a/src/components/Table/Internal/octable.module.scss
+++ b/src/components/Table/Internal/octable.module.scss
@@ -348,6 +348,10 @@
     border-top-right-radius: $table-border-radius;
   }
 
+  &-caption {
+    visibility: hidden;
+  }
+
   &-footer {
     background: var(--table-footer-background-color);
     color: var(--table-footer-foreground-color);
diff --git a/src/components/Table/Table.stories.tsx b/src/components/Table/Table.stories.tsx
index ddbb124d0..96afcf798 100644
--- a/src/components/Table/Table.stories.tsx
+++ b/src/components/Table/Table.stories.tsx
@@ -1441,6 +1441,9 @@ export const Virtual_List: FC = () => {
   );
 };
 
+export const Caption = Table_Base_Story.bind({});
+export const Caption_Bottom = Table_Base_Story.bind({});
+
 // Storybook 6.5 using Webpack >= 5.76.0 automatically alphabetizes exports,
 // this line ensures they are exported in the desired order.
 // See https://www.npmjs.com/package/babel-plugin-named-exports-order
@@ -1460,6 +1463,8 @@ export const __namedExportsOrder = [
   'Empty',
   'Header_Grouping',
   'Header_And_Footer',
+  'Caption',
+  'Caption_Bottom',
   'Fixed_Header',
   'Fixed_Columns',
   'Fixed_Columns_and_Header',
@@ -1825,3 +1830,16 @@ Page_Sizes.args = {
     total: 1000,
   },
 };
+
+Caption.args = {
+  ...tableArgs,
+  bordered: false,
+  caption: 'Sales Team Members - Q4 2024',
+};
+
+Caption_Bottom.args = {
+  ...tableArgs,
+  bordered: false,
+  caption: 'Sales Team Members - Q4 2024',
+  captionSide: 'bottom',
+};