@arbor-education/design-system.components 0.13.1 → 0.15.0

package/src/components/kvpList/KVPList.tsx

@@ -0,0 +1,109 @@
+import classNames from 'classnames';
+
+export type KVPListProps = React.HTMLAttributes<HTMLDivElement> & {
+  children?: React.ReactNode;
+};
+
+export type KVPListRowProps = React.HTMLAttributes<HTMLDListElement> & {
+  children?: React.ReactNode;
+  orientation?: 'horizontal' | 'vertical';
+};
+
+export type KVPListTermProps = React.HTMLAttributes<HTMLElement> & {
+  children?: React.ReactNode;
+};
+
+export type KVPListDefinitionProps = React.HTMLAttributes<HTMLElement> & {
+  children?: React.ReactNode;
+  isRow?: boolean;
+  isPercentage?: boolean;
+  prominence?: 'neutral' | 'strong';
+};
+
+const KVPListRoot = ({
+  children,
+  className,
+  role,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  ...rest
+}: KVPListProps): React.JSX.Element => (
+  <div
+    className={classNames('ds-kvp-list', className)}
+    role={role ?? (ariaLabel || ariaLabelledBy ? 'group' : undefined)}
+    aria-label={ariaLabel}
+    aria-labelledby={ariaLabelledBy}
+    {...rest}
+  >
+    {children}
+  </div>
+);
+
+const KVPListRow = ({
+  children,
+  className,
+  orientation = 'vertical',
+  ...rest
+}: KVPListRowProps): React.JSX.Element => (
+  <dl
+    className={classNames(
+      'ds-kvp-list__row',
+      `ds-kvp-list__row--${orientation}`,
+      className,
+    )}
+    {...rest}
+  >
+    {children}
+  </dl>
+);
+
+const KVPListTerm = ({
+  children,
+  className,
+  ...rest
+}: KVPListTermProps): React.JSX.Element => (
+  <dt className={classNames('ds-kvp-list__term', className)} {...rest}>
+    {children}
+  </dt>
+);
+
+const KVPListDefinition = ({
+  children,
+  className,
+  isRow = false,
+  isPercentage = false,
+  prominence = 'neutral',
+  ...rest
+}: KVPListDefinitionProps): React.JSX.Element => (
+  <dd
+    className={classNames(
+      'ds-kvp-list__description',
+      `ds-kvp-list__description--${prominence}`,
+      {
+        'ds-kvp-list__description--row': isRow,
+      },
+      className,
+    )}
+    {...rest}
+  >
+    {children}
+    {isPercentage
+      ? (
+          <span className="ds-kvp-list__suffix">
+            %
+          </span>
+        )
+      : null}
+  </dd>
+);
+
+KVPListRoot.displayName = 'KVPList';
+KVPListRow.displayName = 'KVPList.Row';
+KVPListTerm.displayName = 'KVPList.Term';
+KVPListDefinition.displayName = 'KVPList.Definition';
+
+export const KVPList = Object.assign(KVPListRoot, {
+  Row: KVPListRow,
+  Term: KVPListTerm,
+  Definition: KVPListDefinition,
+});

package/src/components/kvpList/kvpList.scss

@@ -0,0 +1,64 @@
+.ds-kvp-list {
+  display: flex;
+  width: 100%;
+  flex-direction: column;
+  gap: var(--spacing-medium);
+  box-sizing: border-box;
+}
+
+.ds-kvp-list__term,
+.ds-kvp-list__description {
+  margin: 0;
+  flex: 1;
+}
+
+.ds-kvp-list__term,
+.ds-kvp-list__description--neutral {
+  color: var(--kvp-list-color-text-subtle);
+  font-family: var(--type-body-p-family);
+  font-size: var(--type-body-p-size);
+  font-weight: var(--type-body-p-weight);
+  line-height: var(--type-body-line-height);
+}
+
+.ds-kvp-list__description--strong {
+  color: var(--kvp-list-color-text-strong);
+  font-family: var(--type-headings-h2-family);
+  font-size: var(--type-headings-h2-size);
+  font-weight: var(--type-headings-h2-weight);
+  line-height: var(--type-headings-h2-line-height);
+}
+
+.ds-kvp-list__description--row {
+  flex-basis: 100%;
+  width: 100%;
+}
+
+.ds-kvp-list__suffix {
+  margin-left: var(--spacing-xsmall);
+  font: inherit;
+}
+
+.ds-kvp-list__description {
+  text-align: right;
+}
+
+.ds-kvp-list__row {
+  display: flex;
+  width: 100%;
+  margin: 0;
+  gap: var(--spacing-small);
+
+  &--vertical {
+    flex-direction: column;
+  }
+
+  &--horizontal {
+    flex-wrap: wrap;
+    align-items: center;
+
+    .ds-kvp-list__description:not(.ds-kvp-list__description--row) {
+      flex: 0 0 auto;
+    }
+  }
+}

