@rxdrag/website-lib 0.0.120 → 0.0.121

package/components/BackgroundGroup.astro

@@ -14,8 +14,13 @@ const defaultClass =
 
 <Fragment>
   {
-    backgrounds?.map((background) => (
-      <Background background={background} defaultClass={defaultClass} />
-    ))
+    backgrounds?.length
+      ? backgrounds.map((background) => (
+          <Background
+            background={background}
+            defaultClass={defaultClass}
+          />
+        ))
+      : null
   }
 </Fragment>

package/components/BaseBlock.astro

@@ -0,0 +1,34 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import type { BackgroundConfig } from "@rxdrag/website-lib-core";
+import BackgroundGroup from "./BackgroundGroup.astro";
+
+/**
+ * 基础容器壳
+ *
+ * 规范：被冻结（Frozen）的设计器原子组件（基础壳）
+ * - 对外接口与 DOM 结构应保持稳定，不随业务随意增删/调整
+ * - 允许通过原生属性透传（...rest）注入 id/style/data-*（如 data-aos-*）等通用能力
+ * - baseClass 用于提供组件的默认类名；class/className 由使用方叠加
+ * - backgrounds 用于渲染 BackgroundGroup
+ */
+
+interface Props extends HTMLAttributes<"div"> {
+  baseClass?: string | string[];
+  className?: string;
+  backgrounds?: BackgroundConfig[];
+}
+
+const {
+  baseClass = "",
+  className,
+  class: classAttr,
+  backgrounds,
+  ...rest
+} = Astro.props;
+---
+
+<div class:list={[baseClass, className, classAttr]} {...rest}>
+  {backgrounds?.length ? <BackgroundGroup backgrounds={backgrounds} /> : null}
+  <slot />
+</div>

package/components/{FooterShell.astro → BaseFooter.astro}

@@ -1,8 +1,6 @@
 ---
-import type {
-  AnimationConfig,
-  BackgroundConfig,
-} from "@rxdrag/website-lib-core";
+import type { HTMLAttributes } from "astro/types";
+import type { BackgroundConfig } from "@rxdrag/website-lib-core";
 import BackgroundGroup from "./BackgroundGroup.astro";
 import Container from "./Container.astro";
 
@@ -10,13 +8,10 @@ import Container from "./Container.astro";
  * 区块
  */
 
