[fit addon] Introduce proposeGeometry method

- Introduce new method to propose optimal geometry for the current terminal
- Bump version to 0.23

README.md

@@ -1,14 +1,19 @@
-# xterm.js
+# xterm.js — xterm, in the browser
 
-xterm, in the browser.
+Xterm.js is a full xterm clone, written completely in JavaScript.
+
+Xterm.js supplies a modular, event-based interface that lets developers build addons and themes that augment  the experience of running a fully-featured terminal inside the browser.
+
+Xterm.js serves as foundation for the terminal found at www.sourcelair.com.
+
+![xterm.js screenshot](docs/screenshot.png)
 
 ### Contribution and License Agreement
 
-If you contribute code to this project, you are implicitly allowing your code
-to be distributed under the MIT license. You are also implicitly verifying that
-all code is your original work.
+If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work.
 
 ## License
 
-Copyright (c) 2014, sourceLair Limited (www.sourcelair.com) (MIT License)
+Copyright (c) 2014, SourceLair, Ltd (www.sourcelair.com) (MIT License)
+
 Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)

addons/attach/attach.js

@@ -5,19 +5,55 @@
  * The bidirectional argument indicates, whether the terminal should
  * send data to the socket as well and is true, by default.
  */
-Terminal.prototype.attach = function (socket, bidirectional) {
-  var term = this;
-  
-  bidirectional = (typeof bidirectional == 'undefined') ? true : bidirectional;
-  this.socket = socket;
-  
-  socket.addEventListener('message', function (ev) {
-    term.write(ev.data);
-  });
-  
-  if (bidirectional) {
-    this.on('data', function (data) {
-      socket.send(data);
-    });
-  }
-}
+
+(function (attach) {
+    if (typeof define == 'function') {
+        /*
+         * Require.js is available
+         */
+        define(['../../src/xterm'], attach);
+    } else {
+        /*
+         * Plain browser environment
+         */ 
+        attach(this.Xterm);
+    }
+})(function (Xterm) {
+    Xterm.prototype.attach = function (socket, bidirectional) {
+      var term = this;
+
+      bidirectional = (typeof bidirectional == 'undefined') ? true : bidirectional;
+      this.socket = socket;
+
+      term._getMessage = function (ev) {
+        term.write(ev.data);
+      };
+        
+      term._sendData = function (data) {
+        socket.send(data);
+      };
+
+      socket.addEventListener('message', term._getMessage);
+
+      if (bidirectional) {
+        this.on('data', term._sendData);
+      }
+      
+      socket.addEventListener('close', term.detach.bind(term, socket));
+      socket.addEventListener('error', term.detach.bind(term, socket));
+    };
+    
+    Xterm.prototype.detach = function (socket) {
+      var term = this;
+
+      term.off('data', term._sendData);
+
+      socket = (typeof socket == 'undefined') ? term.socket : socket;
+
+      if (socket) {
+        socket.removeEventListener('message', term._getMessage);
+      }
+
+      delete term.socket;
+    };
+});

addons/attach/index.html

@@ -5,8 +5,61 @@
     <link rel="stylesheet" href="../../demo/style.css" />
     <script src="../../src/xterm.js"></script>
     <script src="attach.js"></script>
+    <style>
+        body {
+            color: #111;
+        }
+        
+        h1, h2 {
+            color: #444;
+            border-bottom: 1px solid #ddd;
+            text-align: left;
+        }
+        
+        form {
+            margin-bottom: 32px;
+        }
+        
+        input, button {
+            line-height: 22px;
+            font-size: 16px;
+            display: inline-block;
+            border-radius: 2px;
+            border: 1px solid #ccc;
+        }
+        
+        input {
+            height: 22px;
+            padding-left: 4px;
+            padding-right: 4px;
+        }
+        
+        button {
+            height: 28px;
+            background-color: #ccc;
+            cursor: pointer;
+            color: #333;
+        }
+        
+        .container {
+            max-width: 900px;
+            margin: 0 auto;
+        }
+    </style>
   </head>
   <body>
+      <div class="container">
+          
+    <h1>
+        xterm.js: socket attach
+    </h1>
+          <p>
+              Attach the terminal to a WebSocket terminal stream with ease. Perfect for attaching to your
+              Docker containers.
+          </p>
+          <h2>
+              Socket information
+          </h2>
     <form id="socket-form">
       <input id="socket-url"
              type="text"
@@ -17,6 +70,8 @@
       </button>
     </form>
     <div id="terminal-container"></div>
+          
+      </div>
     <script>
       var term = new Terminal(),
           container = document.getElementById('terminal-container'),

addons/fit/fit.js

