@cratis/scene.engine 4.3.0 → 4.4.0

package/editing/EditingContext.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { EditingScope, QueryCandidate } from '@cratis/scene.model';
+import { EffectiveIconCatalog } from '../icons/EffectiveIconCatalog';
 import { DescriptorCatalog } from './DescriptorCatalog';
 
 /**
@@ -20,4 +21,14 @@ export interface EditingContext {
      * edited it is checked against these; without them it is checked for shape only.
      */
     queryCandidates?: QueryCandidate[];
+
+    /**
+     * The icons the profile can use. When present, an icon value that is edited is checked against it - a
+     * library the profile lacks, an icon the library no longer has, a library at an incompatible version -
+     * and inspection reports the same problems for values already stored, which are kept either way.
+     * Without it an icon value is checked for shape only. An edit is applied synchronously, so
+     * `await iconCatalog.load()` first for definite answers about icons and variants; until a library's
+     * catalog is loaded its icons are reported as not verified.
+     */
+    iconCatalog?: EffectiveIconCatalog;
 }

package/editing/collectIconUsages.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InstanceContribution, PropertyDescriptor, PropertyValueType, SceneDocument } from '@cratis/scene.model';
+import { IconUsage } from '../icons/IconUsage';
+import { collectComponents } from './collectComponents';
+import { DescriptorCatalog, findComponentDescriptor } from './DescriptorCatalog';
+import { getValueAtPath } from './pathAccess';
+
+function iconFields(property: PropertyDescriptor): string[] {
+    return (property.item?.properties ?? []).filter((field) => field.valueType === PropertyValueType.Icon).map((field) => field.path);
+}
+
+function usagesOf(property: PropertyDescriptor, value: unknown, items: { id: string; values: Record<string, unknown> }[] | undefined, location: string): IconUsage[] {
+    if (property.valueType === PropertyValueType.Icon) {
+        return value === undefined ? [] : [{ value: value as IconUsage['value'], location: `${location}:${property.path}` }];
+    }
+
+    return property.valueType === PropertyValueType.Collection
+        ? (items ?? []).flatMap((item) =>
+              iconFields(property)
+                  .filter((field) => item.values[field] !== undefined)
+                  .map((field) => ({ value: item.values[field] as IconUsage['value'], location: `${location}:${property.path}:${item.id}:${field}` })))
+        : [];
+}
+
+function ownerItems(value: unknown): { id: string; values: Record<string, unknown> }[] {
+    return (Array.isArray(value) ? value : [])
+        .filter((item): item is Record<string, unknown> => item !== null && typeof item === 'object')
+        .map(({ id, ...values }) => ({ id: String(id), values }));
+}
+
+/**
+ * Finds every icon value stored anywhere in a document - the values components carry themselves, and the values
+ * and collection-item icon fields that template instances contributed - as the `IconUsage`s that
+ * `analyzeIconImpact` takes, so "what would removing this library break" can be asked of a whole document.
+ *
+ * Each usage's `location` reads `<owner or instance>:<component>:<path>[:<itemId>:<field>]`, where the first part is
+ * the contributing instance id (`screen:Orders`) for a contributed value and the name of the owning layout or
+ * template for a value the component carries. Values are read as stored; none are changed.
+ *
+ * @param document The document to read.
+ * @param catalog The descriptors saying which properties are icons.
+ */
+export function collectIconUsages(document: SceneDocument, catalog: DescriptorCatalog): IconUsage[] {
+    const usages: IconUsage[] = [];
+    const componentNames = new Map<string, string>();
+
+    const owners: { name: string; value: unknown }[] = [
+        ...document.layouts.map((layout) => ({ name: layout.name, value: layout })),
+        ...document.screenTemplates.map((template) => ({ name: template.name, value: template })),
+        ...document.dialogTemplates.map((template) => ({ name: template.name, value: template })),
+        ...document.screens.map((screen) => ({ name: screen.name, value: screen })),
+    ];
+
+    for (const owner of owners) {
+        for (const component of collectComponents(owner.value)) {
+            if (!componentNames.has(component.id)) componentNames.set(component.id, component.componentName);
+
+            for (const property of findComponentDescriptor(catalog, component.componentName)?.properties ?? []) {
+                const value = getValueAtPath(component.properties, property.path);
+                usages.push(...usagesOf(property, value, ownerItems(value), `${owner.name}:${component.id}`));
+            }
+        }
+    }
+
+    for (const contribution of document.instanceContributions) {
+        const componentName = componentNames.get(contribution.component);
+        const property = componentName === undefined ? undefined : findComponentDescriptor(catalog, componentName)?.properties.find((candidate) => candidate.path === contribution.path);
+        if (property) usages.push(...contributedUsages(property, contribution));
+    }
+
+    return usages;
+}
+
+function contributedUsages(property: PropertyDescriptor, contribution: InstanceContribution): IconUsage[] {
+    return usagesOf(property, contribution.value, contribution.items, `${contribution.instance}:${contribution.component}`);
+}

