@pplancq/react-template 2.8.17 → 2.10.0

package/playwright-report/sonar-results.xml

@@ -0,0 +1,20 @@
+<testExecutions version="1">
+<file path="/Users/paul/dev/@pplancq/dev-tools/packages/react-template/tests/e2e/demo.test.ts">
+<testCase name="Demo Test › should have a title" duration="218">
+</testCase>
+<testCase name="Demo Test › should data fetching" duration="225">
+</testCase>
+</file>
+<file path="/Users/paul/dev/@pplancq/dev-tools/packages/react-template/tests/e2e/demo.test.ts">
+<testCase name="Demo Test › should have a title" duration="210">
+</testCase>
+<testCase name="Demo Test › should data fetching" duration="226">
+</testCase>
+</file>
+<file path="/Users/paul/dev/@pplancq/dev-tools/packages/react-template/tests/e2e/demo.test.ts">
+<testCase name="Demo Test › should have a title" duration="518">
+</testCase>
+<testCase name="Demo Test › should data fetching" duration="509">
+</testCase>
+</file>
+</testExecutions>

package/playwright.config.ts

@@ -3,7 +3,7 @@ import { defineConfig, devices } from '@playwright/test';
 const appUrl = 'http://localhost:3000';
 
 export default defineConfig({
-  testDir: 'tests',
+  testDir: 'tests/e2e',
   outputDir: 'test-results',
   fullyParallel: true,
   forbidOnly: Boolean(process.env.CI),
@@ -18,8 +18,8 @@ export default defineConfig({
       { outputFile: 'playwright-report/sonar-results.xml', sonarcloud: true },
     ],
   ],
-  globalSetup: 'tests/utils/playwright.globalSetup.ts',
-  globalTeardown: 'tests/utils/playwright.globalTeardown.ts',
+  globalSetup: 'tests/e2e/utils/playwright.globalSetup.ts',
+  globalTeardown: 'tests/e2e/utils/playwright.globalTeardown.ts',
   use: {
     baseURL: appUrl,
     trace: 'retain-on-failure',

package/scripts/removeDemo.cjs

@@ -4,79 +4,118 @@ const { resolve } = require('node:path');
 
 const resolveSrc = path => resolve(__dirname, `../src${path}`);
 
-rmSync(resolveSrc('/api/demoApi.ts'));
-
-rmSync(resolveSrc('/assets/css/mainBody.css'));
-rmSync(resolveSrc('/assets/css/reset.css'));
-writeFileSync(resolveSrc('/assets/css/global.css'), ':root {\n  --white-color: #fff;\n}\n', { encoding: 'utf-8' });
-let assetsIndex = readFileSync(resolveSrc('/assets/css/index.ts'), { encoding: 'utf-8' });
-assetsIndex = assetsIndex.replaceAll("import './reset.css';\nimport './mainBody.css';\n", "import './global.css';\n");
-writeFileSync(resolveSrc('/assets/css/index.ts'), assetsIndex, { encoding: 'utf-8' });
-
-rmSync(resolveSrc('/assets/images/logo.png'));
-rmSync(resolveSrc('/assets/images/templatePlugins.png'));
-
-rmSync(resolveSrc('/components/Footer'), { recursive: true });
-rmSync(resolveSrc('/components/Header'), { recursive: true });
-rmSync(resolveSrc('/components/TextInput'), { recursive: true });
-
-rmSync(resolveSrc('/forms/ProfileForm'), { recursive: true });
-
-rmSync(resolveSrc('/hooks/api/useDemoApi.ts'));
-let queryKey = readFileSync(resolveSrc('/hooks/api/queryKey.ts'), { encoding: 'utf-8' });
-queryKey = queryKey.replaceAll("export const demoQuery = () => ['dataWithDelay'];\n", '');
-writeFileSync(resolveSrc('/hooks/api/queryKey.ts'), queryKey, { encoding: 'utf-8' });
-
-rmSync(resolveSrc('/pages/Demo'), { recursive: true });
-rmSync(resolveSrc('/pages/Layout'), { recursive: true });
-rmSync(resolveSrc('/pages/UnexpectedError'), { recursive: true });
-mkdirSync(resolveSrc('/pages/Home'));
-writeFileSync(resolveSrc('/pages/Home/index.ts'), "export { homeRoutes } from './routes';\n", { encoding: 'utf-8' });
+rmSync(resolveSrc('/demo'), { recursive: true, force: true });
+
+rmSync(resolveSrc('/app/assets/css/mainBody.css'), { force: true });
+writeFileSync(resolveSrc('/app/assets/css/global.css'), ':root {\n  --white-color: #fff;\n}\n', { encoding: 'utf-8' });
+writeFileSync(resolveSrc('/app/assets/css/index.ts'), "import './reset.css';\nimport './global.css';\n", {
+  encoding: 'utf-8',
+});
+
+mkdirSync(resolveSrc('/home/domain'), { recursive: true });
+writeFileSync(resolveSrc('/home/domain/.gitkeep'), '', { encoding: 'utf-8' });
+
+mkdirSync(resolveSrc('/home/application'), { recursive: true });
+writeFileSync(resolveSrc('/home/application/.gitkeep'), '', { encoding: 'utf-8' });
+
+mkdirSync(resolveSrc('/home/infrastructure'), { recursive: true });
+writeFileSync(resolveSrc('/home/infrastructure/.gitkeep'), '', { encoding: 'utf-8' });
+
+writeFileSync(resolveSrc('/home/serviceIdentifiers.ts'), 'export const HOME_SERVICES = Object.freeze({});\n', {
+  encoding: 'utf-8',
+});
+
 writeFileSync(
-  resolveSrc('/pages/Home/routes.tsx'),
-  "import type { RouteObject } from 'react-router';\n" +
-    "import { Home } from './Home';\n" +
-    '\n' +
-    'export const homeRoutes: RouteObject = {\n' +
-    '  index: true,\n' +
-    '  element: <Home />,\n' +
-    '};\n',
+  resolveSrc('/home/serviceHome.ts'),
+  [
+    "import { ContainerModule } from 'inversify';",
+    '',
+    'export const serviceHome: ContainerModule = new ContainerModule(_options => {',
+    '  // Register your home context services here',
+    '});',
+    '',
+  ].join('\n'),
   { encoding: 'utf-8' },
 );
-writeFileSync(resolveSrc('/pages/Home/Home.tsx'), 'export const Home = () => {\n  return <div>HomePage</div>;\n};\n', {
-  encoding: 'utf-8',
-});
 
-let appRoutes = readFileSync(resolveSrc('/routing/appRoutes.ts'), { encoding: 'utf-8' });
-appRoutes = appRoutes.replaceAll(
-  "\n  reactQueryDemo: '/reactQueryDemo',\n  reactHookFormDemo: '/reactHookFormDemo',",
-  '',
+mkdirSync(resolveSrc('/home/ui/pages/Home'), { recursive: true });
+writeFileSync(
+  resolveSrc('/home/ui/pages/Home/Home.tsx'),
+  [
+    'export const Home = () => {',
+    '  return (',
+    '    <section>',
+    '      <h1>Home</h1>',
+    '      <p>Your demo context has been removed. Start building your first bounded context from here.</p>',
+    '    </section>',
+    '  );',
+    '};',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
 );
-writeFileSync(resolveSrc('/routing/appRoutes.ts'), appRoutes, { encoding: 'utf-8' });
-let routes = readFileSync(resolveSrc('/routing/routes.tsx'), { encoding: 'utf-8' });
-routes = routes.replaceAll(
-  "import { demoRoutes } from '@Front/pages/Demo';",
-  "import { homeRoutes } from '@Front/pages/Home';",
+
+mkdirSync(resolveSrc('/home/ui/routing'), { recursive: true });
+writeFileSync(
+  resolveSrc('/home/ui/routing/homeAppRoutes.ts'),
+  ['export const homeAppRoutes = Object.freeze({', "  home: '/',", '});', ''].join('\n'),
+  { encoding: 'utf-8' },
+);
+
+writeFileSync(
+  resolveSrc('/home/ui/routing/homeRoutes.tsx'),
+  [
+    "import { Home } from '@Home/ui/pages/Home/Home';",
+    "import type { RouteObject } from 'react-router';",
+    '',
+    'export const homeRoutes: RouteObject = {',
+    '  children: [',
+    '    {',
+    '      index: true,',
+    '      element: <Home />,',
+    '    },',
+    '  ],',
+    '};',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
+);
+
+writeFileSync(
+  resolveSrc('/app/config/serviceContainer.ts'),
+  [
+    "import { serviceHome } from '@Home/serviceHome';",
+    "import { Container } from 'inversify';",
+    '',
+    'export const serviceContainer = new Container();',
+    '',
+    'serviceContainer.load(serviceHome);',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
 );
-routes = routes.replaceAll("\nimport { Layout } from '@Front/pages/Layout';", '');
-routes = routes.replaceAll("\nimport { UnexpectedError } from 'src/pages/UnexpectedError';", '');
-routes = routes.replaceAll(
-  'element: <Layout />,\n    children: [demoRoutes],\n    errorElement: <UnexpectedError />,',
-  'children: [homeRoutes],',
+
+writeFileSync(
+  resolveSrc('/app/routing/routes.tsx'),
+  [
+    "import { homeRoutes } from '@Home/ui/routing/homeRoutes';",
+    "import type { RouteObject } from 'react-router';",
+    '',
+    'export const routeObject: RouteObject[] = [',
+    '  {',
+    "    path: '/',",
+    '    children: [homeRoutes],',
+    '  },',
+    '];',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
 );
-writeFileSync(resolveSrc('/routing/routes.tsx'), routes, { encoding: 'utf-8' });
-
-rmSync(resolveSrc('/types/demoApi.ts'));
-rmSync(resolveSrc('/types/profileTypes.ts'));
-
-rmSync(resolveSrc('/ui/atoms/Input'), { recursive: true });
-rmSync(resolveSrc('/ui/atoms/Logo'), { recursive: true });
-rmSync(resolveSrc('/ui/atoms/NavLink'), { recursive: true });
-rmSync(resolveSrc('/ui/molecules/Navigation'), { recursive: true });
-rmSync(resolveSrc('/ui/organisms/Footer'), { recursive: true });
-rmSync(resolveSrc('/ui/organisms/Header'), { recursive: true });
-rmSync(resolveSrc('/ui/organisms/MainContent'), { recursive: true });
-rmSync(resolveSrc('/ui/templates/MainTemplate'), { recursive: true });
+
+const tsconfigJson = JSON.parse(readFileSync(resolve(__dirname, '../tsconfig.json'), { encoding: 'utf-8' }));
+delete tsconfigJson.compilerOptions.paths['@Demo/*'];
+tsconfigJson.compilerOptions.paths['@Home/*'] = ['./src/home/*'];
+writeFileSync(resolve(__dirname, '../tsconfig.json'), JSON.stringify(tsconfigJson, null, 2), { encoding: 'utf-8' });
 
 const packagesJson = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), { encoding: 'utf-8' }));
 const { 'remove:demo': _, ...scripts } = packagesJson.scripts;

package/src/README.md

@@ -0,0 +1,81 @@
+# `src`
+
+This directory contains the template source code and its explanatory documentation.
+
+## Architecture Philosophy
+
+This starter follows a **hybrid architecture** combining two complementary patterns:
+
+- **Clean Architecture** (Robert C. Martin) — code is organized into horizontal layers that enforce a strict
+  dependency direction. Dependencies always flow **inward toward the domain**. The domain is the most protected
+  layer; it has zero external dependencies.
+- **DDD Bounded Contexts** — code is also organized into vertical slices, each representing an isolated business
+  domain. A bounded context owns its full stack: domain, application, infrastructure, and UI.
+
+The result is a structure where every folder belongs to either a **horizontal layer** (domain, application,
+infrastructure, ui) or a **vertical slice** (a bounded context such as `demo`), and both dimensions are always
+visible.
+
+## Top-level structure
+
+```
+src/
+├── app/       # Application bootstrap layer (not a bounded context)
+├── shared/    # Shared kernel — genuinely cross-context code
+│   ├── domain/
+│   ├── application/
+│   ├── infrastructure/
+│   └── ui/
+└── demo/      # Example bounded context (domain / application / infrastructure / ui)
+```
+
+## Fundamental dependency rule
+
+```
+UI  →  Application  →  Domain
+Infrastructure  -.→  Domain (implements its interfaces)
+```
+
+- **Domain** depends on nothing. Pure TypeScript.
+- **Application** depends on Domain only. Orchestrates use cases, defines infrastructure interfaces.
+- **Infrastructure** implements interfaces defined by Domain/Application. May use external libraries.
+- **UI** depends on Application (use cases) and Domain (DTOs). No business logic.
+
+This rule applies **within each bounded context** and **within the shared kernel**.
+
+## Path aliases
+
+Each first-class section of the source tree has a TypeScript path alias. Use these aliases instead of long
+relative paths; they signal architectural intent and prevent accidental cross-context coupling.
+
+| Alias       | Maps to        |
+| ----------- | -------------- |
+| `@App/*`    | `src/app/*`    |
+| `@Shared/*` | `src/shared/*` |
+| `@Demo/*`   | `src/demo/*`   |
+| `@Mocks/*`  | `mocks/*`      |
+
+When you add a real bounded context alongside `demo`, add its own alias to `tsconfig.json`.
+
+## Table of contents
+
+1. [`app/README.md`](./app/README.md) — application bootstrap, composition root, routing, and providers
+2. [`shared/README.md`](./shared/README.md) — shared kernel concept and usage rules
+3. [`shared/domain/README.md`](./shared/domain/README.md) — shared pure contracts, types, and domain rules
+4. [`shared/application/README.md`](./shared/application/README.md) — shared application-layer abstractions
+5. [`shared/infrastructure/README.md`](./shared/infrastructure/README.md) — shared technical adapters and helpers
+6. [`shared/ui/README.md`](./shared/ui/README.md) — shared UI-facing hooks and utilities
+7. [`demo/README.md`](./demo/README.md) — the example bounded context and how to replicate it
+
+## Suggested reading order
+
+If you are discovering the template for the first time:
+
+1. This file — understand the big picture
+2. `app` — see how the application boots and wires everything together
+3. `shared/domain` — understand why the domain layer is the most protected
+4. `shared` — understand what the shared kernel is and what it must not become
+5. `demo` — walk through a complete bounded context layer by layer
+
+That sequence starts with the overall architecture, moves to the heart of Clean Architecture (domain purity),
+then shows how a real bounded context puts all the pieces together.

package/src/app/App.tsx

@@ -0,0 +1,18 @@
+import { queryClient } from "@App/config/queryClientConfig";
+import { serviceContainer } from "@App/config/serviceContainer";
+import { Providers } from "@App/providers/Providers/Providers";
+import { Router } from "@App/routing/Router";
+
+import "@App/assets/css";
+
+type AppProps = {
+  basename?: string;
+};
+
+export const App = ({ basename }: AppProps) => {
+  return (
+    <Providers queryClient={queryClient} container={serviceContainer}>
+      <Router basename={basename} />
+    </Providers>
+  );
+};

package/src/{bootstrap.tsx → app/AppHTMLElement.tsx}

@@ -1,9 +1,9 @@
-import { App } from '@Front/components/App';
-import { StrictMode } from 'react';
-import { createRoot, type Root } from 'react-dom/client';
+import { App } from "@App/App";
+import { StrictMode } from "react";
+import { createRoot, type Root } from "react-dom/client";
 
 // eslint-disable-next-line import/no-default-export
-export default class Bootstrap extends HTMLElement {
+export default class AppHTMLElement extends HTMLElement {
   private readonly root: Root;
 
   private isMounted = false;
@@ -18,7 +18,7 @@ export default class Bootstrap extends HTMLElement {
     this.isMounted = true;
     this.root.render(
       <StrictMode>
-        <App basename={this.getAttribute('basename') ?? ''} />
+        <App basename={this.getAttribute("basename") ?? ""} />
       </StrictMode>,
     );
   }

package/src/app/README.md

@@ -0,0 +1,69 @@
+# `app`
+
+The `app` folder is the **application bootstrap layer**. It is not a bounded context — it has no business
+domain of its own. Its single responsibility is to assemble all the pieces (providers, router, DI container,
+contexts) and expose the application to the browser.
+
+Path alias: `@App/*`
+
+## Contents
+
+| Subfolder / file     | Role                                                                             |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `App.tsx`            | Root React component — composes providers and router                             |
+| `AppHTMLElement.tsx` | Custom-element bootstrap (`<app-react>`). Mounts/unmounts the React root         |
+| `assets/`            | Global CSS reset, base styles, and app-wide static assets                        |
+| `config/`            | App-wide configuration and the **composition root** (`serviceContainer.ts`)      |
+| `providers/`         | React provider components: `ServiceProvider`, `QueryClientProvider`, `Providers` |
+| `routing/`           | Top-level router and route aggregation                                           |
+
+## Composition root
+
+`config/serviceContainer.ts` is the **composition root** of the dependency injection system. It is the single
+place in the application where the Inversify container is created and all bounded-context service collections
+are loaded:
+
+```ts
+import { serviceDemo } from "@Demo/serviceDemo";
+import { Container } from "inversify";
+
+export const serviceContainer = new Container();
+serviceContainer.load(serviceDemo);
+// add more context modules here as the application grows
+```
+
+The composition root is the **only** place that knows about concrete implementations. Every other layer receives
+dependencies through interfaces and the DI container.
+
+## Provider tree
+
+The `Providers` component wraps the application in its provider tree. The order matters:
+
+```
+ServiceProvider          ← makes the DI container available via React context
+  └── QueryClientProvider ← makes React Query available
+        └── {children}    ← the rest of the application
+```
+
+`ServiceProvider` must be outermost so that any inner provider can use `useService` to resolve DI services.
+
+## Custom element bootstrap
+
+`AppHTMLElement.tsx` registers the application as a
+[custom element](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) (`<app-react>`).
+This allows the React app to be embedded in any HTML host without tight coupling to a specific framework or
+page structure. The custom element mounts a React root in `connectedCallback` and unmounts it in
+`disconnectedCallback`.
+
+## Dependency rules for `app`
+
+- ✅ Can import from `@Shared/*` and any bounded context (e.g., `@Demo/*`)
+- ✅ Responsible for high-level orchestration only
+- ❌ Must not contain business rules or feature-specific logic
+- ❌ Generic helpers belong in `shared`, not here
+
+## Avoid
+
+- Business rules or domain objects
+- Feature-specific orchestration that belongs to a bounded context
+- Generic helpers that should live in `shared`

package/src/app/assets/css/index.ts

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

package/src/{assets → app/assets}/css/reset.css

@@ -83,8 +83,8 @@ video {
   vertical-align: baseline;
   font: inherit;
   font-family:
-    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans',
-    'Helvetica Neue', sans-serif;
+    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans",
+    "Helvetica Neue", sans-serif;
   font-size: 100%;
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
@@ -128,5 +128,5 @@ table {
 }
 
 code {
-  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace;
+  font-family: source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace;
 }

package/src/app/config/queryClientConfig.ts

@@ -0,0 +1,3 @@
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();

package/src/app/config/serviceContainer.ts

@@ -0,0 +1,6 @@
+import { serviceDemo } from "@Demo/serviceDemo";
+import { Container } from "inversify";
+
+export const serviceContainer = new Container();
+
+serviceContainer.load(serviceDemo);

package/src/app/providers/Providers/Providers.tsx

@@ -0,0 +1,18 @@
+import { QueryClientProvider } from "@App/providers/QueryClientProvider/QueryClientProvider";
+import { ServiceProvider } from "@App/providers/ServiceProvider/ServiceProvider";
+import type { QueryClient } from "@tanstack/react-query";
+import type { Container } from "inversify";
+import type { PropsWithChildren } from "react";
+
+type ProvidersProps = PropsWithChildren<{
+  queryClient: QueryClient;
+  container: Container;
+}>;
+
+export const Providers = ({ queryClient, container, children }: ProvidersProps) => {
+  return (
+    <ServiceProvider container={container}>
+      <QueryClientProvider queryClient={queryClient}>{children}</QueryClientProvider>
+    </ServiceProvider>
+  );
+};

package/src/app/providers/QueryClientProvider/QueryClientProvider.tsx

@@ -0,0 +1,16 @@
+import { type QueryClient, QueryClientProvider as ReactQueryClientProvider } from "@tanstack/react-query";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+import type { PropsWithChildren } from "react";
+
+type ClientProviderProps = {
+  queryClient: QueryClient;
+};
+
+export const QueryClientProvider = ({ children, queryClient }: PropsWithChildren<ClientProviderProps>) => {
+  return (
+    <ReactQueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </ReactQueryClientProvider>
+  );
+};

package/src/app/providers/ServiceProvider/ServiceContext.ts

@@ -0,0 +1,8 @@
+import type { Container } from "inversify";
+import { createContext } from "react";
+
+export type ServiceContextValue = {
+  container: Container;
+};
+
+export const ServiceContext = createContext<ServiceContextValue | null>(null);

package/src/app/providers/ServiceProvider/ServiceProvider.tsx

@@ -0,0 +1,14 @@
+import { ServiceContext } from "@App/providers/ServiceProvider/ServiceContext";
+import type { Container } from "inversify";
+import type { PropsWithChildren } from "react";
+import { useRef } from "react";
+
+export type ServiceProviderProps = PropsWithChildren<{
+  container: Container;
+}>;
+
+export const ServiceProvider = ({ container, children }: ServiceProviderProps) => {
+  const containerRef = useRef({ container });
+
+  return <ServiceContext.Provider value={containerRef.current}>{children}</ServiceContext.Provider>;
+};

package/src/app/routing/Router.tsx

@@ -0,0 +1,14 @@
+import { createBrowserRouter, RouterProvider } from "react-router";
+import { routeObject } from "./routes";
+
+type RouterProps = {
+  basename?: string;
+};
+
+export const Router = ({ basename }: RouterProps = {}) => {
+  const router = createBrowserRouter(routeObject, {
+    basename,
+  });
+
+  return <RouterProvider router={router} />;
+};

package/src/app/routing/appRoutes.ts

@@ -0,0 +1,3 @@
+export const appRoutes = Object.freeze({
+  home: "/",
+});

package/src/app/routing/routes.tsx

@@ -0,0 +1,9 @@
+import { demoRoutes } from "@Demo/ui/routing/demoRoutes";
+import type { RouteObject } from "react-router";
+
+export const routeObject: RouteObject[] = [
+  {
+    path: "/",
+    children: [demoRoutes],
+  },
+];