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

package/src/components/widgetFavourites/WidgetFavourites.tsx

@@ -0,0 +1,83 @@
+import { EmptyState } from 'Components/emptyState/EmptyState';
+import { Widget } from 'Components/widget/Widget';
+import type { Widget as WidgetComponent } from 'Components/widget/Widget';
+import type { WidgetFavouritesItemProps, WidgetFavouritesProps } from './types.js';
+import { WidgetFavouritesItem } from './WidgetFavouritesItem.js';
+
+const defaultEmptyState = (
+  <EmptyState
+    padding="md"
+    heading="No favourites yet"
+    subHeading="Star pages from the sidebar to see them here."
+  />
+);
+
+export const WidgetFavourites = (props: WidgetFavouritesProps): React.JSX.Element => {
+  const {
+    heading,
+    tooltip,
+    items,
+    headingHref,
+    isFloating = false,
+    onRemoveItem,
+    emptyState = defaultEmptyState,
+    className,
+  } = props;
+
+  const isEmpty = items.length === 0;
+
+  const widgetCommonProps = {
+    tooltip,
+    isFloating,
+    isEmpty,
+    emptyState,
+    className,
+  };
+
+  const body = (
+    <>
+      <Widget.Header>{heading}</Widget.Header>
+      <Widget.Body>
+        {!isEmpty && (
+          <ul className="ds-widget-favourites__list">
+            {items.map(item => (
+              <WidgetFavouritesItem
+                key={item.id}
+                id={item.id}
+                label={item.label}
+                href={item.href}
+                removeLabel={item.removeLabel}
+                onRemove={onRemoveItem ? () => onRemoveItem(item.id) : undefined}
+              />
+            ))}
+          </ul>
+        )}
+      </Widget.Body>
+    </>
+  );
+
+  return (
+    <Widget
+      {...({
+        ...widgetCommonProps,
+        ...(headingHref ? { href: headingHref } : {}),
+      } as WidgetComponent.Props)}
+    >
+      {body}
+    </Widget>
+  );
+};
+
+WidgetFavourites.Item = WidgetFavouritesItem;
+
+export namespace WidgetFavourites {
+  export type Props = WidgetFavouritesProps;
+  export type ItemProps = WidgetFavouritesItemProps;
+  export type ItemData = import('./types.js').WidgetFavouritesItemData;
+}
+
+export type {
+  WidgetFavouritesItemData,
+  WidgetFavouritesItemProps,
+  WidgetFavouritesProps,
+} from './types.js';

package/src/components/widgetFavourites/WidgetFavouritesItem.tsx

@@ -0,0 +1,37 @@
+import classNames from 'classnames';
+import { FavouriteButton } from 'Components/favourite/FavouriteButton';
+import { FAVOURITE_TOOLTIP } from 'Utils/favourites/favouriteConstants';
+import type { WidgetFavouritesItemProps } from './types.js';
+
+const linkClassName = 'ds-widget-favourites__link';
+
+export const WidgetFavouritesItem = (props: WidgetFavouritesItemProps): React.JSX.Element => {
+  const {
+    id,
+    label,
+    href,
+    removeLabel = FAVOURITE_TOOLTIP.remove,
+    onRemove,
+    className,
+  } = props;
+
+  return (
+    <li
+      className={classNames('ds-widget-favourites__item', className)}
+      data-testid={`widget-favourites-item-${id}`}
+    >
+      <a href={href} className={linkClassName}>
+        {label}
+      </a>
+      {onRemove && (
+        <FavouriteButton
+          variant="remove"
+          label={removeLabel}
+          className="remove-default-button-styles"
+          data-testid={`widget-favourites-remove-${id}`}
+          onClick={onRemove}
+        />
+      )}
+    </li>
+  );
+};

package/src/components/widgetFavourites/types.ts

@@ -0,0 +1,26 @@
+export type WidgetFavouritesItemData = {
+  id: string;
+  label: string;
+  href: string;
+  removeLabel?: string;
+};
+
+export type WidgetFavouritesProps = {
+  heading: React.ReactNode;
+  tooltip?: string;
+  items: WidgetFavouritesItemData[];
+  headingHref?: string;
+  isFloating?: boolean;
+  onRemoveItem?: (id: string) => void;
+  emptyState?: React.ReactNode;
+  className?: string;
+};
+
+export type WidgetFavouritesItemProps = {
+  id: string;
+  label: string;
+  href: string;
+  removeLabel?: string;
+  onRemove?: () => void;
+  className?: string;
+};

