@cratis/event-models 0.259.3 → 0.259.5

package/dist/screen-editor/Crash/CrashBoundary.d.ts

@@ -0,0 +1,36 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import type { CrashStrings } from './CrashStrings';
+import type { CrashContext } from './crashReport';
+export interface CrashBoundaryProps {
+    /** What is guarded - shown in the panel and written into the report. */
+    context: CrashContext;
+    /** Leaves what is guarded; without it the panel has no "Close". */
+    onClose?: (() => void) | undefined;
+    /** `fixed` covers the page; `fill` fills the box the boundary is drawn in. */
+    layout?: 'fixed' | 'fill';
+    /** Values identifying what is guarded: the boundary recovers by itself when any of them changes. */
+    resetKeys?: readonly unknown[];
+    /** Called with the error and the component stack once the crash is on screen, so a host can record it. */
+    onCrash?: (error: Error, componentStack: string | null | undefined) => void;
+    strings?: CrashStrings;
+    children: ReactNode;
+}
+interface CrashBoundaryState {
+    error: Error | null;
+    componentStack: string | null | undefined;
+    attempt: number;
+    resetSignature: string;
+}
+/**
+ * Catches an error thrown while drawing what it guards and draws the {@link CrashPanel} in its place - what failed, Reload, Try again, Close and
+ * "Report this error" - so a crash is never a blank page. Scope it tightly: around a preview, an editor, a lazily loaded page.
+ */
+export declare class CrashBoundary extends Component<CrashBoundaryProps, CrashBoundaryState> {
+    state: CrashBoundaryState;
+    static getDerivedStateFromError(error: Error): Partial<CrashBoundaryState>;
+    static getDerivedStateFromProps(props: CrashBoundaryProps, state: CrashBoundaryState): CrashBoundaryState | null;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+    private readonly recover;
+}
+export {};

package/dist/screen-editor/Crash/CrashPanel.d.ts

@@ -0,0 +1,26 @@
+import { type CrashStrings } from './CrashStrings';
+import { type CrashContext } from './crashReport';
+export interface CrashPanelProps {
+    /** The error that was caught. */
+    error: unknown;
+    /** What the boundary knows about what it guards. */
+    context: CrashContext;
+    /** React's component stack, when the error was caught by a boundary. */
+    componentStack?: string | null | undefined;
+    /** Rebuilds what failed without reloading the page. Without it there is no "Try again". */
+    onRecover?: (() => void) | undefined;
+    /** Leaves what failed (a preview, an editor). Without it there is no "Close". */
+    onClose?: (() => void) | undefined;
+    /**
+     * `fixed` covers the page so the message cannot end up behind what failed (the default); `fill` fills the box it is drawn in, for a surface that is
+     * itself an overlay or a pane.
+     */
+    layout?: 'fixed' | 'fill';
+    strings?: CrashStrings;
+}
+/**
+ * What a crash looks like: never a blank page. It says what failed - the surface, the component, the template or screen and the error text - and offers
+ * Reload, Try again, Close and "Report this error", which copies the technical detail (secrets redacted) and opens a prefilled issue. It is drawn with
+ * plain elements and no provider, because it replaces something that failed and must not depend on it.
+ */
+export declare const CrashPanel: ({ error, context, componentStack, onRecover, onClose, layout, strings }: CrashPanelProps) => import("react").JSX.Element;

package/dist/screen-editor/Crash/CrashStrings.d.ts

@@ -0,0 +1,33 @@
+/** The words of the crash panel, which says what failed instead of leaving a blank page. */
+export interface CrashStrings {
+    /** The heading: `{surface}` is what stopped, such as `The preview`. */
+    title: string;
+    /** The line under the heading. */
+    lead: string;
+    /** The label of the line that names the surface. */
+    surface: string;
+    /** The label of the line that names the component that threw. */
+    component: string;
+    /** The label of the line that names the template. */
+    template: string;
+    /** The label of the line that names the screen. */
+    screen: string;
+    /** The label of the line that carries the error text. */
+    error: string;
+    /** Reloads the page. */
+    reload: string;
+    /** Rebuilds what failed without reloading the page. */
+    tryAgain: string;
+    /** Leaves what failed, when it is something that can be left (a preview, an editor). */
+    close: string;
+    /** Copies the technical detail and opens a prefilled issue. */
+    report: string;
+    /** Said after the technical detail was copied. */
+    copied: string;
+    /** Said when the technical detail could not be copied; it is shown to copy by hand. */
+    copyFailed: string;
+    /** The label of the disclosure that holds the technical detail. */
+    technicalDetail: string;
+}
+/** English words, for specs and for the places that have none of their own. */
+export declare const defaultCrashStrings: CrashStrings;

package/dist/screen-editor/Crash/crashReport.d.ts

