@pplancq/react-template 2.8.16 → 2.9.0

package/src/demo/ui/components/DemoHeader/__tests__/__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/src/demo/ui/components/DemoHeader/index.ts

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

package/src/{ui/molecules/Navigation/Navigation.tsx → demo/ui/components/DemoNavigation/DemoNavigation.tsx}

@@ -1,12 +1,12 @@
-import { NavLink } from '@Front/ui/atoms/NavLink';
+import { NavLink } from '@Demo/ui/components/NavLink/NavLink';
 import { useId } from 'react';
-import classes from './Navigation.module.css';
+import classes from './DemoNavigation.module.css';
 
-type NavigationProps = {
+type DemoNavigationProps = {
   links: { label: string; url: string }[];
 };
 
-export const Navigation = ({ links }: NavigationProps) => {
+export const DemoNavigation = ({ links }: DemoNavigationProps) => {
   const id = useId();
 
   return (

package/src/demo/ui/components/DemoNavigation/index.ts

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

package/src/{components → demo/ui/components}/TextInput/TextInput.tsx

@@ -1,6 +1,6 @@
-import { Input } from '@Front/ui/atoms/Input';
-import { InputHTMLAttributes } from 'react';
-import { FieldError, useFormContext } from 'react-hook-form';
+import { Input } from '@Demo/ui/components/Input/Input';
+import type { InputHTMLAttributes } from 'react';
+import { type FieldError, useFormContext } from 'react-hook-form';
 
 interface TextInputProps extends InputHTMLAttributes<HTMLInputElement> {
   name: string;

package/src/{forms → demo/ui/forms}/ProfileForm/ProfileForm.tsx

@@ -1,12 +1,12 @@
-import { TextInput } from '@Front/components/TextInput';
-import { ProfileType } from '@Front/types/profileTypes';
+import type { ProfileFormValues } from '@Demo/application/dtos/ProfileFormValues';
+import { TextInput } from '@Demo/ui/components/TextInput/TextInput';
 import { yupResolver } from '@hookform/resolvers/yup';
-import { FormProvider, SubmitHandler, useForm } from 'react-hook-form';
+import { FormProvider, type SubmitHandler, useForm } from 'react-hook-form';
 import * as yup from 'yup';
 import classes from './ProfileForm.module.scss';
 
 type ProfileFormProps = {
-  onSubmit: SubmitHandler<ProfileType>;
+  onSubmit: SubmitHandler<ProfileFormValues>;
   resetForm: () => void;
 };
 
@@ -17,15 +17,15 @@ const schema = yup.object().shape({
 });
 
 export const ProfileForm = ({ onSubmit, resetForm }: ProfileFormProps) => {
-  const methods = useForm<ProfileType>({
+  const methods = useForm<ProfileFormValues>({
     resolver: yupResolver(schema),
   });
 
   return (
     <FormProvider {...methods}>
       <form onSubmit={methods.handleSubmit(onSubmit)}>
-        <p>The form is being submited {methods.formState.submitCount} times</p>
-        <TextInput label="E-mail" type="email" name="mail" placeholder="Exemple@gmail.com" />
+        <p>The form has been submitted {methods.formState.submitCount} times.</p>
+        <TextInput label="E-mail" type="email" name="mail" placeholder="example@gmail.com" />
 
         <TextInput label="First Name" name="firstName" placeholder="First Name" />
 

package/src/demo/ui/hooks/useDemoUsersQuery/useDemoUsersQuery.ts

@@ -0,0 +1,13 @@
+import type { GetDemoUsersUseCaseInterface } from '@Demo/application/use-cases/GetDemoUsersUseCaseInterface';
+import { DEMO_SERVICES } from '@Demo/serviceIdentifiers';
+import { useService } from '@Shared/ui/hooks/useService/useService';
+import { useQuery } from '@tanstack/react-query';
+
+export const useDemoUsersQuery = () => {
+  const getDemoUsersUseCase = useService<GetDemoUsersUseCaseInterface>(DEMO_SERVICES.GetDemoUsersUseCase);
+
+  return useQuery({
+    queryKey: ['demo-users'],
+    queryFn: () => getDemoUsersUseCase.execute(),
+  });
+};

package/src/demo/ui/layouts/DemoLayout/DemoLayout.tsx

@@ -0,0 +1,12 @@
+import { DemoFooter } from '@Demo/ui/components/DemoFooter/DemoFooter';
+import { DemoHeader } from '@Demo/ui/components/DemoHeader/DemoHeader';
+import { MainTemplate } from '@Demo/ui/layouts/MainTemplate/MainTemplate';
+import { Outlet } from 'react-router';
+
+export const DemoLayout = () => {
+  return (
+    <MainTemplate headerProps={{ leftComponents: <DemoHeader /> }} footerProps={{ footerContent: <DemoFooter /> }}>
+      <Outlet />
+    </MainTemplate>
+  );
+};

package/src/demo/ui/layouts/MainTemplate/MainTemplate.module.css

@@ -0,0 +1,21 @@
+.mainTemplateStyle {
+  display: flex;
+  min-height: 100%;
+  flex-direction: column;
+}
+
+.header {
+  display: flex;
+  padding: 16px;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.main {
+  flex: 1;
+}
+
+.footer {
+  padding: 16px;
+}

package/src/{ui/templates → demo/ui/layouts}/MainTemplate/MainTemplate.tsx

@@ -1,7 +1,4 @@
-import { Footer } from '@Front/ui/organisms/Footer';
-import { Header } from '@Front/ui/organisms/Header';
-import { MainContent } from '@Front/ui/organisms/MainContent';
-import { PropsWithChildren, ReactNode } from 'react';
+import type { PropsWithChildren, ReactNode } from 'react';
 
 import classes from './MainTemplate.module.css';
 
@@ -18,9 +15,12 @@ type MainTemplateProps = {
 export const MainTemplate = ({ headerProps, footerProps, children }: PropsWithChildren<MainTemplateProps>) => {
   return (
     <div className={classes.mainTemplateStyle}>
-      <Header {...headerProps} />
-      <MainContent>{children}</MainContent>
-      <Footer {...footerProps} />
+      <header className={classes.header}>
+        {headerProps.leftComponents}
+        {headerProps.rightComponents}
+      </header>
+      <main className={classes.main}>{children}</main>
+      <footer className={classes.footer}>{footerProps.footerContent}</footer>
     </div>
   );
 };

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

@@ -0,0 +1,117 @@
+import image from '@Demo/ui/assets/images/templatePlugins.png';
+import { demoAppRoutes } from '@Demo/ui/routing/demoAppRoutes';
+import { NavLink } from '@Demo/ui/components/NavLink/NavLink';
+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 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 { 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 { demoAppRoutes } from '@Demo/ui/routing/demoAppRoutes';
+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 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,4 +1,4 @@
-import AppReact from './bootstrap';
+import AppHTMLElement from '@App/AppHTMLElement';
 
 if (import.meta.env.FRONT_MOCK_ENABLE === 'true') {
   const { worker } = await import('@Mocks/browser');
@@ -7,4 +7,4 @@ if (import.meta.env.FRONT_MOCK_ENABLE === 'true') {
   });
 }
 
-customElements.define('app-react', AppReact);
+customElements.define('app-react', AppHTMLElement);

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.