@myrmidon/paged-data-browsers 5.0.3 → 5.1.1

package/index.d.ts

@@ -57,7 +57,7 @@ interface PagedTreeStoreService<F extends TreeNodeFilter> {
     getNodes(filter: F, pageNumber: number, pageSize: number, hasMockRoot?: boolean): Observable<DataPage<TreeNode>>;
 }
 /**
- * Options for the NodeBrowserStore.
+ * Options for the PagedTreeStore.
  */
 interface PagedTreeStoreOptions {
     /**
@@ -85,11 +85,13 @@ interface PagedTreeStoreOptions {
 }
 /**
  * A store for the node browser component. This store is used to keep a
- * list of nodes, and to load them from the API. It also keeps the root
- * node. Every tree node in the list is extended with page number,
- * page count and total items, plus expansion-related metadata.
+ * list of nodes, and to load them from the injected PagedTreeStoreService<F>.
+ * It also keeps the root node(s) in memory. Every tree node in the list
+ * is extended with page number, page count and total items, plus
+ * expansion-related metadata.
  * The store keeps a flat list of these tree nodes, allowing users to
- * expand and collapse them.
+ * expand and collapse them. Each node has its children paged, and optionally
+ * filtered.
  * F is the type of the filter object, E is the type of the paged tree nodes.
  */
 declare class PagedTreeStore<E extends PagedTreeNode<F>, F extends TreeNodeFilter> {
@@ -122,7 +124,7 @@ declare class PagedTreeStore<E extends PagedTreeNode<F>, F extends TreeNodeFilte
      */
     constructor(_service: PagedTreeStoreService<F>, options?: PagedTreeStoreOptions);
     /**
-     * Gets the global filter, eventually overridden with values
+     * Gets the global filter, optionally overridden with values
      * from the specified node's filter.
      * @param node The optional node.
      * @returns The filter.
@@ -139,7 +141,8 @@ declare class PagedTreeStore<E extends PagedTreeNode<F>, F extends TreeNodeFilte
      */
     getNodes(): Readonly<PagedTreeNode<F>[]>;
     /**
-     * Get the root node of the tree.
+     * Get the root node of the tree. Given that the store keeps a flat
+     * list, this is the first node in the list, if any.
      * @returns The root node of the tree or undefined if empty.
      */
     getRootNode(): PagedTreeNode<F> | undefined;
@@ -202,6 +205,11 @@ declare class PagedTreeStore<E extends PagedTreeNode<F>, F extends TreeNodeFilte
      * @returns Promise.
      */
     expandAll(id?: number): Promise<boolean>;
+    /**
+     * Get the children of the node with the specified ID.
+     * @param id The ID of the node whose children you want to get.
+     * @returns An array of child nodes.
+     */
     getChildren(id: number): E[];
     private removeDescendants;
     /**
@@ -220,7 +228,8 @@ declare class PagedTreeStore<E extends PagedTreeNode<F>, F extends TreeNodeFilte
      */
     collapseAll(id?: number): Promise<boolean>;
     /**
-     * Change the page including the node with the specified ID.
+     * Change the page including the children of the parent node with
+     * the specified ID.
      * @param parentId The ID of the parent node whose children are inside the page
      * you want to change.
      * @param pageNumber The new page number.
@@ -272,9 +281,68 @@ declare class PagedTreeStore<E extends PagedTreeNode<F>, F extends TreeNodeFilte
      * @param nodeId The ID of the node to make visible.
      */
     private ensureNodeVisible;
+    private get _isEditable();
+    private get _editableService();
+    /**
+     * Add a child node to the specified parent.
+     * @param parentId The ID of the parent node.
+     * @param child The child node to add (without ID).
+     * @param first If true, add as first child; otherwise add as last child.
+     * @returns The added node with temporary ID, or undefined if service doesn't support editing.
+     */
+    addChild(parentId: number, child: Omit<TreeNode, 'id' | 'parentId'>, first?: boolean): Promise<TreeNode | undefined>;
+    /**
+     * Add a sibling node next to the anchor node.
+     * @param anchorId The ID of the anchor node.
+     * @param sibling The sibling node to add (without ID).
+     * @param before If true, add before anchor; otherwise add after anchor.
+     * @returns The added node with temporary ID, or undefined if service doesn't support editing.
+     */
+    addSibling(anchorId: number, sibling: Omit<TreeNode, 'id' | 'parentId' | 'y' | 'x'>, before?: boolean): Promise<TreeNode | undefined>;
+    /**
+     * Remove a node from the tree.
+     * We only track the deletion and update visible siblings.
+     * Coordinate adjustments for non-visible nodes are handled by applyLocalChanges.
+     */
+    removeNode(nodeId: number): Promise<boolean>;
+    /**
+     * Replace a node with a new one.
+     * @param oldNodeId The ID of the node to replace.
+     * @param newNode The new node data (without ID).
+     * @param keepDescendants If true, keep descendants; otherwise remove them.
+     * @returns Promise that resolves to the new node, or undefined if service
+     * doesn't support editing.
+     */
+    replaceNode(oldNodeId: number, newNode: Omit<TreeNode, 'id' | 'parentId' | 'y' | 'x'>, keepDescendants?: boolean): Promise<TreeNode | undefined>;
+    /**
+     * Get all descendants of a node.
+     */
+    private getDescendants;
+    /**
+     * Invalidate cache for a specific parent and its ancestors.
+     */
+    private invalidateCache;
+    /**
+     * Save all pending changes if the service supports it.
+     * Preserves the current expansion state after saving.
+     * @returns Promise that resolves when save is complete,
+     * with ID mappings for new nodes.
+     */
+    saveChanges(): Promise<Map<number, number> | undefined>;
+    /**
+     * Check if there are unsaved changes.
+     */
+    hasUnsavedChanges(): boolean;
+    /**
+     * Clear all unsaved changes.
+     */
+    clearUnsavedChanges(): void;
 }
 
 declare class CompactPagerComponent {
+    /**
+     * The current paging information.
+     */
     paging: _angular_core.InputSignal<PagingInfo>;
     /**
      * Emits the new paging information when the user changes the page.
@@ -521,6 +589,152 @@ declare class PagedListStore<F, E> {
     hasCachedPage(pageNumber: number, filter: F): boolean;
 }
 
+/**
+ * Types of operations that can be performed on tree nodes.
+ */
+declare enum ChangeOperationType {
+    ADD = "add",
+    REMOVE = "remove",
+    UPDATE = "update"
+}
+/**
+ * Represents a change operation on a tree node.
+ */
+interface ChangeOperation {
+    type: ChangeOperationType;
+    id: number;
+    node?: TreeNode;
+    originalNode?: TreeNode;
+    parentId?: number;
+    position?: number;
+}
+/**
+ * Interface for a service that can handle both reading and editing tree nodes.
+ * Extends the base PagedTreeStoreService with editing capabilities.
+ */
+interface EditablePagedTreeStoreService<F extends TreeNodeFilter> extends PagedTreeStoreService<F> {
+    /**
+     * Add a new node to the tree.
+     * @param node The node data (without ID).
+     * @param parentId The parent node ID.
+     * @param position Optional position hint.
+     * @returns The added node with temporary ID.
+     */
+    addNode(node: Omit<TreeNode, 'id'>, parentId?: number, position?: number): TreeNode;
+    /**
+     * Update an existing node.
+     * @param id The node ID.
+     * @param updates Partial node updates.
+     */
+    updateNode(id: number, updates: Partial<TreeNode>): void;
+    /**
+     * Remove a node from the tree.
+     * @param id The node ID.
+     */
+    removeNode(id: number): void;
+    /**
+     * Get a node by ID, including local changes.
+     * @param id The node ID.
+     * @returns The node or undefined if not found.
+     */
+    getNode(id: number): TreeNode | undefined;
+    /**
+     * Save all pending changes to the data source.
+     * @returns Observable that completes when save is finished, emitting any ID mappings
+     * for nodes that received new IDs from the backend.
+     */
+    saveChanges(): Observable<Map<number, number>>;
+    /**
+     * Check if there are any unsaved changes.
+     * @returns True if there are pending changes.
+     */
+    hasChanges(): boolean;
+    /**
+     * Clear all pending changes without saving.
+     */
+    clearChanges(): void;
+    /**
+     * Get all pending change operations.
+     * @returns Array of change operations.
+     */
+    getChanges(): ChangeOperation[];
+}
+/**
+ * Base implementation of EditablePagedTreeStoreService that handles change tracking
+ * and provides common editing functionality. Implementers only need to override
+ * the abstract methods for actual data persistence.
+ */
+declare abstract class EditablePagedTreeStoreServiceBase<F extends TreeNodeFilter> implements EditablePagedTreeStoreService<F> {
+    protected _changes: ChangeOperation[];
+    protected _nextTempId: number;
+    protected _nodes: Map<number, TreeNode>;
+    protected _removedNodes: Set<number>;
+    private _hasChanges$;
+    /**
+     * Observable that emits when the change state changes.
+     */
+    hasChanges$: Observable<boolean>;
+    /**
+     * Abstract method to be implemented by subclasses to fetch nodes from the actual data source.
+     */
+    protected abstract fetchNodes(filter: F, pageNumber: number, pageSize: number, hasMockRoot?: boolean): Observable<DataPage<TreeNode>>;
+    /**
+     * Abstract method to be implemented by subclasses to persist changes to the data source.
+     * @param changes The changes to persist.
+     * @returns Observable that emits a map of temporary IDs to permanent IDs.
+     */
+    protected abstract persistChanges(changes: ChangeOperation[]): Observable<Map<number, number>>;
+    /**
+     * Get nodes, including any local changes that haven't been saved yet.
+     */
+    getNodes(filter: F, pageNumber: number, pageSize: number, hasMockRoot?: boolean): Observable<DataPage<TreeNode>>;
+    /**
+     * Apply local changes to a page of nodes.
+     * This includes applying x-coordinate adjustments for siblings of deleted nodes.
+     */
+    private applyLocalChanges;
+    /**
+     * Check if a node matches the given filter.
+     */
+    private matchesFilter;
+    /**
+     * Add a new node to the tree.
+     */
+    addNode(node: Omit<TreeNode, 'id'>, parentId?: number, position?: number): TreeNode;
+    /**
+     * Remove a node from the tree.
+     */
+    removeNode(id: number): void;
+    /**
+     * Update an existing node.
+     * If the node is in cache, update it with the partial updates.
+     * If not in cache and updates is a complete TreeNode, add it to cache.
+     * Otherwise skip (normal for pagination).
+     */
+    updateNode(id: number, updates: Partial<TreeNode>): void;
+    /**
+     * Save all pending changes.
+     */
+    saveChanges(): Observable<Map<number, number>>;
+    /**
+     * Check if there are unsaved changes.
+     */
+    hasChanges(): boolean;
+    /**
+     * Clear all pending changes.
+     */
+    clearChanges(): void;
+    /**
+     * Get all pending changes.
+     */
+    getChanges(): ChangeOperation[];
+    /**
+     * Get a node by ID, including local changes.
+     */
+    getNode(id: number): TreeNode | undefined;
+    protected updateHasChanges(): void;
+}
+
 /**
  * A Least Recently Used cache that can be used to store any type of object.
  * The cache works in two modes: considering the size of the objects or not.
@@ -581,5 +795,5 @@ declare class LRUCache<T> {
     static calculateObjectSize(obj: any): number;
 }
 
-export { BrowserTreeNodeComponent, CompactPagerComponent, DEFAULT_PAGED_LIST_STORE_OPTIONS, LRUCache, PagedListStore, PagedTreeStore, RangeViewComponent };
-export type { PageChangeRequest, PagedListStoreOptions, PagedListStoreService, PagedTreeNode, PagedTreeStoreOptions, PagedTreeStoreService, PagingInfo, TreeNode, TreeNodeFilter };
+export { BrowserTreeNodeComponent, ChangeOperationType, CompactPagerComponent, DEFAULT_PAGED_LIST_STORE_OPTIONS, EditablePagedTreeStoreServiceBase, LRUCache, PagedListStore, PagedTreeStore, RangeViewComponent };
+export type { ChangeOperation, EditablePagedTreeStoreService, PageChangeRequest, PagedListStoreOptions, PagedListStoreService, PagedTreeNode, PagedTreeStoreOptions, PagedTreeStoreService, PagingInfo, TreeNode, TreeNodeFilter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myrmidon/paged-data-browsers",
-  "version": "5.0.3",
+  "version": "5.1.1",
   "description": "Generic simple paged data browsers.",
   "keywords": [
     "data browsers"