@arbor-education/design-system.components 4.3.0 → 4.5.0

package/dist/utils/SlideoverUtils.d.ts

@@ -1,7 +1,9 @@
 import type { SlideoverProps } from '../components/slideover/Slideover.js';
+type ManagedSlideoverProps = Omit<SlideoverProps, 'isClosing' | 'onCloseTransitionEnd'>;
 export declare const SlideoverUtils: {
-    addSlideover: (slideoverConfig: SlideoverProps) => void;
+    addSlideover: (slideoverConfig: ManagedSlideoverProps) => void;
     removeSlideover: () => void;
     removeAllSlideovers: () => void;
 };
+export {};
 //# sourceMappingURL=SlideoverUtils.d.ts.map

package/dist/utils/SlideoverUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SlideoverUtils.d.ts","sourceRoot":"","sources":["../../src/utils/SlideoverUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,eAAO,MAAM,cAAc;oCACO,cAAc;;;CAG/C,CAAC"}
+{"version":3,"file":"SlideoverUtils.d.ts","sourceRoot":"","sources":["../../src/utils/SlideoverUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAKrE,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,sBAAsB,CAAC,CAAC;AAExF,eAAO,MAAM,cAAc;oCACO,qBAAqB;;;CAGtD,CAAC"}

package/dist/utils/SlideoverUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"SlideoverUtils.js","sourceRoot":"","sources":["../../src/utils/SlideoverUtils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,YAAY,EAAE,CAAC,eAA+B,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,eAAe,CAAC;IAC3G,eAAe,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC;IACjE,mBAAmB,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC;CAC3E,CAAC"}
+{"version":3,"file":"SlideoverUtils.js","sourceRoot":"","sources":["../../src/utils/SlideoverUtils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,MAAM,MAAM,aAAa,CAAC;AAKjC,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,YAAY,EAAE,CAAC,eAAsC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,eAAe,CAAC;IAClH,eAAe,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC;IACjE,mBAAmB,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC;CAC3E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbor-education/design-system.components",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "The component library for the design system (the baby)",
   "main": "dist/index.js",
   "type": "module",

package/src/components/datePicker/DatePicker.stories.tsx

@@ -1,6 +1,7 @@
 import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
+  ArgTypes,
   Controls,
   Heading as DocHeading,
   Markdown,
@@ -9,8 +10,13 @@ import {
   Subtitle,
   Title,
 } from '@storybook/addon-docs/blocks';
+import { fn } from 'storybook/test';
+import { format } from 'date-fns';
+import { Button } from 'Components/button/Button';
 import { FormField } from 'Components/formField/FormField';
+import { Icon } from 'Components/icon/Icon';
 import { DatePicker } from './DatePicker.js';
+import { DatePickerPopover } from './DatePickerPopover.js';
 
 // ---------------------------------------------------------------------------
 // Docs page content
@@ -104,6 +110,44 @@ const DEVELOPER_NOTES = [
   '| `DatePicker.Props` | Full props interface |',
 ].join('\n');
 
+const POPOVER_NOTES = [
+  '`DatePickerPopover` is the calendar on its own: no date input, no icon button. You supply the',
+  'trigger (usually a `Button`) and the component opens the same calendar popover as `DatePicker`.',
+  'Use it when the date is shown elsewhere in your UI and you only need a way to pick or jump to a day,',
+  'for example a "jump to day" icon in a calendar header. For a form field where the user types or',
+  'sees the chosen date, use `DatePicker` instead.',
+  '',
+  '```tsx',
+  "import { Button, DatePickerPopover, Icon } from '@arbor-education/design-system.components';",
+  '',
+  '<DatePickerPopover',
+  '  value={date}',
+  '  onChange={setDate}',
+  '  trigger={(',
+  '    <Button variant="tertiary">',
+  '      <Icon name="date" screenReaderText="Jump to day" />',
+  '    </Button>',
+  '  )}',
+  '/>',
+  '```',
+  '',
+  '**Give the trigger an accessible name.** `DatePickerPopover` does not add one for you. A text',
+  'button is named by its text. An icon-only button needs `screenReaderText` on the `Icon` (or an',
+  '`aria-label` on the `Button`), otherwise screen reader users hear an unlabelled button.',
+  '',
+  '**The trigger must forward its ref and spread props onto a DOM node.** The design system `Button`',
+  'does. A custom component that does not will break popover anchoring and focus return to the trigger.',
+  '',
+  '**You own the value.** `onChange` receives a `Date`; store it and pass it back as `value`. If you',
+  'omit `value`, the calendar opens on the current month.',
+  '',
+  '**Time of day is kept.** Picking a day keeps the hours and minutes of the `value` you passed in.',
+  'Picking **Today** does the same.',
+  '',
+  '**Keyboard and focus.** Focus moves into the calendar when it opens. Selecting a day, choosing',
+  '**Today**, or pressing **Escape** closes the calendar and returns focus to your trigger.',
+].join('\n');
+
 const RELATED_COMPONENTS = [
   '## Related components',
   '',
@@ -130,6 +174,9 @@ function DatePickerDocsPage() {
       <Markdown>{USAGE_GUIDANCE}</Markdown>
       <DocHeading>Developer notes</DocHeading>
       <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>DatePickerPopover</DocHeading>
+      <Markdown>{POPOVER_NOTES}</Markdown>
+      <ArgTypes of={DatePickerPopover} />
       <DocHeading>Examples</DocHeading>
       <Stories title="" />
       <Markdown>{RELATED_COMPONENTS}</Markdown>
@@ -820,3 +867,249 @@ export default ParentEveningForm;
     'linked via `aria-describedby` automatically. Once a date is chosen, the error clears.',
   ].join(' '),
 );
+
+// ---------------------------------------------------------------------------
+// DatePickerPopover stories
+// ---------------------------------------------------------------------------
+
+type PopoverStory = StoryObj<typeof DatePickerPopover>;
+
+const withPopoverDescription = (story: PopoverStory, description: string): PopoverStory => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// Fixed date so the play functions are deterministic (15 June 2025, 14:30)
+const POPOVER_INITIAL_DATE = new Date(2025, 5, 15, 14, 30);
+
+const formatLongDate = (date: Date) => date.toLocaleDateString('en-GB', {
+  weekday: 'long',
+  day: 'numeric',
+  month: 'long',
+  year: 'numeric',
+});
+
+type PopoverTemplateProps = {
+  onChange?: (newDate: Date) => void;
+};
+
+const PopoverTextTriggerTemplate = ({ onChange }: PopoverTemplateProps) => {
+  const [date, setDate] = useState(POPOVER_INITIAL_DATE);
+
+  const handleChange = (newDate: Date) => {
+    setDate(newDate);
+    onChange?.(newDate);
+  };
+
+  return (
+    <div>
+      <DatePickerPopover
+        value={date}
+        onChange={handleChange}
+        trigger={<Button variant="secondary">Choose date</Button>}
+      />
+      <p className="ds-text">
+        Selected:
+        {' '}
+        <code>{`${date.toLocaleDateString('en-GB')} ${format(date, 'HH:mm')}`}</code>
+      </p>
+    </div>
+  );
+};
+
+const PopoverIconTriggerTemplate = ({ onChange }: PopoverTemplateProps) => {
+  const [date, setDate] = useState(POPOVER_INITIAL_DATE);
+
+  const handleChange = (newDate: Date) => {
+    setDate(newDate);
+    onChange?.(newDate);
+  };
+
+  return (
+    <div>
+      <DatePickerPopover
+        value={date}
+        onChange={handleChange}
+        trigger={(
+          <Button variant="tertiary">
+            <Icon name="date" screenReaderText="Choose date" />
+          </Button>
+        )}
+      />
+      <p className="ds-text">
+        Selected:
+        {' '}
+        <code>{date.toLocaleDateString('en-GB')}</code>
+      </p>
+    </div>
+  );
+};
+
+const PopoverCalendarHeaderTemplate = ({ onChange }: PopoverTemplateProps) => {
+  const [viewedDate, setViewedDate] = useState(POPOVER_INITIAL_DATE);
+
+  const handleChange = (newDate: Date) => {
+    setViewedDate(newDate);
+    onChange?.(newDate);
+  };
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <DatePickerPopover
+        value={viewedDate}
+        onChange={handleChange}
+        trigger={(
+          <Button variant="tertiary" borderless>
+            <Icon name="date" screenReaderText="Jump to day" />
+          </Button>
+        )}
+      />
+      <p className="ds-text">
+        <time dateTime={format(viewedDate, 'yyyy-MM-dd')}>{formatLongDate(viewedDate)}</time>
+      </p>
+    </div>
+  );
+};
+
+export const PopoverWithTextTrigger: PopoverStory = withPopoverDescription(
+  {
+    args: { onChange: fn() },
+    render: args => <PopoverTextTriggerTemplate onChange={args.onChange} />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, DatePickerPopover } from '@arbor-education/design-system.components';
+
+function ChooseDateButton() {
+  const [date, setDate] = useState(new Date(2025, 5, 15, 14, 30));
+
+  return (
+    <DatePickerPopover
+      value={date}
+      onChange={setDate}
+      // A text button is named by its text content
+      trigger={<Button variant="secondary">Choose date</Button>}
+    />
+  );
+}
+export default ChooseDateButton;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The simplest setup: a text `Button` as the trigger, with the date held in your own state.',
+    'The calendar opens on the month of `value`. Selecting a day (or **Today**) calls `onChange` with a',
+    '`Date`, keeps the time of day from `value`, closes the calendar and returns focus to the button.',
+    'The button is named by its text, so no extra accessibility props are needed.',
+  ].join(' '),
+);
+
+export const PopoverWithIconTrigger: PopoverStory = withPopoverDescription(
+  {
+    args: { onChange: fn() },
+    render: args => <PopoverIconTriggerTemplate onChange={args.onChange} />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, DatePickerPopover, Icon } from '@arbor-education/design-system.components';
+
+function ChooseDateIconButton() {
+  const [date, setDate] = useState(new Date(2025, 5, 15, 14, 30));
+
+  return (
+    <DatePickerPopover
+      value={date}
+      onChange={setDate}
+      trigger={(
+        <Button variant="tertiary">
+          {/* screenReaderText is the button's accessible name */}
+          <Icon name="date" screenReaderText="Choose date" />
+        </Button>
+      )}
+    />
+  );
+}
+export default ChooseDateIconButton;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'An icon-only trigger. The `Icon` is hidden from assistive technology, so **you must give the button',
+    'an accessible name**: use `screenReaderText` on the `Icon` (shown here) or `aria-label` on the `Button`.',
+    'Keyboard users can open the calendar with Enter or Space, move between days with the arrow keys,',
+    'and press **Escape** to close it without choosing a date. Focus returns to the icon button.',
+  ].join(' '),
+);
+
+export const PopoverCalendarHeaderJumpToDay: PopoverStory = withPopoverDescription(
+  {
+    args: { onChange: fn() },
+    render: args => <PopoverCalendarHeaderTemplate onChange={args.onChange} />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { format } from 'date-fns';
+import { Button, DatePickerPopover, Icon } from '@arbor-education/design-system.components';
+
+function CalendarHeader() {
+  const [viewedDate, setViewedDate] = useState(new Date(2025, 5, 15, 14, 30));
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <DatePickerPopover
+        value={viewedDate}
+        onChange={setViewedDate}
+        trigger={(
+          <Button variant="tertiary" borderless>
+            <Icon name="date" screenReaderText="Jump to day" />
+          </Button>
+        )}
+      />
+      <time dateTime={format(viewedDate, 'yyyy-MM-dd')}>
+        {viewedDate.toLocaleDateString('en-GB', {
+          weekday: 'long',
+          day: 'numeric',
+          month: 'long',
+          year: 'numeric',
+        })}
+      </time>
+    </div>
+  );
+}
+export default CalendarHeader;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The motivating use case: a "jump to day" icon button in a calendar header, with the currently viewed',
+    'date shown beside it. The date lives in your state, so the heading updates as soon as a day is picked',
+    'and the same value is passed back in as `value` the next time the calendar opens.',
+    'There is no date input, so the header stays compact and the selection is communicated by the text next to the button.',
+  ].join(' '),
+);

