graphwise-reactodia 0.0.1-TR16 → 0.0.1-TR17

package/dist/types/components/graphwise-reactodia/graphwise-reactodia.d.ts

@@ -1,6 +1,8 @@
+import { EventEmitter } from '../../stencil-public-runtime';
 import { SparqlDataProviderSettings } from '@reactodia/workspace';
 import { LanguageKey } from './i18n/language-key';
 import { ReactodiaConfig } from './models/reactodia-config';
+import { ErrorReport } from './models/error/error-report';
 /**
  * A web component that renders a graph with the Reactodia workspace.
  *
@@ -14,6 +16,7 @@ import { ReactodiaConfig } from './models/reactodia-config';
  */
 export declare class GraphwiseReactodia {
     private readonly hostElement?;
+    private readonly subscriptions;
     /**
      * The active repository id. Appended to {@link queryFunction} as the request `url`;
      * changing it re-points the graph at the new repository (and resets the canvas),
@@ -43,6 +46,10 @@ export declare class GraphwiseReactodia {
      * The reactodia theme to use
      */
     theme?: 'light' | 'dark';
+    /**
+     * Fires, when an error has occurred. The host decides how to handle it.
+     */
+    errorEmitter: EventEmitter<ErrorReport>;
     private reactRoot?;
     /**
      * `connectedCallback` and the watchers can run before all props are set: when the component's
@@ -59,5 +66,7 @@ export declare class GraphwiseReactodia {
     componentDidLoad(): void;
     disconnectedCallback(): void;
     render(): any;
+    private subscribeToErrors;
     private renderGraph;
+    private reportMissingPropError;
 }

package/dist/types/components/graphwise-reactodia/models/error/error-callback.d.ts

@@ -0,0 +1,5 @@
+import { ErrorReport } from './error-report';
+/**
+ * Callback invoked with every reported error.
+ */
+export type ErrorCallback = (report: ErrorReport) => void;

package/dist/types/components/graphwise-reactodia/models/error/error-cause.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A link in the `cause` chain of a thrown value: the value itself, its `cause`, the cause of that, and so on.
+ * Anything can be thrown, so a link is not necessarily an `Error` and neither field is guaranteed.
+ */
+export interface ErrorCause {
+    /** The error name, e.g. `AbortError`. */
+    name?: unknown;
+    /** The next link in the chain. */
+    cause?: unknown;
+}

package/dist/types/components/graphwise-reactodia/models/error/error-code.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The stable category of a reported error. The host uses it to choose its own message.
+ */
+export declare enum ErrorCode {
+    /** A required prop is missing. */
+    MISSING_REQUIRED_PROP = "missing-required-prop",
+    /** A SPARQL data provider call failed. */
+    DATA_FETCH = "data-fetch",
+    /** The startup load, a reload or a repository switch failed. */
+    DIAGRAM_LOAD = "diagram-load",
+    /** The uploaded file was rejected or its import failed. */
+    DIAGRAM_IMPORT = "diagram-import",
+    /** Reading the diagram from local storage failed. */
+    LOCAL_DIAGRAM_READ = "local-diagram-read",
+    /** Saving the diagram in local storage failed. */
+    LOCAL_DIAGRAM_SAVE = "local-diagram-save"
+}

package/dist/types/components/graphwise-reactodia/models/error/error-report.d.ts

@@ -0,0 +1,17 @@
+import { ErrorCode } from './error-code';
+/**
+ * Name of the DOM event the `graphwise-reactodia` element dispatches for every reported error.
+ */
+export declare const GRAPHWISE_REACTODIA_ERROR_EVENT = "graphwiseReactodiaError";
+/**
+ * A failure the wrapper announces to the host.
+ */
+export interface ErrorReport {
+    code: ErrorCode;
+    /**
+     * The thrown value, passed on unchanged. The wrapper and the fork throw `Error`s with an untranslated `message`, but
+     * a failure of the host's `config.queryFunction` arrives as whatever it rejected with (e.g. an HTTP error response),
+     * so narrow it before use.
+     */
+    error: unknown;
+}

package/dist/types/components/graphwise-reactodia/reactodia-app.d.ts

@@ -8,7 +8,7 @@ export declare function mountReactodia(container: HTMLElement, props: ReactodiaA
 /**
  * Re-points the diagram at a new SPARQL endpoint by recreating it with a fresh data provider.
  * The canvas is reset to empty, matching the initial mount, since the data of another repository
- * has nothing to do with the current graph.
+ * has nothing to do with the current graph. A failure is reported, not thrown.
  */
 export declare function updateReactodia(props: ReactodiaAppProps): Promise<void>;
 /**

package/dist/types/components/graphwise-reactodia/services/diagram-storage/diagram-storage.service.d.ts

@@ -5,6 +5,7 @@ import type { SerializedDiagram } from '@reactodia/workspace';
 export declare class DiagramStorageService {
     static readonly ID = "DiagramStorageService";
     private static readonly STORAGE_KEY;
+    private readonly errorService;
     /**
      * Load the persisted diagram from the local store, or `undefined` when nothing is stored (or the stored value
      * is unreadable).

package/dist/types/components/graphwise-reactodia/services/error/error.service.d.ts

@@ -0,0 +1,50 @@
+import { Subscription } from '../../models/subscription';
+import { ErrorCallback } from '../../models/error/error-callback';
+import { ErrorCode } from '../../models/error/error-code';
+/**
+ * Service that collects the failures of the wrapper and the fork, so they can be announced to the host.
+ */
+export declare class ErrorService {
+    static readonly ID = "ErrorService";
+    private static readonly ABORT_ERROR_NAME;
+    private callback?;
+    private readonly reported;
+    /**
+     * Reports a failure to the host, unless it's an abort, or this exact error object is already reported
+     * from another place.
+     *
+     * The same error object may be reported from different places. E.g. a query that fails while a diagram loads is
+     * reported by the data provider decorator as `data-fetch`, and then reaches the `catch` around the load, which
+     * reports it as `diagram-load`. Only the first one is announced.
+     *
+     * The `cause` is checked because the fork wraps whatever fails during a diagram import in a new error:
+     *
+     * ```ts
+     * // reactodia-workspace/src/editor/dataDiagramModel.ts, importLayout
+     * } catch (error) {
+     *   throw new Error('Reactodia: failed to import a layout', {cause: error});
+     * }
+     * ```
+     *
+     * We need to check the cause to make sure we don't report the same error/abort more than once.
+     *
+     * @param code The category of the failure.
+     * @param thrown The thrown value.
+     */
+    report(code: ErrorCode, thrown: unknown): void;
+    /**
+     * Subscribes to the reported errors, replacing the previous subscriber.
+     *
+     * @param callback Called with every reported error.
+     * @returns A {@link Subscription} that, when called, removes the callback, unless it has already been replaced.
+     */
+    subscribe(callback: ErrorCallback): Subscription;
+    /**
+     * Whether any link of the given cause chain is an abort or is already reported.
+     */
+    private isAbortedOrAlreadyReported;
+    /**
+     * The thrown value followed by its `cause`, the cause of that, and so on, for as long as they are objects.
+     */
+    private causeChain;
+}

package/dist/types/components.d.ts

@@ -8,9 +8,11 @@ import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
 import { ReactodiaConfig } from "./components/graphwise-reactodia/models/reactodia-config";
 import { LanguageKey } from "./components/graphwise-reactodia/i18n/language-key";
 import { SparqlDataProviderSettings } from "@reactodia/workspace";
+import { ErrorReport } from "./components/graphwise-reactodia/models/error/error-report";
 export { ReactodiaConfig } from "./components/graphwise-reactodia/models/reactodia-config";
 export { LanguageKey } from "./components/graphwise-reactodia/i18n/language-key";
 export { SparqlDataProviderSettings } from "@reactodia/workspace";
+export { ErrorReport } from "./components/graphwise-reactodia/models/error/error-report";
 export namespace Components {
     /**
      * A web component that renders a graph with the Reactodia workspace.
@@ -45,7 +47,14 @@ export namespace Components {
         "theme"?: 'light' | 'dark';
     }
 }
+export interface GraphwiseReactodiaCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLGraphwiseReactodiaElement;
+}
 declare global {
+    interface HTMLGraphwiseReactodiaElementEventMap {
+        "graphwiseReactodiaError": ErrorReport;
+    }
     /**
      * A web component that renders a graph with the Reactodia workspace.
      * The component is backed by a SPARQL endpoint but is endpoint-agnostic: the host passes
@@ -56,6 +65,14 @@ declare global {
      * wrapper and is supplied through the `providerSettings` prop.
      */
     interface HTMLGraphwiseReactodiaElement extends Components.GraphwiseReactodia, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLGraphwiseReactodiaElementEventMap>(type: K, listener: (this: HTMLGraphwiseReactodiaElement, ev: GraphwiseReactodiaCustomEvent<HTMLGraphwiseReactodiaElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLGraphwiseReactodiaElementEventMap>(type: K, listener: (this: HTMLGraphwiseReactodiaElement, ev: GraphwiseReactodiaCustomEvent<HTMLGraphwiseReactodiaElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
     }
     var HTMLGraphwiseReactodiaElement: {
         prototype: HTMLGraphwiseReactodiaElement;
@@ -89,6 +106,10 @@ declare namespace LocalJSX {
           * @default LanguageKey.EN
          */
         "language"?: LanguageKey;
+        /**
+          * Fires, when an error has occurred. The host decides how to handle it.
+         */
+        "onGraphwiseReactodiaError"?: (event: GraphwiseReactodiaCustomEvent<ErrorReport>) => void;
         /**
           * Query preset for the SPARQL data provider, owned and configured by the host. A DOM property (an object, not an attribute) passed in from outside the wrapper. Required: the wrapper has no default preset and throws when it is missing. Changing it rebuilds the data provider and reloads the graph with it, keeping the current diagram.
          */

package/dist/types/index.d.ts

@@ -1 +1,4 @@
 export { CLEAR_DIAGRAM_STORAGE_EVENT } from './components/graphwise-reactodia/models/clear-diagram-storage-event';
+export { GRAPHWISE_REACTODIA_ERROR_EVENT } from './components/graphwise-reactodia/models/error/error-report';
+export { ErrorCode } from './components/graphwise-reactodia/models/error/error-code';
+export type { ErrorReport } from './components/graphwise-reactodia/models/error/error-report';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphwise-reactodia",
-  "version": "0.0.1-TR16",
+  "version": "0.0.1-TR17",
   "description": "Graphwise wrapper around the Reactodia graph explorer.",
   "license": "LGPL-3.0-or-later",
   "author": "Ontotext AD",