@pplancq/react-template 2.8.17 → 2.10.0

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/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}

package/tests/e2e/demo.test.ts

@@ -0,0 +1,17 @@
+import { getUsers200 } from "@Mocks/handlers/userHandlers";
+import { expect } from "@playwright/test";
+import { describe, it } from "./fixture/playwright.fixture";
+
+describe("Demo Test", () => {
+  it("should have a title", async ({ page }) => {
+    await page.goto("/");
+    const title = page.getByText("WELCOME TO YOUR REACT STARTER KIT");
+    await expect(title).toBeVisible();
+  });
+
+  it("should data fetching", async ({ page, network }) => {
+    network.use(getUsers200);
+    await page.goto("/react-query");
+    await expect(page.getByText("Demo user")).toBeVisible();
+  });
+});

package/tests/e2e/fixture/playwright.fixture.ts

@@ -0,0 +1,15 @@
+import type { NetworkFixture } from "@msw/playwright";
+import { test as base } from "@playwright/test";
+import { createNetworkFixture } from "../utils/createNetworkFixture";
+import { createTestWithCoverageFixture } from "../utils/createTestWithCoverageFixture";
+
+export const test = base.extend<{
+  testWithCoverage: string;
+  network: NetworkFixture;
+}>({
+  testWithCoverage: createTestWithCoverageFixture(),
+  network: createNetworkFixture(),
+});
+
+export const it = test;
+export const { describe } = test;

package/tests/{utils → e2e/utils}/createNetworkFixture.ts