@@ -0,0 +1,80 @@
+/** What a boundary knows about the thing it guards - shown to the user and written into the report. */
+export interface CrashContext {
+    /** What stopped, in the user's words: `The preview`, `The screen editor`, `Play`. */
+    surface: string;
+    /** The component that threw, when the boundary knows it. Otherwise it is read from React's component stack. */
+    component?: string | undefined;
+    /** The template being drawn or edited. */
+    template?: string | undefined;
+    /** The screen being drawn or edited. */
+    screen?: string | undefined;
+    /** Anything else worth reading in the report (ids, node names). Never secrets: values are redacted anyway. */
+    details?: Readonly<Record<string, string | undefined>>;
+}
+/** Where the report is filed. */
+export declare const crashReportIssuesUrl = "https://github.com/Cratis/StudioIssues/issues/new";
+/**
+ * Removes what must never leave the browser in a report: bearer tokens, JWTs, cookies, credentials in query strings or JSON, and well-known key shapes.
+ *
+ * @param text Any text.
+ * @returns The text with the secrets replaced.
+ */
+export declare function redactSecrets(text: string): string;
+/**
+ * Reads the nearest component out of React's component stack - the first line is the component that threw.
+ *
+ * @param componentStack The stack React passes to `componentDidCatch`.
+ * @returns The component's name, or `undefined` when the stack names none.
+ */
+export declare function componentOfStack(componentStack: string | null | undefined): string | undefined;
+/**
+ * The location without its query string and fragment values: a path says where the user was, and the query may carry a token.
+ *
+ * @param href A page address.
+ * @returns The address with the query and fragment removed.
+ */
+export declare function locationWithoutSecrets(href: string): string;
+/** What the page knows about its environment - only what helps to reproduce a crash. */
+export interface CrashEnvironment {
+    href: string;
+    userAgent: string;
+    time: Date;
+    version?: string;
+}
+/**
+ * The technical detail of a crash, as plain text for a report: where, what, the error and the component stack - redacted.
+ *
+ * @param error The error that was caught.
+ * @param context What the boundary knows about what it guards.
+ * @param componentStack React's component stack, when there is one.
+ * @param environment The page; the current one when omitted.
+ * @returns The text that is copied by "Report this error".
+ */
+export declare function describeCrash(error: unknown, context: CrashContext, componentStack?: string | null, environment?: CrashEnvironment): string;
+/** What a report says before the host turns it into an address. */
+export interface CrashReportRequest {
+    /** The issue title. */
+    title: string;
+    /** The short summary: what stopped and the error text. */
+    summary: string;
+    /** The full technical detail, redacted. */
+    details: string;
+}
+/** Turns a report into the address that opens it for filing. */
+export type CrashReportLinkBuilder = (request: CrashReportRequest) => string;
+/**
+ * Lets the host decide where a report is filed. Studio hands over the address of its own report dialog, which files into the right tracker with the page
+ * context attached; without a host the report opens a prefilled issue form.
+ *
+ * @param builder Makes the address of a report.
+ */
+export declare function configureCrashReportLinks(builder: CrashReportLinkBuilder): void;
+/**
+ * The address a report opens. The summary is always in it; the full detail is copied to the clipboard as well, because an address has to stay short.
+ *
+ * @param error The error that was caught.
+ * @param context What the boundary knows about what it guards.
+ * @param componentStack React's component stack.
+ * @returns The address that opens the report.
+ */
+export declare function crashReportUrl(error: unknown, context: CrashContext, componentStack?: string | null): string;

package/dist/screen-editor/ScreenEditor/Host/ScreenEditorBoundary.d.ts

@@ -1,8 +1,10 @@
 import type { ReactNode } from 'react';
 import type { ScreenEditorStrings } from '../Inspector/ScreenEditorStrings';
+import type { ScreenEditorSubject } from './ScreenEditorHost';
 export interface ScreenEditorBoundaryProps {
     strings: ScreenEditorStrings;
-    onClose?: () => void;
+    subject?: ScreenEditorSubject;
+    onClose?: (() => void) | undefined;
     children: ReactNode;
 }
-export declare const ScreenEditorBoundary: ({ strings, onClose, children }: ScreenEditorBoundaryProps) => import("react").JSX.Element;
+export declare const ScreenEditorBoundary: ({ strings, subject, onClose, children }: ScreenEditorBoundaryProps) => import("react").JSX.Element;

package/dist/screen-editor/ScreenEditor/Host/ScreenEditorHost.d.ts

@@ -1,5 +1,5 @@
 import type { ApplicationStructure } from '@cratis/scene.model';
-import type { SceneDocument, TemplateScope } from '@cratis/scene.model';
+import type { SceneDocument, ScreenTemplate, TemplateScope } from '@cratis/scene.model';
 import type { QueryCandidate } from '@cratis/scene.model';
 import type { ConfigurationDestination } from '@cratis/components/ConfigurationEditor';
 import type { ScreenEditorRuntime } from '../Runtime/screenEditorRuntime';
