@cratis/scene.engine 4.2.0 → 4.3.0

package/for_resolveBehaviors/when_resolving_additive_attachments.ts

@@ -1,100 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { Behavior, InteractionActionKind, InteractionTriggerKind } from '@cratis/scene.model';
-import { BehaviorAttachment, resolveApplicationTriggerBehaviors, resolveBehaviors } from '../resolveBehaviors';
-
-const behavior = (name: string | undefined, kind: InteractionTriggerKind, order?: number): Behavior => ({
-    name,
-    order,
-    bindings: [
-        {
-            trigger: { kind } as never,
-            actions: [{ kind: InteractionActionKind.RefreshQuery, query: name ?? 'inline' } as never],
-        },
-    ],
-});
-
-describe('when resolving additive attachments', () => {
-    const attachments: BehaviorAttachment[] = [
-        { level: 'layout', behaviors: [behavior('LayoutWide', InteractionTriggerKind.Click)] },
-        { level: 'module', behaviors: [behavior('ModuleWide', InteractionTriggerKind.Click)] },
-        { level: 'element', behaviors: [behavior(undefined, InteractionTriggerKind.Click)] },
-    ];
-
-    // The point of the additive rule: a module saying 'confirm every destructive action' does not need every
-    // screen beneath it to cooperate, and an element attaching its own does not silently cancel it.
-    it('should run every matching attachment rather than only the most specific', () => {
-        const resolved = resolveBehaviors(attachments, InteractionTriggerKind.Click);
-
-        resolved.should.have.lengthOf(3);
-    });
-
-    it('should run the outermost attachment first', () => {
-        const resolved = resolveBehaviors(attachments, InteractionTriggerKind.Click);
-
-        resolved.map(candidate => candidate.level).should.eql(['layout', 'module', 'element']);
-    });
-
-    it('should keep an inline behavior anonymous', () => {
-        const resolved = resolveBehaviors(attachments, InteractionTriggerKind.Click);
-
-        (resolved[2].behaviorName === undefined).should.be.true;
-    });
-
-    it('should ignore bindings for a different trigger', () => {
-        const resolved = resolveBehaviors(
-            [{ level: 'element', behaviors: [behavior('OnSubmitOnly', InteractionTriggerKind.Submit)] }],
-            InteractionTriggerKind.Click
-        );
-
-        resolved.should.be.empty;
-    });
-
-    it('should let an explicit order win over position', () => {
-        const resolved = resolveBehaviors(
-            [
-                { level: 'layout', behaviors: [behavior('LayoutWide', InteractionTriggerKind.Click)] },
-                { level: 'element', behaviors: [behavior('RunsFirst', InteractionTriggerKind.Click, 1)] },
-            ],
-            InteractionTriggerKind.Click
-        );
-
-        resolved.map(candidate => candidate.behaviorName).should.eql(['RunsFirst', 'LayoutWide']);
-    });
-
-    // Determinism is the reason this is a pure function over an ordered list: the same document has to produce
-    // the same order on every run, or an interaction becomes intermittently wrong rather than wrong.
-    it('should order deterministically across repeated resolutions', () => {
-        const once = resolveBehaviors(attachments, InteractionTriggerKind.Click).map(c => c.level);
-        const twice = resolveBehaviors(attachments, InteractionTriggerKind.Click).map(c => c.level);
-
-        once.should.eql(twice);
-    });
-
-    it('should resolve a named application trigger separately from the built-in kinds', () => {
-        const resolved = resolveApplicationTriggerBehaviors(
-            [
-                {
-                    level: 'screen',
-                    behaviors: [
-                        {
-                            name: undefined,
-                            bindings: [
-                                { trigger: { triggerName: 'InvoiceImported' } as never, actions: [] },
-                                { trigger: { triggerName: 'SomethingElse' } as never, actions: [] },
-                            ],
-                        },
-                    ],
-                },
-            ],
-            'InvoiceImported'
-        );
-
-        resolved.should.have.lengthOf(1);
-    });
-
-    it('should tolerate an attachment with no behaviors at all', () => {
-        resolveBehaviors([{ level: 'element', behaviors: [] }], InteractionTriggerKind.Click).should.be.empty;
-    });
-});

