@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/color/xyz/internal.ts

@@ -0,0 +1,23 @@
+import {
+  internalAssertAlpha,
+  internalAssertNonNegativeFinite,
+} from "../internal.ts"
+
+import type { XyzColorValue } from "../types.ts"
+
+/**
+ * 规范化 XYZ 颜色值结构。
+ */
+export const internalNormalizeXyzColorValue = (color: XyzColorValue): XyzColorValue => {
+  internalAssertNonNegativeFinite(color.x, "Color channel x")
+  internalAssertNonNegativeFinite(color.y, "Color channel y")
+  internalAssertNonNegativeFinite(color.z, "Color channel z")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    x: color.x,
+    y: color.y,
+    z: color.z,
+    alpha: color.alpha,
+  }
+}

package/src/css/README.md

@@ -0,0 +1,93 @@
+# CSS
+
+## Description
+
+CSS 模块提供围绕 CSS 类名集合（class set）的表达、转换和组合能力，用于在字符串、数组、对象三种常见表示之间建立稳定、可解释且可组合的公共语义。
+
+它关注的不是样式体系本身，而是“类名集合如何被表达和变换”。对象表示除了能表达已启用类名，还可以显式保留值为 `false` 的键，以承载“已知但未启用”的状态。
+
+## For Understanding
+
+理解 CSS 模块时，应把它看成“类名集合模型”，而不是“字符串拼接工具”。这个模块要解决的是不同输入形态之间的语义对齐问题：同一组类名可能来自 `.foo.bar`、`foo bar`、`["foo", "bar"]` 或 `{ foo: true, bar: false }`，进入系统后，应尽快被整理成清楚、稳定、可继续变换的集合语义。
+
+三种表示的语义并不完全相同：
+
+- 字符串与数组主要表达“当前启用中的类名集合”。
+- 对象既能表达启用状态，也能保留值为 `false` 的键，从而表达“已知但未启用”的状态信息。
+- 空类名本身不承载有效样式语义，应在公共转换路径中尽早过滤。
+
+因此，这个模块追求的不是机械的完全可逆，而是转换结果为什么会这样始终容易解释。如果某个转换会丢失对象中 `false` 键这类附加状态，那是表示层语义差异，而不是实现缺陷。
+
+## For Using
+
+当应用需要在组件层、渲染层、样式工具层之间传递类名集合时，可以使用这个模块统一管理类名表达，而不是在调用点反复手写拆分、拼接、去重和真假值过滤。
+
+当前公共能力大致可以按以下几类理解：
+
+- 类名表示类型：用于区分 `ClassString`、`ClassArray`、`ClassObject` 以及三者联合的输入形态。
+- 表示间转换：用于在字符串、数组、对象之间显式切换，并根据目标表示保留其应有语义。
+- 统一归一化：用于把混合输入整理成某一种稳定目标表示，减少下游接口摩擦。
+- 前缀处理：用于给类名补前缀、移除前缀，适合组件库或命名空间约定场景。
+- 集合操作：用于添加、移除、切换、替换、判断是否包含某组类名。
+
+这个模块不适合承载样式命名规范、主题系统、选择器优先级策略或任何特定框架的样式约定。它只负责类名集合语义，不负责更高层的样式设计决策。
+
+## For Contributing
+
+贡献 CSS 模块时，应优先判断新增能力是否真正表达了稳定的类名集合语义，而不是某个框架、某个模板语法或某种局部命名习惯的便捷包装。只有前者才适合作为长期公共 API。
+
+在扩展时，应优先遵守以下边界：
+
+- 公共能力应围绕类名集合的表达、转换、组合和集合操作展开。
+- 不要把具体框架的模板语法、渲染约定或样式系统规则直接写入模块公共语义。
+- 表示之间的转换应优先保证结果可解释，而不是追求表面上的完全可逆。
+- 对象表示中的 `false` 键是有意义的显式状态；字符串与数组表示则只表达启用中的类名。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/css/internal.ts`；若当前没有必要，不必为了形式强行拆分。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 涉及字符串解析、空白规整、点号分隔、真假值过滤等规则时，应让行为保持直白、可预测，而不要让调用方猜测隐含规范。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的类名集合语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/css`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/css/<sub-module-name>`。
+- 测试应重点覆盖三种表示之间的语义差异，尤其是空类名过滤、对象 `false` 键保留与集合操作结果是否可解释。

package/src/css/class.ts

@@ -0,0 +1,559 @@
+/**
+ * 表示以空格分隔的 CSS 类名字串。
+ */
+export type ClassString = string
+
+/**
+ * 表示按顺序保存的 CSS 类名数组。
+ */
+export type ClassArray = string[]
+
+/**
+ * 表示以类名为键、以启用状态为值的 CSS 类名对象。
+ *
+ * 该表示允许保留值为 `false` 的键，以表达已知但当前未启用的类名状态。
+ */
+export type ClassObject = Record<string, boolean>
+
+/**
+ * 表示 CSS 类名的三种公共表达形式：字符串、数组或对象。
+ */
+export type ClassUnion = ClassString | ClassArray | ClassObject
+
+/**
+ * 规范化类名字串，使其适合作为统一的字符串表示。
+ *
+ * 该函数会将 `.` 视为分隔符，将连续空白折叠为一个空格，并移除首尾空白。
+ *
+ * @example
+ * ```
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example1 = neatenClassString('mobius-base mobius-theme--light')
+ *
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example2 = neatenClassString('.mobius-base.mobius-theme--light')
+ *
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example3 = neatenClassString('  .mobius-base   mobius-theme--light  ')
+ * ```
+ */
+export const neatenClassString = (str: string): ClassString => {
+  const classString = str.replaceAll('.', ' ').replaceAll(/\s+/g, ' ').trim()
+  return classString
+}
+
+/**
+ * 将类名字串转换为类名数组。
+ *
+ * 输入会先经过 `neatenClassString` 规范化，再按空格拆分，并移除空项。
+ *
+ * @example
+ * ```
+ * // Expect: ['mobius-base', 'mobius-theme--light']
+ * const example1 = classStringToClassArray('mobius-base mobius-theme--light')
+ *
+ * // Expect: ['mobius-base', 'mobius-theme--light']
+ * const example2 = classStringToClassArray('.mobius-base.mobius-theme--light')
+ *
+ * // Expect: ['mobius-base', 'mobius-theme--light']
+ * const example3 = classStringToClassArray('  .mobius-base   mobius-theme--light  ')
+ * ```
+ */
+export const classStringToClassArray = (str: ClassString): ClassArray => {
+  const classArray = neatenClassString(str).split(' ').filter(s => s.length !== 0)
+  return classArray
+}
+
+/**
+ * 将类名数组转换为布尔对象表示。
+ *
+ * 数组中的每个非空类名都会映射为值为 `true` 的对象键。
+ *
+ * @example
+ * ```
+ * // Expect: { 'mobius-base': true, 'mobius-theme--light': true }
+ * const example1 = classArrayToClassObject(['mobius-base', 'mobius-theme--light'])
+ *
+ * // Expect: { 'mobius-base': true }
+ * const example2 = classArrayToClassObject(['mobius-base', ''])
+ *
+ * // Expect: {}
+ * const example3 = classArrayToClassObject([])
+ * ```
+ */
+export const classArrayToClassObject = (arr: ClassArray): ClassObject => {
+  const classObject: ClassObject = {}
+  arr.filter(s => s.length !== 0).forEach(s => {
+    classObject[s] = true
+  })
+  return classObject
+}
+
+/**
+ * 将类名字串直接转换为布尔对象表示。
+ *
+ * 该函数会先把字符串拆分为类名数组，再将每个类名映射为值为 `true` 的对象键。
+ *
+ * @example
+ * ```
+ * // Expect: { 'mobius-base': true, 'mobius-theme--light': true }
+ * const example1 = classStringToClassObject('mobius-base mobius-theme--light')
+ *
+ * // Expect: { 'mobius-base': true, 'mobius-theme--light': true }
+ * const example2 = classStringToClassObject('.mobius-base.mobius-theme--light')
+ * ```
+ */
+export const classStringToClassObject = (str: ClassString): ClassObject => {
+  const classArray = classStringToClassArray(str)
+  const classObject = classArrayToClassObject(classArray)
+  return classObject
+}
+
+/**
+ * 将布尔对象表示转换为类名数组。
+ *
+ * 值为 `false` 的类名和空类名会被忽略。
+ *
+ * @example
+ * ```
+ * // Expect: ['active', 'primary']
+ * const example1 = classObjectToClassArray({ active: true, disabled: false, primary: true })
+ *
+ * // Expect: ['active']
+ * const example2 = classObjectToClassArray({ '': true, active: true, disabled: false })
+ * ```
+ */
+export const classObjectToClassArray = (obj: ClassObject): ClassArray => {
+  const classArray: string[] = []
+  Object.entries(obj)
+    .filter(([key, value]) => key.length !== 0 && value)
+    .forEach(([key, _]) => {
+      classArray.push(key)
+    })
+  return classArray
+}
+
+/**
+ * 将类名数组按空格连接为类名字串。
+ *
+ * 空字符串项会被过滤，以避免产生多余空格。
+ *
+ * @example
+ * ```
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example1 = classArrayToClassString(['mobius-base', 'mobius-theme--light'])
+ *
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example2 = classArrayToClassString(['mobius-base', '', 'mobius-theme--light'])
+ * ```
+ */
+export const classArrayToClassString = (arr: ClassArray): ClassString => {
+  const classString = arr.filter(s => s.length !== 0).join(' ')
+  return classString
+}
+
+/**
+ * 将布尔对象表示转换为类名字串。
+ *
+ * 该函数会忽略值为 `false` 的类名和空类名，并保留其余类名的迭代顺序。
+ *
+ * @example
+ * ```
+ * // Expect: 'active primary'
+ * const example1 = classObjectToClassString({ active: true, disabled: false, primary: true })
+ *
+ * // Expect: 'active'
+ * const example2 = classObjectToClassString({ '': true, active: true, disabled: false })
+ * ```
+ */
+export const classObjectToClassString = (obj: ClassObject): ClassString => {
+  const classArray = classObjectToClassArray(obj)
+  const classString = classArrayToClassString(classArray)
+  return classString
+}
+
+/**
+ * 将任意公共类名表示转换为字符串表示。
+ *
+ * 如果输入本身已经是字符串，则原样返回；数组和对象会分别经过对应的序列化流程。
+ *
+ * @example
+ * ```
+ * // Expect: '  .button   active  '
+ * const example1 = toClassString('  .button   active  ')
+ *
+ * // Expect: 'button active'
+ * const example2 = toClassString(['button', 'active'])
+ *
+ * // Expect: 'button active'
+ * const example3 = toClassString({ button: true, active: true, disabled: false })
+ * ```
+ */
+export const toClassString = (tar: ClassUnion): ClassString => {
+  if (typeof tar === 'string') {
+    return tar
+  } else if (Array.isArray(tar)) {
+    return classArrayToClassString(tar)
+  } else {
+    return classObjectToClassString(tar)
+  }
+}
+
+/**
+ * 将任意公共类名表示转换为数组表示。
+ *
+ * 如果输入本身已经是数组，则会在过滤空类名后返回一个浅拷贝，以避免调用方共享同一数组实例。
+ *
+ * @example
+ * ```
+ * // Expect: ['button', 'active']
+ * const example1 = toClassArray('button active')
+ *
+ * // Expect: ['button', 'active']
+ * const example2 = toClassArray(['button', 'active'])
+ *
+ * // Expect: ['button', 'active']
+ * const example3 = toClassArray({ button: true, disabled: false, active: true })
+ * ```
+ */
+export const toClassArray = (tar: ClassUnion): ClassArray => {
+  if (typeof tar === 'string') {
+    return classStringToClassArray(tar)
+  } else if (Array.isArray(tar)) {
+    return tar.filter(s => s.length !== 0)
+  } else {
+    return classObjectToClassArray(tar)
+  }
+}
+
+/**
+ * 将任意公共类名表示转换为对象表示。
+ *
+ * 如果输入本身已经是对象，则会在过滤空类名后返回一个浅拷贝，以避免外部直接共享内部结果。
+ *
+ * @example
+ * ```
+ * // Expect: { button: true, active: true }
+ * const example1 = toClassObject('button active')
+ *
+ * // Expect: { button: true, active: true }
+ * const example2 = toClassObject(['button', 'active'])
+ *
+ * // Expect: { button: true, active: false }
+ * const example3 = toClassObject({ button: true, active: false, '': true })
+ * ```
+ */
+export const toClassObject = (tar: ClassUnion): ClassObject => {
+  if (typeof tar === 'string') {
+    return classStringToClassObject(tar)
+  } else if (Array.isArray(tar)) {
+    return classArrayToClassObject(tar)
+  } else {
+    const classObject: ClassObject = {}
+    Object.entries(tar).forEach(([key, value]) => {
+      if (key.length !== 0) {
+        classObject[key] = value
+      }
+    })
+    return classObject
+  }
+}
+
+/**
+ * 按目标值的外部表示，将类名集合格式化为相同形态。
+ *
+ * 该函数适合在内部统一按对象进行计算后，再把结果还原为调用方原本使用的表示。
+ *
+ * @example
+ * ```
+ * // Expect: 'button active'
+ * const example1 = formatClassToTarget('', ['button', 'active'])
+ *
+ * // Expect: ['button', 'active']
+ * const example2 = formatClassToTarget([], 'button active')
+ *
+ * // Expect: { button: true, active: true }
+ * const example3 = formatClassToTarget({}, ['button', 'active'])
+ * ```
+ */
+export const formatClassToTarget = <T extends ClassUnion>(target: T, cls: ClassUnion): T => {
+  if (typeof target === 'string') {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return toClassString(cls) as T
+  } else if (Array.isArray(target)) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return toClassArray(cls) as T
+  } else {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return toClassObject(cls) as T
+  }
+}
+
+/**
+ * 为类名集合中的每一项补上指定前缀。
+ *
+ * 已经带有该前缀的类名会保持不变。
+ *
+ * @example
+ * ```
+ * // Expect: 'pm-button pm-active'
+ * const example1 = prefixClassWith('pm-', 'button active')
+ *
+ * // Expect: ['pm-button', 'pm-active']
+ * const example2 = prefixClassWith('pm-', ['button', 'pm-active'])
+ *
+ * // Expect: { 'pm-button': true, 'pm-active': true }
+ * const example3 = prefixClassWith('pm-', { button: true, 'pm-active': true })
+ * ```
+ */
+export const prefixClassWith = <T extends ClassUnion>(prefix: string, cls: T): T => {
+  if (typeof cls === 'string') {
+    const classArray = classStringToClassArray(cls).map(item =>
+      item.startsWith(prefix) ? item : `${prefix}${item}`
+    )
+    const classString = classArrayToClassString(classArray)
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classString as T
+  } else if (Array.isArray(cls)) {
+    const classArray = cls.filter(item => item.length !== 0).map(item =>
+      item.startsWith(prefix) ? item : `${prefix}${item}`
+    )
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classArray as T
+  } else {
+    const classObject: ClassObject = {}
+    Object.entries(cls).forEach(([key, value]) => {
+      if (key.length === 0) {
+        return
+      }
+      const _key = key.startsWith(prefix) ? key : `${prefix}${key}`
+      classObject[_key] = value === true
+    })
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classObject as T
+  }
+}
+
+/**
+ * 从类名集合中的每一项移除指定前缀。
+ *
+ * 不带该前缀的类名会保持原样。
+ *
+ * @example
+ * ```
+ * // Expect: 'button active plain'
+ * const example1 = removePrefixOfClass('pm-', 'pm-button pm-active plain')
+ *
+ * // Expect: ['button', 'plain']
+ * const example2 = removePrefixOfClass('pm-', ['pm-button', 'plain'])
+ *
+ * // Expect: { button: true, plain: false }
+ * const example3 = removePrefixOfClass('pm-', { 'pm-button': true, plain: false, 'pm-': true })
+ * ```
+ */
+export const removePrefixOfClass = <T extends ClassUnion>(prefix: string, cls: T): T => {
+  if (typeof cls === 'string') {
+    const classArray = classStringToClassArray(cls).map(item => {
+      if (item.startsWith(prefix)) {
+        return item.slice(prefix.length)
+      }
+      return item
+    })
+    const classString = classArrayToClassString(classArray)
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classString as T
+  } else if (Array.isArray(cls)) {
+    const classArray = cls.filter(item => item.length !== 0).map(item => {
+      if (item.startsWith(prefix)) {
+        return item.slice(prefix.length)
+      }
+      return item
+    })
+    const filteredClassArray = classArray.filter(item => item.length !== 0)
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return filteredClassArray as T
+  } else {
+    const classObject: ClassObject = {}
+    Object.entries(cls).forEach(([key, value]) => {
+      if (key.length === 0) {
+        return
+      }
+      const _key = key.startsWith(prefix) ? key.slice(prefix.length) : key
+      if (_key.length !== 0) {
+        classObject[_key] = value === true
+      }
+    })
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classObject as T
+  }
+}
+
+/**
+ * 向目标类名集合中加入新的类名。
+ *
+ * 当目标与新增项都包含同名类时，以新增项转换后的对象表示为准。
+ *
+ * @example
+ * ```
+ * // Expect: 'button active primary'
+ * const example1 = addClass('button', 'active primary')
+ *
+ * // Expect: ['button', 'active', 'primary']
+ * const example2 = addClass(['button'], { active: true, primary: true })
+ * ```
+ */
+export const addClass = <T extends ClassUnion>(target: T, added: ClassUnion): T => {
+  const targetClassObj = toClassObject(target)
+  const addedClassObj = toClassObject(added)
+  const resClassObj = { ...targetClassObj, ...addedClassObj }
+  const result = formatClassToTarget(target, resClassObj)
+  return result
+}
+
+/**
+ * 从目标类名集合中移除指定类名。
+ *
+ * 该函数会把待移除项标记为 `false`，再按目标形态输出结果。
+ *
+ * @example
+ * ```
+ * // Expect: 'button primary'
+ * const example1 = removeClass('button active primary', 'active')
+ *
+ * // Expect: { button: true, active: false }
+ * const example2 = removeClass({ button: true, active: true }, ['active'])
+ * ```
+ */
+export const removeClass = <T extends ClassUnion>(target: T, removed: ClassUnion): T => {
+  const targetClassObj = toClassObject(target)
+  const removedClassObj = toClassObject(removed)
+  Object.keys(removedClassObj).forEach(key => {
+    removedClassObj[key] = false
+  })
+  const resClassObj = { ...targetClassObj, ...removedClassObj }
+  const result = formatClassToTarget(target, resClassObj)
+  return result
+}
+
+/**
+ * 切换目标类名集合中指定类名的启用状态。
+ *
+ * 已存在的类名会被关闭，不存在的类名会被开启。
+ *
+ * @example
+ * ```
+ * // Expect: 'button primary'
+ * const example1 = toggleClass('button active', 'active primary')
+ *
+ * // Expect: { button: true, primary: true }
+ * const example2 = toggleClass({ button: true, active: true }, ['active', 'primary'])
+ * ```
+ */
+export const toggleClass = <T extends ClassUnion>(target: T, toggled: ClassUnion): T => {
+  const targetClassObj = toClassObject(target)
+  const toggledClassArr = toClassArray(toggled)
+  toggledClassArr.forEach((cls) => {
+    // oxlint-disable-next-line strict-boolean-expressions
+    targetClassObj[cls] = !targetClassObj[cls]
+  })
+  const result = formatClassToTarget(target, targetClassObj)
+  return result
+}
+
+/**
+ * 替换目标类名集合中的类名。
+ *
+ * `replaced` 支持三种形式：
+ * - 字符串：仅移除对应类名。
+ * - 字符串数组：逐项移除对应类名。
+ * - 元组数组：按 `[from, to]` 的形式逐项替换类名。
+ * - 对象：按键值对执行替换，值为空字符串时表示删除。
+ *
+ * @example
+ * ```
+ * // Expect: 'button selected'
+ * const example1 = replaceClass('button active', [['active', 'selected']])
+ *
+ * // Expect: ['button', 'selected']
+ * const example2 = replaceClass(['button', 'active'], { active: 'selected' })
+ *
+ * // Expect: { button: true, active: false }
+ * const example3 = replaceClass({ button: true, active: true }, 'active')
+ * ```
+ */
+export const replaceClass = <T extends ClassUnion>(
+  target: T,
+  replaced: Record<string, string> | string | string[] | Array<[string, string]>,
+): T => {
+  if (typeof replaced === 'string') {
+    return removeClass(target, replaced)
+  }
+
+  const targetClassObj = toClassObject(target)
+
+  if (Array.isArray(replaced)) {
+    for (const item of replaced) {
+      if (typeof item === 'string') {
+        const fromValue = targetClassObj[item]
+
+        if (fromValue !== undefined) {
+          // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+          delete targetClassObj[item]
+        }
+
+        continue
+      }
+
+      const [from, to] = item
+      const fromValue = targetClassObj[from]
+
+      if (fromValue !== undefined) {
+        if (to !== '') {
+          targetClassObj[to] = fromValue
+        }
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete targetClassObj[from]
+      }
+    }
+
+    return formatClassToTarget(target, targetClassObj)
+  }
+
+  for (const [from, rawTo] of Object.entries(replaced)) {
+    if (typeof rawTo !== 'string') {
+      continue
+    }
+
+    const fromValue = targetClassObj[from]
+
+    if (fromValue !== undefined) {
+      if (rawTo !== '') {
+        targetClassObj[rawTo] = fromValue
+      }
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+      delete targetClassObj[from]
+    }
+  }
+
+  return formatClassToTarget(target, targetClassObj)
+}
+
+/**
+ * 判断目标类名集合是否完整包含另一组类名。
+ *
+ * 只有当 `contained` 中的每个类名都存在于 `target` 中时，才会返回 `true`。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = containClass('button active', 'button active primary')
+ *
+ * // Expect: false
+ * const example2 = containClass(['button', 'missing'], { button: true, active: true })
+ * ```
+ */
+export const containClass = (contained: ClassUnion, target: ClassUnion): boolean => {
+  const containedClassArr = toClassArray(contained)
+  const targetClassArr = toClassArray(target)
+  return containedClassArr.every(item => targetClassArr.includes(item))
+}

package/src/css/index.ts

@@ -0,0 +1 @@
+export * from "./class.ts"