@@ -0,0 +1,70 @@
+/*
+ *  Fit terminal columns and rows to the dimensions of its
+ *  DOM element.
+ *
+ *  Approach:
+ *    - Rows: Truncate the division of the terminal parent element height
+ *            by the terminal row height
+ *
+ *    - Columns: Truncate the division of the terminal parent element width by
+ *               the terminal character width (apply display: inline at the
+ *               terminal row and truncate its width with the current number
+ *               of columns)
+ */
+(function (fit) {
+    if (typeof define == 'function') {
+        /*
+         * Require.js is available
+         */
+        define(['../../src/xterm'], fit);
+    } else {
+        /*
+         * Plain browser environment
+         */ 
+        fit(this.Xterm);
+    }
+})(function (Xterm) {
+    Xterm.prototype.proposeGeometry = function () {
+        var container = this.rowContainer,
+            subjectRow = this.rowContainer.firstElementChild,
+            rows,
+            contentBuffer,
+            characterWidth,
+            cols;
+
+        subjectRow.style.display = 'inline';
+
+        contentBuffer = subjectRow.textContent;
+
+        subjectRow.innerHTML = ' '; /* Arbitrary character to calculate its dimensions */
+        characterWidth = parseInt(subjectRow.offsetWidth);
+        characterHeight = parseInt(subjectRow.offsetHeight);
+
+        subjectRow.style.display = '';
+
+        cols = container.offsetWidth / characterWidth;
+        cols = parseInt(cols);
+
+        var parentElementStyle = window.getComputedStyle(this.element.parentElement),
+            parentElementHeight = parseInt(parentElementStyle.getPropertyValue('height')),
+            elementStyle = window.getComputedStyle(this.element),
+            elementPadding = parseInt(elementStyle.getPropertyValue('padding-top')) + parseInt(elementStyle.getPropertyValue('padding-bottom')),
+            availableHeight = parentElementHeight - elementPadding,
+            rowHeight = this.rowContainer.firstElementChild.offsetHeight;
+
+        rows = parseInt(availableHeight / rowHeight);
+        
+        var geometry = {
+                'cols': cols,
+                'rows': rowss
+            };
+
+        return geometry;
+    };
+
+    Xterm.prototype.fit = function () {
+        var geometry = this.proposeGeometry();
+
+        this.resize(geometry.cols, geometry.rows);
+    };
+});

addons/fullscreen/fullscreen.js

@@ -10,16 +10,30 @@
  * If the `fullscreen` argument has not been supplied, the
  * fullscreen mode is being toggled.
  */
-Terminal.prototype.toggleFullscreen = function (fullscreen) {
-  var fn;
-  
-  if (typeof fullscreen == 'undefined') {
-    fn = (this.element.classList.contains('fullscreen')) ? 'remove' : 'add';
-  } else if (!fullscreen) {
-    fn = 'remove';
-  } else {
-    fn = 'add';
-  }
-  
-  this.element.classList[fn]('fullscreen');
-}
+(function (fullscreen) {
+    if (typeof define == 'function') {
+        /*
+         * Require.js is available
+         */
+        define(['../../src/xterm'], fullscreen);
+    } else {
+        /*
+         * Plain browser environment
+         */ 
+        fullscreen(this.Xterm);
+    }
+})(function (Xterm) {
+    Xterm.prototype.toggleFullscreen = function (fullscreen) {
+      var fn;
+
+      if (typeof fullscreen == 'undefined') {
+        fn = (this.element.classList.contains('fullscreen')) ? 'remove' : 'add';
+      } else if (!fullscreen) {
+        fn = 'remove';
+      } else {
+        fn = 'add';
+      }
+
+      this.element.classList[fn]('fullscreen');
+    };
+});

bower.json

@@ -1,5 +1,5 @@
 {
   "name": "xterm.js",
-  "version": "0.9.2",
+  "version": "0.23",
   "ignore": ["demo", "docs", "test", ".gitignore"]
 }

demo/index.html

@@ -3,11 +3,12 @@
     <head>
         <title>xterm.js demo</title>
         <link rel="stylesheet" href="../src/xterm.css" />
-        <link rel="stylesheet" href="../addon/fullscreen/fullscreen.css" />
+        <link rel="stylesheet" href="../addons/fullscreen/fullscreen.css" />
         <link rel="stylesheet" href="style.css" />
-        <script src="../src/xterm.js"></script>
-        <script src="../addon/fullscreen/fullscreen.js"></script>
-        <script src="main.js" defer></script>
+        <script src="../src/xterm.js" ></script>
+        <script src="../addons/fit/fit.js" ></script>
+        <script src="../addons/fullscreen/fullscreen.js" ></script>
+        <script src="main.js" defer ></script>
     </head>
     <body>
         <h1>

demo/main.js

@@ -1,12 +1,13 @@
 var terminalContainer = document.getElementById('terminal-container'),
