Merge pull request #355 from LevelbossMike/MIKE/remove-addon-docs

Use docfy - no more addon-docs.

Author: LevelbossMike

.docfy-config.js

@@ -0,0 +1,26 @@
+const autolinkHeadings = require('remark-autolink-headings');
+const docfyWithProse = require('@docfy/plugin-with-prose');
+const prism = require('@mapbox/rehype-prism');
+const refractor = require('refractor');
+
+refractor.alias('handlebars', 'hbs');
+refractor.alias('shell', 'sh');
+
+module.exports = {
+  tocMaxDepth: 3,
+  remarkPlugins: [
+    [
+      autolinkHeadings,
+      {
+        behavior: 'wrap',
+      },
+    ],
+  ],
+  plugins: [docfyWithProse],
+  rehypePlugins: [prism],
+  labels: {
+    components: 'Components',
+    workflow: 'Workflow',
+    docs: 'Documentation',
+  },
+};

.eslintignore

@@ -19,3 +19,6 @@
 /.node_modules.ember-try/
 /bower.json.ember-try
 /package.json.ember-try
+
+# api-docs
+/tests/dummy/public/api-docs/

.eslintrc.js

@@ -38,6 +38,8 @@ module.exports = {
         '.eslintrc.js',
         '.prettierrc.js',
         '.template-lintrc.js',
+        '.docfy-config.js',
+        'tailwind.config.js',
         'ember-cli-build.js',
         'index.js',
         'testem.js',
@@ -60,6 +62,10 @@ module.exports = {
       },
       plugins: ['node'],
       extends: ['plugin:node/recommended'],
+      rules: {
+        'node/no-unpublished-require': 'off',
+        'node/no-extraneous-require': 'off',
+      },
     },
   ],
 };

.gitignore

@@ -20,7 +20,12 @@
 /testem.log
 /yarn-error.log
 
+# generated api-docs
+/tests/dummy/public/api-docs/
+
 # ember-try
 /.node_modules.ember-try/
 /bower.json.ember-try
 /package.json.ember-try
+
+.DS_Store

.travis.yml

@@ -3,7 +3,7 @@ language: node_js
 node_js:
   # we recommend testing addons with the same minimum supported node version as Ember CLI
   # so that your addon works for all apps
-  - "10"
+  - "14"
 
 dist: xenial
 

addon/index.ts

@@ -11,6 +11,45 @@ import {
   Typestate,
 } from 'xstate';
 
+/**
+ * A decorator that can be used to create a getter that matches against an
+ * {@link InterpreterUsable}'s state and will return either `true` or `false`
+ *
+ *
+ * ```js
+ * import Component from '@glimmer/component';
+ * import buttonMachine from '../machines/button';
+ *
+ * export default class Button extends Component {
+ *  @use statechart = useMachine(buttonMachine)
+ *
+ *  @matchesState('disabled')
+ *  isDisabled; // true when statechart is in `disabled` state
+ *
+ *  @matchesState({ interactivity: 'disabled' })
+ *  isDisabled; // it is possible to match against nested/parallel states
+ * }
+ * ```
+ *
+ * You can match against any XState [StateValue](https://xstate.js.org/api/globals.html#statevalue)
+ *
+ * By default `matchesState` expects your {@link InterpreterUsable} to be called `statechart`.
+ * If you named it differently you can use the second param to this decorator:
+ *
+ *
+ * ```js
+ * import Component from '@glimmer/component';
+ * import buttonMachine from '../machines/button';
+ *
+ * export default class Button extends Component {
+ *  @use sc = useMachine(buttonMachine)
+ *
+ *  @matchesState('disabled', 'sc')
+ *  isDisabled;
+ * }
+ * ```
+ *
+ */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 function matchesState(
   state: StateValue,
@@ -35,7 +74,16 @@ function matchesState(
 
 /**
  * No-op typecast function that turns what TypeScript believes to be a
- * ConfigurableMachineDefinition function into a InterpreterUsable.
+ * {@link ConfigurableMachineDefinition} into an {@link InterpreterUsable}.
+ *
+ * TypeScript can't deal with decorators changing types thus we need this
+ * typecasting function because `@use`- will take what `useMachine`
+ * returns and initialize the actual usable which is the thing that you will
+ * work with from your code after accessing the usable's value.
+ *
+ * This function can be used in two ways:
+ *
+ * 1) Whenever you want to send an event to a statechart:
  *
  * ```js
  * import { useMachine, interpreterFor } from 'ember-statecharts';
@@ -52,10 +100,22 @@ function matchesState(
  * }
  * ```
  *
- * @param configurableMachineDefinition The ConfigurableMachineDefinition used
- * to initialize the `useMachine`-usable via `@use`
+ * 2) By wrapping `useMachine` directly. This way you don't have to litter the
+ *    rest of your code with `interpreterFor`:
+ *
+ * ```js
+ * import { useMachine, interpreterFor } from 'ember-statecharts';
+ *
+ * class Foo extends EmberObject {
+ *   @use statechart = interpreterFor(useMachine(...) {
+ *     // ...
+ *   })
  *
- * Note that this is purely a typecast function.
+ *   someMethod() {
+ *     this.statechart.send('WAT'); // ok!
+ *   }
+ * }
+ * ```
  */
 function interpreterFor<
   TContext,

addon/usables/use-machine.ts

@@ -58,6 +58,12 @@ export type UsableStatechart<
   | MachineConfig<TContext, TStateSchema, TEvent>
   | StateMachine<TContext, TStateSchema, TEvent, TTypestate>;
 
+/**
+ * An object that makes an XState-[Interpreter](https://xstate.js.org/docs/guides/interpretation.html)
+ * accessible to the outside world and allows `send`ing events to it.
+ *
+ * This is actually the return value of {@link InterpreterService.state}.
+ */
 export type InterpreterUsable<
   TContext,
   TStateSchema extends StateSchema,
@@ -134,6 +140,13 @@ export type UseMachineBucket<
   };
 };
 
