leodido/ng-caret-aware

AngularJS directive for caret aware elements

Caret aware inputs

AngularJS directive for caret aware elements.

Put it on your HTML elements (inputs or textareas, for now) and it will track the caret (i.e. cursor) exporting its position in a variable (named after the value assigned to the directive attribute) appended to the parent scope.

Moreover, it will expose an API (via its controller) to read and write caret position.

Caret aware directive is designed to be cross-browser.

Weight: < 2KB.

See input demo live here or textarea demo live here.

Releases

Latest release files are in the dist directory of this repository.

Note

At the moment this directive can be used as attribute or as comment.

Usage

Include AngularJS, and the build you desire (e.g., dist/caretaware.min.js).

Then load the leodido.caretAware AngularJS module. E.g.,

var app = angular.module('myAwesomeModule', ['leodido.caretAware']);

Instantiate the directive.

<input type="text" name="myname" caret-aware="cursor"/>

And the parent scope of this element will contain a cursor variable - e.g., $scope.cursor - tracking the caret position of your element's content.

Alternatively you can simply instantiate it this way:

<input type="text" name="myname" caret-aware/>

In such case the parent scope will contain a caret variable - e.g., $scope.caret - tracking the caret position of your input element.

Controller usage

• Want to use this directive APIs/controller?

See example directory for further details. For example here.

• Want to use this directive APIs in your custom directive?

Simply require it. E.g.,

var a = angular.module('demo', []);
a.directive('test', function() {
  return {
      restrict: 'A',
      require: ['caretAware'],
      // ...
      link: function(scope, iElem, iAttrs, caretAwareController) {
        // caretAwareController.setPosition(1);
        // ...
      }
  }
});

APIs

This is the public API to manipulate and retrieve the caret position.

/**
 * Retrieve the namespace of the directive instance
 *
 * @return {!string}
 */
caretAwareController.getNamespace()
/**
 * Retrieve the element caret position
 *
 * @return {!number}
 */
caretAwareController.getPosition()
/**
 * Manually set the element caret position and the scope caret variable
 *
 * @param {!number} pos
 * @return {!leodido.controller.Caret}
 * @throws TypeError
 */
caretAwareController.setPosition(pos)
/**
 * Retrive information about the current selection
 *
 * @return {{start: !number, end: !number, length: !number, text: !string}}
 */
caretAwareController.getSelection()

Note

1. the scope caret variable value - i.e., $scope.caret - is asynchronously bound to the actual element caret position, so during the digest cycle the getPosition() could not reflect the scope caret variable value

2. in some browser (e.g., Chrome 42.0.2331) can happen that setPosition() will not be instantly applied, so the getPosition() could return the previous value; see this issue.

Installation

Install it via bower.

bower install ng-caret-aware

Or, you can clone this repo and install it locally (you will need npm, of course).

$ git clone [email protected]:leodido/ng-caret-aware.git
$ cd ng-caret-aware/
$ npm install

Distribution

In the dist directory you can find both development and production ready library files:

1. dev.caretaware.min.js and its sourcemap (i.e., dev.caretaware.min.js.map file) can be used for development purposes

2. caretaware.min.js is the production version of this AngularJS module

Build

Build is handled through Gulp and performed mainly via Google Closure Compiler.

Need help? Run gulp help!

# Usage
#   gulp [task]
# 
# Available tasks
#   build                                  Build the library 
#    --banner                              Prepend banner to the built file
#    --env=production|development          Kind of build to perform, defaults to production
#  bump                                    Bump version up for a new release 
#   --level=major|minor|patch|prerelease   Version level to increment
#   clean                                  Clean build directory
#   help                                   Display this help text
#   karma                                  Run karma tests
#   lint                                   Lint JS source files
#   protractor                             Run protractor E2E tests
#   version                                Print the library version

Tests

This library has been unit tested for Chrome and Firefox.

At the moment coverage is almost complete.

Furthermore E2E tests are provided for Chrome and Firefox, too.

See test directory for details.

Aknowledgements

• Thanks to @leogr for his suggestions, and improvements. Particularly for his help fixing issue #14.

• Thanks for the inspiration to all authors of snippets (that are present on the web) related to the caret management.

---

ng-caret-aware's Issues

Update to latest gulp-closure-compiler

Move also distribution files.

Teardown code

Test activeElement at page load

Refs #43.

Distribution files

• sourcemap
• development distribution: logging enabled, sourcemap linked, advanced optimization
• production distribution: no logging, advanced optimization

Get selection info

Add a method getSelection() that extracts selection info:

1. start caret position
2. end caret position
3. length of selection
4. selected text

NOTE

Method getPosition() simply return the start caret position (1).
So it can be refactored according to getSelection() method.

Add setSelectionText to API

Like this: https://github.com/kof/field-selection/blob/e2da83a6970ee707628a995daee85deb5026a41c/lib/field-selection.js#L67:L100

Position variable and actual position not synched on Firefox

On Firefox can happen that the position variable (e.g., $scope.caret) is updated while the method getPosition() returns the previous position.

This situations happens when position has been changed programmatically (i.e., via setPosition(pos) method).
This method call the setSelectionRange method that, on Firefox, does not instantly updated the selectionStart and selectionEnd target variables.

Nevertheless note that inconsistencies verifies also when you directly change the scope caret variable, due to the nature of AngularJS watches.

Move sync logic in the directive post-link

Remove watch from controller, it should contain only initialization and API.
Move this watch in the postlink function.

Externalize controller

Create a class leodido.controller.Caret.

Reorganize deps

Move closure related dependencies to devDependencies.

E2E tests

Coveralls integration

Integrate coveralls.

Gulp or node communication already done, but it does not work. Verify why.

Update README

• Re-organize docs
• List features and signatures
• Publish and link examples.

Improve build system (gulp file)

Unit tests

Docs

Fix main field of bower.json and package.json

Improve bower package

• Distribute also not minified file
• Remove gulpfile.js and lib (source) directory from package

Travis integration

• YAML file
• Badge
• What about E2E tests?

Ensure target is not focused during first digest cycle

This can be achieved in two semantically different ways:

1. changing the start value (currently set to 0) to null
2. avoid to call .focus() in the setPosition polyfills.

Refs #44

Enforce caret boundaries

A negative caret value must be equivalent to representing caret position from right to left.
Block caret position to text length.

Publish to the npm registry

Missing "dependencies" field in the package.json file.

Review example paths.

Click after selection does not fire caret value change

Scenario:

1. You have selected a part of the text in a caret-aware input.
2. When you release mouse the caret position is equivalent to the starting point of the selection
3. Selection is already visible
4. You click in the middle of the selection
5. The caret variable value is not updated to the position you just clicked

This happens because when you click, the selectionStart (or IE equivalent) variable has not yet been updated, so the call to ctrl.getPosition() returns a value equal to the previous.

Angular versions compatibility

According to bower.json, this project is only compatible with Angular 1.3.x. I have tried to run it on Angular 1.5.6, which has been working thus far. What reasons are there for requiring specifically 1.3? Can I safely use it on a later version?

Cheers

Release 0.3.2