graphwise-reactodia 0.0.1-TR2 → 0.0.1-TR20

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

@@ -0,0 +1,36 @@
+import { SparqlQueryFunction } from './sparql/sparql-query-function';
+import { Triple } from './triple';
+import { UiConfig } from './ui/ui-config';
+/**
+ * Host-supplied configuration read once when the workspace mounts (not reactive).
+ *
+ * Groups the inputs the host wires up before the graph is created: the SPARQL transport
+ * and the optional set of entities to pre-populate the canvas with. Passed to the
+ * `graphwise-reactodia` component as a single DOM property (an object, not an attribute).
+ */
+export interface ReactodiaConfig {
+    /**
+     * HTTP transport for the SPARQL requests. Set by the host so requests go through the host's
+     * HTTP layer (auth, interceptors) instead of a built-in `fetch`.
+     */
+    queryFunction: SparqlQueryFunction;
+    /**
+     * IRIs of the elements(nodes) to place on the canvas on startup. When provided, each IRI is added
+     * as an element and its data (labels, types, properties) and links are resolved from the
+     * SPARQL provider, then the workspace lays them out. Note that when using this seed method reactodia will request data
+     * from the connected sparql endpoint for both elements and links, so if the resources are not in the DB, then this approach will not work.
+     * (e.g. in the case of a construct query)
+     */
+    seedIris?: string[];
+    /**
+     * Pre-resolved triples (source, rawPredicate, target) to place on the canvas on startup. Date for the links is provided
+     * here, so reactodia will not request data for them. Data for nodes will be requested based on the IRIs of the source
+     * and target of the links. This is useful for visualizing the result of a CONSTRUCT query, whose relationships are
+     * computed and not persisted in the repository
+     */
+    seedGraph?: Triple[];
+    /**
+     * A partial UI configuration, merged over the default UI configuration. JSON-serializable.
+     */
+    ui?: UiConfig;
+}

package/dist/types/components/graphwise-reactodia/models/sparql/sparql-query-function.d.ts

@@ -0,0 +1,6 @@
+import { SparqlQueryParams } from './sparql-query-params';
+/**
+ * HTTP transport for the SPARQL requests. The data provider passes it to the fork, so the compiler checks it against
+ * the fork's `SparqlQueryFunction`.
+ */
+export type SparqlQueryFunction = (params: SparqlQueryParams) => Promise<Response>;

package/dist/types/components/graphwise-reactodia/models/sparql/sparql-query-params.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The HTTP request a {@link SparqlQueryFunction} sends.
+ */
+export interface SparqlQueryParams {
+    url: string;
+    body?: string;
+    headers: {
+        [header: string]: string;
+    };
+    method: string;
+    signal?: AbortSignal;
+}

package/dist/types/components/graphwise-reactodia/models/subscription-list.d.ts

@@ -0,0 +1,26 @@
+import { Subscription } from './subscription';
+/**
+ * A collection of {@link Subscription}s that can be released together. Components collect the
+ * subscriptions they open and call {@link unsubscribeAll} on teardown so nothing is left
+ * listening.
+ */
+export declare class SubscriptionList {
+    private items;
+    constructor(subscriptions?: Subscription[]);
+    /**
+     * Adds a subscription to the list.
+     */
+    add(subscription: Subscription): void;
+    /**
+     * Adds multiple subscriptions to the list.
+     */
+    addAll(subscriptions: Subscription[]): void;
+    /**
+     * Removes a subscription from the list without unsubscribing it.
+     */
+    remove(subscription: Subscription): void;
+    /**
+     * Calls every subscription (unsubscribing it) and clears the list.
+     */
+    unsubscribeAll(): void;
+}

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

@@ -0,0 +1,4 @@
+/**
+ * A subscription: calling it unsubscribes (removes the underlying listener).
+ */
+export type Subscription = () => void;

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

