@cratis/scene.engine 4.2.1 → 4.4.0

package/editing/validateValue.ts

@@ -0,0 +1,130 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CollectionItemDescriptor, PropertyDescriptor, PropertyValueType } from '@cratis/scene.model';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+    return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Checks a value against a property descriptor.
+ *
+ * @param descriptor The property the value is for.
+ * @param value The value to check. `undefined` means "not set", which is fine unless the property is required.
+ * @returns The reason the value is not acceptable, or `undefined` when it is.
+ */
+export function validateValue(descriptor: PropertyDescriptor, value: unknown): string | undefined {
+    const constraints = descriptor.constraints ?? {};
+    if (value === undefined || value === null) {
+        return constraints.required ? 'a value is required' : undefined;
+    }
+
+    switch (descriptor.valueType) {
+        case PropertyValueType.String: {
+            if (typeof value !== 'string') return 'expected a string';
+            if (constraints.minimumLength !== undefined && value.length < constraints.minimumLength) return `must be at least ${constraints.minimumLength} characters`;
+            if (constraints.maximumLength !== undefined && value.length > constraints.maximumLength) return `must be at most ${constraints.maximumLength} characters`;
+            if (constraints.pattern !== undefined && !new RegExp(`^(?:${constraints.pattern})$`).test(value)) return `must match ${constraints.pattern}`;
+            return undefined;
+        }
+
+        case PropertyValueType.Number: {
+            if (typeof value !== 'number' || !Number.isFinite(value)) return 'expected a number';
+            if (constraints.integer && !Number.isInteger(value)) return 'expected a whole number';
+            if (constraints.minimum !== undefined && value < constraints.minimum) return `must be at least ${constraints.minimum}`;
+            if (constraints.maximum !== undefined && value > constraints.maximum) return `must be at most ${constraints.maximum}`;
+            return undefined;
+        }
+
+        case PropertyValueType.Boolean:
+            return typeof value === 'boolean' ? undefined : 'expected true or false';
+
+        case PropertyValueType.Enum:
+            return (descriptor.choices ?? []).some(choice => choice.value === value) ? undefined : 'not one of the allowed choices';
+
+        case PropertyValueType.Icon:
+            if (!isRecord(value) || !isNonEmptyString(value.library) || !isNonEmptyString(value.key)) return 'expected an icon reference with a library and a key';
+            return value.variant === undefined || typeof value.variant === 'string' ? undefined : 'the icon variant must be a string';
+
+        case PropertyValueType.Destination:
+            if (!isRecord(value) || !isNonEmptyString(value.screen)) return 'expected a destination naming a screen';
+            return value.routeParameterBindings === undefined || isRecord(value.routeParameterBindings)
+                ? undefined
+                : 'routeParameterBindings must be an object';
+
+        case PropertyValueType.QueryReference:
+            if (isNonEmptyString(value)) return undefined;
+            if (!isRecord(value) || !isNonEmptyString(value.queryId) || !isNonEmptyString(value.query)) return 'expected a query name or a query binding';
+            return Array.isArray(value.arguments) && Array.isArray(value.results) ? undefined : 'a query binding needs arguments and results lists';
+
+        case PropertyValueType.Collection:
+            return validateCollection(descriptor, value);
+
+        default:
+            return isRecord(value) || Array.isArray(value) ? undefined : 'expected a structured value';
+    }
+}
+
+function validateCollection(descriptor: PropertyDescriptor, value: unknown): string | undefined {
+    if (!Array.isArray(value)) return 'expected a list';
+    const constraints = descriptor.constraints ?? {};
+    if (constraints.minimumItems !== undefined && value.length < constraints.minimumItems) return `needs at least ${constraints.minimumItems} items`;
+    if (constraints.maximumItems !== undefined && value.length > constraints.maximumItems) return `allows at most ${constraints.maximumItems} items`;
+
+    const identities = new Set<string>();
+    for (const item of value) {
+        if (!isRecord(item) || !isNonEmptyString(item.id)) return 'every item needs an id';
+        if (identities.has(item.id)) return `the item id '${item.id}' is used twice`;
+        identities.add(item.id);
+
+        const { id: _identity, ...values } = item;
+        const problem = validateItemValues(descriptor.item, values).at(0);
+        if (problem) return `item '${item.id}': ${problem.field} ${problem.problem}`;
+    }
+
+    return undefined;
+}
+
+/**
+ * One field of a collection item that does not fit its descriptor.
+ */
+export interface ItemFieldProblem {
+    field: string;
+    problem: string;
+}
+
+/**
+ * Checks a collection item's field values against the collection's item descriptor.
+ *
+ * @param itemDescriptor What the items look like.
+ * @param values The item's field values, keyed by field path.
+ * @returns Every field that is unknown or has an unacceptable value.
+ */
+export function validateItemValues(itemDescriptor: CollectionItemDescriptor | undefined, values: Record<string, unknown>): ItemFieldProblem[] {
+    const fields = itemDescriptor?.properties ?? [];
+    const problems: ItemFieldProblem[] = [];
+
+    for (const [field, fieldValue] of Object.entries(values)) {
+        const fieldDescriptor = fields.find(candidate => candidate.path === field);
+        if (!fieldDescriptor) {
+            problems.push({ field, problem: 'is not a field of this collection\'s items' });
+            continue;
+        }
+
+        const problem = validateValue(fieldDescriptor, fieldValue);
+        if (problem) problems.push({ field, problem });
+    }
+
+    for (const fieldDescriptor of fields) {
+        if (fieldDescriptor.constraints?.required && values[fieldDescriptor.path] === undefined) {
+            problems.push({ field: fieldDescriptor.path, problem: 'a value is required' });
+        }
+    }
+
+    return problems;
+}