-    term = new Terminal();
+    term = new Terminal(),
+    prompt = '> ';
 
 term.open(terminalContainer);
 term.fit();
 
 term.prompt = function () {
-  term.write('\r\n> ');
-}
+  term.write('\r\n' + prompt);
+};
 
 term.writeln('Welcome to xterm.js');
 term.writeln('Just type some keys in the prompt below.');
@@ -19,7 +20,12 @@ term.on('key', function (key, ev) {
   if (ev.keyIdentifier == 'Enter') {
     term.prompt();
   } else if (ev.keyCode == 8) {
-    term.write('\b \b');
+    /*
+     * Do not delete the prompt
+     */
+    if (term.x > 2) {
+      term.write('\b \b');
+    }
   } else if (printable) {
     term.write(key);
   }

docs/conf.py

@@ -44,16 +44,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'xterm.js'
-copyright = u'2014, sourceLair Limited'
+copyright = u'2014, SourceLair Limited'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1a'
+version = '0.23'
 # The full version, including alpha/beta/rc tags.
-release = '0.1a'
+release = '0.23 Alpha'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/events.rst

@@ -0,0 +1,43 @@
+------
+Events
+------
+
+focus
+^^^^^
+This event is fired, when the Terminal gets focus.
+
+blur
+^^^^
+This event is fired, when the Terminal loses focus.
+
+open
+^^^^
+This event is fired, when the Terminal gets opened into a DOM Element.
+
+keydown
+^^^^^^^
+This event is fired, when the `keydown` DOM Event gets triggered on the Terminal.
+
+keypress
+^^^^^^^^
+This event is fired, when the `keypress` DOM Event gets triggered on the Terminal.
+
+key
+^^^
+This event is fired, when a key is being handled by the Terminal.
+
+resize
+^^^^^^
+This event is being fired, when the Terminal view gets resized by the `resize` method.
+
+data
+^^^^
+This event is being fired, when a chunk of input data gets handled by the terminal.
+
+copy
+^^^^
+This event is fired, when the `copy` DOM Event gets triggered on the Terminal.
+
+paste
+^^^^^
+This event is fired, when the `paste` DOM Event gets triggered on the Terminal.

docs/index.rst

@@ -6,17 +6,40 @@
 Welcome to xterm.js's documentation!
 ====================================
 
-Contents:
+This is the documentation for xterm.js. Xterm.js is a full xterm clone, written completely in JavaScript.
+
+Xterm.js supplies a modular, event-based interface that lets developers build addons and themes that augment 
+the experience of running a fully-feature terminal inside the browser.
+
+Xterm.js serves as the foundation for the terminal found at www.sourcelair.com.
+
+.. image:: screenshot.png
+
+Getting started
+^^^^^^^^^^^^^^^
+
+.. code-block:: javascript
+    
+   var term = new Terminal(),
+       url = 'ws://docker/containers/mycontainer/attach/ws/?stdin=1&stdout=1&stderr=1&logs=1',
+       socket = new WebSocket(url);
+  
+   term.open(document.body);
+   term.on('data', function (data) {
+       socket.send(data);
+   });
+   socket.onmessage = function (e) {
+       term.write(e.data);
+   }
+    
+
+Contents
+^^^^^^^^
+The standard way to create a terminal-based application with xterm.js is to work with its events and
+methods, that let you manipulate input, output, state and size of the terminal.
 
 .. toctree::
-   :maxdepth: 2
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   :maxdepth: 1
+   
+   methods
+   events

docs/methods.rst

@@ -0,0 +1,47 @@
+-------
+Methods
+-------
+
+focus()
+^^^^^^^
+Sends focus to the terminal
+
+blur()
+^^^^^^
+Blurs the Terminal
+
+open(element)
+^^^^
+Open the Xterm terminal, inside the given element.
+
+resize(x, y)
+^^^^^^^^^^^^
+Resize the terminal, according to the given columns and rows.
+
+insertRow(row)
+^^^^^^^^^^^^^^
+Insert the given row in the terminal.
+
+on(event, callback)
+^^^^^^^^^^^^^^^^^^^
+Hook the given callback, to the given event.
+
+off(event, callback)
+^^^^^^^^^^^^^^^^^^^
+Remove the Hook of the given callback, from the given event.
+
+once(event, callback)
+^^^^^^^^^^^^^^^^^^^
+Hook the given callback to the given event, for just a single invocation.
+
+write(data)
+^^^^^^^^^^^
+Write the given data to the terminal.
+
+writeln(data)
+^^^^^^^^^^^^^
+Write the given data to the terminal, followed by a carriage return and a new line.
+
+handler(data)
+^^^^^^^^^^^^^
+Fire the data event, for the given data.

src/xterm.css

@@ -45,6 +45,7 @@
 
 .xterm .terminal-cursor {
     background-color: #fff;
+    color: #000;
 }
 
 .xterm .xterm-helpers {