@@ -0,0 +1,19 @@
+/**
+ * A pre-resolved edge to place on the canvas on startup, mirroring GraphDB's
+ * `rest/explore-graph` link shape. Used to visualize the result of a CONSTRUCT query, whose
+ * relationships are computed and therefore not persisted in the repository, so they cannot be
+ * fetched lazily through the SPARQL provider and must be supplied directly.
+ *
+ * The host adapts its source data into this neutral shape (e.g. the workbench maps the
+ * `rest/explore-graph/graph` response onto {@link rawPredicates}).
+ */
+export interface Triple {
+    /** Source element IRI. */
+    source: string;
+    /** Target element IRI. */
+    target: string;
+    /**
+     * Full (absolute) predicate IRIs.
+     */
+    rawPredicates: string[];
+}

package/dist/types/components/graphwise-reactodia/models/ui/menu-config.d.ts

@@ -0,0 +1,8 @@
+import { MenuItem } from './menu-item';
+/**
+ * The workspace main menu.
+ */
+export interface MenuConfig {
+    /** The menu entries, in order. An empty list hides the menu. */
+    items?: MenuItem[];
+}

package/dist/types/components/graphwise-reactodia/models/ui/menu-item.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An entry of the workspace main menu.
+ */
+export declare enum MenuItem {
+    /** Removes all nodes from the diagram. */
+    CLEAR_ALL = "clear-all",
+    /** Exports the diagram as a PNG image. */
+    EXPORT_PNG = "export-png",
+    /** Exports the diagram as an SVG image. */
+    EXPORT_SVG = "export-svg",
+    /** Prints the diagram. */
+    PRINT = "print",
+    /** Exports the diagram as a JSON file. */
+    EXPORT_JSON = "export-json",
+    /** Imports a diagram from a JSON file. */
+    IMPORT_JSON = "import-json"
+}

package/dist/types/components/graphwise-reactodia/models/ui/node-action.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A button shown around a selected node that acts on it.
+ */
+export declare enum NodeAction {
+    /** Groups or ungroups the selected nodes. */
+    GROUP = "group",
+    /** Removes the node from the diagram. */
+    REMOVE = "remove",
+    /** Expands or collapses the node to show its properties. */
+    EXPAND = "expand",
+    /** Opens the node IRI. */
+    OPEN_LINK = "open-link",
+    /** Opens the menu to navigate to connected nodes. */
+    CONNECTIONS = "connections",
+    /** Searches for nodes connected to this one. */
+    ADD_TO_FILTER = "add-to-filter",
+    /** Adds an annotation to the node. */
+    ANNOTATE = "annotate",
+    /** Draws a new link from the node; for an entity, only in authoring mode. */
+    ESTABLISH_LINK = "establish-link"
+}

package/dist/types/components/graphwise-reactodia/models/ui/resolved-toolbar-position.d.ts

@@ -0,0 +1,8 @@
+import { ToolbarDock } from './toolbar-dock';
+import { ToolbarPosition } from './toolbar-position';
+/**
+ * A toolbar position with its dock set.
+ */
+export interface ResolvedToolbarPosition extends ToolbarPosition {
+    dock: ToolbarDock;
+}

package/dist/types/components/graphwise-reactodia/models/ui/resolved-ui-config.d.ts

@@ -0,0 +1,12 @@
+import { MenuConfig } from './menu-config';
+import { NodeAction } from './node-action';
+import { ResolvedToolbarPosition } from './resolved-toolbar-position';
+/**
+ * The host's UI configuration merged over the default, with every field set.
+ */
+export interface ResolvedUiConfig {
+    mainToolbar: ResolvedToolbarPosition;
+    actionsToolbar: ResolvedToolbarPosition;
+    menu: Required<MenuConfig>;
+    nodeActions: NodeAction[];
+}

package/dist/types/components/graphwise-reactodia/models/ui/toolbar-dock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The side or corner of the canvas a toolbar is docked to.
+ */
+export declare enum ToolbarDock {
+    NW = "nw",
+    N = "n",
+    NE = "ne",
+    E = "e",
+    SE = "se",
+    S = "s",
+    SW = "sw",
+    W = "w"
+}

