@coffic/cosy-ui 0.9.24 → 0.9.25

package/dist/src-astro/header/HeaderEnd.astro

@@ -0,0 +1,90 @@
+---
+/**
+ * @component HeaderEnd
+ *
+ * @description
+ * HeaderEnd 组件负责渲染 Header 的右侧区域，包括主题切换器、语言切换器和右侧导航项。
+ * 这是一个内部组件，通常由 Header 组件使用。
+ *
+ * @usage
+ * ```astro
+ * <HeaderEnd
+ *   navPosition={navPosition}
+ *   navItems={navItems}
+ *   activeLink={activeLink}
+ *   linkHeightClass={linkHeightClass}
+ *   showThemeSwitcher={showThemeSwitcher}
+ *   isI18nEnabled={isI18nEnabled}
+ *   astroI18n={astroI18n}
+ * />
+ * ```
+ *
+ * @props
+ * - navPosition - 导航位置
+ * - navItems - 导航项数组
+ * - activeLink - 当前激活的链接
+ * - linkHeightClass - 链接高度类名
+ * - showThemeSwitcher - 是否显示主题切换器
+ * - isI18nEnabled - 是否启用国际化
+ * - astroI18n - astro:i18n 模块
+ */
+import {
+  ThemeSwitcher,
+  LanguageSwitcher,
+  MenuIcon,
+  type INavItem,
+} from '../../index-astro';
+import NavItems from './NavItems.astro';
+
+export interface Props {
+  navPosition: string;
+  navItems: INavItem[];
+  activeLink: string;
+  linkHeightClass: string;
+  showThemeSwitcher: boolean;
+  isI18nEnabled: boolean;
+  astroI18n?: any;
+}
+
+const {
+  navPosition,
+  navItems,
+  activeLink,
+  linkHeightClass,
+  showThemeSwitcher,
+  isI18nEnabled,
+  astroI18n,
+} = Astro.props;
+---
+
+<div class="cosy:navbar-end cosy:pr-1">
+  {
+    navPosition === 'end' && (
+      <div class="cosy:hidden cosy:lg:flex">
+        <NavItems
+          navItems={navItems}
+          activeLink={activeLink}
+          linkHeightClass={linkHeightClass}
+          gap={4}
+        />
+      </div>
+    )
+  }
+
+  {showThemeSwitcher && <ThemeSwitcher />}
+  {isI18nEnabled && <LanguageSwitcher astroI18n={astroI18n} />}
+
+  <!-- 移动端汉堡菜单按钮 -->
+  {
+    navItems.length > 0 && (
+      <button
+        type="button"
+        class="cosy:btn cosy:btn-ghost cosy:btn-sm cosy:lg:hidden"
+        data-modal-target="mobile-nav">
+        <MenuIcon class="cosy:w-5 cosy:h-5" />
+      </button>
+    )
+  }
+
+  <slot name="navbar-end" />
+</div>

package/dist/src-astro/header/HeaderStart.astro

@@ -0,0 +1,78 @@
+---
+/**
+ * @component HeaderStart
+ *
+ * @description
+ * HeaderStart 组件负责渲染 Header 的左侧区域，包括 logo 和左侧导航项。
+ * 这是一个内部组件，通常由 Header 组件使用。
+ *
+ * @usage
+ * ```astro
+ * <HeaderStart
+ *   logo={logo}
+ *   logoHref={logoHref}
+ *   height={height}
+ *   navPosition={navPosition}
+ *   navItems={navItems}
+ *   activeLink={activeLink}
+ *   linkHeightClass={linkHeightClass}
+ *   debug={debug}
+ * />
+ * ```
+ *
+ * @props
+ * - logo - logo 图片
+ * - logoHref - logo 链接地址
+ * - height - header 高度
+ * - navPosition - 导航位置
+ * - navItems - 导航项数组
+ * - activeLink - 当前激活的链接
+ * - linkHeightClass - 链接高度类名
+ * - debug - 是否启用调试模式
+ */
+import { type INavItem } from '../../index-astro';
+import NavItems from './NavItems.astro';
+import LogoLink from './LogoLink.astro';
+
+export interface Props {
+  logo: string | ImageMetadata;
+  logoHref: string;
+  height: '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  navPosition: string;
+  navItems: INavItem[];
+  activeLink: string;
+  linkHeightClass: string;
+  debug: boolean;
+}
+
+const {
+  logo,
+  logoHref,
+  height,
+  navPosition,
+  navItems,
+  activeLink,
+  linkHeightClass,
+  debug,
+} = Astro.props;
+---
+
+<div class="cosy:navbar-start cosy:pl-1" data-role="header-start">
+  {
+    navPosition === 'start' ? (
+      <div class="cosy:flex cosy:items-center cosy:gap-4">
+        <LogoLink src={logo} href={logoHref} size={height} debug={debug} />
+        <div class="cosy:lg:flex">
+          <NavItems
+            navItems={navItems}
+            activeLink={activeLink}
+            linkHeightClass={linkHeightClass}
+          />
+        </div>
+      </div>
+    ) : (
+      <LogoLink src={logo} href={logoHref} size={height} debug={debug} />
+    )
+  }
+  <slot name="navbar-start" />
+</div>