+/**
+ * The actual usable that gets started when a {@link ConfigurableMachineDefinition} is `@use`d.
+ *
+ * On initial access this class will setup an XState-[Interpreter](https://xstate.js.org/docs/guides/interpretation.html)
+ * and make its state available to the outside world.
+ *
+ */
 export class InterpreterService<
   TContext,
   TStateSchema extends StateSchema,
@@ -159,6 +172,25 @@ export class InterpreterService<
     this.onTransition = onTransition;
   }
 
+  /**
+   * The object that gets returned when you access the Usable.
+   *
+   * ```js
+   * import Component from '@glimmer/component';
+   * import buttonMachine from '../machines/button';
+   *
+   * export default ButtonComponent extends Component {
+   *  @use statechart = useMachine(buttonMachine)
+   *
+   *  @action
+   *  buttonClicked() {
+   *    // acessing `statechart` will return the return value of this getter
+   *    this.statechart.send('CLICK');
+   *  }
+   * }
+   *
+   * ```
+   */
   get state(): {
     state: State<TContext, TEvent, TStateSchema, TTypestate>;
     send: Send<TContext, TStateSchema, TEvent, TTypestate>;
@@ -323,6 +355,81 @@ const createMachineInterpreterManager = () => {
 const MANAGED_INTERPRETER = {};
 setUsableManager(MANAGED_INTERPRETER, createMachineInterpreterManager);
 
+/**
+ * A function that lets you define a {@link ConfigurableMachineDefinition} that can be
+ * `@use`d.
+ *
+ *
+ * ```ts
+ * import Component from '@glimmer/component';
+ * import buttonMachine from '../machines/button';
+ *
+ * export default ButtonComponent extends Component {
+ *  @use statechart = useMachine(buttonMachine)
+ *
+ *  @action
+ *  buttonClicked() {
+ *    this.statechart.send('CLICK');
+ *  }
+ * }
+ * ```
+ *
+ * The {@link ConfigurableMachineDefinition} can be used to override properties
+ * of the {@link UsableStatechart} that was passed to `useMachine`.
+ *
+ * ```ts
+ * import Component from '@glimmer/component';
+ * import formMachine from '../machines/form';
+ * // ...
+ *
+ * export default FormComponent extends Component {
+ *  // ...
+ *  @use statechart = useMachine(formMachine)
+ *    .withContext({
+ *      // we can override the machine's context here
+ *      formObject: this.formObject
+ *    })
+ *    .withConfig({
+ *      services: {
+ *        // to override an async function that can be invoked
+ *        submitForm: this.submitForm
+ *      },
+ *      actions: {
+ *        notifyFormSubmission: this.notifyFormSubmission
+ *      },
+ *      guards: {
+ *        // ...
+ *      }
+ *    })
+ *    .onTransition((state) => {
+ *      // when you want to react to transitions manually
+ *    })
+ *    .update(({ send }) => {
+ *      // decide how to handle properties passed to `useMachine` changing
+ *      send('MY_EVENT_TO_HANDLE_ARGS_CHANGES');
+ *    })
+ *
+ *  @action
+ *  submitForm(context, event) {
+ *    return this.onSubmitForm(context.formObject);
+ *  }
+ *
+ *  @action
+ *  notifyFormSubmission() {
+ *    this.notifications.notify('Form was submitted');
+ *  }
+ * }
+ * ```
+ *
+ * A {@link ConfigurableMachineDefinition} is only used to configure how the
+ * interpreted {@link UsableStatechart} will behave when interacting with it.
+ *
+ * When accessing the `@use`d value you are actually dealing with a {@link
+ * InterpreterUsable} - i.e. an object that gives you access to the
+ * `state`-property of an XState-[Interpreter](https://xstate.js.org/docs/guides/interpretation.html)
+ * and a `send`-function that can be used to send events to the interpreter.
+ *
+ */
 export default function useMachine<
   TContext,
   TStateSchema extends StateSchema,

config/addon-docs.js

@@ -1,29 +1,12 @@
 /* eslint-env node */
 'use strict';
 
-module.exports = function (deployTarget) {
+module.exports = function (/* deployTarget */) {
   let ENV = {
     build: {},
-    // include other plugin configuration that applies to all deploy targets here
+    git: {
+      commitMessage: 'chore: deploy %@',
+    },
   };
-
-  if (deployTarget === 'development') {
-    ENV.build.environment = 'development';
-    // configure other plugins for development deploy target here
-  }
-
-  if (deployTarget === 'staging') {
-    ENV.build.environment = 'production';
-    // configure other plugins for staging deploy target here
-  }
-
-  if (deployTarget === 'production') {
-    ENV.build.environment = 'production';
-    // configure other plugins for production deploy target here
-  }
-
-  // Note: if you need to build some configuration asynchronously, you can return
-  // a promise that resolves with the ENV object instead of returning the
-  // ENV object synchronously.
   return ENV;
 };