@praxisui/settings-panel 9.0.4-rc.3 → 9.0.4-rc.31

package/README.md

@@ -87,14 +87,22 @@ Peer dependencies (Angular v21):
 - 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.
+- `title`, `titleIcon` e `subtitle` formam o cabecalho governado do drawer; o shell resolve espacamento, quebra responsiva e relaciona o subtitulo por `aria-describedby`, sem exigir CSS local do host.
 - 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.
+- Uma sessao runtime pode manter uma unica surface primaria e navegar entre etapas com `surfaceRuntime.push(frame)`, `replace(frame)` e `back()`.
+- O shell preserva a instancia Angular, o scroll e o alvo de foco dos frames anteriores. O botao Voltar so aparece quando existe historico e devolve o foco para a etapa restaurada.
+- `surfaceRuntime.navigation$` publica `sessionId`, `activeFrameId`, profundidade e `canGoBack`; esse estado e efemero e nunca deve ser persistido em metadata, `x-ui` ou configuracao de componente.
+- Formularios podem registrar `surfaceRuntime.setCanLeave(guard)` para impedir `back`, `replace`, Escape, backdrop ou fechamento enquanto o lifecycle da etapa exigir confirmacao. O guard e runtime-only e nao substitui regras de negocio nem autorizacao.
+- Componentes criados dentro de uma frame podem injetar `SURFACE_DRAWER_REF` e `SURFACE_DRAWER_CONTENT_DATA`. Esses tokens representam exclusivamente a frame ativa e seus inputs efemeros; nao devem ser usados como uma segunda fonte de metadata.
+- O CRUD oficial reutiliza automaticamente a sessao ativa: formularios abertos em modo drawer viram uma nova frame, publicam `save/delete/close` no mesmo ref e retornam ao contexto anterior sem empilhar overlays.
 
 ## 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.
+- Tipos de componente e callbacks de navegacao pertencem exclusivamente a sessao runtime; JSON governado continua descrevendo a intencao de abrir a surface, nao uma pilha imperativa serializada.
 
 ## Customizacao visual
 

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-07-31T14:02:14.681Z",
+  "generatedAt": "2026-08-05T03:38:59.493Z",
   "packageName": "@praxisui/settings-panel",
-  "packageVersion": "9.0.4-rc.3",
+  "packageVersion": "9.0.4-rc.31",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 1,

package/fesm2022/praxisui-settings-panel.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { inject, DestroyRef, ViewContainerRef, HostListener, ViewChild, ViewEncapsulation, ChangeDetectionStrategy, Component, InjectionToken, Injector, Injectable, ChangeDetectorRef, ENVIRONMENT_INITIALIZER } from '@angular/core';
+import { inject, DestroyRef, ViewContainerRef, HostListener, ViewChild, ViewEncapsulation, ChangeDetectionStrategy, Component, InjectionToken, Injector, Injectable, ElementRef, ChangeDetectorRef, ENVIRONMENT_INITIALIZER } from '@angular/core';
 import * as i2 from '@angular/common';
 import { CommonModule, NgStyle, NgClass } from '@angular/common';
 import { CdkTrapFocus } from '@angular/cdk/a11y';
@@ -17,7 +17,7 @@ import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { filter, switchMap, debounceTime, distinctUntilChanged } from 'rxjs/operators';
 import { isObservable, firstValueFrom, of, from, Subject, ReplaySubject, take, BehaviorSubject } from 'rxjs';
 import * as i1$2 from '@praxisui/core';
-import { providePraxisI18n, PraxisI18nService, PraxisIconButtonComponent, PraxisIconDirective, SETTINGS_PANEL_DATA as SETTINGS_PANEL_DATA$1, PraxisLayerScaleStyleService, SETTINGS_PANEL_BRIDGE, SURFACE_DRAWER_BRIDGE, GlobalConfigService, FieldControlType, IconPickerService, LoggerService, ComponentMetadataRegistry } from '@praxisui/core';
+import { providePraxisI18n, PraxisI18nService, PraxisIconButtonComponent, PraxisIconDirective, SETTINGS_PANEL_DATA as SETTINGS_PANEL_DATA$1, PraxisLayerScaleStyleService, SETTINGS_PANEL_BRIDGE, SURFACE_DRAWER_BRIDGE, SURFACE_DRAWER_CONTENT_DATA, SURFACE_DRAWER_REF, GlobalConfigService, FieldControlType, IconPickerService, LoggerService, ComponentMetadataRegistry } from '@praxisui/core';
 import { ConfirmDialogComponent } from '@praxisui/dynamic-fields';
 import * as i1$1 from '@angular/cdk/overlay';
 import { ComponentPortal } from '@angular/cdk/portal';
@@ -438,6 +438,7 @@ const PRAXIS_SETTINGS_PANEL_EN_US = {
     'Collapse panel': 'Collapse panel',
     'Expand panel': 'Expand panel',
     Close: 'Close',
+    Back: 'Back',
     Apply: 'Apply',
     'Save & Close': 'Save & Close',
 };
@@ -460,6 +461,7 @@ const PRAXIS_SETTINGS_PANEL_PT_BR = {
     'Collapse panel': 'Reduzir painel',
     'Expand panel': 'Expandir painel',
     Close: 'Fechar',
+    Back: 'Voltar',
     Apply: 'Aplicar',
     'Save & Close': 'Salvar & Fechar',
 };
