@matrix-widget-toolkit/react 2.0.3 → 2.0.4

package/build/cjs/components/CapabilitiesGuard/CapabilitiesGuard.d.cts

@@ -0,0 +1,31 @@
+import { Capability, WidgetEventCapability } from 'matrix-widget-api';
+import { ComponentType, DispatchWithoutAction, PropsWithChildren, ReactElement } from 'react';
+/**
+ * Props for the {@link CapabilitiesGuard} component.
+ */
+export 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;
+}>;
+/**
+ * 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;

package/build/cjs/components/CapabilitiesGuard/CapabilitiesGuard.test.d.cts

@@ -0,0 +1 @@
+export {};

package/build/cjs/components/CapabilitiesGuard/index.d.cts

@@ -0,0 +1,2 @@
+export { CapabilitiesGuard } from './CapabilitiesGuard';
+export type { CapabilitiesGuardProps } from './CapabilitiesGuard';

package/build/cjs/components/ThemeSelectionProvider/ThemeSelectionProvider.d.cts

@@ -0,0 +1,43 @@
+import { PropsWithChildren, ReactElement } from 'react';
+/**
+ * Themes with different color schemes, either `light` or `dark`.
+ */
+export type Theme = 'light' | 'dark' | string;
+/**
+ * Return value of the {@link useThemeSelection} hook.
+ */
+export 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;
+};
+export declare const ThemeSelectionContext: import("react").Context<ThemeSelectionContextType | undefined>;
+/**
+ * Hook for accessing the current theme selection.
+ * @returns The current theme selection.
+ */
+export declare const useThemeSelection: () => ThemeSelectionContextType;
+/**
+ * Props for the {@link ThemeSelectionProvider} component.
+ */
+export type ThemeSelectionProviderProps = PropsWithChildren;
+/**
+ * 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;

package/build/cjs/components/ThemeSelectionProvider/ThemeSelectionProvider.test.d.cts

@@ -0,0 +1 @@
+export {};

package/build/cjs/components/ThemeSelectionProvider/index.d.cts

@@ -0,0 +1,2 @@
+export { ThemeSelectionProvider, useThemeSelection, } from './ThemeSelectionProvider';
+export type { Theme, ThemeSelectionContextType, ThemeSelectionProviderProps, } from './ThemeSelectionProvider';

package/build/cjs/components/WidgetApiProvider/WidgetApiProvider.d.cts

@@ -0,0 +1,55 @@
+import { WidgetApi, WidgetRegistration } from '@matrix-widget-toolkit/api';
+import { ComponentType, DispatchWithoutAction, PropsWithChildren, ReactElement } from 'react';
+import { FallbackProps } from 'react-error-boundary';
+/**
+ * Props for the {@link (WidgetApiProvider:function)} component.
+ */
+export 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;
+    }>;
+}>;
+/**
+ * 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;

package/build/cjs/components/WidgetApiProvider/WidgetApiProvider.test.d.cts

@@ -0,0 +1 @@
+export {};

package/build/cjs/components/WidgetApiProvider/context.d.cts

@@ -0,0 +1,17 @@
+import { WidgetApi } from '@matrix-widget-toolkit/api';
+export declare const WidgetApiContext: import("react").Context<WidgetApi | 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.
+ */
+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: import("react").Provider<WidgetApi | undefined>;

package/build/cjs/components/WidgetApiProvider/index.d.cts

@@ -0,0 +1,3 @@
+export { WidgetApiMockProvider, useWidgetApi } from './context';
+export { WidgetApiProvider } from './WidgetApiProvider';
+export type { WidgetApiProviderProps } from './WidgetApiProvider';

package/build/cjs/components/index.d.cts

@@ -0,0 +1,3 @@
+export * from './CapabilitiesGuard';
+export * from './ThemeSelectionProvider';
+export * from './WidgetApiProvider';

package/build/cjs/index.d.cts

@@ -0,0 +1,5 @@
+/**
+ * @packageDocumentation This is package that provides a Widget API
+ *                       intergration for React apps.
+ */
+export * from './components';

package/build/cjs/setupTests.d.cts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/build/esm/components/CapabilitiesGuard/CapabilitiesGuard.d.ts

