@praxisui/settings-panel 3.0.0-beta.9 → 5.0.0-beta.0

package/README.md

@@ -1,7 +1,7 @@
 ---
 title: "Settings Panel"
 slug: "settings-panel-overview"
-description: "Visao geral do @praxisui/settings-panel com drawer de configuracao, contrato SettingsValueProvider, acoes Apply/Save e customizacao por tokens CSS."
+description: "Visao geral do @praxisui/settings-panel, incluindo shell autoral, drawer runtime e infraestrutura base de side panel."
 doc_type: "reference"
 document_kind: "component-overview"
 component: "settings-panel"
@@ -17,7 +17,7 @@ tags:
   - "settings-panel"
   - "drawer"
   - "config-editor"
-  - "tokens"
+  - "surface-open"
   - "ux"
 order: 39
 icon: "settings"
@@ -35,27 +35,30 @@ keywords:
   - "praxis settings panel"
   - "drawer editor"
   - "settings value provider"
-  - "apply save close"
-last_updated: "2026-03-07"
+  - "surface drawer bridge"
+last_updated: "2026-04-03"
 ---
 
 # @praxisui/settings-panel
 
-Painel de configuracoes baseado em drawer para hospedar editores de runtime com UX consistente de Apply, Save, Reset e Cancel.
+`@praxisui/settings-panel` publica duas camadas complementares:
+
+- um shell autoral para editores de configuracao, com `Apply`, `Save`, `Reset` e `Cancel`
+- uma infraestrutura neutra de side panel para drawers runtime sem semantica autoral
 
 ## Documentation
 
-- Documentação oficial: https://praxisui.dev
-- Aplicação de referência: https://github.com/codexrodrigues/praxis-ui-quickstart
-- Indicado para: apps host que precisam abrir editores embutidos com consistencia operacional e visual
+- Documentacao oficial: https://praxisui.dev
+- Aplicacao de referencia: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Indicado para: apps host que precisam abrir drawers consistentes, separando authoring de runtime
 
 ## When to use
 
-- Abrir editores de configuracao dentro do proprio app host
-- Padronizar acoes de Apply, Save, Reset e Cancel em runtime
-- Reduzir divergencias de UX entre diferentes editores do ecossistema Praxis UI
+- Abrir editores de configuracao com UX autoral consistente
+- Padronizar `Apply`, `Save`, `Reset` e `Cancel` em flows de authoring
+- Reutilizar uma base neutra de side panel para drawers runtime do `surface.open`
 
