ngx-kit 7.1.0 → 7.3.0

package/gallery/README.md

@@ -1,71 +1,71 @@
-# ngx-kit/gallery
-
-A professional image viewer: takes a list of images, navigates them with ‹ › buttons (like a carousel), has a fully configurable toolbar (zoom, rotate, download, print, fullscreen), zoom via mouse scroll or two-finger pinch, and panning via drag once zoomed in.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Usage — directly in the page
-
-```html
-<ngx-image-viewer [images]="images" [toolbar]="{ print: false }" />
-```
-
-```ts
-images: NgxImageViewerItem[] = [
-  { src: '/img/1.jpg', alt: 'Image 1', caption: 'Alborz mountains' },
-  { src: '/img/2.jpg', alt: 'Image 2' },
-];
-```
-
-## Usage — inside a fullscreen dialog
-
-```ts
-import { NgxImageViewerService } from 'ngx-kit/gallery';
-
-constructor(private viewer: NgxImageViewerService) {}
-
-openGallery() {
-  this.viewer.open(this.images, { startIndex: 0 });
-}
-```
-
-`NgxImageViewerComponent` doesn't depend on any dialog (it only has a `closed` output) — if you want to put it inside your own dialog (e.g. `ngx-kit/dialog`), use the component directly; the service is just a convenience shortcut.
-
-## API
-
-### `<ngx-image-viewer>`
-
-| Input                              | Type                                  | Default           | Description                                         |
-| ---------------------------------- | ------------------------------------- | ----------------- | --------------------------------------------------- |
-| `images`                           | `NgxImageViewerItem[]` **(required)** |                   | `{ src, alt?, caption?, downloadFileName? }`        |
-| `startIndex`                       | `number`                              | `0`               |                                                     |
-| `toolbar`                          | `NgxImageViewerToolbarConfig`         | all `true`        | Each button can be toggled individually (see below) |
-| `minZoom` / `maxZoom` / `zoomStep` | `number`                              | `1` / `6` / `0.4` |                                                     |
-
-| Output        | Type     | Description                                                                                                                 |
-| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `indexChange` | `number` | The active image changed                                                                                                    |
-| `closed`      | `void`   | The user clicked the close button or pressed Esc (the component itself doesn't close anything; that's left to the consumer) |
-
-### `NgxImageViewerToolbarConfig`
-
-`prevNext`, `counter`, `zoomIn`, `zoomOut`, `resetZoom`, `rotateLeft`, `rotateRight`, `download`, `print`, `fullscreen`, `close` — all `boolean`, all default to `true` except `close` (`false`).
-
-## Interactions
-
-| Gesture                                     | Result                                                              |
-| ------------------------------------------- | ------------------------------------------------------------------- |
-| Mouse scroll                                | Zoom, relative to the point under the cursor (not the image center) |
-| Two-finger pinch (touch)                    | Zoom                                                                |
-| Drag with mouse or one finger (when zoomed) | Pan                                                                 |
-| ← / →                                       | Previous/next image                                                 |
-| + / -                                       | Zoom in/out                                                         |
-| Esc                                         | Emits `closed`                                                      |
-
-## Dark mode and RTL
-
-Supported automatically.
+# ngx-kit/gallery
+
+A professional image viewer: takes a list of images, navigates them with ‹ › buttons (like a carousel), has a fully configurable toolbar (zoom, rotate, download, print, fullscreen), zoom via mouse scroll or two-finger pinch, and panning via drag once zoomed in.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Usage — directly in the page
+
+```html
+<ngx-image-viewer [images]="images" [toolbar]="{ print: false }" />
+```
+
+```ts
+images: NgxImageViewerItem[] = [
+  { src: '/img/1.jpg', alt: 'Image 1', caption: 'Alborz mountains' },
+  { src: '/img/2.jpg', alt: 'Image 2' },
+];
+```
+
+## Usage — inside a fullscreen dialog
+
+```ts
+import { NgxImageViewerService } from 'ngx-kit/gallery';
+
+constructor(private viewer: NgxImageViewerService) {}
+
+openGallery() {
+  this.viewer.open(this.images, { startIndex: 0 });
+}
+```
+
+`NgxImageViewerComponent` doesn't depend on any dialog (it only has a `closed` output) — if you want to put it inside your own dialog (e.g. `ngx-kit/dialog`), use the component directly; the service is just a convenience shortcut.
+
+## API
+
+### `<ngx-image-viewer>`
+
+| Input                              | Type                                  | Default           | Description                                         |
+| ---------------------------------- | ------------------------------------- | ----------------- | --------------------------------------------------- |
+| `images`                           | `NgxImageViewerItem[]` **(required)** |                   | `{ src, alt?, caption?, downloadFileName? }`        |
+| `startIndex`                       | `number`                              | `0`               |                                                     |
+| `toolbar`                          | `NgxImageViewerToolbarConfig`         | all `true`        | Each button can be toggled individually (see below) |
+| `minZoom` / `maxZoom` / `zoomStep` | `number`                              | `1` / `6` / `0.4` |                                                     |
+
+| Output        | Type     | Description                                                                                                                 |
+| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `indexChange` | `number` | The active image changed                                                                                                    |
+| `closed`      | `void`   | The user clicked the close button or pressed Esc (the component itself doesn't close anything; that's left to the consumer) |
+
+### `NgxImageViewerToolbarConfig`
+
+`prevNext`, `counter`, `zoomIn`, `zoomOut`, `resetZoom`, `rotateLeft`, `rotateRight`, `download`, `print`, `fullscreen`, `close` — all `boolean`, all default to `true` except `close` (`false`).
+
+## Interactions
+
+| Gesture                                     | Result                                                              |
+| ------------------------------------------- | ------------------------------------------------------------------- |
+| Mouse scroll                                | Zoom, relative to the point under the cursor (not the image center) |
+| Two-finger pinch (touch)                    | Zoom                                                                |
+| Drag with mouse or one finger (when zoomed) | Pan                                                                 |
+| ← / →                                       | Previous/next image                                                 |
+| + / -                                       | Zoom in/out                                                         |
+| Esc                                         | Emits `closed`                                                      |
+
+## Dark mode and RTL
+
+Supported automatically.

