diff --git a/.travis.yml b/.travis.yml index 80d7cb3f..1163fc8b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,3 @@ language: node_js node_js: - - "0.11" - - "0.10" -before_script: - - npm install -g grunt-cli + - "6.10" diff --git a/Gruntfile.js b/Gruntfile.js index 46c64ab3..bc234a54 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -1,3 +1,6 @@ +var fs = require("fs"); +var tsfmt = require("typescript-formatter"); + // This file defines grunt tasks used by [Grunt.js](http://gruntjs.com/sample-gruntfile) module.exports = function ( grunt ) { @@ -25,6 +28,8 @@ module.exports = function ( grunt ) { options: {force: true}, dist: [ "dist/" ], jsdoc: [ "dist/jsdoc/" ], + jsdocjson: [ "dist/doc.json" ], + tsd: [ "dist/gitgraph.d.ts" ], release: [ "build/", "docs/" ] }, @@ -41,6 +46,10 @@ module.exports = function ( grunt ) { release: { src: [ "src/gitgraph.js" ], dest: "build/gitgraph.js" + }, + tsd: { + src: [ "dist/gitgraph.d.ts" ], + dest: "dist/gitgraph.d.ts" } }, @@ -91,6 +100,14 @@ module.exports = function ( grunt ) { destination: "dist/docs" } }, + json: { + src: [ "dist/jsdoc/src/*.js", "README.md" ], + options: { + configure: ".jsdocrc", + destination: "dist/doc.json", + template: "./node_modules/jsdoc-json" + } + }, release: { src: [ "dist/jsdoc/src/*.js", "README.md" ], options: { @@ -190,13 +207,47 @@ module.exports = function ( grunt ) { // `grunt lint` will check code by running JSHint and unit tests over it. grunt.registerTask( "test", [ "jshint", "jasmine" ] ); - // `grunt docs` will create non-versioned documentation for development use. + // `grunt doc` will create non-versioned documentation for development use. grunt.registerTask( "doc", [ "string-replace:jsdoc", "jsdoc:dist", "clean:jsdoc" ] ); + // `grunt doc:json` will create non-versioned documentation for development use. + grunt.registerTask( "doc:json", [ + "string-replace:jsdoc", + "jsdoc:json", + "clean:jsdoc" + ] ); + + // `grunt parse:tsd` will parse /dist/doc.json to /dist/gitgraph.d.ts + grunt.registerTask( "parse:tsd", function (dest) { + const done = this.async(); + const data = JSON.parse(fs.readFileSync("./dist/doc.json")); + const fileContent = require("./scripts/json2tsd")(data).generate(); + fs.writeFile(`./${dest}/gitgraph.d.ts`, fileContent, () => { + tsfmt.processFiles([`./${dest}/gitgraph.d.ts`],{ + replace: true + }).then(done); + }); + }); + + // `grunt tsd` will generate /dist/gitgraph.d.ts + grunt.registerTask( "tsd", [ + "doc:json", + "parse:tsd:dist", + "concat:tsd", + "clean:jsdocjson" + ]); + + // `grunt tsd:release` will generate /build/gitgraph.d.ts + grunt.registerTask( "tsd:release", [ + "doc:json", + "parse:tsd:build", + "clean:jsdocjson" + ]); + // `grunt dist` will create a non-versioned new release for development use. grunt.registerTask( "dist", [ "test", @@ -204,7 +255,8 @@ module.exports = function ( grunt ) { "copy:dist", "concat:dist", "uglify:dist", - "doc" + "doc", + "tsd" ] ); // `grunt release` will create a new release of the source code. @@ -216,7 +268,8 @@ module.exports = function ( grunt ) { "uglify:release", "string-replace:jsdoc", "jsdoc:release", - "clean:jsdoc" + "clean:jsdoc", + "tsd:release" ] ); // `grunt server` will open a live reload server in your favorite browser. diff --git a/README.md b/README.md index a8d61e7e..9a2aeb6d 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,6 @@ Grunt commands. From the command line: -- Install `grunt-cli` globally with `npm install -g grunt-cli`. - Install [the necessary local dependencies][] with `npm install`. [the necessary local dependencies]: https://github.com/nicoespeon/gitgraph.js/blob/master/package.json @@ -57,30 +56,34 @@ the command line. [> Need more information about how to get started with Grunt?](http://gruntjs.com/getting-started) -### Available Grunt commands +### Available commands -#### test code - `grunt test` +#### test code - `npm test` Check source code against [JSHint][] then runs unit tests with [Jasmine][]. [JSHint]: http://www.jshint.com/ [Jasmine]: https://jasmine.github.io/ -#### generate documentation - `grunt doc` +#### generate documentation - `npm run doc` Generate source code documentation into `dist/docs/` (not versioned) with [JSDoc](http://usejsdoc.org/). -#### compile a non-versioned release - `grunt dist` +#### generate TypeScript Definition - `npm run tsd` + +Generate TypeScript Definition into `dist/gitgraph.d.ts` (not versioned). + +#### compile a non-versioned release - `npm run dist` Clean `dist/` directory, lint code, output the minified release into `dist/gitgraph.min.js` and generate the documentation into `dist/docs/`. -#### compile a new release - `grunt release` +#### compile a new release - `npm run release` Lint code, output the source and minified releases into `build/` and generate the official documentation into `docs/`. -#### open a live reload server - `grunt server` +#### open a live reload server - `npm start` For a better code experience, this grunt task opens a live server in your favorite browser. This server is automatically reloaded when you save a project diff --git a/bower.json b/bower.json index adea54b8..1c6a50b8 100644 --- a/bower.json +++ b/bower.json @@ -1,7 +1,10 @@ { "name": "gitgraph.js", - "version": "1.9.0", - "main": ["./build/gitgraph.js", "./build/gitgraph.css"], + "version": "1.10.0", + "main": [ + "./build/gitgraph.js", + "./build/gitgraph.css" + ], "ignore": [ "**/.*" ] diff --git a/build/gitgraph.d.ts b/build/gitgraph.d.ts new file mode 100644 index 00000000..36f8ccb3 --- /dev/null +++ b/build/gitgraph.d.ts @@ -0,0 +1,787 @@ +declare namespace GitGraph { + + /** + * GitGraph options + */ + interface GitGraphOptions { + + /** + * Id of the canvas container + */ + elementId?: string; + + /** + * Template of the graph + */ + template?: GitGraph.Template | string | any; + + /** + * Default author for commits + */ + author?: string; + + /** + * Display mode + */ + mode?: string; + + /** + * DOM canvas (ex: document.getElementById("id")) + */ + canvas?: HTMLElement; + + /** + * Graph orientation + */ + orientation?: string; + + /** + * Make arrows point to ancestors if true + */ + reverseArrow?: boolean; + + /** + * Add custom offsetX to initial commit. + */ + initCommitOffsetX?: number; + + /** + * Add custom offsetY to initial commit. + */ + initCommitOffsetY?: number; + + /** + * HTML Element containing tooltips in compact mode. + */ + tooltipContainer?: HTMLElement; + } + + /** + * Options of branch + */ + interface BranchOptions { + + /** + * GitGraph constructor + */ + parent: GitGraph; + + /** + * Parent branch + */ + parentBranch?: GitGraph.Branch; + + /** + * Parent commit + */ + parentCommit?: GitGraph.Commit; + + /** + * Branch name + */ + name?: string; + + /** + * Default options for commits + */ + commitDefaultOptions?: any; + } + + /** + * Branch + * @constructor + * @param options Options of branch + * @this Branch + **/ + class Branch { + constructor(options: GitGraph.BranchOptions); + + /** + * Create new branch + * @param options Branch name | Options of Branch + * @see Branch + * @this Branch + * @return New Branch + **/ + branch(options: string | GitGraph.BranchOptions): GitGraph.Branch; + + /** + * Render the branch + * @this Branch + **/ + render(): void; + + /** + * Add a commit + * @param [options] Message | Options of commit + * @see Commit + * @this Branch + **/ + commit(options?: string | GitGraph.BranchCommitOptions): void; + + /** + * Tag the last commit of the branch. + * @param [options] Message | Options of the tag + * @see Tag + * @this Branch + * */ + tag(options?: string | GitGraph.TagOptions): void; + + /** + * Checkout onto this branch + * @this Branch + **/ + checkout(): void; + + /** + * Delete this branch + * @this Branch + **/ + delete(): void; + + /** + * Merge branch + * @param [target = this.parent.HEAD] + * @param [commitOptions] Message | Options of commit + * @param [commitOptions.fastForward = false] If true, merge should use fast-forward if possible + * @see Commit + * @this Branch + * @return this + **/ + merge(target?: GitGraph.Branch, commitOptions?: string | any): GitGraph.Branch; + + /** + * Calcul column + * @this Branch + **/ + calculColumn(): void; + + /** + * Push a new point to path. + * This method will combine duplicate points and reject reversed points. + * @this Branch + */ + pushPath(): void; + + } + + /** + * Commit options + */ + interface CommitOptions { + + /** + * GitGraph constructor + */ + parent: GitGraph; + + /** + * Position X (dot) + */ + x: number; + + /** + * Position Y (dot) + */ + y: number; + + /** + * Master color (dot & message) + */ + color: string; + + /** + * Add a arrow under commit dot + */ + arrowDisplay: boolean; + + /** + * Author name & email + */ + author?: string; + + /** + * Date of commit, default is now + */ + date?: string; + + /** + * DOM Element of detail part + */ + detail?: string; + + /** + * Sha1, default is a random short sha1 + */ + sha1?: string; + + /** + * Parent commit + */ + parentCommit?: GitGraph.Commit; + + /** + * Type of commit + */ + type?: string; + + /** + * Tag of the commit + */ + tag?: string; + + /** + * Color of the tag + */ + tagColor?: string; + + /** + * Font of the tag + */ + tagFont?: string; + + /** + * If true, display a box around the tag + */ + displayTagBox?: string; + + /** + * Specific dot color + */ + dotColor?: string; + + /** + * Dot size + */ + dotSize?: number; + + /** + * Dot stroke width + */ + dotStrokeWidth?: number; + + /** + * undefined + */ + dotStrokeColor?: string; + + /** + * Commit message + */ + message?: string; + + /** + * Specific message color + */ + messageColor?: string; + + /** + * Font of the message + */ + messageFont?: string; + + /** + * Commit message display policy + */ + messageDisplay?: boolean; + + /** + * Commit message author policy + */ + messageAuthorDisplay?: boolean; + + /** + * Commit message author policy + */ + messageBranchDisplay?: boolean; + + /** + * Commit message hash policy + */ + messageHashDisplay?: boolean; + + /** + * Specific label color + */ + labelColor?: string; + + /** + * Font used for labels + */ + labelFont?: string; + + /** + * Tooltip message display policy + */ + tooltipDisplay?: boolean; + + /** + * OnClick event for the commit dot + */ + onClick?: GitGraph.CommitCallback; + + /** + * Any object which is related to this commit. Can be used in onClick or the formatter. Useful to bind the commit to external objects such as database id etc. + */ + representedObject?: any; + } + + /** + * Commit + * @constructor + * @param options Commit options + * @this Commit + **/ + class Commit { + constructor(options: GitGraph.CommitOptions); + + /** + * Render the commit + * @this Commit + **/ + render(): void; + + /** + * Render a arrow before commit + * @this Commit + **/ + arrow(): void; + + } + + /** + * Tagged commit + */ + interface TagOptions { + + /** + * Specific tag color + */ + color?: string; + + /** + * Font of the tag + */ + font?: string; + } + + /** + * Tag + * @constructor + * @param commit Tagged commit + * @param [options] Tag options + * @return + * @this Tag + * */ + class Tag { + constructor(commit: GitGraph.Commit, options?: GitGraph.TagOptions); + + } + + /** + * Template options + */ + interface TemplateOptions { + + /** + * Colors scheme: One color for each column + */ + colors?: string[]; + arrow?: { + + /** + * Arrow color + */ + color?: string; + + /** + * Arrow size + */ + size?: number; + + /** + * Arrow offset + */ + offset?: number; + }; + branch?: { + + /** + * Branch color + */ + color?: string; + + /** + * Branch line width + */ + lineWidth?: number; + + /** + * Branch merge style + */ + mergeStyle?: string; + + /** + * Space between branches + */ + spacingX?: number; + + /** + * Space between branches + */ + spacingY?: number; + }; + commit?: { + + /** + * Space between commits + */ + spacingX?: number; + + /** + * Space between commits + */ + spacingY?: number; + + /** + * Additional width to be added to the calculated width + */ + widthExtension?: number; + + /** + * Master commit color (dot & message) + */ + color?: string; + dot?: { + + /** + * Commit dot color + */ + color?: string; + + /** + * Commit dot size + */ + size?: number; + + /** + * Commit dot stroke width + */ + strokeWidth?: number; + + /** + * Commit dot stroke color + */ + strokeColor?: string; + + }; + message?: { + + /** + * Commit message color + */ + color?: string; + + /** + * Commit display policy + */ + display?: boolean; + + /** + * Commit message author policy + */ + displayAuthor?: boolean; + + /** + * Commit message branch policy + */ + displayBranch?: boolean; + + /** + * Commit message hash policy + */ + displayHash?: boolean; + + /** + * Commit message font + */ + font?: string; + + }; + + /** + * Tooltips policy + */ + shouldDisplayTooltipsInCompactMode?: boolean; + + /** + * Formatter for the tooltip contents. + */ + tooltipHTMLFormatter?: GitGraph.CommitFormatter; + }; + } + + /** + * Template + * @constructor + * @param options Template options + * @this Template + **/ + class Template { + constructor(options: GitGraph.TemplateOptions); + + /** + * Get a default template from library + * @param name Template name + * @return [template] Template if exist + **/ + get(name: string): GitGraph.Template; + + } + + /** + * A callback for each commit + * @callback CommitCallback + * @param commit A commit + * @param mouseOver True, if the mouse is currently hovering over the commit + * @param event The DOM event (e.g. a click event) + */ + type CommitCallback = (commit: GitGraph.Commit, mouseOver: boolean, event: Event) => void; + + /** + * A formatter for commit + * @callback CommitFormatter + * @param commit The commit to format + */ + type CommitFormatter = (commit: GitGraph.Commit) => void; + + /** + * Branch commit options + */ + interface BranchCommitOptions { + + /** + * Master color (dot & message) + */ + color?: string; + + /** + * Author name & email + */ + author?: string; + + /** + * Date of commit, default is now + */ + date?: string; + + /** + * DOM Element of detail part + */ + detail?: string; + + /** + * Sha1, default is a random short sha1 + */ + sha1?: string; + + /** + * Parent commit + */ + parentCommit?: GitGraph.Commit; + + /** + * Type of commit + */ + type?: string; + + /** + * Tag of the commit + */ + tag?: string; + + /** + * Color of the tag + */ + tagColor?: string; + + /** + * Font of the tag + */ + tagFont?: string; + + /** + * If true, display a box around the tag + */ + displayTagBox?: string; + + /** + * Specific dot color + */ + dotColor?: string; + + /** + * Dot size + */ + dotSize?: number; + + /** + * Dot stroke width + */ + dotStrokeWidth?: number; + + /** + * undefined + */ + dotStrokeColor?: string; + + /** + * Commit message + */ + message?: string; + + /** + * Specific message color + */ + messageColor?: string; + + /** + * Font of the message + */ + messageFont?: string; + + /** + * Commit message display policy + */ + messageDisplay?: boolean; + + /** + * Commit message author policy + */ + messageAuthorDisplay?: boolean; + + /** + * Commit message author policy + */ + messageBranchDisplay?: boolean; + + /** + * Commit message hash policy + */ + messageHashDisplay?: boolean; + + /** + * Specific label color + */ + labelColor?: string; + + /** + * Font used for labels + */ + labelFont?: string; + + /** + * Tooltip message display policy + */ + tooltipDisplay?: boolean; + + /** + * OnClick event for the commit dot + */ + onClick?: GitGraph.CommitCallback; + + /** + * Any object which is related to this commit. Can be used in onClick or the formatter. Useful to bind the commit to external objects such as database id etc. + */ + representedObject?: any; + } +} + +/** + * GitGraph + * @constructor + * @param [options] GitGraph options + * @this GitGraph + **/ +declare class GitGraph { + constructor(options?: GitGraph.GitGraphOptions); + + /** + * Disposing canvas event handlers + * @this GitGraph + **/ + dispose(): void; + + /** + * Create new branch + * @param options Branch name | Options of Branch + * @see Branch + * @this GitGraph + * @return New branch + **/ + branch(options: string | GitGraph.BranchOptions): GitGraph.Branch; + + /** + * Create new orphan branch + * @param options Branch name | Options of Branch + * @see Branch + * @this GitGraph + * @return New branch + **/ + orphanBranch(options: string | GitGraph.BranchOptions): GitGraph.Branch; + + /** + * Commit on HEAD + * @param options Message | Options of commit + * @see Commit + * @this GitGraph + * @return this Return the main object so we can chain + **/ + commit(options: string | GitGraph.BranchCommitOptions): GitGraph; + + /** + * Tag the HEAD + * @param options Options of tag + * @see Tag + * @this GitGraph + * @return this Return the main object so we can chain + **/ + tag(options: GitGraph.TagOptions): GitGraph; + + /** + * Create a new template + * @param options The template name, or the template options + * @see Template + * @this GitGraph + * @return + **/ + newTemplate(options: string | GitGraph.TemplateOptions): GitGraph.Template; + + /** + * Render the canvas + * @this GitGraph + **/ + render(): void; + + /** + * Hover event on commit dot + * @param event Mouse event + * @param callbackFn A callback function that will be called for each commit + * @this GitGraph + **/ + applyCommits(event: MouseEvent, callbackFn: GitGraph.CommitCallback): void; + + /** + * Hover event on commit dot + * @param event Mouse event + * @this GitGraph + **/ + hover(event: MouseEvent): void; + + /** + * Click event on commit dot + * @param event Mouse event + * @this GitGraph + **/ + click(event: MouseEvent): void; +} diff --git a/build/gitgraph.js b/build/gitgraph.js index 5084b988..c07e7ff6 100644 --- a/build/gitgraph.js +++ b/build/gitgraph.js @@ -1,5 +1,5 @@ /* ========================================================== - * GitGraph v1.9.0 + * GitGraph v1.10.0 * https://github.com/nicoespeon/gitgraph.js * ========================================================== * Copyright (c) 2017 Nicolas CARLO (@nicoespeon) ٩(^‿^)۶ @@ -16,16 +16,16 @@ * * @constructor * - * @param {Object} options - GitGraph options - * @param {String} [options.elementId = "gitGraph"] - Id of the canvas container - * @param {Template|String|Object} [options.template] - Template of the graph - * @param {String} [options.author = "Sergio Flores "] - Default author for commits - * @param {String} [options.mode = (null|"compact")] - Display mode + * @param {object} [options] - GitGraph options + * @param {string} [options.elementId = "gitGraph"] - Id of the canvas container + * @param {Template|string|object} [options.template] - Template of the graph + * @param {string} [options.author = "Sergio Flores "] - Default author for commits + * @param {string} [options.mode = (null|"compact")] - Display mode * @param {HTMLElement} [options.canvas] - DOM canvas (ex: document.getElementById("id")) - * @param {String} [options.orientation = ("vertical-reverse"|"horizontal"|"horizontal-reverse")] - Graph orientation - * @param {Boolean} [options.reverseArrow = false] - Make arrows point to ancestors if true - * @param {Number} [options.initCommitOffsetX = 0] - Add custom offsetX to initial commit. - * @param {Number} [options.initCommitOffsetY = 0] - Add custom offsetY to initial commit. + * @param {string} [options.orientation = ("vertical-reverse"|"horizontal"|"horizontal-reverse")] - Graph orientation + * @param {boolean} [options.reverseArrow = false] - Make arrows point to ancestors if true + * @param {number} [options.initCommitOffsetX = 0] - Add custom offsetX to initial commit. + * @param {number} [options.initCommitOffsetY = 0] - Add custom offsetY to initial commit. * @param {HTMLElement} [options.tooltipContainer = document.body] - HTML Element containing tooltips in compact mode. * * @this GitGraph @@ -149,7 +149,7 @@ /** * Create new branch * - * @param {(String | Object)} options - Branch name | Options of Branch + * @param {(string|object)} options - Branch name | Options of Branch * * @see Branch * @this GitGraph @@ -179,7 +179,7 @@ /** * Create new orphan branch * - * @param {(String | Object)} options - Branch name | Options of Branch + * @param {(string|object)} options - Branch name | Options of Branch * * @see Branch * @this GitGraph @@ -208,7 +208,7 @@ /** * Commit on HEAD * - * @param {Object} options - Options of commit + * @param {(string|BranchCommitOptions)} options - Message | Options of commit * * @see Commit * @this GitGraph @@ -225,7 +225,7 @@ /** * Tag the HEAD * - * @param {Object} options - Options of tag + * @param {object} options - Options of tag * * @see Tag * @this GitGraph @@ -242,7 +242,10 @@ /** * Create a new template * - * @param {(String|Object)} options - The template name, or the template options + * @param {(string|object)} options - The template name, or the template options + * + * @see Template + * @this GitGraph * * @return {Template} **/ @@ -264,11 +267,11 @@ // Resize canvas var unscaledResolution = { x: Math.abs((this.columnMax + 1) * this.template.branch.spacingX) + - Math.abs(this.commitOffsetX) + - this.marginX * 2, + Math.abs(this.commitOffsetX) + + this.marginX * 2, y: Math.abs((this.columnMax + 1) * this.template.branch.spacingY) + - Math.abs(this.commitOffsetY) + - this.marginY * 2 + Math.abs(this.commitOffsetY) + + this.marginY * 2 }; if (this.template.commit.message.display) { @@ -320,16 +323,16 @@ /** * A callback for each commit * - * @callback commitCallback + * @callback CommitCallback * @param {Commit} commit - A commit - * @param {Boolean} mouseOver - True, if the mouse is currently hovering over the commit + * @param {boolean} mouseOver - True, if the mouse is currently hovering over the commit * @param {Event} event - The DOM event (e.g. a click event) */ /** * A formatter for commit * - * @callback commitFormatter + * @callback CommitFormatter * @param {Commit} commit - The commit to format */ @@ -337,7 +340,7 @@ * Hover event on commit dot * * @param {MouseEvent} event - Mouse event - * @param {commitCallback} callbackFn - A callback function that will be called for each commit + * @param {CommitCallback} callbackFn - A callback function that will be called for each commit * * @this GitGraph **/ @@ -464,12 +467,12 @@ * * @constructor * - * @param {Object} options - Options of branch + * @param {object} options - Options of branch * @param {GitGraph} options.parent - GitGraph constructor * @param {Branch} [options.parentBranch = options.parentCommit.branch] - Parent branch * @param {Commit} [options.parentCommit = _getLast(options.parentBranch.commits)] - Parent commit - * @param {String} [options.name = "no-name"] - Branch name - * @param {Object} [options.commitDefaultOptions = {}] - Default options for commits + * @param {string} [options.name = "no-name"] - Branch name + * @param {object} [options.commitDefaultOptions = {}] - Default options for commits * * @this Branch **/ @@ -556,7 +559,7 @@ /** * Create new branch * - * @param {(String | Object)} options - Branch name | Options of Branch + * @param {(string|object)} options - Branch name | Options of Branch * * @see Branch * @this Branch @@ -627,11 +630,49 @@ } }; + /** + * Branch commit options + * + * @typedef {object} BranchCommitOptions + * + * @property {string} [color] - Master color (dot & message) + * @property {string} [author = this.parent.author] - Author name & email + * @property {string} [date] - Date of commit, default is now + * @property {string} [detail] - DOM Element of detail part + * @property {string} [sha1] - Sha1, default is a random short sha1 + * @property {Commit} [parentCommit] - Parent commit + * @property {string} [type = ("mergeCommit"|null)] - Type of commit + * + * @property {string} [tag] - Tag of the commit + * @property {string} [tagColor = color] - Color of the tag + * @property {string} [tagFont = this.template.commit.tag.font] - Font of the tag + * @property {string} [displayTagBox = true] - If true, display a box around the tag + * + * @property {string} [dotColor = color] - Specific dot color + * @property {number} [dotSize = this.template.commit.dot.size] - Dot size + * @property {number} [dotStrokeWidth = this.template.commit.dot.strokeWidth] - Dot stroke width + * @property {string} [dotStrokeColor = this.template.commit.dot.strokeColor] + * + * @property {string} [message = "He doesn't like George Michael! Boooo!"] - Commit message + * @property {string} [messageColor = color] - Specific message color + * @property {string} [messageFont = this.template.commit.message.font] - Font of the message + * @property {boolean} [messageDisplay = this.template.commit.message.display] - Commit message display policy + * @property {boolean} [messageAuthorDisplay = this.template.commit.message.displayAuthor] - Commit message author policy + * @property {boolean} [messageBranchDisplay = this.template.commit.message.displayBranch] - Commit message author policy + * @property {boolean} [messageHashDisplay = this.template.commit.message.displayHash] - Commit message hash policy + * + * @property {string} [labelColor = color] - Specific label color + * @property {string} [labelFont = this.template.branch.labelFont] - Font used for labels + * + * @property {boolean} [tooltipDisplay = true] - Tooltip message display policy + * @property {CommitCallback} [onClick] - OnClick event for the commit dot + * @property {object} [representedObject] - Any object which is related to this commit. Can be used in onClick or the formatter. Useful to bind the commit to external objects such as database id etc. + **/ /** * Add a commit * - * @param {(String | Object)} [options] - Message | Options of commit - * @param {String} [options.detailId] - Id of detail DOM Element + * @param {(string|BranchCommitOptions)} [options] - Message | Options of commit + * @param {string} [options.detailId] - Id of detail DOM Element * * @see Commit * @@ -781,11 +822,11 @@ /** * Tag the last commit of the branch. * - * @param {(String | Object)} [options] - Message | Options of the tag - * @param {String} [options.tag] - Message of the tag - * @param {String} [options.tagColor] - Color of the tag - * @param {String} [options.tagFont] - Font of the tag - * @param {Boolean} [options.displayTagBox] - If true, display a box around the tag + * @param {(string|object)} [options] - Message | Options of the tag + * @param {string} [options.tag] - Message of the tag + * @param {string} [options.tagColor] - Color of the tag + * @param {string} [options.tagFont] - Font of the tag + * @param {boolean} [options.displayTagBox] - If true, display a box around the tag * * @see Tag * @@ -798,7 +839,7 @@ }; } - options = _isObject(options) ?  options :  {}; + options = _isObject(options) ? options : {}; var lastCommit = _getLast(this.commits); if (_isObject(lastCommit)) { @@ -832,9 +873,10 @@ * Merge branch * * @param {Branch} [target = this.parent.HEAD] - * @param {(String | Object)} [commitOptions] - Message | Options of commit - * @param {Boolean} [commitOptions.fastForward = false] - If true, merge should use fast-forward if possible + * @param {(string|object)} [commitOptions] - Message | Options of commit + * @param {boolean} [commitOptions.fastForward = false] - If true, merge should use fast-forward if possible * + * @see Commit * @this Branch * * @return {Branch} this @@ -870,7 +912,7 @@ var targetBranchParentCommit = _getParentCommitFromBranch(targetBranch); var isFastForwardPossible = (branchParentCommit && branchParentCommit.sha1 === targetBranchParentCommit.sha1); if (commitOptions.fastForward && isFastForwardPossible) { - var isGraphHorizontal  = _isHorizontal(this.parent); + var isGraphHorizontal = _isHorizontal(this.parent); this.color = targetBranch.color; // Make branch path follow target branch ones @@ -948,7 +990,7 @@ } this.column = 0; - for (;; this.column++) { + for (; ; this.column++) { if (!(this.column in candidates) || candidates[this.column] === 0) { break; } @@ -995,43 +1037,43 @@ * * @constructor * - * @param {Object} options - Commit options + * @param {object} options - Commit options * @param {GitGraph} options.parent - GitGraph constructor - * @param {Number} options.x - Position X (dot) - * @param {Number} options.y - Position Y (dot) - * @param {String} options.color - Master color (dot & message) - * @param {Boolean} options.arrowDisplay - Add a arrow under commit dot - * @param {String} [options.author = this.parent.author] - Author name & email - * @param {String} [options.date] - Date of commit, default is now - * @param {String} [options.detail] - DOM Element of detail part - * @param {String} [options.sha1] - Sha1, default is a random short sha1 + * @param {number} options.x - Position X (dot) + * @param {number} options.y - Position Y (dot) + * @param {string} options.color - Master color (dot & message) + * @param {boolean} options.arrowDisplay - Add a arrow under commit dot + * @param {string} [options.author = this.parent.author] - Author name & email + * @param {string} [options.date] - Date of commit, default is now + * @param {string} [options.detail] - DOM Element of detail part + * @param {string} [options.sha1] - Sha1, default is a random short sha1 * @param {Commit} [options.parentCommit] - Parent commit - * @param {String} [options.type = ("mergeCommit"|null)] - Type of commit + * @param {string} [options.type = ("mergeCommit"|null)] - Type of commit * - * @param {String} [options.tag] - Tag of the commit - * @param {String} [options.tagColor = options.color] - Color of the tag - * @param {String} [options.tagFont = this.template.commit.tag.font] - Font of the tag - * @param {String} [options.displayTagBox = true] - If true, display a box around the tag + * @param {string} [options.tag] - Tag of the commit + * @param {string} [options.tagColor = options.color] - Color of the tag + * @param {string} [options.tagFont = this.template.commit.tag.font] - Font of the tag + * @param {string} [options.displayTagBox = true] - If true, display a box around the tag * - * @param {String} [options.dotColor = options.color] - Specific dot color - * @param {Number} [options.dotSize = this.template.commit.dot.size] - Dot size - * @param {Number} [options.dotStrokeWidth = this.template.commit.dot.strokeWidth] - Dot stroke width - * @param {Number} [options.dotStrokeColor = this.template.commit.dot.strokeColor] + * @param {string} [options.dotColor = options.color] - Specific dot color + * @param {number} [options.dotSize = this.template.commit.dot.size] - Dot size + * @param {number} [options.dotStrokeWidth = this.template.commit.dot.strokeWidth] - Dot stroke width + * @param {string} [options.dotStrokeColor = this.template.commit.dot.strokeColor] * - * @param {String} [options.message = "He doesn't like George Michael! Boooo!"] - Commit message - * @param {String} [options.messageColor = options.color] - Specific message color - * @param {String} [options.messageFont = this.template.commit.message.font] - Font of the message - * @param {Boolean} [options.messageDisplay = this.template.commit.message.display] - Commit message display policy - * @param {Boolean} [options.messageAuthorDisplay = this.template.commit.message.displayAuthor] - Commit message author policy - * @param {Boolean} [options.messageBranchDisplay = this.template.commit.message.displayBranch] - Commit message author policy - * @param {Boolean} [options.messageHashDisplay = this.template.commit.message.displayHash] - Commit message hash policy + * @param {string} [options.message = "He doesn't like George Michael! Boooo!"] - Commit message + * @param {string} [options.messageColor = options.color] - Specific message color + * @param {string} [options.messageFont = this.template.commit.message.font] - Font of the message + * @param {boolean} [options.messageDisplay = this.template.commit.message.display] - Commit message display policy + * @param {boolean} [options.messageAuthorDisplay = this.template.commit.message.displayAuthor] - Commit message author policy + * @param {boolean} [options.messageBranchDisplay = this.template.commit.message.displayBranch] - Commit message author policy + * @param {boolean} [options.messageHashDisplay = this.template.commit.message.displayHash] - Commit message hash policy * - * @param {String} [options.labelColor = options.color] - Specific label color - * @param {String} [options.labelFont = this.template.branch.labelFont] - Font used for labels + * @param {string} [options.labelColor = options.color] - Specific label color + * @param {string} [options.labelFont = this.template.branch.labelFont] - Font used for labels * - * @param {Boolean} [options.tooltipDisplay = true] - Tooltip message display policy - * @param {commitCallback} [options.onClick] - OnClick event for the commit dot - * @param {Object} [options.representedObject] - Any object which is related to this commit. Can be used in onClick or the formatter. Useful to bind the commit to external objects such as database id etc. + * @param {boolean} [options.tooltipDisplay = true] - Tooltip message display policy + * @param {CommitCallback} [options.onClick] - OnClick event for the commit dot + * @param {object} [options.representedObject] - Any object which is related to this commit. Can be used in onClick or the formatter. Useful to bind the commit to external objects such as database id etc. * * @this Commit **/ @@ -1271,9 +1313,9 @@ * @constructor * * @param {Commit} commit - Tagged commit - * @param {Object} [options] - Tag options - * @param {String} [options.color = commit.color] - Specific tag color - * @param {String} [options.font = commit.template.commit.tag.font] - Font of the tag + * @param {object} [options] - Tag options + * @param {string} [options.color = commit.color] - Specific tag color + * @param {string} [options.font = commit.template.commit.tag.font] - Font of the tag * @return {Tag} * * @this Tag @@ -1322,32 +1364,32 @@ * * @constructor * - * @param {Object} options - Template options - * @param {Array} [options.colors] - Colors scheme: One color for each column - * @param {String} [options.arrow.color] - Arrow color - * @param {Number} [options.arrow.size] - Arrow size - * @param {Number} [options.arrow.offset] - Arrow offset - * @param {String} [options.branch.color] - Branch color - * @param {Number} [options.branch.lineWidth] - Branch line width - * @param {String} [options.branch.mergeStyle = ("bezier"|"straight")] - Branch merge style - * @param {Number} [options.branch.spacingX] - Space between branches - * @param {Number} [options.branch.spacingY] - Space between branches - * @param {Number} [options.commit.spacingX] - Space between commits - * @param {Number} [options.commit.spacingY] - Space between commits - * @param {Number} [options.commit.widthExtension = 0] - Additional width to be added to the calculated width - * @param {String} [options.commit.color] - Master commit color (dot & message) - * @param {String} [options.commit.dot.color] - Commit dot color - * @param {Number} [options.commit.dot.size] - Commit dot size - * @param {Number} [options.commit.dot.strokeWidth] - Commit dot stroke width - * @param {Number} [options.commit.dot.strokeColor] - Commit dot stroke color - * @param {String} [options.commit.message.color] - Commit message color - * @param {Boolean} [options.commit.message.display] - Commit display policy - * @param {Boolean} [options.commit.message.displayAuthor] - Commit message author policy - * @param {Boolean} [options.commit.message.displayBranch] - Commit message branch policy - * @param {Boolean} [options.commit.message.displayHash] - Commit message hash policy - * @param {String} [options.commit.message.font = "normal 12pt Calibri"] - Commit message font - * @param {Boolean} [options.commit.shouldDisplayTooltipsInCompactMode] - Tooltips policy - * @param {commitFormatter} [options.commit.tooltipHTMLFormatter = true] - Formatter for the tooltip contents. + * @param {object} options - Template options + * @param {string[]} [options.colors] - Colors scheme: One color for each column + * @param {string} [options.arrow.color] - Arrow color + * @param {number} [options.arrow.size] - Arrow size + * @param {number} [options.arrow.offset] - Arrow offset + * @param {string} [options.branch.color] - Branch color + * @param {number} [options.branch.lineWidth] - Branch line width + * @param {string} [options.branch.mergeStyle = ("bezier"|"straight")] - Branch merge style + * @param {number} [options.branch.spacingX] - Space between branches + * @param {number} [options.branch.spacingY] - Space between branches + * @param {number} [options.commit.spacingX] - Space between commits + * @param {number} [options.commit.spacingY] - Space between commits + * @param {number} [options.commit.widthExtension = 0] - Additional width to be added to the calculated width + * @param {string} [options.commit.color] - Master commit color (dot & message) + * @param {string} [options.commit.dot.color] - Commit dot color + * @param {number} [options.commit.dot.size] - Commit dot size + * @param {number} [options.commit.dot.strokeWidth] - Commit dot stroke width + * @param {string} [options.commit.dot.strokeColor] - Commit dot stroke color + * @param {string} [options.commit.message.color] - Commit message color + * @param {boolean} [options.commit.message.display] - Commit display policy + * @param {boolean} [options.commit.message.displayAuthor] - Commit message author policy + * @param {boolean} [options.commit.message.displayBranch] - Commit message branch policy + * @param {boolean} [options.commit.message.displayHash] - Commit message hash policy + * @param {string} [options.commit.message.font = "normal 12pt Calibri"] - Commit message font + * @param {boolean} [options.commit.shouldDisplayTooltipsInCompactMode] - Tooltips policy + * @param {CommitFormatter} [options.commit.tooltipHTMLFormatter = true] - Formatter for the tooltip contents. * * @this Template **/ @@ -1434,7 +1476,7 @@ /** * Get a default template from library * - * @param {String} name - Template name + * @param {string} name - Template name * * @return {Template} [template] - Template if exist **/ @@ -1470,7 +1512,7 @@ break; case "metro": - /* falls through */ + /* falls through */ default: template = { colors: ["#979797", "#008fb5", "#f1c109"], @@ -1514,11 +1556,11 @@ * Extend given commit with proper attributes for tag from options. * * @param {Commit} commit - * @param {Object} [options] - * @param {String} [options.tag] - Tag of the commit - * @param {String} [options.tagColor = commit.messageColor] - Color of the tag - * @param {String} [options.tagFont = commit.template.commit.tag.font] - Font of the tag - * @param {String} [options.displayTagBox = true] - If true, display a box around the tag + * @param {object} [options] + * @param {string} [options.tag] - Tag of the commit + * @param {string} [options.tagColor = commit.messageColor] - Color of the tag + * @param {string} [options.tagFont = commit.template.commit.tag.font] - Font of the tag + * @param {string} [options.displayTagBox = true] - If true, display a box around the tag * @private */ function _assignTagOptionsToCommit(commit, options) { @@ -1548,8 +1590,8 @@ /** * Returns a copy of the given object. * - * @param {Object} object - * @returns {Object} + * @param {object} object + * @returns {object} * @private * */ function _clone(object) { @@ -1559,8 +1601,8 @@ /** * Returns the height of the given font when rendered. * - * @param {String} font - * @returns {Number} + * @param {string} font + * @returns {number} * @private */ function _getFontHeight(font) { @@ -1581,8 +1623,8 @@ * Returns the `booleanOptions` if it's actually a boolean, returns `defaultOptions` otherwise. * * @param {*} booleanOption - * @param {Boolean} defaultOptions - * @returns {Boolean} + * @param {boolean} defaultOptions + * @returns {boolean} * @private */ function _booleanOptionOr(booleanOption, defaultOption) { @@ -1593,13 +1635,13 @@ * Draw text background. * * @param {CanvasRenderingContext2D} context - Canvas 2D context in which to render text. - * @param {Number} x - Horizontal offset of the text. - * @param {Number} y - Vertical offset of the text. - * @param {String} text - Text content. - * @param {String} color - Text Colors. - * @param {String} font - Text font. - * @param {Number} angle - Angle of the text for rotation. - * @param {Boolean} useStroke - Name of the triggered event. + * @param {number} x - Horizontal offset of the text. + * @param {number} y - Vertical offset of the text. + * @param {string} text - Text content. + * @param {string} color - Text Colors. + * @param {string} font - Text font. + * @param {number} angle - Angle of the text for rotation. + * @param {boolean} useStroke - Name of the triggered event. * @private */ function _drawTextBG(context, x, y, text, color, font, angle, useStroke) { @@ -1634,8 +1676,8 @@ * Emit an event on the given element. * * @param {HTMLElement} element - DOM element to trigger the event on. - * @param {String} eventName - Name of the triggered event. - * @param {Object} [data = {}] - Custom data to attach to the event. + * @param {string} eventName - Name of the triggered event. + * @param {object} [data = {}] - Custom data to attach to the event. * @private */ function _emitEvent(element, eventName, data) { @@ -1663,8 +1705,8 @@ * Returns the scaling factor of given canvas `context`. * Handles high-resolution displays. * - * @param {Object} context - * @returns {Number} + * @param {object} context + * @returns {number} * @private */ function _getScale(context) { @@ -1691,7 +1733,7 @@ * Returns `true` if `graph` has a vertical orientation. * * @param {GitGraph} graph - * @returns {Boolean} + * @returns {boolean} * @private */ function _isVertical(graph) { @@ -1702,7 +1744,7 @@ * Returns `true` if `graph` has an horizontal orientation. * * @param {GitGraph} graph - * @returns {Boolean} + * @returns {boolean} * @private */ function _isHorizontal(graph) { @@ -1713,7 +1755,7 @@ * Returns `true` if `object` is an object. * * @param {*} object - * @returns {Boolean} + * @returns {boolean} * @private */ function _isObject(object) { @@ -1725,8 +1767,8 @@ * Modified from original source: http://stackoverflow.com/a/23809123. * * @param {*} obj - The object whose properties are to be tested as being undefined or equal to null. - * @param {String} key - The property hierarchy of `obj` to be tested, specified using 'dot notation' (e.g. property1.property2.property3 etc). - * @returns {Boolean} - True if ANY of the properties specified by `key` is undefined or equal to null, otherwise False. + * @param {string} key - The property hierarchy of `obj` to be tested, specified using 'dot notation' (e.g. property1.property2.property3 etc). + * @returns {boolean} - True if ANY of the properties specified by `key` is undefined or equal to null, otherwise False. * @private */ function _isNullOrUndefined(obj, key) { diff --git a/build/gitgraph.min.js b/build/gitgraph.min.js index bd529833..e08efaf0 100644 --- a/build/gitgraph.min.js +++ b/build/gitgraph.min.js @@ -1,5 +1,5 @@ /* ========================================================== - * GitGraph v1.9.0 + * GitGraph v1.10.0 * https://github.com/nicoespeon/gitgraph.js * ========================================================== * Copyright (c) 2017 Nicolas CARLO (@nicoespeon) ٩(^‿^)۶ diff --git a/docs/Branch.html b/docs/Branch.html index c1d33204..e2304dd7 100644 --- a/docs/Branch.html +++ b/docs/Branch.html @@ -92,7 +92,7 @@
Parameters:
-Object +object @@ -251,7 +251,7 @@
Properties
-String +string @@ -290,7 +290,7 @@
Properties
-Object +object @@ -364,7 +364,7 @@
Properties
Source:
@@ -465,10 +465,10 @@
Parameters:
-String +string | -Object +object @@ -519,7 +519,7 @@
Parameters:
Source:
@@ -633,7 +633,7 @@
This:
Source:
@@ -718,7 +718,7 @@
This:
Source:
@@ -803,10 +803,10 @@
Parameters:
-String +string | -Object +BranchCommitOptions @@ -860,7 +860,7 @@
Properties
-String +string @@ -928,7 +928,7 @@
Properties
Source:
@@ -1020,7 +1020,7 @@
This:
Source:
@@ -1146,10 +1146,10 @@
Parameters:
-String +string | -Object +object @@ -1209,7 +1209,7 @@
Properties
-Boolean +boolean @@ -1283,13 +1283,20 @@
Properties
Source:
+
See:
+
+ +
+ @@ -1391,7 +1398,7 @@
This:
Source:
@@ -1476,7 +1483,7 @@
This:
Source:
@@ -1561,10 +1568,10 @@
Parameters:
-String +string | -Object +object @@ -1618,7 +1625,7 @@
Properties
-String +string @@ -1651,7 +1658,7 @@
Properties
-String +string @@ -1684,7 +1691,7 @@
Properties
-String +string @@ -1717,7 +1724,7 @@
Properties
-Boolean +boolean @@ -1785,7 +1792,7 @@
Properties
Source:
@@ -1840,7 +1847,7 @@

Home

Classes