LithosGrid 🚀 (v0.1.0)

A documentação definitiva e completa da LithosGrid: a biblioteca de DataGrid de ultra-performance construída para Angular 18+. Desenhada para o processamento e a renderização em tempo real de milhões de registros de dados no navegador, garantindo animações a 60 FPS ininterruptos.

📖 Tabela de Conteúdos

1. O que torna a LithosGrid diferente?
2. Instalação e Setup Zero-Config
3. Uso Rápido (Quickstart)
4. A Interface GridSchema e Configuração de Colunas
5. Motor de Validação (JSON)
6. Interações e Funcionalidades Avançadas
7. Arquitetura e Performance

1. O que torna a LithosGrid diferente?

Bibliotecas tradicionais de UI manipulam ordenação e buscas usando JavaScript na Main Thread, o que bloqueia a interface quando se tenta lidar com matrizes de milhares de linhas. A LithosGrid adota uma Arquitetura Web Híbrida:

• C++ e WebAssembly (WASM): As pesadas lógicas de busca Full-Text (Regex/Contains), ordenações complexas e paginação ocorrem diretamente na Memória Bruta instanciada num motor WebAssembly nativo de alta velocidade.
• Web Workers Isolados: O Angular nunca entra em contato com o loop de dados pesados. A comunicação é feita por PostMessage, garantindo fluidez e tela destravada.
• DOM Recycling Extreme (Virtual Scroll): Ao invés de prender o navegador injetando milhões de tags <tr>/<td>, nós renderizamos um Virtual Content contendo exatamente o número de células suportado pela altura de sua tela (cerca de ~50 instâncias). A rolagem desloca os dados internamente sob demanda (transform: translateY).

2. Instalação e Setup Zero-Config

Para instalar, não é necessário copiar pastas de configuração wasm pro seu projeto, já que na v0.1.0 nossa grid injeta o WASM magicamente via Base64.

npm install lithos-grid

Como o componente foi construído de forma Standalone, basta importar e usar em qualquer Component.

3. Uso Rápido (Quickstart)

Importe o componente e o tipo no seu arquivo TypeScript:

import { Component } from '@angular/core';
import { DgpGridComponent, GridSchema } from 'lithos-grid';

@Component({
  selector: 'app-users-view',
  standalone: true,
  imports: [DgpGridComponent],
  template: `
    <!-- Sempre envolva a grid em um contêiner com altura/largura definida -->
    <div style="width: 100%; height: 80vh;">
      <dgp-grid [schema]="mySchema" [data]="myHugeArray"></dgp-grid>
    </div>
  `
})
export class UsersViewComponent {
  // Configuração puramente via JSON Schema
  mySchema: GridSchema = {
    fields: [
      { name: 'id', type: 'number', label: 'Cód.', width: 80, disabled: true },
      { name: 'fullName', type: 'string', label: 'Nome Completo', width: 250 },
      { name: 'wallet', type: 'currency', label: 'Saldo', currency: 'BRL', locale: 'pt-BR' }
    ]
  };

  // Seus dados do Back-end. Pode injetar 50.000 de uma vez.
  myHugeArray = [
    { id: 1, fullName: 'João da Silva', wallet: 4500.50 },
    // ...
  ];
}

4. A Interface GridSchema e Configuração de Colunas

A arquitetura da Grid é orientada a Schema-Driven. Isso quer dizer que o seu back-end pode ditar inteiramente o comportamento visual, largura e regras de validação enviando a configuração como JSON.

Estrutura Base

interface GridSchema {
  fields: FieldDef[];
}

Propriedades do FieldDef (Configuração de cada Coluna)

| Propriedade | Tipo | O que faz | |-----------------|-----------|-----------| | name | string | Identificador único e chave da propriedade de dado (row[name]). | | type | string | Pode ser: 'string', 'number', 'currency', 'date', 'boolean', 'email', 'password', 'url', 'multi-select', 'custom'. | | label | string | Título legível renderizado no cabeçalho. | | width | number | (Opcional) Largura inicial da coluna em pixels. | | disabled | boolean | (Opcional) Impede a Edição Inline e bloqueia interações. | | readonly | boolean | (Opcional) Exibe dados mas previne modificações. | | currency | string | Ex: 'BRL', 'USD'. Define o símbolo monetário se o type for 'currency'. | | locale | string | Ex: 'pt-BR'. Define a formatação numérica do dinheiro/datas. | | reference | Object | Define dados de relacionamento relacional (Badges / Multi-selects). Veja abaixo. | | validations | Object | Regras para a validação na Edição Inline. Veja a Seção 5. |

