ngx-kit 7.0.1 → 7.2.0

package/infinite-scroll/README.md

@@ -0,0 +1,252 @@
+# ngx-kit Infinite Scroll
+
+A performance-first infinite-scroll directive for Angular, designed as a small reusable primitive for `ngx-kit`.
+
+It uses the browser's `IntersectionObserver` instead of a continuous `scroll` listener, stays outside Angular's zone until an actual boundary trigger occurs, and supports normal lists, browser-window scrolling, custom roots, reverse chat feeds, and bidirectional feeds.
+
+## Features
+
+- `IntersectionObserver` based; no continuous scroll polling.
+- No RxJS dependency in the directive itself.
+- Standalone Angular directive with signal-based inputs and outputs.
+- Window, host element, external element, or selector-based scroll roots.
+- Runtime root/configuration changes.
+- `down`, `up`, and `both` directions.
+- Prefetch distance in pixels.
+- Immediate check for under-filled lists.
+- Minimum trigger interval.
+- Disabled state that automatically rearms the observer.
+- Reverse/prepend support with automatic scroll-position preservation.
+- `ResizeObserver` + `MutationObserver` assist slow and dynamic layout changes.
+- Explicit `check()` and `completePrepend()` escape hatches.
+- SSR-safe: browser-only APIs are guarded.
+- `scrollStartReached` and `scrollEndReached` convenience outputs.
+- Tiny API surface and zero third-party runtime dependencies.
+
+## Installation
+
+From an existing Angular 22 application:
+
+```bash
+npm install @ngx-kit/infinite-scroll
+```
+
+Then import the standalone directive where it is needed:
+
+```ts
+import { NgxInfiniteScroll } from '@ngx-kit/infinite-scroll';
+
+@Component({
+  standalone: true,
+  imports: [NgxInfiniteScroll],
+  // ...
+})
+export class MyComponent {}
+```
+
+## Basic usage
+
+```html
+<div
+  class="list"
+  infiniteScroll
+  [scrollWindow]="false"
+  [infiniteScrollDistance]="300"
+  [infiniteScrollDisabled]="loading() || endOfList()"
+  (scrolled)="loadMore()">
+  @for (item of items(); track item.id) {
+  <article>{{ item.title }}</article>
+  }
+</div>
+```
+
+The host itself is the scroll container when `scrollWindow` is `false` and no explicit container/root is supplied.
+
+## Window scrolling
+
+Leave `scrollWindow` at its default `true`:
+
+```html
+<div
+  infiniteScroll
+  [infiniteScrollDistance]="600"
+  [infiniteScrollDisabled]="loading() || endOfList()"
+  (scrolled)="loadMore()">
+  ...
+</div>
+```
+
+The observer root is `null`, so the browser viewport is used.
+
+## External/custom root
+
+Pass an element directly:
+
+```html
+<div
+  infiniteScroll
+  [scrollWindow]="false"
+  [infiniteScrollRoot]="listViewport"
+  (scrolled)="loadMore()">
+  ...
+</div>
+```
+
+Or use a selector:
+
+```html
+<div
+  infiniteScroll
+  [fromRoot]="true"
+  [infiniteScrollContainer]="'.questioner-infinit'"
+  [scrollWindow]="false"
+  (scrolled)="loadMore()">
+  ...
+</div>
+```
+
+When a selector cannot be resolved, the directive falls back to the host element instead of silently switching to the browser window.
+
+## Reverse / chat feeds
+
+Use `up` and keep scroll anchoring enabled:
+
+```html
+<div
+  class="chat"
+  infiniteScroll
+  [scrollWindow]="false"
+  [infiniteScrollDirection]="'up'"
+  [infiniteScrollDistance]="180"
+  [infiniteScrollMaintainScrollPosition]="true"
+  [infiniteScrollDisabled]="loadingOlder() || reachedBeginning()"
+  (scrolled)="loadOlder()">
+  ...
+</div>
+```
+
+Before emitting the `up` event, the directive snapshots `scrollTop` and `scrollHeight`. When prepended content increases `scrollHeight`, it adds the exact height delta to the previous `scrollTop` so the user's visible messages stay anchored.
+
+For custom rendering pipelines that know exactly when a batch has rendered:
+
+```ts
+@ViewChild(NgxInfiniteScroll)
+private infiniteScroll?: NgxInfiniteScroll;
+
+loadOlder(): void {
+  // fetch + prepend data
+  // ...
+  this.infiniteScroll?.completePrepend();
+}
+```
+
+In most Angular templates, automatic observation is enough and `completePrepend()` is not required.
+
+## Bidirectional feeds
+
+```html
+<div
+  infiniteScroll
+  [scrollWindow]="false"
+  [infiniteScrollDirection]="'both'"
+  [infiniteScrollDistance]="200"
+  (scrolled)="loadFromEdge($event)">
+  ...
+</div>
+```
+
+The event tells you which edge triggered the load:
+
+```ts
+loadFromEdge(event: NgxInfiniteScrollEvent): void {
+  if (event.direction === 'up') {
+    // prepend older records
+    return;
+  }
+
+  // append newer records
+}
+```
+
+## Public API
+
+| Input                                  | Type                            |  Default | Purpose                                                                |
+| -------------------------------------- | ------------------------------- | -------: | ---------------------------------------------------------------------- |
+| `infiniteScrollDistance`               | `number`                        |    `200` | Prefetch threshold in pixels.                                          |
+| `infiniteScrollDisabled`               | `boolean`                       |  `false` | Stops triggers while true.                                             |
+| `infiniteScrollImmediateCheck`         | `boolean`                       |   `true` | Performs a direct visibility check after setup/re-enable.              |
+| `infiniteScrollMinInterval`            | `number`                        |    `100` | Minimum time between trigger emissions.                                |
+| `infiniteScrollUpDistance`             | `number \| null`                |   `null` | Optional top-edge override; falls back to `infiniteScrollDistance`.    |
+| `infiniteScrollDownDistance`           | `number \| null`                |   `null` | Optional bottom-edge override; falls back to `infiniteScrollDistance`. |
+| `infiniteScrollDirection`              | `'up' \| 'down' \| 'both'`      | `'down'` | Active edge(s).                                                        |
+| `infiniteScrollContainer`              | `string \| HTMLElement \| null` |   `null` | Selector or element root.                                              |
+| `infiniteScrollRoot`                   | `HTMLElement \| null`           |   `null` | Explicit observer root; highest precedence.                            |
+| `scrollWindow`                         | `boolean`                       |   `true` | Use browser viewport as root.                                          |
+| `fromRoot`                             | `boolean`                       |  `false` | Resolve a selector from `document` instead of the host.                |
+| `infiniteScrollMaintainScrollPosition` | `boolean`                       |   `true` | Preserve viewport on `up` triggers.                                    |
+| `infiniteScrollPreserveScrollBehavior` | `ScrollBehavior`                | `'auto'` | Behavior used for scroll compensation.                                 |
+
+### Outputs
+
+| Output               | Payload                  | Purpose                                              |
+| -------------------- | ------------------------ | ---------------------------------------------------- |
+| `scrolled`           | `NgxInfiniteScrollEvent` | Main load trigger.                                   |
+| `scrolledUp`         | `NgxInfiniteScrollEvent` | Compatibility/convenience output for an up trigger.  |
+| `scrolledDown`       | `NgxInfiniteScrollEvent` | Compatibility/convenience output for a down trigger. |
+| `scrollStartReached` | `NgxInfiniteScrollEvent` | Convenience output for the top edge.                 |
+| `scrollEndReached`   | `NgxInfiniteScrollEvent` | Convenience output for the bottom edge.              |
+
+### `NgxInfiniteScrollEvent`
+
+```ts
+export interface NgxInfiniteScrollEvent {
+  direction: 'up' | 'down';
+  distance: number;
+  target: HTMLElement;
+  root: HTMLElement | null;
+}
+```
+
+## Performance model
+
+The directive does **not** install a continuous `scroll` handler. Instead, it creates two tiny sentinels:
+
+```text
+┌──────────────────────────────┐
+│ top sentinel                 │ ← up
+│                              │
+│ application items            │
+│ application items            │
+│ application items            │
+│                              │
+│ bottom sentinel              │ ← down
+└──────────────────────────────┘
+             ↑
+     IntersectionObserver
+```
+
+The observer is created outside Angular's zone. Angular is re-entered only for an actual `scrolled`/edge output. This keeps scrolling/layout work in the browser platform rather than turning every scroll movement into Angular work.
+
+The directive also stays passive about data ownership: application state owns the items, loading state, pagination, retry logic, and end-of-list state. The directive only reports that an edge is close.
+
+## Why not a scroll listener?
+
+A classic implementation continuously evaluates:
+
+```ts
+scrollTop + clientHeight >= scrollHeight - threshold;
+```
+
+That can work, but it means the application needs to receive and process a high-frequency browser event. IntersectionObserver lets the browser manage the geometry observation and calls the application when the sentinel actually crosses the configured boundary.
+
+## SSR
+
+The package does not touch browser-only APIs until the directive is running in a browser. `IntersectionObserver`, `ResizeObserver`, `MutationObserver`, `window`, and `document` are all guarded by the browser platform check or accessed after view initialization.
+
+This makes it safe to include in an Angular application that uses SSR.
+
+## Package design notes
+
+This primitive intentionally does not provide pagination state, API calls, retry policy, loaders, virtual scrolling, or item caching. Those concerns belong to the application/data layer.
+
+For very large datasets, combine this directive with ngx-kit virtual scrolling rather than rendering tens of thousands of nodes into the DOM. Infinite scroll decides **when to fetch**; virtual scrolling decides **how much DOM to keep**.

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/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.

