@arbor-education/design-system.components 0.13.0 → 0.14.0

package/src/components/progress/Progress.stories.tsx

@@ -1,90 +1,657 @@
 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 { useEffect, useState } from 'react';
+import { Button } from 'Components/button/Button';
 import { Progress } from './Progress';
 
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Progress is a horizontal progress bar for measurable operations — it fills from left to right as a',
+  'known quantity advances toward a known total. Built on [Radix UI Progress](https://www.radix-ui.com/primitives/docs/components/progress)',
+  'for reliable ARIA semantics.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **File uploads and imports** — "3 of 5 files uploaded", where the total count is known',
+  '- **Multi-step wizards** — completed steps out of total steps',
+  '- **Long-running operations** — any process where progress is calculable and meaningful to show',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Unknown-duration operation | Spinner (Icon `name="loader"` with CSS animation) or estimate a `value` |',
+  '| Full page / section loading placeholder | Skeleton |',
+  '| Operation completed message | [`Banner`](?path=/docs/components-banner--docs) (success state) or [`Toast`](?path=/docs/components-toast--docs) (transient) |',
+  '| Decorative loading bar without a value | Do not — violates WCAG 2.1 4.1.2 |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`aria-label` or `aria-labelledby` is REQUIRED.** Radix renders `role="progressbar"` — a progressbar',
+  'with no accessible name is a WCAG 2.1 failure (4.1.2 Name, Role, Value). Always pass one of these.',
+  '',
+  '**Width is 100% of parent.** Never size `<Progress>` directly. Put a width or `maxWidth` on the',
+  'wrapper element and let Progress fill it.',
+  '',
+  '**Pass raw values, not percentages.** If you have "3 of 5 items", pass `value={3}` and `max={5}` —',
+  'the component calculates the percentage internally. Do not pre-calculate to `value={60}` and `max={100}`.',
+  '',
+  '**`value={null}` does NOT produce a visible indeterminate animation.** Radix will set',
+  '`data-state="indeterminate"` on the root, but this component has no CSS animation defined for that',
+  'state — the indicator bar just disappears. See the IndeterminateAntiPattern story. Use a Spinner instead.',
+  '',
+  '**Built on [Radix UI Progress](https://www.radix-ui.com/primitives/docs/components/progress).** Props not listed above are passed through to the Radix primitive — see the Radix docs for the full API.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- `aria-label` (or `aria-labelledby` pointing to a visible element) is required on every Progress',
+  '- `getValueLabel` shapes the screen-reader announcement — it becomes `aria-valuetext`. Without it,',
+  '  Radix falls back to a rounded percentage string (e.g. `"50%"`). Provide a custom function when you',
+  '  need a fuller sentence, e.g. `(v, m) => v + " of " + m + " files uploaded"`.',
+  '- Radix auto-manages `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext`.',
+  '  Do not set these yourself.',
+  '- Colour alone is not sufficient — always pair the bar with a visible label showing the value or percentage.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Progress } from '@arbor-education/design-system.components';",
+  '',
+  'function MyProgress(props: Progress.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `Progress.Props` | Full props interface |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Banner](?path=/docs/components-banner--docs) · [Toast](?path=/docs/components-toast--docs) · [Icon](?path=/docs/components-icon--docs) · [Badge](?path=/docs/components-badge--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.';
+
+function ProgressDocsPage() {
+  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/Progress',
   component: Progress,
   parameters: {
-    layout: 'centered',
+    layout: 'padded',
+    docs: {
+      page: ProgressDocsPage,
+    },
   },
   tags: ['autodocs'],
-  args: {
-    'aria-label': 'Progress bar',
-  },
   argTypes: {
-    value: {
+    'value': {
       control: { type: 'number', min: 0, max: 100 },
-      description: 'Current progress value',
+      description: [
+        'Current progress value. Defaults to `0`.',
+        'Pass `null` only if you provide a custom animated `indicatorClassName` for an indeterminate state',
+        '— see the IndeterminateAntiPattern story for why bare `null` does nothing visible.',
+      ].join(' '),
+      table: {
+        type: { summary: 'number | null' },
+        defaultValue: { summary: '0' },
+      },
+    },
+    'max': {
+      control: { type: 'number', min: 1 },
+      description: [
+        'Denominator for the progress calculation. Progress calculates the percentage internally',
+        '— pass raw values, not percentages. Defaults to `100`.',
+      ].join(' '),
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: '100' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: [
+        '**Required** (unless `aria-labelledby` is provided).',
+        'A progressbar with no accessible name fails WCAG 2.1 (4.1.2 Name, Role, Value).',
+        'Use `aria-labelledby` instead when a visible label element exists in the DOM.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'getValueLabel': {
+      control: false,
+      description: [
+        'Function that returns the string announced by screen readers as `aria-valuetext`.',
+        'Without it, Radix falls back to a rounded percentage string (e.g. `"50%"`).',
+        'Provide a custom function for a fuller sentence, e.g. `(v, m) => v + " of " + m + " files uploaded"`.',
+      ].join(' '),
+      table: {
+        type: { summary: '(value: number, max: number) => string' },
+        defaultValue: { summary: 'Radix default (rounded percentage, e.g. "50%")' },
+      },
+    },
+    'indicatorClassName': {
+      control: 'text',
+      description: [
+        'Escape hatch for styling the moving indicator bar. Rarely needed.',
+        'Pass a CSS class to override colours, add animations, or customise the indeterminate state.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "''" },
+      },
     },
-    max: {
-      control: 'number',
-      description: 'Maximum progress value',
+    'className': {
+      control: false,
+      description: 'Additional CSS class names on the root progress element. Use sparingly.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "''" },
+      },
     },
   },
-  decorators: [
-    Story => (
-      <div style={{ width: '400px' }}>
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Progress>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+// Use StoryObj<typeof Progress> (not typeof meta) so render-only stories are
+// not forced to provide required args — template components handle their own instances.
+type Story = StoryObj<typeof Progress>;
 
-// Default progress
-export const Default: Story = {
-  args: {
-    value: 50,
-    max: 100,
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
   },
+});
+
+// ---------------------------------------------------------------------------
+// Template components for composition and stateful stories.
+// Named components avoid react-hooks lint issues — the react-hooks ESLint
+// plugin is NOT configured in this project, so do NOT add eslint-disable.
+// ---------------------------------------------------------------------------
+
+const AllStopsTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+      maxWidth: '60%',
+    }}
+  >
+    {([0, 25, 50, 75, 100] as const).map(stop => (
+      <div
+        key={stop}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--spacing-xsmall)',
+        }}
+      >
+        <span
+          className="ds-text"
+          style={{
+            color: 'var(--color-grey-600)',
+            minWidth: '4rem',
+            flexShrink: 0,
+          }}
+        >
+          {stop}
+          {' '}
+          / 100
+        </span>
+        <div style={{ flex: 1 }}>
+          <Progress
+            value={stop}
+            max={100}
+            aria-label={`${stop}% complete`}
+          />
+        </div>
+      </div>
+    ))}
+  </div>
+);
+
+const InteractiveLoadingTemplate = (args: React.ComponentProps<typeof Progress>) => {
+  const [progress, setProgress] = useState(0);
+  const [running, setRunning] = useState(true);
+
+  useEffect(() => {
+    if (!running) return;
+    if (progress >= 100) {
+      setRunning(false);
+      return;
+    }
+    const id = setInterval(() => {
+      setProgress((prev) => {
+        const next = prev + 2;
+        if (next >= 100) {
+          clearInterval(id);
+          setRunning(false);
+          return 100;
+        }
+        return next;
+      });
+    }, 60);
+    return () => clearInterval(id);
+  }, [running, progress]);
+
+  const handleReset = () => {
+    setProgress(0);
+    setRunning(true);
+  };
+
+  return (
+    <div
+      style={{
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+        maxWidth: '60%',
+      }}
+    >
+      <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+        File import progress
+      </span>
+      <Progress
+        {...args}
+        value={progress}
+        max={100}
+        aria-label="File import progress"
+        getValueLabel={v => `${v}% complete`}
+      />
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <span className="ds-text" style={{ color: 'var(--color-grey-600)' }}>
+          {progress}
+          % complete
+        </span>
+        {!running && (
+          <Button variant="secondary" size="S" onClick={handleReset}>
+            Reset
+          </Button>
+        )}
+      </div>
+    </div>
+  );
 };
 
