@coffic/cosy-ui 0.7.4 → 0.8.7

package/dist/src-astro/products/Products.astro

@@ -0,0 +1,200 @@
+---
+/**
+ * @component Products
+ *
+ * @description
+ * Products 组件是ProductCard的容器集合，用于展示多个产品卡片。
+ * 组件会自动根据父容器大小调整布局，确保在任何视口大小下都能整齐排列产品卡片。
+ * 支持网格和列表两种布局模式，并提供多种配置选项以适应不同场景需求。
+ *
+ * @design
+ * 设计理念：
+ * 1. 响应式布局 - 自动适应父容器大小，在不同设备上呈现最佳效果
+ * 2. 灵活配置 - 提供多种布局选项、间距设置和对齐方式
+ * 3. 统一展示 - 确保所有产品卡片视觉一致，提供等高选项
+ * 4. 性能优化 - 支持懒加载和分页显示大量产品
+ *
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <Products
+ *   products={[
+ *     {
+ *       name: "产品1",
+ *       image: "/images/products/product1.jpg",
+ *       description: "产品1描述",
+ *       productUrl: "https://product1.com"
+ *     },
+ *     {
+ *       name: "产品2",
+ *       image: "/images/products/product2.jpg",
+ *       description: "产品2描述",
+ *       appStoreUrl: "https://apps.apple.com/app/product2"
+ *     }
+ *   ]}
+ * />
+ * ```
+ *
+ * 使用网格布局并设置列数：
+ * ```astro
+ * <Products
+ *   layout="grid"
+ *   columns={{ base: 1, sm: 2, md: 3, lg: 4 }}
+ *   products={products}
+ * />
+ * ```
+ *
+ * 使用列表布局：
+ * ```astro
+ * <Products
+ *   layout="list"
+ *   products={products}
+ * />
+ * ```
+ *
+ * 自定义卡片尺寸和间距：
+ * ```astro
+ * <Products
+ *   cardSize="sm"
+ *   gap="lg"
+ *   products={products}
+ * />
+ * ```
+ */
+
+import { ProductCard } from '../../index-astro';
+import '../../style.ts';
+import type { Props as ProductCardProps } from './ProductCard.astro';
+
+// 定义产品项类型
+type ProductItem = Omit<ProductCardProps, 'class'>;
+
+// 定义响应式列数配置
+type ResponsiveColumns = {
+  base?: number; // 默认列数
+  sm?: number; // 小屏幕列数
+  md?: number; // 中等屏幕列数
+  lg?: number; // 大屏幕列数
+  xl?: number; // 超大屏幕列数
+};
+
+// 定义间距大小
+type GapSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+// 定义布局类型
+type LayoutType = 'grid' | 'list';
+
+export interface Props {
+  /**
+   * 产品数据数组
+   */
+  products: ProductItem[];
+  /**
+   * 布局类型
+   * - grid: 网格布局（默认）
+   * - list: 列表布局
+   */
+  layout?: LayoutType;
+  /**
+   * 列数配置
+   * 可以为固定数字或响应式对象
+   * 例如: { base: 1, sm: 2, md: 3, lg: 4 }
+   */
+  columns?: number | ResponsiveColumns;
+  /**
+   * 卡片尺寸
+   * 应用于所有ProductCard
+   */
+  cardSize?: ProductCardProps['size'];
+  /**
+   * 卡片间距
+   * - xs: 超小间距
+   * - sm: 小间距
+   * - md: 中等间距（默认）
+   * - lg: 大间距
+   * - xl: 超大间距
+   */
+  gap?: GapSize;
+  /**
+   * 是否启用等高卡片
+   * 确保所有卡片高度一致
+   */
+  equalHeight?: boolean;
+  /**
+   * 描述文本的最大行数
+   * 应用于所有ProductCard
+   */
+  descriptionLines?: number;
+  /**
+   * 自定义类名
+   */
+  class?: string;
+}
+
+const {
+  products,
+  layout = 'grid',
+  columns = { base: 1, sm: 2, md: 3, lg: 4 },
+  cardSize = 'md',
+  gap = 'md',
+  equalHeight = true,
+  descriptionLines,
+  class: className = '',
+} = Astro.props;
+
+// 间距映射
+const gapMap = {
+  xs: 'cosy:gap-1',
+  sm: 'cosy:gap-2',
+  md: 'cosy:gap-4',
+  lg: 'cosy:gap-6',
+  xl: 'cosy:gap-8',
+};
+
+// 获取响应式列数类名
+const getColumnsClasses = () => {
+  if (typeof columns === 'number') {
+    return `cosy:grid-cols-${columns}`;
+  }
+
+  const { base = 1, sm, md, lg, xl } = columns;
+  const classes = [`cosy:grid-cols-${base}`];
+
+  if (sm) classes.push(`cosy:sm:grid-cols-${sm}`);
+  if (md) classes.push(`cosy:md:grid-cols-${md}`);
+  if (lg) classes.push(`cosy:lg:grid-cols-${lg}`);
+  if (xl) classes.push(`cosy:xl:grid-cols-${xl}`);
+
+  return classes.join(' ');
+};
+
+// 获取布局类名
+const getLayoutClasses = () => {
+  if (layout === 'grid') {
+    return ['cosy:grid', getColumnsClasses()];
+  } else {
+    return ['cosy:flex', 'cosy:flex-col'];
+  }
+};
+
+// 构建容器类名
+const containerClasses = [
+  ...getLayoutClasses(),
+  gapMap[gap],
+  'cosy:w-full',
+  className,
+];
+---
+
+<div class:list={containerClasses}>
+  {
+    products.map((product) => (
+      <ProductCard
+        {...product}
+        size={cardSize}
+        equalHeight={equalHeight}
+        descriptionLines={descriptionLines}
+      />
+    ))
+  }
+</div>

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

