@coffic/cosy-ui 0.1.29 → 0.2.0

package/dist/components/layouts/Flex.astro

@@ -0,0 +1,138 @@
+---
+/**
+ * @component Flex
+ * 
+ * @description
+ * Flex 组件是一个灵活的弹性布局组件，用于创建各种排列和对齐方式的布局。
+ * 它封装了 CSS Flexbox 的常用功能，提供简单易用的接口来控制子元素的排列方式。
+ * 
+ * @note
+ * 此组件需要在 Root 组件内使用以确保样式正确加载。
+ * 
+ * @usage
+ * ```astro
+ * ---
+ * import { Root, Flex } from '@coffic/cosy-ui';
+ * ---
+ * 
+ * <Root>
+ *   <Flex>
+ *     <div>默认水平排列</div>
+ *     <div>居中对齐</div>
+ *   </Flex>
+ * </Root>
+ * ```
+ */
+
+import type { HTMLAttributes } from 'astro/types';
+
+type Direction = 'row' | 'row-reverse' | 'column' | 'column-reverse';
+type Justify = 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly';
+type Align = 'start' | 'end' | 'center' | 'stretch' | 'baseline';
+type Gap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+interface Props extends HTMLAttributes<'div'> {
+  /**
+   * 排列方向
+   * @default "row"
+   */
+  direction?: Direction;
+  
+  /**
+   * 水平对齐方式
+   * @default "center"
+   */
+  justify?: Justify;
+  
+  /**
+   * 垂直对齐方式
+   * @default "center"
+   */
+  align?: Align;
+  
+  /**
+   * 是否允许换行
+   * @default false
+   */
+  wrap?: boolean;
+  
+  /**
+   * 元素间距
+   * @default "md"
+   */
+  gap?: Gap;
+  
+  /**
+   * 自定义类名
+   */
+  class?: string;
+  
+  /**
+   * 类名列表
+   */
+  'class:list'?: any;
+}
+
+const {
+  direction = 'row',
+  justify = 'center',
+  align = 'center',
+  wrap = false,
+  gap = 'md',
+  class: className = '',
+  'class:list': classList,
+  ...rest
+} = Astro.props;
+
+// 方向映射
+const directionClasses: Record<Direction, string> = {
+  'row': 'flex-row',
+  'row-reverse': 'flex-row-reverse',
+  'column': 'flex-col',
+  'column-reverse': 'flex-col-reverse'
+};
+
+// 水平对齐映射
+const justifyClasses: Record<Justify, string> = {
+  'start': 'justify-start',
+  'end': 'justify-end',
+  'center': 'justify-center',
+  'between': 'justify-between',
+  'around': 'justify-around',
+  'evenly': 'justify-evenly'
+};
+
+// 垂直对齐映射
+const alignClasses: Record<Align, string> = {
+  'start': 'items-start',
+  'end': 'items-end',
+  'center': 'items-center',
+  'stretch': 'items-stretch',
+  'baseline': 'items-baseline'
+};
+
+// 间距映射
+const gapClasses: Record<Gap, string> = {
+  'none': 'gap-0',
+  'xs': 'gap-2',
+  'sm': 'gap-4',
+  'md': 'gap-6',
+  'lg': 'gap-8',
+  'xl': 'gap-12'
+};
+
+// 构建最终类名
+const flexClasses = [
+  'flex',
+  directionClasses[direction as Direction],
+  justifyClasses[justify as Justify],
+  alignClasses[align as Align],
+  wrap ? 'flex-wrap' : 'flex-nowrap',
+  gapClasses[gap as Gap],
+  className
+].join(' ');
+---
+
+<div class:list={[flexClasses, classList]} {...rest}>
+  <slot />
+</div>

package/dist/components/layouts/Footer.astro

