# matrix-widget

> Matrix (client) widget(s) are not yet part of the matrix
> specification (experiemental in matrix and here).

To test the matrix-widget, try adding the example HTML page as a
"custom widget" in a matrix client that supports them (Element web
client), with the command:

```
/addwidget https://sctlib.gitlab.io/matrix-widgets/?widgetId=$matrix_widget_id&userId=$matrix_user_id&roomId=$matrix_room_id&displayName=$matrix_display_name&avatarUrl=$matrix_avatar_url
```

> Note: somehow the search params are only needed if the widget does
> not requests capabilities via the client widget api (client GUI prompt).

> Note: adding this URL through the GUI will not trigger element's
> capabilitie authorization requested by the widget; only with the
> `/addwidget <widget_URL_with_query_params>` command. It also won't
> prefill URLSearchParams on the widget iframe src generated by the
> client when embedding it.

# Usage

Insert the `<matrix-widget/>` element in the DOM.

```
<matrix-widget></matrix-widget>
```

If the widget should request "capabilities" to the matrix client in
which it is embeded, use te attributes `capabilities` with a comma `,`
separated list of capabilites that the widget will request to the
client it is embeded into.

```
capabilities="org.matrix.msc2762.send.event:m.room.message,org.matrix.msc2762.read.event:m.room.message,org.matrix.msc2762.send.event:org.libli.room.message.track,m.always_on_screen,m.capability.request_data,m.capability.request_messages"
```

Use the `capabilites-search-param` attribute, to specify from which
URL search param of `window.location` (default if left empty)

```
capabilites-search-param="capabilities"
```

# Capabilites

> See the SPEC and MSC2762 for why we use the `org.matrix.msc2762`
> flag namespace instead of `m.` namespace of the events.

A capability has the shape `<action>:<event_type>` where `action` is
the one requested by the widget as capability for a certain
`event_type` in the room.

> State events can have their capabilities requested against specific
> state keys as well, helping the client limit its exposure to the
> room's history. This is done by appending a # and the state key the
> capability should be against. For example,
> m.send.state_event:m.room.name# will represent an m.room.name state
> event with an empty state key whereas
> m.send.state_event:m.room.name#test will be an m.room.name state
> event still, though with test as the state key. Clients should only
> split on the first #, so m.room.name##test becomes an event type of
> m.room.name and state key of #test.

> m.room.message is the only non-state event which also makes use of
> this # system, though targeting the msgtype of a m.room.message
> event instead. All the same rules apply as they do to state events,
> except instead to msgtype. This ensures that widgets cannot
> interfere with encryption verification. It is expected that most
> widgets looking to use this functionality will request the
> following:

```
m.send.event:m.room.message#m.notice
m.send.event:m.room.message#m.text
m.send.event:m.room.message#m.emote
```


# Development

If we want to be able to add your local project, local running
server, as a widget to a room, we'll have to use `ngrok` (https://ngrok.com).
That way, we don't have to publish our changes to a remote server, to be testing our widget in a matrix room.

```bash
// if our mwc local dev server is on port 5173
npm run dev
# outputs: serving at http://localhost:5173
ngrok http 5173
# visit localhost:4040, to get the public URL for our local server
# example: https://1234-abcd.ngrok-free.app (url to use in the addwidget client command)
```


## Widget ID

Somehow in element, the placeholder replacement do not seem to work
after the capabilities have been requested/accepted; also does not
work when the widget is added via the GUI (and not the `/addwidget`
chat command).

That is why right now we renamed our own URLSearchParams to `widgetId`
instead of `matrix_widget_id`. This way (even with wrong placeholders,
since the matrix client replace the value) our widget api always has
`api.getUrlConfig` resulting with `widgetId` filled (by the client).

MSC proposal: https://github.com/matrix-org/matrix-spec-proposals/blob/travis/msc/widget-id/proposals/2774-widget-id.md

> does not seem to work in element, when it does we should rename our
> own search params, to be like the placeholders
> `matrix_widget_id=$matrix_widget_id`

## Re-exchange capabilities

This is needed for the `matrix-send-events` when the `event_type` changes.

- https://github.com/matrix-org/matrix-spec-proposals/blob/travis/msc/widgets-re-exchange-caps/proposals/2974-widgets-re-exchange-capabilities.md