@pplancq/react-template 1.0.0

package/src/pages/README.md

@@ -0,0 +1,88 @@
+# 📁 pages 
+
+The "pages" folder is designed to contain all the pages of our application. This structure facilitates organization, management, and navigation between the different views of our application. Additionally, if a page contains components related to its structure, we can create sub-folders to maintain order.
+
+## 📑 Table of Contents
+  - [Why Use a "pages" Folder](#folder-organization)
+  - [Typical Structure of a "pages" Folder](#structure)
+  - [Usage Example](#usage)
+  - [Best Practice](#best-practice)
+
+
+## <span id="folder-organization">Why Use a "pages" Folder?</span>
+
+1. **Clear Organization** : By grouping all our pages in a single folder, we maintain a clear organization of our application, making it easy to find specific pages.
+
+2. **Ease of Navigation** : A well-organized "pages" folder structure makes navigation between the views of our application easier.
+
+3. **Reusability** : Components specific to a page can be reused in other pages, promoting code modularity.
+
+## <span id="structure">Typical Structure of a "pages" Folder</span>
+
+The structure of a "pages" folder can vary depending on the size of your application, but here is a typical structure you might adopt:
+```
+📁 Pages
+├── 📁 Home
+├── 📁 User
+│   ├── 📁 UserProfile
+├── 📁 Posts
+│   ├── 📁 Article
+├── 📁 Admin
+```
+
+In this structure, each page, such as "Home" or "User," is typically defined in its own file. If a page is complex and requires related components, you can create a sub-folder to maintain order related to the URL, as with "UserProfile" or "Article" in this example.
+
+## <span id="usage">🧑🏻‍💻 Usage Example</span>
+
+Suppose we have a "UserProfile" page with a complex structure:
+
+```
+📁 UserProfile
+├── 📄 index.ts
+├── 📄 UserProfile.tsx
+├── 📄 routes.tsx
+```
+```javascript
+// index.ts
+export { userProfileRoutes } from './routes';
+
+// routes.tsx (react-router-dom v6)
+import { RouteObject } from 'react-router-dom';
+import { UserProfile } from './UserProfile';
+
+export const userProfileRoutes: RouteObject = {
+  path: 'user-profile',
+  element: <UserProfile />,
+};
+
+// UserProfile.tsx
+export const UserProfile = () => {
+  return (
+    <div>
+      UserProfile
+      {/* Content of the UserProfile page */}
+    </div>
+  );
+}
+```
+
+By using a "pages" folder and the ability to create sub-folders, we effectively organize our pages and their related components for better management of our application.
+
+
+## <span id="best-practice">🎖️ Best Practice</span>
+When working with page components, it is advisable to follow these best practices to maintain a clean and organized code structure:
+
+#### - Minimize Business Logic
+
+Limit the inclusion of business logic within page components. 
+
+Instead, delegate complex business logic to separate utility functions, services, or hooks. This keeps your page components focused on rendering and layout.
+
+#### - Data Presence Control
+
+Keep the logic within page components to a minimum, focusing primarily on controlling the presence of data. 
+
+If data is not available or meets certain conditions, consider redirecting to a dedicated error or not-found page.
+
+---
+***By adopting these practices, you create page components that are focused on their primary responsibilities, leading to cleaner and more maintainable code.***

package/src/providers/QueryClientProvider/QueryClientProvider.tsx

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

package/src/providers/QueryClientProvider/index.ts

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

package/src/providers/README.md

@@ -0,0 +1,115 @@
+# 📁 providers 
+
+The "providers" folder is designed to expose service handlers and custom contexts that provide shared functionality across our entire application. It serves as a centralized way to manage services such as authentication, authorization, translation management, and many others.
+
+## 📑 Table of Contents
+  - [Why Use a "providers" Folder?](#folder-organization)
+  - [Structure of a "providers" Folder](#structure)
+  - [Usage Example](#usage)
+  - [Best Practice](#best-practice)
+
+## <span id="folder-organization">Why Use a "providers" Folder?</span>
+
+1. **Centralization** : By grouping all our service handlers in a "providers" folder, we centralize the management of these services, making configuration and usage simpler.
+
+2. **Reusability** : Service handlers and custom contexts exposed in this folder can be reused across different components of our application, promoting code reuse.
+
+3. **Better Separation of Concerns** : By separating services from the user interface, we improve code readability and adhere to the separation of concerns principle.
+
+## <span id="structure">Structure of a "providers" Folder</span>
+
+The structure of a "providers" folder can vary based on your project's needs, but here is a typical structure you might adopt :
+
+```
+📁 providers
+├── 📁 AuthProvider
+├── 📁 AuthorizationProvider
+├── 📁 TranslationProvider
+├── 📁 CustomRouterProvider
+├── 📁 CustomContextProvider
+├── 📁 ...
+```
+
+Each file, such as "AuthProvider.ts" or "TranslationProvider.ts," contains a service handler or custom context intended to be used throughout your application.
+
+## <span id="usage">🧑🏻‍💻Usage Example </span>
+
+Suppose we have an authentication service handler "AuthProvider" in our "providers" folder:
+
+```javascript
+// AuthProvider.js
+import { createContext, useState } from 'react';
+
+export const AuthContext = createContext();
+
+export const AuthProvider = ({ children }) => {
+  const [isAuthenticated, setIsAuthenticated] = useState(false);
+
+  const login = () => {
+    setIsAuthenticated(true);
+  };
+
+  const logout = () => {
+    setIsAuthenticated(false);
+  };
+
+  return (
+    <AuthContext.Provider value={{ isAuthenticated, login, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+```
+We can then use this authentication service provider in our components by wrapping our components in the provided context:
+```javascript
+import { AuthProvider } from '@Front/Providers/AuthProvider';
+
+export const App = () => {
+  return (
+    <AuthProvider>
+      {/* Vos composants React ici */}
+    </AuthProvider>
+  );
+}
+```
+## <span id="best-practice">🎖️ Best Practice</span>
+
+A good practice is to set up a Higher Order Component (HOC) "withProvider" that allows injecting all providers at 
+once.
+
+Example:
+```typescript
+import { ComponentType } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { AuthProvider } from '@Front/Providers/AuthProvider';
+import { QueryClientProvider }  from '@Front/Providers/QueryClientProvider ';
+
+export interface WithRootProps {
+  queryClient: QueryClient;
+}
+
+export const withProvider = <P extends object>(Component: ComponentType<P>) => {
+  const WithProvider = ({ queryClient, ...props }: P & WithRootProps) => (
+    <QueryClientProvider client={queryClient}>
+        <AuthProvider>
+          <Component {...props as P} />
+        </AuthProvider>
+    </QueryClientProvider>
+  );
+  WithProvider.displayName = `withProvider(${Component.displayName || Component.name})`
+
+  return WithProvider
+
+}
+```
+
+```javascript
+import { withProvider } from '@Front/Providers/withProvider';
+import { App } from '@Front/components/App';
+
+const Root = withProvider(App);
+```
+
+----------
+
+***By using a "providers" folder, we centralize the management of services and custom contexts, enhancing code reuse and ease of maintenance.***

package/src/providers/index.ts

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

package/src/providers/withProviders/index.ts

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

package/src/providers/withProviders/withProviders.tsx

@@ -0,0 +1,18 @@
+import { QueryClientProvider } from '@Front/providers/QueryClientProvider';
+import type { ComponentProps, ComponentType } from 'react';
+
+type WithRootProps = {
+  queryClient: ComponentProps<typeof QueryClientProvider>['client'];
+};
+
+export const withProvider = <P extends object>(Component: ComponentType<P>) => {
+  const WithProvider = ({ queryClient, ...props }: P & WithRootProps) => (
+    <QueryClientProvider client={queryClient}>
+      <Component {...(props as P)} />
+    </QueryClientProvider>
+  );
+
+  WithProvider.displayName = `withProvider(${Component.displayName || Component.name})`;
+
+  return WithProvider;
+};

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

@@ -0,0 +1,3 @@
+// interface ImportMetaEnv {
+//   readonly FRONT_FOO: string;
+// }

package/src/routing/README.md

@@ -0,0 +1,80 @@
+# 📁routing
+
+The "routing" folder is responsible for managing navigation within the application. We use the `react-router-dom` library to facilitate route creation and navigation between different views of our application.
+
+## 📑 Table of Contents
+  - [Folder Organization](#folder-organization)
+  - [Using `react-router-dom`](#react-router-dom)
+  - [Using `appRoutes.ts`](#using-appRoutes)
+  - [Learn More](#learn-more)
+
+## <span id="folder-organization">Folder Organization</span>
+
+In the "routing" folder, you can find the following files and components:
+
+1. **`routesObject.tsx`** : This file contains the configuration of our main router. It declares the various routes of the application and defines the components associated with each route.
+
+2. **`routerFactory.ts`** : The `routerFactory.ts` file can contain functions or reusable components related to routing. You can place routing utilities or custom components to facilitate navigation management in our application.
+
+3. **`appRoutes.ts`** It contains a simple structure to define the paths of our application.
+
+## <span id="react-router-dom">🧑🏻‍💻 Using `react-router-dom` </span>
+
+`react-router-dom` is a library that makes it easy to create routes in a React application. You can import it into the appropriate files to define routes and manage navigation between views. Here's a simple example of its usage:
+
+```javascript
+import { createRoot } from "react-dom/client";
+import {
+  createBrowserRouter,
+  RouterProvider,
+ } from "react-router-dom";
+
+const router = createBrowserRouter([
+  {
+    path: "/",
+    element: (
+      <div>
+        <h1>Hello World</h1>
+        <Link to="about">About Us</Link>
+      </div>
+    ),
+  },
+  {
+    path: "about",
+    element: <div>About</div>,
+  },
+]);
+
+createRoot(document.getElementById("root")).render(
+  <RouterProvider router={router} />
+);
+```
+
+## <span id="using-appRoutes">Using `appRoutes.ts`</span>
+How to define a router with parameters ? 
+
+The simplest way is to write it with the parameters as `react-router` requires, and when using it in a `NavLink` call the `generatPath` function from `react-router`.
+
+For example:
+
+```javascript
+// appRoutes.ts
+export const appRoutes = {
+  home: '/',
+  post: '/post',
+  article: '/post/:id',
+}
+// component.tsx
+import { NavLink, generatePath } from 'react-router-dom';
+import { appRoutes  } from '@Front/routing/appRoutes';
+export const ComponentName = () => {
+  return (
+    <NavLink to={generatePath(appRoutes .article, { id: 1 })}>link to article 1</NavLink>
+ );
+};
+```
+With the `generatePath` function, it is possible to generate URIs with dynamic parameters.
+
+  
+## <span id="learn-more">🙇 Learn More</span>
+- [React Router](https://reactrouter.com/en/main/start/overview)

package/src/routing/appRoutes.ts

@@ -0,0 +1,5 @@
+export const approutes = {
+  home: '/',
+  reactQueryDemo: '/reactQueryDemo',
+  reactHookFormDemo: '/reactHookFormDemo',
+};

package/src/routing/routerFactory.ts

@@ -0,0 +1,10 @@
+import { createBrowserRouter } from 'react-router-dom';
+import { routeObject } from './routes';
+
+interface CreateRouterProps {
+  basename?: string;
+}
+
+export const createRouter = ({ basename }: CreateRouterProps = {}) => {
+  return createBrowserRouter(routeObject, { basename });
+};

package/src/routing/routes.tsx

@@ -0,0 +1,13 @@
+import { demoRoutes } from '@Front/pages/Demo';
+import { Error } from '@Front/pages/Error';
+import { Layout } from '@Front/pages/Layout';
+import type { RouteObject } from 'react-router-dom';
+
+export const routeObject: RouteObject[] = [
+  {
+    path: '/',
+    element: <Layout />,
+    children: [demoRoutes],
+    errorElement: <Error />,
+  },
+];

package/src/types/README.md

@@ -0,0 +1,61 @@
+# 📁 types 
+
+The "types" folder: since we are using TypeScript, this folder is intended to contain custom type definition files that enhance type checking and auto-completion in your code.
+
+## 📑 Table of Contents
+  - [Why use a "types" folder?](#folder-organization)
+  - [Structure of a "types" folder](#structure)
+  - [Example of usage](#usage)
+
+## <span id="folder-organization">Why use a "types" folder?</span>
+
+1. **Type Checking** : By defining custom types for our application, we improve type checking, making it easier to detect and prevent typing errors.
+
+2. **Better Auto-Completion** : Custom type definition files allow code editors to provide more accurate auto-completion when working with objects, functions, and components.
+
+3. **Integrated Documentation** : By creating explicit types, you effectively document your code, making it easier for other developers to understand your components, functions, and data.
+
+## <span id="structure">Structure of a "types" folder</span>
+
+The structure of a "types" folder can vary based on need, but here's a typical structure you might adopt :
+
+```
+📁 src
+📁 types
+├── 📄 customTypes.ts
+├── 📄 apiTypes.ts
+```
+
+In this structure, each file, such as "customTypes.ts" or "apiTypes.ts," contains type definitions specific to your application. For example, you might define types for API data, business objects, or component props.
+
+## <span id="usage">🧑🏻‍💻 Example of usage</span>
+
+Suppose you have defined a custom type in "customTypes.ts":
+
+```typescript
+// customTypes.ts
+export type User = {
+  id: number;
+  name: string;
+  email?: string;
+};
+```
+
+You can then use this type in your React components to define props or states, enhancing type checking:
+
+```typescript
+import { User } from '@Front/types/customTypes';
+
+type UserProfileProps = {
+  user: User;
+};
+
+export const UserProfile = ({ user }: UserProfileProps) => {
+  return (
+    <div id={user.id}>
+      <h1>{user.name}</h1>
+      {user.email && <p>Email: {user.email}</p>}
+    </div>
+  );
+};
+```

package/src/types/demoApi.ts

@@ -0,0 +1,9 @@
+export type User = {
+  id: number;
+  firstName: string;
+  lastName: string;
+  age: number;
+  email: string;
+};
+
+export type Users = User[];

package/src/types/profileTypes.ts

@@ -0,0 +1,5 @@
+export type ProfileType = {
+  mail: string;
+  firstName: string;
+  lastName: string;
+};

package/src/ui/README.md

@@ -0,0 +1,141 @@
+# 📁 ui 
+The "ui" folder is a directory designed to group and organize reusable components. 
+
+We follow the concept of Atomic design to structure our components into "atoms," "molecules," "organisms," and "templates," ensuring consistent design and maximum reusability.
+
+## 📑 Table of Contents
+  - [Why use a "ui" folder with Atomic Design](#folder-organization)
+  - [Structure of a "ui" folder according to Atomic Design](#structure)
+  - [Usage Example](#usage)
+  - [Best Practice](#best-practice)
+
+
+## <span id="folder-organization">Why use a "ui" folder with Atomic Design?</span>
+
+1. **Modularity** : Atomic Design divides components into levels of increasing complexity, making it easy to create reusable components at different levels.
+
+2. **Visual Consistency** : By following the concept of Atomic Design, we can maintain visual consistency across our entire application by reusing atoms, molecules, and organisms.
+
+3. **Productivity** : Creating prefab components in a "ui" folder speeds up development by reducing code duplication.
+
+## <span id="structure">Structure of a "ui" folder according to Atomic Design</span>
+
+The structure of a "ui" folder can follow the hierarchy of Atomic Design:
+
+```
+ 📁 ui
+├── 📁 atoms
+│   ├──📁 Button
+│   ├──📁 Input
+│   ├── ...
+├── 📁 molecules
+│   ├── 📁 FormField
+│   ├── 📁 SearchBar
+│   ├── ...
+├── 📁 organisms
+│   ├── 📁 Header
+│   ├── 📁 Footer
+│   ├── ...
+├── 📁 templates
+│   ├── 📁 PageTemplate
+│   ├── ...
+```
+
+Each level (atoms, molecules, organisms, templates) groups components based on their complexity. You can create subfolders to better organize the components.
+
+## <span id="usage">🧑🏻‍💻Example of usage</span>
+
+## Using components from Atomic Design
+
+In our project, we use Atomic Design to organize our reusable components into levels ranging from "atoms" to "templates." Here's a concrete example of using these components in our application.
+
+### Atom - "Button" Component
+
+"Atoms" are basic components that don't depend on other components. In our "ui/atoms" folder, we have the "Button" component. It's a simple UI element that we can use as follows:
+
+```javascript
+import { Button } from '@Front/ui/atoms/Button';
+
+export const MyComponent = () => {
+  return (
+    <div>
+      <Button label="Cliquez-moi" />
+      {/* ... other elements of the application */}
+    </div>
+  );
+}
+```
+
+### Molecule - "SearchBar" Component
+"Molecules" are more complex components that group atoms to form a functional set. In our "ui/molecules" folder, we have the "SearchBar" component that uses the atomic "Button":
+
+
+```javascript
+import { SearchBar } from '@Front/ui/molecules/SearchBar';
+
+export const MyComponent = () => {
+  return (
+    <div>
+      <SearchBar placeholder="Rechercher..." />
+        {/* ... other elements of the application */}
+    </div>
+  );
+}
+```
+The "SearchBar" component is a molecule because it combines the "Button" atom with other atoms.
+
+### Organism - "Header" Component
+"Organisms" are even more complex components that combine molecules and atoms to create self-contained parts of the UI. In our "ui/organisms" folder, we have the "Header" component that might include the molecular "SearchBar":
+
+```javascript
+import Header from '@Front/ui/organisms/Header';
+
+export const MyComponent = () => {
+  return (
+    <div>
+      <Header />
+       {/* ... other elements of the application */}
+    </div>
+  );
+}
+```
+The "Header" component is an organism because it combines the molecular "SearchBar" with other elements to form a self-contained part of the interface.
+
+### Templates - "PageTemplate" Component
+"Templates" are "skeleton" components that define the placement of elements using React's composition ability.
+
+In our "ui/templates" folder, we have the "PageTemplate" component that defines the placement of the "topBar," "body," and "footer" to create a complete page:
+
+```javascript
+import PageTemplate from '@Front/ui/templates/PageTemplate';
+
+export const MyComponent = () => {
+  return (
+    <PageTemplate
+      topBar={<div>TopBar</div>}
+      body={<div>Boby</div>}
+      footer={<div>Footer</div>}
+    />
+  );
+}
+```
+The "PageTemplate" component is a template because it incorporates the "Header" organism and other elements to create a complete page.
+
+## <span id="best-practice">🎖️ Best Practice</span>
+When incorporating external component libraries, it is recommended to adhere to the following best practices for the organization of UI components:
+
+#### - Export Components via the `ui` Directory
+
+Always export UI components from the `ui` directory, even if they are sourced from an external component library. 
+
+This practice serves as a central point for managing component exports and facilitates handling bugs or breaking changes.
+
+#### - Centralized Component Management
+By exporting components through the ui directory, you establish a centralized location for managing changes or addressing issues related to external components. 
+
+In the event of a bug or breaking change, modifications can be made at a single location, preventing the need to update multiple parts of the codebase.
+
+This approach contributes to better maintainability and ensures that updates to external components are efficiently managed.
+
+---
+***By adopting this practice, you create a clear separation between your custom components and external components, simplifying maintenance and reducing the impact of changes from external dependencies.***

package/src/ui/atoms/Input/Input.module.scss

@@ -0,0 +1,32 @@
+.inputContainerStyle {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: space-between;
+}
+
+%inputStyle {
+  margin: 10px;
+  padding: 10px;
+}
+
+.inputStyle {
+  @extend %inputStyle;
+}
+
+.hasInputError {
+  @extend %inputStyle;
+
+  border: 1px solid red;
+  border-radius: 2px;
+
+  &:focus {
+    border: 2px solid red;
+    outline: none !important;
+  }
+}
+
+.errorsStyle {
+  font-size: x-small;
+  color: red;
+}

package/src/ui/atoms/Input/Input.tsx

@@ -0,0 +1,27 @@
+import { forwardRef, InputHTMLAttributes, useId } from 'react';
+import classes from './Input.module.scss';
+
+interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  label: string;
+  hasError?: boolean;
+  helperText?: string;
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(({ label, hasError, helperText, ...rest }, ref) => {
+  const id = useId();
+  return (
+    <>
+      <div className={classes.inputContainerStyle}>
+        <label htmlFor={id}>{label} </label>
+        <input id={id} ref={ref} {...rest} className={hasError ? classes.hasInputError : classes.inputStyle} />
+      </div>
+      {hasError && (
+        <p role="alert" className={classes.errorsStyle}>
+          {helperText}
+        </p>
+      )}
+    </>
+  );
+});
+
+Input.displayName = 'Input';

package/src/ui/atoms/Input/index.ts

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

package/src/ui/atoms/Logo/Logo.module.css

@@ -0,0 +1,3 @@
+.logoStyle {
+  height: 100%;
+}

package/src/ui/atoms/Logo/Logo.tsx

@@ -0,0 +1,11 @@
+import classes from './Logo.module.css';
+
+type LogoProps = {
+  src: string;
+  alt: string;
+  size?: string;
+};
+
+export const Logo = ({ src, alt, size = '80px' }: LogoProps) => {
+  return <img className={classes.logoStyle} style={{ width: size }} src={src} alt={alt} />;
+};

package/src/ui/atoms/Logo/index.ts

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