package/dist/types/components/graphwise-reactodia/models/ui/toolbar-position.d.ts

@@ -0,0 +1,11 @@
+import { ToolbarDock } from './toolbar-dock';
+/**
+ * Where a toolbar is placed on the canvas.
+ */
+export interface ToolbarPosition {
+    dock?: ToolbarDock;
+    /** Horizontal offset from the dock, in pixels. */
+    offsetX?: number;
+    /** Vertical offset from the dock, in pixels. */
+    offsetY?: number;
+}

package/dist/types/components/graphwise-reactodia/models/ui/ui-config.d.ts

@@ -0,0 +1,17 @@
+import { MenuConfig } from './menu-config';
+import { NodeAction } from './node-action';
+import { ToolbarPosition } from './toolbar-position';
+/**
+ * The UI configuration a host passes. It is partial and merged over the default UI configuration: objects are merged
+ * key by key, lists replace the default whole.
+ */
+export interface UiConfig {
+    /** The toolbar with the menu and the search. */
+    mainToolbar?: ToolbarPosition;
+    /** The toolbar with undo, redo and layout. */
+    actionsToolbar?: ToolbarPosition;
+    /** The main menu in the main toolbar. */
+    menu?: MenuConfig;
+    /** The actions shown around a selected node. */
+    nodeActions?: NodeAction[];
+}

package/dist/types/components/graphwise-reactodia/node-action/node-actions.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from 'react';
+import { NodeAction } from '../models/ui/node-action';
+/**
+ * The `Halo` children for the given node actions.
+ */
+export declare function createNodeActions(actions: NodeAction[]): ReactElement[];

package/dist/types/components/graphwise-reactodia/providers/service/service-inject.d.ts

@@ -0,0 +1,13 @@
+import { Service } from './service';
+/**
+ * Injects the singleton instance of the given service class from the {@link ServiceProvider}.
+ *
+ * @param serviceClass The class of the service to inject.
+ * @returns The shared instance of the specified service class.
+ * @template T The type of the service to inject.
+ * @example
+ * ```typescript
+ * const diagramStateService = service(DiagramStateService);
+ * ```
+ */
+export declare function service<T>(serviceClass: Service<T>): T;

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

@@ -0,0 +1,28 @@
+/**
+ * Interface for injectable services by the service provider. Each service needs to have a static unique ID, which
+ * is used by the {@link ServiceProvider} to cache and retrieve the singleton instance of the service. Unique IDs ensure
+ * correct working of the service provider, when the services are minified
+ *
+ * @template T the type of the service
+ */
+export interface Service<T> {
+    readonly ID: string;
+    new (): T;
+}
+/**
+ * Decorator for a service class.
+ * It receives the class and simply type checks it with the {@link Service} interface.
+ * Works as a contract, which enforces the service class to have a static ID member.
+ * We can't simply implement the interface, since this will enforce the ID to be an instance member, which is not what we want.
+ *
+ * @param _serviceClass The decorated service class, checked for its ID and discarded.
+ * @template T The type of the service instance.
+ * @example
+ * ```TypeScript
+ * @Service
+ * export class WindowService {
+ *   static readonly ID = 'WindowService';
+ * }
+ * ```
+ */
+export declare function Service<T>(_serviceClass: Service<T>): void;

package/dist/types/components/graphwise-reactodia/providers/service/service.provider.d.ts

@@ -0,0 +1,16 @@
+import { Service } from './service';
+/**
+ * Provider for all {@link Service} instances. Services are singletons: there is only one
+ * instance of each service, created on demand and cached here so every consumer shares it.
+ */
+export declare class ServiceProvider {
+    private static readonly SERVICE_INSTANCES;
+    /**
+     * Returns the instance of the given service type, creating and caching it on first request.
+     *
+     * @param serviceClass The service type to retrieve.
+     * @returns The shared instance of the service.
+     * @template T The type of the service to retrieve.
+     */
+    static get<T>(serviceClass: Service<T>): T;
+}

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

