@1urso/generic-editor 0.1.9 → 0.1.12

package/README.md

@@ -1,141 +1,140 @@
 # Generic Editor
 
-Uma biblioteca React poderosa, agnóstica de framework e **100% personalizável** para criação de layouts dinâmicos, geração de templates e edição visual. Projetada para ser o motor de design dentro da sua aplicação (Web, Electron, Tauri, Next.js, etc.).
+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.).
 
 ---
 
-## 📚 Índice
-
-1. [Instalação e Configuração](#instalação-e-configuração)
-2. [Guia do Usuário (Interface Visual)](#guia-do-usuário-interface-visual)
-   - [Manipulação Básica](#manipulação-básica)
-   - [Menu de Contexto e Estilização](#menu-de-contexto-e-estilização)
-   - [Trabalhando com Textos e Fontes](#trabalhando-com-textos-e-fontes)
-   - [Trabalhando com Imagens](#trabalhando-com-imagens)
-3. [Guia do Desenvolvedor (Integração)](#guia-do-desenvolvedor-integração)
-   - [Inicialização e Props](#inicialização-e-props)
-   - [Data Binding e Variáveis](#data-binding-e-variáveis)
-   - [Modos: Item Único vs. Lista](#modos-item-único-vs-lista)
-   - [Estrutura do JSON](#estrutura-do-json)
-   - [Gerando HTML (Backend/Print)](#gerando-html-backendprint)
+## 📚 Table of Contents
+
+1. [Installation and Configuration](#installation-and-configuration)
+2. [User Guide (Visual Interface)](#user-guide-visual-interface)
+   - [Basic Manipulation](#basic-manipulation)
+   - [Context Menu and Styling](#context-menu-and-styling)
+   - [Working with Text and Fonts](#working-with-text-and-fonts)
+   - [Working with Images](#working-with-images)
+3. [Developer Guide (Integration)](#developer-guide-integration)
+   - [Initialization and Props](#initialization-and-props)
+   - [Data Binding and Variables](#data-binding-and-variables)
+   - [Modes: Single Item vs. List](#modes-single-item-vs-list)
+   - [JSON Structure](#json-structure)
+   - [Generating HTML (Backend/Print)](#generating-html-backendprint)
 4. [API Reference](#api-reference)
 
 ---
 
-## Instalação e Configuração
+## Installation and Configuration
 
-### 1. Instale o pacote
+### 1. Install the package
 
 ```bash
 npm install @1urso/generic-editor
-# ou
+# or
 yarn add @1urso/generic-editor
 ```
 
-### 2. Instale as dependências (Peer Dependencies)
+### 2. Install Peer Dependencies
 
-O editor utiliza bibliotecas modernas para garantir performance e acessibilidade. Você precisa instalá-las no seu projeto:
+The editor uses modern libraries to ensure performance and accessibility. You need to install them in your project:
 
 ```bash
 npm install @radix-ui/themes @radix-ui/react-icons react-resizable-panels re-resizable framer-motion @dnd-kit/core
 ```
 
-### 3. Importe os Estilos
+### 3. Import Styles
 
-No arquivo de entrada da sua aplicação (ex: `main.tsx`, `App.tsx` ou `layout.tsx` no Next.js), importe o CSS do editor (obrigatório para o menu de contexto) e do Radix UI:
+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:
 
 ```tsx
-import "@1urso/generic-editor/dist/generic-editor.css"; // Essencial para o funcionamento do editor
+import "@1urso/generic-editor/dist/generic-editor.css"; // Essential for the editor to work
 import "@radix-ui/themes/styles.css";
 ```
 
 ---
 
-## Guia do Usuário (Interface Visual)
+## User Guide (Visual Interface)
 
-Esta seção descreve as funcionalidades disponíveis para o **usuário final** que utilizará o editor na sua plataforma.
+This section describes the features available to the **end user** who will use the editor on your platform.
 
-### Manipulação Básica
+### Basic Manipulation
 
-O editor oferece uma experiência similar a ferramentas de design como Canva ou Figma:
+The editor offers an experience similar to design tools like Canva or Figma:
 
-- **Adicionar Elementos**: Utilize a barra lateral (ou botões que você implementar) para arrastar ou clicar e adicionar Textos, Imagens ou Caixas.
-- **Mover**: Clique e arraste qualquer elemento para reposicioná-lo.
-- **Redimensionar**: Clique no elemento para selecioná-lo. Puxe as alças (quadrados azuis) nas bordas ou cantos para alterar o tamanho.
-- **Rotacionar**: Ao selecionar um elemento, uma alça circular aparecerá acima dele. Clique e arraste para girar livremente.
-- **Deletar**: Selecione um elemento e pressione a tecla `Delete` ou use o menu de contexto.
+- **Add Elements**: Use the sidebar (or buttons you implement) to drag or click and add Texts, Images, or Boxes.
+- **Move**: Click and drag any element to reposition it.
+- **Resize**: Click on the element to select it. Pull the handles (blue squares) on the edges or corners to change the size.
+- **Rotate**: When selecting an element, a circular handle will appear above it. Click and drag to rotate freely.
+- **Delete**: Select an element and press the `Delete` key or use the context menu.
 
-### Menu de Contexto e Estilização
+### Context Menu and Styling
 
-**Clique com o botão direito** em qualquer elemento para abrir o menu de opções avançadas.
+**Right-click** on any element to open the advanced options menu.
 
-#### Opções Gerais (Todos os Elementos)
+#### General Options (All Elements)
 
-- **Duplicar**: Cria uma cópia exata do elemento próximo ao original.
-- **Remover**: Exclui o elemento.
-- **Camadas**:
-  - _Trazer para frente_: Coloca o elemento sobre todos os outros.
-  - _Enviar para trás_: Coloca o elemento atrás de todos.
-- **Cor de Fundo**: Altera a cor de fundo do elemento (inclui transparente).
-- **Bordas**:
-  - _Arredondamento_: De 0px (quadrado) até 50% (círculo/oval).
-  - _Espessura_: Adiciona borda sólida de 1px a 4px.
+- **Duplicate**: Creates an exact copy of the element next to the original.
+- **Remove**: Deletes the element.
+- **Layers**:
+  - _Bring to front_: Places the element above all others.
+  - _Send to back_: Places the element behind all others.
+- **Background Color**: Changes the background color of the element (includes transparent).
+- **Borders**:
+  - _Radius_: From 0px (square) to 50% (circle/oval).
+  - _Thickness_: Adds a solid border from 1px to 4px.
 
-### Configurações e Dados de Teste
+### Settings and Test Data
 
-No topo da barra lateral esquerda, o botão **Configurações** (ícone de engrenagem) permite simular como o layout ficará com dados reais.
+At the top of the left sidebar, the **Settings** button (gear icon) allows you to simulate how the layout will look with real data.
 
-- **Aba Configuração da Lista**:
-  - _Propriedade para Ordenar_: Define qual campo será usado para ordenar a lista (ex: `preco`, `nome`).
-  - _Ordem_: Crescente ou Decrescente.
-- **Aba Dados Mockados**:
-  - _Dados para Lista_: Um array JSON `[...]` para testar o modo lista.
-  - _Dados Únicos_: Um objeto JSON `{...}` para testar o modo único.
-    > Edite esses JSONs para ver o layout reagir em tempo real às suas variáveis.
+- **List Configuration Tab**:
+  - _Sort Property_: Defines which field will be used to sort the list (e.g., `price`, `name`).
+  - _Order_: Ascending or Descending.
+  - _Newest Position_: Defines where the newest item appears ('top' or 'bottom').
+  - _Scroll Behavior_: Defines the scroll direction ('down' - default, or 'up' - chat-like).
 
-### Trabalhando com Textos e Fontes
+### Working with Text and Fonts
 
-Ao clicar com o botão direito em um elemento de **Texto**:
+When right-clicking on a **Text** element:
 
-- **Editar Texto**: Abre uma janela para digitar o conteúdo. É aqui que você insere variáveis (ex: Nome do Cliente) clicando nos botões disponíveis.
-- **Fonte**: Selecione entre diversas fontes seguras para web (Arial, Helvetica, etc) e Google Fonts populares (Roboto, Open Sans, Montserrat).
-  - _Importar Google Font_: Permite digitar o nome de qualquer fonte do Google Fonts (ex: "Pacifico") e o editor a carregará automaticamente.
-- **Tamanho**: Ajuste de 12px a 64px.
-- **Cor do Texto**: Paleta de cores pré-definida.
-- **Peso**: Normal ou Negrito.
-- **Alinhamento**: Esquerda, Centro ou Direita.
+- **Edit Text**: Opens a window to type content. This is where you insert variables (e.g., Customer Name) by clicking on the available buttons.
+- **Font**: Select from various web-safe fonts (Arial, Helvetica, etc.) and popular Google Fonts (Roboto, Open Sans, Montserrat).
+  - _Import Google Font_: Allows you to type the name of any Google Fonts font (e.g., "Pacifico") and the editor will automatically load it.
+- **Size**: Adjust from 12px to 64px.
+- **Text Color**: Pre-defined color palette.
+- **Weight**: Normal or Bold.
+- **Alignment**: Left, Center, or Right.
+- **Vertical Alignment**: Top, Center, or Bottom.
 
-### Trabalhando com Imagens
+### Working with Images
 
-Ao clicar com o botão direito em um elemento de **Imagem**:
+When right-clicking on an **Image** element:
 
-- **Alterar Imagem**:
-  - _Upload_: Carregue uma imagem do seu computador.
-  - _URL_: Cole um link direto para uma imagem da web.
-- **Ajuste (Object Fit)**:
-  - _Ajustar (Contain)_: A imagem inteira é mostrada dentro da caixa, mantendo a proporção (pode sobrar espaço em branco).
-  - _Esticar (Fill)_: A imagem preenche toda a caixa, podendo ser cortada ou distorcida dependendo da proporção.
-- **Vincular Dados**: Conecta a imagem a uma variável dinâmica (ex: Foto do Produto).
+- **Change Image**:
+  - _Upload_: Upload an image from your computer.
+  - _URL_: Paste a direct link to an image from the web.
+- **Fit (Object Fit)**:
+  - _Fit (Contain)_: The entire image is shown inside the box, maintaining proportions (may leave white space).
+  - _Stretch (Fill)_: The image fills the entire box, potentially being cropped or distorted depending on the aspect ratio.
+- **Bind Data**: Connects the image to a dynamic variable (e.g., Product Photo).
 
 ---
 
-## Guia do Desenvolvedor (Integração)
+## Developer Guide (Integration)
 
-### Inicialização e Props
+### Initialization and Props
 
-Para iniciar o editor, você deve fornecer a configuração de `layout` que dita quais dados (variáveis) estarão disponíveis para o usuário.
+To start the editor, you must provide the `layout` configuration which dictates what data (variables) will be available to the user.
 
 ```tsx
 import { EditorContent } from "@1urso/generic-editor";
 
 const config = {
-  isList: false, // Modo único (ex: Crachá) ou Lista (ex: Catálogo)
-  name: "Crachá de Funcionário",
+  isList: false, // Single mode (e.g., ID Card) or List (e.g., Catalog)
+  name: "Employee ID Card",
   props: [
-    // Define as variáveis que aparecerão no botão "Inserir Variável"
-    { name: "Nome Completo", dataName: "nome" },
-    { name: "Cargo", dataName: "cargo" },
-    { name: "Foto de Perfil", dataName: "fotoUrl" },
+    // Define the variables that will appear in the "Insert Variable" button
+    { name: "Full Name", dataName: "nome" },
+    { name: "Role", dataName: "cargo" },
+    { name: "Profile Picture", dataName: "fotoUrl" },
   ],
 };
 
@@ -145,44 +144,45 @@ function App() {
       <EditorContent
         layout={config}
         onSave={(json) => saveToBackend(json)}
-        theme="light" // Opcional: 'light' ou 'dark'
+        theme="light" // Optional: 'light' or 'dark'
       />
     </div>
   );
 }
 ```
 
-### Data Binding e Variáveis
+### Data Binding and Variables
 
-O editor utiliza um sistema de interpolação baseado em chaves duplas `{{chave}}`.
+The editor uses an interpolation system based on double braces `{{key}}`.
 
-1.  **Inserção**: O usuário não precisa digitar `{{...}}` manualmente. Na janela de edição de texto, ele verá botões (badges) com os nomes amigáveis (ex: "Nome Completo"). Ao clicar, o código `{{nome}}` é inserido.
-2.  **Renderização**:
-    - Se `data = { nome: "Maria" }`, o texto "Olá {{nome}}" vira "Olá Maria".
-    - Se a variável não existir nos dados, o editor mantém o texto original `{{nome}}` ou exibe vazio, dependendo da configuração.
+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.
+2.  **Rendering**:
+    - If `data = { nome: "Maria" }`, the text "Hello {{nome}}" becomes "Hello Maria".
+    - If the variable does not exist in the data, the editor keeps the original text `{{nome}}` or displays empty, depending on the configuration.
 
-### Modos: Item Único vs. Lista
+### Modes: Single Item vs. List
 
-A propriedade `isList` muda drasticamente como o editor e o gerador de HTML se comportam.
+The `isList` property drastically changes how the editor and HTML generator behave.
 
-#### `isList: false` (Modo Único)
+#### `isList: false` (Single Mode)
 
-- **Uso**: Certificados, Crachás, Banners, Capas.
-- **Dados**: Espera um **Objeto Único** `{ nome: 'João', cargo: 'Dev' }`.
-- **Canvas**: Mostra uma única página/arte.
+- **Usage**: Certificates, ID Cards, Banners, Covers.
+- **Data**: Expects a **Single Object** `{ nome: 'John', cargo: 'Dev' }`.
+- **Canvas**: Shows a single page/art.
 
-#### `isList: true` (Modo Lista)
+#### `isList: true` (List Mode)
 
-- **Uso**: Listas de Preços, Catálogos, Etiquetas de Gôndola, Relatórios.
-- **Dados**: Espera um **Array de Objetos** `[{ nome: 'A' }, { nome: 'B' }]`.
+- **Usage**: Price Lists, Catalogs, Shelf Labels, Reports.
+- **Data**: Expects an **Array of Objects** `[{ nome: 'A' }, { nome: 'B' }]`.
 - **Canvas**:
-  - O usuário desenha o "Item Modelo" (Template).
-  - O editor repete esse modelo verticalmente para cada item do array de dados mockados.
-  - Permite visualizar como a lista se comporta com múltiplos itens.
+  - The user designs the "Template Item".
+  - The editor repeats this model vertically for each item in the mock data array.
+  - Allows visualization of how the list behaves with multiple items.
+  - **Height Limit**: Elements are constrained within the defined item height (canvas height).
 
-### Estrutura do JSON
+### JSON Structure
 
-O output do `onSave` é um JSON pronto para ser armazenado.
+The output of `onSave` is a JSON ready to be stored.
 
 ```json
 {
@@ -191,7 +191,7 @@ O output do `onSave` é um JSON pronto para ser armazenado.
     {
       "id": "uuid-v4",
       "type": "text", // 'text' | 'image' | 'box'
-      "content": "Nome: {{nome}}",
+      "content": "Name: {{nome}}",
       "x": 50,
       "y": 100,
       "width": 200,
@@ -203,34 +203,37 @@ O output do `onSave` é um JSON pronto para ser armazenado.
         "fontFamily": "Roboto",
         "textAlign": "center"
       },
-      "dataBinding": "nome" // Opcional, usado para vínculo direto
+      "dataBinding": "nome" // Optional, used for direct binding
     }
   ],
   "listSettings": {
     "sortProp": "nome",
-    "sortOrder": "asc"
+    "sortOrder": "asc",
+    "newestPosition": "bottom",
+    "scrollDirection": "down"
   }
 }
 ```
 
-### Gerando HTML (Backend/Print)
+### Generating HTML (Backend/Print)
 
-Para gerar o resultado final (para imprimir, salvar PDF ou enviar por email), use a função `generateHTML`. Ela roda em qualquer ambiente JS (Node, Browser, etc).
+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.).
 
 ```typescript
 import { generateHTML } from "@1urso/generic-editor";
 
-// 1. Carregue o layout e os dados
+// 1. Load layout and data
 const layout = JSON.parse(db.getLayout());
-const dados = db.getFuncionarios(); // Array ou Objeto
+const dados = db.getFuncionarios(); // Array or Object
 
-// 2. Gere o HTML
+// 2. Generate HTML
 const htmlString = generateHTML(layout.elements, dados, {
-  isList: layout.isList, // Importante passar o modo correto
+  isList: layout.isList, // Important to pass the correct mode
   listSettings: layout.listSettings,
+  canvasHeight: layout.canvasHeight, // Optional: Force item height
 });
 
-// 3. Injete onde precisar
+// 3. Inject where needed
 document.getElementById("preview").innerHTML = htmlString;
 ```
 
@@ -238,24 +241,24 @@ document.getElementById("preview").innerHTML = htmlString;
 
 ## API Reference
 
-### Componente `<EditorContent />`
+### Component `<EditorContent />`
 
-| Propriedade    | Tipo                     | Obrigatório | Padrão | Descrição                                     |
-| -------------- | ------------------------ | ----------- | ------ | --------------------------------------------- |
-| `layout`       | `ILayout`                | **Sim**     | -      | Configuração inicial das variáveis e modo.    |
-| `initialState` | `any`                    | Não         | `null` | Estado JSON para carregar um layout salvo.    |
-| `onSave`       | `(json: string) => void` | Não         | -      | Callback acionado ao clicar no botão Salvar.  |
-| `mockData`     | `any[]`                  | Não         | `[]`   | Dados para preview imediato durante a edição. |
+| Property       | Type                     | Required | Default | Description                                   |
+| -------------- | ------------------------ | -------- | ------- | --------------------------------------------- |
+| `layout`       | `ILayout`                | **Yes**  | -       | Initial configuration of variables and mode.  |
+| `initialState` | `any`                    | No       | `null`  | JSON state to load a saved layout.            |
+| `onSave`       | `(json: string) => void` | No       | -       | Callback triggered when clicking Save button. |
+| `mockData`     | `any[]`                  | No       | `[]`    | Data for immediate preview during editing.    |
 
-### Tipos TypeScript
+### TypeScript Types
 
 #### `ILayout`
 
 ```typescript
 interface ILayout {
-  name: string; // Nome do layout (metadado)
-  isList?: boolean; // Define o comportamento padrão (Lista ou Único)
-  props: IProp[]; // Lista de variáveis disponíveis
+  name: string; // Layout name (metadata)
+  isList?: boolean; // Defines default behavior (List or Single)
+  props: IProp[]; // List of available variables
 }
 ```
 
@@ -263,16 +266,16 @@ interface ILayout {
 
 ```typescript
 interface IProp {
-  name: string; // Rótulo visível (ex: "Preço do Produto")
-  dataName: string; // Chave do objeto (ex: "product_price")
+  name: string; // Visible label (e.g., "Product Price")
+  dataName: string; // Object key (e.g., "product_price")
 }
 ```
 
 #### `EditorProps`
 
-| Prop           | Tipo                     | Obrigatório | Descrição                                   |
-| -------------- | ------------------------ | ----------- | ------------------------------------------- |
-| `layout`       | `ILayout`                | Sim         | Configuração inicial e metadados.           |
-| `onSave`       | `(json: string) => void` | Não         | Callback disparado ao salvar.               |
-| `initialState` | `any`                    | Não         | Estado salvo anteriormente (JSON parseado). |
-| `theme`        | `'light' \| 'dark'`      | Não         | Tema da interface (padrão: `'light'`).      |
+| Prop           | Type                     | Required | Description                           |
+| -------------- | ------------------------ | -------- | ------------------------------------- |
+| `layout`       | `ILayout`                | Yes      | Initial configuration and metadata.   |
+| `onSave`       | `(json: string) => void` | No       | Callback triggered on save.           |
+| `initialState` | `any`                    | No       | Previously saved state (parsed JSON). |
+| `theme`        | `'light' \| 'dark'`      | No       | Interface theme (default: `'light'`). |

package/dist/editor/context.d.ts

@@ -14,6 +14,8 @@ export interface IElement {
 export interface IListSettings {
     sortProp?: string;
     sortOrder: 'asc' | 'desc';
+    newestPosition?: 'top' | 'bottom';
+    scrollDirection?: 'up' | 'down';
 }
 export interface IProp {
     name: string;
@@ -26,6 +28,7 @@ interface IEditorState {
     mockData: any[];
     singleMockData: Record<string, any>;
     listSettings: IListSettings;
+    canvasHeight?: number;
     availableProps: IProp[];
     availableFonts: string[];
     theme: 'light' | 'dark';
@@ -39,6 +42,7 @@ interface IEditorContext {
     updateElement: (id: string, updates: Partial<IElement>) => void;
     setMockData: (data: any[], singleData: Record<string, any>) => void;
     updateListSettings: (settings: Partial<IListSettings>) => void;
+    setCanvasHeight: (height: number) => void;
     loadState: (savedState: Partial<IEditorState>) => void;
 }
 export declare const EditorProvider: React.FC<{

package/dist/editor/utils/htmlGenerator.d.ts

@@ -2,6 +2,7 @@ import { IElement, IListSettings } from '../context';
 interface RenderOptions {
     isList?: boolean;
     listSettings?: IListSettings;
+    canvasHeight?: number;
 }
 export declare const generateHTML: (elements: IElement[], data: any, options?: RenderOptions) => string;
 export declare const getRendererCode: () => string;