package/icons/EffectiveIconCatalog.ts

@@ -0,0 +1,199 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconEntry, IconReference, formatIconReference } from '@cratis/scene.model';
+import { EffectiveIconEntry, referencesOfEntry } from './EffectiveIconEntry';
+import { IconCatalogSource } from './IconCatalogSource';
+import { IconDiagnostic } from './IconDiagnostic';
+import { IconLibraryResolution } from './IconLibraryResolution';
+import { IconQuery } from './IconQuery';
+import { IconResolution } from './IconResolution';
+import { IconSearchResult } from './IconSearchResult';
+import { ResolvedIconLibrary } from './ResolvedIconLibrary';
+import { matchesIconQuery } from './matchesIconQuery';
+
+/**
+ * The icons a profile can actually use: the active libraries from {@link resolveIconLibraries}, with their
+ * catalogs loaded on demand.
+ *
+ * Opening it costs nothing - no catalog is read until a query or a lookup needs that library, and a
+ * query narrowed to one library reads only that one. A catalog is loaded once and kept; a load that
+ * fails is not kept, so the next call tries again. Everything that goes wrong is reported as an
+ * {@link IconDiagnostic}; nothing is ever answered with a different icon than the one asked for.
+ */
+export class EffectiveIconCatalog {
+    readonly #sources: Map<string, IconCatalogSource>;
+    readonly #loads = new Map<string, Promise<IconEntry[]>>();
+    readonly #loadedEntries = new Map<string, IconEntry[]>();
+
+    /**
+     * @param resolution The active libraries and the problems found with them.
+     * @param sources The catalog source of each library; a library with none is active but reports
+     * 'catalog-unavailable' when its icons are needed.
+     */
+    constructor(readonly resolution: IconLibraryResolution, sources: IconCatalogSource[]) {
+        this.#sources = new Map(sources.map((source) => [source.library, source]));
+    }
+
+    /**
+     * The active libraries, with provenance.
+     */
+    get libraries(): ResolvedIconLibrary[] {
+        return this.resolution.libraries;
+    }
+
+    /**
+     * Problems with the libraries themselves, known without loading any catalog.
+     */
+    get diagnostics(): IconDiagnostic[] {
+        return this.resolution.diagnostics;
+    }
+
+    /**
+     * Whether a library's catalog has been read yet.
+     */
+    isLoaded(library: string): boolean {
+        return this.#loadedEntries.has(library);
+    }
+
+    /**
+     * The entries of one library, loading its catalog if this is the first time it is needed.
+     * Resolves to `undefined` when the library is not active.
+     *
+     * @throws Whatever the library's source throws, or an Error when an active library has no source.
+     */
+    async entriesOf(library: string): Promise<IconEntry[] | undefined> {
+        if (!this.libraries.some((resolved) => resolved.library === library)) return undefined;
+
+        let load = this.#loads.get(library);
+        if (!load) {
+            const source = this.#sources.get(library);
+            if (!source) throw new Error(`The icon library '${library}' is active but has no catalog source`);
+
+            load = source.loadEntries();
+            this.#loads.set(library, load);
+            load.then(
+                (entries) => this.#loadedEntries.set(library, entries),
+                () => this.#loads.delete(library)
+            );
+        }
+
+        return load;
+    }
+
+    /**
+     * Searches the catalogs of the libraries the query covers - all of them, or the one it names.
+     */
+    async search(query: IconQuery = {}): Promise<IconSearchResult> {
+        const covered = this.libraries.filter((resolved) => query.library === undefined || resolved.library === query.library);
+        const outcomes = await Promise.all(covered.map(async (resolved) => this.#entriesOrDiagnostic(resolved)));
+
+        const entries: EffectiveIconEntry[] = [];
+        const diagnostics: IconDiagnostic[] = [];
+        outcomes.forEach((outcome, position) => {
+            const library = covered[position];
+            if ('diagnostic' in outcome) {
+                diagnostics.push(outcome.diagnostic);
+                return;
+            }
+
+            for (const entry of outcome.entries.filter((candidate) => matchesIconQuery(candidate, query))) {
+                entries.push({ library, entry, references: referencesOfEntry(library.library, entry) });
+            }
+        });
+
+        return { entries, diagnostics };
+    }
+
+    /**
+     * Every active library's icons whose name or key is exactly `name` (ignoring case) - the several
+     * candidates a bare legacy icon name could have meant. More than one is a real answer, not a tie to
+     * break: it is the author's decision which library the icon comes from.
+     */
+    async findByName(name: string): Promise<EffectiveIconEntry[]> {
+        const wanted = name.trim().toLowerCase();
+        const { entries } = await this.search({});
+        return entries.filter(({ entry }) => entry.key.toLowerCase() === wanted || entry.name.toLowerCase() === wanted);
+    }
+
+    /**
+     * The categories in use, sorted, across all libraries or one.
+     */
+    async categories(library?: string): Promise<string[]> {
+        const { entries } = await this.search({ library });
+        return [...new Set(entries.flatMap(({ entry }) => entry.categories))].sort();
+    }
+
+    /**
+     * Looks a reference up: the icon it names, or exactly why there is none.
+     */
+    async resolve(reference: IconReference): Promise<IconResolution> {
+        const library = this.libraries.find((resolved) => resolved.library === reference.library);
+        if (library && !this.isLoaded(library.library) && !this.#incompatibility(library)) {
+            const outcome = await this.#entriesOrDiagnostic(library);
+            if ('diagnostic' in outcome) return { isResolved: false, reference, diagnostic: { ...outcome.diagnostic, reference } };
+        }
+
+        return this.lookup(reference) as IconResolution;
+    }
+
+    /**
+     * Looks a reference up without loading anything, for callers that cannot wait - an edit is applied
+     * synchronously. Resolves everything that is decidable from what is already known: a library that is not
+     * active, one at an incompatible version, and - once the library's catalog has been loaded - a missing
+     * icon or variant.
+     *
+     * @returns The resolution, or `undefined` when the library is active but its catalog has not been loaded,
+     * so nothing can be said about the icon yet. Call {@link load} first to make the answer definite.
+     */
+    lookup(reference: IconReference): IconResolution | undefined {
+        const library = this.libraries.find((resolved) => resolved.library === reference.library);
+        if (!library) {
+            return this.#unresolved(reference, 'missing-library', `The icon library '${reference.library}' is not active in this profile`);
+        }
+
+        const incompatible = this.#incompatibility(library);
+        if (incompatible) return { isResolved: false, reference, diagnostic: { ...incompatible, reference } };
+
+        const entries = this.#loadedEntries.get(library.library);
+        if (!entries) return undefined;
+
+        const entry = entries.find((candidate) => candidate.key === reference.key);
+        if (!entry) {
+            return this.#unresolved(reference, 'missing-icon', `The icon library '${library.library}' has no icon '${reference.key}'`);
+        }
+
+        if (reference.variant !== undefined && !(entry.variants ?? []).includes(reference.variant)) {
+            return this.#unresolved(reference, 'missing-variant', `The icon '${formatIconReference({ library: library.library, key: entry.key })}' has no '${reference.variant}' variant`);
+        }
+
+        return { isResolved: true, reference, library, entry };
+    }
+
+    /**
+     * Loads the catalogs of one library, or of every active library, so that {@link lookup} can answer
+     * definitely. Libraries whose catalog cannot be loaded are reported, not thrown.
+     */
+    async load(library?: string): Promise<IconDiagnostic[]> {
+        const covered = this.libraries.filter((resolved) => library === undefined || resolved.library === library);
+        const outcomes = await Promise.all(covered.map(async (resolved) => this.#entriesOrDiagnostic(resolved)));
+        return outcomes.flatMap((outcome) => ('diagnostic' in outcome ? [outcome.diagnostic] : []));
+    }
+
+    #incompatibility(library: ResolvedIconLibrary): IconDiagnostic | undefined {
+        return this.diagnostics.find((diagnostic) => diagnostic.kind === 'incompatible-version' && diagnostic.library === library.library);
+    }
+
+    async #entriesOrDiagnostic(library: ResolvedIconLibrary): Promise<{ entries: IconEntry[] } | { diagnostic: IconDiagnostic }> {
+        try {
+            return { entries: (await this.entriesOf(library.library)) ?? [] };
+        } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return { diagnostic: { kind: 'catalog-unavailable', library: library.library, message: `The catalog of '${library.library}' could not be loaded: ${reason}` } };
+        }
+    }
+
+    #unresolved(reference: IconReference, kind: IconDiagnostic['kind'], message: string): IconResolution & { isResolved: false } {
+        return { isResolved: false, reference, diagnostic: { kind, library: reference.library, message, reference } };
+    }
+}

