@coffic/cosy-ui 0.1.29 → 0.2.0

package/dist/components/navigation/LanguageSwitcher.astro

@@ -0,0 +1,81 @@
+---
+import Button from '../base/Button.astro';
+import Link from '../base/Link.astro';
+
+interface Language {
+  code: string;
+  name: string;
+}
+
+interface Props {
+  /**
+   * 自定义类名
+   */
+  class?: string;
+
+  /**
+   * 语言列表
+   * @default [{ code: 'zh-cn', name: '简体中文' }, { code: 'en', name: 'English' }]
+   */
+  languages?: Language[];
+
+  /**
+   * 当前语言
+   * @default 'zh-cn'
+   */
+  currentLocale?: string;
+}
+
+const {
+  class: className,
+  languages = [
+    { code: 'zh-cn', name: '简体中文' },
+    { code: 'en', name: 'English' },
+  ],
+  currentLocale = 'zh-cn',
+} = Astro.props;
+
+const currentLanguageName =
+  languages.find((lang: Language) => lang.code === currentLocale)?.name || '简体中文';
+
+// 为每个语言生成对应的URL
+function generateLanguageUrl(langCode: string): string {
+  const currentPath = Astro.url.pathname;
+  const pathParts = currentPath.split('/').filter(Boolean);
+  const firstPathPart = pathParts[0];
+  const supportedLanguages = languages.map((lang: Language) => lang.code);
+  const isFirstPartLang = supportedLanguages.includes(firstPathPart);
+
+  if (isFirstPartLang) {
+    pathParts[0] = langCode;
+    return '/' + pathParts.join('/');
+  } else {
+    return '/' + langCode + (currentPath === '/' ? '' : currentPath);
+  }
+}
+---
+
+<div class:list={["dropdown-end dropdown", className]}>
+  <Button variant="ghost" size="sm" class="p-1">
+    {currentLanguageName}
+  </Button>
+  <ul
+    tabindex={0}
+    class="dropdown-content menu w-40 rounded-box bg-slate-900 p-2 shadow-lg dark:bg-slate-800"
+  >
+    {
+      languages.map((lang: Language) => (
+        <li>
+          <Link 
+            href={generateLanguageUrl(lang.code)}
+            class:list={[
+              { active: lang.code === currentLocale }
+            ]}
+          >
+            {lang.name}
+          </Link>
+        </li>
+      ))
+    }
+  </ul>
+</div> 

package/dist/components/navigation/README.md

@@ -0,0 +1,24 @@
+# 导航组件 (Navigation Components)
+
+这个目录包含了与网站导航和用户界面导航相关的组件。
+
+## 设计原则
+
+1. **直观性**：导航应该清晰易懂，用户能够直观地理解如何使用
+2. **一致性**：导航行为和样式应该在整个应用中保持一致
+3. **响应式**：适应不同的屏幕尺寸和设备类型
+
+## 包含的组件
+
+- `LanguageSwitcher.astro`: 语言切换组件
+- `ThemeSwitcher.astro`: 主题切换组件
+- `TableOfContents.astro`: 目录导航组件
+
+## 使用指南
+
+导航组件通常需要配置相应的数据和回调函数：
+
+```astro
+<LanguageSwitcher languages={['zh', 'en']} />
+<TableOfContents items={tocItems} />
+``` 

package/dist/components/navigation/TableOfContents.astro

