Scaffold a frontend module

The rules are in docs/standards/frontend-architecture.md, in the sections "Layer definitions", "Import matrix", "Naming" and "Tests".

Names

• <feature> is the module name in kebab-case. Example: card-detail.
• <Feature> is the same name in PascalCase. Example: CardDetail.
• <featureCamel> is the same name in camelCase. Example: cardDetail.

Before you start

1. Get the module name from the argument of the command.
2. Make sure that the name is kebab-case. If the name is not kebab-case, stop and tell the user.
3. Make sure that src/web/modules/<feature>/ does not exist. If it exists, stop and tell the user.

Procedure

1. Create the six layer folders. Use these six commands. Do not use brace expansion.

   mkdir -p src/web/modules/<feature>/views
   mkdir -p src/web/modules/<feature>/containers
   mkdir -p src/web/modules/<feature>/components
   mkdir -p src/web/modules/<feature>/hooks
   mkdir -p src/web/modules/<feature>/domain
   mkdir -p src/web/modules/<feature>/queries

2. Write src/web/modules/<feature>/views/<Feature>View.tsx with this content:

   export function <Feature>View() {
     return (
       <section className="flex flex-col gap-2">
         <h1 className="text-lg font-semibold"><Feature></h1>
       </section>
     );
   }

3. Write src/web/modules/<feature>/domain/<feature>-label.ts with this content:

   /**
    * Return the display label for one <feature> item.
    */
   export function <featureCamel>Label(title: string): string {
     return title.trim() || "Untitled";
   }

4. Write src/web/modules/<feature>/domain/<feature>-label.test.ts with this content:

   import { test } from "node:test";
   import assert from "node:assert/strict";
   import { <featureCamel>Label } from "./<feature>-label.js";
   
   test("<featureCamel>Label trims the title", () => {
     assert.equal(<featureCamel>Label("  One  "), "One");
   });
   
   test("<featureCamel>Label returns Untitled for an empty title", () => {
     assert.equal(<featureCamel>Label("   "), "Untitled");
   });

5. Write src/web/modules/<feature>/queries/<feature>-queries.ts with this content. This file holds the query key factory.

   export const <featureCamel>Keys = {
     all: ["<feature>"] as const,
     detail: (id: string) => ["<feature>", "detail", id] as const,
   };

6. Write src/web/modules/<feature>/queries/<feature>-queries.test.ts with this content:

   import { test } from "node:test";
   import assert from "node:assert/strict";
   import { <featureCamel>Keys } from "./<feature>-queries.js";
   
   test("<featureCamel>Keys.detail starts with the module key", () => {
     assert.deepEqual(<featureCamel>Keys.detail("1"), ["<feature>", "detail", "1"]);
   });

7. Write src/web/modules/<feature>/index.ts with this content:

   export { <Feature>View } from "@/modules/<feature>/views/<Feature>View";

Rules for the next files

1. Put each file in one of the six layer folders. Do not put other files in the module root. The module root holds only index.ts.
2. Export only views and queryOptions factories from index.ts.
3. Import a file in another folder with the @/ alias. Import a file in the same layer folder with a relative path.
4. Do not import a sibling module.
5. Do not use the JSX style prop. Do not write a hex colour. Use Tailwind token classes.
6. Call fetch and import src/web/lib/http.ts only in queries/.
7. Give each new .tsx file a PascalCase name. Give each new .ts file a kebab-case name.
8. Put a <subject>.test.ts file next to each domain file and each *-queries.ts file.
9. Do not add comments to a .tsx file. Add a JSDoc block only to a function in a .ts file.

Checks

1. Format the new files with env -u NODE_ENV npx oxfmt <each new file>. A long name can make a line too long for the template layout.

2. Run these commands. Each command must pass.

   env -u NODE_ENV npm run format:check
   env -u NODE_ENV npm run lint
   env -u NODE_ENV npm run typecheck
   env -u NODE_ENV npm run depcruise
   env -u NODE_ENV npm run test

3. Run env -u NODE_ENV npm run deadcode. Until a route imports the module barrel, knip reports the files of the new module. This result is correct. Do not add a route for this reason. Add a route only when the user asks for it.
4. Git does not keep an empty folder. The empty layer folders stay on disk until a file goes into them.