README.md

CharCount

A lightweight (~7KB min) ES6 library for dealing with character counts on text fields, providing events, live counters and more!

An interactive preview can be found on the GitHub page for this project.

Brief

The concept of the library is to define a state that the field is in dependent on where the field sits within the configured thresholds. The character count thresholds are seperated into 3 key targets; Warning, Danger and Expended. Warning is for "you're getting close!", Danger is for "for real, you are running out" and Expended is for "all used up!". When the field is empty an Empty state is declared, along with a similar Fine state being applied when the field sits between an Empty and Warning state.

Based on this, events are fired to allow utilisation of that fact and a counter is placed underneath the field to display the remainder of the expended threshold to the user in realtime.

As for the name, the project was going to be called CharCount through and through, but due to it being too similar to an existing NPM package, it's had to take the name char-count-es6 for under the hood stuff. The package itself will always be accessible via the CharCount class.

Installation

Via NPM

$ npm install char-count-es6 --save-dev

Via download

Download the minified source from dist and include in your project via

<script src="/path/to/charcount.min.js"></script>

Usage

To begin, import the ES6 library where required

import CharCount from 'char-count-es6';

To create a new CharCount instance, you can write something like

let myCharCount = new CharCount({ ...options });

The variable will contain an array of initialised instances, stored in the instances property. The element also has the instance registered against it, in the CharCount property.

Options

All the following is optional. When initialising the library, the following options can be provided as an object:

Core

selector: [String || Object (Element)] [Defaults to 'cc-field']

ID, Class or Element to initialse the library against

Thresholds

warningThreshold: [Number] [Defaults to 25]

Character count threshold for the field to enter the warning state

dangerThreshold: [Number] [Defaults to 10]

Character count threshold for the field to enter the danger state

expendedThreshold: [Number] [Defaults to 100]

Character count for the maximum length of the field

Counter DOM Classes

counterClass: [String] [Defaults to 'cc-count']

Added to all counter elements

emptyClass: [String] [Defaults to 'cc-is-empty']

When the counter element's field is Empty

fineClass: [String] [Defaults to 'cc-is-fine']

When the counter element's field is Fine

warningClass: [String] [Defaults to 'cc-is-warning']

When the counter element's field is Warning

dangerClass: [String] [Defaults to 'cc-is-danger']

When the counter element's field is Danger

expendedClass: [String] [Defaults to 'cc-is-expended']

When the counter element's field is Expended

Callbacks

A field and remaining count is always sent to the method. The field is the element that called the event, with remaining being the current remaining character count of the field away from the expended state.

onFieldEmpty: (field, remaining) => {}

Fired when a fields text count is zero; not entirely sure on its continued usefulness

onFieldFine: (field, remaining) => {}

Fired when a fields text remaining count is a-okay, after coming from another state

onFieldWarning: (field, remaining) => {}

Fired when the desired warning threshold is reached

onFieldDanger: (field, remaining) => {}

Fired when the desired danger threshold is reached

onFieldExpended: (field, remaining) => {}

Fired when the remainder is all used up!

For example implementation of this, see src/example.app.js

Contributing & Development

If you wish to contribute, please just fork and play around! If you have any changes, just submit a PR.

Environment

The project utilises NPM for dependency management and webpack as a build tool, with a couple of NPM scripts setup to help with development.

When you first clone the project, run npm install from the project directory to get the baseline all squared away.

NPM Scripts

$ npm run dev

Build the development environment files, this is example.app.js to the docs directory

$ npm run watch

The usual watch script to automatically build the dev environment

$ npm run hot

Runs a webpack dev server at localhost:8080 from the docs directory, with hot module reloading

$ npm run prod

Builds the project out to the minified charcount.min.js in the dist directory

Project Structure

Directory	Description
dist	Stores assets for distribution
docs	Stores assets to be served up to GitHub pages and the local webpack dev server. Build ouput of dev, hot and watch
legacy	Stores the original jQuery library
src	Stores the source files for the project. This includes the entry point for the library itself CharCount.js, its core and its helpers. There are also example assets in there; example.app.js for implementation and scss (Sass) for styling

Todo

• Unit tests!
• Automatic build, probably on Semaphore CI