@cratis/scene.engine 4.3.0 → 4.5.0

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[];
+}

package/icons/analyzeIconImpact.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { isIconReference } from '@cratis/scene.model';
+import { AffectedIconUsage, IconImpactReport, LegacyIconUsage } from './IconImpactReport';
+import { EffectiveIconCatalog } from './EffectiveIconCatalog';
+import { IconUsage } from './IconUsage';
+
+/**
+ * Reports what changing a profile's icon libraries - removing one, upgrading one to a version that dropped
+ * icons, swapping one - would do to icon values already persisted, without touching them.
+ *
+ * Build `proposed` from the packages the profile would have after the change (with
+ * {@link resolveIconLibraries} and that package set's catalog sources) and compare it with the `current`
+ * one. A reference is *affected* when it does not resolve in `proposed`; `wasResolvable` says whether it did in
+ * `current`. Legacy bare strings are listed with the icons in `proposed` that share their name, but are never
+ * counted as affected and never rewritten - migrating them is an author's decision, one reference at a time.
+ */
+export async function analyzeIconImpact(usages: IconUsage[], current: EffectiveIconCatalog, proposed: EffectiveIconCatalog): Promise<IconImpactReport> {
+    const affected: AffectedIconUsage[] = [];
+    const legacy: LegacyIconUsage[] = [];
+    let unaffectedCount = 0;
+
+    for (const usage of usages) {
+        if (!isIconReference(usage.value)) {
+            legacy.push({ usage, candidates: await proposed.findByName(String(usage.value)) });
+            continue;
+        }
+
+        const after = await proposed.resolve(usage.value);
+        if (after.isResolved) {
+            unaffectedCount++;
+            continue;
+        }
+
+        const before = await current.resolve(usage.value);
+        affected.push({ usage, diagnostic: after.diagnostic, wasResolvable: before.isResolved });
+    }
+
+    return { affected, unaffectedCount, legacy };
+}

package/icons/index.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './IconDiagnostic';
+export * from './ResolvedIconLibrary';
+export * from './IconLibraryResolution';
+export * from './resolveIconLibraries';
+export * from './IconCatalogSource';
+export * from './EffectiveIconEntry';
+export * from './IconQuery';
+export * from './IconSearchResult';
+export * from './IconResolution';
+export * from './EffectiveIconCatalog';
+export * from './IconUsage';
+export * from './IconImpactReport';
+export * from './analyzeIconImpact';

package/icons/matchesIconQuery.ts

@@ -0,0 +1,19 @@
+// 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';
+import { IconQuery } from './IconQuery';
+
+/**
+ * Whether a catalog entry satisfies the entry-level parts of a query - text, category and variant. The
+ * library part is decided earlier, because it decides which catalogs get loaded at all.
+ */
+export function matchesIconQuery(entry: IconEntry, query: IconQuery): boolean {
+    if (query.category !== undefined && !entry.categories.includes(query.category)) return false;
+    if (query.variant !== undefined && !(entry.variants ?? []).includes(query.variant)) return false;
+
+    const text = query.text?.trim().toLowerCase();
+    if (!text) return true;
+
+    return [entry.name, entry.key, ...(entry.aliases ?? []), ...(entry.tags ?? [])].some((term) => term.toLowerCase().includes(text));
+}

package/icons/resolveIconLibraries.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind, ScenePackage } from '@cratis/scene.model';
+import { resolvePackageDependencies } from '../resolvePackageDependencies';
+import { IconDiagnostic } from './IconDiagnostic';
+import { IconLibraryResolution } from './IconLibraryResolution';
+
+/**
+ * Finds the icon libraries a profile's packages make active - the ones it lists and the ones its other
+ * packages declare a dependency on - through the normal package resolver, so an icon library is
+ * selected, ordered and version-checked exactly as any other package is.
+ *
+ * Several libraries coexist. Nothing here ranks them: two libraries that both ship `home` stay two
+ * different icons, told apart by the library in their {@link IconReference}.
+ *
+ * @param selected The package names the profile lists.
+ * @param catalog Every package that could be selected.
+ */
+export function resolveIconLibraries(selected: string[], catalog: ScenePackage[]): IconLibraryResolution {
+    const selection = resolvePackageDependencies(selected, catalog);
+    const index = new Map(catalog.map((scenePackage) => [scenePackage.name, scenePackage]));
+    const chosen = new Set(selected);
+    const active = selection.packages.map((name) => index.get(name)).filter((scenePackage): scenePackage is ScenePackage => scenePackage !== undefined);
+
+    const libraries = active
+        .filter((scenePackage) => scenePackage.kind === PackageKind.IconLibrary)
+        .map((scenePackage) => ({
+            library: scenePackage.name,
+            package: scenePackage,
+            isSelected: chosen.has(scenePackage.name),
+            requiredBy: active
+                .filter((other) => other.dependencies.some((dependency) => dependency.name === scenePackage.name))
+                .map((other) => other.name),
+        }));
+
+    const libraryNames = new Set(libraries.map((resolved) => resolved.library));
+    const diagnostics: IconDiagnostic[] = selection.versionConflicts
+        .filter((conflict) => libraryNames.has(conflict.dependsOn))
+        .map((conflict) => ({
+            kind: 'incompatible-version',
+            library: conflict.dependsOn,
+            message: `'${conflict.package}' needs the icon library '${conflict.dependsOn}' at '${conflict.requiredRange}', but version ${conflict.actualVersion} is what is available`,
+        }));
+
+    return { libraries, diagnostics };
+}

package/index.ts

@@ -8,6 +8,7 @@ export * from './elementKind';
 export * from './panelKind';
 export * from './flowNodeKind';
 export * from './ComponentResolution';
+export * from './icons';
 export * from './resolveComponentName';
 export * from './computeSizeClass';
 export * from './evaluateFlowArrangement';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.3.0",
+    "version": "4.5.0",
     "description": "The Scene runtime: walks a Scene element tree and drives whichever renderer is plugged in. Does not know React, or any other rendering platform, exists.",
     "keywords": [
         "cratis",
@@ -48,9 +48,9 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/scene.model": "4.3.0"
+        "@cratis/scene.model": "4.5.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.3.0"
+        "@cratis/scene.model": "4.5.0"
     }
 }