@arbor-education/design-system.components 3.4.5 → 3.6.0

package/src/components/widgetCalendar/WidgetCalendar.stories.tsx

@@ -227,7 +227,7 @@ const meta = {
       description: [
         'Array of `WidgetCalendar.ItemData` objects rendered as event rows. Each item requires `id`,',
         '`eventPrimaryTerm`, `eventPrimaryDefinition`, `eventSecondaryTerm`, `eventDateTime`, and `eventTimeLabel`.',
-        '`eventType`, `eventLocation`, `eventSecondaryDefinition`, and `buttonA11yText` are optional.',
+        '`eventType`, `eventLocation`, `eventSecondaryDefinition`, `buttonA11yText`, and `tooltip` are optional.',
       ].join(' '),
       table: {
         type: { summary: 'WidgetCalendar.ItemData[]' },
@@ -609,6 +609,48 @@ export const WithTooltip: Story = withDescription(
   'Adding `tooltip` shows supplementary context alongside the heading. A single event keeps the focus on the tooltip.',
 );
 
+export const WithItemTooltips: Story = withDescription(
+  {
+    args: {
+      heading: 'Calendar',
+      items: [
+        {
+          id: 'year-10-10g',
+          eventType: 'primary',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Year 10: 10G',
+          tooltip: 'Room change — this lesson has moved from Classroom 204',
+          ...classEventTime,
+        },
+        {
+          id: 'class-generic',
+          eventType: 'secondary',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Class',
+          ...classEventTime,
+        },
+        {
+          id: 'maths-year-10',
+          eventType: 'primary',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Maths: Year 10: 10x/Ma3',
+          tooltip: 'Cover teacher: Mrs Stanhope',
+          ...classEventTime,
+        },
+      ],
+      onItemClick: fn(),
+    },
+    render: args => <WidgetCalendar {...args} />,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'Per-item `tooltip` text, set on `ItemData`, shown on hover or focus of the row. Use it for',
+    'short supplementary context that would clutter the row itself — a room change, a cover teacher.',
+    'Items without a `tooltip` render exactly as before. Tooltips work on both interactive and',
+    'non-interactive rows, and keyboard interaction (Enter/Space) is unaffected.',
+  ].join(' '),
+);
+
 export const Empty: Story = withDescription(
   {
     args: {

package/src/components/widgetCalendar/WidgetCalendar.test.tsx

@@ -1,5 +1,5 @@
 import '@testing-library/jest-dom/vitest';
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { describe, expect, test, vi } from 'vitest';
 import { WidgetCalendar } from './WidgetCalendar.js';
@@ -134,4 +134,76 @@ describe('WidgetCalendar', () => {
 
     expect(screen.getByRole('heading', { name: 'Nothing scheduled' })).toBeInTheDocument();
   });
+
+  describe('item tooltips', () => {
+    const tooltipItems: WidgetCalendar.ItemData[] = [
+      {
+        id: 'year-10',
+        eventType: 'primary',
+        eventPrimaryTerm: 'Class',
+        eventPrimaryDefinition: 'Year 10: 10G',
+        eventSecondaryTerm: 'Time and location',
+        eventDateTime: '2026-06-08T08:45/2026-06-08T09:00',
+        eventTimeLabel: '08:45 – 09:00',
+        eventLocation: 'Classroom 102',
+        tooltip: 'Double maths with Mr Cullen',
+      },
+      {
+        id: 'class-label',
+        eventType: 'secondary',
+        eventPrimaryTerm: 'Class',
+        eventPrimaryDefinition: 'Class',
+        eventSecondaryTerm: 'Time and location',
+        eventDateTime: '2026-06-08T10:00/2026-06-08T10:45',
+        eventTimeLabel: '10:00 – 10:45',
+        eventLocation: 'Hall',
+      },
+    ];
+
+    test('shows tooltip text when hovering an item with a tooltip', async () => {
+      render(
+        <WidgetCalendar heading="Calendar" items={tooltipItems} />,
+      );
+
+      await userEvent.hover(screen.getByText('Year 10: 10G'));
+
+      await waitFor(() => {
+        expect(screen.getAllByText('Double maths with Mr Cullen').length).toBeGreaterThan(0);
+      });
+    });
+
+    test('does not show tooltip text until the item is hovered', () => {
+      render(
+        <WidgetCalendar heading="Calendar" items={tooltipItems} />,
+      );
+
+      expect(screen.queryByText('Double maths with Mr Cullen')).not.toBeInTheDocument();
+    });
+
+    test('renders items without a tooltip unchanged', () => {
+      render(
+        <WidgetCalendar heading="Calendar" items={tooltipItems} />,
+      );
+
+      expect(screen.getByText('10:00 – 10:45')).toBeInTheDocument();
+    });
+
+    test('tooltip does not break item activation on Enter key', () => {
+      const onItemClick = vi.fn();
+
+      render(
+        <WidgetCalendar
+          heading="Calendar"
+          items={tooltipItems}
+          onItemClick={onItemClick}
+        />,
+      );
+
+      const item = screen.getByRole('button', { name: 'Open Year 10: 10G' });
+
+      fireEvent.keyDown(item, { key: 'Enter' });
+
+      expect(onItemClick).toHaveBeenCalledWith('year-10');
+    });
+  });
 });

package/src/components/widgetCalendar/WidgetCalendar.tsx

@@ -15,6 +15,7 @@ type WidgetCalendarItemData = {
   eventLocation?: string;
   eventSecondaryDefinition?: React.ReactNode;
   buttonA11yText?: string;
+  tooltip?: string;
 };
 
 type WidgetCalendarProps = {
@@ -71,6 +72,7 @@ export const WidgetCalendar = (props: WidgetCalendarProps): React.JSX.Element =>
                 eventSecondaryDefinition={item.eventSecondaryDefinition}
                 buttonA11yText={item.buttonA11yText}
                 onItemClick={onItemClick ? () => onItemClick(item.id) : undefined}
+                tooltip={item.tooltip}
               />
             ))}
           </ul>

package/src/components/widgetCalendar/WidgetCalendarItem.tsx

@@ -1,5 +1,6 @@
 import classNames from 'classnames';
 import { Icon } from 'Components/icon/Icon';
+import { TooltipWrapper } from 'Components/tooltip/TooltipWrapper';
 import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
 
 export type WidgetCalendarEventType = 'primary' | 'secondary';
@@ -17,6 +18,7 @@ export type WidgetCalendarItemProps = {
   buttonA11yText?: string;
   onItemClick?: () => void;
   className?: string;
+  tooltip?: string;
 };
 
 export const WidgetCalendarItem = (props: WidgetCalendarItemProps): React.JSX.Element => {
@@ -33,6 +35,7 @@ export const WidgetCalendarItem = (props: WidgetCalendarItemProps): React.JSX.El
     buttonA11yText,
     onItemClick,
     className,
+    tooltip,
   } = props;
 
   const isInteractive = Boolean(onItemClick);
@@ -61,7 +64,7 @@ export const WidgetCalendarItem = (props: WidgetCalendarItemProps): React.JSX.El
     }
   };
 