package/src/components/widgetFavourites/widgetFavourites.scss

@@ -0,0 +1,84 @@
+.ds-widget-favourites__list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.ds-widget-favourites__item {
+  position: relative;
+  display: flex;
+  align-items: center;
+  border-radius: var(--widget-favourites-radius);
+  background: var(--widget-favourites-default-color-background);
+
+  .ds-favourite-button--remove {
+    color: var(--widget-favourites-icon-default-color-icon);
+    opacity: 0;
+    transition: opacity 0.16s ease, color 0.16s ease, background 0.16s ease;
+
+    &:hover,
+    &[data-state='delayed-open'],
+    &[data-state='instant-open'],
+    &[data-state='open'] {
+      color: var(--widget-favourites-icon-hover-color-icon);
+    }
+
+    &:active {
+      color: var(--widget-favourites-icon-active-color-icon);
+    }
+
+    &:focus-visible,
+    &[data-state='delayed-open'],
+    &[data-state='instant-open'],
+    &[data-state='open'] {
+      opacity: 1;
+    }
+  }
+
+  &:hover,
+  &:focus-within,
+  &:has(.ds-favourite-button--remove[data-state='delayed-open']),
+  &:has(.ds-favourite-button--remove[data-state='instant-open']),
+  &:has(.ds-favourite-button--remove[data-state='open']) {
+    background: var(--widget-favourites-hover-color-background);
+
+    .ds-favourite-button--remove {
+      opacity: 1;
+    }
+  }
+
+  &:has(.ds-widget-favourites__link:focus-visible),
+  &:has(.ds-favourite-button--remove:focus-visible) {
+    background: var(--widget-favourites-focus-color-background);
+  }
+}
+
+.ds-widget-favourites__link {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  padding: var(--widget-favourites-spacing-vertical) var(--widget-favourites-spacing-horizontal);
+  padding-right: calc(var(--size-control-xsmall) + var(--spacing-small));
+  border-radius: var(--widget-favourites-radius);
+  color: var(--widget-favourites-color-text);
+  text-decoration: none;
+  font-size: var(--type-body-p-size);
+  line-height: var(--line-height-default);
+
+  &:hover {
+    color: var(--widget-favourites-color-text);
+  }
+
+  &:focus {
+    outline: none;
+  }
+
+  &:focus-visible {
+    outline: var(--focus-border) solid var(--focus-color-focus);
+    outline-offset: calc(-1 * var(--focus-border));
+  }
+}

package/src/components/widgetNotifications/WidgetNotifications.stories.tsx

