ngx-kit 7.4.0 → 8.0.0

package/types/ngx-kit-drag-resize.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { TemplateRef, EventEmitter, InjectionToken, OnInit, OnDestroy, ElementRef, Renderer2 } from '@angular/core';
+import { TemplateRef, EventEmitter, InjectionToken, OnInit, OnDestroy, ElementRef, Renderer2, AfterContentInit, Injector } from '@angular/core';
 
 interface IPosition {
     x: number;
@@ -12,6 +12,7 @@ interface IPosition {
  * Lists register themselves automatically when `NgxDropListGroup` wraps them.
  */
 declare class DropListGroupRef {
+    el?: HTMLElement;
     readonly lists: Set<DropListRef<any>>;
     add(list: DropListRef<any>): void;
     remove(list: DropListRef<any>): void;
@@ -23,16 +24,26 @@ declare class PlaceHolderRef {
     dropList?: DropListRef;
     element?: HTMLElement;
     private _visible;
+    /**
+     * Angular embedded view created from `tpl`.
+     */
+    private _view?;
     attach(container: HTMLElement, source: HTMLElement, reference?: Node | null): HTMLElement;
     detach(): void;
     get visible(): boolean;
 }
 
 /**
- * DropListRef is intentionally generic, while the positional sorting strategy
- * works on DragRef<any>. The public DropList/DragRef relationship is invariant
- * because IDropEvent<T> contains T in a callback position. Keep the strongly
- * typed Set here, and narrow only at the DOM-local bridge / strategy boundary.
+ * A drop list.
+ *
+ * Membership (`_draggables`) only ever reflects which draggables *belong* to this list in the
+ * template. It is never changed by dragging. Everything that is transient during a drag lives
+ * in a single `SortSession` (see sorting/sort-session.ts) that is created when a drag enters
+ * the list and disposed when it leaves or the drag ends:
+ *
+ *  - the list the drag started in keeps its session for the whole drag (its placeholder holds
+ *    the item's original slot, so leaving and re-entering is stable);
+ *  - any other list gets a fresh session on every entry and drops it on every exit.
  */
 declare class DropListRef<T = any> {
     data?: T;
@@ -40,34 +51,98 @@ declare class DropListRef<T = any> {
     disableSort: boolean;
     connectedTo: HTMLElement[];
     dropListGroup?: DropListGroupRef | null;
+    /** Duration (ms) of the sibling slide animation. `0` disables animation. */
+    sortAnimationDuration: number;
     readonly _draggables: Set<DragRef<T>>;
     readonly onDrop: EventEmitter<IDropEvent<T>>;
-    private strategy;
-    private active;
-    private previousIndex;
+    private session;
     private placeholder?;
+    customPlaceholder?: PlaceHolderRef;
+    private activeDrag;
+    private isOrigin;
+    private hovered;
+    private hit;
+    /** Pre-insertion geometry of a foreign list, restored when the drag leaves it. */
+    private naturalHit;
+    private hitCached;
     addItem(item: DragRef<T>): void;
     removeItem(item: DragRef<T>): void;
     isConnectedTo(other: DropListRef<any>): boolean;
+    /** Measure the list and its clipping ancestors once, at drag start. */
+    _cacheGeometry(): void;
+    /**
+     * Is the point over the *visible* part of this list? Scroll-aware without re-measuring.
+     *
+     * The list box and every clipping ancestor are tracked separately because they react to scroll
+     * differently: scrolling a container moves the list but not the container's own clip window.
+     */
+    _containsPoint(x: number, y: number): boolean;
+    /** Approximate area, used to break ties between overlapping, unrelated lists. */
+    _area(): number;
+    _onScroll(): void;
+    /** Re-measure after a viewport resize. */
+    _refresh(): void;
+    /** Backwards-compatible entry point: makes this list the drag's target. */
     createPlaceholder(drag: DragRef<T>): PlaceHolderRef;
+    /** The drag pointer entered this list (or the drag started inside it). */
     enter(drag: DragRef<T>, x?: number, y?: number): void;
+    /** Re-evaluate the insertion index for the pointer. Returns the new index, or null if unchanged. */
     sortItem(drag: DragRef<T>, position: IPosition): number | null;
+    /** The pointer left this list. */
+    exit(drag: DragRef<T>): void;
+    /**
+     * Ends the drag for this list. Returns the drop event when the pointer was released over this
+     * list, `null` otherwise (nothing to emit). All transient state is disposed either way.
+     */
+    _finish(drag: DragRef<T>, commit: boolean): IDropEvent<T> | null;
+    /** Compatibility wrapper: finish + emit. */
     finishDrag(drag: DragRef<T>): void;
-    exit(_drag: DragRef<T>): void;
     resetSortTransforms(): void;
     getFinalIndex(): number;
     getItemIndex(item: DragRef<T>): number;
+    /** End of the drag: dispose EVERYTHING this list holds, including cached geometry. Idempotent. */
+    _release(drag?: DragRef<T>): void;
+    /** Dispose the sort session, placeholder and drag ownership. */
+    private releaseSession;
+    private begin;
+    /**
+     * First placement into a list that does not contain the item yet: the node the placeholder
+     * must be inserted before (null = append). Same pure resolver as sorting, no hysteresis.
+     */
+    private foreignInsertionReference;
+    private otherSlots;
     private indexOf;
-    private reset;
-    private copyPlaceholderGeometry;
+    private lockPlaceholderGeometry;
+}
+
+declare class DragDropService {
+    readonly drags: _angular_core.WritableSignal<readonly DragRef<unknown>[]>;
+    readonly dropLists: _angular_core.WritableSignal<readonly DropListRef<any>[]>;
+    readonly activeDrag: _angular_core.WritableSignal<DragRef<unknown> | null>;
+    registerDragItem(ref: DragRef<any>): void;
+    removeDragItem(ref: DragRef<any>): void;
+    registerDropList(ref: DropListRef): void;
+    removeDropList(ref: DropListRef<any>): void;
+    begin(ref: DragRef<any>): void;
+    end(ref: DragRef<any>): void;
+    cancelActive(): void;
     /**
-     * The sorting strategy only needs a read-only collection of draggable refs.
-     * Using DragRef<any> at this internal boundary avoids the invariant generic
-     * relationship between DragRef<T> and DragRef<unknown>.
+     * Which drop list is under `point`?
+     *
+     * - Only lists connected to the drag's ORIGIN list qualify (connectivity is not transitive, so
+     *   A→B→C never lets an item hop A→C). Without an origin (a free-drag element) nothing
+     *   qualifies: free dragging is never captured by a list.
+     * - Only the visible (clip-aware) part of a list counts.
+     * - A list inside the dragged element itself is never a target.
+     * - Nested lists: the innermost qualifying list wins. Among unrelated overlapping lists the
+     *   current one is kept (no flicker), otherwise the smallest.
      */
-    private getStrategyItems;
-    private asStrategyDrag;
-    private publishDragItems;
+    findDropList(point: {
+        x: number;
+        y: number;
+    }, current?: DropListRef | null, origin?: DropListRef | null, dragEl?: HTMLElement | null): DropListRef | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DragDropService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<DragDropService>;
 }
 
 type DragAxis = 'x' | 'y' | undefined;
@@ -76,8 +151,16 @@ declare class DragRef<T = unknown> {
     el: HTMLElement;
     boundary?: HTMLElement;
     lockAxis?: DragAxis;
+    /**
+     * The list this draggable BELONGS to (set by the template). Dragging never changes it.
+     * The list the pointer is currently over is `activeDropList`.
+     */
     dropList: DropListRef<T> | null;
     dropListGroup?: DropListGroupRef | null;
+    /** Used to find the drop list under the pointer. Set by the directive; optional. */
+    service?: DragDropService;
+    /** Drop list currently under the pointer during a drop-list drag (null = outside every list). */
+    activeDropList: DropListRef<T> | null;
     placeholder?: PlaceHolderRef;
     originDropList: DropListRef<T> | null;
     originIndex: number;
@@ -97,6 +180,13 @@ declare class DragRef<T = unknown> {
     private sourceVisibility;
     private sourceDisplay;
     private sourcePointerEvents;
+    private sourceTransition;
+    /** True while a drop-list drag (body preview + placeholder) is in progress. Free drag: always false. */
+    private listDrag;
+    private cachedLists;
+    private lastEffective;
+    private scrollListener?;
+    private resizeListener?;
     init(): void;
     withDropList(list: DropListRef<T> | null): this;
     clearDropList(): void;
@@ -106,6 +196,12 @@ declare class DragRef<T = unknown> {
     nudge(dx: number, dy: number): void;
     endDrag(): void;
     cancelDrag(): void;
+    /** Abort without emitting anything (the directive was destroyed mid-drag). Idempotent. */
+    dispose(): void;
+    /** True while a drop-list drag is running. */
+    get isListDrag(): boolean;
+    /** Inline `display` the source element had before it was hidden for the drag. */
+    get originalDisplay(): string;
     get x(): number;
     get y(): number;
     get pointer(): IPosition;
@@ -118,6 +214,15 @@ declare class DragRef<T = unknown> {
      */
     notifyScroll(dx: number, dy: number): void;
     private applyTransform;
+    private beginListDrag;
+    /** Decide which list is under the pointer, switch if needed, then re-sort in the active one. */
+    private updateDropTarget;
+    /**
+     * Single teardown path for every way a drop-list drag can end (drop on a list, drop outside,
+     * Escape, pointercancel, destroy). Everything transient is removed here, so nothing can leak
+     * regardless of how the drag ended. Only then is the drop event emitted.
+     */
+    private finishListDrag;
     private updatePreview;
 }
 
@@ -148,25 +253,6 @@ interface IResizableOutput {
     direction: ResizeDirection;
 }
 
-declare class DragDropService {
-    readonly drags: _angular_core.WritableSignal<readonly DragRef<unknown>[]>;
-    readonly dropLists: _angular_core.WritableSignal<readonly DropListRef<any>[]>;
-    readonly activeDrag: _angular_core.WritableSignal<DragRef<unknown> | null>;
-    registerDragItem(ref: DragRef<any>): void;
-    removeDragItem(ref: DragRef<any>): void;
-    registerDropList(ref: DropListRef): void;
-    removeDropList(ref: DropListRef<any>): void;
-    begin(ref: DragRef<any>): void;
-    end(ref: DragRef<any>): void;
-    cancelActive(): void;
-    findDropList(point: {
-        x: number;
-        y: number;
-    }, current?: DropListRef | null): DropListRef | null;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DragDropService, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<DragDropService>;
-}
-
 declare const NGX_DRAGGABLE: InjectionToken<NgxDraggable<unknown>>;
 declare class NgxDraggable<T = unknown> implements OnInit, OnDestroy {
     private readonly host;
@@ -205,6 +291,8 @@ declare class NgxDraggable<T = unknown> implements OnInit, OnDestroy {
     private removeUp?;
     private removeKeydown?;
     private removeEscape?;
+    private removeCancel?;
+    private removeLostCapture?;
     private scrollTarget;
     private lastScroll;
     private lastWindowScroll;
@@ -222,6 +310,8 @@ declare class NgxDraggable<T = unknown> implements OnInit, OnDestroy {
     private stopScrollTracking;
     private pointerMove;
     private pointerUp;
+    /** Browser cancelled the pointer (touch takeover, lost capture...). */
+    private pointerCancel;
     private cancel;
     private finish;
     /** Arrow-key movement for keyboard/assistive-tech users. Shift multiplies the step by 4. */
@@ -277,29 +367,35 @@ declare class NgxResizable {
 }
 
 declare const NGX_DROPLIST: InjectionToken<NgxDropList<any>>;
-declare class NgxDropList<T = any> implements OnInit, OnDestroy {
+declare class NgxDropList<T = any> implements OnInit, OnDestroy, AfterContentInit {
     private readonly el;
     readonly _ref: DropListRef<T>;
     set data(value: T);
     set connectedTo(value: HTMLElement[] | null | undefined);
     set disableSort(value: boolean);
     readonly drop: EventEmitter<IDropEvent<T>>;
+    private readonly customPlaceholder?;
+    private sub?;
     private readonly service;
     private readonly group;
     constructor(el: ElementRef<HTMLElement>);
     ngOnInit(): void;
+    ngAfterContentInit(): void;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxDropList<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgxDropList<any>, "[NgxDropList],[ngxDropList]", never, { "data": { "alias": "data"; "required": false; }; "connectedTo": { "alias": "connectedTo"; "required": false; }; "disableSort": { "alias": "disableSort"; "required": false; }; }, { "drop": "drop"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgxDropList<any>, "[NgxDropList],[ngxDropList]", never, { "data": { "alias": "data"; "required": false; }; "connectedTo": { "alias": "connectedTo"; "required": false; }; "disableSort": { "alias": "disableSort"; "required": false; }; }, { "drop": "drop"; }, ["customPlaceholder"], never, true, never>;
 }
 
 declare const NGX_DROPLIST_GROUP: InjectionToken<NgxDropListGroup>;
 /** Wrap several `ngxDropList`s to let items move freely between them. */
 declare class NgxDropListGroup implements OnDestroy {
     readonly _ref: DropListGroupRef;
+    protected readonly el: ElementRef<any>;
+    injector: Injector;
+    constructor();
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxDropListGroup, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgxDropListGroup, "[NgxDropListGroup],[ngxDropListGroup]", never, {}, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgxDropListGroup, "[NgxDropListGroup],[ngxDropListGroup]", ["ngxDropListGroup"], {}, {}, never, never, true, never>;
 }
 
 declare const NGX_PLACEHOLDER: InjectionToken<PlaceHolderRef>;

package/types/{ngx-kit-gallery.d.ts → ngx-kit-image-viewer.d.ts}

@@ -4,13 +4,8 @@ interface NgxImageViewerItem {
     src: string;
     alt?: string;
     caption?: string;
-    /** نام فایل هنگام دانلود؛ نبود یعنی از روی src حدس زده می‌شه */
     downloadFileName?: string;
 }
-/**
- * هر دکمه‌ی نوار ابزار جدا فعال/غیرفعال می‌شه — دقیقاً طبق خواسته: «این
- * دکمه‌های کانفیگی باشه که هر کدوم خواست فعال کنه».
- */
 interface NgxImageViewerToolbarConfig {
     prevNext?: boolean;
     counter?: boolean;
@@ -47,7 +42,7 @@ declare const NGX_IMAGE_VIEWER_DEFAULT_TOOLBAR: Required<NgxImageViewerToolbarCo
  * ngx-kit/dialog (یا هر overlay دیگه) قرار بگیره — خودش به هیچ‌کدوم وابسته
  * نیست، فقط با closed خروجی به بیرون خبر می‌ده که «ببندم».
  */
-declare class NgxImageViewerComponent {
+declare class NgxImageViewer {
     images: _angular_core.InputSignal<NgxImageViewerItem[]>;
     startIndex: _angular_core.InputSignal<number>;
     toolbar: _angular_core.InputSignal<NgxImageViewerToolbarConfig>;
@@ -103,37 +98,8 @@ declare class NgxImageViewerComponent {
     private applyZoomAt;
     private clientXOf;
     private clientYOf;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxImageViewerComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxImageViewerComponent, "ngx-image-viewer", never, { "images": { "alias": "images"; "required": true; "isSignal": true; }; "startIndex": { "alias": "startIndex"; "required": false; "isSignal": true; }; "toolbar": { "alias": "toolbar"; "required": false; "isSignal": true; }; "minZoom": { "alias": "minZoom"; "required": false; "isSignal": true; }; "maxZoom": { "alias": "maxZoom"; "required": false; "isSignal": true; }; "zoomStep": { "alias": "zoomStep"; "required": false; "isSignal": true; }; }, { "indexChange": "indexChange"; "closed": "closed"; }, never, never, true, never>;
-}
-
-interface NgxImageViewerOpenOptions {
-    startIndex?: number;
-    toolbar?: NgxImageViewerToolbarConfig;
-    minZoom?: number;
-    maxZoom?: number;
-    zoomStep?: number;
-}
-/**
- * راه میان‌بر برای وقتی که کاربر می‌خواد ویوئر رو داخل یه دیالوگِ تمام‌صفحه
- * باز کنه، بدون این‌که خودش دستی wire کنه. اگه کسی می‌خواد داخل دیالوگِ
- * خودش (مثلاً ngx-kit/dialog) بذارتش، کافیه مستقیم از NgxImageViewerComponent
- * استفاده کنه — این سرویس صرفاً یه میان‌بَره، وابستگی اجباری نیست.
- *
- * دقیقاً همون الگوی امن‌شده‌ی NgxMessageService: با Map<id, ComponentRef> و
- * detachView قبل از destroy، تا اون نشتی حافظه‌ای که قبلاً توی message
- * service پیدا و رفع شد، اینجا از اول تکرار نشه.
- */
-declare class NgxImageViewerService {
-    private readonly appRef;
-    private readonly envInjector;
-    private nextId;
-    private readonly openInstances;
-    open(images: NgxImageViewerItem[], options?: NgxImageViewerOpenOptions): {
-        close: () => void;
-    };
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxImageViewerService, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NgxImageViewerService>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxImageViewer, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxImageViewer, "ngx-image-viewer", never, { "images": { "alias": "images"; "required": true; "isSignal": true; }; "startIndex": { "alias": "startIndex"; "required": false; "isSignal": true; }; "toolbar": { "alias": "toolbar"; "required": false; "isSignal": true; }; "minZoom": { "alias": "minZoom"; "required": false; "isSignal": true; }; "maxZoom": { "alias": "maxZoom"; "required": false; "isSignal": true; }; "zoomStep": { "alias": "zoomStep"; "required": false; "isSignal": true; }; }, { "indexChange": "indexChange"; "closed": "closed"; }, never, never, true, never>;
 }
 
 interface PanZoomState {
@@ -164,5 +130,5 @@ declare function downloadImage(src: string, filename?: string): Promise<void>;
 /** یه پنجره‌ی جدید فقط با همون تصویر باز می‌کنه و بعد از لود، print می‌زنه؛ با DOM API (نه innerHTML) پس در برابر src مخرب امنه */
 declare function printImage(src: string): void;
 
-export { NGX_IMAGE_VIEWER_DEFAULT_TOOLBAR, NgxImageViewerComponent, NgxImageViewerService, clamp, distanceBetweenTouches, downloadImage, midpointOfTouches, printImage, zoomAroundPoint };
-export type { NgxImageViewerItem, NgxImageViewerOpenOptions, NgxImageViewerToolbarConfig, PanZoomState };
+export { NGX_IMAGE_VIEWER_DEFAULT_TOOLBAR, NgxImageViewer, clamp, distanceBetweenTouches, downloadImage, midpointOfTouches, printImage, zoomAroundPoint };
+export type { NgxImageViewerItem, NgxImageViewerToolbarConfig, PanZoomState };

package/types/ngx-kit-side-nav.d.ts

@@ -0,0 +1,53 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, OnInit, OnDestroy } from '@angular/core';
+import * as ngx_kit_side_nav from 'ngx-kit/side-nav';
+
+declare class NgxDrawerMenu {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxDrawerMenu, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxDrawerMenu, "[ngxDrawerMenu]", never, {}, {}, never, never, true, never>;
+}
+
+declare class NgxDrawerMenuToggle {
+    readonly hideOnBreakPoint: i0.InputSignal<boolean>;
+    protected readonly sideNav: ngx_kit_side_nav.NgxSideNav;
+    hide: i0.WritableSignal<boolean>;
+    constructor();
+    protected onClick(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxDrawerMenuToggle, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxDrawerMenuToggle, "[ngxDrawerMenuToggle]", never, { "hideOnBreakPoint": { "alias": "hideOnBreakPoint"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+type NgxSideNavMode = 'push' | 'overlay';
+
+declare const NGX_SIDE_NAV: InjectionToken<NgxSideNav>;
+declare class NgxSideNav implements OnInit, OnDestroy {
+    readonly open: i0.ModelSignal<boolean>;
+    readonly width: i0.InputSignal<number>;
+    readonly breakpoint: i0.InputSignal<number | null>;
+    readonly mode: i0.InputSignal<NgxSideNavMode>;
+    shouldShowOverlay: i0.WritableSignal<boolean>;
+    private mediaQuery?;
+    readonly isMatchMediaQuery: i0.WritableSignal<boolean>;
+    private removeMediaQueryListener?;
+    protected readonly win: Window | null;
+    constructor();
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    initialize(): void;
+    setupMediaQuery(): void;
+    onResize(): void;
+    toggleMenu(): void;
+    closeMenu(): void;
+    openMenu(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxSideNav, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<NgxSideNav, "ngx-side-nav", never, { "open": { "alias": "open"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "breakpoint": { "alias": "breakpoint"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; }, { "open": "openChange"; }, never, ["[ngxDrawerMenu]", "*"], true, never>;
+}
+
+declare class NgxSideNavModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxSideNavModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<NgxSideNavModule, never, [typeof NgxDrawerMenu, typeof NgxDrawerMenuToggle, typeof NgxSideNav], [typeof NgxDrawerMenu, typeof NgxDrawerMenuToggle, typeof NgxSideNav]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<NgxSideNavModule>;
+}
+
+export { NGX_SIDE_NAV, NgxDrawerMenu, NgxDrawerMenuToggle, NgxSideNav, NgxSideNavModule };
+export type { NgxSideNavMode };

package/drawer-menu/README.md

@@ -1,125 +0,0 @@
-# ngx-kit/drawer-menu
-
-A gesture-first Angular navigation drawer designed for desktop and mobile.
-
-## Highlights
-
-- Logical `start` / `end` placement with RTL/LTR support.
-- Mouse + touch + pen drag using Pointer Events.
-- Open from the screen edge when closed.
-- Drag the drawer itself to close it.
-- Live 0..1 gesture progress — effects react while dragging.
-- Fabric / curtain / spring / elastic effects.
-- `overlay`, `push`, and `reveal` content modes.
-- Desktop/mobile responsive state.
-- True docked desktop sidebar: open means it occupies layout space and clicking the page never closes it.
-- Mobile overlay behavior with backdrop and edge swipe.
-- Pin/unpin support.
-- Controlled state with `[(open)]`.
-- Reduced-motion support.
-- Escape and backdrop closing.
-
-## Recommended configuration
-
-```html
-<ngx-drawer-menu
-  side="start"
-  mode="push"
-  effect="fabric"
-  [width]="300"
-  [openOnDesktop]="true"
-  [openOnMobile]="false"
-  [mobileBreakpoint]="960"
-  [(open)]="drawerOpen"
-  [(pinned)]="drawerPinned">
-  <router-outlet />
-
-  <div drawerContent>
-    <!-- navigation -->
-  </div>
-</ngx-drawer-menu>
-```
-
-## Behavior model
-
-The drawer owns one continuous `progress` value between `0` and `1`.
-
-- `0`: fully closed.
-- `1`: fully open.
-- Pointer dragging directly changes progress.
-- On release, velocity and the configured threshold decide the final state.
-
-This is the key to getting a physical-feeling drawer instead of a drawer that simply jumps between CSS classes.
-
-## Inputs
-
-| Input               | Default   | Purpose                                                      |
-| ------------------- | --------- | ------------------------------------------------------------ |
-| `side`              | `start`   | Logical drawer side.                                         |
-| `mode`              | `overlay` | `overlay`, `push`, or `reveal`.                              |
-| `effect`            | `fabric`  | `slide`, `spring`, `fabric`, `curtain`, `elastic`, `reveal`. |
-| `width`             | `300`     | Drawer width in px.                                          |
-| `maxWidth`          | `420`     | Safety cap for drawer width.                                 |
-| `edgeSize`          | `34`      | Edge swipe activation area.                                  |
-| `swipeEnabled`      | `true`    | Enables gesture interaction.                                 |
-| `backdropClose`     | `true`    | Close on backdrop press.                                     |
-| `escapeClose`       | `true`    | Close on Escape.                                             |
-| `open`              | `true`    | Two-way state via `[(open)]`.                                |
-| `pinned`            | `false`   | Persistent drawer state via `[(pinned)]`.                    |
-| `mobileBreakpoint`  | `768`     | Mobile breakpoint.                                           |
-| `openOnDesktop`     | `true`    | State on desktop.                                            |
-| `openOnMobile`      | `false`   | State on mobile/tablet.                                      |
-| `respondToViewport` | `true`    | Enables live responsive switching.                           |
-| `transitionMs`      | `420`     | Settle animation duration.                                   |
-
-## Responsive behavior
-
-By default:
-
-- Desktop >= 768px: open.
-- Mobile < 768px: closed.
-- Crossing the breakpoint updates the drawer live.
-- A pinned drawer is not closed by responsive rules.
-
-A full `responsive` object is also available when a single config object is preferable:
-
-```html
-<ngx-drawer-menu
-  [responsive]="{
-    mode: 'auto',
-    breakpoint: 960,
-    desktopOpen: true,
-    mobileOpen: false,
-    respectPinned: true
-  }"></ngx-drawer-menu>
-```
-
-## Recommended responsive behavior
-
-When `respondToViewport` is enabled, the drawer uses a real sidebar on desktop and an overlay drawer on mobile by default:
-
-```html
-<ngx-drawer-menu
-  side="start"
-  [responsive]="{
-    mode: 'auto',
-    breakpoint: 960,
-    desktopOpen: true,
-    mobileOpen: false,
-    desktopBehavior: 'dock',
-    mobileBehavior: 'overlay',
-    respectPinned: true
-  }"
-  effect="fabric"
-  [width]="300">
-  <router-outlet />
-  <nav drawerContent>...</nav>
-</ngx-drawer-menu>
-```
-
-In this setup:
-
-- `>= 960px`: the open drawer is a real docked sidebar; it owns layout width and does not create a backdrop.
-- `< 960px`: the drawer is an overlay; the page is dimmed and clicking the backdrop can close it.
-- On desktop the drawer can still be dragged closed from its full-height edge handle.
-- When closed, the screen edge remains a mouse/touch drag target and opens the drawer.