@cratis/scene.model 3.7.0 → 4.1.0

package/elements/SceneElement.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { Behavior } from '../interactions';
+
 /**
  * The root of every node in a Scene element tree. Named `SceneElement` rather than `Element` to avoid
  * colliding with the DOM's own global `Element` type, which every consumer of this package also has in scope.
@@ -8,6 +10,11 @@
 export interface SceneElement {
     id: string;
     properties: Record<string, unknown>;
+    /**
+     * The behaviors attached here - what happens when someone interacts with it. Additive with whatever is
+     * attached further out or further in.
+     */
+    behaviors?: Behavior[];
 }
 
-export const SceneElementPropertyNames: (keyof SceneElement)[] = ['id', 'properties'];
+export const SceneElementPropertyNames: (keyof SceneElement)[] = ['id', 'properties', 'behaviors'];

package/forms/Form.ts

@@ -3,6 +3,7 @@
 
 import { PopulateSource } from './PopulateSource';
 import { FormField } from './FormField';
+import { Behavior } from '../interactions';
 
 /**
  * The command-side counterpart to a table or summary: a named, typed form for one command.
@@ -12,6 +13,11 @@ export interface Form {
     forCommand: string;
     populateSource?: PopulateSource;
     fields: FormField[];
+    /**
+     * The behaviors attached here - what happens when someone interacts with it. Additive with whatever is
+     * attached further out or further in.
+     */
+    behaviors?: Behavior[];
 }
 
-export const FormPropertyNames: (keyof Form)[] = ['name', 'forCommand', 'populateSource', 'fields'];
+export const FormPropertyNames: (keyof Form)[] = ['name', 'forCommand', 'populateSource', 'fields', 'behaviors'];

package/index.ts

@@ -9,5 +9,6 @@ export * from './forms';
 export * from './contributionPoints';
 export * from './profiles';
 export * from './packages';
+export * from './interactions';
 export * from './screens';
 export * from './starters';

package/interactions/ApplicationTriggerInteractionTrigger.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionTrigger } from './InteractionTrigger';
+
+/**
+ * An interaction started by a declared application trigger firing.
+ */
+export interface ApplicationTriggerInteractionTrigger extends InteractionTrigger {
+    triggerName: string;
+}
+
+export const ApplicationTriggerInteractionTriggerPropertyNames: (keyof ApplicationTriggerInteractionTrigger)[] = ['triggerName'];

package/interactions/Behavior.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.
+
+import { InteractionBinding } from './InteractionBinding';
+
+/**
+ * A bundle of interaction trigger to action bindings, attached to something that can be interacted with.
+ *
+ * A named behavior and an inline one are the same shape - anonymity is a property rather than a separate kind
+ * of node. Attachments are additive: a behavior on a template and one on an element both run, outermost first,
+ * unless the order says otherwise.
+ */
+export interface Behavior {
+    name?: string;
+    bindings: InteractionBinding[];
+    order?: number;
+}
+
+export const BehaviorPropertyNames: (keyof Behavior)[] = ['name', 'bindings', 'order'];

package/interactions/BuiltInInteractionTrigger.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionTrigger } from './InteractionTrigger';
+import { InteractionTriggerKind } from './InteractionTriggerKind';
+
+/**
+ * One of the built-in interaction kinds.
+ */
+export interface BuiltInInteractionTrigger extends InteractionTrigger {
+    kind: InteractionTriggerKind;
+}
+
+export const BuiltInInteractionTriggerPropertyNames: (keyof BuiltInInteractionTrigger)[] = ['kind'];

package/interactions/CloseDialogAction.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Dismisses the innermost dialog.
+ */
+export interface CloseDialogAction extends InteractionAction {}
+
+export const CloseDialogActionPropertyNames: (keyof CloseDialogAction)[] = ['kind'];

package/interactions/ConfirmAction.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+import { InteractionMessage } from './InteractionMessage';
+
+/**
+ * Gates the actions that follow on the user agreeing.
+ */
+export interface ConfirmAction extends InteractionAction {
+    message: InteractionMessage;
+}
+
+export const ConfirmActionPropertyNames: (keyof ConfirmAction)[] = ['message', 'kind'];

package/interactions/EventInteractionTrigger.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionTrigger } from './InteractionTrigger';
+
+/**
+ * An interaction started by observing a modeled domain event.
+ */
+export interface EventInteractionTrigger extends InteractionTrigger {
+    eventName: string;
+}
+
+export const EventInteractionTriggerPropertyNames: (keyof EventInteractionTrigger)[] = ['eventName'];