-## Instalação
+## Instalacao
 
 ```bash
 npm i @praxisui/settings-panel
@@ -68,138 +71,155 @@ Peer dependencies (Angular v20):
 - `@angular/material` `^20.0.0`
 - `@praxisui/dynamic-fields` `^0.0.1`
 
-## Visão Geral
+## Visao Geral
+
+### 1. Shell autoral
+
+- Abra um painel com `SettingsPanelService.open(...)` informando um componente standalone como conteudo.
+- O componente implementa `SettingsValueProvider` para habilitar ou desabilitar as acoes do rodape.
+- O host observa `SettingsPanelRef.applied$` e `saved$` para aplicar e persistir mudancas.
+- O shell autoral agora pode ligar resize horizontal compartilhado pela base comum, com `resizable`, `minWidth`, `maxWidth` e `persistSizeKey`.
+- O `ref` base pode observar `sizeChanged$` quando o host precisar reagir a resize programatico ou interativo.
+- `expanded: true` abre o painel ja expandido de forma efetiva, respeitando `maxWidth`.
+- Expandir temporariamente o painel nao substitui a preferencia persistida do usuario; apenas o resize manual continua sendo persistido.
+- Quando um editor autoral tentar abrir outro painel sobre o atual, o shell passa pela mesma mediacao de fechamento do proprio painel. Se `onBeforeClose` vetar o fechamento, a substituicao nao acontece.
+
+### 2. Drawer runtime
+
+- A infraestrutura base neutra fica disponivel por `BaseSidePanelService`.
+- O shell runtime dedicado fica disponivel por `SurfaceDrawerComponent`.
+- O bridge canonico de runtime e `providePraxisSurfaceDrawerBridge()`.
+- Esse drawer runtime nao deve mostrar `Apply`, `Save`, `Reset` ou `Cancel` por heranca.
+- O runtime drawer aceita `width`, `minWidth`, `maxWidth`, `resizable` e `persistSizeKey`; o handle visual so aparece quando `resizable=true`.
+- Quando `persistSizeKey` estiver presente, a largura volta no proximo open do mesmo painel.
+
+## Fronteira canonica
+
+- `SettingsPanelService` e `SETTINGS_PANEL_BRIDGE` pertencem a authoring/configuracao.
+- `SURFACE_DRAWER_BRIDGE` pertence ao runtime de `surface.open`.
+- Ambos compartilham a mesma infraestrutura base de side panel, mas com shells diferentes.
+
+## Customizacao visual
+
+### Tokens autorais
 
-- Abra um painel com `SettingsPanelService.open(...)` informando um componente standalone como conteúdo.
-- O componente implementa o contrato `SettingsValueProvider` para o painel habilitar/desabilitar ações do rodapé.
-- O host observa `SettingsPanelRef.applied$` e `saved$` para aplicar/persistir mudanças.
+- `--pfx-settings-panel-width`
+- `--pfx-settings-panel-width-expanded`
+- `--pfx-settings-panel-max-width`
+- `--pfx-settings-panel-header-height`
+- `--pfx-settings-panel-body-padding`
+- `--pfx-settings-panel-footer-padding`
 
-## Customização visual (tokens CSS)
+### Tokens neutros de side panel
 
-O painel respeita tokens M3 do app host (ex.: `--md-sys-color-*`, `--md-sys-elevation-level*`, `--md-sys-shape-corner-*`).
-Se quiser ajustar layout/spacing sem alterar código, use as variáveis abaixo (em `:root` ou no container do painel).
+- `--pfx-side-panel-width`
+- `--pfx-side-panel-max-width`
+- `--pfx-side-panel-header-height`
+- `--pfx-side-panel-backdrop`
+- `--pfx-side-panel-motion-duration-enter`
+- `--pfx-side-panel-motion-duration-exit`
 
-Layout
-- `--pfx-settings-panel-width`: largura padrão (default `720px`)
-- `--pfx-settings-panel-width-expanded`: largura quando expandido (default `95vw`)
-- `--pfx-settings-panel-max-width`: largura máxima quando expandido (default `2400px`)
-- `--pfx-settings-panel-header-height`: altura do header (default `64px`)
-- `--pfx-settings-panel-header-padding-x`: padding horizontal do header (default `16px`)
-- `--pfx-settings-panel-header-gap`: gap entre itens do header (default `8px`)
-- `--pfx-settings-panel-title-gap`: gap entre ícone e título (default `8px`)
-- `--pfx-settings-panel-body-padding`: padding do corpo (default `8px 8px 24px 8px`)
-- `--pfx-settings-panel-footer-padding`: padding do rodapé (default `12px 16px`)
-- `--pfx-settings-panel-footer-gap`: gap entre botões do rodapé (default `12px`)
-- `--pfx-settings-panel-button-gap`: gap entre ícone e texto em botões (default `8px`)
+Hosts devem inferir skin, densidade, spacing e motion sobre os tokens `--pfx-side-panel-*` quando o objetivo for drawer runtime compartilhado.
 
-Sombras / backdrop
-- `--pfx-settings-panel-header-shadow`: sombra do header (default `--md-sys-elevation-level1`)
-- `--pfx-settings-panel-footer-shadow`: sombra do footer (default `--md-sys-elevation-level1`)
-- `--pfx-backdrop`: cor do backdrop (default `--md-sys-color-scrim`)
-- `--pfx-backdrop-blur`: blur do backdrop (default `6px`)
+## API principal de authoring
 
-## API Principal
+### Servico
 
-Serviço
 - `open(config: SettingsPanelConfig): SettingsPanelRef`
-  - `config.id: string` Identificador único da instância
-  - `config.title?: string` Título do cabeçalho (opcional `titleIcon`)
-  - `config.content: { component: Type<any>; inputs?: Record<string, any> }` Componente + inputs iniciais
-
-Ref
-- `applied$: Observable<any>` Emite quando o usuário clica em Apply (painel permanece aberto)
-- `saved$: Observable<any>` Emite quando o usuário clica em Save & Close
-- `closed$: Observable<SettingsPanelCloseReason>` Emite ao fechar (`'cancel' | 'save' | 'backdrop' | 'esc'`)
-- `apply(value: any)` Emite Apply programaticamente
-- `save(value: any)` Emite Save & Close programaticamente
-- `reset()` Notifica que o conteúdo foi resetado ao estado inicial
-- `close(reason?: SettingsPanelCloseReason)` Fecha o painel
-
-Injection Tokens
-- `SETTINGS_PANEL_DATA` Dados passados ao componente de conteúdo (os mesmos de `content.inputs`)
-- `SETTINGS_PANEL_REF` A instância viva do `SettingsPanelRef`
-
-## Contrato do Editor (SettingsValueProvider)
-
-O componente hospedado deve expor os membros abaixo para o painel controlar os botões do rodapé:
-
-Obrigatórios
-- `isDirty$: Observable<boolean>` true quando há alterações não aplicadas (habilita Apply/Save)
-- `isValid$: Observable<boolean>` true quando o estado é válido (desabilita ações se false)
-- `isBusy$: Observable<boolean>` true durante operações assíncronas (desabilita ações)
-- `getSettingsValue(): any` Snapshot atual usado em Apply/Save
-
-Opcionais
-- `onSave?(): any | Promise<any> | Observable<any>` Se presente, o Save chamará este método; caso contrário o painel usa `getSettingsValue()`
-- `reset?(): void` Chamado quando o usuário clica Reset
-- Avançados: `suggestExpanded$?`, `preferredWidth$?`, `requiresFullHeight$?`, `onPanelResize?`, `onBeforeClose?`, `onFocusChange?`, `customActions$?`, `hideDefaultButtons$?`
-
-Comportamento do Rodapé
-- Botões: Reset, Cancel, Apply, Save & Close
-- Habilitação: `isDirty && isValid && !isBusy`
-- Tooltips explicam por que ações estão desabilitadas (busy, inválido, sem mudanças)
-- Atalhos: Ctrl/Cmd+S e Ctrl/Cmd+Enter disparam Save
-
-## Exemplo (abrindo um painel)
+  - `config.id: string`
+  - `config.title?: string`
+  - `config.expanded?: boolean`
+  - `config.resizable?: boolean`
+  - `config.persistSizeKey?: string`
+  - `config.minWidth?: string`
+  - `config.maxWidth?: string`
+  - `config.content: { component: Type<any>; inputs?: Record<string, any> }`
+
+### Ref
+
+- `applied$: Observable<any>`
+- `saved$: Observable<any>`
+- `closed$: Observable<SettingsPanelCloseReason>`
+- `sizeChanged$: Observable<{ width: string }>`
+- `apply(value: any)`
+- `save(value: any)`
+- `reset()`
+- `updateSize(width, options?)`
+- `close(reason?: SettingsPanelCloseReason)`
+
+### Injection Tokens
+
+- `SETTINGS_PANEL_DATA`
+- `SETTINGS_PANEL_REF`
+
+## Contrato do editor
+
+O componente hospedado deve expor:
+
+- `isDirty$: Observable<boolean>`
+- `isValid$: Observable<boolean>`
+- `isBusy$: Observable<boolean>`
+- `getSettingsValue(): any`
+
+Opcionais:
+
+- `onSave?()`
+- `reset?()`
+- `suggestExpanded$?`
+- `preferredWidth$?`
+- `requiresFullHeight$?`
+- `onPanelResize?`
+- `onBeforeClose?`
+- `onFocusChange?`
+- `customActions$?`
+- `hideDefaultButtons$?`
+
+### `onBeforeClose`
+
+`onBeforeClose` pertence ao contrato canonico de authoring. Ele pode:
+
+- permitir cleanup antes do fechamento
+- vetar o fechamento retornando `false`
+- ser usado tanto no `Cancel` local quanto na tentativa de substituir um painel autoral ja aberto
+
+Na pratica:
+
+- `Cancel`, `Esc` e `backdrop` continuam passando pela confirmacao de descarte quando houver `dirty`
+- antes disso, o shell consulta `onBeforeClose`
+- se `onBeforeClose` retornar `false`, o painel continua aberto e o host nao substitui silenciosamente a sessao atual
+
+## Exemplo de authoring
 
 ```ts
