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

package/src/components/emptyState/EmptyState.stories.tsx

@@ -0,0 +1,487 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
+import { Widget } from 'Components/widget/Widget';
+import { EmptyState } from './EmptyState.js';
+import type { ComponentProps } from 'react';
+
+const DESCRIPTION_INTRO = [
+  '`EmptyState` is a centred layout for zero-data views. It supports an optional illustration,',
+  'a heading, supporting text, and a consumer-composed `actions` slot for one or more buttons.',
+  'Use it inside panels, cards, and [`Widget`](?path=/docs/components-widget--docs) bodies when there is nothing to show yet.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- A list, table, or widget has no items yet and you need to explain why and what to do next',
+  '- A filtered view returns zero results and you want to suggest clearing filters or creating content',
+  '- A dashboard region is intentionally blank until the user completes a setup step',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Transient success or error feedback | [`Banner`](?path=/docs/components-banner--docs) or [`Toast`](?path=/docs/components-toast--docs) |',
+  '| Inline hint on an unfilled form field | The relevant input\'s helper or placeholder pattern |',
+  '| Loading while data is still fetching | [`Widget`](?path=/docs/components-widget--docs) with `isLoading` or a local spinner |',
+  '| A full-page first-run marketing layout | Page-level content, not this component |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Pass buttons via `actions`.** Supply one or more [`Button`](?path=/docs/components-button--docs) elements',
+  'in the `actions` slot — for example `variant="primary"`, `variant="secondary"`, or `variant="tertiary"`.',
+  'The component does not wrap or assign variants for you.',
+  '',
+  '**Illustrations are decorative.** When using [`Icon`](?path=/docs/components-icon--docs) or `<img>`, omit',
+  '`screenReaderText` on icons and use `alt=""` on images. The heading and subheading carry the meaning.',
+  '',
+  '**Set `live` when content swaps dynamically.** Use `live={true}` when the empty state is injected after',
+  'an async fetch completes so assistive technology can announce the update politely.',
+  '',
+  '**`subHeading` accepts rich content.** Pass `ReactNode` to embed inline links using a plain `<a href>`',
+  'with the `ds-link` class from the design system stylesheet. Use your router link component with the same',
+  'class when integrating client-side navigation.',
+  '',
+  '**Choose `padding` for the container.** Default is `md`. Use `none` inside tight shells where the parent',
+  'already provides spacing; use `lg` for standalone page-level empty regions.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Renders as `<section role="region">` with `aria-labelledby` pointing at the heading',
+  '- The illustration wrapper is `aria-hidden="true"` when present',
+  '- `aria-live="polite"` is applied only when `live={true}`',
+  '- Verify `headingLevel` fits the surrounding page outline — default is `4` (suited to nested use inside [`Widget`](?path=/docs/components-widget--docs), whose header renders as `h3`)',
+  '- For standalone page-level empty regions, pass `headingLevel={2}` or `headingLevel={3}` to match the surrounding outline',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { EmptyState } from '@arbor-education/design-system.components';",
+  '',
+  'function AttendanceEmpty(props: EmptyState.Props) {',
+  '  return <EmptyState {...props} />;',
+  '}',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Button](?path=/docs/components-button--docs) · [Icon](?path=/docs/components-icon--docs) · [Widget](?path=/docs/components-widget--docs) · [Card](?path=/docs/components-card--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak heading, subheading, orientation, and live region props in real time.';
+
+function EmptyStateDocsPage() {
+  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/EmptyState',
+  component: EmptyState,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: EmptyStateDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    heading: {
+      control: 'text',
+      description: 'Primary heading text.',
+      table: { type: { summary: 'ReactNode' } },
+    },
+    subHeading: {
+      control: 'text',
+      description: 'Supporting description below the heading. Accepts ReactNode for inline links.',
+      table: { type: { summary: 'ReactNode' } },
+    },
+    padding: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg'],
+      description: 'Container padding. `xs`/`sm`/`md`/`lg` map to design-system spacing tokens.',
+      table: {
+        type: { summary: "'none' | 'xs' | 'sm' | 'md' | 'lg'" },
+        defaultValue: { summary: 'md' },
+      },
+    },
+    orientation: {
+      control: 'radio',
+      options: ['horizontal', 'vertical'],
+      description: 'Flex direction for the `actions` container.',
+      table: {
+        type: { summary: "'horizontal' | 'vertical'" },
+        defaultValue: { summary: 'horizontal' },
+      },
+    },
+    live: {
+      control: 'boolean',
+      description: 'Sets `aria-live="polite"` on the region when content updates dynamically.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    headingLevel: {
+      control: { type: 'select' },
+      options: [1, 2, 3, 4],
+      description: 'HTML heading level for the primary heading.',
+      table: {
+        type: { summary: '1 | 2 | 3 | 4' },
+        defaultValue: { summary: '4' },
+      },
+    },
+    illustration: { control: false },
+    actions: { control: false },
+    className: { control: false },
+  },
+} satisfies Meta<typeof EmptyState>;
+
+export default meta;
+
+type Story = StoryObj<typeof EmptyState>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: { story: description },
+    },
+  },
+});
+
+const TwoActionsTemplate = () => (
+  <EmptyState
+    heading="Get Started with Feature Name"
+    subHeading="Every report starts with the first chapter. Add yours below."
+    orientation="horizontal"
+    actions={(
+      <>
+        <Button type="button">Button text</Button>
+        <Button type="button" variant="secondary">Button text</Button>
+      </>
+    )}
+  />
+);
+
+const TertiaryActionTemplate = () => (
+  <EmptyState
+    heading="This chapter is looking a little empty"
+    subHeading="Start by adding the content and data blocks you want to see here."
+    orientation="vertical"
+    actions={(
+      <Button type="button" variant="text-link" iconLeftName="plus">
+        Add
+      </Button>
+    )}
+  />
+);
+
+const WithIllustrationTemplate = () => (
+  <EmptyState
+    illustration={<Icon name="circle-help" size={24} color="var(--color-grey-400)" />}
+    heading="All done!"
+    subHeading={(
+      <>
+        Your to-do list is empty right now. Find out how the to-do list works
+        {' '}
+        <a className="ds-link" href="/help/todo">here</a>
+        .
+      </>
+    )}
+  />
+);
+
+const WithInlineLinkInSubHeadingTemplate = () => (
+  <EmptyState
+    heading="No alerts yet"
+    subHeading={(
+      <>
+        There are no alerts for you right now. Find out how alerts work
+        {' '}
+        <a className="ds-link" href="/help/alerts">here</a>
+        {' '}
+        or read the
+        {' '}
+        <a className="ds-link" href="/help/alerts-guide">alerts guide</a>
+        .
+      </>
+    )}
+  />
+);
+
+const PaddingVariantsTemplate = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
+    {(['none', 'xs', 'sm', 'md', 'lg'] as const).map(size => (
+      <div key={size} style={{ border: '1px dashed var(--color-grey-200)' }}>
+        <EmptyState
+          padding={size}
+          heading={`Padding: ${size}`}
+          subHeading="Container padding around the empty state content."
+        />
+      </div>
+    ))}
+  </div>
+);
+
+const InsideWidgetTemplate = () => (
+  <Widget
+    isEmpty
+    emptyState={(
+      <EmptyState
+        padding="md"
+        illustration={<Icon name="circle-help" size={24} color="var(--color-grey-400)" />}
+        heading="All clear!"
+        subHeading="There are no alerts for you right now."
+      />
+    )}
+  >
+    <Widget.Header>Alerts (0)</Widget.Header>
+    <Widget.Body />
+  </Widget>
+);
+
+export const Default = {
+  args: {
+    heading: 'No reports yet',
+    subHeading: 'Upload your first report to get started.',
+    orientation: 'horizontal',
+    live: false,
+    headingLevel: 4,
+    padding: 'md',
+  },
+  render: (args: ComponentProps<typeof EmptyState>) => (
+    <EmptyState
+      {...args}
+      actions={(
+        <Button type="button" variant="primary">
+          Upload report
+        </Button>
+      )}
+    />
+  ),
+};
+
+export const WithoutIllustrationTwoActions: Story = withDescription(
+  {
+    render: TwoActionsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button, EmptyState } from '@arbor-education/design-system.components';
+
+function EmptyStateTwoActionsExample() {
+  return (
+    <EmptyState
+      heading="Get Started with Feature Name"
+      subHeading="Every report starts with the first chapter. Add yours below."
+      orientation="horizontal"
+      actions={
+        <>
+          <Button type="button">Button text</Button>
+          <Button type="button" variant="secondary">Button text</Button>
+        </>
+      }
+    />
+  );
+}
+export default EmptyStateTwoActionsExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Primary and secondary actions side by side. Use `orientation="horizontal"` when actions sit on one row.',
+);
+
+export const WithoutIllustrationTertiaryAction: Story = withDescription(
+  {
+    render: TertiaryActionTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Button, EmptyState } from '@arbor-education/design-system.components';
+
+function EmptyStateTertiaryActionExample() {
+  return (
+    <EmptyState
+      heading="This chapter is looking a little empty"
+      subHeading="Start by adding the content and data blocks you want to see here."
+      orientation="vertical"
+      actions={
+        <Button type="button" variant="text-link" iconLeftName="plus">
+          Add
+        </Button>
+      }
+    />
+  );
+}
+export default EmptyStateTertiaryActionExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'A single tertiary action below the copy. Use `orientation="vertical"` when actions stack beneath the text.',
+);
+
+export const WithIllustrationNoActions: Story = withDescription(
+  {
+    render: WithIllustrationTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { EmptyState, Icon } from '@arbor-education/design-system.components';
+
+function EmptyStateWithIllustrationExample() {
+  return (
+    <EmptyState
+      illustration={<Icon name="circle-help" size={24} color="var(--color-grey-400)" />}
+      heading="All done!"
+      subHeading={
+        <>
+          Your to-do list is empty right now. Find out how the to-do list works{' '}
+          <a className="ds-link" href="/help/todo">here</a>
+          .
+        </>
+      }
+    />
+  );
+}
+export default EmptyStateWithIllustrationExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Illustration with heading and subheading only. The subheading embeds an inline link styled with `ds-link` for supplementary help.',
+);
+
+export const WithInlineLinkInSubHeading: Story = withDescription(
+  {
+    render: WithInlineLinkInSubHeadingTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { EmptyState } from '@arbor-education/design-system.components';
+
+function EmptyStateInlineLinkExample() {
+  return (
+    <EmptyState
+      heading="No alerts yet"
+      subHeading={
+        <>
+          There are no alerts for you right now. Find out how alerts work{' '}
+          <a className="ds-link" href="/help/alerts">here</a>
+          {' '}or read the <a className="ds-link" href="/help/alerts-guide">alerts guide</a>.
+        </>
+      }
+    />
+  );
+}
+export default EmptyStateInlineLinkExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Embed inline links in `subHeading` with `<a className="ds-link">` — works with plain anchors or router link components.',
+);
+
+export const PaddingVariants: Story = withDescription(
+  {
+    render: PaddingVariantsTemplate,
+    parameters: {
+      controls: { disable: true },
+    },
+  },
+  'All `padding` sizes from `none` through `lg`. Default is `md` — use `none` when the parent shell already provides spacing.',
+);
+
+export const InsideWidget: Story = withDescription(
+  {
+    render: InsideWidgetTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { EmptyState, Icon, Widget } from '@arbor-education/design-system.components';
+
+function EmptyStateInsideWidgetExample() {
+  return (
+    <Widget
+      isEmpty
+      emptyState={
+        <EmptyState
+          padding="md"
+          illustration={<Icon name="circle-help" size={24} color="var(--color-grey-400)" />}
+          heading="All clear!"
+          subHeading="There are no alerts for you right now."
+        />
+      }
+    >
+      <Widget.Header>Alerts (0)</Widget.Header>
+      <Widget.Body />
+    </Widget>
+  );
+}
+export default EmptyStateInsideWidgetExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Typical dashboard usage: pass `<EmptyState />` to `Widget` via `emptyState` when `isEmpty` is true.',
+);

package/src/components/emptyState/EmptyState.test.tsx

@@ -0,0 +1,140 @@
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { Button } from 'Components/button/Button';
+import { EmptyState } from './EmptyState.js';
+
+describe('EmptyState', () => {
+  test('renders semantic structure with heading and subheading', () => {
+    render(
+      <EmptyState
+        heading="No reports yet"
+        subHeading="Upload your first report to get started."
+      />,
+    );
+
+    expect(screen.getByRole('region')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 4, name: 'No reports yet' })).toBeInTheDocument();
+    expect(screen.getByText('Upload your first report to get started.')).toBeInTheDocument();
+  });
+
+  test('omits illustration wrapper when illustration is not provided', () => {
+    const { container } = render(<EmptyState heading="Empty" />);
+
+    expect(container.querySelector('.ds-empty-state__illustration')).not.toBeInTheDocument();
+  });
+
+  test('renders illustration wrapper with aria-hidden when illustration is provided', () => {
+    const { container } = render(
+      <EmptyState
+        heading="All done!"
+        illustration={<span data-testid="illus">icon</span>}
+      />,
+    );
+
+    const illustrationWrapper = container.querySelector('.ds-empty-state__illustration');
+
+    expect(illustrationWrapper).toBeInTheDocument();
+    expect(illustrationWrapper).toHaveAttribute('aria-hidden', 'true');
+    expect(screen.getByTestId('illus')).toBeInTheDocument();
+  });
+
+  test('omits subheading paragraph when subHeading is not provided', () => {
+    const { container } = render(<EmptyState heading="Empty" />);
+
+    expect(container.querySelector('.ds-empty-state__sub-heading')).not.toBeInTheDocument();
+  });
+
+  test('omits actions wrapper when no actions are provided', () => {
+    const { container } = render(<EmptyState heading="Empty" />);
+
+    expect(container.querySelector('.ds-empty-state__actions')).not.toBeInTheDocument();
+  });
+
+  test('renders actions inside actions container', () => {
+    render(
+      <EmptyState
+        heading="Get started"
+        actions={(
+          <>
+            <Button type="button">Primary</Button>
+            <Button type="button" variant="secondary">Secondary</Button>
+            <Button type="button" variant="tertiary">Tertiary</Button>
+          </>
+        )}
+      />,
+    );
+
+    const actions = screen.getByText('Primary').closest('.ds-empty-state__actions');
+
+    expect(actions).toBeInTheDocument();
+    expect(actions).toHaveTextContent('Primary');
+    expect(actions).toHaveTextContent('Secondary');
+    expect(actions).toHaveTextContent('Tertiary');
+  });
+
+  test('applies horizontal orientation modifier by default', () => {
+    const { container } = render(
+      <EmptyState
+        heading="Get started"
+        actions={<Button type="button">Primary</Button>}
+      />,
+    );
+
+    expect(container.querySelector('.ds-empty-state__actions--horizontal')).toBeInTheDocument();
+  });
+
+  test('applies vertical orientation modifier when orientation is vertical', () => {
+    const { container } = render(
+      <EmptyState
+        heading="Get started"
+        orientation="vertical"
+        actions={<Button type="button">Primary</Button>}
+      />,
+    );
+
+    expect(container.querySelector('.ds-empty-state__actions--vertical')).toBeInTheDocument();
+  });
+
+  test('sets aria-live when live is true', () => {
+    render(<EmptyState heading="Empty" live />);
+
+    expect(screen.getByRole('region')).toHaveAttribute('aria-live', 'polite');
+  });
+
+  test('does not set aria-live by default', () => {
+    render(<EmptyState heading="Empty" />);
+
+    expect(screen.getByRole('region')).not.toHaveAttribute('aria-live');
+  });
+
+  test('supports custom heading level', () => {
+    render(<EmptyState heading="Empty" headingLevel={3} />);
+
+    expect(screen.getByRole('heading', { level: 3, name: 'Empty' })).toBeInTheDocument();
+  });
+
+  test('applies md padding modifier by default', () => {
+    const { container } = render(<EmptyState heading="Empty" />);
+
+    expect(container.querySelector('.ds-empty-state')).toHaveClass('ds-empty-state--padding-md');
+  });
+
+  test('applies padding modifier for each size', () => {
+    const { container: xsContainer } = render(<EmptyState heading="Empty" padding="xs" />);
+    const { container: smContainer } = render(<EmptyState heading="Empty" padding="sm" />);
+    const { container: lgContainer } = render(<EmptyState heading="Empty" padding="lg" />);
+
+    expect(xsContainer.querySelector('.ds-empty-state')).toHaveClass('ds-empty-state--padding-xs');
+    expect(smContainer.querySelector('.ds-empty-state')).toHaveClass('ds-empty-state--padding-sm');
+    expect(lgContainer.querySelector('.ds-empty-state')).toHaveClass('ds-empty-state--padding-lg');
+  });
+
+  test('omits padding modifier when padding is none', () => {
+    const { container } = render(<EmptyState heading="Empty" padding="none" />);
+
+    const root = container.querySelector('.ds-empty-state');
+    expect(root).toBeInTheDocument();
+    expect(root?.className).not.toMatch(/ds-empty-state--padding-/);
+  });
+});