@structuralists/scaffolding 0.13.0 → 0.14.0

package/.storybook/preview.tsx

@@ -47,6 +47,9 @@ const preview: Preview = {
     options: {
       storySort: {
         order: [
+          // Demo: polished illustrations of what can be built — first thing
+          // a visitor sees.
+          'Demo',
           // Showcase: how the pieces fit together.
           'Composition',
           // Main library, alphabetical.

package/AGENTS.md

@@ -63,6 +63,17 @@ The Storybook toolbar has a Theme control (paintbrush icon) listing all six
 leaves the attribute unset (prefers-color-scheme fallback) and is the initial
 value, so the vitest story run is unaffected by the toggle.
 
+## The Demo section
+
+The first Storybook section (`'Demo'` in `storySort` in
+`.storybook/preview.tsx`) holds polished showcase compositions — full
+mini-apps built entirely from the library's public pieces, not component API
+docs. Demo stories live in `src/storybook/` (like `Composition.stories.tsx`)
+with titles of the form `Demo/<Name>`, keep their datasets deterministic (no
+`Date.now()`/randomness at render), and double as integration tests via
+`play` functions. Don't add new public components for a demo; compose from
+what exists.
+
 ## Testing
 
 ### Story tests (the main gate)

package/README.md

@@ -53,7 +53,7 @@ export const SignupCard = () => {
 };
 ```
 
-Browse every component (with live controls) in the Storybook: `bun run storybook`. The toolbar's Theme control (paintbrush icon) previews any of the themes above — "System (default)" leaves `data-theme` unset, following system preference.
+Browse every component (with live controls) in the Storybook: `bun run storybook`. The sidebar opens with a **Demo** section — full mini-apps (like a CRUD Team Directory) composed entirely from the library's public pieces, showing what an app scaffolded with it looks like. The toolbar's Theme control (paintbrush icon) previews any of the themes above — "System (default)" leaves `data-theme` unset, following system preference.
 
 ## Consumer notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "main": "./index.ts",
   "types": "./index.ts",
   "exports": {

package/src/storybook/CLAUDE.md

@@ -23,6 +23,15 @@ What still applies: CSS modules, `--ui-*` tokens, no HTML attribute pass-through
 
 If a story util starts getting reached for by app code, that's a signal to build a real primitive, not to promote the story util. A real `Placeholder` for empty states would be a different primitive with proper typography, icon support, and action slots — not this dashed box. Keep the lanes separate.
 
+## Showcase story files live here too
+
+Besides the utils, this folder hosts the cross-component showcase stories:
+`Composition.stories.tsx` (`Composition/…`) and `Demo.stories.tsx` (`Demo/…`
+— the polished mini-app demos; conventions in the root AGENTS.md "The Demo
+section"). They are ordinary stories, not utils: they compose the library's
+public pieces, keep their datasets deterministic, and carry `play`-function
+integration tests. The relaxed util rules above don't apply to them.
+
 ## Adding a new util
 
 - New folder under `src/_StoryUtils/<Name>/` with `index.tsx`.

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();
+  },
+};