ngx-kit 6.3.0 → 7.0.0

package/README.md

@@ -1,3 +1,3 @@
-# NgxInput
-
-## Comming Soon...
+# NgxInput
+
+## Comming Soon...

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,49 +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/data-table/README.md

@@ -1,113 +1,120 @@
-# ngx-kit/data-table
-
-A signal-based data table with full type-safety: column and custom renderer definitions are typed so TypeScript itself catches invalid columns or a wrong `rendererInputs`. Single/multi-column sorting, pagination, lazy (server-side) mode, and column resizing via Pointer Capture.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Registering renderers (optional, but recommended)
-
-```ts
-// app.config.ts
-import { provideTable, defineRenderers } from 'ngx-kit/data-table';
-import { AvatarCellRenderer, BooleanCellRenderer } from './cell-renderers';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideTable({
-      renderers: defineRenderers({ avatar: AvatarCellRenderer, boolean: BooleanCellRenderer }),
-      column: { minWidth: 80, maxWidth: 480, defaultWidth: 160 },
-    }),
-  ],
-};
-```
-
-## Type-safe column definitions
-
-```ts
-interface Tenant {
-  avatarUrl: string;
-  name: string;
-  isActive: boolean;
-}
-
-const renderers = defineRenderers({ avatar: AvatarCellRenderer, boolean: BooleanCellRenderer });
-
-const fields = defineFields<Tenant, typeof renderers>(renderers, [
-  { column: 'avatarUrl', title: 'User', renderer: 'avatar', rendererInputs: { showName: true } }, // ✅ type-checked
-  { column: 'name', title: 'Name', sortable: true },
-  { column: 'isActive', title: 'Active', renderer: 'boolean', align: 'center' },
-]);
-```
-
-If `column` isn't a real field of `Tenant`, or `renderer` isn't a real key of the registry, or `rendererInputs` doesn't match that renderer's actual inputs — it's a compile error, not a runtime one.
-
-## Usage in a template
-
-```html
-<ngx-table
-  [fields]="fields"
-  [data]="tenants"
-  [totalRecords]="tenants.length"
-  [pageSize]="20"
-  (sortChange)="onSortChange($event)"
-></ngx-table>
-```
-
-### Lazy mode (server-side pagination/sorting)
-
-```html
-<ngx-table [fields]="fields" [data]="page" [totalRecords]="total" [lazy]="true" (lazyLoad)="fetchPage($event)"></ngx-table>
-```
-
-```ts
-fetchPage(ev: LazyLoadEvent<Tenant>) {
-  // ev.pageIndex, ev.pageSize, ev.first, ev.sorts
-  this.api.getTenants(ev).subscribe((res) => { this.page = res.data; this.total = res.total; });
-}
-```
-
-## API
-
-### `<ngx-table>` inputs
-
-| Input | Type | Description |
-| --- | --- | --- |
-| `fields` | `TableField<T, R>[]` **(required)** | Column definitions (from `defineFields`) |
-| `data` | `readonly T[]` **(required)** | Current page's data |
-| `totalRecords` | `number` **(required)** | Total row count (for pagination) |
-| `pageSize` | `number` | Defaults from `provideTable` |
-| `lazy` | `boolean` | If `true`, your app manages sorting/pagination (not the table) |
-| `loading` | `boolean` | Shows a loading state |
-| `showRecordNumber` | `boolean` | Shows a row-number column |
-
-### Outputs
-
-| Output | Type | Description |
-| --- | --- | --- |
-| `sortChange` | `SortMeta<T>[]` | Sort change (non-lazy mode) |
-| `lazyLoad` | `LazyLoadEvent<T>` | New page/sort (lazy mode) — includes `pageIndex`, `pageSize`, `first`, `sorts` |
-| `columnResize` | `{ field: string; width: number }` | A column's width changed |
-
-### Defining a custom renderer
-
-```ts
-@Component({
-  standalone: true,
-  selector: 'app-avatar-cell',
-  template: `<img [src]="value()" /><span *ngIf="showName()">{{ row().name }}</span>`,
-})
-export class AvatarCellRenderer implements CellRendererComponent<string, Tenant> {
-  value = input.required<string>();
-  row = input.required<Tenant>();
-  field = input.required<TableFieldBase<Tenant>>();
-  showName = input(false); // automatically usable in rendererInputs for this column
-}
-```
-
-## Dark mode and RTL
-
-Supported automatically.
+# ngx-kit/data-table
+
+A signal-based data table with full type-safety: column and custom renderer definitions are typed so TypeScript itself catches invalid columns or a wrong `rendererInputs`. Single/multi-column sorting, pagination, lazy (server-side) mode, and column resizing via Pointer Capture.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Registering renderers (optional, but recommended)
+
+```ts
+// app.config.ts
+import { provideTable, defineRenderers } from 'ngx-kit/data-table';
+import { AvatarCellRenderer, BooleanCellRenderer } from './cell-renderers';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideTable({
+      renderers: defineRenderers({ avatar: AvatarCellRenderer, boolean: BooleanCellRenderer }),
+      column: { minWidth: 80, maxWidth: 480, defaultWidth: 160 },
+    }),
+  ],
+};
+```
+
+## Type-safe column definitions
+
+```ts
+interface Tenant {
+  avatarUrl: string;
+  name: string;
+  isActive: boolean;
+}
+
+const renderers = defineRenderers({ avatar: AvatarCellRenderer, boolean: BooleanCellRenderer });
+
+const fields = defineFields<Tenant, typeof renderers>(renderers, [
+  { column: 'avatarUrl', title: 'User', renderer: 'avatar', rendererInputs: { showName: true } }, // ✅ type-checked
+  { column: 'name', title: 'Name', sortable: true },
+  { column: 'isActive', title: 'Active', renderer: 'boolean', align: 'center' },
+]);
+```
+
+If `column` isn't a real field of `Tenant`, or `renderer` isn't a real key of the registry, or `rendererInputs` doesn't match that renderer's actual inputs — it's a compile error, not a runtime one.
+
+## Usage in a template
+
+```html
+<ngx-table
+  [fields]="fields"
+  [data]="tenants"
+  [totalRecords]="tenants.length"
+  [pageSize]="20"
+  (sortChange)="onSortChange($event)"></ngx-table>
+```
+
+### Lazy mode (server-side pagination/sorting)
+
+```html
+<ngx-table
+  [fields]="fields"
+  [data]="page"
+  [totalRecords]="total"
+  [lazy]="true"
+  (lazyLoad)="fetchPage($event)"></ngx-table>
+```
+
+```ts
+fetchPage(ev: LazyLoadEvent<Tenant>) {
+  // ev.pageIndex, ev.pageSize, ev.first, ev.sorts
+  this.api.getTenants(ev).subscribe((res) => { this.page = res.data; this.total = res.total; });
+}
+```
+
+## API
+
+### `<ngx-table>` inputs
+
+| Input              | Type                                | Description                                                    |
+| ------------------ | ----------------------------------- | -------------------------------------------------------------- |
+| `fields`           | `TableField<T, R>[]` **(required)** | Column definitions (from `defineFields`)                       |
+| `data`             | `readonly T[]` **(required)**       | Current page's data                                            |
+| `totalRecords`     | `number` **(required)**             | Total row count (for pagination)                               |
+| `pageSize`         | `number`                            | Defaults from `provideTable`                                   |
+| `lazy`             | `boolean`                           | If `true`, your app manages sorting/pagination (not the table) |
+| `loading`          | `boolean`                           | Shows a loading state                                          |
+| `showRecordNumber` | `boolean`                           | Shows a row-number column                                      |
+
+### Outputs
+
+| Output         | Type                               | Description                                                                    |
+| -------------- | ---------------------------------- | ------------------------------------------------------------------------------ |
+| `sortChange`   | `SortMeta<T>[]`                    | Sort change (non-lazy mode)                                                    |
+| `lazyLoad`     | `LazyLoadEvent<T>`                 | New page/sort (lazy mode) — includes `pageIndex`, `pageSize`, `first`, `sorts` |
+| `columnResize` | `{ field: string; width: number }` | A column's width changed                                                       |
+
+### Defining a custom renderer
+
+```ts
+@Component({
+  standalone: true,
+  selector: 'app-avatar-cell',
+  template: `
+    <img [src]="value()" />
+    <span *ngIf="showName()">{{ row().name }}</span>
+  `,
+})
+export class AvatarCellRenderer implements CellRendererComponent<string, Tenant> {
+  value = input.required<string>();
+  row = input.required<Tenant>();
+  field = input.required<TableFieldBase<Tenant>>();
+  showName = input(false); // automatically usable in rendererInputs for this column
+}
+```
+
+## Dark mode and RTL
+
+Supported automatically.

