@cratis/scene.react 4.3.0 → 4.5.0

package/icons/IconAdapter.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentType } from 'react';
+import { IconReference } from '@cratis/scene.model';
+
+/**
+ * What an icon library's glyph is handed to draw itself. The glyph owns only its artwork: `SceneIcon`
+ * has already sized and colored the box it sits in and made it accessible, so a glyph just fills it.
+ */
+export interface IconGlyphProps {
+    /**
+     * The width and height to draw at - a number of pixels or any CSS length.
+     */
+    size: number | string;
+
+    /**
+     * The color to draw in; `currentColor` unless the caller chose one.
+     */
+    color: string;
+
+    /**
+     * An optional class for the artwork element.
+     */
+    className?: string;
+}
+
+/**
+ * One icon's artwork, as a component.
+ */
+export type IconGlyph = ComponentType<IconGlyphProps>;
+
+/**
+ * How one icon library's references become pixels in React. The model persists only an
+ * {@link IconReference}; an adapter is the library's own answer to "what does this one look like here",
+ * so no markup, class name or component is ever persisted - and a library can be re-rendered, or replaced
+ * by one with an adapter for another renderer, without touching a single stored value.
+ *
+ * Artwork is loaded per icon and on demand, so a library with thousands of icons costs a screen only the
+ * ones it shows.
+ */
+export interface IconAdapter {
+    /**
+     * The library this adapter renders - an {@link IconReference.library}.
+     */
+    library: string;
+
+    /**
+     * Loads the artwork for one reference. Resolves to `undefined` when the library has no such icon.
+     */
+    loadGlyph(reference: IconReference): Promise<IconGlyph | undefined> | IconGlyph | undefined;
+}

package/icons/IconAdapterContext.tsx

@@ -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 { ReactNode, createContext, useContext } from 'react';
+import { IconAdapterRegistry } from './IconAdapterRegistry';
+
+const IconAdapterContext = createContext<IconAdapterRegistry | undefined>(undefined);
+
+/**
+ * Supplies the icon adapters every `SceneIcon` below it renders through.
+ */
+export const IconAdapterProvider = ({ registry, children }: { registry: IconAdapterRegistry; children?: ReactNode }) => (
+    <IconAdapterContext.Provider value={registry}>{children}</IconAdapterContext.Provider>
+);
+
+/**
+ * The icon adapters in scope, or `undefined` outside an {@link IconAdapterProvider}.
+ */
+export function useIconAdapters(): IconAdapterRegistry | undefined {
+    return useContext(IconAdapterContext);
+}

package/icons/IconAdapterRegistry.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconAdapter } from './IconAdapter';
+
+/**
+ * The icon adapters a renderer has, one per library. Registering is explicit and never replaces: two
+ * adapters for one library would mean an icon renders differently depending on registration order, which
+ * is the silent swapping the library-qualified reference exists to prevent.
+ */
+export class IconAdapterRegistry {
+    readonly #adapters = new Map<string, IconAdapter>();
+
+    /**
+     * Adds an adapter.
+     *
+     * @throws Error when an adapter for the same library is already registered.
+     */
+    register(adapter: IconAdapter): this {
+        if (this.#adapters.has(adapter.library)) {
+            throw new Error(`An icon adapter for the library '${adapter.library}' is already registered`);
+        }
+
+        this.#adapters.set(adapter.library, adapter);
+        return this;
+    }
+
+    /**
+     * The adapter for a library, or `undefined` when this renderer has none.
+     */
+    get(library: string): IconAdapter | undefined {
+        return this.#adapters.get(library);
+    }
+
+    /**
+     * The libraries this registry can render.
+     */
+    get libraries(): string[] {
+        return [...this.#adapters.keys()];
+    }
+}
+
+/**
+ * Creates a registry holding the given adapters.
+ */
+export function createIconAdapterRegistry(adapters: IconAdapter[] = []): IconAdapterRegistry {
+    const registry = new IconAdapterRegistry();
+    adapters.forEach((adapter) => registry.register(adapter));
+    return registry;
+}

package/icons/IconLibraryBundle.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 { IconCatalogSource } from '@cratis/scene.engine';
+import { IconAdapter } from './IconAdapter';
+
+/**
+ * What an icon-library package ships to a React renderer, as opposed to what its manifest declares.
+ *
+ * The manifest says the library exists, what it is licensed under and which renderers it supports; this
+ * is the code behind it. The catalog is the metadata a picker searches, loaded on demand; the adapter
+ * turns one reference at a time into artwork. They are separate because a catalog is renderer-neutral
+ * and an adapter is not.
+ */
+export interface IconLibraryBundle {
+    /**
+     * Where the library's icon catalog is loaded from.
+     */
+    catalog: IconCatalogSource;
+
+    /**
+     * How the library's references are drawn in React.
+     */
+    adapter: IconAdapter;
+}

package/icons/SceneIcon.tsx

@@ -0,0 +1,73 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode } from 'react';
+import { IconReference } from '@cratis/scene.model';
+import { IconAdapterRegistry } from './IconAdapterRegistry';
+import { useIconAdapters } from './IconAdapterContext';
+import { useIconGlyph } from './useIconGlyph';
+
+export interface SceneIconProps {
+    /**
+     * The icon to draw.
+     */
+    reference: IconReference;
+
+    /**
+     * The adapters to render through. Defaults to the ones an `IconAdapterProvider` supplies.
+     */
+    adapters?: IconAdapterRegistry;
+
+    /**
+     * The width and height of the icon: a number of pixels or any CSS length. Defaults to `1em`, so an
+     * icon scales with the text it sits in.
+     */
+    size?: number | string;
+
+    /**
+     * The color to draw in. Defaults to `currentColor`.
+     */
+    color?: string;
+
+    /**
+     * The accessible name. With a label the icon is announced as an image; without one it is decorative
+     * and hidden from assistive technology - an icon next to its own text label should not be read twice.
+     */
+    label?: string;
+
+    /**
+     * An optional class for the box the icon sits in.
+     */
+    className?: string;
+
+    /**
+     * What to show when the icon cannot be drawn - no adapter, no such icon, a failed load. Nothing by
+     * default; the box keeps its size so layout does not shift.
+     */
+    fallback?: ReactNode;
+}
+
+/**
+ * Draws a renderer-neutral {@link IconReference} through the adapter registered for its library, honoring
+ * size, color and accessible label. The reference is all that is persisted; this is where it becomes pixels.
+ */
+export const SceneIcon = ({ reference, adapters, size = '1em', color = 'currentColor', label, className, fallback }: SceneIconProps) => {
+    const inScope = useIconAdapters();
+    const state = useIconGlyph(reference, adapters ?? inScope);
+    const Glyph = state.status === 'ready' ? state.glyph : undefined;
+
+    return (
+        <span
+            className={className}
+            role={label ? 'img' : undefined}
+            aria-label={label}
+            aria-hidden={label ? undefined : true}
+            data-icon-library={reference.library}
+            data-icon-key={reference.key}
+            data-icon-variant={reference.variant}
+            data-icon-state={state.status}
+            style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: size, height: size, color, flexShrink: 0 }}>
+            {Glyph ? <Glyph size={size} color={color} /> : state.status === 'unavailable' ? fallback : null}
+        </span>
+    );
+};

