@ngneers/controls 0.0.1-next.0

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

@@ -0,0 +1,330 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef, InjectionToken, Provider, Injector, OnInit } from '@angular/core';
+import { NgnActionButtonConfig } from '@ngneers/controls/api';
+import * as _ngneers_controls_custom_types from '@ngneers/controls-custom-types';
+import { CustomColor, IconType } from '@ngneers/controls-custom-types';
+import * as _iconify_types from '@iconify/types';
+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 { NgnBase } from '@ngneers/controls/base';
+
+type HeaderTemplateType = {
+    header?: string;
+    closable: boolean;
+    closeSnackbar: () => void;
+};
+type ContentTemplateType = {
+    content?: string;
+};
+type NgnSnackbarOptionsMeta = {
+    closable?: boolean;
+    color?: CustomColor;
+    icon?: IconType;
+    autoHide?: number | false;
+    actions?: NgnActionButtonConfig[];
+    showProgress?: boolean;
+    pauseOnHover?: boolean;
+    ariaLive?: 'polite' | 'assertive' | 'off';
+};
+type NgnSnackbarOptions = NgnSnackbarOptionsMeta & {
+    header?: string;
+    content?: string;
+    headerTemplate?: TemplateRef<HeaderTemplateType>;
+    contentTemplate?: TemplateRef<ContentTemplateType>;
+};
+type NgnSnackbarRef = {
+    hide: () => void;
+};
+
+type NgnSnackbarFeature = {
+    providers: Provider[];
+};
+declare const NGN_SNACKBAR_USER_DEFAULTS: InjectionToken<NgnSnackbarOptionsMeta>;
+declare function withSnackbars(defaultOptions?: NgnSnackbarOptionsMeta): NgnSnackbarFeature;
+
+declare class SnackbarCreator {
+    private readonly _manager;
+    constructor();
+    show(options: NgnSnackbarOptions): NgnSnackbarRef;
+}
+declare function injectSnackbarCreator(injector?: Injector): SnackbarCreator;
+
+/**
+ * Template inputs for {@link NgnSnackbar}, extracted into a dedicated base class so the
+ * component itself stays focused on behavior.
+ */
+declare abstract class SnackbarTemplates extends NgnBase<'snackbar'> {
+    /** Custom template for the snackbar body, rendered in place of the plain `content` string. */
+    readonly templateContent: _angular_core.InputSignal<TemplateRef<ContentTemplateType> | null | undefined>;
+    /** Custom template for the snackbar header, rendered in place of the plain `header` string. */
+    readonly templateHeader: _angular_core.InputSignal<TemplateRef<HeaderTemplateType> | null | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SnackbarTemplates, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SnackbarTemplates, never, never, { "templateContent": { "alias": "templateContent"; "required": false; "isSignal": true; }; "templateHeader": { "alias": "templateHeader"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * @category control
+ */
+declare class NgnSnackbar extends SnackbarTemplates implements OnInit {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"snackbar", ["root", "host", "body", "anim-enter", "anim-leave", "defaultHeader", "defaultHeaderText", "defaultContent", "actions", "progressBar", "closeButton", "sr-only", `color-${string}`], 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;
+        };
+    }, "_">;
+    private readonly _host;
+    /** Heading text shown at the top of the snackbar. Overridden by {@link templateHeader}. */
+    readonly header: _angular_core.InputSignal<string | undefined>;
+    /** Body text of the snackbar. Overridden by {@link templateContent}. */
+    readonly content: _angular_core.InputSignal<string | undefined>;
+    /** Icon shown at the start of the snackbar. */
+    readonly icon: _angular_core.InputSignal<_iconify_types.IconifyIcon | _ngneers_controls_custom_types.NgnIconEntry | undefined>;
+    /** Icon used for the close button when {@link closable} is enabled. */
+    readonly iconClose: _angular_core.InputSignal<_iconify_types.IconifyIcon | _ngneers_controls_custom_types.NgnIconEntry | undefined>;
+    /**
+     * Whether to render a close button that lets the user dismiss the snackbar.
+     * @default false
+     */
+    readonly closable: _angular_core.InputSignal<boolean | undefined>;
+    /**
+     * Time in ms before the snackbar auto-dismisses, or `false` to keep it open
+     * until dismissed manually.
+     * @default 5000
+     */
+    readonly autoHide: _angular_core.InputSignal<number | false | undefined>;
+    /** Emitted when the snackbar is dismissed (by the timer, close button, or an action). */
+    readonly closeSnackbar: _angular_core.OutputEmitterRef<void>;
+    /**
+     * Action buttons rendered at the end of the snackbar. Clicking any action always
+     * dismisses the snackbar; its `action` callback fires first. Import the config
+     * type from `@ngneers/controls/api`.
+     */
+    readonly actions: _angular_core.InputSignal<NgnActionButtonConfig[] | undefined>;
+    /**
+     * Shows a thin progress bar at the bottom of the snackbar that depletes over the
+     * {@link autoHide} duration.
+     * @default true
+     */
+    readonly showProgress: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Pauses the auto-hide timer and progress bar while the snackbar is hovered,
+     * resuming from the current position on mouse leave.
+     * @default true
+     */
+    readonly pauseOnHover: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Politeness of the live region used to announce the snackbar to assistive tech.
+     * When omitted, it is derived from {@link color}: `error`/`warning` announce as
+     * `assertive` (mapped to `role="alert"`), everything else as `polite`
+     * (`role="status"`).
+     */
+    readonly ariaLive: _angular_core.InputSignal<"polite" | "assertive" | "off" | undefined>;
+    /** Resolved live-region politeness — explicit input, else derived from color. */
+    protected readonly liveMode: _angular_core.Signal<"polite" | "assertive" | "off">;
+    /** Landmark role paired with {@link liveMode} — `alert` when assertive, else `status`. */
+    protected readonly role: _angular_core.Signal<"status" | "alert">;
+    /**
+     * A visually-hidden severity prefix (e.g. "Error:") announced before the header
+     * so screen-reader users get the semantic that sighted users read from color.
+     * Only emitted for the known semantic colors.
+     */
+    protected readonly severityLabel: _angular_core.Signal<string | undefined>;
+    protected readonly paused: _angular_core.WritableSignal<boolean>;
+    /** Auto-hide duration in ms, or 0 when auto-hide is disabled. Drives the progress bar. */
+    protected readonly autoHideMs: _angular_core.Signal<number>;
+    private _closeTimeout?;
+    private _remaining;
+    private _startedAt;
+    private _hovered;
+    private _focused;
+    private _regionPaused;
+    /** Element that had focus before the user moved into the snackbar; focus returns here on close. */
+    private _returnFocus;
+    ngOnInit(): void;
+    private startHideTimer;
+    private pauseHideTimer;
+    /**
+     * Pause the auto-hide timer while the snackbar is hovered (opt-in via
+     * {@link pauseOnHover}), focused (always — a WCAG 2.2.1 requirement so keyboard
+     * and screen-reader users can read it), or while the whole region holds focus,
+     * resuming once none holds.
+     */
+    private updatePause;
+    /** Move DOM focus to the snackbar root (used by the region's roving/hotkey navigation). */
+    focus(): void;
+    /** Freeze the timer because the notification region as a whole holds focus. */
+    regionPause(): void;
+    /** Release the region-level freeze; resumes unless still hovered/focused. */
+    regionResume(): void;
+    protected close(): void;
+    /** Return focus to the pre-snackbar element when it is dismissed while focused within. */
+    private restoreFocus;
+    protected onEscape(): void;
+    protected mouseEnter(): void;
+    protected mouseLeave(): void;
+    protected focusEnter(event: FocusEvent): void;
+    protected focusLeave(event: FocusEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnSnackbar, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgnSnackbar, "ngn-snackbar", never, { "header": { "alias": "header"; "required": false; "isSignal": true; }; "content": { "alias": "content"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconClose": { "alias": "iconClose"; "required": false; "isSignal": true; }; "closable": { "alias": "closable"; "required": false; "isSignal": true; }; "autoHide": { "alias": "autoHide"; "required": false; "isSignal": true; }; "actions": { "alias": "actions"; "required": false; "isSignal": true; }; "showProgress": { "alias": "showProgress"; "required": false; "isSignal": true; }; "pauseOnHover": { "alias": "pauseOnHover"; "required": false; "isSignal": true; }; "ariaLive": { "alias": "ariaLive"; "required": false; "isSignal": true; }; }, { "closeSnackbar": "closeSnackbar"; }, never, never, true, never>;
+}
+
+export { NGN_SNACKBAR_USER_DEFAULTS, NgnSnackbar, SnackbarCreator, injectSnackbarCreator, withSnackbars };
+export type { ContentTemplateType, HeaderTemplateType, NgnSnackbarFeature, NgnSnackbarOptions, NgnSnackbarOptionsMeta, NgnSnackbarRef };

package/types/ngneers-controls-spin-buttons.d.ts

@@ -0,0 +1,69 @@
+import * as _ngneers_controls_custom_types from '@ngneers/controls-custom-types';
+import * as _iconify_types from '@iconify/types';
+import * as _angular_core from '@angular/core';
+import * as _ngneers_controls_api_ng from '@ngneers/controls/api/ng';
+import * as _ngneers_controls_themes from '@ngneers/controls-themes';
+import { NgnBase, AnyNgnBase } from '@ngneers/controls/base';
+
+/**
+ * Increment/decrement buttons for a steppable control (e.g. `ngnNumberInput`).
+ *
+ * Inside an `ngn-input-field` the buttons find the field's primary control
+ * automatically; outside (or to target a specific control) bind `[for]` to a
+ * control instance (e.g. a `#num="ngnNumberInput"` template reference).
+ *
+ * The buttons are a pointer affordance only (`tabindex="-1"`, `aria-hidden`):
+ * keyboard users step via `ArrowUp`/`ArrowDown` on the control itself, which
+ * carries the `spinbutton` role. Press-and-hold auto-repeats; the buttons
+ * disable at the control's min/max bounds.
+ *
+ * Use `buttons="increment"`/`buttons="decrement"` on two instances to flank
+ * an input on both sides; the stacked/inline arrangement of the `both` pair
+ * is a theme kind (`kind="stacked" | "inline"`).
+ *
+ * @category control
+ */
+declare class NgnSpinButtons extends NgnBase<'spinButtons'> {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"spinButtons", ["root", "leading", "trailing", "pair", `kind-${string}`], readonly [{
+        readonly class: "decrement";
+        readonly template: _ngneers_controls_themes.ControlTemplate<"button", ["root", "inline", "loading", `kind-${string}`, `color-${string}`], readonly []>;
+    }, {
+        readonly class: "increment";
+        readonly template: _ngneers_controls_themes.ControlTemplate<"button", ["root", "inline", "loading", `kind-${string}`, `color-${string}`], readonly []>;
+    }]>>;
+    /**
+     * Which buttons to render. Use two instances (`decrement` + `increment`)
+     * to place one button on each side of the input.
+     * @default 'both'
+     */
+    readonly buttons: _angular_core.InputSignal<"decrement" | "increment" | "both">;
+    /**
+     * The control to step. Falls back to the primary control of a surrounding
+     * `ngn-input-field`.
+     */
+    readonly for: _angular_core.InputSignal<AnyNgnBase | undefined>;
+    /** Custom icon for the increment button. */
+    readonly iconIncrement: _angular_core.InputSignal<_iconify_types.IconifyIcon | _ngneers_controls_custom_types.NgnIconEntry | undefined>;
+    /** Custom icon for the decrement button. */
+    readonly iconDecrement: _angular_core.InputSignal<_iconify_types.IconifyIcon | _ngneers_controls_custom_types.NgnIconEntry | undefined>;
+    private readonly _field;
+    /** The resolved step target: explicit `for` wins over the surrounding field. */
+    protected readonly target: _angular_core.Signal<AnyNgnBase | undefined>;
+    private _holdTimeout;
+    private _holdInterval;
+    constructor();
+    protected canStep(direction: 1 | -1): boolean;
+    /**
+     * First step on pointer down (like native spinners), then auto-repeat while
+     * held. `preventDefault` keeps focus (and caret) where it is.
+     */
+    protected pressStart(event: PointerEvent, direction: 1 | -1): void;
+    protected pressEnd(): void;
+    /** Stepping already happened on pointer down — just keep the click local. */
+    protected clicked(event: MouseEvent): void;
+    private _stopRepeat;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnSpinButtons, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgnSpinButtons, "ngn-spin-buttons", never, { "buttons": { "alias": "buttons"; "required": false; "isSignal": true; }; "for": { "alias": "for"; "required": false; "isSignal": true; }; "iconIncrement": { "alias": "iconIncrement"; "required": false; "isSignal": true; }; "iconDecrement": { "alias": "iconDecrement"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgnSpinButtons };

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

@@ -0,0 +1,117 @@
+import * as _angular_core from '@angular/core';
+import { ElementRef, Signal, Injector } from '@angular/core';
+import { CustomColor } from '@ngneers/controls-custom-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';
+
+/**
+ * Creates an instance of the spinner creator.
+ *
+ * @param injector The injector to use. Defaults to the current injector.
+ * @returns The spinner creator.
+ */
+declare function injectSpinnerCreator(injector?: Injector): NgnSpinnerCreator;
+/**
+ * Creates and manages a conditional spinner based on a visibility signal.
+ * @param isVisible Signal that determines whether the spinner is visible.
+ * @param options Optional configuration for the spinner.
+ */
+declare function createConditionalSpinner(isVisible: Signal<boolean>, options?: {
+    /**
+     * Options for the spinner instance.
+     */
+    spinnerOptions?: SpinnerOptions;
+    /**
+     * Debounce time in milliseconds or a boolean indicating whether to debounce (default is 200ms).
+     */
+    debounce?: number | boolean;
+    /**
+     * The target element where the spinner will be attached.
+     * If a string is provided, it will be used as a selector to find the element.
+     * If omitted, the spinner will be attached to the host element of the current injector.
+     */
+    element?: SpinnerTarget;
+    /**
+     * The injector to use. If omitted, the current injector will be used.
+     */
+    injector?: Injector;
+}): void;
+type SpinnerRef = {
+    /**
+     * Hides the spinner.
+     */
+    hide: () => void;
+};
+type SpinnerTarget = HTMLElement | ElementRef<HTMLElement> | string;
+type SpinnerOptions = {
+    /**
+     * The color of the spinner.
+     */
+    color?: CustomColor;
+    /**
+     * The diameter of the spinner in pixels.
+     * @default 64
+     */
+    size?: number;
+    /**
+     * The thickness of the spinner's stroke. If not provided,
+     * a default thickness derived from the size will be used.
+     * @default undefined
+     */
+    thickness?: string;
+    /**
+     * Whether the spinner should be centered within its container.
+     * @default true
+     */
+    centered?: boolean;
+    /**
+     * Set aria busy attribute on the reference element while the spinner is visible.
+     * @default true
+     */
+    ariaBusy?: boolean;
+};
+declare class NgnSpinnerCreator {
+    private readonly _vcr;
+    private readonly _destroyRef;
+    private _destroyed;
+    constructor();
+    /**
+     * Shows a spinner on the specified target element.
+     * @param target The target element or selector where the spinner will be attached.
+     * If a string is provided, it will be used as a selector to find the element.
+     * If the element is not found, the spinner will be retried until it is found.
+     * @param options Optional configuration for the spinner.
+     * @returns A reference to the spinner instance.
+     */
+    show(target: SpinnerTarget, options?: SpinnerOptions): SpinnerRef;
+    private _tryAttach;
+}
+
+/**
+ * @category control
+ */
+declare class NgnSpinner extends NgnBase<'spinner'> {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"spinner", ["root", "circle", "svg", `color-${string}`, "centered"], readonly []>>;
+    /**
+     * Diameter of the spinner in pixels.
+     * @default 64
+     */
+    readonly size: _angular_core.InputSignal<number>;
+    /**
+     * Stroke width of the spinner ring as a CSS length (e.g. `'4px'`).
+     * Falls back to the theme's default thickness when unset.
+     */
+    readonly thickness: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Whether to center the spinner within its containing block.
+     * @default false
+     */
+    readonly centered: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    protected readonly viewBox: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnSpinner, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgnSpinner, "ngn-spinner", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "thickness": { "alias": "thickness"; "required": false; "isSignal": true; }; "centered": { "alias": "centered"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgnSpinner, createConditionalSpinner, injectSpinnerCreator };
+export type { SpinnerOptions, SpinnerRef, SpinnerTarget };