@@ -1408,6 +1410,7 @@ class BaseSidePanelOverlayRef {
     overlayRef;
     titleUpdater;
     sizePersistor;
+    terminalOutcomeEmitted = false;
     closed$ = this.closedSubject.asObservable();
     result$ = this.resultSubject.asObservable();
     sizeChanged$ = this.sizeChangedSubject.asObservable();
@@ -1423,6 +1426,14 @@ class BaseSidePanelOverlayRef {
     emitResult(result) {
         this.resultSubject.next(result);
     }
+    complete(outcome) {
+        if (this.terminalOutcomeEmitted || !this.overlayRef?.hasAttached()) {
+            return;
+        }
+        this.terminalOutcomeEmitted = true;
+        this.resultSubject.next(outcome);
+        this.close(outcome);
+    }
     updateTitle(title) {
         this.titleUpdater?.(title);
     }
@@ -1802,10 +1813,15 @@ class SurfaceDrawerComponent {
     useHostWidth = false;
     theme = null;
     onClose;
+    onBack;
     static nextId = 0;
     titleId = `praxis-surface-drawer-title-${SurfaceDrawerComponent.nextId++}`;
+    subtitleId = `${this.titleId}-description`;
     contentRef;
     contentHost;
+    body;
+    backButton;
+    frames = [];
     constructor(cdr, i18n) {
         this.cdr = cdr;
         this.i18n = i18n;
@@ -1817,7 +1833,25 @@ class SurfaceDrawerComponent {
         return (this.theme?.cssVars ?? {});
     }
     get closeLabel() {
-        return this.i18n.t('Close', undefined, 'Close', PRAXIS_SETTINGS_PANEL_I18N_NAMESPACE);
+        const fallback = this.i18n.getLocale().toLowerCase().startsWith('en')
+            ? 'Close'
+            : 'Fechar';
+        return this.i18n.t('Close', undefined, fallback, PRAXIS_SETTINGS_PANEL_I18N_NAMESPACE);
+    }
+    get backLabel() {
+        const fallback = this.i18n.getLocale().toLowerCase().startsWith('en')
+            ? 'Back'
+            : 'Voltar';
+        return this.i18n.t('Back', undefined, fallback, PRAXIS_SETTINGS_PANEL_I18N_NAMESPACE);
+    }
+    get canGoBack() {
+        return this.frames.length > 1;
+    }
+    get navigationDepth() {
+        return this.frames.length;
+    }
+    get activeFrameId() {
+        return this.frames[this.frames.length - 1]?.definition.id ?? '';
     }
     get hasHeader() {
         return !!(this.title || this.titleIcon || this.subtitle);
@@ -1832,11 +1866,156 @@ class SurfaceDrawerComponent {
         this.title = title;
         this.cdr.markForCheck();
     }
+    ngOnDestroy() {
+        for (const frame of this.frames) {
+            if (!frame.componentRef.hostView.destroyed) {
+                frame.componentRef.destroy();
+            }
+        }
+        this.frames = [];
+    }
     attachContent(component, injector, inputs) {
-        this.contentRef = this.contentHost.createComponent(component, { injector });
-        this.applyInputs(this.contentRef, inputs);
+        return this.initializeFrame({
+            id: 'root',
+            title: this.title,
+            titleIcon: this.titleIcon,
+            subtitle: this.subtitle,
+            content: { component, inputs },
+        }, injector, inputs);
+    }
+    initializeFrame(definition, injector, inputs) {
+        this.destroyAllFrames();
+        const frame = this.createFrame(definition, injector, inputs);
+        this.frames = [frame];
+        this.applyFrameHeader(frame);
+        return frame.componentRef;
+    }
+    pushFrame(definition, injector, inputs) {
+        this.captureActiveFrameState();
+        this.detachActiveView();
+        const frame = this.createFrame(definition, injector, inputs);
+        this.frames.push(frame);
+        this.applyFrameHeader(frame);
+        this.focusNavigationControl();
+        return frame.componentRef;
+    }
+    async replaceFrame(definition, injector, inputs) {
+        if (!(await this.canLeaveActiveFrame())) {
+            return null;
+        }
+        this.removeActiveFrame();
+        const frame = this.createFrame(definition, injector, inputs);
+        this.frames.push(frame);
+        this.applyFrameHeader(frame);
+        this.focusNavigationControl();
+        return frame.componentRef;
+    }
+    async backFrame() {
+        if (!this.canGoBack || !(await this.canLeaveActiveFrame())) {
+            return false;
+        }
+        this.removeActiveFrame();
+        const previous = this.frames[this.frames.length - 1];
+        if (!previous) {
+            return false;
+        }
+        this.contentHost.insert(previous.componentRef.hostView);
+        this.contentRef = previous.componentRef;
+        this.applyFrameHeader(previous);
+        queueMicrotask(() => {
+            if (this.body?.nativeElement) {
+                this.body.nativeElement.scrollTop = previous.scrollTop;
+            }
+            const target = previous.restoreFocusTo;
+            if (target?.isConnected) {
+                target.focus();
+            }
+            else {
+                this.backButton?.nativeElement.focus();
+            }
+        });
+        return true;
+    }
+    setActiveCanLeave(guard) {
+        const active = this.frames[this.frames.length - 1];
+        if (active) {
+            active.canLeave = guard;
+        }
+    }
+    async canCloseSession() {
+        for (let index = this.frames.length - 1; index >= 0; index -= 1) {
+            const guard = this.frames[index].canLeave;
+            if (guard && !(await Promise.resolve(guard()))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    createFrame(definition, injector, inputs) {
+        const componentRef = this.contentHost.createComponent(definition.content.component, { injector });
+        this.applyInputs(componentRef, inputs);
+        this.contentRef = componentRef;
         this.cdr.markForCheck();
-        return this.contentRef;
+        return {
+            definition,
+            componentRef,
+            scrollTop: 0,
+            restoreFocusTo: null,
+            canLeave: definition.canLeave ?? null,
+        };
+    }
+    captureActiveFrameState() {
+        const active = this.frames[this.frames.length - 1];
+        if (!active)
+            return;
+        active.scrollTop = this.body?.nativeElement.scrollTop ?? 0;
+        const focused = typeof document !== 'undefined'
+            ? document.activeElement
+            : null;
+        active.restoreFocusTo = focused instanceof HTMLElement ? focused : null;
+    }
+    detachActiveView() {
+        const active = this.frames[this.frames.length - 1];
+        if (!active)
+            return;
+        const index = this.contentHost.indexOf(active.componentRef.hostView);
+        if (index >= 0) {
+            this.contentHost.detach(index);
+        }
+    }
+    removeActiveFrame() {
+        const active = this.frames.pop();
+        if (!active)
+            return;
+        const index = this.contentHost.indexOf(active.componentRef.hostView);
+        if (index >= 0) {
+            this.contentHost.remove(index);
+        }
+        else if (!active.componentRef.hostView.destroyed) {
+            active.componentRef.destroy();
+        }
+    }
+    destroyAllFrames() {
+        this.contentHost.clear();
+        for (const frame of this.frames) {
+            if (!frame.componentRef.hostView.destroyed) {
+                frame.componentRef.destroy();
+            }
+        }
+        this.frames = [];
+    }
+    async canLeaveActiveFrame() {
+        const guard = this.frames[this.frames.length - 1]?.canLeave;
+        return guard ? Promise.resolve(guard()) : true;
+    }
+    applyFrameHeader(frame) {
+        this.title = frame.definition.title;
+        this.titleIcon = frame.definition.titleIcon;
+        this.subtitle = frame.definition.subtitle;
+        this.cdr.markForCheck();
+    }
+    focusNavigationControl() {
+        queueMicrotask(() => this.backButton?.nativeElement.focus());
     }
     applyInputs(componentRef, inputs) {
         if (!inputs) {
@@ -1869,7 +2048,7 @@ class SurfaceDrawerComponent {
         return new Set(Object.keys(declaredInputs));
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: SurfaceDrawerComponent, deps: [{ token: i0.ChangeDetectorRef }, { token: i1$2.PraxisI18nService }], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: SurfaceDrawerComponent, isStandalone: true, selector: "praxis-surface-drawer", viewQueries: [{ propertyName: "contentHost", first: true, predicate: ["contentHost"], descendants: true, read: ViewContainerRef, static: true }], ngImport: i0, template: "<div\n  class=\"pfx-surface-drawer\"\n  [class.has-header]=\"hasHeader\"\n  [class.width-narrow]=\"widthClass === 'width-narrow'\"\n  [class.width-default]=\"widthClass === 'width-default'\"\n  [class.width-wide]=\"widthClass === 'width-wide'\"\n  [class.width-full]=\"widthClass === 'width-full'\"\n  [class.use-host-width]=\"useHostWidth\"\n  [ngClass]=\"hostClasses\"\n  [ngStyle]=\"hostCssVars\"\n  role=\"dialog\"\n  aria-modal=\"true\"\n  [attr.aria-labelledby]=\"hasHeader ? titleId : null\"\n  cdkTrapFocus\n  cdkTrapFocusAutoCapture\n>\n  @if (hasHeader) {\n    <header class=\"pfx-surface-drawer__header\">\n      <div class=\"pfx-surface-drawer__title-block\">\n        @if (titleIcon) {\n          <mat-icon class=\"pfx-surface-drawer__title-icon\" [praxisIcon]=\"titleIcon\"></mat-icon>\n        }\n        <div class=\"pfx-surface-drawer__copy\">\n          @if (title) {\n            <h2 class=\"pfx-surface-drawer__title\" [id]=\"titleId\">{{ title }}</h2>\n          }\n          @if (subtitle) {\n            <p class=\"pfx-surface-drawer__subtitle\">{{ subtitle }}</p>\n          }\n        </div>\n      </div>\n      <button\n        praxisIconButton=\"close\"\n        size=\"compact\"\n        type=\"button\"\n        class=\"pfx-surface-drawer__close\"\n        [attr.aria-label]=\"closeLabel\"\n        [matTooltip]=\"closeLabel\"\n        (click)=\"onClose?.()\"\n      ></button>\n    </header>\n  }\n\n  <section class=\"pfx-surface-drawer__body\">\n    <ng-template #contentHost></ng-template>\n  </section>\n</div>\n", styles: [":host{display:block;height:100%;width:100%;min-width:0;flex:1 1 auto}.pfx-surface-drawer{display:grid;grid-template-rows:auto 1fr;height:100%;min-width:0;max-width:100%;overflow:hidden;background:var(--md-sys-color-surface-container, #fff);color:var(--md-sys-color-on-surface, #111);border-left:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));border-radius:var(--pfx-side-panel-border-radius, 0);box-shadow:var(--pfx-side-panel-elevation, var(--md-sys-elevation-level2, 0 8px 24px rgba(0, 0, 0, .16)));width:var(--pfx-side-panel-width, 720px);transition:width var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1)),box-shadow var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1))}.pfx-surface-drawer.use-host-width{width:100%;max-width:100%}.pfx-surface-drawer.width-narrow{width:var(--pfx-side-panel-width, 420px)}.pfx-surface-drawer.width-default{width:var(--pfx-side-panel-width, 720px)}.pfx-surface-drawer.width-wide{width:var(--pfx-side-panel-width, 960px)}.pfx-surface-drawer.width-full{width:min(100vw,var(--pfx-side-panel-max-width, 100vw))}.pfx-surface-drawer__header{display:flex;align-items:center;gap:var(--pfx-side-panel-header-gap, 8px);min-height:var(--pfx-side-panel-header-height, 64px);padding:0 var(--pfx-side-panel-header-padding-x, 16px);border-bottom:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));background:var(--md-sys-color-surface-container-high, #f7f7f7)}.pfx-surface-drawer__title-block{display:flex;align-items:flex-start;gap:10px;min-width:0;flex:1 1 auto}.pfx-surface-drawer__title-icon{color:var(--md-sys-color-primary, currentColor)}.pfx-surface-drawer__copy{min-width:0}.pfx-surface-drawer__title,.pfx-surface-drawer__subtitle{margin:0}.pfx-surface-drawer__title{font-size:1rem;font-weight:600}.pfx-surface-drawer__subtitle{margin-top:4px;color:var(--md-sys-color-on-surface-variant, rgba(0, 0, 0, .64));font-size:.875rem}.pfx-surface-drawer__body{min-height:0;overflow:auto;padding:var(--pfx-side-panel-body-padding, 16px);background:var(--md-sys-color-surface, #fff)}@media(prefers-reduced-motion:reduce){.pfx-surface-drawer{transition:none}}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: i2.NgStyle, selector: "[ngStyle]", inputs: ["ngStyle"] }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i3.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i4$1.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "directive", type: CdkTrapFocus, selector: "[cdkTrapFocus]", inputs: ["cdkTrapFocus", "cdkTrapFocusAutoCapture"], exportAs: ["cdkTrapFocus"] }, { kind: "component", type: PraxisIconButtonComponent, selector: "button[praxisIconButton]", inputs: ["praxisIconButton", "size", "appearance", "presentation", "pressed", "busy"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: SurfaceDrawerComponent, isStandalone: true, selector: "praxis-surface-drawer", viewQueries: [{ propertyName: "contentHost", first: true, predicate: ["contentHost"], descendants: true, read: ViewContainerRef, static: true }, { propertyName: "body", first: true, predicate: ["body"], descendants: true, read: ElementRef }, { propertyName: "backButton", first: true, predicate: ["backButton"], descendants: true, read: ElementRef }], ngImport: i0, template: "<div\n  class=\"pfx-surface-drawer\"\n  [class.has-header]=\"hasHeader\"\n  [class.width-narrow]=\"widthClass === 'width-narrow'\"\n  [class.width-default]=\"widthClass === 'width-default'\"\n  [class.width-wide]=\"widthClass === 'width-wide'\"\n  [class.width-full]=\"widthClass === 'width-full'\"\n  [class.use-host-width]=\"useHostWidth\"\n  [ngClass]=\"hostClasses\"\n  [ngStyle]=\"hostCssVars\"\n  role=\"dialog\"\n  aria-modal=\"true\"\n  [attr.aria-labelledby]=\"hasHeader ? titleId : null\"\n  [attr.aria-describedby]=\"subtitle ? subtitleId : null\"\n  cdkTrapFocus\n  cdkTrapFocusAutoCapture\n>\n  @if (hasHeader) {\n    <header class=\"pfx-surface-drawer__header\">\n      @if (canGoBack) {\n        <button\n          #backButton\n          praxisIconButton=\"arrow_back\"\n          size=\"compact\"\n          type=\"button\"\n          class=\"pfx-surface-drawer__back\"\n          [attr.aria-label]=\"backLabel\"\n          [matTooltip]=\"backLabel\"\n          (click)=\"onBack?.()\"\n        ></button>\n      }\n      <div class=\"pfx-surface-drawer__title-block\">\n        @if (titleIcon) {\n          <mat-icon class=\"pfx-surface-drawer__title-icon\" [praxisIcon]=\"titleIcon\"></mat-icon>\n        }\n        <div class=\"pfx-surface-drawer__copy\">\n          @if (title) {\n            <h2 class=\"pfx-surface-drawer__title\" [id]=\"titleId\">{{ title }}</h2>\n          }\n          @if (subtitle) {\n            <p class=\"pfx-surface-drawer__subtitle\" [id]=\"subtitleId\">{{ subtitle }}</p>\n          }\n        </div>\n      </div>\n      <button\n        praxisIconButton=\"close\"\n        size=\"compact\"\n        type=\"button\"\n        class=\"pfx-surface-drawer__close\"\n        [attr.aria-label]=\"closeLabel\"\n        [matTooltip]=\"closeLabel\"\n        (click)=\"onClose?.()\"\n      ></button>\n    </header>\n  }\n\n  <section #body class=\"pfx-surface-drawer__body\">\n    <ng-template #contentHost></ng-template>\n  </section>\n</div>\n", styles: [":host{display:block;height:100%;width:100%;min-width:0;flex:1 1 auto}.pfx-surface-drawer{display:grid;grid-template-rows:auto 1fr;height:100%;min-width:0;max-width:100%;overflow:hidden;background:var(--md-sys-color-surface-container, #fff);color:var(--md-sys-color-on-surface, #111);border-left:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));border-radius:var(--pfx-side-panel-border-radius, 0);box-shadow:var(--pfx-side-panel-elevation, var(--md-sys-elevation-level2, 0 8px 24px rgba(0, 0, 0, .16)));width:var(--pfx-side-panel-width, 720px);transition:width var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1)),box-shadow var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1))}.pfx-surface-drawer.use-host-width{width:100%;max-width:100%}.pfx-surface-drawer.width-narrow{width:var(--pfx-side-panel-width, 420px)}.pfx-surface-drawer.width-default{width:var(--pfx-side-panel-width, 720px)}.pfx-surface-drawer.width-wide{width:var(--pfx-side-panel-width, 960px)}.pfx-surface-drawer.width-full{width:min(100vw,var(--pfx-side-panel-max-width, 100vw))}.pfx-surface-drawer__header{display:flex;align-items:flex-start;gap:var(--pfx-side-panel-header-gap, 12px);min-height:var(--pfx-side-panel-header-height, 64px);padding:var(--pfx-side-panel-header-padding-y, 16px) var(--pfx-side-panel-header-padding-x, 20px);box-sizing:border-box;border-bottom:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));background:var(--md-sys-color-surface-container-high, #f7f7f7)}.pfx-surface-drawer__title-block{display:flex;align-items:flex-start;gap:12px;min-width:0;flex:1 1 auto}.pfx-surface-drawer__title-icon{flex:0 0 auto;display:grid;place-items:center;width:36px;height:36px;margin-top:1px;border-radius:10px;background:var(--md-sys-color-primary-container, rgba(47, 78, 178, .12));color:var(--md-sys-color-primary, currentColor)}.pfx-surface-drawer__copy{min-width:0}.pfx-surface-drawer__title,.pfx-surface-drawer__subtitle{margin:0}.pfx-surface-drawer__title{font-size:1.125rem;font-weight:650;line-height:1.35}.pfx-surface-drawer__subtitle{margin-top:6px;color:var(--md-sys-color-on-surface-variant, rgba(0, 0, 0, .64));font-size:.875rem;line-height:1.45;text-wrap:pretty}.pfx-surface-drawer__close{flex:0 0 auto}.pfx-surface-drawer__back{flex:0 0 auto;margin-top:1px}.pfx-surface-drawer__body{min-height:0;overflow:auto;padding:var(--pfx-side-panel-body-padding, 16px);background:var(--md-sys-color-surface, #fff)}@media(prefers-reduced-motion:reduce){.pfx-surface-drawer{transition:none}}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: i2.NgStyle, selector: "[ngStyle]", inputs: ["ngStyle"] }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i3.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i4$1.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "directive", type: CdkTrapFocus, selector: "[cdkTrapFocus]", inputs: ["cdkTrapFocus", "cdkTrapFocusAutoCapture"], exportAs: ["cdkTrapFocus"] }, { kind: "component", type: PraxisIconButtonComponent, selector: "button[praxisIconButton]", inputs: ["praxisIconButton", "size", "appearance", "presentation", "pressed", "busy"] }, { kind: "directive", type: PraxisIconDirective, selector: "mat-icon[praxisIcon]", inputs: ["praxisIcon"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: SurfaceDrawerComponent, decorators: [{
             type: Component,
@@ -1882,10 +2061,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
                         CdkTrapFocus,
                         PraxisIconButtonComponent,
                         PraxisIconDirective,
-                    ], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div\n  class=\"pfx-surface-drawer\"\n  [class.has-header]=\"hasHeader\"\n  [class.width-narrow]=\"widthClass === 'width-narrow'\"\n  [class.width-default]=\"widthClass === 'width-default'\"\n  [class.width-wide]=\"widthClass === 'width-wide'\"\n  [class.width-full]=\"widthClass === 'width-full'\"\n  [class.use-host-width]=\"useHostWidth\"\n  [ngClass]=\"hostClasses\"\n  [ngStyle]=\"hostCssVars\"\n  role=\"dialog\"\n  aria-modal=\"true\"\n  [attr.aria-labelledby]=\"hasHeader ? titleId : null\"\n  cdkTrapFocus\n  cdkTrapFocusAutoCapture\n>\n  @if (hasHeader) {\n    <header class=\"pfx-surface-drawer__header\">\n      <div class=\"pfx-surface-drawer__title-block\">\n        @if (titleIcon) {\n          <mat-icon class=\"pfx-surface-drawer__title-icon\" [praxisIcon]=\"titleIcon\"></mat-icon>\n        }\n        <div class=\"pfx-surface-drawer__copy\">\n          @if (title) {\n            <h2 class=\"pfx-surface-drawer__title\" [id]=\"titleId\">{{ title }}</h2>\n          }\n          @if (subtitle) {\n            <p class=\"pfx-surface-drawer__subtitle\">{{ subtitle }}</p>\n          }\n        </div>\n      </div>\n      <button\n        praxisIconButton=\"close\"\n        size=\"compact\"\n        type=\"button\"\n        class=\"pfx-surface-drawer__close\"\n        [attr.aria-label]=\"closeLabel\"\n        [matTooltip]=\"closeLabel\"\n        (click)=\"onClose?.()\"\n      ></button>\n    </header>\n  }\n\n  <section class=\"pfx-surface-drawer__body\">\n    <ng-template #contentHost></ng-template>\n  </section>\n</div>\n", styles: [":host{display:block;height:100%;width:100%;min-width:0;flex:1 1 auto}.pfx-surface-drawer{display:grid;grid-template-rows:auto 1fr;height:100%;min-width:0;max-width:100%;overflow:hidden;background:var(--md-sys-color-surface-container, #fff);color:var(--md-sys-color-on-surface, #111);border-left:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));border-radius:var(--pfx-side-panel-border-radius, 0);box-shadow:var(--pfx-side-panel-elevation, var(--md-sys-elevation-level2, 0 8px 24px rgba(0, 0, 0, .16)));width:var(--pfx-side-panel-width, 720px);transition:width var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1)),box-shadow var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1))}.pfx-surface-drawer.use-host-width{width:100%;max-width:100%}.pfx-surface-drawer.width-narrow{width:var(--pfx-side-panel-width, 420px)}.pfx-surface-drawer.width-default{width:var(--pfx-side-panel-width, 720px)}.pfx-surface-drawer.width-wide{width:var(--pfx-side-panel-width, 960px)}.pfx-surface-drawer.width-full{width:min(100vw,var(--pfx-side-panel-max-width, 100vw))}.pfx-surface-drawer__header{display:flex;align-items:center;gap:var(--pfx-side-panel-header-gap, 8px);min-height:var(--pfx-side-panel-header-height, 64px);padding:0 var(--pfx-side-panel-header-padding-x, 16px);border-bottom:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));background:var(--md-sys-color-surface-container-high, #f7f7f7)}.pfx-surface-drawer__title-block{display:flex;align-items:flex-start;gap:10px;min-width:0;flex:1 1 auto}.pfx-surface-drawer__title-icon{color:var(--md-sys-color-primary, currentColor)}.pfx-surface-drawer__copy{min-width:0}.pfx-surface-drawer__title,.pfx-surface-drawer__subtitle{margin:0}.pfx-surface-drawer__title{font-size:1rem;font-weight:600}.pfx-surface-drawer__subtitle{margin-top:4px;color:var(--md-sys-color-on-surface-variant, rgba(0, 0, 0, .64));font-size:.875rem}.pfx-surface-drawer__body{min-height:0;overflow:auto;padding:var(--pfx-side-panel-body-padding, 16px);background:var(--md-sys-color-surface, #fff)}@media(prefers-reduced-motion:reduce){.pfx-surface-drawer{transition:none}}\n"] }]
+                    ], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div\n  class=\"pfx-surface-drawer\"\n  [class.has-header]=\"hasHeader\"\n  [class.width-narrow]=\"widthClass === 'width-narrow'\"\n  [class.width-default]=\"widthClass === 'width-default'\"\n  [class.width-wide]=\"widthClass === 'width-wide'\"\n  [class.width-full]=\"widthClass === 'width-full'\"\n  [class.use-host-width]=\"useHostWidth\"\n  [ngClass]=\"hostClasses\"\n  [ngStyle]=\"hostCssVars\"\n  role=\"dialog\"\n  aria-modal=\"true\"\n  [attr.aria-labelledby]=\"hasHeader ? titleId : null\"\n  [attr.aria-describedby]=\"subtitle ? subtitleId : null\"\n  cdkTrapFocus\n  cdkTrapFocusAutoCapture\n>\n  @if (hasHeader) {\n    <header class=\"pfx-surface-drawer__header\">\n      @if (canGoBack) {\n        <button\n          #backButton\n          praxisIconButton=\"arrow_back\"\n          size=\"compact\"\n          type=\"button\"\n          class=\"pfx-surface-drawer__back\"\n          [attr.aria-label]=\"backLabel\"\n          [matTooltip]=\"backLabel\"\n          (click)=\"onBack?.()\"\n        ></button>\n      }\n      <div class=\"pfx-surface-drawer__title-block\">\n        @if (titleIcon) {\n          <mat-icon class=\"pfx-surface-drawer__title-icon\" [praxisIcon]=\"titleIcon\"></mat-icon>\n        }\n        <div class=\"pfx-surface-drawer__copy\">\n          @if (title) {\n            <h2 class=\"pfx-surface-drawer__title\" [id]=\"titleId\">{{ title }}</h2>\n          }\n          @if (subtitle) {\n            <p class=\"pfx-surface-drawer__subtitle\" [id]=\"subtitleId\">{{ subtitle }}</p>\n          }\n        </div>\n      </div>\n      <button\n        praxisIconButton=\"close\"\n        size=\"compact\"\n        type=\"button\"\n        class=\"pfx-surface-drawer__close\"\n        [attr.aria-label]=\"closeLabel\"\n        [matTooltip]=\"closeLabel\"\n        (click)=\"onClose?.()\"\n      ></button>\n    </header>\n  }\n\n  <section #body class=\"pfx-surface-drawer__body\">\n    <ng-template #contentHost></ng-template>\n  </section>\n</div>\n", styles: [":host{display:block;height:100%;width:100%;min-width:0;flex:1 1 auto}.pfx-surface-drawer{display:grid;grid-template-rows:auto 1fr;height:100%;min-width:0;max-width:100%;overflow:hidden;background:var(--md-sys-color-surface-container, #fff);color:var(--md-sys-color-on-surface, #111);border-left:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));border-radius:var(--pfx-side-panel-border-radius, 0);box-shadow:var(--pfx-side-panel-elevation, var(--md-sys-elevation-level2, 0 8px 24px rgba(0, 0, 0, .16)));width:var(--pfx-side-panel-width, 720px);transition:width var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1)),box-shadow var(--pfx-side-panel-motion-duration-enter, .22s) var(--pfx-side-panel-motion-easing-enter, cubic-bezier(.2, 0, 0, 1))}.pfx-surface-drawer.use-host-width{width:100%;max-width:100%}.pfx-surface-drawer.width-narrow{width:var(--pfx-side-panel-width, 420px)}.pfx-surface-drawer.width-default{width:var(--pfx-side-panel-width, 720px)}.pfx-surface-drawer.width-wide{width:var(--pfx-side-panel-width, 960px)}.pfx-surface-drawer.width-full{width:min(100vw,var(--pfx-side-panel-max-width, 100vw))}.pfx-surface-drawer__header{display:flex;align-items:flex-start;gap:var(--pfx-side-panel-header-gap, 12px);min-height:var(--pfx-side-panel-header-height, 64px);padding:var(--pfx-side-panel-header-padding-y, 16px) var(--pfx-side-panel-header-padding-x, 20px);box-sizing:border-box;border-bottom:1px solid var(--md-sys-color-outline-variant, rgba(0, 0, 0, .12));background:var(--md-sys-color-surface-container-high, #f7f7f7)}.pfx-surface-drawer__title-block{display:flex;align-items:flex-start;gap:12px;min-width:0;flex:1 1 auto}.pfx-surface-drawer__title-icon{flex:0 0 auto;display:grid;place-items:center;width:36px;height:36px;margin-top:1px;border-radius:10px;background:var(--md-sys-color-primary-container, rgba(47, 78, 178, .12));color:var(--md-sys-color-primary, currentColor)}.pfx-surface-drawer__copy{min-width:0}.pfx-surface-drawer__title,.pfx-surface-drawer__subtitle{margin:0}.pfx-surface-drawer__title{font-size:1.125rem;font-weight:650;line-height:1.35}.pfx-surface-drawer__subtitle{margin-top:6px;color:var(--md-sys-color-on-surface-variant, rgba(0, 0, 0, .64));font-size:.875rem;line-height:1.45;text-wrap:pretty}.pfx-surface-drawer__close{flex:0 0 auto}.pfx-surface-drawer__back{flex:0 0 auto;margin-top:1px}.pfx-surface-drawer__body{min-height:0;overflow:auto;padding:var(--pfx-side-panel-body-padding, 16px);background:var(--md-sys-color-surface, #fff)}@media(prefers-reduced-motion:reduce){.pfx-surface-drawer{transition:none}}\n"] }]
         }], ctorParameters: () => [{ type: i0.ChangeDetectorRef }, { type: i1$2.PraxisI18nService }], propDecorators: { contentHost: [{
                 type: ViewChild,
                 args: ['contentHost', { read: ViewContainerRef, static: true }]
+            }], body: [{
+                type: ViewChild,
+                args: ['body', { read: ElementRef }]
+            }], backButton: [{
+                type: ViewChild,
+                args: ['backButton', { read: ElementRef }]
             }] } });
 
 function buildSurfaceRuntime(ref) {
@@ -1894,8 +2079,15 @@ function buildSurfaceRuntime(ref) {
         result$: ref.result$,
         close: (result) => ref.close?.(result),
         emitResult: (result) => ref.emitResult?.(result),
+        complete: (outcome) => ref.complete?.(outcome),
         updateTitle: (title) => ref.updateTitle?.(title),
         updateSize: (preset) => ref.updateSize?.(preset),
+        navigation$: ref.navigation$,
+        push: (frame) => ref.push?.(frame),
+        replace: (frame) => ref.replace?.(frame),
+        back: () => ref.back?.(),
+        canGoBack: () => ref.canGoBack?.() ?? false,
+        setCanLeave: (guard) => ref.setCanLeave?.(guard),
     };
 }
 function enrichSurfaceContentInputs(inputs, ref) {
@@ -1941,7 +2133,159 @@ function providePraxisSurfaceDrawerBridge() {
             useFactory: (service, injector, layerScale) => ({
                 open: (opts) => {
                     layerScale.ensureInstalled();
-                    return service.openHost({
+                    const sessionId = `${opts.id}:${Date.now().toString(36)}`;
+                    const navigationState = new BehaviorSubject({
+                        sessionId,
+                        activeFrameId: opts.id,
+                        depth: 1,
+                        canGoBack: false,
+                    });
+                    let panel = null;
+                    let activeRef = null;
+                    const frameRefs = [];
+                    const createContent = (frame, mode, runtimeRef) => {
+                        if (!panel)
+                            return null;
+                        const contentInputs = enrichSurfaceContentInputs(frame.content.inputs, runtimeRef);
+                        const contentInjector = Injector.create({
+                            providers: [
+                                { provide: BASE_SIDE_PANEL_DATA, useValue: contentInputs },
+                                { provide: BASE_SIDE_PANEL_REF, useValue: runtimeRef },
+                                { provide: SURFACE_DRAWER_CONTENT_DATA, useValue: contentInputs },
+                                { provide: SURFACE_DRAWER_REF, useValue: runtimeRef },
+                            ],
+                            parent: injector,
+                        });
+                        if (mode === 'initial') {
+                            return panel.initializeFrame(frame, contentInjector, contentInputs);
+                        }
+                        if (mode === 'push') {
+                            return panel.pushFrame(frame, contentInjector, contentInputs);
+                        }
+                        return panel.replaceFrame(frame, contentInjector, contentInputs);
+                    };
+                    const publishNavigationState = () => {
+                        if (!panel)
+                            return;
+                        navigationState.next({
+                            sessionId,
+                            activeFrameId: panel.activeFrameId,
+                            depth: panel.navigationDepth,
+                            canGoBack: panel.canGoBack,
+                        });
+                    };
+                    const closeFrameRef = (frameRef, result) => {
+                        const runtime = frameRef;
+                        runtime.__closeFrame?.(result);
+                    };
+                    const navigateBack = async (result) => {
+                        const leaving = frameRefs[frameRefs.length - 1];
+                        const moved = await panel?.backFrame() ?? false;
+                        if (!moved)
+                            return false;
+                        if (leaving) {
+                            frameRefs.pop();
+                            closeFrameRef(leaving, result ?? { type: 'back' });
+                        }
+                        publishNavigationState();
+                        return true;
+                    };
+                    const createFrameRef = (frameId) => {
+                        const closedSubject = new Subject();
+                        const resultSubject = new Subject();
+                        let closed = false;
+                        let cleanup = null;
+                        const frameRef = {
+                            frameId,
+                            closed$: closedSubject.asObservable(),
+                            result$: resultSubject.asObservable(),
+                            navigation$: navigationState.asObservable(),
+                            close: (result) => { void navigateBack(result); },
+                            emitResult: (result) => resultSubject.next(result),
+                            complete: (outcome) => {
+                                resultSubject.next(outcome);
+                                void navigateBack(outcome);
+                            },
+                            updateTitle: (title) => activeRef?.updateTitle?.(title),
+                            updateSize: (preset) => activeRef?.updateSize?.(preset),
+                            push: (frame) => activeRef?.push?.(frame) ?? Promise.resolve(null),
+                            replace: (frame) => activeRef?.replace?.(frame) ?? Promise.resolve(null),
+                            back: () => activeRef?.back?.() ?? Promise.resolve(false),
+                            canGoBack: () => activeRef?.canGoBack?.() ?? false,
+                            setCanLeave: (guard) => activeRef?.setCanLeave?.(guard),
+                            __closeFrame: (result) => {
+                                if (closed)
+                                    return;
+                                closed = true;
+                                cleanup?.();
+                                cleanup = null;
+                                closedSubject.next(result);
+                                closedSubject.complete();
+                                resultSubject.complete();
+                            },
+                            __setCleanup: (nextCleanup) => {
+                                cleanup?.();
+                                cleanup = nextCleanup;
+                            },
+                        };
+                        return frameRef;
+                    };
+                    const configureRef = (ref) => {
+                        activeRef = ref;
+                        if (ref.navigation$) {
+                            return ref;
+                        }
+                        ref.navigation$ = navigationState.asObservable();
+                        ref.canGoBack = () => panel?.canGoBack ?? false;
+                        ref.setCanLeave = (guard) => panel?.setActiveCanLeave(guard);
+                        ref.push = async (frame) => {
+                            const frameRef = createFrameRef(frame.id);
+                            const contentRef = await createContent(frame, 'push', frameRef);
+                            if (!contentRef)
+                                return null;
+                            frameRefs.push(frameRef);
+                            frameRef.__setCleanup?.(bindSurfaceContentSelectionResults(contentRef.instance, frameRef));
+                            publishNavigationState();
+                            return frameRef;
+                        };
+                        ref.replace = async (frame) => {
+                            if ((panel?.navigationDepth ?? 1) === 1) {
+                                const rootRef = frameRefs[0]
+                                    ?? ref;
+                                const contentRef = await createContent(frame, 'replace', rootRef);
+                                if (!contentRef)
+                                    return null;
+                                Object.defineProperty(rootRef, 'frameId', {
+                                    configurable: true,
+                                    value: frame.id,
+                                });
+                                bindSurfaceContentSelectionResults(contentRef.instance, rootRef);
+                                publishNavigationState();
+                                return rootRef;
+                            }
+                            const frameRef = createFrameRef(frame.id);
+                            const contentRef = await createContent(frame, 'replace', frameRef);
+                            if (!contentRef)
+                                return null;
+                            const replaced = frameRefs.pop();
+                            if (replaced)
+                                closeFrameRef(replaced, { type: 'replace' });
+                            frameRefs.push(frameRef);
+                            frameRef.__setCleanup?.(bindSurfaceContentSelectionResults(contentRef.instance, frameRef));
+                            publishNavigationState();
+                            return frameRef;
+                        };
+                        ref.back = () => navigateBack();
+                        if (frameRefs.length === 0) {
+                            Object.defineProperty(ref, 'frameId', {
+                                configurable: true,
+                                value: opts.id,
+                            });
+                            frameRefs.push(ref);
+                        }
+                        return ref;
+                    };
+                    const result = service.openHost({
                         component: SurfaceDrawerComponent,
                         config: {
                             id: opts.id,
@@ -1969,26 +2313,32 @@ function providePraxisSurfaceDrawerBridge() {
                             minHeight: opts.minHeight,
                             maxHeight: opts.maxHeight,
                         },
-                        createRef: (overlayRef) => new BaseSidePanelOverlayRef(overlayRef),
+                        createRef: (overlayRef) => {
+                            const ref = new BaseSidePanelOverlayRef(overlayRef);
+                            return configureRef(ref);
+                        },
                         attach: (panelRef, ref) => {
-                            const contentInputs = enrichSurfaceContentInputs(opts.content.inputs, ref);
-                            panelRef.instance.title = opts.title;
-                            panelRef.instance.titleIcon = opts.titleIcon;
-                            panelRef.instance.subtitle = opts.subtitle;
+                            panel = panelRef.instance;
+                            configureRef(ref);
                             panelRef.instance.widthPreset = opts.widthPreset ?? 'default';
                             panelRef.instance.useHostWidth = !!(opts.width ||
                                 opts.minWidth ||
                                 opts.maxWidth);
-                            panelRef.instance.onClose = () => ref.close({ type: 'close' });
+                            panelRef.instance.onClose = () => {
+                                void panelRef.instance.canCloseSession().then((allowed) => {
+                                    if (allowed)
+                                        ref.close({ type: 'close' });
+                                });
+                            };
+                            panelRef.instance.onBack = () => { void activeRef?.back?.(); };
                             ref.bindTitleUpdater((title) => panelRef.instance.setTitle(title));
-                            const contentInjector = Injector.create({
-                                providers: [
-                                    { provide: BASE_SIDE_PANEL_DATA, useValue: contentInputs },
-                                    { provide: BASE_SIDE_PANEL_REF, useValue: ref },
-                                ],
-                                parent: injector,
-                            });
-                            const contentRef = panelRef.instance.attachContent(opts.content.component, contentInjector, contentInputs);
+                            const contentRef = createContent({
+                                id: opts.id,
+                                title: opts.title,
+                                titleIcon: opts.titleIcon,
+                                subtitle: opts.subtitle,
+                                content: opts.content,
+                            }, 'initial', frameRefs[0] ?? ref);
                             const unbindSelectionResults = contentRef?.instance
                                 ? bindSurfaceContentSelectionResults(contentRef.instance, ref)
                                 : null;
@@ -1997,10 +2347,35 @@ function providePraxisSurfaceDrawerBridge() {
                             }
                             panelRef.changeDetectorRef.detectChanges();
                         },
-                        createCloser: (ref) => (reason = 'close') => ref.close({ type: reason }),
-                        onBackdrop: (ref) => ref.close({ type: 'backdrop' }),
-                        onEsc: (ref) => ref.close({ type: 'esc' }),
+                        createCloser: (ref) => (reason = 'close') => {
+                            void panel?.canCloseSession().then((allowed) => {
+                                if (allowed)
+                                    ref.close({ type: reason });
+                            });
+                        },
+                        onBackdrop: (ref) => {
+                            void panel?.canCloseSession().then((allowed) => {
+                                if (allowed)
+                                    ref.close({ type: 'backdrop' });
+                            });
+                        },
+                        onEsc: (ref) => {
+                            void panel?.canCloseSession().then((allowed) => {
+                                if (allowed)
+                                    ref.close({ type: 'esc' });
+                            });
+                        },
+                    });
+                    result.closed$.subscribe(() => {
+                        while (frameRefs.length > 1) {
+                            closeFrameRef(frameRefs.pop(), { type: 'close' });
+                        }
+                        frameRefs.length = 0;
+                        navigationState.complete();
+                        panel = null;
+                        activeRef = null;
                     });
+                    return result;
                 },
             }),
             deps: [BaseSidePanelService, Injector, PraxisLayerScaleStyleService],

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@praxisui/settings-panel",
-  "version": "9.0.4-rc.3",
+  "version": "9.0.4-rc.31",
   "description": "Settings panel for Praxis UI libraries: open editors for configuration at runtime and persist settings.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
     "@angular/cdk": "^21.0.0",
     "@angular/material": "^21.0.0",
-    "@praxisui/ai": "^9.0.4-rc.3",
-    "@praxisui/core": "^9.0.4-rc.3",
-    "@praxisui/dynamic-fields": "^9.0.4-rc.3",
+    "@praxisui/ai": "^9.0.4-rc.31",
+    "@praxisui/core": "^9.0.4-rc.31",
+    "@praxisui/dynamic-fields": "^9.0.4-rc.31",
     "rxjs": "~7.8.0"
   },
   "dependencies": {

package/types/praxisui-settings-panel.d.ts

@@ -1,9 +1,9 @@
 import * as i0 from '@angular/core';
-import { Type, Injector, ComponentRef, Provider, ChangeDetectorRef, ElementRef, InjectionToken, OnDestroy, OnInit, AfterViewInit, ViewContainerRef } from '@angular/core';
+import { Type, Injector, ComponentRef, Provider, OnDestroy, ChangeDetectorRef, ElementRef, InjectionToken, OnInit, AfterViewInit, ViewContainerRef } from '@angular/core';
 import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject } from 'rxjs';
 import { OverlayRef, Overlay, OverlayContainer } from '@angular/cdk/overlay';
-import { PraxisI18nService, GlobalConfig, FormConfig, FormValueChangeEvent, AiCapability, AiCapabilityCategory, AiCapabilityCatalog, AiValueKind, ComponentAuthoringManifest, ComponentDocMeta } from '@praxisui/core';
+import { SurfaceOutcome, PraxisI18nService, SurfaceDrawerNavigationFrame, SurfaceDrawerNavigationGuard, GlobalConfig, FormConfig, FormValueChangeEvent, AiCapability, AiCapabilityCategory, AiCapabilityCatalog, AiValueKind, ComponentAuthoringManifest, ComponentDocMeta } from '@praxisui/core';
 import { MatDialog } from '@angular/material/dialog';
 import { MatSnackBar } from '@angular/material/snack-bar';
 import { AiProviderCatalogItem } from '@praxisui/ai';
@@ -224,6 +224,7 @@ interface BaseSidePanelRef<T = unknown> {
     }>;
     close(result?: BaseSidePanelResult<T>): void;
     emitResult?(result: BaseSidePanelResult<T>): void;
+    complete?(outcome: SurfaceOutcome<T>): void;
     updateTitle?(title: string): void;
     updateSize?(size: SidePanelWidthPreset | string | {
         width?: string;
@@ -260,6 +261,7 @@ declare class BaseSidePanelOverlayRef<T = unknown> implements BaseSidePanelRef<T
     private overlayRef;
     private titleUpdater?;
     private sizePersistor?;
+    private terminalOutcomeEmitted;
     readonly closed$: rxjs.Observable<BaseSidePanelResult<T> | undefined>;
     readonly result$: rxjs.Observable<BaseSidePanelResult<T>>;
     readonly sizeChanged$: rxjs.Observable<{
@@ -269,6 +271,7 @@ declare class BaseSidePanelOverlayRef<T = unknown> implements BaseSidePanelRef<T
     bindTitleUpdater(fn: (title: string) => void): void;
     bindSizePersistor(fn: (width: string) => void): void;
     emitResult(result: BaseSidePanelResult<T>): void;
+    complete(outcome: SurfaceOutcome<T>): void;
     updateTitle(title: string): void;
     updateSize(size: string | {
         width?: string;
@@ -350,7 +353,7 @@ declare function providePraxisSettingsPanelBridge(): Provider[];
 
 declare function providePraxisSurfaceDrawerBridge(): Provider[];
 
-declare class SurfaceDrawerComponent {
+declare class SurfaceDrawerComponent implements OnDestroy {
     private readonly cdr;
     private readonly i18n;
     title: string;
@@ -360,18 +363,42 @@ declare class SurfaceDrawerComponent {
     useHostWidth: boolean;
     theme: SidePanelThemeContract | null;
     onClose?: () => void;
+    onBack?: () => void;
     private static nextId;
     titleId: string;
+    subtitleId: string;
     contentRef?: ComponentRef<any>;
     private contentHost;
+    private body?;
+    private backButton?;
+    private frames;
     constructor(cdr: ChangeDetectorRef, i18n: PraxisI18nService);
     get hostClasses(): string[];
     get hostCssVars(): Record<string, string>;
     get closeLabel(): string;
+    get backLabel(): string;
+    get canGoBack(): boolean;
+    get navigationDepth(): number;
+    get activeFrameId(): string;
     get hasHeader(): boolean;
     get widthClass(): string | null;
     setTitle(title: string): void;
+    ngOnDestroy(): void;
     attachContent(component: Type<any>, injector: Injector, inputs?: Record<string, unknown>): ComponentRef<any>;
+    initializeFrame(definition: SurfaceDrawerNavigationFrame, injector: Injector, inputs?: Record<string, unknown>): ComponentRef<any>;
+    pushFrame(definition: SurfaceDrawerNavigationFrame, injector: Injector, inputs?: Record<string, unknown>): ComponentRef<any>;
+    replaceFrame(definition: SurfaceDrawerNavigationFrame, injector: Injector, inputs?: Record<string, unknown>): Promise<ComponentRef<any> | null>;
+    backFrame(): Promise<boolean>;
+    setActiveCanLeave(guard: SurfaceDrawerNavigationGuard | null): void;
+    canCloseSession(): Promise<boolean>;
+    private createFrame;
+    private captureActiveFrameState;
+    private detachActiveView;
+    private removeActiveFrame;
+    private destroyAllFrames;
+    private canLeaveActiveFrame;
+    private applyFrameHeader;
+    private focusNavigationControl;
     private applyInputs;
     private resolveSupportedInputs;
     static ɵfac: i0.ɵɵFactoryDeclaration<SurfaceDrawerComponent, never>;