feat(v3)!: [closes #177] Convert to TypeScript (#178)

In this commit: - Convert Shifty to be authored in TypeScript - Publish ES5 artifacts - Remove Core build - Switch from JSDoc to TypeDoc - Fix various minor bugs Breaking changes: - `Tweenable.formulas` has been renamed to `Tweenable.easing` - `tweenConfig.step` has been removed in favor of `tweenConfig.render` (behavior and API is unchanged). - `tweenConfig.attachment` has been removed in favor of `tweenConfig.data` (behavior and API is unchanged). - `Tweenable#tweenable` has been removed. - `Tweenable#set()` is now `Tweenable#setState`. - `Tweenable#get()` is now `Tweenable#state` (a getter, not a method). - `Tweenable#hasEnded()` is now `Tweenable#hasEnded` (a getter, not a method). - `Tweenable#isPlaying()` is now `Tweenable#isPlaying` (a getter, not a method). - `Tweenable#setScheduleFunction` has been removed. The static method `Tweenable.setScheduleFunction` method should be used instead. - Render handler parameters have been reordered: - In v2, the function signature was `(state: TweenState, data: Data, timeElapsed: number) => void` - In v3, the function signature was `(state: TweenState, timeElapsed: number, data: Data) => void` - `Scene#play()` has been renamed to `Scene#tween`. - `Scene#isPlaying()` is now `Scene#isPlaying` (a getter, not a method). - `Scene#playingTweenables()` has been removed. - `unsetBezierFunction` has been removed. - Shifty "Core" build has been removed.
jeremyckahn · Jul 2, 2023 · 1f4725f · 1f4725f
1 parent fee93af
commit 1f4725f
Show file tree

Hide file tree

Showing 39 changed files with 9,848 additions and 9,374 deletions.
diff --git a/.babelrc b/.babelrc
@@ -1,4 +1,4 @@
 {
-  "presets": ["@babel/preset-env"],
+  "presets": ["@babel/preset-env", "@babel/preset-typescript"],
   "plugins": ["@babel/plugin-proposal-class-properties"]
 }
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -5,18 +5,15 @@
     "es6": true,
     "jest": true
   },
-  "extends": ["eslint:recommended", "prettier"],
-  "parser": "babel-eslint",
-  "plugins": ["jest", "prettier"],
+  "extends": [
+    "eslint:recommended",
+    "prettier",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["jest", "prettier", "@typescript-eslint"],
+  "root": true,
   "rules": {
-    "linebreak-style": ["error", "unix"],
-    "valid-jsdoc": [
-      "error",
-      {
-        "requireReturn": false,
-        "requireReturnDescription": false,
-        "requireParamDescription": false
-      }
-    ]
+    "linebreak-style": ["error", "unix"]
   }
 }
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,7 +12,20 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: 16
-      - run: npm ci
-      - run: npm run ci
-      - run: npm run build
+          node-version: 18
+
+      - name: 'Validate code'
+        run: |
+          npm ci
+          npm run ci
+
+      - name: 'Build code'
+        run: |
+          npm run build
+          npm run doc
+
+      - name: 'Upload artifacts'
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-output
+          path: dist
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -16,7 +16,7 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
 
       - run: npm ci
       - run: npm run build

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -25,7 +25,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
           registry-url: 'https://registry.npmjs.org'
 
       - name: Install dependencies