package/src/components/datePicker/DatePickerPopover.test.tsx

@@ -0,0 +1,144 @@
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom/vitest';
+import { Button } from 'Components/button/Button';
+import { DatePickerPopover } from './DatePickerPopover.js';
+
+const renderPopover = (props: Partial<React.ComponentProps<typeof DatePickerPopover>> = {}) => render(
+  <DatePickerPopover
+    trigger={<Button>Jump to date</Button>}
+    value={new Date(2025, 5, 15, 14, 30)}
+    {...props}
+  />,
+);
+
+const openCalendar = () => userEvent.click(screen.getByRole('button', { name: 'Jump to date' }));
+
+describe('DatePickerPopover', () => {
+  test('renders the consumer trigger and no date input', () => {
+    const { container } = renderPopover();
+    expect(screen.getByRole('button', { name: 'Jump to date' })).toBeInTheDocument();
+    expect(container.querySelector('input')).not.toBeInTheDocument();
+  });
+
+  test('calendar is hidden until the trigger is activated', async () => {
+    renderPopover();
+    expect(screen.queryByRole('application')).not.toBeInTheDocument();
+
+    await openCalendar();
+
+    expect(screen.getByRole('application')).toBeInTheDocument();
+  });
+
+  test('opens on the month of the supplied value', async () => {
+    renderPopover();
+    await openCalendar();
+
+    expect(within(screen.getByRole('application')).getByRole('button', { name: /June 20/ })).toBeInTheDocument();
+  });
+
+  test('selecting a day calls onChange with a Date and closes the calendar', async () => {
+    const onChange = vi.fn();
+    renderPopover({ onChange });
+    await openCalendar();
+
+    await userEvent.click(within(screen.getByRole('application')).getByRole('button', { name: /June 20/ }));
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    const selected = onChange.mock.lastCall?.[0] as Date;
+    expect(selected).toBeInstanceOf(Date);
+    expect([selected.getFullYear(), selected.getMonth(), selected.getDate()]).toEqual([2025, 5, 20]);
+    expect(screen.queryByRole('application')).not.toBeInTheDocument();
+  });
+
+  test('selecting a day preserves the time of the supplied value', async () => {
+    const onChange = vi.fn();
+    renderPopover({ onChange });
+    await openCalendar();
+
+    await userEvent.click(within(screen.getByRole('application')).getByRole('button', { name: /June 20/ }));
+
+    const selected = onChange.mock.lastCall?.[0] as Date;
+    expect([selected.getHours(), selected.getMinutes()]).toEqual([14, 30]);
+  });
+
+  test('clicking the already selected day still calls onChange and closes the calendar', async () => {
+    const onChange = vi.fn();
+    renderPopover({ onChange });
+    await openCalendar();
+
+    await userEvent.click(within(screen.getByRole('application')).getByRole('button', { name: /June 15/ }));
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange.mock.lastCall?.[0]).toBeInstanceOf(Date);
+    expect(screen.queryByRole('application')).not.toBeInTheDocument();
+  });
+
+  test('clicking Today calls onChange with today and closes the calendar', async () => {
+    const onChange = vi.fn();
+    renderPopover({ onChange });
+    await openCalendar();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Today' }));
+
+    const today = new Date();
+    const selected = onChange.mock.lastCall?.[0] as Date;
+    expect([selected.getFullYear(), selected.getMonth(), selected.getDate()])
+      .toEqual([today.getFullYear(), today.getMonth(), today.getDate()]);
+    expect(screen.queryByRole('application')).not.toBeInTheDocument();
+  });
+
+  test('works without a value, opening on the current month', async () => {
+    const onChange = vi.fn();
+    renderPopover({ value: undefined, onChange });
+    await openCalendar();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Today' }));
+
+    expect(onChange).toHaveBeenCalledWith(expect.any(Date));
+  });
+
+  test('focus moves into the calendar on open', async () => {
+    renderPopover();
+    await openCalendar();
+
+    expect(screen.getByRole('application')).toContainElement(document.activeElement as HTMLElement);
+  });
+
+  test('Escape closes the calendar and returns focus to the trigger', async () => {
+    renderPopover();
+    await openCalendar();
+
+    await userEvent.keyboard('{Escape}');
+
+    expect(screen.queryByRole('application')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Jump to date' })).toHaveFocus();
+  });
+
+  test('selecting a day returns focus to the trigger', async () => {
+    renderPopover();
+    await openCalendar();
+
+    await userEvent.click(within(screen.getByRole('application')).getByRole('button', { name: /June 20/ }));
+
+    expect(screen.getByRole('button', { name: 'Jump to date' })).toHaveFocus();
+  });
+
+  test('reopening shows the month of the latest value after the user browsed away', async () => {
+    const { rerender } = renderPopover();
+    await openCalendar();
+    await userEvent.click(screen.getByRole('button', { name: 'Go to the Next Month' }));
+    await userEvent.keyboard('{Escape}');
+
+    rerender(
+      <DatePickerPopover
+        trigger={<Button>Jump to date</Button>}
+        value={new Date(2025, 8, 3)}
+      />,
+    );
+    await openCalendar();
+
+    expect(within(screen.getByRole('application')).getByRole('button', { name: /September 10/ })).toBeInTheDocument();
+  });
+});

