@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/toast/Toast.stories.tsx

@@ -1,113 +1,575 @@
+import { createPortal } from 'react-dom';
+import { useState } from 'react';
 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 { Toast, type ToastProps } from './Toast';
-import { useState } from 'react';
 import { Button } from 'Components/button/Button';
 
-const meta: Meta<typeof Toast> = {
-  tags: ['autodocs'],
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Toast is a brief, non-blocking notification that appears at the edge of the screen and auto-dismisses',
+  'after a timeout. Use it for low-priority confirmations of completed actions.',
+  'Built on [Radix UI Toast](https://www.radix-ui.com/primitives/docs/components/toast).',
+  '',
+  '> **Requires setup.** `Toast.Provider` must wrap your component tree (once, near the root) and',
+  '> `Toast.Viewport` must live inside the same provider — this is where toasts are rendered into the DOM.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Action confirmations** — "Record saved", "Email sent", "Item deleted"',
+  '- **Non-blocking status** — the user does not need to read the message before continuing',
+  '- **Low-priority alerts** — information the user benefits from knowing, but that does not require action',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| The user must act before continuing | [`Modal`](?path=/docs/components-modals-modal--docs) |',
+  '| Persistent contextual information on a page | [`Banner`](?path=/docs/components-banner--docs) |',
+  '| An error the user must fix | [`Banner`](?path=/docs/components-banner--docs) (danger) or form validation messages |',
+  '| Content requiring more than 2 lines | Banner — toasts are not designed for long copy |',
+  '',
+  '---',
+  '',
+  '### Content guidelines',
+  '',
+  '- **Ideal: 1 line.** "Assessment period saved." Short, past-tense confirmation.',
+  '- **Acceptable: 2 lines.** A little more context is fine — "Assessment period saved. Pupils can now submit work."',
+  '- **Never: 3+ lines.** If you need that much copy, use a Banner instead.',
+  '- Use sentence case. No trailing punctuation on single sentences (optional on two-sentence messages).',
+  '- Do NOT include action links or buttons inside the toast — the close button is the only interaction.',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Setup — required once per app',
+  '',
+  '```tsx',
+  "import { Toast } from '@arbor-education/design-system.components';",
+  '',
+  'function App() {',
+  '  return (',
+  '    <Toast.Provider>',
+  '      {/* your app */}',
+  '      <Toast.Viewport />  {/* renders toasts into the DOM */}',
+  '    </Toast.Provider>',
+  '  );',
+  '}',
+  '```',
+  '',
+  '`Toast.Provider` and `Toast.Viewport` only need to be mounted **once**. The `Toast` component itself',
+  'can then be rendered and controlled from anywhere in the tree below the provider.',
+  '',
+  '---',
+  '',
+  '### Controlling open state',
+  '',
+  '```tsx',
+  "import { Toast, Button } from '@arbor-education/design-system.components';",
+  "import { useState } from 'react';",
+  '',
+  'function SaveButton() {',
+  '  const [open, setOpen] = useState(false);',
+  '',
+  '  const handleSave = () => {',
+  '    // perform save...',
+  '    setOpen(true); // show toast',
+  '  };',
+  '',
+  '  return (',
+  '    <>',
+  '      <Button onClick={handleSave}>Save</Button>',
+  '      <Toast open={open} onOpenChange={setOpen} variant="success">',
+  '        Assessment period saved',
+  '      </Toast>',
+  '    </>',
+  '  );',
+  '}',
+  '```',
+  '',
+  '**Re-triggering the same toast**: If the user performs the same action twice, React will not re-open',
+  'the toast because `open` is already `true`. Reset it first:',
+  '```ts',
+  'setOpen(false);',
+  'requestAnimationFrame(() => setOpen(true));',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Radix renders `role="status"` (for `type="background"`, the default) or `role="alert"`',
+  '  (for `type="foreground"`). Do NOT add `aria-live` yourself — Radix handles this.',
+  '- `children` is rendered as `Toast.Title` — it is always required for screen reader announcement.',
+  '- `type="foreground"` causes the toast to be announced immediately, interrupting the user.',
+  '  Use only for genuinely urgent messages. Default `type="background"` announces at the next pause.',
+  '',
+  '---',
+  '',
+  '### Sub-component props',
+  '',
+  '| Sub-component | Key props | Description |',
+  '|---|---|---|',
+  '| `Toast.Provider` | `duration?` (default 5000ms), `label?`, `swipeDirection?` | Wraps the tree — mount once |',
+  '| `Toast.Viewport` | `hotkey?` (default F8), `label?` | The DOM target toasts render into — must be inside `Toast.Provider` |',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Toast } from '@arbor-education/design-system.components';",
+  "import type { ToastProps } from '@arbor-education/design-system.components';",
+  '',
+  "type ToastVariant = 'information' | 'success' | 'warning' | 'danger';",
+  '',
+  'type ToastProps = RadixToast.ToastProps & {',
+  '  variant?: ToastVariant; // default: "information"',
+  '};',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Banner](?path=/docs/components-banner--docs) · [Modal](?path=/docs/components-modals-modal--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function ToastDocsPage() {
+  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>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
   title: 'Components/Toast',
   component: Toast,
+  tags: ['autodocs'],
   parameters: {
+    layout: 'centered',
     docs: {
-      description: {
-        component: 'Toasts must have a Toast.Provider somewhere in its parent tree. A Toast.Viewport is also required inside the same provider as it is the element the toasts are rendered into. This uses the Radix Toast component, see https://www.radix-ui.com/primitives/docs/components/toast for more information.',
-      },
+      page: ToastDocsPage,
     },
   },
   argTypes: {
     variant: {
       control: 'select',
       options: ['information', 'success', 'warning', 'danger'],
-      description: 'Toast variant',
+      description: 'Sets the colour, icon, and semantic meaning of the toast.',
+      table: {
+        type: { summary: "'information' | 'success' | 'warning' | 'danger'" },
+        defaultValue: { summary: "'information'" },
+      },
+    },
+    children: {
+      control: 'text',
+      description: [
+        'The toast message. Rendered as `Toast.Title` — always required for screen reader announcement.',
+        'Keep to 1 line ideally, 2 lines maximum.',
+      ].join(' '),
+      table: {
+        type: { summary: 'ReactNode' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    duration: {
+      control: { type: 'number', min: 0, step: 500 },
+      description: [
+        'Time in milliseconds before the toast auto-dismisses.',
+        'Inherited from `Toast.Provider` if not set per-toast.',
+        'Pass `Infinity` to disable auto-dismiss.',
+      ].join(' '),
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: '5000' },
+      },
+    },
+    type: {
+      control: 'select',
+      options: ['background', 'foreground'],
+      description: [
+        '`"background"` (default) — announced at the next pause in user interaction.',
+        '`"foreground"` — announced immediately, interrupting the user. Reserve for urgent messages.',
+      ].join(' '),
+      table: {
+        type: { summary: "'background' | 'foreground'" },
+        defaultValue: { summary: "'background'" },
+      },
+    },
+    open: {
+      control: false,
+      description: 'Controlled open state. Pair with `onOpenChange` to manage dismiss.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    onOpenChange: {
+      control: false,
+      description: 'Fired when the toast opens or closes (including auto-dismiss and swipe).',
+      table: {
+        type: { summary: '(open: boolean) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
   },
-};
+} satisfies Meta<typeof Toast>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// NOTE: Toast.Viewport is portaled to document.body via createPortal so that
+// position:fixed works correctly in Storybook's canvas context (the canvas
+// CSS would otherwise constrain fixed positioning to the canvas area).
+// ---------------------------------------------------------------------------
 
-type Story = StoryObj<typeof Toast>;
+const ToastStoryWrapper = ({ children }: { children: React.ReactNode }) => (
+  <Toast.Provider>
+    {children}
+    {createPortal(<Toast.Viewport />, document.body)}
+  </Toast.Provider>
+);
 
-const ToastWrapper = (args: ToastProps) => {
+const DefaultTemplate = (args: ToastProps) => {
   const [open, setOpen] = useState(false);
   return (
-    <Toast.Provider>
-      <Button onClick={() => setOpen(true)}>Open Toast</Button>
+    <ToastStoryWrapper>
+      <Button onClick={() => setOpen(true)}>Show toast</Button>
       <Toast {...args} open={open} onOpenChange={setOpen} />
-      <Toast.Viewport />
-    </Toast.Provider>
+    </ToastStoryWrapper>
   );
 };
 
-export const Information: Story = {
-  args: {
-    variant: 'information',
-    children: 'This is an information message',
-  },
-  render: ToastWrapper,
+const AllVariantsTemplate = () => {
+  const [infoOpen, setInfoOpen] = useState(false);
+  const [successOpen, setSuccessOpen] = useState(false);
+  const [warningOpen, setWarningOpen] = useState(false);
+  const [dangerOpen, setDangerOpen] = useState(false);
+
+  return (
+    <ToastStoryWrapper>
+      <div style={{ display: 'flex', gap: 'var(--spacing-small)', flexWrap: 'wrap' }}>
+        <Button onClick={() => setInfoOpen(true)}>Information</Button>
+        <Button onClick={() => setSuccessOpen(true)}>Success</Button>
+        <Button onClick={() => setWarningOpen(true)}>Warning</Button>
+        <Button onClick={() => setDangerOpen(true)}>Danger</Button>
+      </div>
+      <Toast variant="information" open={infoOpen} onOpenChange={setInfoOpen}>
+        Attendance report generated
+      </Toast>
+      <Toast variant="success" open={successOpen} onOpenChange={setSuccessOpen}>
+        Assessment period saved
+      </Toast>
+      <Toast variant="warning" open={warningOpen} onOpenChange={setWarningOpen}>
+        Session expires in 5 minutes
+      </Toast>
+      <Toast variant="danger" open={dangerOpen} onOpenChange={setDangerOpen}>
+        Failed to save changes — please try again
+      </Toast>
+    </ToastStoryWrapper>
+  );
 };
 
-export const Success: Story = {
-  args: {
-    variant: 'success',
-    children: 'Your changes have been saved successfully!',
-  },
-  render: ToastWrapper,
+const ContentGuidelinesTemplate = () => {
+  const [idealOpen, setIdealOpen] = useState(false);
+  const [acceptableOpen, setAcceptableOpen] = useState(false);
+  const [tooLongOpen, setTooLongOpen] = useState(false);
+
+  return (
+    <ToastStoryWrapper>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', alignItems: 'flex-start' }}>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-medium)' }}>
+          <Button onClick={() => setIdealOpen(true)}>Ideal — 1 line</Button>
+          <span style={{ fontSize: 'var(--font-size-2-13)', color: 'var(--color-semantic-success-600)' }}>
+            Short, past-tense, no trailing punctuation
+          </span>
+        </div>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-medium)' }}>
+          <Button onClick={() => setAcceptableOpen(true)}>Acceptable — 2 lines</Button>
+          <span style={{ fontSize: 'var(--font-size-2-13)', color: 'var(--color-semantic-caution-600)' }}>
+            A little context is fine
+          </span>
+        </div>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-medium)' }}>
+          <Button variant="secondary-destructive" onClick={() => setTooLongOpen(true)}>Too long — use Banner</Button>
+          <span style={{ fontSize: 'var(--font-size-2-13)', color: 'var(--color-semantic-destructive-600)' }}>
+            3+ lines — switch to Banner instead
+          </span>
+        </div>
+      </div>
+      <Toast variant="success" open={idealOpen} onOpenChange={setIdealOpen}>
+        Assessment period saved
+      </Toast>
+      <Toast variant="success" open={acceptableOpen} onOpenChange={setAcceptableOpen}>
+        Assessment period saved. Pupils can now submit work for grading.
+      </Toast>
+      <Toast variant="information" open={tooLongOpen} onOpenChange={setTooLongOpen}>
+        Assessment period saved. Pupils can now submit work for grading. Remember to notify your department heads and check the term dates align with your reporting schedule before the deadline.
+      </Toast>
+    </ToastStoryWrapper>
+  );
 };
 
-export const Warning: Story = {
-  args: {
-    variant: 'warning',
-    children: 'Please review your changes before proceeding',
-  },
-  render: ToastWrapper,
+const WithCustomDurationTemplate = () => {
+  const [shortOpen, setShortOpen] = useState(false);
+  const [longOpen, setLongOpen] = useState(false);
+
+  return (
+    <ToastStoryWrapper>
+      <div style={{ display: 'flex', gap: 'var(--spacing-small)' }}>
+        <Button onClick={() => setShortOpen(true)}>Short (2 s)</Button>
+        <Button onClick={() => setLongOpen(true)}>Long (10 s)</Button>
+      </div>
+      <Toast variant="information" open={shortOpen} onOpenChange={setShortOpen} duration={2000}>
+        Dismissed in 2 seconds
+      </Toast>
+      <Toast variant="information" open={longOpen} onOpenChange={setLongOpen} duration={10000}>
+        Dismissed in 10 seconds — use for important but non-urgent messages
+      </Toast>
+    </ToastStoryWrapper>
+  );
 };
 
-export const Danger: Story = {
-  args: {
-    variant: 'danger',
-    children: 'An error occurred while processing your request',
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      variant: 'information',
+      children: 'Attendance report generated',
+    },
+    render: args => <DefaultTemplate {...args} />,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Toast, Button } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+// Toast.Provider and Toast.Viewport should be at your app root — mount them once.
+function ToastDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Toast.Provider>
+      <Button onClick={() => setOpen(true)}>Show toast</Button>
+      <Toast variant="information" open={open} onOpenChange={setOpen}>
+        Attendance report generated
+      </Toast>
+      <Toast.Viewport />
+    </Toast.Provider>
+  );
+}
+export default ToastDemo;
+`.trim(),
+        },
+      },
+    },
   },
-  render: ToastWrapper,
-};
+  [
+    'The default `information` toast. Click the button to trigger it — it auto-dismisses after 5 seconds',
+    'or can be closed manually with the X button.',
+    'Tweak the **variant** and **children** controls to preview other variants.',
+  ].join(' '),
+);
+
+export const AllVariants: Story = withDescription(
+  {
+    render: AllVariantsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Toast, Button } from '@arbor-education/design-system.components';
+import { useState } from 'react';
 
-export const LongContent: Story = {
-  args: {
-    variant: 'information',
-    children:
-      'This is a much longer toast message that demonstrates how the component handles extended content. It should wrap appropriately and maintain readability.',
+function AllVariantsDemo() {
+  const [infoOpen, setInfoOpen] = useState(false);
+  const [successOpen, setSuccessOpen] = useState(false);
+  const [warningOpen, setWarningOpen] = useState(false);
+  const [dangerOpen, setDangerOpen] = useState(false);
+
+  return (
+    <Toast.Provider>
+      <Button onClick={() => setInfoOpen(true)}>Information</Button>
+      <Button onClick={() => setSuccessOpen(true)}>Success</Button>
+      <Button onClick={() => setWarningOpen(true)}>Warning</Button>
+      <Button onClick={() => setDangerOpen(true)}>Danger</Button>
+
+      <Toast variant="information" open={infoOpen} onOpenChange={setInfoOpen}>
+        Attendance report generated
+      </Toast>
+      <Toast variant="success" open={successOpen} onOpenChange={setSuccessOpen}>
+        Assessment period saved
+      </Toast>
+      <Toast variant="warning" open={warningOpen} onOpenChange={setWarningOpen}>
+        Session expires in 5 minutes
+      </Toast>
+      <Toast variant="danger" open={dangerOpen} onOpenChange={setDangerOpen}>
+        Failed to save changes — please try again
+      </Toast>
+      <Toast.Viewport />
+    </Toast.Provider>
+  );
+}
+export default AllVariantsDemo;
+`.trim(),
+        },
+      },
+    },
   },