package/for_resolveComponentName/when_resolving_against_the_shared_fixture_corpus.ts

@@ -1,36 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { UiProfile } from '@cratis/scene.model';
-import { ComponentResolution, PackageCatalog, resolveComponentName } from '../index';
-
-interface FixtureCase {
-    name: string;
-    profile: { packages: string[] };
-    catalog: PackageCatalog;
-    requestedName: string;
-    expected: ComponentResolution | null;
-}
-
-interface FixtureCorpus {
-    cases: FixtureCase[];
-}
-
-const manifestPath = join(import.meta.dirname, '..', '..', '..', '..', 'package-resolution-fixtures.json');
-const corpus = JSON.parse(readFileSync(manifestPath, 'utf-8')) as FixtureCorpus;
-
-describe('when resolving against the shared fixture corpus', () => {
-    for (const fixtureCase of corpus.cases) {
-        it(`should match the expected resolution for "${fixtureCase.name}"`, () => {
-            const profile: UiProfile = { name: 'test', targetPlatform: 'web', packages: fixtureCase.profile.packages };
-            const actual = resolveComponentName(fixtureCase.requestedName, profile, fixtureCase.catalog);
-            if (fixtureCase.expected === null) {
-                (actual === undefined).should.be.true;
-            } else {
-                actual!.should.deep.equal(fixtureCase.expected);
-            }
-        });
-    }
-});

package/for_resolveScreenTemplates/when_resolving_against_the_shared_fixture_corpus.ts

@@ -1,49 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { Layout, ScreenTemplate } from '@cratis/scene.model';
-import { isScreenTemplateResolutionValid, resolveScreenTemplates } from '../index';
-
-interface FixtureCase {
-    name: string;
-    layout: { name: string; slots: string[] };
-    templates: { name: string; fitsSlot: string | null; slots: string[] }[];
-    expectedPlacements: { template: string; slot: string; container: string; depth: number }[];
-    expectedUnplaced: { template: string; slot: string; candidates: string[] }[];
-    expectedCycles: string[][];
-}
-
-const fixturePath = join(import.meta.dirname, '..', '..', '..', '..', 'screen-template-fixtures.json');
-const corpus = JSON.parse(readFileSync(fixturePath, 'utf-8')) as { cases: FixtureCase[] };
-
-describe('when resolving against the shared fixture corpus', () => {
-    for (const fixtureCase of corpus.cases) {
-        const layout: Layout = { name: fixtureCase.layout.name, slots: fixtureCase.layout.slots.map((name) => ({ name })) };
-        const templates: ScreenTemplate[] = fixtureCase.templates.map((template) => ({
-            name: template.name,
-            fitsSlot: template.fitsSlot ?? undefined,
-            slots: template.slots.map((name) => ({ name })),
-        }));
-
-        const resolution = resolveScreenTemplates(layout, templates);
-
-        it(`should place every template where the corpus expects for "${fixtureCase.name}"`, () => {
-            resolution.placements.should.deep.equal(fixtureCase.expectedPlacements);
-        });
-
-        it(`should report the expected unplaced templates for "${fixtureCase.name}"`, () => {
-            resolution.unplaced.should.deep.equal(fixtureCase.expectedUnplaced);
-        });
-
-        it(`should report the expected cycles for "${fixtureCase.name}"`, () => {
-            resolution.cycles.should.deep.equal(fixtureCase.expectedCycles);
-        });
-
-        it(`should consider "${fixtureCase.name}" valid only when nothing is wrong`, () => {
-            const expectedValid = fixtureCase.expectedUnplaced.length === 0 && fixtureCase.expectedCycles.length === 0;
-            isScreenTemplateResolutionValid(resolution).should.equal(expectedValid);
-        });
-    }
-});

package/for_resolveStrings/when_resolving_a_strings_reference.ts

