@arbor-education/design-system.components 0.17.1 → 0.19.0

package/src/components/table/cellRenderers/ComboboxCellRenderer.tsx

@@ -0,0 +1,135 @@
+import { useRef } from 'react';
+import type {
+  CellKeyDownEvent,
+  FullWidthCellKeyDownEvent,
+  SuppressKeyboardEventParams,
+} from 'ag-grid-community';
+import type { CustomCellRendererProps } from 'ag-grid-react';
+import { Combobox } from 'Components/combobox/Combobox';
+import type { ComboboxProps } from 'Components/combobox/types';
+import { useComponentDidMount } from 'Utils/hooks/useComponentDidMount';
+
+type ComboboxCellRendererProps = CustomCellRendererProps & ComboboxProps;
+
+export const ComboboxCellRenderer = (props: ComboboxCellRendererProps) => {
+  const {
+    value,
+    node,
+    column,
+    api,
+    options = [],
+    multiple = false,
+    placeholder,
+    triggerVariant,
+    disabled,
+    hasError,
+    searchType,
+    highlightStringMatches,
+    loading,
+    onSearch,
+    id,
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    'aria-label': ariaLabel,
+  } = props;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const normalizedValue: string[] = Array.isArray(value)
+    ? value.map(String)
+    : value != null && value !== ''
+      ? [String(value)]
+      : [];
+
+  useComponentDidMount(() => {
+    // open the combobox when the user presses Enter on the ag-grid cell
+    const handleCellKeyDown = (
+      event: CellKeyDownEvent | FullWidthCellKeyDownEvent,
+    ) => {
+      const { key } = event.event as KeyboardEvent;
+      if (
+        'column' in event
+        && event.node === node
+        && event.column === column
+        && key === 'Enter'
+      ) {
+        const trigger = containerRef.current?.querySelector<HTMLElement>(
+          '[role="combobox"], [role="button"][aria-haspopup="listbox"]',
+        );
+        if (!trigger) return;
+        trigger.focus();
+        // button-style triggers (single-select) need an explicit click to open the popover
+        if (trigger.getAttribute('role') === 'button') {
+          trigger.click();
+        }
+      }
+    };
+
+    api.addEventListener('cellKeyDown', handleCellKeyDown);
+
+    // restore ag-grid cell focus when popover closes without focus leaving the cell
+    const container = containerRef.current;
+    let observer: MutationObserver | undefined;
+    if (container) {
+      const trigger = container.querySelector<HTMLElement>(
+        '[role="combobox"], [role="button"][aria-haspopup="listbox"]',
+      );
+      if (trigger) {
+        observer = new MutationObserver(() => {
+          const isOpen = trigger.getAttribute('aria-expanded') === 'true';
+          if (isOpen || column == null || node.rowIndex == null) return;
+          const active = document.activeElement;
+          const focusIsStillInCell = active == null || active === document.body || container.contains(active);
+          if (focusIsStillInCell) {
+            api.setFocusedCell(node.rowIndex, column);
+          }
+        });
+        observer.observe(trigger, { attributes: true, attributeFilter: ['aria-expanded'] });
+      }
+    }
+
+    return () => {
+      api.removeEventListener('cellKeyDown', handleCellKeyDown);
+      observer?.disconnect();
+    };
+  });
+
+  return (
+    <div ref={containerRef} className="ds-table__combobox">
+      <Combobox
+        options={options}
+        value={normalizedValue}
+        multiple={multiple}
+        placeholder={placeholder}
+        triggerVariant={triggerVariant}
+        disabled={disabled}
+        hasError={hasError}
+        searchType={searchType}
+        highlightStringMatches={highlightStringMatches}
+        loading={loading}
+        onSearch={onSearch}
+        id={id}
+        aria-describedby={ariaDescribedBy}
+        aria-invalid={ariaInvalid}
+        aria-label={ariaLabel}
+        onValueChange={(newValues) => {
+          if (column) {
+            node.setDataValue(column, multiple ? newValues : (newValues[0] ?? null));
+          }
+        }}
+      />
+    </div>
+  );
+};
+
+ComboboxCellRenderer.colDefDefaults = {
+  autoHeight: true,
+  suppressKeyboardEvent: (params: SuppressKeyboardEventParams) => {
+    const cell = (params.event.target as HTMLElement)?.closest('.ag-cell');
+    if (!cell) return false;
+    const openTrigger = cell.querySelector(
+      '[role="combobox"][aria-expanded="true"], [role="button"][aria-expanded="true"]',
+    );
+    return !!openTrigger && ['ArrowUp', 'ArrowDown', 'Enter', 'Escape'].includes(params.event.key);
+  },
+};

