@matrix-widget-toolkit/react 1.0.1

package/README.md

@@ -0,0 +1,39 @@
+# `@matrix-widget-toolkit/react`
+
+This is package that provides a Widget API intergration for React apps.
+
+## Usage
+
+Install it with:
+
+```bash
+yarn add @matrix-widget-toolkit/react
+```
+
+### Providing the Widget API to React components
+
+While this package contains a `<WidgetApiProvider>` you probably don't want to use this package most of the time.
+Prefer using [`@matrix-widget-toolkit/mui`](../mui/) or [`@matrix-widget-toolkit/semantic-ui`](../semantic-ui/) which internally use this package to share functionality.
+
+### Acessing the Widget API
+
+Once the Widget API is provided to React components, use the `useWidgetApi` hook to access it:
+
+```typescript
+import { useWidgetApi } from '@matrix-widget-toolkit/react';
+
+const widgetApi = useWidgetApi();
+```
+
+### Mocking the Widget API
+
+Most of the time you will use `<MuiWidgetApiProvider>` to initialize and provide the `WidgetApi` to your react components.
+However, if you want to mock it in tests, you can use `<WidgetApiMockProvider>` to provide a mocked version:
+
+```tsx
+import { WidgetApiMockProvider } from '@matrix-widget-toolkit/react';
+
+<WidgetApiMockProvider value={widgetApi}>
+  /* Your child components */
+</WidgetApiMockProvider>;
+```

package/build/cjs/index.js

