@coffic/cosy-ui 0.7.4 → 0.8.7

package/dist/src-astro/toc/TableOfContents.astro

@@ -0,0 +1,438 @@
+---
+/**
+ * @component TableOfContents
+ *
+ * @description
+ * TableOfContents 组件是一个目录导航组件，用于显示页面内容的标题结构。
+ * 它会自动检测页面中的标题元素，生成目录列表，并在用户滚动页面时高亮当前可见的标题。
+ * 当页面只有一个标题或没有足够的标题结构时，组件会自动隐藏。
+ *
+ * @design
+ * 设计理念：
+ * 1. 导航辅助 - 帮助用户快速了解页面结构和导航到特定内容
+ * 2. 上下文感知 - 自动高亮当前阅读位置，提供阅读进度反馈
+ * 3. 视觉层次 - 通过缩进和样式区分不同级别的标题
+ * 4. 响应式设计 - 在小屏幕设备上自动隐藏，优化空间利用
+ * 5. 智能显示 - 当页面结构不需要目录时自动隐藏
+ * 6. 多语言支持 - 支持多种语言显示，自动检测当前语言环境
+ *
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <TableOfContents />
+ * ```
+ *
+ * 自定义标题和选择器：
+ * ```astro
+ * <TableOfContents
+ *   title="章节导航"
+ *   selector="h2, h3, h4"
+ *   maxDepth={4}
+ * />
+ * ```
+ *
+ * 非固定位置：
+ * ```astro
+ * <TableOfContents fixed={false} />
+ * ```
+ *
+ * 指定内容容器：
+ * ```astro
+ * <TableOfContents containerSelector=".article-content" />
+ * ```
+ *
+ * 指定语言：
+ * ```astro
+ * <TableOfContents lang="zh-cn" />
+ * ```
+ *
+ * 启用日志：
+ * ```astro
+ * <TableOfContents enableLogging={true} />
+ * ```
+ */
+
+// 导入样式
+import '../../style.ts';
+import { createTextGetter } from '../utils/i18n.ts';
+import { LanguageUtil } from '../utils/language.ts';
+
+interface Props {
+  /**
+   * 是否固定在右侧
+   * @default true
+   */
+  fixed?: boolean;
+  /**
+   * 自定义类名
+   */
+  class?: string;
+  /**
+   * 标题选择器
+   * @default "h2, h3"
+   */
+  selector?: string;
+  /**
+   * 最大深度
+   * @default 3
+   */
+  maxDepth?: number;
+  /**
+   * 标题文本
+   * @default 根据语言自动选择
+   */
+  title?: string;
+  /**
+   * 内容容器选择器，用于限制标题搜索范围
+   * @default "main"
+   */
+  containerSelector?: string;
+  /**
+   * 显示目录所需的最少标题数量
+   * @default 2
+   */
+  minHeadings?: number;
+  /**
+   * 语言
+   * @default 自动检测
+   */
+  lang?: string;
+}
+
+const {
+  fixed = true,
+  class: className = '',
+  selector = 'h2, h3',
+  maxDepth = 3,
+  containerSelector = 'main',
+  minHeadings = 2,
+  title,
+} = Astro.props;
+
+// 获取当前语言
+const langInfo = LanguageUtil.getCurrentLanguage(Astro);
+// 创建文本获取函数
+const t = createTextGetter(langInfo, 'tableOfContents');
+// 获取标题文本，如果用户提供了标题则使用用户提供的标题
+const titleText = title || t('title');
+
+// 生成唯一ID，确保多个TOC实例不会冲突
+const tocId = `toc-${Math.random().toString(36).substring(2, 9)}`;
+---
+
+<aside
+  class:list={['cosy:hidden cosy:xl:block cosy:w-64 cosy:shrink-0', className]}>
+  <div class="cosy:top-18 cosy:sticky">
+    <div
+      class={`toc-container toc-scroll-container ${fixed ? 'cosy:w-64' : 'cosy:w-full cosy:max-w-xs'}`}
+      id={`${tocId}-container`}
+      style="display: none;">
+      <div class="cosy:bg-base-100 cosy:shadow-inner cosy:card">
+        <div class="cosy:p-4 cosy:card-body">
+          <div class="cosy:mb-2 cosy:font-bold cosy:text-lg cosy:card-title">
+            {titleText}
+          </div>
+          <ul class="cosy:menu cosy:menu-sm" id={tocId}>
+            <!-- 目录项将通过 JavaScript 动态生成 -->
+            <li class="cosy:text-base-content/60">{t('loading')}</li>
+          </ul>
+        </div>
+      </div>
+    </div>
+  </div>
+</aside>
+
+<script
+  is:inline
+  define:vars={{
+    selector,
+    maxDepth,
+    tocId,
+    containerSelector,
+    minHeadings,
+    langInfo,
+  }}
+>
+  // @ts-nocheck
+  // 在页面加载完成后生成目录
+  function generateTOC() {
+    // 使用指定的容器选择器查找内容容器
+    const container = document.querySelector(containerSelector);
+    if (!container) return;
+
+    // 排除 IgnoreHeading 组件中的标题
+    const headings = Array.from(container.querySelectorAll(selector)).filter(
+      (heading) => {
+        // 检查标题本身或任何祖先元素是否有 ignore-heading 属性
+        const isInIgnoreHeading =
+          heading.hasAttribute('ignore-heading') ||
+          heading.closest('[ignore-heading]') !== null;
+        return !isInIgnoreHeading;
+      }
+    );
+
+    const tocList = document.getElementById(tocId);
+    const tocContainer = document.getElementById(`${tocId}-container`);
+
+    if (!tocList || !tocContainer) return;
+
+    // 如果标题数量少于最小要求，保持隐藏状态并退出
+    if (headings.length < minHeadings) {
+      tocContainer.style.display = 'none';
+      return;
+    }
+
+    // 显示目录容器
+    tocContainer.style.display = 'block';
+
+    // 清空占位符
+    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-level-${level}`;
+      listItem.dataset.headingId = heading.id;
+
+      const link = document.createElement('a');
+      link.href = `#${heading.id}`;
+      link.textContent = heading.textContent;
+      link.className =
+        'cosy:text-base-content/80 cosy:hover:text-primary cosy:transition-colors';
+
+      // 添加缩进
+      if (level === 3) {
+        link.style.paddingLeft = '1.5rem';
+      }
+
+      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 < minHeadings) {
+      tocContainer.style.display = 'none';
+      return;
+    }
+
+    // 添加活动标题高亮
+    highlightActiveHeading();
+
+    // 使用节流函数优化滚动事件
+    window.addEventListener('scroll', throttle(highlightActiveHeading, 200));
+  }
+
+  // 从文本生成有效的 ID
+  function generateIdFromText(text) {
+    return (
+      text
+        .trim()
+        .toLowerCase()
+        .replace(/[\s\n]+/g, '-') // 将空格和换行替换为连字符
+        .replace(/[^\w\u4e00-\u9fa5-]/g, '') // 只保留字母、数字、中文和连字符
+        .replace(/^-+|-+$/g, '') // 移除开头和结尾的连字符
+        .replace(/-{2,}/g, '-') || // 将多个连字符替换为单个
+      'heading'
+    ); // 如果结果为空，则使用默认值
+  }
+
+  // 高亮当前可见的标题
+  function highlightActiveHeading() {
+    const tocContainer = document.getElementById(`${tocId}-container`);
+    if (!tocContainer || tocContainer.style.display === 'none') return;
+
+    const container = document.querySelector(containerSelector);
+    if (!container) return;
+
+    const headings = Array.from(container.querySelectorAll(selector));
+    if (headings.length < minHeadings) 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;
+    } else if (headings.length > 0) {
+      // 如果没有找到，使用第一个标题
+      activeHeadingId = headings[0].id;
+    }
+
+    // 更新活动链接样式
+    const tocLinks = document.querySelectorAll(`#${tocId} a`);
+    let activeLink = document.querySelector(`#${tocId} a.active-toc-link`);
+    let currentActiveId = activeLink
+      ? activeLink.getAttribute('href').substring(1)
+      : null;
+
+    // 如果当前活动标题没有变化，避免不必要的样式更新
+    if (currentActiveId === activeHeadingId) {
+      return;
+    }
+
+    let hasActiveLink = false;
+
+    tocLinks.forEach((link) => {
+      const href = link.getAttribute('href').substring(1);
+
+      // 清除所有高亮
+      link.classList.remove(
+        'cosy:text-primary',
+        'cosy:font-medium',
+        'active-toc-link'
+      );
+
+      // 添加当前活动标题的高亮
+      if (href === activeHeadingId) {
+        link.classList.add(
+          'cosy:text-primary',
+          'cosy:font-medium',
+          'active-toc-link'
+        );
+        hasActiveLink = true;
+
+        // 只在首次高亮时添加一个轻微的过渡效果，而不是每次滚动都动画
+        if (href !== currentActiveId) {
+          link.style.transition = 'color 0.3s ease';
+        }
+      }
+    });
+
+    // 如果没有找到活动链接，尝试高亮第一个标题
+    if (!hasActiveLink && tocLinks.length > 0) {
+      tocLinks[0].classList.add(
+        'cosy:text-primary',
+        'cosy:font-medium',
+        'active-toc-link'
+      );
+    }
+
+    // 确保活动链接在视图中可见
+    const newActiveLink = document.querySelector(`#${tocId} a.active-toc-link`);
+    const tocList = document.getElementById(tocId);
+    if (newActiveLink && tocList) {
+      const tocScrollContainer = document.querySelector(
+        '.toc-scroll-container'
+      );
+      if (tocScrollContainer) {
+        const linkTop = newActiveLink.offsetTop;
+        const containerScrollTop = tocScrollContainer.scrollTop;
+        const containerHeight = tocScrollContainer.clientHeight;
+
+        // 如果链接不在可视区域内，平滑滚动到可见位置
+        if (
+          linkTop < containerScrollTop ||
+          linkTop > containerScrollTop + containerHeight
+        ) {
+          tocScrollContainer.scrollTo({
+            top: linkTop - containerHeight / 2,
+            behavior: 'smooth',
+          });
+        }
+      }
+    }
+  }
+
+  // 节流函数，限制函数调用频率
+  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);
+    };
+  }
+
+  // 页面加载时初始化
+  document.addEventListener('astro:page-load', generateTOC);
+  // 初始加载时也初始化
+  generateTOC();
+
+  // 添加resize事件监听，在窗口大小变化时重新计算高亮
+  window.addEventListener(
+    'resize',
+    throttle(() => {
+      generateTOC(); // 重新生成TOC，以防窗口大小变化导致标题可见性变化
+      highlightActiveHeading();
+    }, 200)
+  );
+
+  // 立即触发一次高亮计算
+  setTimeout(generateTOC, 100);
+  setTimeout(highlightActiveHeading, 500);
+</script>

