@pplancq/react-template 2.8.17 → 2.9.0

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/{api → shared/infrastructure/http}/fetchApi.ts

@@ -1,4 +1,4 @@
-import type { Json } from '@Front/types/api';
+import type { Json } from './fetchApi.type';
 import { HEADERS, METHODS, MIME_TYPES } from './constant';
 
 export type FetchApiError = Error & {

package/src/shared/ui/README.md

@@ -0,0 +1,50 @@
+# `shared/ui`
+
+The `shared/ui` folder contains **UI-layer code that is genuinely reusable across bounded contexts** — hooks,
+utilities, and components that carry no feature identity.
+
+## What the UI layer represents
+
+In Clean Architecture, the **UI layer** is the outermost ring. Its job is to:
+
+- Present data to the user
+- Translate user actions into application-layer calls (use cases)
+- Never execute business logic or call infrastructure directly
+
+The UI layer depends on the application layer (via use cases and DTOs) and occasionally on domain types.
+It must **never** import from `infrastructure`.
+
+## What belongs here
+
+### `hooks/useService`
+
+`useService` is the bridge between the Inversify DI container and React components:
+
+```ts
+const myService = useService<MyServiceInterface>(SERVICE_IDENTIFIER);
+```
+
+It reads the container from `ServiceContext` (provided by `ServiceProvider` in `app/providers`) and resolves
+the requested service. This pattern means React components declare _what they need_ without knowing _how it is
+constructed_. Swapping a real implementation for a test double requires only a different container binding —
+zero changes to the component.
+
+`useService` lives in `shared/ui` because any bounded context can use it to resolve its own services.
+
+## Dependency rules
+
+```
+shared/ui
+  ✅ can import from: shared/domain, shared/application
+  ❌ must NOT import from: shared/infrastructure
+  ❌ must NOT import from: any bounded context
+```
+
+The UI layer must not call infrastructure directly — if it needs external data it does so through a use case or
+React Query integration, not by importing an HTTP adapter.
+
+## What you should not put here
+
+- Demo-specific visual components (buttons, forms, layouts, logos, nav links)
+- Feature-specific React hooks
+- Infrastructure adapters or API calls

package/src/shared/ui/hooks/useService/useService.ts

@@ -0,0 +1,13 @@
+import { ServiceContext } from '@App/providers/ServiceProvider/ServiceContext';
+import type { ServiceIdentifier } from 'inversify';
+import { useContext } from 'react';
+
+export const useService = <T = unknown>(serviceIdentifier: ServiceIdentifier<T>): T => {
+  const context = useContext(ServiceContext);
+
+  if (!context) {
+    throw new Error('useService must be used within a ServiceProvider');
+  }
+
+  return context.container.get<T>(serviceIdentifier);
+};

package/tsconfig.json

@@ -23,7 +23,9 @@
     "noEmit": true,
     "jsx": "react-jsx",
     "paths": {
-      "@Front/*": ["./src/*"],
+      "@App/*": ["./src/app/*"],
+      "@Shared/*": ["./src/shared/*"],
+      "@Demo/*": ["./src/demo/*"],
       "@Mocks/*": ["./mocks/*"]
     }
   },

package/vitest.config.mts

