create-aron-app 0.1.6 → 0.1.7

package/templates/.cursor/rules/frontend_architecture_core.mdc

@@ -0,0 +1,495 @@
+---
+description: Core frontend surface architecture — framework-agnostic layer model, MobX patterns, dependency injection, data flow, and component rules. Apply across all frontend apps.
+globs: apps/*/src/**
+alwaysApply: false
+---
+
+# Frontend Surface Architecture — Core
+
+Each surface is an isolated vertical slice. Data flows strictly downward. State is held in observable MobX classes, not component hooks. Components are assembled lazily via dynamic `import()`.
+
+**Key principle: display components are dumb, creates are smart closures, controllers are the brain.**
+
+**When to use a Presenter vs Controller:** Use a **presenter** when a section has its own business logic (mutations, input state, submit handling) that doesn't need to coordinate with other sections. Use a **controller** when state must be shared across multiple sections (e.g. dialog open/close, selected item). Presenters are scoped to a single component; controllers span the feature.
+
+---
+
+## Layer Stack
+
+```
+[route entry]               →  mounts surface, passes bootstrap
+bootstrap.ts                →  param validation + data loading (no UI)
+[feature].tsx               →  surface entry (useRef guard, triggers install, receives bootstrap)
+install.tsx                 →  wiring (lazy-imports creates, seeds layout slots, instantiates controller)
+layout.tsx                  →  LayoutController + reactive Layout shell
+[feature]_controller.ts    →  MobX class managing cross-component state
+[section]_presenter.ts      →  MobX class scoped to one section (business logic, mutations, input state)
+[section]/create.tsx        →  factory returning an observer() component closed over deps
+[section]/[section].tsx    →  pure display component (props only, no hooks — see useForm exception)
+ui/                         →  shared display components scoped to this surface
+```
+
+---
+
+## Folder Structure
+
+```
+surfaces/
+  todo_detail/
+    todo_detail.tsx            # surface entry component (receives bootstrap)
+    bootstrap.ts               # data loading, exports TodoDetailBootstrap
+    install.tsx                # wiring — lazy imports, seeds layout, instantiates controller
+    layout.tsx                 # LayoutController + createLayout()
+    todo_detail_controller.ts  # MobX state class
+    header/
+      create.tsx               # createHeader({ navigate }) — thin component, no display file
+    main/
+      create.tsx               # createMain({ controller, bootstrap })
+      main.tsx                 # pure display: MainProps
+      new_todo_sheet/          # child surface inside parent section (DI tree integrity)
+        create.tsx             # createNewTodoSheet({ controller })
+        new_todo_sheet.tsx     # display with useFormContext (form exception)
+        schema.ts              # Zod schema + inferred type
+    ui/
+      status_badge.tsx         # shared display scoped to this surface
+```
+
+Naming conventions:
+- `Opts` suffix for factory/install arg types: `CreateHeaderOpts`, `InstallTodoDetailOpts`
+- `Props` suffix for component prop types: `HeaderProps`, `MainProps`
+- Controller class scoped to feature: `TodoDetailController`, `DashboardController`
+- `bootstrap` stays as `bootstrap` — one per surface
+- All file names must be **snake_case** (e.g. `todo_detail.tsx`, `new_todo_sheet.tsx`)
+- Use **`All`** for list surfaces and **`Single`** for id-specific surfaces
+- **CRUD naming:** Use `new`, `edit`, `delete` for frontend CRUD component names — never `create` (clashes with the `create.tsx` factory pattern). E.g., `new_todo_sheet/`, `edit_todo_dialog/`, `delete_todo_dialog/`.
+- **Component name de-scoping:** Display components must NOT repeat parent surface/section names. The directory path provides scope. E.g., inside `single_todo/header/`, the display is `header.tsx` exporting `Header` — not `single_todo_header.tsx` exporting `SingleTodoHeader`. Inside `all_todos/main/`, the display is `main.tsx` exporting `Main`.
+
+---
+
+## Bootstrap Pattern
+
+Bootstrap validates params, handles auth redirects, and loads the primary entity for the surface. Bootstrap data is immutable after mount — mutable state lives in the controller.
+
+Rules:
+- One bootstrap per surface; lives in `surfaces/[feature]/bootstrap.ts`
+- Auth failures/redirects belong here, not in components
+- Export `[Feature]BootstrapArgs` and `[Feature]Bootstrap` (inferred from return type)
+
+---
+
+## `[feature].tsx` — Surface Entry Component
+
+Receives `bootstrap` from the route. Creates the layout shell, triggers install once on mount via a `useRef` guard. The `useRef` guard runs install synchronously during the first render — StrictMode safe, no double-fire.
+
+**Dependency injection:** Libraries and framework hooks (e.g. router, toast) must be declared at the surface level and injected downwards into install → creates → controllers/presenters. Never call router hooks inside install or create — obtain them in the surface entry and pass them into install.
+
+Rules:
+- Bootstrap is passed in as a prop from the route — never fetched inside the surface
+- `createLayout()` inside `useMemo` runs once synchronously
+- `useRef` guard runs install synchronously on first render, never again
+- No business logic here — mounting point only
+- **Never instantiate controllers here** — controller creation belongs exclusively in `install.tsx`
+- External deps (router, toast, etc.) are obtained at surface level and injected into install
+
+---
+
+## `install.tsx` — Wiring Function
+
+Single place where all deps are assembled. **Instantiates the controller**, lazy-loads creates. This is the **explicit dependency manifest** for the surface.
+
+Do not use React Context to share the controller. Every component's access to the controller is explicit and traceable through the install chain.
+
+Rules:
+- **`controller` instantiated here** — exactly once, shared across all creates
+- Dynamic `import()` makes each section a separate bundle chunk
+- `install` is a plain function, not a component or hook
+- Child creates that don't need the controller should not receive it — access is explicit
+
+---
+
+## `layout.tsx` — Layout Controller and Shell
+
+Rules:
+- Use `observable.ref` for component slots — MobX only needs reference equality
+- Template structure (flex, grid, spacing) defined here; sections don't know about neighbours
+
+---
+
+## `[feature]_controller.ts` — Controller
+
+Rules:
+- No React imports — pure class
+- Use `computed get` for derived values — components re-render only when the value changes
+- Controllers manage coordination state (what is open, what is selected)
+- **UI state** (dialog open/close, sheet visibility) belongs in the controller, not in `useState` calls inside `create.tsx`
+- Server/async data belongs in the `create` layer, not the controller
+
+---
+
+## `[section]_presenter.ts` — Presenter (component-scoped)
+
+Use when a section has its own business logic (mutations, input state, submit handling) that doesn't need to coordinate with other sections. Calls Convex mutations directly via the exported `convex` singleton — no hooks required.
+
+Rules:
+- No React imports — pure class
+- Call mutations via `convex.mutation(api.xxx, args)` — convex singleton imported from the provider
+- Options injected via constructor — use `Opts` suffix, destructure and assign to private readonly fields
+- `create` keeps only hooks that cannot be moved (e.g. `useFormContext` which requires React context)
+
+---
+
+## `[section]/create.tsx` — Create Function
+
+Factory closing over `controller` and `bootstrap`, returning an `observer()` component.
+
+Rules:
+- Child `create` calls go at the top of the factory body, **outside** the returned observer — run once, not per render
+- Returned component is always wrapped in `observer()`
+- Hook calls (`useQuery`) go **inside** the returned observer
+- Pass `bootstrap` data as `initialData` to seed the query on first render — eliminates loading flash, the Convex subscription takes over reactivity after mount
+- No `useMutation` in creates — mutations belong in controllers (`convex.mutation()`) or presenters; pass action callbacks as props to display components
+- **No React state** (`useState`, `useReducer`) in create.tsx — UI state (open/close, selections) belongs in a controller or presenter. Only third-party hooks (`useQuery`, `useForm`) are acceptable inside the observer.
+- Inline JSX callbacks must be multi-line, never one-liners
+
+---
+
+## Display Components
+
+Pure presentational. Everything via props. No hooks, no business logic, no controller/bootstrap imports.
+
+**Exception — form display components:** Display components that own a form may call `useFormContext()` to access the form provided by the parent `create.tsx` via `<FormProvider>`. Never pass `UseFormReturn` as a prop — always use `FormProvider` + `useFormContext()`.
+
+**Thin component rule:** If the display component is thin (few props, minimal JSX, no complex layout), skip the separate display file. The `create.tsx` alone is sufficient — it directly renders the JSX inside the observer. This avoids unnecessary files for trivial components like a back-button header.
+
+Rules:
+- Callbacks are plain `() => void` props — the `create.tsx` sibling maps controller actions to these props
+- Always use domain type aliases (`Todo`, `TodoId`) — never raw `Doc<"todos">` or `Id<"todos">`
+- Never import `Ent<T>` — it is a backend-only type from `convex-ents` carrying write methods
+- Explicit `return (...)` always — no implicit arrow returns
+
+---
+
+## Schema Pattern
+
+Zod schemas live in `schema.ts` inside the section directory. Type infers are declared **above** the schema object and the type name matches the schema variable name.
+
+```typescript
+export type NewTodoSchema = z.infer<typeof newTodoSchema>;
+export const newTodoSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+});
+```
+
+Rules:
+- `z.infer<typeof schema>` type alias goes **above** the const — hoisting makes this safe
+- Type name matches schema name: `newTodoSchema` → `NewTodoSchema`
+- One schema per file — no duplicate definitions
+
+---
+
+## Form Management
+
+- Schema defined in a `schema.ts` file inside the form's section directory (e.g. `new_todo_sheet/schema.ts`)
+- `useForm` called inside the **create.tsx** factory (inside the observer)
+- `<FormProvider>` wraps the display component so children use `useFormContext()` — **never pass `UseFormReturn` as a prop**
+- Display component calls `useFormContext()` to access the form (this is the one hook exception for display components)
+- Form open/close state belongs in a **controller** (not `useState` inside create.tsx)
+- `controller.closeDialog()` / `controller.closeNewTodoSheet()` called in `onSuccess` — UI transitions in one place
+
+Sub-fields with `useFormContext`:
+```typescript
+export const createTitleField = () => {
+  return () => {
+    const { register, formState: { errors } } = useFormContext<NewTodoSchema>();
+    return <input {...register("title")} />;
+  };
+};
+```
+
+---
+
+## DI Tree Integrity
+
+Child surfaces (dialogs, sheets, drawers) must live **inside the parent section directory** that creates them. This keeps the dependency injection tree traceable — the parent's `create.tsx` lazy-imports the child surface, and the child's deps are a subset of the parent's.
+
+```
+main/
+  create.tsx                 # imports new_todo_sheet/create
+  main.tsx                   # display
+  new_todo_sheet/            # child surface — created from main/create.tsx
+    create.tsx
+    new_todo_sheet.tsx
+    schema.ts
+```
+
+Do not place child surfaces as siblings of the parent section. If `main/create.tsx` creates the sheet, the sheet directory belongs under `main/`.
+
+---
+
+## Component Rules
+
+### Arrow Functions
+
+Always export components as **const arrow functions**:
+
+```typescript
+// Good
+export const ComponentName = ({ prop1, prop2 }: ComponentNameProps) => {
+  return <div />;
+};
+
+// Bad
+export function ComponentName({ prop1, prop2 }: ComponentNameProps) {
+  return <div />;
+}
+```
+
+### Explicit Returns
+
+Always use explicit `return` statements in component functions. No implicit arrow returns for JSX.
+
+```typescript
+// Good
+export const Header = ({ title }: HeaderProps) => {
+  return <h1>{title}</h1>;
+};
+
+// Bad — implicit arrow return
+export const Header = ({ title }: HeaderProps) => <h1>{title}</h1>;
+```
+
+### Named Prop Types
+
+Every component must have a named prop type declared immediately above it. Never inline prop types on the component signature.
+
+```typescript
+// Good
+type HeaderProps = {
+  title: string;
+  onBack: () => void;
+};
+
+export const Header = ({ title, onBack }: HeaderProps) => {
+  return <h1>{title}</h1>;
+};
+
+// Bad — inline type
+export const Header = ({ title }: { title: string }) => {
+  return <h1>{title}</h1>;
+};
+```
+
+### No One-Liner Inline Handlers
+
+Multi-line format is required for all inline JSX callbacks, even simple ones.
+
+```typescript
+// Good
+onToggle={(isCompleted) =>
+  controller.updateTodo({
+    todoId: bootstrap.todoId,
+    isCompleted,
+  })
+}
+
+// Also good — block body when there is more than one expression
+onToggle={(isCompleted) => {
+  controller.updateTodo({
+    todoId: bootstrap.todoId,
+    isCompleted,
+  });
+}}
+
+// Bad — single line
+onToggle={(isCompleted) => controller.updateTodo({ todoId: bootstrap.todoId, isCompleted })}
+```
+
+### Create Factory Props vs Display Props
+
+The `create` factory has two layers for receiving data: **factory opts** (known at creation time) and **observer props** (provided at render time). This applies to all prop types — component slots, IDs, data items, callbacks — not just components.
+
+**Factory opts (`Opts`)** — values known when the factory is called. Closed over in the observer, not re-provided per render:
+
+```typescript
+// header/create.tsx — component slot + controller known at creation time
+type CreateHeaderOpts = {
+  NewTodoSheet: ComponentType;
+};
+
+export const createHeader = ({ NewTodoSheet }: CreateHeaderOpts) => {
+  return observer(() => {
+    return (
+      <div>
+        <h1>Todos</h1>
+        <NewTodoSheet />
+      </div>
+    );
+  });
+};
+
+// parent main/create.tsx
+const NewTodoSheet = createNewTodoSheet({ controller });
+const Header = createHeader({ NewTodoSheet });
+
+return observer(() => {
+  return (
+    <main>
+      <Header />
+      <Main /* ... */ />
+    </main>
+  );
+});
+```
+
+**Observer props (`Props`)** — values that vary per instance or are provided at render time by a parent. Declared as a named type on the observer returned by the factory:
+
+```typescript
+// todo_card/create.tsx — todoId varies per list item
+type CreateTodoCardOpts = {
+  controller: AllTodosController;
+};
+
+type TodoCardProps = {
+  todoId: TodoId;
+};
+
+export const createTodoCard = ({ controller }: CreateTodoCardOpts) => {
+  return observer(({ todoId }: TodoCardProps) => {
+    const { data: todo } = useQuery(/* ... */);
+    return (
+      <TodoCard
+        todo={todo}
+        onDelete={() => {
+          void controller.deleteTodo({ todoId });
+        }}
+      />
+    );
+  });
+};
+
+// parent list/create.tsx — passes per-item data at render time
+const TodoCard = createTodoCard({ controller });
+
+return observer(() => {
+  return (
+    <ul>
+      {todos.map((todo) => (
+        <TodoCard key={todo._id} todoId={todo._id} />
+      ))}
+    </ul>
+  );
+});
+```
+
+Component slots follow the same split — factory opt when known at creation time, observer prop when provided at render time:
+
+```typescript
+// observer prop for a component slot
+type HeaderProps = {
+  SomeComponent: ComponentType;
+};
+
+export const createHeader = ({ navigate }: CreateHeaderOpts) => {
+  return observer(({ SomeComponent }: HeaderProps) => {
+    return (
+      <div>
+        <SomeComponent />
+        <Header
+          onBack={() => {
+            navigate("/todos");
+          }}
+        />
+      </div>
+    );
+  });
+};
+```
+
+**Bad** — component slots or dynamic data on a pure display component:
+
+```typescript
+// Bad — display component receiving pre-rendered ReactNode
+type HeaderProps = {
+  toolSlot: React.ReactNode;
+};
+
+export const Header = ({ toolSlot }: HeaderProps) => {
+  return (
+    <div>
+      <h1>Todos</h1>
+      {toolSlot}
+    </div>
+  );
+};
+
+<Header toolSlot={<NewTodoSheet />} />
+```
+
+Rules:
+- **Factory opts** for values known at creation time (controller, bootstrap, component slots created by the parent)
+- **Observer props** for values that vary per instance or are provided at render time (IDs, per-item data, component slots passed down dynamically)
+- Component slots are always `ComponentType`, never `ReactNode` — named after the component they receive
+- Pure display components receive only plain data props and `() => void` callbacks — never `ComponentType` slots, IDs that drive data fetching, or any logic that belongs in `create.tsx`
+
+### Domain Type Imports
+
+Always import the aliased domain type from the entity's `types.ts`. Never use raw Convex generics in frontend code.
+
+```typescript
+// Good
+import type { Todo, TodoId } from "@/api/todos/types";
+
+// Bad — raw Convex generics
+import type { Doc, Id } from "@/api/_generated/dataModel";
+const todoId: Id<"todos"> = ...;
+const todo: Doc<"todos"> = ...;
+```
+
+Each entity's `types.ts` exports `EntityId = Id<"entity">` and `Entity = Doc<"entity">`. Import from there.
+
+`Ent<T>` is a backend-only type from `convex-ents`. Never import it in frontend files — use the `Entity` alias (e.g. `Todo`) from the domain `types.ts` instead.
+
+### Path Alias Imports
+
+Always use path alias imports (`@/...`). **No relative imports** — not even within the same feature folder. Every `import` statement must use the `@/` alias.
+
+```typescript
+// Good — always alias
+import { Button } from "@/ui/base/button";
+import type { TodoId } from "@/api/todos/types";
+import { createHeader } from "@/web/surfaces/todos/all_todos/header/create";
+import { createNewTodoSheet } from "@/web/surfaces/todos/all_todos/main/new_todo_sheet/create";
+
+// Bad — relative paths (even within same feature)
+import { createLayout } from "./layout";
+import type { AllTodosBootstrap } from "../bootstrap";
+import { Main } from "./main";
+```
+
+---
+
+## Install Timing Consistency
+
+**Layout-mounted surfaces** (sidebar, persistent chrome): Use `useEffect` to call install once. The layout persists across navigations, so `useEffect` with a stable `layout` dependency is appropriate.
+
+**Route-mounted surfaces** (pages): Use the synchronous `useRef` install guard. The surface mounts fresh per navigation, so synchronous install during first render avoids flicker.
+
+Pick the correct pattern based on mount context and apply it consistently across all surfaces of the same type.
+
+---
+
+## Quick Reference
+
+| File | Can use hooks? | Imports controller? |
+|---|---|---|
+| Route entry | Framework-dependent | No |
+| `bootstrap.ts` | No | No |
+| `[feature].tsx` | `useRef`, `useMemo`, router hooks | No |
+| `install.tsx` | No | Instantiates it |
+| `layout.tsx` | No | No |
+| `[name]_controller.ts` | No (pure class) | — |
+| `[section]_presenter.ts` | No (pure class) | — |
+| `[section]/create.tsx` | Yes (inside observer) | Yes (via closure) |
+| `[section]/[name].tsx` | `useFormContext` only | No |
+| `ui/[name].tsx` | No | No |