@cratis/scene.react 3.7.0 → 4.1.0

package/interactions/createBrowserDispatcher.ts

@@ -0,0 +1,160 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ActionDispatcher, CommandOutcome, DialogOutcome } from '@cratis/scene.engine';
+import { NotificationLevel } from '@cratis/scene.model';
+
+/**
+ * What a host has to supply for an interaction to reach anything real.
+ *
+ * Every member is optional and every one that is missing is *reported* rather than quietly ignored. A host
+ * that cannot execute commands is a legitimate state - a preview surface, a design tool - but a button that
+ * appears to work and does nothing is not.
+ */
+export interface BrowserDispatcherHost {
+    /** Submits a command. The transport belongs to the host: Scene does not know what a backend is. */
+    executeCommand?: (command: string, args: Record<string, unknown>) => Promise<CommandOutcome>;
+
+    /** Navigates to a screen. The URL belongs to the host, which is why no route is constructed here. */
+    navigate?: (screen: string, args: Record<string, unknown>) => void;
+
+    /** Goes back. */
+    navigateBack?: () => void;
+
+    /** Opens a dialog and answers with what the user did. */
+    openDialog?: (dialogTemplate: string, args: Record<string, unknown>) => Promise<DialogOutcome>;
+
+    /** Closes the open dialog. */
+    closeDialog?: () => void;
+
+    /** Re-runs a query. */
+    refreshQuery?: (query: string) => Promise<void>;
+
+    /** Writes screen state. */
+    setState?: (target: string, value: unknown) => void;
+
+    /** Surfaces a message. Falls back to the console rather than to nothing. */
+    notify?: (level: NotificationLevel, message: string) => void;
+
+    /** Asks the user to confirm. Falls back to the browser's own prompt. */
+    confirm?: (message: string) => Promise<boolean>;
+
+    /** Raises an application trigger. */
+    raise?: (trigger: string, args: Record<string, unknown>) => Promise<void>;
+
+    /** Where an unsupported action is reported. */
+    onUnsupported?: (action: string) => void;
+}
+
+/**
+ * Creates the dispatcher a browser host uses.
+ *
+ * This is the only place in Scene.React that knows an action has to *happen*. Everything about which actions
+ * run and in what order is the engine's, which is why this file is a list of one-line delegations and holds no
+ * rules of its own.
+ *
+ * @param host What the surrounding application can actually do.
+ * @returns The {@link ActionDispatcher}.
+ */
+export function createBrowserDispatcher(host: BrowserDispatcherHost = {}): ActionDispatcher {
+    const unsupported = (action: string) => {
+        host.onUnsupported?.(action);
+        console.warn(`[scene] The host cannot '${action}', so the interaction stopped there.`);
+    };
+
+    return {
+        async executeCommand(command, args) {
+            if (!host.executeCommand) {
+                unsupported(`execute ${command}`);
+
+                // Reported as a failure, so the document's own `on failure` runs. Answering success would
+                // make a command that never reached a backend look like one that worked.
+                return { isSuccess: false, validationErrors: [] };
+            }
+
+            return host.executeCommand(command, args);
+        },
+
+        navigate(screen, args) {
+            if (host.navigate) {
+                host.navigate(screen, args);
+                return;
+            }
+
+            unsupported(`navigate to ${screen}`);
+        },
+
+        navigateBack() {
+            if (host.navigateBack) {
+                host.navigateBack();
+                return;
+            }
+
+            unsupported('navigate back');
+        },
+
+        async openDialog(dialogTemplate, args) {
+            if (!host.openDialog) {
+                unsupported(`open dialog ${dialogTemplate}`);
+                return { isConfirmed: false };
+            }
+
+            return host.openDialog(dialogTemplate, args);
+        },
+
+        closeDialog() {
+            if (host.closeDialog) {
+                host.closeDialog();
+                return;
+            }
+
+            unsupported('close dialog');
+        },
+
+        async refreshQuery(query) {
+            if (host.refreshQuery) {
+                await host.refreshQuery(query);
+                return;
+            }
+
+            unsupported(`refresh ${query}`);
+        },
+
+        setState(target, value) {
+            if (host.setState) {
+                host.setState(target, value);
+                return;
+            }
+
+            unsupported(`set ${target}`);
+        },
+
+        notify(level, message) {
+            if (host.notify) {
+                host.notify(level, message);
+                return;
+            }
+
+            // The console is a poor notification, but it is a real one - and a host that has not wired
+            // notifications yet should still see what the document wanted to say.
+            console.log(`[scene:${level}] ${message}`);
+        },
+
+        async confirm(message) {
+            if (host.confirm) return host.confirm(message);
+
+            // The browser's own prompt is the honest default: a confirm exists to gate what follows, so
+            // answering `true` without asking anyone would remove the gate rather than approximate it.
+            return typeof globalThis.confirm === 'function' ? globalThis.confirm(message) : false;
+        },
+
+        async raise(trigger, args) {
+            if (host.raise) {
+                await host.raise(trigger, args);
+                return;
+            }
+
+            unsupported(`raise ${trigger}`);
+        },
+    };
+}