-// Empty progress
-export const Empty: Story = {
-  args: {
-    value: 0,
-    max: 100,
+const WithAccessibleLabelTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-xlarge)',
+      maxWidth: '60%',
+    }}
+  >
+    {/* Without getValueLabel */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Without getValueLabel — screen reader announces Radix&apos;s default (a rounded percentage, e.g. &ldquo;65%&rdquo;)
+      </p>
+      <Progress
+        value={65}
+        max={100}
+        aria-label="Upload progress"
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        Screen reader: "Upload progress, 65%"
+      </p>
+    </div>
+    {/* With getValueLabel */}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-semantic-success-600)' }}>
+        With getValueLabel — screen reader announces a full sentence
+      </p>
+      <Progress
+        value={65}
+        max={100}
+        aria-label="Upload progress"
+        getValueLabel={v => `${v}% uploaded`}
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        Screen reader: "Upload progress, 65% uploaded"
+      </p>
+    </div>
+  </div>
+);
+
+const IndeterminateAntiPatternTemplate = () => (
+  <div
+    style={{
+      padding: 'var(--spacing-xlarge)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+      maxWidth: '60%',
+    }}
+  >
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-semantic-destructive-600)' }}>
+      The blank bar below is the ACTUAL render of value=null — this is what NOT to do
+    </p>
+    {/* value={null} causes Number(null) = 0, translateX(-100%), indicator invisible */}
+    <Progress
+      value={null}
+      max={100}
+      aria-label="Assessment marksheet export"
+    />
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      The indicator bar has translated fully out of view. No animation plays. The user sees nothing.
+    </p>
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      For unknown-duration operations, use a Spinner (Icon with name="loader" and a CSS rotation
+      animation) or set an approximate value so the bar is at least partially visible.
+    </p>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      'value': 50,
+      'max': 100,
+      'aria-label': 'Page loading',
+    },
+    render: args => <Progress {...args} />,
   },
