@myrmidon/paged-data-browsers 5.2.1 → 5.2.2

package/README.md

@@ -1,59 +1,149 @@
 # 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)
-  - [History](#history)
-    - [5.2.0](#520)
-    - [5.1.3](#513)
-    - [5.1.2](#512)
-    - [5.1.1](#511)
-    - [5.1.0](#510)
-    - [5.0.2](#502)
-    - [5.0.1](#501)
-    - [5.0.0](#500)
-    - [4.0.2](#402)
-    - [4.0.1](#401)
-    - [4.0.0](#400)
-    - [3.0.0](#300)
-    - [2.0.5](#205)
-    - [2.0.4](#204)
-    - [2.0.3](#203)
-    - [2.0.2](#202)
-    - [2.0.1](#201)
-    - [2.0.0](#200)
-    - [1.1.0](#110)
-
-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.
-
-Also, there is a LRU cache service and a compact pager used in the paged tree component.
+- 📦 `@myrmidon/paged-data-browsers`
+
+This library provides components to display filtered and paged data from some service:
+
+- a flat paged list of data.
+- a paged tree, to display hierarchically structured data, combining a tree view with paging.
+- a compact pager component for the tree.
+- a LRU cache service.
+
+---
 
 ## Paged List
 
-Paged list support is provided by a single utility class, [PagedListStore](src/lib/services/paged-list.store.ts). This templated class provides logic for:
+Paged list is provided by a single utility class, [PagedListStore](src/lib/services/paged-list.store.ts). This templated class provides:
 
 - a filter object of type `F`;
 - a list element object of type `E`.
 
-So you need:
+You provide:
 
-- a filter class to represent your elements filter (for `F`).
+- a filter class to represent the filter for list elements (for `F`).
 - an element item class (for `E`).
-- a service to fetch data, implementing interface [PagedListStoreService<F, E>](src/lib/services/paged-list.store.ts). In this shell, a [local service](../../../src/app/services/mock-paged-list-store.service.ts) provides mock data.
+- a service to fetch data, implementing interface [PagedListStoreService<F, E>](src/lib/services/paged-list.store.ts).
+
+>In this workspace demo app, a [local service](../../../src/app/services/mock-paged-list-store.service.ts) provides mock data.
+
+### Using Paged List
+
+▶️ (1) create a **filter dumb component** which just gets the filter and emits it when changes.
+
+- [paged list filter code example](../../../src/app/components/paged-list-filter/paged-list-filter.component.ts)
+- [paged list filter template example](../../../src/app/components/paged-list-filter/paged-list-filter.component.html)
+- [paged list filter styles example](../../../src/app/components/paged-list-filter/paged-list-filter.component.css)
+
+▶️ (2) to persist list state, either **create a service wrapper** or an implementation of `PagedListStoreService<F,E>` for the store. This way the store will be used as a singleton with your data service.
+
+- If you only need a service wrapper with no additional logic, just wrap it and expose the store as a property (see [paged list browser service example](src/app/services/paged-list-browser.service.ts)):
+
+```ts
+/**
+ * Wrapper for a PagedListStore<F, E> instance.
+ * This singleton service ensures that the corresponding component
+ * preserves its state when navigating away and back.
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class PagedListBrowserService {
+  public readonly store: PagedListStore<__F__Filter, __E__>;
+
+  constructor(service: __S__Service) {
+    this.store = new PagedListStore<__F__Filter, __E__>(service);
+  }
+}
+```
+
+- If instead you have additional data and logic in your component, make your service implement `PagedListStoreService<F,E>` and expose wrapped functionality from the store; in addition, it will also include other data (e.g. lookup data) and their services, to fully back the browser component UI.
+
+If you implement this interface, you must provide a `loadPage` method which will be used by the list browser infrastructure to load the requested page; while other methods will just wrap essential functions of the store.
+
+For instance, here is how you can implement `loadPage` and wrap store functionality in a `DocumentRepository implements PagedListStoreService<DocumentFilter, Document>` singleton service:
+
+```ts
+// implement interface
+private _store: PagedListStore<DocumentFilter, Document>;
+
+constructor(private _docService: DocumentService) {
+  this._store = new PagedListStore<DocumentFilter, Document>(this);
+  this._loading$ = new BehaviorSubject<boolean>(false);
+  // ... etc.
+  this._store.reset();
+}
+
+public loadPage(
+  pageNumber: number,
+  pageSize: number,
+  filter: DocumentFilter
+): Observable<DataPage<Document>> {
+  this._loading$.next(true);
+  return this._docService.getDocuments(filter, pageNumber, pageSize).pipe(
+    tap({
+      next: () => this._loading$.next(false),
+      error: () => this._loading$.next(false),
+    })
+  );
+}
+
+// wrap store functions
+public async reset(): Promise<void> {
+  this._loading$.next(true);
+  try {
+    await this._store.reset();
+  } catch (error) {
+    throw error;
+  } finally {
+    this._loading$.next(false);
+  }
+}
+
+public async setFilter(filter: DocumentFilter): Promise<void> {
+  this._loading$.next(true);
+  try {
+    await this._store.setFilter(filter);
+  } catch (error) {
+    throw error;
+  } finally {
+    this._loading$.next(false);
+  }
+}
+
+public getFilter(): DocumentFilter {
+  return this._store.getFilter();
+}
+
+public async setPage(pageNumber: number, pageSize: number): Promise<void> {
+  this._loading$.next(true);
+  try {
+    await this._store.setPage(pageNumber, pageSize);
+  } catch (error) {
+    throw error;
+  } finally {
+    this._loading$.next(false);
+  }
+}
+```
+
+▶️ (3) **create your browser component** which gets the service at (2) injected, and exposes from its wrapped store the filter and page observables, handling filter and page changes:
+
+- [paged list browser code example](src/app/components/paged-list-browser/paged-list-browser.component.ts)
+- [paged list browser template example](src/app/components/paged-list-browser/paged-list-browser.component.html)
+- [paged list browser styles example](src/app/components/paged-list-browser/paged-list-browser.component.css)
+
+---
 
 ## Paged Tree
 
-The paged tree is a tree where each node can page and filter its direct children.
+A paged tree is a tree with flat nodes (of type `PagedTreeNode<F>`), where nodes are dynamically loaded and paged. The tree has two **filters** (equal to or derived from `TreeNodeFilter`):
+
+- a _global_ filter, applied to all the pages it handles;
+- _per-node_ filters, which apply to the node's children to determine their page.
+
+When expanding a node, a page of children nodes is fetched from a configured service. Each parent node maintains paging information about the current page of its children, orchestrating its filter and page number.
+
+![overview](./img/paged-tree.png)
 
 ### Nodes
 
@@ -71,27 +161,19 @@ A paged tree is based on **nodes** of type `TreeNode` or its derived types. This
 
 #### PagedTreeNode
 
-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 **paged tree node** (`PagedTreeNode<F>` where `F` is the type of the nodes filter) derives from `TreeNode` adding:
 
-- _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 properties:
-
-- `paging`: paging information. This is required.
+- `paging`: paging information for children nodes (required). This is of type `PagingInfo` which has page number, page items count, and total items count.
 - `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.
+- `filter`: filter for children nodes. If not set, all children are included.
+
+>Node filters derive from `TreeNodeFilter`, which refers to `TreeNode`'s properties: so, the base filter has only a tag and a parent ID. Typically you derive your own filter from this type. In your filter logic it is very important to take into account the parent ID property of the base filter!
 
 ### Services
 
 #### PagedTreeStoreService
 
-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.
-
-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:
+Data for the tree is dynamically loaded or loaded all at once by a service implementing `PagedTreeStoreService<F>`, where `F` is the tree node filter type. This interface requires to implement `getNodes` to fetch nodes with filtering and paging:
 
 ```ts
 getNodes(
@@ -102,7 +184,14 @@ getNodes(
   ): 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).
+>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. The store extends these nodes with paging and filtering using `PagedTreeNode`. If you want a single root mock node, your implementation of this service must provide it (with Y=0).
+
+The `getNodes` method can also get a mock-root parameter referring to two data models:
+
+- when you have a data model with a single root node for the whole tree, this parameter is `false`, because the root node comes from your data. It will have Y=1 and X=1, and contain all the tree nodes as its descendants.
+- when instead your data lacks a single root node, and at its root level has many root nodes, this parameter can be either `true` or `false`. When `false`, multiple root level nodes are allowed but they are all loaded at once. So this is useful only when your root nodes number is limited. When instead the parameter is `true`, it is up to your service implementation to provide a mock root node for the multiple root nodes, which become its children. This mock root will have Y=0.
+
+>As a sample, compare the [mock service](./src/app/services/paged-tree-browser.service.ts) used in this shell. Its `getData` method gets this parameter and when true it creates a root node with Y=0, X=1, and id=1; in this case, the root nodes are made children of it. Otherwise, it just goes with multiple root nodes. In the example shell, you are allowed to toggle this parameter to see these two models in action. In a real-world application instead you will usually stick to a single model.
 
 #### EditablePagedTreeStoreService
 
@@ -134,16 +223,14 @@ A base implementation `EditablePagedTreeStoreServiceBase<F>` is provided that ha
 - `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:
+The tree logic is implemented by the top-level class `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.
+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-state 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:
 
@@ -165,7 +252,6 @@ All editing operations automatically handle:
 The essential store **data** are:
 
 - 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`).
 
@@ -185,11 +271,15 @@ The main **methods** are:
 - `expand(id)`: expand the specified node (if it has children and is collapsed).
 - `expandAll(id)`: expand all the descendants of the specified node.
 - `collapse(id)`: collapse the specified node if expanded.
-- `collapseAll()`: collpase all the descendants of the specified node.
+- `collapseAll(id?)`: collapse all the descendants of the specified node. When called without an argument, all expanded root-level nodes are collapsed.
 
 - `changePage(parentId, pageNumber)`: change the page of children nodes of the specified parent node.
 - `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.
+- `findLabels(searchText)`: search all nodes (loading lazily as needed) for labels containing the search text, highlight matched nodes, and expand their ancestors so they become visible.
+- `removeHilites()`: remove all search highlights from every node.
+- `ensureNodeVisible(id, expanded?, refresh?)`: find a node by ID, expand all its ancestors, navigate to the page containing it, optionally set its expanded state, and highlight it. Useful for programmatic navigation to a specific node.
+- `getAnchorForDeletedNode(id)`: returns the ID of the node that should be selected after deleting the given node (next sibling → previous sibling → parent → null). Useful for keeping focus meaningful after a deletion.
 
 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:
 
@@ -259,113 +349,160 @@ You should provide your components for:
   - a filters component for global filters. This dummy component gets a `filter$` and emits `filterChange`.
   - a tree view.
 
-## History
-
-### 5.2.0
-
-- 2026-03-02: ⚠️ migrated to `OnPush`.
+### Using Tree
 
-### 5.1.3
+▶️ (1) to define your node, **create a node class** extending `PagedTreeNode<F>`. This parent (derived from `TreeNode`) already has properties for IDs, label, filtering and paging. In your derived class you should add data linked to the node. For example, here data is just the `count` property:
 
-- 2026-01-13: adding ensure node visible functionality to the paged tree store so that we can preserve focus on node when updating it in backend data.
-- 2026-01-12:
-  - updated Angular and packages.
-  - refactored thesauri components moving them from demo app to a new `@myrmidon/cadmus-thesaurus-store` library. Once the components here reach production stage, the library will import `ThesaurusEntry` from the Cadmus core package and be packaged and exported to become part of the Cadmus system.
-  - fixes to editable thesaurus component.
-- 2026-01-07: updated Angular and packages.
-
-### 5.1.2
-
-- 2025-11-22:
-  - ⚠️ upgraded to Angular 21.
-  - ⚠️ migrated to `pnpm`.
-
-### 5.1.1
-
-- 2025-10-05:
-  - fixes in editable tree store.
-  - minor improvements in paged tree store.
-  - better documentation.
-
-### 5.1.0
-
-- 2025-09-23:
-  - added thesaurus tree demo page in app.
-  - added `findLabels` and `removeHilites` to tree store.
-  - updated package and tsconfig for library (version 5.0.3).
-
-### 5.0.2
-
-- 2025-06-15:
-  - fix to tree expand all.
-  - updated Angular and packages.
-
-### 5.0.1
-
-- 2025-06-10: removed dirty check in reset. When reset is requested, just do it.
-
-### 5.0.0
-
-- 2025-05-29: ⚠️ upgraded to Angular 20.
-- 2025-05-25: updated Angular and packages.
-
-### 4.0.2
-
-- 2025-01-01: updated packages.
-
-### 4.0.1
-
-- 2024-12-04: added CSS variables to browser tree node.
-
-### 4.0.0
+```ts
+export interface MockTreeNode extends PagedTreeNode<TreeNodeFilter> {
+  count: number;
+}
+```
 
-- 2024-12-02: ⚠️ refactored code:
-  - replaced dependencies with new standalone `ngx-mat-...` libraries.
-  - upgraded to standalone.
-  - upgraded to functional injection.
-  - upgraded to use signal-based properties and events.
-  - fixes to tree store for collapse.
+▶️ (2) to define your filter, **create a filter class** for this node, extending `TreeNodeFilter` (this parent just provides `tags` and `parentId`). For example:
 
-### 3.0.0
+```ts
+export interface MockTreeFilter extends TreeNodeFilter {
+  label?: string;
+  minCount?: number;
+  maxCount?: number;
+}
+```
 
-- 2024-11-22: ⚠️ upgraded to Angular 19.
+▶️ (3) **create a service** implementing `PagedTreeStoreService<F>` to fetch a page of nodes from some data source (using filter of type `F`). For example:
 
-### 2.0.5
+```ts
+@Injectable({
+  providedIn: 'root',
+})
+export class MockPagedTreeStoreService
+  implements PagedTreeStoreService<MockTreeFilter>
+{
+  /**
+   * 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.
+   */
+  public getNodes(
+    filter: MockTreeFilter,
+    pageNumber: number,
+    pageSize: number,
+    hasMockRoot?: boolean
+  ): Observable<DataPage<MockTreeNode>> {
+    // TODO fetch nodes using filter and pageNumber, pageSize
+    // and return the requested page of nodes with items,
+    // pageNumber, pageSize, pageCount, total.
+  }
+}
+```
 
-- 2024-10-24: added `hideLoc` to tree node component.
+>⚠️ Always remember to **filter by parent ID** in your implementation of `getNodes`! For instance, here is a filter by label, which first filters by parent ID:
 
-### 2.0.4
+```ts
+  /**
+   * 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.
+   */
+  public getNodes(
+    filter: ThesEntryNodeFilter,
+    pageNumber: number,
+    pageSize: number,
+    hasMockRoot?: boolean
+  ): Observable<DataPage<ThesEntryPagedTreeNode>> {
+    this.ensureNodes();
+
+    // apply filtering
+    let nodes = this._nodes.filter((n) => {
+      if (filter.parentId !== undefined && filter.parentId !== null) {
+        if (n.parentId !== filter.parentId) {
+          return false;
+        }
+      } else {
+        if (n.parentId) {
+          return false;
+        }
+      }
+
+      if (filter.label) {
+        const filterValue = filter.label.toLowerCase();
+        if (!n.label.toLowerCase().includes(filterValue)) {
+          return false;
+        }
+      }
+      return true;
+    });
+
+    // apply paging
+    const startIndex = (pageNumber - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    const pagedNodes = nodes.slice(startIndex, endIndex);
+
+    // page and return
+    const paged = nodes.slice(
+      (pageNumber - 1) * pageSize,
+      pageNumber * pageSize
+    );
+    return of({
+      items: paged,
+      pageNumber: pageNumber,
+      pageSize: pageSize,
+      pageCount: Math.ceil(nodes.length / pageSize),
+      total: nodes.length,
+    });
+  }
+```
 
-- 2024-10-23:
-  - updated Angular.
-  - updated package peer dependencies.
-  - added i18n.
-  - added `hideFilter` to paged tree browser.
+▶️ (4) filter UI: create a **paged tree filter dumb component** which just gets the filter and emits it when changes. This component will be used both as the global filter editor and as the per-node filters editor. In the latter case, it will appear as a popup. So you need to inject a `MatDialogRef` and its data in the constructor, and call dialog ref's `close` function when changing the filter. Also, note that in the HTML template we add margin when the filter component is wrapped into a dialog.
 
-### 2.0.3
+- [paged tree filter example code](src/app/components/paged-tree-filter/paged-tree-filter.component.ts)
+- [paged tree filter example template](src/app/components/paged-tree-filter/paged-tree-filter.component.html)
+- [paged tree filter example styles](src/app/components/paged-tree-filter/paged-tree-filter.component.css)
 
-- 2024-10-16: added `clear` method to stores.
+▶️ (5) (optional) singleton service wrapper: if you want to persist the tree state, **create a service wrapper** for the store which gets instantiated with your data fetch service (implementing interface `PagedTreeStoreService<F>`), like in this example. This wrapper will also provide app-specific options for configuring the store, including the `hasMockRoot` parameter, should it be required.
 
-### 2.0.2
+```ts
+// paged-tree-browser.service.ts
+import { Injectable } from '@angular/core';
 
-- 2024-10-02: fix to paged tree store page change when any nodes in old page are expanded.
+@Injectable({
+  providedIn: 'root',
+})
+export class PagedTreeBrowserService {
+  public readonly store: PagedTreeStore<__N__Node, __F__Filter>;
 
-### 2.0.1
+  constructor(service: __S__Service) {
+    this.store = new PagedTreeStore<__N__Node, __F__Filter>(service);
+  }
+}
+```
 
-- 2024-10-02:
-  - updated Angular and packages.
-  - added get root node method to tree store.
-  - more comments.
+If instead you are going to directly use the service, inject the service in a new store, in your browser component (see nr.6) e.g.:
 
-### 2.0.0
+```ts
+  /**
+   * The store instance, built from the service.
+   */
+  public readonly store = computed(() => {
+    const service = this.service();
+    const store = new PagedTreeStore<
+      ThesEntryPagedTreeNode,
+      ThesEntryNodeFilter
+    >(service);
+    this.nodes$ = store.nodes$;
+    this.filter$ = store.filter$;
+    return store;
+  });
+```
 
-- 2024-08-04: ⚠️ breaking changes to tree browser: refactored to remove tag-based multiple trees.
-- 2024-08-02:
-  - upgraded Angular and packages.
-  - replaced `color` with `class`.
-  - refactored styles for new Material.
+▶️ (6) tree-view browser: **create a tree browser component** which gets the wrapper service at (5) injected, and exposes from its wrapped store the filter and page observables, handling filter and page changes:
 
-### 1.1.0
+- [paged tree browser code example](src/app/components/paged-tree-browser/paged-tree-browser.component.ts)
+- [paged tree browser template example](src/app/components/paged-tree-browser/paged-tree-browser.component.html)
+- [paged tree browser styles example](src/app/components/paged-tree-browser/paged-tree-browser.component.css)
 
-- 2024-05-23: upgraded to Angular 18.
-- 2023-11-09: upgraded to Angular 17.
+💡 If you want to add search by label with multiple matches highlight, add a form to your component and call the corresponding methods of the store service, like in the [thesaurus paged browser tree component sample](./src/app/components/thesaurus-paged-tree-browser/thesaurus-paged-tree-browser.component.ts) (`findLabels`, `removeHilites`).