package/icons/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './IconAdapter';
+export * from './IconAdapterRegistry';
+export * from './IconAdapterContext';
+export * from './useIconGlyph';
+export * from './SceneIcon';
+export * from './IconLibraryBundle';

package/icons/useIconGlyph.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useState } from 'react';
+import { IconReference } from '@cratis/scene.model';
+import { IconAdapter, IconGlyph } from './IconAdapter';
+import { IconAdapterRegistry } from './IconAdapterRegistry';
+
+/**
+ * Where loading one icon's artwork stands.
+ */
+export type IconGlyphState =
+    | { status: 'loading' }
+    | { status: 'ready'; glyph: IconGlyph }
+    | { status: 'unavailable'; reason: string };
+
+const loads = new WeakMap<IconAdapter, Map<string, Promise<IconGlyph | undefined>>>();
+
+function keyOf(reference: IconReference): string {
+    return JSON.stringify([reference.key, reference.variant ?? null]);
+}
+
+/**
+ * One load per adapter and icon, shared between every place the icon is drawn; a failed load is
+ * forgotten so the next render can try again.
+ */
+function load(adapter: IconAdapter, reference: IconReference): Promise<IconGlyph | undefined> {
+    let perAdapter = loads.get(adapter);
+    if (!perAdapter) {
+        perAdapter = new Map();
+        loads.set(adapter, perAdapter);
+    }
+
+    const key = keyOf(reference);
+    let pending = perAdapter.get(key);
+    if (!pending) {
+        pending = Promise.resolve().then(() => adapter.loadGlyph(reference));
+        perAdapter.set(key, pending);
+        pending.catch(() => perAdapter.delete(key));
+    }
+
+    return pending;
+}
+
+/**
+ * Loads the artwork for a reference through the adapter registered for its library. An absent registry,
+ * a library with no adapter, an icon the library lacks and a failed load are all `unavailable`, each with
+ * its reason - never a different icon.
+ */
+export function useIconGlyph(reference: IconReference, adapters: IconAdapterRegistry | undefined): IconGlyphState {
+    const [state, setState] = useState<IconGlyphState>({ status: 'loading' });
+    const { library, key, variant } = reference;
+
+    useEffect(() => {
+        let isCurrent = true;
+        const adapter = adapters?.get(library);
+        if (!adapter) {
+            setState({ status: 'unavailable', reason: `No icon adapter is registered for the library '${library}'` });
+            return;
+        }
+
+        setState({ status: 'loading' });
+        load(adapter, { library, key, variant }).then(
+            (glyph) => {
+                if (!isCurrent) return;
+                setState(glyph ? { status: 'ready', glyph } : { status: 'unavailable', reason: `The library '${library}' has no icon '${key}'` });
+            },
+            (error: unknown) => {
+                if (isCurrent) setState({ status: 'unavailable', reason: error instanceof Error ? error.message : String(error) });
+            }
+        );
+
+        return () => {
+            isCurrent = false;
+        };
+    }, [adapters, library, key, variant]);
+
+    return state;
+}

