@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-pagination.d.ts

@@ -0,0 +1,261 @@
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import * as _angular_core from '@angular/core';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvStructural } from '@malva-ui/cdk/utils';
+import { MlvDensity } from '@malva-ui/cdk/density';
+import { MlvSelectOption } from '@malva-ui/core/dropdown';
+
+interface MlvPaginationObject {
+    totalItems: number;
+    itemsPerPage?: number;
+    itemsPerPageOptions: number[];
+    currentPage?: number;
+}
+
+/**
+ * Helper class that is used to retrieve all the pages, the number of pages, and to validate the pagination object.
+ */
+declare class MlvPaginationService {
+    /** @hidden */
+    readonly moreElementValue = -1;
+    readonly pagination: _angular_core.WritableSignal<MlvPaginationObject>;
+    /**
+     * A number array representing the pages of the pagination object.
+     * Array length always the same and configured by CORNER_DISPLAY_PAGES & SIDE_CURRENT_DISPLAY_PAGES.
+     */
+    readonly pages: _angular_core.Signal<number[]>;
+    /**
+     * Total number of pages.
+     */
+    totalPages: _angular_core.Signal<number>;
+    normalizedItemsPerPageOptions: _angular_core.Signal<number[]>;
+    /**
+     * Provides validation for the pagination object.
+     */
+    validate(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPaginationService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MlvPaginationService>;
+}
+
+/**
+ * Replaces the item-count text of `mlv-pagination` with a projected template.
+ *
+ * Receives `MlvPagination.getCellContext()`: `$implicit` is the current page,
+ * plus `total`, `start`, `end` and `options`.
+ *
+ * @example
+ * ```html
+ * <mlv-pagination [totalItems]="total" [(currentPage)]="page">
+ *   <ng-template mlvPaginationCount let-page let-total="total">
+ *     Page {{ page }} · {{ total }} records
+ *   </ng-template>
+ * </mlv-pagination>
+ * ```
+ */
+declare class MlvPaginationCount extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPaginationCount, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvPaginationCount, "[mlvPaginationCount]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Replaces the whole items-per-page selector of `mlv-pagination` — the trigger
+ * button *and* its dropdown — with a projected template. Rendered only while
+ * there is more than one per-page option to offer.
+ *
+ * Receives the same context as {@link MlvPaginationCount}. The template owns the
+ * entire interaction, so it must call `setItemsPerPage()` itself.
+ *
+ * @example
+ * ```html
+ * <mlv-pagination #p [totalItems]="total" [(currentPage)]="page">
+ *   <ng-template mlvPaginationPerPageItem let-options="options">
+ *     @for (option of options; track option) {
+ *       <button type="button" (click)="p.setItemsPerPage(option)">{{ option }}</button>
+ *     }
+ *   </ng-template>
+ * </mlv-pagination>
+ * ```
+ */
+declare class MlvPaginationPerPageItem extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPaginationPerPageItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvPaginationPerPageItem, "[mlvPaginationPerPageItem]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Pagination control: an item-count line with an items-per-page selector, and a
+ * page-navigation strip with prev/next arrows and numbered page buttons.
+ *
+ * Both `currentPage` and `itemsPerPage` are two-way bindable models — the
+ * component owns no data, only the position within it. `totalItems` is the one
+ * required input.
+ *
+ * The page strip collapses on **page count**, not on width: once there are more
+ * pages than fit the fixed window, `MlvPaginationService` replaces the middle
+ * runs with an ellipsis marker that renders as a small numeric field. Type a
+ * page number there and press Enter to jump. The whole strip is hidden while
+ * there is only one page, and the per-page selector is hidden while
+ * `totalItems` is at or below the smallest `perPageOptions` entry.
+ *
+ * @example Basic
+ * ```html
+ * <mlv-pagination [totalItems]="total" [(currentPage)]="page" />
+ * ```
+ *
+ * @example Custom per-page choices, including "all items"
+ * ```html
+ * <mlv-pagination
+ *   [totalItems]="total"
+ *   [(currentPage)]="page"
+ *   [(itemsPerPage)]="perPage"
+ *   [perPageOptions]="[10, 25, 50, Infinity]"
+ * />
+ * ```
+ *
+ * @example Replacing the item-count text
+ * ```html
+ * <mlv-pagination [totalItems]="total" [(currentPage)]="page">
+ *   <ng-template mlvPaginationCount let-page let-start="start" let-end="end">
+ *     Showing {{ start }}–{{ end }} on page {{ page }}
+ *   </ng-template>
+ * </mlv-pagination>
+ * ```
+ */
+declare class MlvPagination {
+    /** @protected Projected custom item-count template, if any. */
+    protected readonly _itemsCountRef: _angular_core.Signal<MlvPaginationCount | undefined>;
+    /** @protected Projected custom items-per-page template, if any. */
+    protected readonly _itemsPerPageRef: _angular_core.Signal<MlvPaginationPerPageItem | undefined>;
+    /**
+     * Unique id for this pagination instance, defaulted to a generated one.
+     *
+     * **Currently inert** — nothing reads it. The per-page trigger and its
+     * listbox pair through their own generated `_perPageListboxId`, and the id is
+     * not reflected onto the host. Binding it compiles but changes nothing.
+     */
+    readonly id: _angular_core.InputSignal<string>;
+    /**
+     * Adds `mlv-pagination--mobile` to the host.
+     *
+     * The library ships **no rules** for that class — the component's own layout
+     * is identical either way. Treat it as a styling hook for the consumer, not
+     * as a built-in responsive mode.
+     */
+    readonly mobile: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Total number of items across all pages. Required.
+     *
+     * Drives the page count (`totalItems / itemsPerPage`), the "X–Y of Z" range
+     * text, and which `perPageOptions` are offered: the list is cut after the
+     * first option that covers `totalItems`, and the selector disappears entirely
+     * when `totalItems` is at or below the smallest option.
+     *
+     * Not coerced: bind a `number`, not a route-param string.
+     */
+    readonly totalItems: _angular_core.InputSignal<number>;
+    /**
+     * Items shown per page. Two-way bindable; also set by the per-page selector.
+     * `Infinity` means "all items on one page".
+     */
+    readonly itemsPerPage: _angular_core.ModelSignal<number>;
+    /**
+     * Choices offered by the items-per-page selector.
+     *
+     * The list is cut after the first option that covers `totalItems` — so one
+     * "show everything" choice always survives and the rest are dropped. Include
+     * `Infinity` to offer "All (Z)" for datasets larger than every option.
+     */
+    readonly perPageOptions: _angular_core.InputSignal<number[]>;
+    /**
+     * **Currently inert** — nothing reads it. The item count is always rendered;
+     * project an `[mlvPaginationCount]` template to change or suppress the text.
+     */
+    readonly displayTotalItems: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Currently active page, 1-based. Two-way bindable. */
+    readonly currentPage: _angular_core.ModelSignal<number>;
+    /**
+     * Density applied to the items-per-page dropdown list.
+     *
+     * The dropdown panel is portaled to the CDK overlay container, outside the
+     * component's DOM tree, so ancestor density classes cannot cascade into it.
+     * Forwarded to the underlying `mlv-popup`, which stamps the resolved
+     * `mlv--{density}` class on the detached panel. When omitted, the global
+     * `MlvDensityService` density applies.
+     */
+    readonly mlvDensity: _angular_core.InputSignal<MlvDensity | undefined>;
+    /** @protected Component-scoped pagination state service. */
+    protected readonly _service: MlvPaginationService;
+    /** @protected The component's i18n strings signal. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvPaginationI18n>;
+    /** @private Resolver for ICU parameterized i18n strings. */
+    private readonly _resolver;
+    /** @protected Index of the first item shown on the current page (1-based). */
+    protected readonly _currentItemsStart: _angular_core.Signal<number>;
+    /** @protected Index of the last item shown on the current page (clamped to total). */
+    protected readonly _currentItemsEnd: _angular_core.Signal<number>;
+    /** @protected `Infinity` constant exposed for the "All items" per-page option comparison in the template. */
+    protected readonly infinity: number;
+    /** @protected Resolved total item count display (e.g. "50 items"). */
+    protected readonly _resolvedItemCount: _angular_core.Signal<string>;
+    /** @protected Resolved "X–Y of Z" range display. */
+    protected readonly _resolvedRange: _angular_core.Signal<string>;
+    /** @protected Resolved "All (Z)" label for the Infinity per-page option in the trigger button. */
+    protected readonly _resolvedAllItems: _angular_core.Signal<string>;
+    /** @protected Resolves per-page option label (e.g. "10 items per page" or "All (50)"). */
+    protected _resolvedPerPageLabel(option: number): string;
+    /**
+     * @protected Per-page choices in the shape `mlv-dropdown-panel` consumes.
+     *
+     * Labels come from {@link _resolvedPerPageLabel}, so the `Infinity` entry keeps
+     * its "All (Z)" wording rather than rendering as a number.
+     */
+    protected readonly _perPageOptions: _angular_core.Signal<MlvSelectOption<number>[]>;
+    /** @protected Currently selected per-page value, as the panel's array shape. */
+    protected readonly _selectedPerPage: _angular_core.Signal<number[]>;
+    /** @protected Id linking the trigger's `aria-controls` to the panel's listbox. */
+    protected readonly _perPageListboxId: string;
+    /** @private Aggregated pagination inputs pushed into the pagination service. */
+    private readonly _paginationObject;
+    constructor();
+    /**
+     * Template context handed to a projected `[mlvPaginationCount]` or
+     * `[mlvPaginationPerPageItem]` slot.
+     *
+     * `$implicit` is the current page; `start`/`end` are the 1-based indices of
+     * the first and last item on it (`end` clamped to `totalItems`); `options` is
+     * the per-page list after trimming against `totalItems`.
+     */
+    getCellContext(): {
+        $implicit: number;
+        total: number;
+        start: number;
+        end: number;
+        options: number[];
+    };
+    /**
+     * Sets `currentPage`. Performs no clamping — callers inside the component
+     * only reach it from enabled controls, so the page is already in range.
+     */
+    goToPage(page: number): void;
+    /** Sets `itemsPerPage`. `Infinity` puts every item on one page. */
+    setItemsPerPage(itemsPerPage: number): void;
+    /**
+     * @protected Applies a per-page choice from the dropdown panel.
+     *
+     * The panel's selection model is array-shaped even for single select, so the
+     * one value is unwrapped here. An empty emission means the panel deselected
+     * rather than selected, which is not a per-page choice.
+     */
+    protected _onPerPageChange(values: readonly number[]): void;
+    /**
+     * Jumps to the page typed into an ellipsis page-jump field (Enter keydown).
+     * Out-of-range values are ignored — the field keeps its text and the page
+     * does not change.
+     */
+    setPageFromInput(event: Event): void;
+    /** @protected Resolves the accessible label for a numbered page button. */
+    protected _pageAriaLabel(page: number): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPagination, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvPagination, "mlv-pagination", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; "mobile": { "alias": "mobile"; "required": false; "isSignal": true; }; "totalItems": { "alias": "totalItems"; "required": true; "isSignal": true; }; "itemsPerPage": { "alias": "itemsPerPage"; "required": false; "isSignal": true; }; "perPageOptions": { "alias": "perPageOptions"; "required": false; "isSignal": true; }; "displayTotalItems": { "alias": "displayTotalItems"; "required": false; "isSignal": true; }; "currentPage": { "alias": "currentPage"; "required": false; "isSignal": true; }; "mlvDensity": { "alias": "mlvDensity"; "required": false; "isSignal": true; }; }, { "itemsPerPage": "itemsPerPageChange"; "currentPage": "currentPageChange"; }, ["_itemsCountRef", "_itemsPerPageRef"], never, true, never>;
+}
+
+export { MlvPagination, MlvPaginationCount, MlvPaginationPerPageItem, MlvPaginationService };
+export type { MlvPaginationObject };

