@arbor-education/design-system.components 0.12.0 → 0.13.1

package/dist/components/formField/inputs/number/NumberInput.stories.js

@@ -1,22 +1,636 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { fn } from 'storybook/test';
+import { useState } from 'react';
+import { FormField } from '../../../formField/FormField';
 import { NumberInput } from './NumberInput';
+// ---------------------------------------------------------------------------
+// Component description — built as joined arrays to avoid no-useless-escape
+// on backtick code spans inside template literals.
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'The **NumberInput** is the precision numeric entry control in the Arbor design system.',
+    'It wraps a native `<input type="text">` element with integrated minus and plus spinner buttons,',
+    'automatic value clamping to `min`/`max` on blur and spinner click, and Decimal.js-powered',
+    'arithmetic to eliminate floating-point drift.',
+].join('\n');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- Numeric data entry where up/down stepping makes sense: attendance counts, exam marks,',
+    '  class sizes, grade percentages, target scores, absence thresholds',
+    '- Fields with a known valid range (use `min`/`max`) — spinners disable automatically at bounds',
+    '- Decimal values that must stay precise — `step={0.1}` with Decimal.js avoids',
+    '  `0.1 + 0.2 = 0.30000000000000004` style drift',
+    '- **Always prefer `FormField` with `inputType="number"`** in real forms — it wires',
+    '  `hasError`, `aria-invalid`, `aria-describedby`, and label association automatically',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Instead of NumberInput... | Use... | Why |',
+    '|---|---|---|',
+    '| Free-form text | [`TextInput`](?path=/docs/components-formfield-inputs-textinput--docs) | No spinners; no clamping; correct semantics |',
+    '| Time values | [`TimeInput`](?path=/docs/components-formfield-inputs-timeinput--docs) | Clock UI, granularity controls, better validation |',
+    '| Large range without stepping | [`TextInput`](?path=/docs/components-formfield-inputs-textinput--docs) with `type="text"` | Spinners add no value for wide-open ranges |',
+    '| Currency with symbol display | Purpose-built currency field | NumberInput does not format currency symbols |',
+    '',
+    '---',
+    '',
+    '### Controlled vs uncontrolled — choose one',
+    '',
+    'NumberInput supports both patterns, but mixing them causes a silent gotcha.',
+    '',
+    '**Uncontrolled** (recommended for most cases): pass `defaultValue` only.',
+    'React will manage the DOM value. The `onChange` prop fires on every change,',
+    'giving you the latest value without needing to drive it from state.',
+    '',
+    '**Controlled**: pass `value` + `onChange`, and do NOT pass `defaultValue`.',
+    'If `defaultValue` is truthy, the component ignores all subsequent `value` prop changes.',
+    'This is an intentional internal guard — the `value` `useEffect` only fires when',
+    '`!defaultValue`. If you start with an empty `defaultValue` and want to drive the',
+    'field from state, use `value` alone.',
+    '',
+    'Never mix both. If you pass `defaultValue="5"` and later push a new `value` prop,',
+    'the new value will be silently ignored after the initial mount.',
+    '',
+    '---',
+    '',
+    '### Spinner bounds behaviour',
+    '',
+    '- The minus button is disabled when `Number(value) <= Number(min)`.',
+    '- The plus button is disabled when `Number(value) >= Number(max)`.',
+    '- Both buttons are disabled when the `disabled` prop is set.',
+    '- **Empty field edge case**: if `min={0}` and the field is empty,',
+    '  `Number(\'\') <= Number(0)` evaluates to `0 <= 0 = true`, so the minus button',
+    '  is disabled even with no value in the field.',
+    '',
+    '---',
+    '',
+    '### Design guidance',
+    '',
+    '- **Width is always 100%** — the container fills its parent. Control width by sizing the wrapper.',
+    '- **Use `FormField` in real forms** — provides label, description, and error message wiring automatically.',
+    '- **Only one height** — unlike TextInput, NumberInput has no size variant. One height fits all contexts.',
+    '- **`disableSpinners` for dense layouts** — removes the spinner buttons for a compact text-entry look,',
+    '  useful in data-grid cells or inline filters where the ± buttons feel too large.',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical gotchas',
+    '',
+    '#### 1. `onChange` fires from `useEffect`, not synchronously',
+    'The component manages an internal `value` state, and `onChange` is called inside a `useEffect`',
+    'that watches that state. This means:',
+    '',
+    '- `onChange` fires asynchronously, after the render in which `value` changed',
+    '- The synthetic event is **manually constructed**: only `e.currentTarget.value` is populated.',
+    '  Accessing `e.target.value` or `e.nativeEvent` will throw or return undefined.',
+    '',
+    '```tsx',
+    '// BAD — e.target.value is undefined in NumberInput\'s onChange',
+    '<NumberInput onChange={(e) => console.log(e.target.value)} />',
+    '',
+    '// GOOD — always use e.currentTarget.value',
+    '<NumberInput onChange={(e) => console.log(e.currentTarget.value)} />',
+    '```',
+    '',
+    '#### 2. `defaultValue` silently blocks `value` prop updates',
+    'If you pass a truthy `defaultValue`, the internal `useEffect` that syncs the `value` prop',
+    'is guarded by `if (!defaultValue)`. After mount, all subsequent `value` prop changes are',
+    'silently ignored.',
+    '',
+    '```tsx',
+    '// BAD — after mount, changes to externalValue are ignored because defaultValue is truthy',
+    '<NumberInput defaultValue="5" value={externalValue} onChange={...} />',
+    '',
+    '// GOOD — controlled: value only, no defaultValue',
+    '<NumberInput value={externalValue} onChange={...} />',
+    '',
+    '// GOOD — uncontrolled: defaultValue only, read via onChange',
+    '<NumberInput defaultValue="5" onChange={...} />',
+    '```',
+    '',
+    '#### 3. Passing `onBlur` silently disables blur-clamping',
+    'The component attaches its own `onBlur` handler (`handleOnBlur`) to the native input for',
+    'min/max clamping. However, `{...rest}` is spread AFTER the internal `onBlur` in the JSX,',
+    'so any `onBlur` prop you pass OVERRIDES the internal handler.',
+    'This silently disables blur-clamping — values will no longer snap to `min`/`max` on focus loss.',
+    'If you need to react to blur events, read the value from `onChange` and apply any validation there,',
+    'or use FormField\'s built-in error state management.',
+    '',
+    '#### 4. `type="text"` not `type="number"` — arrow keys do NOT increment',
+    'NumberInput intentionally uses `type="text"` with `inputMode="numeric"`. This avoids',
+    'browser-native number input quirks (scrollwheel changing values, browser spinner UI competing',
+    'with the custom spinners, inconsistent locale formatting). The trade-off: the up/down arrow',
+    'keys do not increment the value — use the spinner buttons or keyboard-type the value instead.',
+    '',
+    '#### 5. No `forwardRef` — you cannot attach a `ref` to NumberInput',
+    'The component does not use `forwardRef`. If you need to imperatively focus or read the',
+    'DOM input node, this component does not support it. Use a wrapper and focus strategy instead.',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- **Label association** — always wire `id` on the input and `htmlFor` on the label.',
+    '  `FormField` does this automatically; bare NumberInput consumers must do it manually.',
+    '- **Error state** — pair `hasError={true}` with `aria-invalid="true"` and',
+    '  `aria-describedby` pointing to the error message element.',
+    '  `FormField` handles all three automatically when `errorText` is present.',
+    '- **Spinner button labels** — the minus and plus buttons have hardcoded',
+    '  `aria-label="Minus button"` and `aria-label="Plus button"`. These are not customisable.',
+    '- **Disabled state** — `disabled` removes both spinners AND the input from the tab order.',
+    '  Disabled fields are not submitted in forms. Use `readOnly` if you need the value submitted.',
+    '- **No keyboard increment** — because `type="text"` is used, Up/Down arrow keys do not',
+    '  change the value. Screen reader users can still type directly and click spinners.',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '`NumberInput` exports a namespace with the `Props` type:',
+    '',
+    '```tsx',
+    "import { NumberInput } from '@arbor-education/design-system.components';",
+    '',
+    'type Props = NumberInput.Props;',
+    '```',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `NumberInput.Props` | Full props interface — `hasError`, `disableSpinners`, `containerClassName`, plus all `InputHTMLAttributes<HTMLInputElement>` |',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[FormField](?path=/docs/components-formfield--docs)',
+    '· [TextInput](?path=/docs/components-formfield-inputs-textinput--docs)',
+    '· [TimeInput](?path=/docs/components-formfield-inputs-timeinput--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.';
+// ---------------------------------------------------------------------------
+// Custom docs page
+// ---------------------------------------------------------------------------
+function NumberInputDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
-    title: 'Components/FormField/Inputs/Numeric',
+    title: 'Components/FormField/Inputs/NumberInput',
     component: NumberInput,
