Pular para o conteúdo principal

@astradevio/modelarium-editor

npm types

🌟 Modelarium Editor — Visão Geral​

Modelarium Editor é um construtor de formulários moderno e extensível com funcionalidade arrastar e soltar, escrito em TypeScript pela AstraDEV. Oferece uma experiência intuitiva (arrastar-e-soltar e clique-para-adicionar), uma API TypeScript limpa, temas personalizáveis, e importação/exportação JSON para armazenar e reutilizar formulários.

Aviso Esta é uma versão MVP em estágio alfa destinada para avaliação. Use com cautela em produção.

Contribuições são bem-vindas: por favor, abra issues em https://github.com/astradevio/modelarium-editor-dist/issues.

Principais Funcionalidades​

  • 🎯 Interface Arrastar e Soltar — Construa formulários visualmente arrastando elementos para o canvas.
  • 📋 Formulários Baseados em Schema (Importar/Exportar) — Salve, versione e reutilize formulários via JSON para integração com backend.
  • 🧩 Sistema de Plugins Extensível — Adicione elementos customizados e estenda funcionalidades sem tocar no núcleo.
  • ⚡ API TypeScript Completa — Tipagem forte, IntelliSense e autocompletar.
  • 🔌 Agnóstico de Framework — Funciona com React, Vue, Angular ou JavaScript Vanilla.
  • ⚙️ Propriedades Configuráveis — Regras de validação, campos obrigatórios, min/max, atributos customizados.
  • 🔄 Conversão Bidirecional — Importe formulários existentes, edite visualmente e exporte de volta para JSON/HTML.
  • 📚 Documentação — Docs TypeScript inline, guias de uso e exemplos (em desenvolvimento).

Instalação​

Instale via npm:

npm install @astradevio/modelarium-editor

Ou com seu gerenciador preferido:

# pnpm
pnpm add @astradevio/modelarium-editor

# yarn
yarn add @astradevio/modelarium-editor

# bun
bun add @astradevio/modelarium-editor

Requisitos: Node 18+ e TypeScript 5+ (recomendado).

Início Rápido​

ESM​

import ModelariumEditor from '@astradevio/modelarium-editor';
import '@astradevio/modelarium-editor/style.css';

const editor = new ModelariumEditor({
  // ...opções
});

Tipos TypeScript (opcional)

import type { ModelariumEditorOptions } from '@astradevio/modelarium-editor';

CommonJS​

const ModelariumEditor = require('@astradevio/modelarium-editor').default;
require('@astradevio/modelarium-editor/style.css');

const editor = new ModelariumEditor({ /* ... */ });

CDN (jsDelivr / unpkg)​

Use a build UMD diretamente no navegador.

jsDelivr​

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@astradevio/modelarium-editor@latest/dist/style.css" />
<script src="https://cdn.jsdelivr.net/npm/@astradevio/modelarium-editor@latest/dist/modelarium-editor.umd.min.js"></script>
<script>
  const editor = new window.ModelariumEditor({ /* opções */ });
</script>

unpkg​

<link rel="stylesheet" href="https://unpkg.com/@astradevio/modelarium-editor@latest/dist/style.css" />
<script src="https://unpkg.com/@astradevio/modelarium-editor@latest/dist/modelarium-editor.umd.min.js"></script>
<script>
  const editor = new window.ModelariumEditor({ /* opções */ });
</script>

O style.css distribuído não é minificado para facilitar a personalização.

Estilização CSS​

O Modelarium Editor vem com um arquivo CSS altamente otimizado (style.css) que fornece estilização abrangente para todos os componentes do editor.

Variáveis CSS​

Todas as variáveis CSS estão organizadas no início do arquivo para fácil personalização. Todos os estilos usam o prefixo modelarium- para evitar conflitos com seus estilos existentes:

/* Variáveis principais para tematização fácil */
--modelarium-primary-color: #007bff;
--modelarium-background-color: #ffffff;
--modelarium-text-color: #333333;
--modelarium-border-color: #e0e0e0;
/* ... e muitas outras */

Sistema de Temas​

O CSS inclui um sistema automático de temas que se adapta às preferências do sistema do usuário:

  • Modo Claro: Ativado por padrão ou quando prefers-color-scheme: light
  • Modo Escuro: Ativado automaticamente quando prefers-color-scheme: dark

Você pode personalizar temas modificando as variáveis CSS dentro das respectivas media queries.

Exemplos​

Exemplos prontos para uso estão disponíveis no diretório public/examples/:

Exemplos Disponíveis​

  1. js.html - Exemplo de Uso UMD/Global

    • Demonstra carregamento do Modelarium Editor via tags <script>
    • Mostra padrão de uso de variável global
    • Perfeito para páginas web tradicionais ou integração via CDN

  2. module.html - Exemplo de Uso ES Module

    • Demonstra importações modernas de ES module
    • Mostra como usar com type="module"
    • Ideal para aplicações web modernas

API Pública​

Classe ModelariumEditor​

A classe principal para criar e gerenciar o editor visual.

Construtor

new ModelariumEditor( string | HTMLElement, ?options: ModelariumEditorOptions)

Principais Opções de Inicialização

export interface ModelariumEditorOptions {
    debug?:          boolean;  // debug: true ou false
    toolbox?:        string;   // tipo de toolbox, padrão vai para form
    toolboxJSON?:    string;   // JSON do toolbox
    modelariumJSON?: string;  // JSON do modelarium
}

Uso Básico

import ModelariumEditor from '@astradevio/modelarium-editor';

const editor = new ModelariumEditor('editor-container', {
  theme: 'auto',
  debug: true
});

Documentação Completa​

Para documentação completa da API, incluindo todos os métodos, eventos e opções avançadas de configuração, visite:

📚 docs.astradev.io/modelarium

A documentação completa inclui:

  • Referência completa de métodos
  • Documentação do sistema de eventos
  • Opções avançadas de configuração
  • Exemplos de integração
  • Melhores práticas e tutoriais

Issues​

Distribuições​

📄 Licença​

Este pacote de distribuição está disponível sob a Licença MIT.
Licenciamento proprietário — incluindo acesso ao código-fonte e serviços profissionais — está disponível mediante solicitação.

🏢 Sobre a AstraDEV​

AstraDEV (Astra Empreendedorismo Sistemas e Treinamentos Ltda.) é uma empresa de tecnologia focada em soluções de software, treinamentos e inovação para acelerar o desenvolvimento de produtos digitais.

📝 Este README também está disponível em English.