@composy/shared-core

框架无关的 LDesign 共享核心包。该包是 packages/shared 的主要功能实现层， Vue/React/Lit/Vanilla 等适配包都应优先复用这里的工具、协议和类型。

能力范围

| 模块 | 说明 | 入口路径 | |------|------|----------| | utils | 数组、字符串、树、校验、格式化、缓存、事件总线、HTTP、DOM、性能与 storage 工具 | @composy/shared-core/utils | | protocols | 选择器等跨框架协议类型与预设 | @composy/shared-core/protocols | | types | 业务通用类型、深度工具类型、设备和表单类型 | @composy/shared-core/types | | icons | LDesign 图标名到 Lucide 图标名的映射 | @composy/shared-core/icons | | web-components | 框架无关 Web Component（ldesign-view-state） | @composy/shared-core/web-components | | error-handler | 统一错误处理（PluginError、ErrorHandler） | @composy/shared-core/error-handler |

工具函数一览

数组工具 (utils/array)

• unique / uniqueBy — 去重
• chunk / groupBy — 分割与分组
• flatten / flattenDeep — 扁平化
• intersection / union / difference — 集合运算
• shuffle / sample — 随机操作
• compact — 移除假值
• sum / average / max / min — 数学运算

字符串工具 (utils/string)

• capitalize / camelCase / kebabCase / snakeCase — 大小写转换
• template / templateReplacer — 模板字符串
• truncate / padStart / padEnd — 截断与填充
• escapeHtml / unescapeHtml — HTML 转义

DOM 工具 (utils/dom)

• on / off / once / clickOut — 事件绑定
• hasClass / addClass / removeClass — 类名操作
• getScrollContainer / scrollTo / scrollSelectedIntoView — 滚动控制
• elementInViewport / isTextEllipsis / isFixed — 元素检测

校验工具 (utils/validate)

• isValidEmail / isValidPhone / isValidUrl / isValidIPv4 / isValidIPv6 — 格式校验
• validatePassword / isStrongPassword — 密码强度
• isNumeric / isInteger / isFloat / isPositive — 数值校验
• isEmpty / isEqual / deepClone — 值操作

缓存工具 (utils/cache)

• createLRUCache — LRU 缓存
• memoize — 函数记忆化
• cached — 装饰器缓存

事件总线 (utils/eventBus)

• EventBus — 类型安全的事件总线

Storage 工具 (utils/storage)

• readStorageValue / writeStorageValue / removeStorageValue — SSR 安全存储读写
• resolveBrowserStorage — 浏览器存储解析
• parseStorageEventValue — storage 事件解析

Storage 工具示例

import {
  createJsonStorageSerializer,
  readStorageValue,
  writeStorageValue,
} from '@composy/shared-core/utils'

const serializer = createJsonStorageSerializer<{ theme: string }>()

writeStorageValue(
  {
    defaultValue: { theme: 'light' },
    key: 'settings',
    serializer,
    storage: localStorage,
  },
  { theme: 'dark' },
)

const settings = readStorageValue({
  defaultValue: { theme: 'light' },
  key: 'settings',
  serializer,
  storage: localStorage,
})

错误处理示例

import { createPluginErrorHandler } from '@composy/shared-core/error-handler'

const err = createPluginErrorHandler('cache-plugin')

// 包装函数，自动捕获错误
const safeGet = err.wrap(() => cache.get(key))

// 直接抛出带插件名的错误
err.throw('缓存已满', 'CACHE_FULL')

handle() 可以接收任意抛出值并归一为 Error；同步函数、Promise 和 thenable 的失败都会 被包装为 PluginError。已注册处理器自身失败时只记录错误，不会让调用链再次中断。

类型说明

types/common.ts 提供完整的公共类型体系：

• 框架节点：FrameworkNode、TNode、TNodeReturnValue
• CSS/DOM：CSSSelector、AttachNode、ScrollContainer
• 深度工具：DeepPartial、DeepRequired、DeepReadonly、Prettify
• 通用工具：Nullable、Optional、Maybe、ValueOrFunction、ArrayOrSingle
• 业务类型：ApiResponse、PaginationResponse、UploadFile、FormField、MenuItem
• 主题/设备：ThemeConfig、DeviceInfo

开发约定

• core 不依赖 Vue 或其他 UI 框架
• 浏览器能力必须先做 SSR/权限异常保护
• 公共函数需要显式返回类型和中文注释
• 新增 core 行为需要补充 src/**/__tests__/*.test.ts 回归测试
• 禁止在公共类型/参数/返回值中使用 any，统一使用 unknown 替代
• 仅 Chrome-only 非标准 API（如 performance.memory）允许 eslint-disable + any，需注释说明原因

验证

pnpm --filter @composy/shared-core typecheck
pnpm --filter @composy/shared-core test:run
pnpm --filter @composy/shared-core build

构建产物覆盖 dist/es/esm/lib。