@arbor-education/design-system.components 0.25.9 → 1.0.0

package/src/components/widget/widget.scss

@@ -0,0 +1,218 @@
+.ds-widget {
+  width: 100%;
+}
+
+.ds-widget.ds-card__container {
+  height: 100%;
+  min-height: 0;
+  align-items: stretch;
+}
+
+.ds-widget .ds-card__content {
+  flex: 1 1 auto;
+  min-height: 0;
+  width: 100%;
+}
+
+.ds-widget .ds-card__body {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  min-height: 0;
+  height: 100%;
+}
+
+.ds-widget.ds-card__container:hover:not(.ds-card__container--disabled, .ds-widget--floating) {
+  box-shadow: none;
+}
+
+.ds-widget.ds-card__container.ds-widget--floating {
+  box-shadow: var(--shadow-medium);
+
+  &:hover:not(.ds-card__container--disabled) {
+    box-shadow: var(--shadow-medium);
+  }
+}
+
+.ds-widget__header {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-small);
+  width: 100%;
+  margin-bottom: var(--spacing-small);
+  flex-shrink: 0;
+}
+
+.ds-widget__header--linked {
+  position: relative;
+  cursor: pointer;
+
+  &:has(.ds-widget__header-link:focus-within) {
+    outline: var(--focus-border) solid var(--widget-heading-interactive-focus-color-border);
+    border-radius: var(--widget-heading-interactive-radius);
+  }
+}
+
+.ds-widget__header-title-group {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  flex: 1;
+  min-width: 0;
+}
+
+.ds-widget__header-slot-start {
+  display: inline-flex;
+  flex-shrink: 0;
+}
+
+.ds-widget__header-heading-row {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  min-width: 0;
+}
+
+.ds-widget__header--collapsible .ds-widget__header-heading-row {
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+}
+
+.ds-widget__header-heading {
+  margin: 0;
+}
+
+.ds-widget__header--collapsible .ds-widget__header-heading {
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+}
+
+.ds-widget__header-link {
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+  color: inherit;
+  text-decoration-line: underline;
+  text-decoration-style: solid;
+  text-underline-position: from-font;
+
+  &:hover {
+    color: inherit;
+    text-decoration: none;
+  }
+
+  &:focus {
+    outline: none;
+  }
+
+  &:focus-visible {
+    outline: none;
+  }
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+  }
+}
+
+.ds-widget__header-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-small);
+  width: 100%;
+  min-width: 0;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+
+  &:hover {
+    color: inherit;
+  }
+
+  &:focus-within {
+    outline: var(--focus-border) solid var(--widget-heading-interactive-focus-color-border);
+    border-radius: var(--widget-heading-interactive-radius);
+  }
+
+  .ds-heading__inner-container {
+    flex: 1;
+    min-width: 0;
+    text-align: left;
+  }
+}
+
+.ds-widget__header-chevron {
+  flex-shrink: 0;
+  transition: transform 0.16s ease;
+}
+
+.ds-widget__header-toggle[aria-expanded='true'] .ds-widget__header-chevron {
+  transform: rotate(90deg);
+}
+
+.ds-widget__header-end {
+  display: inline-flex;
+  padding-right: var(--spacing-small);
+  flex-shrink: 0;
+  align-items: center;
+  gap: var(--spacing-xsmall);
+  position: relative;
+  z-index: 2;
+}
+
+.ds-widget__header-tooltip-trigger {
+  position: relative;
+  z-index: 2;
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  cursor: pointer;
+  color: var(--color-grey-600);
+
+  &:focus-within {
+    outline: var(--focus-border) solid var(--widget-heading-interactive-focus-color-border);
+    border-radius: var(--widget-heading-interactive-radius);
+  }
+}
+
+.ds-widget__body {
+  position: relative;
+  width: 100%;
+  padding-top: var(--spacing-small);
+  border-top: var(--border-weight) solid var(--card-default-color-border);
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.ds-widget__body--collapsed {
+  display: none;
+}
+
+.ds-widget__loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-height: var(--spacing-xxxlarge);
+}
+
+.ds-widget__loading-spinner {
+  display: inline-flex;
+  animation: ds-widget-loading-spin 1s linear infinite;
+}
+
+@keyframes ds-widget-loading-spin {
+  from {
+    transform: rotate(0deg);
+  }
+
+  to {
+    transform: rotate(360deg);
+  }
+}

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