@@ -0,0 +1,2 @@
+export { default as Products } from './Products.astro';
+export { default as ProductCard } from './ProductCard.astro';

package/dist/src-astro/section/Section.astro

@@ -0,0 +1,150 @@
+---
+/**
+ * Section组件
+ *
+ * 一个用于页面内容区块的组件，支持不同的内边距、背景和间距
+ *
+ * @example
+ * ```astro
+ * <Section>
+ *   <h2>默认区块</h2>
+ *   <p>内容将被包裹在一个合适的区块中</p>
+ * </Section>
+ *
+ * <Section padding="lg" background="gray" centered={true} border={true}>
+ *   <h2>自定义区块</h2>
+ *   <p>大内边距，灰色背景，内容居中，带边框</p>
+ * </Section>
+ * ```
+ */
+
+import type { HTMLAttributes } from 'astro/types';
+import Container from '../container/Container.astro';
+import '../../style.ts';
+
+interface Props extends HTMLAttributes<'section'> {
+  /**
+   * 内边距大小
+   * @default "md"
+   */
+  padding?: 'none' | 'sm' | 'md' | 'lg' | 'xl';
+
+  /**
+   * 背景颜色
+   * @default "transparent"
+   */
+  background?:
+    | 'transparent'
+    | 'white'
+    | 'gray'
+    | 'primary'
+    | 'secondary'
+    | 'dark';
+
+  /**
+   * 是否使用容器包裹内容
+   * @default true
+   */
+  container?: boolean;
+
+  /**
+   * 容器尺寸，仅当container为true时有效
+   * @default "md"
+   */
+  containerSize?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+  /**
+   * 内容是否居中
+   * @default false
+   */
+  centered?: boolean;
+
+  /**
+   * 是否显示边框
+   * @default false
+   */
+  border?: boolean;
+
+  /**
+   * 自定义类名
+   */
+  class?: string;
+
+  /**
+   * 类名列表
+   */
+  'class:list'?: any;
+
+  /**
+   * 自定义ID
+   */
+  id?: string;
+
+  /**
+   * 自定义内联样式
+   */
+  style?: string;
+}
+
+const {
+  padding = 'md',
+  background = 'transparent',
+  container = true,
+  containerSize = 'md',
+  centered = false,
+  border = false,
+  class: className = '',
+  'class:list': classList,
+  id,
+  style,
+  ...rest
+} = Astro.props;
+
+// 内边距映射
+const paddingClasses = {
+  none: 'cosy:py-0',
+  sm: 'cosy:py-6',
+  md: 'cosy:py-12',
+  lg: 'cosy:py-16',
+  xl: 'cosy:py-24',
+};
+
+// 背景颜色映射
+const backgroundClasses = {
+  transparent: 'cosy:bg-transparent',
+  white: 'cosy:bg-base-100',
+  gray: 'cosy:bg-base-200',
+  primary: 'cosy:bg-primary/10',
+  secondary: 'cosy:bg-secondary/10',
+  dark: 'cosy:bg-neutral cosy:text-neutral-content',
+};
+
+// 构建最终类名
+const sectionClasses = [
+  paddingClasses[padding as keyof typeof paddingClasses],
+  backgroundClasses[background as keyof typeof backgroundClasses],
+  border ? 'cosy:border cosy:rounded-lg' : '',
+  className,
+].join(' ');
+
+// 内容类名
+const contentClasses = centered ? 'cosy:text-center' : '';
+---
+
+<section
+  id={id}
+  class:list={[sectionClasses, classList]}
+  style={style}
+  {...rest}>
+  {
+    container ? (
+      <Container size={containerSize} class={contentClasses}>
+        <slot />
+      </Container>
+    ) : (
+      <div class={contentClasses}>
+        <slot />
+      </div>
+    )
+  }
+</section>

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

