@myrmidon/paged-data-browsers 5.0.2 → 5.1.1

package/README.md

@@ -1,5 +1,17 @@
 # Paged Data Browsers
 
+- [Paged Data Browsers](#paged-data-browsers)
+  - [Paged List](#paged-list)
+  - [Paged Tree](#paged-tree)
+    - [Nodes](#nodes)
+      - [TreeNode](#treenode)
+      - [PagedTreeNode](#pagedtreenode)
+    - [Services](#services)
+      - [PagedTreeStoreService](#pagedtreestoreservice)
+      - [EditablePagedTreeStoreService](#editablepagedtreestoreservice)
+      - [PagedTreeStore](#pagedtreestore)
+    - [Node Component](#node-component)
+
 This library provides simple components to display filtered and paged data from some service.
 
 There are currently two components, one for displaying a flat list of data, and another to display hierarchically structured data, combining a tree view with paging.
@@ -21,47 +33,122 @@ So you need:
 
 ## Paged Tree
 
+The paged tree is a tree where each node can page and filter its direct children.
+
 ### Nodes
 
+#### TreeNode
+
 A paged tree is based on **nodes** of type `TreeNode` or its derived types. This basic tree node contains:
 
 - `id`: a unique numeric ID.
 - `parentId`: the ID of the parent, or undefined if it's a root-level node.
-- `y`: Y is the node depth, starting from 1. As we often need a single root node (for paging its children), unless we have a small number of root nodes, when your data source does not return a single root node you have the option of using a mock root. In this case, the mock root Y level will be 0 and all the other nodes will descend from it. Anyway you can also have many root level nodes, whose parent ID is undefined; but in this case all these nodes will appear at once without any paging, because paging is governed by the parent node.
+- `y`: Y is the node depth, starting from 1. As we often need a single root node (for paging its children), unless we have a small number of root nodes, when your data source does not return a single root node you have the option of using a mock root. In this case, the mock root's Y level will be 0 and all the other nodes will descend from it. Anyway you can also have many root level nodes, whose parent ID is undefined; but in this case all these nodes will appear at once without any paging, because paging is governed by the parent node.
 - `x`: X is the ordinal number of the node among its siblings. The first child of a given node has X=1, the second has X=2, and so forth.
 - `label`: a human-friendly label for the node.
 - `tag`: a tag string for virtually categorizing or grouping the node in some way.
-- `hasChildren`: true if the node has children, false if it has no children; undefined if this has not yet been determined.
+- `hasChildren`: true if the node has children, false if it has no children; undefined if this has not yet been determined. This is initially undefined, until the service fetching data has been used to retrieve the children of a node. After that, if no nodes were returned, `hasChildren` is `false` and this will prevent further roundtrips to the server.
+
+#### PagedTreeNode
 
-A **paged tree node** type derives from `TreeNode` adding two essential components:
+A **paged tree node** type (`PagedTreeNode<F>`) derives from this basic `TreeNode`, adding two essential components for filtering and paging its children:
+
+- a _filter_ for its children. Node filters derive from `TreeNodeFilter`, which just refers to `TreeNode`'s properties: so, the base filter just has a tag and a parent ID. Typically you derive your own filter from this type.
+
+>⚠️ It is very important to take into account the parent ID property of the base filter when implementing the paging service.
 
-- a _filter_ for its children. The basic `TreeNodeFilter` just refers to `TreeNode` properties, so it just has tag and parent ID. You can derive your own filter from this type.
 - _paging information_ for its children. This is of type `PagingInfo` which has page number, page items count, and total items count.
 
-The base type for a paged tree node is thus `PagedTreeNode<F>`, where `F` is the type of the filter used for filtering nodes; this adds:
+The base type for a paged tree node is thus `PagedTreeNode<F>`, where `F` is the type of the filter used for filtering nodes; this adds properties:
 
 - `paging`: paging information. This is required.
-- `expanded`: for expanded/collapsed state.
-- `filter`: filter object.
+- `expanded`: for expanded/collapsed state. Initially this is `undefined`.
+- `filter`: filter object. If not set, there will be no filtering and thus all the children will be included.
 
 ### Services
 
-Your data must be provided by a service implementing interface `PagedTreeStoreService<F>`, where `F` is the tree node filter type. This requires you to implement a single function, `getNodes`, which returns a specific page of nodes, applying the specified filter.
+#### PagedTreeStoreService
 
->This service deals with `TreeNode`'s (or their derivations), returning a specific page of them. It is the store which extends these nodes with paging and filtering data using the `PagedTreeNode` type. Note that if you want a single root mock node, your implementation of this service must provide it (with Y=0).
+Typically, data for the tree is dynamically loaded. It can also be loaded all at once; in both cases, data will always be provided by a service implementing the same interface. This is the paged tree store's service, which fetches data from your data source on behalf of the paged tree store.
 
-The tree logic is then implemented by the `PagedTreeStore<E,F>`, where `E` is the element (node) type (a `PagedTreeNode<F>` or any derived type), and `F` is the filter type (a `TreeNodeFilter` or any derived type).
+So, your data must be provided by this service which implements interface `PagedTreeStoreService<F>`, where `F` is the tree node filter type. The interface requires you to implement a single function, `getNodes`, which returns a specific page of nodes, applying the specified filter:
+
+```ts
+getNodes(
+    filter: F,
+    pageNumber: number,
+    pageSize: number,
+    hasMockRoot?: boolean
+  ): Observable<DataPage<TreeNode>>;
+```
+
+>This service deals with `TreeNode`'s (or their derivations), returning a specific page of them. It is the service which is directly in contact with your data source, and its only purpose is to return a page of nodes. It is the store which extends these nodes with paging and filtering data using the `PagedTreeNode` type. Note that if you want a single root mock node, your implementation of this service must provide it (with Y=0).
+
+#### EditablePagedTreeStoreService
+
+For editing scenarios, you can use `EditablePagedTreeStoreService<F>` which extends the base service interface with editing capabilities. This service maintains changes in memory until they are explicitly saved, allowing for:
+
+- **Change tracking**: All modifications (add, remove, update) are tracked internally
+- **Optimistic updates**: The service's `getNodes` method returns data including unsaved changes
+- **Batch saving**: All changes can be committed to the data source at once
+- **ID mapping**: Temporary IDs for new nodes are mapped to permanent IDs after saving
+
+The interface adds these methods:
+
+```ts
+// Save all pending changes to the data source
+saveChanges(): Observable<Map<number, number>>;
+
+// Check if there are any unsaved changes
+hasChanges(): boolean;
+
+// Clear all pending changes without saving
+clearChanges(): void;
+
+// Get all pending change operations
+getChanges(): ChangeOperation[];
+```
+
+A base implementation `EditablePagedTreeStoreServiceBase<F>` is provided that handles all the change tracking logic. You only need to implement:
+
+- `fetchNodes()`: Get nodes from your actual data source
+- `persistChanges()`: Save changes to your data source
+
+This design ensures full backward compatibility - existing readonly implementations continue to work unchanged.
+
+#### PagedTreeStore
+
+The tree logic is implemented by the `PagedTreeStore<E,F>`, where:
+
+- `E` is the element (node) type (a `PagedTreeNode<F>` or any derived type);
+- `F` is the filter type (a `TreeNodeFilter` or any derived type).
 
 The store is used to load and manage a flat list of nodes. Every tree node in the list is extended with page number, page count and total items, plus expansion-related metadata. Users can expand and collapse nodes, browse through pages of children, and filter them.
 
+When using an `EditablePagedTreeStoreService`, the store also supports editing operations:
+
+- `addChild(parentId, child, first)`: Add a child node to the specified parent
+- `addSibling(anchorId, sibling, before)`: Add a sibling node relative to an anchor node  
+- `removeNode(nodeId)`: Remove a node and optionally its descendants
+- `replaceNode(oldNodeId, newNode, keepDescendants)`: Replace a node with new data
+- `saveChanges()`: Persist all changes to the data source
+- `hasUnsavedChanges()`: Check if there are pending changes
+- `clearUnsavedChanges()`: Discard all pending changes
+
+All editing operations automatically handle:
+- Position recalculation (x coordinates)
+- Parent `hasChildren` status updates
+- Cache invalidation
+- UI updates for expanded nodes
+
 The essential store **data** are:
 
-- the flat _list of paged nodes_ (exposed in `nodes$`). This is populated by using an instance of `PagedTreeStoreService<F>`, injected in the store constructor together with its options (of type `PagedTreeStoreOptions`). Among other things, the options specify whether there must be a single mock root node, and the default page size. Once retrieved, pages can be fetched from an internal LRU cache (which is anyway cleared when calling `reset`).
+- the flat _list of paged nodes_ (exposed in `nodes$`). This flat list is populated by using an instance of the paged tree store's service (`PagedTreeStoreService<F>`), injected in the store constructor together with its options (of type `PagedTreeStoreOptions`). Among other things, the options specify whether there must be a single mock root node, and the default page size. Once retrieved, pages can be fetched from an internal LRU cache (which is cleared when calling `reset`).
 - a list of tree _tags_ (exposed in `tags$`).
 - a _global filter_ (exposed in `filter$`). This gets combined with (overridden by) node-specific filters, when specified. You can set it with `setFilter`. To set the filter for the children of a specific node use `setNodeFilter`.
 - the _page size_ (`pageSize`), a get/set property, initially set by the options injected in the store constructor. Setting this property resets the store (like calling `reset`).
 
-To initialize the store, you call `reset`, which loads root nodes (via its service's `getRootNodes`) and their direct children. You then expand or collapse nodes, change page, and set the global or node filters as desired.
+To initialize the store, you call `reset`, which loads root nodes (via its service's `getNodes`) and their direct children. Users then expand or collapse nodes, change page, and set the global or node filters as desired.
 
 The main **methods** are:
 
@@ -69,7 +156,7 @@ The main **methods** are:
 - `clear()`: clear the whole store, emptying the cache and removing all the nodes.
 - `clearCache()`: clears the pages cache.
 - `hasCachedPage(pageNumber, filter)`: checks whether the specified page is cached.
-- `isEmtpy()`: true if the list is empty.
+- `isEmpty()`: true if the list is empty.
 - `getNodes()`: gets all the nodes in the list.
 - `getRootNode()`: returns the root node, i.e. the first node in the list (unless this is empty).
 - `getChildren(id)`: gets the children of the specified node.
@@ -83,7 +170,7 @@ The main **methods** are:
 - `setFilter(filter)`: sets the global filter, resetting the store.
 - `setNodeFilter(id, filter)`: sets the node-filter for the specified node, resetting its children page number to 1.
 
-The store is a plain class. If you want to persist it in the app, you can wrap it in a service and inject the service into your component. If you don't need this, just implement your data service to provide nodes via `getNodes`. Otherwise, you can wrap the store like e.g. here using a singleton for a single page of nodes in the demo app:
+The store is a plain TypeScript class. If you want to **persist** it in the app, you can wrap it in a service and inject the service into your component. If you don't need this, just implement your data service to provide nodes via `getNodes`. Otherwise, you can wrap the store like e.g. here using a singleton for a single page of nodes in the demo app:
 
 ```ts
 @Injectable({