@cratis/scene.model 4.68.3 → 4.69.0

package/package.json

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

package/profiles/CornerStyle.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.
+
+/** How rounded the corners of buttons, cards, the logo block and menu items are. */
+export enum CornerStyle {
+    /** Square-ish corners: 4 px. */
+    Sharp = 'Sharp',
+
+    /** The theme's own corner radius. The default. */
+    Default = 'Default',
+
+    /** Generously rounded corners: 18 px. */
+    Round = 'Round',
+}

package/profiles/LogoKind.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.
+
+/** How the application's logo is made: characters on the accent block, an icon on the accent block, or the author's own image. */
+export enum LogoKind {
+    /** One or two characters on a block in the accent colour. The default. */
+    Initials = 'Initials',
+
+    /** One icon from the closed set of logo icons on a block in the accent colour. */
+    Icon = 'Icon',
+
+    /** The author's own image, drawn without the accent block. */
+    Image = 'Image',
+}

package/profiles/ProfileAppearance.ts

@@ -2,9 +2,10 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { ColorScheme } from './ColorScheme';
+import { CornerStyle } from './CornerStyle';
 
 /**
- * How an application looks beyond the {@link UiProfile.theme} it selects: the colour scheme and the accent colour.
+ * How an application looks beyond the {@link UiProfile.theme} it selects: the colour scheme, the accent colour, the corner style and the font.
  */
 export interface ProfileAppearance {
     /** Whether the application is light, dark or follows the system. Absent leaves the theme's own default. */
@@ -12,6 +13,12 @@ export interface ProfileAppearance {
 
     /** The accent colour as a CSS colour (for example `#4f46e5`). Absent keeps the theme's accent. */
     accent?: string;
+
+    /** How rounded corners are. Absent keeps the theme's own corner radius. */
+    corners?: CornerStyle;
+
+    /** The font, by the id of an entry in the font catalog (for example `inter`). Absent keeps the theme's own font. */
+    font?: string;
 }
 
-export const ProfileAppearancePropertyNames: (keyof ProfileAppearance)[] = ['colorScheme', 'accent'];
+export const ProfileAppearancePropertyNames: (keyof ProfileAppearance)[] = ['colorScheme', 'accent', 'corners', 'font'];

package/profiles/ProfileIdentity.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 { ProfileLogo } from './ProfileLogo';
+
+/**
+ * Who the application is: the name and the logo every blueprint draws, set once for the whole application. Switching the shell or the menu
+ * mode never changes them; changing them changes every blueprint at once.
+ */
+export interface ProfileIdentity {
+    /** The application name the shell shows. Absent means the host's application name. */
+    name?: string;
+
+    /** The logo. Absent means initials taken from the name. */
+    logo?: ProfileLogo;
+
+    /** Whether the name is shown beside the logo mark. Absent means it is shown. */
+    showName?: boolean;
+}
+
+export const ProfileIdentityPropertyNames: (keyof ProfileIdentity)[] = ['name', 'logo', 'showName'];

package/profiles/ProfileLogo.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 { LogoKind } from './LogoKind';
+
+/**
+ * The application's logo. Every member is kept even when the {@link ProfileLogo.kind} does not use it, so switching the type
+ * back shows what was entered before.
+ */
+export interface ProfileLogo {
+    /** How the logo is made. Absent means initials. */
+    kind?: LogoKind;
+
+    /** Up to two characters for the initials logo. Empty or absent means the first letter of the name, upper-cased. */
+    initials?: string;
+
+    /** One of the closed set of logo icons (see `logoIcons` in the engine) for the icon logo. */
+    icon?: string;
+
+    /**
+     * The image for the image logo, as a `data:` URI with base64 content (PNG, JPG, SVG or WebP, up to 400 KB of image data).
+     * The image travels inline in the profile so it is stored and exported with it.
+     */
+    image?: string;
+}
+
+export const ProfileLogoPropertyNames: (keyof ProfileLogo)[] = ['kind', 'initials', 'icon', 'image'];

package/profiles/UiProfile.ts

@@ -4,6 +4,7 @@
 import { SampleDataSelection } from '../sampleData';
 import { ProfileAppearance } from './ProfileAppearance';
 import { ProfileDefaults } from './ProfileDefaults';
+import { ProfileIdentity } from './ProfileIdentity';
 import { RootTemplate } from './RootTemplate';
 import { TargetSizeClass } from '../sizeClasses';
 
@@ -67,11 +68,14 @@ export interface UiProfile {
      */
     root?: RootTemplate;
 
-    /** The colour scheme and accent colour the application presents. Absent keeps the theme's defaults. */
+    /** The colour scheme, accent colour, corner style and font the application presents. Absent keeps the theme's defaults. */
     appearance?: ProfileAppearance;
 
     /** Application-wide authoring defaults such as the template new screens start from. Absent for none. */
     defaults?: ProfileDefaults;
+
+    /** The application's name and logo, set once and drawn by every blueprint. Absent uses the host's application name and initials taken from it. */
+    identity?: ProfileIdentity;
 }
 
 export const UiProfilePropertyNames: (keyof UiProfile)[] = [
@@ -85,4 +89,5 @@ export const UiProfilePropertyNames: (keyof UiProfile)[] = [
     'root',
     'appearance',
     'defaults',
+    'identity',
 ];

package/profiles/index.ts

@@ -5,5 +5,9 @@ export * from './UiProfile';
 export * from './Theme';
 export * from './ColorScheme';
 export * from './ProfileAppearance';
+export * from './CornerStyle';
+export * from './LogoKind';
+export * from './ProfileLogo';
+export * from './ProfileIdentity';
 export * from './ProfileDefaults';
 export * from './RootTemplate';

package/sampleData/SampleDataPackReference.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 { SampleStatusClassification } from './SampleStatusClassification';
+
 /**
  * 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`).
@@ -17,6 +19,18 @@ export interface SampleDataPackReference {
 
     /** The package-relative path of the pack file, under `sampleData/` and ending in `.json`. */
     path: string;
+
+    /** One line saying what the pack is, shown under its name in a selector. */
+    description?: string;
+
+    /** The names of the pack's main table's columns, in the order a preview shows them. */
+    columns?: string[];
+
+    /** The column whose values are drawn as status pills. */
+    statusColumn?: string;
+
+    /** Which values of the status column are good, pending, bad or neutral; any other value is neutral. */
+    statuses?: SampleStatusClassification;
 }
 
-export const SampleDataPackReferencePropertyNames: (keyof SampleDataPackReference)[] = ['id', 'title', 'locale', 'path'];
+export const SampleDataPackReferencePropertyNames: (keyof SampleDataPackReference)[] = ['id', 'title', 'locale', 'path', 'description', 'columns', 'statusColumn', 'statuses'];

package/sampleData/SampleStatus.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.
+
+/** How a pill for a status value is coloured. */
+export enum SampleStatus {
+    /** A positive state: active, delivered, approved. */
+    Good = 'good',
+
+    /** A state that is in progress or waiting. */
+    Pending = 'pending',
+
+    /** A negative state: rejected, overdue, out of stock. */
+    Bad = 'bad',
+
+    /** Anything else; the class of every value the pack does not name. */
+    Neutral = 'neutral',
+}

package/sampleData/SampleStatusClassification.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.
+
+/** Which values of a pack's status column belong to which {@link SampleStatus}. A value in none of the lists is neutral. */
+export interface SampleStatusClassification {
+    good?: string[];
+
+    pending?: string[];
+
+    bad?: string[];
+
+    neutral?: string[];
+}
+
+export const SampleStatusClassificationPropertyNames: (keyof SampleStatusClassification)[] = ['good', 'pending', 'bad', 'neutral'];

package/sampleData/index.ts

@@ -10,3 +10,5 @@ export * from './SampleDataPackReference';
 export * from './SampleDataMapping';
 export * from './SampleDataBinding';
 export * from './SampleDataSelection';
+export * from './SampleStatus';
+export * from './SampleStatusClassification';

package/screens/TemplateMetadata.ts

@@ -57,8 +57,17 @@ export interface TemplateMetadata {
 
     /** For a shell: the name of the slot every screen's content is placed in. Absent means `content`. */
     primaryOutlet?: string;
+
+    /** For a shell: the navigation mode the application starts in when the shell is chosen. The author can change it afterwards. */
+    defaultMenuMode?: string;
+
+    /** For a shell offered as a card: its title. Falls back to the template's display name, then its name. */
+    displayName?: string;
+
+    /** For a shell offered as a card: its one-line description. */
+    description?: string;
 }
 
 export const TemplateMetadataPropertyNames: (keyof TemplateMetadata)[] = [
-    'type', 'category', 'scopes', 'compatibility', 'attribution', 'license', 'licenseUrl', 'sliceKinds', 'thumbnail', 'role', 'primaryOutlet',
+    'type', 'category', 'scopes', 'compatibility', 'attribution', 'license', 'licenseUrl', 'sliceKinds', 'thumbnail', 'role', 'primaryOutlet', 'defaultMenuMode', 'displayName', 'description',
 ];