package/dist/src-astro/header/MobileNav.astro

@@ -0,0 +1,44 @@
+---
+/**
+ * @component MobileNav
+ *
+ * @description
+ * MobileNav 组件是一个移动端导航菜单，用于在小屏幕设备上显示导航项。
+ * 这个组件通常与 Modal 组件配合使用，提供移动端的导航体验。
+ *
+ * @usage
+ * ```astro
+ * <MobileNav
+ *   navItems={navItems}
+ *   activeLink={activeLink}
+ *   linkHeightClass={linkHeightClass}
+ * />
+ * ```
+ *
+ * @props
+ * - navItems - 导航项数组
+ * - activeLink - 当前激活的链接
+ * - linkHeightClass - 链接高度类名
+ */
+import { type INavItem } from '../../index-astro';
+import NavItems from './NavItems.astro';
+
+export interface Props {
+  navItems: INavItem[];
+  activeLink: string;
+  linkHeightClass: string;
+}
+
+const { navItems, activeLink, linkHeightClass } = Astro.props;
+---
+
+<div class="cosy:flex cosy:flex-col cosy:gap-2">
+  <nav class="cosy:flex cosy:flex-col cosy:gap-1">
+    <NavItems
+      navItems={navItems}
+      activeLink={activeLink}
+      linkHeightClass={linkHeightClass}
+      vertical={true}
+    />
+  </nav>
+</div>

package/dist/src-astro/header/NavItems.astro

@@ -0,0 +1,82 @@
+---
+/**
+ * @component NavItems
+ *
+ * @description
+ * NavItems 组件用于渲染导航栏中的导航项目列表。
+ * 支持配置导航项之间的间距，提供预设的 gap 值。
+ *
+ * @usage
+ * ```astro
+ * <NavItems
+ *   navItems={navItems}
+ *   activeLink={activeLink}
+ *   linkHeightClass={linkHeightClass}
+ *   gap={2}
+ * />
+ * ```
+ *
+ * @props
+ * - navItems: INavItem[] - 导航项数组
+ * - activeLink: string - 当前激活的链接
+ * - linkHeightClass: string - 链接高度类名
+ * - vertical?: boolean - 是否垂直布局，默认 false
+ * - gap?: number - 导航项之间的间距，可选值：0, 1, 2, 3, 4, 6, 8, 10, 12，默认 2
+ */
+import '../../style.ts';
+import { type INavItem, Link, ListItem } from '../../index-astro';
+
+interface Props {
+  navItems: INavItem[];
+  activeLink: string;
+  linkHeightClass: string;
+  vertical?: boolean;
+  gap?: number;
+}
+
+const {
+  navItems,
+  activeLink,
+  linkHeightClass,
+  vertical = false,
+  gap = 2,
+} = Astro.props;
+
+// 预设的 gap 值映射
+const gapClasses = {
+  0: '',
+  1: 'cosy:gap-1',
+  2: 'cosy:gap-2',
+  3: 'cosy:gap-3',
+  4: 'cosy:gap-4',
+  6: 'cosy:gap-6',
+  8: 'cosy:gap-8',
+  10: 'cosy:gap-10',
+  12: 'cosy:gap-12',
+} as const;
+
+// 获取对应的 gap 类名
+const gapClass = gapClasses[gap as keyof typeof gapClasses] || gapClasses[2];
+---
+
+<ul
+  data-active-link={activeLink}
+  class:list={[
+    'cosy:px-1 cosy:menu cosy:w-full',
+    vertical ? 'cosy:menu-vertical' : 'cosy:menu-horizontal',
+    linkHeightClass,
+    gapClass,
+  ]}>
+  {
+    navItems.map((item) => (
+      <ListItem>
+        <Link
+          variant={activeLink === item.href ? 'primary' : 'default'}
+          href={item.href}
+          class:list={[linkHeightClass]}>
+          {item.title}
+        </Link>
+      </ListItem>
+    ))
+  }
+</ul>

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

