@cratis/scene.model 4.24.0 → 4.26.0

package/index.ts

@@ -10,6 +10,7 @@ export * from './contributionPoints';
 export * from './profiles';
 export * from './icons';
 export * from './packages';
+export * from './sampleData';
 export * from './interactions';
 export * from './screens';
 export * from './starters';

package/package.json

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

package/packages/ScenePackage.ts

@@ -4,6 +4,7 @@
 import { PackageDesignTimeMetadata } from '../descriptors';
 import { IconLibrary } from '../icons';
 import { PackageDependency } from './PackageDependency';
+import { SampleDataPackReference } from '../sampleData';
 import { PackageKind } from './PackageKind';
 
 /**
@@ -102,6 +103,12 @@ export interface ScenePackage {
 
     /** Runtime singleton dependency names that must not be duplicated across approved bundles. */
     runtimeSingletons?: string[];
+
+    /**
+     * The sample-data packs this package ships (`sampleData/*.json`). Design and preview time only: a
+     * Stage production build never includes or resolves them.
+     */
+    sampleData?: SampleDataPackReference[];
 }
 
 export const ScenePackagePropertyNames: (keyof ScenePackage)[] = [
@@ -123,4 +130,5 @@ export const ScenePackagePropertyNames: (keyof ScenePackage)[] = [
     'designTime',
     'assets',
     'runtimeSingletons',
+    'sampleData',
 ];

package/profiles/UiProfile.ts

@@ -1,6 +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 { SampleDataSelection } from '../sampleData';
 import { TargetSizeClass } from '../sizeClasses';
 
 /**
@@ -46,6 +47,14 @@ export interface UiProfile {
      * meaningful relative to a set of packages, which is why it is chosen here rather than by a screen.
      */
     theme?: string;
+
+    /**
+     * Which sample data the application previews with at design and preview time: the active pack, chosen
+     * once here for the whole application (own or from a blueprint), plus the rare shape-to-read-model
+     * mappings and per-read-model pack bindings. Never stated by a screen, slice or component, and never
+     * part of a production build. Absent selects the blueprint's default pack, then generated data.
+     */
+    sampleData?: SampleDataSelection;
 }
 
 export const UiProfilePropertyNames: (keyof UiProfile)[] = [
@@ -55,4 +64,5 @@ export const UiProfilePropertyNames: (keyof UiProfile)[] = [
     'defaultSizeClass',
     'layout',
     'theme',
+    'sampleData',
 ];

package/sampleData/SampleDataBinding.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.
+
+/**
+ * Binds one specific pack to one read model or shape, overriding the application's active pack.
+ */
+export interface SampleDataBinding {
+    /** The read model or shape name the binding applies to. */
+    target: string;
+
+    /** The identity of the bound pack. */
+    pack: string;
+}
+
+export const SampleDataBindingPropertyNames: (keyof SampleDataBinding)[] = ['target', 'pack'];

package/sampleData/SampleDataMapping.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.
+
+/**
+ * An explicit `shape → read model` mapping, for when a pack's shape name differs from the read model's.
+ */
+export interface SampleDataMapping {
+    /** The shape name in the pack. */
+    shape: string;
+
+    /** The read model (or shape) name the pack's shape supplies rows for. */
+    readModel: string;
+}
+
+export const SampleDataMappingPropertyNames: (keyof SampleDataMapping)[] = ['shape', 'readModel'];

package/sampleData/SampleDataPack.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataSet } from './SampleDataSet';
+
+/**
+ * A named dataset used by design-time editing and preview, owned by a blueprint or by the user. A pack is
+ * never part of a running application: Stage production builds do not include or resolve it.
+ */
+export interface SampleDataPack {
+    /** The pack's stable identity, which selections and bindings refer to. */
+    id: string;
+
+    /** The display name. A blueprint pack's selector label is `<Blueprint> · <title>`. */
+    title: string;
+
+    /** The BCP 47 locale tag of the data (`nb-NO`, `en-GB`); generated gap-filling data follows it. */
+    locale: string;
+
+    /** The owner: `blueprint:<id>` for a pack a blueprint ships, or `user` for the author's own. */
+    owner: string;
+
+    /** The rows per shape. */
+    sets: SampleDataSet[];
+}
+
+export const SampleDataPackPropertyNames: (keyof SampleDataPack)[] = ['id', 'title', 'locale', 'owner', 'sets'];

