Update docs

studiometa · Dec 4, 2024 · 6f725c2 · 6f725c2
1 parent 472f0b8
commit 6f725c2
Show file tree

Hide file tree

Showing 4 changed files with 160 additions and 0 deletions.
diff --git a/packages/docs/.vitepress/config.js b/packages/docs/.vitepress/config.js
@@ -209,6 +209,7 @@ function getServicesSidebar() {
     { text: 'useDrag', link: '/api/services/useDrag.html' },
     { text: 'useKey', link: '/api/services/useKey.html' },
     { text: 'useLoad', link: '/api/services/useLoad.html' },
+    { text: 'useMutation', link: '/api/services/useMutation.html' },
     { text: 'usePointer', link: '/api/services/usePointer.html' },
     { text: 'useRaf', link: '/api/services/useRaf.html' },
     { text: 'useResize', link: '/api/services/useResize.html' },
@@ -227,6 +228,7 @@ function getDecoratorsSidebar() {
     { text: 'withMountOnMediaQuery', link: '/api/decorators/withMountOnMediaQuery.html' },
     { text: 'withMountWhenInView', link: '/api/decorators/withMountWhenInView.html' },
     { text: 'withMountWhenPrefersMotion', link: '/api/decorators/withMountWhenPrefersMotion.html' },
+    { text: 'withMutation', link: '/api/decorators/withMutation.html' },
     { text: 'withRelativePointer', link: '/api/decorators/withRelativePointer.html' },
     { text: 'withResponsiveOptions', link: '/api/decorators/withResponsiveOptions.html' },
     { text: 'withScrolledInView', link: '/api/decorators/withScrolledInView.html' },
@@ -256,6 +258,7 @@ function getUtilsSidebar() {
       link: '/utils/',
       collapsed: true,
       items: [
+        { text: 'cache', link: '/utils/cache.html' },
         { text: 'createElement', link: '/utils/createElement.html' },
         { text: 'debounce', link: '/utils/debounce.html' },
         { text: 'keyCodes', link: '/utils/keyCodes.html' },

diff --git a/packages/docs/api/decorators/withMutation.md b/packages/docs/api/decorators/withMutation.md
@@ -0,0 +1,67 @@
+# withMutation
+
+Use this decorator to add a `mutated(props)` hook managed by the [mutation](/api/services/useMutation.html) service.
+
+## Usage
+
+```js
+import { Base, withMutation } from '@studiometa/js-toolkit';
+
+export default class Component extends withMutation(Base, {
+  target: (instance) => instance.$el,
+}) {
+  static config = {
+    name: 'Component',
+  };
+
+  mutated(props) {
+    for (const mutation of props.mutations) {
+      console.log(mutation); // MutationRecord
+    }
+  }
+}
+```
+
+### Parameters
+
+- `BaseClass` (`Base`): the class to add mutation observation to
+- `options?` (`{ target?: (instance:Base) => Node } & MutationObserverInit`): define which element should be observed (defaults to the component's root element) and any options for the mutation observer
+
+### Return value
+
+- `Base`: a new class extending the given class with mutation observability enabled
+
+## API
+
+### Class methods
+
+#### `mutated`
+
+The `mutated` class method will be triggered when a DOM mutation occurs on the given target.
+
+**Arguments**
+
+- `props` (`MutationServiceProps`): the [mutation service props](/api/services/useMutation.md#props)
+
+## Examples
+
+### Update a component when its children have changed
+
+This decorator can be used to update a component when its inner HTML has changed to rebind refs and child components.
+
+```js
+import { Base, withMutation } from '@studiometa/js-toolkit';
+
+export default class Component extends withMutation(Base, {
+  childList: true,
+  subtree: true,
+}) {
+  static config = {
+    name: 'Component',
+  };
+
+  mutated(props) {
+    this.$update();
+  }
+}
+```
diff --git a/packages/docs/api/services/useMutation.md b/packages/docs/api/services/useMutation.md
@@ -0,0 +1,62 @@
+# Mutation service
+
+The mutation service can be used to observe DOM mutations on a component with the MutationObserver API.
+
+## Usage
+
+```js
+import { useMutation } from '@studiometa/js-toolkit';
+
+const { add, remove } = useMutation();
+
+// Add a callback
+add('custom-id', ({ mutations }) => {
+  console.log('Some attribute has changed!');
+});
+
+// Remove the callback
+remove('custom-id');
+```
+
+## Parameters
+
+### `target`
+
+- Type: `Node`
+
+The target element to observe, defaults to `document.documentElement`.
+
+**Example**
+
+Observe any attribute mutation on the `<body>` element:
+
+```js
+const service = useMutation(document.body);
+```
+
+### `options`
+
+- Type: [`MutationObserverInit`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options)
+
+Options for the mutation observer, defaults to `{ attributes: true }` only.
+
+**Example**
+
+Observe everything on the given element:
+
+```js
+const element = document.querySelector('#element');
+const service = useMutation(element, {
+  attributes: true,
+  childList: true,
+  subtree: true,
+});
+```
+
+## Props
+
+### `mutations`
+
+- Type: `MutationRecord[]`
+
+The list of `MutationRecord` that triggered the callback.
diff --git a/packages/docs/utils/cache.md b/packages/docs/utils/cache.md
@@ -0,0 +1,28 @@
+# cache
+
+Cache the result of a function with a list of keys.
+
+## Usage
+
+```js
+import { cache } from '@studiometa/js-toolkit/utils';
+
+const keys = [document.body, Symbol('key')];
+const callback = () => performance.now();
+
+console.log(cache(keys, callback)); // 100
+console.log(cache(keys, callback) === cache(keys, callback)); // true
+
+setTimeout(() => {
+  console.log(cache(keys, callback)); // 100
+}, 100);
+```
+
+### Parameters
+
+- `keys` (`Array<any>`): a list of keys to be used to cache the result of the callback
+- `callback` (`() => any`): the callback executed to retrieve the value to cache
+
+### Return value
+
+The value returned by the `callback` function given as parameter.