@arbor-education/design-system.components 4.0.0 → 4.2.0

package/src/components/widgetCalendar/WidgetCalendar.tsx

@@ -1,8 +1,10 @@
 import { EmptyState } from 'Components/emptyState/EmptyState';
 import { Icon } from 'Components/icon/Icon';
 import { Widget } from 'Components/widget/Widget';
+import type { WidgetHeadingLinkProps } from 'Components/widget/types';
 import type { WidgetCalendarEventType, WidgetCalendarItemProps } from './WidgetCalendarItem.js';
 import { WidgetCalendarItem } from './WidgetCalendarItem.js';
+import { Fragment } from 'react/jsx-runtime';
 
 type WidgetCalendarItemData = {
   id: string;
@@ -16,17 +18,18 @@ type WidgetCalendarItemData = {
   eventSecondaryDefinition?: React.ReactNode;
   buttonA11yText?: string;
   tooltip?: string;
+  group?: string;
 };
 
-type WidgetCalendarProps = {
+type WidgetCalendarProps = WidgetHeadingLinkProps & {
   heading: React.ReactNode;
   tooltip?: string;
-  headingHref?: string;
   items: WidgetCalendarItemData[];
   isFloating?: boolean;
   onItemClick?: (id: string) => void;
   emptyState?: React.ReactNode;
   className?: string;
+  groupItems?: boolean;
 };
 
 const defaultEmptyState = (
@@ -43,43 +46,42 @@ export const WidgetCalendar = (props: WidgetCalendarProps): React.JSX.Element =>
     heading,
     tooltip,
     headingHref,
+    renderLink,
+    linkProps,
     items,
     isFloating = false,
     onItemClick,
     emptyState = defaultEmptyState,
     className,
+    groupItems,
   } = 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}
-                tooltip={item.tooltip}
-              />
-            ))}
-          </ul>
-        )}
-      </Widget.Body>
-    </>
-  );
+  const groups = ['_ungrouped'];
+
+  const groupMap: Record<string, WidgetCalendarItemData[]> = {
+    _ungrouped: [],
+  };
+
+  if (groupItems) {
+    items.forEach((item) => {
+      if (item.group) {
+        if (!groups.includes(item.group)) {
+          groupMap[item.group] = [];
+          groups.push(item.group);
+        }
+
+        groupMap[item.group]?.push(item);
+      }
+      else {
+        groupMap._ungrouped!.push(item);
+      }
+    });
+  }
+  else {
+    groupMap._ungrouped = [...items];
+  }
 
   const widgetProps = {
     tooltip,
@@ -87,12 +89,54 @@ export const WidgetCalendar = (props: WidgetCalendarProps): React.JSX.Element =>
     isEmpty,
     emptyState,
     className,
-    ...(headingHref ? { href: headingHref } : {}),
+    ...(headingHref ? { href: headingHref, renderLink, linkProps } : {}),
   } as Widget.Props;
 
   return (
     <Widget {...widgetProps}>
-      {body}
+      <Widget.Header>{heading}</Widget.Header>
+      <Widget.Body>
+        {!isEmpty && (
+          groups.map((group) => {
+            const label = group;
+            const eventItems = groupMap[group]!;
+
+            return (
+              <Fragment key={`widgetCalendarGroup_${group}`}>
+                {label !== '_ungrouped' && (
+                  <span
+                    key={`groupLabel_${label}`}
+                    className="ds-widget-calendar__group-heading"
+                  >
+                    {label}
+                  </span>
+                )}
+                {eventItems.length > 0 && (
+                  <ul key={label} className="ds-widget-calendar__list">
+                    {eventItems.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}
+                        tooltip={item.tooltip}
+                      />
+                    ))}
+                  </ul>
+                )}
+              </Fragment>
+            );
+          })
+        )}
+      </Widget.Body>
     </Widget>
   );
 };

package/src/components/widgetCalendar/widgetCalendar.scss

@@ -122,3 +122,12 @@
 .ds-widget-calendar__item--interactive:hover .ds-widget-calendar__action {
   color: var(--widget-list-row-hover-color-icon-arrow);
 }
+
+.ds-widget-calendar__group-heading {
+  color: var(--widget-calendar-color-text);
+  font-family: var(--type-body-bold-family);
+  font-size: var(--type-body-bold-size);
+  font-style: normal;
+  font-weight: var(--type-body-bold-weight);
+  line-height: 150%;
+}

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

