diff --git a/.editorconfig b/.editorconfig index a4e8f29c..d2c566f3 100644 --- a/.editorconfig +++ b/.editorconfig @@ -5,6 +5,11 @@ charset = utf-8 [*.js] indent_style = tab +indent_size = 4 trim_trailing_whitespace = true insert_final_newline = true +<<<<<<< HEAD end_of_line = lf +======= +end_of_line = crlf +>>>>>>> origin/next diff --git a/.eslintrc b/.eslintrc new file mode 100644 index 00000000..6beb82f7 --- /dev/null +++ b/.eslintrc @@ -0,0 +1,93 @@ +{ + "extends": "eslint:recommended", + + "env": { + "browser": true + }, + + "rules": { + "indent": [2, "tab"], + "no-trailing-spaces": 2, + "linebreak-style": [2, "windows"], + + "curly": [2, "multi-line"], + "dot-location": [2, "property"], + "dot-notation": [2, {"allowKeywords": false}], + "eqeqeq": [2, "allow-null"], + "no-alert": 2, + "no-caller": 2, + "guard-for-in": 2, + "no-empty-label": 2, + "no-eval": 2, + "no-extend-native": 2, + "no-extra-bind": 2, + "no-floating-decimal": 2, + "no-implied-eval": 2, + "no-invalid-this": 2, + "no-iterator": 2, + "no-lone-blocks": 2, + "no-loop-func": 2, + "no-multi-spaces": 2, + "no-multi-str": 2, + "no-native-reassign": 2, + "no-new-func": 2, + "no-new-wrappers": 2, + "no-octal-escape": 2, + "no-proto": 2, + "no-self-compare": 2, + "no-sequences": 2, + "no-throw-literal": 2, + "no-unused-expressions": 2, + "no-useless-call": 2, + "no-void": 2, + "no-warning-comments": 1, + "radix": 2, + "wrap-iife": [2, "inside"], + "strict": [2, "function"], + "no-catch-shadow": 2, + "no-label-var": 2, + "no-shadow-restricted-names": 2, + "no-undef-init": 2, + "no-use-before-define": [2, "nofunc"], + "array-bracket-spacing": 2, + "block-spacing": 2, + "brace-style": [2, "1tbs", {"allowSingleLine": true}], + "camelcase": 2, + "comma-spacing": 2, + "comma-style": 2, + "consistent-this": [2, "self"], + "eol-last": 2, + "func-style": [2, "declaration"], + "key-spacing": 2, + "max-nested-callbacks": [2, 4], + "new-parens": 2, + "no-array-constructor": 2, + "no-lonely-if": 2, + "no-new-object": 2, + "no-multiple-empty-lines": [2, {"max": 1}], + "no-spaced-func": 2, + "no-unneeded-ternary": 2, + "object-curly-spacing": 2, + "one-var": [2, {"initialized": "never"}], + "operator-assignment": 2, + "operator-linebreak": [2, "after"], + "padded-blocks": [2, "never"], + "quote-props": [2, "as-needed", {"keywords": true}], + "quotes": [2, "double", "avoid-escape"], + "semi-spacing": 0, + "semi": [2, "never"], + "space-after-keywords": 2, + "space-before-function-paren": [2, { + "anonymous": "always", + "named": "never" + }], + "space-before-keywords": 2, + "space-in-parens": 2, + "space-infix-ops": [2, {"int32Hint": true}], + "space-unary-ops": 2, + "spaced-comment": [2, "always"], + "max-depth": [2, 4], + "max-len": [2, 80, 4], + "max-statements": [2, 20] + } +} diff --git a/.gitattributes b/.gitattributes index 21256661..3ae175ac 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,7 @@ -* text=auto \ No newline at end of file +<<<<<<< HEAD +* text=auto +======= +* text eol=crlf +*.min.js binary +*.map binary +>>>>>>> origin/next diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..eb0febc9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,834 @@ +# Bug reports + +Use the [issue tracker](https://github.com/lhorie/mithril.js/issues). Do check to make sure your bug hasn't already been filed. Please give the following information, where possible: + +1. The version of Mithril you're using, whether it's the dev version or [the version on npm](http://npm.im/mithril.js). The version on npm may not have all the latest bug fixes, so your bug might very well be fixed in the dev version. +2. The name and version of the browser(s) affected. +3. A detailed explanation of the bug. +4. A test case. The simpler, the better. + +# Feature requests + +Use the [issue tracker](https://github.com/lhorie/mithril.js/issues). Please do the following, where possible: + +1. Check to make sure your suggestion hasn't already been filed. There's a nice collection of some of these feature requests [here](https://github.com/lhorie/mithril.js/issues/802). +2. Clearly denote your issue as a feature request. It helps make the intent clearer. Even better is to denote it in the title. +3. Describe your idea. This is the most important part. +4. Submit, and wait for feedback. Don't forget to drop by the [Gitter room](https://gitter.im/lhorie/mithril.js) to get some publicity. It gets traffic daily. :smile: + +# Contributing + +We welcome any and all contributions. This is a community-driven project. Although we don't have a lot, we do have a few guidelines for contributions. + +1. Please try to adhere to the style guide. Most of it is checked by ESLint. ESLint is also set up to check for other common errors, such as undeclared variables and invalid `typeof` values. +2. Please make sure there are no regressions with your patch. Please don't disable existing tests, and please don't send a PR with new, disabled tests. +3. For any new features introduced, be sure to write new unit tests for it. Maximum coverage is what we want. +4. Try to not leave any extra `TODO`s, `FIXME`s, etc. in your code. ESLint will nag at you until you fix whatever problem it is. + - Note that it's only a warning, not an error. It won't fail the CI tests, and there's a few outstanding ones inside Mithril right now. + - If you must, use a `TODO(): whatever` (or the equivalent `FIXME`, etc.) if it's something you are actively working on, or if it's something more general, file an issue titled "TODO: " and reference the `TODO` comment itself. + +It is assumed that for all contributions you make, you have the appropriate rights to and it may be made available under the MIT License, the license used for this project. + +# Style Guide + +The style is checked with ESLint. This style guide is here for one reason only: consistency. This should work for most code here, but it shouldn't be considered absolute &endash; consistency with the surrounding code is higher priority than following this guide. Also, if you need some sort of hack that doesn't follow this style guide like [Bluebird's `toFastProperties` hack](https://stackoverflow.com/q/24987896), make sure the code is consistent with what's around it, and disable whatever ESLint warnings you need to. (In that case, you would use `no-eval` and `no-unused-expressions`). + +### EditorConfig + +This project has its own [EditorConfig](http://editorconfig.org/). Most common editors either support it natively or have a plugin to support it. Here's links for several editors: + +- [Atom](https://atom.io/packages/editorconfig) +- [Nodepad++](https://github.com/editorconfig/editorconfig-notepad-plus-plus#readme) +- [Sublime Text](https://packagecontrol.io/packages/EditorConfig) +- [Vim](http://www.vim.org/scripts/script.php?script_id=3934) +- [Emacs](https://marmalade-repo.org/packages/editorconfig) +- IntelliJ, WebStorm: You're already set, since it supports EditorConfig natively. +- [Eclipse](https://marketplace.eclipse.org/content/editorconfig-eclipse) +- [Visual Studio](https://visualstudiogallery.msdn.microsoft.com/c8bccfe2-650c-4b42-bc5c-845e21f96328) +- [Xcode](https://github.com/MarcoSero/EditorConfig-Xcode) +- [Komodo](http://komodoide.com/packages/addons/editorconfig/) + +EditorConfig also has [their own curated list](http://editorconfig.org/#download) of plugins. Do note that Text Mate's plugin doesn't support multiple properties used in this repo's `.editorconfig`. + +### Line length + +Please keep line length down to a maximum of 80 characters. + +The only exception to this rule is with long regexes and test names. You can use `// eslint-disable-line max-len` to suppress this. + +### Function length + +Please keep function length to no more than 20 statements, including those in nested blocks. + +The only exceptions are for revealing module wrappers and Mocha `describe` and `context` blocks. If you need to suppress this, you can use `// eslint-disable-line max-statements` at the beginning of the function. + +This isn't checked for the tests, but still, please keep it reasonable. + +### Line endings + +Use Windows-style line endings (i.e. CRLF). + +### Semicolons + +Avoid semicolons. A few resources to help you understand this: [*](http://blog.izs.me/post/2353458699/an-open-letter-to-javascript-leaders-regarding) [*](http://inimino.org/~inimino/blog/javascript_semicolons) [*](http://jamesallardice.com/understanding-automatic-semi-colon-insertion-in-javascript/) + +### Redundant expressions + +Don't use redundant parentheses, curly braces, `undefined`s, ternaries, etc. + +- `var foo = value === 1 ? true : false` is better written as `var foo = value === 1`. +- `var foo = undefined` is better written as `var foo`. +- `return undefined` is better written as `return`. +- `delete(obj.foo)` is better written as `delete obj.foo`. +- As an exception, use an extra set of parentheses when assigning in conditions. + +### Equality testing + +Prefer strict equality (`===`/`!==`) to loose equality (`==`/`!=`), unless you're comparing against `null` or `undefined`, where loose equality (`== null`/`!= null`) is preferred. It's more type-safe with primitives. + +### `eval` and friends + +Never use `eval`, the `Function` constructor, and friends. Those will fail when running under CSP restrictions, and this library should work in those environments. + +### Quotes + +Prefer double quotes to single quotes, but using single quotes to avoid escaping is okay. + +### Strict mode + +Any code not in the global scope should be in strict mode unless there's a good reason it shouldn't be. Browsers run it faster, and there's certain things where it's safer. + +## Comments + +Comments are helpful. Use descriptive comments where needed, so others can read it and understand it. If a non-obvious hack is used, explain it with a comment. But don't repeat yourself with a redundant comment when the code adequately describes itself. + +```js +// Good +var CARD_DECK_SIZE = 52 + +// Shuffle the deck of cards. +for (var i = 0; i < CARD_DECK_SIZE; i++) { + var j = i + (Math.random() * CARD_DECK_SIZE - i)|0 + + var tmp = deck[i] + deck[i] = deck[j] + deck[j] = tmp +} + +// Also good +function toFastProperties(obj) { + // Bluebird's toFastProperties hack. Forces V8 to optimize object as prototype, + // significantly speeding up property access. + + /* eslint-disable no-eval */ + function C() {} + C.prototype = obj + new C() + return + eval(obj) + /* eslint-enable no-eval */ +} + +// Bad +var CARD_DECK_SIZE = 52 + +// Shuffle the deck of cards. +function shuffle(deck) { + for (var i = 0; i < CARD_DECK_SIZE; i++) { + // Generate a random card index to swap at. + var j = i + (Math.random() * CARD_DECK_SIZE - i)|0 + + // Swap the cards at each index. + var tmp = deck[i] + deck[i] = deck[j] + deck[j] = tmp + } +} + +// Also bad +// This function loops through each item in a list, calling `f` with each item +// and their respective index. If the function `f` returns explicitly with +// `false`, iteration stops. This function returns the original list for +// convenience. +function forEach(list, f) { + // Loop through each entry in the list with the loop index `i` + for (var i = 0; i < list.length; i++) { + // Call the function with the current item and index + if (f(list[i], i) === false) { + // If the function explicitly returns `false`, immediately stop + // iteration. + break + } + } + // Return the list, for convenience. + return list +} +``` + +### Magic values + +Prefer constant variables to magic values where it helps with code readability. Also, don't use comments in place of a constant. + +```js +// Good +var CARD_DECK_SIZE = 52 +for (var i = 0; i < CARD_DECK_SIZE; i++) { + var j = i + (Math.random() * CARD_DECK_SIZE - i)|0 + var tmp = a[i] + a[i] = a[j] + a[j] = tmp +} + +// Bad +for (var i = 0; i < 52; i++) { + var j = i + (Math.random() * 52 - i)|0 + var tmp = a[i] + a[i] = a[j] + a[j] = tmp +} + +// Also bad +// Note: 52 cards in a deck +for (var i = 0; i < 52; i++) { + var j = i + (Math.random() * 52 - i)|0 + var tmp = a[i] + a[i] = a[j] + a[j] = tmp +} +``` + +### Initial whitespace + +Start your comments with a space. It's more readable. + +```js +// Good +// This is a comment. + +// Bad +//This is a comment. +``` + +### Grammar and spelling + +Please try to use proper grammar and spelling. Not all of us are perfect English speakers (even us native ones struggle at times), but it's easier to understand down the road when reading the code. + +## Whitespace + +Use vertical whitespace and indentation to your advantage. It helps with readability, and minifiers are astonishingly great at removing this. :stuck_out_tongue_winking_eye: + +```js +// Good +function iterate() { + var index = 0 + var list = [] + while (hasNext()) { + list.push(next(index)) + index++ + } + + for (var i = 0; i < list.length; i++) { + read(list[i]) + } +} + +// Bad +function iterate() { + var index = 0 + var list = [] + while (hasNext()) list.push(next(index++)) + for (var i = 0; i < list.length; i++) read(list[i]) +} + +// Also bad +function iterate() { + var list = [] + for (var index = 0; hasNext(); list.push(next(index++))) {} + for (var i = 0; i < list.length; i++) read(list[i]) +} +``` + +### Trailing whitespace + +Please don't leave trailing spaces, even in blank likes. It makes diffs harder to read. If your [editor supports EditorConfig, or you've downloaded a plugin for it](http://editorconfig.org/#download), you're already set. Otherwise, searching " strip trailing whitespace blank lines" should help you. + +### Indentation and vertical whitespace + +Indent with hard tabs. Each one counts for 4 spaces. + +Never mix tabs and spaces. Don't use smart tabs. + +### Excessive whitespace + +Keep whitespace within reason. Limit vertical whitespace to no more than 1 consecutive blank line, and don't start or end blocks with plain whitespace. Don't use more than one character of horizontal whitespace beyond indentation. + +```js +// Bad +function iterate() { + var index = 0 + var list = [] + + while (hasNext()) { + list.push(next(index)) + index++ + } + + + + for (var i = 0; i < list.length; i++) { + read(list[i]) + } +} + +// Also bad +var a = 2 +// ^^ ^^ +``` + +If you're find yourself resorting to multiple consecutive blank lines to separate logic, consider refactoring the code into smaller functions if possible. + +### Control keywords + +Always surround control keywords (e.g. `if`, `else`, `for`) with whitespace. + +## Operators + +### Binary operators + +Always surround binary keyword operators (e.g. `in`, `instanceof`) with whitespace. + +Always surround any other binary operator with whitespace, including assignment operators. Add line breaks after the operator, not before. + +```js +// Good +var a = 1 + 2 +a = 3 + +var a = 1 + 2 + 3 + 4 + 5 + + 6 + 7 + 8 + 9 + 10 + +// Bad +var a = 1+2 +var a=1+2 +a=3 + +var a = 1 + 2 + 3 + 4 + 5 + + 6 + 7 + 8 + 9 + 10 +``` + +In the event you're casting to a 32-bit integer (i.e. `x|0`), it's okay to omit the whitespace. Mithril doesn't currently have any instances of this, but it may in the future. + +```js +// This is okay +var casted = value|0 +``` + +### Unary operators + +Always use whitespace between an unary keyword operator (e.g. `delete`, `new`) with whitespace. + +Do not use spaces between any other unary operator and the value they apply to. + +```js +// Good +!a +-1 +~1 + +// Bad +! a +- 1 +~ 1 +``` + +## Objects + +### Exterior whitespace + +Do not include space between the opening curly brace and the first object key in single line objects. For multi-line objects, don't include any extra preceding whitespace at the beginning or end. + +```js +// Good +var object = {foo: 1} + +var object = { + foo: 1, + bar: 2, + baz: 3, + quux: "string" +} + +// Bad +var object = { foo: 1 } + +var object = { + + foo: 1, + bar: 2, + baz: 3, + quux: "string" + +} +``` + +### Interior whitespace + +Use no space before an object key and the colon, but use a single space between the colon and value. + +```js +// Good +var object = {foo: 1} + +// Bad +var object = {foo:1} +var object = {foo : 1} +var object = {foo :1} +``` + +### Larger objects + +Non-trivial objects should occupy multiple lines. + +```js +// Good +var object = { + foo: 1, + bar: 2, + baz: 3, + quux: "string" +} + +// Bad +var object = {foo: 1, bar: 2, baz: 3, quux: "string"} +``` + +Prefer plain objects over `new function () {}`, but if you feel the latter is better, use `// eslint-disable-line no-new-func` on the first line. + +### Comma placement + +Commas come last. Also, don't use trailing commas. + +```js +// Good +var object = { + foo: 1, + bar: 2 +} + +// Bad +var object = { + foo: 1, + bar: 2, // Trailing comma +} + +var object = { + foo: 1 +, bar: 2 // Comma first +} + +// Also bad +var object = {foo: 1,} +``` + +### Member access + +When chaining methods and/or properties across multiple lines, dots come first. + +```js +// Good +object + .foo() + .bar() + +// Bad +object. + foo(). + bar() +``` + +### Property quoting + +Quote properties when needed. Never quote valid identifiers. This may lead to some inconsistency in whether properties are quoted or not in the object, but that inconsistency is okay. + +```js +// Good +var object = { + foo: 1, + bar: 2 +} + +var object = { + foo: 1, + "non-identifier": 2 +} + +// Bad +var object = { + "foo": 1, + "bar": 2 +} + +var object = { + "foo": 1, + "non-identifier": 2 +} +``` + +### Iteration + +When iterating objects with `for-in`, filter it with `Object.prototype.hasOwnProperty` first. This may be on the same line if that's the only condition. If this is used more than once, make a local `hasOwn` alias to use like `hasOwn.call(object, prop)`. + +## Variables and declarations + +Use camel case (e.g. `loopIndex`) for variables, pascal case (e.g. `MyClass`) for classes, and upper case with underscores (e.g. `MAX_VALUE`) for constants. + +Use `self` to capture `this` where needed. (i.e. `var self = this`) + +Prefer short but clear, descriptive, and self-documenting variable names. + +Single letter names are generally okay in these contexts: + +- Loop variables: `i`, `j`, etc. +- Function arguments in small, trivial functional utilities: `f`, `g`, etc. +- Standard mathematical algorithms: `x`, `y`, `a`, `b`, etc. + +```js +// Good +function forEach(list, f) { + for (var i = 0; i < list.length; i++) { + f(list[i], i) + } + return list +} + +// Also good +function forEach(list, func) { + for (var index = 0; index < list.length; index++) { + func(list[index], index) + } + return list +} + +// Bad +function iterateArray(listOfEntries, callback) { + for (var index = 0; index < listOfEntries.length; index++) { + callback(listOfEntries[index], index) + } + return listOfEntries +} + +// Also bad +function e(l, c) { + for (var x = 0; x < l.length; x++) { + c(l[x], x) + } + return l +} +``` + +### Multiple variable declarations + +If a variable is assigned a value when it's declared, it gets its own line. + +If a variable is not immediately assigned a value, it may be grouped with others that aren't first assigned values. + +Do group related variables. + +Variable declarations in the init block of a for loop are excluded from this rule, but the number of declarations should still be minimized. + +```js +// Good +var a = 1 +var b = 2 +var c, d + +// Also good +var foo, bar, baz, quux +var spam, eggs, ham +var shouldUpdate, initialize + +// Okay, since it's within a for loop +for (var i = 0, test; (test = foo === 1); i++) { + doSomething(i) +} + +// Bad +var a = 1, b = 2, c, d + +// Also bad +var foo, bar, baz, quux, spam, eggs, ham, shouldUpdate, initialize +``` + +## Assignment + +### Native functions + +Don't assign to native functions or prototypes beyond polyfills. Ever. + +### Function declarations + +Don't assign to a function declaration. Declarations look like static values, so they should be treated that way. There is no difference in size, either. + +```js +// Bad +function foo() { return 1 } +foo = function () { return 2 } + +// Also bad +function foo() { return 1 } +foo = 2 +``` + +### Conditions + +Avoid assigning directly in conditions. If you need to assign in a condition, wrap them in a new set of parentheses. + +```js +// Good +var test = foo === 1 +if (test) { + doSomething() +} + +var test = foo === 1 +for (var i = 0; test; i++) { + doSomething(i) + test = foo === 1 +} + +if ((test = foo === 1)) { + doSomething() +} + +for (var i = 0, test; (test = foo === 1); i++) { + doSomething(i) +} + +// Bad +if (test = foo === 1) { + doSomething() +} + +for (var i = 0, test; test = foo === 1; i++) { + doSomething(i) +} +``` + +## Functions + +Prefer anonymous functions to named functions in expressions where possible + +Prefer named function declarations to assigning a function to a declared variable where possible. + +```js +// Good +setTimeout(function () { doSomething() }, 0) + +function foo() { + return 1 +} + +// Good, uses recursion +setTimeout(function f() { + doSomething() + if (shouldRepeat()) setTimeout(f, 0) +}, 0) + +// Bad +requestAnimationFrame(function foo() { runNext() }) + +var foo = function () { + return 1 +} +``` + +### Anonymous functions + +Anonymous functions must have a single space between `function` and the arguments and between the arguments and the opening brace. + +### Named functions, function declarations + +Named functions and function declarations must have no space between the function name and the arguments and a single space between the arguments and the opening brace. + +## Blocks and conditionals + +### Curly braces + +Curly braces are required for blocks if the body takes up more than one line. This goes for functions as well. They are optional if it fits within one line, but don't be afraid to use them where you see fit. + +Do put an extra space after the first brace and before the final brace in single-line functions. + +```js +// Good +if (condition) doSomething() + +if (condition) { + doSomething() +} + +if (condition) { + doSomething() +} else { + doSomethingElse() +} + +if (condition) { + doSomething() + doSomethingElse() +} + +setTimeout(function () { doSomething() }, 0) + +setTimeout(function () { + doSomething() +}, 0) + +// Bad +if (condition) { doSomething(); doSomethingElse() } + +if (condition) + doSomething() + +setTimeout(function () { doSomething(); doSomethingElse() }, 0) + +setTimeout(function () {doSomething()}, 0) +``` + +### Function declarations + +Function declarations should always take more than one line. + +```js +// Good +function foo() { + return bar +} + +// Bad +function foo() { return bar } +``` + +### `if`-`else` + +Be consistent with braces in `if`-`else` statements. + +```js +// Good +if (condition) doSomething() +else doSomethingElse() + +if (condition) { + doSomething() +} else { + doSomethingElse() +} + +if (condition) { + doSomething() +} else if (anotherCondition) { + doSomethingElse() +} else { + doAnotherThing() +} + +// Okay +if (condition) doSomething() +else if (anotherCondition) doSomethingElse() +else doAnotherThing() + +// Bad +if (condition) doSomething() +else { + doSomethingElse() +} + +if (condition) doSomething() +else if (anotherCondition) { + doSomethingElse() +} else doAnotherThing() + + +if (condition) { + doSomething() +} else doSomethingElse() +``` + +## `do`-`while` loops + +Always use braces. + +```js +// Good +do { + doSomething() +} while (condition) + +// Bad +do doSomething() +while (condition) +``` + +### Empty blocks + +Mark empty blocks as intentionally empty via a comment or similar. Don't just leave an empty block and/or semicolon. + +```js +// Good +for (var i = 0; i < list.length && cond(list[i]); i++) { + // do nothing +} + +// Even better +for (var i = 0; i < list.length; i++) { + if (!cond(list[i])) break +} + +// Bad +for (var i = 0; i < list.length && cond(list[i]); i++) {} + +// Also bad +for (var i = 0; i < list.length && cond(list[i]); i++) { + ; +} + +// Even worse +for (var i = 0; i < list.length && cond(list[i]); i++); +``` + +### Nesting + +Don't nest `if` statements in `else` blocks if you don't need to. + +```js +// Good +if (test) { + doSomething() +} else if (otherTest) { + doSomethingElse() +} + +if (test) { + doSomething() +} else { + if (otherTest) { + doSomethingElse() + } + + doThisOtherThing() +} + +// Bad +if (test) { + doSomething() +} else { + if (otherTest) { + doSomethingElse() + } +} +``` + +Don't nest curly braces beyond 4 levels deep. This includes blocks, loops, and functions, as well as IIFE wrappers. This also includes the tests. There's rarely a reason to go farther, as most of the time, it's a signal to refactor and/or re-organize your code. + +### Brace style + +Put the `else`, `catch`, and `finally` on the same line as its closing brace. diff --git a/Gruntfile.js b/Gruntfile.js new file mode 100755 index 00000000..6cb76731 --- /dev/null +++ b/Gruntfile.js @@ -0,0 +1,387 @@ +/* eslint-env node */ +module.exports = function (grunt) { // eslint-disable-line + + var pkg = grunt.file.readJSON("package.json") + var currentYear = grunt.template.today("yyyy") + var inputFolder = "./docs" + var tempFolder = "./temp" + var archiveFolder = "./archive" + var outputFolder = "../mithril" + + var guide = [ + "auto-redrawing", + "benchmarks", + "community", + "optimizing-performance", + "comparison", + "components", + "getting-started", + "installation", + "integration", + "practices", + "refactoring", + "routing", + "tools", + "web-services" + ] + + var api = [ + "change-log", + "roadmap", + "how-to-read-signatures", + "mithril", + "mithril.computation", + "mithril.deferred", + "mithril.mount", + "mithril.component", + "mithril.prop", + "mithril.redraw", + "mithril.render", + "mithril.deps", + "mithril.request", + "mithril.route", + "mithril.sync", + "mithril.trust", + "mithril.withAttr", + "mithril.xhr" + ] + + var md2htmlTasks = {} + function makeTasks(layout, pages) { + pages.forEach(function (name) { + var src = inputFolder + "/" + name + ".md" + var title = "" + + if (grunt.file.exists(src)) { + title = grunt.file.read(src).split(/\n/)[0].substring(3) + + " - " + } + + md2htmlTasks[name] = { + options: { + layout: inputFolder + "/layout/" + layout + ".html", + templateData: {topic: title} + }, + files: [{ + src: [src], + dest: tempFolder + "/" + name + ".html" + }] + } + }) + } + + makeTasks("guide", guide) + makeTasks("api", api) + + var currentVersionArchiveFolder = archiveFolder + "/v" + pkg.version + + grunt.initConfig({ + // Keep this in sync with the .eslintignore + eslint: { + options: { + extensions: [".js"], + fix: true + }, + all: [ + "**/*.js", + "!node_modules/**", + "!**/*.min.js", + "!archive/**", + "!deploy/**", + "!mithril.closure-compiler-externs.js", + "!docs/layout/lib/**" + ] + }, + + mocha_phantomjs: { // eslint-disable-line camelcase + test: { + src: ["test/index.html", "tests/index.html"], + options: { + reporter: "dot" + } + } + }, + + md2html: md2htmlTasks, + + uglify: { + options: { + banner: [ + "/*", + "Mithril v" + pkg.version, + pkg.homepage, + "(c) 2014-" + currentYear + " " + pkg.author.name, + "License: " + pkg.license, + "*/" + ].join("\n"), + sourceMap: true + }, + mithril: {src: "mithril.js", dest: "mithril.min.js"} + }, + + zip: { + distribution: { + cwd: currentVersionArchiveFolder + "/", + src: [ + currentVersionArchiveFolder + "/mithril.min.js", + currentVersionArchiveFolder + "/mithril.min.js.map", + currentVersionArchiveFolder + "/mithril.js" + ], + dest: currentVersionArchiveFolder + "/mithril.min.zip" + } + }, + + replace: { + options: { + force: true, + patterns: [ + {match: /\.md/g, replacement: ".html"}, + {match: /\$version/g, replacement: pkg.version} + ] + }, + + links: { + expand: true, + flatten: true, + src: [tempFolder + "/**/*.html"], + dest: currentVersionArchiveFolder + "/" + }, + + index: { + src: inputFolder + "/layout/index.html", + dest: currentVersionArchiveFolder + "/index.html" + }, + + commonjs: { + expand: true, + flatten: true, + src: [inputFolder + "/layout/*.json"], + dest: currentVersionArchiveFolder + }, + + cdnjs: { + src: "deploy/cdnjs-package.json", + dest: "../cdnjs/ajax/libs/mithril/package.json" + } + }, + + copy: { + style: { + src: inputFolder + "/layout/style.css", + dest: currentVersionArchiveFolder + "/style.css" + }, + + pages: { + src: inputFolder + "/layout/pages.json", + dest: currentVersionArchiveFolder + "/pages.json" + }, + + lib: { + expand: true, + cwd: inputFolder + "/layout/lib/", + src: "./**", + dest: currentVersionArchiveFolder + "/lib/" + }, + + tools: { + expand: true, + cwd: inputFolder + "/layout/tools/", + src: "./**", + dest: currentVersionArchiveFolder + "/tools/" + }, + + comparisons: { + expand: true, + cwd: inputFolder + "/layout/comparisons/", + src: "./**", + dest: currentVersionArchiveFolder + "/comparisons/" + }, + + unminified: { + src: "mithril.js", + dest: currentVersionArchiveFolder + "/mithril.js" + }, + + minified: { + src: "mithril.min.js", + dest: currentVersionArchiveFolder + "/mithril.min.js" + }, + + readme: { + src: "README.md", + dest: currentVersionArchiveFolder + "/README.md" + }, + + map: { + src: "mithril.min.js.map", + dest: currentVersionArchiveFolder + "/mithril.min.js.map" + }, + + typescript: { + src: "mithril.d.ts", + dest: currentVersionArchiveFolder + "/mithril.d.ts" + }, + + publish: { + expand: true, + cwd: currentVersionArchiveFolder, + src: "./**", + dest: outputFolder + }, + + archive: { + expand: true, + cwd: currentVersionArchiveFolder, + src: "./**", + dest: outputFolder + "/archive/v" + pkg.version + } + }, + + "saucelabs-browsers": { + firefox: { + filter: function (browsers) { + return browsers.filter(function (browser) { + if (browser.browserName !== "firefox") return false + var version = browser.version + return version === "dev" || version === "beta" || + +version >= 38 // The latest ESR version + }) + } + }, + + chrome: { + filter: function (browsers) { + return browsers.filter(function (browser) { + if (browser.browserName !== "chrome") return false + var version = browser.version + return version === "dev" || version === "beta" || + +version >= 41 + }) + } + }, + + ie: { + filter: function (browsers) { + return browsers.filter(function (browser) { + return browser.browserName === "internet explorer" && + !/2003/.test(browser.platform) + }) + } + }, + + edge: { + filter: function (browsers) { + return browsers.filter(function (browser) { + return browser.browserName === "microsoftedge" + }) + } + }, + + safari: { + filter: function (browsers) { + return browsers.filter(function (browser) { + return browser.browserName === "safari" + }) + } + }, + + opera: { + filter: function (browsers) { + return browsers.filter(function (browser) { + return browser.browserName === "opera" + }) + } + } + }, + + saucelabs: { + all: { + options: { + username: process.env.SAUCE_USERNAME, + key: process.env.SAUCE_ACCESS_KEY, + testname: "Mithril Tests " + new Date().toJSON(), + browsers: "<%= saucelabs.browsers %>", + urls: ["http://localhost:8000/test/index.html"], + sauceConfig: { + "record-video": false, + "record-screenshots": false + }, + build: process.env.TRAVIS_JOB_ID, + onTestComplete: function (result, callback) { + var user = process.env.SAUCE_USERNAME + var pass = process.env.SAUCE_ACCESS_KEY + + var url = [ + "https://saucelabs.com/rest/v1", user, "jobs", + result.job_id + ].join("/") + + require("request").put({ + url: url, + auth: {user: user, pass: pass}, + json: {passed: result.passed} + }, function (error, response) { + if (error) { + return callback(error) + } else if (response.statusCode !== 200) { + return callback(new Error( + "Unexpected response status: " + + response.statusCode + "\n ")) + } else { + return callback(null, result.passed) + } + }) + }, + tunnelTimeout: 5 + } + } + }, + + connect: { + server: { + options: { + port: 8888, + base: "." + } + } + }, + + clean: { + options: {force: true}, + generated: [tempFolder] + } + }) + + grunt.loadNpmTasks("grunt-saucelabs-browsers") + grunt.loadNpmTasks("grunt-contrib-clean") + grunt.loadNpmTasks("grunt-contrib-copy") + grunt.loadNpmTasks("grunt-contrib-uglify") + grunt.loadNpmTasks("grunt-md2html") + grunt.loadNpmTasks("grunt-replace") + grunt.loadNpmTasks("grunt-zip") + grunt.loadNpmTasks("grunt-contrib-connect") + grunt.loadNpmTasks("grunt-saucelabs") + grunt.loadNpmTasks("grunt-eslint") + grunt.loadNpmTasks("grunt-mocha-phantomjs") + + grunt.registerTask("build", [ + // "lint", + "test", + "uglify", + "zip", + "md2html", + "replace", + "copy", + "clean" + ]) + + grunt.registerTask("lint", ["eslint:all"]) + grunt.registerTask("test", ["mocha_phantomjs"]) + grunt.registerTask("default", ["build"]) + + grunt.registerTask("sauce", [ + "saucelabs-browsers:all", + "connect", + "saucelabs" + ]) +} diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..7fa48b8d --- /dev/null +++ b/ISSUE_TEMPLATE.md @@ -0,0 +1,18 @@ +### Description: + +[Describe bug here] + +### Steps to Reproduce: + +``` +[Provide a small snippet of code where the incorrect behavior can be seen] +``` + +### Expected: + +[What was the expected behavior] + +### Actual: + +[What actually happened] + diff --git a/archive/v0.2.4/mithril.js b/archive/v0.2.4/mithril.js new file mode 100644 index 00000000..7ddcda53 --- /dev/null +++ b/archive/v0.2.4/mithril.js @@ -0,0 +1,2190 @@ +;(function (global, factory) { // eslint-disable-line + "use strict" + /* eslint-disable no-undef */ + var m = factory(global) + if (typeof module === "object" && module != null && module.exports) { + module.exports = m + } else if (typeof define === "function" && define.amd) { + define(function () { return m }) + } else { + global.m = m + } + /* eslint-enable no-undef */ +})(typeof window !== "undefined" ? window : this, function (global, undefined) { // eslint-disable-line + "use strict" + + m.version = function () { + return "v0.2.4" + } + + var hasOwn = {}.hasOwnProperty + var type = {}.toString + + function isFunction(object) { + return typeof object === "function" + } + + function isObject(object) { + return type.call(object) === "[object Object]" + } + + function isString(object) { + return type.call(object) === "[object String]" + } + + var isArray = Array.isArray || function (object) { + return type.call(object) === "[object Array]" + } + + function noop() {} + + var voidElements = { + AREA: 1, + BASE: 1, + BR: 1, + COL: 1, + COMMAND: 1, + EMBED: 1, + HR: 1, + IMG: 1, + INPUT: 1, + KEYGEN: 1, + LINK: 1, + META: 1, + PARAM: 1, + SOURCE: 1, + TRACK: 1, + WBR: 1 + } + + // caching commonly used variables + var $document, $location, $requestAnimationFrame, $cancelAnimationFrame + + // self invoking function needed because of the way mocks work + function initialize(mock) { + $document = mock.document + $location = mock.location + $cancelAnimationFrame = mock.cancelAnimationFrame || mock.clearTimeout + $requestAnimationFrame = mock.requestAnimationFrame || mock.setTimeout + } + + // testing API + m.deps = function (mock) { + initialize(global = mock || window) + return global + } + + m.deps(global) + + /** + * @typedef {String} Tag + * A string that looks like -> div.classname#id[param=one][param2=two] + * Which describes a DOM node + */ + + function parseTagAttrs(cell, tag) { + var classes = [] + var parser = /(?:(^|#|\.)([^#\.\[\]]+))|(\[.+?\])/g + var match + + while ((match = parser.exec(tag))) { + if (match[1] === "" && match[2]) { + cell.tag = match[2] + } else if (match[1] === "#") { + cell.attrs.id = match[2] + } else if (match[1] === ".") { + classes.push(match[2]) + } else if (match[3][0] === "[") { + var pair = /\[(.+?)(?:=("|'|)(.*?)\2)?\]/.exec(match[3]) + cell.attrs[pair[1]] = pair[3] || "" + } + } + + return classes + } + + function getVirtualChildren(args, hasAttrs) { + var children = hasAttrs ? args.slice(1) : args + + if (children.length === 1 && isArray(children[0])) { + return children[0] + } else { + return children + } + } + + function assignAttrs(target, attrs, classes) { + var classAttr = "class" in attrs ? "class" : "className" + + for (var attrName in attrs) { + if (hasOwn.call(attrs, attrName)) { + if (attrName === classAttr && + attrs[attrName] != null && + attrs[attrName] !== "") { + classes.push(attrs[attrName]) + // create key in correct iteration order + target[attrName] = "" + } else { + target[attrName] = attrs[attrName] + } + } + } + + if (classes.length) target[classAttr] = classes.join(" ") + } + + /** + * + * @param {Tag} The DOM node tag + * @param {Object=[]} optional key-value pairs to be mapped to DOM attrs + * @param {...mNode=[]} Zero or more Mithril child nodes. Can be an array, + * or splat (optional) + */ + function m(tag, pairs) { + var args = [] + + for (var i = 1, length = arguments.length; i < length; i++) { + args[i - 1] = arguments[i] + } + + if (isObject(tag)) return parameterize(tag, args) + + if (!isString(tag)) { + throw new Error("selector in m(selector, attrs, children) should " + + "be a string") + } + + var hasAttrs = pairs != null && isObject(pairs) && + !("tag" in pairs || "view" in pairs || "subtree" in pairs) + + var attrs = hasAttrs ? pairs : {} + var cell = { + tag: "div", + attrs: {}, + children: getVirtualChildren(args, hasAttrs) + } + + assignAttrs(cell.attrs, attrs, parseTagAttrs(cell, tag)) + return cell + } + + function forEach(list, f) { + for (var i = 0; i < list.length && !f(list[i], i++);) { + // function called in condition + } + } + + function forKeys(list, f) { + forEach(list, function (attrs, i) { + return (attrs = attrs && attrs.attrs) && + attrs.key != null && + f(attrs, i) + }) + } + // This function was causing deopts in Chrome. + function dataToString(data) { + // data.toString() might throw or return null if data is the return + // value of Console.log in some versions of Firefox (behavior depends on + // version) + try { + if (data != null && data.toString() != null) return data + } catch (e) { + // silently ignore errors + } + return "" + } + + // This function was causing deopts in Chrome. + function injectTextNode(parentElement, first, index, data) { + try { + insertNode(parentElement, first, index) + first.nodeValue = data + } catch (e) { + // IE erroneously throws error when appending an empty text node + // after a null + } + } + + function flatten(list) { + // recursively flatten array + for (var i = 0; i < list.length; i++) { + if (isArray(list[i])) { + list = list.concat.apply([], list) + // check current index again and flatten until there are no more + // nested arrays at that index + i-- + } + } + return list + } + + function insertNode(parentElement, node, index) { + parentElement.insertBefore(node, + parentElement.childNodes[index] || null) + } + + var DELETION = 1 + var INSERTION = 2 + var MOVE = 3 + + function handleKeysDiffer(data, existing, cached, parentElement) { + forKeys(data, function (key, i) { + existing[key = key.key] = existing[key] ? { + action: MOVE, + index: i, + from: existing[key].index, + element: cached.nodes[existing[key].index] || + $document.createElement("div") + } : {action: INSERTION, index: i} + }) + + var actions = [] + for (var prop in existing) { + if (hasOwn.call(existing, prop)) { + actions.push(existing[prop]) + } + } + + var changes = actions.sort(sortChanges) + var newCached = new Array(cached.length) + + newCached.nodes = cached.nodes.slice() + + forEach(changes, function (change) { + var index = change.index + if (change.action === DELETION) { + clear(cached[index].nodes, cached[index]) + newCached.splice(index, 1) + } + if (change.action === INSERTION) { + var dummy = $document.createElement("div") + dummy.key = data[index].attrs.key + insertNode(parentElement, dummy, index) + newCached.splice(index, 0, { + attrs: {key: data[index].attrs.key}, + nodes: [dummy] + }) + newCached.nodes[index] = dummy + } + + if (change.action === MOVE) { + var changeElement = change.element + var maybeChanged = parentElement.childNodes[index] + if (maybeChanged !== changeElement && changeElement !== null) { + parentElement.insertBefore(changeElement, + maybeChanged || null) + } + newCached[index] = cached[change.from] + newCached.nodes[index] = changeElement + } + }) + + return newCached + } + + function diffKeys(data, cached, existing, parentElement) { + var keysDiffer = data.length !== cached.length + + if (!keysDiffer) { + forKeys(data, function (attrs, i) { + var cachedCell = cached[i] + return keysDiffer = cachedCell && + cachedCell.attrs && + cachedCell.attrs.key !== attrs.key + }) + } + + if (keysDiffer) { + return handleKeysDiffer(data, existing, cached, parentElement) + } else { + return cached + } + } + + function diffArray(data, cached, nodes) { + // diff the array itself + + // update the list of DOM nodes by collecting the nodes from each item + forEach(data, function (_, i) { + if (cached[i] != null) nodes.push.apply(nodes, cached[i].nodes) + }) + // remove items from the end of the array if the new array is shorter + // than the old one. if errors ever happen here, the issue is most + // likely a bug in the construction of the `cached` data structure + // somewhere earlier in the program + forEach(cached.nodes, function (node, i) { + if (node.parentNode != null && nodes.indexOf(node) < 0) { + clear([node], [cached[i]]) + } + }) + + if (data.length < cached.length) cached.length = data.length + cached.nodes = nodes + } + + function buildArrayKeys(data) { + var guid = 0 + forKeys(data, function () { + forEach(data, function (attrs) { + if ((attrs = attrs && attrs.attrs) && attrs.key == null) { + attrs.key = "__mithril__" + guid++ + } + }) + return 1 + }) + } + + function isDifferentEnough(data, cached, dataAttrKeys) { + if (data.tag !== cached.tag) return true + + if (dataAttrKeys.sort().join() !== + Object.keys(cached.attrs).sort().join()) { + return true + } + + if (data.attrs.id !== cached.attrs.id) { + return true + } + + if (data.attrs.key !== cached.attrs.key) { + return true + } + + if (m.redraw.strategy() === "all") { + return !cached.configContext || cached.configContext.retain !== true + } + + if (m.redraw.strategy() === "diff") { + return cached.configContext && cached.configContext.retain === false + } + + return false + } + + function maybeRecreateObject(data, cached, dataAttrKeys) { + // if an element is different enough from the one in cache, recreate it + if (isDifferentEnough(data, cached, dataAttrKeys)) { + if (cached.nodes.length) clear(cached.nodes) + + if (cached.configContext && + isFunction(cached.configContext.onunload)) { + cached.configContext.onunload() + } + + if (cached.controllers) { + forEach(cached.controllers, function (controller) { + if (controller.onunload) { + controller.onunload({preventDefault: noop}) + } + }) + } + } + } + + function getObjectNamespace(data, namespace) { + if (data.attrs.xmlns) return data.attrs.xmlns + if (data.tag === "svg") return "http://www.w3.org/2000/svg" + if (data.tag === "math") return "http://www.w3.org/1998/Math/MathML" + return namespace + } + + var pendingRequests = 0 + m.startComputation = function () { pendingRequests++ } + m.endComputation = function () { + if (pendingRequests > 1) { + pendingRequests-- + } else { + pendingRequests = 0 + m.redraw() + } + } + + function unloadCachedControllers(cached, views, controllers) { + if (controllers.length) { + cached.views = views + cached.controllers = controllers + forEach(controllers, function (controller) { + if (controller.onunload && controller.onunload.$old) { + controller.onunload = controller.onunload.$old + } + + if (pendingRequests && controller.onunload) { + var onunload = controller.onunload + controller.onunload = noop + controller.onunload.$old = onunload + } + }) + } + } + + function scheduleConfigsToBeCalled(configs, data, node, isNew, cached) { + // schedule configs to be called. They are called after `build` finishes + // running + if (isFunction(data.attrs.config)) { + var context = cached.configContext = cached.configContext || {} + + // bind + configs.push(function () { + return data.attrs.config.call(data, node, !isNew, context, + cached) + }) + } + } + + function buildUpdatedNode( + cached, + data, + editable, + hasKeys, + namespace, + views, + configs, + controllers + ) { + var node = cached.nodes[0] + + if (hasKeys) { + setAttributes(node, data.tag, data.attrs, cached.attrs, namespace) + } + + cached.children = build( + node, + data.tag, + undefined, + undefined, + data.children, + cached.children, + false, + 0, + data.attrs.contenteditable ? node : editable, + namespace, + configs + ) + + cached.nodes.intact = true + + if (controllers.length) { + cached.views = views + cached.controllers = controllers + } + + return node + } + + function handleNonexistentNodes(data, parentElement, index) { + var nodes + if (data.$trusted) { + nodes = injectHTML(parentElement, index, data) + } else { + nodes = [$document.createTextNode(data)] + if (!(parentElement.nodeName in voidElements)) { + insertNode(parentElement, nodes[0], index) + } + } + + var cached + + if (typeof data === "string" || + typeof data === "number" || + typeof data === "boolean") { + cached = new data.constructor(data) + } else { + cached = data + } + + cached.nodes = nodes + return cached + } + + function reattachNodes( + data, + cached, + parentElement, + editable, + index, + parentTag + ) { + var nodes = cached.nodes + if (!editable || editable !== $document.activeElement) { + if (data.$trusted) { + clear(nodes, cached) + nodes = injectHTML(parentElement, index, data) + } else if (parentTag === "textarea") { + //