-};
-export const Default = {
+    tags: ['autodocs'],
     parameters: {
         layout: 'centered',
+        docs: {
+            page: NumberInputDocsPage,
+        },
+    },
+    argTypes: {
+        hasError: {
+            description: [
+                'Applies `ds-number-input__container--error` class, which sets a red border on the container.',
+                'When using NumberInput inside `FormField`, this is set automatically when `errorText` is present',
+                '— do NOT pass it manually in `inputProps`.',
+                'When using bare NumberInput, also pass `aria-invalid="true"` — `hasError` is purely visual',
+                'and carries no ARIA semantics on its own.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        disableSpinners: {
+            description: [
+                'Hides the minus and plus spinner buttons, rendering a plain numeric text input.',
+                'Use in dense layouts such as data-grid cells or inline filters',
+                'where the ± buttons would feel oversized or distracting.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        containerClassName: {
+            description: [
+                'CSS class name applied to the outer container `<div>` (`.ds-number-input__container`).',
+                'Use for layout overrides — width, margin, or positioning tweaks — that should not',
+                'affect the inner input element itself.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        disabled: {
+            description: [
+                'Native HTML disabled attribute. Greys out the container, disables both spinner buttons,',
+                'and removes the input from tab order.',
+                'Prevents all interaction and excludes the value from form submission.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        step: {
+            description: [
+                'Increment/decrement amount applied on each spinner button click.',
+                'Supports decimal values — Decimal.js ensures precision (no floating-point drift).',
+                'Default is `1`. Use `0.1` for percentage or grade steps, `0.5` for half-marks.',
+            ].join(' '),
+            control: 'number',
+            table: {
+                type: { summary: 'number' },
+                defaultValue: { summary: '1' },
+            },
+        },
+        min: {
+            description: [
+                'Minimum allowed value. The minus spinner button is disabled when the current value',
+                'reaches this bound. On blur, any value below `min` is clamped up to `min`.',
+                'Default is `-Infinity` (no lower bound).',
+            ].join(' '),
+            control: 'number',
+            table: {
+                type: { summary: 'number' },
+                defaultValue: { summary: '-Infinity' },
+            },
+        },
+        max: {
+            description: [
+                'Maximum allowed value. The plus spinner button is disabled when the current value',
+                'reaches this bound. On blur, any value above `max` is clamped down to `max`.',
+                'Default is `Infinity` (no upper bound).',
+            ].join(' '),
+            control: 'number',
+            table: {
+                type: { summary: 'number' },
+                defaultValue: { summary: 'Infinity' },
+            },
+        },
+        placeholder: {
+            description: [
+                'Hint text displayed when the field is empty.',
+                'Never use placeholder as the only visible label — it disappears on input.',
+                'Always pair with a visible label or `aria-label`.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        value: {
+            description: [
+                'Controlled value — pair with `onChange` and do NOT also pass `defaultValue`.',
+                'If `defaultValue` is truthy, subsequent `value` prop changes are silently ignored.',
+                'For uncontrolled usage, use `defaultValue` instead.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string | number' },
+            },
+        },
+        defaultValue: {
+            description: [
+                'Uncontrolled initial value. When truthy, all subsequent `value` prop changes are ignored',
+                '— the internal guard is `if (!defaultValue) { setValue(passedValue) }`.',
+                'For controlled usage, omit `defaultValue` entirely and use `value` + `onChange`.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string | number' },
+                defaultValue: { summary: "''" },
+            },
+        },
+        onChange: {
+            description: [
+                'Called via internal `useEffect` when the value changes.',
+                'The synthetic event is manually constructed — ONLY `e.currentTarget.value` is populated.',
+                'Do NOT access `e.target.value` or `e.nativeEvent` — they will be undefined or throw.',
+            ].join(' '),
+            table: {
+                type: { summary: '(e: ChangeEvent<HTMLInputElement>) => void' },
+            },
+        },
+        className: {
+            description: [
+                'CSS class name applied to the inner `<input>` element only (not the container).',
+                'Use `containerClassName` to style the outer wrapper instead.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
     },
-    tags: ['autodocs'],
     args: {
-        defaultValue: '',
+        onChange: fn(),
+    },
+};
+export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: {
+            ...story.parameters?.docs,
+            description: { story: description },
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// Stateful template components
+// Named components avoid hooks-in-callbacks lint issues (react-hooks plugin
+// is NOT configured in this project — do not add eslint-disable comments).
+// ---------------------------------------------------------------------------
+const ControlledInputTemplate = () => {
+    const [attendanceTarget, setAttendanceTarget] = useState('96');
+    return (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Attendance target (%) \u2014 controlled from parent state" }), _jsx(NumberInput, { id: "attendance-target-controlled", "aria-label": "Attendance target percentage", value: attendanceTarget, min: 0, max: 100, step: 1, onChange: e => setAttendanceTarget(e.currentTarget.value) }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: ["Parent state value:", ' ', _jsxs("strong", { children: [attendanceTarget, "%"] })] }), Number(attendanceTarget) < 90 && (_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-destructive-600)', fontSize: 'var(--font-size-2-13)' }, children: "Warning: targets below 90% are below national guidance" })), Number(attendanceTarget) >= 96 && (_jsx("p", { style: { margin: 0, color: 'var(--color-semantic-success-600)', fontSize: 'var(--font-size-2-13)' }, children: "Excellent \u2014 target meets Arbor recommended threshold" }))] }));
+};
+const DecimalStepTemplate = () => {
+    const [weightingA, setWeightingA] = useState('0.4');
+    const [weightingB, setWeightingB] = useState('0.6');
+    const total = weightingA !== '' && weightingB !== ''
+        ? (parseFloat(weightingA || '0') + parseFloat(weightingB || '0')).toFixed(10)
+        : '—';
+    // Show the floating-point problem vs Decimal.js precision
+    const rawJsTotal = (parseFloat(weightingA || '0') + parseFloat(weightingB || '0'));
+    const formattedTotal = isNaN(rawJsTotal) ? '—' : rawJsTotal.toString();
+    return (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Adjust the grade weightings using step=0.1. Both fields use Decimal.js internally for precision." }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "weighting-component-a", style: { color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Component A weighting" }), _jsx(NumberInput, { id: "weighting-component-a", value: weightingA, min: 0, max: 1, step: 0.1, onChange: e => setWeightingA(e.currentTarget.value) })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "weighting-component-b", style: { color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Component B weighting" }), _jsx(NumberInput, { id: "weighting-component-b", value: weightingB, min: 0, max: 1, step: 0.1, onChange: e => setWeightingB(e.currentTarget.value) })] }), _jsxs("div", { style: { padding: 'var(--spacing-small)', background: 'var(--color-grey-050)', borderRadius: 'var(--border-radius-small)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsxs("p", { style: { margin: 0, fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-600)' }, children: ["Native JS addition result:", ' ', _jsx("strong", { style: { fontFamily: 'monospace' }, children: formattedTotal })] }), _jsxs("p", { style: { margin: 0, fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-600)' }, children: ["With Decimal.js (what spinners use):", ' ', _jsx("strong", { style: { fontFamily: 'monospace' }, children: total })] }), _jsx("p", { style: { margin: 0, fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-500)', fontStyle: 'italic' }, children: "Try stepping 0.1 + 0.2 \u2014 native JS gives 0.30000000000000004; Decimal.js gives 0.3" })] })] }));
+};
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    args: {
+        placeholder: 'Enter a number',
         step: 1,
         disabled: false,
         hasError: false,
-        placeholder: 'Enter a number',
-        min: 0,
-        max: 10,
+        disableSpinners: false,
     },
-};
-export default meta;
+    render: args => _jsx(NumberInput, { ...args }),
+}, 'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore the error state, disabled state, spinner visibility, step size, and min/max bounds.');
+export const Disabled = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "absent-count-disabled", style: { color: 'var(--color-grey-400)', fontSize: 'var(--font-size-2-13)' }, children: "Absent pupils (read-only period)" }), _jsx(NumberInput, { id: "absent-count-disabled", defaultValue: 3, min: 0, disabled: true })] }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)', fontStyle: 'italic' }, children: "The attendance register is locked after the submission window closes. Both spinner buttons and the text input are non-interactive." })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: [
+                    "import { NumberInput } from '@arbor-education/design-system.components';",
+                    '',
+                    'function DisabledExample() {',
+                    '  return (',
+                    '    <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-xsmall)" }}>',
+                    '      <label htmlFor="absent-count-disabled" style={{ color: "var(--color-grey-400)", fontSize: "var(--font-size-2-13)" }}>',
+                    '        Absent pupils (read-only period)',
+                    '      </label>',
+                    '      <NumberInput',
+                    '        id="absent-count-disabled"',
+                    '        defaultValue={3}',
+                    '        min={0}',
+                    '        disabled',
+                    '      />',
+                    '    </div>',
+                    '  );',
+                    '}',
+                    'export default DisabledExample;',
+                ].join('\n'),
+            },
+        },
+    },
+}, '`disabled={true}` applies `ds-number-input__container--disabled` to the container, greys out all elements, and disables both spinner buttons. The input is removed from the tab order and its value is excluded from form submission. Use this after a register submission window closes, or when a field depends on a condition that has not been met.');
+export const WithError = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "exam-mark-error", style: { color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Exam mark out of 100" }), _jsx(NumberInput, { id: "exam-mark-error", defaultValue: 150, min: 0, max: 100, hasError: true, "aria-invalid": "true", "aria-describedby": "exam-mark-error-msg" }), _jsx("span", { id: "exam-mark-error-msg", style: { color: 'var(--color-semantic-destructive-600)', fontSize: 'var(--font-size-1-11)' }, children: "Mark must be between 0 and 100" })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: [
+                    "import { NumberInput } from '@arbor-education/design-system.components';",
+                    '',
+                    'function WithErrorExample() {',
+                    '  return (',
+                    '    <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-xsmall)" }}>',
+                    '      <label htmlFor="exam-mark-error" style={{ color: "var(--color-grey-600)", fontSize: "var(--font-size-2-13)" }}>',
+                    '        Exam mark out of 100',
+                    '      </label>',
+                    '      <NumberInput',
+                    '        id="exam-mark-error"',
+                    '        defaultValue={150}',
+                    '        min={0}',
+                    '        max={100}',
+                    '        hasError',
+                    '        aria-invalid="true"',
+                    '        aria-describedby="exam-mark-error-msg"',
+                    '      />',
+                    '      <span',
+                    '        id="exam-mark-error-msg"',
+                    '        style={{ color: "var(--color-semantic-destructive-600)", fontSize: "var(--font-size-1-11)" }}',
+                    '      >',
+                    '        Mark must be between 0 and 100',
+                    '      </span>',
+                    '    </div>',
+                    '  );',
+                    '}',
+                    'export default WithErrorExample;',
+                ].join('\n'),
+            },
+        },
+    },
+}, [
+    '`hasError={true}` applies `ds-number-input__container--error`, which adds a red border to the container.',
+    '`hasError` is **purely visual** — it carries no ARIA semantics. When using bare NumberInput outside FormField,',
+    'always also set `aria-invalid="true"` and `aria-describedby` pointing to the error message element.',
+    'FormField handles all three automatically when `errorText` is present.',
+].join(' '));
+export const WithMinMax = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "class-size", style: { color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Class size (1\u201340 pupils)" }), _jsx(NumberInput, { id: "class-size", defaultValue: 5, min: 1, max: 40, step: 1 })] }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)', fontStyle: 'italic' }, children: "Try typing 99 and tabbing away \u2014 the value clamps to 40 on blur. The plus button disables at 40; the minus button disables at 1." }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "attendance-threshold", style: { color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Attendance alert threshold % (50\u2013100)" }), _jsx(NumberInput, { id: "attendance-threshold", defaultValue: 90, min: 50, max: 100, step: 1 })] })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: [
+                    "import { NumberInput } from '@arbor-education/design-system.components';",
+                    '',
+                    'function WithMinMaxExample() {',
+                    '  return (',
+                    '    <NumberInput',
+                    '      id="class-size"',
+                    '      defaultValue={5}',
+                    '      min={1}',
+                    '      max={40}',
+                    '      step={1}',
+                    '    />',
+                    '  );',
+                    '}',
+                    'export default WithMinMaxExample;',
+                ].join('\n'),
+            },
+        },
+    },
+}, [
+    'Setting `min` and `max` enables automatic clamping.',
+    'On blur (or after a spinner click that would exceed the bound),',
+    'the value is snapped to the nearest allowed boundary using Decimal.js arithmetic.',
+    'The minus button disables when `value <= min`; the plus button disables when `value >= max`.',
+    'Try typing a value outside the range and tabbing away to see clamping in action.',
+].join(' '));
+export const DecimalStep = withDescription({
+    render: () => _jsx(DecimalStepTemplate, {}),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: [
+                    "import { NumberInput } from '@arbor-education/design-system.components';",
+                    '',
+                    'function DecimalStepExample() {',
+                    '  return (',
+                    '    <NumberInput',
+                    '      id="grade-weighting"',
+                    '      defaultValue={0}',
+                    '      min={0}',
+                    '      max={1}',
+                    '      step={0.1}',
+                    '      aria-label="Grade component weighting"',
+                    '    />',
+                    '  );',
+                    '}',
+                    'export default DecimalStepExample;',
+                ].join('\n'),
+            },
+        },
+    },
+}, [
+    'This story demonstrates why NumberInput uses **Decimal.js** for all spinner arithmetic.',
+    'Native JavaScript floating-point arithmetic means `0.1 + 0.2 = 0.30000000000000004`.',
+    'For grade weightings, mark totals, or percentage thresholds, that kind of drift causes',
+    'real problems. The spinner buttons in this story use `step={0.1}` — try stepping from 0.1',
+    'and watch the Decimal.js result stay precise while the native JS equivalent drifts.',
+    'The live comparison panel makes the difference visible.',
+].join(' '));
+export const SpinnersDisabled = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "pupil-premium-count", style: { color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Pupil premium count" }), _jsx(NumberInput, { id: "pupil-premium-count", defaultValue: 47, disableSpinners: true, "aria-label": "Number of pupil premium eligible pupils" })] }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-1-11)', fontStyle: 'italic' }, children: "No spinner buttons \u2014 keyboard entry only. Min/max and blur-clamping still apply." }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx("label", { htmlFor: "form-capacity", style: { color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Form capacity (grid cell \u2014 spinners would crowd the column)" }), _jsx("div", { style: { width: '6rem' }, children: _jsx(NumberInput, { id: "form-capacity", defaultValue: 30, min: 1, max: 60, disableSpinners: true, "aria-label": "Form group capacity" }) })] })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: [
+                    "import { NumberInput } from '@arbor-education/design-system.components';",
+                    '',
+                    'function SpinnersDisabledExample() {',
+                    '  return (',
+                    '    <NumberInput',
+                    '      id="pupil-premium-count"',
+                    '      defaultValue={47}',
+                    '      disableSpinners',
+                    '      aria-label="Number of pupil premium eligible pupils"',
+                    '    />',
+                    '  );',
+                    '}',
+                    'export default SpinnersDisabledExample;',
+                ].join('\n'),
+            },
+        },
+    },
+}, [
+    '`disableSpinners={true}` hides the minus and plus buttons, leaving a clean text-entry field.',
+    'Use this in data-grid cells, compact filter panels, or anywhere the ± buttons would be too large',
+    'or visually noisy. All other behaviour — blur-clamping, `min`/`max` bounds, Decimal.js arithmetic —',
+    'continues to work exactly as normal. Keyboard users simply type the value directly.',
+].join(' '));
+export const InFormField = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { inputType: "number", label: "Target attendance (%)", id: "target-attendance", fieldDescription: "Set the school-wide attendance target. Pupils below this threshold will appear in the at-risk register.", inputProps: { defaultValue: 96, min: 50, max: 100, step: 1 } }), _jsx(FormField, { inputType: "number", label: "Absence alert after (days)", id: "absence-alert-days", inputProps: { defaultValue: 3, min: 1, step: 1 } }), _jsx(FormField, { inputType: "number", label: "Maximum class size", id: "max-class-size", errorText: "Class size must be between 1 and 40", inputProps: { defaultValue: 50, min: 1, max: 40, step: 1 } })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: [
+                    "import { FormField } from '@arbor-education/design-system.components';",
+                    '',
+                    'function InFormFieldExample() {',
+                    '  return (',
+                    '    <div>',
+                    '      <FormField',
+                    '        inputType="number"',
+                    '        label="Target attendance (%)"',
+                    '        id="target-attendance"',
+                    '        fieldDescription="Set the school-wide attendance target."',
+                    '        inputProps={{ defaultValue: 96, min: 50, max: 100, step: 1 }}',
+                    '      />',
+                    '      <FormField',
+                    '        inputType="number"',
+                    '        label="Maximum class size"',
+                    '        id="max-class-size"',
+                    '        errorText="Class size must be between 1 and 40"',
+                    '        inputProps={{ defaultValue: 50, min: 1, max: 40, step: 1 }}',
+                    '      />',
+                    '    </div>',
+                    '  );',
+                    '}',
+                    'export default InFormFieldExample;',
+                ].join('\n'),
+            },
+        },
+    },
+}, [
+    '**Always use `FormField` with `inputType="number"` in real forms.**',
+    'FormField automatically wires `hasError` (from `errorText`), `aria-invalid`, `aria-describedby`,',
+    'and the label `htmlFor` association — you do not need to set any of these manually in `inputProps`.',
+    'The third field shows how `errorText` drives the error state. The `fieldDescription` prop in the',
+    'first field renders a hint beneath the label, automatically linked via `aria-describedby`.',
+].join(' '));
+export const ControlledInput = withDescription({
+    render: () => _jsx(ControlledInputTemplate, {}),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: [
+                    "import { useState } from 'react';",
+                    "import { NumberInput } from '@arbor-education/design-system.components';",
+                    '',
+                    'function AttendanceTargetField() {',
+                    '  const [target, setTarget] = useState(\'96\');',
+                    '',
+                    '  return (',
+                    '    <div>',
+                    '      <label htmlFor="attendance-target">Attendance target (%)</label>',
+                    '      <NumberInput',
+                    '        id="attendance-target"',
+                    '        value={target}',
+                    '        min={0}',
+                    '        max={100}',
+                    '        step={1}',
+                    '        // NOTE: only e.currentTarget.value is populated — do not use e.target.value',
+                    '        onChange={(e) => setTarget(e.currentTarget.value)}',
+                    '      />',
+                    '      <p>Current target: {target}%</p>',
+                    '    </div>',
+                    '  );',
+                    '}',
+                    'export default AttendanceTargetField;',
+                ].join('\n'),
+            },
+        },
+    },
+}, [
+    'Demonstrates the **controlled** pattern: `value` is driven from `useState`, updated via `onChange`.',
+    'There is no `defaultValue` prop — omitting it is essential, as a truthy `defaultValue`',
+    'would silently block all `value` prop updates after mount.',
+    'Note the `onChange` handler reads from `e.currentTarget.value`, not `e.target.value`',
+    '— the event is manually constructed inside NumberInput and only `currentTarget.value` is set.',
+    'The feedback panel below the input reads the live state value, confirming the controlled link.',
+].join(' '));
 //# sourceMappingURL=NumberInput.stories.js.map