@jsdevlab/classnames 0.0.0-stage → 1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsdevlab
+
+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

@@ -1,3 +1,361 @@
-# Temporary Holding Version
+# @jsdevlab/classnames
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@jsdevlab/classnames.svg)](https://www.npmjs.com/package/@jsdevlab/classnames)
+[![CI](https://github.com/jsdevlab/classnames/actions/workflows/ci.yml/badge.svg)](https://github.com/jsdevlab/classnames/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE.txt)
+
+**English** | [简体中文](./README.zh-CN.md)
+
+Type-safe conditional class names for JavaScript and TypeScript — framework-agnostic,
+classnames-compatible, with lazy evaluation and deduplication by default.
+
+## Features
+
+- **Familiar API** — the same `classNames(...)` call shape you already know.
+- **Deduplication by default** — `'a b a'` becomes `'a b'`; first-occurrence order is preserved.
+- **Lazy function values** — `{ active: () => condition }` is evaluated when the class string is built.
+- **Rich inputs** — strings, numbers, booleans, objects, nested arrays, and `Set`s.
+- **Dedup opt-out factory** — `createClassNames({ unique: false })` keeps duplicates when you need them.
+- **`cx` alias** — a short alias with identical behavior.
+- **TypeScript-first** — complete declarations and exported types.
+- **Zero runtime dependencies** — ESM + CJS builds, works in any modern JS runtime.
+
+## Installation
+
+```bash
+pnpm add @jsdevlab/classnames
+# or
+npm install @jsdevlab/classnames
+# or
+yarn add @jsdevlab/classnames
+```
+
+## Quick start
+
+```ts
+import { classNames, cx, createClassNames } from '@jsdevlab/classnames';
+
+classNames('btn', 'btn-primary');                                // 'btn btn-primary'
+classNames('btn', { 'btn-primary': true, 'is-loading': false }); // 'btn btn-primary'
+classNames('btn', ['btn-lg', ['rounded']]);                      // 'btn btn-lg rounded'
+classNames('btn', new Set(['btn-lg', 'rounded']));               // 'btn btn-lg rounded'
+classNames('btn', 'btn');                                        // 'btn'
+
+cx('btn', { disabled: true });                                   // 'btn disabled'
+```
+
+There is **no default export** — use named imports:
+
+```ts
+import { classNames } from '@jsdevlab/classnames'; // ✅
+// import classNames from '@jsdevlab/classnames'; // ❌ not supported
+```
+
+## Usage
+
+### Conditional class names
+
+Object keys are emitted only when the corresponding value is truthy:
+
+```ts
+const isActive = true;
+
+classNames('tab', {
+  'is-active': isActive,
+  'is-disabled': !isActive,
+});
+// 'tab is-active'
+```
+
+### Strings and numbers
+
+Numbers are stringified; top-level `0` is kept:
+
+```ts
+classNames('z', 0, 1, 2); // 'z 0 1 2'
+```
+
+Note that object values use truthiness, so `0` is dropped there:
+
+```ts
+classNames({ zero: 0, one: 1 }); // 'one'
+```
+
+### Nested arrays and Sets
+
+Arrays are flattened recursively, and `Set`s are supported directly:
+
+```ts
+classNames(['a', ['b', ['c']]]);           // 'a b c'
+classNames(new Set(['a', 'b']));           // 'a b'
+classNames([new Set(['a']), { b: true }]); // 'a b'
+```
+
+### Lazy function values
+
+A function used as an **object value** is invoked once at call time. Its return
+value only decides whether the key is included — it is not converted to a class
+name:
+
+```ts
+const flags = {
+  'is-active': () => user.active,
+  'is-admin': () => user.roles.includes('admin'),
+};
+
+classNames('user', flags);
+// Both functions are evaluated now; only truthy keys are emitted.
+```
+
+This keeps call sites clean and defers expensive checks until the class string is
+actually built. Each function runs once per `classNames` call; reusing the same
+object across calls re-evaluates it.
+
+### Deduplication
+
+Duplicates are removed by default, preserving the order of first appearance:
+
+```ts
+classNames('a', 'b', 'a', ['b', { a: true }]); // 'a b'
+```
+
+### Keeping duplicates
+
+Create a factory with deduplication turned off:
+
+```ts
+import { createClassNames } from '@jsdevlab/classnames';
+
+const join = createClassNames({ unique: false });
+
+join('a', 'a');        // 'a a'
+classNames('a', 'a');  // 'a'
+```
+
+Options are resolved when the factory is created, so the returned function is
+bound to them:
+
+```ts
+const cls = createClassNames(); // unique defaults to true
+cls('a', 'a');                  // 'a'
+```
+
+### React
+
+```tsx
+import { cx } from '@jsdevlab/classnames';
+import type { ReactNode } from 'react';
+
+interface ButtonProps {
+  primary?: boolean;
+  loading?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+export function Button({
+  primary,
+  loading,
+  className,
+  children,
+}: ButtonProps) {
+  return (
+    <button
+      className={cx(
+        'btn',
+        { 'btn-primary': primary, 'is-loading': loading },
+        className,
+      )}
+      disabled={loading}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { classNames } from '@jsdevlab/classnames';
+
+defineProps<{ active?: boolean; disabled?: boolean }>();
+</script>
+
+<template>
+  <button
+    :class="classNames('tab', { 'is-active': active, 'is-disabled': disabled })"
+  >
+    <slot />
+  </button>
+</template>
+```
+
+Because the library is framework-agnostic, the same functions work in Svelte,
+Solid, Angular, plain DOM code, or anywhere else JavaScript runs.
+
+## API
+
+### `classNames(...values: ClassValue[]): string`
+
+Accepts any mix of supported values and returns a single space-separated class
+name string. Returns `''` when nothing matches:
+
+```ts
+classNames();                       // ''
+classNames(null, false, undefined); // ''
+```
+
+### `cx`
+
+An alias of `classNames` with the identical signature and behavior:
+
+```ts
+cx('a', { b: true }); // 'a b'
+```
+
+### `createClassNames(options?: ClassNamesOptions): typeof classNames`
+
+Returns a `classNames`-style function bound to the given options.
+
+#### `ClassNamesOptions`
+
+| Option   | Type      | Default | Description                                       |
+| -------- | --------- | ------- | ------------------------------------------------- |
+| `unique` | `boolean` | `true`  | Deduplicate class names, preserving first-occurrence order. |
+
+```ts
+const defaultJoin = createClassNames();                    // unique: true
+const keepAll = createClassNames({ unique: false });       // keeps duplicates
+```
+
+## Types
+
+All types are exported:
+
+```ts
+export type ClassValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | ClassObject
+  | ClassValue[]
+  | Set<ClassValue>;
+
+export interface ClassObject {
+  [key: string]: ClassValue | (() => ClassValue);
+}
+
+export interface ClassNamesOptions {
+  unique?: boolean;
+}
+```
+
+## Behavior reference
+
+| Input                                                          | Output     |
+| -------------------------------------------------------------- | ---------- |
+| `classNames('a', 'b')`                                         | `'a b'`    |
+| `classNames('a', '', null, undefined, false, true)`            | `'a'`      |
+| `classNames(0, 1)`                                             | `'0 1'`    |
+| `classNames({ a: true, b: false, c: 1, d: 0 })`                | `'a c'`    |
+| `classNames(['a', [{ b: true }]])`                             | `'a b'`    |
+| `classNames(new Set(['a', 'b']))`                              | `'a b'`    |
+| `classNames({ active: () => true, hidden: () => false })`      | `'active'` |
+| `classNames('a', 'b', 'a')`                                    | `'a b'`    |
+| `createClassNames({ unique: false })('a', 'a')`                | `'a a'`    |
+| `classNames()`                                                 | `''`       |
+
+## Notes and edge cases
+
+- Class names are always joined with a **single space**; there is no custom
+  separator option.
+- Deduplication compares exact, case-sensitive strings and does **not** split
+  strings: `classNames('a b', 'b')` returns `'a b b'`.
+- Top-level `0` is kept (`classNames(0)` → `'0'`), but `0` as an object value is
+  falsy and dropped (`{ a: 0 }` → `''`).
+- `true` and `false` are ignored as values; only object keys produce output.
+- Functions are supported **only as object values**. A function passed as a
+  top-level argument is ignored.
+- A function's return value is tested for truthiness; it does not become the
+  class name (`{ a: () => 'foo' }` → `'a'`).
+- Output order follows input order; object keys follow `Object.entries` order.
+  Deduplication keeps the first occurrence.
+- `null`, `undefined`, and empty strings are ignored.
+
+## classnames compatibility
+
+`@jsdevlab/classnames` is a drop-in replacement for `classnames` in most cases:
+
+```diff
+-import classNames from 'classnames';
++import { classNames } from '@jsdevlab/classnames';
+```
+
+| Capability                          | `classnames`                    | `@jsdevlab/classnames`              |
+| ----------------------------------- | ------------------------------- | ----------------------------------- |
+| Strings / numbers                   | ✅                              | ✅                                  |
+| Objects with truthy keys            | ✅                              | ✅                                  |
+| Nested arrays                       | ✅                              | ✅                                  |
+| Skips `null` / `undefined` / `false` / `''` | ✅                      | ✅                                  |
+| `Set` input                         | —                               | ✅                                  |
+| Function values in objects          | Not evaluated (functions are truthy) | Evaluated at call time         |
+| Duplicate removal                   | via `classnames/dedupe`         | Default                             |
+| Keep duplicates                     | Default                         | `createClassNames({ unique: false })` |
+| Custom separator                    | —                               | —                                   |
+| Default export                      | ✅                              | — (named exports only)              |
+
+If you relied on the default duplicate-preserving behavior of `classnames`, bind
+your own instance:
+
+```ts
+import { createClassNames } from '@jsdevlab/classnames';
+
+const classNames = createClassNames({ unique: false });
+```
+
+## Module formats
+
+| Format     | File               |
+| ---------- | ------------------ |
+| ESM        | `dist/index.js`    |
+| CommonJS   | `dist/index.cjs`   |
+| TypeScript | `dist/index.d.ts`  |
+
+```ts
+// ESM
+import { classNames } from '@jsdevlab/classnames';
+
+// CommonJS
+const { classNames } = require('@jsdevlab/classnames');
+```
+
+The package has no runtime dependencies and works in modern browsers, Node.js,
+Bun, and Deno.
+
+## Development
+
+Requires Node.js ≥ 24.19 and pnpm 12.18.
+
+```bash
+pnpm install
+pnpm test        # tsc --noEmit + rstest
+pnpm build       # rslib build → dist/
+pnpm check       # Biome lint + fix
+pnpm format      # Biome format + fix
+```
+
+Releases are managed with [changesets](https://github.com/changesets/changesets):
+
+```bash
+pnpm changeset   # describe the change
+pnpm version     # bump versions and changelog
+pnpm release     # publish to npm
+```
+
+## License
+
+[MIT](./LICENSE.txt) © 2026 jsdevlab

package/README.zh-CN.md

@@ -0,0 +1,353 @@
+# @jsdevlab/classnames
+
+[![npm version](https://img.shields.io/npm/v/@jsdevlab/classnames.svg)](https://www.npmjs.com/package/@jsdevlab/classnames)
+[![CI](https://github.com/jsdevlab/classnames/actions/workflows/ci.yml/badge.svg)](https://github.com/jsdevlab/classnames/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE.txt)
+
+[English](./README.md) | **简体中文**
+
+面向 JavaScript 与 TypeScript 的类型安全条件类名工具 —— 框架无关、兼容 classnames，
+默认去重，并支持惰性求值。
+
+## 特性
+
+- **熟悉的 API** —— 与 `classnames` 相同的 `classNames(...)` 调用方式。
+- **默认去重** —— `'a b a'` 会变成 `'a b'`，并保留首次出现的顺序。
+- **惰性函数值** —— `{ active: () => condition }` 在构建类名字符串时才求值。
+- **输入类型丰富** —— 字符串、数字、布尔值、对象、嵌套数组与 `Set`。
+- **可关闭去重的工厂** —— 需要保留重复项时使用 `createClassNames({ unique: false })`。
+- **`cx` 别名** —— 行为完全一致的简短别名。
+- **TypeScript 优先** —— 完整的类型声明与导出的类型。
+- **零运行时依赖** —— 同时提供 ESM 与 CJS 构建，可在任何现代 JS 运行时中使用。
+
+## 安装
+
+```bash
+pnpm add @jsdevlab/classnames
+# 或
+npm install @jsdevlab/classnames
+# 或
+yarn add @jsdevlab/classnames
+```
+
+## 快速开始
+
+```ts
+import { classNames, cx, createClassNames } from '@jsdevlab/classnames';
+
+classNames('btn', 'btn-primary');                                // 'btn btn-primary'
+classNames('btn', { 'btn-primary': true, 'is-loading': false }); // 'btn btn-primary'
+classNames('btn', ['btn-lg', ['rounded']]);                      // 'btn btn-lg rounded'
+classNames('btn', new Set(['btn-lg', 'rounded']));               // 'btn btn-lg rounded'
+classNames('btn', 'btn');                                        // 'btn'
+
+cx('btn', { disabled: true });                                   // 'btn disabled'
+```
+
+本包**没有默认导出**，请使用具名导入：
+
+```ts
+import { classNames } from '@jsdevlab/classnames'; // ✅
+// import classNames from '@jsdevlab/classnames'; // ❌ 不支持
+```
+
+## 用法
+
+### 条件类名
+
+只有当对象的值为真值时，对应的键才会被输出：
+
+```ts
+const isActive = true;
+
+classNames('tab', {
+  'is-active': isActive,
+  'is-disabled': !isActive,
+});
+// 'tab is-active'
+```
+
+### 字符串与数字
+
+数字会被转换为字符串；顶层的 `0` 会被保留：
+
+```ts
+classNames('z', 0, 1, 2); // 'z 0 1 2'
+```
+
+注意，对象值按真值判断，因此其中的 `0` 会被丢弃：
+
+```ts
+classNames({ zero: 0, one: 1 }); // 'one'
+```
+
+### 嵌套数组与 Set
+
+数组会被递归展平，同时也直接支持 `Set`：
+
+```ts
+classNames(['a', ['b', ['c']]]);           // 'a b c'
+classNames(new Set(['a', 'b']));           // 'a b'
+classNames([new Set(['a']), { b: true }]); // 'a b'
+```
+
+### 惰性函数值
+
+作为**对象值**传入的函数会在调用时执行一次。它的返回值只用于判断是否输出对应
+的键 —— 返回值本身不会作为类名：
+
+```ts
+const flags = {
+  'is-active': () => user.active,
+  'is-admin': () => user.roles.includes('admin'),
+};
+
+classNames('user', flags);
+// 两个函数会在此时求值，只有结果为真值的键会被输出。
+```
+
+这样可以让调用处保持简洁，并把开销较大的判断推迟到真正构建类名字符串时。每个
+函数在每次 `classNames` 调用中执行一次；在多次调用间复用同一个对象会重新求值。
+
+### 去重
+
+默认会移除重复类名，并保留首次出现的顺序：
+
+```ts
+classNames('a', 'b', 'a', ['b', { a: true }]); // 'a b'
+```
+
+### 保留重复项
+
+创建一个关闭去重的工厂函数：
+
+```ts
+import { createClassNames } from '@jsdevlab/classnames';
+
+const join = createClassNames({ unique: false });
+
+join('a', 'a');        // 'a a'
+classNames('a', 'a');  // 'a'
+```
+
+选项在创建工厂时解析，返回的函数会绑定这些选项：
+
+```ts
+const cls = createClassNames(); // unique 默认为 true
+cls('a', 'a');                  // 'a'
+```
+
+### React
+
+```tsx
+import { cx } from '@jsdevlab/classnames';
+import type { ReactNode } from 'react';
+
+interface ButtonProps {
+  primary?: boolean;
+  loading?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+export function Button({
+  primary,
+  loading,
+  className,
+  children,
+}: ButtonProps) {
+  return (
+    <button
+      className={cx(
+        'btn',
+        { 'btn-primary': primary, 'is-loading': loading },
+        className,
+      )}
+      disabled={loading}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { classNames } from '@jsdevlab/classnames';
+
+defineProps<{ active?: boolean; disabled?: boolean }>();
+</script>
+
+<template>
+  <button
+    :class="classNames('tab', { 'is-active': active, 'is-disabled': disabled })"
+  >
+    <slot />
+  </button>
+</template>
+```
+
+由于本库与框架无关，同样的函数也可用于 Svelte、Solid、Angular、原生 DOM 代码，
+或任何其他 JavaScript 运行环境。
+
+## API
+
+### `classNames(...values: ClassValue[]): string`
+
+接收任意组合的受支持值，返回以单个空格连接的类名字符串。没有有效类名时返回
+`''`：
+
+```ts
+classNames();                       // ''
+classNames(null, false, undefined); // ''
+```
+
+### `cx`
+
+`classNames` 的别名，签名与行为完全一致：
+
+```ts
+cx('a', { b: true }); // 'a b'
+```
+
+### `createClassNames(options?: ClassNamesOptions): typeof classNames`
+
+返回一个绑定指定选项的 `classNames` 风格函数。
+
+#### `ClassNamesOptions`
+
+| 选项     | 类型      | 默认值 | 说明                                   |
+| -------- | --------- | ------ | -------------------------------------- |
+| `unique` | `boolean` | `true` | 对类名去重，保留首次出现的顺序。       |
+
+```ts
+const defaultJoin = createClassNames();              // unique: true
+const keepAll = createClassNames({ unique: false }); // 保留重复项
+```
+
+## 类型
+
+所有类型均已导出：
+
+```ts
+export type ClassValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | ClassObject
+  | ClassValue[]
+  | Set<ClassValue>;
+
+export interface ClassObject {
+  [key: string]: ClassValue | (() => ClassValue);
+}
+
+export interface ClassNamesOptions {
+  unique?: boolean;
+}
+```
+
+## 行为参考
+
+| 输入                                                           | 输出       |
+| -------------------------------------------------------------- | ---------- |
+| `classNames('a', 'b')`                                         | `'a b'`    |
+| `classNames('a', '', null, undefined, false, true)`            | `'a'`      |
+| `classNames(0, 1)`                                             | `'0 1'`    |
+| `classNames({ a: true, b: false, c: 1, d: 0 })`                | `'a c'`    |
+| `classNames(['a', [{ b: true }]])`                             | `'a b'`    |
+| `classNames(new Set(['a', 'b']))`                              | `'a b'`    |
+| `classNames({ active: () => true, hidden: () => false })`      | `'active'` |
+| `classNames('a', 'b', 'a')`                                    | `'a b'`    |
+| `createClassNames({ unique: false })('a', 'a')`                | `'a a'`    |
+| `classNames()`                                                 | `''`       |
+
+## 注意事项与边界情况
+
+- 类名始终使用**单个空格**连接，不提供自定义分隔符选项。
+- 去重按完全相同的字符串比较，区分大小写，且**不会**拆分字符串：
+  `classNames('a b', 'b')` 返回 `'a b b'`。
+- 顶层 `0` 会被保留（`classNames(0)` → `'0'`），但对象值中的 `0` 为假值，会被
+  丢弃（`{ a: 0 }` → `''`）。
+- `true` 和 `false` 作为值会被忽略；只有对象的键会产生输出。
+- 函数**只能作为对象值**使用；直接作为顶层参数传入的函数会被忽略。
+- 函数的返回值只用于判断真值，不会成为类名（`{ a: () => 'foo' }` → `'a'`）。
+- 输出顺序与输入顺序一致；对象的键遵循 `Object.entries` 的顺序。去重保留首次
+  出现的位置。
+- `null`、`undefined` 和空字符串会被忽略。
+
+## 与 classnames 的兼容性
+
+在大多数场景下，`@jsdevlab/classnames` 可以直接替代 `classnames`：
+
+```diff
+-import classNames from 'classnames';
++import { classNames } from '@jsdevlab/classnames';
+```
+
+| 能力                                | `classnames`                         | `@jsdevlab/classnames`                    |
+| ----------------------------------- | ------------------------------------ | ----------------------------------------- |
+| 字符串 / 数字                       | ✅                                   | ✅                                        |
+| 值为真值的对象                      | ✅                                   | ✅                                        |
+| 嵌套数组                            | ✅                                   | ✅                                        |
+| 跳过 `null` / `undefined` / `false` / `''` | ✅                            | ✅                                        |
+| `Set` 输入                          | —                                    | ✅                                        |
+| 对象中的函数值                      | 不求值（函数本身为真值）             | 在调用时求值                              |
+| 移除重复项                          | 通过 `classnames/dedupe`             | 默认行为                                  |
+| 保留重复项                          | 默认行为                             | `createClassNames({ unique: false })`     |
+| 自定义分隔符                        | —                                    | —                                         |
+| 默认导出                            | ✅                                   | —（仅具名导出）                           |
+
+如果你的代码依赖 `classnames` 默认保留重复项的行为，可以绑定自己的实例：
+
+```ts
+import { createClassNames } from '@jsdevlab/classnames';
+
+const classNames = createClassNames({ unique: false });
+```
+
+## 模块格式
+
+| 格式       | 文件               |
+| ---------- | ------------------ |
+| ESM        | `dist/index.js`    |
+| CommonJS   | `dist/index.cjs`   |
+| TypeScript | `dist/index.d.ts`  |
+
+```ts
+// ESM
+import { classNames } from '@jsdevlab/classnames';
+
+// CommonJS
+const { classNames } = require('@jsdevlab/classnames');
+```
+
+本包没有运行时依赖，可在现代浏览器、Node.js、Bun 与 Deno 中使用。
+
+## 开发
+
+需要 Node.js ≥ 24.19 与 pnpm 12.18。
+
+```bash
+pnpm install
+pnpm test        # tsc --noEmit + rstest
+pnpm build       # rslib 构建 → dist/
+pnpm check       # Biome 检查并修复
+pnpm format      # Biome 格式化并修复
+```
+
+发布流程使用 [changesets](https://github.com/changesets/changesets)：
+
+```bash
+pnpm changeset   # 描述本次变更
+pnpm version     # 更新版本号与 CHANGELOG
+pnpm release     # 发布到 npm
+```
+
+## 许可证
+
+[MIT](./LICENSE.txt) © 2026 jsdevlab

package/dist/index.cjs

@@ -0,0 +1,91 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+const DEFAULT_OPTIONS = {
+    unique: true
+};
+const resolveOptions = (options)=>({
+        unique: options?.unique ?? DEFAULT_OPTIONS.unique
+    });
+const collect = (value, parts)=>{
+    if (null == value || false === value || true === value) return;
+    if ('string' == typeof value || 'number' == typeof value) {
+        if ('' !== value) parts.push(String(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)collect(item, parts);
+        return;
+    }
+    if (value instanceof Set) {
+        for (const item of value)collect(item, parts);
+        return;
+    }
+    for (const [key, raw] of Object.entries(value)){
+        const v = 'function' == typeof raw ? raw() : raw;
+        if (v) parts.push(key);
+    }
+};
+const classNamesImpl = (values, options)=>{
+    const parts = [];
+    for (const value of values)collect(value, parts);
+    if (!options.unique) return parts.join(' ');
+    const seen = new Set();
+    const unique = [];
+    for (const part of parts)if (!seen.has(part)) {
+        seen.add(part);
+        unique.push(part);
+    }
+    return unique.join(' ');
+};
+function classNames(...values) {
+    return classNamesImpl(values, resolveOptions());
+}
+const cx = classNames;
+function createClassNames(options) {
+    const resolved = resolveOptions(options);
+    return (...values)=>classNamesImpl(values, resolved);
+}
+__webpack_require__.d(__webpack_exports__, {
+    classNames: ()=>classNames,
+    createClassNames: ()=>createClassNames
+}, {
+    cx: cx
+});
+exports.classNames = __webpack_exports__.classNames;
+exports.createClassNames = __webpack_exports__.createClassNames;
+exports.cx = __webpack_exports__.cx;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "classNames",
+    "createClassNames",
+    "cx"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @jsdevlab/classnames — a type-safe conditional class name utility (framework-agnostic).
+ *
+ * classnames-compatible, plus enhancements:
+ * - Basics: strings/numbers/objects (truthy keys)/nested arrays/Sets
+ * - Enhancements: lazily evaluated function values (`{ active: () => cond }`),
+ *   deduplication by default (order preserved), dedup toggle factory (createClassNames)
+ */
+/** Object value: a plain value or a lazily evaluated function. */
+export type ClassValue = string | number | boolean | null | undefined | ClassObject | ClassValue[] | Set<ClassValue>;
+export interface ClassObject {
+    [key: string]: ClassValue | (() => ClassValue);
+}
+/**
+ * Options for the class name factory.
+ *
+ * Class names always join with a space (the only separator CSS accepts),
+ * so only deduplication is configurable.
+ *
+ * @example
+ * createClassNames({ unique: false })
+ */
+export interface ClassNamesOptions {
+    /** Whether to deduplicate (order preserved), defaults to true. */
+    unique?: boolean;
+}
+/**
+ * Conditional class names (classnames-compatible + enhanced); `cx` is an alias.
+ *
+ * @param values Class values: strings/numbers, objects with truthy keys, nested arrays,
+ * Sets, and lazily evaluated function values.
+ * @returns The joined class name string.
+ * @example
+ * classNames('a', 'b', 'c')                          // 'a b c'
+ * classNames('a', { b: true, c: false }, ['d'])      // 'a b d'
+ * classNames({ active: () => isActive })             // 'active' when isActive is truthy
+ * classNames('a', 'b', 'a')                          // 'a b' (deduplicated, order preserved)
+ */
+export declare function classNames(...values: ClassValue[]): string;
+/**
+ * Short alias of `classNames` (identical signature and behavior).
+ *
+ * @example
+ * cx('a', { b: true })   // 'a b'
+ */
+export declare const cx: typeof classNames;
+/**
+ * Factory with a dedup toggle.
+ *
+ * @param options Dedup options.
+ * @returns A `classNames`-like function bound to the given options.
+ * @example
+ * const keep = createClassNames({ unique: false })
+ * keep('a', 'a')              // 'a a'
+ */
+export declare function createClassNames(options?: ClassNamesOptions): typeof classNames;

package/dist/index.js

@@ -0,0 +1,46 @@
+const DEFAULT_OPTIONS = {
+    unique: true
+};
+const resolveOptions = (options)=>({
+        unique: options?.unique ?? DEFAULT_OPTIONS.unique
+    });
+const collect = (value, parts)=>{
+    if (null == value || false === value || true === value) return;
+    if ('string' == typeof value || 'number' == typeof value) {
+        if ('' !== value) parts.push(String(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)collect(item, parts);
+        return;
+    }
+    if (value instanceof Set) {
+        for (const item of value)collect(item, parts);
+        return;
+    }
+    for (const [key, raw] of Object.entries(value)){
+        const v = 'function' == typeof raw ? raw() : raw;
+        if (v) parts.push(key);
+    }
+};
+const classNamesImpl = (values, options)=>{
+    const parts = [];
+    for (const value of values)collect(value, parts);
+    if (!options.unique) return parts.join(' ');
+    const seen = new Set();
+    const unique = [];
+    for (const part of parts)if (!seen.has(part)) {
+        seen.add(part);
+        unique.push(part);
+    }
+    return unique.join(' ');
+};
+function classNames(...values) {
+    return classNamesImpl(values, resolveOptions());
+}
+const cx = classNames;
+function createClassNames(options) {
+    const resolved = resolveOptions(options);
+    return (...values)=>classNamesImpl(values, resolved);
+}
+export { classNames, createClassNames, cx };

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@jsdevlab/classnames",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "private": false,
+  "description": "Type-safe classnames utility — conditional classes with lazy evaluation, dedup, and separator factory. Framework-agnostic.",
+  "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsdevlab/classnames.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "README.zh-CN.md"],
+  "scripts": {
+    "build": "rslib",
+    "changeset": "changeset",
+    "check": "biome check --write",
+    "dev": "rslib --watch",
+    "format": "biome format --write",
+    "prepare": "simple-git-hooks",
+    "release": "changeset publish",
+    "test": "tsc --noEmit && rstest",
+    "test:watch": "rstest --watch",
+    "version": "changeset version"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm check",
+    "pre-push": "pnpm format"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.6",
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^3.0.1",
+    "@rslib/core": "^0.23.2",
+    "@rstest/adapter-rslib": "^0.11.9",
+    "@rstest/core": "^0.11.9",
+    "@rstest/coverage-v8": "^0.11.9",
+    "@types/node": "^24.13.3",
+    "simple-git-hooks": "^2.14.0",
+    "typescript": "^6.0.3"
+  },
+  "packageManager": "pnpm@12.18.0+sha512.9d7882d5dc82147ecfc4e062aa34834e0ad0296710a1837a1115ae012127d36b7109e321ac1598a1dd0a65597681b1e99917e12ed0d749eae91187943363beb3",
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=24.19.0 <27.0.0",
+      "onFail": "download"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}