@@ -0,0 +1 @@
+export { default as Section } from './Section.astro';

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

@@ -0,0 +1,192 @@
+---
+/**
+ * Sidebar组件
+ *
+ * 用于文档页面的侧边栏导航
+ *
+ * @example
+ * ```astro
+ * ---
+ * import Sidebar from './Sidebar.astro';
+ *
+ * const sidebarItems = [
+ *   { title: "入门", items: [
+ *     { href: "/docs/getting-started", text: "快速开始" },
+ *     { href: "/docs/installation", text: "安装" }
+ *   ]}
+ * ];
+ * ---
+ *
+ * <Sidebar sidebarItems={sidebarItems} />
+ * ```
+ */
+
+import '../../style.ts';
+import { isPathMatch } from '../utils/path.ts';
+import { MenuIcon, SidebarNav, Modal } from '../../index-astro';
+import type { ISidebarProps } from '../../index-astro';
+
+export interface Props extends ISidebarProps {}
+
+const {
+  sidebarItems,
+  class: className,
+  debug = false,
+  marginTop = 'md',
+  marginBottom = 'md',
+} = Astro.props;
+
+// 自动获取当前路径
+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>
+
+{/* 移动端侧边栏弹出层 */}
+<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">
+    <SidebarNav
+      sidebarItems={sidebarItems}
+      currentPath={currentPath}
+      debug={debug}
+    />
+  </div>
+</Modal>
+
+{/* 桌面端侧边栏 */}
+<aside
+  data-sidebar
+  data-current-path={currentPath}
+  data-margin-top={marginTop}
+  data-margin-bottom={marginBottom}
+  class:list={[
+    className,
+    debugClass,
+    'cosy:hidden cosy:lg:block',
+    getVerticalMarginTopClasses(marginTop),
+    getVerticalMarginBottomClasses(marginBottom),
+  ]}>
+  <div
+    class="cosy:top-16 cosy:sticky cosy:pb-48 cosy:h-[calc(100vh-0rem)] cosy:overflow-y-auto">
+    <SidebarNav
+      sidebarItems={sidebarItems}
+      currentPath={currentPath}
+      debug={debug}
+    />
+  </div>
+</aside>
+
+<script>
+  // 处理侧边栏滚动位置保存和恢复
+  document.addEventListener('astro:before-preparation', () => {
+    // 获取桌面侧边栏滚动容器
+    const desktopSidebarContent = document.querySelector(
+      'aside[data-sidebar] .cosy\\:overflow-y-auto'
+    );
+
+    // 保存滚动位置到localStorage
+    if (desktopSidebarContent) {
+      localStorage.setItem(
+        'sidebarScrollPosition',
+        desktopSidebarContent.scrollTop.toString()
+      );
+    }
+
+    // 获取移动端侧边栏滚动容器
+    const mobileSidebarContent = document.querySelector(
+      '.cosy\\:h-\\[calc\\(100vh-8rem\\)\\].cosy\\:overflow-y-auto'
+    );
+
+    // 保存移动端滚动位置
+    if (mobileSidebarContent) {
+      localStorage.setItem(
+        'mobileSidebarScrollPosition',
+        mobileSidebarContent.scrollTop.toString()
+      );
+    }
+  });
+
+  document.addEventListener('astro:page-load', () => {
+    // 获取桌面侧边栏滚动容器
+    const desktopSidebarContent = document.querySelector(
+      'aside[data-sidebar] .cosy\\:overflow-y-auto'
+    );
+
+    // 恢复滚动位置
+    if (desktopSidebarContent) {
+      const savedPosition = localStorage.getItem('sidebarScrollPosition');
+      if (savedPosition) {
+        desktopSidebarContent.scrollTop = parseInt(savedPosition, 10);
+      }
+    }
+
+    // 获取移动端侧边栏滚动容器
+    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);
+      }
+    }
+  });
+</script>

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

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

