@coffic/cosy-ui 0.3.67 → 0.4.3

package/dist/components/data-display/Products.astro

@@ -0,0 +1,197 @@
+---
+/**
+ * @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 './ProductCard.astro';
+import '../../app.css';
+
+// 导入ProductCard的类型定义
+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/components/layouts/AppLayout.astro

@@ -0,0 +1,254 @@
+---
+/**
+ * AppLayout组件
+ *
+ * 适用于页面布局，包含侧边栏导航和目录
+ *
+ * 布局效果：
+ *
+ * 移动端：
+ * ```
+ * +------------------+
+ * |     Header      |
+ * +------------------+
+ * | Sidebar (1 line) |
+ * +------------------+
+ * |                  |
+ * |   Main Content   |
+ * |                  |
+ * |                  |
+ * +------------------+
+ * |     Footer      |
+ * +------------------+
+ * ```
+ *
+ * 桌面端：
+ * ```
+ * +------------------+
+ * |      Header     |
+ * +--------+---------+
+ * |        |         |
+ * |Sidebar | Content |
+ * |        |         |
+ * |        |         |
+ * +--------+---------+
+ * |      Footer     |
+ * +------------------+
+ * ```
+ *
+ * @param {Object} sidebarConfig - 侧边栏配置
+ * @param {boolean} [showHeader=true] - 是否显示头部
+ * @param {boolean} [showFooter=true] - 是否显示页脚
+ * @param {boolean} [showSidebar=true] - 是否显示侧边栏
+ * @param {string} [className] - 自定义类名
+ * @param {Array} [classList] - 自定义类名列表
+ * @param {boolean} [debug=true] - 是否启用调试模式
+ * @param {Object} mainContentConfig - 主内容区域配置
+ * @param {Object} footerConfig - 页脚配置
+ * @param {Object} headerConfig - 头部配置
+ * @param {Object} metaConfig - 元数据配置
+ * @param {Object} rest - 其他属性
+ *
+ * @example
+ * ```astro
+ * ---
+ * import AppLayout from '../layouts/AppLayout.astro';
+ *
+ * const sidebarItems = [
+ *   { title: "入门", items: [
+ *     { href: "/docs/getting-started", text: "快速开始" },
+ *     { href: "/docs/installation", text: "安装" }
+ *   ]},
+ *   { title: "组件", items: [
+ *     { href: "/docs/components/button", text: "Button 按钮" },
+ *     { href: "/docs/components/card", text: "Card 卡片" }
+ *   ]}
+ * ];
+ * ---
+ *
+ * <AppLayout
+ *   metaConfig={{
+ *     title: "文档标题",
+ *     description: "文档描述"
+ *   }}
+ *   sidebarConfig={{
+ *     sidebarItems: sidebarItems
+ *   }}
+ * >
+ *   <h1>文档内容</h1>
+ *   <p>这是文档的主要内容</p>
+ * </AppLayout>
+ * ```
+ *
+ * 自定义页脚示例：
+ * ```astro
+ * <AppLayout
+ *   metaConfig={{
+ *     title: "文档标题",
+ *     description: "文档描述"
+ *   }}
+ *   sidebarConfig={{
+ *     sidebarItems: sidebarItems
+ *   }}
+ *   footerConfig={{
+ *     slogan: "简单而强大的组件库",
+ *     inspirationalSlogan: "让开发更加愉悦",
+ *     socialLinks: [
+ *       "https://github.com/myorg/myrepo",
+ *       "https://twitter.com/myorg"
+ *     ],
+ *     products: [
+ *       { name: "组件库", href: "/components" },
+ *       { name: "模板", href: "/templates" }
+ *     ]
+ *   }}
+ * >
+ *   <h1>文档内容</h1>
+ *   <p>这是文档的主要内容</p>
+ * </AppLayout>
+ * ```
+ *
+ * 组件支持多种页脚相关的配置参数，可以通过以 `footer` 为前缀的属性来自定义页脚的内容和链接。
+ * 所有这些参数都是可选的，组件会为常用参数提供默认值。
+ *
+ * 全宽内容区域示例：
+ * ```astro
+ * <AppLayout
+ *   metaConfig={{
+ *     title: "文档标题",
+ *     description: "文档描述"
+ *   }}
+ *   sidebarConfig={{
+ *     sidebarItems: sidebarItems
+ *   }}
+ *   mainContentConfig={{
+ *     fullWidth: true
+ *   }}
+ * >
+ *   <!-- 全宽Hero部分，无需容器限制 -->
+ *   <div class="cosy:bg-primary cosy:p-10 cosy:text-white cosy:text-center">
+ *     <h1 class="cosy:text-3xl">全宽Hero部分</h1>
+ *     <p class="cosy:mt-4">没有容器限制，宽度可以100%占满</p>
+ *   </div>
+ *
+ *   <!-- 自定义容器部分 -->
+ *   <div class="cosy:mx-auto cosy:p-6 cosy:container">
+ *     <p>在全宽模式下，您可以自行控制内容的容器和间距</p>
+ *     <p>这使得创建全宽背景的同时，保持内容在合适的宽度内</p>
+ *   </div>
+ *
+ *   <!-- 另一个全宽部分 -->
+ *   <div class="cosy:bg-accent cosy:mt-8 cosy:p-10">
+ *     <div class="cosy:mx-auto cosy:container">
+ *       <h2 class="cosy:text-2xl">灵活的布局</h2>
+ *       <p>您可以自由组合全宽区域和容器限制区域</p>
+ *     </div>
+ *   </div>
+ * </AppLayout>
+ * ```
+ *
+ * 调试模式示例：
+ * ```astro
+ * <AppLayout
+ *   metaConfig={{
+ *     title: "文档标题",
+ *     description: "文档描述"
+ *   }}
+ *   sidebarConfig={{
+ *     sidebarItems: sidebarItems
+ *   }}
+ *   debug={true}
+ * >
+ *   <h1>文档内容</h1>
+ *   <p>这是文档的主要内容</p>
+ * </AppLayout>
+ * ```
+ */
+
+import '../../app.css';
+import BaseLayout from './BaseLayout.astro';
+import Footer from './Footer.astro';
+import Main from '../containers/Main.astro';
+import Header from './Header.astro';
+import Sidebar from './Sidebar.astro';
+import { ClientRouter } from 'astro:transitions';
+import type { AppLayoutProps } from '@/types/layout';
+
+interface Props extends AppLayoutProps {}
+
+const {
+	sidebarConfig,
+	showHeader = true,
+	showFooter = true,
+	showSidebar = true,
+	class: className,
+	'class:list': classList,
+	debug = true,
+	mainContentConfig,
+	footerConfig,
+	headerConfig,
+	metaConfig,
+	...rest
+}: Props = Astro.props;
+---
+
+<BaseLayout
+	title={metaConfig.title}
+	description={metaConfig.description}
+	keywords={metaConfig.keywords}
+	author={metaConfig.author}
+	robots={metaConfig.robots}
+	head={metaConfig.head}
+	class:list={[
+		'cosy:min-h-screen cosy:flex cosy:flex-col',
+		{ 'cosy:border cosy:border-base-300': debug },
+	]}
+	{...rest}>
+	{
+		showHeader && (
+			<Header
+				logo={headerConfig.logo}
+				logoHref={headerConfig.logoHref}
+				navItems={headerConfig.navItems}
+				languages={headerConfig.languages}
+				currentLocale={headerConfig.currentLocale}
+				sticky={headerConfig.sticky}
+				basePath={headerConfig.basePath}
+				showSidebarToggle={headerConfig.showSidebarToggle}
+				defaultSidebarOpen={headerConfig.defaultSidebarOpen}
+				height={headerConfig.height}
+				transition:persist
+			/>
+		)
+	}
+
+	<div class="cosy:flex cosy:flex-row cosy:flex-1 cosy:pb-0 cosy:min-h-screen">
+		<!-- 侧边栏容器 -->
+		{showSidebar && <Sidebar {...sidebarConfig} />}
+
+		<!-- 主内容区域 -->
+		<Main {...mainContentConfig}>
+			<slot />
+			<ClientRouter />
+		</Main>
+	</div>
+
+	<!-- Footer -->
+	{showFooter && <Footer {...footerConfig} />}
+
+	<script>
+		// Handle sidebar toggle
+		const sidebarToggle = document.getElementById('sidebar-toggle');
+		const sidebar = document.getElementById('sidebar-mobile');
+		const sidebarOverlay = document.getElementById('sidebar-overlay');
+
+		function toggleSidebar() {
+			sidebar?.classList.toggle('cosy:hidden');
+			sidebarOverlay?.classList.toggle('cosy:hidden');
+			document.body.classList.toggle('cosy:overflow-hidden');
+		}
+
+		sidebarToggle?.addEventListener('click', toggleSidebar);
+		sidebarOverlay?.addEventListener('click', toggleSidebar);
+	</script>
+</BaseLayout>

