@cratis/scene.engine 4.2.1 → 4.4.0

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';
@@ -26,3 +27,4 @@ export * from './ActionDispatcher';
 export * from './runActions';
 export * from './resolveBehaviors';
 export * from './resolveStrings';
+export * from './editing';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.2.1",
+    "version": "4.4.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.2.1"
+        "@cratis/scene.model": "4.4.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.2.1"
+        "@cratis/scene.model": "4.4.0"
     }
 }