@myrmidon/cadmus-thesaurus-store 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# CadmusThesaurusStore
|
|
2
|
+
|
|
3
|
+
This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.0.0.
|
|
4
|
+
|
|
5
|
+
This library contains components related to Cadmus thesauri and using as their core the paged tree browser from `@myrmidon/paged-data-browsers`.
|
|
6
|
+
|
|
7
|
+
## Thesauri
|
|
8
|
+
|
|
9
|
+
Thesauri represent taxonomies of any type you might be using in editing your content. For instance, in describing a writing you might have a set of ink colors to pick from. The models for the thesaurus and its entries are defined in an external package (`@myrmidon/cadmus-core`).
|
|
10
|
+
|
|
11
|
+
Essentially, a **thesaurus** is a list of terms, each having an ID and a human-readable value. Such list can be a simple, flat list, or a hierarchical list. In both cases, they are defined as objects having each a list of entries.
|
|
12
|
+
|
|
13
|
+
Each **entry** in a thesaurus object has:
|
|
14
|
+
|
|
15
|
+
- an arbitrarily assigned `id`, which must be unique in the context of that object;
|
|
16
|
+
- a text `value` to be displayed to the end user.
|
|
17
|
+
|
|
18
|
+
For instance, you might have a list of languages to pick from, like English, French, Italian, etc.: in this case, your thesaurus would have its own ID, e.g. `languages`, plus entries like `eng`=English, `fre`=French, `ita`=Italian, etc. Here I'm using ISO 639 for language codes, and using standards is always recommended when available; but IDs are totally arbitrary.
|
|
19
|
+
|
|
20
|
+
You can also have **hierarchical** thesauri, where entries are arranged in a hierarchy represented with _dots_ in their IDs. For instance, say you want to represent this simple 2-levels hierarchy:
|
|
21
|
+
|
|
22
|
+
- language:
|
|
23
|
+
- language: phonology
|
|
24
|
+
- language: morphology
|
|
25
|
+
- language: syntax
|
|
26
|
+
|
|
27
|
+
You can use a dot in each entry to represent three children entries under the same node:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
[
|
|
31
|
+
{ "id": "lang.pho", "value": "language: phonology" },
|
|
32
|
+
{ "id": "lang.mor", "value": "language: morphology" },
|
|
33
|
+
{ "id": "lang.syn", "value": "language: syntax" }
|
|
34
|
+
]
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
>By convention, for each dot in the ID there is a colon in the value, so that the full hierarchy is displayed in every entry.
|
|
38
|
+
|
|
39
|
+
Should you want to have a selectable entry also for the parent language node, you just have to add another one, like this:
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
[
|
|
43
|
+
{ "id": "lang.-", "value": "language" },
|
|
44
|
+
{ "id": "lang.pho", "value": "language: phonology" },
|
|
45
|
+
{ "id": "lang.mor", "value": "language: morphology" },
|
|
46
|
+
{ "id": "lang.syn", "value": "language: syntax" }
|
|
47
|
+
]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Services
|
|
51
|
+
|
|
52
|
+
A couple of services are used by the components in this library:
|
|
53
|
+
|
|
54
|
+
- `StaticThesaurusPagedTreeStoreService`, which represents an in-memory store of the thesaurus being displayed. This service serves as an adapter from an array of thesaurus entries to the paged tree store service. Its nodes are of type `ThesaurusEntryPagedTreeNode` and its filter is of type `ThesaurusEntryNodeFilter`.
|
|
55
|
+
- `EditableStaticThesaurusPagedTreeStoreService`, which is the editable counterpart of `StaticThesaurusPagedTreeStoreService`. It still loads all the entries of a thesaurus at once (whence "static" in its name), but it can keep track of user edits and then commit all changes at once.
|
|
56
|
+
|
|
57
|
+
## Components
|
|
58
|
+
|
|
59
|
+
The higher-level components exported by this library are listed here.
|
|
60
|
+
|
|
61
|
+
### ThesaurusTreeComponent
|
|
62
|
+
|
|
63
|
+
- 🔑 `cadmus-thesaurus-tree`
|
|
64
|
+
|
|
65
|
+
The thesaurus tree component displays a set of hierarchical thesaurus entries in a tree, provided that each entry marks its hierarchy with dots, and allows you to pick any entry.
|
|
66
|
+
|
|
67
|
+
- ▶️ input:
|
|
68
|
+
- `entries`: all the entries in the thesaurus.
|
|
69
|
+
- `renderLabel`: the optional function for rendering node's labels. This is typically used to shorten the label of nested entries when displaying them.
|
|
70
|
+
- 🔥 output:
|
|
71
|
+
- `entryChange`: fired when an entry is picked.
|
|
72
|
+
|
|
73
|
+
Internally, this component uses:
|
|
74
|
+
|
|
75
|
+
- an instance of the `StaticThesaurusPagedTreeStoreService`.
|
|
76
|
+
- an instance of the `ThesaurusBrowserComponent`, which is a readonly paged tree browser specialized to display thesaurus entries.
|
|
77
|
+
|
|
78
|
+
### ThesaurusEntriesPicker
|
|
79
|
+
|
|
80
|
+
- 🔑 `cadmus-thesaurus-entries-picker`
|
|
81
|
+
|
|
82
|
+
This is a more compact and powerful component which allows you to manage **entries picked** from a hierarchical thesaurus, which is usually collapsed so that the component uses just as much space as needed to display a list of picked entries. Each picked entry can be directly removed from the list, and new entries can be added by expanding the tree and picking them.
|
|
83
|
+
|
|
84
|
+
The component also allows users to enter **custom entries** beyond the thesaurus entries. This is a special functionality which must be opted-in. Such entries are all marked by an initial `$` prefix and do not belong to a thesaurus.
|
|
85
|
+
|
|
86
|
+
- ▶️ input:
|
|
87
|
+
- `availableEntries`: all the entries in the thesaurus. Required.
|
|
88
|
+
- `entries`: the entries picked.
|
|
89
|
+
- `hierarchicLabels`: true to show the entries with labels shortened according to their hierarchy.
|
|
90
|
+
- `autoSort`: true to automatically sort the picked entries (disables drag-and-drop). When false, entries can be manually reordered via drag-and-drop.
|
|
91
|
+
- `allowCustom`: true to allow custom values (not in the entries list).
|
|
92
|
+
- `minEntries`: the minimum number of picked entries.
|
|
93
|
+
- `maxEntries`: the maximum number of picked entries.
|
|
94
|
+
- `expanded`: true when the picker is expanded rather than collapsed.
|
|
95
|
+
- `emptyMessage`: the message to show when there are no picked entries.
|
|
96
|
+
- 🔥 output:
|
|
97
|
+
- `entriesChange`: fired when `entries` change.
|
|
98
|
+
|
|
99
|
+
### EditableThesaurusBrowserComponent
|
|
100
|
+
|
|
101
|
+
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`.
|
|
102
|
+
|
|
103
|
+
- ▶️ input:
|
|
104
|
+
- `service`: an instance of `EditableStaticThesPagedTreeStoreService` used to load nodes. Required.
|
|
105
|
+
- `hasRootFilter`: true to show the tree root nodes filter.
|
|
106
|
+
- `nodePick`: fired when an entry node is clicked.
|
|
107
|
+
- 🔥 output:
|
|
108
|
+
- `changesStateChange`: fired when the changes-state changes.
|
|
109
|
+
|
|
110
|
+
## History
|
|
111
|
+
|
|
112
|
+
### 0.0.1
|
|
113
|
+
|
|
114
|
+
- 2026-01-17:
|
|
115
|
+
- added `thesaurus-entries-picker` moving it from `@myrmidon/cadmus-ui` so that all the thesaurus components can migrate into `@myrmidon/cadmus-thesaurus-store` in this workspace. These components are strictly dependent from the paged tree browser in this workspace, which is a generic component. So, this Cadmus-related library is developed in this workspace, rather than in Cadmus shell workspace, as the components are essentially wrappers around the functionality developed in this workspace.
|
|
116
|
+
- renamed thesauri components (changing "thes..." into "thesaurus..." and shortening where possible).
|