@quiteer/naive-extra 0.0.1

package/src/hooks/useForm.ts

@@ -0,0 +1,272 @@
+import type { Ref } from 'vue'
+import type { FormSchema } from '../components/form/props'
+
+interface Option { label: string, value: any, disabled?: boolean }
+
+/**
+ * 基于表单 `schemas` 提供便捷的查询与更新工具
+ *
+ * 适用于外部通过接口动态配置下拉选项、默认值、组件属性等场景，
+ * 对传入的 `schemas` 进行就地更新（保持响应式）。
+ *
+ * @param schemas - 表单项描述数组，建议传入响应式引用
+ * @returns 返回一组对 `schemas` 的操作方法
+ *
+ * @example
+ * ```ts
+ * const { setOptions, setComponentProps } = useForm(schemas)
+ * setOptions('status', [{ label: '启用', value: 1 }])
+ * setComponentProps('status', { clearable: true })
+ * ```
+ *
+ * @remarks
+ * - 所有更新均为原地更新，适配 Vue 的响应式数组/对象
+ * - 仅对存在的字段进行更新，不会抛异常
+ *
+ * @security
+ * 请勿在 `componentProps` 中写入敏感信息
+ *
+ * @performance
+ * 操作复杂度均为 O(n) 或更低，适合一般表单规模
+ */
+export function useForm(schemas: FormSchema[], formRef?: Ref<any>) {
+  /**
+   * 查找指定字段的 schema
+   *
+   * @param field - 字段名
+   * @returns 命中的 `FormSchema` 或 `undefined`
+   *
+   * @example
+   * ```ts
+   * const schema = useItemByField('status')
+   * ```
+   */
+  function useItemByField(field: string) {
+    return schemas.find(item => item.field === field)
+  }
+
+  /**
+   * 为 Select/RadioGroup/Checkbox 等具备 `options` 的组件设置选项
+   *
+   * @param field - 字段名
+   * @param options - 选项数组，包含 `label` 与 `value`
+   *
+   * @example
+   * ```ts
+   * setOptions('status', [
+   *   { label: '未上架', value: 0 },
+   *   { label: '已上架', value: 1 }
+   * ])
+   * ```
+   *
+   * @remarks
+   * - 支持的组件：`NSelect`、`NRadioGroup`、`NCheckbox`
+   */
+  function setOptions(field: string, options: Option[]) {
+    const target = useItemByField(field)
+    if (!target)
+      return
+    const comp = target.component
+    const allow = comp === 'NSelect' || comp === 'NRadioGroup' || comp === 'NCheckbox'
+    if (!allow)
+      return
+    if (!target.componentProps || typeof target.componentProps !== 'object') {
+      target.componentProps = {}
+    }
+    target.componentProps.options = options
+  }
+
+  /**
+   * 获取指定字段的选项数组
+   *
+   * @param field - 字段名
+   * @returns 选项数组或 `undefined`
+   *
+   * @example
+   * ```ts
+   * const opts = getOptions('status')
+   * ```
+   */
+  function getOptions(field: string): Option[] | undefined {
+    const target = useItemByField(field)
+    return target?.componentProps?.options
+  }
+
+  /**
+   * 合并更新组件属性 `componentProps`
+   *
+   * @param field - 字段名
+   * @param props - 待合并的属性对象
+   *
+   * @example
+   * ```ts
+   * setComponentProps('status', { clearable: true })
+   * ```
+   */
+  function setComponentProps(field: string, props: Record<string, any>) {
+    const target = useItemByField(field)
+    if (!target)
+      return
+    if (!target.componentProps || typeof target.componentProps !== 'object') {
+      target.componentProps = {}
+    }
+    Object.assign(target.componentProps, props)
+  }
+
+  /**
+   * 设置单个字段的默认值
+   *
+   * @param field - 字段名
+   * @param value - 默认值
+   *
+   * @example
+   * ```ts
+   * setDefaultValue('status', 1)
+   * ```
+   */
+  function setDefaultValue(field: string, value: any) {
+    const target = useItemByField(field)
+    if (!target)
+      return
+    target.defaultValue = value
+  }
+
+  /**
+   * 局部更新指定字段的 schema
+   *
+   * @param field - 字段名
+   * @param patch - 局部更新内容
+   *
+   * @example
+   * ```ts
+   * replaceSchema('status', { label: '上架状态', component: 'NSelect' })
+   * ```
+   */
+  function replaceSchema(field: string, patch: Partial<FormSchema>) {
+    const target = useItemByField(field)
+    if (!target)
+      return
+    Object.assign(target, patch)
+  }
+
+  /**
+   * 新增或替换（按 `field` 唯一）一个 schema
+   *
+   * @param schema - 完整的表单项描述
+   *
+   * @example
+   * ```ts
+   * upsertSchema({ field: 'title', label: '标题', component: 'NInput' })
+   * ```
+   */
+  function upsertSchema(schema: FormSchema) {
+    const idx = schemas.findIndex(s => s.field === schema.field)
+    if (idx >= 0) {
+      schemas[idx] = { ...schemas[idx], ...schema }
+    }
+    else {
+      schemas.push(schema)
+    }
+  }
+
+  /**
+   * 移除指定字段的 schema
+   *
+   * @param field - 字段名
+   * @returns 是否删除成功
+   *
+   * @example
+   * ```ts
+   * const ok = removeSchema('status')
+   * ```
+   */
+  function removeSchema(field: string): boolean {
+    const idx = schemas.findIndex(s => s.field === field)
+    if (idx < 0)
+      return false
+    schemas.splice(idx, 1)
+    return true
+  }
+
+  /**
+   * 列出所有字段名
+   *
+   * @returns 字段名数组
+   *
+   * @example
+   * ```ts
+   * const fields = listFields()
+   * ```
+   */
+  function listFields(): string[] {
+    return schemas.map(s => String(s.field))
+  }
+
+  /**
+   * 从 `schemas` 生成规则映射（`path -> rules[]`）
+   *
+   * @returns 规则映射对象
+   *
+   * @example
+   * ```ts
+   * const rules = toRulesMap()
+   * ```
+   */
+  function toRulesMap(): Record<string, object[]> {
+    const acc: Record<string, object[]> = {}
+    schemas.forEach((s) => {
+      if (Array.isArray(s.rules) && s.rules.length) {
+        acc[String(s.field)] = s.rules
+      }
+    })
+    return acc
+  }
+
+  function getFormRef() {
+    return formRef?.value
+  }
+
+  function bindFormRef(ref: Ref<any>) {
+    ;(formRef as any) = ref
+  }
+
+  function validate(): Promise<void> | undefined {
+    return formRef?.value?.validate()
+  }
+
+  function resetFields(): Promise<void> | undefined {
+    return formRef?.value?.resetFields()
+  }
+
+  function clearValidate(): Promise<void> | undefined {
+    return formRef?.value?.clearValidate()
+  }
+
+  function getFieldsValue(): Record<string, any> | undefined {
+    return formRef?.value?.getFieldsValue()
+  }
+
+  function setFieldsValue(values: Record<string, any>): void {
+    formRef?.value?.setFieldsValue(values)
+  }
+
+  return {
+    useItemByField,
+    setOptions,
+    getOptions,
+    setComponentProps,
+    setDefaultValue,
+    replaceSchema,
+    upsertSchema,
+    removeSchema,
+    listFields,
+    toRulesMap,
+    getFormRef,
+    bindFormRef,
+    validate,
+    resetFields,
+    clearValidate,
+    getFieldsValue,
+    setFieldsValue
+  }
+}