package/sampleData/SampleDataPackReference.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.
+
+/**
+ * How a {@link ScenePackage} declares a sample-data pack it ships: the pack's identity, enough to list it in
+ * a selector without loading it, and where its JSON file lives (`sampleData/<name>.json`).
+ */
+export interface SampleDataPackReference {
+    /** The pack's identity; must equal the `id` inside the file. */
+    id: string;
+
+    /** The display name shown in a selector. */
+    title: string;
+
+    /** The BCP 47 locale tag of the pack's data. */
+    locale: string;
+
+    /** The package-relative path of the pack file, under `sampleData/` and ending in `.json`. */
+    path: string;
+}
+
+export const SampleDataPackReferencePropertyNames: (keyof SampleDataPackReference)[] = ['id', 'title', 'locale', 'path'];

package/sampleData/SampleDataSelection.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.
+
+import { SampleDataBinding } from './SampleDataBinding';
+import { SampleDataMapping } from './SampleDataMapping';
+
+/**
+ * Which sample data an application previews with: the active pack, the shape→read-model mapping table and
+ * any per-read-model pack bindings. It is carried by the application's {@link UiProfile} (`sampleData`), so
+ * the choice is made once for the whole application and inherited by every screen, slice and component; it
+ * is never chosen per screen.
+ */
+export interface SampleDataSelection {
+    /** The application's active pack identity (an own pack or a blueprint's). Absent falls through to the blueprint's default pack, then generated data. */
+    activePack?: string;
+
+    /** Explicit `shape → read model` mappings, for where a pack's shape name is not the read model's name. */
+    mappings: SampleDataMapping[];
+
+    /** Per read model or shape pack bindings; each overrides the active pack for its target. */
+    bindings: SampleDataBinding[];
+}
+
+export const SampleDataSelectionPropertyNames: (keyof SampleDataSelection)[] = ['activePack', 'mappings', 'bindings'];

package/sampleData/SampleDataSet.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.
+
+/**
+ * The rows a {@link SampleDataPack} provides for one shape.
+ */
+export interface SampleDataSet {
+    /** The shape's name. Matches a read model of the same name unless the selection maps it elsewhere. */
+    shape: string;
+
+    /** The rows: JSON objects keyed by the shape's field names. */
+    rows: Record<string, unknown>[];
+}
+
+export const SampleDataSetPropertyNames: (keyof SampleDataSet)[] = ['shape', 'rows'];

package/sampleData/SampleFieldKind.ts

@@ -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.
+
+/**
+ * What kind of value a field holds, as far as generated sample data is concerned. The deterministic
+ * generator picks a value pool and a value range from the kind; the member values are the strings used in
+ * documents.
+ */
+export enum SampleFieldKind {
+    /** A stable unique identifier (a UUID). */
+    Id = 'id',
+
+    /** A person's full name. */
+    Name = 'name',
+
+    /** A company or organization name. */
+    Company = 'company',
+
+    /** An email address. */
+    Email = 'email',
+
+    /** A phone number in the pack locale's style. */
+    Phone = 'phone',
+
+    /** A city name from the pack locale. */
+    City = 'city',
+
+    /** A short free-text phrase. */
+    Text = 'text',
+
+    /** A whole number. */
+    WholeNumber = 'wholeNumber',
+
+    /** A monetary or other two-decimal amount. */
+    Amount = 'amount',
+
+    /** A true/false value. */
+    Boolean = 'boolean',
+
+    /** A calendar date, `yyyy-MM-dd`. */
+    Date = 'date',
+
+    /** A UTC date and time, `yyyy-MM-ddTHH:mm:ssZ`. */
+    DateTime = 'dateTime',
+
+    /** One of a fixed set of named values, given by the field's `enumValues`. */
+    Enum = 'enum',
+}

package/sampleData/SampleShape.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 { SampleShapeField } from './SampleShapeField';
+
+/**
+ * The shape of the rows a read model or component needs: a name and the fields of one row. Components and
+ * queries declare shapes and never values; sample data fills the shape at design and preview time.
+ */
+export interface SampleShape {
+    /** The shape's name, matched by name against a pack's sets and a selection's mappings. */
+    name: string;
+
+    /** The fields of one row, in the order their values are generated and written. */
+    fields: SampleShapeField[];
+}
+
+export const SampleShapePropertyNames: (keyof SampleShape)[] = ['name', 'fields'];

package/sampleData/SampleShapeField.ts