@@ -6,8 +6,9 @@ import { ReactodiaAppProps } from './models/reactodia-app-props';
  */
 export declare function mountReactodia(container: HTMLElement, props: ReactodiaAppProps): Root;
 /**
- * Re-points the diagram at a new SPARQL endpoint or query preset by recreating it with a
- * fresh data provider. The canvas is reset to empty, matching the initial mount.
+ * 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. A failure is reported, not thrown.
  */
 export declare function updateReactodia(props: ReactodiaAppProps): Promise<void>;
 /**

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

@@ -0,0 +1,36 @@
+import type { DataDiagramModel, DataProvider, SerializedDiagram } from '@reactodia/workspace';
+import { Subscription } from '../../models/subscription';
+/**
+ * Callback invoked with the current diagram layout whenever it changes.
+ */
+export type DiagramChangeCallback = (diagram: SerializedDiagram) => void;
+/**
+ * Service for diagram related operations and subscriptions
+ */
+export declare class DiagramService {
+    static readonly ID = "DiagramService";
+    private static readonly NOTIFY_DEBOUNCE_MS;
+    private static readonly HISTORY_CHANGED_EVENT;
+    /**
+     * Replaces the diagram content with the given serialization. Element data is requested from the data provider and
+     * the links between the imported elements are validated against it.
+     *
+     * @param model The diagram model to import into.
+     * @param dataProvider The data provider to bind to the diagram.
+     * @param diagram The serialization to import. When `undefined`, the diagram is cleared.
+     * @param signal Optional signal to abort the import.
+     */
+    importDiagram(model: DataDiagramModel, dataProvider: DataProvider, diagram: SerializedDiagram | undefined, signal?: AbortSignal): Promise<void>;
+    /**
+     * Subscribes to diagram changes. On every debounced change the current layout is
+     * exported and passed to the callback.
+     * Debounce time for the callback trigger is needed, because certain events (like moving a node) can trigger
+     * multiple `historyChanged` events in a short time.
+     *
+     * @param model The diagram model to observe.
+     * @param onChangeCallback Called with the exported layout when the diagram changes.
+     * @returns A {@link Subscription} that, when called, removes the listener and drops any
+     * pending notification.
+     */
+    subscribeToDiagramChange(model: DataDiagramModel, onChangeCallback: DiagramChangeCallback): Subscription;
+}

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

@@ -0,0 +1,24 @@
+import type { SerializedDiagram } from '@reactodia/workspace';
+/**
+ * Service for downloading and uploading the diagram as a file. The file content is the same
+ * {@link SerializedDiagram} that is persisted to the local store.
+ */
+export declare class DiagramFileService {
+    static readonly ID = "DiagramFileService";
+    static readonly FILE_EXTENSION = ".json";
+    private static readonly MIME_TYPE;
+    /**
+     * Downloads the given diagram serialization as a file with the given name.
+     */
+    download(diagram: SerializedDiagram, fileName: string): void;
+    /**
+     * Reads a diagram serialization from the given file.
+     *
+     * @throws Error when the file is not valid JSON or is not a serialized diagram.
+     */
+    read(file: File): Promise<SerializedDiagram>;
+    /**
+     * Checks if the provided value is a serialized diagram
+     */
+    private isSerializedDiagram;
+}

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

@@ -0,0 +1,27 @@
+import type { SerializedDiagram } from '@reactodia/workspace';
+/**
+ * Service for local store-related diagram operations
+ */
+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).
+     */
+    load(): SerializedDiagram | undefined;
+    /**
+     * Persists the given diagram serialization.
+     */
+    save(diagram: SerializedDiagram): void;
+    /**
+     * Removes the persisted diagram. Used when a new view (a seed) should take precedence over
+     * previously saved edits.
+     */
+    clear(): void;
+    /**
+     * Local storage getter
+     */
+    private get storage();
+}

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