package/editing/diagnoseIcons.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DiagnosticSeverity, PropertyDescriptor, PropertyValueType, SceneDiagnostic, SceneDocument } from '@cratis/scene.model';
+import { findComponentDescriptor } from './DescriptorCatalog';
+import { EditingContext } from './EditingContext';
+import { iconProblemsOfItems, iconProblemsOfProperty } from './iconDiagnostics';
+import { getValueAtPath } from './pathAccess';
+import { resolveEffectiveConfiguration } from './resolveEffectiveConfiguration';
+import { resolveTemplateChain } from './resolveTemplateChain';
+
+function isIconBearing(property: PropertyDescriptor): boolean {
+    return property.valueType === PropertyValueType.Icon
+        || (property.valueType === PropertyValueType.Collection && (property.item?.properties ?? []).some((field) => field.valueType === PropertyValueType.Icon));
+}
+
+/**
+ * Reports every icon in what the editing scope renders - the template chain's own values and what each instance
+ * contributed - that the profile's icon catalog cannot supply: a library the profile lacks, an icon or variant a
+ * library no longer has, a library at an incompatible version.
+ *
+ * It reports; it never changes anything. The offending values stay in the document, still applied (a renderer
+ * shows its fallback), and apply again as soon as the icon is available, so removing a library is reversible.
+ * Each diagnostic names the component, property, collection item and - for a contributed value - the instance.
+ *
+ * Returns nothing when the context carries no `iconCatalog`. Load the catalogs first (`iconCatalog.load()`) for
+ * definite answers; an icon from an unloaded library is reported as not verified.
+ */
+export function diagnoseIcons(document: SceneDocument, context: EditingContext): SceneDiagnostic[] {
+    const iconCatalog = context.iconCatalog;
+    if (!iconCatalog) return [];
+
+    const chain = resolveTemplateChain(document, context.scope);
+    const configuration = resolveEffectiveConfiguration(chain, document.instanceContributions, context.catalog);
+    const diagnostics: SceneDiagnostic[] = [];
+
+    for (const level of chain.levels) {
+        for (const element of level.elements) {
+            const descriptor = findComponentDescriptor(context.catalog, element.componentName);
+            const configured = configuration.components.find((candidate) => candidate.component === element.id);
+
+            for (const property of (descriptor?.properties ?? []).filter(isIconBearing)) {
+                const effective = configured?.values.find((candidate) => candidate.path === property.path);
+                const where = { component: element.id, ...(effective?.contributedBy === undefined ? {} : { instance: effective.contributedBy }) };
+
+                if (property.valueType === PropertyValueType.Icon) {
+                    const value = effective ? effective.value : getValueAtPath(element.properties, property.path);
+                    diagnostics.push(...iconProblemsOfProperty(iconCatalog, property, value, DiagnosticSeverity.Warning, where));
+                } else if (effective?.items) {
+                    const items = effective.items.map((item) => ({ id: item.id, values: item.values, instance: item.origin === 'owner' ? undefined : item.origin }));
+                    diagnostics.push(...iconProblemsOfItems(iconCatalog, property.item, items, DiagnosticSeverity.Warning, { component: element.id, path: property.path }));
+                } else {
+                    diagnostics.push(...iconProblemsOfProperty(iconCatalog, property, getValueAtPath(element.properties, property.path), DiagnosticSeverity.Warning, where));
+                }
+            }
+        }
+    }
+
+    return diagnostics;
+}

