@cratis/event-models 0.240.1 → 0.242.0

package/dist/screen-editor/Preview/previewDataView.d.ts

@@ -0,0 +1,94 @@
+/** A data element of a screen: the query it reads, the read model it yields and whether that is a collection. */
+export interface PreviewDataSource {
+    readonly query: string;
+    readonly typeName: string;
+    readonly isCollection: boolean;
+}
+/** A column or a field of a table or a summary: the property it shows and the label it carries. */
+export interface PreviewDataField {
+    readonly property: string;
+    readonly label: string;
+}
+/**
+ * Every data element of the screens: the pairs of a query and the read model it yields that the tables and summaries of the preview read their rows by.
+ *
+ * @param content Anything that holds screens.
+ * @returns The data sources, in the order they are met.
+ */
+export declare function previewDataSourcesOf(content: unknown): PreviewDataSource[];
+/**
+ * The query a table or a summary of a read model reads its rows from: the one whose data element yields the same read model, a collection for a table and a
+ * single record for a summary, and the other kind when the screen has only that one.
+ *
+ * @param sources The data sources of the screens.
+ * @param typeName The read model the table or summary shows.
+ * @param wantsCollection Whether it is a table, which shows many rows.
+ * @returns The name of the query, or `undefined` when no data element yields that read model.
+ */
+export declare function queryOfTypeName(sources: readonly PreviewDataSource[], typeName: string, wantsCollection: boolean): string | undefined;
+/**
+ * The rows a query's sample data answers, each a plain record.
+ *
+ * @param result What the render scope holds for the query.
+ * @returns The rows; none when the query has no sample data.
+ */
+export declare function rowsOfQueryResult(result: unknown): Record<string, unknown>[];
+/**
+ * How a value reads in a cell: the text itself, a number as it is, a flag as yes or no, and what is nested as its JSON.
+ *
+ * @param value The value of the property in a row.
+ * @returns The text to show.
+ */
+export declare function cellText(value: unknown): string;
+/**
+ * The columns or fields an element carries in one of its slots, in the order they are written.
+ *
+ * @param element The table or the summary.
+ * @param slot The slot that holds them: `columns` or `fields`.
+ * @returns The properties and their labels; a label that was not written is the property.
+ */
+export declare function previewFieldsOf(element: {
+    slots?: Record<string, readonly unknown[]>;
+}, slot: string): PreviewDataField[];
+/** A binding to a value: a path read from the row of a table (`item.orderId`), or from anywhere else the host can resolve. */
+export interface PreviewBinding {
+    readonly path?: string;
+}
+/**
+ * How the bindings of an interaction on a row resolve: `item.<field>` is the field of that row - `with orderId from item.orderId` hands the order the person
+ * double clicked to the screen it opens - and everything else resolves as it does outside the row.
+ *
+ * @param row The row.
+ * @param outer How a binding resolves outside the row.
+ * @returns The resolver for the row.
+ */
+export declare function resolveInRow<TBinding extends PreviewBinding>(row: Record<string, unknown>, outer: (binding: TBinding) => unknown): (binding: TBinding) => unknown;
+/** What the preview does for the actions a row can start: it goes to the screen, and does nothing else - there is no backend behind a preview. */
+export interface PreviewNavigator {
+    navigate(destination: {
+        screen: string;
+    }): unknown;
+}
+/**
+ * The seam the interactions of a table row run through in the preview. Navigating is the one effect a preview has; a command, a dialog and the rest
+ * answer as if nothing happened, because nothing is sent from a preview.
+ *
+ * @param navigator Where the preview goes when a row says to open a screen, or `undefined` outside a preview.
+ * @returns The dispatcher.
+ */
+export declare function previewRowDispatcher(navigator: PreviewNavigator | undefined): {
+    executeCommand: () => Promise<{
+        isSuccess: boolean;
+    }>;
+    navigate: (screen: string) => void;
+    navigateBack: () => void;
+    openDialog: () => Promise<{
+        isConfirmed: boolean;
+    }>;
+    closeDialog: () => void;
+    refreshQuery: () => Promise<void>;
+    setState: () => void;
+    notify: () => void;
+    confirm: () => Promise<boolean>;
+    raise: () => Promise<void>;
+};

package/dist/screen-editor/ScreenEditor/Runtime/screenEditorRuntimeForProfile.d.ts

@@ -1,6 +1,7 @@
 import type { ScenePackageBundle } from '@cratis/scene.react';
 import type { PersistedUiProfile } from '../../UiProfile/PersistedUiProfile';
 import type { SampleDataSelectionSettings } from '../../UiProfile/SampleDataSelectionSettings';
+import { type StoredLook } from '../../UiProfile/withStoredLook';
 import type { ScreenEditorAppearance } from './ScreenEditorAppearance';
 import { type ScreenEditorRuntime } from './screenEditorRuntime';