package/src/components/datePicker/DatePickerPopover.tsx

@@ -0,0 +1,72 @@
+import { Popover } from 'radix-ui';
+import { useContext, useState, type ReactElement } from 'react';
+import { PopupParentContext } from 'Utils/popupParent/PopupParentContext';
+import { formatTimeInputValue, mergeDateAndTime } from './dateInputUtils.js';
+import { DatePickerCalendar } from './DatePickerCalendar.js';
+import { DatePickerCalendarHeader } from './DatePickerCalendarHeader.js';
+
+const TIME_PRESERVATION_GRANULARITY = 'minute' as const;
+
+export type DatePickerPopoverProps = {
+  trigger: ReactElement;
+  value?: Date;
+  onChange?: (newDate: Date) => void;
+};
+
+export const DatePickerPopover = (props: DatePickerPopoverProps) => {
+  const { trigger, value, onChange } = props;
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [month, setMonth] = useState(value ?? new Date());
+  const popupParentRef = useContext(PopupParentContext);
+
+  const handleOpenChange = (open: boolean) => {
+    if (open) {
+      setMonth(value ?? new Date());
+    }
+    setIsOpen(open);
+  };
+
+  const selectDay = (day: Date) => {
+    const timeSource = value ?? day;
+    onChange?.(
+      mergeDateAndTime(
+        day,
+        formatTimeInputValue(timeSource, TIME_PRESERVATION_GRANULARITY),
+        TIME_PRESERVATION_GRANULARITY,
+      ),
+    );
+    setIsOpen(false);
+  };
+
+  const onDayPickerSelect = (day?: Date) => {
+    const selectedDay = day ?? value;
+    if (selectedDay) {
+      selectDay(selectedDay);
+    }
+  };
+
+  return (
+    <Popover.Root open={isOpen} onOpenChange={handleOpenChange}>
+      <Popover.Trigger asChild>{trigger}</Popover.Trigger>
+      <Popover.Portal container={popupParentRef.current}>
+        <Popover.Content align="end" sideOffset={5} onOpenAutoFocus={e => e.preventDefault()}>
+          <div className="ds-date-picker__popup">
+            <DatePickerCalendarHeader month={month} onMonthChange={setMonth} />
+            <DatePickerCalendar
+              month={month}
+              setMonth={setMonth}
+              selectedDate={value}
+              onDayPickerSelect={onDayPickerSelect}
+              handleTodayClick={() => selectDay(new Date())}
+            />
+          </div>
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+};
+
+export namespace DatePickerPopover {
+  export type Props = DatePickerPopoverProps;
+}