package/gradient-picker/README.md

@@ -1,41 +1,41 @@
-# ngx-kit/gradient-picker
-
-A linear/radial gradient picker with multiple draggable color stops, outputting a ready-to-use CSS string.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Usage
-
-```html
-<ngx-input-gradient [(ngModel)]="gradientCss"></ngx-input-gradient>
-```
-
-Or as a directive on a plain input:
-
-```html
-<input type="text" [ngxInputGradient]="gradientCss" (change)="gradientCss = $event" />
-```
-
-The output is a valid CSS string like `linear-gradient(90deg, #ff0000 0%, #0000ff 100%)`, ready to use directly in `background`/`background-image`.
-
-## API
-
-| Input                              | Type                          | Default  | Description                                          |
-| ---------------------------------- | ----------------------------- | -------- | ---------------------------------------------------- |
-| `theme`                            | `'light' \| 'dark' \| 'auto'` | `'auto'` | Panel theme                                          |
-| `setInputBackground` _(directive)_ | `boolean`                     | `true`   | Sets the input's background to the selected gradient |
-| `change` _(directive)_             | `EventEmitter<string>`        |          | The new gradient string                              |
-
-## UI notes
-
-- Add a color stop by clicking on the gradient bar; drag to move it.
-- Double-click a stop to remove it (or use the delete button if shown).
-- Each stop's color is edited with the same `ngx-kit/color-picker` panel (this package depends on it).
-
-## Dark mode and RTL
-
-Supported automatically.
+# ngx-kit/gradient-picker
+
+A linear/radial gradient picker with multiple draggable color stops, outputting a ready-to-use CSS string.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Usage
+
+```html
+<ngx-input-gradient [(ngModel)]="gradientCss"></ngx-input-gradient>
+```
+
+Or as a directive on a plain input:
+
+```html
+<input type="text" [ngxInputGradient]="gradientCss" (change)="gradientCss = $event" />
+```
+
+The output is a valid CSS string like `linear-gradient(90deg, #ff0000 0%, #0000ff 100%)`, ready to use directly in `background`/`background-image`.
+
+## API
+
+| Input                              | Type                          | Default  | Description                                          |
+| ---------------------------------- | ----------------------------- | -------- | ---------------------------------------------------- |
+| `theme`                            | `'light' \| 'dark' \| 'auto'` | `'auto'` | Panel theme                                          |
+| `setInputBackground` _(directive)_ | `boolean`                     | `true`   | Sets the input's background to the selected gradient |
+| `change` _(directive)_             | `EventEmitter<string>`        |          | The new gradient string                              |
+
+## UI notes
+
+- Add a color stop by clicking on the gradient bar; drag to move it.
+- Double-click a stop to remove it (or use the delete button if shown).
+- Each stop's color is edited with the same `ngx-kit/color-picker` panel (this package depends on it).
+
+## Dark mode and RTL
+
+Supported automatically.

