@arsedizioni/ars-utils 22.1.5 → 22.5.2

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

@@ -0,0 +1,163 @@
+import * as _angular_core from '@angular/core';
+
+/** Constants identifying each filter group slot and text filter channels. */
+declare const Filters: {
+    FLT_1: number;
+    FLT_2: number;
+    FLT_3: number;
+    FLT_4: number;
+    FLT_5: number;
+    FLT_TEXT: number;
+    FLT_TEXT_1: number;
+    FLT_TEXT_2: number;
+    FLT_TEXT_3: number;
+};
+/** Describes a top-level filter group with optional items or a custom action. */
+interface FilterGroup {
+    group?: number;
+    title?: string;
+    tooltip?: string;
+    items?: FilterItem[];
+    action?: any;
+}
+/** A single selectable entry within a FilterGroup. */
+interface FilterItem {
+    group?: number;
+    title?: string;
+    titleSelected?: string;
+    description?: string;
+    divider?: boolean;
+    value?: any;
+}
+/** Event payload emitted when an active filter changes. */
+declare class CurrentFilterChanged {
+    /** The updated filter state. */
+    filter: CurrentFilter;
+    /** The group slot that changed (see Filters constants). */
+    group: number;
+}
+/** Holds the current state of all active filters for a filter-bar component. */
+declare class CurrentFilter {
+    flt1?: any;
+    flt1Name?: string;
+    flt2?: any;
+    flt2Name?: string;
+    flt3?: any;
+    flt3Name?: string;
+    flt4?: any;
+    flt4Name?: string;
+    flt5?: any;
+    flt5Name?: string;
+    text?: string;
+    text2?: string;
+    text3?: string;
+    /**
+     * Returns true if any filter slot or text field is currently active.
+     * @returns Whether at least one filter is applied.
+     */
+    filtered(): boolean;
+}
+/** Holds the selected value and display state for a single typed filter slot. */
+declare class CurrentFilterItem<T> {
+    items?: any[];
+    value?: T;
+    enabled?: boolean;
+    title?: string;
+    selectedTitle?: string;
+    /**
+     * Reset the filter to its empty state.
+     */
+    clear(): void;
+}
+
+declare class FilterBarComponent {
+    /** Emitted whenever any filter value changes. */
+    readonly changed: _angular_core.OutputEmitterRef<CurrentFilterChanged>;
+    /** The list of filter groups to display. */
+    readonly filters: _angular_core.InputSignal<FilterGroup[]>;
+    readonly canFilterByText: _angular_core.InputSignal<boolean>;
+    readonly canFilterByText2: _angular_core.InputSignal<boolean>;
+    readonly canFilterByText3: _angular_core.InputSignal<boolean>;
+    /** Initial text values for the search inputs — synced into the model signals on change. */
+    readonly initialText: _angular_core.InputSignal<string>;
+    readonly initialText2: _angular_core.InputSignal<string>;
+    readonly initialText3: _angular_core.InputSignal<string>;
+    readonly textName: _angular_core.InputSignal<string>;
+    readonly text2Name: _angular_core.InputSignal<string>;
+    readonly text3Name: _angular_core.InputSignal<string>;
+    readonly textLength: _angular_core.InputSignal<string>;
+    readonly text2Length: _angular_core.InputSignal<string>;
+    readonly text3Length: _angular_core.InputSignal<string>;
+    readonly showTextSearchButton: _angular_core.InputSignal<boolean>;
+    readonly appearance: _angular_core.InputSignal<"fill" | "outline">;
+    /** Two-way bindable text filter values. */
+    protected readonly text: _angular_core.WritableSignal<string>;
+    protected readonly text2: _angular_core.WritableSignal<string>;
+    protected readonly text3: _angular_core.WritableSignal<string>;
+    /** Filter group for slot 1, derived reactively from the `filters` input. */
+    protected readonly flt1: _angular_core.Signal<FilterGroup>;
+    /** Filter group for slot 2, derived reactively from the `filters` input. */
+    protected readonly flt2: _angular_core.Signal<FilterGroup>;
+    /** Filter group for slot 3, derived reactively from the `filters` input. */
+    protected readonly flt3: _angular_core.Signal<FilterGroup>;
+    /** Filter group for slot 4, derived reactively from the `filters` input. */
+    protected readonly flt4: _angular_core.Signal<FilterGroup>;
+    /** Filter group for slot 5, derived reactively from the `filters` input. */
+    protected readonly flt5: _angular_core.Signal<FilterGroup>;
+    /** True when filter slot 1 has an action or item list. */
+    protected readonly canFilterByFlt1: _angular_core.Signal<boolean>;
+    /** True when filter slot 2 has an action or item list. */
+    protected readonly canFilterByFlt2: _angular_core.Signal<boolean>;
+    /** True when filter slot 3 has an action or item list. */
+    protected readonly canFilterByFlt3: _angular_core.Signal<boolean>;
+    /** True when filter slot 4 has an action or item list. */
+    protected readonly canFilterByFlt4: _angular_core.Signal<boolean>;
+    /** True when filter slot 5 has an action or item list. */
+    protected readonly canFilterByFlt5: _angular_core.Signal<boolean>;
+    readonly currentFilter: CurrentFilter;
+    private readonly cdr;
+    constructor();
+    /**
+     * No-op kept for API compatibility.
+     * Filter groups are now computed reactively from the `filters()` input.
+     */
+    initializeFilters(): void;
+    /**
+     * Applies the selected filter item to the current filter state and emits the change.
+     * @param filter - The filter item to apply.
+     */
+    applyFilter(filter: FilterItem): void;
+    /**
+     * Executes the action associated with a filter group, or clears the filter.
+     * @param group - The filter group number.
+     * @param clear - When `true`, clears the filter instead of triggering its action.
+     */
+    applyFilterAction(group: number, clear?: boolean): void;
+    /** Commits the current text inputs to the filter state and emits the change. */
+    applyTextFilter(): void;
+    /**
+     * Clears the active filter for the specified group and emits the change if it was set.
+     * @param group - The filter group number to clear.
+     */
+    clearFilter(group: number): void;
+    /** Resets all active filters and text inputs, then emits the change. */
+    clearAllFilters(): void;
+    /**
+     * Returns `true` when more than one filter type is active, showing the "clear all" button.
+     * @returns True when the clear-all button should be visible.
+     */
+    canClearAllFilters(): boolean;
+    /**
+     * Returns the filter group matching the given id, or `undefined` if not found.
+     * @param id - The group id to look up.
+     * @returns The matching `FilterGroup`, or `undefined`.
+     */
+    private getFilterGroup;
+    /** Synchronises the filter bar display with the values currently stored in `currentFilter`. */
+    syncFilter(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FilterBarComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FilterBarComponent, "filter-bar", never, { "filters": { "alias": "filters"; "required": false; "isSignal": true; }; "canFilterByText": { "alias": "canFilterByText"; "required": false; "isSignal": true; }; "canFilterByText2": { "alias": "canFilterByText2"; "required": false; "isSignal": true; }; "canFilterByText3": { "alias": "canFilterByText3"; "required": false; "isSignal": true; }; "initialText": { "alias": "initialText"; "required": false; "isSignal": true; }; "initialText2": { "alias": "initialText2"; "required": false; "isSignal": true; }; "initialText3": { "alias": "initialText3"; "required": false; "isSignal": true; }; "textName": { "alias": "textName"; "required": false; "isSignal": true; }; "text2Name": { "alias": "text2Name"; "required": false; "isSignal": true; }; "text3Name": { "alias": "text3Name"; "required": false; "isSignal": true; }; "textLength": { "alias": "textLength"; "required": false; "isSignal": true; }; "text2Length": { "alias": "text2Length"; "required": false; "isSignal": true; }; "text3Length": { "alias": "text3Length"; "required": false; "isSignal": true; }; "showTextSearchButton": { "alias": "showTextSearchButton"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; }, { "changed": "changed"; }, never, never, true, never>;
+}
+
+export { CurrentFilter, CurrentFilterChanged, CurrentFilterItem, FilterBarComponent, Filters };
+export type { FilterGroup, FilterItem };

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

@@ -0,0 +1,220 @@
+import { Folder, ApiResult } from '@arsedizioni/ars-utils/core';
+import * as rxjs from 'rxjs';
+import { BehaviorSubject } from 'rxjs';
+import * as _angular_core from '@angular/core';
+import { OnDestroy } from '@angular/core';
+import { BreakpointObserver } from '@angular/cdk/layout';
+import { MatSidenav } from '@angular/material/sidenav';
+import { MatTree } from '@angular/material/tree';
+
+interface ChapterParentInfo {
+    id: string;
+    name: string;
+}
+interface Chapter extends Folder {
+    parents?: ChapterParentInfo[];
+}
+interface ChapterBag {
+    chapter: Chapter;
+    data: string;
+    hits: number;
+}
+interface ChapterTree extends Chapter {
+    subFolders: ChapterTree[];
+    path: string;
+}
+
+interface HelpViewerDialogData {
+    id?: string;
+}
+declare class IndexInfo {
+    id: string;
+    parent?: IndexInfo;
+    name: string;
+    itemsCount?: number;
+    children?: IndexInfo[];
+}
+declare class IndexNode extends IndexInfo {
+    expandable: boolean;
+    level: number;
+    constructor(item: IndexInfo, level: number);
+}
+declare class IndexTreeDataSource implements OnDestroy {
+    dataChange: BehaviorSubject<IndexInfo[]>;
+    get data(): IndexInfo[];
+    ngOnDestroy(): void;
+    /**
+     * Initialises the data source with a flat list of root nodes.
+     * @param data - Array of root `IndexInfo` items to display in the tree.
+     */
+    initialize(data: IndexInfo[]): void;
+    /**
+     * Recursively searches the tree for a node with the given id.
+     * @param node - The node to start from, or `null`/`undefined` to search from the root.
+     * @param id   - The id of the node to find.
+     * @returns The matching `IndexInfo`, or `undefined` if not found.
+     */
+    findNode(node: IndexInfo | undefined | null, id: string): IndexInfo | undefined;
+    /**
+     * Removes the node with the given id from the tree.
+     * @param id - The id of the node to remove.
+     */
+    removeNode(id: string): void;
+    /**
+     * Inserts a new node at the beginning of its parent's children, or at the root.
+     * @param node - The `IndexInfo` node to insert.
+     */
+    insertNode(node: IndexInfo): void;
+    /**
+     * Renames a node in the tree.
+     * @param id   - The id of the node to rename.
+     * @param name - The new display name.
+     */
+    renameNode(id: string, name: string): void;
+    /**
+     * Re-emits the current data to all subscribers, triggering a tree refresh.
+     */
+    update(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<IndexTreeDataSource, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<IndexTreeDataSource>;
+}
+declare class HelpViewerComponent {
+    readonly indexPane: _angular_core.Signal<MatSidenav>;
+    private readonly destroyRef;
+    private readonly dialogRef;
+    protected readonly dialogData: HelpViewerDialogData;
+    private readonly dialogService;
+    private readonly helpService;
+    protected readonly breakpointObserver: BreakpointObserver;
+    protected readonly busy: _angular_core.WritableSignal<boolean>;
+    protected readonly page: _angular_core.WritableSignal<string>;
+    private indexId;
+    private indexPaneClosed;
+    protected indexNode: IndexInfo | undefined;
+    private readonly history;
+    protected readonly canGoBack: _angular_core.Signal<boolean>;
+    private tree;
+    readonly matTree: _angular_core.Signal<MatTree<IndexNode, IndexNode>>;
+    /** Provides the level of a flat node to the tree component. */
+    protected readonly levelAccessor: (node: IndexNode) => number;
+    /** Flat list of all tree nodes used as the tree data source. */
+    protected readonly flatNodes: _angular_core.WritableSignal<IndexNode[]>;
+    private folders?;
+    protected hasChild: (_: number, _node: IndexNode) => boolean;
+    constructor();
+    /**
+  * Handle filter pane visibility
+  */
+    private handleFilterPaneVisibility;
+    /**
+     * Shows or hides the index pane when the user clicks the toggle button.
+     * Also tracks the user's explicit intent so the pane is not auto-reopened.
+     */
+    protected toggleIndexPane(): void;
+    /**
+     * Closes the help viewer dialog.
+     */
+    protected close(): void;
+    /**
+     * Loads the table of contents from the help service and populates the tree.
+     */
+    protected getToc(): void;
+    /**
+     * Intercepts anchor clicks inside the help page and navigates to the referenced chapter.
+     * @param e - The click `MouseEvent` from the page content area.
+     * @returns `false` to prevent default browser navigation.
+     */
+    protected gotoChapter(e: MouseEvent): boolean;
+    /**
+     * Searches the folder list for a node matching the given id.
+     * @param id - The id of the folder to locate.
+     * @returns The matching `IndexInfo`, or `undefined` if not found.
+     */
+    private findFolder;
+    /**
+     * Expands the tree node that corresponds to the currently selected chapter,
+     * and all its ancestor nodes.
+     */
+    private expandCurrentFolder;
+    /**
+     * Recursively flattens a nested IndexInfo tree into a depth-first ordered array of IndexNodes.
+     * @param items - Root-level nodes to flatten.
+     * @param level - Current depth level.
+     */
+    private flattenNodes;
+    /**
+     * Retrieves and displays a help chapter by id.
+     * Optionally scrolls to an anchor or pixel offset after loading.
+     * @param id       - Chapter id, optionally followed by an anchor (`id#anchor`).
+     * @param position - Pixel scroll offset to restore (default `0`, meaning top).
+     */
+    protected getChapter(id: string, position?: number): void;
+    /**
+     * Scrolls the help content to a named anchor or a numeric pixel offset.
+     * @param anchor   - Named anchor (`<a name="…">`) to scroll to, if any.
+     * @param position - Fallback pixel offset (default `0`).
+     */
+    protected gotoPosition(anchor: string | undefined, position?: number): void;
+    /**
+     * Returns the current vertical scroll offset of the help content scroller.
+     * @returns The `scrollTop` value in pixels, or `0` if the element is not found.
+     */
+    protected getPosition(): number;
+    /**
+     * Scrolls the help content scroller to the specified pixel offset.
+     * @param position - The vertical pixel offset to scroll to.
+     */
+    protected setPosition(position: number): void;
+    /**
+     * Navigates back to the previous chapter in the browsing history.
+     */
+    protected back(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HelpViewerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HelpViewerComponent, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
+declare class HelpService {
+    private readonly httpClient;
+    private readonly dialogService;
+    private serviceUri;
+    /**
+     * Initialises the service with the back-end base URI.
+     * Must be called once during application bootstrap before any other method.
+     * @param serviceUri - Base URL of the help service (e.g. `'https://api.example.com'`).
+     */
+    initialize(serviceUri: string): void;
+    /**
+     * Retrieves the HTML content and metadata of a help chapter.
+     * @param id    - The chapter id.
+     * @param query - Optional search query to highlight within the chapter content.
+     * @returns An observable that emits `ApiResult<ChapterBag>`.
+     */
+    getChapter(id: string, query?: string | undefined): rxjs.Observable<ApiResult<ChapterBag>>;
+    /**
+     * Retrieves metadata (title, path, etc.) for a help chapter without its content.
+     * @param id - The chapter id.
+     * @returns An observable that emits `ApiResult<Chapter>`.
+     */
+    getChapterInfo(id: string): rxjs.Observable<ApiResult<Chapter>>;
+    /**
+     * Retrieves a raw repository file by id.
+     * @param id - The repository file id.
+     * @returns An observable that emits `ApiResult<unknown>`.
+     */
+    getRepo(id: string): rxjs.Observable<ApiResult<unknown>>;
+    /**
+     * Retrieves the table of contents as a hierarchical `IndexInfo` tree.
+     * @returns An observable that emits `ApiResult<IndexInfo>`.
+     */
+    getToc(): rxjs.Observable<ApiResult<IndexInfo>>;
+    /**
+     * Opens the help viewer dialog, optionally pre-navigated to a specific chapter.
+     * @param id - The chapter id to open (default: `'1'`, the root chapter).
+     */
+    show(id?: string): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HelpService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<HelpService>;
+}
+
+export { HelpService, HelpViewerComponent, IndexInfo, IndexNode, IndexTreeDataSource };
+export type { Chapter, ChapterBag, ChapterParentInfo, ChapterTree, HelpViewerDialogData };