@praxisui/settings-panel

@praxisui/settings-panel

🔰 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.

Painel de configurações baseado em drawer para hospedar editores de configuração com UX consistente (Apply, Save & Close, Reset, Cancel).

Instalação

npm i @praxisui/settings-panel

Peer dependencies (Angular v20):

• @angular/core ^20.0.0
• @angular/common ^20.0.0
• @angular/cdk ^20.0.0
• @angular/material ^20.0.0
• @praxisui/dynamic-fields ^0.0.1

Visão Geral

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

API Principal

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)

// Em um componente host (ex.: Filtro Praxis)
const ref = this.settingsPanel.open({
  id: `filter.${this.configKey}`,
  title: 'Configurações 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');
});

Editor Mínimo

@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' });
  }
}

Build local e Publicação

# 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
• Issues: https://github.com/codexrodrigues/praxis/issues