-export declare function screenEditorRuntimeForProfile(applied?: PersistedUiProfile, bundles?: ScenePackageBundle[], appearance?: ScreenEditorAppearance, sampleData?: SampleDataSelectionSettings): ScreenEditorRuntime;
+export declare function screenEditorRuntimeForProfile(applied?: PersistedUiProfile, bundles?: ScenePackageBundle[], appearance?: ScreenEditorAppearance, sampleData?: SampleDataSelectionSettings, look?: StoredLook): ScreenEditorRuntime;

package/dist/screen-editor/ScreenEditor/Surface/DesignTime/designTimeDataComponents.d.ts

@@ -0,0 +1,8 @@
+import { type ComponentRegistry } from '@cratis/scene.react';
+/**
+ * The components the surface draws a screenplay table and summary with: the heading and labels the screen says, over sample rows and values.
+ *
+ * @param registry The runtime's registry, whose own table and summary draw what is not a screenplay's.
+ * @returns The registry entries that replace Scene's two for design time.
+ */
+export declare function designTimeDataComponents(registry: ComponentRegistry): ComponentRegistry;

package/dist/screen-editor/ScreenEditor/Surface/DesignTime/sampleCellValue.d.ts

@@ -0,0 +1,9 @@
+export declare const sampleRows = 3;
+/**
+ * A sample value for a property of a read model.
+ *
+ * @param property The property name, as the table's column or the summary's field names it.
+ * @param row Which sample row it is for, so the rows differ.
+ * @returns The text to draw in the cell.
+ */
+export declare function sampleCellValue(property: string, row: number): string;

package/dist/screen-editor/ScreenEditor/Templates/nativeStandIns.d.ts

@@ -0,0 +1,29 @@
+import type { SceneElement } from '@cratis/scene.model';
+export interface NativeEntry {
+    at?: number;
+    text?: string;
+}
+/**
+ * The stand-ins for what a screen keeps natively in one of its slots.
+ *
+ * @param entries The `native.slots[slot]` entries of the screen.
+ * @param slot The slot they sit in, which keeps their ids apart from the other slots'.
+ * @returns A read-only element for each directive the entries hold, in the order the entries state them.
+ */
+export declare function nativeStandIns(entries: readonly NativeEntry[] | undefined, slot: string): SceneElement[];
+export interface FormStandInSource {
+    name?: string;
+    forCommand?: string;
+    fields?: {
+        name?: string;
+        label?: string;
+    }[];
+}
+/**
+ * The stand-ins for the command forms of a screen.
+ *
+ * @param forms The `forms` of the screen.
+ * @param placed The commands a form element already placed on the canvas stands for, which are not drawn twice.
+ * @returns A read-only form for each command that is not placed.
+ */
+export declare function formStandIns(forms: readonly FormStandInSource[] | undefined, placed?: ReadonlySet<string>): SceneElement[];

package/dist/screen-editor/UiProfile/StoredUiProfileShape.d.ts

@@ -0,0 +1,53 @@
+/** A reference to a template, as the application stores it. */
+export interface StoredTemplateReference {
+    source: string;
+    blueprint: string;
+    id: string;
+    version: string;
+    isNone: boolean;
+}
+/** The root template (the shell) and its options, as the application stores them. */
+export interface StoredUiProfileRoot {
+    template: StoredTemplateReference;
+    optionsJson: string;
+}
+/** The defaults for new work, as the application stores them. */
+export interface StoredUiProfileDefaults {
+    newScreenTemplate: StoredTemplateReference;
+}
+/** The complete profile in the root-template shape: what the designer saves. */
+/** The application's name and logo as stored; every member empty takes Scene's default. */
+export interface StoredUiProfileIdentity {
+    name: string;
+    logoKind: string;
+    initials: string;
+    icon: string;
+    image: string;
+    showName: boolean;
+}
+/** The members Scene added for the designer, stored beside the root, appearance and defaults. */
+export interface StoredUiProfileStyle {
+    identity: StoredUiProfileIdentity;
+    corners: string;
+    font: string;
+}
+export interface UiProfileDocumentValue {
+    packages: string[];
+    templatePacks: string[];
+    resolvedPackages: string[];
+    theme: string;
+    root: StoredUiProfileRoot;
+    appearance: {
+        colorScheme: string;
+        accent: string;
+    };
+    defaults: StoredUiProfileDefaults;
+    style: StoredUiProfileStyle;
+}
+/** What was stored before the designer opened, so what it does not edit is saved back as it was. */
+export interface StoredUiProfileShape {
+    settings: import('./UiProfileSettings').UiProfileSettings;
+    root?: StoredUiProfileRoot;
+    defaults?: StoredUiProfileDefaults;
+    style?: StoredUiProfileStyle;
+}

package/dist/screen-editor/UiProfile/profileStyle.d.ts

