@structuralists/scaffolding 0.4.2 → 0.5.1

package/src/forms/useFormState/useFormState.test.tsx

@@ -0,0 +1,134 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFormState } from './useFormState';
+import { allOf, matches, notEmpty } from '../validators/validators';
+
+type SignupForm = {
+  email: string | undefined;
+  nickname: string | undefined;
+};
+
+const initialValues: SignupForm = { email: undefined, nickname: undefined };
+
+describe('useFormState', () => {
+  test('exposes initial values', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    expect(result.current.values).toEqual(initialValues);
+  });
+
+  test('onValueChanges accepts a replacement object', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    act(() => {
+      result.current.onValueChanges({ email: 'a@b.co', nickname: 'will' });
+    });
+    expect(result.current.values.email).toBe('a@b.co');
+  });
+
+  test('onValueChanges accepts an updater function', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, nickname: 'will' }));
+    });
+    expect(result.current.values).toEqual({ email: undefined, nickname: 'will' });
+  });
+
+  test('errors are derived live from the current values', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+      }),
+    );
+    expect(result.current.errors.email).toBe("'email' cannot be empty");
+    expect(result.current.isValid).toBe(false);
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    expect(result.current.errors.email).toBeUndefined();
+    expect(result.current.isValid).toBe(true);
+  });
+
+  test('fields without constraints never produce errors', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+      }),
+    );
+    expect(result.current.errors.nickname).toBeUndefined();
+  });
+
+  test('a form without constraints is always valid', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    expect(result.current.isValid).toBe(true);
+    expect(result.current.errors).toEqual({});
+  });
+
+  test('submit on an invalid form marks the attempt and skips onSubmit', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+        onSubmit,
+      }),
+    );
+    expect(result.current.submitAttempted).toBe(false);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  test('submit on a valid form calls onSubmit with the current values', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: {
+          email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        },
+        onSubmit,
+      }),
+    );
+
+    act(() => {
+      result.current.onValueChanges({ email: 'a@b.co', nickname: undefined });
+    });
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'a@b.co',
+      nickname: undefined,
+    });
+  });
+
+  test('a failed submit followed by a fix allows the next submit through', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+        onSubmit,
+      }),
+    );
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+});

package/src/forms/useFormState/useFormState.ts

@@ -1,14 +1,50 @@
 import { useState } from 'react';
-import type { FormHelpers, FormValuesObject } from './types';
+import type { FormErrors, FormHelpers, FormValuesObject } from './types';
+import type { Refine, Validations } from '../validations/types';
 
