graphwise-reactodia 0.0.1-TR2 → 0.0.1-TR20

package/COPYING.LESSER

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/NOTICE

@@ -0,0 +1,41 @@
+graphwise-reactodia -- Graphwise wrapper around the Reactodia graph explorer.
+
+Copyright (C) 2026 Ontotext AD
+
+This library is free software: you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or (at your
+option) any later version.
+
+This library is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
+License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this library (COPYING.LESSER), together with the GNU General
+Public License it supplements (COPYING). If not, see
+<https://www.gnu.org/licenses/>.
+
+-------------------------------------------------------------------------------
+
+Reactodia Workspace
+
+The published bundle (dist/) incorporates Reactodia Workspace, built from
+the Ontotext AD fork:
+
+    https://github.com/Ontotext-AD/reactodia-workspace-fork
+
+The corresponding source for a given release is tag v<version> of
+
+    https://github.com/Ontotext-AD/graphwise-reactodia
+
+together with the reactodia-workspace submodule commit it pins in the fork.
+
+Copyright (C) 2026 Alexey Morozov (https://github.com/AlexeyMz)
+Copyright (C) 2019 metaphacts GmbH.
+Copyright (C) 2026 Ontotext AD. Modified from reactodia-workspace v0.35.0.
+
+Reactodia Workspace is licensed under the GNU Lesser General Public License
+version 2.1 or (at your option) any later version. It is incorporated here
+under version 3 of that license, as permitted by that option.

package/README.md

@@ -1,2 +1,226 @@
 # graphwise-reactodia
-Graphwise wrapper around Reactodia graph explorer
+
+Graphwise wrapper (Stencil component) around the [Reactodia](https://github.com/reactodia/reactodia-workspace) graph explorer.
+
+Reactodia is vendored as a **git submodule** (`reactodia-workspace/`, pointing at our [fork](https://github.com/Ontotext-AD/reactodia-workspace-fork)).
+It's built first, then consumed by Stencil as a normal ES module via a `file:` dependency.
+
+## Setup
+
+After cloning the repo for the first time you will need to update git submodules, which will fetch the Reactodia fork:
+```bash
+cd graphwise-reactodia
+git submodule update --init --recursive
+```
+
+Install dependencies, which will symlink the Reactodia fork into `node_modules`:
+```bash
+npm install
+```
+
+## Develop
+For development run:
+```bash
+npm start
+```
+
+## Build
+Build the fork and the Stencil component:
+```bash
+npm run build 
+```
+
+`npm start` and `npm run build` both run `reactodia:build` first, which installs and builds the fork
+(`reactodia:install` + `reactodia:compile`), then runs `reactodia:dedupe-react` to remove the fork's own
+`react`/`react-dom` copies so the bundle ends up with a single React instance.
+
+## Seeding the canvas
+
+By default the canvas starts empty and the user populates it through the workspace search bar. The host can
+instead pre-populate it on startup by passing seed data through `config` (see `ReactodiaAppProps`). Seeding is
+skipped when an `initialDiagram` is restored (e.g. after a language-change remount). There are two mechanisms,
+handled in `reactodia-app.ts`:
+
+### `seedIris` — lazy seed
+
+`config.seedIris` is a list of element(node) IRIs. Each IRI is placed as a placeholder node, then `seedCanvas` calls
+the model's `requestData()` so both the element data **and** its links are fetched from the SPARQL endpoint.
+Use this when the relationships are persisted in the repository and can be resolved lazily.
+
+### `seedGraph` — pre-resolved seed
+
+`config.seedGraph` is a list of `Triple` objects (mirroring GraphDB's `rest/explore-graph` shape).
+`seedGraphCanvas` places each `source`/`target` as an element and draws the supplied links directly, then
+requests **element data only** (`requestElementData`) — it does *not* ask the endpoint for links.
+
+Use this for the result of a CONSTRUCT/DESCRIBE query, whose relationships are computed and therefore not
+persisted in the DB, so they can't be fetched lazily and must be supplied by the host.
+
+`Triple` (`models/triple.ts`):
+
+| Field           | Description                                              |
+|-----------------|----------------------------------------------------------|
+| `source`        | Source element IRI.                                      |
+| `target`        | Target element IRI.                                      |
+| `rawPredicates` | Full (absolute) predicate IRIs — used as the link types. |
+
+When both are supplied `seedGraph` takes precedence over `seedIris`.
+
+## UI configuration
+
+`config.ui` (`UiConfig`) changes the default UI configuration. It is JSON and read once on mount. It is partial and
+merged over the default: objects are merged key by key, lists replace the default whole.
+
+The default UI configuration:
+
+```ts
+{
+  mainToolbar: {dock: ToolbarDock.NW},
+  actionsToolbar: {dock: ToolbarDock.SW},
+  menu: {items: [CLEAR_ALL, EXPORT_PNG, EXPORT_SVG, PRINT, EXPORT_JSON, IMPORT_JSON]},
+  nodeActions: [GROUP, REMOVE, EXPAND, OPEN_LINK, CONNECTIONS, ADD_TO_FILTER, ANNOTATE, ESTABLISH_LINK]
+}
+```
+
+| Field            | Description                                                                        |
+|------------------|------------------------------------------------------------------------------------|
+| `mainToolbar`    | `ToolbarPosition` of the toolbar with the menu and the search.                     |
+| `actionsToolbar` | `ToolbarPosition` of the toolbar with undo, redo and layout.                       |
+| `menu.items`     | `MenuItem`s of the main menu, in order. An empty list hides the menu.              |
+| `nodeActions`    | `NodeAction`s shown around a selected node.                                        |
+
+`ToolbarPosition` is `{dock?: ToolbarDock, offsetX?: number, offsetY?: number}`.
+
+E.g. the actions toolbar at the top right, without the link node action:
+
+```ts
+element.config = {
+  queryFunction,
+  ui: {
+    actionsToolbar: {dock: ToolbarDock.NE},
+    nodeActions: [GROUP, REMOVE, EXPAND, CONNECTIONS, ADD_TO_FILTER, ANNOTATE, ESTABLISH_LINK]
+  }
+};
+```
+
+An unknown value is skipped and reported as `unknown-ui-config`; an unknown dock keeps the default toolbar position.
+
+## Events
+
+The element sends every event to the host through one DOM event, `graphwiseReactodiaEvent`. The event
+only informs the host and it bubbles. Its name is exported as `GRAPHWISE_REACTODIA_EVENT`.
+
+`detail` is an `EventDetail`: `{type, payload}`. `type` is an `EventType`; `payload` depends on it:
+
+| `type`        | `payload`     | Dispatched when                     |
+|---------------|---------------|-------------------------------------|
+| `error`       | `ErrorReport` | An error is reported.               |
+| `text-search` | none          | The user searches entities by text. |
+
+Checking `type` narrows `payload`:
+
+```ts
+element.addEventListener(GRAPHWISE_REACTODIA_EVENT, (event) => {
+  const detail = (event as CustomEvent<EventDetail>).detail;
+  if (detail.type === EventType.ERROR) {
+    const {code, error} = detail.payload; // an ErrorReport
+  }
+});
+```
+
+`EventDetail<T>` is one event, e.g. for a handler of a single type:
+
+```ts
+function onError(detail: EventDetail<EventType.ERROR>): void {
+  const {code, error} = detail.payload;
+}
+```
+
+## Error handling
+
+The element dispatches an `error` event for every error it reports; the codes below list them.
+
+`payload` is an `ErrorReport`:
+
+| Field   | Description                                                                             |
+|---------|-----------------------------------------------------------------------------------------|
+| `code`  | An `ErrorCode`. The host translates by it.                                              |
+| `error` | Always an `Error`; its `message` is untranslated developer text, meant for the logs.    |
+
+`ErrorCode`:
+
+| Code                    | Reported when                                              |
+|-------------------------|------------------------------------------------------------|
+| `missing-required-prop` | A required prop is missing.                                |
+| `data-fetch`            | A SPARQL data provider call failed.                        |
+| `diagram-load`          | The startup load, a reload or a repository switch failed.  |
+| `diagram-import`        | The uploaded file was rejected or its import failed.       |
+| `local-diagram-read`    | Reading the diagram from local storage failed.             |
+| `local-diagram-save`    | Saving the diagram in local storage failed.                |
+| `unknown-ui-config`     | `config.ui` has an unknown value, which is skipped.        |
+
+Failed PNG/SVG exports and printing are not reported.
+
+Every failure is reported once: an error is skipped when it, or an error in its `cause` chain, is already reported.
+Aborted requests are not reported.
+
+## Editing the fork
+
+Reactodia lives in the `reactodia-workspace/` submodule, which is its own git repo (remote:
+[reactodia-workspace-fork](https://github.com/Ontotext-AD/reactodia-workspace-fork)). The parent repo does not
+store the fork's files — it stores a single pointer to a commit in the fork. So a fork change involves two repos
+and two commits: one in the fork (the source change) and one here (the pointer bump).
+
+Simple setup in IntelliJ so you don't switch between projects: map the submodule as a second VCS root 
+(Settings → Version Control → Directory Mappings → add `reactodia-workspace`) so both repos appear 
+in the branch widget and Commit panel.
+
+### Testing fork changes locally
+
+`npm start` and `npm run build` both run `reactodia:build`, which recompiles the fork from its current
+files, so edits are picked up immediately.
+
+### Persisting a fork change
+1. In the fork (reactodia-workspace/): create a new branch,
+2. Make edit, commit and push changes 
+3. Open a PR against the fork's `master` (reactodia-workspace-fork).
+4. Merge the PR.
+5. In the parent (graphwise-reactodia/):
+   1. `git submodule update --remote` to fetch the fork's new commit and update the pointer,
+   2. Make a branch, commit the pointer bump and push.
+
+The parent commit's diff is just the pointer, never the fork's direct file changes.
+Always bump the pointer to a commit that is merged and pushed on the fork's `master`, so
+anyone running `git submodule update` can fetch it.
+
+## Test
+
+Cypress runs against the dev server (`http://localhost:3333`), so start the app first in a separate terminal:
+
+```bash
+npm start
+```
+
+Then, in another terminal:
+```bash
+npm run cy:open  # for interactive browser tests
+npm run cy:run   # for headless tests
+```
+
+OR run tests in a container
+
+```bash
+docker compose up
+```
+
+## License
+
+Copyright (C) 2026 Ontotext AD.
+
+Licensed under the GNU Lesser General Public License v3.0 or later (`LGPL-3.0-or-later`); see
+[`COPYING.LESSER`](COPYING.LESSER) and [`COPYING`](COPYING).
+
+The published bundle includes [Reactodia Workspace](https://github.com/reactodia/reactodia-workspace)
+(`LGPL-2.1-or-later`), built from our [fork](https://github.com/Ontotext-AD/reactodia-workspace-fork) and used
+under LGPL-3.0 through its "or later" option. The source for a release is tag `v<version>` of this repo
+together with the fork commit its `reactodia-workspace` submodule pins. See [`NOTICE`](NOTICE).