@quiteer/naive-extra 0.0.1

package/src/components/layout/utils.ts

@@ -0,0 +1,201 @@
+import type { MenuOption } from 'naive-ui'
+import { h } from 'vue'
+import { RouterLink } from 'vue-router'
+
+type AnyMenuOption = MenuOption & { key?: string | number, children?: AnyMenuOption[], href?: string }
+
+export function renderMenuLabel(option: AnyMenuOption) {
+  const { label, key, children, href } = option
+
+  // 如果有子菜单，直接渲染文本，不进行跳转
+  if (children && children.length > 0) {
+    return label as string
+  }
+
+  if (href) {
+    return h('a', { href, target: '_blank', rel: 'noopener noreferrer' }, label as string)
+  }
+
+  const k = typeof key === 'string' ? key : String(key)
+
+  if (/^https?:\/\//.test(k)) {
+    return h('a', { href: k, target: '_blank', rel: 'noopener noreferrer' }, label as string)
+  }
+
+  return h(RouterLink, { to: { name: k } }, { default: () => label })
+}
+
+// 查找指定 key 的菜单节点
+export function findNodeByKey(options: AnyMenuOption[], key: string | number): AnyMenuOption | null {
+  const stack: AnyMenuOption[] = [...(options || [])]
+  while (stack.length) {
+    const n = stack.pop() as AnyMenuOption
+    if (n?.key === key)
+      return n
+    if (Array.isArray(n?.children))
+      stack.push(...n.children!)
+  }
+  return null
+}
+
+// 返回从当前节点出发的第一个叶子节点
+export function findFirstLeaf(node: AnyMenuOption | null | undefined): AnyMenuOption | null {
+  let cur = node ?? null
+  while (cur && Array.isArray(cur.children) && cur.children.length) {
+    cur = cur.children[0] ?? null
+  }
+  return cur ?? null
+}
+
+/** 解析 activeKey 对应的末端（叶子）key */
+export function resolveLeafKeyFromMenu(options: AnyMenuOption[], activeKey: string | number): string {
+  const node = findNodeByKey(options, activeKey)
+  const leaf = findFirstLeaf(node)
+  const k = leaf?.key
+  return typeof k === 'string' ? k : k != null ? String(k) : ''
+}
+
+/** 从子节点 key 解析顶层父级 key */
+export function resolveTopParentKeyFromMenu(options: AnyMenuOption[], childKey: string | number): string {
+  const stack: Array<{ node: AnyMenuOption, topKey: string | number | undefined }> = []
+  for (const o of options || []) stack.push({ node: o as AnyMenuOption, topKey: o.key })
+  while (stack.length) {
+    const { node, topKey } = stack.pop()!
+    if (node?.key === childKey) {
+      return typeof topKey === 'string' ? topKey : topKey != null ? String(topKey) : ''
+    }
+    if (Array.isArray(node?.children)) {
+      for (const c of node.children!) stack.push({ node: c, topKey })
+    }
+  }
+  return '/'
+}
+
+// 判断 key 是否属于顶层菜单
+export function isTopLevelKey(options: AnyMenuOption[], key: string | number): boolean {
+  const topKeys = (options || []).map(o => o.key)
+  const ks = topKeys.filter(k => k != null).map(k => (typeof k === 'string' ? k : String(k)))
+  const target = typeof key === 'string' ? key : String(key)
+  return ks.includes(target)
+}
+
+// 判断 key 是否为叶子（无子节点）
+export function isLeafKey(options: AnyMenuOption[], key: string | number): boolean {
+  const node = findNodeByKey(options, key)
+  return !!node && (!Array.isArray(node.children) || node.children.length === 0)
+}
+
+/**
+ * 从 activeKey 解析出主菜单与子菜单的键
+ *
+ * 解析传入的活跃键在菜单树中的位置，并分别返回顶层父级的 key（主菜单）
+ * 与该分支上的末端叶子 key（子菜单）。
+ *
+ * @param options - 菜单树，需包含 `key` 与可选的 `children`
+ * @param activeKey - 当前激活的菜单键（路径）
+ * @returns 返回对象 `{ mainKey, subKey }`，可能为 `null` 值
+ * @throws {TypeError} 当 `options` 非数组或 `activeKey` 非字符串/数字时在编译期提示
+ *
+ * @example
+ * ```ts
+ * const { mainKey, subKey } = resolveMainSubFromActive(menuOptions, '/dashboard/analysis')
+ * ```
+ *
+ * @remarks
+ * - mainKey 与 subKey 均进行字符串化处理，确保比较与 includes 一致性
+ *
+ * @security
+ * - 纯函数，无副作用
+ *
+ * @performance
+ * - O(n) 遍历一次菜单树
+ */
+export function resolveMainSubFromActive(
+  options: AnyMenuOption[],
+  activeKey: string | number
+): { mainKey: string | null, subKey: string | null } {
+  const mainKey = resolveTopParentKeyFromMenu(options, activeKey)
+  const subKey = resolveLeafKeyFromMenu(options, activeKey)
+  return { mainKey, subKey }
+}
+
+/**
+ * 合并主/子菜单键为最终 activeKey
+ *
+ * 当存在子菜单键时优先返回子菜单键；否则返回主菜单分支上的第一个叶子键，
+ * 若主菜单键也不存在则返回 `null`。
+ *
+ * @param options - 菜单树，需包含 `key` 与可选的 `children`
+ * @param mainKey - 顶层父级 key（主菜单）
+ * @param subKey - 末端叶子 key（子菜单）
+ * @returns 最终用于路由跳转的 activeKey（字符串）或 `null`
+ * @throws {TypeError} 当参数类型不符合预期在编译期提示
+ *
+ * @example
+ * ```ts
+ * const active = resolveActiveKeyFromPair(menuOptions, '/dashboard', '/dashboard/analysis')
+ * ```
+ *
+ * @remarks
+ * - 若 `subKey` 不存在，将尝试从 `mainKey` 分支解析第一个叶子以保证跳转到可达页面
+ *
+ * @security
+ * - 纯函数，无副作用
+ *
+ * @performance
+ * - O(n)（在需要从 `mainKey` 分支解析叶子时）
+ */
+export function resolveActiveKeyFromPair(
+  options: AnyMenuOption[],
+  mainKey: string | number | null | undefined,
+  subKey: string | number | null | undefined
+): string | null {
+  const s = subKey == null ? null : (typeof subKey === 'string' ? subKey : String(subKey))
+  if (s)
+    return s
+  const m = mainKey == null ? null : (typeof mainKey === 'string' ? mainKey : String(mainKey))
+  if (!m)
+    return null
+  return resolveLeafKeyFromMenu(options, m) ?? m
+}
+
+/**
+ * 递归更新菜单树的每个节点
+ *
+ * 对传入的菜单树做一次深度遍历，并对每个节点应用 `updater`，返回新的树结构。
+ * 该方法默认以不可变方式工作：不会修改原始节点引用，而是为每个节点创建浅拷贝并递归重建 children。
+ *
+ * @param options - 菜单树数组（MenuOption[]），允许为空数组
+ * @param updater - 节点更新函数，接收当前节点并返回更新后的节点
+ * @returns 新的菜单树数组（保持树形结构）
+ *
+ * @throws {TypeError} 当 updater 不是函数时抛出
+ *
+ * @example
+ * ```ts
+ * const next = updateMenuTree(menuOptions, (item) => {
+ *   if (typeof item.key === 'string')
+ *     return { ...item, key: item.key.replace('/old', '/new') }
+ *   return item
+ * })
+ * ```
+ */
+export function updateMenuTree(
+  options: AnyMenuOption[],
+  updater: (item: AnyMenuOption) => AnyMenuOption
+): AnyMenuOption[] {
+  if (typeof updater !== 'function')
+    throw new TypeError('updater must be a function')
+
+  const walk = (list: AnyMenuOption[]): AnyMenuOption[] => {
+    return (list || []).map((raw) => {
+      const nextChildren = Array.isArray(raw?.children) ? walk(raw.children!) : undefined
+      const cloned: AnyMenuOption = nextChildren
+        ? { ...(raw as AnyMenuOption), children: nextChildren }
+        : { ...(raw as AnyMenuOption) }
+      return updater(cloned)
+    })
+  }
+
+  return walk(options || [])
+}