-type Args<T extends FormValuesObject> = {
+// `const V` freezes the inferred type of an inline `constraints` object —
+// each validator's precise type and Refinement marker survive without any
+// `as const` at the call site. Constraint objects built outside the call
+// still need `as const satisfies Validations<T>` (see src/forms/CLAUDE.md).
+type Args<T extends FormValuesObject, V extends Validations<T>> = {
   initialValues: T;
+  constraints?: V;
+  onSubmit?: (values: Refine<T, V>) => void;
 };
 
-export const useFormState = <T extends FormValuesObject>(args: Args<T>): FormHelpers<T> => {
-  const { initialValues } = args;
+export const useFormState = <
+  T extends FormValuesObject,
+  const V extends Validations<T> = Validations<T>,
+>(
+  args: Args<T, V>,
+): FormHelpers<T> => {
+  const { initialValues, constraints, onSubmit } = args;
 
   const [values, onValueChanges] = useState<T>(initialValues);
+  const [submitAttempted, setSubmitAttempted] = useState(false);
 
-  return { values, onValueChanges };
+  const errors: FormErrors<T> = {};
+  if (constraints) {
+    for (const key of Object.keys(constraints) as (keyof T & string)[]) {
+      // Field type and validator input are correlated per key, but TS can't
+      // track that through the union of keys — widen the input to unknown.
+      const validator = constraints[key] as
+        | ((val: unknown) => string | null)
+        | undefined;
+      const error = validator?.(values[key]);
+      if (error != null) errors[key] = error;
+    }
+  }
+
+  const isValid = Object.keys(errors).length === 0;
+
+  const submit = () => {
+    setSubmitAttempted(true);
+    if (!isValid) return;
+    // Every constrained field's validator just passed at runtime — exactly
+    // the guarantee Refine<T, V> encodes.
+    onSubmit?.(values as Refine<T, V>);
+  };
+
+  return { values, onValueChanges, errors, isValid, submitAttempted, submit };
 };

package/src/forms/validations/perField.ts

@@ -0,0 +1,11 @@
+// Aggregation entry point for building a `Validations<T>`-shaped constraints
+// object. Runtime identity; the value is in the type: the `const` type
+// parameter freezes each validator's precise type (including `Refinement`
+// markers) instead of letting function types widen. Callers still apply
+// `as const satisfies Validations<FormType>` to shape-check against their
+// form type without losing that precision — see src/forms/CLAUDE.md.
+export const perField = <
+  const V extends Record<string, (val: never) => string | null>,
+>(
+  validations: V,
+): V => validations;

package/src/forms/validations/types.test-d.ts

@@ -1,5 +1,7 @@
 import { describe, it, expectTypeOf } from 'vitest';
-import type { Refinement, Validator } from './types';
+import { perField } from './perField';
+import { allOf, matches, minLength, notEmpty } from '../validators/validators';
+import type { Refine, Refinement, Validations, Validator } from './types';
 
 describe('Validator<Input, Excluded>', () => {
   it('preserves the input type as the call parameter', () => {
@@ -24,3 +26,74 @@ describe('Validator<Input, Excluded>', () => {
     expectTypeOf<Extracted>().toBeNever();
   });
 });
+
+type FormType = {
+  a: string | undefined;
+  b: number;
+  c: string | null;
+};
+
+describe('Refine<T, V>', () => {
+  it('narrows fields whose validator carries a refinement', () => {
+    const constraints = {
+      a: notEmpty('a'),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<{
+      a: string;
+      b: number;
+      c: string | null;
+    }>();
+  });
+
+  it('preserves precision through perField without as const', () => {
+    const constraints = perField({
+      a: notEmpty('a'),
+      c: notEmpty('c'),
+    }) satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<{
+      a: string;
+      b: number;
+      c: string;
+    }>();
+  });
+
+  it('bare validator functions narrow nothing', () => {
+    const constraints = {
+      a: (val: string | undefined) => (val ? null : 'required'),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('a constraints object widened by annotation refines nothing', () => {
+    // Annotating with `: Validations<FormType>` (instead of `satisfies`)
+    // widens every validator to a bare function — markers are lost. This is
+    // the failure mode the `as const satisfies` / const-generic patterns exist
+    // to prevent.
+    const constraints: Validations<FormType> = { a: notEmpty('a') };
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('allOf carries the union of its parts’ refinements', () => {
+    const constraints = {
+      a: allOf(notEmpty('a'), minLength('a', 3), matches('a', /^\S+$/, 'no spaces')),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string>();
+  });
+
+  it('an empty constraints object leaves the form type unchanged', () => {
+    const constraints = {} as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+});

package/src/forms/validations/types.ts

@@ -1,3 +1,5 @@
+import type { FormValuesObject } from '../useFormState/types';
+
 // Phantom marker carried by validators. The runtime value of `__excludes`
 // is meaningless and never read — only its declared type matters. Required
 // (not optional) so validators can't accidentally drop the marker, and so
@@ -13,3 +15,24 @@ export type Refinement<Excluded = never> = {
 // validates at runtime; it just doesn't shrink the field's submit type).
 export type Validator<Input, Excluded = never> =
   ((val: Input) => string | null) & Refinement<Excluded>;
+
+// The constraint for a per-field validation map. Deliberately does NOT demand
+// the `Refinement` marker: a bare `(val) => string | null` is a legal
+// constraint that narrows nothing. Markers on standard-library validators
+// ride along in the *inferred* type of a concrete constraints object and are
+// recovered structurally by `Refine<>`.
+export type Validations<T extends FormValuesObject> = {
+  readonly [K in keyof T]?: (val: T[K]) => string | null;
+};
+
+// Applies each field's validator marker to the form type: the submit-time
+// type. Fields whose validator carries `Refinement<X>` become
+// `Exclude<T[K], X>`; unconstrained fields and bare (marker-less) validators
+// pass through unchanged. Shallow by design — one mapped type, no recursion.
+export type Refine<T extends FormValuesObject, V extends Validations<T>> = {
+  [K in keyof T]: K extends keyof V
+    ? V[K] extends Refinement<infer Excluded>
+      ? Exclude<T[K], Excluded>
+      : T[K]
+    : T[K];
+};

package/src/forms/validators/validators.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect } from 'bun:test';
+import { allOf, matches, min, minLength, notEmpty } from './validators';
+
+describe('notEmpty', () => {
+  const validator = notEmpty('email');
+
+  test('rejects null, undefined, and the empty string', () => {
+    expect(validator(null)).toBe("'email' cannot be empty");
+    expect(validator(undefined)).toBe("'email' cannot be empty");
+    expect(validator('')).toBe("'email' cannot be empty");
+  });
+
+  test('passes any other value', () => {
+    expect(validator('a@b.co')).toBeNull();
+    expect(validator(0)).toBeNull();
+    expect(validator(' ')).toBeNull();
+  });
+});
+
+describe('minLength', () => {
+  const validator = minLength('nickname', 3);
+
+  test('rejects strings shorter than the minimum', () => {
+    expect(validator('ab')).toBe("'nickname' must be at least 3 characters");
+  });
+
+  test('passes strings at or above the minimum', () => {
+    expect(validator('abc')).toBeNull();
+    expect(validator('abcd')).toBeNull();
+  });
+
+  test('passes nullish and empty values — requiredness is notEmpty’s job', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+    expect(validator('')).toBeNull();
+  });
+});
+
+describe('matches', () => {
+  const validator = matches('email', /@/, 'a valid email');
+
+  test('rejects values that fail the pattern', () => {
+    expect(validator('not-an-email')).toBe("'email' must be a valid email");
+  });
+
+  test('passes values matching the pattern', () => {
+    expect(validator('a@b.co')).toBeNull();
+  });
+
+  test('passes nullish and empty values', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+    expect(validator('')).toBeNull();
+  });
+});
+
+describe('min', () => {
+  const validator = min('age', 18);
+
+  test('rejects numbers below the minimum', () => {
+    expect(validator(17)).toBe("'age' must be at least 18");
+  });
+
+  test('passes numbers at or above the minimum', () => {
+    expect(validator(18)).toBeNull();
+    expect(validator(99)).toBeNull();
+  });
+
+  test('passes nullish values', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+  });
+});
+
+describe('allOf', () => {
+  const validator = allOf(
+    notEmpty('email'),
+    minLength('email', 6),
+    matches('email', /@/, 'a valid email'),
+  );
+
+  test('returns the first failing part’s error', () => {
+    expect(validator(undefined)).toBe("'email' cannot be empty");
+    expect(validator('a@b')).toBe("'email' must be at least 6 characters");
+    expect(validator('abcdefg')).toBe("'email' must be a valid email");
+  });
+
+  test('passes when every part passes', () => {
+    expect(validator('a@b.com')).toBeNull();
+  });
+
+  test('accepts bare validator functions alongside marked ones', () => {
+    const noAdmin = (val: string | null | undefined) =>
+      val === 'admin' ? 'reserved' : null;
+    const composed = allOf(notEmpty('name'), noAdmin);
+    expect(composed('admin')).toBe('reserved');
+    expect(composed('will')).toBeNull();
+  });
+});

package/src/forms/validators/validators.ts

@@ -0,0 +1,95 @@
+import type { Refinement, Validator } from '../validations/types';
+
+// Standard-library validators. Each one declares its refinement explicitly —
+// `Validator<Input, Excluded>` — even when it narrows nothing (`never`).
+// The marker is attached with `Object.assign(fn, {} as Refinement<X>)`: a
+// pure type-level tag, never read at runtime.
+
+// Rules out null, undefined, and the empty string. The only refining
+// validator in the baseline set: submit-time type becomes
+// `Exclude<FieldType, null | undefined | ''>`.
+export const notEmpty = (
+  fieldName: string,
+): Validator<unknown, null | undefined | ''> =>
+  Object.assign(
+    (val: unknown) =>
+      val == null || val === '' ? `'${fieldName}' cannot be empty` : null,
+    {} as Refinement<null | undefined | ''>,
+  );
+
+// Minimum string length. Nullish and empty values pass — requiredness is
+// notEmpty's job; compose via allOf. Narrows nothing: TypeScript has no type
+// for "string of at least n characters".
+export const minLength = (
+  fieldName: string,
+  min: number,
+): Validator<string | null | undefined> =>
+  Object.assign(
+    (val: string | null | undefined) =>
+      val != null && val !== '' && val.length < min
+        ? `'${fieldName}' must be at least ${min} characters`
+        : null,
+    {} as Refinement,
+  );
+
+// Regex test. Nullish and empty values pass (compose with notEmpty for
+// requiredness). Narrows nothing.
+export const matches = (
+  fieldName: string,
+  pattern: RegExp,
+  description: string,
+): Validator<string | null | undefined> =>
+  Object.assign(
+    (val: string | null | undefined) =>
+      val != null && val !== '' && !pattern.test(val)
+        ? `'${fieldName}' must be ${description}`
+        : null,
+    {} as Refinement,
+  );
+
+// Minimum numeric value. Nullish passes. Narrows nothing.
+export const min = (
+  fieldName: string,
+  minimum: number,
+): Validator<number | null | undefined> =>
+  Object.assign(
+    (val: number | null | undefined) =>
+      val != null && val < minimum
+        ? `'${fieldName}' must be at least ${minimum}`
+        : null,
+    {} as Refinement,
+  );
+
+type ExcludedOf<V> = V extends Refinement<infer Excluded> ? Excluded : never;
+
+// The composed input is the *intersection* of the parts' inputs: a value the
+// composite accepts must be acceptable to every part. Inferring `I` from the
+// union of function types puts it in contravariant position, which is what
+// makes TS produce the intersection. Computing it this way — rather than as
+// a standalone `Input` type parameter inferred from the arguments — matters:
+// a separate parameter resolves from whichever argument TS visits first
+// (e.g. `unknown` from notEmpty) and then rejects narrower siblings when the
+// call has no outer contextual type, as inside an inline constraints object.
+type InputOf<Validators extends readonly ((val: never) => string | null)[]> =
+  Validators[number] extends (val: infer I) => string | null ? I : never;
+
+// Composes validators on one field: first error wins. The refinement is the
+// union of the parts' refinements — running all of them earns all of their
+// narrowings. `const Validators` keeps each member's precise type so
+// `ExcludedOf` can extract markers; bare functions contribute `never`.
+export const allOf = <
+  const Validators extends readonly ((val: never) => string | null)[],
+>(
+  ...validators: Validators
+): Validator<InputOf<Validators>, ExcludedOf<Validators[number]>> =>
+  Object.assign(
+    (val: InputOf<Validators>) => {
+      for (const validator of validators) {
+        // Safe: each part's declared input is a supertype of the intersection.
+        const error = (validator as (v: unknown) => string | null)(val);
+        if (error != null) return error;
+      }
+      return null;
+    },
+    {} as Refinement<ExcludedOf<Validators[number]>>,
+  );

package/vitest.config.ts

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { defineConfig } from 'vitest/config';
+
+import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
+
+import { playwright } from '@vitest/browser-playwright';
+
+const dirname =
+  typeof __dirname !== 'undefined' ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+
+// Runs every story as a Vitest test in headless Chromium: each story must
+// mount without throwing, its play function (if any) must pass, and the
+// a11y addon reports axe-core violations (see `a11y` in .storybook/preview.tsx).
+// More info: https://storybook.js.org/docs/writing-tests/integrations/vitest-addon
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        extends: true,
+        plugins: [storybookTest({ configDir: path.join(dirname, '.storybook') })],
+        test: {
+          name: 'storybook',
+          browser: {
+            enabled: true,
+            headless: true,
+            provider: playwright({}),
+            instances: [{ browser: 'chromium' }],
+          },
+        },
+      },
+    ],
+  },
+});

package/CLAUDE.md

@@ -1,55 +0,0 @@
-# @structuralists/scaffolding
-
-Generic React component library. Storybook for dev.
-
-Designed to be used to scaffold up an app
-
-## Conventions
-
-### Component prop destructuring
-
-React components must take a single argument named `props` and destructure
-on the first line of the function body — not in the parameter list.
-
-```tsx
-// ✅ correct
-export const Foo = (props: FooProps) => {
-  const { a, b, c } = props;
-
-  return <div>{a}</div>;
-};
-
-// ❌ wrong — destructures in the parameter list
-export const Foo = ({ a, b, c }: FooProps) => {
-  return <div>{a}</div>;
-};
-```
-
-Why: the destructuring line at the top of the body acts as a quick legend
-of what the component reads from its props, scannable without parsing the
-function signature. Keeps the call shape uniform across the package.
-
-### Custom hook arguments
-
-Project-defined hooks must take a single argument named `args` (an object)
-and destructure on the first line of the function body — same shape as the
-component-prop rule above.
-
-```ts
-// ✅ correct
-export const useFoo = (args: UseFooArgs) => {
-  const { a, b, c } = args;
-  // ...
-};
-
-// ❌ wrong — positional args
-export const useFoo = (a: string, b: number, c?: boolean) => {
-  // ...
-};
-```
-
-Why: named args read clearly at the call site (`useFoo({ a, b })`), survive
-reordering, and let new optional fields be added without breaking callers.
-Built-in React hooks (`useState`, `useEffect`, etc.) keep their stock
-positional signatures — this rule applies only to hooks defined in this
-package.