package/icons/EffectiveIconEntry.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconEntry, IconReference } from '@cratis/scene.model';
+import { ResolvedIconLibrary } from './ResolvedIconLibrary';
+
+/**
+ * An icon as a picker shows it: the catalog entry, the library that provides it (so provenance and
+ * attribution are one step away), and the references that name it.
+ */
+export interface EffectiveIconEntry {
+    /**
+     * The active library that provides the icon.
+     */
+    library: ResolvedIconLibrary;
+
+    /**
+     * The catalog entry.
+     */
+    entry: IconEntry;
+
+    /**
+     * One reference per variant the icon exists in, or the single variant-less reference when it has none.
+     */
+    references: IconReference[];
+}
+
+/**
+ * The references that name an entry of a library: one per variant, or one without a variant.
+ */
+export function referencesOfEntry(library: string, entry: IconEntry): IconReference[] {
+    const variants = entry.variants ?? [];
+    return variants.length === 0
+        ? [{ library, key: entry.key }]
+        : variants.map((variant) => ({ library, key: entry.key, variant }));
+}

package/icons/IconCatalogSource.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconEntry } from '@cratis/scene.model';
+
+/**
+ * Where one icon library's catalog comes from. The library's module provides it; the engine only asks
+ * for it when something needs the library's icons, so resolving a profile never loads a catalog.
+ *
+ * A source supplies metadata only. The artwork for each icon is loaded separately, per icon, by the
+ * renderer's adapter for the library.
+ */
+export interface IconCatalogSource {
+    /**
+     * The library the catalog belongs to.
+     */
+    library: string;
+
+    /**
+     * Loads the library's icon entries. Called at most once per successful load.
+     */
+    loadEntries(): Promise<IconEntry[]>;
+}

