@matrix-widget-toolkit/react 2.0.4 → 2.0.5
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.
- package/README.md +41 -0
- package/build/cjs/index.cjs +18 -6
- package/build/esm/index.js +19 -7
- package/package.json +17 -14
package/README.md
CHANGED
|
@@ -17,6 +17,47 @@ yarn add @matrix-widget-toolkit/react
|
|
|
17
17
|
While this package contains a `<WidgetApiProvider>` you probably don't want to use this package most of the time.
|
|
18
18
|
Prefer using [`@matrix-widget-toolkit/mui`](../mui/) which internally uses this package to share functionality.
|
|
19
19
|
|
|
20
|
+
### Customizing Widget Registration
|
|
21
|
+
|
|
22
|
+
You can customise the Widget registration with a name and type. This will be used to show the widget name in the
|
|
23
|
+
`Extensions` page of Element Web:
|
|
24
|
+
|
|
25
|
+
```typescript
|
|
26
|
+
<WidgetApiProvider
|
|
27
|
+
widgetApiPromise={widgetApiPromise}
|
|
28
|
+
widgetRegistration={{
|
|
29
|
+
name: 'Example Widget',
|
|
30
|
+
type: 'com.example.clock',
|
|
31
|
+
data: { title: 'Learn more…' },
|
|
32
|
+
}}
|
|
33
|
+
>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Checking for specific Widget Parameters
|
|
37
|
+
|
|
38
|
+
Widgets must be registered within the room state with a set of parameters that the hosting client will provide,
|
|
39
|
+
such as the `matrix_user_id`, `matrix_room_id` and others that are essential for the Widget to operate under
|
|
40
|
+
the correct context.
|
|
41
|
+
|
|
42
|
+
As new parameters have been introduced and exposed in the Widget API and hosting clients, by default they will
|
|
43
|
+
not be checked during registration and might not be available for the widget to use.
|
|
44
|
+
|
|
45
|
+
To check for specific parameters and require a re-registration of the widget if they are absent, you can create
|
|
46
|
+
the provider component with a list of required `WidgetParameter`'s:
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
<WidgetApiProvider
|
|
50
|
+
widgetApiPromise={widgetApiPromise}
|
|
51
|
+
widgetRegistration={{
|
|
52
|
+
name: 'Example Widget',
|
|
53
|
+
type: 'com.example.clock',
|
|
54
|
+
data: { title: 'Learn more…' },
|
|
55
|
+
// Device ID must be available upon registration
|
|
56
|
+
requiredParameters: [WidgetParameter.DeviceId],
|
|
57
|
+
}}
|
|
58
|
+
>
|
|
59
|
+
```
|
|
60
|
+
|
|
20
61
|
### Acessing the Widget API
|
|
21
62
|
|
|
22
63
|
Once the Widget API is provided to React components, use the `useWidgetApi` hook to access it:
|
package/build/cjs/index.cjs
CHANGED
|
@@ -88,10 +88,11 @@ var __generator = (undefined && undefined.__generator) || function (thisArg, bod
|
|
|
88
88
|
*/
|
|
89
89
|
function WidgetApiProvider(_a) {
|
|
90
90
|
var _this = this;
|
|
91
|
+
var _b;
|
|
91
92
|
var children = _a.children, widgetApiPromise = _a.widgetApiPromise, widgetRegistration = _a.widgetRegistration, LoadingViewComponent = _a.loadingViewComponent, MobileClientErrorComponent = _a.mobileClientErrorComponent, OutsideClientErrorComponent = _a.outsideClientErrorComponent, ChildErrorComponent = _a.childErrorComponent, MissingCapabilitiesComponent = _a.missingCapabilitiesComponent, MissingParametersErrorComponent = _a.missingParametersErrorComponent;
|
|
92
93
|
var isOpenedByClient = react.useMemo(function () { return api.extractWidgetParameters(); }, []).isOpenedByClient;
|
|
93
|
-
var
|
|
94
|
-
var
|
|
94
|
+
var _c = react.useState(), hasInitalCapabilitiesGranted = _c[0], setInitialCapabilitiesGranted = _c[1];
|
|
95
|
+
var _d = reactUse.useAsyncFn(function (widgetApi) { return __awaiter(_this, void 0, void 0, function () {
|
|
95
96
|
return __generator(this, function (_b) {
|
|
96
97
|
switch (_b.label) {
|
|
97
98
|
case 0:
|
|
@@ -108,8 +109,8 @@ function WidgetApiProvider(_a) {
|
|
|
108
109
|
case 3: return [2 /*return*/];
|
|
109
110
|
}
|
|
110
111
|
});
|
|
111
|
-
}); }, []), rerequestInitialCapabilities =
|
|
112
|
-
var
|
|
112
|
+
}); }, []), rerequestInitialCapabilities = _d[1];
|
|
113
|
+
var _e = reactUse.useAsync(function () { return __awaiter(_this, void 0, void 0, function () {
|
|
113
114
|
var widgetApi;
|
|
114
115
|
return __generator(this, function (_a) {
|
|
115
116
|
switch (_a.label) {
|
|
@@ -120,7 +121,7 @@ function WidgetApiProvider(_a) {
|
|
|
120
121
|
return [2 /*return*/, widgetApi];
|
|
121
122
|
}
|
|
122
123
|
});
|
|
123
|
-
}); }, [widgetApiPromise]), widgetApi =
|
|
124
|
+
}); }, [widgetApiPromise]), widgetApi = _e.value, error = _e.error, loading = _e.loading;
|
|
124
125
|
if (loading) {
|
|
125
126
|
return jsxRuntime.jsx(LoadingViewComponent, {});
|
|
126
127
|
}
|
|
@@ -135,7 +136,18 @@ function WidgetApiProvider(_a) {
|
|
|
135
136
|
if (!hasInitalCapabilitiesGranted) {
|
|
136
137
|
return (jsxRuntime.jsx(MissingCapabilitiesComponent, { onRetry: function () { return rerequestInitialCapabilities(widgetApi); } }));
|
|
137
138
|
}
|
|
138
|
-
var hasParameters = api.
|
|
139
|
+
var hasParameters = api.hasWidgetParameters(widgetApi);
|
|
140
|
+
// Check for custom required parameters that are not part of the default setup
|
|
141
|
+
// and fail registration if they are missing.
|
|
142
|
+
var customRequiredParameters = (_b = widgetRegistration === null || widgetRegistration === void 0 ? void 0 : widgetRegistration.requiredParameters) !== null && _b !== void 0 ? _b : [];
|
|
143
|
+
if (customRequiredParameters.length > 0) {
|
|
144
|
+
hasParameters =
|
|
145
|
+
hasParameters &&
|
|
146
|
+
customRequiredParameters.every(function (param) {
|
|
147
|
+
return (param in widgetApi.widgetParameters &&
|
|
148
|
+
typeof widgetApi.widgetParameters[param] === 'string');
|
|
149
|
+
});
|
|
150
|
+
}
|
|
139
151
|
return (jsxRuntime.jsx(WidgetApiContext.Provider, { value: widgetApi, children: hasParameters ? (jsxRuntime.jsx(reactErrorBoundary.ErrorBoundary, { FallbackComponent: ChildErrorComponent, children: children })) : (jsxRuntime.jsx(MissingParametersErrorComponent, { widgetRegistration: widgetRegistration })) }));
|
|
140
152
|
}
|
|
141
153
|
|
package/build/esm/index.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { jsx, Fragment } from 'react/jsx-runtime';
|
|
2
2
|
import { useAsyncFn, useAsync, useAsyncRetry } from 'react-use';
|
|
3
3
|
import { createContext, useContext, useMemo, useState, useCallback } from 'react';
|
|
4
|
-
import { extractWidgetParameters,
|
|
4
|
+
import { extractWidgetParameters, hasWidgetParameters, extractWidgetApiParameters, parseWidgetId } from '@matrix-widget-toolkit/api';
|
|
5
5
|
import { ErrorBoundary } from 'react-error-boundary';
|
|
6
6
|
|
|
7
7
|
/*
|
|
@@ -86,10 +86,11 @@ var __generator = (undefined && undefined.__generator) || function (thisArg, bod
|
|
|
86
86
|
*/
|
|
87
87
|
function WidgetApiProvider(_a) {
|
|
88
88
|
var _this = this;
|
|
89
|
+
var _b;
|
|
89
90
|
var children = _a.children, widgetApiPromise = _a.widgetApiPromise, widgetRegistration = _a.widgetRegistration, LoadingViewComponent = _a.loadingViewComponent, MobileClientErrorComponent = _a.mobileClientErrorComponent, OutsideClientErrorComponent = _a.outsideClientErrorComponent, ChildErrorComponent = _a.childErrorComponent, MissingCapabilitiesComponent = _a.missingCapabilitiesComponent, MissingParametersErrorComponent = _a.missingParametersErrorComponent;
|
|
90
91
|
var isOpenedByClient = useMemo(function () { return extractWidgetParameters(); }, []).isOpenedByClient;
|
|
91
|
-
var
|
|
92
|
-
var
|
|
92
|
+
var _c = useState(), hasInitalCapabilitiesGranted = _c[0], setInitialCapabilitiesGranted = _c[1];
|
|
93
|
+
var _d = useAsyncFn(function (widgetApi) { return __awaiter(_this, void 0, void 0, function () {
|
|
93
94
|
return __generator(this, function (_b) {
|
|
94
95
|
switch (_b.label) {
|
|
95
96
|
case 0:
|
|
@@ -106,8 +107,8 @@ function WidgetApiProvider(_a) {
|
|
|
106
107
|
case 3: return [2 /*return*/];
|
|
107
108
|
}
|
|
108
109
|
});
|
|
109
|
-
}); }, []), rerequestInitialCapabilities =
|
|
110
|
-
var
|
|
110
|
+
}); }, []), rerequestInitialCapabilities = _d[1];
|
|
111
|
+
var _e = useAsync(function () { return __awaiter(_this, void 0, void 0, function () {
|
|
111
112
|
var widgetApi;
|
|
112
113
|
return __generator(this, function (_a) {
|
|
113
114
|
switch (_a.label) {
|
|
@@ -118,7 +119,7 @@ function WidgetApiProvider(_a) {
|
|
|
118
119
|
return [2 /*return*/, widgetApi];
|
|
119
120
|
}
|
|
120
121
|
});
|
|
121
|
-
}); }, [widgetApiPromise]), widgetApi =
|
|
122
|
+
}); }, [widgetApiPromise]), widgetApi = _e.value, error = _e.error, loading = _e.loading;
|
|
122
123
|
if (loading) {
|
|
123
124
|
return jsx(LoadingViewComponent, {});
|
|
124
125
|
}
|
|
@@ -133,7 +134,18 @@ function WidgetApiProvider(_a) {
|
|
|
133
134
|
if (!hasInitalCapabilitiesGranted) {
|
|
134
135
|
return (jsx(MissingCapabilitiesComponent, { onRetry: function () { return rerequestInitialCapabilities(widgetApi); } }));
|
|
135
136
|
}
|
|
136
|
-
var hasParameters =
|
|
137
|
+
var hasParameters = hasWidgetParameters(widgetApi);
|
|
138
|
+
// Check for custom required parameters that are not part of the default setup
|
|
139
|
+
// and fail registration if they are missing.
|
|
140
|
+
var customRequiredParameters = (_b = widgetRegistration === null || widgetRegistration === void 0 ? void 0 : widgetRegistration.requiredParameters) !== null && _b !== void 0 ? _b : [];
|
|
141
|
+
if (customRequiredParameters.length > 0) {
|
|
142
|
+
hasParameters =
|
|
143
|
+
hasParameters &&
|
|
144
|
+
customRequiredParameters.every(function (param) {
|
|
145
|
+
return (param in widgetApi.widgetParameters &&
|
|
146
|
+
typeof widgetApi.widgetParameters[param] === 'string');
|
|
147
|
+
});
|
|
148
|
+
}
|
|
137
149
|
return (jsx(WidgetApiContext.Provider, { value: widgetApi, children: hasParameters ? (jsx(ErrorBoundary, { FallbackComponent: ChildErrorComponent, children: children })) : (jsx(MissingParametersErrorComponent, { widgetRegistration: widgetRegistration })) }));
|
|
138
150
|
}
|
|
139
151
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@matrix-widget-toolkit/react",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.5",
|
|
4
4
|
"description": "A simplified layer on top of @matrix-widget-toolkit/api to use it in a React based widget.",
|
|
5
5
|
"author": "Nordeck IT + Consulting GmbH",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -23,14 +23,14 @@
|
|
|
23
23
|
"type": "module",
|
|
24
24
|
"devDependencies": {
|
|
25
25
|
"@testing-library/jest-dom": "6.6.3",
|
|
26
|
-
"@testing-library/react": "16.
|
|
27
|
-
"@testing-library/user-event": "14.
|
|
28
|
-
"@types/node": "22.
|
|
29
|
-
"@types/react": "18.3.
|
|
30
|
-
"@vitest/coverage-v8": "
|
|
31
|
-
"typescript": "5.7.
|
|
32
|
-
"vite": "
|
|
33
|
-
"vitest": "
|
|
26
|
+
"@testing-library/react": "16.2.0",
|
|
27
|
+
"@testing-library/user-event": "14.6.1",
|
|
28
|
+
"@types/node": "22.13.5",
|
|
29
|
+
"@types/react": "18.3.18",
|
|
30
|
+
"@vitest/coverage-v8": "3.0.7",
|
|
31
|
+
"typescript": "5.7.3",
|
|
32
|
+
"vite": "6.2.0",
|
|
33
|
+
"vitest": "3.0.7"
|
|
34
34
|
},
|
|
35
35
|
"scripts": {
|
|
36
36
|
"build": "tsc && rollup --config ../../rollup.config.mjs",
|
|
@@ -42,13 +42,16 @@
|
|
|
42
42
|
"postpack": "node ../../scripts/postpack.js",
|
|
43
43
|
"translate": "echo \"Nothing to translate\"",
|
|
44
44
|
"check-api-report": "api-extractor run --verbose",
|
|
45
|
-
"generate-api-report": "tsc && api-extractor run --verbose --local"
|
|
45
|
+
"generate-api-report": "tsc && api-extractor run --verbose --local",
|
|
46
|
+
"clean": "yarn run clean:build",
|
|
47
|
+
"clean:build": "rm -rf lib",
|
|
48
|
+
"clean:cache": "echo 'script not implemented package'"
|
|
46
49
|
},
|
|
47
50
|
"dependencies": {
|
|
48
|
-
"@matrix-widget-toolkit/api": "^4.
|
|
49
|
-
"matrix-widget-api": "1.
|
|
50
|
-
"react-error-boundary": "
|
|
51
|
-
"react-use": "17.
|
|
51
|
+
"@matrix-widget-toolkit/api": "^4.1.0",
|
|
52
|
+
"matrix-widget-api": "1.13.1",
|
|
53
|
+
"react-error-boundary": "5.0.0",
|
|
54
|
+
"react-use": "17.6.0"
|
|
52
55
|
},
|
|
53
56
|
"peerDependencies": {
|
|
54
57
|
"react": "18.3.1"
|