data-primals-engine 1.0.11 → 1.1.1

package/README.md

@@ -43,6 +43,21 @@ Possibly create a `.env` file:
 ```env
 MONGO_DB_URL=mongodb://127.0.0.1:27017
 ```
+| Variable              | 	Description                                                            | 	Example                                 |
+|:----------------------|:------------------------------------------------------------------------|:-----------------------------------------| 
+| MONGO_DB_URL          | Connection URL for your MongoDB database.                               | 	mongodb://user:pass@host:27017/db       |
+| PORT                  | 	Port on which the Express server will listen.	                         | 7633                                     |
+| JWT_SECRET            | 	Secret key for signing JWT authentication tokens.	                     | a_long_random_secret_string              |
+| OPENAI_API_KEY        | 	Your optional OpenAI API key for AI features.	                         | sk-xxxxxxxxxxxxxxxxxxxx                  |
+| GOOGLE_API_KEY        | 	Your optional Google (Gemini) API key for AI features.	                | AIzaSyxxxxxxxxxxxxxxxxxxxx               |
+| AWS_ACCESS_KEY_ID     | 	AWS access key for S3 storage (files, backups). Keep empty to disable	 | AKIAIOSFODNN7EXAMPLE                     |
+| AWS_SECRET_ACCESS_KEY | 	AWS secret access key.	                                                | wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY |                                 |
+| AWS_REGION            | 	Region for your S3 bucket.                                             | 	eu-west-3                               |                                                                 |
+| AWS_S3_BUCKET_NAME    | 	Name of the S3 bucket to use.                                          | 	my-backup-bucket                        |                                                                             |
+| SMTP_HOST             | 	SMTP server host for sending emails.	                                  | smtp.example.com                         |
+| SMTP_PORT             | 	SMTP server port.	                                                     | 587                                      |
+| SMTP_USER             | 	Username for SMTP authentication.                                      | 	user@example.com                        |
+| SMTP_PASS             | 	Password for SMTP authentication.                                      | 	password                                |
 
 Start the server:
 ```bash
@@ -73,6 +88,27 @@ Define schemas using JSON:
   ]
 }
 ```
+| Type        | Description                                                                         | 	Properties/Notes                                                         | 
+|:------------|:------------------------------------------------------------------------------------|:--------------------------------------------------------------------------|
+| string	     | Character string.                                                                   | 	minLength, maxLength                                                     |
+| string_t	   | International character string ID.                                                  | 	same as string, translated in { key, value }                             |
+| number	     | Numeric value (integer or float).                                                   | 	min, max                                                                 |
+| boolean	    | Boolean value (true/false).	                                                        | –                                                                         |
+| date	       | Stores a ISO date.	                                                                 | –                                                                         |
+| datetime	   | Stores an ISO date and time.	                                                       | –                                                                         |
+| richtext	   | Rich text field (HTML) for WYSIWYG editors.	                                        |                                                                           |
+| richtext_t	 | International rich text field (HTML) for WYSIWYG editors.	                          | i18n                                                                      |
+| email	      | String validated as an email address.	                                              | –                                                                         |
+| password	   | String that will be automatically hashed.	                                          | –                                                                         |
+| enum	       | Allows selecting a value from a predefined list.	                                   | items: ["value1", "value2"]                                               |
+| relation	   | Creates a link to a document in another model.                                      | 	relation: "target_model_name", multiple: true/false                      |
+| file	       | For uploading a file (stored on S3 if configured).	                                 | allowedTypes:['image/jpeg', 'image/png', 'image/bmp'], maxSize: 1024*1000 |
+| image	      | Specialized file type for images, with preview.	                                    | –                                                                         |
+| array	      | Stores a list of values.	                                                           | itemsType: 'enum' // any type except relations                            |
+| object	     | Stores a nested JSON object.	–                                                      |                                                                           |
+| code	       | Stores language="*" as string, stores language="json" as arbitrary JSON structure.	 | language="json" conditionBuilder=true                                     |                                            
+| model	      | Stores a model by name                                                              | –                                                                         |                                            
+| modelField	 | Stores a model field path	                                                          | –                                                                         |                                            
 
 ### 2. Modules
 Activatable features:

package/client/README.md

