graphwise-reactodia 0.0.1-TR16 → 0.0.1-TR18

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 { EventDetail } from './models/event/event-detail';
 /**
  * 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 for every event to the host, differentiated by `detail.type`.
+     */
+    eventEmitter: EventEmitter<EventDetail>;
     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 subscribeToEvents;
     private renderGraph;
+    private reportMissingPropError;
 }

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,13 @@
+import { ErrorCode } from './error-code';
+/**
+ * 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/models/event/event-callback.d.ts

@@ -0,0 +1,5 @@
+import { EventDetail } from './event-detail';
+/**
+ * Callback invoked with every emitted event.
+ */
+export type EventCallback = (detail: EventDetail) => void;

package/dist/types/components/graphwise-reactodia/models/event/event-detail.d.ts

@@ -0,0 +1,48 @@
+import { EventType } from './event-type';
+import { ErrorReport } from '../error/error-report';
+/**
+ * Name of the DOM event the `graphwise-reactodia` element dispatches for every event.
+ */
+export declare const GRAPHWISE_REACTODIA_EVENT = "graphwiseReactodiaEvent";
+/**
+ * The payload of each {@link EventType}. It is the single place that ties an event type to its payload, so
+ * adding an event is one {@link EventType} value and one entry here.
+ *
+ * @example
+ * ```ts
+ * interface EventPayloadMap {
+ *   [EventType.ERROR]: ErrorReport;
+ *   // A new event:
+ *   [EventType.NEW_TYPE]: NewTypePayload;
+ * }
+ * ```
+ */
+interface EventPayloadMap {
+    [EventType.ERROR]: ErrorReport;
+}
+/**
+ * Maps an {@link EventType} to its event detail: `{type, payload}`, with the payload from
+ * {@link EventPayloadMap}. If no event type is provided, it is the union of the details of all event types.
+ *
+ * @template T The event type to map.
+ *
+ * @example
+ * ```ts
+ * // Any event, narrowed by its type.
+ * function onEvent(detail: EventDetail): void {
+ *   if (detail.type === EventType.ERROR) {
+ *     const {code, error} = detail.payload; // an ErrorReport
+ *   }
+ * }
+ *
+ * // One event.
+ * const detail: EventDetail<EventType.ERROR> = {type: EventType.ERROR, payload: {code, error}};
+ * ```
+ */
+export type EventDetail<T extends EventType = EventType> = {
+    [K in T]: {
+        type: K;
+        payload: EventPayloadMap[K];
+    };
+}[T];
+export {};

package/dist/types/components/graphwise-reactodia/models/event/event-type.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The kind of event the wrapper announces to the host. It selects the payload of an {@link EventDetail}.
+ */
+export declare enum EventType {
+    ERROR = "error"
+}

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,41 @@
+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 readonly eventService;
+    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;
+    /**
+     * 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/graphwise-reactodia/services/event/event.service.d.ts

@@ -1,9 +1,25 @@
 import { Subscription } from '../../models/subscription';
+import { EventCallback } from '../../models/event/event-callback';
+import { EventDetail } from '../../models/event/event-detail';
 /**
  * Service for event based operations
  */
 export declare class EventService {
     static readonly ID = "EventService";
+    private callback?;
+    /**
+     * Announces an event to the host.
+     *
+     * @param detail The event detail.
+     */
+    emit(detail: EventDetail): void;
+    /**
+     * Subscribes to the emitted events, replacing the previous subscriber.
+     *
+     * @param callback Called with every emitted event.
+     * @returns A {@link Subscription} that, when called, removes the callback, unless it has already been replaced.
+     */
+    subscribe(callback: EventCallback): Subscription;
     /**
      * Subscribes to the host's "clear persisted diagram" command.
      *

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 { EventDetail } from "./components/graphwise-reactodia/models/event/event-detail";
 export { ReactodiaConfig } from "./components/graphwise-reactodia/models/reactodia-config";
 export { LanguageKey } from "./components/graphwise-reactodia/i18n/language-key";
 export { SparqlDataProviderSettings } from "@reactodia/workspace";
+export { EventDetail } from "./components/graphwise-reactodia/models/event/event-detail";
 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 {
+        "graphwiseReactodiaEvent": EventDetail;
+    }
     /**
      * 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 for every event to the host, differentiated by `detail.type`.
+         */
+        "onGraphwiseReactodiaEvent"?: (event: GraphwiseReactodiaCustomEvent<EventDetail>) => 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,6 @@
 export { CLEAR_DIAGRAM_STORAGE_EVENT } from './components/graphwise-reactodia/models/clear-diagram-storage-event';
+export { GRAPHWISE_REACTODIA_EVENT } from './components/graphwise-reactodia/models/event/event-detail';
+export { EventType } from './components/graphwise-reactodia/models/event/event-type';
+export type { EventDetail } from './components/graphwise-reactodia/models/event/event-detail';
+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-TR18",
   "description": "Graphwise wrapper around the Reactodia graph explorer.",
   "license": "LGPL-3.0-or-later",
   "author": "Ontotext AD",