@cratis/scene.react 4.29.0 → 4.31.0

package/index.ts

@@ -6,6 +6,7 @@ export * from './renderer';
 export * from './core';
 export * from './NavBar';
 export * from './navigation';
+export * from './slices';
 export * from './icons';
 export * from './packages';
 export * from './theme';

package/navigation/SceneNavigationContext.tsx

@@ -20,6 +20,9 @@ export interface SceneNavigationContextValue {
     currentOutlet?: string;
     currentDialog?: string;
 
+    /** The parameters the open dialog was opened with - a slice dialog carries its slice, command and title. */
+    currentDialogParameters?: Record<string, string>;
+
     /** The route parameters of the current entry - from the destination that opened it, or the deep link. */
     currentParameters: Record<string, string>;
 

package/navigation/SceneNavigationHost.tsx

@@ -17,6 +17,8 @@ import { useSceneHistoryNavigation } from './useSceneHistoryNavigation';
 import { SceneNavigationModel } from './region/SceneNavigationModel';
 import { SceneNavigationModelProvider } from './region/SceneNavigationModelContext';
 import { navigationDestinations } from './region/navigationDestinations';
+import { SliceDialogView } from '../slices/SliceDialogView';
+import { sliceDialogParameters } from '../slices/sliceDialogDestination';
 
 export interface SceneNavigationHostProps {
     screens: Record<string, SceneElement>;
@@ -54,7 +56,8 @@ export interface SceneNavigationHostProps {
  * Executes Scene destinations against an in-memory rendered hierarchy: a destination into a nested outlet -
  * one a screen declares with `core:outlet` - places its screen there and keeps the screens above it, to any
  * depth; any other screen route replaces the primary region,
- * dialog destinations render dialog content over the screen that opened them, and external destinations
+ * dialog destinations render dialog content over the screen that opened them - a toolbar slice button's dialog falls back to
+ * the built-in task dialog (`SliceDialogView`) when `dialogs` has no template of that name -, and external destinations
  * only report their resolved action. Every navigation is a history entry.
  */
 export function SceneNavigationHost({ screens, dialogs = {}, initialScreen, registry, bindingScope = {}, history, destinations: authoredDestinations, routes, navigationModel, frame }: SceneNavigationHostProps) {
@@ -69,14 +72,16 @@ export function SceneNavigationHost({ screens, dialogs = {}, initialScreen, regi
 
     const screen = screens[value.primaryScreen];
     const dialog = value.currentDialog ? dialogs[value.currentDialog] : undefined;
+    const sliceDialog = !dialog && value.currentDialog && sliceDialogParameters(value.currentDialogParameters) !== undefined;
+    const dialogName = sliceDialogParameters(value.currentDialogParameters)?.title ?? value.currentDialog;
 
     const outlet = <div data-scene-outlet={value.primaryScreen === value.currentScreen ? value.currentOutlet ?? 'primary' : 'primary'} data-scene-url={value.currentUrl}>
         {screen && <SceneElementView element={screen} registry={registry} dataContext={bindingScope.dataContext} queryResults={bindingScope.queryResults} componentOutputs={bindingScope.componentOutputs} />}
     </div>;
     const page = <SceneNavigationProvider value={value}><SceneOutletContext.Provider value={outletContext}>
         {frame ? frame(outlet) : outlet}
-        {dialog && <div role='dialog' aria-modal='true' aria-label={value.currentDialog} data-scene-dialog={value.currentDialog}>
-            <SceneElementView element={dialog} registry={registry} dataContext={bindingScope.dataContext} queryResults={bindingScope.queryResults} componentOutputs={bindingScope.componentOutputs} />
+        {(dialog || sliceDialog) && <div role='dialog' aria-modal='true' aria-label={dialogName} data-scene-dialog={value.currentDialog}>
+            {dialog ? <SceneElementView element={dialog} registry={registry} dataContext={bindingScope.dataContext} queryResults={bindingScope.queryResults} componentOutputs={bindingScope.componentOutputs} /> : <SliceDialogView />}
         </div>}
     </SceneOutletContext.Provider></SceneNavigationProvider>;
 

package/navigation/SceneNavigationState.ts

@@ -27,6 +27,9 @@ export interface SceneNavigationState {
     outlet?: string;
     dialog?: string;
 
+    /** The parameters the open dialog was opened with, by name. */
+    dialogParameters?: Record<string, string>;
+
     /** Route parameters, from the path template and the query string. */
     parameters: Record<string, string>;
 }

package/navigation/useSceneHistoryNavigation.ts

@@ -61,7 +61,7 @@ export function useSceneHistoryNavigation(
     const navigate = useCallback((destination: DestinationReference) => {
         const resolution = resolveDestination(destination, bindingScope);
         if (resolution.kind === DestinationKind.Dialog) {
-            if (resolution.dialog) go({ ...state, dialog: resolution.dialog });
+            if (resolution.dialog) go({ ...state, dialog: resolution.dialog, dialogParameters: resolution.parameters });
         } else if (resolution.kind !== DestinationKind.External) {
             const screen = destination.screen ?? destination.slice ?? state.screen;
             const placement = placeInOutlet(state, screen, resolution.outlet, outletOwners, destinations);
@@ -84,6 +84,7 @@ export function useSceneHistoryNavigation(
         currentUrl: state.url,
         currentOutlet: state.outlet,
         currentDialog: state.dialog,
+        currentDialogParameters: state.dialogParameters,
         currentParameters: state.parameters,
         dialogResult,
         unresolvedUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.29.0",
+    "version": "4.31.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.29.0",
-        "@cratis/scene.model": "4.29.0"
+        "@cratis/scene.engine": "4.31.0",
+        "@cratis/scene.model": "4.31.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.29.0",
-        "@cratis/scene.model": "4.29.0",
+        "@cratis/scene.engine": "4.31.0",
+        "@cratis/scene.model": "4.31.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",

package/slices/CoreSliceDialog.tsx

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '../renderer';
+import { SliceDialogView } from './SliceDialogView';
+
+/**
+ * The `core:sliceDialog` component: the task dialog of a state change slice. Its `slice`, `command` and `title` properties are
+ * optional - opened from a toolbar button the dialog's own parameters supply them - so one dialog template serves every slice.
+ */
+export function CoreSliceDialog({ element }: RegisteredComponentProps) {
+    const text = (name: string) => typeof element.properties[name] === 'string' ? element.properties[name] as string : undefined;
+    return <SliceDialogView slice={text('slice')} command={text('command')} title={text('title')} />;
+}

package/slices/InvocationResult.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.
+
+import { InvocationValidationError } from './InvocationValidationError';
+
+/**
+ * What invoking a state change slice came back with.
+ */
+export interface InvocationResult {
+    /** Whether the slice accepted the command. A dialog closes on success and shows the problems otherwise. */
+    succeeded: boolean;
+
+    /** The validation problems, shown against their fields; a problem without a field is shown for the whole form. */
+    validationErrors?: InvocationValidationError[];
+
+    /** A message for the user - a failure the server reports, or the note of a dry run. */
+    message?: string;
+
+    /** The command payload that was, or with a dry run would have been, sent. */
+    payload?: Record<string, unknown>;
+
+    /** Whether nothing was sent: the invocation was a dry run. */
+    dryRun?: boolean;
+
+    /** Whatever the invoker returns for the caller, for example the result of the command. */
+    value?: unknown;
+}

package/slices/InvocationValidationError.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One validation problem an invocation reports, to be shown inline in the dialog that submitted it.
+ */
+export interface InvocationValidationError {
+    /** The command property the problem belongs to; absent for a problem with the command as a whole. */
+    field?: string;
+
+    /** What is wrong. */
+    message: string;
+}

package/slices/SliceCommandField.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.
+
+/**
+ * One field of the form a slice's command is submitted from.
+ */
+export interface SliceCommandField {
+    /** The command property. */
+    name: string;
+
+    /** The property's type: `string`, `number`, `boolean`, `date`, `guid` ... Numbers and booleans are sent as such. */
+    type: string;
+
+    /** The label shown for the field; derived from the name when absent. */
+    label?: string;
+
+    /** Whether the field must have a value. */
+    required?: boolean;
+
+    /** The value the field starts with - a preview fills it from the active sample data pack; a running application leaves it out. */
+    initialValue?: string | number | boolean;
+}

package/slices/SliceCommandFieldsContext.tsx

@@ -0,0 +1,28 @@
+// 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 { SliceCommandField } from './SliceCommandField';
+
+/** Tells a task dialog which fields a command has. */
+export type SliceCommandFieldsSource = (command: string, sliceId: string) => SliceCommandField[];
+
+const Context = createContext<SliceCommandFieldsSource | undefined>(undefined);
+
+export interface SliceCommandFieldsProviderProps {
+    fieldsFor: SliceCommandFieldsSource;
+    children?: ReactNode;
+}
+
+/**
+ * Supplies the fields of a command to the task dialogs below it. The fields come from the command's metadata - Stage reads it
+ * from the generated schemas, Studio from the model - so this package does not know where commands are defined.
+ */
+export function SliceCommandFieldsProvider({ fieldsFor, children }: SliceCommandFieldsProviderProps) {
+    return <Context.Provider value={fieldsFor}>{children}</Context.Provider>;
+}
+
+/** The fields source in scope, or undefined when a host supplied none. */
+export function useSliceCommandFields(): SliceCommandFieldsSource | undefined {
+    return useContext(Context);
+}

package/slices/SliceDialogView.tsx

@@ -0,0 +1,187 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FormEvent, KeyboardEvent, useContext, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { ApplicationStructureIndex } from '@cratis/scene.engine';
+import { SceneNavigationContextInternal } from '../navigation/SceneNavigationContext';
+import { useSceneNavigationModel } from '../navigation/region/SceneNavigationModelContext';
+import { InvocationResult } from './InvocationResult';
+import { InvocationValidationError } from './InvocationValidationError';
+import { SliceCommandField } from './SliceCommandField';
+import { useSliceCommandFields } from './SliceCommandFieldsContext';
+import { useSliceInvoker } from './SliceInvokerContext';
+import { sliceDialogParameters } from './sliceDialogDestination';
+
+export interface SliceDialogViewProps {
+    /** The qualified id of the slice; the open dialog's `slice` parameter when absent. */
+    slice?: string;
+
+    /** The command the slice accepts; the open dialog's `command` parameter when absent. */
+    command?: string;
+
+    /** The title - the toolbar button's - also the label of the submit button; the open dialog's `title` parameter when absent. */
+    title?: string;
+
+    /** Called when the dialog is cancelled or the slice accepted the command; the host's `closeDialog` when absent. */
+    onClose?(result?: InvocationResult): void;
+}
+
+const focusable = 'input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])';
+
+/** A label for a command property: `customerName` becomes `Customer name`. */
+export function sliceFieldLabel(field: SliceCommandField): string {
+    if (field.label) return field.label;
+    const spaced = field.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').trim().toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+function inputTypeOf(field: SliceCommandField): string {
+    switch (field.type.toLowerCase()) {
+        case 'number': case 'int': case 'integer': case 'long': case 'double': case 'decimal': case 'float': case 'single': case 'int32': case 'int64': return 'number';
+        case 'boolean': case 'bool': return 'checkbox';
+        case 'date': case 'dateonly': return 'date';
+        default: return 'text';
+    }
+}
+
+/** What the form starts with: the fields that carry an initial value, as the strings and booleans the inputs hold. */
+function initialValuesOf(fields: SliceCommandField[]): Record<string, string | boolean> {
+    const values: Record<string, string | boolean> = {};
+    for (const field of fields) {
+        if (field.initialValue === undefined) continue;
+        values[field.name] = typeof field.initialValue === 'boolean' && inputTypeOf(field) === 'checkbox' ? field.initialValue : String(field.initialValue);
+    }
+
+    return values;
+}
+
+/** The payload a form's values make: numbers and booleans as such, an empty number left out. */
+export function slicePayload(fields: SliceCommandField[], values: Record<string, string | boolean>): Record<string, unknown> {
+    const payload: Record<string, unknown> = {};
+    for (const field of fields) {
+        const value = values[field.name];
+        const type = inputTypeOf(field);
+        if (type === 'checkbox') payload[field.name] = value === true;
+        else if (type === 'number') { if (value !== undefined && value !== '') payload[field.name] = Number(value); }
+        else payload[field.name] = value ?? '';
+    }
+
+    return payload;
+}
+
+/**
+ * The task dialog of a toolbar slice button (TB4): a modal card with the button's title, the slice as its subtitle, a labelled
+ * field for each command property, and Cancel and a submit button labelled with the title.
+ *
+ * - The first field takes focus when it opens, Tab stays inside, Escape cancels, and focus returns to the button that opened it.
+ * - Submit validates required fields, then calls the `SliceInvoker` in scope - real, dry-run or the announcing default. The
+ *   problems it reports are shown against their fields (`aria-invalid`, `aria-describedby`) or for the form; success closes the
+ *   dialog and hands the result to the host (`dialogResult`).
+ * - The fields come from the `SliceCommandFieldsProvider`; the subtitle names the slice from the navigation model.
+ *
+ * Inside a navigation host it is the content of the dialog a toolbar button opens; `core:sliceDialog` registers it so a host can
+ * author the dialog template with it.
+ */
+export function SliceDialogView({ slice: sliceProp, command: commandProp, title: titleProp, onClose }: SliceDialogViewProps) {
+    const navigation = useContext(SceneNavigationContextInternal);
+    const opened = sliceDialogParameters(navigation?.currentDialogParameters);
+    const slice = sliceProp ?? opened?.slice ?? '';
+    const command = commandProp ?? opened?.command ?? slice;
+    const title = titleProp ?? opened?.title ?? command;
+
+    const invoker = useSliceInvoker();
+    const fieldsFor = useSliceCommandFields();
+    const model = useSceneNavigationModel();
+    const fields = useMemo(() => fieldsFor?.(command, slice) ?? [], [command, fieldsFor, slice]);
+    const sliceName = useMemo(() => {
+        if (!model) return slice.split('.').pop() ?? slice;
+        const index = model.structure instanceof ApplicationStructureIndex ? model.structure : new ApplicationStructureIndex(model.structure);
+        return index.findSlice(slice)?.id ?? slice.split('.').pop() ?? slice;
+    }, [model, slice]);
+
+    const [values, setValues] = useState<Record<string, string | boolean>>(() => initialValuesOf(fields));
+    const [errors, setErrors] = useState<InvocationValidationError[]>([]);
+    const [submitting, setSubmitting] = useState(false);
+    const form = useRef<HTMLFormElement>(null);
+    const identity = useId();
+
+    const close = (result?: InvocationResult) => onClose ? onClose(result) : navigation?.closeDialog(result);
+
+    // Focus the first field, and give focus back to whatever opened the dialog when it goes.
+    useEffect(() => {
+        const opener = document.activeElement as HTMLElement | null;
+        (form.current?.querySelector<HTMLElement>('input, select, textarea') ?? form.current?.querySelector<HTMLElement>('button'))?.focus();
+        return () => { if (opener && opener.isConnected) opener.focus(); };
+    }, []);
+
+    const errorsOf = (name: string | undefined) => errors.filter(error => error.field === name);
+    const fieldNames = new Set(fields.map(field => field.name));
+    const general = errors.filter(error => error.field === undefined || !fieldNames.has(error.field));
+
+    const submit = async (event: FormEvent) => {
+        event.preventDefault();
+        if (submitting) return;
+
+        const missing = fields.filter(field => field.required && (values[field.name] === undefined || values[field.name] === '')).map(field => ({ field: field.name, message: `${sliceFieldLabel(field)} is required.` }));
+        setErrors(missing);
+        if (missing.length > 0) {
+            form.current?.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus();
+            return;
+        }
+
+        setSubmitting(true);
+        try {
+            const result = await invoker.invoke(slice, slicePayload(fields, values), command);
+            if (result.succeeded) {
+                close(result);
+            } else {
+                const reported = result.validationErrors ?? [];
+                setErrors(reported.length > 0 || !result.message ? reported : [{ message: result.message }]);
+            }
+        } finally {
+            setSubmitting(false);
+        }
+    };
+
+    const onKeyDown = (event: KeyboardEvent<HTMLFormElement>) => {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            close();
+        } else if (event.key === 'Tab') {
+            const targets = Array.from(form.current?.querySelectorAll<HTMLElement>(focusable) ?? []);
+            if (targets.length === 0) return;
+            const first = targets[0];
+            const last = targets[targets.length - 1];
+            if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus(); }
+            else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus(); }
+        }
+    };
+
+    return <form ref={form} className='scene-slice-dialog' data-scene-slice-dialog={slice} data-scene-command={command} noValidate onSubmit={submit} onKeyDown={onKeyDown}>
+        <header className='scene-slice-dialog-header'>
+            <h2 className='scene-slice-dialog-title'>{title}</h2>
+            <p className='scene-slice-dialog-subtitle'>State Change · {sliceName}</p>
+        </header>
+        <div className='scene-slice-dialog-fields'>
+            {fields.map(field => {
+                const id = `${identity}-${field.name}`;
+                const own = errorsOf(field.name);
+                const type = inputTypeOf(field);
+                const description = own.length > 0 ? `${id}-error` : undefined;
+                return <div key={field.name} className='scene-slice-dialog-field' data-type={type}>
+                    <label htmlFor={id}>{sliceFieldLabel(field)}{field.required ? <span aria-hidden='true'> *</span> : null}</label>
+                    <input id={id} name={field.name} type={type} required={field.required} aria-required={field.required || undefined}
+                        aria-invalid={own.length > 0 ? true : undefined} aria-describedby={description}
+                        {...(type === 'checkbox' ? { checked: values[field.name] === true } : { value: (values[field.name] as string | undefined) ?? '' })}
+                        onChange={event => setValues({ ...values, [field.name]: type === 'checkbox' ? event.target.checked : event.target.value })} />
+                    {own.length > 0 && <p id={description} className='scene-slice-dialog-error' role='alert'>{own.map(error => error.message).join(' ')}</p>}
+                </div>;
+            })}
+        </div>
+        {general.length > 0 && <p className='scene-slice-dialog-error scene-slice-dialog-summary' role='alert'>{general.map(error => error.message).join(' ')}</p>}
+        <footer className='scene-slice-dialog-footer'>
+            <button type='button' className='scene-slice-dialog-cancel' onClick={() => close()}>Cancel</button>
+            <button type='submit' className='scene-slice-dialog-submit' disabled={submitting}>{title}</button>
+        </footer>
+    </form>;
+}

package/slices/SliceInvoker.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 { InvocationResult } from './InvocationResult';
+
+/**
+ * Invokes a state change slice with a command payload. This is the seam between the toolbar's task dialogs and whatever
+ * runs the command: Stage provides one that sends it, the Studio preview one that only checks it (`createDryRunInvoker`),
+ * and the default announces it as an event. `@cratis/scene.react` knows no transport.
+ */
+export interface SliceInvoker {
+    /**
+     * Invokes the slice.
+     * @param sliceId The qualified id of the slice, for example `sales.orders.PlaceOrder`.
+     * @param payload The command's values, by property name.
+     * @param command The command the slice accepts, when known.
+     */
+    invoke(sliceId: string, payload: Record<string, unknown>, command?: string): Promise<InvocationResult>;
+}

package/slices/SliceInvokerContext.tsx

@@ -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 { ReactNode, createContext, useContext, useMemo } from 'react';
+import { createAnnouncingInvoker } from './createAnnouncingInvoker';
+import { SliceInvoker } from './SliceInvoker';
+
+interface SliceInvokerScope {
+    invoker: SliceInvoker;
+    warnEmptySlices: boolean;
+}
+
+const announcing = createAnnouncingInvoker();
+const defaultScope: SliceInvokerScope = { invoker: announcing, warnEmptySlices: false };
+const Context = createContext<SliceInvokerScope>(defaultScope);
+
+export interface SliceInvokerProviderProps {
+    /** The invoker toolbar dialogs submit through. */
+    invoker: SliceInvoker;
+
+    /**
+     * Whether a toolbar button without a slice shows a warning badge. Design and preview hosts turn it on (TB5); a
+     * running application never shows it. A dry-run invoker implies it.
+     */
+    warnEmptySlices?: boolean;
+    children?: ReactNode;
+}
+
+/**
+ * Supplies the `sliceInvoker` every toolbar dialog below it submits through: a real one in Stage, a dry-run one in the Studio
+ * preview. Without a provider the command is announced as `cratis.scene.command`.
+ */
+export function SliceInvokerProvider({ invoker, warnEmptySlices, children }: SliceInvokerProviderProps) {
+    const warn = warnEmptySlices ?? (invoker as { dryRun?: boolean }).dryRun === true;
+    const value = useMemo(() => ({ invoker, warnEmptySlices: warn }), [invoker, warn]);
+    return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+/** The invoker in scope: the provider's, or the one that announces the command. */
+export function useSliceInvoker(): SliceInvoker {
+    return useContext(Context).invoker;
+}
+
+/** Whether a button without a slice should show a warning badge here. */
+export function useWarnEmptySlices(): boolean {
+    return useContext(Context).warnEmptySlices;
+}

package/slices/createAnnouncingInvoker.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SliceInvoker } from './SliceInvoker';
+
+/**
+ * The invoker used when a host provides none: it announces the command with the host-neutral `cratis.scene.command` event,
+ * as a `core:toolbarItem` action always has, and reports success. A host that listens for the event runs the command.
+ */
+export function createAnnouncingInvoker(): SliceInvoker {
+    return {
+        async invoke(sliceId, payload, command) {
+            globalThis.dispatchEvent(new CustomEvent('cratis.scene.command', { detail: { command: command ?? sliceId, slice: sliceId, arguments: payload } }));
+            return { succeeded: true, payload };
+        },
+    };
+}

package/slices/createDryRunInvoker.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InvocationValidationError } from './InvocationValidationError';
+import { SliceInvoker } from './SliceInvoker';
+
+/** What a dry run is told about each invocation. */
+export interface DryRunInvocation {
+    /** The qualified id of the slice. */
+    sliceId: string;
+
+    /** The command the slice accepts, when known. */
+    command?: string;
+
+    /** The payload that would have been sent. */
+    payload: Record<string, unknown>;
+}
+
+export interface DryRunInvokerOptions {
+    /** Called for every invocation that passes validation, with the would-be payload - the Studio preview shows it as a toast. */
+    onInvoked?(invocation: DryRunInvocation): void;
+
+    /** Extra validation of the payload; the problems it returns are reported like the real ones and nothing is invoked. */
+    validate?(invocation: DryRunInvocation): InvocationValidationError[];
+}
+
+/**
+ * An invoker that sends nothing (PRV5): it validates, reports what it would have sent and succeeds, so a preview can walk a
+ * toolbar button through its dialog without touching a backend.
+ */
+export function createDryRunInvoker(options: DryRunInvokerOptions = {}): SliceInvoker & { readonly dryRun: true } {
+    return {
+        dryRun: true,
+        async invoke(sliceId, payload, command) {
+            const invocation: DryRunInvocation = { sliceId, payload, ...(command === undefined ? {} : { command }) };
+            const validationErrors = options.validate?.(invocation) ?? [];
+            if (validationErrors.length > 0) return { succeeded: false, validationErrors, payload, dryRun: true };
+
+            options.onInvoked?.(invocation);
+            return { succeeded: true, payload, dryRun: true, message: `Dry run: ${command ?? sliceId} was not sent.` };
+        },
+    };
+}

package/slices/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './InvocationValidationError';
+export * from './InvocationResult';
+export * from './SliceInvoker';
+export * from './createAnnouncingInvoker';
+export * from './createDryRunInvoker';
+export * from './SliceInvokerContext';
+export * from './SliceCommandField';
+export * from './SliceCommandFieldsContext';
+export * from './sliceDialogDestination';
+export * from './SliceDialogView';
+export * from './CoreSliceDialog';

package/slices/sliceDialogDestination.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression, BindingSourceKind, DestinationKind, DestinationReference } from '@cratis/scene.model';
+import { ResolvedToolbarButton } from '@cratis/scene.engine';
+
+const literal = (value: string): BindingExpression => ({ kind: BindingSourceKind.Literal, path: '', value }) as BindingExpression;
+
+/** The dialog parameters a slice dialog is opened with; the navigation host hands them back as `currentDialogParameters`. */
+export interface SliceDialogParameters {
+    slice: string;
+    command: string;
+    title: string;
+}
+
+/**
+ * The destination that opens a toolbar button's task dialog through the navigation host: the dialog template the slice
+ * resolves to (`sliceDialogFor`), with the slice, its command and the button's title as parameters.
+ * @param button The resolved button.
+ * @returns The destination, or undefined when the button has no state change slice to open.
+ */
+export function sliceDialogDestination(button: ResolvedToolbarButton): DestinationReference | undefined {
+    if (!button.dialog) return undefined;
+    return {
+        kind: DestinationKind.Dialog,
+        dialog: button.dialog.template,
+        routeParameterBindings: {
+            slice: literal(button.dialog.slice),
+            command: literal(button.dialog.command),
+            title: literal(button.title),
+        },
+    };
+}
+
+/** Reads the slice dialog parameters back from what the host carries; undefined when they are not those of a slice dialog. */
+export function sliceDialogParameters(parameters: Record<string, string> | undefined): SliceDialogParameters | undefined {
+    const slice = parameters?.slice;
+    const command = parameters?.command;
+    return slice && command ? { slice, command, title: parameters?.title || command } : undefined;
+}