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

package/src/components/editableText/EditableText.stories.tsx

@@ -1,29 +1,201 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { EditableText } from './EditableText';
+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 { EditableText } from 'Components/editableText/EditableText';
+
+// ---------------------------------------------------------------------------
+// Content strings
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = `
+EditableText is an inline text element that can be edited in place. Clicking the text (or the
+pencil icon beside it) switches to an input or textarea, letting users rename records, update
+titles, and correct short pieces of text without navigating away to a separate form.
+`.trim();
+
+const USAGE_GUIDANCE = `
+### When to use
+
+- **Renaming a record title in-context** — group names, report titles, curriculum plan headings
+- **Correcting a short piece of editable text inline** — without navigating to a separate form
+- **Updating a longer freeform description** — use with \`multiline\` for textarea behaviour
+
+---
+
+### When NOT to use
+
+| Situation | Use instead |
+|---|---|
+| Collecting new data in a form | [\`FormField\`](?path=/docs/components-formfield--docs) — labelled inputs with validation |
+| Editing content that requires explicit confirmation before saving | \`FormField\` with a submit button — \`onEditSave\` fires on blur |
+| Displaying text the user should never change | A plain text element — EditableText always shows an edit affordance |
+
+---
+
+### Always update \`text\` in \`onEditSave\`
+
+EditableText is a **controlled-ish** component — it holds its own internal state but
+initialises from the \`text\` prop. If you don't feed the saved value back as the new \`text\`
+prop, the component will snap back to the original value on the next render cycle.
+
+\`\`\`tsx
+const [title, setTitle] = useState('Year 10 Science');
+
+<EditableText text={title} onEditSave={setTitle} />
+\`\`\`
+
+### Multiline mode (\`multiline\`)
+
+When \`multiline={true}\` the underlying input switches to a \`<textarea>\`.
+The keyboard contract changes:
+
+- **Enter** inserts a newline (does **not** save)
+- **Escape** reverts to the pre-edit value
+- **Blur** (clicking away) saves
+
+> In single-line mode **Enter** saves immediately. Forgetting this difference is the most
+> common source of unexpected behaviour — document it clearly when you expose this prop to end users.
+
+### Programmatic edit mode (\`isEditing\`)
+
+\`isEditing\` is a **one-way trigger**. Setting it to \`true\` tells the component to open the
+input, but the component then takes back ownership of that state. You **cannot** force the
+component closed by setting \`isEditing={false}\` after editing has started — only user
+interaction (blur or Escape) can close it.
+
+\`\`\`tsx
+<EditableText
+  text={name}
+  isEditing={shouldEdit}   // opens the input once; component owns state after that
+  onEditSave={setName}
+/>
+\`\`\`
+
+### Blur saves immediately
+
+\`onEditSave\` fires on blur, including accidental focus loss (e.g. the user clicks elsewhere
+on the page). If the user must explicitly confirm a change before it is persisted, use a
+\`<FormField>\` with a dedicated submit button instead.
+
+### Typography is fully inherited
+
+EditableText applies **no font styles of its own**. Size, weight, colour, and line-height all
+come from the parent element. Wrap it in an \`<h1>\`, \`<p>\`, or any container and the input
+will match the surrounding text automatically — no extra CSS needed.
+`.trim();
+
+const DEVELOPER_NOTES = `
+### Accessibility & keyboard contract
+
+| Key | Single-line | Multiline |
+|---|---|---|
+| Enter | Saves and closes the input | Inserts a newline |
+| Escape | Reverts to the pre-edit value and closes | Reverts to the pre-edit value and closes |
+| Tab / click away (blur) | Saves and closes the input | Saves and closes the input |
+
+The display-mode button carries \`aria-label="Edit text"\` so screen-reader users understand
+its purpose. The input carries \`aria-label="Text"\`. Both labels are applied automatically —
+you do not need to pass anything extra.
+`.trim();
+
+const RELATED_COMPONENTS = `
+## Related components
+- [FormField](?path=/docs/components-formfield--docs) — full form inputs with labels, validation, and helper text
+- [Table](?path=/docs/components-table--docs) — data grid that can use EditableText in inline-edit cells
+- [TextInput](?path=/docs/components-formfield-inputs-textinput--docs) — the underlying single-line input used by EditableText
+`.trim();
+
+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 EditableTextDocsPage() {
+  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/EditableText',
   component: EditableText,
+  tags: ['autodocs'],
   parameters: {
-    layout: 'padded',
+    docs: {
+      page: EditableTextDocsPage,
+    },
   },
-  tags: ['autodocs'],
   argTypes: {
     text: {
       control: 'text',
-      description: 'The text to display',
-    },
-    className: {
-      control: 'text',
-      description: 'Optional CSS class name',
+      description: 'The current text value. **Always** update this prop inside `onEditSave` to keep the component in sync.',
+      table: {
+        type: { summary: 'string' },
+      },
     },
     onEditSave: {
-      action: 'edit saved',
-      description: 'Callback fired when the text is edited',
+      control: false,
+      description: 'Callback fired when the user saves a change (on blur or Enter in single-line mode). Receives the new text string.',
+      table: {
+        type: { summary: '(newText: string) => void' },
+      },
     },
     isEditing: {
       control: 'boolean',
-      description: 'Control whether the text is in edit mode',
+      description:
+        'One-way trigger that forces the component into edit mode when set to `true`. The component takes back ownership of this state once editing begins — setting it back to `false` from outside will not close the input.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    multiline: {
+      control: 'boolean',
+      description:
+        'When `true`, switches the input to a `<textarea>`. In multiline mode **Enter inserts a newline** — it does NOT save. Only blur saves.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    className: {
+      control: 'text',
+      description: 'Additional CSS class names applied to the root `<span>` element.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "''" },
+      },
     },
   },
 } satisfies Meta<typeof EditableText>;
