@hydranium/glsp-client-theia 1.0.0-next.245 → 1.0.0-next.247

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +56 -132
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,91 +1,23 @@
1
1
  # `@hydranium/glsp-client-theia`
2
2
 
3
- Theia client primitives for the hydranium **GLSP head** — the companion of
4
- `@hydranium/glsp-server` in the
5
- [Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
6
-
7
- It sits between `@eclipse-glsp/theia-integration` and an adopter's diagram: the
8
- module composition, the instrumented dispatcher and bounds updater, the loading
9
- overlay, the marker-propagation switch, and the backend socket bridge. Install it
10
- if you are mounting a hydranium GLSP diagram in a Theia application.
3
+ The Theia integration for the
4
+ [Hydranium](https://github.com/eclipse-emfcloud/hydranium) GLSP head, the
5
+ companion of `@hydranium/glsp-server`. Install it to mount a Hydranium diagram
6
+ in a Theia application. It builds on `@eclipse-glsp/theia-integration` and
7
+ `@hydranium/client-theia`.
11
8
 
12
9
  ## What it gives you
13
10
 
14
- - **`AbstractHydraniumGlspTheiaFrontendModule`** — a `GLSPTheiaFrontendModule`
15
- subclass that absorbs the overrides every adopter otherwise writes verbatim.
16
- You declare `diagramLanguage`, `diagramConfiguration` and `diagramManager`;
17
- optionally set `logLevelPreference` (the base then binds the log-threshold
18
- contribution for you) and override `bindClientContribution()` — returning
19
- `SkipClientContribution` for a secondary diagram type that shares a server with
20
- a primary one.
21
- - **`createGlspClientTheiaModule(context, options)`** — the standard per-diagram
22
- bindings, all unconditional: the cross-head `ChannelLogger`,
23
- `HydraniumGlspActionDispatcher`, `HydraniumDiagramLoader`,
24
- `HydraniumHiddenBoundsUpdater`, `HydraniumGlspMessageService`, and
25
- `HydraniumStatusOverlay`, which keeps GLSP's status overlay on the page after
26
- sprotty's first render replaces the diagram's base div. Each
27
- replaces a GLSP default with a strict superset of its behaviour, so a head that
28
- wants the original rebinds that one token back.
29
- - **Loading feedback that cannot silently vanish.** `HydraniumDiagramLoader`
30
- catches every load failure — the dispatcher-init, connect and first
31
- `RequestModelAction` steps upstream leaves unwrapped — routes it to the Output
32
- channel, and reports it as an error `StatusAction`. It publishes a terminal
33
- `DiagramLoadOutcome`, which `HydraniumGlspDiagramWidget` keys its opaque canvas
34
- overlay on (`DIAGRAM_LOADING_CLASS`, `DIAGRAM_LOADING_FAILED_CLASS`).
35
- `HydraniumGlspMessageService` then drops the now-redundant "Model loading in
36
- progress" toast (`MODEL_LOADING_PROGRESS_TITLE`) and forwards every other
37
- progress report untouched.
38
- - **Instrumentation.** `HydraniumGlspActionDispatcher` logs action traffic into
39
- the shared Output channel and pairs requests with responses — by id, or by kind
40
- for the GLSP flow actions that carry none (`HYDRANIUM_DEFAULT_LOGGED_KINDS`,
41
- `HYDRANIUM_DEFAULT_KIND_PAIRS`, extensible via
42
- `HydraniumGlspActionDispatcherOptions`). `HydraniumHiddenBoundsUpdater` emits
43
- one trace line per bounds request with the measured element count and the raw
44
- `getBBox` cost — the client-side phase that scales with rendered elements
45
- rather than model size.
46
- - **`AbstractHydraniumGlspDiagramConfiguration`** with
47
- `propagateMarkersToProblemsView` — set it `false` for a head whose co-resident
48
- LSP already publishes the same diagnostics, and the per-diagram container binds
49
- `NoOpExternalMarkerManager` instead: markers still decorate the diagram, but
50
- Theia's Problems view stops double-listing them.
51
- - **`AbstractHydraniumGlspDiagramManager`** derives the language-correlated
52
- getters from one descriptor plus a label, and `reopen` replaces a diagram
53
- with a fresh widget in the same tab position, as the Retry of a failed load
54
- does. It reopens every diagram when their client is lost, and a failed one
55
- when a client starts. A diagram's client id is the same for the same widget
56
- in the same window, so a diagram reopened after its client is lost, or
57
- reloaded with its page, takes its old session over with the window's resume
58
- token and keeps its unsaved text.
59
- - **`WindowSessionService`** — the window's id and resume token, claimed as
60
- the frontend starts. The default keeps them in `sessionStorage` and hands
61
- them on only as the page leaves, so a reload resumes and a duplicated tab
62
- draws its own. Rebind it for a different notion of a window.
63
- - **`HydraniumGlspClientContribution`** — for a server that starts late: it
64
- defers `start` until a workspace is open, fails a start that takes longer than
65
- `startupTimeoutMs` (30 s by default), and starts a fresh client after a failed
66
- start or a lost connection, after a delay that grows while clients keep
67
- failing, reporting each attempt through `client-theia`'s
68
- `ConnectionReporter`. `onDidStartClient` and `onDidLoseClient` announce each
69
- client, and each start and loss is logged to the application-scope
70
- `ChannelLogger` an adopter binds with `bindChannelLogger`. Its client is
71
- `HydraniumGlspClient`, which ends a session without the server once the
72
- connection is gone.
73
- - **`HydraniumGlspSaveable`** — the diagram widget's saveable. Each save is a
74
- `RequestSaveModelAction` the server answers: the save resolves on its own
75
- response, and rejects on its own rejection or after 10 s rather than GLSP's
76
- 2 s. It stays dirty while a save is pending, so Theia's exit check still
77
- counts it. The server answers through
78
- `HydraniumGlspRequestSaveModelActionHandler`, which
79
- `AbstractHydraniumGlspDiagramModule` registers; against a server that does
80
- not advertise the request, the saveable behaves as GLSP's does. The dirty
81
- flag follows the server, so an edit whose dirty state has not arrived when
82
- Save All runs is not saved. Under the `fire-and-forget` `SaveDeliveryPolicy`
83
- the server answers before the disk write finishes, and answers a failed
84
- write as saved.
85
- - **Backend (`./node`)** — `GlspServerConnectionHandler` (the socket bridge,
86
- over `@hydranium/client-theia`'s `SocketChannelForwarder`) and
87
- `createGlspConnectionContainerModule(handler)` for the frontend-scoped module
88
- boilerplate.
11
+ - A diagram mounted from one subclass of
12
+ `AbstractHydraniumGlspTheiaFrontendModule`.
13
+ - Load failures shown on the diagram with a Retry, and logged to the Output
14
+ channel beside the diagram's action traffic.
15
+ - A client that waits for a workspace, and starts again after a failed start
16
+ or a lost connection.
17
+ - Unsaved diagram changes kept across a reload or a reconnect, while the server
18
+ stays the same.
19
+ - Problems listed once when the LSP head reports them too.
20
+ - The backend handler that relays the channel to the GLSP server's socket.
89
21
 
90
22
  ## Install
91
23
 
@@ -93,10 +25,6 @@ if you are mounting a hydranium GLSP diagram in a Theia application.
93
25
  npm install @hydranium/glsp-client-theia
94
26
  ```
95
27
 
96
- You must already have a Theia application wired for GLSP — `@eclipse-glsp/client`
97
- and `@eclipse-glsp/theia-integration` are peers, not bundled — and a running
98
- hydranium GLSP server. The declared peer dependencies are:
99
-
100
28
  | Peer | Range |
101
29
  | --------------------------------- | ------------- |
102
30
  | `@eclipse-glsp/client` | `^2.6.0` |
@@ -112,58 +40,54 @@ hydranium GLSP server. The declared peer dependencies are:
112
40
 
113
41
  ## Wiring
114
42
 
115
- This package declares no `theiaExtensions` — it is a library your own Theia
116
- extension builds on. That extension declares the entries; a diagram is one
117
- frontend/backend pair:
118
-
119
- - the **frontend** entry points at a module that
120
- `export default new MyDiagramModule()`, where `MyDiagramModule` extends
121
- `AbstractHydraniumGlspTheiaFrontendModule`. Your `DiagramConfiguration`
122
- subclass calls `createGlspClientTheiaModule` in its container initialisation,
123
- passing the `channelLogger` name. One of the extension's frontend modules
124
- also calls `bindEditorDiskSync` from `@hydranium/client-theia`, since a
125
- diagram save writes a file an editor can have open;
126
- - the **backend** entry is typically
127
- `export default createGlspConnectionContainerModule(MyHandler)`, where
128
- `MyHandler` extends `GlspServerConnectionHandler`. The handler's
129
- `languageContributionId` decides the per-language service path Theia routes
130
- frontend connections to.
131
-
132
- **The `style/` directory needs no action from you.** It holds one stylesheet,
133
- `diagram-loading.css`, for the widget's loading overlay, and the widget module
134
- imports it itself — precisely so an adopter cannot ship an unstyled `div` in
135
- normal flow by forgetting it. It is listed in `files` because it must be present
136
- in the published tarball for that import to resolve; your bundler needs a CSS
137
- loader, which a Theia application's webpack configuration already has. Colours
138
- come from `--theia-*` theme variables, and every rule is overridable from a
139
- stylesheet loaded afterwards.
43
+ This package declares no `theiaExtensions`; your own Theia extension declares
44
+ them, one frontend and backend pair per diagram.
45
+
46
+ - The frontend entry exports `new MyDiagramModule()`, where `MyDiagramModule`
47
+ extends `AbstractHydraniumGlspTheiaFrontendModule` and names the diagram's
48
+ language, configuration and manager. Return a subclass of
49
+ `HydraniumGlspClientContribution` from its `bindClientContribution()`, and
50
+ set its `logLevelPreference` to have it bind the log level preference.
51
+ - Your diagram configuration extends
52
+ `AbstractHydraniumGlspDiagramConfiguration` and calls
53
+ `createGlspClientTheiaModule` from its `configureContainer`, not from the
54
+ frontend module: called earlier, GLSP's own bindings silently replace its
55
+ rebinds. Set `propagateMarkersToProblemsView` to `false` when the LSP head
56
+ already reports the same problems.
57
+ - One frontend module calls `bindEditorDiskSync` from
58
+ `@hydranium/client-theia`, since a diagram save writes a file an editor can
59
+ have open.
60
+ - The backend entry exports `createGlspConnectionContainerModule(MyHandler)`,
61
+ where `MyHandler` extends `GlspServerConnectionHandler`.
62
+
63
+ The widget imports its own stylesheet, so your bundler needs a CSS loader,
64
+ which a Theia application has.
65
+
66
+ For the whole setup, see *Host in Theia* in
67
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
140
68
 
141
69
  ## Entry points
142
70
 
143
- | Subpath | Holds | Environment |
144
- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
145
- | `.` | Re-exports `./browser` — the larger of the two tiers and safe to load anywhere. | browser-neutral (gated) |
146
- | `./browser` | The frontend module bases, `createGlspClientTheiaModule`, the dispatcher, loader, widget and its saveable, bounds updater, message service, diagram manager and configuration bases, `NoOpExternalMarkerManager` | browser / Theia frontend (gated) |
147
- | `./node` | `GlspServerConnectionHandler`, `createGlspConnectionContainerModule` | Node / Theia backend |
148
- | `./testing` | `makeBindRecorder`, the GLSP-module-specific Inversify double (the cross-head doubles live in `@hydranium/client-theia/testing`) | browser-neutral (gated) |
71
+ | Subpath | Use it for | Runs in |
72
+ | ----------------------------- | ---------------------------------------------------- | --------------- |
73
+ | `.` | The same as `./browser` | Theia frontend |
74
+ | `./browser` | The frontend module, configuration and manager bases | Theia frontend |
75
+ | `./node` | The connection handler and its backend module | Theia backend |
76
+ | `./testing` | A binding recorder for testing your modules | browser-neutral |
77
+ | `./style/diagram-loading.css` | The loading overlay's stylesheet, imported for you | browser |
149
78
 
150
- Resolve the subpaths with [a resolver that reads
151
- `exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
152
- `"Node"` (node10) reaches none of them. "Gated" means the
153
- repository's neutral-bundle check enforces that the entry bundles for the
154
- browser with no `node:*` import, transitive ones included; `./node` is
155
- deliberately outside that gate. Also worth reading: [what "gated neutral" does and does not promise](../../docs/contributing/design/browser-hosting.md#what-gated-neutral-does-and-does-not-promise).
79
+ The subpaths need a TypeScript `moduleResolution` that reads `exports`
80
+ (`NodeNext` or `Bundler`); see *Requirements* in
81
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
156
82
 
157
83
  ## Status
158
84
 
159
- Alpha — pre-v0, published as a `1.0.0-next` prerelease on every merge to `main`.
160
- The API is not stable and may change without a deprecation cycle. See
161
- [Adopting Hydranium](../../docs/ADOPTING.md) for the GLSP head's place among
162
- the heads, and the [repository README](../../README.md)
163
- for current status and known limitations.
85
+ Alpha: every release is a prerelease that may break the API, so pin an exact
86
+ version. Guides and known limitations:
87
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
164
88
 
165
89
  ## License
166
90
 
167
- `MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
168
- runtime dependency closure are collected in the repository
169
- [`NOTICE.md`](../../NOTICE.md).
91
+ `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
92
+ [`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
93
+ for third-party notices.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hydranium/glsp-client-theia",
3
- "version": "1.0.0-next.245",
3
+ "version": "1.0.0-next.247",
4
4
  "description": "Theia-coupled client primitives for GLSP heads built on @hydranium/glsp-server. Provides the action dispatcher, channel logger, and connection-handler bases that Theia-based adopters extend; companion of @hydranium/glsp-server.",
5
5
  "keywords": [
6
6
  "diagram",
@@ -70,10 +70,10 @@
70
70
  "@eclipse-glsp/client": "2.7.0",
71
71
  "@eclipse-glsp/server": "2.7.0",
72
72
  "@eclipse-glsp/theia-integration": "2.7.0",
73
- "@hydranium/client-theia": "1.0.0-next.245",
74
- "@hydranium/core": "1.0.0-next.245",
75
- "@hydranium/glsp-server": "1.0.0-next.245",
76
- "@hydranium/protocol": "1.0.0-next.245",
73
+ "@hydranium/client-theia": "1.0.0-next.247",
74
+ "@hydranium/core": "1.0.0-next.247",
75
+ "@hydranium/glsp-server": "1.0.0-next.247",
76
+ "@hydranium/protocol": "1.0.0-next.247",
77
77
  "@theia/core": "^1.70.0",
78
78
  "@theia/process": "^1.70.0",
79
79
  "@theia/workspace": "^1.70.0",
@@ -88,8 +88,8 @@
88
88
  "peerDependencies": {
89
89
  "@eclipse-glsp/client": "^2.6.0",
90
90
  "@eclipse-glsp/theia-integration": "^2.6.0",
91
- "@hydranium/client-theia": "1.0.0-next.245",
92
- "@hydranium/protocol": "1.0.0-next.245",
91
+ "@hydranium/client-theia": "1.0.0-next.247",
92
+ "@hydranium/protocol": "1.0.0-next.247",
93
93
  "@theia/core": "^1.70.0",
94
94
  "@theia/process": "^1.70.0",
95
95
  "@theia/workspace": "^1.70.0",