package/editing/iconDiagnostics.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CollectionItemDescriptor, DiagnosticCode, DiagnosticSeverity, PropertyDescriptor, PropertyValueType, SceneDiagnostic, isIconReference } from '@cratis/scene.model';
+import { EffectiveIconCatalog } from '../icons/EffectiveIconCatalog';
+import { IconDiagnosticKind } from '../icons/IconDiagnostic';
+import { DiagnosticContext } from './diagnostics';
+
+const codes: Record<IconDiagnosticKind, DiagnosticCode> = {
+    'missing-library': DiagnosticCode.MissingIconLibrary,
+    'missing-icon': DiagnosticCode.MissingIcon,
+    'missing-variant': DiagnosticCode.MissingIconVariant,
+    'incompatible-version': DiagnosticCode.IncompatibleIconLibrary,
+    'catalog-unavailable': DiagnosticCode.IconCatalogUnavailable,
+};
+
+/**
+ * Checks one icon value against the effective icon catalog.
+ *
+ * Nothing is rewritten or dropped: this only reports. A value whose library, icon or variant is missing, or
+ * whose library is at an incompatible version, produces a diagnostic of the given severity - an error when
+ * the value is being *set* (the edit is refused), a warning when it is already stored (it is kept, and
+ * applies again if the icon comes back). A value that cannot be judged yet, because its library's catalog has
+ * not been loaded, produces an `IconNotVerified` warning rather than silently passing.
+ *
+ * @param catalog The effective catalog of the profile being edited.
+ * @param value The value; anything that is not an icon reference is left to `validateValue`.
+ * @param severity How serious a definite problem is.
+ * @param context What the diagnostic is about.
+ */
+export function iconProblem(catalog: EffectiveIconCatalog, value: unknown, severity: DiagnosticSeverity, context: DiagnosticContext): SceneDiagnostic | undefined {
+    if (!isIconReference(value)) return undefined;
+
+    const resolution = catalog.lookup(value);
+    if (resolution === undefined) {
+        return {
+            code: DiagnosticCode.IconNotVerified,
+            severity: DiagnosticSeverity.Warning,
+            message: `The catalog of the icon library '${value.library}' is not loaded, so '${value.key}' could not be verified.`,
+            ...context,
+        };
+    }
+
+    return resolution.isResolved ? undefined : { code: codes[resolution.diagnostic.kind], severity, message: `${resolution.diagnostic.message}.`, ...context };
+}
+
+/**
+ * Checks the icon fields of collection items.
+ *
+ * @param itemDescriptor What the items look like.
+ * @param items The items, each with its id and field values.
+ */
+export function iconProblemsOfItems(
+    catalog: EffectiveIconCatalog,
+    itemDescriptor: CollectionItemDescriptor | undefined,
+    items: { id: string; values: Record<string, unknown>; instance?: string }[],
+    severity: DiagnosticSeverity,
+    context: DiagnosticContext
+): SceneDiagnostic[] {
+    const iconFields = (itemDescriptor?.properties ?? []).filter((field) => field.valueType === PropertyValueType.Icon);
+    return items.flatMap((item) =>
+        iconFields.flatMap((field) => {
+            const problem = iconProblem(catalog, item.values[field.path], severity, { ...context, itemId: item.id, ...(item.instance === undefined ? {} : { instance: item.instance }) });
+            return problem ? [{ ...problem, message: `'${field.label}' of '${item.id}': ${problem.message}` }] : [];
+        })
+    );
+}
+
+/**
+ * Checks a property's value - an icon, or a collection whose items have icon fields - against the effective icon
+ * catalog. Any other kind of property has nothing to check.
+ *
+ * @param descriptor The property.
+ * @param value The value; for a collection, the flat items (`{ id, ...fields }`) as they are stored.
+ */
+export function iconProblemsOfProperty(catalog: EffectiveIconCatalog, descriptor: PropertyDescriptor, value: unknown, severity: DiagnosticSeverity, context: DiagnosticContext): SceneDiagnostic[] {
+    if (descriptor.valueType === PropertyValueType.Icon) {
+        const problem = iconProblem(catalog, value, severity, { ...context, path: descriptor.path });
+        return problem ? [{ ...problem, message: `'${descriptor.label}': ${problem.message}` }] : [];
+    }
+
+    if (descriptor.valueType === PropertyValueType.Collection && Array.isArray(value)) {
+        const items = value
+            .filter((item): item is Record<string, unknown> => item !== null && typeof item === 'object')
+            .map(({ id, ...values }) => ({ id: String(id), values }));
+        return iconProblemsOfItems(catalog, descriptor.item, items, severity, { ...context, path: descriptor.path });
+    }
+
+    return [];
+}

