@cratis/scene.model 4.11.0 → 4.13.0

package/forms/CommandFormLayout.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 { FormColumn } from './FormColumn';
+import { FormFieldPlacement } from './FormFieldPlacement';
+import { FormWidth } from './FormWidth';
+
+/**
+ * Platform-neutral command-form geometry. It is independent of auto/manual field generation mode.
+ */
+export interface CommandFormLayout {
+    columns: FormColumn[];
+    placements: FormFieldPlacement[];
+    columnGap?: FormWidth;
+    rowGap?: FormWidth;
+}
+
+export const CommandFormLayoutPropertyNames: (keyof CommandFormLayout)[] = ['columns', 'placements', 'columnGap', 'rowGap'];

package/forms/Form.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 { CommandFormLayout } from './CommandFormLayout';
+import { FormGenerationMode } from './FormGenerationMode';
 import { PopulateSource } from './PopulateSource';
 import { FormField } from './FormField';
 import { Behavior } from '../interactions';
@@ -12,6 +14,8 @@ export interface Form {
     name: string;
     forCommand: string;
     populateSource?: PopulateSource;
+    generationMode?: FormGenerationMode;
+    layout?: CommandFormLayout;
     fields: FormField[];
     /**
      * The behaviors attached here - what happens when someone interacts with it. Additive with whatever is
@@ -20,4 +24,4 @@ export interface Form {
     behaviors?: Behavior[];
 }
 
-export const FormPropertyNames: (keyof Form)[] = ['name', 'forCommand', 'populateSource', 'fields', 'behaviors'];
+export const FormPropertyNames: (keyof Form)[] = ['name', 'forCommand', 'populateSource', 'generationMode', 'layout', 'fields', 'behaviors'];

package/forms/FormColumn.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 { FormWidth } from './FormWidth';
+
+/**
+ * One column in a command-form geometry grid. Indexes are one-based for authored stability.
+ */
+export interface FormColumn {
+    index: number;
+    width?: FormWidth;
+    minWidth?: FormWidth;
+    maxWidth?: FormWidth;
+}
+
+export const FormColumnPropertyNames: (keyof FormColumn)[] = ['index', 'width', 'minWidth', 'maxWidth'];

package/forms/FormField.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 { FormFieldPlacement } from './FormFieldPlacement';
+
 /**
  * One field of a {@link Form}. Mirrors the three population tiers Screenplay's `form` construct
  * establishes: auto-mapped by name (`sourceProperty` and `composeUsing` both undefined), explicitly
@@ -11,6 +13,7 @@ export interface FormField {
     sourceProperty?: string;
     composeUsing?: string;
     label?: string;
+    placement?: FormFieldPlacement;
 }
 
-export const FormFieldPropertyNames: (keyof FormField)[] = ['name', 'sourceProperty', 'composeUsing', 'label'];
+export const FormFieldPropertyNames: (keyof FormField)[] = ['name', 'sourceProperty', 'composeUsing', 'label', 'placement'];

package/forms/FormFieldPlacement.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 { FormWidth } from './FormWidth';
+
+/**
+ * Authored placement for one command-form field in a platform-neutral grid. Row and column are one-based.
+ */
+export interface FormFieldPlacement {
+    field: string;
+    row: number;
+    column: number;
+    rowSpan?: number;
+    columnSpan?: number;
+    width?: FormWidth;
+}
+
+export const FormFieldPlacementPropertyNames: (keyof FormFieldPlacement)[] = ['field', 'row', 'column', 'rowSpan', 'columnSpan', 'width'];

package/forms/FormGenerationMode.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.
+
+/**
+ * How a command form's fields are generated.
+ */
+export enum FormGenerationMode {
+    Auto = 'auto',
+    Manual = 'manual',
+}

package/forms/FormWidth.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 { FormWidthUnit } from './FormWidthUnit';
+
+/**
+ * A platform-neutral width value for form geometry.
+ */
+export interface FormWidth {
+    unit: FormWidthUnit;
+
+    /** The numeric value for fraction, pixel and percent widths. Omitted for `auto`. */
+    value?: number;
+}
+
+export const FormWidthPropertyNames: (keyof FormWidth)[] = ['unit', 'value'];

package/forms/FormWidthUnit.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The unit used by a command-form column, gap or field width.
+ */
+export enum FormWidthUnit {
+    Fraction = 'fraction',
+    Pixels = 'pixels',
+    Percent = 'percent',
+    Auto = 'auto',
+}

package/forms/index.ts

@@ -1,8 +1,14 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+export * from './CommandFormLayout';
 export * from './Form';
+export * from './FormColumn';
 export * from './FormField';
+export * from './FormFieldPlacement';
+export * from './FormGenerationMode';
+export * from './FormWidth';
+export * from './FormWidthUnit';
 export * from './PopulateSource';
 export * from './PopulateViaQuery';
 export * from './PopulateFromItem';

package/package.json

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

package/screens/Outlet.ts

@@ -10,6 +10,13 @@ export interface Outlet {
 
     /** Optional description for designers. */
     description?: string;
+
+    /**
+     * The semantic template types (`TemplateMetadata.type`) a screen must have to be placed in this outlet,
+     * such as `Detail` or `Form`. Absent accepts any screen. A destination that places a screen of another
+     * type here is diagnosed as an incompatible outlet rather than rendered somewhere it was not designed for.
+     */
+    accepts?: string[];
 }
 
-export const OutletPropertyNames: (keyof Outlet)[] = ['name', 'description'];
+export const OutletPropertyNames: (keyof Outlet)[] = ['name', 'description', 'accepts'];

package/screens/TemplateAttribution.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.
+
+/**
+ * Who authored a template and what must accompany it when it is reused.
+ */
+export interface TemplateAttribution {
+    /** The person or organization that authored the template. */
+    author: string;
+
+    /** An absolute `https` URL where the template's source or documentation lives. */
+    url?: string;
+
+    /** An attribution notice a license requires to travel with the template, shown by a template browser. */
+    notice?: string;
+}
+
+export const TemplateAttributionPropertyNames: (keyof TemplateAttribution)[] = ['author', 'url', 'notice'];

package/screens/TemplateCompatibility.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageDependency } from '../packages/PackageDependency';
+
+/**
+ * Which Scene and package versions a template was authored and verified against.
+ *
+ * A template names components, slots and bindings that only exist in particular versions of Scene and of
+ * the packages that provide them. Declaring the ranges lets a catalog mark a template as incompatible with
+ * the active package set before an author picks it, instead of rendering placeholders after they have.
+ */
+export interface TemplateCompatibility {
+    /** The Scene model version range the template requires, such as `^4.13.0`. */
+    scene: string;
+
+    /** The packages, and their version ranges, whose components or layouts the template uses. */
+    packages?: PackageDependency[];
+}
+
+export const TemplateCompatibilityPropertyNames: (keyof TemplateCompatibility)[] = ['scene', 'packages'];