package/interactions/index.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.
+
+export * from './InteractionScope';
+export * from './useInteractions';
+export * from './createBrowserDispatcher';
+export * from './ConfirmHost';
+export * from './ConfirmRequest';
+export * from './NotificationHost';
+export * from './SceneNotification';
+export * from './UnresolvedAction';
+export * from './UnresolvedActionHost';
+export * from './useInteractionHosts';

package/interactions/useInteractionHosts.tsx

@@ -0,0 +1,101 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, useCallback, useMemo, useRef, useState } from 'react';
+import { NotificationLevel } from '@cratis/scene.model';
+import { BrowserDispatcherHost } from './createBrowserDispatcher';
+import { ConfirmHost } from './ConfirmHost';
+import { ConfirmRequest } from './ConfirmRequest';
+import { NotificationHost } from './NotificationHost';
+import { SceneNotification } from './SceneNotification';
+import { UnresolvedAction } from './UnresolvedAction';
+import { UnresolvedActionHost } from './UnresolvedActionHost';
+
+/**
+ * What {@link useInteractionHosts} gives an application.
+ */
+export interface InteractionHosts {
+    /** The parts of a {@link BrowserDispatcherHost} these surfaces provide. Spread it into the host you build. */
+    readonly host: Pick<BrowserDispatcherHost, 'notify' | 'confirm' | 'onUnsupported'>;
+
+    /** The surfaces themselves. Render them once, anywhere inside the application. */
+    readonly surfaces: ReactNode;
+}
+
+/**
+ * How long a notification stays before it removes itself, in milliseconds.
+ */
+export interface InteractionHostOptions {
+    /** How long a notification stays up. `0` keeps it until it is dismissed. */
+    readonly dismissAfter?: number;
+}
+
+/**
+ * Provides the default surfaces for the actions that need somewhere to appear.
+ *
+ * `notify` and `confirm` are the two actions a document can take that have no backend and no route: they are
+ * purely things the user sees. Without a surface, a host either invents one or the action goes to the console,
+ * which is why these ship with Scene rather than being every application's first chore.
+ *
+ * The three are returned as one unit because they are wired the same way and forgetting to render one of them
+ * is exactly the failure they exist to prevent:
+ *
+ * ```tsx
+ * const { host, surfaces } = useInteractionHosts();
+ * const dispatcher = useMemo(() => createBrowserDispatcher({ ...host, executeCommand, navigate }), [host]);
+ *
+ * return <InteractionScope dispatcher={dispatcher}>{children}{surfaces}</InteractionScope>;
+ * ```
+ *
+ * An application with a design system of its own passes its own `notify` after the spread and keeps the rest.
+ * @param options The {@link InteractionHostOptions}.
+ * @returns The {@link InteractionHosts}.
+ */
+export function useInteractionHosts(options: InteractionHostOptions = {}): InteractionHosts {
+    const { dismissAfter = 6000 } = options;
+    const [notifications, setNotifications] = useState<readonly SceneNotification[]>([]);
+    const [unresolved, setUnresolved] = useState<readonly UnresolvedAction[]>([]);
+    const [request, setRequest] = useState<ConfirmRequest | undefined>(undefined);
+    const nextId = useRef(0);
+
+    const dismiss = useCallback((id: number) => setNotifications(current => current.filter(_ => _.id !== id)), []);
+
+    const notify = useCallback((level: NotificationLevel, message: string) => {
+        const id = nextId.current++;
+        setNotifications(current => [...current, { id, level, message }]);
+
+        if (dismissAfter > 0) {
+            setTimeout(() => setNotifications(current => current.filter(_ => _.id !== id)), dismissAfter);
+        }
+    }, [dismissAfter]);
+
+    const confirm = useCallback((message: string) => new Promise<boolean>(resolve => {
+        setRequest({
+            message,
+            answer(confirmed) {
+                // Cleared before resolving, so the sequence that continues cannot find a question on screen
+                // that has already been answered.
+                setRequest(undefined);
+                resolve(confirmed);
+            },
+        });
+    }), []);
+
+    const onUnsupported = useCallback((action: string) => {
+        // Reported once per distinct action. An unsupported action on a hover or an interval would otherwise
+        // grow the list until it covered the application it is trying to tell you about.
+        setUnresolved(current => current.some(_ => _.action === action) ? current : [...current, { id: nextId.current++, action }]);
+    }, []);
+
+    const host = useMemo(() => ({ notify, confirm, onUnsupported }), [notify, confirm, onUnsupported]);
+
+    const surfaces = useMemo(() => (
+        <>
+            <NotificationHost notifications={notifications} onDismiss={dismiss} />
+            <ConfirmHost request={request} />
+            <UnresolvedActionHost unresolved={unresolved} />
+        </>
+    ), [notifications, dismiss, request, unresolved]);
+
+    return { host, surfaces };
+}