package/editing/index.ts

@@ -19,3 +19,6 @@ export * from './EditingContext';
 export * from './inspect';
 export * from './EditOutcome';
 export * from './applyEdit';
+export * from './iconDiagnostics';
+export * from './diagnoseIcons';
+export * from './collectIconUsages';

package/editing/inspect.ts

@@ -2,12 +2,14 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import {
-    DiagnosticCode, EditTarget, InspectedCollectionItem, InspectedProperty, NodeInspection,
+    DiagnosticCode, DiagnosticSeverity, EditTarget, InspectedCollectionItem, InspectedProperty, NodeInspection,
     NodeProvenance, ProvenanceKind, PropertyDescriptor, PropertyValueType, SceneDiagnostic, SceneDocument, SceneNodeKind, ValueSource,
 } from '@cratis/scene.model';
 import { describeNode, readNodeValue } from './describeNode';
+import { EffectiveIconCatalog } from '../icons/EffectiveIconCatalog';
 import { EditingContext } from './EditingContext';
 import { computeExposureGrants, ExposureGrant, grantKey } from './exposureGrants';
+import { iconProblemsOfItems, iconProblemsOfProperty } from './iconDiagnostics';
 import { indexDocument } from './indexDocument';
 import { NodeRecord } from './DocumentIndex';
 import { resolveEffectiveConfiguration } from './resolveEffectiveConfiguration';
@@ -90,6 +92,22 @@ function inspectProperty(
     return inspected;
 }
 
