npm - @myrmidon/cadmus-refs-asserted-ids - Versions diffs - 10.0.17 → 11.0.1 - Mend

@myrmidon/cadmus-refs-asserted-ids 10.0.17 → 11.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.

Files changed (5) hide show

package/README.md +295 -242
package/fesm2022/myrmidon-cadmus-refs-asserted-ids.mjs +338 -105
package/fesm2022/myrmidon-cadmus-refs-asserted-ids.mjs.map +1 -1
package/package.json +12 -9
package/types/myrmidon-cadmus-refs-asserted-ids.d.ts +102 -4

package/README.md CHANGED Viewed

@@ -8,13 +8,16 @@ This project was generated using [Angular CLI](https://github.com/angular/angula
   - [External IDs](#external-ids)
   - [Internal IDs](#internal-ids)
   - [ID Components](#id-components)
-  - [AssertedIdComponent](#assertedidcomponent)
-    - [Configuring Asserted ID](#configuring-asserted-id)
-  - [AssertedIdsComponent](#assertedidscomponent)
-  - [PinTargetLookupComponent](#pintargetlookupcomponent)
-    - [Configuring the Target ID Editor](#configuring-the-target-id-editor)
-  - [Asserted Composite ID](#asserted-composite-id)
-  - [Asserted Composite IDs](#asserted-composite-ids)
+    - [AssertedCompositeIdComponent](#assertedcompositeidcomponent)
+    - [AssertedCompositeIdsComponent](#assertedcompositeidscomponent)
+    - [PinTargetLookupComponent](#pintargetlookupcomponent)
+  - [Configuring Asserted ID](#configuring-asserted-id)
+    - [Configuring Lookup Providers](#configuring-lookup-providers)
+    - [Configuring Taxonomy Store](#configuring-taxonomy-store)
+    - [Defining Index Lookups](#defining-index-lookups)
+  - [Legacy Components](#legacy-components)
+    - [AssertedIdComponent](#assertedidcomponent)
+    - [AssertedIdsComponent](#assertedidscomponent)
   - [History](#history)
     - [10.0.14](#10014)
     - [10.0.13](#10013)
@@ -31,6 +34,8 @@ This project was generated using [Angular CLI](https://github.com/angular/angula
 The asserted ID and asserted composite IDs bricks provide a way to include _external_ or _internal_ references to resource identifiers, whatever their type and origin. These components are the foundation for pin-based links in links part and links fragment types, as they provide both external and internal links, optionally accompanied by an assertion.
+Additionally, since version 10.1.0 they can target also editable taxonomies from the [Cadmus Taxonomies Store](https://vedph.github.io/cadmus-doc/models/taxonomies.html).
 ## External IDs
 External IDs are provided by users, either manually or with the aid of lookup services. Cadmus already provides a set of builtin lookup providers for popular web APIs like VIAF, DBPedia, Geonames, and WHG, and you can add as many as you want.
@@ -46,27 +51,28 @@ So, in its most complete model an external ID has:
 - an optional scope.
 - an optional tag, which can be used to group or classify IDs in some way.
-## Internal IDs
-Internal IDs are human-friendly identifiers connected to any data in the Cadmus database. They can refer to an item as a whole, or to a specific part or fragment of it, or to a specific feature inside a part or fragment.
+An external ID can also come from a taxonomy. In this case:
-In most cases, human users prefer friendly identifiers, unique only in the context of their editing environment (which is what is present to the user's mind when entering data). These identifiers in Cadmus are named **EID**s (=_entity IDs_), and may be found scattered among parts or fragments via pins, or linked to whole items via a metadata part.
+- the GID is built as `@TX:TREEID/NODEKEY` where `@TX:` is a fixed prefix (meaning the GID refers to a taxonomy), `TREEID` is the tree's ID (an arbitrary ID), and `NODEKEY` the node's key. The node's key is a string unique only within its tree; that's why we build a global ID by prefixing its tree ID. Internally, in the taxonomies store each ID has a unique numeric ID, but this is just an implementation detail and nodes are always referred by their key.
+- the label comes from the node's label.
->Of course, all Cadmus data objects (items, parts and fragments) have their own globally unique identifier, which is an opaque GUID like `401267e7-282c-40e6-8f47-67be54382b07`. EIDs instead provide human-friendly identifiers, e.g. just like the IDs you type in a TEI document. Additionally, they can be used to target a specific feature inside a part or fragment, via search pins provided by it.
+## Internal IDs
-**Item EID**s are just human-friendly aliases used to refer to a Cadmus item as a whole. Whenever we want to assign a human-friendly ID to the _item_ itself, rather than referring to it by its GUID, the conventional method relies on the generic _metadata part_, which allows users entering any number of arbitrarily defined name=value pairs. So, a user might enter a pair like e.g. `eid=vat_lat_123`, and use it as the human friendly identifier for a manuscript item corresponding to Vat.Lat.123.
+Every Cadmus object (item, part or fragment) has its own own _globally unique identifier_, which is an opaque GUID like `401267e7-282c-40e6-8f47-67be54382b07`. These identify the objects; but the framework is completely agnostic with reference to their model: the item is just an empty box, while objects put in it (parts or fragments) can have any model. This is a requirement for those objects to be composable and reusable in the context of an open-ended, dynamic modeling.
-Ultimately, even an item EID, just like any other EID is just based on a **search pin**. In Cadmus, any part or fragment in an item provides any number of _search pins_, which essentially are name=value pairs, used for a simple search during editing.
+The only way Cadmus has to link a part or an entry inside it is via "**pins**", i.e. name=value pairs which the part or fragment exposes in the index whenever it is saved. The part or fragment is the only component which knows what is inside its model; for the rest of the system, it is (and must be) a blackbox. Therefore, these pins are assigned by the object itself by reflecting on its own data, and act as target points for internal links.
-Each pin name is unique only in the context of the part or fragment defining it, so that pin design is not constrained; yet, a pin can easily be turned into a globally unique identifier by adding to it other data.
+Typically, according to the nature of each model, some pins can be designed to be used as anchor points and refer to the object as a whole, or to an entry in its model, when the model contains multiple entries. For instance, in a part with a list of manuscript [decorations](https://github.com/vedph/cadmus-codicology/blob/master/docs/cod-decorations.md), there are multiple entries, one per decoration; and one might want to target a specific decoration. To this end, each decoration has an `eid` property which represents a human-friendly, arbitrary string used to identify it, like `angel`. These identifiers are like the IDs you may type in a TEI document using the `@xml:id` attribute: they are short and human-friendly, and also allow to deeply link a subset of the object's data.
-For instance, given that every part or fragment has its own globally unique ID, you can just prepend it to the pin name to get a globally unique internal ID pointing to a specific feature of a specific part or fragment. Thus, users just enter pins as arbitrary, easy to use strings, when entering data; but the general architecture also provides a way for making them globally unique.
+So, internal IDs are human-friendly identifiers connected to any data in the Cadmus database. They can refer to:
->This is how the in-editor search is implemented, and a similar mechanism is also used when mapping entities from parts into a semantic graph (via mapping rules).
+- a specific _internal entry_ inside a part or fragment containing multiple entries (typically via a property conventionally named `eid`);
+- a specific _part or fragment_ (via any of its pins designed or chosen to represent the object as a whole);
+- an _item_ as a whole (via its [metadata part](https://github.com/vedph/cadmus-general/blob/master/docs/metadata.md)'s `eid` metadatum): this is more tricky, because items are just containers of parts and fragments. So, they have no pins at all on their own, except for those connected to their fixed set of metadata (like title), which usually are not convenient as identifiers, unless you have a well-defined convention for assigning titles. So, conventionally the metadata part is used to provide a human-friendly ID for the item as a whole: whenever the item contains that part, and that part has a metadatum with name=`eid`, this is assumed to be the item's human-friendly ID. So, a user might enter a metadatum like e.g. `eid`=`vat_lat_123`, and use it as the human friendly identifier for a manuscript item corresponding to Vat.Lat.123.
-For instance, say a decorations part in a manuscript item collects a number of decorations; for each one, it might define an arbitrary EID (like e.g. `angel1`) used to identify it among the others, in the context of that part.
+Thus, ultimately all EIDs are based on a search pins. Each _pin name is unique only in the context of the part or fragment defining it_, so that pin design is not constrained; yet, a pin can easily be turned into a globally unique identifier by adding to it other data. For instance, given that every part or fragment has its own globally unique ID, you can just prepend it to the pin name to get a globally unique internal ID pointing to a specific feature of a specific part or fragment. Thus, we get the best of both worlds: when entering data, users are free to define pins as arbitrary, easy to use strings (e.g. "angel1", "angel2", "devil", etc.); but the general architecture also provides a way for making them globally unique, so they do not have to worry about that. All what they need to care about is that they are unique within the part or fragment they are editing.
-When filling the decorations part with data, users just ensure that this EID is unique in the context of the list they are editing; in other terms, no other decoration in that part will have `angel1` as its ID, while it might happen that `angel1` is used somewhere else in another part. Yet, should we be in need of a non-scoped, unique ID, we could easily build it by assembling together the EID with its part/item IDs, which by definition are globally unique (being GUIDs).
+---
 ## ID Components
@@ -79,154 +85,78 @@ According to the scenario illustrated above, the basic requirements for ID compo
 >👉 The demo found in this workspace uses a [mock data service](../../../src/app/services/mock-item.service.ts) instead of the real one, which provides a minimal set of data and functions, just required for the components to function.
-Various components from this library provide a different level of complexity, so you can pick the one which best fits your purposes; in general, the most powerful and versatile ID picker is represented by the [asserted composite ID](#asserted-composite-id), which can be used for both external and internal IDs, with full lookup support from lookup providers in either case.
-## AssertedIdComponent
-- 🔑 `AssertedIdComponent`
-- 🚩 `cadmus-refs-asserted-id`
-- ▶️ input:
-  - `id` (`AssertedId? | null`)
-  - `noEidLookup` (`boolean?`)
-  - `hasSubmit` (`boolean?`)
-- 📚 thesauri:
-  - `asserted-id-scopes` (for `idScopeEntries`)
-  - `asserted-id-tags` (for `idTagEntries`).
-  - `assertion-tags` (for `assTagEntries`).
-  - `doc-reference-types` (for `refTypeEntries`).
-  - `doc-reference-tags` (for `refTagEntries`).
-  - `asserted-id-features` (for `featureEntries`).
-- 🔥 output:
-  - `idChange` (`AssertedId`)
-  - `editorClose`
-  - `extMoreRequest` (`RefLookupSetEvent`): the user requested more about the current external lookup source.
-The asserted ID component allows editing a simple model representing a generic ID with an optional assertion. The ID has:
-- **value**: the ID itself.
-- **scope**: the context the ID originates from (e.g. an ontology, a repository, a website, etc.).
-- an optional **tag**, used to group or classify the ID.
-- an optional set of **features**, from a hierarchical thesaurus. For instance, these could be the role(s) of a person linked to an object, like customer, seller, creator, etc.
-- an optional **note**.
-- an optional **assertion**, used to define the uncertainty level of the assignment of this ID to the context it applies to.
-The asserted ID component provides an internal lookup mechanism based on data pins and metadata conventions. When users want to add an ID referring to some internal entity, either found in a part or corresponding to an item, he just has to pick the type of desired lookup (when more than a single lookup search definition is present), and type some characters to get the first N pins starting with these characters; he can then pick one from the list. Once a pin value is picked, the lookup control shows all the relevant data which can be used as components for the ID to build:
-- the item GUID.
-- the item title.
-- the part GUID.
-- the part type ID.
-- the item's metadata part entries.
-The user can then use buttons to append each of these components to the ID being built, and/or variously edit it. When he's ok with the ID, he can then use it as the reference ID being edited.
-### Configuring Asserted ID
-The asserted ID component internally uses a scoped pin lookup component (`ScopedPinLookupComponent`) to provide a list of pin-based searches with a lookup control.  Whenever the user picks a pin value, he gets the details about its item and part, and item's metadata part, if any. He can then use these data to build a globally unique internal identifier by variously assembling these components.
-You can use the scoped ID lookup control to add a pin-based lookup for any entity in your own UI:
-(1) ensure to import the component (`ScopedPinLookupComponent`).
-(2) add a lookup control to your UI, like this:
-```html
-<!-- lookup -->
-<cadmus-scoped-pin-lookup *ngIf="!noLookup" (idPick)="onIdPick($event)"/>
-```
-In this sample, my UI has a `noLookup` property which can be used to hide the lookup if not required:
-```ts
-@Input()
-public noLookup?: boolean;
-public onIdPick(id: string): void {
-  // TODO: set your control's value, e.g.:
-  // this.myId.setValue(id);
-  // this.myId.updateValueAndValidity();
-  // this.myId.markAsDirty();
-}
-```
-(3) in your app's `index-lookup-definitions.ts` file, add the required lookup definitions. Each definition has a conventional key, and is an object with part type ID for the lookup scope, and pin name, e.g.:
+Various components from this library provide a different level of complexity, so you can pick the one which best fits your purposes; in general, the most powerful and versatile ID picker is represented by the [asserted composite ID](#assertedcompositeidcomponent) and its multiple-targets counterpart [asserted composite IDs](#assertedcompositeidscomponent), which can be used for both external and internal IDs and editable taxonomies, with full lookup support. Other components in this library should be considered obsolete.
-```ts
-import { IndexLookupDefinitions } from '@myrmidon/cadmus-core';
-import {
-  METADATA_PART_TYPEID,
-  HISTORICAL_EVENTS_PART_TYPEID,
-} from '@myrmidon/cadmus-part-general-ui';
-export const INDEX_LOOKUP_DEFINITIONS: IndexLookupDefinitions = {
-  // item's metadata
-  meta_eid: {
-    typeId: METADATA_PART_TYPEID,
-    name: 'eid',
-  },
-  // general parts
-  event_eid: {
-    typeId: HISTORICAL_EVENTS_PART_TYPEID,
-    name: 'eid',
-  },
-  // ... etc.
-};
-```
->Note that while pin name and type will not be displayed to the end user, the key of each definition will. Unless you have a single definition, the lookup component will display a dropdown list with all the available keys, so that the user can select the lookup's scope. So, use short, yet meaningful keys here, like in the above sample (`meta_eid`, `event_eid`).
-## AssertedIdsComponent
-An editable list of asserted IDs.
+### AssertedCompositeIdComponent
-- 🔑 `AssertedIdsComponent`
-- 🚩 `cadmus-refs-asserted-ids`
+- 🔑 `AssertedCompositeIdComponent`
+- 🚩 `cadmus-refs-asserted-composite-id`
 - ▶️ input:
-  - `ids` (`AssertedId[]`)
+  - `id` (`AssertedId`)
+  - `pinByTypeMode` (`boolean?`)
+  - `canSwitchMode` (`boolean?`)
+  - `canEditTarget` (`boolean?`)
+  - `defaultPartTypeKey` (`string?|null`)
+  - `lookupDefinitions` (`IndexLookupDefinitions?`)
 - 📚 thesauri:
   - `asserted-id-scopes` (for `idScopeEntries`)
   - `asserted-id-tags` (for `idTagEntries`)
   - `assertion-tags` (for `assTagEntries`)
   - `doc-reference-types` (for `refTypeEntries`)
   - `doc-reference-tags` (for `refTagEntries`)
-  - `asserted-id-features` (for `featureEntries`).
-- 🔥 output:
-  - `idsChange` (`AssertedId[]`)
-## PinTargetLookupComponent
-- ▶️ input:
-  - `target` (`PinTarget? | null`)
-  - `pinByTypeMode` (`boolean?`)
-  - `canSwitchMode` (`boolean?`)
-  - `canEditTarget` (`boolean?`)
-  - `defaultPartTypeKey` (`string?|null`)
-  - `lookupDefinitions` (`IndexLookupDefinitions?`)
-  - `extLookupConfigs` (`RefLookupConfig[]`): the configurations of external lookup providers, if any.
-- 🔥 output:
-  - `targetChange` (`PinTarget`)
+- ⚡ output:
+  - `idChange` (`AssertedId[]`)
   - `editorClose`
+  - `extMoreRequest` (`RefLookupSetEvent`): the user requested more about the current external lookup source.
-This component is used to edit an internal or external ID via lookup, and is the core of the [asserted composite ID](#asserted-composite-id) component:
+This is the most complete ID reference, which can be used for both external and internal IDs, providing full lookup in either cases. Each asserted composite ID has:
-- for **external** IDs, you can enter the ID and its human-friendly label manually, or get them from any number of lookup providers (e.g. VIAF, geonames, etc.).
+- a `target`, representing the pin-based target of the ID. The target model has these properties:
+  - a global ID, `gid`, built from the pin or manually defined;
+  - a human-friendly `label` for the target, built from the pin or manually defined;
+  - for _internal_ links only:
+    - `itemId` for the item the pin derives from;
+    - when the pin derives from a part, an optional `partId`, `partTypeId`, `roleId`;
+    - the `name` and `value` of the pin.
+- an optional `scope`, representing the context the ID originates from (e.g. an ontology, a repository, a website, etc.).
+- an optional `tag`, possibly used to group or classify the ID.
+- an optional `assertion`, possibly used to define the uncertainty level of the assignment of this ID to the context it applies to.
-- for **internal** IDs, your lookup is based on search pins.
+To distinguish among link targets:
-- for **both** external and internal IDs, you can optionally specify a scope (usually defining the context of the ID, like VIAF or DBPedia, or your own Cadmus database) and a tag (an arbitrary string for grouping or tagging the ID in some way).
+- when the ID is **external**, the only properties set for the target model are `gid` (=the ID) and `label`. So, they never have the `name` property, which instead is required for internal links.
+- when the ID is a **taxonomy** node, it is just like an external link, but the `gid` always starts with prefix `@TX:`.
+- when the ID is **internal**, it has the `name` property (which is the pin's name, a pin being required by definition for an internal link).
+- You can easily distinguish between an external and internal ID by looking at a property like `name`, which is always present for internal IDs, and never present for external IDs.
-With thousands of parts/fragments providing dozens of pins, you quickly end up with a lot of them. So, to ease their lookup in this control, you can filter them. This component provides _two modes_ to get to a pin-based link target:
+For internal lookup, with thousands of parts/fragments providing dozens of pins, you quickly end up with a lot of them. So, to ease their lookup in this control, you can filter them. This component provides _two modes_ to get to a pin-based link target:
-- **by item** (default mode): the user selects an item from a lookup list; then a part, from the list of the parts found in the selected item; and finally a pin, from a lookup list of pins filtered by that item's part. This essentially provides a way of selecting a pin from a restricted lookup set, by walking the data hierarchy from item to part/fragment and finally pin.
-- **by type**: the user selects the part's type (this is automatically pre-selected when only a single type is set), and then selects a pin from a lookup list of pins filtered by that part's type. The list of part types may come from several sources:
+- _by item instance_ (option `pinByTypeMode`=`false`): lookup pins filtered by a specific item (via its assigned EID in its metadata part), and optionally by any of its parts. This is the default mode, as in most cases users have a top-bottom approach and think first of the item they want to target, and then, possibly, to a specific portion of its data (unless they are just happy to target the item as a whole).
+- _by part type_ (option `pinByTypeMode`=`true`): directly lookup by pin value, in the context of a specific part type and pin namem, as specified by index lookup definitions (`indexLookupDefinitions` property). The list of part types may come from several sources:
   - explicitly set via the component `lookupDefinitions` property;
   - if this is not set, the lookup definitions will be got via injection when available;
   - if the injected definitions are empty, the lookup definitions will be built from the `model-types` thesaurus;
   - if this is not available either, the _by-type_ lookup will be disabled.
 >Filtering by item essentially means filtering by an object instance: for instance a specific manuscript object. Filtering by type instead means filtering by pin class, as each part or fragment provides its own set of search pins, whose names are meaningful and unique only in their context.
+>You can use options `canSwitchMode` to allow users switching between by-type and by-item modes, and `canEditTarget` to allow users edit the link target GID and label also for internal pins, where they are automatically provided by pin lookup.
-In both cases, in the end the target ID model is the same; it's just the way the user selects the pin which changes. You can specify the mode for the component with `pinByTypeMode`, and control the possibility of switching between modes with `canSwitchMode`.
+According to the target type and component settings, the following modes are available:
+- external:
+  - pick an ID from 1 or more lookup providers
+  - manually type or paste an ID
+  - manually build an ID from the target object's properties
+- internal:
+  - from pin lookup:
+    - by type: pick a preset (as specified by lookup index definitions) and then lookup a pin within its scope.
+    - by item:
+      - filter by item: lookup pins limited to a specific item.
+      - filter by item's part: lookup pins limited to a specific item's part.
+      - lookup pin directly from its name
+  - manual
+  - both
+- taxonomy: from 1 tree's node.
 Once the user picks an internal pin, the target is automatically filled with data from the pin itself. Two values are calculated:
@@ -243,54 +173,14 @@ Optionally, users can customize both `gid` and `label` (when `canBuildGid` and `
 The user can then use buttons to append each of these components to the ID being built, and/or variously edit it. When he's ok with the ID, he can then use it as the reference ID being edited.
->👉 The demo found in this workspace uses a [mock data service](../../../src/app/services/mock-item.service.ts) instead of the real one, which provides a minimal set of data and functions, just required for the components to function.
-### Configuring the Target ID Editor
-You can configure the target ID editor to use any number of lookup providers:
-(1) ensure to import the `PinTargetLookupComponent` control in your component.
+### AssertedCompositeIdsComponent
-(2) add a lookup control to your UI, like this:
-```html
-<!-- lookup -->
-<cadmus-pin-target-lookup [canSwitchMode]="true"
-                          (targetChange)="onTargetChange($event)"/>
-```
-(3) specify the lookup definitions, either from binding, or via injection. In the latter case, in your app's `index-lookup-definitions.ts` file, add the required lookup definitions. Each definition has a conventional key, and is an object with part type ID for the lookup scope, and pin name, e.g.:
-```ts
-import { IndexLookupDefinitions } from '@myrmidon/cadmus-core';
-import {
-  METADATA_PART_TYPEID,
-  HISTORICAL_EVENTS_PART_TYPEID,
-} from '@myrmidon/cadmus-part-general-ui';
-export const INDEX_LOOKUP_DEFINITIONS: IndexLookupDefinitions = {
-  // item's metadata
-  meta_eid: {
-    typeId: METADATA_PART_TYPEID,
-    name: 'eid',
-  },
-  // general parts
-  event_eid: {
-    typeId: HISTORICAL_EVENTS_PART_TYPEID,
-    name: 'eid',
-  },
-  // ... etc.
-};
-```
->Note that while pin name and type will not be displayed to the end user, the key of each definition will. Unless you have a single definition, the lookup component will display a dropdown list with all the available keys, so that the user can select the lookup's scope. So, use short, yet meaningful keys here, like in the above sample (`meta_eid`, `event_eid`).
-## Asserted Composite ID
+A collection of asserted composite IDs.
-- 🔑 `AssertedCompositeIdComponent`
-- 🚩 `cadmus-refs-asserted-composite-id`
+- 🔑 `AssertedCompositeIdsComponent`
+- 🚩 `cadmus-refs-asserted-composite-ids`
 - ▶️ input:
-  - `id` (`AssertedId`)
+  - `ids` (`AssertedId[]`)
   - `pinByTypeMode` (`boolean?`)
   - `canSwitchMode` (`boolean?`)
   - `canEditTarget` (`boolean?`)
@@ -303,87 +193,250 @@ export const INDEX_LOOKUP_DEFINITIONS: IndexLookupDefinitions = {
   - `doc-reference-types` (for `refTypeEntries`)
   - `doc-reference-tags` (for `refTagEntries`)
 - ⚡ output:
-  - `idChange` (`AssertedId[]`)
-  - `editorClose`
-  - `extMoreRequest` (`RefLookupSetEvent`): the user requested more about the current external lookup source.
-This is the most complete ID reference, which can be used for both external and internal IDs, providing full lookup in either cases. Each asserted composite ID has:
-- a `target`, representing the pin-based target of the ID. The target model has these properties:
-  - a global ID, `gid`, built from the pin or manually defined;
-  - a human-friendly `label` for the target, built from the pin or manually defined;
-  - for internal links only:
-    - `itemId` for the item the pin derives from;
-    - when the pin derives from a part, an optional `partId`, `partTypeId`, `roleId`;
-    - the `name` and `value` of the pin.
-- an optional `scope`, representing the context the ID originates from (e.g. an ontology, a repository, a website, etc.).
-- an optional `tag`, eventually used to group or classify the ID.
-- an optional `assertion`, eventually used to define the uncertainty level of the assignment of this ID to the context it applies to.
+  - `idsChange` (`AssertedCompositeId[]`)
-When the ID is **external**, the only properties set for the target model are `gid` (=the ID) and `label`. You can easily distinguish between an external and internal ID by looking at a property like `name`, which is always present for internal IDs, and never present for external IDs.
+### PinTargetLookupComponent
-There are different **options** to customize the lookup behavior:
+This component is not designed for direct use by higher-level consumer components. It is embedded by other components to edit their target.
-- lookup pins by part type or by item instance:
-  - _by part type_: you directly lookup by pin name, in the context of a specific part type. The part type is selected from a dropdown list, which draws its data from the configured `IndexLookupDefinitions`.
-  - _by item instance_: you lookup pins filtered by a specific item (via its assigned EID in its metadata part), and optionally by any of its parts. This is the default mode, as in most cases users have a top-bottom approach and think first of the item they want to target, and then, possibly, to a specific portion of its data (unless they are just happy to target the item as a whole).
+- ▶️ input:
+  - `target` (`PinTarget? | null`)
+  - `pinByTypeMode` (`boolean?`)
+  - `canSwitchMode` (`boolean?`)
+  - `canEditTarget` (`boolean?`)
+  - `defaultPartTypeKey` (`string?|null`)
+  - `lookupDefinitions` (`IndexLookupDefinitions?`)
+  - `extLookupConfigs` (`RefLookupConfig[]`): the configurations of external lookup providers, if any.
+- 🔥 output:
+  - `targetChange` (`PinTarget`)
+  - `editorClose`
->The part type ID and pin name filter (i.e. the _index lookup definitions_) can be set from many sources:
+## Configuring Asserted ID
+### Configuring Lookup Providers
+Lookup providers must be configured once in the app's root component. Typically (see [app.ts](../../../src/app/app.ts) in this repository):
+1. add a `configureLookup` function to your app's component code:
+    ```ts
+    private configureLookup(): void {
+      const storage = inject(RamStorageService);
+      storage.store(LOOKUP_CONFIGS_KEY, [
+        // the colors provider is a mock provider using local data
+        {
+          name: 'colors',
+          iconUrl: '/img/colors128.png',
+          description: 'Colors',
+          label: 'color',
+          service: new WebColorLookup(),
+          // compute the lookup item's ID
+          itemIdGetter: (item: any) => item?.value,
+          // compute the lookup item's human-friendly label
+          itemLabelGetter: (item: any) => item?.name,
+        },
+        // the VIAF provider consumes the public VIAF API
+        {
+          name: 'VIAF',
+          iconUrl: '/img/viaf128.png',
+          description: 'Virtual International Authority File',
+          label: 'ID',
+          service: inject(ViafRefLookupService),
+          itemIdGetter: (item: any) => item?.viafid,
+          itemLabelGetter: (item: any) => item?.term,
+        },
+        // ... etc.
+    }
+    ```
+2. call this function from your app's constructor.
+>It is suggested to add an icon for each provider so you can easily identify it. You can grab icons for existing providers from this repository (see the `public` folder).
+### Configuring Taxonomy Store
+The taxonomy store can be configured as follows:
+1. ensure to add TaxoStore packages: `pnpm i @myrmidon/taxo-store-api @myrmidon/taxo-store-picker`.
+2. add a `configureTaxoLookup` function to your app's component code, adding an entry for each taxonomy tree you want to expose:
+    ```ts
+    private configureTaxoLookup(storage: RamStorageService): void {
+      storage.store(LOOKUP_TAXOSTORE_CONFIGS_KEY, [
+        {
+          treeId: 'animals',
+          treeName: 'animals',
+          // user can edit nodes
+          canEdit: false,
+          // user can add new nodes
+          canAdd: false,
+          // user can delete nodes
+          canDelete: false,
+        },
+        {
+          treeId: 'food',
+          treeName: 'food',
+          canEdit: false,
+          canAdd: false,
+          canDelete: false,
+        },
+        // ... etc.
+      ] as TaxoStoreLookupConfig[]);
+    }
+    ```
+    >Note that here you can be very granular in your settings: for each taxonomy tree, you can define its UI label and whether its nodes can be edited, deleted and added by users, and set other options to change the picker's behavior (see `TaxoStoreLookupConfig`).
+3. call this function from your app's constructor.
+### Defining Index Lookups
+The part type ID and pin name filter (i.e. the _index lookup definitions_) can be set from many sources:
 1. directly from the consumer code by setting `lookupDefinitions`;
 2. from injection, when (1) is not used;
 3. from thesaurus `model-types`, when (2) is empty.
-- set `pinByTypeMode` to true to let the editor use by-type mode instead of by-item;
-- set `canSwitchMode` to true to allow users switch between by-type and by-item modes;
-- set `canEditTarget` to true to allow users edit the link target GID and label also for internal pins, where they are automatically provided by pin lookup.
+The typical approach is via `lookupDefinitions`. To this end:
+1. add an `index-lookup-definitions.ts` file to your app with code like this (change the array to fit your scenario):
+    ```ts
+    import { IndexLookupDefinitions } from '@myrmidon/cadmus-core';
+    import {
+      HISTORICAL_EVENTS_PART_TYPEID,
+      METADATA_PART_TYPEID,
+    } from '@myrmidon/cadmus-part-general-ui';
+    import { COD_CONTENTS_PART_TYPEID } from '@myrmidon/cadmus-part-codicology-contents';
+    import { COD_DECORATIONS_PART_TYPEID } from '@myrmidon/cadmus-part-codicology-decorations';
+    import { COD_EDITS_PART_TYPEID } from '@myrmidon/cadmus-part-codicology-edits';
+    import { COD_HANDS_PART_TYPEID } from '@myrmidon/cadmus-part-codicology-hands';
+    import { COD_MATERIAL_DSC_PART_TYPEID } from '@myrmidon/cadmus-part-codicology-material-dsc';
+    export const INDEX_LOOKUP_DEFINITIONS: IndexLookupDefinitions = {
+      // item's metadata
+      meta_eid: {
+        typeId: METADATA_PART_TYPEID,
+        name: 'eid',
+      },
+      // general parts
+      event_eid: {
+        typeId: HISTORICAL_EVENTS_PART_TYPEID,
+        name: 'eid',
+      },
+      // codicology parts
+      cod_unit_eid: {
+        typeId: COD_MATERIAL_DSC_PART_TYPEID,
+        name: 'unit-eid',
+      },
+      cod_hand_eid: {
+        typeId: COD_HANDS_PART_TYPEID,
+        name: 'eid',
+      },
+      cod_decoration_eid: {
+        typeId: COD_DECORATIONS_PART_TYPEID,
+        name: 'eid',
+      },
+      cod_artist_eid: {
+        typeId: COD_DECORATIONS_PART_TYPEID,
+        name: 'artist-id',
+      },
+      cod_content_eid: {
+        typeId: COD_CONTENTS_PART_TYPEID,
+        name: 'eid',
+      },
+      cod_edit_eid: {
+        typeId: COD_EDITS_PART_TYPEID,
+        name: 'eid',
+      },
+    };
+    ```
+These definitions are used to define preset filters for internal lookup:
+- each object is a filter, with its name (e.g. `meta_eid`).
+- `typeId` defines the type ID of the part/fragment where the ID to be looked up is stored.
+- `roleId` (optional) can be used to specify the part or fragment's role ID.
+- `name` defines the corresponding data pin's name to search in.
-These options can be variously combined to force users to use a specific behavior only; for instance, if you just want by-type lookup and automatic GID/label, set `pinByTypeMode` to true and `canSwitchMode` and `canEditTarget` to false.
+>Note that while pin name and type will not be displayed to the end user, the key of each definition will. Unless you have a single definition, the lookup component will display a dropdown list with all the available keys, so that the user can select the lookup's scope. So, use short, yet meaningful keys here, like in the above sample (`meta_eid`, `event_eid`).
-Also, you can use any number of lookup components for external IDs. To globally configure all the asserted composite IDs components for this purpose, you can define (e.g. in your app's component constructor) an array of configuration objects keyed under `ASSERTED_COMPOSITE_ID_CONFIGS_KEY`. Thus, this component provides many different ways for creating a link:
+This way, a pin-based lookup will be limited within the scope defined by the combination of object's type ID and pin's name, thus focusing on a specific subset of pins.
-- external:
-  - from 1 or more lookups
-  - manual
-  - both
-- internal:
-  - from pin lookup:
-    - filter by item
-    - filter by item's part
-    - lookup pin
-  - manual
-  - both
+Once this definition is in place, it can be injected where needed by adding this among the consumer class constructor’s arguments:
-Three components are used for this brick:
+```ts
+@Inject(INDEX_LOOKUP_DEFINITIONS)
+private _lookupDefs: IndexLookupDefinitions
+```
-- `AssertedCompositeIdsComponent`, the top level editor for the list of IDs. This has buttons to add new internal/external IDs, and a list of existing IDs. Each existing ID has buttons for editing, moving, and deleting it. When editing, the `AssertedIdComponent` is used in an expansion panel.
-- `AssertedCompositeIdComponent`, the editor for each single ID. This allows you to edit shared metadata (tag and scope), and specific properties for both external and internal ID.
-- `PinTargetLookupComponent`, the editor for an internal ID, i.e. a link target based on pins lookup. This is the core of the editor's logic.
+## Legacy Components
-## Asserted Composite IDs
+### AssertedIdComponent
-A collection of asserted composite IDs.
+>⚠️ Obsolete, use [AssertedCompositeIdComponent](#assertedcompositeidcomponent).
-- 🔑 `AssertedCompositeIdsComponent`
-- 🚩 `cadmus-refs-asserted-composite-ids`
+- 🔑 `AssertedIdComponent`
+- 🚩 `cadmus-refs-asserted-id`
+- ▶️ input:
+  - `id` (`AssertedId? | null`)
+  - `noEidLookup` (`boolean?`)
+  - `hasSubmit` (`boolean?`)
+- 📚 thesauri:
+  - `asserted-id-scopes` (for `idScopeEntries`)
+  - `asserted-id-tags` (for `idTagEntries`).
+  - `assertion-tags` (for `assTagEntries`).
+  - `doc-reference-types` (for `refTypeEntries`).
+  - `doc-reference-tags` (for `refTagEntries`).
+  - `asserted-id-features` (for `featureEntries`).
+- 🔥 output:
+  - `idChange` (`AssertedId`)
+  - `editorClose`
+  - `extMoreRequest` (`RefLookupSetEvent`): the user requested more about the current external lookup source.
+The asserted ID component allows editing a simple model representing a generic ID with an optional assertion. The ID has:
+- **value**: the ID itself.
+- **scope**: the context the ID originates from (e.g. an ontology, a repository, a website, etc.).
+- an optional **tag**, used to group or classify the ID.
+- an optional set of **features**, from a hierarchical thesaurus. For instance, these could be the role(s) of a person linked to an object, like customer, seller, creator, etc.
+- an optional **note**.
+- an optional **assertion**, used to define the uncertainty level of the assignment of this ID to the context it applies to.
+The asserted ID component provides an internal lookup mechanism based on data pins and metadata conventions. When users want to add an ID referring to some internal entity, either found in a part or corresponding to an item, he just has to pick the type of desired lookup (when more than a single lookup search definition is present), and type some characters to get the first N pins starting with these characters; he can then pick one from the list. Once a pin value is picked, the lookup control shows all the relevant data which can be used as components for the ID to build:
+- the item GUID.
+- the item title.
+- the part GUID.
+- the part type ID.
+- the item's metadata part entries.
+The user can then use buttons to append each of these components to the ID being built, and/or variously edit it. When he's ok with the ID, he can then use it as the reference ID being edited.
+### AssertedIdsComponent
+>⚠️ Obsolete, use [AssertedCompositeIdsComponent](#assertedcompositeidscomponent).
+An editable list of asserted IDs.
+- 🔑 `AssertedIdsComponent`
+- 🚩 `cadmus-refs-asserted-ids`
 - ▶️ input:
   - `ids` (`AssertedId[]`)
-  - `pinByTypeMode` (`boolean?`)
-  - `canSwitchMode` (`boolean?`)
-  - `canEditTarget` (`boolean?`)
-  - `defaultPartTypeKey` (`string?|null`)
-  - `lookupDefinitions` (`IndexLookupDefinitions?`)
 - 📚 thesauri:
   - `asserted-id-scopes` (for `idScopeEntries`)
   - `asserted-id-tags` (for `idTagEntries`)
   - `assertion-tags` (for `assTagEntries`)
   - `doc-reference-types` (for `refTypeEntries`)
   - `doc-reference-tags` (for `refTagEntries`)
-- ⚡ output:
-  - `idsChange` (`AssertedCompositeId[]`)
+  - `asserted-id-features` (for `featureEntries`).
+- 🔥 output:
+  - `idsChange` (`AssertedId[]`)
 ## History
+- 2026-06-11: 🆕 added taxonomies mode to `AssertedCompositeId` and `AssertedCompositeIds`.
 ### 10.0.14
 - 2026-02-01: minor fix to pin target lookup component template.