# Widget layout support

Rooms can have a default widget layout to auto-pin certain widgets, make the container different
sizes, etc. These are defined through the `io.element.widgets.layout` state event (empty state key).

Full example content:
```json5
{
  "widgets": {
    "first-widget-id": {
      "container": "top",
      "index": 0,
      "width": 60,
      "height": 40
    },
    "second-widget-id": {
      "container": "right"
    }
  }
}
```

As shown, there are two containers possible for widgets. These containers have different behaviour
and interpret the other options differently. 

## `top` container

This is the "App Drawer" or any pinned widgets in a room. This is by far the most versatile container
though does introduce potential usability issues upon members of the room (widgets take up space and
therefore fewer messages can be shown).

The `index` for a widget determines which order the widgets show up in from left to right. Widgets
without an `index` will show up as the rightmost widgets. Tiebreaks (same `index` or multiple defined
without an `index`) are resolved by comparing widget IDs. A maximum of 3 widgets can be in the top
container - any which exceed this will be ignored. Smaller numbers represent leftmost widgets.

The `width` is relative width within the container in percentage points. This will be clamped to a
range of 0-100 (inclusive). The rightmost widget will have its percentage adjusted to fill the 
container appropriately, shrinking and growing if required. For example, if three widgets are in the
top container at 40% width each then the 3rd widget will be shrunk to 20% because 120% > 100%.
Similarly, if all three widgets were set to 10% width each then the 3rd widget would grow to be 80%.

Note that the client may impose minimum widths on the widgets, such as a 10% minimum to avoid pinning
hidden widgets. In general, widgets defined in the 30-70% range each will be free of these restrictions.

The `height` is not in fact applied per-widget but is recorded per-widget for potential future 
capabilities in future containers. The top container will take the tallest `height` and use that for
the height of the whole container, and thus all widgets in that container. The `height` is relative
to the container, like with `width`, meaning that 100% will consume as much space as the client is
willing to sacrifice to the widget container. Like with `width`, the client may impose minimums to avoid
the container being uselessly small. Heights in the 30-100% range are generally acceptable. The height
is also clamped to be within 0-100, inclusive.

## `right` container

This is the default container and has no special configuration. Widgets which overflow from the top
container will be put in this container instead. Putting a widget in the right container does not
automatically show it - it only mentions that widgets should not be in another container.

The behaviour of this container may change in the future.