ngx-kit 6.1.0 → 6.3.0

package/dialog/README.md

@@ -1,92 +1,92 @@
-# ngx-kit/dialog
-
-Modal/dialog built on the browser's native `<dialog>` — no manual overlay, no third-party library.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Setup
-
-```ts
-// app.config.ts
-import { ApplicationConfig, importProvidersFrom } from '@angular/core';
-import { NgxDialogModule } from 'ngx-kit/dialog';
-
-export const appConfig: ApplicationConfig = {
-  providers: [importProvidersFrom(NgxDialogModule)],
-};
-```
-
-## Opening a dialog
-
-With the static API (no manual service injection needed):
-
-```ts
-import { Dialog } from 'ngx-kit/dialog';
-
-const ref = Dialog.open(MyDialogComponent, {
-  data: { userId: 42 },
-  width: '480px',
-  allowCloseOnOutsideClick: true,
-  header: { enable: true, title: 'Edit user', showCloseButton: true },
-});
-
-ref.afterClosed.subscribe((result) => console.log('Result:', result));
-```
-
-Inside the dialog's component:
-
-```ts
-@Component({ ... })
-export class MyDialogComponent {
-  private ref = inject(NgxDialogRef);
-  data = inject(NGX_DIALOG_DATA); // the data passed via config.data
-
-  save() {
-    this.ref.close({ saved: true });
-  }
-}
-```
-
-### Layout directives inside a dialog
-
-```html
-<div *ngxDialogHeader>Custom title</div>
-<div *ngxDialogBody>Main content</div>
-<div *ngxDialogFooter>
-  <button (click)="save()">Save</button>
-</div>
-```
-
-## API
-
-### `Dialog.open<T>(component, config?)`
-
-| `config` field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `data` | `T` | `{}` | Data passed to the component inside the dialog |
-| `allowCloseOnOutsideClick` | `boolean` | `false` | Close when clicking the backdrop |
-| `containerClass` | `string` | `'ngx-kit'` | Extra class on the container |
-| `header.enable` / `header.title` / `header.showCloseButton` | | | Default header settings |
-| `footer.enable` | `boolean` | | Show the default footer |
-| `width` / `minWidth` / `maxWidth` | `string` | | Horizontal sizing |
-| `height` / `minHeight` / `maxHeight` | `string` | | Vertical sizing |
-| `injector` | `Injector` | | Custom injector for the inner component |
-
-### `NgxDialogRef`
-
-| Member | Description |
-| --- | --- |
-| `close(result?)` | Closes the dialog, optionally passing back a result |
-| `afterClosed: Observable<any>` | Emits `result` after the dialog closes |
-
-## SSR note
-
-`Dialog.open(...)` is a static/global API that's perfectly safe for a typical browser app. If you're using Angular SSR, this static instance is shared across concurrent server requests — instead of the static API, inject `NgxOverlayService` directly (which is per-injector/per-request safe).
-
-## Dark mode and RTL
-
-Supported automatically (`light-dark()` + CSS logical properties).
+# ngx-kit/dialog
+
+Modal/dialog built on the browser's native `<dialog>` — no manual overlay, no third-party library.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Setup
+
+```ts
+// app.config.ts
+import { ApplicationConfig, importProvidersFrom } from '@angular/core';
+import { NgxDialogModule } from 'ngx-kit/dialog';
+
+export const appConfig: ApplicationConfig = {
+  providers: [importProvidersFrom(NgxDialogModule)],
+};
+```
+
+## Opening a dialog
+
+With the static API (no manual service injection needed):
+
+```ts
+import { Dialog } from 'ngx-kit/dialog';
+
+const ref = Dialog.open(MyDialogComponent, {
+  data: { userId: 42 },
+  width: '480px',
+  allowCloseOnOutsideClick: true,
+  header: { enable: true, title: 'Edit user', showCloseButton: true },
+});
+
+ref.afterClosed.subscribe((result) => console.log('Result:', result));
+```
+
+Inside the dialog's component:
+
+```ts
+@Component({ ... })
+export class MyDialogComponent {
+  private ref = inject(NgxDialogRef);
+  data = inject(NGX_DIALOG_DATA); // the data passed via config.data
+
+  save() {
+    this.ref.close({ saved: true });
+  }
+}
+```
+
+### Layout directives inside a dialog
+
+```html
+<div *ngxDialogHeader>Custom title</div>
+<div *ngxDialogBody>Main content</div>
+<div *ngxDialogFooter>
+  <button (click)="save()">Save</button>
+</div>
+```
+
+## API
+
+### `Dialog.open<T>(component, config?)`
+
+| `config` field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `T` | `{}` | Data passed to the component inside the dialog |
+| `allowCloseOnOutsideClick` | `boolean` | `false` | Close when clicking the backdrop |
+| `containerClass` | `string` | `'ngx-kit'` | Extra class on the container |
+| `header.enable` / `header.title` / `header.showCloseButton` | | | Default header settings |
+| `footer.enable` | `boolean` | | Show the default footer |
+| `width` / `minWidth` / `maxWidth` | `string` | | Horizontal sizing |
+| `height` / `minHeight` / `maxHeight` | `string` | | Vertical sizing |
+| `injector` | `Injector` | | Custom injector for the inner component |
+
+### `NgxDialogRef`
+
+| Member | Description |
+| --- | --- |
+| `close(result?)` | Closes the dialog, optionally passing back a result |
+| `afterClosed: Observable<any>` | Emits `result` after the dialog closes |
+
+## SSR note
+
+`Dialog.open(...)` is a static/global API that's perfectly safe for a typical browser app. If you're using Angular SSR, this static instance is shared across concurrent server requests — instead of the static API, inject `NgxOverlayService` directly (which is per-injector/per-request safe).
+
+## Dark mode and RTL
+
+Supported automatically (`light-dark()` + CSS logical properties).

