@react-magma/charts 13.0.4-next.0 → 14.0.0-next.1

package/dist/components/CarbonChart/CarbonChart.d.ts

@@ -2,6 +2,7 @@ import * as React from 'react';
 import { ChartOptions } from '@carbon/charts-react';
 import { ThemeInterface } from 'react-magma-dom';
 import './carbon-charts.css';
+import type { ChartDataTableColumn } from '../ChartTable';
 export declare enum CarbonChartType {
     area = "area",
     areaStacked = "areaStacked",
@@ -22,6 +23,40 @@ export declare enum CarbonChartType {
     scatter = "scatter",
     combo = "combo"
 }
+export interface ChartToolbarConfig {
+    /**
+     * When true, renders a "Show as table" button that opens a Magma Modal
+     * with the chart data in an accessible table.
+     * @default true
+     */
+    showAsTable?: boolean;
+    /**
+     * When true, renders a fullscreen toggle button.
+     * @default true
+     */
+    fullscreen?: boolean;
+    /**
+     * Additional menu items rendered inside a "More options" dropdown,
+     * below the built-in "Download as CSV", "Download as PNG", and "Download as JPG" items.
+     * Pass DropdownMenuItem elements.
+     */
+    moreOptions?: React.ReactNode;
+    /**
+     * Custom column definitions for the table modal.
+     * If omitted, columns are auto-derived from the dataset object keys.
+     */
+    tableColumns?: ChartDataTableColumn[];
+    /**
+     * First line of the modal heading.
+     * @default "Tabular representation"
+     */
+    tableHeaderLabel?: string;
+    /**
+     * Heading level for the modal header.
+     * @default 2
+     */
+    tableHeaderLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+}
 export interface CarbonChartProps extends React.HTMLAttributes<HTMLDivElement> {
     dataSet: Array<Object>;
     isInverse?: boolean;
@@ -42,5 +77,11 @@ export interface CarbonChartProps extends React.HTMLAttributes<HTMLDivElement> {
      * Text for the aria-label attribute for main SVG container, if provided
      */
     ariaLabel?: string;
+    /**
+     * When provided, renders an accessible Magma toolbar above the chart with
+     * "Show as table", fullscreen, and "More options" buttons. Carbon's built-in
+     * toolbar is automatically disabled.
+     */
+    chartToolbar?: ChartToolbarConfig;
 }
 export declare const CarbonChart: React.ForwardRefExoticComponent<CarbonChartProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ChartTable/ChartDataTable.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+export interface ChartDataTableColumn {
+    /** Header text for this column */
+    header: string;
+    /** Key to read from each row object */
+    key: string;
+}
+export interface ChartDataTableProps {
+    /** Column definitions (header + key). If omitted, columns are auto-derived from the dataset object keys with the first character capitalized (e.g. "group" → "Group"). */
+    columns?: ChartDataTableColumn[];
+    /** Array of data objects. Each object should have keys matching the column `key` values. */
+    dataSet: Array<Record<string, React.ReactNode>>;
+    /**
+     * If true, the table uses inverse (dark) styling.
+     * @default false
+     */
+    isInverse?: boolean;
+}
+export declare function ChartDataTable({ columns, dataSet, isInverse, }: ChartDataTableProps): React.JSX.Element;

package/dist/components/ChartTable/ChartFullscreenButton.d.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+export interface ChartFullscreenButtonProps {
+    /** Accessible label for the button, e.g. "View Overall Performance in full screen" */
+    ariaLabel: string;
+    /** Icon rendered when not in fullscreen mode */
+    icon: React.ReactElement;
+    /** Icon rendered when in fullscreen mode. Falls back to `icon` if omitted. */
+    exitIcon?: React.ReactElement;
+    /**
+     * If true, the button uses inverse (dark) styling.
+     * @default false
+     */
+    isInverse?: boolean;
+    /** Whether the chart is currently in fullscreen mode */
+    isFullscreen: boolean;
+    /** Click handler – should toggle fullscreen */
+    onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    /** Optional ref forwarded to the underlying IconButton */
+    buttonRef?: React.Ref<HTMLButtonElement>;
+    /**
+     * Tooltip text shown on hover.
+     * @default "Make full screen" / "Exit full screen" based on state (i18n overridable)
+     */
+    tooltipContent?: string;
+}
+export declare function ChartFullscreenButton({ ariaLabel, buttonRef, exitIcon, icon, isInverse, isFullscreen, onClick, tooltipContent, }: ChartFullscreenButtonProps): React.JSX.Element;

package/dist/components/ChartTable/ChartMoreOptionsButton.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+export interface ChartMoreOptionsButtonProps {
+    /**
+     * Accessible label for the trigger button.
+     * @default "More options" (i18n overridable)
+     */
+    ariaLabel?: string;
+    /** Menu items rendered inside the dropdown (DropdownMenuItem, DropdownDivider, etc.) */
+    children: React.ReactNode;
+    /** Icon element rendered inside the trigger button */
+    icon: React.ReactElement;
+    /**
+     * If true, the dropdown uses inverse (dark) styling.
+     * @default false
+     */
+    isInverse?: boolean;
+}
+export declare function ChartMoreOptionsButton({ ariaLabel, children, icon, isInverse, }: ChartMoreOptionsButtonProps): React.JSX.Element;

package/dist/components/ChartTable/ChartTable.stories.d.ts

@@ -0,0 +1,116 @@
+import { CarbonChartProps, CarbonChartType } from '../CarbonChart';
+declare const _default: import("@storybook/csf").ComponentAnnotations<import("@storybook/react/types-6-0").ReactFramework, import("@storybook/react/types-6-0").Args>;
+export default _default;
+export declare const DonutWithToolbar: {
+    render: import("@storybook/csf").AnnotatedStoryFn<import("@storybook/react/types-6-0").ReactFramework, CarbonChartProps>;
+    args: {
+        isInverse: boolean;
+        type: CarbonChartType;
+        dataSet: {
+            group: string;
+            value: number;
+        }[];
+        options: {
+            title: string;
+            resizable: boolean;
+            height: string;
+            donut: {
+                center: {
+                    label: string;
+                };
+            };
+            legend: {
+                truncation: {
+                    type: string;
+                };
+            };
+        };
+        chartToolbar: {};
+    };
+};
+export declare const BarWithToolbar: {
+    render: import("@storybook/csf").AnnotatedStoryFn<import("@storybook/react/types-6-0").ReactFramework, CarbonChartProps>;
+    args: {
+        isInverse: boolean;
+        type: CarbonChartType;
+        dataSet: {
+            group: string;
+            value: number;
+        }[];
+        options: {
+            title: string;
+            axes: {
+                left: {
+                    mapsTo: string;
+                };
+                bottom: {
+                    mapsTo: string;
+                    scaleType: string;
+                };
+            };
+            height: string;
+        };
+        chartToolbar: {
+            tableColumns: {
+                header: string;
+                key: string;
+            }[];
+        };
+    };
+};
+export declare const InverseTheme: {
+    render: import("@storybook/csf").AnnotatedStoryFn<import("@storybook/react/types-6-0").ReactFramework, CarbonChartProps>;
+    args: {
+        isInverse: boolean;
+        type: CarbonChartType;
+        dataSet: {
+            group: string;
+            value: number;
+        }[];
+        options: {
+            title: string;
+            resizable: boolean;
+            height: string;
+            donut: {
+                center: {
+                    label: string;
+                };
+            };
+            legend: {
+                truncation: {
+                    type: string;
+                };
+            };
+        };
+        chartToolbar: {};
+    };
+};
+export declare const TableOnly: {
+    render: import("@storybook/csf").AnnotatedStoryFn<import("@storybook/react/types-6-0").ReactFramework, CarbonChartProps>;
+    args: {
+        isInverse: boolean;
+        type: CarbonChartType;
+        dataSet: {
+            group: string;
+            value: number;
+        }[];
+        options: {
+            title: string;
+            resizable: boolean;
+            height: string;
+            donut: {
+                center: {
+                    label: string;
+                };
+            };
+            legend: {
+                truncation: {
+                    type: string;
+                };
+            };
+        };
+        chartToolbar: {
+            fullscreen: boolean;
+        };
+    };
+};

package/dist/components/ChartTable/ChartTable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/ChartTable/ChartTableButton.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+export interface ChartTableButtonProps {
+    /** Accessible label for the button – should describe the chart, e.g. "Overall Performance" */
+    ariaLabel: string;
+    /** Icon element rendered inside the button */
+    icon: React.ReactElement;
+    /**
+     * If true, the button uses inverse (dark) styling.
+     * @default false
+     */
+    isInverse?: boolean;
+    /** Whether the associated modal is currently open */
+    isTableOpen: boolean;
+    /** Click handler – should open the modal */
+    onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    /** Optional ref forwarded to the underlying IconButton */
+    buttonRef?: React.Ref<HTMLButtonElement>;
+    /**
+     * Tooltip text shown on hover.
+     * @default "Show as table" (i18n overridable)
+     */
+    tooltipContent?: string;
+}
+export declare function ChartTableButton({ ariaLabel, buttonRef, icon, isInverse, isTableOpen, onClick, tooltipContent, }: ChartTableButtonProps): React.JSX.Element;

package/dist/components/ChartTable/ChartTableModal.d.ts

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { ModalSize } from 'react-magma-dom';
+import { ChartDataTableColumn } from './ChartDataTable';
+export interface ChartTableModalProps {
+    /** The chart's data passed to ChartDataTable */
+    dataSet: Array<Record<string, React.ReactNode>>;
+    /** Column definitions forwarded to ChartDataTable */
+    columns?: ChartDataTableColumn[];
+    /**
+     * DOM element to portal the modal into. Defaults to `document.body`.
+     * When the chart is in fullscreen, pass the fullscreen element so the
+     * modal renders inside it and is visible to the browser.
+     */
+    portalContainer?: HTMLElement | null;
+    /**
+     * If true, the modal uses inverse (dark) styling.
+     * @default false
+     */
+    isInverse?: boolean;
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Called when the modal requests to close */
+    onClose: () => void;
+    /** Called when the "Download as CSV" footer button is clicked */
+    onDownloadCsv?: () => void;
+    /** Chart title – displayed as a second line in the modal heading */
+    title: string;
+    /**
+     * Heading level for the modal header (1–6).
+     * @default 2
+     */
+    headerLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * First line of the modal heading.
+     * @default "Tabular representation" (i18n overridable)
+     */
+    headerLabel?: string;
+    /**
+     * Magma Modal size.
+     * @default ModalSize.large
+     */
+    size?: ModalSize;
+}
+export declare function ChartTableModal({ columns, portalContainer, dataSet, headerLabel, headerLevel, isInverse, isOpen, onClose, onDownloadCsv, size, title, }: ChartTableModalProps): React.JSX.Element;

package/dist/components/ChartTable/ChartToolbar.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { TypographyVisualStyle } from 'react-magma-dom';
+export interface ChartToolbarProps {
+    /** Toolbar action buttons (ChartTableButton, ChartFullscreenButton, ChartMoreOptionsButton, etc.) */
+    children: React.ReactNode;
+    /**
+     * Heading level for the chart title.
+     * @default 3
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Visual style for the heading.
+     * @default TypographyVisualStyle.headingSmall
+     */
+    headingVisualStyle?: TypographyVisualStyle;
+    /** Chart title text */
+    title: string;
+}
+export declare function ChartToolbar({ children, headingLevel, headingVisualStyle, title, }: ChartToolbarProps): React.JSX.Element;

package/dist/components/ChartTable/chartToolbarI18n.d.ts

@@ -0,0 +1,16 @@
+export interface ChartToolbarI18n {
+    defaultTitle: string;
+    downloadAsCsv: string;
+    downloadAsJpg: string;
+    downloadAsPng: string;
+    exitFullScreen: string;
+    makeFullScreen: string;
+    moreOptionsAriaLabel: string;
+    showAsTableTooltip: string;
+    tabularRepresentationLabel: string;
+}
+/**
+ * Reads chart toolbar i18n strings from the I18nContext if available,
+ * falling back to English defaults.
+ */
+export declare function useChartToolbarI18n(): ChartToolbarI18n;

package/dist/components/ChartTable/index.d.ts

@@ -0,0 +1,14 @@
+export { ChartDataTable } from './ChartDataTable';
+export type { ChartDataTableProps, ChartDataTableColumn, } from './ChartDataTable';
+export { ChartFullscreenButton } from './ChartFullscreenButton';
+export type { ChartFullscreenButtonProps } from './ChartFullscreenButton';
+export { ChartMoreOptionsButton } from './ChartMoreOptionsButton';
+export type { ChartMoreOptionsButtonProps } from './ChartMoreOptionsButton';
+export { ChartTableButton } from './ChartTableButton';
+export type { ChartTableButtonProps } from './ChartTableButton';
+export { ChartTableModal } from './ChartTableModal';
+export type { ChartTableModalProps } from './ChartTableModal';
+export { ChartToolbar } from './ChartToolbar';
+export type { ChartToolbarProps } from './ChartToolbar';
+export { useChartToolbarI18n } from './chartToolbarI18n';
+export type { ChartToolbarI18n } from './chartToolbarI18n';

package/dist/components/LineChart/DataTable.d.ts

@@ -2,4 +2,4 @@ import * as React from 'react';
 export interface DataTableProps {
     data?: any;
 }
-export declare const DataTable: (props: any) => React.JSX.Element;
+export declare const DataTable: (props: DataTableProps) => React.JSX.Element;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './components/LineChart';
 export * from './components/CarbonChart';
+export * from './components/ChartTable';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-magma/charts",
-  "version": "13.0.4-next.0",
+  "version": "14.0.0-next.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -47,8 +47,8 @@
     "identity-obj-proxy": "^3.0.0",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
-    "react-magma-dom": "^4.12.2-next.0",
-    "react-magma-icons": "^3.2.4",
+    "react-magma-dom": "^4.13.0-next.2",
+    "react-magma-icons": "^3.2.5",
     "rollup": "^4.52.4",
     "rollup-plugin-postcss": "^4.0.2"
   },
@@ -57,8 +57,8 @@
     "@emotion/styled": "^11.13.0",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
-    "react-magma-dom": "^4.12.2-next.0",
-    "react-magma-icons": "^3.2.4"
+    "react-magma-dom": "^4.13.0-next.2",
+    "react-magma-icons": "^3.2.5"
   },
   "engines": {
     "node": ">=22.14.0",

package/src/components/CarbonChart/CarbonChart.test.js

@@ -1,7 +1,7 @@
 import React from 'react';
 
-import { act, render } from '@testing-library/react';
-import { ThemeContext, magma } from 'react-magma-dom';
+import { act, render, screen, fireEvent } from '@testing-library/react';
+import { ThemeContext, magma, DropdownMenuItem } from 'react-magma-dom';
 
 import { CarbonChart, CarbonChartType } from '.';
 
@@ -754,4 +754,145 @@ describe('CarbonChart', () => {
       expect(document.activeElement).toBe(closeButton);
     });
   });