@@ -0,0 +1,284 @@
+---
+/**
+ * @component Footer
+ * 
+ * @description
+ * Footer 组件用于创建网站的页脚部分，提供版权信息、导航链接和社交媒体链接等内容。
+ * 该组件支持高度自定义，可以根据需要显示或隐藏不同的部分。
+ * 
+ * @design
+ * 设计理念：
+ * 1. 清晰的信息层次 - 通过视觉层次和分组展示不同类别的页脚信息
+ * 2. 响应式布局 - 在不同屏幕尺寸下保持良好的可用性和美观性
+ * 3. 可定制性 - 支持多种配置选项，适应不同网站的需求
+ * 4. 品牌一致性 - 与网站整体设计风格保持一致
+ * 
+ * 视觉特点：
+ * - 分区布局：清晰区分不同类别的信息
+ * - 简洁设计：使用适当的间距和字体大小确保可读性
+ * - 品牌展示：突出显示网站名称和标语
+ * - 社交媒体整合：提供社交媒体链接的展示
+ * 
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <Footer 
+ *   siteName="我的网站"
+ *   homeLink="/"
+ *   slogan="简单而强大"
+ *   company="我的公司"
+ *   copyright="保留所有权利"
+ *   inspirationalSlogan="构建美好的数字体验"
+ * />
+ * ```
+ * 
+ * 添加社交媒体链接：
+ * ```astro
+ * <Footer 
+ *   siteName="我的网站"
+ *   homeLink="/"
+ *   slogan="简单而强大"
+ *   company="我的公司"
+ *   copyright="保留所有权利"
+ *   inspirationalSlogan="构建美好的数字体验"
+ *   socialLinks={[
+ *     "https://github.com/myusername",
+ *     "https://twitter.com/myusername"
+ *   ]}
+ * />
+ * ```
+ * 
+ * 添加产品链接：
+ * ```astro
+ * <Footer 
+ *   siteName="我的网站"
+ *   homeLink="/"
+ *   slogan="简单而强大"
+ *   company="我的公司"
+ *   copyright="保留所有权利"
+ *   inspirationalSlogan="构建美好的数字体验"
+ *   products={[
+ *     { name: "产品A", href: "/products/a" },
+ *     { name: "产品B", href: "/products/b" }
+ *   ]}
+ * />
+ * ```
+ * 
+ * 完整示例：
+ * ```astro
+ * <Footer 
+ *   siteName="我的网站"
+ *   homeLink="/"
+ *   slogan="简单而强大"
+ *   company="我的公司"
+ *   copyright="保留所有权利"
+ *   inspirationalSlogan="构建美好的数字体验"
+ *   logo={{ src: "/logo.png", alt: "网站Logo" }}
+ *   products={[
+ *     { name: "产品A", href: "/products/a" },
+ *     { name: "产品B", href: "/products/b" }
+ *   ]}
+ *   socialLinks={[
+ *     "https://github.com/myusername",
+ *     "https://twitter.com/myusername"
+ *   ]}
+ *   aboutLink="/about"
+ *   contactLink="/contact"
+ *   termsLink="/terms"
+ *   privacyLink="/privacy"
+ * />
+ * ```
+ * 
+ * @props
+ * @prop {string} siteName - 网站名称
+ * @prop {string} homeLink - 首页链接
+ * @prop {string} slogan - 网站标语
+ * @prop {string} company - 公司名称
+ * @prop {string} copyright - 版权信息
+ * @prop {string} inspirationalSlogan - 鼓舞人心的标语，显示在横幅中
+ * @prop {string} [icp] - ICP备案号（中国网站需要）
+ * @prop {Object} [logo] - 网站Logo对象，包含src和alt属性
+ * @prop {Array<Object>} [products=[]] - 产品链接数组，每个对象包含name、href和可选的external属性
+ * @prop {string} [aboutLink] - "关于我们"页面链接
+ * @prop {string} [contactLink] - "联系我们"页面链接
+ * @prop {string} [termsLink] - "服务条款"页面链接
+ * @prop {string} [privacyLink] - "隐私政策"页面链接
+ * @prop {Array<string>} [socialLinks=[]] - 社交媒体链接数组
+ * @prop {string} [teamLink] - "团队介绍"页面链接
+ * @prop {string} [careersLink] - "加入我们"页面链接
+ * @prop {string} [newsLink] - "新闻动态"页面链接
+ * @prop {string} [historyLink] - "发展历程"页面链接
+ * @prop {string} [partnersLink] - "合作伙伴"页面链接
+ * @prop {string} [blogLink] - "技术博客"页面链接
+ * @prop {string} [faqLink] - "常见问题"页面链接
+ * @prop {string} [mediaLink] - "媒体报道"页面链接
+ * @prop {string} [techStackLink] - "技术栈"页面链接
+ * @prop {boolean} [debug=false] - 调试模式
+ * 
+ * @accessibility
+ * - 使用语义化HTML结构，确保屏幕阅读器可以正确解析
+ * - 所有链接都有明确的文本描述
+ * - 社交媒体图标包含屏幕阅读器专用的文本说明
+ */
+
+import { processSocialLink } from '../../utils/social';
+import Link from '../base/Link.astro';
+import SocialIcon from '../icons/SocialIcon.astro';
+import type { FooterProps } from '../../types/footer';
+
+// 导入样式
+import '../../app.css';
+
+interface Props extends FooterProps {}
+
+const {
+	siteName,
+	homeLink,
+	slogan,
+	company,
+	copyright,
+	inspirationalSlogan,
+	icp,
+	logo,
+	products = [],
+	aboutLink,
+	contactLink,
+	termsLink,
+	privacyLink,
+	socialLinks = [],
+	teamLink,
+	careersLink,
+	newsLink,
+	historyLink,
+	partnersLink,
+	blogLink,
+	faqLink,
+	mediaLink,
+	techStackLink,
+	debug = false,
+}: Props = Astro.props;
+
+const currentYear = new Date().getFullYear();
+
+// 处理社交链接
+const processedSocialLinks = socialLinks.map((url) => processSocialLink(url));
+
+// 调试模式的样式类
+const debugClasses = debug ? {
+	footer: "border-2 border-blue-500",
+	section: "border-2 border-green-500",
+	nav: "border-2 border-yellow-500",
+	aside: "border-2 border-purple-500"
+} : {
+	footer: "",
+	section: "",
+	nav: "",
+	aside: ""
+};
+---
+
+<footer class:list={["footer sm:footer-horizontal bg-base-200 text-base-content p-10", debugClasses.footer]}>
+	<div class:list={["flex container mx-auto sm:flex-col md:flex-row justify-between gap-8", debugClasses.section]}>
+		{/* 品牌区域 */}
+		<aside class:list={["max-w-xs", debugClasses.aside]}>
+			<a href={homeLink} class="flex items-center gap-2 mb-4">
+				{logo && (
+					<img
+						src={logo.src}
+						alt={logo.alt}
+						class="mask mask-squircle w-12 h-12"
+						width="48"
+						height="48"
+					/>
+				)}
+				<div>
+					<h2 class="text-xl font-bold">{siteName}</h2>
+					<p class="text-base-content/70">{slogan}</p>
+				</div>
+			</a>
+			
+			{/* 社交媒体链接 */}
+			{processedSocialLinks.length > 0 && (
+				<div class="flex gap-2 mt-4">
+					{processedSocialLinks.map((link) => (
+						<a 
+							href={link.url} 
+							class="btn btn-circle btn-ghost btn-sm"
+							target="_blank" 
+							rel="noopener noreferrer"
+							aria-label={link.name}
+						>
+							<SocialIcon platform={link.platform} />
+						</a>
+					))}
+				</div>
+			)}
+		</aside>
+
+		<div class:list={["grid grid-cols-1 sm:grid-cols-2 md:grid-cols-4 gap-10 sm:justify-end", debugClasses.section]}>
+			{/* 产品导航 */}
+			{products.length > 0 && (
+				<nav class:list={["", debugClasses.nav]}>
+					<h6 class="footer-title">产品</h6>
+					{products.map((product) => (
+						<Link href={product.href} external={product.external} block animation='hover-lift'>
+							{product.name}
+						</Link>
+					))}
+				</nav>
+			)}
+
+			{/* 关于导航 */}
+			{(aboutLink || contactLink || teamLink || careersLink) && (
+				<nav class:list={["", debugClasses.nav]}>
+					<h6 class="footer-title">关于我们</h6>
+					{aboutLink && <Link href={aboutLink} block animation='hover-lift'>关于我们</Link>}
+					{teamLink && <Link href={teamLink} block animation='hover-lift'>团队介绍</Link>}
+					{careersLink && <Link href={careersLink} block animation='hover-lift'>加入我们</Link>}
+					{contactLink && <Link href={contactLink} block animation='hover-lift'>联系我们</Link>}
+				</nav>
+			)}
+
+			{/* 资源导航 */}
+			{(newsLink || historyLink || partnersLink || blogLink || faqLink || mediaLink || techStackLink) && (
+				<nav class:list={["", debugClasses.nav]}>
+					<h6 class="footer-title">资源</h6>
+					{newsLink && <Link href={newsLink} block animation='hover-lift'>新闻动态</Link>}
+					{blogLink && <Link href={blogLink} block animation='hover-lift'>技术博客</Link>}
+					{faqLink && <Link href={faqLink} block animation='hover-lift'>常见问题</Link>}
+					{techStackLink && <Link href={techStackLink} block animation='hover-lift'>技术栈</Link>}
+				</nav>
+			)}
+
+			{/* 法律导航 */}
+			{(termsLink || privacyLink) && (
+				<nav class:list={["", debugClasses.nav]}>
+					<h6 class="footer-title">法律</h6>
+					{termsLink && <Link href={termsLink} block animation='hover-lift'>服务条款</Link>}
+					{privacyLink && <Link href={privacyLink} block animation='hover-lift'>隐私政策</Link>}
+				</nav>
+			)}
+		</div>
+	</div>
+</footer>
+
+{/* 横幅 */}
+{inspirationalSlogan && (
+	<aside class:list={["p-4 bg-primary text-primary-content w-full", debugClasses.aside]}>
+		<p class="text-center">{inspirationalSlogan}</p>
+	</aside>
+)}
+
+{/* 底部版权信息 */}
+<div class:list={["footer footer-center p-4 bg-base-300 text-base-content", debugClasses.footer]}>
+	<aside class:list={["items-center grid-flow-col", debugClasses.aside]}>
+		<p class="text-sm opacity-70">
+			© {currentYear} {company} - {copyright}
+		</p>
+		{icp && (
+			<p class="text-sm opacity-70 ml-4">
+				{icp}
+			</p>
+		)}
+	</aside>
+</div>

