Merge branch 'release/2.4.0'

.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.json

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

packages/demo/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/docs/.vitepress/config.js

@@ -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/api/helpers/getDirectChildren.md

@@ -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/getInstanceFromElement.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/isDirectChild.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/index.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

packages/docs/package.json

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

packages/js-toolkit/helpers/getDirectChildren.js

@@ -0,0 +1,48 @@
+import { isArray } from '../utils/index.js';
+
+/**
+ * @typedef {import('../Base/index.js').default} Base
+ */
+
+/**
+ * Get direct children from a parent when working with nested components.
+ *
+ * @template {Base} T
+ * @param   {Base} parentInstance
+ * @param   {string} parentName
+ * @param   {string} childrenName
+ * @returns {Array<T>}
+ */
+export function getDirectChildren(parentInstance, parentName, childrenName) {
+  const children = parentInstance.$children[childrenName];
+  const nestedParents = parentInstance.$children[parentName];
+
+  if (!isArray(children)) {
+    return [];
+  }
+
+  if (!isArray(nestedParents) || nestedParents.length <= 0) {
+    return children;
+  }
+
+  return children.filter((child) => {
+    return nestedParents.every((nestedParent) => {
+      const nestedChildren = nestedParent.$children[childrenName];
+      /* istanbul ignore next */
+      return isArray(nestedChildren) ? !nestedChildren.includes(child) : true;
+    });
+  });
+}
+
+/**
+ * Test if a component instance is a direct child from the given component.
+ *
+ * @param   {Base}    parentInstance
+ * @param   {string}  parentName
+ * @param   {string}  childrenName
+ * @param   {Base}    childInstance
+ * @returns {boolean}
+ */
+export function isDirectChild(parentInstance, parentName, childrenName, childInstance) {
+  return getDirectChildren(parentInstance, parentName, childrenName).includes(childInstance);
+}

packages/js-toolkit/helpers/index.js

@@ -1,4 +1,5 @@
 export { default as createApp } from './createApp.js';
+export * from './getDirectChildren.js';
 export { default as getInstanceFromElement } from './getInstanceFromElement.js';
 export { default as importOnInteraction } from './importOnInteraction.js';
 export { default as importWhenIdle } from './importWhenIdle.js';

packages/js-toolkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "A set of useful little bits of JavaScript to boost your project! 🚀",
   "publishConfig": {
     "access": "public"

packages/tests/__snapshots__/index.spec.js.snap

@@ -4,10 +4,12 @@ exports[`The package exports should export helpers and the Base class 1`] = `
 Array [
   "Base",
   "createApp",
+  "getDirectChildren",
   "getInstanceFromElement",
   "importOnInteraction",
   "importWhenIdle",
   "importWhenVisible",
+  "isDirectChild",
   "useDrag",
   "useKey",
   "useLoad",

packages/tests/helpers/__snapshots__/index.spec.js.snap

@@ -0,0 +1,13 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`helpers exports 1`] = `
+Array [
+  "createApp",
+  "getDirectChildren",
+  "getInstanceFromElement",
+  "importOnInteraction",
+  "importWhenIdle",
+  "importWhenVisible",
+  "isDirectChild",
+]
+`;