@coffic/cosy-ui 0.7.2 → 0.8.6

package/dist/{header → src-astro/header}/index.ts

@@ -13,14 +13,28 @@ import CustomNavbarStartSourceCode from './HeaderCustomNavbarStart.astro?raw';
 import CustomNavbarCenterSourceCode from './HeaderCustomNavbarCenter.astro?raw';
 import { extractSimpleExample } from '../utils/component';
 
-export { Header, HeaderBasic, HeaderWithNavigation, HeaderCustomPosition, HeaderCustomNavbarEnd, HeaderCustomNavbarStart, HeaderCustomNavbarCenter };
+export {
+  Header,
+  HeaderBasic,
+  HeaderWithNavigation,
+  HeaderCustomPosition,
+  HeaderCustomNavbarEnd,
+  HeaderCustomNavbarStart,
+  HeaderCustomNavbarCenter,
+};
 
 // 导出示例源代码
 export const HeaderExampleCodes = {
-	Basic: extractSimpleExample(BasicSourceCode, 'Header'),
-	WithNavigation: extractSimpleExample(WithNavigationSourceCode, 'Header'),
-	CustomPosition: extractSimpleExample(CustomPositionSourceCode, 'Header'),
-	CustomNavbarEnd: extractSimpleExample(CustomNavbarEndSourceCode, 'Header'),
-	CustomNavbarStart: extractSimpleExample(CustomNavbarStartSourceCode, 'Header'),
-	CustomNavbarCenter: extractSimpleExample(CustomNavbarCenterSourceCode, 'Header'),
-};
+  Basic: extractSimpleExample(BasicSourceCode, 'Header'),
+  WithNavigation: extractSimpleExample(WithNavigationSourceCode, 'Header'),
+  CustomPosition: extractSimpleExample(CustomPositionSourceCode, 'Header'),
+  CustomNavbarEnd: extractSimpleExample(CustomNavbarEndSourceCode, 'Header'),
+  CustomNavbarStart: extractSimpleExample(
+    CustomNavbarStartSourceCode,
+    'Header'
+  ),
+  CustomNavbarCenter: extractSimpleExample(
+    CustomNavbarCenterSourceCode,
+    'Header'
+  ),
+};

package/dist/src-astro/heading/Heading.astro