package/dist/src-astro/toc/TableOfContentsBasic.astro

@@ -0,0 +1,25 @@
+---
+import TableOfContents from './TableOfContents.astro';
+---
+
+<div class="cosy:flex cosy:gap-4">
+  <div class="cosy:w-64">
+    <TableOfContents />
+  </div>
+  <div class="cosy:flex-1">
+    <h2 id="introduction">介绍</h2>
+    <p>这是一个示例内容。</p>
+
+    <h2 id="features">功能特点</h2>
+    <p>这里列出了主要功能。</p>
+
+    <h3 id="feature-1">功能 1</h3>
+    <p>功能 1 的详细说明。</p>
+
+    <h3 id="feature-2">功能 2</h3>
+    <p>功能 2 的详细说明。</p>
+
+    <h2 id="conclusion">总结</h2>
+    <p>这是总结部分。</p>
+  </div>
+</div>

package/dist/src-astro/toc/index.ts

@@ -0,0 +1,11 @@
+import TableOfContents from './TableOfContents.astro';
+import TableOfContentsBasic from './TableOfContentsBasic.astro';
+import BasicSourceCode from './TableOfContentsBasic.astro?raw';
+import { extractSimpleExample } from '../utils/component';
+
+export { TableOfContents, TableOfContentsBasic };
+
+// 导出示例源代码
+export const TableOfContentsExampleCodes = {
+  Basic: extractSimpleExample(BasicSourceCode, 'TableOfContents'),
+};