package/interactions/useInteractions.ts

@@ -0,0 +1,116 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCallback, useEffect, useMemo } from 'react';
+import { BehaviorAttachment, resolveBehaviors, resolveIntervalBehaviors, runBindings } from '@cratis/scene.engine';
+import { Behavior, InteractionTriggerKind } from '@cratis/scene.model';
+import { attachmentFor, useInteractionScope } from './InteractionScope';
+
+/**
+ * The DOM handlers an element should spread onto whatever it renders.
+ *
+ * Only the handlers a document actually asks for are present. An element with no `on click` gets no `onClick`,
+ * so it does not become clickable - and, just as importantly, does not swallow the click from something
+ * enclosing it that does.
+ */
+export interface InteractionHandlers {
+    onClick?: (event: { stopPropagation(): void }) => void;
+    onDoubleClick?: (event: { stopPropagation(): void }) => void;
+    onChange?: () => void;
+    onSubmit?: (event: { preventDefault(): void }) => void;
+    onSelect?: () => void;
+}
+
+const domTriggers: [keyof InteractionHandlers, InteractionTriggerKind][] = [
+    ['onClick', InteractionTriggerKind.Click],
+    ['onDoubleClick', InteractionTriggerKind.DoubleClick],
+    ['onChange', InteractionTriggerKind.Change],
+    ['onSubmit', InteractionTriggerKind.Submit],
+    ['onSelect', InteractionTriggerKind.Select],
+];
+
+/**
+ * Wires the behaviors attached to an element to the events that start them.
+ *
+ * The hook resolves and runs; it decides nothing. Which bindings a trigger runs, in what order, and where a
+ * sequence stops are all the engine's, so a different renderer inherits the same semantics instead of
+ * reimplementing them - and so all of it stays testable without a DOM.
+ *
+ * Lifecycle triggers are handled here rather than by the caller because React is what knows when an element
+ * mounts: `load` and `unload` follow the element, and `enter` and `leave` follow the screen. An `interval`
+ * becomes a timer that is cleared on unmount, because a document declaring one is asking for it to run while
+ * the thing it is attached to is on screen and not afterwards.
+ *
+ * @param level What is being attached to, used when reporting a finding.
+ * @param behaviors The behaviors attached to this element.
+ * @returns The handlers to spread onto the rendered element.
+ */
+export function useInteractions(level: string, behaviors?: Behavior[]): InteractionHandlers {
+    const scope = useInteractionScope();
+
+    const attachments = useMemo<BehaviorAttachment[]>(
+        () => [...(scope?.attachments ?? []), ...attachmentFor(level, behaviors)],
+        [scope, level, behaviors]);
+
+    const run = useCallback(async (kind: InteractionTriggerKind) => {
+        if (!scope) return;
+
+        const result = await runBindings(resolveBehaviors(attachments, kind), scope.dispatcher, scope.context);
+        if (result.findings.length > 0) scope.onFindings?.(result.findings);
+    }, [scope, attachments]);
+
+    // Mount and unmount, for the element and for the screen it is on. Running the unload and leave bindings
+    // from the cleanup is what makes them reliable: React guarantees it, a component remembering to call
+    // something on the way out does not.
+    useEffect(() => {
+        void run(InteractionTriggerKind.Load);
+        void run(InteractionTriggerKind.Enter);
+
+        return () => {
+            void run(InteractionTriggerKind.Unload);
+            void run(InteractionTriggerKind.Leave);
+        };
+    }, [run]);
+
+    useEffect(() => {
+        const intervals = resolveIntervalBehaviors(attachments);
+        if (intervals.length === 0 || !scope) return;
+
+        const timers = intervals.map(candidate => {
+            const seconds = (candidate.binding.trigger as { seconds?: number }).seconds ?? 0;
+            return setInterval(
+                () => void runBindings([candidate], scope.dispatcher, scope.context),
+                Math.max(seconds, 1) * 1000);
+        });
+
+        return () => timers.forEach(clearInterval);
+    }, [attachments, scope]);
+
+    return useMemo(() => {
+        const handlers: InteractionHandlers = {};
+        if (!scope) return handlers;
+
+        for (const [handler, kind] of domTriggers) {
+            // Nothing attached for this trigger means no handler at all. Attaching an empty one would make
+            // every element look interactive and would stop clicks reaching whatever encloses it.
+            if (resolveBehaviors(attachments, kind).length === 0) continue;
+
+            if (handler === 'onSubmit') {
+                handlers.onSubmit = event => {
+                    event.preventDefault();
+                    void run(kind);
+                };
+                continue;
+            }
+
+            handlers[handler] = ((event?: { stopPropagation(): void }) => {
+                // An interaction that ran here is handled here. Without this, a click on a row inside a table
+                // that both declare `on click` would run the table's twice: once for the row, once on the way up.
+                event?.stopPropagation();
+                void run(kind);
+            }) as never;
+        }
+
+        return handlers;
+    }, [scope, attachments, run]);
+}

