@cyberpunk-vue/hooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyberpunk Vue Contributors
+
+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/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("@cyberpunk-vue/constants"),f=require("vue"),h=d.CSS_NAMESPACE;function P(e){const r=h;return{namespace:r,b:()=>`${r}-${e}`,e:n=>n?`${r}-${e}__${n}`:"",m:n=>n?`${r}-${e}--${n}`:"",bem:(n,u,$)=>{let l=`${r}-${e}`;return n&&(l+=`-${n}`),u&&(l+=`__${u}`),$&&(l+=`--${$}`),l},is:(n,u=!0)=>u?`is-${n}`:""}}function z(e,r){const i=f.inject(d.DEFAULTS_KEY,{})[r]??{};return f.computed(()=>{const o={...e};for(const s in i)e[s]===void 0&&(o[s]=i[s]);return o})}function p(e){return e===void 0||e===""?"":typeof e=="number"?`${e}ms`:e}function b(e){return f.computed(()=>p(e.value))}function D(e){return/^-?\d+(\.\d+)?$/.test(e.trim())}function a(e,r){if(e===void 0||e==="")return"";if(typeof e=="number")return`${e}px`;const t=e.trim();return r&&t in r?`${r[t]}px`:D(t)?`${t}px`:t}function _(e,r=["sm","md","lg"]){return typeof e=="string"&&r.includes(e)}function j(e,r){return f.computed(()=>a(e.value,r))}function q(e){return typeof e=="string"?e.replace(/^[?&]/,""):Array.isArray(e)?e.join("&"):typeof e=="object"&&e!==null?Object.entries(e).filter(([,r])=>r!=null).map(([r,t])=>`${encodeURIComponent(r)}=${encodeURIComponent(String(t))}`).join("&"):""}const g=(e,r)=>{if(!r)return e;const t=q(r);if(!t)return e;const i=e.includes("?")?"&":"?";return`${e}${i}${t}`},m=(e,r)=>r?typeof r=="function"?r(e):r.replace(/\{src\}/g,e):e,y=(e,r)=>{if(!r)return e;const t=[];if(r.width||r.height){const o=["resize"];r.mode&&o.push(`m_${r.mode}`),r.width&&o.push(`w_${r.width}`),r.height&&o.push(`h_${r.height}`),t.push(o.join(","))}if(r.quality&&t.push(`quality,q_${r.quality}`),r.format&&t.push(`format,${r.format}`),t.length===0)return e;const i=e.includes("?")?"&":"?";return`${e}${i}x-tos-process=image/${t.join("/")}`},S={append:g,replace:m,tos:y};function w(e){return{processedSrc:f.computed(()=>{var n;const t=typeof e.src=="string"?e.src:e.src.value,i=typeof e.processor=="function"||typeof e.processor=="string"?e.processor:(n=e.processor)==null?void 0:n.value,o=typeof e.params=="object"&&"value"in e.params?e.params.value:e.params,s=i??(o?"append":void 0);if(!s)return t;let c;if(typeof s=="string"){if(c=S[s],!c)return console.warn(`[useImageSrc] Unknown processor: ${s}`),t}else c=s;try{return c(t,o)||t}catch(u){return console.error("[useImageSrc] Processor error:",u),t}})}}exports.appendProcessor=g;exports.builtinProcessors=S;exports.isPresetSize=_;exports.normalizeDuration=p;exports.normalizeSize=a;exports.replaceProcessor=m;exports.tosProcessor=y;exports.useDefaults=z;exports.useDuration=b;exports.useImageSrc=w;exports.useNamespace=P;exports.useSize=j;

package/dist/index.mjs

