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

package/src/components/widget/Widget.test.tsx

@@ -0,0 +1,263 @@
+import '@testing-library/jest-dom/vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { EmptyState } from 'Components/emptyState/EmptyState';
+import { Icon } from 'Components/icon/Icon';
+import { describe, expect, test, vi } from 'vitest';
+import { Widget } from './Widget.js';
+
+describe('Widget', () => {
+  test('throws when used outside Widget context', () => {
+    expect(() => render(<Widget.Header>Title</Widget.Header>)).toThrow(
+      'Widget compound components must be used within <Widget>.',
+    );
+  });
+
+  test('renders static header without link or chevron', () => {
+    const { container } = render(
+      <Widget>
+        <Widget.Header>Alerts (0)</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(screen.getByRole('heading', { level: 3, name: 'Alerts (0)' })).toBeInTheDocument();
+    expect(container.querySelector('a')).not.toBeInTheDocument();
+    expect(container.querySelector('.ds-widget__header-chevron')).not.toBeInTheDocument();
+  });
+
+  test('renders slotEnd in header end region', () => {
+    render(
+      <Widget>
+        <Widget.Header slotEnd={<button type="button">Mark all as read</button>}>
+          Notifications
+        </Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(screen.getByRole('button', { name: 'Mark all as read' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Mark all as read' }).closest('.ds-widget__header-end')).toBeInTheDocument();
+  });
+
+  test('renders linked header with anchor and chevron', () => {
+    const { container } = render(
+      <Widget href="/alerts">
+        <Widget.Header>Alerts (2)</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    const link = screen.getByRole('link', { name: 'Alerts (2)' });
+    const header = container.querySelector('.ds-widget__header');
+
+    expect(link).toHaveAttribute('href', '/alerts');
+    expect(header).toHaveClass('ds-widget__header--linked');
+    expect(container.querySelector('.ds-widget__header-chevron')).toBeInTheDocument();
+    expect(link.querySelector('.ds-widget__header-chevron')).not.toBeInTheDocument();
+    expect(container.querySelector('.ds-widget__header-end .ds-widget__header-chevron')).toBeInTheDocument();
+  });
+
+  test('uses renderLink when provided', () => {
+    const renderLink = vi.fn(({ href, className, children }) => (
+      <a href={href} className={className} data-testid="custom-link">{children}</a>
+    ));
+
+    render(
+      <Widget href="/alerts" renderLink={renderLink}>
+        <Widget.Header>Alerts (2)</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(renderLink).toHaveBeenCalledWith(
+      expect.objectContaining({
+        href: '/alerts',
+        className: 'ds-widget__header-link',
+      }),
+    );
+    expect(screen.getByTestId('custom-link')).toBeInTheDocument();
+  });
+
+  test('renders tooltip trigger as sibling of heading in heading row', () => {
+    const { container } = render(
+      <Widget tooltip="Your starred items appear here">
+        <Widget.Header>Favourites</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    const headingRow = container.querySelector('.ds-widget__header-heading-row');
+
+    expect(headingRow).toBeInTheDocument();
+    expect(headingRow?.querySelector('.ds-widget__header-heading')).toBeInTheDocument();
+    expect(headingRow?.querySelector('.ds-widget__header-tooltip-trigger')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'Favourites' }).closest('button')).not.toBeInTheDocument();
+  });
+
+  test('collapsible header toggles body visibility', () => {
+    render(
+      <Widget collapsible defaultExpanded={false}>
+        <Widget.Header>Attendance</Widget.Header>
+        <Widget.Body><p>Body content</p></Widget.Body>
+      </Widget>,
+    );
+
+    expect(screen.queryByText('Body content')).not.toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 3, name: 'Attendance' })).toBeInTheDocument();
+
+    const toggle = screen.getByRole('button', { name: 'Attendance' });
+
+    expect(toggle.querySelector('h3')).toBeNull();
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+
+    fireEvent.click(toggle);
+
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+    expect(screen.getByText('Body content')).toBeInTheDocument();
+  });
+
+  test('collapsible chevron rotates when expanded', () => {
+    const { container } = render(
+      <Widget collapsible defaultExpanded>
+        <Widget.Header>Attendance</Widget.Header>
+        <Widget.Body><p>Body content</p></Widget.Body>
+      </Widget>,
+    );
+
+    expect(container.querySelector('.ds-widget__header-toggle[aria-expanded="true"] .ds-widget__header-chevron')).toBeInTheDocument();
+  });
+
+  test('throws in dev when href and collapsible are both set', () => {
+    expect(() => render(
+      <Widget
+        {...({
+          href: '/alerts',
+          collapsible: true,
+        } as unknown as Widget.Props)}
+      >
+        <Widget.Header>Alerts</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    )).toThrow('Widget cannot have both href and collapsible. Use one or the other.');
+  });
+
+  test('renders empty state with h4 heading nested under h3 widget header', () => {
+    render(
+      <Widget
+        isEmpty
+        emptyState={(
+          <EmptyState
+            heading="All clear!"
+            subHeading="There are no alerts for you right now."
+          />
+        )}
+      >
+        <Widget.Header>Alerts (0)</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(screen.getByRole('heading', { level: 3, name: 'Alerts (0)' })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 4, name: 'All clear!' })).toBeInTheDocument();
+  });
+
+  test('renders empty state when isEmpty is true', () => {
+    render(
+      <Widget
+        isEmpty
+        emptyState={(
+          <EmptyState
+            heading="All clear!"
+            subHeading="There are no alerts for you right now."
+          />
+        )}
+      >
+        <Widget.Header>Alerts (0)</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(screen.getByRole('heading', { name: 'All clear!' })).toBeInTheDocument();
+  });
+
+  test('sets aria-busy on body when isLoading is true', () => {
+    render(
+      <Widget isLoading loadingLabel="Loading alerts">
+        <Widget.Header>Alerts</Widget.Header>
+        <Widget.Body><p>Body content</p></Widget.Body>
+      </Widget>,
+    );
+
+    expect(screen.getByRole('status', { name: 'Loading alerts' })).toBeInTheDocument();
+    expect(screen.queryByText('Body content')).not.toBeInTheDocument();
+    expect(document.querySelector('.ds-widget__body')).toHaveAttribute('aria-busy', 'true');
+  });
+
+  test('sets aria-live on body when live is true', () => {
+    const { container } = render(
+      <Widget live isEmpty emptyState={<EmptyState heading="Empty" />}>
+        <Widget.Header>Alerts</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(container.querySelector('.ds-widget__body[aria-live="polite"]')).toBeInTheDocument();
+  });
+
+  test('linked header keeps tooltip outside link wrapper', () => {
+    render(
+      <Widget href="/alerts" tooltip="About alerts">
+        <Widget.Header>Alerts (2)</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    const link = screen.getByRole('link', { name: 'Alerts (2)' });
+    const tooltipButton = screen.getByRole('button', { name: 'About alerts' });
+
+    expect(link.contains(tooltipButton)).toBe(false);
+  });
+
+  test('applies floating modifier when isFloating is true', () => {
+    const { container } = render(
+      <Widget isFloating>
+        <Widget.Header>Favourites</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(container.querySelector('.ds-widget.ds-widget--floating')).toBeInTheDocument();
+  });
+
+  test('does not apply floating modifier by default', () => {
+    const { container } = render(
+      <Widget>
+        <Widget.Header>Favourites</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(container.querySelector('.ds-widget--floating')).not.toBeInTheDocument();
+  });
+
+  test('renders empty state with illustration inside widget', () => {
+    render(
+      <Widget
+        isEmpty
+        emptyState={(
+          <EmptyState
+            illustration={<Icon name="circle-help" size={24} />}
+            heading="All clear!"
+            subHeading="There are no alerts for you right now."
+          />
+        )}
+      >
+        <Widget.Header>Alerts (0)</Widget.Header>
+        <Widget.Body />
+      </Widget>,
+    );
+
+    expect(screen.getByRole('region')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'All clear!' })).toBeInTheDocument();
+  });
+});

package/src/components/widget/Widget.tsx

@@ -0,0 +1,102 @@
+import classNames from 'classnames';
+import { Card } from 'Components/card/Card';
+import { useId } from 'react';
+import { useControllableBoolean } from 'Utils/hooks/useControllableBoolean';
+import type {
+  WidgetCollapsibleProps,
+  WidgetLinkedProps,
+  WidgetProps,
+  WidgetRenderLinkArgs,
+  WidgetStaticProps,
+} from './types.js';
+import type { WidgetBodyProps } from './WidgetBody.js';
+import { WidgetBody } from './WidgetBody.js';
+import { WidgetContext } from './WidgetContext.js';
+import type { WidgetHeaderProps } from './WidgetHeader.js';
+import { WidgetHeader } from './WidgetHeader.js';
+
+const HREF_COLLAPSIBLE_ERROR = 'Widget cannot have both href and collapsible. Use one or the other.';
+
+function assertValidWidgetMode(props: WidgetProps): void {
+  const href = 'href' in props ? props.href : undefined;
+  const collapsible = props.collapsible === true;
+
+  if (href && collapsible) {
+    if (process.env.NODE_ENV !== 'production') {
+      throw new Error(HREF_COLLAPSIBLE_ERROR);
+    }
+
+    console.error(HREF_COLLAPSIBLE_ERROR);
+  }
+}
+
+export const Widget = (props: WidgetProps): React.JSX.Element => {
+  assertValidWidgetMode(props);
+
+  const {
+    children,
+    className,
+    tooltip,
+    isFloating = false,
+    isLoading = false,
+    isEmpty = false,
+    emptyState,
+    loadingLabel = 'Loading',
+    live = false,
+    expanded,
+    defaultExpanded = true,
+    onExpandedChange,
+  } = props;
+
+  const href = 'href' in props ? props.href : undefined;
+  const renderLink = 'renderLink' in props ? props.renderLink : undefined;
+  const linkProps = 'linkProps' in props ? props.linkProps : undefined;
+  const collapsible = props.collapsible === true;
+
+  const bodyId = useId();
+  const { value: isExpanded, set: setExpanded } = useControllableBoolean({
+    value: expanded,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange,
+  });
+
+  return (
+    <WidgetContext.Provider
+      value={{
+        bodyId,
+        expanded: isExpanded,
+        setExpanded,
+        collapsible,
+        href,
+        renderLink,
+        linkProps,
+        tooltip,
+        isLoading,
+        isEmpty,
+        emptyState,
+        loadingLabel,
+        live,
+      }}
+    >
+      <Card
+        spacing="dense"
+        className={classNames('ds-widget', { 'ds-widget--floating': isFloating }, className)}
+      >
+        {children}
+      </Card>
+    </WidgetContext.Provider>
+  );
+};
+
+Widget.Header = WidgetHeader;
+Widget.Body = WidgetBody;
+
+export namespace Widget {
+  export type Props = WidgetProps;
+  export type HeaderProps = WidgetHeaderProps;
+  export type BodyProps = WidgetBodyProps;
+  export type RenderLinkArgs = WidgetRenderLinkArgs;
+  export type LinkedProps = WidgetLinkedProps;
+  export type CollapsibleProps = WidgetCollapsibleProps;
+  export type StaticProps = WidgetStaticProps;
+}

package/src/components/widget/WidgetBody.tsx

@@ -0,0 +1,66 @@
+import classNames from 'classnames';
+import { Icon } from 'Components/icon/Icon';
+import { useWidgetContext } from './WidgetContext.js';
+
+export type WidgetBodyProps = {
+  children?: React.ReactNode;
+  className?: string;
+};
+
+export const WidgetBody = (props: WidgetBodyProps): React.JSX.Element => {
+  const {
+    children,
+    className,
+  } = props;
+
+  const {
+    bodyId,
+    expanded,
+    collapsible,
+    isLoading,
+    isEmpty,
+    emptyState,
+    loadingLabel,
+    live,
+  } = useWidgetContext();
+
+  const isCollapsed = collapsible && !expanded;
+
+  let content: React.ReactNode = children;
+
+  if (!isCollapsed) {
+    if (isLoading) {
+      content = (
+        <div
+          role="status"
+          className="ds-widget__loading"
+          aria-label={loadingLabel}
+        >
+          <span className="ds-widget__loading-spinner" aria-hidden="true">
+            <Icon name="loader" size={16} />
+          </span>
+        </div>
+      );
+    }
+    else if (isEmpty) {
+      content = emptyState ?? null;
+    }
+  }
+
+  return (
+    <div
+      id={bodyId}
+      className={classNames(
+        'ds-widget__body',
+        isCollapsed && 'ds-widget__body--collapsed',
+        className,
+      )}
+      hidden={isCollapsed || undefined}
+      aria-hidden={isCollapsed || undefined}
+      aria-live={!isCollapsed && live ? 'polite' : undefined}
+      aria-busy={!isCollapsed && isLoading ? true : undefined}
+    >
+      {isCollapsed ? null : content}
+    </div>
+  );
+};

package/src/components/widget/WidgetContext.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext } from 'react';
+import type { AnchorHTMLAttributes } from 'react';
+import type { Widget } from './Widget.js';
+
+export type WidgetContextValue = {
+  bodyId: string;
+  expanded: boolean;
+  setExpanded: (expanded: boolean) => void;
+  collapsible: boolean;
+  href?: string;
+  renderLink?: (args: Widget.RenderLinkArgs) => React.ReactElement;
+  linkProps?: Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'className' | 'children'>;
+  tooltip?: string;
+  isLoading: boolean;
+  isEmpty: boolean;
+  emptyState?: React.ReactNode;
+  loadingLabel: string;
+  live: boolean;
+};
+
+export const WidgetContext = createContext<WidgetContextValue | null>(null);
+
+export function useWidgetContext(): WidgetContextValue {
+  const context = useContext(WidgetContext);
+
+  if (!context) {
+    throw new Error('Widget compound components must be used within <Widget>.');
+  }
+
+  return context;
+}

package/src/components/widget/WidgetHeader.tsx

@@ -0,0 +1,155 @@
+import classNames from 'classnames';
+import { Heading } from 'Components/heading/Heading';
+import { Icon } from 'Components/icon/Icon';
+import { TooltipWrapper } from 'Components/tooltip/TooltipWrapper';
+import type { MouseEventHandler } from 'react';
+import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
+import { useWidgetContext } from './WidgetContext.js';
+
+export type WidgetHeaderProps = {
+  children: React.ReactNode;
+  slotStart?: React.ReactNode;
+  slotEnd?: React.ReactNode;
+  className?: string;
+};
+
+export const WidgetHeader = (props: WidgetHeaderProps): React.JSX.Element => {
+  const {
+    children,
+    slotStart,
+    slotEnd,
+    className,
+  } = props;
+
+  const {
+    bodyId,
+    expanded,
+    setExpanded,
+    collapsible,
+    href,
+    renderLink,
+    linkProps,
+    tooltip,
+  } = useWidgetContext();
+
+  const isLinked = Boolean(href);
+
+  const headingNode = (
+    <Heading level={3} className="ds-widget__header-heading">
+      {children}
+    </Heading>
+  );
+
+  const chevronNode = (
+    <Icon
+      name="chevron-right"
+      size={16}
+      className="ds-widget__header-chevron"
+    />
+  );
+
+  const tooltipNode = tooltip
+    ? (
+        <TooltipWrapper tooltipContent={tooltip}>
+          <button
+            type="button"
+            className="ds-widget__header-tooltip-trigger remove-default-button-styles"
+            aria-label={tooltip}
+          >
+            <Icon name="info" size={16} />
+          </button>
+        </TooltipWrapper>
+      )
+    : null;
+
+  const toggleCollapsedState = () => {
+    if (collapsible) {
+      setExpanded(!expanded);
+    }
+  };
+
+  const handleToggleKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+    if ([SPACE_KEY, ENTER_KEY].includes(event.key)) {
+      event.preventDefault();
+      toggleCollapsedState();
+    }
+  };
+
+  const linkClassName = 'ds-widget__header-link';
+
+  let headingControl: React.ReactNode;
+
+  if (collapsible) {
+    headingControl = (
+      <Heading level={3} className="ds-widget__header-heading">
+        <button
+          type="button"
+          className={classNames('ds-widget__header-toggle', 'remove-default-button-styles')}
+          aria-expanded={expanded}
+          aria-controls={bodyId}
+          onClick={toggleCollapsedState}
+          onKeyDown={handleToggleKeyDown}
+        >
+          <Heading.InnerContainer>{children}</Heading.InnerContainer>
+          {chevronNode}
+        </button>
+      </Heading>
+    );
+  }
+  else if (isLinked) {
+    const handleLinkClick: MouseEventHandler<HTMLElement> = (event) => {
+      linkProps?.onClick?.(event as React.MouseEvent<HTMLAnchorElement>);
+    };
+
+    headingControl = renderLink
+      ? renderLink({
+          href: href!,
+          className: linkClassName,
+          children: headingNode,
+          linkProps,
+          onClick: handleLinkClick,
+        })
+      : (
+          <a
+            href={href}
+            className={linkClassName}
+            {...linkProps}
+            onClick={handleLinkClick}
+          >
+            {headingNode}
+          </a>
+        );
+  }
+  else {
+    headingControl = headingNode;
+  }
+
+  const headingRow = (
+    <div className="ds-widget__header-heading-row">
+      {headingControl}
+      {tooltipNode}
+    </div>
+  );
+
+  return (
+    <div
+      className={classNames('ds-widget__header', {
+        'ds-widget__header--linked': isLinked,
+        'ds-widget__header--collapsible': collapsible,
+      }, className)}
+    >
+      <div className="ds-widget__header-title-group">
+        {slotStart && (
+          <span className="ds-widget__header-slot-start">{slotStart}</span>
+        )}
+        {headingRow}
+      </div>
+      {(isLinked || slotEnd) && (
+        <span className="ds-widget__header-end">
+          {slotEnd}
+          {isLinked && chevronNode}
+        </span>
+      )}
+    </div>
+  );
+};

package/src/components/widget/types.ts

@@ -0,0 +1,47 @@
+import type { AnchorHTMLAttributes } from 'react';
+
+export type WidgetRenderLinkArgs = {
+  href: string;
+  className: string;
+  children: React.ReactNode;
+  onClick?: React.MouseEventHandler;
+  linkProps?: Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'className' | 'children'>;
+};
+
+type WidgetBaseProps = {
+  children: React.ReactNode;
+  className?: string;
+  tooltip?: string;
+  isFloating?: boolean;
+  isLoading?: boolean;
+  isEmpty?: boolean;
+  emptyState?: React.ReactNode;
+  loadingLabel?: string;
+  live?: boolean;
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+};
+
+export type WidgetLinkedProps = WidgetBaseProps & {
+  href: string;
+  renderLink?: (args: WidgetRenderLinkArgs) => React.ReactElement;
+  linkProps?: Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'className' | 'children'>;
+  collapsible?: false;
+};
+
+export type WidgetCollapsibleProps = WidgetBaseProps & {
+  href?: never;
+  renderLink?: never;
+  linkProps?: never;
+  collapsible: true;
+};
+
+export type WidgetStaticProps = WidgetBaseProps & {
+  href?: never;
+  renderLink?: never;
+  linkProps?: never;
+  collapsible?: false;
+};
+
+export type WidgetProps = WidgetLinkedProps | WidgetCollapsibleProps | WidgetStaticProps;