@structuralists/scaffolding 0.13.0 → 0.15.0

package/src/storybook/Demo.stories.tsx

@@ -0,0 +1,467 @@
+import { useRef, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import {
+  BigTable,
+  badgeColumn,
+  booleanColumn,
+  currencyColumn,
+  dateColumn,
+  textColumn,
+} from '../components/Tables/BigTable';
+import type { ColumnDef } from '../components/Tables/BigTable';
+import { Bar } from '../components/Layout/Bar';
+import { Panels } from '../components/Layout/Panels';
+import { Stack } from '../components/Layout/Stack';
+import { Text } from '../components/Content/Text';
+import { MediumModal } from '../components/Modals/MediumModal';
+import { ConfirmModal } from '../components/Modals/ConfirmModal';
+import { Button } from '../forms/elements/Button';
+import { IconButton } from '../forms/elements/IconButton';
+import type { SelectOption } from '../forms/elements/Select';
+import { useFormState } from '../forms/state/useFormState/useFormState';
+import { matches, notEmpty } from '../forms/state/validators/validators';
+import { TextInputForForm } from '../forms/state/bindings/TextInputForForm';
+import { SingleSelectForForm } from '../forms/state/bindings/SingleSelectForForm';
+
+// The Demo section is a showcase: polished compositions of the library's
+// public pieces, not component API docs. This one is the full CRUD loop —
+// BigTable + MediumModal + useFormState field bindings + ConfirmModal —
+// wired together the way a consuming app would.
+const meta: Meta = {
+  title: 'Demo/Team Directory',
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+const ROLES = ['engineer', 'designer', 'pm', 'sales'] as const;
+type Role = (typeof ROLES)[number];
+
+const TEAMS = ['Platform', 'Growth', 'Infra', 'Brand', 'Revenue', 'Search'] as const;
+type Team = (typeof TEAMS)[number];
+
+const ROLE_OPTIONS: SelectOption<Role>[] = [
+  { value: 'engineer', label: 'Engineer' },
+  { value: 'designer', label: 'Designer' },
+  { value: 'pm', label: 'PM' },
+  { value: 'sales', label: 'Sales' },
+];
+
+const TEAM_OPTIONS: SelectOption<Team>[] = TEAMS.map((team) => ({
+  value: team,
+  label: team,
+}));
+
+type Member = {
+  id: string;
+  name: string;
+  email: string;
+  role: Role;
+  team: Team;
+  salary: number;
+  startDate: string; // ISO
+  isActive: boolean;
+};
+
+const FIRST_NAMES = [
+  'Ada', 'Alan', 'Edsger', 'Barbara', 'Donald', 'Margaret',
+  'John', 'Katherine', 'Dennis', 'Radia', 'Ken', 'Frances',
+];
+const LAST_NAMES = [
+  'Lovelace', 'Turing', 'Dijkstra', 'Liskov', 'Knuth',
+  'Hamilton', 'Backus', 'Johnson', 'Ritchie',
+];
+
+// Deterministic: every value is index arithmetic over literal arrays — the
+// same 34 rows on every render, so the story (and its play test) never
+// flickers. The (i % 12, 5i % 9) name pairing has period 36, so all 34
+// name/email combos are distinct.
+const SEED_MEMBERS: Member[] = Array.from({ length: 34 }, (_, i) => {
+  const first = FIRST_NAMES[i % FIRST_NAMES.length];
+  const last = LAST_NAMES[(i * 5) % LAST_NAMES.length];
+  return {
+    id: `emp_${100 + i}`,
+    name: `${first} ${last}`,
+    email: `${first.toLowerCase()}.${last.toLowerCase()}@acme.dev`,
+    role: ROLES[i % ROLES.length],
+    team: TEAMS[(i * 7) % TEAMS.length],
+    salary: 95_000 + (i % 7) * 8_000 + (i % 3) * 2_500,
+    startDate: new Date(
+      Date.UTC(2019 + (i % 6), (i * 5) % 12, ((i * 7) % 27) + 1),
+    ).toISOString(),
+    isActive: i % 6 !== 0,
+  };
+});
+
+// What the modal form holds while editing: loose everywhere a field starts
+// blank. Salary is a string because it's typed into a text input; the
+// digits-only constraint plus Number() at the boundary turn it back into
+// a number.
+type MemberFormValues = {
+  name: string | undefined;
+  email: string | undefined;
+  role: Role | null;
+  team: Team | null;
+  salary: string | undefined;
+};
+
+// What onSubmit receives: the constraints below strip undefined/null from
+// every field. This type annotating the parent's handler compiles only
+// because useFormState actually delivers the narrowed type.
+type MemberFormSubmit = {
+  name: string;
+  email: string;
+  role: Role;
+  team: Team;
+  salary: string;
+};
+
+const EMPTY_MEMBER_FORM: MemberFormValues = {
+  name: undefined,
+  email: undefined,
+  role: null,
+  team: null,
+  salary: undefined,
+};
+
+type MemberFormModalProps = {
+  isOpen: boolean;
+  title: string;
+  submitLabel: string;
+  initialValues: MemberFormValues;
+  onCancel: () => void;
+  onSubmit: (values: MemberFormSubmit) => void;
+};
+
+// One modal serves both add and edit — the parent remounts it fresh per
+// opening (via key) with the right initialValues, so the hook state never
+// leaks between sessions. Every field is wired with one getFormFieldPropsAt
+// expression; error display (touched OR submit-attempted) comes with it.
+const MemberFormModal = (props: MemberFormModalProps) => {
+  const { isOpen, title, submitLabel, initialValues, onCancel, onSubmit } =
+    props;
+
+  const { getFormFieldPropsAt, submit } = useFormState({
+    initialValues,
+    constraints: {
+      name: notEmpty('name'),
+      email: [
+        notEmpty('email'),
+        matches('email', /^[^@\s]+@[^@\s]+\.[^@\s]+$/, 'a valid email'),
+      ],
+      role: notEmpty('role'),
+      team: notEmpty('team'),
+      salary: [
+        notEmpty('salary'),
+        matches('salary', /^\d+$/, 'a whole dollar amount (digits only)'),
+      ],
+    },
+    onSubmit,
+  });
+
+  return (
+    <MediumModal
+      isOpen={isOpen}
+      onClose={onCancel}
+      title={title}
+      footer={
+        <>
+          <Button onClick={onCancel}>Cancel</Button>
+          <Button variant="primary" onClick={() => submit()}>
+            {submitLabel}
+          </Button>
+        </>
+      }
+    >
+      <Stack gap={3}>
+        <TextInputForForm
+          label="Full name"
+          placeholder="Ada Lovelace"
+          formFieldProps={getFormFieldPropsAt(['name'])}
+        />
+        <TextInputForForm
+          label="Email"
+          type="email"
+          placeholder="ada.lovelace@acme.dev"
+          formFieldProps={getFormFieldPropsAt(['email'])}
+        />
+        <SingleSelectForForm
+          label="Role"
+          options={ROLE_OPTIONS}
+          placeholder="Pick a role"
+          formFieldProps={getFormFieldPropsAt(['role'])}
+        />
+        <SingleSelectForForm
+          label="Team"
+          options={TEAM_OPTIONS}
+          placeholder="Pick a team"
+          formFieldProps={getFormFieldPropsAt(['team'])}
+        />
+        <TextInputForForm
+          label="Salary (USD)"
+          hint="Whole dollars, digits only"
+          placeholder="120000"
+          formFieldProps={getFormFieldPropsAt(['salary'])}
+        />
+      </Stack>
+    </MediumModal>
+  );
+};
+
+const PencilIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+    <path
+      d="M11.5 2.5 L13.5 4.5 L5.5 12.5 L2.8 13.2 L3.5 10.5 Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const TrashIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+    <path
+      d="M3 4.5 H13 M6.5 4.5 V3 H9.5 V4.5 M4.5 4.5 L5.2 13 H10.8 L11.5 4.5 M6.8 7 V10.7 M9.2 7 V10.7"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+type EditorSession = { mode: 'add' } | { mode: 'edit'; member: Member };
+
+// The session outlives the open flag so the form keeps rendering its
+// contents while ModalShell plays the 200ms exit animation; sessionId keys
+// a fresh remount per opening so form state never leaks between sessions.
+type EditorState = {
+  session: EditorSession;
+  sessionId: number;
+  isOpen: boolean;
+};
+
+const TeamDirectoryDemo = () => {
+  const [rows, setRows] = useState<Member[]>(SEED_MEMBERS);
+  const [editor, setEditor] = useState<EditorState | null>(null);
+  const [pendingDelete, setPendingDelete] = useState<Member | null>(null);
+  const nextIdRef = useRef(100 + SEED_MEMBERS.length);
+
+  const openEditor = (session: EditorSession) =>
+    setEditor((prev) => ({
+      session,
+      sessionId: (prev?.sessionId ?? 0) + 1,
+      isOpen: true,
+    }));
+
+  const closeEditor = () =>
+    setEditor((prev) => (prev ? { ...prev, isOpen: false } : prev));
+
+  const handleEditorSubmit = (vals: MemberFormSubmit) => {
+    if (editor?.session.mode === 'edit') {
+      const { id } = editor.session.member;
+      setRows((prev) =>
+        prev.map((row) =>
+          row.id === id
+            ? { ...row, ...vals, salary: Number(vals.salary) }
+            : row,
+        ),
+      );
+    } else {
+      const id = `emp_${nextIdRef.current++}`;
+      setRows((prev) => [
+        ...prev,
+        {
+          ...vals,
+          salary: Number(vals.salary),
+          id,
+          startDate: '2026-07-01T00:00:00.000Z',
+          isActive: true,
+        },
+      ]);
+    }
+    closeEditor();
+  };
+
+  const columnDefs: ColumnDef<Member>[] = [
+    textColumn({ id: 'name', header: 'Name', value: (m) => m.name, minWidth: 160 }),
+    textColumn({ id: 'email', header: 'Email', value: (m) => m.email, minWidth: 220 }),
+    badgeColumn({ id: 'role', header: 'Role', value: (m) => m.role }),
+    textColumn({ id: 'team', header: 'Team', value: (m) => m.team }),
+    currencyColumn({ id: 'salary', header: 'Salary', value: (m) => m.salary }),
+    booleanColumn({ id: 'active', header: 'Active', value: (m) => m.isActive }),
+    dateColumn({ id: 'start', header: 'Started', value: (m) => m.startDate }),
+    {
+      id: 'actions',
+      header: '',
+      align: 'right',
+      cell: (m) => (
+        <Stack direction="row" gap={1} justify="end">
+          <IconButton
+            ariaLabel={`Edit ${m.name}`}
+            tooltip="Edit"
+            size="small"
+            onClick={() => openEditor({ mode: 'edit', member: m })}
+          >
+            <PencilIcon />
+          </IconButton>
+          <IconButton
+            ariaLabel={`Delete ${m.name}`}
+            tooltip="Delete"
+            size="small"
+            variant="danger"
+            onClick={() => setPendingDelete(m)}
+          >
+            <TrashIcon />
+          </IconButton>
+        </Stack>
+      ),
+    },
+  ];
+
+  return (
+    <div style={{ height: '100vh' }}>
+      <Panels
+        header={
+          <Bar
+            title="Team Directory"
+            right={
+              <Stack direction="row" gap={2} align="center">
+                <Text size="small" isMuted>
+                  {rows.length} members
+                </Text>
+                <Button
+                  size="small"
+                  variant="primary"
+                  onClick={() => openEditor({ mode: 'add' })}
+                >
+                  Add member
+                </Button>
+              </Stack>
+            }
+          />
+        }
+      >
+        <BigTable data={rows} columnDefs={columnDefs} getRowKey={(m) => m.id} />
+      </Panels>
+
+      {editor && (
+        <MemberFormModal
+          key={editor.sessionId}
+          isOpen={editor.isOpen}
+          title={editor.session.mode === 'edit' ? 'Edit member' : 'Add member'}
+          submitLabel="Save"
+          initialValues={
+            editor.session.mode === 'edit'
+              ? {
+                  name: editor.session.member.name,
+                  email: editor.session.member.email,
+                  role: editor.session.member.role,
+                  team: editor.session.member.team,
+                  salary: String(editor.session.member.salary),
+                }
+              : EMPTY_MEMBER_FORM
+          }
+          onCancel={closeEditor}
+          onSubmit={handleEditorSubmit}
+        />
+      )}
+
+      <ConfirmModal
+        isOpen={pendingDelete !== null}
+        title="Delete member"
+        description={
+          pendingDelete
+            ? `Remove ${pendingDelete.name} from the directory? This cannot be undone.`
+            : undefined
+        }
+        confirmLabel="Delete member"
+        isDanger
+        onConfirm={() => {
+          if (pendingDelete) {
+            const { id } = pendingDelete;
+            setRows((prev) => prev.filter((row) => row.id !== id));
+          }
+          setPendingDelete(null);
+        }}
+        onCancel={() => setPendingDelete(null)}
+      />
+    </div>
+  );
+};
+
+export const FullCrud: Story = {
+  name: 'Full CRUD',
+  render: () => <TeamDirectoryDemo />,
+  // Walks the whole loop: add (validation errors → fix → row appends),
+  // edit (same modal pre-filled → row updates), delete (confirm → row
+  // removed). Modals and select option lists are portaled to <body>, so
+  // everything inside them is queried on the document body.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    await expect(canvas.getByText('34 members')).toBeInTheDocument();
+
+    // — Add: a failing submit surfaces every constrained field's error.
+    await userEvent.click(canvas.getByRole('button', { name: 'Add member' }));
+    await userEvent.click(await body.findByRole('button', { name: 'Save' }));
+    await expect(body.getByText("'name' cannot be empty")).toBeInTheDocument();
+    await expect(body.getByText("'email' cannot be empty")).toBeInTheDocument();
+    await expect(body.getByText("'role' cannot be empty")).toBeInTheDocument();
+    await expect(body.getByText("'team' cannot be empty")).toBeInTheDocument();
+    await expect(body.getByText("'salary' cannot be empty")).toBeInTheDocument();
+
+    // Validator-array progression: notEmpty passes, matches takes over.
+    await userEvent.type(body.getByLabelText(/^Email/), 'not-an-email');
+    await expect(
+      body.getByText("'email' must be a valid email"),
+    ).toBeInTheDocument();
+
+    // Fill everything in; select option lists are portaled too.
+    await userEvent.type(body.getByLabelText(/^Full name/), 'Grace Hopper');
+    await userEvent.clear(body.getByLabelText(/^Email/));
+    await userEvent.type(body.getByLabelText(/^Email/), 'grace.hopper@acme.dev');
+    await userEvent.click(body.getByRole('button', { name: 'Role' }));
+    await userEvent.click(await body.findByRole('option', { name: 'Engineer' }));
+    await userEvent.click(body.getByRole('button', { name: 'Team' }));
+    await userEvent.click(await body.findByRole('option', { name: 'Platform' }));
+    await userEvent.type(body.getByLabelText(/^Salary/), '180000');
+
+    // A valid submit closes the modal and appends the row.
+    await userEvent.click(body.getByRole('button', { name: 'Save' }));
+    await expect(await canvas.findByText('Grace Hopper')).toBeInTheDocument();
+    await expect(canvas.getByText('grace.hopper@acme.dev')).toBeInTheDocument();
+    await expect(canvas.getByText('35 members')).toBeInTheDocument();
+
+    // — Edit: the same modal opens pre-filled; saving updates in place.
+    await userEvent.click(
+      canvas.getByRole('button', { name: 'Edit Grace Hopper' }),
+    );
+    const nameInput = await body.findByLabelText(/^Full name/);
+    await expect(nameInput).toHaveValue('Grace Hopper');
+    await expect(body.getByLabelText(/^Salary/)).toHaveValue('180000');
+    await userEvent.clear(nameInput);
+    await userEvent.type(nameInput, 'Grace Murray Hopper');
+    await userEvent.click(body.getByRole('button', { name: 'Save' }));
+    await expect(
+      await canvas.findByText('Grace Murray Hopper'),
+    ).toBeInTheDocument();
+    await expect(canvas.getByText('35 members')).toBeInTheDocument();
+
+    // — Delete: per-row action asks for confirmation before removing.
+    await userEvent.click(
+      canvas.getByRole('button', { name: 'Delete Grace Murray Hopper' }),
+    );
+    await userEvent.click(
+      await body.findByRole('button', { name: 'Delete member' }),
+    );
+    await waitFor(() =>
+      expect(canvas.queryByText('Grace Murray Hopper')).not.toBeInTheDocument(),
+    );
+    await expect(canvas.getByText('34 members')).toBeInTheDocument();
+  },
+};