@@ -0,0 +1,245 @@
+---
+/**
+ * @component Heading
+ *
+ * @description
+ * Heading 组件用于创建各级标题，提供一致的排版样式和灵活的定制选项。
+ *
+ * @design
+ * 设计理念：
+ * 1. 层次清晰 - 通过不同级别的标题建立内容的视觉层次结构
+ * 2. 一致性 - 确保整个应用中标题样式的一致性
+ * 3. 可定制性 - 支持多种配置选项，适应不同场景需求
+ * 4. 无障碍性 - 遵循语义化HTML标准，确保屏幕阅读器可以正确解析内容结构
+ *
+ * 视觉特点：
+ * - 字体大小和粗细随级别变化
+ * - 可选的下划线或底部边框
+ * - 可定制的颜色和间距
+ * - 响应式设计，在不同屏幕尺寸下保持良好的可读性
+ *
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <Heading level={1}>这是一个一级标题</Heading>
+ * <Heading level={2}>这是一个二级标题</Heading>
+ * <Heading level={3}>这是一个三级标题</Heading>
+ * ```
+ *
+ * 自定义样式：
+ * ```astro
+ * <Heading level={2} color="primary" underline>带下划线的二级标题</Heading>
+ * ```
+ *
+ * 带锚点链接：
+ * ```astro
+ * <Heading level={2} id="section-1" anchor>带锚点的标题</Heading>
+ * ```
+ *
+ * 自定义间距：
+ * ```astro
+ * <Heading level={1} class="cosy:mb-8">自定义底部间距的标题</Heading>
+ * ```
+ *
+ * @props
+ * @prop {1|2|3|4|5|6} [level=2] - 标题级别，对应 h1-h6 标签
+ * @prop {string} [id] - 标题的 ID，用于锚点链接
+ * @prop {boolean} [anchor=false] - 是否显示锚点链接图标
+ * @prop {boolean} [underline=false] - 是否显示下划线
+ * @prop {string} [align='left'] - 文本对齐方式：'left', 'center', 'right'
+ * @prop {'default'|'primary'|'secondary'|'accent'|'muted'} [color='default'] - 标题颜色
+ * @prop {string} [class] - 自定义 CSS 类名
+ *
+ * @slots
+ * @slot default - 标题内容
+ *
+ * @accessibility
+ * - 使用语义化的 h1-h6 标签
+ * - 锚点链接带有描述性 aria-label
+ * - 遵循标题层次结构的最佳实践
+ *
+ * @dependencies
+ * 依赖于以下图标组件：
+ * - LinkIcon (用于锚点链接)
+ */
+
+import { LinkIcon } from '../../index-astro';
+import '../../style.ts';
+
+interface Props {
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  id?: string;
+  anchor?: boolean;
+  underline?: boolean;
+  align?: 'left' | 'center' | 'right';
+  color?: 'default' | 'primary' | 'secondary' | 'accent' | 'muted';
+  class?: string;
+}
+
+const {
+  level = 2,
+  id,
+  anchor = false,
+  underline = false,
+  align = 'left',
+  color = 'default',
+  class: className = '',
+} = Astro.props;
+
+// 根据级别和颜色设置样式
+const headingClass = {
+  1: 'cosy:text-4xl cosy:font-bold',
+  2: 'cosy:text-3xl cosy:font-semibold',
+  3: 'cosy:text-2xl cosy:font-semibold',
+  4: 'cosy:text-xl cosy:font-medium',
+  5: 'cosy:text-lg cosy:font-medium',
+  6: 'cosy:text-base cosy:font-medium',
+}[(level ?? 2) as 1 | 2 | 3 | 4 | 5 | 6];
+
+const colorClass = {
+  default: 'cosy:text-gray-900 cosy:dark:text-gray-100',
+  primary: 'cosy:text-primary-600 cosy:dark:text-primary-400',
+  secondary: 'cosy:text-secondary-600 cosy:dark:text-secondary-400',
+  accent: 'cosy:text-accent-600 cosy:dark:text-accent-400',
+  muted: 'cosy:text-gray-600 cosy:dark:text-gray-400',
+}[
+  (color ?? 'default') as
+    | 'default'
+    | 'primary'
+    | 'secondary'
+    | 'accent'
+    | 'muted'
+];
+
+const alignClass = {
+  left: 'cosy:text-left',
+  center: 'cosy:text-center',
+  right: 'cosy:text-right',
+}[(align ?? 'left') as 'left' | 'center' | 'right'];
+
+const underlineClass = underline
+  ? 'cosy:border-b cosy:pb-2 cosy:border-gray-200 cosy:dark:border-gray-700'
+  : '';
+
+// 组合所有类名
+const combinedClass = `heading ${headingClass} ${colorClass} ${alignClass} ${underlineClass} ${className}`;
+---
+
+{
+  level === 1 && (
+    <h1 id={id} class={combinedClass}>
+      <slot />
+      {anchor && id && (
+        <a
+          href={`#${id}`}
+          class="cosy:hover:opacity-100 cosy:opacity-0 cosy:ml-2 cosy:transition-opacity heading-anchor"
+          aria-label={`链接到 ${id} 部分`}>
+          <LinkIcon class="cosy:inline-block cosy:w-4 cosy:h-4" />
+        </a>
+      )}
+    </h1>
+  )
+}
+
+{
+  level === 2 && (
+    <h2 id={id} class={combinedClass}>
+      <slot />
+      {anchor && id && (
+        <a
+          href={`#${id}`}
+          class="cosy:hover:opacity-100 cosy:opacity-0 cosy:ml-2 cosy:transition-opacity heading-anchor"
+          aria-label={`链接到 ${id} 部分`}>
+          <LinkIcon class="cosy:inline-block cosy:w-4 cosy:h-4" />
+        </a>
+      )}
+    </h2>
+  )
+}
+
+{
+  level === 3 && (
+    <h3 id={id} class={combinedClass}>
+      <slot />
+      {anchor && id && (
+        <a
+          href={`#${id}`}
+          class="cosy:hover:opacity-100 cosy:opacity-0 cosy:ml-2 cosy:transition-opacity heading-anchor"
+          aria-label={`链接到 ${id} 部分`}>
+          <LinkIcon class="cosy:inline-block cosy:w-4 cosy:h-4" />
+        </a>
+      )}
+    </h3>
+  )
+}
+
+{
+  level === 4 && (
+    <h4 id={id} class={combinedClass}>
+      <slot />
+      {anchor && id && (
+        <a
+          href={`#${id}`}
+          class="cosy:hover:opacity-100 cosy:opacity-0 cosy:ml-2 cosy:transition-opacity heading-anchor"
+          aria-label={`链接到 ${id} 部分`}>
+          <LinkIcon class="cosy:inline-block cosy:w-4 cosy:h-4" />
+        </a>
+      )}
+    </h4>
+  )
+}
+
+{
+  level === 5 && (
+    <h5 id={id} class={combinedClass}>
+      <slot />
+      {anchor && id && (
+        <a
+          href={`#${id}`}
+          class="cosy:hover:opacity-100 cosy:opacity-0 cosy:ml-2 cosy:transition-opacity heading-anchor"
+          aria-label={`链接到 ${id} 部分`}>
+          <LinkIcon class="cosy:inline-block cosy:w-4 cosy:h-4" />
+        </a>
+      )}
+    </h5>
+  )
+}
+
+{
+  level === 6 && (
+    <h6 id={id} class={combinedClass}>
+      <slot />
+      {anchor && id && (
+        <a
+          href={`#${id}`}
+          class="cosy:hover:opacity-100 cosy:opacity-0 cosy:ml-2 cosy:transition-opacity heading-anchor"
+          aria-label={`链接到 ${id} 部分`}>
+          <LinkIcon class="cosy:inline-block cosy:w-4 cosy:h-4" />
+        </a>
+      )}
+    </h6>
+  )
+}
+
+<style>
+  .heading {
+    margin-bottom: 0.5em;
+    line-height: 1.2;
+    scroll-margin-top: 100px;
+  }
+
+  .heading-anchor {
+    color: inherit;
+    text-decoration: none;
+    vertical-align: middle;
+  }
+
+  /* 悬停效果 */
+  .heading:hover .heading-anchor {
+    opacity: 0.7 !important;
+  }
+
+  .heading-anchor:hover {
+    opacity: 1 !important;
+  }
+</style>

