@ngneers/controls 0.0.1-next.0

package/types/ngneers-controls-mask-input.d.ts

@@ -0,0 +1,434 @@
+import * as _angular_core from '@angular/core';
+import * as _ngneers_signal_translate from '@ngneers/signal-translate';
+import * as _ngneers_controls_api_ng from '@ngneers/controls/api/ng';
+import * as _ngneers_controls_themes from '@ngneers/controls-themes';
+import { ValueControlBase } from '@ngneers/controls/base';
+import { NgnRovingGroup } from '@ngneers/controls/roving-focus';
+
+type NumberSegment = {
+    kind: 'number';
+    segment: string;
+    min: number;
+    max: number;
+    /** Omit for a variable-length (non-padded) segment; provide for a fixed, zero-padded width. */
+    length?: number;
+    placeholder?: string;
+};
+type EnumSegment = {
+    kind: 'enum';
+    segment: string;
+    values: string[];
+    placeholder?: string;
+};
+type MaskSegment = NumberSegment | EnumSegment;
+/** A mask config is an ordered list of segments and literal separator strings. */
+type MaskInputCfg = (MaskSegment | string)[];
+type Separator = {
+    kind: 'sep';
+    text: string;
+};
+type NumberField = {
+    kind: 'number';
+    name: string;
+    min: number;
+    max: number;
+    /** Maximum digit count. */
+    maxLen: number;
+    /** When true, render to maxLen with leading zeros once the field is no longer the active one. */
+    pad: boolean;
+    placeholder: string;
+};
+type EnumField = {
+    kind: 'enum';
+    name: string;
+    values: string[];
+    /** Maximum value length. */
+    maxLen: number;
+    placeholder: string;
+};
+type Field = NumberField | EnumField;
+type Part = Separator | Field;
+
+type RenderToken = {
+    kind: 'sep';
+    text: string;
+} | {
+    kind: 'section';
+    ord: number;
+    text: string;
+    placeholder: boolean;
+};
+
+/**
+ * @category control
+ */
+declare class NgnMaskInput extends ValueControlBase<'maskInput', string | null> {
+    readonly isFieldControl = true;
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"mask-input", ["root", "section", "section-active", "section-placeholder", "separator", "proxy", "sr-only"], readonly []>>;
+    protected readonly i18n: _ngneers_signal_translate.TranslationsSignal<{
+        calendar: {
+            today: string;
+            input: string;
+            selectYear: string;
+            selectMonth: string;
+            previousMonth: string;
+            nextMonth: string;
+            weekdays: {
+                monday: string;
+                tuesday: string;
+                wednesday: string;
+                thursday: string;
+                friday: string;
+                saturday: string;
+                sunday: string;
+            };
+            weekdaysShort: {
+                monday: string;
+                tuesday: string;
+                wednesday: string;
+                thursday: string;
+                friday: string;
+                saturday: string;
+                sunday: string;
+            };
+            months: {
+                january: string;
+                february: string;
+                march: string;
+                april: string;
+                may: string;
+                june: string;
+                july: string;
+                august: string;
+                september: string;
+                october: string;
+                november: string;
+                december: string;
+            };
+        };
+        editInplace: {
+            placeholder: string;
+            confirm: string;
+        };
+        filter: {
+            noFilter: string;
+            addCondition: string;
+            removeCondition: string;
+            operator: string;
+            value: string;
+            clear: string;
+            apply: string;
+            cancel: string;
+            matchModeLabel: string;
+            match: {
+                all: string;
+                any: string;
+                and: string;
+                or: string;
+            };
+            selected: string;
+            conditions: string;
+            operators: {
+                isEqual: string;
+                isNotEqual: string;
+                contains: string;
+                startsWith: string;
+                endsWith: string;
+                in: string;
+                isEmpty: string;
+                isNotEmpty: string;
+                greaterThan: string;
+                greaterThanOrEqual: string;
+                lessThan: string;
+                lessThanOrEqual: string;
+                after: string;
+                onOrAfter: string;
+                before: string;
+                onOrBefore: string;
+                isTrue: string;
+                isFalse: string;
+                custom: string;
+            };
+        };
+        splitter: {
+            handleLabel: string;
+        };
+        inputField: {
+            clearInput: string;
+        };
+        maskInput: {
+            roleDescription: string;
+            segmentRange: string;
+            optionSeparator: string;
+        };
+        drawer: {
+            close: string;
+        };
+        dialog: {
+            close: string;
+        };
+        chip: {
+            close: string;
+        };
+        breadcrumb: {
+            overflow: string;
+        };
+        toast: {
+            close: string;
+            region: string;
+        };
+        snackbar: {
+            close: string;
+            region: string;
+            severity: {
+                error: string;
+                warning: string;
+                success: string;
+                info: string;
+            };
+        };
+        upload: {
+            upload: string;
+            uploadNamed: string;
+            retryNamed: string;
+            cancelNamed: string;
+            removeNamed: string;
+            progressNamed: string;
+        };
+        select: {
+            filterOptions: string;
+        };
+        paginator: {
+            previousPage: string;
+            nextPage: string;
+        };
+        listBox: {
+            noItemsFound: string;
+        };
+        tree: {
+            noItemsFound: string;
+        };
+        table: {
+            selectAllRows: string;
+            selectRow: string;
+            sortedBy: string;
+            sortAscending: string;
+            sortDescending: string;
+            sortCleared: string;
+            selectedCount: string;
+            page: string;
+            resultCount: string;
+        };
+        state: {
+            loading: string;
+            success: string;
+            warning: string;
+            error: string;
+            cancelled: string;
+        };
+    }, "_">;
+    /**
+     * The mask to apply to the input. Can be a predefined mask key or a custom mask configuration.
+     */
+    readonly mask: _angular_core.InputSignal<string | MaskInputCfg | null>;
+    private readonly _parts;
+    private readonly _fields;
+    /**
+     * Structural signature of the resolved mask — field kinds/names/widths and
+     * separators, but deliberately NOT numeric min/max. The section values are
+     * reset only when this changes, so a consumer narrowing a field's range (e.g.
+     * a calendar shrinking the day field's max to the current month's length) does
+     * not wipe what the user has already typed.
+     */
+    private readonly _structureSig;
+    /** Source of truth: one raw string per field ordinal. */
+    protected readonly values: _angular_core.WritableSignal<string[]>;
+    /** Whether the proxy input currently holds focus. The active-section
+     * highlight and "actively edited" treatment only apply while focused. */
+    protected readonly focused: _angular_core.WritableSignal<boolean>;
+    /** RenderTokens for template `@for` loop. While unfocused there is no active
+     * section, so padded fields render in their resting (padded) form. */
+    protected readonly tokens: _angular_core.Signal<RenderToken[]>;
+    /** The roving group on the proxy input element. */
+    protected readonly rovingGroup: _angular_core.Signal<NgnRovingGroup>;
+    /** The proxy input element reference. */
+    private readonly _proxyRef;
+    /** Active field ordinal (identity: item index === field ordinal). */
+    protected readonly activeOrd: _angular_core.Signal<number>;
+    protected readonly proxyInputMode: _angular_core.Signal<"text" | "numeric">;
+    protected readonly liveAnnouncement: _angular_core.WritableSignal<string>;
+    protected sectionValueNow(ord: number): number | null;
+    protected sectionMin(ord: number): number | null;
+    protected sectionMax(ord: number): number | null;
+    /** Accessible name for a section's `role="spinbutton"` — the field's name. */
+    protected sectionName(ord: number): string;
+    protected sectionValueText(ord: number): string;
+    /**
+     * Whether every section holds a finished value — i.e. the mask is fully
+     * filled and a serialized output value has been emitted.
+     */
+    readonly complete: _angular_core.Signal<boolean>;
+    /** Whether no section holds any value (the whole field is blank). Lets a host
+     * (e.g. calendar) distinguish a fully-cleared field from mid-typing, both of
+     * which emit a `null` value. */
+    readonly empty: _angular_core.Signal<boolean>;
+    /**
+     * Returns the resolved CSS class string for `section-active` from the theme,
+     * used to highlight the currently active section span in the template.
+     */
+    protected readonly activeSectionClass: _angular_core.Signal<string>;
+    protected readonly segmentDescriptions: _angular_core.Signal<{
+        id: string;
+        text: string;
+    }[]>;
+    /** Returns the description span id for a given field ordinal, or null if none. */
+    protected sectionDescId(ord: number): string | null;
+    constructor();
+    /**
+     * Places focus on the proxy input and selects the section nearest the
+     * pointer's horizontal position. Invoked both by the control's own
+     * `pointerdown` and by a surrounding `ngn-input-field` when its padding is
+     * clicked (so a click "above" a section selects that section). Returns `true`
+     * to signal the field it handled focus.
+     */
+    focusFromPointer(event: MouseEvent): boolean;
+    /** Clears every section (invoked by a surrounding field's clear button). */
+    clearValue(): boolean;
+    /** Field ordinal of the section nearest `clientX`, or -1 when there are none. */
+    private _sectionIndexAt;
+    private _onBeforeInput;
+    private _onKeyDown;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnMaskInput, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgnMaskInput, "ngn-mask-input", never, { "mask": { "alias": "mask"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+declare const MASKS: {
+    readonly phoneNumber: ["(", {
+        readonly kind: "number";
+        readonly segment: "areaCode";
+        readonly min: 0;
+        readonly max: 999;
+        readonly length: 3;
+        readonly placeholder: "000";
+    }, ")", " ", {
+        readonly kind: "number";
+        readonly segment: "exchange";
+        readonly min: 0;
+        readonly max: 999;
+        readonly length: 3;
+        readonly placeholder: "000";
+    }, "-", {
+        readonly kind: "number";
+        readonly segment: "subscriber";
+        readonly min: 0;
+        readonly max: 9999;
+        readonly length: 4;
+        readonly placeholder: "0000";
+    }];
+    readonly creditCard: [{
+        readonly kind: "number";
+        readonly segment: "cardPart1";
+        readonly min: 0;
+        readonly max: 9999;
+        readonly length: 4;
+        readonly placeholder: "0000";
+    }, " ", {
+        readonly kind: "number";
+        readonly segment: "cardPart2";
+        readonly min: 0;
+        readonly max: 9999;
+        readonly length: 4;
+        readonly placeholder: "0000";
+    }, " ", {
+        readonly kind: "number";
+        readonly segment: "cardPart3";
+        readonly min: 0;
+        readonly max: 9999;
+        readonly length: 4;
+        readonly placeholder: "0000";
+    }, " ", {
+        readonly kind: "number";
+        readonly segment: "cardPart4";
+        readonly min: 0;
+        readonly max: 9999;
+        readonly length: 4;
+        readonly placeholder: "0000";
+    }];
+    readonly ssn: [{
+        readonly kind: "number";
+        readonly segment: "areaNumber";
+        readonly min: 0;
+        readonly max: 999;
+        readonly length: 3;
+        readonly placeholder: "000";
+    }, "-", {
+        readonly kind: "number";
+        readonly segment: "groupNumber";
+        readonly min: 0;
+        readonly max: 99;
+        readonly length: 2;
+        readonly placeholder: "00";
+    }, "-", {
+        readonly kind: "number";
+        readonly segment: "serialNumber";
+        readonly min: 0;
+        readonly max: 9999;
+        readonly length: 4;
+        readonly placeholder: "0000";
+    }];
+    readonly zipCode: [{
+        readonly kind: "number";
+        readonly segment: "zipBase";
+        readonly min: 0;
+        readonly max: 99999;
+        readonly length: 5;
+        readonly placeholder: "00000";
+    }, "-", {
+        readonly kind: "number";
+        readonly segment: "zipPlus4";
+        readonly min: 0;
+        readonly max: 9999;
+        readonly length: 4;
+        readonly placeholder: "0000";
+    }];
+    readonly currency: ["$", {
+        readonly kind: "number";
+        readonly segment: "dollars";
+        readonly min: 0;
+        readonly max: 999999999;
+        readonly length: 9;
+        readonly placeholder: "000000000";
+    }, ".", {
+        readonly kind: "number";
+        readonly segment: "cents";
+        readonly min: 0;
+        readonly max: 99;
+        readonly length: 2;
+        readonly placeholder: "00";
+    }];
+    readonly percentage: [{
+        readonly kind: "number";
+        readonly segment: "percent";
+        readonly min: 0;
+        readonly max: 100;
+        readonly length: 3;
+        readonly placeholder: "000";
+    }, "%"];
+};
+
+/**
+ * Returns the input mask configuration for a given date or time mask.
+ * @param mask The mask string representing the date or time format.
+ * For example, 'MM/dd/yyyy' for date, 'HH:mm:ss' for time, 'hh:mm:ss a' for 12-hour time with period.
+ * @returns The input mask configuration that can be used with the input mask component.
+ */
+declare function getDateOrTimeMask(mask: string): MaskInputCfg;
+declare const DATE_TIME_MASKS: {
+    date: MaskInputCfg;
+    time: MaskInputCfg;
+    timeShort: MaskInputCfg;
+    time12: MaskInputCfg;
+};
+
+export { DATE_TIME_MASKS, MASKS, NgnMaskInput, getDateOrTimeMask };
+export type { EnumField, EnumSegment, Field, MaskInputCfg, MaskSegment, NumberField, NumberSegment, Part, Separator };

package/types/ngneers-controls-menu.d.ts

@@ -0,0 +1,192 @@
+import * as _angular_core from '@angular/core';
+import { OnDestroy, TemplateRef, ViewContainerRef, ComponentRef } from '@angular/core';
+import { NgnActionItem } from '@ngneers/controls/api';
+import * as _ngneers_controls_custom_types from '@ngneers/controls-custom-types';
+import * as _iconify_types from '@iconify/types';
+import * as _ngneers_controls_api_ng from '@ngneers/controls/api/ng';
+import { Openable, Anchor } from '@ngneers/controls/api/ng';
+import * as _ngneers_controls_themes from '@ngneers/controls-themes';
+import { maybeCallback } from '@ngneers/controls/utils';
+import { NgnBase } from '@ngneers/controls/base';
+import { Placement } from '@floating-ui/dom';
+
+type MenuItem = MenuItemDefault | MenuItemSeparator;
+type MenuItemDefault = NgnActionItem;
+type MenuItemSeparator = {
+    separator: true;
+};
+
+declare class NgnContextMenu implements OnDestroy {
+    private readonly _elementRef;
+    private readonly _vcr;
+    private _menu?;
+    /**
+     * The menu items to display in the context menu opened on right-click.
+     */
+    readonly ngnContextMenu: _angular_core.InputSignal<MenuItem[]>;
+    constructor();
+    ngOnDestroy(): void;
+    private handleClick;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnContextMenu, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgnContextMenu, "[ngnContextMenu]", never, { "ngnContextMenu": { "alias": "ngnContextMenu"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+declare abstract class MenuTemplates extends NgnBase<'menu'> {
+    private readonly _defaultItemTemplate;
+    private readonly _userItemTemplate;
+    /**
+     * Set a custom template for an item of the menu.
+     * Can also be set using an `<ng-template>` element with `#item` template reference variable.
+     */
+    readonly templateItem: _angular_core.InputSignal<TemplateRef<{
+        $implicit: MenuItemDefault;
+    }> | null>;
+    protected readonly itemTemplate: _angular_core.Signal<TemplateRef<{
+        $implicit: MenuItemDefault;
+    }>>;
+    private readonly _defaultGroupTemplate;
+    private readonly _userGroupTemplate;
+    /**
+     * Set a custom template for a group of items in the menu.
+     * Can also be set using an `<ng-template>` element with `#group` template reference variable.
+     */
+    readonly templateGroup: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    protected readonly groupTemplate: _angular_core.Signal<TemplateRef<unknown>>;
+    /**
+     * Types for the dialog templates.
+     */
+    readonly templateTypes: {
+        item: {
+            $implicit: MenuItemDefault;
+        };
+    } & {
+        $implicit: {
+            item: Partial<{
+                $implicit: MenuItemDefault;
+            }>;
+        };
+    };
+    protected readonly internalTemplateTypes: {
+        regularItem: {
+            $implicit: MenuItemDefault;
+            index: number;
+        };
+    } & {
+        $implicit: {
+            regularItem: Partial<{
+                $implicit: MenuItemDefault;
+                index: number;
+            }>;
+        };
+    };
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MenuTemplates, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuTemplates, never, never, { "templateItem": { "alias": "templateItem"; "required": false; "isSignal": true; }; "templateGroup": { "alias": "templateGroup"; "required": false; "isSignal": true; }; }, {}, ["_userItemTemplate", "_userGroupTemplate"], never, true, never>;
+}
+
+/**
+ * @category control
+ */
+declare class NgnMenu extends MenuTemplates implements Openable {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"menu", ["root", "submenu", "item", "item-opened", "icon-children", "separator"], readonly [{
+        readonly class: "popover";
+        readonly template: _ngneers_controls_themes.ControlTemplate<"popover", ["root", "content", "content-closing"], readonly []>;
+    }]>>;
+    protected readonly elementId: _angular_core.InputSignal<string>;
+    /**
+     * The element to which the menu is anchored. Required if {@link popover} is `true`.
+     */
+    readonly anchor: _angular_core.InputSignal<Anchor | undefined>;
+    /**
+     * The menu items to display.
+     */
+    readonly items: _angular_core.InputSignal<MenuItem[]>;
+    /**
+     * Whether to automatically set ARIA attributes on the anchor element.
+     * @default true if anchor is an HTMLButtonElement, false otherwise.
+     */
+    readonly autoAnchorAria: _angular_core.InputSignal<boolean | undefined>;
+    /**
+     * Whether the menu is a popover. Requires {@link anchor} to be set.
+     * @default false
+     */
+    readonly popover: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * The placement of the menu relative to the anchor element. Only used when {@link popover} is `true`.
+     * @default bottom-start
+     */
+    readonly placement: _angular_core.InputSignal<Placement>;
+    /**
+     * Icon type for children indicator (submenu indicator). If not set, a default icon will be used.
+     */
+    readonly iconSubmenuIndicator: _angular_core.InputSignal<_iconify_types.IconifyIcon | _ngneers_controls_custom_types.NgnIconEntry | undefined>;
+    /**
+     * Whether this menu is a submenu. Used internally.
+     * @internal
+     */
+    readonly isSubMenu: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether to open submenus on hover. Defaults to true in popover mode.
+     * @default popover()
+     */
+    readonly openSubmenuOnHover: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Emitted when the menu is fully closed.
+     */
+    readonly closed: _angular_core.OutputEmitterRef<void>;
+    /**
+     * Emitted when the menu is about to close.
+     */
+    readonly closing: _angular_core.OutputEmitterRef<void>;
+    /**
+     * Emitted when all menus should be closed (including parent menus). Used internally.
+     * @internal
+     */
+    readonly closeAll: _angular_core.OutputEmitterRef<void>;
+    /**
+     * Shows or hides the menu.
+     *
+     * You probably want to react to openChange events from outside to update your variable accordingly.
+     */
+    readonly open: _angular_core.ModelSignal<boolean>;
+    protected readonly maybeCallback: typeof maybeCallback;
+    private readonly _isTouchDevice;
+    private readonly _popover;
+    private readonly _menuItems;
+    private readonly _childMenus;
+    private readonly _openSubmenuOnHover;
+    protected readonly autofocus: _angular_core.WritableSignal<boolean>;
+    constructor();
+    /**
+     * Shows the menu.
+     * @param focus Whether to focus the menu after showing it. Defaults to `true`.
+     */
+    show(focus?: boolean): void;
+    /**
+     * Hides the menu.
+     * @param emitCloseEvent Whether to emit the close event. Defaults to `true`.
+     */
+    hide(emitCloseEvent?: boolean): void;
+    /**
+     * Toggles the menu open or closed.
+     */
+    toggle(): void;
+    protected handleKeydown(event: KeyboardEvent, subMenu?: NgnMenu): void;
+    protected doCloseAll(): void;
+    protected itemClicked(item: MenuItem): void;
+    protected closeChildMenus(closeBy: 'hover' | 'click' | 'arrow', menuItem: HTMLButtonElement | null): void;
+    protected openChildMenu(childMenu: NgnMenu, menuItem: HTMLButtonElement | null, openBy: 'hover' | 'click' | 'arrow'): void;
+    protected popoverOpenChange(newState: boolean): void;
+    protected popoverClosed(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnMenu, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgnMenu, "ngn-menu", never, { "elementId": { "alias": "elementId"; "required": false; "isSignal": true; }; "anchor": { "alias": "anchor"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": true; "isSignal": true; }; "autoAnchorAria": { "alias": "autoAnchorAria"; "required": false; "isSignal": true; }; "popover": { "alias": "popover"; "required": false; "isSignal": true; }; "placement": { "alias": "placement"; "required": false; "isSignal": true; }; "iconSubmenuIndicator": { "alias": "iconSubmenuIndicator"; "required": false; "isSignal": true; }; "isSubMenu": { "alias": "isSubMenu"; "required": false; "isSignal": true; }; "openSubmenuOnHover": { "alias": "openSubmenuOnHover"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; }, { "closed": "closed"; "closing": "closing"; "closeAll": "closeAll"; "open": "openChange"; }, never, never, true, never>;
+}
+
+/**
+ * Lazily creates (or reuses) an `NgnMenu` popover and shows it anchored either
+ * at a viewport point (context-menu style) or to an element. Returns the
+ * `ComponentRef` so callers can keep it for reuse and destroy it on teardown.
+ */
+declare function openMenuAt(vcr: ViewContainerRef, existing: ComponentRef<NgnMenu> | undefined, items: MenuItem[], anchor: Anchor, placement?: Placement): ComponentRef<NgnMenu>;
+
+export { NgnContextMenu, NgnMenu, openMenuAt };
+export type { MenuItem, MenuItemDefault, MenuItemSeparator };

package/types/ngneers-controls-message.d.ts

@@ -0,0 +1,21 @@
+import * as i0 from '@angular/core';
+import * as _ngneers_controls_custom_types from '@ngneers/controls-custom-types';
+import * as _iconify_types from '@iconify/types';
+import * as _ngneers_controls_api_ng from '@ngneers/controls/api/ng';
+import * as _ngneers_controls_themes from '@ngneers/controls-themes';
+import { NgnBase } from '@ngneers/controls/base';
+
+/**
+ * @category control
+ */
+declare class NgnMessage extends NgnBase<'message'> {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"message", ["root", "content", "icon", `kind-${string}`, `color-${string}`], readonly []>>;
+    /**
+     * Set an icon to display before the text.
+     */
+    readonly icon: i0.InputSignal<_iconify_types.IconifyIcon | _ngneers_controls_custom_types.NgnIconEntry | undefined>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgnMessage, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<NgnMessage, "ngn-message", never, { "icon": { "alias": "icon"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+export { NgnMessage };