@edx/frontend-platform 4.6.0 → 4.6.2

package/docs/template/edx/tmpl/members.tmpl

@@ -0,0 +1,38 @@
+<?js
+var data = obj;
+var self = this;
+?>
+<h4 class="name" id="<?js= id ?>"><?js= data.attribs + name + (data.signature ? data.signature : '') ?></h4>
+
+<?js if (data.summary) { ?>
+<p class="summary"><?js= summary ?></p>
+<?js } ?>
+
+<?js if (data.description) { ?>
+<div class="description">
+    <?js= data.description ?>
+</div>
+<?js } ?>
+
+<?js if (data.type && data.type.names) {?>
+    <h5>Type:</h5>
+    <ul>
+        <li>
+            <?js= self.partial('type.tmpl', data.type.names) ?>
+        </li>
+    </ul>
+<?js } ?>
+
+<?js= this.partial('details.tmpl', data) ?>
+
+<?js if (data.fires && fires.length) { ?>
+    <h5>Fires:</h5>
+    <ul><?js fires.forEach(function(f) { ?>
+        <li><?js= self.linkto(f) ?></li>
+    <?js }); ?></ul>
+<?js } ?>
+
+<?js if (data.examples && examples.length) { ?>
+    <h5>Example<?js= examples.length > 1? 's':'' ?></h5>
+    <?js= this.partial('examples.tmpl', examples) ?>
+<?js } ?>

package/docs/template/edx/tmpl/method.tmpl

@@ -0,0 +1,131 @@
+<?js
+var data = obj;
+var self = this;
+?>
+<?js if (data.kind !== 'module' && !data.hideconstructor) { ?>
+    <?js if (data.kind === 'class' && data.classdesc) { ?>
+    <h2>Constructor</h2>
+    <?js } ?>
+
+    <?js if (data.kind !== 'namespace') { ?>
+    <h4 class="name" id="<?js= id ?>"><?js= data.attribs + (kind === 'class' ? 'new ' : '') +
+    name + (data.signature || '') ?></h4>
+    <?js } ?>
+
+    <?js if (data.summary) { ?>
+    <p class="summary"><?js= summary ?></p>
+    <?js } ?>
+<?js } ?>
+
+<?js if (data.kind !== 'module' && data.description && !data.hideconstructor) { ?>
+<div class="description">
+    <?js= data.description ?>
+</div>
+<?js } ?>
+
+<?js if (data.augments && data.alias && data.alias.indexOf('module:') === 0) { ?>
+    <h5>Extends:</h5>
+    <?js= self.partial('augments.tmpl', data) ?>
+<?js } ?>
+
+<?js if (kind === 'event' && data.type && data.type.names) {?>
+    <h5>Type:</h5>
+    <ul>
+        <li>
+            <?js= self.partial('type.tmpl', data.type.names) ?>
+        </li>
+    </ul>
+<?js } ?>
+
+<?js if (data['this']) { ?>
+    <h5>This:</h5>
+    <ul><li><?js= this.linkto(data['this'], data['this']) ?></li></ul>
+<?js } ?>
+
+<?js if (data.params && params.length && !data.hideconstructor) { ?>
+    <h5>Parameters:</h5>
+    <?js= this.partial('params.tmpl', params) ?>
+<?js } ?>
+
+<?js= this.partial('details.tmpl', data) ?>
+
+<?js if (data.kind !== 'module' && data.requires && data.requires.length) { ?>
+<h5>Requires:</h5>
+<ul><?js data.requires.forEach(function(r) { ?>
+    <li><?js= self.linkto(r) ?></li>
+<?js }); ?></ul>
+<?js } ?>
+
+<?js if (data.fires && fires.length) { ?>
+<h5>Fires:</h5>
+<ul><?js fires.forEach(function(f) { ?>
+    <li><?js= self.linkto(f) ?></li>
+<?js }); ?></ul>
+<?js } ?>
+
+<?js if (data.listens && listens.length) { ?>
+<h5>Listens to Events:</h5>
+<ul><?js listens.forEach(function(f) { ?>
+    <li><?js= self.linkto(f) ?></li>
+<?js }); ?></ul>
+<?js } ?>
+
+<?js if (data.listeners && listeners.length) { ?>
+<h5>Listeners of This Event:</h5>
+<ul><?js listeners.forEach(function(f) { ?>
+    <li><?js= self.linkto(f) ?></li>
+<?js }); ?></ul>
+<?js } ?>
+
+<?js if (data.modifies && modifies.length) {?>
+<h5>Modifies:</h5>
+<?js if (modifies.length > 1) { ?><ul><?js
+    modifies.forEach(function(m) { ?>
+        <li><?js= self.partial('modifies.tmpl', m) ?></li>
+    <?js });
+?></ul><?js } else {
+    modifies.forEach(function(m) { ?>
+        <?js= self.partial('modifies.tmpl', m) ?>
+    <?js });
+} } ?>
+
+<?js if (data.exceptions && exceptions.length) { ?>
+<h5>Throws:</h5>
+<?js if (exceptions.length > 1) { ?><ul><?js
+    exceptions.forEach(function(r) { ?>
+        <li><?js= self.partial('exceptions.tmpl', r) ?></li>
+    <?js });
+?></ul><?js } else {
+    exceptions.forEach(function(r) { ?>
+        <?js= self.partial('exceptions.tmpl', r) ?>
+    <?js });
+} } ?>
+
+<?js if (data.returns && returns.length) { ?>
+<h5>Returns:</h5>
+<?js if (returns.length > 1) { ?><ul><?js
+    returns.forEach(function(r) { ?>
+        <li><?js= self.partial('returns.tmpl', r) ?></li>
+    <?js });
+?></ul><?js } else {
+    returns.forEach(function(r) { ?>
+        <?js= self.partial('returns.tmpl', r) ?>
+    <?js });
+} } ?>
+
+<?js if (data.yields && yields.length) { ?>
+<h5>Yields:</h5>
+<?js if (yields.length > 1) { ?><ul><?js
+    yields.forEach(function(r) { ?>
+        <li><?js= self.partial('returns.tmpl', r) ?></li>
+    <?js });
+?></ul><?js } else {
+    yields.forEach(function(r) { ?>
+        <?js= self.partial('returns.tmpl', r) ?>
+    <?js });
+} } ?>
+
+<?js if (data.examples && examples.length) { ?>
+    <h5>Example<?js= examples.length > 1? 's':'' ?></h5>
+    <?js= this.partial('examples.tmpl', examples) ?>
+<?js } ?>