@@ -0,0 +1,352 @@
+---
+/**
+ * @component TableOfContents
+ * 
+ * @description
+ * TableOfContents 组件是一个目录导航组件，用于显示页面内容的标题结构。
+ * 它会自动检测页面中的标题元素，生成目录列表，并在用户滚动页面时高亮当前可见的标题。
+ * 
+ * @design
+ * 设计理念：
+ * 1. 导航辅助 - 帮助用户快速了解页面结构和导航到特定内容
+ * 2. 上下文感知 - 自动高亮当前阅读位置，提供阅读进度反馈
+ * 3. 视觉层次 - 通过缩进和样式区分不同级别的标题
+ * 4. 响应式设计 - 在小屏幕设备上自动隐藏，优化空间利用
+ * 
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <TableOfContents />
+ * ```
+ * 
+ * 自定义标题和选择器：
+ * ```astro
+ * <TableOfContents 
+ *   title="章节导航" 
+ *   selector="h2, h3, h4" 
+ *   maxDepth={4} 
+ * />
+ * ```
+ * 
+ * 非固定位置：
+ * ```astro
+ * <TableOfContents fixed={false} />
+ * ```
+ * 
+ * 指定内容容器：
+ * ```astro
+ * <TableOfContents containerSelector=".article-content" />
+ * ```
+ */
+
+// 导入样式
+import '../../app.css';
+
+interface Props {
+  /**
+   * 是否固定在右侧
+   * @default true
+   */
+  fixed?: boolean;
+  /**
+   * 自定义类名
+   */
+  class?: string;
+  /**
+   * 标题选择器
+   * @default "h2, h3"
+   */
+  selector?: string;
+  /**
+   * 最大深度
+   * @default 3
+   */
+  maxDepth?: number;
+  /**
+   * 标题文本
+   * @default "目录"
+   */
+  title?: string;
+  /**
+   * 内容容器选择器，用于限制标题搜索范围
+   * @default "main"
+   */
+  containerSelector?: string;
+}
+
+const {
+  fixed = true,
+  class: className = '',
+  selector = 'h2, h3',
+  maxDepth = 3,
+  title = '目录',
+  containerSelector = 'main',
+} = Astro.props;
+
+// 生成唯一ID，确保多个TOC实例不会冲突
+const tocId = `toc-${Math.random().toString(36).substring(2, 9)}`;
+---
+
+<div class={`toc ${fixed ? 'toc-fixed' : ''} ${className}`}>
+  <div class="toc-container">
+    <div class="toc-title">{title}</div>
+    <ul class="toc-list" id={tocId}>
+      <!-- 目录项将通过 JavaScript 动态生成 -->
+      <li class="toc-placeholder">加载中...</li>
+    </ul>
+  </div>
+</div>
+
+<script define:vars={{ selector, maxDepth, tocId, containerSelector }}>
+  // 在页面加载完成后生成目录
+  function generateTOC() {
+    // 使用指定的容器选择器查找内容容器
+    const container = document.querySelector(containerSelector);
+    if (!container) return;
+    
+    // 只查找容器内的标题，而不是整个页面
+    const headings = container.querySelectorAll(selector);
+    const tocList = document.getElementById(tocId);
+    
+    if (!tocList || headings.length === 0) return;
+    
+    // 清空占位符
+    tocList.innerHTML = '';
+    
+    // 用于存储已使用的 ID，确保唯一性
+    const usedIds = new Set();
+    
+    // 为每个标题创建目录项
+    headings.forEach((heading) => {
+      // 如果标题没有 ID 或 ID 为空，则生成一个
+      if (!heading.id || heading.id.trim() === '') {
+        // 从标题文本生成 ID
+        let newId = generateIdFromText(heading.textContent || '');
+        
+        // 确保 ID 唯一
+        let counter = 0;
+        let uniqueId = newId;
+        while (usedIds.has(uniqueId) || document.getElementById(uniqueId)) {
+          counter++;
+          uniqueId = `${newId}-${counter}`;
+        }
+        
+        // 设置标题的 ID
+        heading.id = uniqueId;
+      }
+      
+      // 记录已使用的 ID
+      usedIds.add(heading.id);
+      
+      const level = parseInt(heading.tagName.substring(1));
+      if (level > maxDepth) return;
+      
+      const listItem = document.createElement('li');
+      listItem.className = `toc-item toc-level-${level}`;
+      listItem.dataset.headingId = heading.id; // 添加数据属性，便于后续查找
+      
+      const link = document.createElement('a');
+      link.href = `#${heading.id}`;
+      link.textContent = heading.textContent;
+      link.className = 'toc-link';
+      
+      // 添加前缀标记，增强视觉层次
+      if (level === 3) {
+        const prefix = document.createElement('span');
+        prefix.className = 'toc-prefix';
+        prefix.innerHTML = '└─ ';
+        link.prepend(prefix);
+      }
+      
+      listItem.appendChild(link);
+      tocList.appendChild(listItem);
+      
+      // 添加点击事件，平滑滚动到目标位置
+      link.addEventListener('click', (e) => {
+        e.preventDefault();
+        const targetId = link.getAttribute('href').substring(1);
+        const targetElement = document.getElementById(targetId);
+        
+        if (targetElement) {
+          // 滚动到目标位置，并添加一些偏移以避免被固定导航遮挡
+          const offset = 80; // 可根据实际情况调整
+          const targetPosition = targetElement.getBoundingClientRect().top + window.scrollY - offset;
+          
+          window.scrollTo({
+            top: targetPosition,
+            behavior: 'smooth'
+          });
+          
+          // 更新 URL，但不跳转
+          history.pushState(null, null, `#${targetId}`);
+          
+          // 添加高亮效果
+          setTimeout(() => {
+            highlightActiveHeading();
+          }, 500);
+        }
+      });
+    });
+    
+    // 如果没有找到标题，显示提示信息
+    if (tocList.children.length === 0) {
+      const listItem = document.createElement('li');
+      listItem.textContent = '没有找到标题';
+      listItem.className = 'toc-empty';
+      tocList.appendChild(listItem);
+    }
+    
+    // 添加活动标题高亮
+    highlightActiveHeading();
+    
+    // 使用节流函数优化滚动事件
+    window.addEventListener('scroll', throttle(highlightActiveHeading, 100));
+  }
+  
+  // 从文本生成有效的 ID
+  function generateIdFromText(text) {
+    return text
+      .trim()
+      .toLowerCase()
+      .replace(/[\s\n]+/g, '-') // 将空格和换行替换为连字符
+      .replace(/[^\w\u4e00-\u9fa5-]/g, '') // 只保留字母、数字、中文和连字符
+      .replace(/^-+|-+$/g, '') // 移除开头和结尾的连字符
+      .replace(/-{2,}/g, '-') // 将多个连字符替换为单个
+      || 'heading'; // 如果结果为空，则使用默认值
+  }
+  
+  // 节流函数，限制函数调用频率
+  function throttle(func, delay) {
+    let lastCall = 0;
+    return function(...args) {
+      const now = new Date().getTime();
+      if (now - lastCall < delay) {
+        return;
+      }
+      lastCall = now;
+      return func(...args);
+    };
+  }
+  
+  // 高亮当前可见的标题
+  function highlightActiveHeading() {
+    const container = document.querySelector(containerSelector);
+    if (!container) return;
+    
+    const headings = Array.from(container.querySelectorAll(selector));
+    if (headings.length === 0) return;
+    
+    // 获取视口高度和滚动位置
+    const viewportHeight = window.innerHeight;
+    const scrollTop = window.scrollY;
+    
+    // 计算视口中心位置
+    const viewportMiddle = scrollTop + viewportHeight / 3;
+    
+    let activeHeadingId = null;
+    let closestHeading = null;
+    let closestDistance = Infinity;
+    
+    // 找到最接近视口中心的标题
+    for (const heading of headings) {
+      const headingTop = heading.getBoundingClientRect().top + scrollTop;
+      const distance = Math.abs(headingTop - viewportMiddle);
+      
+      if (distance < closestDistance) {
+        closestDistance = distance;
+        closestHeading = heading;
+      }
+    }
+    
+    // 如果找到了最接近的标题，使用它的ID
+    if (closestHeading) {
+      activeHeadingId = closestHeading.id;
+      
+      // 为当前活动标题添加一个临时的高亮效果
+      headings.forEach(h => h.classList.remove('current-heading'));
+      closestHeading.classList.add('current-heading');
+      
+      // 5秒后移除高亮效果
+      setTimeout(() => {
+        closestHeading.classList.remove('current-heading');
+      }, 5000);
+    } else if (headings.length > 0) {
+      // 如果没有找到，使用第一个标题
+      activeHeadingId = headings[0].id;
+    }
+    
+    // 更新活动链接样式
+    const tocLinks = document.querySelectorAll(`#${tocId} .toc-link`);
+    let hasActiveLink = false;
+    
+    tocLinks.forEach(link => {
+      const href = link.getAttribute('href').substring(1);
+      
+      // 清除所有高亮
+      link.classList.remove('toc-active', 'toc-parent-active');
+      
+      // 添加当前活动标题的高亮
+      if (href === activeHeadingId) {
+        link.classList.add('toc-active');
+        hasActiveLink = true;
+        
+        // 添加一个动画效果，使高亮更明显
+        link.animate([
+          { transform: 'translateX(-5px)' },
+          { transform: 'translateX(0)' }
+        ], {
+          duration: 300,
+          easing: 'ease-out'
+        });
+        
+        // 如果是 h3，也高亮相关的 h2
+        const h3Item = link.closest('.toc-level-3');
+        if (h3Item) {
+          // 找到前面最近的 h2
+          let prevItem = h3Item.previousElementSibling;
+          while (prevItem) {
+            if (prevItem.classList.contains('toc-level-2')) {
+              const h2Link = prevItem.querySelector('.toc-link');
+              if (h2Link) h2Link.classList.add('toc-parent-active');
+              break;
+            }
+            prevItem = prevItem.previousElementSibling;
+          }
+        }
+      }
+    });
+    
+    // 如果没有找到活动链接，尝试高亮第一个标题
+    if (!hasActiveLink && tocLinks.length > 0) {
+      tocLinks[0].classList.add('toc-active');
+    }
+    
+    // 确保活动链接在视图中可见
+    const activeLink = document.querySelector(`#${tocId} .toc-active`);
+    if (activeLink && tocList) {
+      const tocContainer = document.querySelector('.toc-fixed');
+      if (tocContainer) {
+        const linkTop = activeLink.offsetTop;
+        const containerScrollTop = tocContainer.scrollTop;
+        const containerHeight = tocContainer.clientHeight;
+        
+        // 如果链接不在可视区域内，滚动到可见位置
+        if (linkTop < containerScrollTop || linkTop > containerScrollTop + containerHeight) {
+          tocContainer.scrollTop = linkTop - containerHeight / 2;
+        }
+      }
+    }
+  }
+  
+  // 页面加载时初始化
+  document.addEventListener('astro:page-load', generateTOC);
+  // 初始加载时也初始化
+  generateTOC();
+  
+  // 添加resize事件监听，在窗口大小变化时重新计算高亮
+  window.addEventListener('resize', throttle(highlightActiveHeading, 100));
+  
+  // 立即触发一次高亮计算
+  setTimeout(highlightActiveHeading, 500);
+</script>
+

