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

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

@@ -0,0 +1,600 @@
+import {
+  Controls,
+  Heading as DocHeading,
+  Primary as DocPrimary,
+  Markdown,
+  Stories,
+  Subheading,
+  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 type { ComponentProps } from 'react';
+import { Widget } from './Widget.js';
+
+const DESCRIPTION_INTRO = [
+  '`Widget` is a compound dashboard card built on [`Card`](?path=/docs/components-card--docs).',
+  'Compose it with `Widget.Header` and `Widget.Body` to show a titled region with optional link navigation,',
+  'collapsible body, header tooltip, and built-in loading or empty states.',
+  '',
+  '> **Built on [`TooltipWrapper`](?path=/docs/components-tooltip-tooltipwrapper--docs) for header tooltips.**',
+  'Tooltips render via a portal — do not place the widget inside a container with `overflow: hidden` if the tooltip is clipped.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Dashboard panels that summarise a dataset (alerts, favourites, attendance) inside a card shell',
+  '- Regions that need a linked header to drill into a full page (`href` + chevron)',
+  '- Collapsible summary widgets where the body can be hidden to save vertical space',
+  '- Async widgets that swap between loading, empty, and populated body content',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| A single metric with label and value | [`KPICard`](?path=/docs/components-card-kpicard--docs) |',
+  '| A static content block with no header states | [`Card`](?path=/docs/components-card--docs) directly |',
+  '| Full-page section with action button in header | [`Section`](?path=/docs/components-section--docs) |',
+  '| Header navigates AND toggles collapse | Pick one — `href` and `collapsible` cannot be combined |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Compound composition only.** Always render `Widget.Header` and `Widget.Body` inside `Widget`.',
+  'Sub-components read shared state from context — they throw if used outside the root.',
+  '',
+  '**`href` and `collapsible` are mutually exclusive.** TypeScript prevents both; a dev runtime error',
+  'is also thrown if both props are passed. A header cannot navigate and toggle body visibility.',
+  '',
+  '**Linked headers use a stretched link overlay.** When `href` is set, the anchor wraps the title text',
+  'and a CSS `::after` pseudo-element covers `slotStart`, the heading, and the end chevron.',
+  'The tooltip icon sits in `.ds-widget__header-heading-row` beside the heading, raised above the overlay.',
+  'A `chevron-right` is auto-injected at the header end.',
+  '',
+  '**Empty state is consumer-composed.** Pass `isEmpty` and an `emptyState` node — typically',
+  '[`<EmptyState />`](?path=/docs/components-emptystate--docs). The default heading outline is',
+  '`Widget.Header` → `h3`, nested `EmptyState` → `h4`. Override `EmptyState` `headingLevel` for other contexts.',
+  '',
+  '**Loading sets `aria-busy`.** When `isLoading` is true, the body shows a status indicator',
+  'and the body container sets `aria-busy="true"`.',
+  '',
+  '**Dense spacing is fixed.** Widget always renders with `Card` spacing `"dense"`.',
+  '',
+  '**Body overflow.** When the widget sits in a height-constrained parent (e.g. a dashboard grid cell),',
+  '`.ds-widget__body` scrolls vertically while the header stays pinned. Give the parent an explicit height',
+  'and place the widget inside a flex column container — the widget fills `height: 100%` automatically.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Collapsible headers render an `h3` wrapping a toggle `button` (title span + chevron) with `aria-expanded` and `aria-controls` pointing at the body id',
+  '- `Widget.Header` renders the title via [`Heading`](?path=/docs/components-heading--docs) at level `3`',
+  '- Enter and Space toggle collapsible headers',
+  '- Tooltip trigger is a separate `<button>` beside the heading — it is not nested inside the link or collapse control',
+  '- Set `live={true}` when body content swaps dynamically after fetch',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Widget } from '@arbor-education/design-system.components';",
+  '',
+  'function AlertsWidget(props: Widget.Props) {',
+  '  return (',
+  '    <Widget {...props}>',
+  '      <Widget.Header>Alerts</Widget.Header>',
+  '      <Widget.Body />',
+  '    </Widget>',
+  '  );',
+  '}',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Card](?path=/docs/components-card--docs) · [EmptyState](?path=/docs/components-emptystate--docs) · [Heading](?path=/docs/components-heading--docs) · [TooltipWrapper](?path=/docs/components-tooltip-tooltipwrapper--docs)',
+].join('\n');
+
+const PROPS_INTRO = [
+  'The preview below wires root-level props to the **Controls** panel.',
+  'Because `Widget` is compound, `Widget.Header` and `Widget.Body` props are documented in the manual tables below.',
+].join(' ');
+
+const HEADER_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | **Required.** Header title text |',
+  '| `slotStart` | `ReactNode` | — | Leading slot (e.g. avatar); included in linked header hit area |',
+  '| `className` | `string` | — | Additional CSS classes on the header wrapper |',
+].join('\n');
+
+const BODY_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | Main body content when not loading or empty |',
+  '| `className` | `string` | — | Additional CSS classes on the body wrapper |',
+].join('\n');
+
+function WidgetDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <Subheading>Widget.Header props</Subheading>
+      <Markdown>{HEADER_PROPS}</Markdown>
+      <Subheading>Widget.Body props</Subheading>
+      <Markdown>{BODY_PROPS}</Markdown>
+      <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',
+  component: Widget,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: WidgetDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    tooltip: {
+      control: 'text',
+      description: 'Renders an info icon with tooltip beside the header title.',
+      table: { type: { summary: 'string' } },
+    },
+    isLoading: {
+      control: 'boolean',
+      description: 'Replaces body content with a loading indicator and sets `aria-busy` on the body.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    isEmpty: {
+      control: 'boolean',
+      description: 'Renders `emptyState` instead of body children.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    loadingLabel: {
+      control: 'text',
+      description: 'Accessible name for the loading status indicator.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'Loading' },
+      },
+    },
+    live: {
+      control: 'boolean',
+      description: 'Sets `aria-live="polite"` on the body when content swaps dynamically.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    collapsible: { control: false },
+    href: { control: false },
+    renderLink: { control: false },
+    linkProps: { control: false },
+    emptyState: { control: false },
+    children: { control: false },
+    className: { control: false },
+    expanded: { control: false },
+    defaultExpanded: { control: false },
+    onExpandedChange: { control: false },
+  },
+} satisfies Meta<typeof Widget>;
+
+export default meta;
+
+type Story = StoryObj<typeof Widget>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...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 StaticWithEmptyStateTemplate = () => (
+  <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. Find out how alerts work
+            {' '}
+            <a className="ds-link" href="/help/alerts">here</a>
+            .
+          </>
+        )}
+      />
+    )}
+  >
+    <Widget.Header>Alerts (0)</Widget.Header>
+    <Widget.Body />
+  </Widget>
+);
+
+const LinkedWithContentTemplate = () => (
+  <Widget href="/alerts">
+    <Widget.Header>Alerts (2)</Widget.Header>
+    <Widget.Body>
+      <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
+        <li>New message from school head</li>
+        <li>Parents evening begins in 5 days</li>
+      </ul>
+    </Widget.Body>
+  </Widget>
+);
+
+const WithTooltipTemplate = () => (
+  <Widget tooltip="Your starred items appear here">
+    <Widget.Header>Favourites</Widget.Header>
+    <Widget.Body>
+      <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
+        {Array.from({ length: 6 }, (_, index) => (
+          <li key={index}>Favourite</li>
+        ))}
+      </ul>
+    </Widget.Body>
+  </Widget>
+);
+
+const CollapsibleTemplate = () => (
+  <Widget collapsible defaultExpanded>
+    <Widget.Header>Attendance summary</Widget.Header>
+    <Widget.Body>
+      <p style={{ margin: 0 }}>Widget body content</p>
+    </Widget.Body>
+  </Widget>
+);
+
+const LoadingTemplate = () => (
+  <Widget isLoading loadingLabel="Loading alerts">
+    <Widget.Header>Alerts</Widget.Header>
+    <Widget.Body><p>Content hidden while loading</p></Widget.Body>
+  </Widget>
+);
+
+const WithRenderLinkTemplate = () => (
+  <Widget
+    href="/alerts"
+    renderLink={({ href, className, children, linkProps }) => (
+      <a href={href} className={className} data-router-link="true" {...linkProps}>
+        {children}
+      </a>
+    )}
+  >
+    <Widget.Header>Alerts (2)</Widget.Header>
+    <Widget.Body>
+      <p style={{ margin: 0 }}>Linked via custom renderLink</p>
+    </Widget.Body>
+  </Widget>
+);
+
+const FixedHeightOverflowTemplate = () => (
+  <FixedHeightWidgetContainer>
+    <Widget isFloating>
+      <Widget.Header>Favourites</Widget.Header>
+      <Widget.Body>
+        <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
+          {Array.from({ length: 20 }, (_, index) => (
+            <li key={index} style={{ padding: 'var(--spacing-xsmall) 0' }}>
+              {`Favourite item ${index + 1}`}
+            </li>
+          ))}
+        </ul>
+      </Widget.Body>
+    </Widget>
+  </FixedHeightWidgetContainer>
+);
+
+export const Default = {
+  args: {
+    tooltip: '',
+    isLoading: false,
+    isEmpty: false,
+    loadingLabel: 'Loading',
+    live: false,
+  },
+  render: (args: ComponentProps<typeof Widget>) => (
+    <Widget {...args}>
+      <Widget.Header>Attendance summary</Widget.Header>
+      <Widget.Body>
+        <p style={{ margin: 0 }}>Widget body content</p>
+      </Widget.Body>
+    </Widget>
+  ),
+};
+
+export const StaticWithEmptyState: Story = withDescription(
+  {
+    render: StaticWithEmptyStateTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { EmptyState, Icon, Widget } from '@arbor-education/design-system.components';
+
+function WidgetStaticEmptyExample() {
+  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. Find out how alerts work{' '}
+              <a className="ds-link" href="/help/alerts">here</a>
+              .
+            </>
+          }
+        />
+      }
+    >
+      <Widget.Header>Alerts (0)</Widget.Header>
+      <Widget.Body />
+    </Widget>
+  );
+}
+export default WidgetStaticEmptyExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Static header with no link or chevron. Body shows `emptyState` when `isEmpty` is true.',
+);
+
+export const LinkedWithContent: Story = withDescription(
+  {
+    render: LinkedWithContentTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Widget } from '@arbor-education/design-system.components';
+
+function WidgetLinkedExample() {
+  return (
+    <Widget href="/alerts">
+      <Widget.Header>Alerts (2)</Widget.Header>
+      <Widget.Body>
+        <ul>
+          <li>New message from school head</li>
+        </ul>
+      </Widget.Body>
+    </Widget>
+  );
+}
+export default WidgetLinkedExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Linked header: anchor wraps the title; a CSS overlay covers slotStart, heading, and end chevron. Tooltip stays above the overlay.',
+);
+
+export const WithTooltip: Story = withDescription(
+  {
+    render: WithTooltipTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Widget } from '@arbor-education/design-system.components';
+
+function WidgetWithTooltipExample() {
+  return (
+    <Widget tooltip="Your starred items appear here">
+      <Widget.Header>Favourites</Widget.Header>
+      <Widget.Body>
+        <ul>
+          <li>Favourite</li>
+        </ul>
+      </Widget.Body>
+    </Widget>
+  );
+}
+export default WidgetWithTooltipExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Info icon tooltip sits in the heading row immediately beside the title text.',
+);
+
+export const Collapsible: Story = withDescription(
+  {
+    render: CollapsibleTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Widget } from '@arbor-education/design-system.components';
+
+function WidgetCollapsibleExample() {
+  return (
+    <Widget collapsible defaultExpanded>
+      <Widget.Header>Attendance summary</Widget.Header>
+      <Widget.Body>
+        <p>Widget body content</p>
+      </Widget.Body>
+    </Widget>
+  );
+}
+export default WidgetCollapsibleExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Collapsible header toggles body visibility. Chevron rotates when expanded.',
+);
+
+export const Loading: Story = withDescription(
+  {
+    render: LoadingTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Widget } from '@arbor-education/design-system.components';
+
+function WidgetLoadingExample() {
+  return (
+    <Widget isLoading loadingLabel="Loading alerts">
+      <Widget.Header>Alerts</Widget.Header>
+      <Widget.Body />
+    </Widget>
+  );
+}
+export default WidgetLoadingExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Loading replaces body content and sets `aria-busy="true"` on the body container.',
+);
+
+export const WithRenderLink: Story = withDescription(
+  {
+    render: WithRenderLinkTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Widget } from '@arbor-education/design-system.components';
+
+function WidgetRenderLinkExample() {
+  return (
+    <Widget
+      href="/alerts"
+      renderLink={({ href, className, children, linkProps }) => (
+        <a href={href} className={className} {...linkProps}>
+          {children}
+        </a>
+      )}
+    >
+      <Widget.Header>Alerts (2)</Widget.Header>
+      <Widget.Body />
+    </Widget>
+  );
+}
+export default WidgetRenderLinkExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Inject a custom router link via `renderLink` — same pattern as SidebarNav.',
+);
+
+export const FixedHeightOverflow: Story = withDescription(
+  {
+    render: FixedHeightOverflowTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Widget } from '@arbor-education/design-system.components';
+
+function WidgetFixedHeightOverflowExample() {
+  return (
+    <div style={{ height: 280, display: 'flex', flexDirection: 'column' }}>
+      <Widget isFloating>
+        <Widget.Header>Favourites</Widget.Header>
+        <Widget.Body>
+          <ul>
+            {Array.from({ length: 20 }, (_, index) => (
+              <li key={index}>Favourite item {index + 1}</li>
+            ))}
+          </ul>
+        </Widget.Body>
+      </Widget>
+    </div>
+  );
+}
+export default WidgetFixedHeightOverflowExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Parent container constrains height; the widget header stays pinned while `.ds-widget__body` scrolls overflow content.',
+);