Feature/10 add usetimeout and useinterval hooks

src/useInterval/useInterval.stories.mdx

@@ -0,0 +1,72 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta
+  title="useInterval/docs"
+/>
+
+# useInterval
+
+The `useInterval` hook is a wrapper around the native `setInterval`, it allows you to easily create set
+an interval within your component that will be auto cancelled when the component unmounts.
+
+## Reference
+
+```ts
+function useInterval(
+  callback: () => void,
+  interval?: number = 100,
+  startImmediate?: boolean = true,
+): { startInterval: () => void, stopInterval: () => void }
+```
+
+### Parameters
+* `callback` – The callback you want to trigger once the interval runs.
+* `interval` - The duration of the interval you want to create.
+* `startImmediate` - Whether or not you want to immediately start the interval.
+
+### Returns
+* `{ startInterval, stopInterval }`
+  * `startInterval` – A function that starts the interval, any running intervals will automatically be stopped.
+  * `stopInterval` – A function that will stop the current active interval.
+
+## Usage
+
+```ts
+const { startInterval, stopInterval } = useInterval(() => {
+  console.log('The interval has run')
+}, 1000, false);
+````
+
+```ts
+const Demo = defineComponent({
+  name: 'demo',
+  refs: {
+    startBtn: 'start-button'
+    stopButton: 'stop-button'
+  },
+  setup({ refs }) {
+    // The interval starts as soon as the component is mounted.
+    useInterval(() => {
+      console.log('The immediate interval callback is triggered.')
+    }, 1000);
+
+    // The interval doesn't start automatically, but requires a user action to start.
+    const { startInterval, stopInterval } = useInterval(() => {
+      console.log('The user-action interval callback is triggered.')
+    }, 1000, false);
+
+    return [
+      bind(refs.startBtn, {
+        click() {
+         startInterval(); // This actually starts the interval.
+        }
+      }),
+      bind(refs.stopButton, {
+        click() {
+          stopInterval(); // This stops the interval if it's active.
+        }
+      })
+    ]
+  }
+})
+```

src/useInterval/useInterval.stories.ts

@@ -0,0 +1,89 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { bind, computed, defineComponent, propType, ref } from '@muban/muban';
+import type { Story } from '@muban/storybook/types-6-0';
+import { html } from '@muban/template';
+import { useInterval } from './useInterval';
+import { useStorybookLog } from '../hooks/useStorybookLog';
+
+export default {
+  title: 'useInterval',
+};
+
+type DemoStoryProps = { startImmediate?: boolean; interval?: number };
+
+export const Demo: Story<DemoStoryProps> = () => ({
+  component: defineComponent({
+    name: 'story',
+    props: {
+      startImmediate: propType.boolean.defaultValue(false),
+      interval: propType.number,
+    },
+    refs: {
+      label: 'label',
+      startButton: 'start-button',
+      stopButton: 'stop-button',
+    },
+    setup({ refs, props }) {
+      const [logBinding, log] = useStorybookLog(refs.label);
+      const isIntervalRunning = ref(false);
+
+      const { startInterval, stopInterval } = useInterval(
+        onInterval,
+        props.interval,
+        props.startImmediate,
+      );
+
+      function onInterval() {
+        log('interval called');
+      }
+
+      return [
+        logBinding,
+        bind(refs.startButton, {
+          attr: {
+            disabled: isIntervalRunning,
+          },
+          click() {
+            isIntervalRunning.value = true;
+            startInterval();
+          },
+        }),
+        bind(refs.stopButton, {
+          attr: {
+            disabled: computed(() => !isIntervalRunning.value),
+          },
+          click() {
+            isIntervalRunning.value = false;
+            log('interval stopped');
+            stopInterval();
+          },
+        }),
+      ];
+    },
+  }),
+  template: ({ startImmediate = false, interval = 2500 }: DemoStoryProps = {}) => html`<div
+    data-component="story"
+    data-start-immediate=${startImmediate}
+    data-interval=${interval}
+  >
+    <div class="alert alert-primary">
+      <h4 class="alert-heading">Instructions!</h4>
+      <p class="mb-0">
+        The demo interval is set to 2.5 seconds, you can start it by clicking the start button. You
+        can stop the interval by clicking the stop button.
+      </p>
+    </div>
+    <div data-ref="label" />
+    <div class="card border-dark">
+      <div class="card-header">Test Area</div>
+      <div class="card-body">
+        <button type="button" data-ref="start-button" class="btn btn-primary">
+          Start interval
+        </button>
+        ${' '}
+        <button type="button" data-ref="stop-button" class="btn btn-danger">Stop interval</button>
+      </div>
+    </div>
+  </div>`,
+});
+Demo.storyName = 'demo';

src/useInterval/useInterval.test.ts

@@ -0,0 +1,85 @@
+import { runComponentSetup } from '@muban/test-utils';
+import { timeout } from '../useTimeout/useTimeout.test.utils';
+import { useInterval } from './useInterval';
+
+jest.mock('@muban/muban', () => jest.requireActual('@muban/test-utils').getMubanLifecycleMock());
+
+describe('useInterval', () => {
+  it('should not crash', async () => {
+    await runComponentSetup(() => {
+      useInterval(() => undefined);
+    });
+  });
+
+  it('should start immediate and not be completed', async () => {
+    const mockHandler = jest.fn();
+
+    await runComponentSetup(() => {
+      useInterval(mockHandler, 100);
+    });
+
+    expect(mockHandler).toBeCalledTimes(0);
+  });
+
+  it('should start immediate and be called once', async () => {
+    const mockHandler = jest.fn();
+
+    await runComponentSetup(
+      () => useInterval(mockHandler, 100),
+      async ({ stopInterval }) => {
+        await timeout(100);
+        stopInterval();
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(1);
+  });
+
+  it('should trigger start and be stopped after three calls', async () => {
+    const mockHandler = jest.fn();
+
+    await runComponentSetup(
+      () => useInterval(mockHandler, 100, false),
+      async ({ startInterval, stopInterval }) => {
+        startInterval();
+        await timeout(400);
+        stopInterval();
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(3);
+  });
+
+  it('should trigger stop once the interval is started', async () => {
+    const mockHandler = jest.fn();
+
+    await runComponentSetup(
+      () => useInterval(mockHandler, 200, false),
+      async ({ startInterval, stopInterval }) => {
+        startInterval();
+        await timeout(100);
+        stopInterval();
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(0);
+  });
+
+  it('should start a new interval before the old one was triggered and only complete once', async () => {
+    const mockHandler = jest.fn();
+
+    await runComponentSetup(
+      () => {
+        return useInterval(mockHandler, 100, false);
+      },
+      async ({ startInterval }) => {
+        startInterval();
+        await timeout(50);
+        startInterval();
+        await timeout(100);
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(1);
+  });
+});

src/useInterval/useInterval.ts

@@ -0,0 +1,36 @@
+import { onMounted, onUnmounted } from '@muban/muban';
+
+/**
+ *  A hook that can be used to call a function on a provided interval, by default the interval
+ *  will run immediate. You can also start and cancel the interval whenever needed.
+ *
+ * @param callback The callback you want to trigger once the interval runs.
+ * @param interval The duration of the interval you want to create.
+ * @param startImmediate Whether or not you want to immediately start the interval.
+ */
+export const useInterval = (
+  callback: () => void,
+  interval: number = 100,
+  startImmediate: boolean = true,
+): { startInterval: () => void; stopInterval: () => void } => {
+  let handle = -1;
+
+  function start() {
+    stop();
+    handle = setInterval(callback, interval) as unknown as number;
+  }
+
+  function stop() {
+    clearInterval(handle);
+  }
+
+  onUnmounted(() => {
+    stop();
+  });
+
+  onMounted(() => {
+    if (startImmediate) start();
+  });
+
+  return { startInterval: start, stopInterval: stop };
+};

src/useInterval/useIntervalStories.test.ts

@@ -0,0 +1,39 @@
+import '@testing-library/jest-dom';
+import { waitFor, render } from '@muban/testing-library';
+import { Demo } from './useInterval.stories';
+import { timeout } from '../useTimeout/useTimeout.test.utils';
+
+describe('useInterval stories', () => {
+  it('should render', () => {
+    const { getByText } = render(Demo);
+
+    expect(getByText('Test Area')).toBeInTheDocument();
+  });
+
+  it('should start immediate and be called after 100ms', async () => {
+    const { getByText } = render(Demo, { startImmediate: true, interval: 100 });
+
+    await waitFor(() => expect(getByText('interval called')).toBeInTheDocument());
+  });
+
+  it('should start after clicking start and be called after 100ms', async () => {
+    const { getByText, getByRef } = render(Demo, { interval: 100 });
+    const startButton = getByRef('start-button');
+
+    startButton.click();
+
+    await waitFor(() => expect(getByText('interval called')).toBeInTheDocument());
+  });
+
+  it('should stop the interval after starting', async () => {
+    const { getByText, getByRef } = render(Demo, { interval: 100 });
+    const startButton = getByRef('start-button');
+    const stopButton = getByRef('stop-button');
+
+    startButton.click();
+    await timeout(100);
+    stopButton.click();
+
+    await waitFor(() => expect(getByText('interval stopped')).toBeInTheDocument());
+  });
+});

src/useTimeout/useTimeout.stories.mdx

@@ -0,0 +1,72 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta
+  title="useTimeout/docs"
+/>
+
+# useTimeout
+
+The `useTimeout` hook is a wrapper around the native `setTimeout`, it allows you to easily create set
+a timeout within your component that will be auto cancelled when the component unmounts.
+
+## Reference
+
+```ts
+function useTimeout(
+  callback: () => void,
+  duration?: number = 100,
+  startImmediate?: boolean = true,
+): { startTimeout: () => void, cancelTimeout: () => void }
+```
+
+### Parameters
+* `callback` – The function to invoke when the timeout runs out.
+* `duration` - The duration of the timeout you want to create.
+* `startImmediate` - Whether or not you want to immediately start the timeout.
+
+### Returns
+* `{ startTimeout, cancelTimeout }`
+  * `startTimeout` – A function that starts the timeout, any running timeouts will automatically be cancelled.
+  * `cancelTimeout` – A function that will cancel the current active timeout.
+
+## Usage
+
+```ts
+const { startTimeout, cancelTimeout } = useTimeout(() => {
+  console.log('The timeout has run out')
+}, 1000, false);
+````
+
+```ts
+const Demo = defineComponent({
+  name: 'demo',
+  refs: {
+    startBtn: 'start-button'
+    cancelButton: 'cancel-button'
+  },
+  setup({ refs }) {
+    // The timeout runs as soon as the component is mounted.
+    useTimeout(() => {
+      console.log('The timeout has run out')
+    }, 1000);
+
+    // The timeout doesn't start automatically, but requires a user action to start.
+    const { startTimeout, cancelTimeout } = useTimeout(() => {
+      console.log('The timeout has run out')
+    }, 1000, false);
+
+    return [
+      bind(refs.startBtn, {
+        click() {
+         startTimeout(); // This actually starts the timeout.
+        }
+      }),
+      bind(refs.cancelButton, {
+        click() {
+          cancelTimeout(); // This cancels the timeout if it's active.
+        }
+      })
+    ]
+  }
+})
+```