package/icons/IconDiagnostic.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconReference } from '@cratis/scene.model';
+
+/**
+ * What can be wrong with an icon library or an icon reference. Each is a distinct, reportable condition -
+ * none of them is ever resolved by quietly substituting another icon.
+ */
+export type IconDiagnosticKind =
+    /** The reference names a library that is not active in the profile. */
+    | 'missing-library'
+    /** The library is active but its catalog has no icon with the reference's key. */
+    | 'missing-icon'
+    /** The icon exists but not in the variant the reference asks for. */
+    | 'missing-variant'
+    /** The library is active but at a version a package that needs it does not accept. */
+    | 'incompatible-version'
+    /** The library is active but its catalog could not be loaded. */
+    | 'catalog-unavailable';
+
+/**
+ * One finding about an icon library or reference, carrying enough to explain it to an author.
+ */
+export interface IconDiagnostic {
+    /**
+     * What kind of problem this is.
+     */
+    kind: IconDiagnosticKind;
+
+    /**
+     * The library the finding is about.
+     */
+    library: string;
+
+    /**
+     * A sentence an author can act on.
+     */
+    message: string;
+
+    /**
+     * The reference the finding is about, when it is about one reference rather than a whole library.
+     */
+    reference?: IconReference;
+}

package/icons/IconImpactReport.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EffectiveIconEntry } from './EffectiveIconEntry';
+import { IconDiagnostic } from './IconDiagnostic';
+import { IconUsage } from './IconUsage';
+
+/**
+ * A reference the proposed change would leave without an icon.
+ */
+export interface AffectedIconUsage {
+    /**
+     * The usage that would break.
+     */
+    usage: IconUsage;
+
+    /**
+     * Why it would no longer resolve.
+     */
+    diagnostic: IconDiagnostic;
+
+    /**
+     * Whether it resolved before the change. `false` marks a reference that was already broken, so a
+     * report can tell new damage from old.
+     */
+    wasResolvable: boolean;
+}
+
+/**
+ * A legacy bare icon string the report leaves untouched, with the icons it could be migrated to.
+ */
+export interface LegacyIconUsage {
+    /**
+     * The usage holding the legacy string.
+     */
+    usage: IconUsage;
+
+    /**
+     * The icons in the proposed catalog whose name or key equals the string. Empty means nothing to
+     * migrate to; more than one means the author has to choose a library.
+     */
+    candidates: EffectiveIconEntry[];
+}
+
+/**
+ * What a library change would do to a set of persisted icon values. It describes; it never rewrites.
+ */
+export interface IconImpactReport {
+    /**
+     * References that resolve now (or did) and would not after the change.
+     */
+    affected: AffectedIconUsage[];
+
+    /**
+     * How many references resolve after the change.
+     */
+    unaffectedCount: number;
+
+    /**
+     * Legacy strings, which are neither affected nor rewritten by a library change.
+     */
+    legacy: LegacyIconUsage[];
+}

