Add documentation page for custom DOM events

docs/publishers/events.rst

+Events
+======
+
+The Hypothesis client emits custom DOM events at ``document.body``, to which your app can react.
+
+They extend `CustomEvent <https://developer.mozilla.org/docs/Web/API/CustomEvent>`_, so their payload can be found inside the ``detail`` property.
+
+.. option:: hypothesis:layoutchange
+
+   This event is emitted when the sidebar layout changes. eg. when it is opened or closed.
+
+Properties
+----------
+
+.. option:: sidebarLayout
+
+  .. option:: expanded
+
+     ``Boolean`` True if the sidebar is open
+
+  .. option:: width
+
+     ``Number`` The width of the sidebar in pixels
+
+  .. option:: height
+
+     ``Number`` The height of the sidebar in pixels
+
+.. option:: sideBySideActive
+
+  ``Boolean`` Indicates whether side-by-side mode is active
+
+.. code-block:: javascript
+
+    document.body.addEventListener('hypothesis:layoutchange', event => {
+      console.log(event.detail.sidebarLayout.expanded);
+      console.log(event.detail.sidebarLayout.width);
+      console.log(event.detail.sidebarLayout.height);
+      console.log(event.detail.sideBySideActive);
+    });
+
+.. note::
+
+  `See also "onLayoutChange" </publishers/config/#cmdoption-arg-onLayoutChange>`_ function, for an alternative way
+  to make your app programmatically react to layout changes.

docs/publishers/index.rst

@@ -13,3 +13,4 @@ pages will help you get started.
    embedding
    config
    host-page-integration
+   events

src/annotator/events.ts

 import type { SidebarLayout } from '../types/annotator';
 
 type LayoutChangeEventDetail = {
-  isSideBySideActive: boolean;
+  sideBySideActive: boolean;
   sidebarLayout: SidebarLayout;
 };
 

src/annotator/guest.ts

@@ -461,7 +461,7 @@ export class Guest extends TinyEmitter implements Annotator, Destroyable {
       this.element.dispatchEvent(
         new LayoutChangeEvent({
           sidebarLayout,
-          isSideBySideActive: this._sideBySideActive,
+          sideBySideActive: this._sideBySideActive,
         })
       );
     });

src/annotator/test/guest-test.js

@@ -260,7 +260,7 @@ describe('Guest', () => {
         assert.notCalled(fakeIntegration.fitSideBySide);
       });
 
-      it('emits a "hypothesis:layoutchange" DOM event', done => {
+      it('emits a "hypothesis:layoutchange" DOM event', () => {
         const guest = createGuest();
         const dummyLayout = {
           expanded: true,
@@ -268,14 +268,20 @@ describe('Guest', () => {
           height: 300,
           toolbarWidth: 10,
         };
+        const listener = sinon.stub();
 
-        guest.element.addEventListener('hypothesis:layoutchange', e => {
-          assert.equal(e.detail.sidebarLayout, dummyLayout);
-          // This ensures the test will timeout if this event is not emitted
-          done();
-        });
+        guest.element.addEventListener('hypothesis:layoutchange', listener);
 
         emitHostEvent('sidebarLayoutChanged', dummyLayout);
+
+        assert.calledWith(
+          listener,
+          sinon.match({
+            detail: sinon.match({
+              sidebarLayout: dummyLayout,
+            }),
+          })
+        );
       });
     });