hypothesis / hypothesis/product-backlog
Configurable sidebar UI placement
- Dominant language
- No language data
- Stars
- 122
- Forks
- 7
- PR merge metrics
- No merged PRs in 30d
Description
This is a feature request proposing a new optional feature that would allow the client's sidebar user interface to be displayed in a chosen container element within the host page.
In combination with the existing theming capability, this could be used to achieve a seamless integration with the UI of the host page.
## Context
The Hypothesis client's main user interface consists of a sidebar that slides in/out from the right side of the host document's viewport.
The sidebar has one configuration. It's in a fixed position, spans the full height of the page, and when expanded it is layered on top of the page content.
This is a design that generally works with a wide range of content and host page user interfaces.
However there are some cases where this design is not completely ideal.
One example is the case where a host page author would prefer the sidebar to not conceal content as it's expanded.
More cases arise when the host page is designed with an existing sidebar.
The Hypothesis client can be deployed on a website through the use of an embeddable script. This usage allows the client to be configured through various settings.
The behaviour, branding and theme are customizable, but there currently is no configuration to change the sidebar's placement and layout.
Giving the host page control on where the client UI is contained would allow for better cohesion of both user interfaces.
## Proposal
- Add a new config option that explicitly specifies the DOM element that is to contain the sidebar's UI elements.
- Let this config be named `externalContainerSelector`
- The value provided is a CSS selector in the context of the host page.
- The selector must be to an element that exists in the DOM at or before client bootstrap.
- The default behaviour of the sidebar opening and closing with an animation should be prevented when the config is used.
- The sidebar is to be bound to and be contained inside the external element.
- The existing `onLayoutChanged` config should maintain an expected level of functionality.
- When the sidebar changes its expanded state, it should emit this accordingly.
- The width/height values emitted are the bounds of the sidebar element, as contained in the external element.
- Hide the Bucket bar and Toolbar when the config is used.
- The respective sidebar plugins will be disabled and not loaded.
- This is a compromise for allowing more control over the sidebar element's container.
- The detaching or reattaching of the external element is to be left as undefined behaviour.
- The client-server architecture with the discovery mechanism of the sidebar may allow this to be a non-issue but there could be unforeseen issues.
## Links
Pull Request: https://github.com/hypothesis/client/pull/707
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the linked Pull Request 707 and the client's embeddable script and bootstrap flow. Trace how the sidebar and its plugins are loaded, including onLayoutChanged, then determine whether the proposed externalContainerSelector behavior is already addressed. Done should match the proposal's container placement, layout events, and plugin exclusions.
Written by the indexing model from the issue text.
Assessment
- Domain
- frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100