Merge branch 'hotfix/2.4.3'

Author: titouanmathis

package-lock.json

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

package.json

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

packages/demo/package.json

@@ -8,9 +8,10 @@ To improve DX and autocompletion of a components' properties, it is possible to
 
 ```ts
 class Base<BaseInterface extends {
-  $options: BaseOptions;
-  $refs: BaseRefs;
-  $children: BaseChildren;
+  $el: HTMLElement;
+  $options: Record<string, any>;
+  $refs: Record<string, HTMLElement | HTMLElement[]>;
+  $children: Record<string, Base | Promise<Base>>;
 }>
 ```
 
@@ -20,7 +21,9 @@ See below for an example of how to define the type parameter in JSDoc or in Type
 This guide assumes that you are familiar with [TypeScript types](https://www.typescriptlang.org/), make sure to read the basics before going any further.
 :::
 
-## With JSDoc comments
+## Basic types
+
+### With JSDoc comments
 
 ```js
 import { Base } from '@studiometa/js-toolkit';
@@ -30,7 +33,8 @@ import { Figure } from '@studiometa/ui';
  * @typedef {{ name: string, lazy: boolean }} ComponentOptions
  * @typedef {{ btn: HTMLButtonElement, items: HTMLElement[] }} ComponentRefs
  * @typedef {{ Figure: Figure, LazyComponent: Promise<LazyComponent> }} ComponentChildren
- * @extends {Base<{ $options: ComponentOptions, $refs: ComponentRefs, $children: ComponentChildren }>}
+ * @typedef {{ $el: HTMLAnchorElement, $options: ComponentOptions, $refs: ComponentRefs, $children: ComponentChildren }} ComponentInterface
+ * @extends {Base<ComponentInterface>}
  */
 export default class Component extends Base {
   static config = {
@@ -47,6 +51,7 @@ export default class Component extends Base {
   };
 
   mounted() {
+    this.$el; // HTMLAnchorElement
     this.$refs.btn; // HTMLButtonElement
     this.$refs.items; // HTMLElement[]
     this.$options.name; // string
@@ -57,33 +62,30 @@ export default class Component extends Base {
 }
 ```
 
-## With TypeScript
+### With TypeScript
 
 ```ts
 import { Base } from '@studiometa/js-toolkit';
 import { Figure } from '@studiometa/ui';
 import type LazyComponent from './LazyComponent.js';
 
-type ComponentOptions {
-  name: string;
-  lazy: boolean;
-}
-
-type ComponentRefs {
-  btn: HTMLButtonElement;
-  items: HTMLElement[];
-}
-
-type ComponentChildren {
-  Figure: Figure;
-  LazyComponent: Promise<LazyComponent>
-}
+type ComponentInterface = {
+  $el: HTMLAnchorElement;
+  $options: {
+    name: string;
+    lazy: boolean;
+  };
+  $refs: {
+    btn: HTMLButtonElement;
+    items: HTMLElement[];
+  };
+  $children: {
+    Figure: Figure;
+    LazyComponent: Promise<LazyComponent>;
+  };
+};
 
-export default class Component extends Base<{
-  $options: ComponentOptions,
-  $refs: ComponentRefs,
-  $children: ComponentChildren,
-}> {
+export default class Component extends Base<ComponentInterface> {
   static config = {
     name: 'Component',
     refs: ['btn', 'items[]'],
@@ -98,6 +100,7 @@ export default class Component extends Base<{
   };
 
   mounted() {
+    this.$el; // HTMLAnchorElement
     this.$refs.btn; // HTMLButtonElement
     this.$refs.items; // HTMLElement[]
     this.$options.name; // string
@@ -107,3 +110,63 @@ export default class Component extends Base<{
   }
 }
 ```
+
+## Typing for extensibility
+
+If you create a component that can be extended by other component, you will need to define a type parameter for it.
+
+### With JSDoc comments
+
+You will need to declare types in a separate comment from the class and import the `BaseTypeParameter` type from the `@studiometa/js-toolkit` package.
+
+```js {2,10,11}
+/**
+ * @typedef {import('@studiometa/js-toolkit').BaseTypeParameter} BaseTypeParameter
+ * @typedef {{ name: string, lazy: boolean }} ComponentOptions
+ * @typedef {{ btn: HTMLButtonElement, items: HTMLElement[] }} ComponentRefs
+ * @typedef {{ Figure: Figure, LazyComponent: Promise<LazyComponent> }} ComponentChildren
+ * @typedef {{ $el: HTMLAnchorElement, $options: ComponentOptions, $refs: ComponentRefs, $children: ComponentChildren }} ComponentInterface
+ */
+
+/**
+ * @template {BaseTypeParameter} [Interface={}]
+ * @extends {Base<Interface & ComponentInterface>}
+ */
+export default class Component extends Base {
+  // ...
+}
+```
+
+You will then be able to use the `Component` class like the `Base` class:
+
+```js
+import Component from './Component.js';
+
+/**
+ * @extends {Component<{ $el: HTMLButtonElement >}}
+ */
+export default class ChildComponent extends Component {
+  // ...
+}
+```
+
+### With TypeScript
+
+```ts
+import { Base } from '@studiometa/js-toolkit';
+import type { BaseTypeParameter } from '@studiometa/js-toolkit';
+
+export default class Component<Interface extends BaseTypeParameter = {}> extends Base<
+  Interface & ComponentInterface
+> {
+  // ...
+}
+```
+
+```ts
+import Component from './Component.js';
+
+export default class ChildComponent extends Component<{ $el: HTMLButtonElement }> {
+  // ...
+}
+```

packages/docs/guide/going-further/typing-components.md

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

packages/docs/package.json

@@ -55,7 +55,7 @@ function createAndTestManagers(instance) {
 /**
  * @typedef {typeof Base} BaseConstructor
  * @typedef {(Base) => Promise<BaseConstructor | { default: BaseConstructor }>} BaseAsyncConstructor
- * @typedef {OptionsManager & { [name:string]: any }} BaseOptions
+ * @typedef {{ [name:string]: any }} BaseOptions
  * @typedef {{ [name:string]: HTMLElement | HTMLElement[] }} BaseRefs
  * @typedef {{ [nameOrSelector:string]: Base[] | Promise<Base>[] }} BaseChildren
  * @typedef {{ [nameOrSelector:string]: BaseConstructor | BaseAsyncConstructor }} BaseConfigComponents
@@ -74,6 +74,15 @@ function createAndTestManagers(instance) {
  * @property {BaseConfigOptions} [options]
  */
 
+/**
+ * @typedef {{
+ *   $el?: HTMLElement,
+ *   $options?: BaseOptions,
+ *   $refs?: BaseRefs,
+ *   $children?: { [name:string]: Base | Promise<Base> },
+ * }} BaseTypeParameter
+ */
+
 /**
  * @typedef {Object} Managers
  * @property {typeof ChildrenManager} ChildrenManager
@@ -85,7 +94,7 @@ function createAndTestManagers(instance) {
 
 /**
  * Base class.
- * @template {{ $options: BaseOptions, $refs: BaseRefs, $children: BaseChildren }} BaseInterface
+ * @template {BaseTypeParameter} [BaseInterface={ $el: HTMLElement, $options: BaseOptions, $refs: BaseRefs, $children: { [name:string]: Base | Promise<Base> } }]
  */
 export default class Base extends EventTarget {
   /**
@@ -109,7 +118,7 @@ export default class Base extends EventTarget {
 
   /**
    * The root element.
-   * @type {HTMLElement & { __base__?: WeakMap<BaseConstructor, Base | 'terminated'> }}
+   * @type {BaseInterface['$el'] & HTMLElement & { __base__?: WeakMap<BaseConstructor, Base | 'terminated'> }}
    */
   $el;
 
@@ -217,39 +226,39 @@ export default class Base extends EventTarget {
   }
 
   /**
-   * @type {RefsManager & { [key in keyof BaseInterface['$refs']]: BaseInterface['$refs'][key] }}
+   * @type {RefsManager & { [key in keyof BaseInterface['$refs']]: BaseInterface['$refs'][key] } & BaseRefs}
    * @private
    */
   __refs;
 
   /**
-   * @returns {RefsManager & { [key in keyof BaseInterface['$refs']]: BaseInterface['$refs'][key] }}
+   * @returns {RefsManager & { [key in keyof BaseInterface['$refs']]: BaseInterface['$refs'][key] } & BaseRefs}
    */
   get $refs() {
     return this.__refs;
   }
 
   /**
-   * @type {BaseOptions & { [key in keyof BaseInterface['$options']]: BaseInterface['$options'][key] }}
+   * @type {OptionsManager & { [key in keyof BaseInterface['$options']]: BaseInterface['$options'][key] } & BaseOptions}
    * @private
    */
   __options;
 
   /**
-   * @returns {BaseOptions & { [key in keyof BaseInterface['$options']]: BaseInterface['$options'][key] }}
+   * @returns {OptionsManager & { [key in keyof BaseInterface['$options']]: BaseInterface['$options'][key] } & BaseOptions}
    */
   get $options() {
     return this.__options;
   }
 
   /**
-   * @type {ChildrenManager & { [key in keyof BaseInterface['$children']]: Array<BaseInterface['$children'][key]> }}
+   * @type {ChildrenManager & { [key in keyof BaseInterface['$children']]: Array<BaseInterface['$children'][key]> } & BaseChildren}
    * @private
    */
   __children;
 
   /**
-   * @returns {ChildrenManager & { [key in keyof BaseInterface['$children']]: Array<BaseInterface['$children'][key]> }}
+   * @returns {ChildrenManager & { [key in keyof BaseInterface['$children']]: Array<BaseInterface['$children'][key]> } & BaseChildren}
    */
   get $children() {
     return this.__children;

packages/js-toolkit/Base/index.js

@@ -235,7 +235,7 @@ export default class EventsManager extends AbstractManager {
 
       let index = 0;
       if (isArray(this.__base.$refs[refName])) {
-        index = this.__base.$refs[refName].indexOf(ref);
+        index = /** @type {HTMLElement[]} */ (this.__base.$refs[refName]).indexOf(ref);
       }
 
       this.__base[method](event, index);
@@ -259,6 +259,7 @@ export default class EventsManager extends AbstractManager {
         .map((childName) => ({
           name: childName,
           child: childrenManager[childName].find(
+            // @ts-ignore
             (instance) => instance === event.currentTarget || instance.$el === event.currentTarget
           ),
         }))

packages/js-toolkit/Base/managers/EventsManager.js

@@ -11,7 +11,7 @@ import { isArray } from '../utils/index.js';
  * @param   {Base} parentInstance
  * @param   {string} parentName
  * @param   {string} childrenName
- * @returns {Array<T>}
+ * @returns {T[]}
  */
 export function getDirectChildren(parentInstance, parentName, childrenName) {
   const children = parentInstance.$children[childrenName];
@@ -22,16 +22,19 @@ export function getDirectChildren(parentInstance, parentName, childrenName) {
   }
 
   if (!isArray(nestedParents) || nestedParents.length <= 0) {
-    return children;
+    return /** @type {T[]} */ (children);
   }
 
-  return children.filter((child) => {
-    return nestedParents.every((nestedParent) => {
-      const nestedChildren = nestedParent.$children[childrenName];
-      /* istanbul ignore next */
-      return isArray(nestedChildren) ? !nestedChildren.includes(child) : true;
-    });
-  });
+  return /** @type {T[]} */ (
+    children.filter((child) => {
+      return nestedParents.every((nestedParent) => {
+        // @ts-ignore
+        const nestedChildren = nestedParent.$children[childrenName];
+        /* istanbul ignore next */
+        return isArray(nestedChildren) ? !nestedChildren.includes(child) : true;
+      });
+    })
+  );
 }
 
 /**

packages/js-toolkit/helpers/getDirectChildren.js

@@ -2,3 +2,7 @@ export { default as Base } from './Base/index.js';
 export * from './decorators/index.js';
 export * from './helpers/index.js';
 export * from './services/index.js';
+
+/**
+ * @typedef {import('./Base/index.js').BaseTypeParameter} BaseTypeParameter
+ */

packages/js-toolkit/index.js

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