package/src/components/table/Table.stories.tsx

@@ -52,6 +52,7 @@ interface RowData {
   email: { value: string } & CellColors;
   role: { value: string } & CellColors;
   status: { value: string } & CellColors;
+  marks: number;
   active: boolean;
   time: string;
   dateOfBirth: Date;
@@ -64,6 +65,7 @@ const sampleData: RowData[] = [
     email: { value: 'alice.johnson@example.com' },
     role: { value: 'Developer' },
     status: { value: 'Active' },
+    marks: 84,
     active: true,
     time: '2026-01-28 12:00:00',
     dateOfBirth: new Date(1990, 0, 1),
@@ -74,6 +76,7 @@ const sampleData: RowData[] = [
     email: { value: 'bob.smith@example.com' },
     role: { value: 'Designer' },
     status: { value: 'Active' },
+    marks: 76,
     active: false,
     time: '2026-01-28 13:00:00',
     dateOfBirth: new Date(1991, 1, 2),
@@ -84,6 +87,7 @@ const sampleData: RowData[] = [
     email: { value: 'charlie.brown@example.com' },
     role: { value: 'Manager' },
     status: { value: 'Inactive' },
+    marks: 92,
     active: true,
     time: '2026-01-28 14:00:00',
     dateOfBirth: new Date(1992, 2, 3),
@@ -94,6 +98,7 @@ const sampleData: RowData[] = [
     email: { value: 'diana.prince@example.com' },
     role: { value: 'Developer' },
     status: { value: 'Active' },
+    marks: 88,
     active: false,
     time: '2026-01-28 15:00:00',
     dateOfBirth: new Date(1993, 3, 4),
@@ -104,6 +109,7 @@ const sampleData: RowData[] = [
     email: { value: 'ethan.hunt@example.com' },
     role: { value: 'Analyst' },
     status: { value: 'Active' },
+    marks: 69,
     active: false,
     time: '2026-01-28 16:00:00',
     dateOfBirth: new Date(1994, 4, 5),
@@ -154,6 +160,17 @@ const sampleColumnDefs: (ColDef | ColGroupDef)[] = [
     valueFormatter: Table.DefaultValueFormatter,
   },
   { field: 'status', valueFormatter: Table.DefaultValueFormatter },
+  {
+    field: 'marks',
+    cellDataType: 'number',
+    cellEditor: 'dsNumberCellEditor',
+    cellEditorParams: {
+      min: 0,
+      max: 100,
+      step: 1,
+      disableSpinners: false,
+    },
+  },
   {
     field: 'active',
     filter: { component: BooleanFilter, doesFilterPass: doesBooleanFilterPass },
@@ -168,6 +185,60 @@ const sampleColumnDefs: (ColDef | ColGroupDef)[] = [
   },
 ];
 
+const verticalHeaderTextColumnDefs: (ColDef | ColGroupDef)[] = [
+  {
+    headerName: 'Details',
+    children: [
+      {
+        field: 'name',
+        headerName: 'Preferred Learner Name',
+        filter: 'agSetColumnFilter',
+      },
+      {
+        field: 'email',
+        headerName: 'Primary Contact Email Address',
+        filter: 'agSetColumnFilter',
+      },
+      {
+        field: 'role',
+        headerName: 'Role',
+        filter: 'agSetColumnFilter',
+      },
+      {
+        field: 'dateOfBirth',
+        headerName: 'Date of Birth',
+        filter: 'agDateColumnFilter',
+        filterParams: { buttons: ['clear', 'apply'] },
+        valueFormatter: params =>
+          params.value instanceof Date
+            ? params.value.toLocaleDateString()
+            : params.value,
+      },
+    ],
+    valueFormatter: Table.DefaultValueFormatter,
+  },
+  {
+    field: 'status',
+    headerName: 'Current Enrollment Status',
+  },
+  {
+    field: 'marks',
+    headerName: 'Overall Score (%)',
+    cellDataType: 'number',
+  },
+  {
+    field: 'active',
+    headerName: 'Active?',
+    cellDataType: 'boolean',
+    editable: false,
+  },
+  {
+    field: 'time',
+    headerName: 'Most Recent Activity Timestamp',
+    editable: false,
+  },
+];
+
 const footerContent = [
   <Button key={0} variant="primary">
     Button 1
@@ -201,6 +272,28 @@ export const Default: Story = {
   },
 };
 
+export const WithVerticalHeaderText: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use the `verticalHeaderText` prop when columns are narrow and header labels need to remain readable.',
+      },
+    },
+  },
+  args: {
+    rowData: sampleData,
+    columnDefs: verticalHeaderTextColumnDefs,
+    defaultColDef: {
+      ...defaultColDef,
+      wrapHeaderText: true,
+      autoHeaderHeight: true,
+    },
+    domLayout: 'autoHeight',
+    verticalHeaderText: true,
+  },
+};
+
 export const WithFooter: Story = {
   args: {
     rowData: sampleData,

package/src/components/table/Table.test.tsx

@@ -36,6 +36,20 @@ describe('Table', () => {
     expect(screen.getByTestId('test-table')).toHaveClass('ds-table__container');
   });
 
+  describe('verticalHeaderText', () => {
+    test('applies vertical header text class when enabled', () => {
+      const { container } = render(<Table verticalHeaderText />);
+
+      expect(container.querySelector('.ds-table')).toHaveClass('ds-table--vertical-header-text');
+    });
+
+    test('does not apply vertical header text class by default', () => {
+      const { container } = render(<Table />);
+
+      expect(container.querySelector('.ds-table')).not.toHaveClass('ds-table--vertical-header-text');
+    });
+  });
+
   describe('TableHeader', () => {
     test('renders header when headerContent is provided', () => {
       render(<Table headerContent={<div>Header content</div>} />);
@@ -1406,6 +1420,247 @@ describe('Table', () => {
 
         expect(onCellValueChanged).toHaveBeenLastCalledWith(expect.objectContaining({ oldValue: 30, newValue: 35 }));
       });
+
+      test('supports editing number fields with the number cell editor spinners', async () => {
+        const onCellValueChanged = vi.fn();
+        const columnDefs = [{
+          field: 'age',
+          headerName: 'Age',
+          editable: true,
+          cellDataType: 'number',
+          cellEditor: 'dsNumberCellEditor',
+          cellEditorParams: {
+            min: 0,
+            max: 100,
+            step: 5,
+            disableSpinners: false,
+          },
+        }];
+        const rowData = [
+          { id: 1, name: 'John Doe', age: 30 },
+          { id: 2, name: 'Jane Smith', age: 25 },
+        ];
+
+        render(
+          <Table
+            columnDefs={columnDefs}
+            rowData={rowData}
+            onCellValueChanged={onCellValueChanged}
+          />,
+        );
+
+        await waitFor(() => expect(screen.getByRole('grid')).toBeInTheDocument());
+        await waitFor(() => expect(screen.getByText('30')).toBeInTheDocument());
+
+        const cell = screen.getByText('30');
+        await userEvent.dblClick(cell);
+
+        const editorInput = await screen.findByRole('textbox');
+        expect(editorInput).toHaveFocus();
+
+        await userEvent.click(screen.getByLabelText('Plus button'));
+        await userEvent.keyboard('{Enter}');
+
+        await waitFor(() => {
+          expect(onCellValueChanged).toHaveBeenCalled();
+        });
+
+        expect(onCellValueChanged).toHaveBeenLastCalledWith(expect.objectContaining({ oldValue: 30, newValue: 35 }));
+      });
+
+      test('clamps out-of-range number editor values when committing with enter', async () => {
+        const onCellValueChanged = vi.fn();
+        const columnDefs = [{
+          field: 'age',
+          headerName: 'Age',
+          editable: true,
+          cellDataType: 'number',
+          cellEditor: 'dsNumberCellEditor',
+          cellEditorParams: {
+            min: 0,
+            max: 100,
+            step: 1,
+            disableSpinners: true,
+          },
+        }];
+        const rowData = [
+          { id: 1, name: 'John Doe', age: 30 },
+          { id: 2, name: 'Jane Smith', age: 25 },
+        ];
+
+        render(
+          <Table
+            columnDefs={columnDefs}
+            rowData={rowData}
+            onCellValueChanged={onCellValueChanged}
+          />,
+        );
+
+        await waitFor(() => expect(screen.getByRole('grid')).toBeInTheDocument());
+        await waitFor(() => expect(screen.getByText('30')).toBeInTheDocument());
+
+        const cell = screen.getByText('30');
+        await userEvent.dblClick(cell);
+
+        const editorInput = await screen.findByRole('textbox');
+        await userEvent.clear(editorInput);
+        await userEvent.type(editorInput, '150');
+        await userEvent.keyboard('{Enter}');
+
+        await waitFor(() => {
+          expect(onCellValueChanged).toHaveBeenCalled();
+        });
+
+        const lastCellChangeEvent = onCellValueChanged.mock.calls.at(-1)?.[0];
+        expect(lastCellChangeEvent?.oldValue).toBe(30);
+        expect(lastCellChangeEvent?.newValue).toBe(100);
+      });
+
+      test('clamps below-min number editor values when committing with enter', async () => {
+        const onCellValueChanged = vi.fn();
+        const columnDefs = [{
+          field: 'age',
+          headerName: 'Age',
+          editable: true,
+          cellDataType: 'number',
+          cellEditor: 'dsNumberCellEditor',
+          cellEditorParams: {
+            min: 0,
+            max: 100,
+            step: 1,
+            disableSpinners: true,
+          },
+        }];
+        const rowData = [
+          { id: 1, name: 'John Doe', age: 30 },
+          { id: 2, name: 'Jane Smith', age: 25 },
+        ];
+
+        render(
+          <Table
+            columnDefs={columnDefs}
+            rowData={rowData}
+            onCellValueChanged={onCellValueChanged}
+          />,
+        );
+
+        await waitFor(() => expect(screen.getByRole('grid')).toBeInTheDocument());
+        await waitFor(() => expect(screen.getByText('30')).toBeInTheDocument());
+
+        const cell = screen.getByText('30');
+        await userEvent.dblClick(cell);
+
+        const editorInput = await screen.findByRole('textbox');
+        await userEvent.clear(editorInput);
+        await userEvent.type(editorInput, '-5');
+        await userEvent.keyboard('{Enter}');
+
+        await waitFor(() => {
+          expect(onCellValueChanged).toHaveBeenCalled();
+        });
+
+        const lastCellChangeEvent = onCellValueChanged.mock.calls.at(-1)?.[0];
+        expect(lastCellChangeEvent?.oldValue).toBe(30);
+        expect(lastCellChangeEvent?.newValue).toBe(0);
+      });
+
+      test('does not clamp in-progress number editor typing before commit', async () => {
+        const onCellValueChanged = vi.fn();
+        const columnDefs = [{
+          field: 'age',
+          headerName: 'Age',
+          editable: true,
+          cellDataType: 'number',
+          cellEditor: 'dsNumberCellEditor',
+          cellEditorParams: {
+            min: 50,
+            max: 100,
+            step: 1,
+            disableSpinners: true,
+          },
+        }];
+        const rowData = [
+          { id: 1, name: 'John Doe', age: 60 },
+          { id: 2, name: 'Jane Smith', age: 25 },
+        ];
+
+        render(
+          <Table
+            columnDefs={columnDefs}
+            rowData={rowData}
+            onCellValueChanged={onCellValueChanged}
+          />,
+        );
+
+        await waitFor(() => expect(screen.getByRole('grid')).toBeInTheDocument());
+        await waitFor(() => expect(screen.getByText('60')).toBeInTheDocument());
+
+        const cell = screen.getByText('60');
+        await userEvent.dblClick(cell);
+
+        const editorInput = await screen.findByRole('textbox');
+        await userEvent.clear(editorInput);
+        await userEvent.type(editorInput, '6');
+        expect(editorInput).toHaveValue('6');
+        await userEvent.type(editorInput, '5');
+        await userEvent.keyboard('{Enter}');
+
+        await waitFor(() => {
+          expect(onCellValueChanged).toHaveBeenCalled();
+        });
+
+        const lastCellChangeEvent = onCellValueChanged.mock.calls.at(-1)?.[0];
+        expect(lastCellChangeEvent?.oldValue).toBe(60);
+        expect(lastCellChangeEvent?.newValue).toBe(65);
+      });
+
+      test('supports clearing number editor values and committing null', async () => {
+        const onCellValueChanged = vi.fn();
+        const columnDefs = [{
+          field: 'age',
+          headerName: 'Age',
+          editable: true,
+          cellDataType: 'number',
+          cellEditor: 'dsNumberCellEditor',
+          cellEditorParams: {
+            min: 0,
+            max: 100,
+            step: 1,
+            disableSpinners: true,
+          },
+        }];
+        const rowData = [
+          { id: 1, name: 'John Doe', age: 30 },
+          { id: 2, name: 'Jane Smith', age: 25 },
+        ];
+
+        render(
+          <Table
+            columnDefs={columnDefs}
+            rowData={rowData}
+            onCellValueChanged={onCellValueChanged}
+          />,
+        );
+
+        await waitFor(() => expect(screen.getByRole('grid')).toBeInTheDocument());
+        await waitFor(() => expect(screen.getByText('30')).toBeInTheDocument());
+
+        const cell = screen.getByText('30');
+        await userEvent.dblClick(cell);
+
+        const editorInput = await screen.findByRole('textbox');
+        expect(screen.queryByLabelText('Plus button')).not.toBeInTheDocument();
+        expect(screen.queryByLabelText('Minus button')).not.toBeInTheDocument();
+
+        await userEvent.clear(editorInput);
+        await userEvent.keyboard('{Enter}');
+
+        await waitFor(() => {
+          expect(onCellValueChanged).toHaveBeenCalled();
+        });
+
+        expect(onCellValueChanged).toHaveBeenLastCalledWith(expect.objectContaining({ oldValue: 30, newValue: null }));
+      });
     });
 
     /**

package/src/components/table/Table.tsx

@@ -16,6 +16,7 @@ import { useTableSettings, type UseTableSettingsParams } from './useTableSetting
 import { setAgGridLicenseKey } from 'Utils/setAgGridLicenseKey';
 import { toggleRowSelectionInCurrentRange } from './toggleRowSelectionInCurrentRange';
 import { defaultValueFormatter, DSDefaultColDef, shouldSuppressFocus } from './DSDefaultColDef';
+import { NumberCellEditor } from './cellEditors/NumberCellEditor';
 import { ButtonCellRenderer } from './cellRenderers/ButtonCellRenderer';
 import { InlineTextCellRenderer } from './cellRenderers/InlineTextCellRenderer';
 import { SelectDropdownCellRenderer } from './cellRenderers/SelectDropdownCellRenderer';
@@ -45,6 +46,7 @@ type TableProps<TData = any> = {
   'enableSimultaneousRangeAndRowSelection'?: boolean;
   'disableDragSelect'?: boolean;
   'tableTheme'?: string;
+  'verticalHeaderText'?: boolean;
 } & UseTableSettingsParams & AgGridReactProps<TData>;
 
 setAgGridLicenseKey();
@@ -76,6 +78,8 @@ export const Table = (props: TableProps) => {
     components = {},
     tableTheme,
     onCellFocused,
+    verticalHeaderText = false,
+    className: propsClassName,
     ...rest
   } = props;
 
@@ -151,6 +155,7 @@ export const Table = (props: TableProps) => {
               setGridApi(api);
               onGridReady?.(event);
             }}
+            className={classNames('ds-table', { 'ds-table--vertical-header-text': verticalHeaderText }, propsClassName)}
             enableFilterHandlers
             suppressPaginationPanel
             onCellSelectionChanged={(event) => {
@@ -185,6 +190,7 @@ export const Table = (props: TableProps) => {
               dsSelectDropdownCellRenderer: SelectDropdownCellRenderer,
               dsBooleanFilter: BooleanFilter,
               dsTimeFilter: TimeFilter,
+              dsNumberCellEditor: NumberCellEditor,
               dsDateCellEditor: DateCellEditor,
               dsCheckboxCellRenderer: CheckboxCellRenderer,
               dsBooleanCellRenderer: BooleanCellRenderer,