package/docs/template/edx/tmpl/modifies.tmpl

@@ -0,0 +1,14 @@
+<?js
+var data = obj || {};
+?>
+
+<?js if (data.type && data.type.names) {?>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+        <?js= this.partial('type.tmpl', data.type.names) ?>
+    </dd>
+</dl>
+<?js } ?>

package/docs/template/edx/tmpl/params.tmpl

@@ -0,0 +1,131 @@
+<?js
+    var params = obj;
+
+    /* sort subparams under their parent params (like opts.classname) */
+    var parentParam = null;
+    params.forEach(function(param, i) {
+        var paramRegExp;
+
+        if (!param) {
+            return;
+        }
+
+        if (parentParam && parentParam.name && param.name) {
+            try {
+                paramRegExp = new RegExp('^(?:' + parentParam.name + '(?:\\[\\])*)\\.(.+)$');
+            }
+            catch (e) {
+                // there's probably a typo in the JSDoc comment that resulted in a weird
+                // parameter name
+                return;
+            }
+
+            if ( paramRegExp.test(param.name) ) {
+                param.name = RegExp.$1;
+                parentParam.subparams = parentParam.subparams || [];
+                parentParam.subparams.push(param);
+                params[i] = null;
+            }
+            else {
+                parentParam = param;
+            }
+        }
+        else {
+            parentParam = param;
+        }
+    });
+
+    /* determine if we need extra columns, "attributes" and "default" */
+    params.hasAttributes = false;
+    params.hasDefault = false;
+    params.hasName = false;
+
+    params.forEach(function(param) {
+        if (!param) { return; }
+
+        if (param.optional || param.nullable || param.variable) {
+            params.hasAttributes = true;
+        }
+
+        if (param.name) {
+            params.hasName = true;
+        }
+
+        if (typeof param.defaultvalue !== 'undefined') {
+            params.hasDefault = true;
+        }
+    });
+?>
+
+<table class="params">
+    <thead>
+    <tr>
+        <?js if (params.hasName) {?>
+        <th>Name</th>
+        <?js } ?>
+
+        <th>Type</th>
+
+        <?js if (params.hasAttributes) {?>
+        <th>Attributes</th>
+        <?js } ?>
+
+        <?js if (params.hasDefault) {?>
+        <th>Default</th>
+        <?js } ?>
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    <?js
+        var self = this;
+        params.forEach(function(param) {
+            if (!param) { return; }
+    ?>
+
+        <tr>
+            <?js if (params.hasName) {?>
+                <td class="name"><code><?js= param.name ?></code></td>
+            <?js } ?>
+
+            <td class="type">
+            <?js if (param.type && param.type.names) {?>
+                <?js= self.partial('type.tmpl', param.type.names) ?>
+            <?js } ?>
+            </td>
+
+            <?js if (params.hasAttributes) {?>
+                <td class="attributes">
+                <?js if (param.optional) { ?>
+                    &lt;optional><br>
+                <?js } ?>
+
+                <?js if (param.nullable) { ?>
+                    &lt;nullable><br>
+                <?js } ?>
+
+                <?js if (param.variable) { ?>
+                    &lt;repeatable><br>
+                <?js } ?>
+                </td>
+            <?js } ?>
+
+            <?js if (params.hasDefault) {?>
+                <td class="default">
+                <?js if (typeof param.defaultvalue !== 'undefined') { ?>
+                    <?js= self.htmlsafe(param.defaultvalue) ?>
+                <?js } ?>
+                </td>
+            <?js } ?>
+
+            <td class="description last"><?js= param.description ?><?js if (param.subparams) { ?>
+                <h6>Properties</h6>
+                <?js= self.partial('params.tmpl', param.subparams) ?>
+            <?js } ?></td>
+        </tr>
+
+    <?js }); ?>
+    </tbody>
+</table>