package/src/components/table/cellRenderers/SelectDropdownCellRenderer.stories.tsx

@@ -187,6 +187,22 @@ const meta = {
       description: 'AG Grid row node. The renderer calls `node.setDataValue` on option selection.',
       table: { type: { summary: 'IRowNode' } },
     },
+    backgroundColor: {
+      control: 'color',
+      description: 'Optional hex colour applied to the dropdown trigger background. Text colour automatically switches between dark and white based on YIQ luminance for legibility.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    fillCell: {
+      control: 'boolean',
+      description: 'When `true` the wrapper and trigger button stretch to 100% of the cell, and the trigger\'s rounded corners are removed. For true edge-to-edge fill, also set `cellStyle: { padding: 0 }` on the column def — AG Grid\'s default cell padding lives outside the renderer.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
   },
 } satisfies Meta<typeof SelectDropdownCellRenderer>;
 
@@ -290,6 +306,58 @@ export const Disabled: Story = withDescription(
   'Pass `disabled: true` via `cellRendererParams` to prevent the user from changing the selection for specific rows.',
 );
 
+export const WithBackgroundColor: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+        <SelectDropdownCellRenderer
+          {...MOCK_CELL_PROPS}
+          api={MOCK_API}
+          value="active"
+          options={STATUS_OPTIONS}
+          placeholder="Select status"
+          backgroundColor="#1F7A1F"
+          node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+          column={{} as CustomCellRendererProps['column']}
+        />
+        <SelectDropdownCellRenderer
+          {...MOCK_CELL_PROPS}
+          api={MOCK_API}
+          value="pending"
+          options={STATUS_OPTIONS}
+          placeholder="Select status"
+          backgroundColor="#FFE68A"
+          node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+          column={{} as CustomCellRendererProps['column']}
+        />
+      </div>
+    ),
+  },
+  'Pass a hex `backgroundColor` via `cellRendererParams` to tint the trigger. The text colour automatically switches between dark (`#2F2F2F`) and white (`#FFFFFF`) based on the YIQ luminance of the background so the label remains legible. Top row: dark green → white text. Bottom row: pale yellow → dark text.',
+);
+
+export const FillCell: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <div style={{ width: 240, height: 40, border: '1px dashed var(--color-grey-300)' }}>
+        <SelectDropdownCellRenderer
+          {...MOCK_CELL_PROPS}
+          api={MOCK_API}
+          value="active"
+          options={STATUS_OPTIONS}
+          placeholder="Select status"
+          fillCell={true}
+          node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+          column={{} as CustomCellRendererProps['column']}
+        />
+      </div>
+    ),
+  },
+  '`fillCell: true` stretches the wrapper and trigger to 100% of the container and removes the trigger\'s rounded corners — typical when the dropdown should look like part of the cell rather than a button placed inside it. The dashed box here represents the surrounding cell.',
+);
+
 const SELECT_IN_TABLE_DATA = [
   { name: 'Alice Johnson', status: 'active' },
   { name: 'Bob Smith', status: 'inactive' },
@@ -367,3 +435,74 @@ export default SelectDropdownCellRendererExample;
   },
   '`dsSelectDropdownCellRenderer` wired up inside a full `Table`. Click a Status dropdown to select a new value — the selection is committed to the row via `node.setDataValue`. Press Enter in a focused Status cell to open the dropdown via keyboard.',
 );