Lidando com Tipos Complexos (multi-select)

A Grid é capaz de desenhar Badges nativos coloridos para campos que referenciam chaves estrangeiras (fk), como tags, status ou categorias.

// Exemplo de Field Schema
{ 
  name: 'status', 
  type: 'multi-select', 
  label: 'Tags / Status', 
  reference: { 
    table: 'tags_db', 
    displayField: 'name', // Propriedade que será mostrada no balão
    colorField: 'color'   // Hex color base (Ex: '#ff0000') para a Badge
  }
}

// Os dados injetados na Grid devem refletir a estrutura
{
  status: [
    { id: 1, name: 'Premium', color: '#818cf8' },
    { id: 2, name: 'Inadimplente', color: '#fb7185' }
  ]
}

5. Motor de Validação (JSON)

A edição em tela está protegida pelo motor embutido. Na propriedade validations dentro do seu FieldDef, você pode acoplar Expressões Regulares de forma puramente configurável.

{
  "name": "email",
  "type": "email",
  "label": "E-mail",
  "validations": {
    "required": true,
    "minLength": 5,
    "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$",
    "message": "Ops! E-mail inválido."
  }
}

Mecânica de Erro: Ao tentar dar duplo clique e salvar (Enter) um valor que fura uma dessas regras, a própria Grid pinta o input de vermelho, e sobe uma caixa flutuante informando o erro, abortando imediatamente o tráfego da informação em direção ao Web Worker/Servidor.

6. Interações e Funcionalidades Avançadas

A biblioteca traz funcionalidades comparadas a softwares de planilha robustos.

• Edição Inline (double-click): Dê um duplo-clique sobre a área de texto de qualquer célula não desabilitada para virar um Input nativo (Suporta inputs especiais de password). Aperte Enter para commitar a mudança, ou Esc para ignorar e fechar.
• Redimensionamento Rápido (Resize): No cabeçalho, pare o ponteiro sobre as extremidades direitas das colunas. Aparecerão guias interativas permitindo clicar e arrastar, esticando ou encurtando aquela coluna.
• Reordenação Nativa (Drag & Drop): Quer a coluna "Salário" na frente do "ID"? Clique em cima do cabeçalho Salário, segure e arraste-o para sua nova posição. Toda a árvore de dados será renderizada no mesmo instante e de forma reativa.
• Fill Handle (A mágica do Excel): Edite dados em massa! Ao clicar uma única vez em uma célula, perceba um ponto azul minúsculo no rodapé direito (Fill Handle). Clique neste ponto e arraste-o para baixo na mesma coluna: ao soltar o mouse, a Grid aplicará aquele valor copiado contra todas as células preenchidas pelo seu arrasto. Se apenas um alvo falhar na validação, o lote inteiro aborta (All-or-Nothing batch).

7. Arquitetura e Performance

Sempre que instanciar o DgpGridComponent, isto é o que ocorre nos bastidores (o seu "Wow effect"):

1. O Angular levanta de forma assíncrona o Web Worker e inicia a ponte.
2. O Web Worker carrega localmente o motor WASM.
3. Os dados brutos injetados via @Input() data são imediatamente esvaziados da memória RAM do Angular e transferidos (postMessage) para a Struct/Vectors C++ no WASM.
4. Qualquer tentativa de digitar no Campo de Busca (Search Bar) fará com que o Angular diga ao Worker qual é a query.
5. O filtro, Full-Text, é processado a baixíssimo custo no C++, devolvendo quase instantaneamente uma mensagem SEARCH_DONE.
6. O Angular então desloca uma "janela" que flutua pelos dados conforme você mexe o Scroll, pedindo apenas 50 linhas por frame. A interface fica completamente suave.

O uso da memória JavaScript da sua página vai se manter em taxas nulas, pois 100% da matriz tabular fica isolada dentro da máquina virtual!