-  render: ToastWrapper,
-};
+  [
+    'All four toast variants. Each has a dedicated icon and colour scheme:',
+    '**information** (ℹ blue) for neutral updates,',
+    '**success** (✓ green) for completed actions,',
+    '**warning** (⚠ amber) for non-blocking cautions,',
+    '**danger** (⚠ red) for failed operations.',
+    'Multiple toasts can be open simultaneously — they stack in the viewport.',
+  ].join(' '),
+);
 
-export const MultipleToasts: Story = {
-  render: () => {
-    const [infoOpen, setInfoOpen] = useState(false);
-    const [successOpen, setSuccessOpen] = useState(false);
-    const [warningOpen, setWarningOpen] = useState(false);
-    const [dangerOpen, setDangerOpen] = useState(false);
-
-    return (
-      <Toast.Provider>
-        <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
-          <Button onClick={() => setInfoOpen(true)}>Open Info</Button>
-          <Button onClick={() => setSuccessOpen(true)}>Open Success</Button>
-          <Button onClick={() => setWarningOpen(true)}>Open Warning</Button>
-          <Button onClick={() => setDangerOpen(true)}>Open Danger</Button>
-        </div>
-        <Toast variant="information" open={infoOpen} onOpenChange={setInfoOpen}>
-          Information message
-        </Toast>
-        <Toast variant="success" open={successOpen} onOpenChange={setSuccessOpen}>
-          Success message
-        </Toast>
-        <Toast variant="warning" open={warningOpen} onOpenChange={setWarningOpen}>
-          Warning message
-        </Toast>
-        <Toast variant="danger" open={dangerOpen} onOpenChange={setDangerOpen}>
-          Error message
-        </Toast>
-        <Toast.Viewport />
-      </Toast.Provider>
-    );
+export const ContentGuidelines: Story = withDescription(
+  {
+    render: ContentGuidelinesTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+// ✅ Ideal — 1 line, past tense, no trailing punctuation
+<Toast variant="success" open={open} onOpenChange={setOpen}>
+  Assessment period saved
+</Toast>
+
+// ✅ Acceptable — 2 lines with brief context
+<Toast variant="success" open={open} onOpenChange={setOpen}>
+  Assessment period saved. Pupils can now submit work for grading.
+</Toast>
+
+// ❌ Too long — switch to a Banner instead
+<Toast variant="information" open={open} onOpenChange={setOpen}>
+  Assessment period saved. Pupils can now submit work for grading.
+  Remember to notify your department heads and check the term dates
+  align with your reporting schedule before the deadline.
+</Toast>
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Toast messages should be **1 line ideally, 2 lines maximum**.',
+    'If your message needs more space, use a `Banner` component instead.',
+    'Keep copy short, past-tense where possible, and without trailing punctuation on single-sentence messages.',
+    'Trigger each button to compare how different content lengths look in practice.',
+  ].join(' '),
+);
 
-export default meta;
+export const WithCustomDuration: Story = withDescription(
+  {
+    render: WithCustomDurationTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Toast, Button } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+function CustomDurationDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Toast.Provider>
+      <Button onClick={() => setOpen(true)}>Show toast</Button>
+
+      {/* Per-toast duration overrides the provider default (5000ms) */}
+      <Toast variant="information" open={open} onOpenChange={setOpen} duration={10000}>
+        This stays visible for 10 seconds
+      </Toast>
+
+      {/* Pass Infinity to keep the toast open until manually dismissed */}
+      {/* <Toast duration={Infinity}>Persistent until closed</Toast> */}
+
+      <Toast.Viewport />
+    </Toast.Provider>
+  );
+}
+export default CustomDurationDemo;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The `duration` prop controls how long the toast stays visible before auto-dismissing.',
+    'It defaults to 5000 ms (5 seconds), inherited from `Toast.Provider`.',
+    'Override per-toast by passing `duration` directly.',
+    'Pass `duration={Infinity}` to keep the toast open until the user explicitly dismisses it.',
+  ].join(' '),
+);