+
+const STATUS_BACKGROUND_COLORS: Record<string, string> = {
+  active: '#1F7A1F',
+  inactive: '#B91C1C',
+  pending: '#FFE68A',
+};
+
+export const ColoredCellsInATable: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const STATUS_BACKGROUND_COLORS = {
+  active: '#1F7A1F',
+  inactive: '#B91C1C',
+  pending: '#FFE68A',
+};
+
+const columnDefs = [
+  { field: 'name', headerName: 'Name', flex: 2 },
+  {
+    field: 'status',
+    headerName: 'Status',
+    flex: 1,
+    editable: false,
+    cellRenderer: 'dsSelectDropdownCellRenderer',
+    // Per-row params: derive the cell background from the row's current value.
+    cellRendererParams: (params) => ({
+      options: statusOptions,
+      backgroundColor: STATUS_BACKGROUND_COLORS[params.value],
+      fillCell: true,
+    }),
+    // fillCell wants a flush cell — strip AG Grid's default cell padding.
+    cellStyle: { padding: 0 },
+  },
+];
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={SELECT_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          {
+            field: 'status',
+            headerName: 'Status',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsSelectDropdownCellRenderer',
+            cellRendererParams: (params: { value?: string }) => ({
+              options: STATUS_OPTIONS,
+              backgroundColor: params.value ? STATUS_BACKGROUND_COLORS[params.value] : undefined,
+              fillCell: true,
+            }),
+            cellStyle: { padding: 0 },
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  'Combines `backgroundColor` and `fillCell` to drive a status-coloured column. `cellRendererParams` is a function so each row gets a colour based on its current value, and `cellStyle: { padding: 0 }` removes AG Grid\'s default cell padding so the tinted trigger spans the cell edge-to-edge. Text colour switches automatically between dark and white for legibility.',
+);

package/src/components/table/cellRenderers/SelectDropdownCellRenderer.test.tsx

@@ -0,0 +1,118 @@
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import type { CustomCellRendererProps } from 'ag-grid-react';
+import type { GridApi } from 'ag-grid-community';
+import { SelectDropdownCellRenderer } from './SelectDropdownCellRenderer';
+
+const MOCK_API = {
+  addEventListener: vi.fn(),
+  removeEventListener: vi.fn(),
+} as unknown as GridApi;
+
+const OPTIONS = [
+  { label: 'Option 1', value: 'option1' },
+  { label: 'Option 2', value: 'option2' },
+];
+
+const createMockProps = (
+  overrides: Partial<CustomCellRendererProps> & {
+    backgroundColor?: string;
+    fillCell?: boolean;
+  } = {},
+) => ({
+  value: 'option1',
+  api: MOCK_API,
+  node: { setDataValue: vi.fn() },
+  column: 'selectField',
+  options: OPTIONS,
+  ...overrides,
+} as unknown as Parameters<typeof SelectDropdownCellRenderer>[0]);
+
+describe('SelectDropdownCellRenderer', () => {
+  test('renders the dropdown trigger button', () => {
+    render(<SelectDropdownCellRenderer {...createMockProps()} />);
+    expect(screen.getByRole('button')).toBeInTheDocument();
+  });
+
+  describe('backgroundColor', () => {
+    test('does not apply the custom-bg or text-contrast modifiers when not provided', () => {
+      const { container } = render(<SelectDropdownCellRenderer {...createMockProps()} />);
+      const wrapper = container.querySelector('.ds-table__select-dropdown') as HTMLElement;
+      expect(wrapper).not.toHaveClass('ds-table__select-dropdown--custom-bg');
+      expect(wrapper).not.toHaveClass('ds-table__select-dropdown--text-dark');
+      expect(wrapper).not.toHaveClass('ds-table__select-dropdown--text-light');
+      expect(wrapper.style.getPropertyValue('--ds-select-cell-bg')).toBe('');
+    });
+
+    test('applies the custom-bg modifier and bg CSS var when provided', () => {
+      const { container } = render(
+        <SelectDropdownCellRenderer {...createMockProps({ backgroundColor: '#1F7A1F' })} />,
+      );
+      const wrapper = container.querySelector('.ds-table__select-dropdown') as HTMLElement;
+      expect(wrapper).toHaveClass('ds-table__select-dropdown--custom-bg');
+      expect(wrapper.style.getPropertyValue('--ds-select-cell-bg')).toBe('#1F7A1F');
+    });
+
+    test('emits the text-light modifier for a dark background', () => {
+      const { container } = render(
+        <SelectDropdownCellRenderer {...createMockProps({ backgroundColor: '#000000' })} />,
+      );
+      const wrapper = container.querySelector('.ds-table__select-dropdown');
+      expect(wrapper).toHaveClass('ds-table__select-dropdown--text-light');
+      expect(wrapper).not.toHaveClass('ds-table__select-dropdown--text-dark');
+    });
+
+    test('emits the text-dark modifier for a light background', () => {
+      const { container } = render(
+        <SelectDropdownCellRenderer {...createMockProps({ backgroundColor: '#FFFFFF' })} />,
+      );
+      const wrapper = container.querySelector('.ds-table__select-dropdown');
+      expect(wrapper).toHaveClass('ds-table__select-dropdown--text-dark');
+      expect(wrapper).not.toHaveClass('ds-table__select-dropdown--text-light');
+    });
+
+    test('expands 3-digit hex shorthand correctly', () => {
+      const { container } = render(
+        <SelectDropdownCellRenderer {...createMockProps({ backgroundColor: '#000' })} />,
+      );
+      const wrapper = container.querySelector('.ds-table__select-dropdown');
+      expect(wrapper).toHaveClass('ds-table__select-dropdown--text-light');
+    });
+
+    test('falls back to the text-dark modifier when the hex is malformed', () => {
+      const { container } = render(
+        <SelectDropdownCellRenderer {...createMockProps({ backgroundColor: 'not-a-color' })} />,
+      );
+      const wrapper = container.querySelector('.ds-table__select-dropdown');
+      expect(wrapper).toHaveClass('ds-table__select-dropdown--text-dark');
+    });
+  });
+
+  describe('fillCell', () => {
+    test('does not apply the fill-cell modifier by default', () => {
+      const { container } = render(<SelectDropdownCellRenderer {...createMockProps()} />);
+      const wrapper = container.querySelector('.ds-table__select-dropdown');
+      expect(wrapper).not.toHaveClass('ds-table__select-dropdown--fill-cell');
+    });
+
+    test('applies the fill-cell modifier when true', () => {
+      const { container } = render(
+        <SelectDropdownCellRenderer {...createMockProps({ fillCell: true })} />,
+      );
+      const wrapper = container.querySelector('.ds-table__select-dropdown');
+      expect(wrapper).toHaveClass('ds-table__select-dropdown--fill-cell');
+    });
+  });
+
+  test('applies both modifiers when backgroundColor and fillCell are set together', () => {
+    const { container } = render(
+      <SelectDropdownCellRenderer
+        {...createMockProps({ backgroundColor: '#1F7A1F', fillCell: true })}
+      />,
+    );
+    const wrapper = container.querySelector('.ds-table__select-dropdown');
+    expect(wrapper).toHaveClass('ds-table__select-dropdown--custom-bg');
+    expect(wrapper).toHaveClass('ds-table__select-dropdown--fill-cell');
+  });
+});

package/src/components/table/cellRenderers/SelectDropdownCellRenderer.tsx

@@ -1,4 +1,5 @@
 import { useState } from 'react';
+import classNames from 'classnames';
 import type {
   CellKeyDownEvent,
   FullWidthCellKeyDownEvent,
@@ -9,9 +10,14 @@ import {
   type SelectDropdownInputProps,
 } from 'Components/formField/inputs/selectDropdown/SelectDropdown';
 import { useComponentDidMount } from 'Utils/hooks/useComponentDidMount';
+import { getTextContrast } from 'Utils/getTextContrast';
 
 type SelectDropdownCellRendererProps = CustomCellRendererProps
-  & SelectDropdownInputProps;
+  & SelectDropdownInputProps
+  & {
+    backgroundColor?: string;
+    fillCell?: boolean;
+  };
 
 type SelectDropdownCellRendererOption = Omit<
   SelectDropdownInputProps['options'][number],
@@ -36,8 +42,22 @@ export const SelectDropdownCellRenderer = (
     'aria-describedBy': ariaDescribedBy,
     'aria-invalid': ariaInvalid,
     alwaysShowPlaceholder = false,
+    backgroundColor,
+    fillCell = false,
   } = props;
 
+  const textContrast = backgroundColor ? getTextContrast(backgroundColor) : null;
+
+  const wrapperClassName = classNames('ds-table__select-dropdown', {
+    'ds-table__select-dropdown--custom-bg': backgroundColor,
+    'ds-table__select-dropdown--fill-cell': fillCell,
+    [`ds-table__select-dropdown--text-${textContrast}`]: textContrast,
+  });
+
+  const wrapperStyle = backgroundColor
+    ? { ['--ds-select-cell-bg' as string]: backgroundColor }
+    : undefined;
+
   const rawOptions: SelectDropdownCellRendererOption[] = options;
   const normalisedOptions: SelectDropdownInputProps['options'] = rawOptions.map(option => ({
     ...option,
@@ -70,7 +90,7 @@ export const SelectDropdownCellRenderer = (
   });
 
   return (
-    <div className="ds-table__select-dropdown">
+    <div className={wrapperClassName} style={wrapperStyle}>
       <SelectDropdown
         disabled={disabled}
         hasError={hasError}

package/src/components/table/table.scss

@@ -14,12 +14,43 @@
     width: 100%;
   }
 
+  &__select-dropdown {
+    &--fill-cell {
+      display: flex;
+      width: 100%;
+      height: 100%;
+
+      .ds-button--dropdown {
+        flex: 1;
+        width: 100%;
+        height: 100%;
+        border-radius: 0;
+      }
+    }
+
+    &--custom-bg .ds-button--dropdown {
+      background: var(--ds-select-cell-bg);
+    }
+
+    &--text-dark .ds-button--dropdown {
+      color: var(--color-grey-900);
+    }
+
+    &--text-light .ds-button--dropdown {
+      color: var(--color-mono-white);
+    }
+  }
+
   &__container {
     *[class^='ag-'], *[class*=' ag-'] {
       // AG-Grid gives these a z-index of 2 which interferes with our stacking elements
       // so we just unset it here
       z-index: unset;
     }
+
+    .ag-cell:has(.ds-table__combobox) {
+      padding: var(--spacing-xsmall) var(--spacing-small);
+    }
   }
   
   &__controls {

package/src/utils/getTextContrast.test.ts

@@ -0,0 +1,82 @@
+import { getTextContrast } from 'Utils/getTextContrast';
+import { describe, expect, test } from 'vitest';
+
+describe('getTextContrast', () => {
+  test('returns "light" for pure black', () => {
+    expect(getTextContrast('#000000')).toBe('light');
+  });
+
+  test('returns "dark" for pure white', () => {
+    expect(getTextContrast('#FFFFFF')).toBe('dark');
+  });
+
+  test('returns "dark" at the threshold (YIQ === 128)', () => {
+    // #808080 → YIQ exactly 128; the comparison is `>=` so it counts as light bg.
+    expect(getTextContrast('#808080')).toBe('dark');
+  });
+
+  test('returns "light" just below the threshold (YIQ === 127)', () => {
+    expect(getTextContrast('#7F7F7F')).toBe('light');
+  });
+
+  test('weights green more heavily than red or blue', () => {
+    // Pure green (#00FF00) has high YIQ (≈ 150) → dark text reads better.
+    expect(getTextContrast('#00FF00')).toBe('dark');
+    // Pure red (#FF0000) has YIQ ≈ 76 → light text reads better.
+    expect(getTextContrast('#FF0000')).toBe('light');
+    // Pure blue (#0000FF) has YIQ ≈ 29 → light text reads better.
+    expect(getTextContrast('#0000FF')).toBe('light');
+  });
+
+  test('handles real-world status colours', () => {
+    expect(getTextContrast('#1F7A1F')).toBe('light'); // dark green
+    expect(getTextContrast('#B91C1C')).toBe('light'); // dark red
+    expect(getTextContrast('#FFE68A')).toBe('dark'); // pale yellow
+  });
+
+  describe('input parsing', () => {
+    test('expands 3-digit hex shorthand', () => {
+      expect(getTextContrast('#000')).toBe('light');
+      expect(getTextContrast('#fff')).toBe('dark');
+      expect(getTextContrast('#abc')).toBe('dark'); // #aabbcc → YIQ ≈ 184
+    });
+
+    test('accepts hex without a leading "#"', () => {
+      expect(getTextContrast('000000')).toBe('light');
+      expect(getTextContrast('ffffff')).toBe('dark');
+    });
+
+    test('is case-insensitive', () => {
+      expect(getTextContrast('#abcdef')).toBe(getTextContrast('#ABCDEF'));
+    });
+
+    test('trims surrounding whitespace', () => {
+      expect(getTextContrast('  #000000  ')).toBe('light');
+    });
+  });
+
+  describe('invalid input', () => {
+    test('falls back to "dark" for non-hex characters', () => {
+      expect(getTextContrast('#zzzzzz')).toBe('dark');
+    });
+
+    test('falls back to "dark" for malformed length', () => {
+      expect(getTextContrast('#12345')).toBe('dark'); // 5 chars
+      expect(getTextContrast('#1234567')).toBe('dark'); // 7 chars
+    });
+
+    test('falls back to "dark" for empty string', () => {
+      expect(getTextContrast('')).toBe('dark');
+    });
+
+    test('falls back to "dark" for CSS keyword colours', () => {
+      expect(getTextContrast('red')).toBe('dark');
+      expect(getTextContrast('rebeccapurple')).toBe('dark');
+    });
+
+    test('falls back to "dark" for rgb()/hsl() notation', () => {
+      expect(getTextContrast('rgb(0, 0, 0)')).toBe('dark');
+      expect(getTextContrast('hsl(0, 0%, 0%)')).toBe('dark');
+    });
+  });
+});

package/src/utils/getTextContrast.ts

@@ -0,0 +1,14 @@
+type TextContrast = 'dark' | 'light';
+
+export const getTextContrast = (color: string): TextContrast => {
+  const CONTRAST_THRESHOLD = 128;
+
+  let hex = color.trim().replace('#', '');
+  if (hex.length === 3) hex = hex.split('').map(c => c + c).join('');
+  if (hex.length !== 6 || /[^0-9a-f]/i.test(hex)) return 'dark';
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
+  return yiq >= CONTRAST_THRESHOLD ? 'dark' : 'light';
+};