package/grid-layout/README.md

@@ -1,64 +1,64 @@
-# ngx-kit grid-layout
-
-## Angular 22 API
-
-The rewrite is intentionally signal-first. Inputs use Angular signal inputs, outputs use `output()`, and the grid engine exposes `signal()`/`computed()` state. There is no RxJS-driven layout loop.
-
-### Layout modes
-
-- `flow: 'free'` — the user can place items anywhere in the grid.
-- `flow: 'horizontal'` — horizontal-first placement.
-- `flow: 'vertical'` — vertical-first placement.
-- `compact: 'none'` — preserve empty cells.
-- `compact: 'vertical'` — pack upward.
-- `compact: 'horizontal'` — pack toward the start edge.
-- `compact: 'both'` — perform both passes.
-
-### RTL
-
-Use `[dir]="'rtl'"` or `options.rtl = 'auto'`. Logical `x=0` is always the start-most column. The rendering layer maps that logical coordinate to the physical left/right edge. This keeps persisted layouts direction-independent.
-
-### Collision behavior
-
-`allowOverlap` disables collision resolution. `pushItems` controls whether a dragged/resized item pushes colliding siblings during interaction. The final layout is normalized again when the pointer is released.
-
-### Example
-
-```html
-<ngx-grid-layout
-  [dir]="direction()"
-  [options]="{ cols: 12, rowHeight: 48, gap: 8, compact: 'vertical', pushItems: true }"
-  (layoutChange)="saveLayout($event)">
-  @for (item of layout(); track item.id) {
-  <ngx-grid-item [id]="item.id!" [config]="item">
-    <div class="widget">{{ item.id }}</div>
-  </ngx-grid-item>
-  }
-</ngx-grid-layout>
-```
-
-`ngx-grid-item` installs drag and resize behavior on its host. Resize recognizes all eight edges/corners and uses grid snapping supplied by the grid engine.
-
-> **Note on `[config]="item"` above:** `layout()` is a `computed()` that maps the
-> internal item list to a fresh array of fresh objects on every recompute, so
-> each item gets a *new* config object reference whenever anything in the grid
-> changes — even if the values are identical. `NgxGridItemComponent` and
-> `GridLayoutService` are written to tolerate this (they compare configs by
-> value before writing to any signal), so this pattern is safe to use as-is.
-> If you maintain your own item list instead, prefer keeping a stable object
-> reference per item and only replacing it when its values actually change —
-> it's cheaper and avoids relying on the library's internal guards.
-
-# Grid layout API reference
-
-| Option         | Meaning                                           |
-| -------------- | ------------------------------------------------- |
-| `cols`         | Number of logical columns.                        |
-| `rowHeight`    | Pixel row height or `fit`.                        |
-| `gap`          | Gap between cells in pixels.                      |
-| `flow`         | Free, horizontal-first, or vertical-first intent. |
-| `compact`      | Compaction direction.                             |
-| `allowOverlap` | Allow items to occupy the same cells.             |
-| `pushItems`    | Push siblings away during interaction.            |
-| `rtl`          | `true`, `false`, or `auto`.                       |
-| `animate`      | Reserved for the visual animation layer.          |
+# ngx-kit grid-layout
+
+## Angular 22 API
+
+The rewrite is intentionally signal-first. Inputs use Angular signal inputs, outputs use `output()`, and the grid engine exposes `signal()`/`computed()` state. There is no RxJS-driven layout loop.
+
+### Layout modes
+
+- `flow: 'free'` — the user can place items anywhere in the grid.
+- `flow: 'horizontal'` — horizontal-first placement.
+- `flow: 'vertical'` — vertical-first placement.
+- `compact: 'none'` — preserve empty cells.
+- `compact: 'vertical'` — pack upward.
+- `compact: 'horizontal'` — pack toward the start edge.
+- `compact: 'both'` — perform both passes.
+
+### RTL
+
+Use `[dir]="'rtl'"` or `options.rtl = 'auto'`. Logical `x=0` is always the start-most column. The rendering layer maps that logical coordinate to the physical left/right edge. This keeps persisted layouts direction-independent.
+
+### Collision behavior
+
+`allowOverlap` disables collision resolution. `pushItems` controls whether a dragged/resized item pushes colliding siblings during interaction. The final layout is normalized again when the pointer is released.
+
+### Example
+
+```html
+<ngx-grid-layout
+  [dir]="direction()"
+  [options]="{ cols: 12, rowHeight: 48, gap: 8, compact: 'vertical', pushItems: true }"
+  (layoutChange)="saveLayout($event)">
+  @for (item of layout(); track item.id) {
+  <ngx-grid-item [id]="item.id!" [config]="item">
+    <div class="widget">{{ item.id }}</div>
+  </ngx-grid-item>
+  }
+</ngx-grid-layout>
+```
+
+`ngx-grid-item` installs drag and resize behavior on its host. Resize recognizes all eight edges/corners and uses grid snapping supplied by the grid engine.
+
+> **Note on `[config]="item"` above:** `layout()` is a `computed()` that maps the
+> internal item list to a fresh array of fresh objects on every recompute, so
+> each item gets a _new_ config object reference whenever anything in the grid
+> changes — even if the values are identical. `NgxGridItemComponent` and
+> `GridLayoutService` are written to tolerate this (they compare configs by
+> value before writing to any signal), so this pattern is safe to use as-is.
+> If you maintain your own item list instead, prefer keeping a stable object
+> reference per item and only replacing it when its values actually change —
+> it's cheaper and avoids relying on the library's internal guards.
+
+# Grid layout API reference
+
+| Option         | Meaning                                           |
+| -------------- | ------------------------------------------------- |
+| `cols`         | Number of logical columns.                        |
+| `rowHeight`    | Pixel row height or `fit`.                        |
+| `gap`          | Gap between cells in pixels.                      |
+| `flow`         | Free, horizontal-first, or vertical-first intent. |
+| `compact`      | Compaction direction.                             |
+| `allowOverlap` | Allow items to occupy the same cells.             |
+| `pushItems`    | Push siblings away during interaction.            |
+| `rtl`          | `true`, `false`, or `auto`.                       |
+| `animate`      | Reserved for the visual animation layer.          |

