simple-merge-class-names 7.0.3 → 8.1.0

package/README.md

@@ -1,75 +1,84 @@
 # simple-merge-class-names
 
-A straightforward utility for merging CSS class names in _React (JSX)_ and other _JavaScript_ projects.
+A class names merger for TypeScript, JavaScript, TSX / JSX (React).
 
-For Production look into [https://www.npmjs.com/package/clsx](https://www.npmjs.com/package/clsx)
+> For production purposes there is also [https://www.npmjs.com/package/clsx](https://www.npmjs.com/package/clsx)
 
 ## Table of Contents
 
--   [simple-merge-class-names](#simple-merge-class-names)
-    -   [Table of Contents](#table-of-contents)
-    -   [The Genocidal Occupation Is Starving Gaza](#the-genocidal-occupation-is-starving-gaza)
-    -   [Installation](#installation)
-        -   [_Recommended If Using VSCode: Install `Prettier` Extension_](#recommended-if-using-vscode-install-prettier-extension)
-    -   [Usage](#usage)
-        -   [TypeScript Definitions](#typescript-definitions)
-        -   [Valid Arguments](#valid-arguments)
-        -   [Invalid Arguments](#invalid-arguments)
-        -   [Reason for warnings](#reason-for-warnings)
-        -   [Conditional class inclusion](#conditional-class-inclusion)
-        -   [Return Result](#return-result)
-        -   [Chaining](#chaining)
-    -   [Usage of Browser Debugger](#usage-of-browser-debugger)
-    -   [VSCode Workflow To Minimize Typing Strain](#vscode-workflow-to-minimize-typing-strain)
-    -   [Testing Source Code](#testing-source-code)
-        -   [Run Once](#run-once)
-        -   [Run Watch Mode](#run-watch-mode)
-    -   [License](#license)
-
-## The Genocidal Occupation Is Starving Gaza
-
--   [Donate](https://gazafunds.com/)
-
--   [(US) Demand Immediate Opening of ALL Gaza Border Crossings](https://act.uscpr.org/a/letaidin)
-
--   [Boycott Brands Supporting Gaza Holocaust](https://www.uplift.ie/bds/)
-
--   [Legal Action](https://www.hindrajabfoundation.org/perpetrators)
-
-_Palestine is about fundamental non-negotiable human rights. End all financial and diplomatic ties with i\*rael_.
-
-## Installation
+- [simple-merge-class-names](#simple-merge-class-names)
+    - [Table of Contents](#table-of-contents)
+    - [Stop Starving Gaza](#stop-starving-gaza)
+    - [Install](#install)
+        - [Install `Prettier` too](#install-prettier-too)
+    - [Exported Functions](#exported-functions)
+    - [Non-scale Usage](#non-scale-usage)
+        - [Example](#example)
+    - [Scale Usage](#scale-usage)
+        - [Create intermediary `@/mergeClassNames.js`](#create-intermediary-mergeclassnamesjs)
+            - [Project Structure](#project-structure)
+            - [Enable `@`-style Imports in Vite](#enable--style-imports-in-vite)
+        - [Example](#example-1)
+            - [During Dev, Debug Entire Project](#during-dev-debug-entire-project)
+    - [Valid Arguments](#valid-arguments)
+        - [Example](#example-2)
+    - [Invalid Arguments](#invalid-arguments)
+        - [Example](#example-3)
+            - [Developer Console Warnings](#developer-console-warnings)
+    - [Conditional Class Inclusion](#conditional-class-inclusion)
+        - [Avoid Short-circuit Syntax](#avoid-short-circuit-syntax)
+    - [Return Result](#return-result)
+        - [Example](#example-4)
+    - [Side Effect](#side-effect)
+        - [Example](#example-5)
+    - [Chaining](#chaining)
+    - [Usage of Browser Debugger](#usage-of-browser-debugger)
+    - [Testing Source Code](#testing-source-code)
+        - [Run Once](#run-once)
+        - [Run Watch Mode](#run-watch-mode)
+    - [License](#license)
+
+## Stop Starving Gaza
+
+- [Donate Direct Aid to Gazan Families](https://gazafunds.com/)
+
+- [Call US Congress and Demand Immediate Opening of ALL Gaza Border Crossings](https://act.uscpr.org/a/letaidin)
+
+- [Boycott Brands Supporting Gaza Holocaust](https://www.uplift.ie/bds/)
+
+- [Legal Action](https://www.hindrajabfoundation.org/perpetrators)
+
+## Install
 
 ```bash
 pnpm add simple-merge-class-names
-```
 
-```bash
+# or
 yarn add simple-merge-class-names
-```
 
-```bash
+# or
 npm install simple-merge-class-names
 ```
 
-### _Recommended If Using VSCode: Install `Prettier` Extension_
+### Install `Prettier` too
 
--   _[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)
 
-_It will nicely format your code especially when you have lots of classes, and will significantly improve your visual experience._
+It will nicely format and split your classes across new lines, and alleviate wrist strain because you will use single quotes (single key) instead of double (2 keys).
 
-_If you have a different IDE use an equivalent auto code formatter tool/extension_
+## Exported Functions
 
-## Usage
+|                           | `console.warn`s | Invokes JS `debugger;` statement on invalid arguments, which pauses execution when Debugger is attached |
+| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
+| `mergeClassNames`         | ✅              | ❌                                                                                                      |
+| `mergeClassNamesDebugger` | ✅              | ✅                                                                                                      |
 
-| Function                  | Prints console warnings | Activates debugger |
-| ------------------------- | ----------------------- | ------------------ |
-| `mergeClassNames`         | ✅                      | ❌                 |
-| `mergeClassNamesDebugger` | ✅                      | ✅                 |
+## Non-scale Usage
 
-_Example_:
+### Example
 
 ```jsx
+// src/App.jsx
 import { mergeClassNames } from "simple-merge-class-names";
 
 const Component = ({ condition }) => {
@@ -80,7 +89,7 @@ const Component = ({ condition }) => {
                 condition ? "min-h-dvh" : false,
                 "grid",
                 "grid-rows-[auto_1fr_auto]",
-                "outline"
+                "outline",
             )}
         >
             Hello, world!
@@ -89,32 +98,106 @@ const Component = ({ condition }) => {
 };
 ```
 
-### TypeScript Definitions
+## Scale Usage
+
+![diagram explanation of best way to use package](./.github/images/root-file.png)
 
-```ts
-export declare const mergeClassNames: (
-    ...args: (string | false)[]
-) => string | false;
+### Create intermediary `@/mergeClassNames.js`
 
-export declare const mergeClassNamesDebugger: (
-    ...args: (string | false)[]
-) => string | false;
+#### Project Structure
+
+```
+my-react-app/
+├─ src/
+│  ├─ components/
+│  ├─ mergeClassNames.js  // <- create it here
+│  ├─ App.jsx
+│  └─ index.js
+├─ package.json
+├─ vite.config.js
+└─ README.md
 ```
 
-### Valid Arguments
+#### Enable `@`-style Imports in Vite
 
-Only 2:
+`@` points to `my-react-app/src`
+
+```js
+// vite.config.js
+
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import path from "path";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+    plugins: [react(), tailwindcss()],
+
+    resolve: {
+        alias: {
+            "@": path.resolve(__dirname, "src"), //  @ now points to "my-react-app/src"
+        },
+    },
+});
+```
+
+```js
+// src/mergeClassNames.js
+
+export { mergeClassNames } from "simple-merge-class-names";
+
+// export { mergeClassNames as mergeClassNamesDebugger } from "simple-merge-class-names";
+```
+
+And toggle-comment between the first and second lines as needed.
+
+### Example
 
-1. **Valid strings, not whitespace, of length >= 1**
+#### During Dev, Debug Entire Project
 
-    _(As long as you have content in the string you're OK)_
+```js
+// @/mergeClassNames.js
+
+// export { mergeClassNames } from "simple-merge-class-names";
+
+export { mergeClassNames as mergeClassNamesDebugger } from "simple-merge-class-names";
+```
 
-2. **`false`**
+```jsx
+// @/App.jsx
 
-_Example, This is OK:_
+import { mergeClassNames } from "@/mergeClassNames.js";
+
+const Component = ({ condition }) => {
+    return (
+        <div
+            className={mergeClassNames(
+                "app",
+                condition ? "min-h-dvh" : false,
+                "grid",
+                "grid-rows-[auto_1fr_auto]",
+                "outline",
+            )}
+        >
+            Hello, world!
+        </div>
+    );
+};
+```
+
+## Valid Arguments
+
+Only 2:
+
+1. A valid string (not empty, not fully whitespace)
+2. Value `false`
+
+### Example
 
 ```js
 mergeClassNames(
+    condition ? "daisy-btn-active" : false
     "mx-auto",
     "min-dvh    ",
     "   flex",
@@ -123,101 +206,119 @@ mergeClassNames(
     `
         gap-y-4
     `,
-    false,
-    condition ? "daisy-btn-active" : false
 );
 ```
 
-### Invalid Arguments
+## Invalid Arguments
 
-Each below argument will be **ignored**, and cause a Dev Console **warning to be printed** to alert you:
+Anything that is not a valid argument, this includes:
 
--   **Empty strings**: _(e.g. `""`)_
--   **Whitespace** any consecutive combination of the following:
-    -   new lines,
-    -   spaces,
-    -   tabs
-    -   _(e.g._ `"   "`, `"\n "`, `"  \t  \n "`, _etc.)_
--   **`true`**
--   **`undefined`**
--   **`null`**
--   **Objects**
--   **Numbers**
--   **Big Int**
--   **Symbols**
+- Invalid strings:
+    - Empty strings: _(`""`)_
+    - Fully whitespace strings: any consecutive combination of the following:
+        - new lines,
+        - spaces,
+        - tabs
+        - _(e.g. `"   "`, `"\n "`, `"  \t  \n "`, etc.)_
+- `true`
+- `undefined`
+- `null`
+- Objects
+- Numbers
+- Big Int
+- Symbols
 
-```js
-// Example: These arguments will be **ignored**, and a console.warn will be printed
+_All of above will be **ignored**, and cause a `console.warn` to be printed_
 
+### Example
+
+```js
 const someVariable = "";
 
 mergeClassNames(
-    someVariable, // empty string
-    "   ", // whitespace
-    "\n ", // whitespace
-    "  \t  \n ", // whitespace
-    `           // whitespace
+    someVariable,
+    "   ",
+    "\n ",
+    "  \t  \n ",
+    `          
         \n
     `,
-    true, // true
-    undefined, // undefined
-    null, // null
+    true,
+    undefined,
+    null,
     {
-        // object
-        name: "value",
-        email: "email@example.com",
+        name: "name",
+        email: "name@example.com",
     },
-    123, // number
-    123.45 // number
+    123,
+    123.45,
 );
 ```
 
+#### Developer Console Warnings
+
 ![screenshot of console.warn warnings because invalid arguments were provided and ignored, so no silent failing](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/console-warnings.png)
 
-### Reason for warnings
+## Conditional Class Inclusion
+
+```jsx
+mergeClassNames(condition ? "min-h-dvh" : false);
 
--   To avoid silent failures, because you will be pulling your hair asking why a Tailwind class isn't working only to figure out you passed an _object_, _array_ or an _empty string_ instead of a valid string. _(It could also be because of an unsupported class name or typo but this is beyond the scope of this package)_
+// or if you want preciseness.
+mergeClassNames(condition === true ? "min-h-dvh" : false);
+```
 
-### Conditional class inclusion
+### Avoid Short-circuit Syntax
 
-Use this pattern:
+Avoid the syntax (`condition && "class-name"`) because it can produce falsy values (e.g. `0`, `""`, `undefined`, `null`) which will be ignored and warned about.
 
--   `condition ? "class-name" : false` with `false` serving as the valid fallback.
--   _or_ `condition === true ? "class-name" : false` if you want to be specific.
+## Return Result
 
-_Note:_ Avoid using the _short-circuit implicit syntax_ like this:
+String of all merged valid classes. Invalid arguments are ignored and warned about.
 
--   `condition && "class-name"`, beside less readable code, it can produce _falsy_ values which will be **_ignored_** _(e.g. `0`, `""`, `undefined`, and `null`)_.
+### Example
 
 ```jsx
 import { mergeClassNames } from "simple-merge-class-names";
 
-const Component = () => {
-    return (
-        <div
-            className={mergeClassNames(
-                "app",
-                condition ? "min-h-dvh" : false,
-                "grid",
-                "grid-rows-[auto_1fr_auto]",
-                "outline"
-            )}
-        >
-            Hello, world!
-        </div>
-    );
-};
+// "app min-h-dvh grid grid-rows-[auto_1fr_auto] outline"
+mergeClassNames(
+    " app ",
+    undefined,
+    [" test "],
+    { key: "value" },
+    "",
+    "min-h-dvh",
+    "grid ",
+    true,
+    null,
+    "grid-rows-[auto_1fr_auto]",
+    "outline",
+    " ",
+);
 ```
 
-### Return Result
+## Side Effect
 
-Either:
+`console.warn`s if arguments contain invalid arguments.
 
-1. **Valid `string`, never whitespace, always length >= 1**
+### Example
 
-2. _or_ **`false`** _(if all input arguments were invalid)_
+```
+Ignored invalid argument: >undefined< (undefined)
+Ignored invalid argument: > test < (object)
+Ignored invalid argument: >[object Object]< (object)
+Ignored empty string: ""
+Ignored invalid argument: >true< (boolean)
+Ignored invalid argument: >null< (object)
+Ignored whitespace string:
+```
 
-### Chaining
+> _It can be empy_
+
+1. **Valid `string`, never whitespace, always length >= 1**
+
+## Chaining
 
 Because of safe return types you can chain calls safely without worrying about warnings or arguments being ignored.
 
@@ -229,85 +330,45 @@ mergeClassNames(condition ? "disabled" : mergeClassNames(...) )
 
 ## Usage of Browser Debugger
 
-**Once you see warnings in the console, the next step is to use `mergeClassNamesDebugger`**
+1.  Use **`import {mergeClassNamesDebugger as mergeClassNames}`** to debug the entire file.
+
+```jsx
+import { mergeClassNamesDebugger as mergeClassNames } from "simple-merge-class-names";
 
-1. Enable Debugger
+const Component = ({ condition }) => {
+    return (
+        <div
+            className={mergeClassNames(
+                "app",
+                condition ? "min-h-dvh" : false,
+                "grid",
+                "grid-rows-[auto_1fr_auto]",
+                "outline",
+            )}
+        >
+            Hello, world!
+        </div>
+    );
+};
+```
+
+2. Enable Debugger
     - _For chromium-based browsers it's On by default and you don't need to do anything AFAIK._
     - _For Firefox:_ Open **_Developer Tools_:**
         - _Make Sure_ **_Debugger_** _(tab)_ -> **`Pause on debugger statement`** is ticked.
         - Keep Dev Tools open.
-          ![screenshot of Firefox Debugger section with Pause on debugger statement ticked on](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/debugger-check.png)
-
--   Use **`import {mergeClassNamesDebugger as mergeClassNames}`** to debug the entire file, and keep the rest intact.
-
-    ```jsx
-    import { mergeClassNamesDebugger as mergeClassNames } from "simple-merge-class-names";
-
-    const Component = ({ condition }) => {
-        return (
-            <div
-                className={mergeClassNames(
-                    "app",
-                    condition ? "min-h-dvh" : false,
-                    "grid",
-                    "grid-rows-[auto_1fr_auto]",
-                    "outline"
-                )}
-            >
-                Hello, world!
-            </div>
-        );
-    };
-    ```
-
--   or call `mergeClassNamesDebugger` directly.
-
-    ```jsx
-    import { mergeClassNamesDebugger } from "simple-merge-class-names";
-
-    const Component = ({ condition }) => {
-        return (
-            <div
-                className={mergeClassNamesDebugger(
-                    "app",
-                    condition ? "min-h-dvh" : false,
-                    "grid",
-                    "grid-rows-[auto_1fr_auto]",
-                    "outline"
-                )}
-            >
-                Hello, world!
-            </div>
-        );
-    };
-    ```
-
--   Refresh the page, the debugger should connect:
-
-    -   Navigate to the **_Call stack_**
-    -   Click the function/component right before _`mergeClassNamesDebugger`_
-
-    ![screenshot of Firefox debugger active because of `undefined` invalid class name argument](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/debugger-active.png)
-
--   Hover over the arguments, one or several should be invalid:
-    ![screenshot of Firefox debugger active because of `undefined` invalid class name argument](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/debugger-3.png)
-
-## VSCode Workflow To Minimize Typing Strain
-
-Use single quotes around class names, and activate `Prettier` which will neatly format and arrange the classes.
 
--   Install `Prettier`
--   Enable `Editor: Word Wrap`:
+![screenshot of Firefox Debugger section with Pause on debugger statement ticked on](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/debugger-check.png)
 
-    -   Open `Settings (UI)` → `Editor: Word Wrap` → `on`
-    -   _or_ `User Settings (JSON)` and add this entry `"editor.wordWrap": "on"`
+3.  Refresh the page, the debugger should connect:
+    - Navigate to the **_Call stack_**
+    - Click the function/component right before _`mergeClassNamesDebugger`_
 
--   Use single quotes (<kbd>'</kbd>) around class names
--   Save the file
+![screenshot of Firefox debugger active because of `undefined` invalid class name argument](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/debugger-active.png)
 
-_Before and after:_
+4. Hover over the arguments, one or several should be invalid:
 
-![Screenshot of code before Prettier neatly formats code](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/Reduce-typing-strain.gif)
+![screenshot of Firefox debugger active because of `undefined` invalid class name argument](https://raw.githubusercontent.com/new-AF/simple-merge-class-names/main/.github/images/debugger-3.png)
 
 ## Testing Source Code
 
@@ -318,6 +379,7 @@ This project uses `Vitest` as the test runner for fast and modern testing.
 ```bash
 git clone https://github.com/new-AF/simple-merge-class-names
 cd simple-merge-class-names
+pnpm install
 pnpm test
 ```
 

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+/**
+ * mergeClassNames - A class names merger for TypeScript, JavaScript, TSX / JSX (React).
+ *
+ * @license AGPL-3.0
+ * Copyright (C) 2026 Abdullah Fatota
+ *
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ 
+
+Only Valid Arguments:
+    1) valid strings: non-empty, non-whitespace
+    2) value `false`
+
+Invalid arguments: anything else e.g.
+    - empty strings
+    - whitespace strings
+    - arrays
+    - numbers
+    - objects
+    - value true
+    - etc.
+*/
+
+declare const mergeClassNames: (...input: (string | false)[]) => string;
+declare const mergeClassNamesDebugger: (...input: (string | false)[]) => string;
+
+export { mergeClassNames, mergeClassNamesDebugger };

package/dist/index.mjs

@@ -0,0 +1,152 @@
+// src/utils.ts
+var classify = (value) => {
+  if (value === false) {
+    return {
+      status: "ignore",
+      value
+    };
+  }
+  if (typeof value !== "string") {
+    return {
+      status: "invalid",
+      value,
+      reason: 0 /* NotAString */
+    };
+  }
+  if (value === "") {
+    return {
+      status: "invalid",
+      value,
+      reason: 1 /* EmptyString */
+    };
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return {
+      status: "invalid",
+      value,
+      reason: 2 /* Whitespace */
+    };
+  }
+  return {
+    status: "class-name",
+    value: trimmed
+  };
+};
+var getClassNames = (values) => {
+  return values.filter((obj) => obj.status === "class-name");
+};
+var getInvalid = (values) => {
+  return values.filter((obj) => obj.status === "invalid");
+};
+var warningMessage = ({
+  value,
+  reason
+}) => {
+  if (reason === 0 /* NotAString */) {
+    if (value === null || value === void 0) {
+      return `Ignored non-string argument: ${value}`;
+    }
+    if (value === true) {
+      return `Ignored non-string argument: ${value} (boolean)`;
+    }
+    if (Array.isArray(value)) {
+      const sub = value.slice(0, 3);
+      const string = JSON.stringify(sub).slice(1, -1);
+      const ellipsisPart = value.length > sub.length ? ", ..." : "";
+      return `Ignored non-string argument: array ([${string}${ellipsisPart}])`;
+    }
+  }
+  if (reason === 1 /* EmptyString */) {
+    return `Ignored empty string argument.`;
+  }
+  if (reason === 2 /* Whitespace */) {
+    return `Ignored whitespace string argument: "${value}"`;
+  }
+  return `Ignored non-string argument: ${value} (${typeof value})`;
+};
+var warn = (invalid, functionName) => {
+  const warning = warningMessage(invalid);
+  console.warn(`[${functionName}]`, warning);
+};
+var activateDebugger = (_invalid) => {
+  debugger;
+};
+
+// src/mergeClassNames.ts
+var mergeClassNamesCore = (values, onClassifiedInvalid) => {
+  const classified = values.map(classify);
+  if (onClassifiedInvalid) {
+    getInvalid(classified).forEach(onClassifiedInvalid);
+  }
+  const classNames = getClassNames(classified).map(
+    ({ value }) => value
+  );
+  const finalClassName = classNames.join(" ");
+  return finalClassName;
+};
+var createCustomMergeClassNames = (options) => {
+  const invalidHandlers = [];
+  const functionName = options.name ?? "Custom mergeClassNames";
+  if (options["console-warn-invalid-and-whitespace-arguments"]) {
+    invalidHandlers.push((arg) => warn(arg, functionName));
+  }
+  if (options["activate-debugger-on-invalid-arguments"]) {
+    invalidHandlers.push(activateDebugger);
+  }
+  const combinedInvalidHandler = (value) => {
+    invalidHandlers.forEach((func) => func(value));
+  };
+  return (...input) => mergeClassNamesCore(
+    input,
+    invalidHandlers.length > 0 ? combinedInvalidHandler : void 0
+  );
+};
+var mergeClassNames = createCustomMergeClassNames({
+  "console-warn-invalid-and-whitespace-arguments": true,
+  "activate-debugger-on-invalid-arguments": false,
+  name: "mergeClassNames"
+});
+var mergeClassNamesDebugger = createCustomMergeClassNames({
+  "console-warn-invalid-and-whitespace-arguments": true,
+  "activate-debugger-on-invalid-arguments": true,
+  name: "mergeClassNamesDebugger"
+});
+/**
+ * mergeClassNames - A class names merger for TypeScript, JavaScript, TSX / JSX (React).
+ *
+ * @license AGPL-3.0
+ * Copyright (C) 2026 Abdullah Fatota
+ *
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ 
+
+Only Valid Arguments:
+    1) valid strings: non-empty, non-whitespace
+    2) value `false`
+
+Invalid arguments: anything else e.g.
+    - empty strings
+    - whitespace strings
+    - arrays
+    - numbers
+    - objects
+    - value true
+    - etc.
+*/
+
+export { mergeClassNames, mergeClassNamesDebugger };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/mergeClassNames.ts"],"names":[],"mappings":";AAQO,IAAM,QAAA,GAAW,CAAC,KAAsC,KAAA;AAM3D,EAAA,IAAI,UAAU,KAAO,EAAA;AACjB,IAAO,OAAA;AAAA,MACH,MAAQ,EAAA,QAAA;AAAA,MACR;AAAA,KACJ;AAAA;AAIJ,EAAI,IAAA,OAAO,UAAU,QAAU,EAAA;AAC3B,IAAO,OAAA;AAAA,MACH,MAAQ,EAAA,SAAA;AAAA,MACR,KAAA;AAAA,MACA,MAAA,EAAA,CAAA;AAAA,KACJ;AAAA;AAMJ,EAAA,IAAI,UAAU,EAAI,EAAA;AACd,IAAO,OAAA;AAAA,MACH,MAAQ,EAAA,SAAA;AAAA,MACR,KAAA;AAAA,MACA,MAAA,EAAA,CAAA;AAAA,KACJ;AAAA;AAGJ,EAAM,MAAA,OAAA,GAAU,MAAM,IAAK,EAAA;AAG3B,EAAA,IAAI,YAAY,EAAI,EAAA;AAChB,IAAO,OAAA;AAAA,MACH,MAAQ,EAAA,SAAA;AAAA,MACR,KAAA;AAAA,MACA,MAAA,EAAA,CAAA;AAAA,KACJ;AAAA;AAIJ,EAAO,OAAA;AAAA,IACH,MAAQ,EAAA,YAAA;AAAA,IACR,KAAO,EAAA;AAAA,GACX;AACJ,CAAA;AAGO,IAAM,aAAA,GAAgB,CAAC,MAAgD,KAAA;AAC1E,EAAA,OAAO,OAAO,MAAO,CAAA,CAAC,GAAQ,KAAA,GAAA,CAAI,WAAW,YAAY,CAAA;AAC7D,CAAA;AAGO,IAAM,UAAA,GAAa,CAAC,MAA8C,KAAA;AACrE,EAAA,OAAO,OAAO,MAAO,CAAA,CAAC,GAAQ,KAAA,GAAA,CAAI,WAAW,SAAS,CAAA;AAC1D,CAAA;AAEO,IAAM,iBAAiB,CAAC;AAAA,EAC3B,KAAA;AAAA,EACA;AACJ,CAAiC,KAAA;AAC7B,EAAA,IAAI,MAA+C,KAAA,CAAA,mBAAA;AAE/C,IAAI,IAAA,KAAA,KAAU,IAAQ,IAAA,KAAA,KAAU,MAAW,EAAA;AACvC,MAAA,OAAO,gCAAgC,KAAK,CAAA,CAAA;AAAA;AAIhD,IAAA,IAAI,UAAU,IAAM,EAAA;AAChB,MAAA,OAAO,gCAAgC,KAAK,CAAA,UAAA,CAAA;AAAA;AAIhD,IAAI,IAAA,KAAA,CAAM,OAAQ,CAAA,KAAK,CAAG,EAAA;AACtB,MAAA,MAAM,GAAM,GAAA,KAAA,CAAM,KAAM,CAAA,CAAA,EAAG,CAAC,CAAA;AAC5B,MAAA,MAAM,SAAS,IAAK,CAAA,SAAA,CAAU,GAAG,CAAE,CAAA,KAAA,CAAM,GAAG,EAAE,CAAA;AAC9C,MAAA,MAAM,YAAe,GAAA,KAAA,CAAM,MAAS,GAAA,GAAA,CAAI,SAAS,OAAU,GAAA,EAAA;AAE3D,MAAO,OAAA,CAAA,qCAAA,EAAwC,MAAM,CAAA,EAAG,YAAY,CAAA,EAAA,CAAA;AAAA;AACxE;AAIJ,EAAA,IAAI,MAAgD,KAAA,CAAA,oBAAA;AAChD,IAAO,OAAA,CAAA,8BAAA,CAAA;AAAA;AAIX,EAAA,IAAI,MAA+C,KAAA,CAAA,mBAAA;AAC/C,IAAA,OAAO,wCAAwC,KAAK,CAAA,CAAA,CAAA;AAAA;AAIxD,EAAA,OAAO,CAAgC,6BAAA,EAAA,KAAK,CAAK,EAAA,EAAA,OAAO,KAAK,CAAA,CAAA,CAAA;AACjE,CAAA;AAGO,IAAM,IAAA,GAAO,CAAC,OAAA,EAA4B,YAAyB,KAAA;AACtE,EAAM,MAAA,OAAA,GAAU,eAAe,OAAO,CAAA;AAEtC,EAAA,OAAA,CAAQ,IAAK,CAAA,CAAA,CAAA,EAAI,YAAY,CAAA,CAAA,CAAA,EAAK,OAAO,CAAA;AAC7C,CAAA;AAGO,IAAM,gBAAA,GAAmB,CAAC,QAAgC,KAAA;AAC7D,EAAA;AACJ,CAAA;;;ACpEA,IAAM,mBAAA,GAAsB,CACxB,MAAA,EACA,mBACC,KAAA;AAED,EAAM,MAAA,UAAA,GAAa,MAAO,CAAA,GAAA,CAAI,QAAQ,CAAA;AAGtC,EAAA,IAAI,mBAAqB,EAAA;AACrB,IAAW,UAAA,CAAA,UAAU,CAAE,CAAA,OAAA,CAAQ,mBAAmB,CAAA;AAAA;AAItD,EAAM,MAAA,UAAA,GAAuB,aAAc,CAAA,UAAU,CAAE,CAAA,GAAA;AAAA,IACnD,CAAC,EAAE,KAAA,EAAY,KAAA;AAAA,GACnB;AAEA,EAAM,MAAA,cAAA,GAAiB,UAAW,CAAA,IAAA,CAAK,GAAG,CAAA;AAC1C,EAAO,OAAA,cAAA;AACX,CAAA;AAGO,IAAM,2BAAA,GAA8B,CAAC,OAA2B,KAAA;AACnE,EAAA,MAAM,kBAA+C,EAAC;AAGtD,EAAM,MAAA,YAAA,GAAe,QAAQ,IAAQ,IAAA,wBAAA;AAErC,EAAI,IAAA,OAAA,CAAQ,+CAA+C,CAAG,EAAA;AAC1D,IAAA,eAAA,CAAgB,KAAK,CAAC,GAAA,KAAQ,IAAK,CAAA,GAAA,EAAK,YAAY,CAAC,CAAA;AAAA;AAGzD,EAAI,IAAA,OAAA,CAAQ,wCAAwC,CAAG,EAAA;AACnD,IAAA,eAAA,CAAgB,KAAK,gBAAgB,CAAA;AAAA;AAGzC,EAAM,MAAA,sBAAA,GAAyB,CAAC,KAA6B,KAAA;AACzD,IAAA,eAAA,CAAgB,OAAQ,CAAA,CAAC,IAAS,KAAA,IAAA,CAAK,KAAK,CAAC,CAAA;AAAA,GACjD;AAGA,EAAA,OAAO,IAAI,KACP,KAAA,mBAAA;AAAA,IACI,KAAA;AAAA,IACA,eAAA,CAAgB,MAAS,GAAA,CAAA,GAAI,sBAAyB,GAAA;AAAA,GAC1D;AACR,CAAA;AAEO,IAAM,kBAAkB,2BAA4B,CAAA;AAAA,EACvD,+CAAiD,EAAA,IAAA;AAAA,EACjD,wCAA0C,EAAA,KAAA;AAAA,EAC1C,IAAM,EAAA;AACV,CAAC;AAEM,IAAM,0BAA0B,2BAA4B,CAAA;AAAA,EAC/D,+CAAiD,EAAA,IAAA;AAAA,EACjD,wCAA0C,EAAA,IAAA;AAAA,EAC1C,IAAM,EAAA;AACV,CAAC","file":"index.mjs","sourcesContent":["import {\r\n    Classified,\r\n    ClassifiedInvalid,\r\n    ClassifiedInvalidReason,\r\n    ClassifiedClassName,\r\n} from \"./types\";\r\n\r\n// classifies input arguments\r\nexport const classify = (value: string | false): Classified => {\r\n    // FP pattern of mapping values with extra information.\r\n    // The core computes data.\r\n    // because TS types disappear in JS runtime\r\n\r\n    // valid but ignored\r\n    if (value === false) {\r\n        return {\r\n            status: \"ignore\",\r\n            value,\r\n        };\r\n    }\r\n\r\n    // invalid\r\n    if (typeof value !== \"string\") {\r\n        return {\r\n            status: \"invalid\",\r\n            value,\r\n            reason: ClassifiedInvalidReason.NotAString,\r\n        };\r\n    }\r\n\r\n    // it's a string\r\n\r\n    // invalid.\r\n    if (value === \"\") {\r\n        return {\r\n            status: \"invalid\",\r\n            value,\r\n            reason: ClassifiedInvalidReason.EmptyString,\r\n        };\r\n    }\r\n\r\n    const trimmed = value.trim();\r\n\r\n    // invalid\r\n    if (trimmed === \"\") {\r\n        return {\r\n            status: \"invalid\",\r\n            value,\r\n            reason: ClassifiedInvalidReason.Whitespace,\r\n        };\r\n    }\r\n\r\n    // valid\r\n    return {\r\n        status: \"class-name\",\r\n        value: trimmed,\r\n    };\r\n};\r\n\r\n// get only valid objects\r\nexport const getClassNames = (values: Classified[]): ClassifiedClassName[] => {\r\n    return values.filter((obj) => obj.status === \"class-name\");\r\n};\r\n\r\n// get only valid objects\r\nexport const getInvalid = (values: Classified[]): ClassifiedInvalid[] => {\r\n    return values.filter((obj) => obj.status === \"invalid\");\r\n};\r\n\r\nexport const warningMessage = ({\r\n    value,\r\n    reason,\r\n}: ClassifiedInvalid): string => {\r\n    if (reason === ClassifiedInvalidReason.NotAString) {\r\n        // null, undefined\r\n        if (value === null || value === undefined) {\r\n            return `Ignored non-string argument: ${value}`;\r\n        }\r\n\r\n        // true (because false was filtered out)\r\n        if (value === true) {\r\n            return `Ignored non-string argument: ${value} (boolean)`;\r\n        }\r\n\r\n        // array\r\n        if (Array.isArray(value)) {\r\n            const sub = value.slice(0, 3);\r\n            const string = JSON.stringify(sub).slice(1, -1);\r\n            const ellipsisPart = value.length > sub.length ? \", ...\" : \"\";\r\n\r\n            return `Ignored non-string argument: array ([${string}${ellipsisPart}])`;\r\n        }\r\n    }\r\n\r\n    // empty string\r\n    if (reason === ClassifiedInvalidReason.EmptyString) {\r\n        return `Ignored empty string argument.`;\r\n    }\r\n\r\n    // whitespace\r\n    if (reason === ClassifiedInvalidReason.Whitespace) {\r\n        return `Ignored whitespace string argument: \"${value}\"`;\r\n    }\r\n\r\n    // object, symbol, etc.\r\n    return `Ignored non-string argument: ${value} (${typeof value})`;\r\n};\r\n\r\n// console.warn\r\nexport const warn = (invalid: ClassifiedInvalid, functionName: string) => {\r\n    const warning = warningMessage(invalid);\r\n\r\n    console.warn(`[${functionName}]`, warning);\r\n};\r\n\r\n// activates debugger\r\nexport const activateDebugger = (_invalid: ClassifiedInvalid) => {\r\n    debugger;\r\n};\r\n","/**\r\n * mergeClassNames - A class names merger for TypeScript, JavaScript, TSX / JSX (React).\r\n *\r\n * @license AGPL-3.0\r\n * Copyright (C) 2026 Abdullah Fatota\r\n *\r\n *\r\n * This program is free software: you can redistribute it and/or modify\r\n * it under the terms of the GNU Affero General Public License as published by\r\n * the Free Software Foundation, either version 3 of the License, or\r\n * (at your option) any later version.\r\n *\r\n * This program is distributed in the hope that it will be useful,\r\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\r\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\r\n * GNU Affero General Public License for more details.\r\n *\r\n * You should have received a copy of the GNU Affero General Public License\r\n * along with this program. If not, see <https://www.gnu.org/licenses/>.\r\n \r\n\r\nOnly Valid Arguments:\r\n    1) valid strings: non-empty, non-whitespace\r\n    2) value `false`\r\n\r\nInvalid arguments: anything else e.g.\r\n    - empty strings\r\n    - whitespace strings\r\n    - arrays\r\n    - numbers\r\n    - objects\r\n    - value true\r\n    - etc.\r\n*/\r\n\r\nimport {\r\n    ClassifiedInvalidFunction,\r\n    ClassifiedInvalid,\r\n    CustomOptions,\r\n} from \"./types\";\r\n\r\nimport {\r\n    classify,\r\n    getInvalid,\r\n    warn,\r\n    activateDebugger,\r\n    getClassNames,\r\n} from \"./utils\";\r\n\r\n// joins valid strings into final className\r\nconst mergeClassNamesCore = (\r\n    values: (string | false)[],\r\n    onClassifiedInvalid?: ClassifiedInvalidFunction,\r\n) => {\r\n    // classify arguments\r\n    const classified = values.map(classify);\r\n\r\n    // optional call invalid arguments handlers: warn and/or activate debugger\r\n    if (onClassifiedInvalid) {\r\n        getInvalid(classified).forEach(onClassifiedInvalid);\r\n    }\r\n\r\n    // valid strings only\r\n    const classNames: string[] = getClassNames(classified).map(\r\n        ({ value }) => value,\r\n    );\r\n\r\n    const finalClassName = classNames.join(\" \");\r\n    return finalClassName;\r\n};\r\n\r\n// creates custom mergeClassNames e.g. warn = false, activate debugger = true\r\nexport const createCustomMergeClassNames = (options: CustomOptions) => {\r\n    const invalidHandlers: ClassifiedInvalidFunction[] = [];\r\n\r\n    // will be logged in console\r\n    const functionName = options.name ?? \"Custom mergeClassNames\";\r\n\r\n    if (options[\"console-warn-invalid-and-whitespace-arguments\"]) {\r\n        invalidHandlers.push((arg) => warn(arg, functionName));\r\n    }\r\n\r\n    if (options[\"activate-debugger-on-invalid-arguments\"]) {\r\n        invalidHandlers.push(activateDebugger);\r\n    }\r\n\r\n    const combinedInvalidHandler = (value: ClassifiedInvalid) => {\r\n        invalidHandlers.forEach((func) => func(value));\r\n    };\r\n\r\n    // construct the mergeClassNames function\r\n    return (...input: (string | false)[]) =>\r\n        mergeClassNamesCore(\r\n            input,\r\n            invalidHandlers.length > 0 ? combinedInvalidHandler : undefined,\r\n        );\r\n};\r\n\r\nexport const mergeClassNames = createCustomMergeClassNames({\r\n    \"console-warn-invalid-and-whitespace-arguments\": true,\r\n    \"activate-debugger-on-invalid-arguments\": false,\r\n    name: \"mergeClassNames\",\r\n});\r\n\r\nexport const mergeClassNamesDebugger = createCustomMergeClassNames({\r\n    \"console-warn-invalid-and-whitespace-arguments\": true,\r\n    \"activate-debugger-on-invalid-arguments\": true,\r\n    name: \"mergeClassNamesDebugger\",\r\n});\r\n"]}

package/package.json

@@ -1,23 +1,24 @@
 {
   "name": "simple-merge-class-names",
-  "version": "7.0.3",
-  "description": "A straightforward utility for merging CSS class names in React + Tailwind and JavaScript projects.",
+  "version": "8.1.0",
+  "description": " A class names merger for TypeScript, JavaScript, TSX, and JSX (React)",
   "exports": {
     ".": {
-      "import": "./mergeClassNames.js",
-      "types": "./mergeClassNames.d.ts"
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
     }
   },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "files": [
-    "mergeClassNames.js",
-    "mergeClassNames.d.ts",
+    "dist",
     "LICENSE.txt",
     "README.md"
   ],
   "sideEffects": false,
   "keywords": [
-    "class-merger",
     "class-names-merger",
+    "classes-merger",
     "jsx",
     "merge",
     "mergeClassNames",
@@ -25,6 +26,7 @@
     "merger",
     "react",
     "tailwindcss",
+    "tsx",
     "utility"
   ],
   "author": "Abdullah Fatota",
@@ -33,14 +35,14 @@
     "type": "git",
     "url": "git+https://github.com/new-AF/simple-merge-class-names.git"
   },
-  "bugs": {
-    "url": "https://github.com/new-AF/simple-merge-class-names/issues"
-  },
   "homepage": "https://github.com/new-AF/simple-merge-class-names",
   "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
     "vitest": "^3.2.3"
   },
   "scripts": {
+    "build": "tsup",
     "test": "vitest",
     "test:watch": "vitest --watch",
     "test:ui": "vitest --ui"

package/mergeClassNames.d.ts

@@ -1,7 +0,0 @@
-export declare const mergeClassNames: (
-    ...args: (string | false)[]
-) => string | false;
-
-export declare const mergeClassNamesDebugger: (
-    ...args: (string | false)[]
-) => string | false;

package/mergeClassNames.js

@@ -1,175 +0,0 @@
-/**
- * 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
- *
- * Example usage:
- * import { mergeClassNames } from "simple-merge-class-names";
- *
- * function MyComponent() {
- *   return (
- *     <div
- *       className={mergeClassNames(
- *         "app",
- *         "min-h-dvh",
- *         "grid",
- *         "grid-rows-[auto_1fr_auto]",
- *         "outline"
- *       )}
- *     >
- *       Hello, world!
- *     </div>
- *   );
- * }
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
-
-const partition = (array, keepPredicate) => {
-    const keep = [];
-    const ignore = [];
-    for (const element of array) {
-        const arrayRef = keepPredicate(element) ? keep : ignore;
-        arrayRef.push(element);
-    }
-    return [keep, ignore];
-};
-
-const filterArguments = (argumentsArray) => {
-    /* 
-    returns {
-        valid: bool,
-        value: any
-        (optional) isString: bool,
-        (optional) valueType: any
-        (optional) isValueFalse
-        (optional) isValidString: bool
-    }
-    */
-    const isValidArgument = (value) => {
-        const valueType = typeof value;
-
-        if (value === false) {
-            return { valid: true, value };
-        }
-
-        if (valueType === "string") {
-            const trimmed = value.trim();
-
-            // invalid string
-            if (trimmed === "") {
-                return {
-                    valid: false,
-                    value,
-                    isString: true,
-                    isValidString: false,
-                };
-            }
-            // valid string
-            return {
-                valid: true,
-                value: trimmed,
-                isString: true,
-                isValidString: true,
-            };
-        }
-
-        // everything else
-        return { valid: false, value, isString: false, valueType };
-    };
-
-    // array of objects
-    const newArguments = argumentsArray.map((element) =>
-        isValidArgument(element)
-    );
-
-    // includes `false`
-    const [validArgumentsWithFalse, invalidArguments] = partition(
-        newArguments,
-        ({ valid }) => valid === true
-    );
-
-    // ignore `false`
-    const [validArguments, _] = partition(
-        validArgumentsWithFalse,
-        ({ value }) => value !== false
-    );
-
-    // console.log({ validArgumentsWithFalse, validArguments, invalidArguments });
-
-    return { validArguments, invalidArguments };
-};
-
-const warnMessage = (
-    { value, isString, valueType, isValidString },
-    callerFunctionName
-) => {
-    if (isString === false) {
-        return `[${callerFunctionName}] Ignored non-string >${value}< (${valueType})`;
-    } else if (isValidString === false) {
-        return `[${callerFunctionName}] Ignored empty string "${value}"`;
-    }
-};
-
-const warnOnly = (
-    invalidArgumentsArray,
-    callerFunctionName,
-    debuggerVariantName
-) =>
-    invalidArgumentsArray.forEach((obj) => {
-        const message = warnMessage(obj, callerFunctionName);
-        console.warn(`${message}`);
-    });
-
-const warnDebug = (invalidArgumentsArray, callerFunctionName) =>
-    invalidArgumentsArray.forEach((obj) => {
-        console.warn(warnMessage(obj, callerFunctionName));
-        debugger;
-    });
-
-const join = (argumentsArray) => {
-    const space = "\x20"; // ASCII for single space (" "), decimal 32
-    const classNames = argumentsArray.map(({ value }) => value).join(space);
-    return classNames;
-};
-
-const finalResult = (joinedClassNames) =>
-    joinedClassNames === "" ? false : joinedClassNames;
-
-// exported
-// export const mergeClassNamesNoWarning = (...argumentsArray) => {
-//     const { validArguments, _ } = filterArguments(argumentsArray);
-//     const classNames = join(validArguments);
-//     const result = finalResult(classNames);
-//     return result;
-// };
-
-export const mergeClassNames = (...argumentsArray) => {
-    const { validArguments, invalidArguments } =
-        filterArguments(argumentsArray);
-    warnOnly(invalidArguments, "mergeClassNames", "mergeClassNamesDebugger");
-    const classNames = join(validArguments);
-    const result = finalResult(classNames);
-    return result;
-};
-
-export const mergeClassNamesDebugger = (...argumentsArray) => {
-    const { validArguments, invalidArguments } =
-        filterArguments(argumentsArray);
-    warnDebug(invalidArguments, "mergeClassNamesDebugger");
-    const classNames = join(validArguments);
-    const result = finalResult(classNames);
-    return result;
-};