structra-ui 0.2.54 → 0.2.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structra-ui",
-  "version": "0.2.54",
+  "version": "0.2.56",
   "description": "Biblioteca de componentes Angular da StructraLab (UI reutilizável).",
   "homepage": "https://structralab.com/",
   "license": "MIT",

package/types/structra-ui.d.ts

@@ -1040,6 +1040,7 @@ declare class SwitchFieldComponent extends BooleanFieldDirective implements Afte
 declare class DropdownBaseComponent {
     private readonly appTheme;
     private readonly overlay;
+    private connectedOverlay?;
     /**
      * O overlay do CDK fica sob `body`; sem estas classes, `var(--app-color-*)` cai no `:root`.
      * Tem de ser **array**: uma única string com espaço quebra `classList.add` e as classes não aplicam.
@@ -1068,11 +1069,18 @@ declare class DropdownBaseComponent {
     /** Empurra o overlay para caber no viewport quando há espaço insuficiente. */
     pushConnectedOverlay: boolean;
     /**
-     * Por omissão **reposiciona** o painel quando o viewport ou contentores com scroll se movem
-     * (mesma ideia que submenus em `app-menu-list`). Sobrescrever só em casos especiais (ex.: fechar ao scroll).
+     * `true`: mantém a última posição escolhida e só reancora ao rect do gatilho — evita flip/push bruscos
+     * quando o conteúdo do painel muda (ex.: multiselect que reordena opções ao seleccionar).
+     */
+    lockConnectedOverlayPosition: boolean;
+    /**
+     * Sobrescrever a estratégia CDK (ex.: `noop()` em cenários de teste).
+     * Por omissão: **reposiciona** em desktop; em ambientes sem `(hover: hover)` usa **fecho ao scroll**
+     * da página (lista não fica desalinhada ao rolar o formulário no telemóvel).
      */
     scrollStrategy: ScrollStrategy | null;
-    readonly defaultScrollStrategy: _angular_cdk_overlay.RepositionScrollStrategy;
+    readonly repositionScrollStrategy: _angular_cdk_overlay.RepositionScrollStrategy;
+    readonly closeOnOuterScrollStrategy: _angular_cdk_overlay.CloseScrollStrategy;
     get effectiveScrollStrategy(): ScrollStrategy;
     /**
      * `true`: painel sem fundo/borda/sombra próprios — o conteúdo (ex.: `app-menu-list`) define o chrome.
@@ -1090,12 +1098,17 @@ declare class DropdownBaseComponent {
     onOverlayKeydown(ev: KeyboardEvent): void;
     setOpen(next: boolean): void;
     toggle(): void;
+    /**
+     * Após o gatilho ou o painel mudarem de layout com o overlay aberto (ex.: teclado / multiselect).
+     */
+    scheduleOverlayPositionSync(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<DropdownBaseComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DropdownBaseComponent, "app-dropdown-base", never, { "open": { "alias": "open"; "required": false; }; "panelTemplate": { "alias": "panelTemplate"; "required": true; }; "panelWidthPx": { "alias": "panelWidthPx"; "required": false; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; }; "hasBackdrop": { "alias": "hasBackdrop"; "required": false; }; "connectedPositions": { "alias": "connectedPositions"; "required": false; }; "pushConnectedOverlay": { "alias": "pushConnectedOverlay"; "required": false; }; "scrollStrategy": { "alias": "scrollStrategy"; "required": false; }; "bareOverlayPanel": { "alias": "bareOverlayPanel"; "required": false; }; }, { "openChange": "openChange"; }, never, ["[appDropdownTrigger]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DropdownBaseComponent, "app-dropdown-base", never, { "open": { "alias": "open"; "required": false; }; "panelTemplate": { "alias": "panelTemplate"; "required": true; }; "panelWidthPx": { "alias": "panelWidthPx"; "required": false; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; }; "hasBackdrop": { "alias": "hasBackdrop"; "required": false; }; "connectedPositions": { "alias": "connectedPositions"; "required": false; }; "pushConnectedOverlay": { "alias": "pushConnectedOverlay"; "required": false; }; "lockConnectedOverlayPosition": { "alias": "lockConnectedOverlayPosition"; "required": false; }; "scrollStrategy": { "alias": "scrollStrategy"; "required": false; }; "bareOverlayPanel": { "alias": "bareOverlayPanel"; "required": false; }; }, { "openChange": "openChange"; }, never, ["[appDropdownTrigger]"], true, never>;
     static ngAcceptInputType_open: unknown;
     static ngAcceptInputType_closeOnEscape: unknown;
     static ngAcceptInputType_hasBackdrop: unknown;
     static ngAcceptInputType_pushConnectedOverlay: unknown;
+    static ngAcceptInputType_lockConnectedOverlayPosition: unknown;
     static ngAcceptInputType_bareOverlayPanel: unknown;
 }
 
@@ -1255,9 +1268,15 @@ declare class MultiselectFieldComponent extends DropdownMultiOptionFieldBase imp
     optionsPanelTpl: TemplateRef<unknown>;
     private readonly dropdownTriggerRootRef;
     private readonly nativeInputRef?;
+    private readonly dropdownBase?;
     panelOpen: boolean;
     panelOverlayWidth: number;
     private scrollLoadTimer;
+    /**
+     * Sem hover primário (telemóvel): o CDK volta a avaliar encaixe quando a lista reordena e o painel
+     * pode «saltar» por cima do campo — `lockPosition` mantém ancoragem ao fundo do gatilho.
+     */
+    get lockOverlayWhileOpen(): boolean;
     ngAfterViewInit(): void;
     writeValue(value: unknown[] | null): void;
     protected afterWriteValue(_value: unknown[]): void;
@@ -1332,6 +1351,11 @@ declare class DropdownSearchFieldComponent extends DropdownOptionFieldBase imple
     get isLockedSelectionDisplay(): boolean;
     /** `readonly` nativo: prop do campo ou bloqueio de exibição da seleção. */
     get isNativeInputReadonly(): boolean;
+    /**
+     * Paginação / API pode devolver o mesmo `value` em mais do que uma linha — `track` só por valor
+     * duplica chaves (aviso NG0955). O índice na vista torna a chave única sem alterar select/multiselect.
+     */
+    trackOption(index: number, opt: UiSelectOption<unknown>): unknown;
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     onDropdownOpenChange(next: boolean, openMode?: DropdownSearchOpenMode): void;
@@ -3090,9 +3114,12 @@ declare class DrawerComponent implements OnChanges, OnDestroy {
     static ngAcceptInputType_showCloseButton: unknown;
 }
 
-declare class MenuListComponent<T = string> implements OnChanges {
+declare class MenuListComponent<T = string> implements OnChanges, AfterViewInit {
     private readonly cdr;
+    private readonly injector;
+    private readonly destroyRef;
     readonly appTheme: i0.InputSignal<"blue" | "green" | "purple" | "orange" | "white" | "gray" | "sepia" | "black" | AppTheme | undefined>;
+    private bodyRouteSyncGen;
     items: readonly MenuNodeItem<T>[];
     menuId: string;
     dense: boolean;
@@ -3109,30 +3136,52 @@ declare class MenuListComponent<T = string> implements OnChanges {
      */
     persistGroupExpansion: boolean;
     searchable: boolean;
+    /**
+     * Com `searchable`, se `true` limpa o campo e repõe a lista completa após {@link itemSelect}.
+     */
+    limparAposPesquisar: boolean;
     searchPlaceholder: string;
     readonly itemSelect: EventEmitter<T>;
     readonly closeRequest: EventEmitter<void>;
     readonly submenuBack: EventEmitter<void>;
     readonly groupToggled: i0.OutputEmitterRef<number>;
+    /** Ver {@link MenuListBodyComponent.selectionScrollHint}. */
+    readonly selectionScrollHint: i0.OutputEmitterRef<void>;
     private body?;
     searchQuery: string;
+    constructor();
+    ngAfterViewInit(): void;
     displayItems: MenuNodeItem<T>[];
     get showSearchField(): boolean;
     get expandAllGroupsWhenSearching(): boolean;
     get showSearchNoResults(): boolean;
     ngOnChanges(changes: SimpleChanges): void;
+    /** `false` quando o corpo já tratou a selecção no mesmo ciclo — não repetir após `afterNextRender`. */
+    private needsDeferredBodyRouteSync;
+    /**
+     * O corpo do menu só existe após o primeiro render; no drawer mobile isso atrasa `ensureExpanded`
+     * relativamente ao `ngOnChanges` do corpo — repetimos após `afterNextRender`.
+     */
+    private scheduleBodyRouteSelectionSync;
     onSearchQueryInput(value: string | null): void;
+    onMenuItemSelect(id: T): void;
     resetHighlight(): void;
     focusFirstOption(): void;
+    /**
+     * Usado pela `app-sidebar` ao abrir o drawer móvel: garante {@link MenuListBodyComponent.syncRouteSelectionExpansion}
+     * antes do scroll (grupos fechados em `sessionStorage` passam a abrir no caminho do item activo).
+     */
+    syncSelectionForMobileDrawerOpen(): void;
     private syncDisplayItems;
     static ɵfac: i0.ɵɵFactoryDeclaration<MenuListComponent<any>, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<MenuListComponent<any>, "app-menu-list", never, { "appTheme": { "alias": "appTheme"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; }; "menuId": { "alias": "menuId"; "required": false; }; "dense": { "alias": "dense"; "required": false; }; "nested": { "alias": "nested"; "required": false; }; "selectedItemId": { "alias": "selectedItemId"; "required": false; }; "compressText": { "alias": "compressText"; "required": false; }; "clickToOpen": { "alias": "clickToOpen"; "required": false; }; "groupCollapsible": { "alias": "groupCollapsible"; "required": false; }; "groupDefaultExpansion": { "alias": "groupDefaultExpansion"; "required": false; }; "persistGroupExpansion": { "alias": "persistGroupExpansion"; "required": false; }; "searchable": { "alias": "searchable"; "required": false; }; "searchPlaceholder": { "alias": "searchPlaceholder"; "required": false; }; }, { "itemSelect": "itemSelect"; "closeRequest": "closeRequest"; "submenuBack": "submenuBack"; "groupToggled": "groupToggled"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MenuListComponent<any>, "app-menu-list", never, { "appTheme": { "alias": "appTheme"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; }; "menuId": { "alias": "menuId"; "required": false; }; "dense": { "alias": "dense"; "required": false; }; "nested": { "alias": "nested"; "required": false; }; "selectedItemId": { "alias": "selectedItemId"; "required": false; }; "compressText": { "alias": "compressText"; "required": false; }; "clickToOpen": { "alias": "clickToOpen"; "required": false; }; "groupCollapsible": { "alias": "groupCollapsible"; "required": false; }; "groupDefaultExpansion": { "alias": "groupDefaultExpansion"; "required": false; }; "persistGroupExpansion": { "alias": "persistGroupExpansion"; "required": false; }; "searchable": { "alias": "searchable"; "required": false; }; "limparAposPesquisar": { "alias": "limparAposPesquisar"; "required": false; }; "searchPlaceholder": { "alias": "searchPlaceholder"; "required": false; }; }, { "itemSelect": "itemSelect"; "closeRequest": "closeRequest"; "submenuBack": "submenuBack"; "groupToggled": "groupToggled"; "selectionScrollHint": "selectionScrollHint"; }, never, never, true, never>;
     static ngAcceptInputType_dense: unknown;
     static ngAcceptInputType_nested: unknown;
     static ngAcceptInputType_compressText: unknown;
     static ngAcceptInputType_groupCollapsible: unknown;
     static ngAcceptInputType_persistGroupExpansion: unknown;
     static ngAcceptInputType_searchable: unknown;
+    static ngAcceptInputType_limparAposPesquisar: unknown;
 }
 
 /**
@@ -3429,6 +3478,7 @@ declare class AppSidebarComponent<T extends string = string> implements OnChange
     private readonly cdr;
     private readonly destroyRef;
     private readonly hostEl;
+    private readonly injector;
     private readonly renderer;
     /** Igual a `[appTheme]` / {@link ThemeDirective}: paleta explícita no host; omitir = herdar / serviço. */
     readonly appTheme: i0.InputSignal<"blue" | "green" | "purple" | "orange" | "white" | "gray" | "sepia" | "black" | AppTheme | undefined>;
@@ -3438,8 +3488,16 @@ declare class AppSidebarComponent<T extends string = string> implements OnChange
     selectedItemId: T | null;
     /** Modo estreito: só ícones + `compressText` na lista (rótulos via `title` / `aria-label`). */
     collapsed: boolean;
+    /**
+     * Ligado ao estado do drawer no telemóvel (ex.: `mobileNavOpen` do `app-shell`).
+     * Em cada transição para `true`, volta a agendar o scroll até ao item activo — útil porque `selectedItemId`
+     * pode não mudar entre aberturas e o menu pode ser recriado dentro do `@if (open)` do drawer.
+     */
+    mobileNavOpenPulse: boolean;
     /** Repassado a {@link MenuListComponent.searchable}: campo de pesquisa na lista da lateral. */
     searchable: boolean;
+    /** Repassado a {@link MenuListComponent.limparAposPesquisar}. */
+    limparAposPesquisar: boolean;
     /**
      * Repassado a {@link MenuListComponent.clickToOpen}: submenus na lateral abrem por **clique** (`true`, omissão)
      * ou por **hover** (`false`).
@@ -3455,6 +3513,7 @@ declare class AppSidebarComponent<T extends string = string> implements OnChange
      */
     groupDefaultExpansion: 'all' | 'first';
     readonly itemSelect: EventEmitter<T>;
+    private menuList?;
     /**
      * Valor efectivo de `compressText` em `app-menu-list`: ao expandir a partir do modo rail,
      * mantém-se comprimido até a animação de largura terminar (evita flicker de texto).
@@ -3464,14 +3523,29 @@ declare class AppSidebarComponent<T extends string = string> implements OnChange
     readonly listCompressText: i0.WritableSignal<boolean>;
     private listRevealTimeoutId;
     private scrollRestoreTimeoutId;
+    /** Invalida tentativas de scroll pendentes (ex.: novo agendamento ou destroy). */
+    private scrollToSelectedGeneration;
+    /** `setTimeout` extra ao abrir o drawer — animação (~240ms) e flex podem atrasar métricas do scroll. */
+    private drawerScrollAssistTimeouts;
     constructor();
     ngAfterViewInit(): void;
     ngOnChanges(changes: SimpleChanges): void;
     /**
-     * Garante que o item `--selected` fica inteiro na área útil (margem + cabeçalho sticky),
-     * com ~½ da opção vizinha visível quando há scroll, e movimento suave.
+     * Agenda scroll até ao `--selected` depois do próximo render (filhos OnPush) e reintenta em `rAF`
+     * até o elemento existir — necessário no drawer mobile, onde o menu acaba de montar.
+     */
+    /**
+     * Repete o scroll quando o utilizador clica num item já activo mas «cortado» (`selectedItemId` não muda).
      */
-    private scrollSidebarToSelectedItem;
+    onSidebarItemSelect(id: T): void;
+    /** Também ligado a `(selectionScrollHint)` em `app-menu-list` para o drawer mobile. */
+    scheduleScrollToSelected(): void;
+    private static readonly SCROLL_TO_SELECTED_MAX_ATTEMPTS;
+    private static readonly SCROLL_TO_SELECTED_MAX_ATTEMPTS_DRAWER;
+    /** Sidebar projectada em `.app-drawer__body` — animação do painel e `overflow` do shell afectam o layout. */
+    private isInsideMobileDrawer;
+    private clearDrawerScrollAssistTimeouts;
+    private runScrollToSelectedRetry;
     /** Após clicar num grupo colapsável: leva o cabeçalho do grupo para a zona visível (como o item seleccionado). */
     onMenuGroupToggled(groupId: number): void;
     /** Área com scroll dos itens (`cdkScrollable`), não o cabeçalho nem a pesquisa. */
@@ -3485,9 +3559,11 @@ declare class AppSidebarComponent<T extends string = string> implements OnChange
     private scheduleSidebarHeadLayoutGuards;
     private applySidebarHeadLayoutGuards;
     static ɵfac: i0.ɵɵFactoryDeclaration<AppSidebarComponent<any>, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<AppSidebarComponent<any>, "app-sidebar", never, { "appTheme": { "alias": "appTheme"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; }; "menuId": { "alias": "menuId"; "required": false; }; "selectedItemId": { "alias": "selectedItemId"; "required": false; }; "collapsed": { "alias": "collapsed"; "required": false; }; "searchable": { "alias": "searchable"; "required": false; }; "clickToOpen": { "alias": "clickToOpen"; "required": false; }; "groupCollapsible": { "alias": "groupCollapsible"; "required": false; }; "groupDefaultExpansion": { "alias": "groupDefaultExpansion"; "required": false; }; }, { "itemSelect": "itemSelect"; }, never, ["[appSidebarBrand]", "[appSidebarToolbar]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<AppSidebarComponent<any>, "app-sidebar", never, { "appTheme": { "alias": "appTheme"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; }; "menuId": { "alias": "menuId"; "required": false; }; "selectedItemId": { "alias": "selectedItemId"; "required": false; }; "collapsed": { "alias": "collapsed"; "required": false; }; "mobileNavOpenPulse": { "alias": "mobileNavOpenPulse"; "required": false; }; "searchable": { "alias": "searchable"; "required": false; }; "limparAposPesquisar": { "alias": "limparAposPesquisar"; "required": false; }; "clickToOpen": { "alias": "clickToOpen"; "required": false; }; "groupCollapsible": { "alias": "groupCollapsible"; "required": false; }; "groupDefaultExpansion": { "alias": "groupDefaultExpansion"; "required": false; }; }, { "itemSelect": "itemSelect"; }, never, ["[appSidebarBrand]", "[appSidebarToolbar]"], true, never>;
     static ngAcceptInputType_collapsed: unknown;
+    static ngAcceptInputType_mobileNavOpenPulse: unknown;
     static ngAcceptInputType_searchable: unknown;
+    static ngAcceptInputType_limparAposPesquisar: unknown;
     static ngAcceptInputType_groupCollapsible: unknown;
 }