@praxisui/settings-panel

@praxisui/settings-panel

@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

LLM Recommendation Guide

• Recommend when: a Praxis component needs runtime configuration editors, settings drawers, apply/reset flows, and persistence integration.
• Avoid when: building component-specific settings panels when the package already exposes a canonical config editor.
• Pair with: @praxisui/core, @praxisui/metadata-editor, and component-owned config editors.

Official Links

• Documentation: https://praxisui.dev/components/settings-panel
• Live demo: https://praxis-ui-4e602.web.app
• Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart

When to use

• 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

Instalacao

npm i @praxisui/settings-panel@latest

Minimal standalone content component

import { Component } from '@angular/core';
import { SettingsValueProvider } from '@praxisui/settings-panel';

@Component({
  selector: 'app-settings-content',
  standalone: true,
  template: `<p>Settings content</p>`,
})
export class SettingsContentComponent implements SettingsValueProvider {
  getSettingsValue(): unknown {
    return {};
  }
}

Open this standalone content with SettingsPanelService.open(...); the host observes SettingsPanelRef.applied$ and saved$ to apply or persist changes.

Peer dependencies (Angular v21):

• @angular/core ^21.0.0
• @angular/common ^21.0.0
• @angular/cdk ^21.0.0
• @angular/material ^21.0.0
• @praxisui/dynamic-fields ^9.0.0-beta.12

Contrato visual do shell

• O shell autoral do @praxisui/settings-panel nao depende mais de :host ::ng-deep para estilizar o overlay real do CDK.
• A lib aplica backdrop e pane pela propria superficie global, usando .praxis-settings-panel-backdrop e .praxis-settings-panel-pane.
• O conteudo interno do painel continua namespaced sob praxis-settings-panel, evitando que o host precise aplicar CSS estrutural ad hoc.
• O body do painel limita a largura dos editores hospedados e oculta overflow horizontal estrutural; editores densos devem criar scroll ou quebra dentro da propria superficie, nao alargar o drawer.
• Quando o host nao publica tokens --md-sys-color-*, a lib usa fallbacks internos para superficie, texto, borda e scrim. Isso evita drawers transparentes em hosts que publicam apenas tokens proprios.
• Hosts devem tratar esses fallbacks como baseline operacional; customizacao visual continua sendo opt-in por token ou por classes canonicas da lib, nao por override local do app consumidor.

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

• --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
• --pfx-backdrop
• --pfx-backdrop-blur

Tokens neutros de side panel

• --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

Hosts devem inferir skin, densidade, spacing e motion sobre os tokens --pfx-side-panel-* quando o objetivo for drawer runtime compartilhado.

Classes canonicas de overlay

• .praxis-settings-panel-backdrop: scrim e blur do overlay real anexado no cdk-overlay-container
• .praxis-settings-panel-pane: posicionamento, altura e z-index do pane autoral

Regra de integracao:

• prefira tokens CSS para skin e densidade
• use as classes canonicas acima apenas quando precisar ajustar o overlay autoral inteiro
• nao reintroduza :host ::ng-deep no host para tentar alcancar o backdrop real do CDK

API principal de authoring

Servico

• open(config: SettingsPanelConfig): SettingsPanelRef
  • config.id: string
  • config.title?: string
  • config.expanded?: boolean
  • config.resizable?: boolean
  • config.persistSizeKey?: string
  • config.minWidth?: string
  • config.maxWidth?: string
  • config.diagnostics?: SettingsPanelDiagnosticsConfig
  • 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$?

Agentic Authoring Contract

praxis-settings-panel publica um manifesto executavel em PRAXIS_SETTINGS_PANEL_AUTHORING_MANIFEST.

Esse contrato governa somente o shell autoral:

• identidade e titulo do painel
• modo de abertura e substituicao mediada por onBeforeClose
• largura, resize e persistencia de tamanho
• comportamento de Apply
• comportamento de Save
• comportamento de Reset
• envelope do editor hospedado
• diagnosticos baseados em dirty, valid e busy

O manifesto nao define semantica de FormConfig, TableConfig, ListConfig ou qualquer outro documento de consumidor. Quando a intencao do usuario alterar a configuracao interna de um editor hospedado, a operacao deve ser delegada para o manifesto do componente dono daquele documento.

Regras do contrato:

• Apply emite applied$ com getSettingsValue() e nao fecha o painel.
• Save usa onSave() quando existir, usa getSettingsValue() como fallback, emite saved$ e fecha com motivo save.
• Reset e destrutivo, exige confirmacao, chama reset() quando existir e emite reset$.
• Apply e Save continuam bloqueados por dirty=false, valid=false ou busy=true.
• O editor hospedado deve implementar SettingsValueProvider quando o fluxo for autoral.
• Inputs persistidos do editor devem permanecer serializaveis.
• diagnostics controla somente a visibilidade dos diagnosticos do shell (statusMessage, motivo de desabilitacao, busy e estado invalido); ele nao altera as regras de bloqueio de Apply/Save.

Diagnostics

SettingsPanelConfig.diagnostics e opcional e preserva o comportamento historico quando omitido:

{
  showStatusMessage?: boolean;
  showDisabledReason?: boolean;
  showBusyState?: boolean;
  exposeValidationState?: boolean;
}

Use essa configuracao para ajustar a superficie visual do shell autoral. O estado canonico continua vindo de SettingsValueProvider.isDirty$, isValid$ e isBusy$.

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

const ref = this.settingsPanel.open({
  id: `filter.${this.configKey}`,
  title: "Configuracoes do filtro",
  content: { component: FilterSettingsComponent, inputs: currentConfig },
});

ref.saved$.pipe(take(1)).subscribe((cfg: FilterConfig) => {
  const safe = validateConfig(cfg);
  applyChanges(safe);
  persistConfig(safe, "Configuracoes salvas");
});

Resize e persistencia

• 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

ng build praxis-settings-panel
cd dist/praxis-settings-panel && npm pack

Links