@@ -1,85 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { Control, ExternalComponent, HorizontalAlignment, VerticalAlignment, Visibility } from '@cratis/scene.model';
-import { isStringsReference, resolveStringsInElement, resolveStringsValue } from '../index';
-
-const dictionary = {
-    'invoice.title': 'Invoices',
-    'invoice.number': 'Invoice #',
-};
-
-function control(id: string): Control {
-    return {
-        id,
-        name: id,
-        properties: {},
-        visibility: Visibility.Visible,
-        isEnabled: true,
-        opacity: 1,
-        size: {},
-        zIndex: 0,
-        minimumSize: {},
-        maximumSize: {},
-        margin: { left: 0, top: 0, right: 0, bottom: 0 },
-        horizontalAlignment: HorizontalAlignment.Stretch,
-        verticalAlignment: VerticalAlignment.Stretch,
-        borderThickness: { left: 0, top: 0, right: 0, bottom: 0 },
-        padding: { left: 0, top: 0, right: 0, bottom: 0 },
-        tabIndex: 0,
-    };
-}
-
-function externalComponent(id: string, componentName: string, properties: Record<string, unknown>, slots: Record<string, ExternalComponent[]> = {}): ExternalComponent {
-    return { ...control(id), componentName, properties, slots };
-}
-
-describe('when telling a strings reference apart from a literal value', () => {
-    it('should recognize a $strings. reference', () => {
-        isStringsReference('$strings.invoice.title').should.be.true;
-    });
-
-    it('should reject a literal value', () => {
-        isStringsReference('Invoices').should.be.false;
-    });
-
-    it('should reject a non-string value', () => {
-        isStringsReference(42).should.be.false;
-    });
-});
-
-describe('when resolving a single property value', () => {
-    it('should resolve a reference present in the dictionary', () => {
-        (resolveStringsValue('$strings.invoice.title', dictionary) as string).should.equal('Invoices');
-    });
-
-    it('should leave a reference missing from the dictionary as its literal token', () => {
-        (resolveStringsValue('$strings.invoice.missing', dictionary) as string).should.equal('$strings.invoice.missing');
-    });
-
-    it('should pass a non-reference value through unchanged', () => {
-        (resolveStringsValue(42, dictionary) as number).should.equal(42);
-    });
-});
-
-describe('when resolving references nested inside an external component tree', () => {
-    const title = externalComponent('title', 'core:title', { text: '$strings.invoice.title' });
-    const table = externalComponent('table', 'core:table', {}, {
-        columns: [externalComponent('column', 'core:column', { label: '$strings.invoice.number' })],
-    });
-
-    const resolvedTitle = resolveStringsInElement(title, dictionary) as ExternalComponent;
-    const resolvedTable = resolveStringsInElement(table, dictionary) as ExternalComponent;
-
-    it('should resolve a reference at the top of the tree', () => {
-        (resolvedTitle.properties.text as string).should.equal('Invoices');
-    });
-
-    it('should leave the original element untouched', () => {
-        (title.properties.text as string).should.equal('$strings.invoice.title');
-    });
-
-    it('should resolve a reference nested inside a slot', () => {
-        (resolvedTable.slots.columns[0].properties.label as string).should.equal('Invoice #');
-    });
-});

package/for_runActions/given/a_recording_dispatcher.ts