@@ -31,106 +203,410 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Default (inherits parent styles)
-export const Default: Story = {
-  render: args => (
-    <div style={{ width: '100%' }}>
-      <EditableText {...args} />
-    </div>
-  ),
-  args: {
-    text: 'Editable Text',
-    onEditSave: () => {},
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: StoryObj<typeof meta>, description: string): StoryObj<typeof meta> => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
   },
+});
+
+// ---------------------------------------------------------------------------
+// Named template components
+// (All use useState so onEditSave keeps the component in sync — this is the
+//  pattern every consumer MUST follow to avoid text snapping back on re-render)
+// ---------------------------------------------------------------------------
+
+const DefaultTemplate = (args: React.ComponentProps<typeof EditableText>) => {
+  const [text, setText] = useState(args.text);
+  const [lastSaved, setLastSaved] = useState(args.text);
+
+  useEffect(() => {
+    setText(args.text);
+    setLastSaved(args.text);
+  }, [args.text]);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '480px' }}>
+      <EditableText
+        {...args}
+        text={text}
+        onEditSave={(val) => {
+          setText(val);
+          setLastSaved(val);
+        }}
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: '0.875rem' }}>
+        Last saved: &quot;
+        {lastSaved}
+        &quot;
+      </p>
+    </div>
+  );
+};
+
+const MultilineTemplate = () => {
+  const [text, setText] = useState(
+    'Attendance requirements and absence notification procedures for all pupils enrolled in Year 10.',
+  );
+  const [lastSaved, setLastSaved] = useState(text);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '560px' }}>
+      <EditableText
+        text={text}
+        multiline
+        onEditSave={(val) => {
+          setText(val);
+          setLastSaved(val);
+        }}
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: '0.875rem' }}>
+        Last saved: &quot;
+        {lastSaved}
+        &quot;
+      </p>
+    </div>
+  );
+};
+
+const ProgrammaticControlTemplate = () => {
+  const [text, setText] = useState('Spring Term Assessment Schedule');
+  const [triggerEdit, setTriggerEdit] = useState(false);
+
+  const handleEditSave = (val: string) => {
+    setText(val);
+    setTriggerEdit(false);
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '480px' }}>
+      <EditableText text={text} isEditing={triggerEdit} onEditSave={handleEditSave} />
+      <Button variant="secondary" onClick={() => setTriggerEdit(true)}>
+        Edit title
+      </Button>
+    </div>
+  );
 };
 