package/dist/src-astro/types/article.ts

@@ -0,0 +1,22 @@
+export interface IArticleProps {
+  /**
+   * 文章的类名
+   */
+  class?: string;
+
+  /**
+   * 类名列表
+   */
+  'class:list'?: any;
+
+  /**
+   * 内联样式
+   */
+  style?: string;
+
+  /**
+   * 文章宽度
+   * @default "medium"
+   */
+  width?: 'narrow' | 'medium' | 'wide' | 'full';
+}

package/dist/src-astro/types/footer.ts

@@ -0,0 +1,129 @@
+import type { ILogo, IProduct } from './product';
+
+export interface IFooterProps {
+  /**
+   * 关于链接
+   */
+  aboutLink?: string;
+
+  /**
+   * 博客链接
+   */
+  blogLink?: string;
+
+  /**
+   * 职业链接
+   */
+  careersLink?: string;
+
+  /**
+   * 公司名称
+   */
+  company: string;
+
+  /**
+   * 联系链接
+   */
+  contactLink?: string;
+
+  /**
+   * 版权信息
+   */
+  copyright: string;
+
+  /**
+   * 调试模式
+   */
+  debug?: boolean;
+
+  /**
+   * 是否启用日志输出
+   * @default false
+   */
+  enableLogging?: boolean;
+
+  /**
+   * 常见问题链接
+   */
+  faqLink?: string;
+
+  /**
+   * 历史链接
+   */
+  historyLink?: string;
+
+  /**
+   * 首页链接
+   */
+  homeLink: string;
+
+  /**
+   * ICP备案号
+   */
+  icp?: string;
+
+  /**
+   * 激励标语
+   */
+  inspirationalSlogan: string;
+
+  /**
+   * 徽标
+   */
+  logo?: ILogo;
+
+  /**
+   * 媒体链接
+   */
+  mediaLink?: string;
+
+  /**
+   * 新闻链接
+   */
+  newsLink?: string;
+
+  /**
+   * 合作伙伴链接
+   */
+  partnersLink?: string;
+
+  /**
+   * 隐私链接
+   */
+  privacyLink?: string;
+
+  /**
+   * 产品
+   */
+  products?: IProduct[];
+
+  /**
+   * 站点名称
+   */
+  siteName: string;
+
+  /**
+   * 标语
+   */
+  slogan: string;
+
+  /**
+   * 社交链接
+   */
+  socialLinks?: string[];
+
+  /**
+   * 团队链接
+   */
+  teamLink?: string;
+
+  /**
+   * 技术栈链接
+   */
+  techStackLink?: string;
+
+  /**
+   * 条款链接
+   */
+  termsLink?: string;
+}