@@ -1,5 +1,5 @@
-import { defineNetworkFixture, type NetworkFixture } from '@msw/playwright';
-import type { PlaywrightTestArgs, PlaywrightWorkerArgs, TestFixture } from '@playwright/test';
+import { defineNetworkFixture, type NetworkFixture } from "@msw/playwright";
+import type { PlaywrightTestArgs, PlaywrightWorkerArgs, TestFixture } from "@playwright/test";
 
 export const createNetworkFixture = (): [
   TestFixture<NetworkFixture, PlaywrightTestArgs & PlaywrightWorkerArgs>,

package/tests/{utils → e2e/utils}/createTestWithCoverageFixture.ts

@@ -1,14 +1,14 @@
-import type { PlaywrightTestArgs, PlaywrightWorkerArgs, TestFixture } from '@playwright/test';
-import { test } from '@playwright/test';
-import { CoverageReport } from 'monocart-coverage-reports';
-import { coverageOptions } from '../../mrc.playwright.config';
+import type { PlaywrightTestArgs, PlaywrightWorkerArgs, TestFixture } from "@playwright/test";
+import { test } from "@playwright/test";
+import { CoverageReport } from "monocart-coverage-reports";
+import { coverageOptions } from "../../../mrc.playwright.config";
 
 export const createTestWithCoverageFixture = (): [
   TestFixture<string, PlaywrightTestArgs & PlaywrightWorkerArgs>,
-  { scope: 'test'; auto: true },
+  { scope: "test"; auto: true },
 ] => [
   async ({ page }, use) => {
-    const isChromium = test.info().project.name === 'chromium';
+    const isChromium = test.info().project.name === "chromium";
 
     if (isChromium && coverageOptions.enabled) {
       await page.coverage.startJSCoverage({
@@ -16,7 +16,7 @@ export const createTestWithCoverageFixture = (): [
       });
     }
 
-    await use('testWithCoverage');
+    await use("testWithCoverage");
 
     if (isChromium && coverageOptions.enabled) {
       const coverageList = await page.coverage.stopJSCoverage();
@@ -25,7 +25,7 @@ export const createTestWithCoverageFixture = (): [
     }
   },
   {
-    scope: 'test',
+    scope: "test",
     auto: true,
   },
 ];

package/tests/{utils → e2e/utils}/playwright.globalSetup.ts

@@ -1,10 +1,10 @@
-import type { FullConfig } from '@playwright/test';
-import { CoverageReport } from 'monocart-coverage-reports';
-import { coverageOptions } from '../../mrc.playwright.config';
+import type { FullConfig } from "@playwright/test";
+import { CoverageReport } from "monocart-coverage-reports";
+import { coverageOptions } from "../../../mrc.playwright.config";
 
 const globalSetup = (config: FullConfig) => {
   if (config.webServer && coverageOptions.enabled) {
-    console.info('[playwright]  Coverage enabled with monocart');
+    console.info("[playwright]  Coverage enabled with monocart");
     const mcr = new CoverageReport(coverageOptions);
     mcr.cleanCache();
   }

package/tests/{utils → e2e/utils}/playwright.globalTeardown.ts

@@ -1,6 +1,6 @@
-import type { FullConfig } from '@playwright/test';
-import { CoverageReport } from 'monocart-coverage-reports';
-import { coverageOptions } from '../../mrc.playwright.config';
+import type { FullConfig } from "@playwright/test";
+import { CoverageReport } from "monocart-coverage-reports";
+import { coverageOptions } from "../../../mrc.playwright.config";
 
 const globalTeardown = async (config: FullConfig) => {
   if (config.webServer && coverageOptions.enabled) {

package/{src/__tests__/bootstraps.test.tsx → tests/unit/app/AppHTMLElement.test.tsx}

@@ -1,19 +1,19 @@
-import { App } from '@Front/components/App';
-import { waitFor } from '@testing-library/react';
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
-import bootstrap from '../bootstrap';
+import { App } from "@App/App";
+import AppHTMLElement from "@App/AppHTMLElement";
+import { waitFor } from "@testing-library/react";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from "vitest";
 
-vi.mock('@Front/components/App', () => ({
+vi.mock("@App/App", () => ({
   App: () => <div data-testid="app-mock">AppMock</div>,
 }));
 
-vi.mock('react-dom/client', () => ({
+vi.mock("react-dom/client", () => ({
   createRoot: vi.fn(),
 }));
 
-describe('bootstrap', () => {
+describe("AppHTMLElement", () => {
   let container: HTMLElement;
   const render = vi.fn();
   const unmount = vi.fn();
@@ -22,17 +22,17 @@ describe('bootstrap', () => {
     unmount,
   }));
 
-  customElements.define('bootstrap-html-element', bootstrap);
+  customElements.define("bootstrap-html-element", AppHTMLElement);
 
   beforeEach(() => {
-    container = document.createElement('bootstrap-html-element');
+    container = document.createElement("bootstrap-html-element");
   });
 
   afterEach(() => {
     container.remove();
   });
 
-  it('should mount the React component in the custom element', () => {
+  it("should mount the React component in the custom element", () => {
     document.body.appendChild(container);
 
     expect(createRoot as Mock).toHaveBeenCalledWith(expect.anything());
@@ -44,7 +44,7 @@ describe('bootstrap', () => {
     expect(unmount).not.toHaveBeenCalled();
   });
 
-  it('should unmount the React component when removed from the DOM', async () => {
+  it("should unmount the React component when removed from the DOM", async () => {
     document.body.appendChild(container);
 
     expect(unmount).not.toHaveBeenCalled();
@@ -56,7 +56,7 @@ describe('bootstrap', () => {
     });
   });
 
-  it('should not unmount when element is removed and re-added to the DOM', async () => {
+  it("should not unmount when element is removed and re-added to the DOM", async () => {
     document.body.appendChild(container);
     container.remove();
     document.body.appendChild(container);

package/tests/unit/demo/ui/components/DemoFooter/Footer.test.tsx

@@ -0,0 +1,15 @@
+import { DemoFooter } from "@Demo/ui/components/DemoFooter";
+import { render } from "@testing-library/react";
+import { BrowserRouter as Router } from "react-router";
+
+describe("Footer Component", () => {
+  it("should render the Footer component correctly", () => {
+    const { container } = render(
+      <Router>
+        <DemoFooter />
+      </Router>,
+    );
+
+    expect(container).toMatchSnapshot();
+  });
+});

package/{src/components/Footer/__tests__ → tests/unit/demo/ui/components/DemoFooter}/__snapshots__/Footer.test.tsx.snap

@@ -3,7 +3,7 @@
 exports[`Footer Component > should render the Footer component correctly 1`] = `
 <div>
   <div
-    class="_container_acfd2c"
+    class="container"
   >
     <hr />
     <a
@@ -12,8 +12,8 @@ exports[`Footer Component > should render the Footer component correctly 1`] = `
     >
       <img
         alt="logo"
-        class="_logoStyle_9e86a7"
-        src="/src/assets/images/logo.png"
+        class="logoStyle"
+        src="/src/demo/ui/assets/images/logo.png"
         style="width: 50px;"
       />
     </a>

package/tests/unit/demo/ui/components/DemoHeader/Header.test.tsx

@@ -0,0 +1,15 @@
+import { DemoHeader } from "@Demo/ui/components/DemoHeader";
+import { render } from "@testing-library/react";
+import { BrowserRouter as Router } from "react-router";
+
+describe("Header Component", () => {
+  it("should render the Header component correctly", () => {
+    const { container } = render(
+      <Router>
+        <DemoHeader />
+      </Router>,
+    );
+
+    expect(container).toMatchSnapshot();
+  });
+});

package/tests/unit/demo/ui/components/DemoHeader/__snapshots__/Header.test.tsx.snap

@@ -0,0 +1,64 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Header Component > should render the Header component correctly 1`] = `
+<div>
+  <div
+    class="container"
+  >
+    <a
+      data-discover="true"
+      href="/"
+    >
+      <img
+        alt="logo"
+        class="logoStyle"
+        src="/src/demo/ui/assets/images/logo.png"
+        style="width: 50px;"
+      />
+    </a>
+    <nav>
+      <ul
+        class="navList"
+      >
+        <li>
+          <a
+            aria-current="page"
+            class="a active"
+            data-discover="true"
+            href="/"
+          >
+            Overview
+          </a>
+        </li>
+        <li>
+          <a
+            class="a"
+            data-discover="true"
+            href="/react-query"
+          >
+            React Query
+          </a>
+        </li>
+        <li>
+          <a
+            class="a"
+            data-discover="true"
+            href="/react-hook-form"
+          >
+            React Hook Form
+          </a>
+        </li>
+        <li>
+          <a
+            class="a"
+            data-discover="true"
+            href="/dependency-injection"
+          >
+            Dependency Injection
+          </a>
+        </li>
+      </ul>
+    </nav>
+  </div>
+</div>
+`;

package/tests/unit/demo/ui/components/Logo/Logo.test.tsx

@@ -0,0 +1,12 @@
+import { Logo } from "@Demo/ui/components/Logo";
+import { render } from "@testing-library/react";
+import { expect } from "vitest";
+import { axe } from "vitest-axe";
+
+describe("<Logo />", () => {
+  it("should", async () => {
+    const { container } = render(<Logo src="foo" alt="bar" />);
+
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/tsconfig.json

@@ -23,10 +23,12 @@
     "noEmit": true,
     "jsx": "react-jsx",
     "paths": {
-      "@Front/*": ["./src/*"],
+      "@App/*": ["./src/app/*"],
+      "@Shared/*": ["./src/shared/*"],
+      "@Demo/*": ["./src/demo/*"],
       "@Mocks/*": ["./mocks/*"]
     }
   },
-  "include": ["src", "mocks", "vitest.setup.ts", "rsbuild.config.ts"],
+  "include": ["src", "tests", "mocks", "vitest.setup.ts", "rsbuild.config.ts"],
   "exclude": ["node_modules"]
 }

package/vitest.config.mts

@@ -18,13 +18,17 @@ 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',
         junit: 'junit-report.xml',
       },
-      include: ['src/**/*.(spec|test|steps).[jt]s?(x)'],
+      include: ['tests/unit/**/*.(spec|test|steps).[jt]s?(x)'],
       maxWorkers: env.CI ? 2 : undefined,
       coverage: {
         enabled: env.CI === 'true',

package/postcss.config.mjs

@@ -1,5 +0,0 @@
-import defaultConfig from '@pplancq/postcss-config';
-
-export default {
-  ...defaultConfig,
-};

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/constant.ts

@@ -1,16 +0,0 @@
-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/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/assets/css/index.ts

@@ -1,2 +0,0 @@
-import './reset.css';
-import './mainBody.css';

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/__tests__/Footer.test.tsx

@@ -1,15 +0,0 @@
-import { render } from '@testing-library/react';
-import { BrowserRouter as Router } from 'react-router';
-import { Footer } from '../Footer';
-
-describe('Footer Component', () => {
-  it('should render the Footer component correctly', () => {
-    const { container } = render(
-      <Router>
-        <Footer />
-      </Router>,
-    );
-
-    expect(container).toMatchSnapshot();
-  });
-});

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>
-  );
-};