@@ -25,6 +25,12 @@ const initialItems: WidgetFavouritesItemData[] = [
   { id: 'calendar', label: 'School Calendar', href: '/calendar' },
 ];
 
+const longListItems: WidgetFavouritesItemData[] = Array.from({ length: 20 }, (_, index) => ({
+  id: `favourite-${index + 1}`,
+  label: `Favourite page ${index + 1}`,
+  href: `/favourites/${index + 1}`,
+}));
+
 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 —',
@@ -59,11 +65,22 @@ const DEVELOPER_NOTES = [
   '**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()`.',
   '',
+  '**Height is bounded by a token.** `WidgetFavourites` caps itself at `--widget-favourites-max-height` (375px),',
+  'so a long list scrolls inside the widget body instead of growing the page. Override the token on an ancestor',
+  'to change the cap; no parent height is required.',
+  '',
   '**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.',
   '',
+  '**`renderLink` and `linkProps` apply to the heading link only.** Both are forwarded to `Widget` only when',
+  '`headingHref` is set, and the types reject either prop without `headingHref`.',
+  '',
+  '**Items accept `linkProps` for row click handling.** `items[].linkProps` (or `linkProps` on',
+  '`WidgetFavourites.Item`) is spread onto the row `<a>`. `href` and `className` are applied after the spread',
+  'and cannot be overridden.',
+  '',
   '---',
   '',
   '### Accessibility',
@@ -300,6 +317,90 @@ const WithConfirmRemoveTemplate = () => {
   );
 };
 
