ngx-kit 7.1.0 → 7.3.0

package/angle-selector/README.md

@@ -1,34 +1,34 @@
-# ngx-kit/angle-selector
-
-An angle picker (0 to 360 degrees) with a draggable circular handle — for setting a gradient's direction, a shadow's rotation, or any other angular value.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Usage
-
-```html
-<ngx-input-angle [(ngModel)]="angle"></ngx-input-angle>
-```
-
-Or on a plain input:
-
-```html
-<input type="number" [ngxInputAngle]="angle" (change)="angle = $event" />
-```
-
-## API
-
-| Input                  | Type                          | Default  | Description                |
-| ---------------------- | ----------------------------- | -------- | -------------------------- |
-| `theme`                | `'light' \| 'dark' \| 'auto'` | `'auto'` | Component theme            |
-| `change` _(directive)_ | `EventEmitter<number>`        |          | The new angle (in degrees) |
-
-The value is always a number between `0` and `360`.
-
-## Dark mode and RTL
-
-Supported automatically. The handle is implemented with RxJS (`switchMap` + `takeUntil` + `takeUntilDestroyed`), so drag listeners are only ever active during an actual drag.
+# ngx-kit/angle-selector
+
+An angle picker (0 to 360 degrees) with a draggable circular handle — for setting a gradient's direction, a shadow's rotation, or any other angular value.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Usage
+
+```html
+<ngx-input-angle [(ngModel)]="angle"></ngx-input-angle>
+```
+
+Or on a plain input:
+
+```html
+<input type="number" [ngxInputAngle]="angle" (change)="angle = $event" />
+```
+
+## API
+
+| Input                  | Type                          | Default  | Description                |
+| ---------------------- | ----------------------------- | -------- | -------------------------- |
+| `theme`                | `'light' \| 'dark' \| 'auto'` | `'auto'` | Component theme            |
+| `change` _(directive)_ | `EventEmitter<number>`        |          | The new angle (in degrees) |
+
+The value is always a number between `0` and `360`.
+
+## Dark mode and RTL
+
+Supported automatically. The handle is implemented with RxJS (`switchMap` + `takeUntil` + `takeUntilDestroyed`), so drag listeners are only ever active during an actual drag.

package/box-shadow/README.md

@@ -1,33 +1,33 @@
-# ngx-kit/box-shadow
-
-A visual `box-shadow` builder: drag the shadow's offset on a 2D pad with mouse/touch, plus controls for blur, spread, and color.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Usage
-
-```html
-<ngx-box-shadow [(ngModel)]="shadowCss"></ngx-box-shadow>
-```
-
-Or on a plain input:
-
-```html
-<input type="text" [ngxInputBoxShadow]="shadowCss" (change)="shadowCss = $event" />
-```
-
-The output is a valid CSS string like `0px 4px 12px 0px rgba(0,0,0,0.25)`.
-
-## API
-
-| Input                              | Type      | Default | Description                                      |
-| ---------------------------------- | --------- | ------- | ------------------------------------------------ |
-| `setInputBackground` _(directive)_ | `boolean` | `true`  | Shows the shadow color as the input's background |
-
-## Dark mode and RTL
-
-Supported automatically. The shadow-offset pad is implemented with Pointer Capture (no global `document` listener needed), so it works smoothly on mobile too.
+# ngx-kit/box-shadow
+
+A visual `box-shadow` builder: drag the shadow's offset on a 2D pad with mouse/touch, plus controls for blur, spread, and color.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Usage
+
+```html
+<ngx-box-shadow [(ngModel)]="shadowCss"></ngx-box-shadow>
+```
+
+Or on a plain input:
+
+```html
+<input type="text" [ngxInputBoxShadow]="shadowCss" (change)="shadowCss = $event" />
+```
+
+The output is a valid CSS string like `0px 4px 12px 0px rgba(0,0,0,0.25)`.
+
+## API
+
+| Input                              | Type      | Default | Description                                      |
+| ---------------------------------- | --------- | ------- | ------------------------------------------------ |
+| `setInputBackground` _(directive)_ | `boolean` | `true`  | Shows the shadow color as the input's background |
+
+## Dark mode and RTL
+
+Supported automatically. The shadow-offset pad is implemented with Pointer Capture (no global `document` listener needed), so it works smoothly on mobile too.

