@cratis/scene.engine 4.1.1 → 4.2.1

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_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');
-    });
-});

package/for_runActions/when_running_against_the_shared_fixture_corpus.ts

@@ -1,124 +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 { InteractionAction, InteractionActionKind, InteractionTriggerKind, NotificationLevel } from '@cratis/scene.model';
-import { BehaviorAttachment, resolveBehaviors } from '../resolveBehaviors';
-import { InteractionStop, runActions } from '../runActions';
-import { pathEchoingContext, RecordingDispatcher } from './given/a_recording_dispatcher';
-
-interface FixtureBehavior {
-    name: string | null;
-    trigger: keyof typeof InteractionTriggerKind;
-    order?: number;
-}
-
-interface FixtureAttachment {
-    level: string;
-    depth?: number;
-    behaviors: FixtureBehavior[];
-}
-
-interface ResolutionCase {
-    name: string;
-    trigger: keyof typeof InteractionTriggerKind;
-    attachments: FixtureAttachment[];
-    expected: (string | null)[];
-}
-
-interface FixtureAction {
-    kind: string;
-    command?: string;
-    query?: string;
-    screen?: string;
-    dialogTemplate?: string;
-    level?: keyof typeof NotificationLevel;
-    text?: string;
-    onSuccess?: FixtureAction[];
-    onFailure?: FixtureAction[];
-    onResult?: FixtureAction[];
-}
-
-interface SequencingCase {
-    name: string;
-    actions: FixtureAction[];
-    commandSucceeds: boolean;
-    confirmAnswer: boolean;
-    expectedCalls: string[];
-    expectedStop: keyof typeof InteractionStop;
-    expectedFindings?: string[];
-}
-
-interface FixtureCorpus {
-    resolutionCases: ResolutionCase[];
-    sequencingCases: SequencingCase[];
-}
-
-const manifestPath = join(import.meta.dirname, '..', '..', '..', '..', 'interaction-fixtures.json');
-const corpus = JSON.parse(readFileSync(manifestPath, 'utf-8')) as FixtureCorpus;
-
-function attachment(fixture: FixtureAttachment): BehaviorAttachment {
-    return {
-        level: fixture.level,
-        depth: fixture.depth,
-        behaviors: fixture.behaviors.map(behavior => ({
-            name: behavior.name ?? undefined,
-            order: behavior.order,
-            bindings: [
-                {
-                    trigger: { kind: InteractionTriggerKind[behavior.trigger] } as never,
-                    actions: [],
-                },
-            ],
-        })),
-    };
-}
-
-function action(fixture: FixtureAction): InteractionAction {
-    return {
-        kind: InteractionActionKind[fixture.kind as keyof typeof InteractionActionKind] ?? fixture.kind,
-        command: fixture.command,
-        query: fixture.query,
-        screen: fixture.screen,
-        dialogTemplate: fixture.dialogTemplate,
-        level: fixture.level === undefined ? undefined : NotificationLevel[fixture.level],
-        message: fixture.text === undefined ? undefined : { text: fixture.text },
-        onSuccess: (fixture.onSuccess ?? []).map(action),
-        onFailure: (fixture.onFailure ?? []).map(action),
-        onResult: (fixture.onResult ?? []).map(action),
-    } as InteractionAction;
-}
-
-// The dispatcher records the command name without its arguments, because the corpus pins the sequencing rule
-// and not how a binding resolves - that is asserted by the unit specs next to this file.
-function callsWithoutArguments(calls: string[]): string[] {
-    return calls.map(call => call.replace(/:\{.*\}$/, ''));
-}
-
-describe('when running against the shared fixture corpus', () => {
-    for (const fixture of corpus.resolutionCases) {
-        it(`should resolve the case where ${fixture.name}`, () => {
-            const resolved = resolveBehaviors(
-                fixture.attachments.map(attachment),
-                InteractionTriggerKind[fixture.trigger]
-            );
-
-            resolved.map(candidate => candidate.behaviorName ?? null).should.eql(fixture.expected);
-        });
-    }
-
-    for (const fixture of corpus.sequencingCases) {
-        it(`should sequence the case where ${fixture.name}`, async () => {
-            const dispatcher = new RecordingDispatcher();
-            dispatcher.commandSucceeds = fixture.commandSucceeds;
-            dispatcher.confirmAnswer = fixture.confirmAnswer;
-
-            const run = await runActions(fixture.actions.map(action), dispatcher, pathEchoingContext);
-
-            callsWithoutArguments(dispatcher.calls).should.eql(fixture.expectedCalls);
-            run.stop.should.equal(InteractionStop[fixture.expectedStop]);
-            run.findings.map(finding => finding.kind).should.eql(fixture.expectedFindings ?? []);
-        });
-    }
-});

package/for_themeCompatibility/when_checking_against_the_shared_fixture_corpus.ts

@@ -1,37 +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 { Theme, UiProfile } from '@cratis/scene.model';
-import { applicableThemePackages, incompatiblePackages } from '../index';
-
-interface FixtureCase {
-    name: string;
-    theme: { compatibleWith: string[] };
-    profile: { packages: string[] };
-    expectedIncompatible: string[];
-    expectedApplicable: string[];
-}
-
-interface FixtureCorpus {
-    cases: FixtureCase[];
-}
-
-const manifestPath = join(import.meta.dirname, '..', '..', '..', '..', 'theme-compatibility-fixtures.json');
-const corpus = JSON.parse(readFileSync(manifestPath, 'utf-8')) as FixtureCorpus;
-
-describe('when checking against the shared fixture corpus', () => {
-    for (const fixtureCase of corpus.cases) {
-        const theme: Theme = { name: 'test-theme', compatibleWith: fixtureCase.theme.compatibleWith };
-        const profile: UiProfile = { name: 'test-profile', targetPlatform: 'web', packages: fixtureCase.profile.packages };
-
-        it(`should match the expected incompatible packages for "${fixtureCase.name}"`, () => {
-            incompatiblePackages(theme, profile).should.deep.equal(fixtureCase.expectedIncompatible);
-        });
-
-        it(`should match the expected applicable packages for "${fixtureCase.name}"`, () => {
-            applicableThemePackages(theme, profile).should.deep.equal(fixtureCase.expectedApplicable);
-        });
-    }
-});