+// Modifier-clicks (cmd/ctrl/shift/alt) open new tabs or windows, so leave them to the browser.
+const isModifiedClick = (event: React.MouseEvent<HTMLAnchorElement>) =>
+  event.metaKey || event.ctrlKey || event.shiftKey || event.altKey;
+
+const LastClicked = ({ label, placeholder }: { label: string | null; placeholder: string }) => (
+  <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+    {label
+      ? (
+          <>
+            Last clicked:
+            {' '}
+            {label}
+          </>
+        )
+      : placeholder}
+  </span>
+);
+
+const handleHeadingLinkClick = fn().mockName('linkProps.onClick');
+const handleItemLinkClick = fn().mockName('items[].linkProps.onClick');
+
+const WithHeadingLinkPropsTemplate = () => {
+  const [lastClickedHref, setLastClickedHref] = useState<string | null>(null);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <WidgetFavourites
+        heading={`Favourites (${initialItems.length})`}
+        tooltip="Your starred pages appear here"
+        headingHref="/favourites"
+        isFloating
+        items={initialItems}
+        linkProps={{
+          onClick: (event) => {
+            handleHeadingLinkClick(event);
+            if (isModifiedClick(event)) {
+              return;
+            }
+            event.preventDefault();
+            setLastClickedHref(event.currentTarget.getAttribute('href'));
+          },
+        }}
+      />
+      <LastClicked
+        label={lastClickedHref}
+        placeholder="Click the heading to see the handled navigation captured here."
+      />
+    </div>
+  );
+};
+
+const WithItemLinkPropsTemplate = () => {
+  const [lastClickedLabel, setLastClickedLabel] = useState<string | null>(null);
+
+  const items = initialItems.map((item): WidgetFavouritesItemData => ({
+    ...item,
+    linkProps: {
+      onClick: (event) => {
+        handleItemLinkClick(item.id, event);
+        if (isModifiedClick(event)) {
+          return;
+        }
+        event.preventDefault();
+        setLastClickedLabel(item.label);
+      },
+    },
+  }));
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <WidgetFavourites
+        heading={`Favourites (${items.length})`}
+        tooltip="Your starred pages appear here"
+        isFloating
+        items={items}
+      />
+      <LastClicked
+        label={lastClickedLabel}
+        placeholder="Click a favourite to see it captured here."
+      />
+    </div>
+  );
+};
+
 const EmptyTemplate = () => (
   <WidgetFavourites
     heading="Favourites (0)"
@@ -320,6 +421,112 @@ export const Default: Story = withDescription(
   'Recommended product flow: remove a favourite, then undo via a foreground toast. Each row shows the remove button when `onRemoveItem` is wired.',
 );
 
+export const WithHeadingLinkProps: Story = {
+  name: 'With heading linkProps',
+  ...withDescription(
+    {
+      render: WithHeadingLinkPropsTemplate,
+      parameters: {
+        controls: { disable: true },
+        docs: {
+          source: {
+            language: 'tsx',
+            code: `
+import { WidgetFavourites } from '@arbor-education/design-system.components';
+
+function FavouritesHeadingLinkPropsExample() {
+  return (
+    <WidgetFavourites
+      heading="Favourites"
+      headingHref="/favourites"
+      isFloating
+      items={items}
+      linkProps={{
+        onClick: (event) => {
+          // Leave modifier-clicks (new tab/window) to the browser.
+          if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+            return;
+          }
+          event.preventDefault();
+          navigate('/favourites');
+        },
+      }}
+    />
+  );
+}
+export default FavouritesHeadingLinkPropsExample;
+`.trim(),
+          },
+        },
+      },
+    },
+    [
+      '**Demonstrates the `linkProps` prop** (forwarded to `Widget` when `headingHref` is set). `linkProps` is',
+      'spread onto the heading `<a>`, so consumers can attach `onClick` for analytics or client-side navigation.',
+      'Each click is logged to the Actions panel as `linkProps.onClick`. A plain click calls `preventDefault()`',
+      'and shows the destination below the widget as "Last clicked: {href}"; modifier-clicks (cmd/ctrl/shift/alt)',
+      'are left to the browser. For a custom link element (e.g. a router link) use `renderLink` instead, as in',
+      'the `Widget` "With Render Link" story. For row clicks, see "With item linkProps".',
+    ].join(' '),
+  ),
+};
+
+export const WithItemLinkProps: Story = {
+  name: 'With item linkProps',
+  ...withDescription(
+    {
+      render: WithItemLinkPropsTemplate,
+      parameters: {
+        controls: { disable: true },
+        docs: {
+          source: {
+            language: 'tsx',
+            code: `
+import { useState } from 'react';
+import { WidgetFavourites } from '@arbor-education/design-system.components';
+import type { WidgetFavouritesItemData } from '@arbor-education/design-system.components';
+
+function FavouritesItemLinkPropsExample() {
+  const [lastClicked, setLastClicked] = useState<string | null>(null);
+
+  const items: WidgetFavouritesItemData[] = favourites.map(item => ({
+    ...item,
+    linkProps: {
+      onClick: (event) => {
+        // Leave modifier-clicks (new tab/window) to the browser.
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+          return;
+        }
+        event.preventDefault();
+        setLastClicked(item.label);
+        navigate(item.href);
+      },
+    },
+  }));
+
+  return (
+    <>
+      <WidgetFavourites heading="Favourites" isFloating items={items} />
+      <span>Last clicked: {lastClicked ?? 'none yet'}</span>
+    </>
+  );
+}
+export default FavouritesItemLinkPropsExample;
+`.trim(),
+          },
+        },
+      },
+    },
+    [
+      '**Demonstrates the `linkProps` field on `items`** (also accepted by `WidgetFavourites.Item`). Each item\'s',
+      '`linkProps` is spread onto its row `<a>`; `href` and `className` are applied after the spread and cannot',
+      'be overridden. Each click is logged to the Actions panel as `items[].linkProps.onClick` with the item id.',
+      'A plain click calls `preventDefault()` and shows the clicked favourite below the widget as',
+      '"Last clicked: {label}"; modifier-clicks (cmd/ctrl/shift/alt) are left to the browser.',
+    ].join(' '),
+  ),
+};
+
 export const WithConfirmRemove: Story = withDescription(
   {
     render: WithConfirmRemoveTemplate,
@@ -330,6 +537,16 @@ export const WithConfirmRemove: Story = withDescription(
   'Alternative flow when removal must be confirmed before mutating state. The remove button opens a destructive modal.',
 );
 
+export const LongList: Story = withDescription(
+  {
+    args: {
+      heading: `Favourites (${longListItems.length})`,
+      items: longListItems,
+    },
+  },
+  'A long list stays within `--widget-favourites-max-height` (375px). The header stays fixed and only the list scrolls.',
+);
+
 export const Empty: Story = withDescription(
   {
     render: EmptyTemplate,

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

@@ -63,6 +63,14 @@ describe('WidgetFavourites', () => {
     expect(container.querySelector('.ds-widget--floating')).toBeInTheDocument();
   });
 
+  test('applies the bounded root class alongside a consumer className', () => {
+    const { container } = render(
+      <WidgetFavourites heading="Favourites" items={mockItems} className="consumer-class" />,
+    );
+
+    expect(container.querySelector('.ds-widget')).toHaveClass('ds-widget-favourites', 'consumer-class');
+  });
+
   test('renders linked widget header when headingHref is provided', () => {
     render(
       <WidgetFavourites
@@ -75,6 +83,97 @@ describe('WidgetFavourites', () => {
     expect(screen.getByRole('link', { name: 'Favourites (2)' })).toHaveAttribute('href', '/favourites');
   });
 
+  test('forwards linkProps to the linked header', () => {
+    const onClick = vi.fn();
+
+    render(
+      <WidgetFavourites
+        heading="Favourites (2)"
+        headingHref="/favourites"
+        linkProps={{ onClick, target: '_blank' }}
+        items={mockItems}
+      />,
+    );
+
+    const link = screen.getByRole('link', { name: 'Favourites (2)' });
+    fireEvent.click(link);
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(link).toHaveAttribute('target', '_blank');
+  });
+
+  test('renders the linked header through renderLink', () => {
+    render(
+      <WidgetFavourites
+        heading="Favourites (2)"
+        headingHref="/favourites"
+        renderLink={({ href, className, children }) => (
+          <a href={href} className={className} data-router-link="true">
+            {children}
+          </a>
+        )}
+        items={mockItems}
+      />,
+    );
+
+    expect(screen.getByRole('link', { name: 'Favourites (2)' })).toHaveAttribute('data-router-link', 'true');
+  });
+
+  test('rejects heading link props without headingHref at the type level', () => {
+    render(
+      <>
+        {/* @ts-expect-error linkProps requires headingHref */}
+        <WidgetFavourites heading="Favourites" items={mockItems} linkProps={{ onClick: vi.fn() }} />
+        {/* @ts-expect-error renderLink requires headingHref */}
+        <WidgetFavourites heading="Favourites" items={mockItems} renderLink={() => <a />} />
+      </>,
+    );
+
+    expect(screen.queryByRole('link', { name: 'Favourites' })).not.toBeInTheDocument();
+  });
+
+  test('applies item linkProps to the row link', () => {
+    const onClick = vi.fn();
+
+    render(
+      <WidgetFavourites
+        heading="Favourites"
+        items={[{
+          id: 'daily',
+          label: 'Daily Attendance',
+          href: '/attendance/daily',
+          linkProps: { onClick, target: '_blank' },
+        }]}
+      />,
+    );
+
+    const link = screen.getByRole('link', { name: 'Daily Attendance' });
+    fireEvent.click(link);
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(link).toHaveAttribute('target', '_blank');
+    expect(link).toHaveAttribute('href', '/attendance/daily');
+  });
+
+  test('WidgetFavourites.Item applies linkProps to the row link', () => {
+    const onClick = vi.fn();
+
+    render(
+      <ul>
+        <WidgetFavourites.Item
+          id="daily"
+          label="Daily Attendance"
+          href="/attendance/daily"
+          linkProps={{ onClick }}
+        />
+      </ul>,
+    );
+
+    fireEvent.click(screen.getByRole('link', { name: 'Daily Attendance' }));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
   test('uses default remove label on remove button', () => {
     render(
       <WidgetFavourites heading="Favourites" items={mockItems} onRemoveItem={vi.fn()} />,

package/src/components/widgetFavourites/WidgetFavourites.tsx

@@ -1,3 +1,4 @@
+import classNames from 'classnames';
 import { EmptyState } from 'Components/emptyState/EmptyState';
 import { Widget } from 'Components/widget/Widget';
 import type { Widget as WidgetComponent } from 'Components/widget/Widget';
@@ -18,6 +19,8 @@ export const WidgetFavourites = (props: WidgetFavouritesProps): React.JSX.Elemen
     tooltip,
     items,
     headingHref,
+    renderLink,
+    linkProps,
     isFloating = false,
     onRemoveItem,
     emptyState = defaultEmptyState,
@@ -31,7 +34,7 @@ export const WidgetFavourites = (props: WidgetFavouritesProps): React.JSX.Elemen
     isFloating,
     isEmpty,
     emptyState,
-    className,
+    className: classNames('ds-widget-favourites', className),
   };
 
   const body = (
@@ -47,6 +50,7 @@ export const WidgetFavourites = (props: WidgetFavouritesProps): React.JSX.Elemen
                 label={item.label}
                 href={item.href}
                 removeLabel={item.removeLabel}
+                linkProps={item.linkProps}
                 onRemove={onRemoveItem ? () => onRemoveItem(item.id) : undefined}
               />
             ))}
@@ -60,7 +64,7 @@ export const WidgetFavourites = (props: WidgetFavouritesProps): React.JSX.Elemen
     <Widget
       {...({
         ...widgetCommonProps,
-        ...(headingHref ? { href: headingHref } : {}),
+        ...(headingHref ? { href: headingHref, renderLink, linkProps } : {}),
       } as WidgetComponent.Props)}
     >
       {body}

package/src/components/widgetFavourites/WidgetFavouritesItem.tsx

@@ -11,6 +11,7 @@ export const WidgetFavouritesItem = (props: WidgetFavouritesItemProps): React.JS
     label,
     href,
     removeLabel = FAVOURITE_TOOLTIP.remove,
+    linkProps,
     onRemove,
     className,
   } = props;
@@ -20,7 +21,7 @@ export const WidgetFavouritesItem = (props: WidgetFavouritesItemProps): React.JS
       className={classNames('ds-widget-favourites__item', className)}
       data-testid={`widget-favourites-item-${id}`}
     >
-      <a href={href} className={linkClassName}>
+      <a {...linkProps} href={href} className={linkClassName}>
         {label}
       </a>
       {onRemove && (

package/src/components/widgetFavourites/types.ts

@@ -1,15 +1,17 @@
+import type { WidgetHeadingLinkProps, WidgetLinkedProps } from 'Components/widget/types';
+
 export type WidgetFavouritesItemData = {
   id: string;
   label: string;
   href: string;
   removeLabel?: string;
+  linkProps?: WidgetLinkedProps['linkProps'];
 };
 
-export type WidgetFavouritesProps = {
+export type WidgetFavouritesProps = WidgetHeadingLinkProps & {
   heading: React.ReactNode;
   tooltip?: string;
   items: WidgetFavouritesItemData[];
-  headingHref?: string;
   isFloating?: boolean;
   onRemoveItem?: (id: string) => void;
   emptyState?: React.ReactNode;
@@ -21,6 +23,7 @@ export type WidgetFavouritesItemProps = {
   label: string;
   href: string;
   removeLabel?: string;
+  linkProps?: WidgetLinkedProps['linkProps'];
   onRemove?: () => void;
   className?: string;
 };

package/src/components/widgetFavourites/widgetFavourites.scss

@@ -1,3 +1,10 @@
+// Grid resolves its row against max-height, giving the content a definite height so only the body scrolls.
+.ds-widget.ds-widget-favourites {
+  display: grid;
+  grid-template-rows: minmax(0, 1fr);
+  max-height: var(--widget-favourites-max-height);
+}
+
 .ds-widget-favourites__list {
   list-style: none;
   margin: 0;

package/src/index.ts

@@ -28,6 +28,7 @@ export {
 } from 'Components/filterBar/FilterBar';
 export { Fieldset } from 'Components/formField/fieldset/Fieldset';
 export { FormField } from 'Components/formField/FormField';
+export type { CustomInputProps, CustomInputRenderProps, FormFieldSharedProps } from 'Components/formField/FormField';
 export { CheckboxGroup } from 'Components/formField/inputs/checkbox/CheckboxGroup';
 export { CheckboxInput } from 'Components/formField/inputs/checkbox/CheckboxInput';
 export { ColourPickerDropdown } from 'Components/formField/inputs/colourPickerDropdown/ColourPickerDropdown';

package/src/tokens.scss

@@ -882,6 +882,7 @@
   --widget-favourites-weight-border: var(--border-weight);
   --widget-favourites-spacing-vertical: var(--spacing-small);
   --widget-favourites-spacing-horizontal: var(--spacing-small);
+  --widget-favourites-max-height: 375px;
   --widget-attachments-hover-color-icon: var(--color-grey-900);
   --widget-attachments-hover-color-text: var(--color-grey-900);
   --widget-attachments-hover-color-background: var(--color-grey-100);

package/tokens/json/Arbor.json

@@ -3973,6 +3973,10 @@
         "spacing-horizontal": {
           "$type": "dimension",
           "$value": "{spacing.small}"
+        },
+        "max-height": {
+          "$type": "dimension",
+          "$value": "375px"
         }
       },
       "attachments": {