@cratis/scene.react 3.6.0 → 4.0.0

package/for_useInteractions/when_clicking_an_element_that_executes_a_command.tsx

@@ -0,0 +1,141 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ActionDispatcher, CommandOutcome, InteractionContext } from '@cratis/scene.engine';
+import { Behavior, InteractionActionKind, InteractionTriggerKind, NotificationLevel } from '@cratis/scene.model';
+import { InteractionScope, useInteractions } from '../interactions';
+
+const calls: string[] = [];
+
+const dispatcher = {
+    async executeCommand(command: string, args: Record<string, unknown>): Promise<CommandOutcome> {
+        calls.push(`executeCommand:${command}:${JSON.stringify(args)}`);
+        return { isSuccess: true };
+    },
+    navigate: (screenName: string) => { calls.push(`navigate:${screenName}`); },
+    navigateBack: () => { calls.push('navigateBack'); },
+    openDialog: async () => { calls.push('openDialog'); return { isConfirmed: true }; },
+    closeDialog: () => { calls.push('closeDialog'); },
+    refreshQuery: async (query: string) => { calls.push(`refreshQuery:${query}`); },
+    setState: (target: string) => { calls.push(`setState:${target}`); },
+    notify: (level: NotificationLevel, message: string) => { calls.push(`notify:${level}:${message}`); },
+    confirm: async () => { calls.push('confirm'); return true; },
+    raise: async (trigger: string) => { calls.push(`raise:${trigger}`); },
+} satisfies ActionDispatcher;
+
+const context: InteractionContext = { resolve: binding => `<${binding.path}>` };
+
+const cancelOnClick: Behavior = {
+    name: 'CancelInvoice',
+    bindings: [
+        {
+            trigger: { kind: InteractionTriggerKind.Click } as never,
+            actions: [
+                {
+                    kind: InteractionActionKind.ExecuteCommand,
+                    command: 'CancelInvoice',
+                    arguments: [{ name: 'invoiceId', value: { path: 'item.invoiceId' } }],
+                    onSuccess: [{ kind: InteractionActionKind.RefreshQuery, query: 'Invoices' }],
+                } as never,
+            ],
+        },
+    ],
+};
+
+function Button({ behaviors }: { behaviors?: Behavior[] }) {
+    const handlers = useInteractions('element', behaviors);
+    return <button type="button" {...handlers}>Cancel</button>;
+}
+
+function renderInScope(behaviors?: Behavior[]) {
+    return render(
+        <InteractionScope dispatcher={dispatcher} context={context} attachments={[]}>
+            <Button behaviors={behaviors} />
+        </InteractionScope>
+    );
+}
+
+describe('when clicking an element that executes a command', () => {
+    beforeEach(() => { calls.length = 0; });
+
+    // The whole point of everything beneath this: a document said what a click does, and a click does it.
+    it('should execute the command the document declared', async () => {
+        renderInScope([cancelOnClick]);
+
+        await userEvent.click(screen.getByRole('button'));
+
+        calls.should.eql(['executeCommand:CancelInvoice:{"invoiceId":"<item.invoiceId>"}', 'refreshQuery:Invoices']);
+    });
+
+    it('should not make an element interactive when nothing is attached', async () => {
+        renderInScope();
+
+        await userEvent.click(screen.getByRole('button'));
+        calls.should.have.lengthOf(0);
+    });
+
+    // A handler attached for a trigger the document never mentioned would swallow the event from whatever
+    // encloses the element, which is a bug you find by accident and spend an afternoon on.
+    it('should attach no handler for a trigger the document does not use', async () => {
+        renderInScope([cancelOnClick]);
+
+        await userEvent.dblClick(screen.getByRole('button'));
+
+        // The two clicks a double click is made of still run the click binding - that is what a double click
+        // is. What must not happen is a double-click handler existing when no binding asked for one.
+        calls.filter(call => call.startsWith('executeCommand')).should.have.lengthOf(2);
+    });
+
+    it('should run a behavior attached further out as well as its own', async () => {
+        render(
+            <InteractionScope
+                dispatcher={dispatcher}
+                context={context}
+                attachments={[{
+                    level: 'module',
+                    behaviors: [{
+                        name: 'ModuleWide',
+                        bindings: [{
+                            trigger: { kind: InteractionTriggerKind.Click } as never,
+                            actions: [{ kind: InteractionActionKind.Notify, level: NotificationLevel.Info, message: { text: 'from the module' } } as never],
+                        }],
+                    }],
+                }]}>
+                <Button behaviors={[cancelOnClick]} />
+            </InteractionScope>
+        );
+
+        await userEvent.click(screen.getByRole('button'));
+
+        calls.should.eql([
+            'notify:Info:from the module',
+            'executeCommand:CancelInvoice:{"invoiceId":"<item.invoiceId>"}',
+            'refreshQuery:Invoices',
+        ]);
+    });
+
+    it('should not run a binding whose guard is false', async () => {
+        render(
+            <InteractionScope
+                dispatcher={dispatcher}
+                // The guard has to actually resolve to false; a context echoing the path would make every
+                // guard a non-empty string, and so always true.
+                context={{ resolve: () => false }}
+                attachments={[]}>
+                <Button behaviors={[{
+            name: 'Guarded',
+            bindings: [{
+                trigger: { kind: InteractionTriggerKind.Click } as never,
+                condition: { path: 'item.canCancel' },
+                actions: [{ kind: InteractionActionKind.ExecuteCommand, command: 'CancelInvoice' } as never],
+            }],
+                }]} />
+            </InteractionScope>
+        );
+
+        await userEvent.click(screen.getByRole('button'));
+        calls.should.have.lengthOf(0);
+    });
+});