@@ -1,72 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { BindingExpression, NotificationLevel } from '@cratis/scene.model';
-import { ActionDispatcher, CommandOutcome, DialogOutcome } from '../../ActionDispatcher';
-import { InteractionContext } from '../../runActions';
-
-/**
- * A dispatcher that records what it was asked to do instead of doing it.
- *
- * The whole point of the engine owning the sequencing is that this is possible: no DOM, no React, no transport -
- * the rules are assertable as a list of calls.
- */
-export class RecordingDispatcher implements ActionDispatcher {
-    readonly calls: string[] = [];
-
-    commandSucceeds = true;
-    dialogConfirmed = true;
-    confirmAnswer = true;
-
-    async executeCommand(command: string, args: Record<string, unknown>): Promise<CommandOutcome> {
-        this.calls.push(`executeCommand:${command}:${JSON.stringify(args)}`);
-        return this.commandSucceeds
-            ? { isSuccess: true }
-            : { isSuccess: false, validationErrors: [{ member: 'amount', message: 'Must be positive' }] };
-    }
-
-    navigate(screen: string): void {
-        this.calls.push(`navigate:${screen}`);
-    }
-
-    navigateBack(): void {
-        this.calls.push('navigateBack');
-    }
-
-    async openDialog(dialogTemplate: string, args: Record<string, unknown>): Promise<DialogOutcome> {
-        this.calls.push(`openDialog:${dialogTemplate}:${JSON.stringify(args)}`);
-        return { isConfirmed: this.dialogConfirmed, result: 'the-result' };
-    }
-
-    closeDialog(): void {
-        this.calls.push('closeDialog');
-    }
-
-    async refreshQuery(query: string): Promise<void> {
-        this.calls.push(`refreshQuery:${query}`);
-    }
-
-    setState(target: string, value: unknown): void {
-        this.calls.push(`setState:${target}:${String(value)}`);
-    }
-
-    notify(level: NotificationLevel, message: string): void {
-        this.calls.push(`notify:${level}:${message}`);
-    }
-
-    async confirm(message: string): Promise<boolean> {
-        this.calls.push(`confirm:${message}`);
-        return this.confirmAnswer;
-    }
-
-    async raise(trigger: string): Promise<void> {
-        this.calls.push(`raise:${trigger}`);
-    }
-}
-
-/**
- * A context that resolves a binding to its path, so an assertion can see which binding was used.
- */
-export const pathEchoingContext: InteractionContext = {
-    resolve: (binding: BindingExpression) => `<${binding.path}>`,
-};

package/for_runActions/when_running_a_sequence_of_actions.ts