package/src/components/provider/index.ts

@@ -0,0 +1,5 @@
+import QuiProvider from './index.vue'
+
+export { QuiProvider }
+
+export type { ProviderProps } from './props'

package/src/components/provider/index.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import type { ProviderProps } from './props'
+import { initNaiveTheme } from '@quiteer/unocss/provide'
+import { useDialog, useLoadingBar, useMessage, useNotification } from 'naive-ui'
+import { computed, createTextVNode, defineComponent, watch } from 'vue'
+import { createProviderContext } from '../../context/index'
+
+defineOptions({
+  name: 'QuiProvider'
+})
+
+const props = defineProps<ProviderProps>()
+
+// 创建并整合主题上下文
+const { providerProps: internalProviderProps, updateConfig } = createProviderContext(props.config)
+
+// 监听外部传入的 config 变化并同步到 context
+watch(() => props.config, (newConfig) => {
+  if (newConfig) {
+    updateConfig(newConfig)
+  }
+}, { deep: true })
+
+onMounted(() => {
+  initNaiveTheme()
+})
+
+// 合并外部传入的 configProviderProps
+const mergedConfigProviderProps = computed(() => ({
+  ...internalProviderProps.value,
+  ...props.configProviderProps
+}))
+
+const ContextHolder = defineComponent({
+  name: 'ContextHolder',
+  setup() {
+    function register() {
+      window.$loadingBar = useLoadingBar()
+      window.$dialog = useDialog()
+      window.$message = useMessage()
+      window.$notification = useNotification()
+    }
+
+    register()
+
+    return () => createTextVNode()
+  }
+})
+</script>
+
+<template>
+  <n-config-provider
+    class="h-full"
+    v-bind="mergedConfigProviderProps"
+  >
+    <n-loading-bar-provider v-bind="props.loadingBarProviderProps">
+      <n-dialog-provider v-bind="props.dialogProviderProps">
+        <n-notification-provider v-bind="props.notificationProviderProps">
+          <n-message-provider v-bind="props.messageProviderProps">
+            <ContextHolder />
+            <slot />
+          </n-message-provider>
+        </n-notification-provider>
+      </n-dialog-provider>
+    </n-loading-bar-provider>
+  </n-config-provider>
+</template>
+
+<style scoped></style>

