@cratis/scene.model 4.3.0 → 4.5.0

package/editing/DiagnosticCode.ts

@@ -55,4 +55,12 @@ export enum DiagnosticCode {
     CollectionItemNotFound = 'collectionItemNotFound',
     DuplicateCollectionItem = 'duplicateCollectionItem',
     UnknownInstance = 'unknownInstance',
+
+    // Icons
+    MissingIconLibrary = 'missingIconLibrary',
+    MissingIcon = 'missingIcon',
+    MissingIconVariant = 'missingIconVariant',
+    IncompatibleIconLibrary = 'incompatibleIconLibrary',
+    IconCatalogUnavailable = 'iconCatalogUnavailable',
+    IconNotVerified = 'iconNotVerified',
 }

package/icons/IconEntry.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.
+
+/**
+ * One icon in an icon library's catalog: what a picker needs to find it and a reference needs to name it.
+ *
+ * An entry is metadata only. It holds no SVG, class name or component - that is the renderer's concern,
+ * resolved lazily per icon by the adapter - so a catalog is cheap to load and identical for every
+ * renderer. The {@link IconReference} that names the icon is the entry's `key` (and one of its
+ * `variants`) together with the library the catalog belongs to.
+ */
+export interface IconEntry {
+    /**
+     * The stable key within the library; what an {@link IconReference} persists.
+     */
+    key: string;
+
+    /**
+     * The display name a picker shows. Never identity - two libraries may share a name.
+     */
+    name: string;
+
+    /**
+     * The categories the icon is filed under, for browsing.
+     */
+    categories: string[];
+
+    /**
+     * Alternative names to find the icon by (`bin` for `trash`).
+     */
+    aliases?: string[];
+
+    /**
+     * Free-form search terms.
+     */
+    tags?: string[];
+
+    /**
+     * The variants this icon exists in. Absent or empty when the icon has no variants, in which case
+     * references to it carry none.
+     */
+    variants?: string[];
+}
+
+export const IconEntryPropertyNames: (keyof IconEntry)[] = ['key', 'name', 'categories', 'aliases', 'tags', 'variants'];

package/icons/IconLibrary.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a {@link ScenePackage} of kind {@link PackageKind.IconLibrary} declares about its icons, beyond
+ * what every package declares (name, version, license, dependencies, module).
+ *
+ * It is deliberately small. The icons themselves are not listed here: a library can ship thousands, and a
+ * profile resolution that read every key of every library would defeat the point of resolving without
+ * loading anything. The icon *catalog* - an {@link IconEntry} per icon - is loaded on demand from the
+ * library's module, and each icon's artwork is loaded per icon by the renderer's adapter.
+ */
+export interface IconLibrary {
+    /**
+     * The style variants the library offers (`outline`, `solid` ...), empty when it has a single style.
+     * Declared here so a picker can offer variant filters before it has loaded the catalog.
+     */
+    variants: string[];
+
+    /**
+     * The renderers the library ships an adapter for (`react` ...), so tooling can say whether the
+     * library can render for the target a profile selects without loading it.
+     */
+    renderers: string[];
+
+    /**
+     * The credit line the library's license asks to be shown, for example "Icons by Lucide contributors".
+     */
+    attribution?: string;
+
+    /**
+     * Where the attribution points - the library's home or license page.
+     */
+    attributionUrl?: string;
+
+    /**
+     * How many icons the catalog holds, for a picker's "1,500 icons" before the catalog is loaded.
+     */
+    iconCount?: number;
+}
+
+export const IconLibraryPropertyNames: (keyof IconLibrary)[] = ['variants', 'renderers', 'attribution', 'attributionUrl', 'iconCount'];

package/icons/IconReference.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The persisted, renderer-neutral identity of one icon: which icon library it comes from, which icon
+ * inside that library, and optionally which style variant of it.
+ *
+ * This is the only form in which a screen, template, blueprint or profile refers to an icon. It carries
+ * no CSS class, no SVG and no component - those belong to a renderer's adapter for the library - so the
+ * same reference renders on the web, on a phone, or anywhere else a library has an adapter.
+ *
+ * Identity is all three fields. A display name, a catalog position or a CSS class is never identity:
+ * two libraries can each ship an icon called `home`, and `{ library: 'a', key: 'home' }` and
+ * `{ library: 'b', key: 'home' }` are different icons that are never silently swapped for one another.
+ */
+export interface IconReference {
+    /**
+     * The identity of the icon library - the `name` of the {@link ScenePackage} of kind
+     * {@link PackageKind.IconLibrary} that provides the icon.
+     */
+    library: string;
+
+    /**
+     * The stable key of the icon inside its library. Stable means a library keeps the key across
+     * versions for as long as it ships the icon; it is not the icon's display name.
+     */
+    key: string;
+
+    /**
+     * The style variant (`outline`, `solid`, `filled` ...), or absent for a library or icon that has none.
+     */
+    variant?: string;
+}
+
+export const IconReferencePropertyNames: (keyof IconReference)[] = ['library', 'key', 'variant'];