package/dist/components/navigation/ThemeSwitcher.astro

@@ -0,0 +1,89 @@
+---
+import Button from '../base/Button.astro';
+import SunCloudyIcon from '../icons/SunCloudyIcon.astro';
+
+interface Props {
+  /**
+   * 自定义类名
+   */
+  class?: string;
+}
+
+const { class: className } = Astro.props;
+
+const themes = [
+  { id: 'default', name: 'Default' },
+  { id: 'light', name: 'Light' },
+  { id: 'dark', name: 'Dark' },
+  { id: 'pastel', name: 'Pastel' },
+  { id: 'lemonade', name: 'Lemonade' },
+  { id: 'cupcake', name: 'Cupcake' },
+  { id: 'nord', name: 'Nord' },
+  { id: 'business', name: 'Business' },
+  { id: 'luxury', name: 'Luxury' },
+];
+---
+
+<div class:list={["dropdown-end dropdown", className]}>
+  <Button variant="ghost" size="sm" class="p-1">
+    <SunCloudyIcon class="h-5 w-5" slot="icon-left" />
+  </Button>
+  <ul
+    tabindex="0"
+    class="dropdown-content menu w-56 rounded-box bg-neutral-900 p-2 shadow-lg dark:bg-neutral-800"
+  >
+    {themes.map((theme) => (
+      <li>
+        <button
+          class="theme-item"
+          data-theme={theme.id}
+          data-active={false}
+        >
+          {theme.name}
+        </button>
+      </li>
+    ))}
+  </ul>
+</div>
+
+<script>
+  import { createThemeManager } from '../../utils/theme';
+
+  const themeManager = createThemeManager();
+
+  function updateActiveTheme() {
+    const currentTheme = document.documentElement.getAttribute('data-theme') || 'default';
+    document.querySelectorAll('.theme-item').forEach((item) => {
+      const isActive = item.getAttribute('data-theme') === currentTheme;
+      item.setAttribute('data-active', String(isActive));
+      if (isActive) {
+        item.classList.add('active');
+      } else {
+        item.classList.remove('active');
+      }
+    });
+  }
+
+  // 初始化主题切换按钮
+  document.querySelectorAll('.theme-item').forEach((item) => {
+    item.addEventListener('click', () => {
+      const theme = item.getAttribute('data-theme');
+      if (theme) {
+        themeManager.setTheme(theme);
+        updateActiveTheme();
+      }
+    });
+  });
+
+  // 初始加载时初始化
+  document.addEventListener('DOMContentLoaded', () => {
+    themeManager.initialize();
+    updateActiveTheme();
+  });
+
+  // Astro view transitions 后重新初始化
+  document.addEventListener('astro:after-swap', () => {
+    themeManager.initialize();
+    updateActiveTheme();
+  });
+</script>