package/dist/components/layouts/BaseLayout.astro

@@ -49,59 +49,10 @@
  * ```
  */
 
-// 导入样式
 import '../../app.css';
+import type { MetaProps } from '@/types/meta';
 
-export interface Props {
-  /**
-   * 页面标题
-   */
-  title: string;
-  
-  /**
-   * 页面描述
-   * @default ""
-   */
-  description?: string;
-  
-  /**
-   * 页面关键词
-   * @default ""
-   */
-  keywords?: string;
-  
-  /**
-   * 页面语言
-   * @default "zh-CN"
-   */
-  lang?: string;
-  
-  /**
-   * 是否包含视口元标签
-   * @default true
-   */
-  viewport?: boolean;
-  
-  /**
-   * 自定义CSS
-   */
-  customStyles?: string;
-  
-  /**
-   * 自定义头部内容
-   */
-  head?: astroHTML.JSX.Element;
-  
-  /**
-   * 页面类名
-   */
-  class?: string;
-  
-  /**
-   * 类名列表
-   */
-  'class:list'?: any;
-}
+export interface Props extends MetaProps {}
 
 const {
   title,
@@ -141,4 +92,4 @@ let bodyClasses = className || "";
   <body class:list={[bodyClasses, classList]}>
     <slot />
   </body>
-</html> 
+</html>