package/icons/iconReferences.ts

@@ -0,0 +1,62 @@
+// 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 './IconReference';
+
+/**
+ * The character that separates the parts of an icon reference's text form. A reference's parts therefore
+ * cannot contain it - an npm package name, an icon key and a variant name never do.
+ */
+const separator = '#';
+
+function isPart(value: unknown): value is string {
+    return typeof value === 'string' && value.length > 0 && !value.includes(separator);
+}
+
+/**
+ * Whether a value is a well-formed {@link IconReference}: a library and a key that are non-empty, an
+ * optional non-empty variant, none of them containing the text-form separator. Extra properties are
+ * tolerated, because a reference read from a persisted document may carry editor-added metadata.
+ */
+export function isIconReference(value: unknown): value is IconReference {
+    if (typeof value !== 'object' || value === null) return false;
+    const candidate = value as Record<string, unknown>;
+    return isPart(candidate.library) && isPart(candidate.key) && (candidate.variant === undefined || isPart(candidate.variant));
+}
+
+/**
+ * Whether two references name the same icon. Equality is all three fields - library, key and variant -
+ * and nothing else; an absent variant equals only another absent variant.
+ */
+export function iconReferencesEqual(left: IconReference, right: IconReference): boolean {
+    return left.library === right.library && left.key === right.key && (left.variant ?? undefined) === (right.variant ?? undefined);
+}
+
+/**
+ * The canonical single-string form of a reference, for keys, logs and diagnostics:
+ * `library#key`, or `library#key#variant`. Two references are equal exactly when their text forms are equal.
+ * It is a convenience for people and tools, not the persisted shape - persist the {@link IconReference}.
+ *
+ * @throws Error when a part is empty or contains `#`.
+ */
+export function formatIconReference(reference: IconReference): string {
+    if (!isIconReference(reference)) {
+        throw new Error(`'${JSON.stringify(reference)}' is not a valid icon reference: library and key are required, and no part may be empty or contain '${separator}'`);
+    }
+
+    return reference.variant === undefined
+        ? `${reference.library}${separator}${reference.key}`
+        : `${reference.library}${separator}${reference.key}${separator}${reference.variant}`;
+}
+
+/**
+ * Reads the text form produced by {@link formatIconReference}. Returns `undefined` for anything that is
+ * not one - including a bare legacy icon name such as `pi pi-home`, which has no library and so cannot be
+ * made into a reference without choosing one.
+ */
+export function parseIconReference(text: string): IconReference | undefined {
+    const parts = text.split(separator);
+    if (parts.length < 2 || parts.length > 3 || !parts.every(isPart)) return undefined;
+    const [library, key, variant] = parts;
+    return variant === undefined ? { library, key } : { library, key, variant };
+}

package/icons/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './IconReference';
+export * from './iconReferences';
+export * from './IconLibrary';
+export * from './IconEntry';

package/index.ts

@@ -8,6 +8,7 @@ export * from './layouts';
 export * from './forms';
 export * from './contributionPoints';
 export * from './profiles';
+export * from './icons';
 export * from './packages';
 export * from './interactions';
 export * from './screens';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.model",
