Support for a docked sheet

[HadrienGardeur]

This component will look almost exactly like the popover sheet described in #41, but rather than appearing on top of the content, it'll be displayed next to it, pushing things to the side in doing so.

If the affordance allows it, this component should also be resizable, allowing the user to control the width, as constrained by a minimum and maximum width.

[JayPanoz]

Question: what happens to Arrows when a sheet is docked?

Is it grouped with the iframe’s container and displayed next to it? Or is it its own separate element that is always displayed at the edge of the screen/window?

For instance:

1. Docked Toc | Arrow Left | iframe | Arrow Right
2. Arrow Left | Docked Toc | iframe | Arrow Right

Edit: Answer 2.

Basically we have docked left | arrow left | iframe | arrow right | docked right

[JayPanoz]

Detailing what has to be handled after the initial implementation on commit 33fc3d8d deployment – not using the alias to pinpoint the state at the time of writing.

• add aria labels to docking elements
• display based on preference (Sheets.dockedLeft + Sheets.dockedRight)
• make panel draggable, with preferences
• handle edge cases of dockable and sheet: Sheets.docked{Side} preferences since on smaller breakpoints, it makes sense panels are not dockable but fullscreen – and the sheet should therefore not display the docking options in that case
• clicking on the action icon should close the docked panel
• there’s a bug the first time you dock the panel – autoPagination doesn’t update as it should, which may either be a stale state, or a wrong clientWidth when constraining the container’s width
• there’s a rendering issue with the container’s width not being correct, with the panel being cut off
• add the logic for FXL – unlike reflow, the navigator’s container is not constrained at the moment, as it created issues with the FXLFramePoolManager’s resize handler that we didn’t need to address at that time, but we now do and it seems likely it will impact the ts-toolkit
• define focus and keyboard handling

[JayPanoz]

Some catching up cos this has been quite an epic.

The docking system is relying on React-Resizeable Panels for layout and resizeability, a DockedSheet component, and a useDocking hook to encapsulate the logic as much as possible. Actions themselves don’t care about docking at all, they’re merely passing props from the custom hook to a wrapper component returning the correct type of sheet/container, and to the Docker component responsible for displaying docking options to the user.

Anyways, there are a lot of preferences, which took some time to orchestrate, especially with user overrides on top of it.

• docking object:
  • displayOrder of docking actions (transient e.g. popover, start, end)
  • dock: boolean (enable/disable) or map of breakpoints to select which docking slots are enabled based on breakpoints;
  • defaultWidth: a default width for the Docked Sheets
  • collapse: collapsibility of docking actions
  • for each docking action, their visibility and shortcut, if any.
• for each action e.g. toc, settings, etc.:
  • dockedStart and dockedEnd as the type of sheet you’d like by default for specific breakpoints – can’t be a defaultSheet;
  • docked object:
    • dockable: if the action is dockable in both slots, in the left or right slot, or not dockable at all;
    • width: the initial width when docked
    • minWidth: the min width when docked
    • maxWidth: the max width when docked

Note a custom hook for docking panels takes care of resizability e.g. if you don’t set widths at all, it will fall back onto the docking.defaultWidth and infer the panel is not resizable.

The useDocking hook should cover these preferences, and discover conflicting/incompatible preferences, which is why it took that long an effort. It also prioritises user customisation over preferences when returning the type of sheet that should be displayed based on the current breakpoint.

There hasn’t been a strong attempt to hide this complexity in this initial implementation so I’m sure it could be improved and abstracted further down the line if someone wants to take a closer look at improving the docking system. But as far as I can tell, it already does a proper job at handling all corner cases.