Merge pull request #69 from readium/feature/es-refactor

ES2015+ refactoring and project restructuring

.editorconfig

@@ -0,0 +1,6 @@
+root = true
+
+[*.js]
+indent_style = space
+indent_size = 2
+max_line_length = 100

.eslintrc

@@ -0,0 +1,7 @@
+{
+  "env": {
+    "browser": true,
+    "es6": true
+  },
+  "extends": "airbnb-base"
+}

.gitignore

@@ -1,7 +1,22 @@
 .history
 .DS_Store
-build-output
+dist
 node_modules
 build.txt
 http.log
 api-docs
+
+# JetBrains IDE
+# User-specific stuff:
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/dictionaries
+
+# Sensitive or high-churn files:
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.xml
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml

.travis.yml

@@ -15,7 +15,7 @@ env:
 #before_install:
 #- npm install -g grunt-cli
 install:
-- npm run prepare:all
+- npm install
 script:
 - npm run build
 - npm run test:travis

README.md

@@ -1,6 +1,6 @@
 # readium-cfi-js
 
-**EPUB3 CFI utility library written in Javascript.**
+**EPUB3 CFI utility library in JavaScript**
 
 This is a software component used by other Readium projects, see https://github.com/readium/readium-shared-js
 
@@ -12,165 +12,83 @@ This is a software component used by other Readium projects, see https://github.
 See [license.txt](./license.txt).
 
 
-## Prerequisites
+## Installation
 