+/**
+ * Reports icons the profile cannot supply - on the node itself and in configuration contributed to it. The values
+ * stay where they are; these are warnings.
+ */
+function iconDiagnosticsOf(properties: InspectedProperty[], iconCatalog: EffectiveIconCatalog, nodeId: string): SceneDiagnostic[] {
+    return properties.flatMap(property => {
+        const descriptor = property.descriptor;
+        if (descriptor.valueType !== PropertyValueType.Collection) {
+            return iconProblemsOfProperty(iconCatalog, descriptor, property.effectiveValue, DiagnosticSeverity.Warning, { nodeId });
+        }
+
+        const items = (property.items ?? []).map(item => ({ id: item.id, values: item.values, instance: item.origin === 'owner' ? undefined : item.origin }));
+        return iconProblemsOfItems(iconCatalog, descriptor.item, items, DiagnosticSeverity.Warning, { nodeId, path: descriptor.path });
+    });
+}
+
 /**
  * Describes one node for an editor: what it is, where it comes from, what can be edited on it - with current and
  * effective values and effective editability - and what can be done with it.
@@ -127,6 +145,11 @@ export function inspect(document: SceneDocument, nodeId: string, context: Editin
         diagnostics.push(...chain.diagnostics.filter(diagnostic => diagnostic.code === DiagnosticCode.UnknownScope));
     }
 
+    const properties = description.properties.map(descriptor => inspectProperty(descriptor, record, provenance, scopeInstance, scopeGrants, configuredValues));
+    if (context.iconCatalog) {
+        diagnostics.push(...iconDiagnosticsOf(properties, context.iconCatalog, nodeId));
+    }
+
     return {
         nodeId,
         kind: record.kind,
@@ -134,7 +157,7 @@ export function inspect(document: SceneDocument, nodeId: string, context: Editin
         label: record.label,
         parentId: record.parentId,
         provenance,
-        properties: description.properties.map(descriptor => inspectProperty(descriptor, record, provenance, scopeInstance, scopeGrants, configuredValues)),
+        properties,
         capabilities: description.capabilities,
         removable: isRemovable(record, provenance),
         diagnostics,

package/editing/instanceEdits.ts

@@ -2,11 +2,12 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import {
-    AddCollectionItemEdit, CollectionOperation, ContributedItem, DiagnosticCode, EditCollectionItemEdit, InstanceContribution,
+    AddCollectionItemEdit, CollectionOperation, ContributedItem, DiagnosticCode, DiagnosticSeverity, EditCollectionItemEdit, InstanceContribution,
     PropertyValueType, RemoveCollectionItemEdit, ReorderCollectionItemEdit, ResetInstanceValueEdit, SceneDiagnostic,
     SceneDocument, SetInstanceValueEdit,
 } from '@cratis/scene.model';
-import { errorDiagnostic } from './diagnostics';
+import { errorDiagnostic, hasErrors } from './diagnostics';
+import { iconProblemsOfItems } from './iconDiagnostics';
 import { EditSession } from './EditSession';
 import { ExposureGrant, grantKey } from './exposureGrants';
 import { cloneData } from './pathAccess';
@@ -66,7 +67,7 @@ function permitted(grant: ExposureGrant, operation: CollectionOperation, instanc
     return true;
 }
 
-function checkFields(grant: ExposureGrant, values: Record<string, unknown>, itemId: string, instance: string, diagnostics: SceneDiagnostic[], requireAll: boolean): boolean {
+function checkFields(session: EditSession, grant: ExposureGrant, values: Record<string, unknown>, itemId: string, instance: string, diagnostics: SceneDiagnostic[], requireAll: boolean): boolean {
     const context = { instance, component: grant.component, path: grant.path, itemId };
     let valid = true;
 
@@ -88,6 +89,13 @@ function checkFields(grant: ExposureGrant, values: Record<string, unknown>, item
         valid = false;
     }
 
+    const icons = session.context.iconCatalog;
+    if (icons && valid) {
+        const iconProblems = iconProblemsOfItems(icons, itemDescriptor, [{ id: itemId, values }], DiagnosticSeverity.Error, context);
+        diagnostics.push(...iconProblems);
+        valid = !hasErrors(iconProblems);
+    }
+
     return valid;
 }
 
@@ -163,7 +171,7 @@ export function applyAddCollectionItem(session: EditSession, edit: AddCollection
         return;
     }
 
-    if (!checkFields(grant, edit.item.values, edit.item.id, instance, diagnostics, true)) return;
+    if (!checkFields(session, grant, edit.item.values, edit.item.id, instance, diagnostics, true)) return;
 
     const { contribution, items } = ownItems(clone, instance, grant);
     if (edit.index !== undefined && (!Number.isInteger(edit.index) || edit.index < 0 || edit.index > items.length)) {
@@ -236,7 +244,7 @@ export function applyEditCollectionItem(session: EditSession, edit: EditCollecti
     const position = findOwnItem(items, edit.itemId, resolved.instance, resolved.grant, session, diagnostics);
     if (position < 0) return;
 
-    if (!checkFields(resolved.grant, { [edit.field]: edit.value }, edit.itemId, resolved.instance, diagnostics, false)) return;
+    if (!checkFields(session, resolved.grant, { [edit.field]: edit.value }, edit.itemId, resolved.instance, diagnostics, false)) return;
 
     const next = items.map((item, index) => index === position ? { ...item, values: { ...item.values, [edit.field]: cloneData(edit.value) } } : item);
     save(clone, resolved.instance, resolved.grant, contribution, next);

package/editing/propertyEdits.ts

@@ -2,14 +2,15 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import {
-    DiagnosticCode, PropertyDescriptor, PropertyValueType, QueryBinding, ResetPropertyEdit, SceneDiagnostic, SceneDocument,
+    DiagnosticCode, DiagnosticSeverity, PropertyDescriptor, PropertyValueType, QueryBinding, ResetPropertyEdit, SceneDiagnostic, SceneDocument,
     SceneNodeKind, SetPropertyEdit,
 } from '@cratis/scene.model';
 import { describeNode } from './describeNode';
-import { errorDiagnostic } from './diagnostics';
+import { errorDiagnostic, hasErrors } from './diagnostics';
 import { NodeRecord } from './DocumentIndex';
 import { getAtPath, mirroredPaths } from './documentPaths';
 import { EditSession } from './EditSession';
+import { iconProblemsOfProperty } from './iconDiagnostics';
 import { cloneData, removeValueAtPath, setValueAtPath } from './pathAccess';
 import { validateBinding } from './validateBinding';
 import { validateValue } from './validateValue';
@@ -75,6 +76,13 @@ export function checkValue(session: EditSession, descriptor: PropertyDescriptor,
         return problems.length === 0;
     }
 
+    const icons = session.context.iconCatalog;
+    if (icons) {
+        const problems = iconProblemsOfProperty(icons, descriptor, value, DiagnosticSeverity.Error, context);
+        diagnostics.push(...problems);
+        return !hasErrors(problems);
+    }
+
     return true;
 }
 

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 }));
+}