-interface Props {
-  class?: string;
+interface Props extends HTMLAttributes<'footer'> {
   className?: string;
   containerClassName?: string;
   backgrounds?: BackgroundConfig[];
-  //动效
-  animation?: AnimationConfig;
   disableContainer?: boolean;
 }
 
@@ -26,10 +21,11 @@ const {
   backgrounds,
   disableContainer,
   class: originalClass,
+  ...rest
 } = Astro.props;
 ---
 
-<footer class:list={["footer-block relative", className, originalClass]}>
+<footer class:list={["footer-block relative", className, originalClass]} {...rest}>
   <BackgroundGroup backgrounds={backgrounds} />
   {
     disableContainer ? (

package/components/{HeaderShell.astro → BaseHeader.astro}

@@ -1,8 +1,6 @@
 ---
-import type {
-  AnimationConfig,
-  BackgroundConfig,
-} from "@rxdrag/website-lib-core";
+import type { HTMLAttributes } from "astro/types";
+import type { BackgroundConfig } from "@rxdrag/website-lib-core";
 import BackgroundGroup from "./BackgroundGroup.astro";
 import Container from "./Container.astro";
 
@@ -10,13 +8,11 @@ import Container from "./Container.astro";
  * 区块
  */
 
-interface Props {
-  class?: string;
+interface Props extends HTMLAttributes<'header'> {
   className?: string;
   containerClassName?: string;
   backgrounds?: BackgroundConfig[];
   //动效
-  animation?: AnimationConfig;
   disableContainer?: boolean;
 }
 
@@ -26,10 +22,12 @@ const {
   backgrounds,
   disableContainer,
   class: originalClass,
+  ...rest
 } = Astro.props;
----
 
-<header class:list={["header-block", className, originalClass]}>
+---
+ 
+<header class:list={["header-block", className, originalClass]} {...rest}>
   <BackgroundGroup backgrounds={backgrounds} />
   {
     disableContainer ? (

package/components/Box.astro

@@ -1,25 +1,22 @@
 ---
-import type {
-  AnimationConfig,
-  BackgroundConfig,
-} from "@rxdrag/website-lib-core";
-import BackgroundGroup from "./BackgroundGroup.astro";
+import type { BackgroundConfig } from "@rxdrag/website-lib-core";
+import BaseBlock from "./BaseBlock.astro";
 
 interface Props {
   class?: string;
   className?: string;
   backgrounds?: BackgroundConfig[];
-  //动效
-  animation?: AnimationConfig;
 }
 
 const { className, class: originalClass, backgrounds, ...rest } = Astro.props;
 ---
 
-<div
-  class:list={["w-full, h-full flex flex-col", className, originalClass]}
+<BaseBlock
+  baseClass={["w-full", "h-full", "flex", "flex-col"]}
+  className={className}
+  class={originalClass}
+  backgrounds={backgrounds}
   {...rest}
 >
-  <BackgroundGroup backgrounds={backgrounds} />
   <slot />
-</div>
+</BaseBlock>

package/components/Container.astro

@@ -1,13 +1,28 @@
 ---
-interface Props {
+import type { HTMLAttributes } from "astro/types";
+import BaseBlock from "./BaseBlock.astro";
+
+/**
+ * 容器
+ *
+ * 规范：被冻结（Frozen）的设计器原子组件
+ * - 对外接口与 DOM 结构应保持稳定，不随业务随意增删/调整
+ * - 允许通过原生属性透传（...rest）注入 id/style/data-*（如 data-aos-*）等通用能力
+ */
+
+interface Props extends HTMLAttributes<"div"> {
   //布局
   className?: string;
-  class?: string;
 }
 
 const { className, class: classAttr, ...rest } = Astro.props;
 ---
 
-<div class:list={["section-container", className, classAttr]} {...rest}>
+<BaseBlock
+  baseClass="section-container"
+  className={className}
+  class={classAttr}
+  {...rest}
+>
   <slot />
-</div>
+</BaseBlock>

package/components/Document.astro

@@ -0,0 +1,110 @@
+---
+import { PageType, type PageMeta } from "@rxdrag/rxcms-models";
+import type { Locals } from "@rxdrag/website-lib-core";
+import Meta from "@rxdrag/website-lib/components/Meta.astro";
+import { Entify } from "@rxdrag/website-lib-core";
+
+const { env, imageSizes } = Astro.locals as Locals;
+
+const rx = Entify.getInstance(env, imageSizes);
+
+// 文档壳：只负责 <html>/<head>/<body> 结构，不包含 Header/Footer 等站点布局。
+interface Props {
+  // html 的 lang 属性
+  lang?: string;
+  // SEO Meta（由上层 Layout/页面传入）
+  meta?: PageMeta;
+  // 页面标题（由 Meta 组件消费）
+  title?: string;
+  // 兼容 class / className 两种写法，最终合并到 body 上
+  class?: string;
+  className?: string;
+}
+
+const {
+  lang = "en",
+  meta,
+  title,
+  class: className = "scroll-smooth",
+  className: className2,
+  // 其余 props 透传到 body（例如 data-* 属性等）
+  ...rest
+} = Astro.props;
+
+//TODO: 添加meta获取逻辑，有可能需要重构后端数据结构，现在看来，只有动态内容需要获取meta，其它页面可以传入
+
+let resolvedMeta: PageMeta | undefined = meta;
+let resolvedTitle: string | undefined = title;
+
+// 仅在未传入 meta/title 时，针对动态详情页兜底拉取
+if (!resolvedMeta || !resolvedTitle) {
+  try {
+    const pathname = Astro.url?.pathname || "";
+    const slug = typeof Astro.params?.slug === "string" ? Astro.params.slug : undefined;
+
+    if (slug && pathname.startsWith("/posts/categories/")) {
+      const category = await rx.getPostCategoryBySlug(slug);
+      const page = await rx.getPageByType(PageType.PostList);
+      resolvedTitle = resolvedTitle ?? category?.name ?? "Blog";
+      resolvedMeta = resolvedMeta ?? page?.meta;
+    } else if (slug && pathname.startsWith("/products/categories/")) {
+      const category = await rx.getProductCategoryBySlug(slug);
+      const page = await rx.getPageByType(PageType.ProductList);
+      resolvedTitle = resolvedTitle ?? category?.name ?? "Products";
+      resolvedMeta = resolvedMeta ?? page?.meta;
+    } else if (slug && pathname.startsWith("/posts/")) {
+      const post = await rx.getPostBySlug(slug, { width: 1200, height: 600 });
+      resolvedTitle = resolvedTitle ?? post?.title;
+      resolvedMeta = resolvedMeta ?? post?.meta;
+    } else if (slug && pathname.startsWith("/products/")) {
+      const product = await rx.getProductBySlug(slug, { width: 800, height: 800 });
+      resolvedTitle = resolvedTitle ?? product?.title;
+      resolvedMeta = resolvedMeta ?? product?.meta;
+    }
+  } catch (e) {
+    console.log("[Document] resolve meta failed:", e);
+  }
+}
+---
+
+<!doctype html>
+<html lang={lang} class="aos-preload">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=5.0, minimum-scale=0.5, user-scalable=yes"
+    />
+
+    <meta name="generator" content={Astro.generator} />
+    <link rel="sitemap" href="/sitemap-index.xml" />
+    <link rel="icon" type="image/png" href="/favicon.png" />
+    <!-- 给上层 Layout/页面注入自定义 head 内容（预加载、脚本、样式等） -->
+    <slot name="head" />
+    <Meta title={resolvedTitle} content={resolvedMeta} />
+    <style>
+      html.aos-preload [data-aos] {
+        opacity: 1 !important;
+        transform: none !important;
+        transition: none !important;
+      }
+    </style>
+  </head>
+  <!-- rest 会被展开到 body 上，方便上层控制 data-* 等属性 -->
+  <body class:list={[className, className2]} {...rest}>
+    <slot />
+  </body>
+</html>
+
+<style>
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+  }
+
+  html {
+    scroll-behavior: smooth;
+  }
+</style>

package/components/Grid.astro

@@ -1,26 +1,34 @@
 ---
-import type {
-  AnimationConfig,
-  BackgroundConfig,
-} from "@rxdrag/website-lib-core";
-import BackgroundGroup from "./BackgroundGroup.astro";
+import type { HTMLAttributes } from "astro/types";
+import type { BackgroundConfig } from "@rxdrag/website-lib-core";
+import BaseBlock from "./BaseBlock.astro";
 
-interface Props {
-  //布局方案名称，设计qi'yong
+/**
+ * 网格
+ *
+ * 规范：被冻结（Frozen）的设计器原子组件
+ * - 对外接口与 DOM 结构应保持稳定，不随业务随意增删/调整
+ * - 允许通过原生属性透传（...rest）注入 id/style/data-*（如 data-aos-*）等通用能力
+ */
+
+interface Props extends HTMLAttributes<'div'> {
+  // 布局方案名称（设计器用）
   patternName?: string;
-  class?: string;
   className?: string;
   backgrounds?: BackgroundConfig[];
-  //动效
-  animation?: AnimationConfig;
 }
 
-const { className, class: originalClass, backgrounds } = Astro.props;
+const { className, class: originalClass, backgrounds, ...rest } = Astro.props;
 
 //布局容器
 ---
 
-<div class:list={["relative grid gap-12", className, originalClass]}>
-  <BackgroundGroup backgrounds={backgrounds} />
+<BaseBlock
+  baseClass="relative grid gap-12"
+  className={className}
+  class={originalClass}
+  backgrounds={backgrounds}
+  {...rest}
+>
   <slot />
-</div>
+</BaseBlock>

package/components/GridCell.astro

@@ -1,22 +1,32 @@
 ---
+import type { HTMLAttributes } from "astro/types";
 import type {
-  AnimationConfig,
   BackgroundConfig,
 } from "@rxdrag/website-lib-core";
-import BackgroundGroup from "./BackgroundGroup.astro";
+import BaseBlock from "./BaseBlock.astro";
 
-interface Props {
-  class?: string;
+/**
+ * 网格单元
+ *
+ * 规范：被冻结（Frozen）的设计器原子组件
+ * - 对外接口与 DOM 结构应保持稳定，不随业务随意增删/调整
+ * - 允许通过原生属性透传（...rest）注入 id/style/data-*（如 data-aos-*）等通用能力
+ */
+
+interface Props extends HTMLAttributes<'div'> {
   className?: string;
   backgrounds?: BackgroundConfig[];
-  //动效
-  animation?: AnimationConfig;
 }
 
-const { className, class: originalClass, backgrounds } = Astro.props;
+const { className, class: originalClass, backgrounds, ...rest } = Astro.props;
 ---
 
-<div class:list={["w-full h-full flex flex-col", className, originalClass]}>
-  <BackgroundGroup backgrounds={backgrounds} />
+<BaseBlock
+  baseClass={["w-full", "h-full", "flex", "flex-col"]}
+  className={className}
+  class={originalClass}
+  backgrounds={backgrounds}
+  {...rest}
+>
   <slot />
-</div>
+</BaseBlock>

package/components/Link.astro

@@ -3,18 +3,33 @@ import { toHref, type LinkType } from "@rxdrag/website-lib-core";
 
 import type { HTMLAttributes } from "astro/types";
 
+/**
+ * 链接
+ *
+ * 规范：被冻结（Frozen）的设计器原子组件
+ * - 对外接口与 DOM 结构应保持稳定，不随业务随意增删/调整
+ * - 允许通过原生属性透传（...rest）注入 id/style/data-* 等通用能力
+ * - 支持 className（自定义组件统一约定）
+ * - href 由 type/to/options 计算得出；不允许外部通过 props 覆盖（避免行为不稳定）
+ */
+
 interface Props extends HTMLAttributes<"a"> {
   type?: LinkType | string;
-  to?: string | undefined;
-  class?: string;
+  to?: string;
   className?: string;
   //用于active类名的传递
   activeWhen?: string | true;
 
+  // 链接生成配置：用于 toHref 计算最终 href 的路径前缀
+  // - productsSlug：产品详情页路径前缀（如 "products"）
+  // - postsSlug：文章详情页路径前缀（如 "posts"）
   options?: {
     productsSlug?: string;
     postsSlug?: string;
   };
+
+  // 允许外部传入以便兼容旧用法，但运行时会被忽略（href 统一由 type/to/options 生成）
+  href?: string;
 }
 
 const {
@@ -24,17 +39,31 @@ const {
   className,
   activeWhen,
   options,
+  href: hrefFromProps,
+  "class:list": classListFromProps,
   ...props
 } = Astro.props;
+
+if (hrefFromProps) {
+  console.log(
+    `[Link] prop "href" is ignored. Use type/to/options to generate href. href=${hrefFromProps}`
+  );
+}
+if (classListFromProps) {
+  console.log(
+    '[Link] prop "class:list" is ignored. Use class/className instead.'
+  );
+}
+
 const href = toHref(type || "", to || "", options);
 const hrefObj = href ? { href } : {};
 ---
 
 <a
-  data-actived-path={activeWhen}
+  {...props}
   {...hrefObj}
+  data-actived-path={activeWhen}
   class:list={[cls, className]}
-  {...props}
 >
   <slot />
 </a>

package/components/Picture.astro

@@ -0,0 +1,35 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+type PictureSource = {
+  srcset: string;
+  media?: string;
+  type?: string;
+  sizes?: string;
+};
+
+interface Props extends HTMLAttributes<"picture"> {
+  className?: string;
+  sources?: PictureSource[];
+  imgProps: Omit<HTMLAttributes<"img">, "src"> & {
+    src: string;
+  };
+}
+
+const {
+  className,
+  sources,
+  imgProps,
+  class: originalClass,
+  ...rest
+} = Astro.props;
+
+const sourceList = sources ?? [];
+---
+
+<picture class:list={["picture-block", className, originalClass]} {...rest}>
+  {sourceList.map((source) => (
+    <source {...source} />
+  ))}
+  <img {...imgProps} />
+</picture>

package/components/Section.astro

@@ -1,22 +1,22 @@
 ---
-import type {
-  AnimationConfig,
-  BackgroundConfig,
-} from "@rxdrag/website-lib-core";
+import type { HTMLAttributes } from "astro/types";
+import type { BackgroundConfig } from "@rxdrag/website-lib-core";
 import BackgroundGroup from "./BackgroundGroup.astro";
 import Container from "./Container.astro";
 
 /**
  * 区块
+ *
+ * 规范：被冻结（Frozen）的设计器原子组件
+ * - 对外接口与 DOM 结构应保持稳定，不随业务随意增删/调整
+ * - 允许通过原生属性透传（...rest）注入 id/style/data-*（如 data-aos-*）等通用能力
+ * - 默认包裹 Container 提供统一容器宽度；需要全宽内容时使用 disableContainer
  */
 
-interface Props {
-  class?: string;
+interface Props extends HTMLAttributes<'section'> {
   className?: string;
   containerClassName?: string;
   backgrounds?: BackgroundConfig[];
-  //动效
-  animation?: AnimationConfig;
   disableContainer?: boolean;
 }
 
@@ -26,10 +26,11 @@ const {
   backgrounds,
   disableContainer,
   class: originalClass,
+  ...rest
 } = Astro.props;
 ---
 
-<section class:list={["section-block", className, originalClass]}>
+<section class:list={["section-block", className, originalClass]} {...rest}>
   <BackgroundGroup backgrounds={backgrounds} />
   {
     disableContainer ? (

package/components/Stack.astro

@@ -0,0 +1,31 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import type { BackgroundConfig } from "@rxdrag/website-lib-core";
+import BaseBlock from "./BaseBlock.astro";
+
+/**
+ * 堆叠布局
+ *
+ * 规范：被冻结（Frozen）的设计器原子组件
+ * - 对外接口与 DOM 结构应保持稳定，不随业务随意增删/调整
+ * - 允许通过原生属性透传（...rest）注入 id/style/data-*（如 data-aos-*）等通用能力
+ * - 默认 mobile 为 vertical（flex-col）；响应式方向/间距/对齐通过 class / className（Tailwind）表达
+ */
+
+interface Props extends HTMLAttributes<'div'> {
+  className?: string;
+  backgrounds?: BackgroundConfig[];
+}
+
+const { className, class: classAttr, backgrounds, ...rest } = Astro.props;
+---
+
+<BaseBlock
+  baseClass={["flex", "flex-col"]}
+  className={className}
+  class={classAttr}
+  backgrounds={backgrounds}
+  {...rest}
+>
+  <slot />
+</BaseBlock>

package/components/Video.astro

@@ -7,8 +7,12 @@ import {
 const { env, imageSizes } = Astro.locals as Locals;
 
 interface Props {
+  //TODO 要删除
   videoRef?: string;
+  //TODO 要删除
   posterRef?: string;
+  src?: string;
+  poster?: string;
   endTitle?: string;
   eagerLoad?: boolean;
   classNames?: {
@@ -28,6 +32,8 @@ interface Props {
 const {
   videoRef,
   posterRef,
+  src,
+  poster,
   eagerLoad,
   endTitle = "Contact Us Now",
   classNames = {},
@@ -37,7 +43,7 @@ const rx = Entify.getInstance(env, imageSizes);
 
 // 获取媒体数据（增加 rx 为空时的保护）
 const media = rx ? await rx.getMedia(videoRef) : undefined;
-const poster = rx ? await rx.getMedia(posterRef) : undefined;
+const posterObj = rx ? await rx.getMedia(posterRef) : undefined;
 ---
 
 {
@@ -46,7 +52,7 @@ const poster = rx ? await rx.getMedia(posterRef) : undefined;
       client:load
       media={media}
       endTitle={endTitle}
-      posterUrl={poster?.file?.original}
+      posterUrl={posterObj?.file?.original}
       eagerLoad={eagerLoad}
       classNames={classNames}
     />