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

package/src/components/widgetCalendar/WidgetCalendarItem.tsx

@@ -0,0 +1,105 @@
+import classNames from 'classnames';
+import { Icon } from 'Components/icon/Icon';
+import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
+
+export type WidgetCalendarEventType = 'primary' | 'secondary';
+
+export type WidgetCalendarItemProps = {
+  id: string;
+  eventType?: WidgetCalendarEventType;
+  eventPrimaryTerm: React.ReactNode;
+  eventPrimaryDefinition: React.ReactNode;
+  eventSecondaryTerm: React.ReactNode;
+  eventDateTime: string;
+  eventTimeLabel: string;
+  eventLocation?: string;
+  eventSecondaryDefinition?: React.ReactNode;
+  buttonA11yText?: string;
+  onItemClick?: () => void;
+  className?: string;
+};
+
+export const WidgetCalendarItem = (props: WidgetCalendarItemProps): React.JSX.Element => {
+  const {
+    id,
+    eventType = 'primary',
+    eventPrimaryTerm,
+    eventPrimaryDefinition,
+    eventSecondaryTerm,
+    eventDateTime,
+    eventTimeLabel,
+    eventLocation,
+    eventSecondaryDefinition,
+    buttonA11yText,
+    onItemClick,
+    className,
+  } = props;
+
+  const isInteractive = Boolean(onItemClick);
+
+  const defaultA11yLabel = typeof eventPrimaryDefinition === 'string'
+    ? `Open ${eventPrimaryDefinition}`
+    : 'Open event';
+
+  const secondaryContent = eventSecondaryDefinition ?? (
+    <>
+      <time dateTime={eventDateTime} className="ds-widget-calendar__time">
+        {eventTimeLabel}
+      </time>
+      {eventLocation ? `, ${eventLocation}` : null}
+    </>
+  );
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLLIElement>) => {
+    if (!isInteractive) {
+      return;
+    }
+
+    if ([SPACE_KEY, ENTER_KEY].includes(event.key)) {
+      event.preventDefault();
+      onItemClick?.();
+    }
+  };
+
+  return (
+    <li
+      className={classNames(
+        'ds-widget-calendar__item',
+        eventType === 'secondary'
+          ? 'ds-widget-calendar__item--secondary'
+          : 'ds-widget-calendar__item--primary',
+        isInteractive && 'ds-widget-calendar__item--interactive',
+        className,
+      )}
+      data-testid={`widget-calendar-item-${id}`}
+      role={isInteractive ? 'button' : undefined}
+      tabIndex={isInteractive ? 0 : undefined}
+      aria-label={isInteractive ? (buttonA11yText ?? defaultA11yLabel) : undefined}
+      onClick={isInteractive ? onItemClick : undefined}
+      onKeyDown={handleKeyDown}
+    >
+      <div className="ds-widget-calendar__content">
+        <dl className="ds-widget-calendar__details">
+          <dt className="sr-only">{eventPrimaryTerm}</dt>
+          <dd className="ds-widget-calendar__primary-definition">{eventPrimaryDefinition}</dd>
+          <dt className="sr-only">{eventSecondaryTerm}</dt>
+          <dd className="ds-widget-calendar__secondary-definition">{secondaryContent}</dd>
+        </dl>
+      </div>
+      {isInteractive && (
+        <div className="ds-widget-calendar__action" aria-hidden="true">
+          <Icon
+            name="chevron-right"
+            size={16}
+            className="ds-widget-calendar__icon-chevron"
+          />
+          <Icon
+            name="arrow-right"
+            size={16}
+            className="ds-widget-calendar__icon-arrow"
+          />
+        </div>
+      )}
+    </li>
+  );
+};

package/src/components/widgetCalendar/widgetCalendar.scss