package/screens/TemplateMetadata.ts

@@ -1,6 +1,9 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { TemplateAttribution } from './TemplateAttribution';
+import { TemplateCompatibility } from './TemplateCompatibility';
+
 /** The application hierarchy at which a reusable template is selected. */
 export enum TemplateScope {
     Application = 'Application',
@@ -21,6 +24,16 @@ export interface TemplateMetadata {
     category?: string;
     /** Explicit scope restriction. Absent uses the structural role; an empty list allows no scope. */
     scopes?: TemplateScope[];
+    /** The Scene and package versions the template requires. Required for every shipped template. */
+    compatibility?: TemplateCompatibility;
+    /** Who authored the template. Required for every shipped template. */
+    attribution?: TemplateAttribution;
+    /** The SPDX license identifier the template is available under, such as `MIT`. Required for every shipped template. */
+    license?: string;
+    /** An absolute `https` URL to the license terms. */
+    licenseUrl?: string;
 }
 
-export const TemplateMetadataPropertyNames: (keyof TemplateMetadata)[] = ['type', 'category', 'scopes'];
+export const TemplateMetadataPropertyNames: (keyof TemplateMetadata)[] = [
+    'type', 'category', 'scopes', 'compatibility', 'attribution', 'license', 'licenseUrl',
+];

package/screens/index.ts

@@ -5,4 +5,6 @@ export * from './Outlet';
 export * from './Screen';
 export * from './ScreenTemplate';
 export * from './DialogTemplate';
+export * from './TemplateAttribution';
+export * from './TemplateCompatibility';
 export * from './TemplateMetadata';