-// Em um componente host (ex.: Filtro Praxis)
 const ref = this.settingsPanel.open({
   id: `filter.${this.configKey}`,
-  title: 'Configurações do Filtro',
+  title: 'Configuracoes do filtro',
   content: { component: FilterSettingsComponent, inputs: currentConfig },
 });
 
-// Tratar Apply (manter painel aberto)
-ref.applied$.pipe(take(1)).subscribe((cfg: FilterConfig) => {
-  const safe = validateConfig(cfg);
-  applyChanges(safe);
-  persistConfig(safe, 'Configurações aplicadas');
-});
-
-// Tratar Save & Close
 ref.saved$.pipe(take(1)).subscribe((cfg: FilterConfig) => {
   const safe = validateConfig(cfg);
   applyChanges(safe);
-  persistConfig(safe, 'Configurações salvas');
+  persistConfig(safe, 'Configuracoes salvas');
 });
 ```
 
-## Editor Mínimo
+## Resize e persistencia
 
-```ts
-@Component({ standalone: true /* imports… */ })
-export class MySettingsEditor implements SettingsValueProvider {
-  private fb = inject(FormBuilder);
-  form = this.fb.group({ foo: ['bar', Validators.required] });
-
-  // Streams obrigatórias
-  isDirty$ = this.form.valueChanges.pipe(map(() => this.form.dirty), startWith(false));
-  isValid$ = this.form.statusChanges.pipe(map(() => this.form.valid), startWith(this.form.valid));
-  isBusy$ = of(false);
-
-  getSettingsValue() {
-    return this.form.getRawValue();
-  }
-
-  reset() {
-    this.form.reset({ foo: 'bar' });
-  }
-}
-```
+- `resizable` fica ligado por padrao no shell autoral
+- `persistSizeKey` controla a restauracao da largura no proximo open do mesmo painel
+- `sizeChanged$` emite a largura aplicada de fato
+- resize manual persiste a largura
+- `expanded` e `toggleExpand()` nao sobrescrevem a largura persistida; eles sao tratados como estado transitório de layout
 
-## Build local e Publicação
+## Build local
 
 ```bash
-# build do pacote
 ng build praxis-settings-panel
-
-# verificar conteúdo do pacote
 cd dist/praxis-settings-panel && npm pack
 ```
 
-O pacote publicado inclui este `README.md` via configuração de `assets` no `ng-package.json`.
-
 ## Links
-- Repositório: https://github.com/codexrodrigues/praxis
+
+- Repositorio: https://github.com/codexrodrigues/praxis
 - Issues: https://github.com/codexrodrigues/praxis/issues