-// Inside H1 heading
-export const InH1: Story = {
-  render: args => (
+const InHeading1Template = () => {
+  const [text, setText] = useState('Year 10 Science Curriculum Plan');
+  return (
     <h1>
-      <EditableText {...args} />
+      <EditableText text={text} onEditSave={setText} />
     </h1>
-  ),
-  args: {
-    text: 'Editable Heading Level 1',
-    onEditSave: () => {},
-  },
+  );
 };
 
-// Inside H2 heading
-export const InH2: Story = {
-  render: args => (
+const InHeading2Template = () => {
+  const [text, setText] = useState('Spring Term Assessment Schedule');
+  return (
     <h2>
-      <EditableText {...args} />
+      <EditableText text={text} onEditSave={setText} />
     </h2>
-  ),
-  args: {
-    text: 'Editable Heading Level 2',
-    onEditSave: () => {},
-  },
+  );
 };
 
-// Inside H3 heading
-export const InH3: Story = {
-  render: args => (
-    <h3>
-      <EditableText {...args} />
-    </h3>
-  ),
-  args: {
-    text: 'Editable Heading Level 3',
-    onEditSave: () => {},
-  },
+const InParagraphTemplate = () => {
+  const [text, setText] = useState('Emily Johnson');
+  return (
+    <p className="ds-text">
+      Class teacher:
+      {' '}
+      <EditableText text={text} onEditSave={setText} />
+    </p>
+  );
 };
 
-// Inside H4 heading
-export const InH4: Story = {
-  render: args => (
-    <h4>
-      <EditableText {...args} />
-    </h4>
-  ),
-  args: {
-    text: 'Editable Heading Level 4',
-    onEditSave: () => {},
-  },
+const LongTextTemplate = () => {
+  const [text, setText] = useState(
+    'Behaviour policy and expectations for all students during lesson time, including mobile phone usage and dress code requirements',
+  );
+  return (
+    <div style={{ maxWidth: '480px' }}>
+      <EditableText text={text} onEditSave={setText} />
+    </div>
+  );
 };
 
-// Inside paragraph
-export const InParagraph: Story = {
-  render: args => (
-    <p>
-      <EditableText {...args} />
-    </p>
-  ),
-  args: {
-    text: 'Editable paragraph text',
-    onEditSave: () => {},
-  },
-};
+const EscapeToCancelTemplate = () => {
+  const [text, setText] = useState('Mr. David Chen');
+  const [savedText, setSavedText] = useState('Mr. David Chen');
+  const [cancelCount, setCancelCount] = useState(0);
 
-// Inside custom styled div
-export const InCustomStyledDiv: Story = {
-  render: args => (
-    <div style={{ fontSize: '24px', fontWeight: 'bold', color: '#0066cc' }}>
-      <EditableText {...args} />
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '480px' }}>
+      <EditableText
+        text={text}
+        onEditSave={(val) => {
+          setText(val);
+          setSavedText(val);
+        }}
+      />
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem' }}>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: '0.875rem' }}>
+          Saved value: &quot;
+          {savedText}
+          &quot;
+        </p>
+        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: '0.875rem' }}>
+          Escapes pressed:
+          {' '}
+          {cancelCount}
+        </p>
+      </div>
+      <p className="ds-text" style={{ margin: 0, fontSize: '0.875rem' }}>
+        Try editing the text above, type something new, then press
+        {' '}
+        <kbd>Escape</kbd>
+        {' '}
+        — the
+        original value is restored without calling
+        {' '}
+        <code>onEditSave</code>
+        .
+      </p>
+      {/*
+        We track cancels by wrapping the component and watching for text changes
+        that don't match what we'd expect from a save — but EditableText does not
+        expose an onCancel callback. The counter below is illustrative only.
+        Reset the page to see the true saved state.
+      */}
+      <Button variant="secondary" onClick={() => setCancelCount(c => c + 1)}>
+        Simulate cancel count (manual)
+      </Button>
     </div>
-  ),
-  args: {
-    text: 'Custom styled editable text',
-    onEditSave: () => {},
-  },
+  );
 };
 
-// Long text example
-export const LongText: Story = {
-  render: args => (
-    <h2>
-      <EditableText {...args} />
-    </h2>
-  ),
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
   args: {
-    text: 'This is a much longer text that demonstrates how the component handles extended content',
+    text: 'Year 10 Science Curriculum Plan',
     onEditSave: () => {},
+    isEditing: false,
+    multiline: false,
+    className: '',
+  },
+  render: args => <DefaultTemplate {...args} />,
+  parameters: {
+    docs: {
+      description: {
+        story: PROPS_INTRO,
+      },
+    },
   },
 };