package/interactions/ExecuteCommandAction.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Submits a modeled command.
+ */
+export interface ExecuteCommandAction extends InteractionAction {
+    command: string;
+}
+
+export const ExecuteCommandActionPropertyNames: (keyof ExecuteCommandAction)[] = ['command', 'kind'];

package/interactions/InteractionAction.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionActionKind } from './InteractionActionKind';
+import { InteractionArgument } from './InteractionArgument';
+
+/**
+ * One declarative effect inside a binding.
+ *
+ * The set is closed and every operand references something the model declares rather than being a string a
+ * renderer interprets - that is what lets an action naming nothing be reported instead of becoming a control
+ * that does nothing when clicked.
+ */
+export interface InteractionAction {
+    kind: InteractionActionKind;
+    arguments?: InteractionArgument[];
+    onSuccess?: InteractionAction[];
+    onFailure?: InteractionAction[];
+    onResult?: InteractionAction[];
+}
+
+export const InteractionActionPropertyNames: (keyof InteractionAction)[] = ['kind', 'arguments', 'onSuccess', 'onFailure', 'onResult'];

package/interactions/InteractionActionKind.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Which effect an {@link InteractionAction} is.
+ *
+ * An explicit discriminator rather than a structural one: NavigateBackAction and CloseDialogAction both carry no
+ * operand, so nothing about their shape tells them apart. It also means a renderer meeting an action it does not
+ * know can name it in a finding instead of reporting that something unidentifiable failed.
+ *
+ * Append only.
+ */
+export enum InteractionActionKind {
+    ExecuteCommand = 'ExecuteCommand',
+    Navigate = 'Navigate',
+    NavigateBack = 'NavigateBack',
+    OpenDialog = 'OpenDialog',
+    CloseDialog = 'CloseDialog',
+    RefreshQuery = 'RefreshQuery',
+    SetState = 'SetState',
+    Notify = 'Notify',
+    Confirm = 'Confirm',
+    RaiseTrigger = 'RaiseTrigger',
+}

package/interactions/InteractionArgument.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression } from '../common';
+
+/**
+ * One argument passed to an action.
+ */
+export interface InteractionArgument {
+    name: string;
+    value: BindingExpression;
+}
+
+export const InteractionArgumentPropertyNames: (keyof InteractionArgument)[] = ['name', 'value'];

package/interactions/InteractionBinding.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.
+
+import { BindingExpression } from '../common';
+import { InteractionAction } from './InteractionAction';
+import { InteractionTrigger } from './InteractionTrigger';
+
+/**
+ * One interaction trigger to actions binding.
+ */
+export interface InteractionBinding {
+    trigger: InteractionTrigger;
+    actions: InteractionAction[];
+    condition?: BindingExpression;
+}
+
+export const InteractionBindingPropertyNames: (keyof InteractionBinding)[] = ['trigger', 'actions', 'condition'];

package/interactions/InteractionMessage.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression } from '../common';
+
+/**
+ * The text an action shows: a literal, a localization key, or a binding resolved when the action runs. Exactly
+ * one is set.
+ */
+export interface InteractionMessage {
+    text?: string;
+    stringsKey?: string;
+    binding?: BindingExpression;
+}
+
+export const InteractionMessagePropertyNames: (keyof InteractionMessage)[] = ['text', 'stringsKey', 'binding'];

package/interactions/InteractionTrigger.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What starts an interaction.
+ *
+ * Never declared - it exists only as part of a binding, which is what makes it a different concept from the
+ * application trigger a backend reaction consumes.
+ */
+export interface InteractionTrigger {}

package/interactions/InteractionTriggerKind.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The built-in interaction kinds - what a user or a lifecycle did, rather than something the document declared.
+ *
+ * Append only: a renderer that does not know a member reports it rather than guessing, so members are never
+ * renumbered or reordered.
+ */
+export enum InteractionTriggerKind {
+    Click = 'Click',
+    DoubleClick = 'DoubleClick',
+    Select = 'Select',
+    Submit = 'Submit',
+    Change = 'Change',
+    Load = 'Load',
+    Unload = 'Unload',
+    Enter = 'Enter',
+    Leave = 'Leave',
+}

package/interactions/IntervalInteractionTrigger.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionTrigger } from './InteractionTrigger';
+
+/**
+ * An interaction started by an elapsed interval, normalized to seconds so nothing downstream carries a unit.
+ */
+export interface IntervalInteractionTrigger extends InteractionTrigger {
+    seconds: number;
+}
+
+export const IntervalInteractionTriggerPropertyNames: (keyof IntervalInteractionTrigger)[] = ['seconds'];