package/image-editor/README.md

@@ -1,44 +1,44 @@
-# ngx-kit/image-editor
-
-An image editor built on raw Canvas: crop with draggable corner handles, rotation (quick 90° and free), brightness/contrast/saturation, built-in filters (grayscale, sepia, invert), a **real cartoon filter** (posterize + Sobel edge detection, hand-implemented since there's no native equivalent), and output compression with adjustable quality.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Usage
-
-```html
-<ngx-image-editor [source]="selectedFile" (saved)="onSaved($event)" (cancelled)="onCancelled()" />
-```
-
-```ts
-onSaved(result: NgxImageEditorResult) {
-  // result.blob (for uploading), result.dataUrl (for an instant preview), result.width/height
-}
-```
-
-## API
-
-| Input                                | Type                                            | Default        | Description                                                 |
-| ------------------------------------ | ----------------------------------------------- | -------------- | ----------------------------------------------------------- |
-| `source`                             | `File \| Blob \| string \| null` **(required)** |                | The source file/blob/data URL                               |
-| `aspectRatio`                        | `number`                                        | free           | Lock the crop's aspect ratio (e.g. `1` for a square avatar) |
-| `outputMaxWidth` / `outputMaxHeight` | `number`                                        | unlimited      | Resize the final output's dimensions                        |
-| `outputType`                         | `'image/jpeg' \| 'image/png' \| 'image/webp'`   | `'image/jpeg'` |                                                             |
-| `displayMaxWidth`                    | `number`                                        | `420`          | Max display width for the crop area on screen               |
-
-| Output      | Type                                                        | Description |
-| ----------- | ----------------------------------------------------------- | ----------- |
-| `saved`     | `NgxImageEditorResult` (`{ blob, dataUrl, width, height }`) |             |
-| `cancelled` | `void`                                                      |             |
-
-## Internal architecture (why it's fast)
-
-All live interaction (rotating, moving/resizing the crop box, previewing filters including cartoon) happens on a downscaled copy of the image (max 1200px) — only when you call `save()` is the final render done from the full-resolution original. `brightness`/`contrast`/`saturate`/`grayscale`/`sepia`/`invert` are all implemented with Canvas 2D's native `ctx.filter` (browser-accelerated); only the cartoon filter (which has no native equivalent) is done with separate pixel processing.
-
-## Dark mode and RTL
-
-Supported automatically.
+# ngx-kit/image-editor
+
+An image editor built on raw Canvas: crop with draggable corner handles, rotation (quick 90° and free), brightness/contrast/saturation, built-in filters (grayscale, sepia, invert), a **real cartoon filter** (posterize + Sobel edge detection, hand-implemented since there's no native equivalent), and output compression with adjustable quality.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Usage
+
+```html
+<ngx-image-editor [source]="selectedFile" (saved)="onSaved($event)" (cancelled)="onCancelled()" />
+```
+
+```ts
+onSaved(result: NgxImageEditorResult) {
+  // result.blob (for uploading), result.dataUrl (for an instant preview), result.width/height
+}
+```
+
+## API
+
+| Input                                | Type                                            | Default        | Description                                                 |
+| ------------------------------------ | ----------------------------------------------- | -------------- | ----------------------------------------------------------- |
+| `source`                             | `File \| Blob \| string \| null` **(required)** |                | The source file/blob/data URL                               |
+| `aspectRatio`                        | `number`                                        | free           | Lock the crop's aspect ratio (e.g. `1` for a square avatar) |
+| `outputMaxWidth` / `outputMaxHeight` | `number`                                        | unlimited      | Resize the final output's dimensions                        |
+| `outputType`                         | `'image/jpeg' \| 'image/png' \| 'image/webp'`   | `'image/jpeg'` |                                                             |
+| `displayMaxWidth`                    | `number`                                        | `420`          | Max display width for the crop area on screen               |
+
+| Output      | Type                                                        | Description |
+| ----------- | ----------------------------------------------------------- | ----------- |
+| `saved`     | `NgxImageEditorResult` (`{ blob, dataUrl, width, height }`) |             |
+| `cancelled` | `void`                                                      |             |
+
+## Internal architecture (why it's fast)
+
+All live interaction (rotating, moving/resizing the crop box, previewing filters including cartoon) happens on a downscaled copy of the image (max 1200px) — only when you call `save()` is the final render done from the full-resolution original. `brightness`/`contrast`/`saturate`/`grayscale`/`sepia`/`invert` are all implemented with Canvas 2D's native `ctx.filter` (browser-accelerated); only the cartoon filter (which has no native equivalent) is done with separate pixel processing.
+
+## Dark mode and RTL
+
+Supported automatically.

package/menu/README.md

@@ -1,85 +1,85 @@
-# ngx-kit/menu
-
-Dropdown menu and context (right-click) menu, with smart positioning relative to an anchor (via `ngx-kit/shared`'s `OverlayService`).
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Basic usage (dropdown menu)
-
-```ts
-import { NgxMenuModule } from 'ngx-kit/menu';
-
-@Component({
-  standalone: true,
-  imports: [NgxMenuModule],
-  template: `
-    <button [ngxMenu]="userMenu">Open menu</button>
-
-    <ngx-menu #userMenu="ngxMenu">
-      <ngx-menu-item (click)="editProfile()">Edit profile</ngx-menu-item>
-      <ngx-menu-item (click)="logout()">Sign out</ngx-menu-item>
-      <ngx-menu-divider></ngx-menu-divider>
-      <ngx-menu-item [ngxMenu]="subMenu">More settings ›</ngx-menu-item>
-    </ngx-menu>
-
-    <ngx-menu #subMenu="ngxMenu">
-      <ngx-menu-item>Option A</ngx-menu-item>
-      <ngx-menu-item>Option B</ngx-menu-item>
-    </ngx-menu>
-  `,
-})
-export class MyComponent {}
-```
-
-Important: `<ngx-menu>`'s content isn't rendered until it's triggered via `[ngxMenu]` (or `[ngxContextMenu]`) — so you can't use `<ngx-menu>` directly, without a trigger, as an always-visible list (like a sidebar). For that, use a regular list styled similarly.
-
-Nested menus (submenus) work exactly as shown above, just by putting `[ngxMenu]` on the `<ngx-menu-item>` itself.
-
-## Right-click (context) menu
-
-```html
-<div [ngxContextMenu]="rightClickMenu">Right-click me</div>
-
-<ngx-menu #rightClickMenu="ngxMenu">
-  <ngx-menu-item>Copy</ngx-menu-item>
-  <ngx-menu-item>Paste</ngx-menu-item>
-</ngx-menu>
-```
-
-## API
-
-### `[ngxMenu]` directive
-
-| Input       | Type                          | Description                                                                               |
-| ----------- | ----------------------------- | ----------------------------------------------------------------------------------------- |
-| `ngxMenu`   | `NgxMenu \| TemplateRef`      | Reference to the menu to open                                                             |
-| `placement` | `'top' \| 'bottom' \| 'auto'` | Opening direction; defaults to `'auto'` (picked automatically if there isn't enough room) |
-
-### `<ngx-menu>`
-
-| Input   | Type     | Description                  |
-| ------- | -------- | ---------------------------- |
-| `class` | `string` | Extra CSS class on the panel |
-
-### Styling
-
-Via CSS custom properties:
-
-```css
-ngx-menu {
-  --ngx-menu-bg: light-dark(#fff, #252425);
-  --ngx-menu-fg: light-dark(#000, #fff);
-  --ngx-menu-radius: 10px;
-  --ngx-menu-shadow: 0 4px 20px rgba(0, 0, 0, 0.2);
-  --ngx-menu-item-padding: 8px 14px;
-  --ngx-menu-item-hover-bg: #9bc6ff68;
-}
-```
-
-## Dark mode and RTL
-
-Both are supported automatically (via `ngx-kit/shared`'s `OverlayService`/`DirectionService` and `light-dark()`); no extra work needed.
+# ngx-kit/menu
+
+Dropdown menu and context (right-click) menu, with smart positioning relative to an anchor (via `ngx-kit/core`'s `OverlayService`).
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Basic usage (dropdown menu)
+
+```ts
+import { NgxMenuModule } from 'ngx-kit/menu';
+
+@Component({
+  standalone: true,
+  imports: [NgxMenuModule],
+  template: `
+    <button [ngxMenu]="userMenu">Open menu</button>
+
+    <ngx-menu #userMenu="ngxMenu">
+      <ngx-menu-item (click)="editProfile()">Edit profile</ngx-menu-item>
+      <ngx-menu-item (click)="logout()">Sign out</ngx-menu-item>
+      <ngx-menu-divider></ngx-menu-divider>
+      <ngx-menu-item [ngxMenu]="subMenu">More settings ›</ngx-menu-item>
+    </ngx-menu>
+
+    <ngx-menu #subMenu="ngxMenu">
+      <ngx-menu-item>Option A</ngx-menu-item>
+      <ngx-menu-item>Option B</ngx-menu-item>
+    </ngx-menu>
+  `,
+})
+export class MyComponent {}
+```
+
+Important: `<ngx-menu>`'s content isn't rendered until it's triggered via `[ngxMenu]` (or `[ngxContextMenu]`) — so you can't use `<ngx-menu>` directly, without a trigger, as an always-visible list (like a sidebar). For that, use a regular list styled similarly.
+
+Nested menus (submenus) work exactly as shown above, just by putting `[ngxMenu]` on the `<ngx-menu-item>` itself.
+
+## Right-click (context) menu
+
+```html
+<div [ngxContextMenu]="rightClickMenu">Right-click me</div>
+
+<ngx-menu #rightClickMenu="ngxMenu">
+  <ngx-menu-item>Copy</ngx-menu-item>
+  <ngx-menu-item>Paste</ngx-menu-item>
+</ngx-menu>
+```
+
+## API
+
+### `[ngxMenu]` directive
+
+| Input       | Type                          | Description                                                                               |
+| ----------- | ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `ngxMenu`   | `NgxMenu \| TemplateRef`      | Reference to the menu to open                                                             |
+| `placement` | `'top' \| 'bottom' \| 'auto'` | Opening direction; defaults to `'auto'` (picked automatically if there isn't enough room) |
+
+### `<ngx-menu>`
+
+| Input   | Type     | Description                  |
+| ------- | -------- | ---------------------------- |
+| `class` | `string` | Extra CSS class on the panel |
+
+### Styling
+
+Via CSS custom properties:
+
+```css
+ngx-menu {
+  --ngx-menu-bg: light-dark(#fff, #252425);
+  --ngx-menu-fg: light-dark(#000, #fff);
+  --ngx-menu-radius: 10px;
+  --ngx-menu-shadow: 0 4px 20px rgba(0, 0, 0, 0.2);
+  --ngx-menu-item-padding: 8px 14px;
+  --ngx-menu-item-hover-bg: #9bc6ff68;
+}
+```
+
+## Dark mode and RTL
+
+Both are supported automatically (via `ngx-kit/core`'s `OverlayService`/`DirectionService` and `light-dark()`); no extra work needed.