@coffic/cosy-ui 0.9.18 → 0.9.20

package/dist/src-astro/loading-overlay/LoadingOverlay.astro

@@ -3,17 +3,15 @@
  * @component LoadingOverlay
  *
  * @description
- * LoadingOverlay 组件是一个全屏加载弹出层，用于在页面跳转时显示加载状态。
- * 它监听 Astro 的页面过渡事件，在跳转开始时延迟显示，跳转完成后隐藏。
- * 为了避免频繁的视觉干扰，只有在加载时间超过指定延迟时间（默认1秒）时才显示。
+ * LoadingOverlay 组件是一个全屏加载遮罩层，用于在页面加载或路由切换时显示加载状态。
+ * 它提供了多种加载动画类型，支持延迟显示和背景模糊效果，确保良好的用户体验。
  *
  * @design
  * 设计理念：
- * 1. 全屏覆盖 - 使用固定定位覆盖整个视口
- * 2. 居中显示 - 加载指示器在屏幕中央显示
- * 3. 平滑动画 - 使用淡入淡出动画效果
- * 4. 延迟显示 - 避免短时间加载的视觉干扰
- * 5. 可定制性 - 支持自定义加载文本、样式和延迟时间
+ * 1. 用户体验优先 - 通过延迟显示避免闪烁，确保最小显示时间
+ * 2. 视觉反馈 - 提供多种动画类型，满足不同场景需求
+ * 3. 无障碍设计 - 支持键盘导航和屏幕阅读器
+ * 4. 性能优化 - 使用 CSS 动画和事件监听，避免阻塞主线程
  *
  * @usage
  * 基本用法：
@@ -22,22 +20,53 @@
  * import { LoadingOverlay } from '@coffic/cosy-ui';
  * ---
  *
- * <LoadingOverlay />
+ * <LoadingOverlay text="正在加载..." />
  * ```
  *
- * 自定义延迟时间：
+ * 自定义动画类型：
  * ```astro
- * <LoadingOverlay delay={2000} text="页面加载中..." />
+ * <LoadingOverlay
+ *   text="处理中..."
+ *   spinnerType="spinner"
+ *   loadingDelay={500}
+ * />
+ * ```
+ *
+ * 无背景遮罩：
+ * ```astro
+ * <LoadingOverlay
+ *   text="加载中..."
+ *   showBackdrop={false}
+ *   class="cosy:bg-transparent"
+ * />
  * ```
  *
  * 自定义样式：
  * ```astro
  * <LoadingOverlay