-};
+  [
+    'The interactive canvas — every prop is wired to the Controls panel below.',
+    'Adjust `value` and `max` to see the bar move. Control the width by sizing the parent container',
+    '— Progress fills 100% of its parent, so the wrapper\'s `maxWidth` is what you control.',
+  ].join(' '),
+);
+
+export const AllStops: Story = withDescription(
+  {
+    render: AllStopsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Progress } from '@arbor-education/design-system.components';
 
-// Quarter progress
-export const Quarter: Story = {
-  args: {
-    value: 25,
-    max: 100,
+function AllStopsExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', maxWidth: '60%', padding: 'var(--spacing-xlarge)' }}>
+      <Progress value={0}   max={100} aria-label="0% complete" />
+      <Progress value={25}  max={100} aria-label="25% complete" />
+      <Progress value={50}  max={100} aria-label="50% complete" />
+      <Progress value={75}  max={100} aria-label="75% complete" />
+      <Progress value={100} max={100} aria-label="100% complete" />
+    </div>
+  );
+}
+export default AllStopsExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'All five canonical stops — 0, 25, 50, 75, and 100 — rendered side by side for visual reference.',
+    'Each bar has an `aria-label` describing its completion percentage.',
+    'The "0 / 100" bar shows that an empty state is a valid initial render, not a missing or broken component.',
+  ].join(' '),
+);
 
