@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/react/component-design.md

@@ -0,0 +1,139 @@
+# Component Design
+
+## Core Rules
+
+- One file, one primary responsibility
+- Prefer feature-driven colocation over organization-by-type
+- Prefer composition over prop drilling
+- Avoid gigantic files — large files signal decomposition is needed
+
+## Feature-Driven Colocation
+
+```
+features/
+  invoices/
+    InvoiceTable.tsx
+    InvoiceTable.test.tsx
+    InvoiceRow.tsx
+    InvoiceFilters.tsx
+    useInvoiceSort.ts
+    invoice.types.ts
+    invoice.api.ts
+```
+
+Do not scatter invoice logic across `components/`, `hooks/`, `types/`, `api/` at the root level.
+
+## DO
+
+- Keep components reasonably scoped — render one thing well
+- Decompose when a file becomes hard to scan
+- Use composition to avoid deep prop drilling
+- Use compound components for tightly coupled UI groups
+- Prefer explicit props over spreading unknown props onto DOM elements
+- Forward refs with `forwardRef` when wrapping native elements
+
+## DO NOT
+
+- Pass more than 4–5 props through intermediate components without reconsidering the design
+- Put business logic directly in JSX — extract to a variable or function
+- Use default exports for everything — named exports improve refactorability
+- Render large lists inline without key management and performance consideration
+
+## Compound Components
+
+Use compound components when a group of UI elements are tightly coupled and share state:
+
+```tsx
+// Usage
+<Tabs defaultValue="overview">
+  <Tabs.List>
+    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+    <Tabs.Trigger value="details">Details</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Panel value="overview"><Overview /></Tabs.Panel>
+  <Tabs.Panel value="details"><Details /></Tabs.Panel>
+</Tabs>
+```
+
+## Prop Design
+
+Define props as a named `interface` above the component. Do not define prop types inline.
+
+```tsx
+// GOOD — named interface above the component
+interface InvoiceTableProps {
+  invoices: Invoice[];
+  onRowClick: (id: string) => void;
+  isLoading?: boolean;
+}
+
+export function InvoiceTable({ invoices, onRowClick, isLoading }: InvoiceTableProps) {
+  ...
+}
+
+// BAD — inline object type
+export function InvoiceTable({
+  invoices,
+  onRowClick,
+}: {
+  invoices: Invoice[];
+  onRowClick: (id: string) => void;
+}) {
+  ...
+}
+
+// BAD — type alias when interface would do
+type InvoiceTableProps = {
+  invoices: Invoice[];
+  onRowClick: (id: string) => void;
+};
+```
+
+Naming: suffix the interface with `Props` and prefix with the component name (`InvoiceTableProps`, not `Props`).
+
+### Variant Props
+
+```tsx
+// BAD — boolean props for variants
+<Button primary large disabled />
+
+// GOOD — explicit variant props
+<Button variant="primary" size="lg" disabled />
+```
+
+### Avoid Spreading Unknown Props
+
+```tsx
+// BAD — spreading unknown props onto DOM
+function Card({ className, ...rest }: unknown) {
+  return <div className={className} {...rest} />;
+}
+
+// GOOD — explicit allowed props
+interface CardProps {
+  className?: string;
+  children: React.ReactNode;
+  onClick?: () => void;
+}
+```
+
+## File Size Signals
+
+Trigger a decomposition review when:
+- A file exceeds ~300 lines
+- A component handles multiple unrelated concerns
+- Props grow beyond 8–10 items
+- JSX exceeds what fits on a single screen
+
+## PRIORITY
+
+```
+Single responsibility > Reuse > Brevity
+```
+
+## See Also
+
+- [hooks.md](hooks.md)
+- [state-management.md](state-management.md)
+- [accessibility.md](accessibility.md)
+- [anti-patterns.md](anti-patterns.md)

package/templates/standards/react/error-boundaries.md