@@ -1 +1,7 @@
 export { default as Header } from './Header.astro';
+export { default as HeaderStart } from './HeaderStart.astro';
+export { default as HeaderCenter } from './HeaderCenter.astro';
+export { default as HeaderEnd } from './HeaderEnd.astro';
+export { default as LogoLink } from './LogoLink.astro';
+export { default as MobileNav } from './MobileNav.astro';
+export { default as NavItems } from './NavItems.astro';

package/dist/src-astro/icons/GlobeIcon.astro

@@ -0,0 +1,28 @@
+---
+import AstroIcon from './AstroIcon.astro';
+
+interface Props {
+  /**
+   * 图标的大小
+   * @default "24px"
+   */
+  size?: string;
+  /**
+   * 图标的颜色
+   * @default "currentColor"
+   */
+  color?: string;
+  /**
+   * 自定义类名
+   */
+  class?: string;
+}
+
+const {
+  size = '24px',
+  color = 'currentColor',
+  class: className = '',
+} = Astro.props;
+---
+
+<AstroIcon name="globe" size={size} stroke={color} class={className} />

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

@@ -21,6 +21,7 @@ export { default as CodeIcon } from './CodeIcon.astro';
 export { default as DeleteIcon } from './DeleteIcon.astro';
 export { default as ErrorIcon } from './ErrorIcon.astro';
 export { default as GithubIcon } from './GithubIcon.astro';
+export { default as GlobeIcon } from './GlobeIcon.astro';
 export { default as InfoCircle } from './InfoCircle.astro';
 export { default as InboxArchive } from './InboxArchive.astro';
 export { default as SettingsIcon } from './SettingsIcon.astro';

package/dist/src-astro/language-switcher/LanguageSwitcher.astro

@@ -27,7 +27,7 @@
  * - class - 自定义CSS类名
  */
 