package/interactions/NavigateAction.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Changes the active screen. The screen is named, never addressed - turning that into a URL is a renderer's job.
+ */
+export interface NavigateAction extends InteractionAction {
+    screen: string;
+}
+
+export const NavigateActionPropertyNames: (keyof NavigateAction)[] = ['screen', 'kind'];

package/interactions/NavigateBackAction.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Pops navigation history.
+ */
+export interface NavigateBackAction extends InteractionAction {}
+
+export const NavigateBackActionPropertyNames: (keyof NavigateBackAction)[] = ['kind'];

package/interactions/NotificationLevel.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * How prominently a {@link NotifyAction} surfaces its message.
+ *
+ * Append only.
+ */
+export enum NotificationLevel {
+    Info = 'Info',
+    Warning = 'Warning',
+    Error = 'Error',
+}

package/interactions/NotifyAction.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+import { InteractionMessage } from './InteractionMessage';
+import { NotificationLevel } from './NotificationLevel';
+
+/**
+ * Surfaces a message.
+ */
+export interface NotifyAction extends InteractionAction {
+    level: NotificationLevel;
+    message: InteractionMessage;
+}
+
+export const NotifyActionPropertyNames: (keyof NotifyAction)[] = ['level', 'message', 'kind'];

package/interactions/OpenDialogAction.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Opens a dialog over the application.
+ */
+export interface OpenDialogAction extends InteractionAction {
+    dialogTemplate: string;
+}
+
+export const OpenDialogActionPropertyNames: (keyof OpenDialogAction)[] = ['dialogTemplate', 'kind'];

package/interactions/RaiseTriggerAction.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Fires a declared application trigger.
+ */
+export interface RaiseTriggerAction extends InteractionAction {
+    trigger: string;
+}
+
+export const RaiseTriggerActionPropertyNames: (keyof RaiseTriggerAction)[] = ['trigger', 'kind'];

package/interactions/RefreshQueryAction.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Re-runs a query-backed element.
+ */
+export interface RefreshQueryAction extends InteractionAction {
+    query: string;
+}
+
+export const RefreshQueryActionPropertyNames: (keyof RefreshQueryAction)[] = ['query', 'kind'];

package/interactions/SetStateAction.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression } from '../common';
+import { InteractionAction } from './InteractionAction';
+
+/**
+ * Writes screen state.
+ */
+export interface SetStateAction extends InteractionAction {
+    target: string;
+    value: BindingExpression;
+}
+
+export const SetStateActionPropertyNames: (keyof SetStateAction)[] = ['target', 'value', 'kind'];

package/interactions/index.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './InteractionTriggerKind';
+export * from './NotificationLevel';
+export * from './InteractionTrigger';
+export * from './BuiltInInteractionTrigger';
+export * from './EventInteractionTrigger';
+export * from './IntervalInteractionTrigger';
+export * from './ApplicationTriggerInteractionTrigger';
+export * from './InteractionMessage';
+export * from './InteractionArgument';
+export * from './InteractionActionKind';
+export * from './InteractionAction';
+export * from './ExecuteCommandAction';
+export * from './NavigateAction';
+export * from './NavigateBackAction';
+export * from './OpenDialogAction';
+export * from './CloseDialogAction';
+export * from './RefreshQueryAction';
+export * from './SetStateAction';
+export * from './NotifyAction';
+export * from './ConfirmAction';
+export * from './RaiseTriggerAction';
+export * from './InteractionBinding';
+export * from './Behavior';

package/layouts/Layout.ts

@@ -3,6 +3,7 @@
 
 import { Arrangement } from './Arrangement';
 import { Slot } from './Slot';
+import { Behavior } from '../interactions';
 
 /**
  * A named template of slots that a {@link Screen} fills with content. Mirrors Screenplay's `layout`
@@ -21,6 +22,11 @@ export interface Layout {
      * themselves.
      */
     arrangement?: Arrangement;
+    /**
+     * The behaviors attached here - what happens when someone interacts with it. Additive with whatever is
+     * attached further out or further in.
+     */
+    behaviors?: Behavior[];
 }
 