@@ -0,0 +1,195 @@
+# Error Boundaries and Suspense
+
+## Core Rules
+
+- Wrap async / risky UI subtrees in error boundaries — never let a render error crash the whole app
+- Co-locate boundaries with the feature they protect
+- Pair `<Suspense>` with `<ErrorBoundary>` — loading and error states are two sides of the same boundary
+- Provide actionable error UI — explain what failed and what the user can do
+
+## Error Boundaries
+
+React error boundaries catch errors thrown during render, in lifecycle methods, and in constructors of descendant components. They do **not** catch:
+
+- Errors in event handlers (use try/catch or `.catch()`)
+- Errors in async code (handle with TanStack Query's `onError` or `try/catch`)
+- Errors in the boundary itself
+
+Use [`react-error-boundary`](https://github.com/bvaughn/react-error-boundary) — it provides a clean hook + component API and avoids the class component boilerplate:
+
+```tsx
+import { ErrorBoundary } from "react-error-boundary";
+
+function InvoiceErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
+  return (
+    <div role="alert">
+      <p>We couldn't load your invoices. Please try again.</p>
+      <p><small>Error: {error.message}</small></p>
+      <button type="button" onClick={resetErrorBoundary}>Retry</button>
+    </div>
+  );
+}
+
+export function InvoicesPage() {
+  return (
+    <ErrorBoundary FallbackComponent={InvoiceErrorFallback}>
+      <InvoiceList />
+    </ErrorBoundary>
+  );
+}
+```
+
+## Where to Place Boundaries
+
+Place boundaries at meaningful UI seams. There are two layers:
+
+**Route-level** — use TanStack Router's `errorComponent` and `pendingComponent` for failures and loading during route transitions (loader runs, then renders). See [`../tooling/tanstack-router.md`](../tooling/tanstack-router.md).
+
+**Component-level** — use `<ErrorBoundary>` and `<Suspense>` for independent widgets within a page that can fail or load separately from the route as a whole.
+
+Typical layout:
+- One route-level `errorComponent` per route
+- Component-level boundaries around independent widgets (dashboard panels, charts, third-party embeds)
+- One component-level boundary around any subtree that suspends independently of the route loader
+
+```tsx
+// Multiple boundaries — one failing widget doesn't kill the dashboard
+function Dashboard() {
+  return (
+    <Layout>
+      <ErrorBoundary FallbackComponent={WidgetErrorFallback}>
+        <RevenueChart />
+      </ErrorBoundary>
+      <ErrorBoundary FallbackComponent={WidgetErrorFallback}>
+        <RecentInvoices />
+      </ErrorBoundary>
+      <ErrorBoundary FallbackComponent={WidgetErrorFallback}>
+        <NotificationsPanel />
+      </ErrorBoundary>
+    </Layout>
+  );
+}
+```
+
+## Suspense for Loading States
+
+`<Suspense>` declaratively handles loading states for lazy components, suspended TanStack Query calls (with `useSuspenseQuery`), and React Server Components.
+
+```tsx
+import { Suspense, lazy } from "react";
+
+const InvoiceTable = lazy(() => import("./InvoiceTable"));
+
+export function InvoicesPage() {
+  return (
+    <ErrorBoundary FallbackComponent={InvoiceErrorFallback}>
+      <Suspense fallback={<TableSkeleton />}>
+        <InvoiceTable />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+## Pairing Error and Loading Boundaries
+
+Loading + error are two sides of the same boundary. Always declare them together:
+
+```tsx
+<ErrorBoundary FallbackComponent={ErrorFallback}>
+  <Suspense fallback={<LoadingFallback />}>
+    <FeatureContent />
+  </Suspense>
+</ErrorBoundary>
+```
+
+## Suspense with TanStack Query
+
+```tsx
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+function InvoiceTable() {
+  // No isLoading / isError branching — the boundaries handle it
+  const { data: invoices } = useSuspenseQuery({
+    queryKey: ["invoices"],
+    queryFn: fetchInvoices,
+  });
+
+  return <table>...</table>;
+}
+```
+
+## Loading and Empty States
+
+A complete data-fetching UI has four states:
+
+- **Loading** — handled by `<Suspense>` or `isLoading` flag
+- **Error** — handled by `<ErrorBoundary>` or `error` flag
+- **Empty** — no data found; show a helpful empty state, not a blank screen
+- **Success** — render the data
+
+```tsx
+if (invoices.length === 0) {
+  return (
+    <div>
+      <p>No invoices yet.</p>
+      <button type="button" onClick={onCreate}>Create your first invoice</button>
+    </div>
+  );
+}
+```
+
+## Skeleton Loaders
+
+For above-the-fold content, use skeleton loaders (placeholder shapes) instead of spinners — they reduce perceived load time and prevent layout shift.
+
+```tsx
+function TableSkeleton() {
+  return (
+    <div aria-busy="true" aria-label="Loading invoices">
+      {Array.from({ length: 5 }).map((_, i) => (
+        <div key={i} className="h-12 bg-muted animate-pulse rounded mb-2" />
+      ))}
+    </div>
+  );
+}
+```
+
+## Reporting Errors
+
+In an `<ErrorBoundary>`, send caught errors to your error monitoring service:
+
+```tsx
+<ErrorBoundary
+  FallbackComponent={InvoiceErrorFallback}
+  onError={(error, info) => {
+    reportError(error, { componentStack: info.componentStack });
+  }}
+>
+  <InvoiceList />
+</ErrorBoundary>
+```
+
+See [`tooling/observability.md`](../tooling/observability.md) for error monitoring patterns.
+
+## DO NOT
+
+- Wrap the entire app in a single error boundary — a leaf failure should not blank the whole UI
+- Show a generic "Something went wrong" message — give specific, actionable feedback
+- Swallow the error in the fallback without reporting it
+- Use `<Suspense>` for things that don't actually suspend (regular `useState`, non-suspended queries)
+
+## PRIORITY
+
+```
+Co-located boundaries > Single global boundary
+Specific error UI > Generic fallback
+Suspense + ErrorBoundary together > Either alone
+Route-level errorComponent (route transitions) > Component-level ErrorBoundary (widgets)
+```
+
+## See Also
+
+- [`../tooling/tanstack-router.md`](../tooling/tanstack-router.md) — route-level `pendingComponent` / `errorComponent`
+- [`../tooling/tanstack-query.md`](../tooling/tanstack-query.md) — `useSuspenseQuery` for component-level boundaries
+- [`../tooling/observability.md`](../tooling/observability.md) — reporting caught errors to monitoring

package/templates/standards/react/forms.md

@@ -0,0 +1,147 @@
+# Forms
+
+## Core Rules
+
+- Prefer controlled inputs
+- Validate with a shared Zod schema (used on both client and server)
+- Use optimistic updates for responsive UIs
+- Handle loading and error states explicitly
+
+## Preferred Tooling
+
+**TanStack Form** is the preferred choice — integrates with TanStack Query and supports schema validation natively.
+
+**React Hook Form** is an acceptable alternative — mature, well-documented, minimal re-renders.
+
+Do not build custom form state management with `useState` arrays.
+
+## TanStack Form Pattern
+
+```tsx
+import { useForm } from "@tanstack/react-form";
+import { zodValidator } from "@tanstack/zod-form-adapter";
+import { createInvoiceSchema } from "~/features/invoices/invoice.schema";
+
+function CreateInvoiceForm() {
+  const form = useForm({
+    defaultValues: { title: "", amount: 0 },
+    validatorAdapter: zodValidator(),
+    validators: {
+      onChange: createInvoiceSchema,
+    },
+    onSubmit: async ({ value }) => {
+      await createInvoice(value);
+    },
+  });
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
+      <form.Field
+        name="title"
+        children={(field) => (
+          <label>
+            Title
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+            {field.state.meta.errors.map((error) => (
+              <span key={error} role="alert">{error}</span>
+            ))}
+          </label>
+        )}
+      />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+## React Hook Form Pattern
+
+```tsx
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { type CreateInvoice, createInvoiceSchema } from "~/features/invoices/invoice.schema";
+
+function CreateInvoiceForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<CreateInvoice>({
+    resolver: zodResolver(createInvoiceSchema),
+  });
+
+  const onSubmit = async (data: CreateInvoice) => {
+    await createInvoice(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <label htmlFor="title">Title</label>
+      <input id="title" {...register("title")} />
+      {errors.title && <span role="alert">{errors.title.message}</span>}
+      <button type="submit" disabled={isSubmitting}>Create</button>
+    </form>
+  );
+}
+```
+
+## Shared Schema
+
+```ts
+// features/invoices/invoice.schema.ts
+import { z } from "zod";
+
+export const createInvoiceSchema = z.object({
+  title: z.string().min(1, "Title is required").max(200),
+  amount: z.number().positive("Amount must be positive"),
+  dueDate: z.coerce.date().min(new Date(), "Due date must be in the future"),
+});
+
+export type CreateInvoice = z.infer<typeof createInvoiceSchema>;
+```
+
+## Optimistic Updates
+
+```ts
+const { mutate } = useMutation({
+  mutationFn: createInvoice,
+  onMutate: async (newInvoice) => {
+    await queryClient.cancelQueries({ queryKey: ["invoices"] });
+    const previous = queryClient.getQueryData(["invoices"]);
+    queryClient.setQueryData(["invoices"], (old: Invoice[]) => [
+      ...old,
+      { ...newInvoice, id: "temp", status: "pending" },
+    ]);
+    return { previous };
+  },
+  onError: (_, __, context) => {
+    queryClient.setQueryData(["invoices"], context?.previous);
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ["invoices"] });
+  },
+});
+```
+
+## DO NOT
+
+- Build form state with multiple `useState` calls
+- Duplicate validation logic between client and server
+- Submit without disabling the submit button during submission
+- Leave error states unhandled
+
+## PRIORITY
+
+```
+Schema validation > Controlled inputs > Optimistic updates
+```
+
+## See Also
+
+- [`../typescript/validation.md`](../typescript/validation.md) — Zod schema patterns
+- [`accessibility.md`](accessibility.md) — labels, errors, keyboard support
+- [`../tooling/tanstack-query.md`](../tooling/tanstack-query.md) — mutations and cache invalidation
+- [`../tooling/shadcn.md`](../tooling/shadcn.md) — shadcn/ui form components

package/templates/standards/react/hooks.md

@@ -0,0 +1,88 @@
+# Hooks
+
+## Core Rules
+
+- Use hooks to encapsulate reusable stateful behavior
+- Keep hooks composable — hooks should call other hooks, not re-implement logic
+- Before writing a custom hook, check if a solution already exists
+
+## Check First
+
+Before writing a custom hook:
+
+1. Check [`@uidotdev/usehooks`](https://usehooks.com/) — covers most common patterns
+2. Check if TanStack Query, TanStack Router, or Zustand handles your case
+3. Check if a plain utility function (non-hook) is sufficient
+
+## DO
+
+- Name hooks with the `use` prefix
+- Keep hooks focused on a single behavior
+- Compose hooks from smaller hooks
+- Return only what the caller needs — avoid returning large objects when specific values suffice
+- Expose stable references with `useCallback` when callbacks are drilled or passed to external APIs
+
+## DO NOT
+
+- Create hook mini-frameworks with complex internal state machines
+- Wrap `useState` purely to rename it — that is indirection, not abstraction
+- Hide side effects or subscriptions without documenting them
+- Create hooks that only one component ever calls (unless the hook isolates complexity)
+- Use hooks to share instance state between unrelated components — use context or a store instead
+
+## Good Hook Shape
+
+```ts
+// Focused, composable, clear return
+function useDisclosure(defaultOpen = false) {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+  const open = useCallback(() => setIsOpen(true), []);
+  const close = useCallback(() => setIsOpen(false), []);
+  const toggle = useCallback(() => setIsOpen((prev) => !prev), []);
+  return { isOpen, open, close, toggle };
+}
+```
+
+## Bad Hook Shape
+
+```ts
+// BAD — wraps useState purely for renaming
+function useModalOpen() {
+  const [isOpen, setIsOpen] = useState(false);
+  return [isOpen, setIsOpen] as const;
+}
+
+// BAD — hidden side effect with no documentation
+function useUserData(userId: string) {
+  const [data, setData] = useState(null);
+  useEffect(() => {
+    // secretly sends analytics on every render
+    track("user-viewed");
+    fetchUser(userId).then(setData);
+  }, [userId]);
+  return data;
+}
+```
+
+## Composing Hooks
+
+```ts
+function useInvoiceTable(filters: InvoiceFilters) {
+  const { data, isLoading } = useInvoices(filters); // data fetching
+  const { sorted, sortKey, setSortKey } = useSort(data); // sort behavior
+  const { paginated, page, setPage } = usePagination(sorted); // pagination
+  return { invoices: paginated, isLoading, sortKey, setSortKey, page, setPage };
+}
+```
+
+## PRIORITY
+
+```
+Composability > Encapsulation > Abstraction
+```
+
+## See Also
+
+- [use-effect.md](use-effect.md)
+- [memoization.md](memoization.md)
+- [state-management.md](state-management.md)

package/templates/standards/react/memoization.md

@@ -0,0 +1,87 @@
+# Memoization
+
+## Core Rule
+
+Memoize proven performance bottlenecks. Do not memoize speculatively.
+
+## DO
+
+- Use `useCallback` for callbacks passed to heavily optimized child components or external APIs that need stable references
+- Use `useMemo` for computationally expensive operations that have been profiled
+- Use `React.memo` on components that receive stable props and re-render frequently with identical inputs
+
+## DO NOT
+
+- Wrap every function in `useCallback` by default
+- Wrap every value in `useMemo` by default
+- Use memoization to silence exhaustive-deps lint warnings
+- Use `React.memo` on every component
+- Reach for memoization before profiling
+
+## The Cost of Memoization
+
+Every `useMemo` and `useCallback` adds:
+- Memory overhead (the cached value + the dependency array)
+- Comparison overhead (shallow equality check on every render)
+- Cognitive overhead (the reader must understand what is being memoized and why)
+
+These costs are only worth paying when the avoided re-render or recalculation is measurably expensive.
+
+## When `useCallback` Makes Sense
+
+```tsx
+// GOOD — stable callback passed to a memoized child
+const handleRowClick = useCallback((id: string) => {
+  navigate(`/invoices/${id}`);
+}, [navigate]);
+
+return <InvoiceTable onRowClick={handleRowClick} />;
+```
+
+## When `useMemo` Makes Sense
+
+```tsx
+// GOOD — expensive computation, profiled
+const sortedAndFilteredInvoices = useMemo(() => {
+  return invoices
+    .filter(matchesFilters)
+    .sort(bySortKey(sortKey));
+}, [invoices, matchesFilters, sortKey]);
+```
+
+## When Memoization Is Unnecessary
+
+```tsx
+// BAD — trivial computation, memoization is noise
+const label = useMemo(() => `Hello, ${name}`, [name]);
+
+// GOOD
+const label = `Hello, ${name}`;
+```
+
+```tsx
+// BAD — callback not passed anywhere that needs stability
+const handleClick = useCallback(() => setOpen(true), []);
+
+// GOOD
+const handleClick = () => setOpen(true);
+```
+
+## Profiling First
+
+Before adding memoization, use React DevTools Profiler to confirm:
+1. The component is re-rendering
+2. The re-render is caused by the thing you are memoizing
+3. The re-render is causing a measurable performance problem
+
+## PRIORITY
+
+```
+Readability > Micro-optimization
+```
+
+## See Also
+
+- [`component-design.md`](component-design.md) — decomposition over memoization
+- [`anti-patterns.md`](anti-patterns.md) — defensive memoization
+- [`../tooling/observability.md`](../tooling/observability.md) — Web Vitals for real performance signals