package/src/hooks/useLayout.ts

@@ -0,0 +1,300 @@
+/** 提供给用户的布局上下文以及一些协助使用的函数 */
+
+import type { MenuOption } from 'naive-ui'
+import type { ComputedRef, Ref, WritableComputedRef } from 'vue'
+import type { RouteRecordRaw } from 'vue-router'
+import type { LayoutType, RouteMeta } from '../components/layout/types'
+import { computed, isRef, onUnmounted, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { DEFAULT_LAYOUT_PROPS } from '../components/layout/const'
+import { filterRouteTree, normalizeAndRedirect, sortRouteTree, toRouteTree } from '../utils/transformRoutes'
+
+// 仅在此文件内用简化上下文类型，避免类型实例化过深
+export interface UseLayoutContext {
+  type: 'left-menu' | string
+  bordered: boolean
+  inverted: boolean
+  isCollapsed: boolean
+  headerHeight: number
+  footerHeight: number
+  showFooter: boolean
+  siderWidth: number
+  siderMixedWidth: number
+  collapsedWidth: number
+  routes: RouteLike[]
+  activeKey: string
+  menuOptions: MenuOption[]
+  accordion: boolean
+  homePath?: string
+  excludePaths?: string[]
+  updateIsCollapsed: (v: boolean) => void
+  updateInverted: (v: boolean) => void
+  updateActiveKey: (v: string) => void
+}
+
+export interface UseLayoutReturn {
+  collapsed: Ref<boolean>
+  baseRoutes: any
+  addRoute: (route: RouteRecordRaw) => void
+  addRoutes: (routes: RouteRecordRaw[]) => void
+  removeRoute: (id: string) => void
+  toggle: () => void
+  setCollapsed: (v: boolean) => void
+  activeKey: Ref<string>
+  setActiveKey: (key: string) => void
+  menuOptions: ComputedRef<MenuOption[]>
+  context: UseLayoutContext
+  type: WritableComputedRef<LayoutType>
+  bordered: Ref<boolean>
+  inverted: Ref<boolean>
+  headerHeight: Ref<number>
+  footerHeight: Ref<number>
+  siderWidth: Ref<number>
+  siderMixedWidth: Ref<number>
+  collapsedWidth: Ref<number>
+  accordion: Ref<boolean>
+}
+
+/**
+ * 获取扁平路由列表（基于 Vue Router）
+ *
+ * 读取 `useRouter().getRoutes()` 并转换为简化的 `RouteRecordRaw[]`（扁平结构）。
+ * 自动补充 `meta.title` 兜底为 `name`，并过滤 `meta.showInMenu === false` 的项。
+ *
+ * @returns 扁平路由数组，适配菜单转换
+ *
+ * @example
+ * ```ts
+ * const routes = getRoutes()
+ * ```
+ */
+export interface RouteLike {
+  path: string
+  name?: string
+  meta?: RouteMeta
+  children?: RouteLike[]
+}
+
+export function useActiveKey(initialKey = ''): {
+  activeKey: Ref<string>
+  setActiveKey: (key: string) => void
+} {
+  const activeKey = ref<string>(initialKey)
+  const setActiveKey = (key: string) => {
+    activeKey.value = key
+  }
+  return { activeKey, setActiveKey }
+}
+
+/**
+ * 创建布局辅助方法集合
+ *
+ * 提供统一的布局状态管理（折叠、激活键）、菜单生成以及用于 provide/inject 的上下文对象构建。
+ *
+ * @param option - 布局初始化与参数配置
+ * @param option.routes - 路由数组或其 Ref（用于生成菜单）
+ * @param option.initialCollapsed - 初始折叠状态，默认 false
+ * @param option.initialActiveKey - 初始激活菜单键，默认 ''
+ * @param option.bordered - 是否显示边框，支持布尔或 Ref
+ * @param option.inverted - 是否启用反色样式，支持布尔或 Ref
+ * @param option.headerHeight - 头部高度，支持 number 或 Ref<number>
+ * @param option.footerHeight - 底部高度，支持 number 或 Ref<number>
+ * @param option.siderWidth - 侧栏宽度，支持 number 或 Ref<number>
+ * @param option.collapsedWidth - 折叠宽度，支持 number 或 Ref<number>
+ * @returns 返回包含状态控制、菜单选项与上下文的辅助对象
+ * @throws {TypeError} 在编译期校验参数类型，不在运行时抛错
+ *
+ * @remarks
+ * - 统一创建 ComputedRef 包裹的配置，确保在 provide/inject 下保持响应式
+ * - `routes` 支持数组或 Ref，内部自动转换为响应式
+ *
+ * @security
+ * - 无副作用，仅管理 UI 状态与映射
+ *
+ * @performance
+ * - 主要开销为菜单映射与少量 computed，通常可忽略
+ */
+
+export function useLayout(option: {
+  baseRoutes: Readonly<Ref<RouteRecordRaw[]> | RouteRecordRaw[]>
+  menuOptions?: Ref<MenuOption[]> | MenuOption[]
+  initialCollapsed?: boolean
+  initialActiveKey?: string
+  type?: LayoutType
+  bordered?: boolean
+  inverted?: boolean
+  headerHeight?: number
+  footerHeight?: number
+  showFooter?: boolean
+  siderWidth?: number
+  siderMixedWidth?: number
+  collapsedWidth?: number
+  accordion?: boolean
+  homePath?: string
+  excludePaths?: string[]
+}): UseLayoutReturn {
+  const route = useRoute()
+  const router = useRouter()
+
+  // 状态管理
+  const collapsed = ref(option.initialCollapsed ?? false)
+  const { activeKey, setActiveKey } = useActiveKey(option.initialActiveKey ?? option.homePath ?? '/')
+
+  // 全局布局类型（当页面没有指定 meta.layout 时使用）
+  const globalType = ref<LayoutType>(option.type ?? DEFAULT_LAYOUT_PROPS.type)
+
+  // 最终使用的布局类型（优先使用页面 meta.layout）
+  const type = computed<LayoutType>({
+    get: () => (route.meta.layout as LayoutType) || globalType.value,
+    set: (v) => {
+      globalType.value = v
+    }
+  })
+
+  // 配置项全部转为 ref（统一响应式）
+  const bordered = ref(option.bordered ?? DEFAULT_LAYOUT_PROPS.bordered)
+  const inverted = ref(option.inverted ?? DEFAULT_LAYOUT_PROPS.inverted)
+  const headerHeight = ref(option.headerHeight ?? DEFAULT_LAYOUT_PROPS.headerHeight)
+  const footerHeight = ref(option.footerHeight ?? DEFAULT_LAYOUT_PROPS.footerHeight)
+  const showFooter = ref(option.showFooter ?? DEFAULT_LAYOUT_PROPS.showFooter)
+  const siderWidth = ref(option.siderWidth ?? DEFAULT_LAYOUT_PROPS.siderWidth)
+  const siderMixedWidth = ref(option.siderMixedWidth ?? DEFAULT_LAYOUT_PROPS.siderMixedWidth)
+  const collapsedWidth = ref(option.collapsedWidth ?? DEFAULT_LAYOUT_PROPS.collapsedWidth)
+  const accordion = ref(option.accordion ?? DEFAULT_LAYOUT_PROPS.accordion)
+
+  // 基础路由处理
+  const baseRoutes = isRef(option.baseRoutes) ? option.baseRoutes : ref(option.baseRoutes)
+  const normalizedBaseRoutes = computed(() => normalizeAndRedirect(baseRoutes.value as RouteRecordRaw[]))
+  const routesTree = computed<RouteLike[]>(() => {
+    const tree = toRouteTree(normalizedBaseRoutes.value) as any
+    const sorted = sortRouteTree(tree)
+    const filtered = filterRouteTree(sorted as any, option.excludePaths ?? [])
+    return filtered as any
+  })
+
+  const menuOptions = computed<MenuOption[]>(() => {
+    if (option.menuOptions)
+      return isRef(option.menuOptions) ? option.menuOptions.value : option.menuOptions
+
+    return []
+  })
+
+  // ✅ 构建响应式 context：直接放 ref/computed，不要 .value！
+  const context = reactive({
+    type,
+    // 响应式字段（ref 会被 reactive 自动 unwrap 使用，但保持响应链接）
+    bordered,
+    inverted,
+    isCollapsed: collapsed,
+    headerHeight,
+    footerHeight,
+    showFooter,
+    siderWidth,
+    collapsedWidth,
+    activeKey,
+    menuOptions,
+    accordion,
+    routes: routesTree as unknown as any,
+    homePath: option.homePath,
+    excludePaths: option.excludePaths,
+
+    // 方法
+    updateIsCollapsed(v: boolean) {
+      collapsed.value = v
+    },
+    updateInverted(v: boolean) {
+      inverted.value = v
+    },
+    updateActiveKey(v: string) {
+      setActiveKey(v)
+      if (/^https?:\/\//.test(v))
+        return
+
+      if (v.startsWith('/')) {
+        router.push(v)
+      }
+      else {
+        router.push({ name: v })
+      }
+    }
+  }) as unknown as UseLayoutContext
+
+  // 监听路由变化，同步更新 activeKey
+  const stop = watch(
+    () => [route.name, route.path, route.meta.activeMenu],
+    ([name, path, activeMenu]) => {
+      setActiveKey((activeMenu as string) || (name as string) || (path as string))
+    },
+    { immediate: true }
+  )
+
+  const stopSync = watch(
+    normalizedBaseRoutes,
+    (list) => {
+      for (const r of list as RouteRecordRaw[]) {
+        const name = r.name as string | undefined
+        if (name && router.hasRoute(name)) {
+          router.removeRoute(name)
+        }
+        router.addRoute(r)
+      }
+    },
+    { immediate: true, deep: true }
+  )
+
+  onUnmounted(() => stop())
+  onUnmounted(() => stopSync())
+
+  function addRoute(route: RouteRecordRaw) {
+    const existing = new Set<string>(router.getRoutes().map(r => String(r.name ?? '')))
+    const name = route.name as string | undefined
+    if (name && existing.has(name))
+      return
+    const [rec] = normalizeAndRedirect([route])
+    if (rec) {
+      router.addRoute(rec)
+    }
+  }
+
+  function addRoutes(routes: RouteRecordRaw[]) {
+    const existing = new Set<string>(router.getRoutes().map(r => String(r.name ?? '')))
+    const toAdd = routes.filter((r) => {
+      const n = r.name as string | undefined
+      return !n || !existing.has(n)
+    })
+    if (!toAdd.length)
+      return
+    const recs = normalizeAndRedirect(toAdd)
+    for (const rec of recs) router.addRoute(rec)
+  }
+
+  function removeRoute(id: string) {
+    const name = id
+    if (router.hasRoute(name)) {
+      router.removeRoute(name)
+    }
+  }
+
+  return {
+    collapsed,
+    baseRoutes,
+    addRoute,
+    addRoutes,
+    removeRoute,
+    toggle: () => (collapsed.value = !collapsed.value),
+    setCollapsed: (v: boolean) => (collapsed.value = v),
+    activeKey,
+    setActiveKey,
+    menuOptions,
+    context,
+    type,
+    bordered,
+    inverted,
+    headerHeight,
+    footerHeight,
+    siderWidth,
+    siderMixedWidth,
+    collapsedWidth,
+    accordion
+  }
+}

package/src/hooks/useProviderContext.ts

@@ -0,0 +1,47 @@
+import type { NaiveExtraThemeConfig } from '../const'
+import type { NaiveExtraContext } from '../context/index'
+import { computed, inject, ref } from 'vue'
+import { DEFAULT_THEME_CONFIG } from '../const'
+import { NAIVE_EXTRA_CONTEXT_KEY } from '../context/index'
+
+/**
+ * 消费主题配置上下文
+ *
+ * 为用户提供访问和更新全局配置的能力。
+ *
+ * @returns {NaiveExtraContext} 包含配置状态、合并后的配置、以及更新方法
+ *
+ * @example
+ * ```ts
+ * const { mergedConfig, updateConfig } = useProviderContext()
+ *
+ * // 更新品牌色
+ * updateConfig({ palette: { primary: '#ff0000' } })
+ * ```
+ */
+export function useProviderContext(): NaiveExtraContext {
+  const context = inject(NAIVE_EXTRA_CONTEXT_KEY, null)
+  if (context)
+    return context
+
+  // 兜底逻辑
+  const config = ref(DEFAULT_THEME_CONFIG)
+  const isDark = computed(() => DEFAULT_THEME_CONFIG.themeMode === 'dark')
+
+  return {
+    config,
+    mergedConfig: computed(() => DEFAULT_THEME_CONFIG as Required<NaiveExtraThemeConfig>),
+    providerProps: computed(() => ({})),
+    loadingBarProviderProps: computed(() => ({})),
+    messageProviderProps: computed(() => ({})),
+    notificationProviderProps: computed(() => ({})),
+    isDark,
+    updateConfig: () => console.warn('[NaiveExtra] 尝试在未挂载 Provider 的情况下更新配置，操作无效。'),
+    setThemeMode: () => {},
+    toggleTheme: () => {},
+    setLocaleMode: () => {},
+    toggleLocale: () => {},
+    setPrimaryColor: () => {},
+    setBorderRadius: () => {}
+  }
+}