@praxisui/page-builder/README.md

Page and widget builder utilities for Praxis UI (grid, dynamic widgets, editors).

# @praxisui/page-builder

## 🔰 Exemplos / Quickstart

Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):

- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.

Ferramentas de edição para páginas dinâmicas baseadas em Gridster. Inclui o conjunto de editores (Builder, Graph), paleta de componentes e toolbars para montar e inspecionar conexões entre widgets definidos por metadata (`GridPageDefinition` do `@praxisui/core`). Integra com o `@praxisui/settings-panel` para abrir editores em painel lateral e oferece um modo de diálogo fullscreen para edição visual.

## Instalação

```bash
npm i @praxisui/page-builder
```

Peer dependencies (Angular v20):
- `@angular/core` `^20.0.0`
- `@angular/common` `^20.0.0`
- `@angular/forms` `^20.0.0`
- `@angular/cdk` `^20.0.0`
- `@angular/material` `^20.0.0`
- `angular-gridster2` `^20.2.2`
- `@praxisui/core` `*`
- `@praxisui/settings-panel` `*`

## Visão Geral

Este pacote expõe os editores e utilitários usados pelo componente de página dinâmica (Gridster):
- `ConnectionBuilderComponent` — lista e edita conexões (from.output → to.input) com filtros, agrupamentos e validação.
- `ConnectionGraph` (uso integrado) — visualiza nós/portas/arestas; suporta arrastar para criar conexões e abrir o Builder.
- `ComponentPaletteDialog` — paleta para adicionar widgets à página.
- `FloatingToolbar` e `TileToolbar` — ações rápidas (adicionar, conexões, configurações, salvar, pré‑visualizar).

Os editores podem ser abertos:
- Via `SettingsPanelService` (painel lateral) — recomendado para fluxo dentro do app.
- Como diálogo fullscreen (Material Dialog) para uma experiência imersiva de edição.

## Quick Start (usando a página Gridster)

O componente de página dinâmica (parte do workspace) expõe métodos utilitários para abrir editores. Exemplo de uso no template:

```html
<praxis-dynamic-gridster-page
  #page
  [page]="page"
  [editModeEnabled]="true"
  (pageChange)="onPageChange($event)">
</praxis-dynamic-gridster-page>

<!-- Ações auxiliares -->
<button (click)="page.openConnectionsGraph()">Conexões (Graph)</button>
<button (click)="page.openConnectionsBuilder()">Conexões (Builder)</button>
<button (click)="page.openConnectionsEditor()">Editor Visual (Dialog)</button>
```

`page` é um `GridPageDefinition` (do `@praxisui/core`) contendo `widgets` e opcionalmente `connections`.

## Abrindo editores via Settings Panel

Para abrir o Builder/Graph em um painel lateral, injete o `SettingsPanelService` e forneça o conteúdo. O `ConnectionBuilderComponent` é exportado por este pacote.

```ts
import { Component } from '@angular/core';
import { SettingsPanelService } from '@praxisui/settings-panel';
import { ConnectionBuilderComponent } from '@praxisui/page-builder';
import type { GridPageDefinition, GridWidgetInstance } from '@praxisui/core';

@Component({ selector: 'app-page-tools', standalone: true })
export class PageToolsComponent {
  constructor(private settings: SettingsPanelService) {}

  openBuilder(page: GridPageDefinition, widgets: GridWidgetInstance[]) {
    this.settings.open({
      id: 'grid-connections:builder',
      title: 'Conexões (Builder)',
      content: { component: ConnectionBuilderComponent, inputs: { page, widgets } },
    });
  }
}
```

Para abrir o Graph visual como painel, utilize os métodos do componente da página (`page.openConnectionsGraph()`), que encapsulam o componente interno do gráfico.

## Diálogo fullscreen (Graph/Editor Visual)

O fluxo visual completo pode ser aberto em diálogo Material (fullscreen). Caso esteja usando o componente de página, utilize `page.openConnectionsEditor()` para abrir o editor visual; ele lida com a passagem de `page` e `widgets` e propaga o resultado em `pageChange` quando o usuário salva.

## Dicas
- O Builder valida se o `output` existe no widget de origem e se o `input` existe no destino.
- No Graph, ativar “Mostrar portas não conectadas” ajuda a descobrir possibilidades de ligação.
- Tanto Builder quanto Graph funcionam com `GridPageDefinition` em string (JSON) ou objeto.

## API (resumo)

Exports deste pacote:
- `ConnectionBuilderComponent`
- `ComponentPaletteDialogComponent`
- `FloatingToolbarComponent`
- `TileToolbarComponent`

Integrações comuns:
- `SettingsPanelService.open({ id, title, content: { component, inputs } })`
- Métodos do componente da página: `openConnectionsGraph()`, `openConnectionsBuilder()`, `openConnectionsEditor()`

## Links
- Repo: https://github.com/codexrodrigues/praxis
- Issues: https://github.com/codexrodrigues/praxis/issues