@arbor-education/design-system.components 3.2.0 → 3.3.0

package/src/components/table/tableControls/TableControls.stories.tsx

@@ -51,7 +51,9 @@ const USAGE_GUIDANCE = [
   '|---|---|---|',
   '| `bulkActions` | Start | Array of `{ displayName, callback, disabled? }` — shown as a dropdown when rows are selected |',
   '| `onUndo` | Start | Renders an undo icon button |',
+  '| `isUndoDisabled` | Start | Disables the undo button (e.g. when there is nothing to undo) |',
   '| `onRedo` | Start | Renders a redo icon button |',
+  '| `isRedoDisabled` | Start | Disables the redo button (e.g. when there is nothing to redo) |',
   '| `showHideColumns` | Start | Renders the `HideColumnsDropdown` |',
   '| `hasSearch` | End | Renders the `SearchBar` |',
   '| `onDownload` | End | Renders a download icon button |',
@@ -65,7 +67,7 @@ const DEVELOPER_NOTES = [
   '### Wiring into `<Table />`',
   '',
   '```tsx',
-  "import { Table, TableControls } from '@arbor-education/design-system.components';",
+  "import { Table } from '@arbor-education/design-system.components';",
   '',
   'function MyTable() {',
   '  return (',
@@ -73,12 +75,13 @@ const DEVELOPER_NOTES = [
   '      rowData={rows}',
   '      columnDefs={colDefs}',
   '      headerContent={(',
-  '        <TableControls',
+  '        <Table.TableControls',
   '          bulkActions={[',
   '            { displayName: "Export selected", callback: api => exportCsv(api) },',
   '            { displayName: "Delete selected", callback: api => deleteRows(api) },',
   '          ]}',
   '          onUndo={handleUndo}',
+  '          isUndoDisabled={!canUndo}',
   '          showHideColumns',
   '          onDownload={handleDownload}',
   '          showSettings',
@@ -93,16 +96,19 @@ const DEVELOPER_NOTES = [
   '',
   '---',
   '',
-  '### `BulkAction` type',
+  '### `Table.BulkAction` type',
   '',
   '```ts',
-  "import type { BulkAction } from '@arbor-education/design-system.components';",
+  "import { Table } from '@arbor-education/design-system.components';",
   '',
-  'type BulkAction = {',
-  '  displayName: string;',
-  '  callback: (gridApi: GridApi) => void;',
-  '  disabled?: boolean;',
-  '};',
+  'type MyAction = Table.BulkAction;',
+  '',
+  '// shape:',
+  '// {',
+  '//   displayName: string;',
+  '//   callback: (gridApi: GridApi) => void;',
+  '//   disabled?: boolean;',
+  '// }',
   '```',
   '',
   '---',
@@ -115,7 +121,7 @@ const DEVELOPER_NOTES = [
   'prop to supply columns manually:',
   '',
   '```tsx',
-  '<TableControls',
+  '<Table.TableControls',
   '  showHideColumns',
   '  hideColumnsProps={{',
   '    columns: myColumns,',
@@ -129,8 +135,10 @@ const DEVELOPER_NOTES = [
   '### TypeScript types',
   '',
   '```ts',
-  "import { TableControls } from '@arbor-education/design-system.components';",
-  "import type { TableControlsProps, BulkAction } from '@arbor-education/design-system.components';",
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'type MyControlsProps = Table.ControlsProps;',
+  'type MyAction = Table.BulkAction;',
   '```',
 ].join('\n');
 
@@ -190,11 +198,21 @@ const meta = {
       control: false,
       table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
     },
+    isUndoDisabled: {
+      description: 'When `true`, disables the undo button (e.g. when there is nothing to undo). Has no effect if `onUndo` is not provided.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
     onRedo: {
       description: 'Renders a redo icon button in the start group. Called with no arguments on click.',
       control: false,
       table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
     },
+    isRedoDisabled: {
+      description: 'When `true`, disables the redo button (e.g. when there is nothing to redo). Has no effect if `onRedo` is not provided.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
     showHideColumns: {
       description: 'When `true`, renders the `HideColumnsDropdown` in the start group. Reads column visibility from `GridApiContext` (provided by `<Table />`). Pass `hideColumnsProps` for manual column control.',
       control: 'boolean',
@@ -294,6 +312,21 @@ export const StartGroupOnly: Story = withDescription(
   + 'see the **Within a Table** story for a fully wired example.',
 );
 
+export const UndoRedoDisabled: Story = withDescription(
+  {
+    args: {
+      onUndo: fn(),
+      isUndoDisabled: true,
+      onRedo: fn(),
+      isRedoDisabled: true,
+    },
+  },
+  'Undo and redo rendered with `isUndoDisabled` / `isRedoDisabled` set — use these when there is '
+  + 'nothing left to undo or redo, so the buttons stay visible but communicate they are unavailable '
+  + 'instead of silently no-opping when clicked. Toggle `isUndoDisabled` / `isRedoDisabled` off in the '
+  + 'Controls panel to compare against the enabled state.',
+);
+
 export const EndGroupOnly: Story = withDescription(
   {
     parameters: { controls: { disable: true } },
@@ -317,7 +350,7 @@ export const BulkActionsOnly: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Table, TableControls } from '@arbor-education/design-system.components';
+import { Table } from '@arbor-education/design-system.components';
 
 function MyTable() {
   return (
@@ -326,7 +359,7 @@ function MyTable() {
       columnDefs={colDefs}
       rowSelection={{ mode: 'multiRow', checkboxes: true }}
       headerContent={(
-        <TableControls
+        <Table.TableControls
           bulkActions={[
             { displayName: 'Export selected', callback: api => api.exportDataAsCsv() },
             { displayName: 'Delete selected', callback: handleDelete, disabled: !canDelete },
@@ -355,7 +388,7 @@ export default MyTable;
   + 'Pass `disabled: true` to a specific action to grey it out (e.g. "Delete selected" when nothing is selected).',
 );
 
-export const FullToolbar: Story = withDescription(
+export const MaximumStandaloneToolbar: Story = withDescription(
   {
     parameters: {
       controls: { disable: true },
@@ -363,7 +396,7 @@ export const FullToolbar: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Table, TableControls } from '@arbor-education/design-system.components';
+import { Table } from '@arbor-education/design-system.components';
 
 function FullTableExample() {
   return (
@@ -372,7 +405,7 @@ function FullTableExample() {
       columnDefs={colDefs}
       rowSelection={{ mode: 'multiRow', checkboxes: true }}
       headerContent={(
-        <TableControls
+        <Table.TableControls
           bulkActions={[
             { displayName: 'Export selected', callback: api => api.exportDataAsCsv() },
             { displayName: 'Delete selected', callback: handleDelete },
@@ -408,8 +441,8 @@ export default FullTableExample;
       onExpandToggle: fn(),
     },
   },
-  'The full toolbar with both groups populated: bulk actions, undo, redo, hide columns, download, settings, help, and expand. '
-  + 'This is the maximum control density — only include the slots your users actually need. '
-  + '`showHideColumns` renders a `HideColumnsDropdown` that reads columns from `GridApiContext`; '
-  + 'in this standalone preview it is disabled since there is no enclosing `<Table />` providing that context.',
+  'Every standalone control except `showHideColumns`: bulk actions, undo, redo, download, settings, help, and expand. '
+  + '`showHideColumns` is left `false` here because `HideColumnsDropdown` needs a `GridApiContext` to read column data, '
+  + 'and that context is only provided by a real `<Table />` — it cannot be faked in this standalone preview. '
+  + 'See [Table](?path=/docs/components-table--docs) for a fully-wired example with `showHideColumns: true` inside an actual `<Table />`.',
 );

package/src/components/table/tableControls/TableControls.test.tsx

@@ -44,6 +44,26 @@ describe('TableControls', () => {
       expect(onRedo).toHaveBeenCalledTimes(1);
     });
 
+    test('disables the undo button when isUndoDisabled is true', () => {
+      render(<TableControls onUndo={vi.fn()} isUndoDisabled />);
+      expect(screen.getByRole('button', { name: /undo/i })).toBeDisabled();
+    });
+
+    test('does not disable the undo button by default', () => {
+      render(<TableControls onUndo={vi.fn()} />);
+      expect(screen.getByRole('button', { name: /undo/i })).toBeEnabled();
+    });
+
+    test('disables the redo button when isRedoDisabled is true', () => {
+      render(<TableControls onRedo={vi.fn()} isRedoDisabled />);
+      expect(screen.getByRole('button', { name: /redo/i })).toBeDisabled();
+    });
+
+    test('does not disable the redo button by default', () => {
+      render(<TableControls onRedo={vi.fn()} />);
+      expect(screen.getByRole('button', { name: /redo/i })).toBeEnabled();
+    });
+
     test('renders bulk actions dropdown when bulkActions is provided', () => {
       render(
         <TableControls

package/src/components/table/tableControls/TableControls.tsx

@@ -16,6 +16,8 @@ export type TableControlsProps = {
   bulkActions?: BulkAction[];
   onUndo?: () => void;
   onRedo?: () => void;
+  isUndoDisabled?: boolean;
+  isRedoDisabled?: boolean;
   showHideColumns?: boolean;
   hideColumnsProps?: HideColumnsDropdownProps;
   hasSearch?: boolean;
@@ -36,6 +38,8 @@ export const TableControls = (props: TableControlsProps) => {
     bulkActions,
     onUndo,
     onRedo,
+    isUndoDisabled = false,
+    isRedoDisabled = false,
     showHideColumns,
     hideColumnsProps,
     hasSearch,
@@ -73,6 +77,7 @@ export const TableControls = (props: TableControlsProps) => {
               variant="secondary"
               borderless
               isRound
+              disabled={isUndoDisabled}
               onClick={onUndo}
             >
               <Icon name="undo" screenReaderText="Undo" />
@@ -83,6 +88,7 @@ export const TableControls = (props: TableControlsProps) => {
               variant="secondary"
               borderless
               isRound
+              disabled={isRedoDisabled}
               onClick={onRedo}
             >
               <Icon name="redo" screenReaderText="Redo" />

package/src/components/table/useTableSettings.ts

@@ -8,7 +8,14 @@ export type TableSettings = {
   areCellColorsEnabled?: boolean;
 };
 
+export const DEFAULT_TABLE_SETTINGS: Required<TableSettings> = {
+  hasColumnBorders: false,
+  tableSpacing: TABLE_SPACING.M,
+  areCellColorsEnabled: true,
+};
+
 export type UseTableSettingsParams = {
+  initialSettings?: Partial<TableSettings>;
   onTableSettingsChanged?: (val: TableSettings) => void;
   onTableSettingsReset?: () => void;
   onColumnBordersChanged?: (val: boolean) => void;
@@ -18,15 +25,22 @@ export type UseTableSettingsParams = {
 
 export const useTableSettings = (params: UseTableSettingsParams = {}) => {
   const {
+    initialSettings,
     onTableSettingsChanged,
     onTableSettingsReset,
     onColumnBordersChanged,
     onTableSpacingChanged,
     onCellColorsChanged,
   } = params;
-  const [hasColumnBorders, setHasColumnBorders] = useState(false);
-  const [tableSpacing, setTableSpacing] = useState(TABLE_SPACING.M);
-  const [areCellColorsEnabled, setAreCellColorsEnabled] = useState(true);
+  const [hasColumnBorders, setHasColumnBorders] = useState(
+    initialSettings?.hasColumnBorders ?? DEFAULT_TABLE_SETTINGS.hasColumnBorders,
+  );
+  const [tableSpacing, setTableSpacing] = useState(
+    initialSettings?.tableSpacing ?? DEFAULT_TABLE_SETTINGS.tableSpacing,
+  );
+  const [areCellColorsEnabled, setAreCellColorsEnabled] = useState(
+    initialSettings?.areCellColorsEnabled ?? DEFAULT_TABLE_SETTINGS.areCellColorsEnabled,
+  );
 
   const settings = {
     hasColumnBorders,
@@ -35,9 +49,9 @@ export const useTableSettings = (params: UseTableSettingsParams = {}) => {
   };
 
   const resetSettings = () => {
-    setHasColumnBorders(false);
-    setTableSpacing(TABLE_SPACING.M);
-    setAreCellColorsEnabled(true);
+    setHasColumnBorders(DEFAULT_TABLE_SETTINGS.hasColumnBorders);
+    setTableSpacing(DEFAULT_TABLE_SETTINGS.tableSpacing);
+    setAreCellColorsEnabled(DEFAULT_TABLE_SETTINGS.areCellColorsEnabled);
     if (onTableSettingsReset) {
       onTableSettingsReset();
     }

package/src/components/widget/Widget.stories.tsx

@@ -165,6 +165,14 @@ const meta = {
       description: 'Renders an info icon with tooltip beside the header title.',
       table: { type: { summary: 'string' } },
     },
+    isFloating: {
+      control: 'boolean',
+      description: 'Gives the widget a permanent elevated shadow (`ds-widget--floating`), on both hover and rest, instead of the default where hovering removes the shadow entirely. Use for widgets that need to visually lift off a busy dashboard background.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
     isLoading: {
       control: 'boolean',
       description: 'Replaces body content with a loading indicator and sets `aria-busy` on the body.',
@@ -296,7 +304,7 @@ const WithTooltipTemplate = () => (
 );
 
 const CollapsibleTemplate = () => (
-  <Widget collapsible defaultExpanded>
+  <Widget collapsible>
     <Widget.Header>Attendance summary</Widget.Header>
     <Widget.Body>
       <p style={{ margin: 0 }}>Widget body content</p>
@@ -327,9 +335,22 @@ const WithRenderLinkTemplate = () => (
   </Widget>
 );
 
+const FloatingTemplate = () => (
+  <Widget isFloating>
+    <Widget.Header>Favourites</Widget.Header>
+    <Widget.Body>
+      <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
+        {Array.from({ length: 6 }, (_, index) => (
+          <li key={index}>Favourite</li>
+        ))}
+      </ul>
+    </Widget.Body>
+  </Widget>
+);
+
 const FixedHeightOverflowTemplate = () => (
   <FixedHeightWidgetContainer>
-    <Widget isFloating>
+    <Widget>
       <Widget.Header>Favourites</Widget.Header>
       <Widget.Body>
         <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
@@ -483,7 +504,7 @@ import { Widget } from '@arbor-education/design-system.components';
 
 function WidgetCollapsibleExample() {
   return (
-    <Widget collapsible defaultExpanded>
+    <Widget collapsible>
       <Widget.Header>Attendance summary</Widget.Header>
       <Widget.Body>
         <p>Widget body content</p>
@@ -515,7 +536,9 @@ function WidgetLoadingExample() {
   return (
     <Widget isLoading loadingLabel="Loading alerts">
       <Widget.Header>Alerts</Widget.Header>
-      <Widget.Body />
+      <Widget.Body>
+        <p>Content hidden while loading</p>
+      </Widget.Body>
     </Widget>
   );
 }
@@ -544,7 +567,7 @@ function WidgetRenderLinkExample() {
     <Widget
       href="/alerts"
       renderLink={({ href, className, children, linkProps }) => (
-        <a href={href} className={className} {...linkProps}>
+        <a href={href} className={className} data-router-link="true" {...linkProps}>
           {children}
         </a>
       )}
@@ -577,7 +600,7 @@ import { Widget } from '@arbor-education/design-system.components';
 function WidgetFixedHeightOverflowExample() {
   return (
     <div style={{ height: 280, display: 'flex', flexDirection: 'column' }}>
-      <Widget isFloating>
+      <Widget>
         <Widget.Header>Favourites</Widget.Header>
         <Widget.Body>
           <ul>
@@ -598,3 +621,35 @@ export default WidgetFixedHeightOverflowExample;
   },
   'Parent container constrains height; the widget header stays pinned while `.ds-widget__body` scrolls overflow content.',
 );
+
+export const Floating: Story = withDescription(
+  {
+    render: FloatingTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Widget } from '@arbor-education/design-system.components';
+
+function WidgetFloatingExample() {
+  return (
+    <Widget isFloating>
+      <Widget.Header>Favourites</Widget.Header>
+      <Widget.Body>
+        <ul>
+          <li>Favourite</li>
+        </ul>
+      </Widget.Body>
+    </Widget>
+  );
+}
+export default WidgetFloatingExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  '`isFloating` gives the widget a permanent elevated shadow that does not clear on hover. Use it to visually lift a widget off a busy dashboard background.',
+);