add openLocalFileWithConfirmation

This checks if the document is dirty and asks for confirmation if it is. Then it opens the passed in file object.

Other changes:
- example-app is updated to test this
- s3-share-provider is removed all-providers.html to prevent warning about it not being valid
- typo fixed in s3-provider comment
- npm yalc commands updated to match other projects
- readme updated with yalc instructions
- new providers.md started to document the providers

doc/providers.md

@@ -0,0 +1,40 @@
+# Providers
+
+Available provider names:
+- googleDrive
+- interactiveApi
+- lara
+- localFile
+- localStorage
+- postMessage
+- readOnly
+- s3-provider
+- testProvider
+- url-provider
+
+Legacy providers:
+- LegacyGoogleDriveProvider (googleDrive)
+
+## postMessage
+This is a special provider. It should **not** be added to the client's list of providers when the client configures the CFM. 
+
+To use this provider the url param `saveSecondaryFileViaPostMessage` should be set. Currently any value works including "false" or "no", but that might change in the future so a value of "yes" or "true" is recommended.
+
+If there is no other provider that has the capability of `export: 'auto'`, then this *postMessage* provider will be used when the client calls `saveAsExport`. Currently the only other provider which has an `export: 'auto'` is the testProvider. When an `export: 'auto'` provider is found the CFM will use this provider's `saveAsExport` method instead of the default behavior of CFM's `saveAsExport`. **TODO** document what the default behavior of saveAsExport is.
+
+The *postMessage* provider's `saveAsExport` sends a message to the parent window:
+```js
+{
+    action: "saveSecondaryFile",
+    extension: metadata.extension  // file extension if known
+    mimeType: metadata.mimeType,   // file type if known
+    content                        // the current file content
+}
+```
+
+Notes:
+This provider will be added to the list of providers configured by the client if the URL param `saveSecondaryFileViaPostMessage` is set.
+
+This provider only supports the export capability. This export capability is only enabled if the url param `saveSecondaryFileViaPostMessage` is set. So adding this provider to the CFM config will have no effect if the the URL parameter is not also set. 
+
+## TODO: add info on each of the other providers

package.json

@@ -106,7 +106,8 @@
     "publish:npm:latest:preview": "npm publish --access public --dry-run",
     "publish:npm:next": "npm publish --access public --tag next",
     "publish:npm:next:preview": "npm publish --access public --tag next --dry-run",
-    "publish:yalc": "npx yalc publish",
+    "yalc:publish": "npx yalc publish --push",
+    "yalc:unpublish": "npx yalc installations clean @concord-consortium/cloud-file-manager",
     "strings:build": "strip-json-comments src/code/utils/lang/en-US-master.json > src/code/utils/lang/en-US.json",
     "strings:pull:usage": "echo Usage: `npm run strings:pull -- -a <poeditor_api_key>`",
     "strings:pull": "./bin/strings-pull-project.sh",

readme.md

@@ -7,6 +7,8 @@ The Cloud File Manager is a Javascript library that enables applications to save
 * Local and remote read-only files
 * Browser LocalStorage (used mostly for development/testing)
 
+[More details on the providers](doc/providers.md)
+
 ## Development Setup
     npm install
     npm run build
@@ -26,6 +28,26 @@ More info:
   4. Make the cert files: `mkcert -cert-file localhost.pem -key-file localhost.key localhost 127.0.0.1 ::1`
   5. Run `npm run start:secure` to run `webpack-dev-server` in development mode with hot module replacement
 
+### Testing in CODAPv3 and other projects
+
+The CFM is used as a npm library in CODAPv3, and possibly other projects as well. As you're making changes to this library, it can be helpful to test those changes within client projects without deploying. This can be done with yalc.
+
+[yalc](https://www.npmjs.com/package/yalc) provides an alternative to `npm link`. It acts as a very simple local repository for locally developed packages that can be shared across a local environment. It provides a better workflow than `npm | yarn link` for package authors. There are scripts in package.json to make this easier.
+
+To publish an in-development version of the CFM library, run:
+
+`npm run yalc:publish`
+
+To consume an in-development version of the CFM library, in the root directory of the client project:
+
+`npx yalc add @concord-consortium/cloud-file-manager`
+
+To update all clients that are using the in-development version of CFM, in the CFM project:
+
+`npm run yalc:publish`
+
+`yalc` modifies the `package.json` of the client project with a link to the local `yalc` repository. _This is a good thing!_ as it makes it obvious when you're using an in-development version of a library and serves as a reminder to install a fully published version before pushing to GitHub, etc. It also means that running `npm install` in the client project will not break the setup.
+
 ## Deployment
 
 Deployments are based on the contents of the /dist folder and are built automatically by GitHub Actions for each branch and tag pushed to GitHub.

src/assets/examples/all-providers.html

@@ -40,7 +40,6 @@
             "name": "documentStore",
             "patch": true
           },
-          "s3-share-provider"
         ],
         ui: {
           menu: CloudFileManager.DefaultMenu,

src/assets/examples/example-app/index.html

@@ -72,6 +72,14 @@
       function openLocalFile(e) {
         cfmClient && cfmClient.openLocalFile(e.target.files[0]);
       }
+
+      function openLocalFileWithConfirmation(e) {
+        cfmClient && cfmClient.openLocalFileWithConfirmation(e.target.files[0]);
+      }
+
+      function clearInput(event) {
+        event.target.value = null;
+      }
     </script>
   </head>
   <body>
@@ -90,10 +98,16 @@ <h2>Demo App</h2>
       <button onclick="saveSecondaryFileAs()">Export Separate File</button>
     </div>
     <div>
-      Import Local File: <input type="file" onchange="importLocalFile(event)">
+      Import Local File: 
+      <input type="file" onchange="importLocalFile(event)" onclick="clearInput(event)">
+    </div>
+    <div>
+      Open Local File:
+      <input type="file" onchange="openLocalFile(event)" onclick="clearInput(event)">
     </div>
     <div>
-      Open Local File: <input type="file" onchange="openLocalFile(event)">
+      Open Local File with Confirmation: 
+      <input type="file" oninput="openLocalFileWithConfirmation(event)" onclick="clearInput(event)">
     </div>
     <script type="text/javascript">
       var cfm = parent && parent.CloudFileManager ? parent.CloudFileManager : null,

src/code/client.ts

@@ -485,6 +485,15 @@ class CloudFileManagerClient {
     })
   }
 
+  openLocalFileWithConfirmation(file: any, callback: OpenSaveCallback = null) {
+    const openFile = () => this.openLocalFile(file, callback)
+    if (!this.state.dirty) {
+      return openFile()
+    } else {
+      return this.confirm(tr('~CONFIRM.OPEN_FILE'), openFile)
+    }  
+  }
+
   importLocalFile(file: any, callback: (data: any) => void = null) {
     return this.readLocalFile(file, (data: any) => {
       return this.importData(data, callback)

src/code/providers/s3-provider.ts

@@ -13,7 +13,7 @@ import tr from '../utils/translate'
 
 // New method for sharing read only documents using S3.
 // The readWrite key must be retained in the original document
-// so that the shared document can be upadted.
+// so that the shared document can be updated.
 // Based on the historical `document-store-share-provider`
 class S3Provider extends ProviderInterface {
   public static Name = 's3-provider'