@@ -35,6 +35,7 @@ export interface ScreenEditorEnvironment {
         colorTokens?: readonly ColorToken[];
         references?: (target: string) => readonly EditorReference[];
     };
+    ownTemplates?: readonly ScreenTemplate[];
     templateScope?: TemplateScope;
     navigation?: ScreenEditorNavigation;
     location?: ScreenEditorLocation;

package/dist/screen-editor/ScreenEditor/Host/createScreenEditorEnvironment.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigurationDestination } from '@cratis/components/ConfigurationEditor';
-import type { TemplateScope } from '@cratis/scene.model';
+import type { ScreenTemplate, TemplateScope } from '@cratis/scene.model';
 import type { ScreenEditorRuntime } from '../Runtime/screenEditorRuntime';
 import type { QuillLoader } from '@cratis/scene.primereact';
 import type { StateChangeSlice } from '../Actions/StateChangeSlice';
@@ -15,6 +15,7 @@ export interface ScreenEditorEnvironmentSource {
     richText?: QuillLoader | false;
     fileUpload?: ScreenEditorFileUpload;
     templateScope?: TemplateScope;
+    ownTemplates?: readonly ScreenTemplate[];
     navigation?: ScreenEditorEnvironment['navigation'];
     location?: ScreenEditorEnvironment['location'];
 }

package/dist/screen-editor/ScreenTemplates/ApplicationTemplate.d.ts

@@ -0,0 +1,25 @@
+import type { ScreenTemplate, SliceKind, TemplateRole, TemplateScope } from '@cratis/scene.model';
+/** A screen template built for the application, as the catalog needs to know it. */
+export interface ApplicationTemplate {
+    /** The template's identifier. */
+    id: string;
+    /** The template's name. */
+    name: string;
+    /** The category the template is listed under (spec TPL1). Absent for a template made before categories existed. */
+    category?: string;
+    /** The levels the template may be chosen at. Absent for a template made before scopes existed: it fits every level a screen sits at. */
+    scopes?: TemplateScope[];
+    /** For a template made for slices, the kinds of slice it fits. Absent for one made before this was recorded: it fits every slice that has a screen. */
+    sliceKinds?: SliceKind[];
+    /** `Root` when the template is made to be the application's shell, which its document says. */
+    role?: TemplateRole;
+    /** The outlet of a shell that holds the screen when a screen does not say which one it fills. */
+    primaryOutlet?: string;
+    /** The outlets a shell offers. */
+    outlets?: string[];
+    /**
+     * The template as its saved Scene document declares it - the content it places and the arrangement it lays out - when the document is known. A shell that is
+     * drawn needs it: the metadata above says where a template may be used, only the template itself says what it draws.
+     */
+    template?: ScreenTemplate;
+}

package/dist/screen-editor/ScreenTemplates/ownTemplateSource.d.ts

@@ -0,0 +1,34 @@
+import { TemplateScope, type ScreenTemplate } from '@cratis/scene.model';
+import type { TemplateSource } from '@cratis/scene.engine';
+import { ApplicationTemplate } from './ApplicationTemplate';
+/** The levels an application template fits when it was made without saying: everywhere a screen sits. */
+export declare const defaultApplicationTemplateScopes: readonly TemplateScope[];
+/** The name Scene sees the application's own templates under. It is never shown: own templates are listed without a package. */
+export declare const ownTemplatePackageName = "application";
+/**
+ * Presents the application's own templates to Scene as a template source, so the one applicability rule that
+ * covers blueprints covers them too.
+ *
+ * An own template has no slot contract, so it carries no `fitsSlot`; its identifier is its Scene name and the
+ * name the user gave it is its display name.
+ *
+ * @param templates The templates built for the application.
+ * @returns The Scene source.
+ */
+export declare function ownTemplateSource(templates: readonly ApplicationTemplate[]): TemplateSource;
+/**
+ * Presents screen templates that are already in Scene's shape (see {@link namedAsScreensRefer}) as the application's own template source.
+ *
+ * @param templates The application's own screen templates.
+ * @returns The Scene source.
+ */
+export declare function ownTemplateSourceOf(templates: readonly ScreenTemplate[]): TemplateSource;
+/**
+ * The application's own templates as Scene screen templates named the way a screen refers to them: by the name its author gave. A slice
+ * stores that name (`screen template SideSummary`); the identifier the catalog keeps is only how Studio finds the template's document, so
+ * a screen editor that looks a template up by identifier calls a template a screen already uses "missing" (StudioIssues#998).
+ *
+ * @param templates The templates built for the application.
+ * @returns The Scene templates, with the author's name as the name and the display name.
+ */
+export declare function namedAsScreensRefer(templates: readonly ApplicationTemplate[]): ScreenTemplate[];