package/color-picker/README.md

@@ -1,52 +1,52 @@
-# ngx-kit/color-picker
-
-A complete color picker: a visual picker (saturation/hue), RGB/HSL/CMYK/HEX inputs, an alpha channel, and support for the browser's EyeDropper API to pick a color from anywhere on the screen.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Usage as a component
-
-```html
-<ngx-input-color
-  [(ngModel)]="color"
-  [outputType]="'HEX'"
-  [defaultInspector]="ColorInspector.Picker"></ngx-input-color>
-```
-
-`NgxInputColorComponent` is a full `ControlValueAccessor`, so it works with `ngModel`, `formControl`, and `formControlName`.
-
-## Usage as a directive (on a plain input)
-
-```html
-<input type="text" [ngxInputColor]="color" (change)="color = $event" [outputType]="'RGB'" />
-```
-
-## API
-
-### `<ngx-input-color>` / `[ngxInputColor]`
-
-| Input                                        | Type                                              | Default  | Description                                           |
-| -------------------------------------------- | ------------------------------------------------- | -------- | ----------------------------------------------------- |
-| `theme`                                      | `'light' \| 'dark' \| 'auto'`                     | `'auto'` | `'auto'` follows the browser's `prefers-color-scheme` |
-| `simpleMode`                                 | `boolean`                                         | `false`  | A more compact UI                                     |
-| `outputType`                                 | `'HEX' \| 'RGB' \| 'HSL' \| 'HSV' \| 'CMYK'`      | `'HEX'`  | Output string format                                  |
-| `defaultInspector`                           | `ColorInspector` (`Picker \| RGB \| HSL \| CMYK`) | `Picker` | Which tab is open by default                          |
-| `useAlphaChannel`                            | `boolean`                                         | `true`   | Show/hide the alpha (transparency) channel            |
-| `setInputBackgroundColor` _(directive only)_ | `boolean`                                         | `true`   | Sets the input's own background to the selected color |
-| `change` _(output, directive only)_          | `EventEmitter<string>`                            |          | The new value whenever the color changes              |
-
-### Input/output formats
-
-The value can be any of: `#rrggbb`, `#rrggbbaa` (including 3- and 4-character shorthand with alpha), `rgb()`/`rgba()`, `hsl()`/`hsla()`.
-
-## EyeDropper
-
-If the user's browser supports the [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) (recent Chrome/Edge), the eyedropper button is enabled automatically and the user can pick a color from anywhere on the page (even outside the browser). On browsers without support, the button stays hidden.
-
-## Dark mode and RTL
-
-Supported automatically.
+# ngx-kit/color-picker
+
+A complete color picker: a visual picker (saturation/hue), RGB/HSL/CMYK/HEX inputs, an alpha channel, and support for the browser's EyeDropper API to pick a color from anywhere on the screen.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Usage as a component
+
+```html
+<ngx-input-color
+  [(ngModel)]="color"
+  [outputType]="'HEX'"
+  [defaultInspector]="ColorInspector.Picker"></ngx-input-color>
+```
+
+`NgxInputColorComponent` is a full `ControlValueAccessor`, so it works with `ngModel`, `formControl`, and `formControlName`.
+
+## Usage as a directive (on a plain input)
+
+```html
+<input type="text" [ngxInputColor]="color" (change)="color = $event" [outputType]="'RGB'" />
+```
+
+## API
+
+### `<ngx-input-color>` / `[ngxInputColor]`
+
+| Input                                        | Type                                              | Default  | Description                                           |
+| -------------------------------------------- | ------------------------------------------------- | -------- | ----------------------------------------------------- |
+| `theme`                                      | `'light' \| 'dark' \| 'auto'`                     | `'auto'` | `'auto'` follows the browser's `prefers-color-scheme` |
+| `simpleMode`                                 | `boolean`                                         | `false`  | A more compact UI                                     |
+| `outputType`                                 | `'HEX' \| 'RGB' \| 'HSL' \| 'HSV' \| 'CMYK'`      | `'HEX'`  | Output string format                                  |
+| `defaultInspector`                           | `ColorInspector` (`Picker \| RGB \| HSL \| CMYK`) | `Picker` | Which tab is open by default                          |
+| `useAlphaChannel`                            | `boolean`                                         | `true`   | Show/hide the alpha (transparency) channel            |
+| `setInputBackgroundColor` _(directive only)_ | `boolean`                                         | `true`   | Sets the input's own background to the selected color |
+| `change` _(output, directive only)_          | `EventEmitter<string>`                            |          | The new value whenever the color changes              |
+
+### Input/output formats
+
+The value can be any of: `#rrggbb`, `#rrggbbaa` (including 3- and 4-character shorthand with alpha), `rgb()`/`rgba()`, `hsl()`/`hsla()`.
+
+## EyeDropper
+
+If the user's browser supports the [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) (recent Chrome/Edge), the eyedropper button is enabled automatically and the user can pick a color from anywhere on the page (even outside the browser). On browsers without support, the button stays hidden.
+
+## Dark mode and RTL
+
+Supported automatically.