package/icons/IconLibraryResolution.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconDiagnostic } from './IconDiagnostic';
+import { ResolvedIconLibrary } from './ResolvedIconLibrary';
+
+/**
+ * The icon libraries a set of packages makes active, and what is wrong with them.
+ */
+export interface IconLibraryResolution {
+    /**
+     * Every active icon library - selected or required transitively - in the dependency order of
+     * {@link resolvePackageDependencies}. Order carries no precedence: libraries coexist, and the library
+     * is part of every icon's identity.
+     */
+    libraries: ResolvedIconLibrary[];
+
+    /**
+     * Problems with the libraries themselves, such as a version a dependent does not accept.
+     */
+    diagnostics: IconDiagnostic[];
+}

package/icons/IconQuery.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a picker asks the effective catalog for. Every field narrows; an empty query returns everything.
+ */
+export interface IconQuery {
+    /**
+     * Free text, matched case-insensitively against each icon's name, key, aliases and tags.
+     */
+    text?: string;
+
+    /**
+     * Only the icons of this library. Narrowing to one library also means only that library's catalog is loaded.
+     */
+    library?: string;
+
+    /**
+     * Only the icons filed under this category.
+     */
+    category?: string;
+
+    /**
+     * Only the icons that exist in this variant.
+     */
+    variant?: string;
+}