package/types/malva-ui-core-pin-input.d.ts

@@ -0,0 +1,203 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import { MlvSignalFormControlBase, MlvFormControl } from '@malva-ui/core/form-utils';
+
+/**
+ * Structural directive used to provide a custom template for the separator
+ * rendered between `mlv-pin-input` cells. When no instance is projected, the
+ * component falls back to a default Lucide dot icon.
+ *
+ * @example
+ * ```html
+ * <mlv-pin-input [length]="6" separator="each">
+ *   <ng-template mlvPinInputSeparator>
+ *     <span class="dash">—</span>
+ *   </ng-template>
+ * </mlv-pin-input>
+ * ```
+ */
+declare class MlvPinInputSeparator {
+    /**
+     * The template reference for the projected separator content.
+     */
+    readonly templateRef: TemplateRef<any>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPinInputSeparator, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvPinInputSeparator, "[mlvPinInputSeparator]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * OTP / PIN input component — a row of single-character `mlv-input` cells that
+ * behave as one logical form control.
+ *
+ * - Auto-advances focus to the next cell after a character is entered.
+ * - Backspace moves focus backwards and clears the cell.
+ * - Arrow keys navigate between cells.
+ * - Pasting a string distributes characters across cells starting from the first cell.
+ * - Integrates with Angular Reactive Forms and Template-Driven Forms via CVA.
+ * - Supports `mlv-label`, `mlv-hint`, and `mlv-message` via the same `label`,
+ *   `hint`, `message`, and `state` inputs as every other Malva UI form control.
+ *
+ * @example Reactive form with label and error message
+ * ```html
+ * <mlv-pin-input
+ *   [length]="6"
+ *   [formControl]="otpControl"
+ *   label="One-time code"
+ *   hint="Sent to +1 ••• 1234"
+ *   [state]="otpControl.invalid && otpControl.touched ? 'error' : 'default'"
+ *   [message]="otpControl.invalid && otpControl.touched ? 'Code is invalid' : ''"
+ * />
+ * ```
+ *
+ * @example Password mode
+ * ```html
+ * <mlv-pin-input type="password" [length]="6" [formControl]="pinControl" />
+ * ```
+ */
+declare class MlvPinInput extends MlvSignalFormControlBase<string> implements MlvFormControl {
+    /** @protected The component's i18n strings signal. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvPinInputI18n>;
+    /** @private Resolver for ICU parameterized i18n strings. */
+    private readonly _resolver;
+    /**
+     * Number of cells (characters) in the PIN / OTP.
+     * @default 6
+     */
+    readonly length: _angular_core.InputSignal<number>;
+    /**
+     * Input type applied to each cell.
+     * Use `'password'` to mask characters; `'number'` for digit-only PIN.
+     * @default 'text'
+     */
+    readonly type: _angular_core.InputSignal<"number" | "text" | "password">;
+    /**
+     * Placeholder character shown in each empty cell.
+     * @default '·'
+     */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /**
+     * Controls separator placement between cells.
+     *
+     * - `''` (default) — no separators
+     * - `'each'` — separator between every pair of consecutive cells
+     * - comma-separated indices (e.g. `'1,3'`) — separator before the cell at
+     *   each listed index. With `length=4` and `'1,3'` the result is
+     *   `[0]—[1][2]—[3]`.
+     *
+     * By default separators render as a Lucide dot icon. Project a custom
+     * template via `*mlvPinInputSeparator` to override.
+     *
+     * @default ''
+     */
+    readonly separator: _angular_core.InputSignal<string>;
+    /**
+     * Emits the complete value string when all cells are filled.
+     */
+    readonly completed: _angular_core.OutputEmitterRef<string>;
+    /** The complete PIN/OTP value used by all Angular forms APIs. */
+    readonly value: _angular_core.ModelSignal<string>;
+    /**
+     * @protected Char values per cell index. Sparse — empty cell = `''`.
+     */
+    protected readonly _values: _angular_core.WritableSignal<string[]>;
+    /** @private Latest model value written by this component, used to avoid collapsing sparse cells. */
+    private _internalModelWrite;
+    /** @protected Stable cell indexes derived from {@link length}. */
+    protected readonly _cellIndices: _angular_core.Signal<number[]>;
+    /**
+     * @private Live refs to each rendered `<mlv-input>` cell, order-aligned
+     * with `_cellControls`. Used for programmatic focus / text selection.
+     */
+    private readonly _cells;
+    /** @private Normalizes horizontal cell navigation for RTL layouts. */
+    private readonly _rtlService;
+    /**
+     * @protected Optional projected template used as separator content between
+     * cells. When absent the component renders a default Lucide dot icon.
+     */
+    protected readonly _separatorDef: _angular_core.Signal<MlvPinInputSeparator | undefined>;
+    /**
+     * @protected Custom separator template, derived from `_separatorDef`.
+     */
+    protected readonly _separatorTemplate: _angular_core.Signal<TemplateRef<unknown> | null>;
+    /**
+     * @protected Resolved set of cell indices that should be preceded by a
+     * separator. Derived from the `separator` input and `length`.
+     *
+     * - `''` → empty set
+     * - `'each'` → `{1, 2, …, length - 1}`
+     * - `'1,3'` → `{1, 3}` (values outside `[1, length - 1]` are ignored)
+     */
+    protected readonly _separatorPositions: _angular_core.Signal<Set<number>>;
+    /**
+     * @protected Whether a separator should be rendered before the cell at
+     * `index`.
+     */
+    protected _hasSeparatorBefore(index: number): boolean;
+    /**
+     * @protected Stable per-cell id. The first cell's id is referenced by the
+     * optional `<mlv-label>`'s `for` attribute so clicking the label focuses
+     * the first cell.
+     */
+    protected _cellId(index: number): string;
+    /**
+     * @protected Resolves a single cell's aria-label, e.g. "Digit 2 of 6".
+     * @param index 0-based cell index.
+     */
+    protected _cellLabel(index: number): string;
+    constructor();
+    /** Whether the control holds a clearable value — At least one cell filled. */
+    readonly hasValue: _angular_core.Signal<boolean>;
+    /**
+     * @protected Reacts to cell FormControl value changes. Normalises multi-char
+     * input to the last character and auto-advances focus, or distributes a
+     * multi-char string across subsequent cells when triggered by IME / fast typing.
+     */
+    protected _onCellChange(index: number, raw: string): void;
+    /**
+     * @protected Handles cell keyboard input — Backspace, Delete, arrows, Home/End.
+     */
+    protected _onCellKeydown(index: number, event: KeyboardEvent): void;
+    /**
+     * @protected Pastes a string of characters across cells starting from the
+     * first cell. Whitespace is stripped before distribution.
+     */
+    protected _onCellPaste(_index: number, event: ClipboardEvent): void;
+    /**
+     * @protected Selects the contents of a cell when it receives focus so the
+     * next keystroke replaces the current character.
+     */
+    protected _onCellFocus(index: number): void;
+    /**
+     * @protected Emits the signal-forms touch output when a cell loses focus.
+     */
+    protected _onCellBlur(): void;
+    /**
+     * @private Sets a single cell's value, preserving the length of `_values`.
+     */
+    private _setCell;
+    /**
+     * @private Distributes a sequence of characters across cells starting from
+     * `startIndex`, advances focus to the next empty cell, and emits.
+     */
+    private _distributeChars;
+    /**
+     * @private Focuses the cell at the given index, clamped to `[0, length - 1]`.
+     */
+    private _focusCell;
+    /**
+     * @private Returns the `MlvInput` instance rendered for the cell at
+     * the given index, or `null` if the cell is not yet rendered.
+     */
+    private _cellAt;
+    /**
+     * @private Pushes the current joined value to the forms model and
+     * emits `completed` when every cell is filled.
+     */
+    private _emit;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPinInput, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvPinInput, "mlv-pin-input", never, { "length": { "alias": "length"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "separator": { "alias": "separator"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "completed": "completed"; "value": "valueChange"; }, ["_separatorDef"], never, true, never>;
+}
+
+export { MlvPinInput, MlvPinInputSeparator };