@@ -0,0 +1,30 @@
+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.
+     *
+     * @param onClear Called whenever the event fires.
+     * @returns A {@link Subscription} that, when called, removes the listener.
+     */
+    subscribeToClearDiagramStorage(onClear: () => void): Subscription;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Service that provides access to browser window-related functionality.
+ */
+export declare class WindowService {
+    static readonly ID = "WindowService";
+    getWindow(): Window;
+}

package/dist/types/components/graphwise-reactodia/styles/type-style.resolver.d.ts

@@ -0,0 +1,11 @@
+import { TypeStyleResolver } from '@reactodia/workspace';
+/**
+ * Colors an element by its type: each type takes the next color from the palette, which wraps
+ * around once it runs out
+ *
+ * Returns `undefined` for elements without a type (placeholders and other non-entity elements) and
+ * when the host does not define the palette, leaving Reactodia to fall back to its own hash-based
+ * colors.
+ */
+export declare const resolveTypeStyle: TypeStyleResolver;
+export declare const resetColors: () => void;

package/dist/types/components/graphwise-reactodia/testing/storage.mock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal in-memory {@link Storage}, so services that read `localStorage` can be exercised
+ * without a real browser store and asserted against directly. Shared across test suites.
+ */
+export declare class StorageMock implements Storage {
+    private readonly store;
+    get length(): number;
+    clear(): void;
+    getItem(key: string): string | null;
+    key(index: number): string | null;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+}
+/**
+ * Creates a fresh {@link StorageMock}. Suites install the returned instance as the global
+ * `localStorage` themselves.
+ */
+export declare function createStorageMock(): StorageMock;

package/dist/types/components/graphwise-reactodia/ui-config/default-ui-config.d.ts

@@ -0,0 +1,5 @@
+import { ResolvedUiConfig } from '../models/ui/resolved-ui-config';
+/**
+ * The default UI configuration: Reactodia's behaviour, plus the diagram download and upload in the menu.
+ */
+export declare const DEFAULT_UI_CONFIG: ResolvedUiConfig;

package/dist/types/components/graphwise-reactodia/ui-config/ui-config-mapper.d.ts

@@ -0,0 +1,14 @@
+import { DefaultWorkspaceProps } from '@reactodia/workspace';
+import { UiConfig } from '../models/ui/ui-config';
+/**
+ * The `DefaultWorkspace` props the UI configuration sets.
+ */
+export type UiConfigProps = Pick<DefaultWorkspaceProps, 'menu' | 'mainToolbar' | 'actionsToolbar' | 'halo'>;
+/**
+ * Merges the host's UI configuration over the default and maps the result to `DefaultWorkspace` props. A `null` or
+ * missing field keeps the default; objects merge key by key and lists replace the default whole. Unknown values are
+ * reported and left out; a repeated list entry is kept once.
+ *
+ * @param ui The host's UI configuration.
+ */
+export declare function toWorkspaceProps(ui: UiConfig | undefined): UiConfigProps;

package/dist/types/components/graphwise-reactodia/utils/object-util.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Merges an object with default values. Ported from the GraphDB Workbench `ObjectUtil.mergeWithDefaults`.
+ *
+ * For each property in `defaults`, if the value in `object` is `null` or `undefined`, the default value is used instead.
+ * Nested objects are merged recursively. Arrays and other non-plain values are treated as single values and are not
+ * merged.
+ *
+ * The returned object is a new object and does not share references with the inputs. The inputs must be
+ * structured-cloneable.
+ *
+ * @param object Source object whose values take precedence over defaults.
+ * @param defaults Default values applied when properties are missing or null.
+ * @returns A new object containing the merged result.
+ */
+export declare function mergeWithDefaults<T extends object>(object: object, defaults: T): T;