create-aron-app 0.1.7 → 0.1.8

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

@@ -1,495 +0,0 @@
----
-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 |