package/icons/IconResolution.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconEntry, IconReference } from '@cratis/scene.model';
+import { IconDiagnostic } from './IconDiagnostic';
+import { ResolvedIconLibrary } from './ResolvedIconLibrary';
+
+/**
+ * The outcome of looking one reference up in the effective catalog: either the icon it names, or the
+ * precise reason there is none.
+ */
+export type IconResolution =
+    | {
+          /** The reference resolved. */
+          isResolved: true;
+          reference: IconReference;
+          library: ResolvedIconLibrary;
+          entry: IconEntry;
+      }
+    | {
+          /** The reference did not resolve. */
+          isResolved: false;
+          reference: IconReference;
+          diagnostic: IconDiagnostic;
+      };

package/icons/IconSearchResult.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EffectiveIconEntry } from './EffectiveIconEntry';
+import { IconDiagnostic } from './IconDiagnostic';
+
+/**
+ * The outcome of querying the effective catalog.
+ */
+export interface IconSearchResult {
+    /**
+     * The icons that matched, library by library in resolution order and in each catalog's own order.
+     */
+    entries: EffectiveIconEntry[];
+
+    /**
+     * Libraries whose catalog could not be loaded and so contributed nothing - reported rather than
+     * dropped, so an absent icon is never mistaken for one that does not exist.
+     */
+    diagnostics: IconDiagnostic[];
+}

package/icons/IconUsage.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconReference } from '@cratis/scene.model';
+
+/**
+ * One place an icon is used - a persisted value somewhere in a screen, template, blueprint or profile.
+ */
+export interface IconUsage {
+    /**
+     * The icon value as persisted: an {@link IconReference}, or a legacy bare string (an icon font class
+     * such as `pi pi-home`) from before icons were library-qualified.
+     */
+    value: IconReference | string;
+
+    /**
+     * Where the value lives, in whatever terms the caller wants reported back (a screen name, a path).
+     * Never interpreted.
+     */
+    location?: string;
+}

package/icons/ResolvedIconLibrary.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ScenePackage } from '@cratis/scene.model';
+
+/**
+ * An icon library that is active in a profile, with the reason it is.
+ */
+export interface ResolvedIconLibrary {
+    /**
+     * The library's identity - what an {@link IconReference.library} names.
+     */
+    library: string;
+
+    /**
+     * The package declaration behind the library: version, license, attribution, renderers.
+     */
+    package: ScenePackage;
+
+    /**
+     * Whether the profile lists the library itself. `false` means it is only active because something
+     * else needs it.
+     */
+    isSelected: boolean;
+
+    /**
+     * The names of the active packages that declare a dependency on the library. Together with
+     * {@link isSelected} this is the library's provenance: why it is here, and what stops depending on it
+     * when it is removed.
+     */
+    requiredBy: string[];
+}