-  return (
+  const item = (
     <li
       className={classNames(
         'ds-widget-calendar__item',
@@ -102,4 +105,14 @@ export const WidgetCalendarItem = (props: WidgetCalendarItemProps): React.JSX.El
       )}
     </li>
   );
+
+  if (tooltip) {
+    return (
+      <TooltipWrapper tooltipContent={tooltip}>
+        {item}
+      </TooltipWrapper>
+    );
+  }
+
+  return item;
 };

package/src/index.scss

@@ -17,6 +17,7 @@
 @use "components/formField/label/label.scss";
 @use "components/formField/inputs/number/numberInput.scss";
 @use "components/formField/inputs/time/timeInput.scss";
+@use "components/formField/inputs/singleFile/singleFileInput.scss";
 @use "components/formField/inputs/radio/radioButtonInput.scss";
 @use "components/formField/inputs/checkbox/checkboxInput.scss";
 @use "components/formField/inputs/selectDropdown/selectDropdown";

package/src/index.ts

@@ -35,6 +35,7 @@ export { NumberInput } from 'Components/formField/inputs/number/NumberInput';
 export { RadioButtonGroup } from 'Components/formField/inputs/radio/RadioButtonGroup';
 export { RadioButtonInput } from 'Components/formField/inputs/radio/RadioButtonInput';
 export { SelectDropdown } from 'Components/formField/inputs/selectDropdown/SelectDropdown';
+export { SingleFileInput } from 'Components/formField/inputs/singleFile/SingleFileInput';
 export { Skeleton } from 'Components/skeleton/Skeleton';
 export { TextInput } from 'Components/formField/inputs/text/TextInput';
 export { TextArea } from 'Components/formField/inputs/textArea/TextArea';