@myrmidon/cadmus-thesaurus-store 0.0.1

package/types/myrmidon-cadmus-thesaurus-store.d.ts

@@ -0,0 +1,395 @@
+import * as _angular_core from '@angular/core';
+import { OnInit, OnDestroy, Type } from '@angular/core';
+import { FormControl, FormGroup, FormBuilder } from '@angular/forms';
+import { Observable } from 'rxjs';
+import { TreeNodeFilter, PagedTreeNode, PagedTreeStoreService, EditablePagedTreeStoreServiceBase, TreeNode, ChangeOperation, PagedTreeStore, PageChangeRequest } from '@myrmidon/paged-data-browsers';
+import { DataPage } from '@myrmidon/ngx-tools';
+import { ThesaurusEntry } from '@myrmidon/cadmus-core';
+import { CdkDragDrop } from '@angular/cdk/drag-drop';
+import { MatDialogConfig, MatDialogRef } from '@angular/material/dialog';
+
+/**
+ * The filter for thesaurus entry nodes. The only filtered property is
+ * the node's label.
+ */
+interface ThesaurusEntryNodeFilter extends TreeNodeFilter {
+    label?: string;
+}
+/**
+ * The tree node for thesaurus entries in a paging tree node.
+ */
+interface ThesaurusEntryPagedTreeNode extends PagedTreeNode<ThesaurusEntryNodeFilter> {
+    key: string;
+    value: string;
+}
+/**
+ * A label rendering function which removes from a label
+ * all the characters past the last colon, trimming the result.
+ * This is a typical rendering when dealing with hierarchical
+ * thesaurus entries, e.g. "furniture: table: color", where
+ * we can shorten the label to just "color", as "furniture"
+ * and "table" are its ancestors.
+ */
+declare function renderLabelFromLastColon(label: string): string;
+/**
+ * A static paged tree store service for thesaurus entries.
+ * This builds tree nodes from all the thesaurus entries from a specific
+ * thesaurus, assuming that entry IDs are hierarchical and
+ * separated by dots (.).
+ * Nodes are received all at once for a thesaurus, so this is essentially
+ * an adapter to the paged tree store service interface.
+ * The entries are a flat list where hierarchy is implied by the IDs:
+ * for instance, "animal.mammal.dog" is a child of "animal.mammal"
+ * which is a child of "animal". Numeric IDs are added to each node
+ * based on the order of entries to ensure stable IDs.
+ * The label of each node can be rendered as-is from the entry value,
+ * or a custom rendering function can be provided to the constructor.
+ */
+declare class StaticThesaurusPagedTreeStoreService implements PagedTreeStoreService<ThesaurusEntryNodeFilter> {
+    private _renderLabel?;
+    private _nodes;
+    private _built;
+    private readonly _entries;
+    /**
+     * Constructor.
+     * @param entries The thesaurus entries.
+     * @param _renderLabel An optional function to render the label
+     * of each node.
+     */
+    constructor(entries: ThesaurusEntry[], _renderLabel?: ((label: string) => string) | undefined);
+    /**
+     * Ensure that nodes have been built from entries.
+     */
+    private ensureNodes;
+    /**
+     * Get the specified page of nodes.
+     * @param filter The filter.
+     * @param pageNumber The page number.
+     * @param pageSize The page size.
+     * @param hasMockRoot Whether the root node is a mock node. Not used here.
+     */
+    getNodes(filter: ThesaurusEntryNodeFilter, pageNumber: number, pageSize: number, hasMockRoot?: boolean): Observable<DataPage<ThesaurusEntryPagedTreeNode>>;
+}
+
+/**
+ * Editable version of the static thesaurus paged tree store service.
+ * This service allows editing operations on the flat ThesaurusEntry list
+ * while maintaining the tree structure implied by the hierarchical IDs.
+ */
+declare class EditableStaticThesaurusPagedTreeStoreService extends EditablePagedTreeStoreServiceBase<ThesaurusEntryNodeFilter> {
+    private _entries;
+    private _staticService;
+    private _renderLabel?;
+    constructor(entries: ThesaurusEntry[], renderLabel?: (label: string) => string);
+    protected fetchNodes(filter: ThesaurusEntryNodeFilter, pageNumber: number, pageSize: number, hasMockRoot?: boolean): Observable<DataPage<TreeNode>>;
+    protected persistChanges(changes: ChangeOperation[]): Observable<Map<number, number>>;
+    /**
+     * Convert a TreeNode back to a ThesaurusEntry.
+     */
+    private nodeToEntry;
+    /**
+     * Remove an entry and all its descendants from the entries list.
+     */
+    private removeEntryAndDescendants;
+    /**
+     * Get current entries (for demonstration purposes).
+     */
+    getCurrentEntries(): ThesaurusEntry[];
+}
+
+/**
+ * An editable paged tree browser for thesaurus entries. Editing happens in memory
+ * and when complete, the changes can be committed to the underlying data store
+ * via the EditableStaticThesaurusPagedTreeStoreService.
+ */
+declare class EditableThesaurusBrowserComponent implements OnInit, OnDestroy {
+    private _dialog;
+    private _snackBar;
+    private _dialogService;
+    private _sub?;
+    /**
+     * The editable service to use to load the nodes.
+     */
+    readonly service: _angular_core.InputSignal<EditableStaticThesaurusPagedTreeStoreService | undefined>;
+    /**
+     * True to show the tree root nodes filter.
+     */
+    readonly hasRootFilter: _angular_core.InputSignal<boolean>;
+    /**
+     * Emitted when a node is clicked.
+     */
+    readonly nodePick: _angular_core.OutputEmitterRef<ThesaurusEntryPagedTreeNode>;
+    /**
+     * Emitted when the changes state changes.
+     */
+    readonly changesStateChange: _angular_core.OutputEmitterRef<boolean>;
+    /**
+     * The store instance, built from the service.
+     */
+    readonly store: _angular_core.Signal<PagedTreeStore<ThesaurusEntryPagedTreeNode, ThesaurusEntryNodeFilter> | null>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly selectedNode: _angular_core.WritableSignal<ThesaurusEntryPagedTreeNode | null>;
+    debug: FormControl<boolean>;
+    hideLoc: FormControl<boolean>;
+    hideFilter: FormControl<boolean>;
+    filter$: Observable<Readonly<ThesaurusEntryNodeFilter>>;
+    nodes$: Observable<Readonly<ThesaurusEntryPagedTreeNode[]>>;
+    label: FormControl<string | null>;
+    form: FormGroup<{
+        label: FormControl<string | null>;
+    }>;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    reset(): void;
+    onToggleExpanded(node: ThesaurusEntryPagedTreeNode): void;
+    onPageChangeRequest(request: PageChangeRequest): void;
+    onFilterChange(filter: ThesaurusEntryNodeFilter | null | undefined): void;
+    onEditFilterRequest(node: ThesaurusEntryPagedTreeNode): void;
+    expandAll(): void;
+    collapseAll(): void;
+    clear(): void;
+    onNodeClick(node: ThesaurusEntryPagedTreeNode): void;
+    findLabels(): void;
+    removeHilites(): void;
+    private editEntry;
+    addChild(): Promise<void>;
+    addSibling(): Promise<void>;
+    removeNode(): void;
+    editNode(): Promise<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<EditableThesaurusBrowserComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EditableThesaurusBrowserComponent, "cadmus-editable-thesaurus-browser", never, { "service": { "alias": "service"; "required": false; "isSignal": true; }; "hasRootFilter": { "alias": "hasRootFilter"; "required": false; "isSignal": true; }; }, { "nodePick": "nodePick"; "changesStateChange": "changesStateChange"; }, never, never, true, never>;
+}
+
+/**
+ * The prefix added to custom entries' IDs.
+ */
+declare const CUSTOM_ENTRY_PREFIX = "$";
+/**
+ * A picker component for thesaurus entries.
+ * This component allows picking one or more entries from a given thesaurus.
+ * In its collapsed state, it shows the picked entries as chips; when
+ * expanded, it shows the thesaurus tree to pick from. Custom entries
+ * (not in the thesaurus) can be optionally allowed.
+ */
+declare class ThesaurusEntriesPickerComponent {
+    /**
+     * The thesaurus entries to pick from (required).
+     */
+    readonly availableEntries: _angular_core.InputSignal<ThesaurusEntry[]>;
+    /**
+     * The picked entries.
+     */
+    readonly entries: _angular_core.ModelSignal<ThesaurusEntry[]>;
+    /**
+     * True to show the entries with labels shortened according to
+     * their hierarchy.
+     */
+    readonly hierarchicLabels: _angular_core.InputSignal<boolean>;
+    /**
+     * True to automatically sort the picked entries (disables drag-and-drop).
+     * When false, entries can be manually reordered via drag-and-drop.
+     */
+    readonly autoSort: _angular_core.InputSignal<boolean>;
+    /**
+     * True to allow custom values (not in the entries list).
+     */
+    readonly allowCustom: _angular_core.InputSignal<boolean>;
+    /**
+     * The minimum number of entries to pick.
+     */
+    readonly minEntries: _angular_core.InputSignal<number>;
+    /**
+     * The maximum number of entries to pick (0=unlimited).
+     */
+    readonly maxEntries: _angular_core.InputSignal<number>;
+    /**
+     * True when the picker is expanded (showing the entries list).
+     */
+    readonly expanded: _angular_core.ModelSignal<boolean>;
+    /**
+     * The message to show when there are no picked entries.
+     */
+    readonly emptyMessage: _angular_core.InputSignal<string>;
+    /**
+     * The number of remaining entries that can be picked (0=unlimited).
+     * This is displayed only if maxEntries > 1.
+     */
+    readonly remaining: _angular_core.Signal<number>;
+    id: FormControl<string>;
+    value: FormControl<string>;
+    form: FormGroup;
+    constructor(formBuilder: FormBuilder);
+    renderLabel: (label: string) => string;
+    private sortEntries;
+    onEntryChange(entry: ThesaurusEntry): void;
+    addCustomEntry(): void;
+    removeEntry(entry: ThesaurusEntry): void;
+    clear(): void;
+    onDrop(event: CdkDragDrop<ThesaurusEntry[]>): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThesaurusEntriesPickerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ThesaurusEntriesPickerComponent, "cadmus-thesaurus-entries-picker", never, { "availableEntries": { "alias": "availableEntries"; "required": true; "isSignal": true; }; "entries": { "alias": "entries"; "required": false; "isSignal": true; }; "hierarchicLabels": { "alias": "hierarchicLabels"; "required": false; "isSignal": true; }; "autoSort": { "alias": "autoSort"; "required": false; "isSignal": true; }; "allowCustom": { "alias": "allowCustom"; "required": false; "isSignal": true; }; "minEntries": { "alias": "minEntries"; "required": false; "isSignal": true; }; "maxEntries": { "alias": "maxEntries"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; "isSignal": true; }; }, { "entries": "entriesChange"; "expanded": "expandedChange"; }, never, never, true, never>;
+}
+
+/**
+ * An edited thesaurus entry.
+ */
+interface EditedThesEntry {
+    id: string;
+    value: string;
+    /**
+     * True if this entry belongs to a hierarchical thesaurus. When this is true,
+     * and parentId is set, the parentId field will be used as the prefix for the
+     * id field when creating a new entry.
+     */
+    hierarchical?: boolean;
+    /**
+     * The ID of the parent entry, if any.
+     */
+    parentId?: string;
+    /**
+     * If true, the id field is read-only. This is used when editing an existing
+     * entry so you cannot change its ID.
+     */
+    idLocked?: boolean;
+    /**
+     * Function used to check if the given ID exists. This is used when
+     * creating a new entry to ensure it does not duplicate an existing ID.
+     * @param id The ID to check.
+     * @returns True if exists.
+     */
+    idExists?: (id: string) => boolean;
+}
+interface PayloadMatDialogConfig<T> extends MatDialogConfig {
+    payload?: T;
+}
+/**
+ * A dialog component to edit a thesaurus entry.
+ */
+declare class ThesEntryEditorComponent {
+    dialogRef: MatDialogRef<ThesEntryEditorComponent>;
+    data: PayloadMatDialogConfig<EditedThesEntry>;
+    readonly entry: _angular_core.ModelSignal<EditedThesEntry | undefined>;
+    wrapped: boolean;
+    id: FormControl<string>;
+    value: FormControl<string>;
+    form: FormGroup;
+    constructor(dialogRef: MatDialogRef<ThesEntryEditorComponent>, data: PayloadMatDialogConfig<EditedThesEntry>, formBuilder: FormBuilder);
+    cancel(): void;
+    save(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThesEntryEditorComponent, [{ optional: true; }, { optional: true; }, null]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ThesEntryEditorComponent, "cadmus-thesaurus-entry-editor", never, { "entry": { "alias": "entry"; "required": false; "isSignal": true; }; }, { "entry": "entryChange"; }, never, never, true, never>;
+}
+
+/**
+ * A readonly paged tree browser for thesaurus entries. This is a lower-level component
+ * used as an adapter between the generic paged tree browser and the thesaurus entries
+ * data model.
+ */
+declare class ThesaurusBrowserComponent implements OnInit, OnDestroy {
+    private _dialog;
+    private _sub?;
+    /**
+     * The service to use to load the nodes.
+     */
+    readonly service: _angular_core.InputSignal<StaticThesaurusPagedTreeStoreService>;
+    /**
+     * Emitted when a node is clicked.
+     */
+    readonly nodePick: _angular_core.OutputEmitterRef<ThesaurusEntryPagedTreeNode>;
+    /**
+     * The store instance, built from the service.
+     */
+    readonly store: _angular_core.Signal<PagedTreeStore<ThesaurusEntryPagedTreeNode, ThesaurusEntryNodeFilter>>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    debug: FormControl<boolean>;
+    hideLoc: FormControl<boolean>;
+    hideFilter: FormControl<boolean>;
+    filter$: Observable<Readonly<ThesaurusEntryNodeFilter>>;
+    nodes$: Observable<Readonly<ThesaurusEntryPagedTreeNode[]>>;
+    label: FormControl<string | null>;
+    form: FormGroup<{
+        label: FormControl<string | null>;
+    }>;
+    constructor();
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    reset(): void;
+    onToggleExpanded(node: ThesaurusEntryPagedTreeNode): void;
+    onPageChangeRequest(request: PageChangeRequest): void;
+    onFilterChange(filter: ThesaurusEntryNodeFilter | null | undefined): void;
+    onEditFilterRequest(node: ThesaurusEntryPagedTreeNode): void;
+    expandAll(): void;
+    collapseAll(): void;
+    clear(): void;
+    onNodeClick(node: ThesaurusEntryPagedTreeNode): void;
+    findLabels(): void;
+    removeHilites(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThesaurusBrowserComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ThesaurusBrowserComponent, "cadmus-thesaurus-browser", never, { "service": { "alias": "service"; "required": false; "isSignal": true; }; }, { "nodePick": "nodePick"; }, never, never, true, never>;
+}
+
+/**
+ * A filter to be used for thesaurus paged tree browsers.
+ */
+declare class ThesaurusPagedTreeFilterComponent implements OnInit {
+    readonly dialogRef: MatDialogRef<ThesaurusPagedTreeFilterComponent, any> | null;
+    readonly data: any;
+    /**
+     * The filter.
+     */
+    readonly filter: _angular_core.ModelSignal<ThesaurusEntryNodeFilter | null | undefined>;
+    readonly wrapped: _angular_core.WritableSignal<boolean>;
+    label: FormControl<string | null>;
+    form: FormGroup;
+    constructor();
+    ngOnInit(): void;
+    private updateForm;
+    private getFilter;
+    reset(): void;
+    apply(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThesaurusPagedTreeFilterComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ThesaurusPagedTreeFilterComponent, "cadmus-thesaurus-paged-tree-filter", never, { "filter": { "alias": "filter"; "required": false; "isSignal": true; }; }, { "filter": "filterChange"; }, never, never, true, never>;
+}
+
+/**
+ * Thesaurus tree component.
+ * This component displays a set of hierarchical thesaurus entries
+ * in a tree, provided that each entry marks its hierarchy with
+ * dots. For instance, say you have the hierarchy "furniture" -
+ * "type" - "color". You might have an entry whose ID is
+ * "furniture.table.red", with a sibling "furniture.table.green",
+ * and a parent "furniture.table". This parent is there only to
+ * provide a label to the parent node, but only leaf nodes can be
+ * picked by the user. Whenever one is picked, the entryChange
+ * event is emitted.
+ */
+declare class ThesaurusTreeComponent {
+    /**
+     * The thesaurus entries.
+     */
+    readonly entries: _angular_core.InputSignal<ThesaurusEntry[] | undefined>;
+    /**
+     * The optional node label rendering function. Note that even if you
+     * specify a label renderer function, the entryChange event always
+     * emits the original label.
+     */
+    readonly renderLabel: _angular_core.InputSignal<(label: string) => string>;
+    /**
+     * Fired when a thesaurus entry is selected.
+     */
+    readonly entryChange: _angular_core.OutputEmitterRef<ThesaurusEntry>;
+    /**
+     * The tree store service, dependent on the current entries and renderLabel.
+     */
+    readonly service: _angular_core.Signal<StaticThesaurusPagedTreeStoreService>;
+    /**
+     * The filter component class to use.
+     */
+    readonly filterComponent: Type<ThesaurusPagedTreeFilterComponent>;
+    onNodePick(node: ThesaurusEntryPagedTreeNode): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThesaurusTreeComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ThesaurusTreeComponent, "cadmus-thesaurus-tree", never, { "entries": { "alias": "entries"; "required": false; "isSignal": true; }; "renderLabel": { "alias": "renderLabel"; "required": false; "isSignal": true; }; }, { "entryChange": "entryChange"; }, never, never, true, never>;
+}
+
+export { CUSTOM_ENTRY_PREFIX, EditableStaticThesaurusPagedTreeStoreService, EditableThesaurusBrowserComponent, StaticThesaurusPagedTreeStoreService, ThesEntryEditorComponent, ThesaurusBrowserComponent, ThesaurusEntriesPickerComponent, ThesaurusPagedTreeFilterComponent, ThesaurusTreeComponent, renderLabelFromLastColon };
+export type { EditedThesEntry, PayloadMatDialogConfig, ThesaurusEntryNodeFilter, ThesaurusEntryPagedTreeNode };