package/date-picker/README.md

@@ -1,69 +1,74 @@
-# ngx-kit/date-picker
-
-A date picker supporting four calendar systems: Gregorian, Jalali (Persian), Hijri (Islamic), and Chinese — built on an adapter-based architecture that also makes it possible to add other calendars. It also ships a standalone calendar component (`ngx-calendar`) usable without any inputs.
-
-## Install
-
-```bash
-npm install ngx-kit
-```
-
-## Setup
-
-Calendar adapters need to be provided (the default provides all four; if you only need some of them, the bundle stays smaller since each is lazily imported):
-
-```ts
-// app.config.ts
-import { provideDateAdapters } from 'ngx-kit/date-picker';
-
-export const appConfig: ApplicationConfig = {
-  providers: [provideDateAdapters()],
-};
-```
-
-## Usage
-
-```html
-<input type="text" [ngxInputDatePicker]="date" (change)="date = $event" [locale]="'fa'" [displayFormat]="'yyyy/MM/dd'" />
-```
-
-```html
-<ngx-calendar [locale]="'fa'" [theme]="'auto'"></ngx-calendar>
-```
-
-## API
-
-### `[ngxInputDatePicker]`
-
-| Input | Type | Default | Description |
-| --- | --- | --- | --- |
-| `locale` | `string` (`'en'`, `'fa'`, `'hi'`, `'zh'`, or any custom registered locale) | `'en'` | Which calendar to use |
-| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | |
-| `displayFormat` | `string` | `'yyyy/MM/dd'` | Text display format for the date |
-| `min` / `max` | `Date` | | Allowed range |
-| `config` | `NgxDatePickerConfig` | | Show/hide and text for the "today"/"clear" buttons, custom icon templates |
-| `change` *(output)* | `EventEmitter<Date>` | | The selected date (always a standard JavaScript `Date`, regardless of the displayed calendar) |
-
-### `getLocals()`
-
-Returns the list of currently registered locales (e.g. to populate a language `<select>`):
-
-```ts
-availableLocals = getLocals(); // ['en', 'fa', 'hi', 'zh']
-```
-
-### Adding a custom calendar
-
-```ts
-provideDateAdapters({ locale: 'ja', useClass: MyJapaneseAdapter });
-```
-
-`MyJapaneseAdapter` must implement the `IDateAdapter` interface.
-
-## Performance note
-
-The Hijri and Chinese calendars (which are table/astronomical-based, unlike the formulaic Gregorian/Jalali ones) cache their computation results internally — since rendering a calendar month calls the date computation separately for every day cell, without caching this could take several hundred milliseconds for years far from today.
-
-## Dark mode and RTL
-
-Supported automatically (the Jalali/Hijri calendars are naturally RTL too).
+# ngx-kit/date-picker
+
+A date picker supporting four calendar systems: Gregorian, Jalali (Persian), Hijri (Islamic), and Chinese — built on an adapter-based architecture that also makes it possible to add other calendars. It also ships a standalone calendar component (`ngx-calendar`) usable without any inputs.
+
+## Install
+
+```bash
+npm install ngx-kit
+```
+
+## Setup
+
+Calendar adapters need to be provided (the default provides all four; if you only need some of them, the bundle stays smaller since each is lazily imported):
+
+```ts
+// app.config.ts
+import { provideDateAdapters } from 'ngx-kit/date-picker';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideDateAdapters()],
+};
+```
+
+## Usage
+
+```html
+<input
+  type="text"
+  [ngxInputDatePicker]="date"
+  (change)="date = $event"
+  [locale]="'fa'"
+  [displayFormat]="'yyyy/MM/dd'" />
+```
+
+```html
+<ngx-calendar [locale]="'fa'" [theme]="'auto'"></ngx-calendar>
+```
+
+## API
+
+### `[ngxInputDatePicker]`
+
+| Input               | Type                                                                       | Default        | Description                                                                                   |
+| ------------------- | -------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
+| `locale`            | `string` (`'en'`, `'fa'`, `'hi'`, `'zh'`, or any custom registered locale) | `'en'`         | Which calendar to use                                                                         |
+| `theme`             | `'light' \| 'dark' \| 'auto'`                                              | `'auto'`       |                                                                                               |
+| `displayFormat`     | `string`                                                                   | `'yyyy/MM/dd'` | Text display format for the date                                                              |
+| `min` / `max`       | `Date`                                                                     |                | Allowed range                                                                                 |
+| `config`            | `NgxDatePickerConfig`                                                      |                | Show/hide and text for the "today"/"clear" buttons, custom icon templates                     |
+| `change` _(output)_ | `EventEmitter<Date>`                                                       |                | The selected date (always a standard JavaScript `Date`, regardless of the displayed calendar) |
+
+### `getLocals()`
+
+Returns the list of currently registered locales (e.g. to populate a language `<select>`):
+
+```ts
+availableLocals = getLocals(); // ['en', 'fa', 'hi', 'zh']
+```
+
+### Adding a custom calendar
+
+```ts
+provideDateAdapters({ locale: 'ja', useClass: MyJapaneseAdapter });
+```
+
+`MyJapaneseAdapter` must implement the `IDateAdapter` interface.
+
+## Performance note
+
+The Hijri and Chinese calendars (which are table/astronomical-based, unlike the formulaic Gregorian/Jalali ones) cache their computation results internally — since rendering a calendar month calls the date computation separately for every day cell, without caching this could take several hundred milliseconds for years far from today.
+
+## Dark mode and RTL
+
+Supported automatically (the Jalali/Hijri calendars are naturally RTL too).