@arrai-innovations/reactive-helpers 8.1.0 → 8.1.1

package/.eslintrc.cjs

@@ -5,7 +5,7 @@ module.exports = {
         node: true,
     },
     plugins: ["jsdoc"],
-    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier", "plugin:jsdoc/recommended-error"],
+    extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/prettier", "plugin:jsdoc/recommended"],
 
     rules: {
         "no-console": "off", // console.error is useful.

package/docs.md

@@ -9,6 +9,35 @@
 | [utils/lifecycleDebug]       | Debug lifecycle hooks                                                                                                        |
 | [utils/transformWalk]        | Object walking utility.                                                                                                      |
 
+## Constants
+
+| Name               | Description |
+| ------------------ | ----------- |
+| [objectifyClasses] |
+| [combineClasses]   |
+| [stringifyClass]   |
+| [stringifyClasses] |
+
+## Functions
+
+| Name                         | Description |
+| ---------------------------- | ----------- |
+| [useCombineClasses(classes)] |
+
+## Typedefs
+
+| Name                 | Description                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------ |
+| [CSSValue]           | A string representing a CSS class or a space-separated list of CSS classes.                            |
+| [CSSObject]          | A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class. |
+| [CSSClasses]         | A mixed array containing multiple ways of specifying CSS classes.                                      |
+| [CSSStringOrObject]  | The amalgamated classes as returned by `objectifyClasses` & `combineClasses`.                          |
+| [CSSValue]           | A string representing a CSS class or a space-separated list of CSS classes.                            |
+| [CSSObject]          | A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class. |
+| [CSSClasses]         | A mixed array containing multiple ways of specifying CSS classes.                                      |
+| [CSSClassesWithRefs] | A mixed array containing multiple ways of specifying CSS classes.                                      |
+| [CSSStringOrObject]  | A CSS object or a space-separated list of CSS classes.                                                 |
+
 ## utils/assignReactiveObject
 
 Reactive object assignment utilities
@@ -320,6 +349,105 @@ const transformed = transformWalk(obj, (key, value, path) => {
 // }
 ```
 
+## objectifyClasses
+
+**Kind**: global constant  
+**Returns**: [`CSSStringOrObject`][1] - A CSS object or a space-separated list of CSS classes.
+
+| Param      | Type           | Description                                                       |
+| ---------- | -------------- | ----------------------------------------------------------------- |
+| ...classes | [`CSSClasses`] | A mixed array containing multiple ways of specifying CSS classes. |
+
+## combineClasses
+
+**Kind**: global constant  
+**Returns**: [`CSSStringOrObject`] - A CSS object or a space-separated list of CSS classes.
+
+| Param      | Type                   | Description                                                                                                   |
+| ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
+| ...classes | [`CSSClassesWithRefs`] | Handles as arguments the multiple ways of specifying CSS class related values, including refs to such values. |
+
+## stringifyClass
+
+**Kind**: global constant  
+**Returns**: `CSSString` - A space-separated list of CSS classes.
+
+| Param | Type           | Description                                                       |
+| ----- | -------------- | ----------------------------------------------------------------- |
+| cls   | [`CSSClasses`] | A mixed array containing multiple ways of specifying CSS classes. |
+
+## stringifyClasses
+
+**Kind**: global constant  
+**Returns**: `CSSString` - A space-separated list of CSS classes.
+
+| Param      | Type           | Description                                                                    |
+| ---------- | -------------- | ------------------------------------------------------------------------------ |
+| ...classes | [`CSSClasses`] | Handles as arguments the multiple ways of specifying CSS class related values. |
+
+## useCombineClasses(classes)
+
+**Kind**: global function  
+**Returns**: `Ref.<CSSStringOrObject>` - A Vue ref pointing to the amalgamated CSS string or object.
+
+| Param   | Type           | Description                                                                                  |
+| ------- | -------------- | -------------------------------------------------------------------------------------------- |
+| classes | [`CSSClasses`] | A mixed array containing multiple ways of specifying CSS classes. Non-ref values are cloned. |
+
+## CSSValue
+
+A string representing a CSS class or a space-separated list of CSS classes.
+
+**Kind**: global typedef
+
+## CSSObject
+
+A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class.
+
+**Kind**: global typedef
+
+## CSSClasses
+
+A mixed array containing multiple ways of specifying CSS classes.
+
+**Kind**: global typedef
+
+## CSSStringOrObject
+
+The amalgamated classes as returned by `objectifyClasses` & `combineClasses`.
+
+**Kind**: global typedef
+
+## CSSValue
+
+A string representing a CSS class or a space-separated list of CSS classes.
+
+**Kind**: global typedef
+
+## CSSObject
+
+A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class.
+
+**Kind**: global typedef
+
+## CSSClasses
+
+A mixed array containing multiple ways of specifying CSS classes.
+
+**Kind**: global typedef
+
+## CSSClassesWithRefs
+
+A mixed array containing multiple ways of specifying CSS classes.
+
+**Kind**: global typedef
+
+## CSSStringOrObject
+
+A CSS object or a space-separated list of CSS classes.
+
+**Kind**: global typedef
+
 <!-- LINKS -->
 
 [utils/assignreactiveobject]: #utilsassignreactiveobject
@@ -328,6 +456,15 @@ const transformed = transformWalk(obj, (key, value, path) => {
 [utils/keydiff]: #utilskeydiff
 [utils/lifecycledebug]: #utilslifecycledebug
 [utils/transformwalk]: #utilstransformwalk
+[objectifyclasses]: #objectifyclasses
+[combineclasses]: #combineclasses
+[stringifyclass]: #stringifyclass
+[stringifyclasses]: #stringifyclasses
+[cssvalue]: #cssvalue
+[cssobject]: #cssobject
+[cssclasses]: #cssclasses
+[cssstringorobject]: #cssstringorobject
+[cssclasseswithrefs]: #cssclasseswithrefs
 [~validtargetorsource]: #utilsassignreactiveobjectvalidtargetorsource
 [`utils/assignreactiveobject`]: #utilsassignreactiveobject
 [~debugmessagefunction]: #utilsdebugmessagedebugmessagefunction
@@ -338,6 +475,11 @@ const transformed = transformWalk(obj, (key, value, path) => {
 [`utils/keydiff`]: #utilskeydiff
 [`utils/lifecycledebug`]: #utilslifecycledebug
 [`utils/transformwalk`]: #utilstransformwalk
+[1]: #cssstringorobject
+[`cssclasses`]: #cssclasses
+[`cssstringorobject`]: #cssstringorobject
+[`cssclasseswithrefs`]: #cssclasseswithrefs
+[usecombineclasses(classes)]: #usecombineclassesclasses
 [~addreactiveobject(target, source, \[exclude\], \[addedkeys\])]: #utilsassignreactiveobjectaddreactiveobjecttarget-source-exclude-addedkeys
 [~updatereactiveobject(target, source, \[exclude\], \[samekeys\])]: #utilsassignreactiveobjectupdatereactiveobjecttarget-source-exclude-samekeys
 [~addorupdatereactiveobject(target, source, \[exclude\], \[addedkeys\], \[samekeys\])]: #utilsassignreactiveobjectaddorupdatereactiveobjecttarget-source-exclude-addedkeys-samekeys

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "8.1.0",
+    "version": "8.1.1",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",

package/use/combineClasses.js

@@ -1,16 +1,58 @@
 import { combineClasses } from "../utils/classes";
-import { isReactive, isRef, ref, watch } from "vue";
+import { cloneDeep } from "lodash-es";
+import { isRef, ref, watch, isReactive } from "vue";
 
+/**
+ * @typedef {*} Ref A Vue ref
+ * @private
+ */
+
+/**
+ * @typedef {string} CSSString A string representing a CSS class or a space-separated list of CSS classes.
+ * @typedef {CSSString|CSSString[]} CSSClassNames An array of CSS string(s) or a single CSS string.
+ * @typedef {boolean|Ref<boolean>} CSSValue A truthy value or a reference to a truthy value, indicating whether to apply a CSS class, or unapply it if already applied.
+ */
+/* eslint-disable jsdoc/check-types */
+// types valid for jsdoc-to-markdown, which uses the strict jsdoc.app. Object shorthand syntax doesn't work.
+/**
+ * @typedef {Object.<CSSString, CSSValue>} CSSObject A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class.
+ */
+/* eslint-enable jsdoc/check-types */
+/**
+ * A mixed array containing multiple ways of specifying CSS classes.
+ * @typedef {Array<
+ *   CSSClassNames,
+ *   CSSString[],
+ *   CSSString,
+ *   CSSObject,
+ *   Ref<CSSClassNames>,
+ *   Ref<CSSString[]>,
+ *   Ref<CSSString>,
+ *   Ref<CSSClassNames>
+ * >} CSSClasses
+ */
+/**
+ * @typedef {CSSString|CSSObject} CSSStringOrObject The amalgamated classes as returned by `objectifyClasses` & `combineClasses`.
+ */
+
+const isRefOrReactive = (v) => isRef(v) || isReactive(v);
+
+/**
+ * @param {CSSClasses} classes A mixed array containing multiple ways of specifying CSS classes. Non-ref values are cloned.
+ * @returns {Ref<CSSStringOrObject>} A Vue ref pointing to the amalgamated CSS string or object.
+ */
 export function useCombineClasses(...classes) {
     const classesComputed = ref();
-    const reactiveValues = classes.filter((c) => isRef(c) && isReactive(c));
+    const reactiveValues = classes.filter((c) => isRefOrReactive(c));
+    // cloneDeep any non-reactive values, but maintain order
+    const myClasses = classes.map((c) => (isRefOrReactive(c) ? c : cloneDeep(c)));
     if (!reactiveValues.length) {
-        classesComputed.value = combineClasses(...classes);
+        classesComputed.value = combineClasses(...myClasses);
     } else {
         watch(
             reactiveValues,
             () => {
-                classesComputed.value = combineClasses(...classes);
+                classesComputed.value = combineClasses(...myClasses);
             },
             {
                 immediate: true,

package/utils/classes.js

@@ -6,6 +6,46 @@ import isSet from "lodash-es/isSet";
 import isString from "lodash-es/isString";
 import { isRef, unref } from "vue";
 
+/**
+ * @typedef {*} Ref A Vue ref
+ * @private
+ */
+
+/**
+ * @typedef {string} CSSString A string representing a CSS class or a space-separated list of CSS classes.
+ * @typedef {CSSString|CSSString[]} CSSClassNames An array of CSS string(s) or a single CSS string.
+ * @typedef {boolean|Ref<boolean>} CSSValue A truthy value or a reference to a truthy value, indicating whether to apply a CSS class, or unapply it if already applied.
+ */
+/* eslint-disable jsdoc/check-types */
+// types valid for jsdoc-to-markdown, which uses the strict jsdoc.app. Object shorthand syntax doesn't work.
+/**
+ * @typedef {Object.<CSSString, CSSValue>} CSSObject A CSS object where keys are CSS classes and values are booleans indicating whether to apply the class.
+ */
+/* eslint-enable jsdoc/check-types */
+/**
+ * @typedef {Array<CSSClassNames, CSSString[], CSSString, CSSObject>} CSSClasses A mixed array containing multiple ways of specifying CSS classes.
+ */
+/**
+ * A mixed array containing multiple ways of specifying CSS classes.
+ * @typedef {Array<
+ *   CSSClassNames,
+ *   CSSString[],
+ *   CSSString,
+ *   CSSObject,
+ *   Ref<CSSClassNames>,
+ *   Ref<CSSString[]>,
+ *   Ref<CSSString>,
+ *   Ref<CSSClassNames>
+ * >} CSSClassesWithRefs
+ */
+/**
+ * @typedef {CSSString|CSSObject} CSSStringOrObject A CSS object or a space-separated list of CSS classes.
+ */
+
+/**
+ * @param {...CSSClasses} classes A mixed array containing multiple ways of specifying CSS classes.
+ * @returns {CSSStringOrObject} A CSS object or a space-separated list of CSS classes.
+ */
 export const objectifyClasses = (...classes) => {
     const flatClasses = classes.flat(Infinity).filter(identity);
     const objects = flatClasses.map((c) => {
@@ -71,6 +111,11 @@ const deepUnrefArrays = (val) => {
     return checkedVal;
 };
 
+/**
+ * @param {...CSSClassesWithRefs} classes Handles as arguments the multiple ways of specifying CSS class related
+ *  values, including refs to such values.
+ * @returns {CSSStringOrObject} A CSS object or a space-separated list of CSS classes.
+ */
 export const combineClasses = (...classes) => {
     // we unref your refs, so probably want a computed around this
     // ultimately, strings and objects are classes, arrays are organization and containers
@@ -88,6 +133,10 @@ export const combineClasses = (...classes) => {
     return isEmpty(result) ? undefined : result;
 };
 
+/**
+ * @param {CSSClasses} cls A mixed array containing multiple ways of specifying CSS classes.
+ * @returns {CSSString} A space-separated list of CSS classes.
+ */
 export const stringifyClass = (cls) => {
     if (isArray(cls)) {
         return stringifyClasses(...cls);
@@ -100,6 +149,10 @@ export const stringifyClass = (cls) => {
     }
 };
 
+/**
+ * @param {...CSSClasses} classes Handles as arguments the multiple ways of specifying CSS class related values.
+ * @returns {CSSString} A space-separated list of CSS classes.
+ */
 export const stringifyClasses = (...classes) =>
     classes
         .map(stringifyClass)