hypothesis / hypothesis/client
Support loading Hypothesis as an ESM library
- Dominant language
- Mustache
- Stars
- 730
- Forks
- 224
- PR merge metrics
- No merged PRs in 30d
Description
The current mechanism for a web app like our video player to load Hypothesis into a page is clunky and doesn't provide the caller with a direct way to interact with the client after it is loaded.
A potentially better approach in modern browsers would be to support loading the boot script as an ES module and interacting with the client more like a library:
```js
const { initHypothesis } = import('https://hypothes.is/client.js');
// Load client. Returns a promise that resolves when ready.
const hypothesis = await initHypothesis({
openSidebar: true,
// Configuration here
});
// Listen for events.
hypothesis.on('layoutChanged', layout => {
console.log('Sidebar open?', layout.expanded);
});
// Command the client to do something.
hypothesis.sidebar.open();
// Unload the client if the web app decides to "turn off Hypothesis"
hypothesis.unload();
```
The immediate advantages for us in the context of the video player would be:
- Easier to use than adding a script tag to the page
- Supports passing non JSON-serializable configuration to client, without needing to create a script tag that sets global variables. The video player for example could pass an HTML element for the bucket bar container rather than a selector.
- Exposes a reference to a "controller" that can be used later to interact with the loaded client. We could use this for example to defer anchoring of annotations in the client until the transcript has loaded (https://github.com/hypothesis/client/issues/5568)
Some other future advantages:
- If client events were registered via the controller, this would allow us to observe how many websites are registering for particular events, making it easier to safely make changes to them if we need.
Some outstanding questions:
- How do we deal with versioning? The answer with the current Hypothesis client "API" is "we don't make breaking changes". We could probably take the same approach here, although we'd have more flexibility.
## Out of scope
This proposal is not focused on supporting the use case of someone trying to re-use parts of Hypothesis's internals like anchoring or API client, though that would be separately useful. The right way to handle that would be to extract that functionality into separate packages and publish those to npm.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.