+
+export const MultilineEditing: Story = withDescription(
+  {
+    args: { text: '', onEditSave: () => {} },
+    render: () => <MultilineTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+import { EditableText } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+const [text, setText] = useState(
+  'Attendance requirements and absence notification procedures for all pupils enrolled in Year 10.',
+);
+
+<EditableText
+  text={text}
+  multiline
+  onEditSave={setText}
+/>
+          `.trim(),
+        },
+      },
+    },
+  },
+  `When \`multiline={true}\` the component renders a \`<textarea>\` instead of a text input.
+
+> **Key difference:** In multiline mode **Enter inserts a newline** — it does **not** save.
+> Only blur (clicking away) or Escape will close the editor.
+> In single-line mode, Enter saves immediately.
+
+Use multiline for longer freeform text such as descriptions, notes, or policy summaries.`,
+);
+
+export const ProgrammaticControl: Story = withDescription(
+  {
+    args: { text: '', onEditSave: () => {} },
+    render: () => <ProgrammaticControlTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+import { EditableText } from '@arbor-education/design-system.components';
+import { Button } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+const [text, setText] = useState('Spring Term Assessment Schedule');
+const [triggerEdit, setTriggerEdit] = useState(false);
+
+<EditableText
+  text={text}
+  isEditing={triggerEdit}
+  onEditSave={(val) => {
+    setText(val);
+    setTriggerEdit(false);
+  }}
+/>
+<Button variant="secondary" onClick={() => setTriggerEdit(true)}>
+  Edit title
+</Button>
+          `.trim(),
+        },
+      },
+    },
+  },
+  `Use \`isEditing\` to open the input programmatically — for example, from a toolbar button or a keyboard shortcut.
+
+> **Important:** \`isEditing\` is a one-way trigger. Once the component receives \`true\` it takes back
+> ownership of edit state. Setting \`isEditing={false}\` from the outside will **not** close
+> the input after editing has begun — only blur or Escape can do that.`,
+);
+
+export const InHeading1: Story = withDescription(
+  {
+    args: { text: '', onEditSave: () => {} },
+    render: () => <InHeading1Template />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+import { EditableText } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+const [text, setText] = useState('Year 10 Science Curriculum Plan');
+
+<h1>
+  <EditableText text={text} onEditSave={setText} />
+</h1>
+          `.trim(),
+        },
+      },
+    },
+  },
+  `EditableText inherits all typography from its parent. Wrapping it in an \`<h1>\` gives the
+input the same font size, weight, and line-height as the surrounding heading — no extra CSS needed.`,
+);
+
+export const InHeading2: Story = withDescription(
+  {
+    args: { text: '', onEditSave: () => {} },
+    render: () => <InHeading2Template />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+import { EditableText } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+const [text, setText] = useState('Spring Term Assessment Schedule');
+
+<h2>
+  <EditableText text={text} onEditSave={setText} />
+</h2>
+          `.trim(),
+        },
+      },
+    },
+  },
+  `Same inheritance pattern as \`InHeading1\` but at \`<h2>\` size — useful for section titles and
+panel headers inside a page that already has an \`<h1>\`.`,
+);
+
+export const InParagraph: Story = withDescription(
+  {
+    args: { text: '', onEditSave: () => {} },
+    render: () => <InParagraphTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+import { EditableText } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+const [text, setText] = useState('Emily Johnson');
+
+<p className="ds-text">
+  Class teacher: <EditableText text={text} onEditSave={setText} />
+</p>
+          `.trim(),
+        },
+      },
+    },
+  },
+  `EditableText can sit inline within a paragraph. The input inherits body-text styles automatically,
+so it blends seamlessly with surrounding copy. Use \`className="ds-text"\` on the wrapping \`<p>\`
+to apply design-system base font styles.`,
+);
+
+export const LongText: Story = withDescription(
+  {
+    args: { text: '', onEditSave: () => {} },
+    render: () => <LongTextTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+import { EditableText } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+const [text, setText] = useState(
+  'Behaviour policy and expectations for all students during lesson time, including mobile phone usage and dress code requirements',
+);
+
+<EditableText text={text} onEditSave={setText} />
+          `.trim(),
+        },
+      },
+    },
+  },
+  `Long text strings wrap naturally inside the component button. The input expands to fill the
+available width when the user enters edit mode. Constrain the parent container's width if you
+need to limit how wide the input can grow.`,
+);
+
+export const EscapeToCancel: Story = withDescription(
+  {
+    args: { text: '', onEditSave: () => {} },
+    render: () => <EscapeToCancelTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+import { EditableText } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+const [text, setText] = useState('Mr. David Chen');
+
+// Pressing Escape while editing restores the pre-edit value
+// and does NOT call onEditSave — no network request is made.
+<EditableText text={text} onEditSave={setText} />
+          `.trim(),
+        },
+      },
+    },
+  },
+  `Press **Escape** while editing to revert the input to its pre-edit value without calling
+\`onEditSave\`. This means no data is persisted — a safe exit for users who change their minds.
+
+The component handles this internally. No special setup is needed in the consumer.`,
+);