package/docs/template/edx/tmpl/properties.tmpl

@@ -0,0 +1,108 @@
+<?js
+    var data = obj;
+    var props = data.subprops || data.properties;
+
+    /* sort subprops under their parent props (like opts.classname) */
+    var parentProp = null;
+    props.forEach(function(prop, i) {
+        if (!prop) { return; }
+        if ( parentProp && prop.name && prop.name.indexOf(parentProp.name + '.') === 0 ) {
+            prop.name = prop.name.substr(parentProp.name.length+1);
+            parentProp.subprops = parentProp.subprops || [];
+            parentProp.subprops.push(prop);
+            props[i] = null;
+        }
+        else {
+            parentProp = prop;
+        }
+    });
+
+    /* determine if we need extra columns, "attributes" and "default" */
+    props.hasAttributes = false;
+    props.hasDefault = false;
+    props.hasName = false;
+
+    props.forEach(function(prop) {
+        if (!prop) { return; }
+
+        if (prop.optional || prop.nullable) {
+            props.hasAttributes = true;
+        }
+
+        if (prop.name) {
+            props.hasName = true;
+        }
+
+        if (typeof prop.defaultvalue !== 'undefined' && !data.isEnum) {
+            props.hasDefault = true;
+        }
+    });
+?>
+
+<table class="props">
+    <thead>
+    <tr>
+        <?js if (props.hasName) {?>
+        <th>Name</th>
+        <?js } ?>
+
+        <th>Type</th>
+
+        <?js if (props.hasAttributes) {?>
+        <th>Attributes</th>
+        <?js } ?>
+
+        <?js if (props.hasDefault) {?>
+        <th>Default</th>
+        <?js } ?>
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    <?js
+        var self = this;
+        props.forEach(function(prop) {
+            if (!prop) { return; }
+    ?>
+
+        <tr>
+            <?js if (props.hasName) {?>
+                <td class="name"><code><?js= prop.name ?></code></td>
+            <?js } ?>
+
+            <td class="type">
+            <?js if (prop.type && prop.type.names) {?>
+                <?js= self.partial('type.tmpl', prop.type.names) ?>
+            <?js } ?>
+            </td>
+
+            <?js if (props.hasAttributes) {?>
+                <td class="attributes">
+                <?js if (prop.optional) { ?>
+                    &lt;optional><br>
+                <?js } ?>
+
+                <?js if (prop.nullable) { ?>
+                    &lt;nullable><br>
+                <?js } ?>
+                </td>
+            <?js } ?>
+
+            <?js if (props.hasDefault) {?>
+                <td class="default">
+                <?js if (typeof prop.defaultvalue !== 'undefined') { ?>
+                    <?js= self.htmlsafe(prop.defaultvalue) ?>
+                <?js } ?>
+                </td>
+            <?js } ?>
+
+            <td class="description last"><?js= prop.description ?><?js if (prop.subprops) { ?>
+                <h6>Properties</h6><?js= self.partial('properties.tmpl', prop) ?>
+            <?js } ?></td>
+        </tr>
+
+    <?js }); ?>
+    </tbody>
+</table>