diff --git a/.jsdoc b/.jsdoc
diff --git a/.jshintrc b/.jshintrc
diff --git a/README.md b/README.md
@@ -1,22 +1,20 @@
-# Shifty - The fastest JavaScript animation engine on the web
+# Shifty - The fastest TypeScript animation engine on the web
 
 [![Current Shifty version](https://badgen.net/npm/v/shifty)](https://www.npmjs.com/package/shifty)
 
 - `main`: [![CI](https://github.com/jeremyckahn/shifty/workflows/CI/badge.svg?branch=main)](https://github.com/jeremyckahn/shifty/actions?query=workflow%3ACI+branch%3Amain)
 
-Shifty is a tweening engine for JavaScript. It is a lightweight library meant
+Shifty is a tweening engine for TypeScript. It is a lightweight library meant
 to be encapsulated by higher level tools. At its core, Shifty provides:
 
-- Best-in-class performance
-- Interpolation of `Number`s over time (tweening)
+- Best-in-class animation performance
 - Playback control of an individual tween
-- Extensibility hooks for key points in the tweening process
+- Extensibility hooks for key points in the tween lifecycle
 - `Promise` support for `async`/`await` programming
 
 This is useful because it is the least amount of functionality needed to build
-customizable animations. Shifty is optimized to run many times a second with
-minimal processing and memory overhead, which is necessary to achieve smooth
-animations.
+customizable animations. Shifty is optimized to run with the minimal processing
+and memory overhead.
 
 ```js
 import { tween } from 'shifty'
@@ -52,24 +50,11 @@ npm install --save shifty
 ## Environment compatibility
 
 Shifty officially supports Evergreen browsers, Safari, and Node 10 and above.
-If you encounter a browser-specific bug, please [open an issue about
+Internet Explorer is supported by
+[v2](https://github.com/jeremyckahn/shifty/tree/v2) If you encounter a
+browser-specific bug, please [open an issue about
 it](https://github.com/jeremyckahn/shifty/issues/new)!
 
-### IE compatibility
-
-Shifty is compatible with IE11 (possibly older versions as well), but you
-will need to provide your own polyfills for it to work. If you are using
-https://polyfill.io/, you just need the `es6` features enabled:
-
-```
-https://polyfill.io/v3/polyfill.min.js?features=es6
-```
-
-[Here's a polyfilled demo of Shifty that works with
-IE11](https://codepen.io/jeremyckahn/pen/RwbzvEj). Please see [issue
-#113](https://github.com/jeremyckahn/shifty/issues/113) for background on
-this.
-
 ## Support this project!
 
 Shifty is a labor of love that will always be free and open source. If you've
@@ -78,7 +63,7 @@ small donation](https://github.com/jeremyckahn#please-help-support-my-work)**!
 
 ## Developing Shifty
 
-First, install the dependencies via npm like so:
+First, install the development dependencies via NPM:
 
 ```
 npm ci
@@ -96,18 +81,12 @@ To run the tests:
 npm test
 ```
 
-To generate the documentation (`dist/doc`):
+To generate the documentation (in `dist/doc`):
 
 ```
 npm run doc
 ```
 
-To generate live documentation to preview in your browser:
-
-```
-npm run doc:live
-```
-
 ## Loading Shifty
 
 Shifty exposes a UMD module, so you can load it however you like:
@@ -137,7 +116,7 @@ tween({ from: { x: 0 }, to: { x: 10 } })
 
 ## Using Shifty
 
-Please see the [Getting
+See the [Getting
 Started](https://jeremyckahn.github.io/shifty/doc/tutorial-getting-started.html)
 guide and check out the API documentation.
 
@@ -165,20 +144,48 @@ afterAll(() => {
 })
 ```
 
-## Releasing
-
-Releases are done from the CLI. Assuming you have commit access, use [`npm version`](https://docs.npmjs.com/cli/v8/commands/npm-version) to tag and push a
-new release in a single operation. This will kick off [a GitHub
-action](https://github.com/jeremyckahn/shifty/blob/develop/.github/workflows/publish-package.yml)
-that builds and publishes Shifty to NPM.
+## Breaking changes
+
+### From v2 to v3
+
+Shifty's legacy version 2 remains available in the
+[v2](https://github.com/jeremyckahn/shifty/tree/v2) branch. Legacy
+documentation can be found at:
+https://shifty-git-v2-jeremyckahn.vercel.app/doc/
+
+- `Tweenable.formulas` has been renamed to `Tweenable.easing`
+- `tweenConfig.step` has been removed in favor of `tweenConfig.render`
+  (behavior and API is unchanged).
+- `tweenConfig.attachment` has been removed in favor of `tweenConfig.data`
+  (behavior and API is unchanged).
+- `Tweenable#tweenable` has been removed.
+- `Tweenable#set()` is now `Tweenable#setState`.
+- `Tweenable#get()` is now `Tweenable#state` (a getter, not a method).
+- `Tweenable#hasEnded()` is now `Tweenable#hasEnded` (a getter, not a method).
+- `Tweenable#isPlaying()` is now `Tweenable#isPlaying` (a getter, not a
+  method).
+- `Tweenable#setScheduleFunction` has been removed. The static method
+  `Tweenable.setScheduleFunction` method should be used instead.
+- Render handler parameters have been reordered:
+  - In v2, the function signature was `(state: TweenState, data: Data, timeElapsed: number) => void`
+  - In v3, the function signature was `(state: TweenState, timeElapsed: number, data: Data) => void`
+- `Scene#play()` has been renamed to `Scene#tween`.
+- `Scene#isPlaying()` is now `Scene#isPlaying` (a getter, not a method).
+- `Scene#playingTweenables()` has been removed.
+- `unsetBezierFunction` has been removed.
+- Shifty "Core" build has been removed.
+
+#### Non-breaking changes
+
+- Token extension is now baked into Shifty Core.
 
 ## Contributors
 
-Take a peek at the [Network](https://github.com/jeremyckahn/shifty/network)
+Take a look at the [Network](https://github.com/jeremyckahn/shifty/network)
 page to see all of the Shifty contributors.
 
 Special thanks goes to [Thomas Fuchs](https://twitter.com/thomasfuchs):
-Shifty's easing formulas and Bezier curve code was adapted from his awesome
+Shifty's easing functions and Bezier curve code was adapted from his awesome
 [Scripty2](https://github.com/madrobby/scripty2) project.
 
 ## License

diff --git a/index.md b/index.md
@@ -2,9 +2,10 @@
 
 **_The fastest JavaScript animation engine on the web_**
 
-### `npm install --save shifty`
+- `npm install --save shifty`
+- `https://unpkg.com/shifty`
 
-[![Current Shifty version](https://badgen.net/npm/v/shifty)](https://www.npmjs.com/package/shifty) [![Shifty license](https://badgen.net/github/license/jeremyckahn/shifty)](https://github.com/jeremyckahn/shifty/blob/develop/LICENSE-MIT) [![Downloads per week](https://badgen.net/npm/dw/shifty)](https://www.npmjs.com/package/shifty) [![GitHub stars](https://badgen.net/github/stars/jeremyckahn/shifty)](https://github.com/jeremyckahn/shifty/stargazers) [![Repo dependents](https://badgen.net/github/dependents-repo/jeremyckahn/shifty)](https://github.com/jeremyckahn/shifty/network/dependents)
+[![Current Shifty version](https://badgen.net/npm/v/shifty)](https://www.npmjs.com/package/shifty) [![Shifty license](https://badgen.net/github/license/jeremyckahn/shifty)](https://github.com/jeremyckahn/shifty/blob/develop/LICENSE-MIT) [![Shifty full bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/shifty@latest)](https://unpkg.com/shifty) [![Downloads per week](https://badgen.net/npm/dw/shifty)](https://www.npmjs.com/package/shifty) [![GitHub stars](https://badgen.net/github/stars/jeremyckahn/shifty)](https://github.com/jeremyckahn/shifty/stargazers) [![Repo dependents](https://badgen.net/github/dependents-repo/jeremyckahn/shifty)](https://github.com/jeremyckahn/shifty/network/dependents)
 
 ## [Source code](https://github.com/jeremyckahn/shifty)
 
@@ -15,21 +16,14 @@ Shifty is a highly-optimized JavaScript tweening engine designed to fit all of y
 - **Renderer-agnostic**: Shifty does not perform any rendering, but it can be easily integrated into whatever rendering mechanism is most appropriate for your project such as DOM or `<canvas>`.
 - **`Promise` support**: Shifty's tweens are `await`-able [thenables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then). ([Learn about the benefits of `async`/`await`-based animations here](https://dev.to/jeremyckahn/the-case-for-async-await-based-javascript-animations-pkl)).
 
-### Load from CDN
-
-| Variant | URL                                            | Size                                                                                                                                                            | Description                                                                                    |
-| ------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Full    | `https://unpkg.com/shifty`                     | [![Shifty full bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/shifty@latest)](https://unpkg.com/shifty)                                         | Contains full library                                                                          |
-| Core    | `https://unpkg.com/shifty/dist/shifty.core.js` | [![Shifty core bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/shifty@latest/dist/shifty.core.js)](https://unpkg.com/shifty/dist/shifty.core.js) | Contains {@link shifty.Tweenable}, {@link shifty.tween}, and {@link shifty.Tweenable.formulas} |
-
 <p class="codepen" data-height="590" data-theme-id="dark" data-default-tab="js,result" data-user="jeremyckahn" data-slug-hash="PoNNNye" style="height: 590px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="Shifty async/await demo">
   <span>See the Pen <a href="https://codepen.io/jeremyckahn/pen/PoNNNye">
   Shifty async/await demo</a> by Jeremy Kahn (<a href="https://codepen.io/jeremyckahn">@jeremyckahn</a>)
   on <a href="https://codepen.io">CodePen</a>.</span>
 </p>
 <script async src="https://static.codepen.io/assets/embed/ei.js"></script>
 
-Shifty powers [Stylie](https://jeremyckahn.github.io/stylie/) and [Mantra](https://jeremyckahn.github.io/mantra/), a suite of graphical animation tools. It is also the tweening engine used by [GDevelop](https://gdevelop-app.com/) and [ProgessBar.js](https://progressbarjs.readthedocs.io/en/latest/#how-it-works). Even [Yelp](http://engineeringblog.yelp.com/2015/01/animating-the-mobile-web.html) has used it!
+Shifty powers [Stylie](https://jeremyckahn.github.io/stylie/) and [Mantra](https://jeremyckahn.github.io/mantra/), a suite of graphical animation tools. It is also the tweening engine used by [GDevelop](https://gdevelop.io/) and [ProgessBar.js](https://progressbarjs.readthedocs.io/en/latest/#how-it-works). Even [Yelp](http://engineeringblog.yelp.com/2015/01/animating-the-mobile-web.html) has used it!
 
 **Please use, fork, and contribute to Shifty! It is distributed under the MIT License, and experimentation is encouraged. If you find a bug or have a question about Shifty, please submit it via the [GitHub issue tracker](https://github.com/jeremyckahn/shifty/issues).**
 
@@ -51,15 +45,14 @@ Shifty is meant to be a lightweight alternative to rich tools like the excellent
 
 Shifty's tiny footprint compares very favorably against other popular animation libraries:
 
-| Library       | Size                                                                                                                                                            |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Shifty (full) | [![Shifty full bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/shifty@latest)](https://bundlephobia.com/result?p=shifty)                         |
-| Shifty (core) | [![Shifty core bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/shifty@latest/dist/shifty.core.js)](https://unpkg.com/shifty/dist/shifty.core.js) |
-| GreenSock     | [![GreenSock bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/gsap)](https://bundlephobia.com/result?p=gsap)                                      |
-| AnimeJS       | [![AnimeJS bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/animejs)](https://bundlephobia.com/result?p=animejs)                                  |
-| `@mojs/core`  | [![@core/mojs bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/@mojs/core)](https://bundlephobia.com/result?p=@mojs/core)                         |
-| Velocity      | [![Velocity bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/velocity-animate)](https://bundlephobia.com/result?p=velocity-animate)               |
-| Popmotion     | [![Popmotion bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/popmotion)](https://bundlephobia.com/result?p=popmotion)                            |
+| Library      | Size                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Shifty       | [![Shifty bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/shifty@latest)](https://bundlephobia.com/result?p=shifty)                |
+| GreenSock    | [![GreenSock bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/gsap)](https://bundlephobia.com/result?p=gsap)                        |
+| AnimeJS      | [![AnimeJS bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/animejs)](https://bundlephobia.com/result?p=animejs)                    |
+| `@mojs/core` | [![@core/mojs bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/@mojs/core)](https://bundlephobia.com/result?p=@mojs/core)           |
+| Velocity     | [![Velocity bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/velocity-animate)](https://bundlephobia.com/result?p=velocity-animate) |
+| Popmotion    | [![Popmotion bundle size](https://badgen.net/badgesize/gzip/https/unpkg.com/popmotion)](https://bundlephobia.com/result?p=popmotion)              |
 
 ## Examples
 
@@ -86,9 +79,9 @@ This next example demonstrates how `await`ed tweens interoperate well with stand
 </p>
 <script async src="https://static.codepen.io/assets/embed/ei.js"></script>
 
-### Tweening with a custom easing formula
+### Tweening with a custom easing
 
-<p data-height="265" data-theme-id="0" data-slug-hash="xqpLQg" data-default-tab="js,result" data-user="jeremyckahn" data-embed-version="2" data-pen-title="Tweening with a custom easing formula" class="codepen">See the Pen <a href="http://codepen.io/jeremyckahn/pen/xqpLQg/">Tweening with a custom easing formula</a> by Jeremy Kahn (<a href="http://codepen.io/jeremyckahn">@jeremyckahn</a>) on <a href="http://codepen.io">CodePen</a>.</p>
+<p data-height="265" data-theme-id="0" data-slug-hash="xqpLQg" data-default-tab="js,result" data-user="jeremyckahn" data-embed-version="2" data-pen-title="Tweening with a custom easing" class="codepen">See the Pen <a href="http://codepen.io/jeremyckahn/pen/xqpLQg/">Tweening with a custom easing</a> by Jeremy Kahn (<a href="http://codepen.io/jeremyckahn">@jeremyckahn</a>) on <a href="http://codepen.io">CodePen</a>.</p>
 <script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
 
 ### Shifting a color

diff --git a/jsdoc-ts.js b/jsdoc-ts.js