-* A decent terminal. On Windows, GitShell works great ( http://git-scm.com ), GitBash works too ( https://msysgit.github.io ), and Cygwin adds useful commands ( https://www.cygwin.com ).
-* NodeJS ( https://nodejs.org ) **v4+** (Note that NodeJS v6+ and NPM v3+ are now supported, including NodeJS v7+ and NPM v4+)
-* Optionally: Yarn ( https://yarnpkg.com ) **v0.23+**
-
-
-## Development
-
-Follow [this image link](readium-cfi-js_build_tasks.png) to see a flowchart for this project's build tasks (click on the "raw" button for the full size diagram).
-
-
-**Initial setup:**
-
-* `npm run prepare:all` (to perform required preliminary tasks, like patching code before building)
-* OR: `yarn run prepare:yarn:all` (to use Yarn instead of NPM for node_module management)
-
-Note that in some cases, administrator rights may be needed in order to install dependencies, because of NPM-related file access permissions (the console log would clearly show the error). Should this be the case, running `sudo npm run prepare:all` usually solves this.
-
-Note that the above command executes the following:
-
-* `npm install` (to download dependencies defined in `package.json` ... note that the `--production` option can be used to avoid downloading development dependencies, for example when testing only the pre-built `build-output` folder contents)
-* `npm update` (to make sure that the dependency tree is up to date)
-
-**Typical workflow:**
-
-* Hack away! (mostly the source code in the `js` and `plugins` folders)
-* `npm run build` (to update the RequireJS bundles in the build output folder)
-* `npm run http:watch` (to launch an http server with live-reload, automatically opens a web browser instance to the HTML files in the `dev` folder)
-* `npm run http` (same as above, but without watching for file changes (no automatic rebuild))
-
-**Unit tests:**
-
-* `npm run test` (Karma launcher)
-
-Travis (Continuous Integration): https://travis-ci.org/readium/readium-cfi-js/
-
-## NPM (Node Package Manager)
-
-All packages "owned" and maintained by the Readium Foundation are listed here: https://www.npmjs.com/~readium
-
-Note that although Node and NPM natively use the CommonJS format, Readium modules are currently only defined as AMD (RequireJS).
-This explains why Browserify ( http://browserify.org ) is not used by this Readium project.
-More information at http://requirejs.org/docs/commonjs.html and http://requirejs.org/docs/node.html
+### Using npm / yarn
 
-* Make sure `npm install readium-cfi-js` completes successfully ( https://www.npmjs.com/package/readium-cfi-js )
-* Execute `npm run http`, which opens a web browser to a basic RequireJS bootstrapper located in the `dev` folder (this is *not* a fully-functioning application!)
-* To see an actual application that uses this "readium-cfi-js" component, try "readium-js-viewer" ( https://www.npmjs.com/package/readium-js-viewer )
+`npm install readium-cfi-js` or `yarn add readium-cfi-js`
 
-Note: the `--dev` option after `npm install readium-cfi-js` can be used to force the download of development dependencies,
-but this is kind of pointless as the code source and RequireJS build configuration files are missing.
-See below if you need to hack the code.
+### Importing
 
+**This library is bundled in UMD and ES module formats.**
 
-## How to use (RequireJS bundles / AMD modules)
-
-The `build-output` directory contains common CSS styles, as well as two distinct folders:
-
-### Single bundle
-
-The `_single-bundle` folder contains `readium-cfi-js_all.js` (and its associated source-map file, as well as a RequireJS bundle index file (which isn't actually needed at runtime, so here just as a reference)),
-which aggregates all the required code (external library dependencies included, such as Underscore, jQuery, etc.),
-as well as the "Almond" lightweight AMD loader ( https://github.com/jrburke/almond ).
+- CommonJS
+```javascript
+const EPUBcfi = require('readium-cfi-js');
+```
 
-This means that the full RequireJS library ( http://requirejs.org ) is not actually needed to bootstrap the AMD modules at runtime,
-as demonstrated by the HTML file in the `dev` folder (trimmed for brevity):
+- ES Module
+```javascript
+import * as EPUBcfi from 'readium-cfi-js';
+```
 
+- Globally with `window.EPUBcfi`
 ```html
-<html>
-<head>
-
-<!-- main code bundle, which includes its own Almond AMD loader (no need for the full RequireJS library) -->
-<script type="text/javascript" src="../build-output/_single-bundle/readium-cfi-js_all.js"> </script>
-
-<!-- index.js calls into the above library -->
-<script type="text/javascript" src="./index.js"> </script>
-
-</head>
-<body>
-<div id="viewport"> </div>
-</body>
-</html>
+<script src="readium-cfi.umd.js"></script>
 ```
 
-### Multiple bundles
-
-
-The `_multiple-bundles` folder contains several Javascript bundles (and their respective source-map files, as well as RequireJS bundle index files):
-
-
-* `readium-cfi-js.js`: The aggregated CFI library modules
-
-In addition, the folder contains the full `RequireJS.js` library ( http://requirejs.org ), as the above bundles do no include the lightweight "Almond" AMD loader ( https://github.com/jrburke/almond ). JQuery is also part of the build output.
+## Usage in non-browser environments (Node)
+Currently not supported as the implementation depends on jQuery and the DOM. 
 
-Usage is demonstrated by the HTML file in the `dev` folder (trimmed for brevity):
+A subset of the API could work without a browser, which may be planned for a future release.
 
-```html
-<html>
-<head>
+## Development
 
-<!-- full RequireJS library -->
-<script type="text/javascript" src="../build-output/_multiple-bundles/RequireJS.js"> </script>
+**Prerequisites:**
 
-<!-- JQuery -->
-<script type="text/javascript" src="../build-output/_multiple-bundles/jquery.js"> </script>
+* A decent terminal. On Windows, GitShell works great ( http://git-scm.com ), GitBash works too ( https://msysgit.github.io ), and Cygwin adds useful commands ( https://www.cygwin.com ).
+* NodeJS ( https://nodejs.org ) **v4+** (Note that NodeJS v6+ and NPM v3+ are now supported, including NodeJS v7+ and NPM v4+)
 
 
+**Initial setup:**
 
-<!-- individual bundles: -->
+* `npm install` (to download dependencies defined in `package.json` ... note that the `--production` option can be used to avoid downloading development dependencies, for example when testing only the pre-built `dist` folder contents)
 
-<!-- The Readium CFI library -->
-<script type="text/javascript" src="../build-output/_multiple-bundles/readium-cfi-js.js"> </script>
+**Typical workflow:**
 
+* Hack away! (mostly the source code in `./src` and `./spec/models` )
+* `npm run build` (to update the output bundles in the `dist` folder)
 
-<!-- index.js calls into the above libraries -->
-<script type="text/javascript" src="./index.js"> </script>
+**Unit tests:**
 
-</head>
-<body>
-<div id="viewport"> </div>
-</body>
-</html>
-```
+* `npm run test` (Karma launcher)
 
+Travis (Continuous Integration): https://travis-ci.org/readium/readium-cfi-js/
 
-Note how the various sets of AMD modules can be invoked on-demand (lazy) using the `bundles` RequireJS configuration directive
-(this eliminates the apparent opacity of such as large container of library dependencies):
 
+## Bundled outputs
 
-```html
+The `dist` directory contains bundled scripts in two module formats:
 
-<script type="text/javascript">
-requirejs.config({
-    baseUrl: '../build-output/_multiple-bundles'
-});
-</script>
+### UMD - [Universal Module Definition](https://github.com/umdjs/umd)
 
-<script type="text/javascript" src="../build-output/_multiple-bundles/readium-cfi-js.js.bundles.js"> </script>
+`readium-cfi.umd.js` (and its associated source-map file),
+which aggregates all the required code (external library dependencies included, such as jQuery, etc.)
 
-```
+You can include this as CommonJS/AMD or with the global `EPUBcfi`
 
+Works best for when using _Browserify_ or _RequireJS_
 
+### ES Modules
 
+`readium-cfi.esm.js` (and its associated source-map file),
+also aggregates all the required code
 
-## CSON vs. JSON (package.json)
+Works best for _rollup.js_ or _webpack_
 
-CSON = CoffeeScript-Object-Notation ( https://github.com/bevry/cson )
 
-Running the command `npm run cson2json` will re-generate the `package.json` JSON file.
-For more information, see comments in the master `package.cson` CSON file.
 
-Why CSON? Because it is a lot more readable than JSON, and therefore easier to maintain.
-The syntax is not only less verbose (separators, etc.), more importantly it allows *comments* and *line breaking*!
+## NPM package
 
-Although these benefits are not so critical for basic "package" definitions,
-here `package.cson/json` declares relatively intricate `script` tasks that are used in the development workflow.
-`npm run SCRIPT_NAME` offers a lightweight technique to handle most build tasks,
-as NPM CLI utilities are available to perform cross-platform operations (agnostic to the actual command line interface / shell).
-For more complex build processes, Grunt / Gulp can be used, but these build systems do not necessarily offer the most readable / maintainable options.
+All packages "owned" and maintained by the Readium Foundation are listed here: https://www.npmjs.com/~readium
 
-Downside: DO NOT invoke `npm init` or `npm install --save` `--save-dev` `--save-optional`,
-as this would overwrite / update the JSON, not the master CSON!