@rt-tools/ui-kit-v2 0.16.0 → 0.18.0

package/types/rt-tools-ui-kit-v2-container.d.ts

@@ -0,0 +1,425 @@
+import * as i0 from '@angular/core';
+import { Signal, TemplateRef, InputSignal, OutputEmitterRef, WritableSignal, OnDestroy, OnInit, DestroyRef } from '@angular/core';
+import { AbstractControl } from '@angular/forms';
+import { Router, ActivatedRoute, Params, CanDeactivateFn } from '@angular/router';
+import { Observable } from 'rxjs';
+import { IRtAsideUnsavedGuard } from '@rt-tools/ui-kit-v2/aside';
+
+/**
+ * Multi-slot container с CSS-grid layout. Slot consumers wrap content в
+ * `*rtContainerXxx` structural directives, контейнер подхватывает шаблоны через
+ * `contentChild(..., { read: TemplateRef })` + рендерит через `*ngTemplateOutlet`.
+ *
+ * Slots: `header`, `leftSidenav`, `toolbarLeft/Center/Right`, `content` — живут в
+ * CSS-grid. `rightSidenav` рендерится через CDK Overlay поверх grid'а (slide-in
+ * side-sheet), а не как grid-cell — overlay переиспользует глобальные
+ * `rt-aside-overlay` / `rt-aside-backdrop` классы из rt-aside, чтобы анимация и
+ * backdrop вели себя идентично программно открываемым asides.
+ *
+ * Driver-directives (`[rtContainerLeftSidenavPanel/RightSidenavPanel]`) общаются с
+ * контейнером через `RtContainerStateService` (для левой docked) и через
+ * `openRight()/closeRight()` + lifecycle outputs (для правой overlay).
+ */
+declare class RtContainerComponent {
+    #private;
+    protected readonly headerTpl: Signal<TemplateRef<unknown> | undefined>;
+    protected readonly leftSidenavTpl: Signal<TemplateRef<unknown> | undefined>;
+    protected readonly rightSidenavTpl: Signal<TemplateRef<unknown> | undefined>;
+    protected readonly toolbarLeftTpl: Signal<TemplateRef<unknown> | undefined>;
+    protected readonly toolbarCenterTpl: Signal<TemplateRef<unknown> | undefined>;
+    protected readonly toolbarRightTpl: Signal<TemplateRef<unknown> | undefined>;
+    protected readonly contentTpl: Signal<TemplateRef<unknown> | undefined>;
+    /**
+     * Поведение левого sidenav на мобилке (<=768px): `keep` — остаётся боковой
+     * колонкой (по умолчанию, десктоп-стиль); `bottom` — сворачивается в нижний
+     * ряд grid'а (таб-бар), контент занимает всю ширину и скроллится над ним.
+     */
+    readonly mobileLeftNav: InputSignal<'keep' | 'bottom'>;
+    /**
+     * Высота контейнера: `auto` — растёт под контент, скроллится документ (по
+     * умолчанию; на этом держится sticky-хедер); `viewport` — контейнер жёстко
+     * равен вьюпорту, страница не скроллится вовсе, а скроллятся зоны внутри —
+     * каждая сама по себе (app-shell раскладка, напр. чаты бот-панели).
+     */
+    readonly height: InputSignal<'auto' | 'viewport'>;
+    readonly backdropClick: OutputEmitterRef<void>;
+    readonly rightOpened: OutputEmitterRef<void>;
+    readonly rightClosed: OutputEmitterRef<void>;
+    readonly rightOpen: WritableSignal<boolean>;
+    /**
+     * `true` когда CDK Overlay для правой sidenav создан и attache'нут (см.
+     * effect в constructor'е). Дёргать panel.open() из консьюмера можно только
+     * когда это true — иначе openRight() видит null overlayRef и early-return'ит,
+     * --entering modifier остаётся, панель остаётся за экраном. Re-exposed на
+     * driver через `panel.ready` для удобства route-driven dialog'ов.
+     */
+    readonly rightOverlayReady: Signal<boolean>;
+    constructor();
+    openRight(): void;
+    closeRight(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RtContainerComponent, "rt-container", never, { "mobileLeftNav": { "alias": "mobileLeftNav"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; }, { "backdropClick": "backdropClick"; "rightOpened": "rightOpened"; "rightClosed": "rightClosed"; }, ["headerTpl", "leftSidenavTpl", "rightSidenavTpl", "toolbarLeftTpl", "toolbarCenterTpl", "toolbarRightTpl", "contentTpl"], never, true, never>;
+}
+
+/**
+ * Маркеры слотов оболочки — своим файлом, а не рядом с панельными директивами.
+ *
+ * Панельные директивы берут сам компонент оболочки значением, а компонент объявляет маркеры в
+ * своих импортах: вместе это круг «оболочка → директивы → оболочка». Маркеры пусты и не знают
+ * об оболочке ничего, поэтому расходятся с ней без потерь.
+ */
+/**
+ * Маркер-директива для содержимого хедера `rt-container`.
+ *
+ * @example
+ * ```html
+ * <rt-container>
+ *     <ng-container *rtContainerHeader>
+ *         <rt-header />
+ *     </ng-container>
+ * </rt-container>
+ * ```
+ */
+declare class RtContainerHeaderDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerHeaderDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerHeaderDirective, "[rtContainerHeader]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Маркер-директива для контента левой sidenav в `rt-container`.
+ *
+ * @example
+ * ```html
+ * <rt-container>
+ *     <ng-container *rtContainerLeftSidenav>
+ *         <router-outlet name="lo" />
+ *     </ng-container>
+ * </rt-container>
+ * ```
+ */
+declare class RtContainerLeftSidenavDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerLeftSidenavDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerLeftSidenavDirective, "[rtContainerLeftSidenav]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Маркер-директива для контента правой sidenav в `rt-container`.
+ *
+ * @example
+ * ```html
+ * <rt-container>
+ *     <ng-container *rtContainerRightSidenav>
+ *         <router-outlet name="ro" />
+ *     </ng-container>
+ * </rt-container>
+ * ```
+ */
+declare class RtContainerRightSidenavDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerRightSidenavDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerRightSidenavDirective, "[rtContainerRightSidenav]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Маркер-директива для контента в левой секции toolbar.
+ *
+ * @example
+ * ```html
+ * <rt-container>
+ *     <ng-container *rtContainerToolbarLeft>
+ *         <router-outlet name="lb" />
+ *     </ng-container>
+ * </rt-container>
+ * ```
+ */
+declare class RtContainerToolbarLeftDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerToolbarLeftDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerToolbarLeftDirective, "[rtContainerToolbarLeft]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Маркер-директива для контента в центральной секции toolbar.
+ *
+ * @example
+ * ```html
+ * <rt-container>
+ *     <ng-container *rtContainerToolbarCenter>
+ *         <router-outlet name="cb" />
+ *     </ng-container>
+ * </rt-container>
+ * ```
+ */
+declare class RtContainerToolbarCenterDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerToolbarCenterDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerToolbarCenterDirective, "[rtContainerToolbarCenter]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Маркер-директива для контента в правой секции toolbar.
+ *
+ * @example
+ * ```html
+ * <rt-container>
+ *     <ng-container *rtContainerToolbarRight>
+ *         <router-outlet name="rb" />
+ *     </ng-container>
+ * </rt-container>
+ * ```
+ */
+declare class RtContainerToolbarRightDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerToolbarRightDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerToolbarRightDirective, "[rtContainerToolbarRight]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Маркер-директива для основного контента `rt-container`.
+ *
+ * @example
+ * ```html
+ * <rt-container>
+ *     <ng-container *rtContainerContent>
+ *         <router-outlet />
+ *     </ng-container>
+ * </rt-container>
+ * ```
+ */
+declare class RtContainerContentDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerContentDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerContentDirective, "[rtContainerContent]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Driver-директива для управления левой sidenav через шаблонную ссылку.
+ *
+ * Пишет в component-scoped `RtContainerStateService.leftSidenavOpen` signal —
+ * шаблон контейнера читает этот signal и применяет docked grid-cell состояние.
+ *
+ * @example
+ * ```html
+ * <ng-container rtContainerLeftSidenavPanel #left="containerLeftPanel">
+ *     <button (click)="left.toggle(true)">Open</button>
+ * </ng-container>
+ * ```
+ */
+declare class RtContainerLeftSidenavPanelDirective {
+    #private;
+    open(): void;
+    close(): void;
+    toggle(isOpen: boolean): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerLeftSidenavPanelDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerLeftSidenavPanelDirective, "[rtContainerLeftSidenavPanel]", ["containerLeftPanel"], {}, {}, never, never, true, never>;
+}
+/**
+ * Driver-директива правой sidenav: route-component вызывает `open()`/`close()`,
+ * rt-container выполняет slide-in/slide-out через CSS transform. После завершения
+ * анимации driver эмитит `(opened)` / `(closed)`; backdrop click и ESC контейнера
+ * эмитятся через `(cancelled)` — консьюмер сам решает что делать (обычно `close()`).
+ *
+ * Sub'ы через `takeUntilDestroyed` снимаются при разрушении route-component'а.
+ * При уничтожении с открытой панелью гарантирует cleanup overlay'я (см. `ngOnDestroy`),
+ * иначе при hard-navigate без `panel.close()` overlay останется висеть.
+ *
+ * @example
+ * ```html
+ * <ng-container
+ *     rtContainerRightSidenavPanel
+ *     #right="rtContainerRightPanel"
+ *     (cancelled)="onClose()"
+ *     (closed)="onClosed()">
+ * </ng-container>
+ * ```
+ */
+declare class RtContainerRightSidenavPanelDirective implements OnDestroy {
+    #private;
+    readonly opened: OutputEmitterRef<void>;
+    readonly closed: OutputEmitterRef<void>;
+    readonly cancelled: OutputEmitterRef<void>;
+    /**
+     * Re-export rt-container.rightOverlayReady — `true` когда CDK Overlay создан
+     * и attache'нут. Консьюмер должен ждать этого signal'а в effect'е, перед
+     * тем как вызывать `panel.open()` (иначе race: rt-container.effect ещё не
+     * создал overlay → openRight() рано вернётся → --entering остаётся).
+     */
+    readonly ready: Signal<boolean>;
+    constructor();
+    ngOnDestroy(): void;
+    open(): void;
+    close(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerRightSidenavPanelDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerRightSidenavPanelDirective, "[rtContainerRightSidenavPanel]", ["rtContainerRightPanel"], {}, { "opened": "opened"; "closed": "closed"; "cancelled": "cancelled"; }, never, never, true, never>;
+}
+/**
+ * Driver-директива для основного content-региона `rt-container`.
+ *
+ * Объявляет 3 outputs (`scrolled/scrolledUp/scrolledDown`) — публичную поверхность
+ * для будущих consumer'ов. Real-time wiring (scroll listeners → emit) отложено
+ * до первого реального потребителя.
+ *
+ * @example
+ * ```html
+ * <ng-container
+ *     rtContainerContentPanel
+ *     (scrolled)="onScroll()"
+ * >
+ *     <router-outlet />
+ * </ng-container>
+ * ```
+ */
+declare class RtContainerContentPanelDirective {
+    readonly scrolled: OutputEmitterRef<void>;
+    readonly scrolledUp: OutputEmitterRef<void>;
+    readonly scrolledDown: OutputEmitterRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerContentPanelDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtContainerContentPanelDirective, "[rtContainerContentPanel]", never, {}, { "scrolled": "scrolled"; "scrolledUp": "scrolledUp"; "scrolledDown": "scrolledDown"; }, never, never, true, never>;
+}
+
+/**
+ * Приватный signal-store для `rt-container`.
+ *
+ * Хранит open-state левой docked sidenav. Driver-директива
+ * `[rtContainerLeftSidenavPanel]` пишет в `leftSidenavOpen`, шаблон
+ * `RtContainerComponent` читает через signal-tracking.
+ *
+ * Provided component-level через `providers: [RtContainerStateService]` на
+ * `RtContainerComponent` — per-instance state, без singleton'а. Pure signal IO
+ * с автоматической reactivity.
+ *
+ * Правая sidenav (overlay) НЕ хранится здесь: её open-state живёт прямо в
+ * `RtContainerComponent.rightOpen` сигнале и управляется через `openRight()` /
+ * `closeRight()` методы + lifecycle outputs.
+ */
+declare class RtContainerStateService {
+    readonly leftSidenavOpen: WritableSignal<boolean>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtContainerStateService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+
+/**
+ * Открытие ждёт `panel.ready()`, а не `ngAfterViewInit`: на F5 rt-container
+ * создаёт overlay асинхронно, иначе `open()` гонится с ещё не готовым overlay.
+ *
+ * `@Directive()` без селектора — чтобы query/`inject`/lifecycle наследовались на
+ * конкретный `@Component` (как `RtFormControlBase`).
+ *
+ * Закрытие всегда идёт через `onClose()`, куда сходятся все четыре пути: две
+ * кнопки панели и — через `onCancel()` — нажатие мимо панели и Esc, которые ловит
+ * `rt-container`. Панель, поставившая гард через `guardUnsavedChanges()`, на
+ * тронутой форме получает вопрос о правках; панель без гарда закрывается сразу.
+ */
+declare abstract class RtRouteAsideComponent<T> implements OnInit {
+    #private;
+    protected readonly router: Router;
+    protected readonly route: ActivatedRoute;
+    protected readonly destroyRef: DestroyRef;
+    protected readonly panel: Signal<RtContainerRightSidenavPanelDirective | undefined>;
+    protected readonly entity: Signal<T | null>;
+    /** id из route-параметра как есть (uuid/строка); числовые id консьюмер парсит сам. */
+    protected readonly entityId: Signal<string | null>;
+    protected readonly isCreateMode: Signal<boolean>;
+    protected readonly submitting: Signal<boolean>;
+    /**
+     * Скелетоны биндятся на это, а не на пустоту `entity()`: та залипает после
+     * первой загрузки и не ловит рефетч.
+     */
+    protected readonly resolving: Signal<boolean>;
+    protected readonly busy: Signal<boolean>;
+    /**
+     * Форма не тронута. Панель, которая не поставила гард закрытия, считается
+     * нетронутой всегда — и закрывается без вопроса, как раньше.
+     */
+    protected readonly pristine: Signal<boolean>;
+    protected readonly submitError: WritableSignal<string | null>;
+    /**
+     * Удача мутации — тем же способом, что и отказ. Человек, работающий в панели,
+     * смотрит в панель, а не на экран за её краем: тост об успехе всплывает там,
+     * куда он в эту минуту не смотрит. Оба сигнала гасятся в начале каждой
+     * попытки и гасят друг друга — это ответы на один вопрос, и двух сразу не
+     * бывает.
+     */
+    protected readonly submitSuccess: WritableSignal<string | null>;
+    protected readonly idParamName: string;
+    /** id-only режим: нужен только id (например, смена пароля по userId), сущность не грузится. */
+    protected readonly idOnly: boolean;
+    constructor();
+    ngOnInit(): void;
+    /**
+     * Панель уходит с экрана не сама: её место в аутлете занимает другая — лента
+     * событий из шапки или соседняя запись. Тронутая форма спрашивает о правках
+     * так же, как при закрытии; окно кнопок этот путь не ловит, потому что панель
+     * закрывает роутер.
+     *
+     * Гард ставится на ro-маршрут панели (`rtAsideUnsavedGuard`).
+     */
+    canDeactivate(): Observable<boolean>;
+    protected setEntity(entity: T | null): void;
+    /** Признак нетронутой формы — тот же, что гейтит кнопку записи. */
+    protected pristineSignal(control: AbstractControl | Signal<AbstractControl | undefined>): Signal<boolean>;
+    /**
+     * Ставит гард закрытия: пока форма тронута, любой из четырёх путей закрытия
+     * спрашивает, что сделать с правками, и исход «закрыть с сохранением» зовёт
+     * `save`. Признак нетронутости даёт `pristineSignal(control)` — тот же, что
+     * гейтит кнопку записи.
+     */
+    protected guardUnsavedChanges(guard: IRtAsideUnsavedGuard): void;
+    /**
+     * Адрес связанной записи для атрибута `href`. Ссылка остаётся настоящей
+     * ссылкой: её открывают в новой вкладке и копируют, а обычное нажатие панель
+     * перехватывает и уводит сама.
+     */
+    protected relatedUrl(commands: readonly unknown[]): string;
+    /**
+     * Уход на связанную запись. Он уводит с адреса панели так же, как её
+     * закрытие, поэтому идёт тем же путём: тронутая форма спрашивает, что
+     * сделать с правками, и на исходе «закрыть с сохранением» запись открывается
+     * после удачной записи.
+     */
+    protected openRelated(commands: readonly unknown[], queryParams?: Params | null): void;
+    protected onResolved(): void;
+    protected closeOutlets(): Record<string, Array<string> | null>;
+    /**
+     * `successText` — готовый текст тоста об успехе. Он принадлежит конкретной
+     * мутации, а не панели: у снятия промокода и опроса подписки свой текст
+     * успеха, и один на панель показал бы не тот.
+     *
+     * Именно текст, а не ключ словаря: ключ принадлежал бы словарю приложения, а
+     * кит чужих словарей не знает — переводит приложение и передаёт готовое.
+     *
+     * `errorText` принимается и функцией: причина отказа известна только после
+     * него — стор кладёт её в свой сигнал, а панель без стора выводит из ответа
+     * сервера, — и готовой строкой на момент запуска мутации её не передать.
+     *
+     * `successMessage` — текст удачи, который панель показывает внутри себя,
+     * рядом с формой. Довод отделён от `successText` намеренно: переезд текста
+     * из тоста в панель сломал бы всякого потребителя, который тост и хотел, а
+     * сказать «мне нужен тост» ему после этого было бы нечем. Назван он по месту
+     * показа, а не по исходу: два довода с разницей в одном слоге читались бы
+     * как опечатка.
+     */
+    protected runMutation(op$: Observable<unknown>, opts?: {
+        onSuccess?: () => void;
+        successText?: string;
+        successMessage?: string;
+        errorText?: string | ((error: unknown) => string);
+        closeOnSuccess?: boolean;
+        refreshOnSuccess?: boolean;
+    }): void;
+    /**
+     * Единственная точка закрытия панели. Через неё идут все четыре пути: кнопка
+     * в шапке, кнопка в футере и — через `onCancel()` — нажатие мимо панели и
+     * клавиша Esc, которые ловит `rt-container` и отдаёт панели одним выходом
+     * `cancelled`.
+     */
+    protected onClose(): void;
+    protected onCancel(): void;
+    protected onClosed(): void;
+    protected abstract resolve(id: string): Observable<T | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RtRouteAsideComponent<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RtRouteAsideComponent<any>, never, never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Панель, которая умеет ответить на вопрос «можно ли уступить место».
+ *
+ * Объявлена рядом с учётом панелей, а не рядом с гардом: гард берёт учёт значением, и
+ * объявление у него замыкало круг «учёт → гард → учёт».
+ */
+interface IRtAsideDeactivate {
+    canDeactivate(): Observable<boolean>;
+}
+
+declare const rtAsideUnsavedGuard: CanDeactivateFn<IRtAsideDeactivate | null>;
+
+export { RtContainerComponent, RtContainerContentDirective, RtContainerContentPanelDirective, RtContainerHeaderDirective, RtContainerLeftSidenavDirective, RtContainerLeftSidenavPanelDirective, RtContainerRightSidenavDirective, RtContainerRightSidenavPanelDirective, RtContainerStateService, RtContainerToolbarCenterDirective, RtContainerToolbarLeftDirective, RtContainerToolbarRightDirective, RtRouteAsideComponent, rtAsideUnsavedGuard };