package/{shared → core}/README.md

@@ -1,117 +1,117 @@
-# ngx-kit/shared
-
-Shared utilities and services that the rest of the `ngx-kit` packages are built on: overlay/dialog management, page-direction (RTL/LTR) detection, browser-preference detection, and a few reusable base components (slider, range slider, color-saturation panel).
-
-You usually won't need this package directly — the other packages depend on it automatically. But if you're building a custom component that should stay consistent with the rest of the library (dark mode, RTL, drag performance), use these same utilities.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-Import the base styles (which enable dark mode via `color-scheme`) once, app-wide:
-
-```scss
-// styles.scss
-@import 'ngx-kit/styles/all.css';
-```
-
-## Services
-
-### `OverlayService`
-
-The engine behind everything floating in the library (menus, dialogs, the color/gradient/angle picker popups). Renders an Angular component inside a native `<dialog>` (`showModal()`) and positions it relative to an anchor.
-
-```ts
-import { OverlayService } from 'ngx-kit/shared';
-
-const overlay = inject(OverlayService);
-const viewContainerRef = inject(ViewContainerRef);
-
-const ref = overlay.open({
-  component: MyComponent,
-  viewContainerRef,
-  anchor: buttonElementRef.nativeElement,
-  placement: 'bottom', // 'top' | 'bottom' | 'auto'
-  alignment: 'start', // 'start' | 'center' | 'end'
-  margin: 8,
-});
-
-ref.close(); // OverlayRef.close() takes no argument and has no afterClosed; for that (return value, afterClosed) use ngx-kit/dialog, which is built on top of this service
-```
-
-What's handled for you automatically:
-
-- **Smart positioning**: if there isn't enough room below the anchor, it flips above (`placement: 'auto'`).
-- **Click-outside dismissal**: detected via the backdrop click, not a global `document` listener.
-- **Correct stacking**: multiple simultaneous overlays (e.g. a menu with a submenu) work correctly; Escape only closes the last (topmost) overlay.
-- **Focus restoration**: after closing, focus returns to whatever had focus before the overlay opened (accessibility).
-- **Automatic RTL**: alignment and placement are computed against the page's actual direction (not a fixed assumption).
-
-### `DirectionService`
-
-A signal (`isRtl(): boolean`) that watches the `<html>` element's `dir` attribute with a `MutationObserver` and updates reactively the moment it changes — so if your app switches languages at runtime, everything stays in sync automatically.
-
-```ts
-const direction = inject(DirectionService);
-direction.isRtl(); // signal<boolean>
-```
-
-### `BrowserService`
-
-```ts
-const browser = inject(BrowserService);
-browser.prefersDarkMode; // boolean — read once at service construction time
-```
-
-## Utilities
-
-### `startDragSession(callbacks)`
-
-Replaces the problematic `@HostListener('document:mousemove', ...)` pattern, which keeps a listener attached to `document` for the entire lifetime of the component — even when nothing is being dragged (a real performance issue on pages with many simultaneous instances). This function only adds a listener for the duration of an actual drag and removes it itself; `touchmove` is handled with `{passive: false}`, so dragging on mobile doesn't also scroll the page.
-
-```ts
-import { startDragSession } from 'ngx-kit/shared';
-
-let stop: (() => void) | undefined;
-
-function onPointerDown(ev: MouseEvent | TouchEvent) {
-  stop?.();
-  stop = startDragSession({
-    onMove: (ev) => {
-      /* update position */
-    },
-    onEnd: () => {
-      stop = undefined;
-    },
-  });
-}
-```
-
-> If your component is `OnPush` and uses `startDragSession` (instead of `@HostListener`), make sure to call `ChangeDetectorRef.markForCheck()` inside `onMove`/`onEnd` yourself — unlike `@HostListener`, which automatically marks the view dirty, a manual `addEventListener` does not.
-
-### `getOffsetPosition(event, element)`
-
-Returns the pointer/touch position relative to an element's top-left corner; used to implement drag-based components (sliders, color pickers, etc.).
-
-### `mergeConfig(base, override)`
-
-Deep-merges two config objects (for the `provideXxx({...})` pattern used throughout the library).
-
-## Base components
-
-These can be used directly, but they're mostly designed as building blocks for other components (like `color-picker`, `box-shadow`):
-
-| Component              | Selector                | Description                                                           |
-| ---------------------- | ----------------------- | --------------------------------------------------------------------- |
-| `SliderComponent`      | `slider`                | Single-value slider, `ControlValueAccessor`, `[min]`/`[max]`/`[step]` |
-| `RangeSliderComponent` | `range-slider`          | Range slider (two thumbs)                                             |
-| `SaturationComponent`  | internal (color-picker) | 2D saturation/lightness picker panel                                  |
-
-## Dark mode and RTL
-
-Both rely directly on `ngx-kit/shared`:
-
-- **Dark mode**: uses the native CSS `light-dark()` function. For it to work, `color-scheme: light dark` (or `only light`/`only dark` to force it manually) must be set on `:root` — this happens automatically when you import `ngx-kit/styles/all.css`. To force a theme manually (independent of the OS's `prefers-color-scheme`), set `data-ngx-theme="dark"` or `"light"` on `<html>`/`<body>`.
-- **RTL**: enabled via `dir="rtl"` on `<html>`; the whole library uses CSS logical properties (`inset-inline-start`, etc.), so no separate styling is needed.
+# ngx-kit/core
+
+Shared utilities and services that the rest of the `ngx-kit` packages are built on: overlay/dialog management, page-direction (RTL/LTR) detection, browser-preference detection, and a few reusable base components (slider, range slider, color-saturation panel).
+
+You usually won't need this package directly — the other packages depend on it automatically. But if you're building a custom component that should stay consistent with the rest of the library (dark mode, RTL, drag performance), use these same utilities.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+Import the base styles (which enable dark mode via `color-scheme`) once, app-wide:
+
+```scss
+// styles.scss
+@import 'ngx-kit/styles/all.css';
+```
+
+## Services
+
+### `OverlayService`
+
+The engine behind everything floating in the library (menus, dialogs, the color/gradient/angle picker popups). Renders an Angular component inside a native `<dialog>` (`showModal()`) and positions it relative to an anchor.
+
+```ts
+import { OverlayService } from 'ngx-kit/core';
+
+const overlay = inject(OverlayService);
+const viewContainerRef = inject(ViewContainerRef);
+
+const ref = overlay.open({
+  component: MyComponent,
+  viewContainerRef,
+  anchor: buttonElementRef.nativeElement,
+  placement: 'bottom', // 'top' | 'bottom' | 'auto'
+  alignment: 'start', // 'start' | 'center' | 'end'
+  margin: 8,
+});
+
+ref.close(); // OverlayRef.close() takes no argument and has no afterClosed; for that (return value, afterClosed) use ngx-kit/dialog, which is built on top of this service
+```
+
+What's handled for you automatically:
+
+- **Smart positioning**: if there isn't enough room below the anchor, it flips above (`placement: 'auto'`).
+- **Click-outside dismissal**: detected via the backdrop click, not a global `document` listener.
+- **Correct stacking**: multiple simultaneous overlays (e.g. a menu with a submenu) work correctly; Escape only closes the last (topmost) overlay.
+- **Focus restoration**: after closing, focus returns to whatever had focus before the overlay opened (accessibility).
+- **Automatic RTL**: alignment and placement are computed against the page's actual direction (not a fixed assumption).
+
+### `DirectionService`
+
+A signal (`isRtl(): boolean`) that watches the `<html>` element's `dir` attribute with a `MutationObserver` and updates reactively the moment it changes — so if your app switches languages at runtime, everything stays in sync automatically.
+
+```ts
+const direction = inject(DirectionService);
+direction.isRtl(); // signal<boolean>
+```
+
+### `BrowserService`
+
+```ts
+const browser = inject(BrowserService);
+browser.prefersDarkMode; // boolean — read once at service construction time
+```
+
+## Utilities
+
+### `startDragSession(callbacks)`
+
+Replaces the problematic `@HostListener('document:mousemove', ...)` pattern, which keeps a listener attached to `document` for the entire lifetime of the component — even when nothing is being dragged (a real performance issue on pages with many simultaneous instances). This function only adds a listener for the duration of an actual drag and removes it itself; `touchmove` is handled with `{passive: false}`, so dragging on mobile doesn't also scroll the page.
+
+```ts
+import { startDragSession } from 'ngx-kit/core';
+
+let stop: (() => void) | undefined;
+
+function onPointerDown(ev: MouseEvent | TouchEvent) {
+  stop?.();
+  stop = startDragSession({
+    onMove: (ev) => {
+      /* update position */
+    },
+    onEnd: () => {
+      stop = undefined;
+    },
+  });
+}
+```
+
+> If your component is `OnPush` and uses `startDragSession` (instead of `@HostListener`), make sure to call `ChangeDetectorRef.markForCheck()` inside `onMove`/`onEnd` yourself — unlike `@HostListener`, which automatically marks the view dirty, a manual `addEventListener` does not.
+
+### `getOffsetPosition(event, element)`
+
+Returns the pointer/touch position relative to an element's top-left corner; used to implement drag-based components (sliders, color pickers, etc.).
+
+### `mergeConfig(base, override)`
+
+Deep-merges two config objects (for the `provideXxx({...})` pattern used throughout the library).
+
+## Base components
+
+These can be used directly, but they're mostly designed as building blocks for other components (like `color-picker`, `box-shadow`):
+
+| Component              | Selector                | Description                                                           |
+| ---------------------- | ----------------------- | --------------------------------------------------------------------- |
+| `SliderComponent`      | `slider`                | Single-value slider, `ControlValueAccessor`, `[min]`/`[max]`/`[step]` |
+| `RangeSliderComponent` | `range-slider`          | Range slider (two thumbs)                                             |
+| `SaturationComponent`  | internal (color-picker) | 2D saturation/lightness picker panel                                  |
+
+## Dark mode and RTL
+
+Both rely directly on `ngx-kit/core`:
+
+- **Dark mode**: uses the native CSS `light-dark()` function. For it to work, `color-scheme: light dark` (or `only light`/`only dark` to force it manually) must be set on `:root` — this happens automatically when you import `ngx-kit/styles/all.css`. To force a theme manually (independent of the OS's `prefers-color-scheme`), set `data-ngx-theme="dark"` or `"light"` on `<html>`/`<body>`.
+- **RTL**: enabled via `dir="rtl"` on `<html>`; the whole library uses CSS logical properties (`inset-inline-start`, etc.), so no separate styling is needed.