@@ -1,226 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { InteractionAction, InteractionActionKind, NotificationLevel } from '@cratis/scene.model';
-import { InteractionStop, runActions } from '../runActions';
-import { pathEchoingContext, RecordingDispatcher } from './given/a_recording_dispatcher';
-
-const action = (kind: InteractionActionKind, extra: Record<string, unknown> = {}): InteractionAction =>
-    ({ kind, ...extra }) as InteractionAction;
-
-describe('when running a sequence of actions', () => {
-    it('should run them in the order they were declared', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        await runActions(
-            [
-                action(InteractionActionKind.RefreshQuery, { query: 'Invoices' }),
-                action(InteractionActionKind.Notify, { level: NotificationLevel.Info, message: { text: 'Done' } }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['refreshQuery:Invoices', 'notify:Info:Done']);
-    });
-
-    it('should resolve an action\'s arguments through the binding resolver', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        await runActions(
-            [
-                action(InteractionActionKind.ExecuteCommand, {
-                    command: 'CancelInvoice',
-                    arguments: [{ name: 'invoiceId', value: { path: 'item.invoiceId' } }],
-                }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['executeCommand:CancelInvoice:{"invoiceId":"<item.invoiceId>"}']);
-    });
-
-    it('should take the success branch when a command succeeds', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        const run = await runActions(
-            [
-                action(InteractionActionKind.ExecuteCommand, {
-                    command: 'RegisterInvoice',
-                    onSuccess: [action(InteractionActionKind.CloseDialog)],
-                    onFailure: [action(InteractionActionKind.Notify, { level: NotificationLevel.Error, message: { text: 'Failed' } })],
-                }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['executeCommand:RegisterInvoice:{}', 'closeDialog']);
-        run.stop.should.equal(InteractionStop.Completed);
-    });
-
-    it('should take the failure branch when a command fails', async () => {
-        const dispatcher = new RecordingDispatcher();
-        dispatcher.commandSucceeds = false;
-
-        await runActions(
-            [
-                action(InteractionActionKind.ExecuteCommand, {
-                    command: 'RegisterInvoice',
-                    onSuccess: [action(InteractionActionKind.CloseDialog)],
-                    onFailure: [action(InteractionActionKind.Notify, { level: NotificationLevel.Error, message: { text: 'Failed' } })],
-                }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['executeCommand:RegisterInvoice:{}', 'notify:Error:Failed']);
-    });
-
-    // A confirm exists to gate what follows it. If a decline let the rest run, the gate would be decorative.
-    it('should stop the sequence when a confirm is declined', async () => {
-        const dispatcher = new RecordingDispatcher();
-        dispatcher.confirmAnswer = false;
-
-        const run = await runActions(
-            [
-                action(InteractionActionKind.Confirm, {
-                    message: { text: 'Are you sure?' },
-                    onSuccess: [action(InteractionActionKind.ExecuteCommand, { command: 'CancelInvoice' })],
-                }),
-                action(InteractionActionKind.Notify, { level: NotificationLevel.Info, message: { text: 'Cancelled' } }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['confirm:Are you sure?']);
-        run.stop.should.equal(InteractionStop.Declined);
-    });
-
-    it('should run the gated actions when a confirm is accepted', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        await runActions(
-            [
-                action(InteractionActionKind.Confirm, {
-                    message: { text: 'Are you sure?' },
-                    onSuccess: [action(InteractionActionKind.ExecuteCommand, { command: 'CancelInvoice' })],
-                }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['confirm:Are you sure?', 'executeCommand:CancelInvoice:{}']);
-    });
-
-    // The screen the remaining actions were written for is gone. The compiler reports this as unreachable, so
-    // reaching it at runtime means the document changed underneath - still not a reason to run them.
-    it('should stop the sequence after a navigation', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        const run = await runActions(
-            [
-                action(InteractionActionKind.Navigate, { screen: 'InvoiceList' }),
-                action(InteractionActionKind.Notify, { level: NotificationLevel.Info, message: { text: 'Never runs' } }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['navigate:InvoiceList']);
-        run.stop.should.equal(InteractionStop.Navigated);
-    });
-
-    it('should stop the sequence after navigating back', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        const run = await runActions(
-            [action(InteractionActionKind.NavigateBack), action(InteractionActionKind.CloseDialog)],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['navigateBack']);
-        run.stop.should.equal(InteractionStop.Navigated);
-    });
-
-    it('should run a dialog\'s result continuation after it closes', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        await runActions(
-            [
-                action(InteractionActionKind.OpenDialog, {
-                    dialogTemplate: 'InvoiceDetails',
-                    arguments: [{ name: 'invoiceId', value: { path: 'item.invoiceId' } }],
-                    onResult: [action(InteractionActionKind.RefreshQuery, { query: 'Invoices' })],
-                }),
-            ],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql([
-            'openDialog:InvoiceDetails:{"invoiceId":"<item.invoiceId>"}',
-            'refreshQuery:Invoices',
-        ]);
-    });
-
-    it('should resolve a message from a binding when it has one', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        await runActions(
-            [action(InteractionActionKind.Notify, { level: NotificationLevel.Info, message: { binding: { path: 'state.message' } } })],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.eql(['notify:Info:<state.message>']);
-    });
-
-    it('should localize a message given a strings key', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        await runActions(
-            [action(InteractionActionKind.Notify, { level: NotificationLevel.Info, message: { stringsKey: 'invoiceRegistered' } })],
-            dispatcher,
-            { resolve: () => undefined, localize: key => `localized(${key})` }
-        );
-
-        dispatcher.calls.should.eql(['notify:Info:localized(invoiceRegistered)']);
-    });
-
-    // Fail closed and visible: an action kind this engine does not know is reported, and the rest of the
-    // sequence is abandoned rather than half-applied silently.
-    it('should report an action kind it does not know instead of ignoring it', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        const run = await runActions(
-            [action('SomethingFromALaterVersion' as InteractionActionKind)],
-            dispatcher,
-            pathEchoingContext
-        );
-
-        dispatcher.calls.should.be.empty;
-        run.stop.should.equal(InteractionStop.Reported);
-        run.findings.should.have.lengthOf(1);
-        run.findings[0].kind.should.equal('unknownAction');
-        run.findings[0].detail.should.contain('SomethingFromALaterVersion');
-    });
-
-    it('should report a message binding that resolved to nothing', async () => {
-        const dispatcher = new RecordingDispatcher();
-
-        const run = await runActions(
-            [action(InteractionActionKind.Confirm, { message: { binding: { path: 'state.missing' } } })],
-            dispatcher,
-            { resolve: () => undefined }
-        );
-
-        run.findings[0].kind.should.equal('unresolvedMessage');
-        run.findings[0].detail.should.contain('state.missing');
-    });
-});