package/dist/components/layouts/Grid.astro

@@ -0,0 +1,182 @@
+---
+/**
+ * @component Grid
+ * 
+ * @description
+ * Grid 组件是一个灵活的网格布局组件，用于创建响应式的多列布局。
+ * 它封装了 CSS Grid 的常用功能，提供简单易用的接口来控制网格的列数和间距。
+ * 
+ * @design
+ * 设计理念：
+ * 1. 简单易用 - 通过简洁的 API 控制复杂的 Grid 布局
+ * 2. 响应式优先 - 内置响应式断点，轻松创建适应不同屏幕尺寸的布局
+ * 3. 灵活可配置 - 支持自定义列数和间距
+ * 4. 语义化属性 - 使用直观的属性名称，降低学习成本
+ * 
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <Grid cols={3} gap="md">
+ *   <div>第一列</div>
+ *   <div>第二列</div>
+ *   <div>第三列</div>
+ * </Grid>
+ * ```
+ * 
+ * 响应式网格：
+ * ```astro
+ * <Grid cols={{base: 1, md: 2, lg: 3}} gap="lg">
+ *   <div>响应式网格</div>
+ *   <div>在不同屏幕尺寸下</div>
+ *   <div>显示不同的列数</div>
+ * </Grid>
+ * ```
+ * 
+ * 自定义行列间距：
+ * ```astro
+ * <Grid cols={2} rowGap="lg" colGap="sm">
+ *   <div>行间距大</div>
+ *   <div>列间距小</div>
+ *   <div>第三项</div>
+ *   <div>第四项</div>
+ * </Grid>
+ * ```
+ * 
+ * @props
+ * @prop {number | Object} [cols=1] - 网格列数，可以是固定值或响应式对象
+ * @prop {string} [gap="md"] - 网格间距，可选值：none, xs, sm, md, lg, xl
+ * @prop {string} [rowGap] - 行间距，默认与 gap 相同
+ * @prop {string} [colGap] - 列间距，默认与 gap 相同
+ * @prop {string} [class] - 自定义类名
+ * @prop {any} [class:list] - 类名列表
+ */
+
+// 导入样式
+import '../../app.css';
+
+import type { HTMLAttributes } from 'astro/types';
+
+type GapSize = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type Breakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+type ResponsiveValue<T> = T | {
+  base?: T;
+  sm?: T;
+  md?: T;
+  lg?: T;
+  xl?: T;
+  '2xl'?: T;
+};
+
+interface Props extends HTMLAttributes<'div'> {
+  /**
+   * 网格列数，可以是固定值或响应式对象
+   * @default 1
+   */
+  cols?: ResponsiveValue<number>;
+  
+  /**
+   * 网格间距
+   * @default "md"
+   */
+  gap?: GapSize;
+  
+  /**
+   * 行间距，默认与gap相同
+   */
+  rowGap?: GapSize;
+  
+  /**
+   * 列间距，默认与gap相同
+   */
+  colGap?: GapSize;
+  
+  /**
+   * 自定义类名
+   */
+  class?: string;
+  
+  /**
+   * 类名列表
+   */
+  'class:list'?: any;
+}
+
+const {
+  cols = 1,
+  gap = 'md',
+  rowGap,
+  colGap,
+  class: className = '',
+  'class:list': classList,
+  ...rest
+} = Astro.props;
+
+// 处理响应式列数
+const getColsClasses = (cols: ResponsiveValue<number>) => {
+  if (typeof cols === 'number') {
+    return `grid-cols-${cols}`;
+  }
+  
+  const breakpoints: Record<Breakpoint, string> = {
+    base: '',
+    sm: 'sm:',
+    md: 'md:',
+    lg: 'lg:',
+    xl: 'xl:',
+    '2xl': '2xl:'
+  };
+  
+  return Object.entries(cols)
+    .map(([breakpoint, value]) => {
+      if (breakpoint === 'base') {
+        return `grid-cols-${value}`;
+      }
+      return `${breakpoints[breakpoint as Breakpoint]}grid-cols-${value}`;
+    })
+    .join(' ');
+};
+
+// 间距映射
+const gapClasses: Record<GapSize, string> = {
+  none: 'gap-0',
+  xs: 'gap-2',
+  sm: 'gap-4',
+  md: 'gap-6',
+  lg: 'gap-8',
+  xl: 'gap-12'
+};
+
+// 行间距映射
+const rowGapClasses: Record<GapSize, string> = {
+  none: 'row-gap-0',
+  xs: 'row-gap-2',
+  sm: 'row-gap-4',
+  md: 'row-gap-6',
+  lg: 'row-gap-8',
+  xl: 'row-gap-12'
+};
+
+// 列间距映射
+const colGapClasses: Record<GapSize, string> = {
+  none: 'col-gap-0',
+  xs: 'col-gap-2',
+  sm: 'col-gap-4',
+  md: 'col-gap-6',
+  lg: 'col-gap-8',
+  xl: 'col-gap-12'
+};
+
+// 构建最终类名
+const gridClasses = [
+  'grid',
+  getColsClasses(cols),
+  rowGap ? rowGapClasses[rowGap as GapSize] : colGap ? gapClasses[gap as GapSize] : gapClasses[gap as GapSize],
+  colGap ? colGapClasses[colGap as GapSize] : null,
+  className
+].filter(Boolean).join(' ');
+---
+
+<div class:list={[gridClasses, classList]} {...rest}>
+  <slot />
+</div>