@@ -0,0 +1,116 @@
+This guide explains how to integrate and use the client-side part of the `data-primals-engine` library in an external React application (such as hackersonline).  
+The library provides a set of context Providers, Hooks, and UI components to interact with the `data-primals-engine` backend.
+
+# Table of Contents
+## Prerequisites
+Your React application must have the following dependencies installed:
+- react & react-dom (version >= 18.0.0)
+- react-query (version >= 3.0.0)
+- react-router-dom
+- react-cookie
+
+## Installation
+Install the library:
+```shell
+npm install ../../data-primals-engine
+```
+Install peer dependencies:
+```shell
+npm install react-query react-router-dom react-cookie
+```
+
+## Basic Setup
+
+The setup mainly occurs in your application's root file (typically App.jsx or main.jsx).
+
+It consists of initializing a single QueryClient instance and wrapping your app with the required Providers.
+
+### Set the QueryClient (Singleton)
+For react-query caching to work correctly across your app (including inside the library), it is crucial to instantiate QueryClient only once.
+
+The data-primals-engine library needs to know which QueryClient instance you're using. It exports a setQueryClient function for that purpose.
+
+### Set up the Providers
+Your app must be wrapped by several Providers in the correct order so the contexts are available to all child components.
+
+## Full example (App.jsx)
+Here's what your main application file should look like:
+```jsx
+// In your main App.jsx file (e.g., hackersonline/client/src/App.jsx)
+
+import React from 'react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { CookiesProvider } from 'react-cookie';
+
+// 1. Import QueryClient and its Provider from react-query
+import { QueryClient, QueryClientProvider } from 'react-query';
+
+// 2. Import Providers and the config function from data-primals-engine
+import {
+   ModelProvider,
+   AuthProvider,
+   UIProvider,
+   NotificationProvider,
+   setQueryClient // <-- Important config function
+} from 'data-primals-engine/client';
+
+// 3. Import the i18n config (see dedicated section)
+import 'data-primals-engine/i18n';
+
+// 4. (CRUCIAL) Create a unique instance of QueryClient
+const queryClient = new QueryClient();
+
+// 5. (CRUCIAL) Pass the instance to the shared library
+setQueryClient(queryClient);
+
+// Your page components
+import HomePage from './pages/HomePage';
+import UserDashboard from './pages/UserDashboard';
+
+function App() {
+   return (
+           // 6. Wrap the app with all required providers
+           <QueryClientProvider client={queryClient}>
+              <AuthProvider>
+                 <CookiesProvider>
+                    <ModelProvider>
+                       <BrowserRouter>
+                          <UIProvider>
+                             <NotificationProvider>
+
+                                {/* Your app content */}
+                                <Routes>
+                                   <Route path="/" element={<HomePage />} />
+                                   <Route path="/dashboard" element={<UserDashboard />} />
+                                   {/* ... other routes */}
+                                </Routes>
+
+                             </NotificationProvider>
+                          </UIProvider>
+                       </BrowserRouter>
+                    </ModelProvider>
+                 </CookiesProvider>
+              </AuthProvider>
+           </QueryClientProvider>
+   );
+}
+
+export default App;
+```
+
+## Internationalization (i18n)
+The library comes with its own i18next configuration and translation files.
+To enable it in your app, you just need to import the config module once in your main file (App.jsx or main.jsx):
+
+```jsx
+// In App.jsx or main.jsx
+import 'data-primals-engine/i18n';
+```
+
+This simple import will:
+
+- Initialize i18next.
+- Load default translations (French, English, etc.).
+- Enable automatic browser language detection.
+
+You can then use react-i18next components and hooks (useTranslation, Trans) as usual in your application.

package/client/index.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Welcome page - data-primals-engine</title>
+    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="shortcut icon" href="/favicon.ico" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
+    <link rel="manifest" href="/site.webmanifest" />
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Nunito+Sans:ital,opsz,wght@0,6..12,200..1000;1,6..12,200..1000&family=Outfit:wght@100..900&display=swap" rel="stylesheet">
+  </head>
+  <body>
+    <div id="root"></div>
+
+    <!-- Google tag (gtag.js) -->
+    <script async src="https://www.googletagmanager.com/gtag/js?id=G-NDHNSVB4YB"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+
+    </script>
+
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/client/index.js

@@ -0,0 +1,25 @@
+// data-primals-engine/client/src/index.js
+
+// Contexts
+export { ModelProvider, useModelContext } from './src/contexts/ModelContext';
+export { AuthProvider, useAuthContext } from './src/contexts/AuthContext';
+export { UIProvider, useUI } from './src/contexts/UIContext';
+export { NotificationProvider, useNotificationContext } from './src/NotificationProvider';
+
+// Hooks
+export { default as useLocalStorage } from './src/hooks/useLocalStorage';
+
+// Components
+export { default as DataLayout } from './src/DataLayout';
+export { default as Webpage } from './src/Webpage';
+export { SelectField, TextField } from './src/Field';
+export { default as Button } from './src/Button';
+export { default as APIInfo } from './src/APIInfo';
+export { NotificationList } from './src/Notification';
+export { DashboardsPage } from './src/Dashboard';
+export { default as RestoreDialog } from './src/RestoreDialog';
+export { default as MessageRotator } from './src/MessageRotator';
+export { default as DocumentationPageLayout } from './src/DocumentationPageLayout';
+export { default as ContentView } from './src/ContentView';
+export { default as AssistantChat } from './src/AssistantChat';
+export { setQueryClient } from './src/App.jsx';