Merge branch 'release/2.4.0'

Author: titouanmathis

.github/workflows/tests.yml

@@ -68,5 +68,5 @@ jobs:
       - uses: antfu/export-size-action@v1
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          build_script: npm run build-for-export-size
-          paths: ./dist
+          build_script: node ./scripts/add-utils-export.js
+          paths: packages/js-toolkit

README.md

@@ -5,7 +5,7 @@
 [![Dependency Status](https://img.shields.io/librariesio/release/npm/@studiometa/js-toolkit?style=flat-square)](https://david-dm.org/studiometa/js-toolkit)
 ![Codecov](https://img.shields.io/codecov/c/github/studiometa/js-toolkit?style=flat-square)
 
-> A set of useful little bits of JavaScript to boost your project! 🚀
+> A JavaScript data-attributes driven micro-framework shipped with plenty of useful utility functions to boost your project.
 
 ## Installation
 
@@ -15,9 +15,9 @@ Install the latest version via NPM:
 npm install @studiometa/js-toolkit
 ```
 
-## Documentation
+## What is it?
 
-This project contains a JavaScript micro-framework and its utility functions whose main objectives are:
+This project is a JavaScript micro-framework (along with its utility functions) whose main objectives are:
 
 - Enforcing best-practice and consistency between projects
 - Using elements from the DOM easily

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit-workspace",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "private": true,
   "workspaces": [
     "packages/*"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit-demo",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "private": true,
   "type": "commonjs",
   "scripts": {

packages/demo/package.json

@@ -7,8 +7,8 @@ const pkg = JSON.parse(
 
 export default defineConfig({
   lang: 'en-US',
-  title: 'JS Toolkit',
-  description: 'A set of useful little bits of JavaScript to boost your project! 🚀',
+  title: 'A JavaScript data-attributes driven micro-framework',
+  description: 'The JS Toolkit by Studio Meta is a JavaScript data-attributes driven micro-framework shipped with plenty of useful utility functions to boost your project.',
   lastUpdated: true,
   head: [['link', { rel: 'icon', type: 'image/x-icon', href: '/logo.png' }]],
   themeConfig: {
@@ -198,10 +198,12 @@ function getDecoratorsSidebar() {
 function getHelpersSidebar() {
   return [
     { text: 'createApp', link: '/api/helpers/createApp.html' },
+    { text: 'getDirectChildren', link: '/api/helpers/getDirectChildren.html' },
     { text: 'getInstanceFromElement', link: '/api/helpers/getInstanceFromElement.html' },
     { text: 'importOnInteraction', link: '/api/helpers/importOnInteraction.html' },
     { text: 'importWhenIdle', link: '/api/helpers/importWhenIdle.html' },
     { text: 'importWhenVisible', link: '/api/helpers/importWhenVisible.html' },
+    { text: 'isDirectChild', link: '/api/helpers/isDirectChild.html' },
   ];
 }
 

packages/docs/.vitepress/config.js

@@ -0,0 +1,43 @@
+# getDirectChildren
+
+Use the `getDirectChildren` function to get a list components which are direct descendants of the given parent instance. This function is helpful when working with nested components which declare themselves as children.
+
+:::tip
+If you need to only check if an instance is a direct descendant of another instance, prefer the [`isDirectChild` helper function](/api/helpers/isDirectChild.md) which will return a `boolean` directly.
+:::
+
+## Usage
+
+```js {1,9,16}
+import { Base, getDirectChildren } from '@studiometa/js-toolkit';
+import Child from './Child.js';
+
+class Parent extends Base {
+  static config = {
+    name: 'Parent',
+    components: {
+      Child,
+      Parent, // Useful for recursive components only
+    },
+  };
+
+  onChildClick(index, event) {
+    const childInstance = this.$children.Child[index];
+    const directChildren = getDirectChildren(this, 'Parent', 'Child');
+
+    if (directChildren.includes(childInstance)) {
+      event.preventDefault();
+    }
+  }
+}
+```
+
+**Parameters**
+
+- `parentInstance` (`Base`): the target element
+- `parentName` (`string`): the name of the recursive parent as specified in the `config.components` object.
+- `childrenName` (`string`): the name of the children components as specified in the `config.components` object.
+
+**Return value**
+
+- `Base[]`: a list of the direct child components corresponding to the given `childrenName`

packages/docs/api/helpers/getDirectChildren.md

@@ -14,7 +14,7 @@ const componentInstance = getInstanceFromElement(document.body, Component);
 **Parameters**
 
 - `element` (`HTMLElement`): the target element
-- `BaseConstructor`: (`BaseConstructor`): the class (constructor) of the component to look for
+- `BaseConstructor` (`BaseConstructor`): the class (constructor) of the component to look for
 
 **Return value**
 

packages/docs/api/helpers/getInstanceFromElement.md

@@ -0,0 +1,39 @@
+# isDirectChild
+
+Use the `isDirectChild` function to test if a child component instance is a direct descendant of the given parent instance. This function is helpful when working with nested components which declare themselves as children.
+
+## Usage
+
+```js {1,9,16}
+import { Base, isDirectChild } from '@studiometa/js-toolkit';
+import Child from './Child.js';
+
+class Parent extends Base {
+  static config = {
+    name: 'Parent',
+    components: {
+      Child,
+      Parent, // Useful for recursive components only
+    },
+  };
+
+  onChildClick(index, event) {
+    const childInstance = this.$children.Child[index];
+
+    if (isDirectChild(this, 'Parent', 'Child', childInstance)) {
+      event.preventDefault();
+    }
+  }
+}
+```
+
+**Parameters**
+
+- `parentInstance` (`Base`): the parent instance.
+- `parentName` (`string`): the name of the recursive parent as specified in the `config.components` object.
+- `childName` (`string`): the name of the child component as specified in the `config.components` object.
+- `childInstance` (`Base`): the child instance.
+
+**Return value**
+
+- `boolean`: `true` if the given child instance is a direct descendant of the given parent instance.

packages/docs/api/helpers/isDirectChild.md

@@ -1,6 +1,8 @@
 ---
 layout: home
 sidebar: false
+title: A data-attributes driven micro-framework
+description: The JS Toolkit by Studio Meta is a JavaScript data-attributes driven micro-framework shipped with plenty of useful utility functions to boost your project.
 hero:
   name: JS Toolkit
   text: A data-attributes driven micro framework