-    "version": "4.3.0",
+    "version": "4.5.0",
     "description": "The TypeScript mirror of Cratis.Scene.Model — the platform-agnostic Screen object model.",
     "keywords": [
         "cratis",

package/packages/PackageKind.ts

@@ -3,7 +3,7 @@
 
 /**
  * What a {@link ScenePackage} contributes to a {@link UiProfile}. A profile's package list mixes all
- * three kinds freely - the kind says what a package is for, never where it sits in the override-priority
+ * four kinds freely - the kind says what a package is for, never where it sits in the override-priority
  * order.
  */
 export enum PackageKind {
@@ -32,4 +32,17 @@ export enum PackageKind {
      * use" answerable from the packages a profile already has.
      */
     Blueprint = 'Blueprint',
+
+    /**
+     * Provides icons - a named, versioned library of them, such as Lucide or PrimeIcons - that screens,
+     * templates and blueprints refer to by {@link IconReference} rather than by CSS class or markup.
+     * A library declares its variants, renderer adapters and attribution through
+     * {@link ScenePackage.iconLibrary}; its icon catalog is loaded on demand, never listed in the package.
+     *
+     * It is a package kind rather than a contribution on another kind because everything an author asks
+     * of a library - select it in a profile, see its license and version, have it pulled in by the
+     * components that need it - is already what a package is. Several libraries coexist in one profile,
+     * and the library is part of every icon's identity, so same-named icons never shadow one another.
+     */
+    IconLibrary = 'IconLibrary',
 }

package/packages/ScenePackage.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { IconLibrary } from '../icons';
 import { PackageDependency } from './PackageDependency';
 import { PackageKind } from './PackageKind';
 
@@ -86,6 +87,11 @@ export interface ScenePackage {
      * tells an author nothing about eligibility or obligations.
      */
     licenseUrl?: string;
+
+    /**
+     * What the package declares about its icons. Present exactly for a {@link PackageKind.IconLibrary}.
+     */
+    iconLibrary?: IconLibrary;
 }
 
 export const ScenePackagePropertyNames: (keyof ScenePackage)[] = [
@@ -103,4 +109,5 @@ export const ScenePackagePropertyNames: (keyof ScenePackage)[] = [
     'module',
     'license',
     'licenseUrl',
+    'iconLibrary',
 ];

package/common/IconReference.ts

@@ -1,22 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-/**
- * A qualified reference to one icon: the library it comes from, its key within that library and an optional
- * style variant. This is the renderer-neutral, persisted form of an icon choice.
- *
- * Identity is all three fields. A label, a display name, a CSS class, an SVG or a position in a catalog is
- * never identity - none of them survive a library upgrade, and a persisted choice has to.
- */
-export interface IconReference {
-    /** The stable identity of the icon library package the icon belongs to. */
-    library: string;
-
-    /** The stable key of the icon within `library`. */
-    key: string;
-
-    /** The style variant (outlined, filled, ...), when the library has them. */
-    variant?: string;
-}
-
-export const IconReferencePropertyNames: (keyof IconReference)[] = ['library', 'key', 'variant'];

package/dist/cjs/common/IconReference.js

@@ -1,18 +0,0 @@
-'use strict';
-
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-/**
- * A qualified reference to one icon: the library it comes from, its key within that library and an optional
- * style variant. This is the renderer-neutral, persisted form of an icon choice.
- *
- * Identity is all three fields. A label, a display name, a CSS class, an SVG or a position in a catalog is
- * never identity - none of them survive a library upgrade, and a persisted choice has to.
- */ const IconReferencePropertyNames = [
-    'library',
-    'key',
-    'variant'
-];
-
-exports.IconReferencePropertyNames = IconReferencePropertyNames;
-//# sourceMappingURL=IconReference.js.map

package/dist/cjs/common/IconReference.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IconReference.js","sources":["../../../common/IconReference.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * A qualified reference to one icon: the library it comes from, its key within that library and an optional\n * style variant. This is the renderer-neutral, persisted form of an icon choice.\n *\n * Identity is all three fields. A label, a display name, a CSS class, an SVG or a position in a catalog is\n * never identity - none of them survive a library upgrade, and a persisted choice has to.\n */\nexport interface IconReference {\n    /** The stable identity of the icon library package the icon belongs to. */\n    library: string;\n\n    /** The stable key of the icon within `library`. */\n    key: string;\n\n    /** The style variant (outlined, filled, ...), when the library has them. */\n    variant?: string;\n}\n\nexport const IconReferencePropertyNames: (keyof IconReference)[] = ['library', 'key', 'variant'];\n"],"names":["IconReferencePropertyNames"],"mappings":";;AAAA;AACA;AAEA;;;;;;UAkBaA,0BAAAA,GAAsD;AAAC,IAAA,SAAA;AAAW,IAAA,KAAA;AAAO,IAAA;;;"}

package/dist/esm/common/IconReference.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"IconReference.d.ts","sourceRoot":"","sources":["../../../common/IconReference.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,aAAa;IAE1B,OAAO,EAAE,MAAM,CAAC;IAGhB,GAAG,EAAE,MAAM,CAAC;IAGZ,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,0BAA0B,EAAE,CAAC,MAAM,aAAa,CAAC,EAAkC,CAAC"}

package/dist/esm/common/IconReference.js

@@ -1,16 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-/**
- * A qualified reference to one icon: the library it comes from, its key within that library and an optional
- * style variant. This is the renderer-neutral, persisted form of an icon choice.
- *
- * Identity is all three fields. A label, a display name, a CSS class, an SVG or a position in a catalog is
- * never identity - none of them survive a library upgrade, and a persisted choice has to.
- */ const IconReferencePropertyNames = [
-    'library',
-    'key',
-    'variant'
-];
-
-export { IconReferencePropertyNames };
-//# sourceMappingURL=IconReference.js.map

package/dist/esm/common/IconReference.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IconReference.js","sources":["../../../common/IconReference.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\n/**\n * A qualified reference to one icon: the library it comes from, its key within that library and an optional\n * style variant. This is the renderer-neutral, persisted form of an icon choice.\n *\n * Identity is all three fields. A label, a display name, a CSS class, an SVG or a position in a catalog is\n * never identity - none of them survive a library upgrade, and a persisted choice has to.\n */\nexport interface IconReference {\n    /** The stable identity of the icon library package the icon belongs to. */\n    library: string;\n\n    /** The stable key of the icon within `library`. */\n    key: string;\n\n    /** The style variant (outlined, filled, ...), when the library has them. */\n    variant?: string;\n}\n\nexport const IconReferencePropertyNames: (keyof IconReference)[] = ['library', 'key', 'variant'];\n"],"names":["IconReferencePropertyNames"],"mappings":"AAAA;AACA;AAEA;;;;;;UAkBaA,0BAAAA,GAAsD;AAAC,IAAA,SAAA;AAAW,IAAA,KAAA;AAAO,IAAA;;;"}