@@ -0,0 +1,31 @@
+import { Capability, WidgetEventCapability } from 'matrix-widget-api';
+import { ComponentType, DispatchWithoutAction, PropsWithChildren, ReactElement } from 'react';
+/**
+ * Props for the {@link CapabilitiesGuard} component.
+ */
+export 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;
+}>;
+/**
+ * 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;

package/build/esm/components/CapabilitiesGuard/CapabilitiesGuard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/components/CapabilitiesGuard/index.d.ts

@@ -0,0 +1,2 @@
+export { CapabilitiesGuard } from './CapabilitiesGuard';
+export type { CapabilitiesGuardProps } from './CapabilitiesGuard';

package/build/esm/components/ThemeSelectionProvider/ThemeSelectionProvider.d.ts

@@ -0,0 +1,43 @@
+import { PropsWithChildren, ReactElement } from 'react';
+/**
+ * Themes with different color schemes, either `light` or `dark`.
+ */
+export type Theme = 'light' | 'dark' | string;
+/**
+ * Return value of the {@link useThemeSelection} hook.
+ */
+export 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;
+};
+export declare const ThemeSelectionContext: import("react").Context<ThemeSelectionContextType | undefined>;
+/**
+ * Hook for accessing the current theme selection.
+ * @returns The current theme selection.
+ */
+export declare const useThemeSelection: () => ThemeSelectionContextType;
+/**
+ * Props for the {@link ThemeSelectionProvider} component.
+ */
+export type ThemeSelectionProviderProps = PropsWithChildren;
+/**
+ * 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;

package/build/esm/components/ThemeSelectionProvider/ThemeSelectionProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/components/ThemeSelectionProvider/index.d.ts

@@ -0,0 +1,2 @@
+export { ThemeSelectionProvider, useThemeSelection, } from './ThemeSelectionProvider';
+export type { Theme, ThemeSelectionContextType, ThemeSelectionProviderProps, } from './ThemeSelectionProvider';

package/build/esm/components/WidgetApiProvider/WidgetApiProvider.d.ts

@@ -0,0 +1,55 @@
+import { WidgetApi, WidgetRegistration } from '@matrix-widget-toolkit/api';
+import { ComponentType, DispatchWithoutAction, PropsWithChildren, ReactElement } from 'react';
+import { FallbackProps } from 'react-error-boundary';
+/**
+ * Props for the {@link (WidgetApiProvider:function)} component.
+ */
+export 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;
+    }>;
+}>;
+/**
+ * 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;

package/build/esm/components/WidgetApiProvider/WidgetApiProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/esm/components/WidgetApiProvider/context.d.ts

@@ -0,0 +1,17 @@
+import { WidgetApi } from '@matrix-widget-toolkit/api';
+export declare const WidgetApiContext: import("react").Context<WidgetApi | 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.
+ */
+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: import("react").Provider<WidgetApi | undefined>;

package/build/esm/components/WidgetApiProvider/index.d.ts

@@ -0,0 +1,3 @@
+export { WidgetApiMockProvider, useWidgetApi } from './context';
+export { WidgetApiProvider } from './WidgetApiProvider';
+export type { WidgetApiProviderProps } from './WidgetApiProvider';

package/build/esm/components/index.d.ts

@@ -0,0 +1,3 @@
+export * from './CapabilitiesGuard';
+export * from './ThemeSelectionProvider';
+export * from './WidgetApiProvider';

package/build/esm/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @packageDocumentation This is package that provides a Widget API
+ *                       intergration for React apps.
+ */
+export * from './components';

package/build/esm/setupTests.d.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/package.json

@@ -1,27 +1,36 @@
 {
   "name": "@matrix-widget-toolkit/react",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "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",
-  "types": "./build/index.d.ts",
+  "types": "./build/esm/index.d.ts",
   "exports": {
-    "import": "./build/esm/index.js",
-    "require": "./build/cjs/index.js",
-    "types": "./build/index.d.ts"
+    ".": {
+      "module": "./build/esm/index.js",
+      "import": {
+        "types": "./build/esm/index.d.ts",
+        "default": "./build/esm/index.js"
+      },
+      "require": {
+        "types": "./build/cjs/index.d.cts",
+        "default": "./build/cjs/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "type": "module",
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.5.0",
-    "@testing-library/react": "^16.0.1",
-    "@testing-library/user-event": "^14.5.2",
-    "@types/node": "^22.7.5",
-    "@types/react": "^18.2.74",
-    "@vitest/coverage-v8": "^2.1.3",
-    "typescript": "^5.6.3",
-    "vite": "^5.4.8",
-    "vitest": "^2.1.3"
+    "@testing-library/jest-dom": "6.6.3",
+    "@testing-library/react": "16.1.0",
+    "@testing-library/user-event": "14.5.2",
+    "@types/node": "22.10.1",
+    "@types/react": "18.3.14",
+    "@vitest/coverage-v8": "2.1.8",
+    "typescript": "5.7.2",
+    "vite": "5.4.11",
+    "vitest": "2.1.8"
   },
   "scripts": {
     "build": "tsc && rollup --config ../../rollup.config.mjs",
@@ -36,11 +45,13 @@
     "generate-api-report": "tsc && api-extractor run --verbose --local"
   },
   "dependencies": {
-    "@matrix-widget-toolkit/api": "^3.4.2",
-    "matrix-widget-api": "^1.9.0",
-    "react": "^18.2.0",
-    "react-error-boundary": "^3.1.4",
-    "react-use": "^17.5.1"
+    "@matrix-widget-toolkit/api": "^4.0.0",
+    "matrix-widget-api": "1.10.0",
+    "react-error-boundary": "4.1.2",
+    "react-use": "17.5.1"
+  },
+  "peerDependencies": {
+    "react": "18.3.1"
   },
   "repository": {
     "type": "git",
@@ -56,5 +67,5 @@
     "matrix-widget-api"
   ],
   "module": "./build/esm/index.js",
-  "main": "./build/cjs/index.js"
+  "main": "./build/cjs/index.cjs"
 }