package/docs/template/edx/tmpl/returns.tmpl

@@ -0,0 +1,19 @@
+<?js
+var data = obj || {};
+if (data.description) {
+?>
+<div class="param-desc">
+    <?js= description ?>
+</div>
+<?js } ?>
+
+<?js if (data.type && data.type.names) {?>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+        <?js= this.partial('type.tmpl', data.type.names) ?>
+    </dd>
+</dl>
+<?js } ?>

package/docs/template/edx/tmpl/source.tmpl

@@ -0,0 +1,8 @@
+<?js
+    var data = obj;
+?>
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code><?js= data.code ?></code></pre>
+        </article>
+    </section>

package/docs/template/edx/tmpl/tutorial.tmpl

@@ -0,0 +1,19 @@
+<section>
+
+<header>
+    <?js if (children.length > 0) { ?>
+    <ul><?js
+        var self = this;
+        children.forEach(function(t) { ?>
+        <li><?js= self.tutoriallink(t.name) ?></li>
+    <?js }); ?></ul>
+    <?js } ?>
+
+    <h2><?js= header ?></h2>
+</header>
+
+<article>
+    <?js= content ?>
+</article>
+
+</section>

package/docs/template/edx/tmpl/type.tmpl

@@ -0,0 +1,7 @@
+<?js
+    var data = obj;
+    var self = this;
+    data.forEach(function(name, i) { ?>
+<span class="param-type"><?js= self.linkto(name, self.htmlsafe(name)) ?></span>
+<?js if (i < data.length-1) { ?>|<?js } ?>
+<?js }); ?>

package/env.config.js

@@ -0,0 +1,8 @@
+// NOTE: This file is used by the example app.  frontend-build expects the file
+// to be in the root of the repository.  This is not used by the actual frontend-platform library.
+// Also note that in an actual application this file would be added to .gitignore.
+const config = {
+  JS_FILE_VAR: 'JS_FILE_VAR_VALUE_FOR_EXAMPLE_APP',
+};
+
+export default config;

package/jsdoc.json

@@ -0,0 +1,36 @@
+{
+  "tags": {
+      "allowUnknownTags": true,
+      "dictionaries": ["jsdoc"]
+  },
+  "source": {
+      "include": ["src", "package.json", "README.md"],
+      "includePattern": ".+\\.js(doc|x)?$",
+      "excludePattern": "(node_modules/|docs)"
+  },
+  "plugins": [
+      "plugins/markdown",
+      "docs/addTagsPlugin",
+      "docs/removeExport"
+  ],
+  "templates": {
+      "cleverLinks": false,
+      "monospaceLinks": true,
+      "useLongnameInNav": false,
+      "showInheritedInNav": true,
+      "default": {
+        "staticFiles": {
+          "include": [
+              "./service-interface.png"
+          ]
+        }
+      }
+  },
+  "opts": {
+      "destination": "./docs/api",
+      "encoding": "utf8",
+      "private": true,
+      "recurse": true,
+      "template": "docs/template/edx"
+  }
+}