+
+  describe('chartToolbar prop', () => {
+    const toolbarProps = {
+      dataSet,
+      options: chartOptions,
+      type: CarbonChartType.bar,
+      chartToolbar: {},
+    };
+
+    it('should render the show-as-table button with aria-haspopup="dialog"', () => {
+      render(<CarbonChart {...toolbarProps} />);
+
+      const button = screen.getByRole('button', {
+        name: chartOptions.title,
+      });
+      expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('should render the fullscreen button without aria-haspopup', () => {
+      render(<CarbonChart {...toolbarProps} />);
+
+      const button = screen.getByRole('button', {
+        name: `View ${chartOptions.title} full screen`,
+      });
+      expect(button).not.toHaveAttribute('aria-haspopup');
+    });
+
+    it('should open the table modal when show-as-table button is clicked', () => {
+      render(<CarbonChart {...toolbarProps} />);
+
+      fireEvent.click(screen.getByRole('button', { name: chartOptions.title }));
+
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
+      expect(
+        screen.getByRole('heading', {
+          level: 2,
+          name: `Tabular representation ${chartOptions.title}`,
+        })
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('columnheader', { name: 'Group' })
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('columnheader', { name: 'Value' })
+      ).toBeInTheDocument();
+    });
+
+    it('should render chart data in the table modal', () => {
+      render(<CarbonChart {...toolbarProps} />);
+
+      fireEvent.click(screen.getByRole('button', { name: chartOptions.title }));
+
+      expect(screen.getByRole('cell', { name: 'Qty' })).toBeInTheDocument();
+      expect(screen.getByRole('cell', { name: '65000' })).toBeInTheDocument();
+    });
+
+    it('should set aria-expanded to true when modal is open', () => {
+      render(<CarbonChart {...toolbarProps} />);
+
+      const tableButton = screen.getByRole('button', {
+        name: chartOptions.title,
+      });
+      fireEvent.click(tableButton);
+
+      expect(tableButton).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should not render the table button when showAsTable is false', () => {
+      render(
+        <CarbonChart {...toolbarProps} chartToolbar={{ showAsTable: false }} />
+      );
+
+      expect(
+        screen.queryByRole('button', { name: chartOptions.title })
+      ).not.toBeInTheDocument();
+    });
+
+    it('should not render the fullscreen button when fullscreen is false', () => {
+      render(
+        <CarbonChart {...toolbarProps} chartToolbar={{ fullscreen: false }} />
+      );
+
+      expect(
+        screen.queryByRole('button', { name: /full screen/i })
+      ).not.toBeInTheDocument();
+    });
+
+    it('should always render the more options dropdown with built-in download items', () => {
+      render(<CarbonChart {...toolbarProps} />);
+
+      const moreBtn = screen.getByRole('button', { name: 'More options' });
+      expect(moreBtn).toBeInTheDocument();
+
+      fireEvent.click(moreBtn);
+      expect(screen.getByText('Download as CSV')).toBeVisible();
+      expect(screen.getByText('Download as PNG')).toBeVisible();
+      expect(screen.getByText('Download as JPG')).toBeVisible();
+    });
+
+    it('should render additional moreOptions items below built-in downloads', () => {
+      render(
+        <CarbonChart
+          {...toolbarProps}
+          chartToolbar={{
+            moreOptions: <DropdownMenuItem>Custom Action</DropdownMenuItem>,
+          }}
+        />
+      );
+
+      const moreBtn = screen.getByRole('button', { name: 'More options' });
+      fireEvent.click(moreBtn);
+      expect(screen.getByText('Download as CSV')).toBeVisible();
+      expect(screen.getByText('Download as PNG')).toBeVisible();
+      expect(screen.getByText('Download as JPG')).toBeVisible();
+      expect(screen.getByText('Custom Action')).toBeVisible();
+    });
+
+    it('should support custom table columns', () => {
+      render(
+        <CarbonChart
+          {...toolbarProps}
+          chartToolbar={{
+            tableColumns: [
+              { header: 'Category', key: 'group' },
+              { header: 'Count', key: 'value' },
+            ],
+          }}
+        />
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: chartOptions.title }));
+
+      expect(
+        screen.getByRole('columnheader', { name: 'Category' })
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('columnheader', { name: 'Count' })
+      ).toBeInTheDocument();
+    });
+  });
 });