JigSass Generic Normalize

[![NPM version][npm-image]][npm-url] [![Dependency Status][daviddm-image]][daviddm-url]

> Modular, configurable, opt-in browser normalization

JigSass Normalize is a modularized and configurable version of Nicolas Gallagher and
Jonathan Neal's normalize.css at version 4.0.0.

Normalize.css is a modern alternative to css resets, which preserves useful defaults and corrects
bugs and common browser inconsistencies.

Installation

Using npm:

``sh
npm i -S jigsass-generic-normalize
`

Usage

`scss
@import 'path/to/jigsass-generic-normalize'/scss/index;
`

Jigsass Normalize will not output any CSS, unless explicitly included using one of the mixins.

Jigsass Normalize's
configuration variables allow
overriding the very few default opinionated choices made by normalize.css.

To include all or parts of JigSass Normalize's submodules, use the
jigsass-normalize
mixin.

JigSass Normalize offers mixins for including each of the submodules, and a shortcut mixin,
jigsass-normalize, to include all parts at once.

The styles of each JigSass Normalize submodule will only be included a single time,
where they were imported.

Check out the documentation for more details

Extended details and known issues

Additional detail and explanation of the esoteric parts of normalize.css.

#### pre, code, kbd, samp

The font-family: monospace, monospace hack fixes the inheritance and scaling
of font-size for preformatted text. The duplication of monospace is
intentional. Source.

#### sub, sup

Normally, using sub or sup affects the line-box height of text in all
browsers. Source.

#### svg:not(:root)

Adding overflow: hidden fixes IE9's SVG rendering. Earlier versions of IE
don't support SVG, so we can safely use the :not() and :root selectors that
modern browsers use in the default UA stylesheets to apply this style. [Source]
(https://lists.w3.org/Archives/Public/public-svg-wg/2008JulSep/0339.html).

#### select

By default, Chrome on OS X and Safari on OS X allow very limited styling of
select, unless a border property is set. The default font weight on optgroup
elements cannot safely be changed in Chrome on OSX and Safari on OS X.

#### [type="checkbox"]

It is recommended that you do not style checkbox and radio inputs as Firefox's
implementation does not respect box-sizing, padding, or width.

#### [type="number"]

Certain font size values applied to number inputs cause the cursor style of the
decrement button to change from default to text.

#### [type="search"]

The search input is not fully stylable by default. In Chrome and Safari on
OSX/iOS you can't control font, padding, border, or background. In
Chrome and Safari on Windows you can't control border properly. It will apply
border-width but will only show a border color (which cannot be controlled)
for the outer 1px of that border. Applying -webkit-appearance: textfield
addresses these issues without removing the benefits of search inputs (e.g.
showing past searches). Safari (but not Chrome) will clip the cancel button on
when it has padding (and textfield appearance).

Development

It is a best practice for JigSass modules to not automatically generate css on @import, but
rather have to user explicitly enable the generation of specific styles from the module.

Contributions in the form of pull-requests, issues, bug reports, etc. are welcome.
Please feel free to fork, hack or modify JigSass Generic Normalize in any way you see fit.

#### Writing documentation

Good documentation is crucial for scalability and maintainability. When contributing,
please do make sure that all Sass functionality (functions, mixins,
variables and placeholder selectors) is well documented.

Documentation is auto-generated using SassDoc

#### Running tests
gulp lint will, well, lint the contents scss files in the scss directory.

gulp test with run module's test using Mocha and Sassaby.

gulp tdd will watch both the Sass files and the test specs for changes, and will
run tests automatically upon them.

#### Writing tests

JigSass Generic Normalize tests are written using Sassaby
and Mocha. Spec files are located in the test directory.

Mocha allows us to place a call to before() in the root of any test file and it
will be run once, before all the other tests in every test_*.js file.
We can also require() files and assign them to the global object to make them
available to all test_*.js files.

jigsass-generic-normalize uses a file called helper.js can be used to set up mocha
globals requires and before().

In addition to Sassaby's testing functions, jigsass-generic-normalize makes a few Sass
functions available to the test suite, for use inside Sassaby tests:

jig-var-equals($value, $var) -> {boolean}

Check if a variable equals a value.

$value {*}: A value to compare the value of $var to.

$var {*}: The variable to test

jig-var-type-is($type, $var) -> {boolean}

Check if a variable is of a certain type.

$type {string}: A type to compare with the type of $var.

$var {*}: The variable to test

jig-map-key-equals($value, $map, $keys...) -> {boolean}

Check if a map's key is assigned a cerain value.

$value {*}: A value to compare the value of a key in $map with.

$map {map}: The map to test.

$keys... {arglist}: A recursive chain of keys.

jig-map-key-type-is($type, $map, keys...) -> {boolean}

Check if a map's key is of a certain type

$type {string}: A type to compare with the type of $var.

$map {map}: The map to test.

$keys... {arglist}: A recursive chain of keys.




File structure


`bash
┬ ./
│
├─┬ scss/
│ └─ index.scss # The module's importable file.
│
├── sassdoc/ # Generated documentation
│ # of the module's sass features
│
└─┬─ test/
│
├─┬ helpers/
│ │
│ ├── importer.scss # Used for easilty importing tested scss files
│ │
│ └── _test_helpers.scss # JigSass's assertion helpers,
│ # for use inside Sassaby tests.
│
├── helper.js # Used for defining global before()
│ # functions and requiring modules.
│
└── test_jigsass-generic-normalize # Specs. Mocha will automatically
# run all javascript files located
# in the test directory.
``

License: MIT

[npm-image]: https://badge.fury.io/js/jigsass-generic-normalize.svg
[npm-url]: https://npmjs.org/package/jigsass-generic-normalize

[daviddm-image]: https://david-dm.org/TxHawks/jigsass-generic-normalize.svg?theme=shields.io
[daviddm-url]: https://david-dm.org/TxHawks/jigsass-generic-normalize