-export const LayoutPropertyNames: (keyof Layout)[] = ['name', 'slots', 'arrangement'];
+export const LayoutPropertyNames: (keyof Layout)[] = ['name', 'slots', 'arrangement', 'behaviors'];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.model",
-    "version": "3.7.0",
+    "version": "4.1.0",
     "description": "The TypeScript mirror of Cratis.Scene.Model — the platform-agnostic Screen object model.",
     "keywords": [
         "cratis",

package/profiles/UiProfile.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { SizeClass } from '../sizeClasses';
+import { TargetSizeClass } from '../sizeClasses';
 
 /**
  * A named target: a platform, a default size class, an ordered list of component packages, and the
@@ -33,7 +33,7 @@ export interface UiProfile {
     /**
      * The size class assumed when the renderer cannot otherwise determine one.
      */
-    defaultSizeClass?: SizeClass;
+    defaultSizeClass?: TargetSizeClass;
 
     /**
      * The name of the {@link Layout} this profile renders inside — the application's base navigational

package/screens/DialogTemplate.ts

@@ -3,6 +3,7 @@
 
 import { SceneElement } from '../elements';
 import { Arrangement, Slot } from '../layouts';
+import { Behavior } from '../interactions';
 
 /**
  * A reusable dialog structure — the same idea as a {@link ScreenTemplate}, for content that opens over an
@@ -45,6 +46,11 @@ export interface DialogTemplate {
      * A one-line description for a template picker.
      */
     description?: string;
+    /**
+     * The behaviors attached here - what happens when someone interacts with it. Additive with whatever is
+     * attached further out or further in.
+     */
+    behaviors?: Behavior[];
 }
 
 export const DialogTemplatePropertyNames: (keyof DialogTemplate)[] = [
@@ -54,4 +60,5 @@ export const DialogTemplatePropertyNames: (keyof DialogTemplate)[] = [
     'content',
     'displayName',
     'description',
+    'behaviors',
 ];

package/screens/Screen.ts

@@ -4,6 +4,7 @@
 import { SceneElement } from '../elements';
 import { Form } from '../forms';
 import { Contribution } from '../contributionPoints';
+import { Behavior } from '../interactions';
 
 /**
  * A named screen: the structure it fills, the content that fills it, the forms it hosts, and whatever it
@@ -45,6 +46,11 @@ export interface Screen {
      * never has to state its own position.
      */
     screenTemplate?: string;
+    /**
+     * The behaviors attached here - what happens when someone interacts with it. Additive with whatever is
+     * attached further out or further in.
+     */
+    behaviors?: Behavior[];
 }
 
-export const ScreenPropertyNames: (keyof Screen)[] = ['name', 'layout', 'slotContent', 'forms', 'contributions', 'screenTemplate'];
+export const ScreenPropertyNames: (keyof Screen)[] = ['name', 'layout', 'slotContent', 'forms', 'contributions', 'screenTemplate', 'behaviors'];

package/screens/ScreenTemplate.ts

@@ -3,6 +3,7 @@
 
 import { SceneElement } from '../elements';
 import { Arrangement, Slot } from '../layouts';
+import { Behavior } from '../interactions';
 
 /**
  * A reusable screen structure that fills a named slot on whatever contains it, and offers slots of its
@@ -57,6 +58,11 @@ export interface ScreenTemplate {
      * A one-line description for a template picker.
      */
     description?: string;
+    /**
+     * The behaviors attached here - what happens when someone interacts with it. Additive with whatever is
+     * attached further out or further in.
+     */
+    behaviors?: Behavior[];
 }
 
 export const ScreenTemplatePropertyNames: (keyof ScreenTemplate)[] = [
@@ -67,4 +73,5 @@ export const ScreenTemplatePropertyNames: (keyof ScreenTemplate)[] = [
     'content',
     'displayName',
     'description',
+    'behaviors',
 ];

package/sizeClasses/TargetSizeClass.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines the size a deployment target assumes by default.
+ *
+ * Deliberately a different vocabulary from {@link WidthSizeClass} and {@link HeightSizeClass}. Those two form
+ * the matrix an arrangement resolves against, where the only distinction that matters is whether an axis is
+ * cramped. What a target assumes is a coarser, one-dimensional statement about the device - a desktop is not
+ * merely 'regular' - and it carries a third value because of it.
+ */
+export enum TargetSizeClass {
+    Compact = 'Compact',
+    Regular = 'Regular',
+    Expanded = 'Expanded'
+}

package/sizeClasses/index.ts

@@ -4,3 +4,4 @@
 export * from './WidthSizeClass';
 export * from './HeightSizeClass';
 export * from './SizeClass';
+export * from './TargetSizeClass';