@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-drawer.d.ts

@@ -0,0 +1,333 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, StaticProvider, TemplateRef, Signal, ElementRef, OnDestroy, OnInit, Type } from '@angular/core';
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import { OverlayRef, PositionStrategy, OverlayConfig } from '@angular/cdk/overlay';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvOverlayRef, MlvBaseOverlayConfig, MlvOverlayServiceBase, MlvOverlayHostBase } from '@malva-ui/cdk/overlay';
+import { MlvStructural } from '@malva-ui/cdk/utils';
+import { DefaultExport, Route } from '@angular/router';
+
+declare class MlvDrawerContent extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvDrawerContent, "[mlvDrawerContent]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Reference to an imperatively opened drawer; exposes `close()`, `afterClosed()`,
+ * and `beforeClose()`.
+ *
+ * Thin subclass of {@link MlvOverlayRef} that supplies the drawer surface's
+ * leave-animation class names and fallback duration; all close/afterClosed/
+ * beforeClose logic is inherited.
+ *
+ * @typeParam R - The result type emitted by `afterClosed()`. Defaults to `unknown`.
+ */
+declare class MlvDrawerRef<R = unknown> extends MlvOverlayRef<R> {
+    /** @private The edge the drawer slides from. */
+    private readonly _position;
+    /** @private Configured close-animation duration in milliseconds. */
+    private readonly _animationDuration;
+    /** @protected Backdrop leave-animation class for drawers. */
+    protected readonly _backdropLeavingClass = "mlv-drawer-backdrop--leaving";
+    /** @protected Panel leave-animation class for drawers. */
+    protected readonly _panelLeaveClass = "mlv-drawer--leave";
+    /** @protected Fallback close-animation duration (ms) for drawers. */
+    protected readonly _leaveFallbackMs = 350;
+    constructor(overlayRef: OverlayRef, 
+    /** @private The edge the drawer slides from. */
+    _position?: string, 
+    /** @private Configured close-animation duration in milliseconds. */
+    _animationDuration?: number);
+}
+
+type MlvDrawerPosition = 'left' | 'right' | 'top' | 'bottom';
+interface MlvDrawerConfig extends MlvBaseOverlayConfig {
+    /** Edge the drawer slides from. Defaults to `'right'`. */
+    position?: MlvDrawerPosition;
+    /** CSS width (left/right) or height (top/bottom) of the panel. */
+    size?: string;
+    /**
+     * CSS max-size ceiling for the panel's sizing axis (width for `left`/`right`,
+     * height for `top`/`bottom`).
+     *
+     * Applied whether or not the drawer is `resizable`, and always additionally
+     * clamped to the viewport so a fixed `size` can never exceed the screen.
+     */
+    maxSize?: string;
+    /** Animation duration in milliseconds. Defaults to `300`. */
+    animationDuration?: number;
+    /**
+     * When true, renders a drag handle on the inward-facing edge.
+     * Enables drag-to-resize and swipe-to-dismiss.
+     */
+    resizable?: boolean;
+    /**
+     * Sorted array of viewport-percentage snap points (0–100).
+     * After drag ends, the panel animates to the nearest snap point.
+     * Only effective when `resizable` is true.
+     */
+    snapPoints?: number[];
+    /**
+     * Initial snap point percentage (0–100) applied when the drawer opens.
+     * Defaults to 100 (full size). Only used when `resizable` is true.
+     */
+    defaultSnap?: number;
+}
+declare const DRAWER_DATA: InjectionToken<unknown>;
+declare class MlvDrawerService extends MlvOverlayServiceBase<MlvDrawerConfig, MlvDrawerRef> {
+    /** @protected Panel enter-animation class for drawers. */
+    protected readonly _enterAnimationClass = "mlv-drawer--enter";
+    /** @protected Anchors the drawer to the configured viewport edge. */
+    protected _buildPositionStrategy(config: MlvDrawerConfig): PositionStrategy;
+    /** @protected Drawer backdrop class. */
+    protected _buildOverlayConfig(): OverlayConfig;
+    /** @protected Creates the drawer reference, forwarding position and animation duration. */
+    protected _createRef(overlayRef: OverlayRef, config: MlvDrawerConfig): MlvDrawerRef;
+    /** @protected Provides `MlvDrawerRef` and `DRAWER_DATA` to the opened component. */
+    protected _createProviders(ref: MlvDrawerRef, config: MlvDrawerConfig): StaticProvider[];
+    /** @protected Applies drawer shell classes, hidden-transform var, and panel sizing to the overlay pane. */
+    protected _decoratePanel(panelEl: HTMLElement, config: MlvDrawerConfig): void;
+    /**
+     * @private Combines a configured `maxSize` with the viewport ceiling for the
+     * sizing axis.
+     *
+     * `drawer.scss` cannot help here — Angular injects a component's styles when
+     * that component is first instantiated, and `MlvDrawer` is never constructed
+     * on the service path — so the clamp has to be written onto the pane.
+     */
+    private _resolveMaxSize;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MlvDrawerService>;
+}
+
+declare class MlvDrawer extends MlvOverlayHostBase {
+    /** @protected The component's i18n strings signal. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvDrawerI18n>;
+    /** @protected Base CSS class of the drawer backdrop. */
+    protected readonly _backdropClass = "mlv-drawer-backdrop";
+    /** Which edge of the viewport the drawer slides from. */
+    readonly position: _angular_core.InputSignal<MlvDrawerPosition>;
+    /**
+     * Accessible name for the drawer dialog surface. Used as the `aria-label`
+     * when no `ariaLabelledBy` is provided. When both are omitted, the drawer
+     * falls back to the localized default ("Drawer") so the `role="dialog"`
+     * is never left without an accessible name.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Id of a visible element (typically a projected `[mlvDrawerHeader]`) that
+     * labels the drawer. When set, it takes precedence over `ariaLabel` and the
+     * i18n fallback via `aria-labelledby` — mirroring how `mlv-dialog` labels
+     * itself by its projected header.
+     */
+    readonly ariaLabelledBy: _angular_core.InputSignal<string | undefined>;
+    /**
+     * @protected Resolved `aria-label` for the dialog surface: the explicit
+     * `ariaLabel` input, or the localized fallback. Suppressed (null) when
+     * `ariaLabelledBy` is set so the two naming methods never conflict.
+     */
+    protected readonly _resolvedAriaLabel: _angular_core.Signal<string | null>;
+    /**
+     * CSS width (left/right drawers) or height (top/bottom drawers) of the panel.
+     * Used as the initial size when `resizable` is false or no `defaultSnap` is set.
+     */
+    readonly size: _angular_core.InputSignal<string>;
+    /**
+     * When true, renders a drag handle on the inward-facing edge.
+     * Enables drag-to-resize and swipe-to-dismiss.
+     */
+    readonly resizable: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Sorted array of viewport-percentage snap points (0–100).
+     * After drag ends, the panel animates to the nearest snap point.
+     * If empty, the panel stays at its released position.
+     * Only effective when `resizable` is true.
+     */
+    readonly snapPoints: _angular_core.InputSignal<number[]>;
+    /**
+     * Initial snap point percentage (0–100) applied when the drawer opens.
+     * Defaults to 100 (full size). Only used when `resizable` is true.
+     */
+    readonly defaultSnap: _angular_core.InputSignal<number>;
+    /**
+     * CSS min-size floor applied during drag resize.
+     * Only used when `resizable` is true.
+     */
+    readonly minSize: _angular_core.InputSignal<string>;
+    /**
+     * CSS max-size ceiling for the panel's sizing axis (width for `left`/`right`,
+     * height for `top`/`bottom`).
+     *
+     * Honoured whether or not the drawer is `resizable` — a fixed `size` is
+     * clamped by it too. The resolved ceiling is always additionally clamped to
+     * the viewport (`100dvw`/`100dvh`), so a `size="36rem"` drawer can never be
+     * wider than a 375 px phone.
+     */
+    readonly maxSize: _angular_core.InputSignal<string>;
+    readonly hiddenTransform: _angular_core.Signal<string>;
+    /** @protected Projected drawer content directive, rendered into the overlay panel. */
+    protected readonly contentRef: _angular_core.Signal<MlvDrawerContent | undefined>;
+    /** @protected The `#drawerTemplate` view template attached to the CDK overlay portal. */
+    protected readonly drawerTemplate: _angular_core.Signal<TemplateRef<unknown> | undefined>;
+    /**
+     * @protected Computes the initial panel size string.
+     * When resizable, uses `defaultSnap` as a dvh/dvw percentage;
+     * otherwise falls back to the `size` input.
+     */
+    protected readonly _initialPanelSize: _angular_core.Signal<string>;
+    /**
+     * @private Combines the configured `maxSize` with the viewport ceiling for
+     * the sizing axis.
+     *
+     * The viewport ceiling is unconditional: without it a fixed `size` larger
+     * than the screen (`size="36rem"` on a 375 px phone) renders a panel that
+     * hangs off the edge. `maxSize` is folded in through CSS `min()` so it is
+     * honoured on the non-resizable path too. The `'100%'` default is dropped
+     * rather than nested — it resolves against the overlay pane, which is itself
+     * sized by this panel, so it would add nothing but an indirection.
+     */
+    private _resolveMaxSize;
+    /**
+     * Resolved inline geometry for the panel element: the sizing-axis `size`, the
+     * cross-axis viewport fill, and the max ceilings on both axes.
+     */
+    get drawerDimensions(): Record<string, string>;
+    /** @protected Returns the drawer surface template to attach to the overlay. */
+    protected _getOverlayTemplate(): TemplateRef<unknown> | undefined;
+    /** @protected Anchors the drawer to the configured viewport edge. */
+    protected _buildPositionStrategy(): PositionStrategy;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawer, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvDrawer, "mlv-drawer", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "ariaLabelledBy"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "resizable": { "alias": "resizable"; "required": false; "isSignal": true; }; "snapPoints": { "alias": "snapPoints"; "required": false; "isSignal": true; }; "defaultSnap": { "alias": "defaultSnap"; "required": false; "isSignal": true; }; "minSize": { "alias": "minSize"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; }, {}, ["contentRef"], never, true, never>;
+}
+
+declare class MlvDrawerHeader {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerHeader, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvDrawerHeader, "[mlvDrawerHeader]", never, {}, {}, never, never, true, never>;
+}
+
+/** Scrollable body region used by declarative and service-opened drawers. */
+declare class MlvDrawerBody {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerBody, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvDrawerBody, "[mlvDrawerBody]", never, {}, {}, never, ["*"], true, never>;
+}
+
+declare class MlvDrawerFooter {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerFooter, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvDrawerFooter, "[mlvDrawerFooter]", never, {}, {}, never, never, true, never>;
+}
+
+interface MlvDrawerSectionState {
+    id: Signal<string>;
+    label: Signal<string>;
+    elementRef: ElementRef;
+}
+interface MlvDrawerSectionConfig {
+    id: string;
+    label: string;
+    element: ElementRef;
+}
+interface MlvDrawerSectionIntersection {
+    intersecting: boolean;
+    threshold: number;
+    id: string;
+}
+declare class MlvDrawerSectionsService implements OnDestroy {
+    readonly sections: _angular_core.WritableSignal<Map<string, MlvDrawerSectionState>>;
+    readonly intersectedSections: _angular_core.WritableSignal<Record<string, MlvDrawerSectionIntersection>>;
+    readonly currentScrolledSection: Signal<MlvDrawerSectionState | null | undefined>;
+    readonly normalizedSections: Signal<MlvDrawerSectionState[]>;
+    private _observer;
+    constructor();
+    /**
+     * Registers a section so it appears in `normalizedSections` and is observed
+     * for scroll position.
+     *
+     * A **new** `Map` is stored rather than the existing one being mutated:
+     * signals compare with `Object.is`, so returning the same reference from
+     * `update()` is not a change and neither `normalizedSections` nor the
+     * observer effect would ever see the section.
+     */
+    register(section: MlvDrawerSectionState): void;
+    /** Removes a section from tracking. See {@link register} for why the map is copied. */
+    unregister(section: MlvDrawerSectionState): void;
+    destroyObservers(): void;
+    initObservers(): void;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerSectionsService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MlvDrawerSectionsService>;
+}
+
+declare class MlvDrawerSection implements MlvDrawerSectionState, OnInit, OnDestroy {
+    readonly label: _angular_core.InputSignal<string>;
+    readonly id: _angular_core.InputSignal<string>;
+    readonly elementRef: ElementRef<any>;
+    /** @private Scoped service tracking section registration and scroll-active state. */
+    private readonly _sectionService;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerSection, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvDrawerSection, "[mlvDrawerSection]", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+declare class MlvDrawerSections {
+    /** @protected Service exposing the registered drawer sections and the currently scrolled section. */
+    protected readonly sectionsService: MlvDrawerSectionsService;
+    /** @protected Two-way open state of the section-navigation popup. */
+    protected readonly isOpen: _angular_core.WritableSignal<boolean>;
+    /**
+     * @protected Whether the navigator has anything to navigate between.
+     *
+     * A single registered section produced a "Meta ▾" menu whose only entry was
+     * the section already on screen, so the control is suppressed below two.
+     */
+    protected readonly _hasMultipleSections: _angular_core.Signal<boolean>;
+    /** @private Host used to scope body lookup to this drawer instance. */
+    private readonly _host;
+    navigateToSection(section: ElementRef): void;
+    scrollIntoViewWithScrollableContainer(baseElement: Element | null | undefined, destinationElement: Element | null | undefined, topMargin?: number): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDrawerSections, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvDrawerSections, "mlv-drawer-sections", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Generates a route configuration that opens a component inside a routed drawer.
+ * When the drawer closes, the router navigates back to the parent route.
+ *
+ * The component receives the shell's `Injector`, so it can inject `ActivatedRoute`
+ * to access route params, resolved data, and query params. It can also inject
+ * `MlvDrawerRef` to close itself programmatically.
+ *
+ * @param component - The component to render inside the drawer. Can be an eager class reference
+ *   or a lazy import function (e.g., `() => import('./my-drawer.component')`).
+ * @param options - Route path, named outlet, and drawer configuration options.
+ * @returns A `Route` object to include in your route configuration.
+ *
+ * @example
+ * ```ts
+ * // Lazy-loaded drawer route
+ * {
+ *   path: 'users',
+ *   component: UsersListPage,
+ *   children: [
+ *     mlvGenerateRoutableDrawerRoute(
+ *       () => import('./user-details.component'),
+ *       { path: ':id', position: 'right', size: '500px' },
+ *     ),
+ *   ],
+ * }
+ *
+ * // With guards and resolvers (spread the returned route)
+ * {
+ *   ...mlvGenerateRoutableDrawerRoute(() => import('./details'), { path: ':id' }),
+ *   canActivate: [authGuard],
+ *   resolve: { user: userResolver },
+ * }
+ * ```
+ */
+declare function mlvGenerateRoutableDrawerRoute(component: Type<unknown> | (() => Promise<DefaultExport<Type<unknown>> | Type<unknown>>), { path, outlet, ...drawerOptions }?: {
+    path?: string;
+    outlet?: string;
+} & Omit<MlvDrawerConfig, 'data' | 'injector'>): Route;
+
+export { DRAWER_DATA, MlvDrawerBody as DrawerBodyDirective, MlvDrawer, MlvDrawerBody, MlvDrawerContent, MlvDrawerFooter, MlvDrawerHeader, MlvDrawerRef, MlvDrawerSection, MlvDrawerSections, MlvDrawerSectionsService, MlvDrawerService, mlvGenerateRoutableDrawerRoute };
+export type { MlvDrawerConfig, MlvDrawerPosition, MlvDrawerSectionConfig, MlvDrawerSectionIntersection, MlvDrawerSectionState };