package/drawer-menu/README.md

@@ -1,77 +1,125 @@
 # ngx-kit/drawer-menu
 
-A side drawer menu with 7 different opening/closing effects (from simple to 3D/jelly), 3 behaviors for the page content (overlay/push/reveal), and a responsive default open/closed state based on screen size.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Basic usage
+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"
-  effect="jelly"
-  contentBehavior="push"
-  [width]="280"
+  mode="push"
+  effect="fabric"
+  [width]="300"
   [openOnDesktop]="true"
   [openOnMobile]="false"
-  [(open)]="isOpen"
->
+  [mobileBreakpoint]="960"
+  [(open)]="drawerOpen"
+  [(pinned)]="drawerPinned">
+  <router-outlet />
+
   <div drawerContent>
-    <!-- menu content -->
-    <a routerLink="/home">Home</a>
-    <a routerLink="/settings">Settings</a>
+    <!-- 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.                                   |
 
-  <!-- main page content (default, no select) -->
+## 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>
 ```
 
-## API
-
-| Input | Type | Default | Description |
-| --- | --- | --- | --- |
-| `side` | `'start' \| 'end'` | `'start'` | Logical — automatically flips under RTL |
-| `effect` | `'slide' \| 'curtain' \| 'jelly' \| 'pull' \| 'rotate3d' \| 'flip3d' \| 'scale'` | `'slide'` | The panel's own open/close effect (described below) |
-| `contentBehavior` | `'overlay' \| 'push' \| 'reveal'` | `'overlay'` | How the main page content behaves |
-| `width` | `number` | `280` | Panel width in pixels |
-| `swipeEnabled` | `boolean` | `true` | Open by swiping from the screen edge |
-| `swipeEdgeSize` | `number` | `24` | Width of the invisible edge zone that a swipe can start from |
-| `backdropClose` | `boolean` | `true` | Close on backdrop click (or dimming the content in push/reveal) |
-| `curtainStrips` | `number` | `7` | Only for `effect="curtain"` |
-| `open` | `boolean` (model, two-way) | `false` | Controllable via `[(open)]` |
-| `respondToViewport` | `boolean` | `true` | Crossing `mobileBreakpoint` **live** (not just on first load) syncs `open` with `openOnDesktop`/`openOnMobile` |
-| `openOnDesktop` / `openOnMobile` | `boolean` | `true` / `false` | |
-| `mobileBreakpoint` | `number` | `768` | |
-
-### Effects (`effect`)
-
-| Value | Description |
-| --- | --- |
-| `slide` | Classic simple slide |
-| `curtain` | Several same-colored vertical strips that collapse with a staggered delay, revealing the content |
-| `jelly` | A multi-stage spring oscillation that settles down (inspired by the [Jelly Slide Menu](https://dribbble.com/shots/2307371) effect) |
-| `pull` | A single rubber-band stretch |
-| `rotate3d` | A 3D rotation around a hinge, like a door opening |
-| `flip3d` | Flips with depth on the Z axis, like a book cover |
-| `scale` | Zooms in from the center with a fade |
-
-### Content behavior (`contentBehavior`)
-
-| Value | Description |
-| --- | --- |
-| `overlay` | Content stays in place, the drawer floats over it (with a backdrop) |
-| `push` | Content is pushed aside by the drawer's width |
-| `reveal` | Content shrinks/recedes slightly, as if the drawer is revealed behind it (the iOS effect) |
-
-## Architecture note: embedding inside a bounded area
-
-By default, the drawer takes up the full height of the nearest positioned ancestor (which is what you want for a full app shell). If you want to embed it inside a bounded card/area (not the whole page), just give that container `position: relative` and a defined height — the drawer will automatically confine itself to that box (thanks to the `perspective` it uses for 3D effects, which per the CSS spec creates a containing block for `position:fixed` descendants).
-
-## Dark mode and RTL
-
-Supported automatically; drag math (which, unlike CSS logical properties, needs the real physical direction) uses the shared `DirectionService`, so it works correctly even with a live `dir` change.
+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.