@1urso/generic-editor 0.1.9 → 0.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +129 -129
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,141 +1,141 @@
|
|
|
1
1
|
# Generic Editor
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A powerful, framework-agnostic, and **100% customizable** React library for creating dynamic layouts, template generation, and visual editing. Designed to be the design engine within your application (Web, Electron, Tauri, Next.js, etc.).
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
## 📚
|
|
8
|
-
|
|
9
|
-
1. [
|
|
10
|
-
2. [
|
|
11
|
-
- [
|
|
12
|
-
- [Menu
|
|
13
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
3. [
|
|
16
|
-
- [
|
|
17
|
-
- [Data Binding
|
|
18
|
-
- [
|
|
19
|
-
- [
|
|
20
|
-
- [
|
|
7
|
+
## 📚 Table of Contents
|
|
8
|
+
|
|
9
|
+
1. [Installation and Configuration](#installation-and-configuration)
|
|
10
|
+
2. [User Guide (Visual Interface)](#user-guide-visual-interface)
|
|
11
|
+
- [Basic Manipulation](#basic-manipulation)
|
|
12
|
+
- [Context Menu and Styling](#context-menu-and-styling)
|
|
13
|
+
- [Working with Text and Fonts](#working-with-text-and-fonts)
|
|
14
|
+
- [Working with Images](#working-with-images)
|
|
15
|
+
3. [Developer Guide (Integration)](#developer-guide-integration)
|
|
16
|
+
- [Initialization and Props](#initialization-and-props)
|
|
17
|
+
- [Data Binding and Variables](#data-binding-and-variables)
|
|
18
|
+
- [Modes: Single Item vs. List](#modes-single-item-vs-list)
|
|
19
|
+
- [JSON Structure](#json-structure)
|
|
20
|
+
- [Generating HTML (Backend/Print)](#generating-html-backendprint)
|
|
21
21
|
4. [API Reference](#api-reference)
|
|
22
22
|
|
|
23
23
|
---
|
|
24
24
|
|
|
25
|
-
##
|
|
25
|
+
## Installation and Configuration
|
|
26
26
|
|
|
27
|
-
### 1.
|
|
27
|
+
### 1. Install the package
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
30
|
npm install @1urso/generic-editor
|
|
31
|
-
#
|
|
31
|
+
# or
|
|
32
32
|
yarn add @1urso/generic-editor
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
### 2.
|
|
35
|
+
### 2. Install Peer Dependencies
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
The editor uses modern libraries to ensure performance and accessibility. You need to install them in your project:
|
|
38
38
|
|
|
39
39
|
```bash
|
|
40
40
|
npm install @radix-ui/themes @radix-ui/react-icons react-resizable-panels re-resizable framer-motion @dnd-kit/core
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
### 3.
|
|
43
|
+
### 3. Import Styles
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
In your application entry file (e.g., `main.tsx`, `App.tsx`, or `layout.tsx` in Next.js), import the editor's CSS (required for the context menu) and Radix UI:
|
|
46
46
|
|
|
47
47
|
```tsx
|
|
48
|
-
import "@1urso/generic-editor/dist/generic-editor.css"; //
|
|
48
|
+
import "@1urso/generic-editor/dist/generic-editor.css"; // Essential for the editor to work
|
|
49
49
|
import "@radix-ui/themes/styles.css";
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
---
|
|
53
53
|
|
|
54
|
-
##
|
|
54
|
+
## User Guide (Visual Interface)
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
This section describes the features available to the **end user** who will use the editor on your platform.
|
|
57
57
|
|
|
58
|
-
###
|
|
58
|
+
### Basic Manipulation
|
|
59
59
|
|
|
60
|
-
|
|
60
|
+
The editor offers an experience similar to design tools like Canva or Figma:
|
|
61
61
|
|
|
62
|
-
- **
|
|
63
|
-
- **
|
|
64
|
-
- **
|
|
65
|
-
- **
|
|
66
|
-
- **
|
|
62
|
+
- **Add Elements**: Use the sidebar (or buttons you implement) to drag or click and add Texts, Images, or Boxes.
|
|
63
|
+
- **Move**: Click and drag any element to reposition it.
|
|
64
|
+
- **Resize**: Click on the element to select it. Pull the handles (blue squares) on the edges or corners to change the size.
|
|
65
|
+
- **Rotate**: When selecting an element, a circular handle will appear above it. Click and drag to rotate freely.
|
|
66
|
+
- **Delete**: Select an element and press the `Delete` key or use the context menu.
|
|
67
67
|
|
|
68
|
-
### Menu
|
|
68
|
+
### Context Menu and Styling
|
|
69
69
|
|
|
70
|
-
**
|
|
70
|
+
**Right-click** on any element to open the advanced options menu.
|
|
71
71
|
|
|
72
|
-
####
|
|
72
|
+
#### General Options (All Elements)
|
|
73
73
|
|
|
74
|
-
- **
|
|
75
|
-
- **
|
|
76
|
-
- **
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
- **
|
|
80
|
-
- **
|
|
81
|
-
-
|
|
82
|
-
-
|
|
74
|
+
- **Duplicate**: Creates an exact copy of the element next to the original.
|
|
75
|
+
- **Remove**: Deletes the element.
|
|
76
|
+
- **Layers**:
|
|
77
|
+
- _Bring to front_: Places the element above all others.
|
|
78
|
+
- _Send to back_: Places the element behind all others.
|
|
79
|
+
- **Background Color**: Changes the background color of the element (includes transparent).
|
|
80
|
+
- **Borders**:
|
|
81
|
+
- _Radius_: From 0px (square) to 50% (circle/oval).
|
|
82
|
+
- _Thickness_: Adds a solid border from 1px to 4px.
|
|
83
83
|
|
|
84
|
-
###
|
|
84
|
+
### Settings and Test Data
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
At the top of the left sidebar, the **Settings** button (gear icon) allows you to simulate how the layout will look with real data.
|
|
87
87
|
|
|
88
|
-
- **
|
|
89
|
-
-
|
|
90
|
-
-
|
|
91
|
-
- **
|
|
92
|
-
-
|
|
93
|
-
-
|
|
94
|
-
>
|
|
88
|
+
- **List Configuration Tab**:
|
|
89
|
+
- _Sort Property_: Defines which field will be used to sort the list (e.g., `price`, `name`).
|
|
90
|
+
- _Order_: Ascending or Descending.
|
|
91
|
+
- **Mock Data Tab**:
|
|
92
|
+
- _List Data_: A JSON array `[...]` to test list mode.
|
|
93
|
+
- _Single Data_: A JSON object `{...}` to test single mode.
|
|
94
|
+
> Edit these JSONs to see the layout react in real-time to your variables.
|
|
95
95
|
|
|
96
|
-
###
|
|
96
|
+
### Working with Text and Fonts
|
|
97
97
|
|
|
98
|
-
|
|
98
|
+
When right-clicking on a **Text** element:
|
|
99
99
|
|
|
100
|
-
- **
|
|
101
|
-
- **
|
|
102
|
-
-
|
|
103
|
-
- **
|
|
104
|
-
- **
|
|
105
|
-
- **
|
|
106
|
-
- **
|
|
100
|
+
- **Edit Text**: Opens a window to type content. This is where you insert variables (e.g., Customer Name) by clicking on the available buttons.
|
|
101
|
+
- **Font**: Select from various web-safe fonts (Arial, Helvetica, etc.) and popular Google Fonts (Roboto, Open Sans, Montserrat).
|
|
102
|
+
- _Import Google Font_: Allows you to type the name of any Google Fonts font (e.g., "Pacifico") and the editor will automatically load it.
|
|
103
|
+
- **Size**: Adjust from 12px to 64px.
|
|
104
|
+
- **Text Color**: Pre-defined color palette.
|
|
105
|
+
- **Weight**: Normal or Bold.
|
|
106
|
+
- **Alignment**: Left, Center, or Right.
|
|
107
107
|
|
|
108
|
-
###
|
|
108
|
+
### Working with Images
|
|
109
109
|
|
|
110
|
-
|
|
110
|
+
When right-clicking on an **Image** element:
|
|
111
111
|
|
|
112
|
-
- **
|
|
113
|
-
- _Upload_:
|
|
114
|
-
- _URL_:
|
|
115
|
-
- **
|
|
116
|
-
-
|
|
117
|
-
-
|
|
118
|
-
- **
|
|
112
|
+
- **Change Image**:
|
|
113
|
+
- _Upload_: Upload an image from your computer.
|
|
114
|
+
- _URL_: Paste a direct link to an image from the web.
|
|
115
|
+
- **Fit (Object Fit)**:
|
|
116
|
+
- _Fit (Contain)_: The entire image is shown inside the box, maintaining proportions (may leave white space).
|
|
117
|
+
- _Stretch (Fill)_: The image fills the entire box, potentially being cropped or distorted depending on the aspect ratio.
|
|
118
|
+
- **Bind Data**: Connects the image to a dynamic variable (e.g., Product Photo).
|
|
119
119
|
|
|
120
120
|
---
|
|
121
121
|
|
|
122
|
-
##
|
|
122
|
+
## Developer Guide (Integration)
|
|
123
123
|
|
|
124
|
-
###
|
|
124
|
+
### Initialization and Props
|
|
125
125
|
|
|
126
|
-
|
|
126
|
+
To start the editor, you must provide the `layout` configuration which dictates what data (variables) will be available to the user.
|
|
127
127
|
|
|
128
128
|
```tsx
|
|
129
129
|
import { EditorContent } from "@1urso/generic-editor";
|
|
130
130
|
|
|
131
131
|
const config = {
|
|
132
|
-
isList: false, //
|
|
133
|
-
name: "
|
|
132
|
+
isList: false, // Single mode (e.g., ID Card) or List (e.g., Catalog)
|
|
133
|
+
name: "Employee ID Card",
|
|
134
134
|
props: [
|
|
135
|
-
// Define
|
|
136
|
-
{ name: "
|
|
137
|
-
{ name: "
|
|
138
|
-
{ name: "
|
|
135
|
+
// Define the variables that will appear in the "Insert Variable" button
|
|
136
|
+
{ name: "Full Name", dataName: "nome" },
|
|
137
|
+
{ name: "Role", dataName: "cargo" },
|
|
138
|
+
{ name: "Profile Picture", dataName: "fotoUrl" },
|
|
139
139
|
],
|
|
140
140
|
};
|
|
141
141
|
|
|
@@ -145,44 +145,44 @@ function App() {
|
|
|
145
145
|
<EditorContent
|
|
146
146
|
layout={config}
|
|
147
147
|
onSave={(json) => saveToBackend(json)}
|
|
148
|
-
theme="light" //
|
|
148
|
+
theme="light" // Optional: 'light' or 'dark'
|
|
149
149
|
/>
|
|
150
150
|
</div>
|
|
151
151
|
);
|
|
152
152
|
}
|
|
153
153
|
```
|
|
154
154
|
|
|
155
|
-
### Data Binding
|
|
155
|
+
### Data Binding and Variables
|
|
156
156
|
|
|
157
|
-
|
|
157
|
+
The editor uses an interpolation system based on double braces `{{key}}`.
|
|
158
158
|
|
|
159
|
-
1. **
|
|
160
|
-
2. **
|
|
161
|
-
-
|
|
162
|
-
-
|
|
159
|
+
1. **Insertion**: The user does not need to type `{{...}}` manually. In the text edit window, they will see buttons (badges) with friendly names (e.g., "Full Name"). Clicking them inserts the `{{nome}}` code.
|
|
160
|
+
2. **Rendering**:
|
|
161
|
+
- If `data = { nome: "Maria" }`, the text "Hello {{nome}}" becomes "Hello Maria".
|
|
162
|
+
- If the variable does not exist in the data, the editor keeps the original text `{{nome}}` or displays empty, depending on the configuration.
|
|
163
163
|
|
|
164
|
-
###
|
|
164
|
+
### Modes: Single Item vs. List
|
|
165
165
|
|
|
166
|
-
|
|
166
|
+
The `isList` property drastically changes how the editor and HTML generator behave.
|
|
167
167
|
|
|
168
|
-
#### `isList: false` (
|
|
168
|
+
#### `isList: false` (Single Mode)
|
|
169
169
|
|
|
170
|
-
- **
|
|
171
|
-
- **
|
|
172
|
-
- **Canvas**:
|
|
170
|
+
- **Usage**: Certificates, ID Cards, Banners, Covers.
|
|
171
|
+
- **Data**: Expects a **Single Object** `{ nome: 'John', cargo: 'Dev' }`.
|
|
172
|
+
- **Canvas**: Shows a single page/art.
|
|
173
173
|
|
|
174
|
-
#### `isList: true` (
|
|
174
|
+
#### `isList: true` (List Mode)
|
|
175
175
|
|
|
176
|
-
- **
|
|
177
|
-
- **
|
|
176
|
+
- **Usage**: Price Lists, Catalogs, Shelf Labels, Reports.
|
|
177
|
+
- **Data**: Expects an **Array of Objects** `[{ nome: 'A' }, { nome: 'B' }]`.
|
|
178
178
|
- **Canvas**:
|
|
179
|
-
-
|
|
180
|
-
-
|
|
181
|
-
-
|
|
179
|
+
- The user designs the "Template Item".
|
|
180
|
+
- The editor repeats this model vertically for each item in the mock data array.
|
|
181
|
+
- Allows visualization of how the list behaves with multiple items.
|
|
182
182
|
|
|
183
|
-
###
|
|
183
|
+
### JSON Structure
|
|
184
184
|
|
|
185
|
-
|
|
185
|
+
The output of `onSave` is a JSON ready to be stored.
|
|
186
186
|
|
|
187
187
|
```json
|
|
188
188
|
{
|
|
@@ -191,7 +191,7 @@ O output do `onSave` é um JSON pronto para ser armazenado.
|
|
|
191
191
|
{
|
|
192
192
|
"id": "uuid-v4",
|
|
193
193
|
"type": "text", // 'text' | 'image' | 'box'
|
|
194
|
-
"content": "
|
|
194
|
+
"content": "Name: {{nome}}",
|
|
195
195
|
"x": 50,
|
|
196
196
|
"y": 100,
|
|
197
197
|
"width": 200,
|
|
@@ -203,7 +203,7 @@ O output do `onSave` é um JSON pronto para ser armazenado.
|
|
|
203
203
|
"fontFamily": "Roboto",
|
|
204
204
|
"textAlign": "center"
|
|
205
205
|
},
|
|
206
|
-
"dataBinding": "nome" //
|
|
206
|
+
"dataBinding": "nome" // Optional, used for direct binding
|
|
207
207
|
}
|
|
208
208
|
],
|
|
209
209
|
"listSettings": {
|
|
@@ -213,24 +213,24 @@ O output do `onSave` é um JSON pronto para ser armazenado.
|
|
|
213
213
|
}
|
|
214
214
|
```
|
|
215
215
|
|
|
216
|
-
###
|
|
216
|
+
### Generating HTML (Backend/Print)
|
|
217
217
|
|
|
218
|
-
|
|
218
|
+
To generate the final result (for printing, saving as PDF, or sending via email), use the `generateHTML` function. It runs in any JS environment (Node, Browser, etc.).
|
|
219
219
|
|
|
220
220
|
```typescript
|
|
221
221
|
import { generateHTML } from "@1urso/generic-editor";
|
|
222
222
|
|
|
223
|
-
// 1.
|
|
223
|
+
// 1. Load layout and data
|
|
224
224
|
const layout = JSON.parse(db.getLayout());
|
|
225
|
-
const dados = db.getFuncionarios(); // Array
|
|
225
|
+
const dados = db.getFuncionarios(); // Array or Object
|
|
226
226
|
|
|
227
|
-
// 2.
|
|
227
|
+
// 2. Generate HTML
|
|
228
228
|
const htmlString = generateHTML(layout.elements, dados, {
|
|
229
|
-
isList: layout.isList, //
|
|
229
|
+
isList: layout.isList, // Important to pass the correct mode
|
|
230
230
|
listSettings: layout.listSettings,
|
|
231
231
|
});
|
|
232
232
|
|
|
233
|
-
// 3.
|
|
233
|
+
// 3. Inject where needed
|
|
234
234
|
document.getElementById("preview").innerHTML = htmlString;
|
|
235
235
|
```
|
|
236
236
|
|
|
@@ -238,24 +238,24 @@ document.getElementById("preview").innerHTML = htmlString;
|
|
|
238
238
|
|
|
239
239
|
## API Reference
|
|
240
240
|
|
|
241
|
-
###
|
|
241
|
+
### Component `<EditorContent />`
|
|
242
242
|
|
|
243
|
-
|
|
|
244
|
-
| -------------- | ------------------------ |
|
|
245
|
-
| `layout` | `ILayout` | **
|
|
246
|
-
| `initialState` | `any` |
|
|
247
|
-
| `onSave` | `(json: string) => void` |
|
|
248
|
-
| `mockData` | `any[]` |
|
|
243
|
+
| Property | Type | Required | Default | Description |
|
|
244
|
+
| -------------- | ------------------------ | -------- | ------- | --------------------------------------------- |
|
|
245
|
+
| `layout` | `ILayout` | **Yes** | - | Initial configuration of variables and mode. |
|
|
246
|
+
| `initialState` | `any` | No | `null` | JSON state to load a saved layout. |
|
|
247
|
+
| `onSave` | `(json: string) => void` | No | - | Callback triggered when clicking Save button. |
|
|
248
|
+
| `mockData` | `any[]` | No | `[]` | Data for immediate preview during editing. |
|
|
249
249
|
|
|
250
|
-
###
|
|
250
|
+
### TypeScript Types
|
|
251
251
|
|
|
252
252
|
#### `ILayout`
|
|
253
253
|
|
|
254
254
|
```typescript
|
|
255
255
|
interface ILayout {
|
|
256
|
-
name: string; //
|
|
257
|
-
isList?: boolean; //
|
|
258
|
-
props: IProp[]; //
|
|
256
|
+
name: string; // Layout name (metadata)
|
|
257
|
+
isList?: boolean; // Defines default behavior (List or Single)
|
|
258
|
+
props: IProp[]; // List of available variables
|
|
259
259
|
}
|
|
260
260
|
```
|
|
261
261
|
|
|
@@ -263,16 +263,16 @@ interface ILayout {
|
|
|
263
263
|
|
|
264
264
|
```typescript
|
|
265
265
|
interface IProp {
|
|
266
|
-
name: string; //
|
|
267
|
-
dataName: string; //
|
|
266
|
+
name: string; // Visible label (e.g., "Product Price")
|
|
267
|
+
dataName: string; // Object key (e.g., "product_price")
|
|
268
268
|
}
|
|
269
269
|
```
|
|
270
270
|
|
|
271
271
|
#### `EditorProps`
|
|
272
272
|
|
|
273
|
-
| Prop |
|
|
274
|
-
| -------------- | ------------------------ |
|
|
275
|
-
| `layout` | `ILayout` |
|
|
276
|
-
| `onSave` | `(json: string) => void` |
|
|
277
|
-
| `initialState` | `any` |
|
|
278
|
-
| `theme` | `'light' \| 'dark'` |
|
|
273
|
+
| Prop | Type | Required | Description |
|
|
274
|
+
| -------------- | ------------------------ | -------- | ------------------------------------- |
|
|
275
|
+
| `layout` | `ILayout` | Yes | Initial configuration and metadata. |
|
|
276
|
+
| `onSave` | `(json: string) => void` | No | Callback triggered on save. |
|
|
277
|
+
| `initialState` | `any` | No | Previously saved state (parsed JSON). |
|
|
278
|
+
| `theme` | `'light' \| 'dark'` | No | Interface theme (default: `'light'`). |
|