@cratis/scene.model 4.25.0 → 4.27.0

package/exposure/InstanceContribution.ts

@@ -31,6 +31,13 @@ export interface InstanceContribution {
 
     /** The items a collection property gets from this instance, in order. */
     items?: ContributedItem[];
+
+    /**
+     * For a collection: hide the items the owner and the levels above put in it, so only this instance's own items
+     * remain. The hidden items stay where they are and come back when this is cleared. It needs the `replace`
+     * operation to be exposed.
+     */
+    replaceOwnerItems?: boolean;
 }
 
-export const InstanceContributionPropertyNames: (keyof InstanceContribution)[] = ['instance', 'component', 'path', 'value', 'items'];
+export const InstanceContributionPropertyNames: (keyof InstanceContribution)[] = ['instance', 'component', 'path', 'value', 'items', 'replaceOwnerItems'];

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';
@@ -18,3 +19,4 @@ export * from './descriptors';
 export * from './exposure';
 export * from './editing';
 export * from './structure';
+export * from './navigation';

package/navigation/ApplicationLogo.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 application's logo. It is defined at the application level only; a module shows it locked.
+ */
+export interface ApplicationLogo {
+    /** The image reference. */
+    image: string;
+
+    /** The application name shown with or instead of the image. */
+    title: string;
+}
+
+export const ApplicationLogoPropertyNames: (keyof ApplicationLogo)[] = ['image', 'title'];

package/navigation/ApplicationNavigation.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 { ApplicationLogo } from './ApplicationLogo';
+import { NavigationRegion } from './NavigationRegion';
+
+/**
+ * The application-level navigation: the base every module inherits, extends or overrides.
+ */
+export interface ApplicationNavigation {
+    /** The regions the application defines items for. */
+    regions: NavigationRegion[];
+
+    /** The application logo. */
+    logo?: ApplicationLogo;
+}
+
+export const ApplicationNavigationPropertyNames: (keyof ApplicationNavigation)[] = ['regions', 'logo'];

package/navigation/ModuleNavigation.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 { NavigationRegion } from './NavigationRegion';
+
+/**
+ * The navigation a module declares for the regions it changes. A region it does not declare inherits the application's.
+ */
+export interface ModuleNavigation {
+    /** The module identity. */
+    module: string;
+
+    /** The regions the module changes. */
+    regions: NavigationRegion[];
+}
+
+export const ModuleNavigationPropertyNames: (keyof ModuleNavigation)[] = ['module', 'regions'];

package/navigation/NavItem.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationReference } from '../common';
+
+/**
+ * One item of a navigation region.
+ */
+export interface NavItem {
+    /** The item identity, unique in its region at the level that owns it. */
+    id: string;
+
+    /** The text shown for the item. */
+    title: string;
+
+    /** Qualified icon reference, when the item has one. */
+    icon?: string;
+
+    /**
+     * What the item navigates to: `module`, and optionally `feature` (a dotted path inside the module). A module
+     * without a feature goes to the module's first feature.
+     */
+    target?: DestinationReference;
+
+    /** The rendering slot - an outlet id - the target renders into; `content`, the primary outlet, when absent. */
+    slot?: string;
+
+    /** The sub-items; only a sidebar item has them. */
+    children?: NavItem[];
+}
+
+export const NavItemPropertyNames: (keyof NavItem)[] = ['id', 'title', 'icon', 'target', 'slot', 'children'];

package/navigation/NavigationModel.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 { ApplicationNavigation } from './ApplicationNavigation';
+import { ModuleNavigation } from './ModuleNavigation';
+
+/**
+ * All the navigation an application declares: its own regions and the regions each module changes.
+ */
+export interface NavigationModel {
+    /** The application-level navigation. */
+    application: ApplicationNavigation;
+
+    /** The per-module navigation; a module that is not listed inherits everything. */
+    modules: ModuleNavigation[];
+}
+
+export const NavigationModelPropertyNames: (keyof NavigationModel)[] = ['application', 'modules'];

package/navigation/NavigationRegion.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationRegionKind } from './NavigationRegionKind';
+import { NavigationRegionMode } from './NavigationRegionMode';
+import { NavItem } from './NavItem';
+
+/**
+ * The items one level (the application or a module) defines for one navigation region.
+ */
+export interface NavigationRegion {
+    /** Which region the items belong to. */
+    region: NavigationRegionKind;
+
+    /**
+     * How a module's items relate to the application's. Absent at the application level, which is the base, and
+     * meaning `inherit` at a module.
+     */
+    mode?: NavigationRegionMode;
+
+    /** The items, in order. */
+    items: NavItem[];
+}
+
+export const NavigationRegionPropertyNames: (keyof NavigationRegion)[] = ['region', 'mode', 'items'];

package/navigation/NavigationRegionKind.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.
+
+/**
+ * The navigation regions an application shell has.
+ */
+export enum NavigationRegionKind {
+    /** The flat strip along the top. */
+    Topbar = 'topbar',
+
+    /** The side list, whose items may have sub-items. */
+    Sidebar = 'sidebar',
+}

package/navigation/NavigationRegionMode.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.
+
+/**
+ * How a module's region relates to the application's items for the same region.
+ */
+export enum NavigationRegionMode {
+    /** Effective items are the application items; the module's own items are cleared. */
+    Inherit = 'inherit',
+
+    /** Effective items are the application items followed by the module's items. */
+    Extend = 'extend',
+
+    /** Effective items are the module's items only. */
+    Override = 'override',
+}

package/navigation/index.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.
+
+export * from './NavigationRegionKind';
+export * from './NavigationRegionMode';
+export * from './NavItem';
+export * from './NavigationRegion';
+export * from './ApplicationLogo';
+export * from './ApplicationNavigation';
+export * from './ModuleNavigation';
+export * from './NavigationModel';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.model",
-    "version": "4.25.0",
+    "version": "4.27.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';