package/index.ts

@@ -7,3 +7,4 @@ export * from './core';
 export * from './NavBar';
 export * from './packages';
 export * from './theme';
+export * from './interactions';

package/interactions/InteractionScope.tsx

@@ -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 { ReactNode, createContext, useContext, useMemo } from 'react';
+import { ActionDispatcher, BehaviorAttachment, InteractionContext, InteractionFinding } from '@cratis/scene.engine';
+import { Behavior } from '@cratis/scene.model';
+
+/**
+ * What the elements beneath a scope need in order to run an interaction.
+ */
+export interface InteractionScopeValue {
+    /** The seam that performs the effects. */
+    dispatcher: ActionDispatcher;
+
+    /** How bindings and localization resolve. */
+    context: InteractionContext;
+
+    /** The attachments enclosing this point, outermost first. */
+    attachments: BehaviorAttachment[];
+
+    /** Where a finding goes. Absent means nothing is listening, which is itself worth knowing. */
+    onFindings?: (findings: InteractionFinding[]) => void;
+}
+
+const Scope = createContext<InteractionScopeValue | undefined>(undefined);
+
+export interface InteractionScopeProps extends InteractionScopeValue {
+    children: ReactNode;
+}
+
+/**
+ * Provides the dispatcher, the resolution context and the enclosing attachments to everything beneath it.
+ *
+ * Attachments nest: a scope inside another scope appends to it rather than replacing it, so an element's
+ * enclosing chain is assembled by the tree rather than reconstructed at each leaf. That is what keeps the
+ * additive rule true in a renderer - a module's behavior is still in scope at a button six levels down,
+ * without the button knowing the module exists.
+ */
+export function InteractionScope({ children, dispatcher, context, attachments, onFindings }: InteractionScopeProps) {
+    const enclosing = useContext(Scope);
+
+    const value = useMemo<InteractionScopeValue>(() => ({
+        dispatcher,
+        context,
+        attachments: [...(enclosing?.attachments ?? []), ...attachments],
+        onFindings: onFindings ?? enclosing?.onFindings,
+    }), [dispatcher, context, attachments, onFindings, enclosing]);
+
+    return <Scope.Provider value={value}>{children}</Scope.Provider>;
+}
+
+/**
+ * Reads the enclosing interaction scope.
+ *
+ * @returns The scope, or `undefined` when the tree is rendered without one.
+ * @remarks
+ * Rendering without a scope is legitimate - a preview surface showing what a screen looks like has nothing to
+ * dispatch to - so this answers `undefined` rather than throwing. What must not happen is an element silently
+ * appearing interactive when nothing can run; {@link useInteractions} is where that is decided.
+ */
+export function useInteractionScope(): InteractionScopeValue | undefined {
+    return useContext(Scope);
+}
+
+/**
+ * Builds the attachment list for one element, so a caller does not have to know the shape.
+ *
+ * @param level What is being attached to, used when reporting.
+ * @param behaviors The behaviors attached there.
+ * @returns The attachment, or an empty list when there are none.
+ */
+export function attachmentFor(level: string, behaviors?: Behavior[]): BehaviorAttachment[] {
+    return behaviors && behaviors.length > 0 ? [{ level, behaviors }] : [];
+}

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,6 @@
+// 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';

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.6.0",
+    "version": "4.0.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.6.0",
-        "@cratis/scene.model": "3.6.0"
+        "@cratis/scene.engine": "4.0.0",
+        "@cratis/scene.model": "4.0.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "3.6.0",
-        "@cratis/scene.model": "3.6.0",
+        "@cratis/scene.engine": "4.0.0",
+        "@cratis/scene.model": "4.0.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';