@@ -0,0 +1,124 @@
+.ds-widget-calendar__list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--widget-calendar-list-gap);
+}
+
+.ds-widget-calendar__icon-chevron {
+  display: inline-flex;
+}
+
+.ds-widget-calendar__icon-arrow {
+  display: none;
+}
+
+.ds-widget-calendar__item {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-small);
+  padding: var(--widget-calendar-spacing-vertical) var(--widget-calendar-spacing-horizontal);
+  border-bottom: var(--widget-calendar-weight-border) solid var(--widget-calendar-color-border);
+  background-color: var(--widget-calendar-default-color-background);
+  border-radius: var(--widget-calendar-radius);
+
+  &:last-child {
+    border-bottom: none;
+  }
+
+  &--interactive {
+    cursor: pointer;
+
+    &:hover {
+      background-color: var(--widget-calendar-hover-color-background);
+
+      .ds-widget-calendar__icon-chevron {
+        display: none;
+      }
+
+      .ds-widget-calendar__icon-arrow {
+        display: inline-flex;
+      }
+    }
+
+    &:focus-visible {
+      outline: var(--focus-border) solid var(--focus-color-focus);
+      background-color: var(--widget-calendar-focus-color-background);
+    }
+  }
+}
+
+.ds-widget-calendar__content {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  padding-left: calc(var(--widget-calendar-type-bar-width) + var(--spacing-small));
+
+  &::before {
+    content: '';
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    width: var(--widget-calendar-type-bar-width);
+    border-radius: var(--widget-calendar-type-bar-radius);
+  }
+}
+
+.ds-widget-calendar__item--primary .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-primary-color);
+}
+
+.ds-widget-calendar__item--secondary .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-secondary-color);
+}
+
+.ds-widget-calendar__details {
+  margin: 0;
+}
+
+.ds-widget-calendar__row {
+  margin: 0;
+}
+
+.ds-widget-calendar__primary-definition {
+  margin: 0;
+  font-family: var(--type-body-p-family);
+  font-size: var(--type-body-p-size);
+  font-weight: var(--type-body-bold-weight);
+  line-height: var(--type-body-line-height);
+  color: var(--widget-calendar-color-title);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ds-widget-calendar__secondary-definition {
+  margin: 0;
+  font-family: var(--type-body-p-family);
+  font-size: var(--type-body-p-size);
+  font-weight: var(--type-body-p-weight);
+  line-height: var(--type-body-line-height);
+  color: var(--widget-calendar-color-text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ds-widget-calendar__time {
+  font: inherit;
+  color: inherit;
+}
+
+.ds-widget-calendar__action {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  color: var(--widget-list-row-default-color-icon-arrow);
+}
+
+.ds-widget-calendar__item--interactive:hover .ds-widget-calendar__action {
+  color: var(--widget-list-row-hover-color-icon-arrow);
+}

package/src/components/widgetFavourites/WidgetFavourites.stories.tsx

@@ -0,0 +1,341 @@
+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 { Button } from 'Components/button/Button';
+import { Modal } from 'Components/modal/Modal';
+import { Toast } from 'Components/toast/Toast';
+import { useCallback, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { fn } from 'storybook/test';
+import { getFavouriteRemovedToastMessage } from 'Utils/favourites/favouriteConstants';
+import type { WidgetFavouritesItemData } from './types.js';
+import { WidgetFavourites } from './WidgetFavourites.js';
+
+const initialItems: WidgetFavouritesItemData[] = [
+  { id: 'daily', label: 'Daily Attendance', href: '/attendance/daily' },
+  { id: 'reports', label: 'Assessment Reports', href: '/reports/assessment' },
+  { id: 'behaviour', label: 'Behaviour Incidents', href: '/behaviour/incidents' },
+  { id: 'calendar', label: 'School Calendar', href: '/calendar' },
+];
+
+const DESCRIPTION_INTRO = [
+  '`WidgetFavourites` is a pre-composed dashboard widget for starred pages.',
+  'It wraps [`Widget`](?path=/docs/components-widget--docs) with a linked header and a list of favourite rows —',
+  'each row navigates via `href` and exposes a remove button when `onRemoveItem` is provided.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Dashboard home panels showing a user\'s starred sidebar pages',
+  '- A compact favourites summary with a linked header to the full favourites page',
+  '- Lists where removal should offer undo via [`Toast`](?path=/docs/components-toast--docs)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Editing favourites inside the sidebar itself | [`SidebarNav`](?path=/docs/components-sidebarnav--docs) panel items with `canFavourite` |',
+  '| A generic linked list without remove affordance | [`Widget`](?path=/docs/components-widget--docs) with custom body content |',
+  '| Destructive removal that must be confirmed first | Pair with [`Modal`](?path=/docs/components-modal--docs) before mutating state |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Remove buttons are opt-in.** Pass `onRemoveItem` to show the star remove control on each row.',
+  'The parent owns persistence, confirmation, and undo behaviour. Remove buttons use shared',
+  '`FAVOURITE_TOOLTIP.remove` for tooltip and `aria-label` by default.',
+  '',
+  '**Row link and remove are siblings.** The remove button is not nested inside the row anchor —',
+  'same pattern as sidebar favourites. Click handlers call `event.stopPropagation()`.',
+  '',
+  '**Empty list uses Widget empty state.** When `items` is empty, `WidgetFavourites` sets `isEmpty` on the',
+  'underlying `Widget` and renders the default or custom `emptyState`.',
+  '',
+  '**Undo removal.** Wire removal in the parent and pass a foreground toast with `toastActions` for the recommended product flow.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Each remove button has a tooltip and `aria-label` — defaults to **Remove from favourites**; override per row via `items[].removeLabel`',
+  '- Remove controls are always visible when `onRemoveItem` is provided',
+  '- Linked header follows the same stretched-link overlay pattern as `Widget`',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { WidgetFavourites } from '@arbor-education/design-system.components';",
+  '',
+  'function FavouritesWidget(props: WidgetFavourites.Props) {',
+  '  return <WidgetFavourites {...props} />;',
+  '}',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Widget](?path=/docs/components-widget--docs) · [EmptyState](?path=/docs/components-emptystate--docs) · [Toast](?path=/docs/components-toast--docs) · [Modal](?path=/docs/components-modal--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below demonstrates the recommended undo-toast removal flow. Use the named stories to explore confirmation and empty states.';
+
+function WidgetFavouritesDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <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 meta = {
+  title: 'Components/Widget/WidgetFavourites',
+  component: WidgetFavourites,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: WidgetFavouritesDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  args: {
+    heading: 'Favourites',
+    tooltip: 'Your starred pages appear here',
+    headingHref: '/favourites',
+    isFloating: true,
+    items: initialItems,
+    onRemoveItem: fn(),
+  },
+  argTypes: {
+    heading: {
+      control: 'text',
+      description: 'Widget header title — often includes a live count.',
+      table: { type: { summary: 'ReactNode' } },
+    },
+    tooltip: {
+      control: 'text',
+      description: 'Info tooltip beside the header title.',
+      table: { type: { summary: 'string' } },
+    },
+    headingHref: {
+      control: 'text',
+      description: 'Linked header URL for the full favourites page.',
+      table: { type: { summary: 'string' } },
+    },
+    isFloating: {
+      control: 'boolean',
+      description: 'Applies permanent elevation shadow on the underlying Widget.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    items: { control: false },
+    onRemoveItem: { control: false },
+    emptyState: { control: false },
+    className: { control: false },
+  },
+} satisfies Meta<typeof WidgetFavourites>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: { story: description },
+    },
+  },
+});
+
+const ToastStoryWrapper = ({ children }: { children: React.ReactNode }) => (
+  <Toast.Provider>
+    {children}
+    {createPortal(<Toast.Viewport />, document.body)}
+  </Toast.Provider>
+);
+
+const UndoableFavouritesTemplate = () => {
+  const [items, setItems] = useState(initialItems);
+  const [removedItem, setRemovedItem] = useState<WidgetFavouritesItemData | null>(null);
+  const [removedItemIndex, setRemovedItemIndex] = useState<number | null>(null);
+  const [toastOpen, setToastOpen] = useState(false);
+
+  const removeItem = useCallback((id: string) => {
+    setItems((current) => {
+      const index = current.findIndex(entry => entry.id === id);
+
+      if (index === -1) {
+        return current;
+      }
+
+      const item = current[index];
+
+      if (item === undefined) {
+        return current;
+      }
+
+      setRemovedItem(item);
+      setRemovedItemIndex(index);
+      setToastOpen(false);
+      requestAnimationFrame(() => setToastOpen(true));
+
+      return current.filter(entry => entry.id !== id);
+    });
+  }, []);
+
+  const undoRemove = useCallback(() => {
+    if (removedItem !== null && removedItemIndex !== null) {
+      setItems((current) => {
+        const next = [...current];
+        next.splice(removedItemIndex, 0, removedItem);
+        return next;
+      });
+      setRemovedItem(null);
+      setRemovedItemIndex(null);
+    }
+
+    setToastOpen(false);
+  }, [removedItem, removedItemIndex]);
+
+  return (
+    <ToastStoryWrapper>
+      <WidgetFavourites
+        heading={`Favourites (${items.length})`}
+        tooltip="Your starred pages appear here"
+        headingHref="/favourites"
+        isFloating
+        items={items}
+        onRemoveItem={removeItem}
+      />
+      <Toast
+        open={toastOpen}
+        onOpenChange={setToastOpen}
+        type="foreground"
+        duration={10000}
+        variant="information"
+        toastContent={removedItem ? getFavouriteRemovedToastMessage(removedItem.label) : ''}
+        toastActions={(
+          <Toast.Action altText="Undo removal" onClick={undoRemove} asChild>
+            <Button variant="text-link" type="button" hasHorizontalPadding={false}>Undo</Button>
+          </Toast.Action>
+        )}
+      />
+    </ToastStoryWrapper>
+  );
+};
+
+const WithConfirmRemoveTemplate = () => {
+  const [items, setItems] = useState(initialItems);
+  const [pendingRemoveId, setPendingRemoveId] = useState<string | null>(null);
+
+  const pendingItem = items.find(item => item.id === pendingRemoveId);
+
+  const handleConfirmRemove = () => {
+    if (pendingRemoveId) {
+      setItems(current => current.filter(item => item.id !== pendingRemoveId));
+      setPendingRemoveId(null);
+    }
+  };
+
+  return (
+    <>
+      <WidgetFavourites
+        heading={`Favourites (${items.length})`}
+        tooltip="Your starred pages appear here"
+        headingHref="/favourites"
+        isFloating
+        items={items}
+        onRemoveItem={setPendingRemoveId}
+      />
+      <Modal open={pendingRemoveId !== null} title={pendingItem ? `Remove ${pendingItem.label}?` : 'Remove favourite?'}>
+        <Modal.Body>
+          <p style={{ margin: 0 }}>
+            Are you sure you want to remove
+            {' '}
+            <strong>{pendingItem?.label}</strong>
+            {' '}
+            from your favourites?
+          </p>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setPendingRemoveId(null)}>
+            Cancel
+          </Button>
+          <Button variant="primary-destructive" onClick={handleConfirmRemove}>
+            Yes, remove
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+const EmptyTemplate = () => (
+  <WidgetFavourites
+    heading="Favourites (0)"
+    tooltip="Your starred pages appear here"
+    headingHref="/favourites"
+    isFloating
+    items={[]}
+  />
+);
+
+export const Default: Story = withDescription(
+  {
+    render: UndoableFavouritesTemplate,
+    parameters: {
+      controls: { disable: true },
+    },
+  },
+  'Recommended product flow: remove a favourite, then undo via a foreground toast. Each row shows the remove button when `onRemoveItem` is wired.',
+);
+
+export const WithConfirmRemove: Story = withDescription(
+  {
+    render: WithConfirmRemoveTemplate,
+    parameters: {
+      controls: { disable: true },
+    },
+  },
+  'Alternative flow when removal must be confirmed before mutating state. The remove button opens a destructive modal.',
+);
+
+export const Empty: Story = withDescription(
+  {
+    render: EmptyTemplate,
+    parameters: {
+      controls: { disable: true },
+    },
+  },
+  'Empty `items` array enables the built-in empty state inside the Widget body.',
+);

package/src/components/widgetFavourites/WidgetFavourites.test.tsx

@@ -0,0 +1,127 @@
+import '@testing-library/jest-dom/vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+import { describe, expect, test, vi } from 'vitest';
+import { WidgetFavourites } from './WidgetFavourites.js';
+
+const mockItems = [
+  { id: 'daily', label: 'Daily Attendance', href: '/attendance/daily' },
+  { id: 'reports', label: 'Assessment Reports', href: '/reports' },
+];
+
+describe('WidgetFavourites', () => {
+  test('renders list items with links', () => {
+    render(
+      <WidgetFavourites heading="Favourites" items={mockItems} />,
+    );
+
+    expect(screen.getByRole('heading', { name: 'Favourites' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Daily Attendance' })).toHaveAttribute('href', '/attendance/daily');
+    expect(screen.getByRole('link', { name: 'Assessment Reports' })).toHaveAttribute('href', '/reports');
+  });
+
+  test('remove button is sibling of link, not nested inside it', () => {
+    render(
+      <WidgetFavourites heading="Favourites" items={mockItems} onRemoveItem={vi.fn()} />,
+    );
+
+    const link = screen.getByRole('link', { name: 'Daily Attendance' });
+    const removeButton = screen.getByTestId('widget-favourites-remove-daily');
+
+    expect(link.contains(removeButton)).toBe(false);
+    expect(removeButton).toHaveClass('ds-favourite-button', 'ds-favourite-button--remove');
+    expect(link.closest('.ds-widget-favourites__item')).toContainElement(removeButton);
+  });
+
+  test('calls onRemoveItem with item id when remove is clicked', () => {
+    const onRemoveItem = vi.fn();
+
+    render(
+      <WidgetFavourites heading="Favourites" items={mockItems} onRemoveItem={onRemoveItem} />,
+    );
+
+    fireEvent.click(screen.getByTestId('widget-favourites-remove-daily'));
+
+    expect(onRemoveItem).toHaveBeenCalledWith('daily');
+  });
+
+  test('renders empty state when items is empty', () => {
+    render(
+      <WidgetFavourites heading="Favourites" items={[]} />,
+    );
+
+    expect(screen.getByRole('heading', { name: 'No favourites yet' })).toBeInTheDocument();
+    expect(screen.queryByRole('listitem')).not.toBeInTheDocument();
+  });
+
+  test('applies floating modifier when isFloating is true', () => {
+    const { container } = render(
+      <WidgetFavourites heading="Favourites" items={mockItems} isFloating />,
+    );
+
+    expect(container.querySelector('.ds-widget--floating')).toBeInTheDocument();
+  });
+
+  test('renders linked widget header when headingHref is provided', () => {
+    render(
+      <WidgetFavourites
+        heading="Favourites (2)"
+        headingHref="/favourites"
+        items={mockItems}
+      />,
+    );
+
+    expect(screen.getByRole('link', { name: 'Favourites (2)' })).toHaveAttribute('href', '/favourites');
+  });
+
+  test('uses default remove label on remove button', () => {
+    render(
+      <WidgetFavourites heading="Favourites" items={mockItems} onRemoveItem={vi.fn()} />,
+    );
+
+    expect(screen.getByTestId('widget-favourites-remove-daily')).toHaveAttribute(
+      'aria-label',
+      'Remove from favourites',
+    );
+  });
+
+  test('uses custom removeLabel on item', () => {
+    render(
+      <WidgetFavourites
+        heading="Favourites"
+        items={[{
+          id: 'daily',
+          label: 'Daily Attendance',
+          href: '/attendance/daily',
+          removeLabel: 'Unstar Daily Attendance',
+        }]}
+        onRemoveItem={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Unstar Daily Attendance' })).toBeInTheDocument();
+  });
+
+  test('WidgetFavourites.Item renders standalone list item', async () => {
+    const onRemove = vi.fn();
+    const user = userEvent.setup();
+
+    render(
+      <TooltipPrimitive.Provider delayDuration={400}>
+        <ul>
+          <WidgetFavourites.Item
+            id="daily"
+            label="Daily Attendance"
+            href="/attendance/daily"
+            onRemove={onRemove}
+          />
+        </ul>
+      </TooltipPrimitive.Provider>,
+    );
+
+    await user.click(screen.getByTestId('widget-favourites-remove-daily'));
+
+    expect(onRemove).toHaveBeenCalled();
+  });
+});