package/src/components/provider/props.ts

@@ -0,0 +1,45 @@
+import type {
+  ConfigProviderProps,
+  DialogProviderProps,
+  LoadingBarProviderProps,
+  MessageProviderProps,
+  NotificationProviderProps
+} from 'naive-ui'
+import type { NaiveExtraThemeConfig } from '../../const'
+
+export interface ProviderProps {
+  /**
+   * NaiveExtra 主题配置
+   */
+  config?: NaiveExtraThemeConfig
+
+  /**
+   * Config Provider Props
+   * 透传 NConfigProvider 的所有属性 (优先级高于 config)
+   */
+  configProviderProps?: ConfigProviderProps
+
+  /**
+   * Loading Bar Provider Props
+   * 透传 NLoadingBarProvider 的所有属性
+   */
+  loadingBarProviderProps?: LoadingBarProviderProps
+
+  /**
+   * Dialog Provider Props
+   * 透传 NDialogProvider 的所有属性
+   */
+  dialogProviderProps?: DialogProviderProps
+
+  /**
+   * Notification Provider Props
+   * 透传 NNotificationProvider 的所有属性
+   */
+  notificationProviderProps?: NotificationProviderProps
+
+  /**
+   * Message Provider Props
+   * 透传 NMessageProvider 的所有属性
+   */
+  messageProviderProps?: MessageProviderProps
+}

package/src/components/search-bar/index.ts

@@ -0,0 +1,5 @@
+import QuiSearchBar from './index.vue'
+
+export { QuiSearchBar }
+
+export type { Props as SearchBarProps } from './props'

package/src/components/search-bar/index.vue