@@ -0,0 +1,105 @@
+import { CSS_NAMESPACE as d, DEFAULTS_KEY as p } from "@cyberpunk-vue/constants";
+import { inject as g, computed as $ } from "vue";
+const h = d;
+function w(e) {
+  const r = h;
+  return {
+    namespace: r,
+    b: () => `${r}-${e}`,
+    e: (n) => n ? `${r}-${e}__${n}` : "",
+    m: (n) => n ? `${r}-${e}--${n}` : "",
+    bem: (n, u, l) => {
+      let f = `${r}-${e}`;
+      return n && (f += `-${n}`), u && (f += `__${u}`), l && (f += `--${l}`), f;
+    },
+    is: (n, u = !0) => u ? `is-${n}` : ""
+  };
+}
+function A(e, r) {
+  const s = g(p, {})[r] ?? {};
+  return $(() => {
+    const o = { ...e };
+    for (const i in s)
+      e[i] === void 0 && (o[i] = s[i]);
+    return o;
+  });
+}
+function m(e) {
+  return e === void 0 || e === "" ? "" : typeof e == "number" ? `${e}ms` : e;
+}
+function I(e) {
+  return $(() => m(e.value));
+}
+function y(e) {
+  return /^-?\d+(\.\d+)?$/.test(e.trim());
+}
+function S(e, r) {
+  if (e === void 0 || e === "") return "";
+  if (typeof e == "number")
+    return `${e}px`;
+  const t = e.trim();
+  return r && t in r ? `${r[t]}px` : y(t) ? `${t}px` : t;
+}
+function q(e, r = ["sm", "md", "lg"]) {
+  return typeof e == "string" && r.includes(e);
+}
+function x(e, r) {
+  return $(() => S(e.value, r));
+}
+function a(e) {
+  return typeof e == "string" ? e.replace(/^[?&]/, "") : Array.isArray(e) ? e.join("&") : typeof e == "object" && e !== null ? Object.entries(e).filter(([, r]) => r != null).map(([r, t]) => `${encodeURIComponent(r)}=${encodeURIComponent(String(t))}`).join("&") : "";
+}
+const P = (e, r) => {
+  if (!r) return e;
+  const t = a(r);
+  if (!t) return e;
+  const s = e.includes("?") ? "&" : "?";
+  return `${e}${s}${t}`;
+}, _ = (e, r) => r ? typeof r == "function" ? r(e) : r.replace(/\{src\}/g, e) : e, b = (e, r) => {
+  if (!r) return e;
+  const t = [];
+  if (r.width || r.height) {
+    const o = ["resize"];
+    r.mode && o.push(`m_${r.mode}`), r.width && o.push(`w_${r.width}`), r.height && o.push(`h_${r.height}`), t.push(o.join(","));
+  }
+  if (r.quality && t.push(`quality,q_${r.quality}`), r.format && t.push(`format,${r.format}`), t.length === 0) return e;
+  const s = e.includes("?") ? "&" : "?";
+  return `${e}${s}x-tos-process=image/${t.join("/")}`;
+}, j = {
+  append: P,
+  replace: _,
+  tos: b
+};
+function C(e) {
+  return { processedSrc: $(() => {
+    var n;
+    const t = typeof e.src == "string" ? e.src : e.src.value, s = typeof e.processor == "function" || typeof e.processor == "string" ? e.processor : (n = e.processor) == null ? void 0 : n.value, o = typeof e.params == "object" && "value" in e.params ? e.params.value : e.params, i = s ?? (o ? "append" : void 0);
+    if (!i)
+      return t;
+    let c;
+    if (typeof i == "string") {
+      if (c = j[i], !c)
+        return console.warn(`[useImageSrc] Unknown processor: ${i}`), t;
+    } else
+      c = i;
+    try {
+      return c(t, o) || t;
+    } catch (u) {
+      return console.error("[useImageSrc] Processor error:", u), t;
+    }
+  }) };
+}
+export {
+  P as appendProcessor,
+  j as builtinProcessors,
+  q as isPresetSize,
+  m as normalizeDuration,
+  S as normalizeSize,
+  _ as replaceProcessor,
+  b as tosProcessor,
+  A as useDefaults,
+  I as useDuration,
+  C as useImageSrc,
+  w as useNamespace,
+  x as useSize
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@cyberpunk-vue/hooks",
+  "version": "0.1.0",
+  "description": "Cyberpunk Vue composables - Reusable Vue 3 composition functions",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@cyberpunk-vue/constants": "0.1.0"
+  },
+  "author": "Juxest",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/cyberpunk-vue.git",
+    "directory": "packages/hooks"
+  },
+  "homepage": "https://github.com/user/cyberpunk-vue#readme",
+  "bugs": {
+    "url": "https://github.com/user/cyberpunk-vue/issues"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "composables",
+    "hooks",
+    "cyberpunk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build"
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { useNamespace } from './use-namespace'
+export type { UseNamespaceReturn } from './use-namespace'
+
+export { useDefaults } from './use-defaults'
+
+export { useDuration, normalizeDuration } from './use-duration'
+export type { DurationValue } from './use-duration'
+
+export { useSize, normalizeSize, isPresetSize } from './use-size'
+export type { SizeValue, CommonSize, Size } from './use-size'
+
+export {
+    useImageSrc,
+    appendProcessor,
+    replaceProcessor,
+    tosProcessor,
+    builtinProcessors,
+} from './use-image-src'
+export type {
+    ImageSrcProcessor,
+    ImageProcessorParams,
+    TosProcessorParams,
+    BuiltinProcessorName,
+    UseImageSrcOptions,
+    UseImageSrcReturn,
+} from './use-image-src'
+

package/src/use-defaults/index.ts

@@ -0,0 +1,29 @@
+/**
+ * useDefaults - 全局默认值合并
+ * 合并优先级: 显式 Props > 全局配置 > 组件默认值
+ */
+import { inject, computed, type ComputedRef } from 'vue'
+import { DEFAULTS_KEY } from '@cyberpunk-vue/constants'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- 泛型约束需要 any
+export function useDefaults<T extends Record<string, any>>(
+    props: T,
+    name: string
+): ComputedRef<T> {
+    const globalDefaults = inject(DEFAULTS_KEY, {}) as Record<string, Partial<T>>
+    const componentDefaults = globalDefaults[name] ?? {}
+
+    return computed(() => {
+        const result = { ...props }
+
+        // 只覆盖未显式传递的 props
+        for (const key in componentDefaults) {
+            if (props[key] === undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 动态属性赋值需要类型断言
+                ; (result as any)[key] = componentDefaults[key]
+            }
+        }
+
+        return result
+    })
+}

package/src/use-duration/index.ts

@@ -0,0 +1,39 @@
+/**
+ * useDuration - 动画时间单位标准化工具
+ * 
+ * 统一处理动画时间值，支持数字和字符串两种格式：
+ * - 数字：默认视为毫秒 (ms)，转为 CSS 时间字符串
+ * - 字符串：保持原样，用户可自行指定单位 (如 '1.5s' 或 '500ms')
+ * 
+ * @example
+ * ```ts
+ * normalizeDuration(300)     // => '300ms'
+ * normalizeDuration('1.5s')  // => '1.5s'
+ * normalizeDuration('500ms') // => '500ms'
+ * normalizeDuration('')      // => ''
+ * ```
+ */
+
+import { computed, type Ref, type ComputedRef } from 'vue'
+
+export type DurationValue = number | string | undefined
+
+/**
+ * 将时间值标准化为 CSS 可用的时间字符串
+ * @param value - 时间值（数字默认 ms，字符串保持原样）
+ * @returns CSS 时间字符串，如 '300ms' 或 '1.5s'
+ */
+export function normalizeDuration(value: DurationValue): string {
+  if (value === undefined || value === '') return ''
+  if (typeof value === 'number') return `${value}ms`
+  return value
+}
+
+/**
+ * 响应式版本的时间标准化
+ * @param valueRef - 响应式时间值引用
+ * @returns 响应式 CSS 时间字符串
+ */
+export function useDuration(valueRef: Ref<DurationValue>): ComputedRef<string> {
+  return computed(() => normalizeDuration(valueRef.value))
+}

package/src/use-image-src/index.ts

@@ -0,0 +1,216 @@
+import { computed, type Ref, type ComputedRef } from 'vue'
+
+/**
+ * 图片 URL 处理器函数签名
+ * @param src - 原始图片 URL
+ * @param params - 处理参数（可选）
+ * @returns 处理后的 URL
+ */
+export type ImageSrcProcessor<T = unknown> = (src: string, params?: T) => string
+
+/**
+ * 处理器参数类型
+ * 支持字符串、对象、数组等
+ */
+export type ImageProcessorParams = string | Record<string, unknown> | unknown[]
+
+/**
+ * TOS 图像处理参数
+ */
+export interface TosProcessorParams {
+    /** 目标宽度 */
+    width?: number
+    /** 目标高度 */
+    height?: number
+    /** 图片质量 (1-100) */
+    quality?: number
+    /** 输出格式 */
+    format?: 'jpg' | 'png' | 'webp' | 'avif' | 'gif'
+    /** 缩放模式 */
+    mode?: 'fit' | 'fill' | 'pad'
+}
+
+// ============================================
+// 内置处理器
+// ============================================
+
+/**
+ * 将查询参数序列化为字符串
+ */
+function serializeParams(params: unknown): string {
+    if (typeof params === 'string') {
+        // 移除开头的 ? 或 &
+        return params.replace(/^[?&]/, '')
+    }
+    if (Array.isArray(params)) {
+        return params.join('&')
+    }
+    if (typeof params === 'object' && params !== null) {
+        return Object.entries(params as Record<string, unknown>)
+            .filter(([, value]) => value !== undefined && value !== null)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+            .join('&')
+    }
+    return ''
+}
+
+/**
+ * append 处理器 - 追加查询参数
+ * 智能处理 URL 中的 ? 和 &
+ */
+export const appendProcessor: ImageSrcProcessor<ImageProcessorParams> = (src, params) => {
+    if (!params) return src
+    
+    const serialized = serializeParams(params)
+    if (!serialized) return src
+    
+    // 检查 URL 是否已有查询参数
+    const separator = src.includes('?') ? '&' : '?'
+    return `${src}${separator}${serialized}`
+}
+
+/**
+ * replace 处理器 - 替换 URL
+ * 支持字符串模板或函数
+ */
+export const replaceProcessor: ImageSrcProcessor<string | ((src: string) => string)> = (src, params) => {
+    if (!params) return src
+    
+    if (typeof params === 'function') {
+        return params(src)
+    }
+    
+    // 字符串模板，支持 {src} 占位符
+    return params.replace(/\{src\}/g, src)
+}
+
+/**
+ * TOS 处理器 - 火山引擎图像处理
+ * 格式: ~tplv-xxx~image/resize,w_100,h_100/quality,q_80/format,webp
+ */
+export const tosProcessor: ImageSrcProcessor<TosProcessorParams> = (src, params) => {
+    if (!params) return src
+    
+    const operations: string[] = []
+    
+    // 缩放
+    if (params.width || params.height) {
+        const resizeParts = ['resize']
+        if (params.mode) resizeParts.push(`m_${params.mode}`)
+        if (params.width) resizeParts.push(`w_${params.width}`)
+        if (params.height) resizeParts.push(`h_${params.height}`)
+        operations.push(resizeParts.join(','))
+    }
+    
+    // 质量
+    if (params.quality) {
+        operations.push(`quality,q_${params.quality}`)
+    }
+    
+    // 格式
+    if (params.format) {
+        operations.push(`format,${params.format}`)
+    }
+    
+    if (operations.length === 0) return src
+    
+    // TOS URL 格式
+    const separator = src.includes('?') ? '&' : '?'
+    return `${src}${separator}x-tos-process=image/${operations.join('/')}`
+}
+
+/**
+ * 内置处理器映射
+ */
+export const builtinProcessors: Record<string, ImageSrcProcessor<unknown>> = {
+    append: appendProcessor as ImageSrcProcessor<unknown>,
+    replace: replaceProcessor as ImageSrcProcessor<unknown>,
+    tos: tosProcessor as ImageSrcProcessor<unknown>,
+}
+
+/**
+ * 预设处理器名称类型
+ */
+export type BuiltinProcessorName = keyof typeof builtinProcessors
+
+// ============================================
+// Hook
+// ============================================
+
+export interface UseImageSrcOptions {
+    /** 原始 URL */
+    src: Ref<string> | string
+    /** 处理器：预设名称或自定义函数 */
+    processor?: Ref<string | ImageSrcProcessor | undefined> | string | ImageSrcProcessor
+    /** 处理器参数 */
+    params?: Ref<ImageProcessorParams | undefined> | ImageProcessorParams
+}
+
+export interface UseImageSrcReturn {
+    /** 处理后的 URL */
+    processedSrc: ComputedRef<string>
+}
+
+/**
+ * 图片 URL 处理 Hook
+ * 
+ * @example
+ * ```ts
+ * // 使用预设处理器
+ * const { processedSrc } = useImageSrc({
+ *   src: 'https://example.com/image.jpg',
+ *   processor: 'append',
+ *   params: { width: 100 }
+ * })
+ * 
+ * // 使用自定义处理器
+ * const { processedSrc } = useImageSrc({
+ *   src: imageUrl,
+ *   processor: (src, params) => `${src}?custom=${params.id}`
+ * })
+ * ```
+ */
+export function useImageSrc(options: UseImageSrcOptions): UseImageSrcReturn {
+    const processedSrc = computed(() => {
+        // 获取原始值
+        const srcValue = typeof options.src === 'string' ? options.src : options.src.value
+        const processorValue = typeof options.processor === 'function' || typeof options.processor === 'string'
+            ? options.processor
+            : options.processor?.value
+        const paramsValue = typeof options.params === 'object' && 'value' in (options.params as object)
+            ? (options.params as Ref<ImageProcessorParams | undefined>).value
+            : options.params as ImageProcessorParams | undefined
+        
+        // 无处理器但有参数时，默认使用 append
+        const effectiveProcessor = processorValue ?? (paramsValue ? 'append' : undefined)
+        
+        if (!effectiveProcessor) {
+            return srcValue
+        }
+        
+        // 获取处理器函数
+        let processorFn: ImageSrcProcessor<unknown>
+        
+        if (typeof effectiveProcessor === 'string') {
+            processorFn = builtinProcessors[effectiveProcessor]
+            if (!processorFn) {
+                console.warn(`[useImageSrc] Unknown processor: ${effectiveProcessor}`)
+                return srcValue
+            }
+        } else {
+            processorFn = effectiveProcessor
+        }
+        
+        // 执行处理
+        try {
+            return processorFn(srcValue, paramsValue) || srcValue
+        } catch (e) {
+            console.error('[useImageSrc] Processor error:', e)
+            return srcValue
+        }
+    })
+    
+    return { processedSrc }
+}
+
+export default useImageSrc

package/src/use-namespace/index.ts

@@ -0,0 +1,60 @@
+/**
+ * useNamespace - BEM 命名空间生成器
+ * 用于生成符合 BEM 规范的 CSS 类名
+ */
+
+import { CSS_NAMESPACE } from '@cyberpunk-vue/constants'
+
+const defaultNamespace = CSS_NAMESPACE
+
+export type UseNamespaceReturn = {
+
+    /** 命名空间 */
+    namespace: string
+    /** 块类名 cp-{block} */
+    b: () => string
+    /** 元素类名 cp-{block}__{element} */
+    e: (element: string) => string
+    /** 修饰符类名 cp-{block}--{modifier} */
+    m: (modifier: string) => string
+    /** 块+元素+修饰符 */
+    bem: (block?: string, element?: string, modifier?: string) => string
+    /** 状态类名 is-{state} */
+    is: (state: string, value?: boolean) => string
+}
+
+export function useNamespace(block: string): UseNamespaceReturn {
+    const namespace = defaultNamespace
+
+    const b = () => `${namespace}-${block}`
+
+    const e = (element: string) =>
+        element ? `${namespace}-${block}__${element}` : ''
+
+    const m = (modifier: string) =>
+        modifier ? `${namespace}-${block}--${modifier}` : ''
+
+    const bem = (
+        blockSuffix?: string,
+        element?: string,
+        modifier?: string
+    ) => {
+        let cls = `${namespace}-${block}`
+        if (blockSuffix) cls += `-${blockSuffix}`
+        if (element) cls += `__${element}`
+        if (modifier) cls += `--${modifier}`
+        return cls
+    }
+
+    const is = (state: string, value = true) =>
+        value ? `is-${state}` : ''
+
+    return {
+        namespace,
+        b,
+        e,
+        m,
+        bem,
+        is,
+    }
+}

package/src/use-size/index.ts

@@ -0,0 +1,131 @@
+/**
+ * useSize - 尺寸值标准化工具
+ *
+ * 统一处理组件尺寸值，支持预设值、数字和带单位字符串：
+ * - 数字：默认视为像素 (px)
+ * - 纯数字字符串：默认视为像素 (px)
+ * - 带单位字符串：保持原样 (如 '2rem', '100%')
+ * - 预设字符串：通过 sizeMap 查表转换
+ *
+ * @example
+ * ```ts
+ * normalizeSize(32)              // => '32px'
+ * normalizeSize('32')            // => '32px'
+ * normalizeSize('2rem')          // => '2rem'
+ * normalizeSize('md', { md: 40 }) // => '40px'
+ * normalizeSize('100%')          // => '100%'
+ * ```
+ */
+
+import { computed, type Ref, type ComputedRef } from 'vue'
+
+/**
+ * 尺寸值类型
+ * - 数字：直接作为像素值
+ * - 字符串：可以是预设值、带单位的值或纯数字
+ */
+export type SizeValue = string | number | undefined
+
+/**
+ * 通用尺寸预设类型
+ * 所有组件基础尺寸，组件可扩展为专属 Size
+ */
+export type CommonSize = 'sm' | 'md' | 'lg'
+
+/**
+ * 通用 Size 类型 - 预设值 + 自定义值
+ * 可直接用于大部分组件的 size prop
+ */
+export type Size = CommonSize | number | string
+
+/**
+ * 检测字符串是否为纯数字（不含单位）
+ */
+function isNumericString(value: string): boolean {
+    return /^-?\d+(\.\d+)?$/.test(value.trim())
+}
+
+/**
+ * 检测字符串是否已包含 CSS 单位
+ */
+function hasUnit(value: string): boolean {
+    return /^-?\d+(\.\d+)?(px|em|rem|%|vh|vw|vmin|vmax|ch|ex|cm|mm|in|pt|pc)$/i.test(value.trim())
+}
+
+/**
+ * 将尺寸值标准化为 CSS 可用的尺寸字符串
+ *
+ * @param value - 尺寸值（数字、字符串或预设）
+ * @param sizeMap - 预设值映射表（如 { sm: 24, md: 32, lg: 40 }）
+ * @returns CSS 尺寸字符串，如 '32px' 或 '2rem'
+ */
+export function normalizeSize(
+    value: SizeValue,
+    sizeMap?: Record<string, number>
+): string {
+    // 空值返回空字符串
+    if (value === undefined || value === '') return ''
+
+    // 数字直接转 px
+    if (typeof value === 'number') {
+        return `${value}px`
+    }
+
+    // 字符串处理
+    const trimmed = value.trim()
+
+    // 1. 检查是否为预设值
+    if (sizeMap && trimmed in sizeMap) {
+        return `${sizeMap[trimmed]}px`
+    }
+
+    // 2. 纯数字字符串，添加 px
+    if (isNumericString(trimmed)) {
+        return `${trimmed}px`
+    }
+
+    // 3. 已有单位或其他有效 CSS 值，保持原样
+    return trimmed
+}
+
+/**
+ * 检测 size 值是否为 CommonSize 预设值
+ * 用于组件判断是否应用 CSS 类名还是内联样式
+ *
+ * @param value - size 值
+ * @param presets - 预设值列表，默认 ['sm', 'md', 'lg']
+ * @returns 是否为预设值
+ *
+ * @example
+ * isPresetSize('md')      // true
+ * isPresetSize('xl', ['sm','md','lg','xl']) // true
+ * isPresetSize(32)        // false
+ * isPresetSize('2rem')    // false
+ */
+export function isPresetSize(
+    value: SizeValue,
+    presets: readonly string[] = ['sm', 'md', 'lg']
+): value is string {
+    return typeof value === 'string' && presets.includes(value)
+}
+
+/**
+ * 响应式版本的尺寸标准化
+ *
+ * @param valueRef - 响应式尺寸值引用
+ * @param sizeMap - 预设值映射表
+ * @returns 响应式 CSS 尺寸字符串
+ *
+ * @example
+ * ```ts
+ * const size = ref<SizeValue>('md')
+ * const normalizedSize = useSize(size, { sm: 24, md: 32, lg: 40 })
+ * // normalizedSize.value === '32px'
+ * ```
+ */
+export function useSize(
+    valueRef: Ref<SizeValue>,
+    sizeMap?: Record<string, number>
+): ComputedRef<string> {
+    return computed(() => normalizeSize(valueRef.value, sizeMap))
+}