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

package/src/components/toggle/Toggle.stories.tsx

@@ -1,39 +1,129 @@
 import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { fn } from 'storybook/test';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
 import { Toggle } from './Toggle';
 
-/**
- * The Toggle component is a binary on/off switch, built on top of Radix UI's
- * Switch primitive. Think of it like the light switch in the St. Olaf town
- * hall — everyone in town knows exactly whether the lights are on or off,
- * and there is never any confusion about which state you are in.
- *
- * Toggling is the right choice when you need an immediate, binary setting
- * change — "dark mode on", "notifications off", "feature enabled". Unlike a
- * checkbox, a toggle implies the change takes effect right away, without
- * needing a form submission.
- *
- * **Accessibility**
- * - Rendered as a `<button role="switch">` — screen readers announce the
- *   current state ("checked" / "not checked") automatically.
- * - Fully keyboard accessible: `Space` or `Enter` toggles the state.
- * - Associate a visible label with the toggle using a `<label htmlFor={id}>`
- *   so users of all abilities know what they are toggling.
- * - The `disabled` prop renders the element as non-interactive and applies
- *   correct ARIA semantics.
- *
- * **CSS classes**
- * - Root element: `ds-toggle`
- * - Thumb (the sliding dot): `ds-toggle__thumb`
- * - Checked state is driven by Radix's `data-state="checked"` attribute,
- *   which the SCSS uses to apply brand colours and shift the thumb position.
- */
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Toggle is an immediate binary on/off switch built on',
+  '[Radix UI Switch](https://www.radix-ui.com/primitives/docs/components/switch).',
+  'It communicates that a change takes effect instantly — without a form submission — making it the right',
+  'choice for settings toggles, feature flags, and preference switches.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Immediate settings** — when flipping a switch takes effect right now (dark mode, notifications, feature enabled)',
+  '- **Binary state** — exactly two options: on and off, enabled and disabled',
+  '- **Standalone settings pages** — outside a form, where pressing Submit before seeing the effect would be jarring',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Choice requires confirmation before taking effect | [`CheckboxInput`](?path=/docs/components-formfield-inputs-checkbox--docs) inside a form |',
+  '| Multiple related on/off items in a list | `CheckboxInput` group — clearer visual grouping |',
+  '| Part of a multi-field form submission | `CheckboxInput` — toggle implies instant action, not deferred submission |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Always provide a visible label.** Toggle renders as a styled button with no visible text. Without a',
+  '`<label htmlFor={id}>`, sighted users see a switch with no explanation of what it controls. Screen',
+  'readers announce the state ("checked" / "not checked") but cannot convey the meaning without a label.',
+  '',
+  '**`checked` vs `defaultChecked`.** Use `defaultChecked` for uncontrolled usage where the component',
+  'manages its own state after mount. Use `checked` + `onCheckedChange` for controlled mode when you need',
+  'to read the value elsewhere in the UI or sync with external state.',
+  '',
+  '**`onCheckedChange` receives a boolean — not an event.** Unlike native checkbox `onChange`, this',
+  'callback receives the new boolean value directly: `(checked: boolean) => void`. No `event.target.checked`',
+  'unwrapping needed.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Rendered as `<button role="switch">` — screen readers announce "checked" / "not checked" automatically',
+  '- Fully keyboard accessible: `Space` or `Enter` toggles the state',
+  '- Associate with `<label htmlFor={id}>` — clicking the label also toggles the switch (larger tap target)',
+  '- The `disabled` prop renders the element as truly non-interactive with correct ARIA semantics',
+  '',
+  '---',
+  '',
+  '### Design tokens used',
+  '',
+  '| Token | Usage |',
+  '|---|---|',
+  '| `--toggle-off-default-color-background` | Track background (unchecked) |',
+  '| `--toggle-on-default-color-background` | Track background (checked — brand colour) |',
+  '| `--toggle-off-disabled-color-background` | Track background (disabled) |',
+  '| `--toggle-radius` | Track border radius |',
+  '| `--toggle-weight-border` | Track border weight |',
+  '| `--border-radius-round` | Thumb shape (circular) |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[CheckboxInput](?path=/docs/components-formfield-inputs-checkbox--docs) · [FormField](?path=/docs/components-formfield--docs) · [RadioButtonInput](?path=/docs/components-formfield-inputs-radio--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 ToggleDocsPage() {
+  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/Toggle',
   component: Toggle,
   parameters: {
     layout: 'centered',
+    docs: {
+      page: ToggleDocsPage,
+    },
   },
   tags: ['autodocs'],
   args: {
@@ -42,45 +132,82 @@ const meta = {
   argTypes: {
     checked: {
       control: 'boolean',
-      description:
-        'Controls the checked state when used as a controlled component. '
-        + 'Pair with `onCheckedChange` to keep your state in sync.',
+      description: [
+        'Controls the checked state when used as a controlled component.',
+        'Pair with `onCheckedChange` to keep your state in sync.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     defaultChecked: {
       control: 'boolean',
-      description:
-        'Sets the initial checked state for an uncontrolled toggle. '
-        + 'The component manages its own state after mount.',
+      description: [
+        'Sets the initial checked state for an uncontrolled toggle.',
+        'The component manages its own state after mount.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     disabled: {
       control: 'boolean',
-      description:
-        'Disables the toggle. The toggle becomes non-interactive and is '
-        + 'visually dimmed. Useful for read-only settings or permission-gated features.',
+      description: [
+        'Disables the toggle. The toggle becomes non-interactive and is visually dimmed.',
+        'Useful for read-only settings or permission-gated features.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     required: {
       control: 'boolean',
-      description:
-        'Marks the toggle as required when used inside a `<form>`. '
-        + 'Prevents form submission if the toggle is unchecked.',
+      description: [
+        'Marks the toggle as required when used inside a `<form>`.',
+        'Prevents form submission if the toggle is unchecked.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     name: {
       control: 'text',
-      description:
-        'The name of the toggle as submitted with form data. '
-        + 'Works the same as the `name` attribute on a native `<input>`.',
+      description: [
+        'The name of the toggle as submitted with form data.',
+        'Works the same as the `name` attribute on a native `<input>`.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     value: {
       control: 'text',
-      description:
-        'The value submitted with form data when the toggle is checked. '
-        + 'Defaults to `"on"` (matching native checkbox behaviour).',
+      description: [
+        'The value submitted with form data when the toggle is checked.',
+        'Defaults to `"on"` (matching native checkbox behaviour).',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: '"on"' },
+      },
     },
     onCheckedChange: {
       action: 'checkedChange',
-      description:
-        'Callback fired whenever the checked state changes. '
-        + 'Receives the new boolean value: `(checked: boolean) => void`.',
+      control: false,
+      description: [
+        'Callback fired whenever the checked state changes.',
+        'Receives the new boolean value directly: `(checked: boolean) => void`.',
+        'Unlike native checkbox `onChange`, there is no event object to unwrap.',
+      ].join(' '),
+      table: {
+        type: { summary: '(checked: boolean) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
   },
 } satisfies Meta<typeof Toggle>;
@@ -89,71 +216,26 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 // ---------------------------------------------------------------------------
-// Basic states
-// ---------------------------------------------------------------------------
-
-/** The toggle in its default, unchecked (off) state. */
-export const Default: Story = {};
-
-/**
- * The toggle in its checked (on) state.
- *
- * Uses `defaultChecked` so the component manages its own state — perfect for
- * uncontrolled usage where you just need a sensible starting position.
- */
-export const Checked: Story = {
-  args: {
-    defaultChecked: true,
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Disabled states
+// Helper
 // ---------------------------------------------------------------------------
 
-/**
- * A disabled toggle that is currently off.
- *
- * Use this when a setting exists but cannot be changed in the current context
- * — for example, a feature that requires a higher subscription tier.
- */
-export const Disabled: Story = {
-  args: {
-    disabled: true,
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
   },
-};
-
-/**
- * A disabled toggle that is currently on.
- *
- * This communicates "this setting is enabled, but you cannot change it right
- * now." Always pair a disabled toggle with a tooltip or helper text that
- * explains why it cannot be interacted with.
- */
-export const DisabledChecked: Story = {
-  args: {
-    defaultChecked: true,
-    disabled: true,
-  },
-};
+});
 
 // ---------------------------------------------------------------------------
-// Controlled usage
+// Templates
 // ---------------------------------------------------------------------------
 
-/**
- * A fully controlled toggle backed by React state.
- *
- * Back in St. Olaf, my neighbour Hildegard Bjornsson kept a hand-written
- * ledger of every switch in her house — she never trusted a switch to remember
- * its own state! A controlled toggle is just like that ledger: your component
- * owns the truth, and the toggle simply displays what you tell it to.
- *
- * Use the controlled pattern when:
- * - You need to read the toggle state elsewhere in the UI.
- * - You want to conditionally show/hide other elements based on the state.
- * - You are submitting state as part of a larger form payload.
- */
 const ControlledTemplate = (args: React.ComponentProps<typeof Toggle>) => {
   const [enabled, setEnabled] = useState(false);
 
@@ -163,7 +245,7 @@ const ControlledTemplate = (args: React.ComponentProps<typeof Toggle>) => {
         display: 'flex',
         flexDirection: 'column',
         alignItems: 'center',
-        gap: '12px',
+        gap: 'var(--spacing-small)',
       }}
     >
       <Toggle
@@ -177,7 +259,7 @@ const ControlledTemplate = (args: React.ComponentProps<typeof Toggle>) => {
       <p
         style={{
           margin: 0,
-          fontSize: '14px',
+          fontSize: 'var(--font-size-2-13)',
           color: enabled ? 'var(--color-brand-700)' : 'var(--color-grey-500)',
         }}
       >
@@ -187,34 +269,17 @@ const ControlledTemplate = (args: React.ComponentProps<typeof Toggle>) => {
   );
 };
 
-export const Controlled: Story = {
-  render: ControlledTemplate,
-};
-
-// ---------------------------------------------------------------------------
-// With label (accessible usage)
-// ---------------------------------------------------------------------------
-
-/**
- * A toggle paired with a visible `<label>` element for full accessibility.
- *
- * This is the pattern you should reach for in almost every real-world use
- * case. By wiring the label's `htmlFor` to the toggle's `id`, you get:
- *
- * - Screen readers announce both the label text and the toggle state.
- * - Clicking the label text also toggles the switch (larger click target).
- * - Visual users see a clear description of what the toggle controls.
- *
- * You know, this is a lot like what we learned in St. Olaf Home Economics
- * class — always label your preserves. An unlabelled jar of lingonberry jam
- * looks just like an unlabelled jar of beet relish, and nobody wants that
- * confusion at the dinner table. Or on a settings page!
- */
 const WithLabelTemplate = (args: React.ComponentProps<typeof Toggle>) => {
   const [enabled, setEnabled] = useState(false);
 
   return (
-    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--spacing-xsmall)',
+      }}
+    >
       <Toggle
         {...args}
         id="email-notifications-toggle"
@@ -226,7 +291,11 @@ const WithLabelTemplate = (args: React.ComponentProps<typeof Toggle>) => {
       />
       <label
         htmlFor="email-notifications-toggle"
-        style={{ fontSize: '14px', cursor: 'pointer', userSelect: 'none' }}
+        style={{
+          fontSize: 'var(--font-size-2-13)',
+          cursor: 'pointer',
+          userSelect: 'none',
+        }}
       >
         Email notifications
       </label>
@@ -234,6 +303,173 @@ const WithLabelTemplate = (args: React.ComponentProps<typeof Toggle>) => {
   );
 };
 
-export const WithLabel: Story = {
-  render: WithLabelTemplate,
-};
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    render: args => <Toggle {...args} />,
+  },
+  'The toggle in its default, unchecked (off) state. Use the Controls panel to flip `checked`, `defaultChecked`, `disabled`, and other props.',
+);
+
+export const Checked: Story = withDescription(
+  {
+    args: {
+      defaultChecked: true,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Toggle } from '@arbor-education/design-system.components';
+
+function EnabledByDefaultToggle() {
+  return <Toggle defaultChecked />;
+}
+export default EnabledByDefaultToggle;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The toggle in its checked (on) state. Uses `defaultChecked` for uncontrolled usage — the component manages its own state after mount.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    args: {
+      disabled: true,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Toggle } from '@arbor-education/design-system.components';
+
+function DisabledToggle() {
+  return <Toggle disabled />;
+}
+export default DisabledToggle;
+`.trim(),
+        },
+      },
+    },
+  },
+  'A disabled toggle in the off state. Use when a setting exists but cannot currently be changed — for example, a feature that requires a higher subscription tier.',
+);
+
+export const DisabledChecked: Story = withDescription(
+  {
+    args: {
+      defaultChecked: true,
+      disabled: true,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Toggle } from '@arbor-education/design-system.components';
+
+function DisabledCheckedToggle() {
+  return <Toggle defaultChecked disabled />;
+}
+export default DisabledCheckedToggle;
+`.trim(),
+        },
+      },
+    },
+  },
+  'A disabled toggle in the on state. This communicates "this setting is enabled, but you cannot change it right now." Always pair a disabled toggle with a tooltip or helper text explaining why it is locked.',
+);
+
+export const Controlled: Story = withDescription(
+  {
+    render: ControlledTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Toggle } from '@arbor-education/design-system.components';
+
+function ControlledToggle() {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <Toggle
+        checked={enabled}
+        onCheckedChange={setEnabled}
+      />
+      <p style={{ margin: 0 }}>
+        {enabled ? 'Feature enabled' : 'Feature disabled'}
+      </p>
+    </div>
+  );
+}
+export default ControlledToggle;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A fully controlled toggle backed by React state.',
+    'Use the controlled pattern when you need to read the toggle state elsewhere in the UI, conditionally',
+    'show or hide other elements, or include the state in a larger form payload.',
+  ].join(' '),
+);
+
+export const WithLabel: Story = withDescription(
+  {
+    render: WithLabelTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Toggle } from '@arbor-education/design-system.components';
+
+function ToggleWithLabel() {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-xsmall)' }}>
+      <Toggle
+        id="email-notifications-toggle"
+        checked={enabled}
+        onCheckedChange={setEnabled}
+      />
+      <label
+        htmlFor="email-notifications-toggle"
+        style={{ cursor: 'pointer', userSelect: 'none' }}
+      >
+        Email notifications
+      </label>
+    </div>
+  );
+}
+export default ToggleWithLabel;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A toggle paired with a visible `<label>` element for full accessibility.',
+    'Wiring `htmlFor` on the label to the toggle\'s `id` means screen readers announce both the label text and',
+    'the toggle state, and clicking the label also toggles the switch — giving a larger tap target for all users.',
+  ].join(' '),
+);