@@ -0,0 +1,417 @@
+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 { EmptyState } from 'Components/emptyState/EmptyState';
+import { Icon } from 'Components/icon/Icon';
+import { useState } from 'react';
+import { fn } from 'storybook/test';
+import { Widget } from 'Components/widget/Widget';
+import { WidgetNotifications } from './WidgetNotifications.js';
+
+const initialItems: WidgetNotifications.ItemData[] = [
+  {
+    id: 'email-complete',
+    title: 'Sending email message is complete',
+    description: 'Click here to see the message and check delivery status.',
+    dateTime: '2026-06-08T10:54:00Z',
+    timeLabel: '6 minutes ago',
+    isRead: false,
+  },
+  {
+    id: 'sms-failed',
+    title: 'SMS failed to be sent',
+    description: 'The SMS to Tim Jones failed to be sent',
+    dateTime: '2026-06-08T09:30:00Z',
+    timeLabel: '1 hour ago',
+    isRead: false,
+  },
+  {
+    id: 'report-ready',
+    title: 'Assessment report generated',
+    description: 'Your requested report is ready to download.',
+    dateTime: '2026-06-07T09:00:00Z',
+    timeLabel: '1 day ago',
+    isRead: true,
+  },
+];
+
+const DESCRIPTION_INTRO = [
+  '`WidgetNotifications` is a pre-composed dashboard widget for in-app notifications.',
+  'It wraps [`Widget`](?path=/docs/components-widget--docs) with a header action, a list of notification rows,',
+  'and a built-in empty state when there are no items.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Dashboard home panels summarising recent notifications',
+  '- Notification feeds where users can mark all as read, open a detail view, or clear individual items',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Real-time toast feedback for a single action | [`Toast`](?path=/docs/components-toast--docs) |',
+  '| A generic list without notification-specific chrome | [`Widget`](?path=/docs/components-widget--docs) with custom body |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Handlers are opt-in.** Pass `onItemClick`, `onClearItem`, and `onMarkAllAsRead` to wire product behaviour.',
+  'The parent owns persistence and navigation.',
+  '',
+  '**Time labels are presentational.** Pass ISO `dateTime` for the `<time>` element and a pre-formatted `timeLabel`',
+  '(e.g. "6 minutes ago") from your application layer.',
+  '',
+  '**Read state is parent-owned.** Set `isRead` on each item in `items` data. Use `onItemClick` to navigate',
+  'and update `isRead` in your state (e.g. mark as read when the user opens a notification).',
+  '',
+  '**Mark all as read** hides automatically when the list is empty or every item is read.',
+  '',
+  '**Empty list** uses Widget `isEmpty` with the default or custom `emptyState` ReactNode.',
+  '',
+  '**Body overflow.** When the widget sits in a height-constrained dashboard cell, the notification list',
+  'scrolls inside `Widget.Body` while the header (and mark-all-as-read action) stays pinned.',
+  'Give the parent an explicit height — the widget fills `height: 100%` automatically.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Widget](?path=/docs/components-widget--docs) · [EmptyState](?path=/docs/components-emptystate--docs)',
+].join('\n');
+
+function WidgetNotificationsDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+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 overflowItems: WidgetNotifications.ItemData[] = [
+  ...initialItems,
+  {
+    id: 'attendance-alert',
+    title: 'Attendance threshold reached',
+    description: 'Year 9 attendance has dropped below 90% this week.',
+    dateTime: '2026-06-06T14:00:00Z',
+    timeLabel: '2 days ago',
+    isRead: false,
+  },
+  {
+    id: 'parent-message',
+    title: 'New parent message',
+    description: 'Sarah Chen sent a message about the school trip.',
+    dateTime: '2026-06-06T09:15:00Z',
+    timeLabel: '2 days ago',
+    isRead: true,
+  },
+  {
+    id: 'timetable-change',
+    title: 'Timetable change published',
+    description: 'Room 12 has been reassigned for Period 4 on Thursday.',
+    dateTime: '2026-06-05T16:30:00Z',
+    timeLabel: '3 days ago',
+    isRead: false,
+  },
+  {
+    id: 'exam-results',
+    title: 'Exam results uploaded',
+    description: 'GCSE mock results are ready for review.',
+    dateTime: '2026-06-05T11:00:00Z',
+    timeLabel: '3 days ago',
+    isRead: true,
+  },
+  {
+    id: 'staff-absence',
+    title: 'Staff absence notification',
+    description: 'Mr Patel is absent today — cover assigned.',
+    dateTime: '2026-06-04T08:00:00Z',
+    timeLabel: '4 days ago',
+    isRead: false,
+  },
+  {
+    id: 'behaviour-incident',
+    title: 'Behaviour incident logged',
+    description: 'A minor incident was recorded during lunch break.',
+    dateTime: '2026-06-03T13:45:00Z',
+    timeLabel: '5 days ago',
+    isRead: true,
+  },
+  {
+    id: 'data-export',
+    title: 'Data export complete',
+    description: 'Your requested pupil export is ready to download.',
+    dateTime: '2026-06-02T17:20:00Z',
+    timeLabel: '6 days ago',
+    isRead: false,
+  },
+  {
+    id: 'calendar-reminder',
+    title: 'Calendar reminder',
+    description: 'Parents evening begins in 5 days.',
+    dateTime: '2026-06-01T10:00:00Z',
+    timeLabel: '1 week ago',
+    isRead: true,
+  },
+  {
+    id: 'system-update',
+    title: 'System update scheduled',
+    description: 'Maintenance window this Saturday 02:00–04:00.',
+    dateTime: '2026-05-30T09:00:00Z',
+    timeLabel: '1 week ago',
+    isRead: false,
+  },
+];
+
+const DefaultTemplate = () => {
+  const [items, setItems] = useState(initialItems);
+
+  return (
+    <WidgetNotifications
+      heading="Notifications"
+      isFloating
+      items={items}
+      onItemClick={(id) => {
+        window.alert(`Opened notification: ${id}`);
+        setItems(current =>
+          current.map(item => item.id === id ? { ...item, isRead: true } : item),
+        );
+      }}
+      onClearItem={(id) => {
+        setItems(current => current.filter(item => item.id !== id));
+      }}
+      onMarkAllAsRead={() => {
+        setItems(current => current.map(item => ({ ...item, isRead: true })));
+      }}
+    />
+  );
+};
+
+const AllReadTemplate = () => (
+  <WidgetNotifications
+    heading="Notifications"
+    isFloating
+    items={initialItems.map(item => ({ ...item, isRead: true }))}
+    onClearItem={fn()}
+  />
+);
+
+const EmptyTemplate = () => (
+  <WidgetNotifications heading="Notifications" isFloating items={[]} />
+);
+
+const CustomEmptyStateTemplate = () => (
+  <WidgetNotifications
+    heading="Notifications"
+    isFloating
+    items={[]}
+    emptyState={(
+      <EmptyState
+        padding="md"
+        illustration={<Icon name="mail" size={24} />}
+        heading="Inbox zero"
+        subHeading="No new notifications right now."
+      />
+    )}
+  />
+);
+
+const FixedHeightOverflowTemplate = () => {
+  const [items, setItems] = useState(overflowItems);
+
+  return (
+    <FixedHeightWidgetContainer>
+      <WidgetNotifications
+        heading="Notifications"
+        isFloating
+        items={items}
+        onItemClick={(id) => {
+          window.alert(`Opened notification: ${id}`);
+          setItems(current =>
+            current.map(item => item.id === id ? { ...item, isRead: true } : item),
+          );
+        }}
+        onClearItem={(id) => {
+          setItems(current => current.filter(item => item.id !== id));
+        }}
+        onMarkAllAsRead={() => {
+          setItems(current => current.map(item => ({ ...item, isRead: true })));
+        }}
+      />
+    </FixedHeightWidgetContainer>
+  );
+};
+
+const meta = {
+  title: 'Components/Widget/WidgetNotifications',
+  component: WidgetNotifications,
+  parameters: {
+    layout: 'padded',
+    docs: { page: WidgetNotificationsDocsPage },
+  },
+  tags: ['autodocs'],
+  args: {
+    heading: 'Notifications',
+    isFloating: true,
+    items: initialItems,
+    onItemClick: fn(),
+    onClearItem: fn(),
+    onMarkAllAsRead: fn(),
+  },
+} satisfies Meta<typeof WidgetNotifications>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = withDescription(
+  {
+    render: DefaultTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Click a notification to open it (alert demo) and mark it read — unread rows use brand-tinted styling until `isRead` is true.',
+);
+
+export const AllRead: Story = withDescription(
+  {
+    render: AllReadTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'All items marked read — unread background styling is not applied.',
+);
+
+export const Empty: Story = withDescription(
+  {
+    render: EmptyTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Empty items array shows the default EmptyState inside the Widget body.',
+);
+
+export const CustomEmptyState: Story = withDescription(
+  {
+    render: CustomEmptyStateTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Pass a custom `emptyState` ReactNode to override the default empty presentation.',
+);
+
+export const Composable: Story = withDescription(
+  {
+    render: () => (
+      <Widget isFloating>
+        <Widget.Header>Notifications</Widget.Header>
+        <Widget.Body>
+          <ol className="ds-widget-notifications__list">
+            {initialItems.map(item => (
+              <WidgetNotifications.Item
+                key={item.id}
+                id={item.id}
+                title={item.title}
+                description={item.description}
+                dateTime={item.dateTime}
+                timeLabel={item.timeLabel}
+                isRead={item.isRead}
+              />
+            ))}
+          </ol>
+        </Widget.Body>
+      </Widget>
+    ),
+    parameters: { controls: { disable: true } },
+  },
+  'Compose manually with `WidgetNotifications.Item` inside `Widget.Body` when you need custom list logic beyond the `items` prop.',
+);
+
+export const FixedHeightOverflow: Story = withDescription(
+  {
+    render: FixedHeightOverflowTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { WidgetNotifications } from '@arbor-education/design-system.components';
+
+function WidgetNotificationsFixedHeightOverflowExample() {
+  return (
+    <div style={{ height: 280, display: 'flex', flexDirection: 'column' }}>
+      <WidgetNotifications
+        heading="Notifications"
+        isFloating
+        items={items}
+        onItemClick={handleItemClick}
+        onClearItem={handleClearItem}
+        onMarkAllAsRead={handleMarkAllAsRead}
+      />
+    </div>
+  );
+}
+export default WidgetNotificationsFixedHeightOverflowExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Parent container constrains height; the header stays pinned while the notification list scrolls inside Widget.Body.',
+);