@matrix-widget-toolkit/react 2.0.4 → 2.0.6

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 (4) hide show
  1. package/README.md +41 -0
  2. package/build/cjs/index.cjs +18 -6
  3. package/build/esm/index.js +19 -7
  4. 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 _b = react.useState(), hasInitalCapabilitiesGranted = _b[0], setInitialCapabilitiesGranted = _b[1];
94
- var _c = reactUse.useAsyncFn(function (widgetApi) { return __awaiter(_this, void 0, void 0, function () {
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 = _c[1];
112
- var _d = reactUse.useAsync(function () { return __awaiter(_this, void 0, void 0, function () {
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 = _d.value, error = _d.error, loading = _d.loading;
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.hasRequiredWidgetParameters(widgetApi);
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, hasRequiredWidgetParameters, extractWidgetApiParameters, parseWidgetId } from '@matrix-widget-toolkit/api';
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 _b = useState(), hasInitalCapabilitiesGranted = _b[0], setInitialCapabilitiesGranted = _b[1];
92
- var _c = useAsyncFn(function (widgetApi) { return __awaiter(_this, void 0, void 0, function () {
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 = _c[1];
110
- var _d = useAsync(function () { return __awaiter(_this, void 0, void 0, function () {
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 = _d.value, error = _d.error, loading = _d.loading;
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 = hasRequiredWidgetParameters(widgetApi);
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.4",
3
+ "version": "2.0.6",
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.1.0",
27
- "@testing-library/user-event": "14.5.2",
28
- "@types/node": "22.10.1",
29
- "@types/react": "18.3.14",
30
- "@vitest/coverage-v8": "2.1.8",
31
- "typescript": "5.7.2",
32
- "vite": "5.4.11",
33
- "vitest": "2.1.8"
26
+ "@testing-library/react": "16.3.0",
27
+ "@testing-library/user-event": "14.6.1",
28
+ "@types/node": "22.15.30",
29
+ "@types/react": "18.3.23",
30
+ "@vitest/coverage-v8": "3.2.2",
31
+ "typescript": "5.8.3",
32
+ "vite": "6.3.5",
33
+ "vitest": "3.2.2"
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.0.0",
49
- "matrix-widget-api": "1.10.0",
50
- "react-error-boundary": "4.1.2",
51
- "react-use": "17.5.1"
51
+ "@matrix-widget-toolkit/api": "^4.2.0",
52
+ "matrix-widget-api": "1.13.1",
53
+ "react-error-boundary": "6.0.0",
54
+ "react-use": "17.6.0"
52
55
  },
53
56
  "peerDependencies": {
54
57
  "react": "18.3.1"