@arsedizioni/ars-utils 22.1.5 → 22.5.2

package/types/arsedizioni-ars-utils-ui.controls.d.ts

@@ -0,0 +1,413 @@
+import * as _angular_core from '@angular/core';
+import { OnDestroy } from '@angular/core';
+import { ControlValueAccessor, NgControl } from '@angular/forms';
+import { NameValueItem, INode } from '@arsedizioni/ars-utils/core';
+
+declare class ButtonSelectorComponent implements OnDestroy, ControlValueAccessor {
+    ngControl: NgControl;
+    /** Emitted whenever the selected value changes (including programmatic resets). */
+    readonly changed: _angular_core.OutputEmitterRef<NameValueItem<any>>;
+    /** Emitted when the user explicitly picks an item from the menu. */
+    readonly selected: _angular_core.OutputEmitterRef<NameValueItem<any>>;
+    private readonly stateChanges;
+    private focused;
+    private _value;
+    set value(value: NameValueItem<any> | undefined);
+    /**
+     * Updates the internal state. Form propagation is skipped for model->view
+     * writes (writeValue) to avoid the CVA echo loop, and performed for
+     * user/programmatic changes via the `value` setter.
+     * @param value     - The new value to store and display.
+     * @param propagate - When `true`, notifies the registered onChange callback.
+     */
+    private setValue;
+    /** The current value as the selected item. */
+    get value(): NameValueItem<any> | undefined;
+    private _disabled;
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    private propagateChange;
+    private propagateTouched;
+    id: string;
+    describedBy: string;
+    private readonly renderer;
+    /** Currently selected item, kept in sync with the form control value. */
+    protected readonly current: _angular_core.WritableSignal<NameValueItem<any>>;
+    /** Width of the trigger button in pixels. Use `-1` for 100 %, `0` for `auto`. */
+    readonly width: _angular_core.InputSignal<number>;
+    /** Border thickness override. Use `-1` to inherit. */
+    readonly border: _angular_core.InputSignal<number>;
+    /** CSS border-radius of the trigger button. Defaults to a pill shape. */
+    readonly borderRadius: _angular_core.InputSignal<string>;
+    /** Placeholder label shown when nothing is selected. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** Label shown above the selected value (replaces `label` when an item is selected). */
+    readonly labelSelected: _angular_core.InputSignal<string>;
+    /** List of selectable options. */
+    readonly options: _angular_core.InputSignal<NameValueItem<any>[]>;
+    /** When `true`, the first available option is pre-selected on init. */
+    readonly autoSelect: _angular_core.InputSignal<boolean>;
+    constructor(ngControl: NgControl);
+    ngOnDestroy(): void;
+    /**
+     * Writes a new value to the component (called by the form layer).
+     * @param value - The new value to display.
+     */
+    writeValue(value: any): void;
+    /**
+     * Registers the on-change callback (called by the form layer).
+     * @param fn - Callback to invoke whenever the value changes.
+     */
+    registerOnChange(fn: (_: any) => void): void;
+    /**
+     * Registers the on-touched callback (called by the form layer).
+     * @param fn - Callback to invoke when the control is touched.
+     */
+    registerOnTouched(fn: () => void): void;
+    /**
+     * Sets the ARIA described-by IDs for accessibility.
+     * @param ids - The list of element IDs to associate with this control.
+     */
+    setDescribedByIds(ids: string[]): void;
+    /**
+     * Updates the disabled state when the Angular form layer changes it.
+     * @param isDisabled - Whether the control should be disabled.
+     */
+    setDisabledState(isDisabled: boolean): void;
+    /**
+     * Handles a click on the container element, focusing it and marking it as touched.
+     */
+    onContainerClick(): void;
+    /**
+     * Selects an option and optionally emits the `selected` output event.
+     * @param item   - The item to select.
+     * @param notify - When `true` (default), emits the `selected` event.
+     */
+    select(item: NameValueItem<any>, notify?: boolean): void;
+    /** Clears the current selection and resets the control to an empty state. */
+    reset(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ButtonSelectorComponent, [{ optional: true; self: true; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ButtonSelectorComponent, "button-selector", never, { "disabled": { "alias": "disabled"; "required": false; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "border": { "alias": "border"; "required": false; "isSignal": true; }; "borderRadius": { "alias": "borderRadius"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelSelected": { "alias": "labelSelected"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "autoSelect": { "alias": "autoSelect"; "required": false; "isSignal": true; }; }, { "changed": "changed"; "selected": "selected"; }, never, never, true, never>;
+}
+
+interface ButtonToggleInfo {
+    value: boolean;
+    toggled: boolean;
+}
+declare class ButtonToggleComponent {
+    /** Emitted each time the button is clicked. Carries the current `value` and the new `toggled` state. */
+    readonly changed: _angular_core.OutputEmitterRef<ButtonToggleInfo>;
+    /** Current value bound from the parent. Drives label and icon selection. */
+    readonly value: _angular_core.InputSignal<boolean>;
+    /** Width of the button in pixels. Use `-1` for automatic sizing. */
+    readonly width: _angular_core.InputSignal<number>;
+    /** Border thickness override in pixels. Use `-1` to inherit. */
+    readonly border: _angular_core.InputSignal<number>;
+    /** Label shown when `value` is `true`. */
+    readonly labelOn: _angular_core.InputSignal<string>;
+    /** Label shown when `value` is `false`. */
+    readonly labelOff: _angular_core.InputSignal<string>;
+    /** Material icon name shown when `value` is `true`. */
+    readonly iconOn: _angular_core.InputSignal<string>;
+    /** Material icon name shown when `value` is `false`. */
+    readonly iconOff: _angular_core.InputSignal<string>;
+    /** CSS class applied to the button at all breakpoints. */
+    readonly cssClass: _angular_core.InputSignal<string>;
+    /** CSS class applied to the button on `xs` screens. */
+    readonly cssClassSmall: _angular_core.InputSignal<string>;
+    /** Resolves the appropriate label for the current value state. */
+    protected readonly label: _angular_core.Signal<string>;
+    /** Resolves the appropriate icon name for the current value state. */
+    protected readonly icon: _angular_core.Signal<string>;
+    /**
+     * Toggles the button state and emits the `changed` event.
+     * The emitted `toggled` value is the logical inverse of the current `value`.
+     */
+    toggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ButtonToggleComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ButtonToggleComponent, "button-toggle", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "border": { "alias": "border"; "required": false; "isSignal": true; }; "labelOn": { "alias": "labelOn"; "required": false; "isSignal": true; }; "labelOff": { "alias": "labelOff"; "required": false; "isSignal": true; }; "iconOn": { "alias": "iconOn"; "required": false; "isSignal": true; }; "iconOff": { "alias": "iconOff"; "required": false; "isSignal": true; }; "cssClass": { "alias": "cssClass"; "required": false; "isSignal": true; }; "cssClassSmall": { "alias": "cssClassSmall"; "required": false; "isSignal": true; }; }, { "changed": "changed"; }, never, never, true, never>;
+}
+
+declare class ChipsSelectorComponent implements OnDestroy, ControlValueAccessor {
+    ngControl: NgControl;
+    /** Emitted when the selection changes. Carries the new array of selected items, or `undefined` when cleared. */
+    readonly changed: _angular_core.OutputEmitterRef<NameValueItem<any>[]>;
+    protected readonly containerId: string;
+    protected readonly containerWidth: _angular_core.WritableSignal<number>;
+    private focused;
+    private readonly stateChanges;
+    private readonly destroyRef;
+    private changesEnabled;
+    private destroyed;
+    private widthRetries;
+    /** Observer that tracks size changes of the container element. */
+    private resizeObserver?;
+    /** Debounce bridge for `ResizeObserver` notifications. */
+    private readonly resize$;
+    /** List of available options to display as chips. */
+    readonly options: _angular_core.InputSignal<NameValueItem<any>[]>;
+    /** Minimum width in pixels when collapsed. Use `-1` for automatic. */
+    readonly collapsedWidth: _angular_core.InputSignal<number>;
+    /** Display mode used when the selector is in collapsed state. */
+    readonly collapsedDisplayMode: _angular_core.InputSignal<"dropdown" | "button">;
+    /** Pixel threshold below which the selector collapses. Use `-1` to disable. */
+    readonly collapseAt: _angular_core.InputSignal<number>;
+    /** When `true`, `collapseAt` is compared against the container width rather than the window width. */
+    readonly collapseAtContainer: _angular_core.InputSignal<boolean>;
+    protected readonly collapsed: _angular_core.Signal<boolean>;
+    /** Label shown in the dropdown / above the chip list. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** When `true`, multiple chips can be selected simultaneously. */
+    readonly multiple: _angular_core.InputSignal<boolean>;
+    /** When `true`, at least one item must remain selected. */
+    readonly mustSelect: _angular_core.InputSignal<boolean>;
+    /** Layout mode: `'collapsed'` forces dropdown mode, `'dynamic'` collapses based on `collapseAt`. */
+    readonly mode: _angular_core.InputSignal<"collapsed" | "dynamic">;
+    /** When `true`, chips are stacked vertically instead of wrapping horizontally. */
+    readonly stacked: _angular_core.InputSignal<boolean>;
+    /** Chips below this index receive extra padding to align with other UI elements. */
+    readonly padAt: _angular_core.InputSignal<number>;
+    /** When `true`, the control is required. */
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Placeholder text shown when no value is selected. */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    private _disabled;
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    id: string;
+    describedBy: string;
+    /** True when the label should float above the field (focused or has a value). */
+    get shouldLabelFloat(): boolean;
+    private _value?;
+    set value(value: NameValueItem<any>[] | undefined);
+    /**
+     * Updates the internal state and selection mirrors.
+     * @param value     - The new selection array.
+     * @param propagate - When `true`, notifies the registered onChange callback.
+     */
+    private setValue;
+    /** The current value as an array of selected items. */
+    get value(): NameValueItem<any>[] | undefined;
+    /** True when no item is selected. */
+    get empty(): boolean;
+    /** True when the control has validation errors and has been touched. */
+    get errorState(): boolean;
+    private propagateChange;
+    private propagateTouched;
+    private readonly renderer;
+    private readonly cdr;
+    /** Currently selected items (may contain multiple entries when `multiple` is `true`). */
+    protected selection: NameValueItem<any>[];
+    /** The single selected item — used in `button` collapsed-display mode. */
+    protected singleSelection?: NameValueItem<any>;
+    constructor(ngControl: NgControl);
+    ngOnDestroy(): void;
+    /**
+     * Measures the container (or window) width and updates the `containerWidth` signal,
+     * retrying after 100 ms if the element is not yet laid out.
+     */
+    private updateContainerWidth;
+    /**
+     * Resolves the effective selection array for the current display mode.
+     * In single-select collapsed button mode the `singleSelection` item is wrapped in an array.
+     * @returns The array of currently selected items.
+     */
+    private getSelection;
+    /**
+     * Schedules a value update after a short delay, giving the template time to sync `ngModel`.
+     */
+    updateValue(): void;
+    /**
+     * Returns `true` when the given item can be selected in the current mode.
+     * In single-select mode an already-selected item is not re-selectable.
+     * @param item - The item to check.
+     * @returns True when the item is selectable.
+     */
+    isSelectable(item: NameValueItem<any>): boolean;
+    /**
+     * Writes a new value to the component (called by the form layer).
+     * @param value - The new selection to display.
+     */
+    writeValue(value: any): void;
+    /**
+     * Registers the on-change callback (called by the form layer).
+     * @param fn - Callback to invoke whenever the value changes.
+     */
+    registerOnChange(fn: (_: any) => void): void;
+    /**
+     * Registers the on-touched callback (called by the form layer).
+     * @param fn - Callback to invoke when the control is touched.
+     */
+    registerOnTouched(fn: () => void): void;
+    /**
+     * Sets the ARIA described-by IDs for accessibility.
+     * @param ids - The list of element IDs to associate with this control.
+     */
+    setDescribedByIds(ids: string[]): void;
+    /**
+     * Updates the disabled state when the Angular form layer changes it.
+     * @param isDisabled - Whether the control should be disabled.
+     */
+    setDisabledState(isDisabled: boolean): void;
+    /**
+     * Handles a click on the container element, focusing it and marking it as touched.
+     */
+    onContainerClick(): void;
+    /**
+     * Clears the current selection and stops the event from bubbling.
+     * @param e - The originating click event.
+     */
+    clear(e: Event): void;
+    /**
+     * Selects a single item, replacing any existing selection.
+     * @param item - The item to select. Does nothing when `undefined`.
+     */
+    select(item?: NameValueItem<any>): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChipsSelectorComponent, [{ optional: true; self: true; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChipsSelectorComponent, "chips-selector", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "collapsedWidth": { "alias": "collapsedWidth"; "required": false; "isSignal": true; }; "collapsedDisplayMode": { "alias": "collapsedDisplayMode"; "required": false; "isSignal": true; }; "collapseAt": { "alias": "collapseAt"; "required": false; "isSignal": true; }; "collapseAtContainer": { "alias": "collapseAtContainer"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "mustSelect": { "alias": "mustSelect"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "stacked": { "alias": "stacked"; "required": false; "isSignal": true; }; "padAt": { "alias": "padAt"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; }; }, { "changed": "changed"; }, never, never, true, never>;
+}
+
+declare class TreePickerComponent {
+    /** Nested tree data to display. */
+    readonly tree: _angular_core.InputSignal<INode[]>;
+    /** Currently selected node ids. Supports two-way binding via [(selection)]. */
+    readonly selection: _angular_core.ModelSignal<string[]>;
+    /** When true, checkboxes and chip remove buttons are disabled (mirrors Material convention). */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    /** Description to display when no selection is made. */
+    readonly descriptionEmpty: _angular_core.InputSignal<string>;
+    /** Maximum number of tree levels to display (default: 3). */
+    readonly maxDepth: _angular_core.InputSignal<number>;
+    /**
+     * List of node IDs at depth >= maxDepth that unlock selection for themselves
+     * and all their descendants, regardless of depth.
+     */
+    readonly maxDepthOverrides: _angular_core.InputSignal<string[]>;
+    /**
+     * Number of levels to auto-expand on load.
+     * 0 or undefined = only top level visible (no expansion);
+     * 1 = expand depth-0 nodes; 2 = expand depth-0 and depth-1 nodes; etc.
+     * Must be less than maxDepth.
+     */
+    readonly minDepth: _angular_core.InputSignal<number>;
+    /**
+     * Emits the count of visible selected nodes whenever the selection changes.
+     * Emits 0 when nothing is selected (meaning all items are implicitly included).
+     */
+    readonly selectionCount: _angular_core.OutputEmitterRef<number>;
+    /** Emits void whenever the user changes the selection (toggle, remove, clear). */
+    readonly changed: _angular_core.OutputEmitterRef<void>;
+    private readonly _treeRef;
+    private readonly _elRef;
+    /**
+     * Set of all node IDs selectable via overrides: each listed root and all its descendants.
+     * Recomputed whenever the tree data or the override list changes.
+     */
+    private readonly _overrideSubtreeSet;
+    /** All three maps rebuilt lazily as a single computed whenever taxonomy changes. */
+    private readonly _maps;
+    /** O(1) set of selected ids, rebuilt only when selection changes. */
+    private readonly _selectedSet;
+    /** True when at least one node is explicitly selected. */
+    protected readonly hasSelection: _angular_core.Signal<boolean>;
+    /** Count of selected nodes within selectable levels (depth < maxDepth or in overrides), shown in the tab label. */
+    protected readonly selectedVisibleCount: _angular_core.Signal<number>;
+    readonly treeChildrenAccessor: (node: INode) => INode[];
+    readonly hasChild: (_: number, node: INode) => boolean;
+    /** Returns true when the node can be selected: depth < maxDepth or explicitly listed in maxDepthOverrides. */
+    protected isSelectable(node: INode): boolean;
+    private _isSelectableNode;
+    /** Current filter text. */
+    protected readonly filterText: _angular_core.WritableSignal<string>;
+    /** Nodes matching the current filter text, in nodeMap iteration order. */
+    protected readonly filteredItems: _angular_core.WritableSignal<INode[]>;
+    /** Index of the currently highlighted filtered node (-1 = none). */
+    protected readonly filterIndex: _angular_core.WritableSignal<number>;
+    /** The currently highlighted filtered node, or null. */
+    protected readonly filteredNode: _angular_core.Signal<INode>;
+    constructor();
+    /** Expands all visible nodes in the tree. */
+    protected expandAll(): void;
+    /** Collapses all nodes in the tree. */
+    protected collapseAll(): void;
+    /** Clears the entire selection. */
+    protected clearAll(): void;
+    /** Searches nodes by text and moves to the first match. */
+    protected doFilter(): void;
+    /** Clears the filter and restores the original tree state. */
+    protected clearFilter(): void;
+    /** Moves to the next matching node, cycling back to the first. */
+    protected nextFiltered(): void;
+    /** Returns true when the node is the currently highlighted filter match. */
+    protected isFilteredNode(node: INode): boolean;
+    /** Expands ancestors of the target node and scrolls it into view. */
+    private _scrollToFiltered;
+    /**
+     * Returns true when the node is in the active selection.
+     * @param node - tree node to check
+     * @returns true if selected
+     */
+    protected isSelected(node: INode): boolean;
+    /**
+     * Returns true when a subset (but not all) of the node's descendants are selected,
+     * producing the indeterminate checkbox state.
+     * @param node - tree node to evaluate
+     * @returns true if the node is in a partial-selection (indeterminate) state
+     */
+    protected isIndeterminate(node: INode): boolean;
+    /**
+     * Toggles the node and all its descendants; then syncs the ancestor chain.
+     * @param node - the node that was clicked
+     */
+    protected toggleNode(node: INode): void;
+    /**
+     * Deselects the node and all its descendants. Called by the chip remove button.
+     * @param node - the node to remove from the selection
+     */
+    protected removeNode(node: INode): void;
+    /**
+     * Returns the INode for the given id, or undefined if not found.
+     * @param id - node id to look up
+     * @returns the matching INode
+     */
+    protected nodeById(id: string): INode | undefined;
+    /**
+     * Returns true when the node at the given id is within the visible depth range
+     * and should appear in the chip list.
+     * @param id - node id to check
+     * @returns true if the node depth is less than maxDepth
+     */
+    protected isChipVisible(id: string): boolean;
+    /**
+     * Returns only the selectable descendants of node (depth < maxDepth or in overrides),
+     * used for indeterminate state and parent auto-selection logic.
+     * @param node - root of the subtree to traverse
+     * @returns flat array of selectable descendant INodes
+     */
+    private _getSelectableDescendants;
+    /**
+     * Walks up the ancestor chain from node, selecting a parent only when all
+     * its descendants are in the set, deselecting it otherwise.
+     * @param node - starting node for the upward traversal
+     * @param set - mutable selection set updated in place
+     */
+    private _syncParentsInSet;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TreePickerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TreePickerComponent, "tree-picker", never, { "tree": { "alias": "tree"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "descriptionEmpty": { "alias": "descriptionEmpty"; "required": false; "isSignal": true; }; "maxDepth": { "alias": "maxDepth"; "required": false; "isSignal": true; }; "maxDepthOverrides": { "alias": "maxDepthOverrides"; "required": false; "isSignal": true; }; "minDepth": { "alias": "minDepth"; "required": false; "isSignal": true; }; }, { "selection": "selectionChange"; "selectionCount": "selectionCount"; "changed": "changed"; }, never, never, true, never>;
+}
+
+/**
+ * A blank calendar header that hides the month/year navigation controls.
+ * Used when an inline calendar should render without any navigation UI.
+ */
+declare class CalendarEmptyHeader<D> {
+    private readonly destroyRef;
+    private readonly calendar;
+    private readonly changeDetector;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CalendarEmptyHeader<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CalendarEmptyHeader<any>, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
+export { ButtonSelectorComponent, ButtonToggleComponent, CalendarEmptyHeader, ChipsSelectorComponent, TreePickerComponent };
+export type { ButtonToggleInfo };