-// Half progress
-export const Half: Story = {
-  args: {
-    value: 50,
-    max: 100,
+export const CustomMax: Story = withDescription(
+  {
+    args: {
+      'value': 30,
+      'max': 50,
+      'aria-label': 'Assessment sections completed',
+      'getValueLabel': (v: number, m: number) => `${v} of ${m}`,
+    },
+    render: args => (
+      <div style={{ maxWidth: '60%', padding: 'var(--spacing-xlarge)' }}>
+        <Progress {...args} />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Progress } from '@arbor-education/design-system.components';
+
+// Pass raw values — Progress calculates the percentage internally.
+// value={30} max={50} renders a 60% filled bar.
+function CustomMaxExample() {
+  return (
+    <Progress
+      value={30}
+      max={50}
+      aria-label="Assessment sections completed"
+      getValueLabel={(v, m) => \`\${v} of \${m}\`}
+    />
+  );
+}
+export default CustomMaxExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'When your total is not 100, set `max` to the real denominator and `value` to the raw count.',
+    'Here `value={30}` and `max={50}` — Progress renders a 60% filled bar without you calculating anything.',
+    'The `getValueLabel` prop shapes the screen-reader announcement — `(v, m) => v + " of " + m` produces',
+    '"30 of 50" as `aria-valuetext` instead of just the raw percentage.',
+  ].join(' '),
+);
 
-// Three quarters progress
-export const ThreeQuarters: Story = {
-  args: {
-    value: 75,
-    max: 100,
+export const InteractiveLoading: Story = withDescription(
+  {
+    render: InteractiveLoadingTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useEffect, useState } from 'react';
+import { Button, Progress } from '@arbor-education/design-system.components';
+
+function FileImportProgress() {
+  const [progress, setProgress] = useState(0);
+  const [running, setRunning] = useState(true);
+
+  useEffect(() => {
+    if (!running) return;
+    if (progress >= 100) { setRunning(false); return; }
+    const id = setInterval(() => {
+      setProgress((prev) => {
+        const next = prev + 2;
+        if (next >= 100) { clearInterval(id); setRunning(false); return 100; }
+        return next;
+      });
+    }, 60);
+    return () => clearInterval(id);
+  }, [running, progress]);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', maxWidth: '60%' }}>
+      <span>File import progress</span>
+      <Progress
+        value={progress}
+        max={100}
+        aria-label="File import progress"
+        getValueLabel={v => \`\${v}% complete\`}
+      />
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+        <span>{progress}% complete</span>
+        {!running && (
+          <Button variant="secondary" size="S" onClick={() => { setProgress(0); setRunning(true); }}>
+            Reset
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+export default FileImportProgress;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'A timed simulation of a file import: 0 → 100% over ~3 seconds using `setInterval` in a',
+    'named template component (the react-hooks ESLint plugin is not configured here, so hooks inside',
+    'a named component are used directly without disable comments).',
+    'The Reset button reruns the animation. `getValueLabel` returns a richer phrase (e.g. "42% complete")',
+    'instead of Radix\'s default rounded-percentage string on each `aria-valuenow` update.',
+    'In a real import, drive `value` from an API polling response — never fake it like this demo.',
+  ].join(' '),
+);
+
+export const WithAccessibleLabel: Story = withDescription(
+  {
+    render: WithAccessibleLabelTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Progress } from '@arbor-education/design-system.components';
 
-// Complete progress
-export const Complete: Story = {
-  args: {
-    value: 100,
-    max: 100,
+function WithAccessibleLabelExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)', maxWidth: '60%', padding: 'var(--spacing-xlarge)' }}>
+      {/* Without getValueLabel — screen reader announces Radix's default (rounded %) */}
+      <Progress value={65} max={100} aria-label="Upload progress" />
+      {/* With getValueLabel — screen reader announces a full sentence via aria-valuetext */}
+      <Progress
+        value={65}
+        max={100}
+        aria-label="Upload progress"
+        getValueLabel={v => \`\${v}% uploaded\`}
+      />
+    </div>
+  );
+}
+export default WithAccessibleLabelExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Side-by-side contrast: the top bar has only `aria-label` — screen readers announce the raw Radix',
+    'default (the percentage as a number). The bottom bar adds `getValueLabel` returning "65% uploaded",',
+    'which populates `aria-valuetext` and gives a screen reader a complete sentence.',
+    'Inspect the DOM to see `aria-valuetext` populated on the lower bar — it will read "65% uploaded"',
+    'rather than "65".',
+  ].join(' '),
+);
+
+export const IndeterminateAntiPattern: Story = withDescription(
+  {
+    render: IndeterminateAntiPatternTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Progress } from '@arbor-education/design-system.components';
 
-// Custom max value
-export const CustomMax: Story = {
-  args: {
-    value: 30,
-    max: 50,
+function IndeterminateAntiPatternExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', maxWidth: '60%', padding: 'var(--spacing-xlarge)' }}>
+      {/* ⚠️ ANTI-PATTERN — value={null} does NOT produce an indeterminate animation. */}
+      {/* Number(null) = 0, so the indicator bar translates fully off-screen. */}
+      <Progress value={null} max={100} aria-label="Assessment marksheet export" />
+
+      {/* ✅ Or set an approximate value so the bar is at least partially visible: */}
+      <Progress value={50} max={100} aria-label="Assessment marksheet export" />
+    </div>
+  );
+}
+export default IndeterminateAntiPatternExample;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    '**Do not use `value={null}` with this component.** When `value` is `null`,',
+    '`Number(null)` evaluates to `0`, the indicator translates fully off-screen (`translateX(-100%)`),',
+    'and the user sees a blank bar. Radix sets `data-state="indeterminate"` on the root element,',
+    'but this component has NO animation CSS defined for that state.',
+    '',
+    'The blank bar in this story IS the actual render — it is not a Storybook display issue.',
+    '',
+    'For unknown-duration operations, use a Spinner (Icon with `name="loader"` plus a CSS rotation',
+    'animation) or set an approximate `value` so the bar is at least partially visible.',
+    '',
+    'If you genuinely need an animated indeterminate bar, pass a custom `indicatorClassName` with',
+    'a keyframe animation targeting `[data-state="indeterminate"]`.',
+  ].join('\n'),
+);