open-index/open-npm huggingface dataset:
npm package: @matrix-widget-toolkit/react
Description: A simplified layer on top of @matrix-widget-toolkit/api to use it in a React based widget.
Author: Nordeck IT + Consulting GmbH
Latest version: 2.1.1

# `@matrix-widget-toolkit/react`

[![@matrix-widget-toolkit/react](https://img.shields.io/npm/v/@matrix-widget-toolkit/react)](https://www.npmjs.com/package/@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/) which internally uses this package to share functionality.

### Customizing Widget Registration

You can customise the Widget registration with a name and type. This will be used to show the widget name in the
`Extensions` page of Element Web:

```typescript
<WidgetApiProvider
  widgetApiPromise={widgetApiPromise}
  widgetRegistration={{
    name: 'Example Widget',
    type: 'com.example.clock',
    data: { title: 'Learn more…' },
  }}
>
```

### Checking for specific Widget Parameters

Widgets must be registered within the room state with a set of parameters that the hosting client will provide,
such as the `matrix_user_id`, `matrix_room_id` and others that are essential for the Widget to operate under
the correct context.

As new parameters have been introduced and exposed in the Widget API and hosting clients, by default they will
not be checked during registration and might not be available for the widget to use.

To check for specific parameters and require a re-registration of the widget if they are absent, you can create
the provider component with a list of required `WidgetParameter`'s:

```typescript
<WidgetApiProvider
  widgetApiPromise={widgetApiPromise}
  widgetRegistration={{
    name: 'Example Widget',
    type: 'com.example.clock',
    data: { title: 'Learn more…' },
    // Device ID must be available upon registration
    requiredParameters: [WidgetParameter.DeviceId],
  }}
>
```

### 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>;
```
npm package: @matrix-widget-toolkit/semantic-ui
Description: A customized semantic-ui theme that matches the style of the Element Matrix client
Author: Nordeck IT + Consulting GmbH
Latest version: 2.0.0
Deprecated: true

# `@matrix-widget-toolkit/semantic-ui`

[![@matrix-widget-toolkit/semantic-ui](https://img.shields.io/npm/v/@matrix-widget-toolkit/semantic-ui)](https://www.npmjs.com/package/@matrix-widget-toolkit/semantic-ui)

This package provides a Semantic UI theme that fits to the default Element theme.
See [`matrix-example-widget-semantic-ui`](../../matrix-example-widget-semantic-ui/) for some examples.

> **Warning** This package is deprecated. We are about to migrate all our packages to use Material UI in the future.

## Usage

This package should be used with a [CRACO](https://www.npmjs.com/package/@craco/craco) project.

Install it with:

```bash
yarn add @matrix-widget-toolkit/semantic-ui semantic-ui-react
yarn add --dev @semantic-ui-react/craco-less
```

Register the plugin in your `craco.config.js`:

```js
module.exports = {
  plugins: [
    {
      plugin: require('@matrix-widget-toolkit/semantic-ui/craco/buildSemanticUiThemePlugin'),
    },
  ],
};
```

Add the following to your `package.json` so `jest` finds the virtual modules that are used inside of the package:

```json
  "jest": {
    "moduleNameMapper": {
      "semantic-ui-less/semantic.less(.+)": "semantic-ui-less/semantic.less"
    }
  }
```

Now you can use it in your application:

```tsx
import {
  SemanticUiThemeProvider,
  SemanticUiWidgetApiProvider,
} from '@matrix-widget-toolkit/semantic-ui';
import { Button } from 'semantic-ui-react';

function App() {
  return (
    <SemanticUiThemeProvider>
      <SemanticUiWidgetApiProvider>
        <Button primary>A styled button</Button>
      </SemanticUiWidgetApiProvider>
    </SemanticUiThemeProvider>
  );
}

export default App;
```

## Customization

You can override the primary color by setting the `REACT_APP_PRIMARY_COLOR` environment variable to a custom color during build.

## Update Font Awesome icons

The Font Awesome version coming with Semantic UI is to old and is missing icons.
Therefore this theme includes a newer set of icons.
To update the icons, use the following steps:

1. Use [`create-fomantic-icons`](https://github.com/fomantic/create-fomantic-icons) to download the newest stable version of fontawesome and generate the files needed by Semantic UI. Run `yarn create fomantic-icons` to generate the required files.
2. Modify `fui-icons/ui/src/themes/default/elements/icon.variables` and remove the `#icons` references from SVG font imports.
npm package: @matrix-widget-toolkit/testing
Description: Testing support for @matrix-widget-toolkit/api.
Author: Nordeck IT + Consulting GmbH
Latest version: 4.0.1

# `@matrix-widget-toolkit/testing`

[![@matrix-widget-toolkit/testing](https://img.shields.io/npm/v/@matrix-widget-toolkit/testing)](https://www.npmjs.com/package/@matrix-widget-toolkit/testing)

Testing support for `@matrix-widget-toolkit/api`.

## Usage

When testing widgets that are using `@matrix-widget-toolkit/api` you quickly run
into the situation where you have to mock `WidgetApi`. While this can be done
using `vitest`, this can be a lot of repeated work and you might miss edge cases
that makes the mock behave differently than the original. The package provides
a `mockWidgetApi` helper to cover this case. The returned mock can be used to
emulate a Widget host like Element, so that the widget can interact with the
Matrix room, like sending and receiving events.

Install it with:

```bash
yarn add @matrix-widget-toolkit/testing
```

### Setup

It's recommended to use a fresh mock instance in every test. After each test,
make sure to stop the mock by calling `stop()` to free resources:

```typescript
import { MockedWidgetApi, mockWidgetApi } from '@matrix-widget-toolkit/testing';

let widgetApi: MockedWidgetApi;

afterEach(() => widgetApi.stop());

beforeEach(() => (widgetApi = mockWidgetApi()));
```

### Simple Event Mock

In test, you can use the mock to prepopulate the current Matrix room with
events:

```typescript
// Prepopulate the power levels event in the room:
widgetApi.mockSendStateEvent({
  type: 'm.room.power_levels',
  sender: '@user-id:example.com',
  content: {
    users: {
      '@my-user:example.com': 100,
    },
  },
  state_key: '',
  origin_server_ts: 0,
  event_id: '$event-id-0',
  room_id: '!room-id:example.com',
});

// You can receive it using any of the methods of the widget api:
const powerLevels = widgetApi.receiveSingleStateEvent('m.room.power_levels');
```

### Verifying Sending of Events

As the methods of the mock are using `vi.fn()`, you can verify all of them:

```typescript
// In your code, send an event:
widgetApi.sendStateEvent(
  'm.room.topic',
  { topic: 'A brief description' },
  { roomId: '!my-room' },
);

// Verify that the event was send in your test:
expect(widgetApi.sendStateEvent).toBeCalledWith(
  'm.room.topic',
  { topic: 'A brief description' },
  { roomId: '!my-room' },
);
```

### Overriding Behavior

As the methods of the mock are using `vi.fn()`, you can change their default
behavior by mocking them:

```typescript
// Returns true by default, override to return false:
widgetApi.hasCapabilities.mockReturnValue(false);
```