Skip to content

Commit a9547be

Browse files
fblettnerfblettner
committed
Add documentation for liberty core
1 parent 1bcea11 commit a9547be

File tree

74 files changed

+49845
-200
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

74 files changed

+49845
-200
lines changed

‎.DS_Store

0 Bytes
Binary file not shown.

‎docs/liberty/core/getting-started.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Liberty Core
2+
3+
A modular, extensible framework for building modern applications with reusable UI components and application management tools.
4+
5+
## Overview
6+
**Liberty Core** is a comprehensive framework that provides a robust set of **UI components**, **application management tools**, and **context providers** to streamline development.
7+
8+
### Features
9+
- 🚀 **Prebuilt UI Components**: Buttons, Dialogs, Alerts, Tables, and more.
10+
- ⚙️ **Context Providers**: Manage applications, authentication, users, and modules.
11+
- 🎨 **Theming Support**: Customizable styles for different UI needs.
12+
- 🔌 **Extensibility**: Easily add and configure new modules.
13+
- 🌐 **Integrated State Management**: Built-in context for handling global application state.
14+
15+
### Backend Integration
16+
Liberty Core is designed to seamlessly integrate with the Liberty Framework, which includes a FastAPI-based backend powered by PostgreSQL. This backend provides a preconfigured database and a complete set of ready-to-use APIs, allowing developers to focus on building applications without worrying about backend setup.
17+
18+
- 🔗 Backend Repository: Liberty Framework
19+
20+
## Documentation Structure
21+
The documentation is divided into the following categories:
22+
23+
### **Application Management**
24+
- 🔹 **[AppProvider]** - Provides global application state.
25+
- 🔹 **[Modules]** - Handles feature activation.
26+
- 🔹 **[Applications]** - Manages multiple application instances.
27+
- 🔹 **[Users]** - User authentication and profiles.
28+
- 🔹 **[Authentication]** - Token-based authentication system.
29+
- 🔹 **[Use Media Query]** - Responsive design utilities.
30+
31+
### **UI Components**
32+
- 🎯 **Alerts & Messages** - Alert, AlertMessage, SnackMessage.
33+
- 🎛 **Buttons & Toggles** - Button, IconButton, Toggle.
34+
- 🗔 **Dialogs & Overlays** - Dialog, ConfirmationDialog, DialogExport, Popper, Tooltip.
35+
- ✍️ **Inputs & Forms** - Input, Checkbox, Select.
36+
- 📂 **Navigation** - Menu, Tabs.
37+
- 📊 **Data Display** - Table, List, Grid, Typography.
38+
39+
## Getting Started
40+
To use Liberty Core, install it via npm:
41+
\`\`\`sh
42+
npm install @nomana-it/liberty-core
43+
\`\`\`
44+
45+
Then import the necessary components:
46+
\`\`\`tsx
47+
import { AppProvider, Button, Dialog } from "liberty-core";
48+
49+
export const MyApp = () => (
50+
<AppProvider>
51+
<Button>Click Me</Button>
52+
</AppProvider>
53+
);
54+
\`\`\`
55+
56+
## Useful Links
57+
🔗 **GitHub Repository (Core):** [Liberty Core](https://github.com/fblettner/liberty-core/)
58+
🔗 **GitHub Repository (Test Project):** [Liberty Test](https://github.com/fblettner/liberty-test/)
59+
📖 **Live Documentation:** [Liberty Core Docs](https://docs.nomana-it.fr/liberty-core/)
60+
💖 **Sponsor & Support:** [Sponsor Liberty Core](https://github.com/sponsors/fblettner)

‎docs/liberty/core/new-project.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Creating a New React App with Liberty Core
2+
3+
## **Description**
4+
Liberty Core provides a modular and extensible foundation for building modern web applications. This guide explains how to create a new React app using **Liberty Core**, set up authentication with **OIDC**, and configure **translations and error handling**.
5+
6+
---
7+
8+
## **Step 1: Initialize a New React Project**
9+
Create a new React project using Vite (recommended for performance):
10+
11+
```sh
12+
npm create vite@latest my-liberty-app --template react-ts
13+
cd my-liberty-app
14+
```
15+
16+
Then, install the required dependencies:
17+
18+
```sh
19+
npm install liberty-core react-oidc-context @mui/material @emotion/react @emotion/styled
20+
```
21+
22+
---
23+
24+
## **Step 2: Create the Application Entry Point**
25+
Create a new file called \`main.tsx\` inside \`src/\` with the following setup:
26+
27+
```tsx
28+
import React from "react"
29+
import ReactDOM from "react-dom/client"
30+
import { App } from "./App"
31+
import { AppProvider, Div, ErrorBoundary, TranslationProvider } from "liberty-core"
32+
import { AuthProvider, useAuth as oidcUseAuth } from "react-oidc-context";
33+
34+
// OIDC Configuration
35+
const oidcConfig = {
36+
authority: window.location.origin + "/oidc/realms/Liberty",
37+
client_id: "liberty-framework",
38+
redirect_uri: window.location.origin,
39+
};
40+
41+
// Render the app inside ReactDOM with the required providers
42+
ReactDOM.createRoot(document.getElementById("root")!).render(
43+
<React.StrictMode>
44+
<AuthProvider {...oidcConfig}>
45+
<AppProvider useAuth={oidcUseAuth}>
46+
<ErrorBoundary fallback={<Div>An error has occurred</Div>}>
47+
<TranslationProvider>
48+
<App />
49+
</TranslationProvider>
50+
</ErrorBoundary>
51+
</AppProvider>
52+
</AuthProvider>
53+
</React.StrictMode>,
54+
)
55+
```
56+
57+
---
58+
59+
## **Step 3: Create the App Component**
60+
Now, create a file named \`App.tsx\` inside \`src/\` and add:
61+
62+
```tsx
63+
import { AppsContent, LYThemeProvider, useAppContext } from 'liberty-core';
64+
65+
export function App() {
66+
const { userProperties, appsProperties, modulesProperties } = useAppContext();
67+
68+
return (
69+
<LYThemeProvider>
70+
<AppsContent />
71+
</LYThemeProvider>
72+
);
73+
}
74+
```
75+
76+
---
77+
78+
## **Step 4: Run the Application**
79+
Start the development server:
80+
81+
```sh
82+
npm run dev
83+
```
84+
85+
Your **Liberty Core** app is now running! 🎉
86+
87+
---
88+
89+
## **Customization**
90+
### **1. Customize the Theme**
91+
Modify the theme inside \`App.tsx\`:
92+
93+
```tsx
94+
import { AppsContent, LYThemeProvider } from 'liberty-core';
95+
import { theme } from './theme'; // Create a theme file
96+
97+
export function App() {
98+
return (
99+
<LYThemeProvider customTheme={theme}>
100+
<AppsContent />
101+
</LYThemeProvider>
102+
);
103+
}
104+
```
105+
106+
---
107+
108+
### **2. Customize Menus**
109+
To override the default menus, use \`getMenus\` in \`AppProvider\`:
110+
111+
```tsx
112+
const getMenus = async () => {
113+
return {
114+
items: [
115+
{
116+
MENU_LABEL: "Dashboard",
117+
MENU_COMPONENT: "FormsDashboard",
118+
MENU_COMPONENT_ID: 1,
119+
},
120+
{
121+
MENU_LABEL: "Settings",
122+
MENU_COMPONENT: "FormsContent",
123+
MENU_COMPONENT_ID: 2,
124+
},
125+
],
126+
};
127+
};
128+
129+
// Wrap AppProvider with custom menus
130+
<AppProvider getMenus={getMenus}>
131+
```
132+
133+
---
134+
135+
## **Conclusion**
136+
You have now set up a **React application using Liberty Core** with authentication, error handling, translation, and theming. 🎯
137+
138+
## Useful Links
139+
🔗 **GitHub Repository (Core):** [Liberty Core](https://github.com/fblettner/liberty-core/)
140+
🔗 **GitHub Repository (Test Project):** [Liberty Test](https://github.com/fblettner/liberty-test/)
141+
📖 **Live Documentation:** [Liberty Core Docs](https://docs.nomana-it.fr/liberty-core/)
142+
💖 **Sponsor & Support:** [Sponsor Liberty Core](https://github.com/sponsors/fblettner)

‎docs/liberty/core/services/applications.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Applications Configuration
2+
3+
## Description
4+
The `Applications Configuration` defines multiple applications within the Liberty Framework. Each application has specific settings such as offset, limit, version, dashboard, and theme.
5+
6+
## Data Structure
7+
| Field Name | Type | Description |
8+
|-----------------|-----------|-------------|
9+
| `APPS_ID` | `number` | Unique application identifier. |
10+
| `APPS_NAME` | `string` | The name of the application. |
11+
| `APPS_DESCRIPTION` | `string` | Description of the application’s purpose. |
12+
| `APPS_POOL` | `string` | The database connection pool used by the application. |
13+
| `APPS_OFFSET` | `number` | The default offset value for queries. |
14+
| `APPS_LIMIT` | `number` | The maximum number of records per query. |
15+
| `APPS_VERSION` | `string` | The current version of the application. |
16+
| `APPS_DASHBOARD` | `number | undefined` | The dashboard ID associated with the app. |
17+
| `APPS_THEME` | `string` | The theme applied to the application. |
18+
| `APPS_SESSION` | `string` | The session mode (e.g., `session`). |
19+
| `APPS_JWT_TOKEN` | `string` | JWT token for authentication (if applicable). |
20+
21+
## Example Usage
22+
```tsx
23+
import { useAppContext } from "liberty-core";
24+
25+
export const ApplicationsExample = () => {
26+
const { appsProperties } = useAppContext();
27+
28+
return (
29+
<div>
30+
<h2>Available Applications</h2>
31+
<ul>
32+
{Object.entries(appsProperties).map(([key, app]) => (
33+
<li key={key}>
34+
<strong>{app.name}</strong> - {app.description} (Version: {app.version})
35+
</li>
36+
))}
37+
</ul>
38+
</div>
39+
);
40+
};
41+
```
42+
43+
## Useful Links
44+
🔗 **GitHub Repository (Core):** [Liberty Core](https://github.com/fblettner/liberty-core/)
45+
🔗 **GitHub Repository (Test Project):** [Liberty Test](https://github.com/fblettner/liberty-test/)
46+
📖 **Live Documentation:** [Liberty Core Docs](https://docs.nomana-it.fr/liberty-core/)
47+
💖 **Sponsor & Support:** [Sponsor Liberty Core](https://github.com/sponsors/fblettner)

‎docs/liberty/core/services/appprovider.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# AppProvider Component
2+
3+
## Description
4+
The `AppProvider` is a context provider that manages global state for the Liberty Framework. It provides access to:
5+
6+
- **Authentication state**
7+
- **Application properties**
8+
- **User properties**
9+
- **Module configurations**
10+
- **Snack messages**
11+
- **WebSocket handling**
12+
13+
This provider allows injecting custom functions for retrieving data such as applications, users, tokens, and menus.
14+
15+
## Props
16+
| Prop | Type | Default | Description |
17+
|-----------------|--------------------------|---------|-------------|
18+
| `children` | `ReactNode` | - | Components wrapped by the provider. |
19+
| `useAuth` | `() => AuthContextProps` | - | Custom authentication hook. |
20+
| `getModules` | `() => Promise<IModulesProps>` | - | Fetch function for modules configuration. |
21+
| `getApplications` | `() => Promise<IAppsProps>` | - | Fetch function for application settings. |
22+
| `getUser` | `() => Promise<IUsersProps>` | - | Fetch function for user details. |
23+
| `getMenus` | `() => Promise<IMenusProps>` | - | Fetch function for application menus. |
24+
25+
## Example Usage
26+
```tsx
27+
import { AppProvider, useAppContext } from "liberty-core";
28+
29+
export const AppProviderExample = () => {
30+
return (
31+
<AppProvider>
32+
<MyApp />
33+
</AppProvider>
34+
);
35+
};
36+
37+
const MyApp = () => {
38+
const { userProperties, modulesProperties } = useAppContext();
39+
40+
return (
41+
<div>
42+
<h2>User: {userProperties.name}</h2>
43+
<p>Debug Mode: {modulesProperties.debug.enabled ? "Enabled" : "Disabled"}</p>
44+
</div>
45+
);
46+
};
47+
```
48+
49+
## Useful Links
50+
🔗 **GitHub Repository (Core):** [Liberty Core](https://github.com/fblettner/liberty-core/)
51+
🔗 **GitHub Repository (Test Project):** [Liberty Test](https://github.com/fblettner/liberty-test/)
52+
📖 **Live Documentation:** [Liberty Core Docs](https://docs.nomana-it.fr/liberty-core/)
53+
💖 **Sponsor & Support:** [Sponsor Liberty Core](https://github.com/sponsors/fblettner)

‎docs/liberty/core/services/authentication.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Authentication & Token Management
2+
3+
## Description
4+
The authentication system in Liberty Framework uses an access token mechanism. A user provides their credentials, and if authenticated, they receive an access token.
5+
6+
## Data Structure
7+
### **Successful Response**
8+
| Field Name | Type | Description |
9+
|-------------|--------|-------------|
10+
| `access_token` | `string` | The generated token for the session. |
11+
| `token_type` | `string` | Type of token, usually `"bearer"`. |
12+
| `status` | `"success"` | Indicates authentication was successful. |
13+
| `message` | `string` | Message confirming login success. |
14+
15+
### **Failed Response (Login Error)**
16+
| Field Name | Type | Description |
17+
|-------------|--------|-------------|
18+
| `access_token` | `string` | Empty, as login failed. |
19+
| `token_type` | `string` | Type of token, usually `"bearer"`. |
20+
| `status` | `"failed"` | Indicates authentication failure. |
21+
| `message` | `string` | Error message `"loginError"`. |
22+
23+
### **Failed Response (Password Error)**
24+
| Field Name | Type | Description |
25+
|-------------|--------|-------------|
26+
| `access_token` | `string` | Empty, as authentication failed. |
27+
| `token_type` | `string` | Type of token, usually `"bearer"`. |
28+
| `status` | `"failed"` | Indicates authentication failure. |
29+
| `message` | `string` | Error message `"passwordError"`. |
30+
31+
## Example Usage
32+
```tsx
33+
import { getToken } from "liberty-core";
34+
35+
export const AuthenticationExample = async () => {
36+
const response = await getToken("admin", "admin");
37+
38+
if (response.status === "success") {
39+
console.log("Access Token:", response.access_token);
40+
} else {
41+
console.error("Authentication Failed:", response.message);
42+
}
43+
};
44+
```
45+
46+
## Useful Links
47+
🔗 **GitHub Repository (Core):** [Liberty Core](https://github.com/fblettner/liberty-core/)
48+
🔗 **GitHub Repository (Test Project):** [Liberty Test](https://github.com/fblettner/liberty-test/)
49+
📖 **Live Documentation:** [Liberty Core Docs](https://docs.nomana-it.fr/liberty-core/)
50+
💖 **Sponsor & Support:** [Sponsor Liberty Core](https://github.com/sponsors/fblettner)

0 commit comments

Comments
 (0)