@@ -0,0 +1,241 @@
+import {
+  Controls,
+  Heading as DocHeading,
+  Primary as DocPrimary,
+  Markdown,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Widget } from 'Components/widget/Widget';
+import { fn } from 'storybook/test';
+import { WidgetCalendar } from './WidgetCalendar.js';
+
+const classEventTime = {
+  eventSecondaryTerm: 'Time and location',
+  eventDateTime: '2026-06-08T08:45/2026-06-08T09:00',
+  eventTimeLabel: '08:45 – 09:00',
+  eventLocation: 'Classroom 102',
+} as const;
+
+const initialItems: WidgetCalendar.ItemData[] = [
+  {
+    id: 'year-10-10g',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Class',
+    eventPrimaryDefinition: 'Year 10: 10G',
+    ...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',
+    ...classEventTime,
+  },
+  {
+    id: 'year-10-10g-2',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Class',
+    eventPrimaryDefinition: 'Year 10: 10G',
+    eventDateTime: '2026-06-08T09:00/2026-06-08T09:45',
+    eventTimeLabel: '09:00 – 09:45',
+    eventLocation: 'Classroom 204',
+    eventSecondaryTerm: 'Time and location',
+  },
+  {
+    id: 'class-generic-2',
+    eventType: 'secondary',
+    eventPrimaryTerm: 'Class',
+    eventPrimaryDefinition: 'Class',
+    eventDateTime: '2026-06-08T10:15/2026-06-08T11:00',
+    eventTimeLabel: '10:15 – 11:00',
+    eventLocation: 'Hall',
+    eventSecondaryTerm: 'Time and location',
+  },
+  {
+    id: 'maths-year-10-2',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Class',
+    eventPrimaryDefinition: 'Maths: Year 10: 10x/Ma3',
+    eventDateTime: '2026-06-08T11:15/2026-06-08T12:00',
+    eventTimeLabel: '11:15 – 12:00',
+    eventLocation: 'Classroom 102',
+    eventSecondaryTerm: 'Time and location',
+  },
+  {
+    id: 'year-10-10g-3',
+    eventType: 'primary',
+    eventPrimaryTerm: 'Class',
+    eventPrimaryDefinition: 'Year 10: 10G',
+    eventDateTime: '2026-06-08T13:00/2026-06-08T13:45',
+    eventTimeLabel: '13:00 – 13:45',
+    eventLocation: 'Classroom 102',
+    eventSecondaryTerm: 'Time and location',
+  },
+];
+
+const overflowItems: WidgetCalendar.ItemData[] = [
+  ...initialItems,
+  ...initialItems.map((item, index) => ({ ...item, id: `${item.id}-overflow-${index}` })),
+];
+
+const DESCRIPTION_INTRO = [
+  '`WidgetCalendar` is a pre-composed dashboard widget for upcoming calendar events.',
+  'It wraps [`Widget`](?path=/docs/components-widget--docs) with event rows, type indicators, and optional navigation.',
+  'Pass ISO `eventDateTime` and a formatted `eventTimeLabel` for each item — the component renders a semantic `<time>` element, matching the pattern used by `WidgetNotifications`.',
+].join(' ');
+
+function WidgetCalendarDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+    </>
+  );
+}
+
+const withDescription = (story: StoryObj, description: string): StoryObj => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: { story: description },
+    },
+  },
+});
+
+function FixedHeightWidgetContainer({
+  children,
+  height = 280,
+}: {
+  children: React.ReactNode;
+  height?: number;
+}) {
+  return (
+    <div
+      style={{
+        height,
+        display: 'flex',
+        flexDirection: 'column',
+        border: '1px dashed var(--color-grey-300)',
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+const DefaultTemplate = () => (
+  <WidgetCalendar
+    heading="Calendar"
+    headingHref="/calendar"
+    isFloating
+    items={initialItems}
+    onItemClick={fn()}
+  />
+);
+
+const EmptyTemplate = () => (
+  <WidgetCalendar heading="Calendar" isFloating items={[]} />
+);
+
+const FixedHeightOverflowTemplate = () => (
+  <FixedHeightWidgetContainer>
+    <WidgetCalendar
+      heading="Calendar"
+      isFloating
+      items={overflowItems}
+      onItemClick={fn()}
+    />
+  </FixedHeightWidgetContainer>
+);
+
+const meta = {
+  title: 'Components/Widget/WidgetCalendar',
+  component: WidgetCalendar,
+  parameters: {
+    layout: 'padded',
+    docs: { page: WidgetCalendarDocsPage },
+  },
+  tags: ['autodocs'],
+  args: {
+    heading: 'Calendar',
+    isFloating: true,
+    items: initialItems,
+    onItemClick: fn(),
+  },
+} satisfies Meta<typeof WidgetCalendar>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = withDescription(
+  {
+    render: DefaultTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Linked header with primary (green) and secondary (grey) event type indicators. Rows are keyboard-focusable when `onItemClick` is provided.',
+);
+
+export const Empty: Story = withDescription(
+  {
+    render: EmptyTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Empty items array shows the default EmptyState inside the Widget body.',
+);
+
+export const FixedHeightOverflow: Story = withDescription(
+  {
+    render: FixedHeightOverflowTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Parent container constrains height; the header stays pinned while the event list scrolls inside Widget.Body.',
+);
+
+export const Composable: Story = withDescription(
+  {
+    render: () => (
+      <Widget isFloating>
+        <Widget.Header>Calendar</Widget.Header>
+        <Widget.Body>
+          <ul className="ds-widget-calendar__list">
+            {initialItems.slice(0, 2).map(item => (
+              <WidgetCalendar.Item
+                key={item.id}
+                id={item.id}
+                eventType={item.eventType}
+                eventPrimaryTerm={item.eventPrimaryTerm}
+                eventPrimaryDefinition={item.eventPrimaryDefinition}
+                eventSecondaryTerm={item.eventSecondaryTerm}
+                eventDateTime={item.eventDateTime}
+                eventTimeLabel={item.eventTimeLabel}
+                eventLocation={item.eventLocation}
+                onItemClick={fn()}
+              />
+            ))}
+          </ul>
+        </Widget.Body>
+      </Widget>
+    ),
+    parameters: { controls: { disable: true } },
+  },
+  'Compose manually with `WidgetCalendar.Item` inside `Widget.Body` when you need custom list logic beyond the `items` prop.',
+);

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

@@ -0,0 +1,137 @@
+import '@testing-library/jest-dom/vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, test, vi } from 'vitest';
+import { WidgetCalendar } from './WidgetCalendar.js';
+
+const mockItems: 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',
+  },
+  {
+    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',
+  },
+];
+
+describe('WidgetCalendar', () => {
+  test('renders calendar items with primary and secondary definitions', () => {
+    render(
+      <WidgetCalendar heading="Calendar" items={mockItems} />,
+    );
+
+    expect(screen.getByRole('heading', { name: 'Calendar' })).toBeInTheDocument();
+    expect(screen.getByText('Year 10: 10G')).toBeInTheDocument();
+    expect(screen.getAllByText('Class').length).toBeGreaterThan(0);
+    expect(screen.getByText('08:45 – 09:00')).toBeInTheDocument();
+    expect(screen.getByText(/Classroom 102/)).toBeInTheDocument();
+  });
+
+  test('renders semantic time element with ISO dateTime', () => {
+    render(
+      <WidgetCalendar heading="Calendar" items={mockItems} />,
+    );
+
+    const time = screen.getByText('08:45 – 09:00').closest('time');
+
+    expect(time).toHaveAttribute('datetime', '2026-06-08T08:45/2026-06-08T09:00');
+    expect(time).toHaveClass('ds-widget-calendar__time');
+  });
+
+  test('applies primary and secondary modifier classes', () => {
+    const { container } = render(
+      <WidgetCalendar heading="Calendar" items={mockItems} />,
+    );
+
+    expect(container.querySelector('.ds-widget-calendar__item--primary')).toBeInTheDocument();
+    expect(container.querySelector('.ds-widget-calendar__item--secondary')).toBeInTheDocument();
+  });
+
+  test('calls onItemClick with item id', async () => {
+    const user = userEvent.setup();
+    const onItemClick = vi.fn();
+
+    render(
+      <WidgetCalendar
+        heading="Calendar"
+        items={mockItems}
+        onItemClick={onItemClick}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Open Year 10: 10G' }));
+
+    expect(onItemClick).toHaveBeenCalledWith('year-10');
+  });
+
+  test('uses custom buttonA11yText for item label', () => {
+    render(
+      <WidgetCalendar
+        heading="Calendar"
+        items={[
+          {
+            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',
+            buttonA11yText: 'View Year 10 timetable',
+          },
+        ]}
+        onItemClick={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'View Year 10 timetable' })).toBeInTheDocument();
+  });
+
+  test('activates item on Enter key', () => {
+    const onItemClick = vi.fn();
+
+    render(
+      <WidgetCalendar
+        heading="Calendar"
+        items={mockItems}
+        onItemClick={onItemClick}
+      />,
+    );
+
+    const item = screen.getByRole('button', { name: 'Open Year 10: 10G' });
+
+    fireEvent.keyDown(item, { key: 'Enter' });
+
+    expect(onItemClick).toHaveBeenCalledWith('year-10');
+  });
+
+  test('renders linked header when headingHref is set', () => {
+    render(
+      <WidgetCalendar heading="Calendar" headingHref="/calendar" items={mockItems} />,
+    );
+
+    expect(screen.getByRole('link', { name: 'Calendar' })).toHaveAttribute('href', '/calendar');
+  });
+
+  test('renders empty state when items is empty', () => {
+    render(
+      <WidgetCalendar heading="Calendar" items={[]} />,
+    );
+
+    expect(screen.getByRole('heading', { name: 'Nothing scheduled' })).toBeInTheDocument();
+  });
+});

package/src/components/widgetCalendar/WidgetCalendar.tsx

@@ -0,0 +1,105 @@
+import { EmptyState } from 'Components/emptyState/EmptyState';
+import { Icon } from 'Components/icon/Icon';
+import { Widget } from 'Components/widget/Widget';
+import type { WidgetCalendarEventType, WidgetCalendarItemProps } from './WidgetCalendarItem.js';
+import { WidgetCalendarItem } from './WidgetCalendarItem.js';
+
+type WidgetCalendarItemData = {
+  id: string;
+  eventType?: WidgetCalendarEventType;
+  eventPrimaryTerm: React.ReactNode;
+  eventPrimaryDefinition: React.ReactNode;
+  eventSecondaryTerm: React.ReactNode;
+  eventDateTime: string;
+  eventTimeLabel: string;
+  eventLocation?: string;
+  eventSecondaryDefinition?: React.ReactNode;
+  buttonA11yText?: string;
+};
+
+type WidgetCalendarProps = {
+  heading: React.ReactNode;
+  tooltip?: string;
+  headingHref?: string;
+  items: WidgetCalendarItemData[];
+  isFloating?: boolean;
+  onItemClick?: (id: string) => void;
+  emptyState?: React.ReactNode;
+  className?: string;
+};
+
+const defaultEmptyState = (
+  <EmptyState
+    padding="md"
+    illustration={<Icon name="date" size={24} />}
+    heading="Nothing scheduled"
+    subHeading="There are no upcoming events."
+  />
+);
+
+export const WidgetCalendar = (props: WidgetCalendarProps): React.JSX.Element => {
+  const {
+    heading,
+    tooltip,
+    headingHref,
+    items,
+    isFloating = false,
+    onItemClick,
+    emptyState = defaultEmptyState,
+    className,
+  } = props;
+
+  const isEmpty = items.length === 0;
+
+  const body = (
+    <>
+      <Widget.Header>{heading}</Widget.Header>
+      <Widget.Body>
+        {!isEmpty && (
+          <ul className="ds-widget-calendar__list">
+            {items.map(item => (
+              <WidgetCalendarItem
+                key={item.id}
+                id={item.id}
+                eventType={item.eventType}
+                eventPrimaryTerm={item.eventPrimaryTerm}
+                eventPrimaryDefinition={item.eventPrimaryDefinition}
+                eventSecondaryTerm={item.eventSecondaryTerm}
+                eventDateTime={item.eventDateTime}
+                eventTimeLabel={item.eventTimeLabel}
+                eventLocation={item.eventLocation}
+                eventSecondaryDefinition={item.eventSecondaryDefinition}
+                buttonA11yText={item.buttonA11yText}
+                onItemClick={onItemClick ? () => onItemClick(item.id) : undefined}
+              />
+            ))}
+          </ul>
+        )}
+      </Widget.Body>
+    </>
+  );
+
+  const widgetProps = {
+    tooltip,
+    isFloating,
+    isEmpty,
+    emptyState,
+    className,
+    ...(headingHref ? { href: headingHref } : {}),
+  } as Widget.Props;
+
+  return (
+    <Widget {...widgetProps}>
+      {body}
+    </Widget>
+  );
+};
+
+WidgetCalendar.Item = WidgetCalendarItem;
+
+export namespace WidgetCalendar {
+  export type Props = WidgetCalendarProps;
+  export type ItemProps = WidgetCalendarItemProps;
+  export type ItemData = WidgetCalendarItemData;
+  export type EventType = WidgetCalendarEventType;
+}