@cratis/scene.react 3.7.0 → 4.1.0

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/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/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

@@ -0,0 +1,94 @@
+// 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;
+}
+
+/**
+ * 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);
+
+/**
+ * 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;
+}
+
+/**
+ * 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 = resolvesNothing, 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/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>
+    );
+}