package/openedx.yaml

@@ -0,0 +1,12 @@
+# openedx.yaml
+
+---
+owner: edx/fedx-team
+tags:
+  - library
+  - platform
+  - react
+  - i18n
+  - analytics
+  - logging
+  - authentication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edx/frontend-platform",
-  "version": "4.6.0",
+  "version": "4.6.2",
   "description": "Foundational application framework for Open edX micro-frontend applications.",
   "main": "index.js",
   "publishConfig": {
@@ -34,12 +34,12 @@
   "devDependencies": {
     "@edx/brand": "npm:@edx/brand-openedx@1.2.0",
     "@edx/browserslist-config": "1.2.0",
-    "@edx/frontend-build": "12.8.57",
+    "@edx/frontend-build": "12.9.3",
     "@edx/paragon": "^20.44.0",
     "@testing-library/react-hooks": "^8.0.1",
     "@wojtekmaj/enzyme-adapter-react-17": "0.8.0",
-    "axios-mock-adapter": "^1.21.3",
-    "core-js": "3.31.0",
+    "axios-mock-adapter": "^1.21.5",
+    "core-js": "3.32.0",
     "enzyme": "3.11.0",
     "husky": "8.0.3",
     "jsdoc": "^4.0.0",
@@ -74,8 +74,8 @@
     "universal-cookie": "4.0.4"
   },
   "peerDependencies": {
-    "@edx/frontend-build": ">= 8.1.0",
-    "@edx/paragon": ">= 10.0.0 < 21.0.0",
+    "@edx/frontend-build": ">= 8.1.0 || ^12.9.0-alpha.1",
+    "@edx/paragon": ">= 10.0.0 < 22.0.0",
     "prop-types": "^15.7.2",
     "react": "^16.9.0 || ^17.0.0",
     "react-dom": "^16.9.0 || ^17.0.0",

package/src/analytics/MockAnalyticsService.js

@@ -0,0 +1,71 @@
+/**
+ * The MockAnalyticsService implements all functions of AnalyticsService as Jest mocks (jest.fn())).
+ * It emulates the behavior of a real analytics service but witohut making any requests. It has no
+ * other functionality.
+ *
+ * @implements {AnalyticsService}
+ * @memberof module:Analytics
+ */
+class MockAnalyticsService {
+  static hasIdentifyBeenCalled = false;
+
+  constructor({ httpClient, loggingService }) {
+    this.loggingService = loggingService;
+    this.httpClient = httpClient;
+  }
+
+  checkIdentifyCalled = jest.fn(() => {
+    if (!this.hasIdentifyBeenCalled) {
+      this.loggingService.logError('Identify must be called before other tracking events.');
+    }
+  });
+
+  /**
+   * Returns a resolved promise.
+   *
+   * @returns {Promise} The promise returned by HttpClient.post.
+   */
+  sendTrackingLogEvent = jest.fn(() => Promise.resolve());
+
+  /**
+   * No-op, but records that identify has been called.
+   *
+   * @param {string} userId
+   * @throws {Error} If userId argument is not supplied.
+   */
+  identifyAuthenticatedUser = jest.fn((userId) => {
+    if (!userId) {
+      throw new Error('UserId is required for identifyAuthenticatedUser.');
+    }
+    this.hasIdentifyBeenCalled = true;
+  });
+
+  /**
+   * No-op, but records that it has been called to prevent double-identification.
+   * @returns {Promise} A resolved promise.
+   */
+  identifyAnonymousUser = jest.fn(() => {
+    this.hasIdentifyBeenCalled = true;
+    return Promise.resolve();
+  });
+
+  /**
+   * Logs the event to the console.
+   *
+   * Checks whether identify has been called, logging an error to the logging service if not.
+   */
+  sendTrackEvent = jest.fn(() => {
+    this.checkIdentifyCalled();
+  });
+
+  /**
+   * Logs the event to the console.
+   *
+   * Checks whether identify has been called, logging an error to the logging service if not.
+   */
+  sendPageEvent = jest.fn(() => {
+    this.checkIdentifyCalled();
+  });
+}
+
+export default MockAnalyticsService;