package/dist/{heading → src-astro/heading}/index.ts

@@ -7,5 +7,5 @@ export { Heading, HeadingBasic };
 
 // 导出示例源代码
 export const HeadingExampleCodes = {
-	Basic: extractSimpleExample(BasicSourceCode, 'Heading'),
+  Basic: extractSimpleExample(BasicSourceCode, 'Heading'),
 };

package/dist/src-astro/hero/Hero.astro

@@ -0,0 +1,381 @@
+---
+/**
+ * @component Hero
+ *
+ * @description
+ * Hero 组件是一个全屏的展示区域，通常用于网站的首页或重要页面的顶部。
+ * 它提供了一个引人注目的视觉区域，可以包含标题、描述、图片和行动按钮。
+ *
+ * @design
+ * 设计理念：
+ * 1. 视觉冲击力 - 全屏展示，吸引用户注意
+ * 2. 内容聚焦 - 清晰地传达核心信息
+ * 3. 引导行动 - 通过链接按钮引导用户进行下一步操作
+ * 4. 灵活布局 - 支持图片、标题、描述和自定义内容
+ *
+ * @usage
+ * 基本用法：
+ * ```astro
+ * <Hero
+ *   title="欢迎使用我们的产品"
+ *   description="这是一个简短的描述，介绍产品的主要特点和价值。"
+ *   links={[
+ *     { text: "开始使用", href: "/getting-started" },
+ *     { text: "了解更多", href: "/about" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 带图片的用法（图片在右侧）：
+ * ```astro
+ * <Hero
+ *   title="产品展示"
+ *   description="查看我们的最新产品。"
+ *   image={{ src: "/images/product.png", alt: "产品图片" }}
+ *   imagePosition="right"
+ *   links={[
+ *     { text: "立即购买", href: "/buy" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 带图片的用法（图片在左侧）：
+ * ```astro
+ * <Hero
+ *   title="产品展示"
+ *   description="查看我们的最新产品。"
+ *   image={{ src: "/images/product.png", alt: "产品图片" }}
+ *   imagePosition="left"
+ *   links={[
+ *     { text: "立即购买", href: "/buy" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 带图片的用法（图片在顶部）：
+ * ```astro
+ * <Hero
+ *   title="产品展示"
+ *   description="查看我们的最新产品。"
+ *   image={{ src: "/images/product.png", alt: "产品图片" }}
+ *   imagePosition="top"
+ *   links={[
+ *     { text: "立即购买", href: "/buy" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 带图片的用法（图片在底部）：
+ * ```astro
+ * <Hero
+ *   title="产品展示"
+ *   description="查看我们的最新产品。"
+ *   image={{ src: "/images/product.png", alt: "产品图片" }}
+ *   imagePosition="bottom"
+ *   links={[
+ *     { text: "立即购买", href: "/buy" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 带背景图片的用法：
+ * ```astro
+ * <Hero
+ *   title="产品展示"
+ *   description="查看我们的最新产品。"
+ *   backgroundImage="/images/hero-bg.jpg"
+ *   backgroundOverlay="dark"
+ *   links={[
+ *     { text: "立即购买", href: "/buy" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 带渐变背景遮罩的背景图片：
+ * ```astro
+ * <Hero
+ *   title="产品展示"
+ *   description="查看我们的最新产品。"
+ *   backgroundImage="/images/hero-bg.jpg"
+ *   backgroundOverlay="gradient"
+ *   links={[
+ *     { text: "立即购买", href: "/buy" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 自定义遮罩不透明度：
+ * ```astro
+ * <Hero
+ *   title="产品展示"
+ *   description="查看我们的最新产品。"
+ *   backgroundImage="/images/hero-bg.jpg"
+ *   backgroundOverlay="dark"
+ *   overlayOpacity={0.5}
+ *   links={[
+ *     { text: "立即购买", href: "/buy" }
+ *   ]}
+ * />
+ * ```
+ *
+ * 带自定义内容的用法：
+ * ```astro
+ * <Hero
+ *   title="交互式演示"
+ *   description="尝试我们的交互式演示。"
+ *   links={[
+ *     { text: "查看文档", href: "/docs" }
+ *   ]}
+ * >
+ *   <div slot="app">
+ *     <InteractiveDemo />
+ *   </div>
+ * </Hero>
+ * ```
+ *
+ * @props
+ * @prop {string} title - Hero 区域的主标题
+ * @prop {string} description - 标题下方的描述文本
+ * @prop {Object} [image] - 可选的图片配置
+ * @prop {string} image.src - 图片的源地址
+ * @prop {string} image.alt - 图片的替代文本
+ * @prop {Array<Link>} links - 链接按钮数组
+ * @prop {string} links[].text - 链接按钮的文本
+ * @prop {string} links[].href - 链接按钮的目标地址
+ * @prop {string} [background="gradient"] - 背景样式，可选值："gradient", "plain"
+ * @prop {string} [align="center"] - 内容对齐方式，可选值："center", "left", "right"
+ * @prop {string} [imagePosition="right"] - 图片位置，可选值："right", "left", "top", "bottom"
+ * @prop {string} [backgroundImage] - 背景图片的URL
+ * @prop {string} [backgroundOverlay="none"] - 背景图片上的遮罩，可选值："none", "light", "dark", "primary", "gradient"
+ * @prop {number} [overlayOpacity=0.7] - 遮罩的不透明度，可选值：0-1之间的数字
+ */
+
+import '../../style.ts';
+import { Link } from '../../index-astro';
+
+interface Link {
+  text: string;
+  href: string;
+}
+
+interface Props {
+  title: string;
+  description: string;
+  image?: {
+    src: string;
+    alt: string;
+  };
+  links: Link[];
+  background?: 'gradient' | 'plain';
+  align?: 'center' | 'left' | 'right';
+  imagePosition?: 'right' | 'left' | 'top' | 'bottom';
+  backgroundImage?: string;
+  backgroundOverlay?: 'none' | 'light' | 'dark' | 'primary' | 'gradient';
+  overlayOpacity?: number;
+}
+
+const {
+  title,
+  description,
+  image,
+  links = [],
+  background = 'gradient',
+  align = 'center',
+  imagePosition = 'right',
+  backgroundImage,
+  backgroundOverlay = 'none',
+  overlayOpacity = 0.7,
+} = Astro.props;
+
+// 确保不透明度在0-1之间
+const safeOpacity = Math.max(0, Math.min(1, overlayOpacity));
+
+// 确定容器类
+const containerClasses = [
+  'cosy:hero',
+  'cosy:min-h-screen',
+  'cosy:w-full',
+  'cosy:relative',
+  backgroundImage ? 'cosy:bg-cover cosy:bg-center' : '',
+  !backgroundImage && background === 'gradient'
+    ? 'cosy:bg-gradient-to-br cosy:from-primary/10 cosy:to-secondary/20'
+    : '',
+  !backgroundImage && background === 'plain' ? 'cosy:bg-base-100' : '',
+].join(' ');
+
+// 确定内容布局类
+const contentClasses = [
+  'cosy:flex',
+  imagePosition === 'top' || imagePosition === 'bottom'
+    ? 'cosy:flex-col'
+    : 'cosy:flex-col cosy:lg:flex-row',
+  align === 'center' ? 'cosy:text-center cosy:items-center' : '',
+  align === 'left' ? 'cosy:text-left cosy:items-start' : '',
+  align === 'right' ? 'cosy:text-right cosy:items-end' : '',
+  'cosy:w-full',
+  'cosy:mx-auto',
+  'cosy:gap-10',
+  'cosy:lg:gap-16',
+  'cosy:z-10',
+  'cosy:relative',
+  'cosy:py-16',
+  'cosy:px-4',
+  'cosy:sm:px-6',
+  'cosy:lg:px-8',
+].join(' ');
+
+// 确定背景遮罩类
+const overlayClasses = [
+  'cosy:absolute',
+  'cosy:inset-0',
+  'cosy:z-0',
+  'cosy:m-0',
+  'cosy:p-0',
+].join(' ');
+
+// 创建遮罩样式对象，包括不透明度
+const overlayStyle =
+  backgroundOverlay === 'light'
+    ? { backgroundColor: `rgba(255, 255, 255, ${safeOpacity})` }
+    : backgroundOverlay === 'dark'
+      ? { backgroundColor: `rgba(0, 0, 0, ${safeOpacity})` }
+      : backgroundOverlay === 'primary'
+        ? {
+            backgroundColor: `var(--color-primary-500, #4338ca)`,
+            opacity: safeOpacity,
+          }
+        : backgroundOverlay === 'gradient'
+          ? {
+              backgroundImage: `linear-gradient(135deg, var(--color-primary-500, #4338ca) ${safeOpacity * 100}%, var(--color-secondary-500, #0ea5e9) ${safeOpacity * 100}%)`,
+            }
+          : {};
+
+const titleClasses = [
+  'cosy:text-5xl',
+  'cosy:font-bold',
+  'cosy:mb-4',
+  'cosy:sm:text-6xl',
+  'cosy:lg:text-7xl',
+  backgroundImage &&
+  (backgroundOverlay === 'dark' || backgroundOverlay === 'gradient')
+    ? 'cosy:text-white'
+    : 'cosy:text-primary',
+].join(' ');
+
+const descriptionClasses = [
+  'cosy:text-xl',
+  'cosy:max-w-3xl',
+  'cosy:mb-8',
+  backgroundImage &&
+  (backgroundOverlay === 'dark' || backgroundOverlay === 'gradient')
+    ? 'cosy:text-white cosy:opacity-90'
+    : 'cosy:opacity-80',
+].join(' ');
+
+const imageClasses = [
+  'cosy:rounded-lg',
+  'cosy:shadow-2xl',
+  'cosy:transition-all',
+  'cosy:duration-300',
+  'cosy:hover:scale-105',
+  'cosy:hover:shadow-primary/20',
+  imagePosition === 'top' || imagePosition === 'bottom'
+    ? 'cosy:max-w-lg cosy:w-full'
+    : 'cosy:max-w-sm cosy:lg:max-w-md',
+].join(' ');
+
+const linksContainerClasses = [
+  'cosy:flex',
+  'cosy:flex-wrap',
+  'cosy:gap-4',
+  align === 'center' ? 'cosy:justify-center' : '',
+  align === 'left' ? 'cosy:justify-start' : '',
+  align === 'right' ? 'cosy:justify-end' : '',
+  'cosy:mt-4',
+].join(' ');
+
+const appContainerClasses = [
+  'cosy:w-full',
+  'cosy:max-w-3xl',
+  'cosy:mx-auto',
+  'cosy:my-8',
+].join(' ');
+
+// 确定图片顺序
+const imageOrder = {
+  right: 'cosy:order-1 cosy:lg:order-2',
+  left: 'cosy:order-2 cosy:lg:order-1',
+  top: 'cosy:order-1',
+  bottom: 'cosy:order-3',
+};
+
+// 确定内容顺序
+const contentOrder = {
+  right: 'cosy:order-2 cosy:lg:order-1',
+  left: 'cosy:order-1 cosy:lg:order-2',
+  top: 'cosy:order-2',
+  bottom: 'cosy:order-1',
+};
+---
+
+<div
+  class={containerClasses}
+  style={backgroundImage ? `background-image: url(${backgroundImage})` : ''}
+  ignore-heading>
+  {
+    backgroundImage && backgroundOverlay !== 'none' && (
+      <div class={overlayClasses} style={overlayStyle} />
+    )
+  }
+
+  <div class={contentClasses}>
+    {
+      image && (
+        <div class={imageOrder[imagePosition]}>
+          <img class={imageClasses} src={image.src} alt={image.alt} />
+        </div>
+      )
+    }
+
+    <div
+      class={contentOrder[imagePosition] +
+        ' cosy:flex cosy:flex-col cosy:w-full ' +
+        (align === 'center' ? 'cosy:text-center cosy:items-center' : '') +
+        (align === 'left' ? 'cosy:text-left cosy:items-start' : '') +
+        (align === 'right' ? 'cosy:text-right cosy:items-end' : '')}>
+      <h2 class={titleClasses}>{title}</h2>
+      <p class={descriptionClasses}>
+        {description}
+      </p>
+
+      {
+        Astro.slots.has('app') && (
+          <div class={appContainerClasses}>
+            <slot name="app" />
+          </div>
+        )
+      }
+
+      <div class={linksContainerClasses}>
+        {
+          links.map((link: Link) => (
+            <Link
+              href={link.href}
+              external
+              variant={
+                backgroundImage &&
+                (backgroundOverlay === 'dark' ||
+                  backgroundOverlay === 'gradient')
+                  ? 'light'
+                  : 'cta'
+              }
+              animation="hover-lift"
+              size="lg">
+              {link.text}
+            </Link>
+          ))
+        }
+      </div>
+    </div>
+  </div>
+</div>

package/dist/src-astro/hero/HeroAlignCenter.astro

@@ -0,0 +1,13 @@
+---
+import Hero from './Hero.astro';
+---
+
+<Hero
+  title="居中对齐标题"
+  description="这是一个居中对齐的Hero组件示例。"
+  align="center"
+  links={[
+    { text: '主要操作', href: '#' },
+    { text: '次要操作', href: '#' },
+  ]}
+/>