package/package.json

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

package/renderer/ComponentRegistry.ts

@@ -3,6 +3,7 @@
 
 import { ComponentType, ReactNode } from 'react';
 import { ExternalComponent } from '@cratis/scene.model';
+import { InteractionHandlers } from '../interactions';
 
 /**
  * The props every registered component receives.
@@ -10,6 +11,16 @@ import { ExternalComponent } from '@cratis/scene.model';
 export interface RegisteredComponentProps {
     element: ExternalComponent;
     slots: Record<string, ReactNode[]>;
+
+    /**
+     * The handlers for whatever the document attached to this element, to spread onto the node they belong on.
+     *
+     * Passed to the component rather than applied by the renderer because only the component knows which node
+     * that is - on a button it is the button, on a table it is the row. It is empty when the document attached
+     * nothing, and absent when the component is rendered directly rather than through the renderer - a
+     * specification, or a gallery. Spreading it is safe either way.
+     */
+    interactions?: InteractionHandlers;
 }
 
 /**

package/renderer/InteractiveComponent.tsx

@@ -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 { ComponentType, ReactNode, createElement } from 'react';
+import { ExternalComponent } from '@cratis/scene.model';
+import { useInteractions } from '../interactions';
+import { RegisteredComponentProps } from './ComponentRegistry';
+
+export interface InteractiveComponentProps {
+    component: ComponentType<RegisteredComponentProps>;
+    element: ExternalComponent;
+    slots: Record<string, ReactNode[]>;
+}
+
+/**
+ * Resolves an element's interactions and hands them to the component that renders it.
+ *
+ * This exists as a component rather than as a call inside the renderer because resolving them is a hook, and a
+ * hook cannot run inside the plain function a {@link Renderer} is. Keeping the renderer plain is what lets the
+ * same element tree be rendered by something that is not React at all.
+ */
+export function InteractiveComponent({ component, element, slots }: InteractiveComponentProps) {
+    const interactions = useInteractions(element.id, element.behaviors);
+    return createElement(component, { element, slots, interactions });
+}

package/renderer/createReactRenderer.tsx

@@ -5,6 +5,7 @@ import { ReactNode, createElement } from 'react';
 import { Renderer } from '@cratis/scene.engine';
 import { ContentControl, ExternalComponent, ItemsControl, Panel } from '@cratis/scene.model';
 import { ComponentRegistry } from './ComponentRegistry';
+import { InteractiveComponent } from './InteractiveComponent';
 import { childStyle, panelStyle } from './panelLayout';
 import { UnresolvedComponent } from './UnresolvedComponent';
 
@@ -28,7 +29,7 @@ export function createReactRenderer(registry: ComponentRegistry): Renderer<React
 
         renderExternalComponent(element: ExternalComponent, slots: Record<string, ReactNode[]>): ReactNode {
             const Component = registry[element.componentName] ?? UnresolvedComponent;
-            return createElement(Component, { key: element.id, element, slots });
+            return createElement(InteractiveComponent, { key: element.id, component: Component, element, slots });
         },
 
         renderPanel(element: Panel, children: ReactNode[]): ReactNode {

package/renderer/index.ts

@@ -4,3 +4,4 @@
 export * from './ComponentRegistry';
 export * from './UnresolvedComponent';
 export * from './createReactRenderer';
+export * from './InteractiveComponent';