simple-merge-class-names 4.0.0 → 5.0.0

package/README.md

@@ -1,31 +1,32 @@
 # simple-merge-class-names
 
-A straightforward utility for merging CSS class names in `React + Tailwind` and other JavaScript projects.
+A straightforward utility for merging CSS class names in `React + Tailwind` and other _JavaScript_ projects.
 
 ## Table of Contents
 
+-   [Production Considerations](#production-considerations)
 -   [Installation](#installation)
     -   [Install Prettier With VSCode (Most Recommended)](#install-prettier-with-vscode-most-recommended)
 -   [Usage](#usage)
-
-    -   [Workflow To Minimize Typing Strain](#workflow-to-minimize-typing-strain)
-
--   [Argument Handling](#argument-handling)
-
-    -   [Breaking Changes From Version 1.X.X](#breaking-changes-from-version-1xx)
-
-    -   [Console Warning for Invalid Arguments](#console-warning-for-invalid-arguments)
-
+-   [Workflow To Minimize Typing Strain](#workflow-to-minimize-typing-strain)
+-   [Type Definitions (of Exported Functions)](#type-definitions-of-exported-functions)
+-   [Accepted Arguments](#accepted-arguments)
+-   [Console Warning](#console-warning)
+-   [Conditionally Include Class Names](#conditionally-include-class-names)
+-   [Using `mergeClassNamesDebugger` And The Built-in Browser Debugger To Find And Fix Warnings](#using-mergeclassnamesdebugger-and-the-built-in-browser-debugger-to-find-and-fix-warnings)
+-   [Strategies To Ensure Correct Arguments Are Sent to `mergeClassNames`](#strategies-to-ensure-correct-arguments-are-sent-to-mergeclassnames)
 -   [Testing](#testing)
 -   [Source Code (Partial)](#source-code-partial)
 -   [Misc.](#misc)
-
+    -   [Motivation](#motivation)
     -   [Why the Mismatch Between Exported Function and Package Name?](#why-the-mismatch-between-exported-function-and-package-name)
     -   [Where This Package Excels](#where-this-package-excels)
-
--   [Production Considerations](#production-considerations)
 -   [License](#license)
 
+## Production Considerations
+
+When developing this package I prioritized _code readability_, _strict input handling_, and _improved developer experience_, as such **_performance_** and **_features_** were not the guiding factor. Therefore if you are considering this package for production, you might also want to look into `clsx`: [https://www.npmjs.com/package/clsx](https://www.npmjs.com/package/clsx)
+
 ## Installation
 
 ```bash
@@ -42,23 +43,23 @@ npm install simple-merge-class-names
 
 ### Install `Prettier` With VSCode (Most Recommended)
 
-[https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+-   [https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
 
-Or install an equivalent auto code formatter for your IDE.
+-   Or use an equivalent auto code formatter for your IDE.
 
 ## Usage
 
-Import `mergeClassNames(...args)` from the package, and use it in your JSX or JavaScript code.
+Import `mergeClassNames(...args)` from the package, and use it in your _JSX_ or _JavaScript_ code.
 
 ```jsx
 import { mergeClassNames } from "simple-merge-class-names";
 
-function MyComponent() {
+const MyComponent = () => {
     return (
         <div
             className={mergeClassNames(
                 "app",
-                "min-h-dvh",
+                condition ? "min-h-dvh" : false,
                 "grid",
                 "grid-rows-[auto_1fr_auto]",
                 "outline"
@@ -67,24 +68,35 @@ function MyComponent() {
             Hello, world!
         </div>
     );
-}
+};
 ```
 
-While using separate strings for each class name can be tedious, see [Workflow To Minimize Typing Strain](#workflow-to-minimize-typing-strain), it significantly enhances code readability and Developer Experience (DX). This is in contrast to hard-to-read strings like:
+Or for debugging purposes to fix [console warnings](#console-warning):
+
+-   Open the _Browser's Developer Tools_ and
+-   Use `mergeClassNamesDebugger`
 
 ```jsx
-function MyComponent() {
+import { mergeClassNamesDebugger } from "simple-merge-class-names";
+
+const MyComponent = () => {
     return (
-        <div className="app min-h-dvh grid grid-rows-[auto_1fr_auto] outline">
+        <div
+            className={mergeClassNamesDebugger(
+                "app",
+                condition ? "min-h-dvh" : false,
+                "grid",
+                "grid-rows-[auto_1fr_auto]",
+                "outline"
+            )}
+        >
             Hello, world!
         </div>
     );
-}
+};
 ```
 
-### Workflow To Minimize Typing Strain
-
-![Screen recording of optimal DX in action: using this package with Prettier as it neatly arranges each class name on a new line](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/Reduce%20typing%20strain.gif)
+## Workflow To Minimize Typing Strain
 
 -   Have `Prettier` installed
 -   Have `Editor: Word Wrap` enabled in VS Code:
@@ -94,38 +106,192 @@ function MyComponent() {
 
         `"editor.wordWrap": "on"`
 
--   Use single quotes (<kbd>'</kbd>) for class names, often a single key press on many keyboards.
--   Save the file (<kbd>Ctrl+S</kbd>), and Prettier does the formatting heavy-lifting, it automatically:
-    -   Replaces single quotes with double quotes.
-    -   Neatly arranges each class name on a new line.
+-   **Use single quotes** (<kbd>'</kbd>) for class names, often a single key press on many keyboards.
+-   **Save the file** (<kbd>Ctrl+S</kbd>), which activates `Prettier` to auto-format the file, it will:
+
+    -   Replace single quotes with double quotes.
+    -   Neatly arrange each class name on a new line.
+
+### Result
 
-## Argument Handling
+#### Before
 
-`mergeClassNames` only accepts **_non-empty string values_**, everything else like empty strings (`""`), `null`, `undefined`, numbers, objects and arrays is _ignored_. This ensures stricter and predictable output.
+![Screenshot of code before Prettier neatly formats code](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/before.png)
 
-### Breaking Changes From Version 1.X.X
+#### After
 
-In pervious versions, arguments that were not strings were implicitly converted to strings by the JavaScript engine.
+![Screenshot of code after Prettier neatly formats code](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/after.png)
 
-### Console Warning for Invalid Arguments
+## Type Definitions (of Exported Functions)
 
-Invalid arguments are not silently ignored, as they may indicate a deeper issue. A single warning is logged to the developer console whenever these arguments are passed and ignored.
+```jsx
+mergeClassNames: (...args: (string | false)[]) => string;
+```
+
+```jsx
+mergeClassNamesDebugger: (...args: (string | false)[]) => string;
+```
+
+```jsx
+isEmptyString: (argument: string) => boolean;
+```
 
-Example output:
+For both `mergeClassNames` and `mergeClassNamesDebugger` they always return a string.
+
+-   If no inputs were provided e.g. `mergeClassNames()` or were invalid `mergeClassNames(undefined, " ")` then an _empty string_ is returned `""`
+
+## Accepted Arguments
+
+`mergeClassNames(...args)` and `mergeClassNamesDebugger(...args)` only accept the following arguments:
+
+-   **Strings that are not empty, and are not whitespace** (for example: `"app"`, `"min-h-dvh"`, `"   grid   "`)
+
+-   The boolean value **`false`**
+
+Everything else is an _invalid argument_ that will be _ignored_, and cause a _warning_ to be logged, these argument types include:
+
+-   _empty strings_ (`""`),
+-   _whitespace combinations_ (e.g. `"\n"`, `"  \n\t "`, etc...),
+-   `null`,
+-   `undefined`,
+-   _numbers_,
+-   _objects_,
+-   _arrays_
+
+## Console Warning
+
+Whenever invalid arguments are passed to `mergeClassNames` they are _not silently ignored_ because this can cause a lot of subtle bugs in the future and compound technical debt. Therefore a `console.warn` is printed in the _Developer Console_ to alert of the potentially deeper issue that requires rectifying. Example:
 
 ```plaintext
-[mergeClassNames] Warning: invalid arguments were provided and were ignored:
-    - Expected all arguments to be strings, but got 4 non-string values: [(1/4): (undefined) of type "undefined", (2/4): (test) of type "object", (3/4): ([object Object]) of type "object", (4/4): (null) of type "object"].
-    - Expected 0 empty strings, but got 2.
+[mergeClassNames] Warning: invalid arguments were provided and ignored:
+
+        * Replace "mergeClassNames" with "mergeClassNamesDebugger" without changing any arguments, and open the Developer Console, or attach Debugger (see README.md).
+
+        * Expected all arguments to be either strings or value `false`, but got 5 invalid value(s):
+        [
+        (1/5): >undefined< of type "undefined",
+        (2/5): > test < of type "object",
+        (3/5): >[object Object]< of type "object",
+        (4/5): >true< of type "boolean",
+        (5/5): >null< of type "object"
+        ]
+
+        * Expected 0 empty strings, but got 2 invalid value(s):
+        [
+        (1/2): ><,
+        (2/2): >   <
+        ]
+```
+
+## Conditionally Include Class Names
+
+To conditionally include a class name, use the
+
+-   _Conditional operator_ `condition ? "class-name" : false` with `false` as the fallback value to maintain a clear and warning-free code.
+
+This is because `false` will never cause the function to print a warning.
+
+**Important**: Avoid using the
+
+-   _Short-circuit implicit syntax_ `condition && "class-name"` because it can produce falsy values like `0`, `""`, `undefined`, `null`, which will cause warnings to be logged.
+
+```jsx
+import { mergeClassNames } from "simple-merge-class-names";
+
+const MyComponent = () => {
+    return (
+        <div
+            className={mergeClassNames(
+                "app",
+                condition ? "min-h-dvh" : false,
+                "grid",
+                "grid-rows-[auto_1fr_auto]",
+                "outline"
+            )}
+        >
+            Hello, world!
+        </div>
+    );
+};
+```
+
+## Using `mergeClassNamesDebugger` And The Built-in Browser Debugger To Find And Fix Warnings
+
+`mergeClassNamesDebugger` is a drop-in replacement for `mergeClassNames` but with the added _benefit_ that it will activate the built-in **_debugger_** inside browsers like _FireFox_, _Chrome_, _Safari_ and even _VS Code_ if configured properly.
+
+This built-in JavaScript feature gained wide-spread support from major browsers around 2012, so you are getting this feature for free with minimal effort, all you have to do are 2 things:
+
+1.  Simply **_Open the Browser's Developer Tools_**, this tells the JavaScript engine that the Debugger is _enabled_.
+2.  **_Replace_** `mergeClassNames` with **`mergeClassNamesDebugger`** _without_ changing any of the argument provided.
+
+_When the Debugger is enabled (i.e. *Browser's Developer Tools* is open) and an invalid argument like `undefined` or `" "` is passed to `mergeClassNamesDebugger`, then the JavaScript engine will automatically pause execution and highlight the invalid argument. You simply have to select the offending component (`Container.jsx` in this case) from the Call Stack._
+
+When the Debugger is active, it should look like this screenshot (in _FireFox_):
+
+![Firefox Debugger automatically paused execution when undefined was passed to mergeClassNamesDebugger](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/debugger.png)
+
+## Strategies To Ensure Correct Arguments Are Sent to `mergeClassNames`
+
+-   Use the _conditional operator_ to conditionally including class names:
+
+```jsx
+import { mergeClassNames } from "simple-merge-class-names";
+
+const MyComponent = () => {
+    return (
+        <div
+            className={mergeClassNames(
+                "app",
+                condition ? "min-h-dvh" : false,
+                "grid",
+                "grid-rows-[auto_1fr_auto]",
+                "outline"
+            )}
+        >
+            Hello, world!
+        </div>
+    );
+};
+```
+
+-   If chaining the result of another `mergeClassNames` then use `isEmptyString` to check if the result is not the _empty string_ (`""`):
+
+```jsx
+import { mergeClassNames, isEmptyString } from "simple-merge-class-names";
+
+const MyComponent = ({ condition, resultOfAnotherMergeClassNames }) => {
+    return (
+        <div
+            className={mergeClassNames(
+                "app",
+
+                condition ? "min-h-dvh" : false,
+
+                isEmptyString(resultOfAnotherMergeClassNames)
+                    ? false
+                    : resultOfAnotherMergeClassNames,
+
+                "grid",
+                "grid-rows-[auto_1fr_auto]",
+                "outline"
+            )}
+        >
+            Hello, world!
+        </div>
+    );
+};
 ```
 
 ## Testing
 
-This project uses `Vitest` as the test runner for fast, modern testing.
+This project uses `Vitest` as the test runner for fast and modern testing.
 
-#### Run All Testing Once
+#### Run All Tests Once
 
 ```bash
+git clone https://github.com/new-AF/simple-merge-class-names
+cd simple-merge-class-names
+pnpm install
 pnpm test
 ```
 
@@ -140,56 +306,58 @@ pnpm test:watch
 ```javascript
 /**
  * mergeClassNames - A straightforward utility for merging CSS class names in React + Tailwind, and other JavaScript projects.
- ...
+ *
+ * @license AGPL-3.0
+ * Copyright (C) 2025 Abdullah Fatota
+ *
+ * ...
  */
 
-const isTypeString = (val) => typeof val === "string";
-
-const isNonEmptyString = (val) => val !== "";
-
-const partition = (array, keepPredicate) => {
-    const keep = [];
-    const ignore = [];
-    for (const element of array) {
-        (keepPredicate(element) ? keep : ignore).push(element);
-    }
-    return [keep, ignore];
-};
-
-export const mergeClassNames = (...args) => {
+const mergeClassNamesCore = ({ args, activateDebugger }) => {
     const space = "\x20"; // ASCII code for a single space character (" "), decimal 32
 
-    const [strings, nonStrings] = partition(args, isTypeString);
+    const [_, nonFalseValues] = partition(args, isValueFalse); // ignore all false values used for conditional class inclusion
+    const [strings, nonStrings] = partition(nonFalseValues, isTypeString);
+    const [emptyStrings, nonEmptyStrings] = partition(strings, isEmptyString);
+    const trimmed = nonEmptyStrings.map((val) => val.trim());
+    const className = trimmed.join(space);
 
-    const trimmed = strings.map((val) => val.trim());
+    /* Don't silently ignore invalid input, explicitly disclose them as it may indicate a bigger problem */
+    warnInvalidArguments({ nonStrings, emptyStrings, activateDebugger });
 
-    const [nonEmptyStrings, emptyStrings] = partition(
-        trimmed,
-        isNonEmptyString
-    );
+    return className;
+};
 
-    const className = nonEmptyStrings.join(space);
+export const mergeClassNames = (...args) =>
+    mergeClassNamesCore({ args, activateDebugger: false });
 
-    /* Don't silently ignore invalid input, explicitly disclose them as it may indicate a bigger problem */
-    const warn = [];
-    /* ... */
+export const mergeClassNamesDebugger = (...args) =>
+    mergeClassNamesCore({ args, activateDebugger: true });
 ```
 
 ## Misc.
 
-### Why the Mismatch Between Exported Function and Package Name?
+### Motivation
 
-I wanted to name the package as `mergeClassNames` to reflect the single exported function, but the NPM Package Registry does not allow capital letters, only lower case and dash characters.
+This package aims to improve code readability and developer experience in `React & Tailwind` projects by enforcing strict input handling. It logs warnings for invalid arguments, helping developers catch and fix underlying issues _early_.
 
-In addition there was already a package named `merge-class-names` but it is no longer maintained (and the developer recommends `clsx` instead).
+In addition while writing class names as separate strings may seem tedious, the [workflow](#workflow-to-minimize-typing-strain) reduces friction and the overall process results in more readable and maintainable code than using single long strings:
 
-### Where This Package Excels
+```jsx
+const MyComponent = () => {
+    return (
+        <div className="app min-h-dvh grid grid-rows-[auto_1fr_auto] outline">
+            Hello, world!
+        </div>
+    );
+};
+```
 
-While similar packages exist (`clsx`) with better features and potentially improved performance, `simple-merge-class-names` focuses on being very straightforward and easy to reason about, as defined in its source code.
+### Why the Mismatch Between Exported Function and Package Name?
 
-## Production Considerations
+I wanted to name the package `mergeClassNames` to reflect the exported function, but the NPM Package Registry doesn't allow capital letters, only lower case and dash characters.
 
-If you are considering this package for production, you might also want to look into `clsx`: [https://www.npmjs.com/package/clsx](https://www.npmjs.com/package/clsx)
+In addition there was already a package named `merge-class-names` but it is no longer maintained (and the developer recommends `clsx` instead).
 
 ## License
 

package/mergeClassNames.d.ts

@@ -1 +1,5 @@
-export declare const mergeClassNames: (...args: (string | boolean)[]) => string;
+export declare const mergeClassNames: (...args: (string | false)[]) => string;
+export declare const mergeClassNamesDebugger: (
+    ...args: (string | false)[]
+) => string;
+export declare const isEmptyString: (argument: string) => boolean;

package/mergeClassNames.js

@@ -41,7 +41,10 @@ const isValueFalse = (val) => val === false;
 
 const isTypeString = (val) => typeof val === "string";
 
-const isNonEmptyString = (val) => val !== "";
+export const isEmptyString = (val) => {
+    const trimmed = val.trim();
+    return trimmed === "";
+};
 
 const partition = (array, keepPredicate) => {
     const keep = [];
@@ -52,62 +55,135 @@ const partition = (array, keepPredicate) => {
     return [keep, ignore];
 };
 
-export const mergeClassNames = (...args) => {
-    const space = "\x20"; // ASCII code for a single space character (" "), decimal 32
-
-    const [_, nonFalseValues] = partition(args, isValueFalse); // ignore all false values used for conditional class inclusion
-
-    const [strings, nonStrings] = partition(nonFalseValues, isTypeString);
-
-    const trimmed = strings.map((val) => val.trim());
-
-    const [nonEmptyStrings, emptyStrings] = partition(
-        trimmed,
-        isNonEmptyString
-    );
-
-    const className = nonEmptyStrings.join(space);
+const warnInvalidArguments = ({
+    nonStrings,
+    emptyStrings,
+    activateDebugger = false,
+}) => {
+    const hasInvalidTypes = nonStrings.length > 0;
+    const hasEmptyStrings = emptyStrings.length > 0;
+    const doPrint = hasInvalidTypes || hasEmptyStrings;
+
+    if (doPrint === false) return;
+
+    const messages = [];
+    const newline = "\n";
+    const doubleNewline = newline.repeat(2);
+
+    const tabString = (string, tabCount = 0) => {
+        const tab = "\t".repeat(tabCount);
+        return `${tab}${string}`;
+    };
+
+    const tabArray = (array, tabCount) =>
+        array.map((element) => tabString(element, tabCount));
+
+    /* convert array to nice string because console.warn(array) squashes it on 1 line */
+    const makeMessage = ({
+        array,
+        expected,
+        tabCount = 1,
+        includeElementType = false,
+        arrayMaxLength = 5,
+    }) => {
+        const count = array.length;
+        const addEllipsis = count > arrayMaxLength;
+        const slice = addEllipsis ? array.slice(0, arrayMaxLength) : array;
+
+        const formatElementWithType = (element, index) =>
+            `(${index + 1}/${count}): >${element}< of type "${typeof element}"`;
+
+        const formatElement = (element, index) =>
+            `(${index + 1}/${count}): >${element}<`;
+
+        const initialMapped = slice.map(
+            includeElementType ? formatElementWithType : formatElement
+        );
 
-    /* Don't silently ignore invalid input, explicitly disclose them as it may indicate a bigger problem */
-    const warn = [];
+        const mapped = addEllipsis ? [...initialMapped, "..."] : initialMapped;
+
+        const string = [
+            tabString(
+                `${expected}, but got ${count} invalid value(s):`,
+                tabCount
+            ),
+            tabString("[", tabCount),
+            tabArray(mapped, tabCount).join("," + newline),
+            tabString("]", tabCount),
+        ].join(newline);
+
+        return string;
+    };
+
+    /* "Replace "mergeClassNames" with "mergeClassNamesDebugger" ... " */
+    if (doPrint && activateDebugger === false) {
+        messages.push(
+            tabString(
+                '* Replace "mergeClassNames" with "mergeClassNamesDebugger" without changing any arguments, and open the Developer Console, or attach Debugger (see README.md).',
+                1
+            )
+        );
+    }
 
     /* "Expected all arguments to be either ..." */
-    if (nonStrings.length > 0) {
-        const join = ", ";
-        const count = nonStrings.length;
-        const maxPrint = 10;
-        const formatGotArray = (element, index) =>
-            `(${index + 1}/${count}): (${element}) of type "${typeof element}"`;
-        const message = (
-            count > maxPrint ? nonStrings.slice(0, maxPrint) : nonStrings
-        )
-            .map(formatGotArray)
-            .join(join);
-        const suffix = count > maxPrint ? ", ... ]" : "]";
-
-        warn.push(
-            `Expected all arguments to be either strings or value "false", but got ${count} invalid values: [${message}${suffix}.`
+    if (hasInvalidTypes) {
+        if (activateDebugger) {
+            debugger;
+        }
+        messages.push(
+            makeMessage({
+                array: nonStrings,
+                expected:
+                    "* Expected all arguments to be either strings or value `false`",
+                includeElementType: true,
+            })
         );
     }
 
     /* "Expected 0 empty strings ..." */
-    if (emptyStrings.length > 0) {
-        const count = emptyStrings.length;
-        warn.push(`Expected 0 empty strings, but got ${count}.`);
+    if (hasEmptyStrings) {
+        if (activateDebugger) {
+            debugger;
+        }
+        messages.push(
+            makeMessage({
+                array: emptyStrings,
+                expected: "* Expected 0 empty strings",
+            })
+        );
     }
 
-    /* Full Warn Message */
-    if (warn.length > 0) {
-        const newline = "\n";
-        const prefix = "\t" + "- ";
-        const message = warn.map((text) => `${prefix}${text}`).join(newline);
+    /* Full Warn makeMessage */
+    const functionName =
+        activateDebugger === false
+            ? "mergeClassNames"
+            : "mergeClassNamesDebugger";
 
-        console.warn(
-            "[mergeClassNames] Warning: invalid arguments were provided and were ignored:",
-            newline,
-            message
-        );
-    }
+    const string = [
+        `[${functionName}] Warning: invalid arguments were provided and ignored:`,
+        ...messages,
+    ].join(doubleNewline);
+
+    console.warn(string);
+};
+
+const mergeClassNamesCore = ({ args, activateDebugger }) => {
+    const space = "\x20"; // ASCII code for a single space character (" "), decimal 32
+
+    const [_, nonFalseValues] = partition(args, isValueFalse); // ignore all false values used for conditional class inclusion
+    const [strings, nonStrings] = partition(nonFalseValues, isTypeString);
+    const [emptyStrings, nonEmptyStrings] = partition(strings, isEmptyString);
+    const trimmed = nonEmptyStrings.map((val) => val.trim());
+    const className = trimmed.join(space);
+
+    /* Don't silently ignore invalid input, explicitly disclose them as it may indicate a bigger problem */
+    warnInvalidArguments({ nonStrings, emptyStrings, activateDebugger });
 
     return className;
 };
+
+export const mergeClassNames = (...args) =>
+    mergeClassNamesCore({ args, activateDebugger: false });
+
+export const mergeClassNamesDebugger = (...args) =>
+    mergeClassNamesCore({ args, activateDebugger: true });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "simple-merge-class-names",
-    "version": "4.0.0",
+    "version": "5.0.0",
     "description": "A straightforward utility for merging CSS class names in React + Tailwind and JavaScript projects.",
     "exports": {
         ".": {