@lightsound/cn 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 lightsound
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,183 @@
+# @lightsound/cn
+
+A tiny, **blazing fast** utility for constructing `className` strings conditionally.
+
+[![npm version](https://img.shields.io/npm/v/@lightsound/cn.svg)](https://www.npmjs.com/package/@lightsound/cn)
+[![gzip size](https://img.shields.io/badge/gzip-139B-brightgreen.svg)](https://bundlephobia.com/package/@lightsound/cn)
+[![license](https://img.shields.io/npm/l/@lightsound/cn.svg)](./LICENSE)
+
+## Features
+
+- **Blazing Fast**: Up to 48% faster than `clsx/lite`
+- **Tiny**: ~139B gzipped (smaller than clsx/lite!)
+- **TypeScript**: Full type support out of the box
+- **Simple API**: Strings only - no objects, no arrays, maximum performance
+- **Zero Dependencies**: No external dependencies
+
+## Benchmarks
+
+Benchmarked on Apple M2 with Bun 1.3.4:
+
+| Test Case  | @lightsound/cn | clsx/lite | Improvement    |
+| ---------- | -------------- | --------- | -------------- |
+| 2 strings  | 21.17 ns       | 33.23 ns  | **36% faster** |
+| 3 strings  | 25.74 ns       | 46.05 ns  | **44% faster** |
+| 5 strings  | 37.84 ns       | 70.59 ns  | **46% faster** |
+| 10 strings | 63.60 ns       | 121.75 ns | **48% faster** |
+
+## Installation
+
+```bash
+# npm
+npm install @lightsound/cn
+
+# pnpm
+pnpm add @lightsound/cn
+
+# yarn
+yarn add @lightsound/cn
+
+# bun
+bun add @lightsound/cn
+```
+
+## Usage
+
+```typescript
+import { cn } from "@lightsound/cn";
+// or
+import cn from "@lightsound/cn";
+
+// Basic usage
+cn("foo", "bar");
+// => 'foo bar'
+
+// Conditional classes
+cn("btn", isActive && "btn-active", isDisabled && "btn-disabled");
+// => 'btn btn-active' (if isActive is true, isDisabled is false)
+
+// With ternary expressions
+cn("btn", variant === "primary" ? "btn-primary" : "btn-secondary");
+// => 'btn btn-primary'
+
+// Falsy values are ignored
+cn("foo", false, null, undefined, 0, "", "bar");
+// => 'foo bar'
+```
+
+## Real-world Example (Tailwind CSS)
+
+```typescript
+import { cn } from "@lightsound/cn";
+
+interface ButtonProps {
+  variant?: "primary" | "secondary";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  className?: string;
+}
+
+function Button({
+  variant = "primary",
+  size = "md",
+  disabled,
+  className,
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(
+        "inline-flex items-center justify-center rounded-md font-medium",
+        "transition-colors focus-visible:outline-none focus-visible:ring-2",
+        variant === "primary" && "bg-blue-500 text-white hover:bg-blue-600",
+        variant === "secondary" &&
+          "bg-gray-200 text-gray-900 hover:bg-gray-300",
+        size === "sm" && "h-8 px-3 text-sm",
+        size === "md" && "h-10 px-4 text-base",
+        size === "lg" && "h-12 px-6 text-lg",
+        disabled && "pointer-events-none opacity-50",
+        className
+      )}
+      disabled={disabled}
+    >
+      Click me
+    </button>
+  );
+}
+```
+
+## API
+
+### `cn(...classes)`
+
+Combines class names into a single string. Only accepts strings - non-string values (falsy values) are ignored.
+
+#### Parameters
+
+- `...classes`: `(string | false | null | undefined | 0)[]` - Any number of class name strings or falsy values
+
+#### Returns
+
+- `string` - The combined class names separated by spaces
+
+## Why @lightsound/cn?
+
+| Feature         | @lightsound/cn | clsx  | clsx/lite |
+| --------------- | -------------- | ----- | --------- |
+| Strings only    | ✅             | ❌    | ✅        |
+| Objects support | ❌             | ✅    | ❌        |
+| Arrays support  | ❌             | ✅    | ❌        |
+| Size (gzip)     | ~139B          | ~239B | ~149B     |
+| Performance     | ⚡⚡⚡         | ⚡⚡  | ⚡⚡      |
+
+If you only use string-based class composition (the most common pattern with Tailwind CSS), `@lightsound/cn` provides the best performance.
+
+## Compatibility with clsx/lite
+
+`@lightsound/cn` is designed as a faster, drop-in replacement for `clsx/lite` in typical usage:
+
+```typescript
+// Before
+import clsx from "clsx/lite";
+clsx("btn", isActive && "active", "btn-primary");
+
+// After
+import { cn } from "@lightsound/cn";
+cn("btn", isActive && "active", "btn-primary");
+```
+
+### TypeScript Users
+
+**You're fully covered!** The type definition only accepts `string | false | 0 | null | undefined`, so passing objects or arrays will result in a compile-time error:
+
+```typescript
+cn("btn", { active: true }); // ❌ TypeScript error
+cn("btn", ["a", "b"]); // ❌ TypeScript error
+cn("btn", isActive && "active"); // ✅ Works perfectly
+```
+
+### JavaScript Users
+
+Note that runtime behavior differs from `clsx/lite` when passing unsupported types:
+
+| Input              | clsx/lite | @lightsound/cn      |
+| ------------------ | --------- | ------------------- |
+| `{ active: true }` | `""`      | `"[object Object]"` |
+| `["a", "b"]`       | `""`      | `"a,b"`             |
+
+If you're using JavaScript, ensure your codebase only passes strings and falsy values to `cn()`.
+
+## Tailwind CSS IntelliSense
+
+To enable Tailwind CSS IntelliSense for `cn()`, add this to your VS Code settings:
+
+```json
+{
+  "tailwindCSS.experimental.classRegex": [
+    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
+  ]
+}
+```
+
+## License
+
+MIT © [lightsound](https://github.com/lightsound)

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+type ClassValue = string | false | 0 | null | undefined;
+export declare function cn(): string;
+export declare function cn(a: ClassValue): string;
+export declare function cn(a: ClassValue, b: ClassValue): string;
+export declare function cn(a: ClassValue, b: ClassValue, c: ClassValue): string;
+export declare function cn(a: ClassValue, b: ClassValue, c: ClassValue, d: ClassValue): string;
+export declare function cn(...args: ClassValue[]): string;
+export { cn as default };

package/dist/index.js

@@ -0,0 +1 @@
+function e(){let s="",a,l=arguments.length;for(let n=0;n<l;n++)if(a=arguments[n])s=s?s+" "+a:a;return s}export{e as default,e as cn};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lightsound/cn",
+  "version": "0.1.0",
+  "description": "A tiny, blazing fast utility for constructing className strings conditionally",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build src/index.ts --outdir dist --minify --target browser",
+    "build:types": "tsgo -p tsconfig.build.json",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "bench": "bun run bench/index.ts",
+    "prepublishOnly": "bun run build && bun run test"
+  },
+  "keywords": [
+    "classnames",
+    "classes",
+    "classname",
+    "class",
+    "cn",
+    "clsx",
+    "tailwind",
+    "css"
+  ],
+  "author": "lightsound",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lightsound/cn.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lightsound/cn/issues"
+  },
+  "homepage": "https://github.com/lightsound/cn#readme",
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "@typescript/native-preview": "^7.0.0-dev.20251213.1",
+    "clsx": "^2.1.1",
+    "mitata": "^1.0.34"
+  }
+}