-import { ChevronDownIcon, Link, ListItem } from '../../index-astro';
+import { ChevronDownIcon, GlobeIcon, Link, ListItem } from '../../index-astro';
 import {
   checkSwitcherRenderState,
   generateSwitcherLinks,
@@ -78,7 +78,10 @@ if (renderState.shouldRender && Astro.currentLocale) {
   renderState.shouldRender && (
     <div class={`cosy:dropdown cosy:dropdown-end ${className}`}>
       <div tabindex="0" role="button" class:list={['cosy:btn cosy:btn-ghost']}>
-        <span class="cosy:mr-1">{renderState.currentLanguageName}</span>
+        <GlobeIcon size="16px" class="cosy:w-4 cosy:h-4 cosy:mr-1" />
+        <span class="cosy:mr-1 cosy:hidden cosy:sm:inline">
+          {renderState.currentLanguageName}
+        </span>
         <ChevronDownIcon size="16px" class="cosy:w-4 cosy:h-4" />
       </div>
       <ul

package/dist/src-astro/layout-app/AppHeader.astro

@@ -0,0 +1,95 @@
+---
+/**
+ * AppHeader组件
+ *
+ * 专门处理应用布局中的头部导航栏
+ *
+ * @param {Object} headerConfig - 头部配置
+ * @param {boolean} [debug=false] - 是否启用调试模式
+ * @param {boolean} [showSidebar=true] - 是否显示侧边栏切换按钮
+ * @param {boolean} [showSearch=true] - 是否显示搜索按钮
+ * @param {Object} rest - 其他属性
+ *
+ * @slot navbar-start - 导航栏开始位置的内容
+ * @slot navbar-center - 导航栏中间位置的内容
+ * @slot navbar-end - 导航栏结束位置的内容
+ * @slot modal-search - 搜索模态框内容，当提供此slot时会显示搜索按钮
+ *
+ * @example
+ * ```astro
+ * ---
+ * import AppHeader from './AppHeader.astro';
+ * import { Button } from '@coffic/cosy-ui';
+ * ---
+ *
+ * <AppHeader>
+ *   <div slot="navbar-start">
+ *     <h1 class="cosy:text-xl cosy:font-bold">我的应用</h1>
+ *   </div>
+ *
+ *   <div slot="navbar-center">
+ *     <nav class="cosy:flex cosy:gap-4">
+ *       <a href="/docs" class="cosy:link cosy:link-hover">文档</a>
+ *       <a href="/components" class="cosy:link cosy:link-hover">组件</a>
+ *     </nav>
+ *   </div>
+ *
+ *   <div slot="navbar-end">
+ *     <Button variant="primary">登录</Button>
+ *   </div>
+ * </AppHeader>
+ * ```
+ */
+
+import '../../style.ts';
+import { Header, Button, MenuIcon, SearchIcon } from '../../index-astro';
+
+interface Props {
+  headerConfig?: any;
+  debug?: boolean;
+  showSidebar?: boolean;
+  showSearch?: boolean;
+  [key: string]: any;
+}
+
+const {
+  headerConfig = {},
+  debug = false,
+  showSidebar = true,
+  showSearch = true,
+  ...rest
+}: Props = Astro.props;
+---
+
+<Header {...headerConfig} debug={debug}>
+  <div slot="navbar-start">
+    {/* 小屏幕显示侧边栏切换按钮 */}
+    {
+      showSidebar && (
+        <Button
+          class="cosy:lg:hidden"
+          data-modal-target="mobile-sidebar"
+          variant="ghost"
+          size="sm">
+          <MenuIcon size="20px" />
+        </Button>
+      )
+    }
+    <slot name="navbar-start" />
+  </div>
+
+  <div slot="navbar-center">
+    <slot name="navbar-center" />
+  </div>
+
+  <div slot="navbar-end">
+    {
+      showSearch && Astro.slots.has('modal-search') && (
+        <Button data-modal-target="modalSearch" variant="ghost" size="sm">
+          <SearchIcon size="24px" />
+        </Button>
+      )
+    }
+    <slot name="navbar-end" />
+  </div>
+</Header>

package/dist/src-astro/layout-app/AppLayout.astro

@@ -2,7 +2,7 @@
 /**
  * AppLayout组件
  *
- * 适用于页面布局，包含侧边栏导航和目录
+ * 适用于页面布局，包含头部导航、侧边栏导航和目录
  *
  * 布局效果：
  *
@@ -45,15 +45,15 @@
  * @param {boolean} [debug=true] - 是否启用调试模式
  * @param {Object} mainContentConfig - 主内容区域配置
  * @param {Object} footerConfig - 页脚配置
- * @param {Object} headerConfig - 头部配置
+ * @param {Object} headerConfig - 头部配置（传递给AppHeader组件）
  * @param {Object} metaConfig - 元数据配置
  * @param {Object} rest - 其他属性
  *
  * @slot default - 主内容区域
- * @slot navbar-start - 导航栏开始位置的内容
- * @slot navbar-center - 导航栏中间位置的内容
- * @slot navbar-end - 导航栏结束位置的内容
- * @slot modal-search - 搜索模态框内容，当提供此slot时会显示搜索按钮
+ * @slot navbar-start - 导航栏开始位置的内容（传递给AppHeader）
+ * @slot navbar-center - 导航栏中间位置的内容（传递给AppHeader）
+ * @slot navbar-end - 导航栏结束位置的内容（传递给AppHeader）
+ * @slot modal-search - 搜索模态框内容，当提供此slot时会显示搜索按钮（传递给AppHeader）
  *
  * @example
  * ```astro
@@ -242,14 +242,12 @@ import {
   BaseLayout,
   type IAppLayoutProps,
   Footer,
-  Header,
   Container,
   Main,
   Sidebar,
   Modal,
-  SearchIcon,
-  Button,
 } from '../../index-astro';
+import AppHeader from './AppHeader.astro';
 import SkeletonLoader from './SkeletonLoader.astro';
 
 interface Props extends IAppLayoutProps {}
@@ -328,22 +326,16 @@ const sidebarHeightClass = getSidebarHeightClass(headerConfig?.height);
 <BaseLayout {...metaConfig} debug={debug}>
   {
     showHeader && (
-      <Header {...headerConfig} debug={debug}>
-        <div slot="navbar-start">
-          <slot name="navbar-start" />
-        </div>
-        <div slot="navbar-center">
-          <slot name="navbar-center" />
-        </div>
-        <div slot="navbar-end">
-          {Astro.slots.has('modal-search') && (
-            <Button data-modal-target="modalSearch" variant="ghost" size="sm">
-              <SearchIcon size="24px" />
-            </Button>
-          )}
-          <slot name="navbar-end" />
-        </div>
-      </Header>
+      <AppHeader
+        headerConfig={headerConfig}
+        debug={debug}
+        showSidebar={showSidebar}
+        showSearch={true}>
+        <slot name="navbar-start" slot="navbar-start" />
+        <slot name="navbar-center" slot="navbar-center" />
+        <slot name="navbar-end" slot="navbar-end" />
+        <slot name="modal-search" slot="modal-search" />
+      </AppHeader>
     )
   }
 
@@ -365,7 +357,7 @@ const sidebarHeightClass = getSidebarHeightClass(headerConfig?.height);
     }
 
     <!-- 主内容区域 -->
-    <Main {...mainContentConfig} class="cosy:flex-1 cosy:min-w-0">
+    <Main {...mainContentConfig} class="cosy:flex-1 cosy:min-w-xs">
       <SkeletonLoader
         showLoading={true}
         loadingSize="xl"

package/dist/src-astro/modal/Modal.astro

@@ -42,6 +42,13 @@
  *   <img src="/images/large-image.jpg" alt="大图预览" />
  * </Modal>
  * ```
+ *
+ * 带链接标题的模态框：
+ * ```astro
+ * <Modal id="help-modal" title="帮助文档" titleHref="/help" titleExternal>
+ *   <p>点击标题可以跳转到帮助文档。</p>
+ * </Modal>
+ * ```
  */
 
 import '../../style.ts';
@@ -57,20 +64,38 @@ interface Props {
    * 模态框的标题
    */
   title?: string;
+  /**
+   * 标题的链接地址，传入后标题会变成可点击的链接
+   */
+  titleHref?: string;
+  /**
+   * 标题链接是否为外部链接
+   */
+  titleExternal?: boolean;
   /**
    * 自定义类名
    */
   class?: string;
 }
 
-const { id, title = '', class: className = '' } = Astro.props;
+const {
+  id,
+  title = '',
+  titleHref,
+  titleExternal = false,
+  class: className = '',
+} = Astro.props;
 ---
 
 <dialog id={id} class="cosy:modal">
-  <div class:list={['cosy:modal-box cosy:pt-0', className]}>
+  <div class:list={['cosy:modal-box', className]}>
     <div
-      class="cosy:flex cosy:justify-between cosy:items-center cosy:border-b-1 cosy:border-base-300 cosy:mb-4 not-prose">
-      <Heading level={4} class="cosy:modal-title cosy:m-0">
+      class="cosy:flex cosy:justify-between cosy:items-center cosy:p-2 cosy:border-b-1 cosy:border-base-300 not-prose">
+      <Heading
+        level={4}
+        class="cosy:modal-title cosy:m-0"
+        href={titleHref}
+        external={titleExternal}>
         {title}
       </Heading>
       <CloseButton class="cosy:absolute" />