@structuralists/scaffolding 0.0.2 → 0.1.1

package/.storybook/main.ts

@@ -3,7 +3,7 @@ import type { StorybookConfig } from '@storybook/react-vite';
 const config: StorybookConfig = {
   framework: '@storybook/react-vite',
   stories: ['../src/**/*.stories.@(ts|tsx)'],
-  addons: ['@storybook/addon-essentials', '@storybook/addon-storysource'],
+  addons: ['@storybook/addon-docs'],
 };
 
 export default config;

package/.storybook/preview.tsx

@@ -1,10 +1,45 @@
-import type { Preview } from '@storybook/react';
+import type { Preview } from '@storybook/react-vite';
 import { MemoryRouter } from 'react-router';
+import * as prettier from 'prettier/standalone';
+import * as babel from 'prettier/plugins/babel';
+import * as estree from 'prettier/plugins/estree';
 import '../tokens.css';
 
+// Storybook's useTransformCode re-invokes transform on every render with no
+// dep array; memoizing by input lets cache hits return a string synchronously
+// and skip the "Transforming..." placeholder that causes the flicker.
+const formatCache = new Map<string, string>();
+
 const preview: Preview = {
   parameters: {
     layout: 'padded',
+
+    docs: {
+      codePanel: true,
+      source: {
+        type: 'dynamic',
+        transform: (code: string) => {
+          const cached = formatCache.get(code);
+          if (cached !== undefined) return cached;
+
+          return prettier
+            .format(code, {
+              parser: 'babel',
+              plugins: [babel, estree],
+              printWidth: 80,
+              singleQuote: true,
+            })
+            .then((formatted) => {
+              formatCache.set(code, formatted);
+              return formatted;
+            })
+            .catch(() => {
+              formatCache.set(code, code);
+              return code;
+            });
+        },
+      },
+    }
   },
   decorators: [
     (Story) => (

package/CLAUDE.md

@@ -28,3 +28,28 @@ export const Foo = ({ a, b, c }: FooProps) => {
 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.