package/index.ts

@@ -5,6 +5,7 @@ export * from './SceneElementView';
 export * from './renderer';
 export * from './core';
 export * from './NavBar';
+export * from './icons';
 export * from './packages';
 export * from './theme';
 export * from './interactions';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.3.0",
+    "version": "4.5.0",
     "description": "The React renderer implementing Scene.Engine's Renderer contract against real React/DOM.",
     "keywords": [
         "cratis",
@@ -51,12 +51,12 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.3.0",
-        "@cratis/scene.model": "4.3.0"
+        "@cratis/scene.engine": "4.5.0",
+        "@cratis/scene.model": "4.5.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.3.0",
-        "@cratis/scene.model": "4.3.0",
+        "@cratis/scene.engine": "4.5.0",
+        "@cratis/scene.model": "4.5.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",

package/packages/ScenePackageBundle.ts

@@ -1,7 +1,9 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ComponentDescriptor, DialogTemplate, Layout, PropertyValueType, ScenePackage, Screen, ScreenTemplate, Theme } from '@cratis/scene.model';
+import { ComponentDescriptor, DialogTemplate, Layout, PackageKind, PropertyValueType, ScenePackage, Screen, ScreenTemplate, Theme } from '@cratis/scene.model';
+import { IconAdapterRegistry, createIconAdapterRegistry } from '../icons/IconAdapterRegistry';
+import { IconLibraryBundle } from '../icons/IconLibraryBundle';
 import { ComponentRegistry } from '../renderer';
 
 /**
@@ -62,6 +64,12 @@ export interface ScenePackageBundle {
      * The themes this package ships, if any.
      */
     themes?: Theme[];
+
+    /**
+     * The icon catalog and renderer adapter of an icon-library package. Present exactly when the
+     * manifest declares an icon library.
+     */
+    iconLibrary?: IconLibraryBundle;
 }
 
 /**
@@ -132,7 +140,47 @@ export function validatePackageBundle(bundle: ScenePackageBundle): string[] {
         }
     }
 
+    problems.push(...validateIconLibrary(bundle));
     problems.push(...validateDescriptors(bundle));
+
+    return problems;
+}
+
+function validateIconLibrary(bundle: ScenePackageBundle): string[] {
+    const problems: string[] = [];
+    const { manifest, iconLibrary } = bundle;
+    const declaresIconLibrary = manifest.kind === PackageKind.IconLibrary || manifest.iconLibrary !== undefined;
+
+    if (manifest.kind === PackageKind.IconLibrary && !manifest.iconLibrary) {
+        problems.push('is an icon library but declares no iconLibrary metadata');
+    }
+
+    if (manifest.kind !== PackageKind.IconLibrary && manifest.iconLibrary) {
+        problems.push('declares iconLibrary metadata but is not of kind IconLibrary');
+    }
+
+    if (declaresIconLibrary && !iconLibrary) {
+        problems.push('declares an icon library but the bundle provides no catalog or adapter for it');
+    }
+
+    if (!declaresIconLibrary && iconLibrary) {
+        problems.push('provides an icon catalog and adapter, which the manifest does not declare');
+    }
+
+    if (iconLibrary) {
+        if (iconLibrary.catalog.library !== manifest.name) {
+            problems.push(`provides an icon catalog for '${iconLibrary.catalog.library}' instead of '${manifest.name}'`);
+        }
+
+        if (iconLibrary.adapter.library !== manifest.name) {
+            problems.push(`provides an icon adapter for '${iconLibrary.adapter.library}' instead of '${manifest.name}'`);
+        }
+
+        if (manifest.iconLibrary && !manifest.iconLibrary.renderers.includes('react')) {
+            problems.push("provides a React icon adapter but does not list 'react' among its icon renderers");
+        }
+    }
+
     return problems;
 }
 
@@ -182,3 +230,12 @@ function validateDescriptors(bundle: ScenePackageBundle): string[] {
 export function mergePackageRegistries(bundles: ScenePackageBundle[]): ComponentRegistry {
     return Object.assign({}, ...bundles.map((bundle) => bundle.components)) as ComponentRegistry;
 }
+
+/**
+ * Collects the icon adapters of several bundles into the registry `SceneIcon` renders through.
+ *
+ * @throws Error when two bundles provide an adapter for the same library.
+ */
+export function mergeIconAdapters(bundles: ScenePackageBundle[]): IconAdapterRegistry {
+    return createIconAdapterRegistry(bundles.flatMap((bundle) => (bundle.iconLibrary ? [bundle.iconLibrary.adapter] : [])));
+}