- *   text="正在跳转..."
- *   class="custom-loading-overlay"
- *   delay={1500}
+ *   text="请稍候..."
+ *   spinnerType="pulse"
+ *   class="cosy:bg-blue-500/20"
  * />
  * ```
+ *
+ * @props
+ * - text?: string - 加载文本，默认为 "Loading..."
+ * - class?: string - 自定义 CSS 类名
+ * - showSpinner?: boolean - 是否显示加载动画，默认为 true
+ * - spinnerType?: 'dots' | 'spinner' | 'pulse' - 加载动画类型，默认为 'dots'
+ * - loadingDelay?: number - 延迟显示时间（毫秒），默认为 1000ms
+ * - showBackdrop?: boolean - 是否显示背景模糊遮罩，默认为 true
+ *
+ * @slots
+ * 此组件没有插槽，所有内容通过 props 配置
+ *
+ * @events
+ * 组件会自动监听以下 Astro 事件：
+ * - astro:page-load - 页面加载完成时隐藏
+ * - astro:before-preparation - 页面准备前显示
+ * - astro:before-swap - 路由切换前显示
+ * - astro:after-swap - 路由切换后隐藏
  */
 
 import '../../style.ts';
@@ -53,6 +82,8 @@ export interface Props {
   spinnerType?: 'dots' | 'spinner' | 'pulse';
   /** 延迟显示时间（毫秒），默认1000ms */
   loadingDelay?: number;
+  /** 是否显示背景模糊遮罩，默认true */
+  showBackdrop?: boolean;
 }
 
 const {
@@ -61,23 +92,26 @@ const {
   showSpinner = true,
   spinnerType = 'dots',
   loadingDelay = 1000,
+  showBackdrop = true,
 } = Astro.props;
 
 // 生成唯一的 ID
-const overlayId = `loading-overlay-${Math.random().toString(36).substr(2, 9)}`;
+const overlayId = `loading-overlay`;
 ---
 
 <div
   id={overlayId}
+  transition:persist
   class:list={[
-    'cosy:fixed cosy:inset-0 cosy:z-[9999] cosy:bg-black/50 cosy:backdrop-blur-sm',
+    'cosy:fixed cosy:inset-0 cosy:z-[9999]',
+    showBackdrop ? 'cosy:bg-black/50 cosy:backdrop-blur-sm' : '',
     'cosy:flex cosy:items-center cosy:justify-center',
     'cosy:opacity-0 cosy:pointer-events-none cosy:transition-opacity cosy:duration-300',
     className,
   ]}
   data-loading-overlay>
   <div
-    class="cosy:bg-white cosy:dark:bg-gray-800 cosy:rounded-lg cosy:shadow-xl cosy:p-6 cosy:max-w-sm cosy:w-full cosy:mx-4">
+    class="cosy:bg-accent cosy:rounded-lg cosy:shadow-xl cosy:p-6 cosy:max-w-sm cosy:w-full cosy:mx-4">
     <div class="cosy:flex cosy:flex-col cosy:items-center cosy:space-y-4">
       {
         showSpinner && (
@@ -112,67 +146,105 @@ const overlayId = `loading-overlay-${Math.random().toString(36).substr(2, 9)}`;
   </div>
 </div>
 
-<script define:vars={{ overlayId, loadingDelay }}>
-  // 获取加载弹出层元素
-  const overlay = document.getElementById(overlayId);
-
-  if (overlay) {
-    let loadingStartTime = null;
-    let showTimeout = null;
-    let isLoading = false;
-
-    // 显示加载弹出层的函数
-    const showOverlay = () => {
-      if (isLoading) return;
-
-      isLoading = true;
-      loadingStartTime = Date.now();
-
-      // 延迟显示，避免短时间加载的视觉干扰
-      showTimeout = window.setTimeout(() => {
-        overlay.style.opacity = '1';
-        overlay.style.pointerEvents = 'auto';
-      }, loadingDelay);
-    };
-
-    // 隐藏加载弹出层的函数
-    const hideOverlay = () => {
-      if (showTimeout) {
-        clearTimeout(showTimeout);
-        showTimeout = null;
+<script is:inline define:vars={{ overlayId, loadingDelay }}>
+  let showTimeout = null;
+  let hideTimeout = null;
+  let displayStartTime = null;
+  let loaded = false;
+  const minDisplayTime = 1000;
+
+  const reset = () => {
+    displayStartTime = null;
+  };
+
+  const isDomDisplayed = () => {
+    const overlay = document.getElementById(overlayId);
+    if (!overlay) {
+      return false;
+    }
+    return (
+      overlay.style.opacity === '1' && overlay.style.pointerEvents === 'auto'
+    );
+  };
+
+  // 显示加载弹出层的函数
+  const showOverlay = () => {
+    if (isDomDisplayed() || loaded) return;
+
+    // 设置延迟显示
+    showTimeout = setTimeout(() => {
+      const overlay = document.getElementById(overlayId);
+      if (!overlay) {
+        return;
       }
 
-      isLoading = false;
-      loadingStartTime = null;
+      if (loaded) {
+        return;
+      }
+
+      overlay.style.opacity = '1';
+      overlay.style.pointerEvents = 'auto';
+      displayStartTime = Date.now();
+    }, loadingDelay);
+  };
+
+  // 隐藏加载弹出层的函数
+  const hideOverlay = (reason) => {
+    console.log('LoadingOverlay: hideOverlay', reason);
+
+    // 清除显示延迟
+    if (showTimeout) {
+      clearTimeout(showTimeout);
+      showTimeout = null;
+    }
+
+    // 如果没有显示
+    if (!isDomDisplayed()) {
+      reset();
+      return;
+    }
+
+    hideTimeout = setTimeout(() => {
+      const overlay = document.getElementById(overlayId);
+      if (!overlay) {
+        return;
+      }
 
       overlay.style.opacity = '0';
       overlay.style.pointerEvents = 'none';
-    };
-
-    // 监听 Astro 页面过渡事件
-    document.addEventListener('astro:page-load', () => {
-      hideOverlay();
-    });
-
-    document.addEventListener('astro:before-preparation', () => {
-      showOverlay();
-    });
-
-    // 监听路由变化
-    document.addEventListener('astro:before-swap', () => {
-      showOverlay();
-    });
-
-    document.addEventListener('astro:after-swap', () => {
-      // 如果加载时间很短，立即隐藏
-      if (loadingStartTime && Date.now() - loadingStartTime < loadingDelay) {
-        hideOverlay();
-      } else {
-        // 否则延迟隐藏，给用户一个视觉反馈
-        setTimeout(() => {
-          hideOverlay();
-        }, 100);
-      }
-    });
-  }
+      reset();
+    }, minDisplayTime);
+  };
+
+  // 监听 Astro 页面过渡事件
+  document.addEventListener('astro:page-load', () => {
+    loaded = true;
+    hideOverlay('astro:page-load');
+  });
+
+  document.addEventListener('astro:before-preparation', () => {
+    loaded = false;
+    showOverlay('astro:before-preparation');
+  });
+
+  // 监听路由变化
+  document.addEventListener('astro:before-swap', () => {
+    loaded = false;
+    showOverlay('astro:before-swap');
+  });
+
+  document.addEventListener('astro:after-swap', () => {
+    loaded = true;
+    hideOverlay('astro:after-swap');
+  });
+
+  // 页面卸载时清理定时器
+  window.addEventListener('beforeunload', () => {
+    if (showTimeout) {
+      clearTimeout(showTimeout);
+    }
+    if (hideTimeout) {
+      clearTimeout(hideTimeout);
+    }
+  });
 </script>

package/dist/src-astro/loading-overlay/index.ts

@@ -1,2 +1,2 @@
 export { default as LoadingOverlay } from './LoadingOverlay.astro';
-export type { LoadingOverlayProps } from './types'; 
+export type { Props as LoadingOverlayProps } from './LoadingOverlay.astro'; 

package/dist/src-astro/sidebar/MobileNav.astro

@@ -0,0 +1,55 @@
+---
+/**
+ * MobileNav组件
+ *
+ * 移动端导航栏组件
+ */
+
+import { MenuIcon } from '../../index-astro';
+import { isPathMatch } from '../../src/utils/path.ts';
+import type { ISidebarItem } from '../types/sidebar.ts';
+
+interface Props {
+  /**
+   * 侧边栏项目
+   */
+  sidebarItems: ISidebarItem[];
+
+  /**
+   * 当前路径
+   */
+  currentPath: string;
+
+  /**
+   * 是否开启调试模式
+   */
+  debug?: boolean;
+}
+
+const { sidebarItems, currentPath, debug = false } = Astro.props;
+
+const debugClass = debug ? 'cosy:border cosy:border-red-500' : '';
+
+// 获取当前活动的一级导航项
+const currentSection = sidebarItems.find((section) =>
+  section.items?.some((item) => isPathMatch(currentPath, item.href))
+);
+---
+
+<div
+  class:list={[
+    'cosy:flex cosy:lg:hidden cosy:items-center cosy:justify-between cosy:px-4 cosy:py-2 cosy:border-b cosy:border-base-300 cosy:bg-base-100 cosy:relative cosy:z-10',
+    debugClass,
+  ]}>
+  <div class="cosy:flex cosy:items-center cosy:gap-2">
+    <button
+      type="button"
+      class="cosy:p-2 cosy:btn cosy:btn-ghost cosy:btn-sm"
+      data-modal-target="mobile-sidebar">
+      <MenuIcon class="cosy:w-5 cosy:h-5" />
+    </button>
+    <span class="cosy:font-medium cosy:text-sm">
+      {currentSection?.text || '导航'}
+    </span>
+  </div>
+</div>

package/dist/src-astro/sidebar/NavItem.astro

@@ -0,0 +1,100 @@
+---
+/**
+ * NavItem组件
+ *
+ * 递归渲染导航项，支持无限层级
+ */
+
+import { isPathMatch } from '../../src/utils/path.ts';
+import '../../style.ts';
+import type { ISidebarItem } from '../types/sidebar.ts';
+
+interface Props {
+  /**
+   * 导航项
+   */
+  item: ISidebarItem;
+
+  /**
+   * 当前路径
+   */
+  currentPath: string;
+
+  /**
+   * 嵌套层级
+   * @default 0
+   */
+  level?: number;
+
+  /**
+   * 是否开启调试模式
+   */
+  debug?: boolean;
+}
+
+const { item, currentPath, level = 0, debug = false } = Astro.props;
+
+const debugClass = debug ? 'cosy:border cosy:border-red-500' : '';
+const isActive = isPathMatch(currentPath, item.href);
+const badgeSize = level === 0 ? 'cosy:badge-sm' : 'cosy:badge-xs';
+---
+
+<li class:list={[debugClass, level === 0 ? 'cosy:no-underline' : '']}>
+  <a
+    data-sidebar-item
+    data-current-path={currentPath}
+    data-href={item.href}
+    href={item.href}
+    class:list={[
+      'cosy:hover:bg-base-300',
+      level === 0 ? 'cosy:no-underline' : '',
+      { 'cosy:menu-active': isActive },
+      debugClass,
+    ]}>
+    {item.text}
+    {
+      item.badge !== undefined && item.badge !== null && (
+        <span class={`cosy:badge ${badgeSize} cosy:ml-2`}>{item.badge}</span>
+      )
+    }
+  </a>
+  {
+    item.items && item.items.length > 0 && (
+      <ul class:list={[debugClass]}>
+        {item.items.map((subitem) => (
+          <Astro.self
+            item={subitem}
+            currentPath={currentPath}
+            level={level + 1}
+            debug={debug}
+          />
+        ))}
+      </ul>
+    )
+  }
+</li>
+
+<script>
+  // 立即处理导航项点击，更新高亮状态
+  document.addEventListener('click', (event) => {
+    const target = event.target as HTMLElement;
+    const navItem = target.closest('[data-sidebar-item]') as HTMLAnchorElement;
+
+    if (navItem) {
+      // 立即移除所有导航项的高亮状态
+      const allNavItems = document.querySelectorAll('[data-sidebar-item]');
+      allNavItems.forEach((item) => {
+        item.classList.remove('cosy:menu-active');
+      });
+
+      // 立即为当前点击的导航项添加高亮状态
+      navItem.classList.add('cosy:menu-active');
+
+      // 可选：添加一个短暂的视觉反馈
+      navItem.style.transition = 'background-color 0.2s ease';
+      setTimeout(() => {
+        navItem.style.transition = '';
+      }, 200);
+    }
+  });
+</script>

package/dist/src-astro/sidebar/Sidebar.astro

@@ -22,8 +22,9 @@
  */
 
 import '../../style.ts';
-import { isPathMatch } from '../../src/utils/path.ts';
-import { MenuIcon, SidebarNav, Modal } from '../../index-astro';
+import { SidebarNav, Modal } from '../../index-astro';
+import { getMarginTopClass, getMarginBottomClass } from './utils.ts';
+import MobileNav from './MobileNav.astro';
 import type { ISidebarProps } from '../../index-astro';
 
 export interface Props extends ISidebarProps {}
@@ -40,65 +41,22 @@ const {
 const currentPath = Astro.url.pathname;
 
 const debugClass = debug ? 'cosy:border cosy:border-red-500' : '';
-
-function getVerticalMarginTopClasses(marginTop: string) {
-  if (marginTop === 'none') return 'cosy:mt-0';
-  if (marginTop === 'xs') return 'cosy:mt-1';
-  if (marginTop === 'sm') return 'cosy:mt-2';
-  if (marginTop === 'md') return 'cosy:mt-4';
-  if (marginTop === 'lg') return 'cosy:mt-6';
-  if (marginTop === 'xl') return 'cosy:mt-8';
-  if (marginTop === '2xl') return 'cosy:mt-10';
-  if (marginTop === '3xl') return 'cosy:mt-12';
-  if (marginTop === '4xl') return 'cosy:mt-16';
-  if (marginTop === '5xl') return 'cosy:mt-20';
-  return '';
-}
-
-function getVerticalMarginBottomClasses(marginBottom: string) {
-  if (marginBottom === 'none') return 'cosy:mb-0';
-  if (marginBottom === 'xs') return 'cosy:mb-1';
-  if (marginBottom === 'sm') return 'cosy:mb-2';
-  if (marginBottom === 'md') return 'cosy:mb-4';
-  if (marginBottom === 'lg') return 'cosy:mb-6';
-  if (marginBottom === 'xl') return 'cosy:mb-8';
-  if (marginBottom === '2xl') return 'cosy:mb-10';
-  if (marginBottom === '3xl') return 'cosy:mb-12';
-  if (marginBottom === '4xl') return 'cosy:mb-16';
-  if (marginBottom === '5xl') return 'cosy:mb-20';
-  return '';
-}
-
-// 获取当前活动的一级导航项
-const currentSection = sidebarItems.find((section) =>
-  section.items?.some((item) => isPathMatch(currentPath, item.href))
-);
 ---
 
 {/* 移动端导航栏 */}
-<div
-  class:list={[
-    'cosy:flex cosy:lg:hidden cosy:items-center cosy:justify-between cosy:px-4 cosy:py-2 cosy:border-b cosy:border-base-300 cosy:bg-base-100 cosy:relative cosy:z-10',
-    debugClass,
-  ]}>
-  <div class="cosy:flex cosy:items-center cosy:gap-2">
-    <button
-      type="button"
-      class="cosy:p-2 cosy:btn cosy:btn-ghost cosy:btn-sm"
-      data-modal-target="mobile-sidebar">
-      <MenuIcon class="cosy:w-5 cosy:h-5" />
-    </button>
-    <span class="cosy:font-medium cosy:text-sm"
-      >{currentSection?.text || '导航'}</span
-    >
-  </div>
-</div>
+<MobileNav
+  sidebarItems={sidebarItems}
+  currentPath={currentPath}
+  debug={debug}
+/>
 
 {/* 移动端侧边栏弹出层 */}
 <Modal
   id="mobile-sidebar"
   class="cosy:mx-4 cosy:lg:w-80 cosy:w-[calc(100vw-2rem)] cosy:max-w-full">
-  <div class="cosy:h-[calc(100vh-8rem)] cosy:overflow-y-auto">
+  <div
+    class="cosy:h-[calc(100vh-8rem)] cosy:overflow-y-auto"
+    data-mobile-sidebar-content>
     <SidebarNav
       sidebarItems={sidebarItems}
       currentPath={currentPath}
@@ -117,11 +75,12 @@ const currentSection = sidebarItems.find((section) =>
     className,
     debugClass,
     'cosy:hidden cosy:lg:block',
-    getVerticalMarginTopClasses(marginTop),
-    getVerticalMarginBottomClasses(marginBottom),
+    getMarginTopClass(marginTop),
+    getMarginBottomClass(marginBottom),
   ]}>
   <div
-    class="cosy:top-16 cosy:sticky cosy:pb-48 cosy:h-[calc(100vh-0rem)] cosy:overflow-y-auto">
+    class="cosy:top-16 cosy:sticky cosy:pb-48 cosy:h-[calc(100vh-0rem)] cosy:overflow-y-auto"
+    data-desktop-sidebar-content>
     <SidebarNav
       sidebarItems={sidebarItems}
       currentPath={currentPath}
@@ -131,62 +90,42 @@ const currentSection = sidebarItems.find((section) =>
 </aside>
 
 <script>
+  import { saveScrollPosition, restoreScrollPosition } from './utils.ts';
+
   // 处理侧边栏滚动位置保存和恢复
   document.addEventListener('astro:before-preparation', () => {
-    // 获取桌面侧边栏滚动容器
-    const desktopSidebarContent = document.querySelector(
-      'aside[data-sidebar] .cosy\\:overflow-y-auto'
+    // 保存桌面端滚动位置
+    const desktopContent = document.querySelector(
+      '[data-desktop-sidebar-content]'
     );
-
-    // 保存滚动位置到localStorage
-    if (desktopSidebarContent) {
-      localStorage.setItem(
-        'sidebarScrollPosition',
-        desktopSidebarContent.scrollTop.toString()
-      );
+    if (desktopContent) {
+      saveScrollPosition(desktopContent, 'sidebarScrollPosition');
     }
 
-    // 获取移动端侧边栏滚动容器
-    const mobileSidebarContent = document.querySelector(
-      '.cosy\\:h-\\[calc\\(100vh-8rem\\)\\].cosy\\:overflow-y-auto'
-    );
-
     // 保存移动端滚动位置
-    if (mobileSidebarContent) {
-      localStorage.setItem(
-        'mobileSidebarScrollPosition',
-        mobileSidebarContent.scrollTop.toString()
-      );
+    const mobileContent = document.querySelector(
+      '[data-mobile-sidebar-content]'
+    );
+    if (mobileContent) {
+      saveScrollPosition(mobileContent, 'mobileSidebarScrollPosition');
     }
   });
 
   document.addEventListener('astro:page-load', () => {
-    // 获取桌面侧边栏滚动容器
-    const desktopSidebarContent = document.querySelector(
-      'aside[data-sidebar] .cosy\\:overflow-y-auto'
+    // 恢复桌面端滚动位置
+    const desktopContent = document.querySelector(
+      '[data-desktop-sidebar-content]'
     );
-
-    // 恢复滚动位置
-    if (desktopSidebarContent) {
-      const savedPosition = localStorage.getItem('sidebarScrollPosition');
-      if (savedPosition) {
-        desktopSidebarContent.scrollTop = parseInt(savedPosition, 10);
-      }
+    if (desktopContent) {
+      restoreScrollPosition(desktopContent, 'sidebarScrollPosition');
     }
 
-    // 获取移动端侧边栏滚动容器
-    const mobileSidebarContent = document.querySelector(
-      '.cosy\\:h-\\[calc\\(100vh-8rem\\)\\].cosy\\:overflow-y-auto'
-    );
-
     // 恢复移动端滚动位置
-    if (mobileSidebarContent) {
-      const savedMobilePosition = localStorage.getItem(
-        'mobileSidebarScrollPosition'
-      );
-      if (savedMobilePosition) {
-        mobileSidebarContent.scrollTop = parseInt(savedMobilePosition, 10);
-      }
+    const mobileContent = document.querySelector(
+      '[data-mobile-sidebar-content]'
+    );
+    if (mobileContent) {
+      restoreScrollPosition(mobileContent, 'mobileSidebarScrollPosition');
     }
   });
 </script>