@@ -18,7 +18,11 @@ export default defineConfig(({ mode }) => {
       environment: 'jsdom',
       setupFiles: 'vitest.setup.ts',
       clearMocks: true,
-      css: false,
+      css: {
+        modules: {
+          classNameStrategy: 'non-scoped',
+        },
+      },
       reporters: ['default', 'junit', 'vitest-sonar-reporter'],
       outputFile: {
         'vitest-sonar-reporter': 'sonar-report.xml',

package/src/api/README.md

@@ -1,65 +0,0 @@
-# 📁 api
-
-The "api" folder is designed to handle calls to native APIs using the fetch function. These calls are essential for retrieving real-time data from external sources, such as remote servers or web services.
-
-## 📑 Table of Contents
-
-- [Folder Organization](#folder-organization)
-- [Usage](#usage)
-- [Error Handling](#error-handling)
-- [Security](#security)
-- [Documentation](#documentation)
-- [Testing](#testing)
-- [Best Practice](#best-practice)
-
-## <span id="folder-organization">Folder Organization</span>
-
-The "api" folder can be organized as follows :
-
-1. **API Endpoints** : Create a separate file for each API you are calling. For example, if you have a user management API and a data retrieval API, you can have the files `users.ts` and `data.ts` to handle these respective calls.
-
-2. **Call Functions** : Inside each API file, define dedicated functions to make `fetch` requests to the corresponding endpoints. These functions can also include handling responses and errors.
-
-## <span id="usage">🧑🏻‍💻 Usage</span>
-
-When you need to make a call to a native API, import the appropriate function from the "api" folder into your code. For example:
-
-```javascript
-import { getUsers } from '@Front/api/users';
-
-const users = getUsers();
-```
-
-## <span id="error-handling">Error Handling</span>
-
-Ensure proper error handling in your API call functions. You can use error handling mechanisms such as promises or `try/catch` to capture and handle potential errors when making API calls.
-
-## <span id="security">Security</span>
-
-Be mindful of security when interacting with external APIs. Avoid storing sensitive information, such as API keys, directly in your source code. Use environment variables or external configuration files to manage this sensitive information securely.
-
-## <span id="documentation">Documentation</span>
-
-Document each API call function, specifying expected parameters, possible responses, and any relevant information about the API itself.
-
-## <span id="testing">Testing</span>
-
-Whenever possible, write unit tests to validate the behavior of API call functions. This will ensure that API calls work correctly and quickly detect potential issues.
-
-## <span id="best-practice">🎖️ Best Practice</span>
-
-It is recommended to implement a custom fetch function that serves as an enhancement or override of the default fetch function. This can be particularly useful for incorporating common configurations, such as adding headers like an API token.
-
-Consider the following example of a custom fetch function :
-
-```javascript
-// Custom fetch function with common configurations
-export const fetchApi = (uri, options) => {
-  const headers = new Headers(options.headers ?? []);
-  headers.append('x-api-key', '<token-api>');
-
-  return fetch(uri, { ...options, headers });
-};
-```
-
-In this example, the fetchApi function extends the default fetch function by automatically including an API token in the request header. This practice helps centralize common configurations and promotes consistency across your application.

package/src/api/demoApi.ts

@@ -1,10 +0,0 @@
-import { fetchApi } from '@Front/api/fetchApi';
-import type { Users } from '@Front/types/demoApi';
-
-export const fetchDemoApi = async () => {
-  const users = await fetchApi<Users>({
-    path: 'https://jsonplaceholder.typicode.com/users',
-  });
-
-  return users.map(user => ({ ...user, username: user.username.toUpperCase(), email: user.email.toLowerCase() }));
-};

package/src/assets/README.md

@@ -1,54 +0,0 @@
-# 📁 assets
-
-The "assets" folder is a commonly used directory in a React application to store static resources such as images, CSS files, fonts, JSON data files, icons, and other non-JavaScript files used in your application. These resources are typically needed to style and customize the user interface of your application.
-
-## 📑 Table of Contents
-
-- [Why Use an "assets" Folder](#folder-organization)
-- [Usage Example](#usage)
-- [Best Practice](#best-practice)
-
-## <span id="folder-organization">Why Use an "assets" Folder?</span>
-
-1. **Organization** : By storing your static resources in a separate folder named "assets," you maintain a cleaner and more organized project structure. This clearly separates static content from JavaScript files.
-
-2. **Ease of Access** : Files in the "assets" folder can be easily referenced in your code using relative paths. This simplifies the inclusion of images, CSS, fonts, and other resources in your React components.
-
-3. **Performance Optimization** : By storing static resources like images in an "assets" folder, you can optimize these files for better performance, for example, by using image compression tools.
-
-## <span id="usage">🧑🏻‍💻 Usage Example </span>
-
-To use an image stored in the "assets" folder, you can reference its relative path in your JavaScript or JSX code like this:
-
-```javascript
-import logo from '@Front/assets/images/logo.png';
-
-export const App = () => {
-  return (
-    <div>
-      <img src={logo} alt="Logo" />
-      {/* ... other elements of the application */}
-    </div>
-  );
-};
-```
-
-## <span id="best-practice">🎖️ Best Practice</span>
-
-When it comes to styling and managing assets, adopting the following practices can enhance maintainability and structure in your project:
-
-### - Global CSS Rules
-
-Define all global CSS rules, such as resets, fonts, and general styling, in a centralized stylesheet (in the css folder under the assets ).
-
-This ensures consistency across your entire application.
-
-### - CSS Modules
-
-For component-specific styles, leverage CSS Modules to encapsulate styles within the component scope.
-
-This helps prevent unintentional styling conflicts and promotes a modular approach to styling.
-
----
-
-**_By adhering to these practices, you create a clear separation between global styles and component-specific styles, making your codebase more maintainable and scalable._**

package/src/components/App/App.tsx

@@ -1,18 +0,0 @@
-import { queryClient } from '@Front/config';
-import { withProvider } from '@Front/providers';
-import { createRouter } from '@Front/routing/routerFactory';
-import { RouterProvider } from 'react-router';
-
-import '@Front/assets/css';
-
-type AppProps = {
-  basename?: string;
-};
-
-const AppWithProviders = withProvider(RouterProvider);
-
-export const App = ({ basename }: AppProps) => {
-  const router = createRouter({ basename });
-
-  return <AppWithProviders queryClient={queryClient} router={router} />;
-};

package/src/components/App/index.ts

@@ -1 +0,0 @@
-export { App } from './App';

package/src/components/Footer/Footer.tsx

@@ -1,16 +0,0 @@
-import logo from '@Front/assets/images/logo.png';
-import { Logo } from '@Front/ui/atoms/Logo';
-import { Link } from 'react-router';
-
-import classes from './Footer.module.css';
-
-export const Footer = () => {
-  return (
-    <div className={classes.container}>
-      <hr />
-      <Link to="/">
-        <Logo size="50px" src={logo} alt="logo" />
-      </Link>
-    </div>
-  );
-};

package/src/components/Footer/index.ts

@@ -1 +0,0 @@
-export { Footer } from './Footer';

package/src/components/Header/Header.tsx

@@ -1,17 +0,0 @@
-import logo from '@Front/assets/images/logo.png';
-import { Logo } from '@Front/ui/atoms/Logo';
-import { Navigation } from '@Front/ui/molecules/Navigation';
-import { Link } from 'react-router';
-
-import classes from './Header.module.css';
-
-export const Header = () => {
-  return (
-    <div className={classes.container}>
-      <Link to="/">
-        <Logo size="50px" src={logo} alt="logo" />
-      </Link>
-      <Navigation links={[{ label: 'Demo', url: '/' }]} />
-    </div>
-  );
-};

package/src/components/Header/__tests__/__snapshots__/Header.test.tsx.snap

@@ -1,37 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`Header Component > should render the Header component correctly 1`] = `
-<div>
-  <div
-    class="_container_a5b977"
-  >
-    <a
-      data-discover="true"
-      href="/"
-    >
-      <img
-        alt="logo"
-        class="_logoStyle_9e86a7"
-        src="/src/assets/images/logo.png"
-        style="width: 50px;"
-      />
-    </a>
-    <nav>
-      <ul
-        class="_navList_eee024"
-      >
-        <li>
-          <a
-            aria-current="page"
-            class="_a_eee024 active"
-            data-discover="true"
-            href="/"
-          >
-            Demo
-          </a>
-        </li>
-      </ul>
-    </nav>
-  </div>
-</div>
-`;

package/src/components/Header/index.ts

@@ -1 +0,0 @@
-export { Header } from './Header';

package/src/components/README.md

@@ -1,33 +0,0 @@
-# 📁 components
-
-The "components" folder is a crucial element of any React application. It is used to organize and store reusable components that make up the user interface of your application. React components are self-contained pieces of the user interface, each having its own logic and rendering.
-
-## 📑 Table of Contents
-
-- [Why Use a "components" Folder](#folder-organization)
-- [Usage](#usage)
-
-## <span id="folder-organization">Why Use a "components" Folder?</span>
-
-1. **Modularity** : Components can be reused across different parts of your application. This promotes code modularity and allows you to maintain your application more efficiently.
-
-2. **Clarity** : By grouping all your components in a "components" folder, it is easier to understand the structure of your application. It also facilitates the search and management of components.
-
-3. **Better Organization** : Organizing components in a dedicated folder helps clearly distinguish components from other elements of the application, such as styles, images, or configuration files.
-
-## <span id="usage">🧑🏻‍💻 Usage Example </span>
-
-Suppose you have a "Header.js" component in the "components" folder. You can import and use it in other parts of your application like this:
-
-```javascript
-import Header from '@Front/components/Header';
-
-export const App = () => {
-  return (
-    <div>
-      <Header />
-      {/* ... other elements of the application */}
-    </div>
-  );
-};
-```

package/src/config/README.md

@@ -1,63 +0,0 @@
-# 📁 config
-
-The "config" folder is intended to store all important configurations and utilities needed for our React project. Bringing together this information in one place makes managing configuration settings easier and ensures better code organization.
-
-## 📑 Table of Contents
-
-- [Folder Organization](#folder-organization)
-- [Content Example](#content-example)
-- [Usage](#usage)
-- [Best Practice](#best-practice)
-
-## <span id="folder-organization">Folder Organization</span>
-
-Within the "config" folder, you can find the following elements:
-
-1. **Configuration Files** : Files containing variables and configuration parameters, such as `apiConfig.ts` for configurations related to API calls, `appConfig.ts` for general application settings, `queryClientConfig.ts` for react-query-related configuration, etc.
-
-2. **Configuration Scripts** : Scripts or utilities that facilitate dynamic configuration of the application, such as theme configuration, language management, etc.
-
-## <span id="content-example">Content Example</span>
-
-Here is an example folder structure for "config":
-
-```
-📁config/
-├── 📄 apiConfig.ts
-├── 📄 appConfig.ts
-├── 📄 queryClientConfig.ts
-├── 📄 translationConfig.ts
-```
-
-## <span id="usage">🧑🏻‍💻Usage in the Project</span>
-
-When you need to access a specific configuration in your code, import the appropriate file from the "config" folder. For example:
-
-```javascript
-// Example of using an API configuration
-import { apiEndpoint } from '@Front/config/apiConfig';
-
-// Example of using a react-query configuration
-import { queryClient } from '@Front/config/queryConfig';
-
-// Example of using a general application configuration
-import { appName } from '@Front/config/appConfig';
-```
-
-## <span id="best-practice">🎖️ Best Practice</span>
-
-Efficient configuration management is crucial for maintaining a clear and organized codebase. Follow these best practices for managing configuration files:
-
-#### - Context-Specific Configuration
-
-Separate configuration files based on different contexts, such as API configurations, QueryClient configurations, translations, etc.
-
-This helps in better organization and ease of maintenance.
-
-#### - File Naming Convention
-
-Suffix configuration files with `Config` to enhance visibility and make it easier to identify configuration files at a glance.
-
----
-
-**_By adopting these practices, you create a modular and organized approach to configuration management, making it simpler to locate and manage context-specific settings._**

package/src/config/index.ts

@@ -1 +0,0 @@
-export { queryClient } from './queryClientConfig';