@@ -0,0 +1,282 @@
+<script setup lang="ts">
+/**
+ * 引入 async-validator 类型以为声明生成提供稳定引用，避免 TS2742。
+ * 仅类型导入，不会影响运行时体积或行为。
+ */
+import type {} from 'async-validator'
+import type { ButtonProps } from 'naive-ui'
+import type { Recordable } from '../../const'
+import type { Props } from './props'
+import { isNullOrUnDef } from '@quiteer/is'
+import { computed, nextTick, onMounted, ref, toRaw, unref, useAttrs, watch, watchEffect } from 'vue'
+import { QuiForm } from '../form'
+
+const props = withDefaults(defineProps<Props>(), {
+  title: '搜索',
+  labelWidth: 80,
+  labelPlacement: 'top',
+  layout: 'inline',
+  inline: false,
+  size: 'medium',
+  isFull: true,
+  showActionButtonGroup: true,
+  showResetButton: true,
+  resetButtonOptions: undefined,
+  showSubmitButton: true,
+  submitButtonOptions: undefined,
+  showAdvancedButton: true,
+  expanded: undefined,
+  submitButtonText: '查询',
+  resetButtonText: '重置',
+  gridProps: undefined
+})
+
+const emit = defineEmits<{
+  'reset': []
+  'submit': [data: any]
+  'update:expanded': [value: boolean]
+}>()
+
+const slots = defineSlots()
+
+const attrs = useAttrs()
+
+const formProps = computed(() => {
+  return { ...toRaw(props), ...attrs }
+})
+
+const formRef = ref<InstanceType<typeof QuiForm>>()
+const loadingSub = ref(false)
+
+const submitBtnProps = computed((): ButtonProps => {
+  return {
+    size: props.size,
+    type: 'primary',
+    ...props.submitButtonOptions
+  }
+})
+
+const resetBtnProps = computed((): ButtonProps => {
+  return {
+    size: props.size,
+    type: 'default',
+    ...props.resetButtonOptions
+  }
+})
+
+/**
+ * 提交搜索请求
+ *
+ * 校验内部表单并返回过滤后的字段值，同时触发外部 `submit` 事件。
+ *
+ * @param e - 原生点击/提交事件
+ * @returns 成功时返回过滤后的表单数据对象；失败或未挂载时返回 `false`
+ *
+ * @example
+ * ```ts
+ * await handleSubmit()
+ * ```
+ *
+ * @remarks
+ * - 内部调用 `QuiForm.validate()` 保证校验一致性
+ * - 使用 `loadingSub` 控制提交按钮 loading 状态
+ */
+async function handleSubmit(e?: Event): Promise<object | boolean> {
+  if (e) {
+    e.preventDefault()
+  }
+  loadingSub.value = true
+
+  const formEl = unref(formRef)
+  if (!formEl)
+    return false
+  try {
+    await formEl.validate()
+    const values = formEl.getFieldsValue()
+    loadingSub.value = false
+    emit('submit', values)
+    return values
+  }
+  catch (error: any) {
+    emit('submit', null)
+    loadingSub.value = false
+    console.error(error)
+    return false
+  }
+}
+
+/**
+ * 重置搜索条件
+ *
+ * 调用内部表单的重置逻辑，并根据 `submitOnReset` 配置决定是否立即提交一次。
+ *
+ * @returns 无返回值
+ *
+ * @example
+ * ```ts
+ * resetFields()
+ * ```
+ *
+ * @remarks
+ * - 当 `submitOnReset` 为 `true` 时，重置后调用 `handleSubmit`
+ */
+async function resetFields(): Promise<void> {
+  await formRef.value?.resetFields()
+  if (props.submitOnReset) {
+    await handleSubmit()
+  }
+}
+
+const expandedNames = ref<string[]>([])
+
+const isControlledExpanded = computed(() => typeof props.expanded !== 'undefined')
+
+watch(
+  () => props.expanded,
+  (val) => {
+    if (typeof val !== 'undefined') {
+      expandedNames.value = val ? ['search'] : []
+    }
+  },
+  { immediate: true }
+)
+
+watch(
+  expandedNames,
+  (names) => {
+    emit('update:expanded', !!names.length)
+  }
+)
+
+/**
+ * 展开搜索栏
+ *
+ * @example
+ * ```ts
+ * expandedBar()
+ * ```
+ */
+function expandedBar() {
+  expandedNames.value = ['search']
+}
+
+/**
+ * 收起搜索栏
+ *
+ * @example
+ * ```ts
+ * closeBar()
+ * ```
+ */
+function closeBar() {
+  expandedNames.value = []
+}
+
+/**
+ * 表单重置事件处理
+ *
+ * 透传外部 `reset` 事件，并按需触发提交。
+ */
+async function onFormReset() {
+  emit('reset')
+  if (props.submitOnReset) {
+    await handleSubmit()
+  }
+}
+
+onMounted(() => {
+  if (!props.showAdvancedButton && !isControlledExpanded.value) {
+    expandedBar()
+  }
+})
+
+watchEffect(() => {
+  if (props.showAdvancedButton === false && !isControlledExpanded.value) {
+    expandedBar()
+  }
+})
+
+/**
+ * 获取去除空值的表单字段
+ *
+ * 过滤 `null/undefined` 字段，避免将无效条件提交至后端。
+ *
+ * @returns 仅包含有效值的表单对象
+ */
+function getFilteredFieldsValue() {
+  const state = formRef.value?.getFieldsValue() ?? {}
+  const formState = {} as typeof state
+
+  for (const key in state) {
+    if (!isNullOrUnDef(state[key])) {
+      formState[key] = state[key]
+    }
+  }
+  return formState
+}
+
+defineExpose({
+  getFormRef: () => formRef.value,
+  getFieldsValue: getFilteredFieldsValue,
+  submit: handleSubmit,
+  reset: resetFields,
+  expandedBar,
+  closeBar,
+  /**
+   * 设置搜索数据并自动展开
+   *
+   * @param data - 需要写入的搜索条件键值对
+   */
+  setSearchData: async (data: Recordable) => {
+    expandedBar()
+    await nextTick()
+    formRef.value?.setFieldsValue(data)
+  },
+  resetFields
+})
+</script>
+
+<template>
+  <NCard size="small">
+    <NCollapse v-model:expanded-names="expandedNames" class="select-none" display-directive="show">
+      <template v-if="showAdvancedButton" #header-extra>
+        <NFlex align="center" :gap="0" class="text-purple-8">
+          {{ expandedNames.length ? '关闭' : '展开' }}
+          <i v-if="!expandedNames.length" class="i-mdi-arrow-up-down-bold" />
+          <i v-else class="i-mdi-arrow-collapse-vertical" />
+        </NFlex>
+      </template>
+      <NCollapseItem :title="title" name="search">
+        <QuiForm ref="formRef" v-bind="formProps" size="small" @reset="onFormReset">
+          <template v-for="(_, key, i) in slots" :key="i" #[key]="{ model, field, value }">
+            <slot :name="key" :model="model" :field="field" :value="value" />
+          </template>
+          <template #action-button>
+            <NButton
+              v-if="showSubmitButton"
+              size="small"
+              v-bind="submitBtnProps"
+              :loading="loadingSub"
+              attr-type="submit"
+              secondary
+              @click="handleSubmit"
+            >
+              <template #icon>
+                <i class="i-ic-round-search text-icon" />
+              </template>
+              {{ submitButtonText }}
+            </NButton>
+            <NButton v-if="showResetButton" size="small" secondary v-bind="resetBtnProps" @click="resetFields">
+              <template #icon>
+                <i class="i-ic-round-refresh text-icon" />
+              </template>
+              {{ resetButtonText }}
+            </NButton>
+          </template>
+        </QuiForm>
+      </NCollapseItem>
+    </NCollapse>
+  </NCard>
+</template>
+
+<style lang="scss" scoped></style>

package/src/components/search-bar/props.ts

@@ -0,0 +1,26 @@
+import type { ButtonProps } from 'naive-ui'
+import type { FormProps } from '../form'
+
+export interface Props extends FormProps {
+  title?: string
+  // 是否显示操作按钮（查询/重置）
+  showActionButtonGroup?: boolean
+  // 显示重置按钮
+  showResetButton?: boolean
+  // 重置按钮配置
+  resetButtonOptions?: ButtonProps
+  // 显示确认按钮
+  showSubmitButton?: boolean
+  // 确认按钮配置
+  submitButtonOptions?: ButtonProps
+  // 展开收起按钮
+  showAdvancedButton?: boolean
+  // 受控的展开状态
+  expanded?: boolean
+  // 确认按钮文字
+  submitButtonText?: string
+  // 重置按钮文字
+  resetButtonText?: string
+  // 重置时是否提交表单
+  submitOnReset?: boolean
+}