@structuralists/scaffolding 0.5.0 → 0.6.0

package/src/forms/useFormState/useFormState.ts

@@ -1,5 +1,14 @@
-import { useState } from 'react';
-import type { FormErrors, FormHelpers, FormValuesObject } from './types';
+import { useEffect, useRef, useState } from 'react';
+import { createFormDebugger } from './FormDebugger';
+import type { FormDebuggerComponent } from './FormDebugger';
+import { createSnapshotStore } from './snapshotStore';
+import type { SnapshotStore } from './snapshotStore';
+import type {
+  FormDebugSnapshot,
+  FormErrors,
+  FormHelpers,
+  FormValuesObject,
+} from './types';
 import type { Refine, Validations } from '../validations/types';
 
 // `const V` freezes the inferred type of an inline `constraints` object —
@@ -38,6 +47,31 @@ export const useFormState = <
 
   const isValid = Object.keys(errors).length === 0;
 
+  // Debugger plumbing: one store + one component per hook instance, created
+  // lazily on first render. The component's identity must be stable across
+  // renders — recreated each render it would remount (and lose its
+  // open/closed state) on every keystroke.
+  const debugRef = useRef<{
+    store: SnapshotStore<FormDebugSnapshot<T>>;
+    Debugger: FormDebuggerComponent;
+  } | null>(null);
+  if (debugRef.current === null) {
+    const store = createSnapshotStore<FormDebugSnapshot<T>>({
+      values,
+      errors,
+      isValid,
+      submitAttempted,
+    });
+    debugRef.current = { store, Debugger: createFormDebugger(store) };
+  }
+  const { store, Debugger } = debugRef.current;
+
+  // Publish after every commit. With no debugger window subscribed this is a
+  // field write and an empty notify loop — effectively free.
+  useEffect(() => {
+    store.publish({ values, errors, isValid, submitAttempted });
+  });
+
   const submit = () => {
     setSubmitAttempted(true);
     if (!isValid) return;
@@ -46,5 +80,13 @@ export const useFormState = <
     onSubmit?.(values as Refine<T, V>);
   };
 
-  return { values, onValueChanges, errors, isValid, submitAttempted, submit };
+  return {
+    values,
+    onValueChanges,
+    errors,
+    isValid,
+    submitAttempted,
+    submit,
+    Debugger,
+  };
 };

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.