ngx-kit 6.2.0 → 7.0.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/drag-resize/README.md

@@ -0,0 +1,55 @@
+# ngx-kit drag-resize
+
+## Design goals
+
+The package uses Angular 22 signals and Pointer Events. Dragging and resizing remain transform/pointer based, while drop-list sorting uses live DOM geometry.
+
+### Professional drop-list behavior
+
+When a drag starts inside a drop list:
+
+- the real item remains in its original DOM position as a hidden layout anchor;
+- exactly one placeholder preserves the item's layout space;
+- a fully styled visual clone is moved to `document.body`, so overflow/scroll containers cannot clip the drag;
+- the body preview copies computed styles recursively, including CSS custom properties and descendant styles;
+- entering, leaving and switching lists always disposes the previous placeholder before creating the next one;
+- sorting uses current DOM geometry instead of stale start-of-drag rectangles;
+- `previousIndex` is captured from the origin list and `currentIndex` is the final placeholder position;
+- dropping outside every connected list cancels the drag instead of accidentally committing it;
+- auto-scroll follows the currently hovered drop list.
+
+## Basic drop list
+
+```html
+<div NgxDropList (drop)="onDrop($event)">
+  @for (item of items; track item.id) {
+    <article NgxDraggable [data]="item">
+      {{ item.name }}
+    </article>
+  }
+</div>
+```
+
+For most UIs, wrap related lists in `NgxDropListGroup` so they are connected automatically:
+
+```html
+<div NgxDropListGroup>
+  <div NgxDropList>...</div>
+  <div NgxDropList>...</div>
+  <div NgxDropList>...</div>
+</div>
+```
+
+The emitted event follows the familiar `previousIndex/currentIndex` model, making it suitable for `moveItemInArray` / `transferArrayItem` style data updates.
+
+## Resize
+
+```html
+<article
+  NgxResizable
+  [minWidth]="120"
+  [minHeight]="80"
+  [directions]="['n','e','s','w','ne','se','sw','nw']"></article>
+```
+
+Resize is pointer based, supports all eight directions, minimum/maximum constraints and optional pixel snapping.

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
-
-```html
-<ngx-drawer-menu
-  side="start"
-  effect="jelly"
-  contentBehavior="push"
-  [width]="280"
-  [openOnDesktop]="true"
-  [openOnMobile]="false"
-  [(open)]="isOpen"
->
-  <div drawerContent>
-    <!-- menu content -->
-    <a routerLink="/home">Home</a>
-    <a routerLink="/settings">Settings</a>
-  </div>
-
-  <!-- main page content (default, no select) -->
-  <router-outlet />
-</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.
+# 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.