package/dist/src-astro/types/header.ts

@@ -0,0 +1,87 @@
+import type { INavItem } from './nav';
+
+export interface IHeaderProps {
+  /**
+   * 侧边栏是否默认展开
+   * @default false
+   */
+  defaultSidebarOpen?: boolean;
+
+  /**
+   * 导航栏高度
+   * @default "md"
+   */
+  height?: '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+  /**
+   * 语言选项列表
+   */
+  languages?: string[];
+
+  /**
+   * Logo图片元数据
+   */
+  logo?: ImageMetadata;
+
+  /**
+   * Logo 链接地址
+   * @default "/"
+   */
+  logoHref?: string;
+
+  /**
+   * 导航菜单项
+   */
+  navItems?: INavItem[];
+
+  /**
+   * 导航栏位置
+   * @default "start"
+   */
+  navPosition?: 'start' | 'center' | 'end';
+
+  /**
+   * 水平内边距
+   * @default "md"
+   */
+  paddingHorizontal?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+  /**
+   * 垂直内边距
+   * @default "md"
+   */
+  paddingVertical?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+  /**
+   * 圆角大小
+   * @default "md"
+   */
+  rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+  /**
+   * 是否显示侧边栏切换按钮
+   * @default false
+   */
+  showSidebarToggle?: boolean;
+
+  /**
+   * 是否显示主题切换按钮
+   * @default false
+   */
+  showThemeSwitcher?: boolean;
+
+  /**
+   * 社交媒体链接列表
+   */
+  socialLinks?: Array<{
+    name: string;
+    url: string;
+    icon: any;
+  }>;
+
+  /**
+   * 是否固定在顶部
+   * @default true
+   */
+  sticky?: boolean;
+}