diff --git a/.changeset/selfish-humans-hope.md b/.changeset/selfish-humans-hope.md deleted file mode 100644 index 4a32e656..00000000 --- a/.changeset/selfish-humans-hope.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -'ember-statecharts': minor ---- - -## 🥁 Features - -### InterpreterOptions -Bring back ability to customize [InterpreterOptions](https://xstate.js.org/docs/guides/interpretation.html#options) that are used when a machine passed to `useMachine` gets interpreted. This is probably most useful for people that want to have xState delays etc. be scheduled via a custom clock service that uses [Ember's runloop](https://guides.emberjs.com/release/applications/run-loop/), but can be used to pass other [interpreterOptions](https://xstate.js.org/docs/guides/interpretation.html#options) as well. - -To customize `interpreterOptions`, when you would like to provide the same options every time you use `useMachine`, you can create a wrapper-function for `useMachine`: - -Example: - -```js -const wrappedUseMachine = (context, options) => { - return useMachine(context, () => { - return { - interpreterOptions: { - clock: { - setTimeout(fn, timeout) { - later.call(null, fn, timeout); - }, - clearTimeout(id) { - cancel.call(null, id); - }, - }, - }, - ...options(), - }; - }); -}; - -statechart = wrappedUseMachine(this, () => { - // ... -}); -``` - -### `runloopClockService`-configuration option -For the use-case of having xState timeouts etc. be schedule via the runloop, `ember-statecharts` now provides a configuration option. You can turn it on to have xState use a custom [clock](https://xstate.js.org/docs/guides/delays.html#interpretation) and schedule, and cancel timeouts via the ember-runloop. This makes testing via `@ember/test-helpers` arguably more ergonomic, as you won't need to explicitly await ui changes that are triggered by schedule statechart changes explicitly anymore. - -Example - based on the test that tests this behavior: - -```js -import { module, test } from 'qunit'; -import { setupRenderingTest } from 'test-app/tests/helpers'; -import { click, render, waitUntil } from '@ember/test-helpers'; -import { hbs } from 'ember-cli-htmlbars'; - -module('Integration | Component | use-machine', function (hooks) { - setupRenderingTest(hooks); - - test('awaiting needs to be explicit with no `runloopClockService`-option set', async function (assert) { - const config = this.owner.resolveRegistration('config:environment'); - - config['ember-statecharts'] = { - runloopClockService: false, - }; - - await render(hbs``); - - assert.dom('[data-test-off]').exists('initially toggle is off'); - - await click('[data-test-toggle]'); - - // oh noes, we need to wait explicitly as xState uses `window.setTimeout` by default 😢 - await waitUntil(() => { - return document.querySelector('[data-test-off]'); - }); - - assert.dom('[data-test-off]').exists('initially toggle is off'); - }); - - test('awaiting happens automatically when `runloopClockService`-option is set', async function (assert) { - const config = this.owner.resolveRegistration('config:environment'); - - config['ember-statecharts'] = { - runloopClockService: true, - }; - - await render(hbs``); - - assert.dom('[data-test-off]').exists('initially toggle is off'); - - // just awaiting the click is enough now, because we schedule delays on the runloop 🥳 - await click('[data-test-toggle]'); - - assert.dom('[data-test-off]').exists('initially toggle is off'); - }); -}); -``` - -To turn on this behavior, you can set the `runloopClockService`-configuration in `config/environment.js`: - -```js -ENV['ember-statecharts'] = { - runloopClockService: true -} -``` diff --git a/ember-statecharts/CHANGELOG.md b/ember-statecharts/CHANGELOG.md index ed5cbfd5..51f4279c 100644 --- a/ember-statecharts/CHANGELOG.md +++ b/ember-statecharts/CHANGELOG.md @@ -1,3 +1,105 @@ +## 0.16.0 + +### Minor Changes + +- 9ee0ef3: [#393 Allow passing interpreterOptions to useMachine](https://github.com/LevelbossMike/ember-statecharts/pull/393) - [LevelbossMike](https://github.com/levelbossmike) + ## 🥁 Features + + ### InterpreterOptions + + Bring back ability to customize [InterpreterOptions](https://xstate.js.org/docs/guides/interpretation.html#options) that are used when a machine passed to `useMachine` gets interpreted. This is probably most useful for people that want to have xState delays etc. be scheduled via a custom clock service that uses [Ember's runloop](https://guides.emberjs.com/release/applications/run-loop/), but can be used to pass other [interpreterOptions](https://xstate.js.org/docs/guides/interpretation.html#options) as well. + + To customize `interpreterOptions`, when you would like to provide the same options every time you use `useMachine`, you can create a wrapper-function for `useMachine`: + + Example: + + ```js + const wrappedUseMachine = (context, options) => { + return useMachine(context, () => { + return { + interpreterOptions: { + clock: { + setTimeout(fn, timeout) { + later.call(null, fn, timeout); + }, + clearTimeout(id) { + cancel.call(null, id); + }, + }, + }, + ...options(), + }; + }); + }; + + statechart = wrappedUseMachine(this, () => { + // ... + }); + ``` + + ### `runloopClockService`-configuration option + + For the use-case of having xState timeouts etc. be schedule via the runloop, `ember-statecharts` now provides a configuration option. You can turn it on to have xState use a custom [clock](https://xstate.js.org/docs/guides/delays.html#interpretation) and schedule, and cancel timeouts via the ember-runloop. This makes testing via `@ember/test-helpers` arguably more ergonomic, as you won't need to explicitly await ui changes that are triggered by schedule statechart changes explicitly anymore. + + Example - based on the test that tests this behavior: + + ```js + import { module, test } from 'qunit'; + import { setupRenderingTest } from 'test-app/tests/helpers'; + import { click, render, waitUntil } from '@ember/test-helpers'; + import { hbs } from 'ember-cli-htmlbars'; + + module('Integration | Component | use-machine', function (hooks) { + setupRenderingTest(hooks); + + test('awaiting needs to be explicit with no `runloopClockService`-option set', async function (assert) { + const config = this.owner.resolveRegistration('config:environment'); + + config['ember-statecharts'] = { + runloopClockService: false, + }; + + await render(hbs``); + + assert.dom('[data-test-off]').exists('initially toggle is off'); + + await click('[data-test-toggle]'); + + // oh noes, we need to wait explicitly as xState uses `window.setTimeout` by default 😢 + await waitUntil(() => { + return document.querySelector('[data-test-off]'); + }); + + assert.dom('[data-test-off]').exists('initially toggle is off'); + }); + + test('awaiting happens automatically when `runloopClockService`-option is set', async function (assert) { + const config = this.owner.resolveRegistration('config:environment'); + + config['ember-statecharts'] = { + runloopClockService: true, + }; + + await render(hbs``); + + assert.dom('[data-test-off]').exists('initially toggle is off'); + + // just awaiting the click is enough now, because we schedule delays on the runloop 🥳 + await click('[data-test-toggle]'); + + assert.dom('[data-test-off]').exists('initially toggle is off'); + }); + }); + ``` + + To turn on this behavior, you can set the `runloopClockService`-configuration in `config/environment.js`: + + ```js + ENV['ember-statecharts'] = { + runloopClockService: true, + }; + ``` + ## 0.15.1 ### Patch Changes diff --git a/ember-statecharts/package.json b/ember-statecharts/package.json index af42b9fe..2f48e3de 100644 --- a/ember-statecharts/package.json +++ b/ember-statecharts/package.json @@ -1,6 +1,6 @@ { "name": "ember-statecharts", - "version": "0.15.1", + "version": "0.16.0", "description": "Statecharts for Ember.js applications", "keywords": [ "ember-addon" diff --git a/site/CHANGELOG.md b/site/CHANGELOG.md index 5592e711..72c7870c 100644 --- a/site/CHANGELOG.md +++ b/site/CHANGELOG.md @@ -1,5 +1,12 @@ # site +## 0.13.5 + +### Patch Changes + +- Updated dependencies [9ee0ef3] + - ember-statecharts@0.16.0 + ## 0.13.4 ### Patch Changes diff --git a/site/package.json b/site/package.json index fcb1eefb..e6988825 100644 --- a/site/package.json +++ b/site/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "site", - "version": "0.13.4", + "version": "0.13.5", "description": "Site for ember-statecharts", "homepage": "https://ember-statecharts.com/", "repository": "https://github.com/LevelbossMike/ember-statecharts",