@pplancq/react-template 2.8.17 → 2.10.0

package/src/{pages/Demo/Demo.module.scss → demo/ui/pages/DemoHome/DemoHome.module.scss}

@@ -40,7 +40,7 @@
       border-top: 1px solid #ccc;
       border-bottom: 1px solid #ccc;
       background-color: #f8f8f8;
-      content: '';
+      content: "";
     }
 
     &::after {
@@ -49,7 +49,7 @@
       border-top: 1px solid #ccc;
       border-bottom: 1px solid #ccc;
       background-color: #f8f8f8;
-      content: ' ';
+      content: " ";
     }
   }
 }
@@ -83,7 +83,7 @@
     width: 55px;
     height: 5px;
     background-color: #111;
-    content: '';
+    content: "";
   }
 
   &::after {
@@ -94,7 +94,7 @@
     max-width: 255px;
     height: 1px;
     background-color: #333;
-    content: '';
+    content: "";
   }
 }
 
@@ -177,7 +177,7 @@ li {
 code {
   padding: 2px 5px;
   border-radius: 4px;
-  font-family: 'Courier New', monospace;
+  font-family: "Courier New", monospace;
   font-size: 14px;
   background-color: #f8f9fa;
 }

package/src/demo/ui/pages/DemoHome/DemoHome.tsx

@@ -0,0 +1,117 @@
+import image from "@Demo/ui/assets/images/templatePlugins.png";
+import { NavLink } from "@Demo/ui/components/NavLink/NavLink";
+import { demoAppRoutes } from "@Demo/ui/routing/demoAppRoutes";
+import classes from "./DemoHome.module.scss";
+
+export const DemoHome = () => {
+  return (
+    <div className={classes.container}>
+      <div className={classes.bigTitleStyle}>
+        Welcome to Your React Starter Kit <span>Clean Architecture</span>
+      </div>
+
+      <div className={classes.foo}>Vertical slices, shared kernel, and explicit composition.</div>
+
+      <div className={classes.paragraphContainer}>
+        <h1 className={classes.titleStyle}>Overview</h1>
+        <div className={classes.infoSection}>
+          <span className={classes.centredText}>
+            <p className={classes.paragraphStyle}>
+              This template now starts from a <span className={classes.highlight}>Clean Architecture</span> inspired
+              structure with a dedicated <span className={classes.boldText}>app</span> bootstrap layer, a{" "}
+              <span className={classes.boldText}>shared</span> common layer, and a{" "}
+              <span className={classes.boldText}>demo</span> bounded context.
+            </p>
+            <p className={classes.paragraphStyle}>
+              The goal is to help you start from explicit architecture choices while still keeping a runnable example
+              project that demonstrates routing, form handling, data fetching, and dependency injection.
+            </p>
+          </span>
+        </div>
+      </div>
+      <img src={image} alt="Template architecture overview" className={classes.imagePlace} />
+
+      <div className={classes.paragraphContainer}>
+        <h1 className={classes.titleStyle}>Folder Structure</h1>
+        <div className={classes.infoSection}>
+          <div className={classes.tableWrapper}>
+            <table>
+              <thead>
+                <tr>
+                  <th>Folder</th>
+                  <th>Description</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td>
+                    <span className={classes.boldText}>app</span>
+                  </td>
+                  <td>Application bootstrap, routing, providers, config, and global assets.</td>
+                </tr>
+                <tr>
+                  <td>
+                    <span className={classes.boldText}>shared</span>
+                  </td>
+                  <td>Reusable common code with no demo-specific responsibility.</td>
+                </tr>
+                <tr>
+                  <td>
+                    <span className={classes.boldText}>demo</span>
+                  </td>
+                  <td>Example bounded context split into ui, application, domain, and infrastructure.</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>
+      <div className={classes.paragraphContainer}>
+        <h1 className={classes.titleStyle}>Pedagogical Demos</h1>
+        <div className={classes.infoSection}>
+          <p className={classes.paragraphStyle}>
+            Each page below demonstrates a different aspect of the template. The React Query example resolves its use
+            case through Inversify, the React Hook Form example stays focused on UI composition, and the dependency
+            injection example makes the layer boundaries explicit.
+          </p>
+        </div>
+
+        <div className={classes.infoSection}>
+          <p className={classes.paragraphStyle}>
+            <span className={classes.boldText}>React Query demo: </span>
+            fetches remote users through a repository and a use case.
+          </p>
+          <div className={classes.demoStyle}>
+            <NavLink to={demoAppRoutes.reactQuery} className={classes.a}>
+              Run demo
+            </NavLink>
+          </div>
+        </div>
+
+        <div className={classes.infoSection}>
+          <p className={classes.paragraphStyle}>
+            <span className={classes.boldText}>React Hook Form demo: </span>
+            shows a form-first UI example inside the new bounded context.
+          </p>
+          <div className={classes.demoStyle}>
+            <NavLink to={demoAppRoutes.reactHookForm} className={classes.a}>
+              Run demo
+            </NavLink>
+          </div>
+        </div>
+
+        <div className={classes.infoSection}>
+          <p className={classes.paragraphStyle}>
+            <span className={classes.boldText}>Dependency injection demo: </span>
+            explains how app, shared, and demo collaborate through explicit abstractions.
+          </p>
+          <div className={classes.demoStyle}>
+            <NavLink to={demoAppRoutes.dependencyInjection} className={classes.a}>
+              Run demo
+            </NavLink>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/demo/ui/pages/DependencyInjectionDemo/DependencyInjectionDemo.tsx

@@ -0,0 +1,47 @@
+import type { GetArchitecturePrinciplesUseCaseInterface } from "@Demo/application/use-cases/GetArchitecturePrinciplesUseCaseInterface";
+import { DEMO_SERVICES } from "@Demo/serviceIdentifiers";
+import { useService } from "@Shared/ui/hooks/useService/useService";
+import classes from "./DependencyInjectionDemo.module.scss";
+
+export const DependencyInjectionDemo = () => {
+  const getArchitecturePrinciplesUseCase = useService<GetArchitecturePrinciplesUseCaseInterface>(
+    DEMO_SERVICES.GetArchitecturePrinciplesUseCase,
+  );
+  const architecturePrinciples = getArchitecturePrinciplesUseCase.execute();
+
+  return (
+    <div className={classes.container}>
+      <h1 className={classes.title}>Dependency Injection</h1>
+      <hr className={classes.lineStyle} color="#00008f" />
+
+      <div className={classes.fieldsetStyle}>
+        <p className={classes.paragraph}>
+          This page is driven by a use case resolved from the Inversify container. The page knows the use case contract,
+          but it does not instantiate infrastructure classes directly.
+        </p>
+
+        <h1 className={classes.dataTitle}>Clean Architecture Principles</h1>
+        <div className={classes.tableWrapper}>
+          <table>
+            <thead>
+              <tr>
+                <th>Layer</th>
+                <th>Principle</th>
+                <th>Description</th>
+              </tr>
+            </thead>
+            <tbody>
+              {architecturePrinciples.map((principle) => (
+                <tr key={`${principle.layer}-${principle.title}`}>
+                  <td>{principle.layer}</td>
+                  <td>{principle.title}</td>
+                  <td>{principle.description}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/{pages/Demo → demo/ui/pages}/ReactHookFormDemo/ReactHookFormDemo.tsx

@@ -1,13 +1,13 @@
-import { ProfileForm } from '@Front/forms/ProfileForm';
-import { ProfileType } from '@Front/types/profileTypes';
-import { useState } from 'react';
+import type { ProfileFormValues } from "@Demo/application/dtos/ProfileFormValues";
+import { ProfileForm } from "@Demo/ui/forms/ProfileForm/ProfileForm";
+import { useState } from "react";
 
-import classes from './ReactHookFormDemo.module.css';
+import classes from "./ReactHookFormDemo.module.scss";
 
 export const ReactHookFormDemo = () => {
-  const [profileData, setProfileData] = useState<ProfileType>();
+  const [profileData, setProfileData] = useState<ProfileFormValues>();
 
-  const onSubmit = (data: ProfileType) => {
+  const onSubmit = (data: ProfileFormValues) => {
     setProfileData({ ...data });
   };
 
@@ -29,13 +29,13 @@ export const ReactHookFormDemo = () => {
         </p>
         <div className={classes.profileSectionStyle}>
           <fieldset>
-            <legend>Formulaire</legend>
+            <legend>Form</legend>
             <ProfileForm onSubmit={onSubmit} resetForm={resetForm} />
           </fieldset>
 
           {profileData ? (
             <fieldset>
-              <legend>Résultat</legend>
+              <legend>Result</legend>
               <p>E-mail: {profileData.mail} </p>
               <p>First-name: {profileData.firstName} </p>
               <p>Last-name: {profileData.lastName} </p>

package/src/demo/ui/pages/ReactQueryDemo/ReactQueryDemo.module.scss

@@ -0,0 +1,38 @@
+.container {
+  padding: 32px;
+}
+
+.fieldsetStyle {
+  margin-top: 24px;
+  padding: 16px;
+  border: 1px solid black;
+}
+
+.title {
+  padding-top: 16px;
+  font-size: 20px;
+  letter-spacing: 4px;
+  text-align: center;
+  color: #00008f;
+}
+
+.tableWrapper {
+  overflow: auto;
+}
+
+.dataTitle {
+  padding-top: 16px;
+  padding-bottom: 16px;
+  font-size: 20px;
+  letter-spacing: 4px;
+  text-align: center;
+  color: #00008f;
+}
+
+.lineStyle {
+  width: 20%;
+}
+
+.paragraph {
+  padding-top: 16px;
+}

package/src/{pages/Demo → demo/ui/pages}/ReactQueryDemo/ReactQueryDemo.tsx

@@ -1,8 +1,8 @@
-import { useDemoApi } from '@Front/hooks/api/useDemoApi';
-import classes from './ReactQueryDemo.module.scss';
+import { useDemoUsersQuery } from "@Demo/ui/hooks/useDemoUsersQuery/useDemoUsersQuery";
+import classes from "./ReactQueryDemo.module.scss";
 
 export const ReactQueryDemo = () => {
-  const { result, isLoading, isError } = useDemoApi();
+  const { data = [], isLoading, isError } = useDemoUsersQuery();
 
   if (isError) {
     return <div>Error fetching data</div>;
@@ -16,7 +16,8 @@ export const ReactQueryDemo = () => {
       <div className={classes.fieldsetStyle}>
         <p className={classes.paragraph}>
           React Query is a popular library for data management in React applications. It simplifies data query
-          management, caching, data invalidation, and loading state handling.
+          management, caching, data invalidation, and loading state handling. In this template the query calls a use
+          case resolved through Inversify, which keeps the UI layer independent from the infrastructure adapter.
         </p>
         {isLoading ? (
           <h1 className={classes.dataTitle}>Loading...</h1>
@@ -35,7 +36,7 @@ export const ReactQueryDemo = () => {
                   </tr>
                 </thead>
                 <tbody>
-                  {result?.map(eachResult => (
+                  {data.map((eachResult) => (
                     <tr key={eachResult.id}>
                       <td>{eachResult.id}</td>
                       <td>{eachResult.name}</td>

package/src/demo/ui/routing/demoAppRoutes.ts

@@ -0,0 +1,6 @@
+export const demoAppRoutes = Object.freeze({
+  home: "/",
+  reactQuery: "/react-query",
+  reactHookForm: "/react-hook-form",
+  dependencyInjection: "/dependency-injection",
+});

package/src/demo/ui/routing/demoRoutes.tsx

@@ -0,0 +1,31 @@
+import { DemoLayout } from "@Demo/ui/layouts/DemoLayout/DemoLayout";
+import { DemoHome } from "@Demo/ui/pages/DemoHome/DemoHome";
+import { DependencyInjectionDemo } from "@Demo/ui/pages/DependencyInjectionDemo/DependencyInjectionDemo";
+import { ReactHookFormDemo } from "@Demo/ui/pages/ReactHookFormDemo/ReactHookFormDemo";
+import { ReactQueryDemo } from "@Demo/ui/pages/ReactQueryDemo/ReactQueryDemo";
+import { demoAppRoutes } from "@Demo/ui/routing/demoAppRoutes";
+import type { RouteObject } from "react-router";
+
+const toRelativePath = (path: string) => path.replace(/^\//, "");
+
+export const demoRoutes: RouteObject = {
+  element: <DemoLayout />,
+  children: [
+    {
+      index: true,
+      element: <DemoHome />,
+    },
+    {
+      path: toRelativePath(demoAppRoutes.reactQuery),
+      element: <ReactQueryDemo />,
+    },
+    {
+      path: toRelativePath(demoAppRoutes.reactHookForm),
+      element: <ReactHookFormDemo />,
+    },
+    {
+      path: toRelativePath(demoAppRoutes.dependencyInjection),
+      element: <DependencyInjectionDemo />,
+    },
+  ],
+};

package/src/main.ts

@@ -1,10 +1,10 @@
-import AppReact from './bootstrap';
+import AppHTMLElement from "@App/AppHTMLElement";
 
-if (import.meta.env.FRONT_MOCK_ENABLE === 'true') {
-  const { worker } = await import('@Mocks/browser');
+if (import.meta.env.FRONT_MOCK_ENABLE === "true") {
+  const { worker } = await import("@Mocks/browser");
   await worker.start({
-    onUnhandledRequest: 'warn',
+    onUnhandledRequest: "warn",
   });
 }
 
-customElements.define('app-react', AppReact);
+customElements.define("app-react", AppHTMLElement);

package/src/react-app-env.d.ts

@@ -1,3 +1,3 @@
 interface ImportMetaEnv {
-  readonly FRONT_MOCK_ENABLE: 'true' | 'false';
+  readonly FRONT_MOCK_ENABLE: "true" | "false";
 }

package/src/shared/README.md

@@ -0,0 +1,53 @@
+# `shared`
+
+The `shared` folder is the **Shared Kernel** of the application — a DDD term for a small, deliberately
+stable set of code that multiple bounded contexts genuinely need.
+
+Path alias: `@Shared/*`
+
+## What the Shared Kernel is (and is not)
+
+In Domain-Driven Design, a **Shared Kernel** is a portion of the domain model that two or more bounded contexts
+explicitly agree to share. It is held to a higher standard than context-specific code:
+
+- **Small by intention.** Every addition to `shared` is available to every context. A mistake here propagates
+  everywhere. Err on the side of keeping code inside its bounded context.
+- **Stable by discipline.** Changing `shared` can affect all contexts simultaneously. Any modification should
+  be consciously reviewed.
+- **Agnostic by design.** `shared` must contain no feature logic specific to a bounded context. If a file
+  references a demo concept, it belongs in `demo`, not here.
+- **Direction is one-way.** Bounded contexts may import from `shared`. `shared` must never import from a
+  bounded context (`@Demo/*`, etc.).
+
+## What belongs here
+
+- Cross-context contracts and types
+- Generic infrastructure helpers (e.g., HTTP client wrappers)
+- Common application-level abstractions
+- Shared UI utilities that are not tied to any specific context experience
+
+## What should not go here
+
+- Demo pages, forms, layouts, or visual components
+- Feature-specific services that belong inside a bounded context
+- Convenience helpers without clear ownership or a concrete need to share them
+
+## Folder map
+
+| Sub-folder                                      | Role                                                              |
+| ----------------------------------------------- | ----------------------------------------------------------------- |
+| [`domain/`](./domain/README.md)                 | Shared pure contracts, types, and abstractions. Zero dependencies |
+| [`application/`](./application/README.md)       | Shared helpers for orchestration — must not depend on infra or UI |
+| [`infrastructure/`](./infrastructure/README.md) | Shared technical adapters — may depend on external libraries      |
+| [`ui/`](./ui/README.md)                         | Shared React hooks and components — must not depend on infra      |
+
+## Before you add to `shared`
+
+Ask yourself:
+
+1. Does more than one bounded context genuinely need this?
+2. Is it stable enough to be shared without frequent modification?
+3. Does it belong to one of the four Clean Architecture layers?
+
+If the answer to any of these is "not sure", keep it in its bounded context first and promote it to `shared`
+only when the need is proven.

package/src/shared/application/README.md

@@ -0,0 +1,49 @@
+# `shared/application`
+
+The `shared/application` folder contains the **application layer** of the shared kernel — code that
+orchestrates the domain and defines the contracts that infrastructure must fulfill, without doing either
+of those jobs itself.
+
+## What the application layer represents
+
+In Clean Architecture, the **application layer** sits between the domain and the outside world. Its job is to:
+
+1. **Orchestrate use cases.** A use case is a single, named, testable business operation (e.g., "Get the list
+   of demo users"). It calls domain objects and repository interfaces; it does not contain business rules
+   itself — it delegates those to the domain.
+2. **Define infrastructure contracts.** Use cases depend on repository interfaces that are often declared in
+   the domain, but the application layer adds its own interface contracts for services (e.g., caching helpers,
+   event buses).
+3. **Carry data across layer boundaries via DTOs.** A **Data Transfer Object (DTO)** is a plain, typed
+   structure that carries data from one layer to another without exposing internal domain objects.
+
+## Dependency rules
+
+```
+shared/application
+  ✅ can import from: shared/domain
+  ❌ must NOT import from: shared/infrastructure
+  ❌ must NOT import from: shared/ui
+  ❌ must NOT import from: any bounded context
+```
+
+If application code needs something from infrastructure, it should define an interface that infrastructure
+implements (Dependency Inversion).
+
+## What you can put here
+
+- Shared use-case helper base classes or abstract factories
+- Cross-context DTO types that carry data across layer boundaries
+- Common abstractions used by multiple application layers (e.g., a `Result<T, E>` type)
+
+## What you should not put here
+
+- Feature-specific use cases (those belong in their bounded context's `application` folder)
+- React components, hooks, or JSX
+- Infrastructure implementations
+- Domain entities or business rules
+
+## Rule of thumb
+
+If the code describes _what the application does_ (not _how it stores data_ or _how it looks_) and at least
+two bounded contexts could plausibly depend on it, this folder is the right place.

package/src/shared/domain/README.md

@@ -0,0 +1,52 @@
+# `shared/domain`
+
+The `shared/domain` folder contains the **innermost layer** of the shared kernel — the most protected, most
+stable, and most dependency-free part of the codebase.
+
+## What the domain layer represents
+
+In Clean Architecture, the **domain layer** is the heart of the application. It captures the business rules and
+invariants that would still be true even if you replaced the database, the HTTP client, or the UI framework.
+
+In DDD terms, the domain layer hosts:
+
+- **Entities** — objects with a stable identity that persists across state changes (e.g., `User`, `Order`).
+- **Value Objects** — immutable objects defined entirely by their attributes, with no identity (e.g., `Email`,
+  `Money`, `DateRange`). Two value objects with the same attributes are equal.
+- **Domain Services** — stateless operations that belong to the domain but do not fit naturally on a single
+  entity.
+- **Repository Interfaces** — contracts that define _what_ data access operations exist, without specifying
+  _how_ they are implemented. The concrete implementation lives in `infrastructure`.
+- **Domain Errors** — typed, domain-meaningful error cases.
+
+## Absolute constraints
+
+This layer must have **zero external dependencies**:
+
+| Forbidden              | Why                                             |
+| ---------------------- | ----------------------------------------------- |
+| React / JSX            | Domain must not know how it is rendered         |
+| Inversify / decorators | DI is an infrastructure concern                 |
+| HTTP / fetch / axios   | I/O belongs to infrastructure                   |
+| Browser APIs           | Domain must run anywhere (browser, Node, tests) |
+| External NPM packages  | Brings in coupling and upgrade risk             |
+
+Only plain TypeScript (interfaces, types, classes, functions, constants) belongs here.
+
+## Difference between `shared/domain` and a context's own domain
+
+`shared/domain` is the shared kernel's domain — only types or interfaces that are **genuinely used by more
+than one bounded context**. If a domain concept belongs only to `demo`, it lives in `demo/domain`.
+
+## What you can put here
+
+- Shared pure interfaces and type aliases
+- Value-object-like primitives reused across contexts
+- Shared domain error types
+- Repository interface contracts shared by multiple contexts (rare)
+
+## What you should not put here
+
+- Anything with an `import` statement that references React, Inversify, or external libraries
+- Demo-specific entities or repository interfaces
+- Speculative types added "just in case" they might be needed later

package/src/shared/infrastructure/README.md

@@ -0,0 +1,51 @@
+# `shared/infrastructure`
+
+The `shared/infrastructure` folder contains **technical adapters and concrete implementations** that can be
+reused across bounded contexts.
+
+## What the infrastructure layer represents
+
+In Clean Architecture, **infrastructure** is the outermost ring alongside UI. It is the layer that deals with
+the real world: databases, HTTP APIs, browser storage, timers, external SDKs, and so on.
+
+The key principle at work here is the **Dependency Inversion Principle (DIP)**:
+
+> High-level modules (domain, application) should not depend on low-level modules (infrastructure). Both
+> should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.
+
+In practice this means:
+
+- The **domain** defines a `UserRepositoryInterface` describing what it needs ("give me a user by ID").
+- The **infrastructure** provides the concrete `HttpUserRepository` that knows _how_ to fetch the user.
+- The domain and application layers never import `HttpUserRepository` directly — they work through the
+  interface. The DI container wires the concrete class to the interface at startup.
+
+This **Ports and Adapters** pattern (also called Hexagonal Architecture) makes the domain fully testable in
+isolation and lets you swap a real HTTP repository for a mock without touching any business logic.
+
+## What you can put here
+
+- Generic HTTP helpers and API client wrappers (e.g., `fetchApi`)
+- Shared persistence adapters (local storage wrappers, IndexedDB helpers)
+- Generic caching utilities
+- Third-party SDK wrappers that multiple contexts share
+- Base classes for repositories or adapters
+
+## What you should not put here
+
+- Feature-specific repositories or adapters (those belong in the bounded context's `infrastructure` folder)
+- UI code, React components, or hooks
+- Business rules or domain objects
+
+## In this starter
+
+The `http/` sub-folder holds a generic `fetchApi` helper used by the demo's HTTP repositories. It lives in
+`shared/infrastructure` (not in `demo`) because the helper itself is context-agnostic — any bounded context
+could use it to call an HTTP API.
+
+```
+shared/infrastructure/http/
+├── fetchApi.ts          ← generic HTTP adapter
+├── fetchApi.type.d.ts   ← request/response type definitions
+└── constant.ts          ← HTTP-layer constants
+```

package/src/shared/infrastructure/http/constant.ts

@@ -0,0 +1,16 @@
+export enum METHODS {
+  get = "GET",
+  post = "POST",
+  put = "PUT",
+  patch = "PATCH",
+  delete = "DELETE",
+}
+
+export enum HEADERS {
+  contentType = "content-type",
+}
+
+export enum MIME_TYPES {
+  json = "application/json",
+  text = "plain/text",
+}

package/src/{api → shared/infrastructure/http}/fetchApi.ts

@@ -1,5 +1,5 @@
-import type { Json } from '@Front/types/api';
-import { HEADERS, METHODS, MIME_TYPES } from './constant';
+import { HEADERS, METHODS, MIME_TYPES } from "./constant";
+import type { Json } from "./fetchApi.type";
 
 export type FetchApiError = Error & {
   code?: number;
@@ -41,7 +41,7 @@ export const fetchApi = async <T extends Json | string>({
     throw error;
   }
 
-  if ((response.headers.get(HEADERS.contentType) ?? '').includes('json')) {
+  if ((response.headers.get(HEADERS.contentType) ?? "").includes("json")) {
     return JSON.parse(content) as T;
   }