package/dist/components/navigation/index.ts

@@ -0,0 +1,3 @@
+export { default as LanguageSwitcher } from './LanguageSwitcher.astro';
+export { default as ThemeSwitcher } from './ThemeSwitcher.astro';
+export { default as TableOfContents } from './TableOfContents.astro'; 

package/dist/components/typography/Article.astro

@@ -0,0 +1,144 @@
+---
+/**
+ * @component Article
+ *
+ * @description
+ * Article 组件用于展示格式化的文章内容，提供了一套完整的排版样式，使文章内容更易于阅读和理解。
+ * 该组件适用于博客文章、文档页面、新闻内容等需要良好排版的场景。
+ *
+ * @design
+ * 设计理念：
+ * 1. 可读性优先 - 使用合理的行高、字体大小和间距，提高长文本的阅读体验
+ * 2. 层次分明 - 通过不同级别标题的样式区分，建立清晰的内容层次结构
+ * 3. 响应式设计 - 在不同设备上保持良好的阅读体验
+ * 4. 暗黑模式支持 - 自动适应系统的暗黑模式设置
+ *
+ * 视觉特点：
+ * - 合理的文本行高和段落间距
+ * - 标题使用较粗的字重和较小的行高
+ * - 列表项有适当的缩进和间距
+ * - 引用块使用左侧边框和斜体样式
+ * - 代码块和行内代码有不同的背景色
+ * - 表格有清晰的边框和背景色区分
+ *
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <Article>
+ *   <h1>文章标题</h1>
+ *   <p>这是一段文章内容...</p>
+ * </Article>
+ * ```
+ *
+ * 添加自定义类名：
+ * ```astro
+ * <Article class="my-custom-article">
+ *   <h2>带自定义类的文章</h2>
+ *   <p>这是一段文章内容...</p>
+ * </Article>
+ * ```
+ * 
+ * 设置文章宽度：
+ * ```astro
+ * <Article width="narrow">
+ *   <h2>窄宽度文章</h2>
+ *   <p>这是一段文章内容...</p>
+ * </Article>
+ * ```
+ *
+ * 完整示例：
+ * ```astro
+ * <Article>
+ *   <h1>文章标题</h1>
+ *   <p>这是一段介绍性文字，可以包含<a href="#">链接</a>和<code>行内代码</code>。</p>
+ *
+ *   <h2>二级标题</h2>
+ *   <p>这是二级标题下的段落内容。</p>
+ *
+ *   <blockquote>
+ *     这是一段引用内容，可以用来强调重要信息或引用他人的话。
+ *   </blockquote>
+ *
+ *   <h3>三级标题</h3>
+ *   <ul>
+ *     <li>无序列表项一</li>
+ *     <li>无序列表项二</li>
+ *   </ul>
+ *
+ *   <h4>四级标题</h4>
+ *   <ol>
+ *     <li>有序列表项一</li>
+ *     <li>有序列表项二</li>
+ *   </ol>
+ *
+ *   <pre><code>// 这是一个代码块
+ * function example() {
+ *   return "示例代码";
+ * }</code></pre>
+ * </Article>
+ * ```
+ *
+ * @props
+ * @prop {string} [class] - 自定义 CSS 类名，会与组件内置的类名合并
+ * @prop {string} [width="medium"] - 文章宽度，可选值为 "narrow"(窄), "medium"(中等), "wide"(宽), "full"(全宽)
+ *
+ * @slots
+ * @slot default - 文章内容，可以包含任何 HTML 元素
+ *
+ * @cssFeatures
+ * 组件支持的 HTML 元素样式：
+ * - 标题 (h1-h6)：不同级别的标题有不同的大小和间距
+ * - 段落 (p)：适当的行高和段落间距
+ * - 列表 (ul, ol, li)：合理的缩进和项目间距
+ * - 链接 (a)：带下划线的彩色文本
+ * - 引用块 (blockquote)：带左侧边框的斜体文本
+ * - 代码 (code, pre)：带背景色的等宽字体
+ * - 图片 (img)：自适应宽度
+ * - 水平线 (hr)：简洁的分隔线
+ * - 表格 (table, th, td)：清晰的表格样式
+ *
+ * @accessibility
+ * - 使用语义化的 article 元素作为容器
+ * - 保持足够的颜色对比度，确保在不同模式下的可读性
+ * - 支持系统的暗黑模式设置
+ */
+
+// 导入样式
+import '../../app.css';
+
+export interface Props {
+	/**
+	 * 文章的类名
+	 */
+	class?: string;
+	
+	/**
+	 * 类名列表
+	 */
+	'class:list'?: any;
+	
+	/**
+	 * 内联样式
+	 */
+	style?: string;
+	
+	/**
+	 * 文章宽度
+	 * @default "medium"
+	 */
+	width?: "narrow" | "medium" | "wide" | "full";
+}
+
+const { 
+	class: className = '',
+	width = "medium",
+	style = ""
+} = Astro.props;
+
+// 根据宽度选项设置类名
+const widthClass = `article-width-${width}`;
+---
+
+<article class:list={['article', widthClass, className]} style={style}>
+	<slot />
+</article>