simple-merge-class-names 3.0.4 → 4.0.1

package/README.md

@@ -8,14 +8,16 @@ A straightforward utility for merging CSS class names in `React + Tailwind` and
     -   [Install Prettier With VSCode (Most Recommended)](#install-prettier-with-vscode-most-recommended)
 -   [Usage](#usage)
 
+    -   [Conditionally Include Class Names](#conditionally-include-class-names)
+
     -   [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)
 
+    -   [Breaking Changes From Version 1.X.X](#breaking-changes-from-version-1xx)
+
 -   [Testing](#testing)
 -   [Source Code (Partial)](#source-code-partial)
 -   [Misc.](#misc)
@@ -58,7 +60,7 @@ function MyComponent() {
         <div
             className={mergeClassNames(
                 "app",
-                "min-h-dvh",
+                condition ? "min-h-dvh" : false,
                 "grid",
                 "grid-rows-[auto_1fr_auto]",
                 "outline"
@@ -82,6 +84,22 @@ function MyComponent() {
 }
 ```
 
+### Conditionally Include Class Names
+
+To conditionally include a class, use the ternary operator like this: `condition ? 'class-name' : false` to maintain clear and warning-free code.
+
+```jsx
+mergeClassNames(
+    "app",
+    condition ? "min-h-dvh" : false,
+    "grid",
+    "grid-rows-[auto_1fr_auto]",
+    "outline"
+);
+```
+
+**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.
+
 ### 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)
@@ -101,11 +119,13 @@ function MyComponent() {
 
 ## Argument Handling
 
-`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.
+`mergeClassNames(...args)` accepts only the following arguments:
 
-### Breaking Changes From Version 1.X.X
+-   **Non-empty strings** (for example: `"app"`, `"min-h-dvh"`)
 
-In pervious versions, arguments that were not strings were implicitly converted to strings by the JavaScript engine.
+-   The boolean value **`false`**
+
+Everything else like empty strings (`""`), `null`, `undefined`, numbers, objects and arrays is _ignored_ and logged via `console.warn` to alert the user of a potentially deeper issue.
 
 ### Console Warning for Invalid Arguments
 
@@ -119,6 +139,10 @@ Example output:
     - Expected 0 empty strings, but got 2.
 ```
 
+### Breaking Changes From Version 1.X.X
+
+In pervious versions, arguments that were not strings were implicitly converted to strings by the JavaScript engine.
+
 ## Testing
 
 This project uses `Vitest` as the test runner for fast, modern testing.

package/mergeClassNames.d.ts

@@ -1 +1 @@
-export declare const mergeClassNames: (...args: string[]) => string;
+export declare const mergeClassNames: (...args: (string | boolean)[]) => string;

package/mergeClassNames.js

@@ -37,6 +37,8 @@
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 
+const isValueFalse = (val) => val === false;
+
 const isTypeString = (val) => typeof val === "string";
 
 const isNonEmptyString = (val) => val !== "";
@@ -53,7 +55,9 @@ const partition = (array, keepPredicate) => {
 export const mergeClassNames = (...args) => {
     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 trimmed = strings.map((val) => val.trim());
 
@@ -67,16 +71,22 @@ export const mergeClassNames = (...args) => {
     /* Don't silently ignore invalid input, explicitly disclose them as it may indicate a bigger problem */
     const warn = [];
 
-    /* "Expected all arguments to be strings ..." */
+    /* "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 = nonStrings.map(formatGotArray).join(join);
+        const message = (
+            count > maxPrint ? nonStrings.slice(0, maxPrint) : nonStrings
+        )
+            .map(formatGotArray)
+            .join(join);
+        const suffix = count > maxPrint ? ", ... ]" : "]";
 
         warn.push(
-            `Expected all arguments to be strings, but got ${count} non-string values: [${message}].`
+            `Expected all arguments to be either strings or value "false", but got ${count} invalid values: [${message}${suffix}.`
         );
     }
 

package/package.json

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