@@ -0,0 +1,19 @@
+import type { StoredUiProfileStyle } from './StoredUiProfileShape';
+import type { UiProfileSettings } from './UiProfileSettings';
+/**
+ * Turns the identity, corners and font a draft holds into what the application stores. Anything the author left out is stored empty, which reads
+ * back as Scene's default: no member is invented here.
+ *
+ * @param settings The settings to store.
+ * @returns The stored style.
+ */
+export declare function styleOf(settings: UiProfileSettings): StoredUiProfileStyle;
+/**
+ * Reads a stored style back into the choices a draft edits. A profile stored before the style existed has none and keeps Scene's defaults; a corner
+ * style this build does not know is dropped rather than thrown, so the page still opens.
+ *
+ * @param settings The settings read so far.
+ * @param style What was stored beside the profile, if anything.
+ * @returns The settings with the identity, corners and font.
+ */
+export declare function withStoredStyle(settings: UiProfileSettings, style: StoredUiProfileStyle | undefined | null): UiProfileSettings;

package/dist/screen-editor/UiProfile/settingsFromPersisted.d.ts

@@ -0,0 +1,17 @@
+import type { ScenePackageBundle } from '@cratis/scene.react';
+import { PersistedUiProfile } from './PersistedUiProfile';
+import type { SampleDataSelectionSettings } from './SampleDataSelectionSettings';
+import { UiProfileSettings } from './UiProfileSettings';
+/**
+ * Reads stored settings back into the choices a draft edits.
+ *
+ * A stored color scheme or navigation mode this build does not know - written by a newer shell, say - falls
+ * back to the default rather than throwing, so the page still opens and the next apply repairs the value.
+ *
+ * @param persisted The stored profile.
+ * @param sampleData The application's sample data choice, which is stored apart from the profile; absent when none was made.
+ * @param bundles Every known package bundle. With them, a stored layout that is not the blueprint's first one is read back as the profile's root template; without
+ * them the profile is read as the blueprint's shell.
+ * @returns The {@link UiProfileSettings} it records.
+ */
+export declare function settingsFromPersisted(persisted: PersistedUiProfile, sampleData?: SampleDataSelectionSettings, bundles?: ScenePackageBundle[]): UiProfileSettings;

package/dist/screen-editor/UiProfile/withStoredLook.d.ts

@@ -0,0 +1,25 @@
+import type { ScenePackageBundle } from '@cratis/scene.react';
+import type { UiProfile } from '@cratis/scene.model';
+import type { PersistedUiProfile } from './PersistedUiProfile';
+import type { SampleDataSelectionSettings } from './SampleDataSelectionSettings';
+import type { StoredUiProfileRoot, StoredUiProfileStyle } from './StoredUiProfileShape';
+/** What an application stored beside the legacy members of its UI profile, which is the application's own look: the shell with its menu options and the identity, corners and font. */
+export interface StoredLook {
+    /** The root template and the options of the shell (menu mode and theme), when the profile is in the root-template shape. */
+    root?: StoredUiProfileRoot;
+    /** The name, logo, corners and font, when the profile stored them. */
+    style?: StoredUiProfileStyle | null;
+}
+/**
+ * Gives a Scene profile the application's own look: the accent and colour scheme, the logo and name, the corners and font, and the shell's menu mode
+ * and menu theme. The preview and the UI Profile designer draw from the same resolution, so an application previews as the designer shows it and as it
+ * will run - not in the theme's bare defaults, which is all the legacy members of the stored profile carry.
+ *
+ * @param profile The profile built from the legacy members.
+ * @param persisted The stored profile the legacy members are read from.
+ * @param look What the profile stored beside them.
+ * @param sampleData The application's sample data choice.
+ * @param bundles The bundles in play.
+ * @returns The profile with the look; the input when the application stored none.
+ */
+export declare function withStoredLook(profile: UiProfile, persisted: PersistedUiProfile, look: StoredLook | undefined, sampleData?: SampleDataSelectionSettings, bundles?: ScenePackageBundle[]): UiProfile;

package/dist/screen-editor/UiProfile/withStoredRoot.d.ts

@@ -0,0 +1,11 @@
+import type { StoredUiProfileRoot } from './StoredUiProfileShape';
+import type { UiProfileSettings } from './UiProfileSettings';
+/**
+ * The settings with the root template the application stored: its template with its version pin, the options of the shell and the navigation mode among them.
+ * A profile that stored none (the legacy shape, or the bare shell) is left as it is - the blueprint's first layout is then its shell.
+ *
+ * @param settings What the legacy members say.
+ * @param root The stored root template, when the profile has one.
+ * @returns The settings, with `root` when the profile stored one.
+ */
+export declare function withStoredRoot(settings: UiProfileSettings, root: StoredUiProfileRoot | undefined): UiProfileSettings;