Merge branch 'main' into export-lodash-intersection-function

Author: brandongregoryscott

.gitignore

@@ -82,6 +82,7 @@ web_modules/
 # Nuxt.js build / generate output
 .nuxt
 dist
+dist-global
 
 # Gatsby files
 .cache/

.travis.yml

@@ -9,6 +9,7 @@ before_script:
 script:
 - npm run build
 - npm run coverage
+- npm run test-cypress
 - codecov --disable=gcov
 notifications:
   slack:

.vscode/settings.json

@@ -14,15 +14,19 @@
     "csharp.format.enable": true,
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true,
-    "editor.rulers": [100],
+    "editor.rulers": [
+        100
+    ],
     "json.schemas": [
         {
-            "fileMatch": ["cypress.json"],
+            "fileMatch": [
+                "cypress.json"
+            ],
             "url": "https://on.cypress.io/cypress.schema.json"
         }
     ],
     "prettier.requireConfig": true,
     "trailing-spaces.trimOnSave": true,
     "typescript.preferences.quoteStyle": "double",
-    "typescript.tsdk": "./frontend/node_modules/typescript/lib"
-}
+    "typescript.tsdk": "./node_modules/typescript/lib"
+}

CONTRIBUTING.md

@@ -1,3 +1,18 @@
 # How to Contribute
 
-Information on contributing to this repo is in the [Contributing Guide](https://github.com/AndcultureCode/AndcultureCode/blob/master/CONTRIBUTING.md) in the Home repo.
+## Considerations
+This repo is now distributing packages for both module loaded applications as well as global distribution for things such as websites.  What this means is:
+
+1.  When adding new peer dependencies to this repo, please account for them in one of the following ways:
+    - Bundle the dependency as part of this package. Add these dependencies by updating [dependency-externals.json](./dependency-externals.json).
+    - Externalize the dependency.  This forces the consumer to reference the dependency using `<script />` tags.  Add these dependencies by updating [dependency-bundles.json](./dependency-bundles.json).
+2.  When adding new external peer dependencies, please make sure to perform the following:
+    - Add any new needed `<script />` peer dependency references to  [test-global-distribution.html](./test-global-distribution.html).  Please use a reliable CDN such as https://unpkg.com or https://cdnjs.cloudflare.com.
+    -  Add a small, quick example to test that peer dependency within [test-global-distribution.html](./test-global-distribution.html).  You will need to run `npm run build` in order to regenerate the global package beforehand.  Open up the HTML file in your browser and validate there are no javascript errors.
+3.  We need to be careful of loosely adding new peer dependencies to this repo.  Adding new peer dependencies to this repo means that the global package will slowly but surely increase in size with peer dependency code (if bundling) OR force consumers to pre-load the peer dependencies (if excluding from bundling).  Neither of these approaches are ideal.  When considering a new peer dependency, please consider adding an issue to the repo before hand so others can be involved early in the process.
+
+### Automated Testing
+
+This repo uses a simple Cypress test to open and test [test-global-distribution.html](./test-global-distribution.html) to validate there are no javascript errors.  Also, any unhandled dependencies within `package.json/dependencies` will throw errors during the build process.  Make sure you add them either as externals or bundles to prevent these build errors.
+
+Additional information on contributing to this repo is in the [Contributing Guide](https://github.com/AndcultureCode/AndcultureCode/blob/master/CONTRIBUTING.md) in the Home repo.

README.md

@@ -26,6 +26,19 @@ import {
 } from "andculturecode-javascript-core";
 ```
 
+You can also reference the global distribution package within a website which gives you access to the `AndcultureCode` namespace. See the example below
+
+```html
+<script src="https://unpkg.com/browse/andculturecode-javascript-core@[version-number]/dist/global/index.js"></script>
+
+<script>
+    var myAuthObject = AndcultureCode.RouteUtils.queryStringToObject('#token=bada55cafe')
+</script>
+
+```
+
+**NOTE** - This source code relies on several peer dependencies, most of which are not included in this bundled global distribution.  You will likely want to reference these in your website prior to referencing the `andculture-javascript-core` global package.  See [test-global-distribution.html](./test-global-distribution.html) for the full list of dependencies.  Also note that peer dependencies are only required if your code will be executing code paths that utilize any of those peer dependencies.
+
 ## Documentation
 
 [Full API documentation](docs/README.md)

cypress.json

@@ -0,0 +1,3 @@
+{
+    "video": false
+}

cypress/integration/test-global-distribution.html.spec.js

@@ -0,0 +1,15 @@
+/// <reference types="cypress" />
+
+context('test-global-distribution.html', () => {
+  it('when visiting then does not throw any errors', () => {
+
+    /*
+      The following will load the given HTML file, read in any external dependencies via script
+      tags, and proceed to execute various code paths to validate those external dependencies are
+      properly loaded.
+    */
+
+    // Arrange, Act, Assert
+    cy.visit('test-global-distribution.html');
+  })
+})

cypress/plugins/index.js

@@ -0,0 +1,21 @@
+/// <reference types="cypress" />
+// ***********************************************************
+// This example plugins/index.js can be used to load plugins
+//
+// You can change the location of this file or turn off loading
+// the plugins file with the 'pluginsFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/plugins-guide
+// ***********************************************************
+
+// This function is called when a project is opened or re-opened (e.g. due to
+// the project's config changing)
+
+/**
+ * @type {Cypress.PluginConfig}
+ */
+module.exports = (on, config) => {
+  // `on` is used to hook into various events Cypress emits
+  // `config` is the resolved Cypress config
+}

cypress/support/commands.js

@@ -0,0 +1,25 @@
+// ***********************************************
+// This example commands.js shows you how to
+// create various custom commands and overwrite
+// existing commands.
+//
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add("login", (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add("drag", { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add("dismiss", { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite("visit", (originalFn, url, options) => { ... })

cypress/support/index.js

@@ -0,0 +1,20 @@
+// ***********************************************************
+// This example support/index.js is processed and
+// loaded automatically before your test files.
+//
+// This is a great place to put global configuration and
+// behavior that modifies Cypress.
+//
+// You can change the location of this file or turn off
+// automatically serving support files with the
+// 'supportFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/configuration
+// ***********************************************************
+
+// Import commands.js using ES2015 syntax:
+import './commands'
+
+// Alternatively you can use CommonJS syntax:
+// require('./commands')