@arbor-education/design-system.components 4.9.2 → 5.0.0

package/src/components/row/Row.stories.tsx

@@ -25,6 +25,7 @@ const DESCRIPTION_INTRO = [
   'Pass an `onClick` handler to make the row fully interactive — it enters the tab order, gains hover and focus styles, and renders a pair of animated directional icons.',
   'Pass `href` to turn the value into a native anchor link, supporting any protocol including `mailto:` and `tel:`.',
   'Pass `tooltipText` to show an explanatory tooltip when a user hovers the row — useful for read-only fields or values that need additional context.',
+  'Pass `isActive` to highlight the row as the one currently being worked on, for example the row a slideover was opened from.',
 ].join(' ');
 
 const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
@@ -60,6 +61,9 @@ const DEVELOPER_NOTES = [
   '| Static | `-1` (not in tab order) | — | None |',
   '| Clickable | `0` (in tab order) | `ds-row--clickable` | `chevron-right` + `arrow-right` |',
   '',
+  '`isActive` is independent of `onClick`: it adds the `ds-row--active` modifier and `aria-current="true"`, and can be combined with either state.',
+  'The active background is kept on hover so an active clickable row stays distinguishable from its siblings.',
+  '',
   '**Dual-icon swap:** Both icons are always in the DOM when `onClick` is provided. CSS controls visibility —',
   'at rest `chevron-right` shows; on hover/focus `arrow-right` shows. No JavaScript state is involved.',
   '',
@@ -109,6 +113,7 @@ const DEVELOPER_NOTES = [
   '|---|---|',
   '| `--section-list-row-default-color-background` | Resting background colour |',
   '| `--section-list-row-hover-hover-bg` | Hover background (clickable rows only) |',
+  '| `--section-list-row-active-active-bg` | Background of an active row (`isActive`), including on hover |',
   '| `--section-list-row-spacing-vertical` | Top/bottom padding |',
   '| `--section-list-row-spacing-horizontal` | Left/right padding |',
   '| `--section-list-row-radius` | Border radius |',
@@ -133,6 +138,7 @@ const DEVELOPER_NOTES = [
   '  note?: ReactNode;',
   '  placeholder?: string;',
   '  tooltipText?: string;',
+  '  isActive?: boolean;',
   '  onClick?: MouseEventHandler<HTMLDivElement>;',
   '};',
   '```',
@@ -256,6 +262,18 @@ const meta = {
         defaultValue: { summary: 'undefined' },
       },
     },
+    isActive: {
+      description: [
+        'Marks the row as the currently active or selected row, such as the row a slideover was opened from.',
+        'Adds the `ds-row--active` modifier and `aria-current="true"`, and applies the `--section-list-row-active-active-bg` background, which is kept on hover.',
+        'Combine with `onClick` for an active row that is also clickable.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
     onClick: {
       description: [
         'When provided, activates all clickable behaviour: the row enters the tab order (`tabIndex={0}`),',
@@ -757,6 +775,51 @@ export default GuardianRow;
   'Clickable row with all three right-side elements active: value, note, and the chevron/arrow icon pair. The note takes 20% flex-basis; the value narrows to 50%; the icon is flex-shrunk. The secondary context ("Primary contact") persists alongside the navigation affordance.',
 );
 
+export const Active: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Section } from '@arbor-education/design-system.components';
+
+function GuardianSection({ activeGuardianId, openGuardian }) {
+  return (
+    <Section title="Guardians">
+      <Row
+        label="Mother"
+        value="Sarah Okafor"
+        isActive={activeGuardianId === 'guardian-42'}
+        onClick={() => openGuardian('guardian-42')}
+      />
+      <Row
+        label="Father"
+        value="David Okafor"
+        isActive={activeGuardianId === 'guardian-43'}
+        onClick={() => openGuardian('guardian-43')}
+      />
+      <Row label="Emergency contact" value="Grace Mensah" isActive={false} />
+    </Section>
+  );
+}
+export default GuardianSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section title="Guardians">
+        <Row label="Mother" value="Sarah Okafor" isActive onClick={fn()} />
+        <Row label="Father" value="David Okafor" onClick={fn()} />
+        <Row label="Emergency contact" value="Grace Mensah" />
+      </Section>
+    ),
+  },
+  'Set `isActive` to highlight the row currently being worked on — for example the row a slideover was opened from. The first row is active **and** clickable: it keeps the active background on hover, retains its focus ring and keyboard activation, and exposes `aria-current="true"`. The other rows render exactly as they do without the prop.',
+);
+
 export const MixedClickableAndStatic: Story = withDescription(
   {
     parameters: {

package/src/components/row/Row.test.tsx

@@ -106,6 +106,65 @@ describe('Row component', () => {
     });
   });
 
+  describe('active behaviour', () => {
+    test('applies the active modifier when isActive is true', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveClass('ds-row--active');
+    });
+
+    test('marks an active row as the current item for assistive technology', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveAttribute('aria-current', 'true');
+    });
+
+    test('does not apply the active modifier when isActive is omitted', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" />);
+
+      const row = container.querySelector('.ds-row');
+      expect(row).not.toHaveClass('ds-row--active');
+      expect(row).not.toHaveAttribute('aria-current');
+    });
+
+    test('does not apply the active modifier when isActive is false', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive={false} />);
+
+      expect(container.querySelector('.ds-row')).not.toHaveClass('ds-row--active');
+    });
+
+    test('keeps clickable behaviour on an active clickable row', async () => {
+      const handleClick = vi.fn();
+      const { container } = render(
+        <Row label="Guardian" value="Sarah Okafor" isActive onClick={handleClick} />,
+      );
+
+      const row = container.querySelector('.ds-row')!;
+      expect(row).toHaveClass('ds-row--active', 'ds-row--clickable');
+      expect(row).toHaveAttribute('tabindex', '0');
+
+      await userEvent.click(screen.getByText('Sarah Okafor'));
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('activates an active clickable row with the keyboard', async () => {
+      const handleClick = vi.fn();
+      render(<Row label="Guardian" value="Sarah Okafor" isActive onClick={handleClick} />);
+
+      await userEvent.tab();
+      await userEvent.keyboard('{Enter}');
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('combines the active modifier with a custom className', () => {
+      const { container } = render(<Row label="Guardian" className="custom-row" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveClass('ds-row', 'ds-row--active', 'custom-row');
+    });
+  });
+
   describe('placeholder behaviour', () => {
     test('renders placeholder text when no value is provided', () => {
       render(<Row label="Medical condition" placeholder="Not recorded" />);

package/src/components/row/Row.tsx

@@ -13,6 +13,7 @@ export type RowProps = {
   note?: ReactNode;
   placeholder?: string;
   tooltipText?: string;
+  isActive?: boolean;
   onClick?: MouseEventHandler<HTMLDivElement>;
 };
 
@@ -26,6 +27,7 @@ export const Row = (props: RowProps) => {
     note,
     placeholder,
     tooltipText,
+    isActive = false,
     onClick,
   } = props;
 
@@ -47,10 +49,12 @@ export const Row = (props: RowProps) => {
         'ds-row',
         {
           'ds-row--clickable': isClickable,
+          'ds-row--active': isActive,
         },
         className,
       )}
       style={style}
+      aria-current={isActive ? 'true' : undefined}
       onClick={onClick}
       onKeyDown={(e) => {
         if (isClickable && [ENTER_KEY, SPACE_KEY].includes(e.key)) {

package/src/components/row/row.scss

@@ -11,7 +11,6 @@
   .ds-row__icon-click {
     flex-shrink: 0;
     stroke: var(--section-list-row-default-color-icon-arrow);
-    
 
     &.ds-icon-arrow-right {
       display: none;
@@ -26,6 +25,11 @@
     }
   }
 
+  &--active,
+  &--active:hover {
+    background-color: var(--section-list-row-active-active-bg);
+  }
+
   &:focus {
     box-shadow: 0 0 0 3px var(--color-brand-300);
     outline: none;
@@ -34,7 +38,6 @@
   &:hover {
     .ds-row__icon-click {
         stroke: var(--section-list-row-hover-color-icon-arrow);
-      
 
       &.ds-icon-chevron-right {
         display: none;

package/src/utils/hooks/useIsControlledOnceSet.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useIsControlledOnceSet } from './useIsControlledOnceSet.js';
+
+describe('useIsControlledOnceSet', () => {
+  test('is uncontrolled while no value has been received', () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useIsControlledOnceSet(value),
+      { initialProps: { value: undefined as Date | undefined } },
+    );
+
+    rerender({ value: undefined });
+
+    expect(result.current).toBe(false);
+  });
+
+  test('is controlled from the first render with a value', () => {
+    const { result } = renderHook(() => useIsControlledOnceSet(new Date(2026, 3, 14)));
+
+    expect(result.current).toBe(true);
+  });
+
+  test('becomes controlled when a value arrives after an empty mount', () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useIsControlledOnceSet(value),
+      { initialProps: { value: undefined as Date | undefined } },
+    );
+
+    rerender({ value: new Date(2026, 3, 14) });
+
+    expect(result.current).toBe(true);
+  });
+
+  test('stays controlled when the value is cleared', () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useIsControlledOnceSet(value),
+      { initialProps: { value: new Date(2026, 3, 14) as Date | undefined } },
+    );
+
+    rerender({ value: undefined });
+
+    expect(result.current).toBe(true);
+  });
+});

package/src/utils/hooks/useIsControlledOnceSet.ts

@@ -0,0 +1,13 @@
+import { useRef } from 'react';
+
+/**
+ * Treats a component as controlled from the first render that receives a `value`, so a later
+ * `undefined` means "controlled and empty" rather than reverting to uncontrolled.
+ */
+export const useIsControlledOnceSet = <T>(value: T | undefined) => {
+  const hasReceivedValueRef = useRef(value !== undefined);
+  if (value !== undefined) {
+    hasReceivedValueRef.current = true;
+  }
+  return hasReceivedValueRef.current;
+};