package/message/README.md

@@ -1,70 +1,70 @@
-# ngx-kit/message
-
-Alert/confirm dialogs (SweetAlert-style), with a static API callable from anywhere in the app.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Setup
-
-```ts
-// app.config.ts
-import { provideMessage } from 'ngx-kit/message';
-
-export const appConfig: ApplicationConfig = {
-  providers: [provideMessage({ confirmButtonText: 'OK' /* global defaults */ })],
-};
-```
-
-## Usage
-
-```ts
-import { MSG } from 'ngx-kit/message';
-
-MSG.success('Saved!', 'Your changes were saved successfully.');
-MSG.error('Error', 'Something went wrong.');
-MSG.warning('Warning', 'Are you sure?');
-MSG.info('Heads up', 'This is an informational message.');
-MSG.question('Question', 'Continue?');
-MSG.loading('Processing…');
-
-// full control over options:
-const result = MSG.show({
-  title: 'Delete this?',
-  text: 'This action cannot be undone.',
-  showCancelButton: true,
-  showDenyButton: true,
-  confirmButtonText: 'Yes, delete it',
-});
-result.afterClose.subscribe((r) => console.log(r));
-```
-
-## API
-
-### `MSG` (and its alias `Modal`)
-
-| Method                                                            | Signature                  | Description      |
-| ----------------------------------------------------------------- | -------------------------- | ---------------- |
-| `show(options?)`                                                  | `IMessageOptions`          | Full control     |
-| `info` / `success` / `warning` / `error` / `question` / `loading` | `(title, text?, options?)` | Common shortcuts |
-
-### `IMessageOptions` (key fields)
-
-| Field                                                       | Type          | Default                      | Description                                                                                           |
-| ----------------------------------------------------------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `title` / `text` / `html`                                   | `string`      |                              | Content (`html` is not sanitized — escaping is your responsibility)                                   |
-| `icon`                                                      | `MessageIcon` |                              | Icon shown                                                                                            |
-| `showConfirmButton` / `showDenyButton` / `showCancelButton` | `boolean`     | `true` / `false` / `false`   |                                                                                                       |
-| `confirmButtonText` / `denyButtonText` / `cancelButtonText` | `string`      | `'OK'` / `'No'` / `'Cancel'` |                                                                                                       |
-| `allowOutsideClick` / `allowEscapeKey` / `allowEnterKey`    | `boolean`     | `true`                       | How the message can be dismissed                                                                      |
-| `showCloseButton`                                           | `boolean`     | `false`                      | The ✕ button                                                                                          |
-| `useOverlay`                                                | `boolean`     |                              | For when it's used inside another dialog (e.g. Angular Material), raises the display layer to the top |
-
-If several messages are open at once, Escape/Enter only affect the **last (topmost) message**, not all of them.
-
-## Dark mode and RTL
-
-Supported automatically.
+# ngx-kit/message
+
+Alert/confirm dialogs (SweetAlert-style), with a static API callable from anywhere in the app.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Setup
+
+```ts
+// app.config.ts
+import { provideMessage } from 'ngx-kit/message';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideMessage({ confirmButtonText: 'OK' /* global defaults */ })],
+};
+```
+
+## Usage
+
+```ts
+import { MSG } from 'ngx-kit/message';
+
+MSG.success('Saved!', 'Your changes were saved successfully.');
+MSG.error('Error', 'Something went wrong.');
+MSG.warning('Warning', 'Are you sure?');
+MSG.info('Heads up', 'This is an informational message.');
+MSG.question('Question', 'Continue?');
+MSG.loading('Processing…');
+
+// full control over options:
+const result = MSG.show({
+  title: 'Delete this?',
+  text: 'This action cannot be undone.',
+  showCancelButton: true,
+  showDenyButton: true,
+  confirmButtonText: 'Yes, delete it',
+});
+result.afterClose.subscribe((r) => console.log(r));
+```
+
+## API
+
+### `MSG` (and its alias `Modal`)
+
+| Method                                                            | Signature                  | Description      |
+| ----------------------------------------------------------------- | -------------------------- | ---------------- |
+| `show(options?)`                                                  | `IMessageOptions`          | Full control     |
+| `info` / `success` / `warning` / `error` / `question` / `loading` | `(title, text?, options?)` | Common shortcuts |
+
+### `IMessageOptions` (key fields)
+
+| Field                                                       | Type          | Default                      | Description                                                                                           |
+| ----------------------------------------------------------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `title` / `text` / `html`                                   | `string`      |                              | Content (`html` is not sanitized — escaping is your responsibility)                                   |
+| `icon`                                                      | `MessageIcon` |                              | Icon shown                                                                                            |
+| `showConfirmButton` / `showDenyButton` / `showCancelButton` | `boolean`     | `true` / `false` / `false`   |                                                                                                       |
+| `confirmButtonText` / `denyButtonText` / `cancelButtonText` | `string`      | `'OK'` / `'No'` / `'Cancel'` |                                                                                                       |
+| `allowOutsideClick` / `allowEscapeKey` / `allowEnterKey`    | `boolean`     | `true`                       | How the message can be dismissed                                                                      |
+| `showCloseButton`                                           | `boolean`     | `false`                      | The ✕ button                                                                                          |
+| `useOverlay`                                                | `boolean`     |                              | For when it's used inside another dialog (e.g. Angular Material), raises the display layer to the top |
+
+If several messages are open at once, Escape/Enter only affect the **last (topmost) message**, not all of them.
+
+## Dark mode and RTL
+
+Supported automatically.