@@ -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 { SampleFieldKind } from './SampleFieldKind';
+
+/**
+ * One field of a {@link SampleShape}: what the generator needs to know to produce a plausible value.
+ * A field gives a `kind`, or just a `type` (and name) from which the kind is inferred.
+ */
+export interface SampleShapeField {
+    /** The field's name, as it appears on each row. */
+    name: string;
+
+    /** The field's type name (`string`, `Guid`, `int`, `decimal`, `bool`, `DateTime` ...); used to infer the kind when `kind` is absent. */
+    type?: string;
+
+    /** The kind of value, overriding what would be inferred from `type` and `name`. Accepts the {@link SampleFieldKind} members or their strings. */
+    kind?: `${SampleFieldKind}`;
+
+    /** Whether the field may be null. A nullable field is occasionally null in generated data. */
+    nullable?: boolean;
+
+    /** The member names of an enum field. Generated values are always one of these. */
+    enumValues?: string[];
+
+    /** The smallest value of a numeric field (inclusive). */
+    min?: number;
+
+    /** The largest value of a numeric field (inclusive). */
+    max?: number;
+}
+
+export const SampleShapeFieldPropertyNames: (keyof SampleShapeField)[] = ['name', 'type', 'kind', 'nullable', 'enumValues', 'min', 'max'];

package/sampleData/index.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.
+
+export * from './SampleFieldKind';
+export * from './SampleShapeField';
+export * from './SampleShape';
+export * from './SampleDataSet';
+export * from './SampleDataPack';
+export * from './SampleDataPackReference';
+export * from './SampleDataMapping';
+export * from './SampleDataBinding';
+export * from './SampleDataSelection';

package/screens/TemplateMetadata.ts

@@ -3,6 +3,7 @@
 
 import { TemplateAttribution } from './TemplateAttribution';
 import { TemplateCompatibility } from './TemplateCompatibility';
+import { SliceKind } from '../structure';
 
 /** The application hierarchy at which a reusable template is selected. */
 export enum TemplateScope {
@@ -14,7 +15,7 @@ export enum TemplateScope {
 }
 
 /**
- * Optional semantic and browsing metadata. Type and category are open strings so packages can
+ * Semantic and browsing metadata. Category is required for blueprint templates and recommended for own templates. Type and category are open strings so packages can
  * introduce their own vocabulary without a Scene release. Category never determines applicability.
  */
 export interface TemplateMetadata {
@@ -32,8 +33,14 @@ export interface TemplateMetadata {
     license?: string;
     /** An absolute `https` URL to the license terms. */
     licenseUrl?: string;
+    /**
+     * For a template that applies at {@link TemplateScope.Slice}, the slice kinds it applies to. Absent uses the
+     * structural default: a dialog template applies to state change slices, a screen template to every kind that
+     * presents something. Declaring slice kinds without scopes makes the default scope Slice.
+     */
+    sliceKinds?: SliceKind[];
 }
 
 export const TemplateMetadataPropertyNames: (keyof TemplateMetadata)[] = [
-    'type', 'category', 'scopes', 'compatibility', 'attribution', 'license', 'licenseUrl',
+    'type', 'category', 'scopes', 'compatibility', 'attribution', 'license', 'licenseUrl', 'sliceKinds',
 ];

package/screens/TemplateReference.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Where a referenced template comes from. */
+export enum TemplateReferenceSource {
+    /** A template the user created in the workspace. */
+    Own = 'Own',
+    /** A template shipped by a blueprint package, referenced by blueprint name, template name and version range. */
+    Blueprint = 'Blueprint',
+}
+
+/**
+ * How a module, feature or slice refers to the template it uses: an own template by name, or a blueprint
+ * template by blueprint, name and the version range of the blueprint it was chosen from.
+ */
+export interface TemplateReference {
+    /** Whether the template is the user's own or comes from a blueprint. */
+    source: TemplateReferenceSource;
+    /** The template's name - within the workspace for an own template, within the blueprint for a blueprint template. */
+    id: string;
+    /** The blueprint package name. Present exactly when `source` is {@link TemplateReferenceSource.Blueprint}. */
+    blueprint?: string;
+    /**
+     * The semver range of the blueprint the reference accepts, such as `^1.2.0`. Defaults to the caret range of the
+     * installed blueprint version when a reference is created; absent means any version. Only meaningful for a blueprint reference.
+     */
+    version?: string;
+}
+
+export const TemplateReferencePropertyNames: (keyof TemplateReference)[] = ['source', 'id', 'blueprint', 'version'];

package/screens/index.ts

@@ -8,3 +8,4 @@ export * from './DialogTemplate';
 export * from './TemplateAttribution';
 export * from './TemplateCompatibility';
 export * from './TemplateMetadata';
+export * from './TemplateReference';