@cratis/scene.react 4.22.1 → 4.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.22.1",
+    "version": "4.24.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.22.1",
-        "@cratis/scene.model": "4.22.1"
+        "@cratis/scene.engine": "4.24.0",
+        "@cratis/scene.model": "4.24.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.22.1",
-        "@cratis/scene.model": "4.22.1",
+        "@cratis/scene.engine": "4.24.0",
+        "@cratis/scene.model": "4.24.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,8 @@
 // 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, PackageKind, PropertyDescriptor, PropertyValueType, ScenePackage, Screen, ScreenTemplate, Theme } from '@cratis/scene.model';
+import { validateComponentDescriptors } from '@cratis/scene.engine';
+import { ComponentDescriptor, DiagnosticCode, DialogTemplate, Layout, PackageKind, PropertyDescriptor, PropertyValueType, ScenePackage, Screen, ScreenTemplate, Theme } from '@cratis/scene.model';
 import { IconAdapterRegistry, createIconAdapterRegistry } from '../icons/IconAdapterRegistry';
 import { IconLibraryBundle } from '../icons/IconLibraryBundle';
 import { ComponentRegistry } from '../renderer';
@@ -250,6 +251,11 @@ function validateDescriptors(bundle: ScenePackageBundle): string[] {
         validateProperties(descriptor.component, descriptor.properties, '', problems);
     }
 
+    // The category rule (CMP1) is not checked here - it gates a designer, not a host loading a package (see validateComponentMetadata) -
+    // but a design-mode descriptor or editor parameter that cannot work is as much a mistake as an enum without choices.
+    const structural: string[] = [DiagnosticCode.ComponentDesignModeInvalid, DiagnosticCode.PropertyEditorOptionsInvalid];
+    problems.push(...validateComponentDescriptors(bundle.descriptors ?? []).filter(diagnostic => structural.includes(diagnostic.code)).map(diagnostic => diagnostic.message));
+
     return problems;
 }
 

package/packages/describeComponents.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 { ComponentDescriptor, ComponentDesignModeDescriptor, componentIcon } from '@cratis/scene.model';
+import { componentRegistryKey } from './ScenePackageBundle';
+
+/**
+ * What a package says about one of its components for a picker, besides what can be edited: the data of CMP1 and the picker's
+ * rows. Written once per package as a table keyed by the bare component name.
+ */
+export interface ComponentMetadata {
+    /** The name a picker shows. Absent keeps the one the component's descriptor has, or the bare name. */
+    displayName?: string;
+
+    /** One of `ComponentCategory`, or a category of the package's own. */
+    category: string;
+
+    /** The key of the icon in the built-in icon library (`componentIcon`). */
+    icon?: string;
+
+    /** Words the picker's filter matches besides the name. */
+    keywords?: string[];
+
+    /** An explicit two-letter badge; absent means derived from the name. */
+    badge?: string;
+
+    /** How the component is edited directly on the design surface. */
+    designMode?: ComponentDesignModeDescriptor;
+}
+
+/** A `ComponentMetadata` entry in one line: what a package's metadata table is made of. */
+export function componentMetadata(
+    displayName: string,
+    category: string,
+    icon: string,
+    keywords: string[] = [],
+    badge?: string,
+    designMode?: ComponentDesignModeDescriptor
+): ComponentMetadata {
+    return { displayName, category, icon, keywords, ...(badge === undefined ? {} : { badge }), ...(designMode === undefined ? {} : { designMode }) };
+}
+
+/**
+ * Builds the descriptors a bundle ships: the ones written by hand with the package's component metadata merged in, plus a descriptor with
+ * no editable properties for every component the metadata names that nobody described - such a component still has a name, a
+ * category and a place in a picker. A hand-written descriptor keeps everything it already says; metadata only fills in what it
+ * leaves out.
+ *
+ * The component list is the metadata table's own, so a component the table forgets has no descriptor and `validateComponentMetadata`
+ * reports it (CMP1); one the table names but the manifest does not declare is reported by `validatePackageBundle`.
+ */
+export function describeComponents(
+    packageName: string,
+    described: readonly ComponentDescriptor[],
+    metadata: Readonly<Record<string, ComponentMetadata>>
+): ComponentDescriptor[] {
+    const describedKeys = new Set(described.map(descriptor => descriptor.component));
+    const bare = Object.keys(metadata)
+        .map(name => componentRegistryKey(packageName, name))
+        .filter(key => !describedKeys.has(key))
+        .map((key): ComponentDescriptor => ({ component: key, properties: [] }));
+
+    return [...described, ...bare].map(descriptor => withMetadata(descriptor, metadata[descriptor.component.slice(packageName.length + 1)]));
+}
+
+function withMetadata(descriptor: ComponentDescriptor, metadata: ComponentMetadata | undefined): ComponentDescriptor {
+    if (!metadata) return descriptor;
+
+    return {
+        ...descriptor,
+        displayName: descriptor.displayName ?? metadata.displayName ?? descriptor.component.slice(descriptor.component.indexOf(':') + 1),
+        category: descriptor.category ?? metadata.category,
+        ...(descriptor.icon === undefined && metadata.icon !== undefined ? { icon: componentIcon(metadata.icon) } : {}),
+        ...(descriptor.keywords === undefined && metadata.keywords !== undefined ? { keywords: metadata.keywords } : {}),
+        ...(descriptor.badge === undefined && metadata.badge !== undefined ? { badge: metadata.badge } : {}),
+        ...(descriptor.designMode === undefined && metadata.designMode !== undefined ? { designMode: metadata.designMode } : {}),
+    };
+}

