Merge pull request #1454 from hypothesis/help-panel-utilities

Help & Tutorial 2/n: Add `isSidebar`, `versionData` utilities

src/sidebar/util/is-sidebar.js

+'use strict';
+
+/**
+ * Is the instance of the application in the current `window_` within a
+ * sidebar (vs. single-annotation or stream view)?
+ */
+const isSidebar = (window_ = window) => {
+  return !(
+    window_.location.pathname.startsWith('/stream') ||
+    window_.location.pathname.startsWith('/a/')
+  );
+};
+
+module.exports = isSidebar;

src/sidebar/util/test/is-sidebar-test.js

+'use strict';
+
+const isSidebar = require('../is-sidebar');
+
+describe('sidebar.utils.is-sidebar', () => {
+  [
+    '/a/random-annotation-id',
+    '/stream/',
+    '/stream',
+    '/a/',
+    '/a/foo.html',
+  ].forEach(fakePath => {
+    it(`returns false if window.location is in stream or single-annotation view (${fakePath})`, () => {
+      const window_ = {};
+      window_.location = new URL(`http://www.example.com${fakePath}`);
+      assert.isFalse(isSidebar(window_));
+    });
+  });
+
+  ['/whatever', '/anything-else', '/a', '/apples/', '/app.html'].forEach(
+    fakePath => {
+      it(`returns true if window.location is not in stream or single-annotation view (${fakePath})`, () => {
+        const window_ = {};
+        window_.location = new URL(`http://www.example.com${fakePath}`);
+        assert.isTrue(isSidebar(window_));
+      });
+    }
+  );
+});

src/sidebar/util/test/version-data-test.js

+'use strict';
+
+const VersionData = require('../version-data');
+
+describe('VersionData', () => {
+  let clock;
+
+  beforeEach(() => {
+    clock = sinon.useFakeTimers();
+  });
+
+  afterEach(() => {
+    clock.restore();
+  });
+
+  describe('constructor', () => {
+    it('sets `timestamp` to string of current date', () => {
+      const versionData = new VersionData({}, {});
+      assert.equal(versionData.timestamp, new Date().toString());
+    });
+
+    it('sets `version`', () => {
+      const versionData = new VersionData({}, {});
+      assert.equal(versionData.version, '1.0.0-dummy-version');
+    });
+
+    it('sets `userAgent`', () => {
+      const versionData = new VersionData(
+        {},
+        {},
+        { navigator: { userAgent: 'fakeUserAgent' } }
+      );
+      assert.equal(versionData.userAgent, 'fakeUserAgent');
+    });
+
+    context('empty `userInfo` and `documentInfo` objects', () => {
+      // This can happen early in app lifecycle
+      it('sets properties to "N/A" for missing values', () => {
+        const versionData = new VersionData({}, {});
+        ['url', 'fingerprint', 'account'].forEach(prop => {
+          assert.equal(versionData[prop], 'N/A');
+        });
+      });
+    });
+
+    describe('account information', () => {
+      it('includes display name if available', () => {
+        const versionData = new VersionData(
+          {
+            userid: 'acct:foo@bar.com',
+            displayName: 'Fred Hubert',
+          },
+          {}
+        );
+        assert.equal(versionData.account, 'Fred Hubert (acct:foo@bar.com)');
+      });
+
+      it('only includes userid if no display name', () => {
+        const versionData = new VersionData({ userid: 'acct:foo@bar.com' }, {});
+        assert.equal(versionData.account, 'acct:foo@bar.com');
+      });
+    });
+
+    describe('document information', () => {
+      it('sets `url`', () => {
+        const versionData = new VersionData(
+          {},
+          { uri: 'https://www.whatbadgerseat.com' }
+        );
+        assert.equal(versionData.url, 'https://www.whatbadgerseat.com');
+      });
+
+      it('sets `fingerprint`', () => {
+        const versionData = new VersionData(
+          {},
+          { metadata: { documentFingerprint: 'DEADBEEF' } }
+        );
+        assert.equal(versionData.fingerprint, 'DEADBEEF');
+      });
+    });
+  });
+
+  describe('#asEncodedURLString', () => {
+    ['timestamp', 'account'].forEach(prop => {
+      it(`includes encoded value for ${prop} in URL string`, () => {
+        const versionData = new VersionData({}, {});
+        const encoded = versionData.asEncodedURLString();
+        const subStr = encodeURIComponent(`${prop}: ${versionData[prop]}\r\n`);
+        assert.include(encoded, subStr);
+      });
+    });
+  });
+});

src/sidebar/util/version-data.js

+'use strict';
+
+/**
+ * An object representing user info
+ *
+ * @typedef {Object} UserInfo
+ * @property {string=} userid
+ * @property {string=} displayName
+ */
+
+/**
+ * An object representing document metadata
+ *
+ * @typedef {Object} DocMetadata
+ * @property {string=} documentFingerprint - optional PDF fingerprint for
+ *                     current document
+ */
+
+/**
+ * An object representing document info
+ *
+ * @typedef {Object} DocumentInfo
+ * @property {string=} url - current document URL
+ * @property {DocMetadata} metadata - document metadata
+ */
+
+class VersionData {
+  /**
+   * @param {UserInfo} userInfo
+   * @param {DocumentInfo} documentInfo
+   * @param {Window} window_ - test seam
+   * @return {VersionData}
+   */
+  constructor(userInfo, documentInfo, window_ = window) {
+    const noValueString = 'N/A';
+    const docMeta = documentInfo.metadata;
+
+    let accountString = noValueString;
+    if (userInfo.userid) {
+      accountString = userInfo.userid;
+      if (userInfo.displayName) {
+        accountString = `${userInfo.displayName} (${accountString})`;
+      }
+    }
+
+    this.timestamp = new Date().toString();
+    this.url = documentInfo.uri || noValueString;
+    this.fingerprint =
+      docMeta && docMeta.documentFingerprint
+        ? docMeta.documentFingerprint
+        : noValueString;
+    this.account = accountString;
+    this.userAgent = window_.navigator.userAgent;
+    this.version = '__VERSION__';
+  }
+
+  /**
+   * Return a single, encoded URL string of version data suitable for use in
+   * a querystring (as the value of a single parameter)
+   *
+   * @return {string} - URI-encoded string
+   */
+  asEncodedURLString() {
+    let versionString = '';
+    for (let prop in this) {
+      if (Object.prototype.hasOwnProperty.call(this, prop)) {
+        versionString += `${prop}: ${this[prop]}\r\n`;
+      }
+    }
+    return encodeURIComponent(versionString);
+  }
+}
+
+module.exports = VersionData;