Merge pull request #8 from jonaskuske/dev

Beta release for v1
jonaskuske · Dec 5, 2018 · 77c77b8 · 77c77b8
2 parents 6595b21 + 07e0b3e
commit 77c77b8
Show file tree

Hide file tree

Showing 8 changed files with 6,018 additions and 75 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,7 @@
+language: node_js
+node_js:
+  - "node"
+install:
+  - npm install
+script:
+  - npm test
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0-beta]
+### Changed
+ - The README.md file has been updated to match the API of v1.0.0
+ - Fixed 'window is not defined' error in Node environments, important for usage with SSR
+ - BREAKING: Polyfill now only handles smooth scroll if scroll-behavior is set to 'smooth' via <html style="">, documentElement.style.scrollBehavior or a custom font-family (more information will be added to the documentation)
+### Added
+ - Tests for smooth scrolling when clicking anchors have been implemented
+
 ## [0.12.0] - 2018-11-15
 ### Added
 - The special fragment `#top` is now supported for scrolling to the top, but only if no element with id `top` is found

diff --git a/README.md b/README.md
@@ -1,15 +1,69 @@
-# smoothscroll-anchor-polyfill
-⚓ Apply smooth scroll to anchor links to replicate CSS property `scroll-behavior`
+<p align="center">
+  <a href="https://www.npmjs.com/package/smoothscroll-anchor-polyfill"><img align="center" src="https://img.shields.io/npm/v/smoothscroll-anchor-polyfill.svg" alt="NPM version"></a>
+  <a href="https://travis-ci.org/jonaskuske/smoothscroll-anchor-polyfill"><img align="center" src="https://travis-ci.org/jonaskuske/smoothscroll-anchor-polyfill.svg?branch=dev" alt="Build status"></a>
+  <a href="./LICENSE"><img align="center" src="https://img.shields.io/npm/l/smoothscroll-anchor-polyfill.svg" alt="License"></a>
+</p>  
 
-> ⚠ Requires a polyfill for `window.scroll()` and `Element.scrollIntoView()` (e.g. [smoothscroll-polyfill](http://iamdustan.com/smoothscroll/)) to work! ⚠
+&nbsp;  
+&nbsp;  
 
-## Installation
+<h1 align="center">smoothscroll-anchor-polyfill</h1>
+<p align="center">⚓ Apply smooth scroll to anchor links to polyfill the CSS property <code>scroll-behavior</code></p>
 
-### From CDN
+&nbsp;  
+&nbsp;  
+
+## Browser support
+⚠ Requires smooth scroll for `window.scroll()` and `Element.scrollIntoView()` (e.g. [smoothscroll-polyfill](http://iamdustan.com/smoothscroll/)) to work!
+
+| [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt="IE / Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>IE / Edge | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Firefox | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Safari | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari-ios/safari-ios_48x48.png" alt="iOS Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>iOS Safari | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/opera/opera_48x48.png" alt="Opera" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Opera |
+| --------- | --------- | --------- | --------- | --------- | --------- |
+| IE9+, Edge| native| native*| last 2 versions| last 2 versions| native*  
+
+> \* hashchange navigation triggered by forwards/backwards buttons isn't smooth despite native support. [Learn more](https://jonaskuske.github.io/smoothscroll-anchor-polyfill#hashchange)
+
+&nbsp;  
+
+## Usage
+
+### 1. Set `scroll-behavior: smooth` in CSS
+> Has to be set global (on `html`), [check the docs for limitations](https://jonaskuske.github.io/smoothscroll-anchor-polyfill#limitations)  
+
+Because CSS properties unknown to a browser can't efficiently be parsed from JavaScript, using normal stylesheets is not enough unfortunately. To specify the property in a way the polyfill can read it, you have two options:
+#### 1a. Using inline styles
+```html
+<html style="scroll-behavior: smooth;">
+...
+</html>
+```
+
+#### 1b. Using `font-family` as workaround
+Alternatively, you can specify the property as the name of a custom font family. Your actual fonts will still work the way they should (plus, you can simply declare actual fonts on `body`). Unlike inline styles, this allows you to use normal CSS features like media queries. The following only enables smooth scroll on desktop devices, for example:
+```html
+<style>
+  html {
+    scroll-behavior: instant;
+    font-family: 'scroll-behavior: instant;', 'Roboto', sans-serif;
+  }
+  @media screen and (min-width: 1150px) {
+    html {
+      scroll-behavior: smooth;
+      font-family: 'scroll-behavior: smooth;', 'Roboto', sans-serif;
+    }
+  }
+</style>
+```
+> This process can also be automated using a [PostCSS plugin](https://github.com/jonaskuske/postcss-smoothscroll-anchor-polyfill), so you can write regular CSS and don't have to bother with font-families. It just works™
+
+### 2. Install the polyfill
+Because this polyfill only wires up anchor links to use the browser's native `window.scroll()` and `element.scrollIntoView()` methods, you'll need to load a polyfill providing smooth scroll to these methods in addition to the steps outlined below.
+> [smoothscroll-polyfill](http://iamdustan.com/smoothscroll/) works, but you can just as well use another one or write your own implementation. [Learn More](https://jonaskuske.github.io/smoothscroll-anchor-polyfill#requirements)
+#### 2a. From a CDN
 ```html
 <script src="https://unpkg.com/smoothscroll-anchor-polyfill"></script>
 ```
-### Or with npm
+
+#### 2b. From npm
 ```bash
 npm install smoothscroll-anchor-polyfill
 ```
@@ -18,10 +72,24 @@ then
 ```js
 import 'smoothscroll-anchor-polyfill';
 ```
-## Documentation & Demo
 
-Found [here](https://jonaskuske.github.io/smoothscroll-anchor-polyfill).
+&nbsp;  
+
+## Full Documentation & Demo
+
+> ⚠ The documentation is not up-to-date as of now, it will be updated  when this packages leaves the beta phase.
+
+The full documentation with advanced installation instructions, known limitations, features like enabling and disabling the smooth scroll and more can be found at
+[**jonaskuske.github.io/smoothscroll-anchor-polyfill**](https://jonaskuske.github.io/smoothscroll-anchor-polyfill).  
+The documentation site itself is built as a smooth scrolling one-page design, utilizing this polyfill.
+
+&nbsp;  
+&nbsp;
 
 ___
 
-**PRs welcome!**
+**PRs welcome!**  
+
+  &nbsp;  
+
+© 2018, Jonas Kuske
diff --git a/index.css b/index.css
@@ -1,5 +1,7 @@
 html {
   scroll-behavior: smooth;
+  /* Additionally specified in custom font-family so polyfill can parse it */
+  font-family: 'scroll-behavior:smooth';
 }
 
 body {