package/packages/designModes.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentDesignModeDescriptor, DesignModeItemAction, componentIcon } from '@cratis/scene.model';
+
+/** The rule that says an item may be changed (not inherited), interpreted by the package's design-time bundle. */
+export const itemEditableRule = 'item.editable';
+
+/** The rule that says why an inherited item may not be changed. */
+export const itemInheritedReason = 'item.inherited';
+
+const mutating = (action: Omit<DesignModeItemAction, 'icon'> & { icon: string }, compact?: boolean): DesignModeItemAction => ({
+    id: action.id,
+    icon: componentIcon(action.icon),
+    title: action.title,
+    ...(compact === true ? { compact: true } : {}),
+    availability: action.availability ?? itemEditableRule,
+    readOnlyReason: itemInheritedReason,
+});
+
+export interface NavigationDesignModeOptions {
+    /** The `Collection` property that holds the items; absent when the host resolves them (a topbar's or sidebar's navigation region). */
+    itemsPath?: string;
+
+    /** A sidebar's items nest, and its toolbar sits below the item in a compact two-row form (spec DM3, DM4). */
+    sidebar?: boolean;
+}
+
+/**
+ * The design mode of a component made of navigation items (a topbar, a sidebar, a navigation bar): add an item, and on a selected
+ * item rename it, choose its target and rendering slot, move it earlier or later, duplicate it, delete it, and - in a sidebar - add a
+ * sub-item (spec DM3). Pass the `itemsPath` of a component whose items are a `Collection` property; the target and slot buttons are
+ * left out of such a component unless `itemsPath` is absent, because only the navigation region's items have them.
+ */
+export function navigationDesignMode(options: NavigationDesignModeOptions = {}): ComponentDesignModeDescriptor {
+    const { itemsPath, sidebar = false } = options;
+    const regionItems = itemsPath === undefined;
+
+    return {
+        ...(itemsPath === undefined ? {} : { itemsPath }),
+        addActions: [{ id: 'addItem', label: 'Add item', icon: componentIcon('plus'), ...(itemsPath === undefined ? {} : { collectionPath: itemsPath }) }],
+        itemToolbar: [
+            mutating({ id: 'rename', icon: 'pencil', title: 'Rename' }, sidebar),
+            ...(regionItems ? [
+                mutating({ id: 'target', icon: 'link', title: 'Link target' }, sidebar),
+                mutating({ id: 'slot', icon: 'layout-panel-left', title: 'Rendering slot' }, sidebar),
+            ] : []),
+            mutating({ id: 'moveEarlier', icon: sidebar ? 'arrow-up' : 'arrow-left', title: 'Move earlier' }, sidebar),
+            mutating({ id: 'moveLater', icon: sidebar ? 'arrow-down' : 'arrow-right', title: 'Move later' }, sidebar),
+            mutating({ id: 'duplicate', icon: 'copy', title: 'Duplicate' }, sidebar),
+            mutating({ id: 'delete', icon: 'trash', title: 'Delete' }, sidebar),
+            ...(sidebar ? [mutating({ id: 'addSubItem', icon: 'corner-down-right', title: 'Add sub-item' }, true)] : []),
+        ],
+    };
+}
+
+/**
+ * The design mode of a toolbar: add a button, and on a selected button rename it, choose the slice it starts, set its emphasis,
+ * move it earlier or later, duplicate it, delete it (spec DM3). The buttons are the toolbar's own items, which the host resolves.
+ */
+export function toolbarDesignMode(): ComponentDesignModeDescriptor {
+    return {
+        addActions: [{ id: 'addButton', label: 'Add button', icon: componentIcon('plus') }],
+        itemToolbar: [
+            mutating({ id: 'rename', icon: 'pencil', title: 'Rename' }),
+            mutating({ id: 'slice', icon: 'git-branch', title: 'Choose slice' }),
+            mutating({ id: 'emphasis', icon: 'contrast', title: 'Emphasis' }),
+            mutating({ id: 'moveEarlier', icon: 'arrow-left', title: 'Move earlier' }),
+            mutating({ id: 'moveLater', icon: 'arrow-right', title: 'Move later' }),
+            mutating({ id: 'duplicate', icon: 'copy', title: 'Duplicate' }),
+            mutating({ id: 'delete', icon: 'trash', title: 'Delete' }),
+        ],
+    };
+}

package/packages/index.ts

@@ -26,6 +26,9 @@ export * from './PackageHostView';
 export * from './resolveDesignTimeHost';
 export * from './runDesignTimeAction';
 export * from './ScenePackageBundle';
+export * from './describeComponents';
+export * from './designModes';
+export * from './validateComponentMetadata';
 export * from './StandalonePackageHost';
 export * from './WebViewPackageHost';
 export * from './ComponentsUiLibraryContract';

package/packages/validateComponentMetadata.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 { validateComponentDescriptors } from '@cratis/scene.engine';
+import { SceneDiagnostic } from '@cratis/scene.model';
+import { ScenePackageBundle, componentRegistryKey } from './ScenePackageBundle';
+
+/**
+ * Checks the component metadata of a bundle (rule CMP1): every component its manifest declares or its registry holds is described
+ * and declares a category, and the design-mode and editor parameters of its descriptors are sound.
+ *
+ * This is not part of `validatePackageBundle`: that gates what a host loads, and a third-party package written before components
+ * had categories must still load. A designer and the in-repo packages' own specs run this one.
+ */
+export function validateComponentMetadata(bundle: ScenePackageBundle): SceneDiagnostic[] {
+    const registered = new Set([
+        ...bundle.manifest.components.map(name => componentRegistryKey(bundle.manifest.name, name)),
+        ...Object.keys(bundle.components),
+    ]);
+
+    return validateComponentDescriptors(bundle.descriptors ?? [], [...registered]);
+}