package/dist/src-astro/sidebar-nav/SidebarNav.astro

@@ -0,0 +1,136 @@
+---
+/**
+ * SidebarNav组件
+ *
+ * 用于渲染侧边栏的导航内容
+ */
+
+import { isPathMatch } from '../utils/path.ts';
+import '../../style.ts';
+import type { ISidebarItem } from '../types/sidebar.ts';
+
+interface Props {
+  /**
+   * 侧边栏项目
+   */
+  sidebarItems: ISidebarItem[];
+
+  /**
+   * 当前路径
+   */
+  currentPath: string;
+
+  /**
+   * 是否开启调试模式，显示边框
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * 自定义类名
+   */
+  class?: string;
+}
+
+const {
+  sidebarItems,
+  currentPath,
+  debug = false,
+  class: className,
+} = Astro.props;
+
+const debugClass = debug ? 'cosy:border cosy:border-red-500' : '';
+---
+
+<nav
+  data-sidebar-nav
+  data-current-path={currentPath}
+  class:list={['cosy:p-4', debugClass, className]}>
+  {
+    sidebarItems.map((section: ISidebarItem) => (
+      <div class:list={['cosy:mb-6', debugClass]}>
+        <h3
+          class:list={[
+            'cosy:font-bold cosy:mb-2 cosy:text-base-content/70',
+            debugClass,
+          ]}>
+          {section.text}
+        </h3>
+        <ul
+          class:list={[
+            'cosy:menu cosy:bg-base-200 cosy:rounded-box cosy:w-56',
+            debugClass,
+          ]}>
+          {section.items?.map((item: ISidebarItem) => {
+            const isActive = isPathMatch(currentPath, item.href);
+            return (
+              <li class:list={[debugClass]}>
+                <a
+                  data-sidebar-item
+                  data-current-path={currentPath}
+                  href={item.href}
+                  class:list={[
+                    'cosy:hover:bg-base-300',
+                    { 'cosy:menu-active': isActive },
+                    debugClass,
+                  ]}>
+                  {item.text}
+                </a>
+                {item.items && (
+                  <ul class:list={[debugClass]}>
+                    {item.items.map((subitem: ISidebarItem) => {
+                      const isSubActive = isPathMatch(
+                        currentPath,
+                        subitem.href
+                      );
+                      return (
+                        <li class:list={[debugClass]}>
+                          <a
+                            data-sidebar-item
+                            data-current-path={currentPath}
+                            href={subitem.href}
+                            class:list={[
+                              'cosy:hover:bg-base-300',
+                              { 'cosy:menu-active': isSubActive },
+                              debugClass,
+                            ]}>
+                            {subitem.text}
+                          </a>
+                          {subitem.items && (
+                            <ul class:list={[debugClass]}>
+                              {subitem.items.map((subsubitem: ISidebarItem) => {
+                                const isSubSubActive = isPathMatch(
+                                  currentPath,
+                                  subsubitem.href
+                                );
+                                return (
+                                  <li class:list={[debugClass]}>
+                                    <a
+                                      data-sidebar-item
+                                      data-current-path={currentPath}
+                                      href={subsubitem.href}
+                                      class:list={[
+                                        'cosy:hover:bg-base-300',
+                                        { 'cosy:active': isSubSubActive },
+                                        debugClass,
+                                      ]}>
+                                      {subsubitem.text}
+                                    </a>
+                                  </li>
+                                );
+                              })}
+                            </ul>
+                          )}
+                        </li>
+                      );
+                    })}
+                  </ul>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    ))
+  }
+</nav>