@@ -0,0 +1,236 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var reactUse = require('react-use');
+var react = require('react');
+var api = require('@matrix-widget-toolkit/api');
+var reactErrorBoundary = require('react-error-boundary');
+
+/*
+ * Copyright 2022 Nordeck IT + Consulting GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var WidgetApiContext = react.createContext(undefined);
+/**
+ * Hook for accessing the widget API.
+ *
+ * @remarks Can only be called inside a `WidgetApiProvider`
+ *          (or WidgetApiMockProvider in tests).
+ *
+ * @returns A fully initialized widget API.
+ */
+var useWidgetApi = function () {
+    var context = react.useContext(WidgetApiContext);
+    if (context === undefined) {
+        throw new Error('useWidgetApi must be used within a WidgetApiProvider (or WidgetApiMockProvider in tests)');
+    }
+    return context;
+};
+/**
+ * Provides a custom instance of the `WidgetApi` to the context.
+ *
+ * @remarks Should only be used in tests.
+ */
+var WidgetApiMockProvider = WidgetApiContext.Provider;
+
+var __assign$1 = (undefined && undefined.__assign) || function () {
+    __assign$1 = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign$1.apply(this, arguments);
+};
+var __awaiter = (undefined && undefined.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (undefined && undefined.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+/**
+ * Provides the `WidgetApi` in the React context once it's fully
+ * initialized without errors.
+ * Use {@link useWidgetApi} to access it.
+ * @param param0 - {@link WidgetApiProviderProps}
+ */
+function WidgetApiProvider(_a) {
+    var _this = this;
+    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;
+    var isOpenedByClient = react.useMemo(function () { return api.extractWidgetParameters(); }, []).isOpenedByClient;
+    var _b = react.useState(), hasInitalCapabilitiesGranted = _b[0], setInitialCapabilitiesGranted = _b[1];
+    var _c = reactUse.useAsyncFn(function (widgetApi) { return __awaiter(_this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _a.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, widgetApi.rerequestInitialCapabilities()];
+                case 1:
+                    _a.sent();
+                    setInitialCapabilitiesGranted(true);
+                    return [3 /*break*/, 3];
+                case 2:
+                    _a.sent();
+                    setInitialCapabilitiesGranted(false);
+                    return [3 /*break*/, 3];
+                case 3: return [2 /*return*/];
+            }
+        });
+    }); }, []), rerequestInitialCapabilities = _c[1];
+    var _d = reactUse.useAsync(function () { return __awaiter(_this, void 0, void 0, function () {
+        var widgetApi;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, widgetApiPromise];
+                case 1:
+                    widgetApi = _a.sent();
+                    setInitialCapabilitiesGranted(widgetApi.hasInitialCapabilities());
+                    return [2 /*return*/, widgetApi];
+            }
+        });
+    }); }, [widgetApiPromise]), widgetApi = _d.value, error = _d.error, loading = _d.loading;
+    if (loading) {
+        return jsxRuntime.jsx(LoadingViewComponent, {});
+    }
+    if (error || !widgetApi) {
+        if (isOpenedByClient) {
+            return jsxRuntime.jsx(MobileClientErrorComponent, {});
+        }
+        else {
+            return jsxRuntime.jsx(OutsideClientErrorComponent, {});
+        }
+    }
+    if (!hasInitalCapabilitiesGranted) {
+        return (jsxRuntime.jsx(MissingCapabilitiesComponent, { onRetry: function () { return rerequestInitialCapabilities(widgetApi); } }));
+    }
+    var hasParameters = api.hasRequiredWidgetParameters(widgetApi);
+    return (jsxRuntime.jsx(WidgetApiContext.Provider, __assign$1({ value: widgetApi }, { children: hasParameters ? (jsxRuntime.jsx(reactErrorBoundary.ErrorBoundary, __assign$1({ FallbackComponent: ChildErrorComponent }, { children: children }))) : (jsxRuntime.jsx(MissingParametersErrorComponent, { widgetRegistration: widgetRegistration })) })));
+}
+
+/**
+ * A guard that ask the user for capabilities and only shows the `children`
+ * if all capabilities were accepted.
+ * If capabilities are denined, a message and a button to retry is displayed
+ * instead.
+ * @param param0 - {@link CapabilitiesGuardProps}
+ */
+function CapabilitiesGuard(_a) {
+    var capabilities = _a.capabilities, children = _a.children, MissingCapabilitiesComponent = _a.missingCapabilitiesComponent, LoadingComponent = _a.loadingComponent;
+    var widgetApi = useWidgetApi();
+    var _b = reactUse.useAsyncRetry(function () { return widgetApi.requestCapabilities(capabilities); }, [widgetApi, capabilities]), loading = _b.loading, error = _b.error, requestCapabilities = _b.retry;
+    if (loading) {
+        return jsxRuntime.jsx(LoadingComponent, {});
+    }
+    if (error) {
+        return jsxRuntime.jsx(MissingCapabilitiesComponent, { onRetry: requestCapabilities });
+    }
+    return jsxRuntime.jsx(jsxRuntime.Fragment, { children: children });
+}
+
+var __assign = (undefined && undefined.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var ThemeSelectionContext = react.createContext(undefined);
+/**
+ * Hook for accessing the current theme selection.
+ * @returns The current theme selection.
+ */
+var useThemeSelection = function () {
+    var context = react.useContext(ThemeSelectionContext);
+    if (context === undefined) {
+        throw new Error('useThemeSelection must be used within a ThemeSelectionProvider');
+    }
+    return context;
+};
+/**
+ * Provides the current theme selection to child components.
+ * Use the {@link useThemeSelection} hook to access it.
+ * @param param0 - {@link ThemeSelectionProviderProps}
+ */
+function ThemeSelectionProvider(_a) {
+    var children = _a.children;
+    var _b = react.useState(function () {
+        var widgetId = '';
+        try {
+            (widgetId = api.extractWidgetApiParameters().widgetId);
+        }
+        catch (e) {
+            // ignore
+        }
+        var isModal = api.parseWidgetId(widgetId).isModal;
+        var theme = api.extractWidgetParameters().theme;
+        if (theme) {
+            return { theme: theme, isModal: isModal };
+        }
+        var prefersColorSchemeDark = window.matchMedia &&
+            window.matchMedia('(prefers-color-scheme: dark)').matches;
+        return { theme: prefersColorSchemeDark ? 'dark' : 'light', isModal: isModal };
+    }), _c = _b[0], theme = _c.theme, isModal = _c.isModal, setState = _b[1];
+    var setTheme = react.useCallback(function (theme) {
+        setState(function (old) { return (__assign(__assign({}, old), { theme: theme })); });
+    }, []);
+    var context = react.useMemo(function () { return ({
+        theme: theme,
+        isModal: isModal,
+        setTheme: setTheme,
+    }); }, [isModal, setTheme, theme]);
+    return (jsxRuntime.jsx(ThemeSelectionContext.Provider, __assign({ value: context }, { children: children })));
+}
+
+exports.CapabilitiesGuard = CapabilitiesGuard;
+exports.ThemeSelectionProvider = ThemeSelectionProvider;
+exports.WidgetApiMockProvider = WidgetApiMockProvider;
+exports.WidgetApiProvider = WidgetApiProvider;
+exports.useThemeSelection = useThemeSelection;
+exports.useWidgetApi = useWidgetApi;

package/build/esm/index.js

@@ -0,0 +1,229 @@
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { useAsyncFn, useAsync, useAsyncRetry } from 'react-use';
+import { createContext, useContext, useMemo, useState, useCallback } from 'react';
+import { extractWidgetParameters, hasRequiredWidgetParameters, extractWidgetApiParameters, parseWidgetId } from '@matrix-widget-toolkit/api';
+import { ErrorBoundary } from 'react-error-boundary';
+
+/*
+ * Copyright 2022 Nordeck IT + Consulting GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var WidgetApiContext = createContext(undefined);
+/**
+ * Hook for accessing the widget API.
+ *
+ * @remarks Can only be called inside a `WidgetApiProvider`
+ *          (or WidgetApiMockProvider in tests).
+ *
+ * @returns A fully initialized widget API.
+ */
+var useWidgetApi = function () {
+    var context = useContext(WidgetApiContext);
+    if (context === undefined) {
+        throw new Error('useWidgetApi must be used within a WidgetApiProvider (or WidgetApiMockProvider in tests)');
+    }
+    return context;
+};
+/**
+ * Provides a custom instance of the `WidgetApi` to the context.
+ *
+ * @remarks Should only be used in tests.
+ */
+var WidgetApiMockProvider = WidgetApiContext.Provider;
+
+var __assign$1 = (undefined && undefined.__assign) || function () {
+    __assign$1 = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign$1.apply(this, arguments);
+};
+var __awaiter = (undefined && undefined.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (undefined && undefined.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+/**
+ * Provides the `WidgetApi` in the React context once it's fully
+ * initialized without errors.
+ * Use {@link useWidgetApi} to access it.
+ * @param param0 - {@link WidgetApiProviderProps}
+ */
+function WidgetApiProvider(_a) {
+    var _this = this;
+    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;
+    var isOpenedByClient = useMemo(function () { return extractWidgetParameters(); }, []).isOpenedByClient;
+    var _b = useState(), hasInitalCapabilitiesGranted = _b[0], setInitialCapabilitiesGranted = _b[1];
+    var _c = useAsyncFn(function (widgetApi) { return __awaiter(_this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _a.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, widgetApi.rerequestInitialCapabilities()];
+                case 1:
+                    _a.sent();
+                    setInitialCapabilitiesGranted(true);
+                    return [3 /*break*/, 3];
+                case 2:
+                    _a.sent();
+                    setInitialCapabilitiesGranted(false);
+                    return [3 /*break*/, 3];
+                case 3: return [2 /*return*/];
+            }
+        });
+    }); }, []), rerequestInitialCapabilities = _c[1];
+    var _d = useAsync(function () { return __awaiter(_this, void 0, void 0, function () {
+        var widgetApi;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, widgetApiPromise];
+                case 1:
+                    widgetApi = _a.sent();
+                    setInitialCapabilitiesGranted(widgetApi.hasInitialCapabilities());
+                    return [2 /*return*/, widgetApi];
+            }
+        });
+    }); }, [widgetApiPromise]), widgetApi = _d.value, error = _d.error, loading = _d.loading;
+    if (loading) {
+        return jsx(LoadingViewComponent, {});
+    }
+    if (error || !widgetApi) {
+        if (isOpenedByClient) {
+            return jsx(MobileClientErrorComponent, {});
+        }
+        else {
+            return jsx(OutsideClientErrorComponent, {});
+        }
+    }
+    if (!hasInitalCapabilitiesGranted) {
+        return (jsx(MissingCapabilitiesComponent, { onRetry: function () { return rerequestInitialCapabilities(widgetApi); } }));
+    }
+    var hasParameters = hasRequiredWidgetParameters(widgetApi);
+    return (jsx(WidgetApiContext.Provider, __assign$1({ value: widgetApi }, { children: hasParameters ? (jsx(ErrorBoundary, __assign$1({ FallbackComponent: ChildErrorComponent }, { children: children }))) : (jsx(MissingParametersErrorComponent, { widgetRegistration: widgetRegistration })) })));
+}
+
+/**
+ * A guard that ask the user for capabilities and only shows the `children`
+ * if all capabilities were accepted.
+ * If capabilities are denined, a message and a button to retry is displayed
+ * instead.
+ * @param param0 - {@link CapabilitiesGuardProps}
+ */
+function CapabilitiesGuard(_a) {
+    var capabilities = _a.capabilities, children = _a.children, MissingCapabilitiesComponent = _a.missingCapabilitiesComponent, LoadingComponent = _a.loadingComponent;
+    var widgetApi = useWidgetApi();
+    var _b = useAsyncRetry(function () { return widgetApi.requestCapabilities(capabilities); }, [widgetApi, capabilities]), loading = _b.loading, error = _b.error, requestCapabilities = _b.retry;
+    if (loading) {
+        return jsx(LoadingComponent, {});
+    }
+    if (error) {
+        return jsx(MissingCapabilitiesComponent, { onRetry: requestCapabilities });
+    }
+    return jsx(Fragment, { children: children });
+}
+
+var __assign = (undefined && undefined.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var ThemeSelectionContext = createContext(undefined);
+/**
+ * Hook for accessing the current theme selection.
+ * @returns The current theme selection.
+ */
+var useThemeSelection = function () {
+    var context = useContext(ThemeSelectionContext);
+    if (context === undefined) {
+        throw new Error('useThemeSelection must be used within a ThemeSelectionProvider');
+    }
+    return context;
+};
+/**
+ * Provides the current theme selection to child components.
+ * Use the {@link useThemeSelection} hook to access it.
+ * @param param0 - {@link ThemeSelectionProviderProps}
+ */
+function ThemeSelectionProvider(_a) {
+    var children = _a.children;
+    var _b = useState(function () {
+        var widgetId = '';
+        try {
+            (widgetId = extractWidgetApiParameters().widgetId);
+        }
+        catch (e) {
+            // ignore
+        }
+        var isModal = parseWidgetId(widgetId).isModal;
+        var theme = extractWidgetParameters().theme;
+        if (theme) {
+            return { theme: theme, isModal: isModal };
+        }
+        var prefersColorSchemeDark = window.matchMedia &&
+            window.matchMedia('(prefers-color-scheme: dark)').matches;
+        return { theme: prefersColorSchemeDark ? 'dark' : 'light', isModal: isModal };
+    }), _c = _b[0], theme = _c.theme, isModal = _c.isModal, setState = _b[1];
+    var setTheme = useCallback(function (theme) {
+        setState(function (old) { return (__assign(__assign({}, old), { theme: theme })); });
+    }, []);
+    var context = useMemo(function () { return ({
+        theme: theme,
+        isModal: isModal,
+        setTheme: setTheme,
+    }); }, [isModal, setTheme, theme]);
+    return (jsx(ThemeSelectionContext.Provider, __assign({ value: context }, { children: children })));
+}
+
+export { CapabilitiesGuard, ThemeSelectionProvider, WidgetApiMockProvider, WidgetApiProvider, useThemeSelection, useWidgetApi };

package/build/index.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @packageDocumentation This is package that provides a Widget API
+ *                       intergration for React apps.
+ */
+
+/// <reference types="react" />
+
+import { Capability } from 'matrix-widget-api';
+import { ComponentType } from 'react';
+import { DispatchWithoutAction } from 'react';
+import { FallbackProps } from 'react-error-boundary';
+import { PropsWithChildren } from 'react';
+import { Provider } from 'react';
+import { ReactElement } from 'react';
+import { WidgetApi } from '@matrix-widget-toolkit/api';
+import { WidgetEventCapability } from 'matrix-widget-api';
+import { WidgetRegistration } from '@matrix-widget-toolkit/api';
+
+/**
+ * A guard that ask the user for capabilities and only shows the `children`
+ * if all capabilities were accepted.
+ * If capabilities are denined, a message and a button to retry is displayed
+ * instead.
+ * @param param0 - {@link CapabilitiesGuardProps}
+ */
+export declare function CapabilitiesGuard({ capabilities, children, missingCapabilitiesComponent: MissingCapabilitiesComponent, loadingComponent: LoadingComponent, }: CapabilitiesGuardProps): ReactElement;
+
+/**
+ * Props for the {@link CapabilitiesGuard} component.
+ */
+export declare type CapabilitiesGuardProps = PropsWithChildren<{
+    /**
+     * Required capabilities to display the `children`.
+     */
+    capabilities: Array<WidgetEventCapability | Capability>;
+    /**
+     * Component to display if the required capabilities are missing. The
+     * `onRetry` callback can be used to re-request them from the user.
+     */
+    missingCapabilitiesComponent: ComponentType<{
+        onRetry: DispatchWithoutAction;
+    }>;
+    /**
+     * Component to display while the capabilities are evaluated or requested from
+     * the user.
+     */
+    loadingComponent: ComponentType;
+}>;
+
+/**
+ * Themes with different color schemes, either `light` or `dark`.
+ */
+export declare type Theme = 'light' | 'dark' | string;
+
+/**
+ * Return value of the {@link useThemeSelection} hook.
+ */
+export declare type ThemeSelectionContextType = {
+    /**
+     * The current color scheme.
+     */
+    theme: Theme;
+    /**
+     * Whether the widget is displayed in a modal.
+     *
+     * @remarks Modals have different background colors which the theme needs to
+     * take into account.
+     */
+    isModal: boolean;
+    /**
+     * Select the current color scheme.
+     *
+     * @param theme - The new color scheme.
+     */
+    setTheme: (theme: Theme) => void;
+};
+
+/**
+ * Provides the current theme selection to child components.
+ * Use the {@link useThemeSelection} hook to access it.
+ * @param param0 - {@link ThemeSelectionProviderProps}
+ */
+export declare function ThemeSelectionProvider({ children, }: ThemeSelectionProviderProps): ReactElement;
+
+/**
+ * Props for the {@link ThemeSelectionProvider} component.
+ */
+export declare type ThemeSelectionProviderProps = PropsWithChildren<{}>;
+
+/**
+ * Hook for accessing the current theme selection.
+ * @returns The current theme selection.
+ */
+export declare const useThemeSelection: () => ThemeSelectionContextType;
+
+/**
+ * Hook for accessing the widget API.
+ *
+ * @remarks Can only be called inside a `WidgetApiProvider`
+ *          (or WidgetApiMockProvider in tests).
+ *
+ * @returns A fully initialized widget API.
+ */
+export declare const useWidgetApi: () => WidgetApi;
+
+/**
+ * Provides a custom instance of the `WidgetApi` to the context.
+ *
+ * @remarks Should only be used in tests.
+ */
+export declare const WidgetApiMockProvider: Provider<WidgetApi | undefined>;
+
+/**
+ * Provides the `WidgetApi` in the React context once it's fully
+ * initialized without errors.
+ * Use {@link useWidgetApi} to access it.
+ * @param param0 - {@link WidgetApiProviderProps}
+ */
+export declare function WidgetApiProvider({ children, widgetApiPromise, widgetRegistration, loadingViewComponent: LoadingViewComponent, mobileClientErrorComponent: MobileClientErrorComponent, outsideClientErrorComponent: OutsideClientErrorComponent, childErrorComponent: ChildErrorComponent, missingCapabilitiesComponent: MissingCapabilitiesComponent, missingParametersErrorComponent: MissingParametersErrorComponent, }: WidgetApiProviderProps): ReactElement;
+
+/**
+ * Props for the {@link (WidgetApiProvider:function)} component.
+ */
+export declare type WidgetApiProviderProps = PropsWithChildren<{
+    /**
+     * Configuration to set during Widget registration.
+     */
+    widgetRegistration?: WidgetRegistration;
+    /**
+     * Result from a call to `WidgetApiImpl.create`.
+     */
+    widgetApiPromise: Promise<WidgetApi>;
+    /**
+     * Component to display while the widget API communication is established or
+     * while capabilities are evaluated or requested from the user.
+     */
+    loadingViewComponent: ComponentType;
+    /**
+     * Component to display if the widget is opened in an unsupported mobile
+     * client.
+     */
+    mobileClientErrorComponent: ComponentType;
+    /**
+     * Component to display if the widget is opened outside a Matrix client.
+     */
+    outsideClientErrorComponent: ComponentType;
+    /**
+     * Component to display when a child component fails to render.
+     */
+    childErrorComponent: ComponentType<FallbackProps>;
+    /**
+     * Component to display if the required capabilities are missing. The
+     * `onRetry` callback can be used to re-request them from the user.
+     */
+    missingCapabilitiesComponent: ComponentType<{
+        onRetry: DispatchWithoutAction;
+    }>;
+    /**
+     * Component to display when the widget is not properly configured in the
+     * room. Takes the expected `widgetRegistration` as a parameter.
+     */
+    missingParametersErrorComponent: ComponentType<{
+        widgetRegistration?: WidgetRegistration;
+    }>;
+}>;
+
+export { }

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@matrix-widget-toolkit/react",
+  "version": "1.0.1",
+  "description": "A simplified layer on top of @matrix-widget-toolkit/api to use it in a React based widget.",
+  "author": "Nordeck IT + Consulting GmbH",
+  "license": "Apache-2.0",
+  "source": "./src/index.ts",
+  "module": "./build/esm/index.js",
+  "types": "./build/index.d.ts",
+  "devDependencies": {
+    "@craco/craco": "^6.4.5",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^12.1.5",
+    "@testing-library/react-hooks": "^8.0.0",
+    "@testing-library/user-event": "^14.4.3",
+    "@types/jest": "^27.5.2",
+    "@types/node": "^16.11.64",
+    "@types/react": "^17.0.45",
+    "react-scripts": "5.0.1",
+    "typescript": "^4.8.4"
+  },
+  "scripts": {
+    "build": "tsc && rollup --config ../../rollup.config.mjs",
+    "tsc": "tsc",
+    "lint": "eslint .",
+    "test": "jest --watch",
+    "depcheck": "depcheck --ignores=@types/jest,@types/node --ignore-dirs=lib,build",
+    "prepack": "node ../../scripts/prepack.js",
+    "postpack": "node ../../scripts/postpack.js",
+    "translate": "echo \"Nothing to translate\"",
+    "check-api-report": "api-extractor run --verbose",
+    "generate-api-report": "tsc && api-extractor run --verbose --local"
+  },
+  "dependencies": {
+    "@matrix-widget-toolkit/api": "^1.0.1",
+    "matrix-widget-api": "^1.1.1",
+    "react": "^17.0.2",
+    "react-error-boundary": "^3.1.4",
+    "react-use": "^17.3.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nordeck/matrix-widget-toolkit.git",
+    "directory": "packages/react"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "matrix",
+    "widget",
+    "matrix-widget-api"
+  ],
+  "main": "./build/cjs/index.js"
+}