diff --git a/.eslintrc.cjs b/.eslintrc.cjs new file mode 100755 index 000000000..125972f32 --- /dev/null +++ b/.eslintrc.cjs @@ -0,0 +1,42 @@ +// eslint-disable-next-line import/no-extraneous-dependencies +const { getBaseConfig } = require('@edx/frontend-build'); + +const config = getBaseConfig('eslint'); + +// Enable the eslint-plugin-jsdoc plugin +config.extends = ['@edx/eslint-config', 'plugin:jsdoc/recommended-typescript-flavor']; +config.plugins = [...(config.plugins ?? []), 'jsdoc']; +config.settings = { + ...config.settings, + jsdoc: { mode: 'typescript', preferredTypes: { object: 'Object' } }, +}; + +config.rules = { + 'import/no-extraneous-dependencies': ['error', { + devDependencies: [ + '**/*.config.js', + '**/*.test.jsx', + '**/*.test.js', + 'example/*', + ], + }], + 'import/extensions': ['error', 'always', { + ignorePackages: true, + }], + 'import/no-unresolved': ['error', { + ignore: ['@edx/frontend-platform*'], + }], + 'jsx-a11y/anchor-is-valid': ['error', { + components: ['Link'], + specialLink: ['to'], + aspects: ['noHref', 'invalidHref', 'preferButton'], + }], + // There are too many missing descriptions to turn this on at the moment :/ + 'jsdoc/require-property-description': ['off'], + 'jsdoc/require-param-description': ['off'], + 'jsdoc/require-returns-description': ['off'], + 'jsdoc/check-types': ['warn'], + 'jsdoc/tag-lines': ['off'], +}; + +module.exports = config; diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100755 index 8d5d03d00..000000000 --- a/.eslintrc.js +++ /dev/null @@ -1,28 +0,0 @@ -// eslint-disable-next-line import/no-extraneous-dependencies -const { getBaseConfig } = require('@edx/frontend-build'); - -const config = getBaseConfig('eslint'); - -config.rules = { - 'import/no-extraneous-dependencies': ['error', { - devDependencies: [ - '**/*.config.js', - '**/*.test.jsx', - '**/*.test.js', - 'example/*', - ], - }], - 'import/extensions': ['error', { - ignore: ['@edx/frontend-platform*'], - }], - 'import/no-unresolved': ['error', { - ignore: ['@edx/frontend-platform*'], - }], - 'jsx-a11y/anchor-is-valid': ['error', { - components: ['Link'], - specialLink: ['to'], - aspects: ['noHref', 'invalidHref', 'preferButton'], - }], -}; - -module.exports = config; diff --git a/.gitignore b/.gitignore index 908e81fe5..df08d13a1 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ .vscode coverage dist +types node_modules /docs/api .env.private diff --git a/Makefile b/Makefile index 139d2f848..af5d96b70 100644 --- a/Makefile +++ b/Makefile @@ -4,14 +4,8 @@ doc_command = ./node_modules/.bin/documentation build src -g -c ./docs/documenta cat_docs_command = cat ./docs/_API-header.md ./docs/_API-body.md > ./docs/API.md build: - rm -rf ./dist - ./node_modules/.bin/fedx-scripts babel src --out-dir dist --source-maps --ignore **/*.test.jsx,**/*.test.js,**/setupTest.js --copy-files - @# --copy-files will bring in everything else that wasn't processed by babel. Remove what we don't want. - @find dist -name '*.test.js*' -delete - rm ./dist/setupTest.js - cp ./package.json ./dist/package.json - cp ./LICENSE ./dist/LICENSE - cp ./README.md ./dist/README.md + rm -rf types/* + npx tsc docs-build: ${doc_command} diff --git a/babel.config.js b/babel.config.cjs similarity index 100% rename from babel.config.js rename to babel.config.cjs diff --git a/docs/addTagsPlugin.js b/docs/addTagsPlugin.js deleted file mode 100644 index f82e516f9..000000000 --- a/docs/addTagsPlugin.js +++ /dev/null @@ -1,10 +0,0 @@ -exports.defineTags = function (dictionary) { - dictionary.defineTag("service", { - mustHaveValue: true, - canHaveType: false, - canHaveName: true, - onTagged: function (doclet, tag) { - doclet.service = tag.value; - } - }); -}; diff --git a/docs/removeExport.js b/docs/removeExport.js deleted file mode 100644 index dc454e0c5..000000000 --- a/docs/removeExport.js +++ /dev/null @@ -1,24 +0,0 @@ -/** - * JSDoc plugin. - * - * Modifies the source code to remove the "export" keyword before JS doc sees it. This removes - * "exports." prefixes from documented members. - * - * @module plugins/exportKiller - */ -exports.handlers = { - beforeParse(e) { - e.source = e.source.replace(/(\nexport function)/g, $ => { - return `\nfunction`; - }); - e.source = e.source.replace(/(\nexport const)/g, $ => { - return `\nconst`; - }); - e.source = e.source.replace(/(\nexport default)/g, $ => { - return `\n`; - }); - e.source = e.source.replace(/(\nexport async function)/g, $ => { - return `\nasync function`; - }); - } -}; diff --git a/docs/template/edx/README.md b/docs/template/edx/README.md deleted file mode 100644 index fa14df95c..000000000 --- a/docs/template/edx/README.md +++ /dev/null @@ -1,12 +0,0 @@ -The default template for JSDoc 4 uses: the [Underscore Template library](http://underscorejs.org/). - - -## Generating Typeface Fonts - -The default template uses the [OpenSans](https://www.google.com/fonts/specimen/Open+Sans) typeface. The font files can be regenerated as follows: - -1. Open the [OpenSans page at Font Squirrel](). -2. Click on the 'Webfont Kit' tab. -3. Either leave the subset drop-down as 'Western Latin (Default)', or, if we decide we need more glyphs, than change it to 'No Subsetting'. -4. Click the 'DOWNLOAD @FONT-FACE KIT' button. -5. For each typeface variant we plan to use, copy the 'eot', 'svg' and 'woff' files into the 'templates/default/static/fonts' directory. diff --git a/docs/template/edx/publish.js b/docs/template/edx/publish.js deleted file mode 100644 index 4c390f56c..000000000 --- a/docs/template/edx/publish.js +++ /dev/null @@ -1,713 +0,0 @@ -const doop = require('jsdoc/util/doop'); -const env = require('jsdoc/env'); -const fs = require('jsdoc/fs'); -const helper = require('jsdoc/util/templateHelper'); -const logger = require('jsdoc/util/logger'); -const path = require('jsdoc/path'); -const template = require('jsdoc/template'); -const util = require('util'); - -const htmlsafe = helper.htmlsafe; -const linkto = helper.linkto; -const resolveAuthorLinks = helper.resolveAuthorLinks; -const hasOwnProp = Object.prototype.hasOwnProperty; - -let data; -let view; - -let outdir = path.normalize(env.opts.destination); - -function find(spec) { - return helper.find(data, spec); -} - -function tutoriallink(tutorial) { - return helper.toTutorial(tutorial, null, { - tag: 'em', - classname: 'disabled', - prefix: 'Tutorial: ' - }); -} - -function getAncestorLinks(doclet) { - return helper.getAncestorLinks(data, doclet); -} - -function hashToLink(doclet, hash) { - let url; - - if ( !/^(#.+)/.test(hash) ) { - return hash; - } - - url = helper.createLink(doclet); - url = url.replace(/(#.+|$)/, hash); - - return `${hash}`; -} - -function needsSignature({kind, type, meta}) { - let needsSig = false; - - // function and class definitions always get a signature - if (kind === 'function' || kind === 'class') { - needsSig = true; - } - // typedefs that contain functions get a signature, too - else if (kind === 'typedef' && type && type.names && - type.names.length) { - for (let i = 0, l = type.names.length; i < l; i++) { - if (type.names[i].toLowerCase() === 'function') { - needsSig = true; - break; - } - } - } - // and namespaces that are functions get a signature (but finding them is a - // bit messy) - else if (kind === 'namespace' && meta && meta.code && - meta.code.type && meta.code.type.match(/[Ff]unction/)) { - needsSig = true; - } - - return needsSig; -} - -function getSignatureAttributes({optional, nullable}) { - const attributes = []; - - if (optional) { - attributes.push('opt'); - } - - if (nullable === true) { - attributes.push('nullable'); - } - else if (nullable === false) { - attributes.push('non-null'); - } - - return attributes; -} - -function updateItemName(item) { - const attributes = getSignatureAttributes(item); - let itemName = item.name || ''; - - if (item.variable) { - itemName = `…${itemName}`; - } - - if (attributes && attributes.length) { - itemName = util.format( '%s%s', itemName, - attributes.join(', ') ); - } - - return itemName; -} - -function addParamAttributes(params) { - return params.filter(({name}) => name && !name.includes('.')).map(updateItemName); -} - -function buildItemTypeStrings(item) { - const types = []; - - if (item && item.type && item.type.names) { - item.type.names.forEach(name => { - types.push( linkto(name, htmlsafe(name)) ); - }); - } - - return types; -} - -function buildAttribsString(attribs) { - let attribsString = ''; - - if (attribs && attribs.length) { - attribsString = htmlsafe( util.format('(%s) ', attribs.join(', ')) ); - } - - return attribsString; -} - -function addNonParamAttributes(items) { - let types = []; - - items.forEach(item => { - types = types.concat( buildItemTypeStrings(item) ); - }); - - return types; -} - -function addSignatureParams(f) { - const params = f.params ? addParamAttributes(f.params) : []; - - f.signature = util.format( '%s(%s)', (f.signature || ''), params.join(', ') ); -} - -function addSignatureReturns(f) { - const attribs = []; - let attribsString = ''; - let returnTypes = []; - let returnTypesString = ''; - const source = f.yields || f.returns; - - // jam all the return-type attributes into an array. this could create odd results (for example, - // if there are both nullable and non-nullable return types), but let's assume that most people - // who use multiple @return tags aren't using Closure Compiler type annotations, and vice-versa. - if (source) { - source.forEach(item => { - helper.getAttribs(item).forEach(attrib => { - if (!attribs.includes(attrib)) { - attribs.push(attrib); - } - }); - }); - - attribsString = buildAttribsString(attribs); - } - - if (source) { - returnTypes = addNonParamAttributes(source); - } - if (returnTypes.length) { - returnTypesString = util.format( ' → %s{%s}', attribsString, returnTypes.join('|') ); - } - - f.signature = `${f.signature || ''}${returnTypesString}`; -} - -function addSignatureTypes(f) { - const types = f.type ? buildItemTypeStrings(f) : []; - - f.signature = `${f.signature || ''}${types.length ? ` :${types.join('|')}` : ''}`; -} - -function addAttribs(f) { - const attribs = helper.getAttribs(f); - const attribsString = buildAttribsString(attribs); - - f.attribs = util.format('%s', attribsString); -} - -function shortenPaths(files, commonPrefix) { - Object.keys(files).forEach(file => { - files[file].shortened = files[file].resolved.replace(commonPrefix, '') - // always use forward slashes - .replace(/\\/g, '/'); - }); - - return files; -} - -function getPathFromDoclet({meta}) { - if (!meta) { - return null; - } - - return meta.path && meta.path !== 'null' ? - path.join(meta.path, meta.filename) : - meta.filename; -} - -function generate(title, docs, filename, { resolveLinks = false, moduleName = '' } = {}) { - let docData; - let html; - let outpath; - resolveLinks = resolveLinks !== false; - - docData = { - env: env, - title: title, - docs: docs, - moduleName, - }; - - outpath = path.join(outdir, filename); - html = view.render('container.tmpl', docData); - - if (resolveLinks) { - html = helper.resolveLinks(html); // turn {@link foo} into foo - } - - fs.writeFileSync(outpath, html, 'utf8'); -} - -function generateSourceFiles(sourceFiles, encoding = 'utf8') { - Object.keys(sourceFiles).forEach(file => { - let source; - // links are keyed to the shortened path in each doclet's `meta.shortpath` property - const sourceOutfile = helper.getUniqueFilename(sourceFiles[file].shortened); - - helper.registerLink(sourceFiles[file].shortened, sourceOutfile); - - try { - source = { - kind: 'source', - code: helper.htmlsafe( fs.readFileSync(sourceFiles[file].resolved, encoding) ) - }; - } - catch (e) { - logger.error('Error while generating source file %s: %s', file, e.message); - } - - generate(`Source: ${sourceFiles[file].shortened}`, [source], sourceOutfile); - }); -} - -/** - * Look for classes or functions with the same name as modules (which indicates that the module - * exports only that class or function), then attach the classes or functions to the `module` - * property of the appropriate module doclets. The name of each class or function is also updated - * for display purposes. This function mutates the original arrays. - * - * @private - * @param {Array.} doclets - The array of classes and functions to - * check. - * @param {Array.} modules - The array of module doclets to search. - */ -function attachModuleSymbols(doclets, modules) { - const symbols = {}; - - // build a lookup table - doclets.forEach(symbol => { - symbols[symbol.longname] = symbols[symbol.longname] || []; - symbols[symbol.longname].push(symbol); - }); - - modules.forEach(module => { - if (symbols[module.longname]) { - module.modules = symbols[module.longname] - // Only show symbols that have a description. Make an exception for classes, because - // we want to show the constructor-signature heading no matter what. - .filter(({description, kind}) => description || kind === 'class') - .map(symbol => { - symbol = doop(symbol); - - if (symbol.kind === 'class' || symbol.kind === 'function') { - symbol.name = `${symbol.name.replace('module:', '(require("')}"))`; - } - - return symbol; - }); - } - }); -} - -function buildMemberNav(items, itemHeading, itemsSeen, linktoFn) { - let nav = ''; - - const renderSubNav = (doclets => { - if (!doclets || !doclets.length) return ''; - - const renderChild = (doclet) => { - return `
  • ${linktoFn(doclet.longname, doclet.name)}
    • `; - } - - return ` -
      - ${doclets.map(renderChild).join('')} -
    - `; - }); - - if (items.length) { - let itemsNav = ''; - - items.forEach(item => { - let displayName; - - if ( !hasOwnProp.call(item, 'longname') ) { - itemsNav += `
  • ${linktoFn('', item.name, 'nav-link')}
    • `; - } - else if ( !hasOwnProp.call(itemsSeen, item.longname) ) { - if (env.conf.templates.default.useLongnameInNav) { - displayName = item.longname; - } else { - displayName = item.name; - } - - itemsNav += `
  • - ${linktoFn(item.longname, displayName.replace(/\b(module|event):/g), 'nav-link font-weight-bold')} - ${renderSubNav(item.children)} -
    • `; - - itemsSeen[item.longname] = true; - } - }); - - if (itemsNav !== '') { - nav += `
      ${itemsNav}
    `; - } - } - - return nav; -} - -function linktoTutorial(longName, name) { - return tutoriallink(name); -} - -function linktoExternal(longName, name) { - return linkto(longName, name.replace(/(^"|"$)/g, '')); -} - -/** - * Create the navigation sidebar. - * @param {object} members The members that will be used to create the sidebar. - * @param {array} members.classes - * @param {array} members.externals - * @param {array} members.globals - * @param {array} members.mixins - * @param {array} members.modules - * @param {array} members.namespaces - * @param {array} members.tutorials - * @param {array} members.events - * @param {array} members.interfaces - * @return {string} The HTML for the navigation sidebar. - */ -function buildNav(members) { - let globalNav; - let nav = '

    Home

    '; - const seen = {}; - const seenTutorials = {}; - - nav += buildMemberNav(members.modules, 'Modules', {}, linkto); - // nav += buildMemberNav(members.externals, 'Externals', seen, linktoExternal); - // nav += buildMemberNav(members.namespaces, 'Namespaces', seen, linkto); - // nav += buildMemberNav(members.classes, 'Classes', seen, linkto); - // nav += buildMemberNav(members.interfaces, 'Interfaces', seen, linkto); - // nav += buildMemberNav(members.events, 'Events', seen, linkto); - // nav += buildMemberNav(members.mixins, 'Mixins', seen, linkto); - // nav += buildMemberNav(members.tutorials, 'Tutorials', seenTutorials, linktoTutorial); - - // if (members.globals.length) { - // globalNav = ''; - - // members.globals.forEach(({kind, longname, name}) => { - // if ( kind !== 'typedef' && !hasOwnProp.call(seen, longname) ) { - // globalNav += `
  • ${linkto(longname, name)}
    • `; - // } - // seen[longname] = true; - // }); - - // if (!globalNav) { - // // turn the heading into a link so you can actually get to the global page - // nav += `

    ${linkto('global', 'Global')}

    `; - // } - // else { - // nav += `

    Global

      ${globalNav}
    `; - // } - // } - - return nav; -} - -/** - @param {object} memberData - @param {object} opts - @param {Tutorial} tutorials - */ -exports.publish = (memberData, opts, tutorials) => { - let classes; - let conf; - let externals; - let files; - let fromDir; - let globalUrl; - let indexUrl; - let interfaces; - let members; - let mixins; - let modules; - let namespaces; - let outputSourceFiles; - let packageInfo; - let packages; - const sourceFilePaths = []; - let sourceFiles = {}; - let staticFileFilter; - let staticFilePaths; - let staticFiles; - let staticFileScanner; - let templatePath; - - data = memberData; - - conf = env.conf.templates || {}; - conf.default = conf.default || {}; - - templatePath = path.normalize(opts.template); - view = new template.Template( path.join(templatePath, 'tmpl') ); - - // claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness - // doesn't try to hand them out later - indexUrl = helper.getUniqueFilename('index'); - // don't call registerLink() on this one! 'index' is also a valid longname - - globalUrl = helper.getUniqueFilename('global'); - helper.registerLink('global', globalUrl); - - // set up templating - view.layout = conf.default.layoutFile ? - path.getResourcePath(path.dirname(conf.default.layoutFile), - path.basename(conf.default.layoutFile) ) : - 'layout.tmpl'; - - // set up tutorials for helper - helper.setTutorials(tutorials); - - data = helper.prune(data); - data.sort('longname, version, since'); - helper.addEventListeners(data); - - data().each(doclet => { - let sourcePath; - - doclet.attribs = ''; - - if (doclet.examples) { - doclet.examples = doclet.examples.map(example => { - let caption; - let code; - - if (example.match(/^\s*([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) { - caption = RegExp.$1; - code = RegExp.$3; - } - - return { - caption: caption || '', - code: code || example - }; - }); - } - if (doclet.see) { - doclet.see.forEach((seeItem, i) => { - doclet.see[i] = hashToLink(doclet, seeItem); - }); - } - - // build a list of source files - if (doclet.meta) { - sourcePath = getPathFromDoclet(doclet); - sourceFiles[sourcePath] = { - resolved: sourcePath, - shortened: null - }; - if (!sourceFilePaths.includes(sourcePath)) { - sourceFilePaths.push(sourcePath); - } - } - }); - - // update outdir if necessary, then create outdir - packageInfo = ( find({kind: 'package'}) || [] )[0]; - if (packageInfo && packageInfo.name) { - outdir = path.join( outdir, packageInfo.name, (packageInfo.version || '') ); - } - fs.mkPath(outdir); - - // copy the template's static files to outdir - fromDir = path.join(templatePath, 'static'); - staticFiles = fs.ls(fromDir, 3); - - staticFiles.forEach(fileName => { - const toDir = fs.toDir( fileName.replace(fromDir, outdir) ); - - fs.mkPath(toDir); - fs.copyFileSync(fileName, toDir); - }); - - // copy user-specified static files to outdir - if (conf.default.staticFiles) { - // The canonical property name is `include`. We accept `paths` for backwards compatibility - // with a bug in JSDoc 3.2.x. - staticFilePaths = conf.default.staticFiles.include || - conf.default.staticFiles.paths || - []; - staticFileFilter = new (require('jsdoc/src/filter').Filter)(conf.default.staticFiles); - staticFileScanner = new (require('jsdoc/src/scanner').Scanner)(); - - staticFilePaths.forEach(filePath => { - let extraStaticFiles; - - filePath = path.resolve(env.pwd, filePath); - extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter); - - extraStaticFiles.forEach(fileName => { - const sourcePath = fs.toDir(filePath); - const toDir = fs.toDir( fileName.replace(sourcePath, outdir) ); - - fs.mkPath(toDir); - fs.copyFileSync(fileName, toDir); - }); - }); - } - - if (sourceFilePaths.length) { - sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) ); - } - data().each(doclet => { - let docletPath; - const url = helper.createLink(doclet); - - helper.registerLink(doclet.longname, url); - - // add a shortened version of the full path - if (doclet.meta) { - docletPath = getPathFromDoclet(doclet); - docletPath = sourceFiles[docletPath].shortened; - if (docletPath) { - doclet.meta.shortpath = docletPath; - } - } - }); - - data().each(doclet => { - const url = helper.longnameToUrl[doclet.longname]; - - if (url.includes('#')) { - doclet.id = helper.longnameToUrl[doclet.longname].split(/#/).pop(); - } - else { - doclet.id = doclet.name; - } - - if ( needsSignature(doclet) ) { - addSignatureParams(doclet); - addSignatureReturns(doclet); - addAttribs(doclet); - } - }); - - // do this after the urls have all been generated - data().each(doclet => { - doclet.ancestors = getAncestorLinks(doclet); - - if (doclet.kind === 'member') { - addSignatureTypes(doclet); - addAttribs(doclet); - } - - if (doclet.kind === 'constant') { - addSignatureTypes(doclet); - addAttribs(doclet); - doclet.kind = 'member'; - } - }); - - members = helper.getMembers(data); - - members.modules = members.modules.map(module => { - module.children = data({ memberof: `module:${module.name}`}).get(); - return module; - }) - - members.tutorials = tutorials.children; - - // output pretty-printed source files by default - outputSourceFiles = conf.default && conf.default.outputSourceFiles !== false; - - // add template helpers - view.find = find; - view.linkto = linkto; - view.resolveAuthorLinks = resolveAuthorLinks; - view.tutoriallink = tutoriallink; - view.htmlsafe = htmlsafe; - view.outputSourceFiles = outputSourceFiles; - - // once for all - view.nav = buildNav(members); - attachModuleSymbols( find({ longname: {left: 'module:'} }), members.modules ); - - // generate the pretty-printed source files first so other pages can link to them - if (outputSourceFiles) { - generateSourceFiles(sourceFiles, opts.encoding); - } - - // if (members.globals.length) { generate('Global', [{kind: 'globalobj'}], globalUrl); } - - // index page displays information from package.json and lists files - files = find({kind: 'file'}); - packages = find({kind: 'package'}); - - generate('Open edX frontend-platform API Documentation', - packages.concat( - [{ - kind: 'mainpage', - readme: opts.readme, - longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page' - }] - ).concat(files), indexUrl); - - Object.keys(helper.longnameToUrl).forEach(longname => { - const myClasses = members.classes.filter(obj => obj.longname === longname); - const myExternals = members.externals.filter(obj => obj.longname === longname); - const myInterfaces = members.interfaces.filter(obj => obj.longname === longname); - const myMixins = members.mixins.filter(obj => obj.longname === longname); - const myModules = members.modules.filter(obj => obj.longname === longname); - const myNamespaces = members.namespaces.filter(obj => obj.longname === longname); - - const trimModuleName = (moduleName) => { - if (moduleName.includes('module:')) { - return moduleName.split(':')[1]; - } - return moduleName; - } - - if (myModules.length) { - generate(`${myModules[0].name}`, myModules, helper.longnameToUrl[longname], { moduleName: myModules[0].name }); - } - - if (myClasses.length) { - generate(`Class: ${myClasses[0].name}`, myClasses, helper.longnameToUrl[longname], { moduleName: trimModuleName(myClasses[0].memberof) }); - } - - if (myNamespaces.length) { - generate(`Namespace: ${myNamespaces[0].name}`, myNamespaces, helper.longnameToUrl[longname], { moduleName: trimModuleName(myNamespaces[0].memberof) }); - } - - if (myMixins.length) { - generate(`Mixin: ${myMixins[0].name}`, myMixins, helper.longnameToUrl[longname], { moduleName: trimModuleName(myMixins[0].memberof) }); - } - - if (myExternals.length) { - generate(`External: ${myExternals[0].name}`, myExternals, helper.longnameToUrl[longname], { moduleName: trimModuleName(myExternals[0].memberof) }); - } - - if (myInterfaces.length) { - generate(`Interface: ${myInterfaces[0].name}`, myInterfaces, helper.longnameToUrl[longname], { moduleName: trimModuleName(myInterfaces[0].memberof) }); - } - }); - - // TODO: move the tutorial functions to templateHelper.js - function generateTutorial(title, tutorial, filename) { - const tutorialData = { - title: title, - header: tutorial.title, - content: tutorial.parse(), - children: tutorial.children - }; - const tutorialPath = path.join(outdir, filename); - let html = view.render('tutorial.tmpl', tutorialData); - - // yes, you can use {@link} in tutorials too! - html = helper.resolveLinks(html); // turn {@link foo} into foo - - fs.writeFileSync(tutorialPath, html, 'utf8'); - } - - // tutorials can have only one parent so there is no risk for loops - function saveChildren({children}) { - children.forEach(child => { - generateTutorial(`Tutorial: ${child.title}`, child, helper.tutorialToUrl(child.name)); - saveChildren(child); - }); - } - - saveChildren(tutorials); -}; diff --git a/docs/template/edx/static/fonts/OpenSans-Bold-webfont.eot b/docs/template/edx/static/fonts/OpenSans-Bold-webfont.eot deleted file mode 100644 index 5d20d9163..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Bold-webfont.eot and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-Bold-webfont.svg b/docs/template/edx/static/fonts/OpenSans-Bold-webfont.svg deleted file mode 100644 index 3ed7be4bc..000000000 --- a/docs/template/edx/static/fonts/OpenSans-Bold-webfont.svg +++ /dev/null @@ -1,1830 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/template/edx/static/fonts/OpenSans-Bold-webfont.woff b/docs/template/edx/static/fonts/OpenSans-Bold-webfont.woff deleted file mode 100644 index 1205787b0..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Bold-webfont.woff and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.eot b/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.eot deleted file mode 100644 index 1f639a15f..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.eot and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.svg b/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.svg deleted file mode 100644 index 6a2607b9d..000000000 --- a/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.svg +++ /dev/null @@ -1,1830 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.woff b/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.woff deleted file mode 100644 index ed760c062..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-BoldItalic-webfont.woff and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-Italic-webfont.eot b/docs/template/edx/static/fonts/OpenSans-Italic-webfont.eot deleted file mode 100644 index 0c8a0ae06..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Italic-webfont.eot and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-Italic-webfont.svg b/docs/template/edx/static/fonts/OpenSans-Italic-webfont.svg deleted file mode 100644 index e1075dcc2..000000000 --- a/docs/template/edx/static/fonts/OpenSans-Italic-webfont.svg +++ /dev/null @@ -1,1830 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/template/edx/static/fonts/OpenSans-Italic-webfont.woff b/docs/template/edx/static/fonts/OpenSans-Italic-webfont.woff deleted file mode 100644 index ff652e643..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Italic-webfont.woff and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-Light-webfont.eot b/docs/template/edx/static/fonts/OpenSans-Light-webfont.eot deleted file mode 100644 index 14868406a..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Light-webfont.eot and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-Light-webfont.svg b/docs/template/edx/static/fonts/OpenSans-Light-webfont.svg deleted file mode 100644 index 11a472ca8..000000000 --- a/docs/template/edx/static/fonts/OpenSans-Light-webfont.svg +++ /dev/null @@ -1,1831 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/template/edx/static/fonts/OpenSans-Light-webfont.woff b/docs/template/edx/static/fonts/OpenSans-Light-webfont.woff deleted file mode 100644 index e78607481..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Light-webfont.woff and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.eot b/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.eot deleted file mode 100644 index 8f445929f..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.eot and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.svg b/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.svg deleted file mode 100644 index 431d7e354..000000000 --- a/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.svg +++ /dev/null @@ -1,1835 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.woff b/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.woff deleted file mode 100644 index 43e8b9e6c..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-LightItalic-webfont.woff and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-Regular-webfont.eot b/docs/template/edx/static/fonts/OpenSans-Regular-webfont.eot deleted file mode 100644 index 6bbc3cf58..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Regular-webfont.eot and /dev/null differ diff --git a/docs/template/edx/static/fonts/OpenSans-Regular-webfont.svg b/docs/template/edx/static/fonts/OpenSans-Regular-webfont.svg deleted file mode 100644 index 25a395234..000000000 --- a/docs/template/edx/static/fonts/OpenSans-Regular-webfont.svg +++ /dev/null @@ -1,1831 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/template/edx/static/fonts/OpenSans-Regular-webfont.woff b/docs/template/edx/static/fonts/OpenSans-Regular-webfont.woff deleted file mode 100644 index e231183dc..000000000 Binary files a/docs/template/edx/static/fonts/OpenSans-Regular-webfont.woff and /dev/null differ diff --git a/docs/template/edx/static/scripts/linenumber.js b/docs/template/edx/static/scripts/linenumber.js deleted file mode 100644 index 4354785ce..000000000 --- a/docs/template/edx/static/scripts/linenumber.js +++ /dev/null @@ -1,25 +0,0 @@ -/*global document */ -(() => { - const source = document.getElementsByClassName('prettyprint source linenums'); - let i = 0; - let lineNumber = 0; - let lineId; - let lines; - let totalLines; - let anchorHash; - - if (source && source[0]) { - anchorHash = document.location.hash.substring(1); - lines = source[0].getElementsByTagName('li'); - totalLines = lines.length; - - for (; i < totalLines; i++) { - lineNumber++; - lineId = `line${lineNumber}`; - lines[i].id = lineId; - if (lineId === anchorHash) { - lines[i].className += ' selected'; - } - } - } -})(); diff --git a/docs/template/edx/static/scripts/prettify/Apache-License-2.0.txt b/docs/template/edx/static/scripts/prettify/Apache-License-2.0.txt deleted file mode 100644 index d64569567..000000000 --- a/docs/template/edx/static/scripts/prettify/Apache-License-2.0.txt +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/docs/template/edx/static/scripts/prettify/lang-css.js b/docs/template/edx/static/scripts/prettify/lang-css.js deleted file mode 100644 index 041e1f590..000000000 --- a/docs/template/edx/static/scripts/prettify/lang-css.js +++ /dev/null @@ -1,2 +0,0 @@ -PR.registerLangHandler(PR.createSimpleLexer([["pln",/^[\t\n\f\r ]+/,null," \t\r\n "]],[["str",/^"(?:[^\n\f\r"\\]|\\(?:\r\n?|\n|\f)|\\[\S\s])*"/,null],["str",/^'(?:[^\n\f\r'\\]|\\(?:\r\n?|\n|\f)|\\[\S\s])*'/,null],["lang-css-str",/^url\(([^"')]*)\)/i],["kwd",/^(?:url|rgb|!important|@import|@page|@media|@charset|inherit)(?=[^\w-]|$)/i,null],["lang-css-kw",/^(-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*)\s*:/i],["com",/^\/\*[^*]*\*+(?:[^*/][^*]*\*+)*\//],["com", -/^(?:<\!--|--\>)/],["lit",/^(?:\d+|\d*\.\d+)(?:%|[a-z]+)?/i],["lit",/^#[\da-f]{3,6}/i],["pln",/^-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*/i],["pun",/^[^\s\w"']+/]]),["css"]);PR.registerLangHandler(PR.createSimpleLexer([],[["kwd",/^-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*/i]]),["css-kw"]);PR.registerLangHandler(PR.createSimpleLexer([],[["str",/^[^"')]+/]]),["css-str"]); diff --git a/docs/template/edx/static/scripts/prettify/prettify.js b/docs/template/edx/static/scripts/prettify/prettify.js deleted file mode 100644 index eef5ad7e6..000000000 --- a/docs/template/edx/static/scripts/prettify/prettify.js +++ /dev/null @@ -1,28 +0,0 @@ -var q=null;window.PR_SHOULD_USE_CONTINUATION=!0; -(function(){function L(a){function m(a){var f=a.charCodeAt(0);if(f!==92)return f;var b=a.charAt(1);return(f=r[b])?f:"0"<=b&&b<="7"?parseInt(a.substring(1),8):b==="u"||b==="x"?parseInt(a.substring(2),16):a.charCodeAt(1)}function e(a){if(a<32)return(a<16?"\\x0":"\\x")+a.toString(16);a=String.fromCharCode(a);if(a==="\\"||a==="-"||a==="["||a==="]")a="\\"+a;return a}function h(a){for(var f=a.substring(1,a.length-1).match(/\\u[\dA-Fa-f]{4}|\\x[\dA-Fa-f]{2}|\\[0-3][0-7]{0,2}|\\[0-7]{1,2}|\\[\S\s]|[^\\]/g),a= -[],b=[],o=f[0]==="^",c=o?1:0,i=f.length;c122||(d<65||j>90||b.push([Math.max(65,j)|32,Math.min(d,90)|32]),d<97||j>122||b.push([Math.max(97,j)&-33,Math.min(d,122)&-33]))}}b.sort(function(a,f){return a[0]-f[0]||f[1]-a[1]});f=[];j=[NaN,NaN];for(c=0;ci[0]&&(i[1]+1>i[0]&&b.push("-"),b.push(e(i[1])));b.push("]");return b.join("")}function y(a){for(var f=a.source.match(/\[(?:[^\\\]]|\\[\S\s])*]|\\u[\dA-Fa-f]{4}|\\x[\dA-Fa-f]{2}|\\\d+|\\[^\dux]|\(\?[!:=]|[()^]|[^()[\\^]+/g),b=f.length,d=[],c=0,i=0;c=2&&a==="["?f[c]=h(j):a!=="\\"&&(f[c]=j.replace(/[A-Za-z]/g,function(a){a=a.charCodeAt(0);return"["+String.fromCharCode(a&-33,a|32)+"]"}));return f.join("")}for(var t=0,s=!1,l=!1,p=0,d=a.length;p=5&&"lang-"===b.substring(0,5))&&!(o&&typeof o[1]==="string"))c=!1,b="src";c||(r[f]=b)}i=d;d+=f.length;if(c){c=o[1];var j=f.indexOf(c),k=j+c.length;o[2]&&(k=f.length-o[2].length,j=k-c.length);b=b.substring(5);B(l+i,f.substring(0,j),e,p);B(l+i+j,c,C(b,c),p);B(l+i+k,f.substring(k),e,p)}else p.push(l+i,b)}a.e=p}var h={},y;(function(){for(var e=a.concat(m), -l=[],p={},d=0,g=e.length;d=0;)h[n.charAt(k)]=r;r=r[1];n=""+r;p.hasOwnProperty(n)||(l.push(r),p[n]=q)}l.push(/[\S\s]/);y=L(l)})();var t=m.length;return e}function u(a){var m=[],e=[];a.tripleQuotedStrings?m.push(["str",/^(?:'''(?:[^'\\]|\\[\S\s]|''?(?=[^']))*(?:'''|$)|"""(?:[^"\\]|\\[\S\s]|""?(?=[^"]))*(?:"""|$)|'(?:[^'\\]|\\[\S\s])*(?:'|$)|"(?:[^"\\]|\\[\S\s])*(?:"|$))/,q,"'\""]):a.multiLineStrings?m.push(["str",/^(?:'(?:[^'\\]|\\[\S\s])*(?:'|$)|"(?:[^"\\]|\\[\S\s])*(?:"|$)|`(?:[^\\`]|\\[\S\s])*(?:`|$))/, -q,"'\"`"]):m.push(["str",/^(?:'(?:[^\n\r'\\]|\\.)*(?:'|$)|"(?:[^\n\r"\\]|\\.)*(?:"|$))/,q,"\"'"]);a.verbatimStrings&&e.push(["str",/^@"(?:[^"]|"")*(?:"|$)/,q]);var h=a.hashComments;h&&(a.cStyleComments?(h>1?m.push(["com",/^#(?:##(?:[^#]|#(?!##))*(?:###|$)|.*)/,q,"#"]):m.push(["com",/^#(?:(?:define|elif|else|endif|error|ifdef|include|ifndef|line|pragma|undef|warning)\b|[^\n\r]*)/,q,"#"]),e.push(["str",/^<(?:(?:(?:\.\.\/)*|\/?)(?:[\w-]+(?:\/[\w-]+)+)?[\w-]+\.h|[a-z]\w*)>/,q])):m.push(["com",/^#[^\n\r]*/, -q,"#"]));a.cStyleComments&&(e.push(["com",/^\/\/[^\n\r]*/,q]),e.push(["com",/^\/\*[\S\s]*?(?:\*\/|$)/,q]));a.regexLiterals&&e.push(["lang-regex",/^(?:^^\.?|[!+-]|!=|!==|#|%|%=|&|&&|&&=|&=|\(|\*|\*=|\+=|,|-=|->|\/|\/=|:|::|;|<|<<|<<=|<=|=|==|===|>|>=|>>|>>=|>>>|>>>=|[?@[^]|\^=|\^\^|\^\^=|{|\||\|=|\|\||\|\|=|~|break|case|continue|delete|do|else|finally|instanceof|return|throw|try|typeof)\s*(\/(?=[^*/])(?:[^/[\\]|\\[\S\s]|\[(?:[^\\\]]|\\[\S\s])*(?:]|$))+\/)/]);(h=a.types)&&e.push(["typ",h]);a=(""+a.keywords).replace(/^ | $/g, -"");a.length&&e.push(["kwd",RegExp("^(?:"+a.replace(/[\s,]+/g,"|")+")\\b"),q]);m.push(["pln",/^\s+/,q," \r\n\t\xa0"]);e.push(["lit",/^@[$_a-z][\w$@]*/i,q],["typ",/^(?:[@_]?[A-Z]+[a-z][\w$@]*|\w+_t\b)/,q],["pln",/^[$_a-z][\w$@]*/i,q],["lit",/^(?:0x[\da-f]+|(?:\d(?:_\d+)*\d*(?:\.\d*)?|\.\d\+)(?:e[+-]?\d+)?)[a-z]*/i,q,"0123456789"],["pln",/^\\[\S\s]?/,q],["pun",/^.[^\s\w"-$'./@\\`]*/,q]);return x(m,e)}function D(a,m){function e(a){switch(a.nodeType){case 1:if(k.test(a.className))break;if("BR"===a.nodeName)h(a), -a.parentNode&&a.parentNode.removeChild(a);else for(a=a.firstChild;a;a=a.nextSibling)e(a);break;case 3:case 4:if(p){var b=a.nodeValue,d=b.match(t);if(d){var c=b.substring(0,d.index);a.nodeValue=c;(b=b.substring(d.index+d[0].length))&&a.parentNode.insertBefore(s.createTextNode(b),a.nextSibling);h(a);c||a.parentNode.removeChild(a)}}}}function h(a){function b(a,d){var e=d?a.cloneNode(!1):a,f=a.parentNode;if(f){var f=b(f,1),g=a.nextSibling;f.appendChild(e);for(var h=g;h;h=g)g=h.nextSibling,f.appendChild(h)}return e} -for(;!a.nextSibling;)if(a=a.parentNode,!a)return;for(var a=b(a.nextSibling,0),e;(e=a.parentNode)&&e.nodeType===1;)a=e;d.push(a)}var k=/(?:^|\s)nocode(?:\s|$)/,t=/\r\n?|\n/,s=a.ownerDocument,l;a.currentStyle?l=a.currentStyle.whiteSpace:window.getComputedStyle&&(l=s.defaultView.getComputedStyle(a,q).getPropertyValue("white-space"));var p=l&&"pre"===l.substring(0,3);for(l=s.createElement("LI");a.firstChild;)l.appendChild(a.firstChild);for(var d=[l],g=0;g=0;){var h=m[e];A.hasOwnProperty(h)?window.console&&console.warn("cannot override language handler %s",h):A[h]=a}}function C(a,m){if(!a||!A.hasOwnProperty(a))a=/^\s*=o&&(h+=2);e>=c&&(a+=2)}}catch(w){"console"in window&&console.log(w&&w.stack?w.stack:w)}}var v=["break,continue,do,else,for,if,return,while"],w=[[v,"auto,case,char,const,default,double,enum,extern,float,goto,int,long,register,short,signed,sizeof,static,struct,switch,typedef,union,unsigned,void,volatile"], -"catch,class,delete,false,import,new,operator,private,protected,public,this,throw,true,try,typeof"],F=[w,"alignof,align_union,asm,axiom,bool,concept,concept_map,const_cast,constexpr,decltype,dynamic_cast,explicit,export,friend,inline,late_check,mutable,namespace,nullptr,reinterpret_cast,static_assert,static_cast,template,typeid,typename,using,virtual,where"],G=[w,"abstract,boolean,byte,extends,final,finally,implements,import,instanceof,null,native,package,strictfp,super,synchronized,throws,transient"], -H=[G,"as,base,by,checked,decimal,delegate,descending,dynamic,event,fixed,foreach,from,group,implicit,in,interface,internal,into,is,lock,object,out,override,orderby,params,partial,readonly,ref,sbyte,sealed,stackalloc,string,select,uint,ulong,unchecked,unsafe,ushort,var"],w=[w,"debugger,eval,export,function,get,null,set,undefined,var,with,Infinity,NaN"],I=[v,"and,as,assert,class,def,del,elif,except,exec,finally,from,global,import,in,is,lambda,nonlocal,not,or,pass,print,raise,try,with,yield,False,True,None"], -J=[v,"alias,and,begin,case,class,def,defined,elsif,end,ensure,false,in,module,next,nil,not,or,redo,rescue,retry,self,super,then,true,undef,unless,until,when,yield,BEGIN,END"],v=[v,"case,done,elif,esac,eval,fi,function,in,local,set,then,until"],K=/^(DIR|FILE|vector|(de|priority_)?queue|list|stack|(const_)?iterator|(multi)?(set|map)|bitset|u?(int|float)\d*)/,N=/\S/,O=u({keywords:[F,H,w,"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END"+ -I,J,v],hashComments:!0,cStyleComments:!0,multiLineStrings:!0,regexLiterals:!0}),A={};k(O,["default-code"]);k(x([],[["pln",/^[^]*(?:>|$)/],["com",/^<\!--[\S\s]*?(?:--\>|$)/],["lang-",/^<\?([\S\s]+?)(?:\?>|$)/],["lang-",/^<%([\S\s]+?)(?:%>|$)/],["pun",/^(?:<[%?]|[%?]>)/],["lang-",/^]*>([\S\s]+?)<\/xmp\b[^>]*>/i],["lang-js",/^]*>([\S\s]*?)(<\/script\b[^>]*>)/i],["lang-css",/^]*>([\S\s]*?)(<\/style\b[^>]*>)/i],["lang-in.tag",/^(<\/?[a-z][^<>]*>)/i]]), -["default-markup","htm","html","mxml","xhtml","xml","xsl"]);k(x([["pln",/^\s+/,q," \t\r\n"],["atv",/^(?:"[^"]*"?|'[^']*'?)/,q,"\"'"]],[["tag",/^^<\/?[a-z](?:[\w-.:]*\w)?|\/?>$/i],["atn",/^(?!style[\s=]|on)[a-z](?:[\w:-]*\w)?/i],["lang-uq.val",/^=\s*([^\s"'>]*(?:[^\s"'/>]|\/(?=\s)))/],["pun",/^[/<->]+/],["lang-js",/^on\w+\s*=\s*"([^"]+)"/i],["lang-js",/^on\w+\s*=\s*'([^']+)'/i],["lang-js",/^on\w+\s*=\s*([^\s"'>]+)/i],["lang-css",/^style\s*=\s*"([^"]+)"/i],["lang-css",/^style\s*=\s*'([^']+)'/i],["lang-css", -/^style\s*=\s*([^\s"'>]+)/i]]),["in.tag"]);k(x([],[["atv",/^[\S\s]+/]]),["uq.val"]);k(u({keywords:F,hashComments:!0,cStyleComments:!0,types:K}),["c","cc","cpp","cxx","cyc","m"]);k(u({keywords:"null,true,false"}),["json"]);k(u({keywords:H,hashComments:!0,cStyleComments:!0,verbatimStrings:!0,types:K}),["cs"]);k(u({keywords:G,cStyleComments:!0}),["java"]);k(u({keywords:v,hashComments:!0,multiLineStrings:!0}),["bsh","csh","sh"]);k(u({keywords:I,hashComments:!0,multiLineStrings:!0,tripleQuotedStrings:!0}), -["cv","py"]);k(u({keywords:"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END",hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["perl","pl","pm"]);k(u({keywords:J,hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["rb"]);k(u({keywords:w,cStyleComments:!0,regexLiterals:!0}),["js"]);k(u({keywords:"all,and,by,catch,class,else,extends,false,finally,for,if,in,is,isnt,loop,new,no,not,null,of,off,on,or,return,super,then,true,try,unless,until,when,while,yes", -hashComments:3,cStyleComments:!0,multilineStrings:!0,tripleQuotedStrings:!0,regexLiterals:!0}),["coffee"]);k(x([],[["str",/^[\S\s]+/]]),["regex"]);window.prettyPrintOne=function(a,m,e){var h=document.createElement("PRE");h.innerHTML=a;e&&D(h,e);E({g:m,i:e,h:h});return h.innerHTML};window.prettyPrint=function(a){function m(){for(var e=window.PR_SHOULD_USE_CONTINUATION?l.now()+250:Infinity;p=0){var k=k.match(g),f,b;if(b= -!k){b=n;for(var o=void 0,c=b.firstChild;c;c=c.nextSibling)var i=c.nodeType,o=i===1?o?b:c:i===3?N.test(c.nodeValue)?b:o:o;b=(f=o===b?void 0:o)&&"CODE"===f.tagName}b&&(k=f.className.match(g));k&&(k=k[1]);b=!1;for(o=n.parentNode;o;o=o.parentNode)if((o.tagName==="pre"||o.tagName==="code"||o.tagName==="xmp")&&o.className&&o.className.indexOf("prettyprint")>=0){b=!0;break}b||((b=(b=n.className.match(/\blinenums\b(?::(\d+))?/))?b[1]&&b[1].length?+b[1]:!0:!1)&&D(n,b),d={g:k,h:n,i:b},E(d))}}p a, -[data-module="Auth"] .module-section.Auth > a, -[data-module="Config"] .module-section.Config > a, -[data-module="Initialization"] .module-section.Initialization > a, -[data-module="Internationalization"] .module-section.Internationalization > a, -[data-module="Logging"] .module-section.Logging > a, -[data-module="PubSub"] .module-section.PubSub > a, -[data-module="React"] .module-section.React > a, -[data-module="Utilities"] .module-section.Utilities > a { - color: #333; - background: #f8f9fa; -} - -.variation { - display: none; -} - -.signature-attributes { - font-size: 60%; - color: #aaa; - font-style: italic; - font-weight: lighter; -} - -nav -{ - display: block; - background: white; - position: fixed; - top: 0; - bottom: 0; - left: 0;; - padding-top: 28px; - width: 300px; - box-sizing: border-box; - border-right: 1px solid #ddd; - overflow: auto;; -} -nav h2 { - padding-left: 1rem; -} - -footer { - display: block; - padding: 6px; - margin-top: 12px; - font-style: italic; - font-size: 90%; -} - -h1, h2, h3, h4 { - font-weight: 200; - margin: 0; -} - -h1 -{ - font-family: 'Open Sans Light', sans-serif; - font-size: 48px; - letter-spacing: -2px; - margin: 12px 24px 20px; -} - -article h1 { - margin: 12px 24px 20px 0px; -} - -h2, h3.subsection-title -{ - font-size: 30px; - font-weight: 700; - letter-spacing: -1px; - margin-bottom: 12px; -} - -h3 -{ - font-size: 24px; - letter-spacing: -0.5px; - margin-bottom: 12px; -} - -h4 -{ - font-size: 18px; - letter-spacing: -0.33px; - margin-bottom: 12px; - color: #4d4e53; -} - -h5, .container-overview .subsection-title -{ - font-size: 120%; - font-weight: bold; - letter-spacing: -0.01em; - margin: 8px 0 3px 0; -} - -h6 -{ - font-size: 100%; - letter-spacing: -0.01em; - margin: 6px 0 3px 0; - font-style: italic; -} - -table -{ - border-spacing: 0; - border: 0; - border-collapse: collapse; -} - -td, th -{ - border: 1px solid #ddd; - margin: 0px; - text-align: left; - vertical-align: top; - padding: 4px 6px; - display: table-cell; -} - -thead tr -{ - background-color: #ddd; - font-weight: bold; -} - -th { border-right: 1px solid #aaa; } -tr > th:last-child { border-right: 1px solid #ddd; } - -.ancestors, .attribs { color: #999; } -.ancestors a, .attribs a -{ - color: #999 !important; - text-decoration: none; -} - -.clear -{ - clear: both; -} - -.important -{ - font-weight: bold; - color: #950B02; -} - -.yes-def { - text-indent: -1000px; -} - -.type-signature { - color: #aaa; -} - -.name, .signature { - font-family: monospace; -} - -.details { margin-top: 14px; border-left: 2px solid #DDD; } -.details dt { width: 120px; float: left; padding-left: 10px; padding-top: 6px; } -.details dd { margin-left: 70px; } -.details ul { margin: 0; } -.details ul { list-style-type: none; } -.details li { margin-left: 30px; padding-top: 6px; } -.details pre.prettyprint { margin: 0 } -.details .object-value { padding-top: 0; } - -.description { - margin-bottom: 1em; - margin-top: 1em; -} - -.code-caption -{ - font-style: italic; - font-size: 107%; - margin: 0; -} - -.source -{ - border: 1px solid #ddd; - width: 80%; - overflow: auto; -} - -.prettyprint.source { - width: inherit; -} - -.source code -{ - font-size: 100%; - line-height: 18px; - display: block; - padding: 4px 12px; - margin: 0; - background-color: #fff; - color: #4D4E53; -} - -.prettyprint code span.line -{ - display: inline-block; -} - -.prettyprint.linenums -{ - padding-left: 70px; - -webkit-user-select: none; - -moz-user-select: none; - -ms-user-select: none; - user-select: none; -} - -.prettyprint.linenums ol -{ - padding-left: 0; -} - -.prettyprint.linenums li -{ - border-left: 3px #ddd solid; -} - -.prettyprint.linenums li.selected, -.prettyprint.linenums li.selected * -{ - background-color: lightyellow; -} - -.prettyprint.linenums li * -{ - -webkit-user-select: text; - -moz-user-select: text; - -ms-user-select: text; - user-select: text; -} - -.params .name, .props .name, .name code { - color: #4D4E53; - font-family: monospace; - font-size: 100%; -} - -.params td.description > p:first-child, -.props td.description > p:first-child -{ - margin-top: 0; - padding-top: 0; -} - -.params td.description > p:last-child, -.props td.description > p:last-child -{ - margin-bottom: 0; - padding-bottom: 0; -} - -.disabled { - color: #454545; -} diff --git a/docs/template/edx/static/styles/prettify-jsdoc.css b/docs/template/edx/static/styles/prettify-jsdoc.css deleted file mode 100644 index 5a2526e37..000000000 --- a/docs/template/edx/static/styles/prettify-jsdoc.css +++ /dev/null @@ -1,111 +0,0 @@ -/* JSDoc prettify.js theme */ - -/* plain text */ -.pln { - color: #000000; - font-weight: normal; - font-style: normal; -} - -/* string content */ -.str { - color: #006400; - font-weight: normal; - font-style: normal; -} - -/* a keyword */ -.kwd { - color: #000000; - font-weight: bold; - font-style: normal; -} - -/* a comment */ -.com { - font-weight: normal; - font-style: italic; -} - -/* a type name */ -.typ { - color: #000000; - font-weight: normal; - font-style: normal; -} - -/* a literal value */ -.lit { - color: #006400; - font-weight: normal; - font-style: normal; -} - -/* punctuation */ -.pun { - color: #000000; - font-weight: bold; - font-style: normal; -} - -/* lisp open bracket */ -.opn { - color: #000000; - font-weight: bold; - font-style: normal; -} - -/* lisp close bracket */ -.clo { - color: #000000; - font-weight: bold; - font-style: normal; -} - -/* a markup tag name */ -.tag { - color: #006400; - font-weight: normal; - font-style: normal; -} - -/* a markup attribute name */ -.atn { - color: #006400; - font-weight: normal; - font-style: normal; -} - -/* a markup attribute value */ -.atv { - color: #006400; - font-weight: normal; - font-style: normal; -} - -/* a declaration */ -.dec { - color: #000000; - font-weight: bold; - font-style: normal; -} - -/* a variable name */ -.var { - color: #000000; - font-weight: normal; - font-style: normal; -} - -/* a function name */ -.fun { - color: #000000; - font-weight: bold; - font-style: normal; -} - -/* Specify class=linenums on a pre to get line numbering */ -ol.linenums { - margin-top: 0; - margin-bottom: 0; -} diff --git a/docs/template/edx/static/styles/prettify-tomorrow.css b/docs/template/edx/static/styles/prettify-tomorrow.css deleted file mode 100644 index b6f92a78d..000000000 --- a/docs/template/edx/static/styles/prettify-tomorrow.css +++ /dev/null @@ -1,132 +0,0 @@ -/* Tomorrow Theme */ -/* Original theme - https://github.com/chriskempson/tomorrow-theme */ -/* Pretty printing styles. Used with prettify.js. */ -/* SPAN elements with the classes below are added by prettyprint. */ -/* plain text */ -.pln { - color: #4d4d4c; } - -@media screen { - /* string content */ - .str { - color: #718c00; } - - /* a keyword */ - .kwd { - color: #8959a8; } - - /* a comment */ - .com { - color: #8e908c; } - - /* a type name */ - .typ { - color: #4271ae; } - - /* a literal value */ - .lit { - color: #f5871f; } - - /* punctuation */ - .pun { - color: #4d4d4c; } - - /* lisp open bracket */ - .opn { - color: #4d4d4c; } - - /* lisp close bracket */ - .clo { - color: #4d4d4c; } - - /* a markup tag name */ - .tag { - color: #c82829; } - - /* a markup attribute name */ - .atn { - color: #f5871f; } - - /* a markup attribute value */ - .atv { - color: #3e999f; } - - /* a declaration */ - .dec { - color: #f5871f; } - - /* a variable name */ - .var { - color: #c82829; } - - /* a function name */ - .fun { - color: #4271ae; } } -/* Use higher contrast and text-weight for printable form. */ -@media print, projection { - .str { - color: #060; } - - .kwd { - color: #006; - font-weight: bold; } - - .com { - color: #600; - font-style: italic; } - - .typ { - color: #404; - font-weight: bold; } - - .lit { - color: #044; } - - .pun, .opn, .clo { - color: #440; } - - .tag { - color: #006; - font-weight: bold; } - - .atn { - color: #404; } - - .atv { - color: #060; } } -/* Style */ -/* -pre.prettyprint { - background: white; - font-family: Consolas, Monaco, 'Andale Mono', monospace; - font-size: 12px; - line-height: 1.5; - border: 1px solid #ccc; - padding: 10px; } -*/ - -/* Specify class=linenums on a pre to get line numbering */ -ol.linenums { - margin-top: 0; - margin-bottom: 0; } - -/* IE indents via margin-left */ -li.L0, -li.L1, -li.L2, -li.L3, -li.L4, -li.L5, -li.L6, -li.L7, -li.L8, -li.L9 { - /* */ } - -/* Alternate shading for lines */ -li.L1, -li.L3, -li.L5, -li.L7, -li.L9 { - /* */ } diff --git a/docs/template/edx/tmpl/augments.tmpl b/docs/template/edx/tmpl/augments.tmpl deleted file mode 100644 index 446d28aa5..000000000 --- a/docs/template/edx/tmpl/augments.tmpl +++ /dev/null @@ -1,10 +0,0 @@ - - - -
      -
      • -
    - diff --git a/docs/template/edx/tmpl/container.tmpl b/docs/template/edx/tmpl/container.tmpl deleted file mode 100644 index 1b9400408..000000000 --- a/docs/template/edx/tmpl/container.tmpl +++ /dev/null @@ -1,196 +0,0 @@ - - - - - - - - - -
    - -
    - -

    - -

    - -
    - - - - -
    - - - -
    - -
    -
    - - -
    - - - - - - - - - -
    - - - - - -

    Example 1? 's':'' ?>

    - - - -
    - - -

    Extends

    - - - - - -

    Requires

    - -
      -
      • -
    - - - -

    Classes

    - -
    -
    -
    -
    - - - -

    Interfaces

    - -
    -
    -
    -
    - - - -

    Mixins

    - -
    -
    -
    -
    - - - -

    Namespaces

    - -
    -
    -
    -
    - - - -

    Members

    - - - - - - - -

    Methods

    - - - - - - - -

    Type Definitions

    - - - - - - - - - -

    Events

    - - - - - -
    - -
    - - - diff --git a/docs/template/edx/tmpl/details.tmpl b/docs/template/edx/tmpl/details.tmpl deleted file mode 100644 index 4a5bd49fb..000000000 --- a/docs/template/edx/tmpl/details.tmpl +++ /dev/null @@ -1,143 +0,0 @@ -" + data.defaultvalue + ""; - defaultObjectClass = ' class="object-value"'; -} -?> - - -
    Properties:
    - - - - - -
    - - -
    Version:
    -
    - - - -
    Since:
    -
    - - - -
    Inherited From:
    -
    • - -
    - - - -
    Overrides:
    -
    • - -
    - - - -
    Implementations:
    -
      - -
      • - -
    - - - -
    Implements:
    -
      - -
      • - -
    - - - -
    Mixes In:
    - -
      - -
      • - -
    - - - -
    Deprecated:
    • Yes
    - - - -
    Author:
    -
    -
      -
      • -
    -
    - - - -
    Copyright:
    -
    - - - -
    License:
    -
    - - - -
    Default Value:
    -
      - > -
    - - - -
    Source:
    -
    • - , -
    - - - -
    Tutorials:
    -
    -
      -
      • -
    -
    - - - -
    See:
    -
    -
      -
      • -
    -
    - - - -
    To Do:
    -
    -
      -
      • -
    -
    - -
    diff --git a/docs/template/edx/tmpl/example.tmpl b/docs/template/edx/tmpl/example.tmpl deleted file mode 100644 index e87caa5b7..000000000 --- a/docs/template/edx/tmpl/example.tmpl +++ /dev/null @@ -1,2 +0,0 @@ - -
    diff --git a/docs/template/edx/tmpl/examples.tmpl b/docs/template/edx/tmpl/examples.tmpl deleted file mode 100644 index 04d975e96..000000000 --- a/docs/template/edx/tmpl/examples.tmpl +++ /dev/null @@ -1,13 +0,0 @@ - -

    - -
    - \ No newline at end of file diff --git a/docs/template/edx/tmpl/exceptions.tmpl b/docs/template/edx/tmpl/exceptions.tmpl deleted file mode 100644 index 9cef6c7d9..000000000 --- a/docs/template/edx/tmpl/exceptions.tmpl +++ /dev/null @@ -1,32 +0,0 @@ - - -
    -
    -
    - -
    -
    -
    -
    -
    -
    - Type -
    -
    - -
    -
    -
    -
    -
    - -
    - - - - - -
    - diff --git a/docs/template/edx/tmpl/layout.tmpl b/docs/template/edx/tmpl/layout.tmpl deleted file mode 100644 index b658b8b36..000000000 --- a/docs/template/edx/tmpl/layout.tmpl +++ /dev/null @@ -1,39 +0,0 @@ - - - - - JSDoc: <?js= title ?> - - - - - - - - - - - - -
    -

    - - -
    - - - -
    - -
    - Documentation generated by JSDoc on -
    - - - - - diff --git a/docs/template/edx/tmpl/mainpage.tmpl b/docs/template/edx/tmpl/mainpage.tmpl deleted file mode 100644 index 65380e327..000000000 --- a/docs/template/edx/tmpl/mainpage.tmpl +++ /dev/null @@ -1,10 +0,0 @@ - - - -
    -
    -
    - diff --git a/docs/template/edx/tmpl/members.tmpl b/docs/template/edx/tmpl/members.tmpl deleted file mode 100644 index 154c17b6e..000000000 --- a/docs/template/edx/tmpl/members.tmpl +++ /dev/null @@ -1,38 +0,0 @@ - -

    - - -

    - - - -
    - -
    - - - -
    Type:
    -
      -
    • - -
      • -
    - - - - - -
    Fires:
    -
      -
      • -
    - - - -
    Example 1? 's':'' ?>
    - - diff --git a/docs/template/edx/tmpl/method.tmpl b/docs/template/edx/tmpl/method.tmpl deleted file mode 100644 index 0125fe29a..000000000 --- a/docs/template/edx/tmpl/method.tmpl +++ /dev/null @@ -1,131 +0,0 @@ - - - -

    Constructor

    - - - -

    - - - -

    - - - - -
    - -
    - - - -
    Extends:
    - - - - -
    Type:
    -
      -
    • - -
      • -
    - - - -
    This:
    -
    - - - -
    Parameters:
    - - - - - - -
    Requires:
    -
      -
      • -
    - - - -
    Fires:
    -
      -
      • -
    - - - -
    Listens to Events:
    -
      -
      • -
    - - - -
    Listeners of This Event:
    -
      -
      • -
    - - - -
    Modifies:
    - 1) { ?>
      -
      • -
    - - - - -
    Throws:
    - 1) { ?>
      -
      • -
    - - - - -
    Returns:
    - 1) { ?>
      -
      • -
    - - - - -
    Yields:
    - 1) { ?>
      -
      • -
    - - - - -
    Example 1? 's':'' ?>
    - - diff --git a/docs/template/edx/tmpl/modifies.tmpl b/docs/template/edx/tmpl/modifies.tmpl deleted file mode 100644 index 16ccbf8d8..000000000 --- a/docs/template/edx/tmpl/modifies.tmpl +++ /dev/null @@ -1,14 +0,0 @@ - - - -
    -
    - Type -
    -
    - -
    -
    - diff --git a/docs/template/edx/tmpl/params.tmpl b/docs/template/edx/tmpl/params.tmpl deleted file mode 100644 index 1fb4049c1..000000000 --- a/docs/template/edx/tmpl/params.tmpl +++ /dev/null @@ -1,131 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeAttributesDefaultDescription
    - - - - - - <optional>
    - - - - <nullable>
    - - - - <repeatable>
    - -     		- - - - -
    Properties
    - -
    diff --git a/docs/template/edx/tmpl/properties.tmpl b/docs/template/edx/tmpl/properties.tmpl deleted file mode 100644 index 40e090971..000000000 --- a/docs/template/edx/tmpl/properties.tmpl +++ /dev/null @@ -1,108 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeAttributesDefaultDescription
    - - - - - - <optional>
    - - - - <nullable>
    - -     		- - - - -
    Properties
    -
    diff --git a/docs/template/edx/tmpl/returns.tmpl b/docs/template/edx/tmpl/returns.tmpl deleted file mode 100644 index d07045920..000000000 --- a/docs/template/edx/tmpl/returns.tmpl +++ /dev/null @@ -1,19 +0,0 @@ - -
    - -
    - - - -
    -
    - Type -
    -
    - -
    -
    - \ No newline at end of file diff --git a/docs/template/edx/tmpl/source.tmpl b/docs/template/edx/tmpl/source.tmpl deleted file mode 100644 index e559b5d10..000000000 --- a/docs/template/edx/tmpl/source.tmpl +++ /dev/null @@ -1,8 +0,0 @@ - -
    -
    -
    -
    -
    \ No newline at end of file diff --git a/docs/template/edx/tmpl/tutorial.tmpl b/docs/template/edx/tmpl/tutorial.tmpl deleted file mode 100644 index 88a0ad52a..000000000 --- a/docs/template/edx/tmpl/tutorial.tmpl +++ /dev/null @@ -1,19 +0,0 @@ -
    - -
    - 0) { ?> -
      -
      • -
    - - -

    -
    - -
    - -
    - -
    diff --git a/docs/template/edx/tmpl/type.tmpl b/docs/template/edx/tmpl/type.tmpl deleted file mode 100644 index ec2c6c0df..000000000 --- a/docs/template/edx/tmpl/type.tmpl +++ /dev/null @@ -1,7 +0,0 @@ - - -| - \ No newline at end of file diff --git a/example/ExamplePage.jsx b/example/ExamplePage.jsx index 1b513ded3..e98041d3e 100644 --- a/example/ExamplePage.jsx +++ b/example/ExamplePage.jsx @@ -5,7 +5,7 @@ import { injectIntl, intlShape } from '@edx/frontend-platform/i18n'; import { logInfo } from '@edx/frontend-platform/logging'; import { AppContext } from '@edx/frontend-platform/react'; import { ensureConfig, mergeConfig, getConfig } from '@edx/frontend-platform'; -import messages from './messages'; +import messages from './messages.js'; mergeConfig({ EXAMPLE_VAR: process.env.EXAMPLE_VAR, diff --git a/example/index.jsx b/example/index.jsx index 52b37aec5..7dbd143ae 100644 --- a/example/index.jsx +++ b/example/index.jsx @@ -14,8 +14,8 @@ import { subscribe } from '@edx/frontend-platform/pubSub'; import { Routes, Route } from 'react-router-dom'; import './index.scss'; -import ExamplePage from './ExamplePage'; -import AuthenticatedPage from './AuthenticatedPage'; +import ExamplePage from './ExamplePage.jsx'; +import AuthenticatedPage from './AuthenticatedPage.jsx'; subscribe(APP_READY, () => { ReactDOM.render( diff --git a/jest.config.js b/jest.config.js index 1afb8e530..f8bea2fbe 100644 --- a/jest.config.js +++ b/jest.config.js @@ -1,8 +1,10 @@ -const { createConfig } = require('@edx/frontend-build'); +import { createConfig } from '@edx/frontend-build'; -module.exports = createConfig('jest', { +const config = createConfig('jest', { setupFiles: [ '/src/setupTest.js', ], testTimeout: 20000, }); + +export default config; diff --git a/jsdoc.json b/jsdoc.json index ec2291a7d..3b6636edd 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -10,8 +10,9 @@ }, "plugins": [ "plugins/markdown", - "docs/addTagsPlugin", - "docs/removeExport" + "docs/addTagsPlugin.js", + "docs/removeExport.js", + "node_modules/jsdoc-tsimport-plugin/index.js" ], "templates": { "cleverLinks": false, diff --git a/package-lock.json b/package-lock.json index 4f6230ccb..8fedb664c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -43,8 +43,8 @@ "axios-mock-adapter": "^1.21.3", "core-js": "3.34.0", "enzyme": "3.11.0", + "eslint-plugin-jsdoc": "^46.9.1", "husky": "8.0.3", - "jsdoc": "^4.0.0", "nodemon": "3.0.2", "prop-types": "15.8.1", "react": "17.0.2", @@ -52,7 +52,8 @@ "react-redux": "^8.1.1", "react-router-dom": "^6.6.1", "redux": "4.2.1", - "regenerator-runtime": "0.14.0" + "regenerator-runtime": "0.14.0", + "typedoc": "^0.25.7" }, "peerDependencies": { "@edx/frontend-build": ">= 8.1.0 || ^12.9.0-alpha.1", @@ -2475,6 +2476,20 @@ "tslib": "^2.4.0" } }, + "node_modules/@es-joy/jsdoccomment": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.41.0.tgz", + "integrity": "sha512-aKUhyn1QI5Ksbqcr3fFJj16p99QdjUxXAEuFst1Z47DRyoiMwivIH9MV/ARcJOCXVjPfjITciej8ZD2O/6qUmw==", + "dev": true, + "dependencies": { + "comment-parser": "1.4.1", + "esquery": "^1.5.0", + "jsdoc-type-pratt-parser": "~4.0.0" + }, + "engines": { + "node": ">=16" + } + }, "node_modules/@eslint-community/eslint-utils": { "version": "4.4.0", "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz", @@ -3819,18 +3834,6 @@ "@jridgewell/sourcemap-codec": "^1.4.14" } }, - "node_modules/@jsdoc/salty": { - "version": "0.2.5", - "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.5.tgz", - "integrity": "sha512-TfRP53RqunNe2HBobVBJ0VLhK1HbfvBYeTC1ahnN64PWvyYyGebmMiPkuwvD9fpw2ZbkoPb8Q7mwy0aR8Z9rvw==", - "dev": true, - "dependencies": { - "lodash": "^4.17.21" - }, - "engines": { - "node": ">=v12.0.0" - } - }, "node_modules/@leichtgewicht/ip-codec": { "version": "2.0.4", "resolved": "https://registry.npmjs.org/@leichtgewicht/ip-codec/-/ip-codec-2.0.4.tgz", @@ -4562,28 +4565,6 @@ "integrity": "sha512-dRLjCWHYg4oaA77cxO64oO+7JwCwnIzkZPdrrC71jQmQtlhM556pwKo5bUzqvZndkVbeFLIIi+9TC40JNF5hNQ==", "dev": true }, - "node_modules/@types/linkify-it": { - "version": "3.0.4", - "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-3.0.4.tgz", - "integrity": "sha512-hPpIeeHb/2UuCw06kSNAOVWgehBLXEo0/fUs0mw3W2qhqX89PI2yvok83MnuctYGCPrabGIoi0fFso4DQ+sNUQ==", - "dev": true - }, - "node_modules/@types/markdown-it": { - "version": "12.2.3", - "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-12.2.3.tgz", - "integrity": "sha512-GKMHFfv3458yYy+v/N8gjufHO6MSZKCOXpZc5GXIWWy8uldwfmPn98vp81gZ5f9SVw8YYBctgfJ22a2d7AOMeQ==", - "dev": true, - "dependencies": { - "@types/linkify-it": "*", - "@types/mdurl": "*" - } - }, - "node_modules/@types/mdurl": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-1.0.4.tgz", - "integrity": "sha512-ARVxjAEX5TARFRzpDRVC6cEk0hUIXCCwaMhz8y7S1/PxU6zZS1UMjyobz7q4w/D/R552r4++EhwmXK1N2rAy0A==", - "dev": true - }, "node_modules/@types/mime": { "version": "1.3.4", "resolved": "https://registry.npmjs.org/@types/mime/-/mime-1.3.4.tgz", @@ -5213,6 +5194,12 @@ "node": ">=8" } }, + "node_modules/ansi-sequence-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", + "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", + "dev": true + }, "node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -5241,6 +5228,15 @@ "node": ">= 8" } }, + "node_modules/are-docs-informative": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz", + "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==", + "dev": true, + "engines": { + "node": ">=14" + } + }, "node_modules/argparse": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", @@ -6020,12 +6016,6 @@ "readable-stream": "^3.4.0" } }, - "node_modules/bluebird": { - "version": "3.7.2", - "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz", - "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==", - "dev": true - }, "node_modules/body-parser": { "version": "1.20.1", "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.1.tgz", @@ -6207,6 +6197,18 @@ "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", "dev": true }, + "node_modules/builtin-modules": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/builtin-modules/-/builtin-modules-3.3.0.tgz", + "integrity": "sha512-zhaCDicdLuWN5UbN5IMnFqNMhNfo919sH85y2/ea+5Yg9TsTkeZxpL+JLbp6cgYFS4sRLp3YV4S6yDuqVWHYOw==", + "dev": true, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/bytes": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", @@ -6339,18 +6341,6 @@ "isarray": "0.0.1" } }, - "node_modules/catharsis": { - "version": "0.9.0", - "resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.9.0.tgz", - "integrity": "sha512-prMTQVpcns/tzFgFVkVp6ak6RykZyWb3gu8ckUpd6YkTlacOd3DXGJjIpD4Q6zJirizvaiAjSSHlOsA+6sNh2A==", - "dev": true, - "dependencies": { - "lodash": "^4.17.15" - }, - "engines": { - "node": ">= 10" - } - }, "node_modules/chalk": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", @@ -6818,6 +6808,15 @@ "node": ">= 6" } }, + "node_modules/comment-parser": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.1.tgz", + "integrity": "sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg==", + "dev": true, + "engines": { + "node": ">= 12.0.0" + } + }, "node_modules/common-path-prefix": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/common-path-prefix/-/common-path-prefix-3.0.0.tgz", @@ -8391,6 +8390,72 @@ "node": ">=0.10.0" } }, + "node_modules/eslint-plugin-jsdoc": { + "version": "46.9.1", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-46.9.1.tgz", + "integrity": "sha512-11Ox5LCl2wY7gGkp9UOyew70o9qvii1daAH+h/MFobRVRNcy7sVlH+jm0HQdgcvcru6285GvpjpUyoa051j03Q==", + "dev": true, + "dependencies": { + "@es-joy/jsdoccomment": "~0.41.0", + "are-docs-informative": "^0.0.2", + "comment-parser": "1.4.1", + "debug": "^4.3.4", + "escape-string-regexp": "^4.0.0", + "esquery": "^1.5.0", + "is-builtin-module": "^3.2.1", + "semver": "^7.5.4", + "spdx-expression-parse": "^4.0.0" + }, + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/lru-cache": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", + "dev": true, + "dependencies": { + "yallist": "^4.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/semver": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", + "dev": true, + "dependencies": { + "lru-cache": "^6.0.0" + }, + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/spdx-expression-parse": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-4.0.0.tgz", + "integrity": "sha512-Clya5JIij/7C6bRR22+tnGXbc4VKlibKSVj2iHvVeX5iMW7s1SIQlqu699JkODJJIhh/pUu8L0/VLh8xflD+LQ==", + "dev": true, + "dependencies": { + "spdx-exceptions": "^2.1.0", + "spdx-license-ids": "^3.0.0" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/yallist": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz", + "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", + "dev": true + }, "node_modules/eslint-plugin-jsx-a11y": { "version": "6.7.1", "resolved": "https://registry.npmjs.org/eslint-plugin-jsx-a11y/-/eslint-plugin-jsx-a11y-6.7.1.tgz", @@ -10956,6 +11021,21 @@ "node": ">=4" } }, + "node_modules/is-builtin-module": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/is-builtin-module/-/is-builtin-module-3.2.1.tgz", + "integrity": "sha512-BSLE3HnV2syZ0FK0iMA/yUGplUeMmNz4AW5fnTunbCIqZi4vG3WjJT9FHMy5D69xmAYBHXQhJdALdpwVxV501A==", + "dev": true, + "dependencies": { + "builtin-modules": "^3.3.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/is-callable": { "version": "1.2.7", "resolved": "https://registry.npmjs.org/is-callable/-/is-callable-1.2.7.tgz", @@ -12421,53 +12501,15 @@ "js-yaml": "bin/js-yaml.js" } }, - "node_modules/js2xmlparser": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/js2xmlparser/-/js2xmlparser-4.0.2.tgz", - "integrity": "sha512-6n4D8gLlLf1n5mNLQPRfViYzu9RATblzPEtm1SthMX1Pjao0r9YI9nw7ZIfRxQMERS87mcswrg+r/OYrPRX6jA==", + "node_modules/jsdoc-type-pratt-parser": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz", + "integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==", "dev": true, - "dependencies": { - "xmlcreate": "^2.0.4" - } - }, - "node_modules/jsdoc": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-4.0.2.tgz", - "integrity": "sha512-e8cIg2z62InH7azBBi3EsSEqrKx+nUtAS5bBcYTSpZFA+vhNPyhv8PTFZ0WsjOPDj04/dOLlm08EDcQJDqaGQg==", - "dev": true, - "dependencies": { - "@babel/parser": "^7.20.15", - "@jsdoc/salty": "^0.2.1", - "@types/markdown-it": "^12.2.3", - "bluebird": "^3.7.2", - "catharsis": "^0.9.0", - "escape-string-regexp": "^2.0.0", - "js2xmlparser": "^4.0.2", - "klaw": "^3.0.0", - "markdown-it": "^12.3.2", - "markdown-it-anchor": "^8.4.1", - "marked": "^4.0.10", - "mkdirp": "^1.0.4", - "requizzle": "^0.2.3", - "strip-json-comments": "^3.1.0", - "underscore": "~1.13.2" - }, - "bin": { - "jsdoc": "jsdoc.js" - }, "engines": { "node": ">=12.0.0" } }, - "node_modules/jsdoc/node_modules/escape-string-regexp": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz", - "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==", - "dev": true, - "engines": { - "node": ">=8" - } - }, "node_modules/jsdom": { "version": "16.7.0", "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-16.7.0.tgz", @@ -12594,6 +12636,12 @@ "node": ">=6" } }, + "node_modules/jsonc-parser": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", + "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==", + "dev": true + }, "node_modules/jsonfile": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", @@ -12653,15 +12701,6 @@ "node": ">=0.10.0" } }, - "node_modules/klaw": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/klaw/-/klaw-3.0.0.tgz", - "integrity": "sha512-0Fo5oir+O9jnXu5EefYbVK+mHMBeEVEy2cmctR1O1NECcCkPRreJKrS6Qt/j3KC2C148Dfo9i3pCmCMsdqGr0g==", - "dev": true, - "dependencies": { - "graceful-fs": "^4.1.9" - } - }, "node_modules/kleur": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/kleur/-/kleur-3.0.3.tgz", @@ -12741,15 +12780,6 @@ "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", "dev": true }, - "node_modules/linkify-it": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-3.0.3.tgz", - "integrity": "sha512-ynTsyrFSdE5oZ/O9GEf00kPngmOfVwazR5GKDq6EYfhlpFug3J2zybX56a2PRRpc9P+FuSoGNAwjlbDs9jJBPQ==", - "dev": true, - "dependencies": { - "uc.micro": "^1.0.1" - } - }, "node_modules/loader-runner": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/loader-runner/-/loader-runner-4.3.0.tgz", @@ -12911,6 +12941,12 @@ "yallist": "^3.0.2" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/mailto-link": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/mailto-link/-/mailto-link-2.0.0.tgz", @@ -12978,47 +13014,6 @@ "node": ">=0.10.0" } }, - "node_modules/markdown-it": { - "version": "12.3.2", - "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-12.3.2.tgz", - "integrity": "sha512-TchMembfxfNVpHkbtriWltGWc+m3xszaRD0CZup7GFFhzIgQqxIfn3eGj1yZpfuflzPvfkt611B2Q/Bsk1YnGg==", - "dev": true, - "dependencies": { - "argparse": "^2.0.1", - "entities": "~2.1.0", - "linkify-it": "^3.0.1", - "mdurl": "^1.0.1", - "uc.micro": "^1.0.5" - }, - "bin": { - "markdown-it": "bin/markdown-it.js" - } - }, - "node_modules/markdown-it-anchor": { - "version": "8.6.7", - "resolved": "https://registry.npmjs.org/markdown-it-anchor/-/markdown-it-anchor-8.6.7.tgz", - "integrity": "sha512-FlCHFwNnutLgVTflOYHPW2pPcl2AACqVzExlkGQNsi4CJgqOHN7YTgDd4LuhgN1BFO3TS0vLAruV1Td6dwWPJA==", - "dev": true, - "peerDependencies": { - "@types/markdown-it": "*", - "markdown-it": "*" - } - }, - "node_modules/markdown-it/node_modules/argparse": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", - "dev": true - }, - "node_modules/markdown-it/node_modules/entities": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/entities/-/entities-2.1.0.tgz", - "integrity": "sha512-hCx1oky9PFrJ611mf0ifBLBRW8lUUVRlFolb5gWRfIELabBlbp9xZvrqZLZAs+NxFnbfQoeGd8wDkygjg7U85w==", - "dev": true, - "funding": { - "url": "https://github.com/fb55/entities?sponsor=1" - } - }, "node_modules/marked": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", @@ -13046,12 +13041,6 @@ "integrity": "sha512-GaqWWShW4kv/G9IEucWScBx9G1/vsFZZJUO+tD26M8J8z3Kw5RDQjaoZe03YAClgeS/SWPOcb4nkFBTEi5DUEA==", "dev": true }, - "node_modules/mdurl": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", - "integrity": "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==", - "dev": true - }, "node_modules/media-typer": { "version": "0.3.0", "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", @@ -13216,18 +13205,6 @@ "node": ">=0.10.0" } }, - "node_modules/mkdirp": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", - "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", - "dev": true, - "bin": { - "mkdirp": "bin/cmd.js" - }, - "engines": { - "node": ">=10" - } - }, "node_modules/moo": { "version": "0.5.2", "resolved": "https://registry.npmjs.org/moo/-/moo-0.5.2.tgz", @@ -16447,15 +16424,6 @@ "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==", "dev": true }, - "node_modules/requizzle": { - "version": "0.2.4", - "resolved": "https://registry.npmjs.org/requizzle/-/requizzle-0.2.4.tgz", - "integrity": "sha512-JRrFk1D4OQ4SqovXOgdav+K8EAhSB/LJZqCz8tbX0KObcdeM15Ss59ozWMBWmmINMagCwmqn4ZNryUGpBsl6Jw==", - "dev": true, - "dependencies": { - "lodash": "^4.17.21" - } - }, "node_modules/resolve": { "version": "1.22.8", "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.8.tgz", @@ -17520,6 +17488,18 @@ "dev": true, "optional": true }, + "node_modules/shiki": { + "version": "0.14.7", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.7.tgz", + "integrity": "sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==", + "dev": true, + "dependencies": { + "ansi-sequence-parser": "^1.1.0", + "jsonc-parser": "^3.2.0", + "vscode-oniguruma": "^1.7.0", + "vscode-textmate": "^8.0.0" + } + }, "node_modules/side-channel": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz", @@ -19028,6 +19008,51 @@ "is-typedarray": "^1.0.0" } }, + "node_modules/typedoc": { + "version": "0.25.7", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.7.tgz", + "integrity": "sha512-m6A6JjQRg39p2ZVRIN3NKXgrN8vzlHhOS+r9ymUYtcUP/TIQPvWSq7YgE5ZjASfv5Vd5BW5xrir6Gm2XNNcOow==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "marked": "^4.3.0", + "minimatch": "^9.0.3", + "shiki": "^0.14.7" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 16" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x" + } + }, + "node_modules/typedoc/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/typedoc/node_modules/minimatch": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", + "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/typescript": { "version": "5.3.2", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.3.2.tgz", @@ -19041,12 +19066,6 @@ "node": ">=14.17" } }, - "node_modules/uc.micro": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", - "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==", - "dev": true - }, "node_modules/unbox-primitive": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.0.2.tgz", @@ -19083,12 +19102,6 @@ "integrity": "sha512-WxONCrssBM8TSPRqN5EmsjVrsv4A8X12J4ArBiiayv3DyyG3ZlIg6yysuuSYdZsVz3TKcTg2fd//Ujd4CHV1iA==", "dev": true }, - "node_modules/underscore": { - "version": "1.13.6", - "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.6.tgz", - "integrity": "sha512-+A5Sja4HP1M08MaXya7p5LvjuM7K6q/2EaC0+iovj/wOcMsTzMvDFbasi/oSapiwOlt252IqsKqPjCl7huKS0A==", - "dev": true - }, "node_modules/undici-types": { "version": "5.25.3", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.25.3.tgz", @@ -19464,6 +19477,18 @@ "node": ">= 0.8" } }, + "node_modules/vscode-oniguruma": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", + "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", + "dev": true + }, + "node_modules/vscode-textmate": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", + "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", + "dev": true + }, "node_modules/w3c-hr-time": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/w3c-hr-time/-/w3c-hr-time-1.0.2.tgz", @@ -20142,12 +20167,6 @@ "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==", "dev": true }, - "node_modules/xmlcreate": { - "version": "2.0.4", - "resolved": "https://registry.npmjs.org/xmlcreate/-/xmlcreate-2.0.4.tgz", - "integrity": "sha512-nquOebG4sngPmGPICTS5EnxqhKbCmz5Ox5hsszI2T6U5qdrJizBc+0ilYSEjTSzU0yZcmvppztXe/5Al5fUwdg==", - "dev": true - }, "node_modules/y18n": { "version": "5.0.8", "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", diff --git a/package.json b/package.json index 48b65657f..1492b0c4c 100644 --- a/package.json +++ b/package.json @@ -2,16 +2,64 @@ "name": "@edx/frontend-platform", "version": "1.0.0-semantically-released", "description": "Foundational application framework for Open edX micro-frontend applications.", - "main": "index.js", + "type": "module", + "exports": { + ".": { + "import": "./src/index.js", + "types": "./types/index.d.ts" + }, + "./analytics": { + "import": "./src/analytics/index.js", + "types": "./types/analytics/index.d.ts" + }, + "./auth": { + "import": "./src/auth/index.js", + "types": "./types/auth/index.d.ts" + }, + "./i18n": { + "import": "./src/i18n/index.js", + "types": "./types/i18n/index.d.ts" + }, + "./logging": { + "import": "./src/logging/index.js", + "types": "./types/logging/index.d.ts" + }, + "./react": { + "import": "./src/react/index.js", + "types": "./types/react/index.d.ts" + } + }, + "typesVersions": { + "*": { + "*": [ + "types/index.d.ts" + ], + "analytics": [ + "types/analytics/index.d.ts" + ], + "auth": [ + "types/auth/index.d.ts" + ], + "i18n": [ + "types/i18n/index.d.ts" + ], + "logging": [ + "types/logging/index.d.ts" + ], + "react": [ + "types/react/index.d.ts" + ] + } + }, "publishConfig": { "access": "public" }, "sideEffects": false, "scripts": { "build": "make build", - "docs": "jsdoc -c jsdoc.json", + "docs": "./node_modules/.bin/typedoc src/config.js src/pubSub.js src/initialize.js src/utils.js src/analytics/index.js src/auth/index.js src/i18n/index.js src/logging/index.js src/react/index.js src/scripts/index.js src/testing/index.js --out docs/api", "docs-watch": "nodemon -w src -w docs/template -w README.md -e js,jsx --exec npm run docs", - "lint": "fedx-scripts eslint --ext .js --ext .jsx .", + "lint": "fedx-scripts eslint --ext .js --ext .jsx --config .eslintrc.cjs .", "snapshot": "fedx-scripts jest --updateSnapshot", "start": "fedx-scripts webpack-dev-server --progress", "test": "fedx-scripts jest --coverage", @@ -41,8 +89,8 @@ "axios-mock-adapter": "^1.21.3", "core-js": "3.34.0", "enzyme": "3.11.0", + "eslint-plugin-jsdoc": "^46.9.1", "husky": "8.0.3", - "jsdoc": "^4.0.0", "nodemon": "3.0.2", "prop-types": "15.8.1", "react": "17.0.2", @@ -50,7 +98,8 @@ "react-redux": "^8.1.1", "react-router-dom": "^6.6.1", "redux": "4.2.1", - "regenerator-runtime": "0.14.0" + "regenerator-runtime": "0.14.0", + "typedoc": "^0.25.7" }, "dependencies": { "@cospired/i18n-iso-languages": "4.1.0", diff --git a/src/analytics/MockAnalyticsService.js b/src/analytics/MockAnalyticsService.js index 6c3c24590..7132c0dc3 100644 --- a/src/analytics/MockAnalyticsService.js +++ b/src/analytics/MockAnalyticsService.js @@ -1,10 +1,11 @@ +/** @typedef {import('./interface.js').AnalyticsService} AnalyticsService */ + /** * 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 + * It emulates the behavior of a real analytics service but without making any requests. It has no * other functionality. * * @implements {AnalyticsService} - * @memberof module:Analytics */ class MockAnalyticsService { static hasIdentifyBeenCalled = false; diff --git a/src/analytics/SegmentAnalyticsService.js b/src/analytics/SegmentAnalyticsService.js index 3a22b406c..b3c3d69f1 100644 --- a/src/analytics/SegmentAnalyticsService.js +++ b/src/analytics/SegmentAnalyticsService.js @@ -1,9 +1,10 @@ +// @ts-check import formurlencoded from 'form-urlencoded'; -import { snakeCaseObject } from '../utils'; +import { snakeCaseObject } from '../utils.js'; +/** @typedef {import('./interface.js').AnalyticsService} AnalyticsService */ /** * @implements {AnalyticsService} - * @memberof module:Analytics */ class SegmentAnalyticsService { constructor({ httpClient, loggingService, config }) { @@ -28,6 +29,7 @@ class SegmentAnalyticsService { initializeSegment() { // Create a queue, but don't obliterate an existing one! global.analytics = global.analytics || []; + // @ts-ignore const { analytics } = global; // If the real analytics.js is already on the page return. @@ -97,6 +99,7 @@ class SegmentAnalyticsService { // Insert our script next to the first script element. const first = document.getElementsByTagName('script')[0]; + // @ts-ignore first.parentNode.insertBefore(script, first); analytics._loadOptions = options; // eslint-disable-line no-underscore-dangle @@ -131,7 +134,7 @@ class SegmentAnalyticsService { * @returns {Promise} The promise returned by HttpClient.post. */ sendTrackingLogEvent(eventName, properties) { - const snakeEventData = snakeCaseObject(properties, { deep: true }); + const snakeEventData = snakeCaseObject(properties); const serverData = { event_type: eventName, event: JSON.stringify(snakeEventData), @@ -182,7 +185,7 @@ class SegmentAnalyticsService { // but we still have a user id associated in segment, reset the local segment state // This has to be wrapped in the analytics.ready() callback because the analytics.user() // function isn't available until the analytics.js package has finished initializing. - return new Promise((resolve, reject) => { // eslint-disable-line no-unused-vars + return /** @type {Promise} */(new Promise((resolve) => { global.analytics.ready(() => { if (global.analytics.user().id()) { global.analytics.reset(); @@ -197,7 +200,7 @@ class SegmentAnalyticsService { // this is added to handle a specific use-case where if a user has blocked the analytics // tools in their browser, this promise does not get resolved and user sees a blank // page. Dispatching this event in script.onerror callback in analytics.load. - document.addEventListener('segmentFailed', resolve); + document.addEventListener('segmentFailed', () => resolve()); // This is added to handle the google analytics blocked case which is injected into // the DOM by segment.min.js. setTimeout(() => { @@ -206,7 +209,7 @@ class SegmentAnalyticsService { resolve(); } }, 2000); - }); + })); } /** diff --git a/src/analytics/index.js b/src/analytics/index.js index 8f6d3af21..9f4dea981 100644 --- a/src/analytics/index.js +++ b/src/analytics/index.js @@ -1,3 +1,31 @@ +// @ts-check +/** + * **Import members from `@openedx/frontend-platform/analytics`** + * + * Contains a shared interface for tracking events. Has a default implementation of + * SegmentAnalyticsService, which supports Segment and the Tracking Log API (hosted in LMS). + * + * The `initialize` function performs much of the analytics configuration for you. If, however, + * you're not using the `initialize` function, analytics can be configured via: + * + * ``` + * import { configure, SegmentAnalyticsService } from '@edx/frontend-platform/analytics'; + * import { getConfig } from '@edx/frontend-platform'; + * import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth'; + * import { getLoggingService } from '@edx/frontend-platform/logging'; + * + * configure(SegmentAnalyticsService, { + * config: getConfig(), + * loggingService: getLoggingService(), + * httpClient: getAuthenticatedHttpClient(), + * }); + * ``` + * + * As shown in this example, analytics depends on the configuration document, logging, and having + * an authenticated HTTP client. + * + * @module Analytics + */ export { configure, identifyAnonymousUser, @@ -7,6 +35,11 @@ export { sendTrackingLogEvent, getAnalyticsService, resetAnalyticsService, -} from './interface'; -export { default as SegmentAnalyticsService } from './SegmentAnalyticsService'; -export { default as MockAnalyticsService } from './MockAnalyticsService'; +} from './interface.js'; +export { default as SegmentAnalyticsService } from './SegmentAnalyticsService.js'; +export { default as MockAnalyticsService } from './MockAnalyticsService.js'; + +// Export types too - required for interfaces to be documented by TypeDoc: +/** @typedef {import('./interface.js').AnalyticsService} AnalyticsService */ +/** @typedef {import('./interface.js').AnalyticsServiceConstructor} AnalyticsServiceConstructor */ +/** @typedef {import('./interface.js').AnalyticsServiceOptions} AnalyticsServiceOptions */ diff --git a/src/analytics/interface.js b/src/analytics/interface.js index 48d60be61..12b45ca8b 100755 --- a/src/analytics/interface.js +++ b/src/analytics/interface.js @@ -1,30 +1,4 @@ -/** - * #### Import members from **@edx/frontend-platform/analytics** - * - * Contains a shared interface for tracking events. Has a default implementation of - * SegmentAnalyticsService, which supports Segment and the Tracking Log API (hosted in LMS). - * - * The `initialize` function performs much of the analytics configuration for you. If, however, - * you're not using the `initialize` function, analytics can be configured via: - * - * ``` - * import { configure, SegmentAnalyticsService } from '@edx/frontend-platform/analytics'; - * import { getConfig } from '@edx/frontend-platform'; - * import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth'; - * import { getLoggingService } from '@edx/frontend-platform/logging'; - * - * configure(SegmentAnalyticsService, { - * config: getConfig(), - * loggingService: getLoggingService(), - * httpClient: getAuthenticatedHttpClient(), - * }); - * ``` - * - * As shown in this example, analytics depends on the configuration document, logging, and having - * an authenticated HTTP client. - * - * @module Analytics - */ +// @ts-check import PropTypes from 'prop-types'; const optionsShape = { @@ -48,8 +22,8 @@ let service; /** * - * @param {class} AnalyticsService - * @param {*} options + * @param {AnalyticsServiceConstructor} AnalyticsService + * @param {AnalyticsServiceOptions} options * @returns {AnalyticsService} */ export function configure(AnalyticsService, options) { @@ -73,7 +47,7 @@ export function sendTrackingLogEvent(eventName, properties) { * * * @param {*} userId - * @param {*} traits + * @param {*} [traits] */ export function identifyAuthenticatedUser(userId, traits) { service.identifyAuthenticatedUser(userId, traits); @@ -82,7 +56,7 @@ export function identifyAuthenticatedUser(userId, traits) { /** * * - * @param {*} traits + * @param {*} [traits] * @returns {Promise} */ export function identifyAnonymousUser(traits) { @@ -131,12 +105,21 @@ export function resetAnalyticsService() { } /** - * @name AnalyticsService - * @interface - * @memberof module:Analytics + * @typedef {Object} AnalyticsService * @property {function} identifyAnonymousUser * @property {function} identifyAuthenticatedUser * @property {function} sendPageEvent * @property {function} sendTrackEvent * @property {function} sendTrackingLogEvent */ + +/** + * @typedef {Object} AnalyticsServiceOptions + * @property {import('../config.js').ConfigDocument} config + * @property {*} httpClient + * @property {import('../logging/interface.js').LoggingService} loggingService + */ + +/** + * @typedef {new (options: AnalyticsServiceOptions) => AnalyticsService} AnalyticsServiceConstructor + */ diff --git a/src/analytics/interface.test.js b/src/analytics/interface.test.js index 5f7047819..4abd84076 100644 --- a/src/analytics/interface.test.js +++ b/src/analytics/interface.test.js @@ -6,7 +6,7 @@ import { sendTrackEvent, sendTrackingLogEvent, SegmentAnalyticsService, -} from './index'; +} from './index.js'; const eventType = 'test.event'; const eventData = { diff --git a/src/auth/AxiosCsrfTokenService.js b/src/auth/AxiosCsrfTokenService.js index e40a615da..723d49ba1 100644 --- a/src/auth/AxiosCsrfTokenService.js +++ b/src/auth/AxiosCsrfTokenService.js @@ -1,5 +1,6 @@ +// @ts-check import axios from 'axios'; -import { getUrlParts, processAxiosErrorAndThrow } from './utils'; +import { getUrlParts, processAxiosErrorAndThrow } from './utils.js'; export default class AxiosCsrfTokenService { constructor(csrfTokenApiPath) { diff --git a/src/auth/AxiosJwtAuthService.js b/src/auth/AxiosJwtAuthService.js index de97b0efc..a4e4a0260 100644 --- a/src/auth/AxiosJwtAuthService.js +++ b/src/auth/AxiosJwtAuthService.js @@ -1,13 +1,19 @@ +// @ts-check import axios from 'axios'; import PropTypes from 'prop-types'; -import { logFrontendAuthError } from './utils'; -import { camelCaseObject, ensureDefinedConfig } from '../utils'; -import createJwtTokenProviderInterceptor from './interceptors/createJwtTokenProviderInterceptor'; -import createCsrfTokenProviderInterceptor from './interceptors/createCsrfTokenProviderInterceptor'; -import createProcessAxiosRequestErrorInterceptor from './interceptors/createProcessAxiosRequestErrorInterceptor'; -import AxiosJwtTokenService from './AxiosJwtTokenService'; -import AxiosCsrfTokenService from './AxiosCsrfTokenService'; -import configureCache from './LocalForageCache'; +import { logFrontendAuthError } from './utils.js'; +import { camelCaseObject, ensureDefinedConfig } from '../utils.js'; +import createJwtTokenProviderInterceptor from './interceptors/createJwtTokenProviderInterceptor.js'; +import createCsrfTokenProviderInterceptor from './interceptors/createCsrfTokenProviderInterceptor.js'; +import createProcessAxiosRequestErrorInterceptor from './interceptors/createProcessAxiosRequestErrorInterceptor.js'; +import AxiosJwtTokenService from './AxiosJwtTokenService.js'; +import AxiosCsrfTokenService from './AxiosCsrfTokenService.js'; +import configureCache from './LocalForageCache.js'; + +/** @typedef {import('./interface.js').AuthService} AuthService */ +/** @typedef {import('./interface.js').AuthServiceOptions} AuthServiceOptions */ +/** @typedef {import('./interface.js').HttpClient} HttpClient */ +/** @typedef {import('./interface.js').UserData} UserData */ const optionsPropTypes = { config: PropTypes.shape({ @@ -27,20 +33,10 @@ const optionsPropTypes = { /** * @implements {AuthService} - * @memberof module:Auth */ class AxiosJwtAuthService { /** - * @param {Object} options - * @param {Object} options.config - * @param {string} options.config.BASE_URL - * @param {string} options.config.LMS_BASE_URL - * @param {string} options.config.LOGIN_URL - * @param {string} options.config.LOGOUT_URL - * @param {string} options.config.REFRESH_ACCESS_TOKEN_ENDPOINT - * @param {string} options.config.ACCESS_TOKEN_COOKIE_NAME - * @param {string} options.config.CSRF_TOKEN_API_PATH - * @param {Object} options.loggingService requires logError and logInfo methods + * @param {AuthServiceOptions} options */ constructor(options) { this.authenticatedHttpClient = null; @@ -110,6 +106,7 @@ class AxiosJwtAuthService { */ getAuthenticatedHttpClient(options = {}) { if (options.useCache) { + // @ts-ignore - Typescript shows that this can be null. Probably worth fixing properly. return this.cachedAuthenticatedHttpClient; } @@ -209,7 +206,7 @@ class AxiosJwtAuthService { /** * Sets the authenticated user to the provided value. * - * @param {UserData} authUser + * @param {UserData|null} authUser */ setAuthenticatedUser(authUser) { this.authenticatedUser = authUser; @@ -219,7 +216,7 @@ class AxiosJwtAuthService { * Reads the authenticated user's access token. Resolves to null if the user is * unauthenticated. * - * @returns {Promise|Promise} Resolves to the user's access token if they are + * @returns {Promise} Resolves to the user's access token if they are * logged in. */ async fetchAuthenticatedUser(options = {}) { @@ -250,14 +247,15 @@ class AxiosJwtAuthService { * Ensures a user is authenticated. It will redirect to login when not * authenticated. * - * @param {string} [redirectUrl=config.BASE_URL] to return user after login when not + * @param {string} [redirectUrl] to return user after login when not * authenticated. * @returns {Promise} */ async ensureAuthenticatedUser(redirectUrl = this.config.BASE_URL) { await this.fetchAuthenticatedUser(); - if (this.getAuthenticatedUser() === null) { + const authenticatedUser = this.getAuthenticatedUser(); + if (authenticatedUser === null) { const isRedirectFromLoginPage = global.document.referrer && global.document.referrer.startsWith(this.config.LOGIN_URL); @@ -271,11 +269,12 @@ class AxiosJwtAuthService { this.redirectToLogin(redirectUrl); const unauthorizedError = new Error('Failed to ensure the user is authenticated'); + // @ts-ignore unauthorizedError.isRedirecting = true; throw unauthorizedError; } - return this.getAuthenticatedUser(); + return authenticatedUser; } /** @@ -289,7 +288,7 @@ class AxiosJwtAuthService { * console.log(authenticatedUser); // Will contain additional user information * ``` * - * @returns {Promise} + * @returns {Promise} */ async hydrateAuthenticatedUser() { const user = this.getAuthenticatedUser(); @@ -304,10 +303,6 @@ class AxiosJwtAuthService { * Adds authentication defaults and interceptors to an HTTP client instance. * * @param {HttpClient} newHttpClient - * @param {Object} config - * @param {string} [config.REFRESH_ACCESS_TOKEN_ENDPOINT] - * @param {string} [config.ACCESS_TOKEN_COOKIE_NAME] - * @param {string} [config.CSRF_TOKEN_API_PATH] * @returns {HttpClient} A configured Axios HTTP client. */ addAuthenticationToHttpClient(newHttpClient) { diff --git a/src/auth/AxiosJwtAuthService.test.jsx b/src/auth/AxiosJwtAuthService.test.jsx index 0ca97d494..458696ff3 100644 --- a/src/auth/AxiosJwtAuthService.test.jsx +++ b/src/auth/AxiosJwtAuthService.test.jsx @@ -2,7 +2,7 @@ import axios from 'axios'; import Cookies from 'universal-cookie'; import MockAdapter from 'axios-mock-adapter'; -import AxiosJwtAuthService from './AxiosJwtAuthService'; +import AxiosJwtAuthService from './AxiosJwtAuthService.js'; const mockLoggingService = { logInfo: jest.fn(), diff --git a/src/auth/AxiosJwtTokenService.js b/src/auth/AxiosJwtTokenService.js index 83021ed7c..0bcea3c0e 100644 --- a/src/auth/AxiosJwtTokenService.js +++ b/src/auth/AxiosJwtTokenService.js @@ -1,8 +1,8 @@ import Cookies from 'universal-cookie'; import jwtDecode from 'jwt-decode'; import axios from 'axios'; -import { logFrontendAuthError, processAxiosErrorAndThrow } from './utils'; -import createRetryInterceptor from './interceptors/createRetryInterceptor'; +import { logFrontendAuthError, processAxiosErrorAndThrow } from './utils.js'; +import createRetryInterceptor from './interceptors/createRetryInterceptor.js'; export default class AxiosJwtTokenService { static isTokenExpired(token) { diff --git a/src/auth/LocalForageCache.js b/src/auth/LocalForageCache.js index 0b9416b22..78578fba5 100644 --- a/src/auth/LocalForageCache.js +++ b/src/auth/LocalForageCache.js @@ -1,3 +1,4 @@ +// @ts-check /* eslint-disable no-underscore-dangle */ import localforage from 'localforage'; import memoryDriver from 'localforage-memoryStorageDriver'; diff --git a/src/auth/MockAuthService.js b/src/auth/MockAuthService.js index 159f556c0..126c0239c 100644 --- a/src/auth/MockAuthService.js +++ b/src/auth/MockAuthService.js @@ -1,6 +1,9 @@ import axios from 'axios'; import PropTypes from 'prop-types'; -import { ensureDefinedConfig } from '../utils'; +import { ensureDefinedConfig } from '../utils.js'; + +/** @typedef {import('../config.js').ConfigDocument} ConfigDocument */ +/** @typedef {import('../logging/interface.js').LoggingService} LoggingService */ const userPropTypes = PropTypes.shape({ userId: PropTypes.string.isRequired, @@ -72,22 +75,12 @@ const optionsPropTypes = { * Logging and Analytics. * * @implements {AuthService} - * @memberof module:Auth */ class MockAuthService { /** * @param {Object} options - * @param {Object} options.config - * @param {string} options.config.BASE_URL - * @param {string} options.config.LMS_BASE_URL - * @param {string} options.config.LOGIN_URL - * @param {string} options.config.LOGOUT_URL - * @param {string} options.config.REFRESH_ACCESS_TOKEN_ENDPOINT - * @param {string} options.config.ACCESS_TOKEN_COOKIE_NAME - * @param {string} options.config.CSRF_TOKEN_API_PATH - * @param {Object} options.config.hydratedAuthenticatedUser - * @param {Object} options.config.authenticatedUser - * @param {Object} options.loggingService requires logError and logInfo methods + * @param {ConfigDocument&{hydratedAuthenticatedUser?: any, authenticatedUser?: any}} options.config + * @param {LoggingService} options.loggingService requires logError and logInfo methods */ constructor(options) { this.authenticatedHttpClient = null; diff --git a/src/auth/index.js b/src/auth/index.js index 779c43f0a..72fcaed4b 100644 --- a/src/auth/index.js +++ b/src/auth/index.js @@ -1,3 +1,40 @@ +// @ts-check +/** + * **Import members from `@openedx/frontend-platform/auth`** + * + * Simplifies the process of making authenticated API requests to backend edX services by providing + * common authN/authZ client code that enables the login/logout flow and handles ensuring the + * presence of a valid [JWT cookie](https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/oauth_dispatch/docs/decisions/0009-jwt-in-session-cookie.rst). + * + * The `initialize` function performs much of the auth configuration for you. If, however, you're + * not using the `initialize` function, an authenticated API client can be created via: + * + * ``` + * import { + * configure, + * fetchAuthenticatedUser, + * getAuthenticatedHttpClient + * } from '@edx/frontend-platform/auth'; + * import { getConfig } from '@edx/frontend-platform'; + * import { getLoggingService } from '@edx/frontend-platform/logging'; + * + * configure({ + * loggingService: getLoggingService(), + * config: getConfig(), + * }); + * + * const authenticatedUser = await fetchAuthenticatedUser(); // validates and decodes JWT token + * const authenticatedHttpClient = getAuthenticatedHttpClient(); + * const response = await getAuthenticatedHttpClient().get(`https://example.com/api/user/data/${authenticatedUser.username}`); // fetching from an authenticated API using user data + * ``` + * + * As shown in this example, auth depends on the configuration document and logging. + * + * NOTE: The documentation for AxiosJwtAuthService is nearly the same as that for the top-level + * auth interface, except that it contains some Axios-specific details. + * + * @module Auth + */ export { AUTHENTICATED_USER_TOPIC, AUTHENTICATED_USER_CHANGED, @@ -14,6 +51,12 @@ export { fetchAuthenticatedUser, ensureAuthenticatedUser, hydrateAuthenticatedUser, -} from './interface'; -export { default as AxiosJwtAuthService } from './AxiosJwtAuthService'; -export { default as MockAuthService } from './MockAuthService'; +} from './interface.js'; +export { default as AxiosJwtAuthService } from './AxiosJwtAuthService.js'; +export { default as MockAuthService } from './MockAuthService.js'; + +// Export types too - required for interfaces to be documented by TypeDoc: +/** @typedef {import('./interface.js').AuthService} AuthService */ +/** @typedef {import('./interface.js').AuthServiceConstructor} AuthServiceConstructor */ +/** @typedef {import('./interface.js').AuthServiceOptions} AuthServiceOptions */ +/** @typedef {import('./interface.js').UserData} UserData */ diff --git a/src/auth/interceptors/createProcessAxiosRequestErrorInterceptor.js b/src/auth/interceptors/createProcessAxiosRequestErrorInterceptor.js index 23bda7e4c..3194ce00e 100644 --- a/src/auth/interceptors/createProcessAxiosRequestErrorInterceptor.js +++ b/src/auth/interceptors/createProcessAxiosRequestErrorInterceptor.js @@ -1,4 +1,5 @@ -import { processAxiosError } from '../utils'; +// @ts-check +import { processAxiosError } from '../utils.js'; const createProcessAxiosRequestErrorInterceptor = (options) => { const { loggingService } = options; diff --git a/src/auth/interceptors/createRetryInterceptor.js b/src/auth/interceptors/createRetryInterceptor.js index 65360e18b..3c8f861ed 100644 --- a/src/auth/interceptors/createRetryInterceptor.js +++ b/src/auth/interceptors/createRetryInterceptor.js @@ -1,3 +1,4 @@ +// @ts-check import axios from 'axios'; // This default algorithm is a recreation of what is documented here diff --git a/src/auth/interceptors/createRetryInterceptor.test.js b/src/auth/interceptors/createRetryInterceptor.test.js index ef4be6f29..e03eb9753 100644 --- a/src/auth/interceptors/createRetryInterceptor.test.js +++ b/src/auth/interceptors/createRetryInterceptor.test.js @@ -1,4 +1,4 @@ -import { defaultGetBackoffMilliseconds } from './createRetryInterceptor'; +import { defaultGetBackoffMilliseconds } from './createRetryInterceptor.js'; describe('createRetryInterceptor: defaultGetBackoffMilliseconds', () => { it('returns a number between 2000 and 3000 on the first retry', () => { diff --git a/src/auth/interface.js b/src/auth/interface.js index cd3e416d2..bb1168ef5 100644 --- a/src/auth/interface.js +++ b/src/auth/interface.js @@ -1,41 +1,6 @@ -/** - * #### Import members from **@edx/frontend-platform/auth** - * - * Simplifies the process of making authenticated API requests to backend edX services by providing - * common authN/authZ client code that enables the login/logout flow and handles ensuring the - * presence of a valid [JWT cookie](https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/oauth_dispatch/docs/decisions/0009-jwt-in-session-cookie.rst). - * - * The `initialize` function performs much of the auth configuration for you. If, however, you're - * not using the `initialize` function, an authenticated API client can be created via: - * - * ``` - * import { - * configure, - * fetchAuthenticatedUser, - * getAuthenticatedHttpClient - * } from '@edx/frontend-platform/auth'; - * import { getConfig } from '@edx/frontend-platform'; - * import { getLoggingService } from '@edx/frontend-platform/logging'; - * - * configure({ - * loggingService: getLoggingService(), - * config: getConfig(), - * }); - * - * const authenticatedUser = await fetchAuthenticatedUser(); // validates and decodes JWT token - * const authenticatedHttpClient = getAuthenticatedHttpClient(); - * const response = await getAuthenticatedHttpClient().get(`https://example.com/api/user/data/${authenticatedUser.username}`); // fetching from an authenticated API using user data - * ``` - * - * As shown in this example, auth depends on the configuration document and logging. - * - * NOTE: The documentation for AxiosJwtAuthService is nearly the same as that for the top-level - * auth interface, except that it contains some Axios-specific details. - * - * @module Auth - */ +// @ts-check import PropTypes from 'prop-types'; -import { publish } from '../pubSub'; +import { publish } from '../pubSub.js'; /** * @constant @@ -88,8 +53,8 @@ let service; /** * - * @param {class} AuthService - * @param {*} options + * @param {AuthServiceConstructor} AuthService + * @param {AuthServiceOptions} options * @returns {AuthService} */ export function configure(AuthService, options) { @@ -214,7 +179,7 @@ export function setAuthenticatedUser(authUser) { * Reads the authenticated user's access token. Resolves to null if the user is * unauthenticated. * - * @returns {Promise|Promise} Resolves to the user's access token if they are + * @returns {Promise} Resolves to the user's access token if they are * logged in. */ export async function fetchAuthenticatedUser(options = {}) { @@ -252,11 +217,28 @@ export async function hydrateAuthenticatedUser() { } /** - * @name AuthService - * @interface - * @memberof module:Auth - * @property {function} getAuthenticatedHttpClient - * @property {function} getHttpClient + * @typedef {import("axios").Axios} HttpClient + */ + +/** + * @typedef {Object} CustomErrorAttributes + * @property {number} [httpErrorStatus] + * @property {'unknown-api-request-error'|'api-response-error'|'api-request-error'|'api-request-config-error' + * } [httpErrorType] + * @property {string} [httpErrorMessage] + * @property {string} [httpErrorRequestUrl] + * @property {string} [httpErrorRequestMethod] + * @property {any} [httpErrorResponseData] + */ + +/** + * @typedef {import("axios").AxiosError & {customAttributes: CustomErrorAttributes}} DetailedAxiosError + */ + +/** + * @typedef {Object} AuthService + * @property {typeof getAuthenticatedHttpClient} getAuthenticatedHttpClient + * @property {typeof getHttpClient} getHttpClient * @property {function} getLoginRedirectUrl * @property {function} redirectToLogin * @property {function} getLogoutRedirectUrl @@ -269,40 +251,21 @@ export async function hydrateAuthenticatedUser() { */ /** - * A configured axios client. See axios docs for more - * info https://github.com/axios/axios. All the functions - * below accept isPublic and isCsrfExempt in the request - * config options. Setting these to true will prevent this - * client from attempting to refresh the jwt access token - * or a csrf token respectively. - * - * ``` - * // A public endpoint (no jwt token refresh) - * apiClient.get('/path/to/endpoint', { isPublic: true }); - * ``` - * - * ``` - * // A csrf exempt endpoint - * apiClient.post('/path/to/endpoint', { data }, { isCsrfExempt: true }); - * ``` - * - * @name HttpClient - * @interface - * @memberof module:Auth - * @property {function} get - * @property {function} head - * @property {function} options - * @property {function} delete (csrf protected) - * @property {function} post (csrf protected) - * @property {function} put (csrf protected) - * @property {function} patch (csrf protected) + * @typedef {Object} AuthServiceOptions + * @property {import('../config.js').ConfigDocument} config + * @property {import('../logging/interface.js').LoggingService} loggingService + * @property {((client: HttpClient) => void)[]} [middleware] + */ + +/** + * @typedef {new (options: AuthServiceOptions) => AuthService} AuthServiceConstructor */ /** - * @name UserData - * @interface - * @memberof module:Auth + * @typedef {Object} UserData * @property {string} userId + * @property {string} email + * @property {string} name * @property {string} username * @property {Array} roles * @property {boolean} administrator diff --git a/src/auth/utils.js b/src/auth/utils.js index 92c174e5f..3e9956a2c 100644 --- a/src/auth/utils.js +++ b/src/auth/utils.js @@ -1,3 +1,4 @@ +// @ts-check // Lifted from here: https://regexr.com/3ok5o const urlRegex = /([a-z]{1,2}tps?):\/\/((?:(?!(?:\/|#|\?|&)).)+)(?:(\/(?:(?:(?:(?!(?:#|\?|&)).)+\/))?))?(?:((?:(?!(?:\.|$|\?|#)).)+))?(?:(\.(?:(?!(?:\?|$|#)).)+))?(?:(\?(?:(?!(?:$|#)).)+))?(?:(#.+))?/; const getUrlParts = (url) => { @@ -35,7 +36,13 @@ const logFrontendAuthError = (loggingService, error) => { loggingService.logError(prefixedMessageError, prefixedMessageError.customAttributes); }; +/** + * Handle an Axios error + * @param {import("axios").AxiosError} axiosErrorObject The error + * @returns {import("./interface").DetailedAxiosError} + */ const processAxiosError = (axiosErrorObject) => { + /** @type {import("./interface").DetailedAxiosError} */ const error = Object.create(axiosErrorObject); const { request, response, config } = error; diff --git a/src/config.js b/src/config.js index 3adea36dd..5abea2493 100644 --- a/src/config.js +++ b/src/config.js @@ -1,5 +1,6 @@ +// @ts-check /** - * #### Import members from **@edx/frontend-platform** + * **Import members from `@openedx/frontend-platform`** * * The configuration module provides utilities for working with an application's configuration * document (ConfigDocument). Configuration variables can be supplied to the @@ -123,10 +124,10 @@ * @module Config */ -import { APP_CONFIG_INITIALIZED, CONFIG_CHANGED } from './constants'; +import { APP_CONFIG_INITIALIZED, CONFIG_CHANGED } from './constants.js'; -import { publish, subscribe } from './pubSub'; -import { ensureDefinedConfig } from './utils'; +import { publish, subscribe } from './pubSub.js'; +import { ensureDefinedConfig } from './utils.js'; function extractRegex(envVar) { // Convert the environment variable string to a regex, while guarding @@ -137,40 +138,41 @@ function extractRegex(envVar) { return undefined; } -const ENVIRONMENT = process.env.NODE_ENV; +const ENVIRONMENT = /** @type {"production"|"development"|"test"} */ (process.env.NODE_ENV); +/** @type {ConfigDocument} */ let config = { - ACCESS_TOKEN_COOKIE_NAME: process.env.ACCESS_TOKEN_COOKIE_NAME, - ACCOUNT_PROFILE_URL: process.env.ACCOUNT_PROFILE_URL, - ACCOUNT_SETTINGS_URL: process.env.ACCOUNT_SETTINGS_URL, - BASE_URL: process.env.BASE_URL, + ACCESS_TOKEN_COOKIE_NAME: process.env.ACCESS_TOKEN_COOKIE_NAME || '', + ACCOUNT_PROFILE_URL: process.env.ACCOUNT_PROFILE_URL || '', + ACCOUNT_SETTINGS_URL: process.env.ACCOUNT_SETTINGS_URL || '', + BASE_URL: process.env.BASE_URL || '', PUBLIC_PATH: process.env.PUBLIC_PATH || '/', - CREDENTIALS_BASE_URL: process.env.CREDENTIALS_BASE_URL, - CSRF_TOKEN_API_PATH: process.env.CSRF_TOKEN_API_PATH, - DISCOVERY_API_BASE_URL: process.env.DISCOVERY_API_BASE_URL, - PUBLISHER_BASE_URL: process.env.PUBLISHER_BASE_URL, - ECOMMERCE_BASE_URL: process.env.ECOMMERCE_BASE_URL, + CREDENTIALS_BASE_URL: process.env.CREDENTIALS_BASE_URL || '', + CSRF_TOKEN_API_PATH: process.env.CSRF_TOKEN_API_PATH || '', + DISCOVERY_API_BASE_URL: process.env.DISCOVERY_API_BASE_URL || '', + PUBLISHER_BASE_URL: process.env.PUBLISHER_BASE_URL || '', + ECOMMERCE_BASE_URL: process.env.ECOMMERCE_BASE_URL || '', ENVIRONMENT, IGNORED_ERROR_REGEX: extractRegex(process.env.IGNORED_ERROR_REGEX), - LANGUAGE_PREFERENCE_COOKIE_NAME: process.env.LANGUAGE_PREFERENCE_COOKIE_NAME, - LEARNING_BASE_URL: process.env.LEARNING_BASE_URL, - LMS_BASE_URL: process.env.LMS_BASE_URL, - LOGIN_URL: process.env.LOGIN_URL, - LOGOUT_URL: process.env.LOGOUT_URL, - STUDIO_BASE_URL: process.env.STUDIO_BASE_URL, - MARKETING_SITE_BASE_URL: process.env.MARKETING_SITE_BASE_URL, - ORDER_HISTORY_URL: process.env.ORDER_HISTORY_URL, - REFRESH_ACCESS_TOKEN_ENDPOINT: process.env.REFRESH_ACCESS_TOKEN_ENDPOINT, + LANGUAGE_PREFERENCE_COOKIE_NAME: process.env.LANGUAGE_PREFERENCE_COOKIE_NAME || '', + LEARNING_BASE_URL: process.env.LEARNING_BASE_URL || '', + LMS_BASE_URL: process.env.LMS_BASE_URL || '', + LOGIN_URL: process.env.LOGIN_URL || '', + LOGOUT_URL: process.env.LOGOUT_URL || '', + STUDIO_BASE_URL: process.env.STUDIO_BASE_URL || '', + MARKETING_SITE_BASE_URL: process.env.MARKETING_SITE_BASE_URL || '', + ORDER_HISTORY_URL: process.env.ORDER_HISTORY_URL || '', + REFRESH_ACCESS_TOKEN_ENDPOINT: process.env.REFRESH_ACCESS_TOKEN_ENDPOINT || '', SECURE_COOKIES: ENVIRONMENT !== 'development', - SEGMENT_KEY: process.env.SEGMENT_KEY, - SITE_NAME: process.env.SITE_NAME, - USER_INFO_COOKIE_NAME: process.env.USER_INFO_COOKIE_NAME, - LOGO_URL: process.env.LOGO_URL, - LOGO_TRADEMARK_URL: process.env.LOGO_TRADEMARK_URL, - LOGO_WHITE_URL: process.env.LOGO_WHITE_URL, - FAVICON_URL: process.env.FAVICON_URL, - MFE_CONFIG_API_URL: process.env.MFE_CONFIG_API_URL, - APP_ID: process.env.APP_ID, - SUPPORT_URL: process.env.SUPPORT_URL, + SEGMENT_KEY: process.env.SEGMENT_KEY || '', + SITE_NAME: process.env.SITE_NAME || '', + USER_INFO_COOKIE_NAME: process.env.USER_INFO_COOKIE_NAME || '', + LOGO_URL: process.env.LOGO_URL || '', + LOGO_TRADEMARK_URL: process.env.LOGO_TRADEMARK_URL || '', + LOGO_WHITE_URL: process.env.LOGO_WHITE_URL || '', + FAVICON_URL: process.env.FAVICON_URL || '', + MFE_CONFIG_API_URL: process.env.MFE_CONFIG_API_URL || '', + APP_ID: process.env.APP_ID || '', + SUPPORT_URL: process.env.SUPPORT_URL || '', }; /** @@ -188,7 +190,7 @@ let config = { * ``` * * @returns {ConfigDocument} - */ + */ export function getConfig() { return config; } @@ -229,7 +231,7 @@ export function setConfig(newConfig) { * * If any of the key values are `undefined`, an error will be logged to 'warn'. * - * @param {Object} newConfig + * @param {Partial} newConfig */ export function mergeConfig(newConfig) { ensureDefinedConfig(newConfig, 'ProcessEnvConfigService'); @@ -291,8 +293,7 @@ export function ensureConfig(keys, requester = 'unspecified application code') { * variables via command-line environment variables. That means they must be supplied at build * time. * - * @name ConfigDocument - * @memberof module:Config + * @typedef {Object} ConfigDocument * @property {string} ACCESS_TOKEN_COOKIE_NAME * @property {string} ACCOUNT_PROFILE_URL * @property {string} ACCOUNT_SETTINGS_URL @@ -302,8 +303,8 @@ export function ensureConfig(keys, requester = 'unspecified application code') { * @property {string} DISCOVERY_API_BASE_URL * @property {string} PUBLISHER_BASE_URL * @property {string} ECOMMERCE_BASE_URL - * @property {string} ENVIRONMENT This is one of: development, production, or test. - * @property {string} IGNORED_ERROR_REGEX + * @property {"development"|"production"|"test"} ENVIRONMENT + * @property {RegExp | undefined} IGNORED_ERROR_REGEX * @property {string} LANGUAGE_PREFERENCE_COOKIE_NAME * @property {string} LEARNING_BASE_URL * @property {string} LMS_BASE_URL @@ -312,6 +313,7 @@ export function ensureConfig(keys, requester = 'unspecified application code') { * @property {string} STUDIO_BASE_URL * @property {string} MARKETING_SITE_BASE_URL * @property {string} ORDER_HISTORY_URL + * @property {string} PUBLIC_PATH * @property {string} REFRESH_ACCESS_TOKEN_ENDPOINT * @property {boolean} SECURE_COOKIES * @property {string} SEGMENT_KEY @@ -324,4 +326,7 @@ export function ensureConfig(keys, requester = 'unspecified application code') { * @property {string} MFE_CONFIG_API_URL * @property {string} APP_ID * @property {string} SUPPORT_URL + * @property {import('./logging/interface.js').LoggingServiceConstructor} [loggingService] + * @property {import('./analytics/interface.js').AnalyticsServiceConstructor} [analyticsService] + * @property {import('./auth/interface.js').AuthServiceConstructor} [authService] */ diff --git a/src/i18n/countries.js b/src/i18n/countries.js index d88bf58c9..08026fb1b 100644 --- a/src/i18n/countries.js +++ b/src/i18n/countries.js @@ -1,5 +1,7 @@ +// @ts-check /* eslint-disable import/extensions */ -import COUNTRIES, { langs as countryLangs } from 'i18n-iso-countries'; +import * as COUNTRIES from 'i18n-iso-countries'; +import { langs as countryLangs } from 'i18n-iso-countries'; import { getPrimaryLanguageSubtag } from './lib'; @@ -29,7 +31,6 @@ COUNTRIES.registerLocale(require('i18n-iso-countries/langs/uk.json')); /** * Provides a lookup table of country IDs to country names for the current locale. * - * @memberof module:I18n */ export function getCountryMessages(locale) { const primaryLanguageSubtag = getPrimaryLanguageSubtag(locale); @@ -49,7 +50,6 @@ export function getCountryMessages(locale) { * TODO: ARCH-878: The list should be sorted alphabetically in the current locale. * This is useful for populating dropdowns. * - * @memberof module:I18n */ export function getCountryList(locale) { const countryMessages = getCountryMessages(locale); diff --git a/src/i18n/index.js b/src/i18n/index.js index 7ff12e4f5..91e53ad93 100644 --- a/src/i18n/index.js +++ b/src/i18n/index.js @@ -1,5 +1,7 @@ +// @ts-check /** - * #### Import members from **@edx/frontend-platform/i18n** + * **Import members from `@openedx/frontend-platform/i18n`** + * * The i18n module relies on react-intl and re-exports all of that package's exports. * * For each locale we want to support, react-intl needs 1) the locale-data, which includes @@ -23,66 +25,6 @@ * */ -/** - * @name createIntl - * @kind function - * @see {@link https://formatjs.io/docs/react-intl/api#createIntl Intl} - */ - -/** - * @name FormattedDate - * @kind class - * @see {@link https://formatjs.io/docs/react-intl/components/#formatteddate Intl} - */ - -/** - * @name FormattedTime - * @kind class - * @see {@link https://formatjs.io/docs/react-intl/components/#formattedtime Intl} - */ - -/** - * @name FormattedRelativeTime - * @kind class - * @see {@link https://formatjs.io/docs/react-intl/components/#formattedrelativetime Intl} - */ - -/** - * @name FormattedNumber - * @kind class - * @see {@link https://formatjs.io/docs/react-intl/components/#formattednumber Intl} - */ - -/** - * @name FormattedPlural - * @kind class - * @see {@link https://formatjs.io/docs/react-intl/components/#formattedplural Intl} - */ - -/** - * @name FormattedMessage - * @kind class - * @see {@link https://formatjs.io/docs/react-intl/components/#formattedmessage Intl} - */ - -/** - * @name IntlProvider - * @kind class - * @see {@link https://formatjs.io/docs/react-intl/components/#intlprovider Intl} - */ - -/** - * @name defineMessages - * @kind function - * @see {@link https://formatjs.io/docs/react-intl/api#definemessagesdefinemessage Intl} - */ - -/** - * @name useIntl - * @kind function - * @see {@link https://formatjs.io/docs/react-intl/api#useIntl Intl} - */ - export { createIntl, FormattedDate, @@ -107,18 +49,22 @@ export { mergeMessages, LOCALE_CHANGED, LOCALE_TOPIC, -} from './lib'; +} from './lib.js'; export { default as injectIntl, -} from './injectIntlWithShim'; +} from './injectIntlWithShim.jsx'; export { getCountryList, getCountryMessages, -} from './countries'; +} from './countries.js'; export { getLanguageList, getLanguageMessages, -} from './languages'; +} from './languages.js'; + +// Export types too - required for interfaces to be documented by TypeDoc: +/** @typedef {import('./lib.js').Messages} Messages */ +/** @typedef {import('./lib.js').MessagesByLocale} MessagesByLocale */ diff --git a/src/i18n/injectIntlWithShim.jsx b/src/i18n/injectIntlWithShim.jsx index 17ace6068..8a25a7aea 100644 --- a/src/i18n/injectIntlWithShim.jsx +++ b/src/i18n/injectIntlWithShim.jsx @@ -1,12 +1,12 @@ import React from 'react'; import { injectIntl } from 'react-intl'; -import { getLoggingService, intlShape } from './lib'; +import { getLoggingService, intlShape } from './lib.js'; /** * This function wraps react-intl's injectIntl function in order to add error logging to the intl * property's formatMessage function. * - * @memberof I18n + * @deprecated Use useIntl hook instead */ const injectIntlWithShim = (WrappedComponent) => { class ShimmedIntlComponent extends React.Component { diff --git a/src/i18n/languages.js b/src/i18n/languages.js index 74f7eca17..300be7c1b 100644 --- a/src/i18n/languages.js +++ b/src/i18n/languages.js @@ -1,5 +1,7 @@ +// @ts-check /* eslint-disable import/extensions */ -import LANGUAGES, { langs as languageLangs } from '@cospired/i18n-iso-languages'; +import * as LANGUAGES from '@cospired/i18n-iso-languages'; +import { langs as languageLangs } from '@cospired/i18n-iso-languages'; import { getPrimaryLanguageSubtag } from './lib'; @@ -31,8 +33,6 @@ LANGUAGES.registerLocale(require('@cospired/i18n-iso-languages/langs/pt.json')); /** * Provides a lookup table of language IDs to language names for the current locale. - * - * @memberof I18n */ export const getLanguageMessages = (locale) => { const primaryLanguageSubtag = getPrimaryLanguageSubtag(locale); @@ -51,8 +51,6 @@ export const getLanguageMessages = (locale) => { * * TODO: ARCH-878: The list should be sorted alphabetically in the current locale. * This is useful for populating dropdowns. - * - * @memberof I18n */ export const getLanguageList = (locale) => { const languageMessages = getLanguageMessages(locale); diff --git a/src/i18n/lib.js b/src/i18n/lib.js index 6f389526a..596e233bd 100644 --- a/src/i18n/lib.js +++ b/src/i18n/lib.js @@ -1,3 +1,4 @@ +// @ts-check import PropTypes from 'prop-types'; import Cookies from 'universal-cookie'; import merge from 'lodash.merge'; @@ -34,6 +35,10 @@ import '@formatjs/intl-relativetimeformat/locale-data/ru'; import '@formatjs/intl-relativetimeformat/locale-data/th'; import '@formatjs/intl-relativetimeformat/locale-data/uk'; +/** @typedef {import('../logging/interface').LoggingService} LoggingService */ +/** @typedef {{[id: string]: string}} Messages */ +/** @typedef {{[languageCode: string]: Messages}} MessagesByLocale */ + const cookies = new Cookies(); const supportedLocales = [ 'ar', // Arabic @@ -66,8 +71,6 @@ let loggingService = null; let messages = null; /** - * @memberof module:Internationalization - * * Prior versions of react-intl (our primary implementation of the i18n service) included a * PropTypes-based 'shape' for its `intl` object. This has since been removed. For legacy * compatibility, we include an `intlShape` export that is set to PropTypes.object. Usage of this @@ -84,19 +87,12 @@ export const intlShape = PropTypes.object; */ export const getLoggingService = () => loggingService; -/** - * @memberof module:Internationalization - */ export const LOCALE_TOPIC = 'LOCALE'; -/** - * @memberof module:Internationalization - */ export const LOCALE_CHANGED = `${LOCALE_TOPIC}.CHANGED`; /** - * - * @memberof module:Internationalization + * Get the cookie manager instance * @returns {Cookies} */ export function getCookies() { @@ -109,7 +105,7 @@ export function getCookies() { * may be 2 or more characters. * * @param {string} code - * @memberof module:Internationalization + * @returns {string} */ export function getPrimaryLanguageSubtag(code) { return code.split('-')[0]; @@ -125,7 +121,6 @@ export function getPrimaryLanguageSubtag(code) { * * @param {string} locale * @returns {string} - * @memberof module:Internationalization */ export function findSupportedLocale(locale) { if (messages[locale] !== undefined) { @@ -144,10 +139,9 @@ export function findSupportedLocale(locale) { * Gracefully fall back to a more general primary language subtag or to English (en) * if we don't support that language. * - * @param {string} locale If a locale is provided, returns the closest supported locale. Optional. + * @param {string} [locale] If a locale is provided, returns the closest supported locale. Optional. * @throws An error if i18n has not yet been configured. * @returns {string} - * @memberof module:Internationalization */ export function getLocale(locale) { if (messages === null) { @@ -174,8 +168,8 @@ export function getLocale(locale) { * Returns messages for the provided locale, or the user's preferred locale if no argument is * provided. * - * @param {string} [locale=getLocale()] - * @memberof module:Internationalization + * @param {string} [locale] + * @returns {Messages} */ export function getMessages(locale = getLocale()) { return messages[locale]; @@ -185,7 +179,7 @@ export function getMessages(locale = getLocale()) { * Determines if the provided locale is a right-to-left language. * * @param {string} locale - * @memberof module:Internationalization + * @returns {boolean} */ export function isRtl(locale) { return rtlLocales.includes(locale); @@ -194,8 +188,6 @@ export function isRtl(locale) { /** * Handles applying the RTL stylesheet and "dir=rtl" attribute to the html tag if the current locale * is a RTL language. - * - * @memberof module:Internationalization */ export function handleRtl() { if (isRtl(getLocale())) { @@ -236,9 +228,8 @@ const optionsShape = { /** * * - * @param {Object} newMessages - * @returns {Object} - * @memberof module:Internationalization + * @param {MessagesByLocale|MessagesByLocale[]} newMessages + * @returns {MessagesByLocale} */ export function mergeMessages(newMessages) { const msgs = Array.isArray(newMessages) ? merge({}, ...newMessages) : newMessages; @@ -255,9 +246,8 @@ export function mergeMessages(newMessages) { * * @param {Object} options * @param {LoggingService} options.loggingService - * @param {Object} options.config - * @param {Object} options.messages - * @memberof module:Internationalization + * @param {import('../config').ConfigDocument} options.config + * @param {MessagesByLocale|MessagesByLocale[]} options.messages */ export function configure(options) { PropTypes.checkPropTypes(optionsShape, options, 'property', 'i18n'); diff --git a/src/i18n/lib.test.js b/src/i18n/lib.test.js index b9285226b..7fdc8adec 100644 --- a/src/i18n/lib.test.js +++ b/src/i18n/lib.test.js @@ -8,7 +8,7 @@ import { handleRtl, getCookies, mergeMessages, -} from './lib'; +} from './lib.js'; jest.mock('universal-cookie'); diff --git a/src/i18n/scripts/intl-imports.test.js b/src/i18n/scripts/intl-imports.test.js index 992d23780..6d8d2d26c 100644 --- a/src/i18n/scripts/intl-imports.test.js +++ b/src/i18n/scripts/intl-imports.test.js @@ -1,7 +1,7 @@ // Tests for the intl-imports.js command line. import path from 'path'; -import { main as realMain } from './intl-imports'; +import { main as realMain } from './intl-imports.js'; const sempleAppDirectory = path.join(__dirname, '../../../example'); diff --git a/src/index.js b/src/index.js index 9a4137740..8124c1c5c 100644 --- a/src/index.js +++ b/src/index.js @@ -1,3 +1,16 @@ +/** + * Here you can find the core functionality of `frontend-platform`, which you + * can import directly. For example: + * ```js + * import { getConfig } from "@openedx/frontend-platform"; + * ``` + * Other functionality is split into modules, which you import separately, e.g. + * i18n functionality can be imported from "@openedx/frontend-platform/i18n". + * + * @module Core + * + */ + export { modifyObjectKeys, camelCaseObject, @@ -7,7 +20,7 @@ export { ensureDefinedConfig, parseURL, getPath, -} from './utils'; +} from './utils.js'; export { APP_TOPIC, APP_PUBSUB_INITIALIZED, @@ -20,25 +33,28 @@ export { APP_INIT_ERROR, CONFIG_TOPIC, CONFIG_CHANGED, -} from './constants'; +} from './constants.js'; export { initialize, history, initError, auth, -} from './initialize'; +} from './initialize.js'; export { publish, subscribe, unsubscribe, -} from './pubSub'; +} from './pubSub.js'; export { getConfig, setConfig, mergeConfig, ensureConfig, -} from './config'; +} from './config.js'; export { initializeMockApp, mockMessages, -} from './testing'; +} from './testing/index.js'; + +// Export types too - required for interfaces to be documented by TypeDoc: +/** @typedef {import('./config.js').ConfigDocument} ConfigDocument */ diff --git a/src/initialize.async.function.config.test.js b/src/initialize.async.function.config.test.js index 1ee0250ed..f49588b9e 100644 --- a/src/initialize.async.function.config.test.js +++ b/src/initialize.async.function.config.test.js @@ -1,21 +1,21 @@ import PubSub from 'pubsub-js'; -import { initialize } from './initialize'; +import { initialize } from './initialize.js'; import { logError, -} from './logging'; +} from './logging/index.js'; import { ensureAuthenticatedUser, fetchAuthenticatedUser, hydrateAuthenticatedUser, -} from './auth'; -import { getConfig } from './config'; +} from './auth/index.js'; +import { getConfig } from './config.js'; -jest.mock('./logging'); -jest.mock('./auth'); -jest.mock('./analytics'); -jest.mock('./i18n'); -jest.mock('./auth/LocalForageCache'); +jest.mock('./logging/index.js'); +jest.mock('./auth/index.js'); +jest.mock('./analytics/index.js'); +jest.mock('./i18n/index.js'); +jest.mock('./auth/LocalForageCache.js'); jest.mock('env.config.js', () => async () => new Promise((resolve) => { resolve({ JS_FILE_VAR: 'JS_FILE_VAR_VALUE_ASYNC_FUNCTION', diff --git a/src/initialize.const.config.test.js b/src/initialize.const.config.test.js index 12091328f..2a159f76b 100644 --- a/src/initialize.const.config.test.js +++ b/src/initialize.const.config.test.js @@ -1,21 +1,21 @@ import PubSub from 'pubsub-js'; -import { initialize } from './initialize'; +import { initialize } from './initialize.js'; import { logError, -} from './logging'; +} from './logging/index.js'; import { ensureAuthenticatedUser, fetchAuthenticatedUser, hydrateAuthenticatedUser, -} from './auth'; -import { getConfig } from './config'; +} from './auth/index.js'; +import { getConfig } from './config.js'; -jest.mock('./logging'); -jest.mock('./auth'); -jest.mock('./analytics'); -jest.mock('./i18n'); -jest.mock('./auth/LocalForageCache'); +jest.mock('./logging/index.js'); +jest.mock('./auth/index.js'); +jest.mock('./analytics/index.js'); +jest.mock('./i18n/index.js'); +jest.mock('./auth/LocalForageCache.js'); jest.mock('env.config.js', () => ({ JS_FILE_VAR: 'JS_FILE_VAR_VALUE_CONSTANT', })); diff --git a/src/initialize.function.config.test.js b/src/initialize.function.config.test.js index 06c13fc01..dc93403b5 100644 --- a/src/initialize.function.config.test.js +++ b/src/initialize.function.config.test.js @@ -1,21 +1,21 @@ import PubSub from 'pubsub-js'; -import { initialize } from './initialize'; +import { initialize } from './initialize.js'; import { logError, -} from './logging'; +} from './logging/index.js'; import { ensureAuthenticatedUser, fetchAuthenticatedUser, hydrateAuthenticatedUser, -} from './auth'; -import { getConfig } from './config'; +} from './auth/index.js'; +import { getConfig } from './config.js'; -jest.mock('./logging'); -jest.mock('./auth'); -jest.mock('./analytics'); -jest.mock('./i18n'); -jest.mock('./auth/LocalForageCache'); +jest.mock('./logging/index.js'); +jest.mock('./auth/index.js'); +jest.mock('./analytics/index.js'); +jest.mock('./i18n/index.js'); +jest.mock('./auth/LocalForageCache.js'); jest.mock('env.config.js', () => () => ({ JS_FILE_VAR: 'JS_FILE_VAR_VALUE_FUNCTION', })); diff --git a/src/initialize.js b/src/initialize.js index 2c7223595..718670510 100644 --- a/src/initialize.js +++ b/src/initialize.js @@ -1,5 +1,6 @@ +// @ts-check /** - * #### Import members from **@edx/frontend-platform** + * **Import members from `@openedx/frontend-platform`** * * The initialization module provides a function for managing an application's initialization * lifecycle. It also provides constants and default handler implementations. @@ -40,8 +41,7 @@ * requireAuthenticatedUser: true, * hydrateAuthenticatedUser: true, * }); - -``` + * ``` * @module Initialization */ @@ -53,22 +53,23 @@ to an empty object `{}` if the file doesn't exist. This acts like an 'optional' Note that the env.config.js file in frontend-platform's root directory is NOT used by the actual initialization code, it's just there for the test suite and example application. */ +// @ts-ignore import envConfig from 'env.config'; // eslint-disable-line import/no-unresolved -import { getPath } from './utils'; +import { getPath } from './utils.js'; import { publish, -} from './pubSub'; +} from './pubSub.js'; // eslint-disable-next-line import/no-cycle import { getConfig, mergeConfig, -} from './config'; +} from './config.js'; import { configure as configureLogging, getLoggingService, NewRelicLoggingService, logError, -} from './logging'; +} from './logging/index.js'; import { configure as configureAnalytics, SegmentAnalyticsService, identifyAnonymousUser, identifyAuthenticatedUser, -} from './analytics'; -import { GoogleAnalyticsLoader } from './scripts'; +} from './analytics/index.js'; +import { GoogleAnalyticsLoader } from './scripts/index.js'; import { getAuthenticatedHttpClient, configure as configureAuth, @@ -77,8 +78,8 @@ import { hydrateAuthenticatedUser, getAuthenticatedUser, AxiosJwtAuthService, -} from './auth'; -import { configure as configureI18n } from './i18n'; +} from './auth/index.js'; +import { configure as configureI18n } from './i18n/index.js'; import { APP_PUBSUB_INITIALIZED, APP_CONFIG_INITIALIZED, @@ -87,8 +88,8 @@ import { APP_LOGGING_INITIALIZED, APP_ANALYTICS_INITIALIZED, APP_READY, APP_INIT_ERROR, -} from './constants'; -import configureCache from './auth/LocalForageCache'; +} from './constants.js'; +import configureCache from './auth/LocalForageCache.js'; /** * A browser history or memory history object created by the [history](https://github.com/ReactTraining/history) @@ -172,7 +173,7 @@ async function jsFileConfig() { mergeConfig(config); } -/* +/** * Set or overrides configuration through an API. * This method allows runtime configuration. * Set a basic configuration when an error happen and allow initError and display the ErrorPage. @@ -193,6 +194,7 @@ async function runtimeConfig() { mergeConfig(data); } } catch (error) { + // @ts-ignore // eslint-disable-next-line no-console console.error('Error with config API', error.message); } @@ -263,25 +265,27 @@ function applyOverrideHandlers(overrides) { * - ready: A no-op by default. * - initError: Uses the 'initError' handler defined above. * - * @param {Object} [options] - * @param {*} [options.loggingService=NewRelicLoggingService] The `LoggingService` implementation - * to use. - * @param {*} [options.analyticsService=SegmentAnalyticsService] The `AnalyticsService` - * implementation to use. - * @param {*} [options.authMiddleware=[]] An array of middleware to apply to http clients in the auth service. - * @param {*} [options.externalScripts=[GoogleAnalyticsLoader]] An array of externalScripts. + * @param {Object} options + * @param {import('./logging/interface.js').LoggingServiceConstructor} [options.loggingService] + * The `LoggingService` implementation to use. + * @param {import('./analytics/interface.js').AnalyticsServiceConstructor} [options.analyticsService] + * The `AnalyticsService` implementation to use. + * @param {import('./auth/interface.js').AuthServiceConstructor} [options.authService] + * The `AuthService` implementation to use. + * @param {*} [options.authMiddleware] An array of middleware to apply to http clients in the auth service. + * @param {*} [options.externalScripts] An array of externalScripts. * By default added GoogleAnalyticsLoader. - * @param {*} [options.requireAuthenticatedUser=false] If true, turns on automatic login + * @param {*} [options.requireAuthenticatedUser] If true, turns on automatic login * redirection for unauthenticated users. Defaults to false, meaning that by default the * application will allow anonymous/unauthenticated sessions. - * @param {*} [options.hydrateAuthenticatedUser=false] If true, makes an API call to the user + * @param {*} [options.hydrateAuthenticatedUser] If true, makes an API call to the user * account endpoint (`${App.config.LMS_BASE_URL}/api/user/v1/accounts/${username}`) to fetch * detailed account information for the authenticated user. This data is merged into the return * value of `getAuthenticatedUser`, overriding any duplicate keys that already exist. Defaults to * false, meaning that no additional account information will be loaded. * @param {*} [options.messages] A i18n-compatible messages object, or an array of such objects. If * an array is provided, duplicate keys are resolved with the last-one-in winning. - * @param {*} [options.handlers={}] An optional object of handlers which can be used to replace the + * @param {*} [options.handlers] An optional object of handlers which can be used to replace the * default behavior of any part of the startup sequence. It can also be used to add additional * initialization behavior before or after the rest of the sequence. */ @@ -295,7 +299,7 @@ export async function initialize({ hydrateAuthenticatedUser: hydrateUser = false, messages, handlers: overrideHandlers = {}, -}) { +} = {}) { const handlers = applyOverrideHandlers(overrideHandlers); try { // Pub/Sub @@ -360,6 +364,7 @@ export async function initialize({ await handlers.ready(); publish(APP_READY); } catch (error) { + // @ts-ignore if (!error.isRedirecting) { // Initialization Error await handlers.initError(error); @@ -367,3 +372,5 @@ export async function initialize({ } } } + +initialize(); diff --git a/src/initialize.test.js b/src/initialize.test.js index 5276f705e..79762ff64 100644 --- a/src/initialize.test.js +++ b/src/initialize.test.js @@ -9,16 +9,16 @@ import { APP_I18N_INITIALIZED, APP_READY, APP_INIT_ERROR, -} from './constants'; -import { initialize } from './initialize'; -import { subscribe } from './pubSub'; +} from './constants.js'; +import { initialize } from './initialize.js'; +import { subscribe } from './pubSub.js'; import { configure as configureLogging, NewRelicLoggingService, getLoggingService, logError, -} from './logging'; +} from './logging/index.js'; import { configure as configureAuth, getAuthenticatedHttpClient, @@ -27,17 +27,17 @@ import { hydrateAuthenticatedUser, getAuthenticatedUser, AxiosJwtAuthService, -} from './auth'; -import { configure as configureAnalytics, SegmentAnalyticsService } from './analytics'; -import { configure as configureI18n } from './i18n'; -import { getConfig } from './config'; -import configureCache from './auth/LocalForageCache'; - -jest.mock('./logging'); -jest.mock('./auth'); -jest.mock('./analytics'); -jest.mock('./i18n'); -jest.mock('./auth/LocalForageCache'); +} from './auth/index.js'; +import { configure as configureAnalytics, SegmentAnalyticsService } from './analytics/index.js'; +import { configure as configureI18n } from './i18n/index.js'; +import { getConfig } from './config.js'; +import configureCache from './auth/LocalForageCache.js'; + +jest.mock('./logging/index.js'); +jest.mock('./auth/index.js'); +jest.mock('./analytics/index.js'); +jest.mock('./i18n/index.js'); +jest.mock('./auth/LocalForageCache.js'); jest.mock('history'); let config = null; diff --git a/src/logging/MockLoggingService.js b/src/logging/MockLoggingService.js index c81bad3c6..eb41980d7 100644 --- a/src/logging/MockLoggingService.js +++ b/src/logging/MockLoggingService.js @@ -3,27 +3,20 @@ * jest.fn(). It has no other functionality. * * @implements {LoggingService} - * @memberof module:Logging */ class MockLoggingService { /** * Implemented as a jest.fn() - * - * @memberof MockLoggingService */ logInfo = jest.fn(); /** * Implemented as a jest.fn() - * - * @memberof MockLoggingService */ logError = jest.fn(); /** * Implemented as a jest.fn() - * - * @memberof MockLoggingService */ setCustomAttribute = jest.fn(); } diff --git a/src/logging/NewRelicLoggingService.js b/src/logging/NewRelicLoggingService.js index d4fb1eb2a..e18b8981c 100644 --- a/src/logging/NewRelicLoggingService.js +++ b/src/logging/NewRelicLoggingService.js @@ -41,6 +41,10 @@ function sendError(error, customAttributes) { } } +/** + * @param {string} name + * @param {string|number|boolean|null} value + */ function setCustomAttribute(name, value) { if (process.env.NODE_ENV === 'development') { console.log(name, value); // eslint-disable-line @@ -82,8 +86,7 @@ function setCustomAttribute(name, value) { * * Requires the NewRelic Browser JavaScript snippet. * - * @implements {LoggingService} - * @memberof module:Logging + * @implements {import('./interface.js').LoggingService} */ export default class NewRelicLoggingService { constructor(options) { @@ -123,8 +126,7 @@ export default class NewRelicLoggingService { * * * @param {*} infoStringOrErrorObject - * @param {*} [customAttributes={}] - * @memberof NewRelicLoggingService + * @param {*} [customAttributes] */ logInfo(infoStringOrErrorObject, customAttributes = {}) { let message = infoStringOrErrorObject; @@ -142,9 +144,8 @@ export default class NewRelicLoggingService { /** * * - * @param {*} errorStringOrObject + * @param {string|Error} errorStringOrObject * @param {*} [customAttributes={}] - * @memberof NewRelicLoggingService */ logError(errorStringOrObject, customAttributes = {}) { const errorCustomAttributes = errorStringOrObject.customAttributes || {}; @@ -173,7 +174,7 @@ export default class NewRelicLoggingService { * Sets a custom attribute that will be included with all subsequent log messages. * * @param {string} name - * @param {string|number|null} value + * @param {string|number|boolean|null} value */ setCustomAttribute(name, value) { setCustomAttribute(name, value); diff --git a/src/logging/NewRelicLoggingService.test.js b/src/logging/NewRelicLoggingService.test.js index 24c792ec4..d9160b617 100644 --- a/src/logging/NewRelicLoggingService.test.js +++ b/src/logging/NewRelicLoggingService.test.js @@ -1,4 +1,4 @@ -import NewRelicLoggingService, { MAX_ERROR_LENGTH } from './NewRelicLoggingService'; +import NewRelicLoggingService, { MAX_ERROR_LENGTH } from './NewRelicLoggingService.js'; global.newrelic = { addPageAction: jest.fn(), diff --git a/src/logging/index.js b/src/logging/index.js index dbe09ec81..b4f04d842 100644 --- a/src/logging/index.js +++ b/src/logging/index.js @@ -1,9 +1,39 @@ +/** + * **Import members from `@openedx/frontend-platform/logging`** + * + * Contains a shared interface for logging information. (The default implementation is in + * NewRelicLoggingService.js.) When in development mode, all messages will instead be sent to the console. + * + * The `initialize` function performs much of the logging configuration for you. If, however, + * you're not using the `initialize` function, logging (via New Relic) can be configured via: + * + * ``` + * import { configure, NewRelicLoggingService, logInfo, logError } from '@edx/frontend-platform/logging'; + * import { geConfig } from '@edx/frontend-platform'; + * + * configureLogging(NewRelicLoggingService, { + * config: getConfig(), + * }); + * + * logInfo('Just so you know...'); + * logInfo(new Error('Unimportant error'), { type: 'unimportant' }); + * logError('Uhoh!'); + * logError(new Error('Uhoh error!')); + * ``` + * + * As shown in this example, logging depends on the configuration document. + * @module Logging + */ export { getLoggingService, resetLoggingService, configure, logInfo, logError, -} from './interface'; -export { default as NewRelicLoggingService } from './NewRelicLoggingService'; -export { default as MockLoggingService } from './MockLoggingService'; +} from './interface.js'; +export { default as NewRelicLoggingService } from './NewRelicLoggingService.js'; +export { default as MockLoggingService } from './MockLoggingService.js'; + +// Export types too - required for interfaces to be documented by TypeDoc: +/** @typedef {import('./interface.js').LoggingService} LoggingService */ +/** @typedef {import('./interface.js').LoggingServiceConstructor} LoggingServiceConstructor */ diff --git a/src/logging/interface.js b/src/logging/interface.js index 4c38748db..2bcd7b4a5 100644 --- a/src/logging/interface.js +++ b/src/logging/interface.js @@ -1,33 +1,8 @@ -/** - * #### Import members from **@edx/frontend-platform/logging** - * - * Contains a shared interface for logging information. (The default implementation is in - * NewRelicLoggingService.js.) When in development mode, all messages will instead be sent to the console. - * - * The `initialize` function performs much of the logging configuration for you. If, however, - * you're not using the `initialize` function, logging (via New Relic) can be configured via: - * - * ``` - * import { configure, NewRelicLoggingService, logInfo, logError } from '@edx/frontend-platform/logging'; - * import { geConfig } from '@edx/frontend-platform'; - * - * configureLogging(NewRelicLoggingService, { - * config: getConfig(), - * }); - * - * logInfo('Just so you know...'); - * logInfo(new Error('Unimportant error'), { type: 'unimportant' }); - * logError('Uhoh!'); - * logError(new Error('Uhoh error!')); - * ``` - * - * As shown in this example, logging depends on the configuration document. - * - * @module Logging - */ - +// @ts-check import PropTypes from 'prop-types'; +/** @typedef {import('../config.js').ConfigDocument} ConfigDocument */ + const optionsShape = { config: PropTypes.object.isRequired, }; @@ -37,10 +12,14 @@ const serviceShape = { logError: PropTypes.func.isRequired, }; +/** @type {LoggingService|null} */ let service = null; /** - * + * Configure the logging service for this frontend application + * @param {LoggingServiceConstructor} LoggingService + * @param {{config: ConfigDocument}} options + * @returns {LoggingService} */ export function configure(LoggingService, options) { PropTypes.checkPropTypes(optionsShape, options, 'property', 'Logging'); @@ -54,10 +33,11 @@ export function configure(LoggingService, options) { * object, or as an optional second parameter. * * @param {string|Error} infoStringOrErrorObject - * @param {Object} [customAttributes={}] + * @param {Object} [customAttributes] + * @returns {void} */ export function logInfo(infoStringOrErrorObject, customAttributes) { - return service.logInfo(infoStringOrErrorObject, customAttributes); + return service?.logInfo(infoStringOrErrorObject, customAttributes); } /** @@ -65,20 +45,22 @@ export function logInfo(infoStringOrErrorObject, customAttributes) { * object, or as an optional second parameter. * * @param {string|Error} errorStringOrObject - * @param {Object} [customAttributes={}] + * @param {Object} [customAttributes] + * @returns {void} */ export function logError(errorStringOrObject, customAttributes) { - return service.logError(errorStringOrObject, customAttributes); + return service?.logError(errorStringOrObject, customAttributes); } /** * Sets a custom attribute that will be included with all subsequent log messages. * * @param {string} name - * @param {string|number|null} value + * @param {string|number|boolean|null} value + * @returns {void} */ export function setCustomAttribute(name, value) { - return service.setCustomAttribute(name, value); + return service?.setCustomAttribute(name, value); } /** @@ -102,9 +84,12 @@ export function resetLoggingService() { } /** - * @name LoggingService - * @interface - * @memberof module:Logging - * @property {function} logError - * @property {function} logInfo + * @typedef {Object} LoggingService + * @property {(stringOrError: string|Error, customAttributes?: Object) => void} logError + * @property {(stringOrError: string|Error, customAttributes?: Object) => void} logInfo + * @property {typeof setCustomAttribute} setCustomAttribute + */ + +/** + * @typedef {new (options: {config: ConfigDocument}) => LoggingService} LoggingServiceConstructor */ diff --git a/src/pubSub.js b/src/pubSub.js index 1104f2442..edcde6169 100644 --- a/src/pubSub.js +++ b/src/pubSub.js @@ -40,7 +40,7 @@ export function unsubscribe(token) { /** * * @param {string} type - * @param {Object} data + * @param {Object} [data] */ export function publish(type, data) { return PubSub.publish(type, data); diff --git a/src/react/AppContext.jsx b/src/react/AppContext.jsx index c20046613..d6e5feda4 100644 --- a/src/react/AppContext.jsx +++ b/src/react/AppContext.jsx @@ -1,5 +1,12 @@ import React from 'react'; +/** + * @typedef IAppContext + * @property {import('../auth/interface.js').UserData|null} authenticatedUser + * @property {import('../config.js').ConfigDocument} config + * @property {string} locale + */ + /** * `AppContext` provides data from `App` in a way that React components can readily consume, even * if it's mutable data. `AppContext` contains the following data structure: @@ -13,12 +20,12 @@ import React from 'react'; * If the `App.authenticatedUser` or `App.config` data changes, `AppContext` will be updated * accordingly and pass those changes onto React components using the context. * - * `AppContext` is used in a React application like any other `[React Context](https://reactjs.org/docs/context.html) - * @memberof module:React + * `AppContext` is used in a React application like any other [React Context](https://reactjs.org/docs/context.html) */ -const AppContext = React.createContext({ +const AppContext = React.createContext(/** @type {IAppContext} */ ({ authenticatedUser: null, config: {}, -}); + locale: '', +})); export default AppContext; diff --git a/src/react/AppProvider.jsx b/src/react/AppProvider.jsx index a2ccd8bb1..52824be1d 100644 --- a/src/react/AppProvider.jsx +++ b/src/react/AppProvider.jsx @@ -1,22 +1,23 @@ +// @ts-check import React, { useState, useMemo } from 'react'; import PropTypes from 'prop-types'; import { BrowserRouter as Router } from 'react-router-dom'; -import OptionalReduxProvider from './OptionalReduxProvider'; +import OptionalReduxProvider from './OptionalReduxProvider.jsx'; -import ErrorBoundary from './ErrorBoundary'; -import AppContext from './AppContext'; -import { useAppEvent, useTrackColorSchemeChoice } from './hooks'; -import { getAuthenticatedUser, AUTHENTICATED_USER_CHANGED } from '../auth'; -import { getConfig } from '../config'; -import { CONFIG_CHANGED } from '../constants'; +import ErrorBoundary from './ErrorBoundary.jsx'; +import AppContext from './AppContext.jsx'; +import { useAppEvent, useTrackColorSchemeChoice } from './hooks.js'; +import { getAuthenticatedUser, AUTHENTICATED_USER_CHANGED } from '../auth/index.js'; +import { getConfig } from '../config.js'; +import { CONFIG_CHANGED } from '../constants.js'; import { getLocale, getMessages, IntlProvider, LOCALE_CHANGED, -} from '../i18n'; -import { basename } from '../initialize'; +} from '../i18n/index.js'; +import { basename } from '../initialize.js'; /** * A wrapper component for React-based micro-frontends to initialize a number of common data/ @@ -41,10 +42,11 @@ import { basename } from '../initialize'; * - A `Router` for react-router. * * @param {Object} props - * @param {Object} [props.store] A redux store. - * @memberof module:React + * @param {import('react').ReactNode} props.children The contents of your app, as React components + * @param {import('redux').Store|null} [props.store] Optional redux store. + * @param {boolean} [props.wrapWithRouter] Set this false if you want to supply your own router */ -export default function AppProvider({ store, children, wrapWithRouter }) { +export default function AppProvider({ children, store = null, wrapWithRouter = true }) { const [config, setConfig] = useState(getConfig()); const [authenticatedUser, setAuthenticatedUser] = useState(getAuthenticatedUser()); const [locale, setLocale] = useState(getLocale()); @@ -85,13 +87,10 @@ export default function AppProvider({ store, children, wrapWithRouter }) { } AppProvider.propTypes = { - // eslint-disable-next-line react/forbid-prop-types + // Note: default values are set above in the props destructuring. + // eslint-disable-next-line react/forbid-prop-types, react/require-default-props store: PropTypes.object, children: PropTypes.node.isRequired, + // eslint-disable-next-line react/require-default-props wrapWithRouter: PropTypes.bool, }; - -AppProvider.defaultProps = { - store: null, - wrapWithRouter: true, -}; diff --git a/src/react/AppProvider.test.jsx b/src/react/AppProvider.test.jsx index 231d2f0c3..9f8fc0b04 100644 --- a/src/react/AppProvider.test.jsx +++ b/src/react/AppProvider.test.jsx @@ -2,8 +2,8 @@ import React from 'react'; import { createStore } from 'redux'; import { mount } from 'enzyme'; import { BrowserRouter as Router } from 'react-router-dom'; -import AppProvider from './AppProvider'; -import { initialize } from '../initialize'; +import AppProvider from './AppProvider.jsx'; +import { initialize } from '../initialize.js'; jest.mock('../auth', () => ({ configure: () => {}, diff --git a/src/react/AuthenticatedPageRoute.jsx b/src/react/AuthenticatedPageRoute.jsx index d67231c8e..ae4027597 100644 --- a/src/react/AuthenticatedPageRoute.jsx +++ b/src/react/AuthenticatedPageRoute.jsx @@ -1,9 +1,9 @@ import React, { useContext } from 'react'; import PropTypes from 'prop-types'; -import AppContext from './AppContext'; -import PageWrap from './PageWrap'; -import { getLoginRedirectUrl } from '../auth'; +import AppContext from './AppContext.jsx'; +import PageWrap from './PageWrap.jsx'; +import { getLoginRedirectUrl } from '../auth/index.js'; /** * A react-router route that redirects to the login page when the route becomes active and the user @@ -17,7 +17,6 @@ import { getLoginRedirectUrl } from '../auth'; * * @see PageWrap * @see {@link module:frontend-platform/analytics~sendPageEvent} - * @memberof module:React * @param {Object} props * @param {string} props.redirectUrl The URL anonymous users should be redirected to, rather than * viewing the route's contents. diff --git a/src/react/AuthenticatedPageRoute.test.jsx b/src/react/AuthenticatedPageRoute.test.jsx index b8d68b0b1..8f9dd3123 100644 --- a/src/react/AuthenticatedPageRoute.test.jsx +++ b/src/react/AuthenticatedPageRoute.test.jsx @@ -2,11 +2,11 @@ import React from 'react'; import { mount } from 'enzyme'; import { Route, Routes, MemoryRouter } from 'react-router-dom'; -import { getAuthenticatedUser, getLoginRedirectUrl } from '../auth'; -import AuthenticatedPageRoute from './AuthenticatedPageRoute'; -import AppContext from './AppContext'; -import { getConfig } from '../config'; -import { sendPageEvent } from '../analytics'; +import { getAuthenticatedUser, getLoginRedirectUrl } from '../auth/index.js'; +import AuthenticatedPageRoute from './AuthenticatedPageRoute.jsx'; +import AppContext from './AppContext.jsx'; +import { getConfig } from '../config.js'; +import { sendPageEvent } from '../analytics/index.js'; jest.mock('../analytics'); jest.mock('../auth'); diff --git a/src/react/ErrorBoundary.jsx b/src/react/ErrorBoundary.jsx index a655e659f..d94ff3481 100644 --- a/src/react/ErrorBoundary.jsx +++ b/src/react/ErrorBoundary.jsx @@ -1,14 +1,12 @@ import React, { Component } from 'react'; import PropTypes from 'prop-types'; -import { logError } from '../logging'; +import { logError } from '../logging/index.js'; -import ErrorPage from './ErrorPage'; +import ErrorPage from './ErrorPage.jsx'; /** * Error boundary component used to log caught errors and display the error page. - * - * @memberof module:React * @extends {Component} */ class ErrorBoundary extends Component { diff --git a/src/react/ErrorBoundary.test.jsx b/src/react/ErrorBoundary.test.jsx index 538f2b6fa..ca1ec622a 100644 --- a/src/react/ErrorBoundary.test.jsx +++ b/src/react/ErrorBoundary.test.jsx @@ -1,9 +1,9 @@ import React from 'react'; import { mount } from 'enzyme'; -import ErrorBoundary from './ErrorBoundary'; -import ErrorPage from './ErrorPage'; -import { initializeMockApp } from '..'; +import ErrorBoundary from './ErrorBoundary.jsx'; +import ErrorPage from './ErrorPage.jsx'; +import { initializeMockApp } from '../index.js'; describe('ErrorBoundary', () => { let logError = jest.fn(); diff --git a/src/react/ErrorPage.jsx b/src/react/ErrorPage.jsx index 6cacb58e0..14c591e78 100644 --- a/src/react/ErrorPage.jsx +++ b/src/react/ErrorPage.jsx @@ -4,20 +4,19 @@ import { Button, Container, Row, Col, } from '@edx/paragon'; -import { useAppEvent } from './hooks'; +import { useAppEvent } from './hooks.js'; import { FormattedMessage, IntlProvider, getMessages, getLocale, LOCALE_CHANGED, -} from '../i18n'; +} from '../i18n/index.js'; /** * An error page that displays a generic message for unexpected errors. Also contains a "Try * Again" button to refresh the page. * - * @memberof module:React * @extends {Component} */ function ErrorPage({ diff --git a/src/react/LoginRedirect.jsx b/src/react/LoginRedirect.jsx index 47cca4d72..99377c10c 100644 --- a/src/react/LoginRedirect.jsx +++ b/src/react/LoginRedirect.jsx @@ -1,12 +1,11 @@ import { useEffect } from 'react'; -import { redirectToLogin } from '../auth'; +import { redirectToLogin } from '../auth/index.js'; /** * A React component that, when rendered, redirects to the login page as a side effect. Uses * `redirectToLogin` to perform the redirect. * * @see {@link module:frontend-platform/auth~redirectToLogin} - * @memberof module:React */ export default function LoginRedirect() { useEffect(() => { diff --git a/src/react/OptionalReduxProvider.jsx b/src/react/OptionalReduxProvider.jsx index 6ebb20b67..07f2c2fcb 100644 --- a/src/react/OptionalReduxProvider.jsx +++ b/src/react/OptionalReduxProvider.jsx @@ -1,14 +1,19 @@ +// @ts-check +// Since this is an "internal" component, we check props with typescript not propTypes. +/* eslint-disable react/prop-types */ import React from 'react'; -import PropTypes from 'prop-types'; import { Provider } from 'react-redux'; /** - * @memberof module:React + * Optional Redux provider, that wraps components with a redux provider if needed * @param {Object} props + * @param {import('redux').Store|null} props.store + * @param {React.ReactNode} props.children */ -export default function OptionalReduxProvider({ store, children }) { +export default function OptionalReduxProvider({ store = null, children }) { if (store === null) { - return children; + // eslint-disable-next-line react/jsx-no-useless-fragment + return <>{children}; } return ( @@ -17,12 +22,3 @@ export default function OptionalReduxProvider({ store, children }) { ); } - -OptionalReduxProvider.propTypes = { - store: PropTypes.object, // eslint-disable-line - children: PropTypes.node.isRequired, -}; - -OptionalReduxProvider.defaultProps = { - store: null, -}; diff --git a/src/react/PageWrap.jsx b/src/react/PageWrap.jsx index d7130cd73..7454625fa 100644 --- a/src/react/PageWrap.jsx +++ b/src/react/PageWrap.jsx @@ -3,13 +3,12 @@ import React, { useEffect } from 'react'; import { useLocation } from 'react-router-dom'; -import { sendPageEvent } from '../analytics'; +import { sendPageEvent } from '../analytics/index.js'; /** * A Wrapper component that calls `sendPageEvent` when it becomes active. * * @see {@link module:frontend-platform/analytics~sendPageEvent} - * @memberof module:React * @param {Object} props */ export default function PageWrap({ children }) { diff --git a/src/react/hooks.js b/src/react/hooks.js index b1d4e219e..275db4285 100644 --- a/src/react/hooks.js +++ b/src/react/hooks.js @@ -1,7 +1,7 @@ /* eslint-disable import/prefer-default-export */ import { useEffect } from 'react'; -import { subscribe, unsubscribe } from '../pubSub'; -import { sendTrackEvent } from '../analytics'; +import { subscribe, unsubscribe } from '../pubSub.js'; +import { sendTrackEvent } from '../analytics/index.js'; /** * A React hook that allows functional components to subscribe to application events. This should @@ -9,7 +9,6 @@ import { sendTrackEvent } from '../analytics'; * provide necessary data to a given component, rather than utilizing a non-React-like Pub/Sub * mechanism. * - * @memberof module:React * @param {string} type * @param {function} callback */ @@ -27,7 +26,6 @@ export const useAppEvent = (type, callback) => { * A React hook that tracks user's preferred color scheme (light or dark) and sends respective * event to the tracking service. * - * @memberof module:React */ export const useTrackColorSchemeChoice = () => { useEffect(() => { diff --git a/src/react/hooks.test.jsx b/src/react/hooks.test.jsx index 48623a3b3..25b39a052 100644 --- a/src/react/hooks.test.jsx +++ b/src/react/hooks.test.jsx @@ -1,6 +1,6 @@ import { renderHook } from '@testing-library/react-hooks'; -import { useTrackColorSchemeChoice } from './hooks'; -import { sendTrackEvent } from '../analytics'; +import { useTrackColorSchemeChoice } from './hooks.js'; +import { sendTrackEvent } from '../analytics/index.js'; jest.mock('../analytics'); diff --git a/src/react/index.js b/src/react/index.js index 0985d9271..c5717dad0 100644 --- a/src/react/index.js +++ b/src/react/index.js @@ -1,16 +1,20 @@ /** - * #### Import members from **@edx/frontend-platform/react** + * **Import members from `@openedx/frontend-platform/react`** + * * The React module provides a variety of React components, hooks, and contexts for use in an * application. * * @module React */ -export { default as AppContext } from './AppContext'; -export { default as AppProvider } from './AppProvider'; -export { default as AuthenticatedPageRoute } from './AuthenticatedPageRoute'; -export { default as ErrorBoundary } from './ErrorBoundary'; -export { default as ErrorPage } from './ErrorPage'; -export { default as LoginRedirect } from './LoginRedirect'; -export { default as PageWrap } from './PageWrap'; -export { useAppEvent } from './hooks'; +export { default as AppContext } from './AppContext.jsx'; +export { default as AppProvider } from './AppProvider.jsx'; +export { default as AuthenticatedPageRoute } from './AuthenticatedPageRoute.jsx'; +export { default as ErrorBoundary } from './ErrorBoundary.jsx'; +export { default as ErrorPage } from './ErrorPage.jsx'; +export { default as LoginRedirect } from './LoginRedirect.jsx'; +export { default as PageWrap } from './PageWrap.jsx'; +export { useAppEvent } from './hooks.js'; + +// Export types too - required for interfaces to be documented by TypeDoc: +/** @typedef {import('./AppContext.js').IAppContext} IAppContext */ diff --git a/src/scripts/GoogleAnalyticsLoader.js b/src/scripts/GoogleAnalyticsLoader.js index 290a7a1fc..63c9b17da 100644 --- a/src/scripts/GoogleAnalyticsLoader.js +++ b/src/scripts/GoogleAnalyticsLoader.js @@ -1,6 +1,5 @@ /** * @implements {GoogleAnalyticsLoader} - * @memberof module:GoogleAnalytics */ class GoogleAnalyticsLoader { constructor({ config }) { diff --git a/src/scripts/GoogleAnalyticsLoader.test.js b/src/scripts/GoogleAnalyticsLoader.test.js index cca57edee..b424b14eb 100644 --- a/src/scripts/GoogleAnalyticsLoader.test.js +++ b/src/scripts/GoogleAnalyticsLoader.test.js @@ -1,4 +1,4 @@ -import { GoogleAnalyticsLoader } from './index'; +import { GoogleAnalyticsLoader } from './index.js'; const googleAnalyticsId = 'test-key'; diff --git a/src/scripts/index.js b/src/scripts/index.js index 3c627f0cc..09eeee20d 100644 --- a/src/scripts/index.js +++ b/src/scripts/index.js @@ -1,2 +1,2 @@ /* eslint-disable import/prefer-default-export */ -export { default as GoogleAnalyticsLoader } from './GoogleAnalyticsLoader'; +export { default as GoogleAnalyticsLoader } from './GoogleAnalyticsLoader.js'; diff --git a/src/testing/index.js b/src/testing/index.js index 422ebe392..c664b4d0a 100644 --- a/src/testing/index.js +++ b/src/testing/index.js @@ -1,9 +1,10 @@ /** - * #### Import members from **@edx/frontend-platform/testing** + * **Import members from `@openedx/frontend-platform/testing`** + * * The testing module provides helpers for writing tests in Jest. * * @module Testing */ -export { default as initializeMockApp } from './initializeMockApp'; -export { default as mockMessages } from './mockMessages'; +export { default as initializeMockApp } from './initializeMockApp.js'; +export { default as mockMessages } from './mockMessages.js'; diff --git a/src/testing/initializeMockApp.js b/src/testing/initializeMockApp.js index 27f50c1aa..c5676ff4c 100644 --- a/src/testing/initializeMockApp.js +++ b/src/testing/initializeMockApp.js @@ -1,9 +1,9 @@ -import { configure as configureAnalytics, MockAnalyticsService } from '../analytics'; -import { configure as configureI18n } from '../i18n'; -import { configure as configureLogging, MockLoggingService } from '../logging'; -import { configure as configureAuth, MockAuthService } from '../auth'; -import { getConfig } from '../config'; -import mockMessages from './mockMessages'; +import { configure as configureAnalytics, MockAnalyticsService } from '../analytics/index.js'; +import { configure as configureI18n } from '../i18n/index.js'; +import { configure as configureLogging, MockLoggingService } from '../logging/index.js'; +import { configure as configureAuth, MockAuthService } from '../auth/index.js'; +import { getConfig } from '../config.js'; +import mockMessages from './mockMessages.js'; /** * Initializes a mock application for component testing. The mock application includes @@ -41,7 +41,6 @@ import mockMessages from './mockMessages'; * an array is provided, duplicate keys are resolved with the last-one-in winning. * @param {UserData|null} [options.authenticatedUser] A UserData object representing the * authenticated user. This is passed directly to MockAuthService. - * @memberof module:Testing */ export default function initializeMockApp({ messages = mockMessages, diff --git a/src/testing/initializeMockApp.test.js b/src/testing/initializeMockApp.test.js index 5e5b18668..4c6eefd53 100644 --- a/src/testing/initializeMockApp.test.js +++ b/src/testing/initializeMockApp.test.js @@ -1,21 +1,21 @@ -import initializeMockApp from './initializeMockApp'; +import initializeMockApp from './initializeMockApp.js'; import { getAnalyticsService, MockAnalyticsService, sendTrackEvent, -} from '../analytics'; +} from '../analytics/index.js'; import { MockAuthService, ensureAuthenticatedUser, getAuthService, getLoginRedirectUrl, setAuthenticatedUser, -} from '../auth'; +} from '../auth/index.js'; import { getLoggingService, logInfo, MockLoggingService, -} from '../logging'; +} from '../logging/index.js'; describe('initializeMockApp', () => { it('should create mock analytics, auth, and logging services, and a real i18n service', () => { diff --git a/src/testing/mockMessages.js b/src/testing/mockMessages.js index 12c89aa0a..f8129f1aa 100644 --- a/src/testing/mockMessages.js +++ b/src/testing/mockMessages.js @@ -1,6 +1,5 @@ /** * An empty messages object suitable for fulfilling the i18n service's contract. - * @memberof module:Testing */ const messages = { ar: {}, diff --git a/src/utils.js b/src/utils.js index 7d7412839..3e7508701 100644 --- a/src/utils.js +++ b/src/utils.js @@ -1,5 +1,6 @@ +// @ts-check /** - * #### Import members from **@edx/frontend-platform** + * **Import members from `@edx/frontend-platform`** * * @module Utilities */ @@ -134,8 +135,9 @@ export function convertKeyNames(object, nameMap) { parser.host; // => "example.com:3000" * https://gist.github.com/jlong/2428561 * - * @param {string} - * @returns {Object} + * @param {string} url The URL to parse + * @deprecated Just use the URL global instead: `new URL(str)` or `new URL(str, location.href)` + * @returns {HTMLAnchorElement|Record} */ export function parseURL(url) { if (typeof document !== 'undefined') { @@ -149,13 +151,11 @@ export function parseURL(url) { /** * Given a string URL return the path of the URL - * - * - * @param {string} + * @param {string} url * @returns {string} */ export function getPath(url) { - return typeof document !== 'undefined' ? parseURL(url)?.pathname : ''; + return new URL(url, window?.location.href ?? 'https://example.com')?.pathname || ''; } /** diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 000000000..aa6c7e2b7 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "allowJs": true, + "declaration": true, + "declarationDir": "types", + "emitDeclarationOnly": true, + "declarationMap": true, + "strict": true, + "jsx": "react", + "noImplicitAny": false, + "resolveJsonModule": true, + "esModuleInterop": true + }, + "include": ["./src/"] +}