@cratis/scene.react 4.0.0 → 4.1.1

package/for_useInteractionHosts/when_a_document_asks_the_user_something.tsx

@@ -0,0 +1,106 @@
+// 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, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useMemo } from 'react';
+import { InteractionActionKind, InteractionTriggerKind, Behavior, NotificationLevel } from '@cratis/scene.model';
+import { InteractionScope, createBrowserDispatcher, useInteractionHosts, useInteractions } from '../interactions';
+
+const executed: string[] = [];
+
+const confirmThenExecute: Behavior = {
+    name: 'CancelInvoice',
+    bindings: [
+        {
+            trigger: { kind: InteractionTriggerKind.Click } as never,
+            actions: [
+                { kind: InteractionActionKind.Confirm, message: { text: 'Cancel this invoice?' } } as never,
+                { kind: InteractionActionKind.ExecuteCommand, command: 'CancelInvoice' } as never,
+                { kind: InteractionActionKind.Notify, level: NotificationLevel.Info, message: { text: 'Invoice cancelled' } } as never,
+            ],
+        },
+    ],
+};
+
+function Button({ behaviors }: { behaviors: Behavior[] }) {
+    const handlers = useInteractions('element', behaviors);
+    return <button type="button" {...handlers}>Cancel</button>;
+}
+
+function Application({ behaviors }: { behaviors: Behavior[] }) {
+    const { host, surfaces } = useInteractionHosts();
+    const dispatcher = useMemo(() => createBrowserDispatcher({
+        ...host,
+        executeCommand: async command => {
+            executed.push(command);
+            return { isSuccess: true };
+        },
+    }), [host]);
+
+    return (
+        <InteractionScope dispatcher={dispatcher} attachments={[]}>
+            <Button behaviors={behaviors} />
+            {surfaces}
+        </InteractionScope>
+    );
+}
+
+describe('when a document asks the user something', () => {
+    beforeEach(() => { executed.length = 0; });
+
+    it('should ask in the page rather than in a browser prompt', async () => {
+        render(<Application behaviors={[confirmThenExecute]} />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+
+        screen.getByRole('alertdialog').getAttribute('aria-label')!.should.equal('Cancel this invoice?');
+    });
+
+    // The reason a confirm exists at all: what follows it runs only if the answer was yes.
+    it('should not run what follows until the question is answered', async () => {
+        render(<Application behaviors={[confirmThenExecute]} />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+
+        executed.should.have.lengthOf(0);
+    });
+
+    it('should run what follows when the answer is yes', async () => {
+        render(<Application behaviors={[confirmThenExecute]} />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+        await userEvent.click(screen.getByRole('button', { name: 'OK' }));
+
+        executed.should.eql(['CancelInvoice']);
+    });
+
+    it('should abandon the sequence when the answer is no', async () => {
+        render(<Application behaviors={[confirmThenExecute]} />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+        // Two buttons say 'Cancel' now - the modelled one and the declining choice - so the question has to
+        // be answered through the dialog it belongs to.
+        await userEvent.click(within(screen.getByRole('alertdialog')).getByRole('button', { name: 'Cancel' }));
+
+        executed.should.have.lengthOf(0);
+    });
+
+    it('should take the question down once it is answered', async () => {
+        render(<Application behaviors={[confirmThenExecute]} />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+        await userEvent.click(screen.getByRole('button', { name: 'OK' }));
+
+        (screen.queryByRole('alertdialog') === null).should.equal(true);
+    });
+
+    it('should show what the document said after the command ran', async () => {
+        render(<Application behaviors={[confirmThenExecute]} />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+        await userEvent.click(screen.getByRole('button', { name: 'OK' }));
+
+        screen.getByText('Invoice cancelled').textContent!.should.equal('Invoice cancelled');
+    });
+});

package/for_useInteractionHosts/when_the_host_cannot_do_what_was_asked.tsx

@@ -0,0 +1,66 @@
+// 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 { useMemo } from 'react';
+import { InteractionActionKind, InteractionTriggerKind, Behavior } from '@cratis/scene.model';
+import { InteractionScope, createBrowserDispatcher, useInteractionHosts, useInteractions } from '../interactions';
+
+const navigateSomewhere: Behavior = {
+    name: 'GoToInvoice',
+    bindings: [
+        {
+            trigger: { kind: InteractionTriggerKind.Click } as never,
+            actions: [{ kind: InteractionActionKind.Navigate, screen: 'InvoiceDetails' } as never],
+        },
+    ],
+};
+
+function Button() {
+    const handlers = useInteractions('element', [navigateSomewhere]);
+    return <button type="button" {...handlers}>Open</button>;
+}
+
+/**
+ * A host that can do nothing at all - a preview surface, or an application half-way through being wired.
+ */
+function Application() {
+    const { host, surfaces } = useInteractionHosts();
+    const dispatcher = useMemo(() => createBrowserDispatcher(host), [host]);
+
+    return (
+        <InteractionScope dispatcher={dispatcher} attachments={[]}>
+            <Button />
+            {surfaces}
+        </InteractionScope>
+    );
+}
+
+describe('when the host cannot do what was asked', () => {
+    it('should say so on the screen rather than do nothing', async () => {
+        render(<Application />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Open' }));
+
+        screen.getByText('navigate to InvoiceDetails').textContent!.should.equal('navigate to InvoiceDetails');
+    });
+
+    // A trigger that repeats would otherwise grow the report until it covered the application it is
+    // describing, which turns a useful warning into something to be closed without reading.
+    it('should report the same action once however often it is asked for', async () => {
+        render(<Application />);
+
+        await userEvent.click(screen.getByRole('button', { name: 'Open' }));
+        await userEvent.click(screen.getByRole('button', { name: 'Open' }));
+        await userEvent.click(screen.getByRole('button', { name: 'Open' }));
+
+        screen.getAllByText('navigate to InvoiceDetails').should.have.lengthOf(1);
+    });
+
+    it('should say nothing when nothing has failed', () => {
+        render(<Application />);
+
+        (screen.queryByText(/cannot do what the document asked/) === null).should.equal(true);
+    });
+});

package/interactions/ConfirmHost.tsx

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConfirmRequest } from './ConfirmRequest';
+
+/**
+ * The properties of {@link ConfirmHost}.
+ */
+export interface ConfirmHostProps {
+    /** The question waiting on an answer, or `undefined` when nothing is being asked. */
+    readonly request?: ConfirmRequest;
+
+    /** The label on the agreeing choice. */
+    readonly confirmLabel?: string;
+
+    /** The label on the declining choice. */
+    readonly cancelLabel?: string;
+}
+
+/**
+ * Asks what a document's `confirm` asked, in the page rather than in a browser prompt.
+ *
+ * The browser's own prompt blocks the event loop and cannot be styled or tested, which is why it is the
+ * fallback and not this. Declining is the default action, so dismissing the question stops the sequence - a
+ * confirm exists to gate what follows it, and a gate that opens when ignored is not one.
+ * @param props The {@link ConfirmHostProps}.
+ */
+export function ConfirmHost({ request, confirmLabel = 'OK', cancelLabel = 'Cancel' }: ConfirmHostProps) {
+    if (!request) return null;
+
+    return (
+        <div data-scene-confirm style={{ position: 'fixed', inset: 0, display: 'flex', alignItems: 'center', justifyContent: 'center', background: 'rgba(0,0,0,0.35)', zIndex: 1100 }}>
+            <div role="alertdialog" aria-modal="true" aria-label={request.message} style={{ minWidth: '18rem', maxWidth: '28rem', padding: '1rem', borderRadius: 4, background: '#fff', color: '#1a1a1a' }}>
+                <p style={{ margin: '0 0 1rem' }}>{request.message}</p>
+                <div style={{ display: 'flex', justifyContent: 'flex-end', gap: '0.5rem' }}>
+                    <button type="button" onClick={() => request.answer(false)}>{cancelLabel}</button>
+                    <button type="button" onClick={() => request.answer(true)}>{confirmLabel}</button>
+                </div>
+            </div>
+        </div>
+    );
+}

package/interactions/ConfirmRequest.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.
+
+/**
+ * A question an interaction is waiting on the answer to.
+ *
+ * The sequence that asked is suspended until {@link answer} is called, which is the whole point of a confirm:
+ * everything after it in the document runs only if the answer was yes.
+ */
+export interface ConfirmRequest {
+    /** What the document asked, already resolved against the interaction's context. */
+    readonly message: string;
+
+    /**
+     * Answers the question and lets the suspended sequence continue.
+     * @param confirmed Whether the user agreed.
+     */
+    answer(confirmed: boolean): void;
+}

package/interactions/InteractionScope.tsx

@@ -22,9 +22,29 @@ export interface InteractionScopeValue {
     onFindings?: (findings: InteractionFinding[]) => void;
 }
 
+/**
+ * The context a scope uses when it was given none.
+ *
+ * A document whose messages are literal text and whose actions take no arguments resolves nothing, and that is
+ * an ordinary document rather than a degenerate one. Requiring a context anyway would make every host invent
+ * an empty resolver, and an invented one is a place for a mistake to hide.
+ */
+const resolvesNothing: InteractionContext = { resolve: () => undefined };
+
 const Scope = createContext<InteractionScopeValue | undefined>(undefined);
 
-export interface InteractionScopeProps extends InteractionScopeValue {
+/**
+ * The properties of {@link InteractionScope}.
+ *
+ * The context is the one thing an author may leave out, because a document whose messages are literal text and
+ * whose actions take no arguments resolves nothing. Everything beneath a scope still reads a context that is
+ * definitely there, so only the author is spared, not the code doing the work.
+ */
+export interface InteractionScopeProps extends Omit<InteractionScopeValue, 'context'> {
+    /** How bindings and localization resolve. Omitted means nothing resolves. */
+    context?: InteractionContext;
+
+    /** What the scope encloses. */
     children: ReactNode;
 }
 
@@ -36,7 +56,7 @@ export interface InteractionScopeProps extends InteractionScopeValue {
  * 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) {
+export function InteractionScope({ children, dispatcher, context = resolvesNothing, attachments, onFindings }: InteractionScopeProps) {
     const enclosing = useContext(Scope);
 
     const value = useMemo<InteractionScopeValue>(() => ({

package/interactions/NotificationHost.tsx

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NotificationLevel } from '@cratis/scene.model';
+import { SceneNotification } from './SceneNotification';
+
+/**
+ * The properties of {@link NotificationHost}.
+ */
+export interface NotificationHostProps {
+    /** What is currently being said, oldest first. */
+    readonly notifications: readonly SceneNotification[];
+
+    /** Called when one is dismissed. */
+    readonly onDismiss: (id: number) => void;
+}
+
+const colours: Record<NotificationLevel, string> = {
+    [NotificationLevel.Info]: '#1e6fbf',
+    [NotificationLevel.Warning]: '#b8860b',
+    [NotificationLevel.Error]: '#c0392b',
+};
+
+/**
+ * Shows what a document's `notify` asked to say.
+ *
+ * Deliberately plain. An application with a design system of its own passes its own `notify` to the dispatcher
+ * and never renders this; what this exists for is that the default is *something* rather than a console line
+ * nobody is looking at.
+ * @param props The {@link NotificationHostProps}.
+ */
+export function NotificationHost({ notifications, onDismiss }: NotificationHostProps) {
+    if (notifications.length === 0) return null;
+
+    return (
+        <div role="log" aria-live="polite" data-scene-notifications style={{ position: 'fixed', top: '1rem', right: '1rem', display: 'flex', flexDirection: 'column', gap: '0.5rem', zIndex: 1000 }}>
+            {notifications.map(notification => (
+                <div
+                    key={notification.id}
+                    data-scene-notification={notification.level}
+                    style={{ display: 'flex', alignItems: 'center', gap: '0.75rem', maxWidth: '24rem', padding: '0.625rem 0.75rem', borderRadius: 4, border: `1px solid ${colours[notification.level]}`, borderLeftWidth: 4, background: '#fff', color: '#1a1a1a' }}>
+                    <span style={{ flex: 1 }}>{notification.message}</span>
+                    <button type="button" aria-label="Dismiss" onClick={() => onDismiss(notification.id)} style={{ border: 'none', background: 'none', cursor: 'pointer', fontSize: '1rem', lineHeight: 1 }}>x</button>
+                </div>
+            ))}
+        </div>
+    );
+}

package/interactions/SceneNotification.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NotificationLevel } from '@cratis/scene.model';
+
+/**
+ * Something a document asked to be said, waiting to be seen.
+ */
+export interface SceneNotification {
+    /** Identifies the notification for the lifetime of the surface showing it. */
+    readonly id: number;
+
+    /** How the document classified it. */
+    readonly level: NotificationLevel;
+
+    /** What it says, already resolved against the interaction's context. */
+    readonly message: string;
+}

package/interactions/UnresolvedAction.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.
+
+/**
+ * An action a document asked for that this host cannot carry out.
+ *
+ * Kept as data rather than written straight to the console, so a surface can show it. A modelled button that
+ * silently does nothing is the hardest kind of defect to trace back to its cause: nothing failed, so nothing
+ * was reported, and the document looks correct because it is.
+ */
+export interface UnresolvedAction {
+    /** Identifies the report for the lifetime of the surface showing it. */
+    readonly id: number;
+
+    /** What the document asked for, phrased as the document phrased it. */
+    readonly action: string;
+}

package/interactions/UnresolvedActionHost.tsx

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UnresolvedAction } from './UnresolvedAction';
+
+/**
+ * The properties of {@link UnresolvedActionHost}.
+ */
+export interface UnresolvedActionHostProps {
+    /** What has been asked for and could not be done. */
+    readonly unresolved: readonly UnresolvedAction[];
+}
+
+/**
+ * Shows what a document asked for that this host cannot do.
+ *
+ * Only useful while an application is being built, which is why an application that has wired everything will
+ * never see it. It is rendered rather than logged because the person who would fix it is usually looking at
+ * the screen and not at the console.
+ * @param props The {@link UnresolvedActionHostProps}.
+ */
+export function UnresolvedActionHost({ unresolved }: UnresolvedActionHostProps) {
+    if (unresolved.length === 0) return null;
+
+    return (
+        <div role="status" data-scene-unresolved style={{ position: 'fixed', bottom: '1rem', left: '1rem', maxWidth: '28rem', padding: '0.625rem 0.75rem', borderRadius: 4, border: '1px solid #c0392b', background: '#fff', color: '#1a1a1a', zIndex: 1000 }}>
+            <strong style={{ display: 'block', marginBottom: '0.25rem' }}>This surface cannot do what the document asked</strong>
+            <ul style={{ margin: 0, paddingLeft: '1.25rem' }}>
+                {unresolved.map(action => <li key={action.id}>{action.action}</li>)}
+            </ul>
+        </div>
+    );
+}

package/interactions/index.ts

@@ -4,3 +4,10 @@
 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/package.json

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