willa-workspace 0.0.3-alpha.2739b3e → 0.0.4

package/example/src/App.tsx

@@ -20,6 +20,7 @@ import { PageHeader } from "willa/PageHeader";
 import { Typography } from "willa/Typography";
 import { SearchInput } from "willa/SearchInput";
 import { Skeleton } from "willa/Skeleton";
+import { WillaShell } from "willa/WillaShell";
 import "willa/AppShell.css";
 import "willa/Anchor.css";
 import "willa/Callout.css";
@@ -29,6 +30,7 @@ import "willa/PageHeader.css";
 import "willa/SearchInput.css";
 import "willa/Skeleton.css";
 import "willa/Typography.css";
+import "willa/WillaShell.css";
 
 import {
   componentDocRegistry,
@@ -190,6 +192,7 @@ const docChineseNames: Record<string, string> = {
   VideoLink: "视频链接",
   Watermark: "水印",
   WebEmbed: "网页嵌入",
+  WillaShell: "Willa 作用域",
   XPostEmbed: "X 内容嵌入",
 };
 
@@ -292,6 +295,7 @@ export function App() {
   const [isDocLoading, setIsDocLoading] = useState(false);
   const [docError, setDocError] = useState<string | null>(null);
   const [sidebarQuery, setSidebarQuery] = useState(getInitialSidebarQuery);
+  const [isCompactSidebar, setIsCompactSidebar] = useState(getIsCompactSidebar);
   const [expandedDocGroups, setExpandedDocGroups] = useState(() =>
     getDefaultExpandedDocGroups(!getIsCompactSidebar()),
   );
@@ -318,6 +322,12 @@ export function App() {
     (count, group) => count + group.docs.length,
     0,
   );
+  const backToTopFloatButtonProps = isCompactSidebar
+    ? {
+        hoverTextColor: "var(--willa-text-strong)",
+        variant: "ghost" as const,
+      }
+    : {};
 
   const startAnchorItems: Array<AnchorItem> = [
     {
@@ -387,7 +397,7 @@ export function App() {
   );
 
   const sidebar = (
-    <div className="docs-sidebar willa-shell">
+    <div className="docs-sidebar">
       <div className="docs-sidebar-top">
         <a className="docs-brand" href={`#/${usagePageId}`}>
           <span className="docs-brand-mark">W</span>
@@ -496,9 +506,11 @@ export function App() {
   useEffect(() => {
     const media = window.matchMedia(sidebarCompactQuery);
     const updateExpandedGroups = () => {
+      setIsCompactSidebar(media.matches);
       setExpandedDocGroups(getDefaultExpandedDocGroups(!media.matches));
     };
 
+    updateExpandedGroups();
     media.addEventListener("change", updateExpandedGroups);
 
     return () => {
@@ -570,7 +582,7 @@ export function App() {
   }, [activeEntry]);
 
   return (
-    <>
+    <WillaShell>
       <AppShell className="docs-app" sidebar={sidebar} sidebarWidth="324px">
         <div className="docs-main" ref={docsMainRef}>
           <PageHeader
@@ -580,7 +592,7 @@ export function App() {
             actions={renderDocsActions("docs-actions docs-header-actions")}
           />
 
-          <div className="docs-content willa-shell">
+          <div className="docs-content">
             {activeId === usagePageId ? (
               <UsageGuide />
             ) : loadedDoc ? (
@@ -607,7 +619,12 @@ export function App() {
           </div>
         </div>
       </AppShell>
-      <FloatButton backToTop ariaLabel="回到顶部" tooltip="回到顶部" />
-    </>
+      <FloatButton
+        backToTop
+        ariaLabel="回到顶部"
+        tooltip="回到顶部"
+        {...backToTopFloatButtonProps}
+      />
+    </WillaShell>
   );
 }

package/example/src/catalog/defineDoc.tsx

@@ -170,6 +170,7 @@ const willaDemoImportNames = new Set([
   "VideoLink",
   "Watermark",
   "WebEmbed",
+  "WillaShell",
   "XPostEmbed",
 ]);
 

package/example/src/catalog/registry.ts

@@ -91,6 +91,7 @@ const docSpecGroups = {
     "SidebarLayout",
     "SplitPane",
     "Stack",
+    "WillaShell",
   ],
   content: [
     "Alert",

package/example/src/docs/Anchor.demo.tsx

@@ -187,6 +187,12 @@ export default defineDoc({
       type: "Partial<Record<AnchorSlot, string>>",
       description: "按语义槽位追加 className，用于定制局部样式。",
     },
+    {
+      name: "renderLink",
+      type: "(props: WillaRenderLinkProps) => ReactNode",
+      description:
+        "自定义目录项链接渲染，可接入客户端路由；未传时渲染原生 a 标签。",
+    },
     {
       name: "styles",
       type: "Partial<Record<AnchorSlot, CSSProperties>>",

package/example/src/docs/Breadcrumb.demo.tsx

@@ -141,6 +141,12 @@ export default defineDoc({
       defaultValue: "<ChevronRightIcon />",
       description: "分隔符，默认使用箭头图标。",
     },
+    {
+      name: "renderLink",
+      type: "(props: WillaRenderLinkProps) => ReactNode",
+      description:
+        "自定义非当前项链接渲染，可接入客户端路由；未传时渲染原生 a 标签。",
+    },
     {
       name: "BreadcrumbItem.label",
       type: "ReactNode",

package/example/src/docs/Button.demo.tsx

@@ -226,6 +226,12 @@ export default defineDoc({
       type: "string",
       description: "传入后渲染为链接按钮。",
     },
+    {
+      name: "renderLink",
+      type: "(props: WillaRenderLinkProps) => ReactNode",
+      description:
+        "自定义链接渲染。传入 href 时可接入客户端路由，未传时渲染原生 a 标签；disabled 或 loading 时不会调用。",
+    },
     {
       name: "icon",
       type: "ReactNode",

package/example/src/docs/FloatButton.demo.tsx

@@ -64,6 +64,8 @@ const BackToTopPreview = () => {
       </Stack>
       <FloatButton
         backToTop
+        variant="ghost"
+        hoverTextColor="var(--willa-text-strong)"
         target={() => document.querySelector("[data-float-button-scroll]")}
       />
     </div>
@@ -214,7 +216,9 @@ const CustomColorPreview = () => {
         label="上线中心"
         description="查看待发布项"
         backgroundColor="#1f2937"
+        hoverBackgroundColor="#111827"
         textColor="#f8fafc"
+        hoverTextColor="#ffffff"
         badge="2"
       />
     </div>
@@ -452,7 +456,9 @@ export default defineDoc({
             label="上线中心"
             description="查看待发布项"
             backgroundColor="#1f2937"
+            hoverBackgroundColor="#111827"
             textColor="#f8fafc"
+            hoverTextColor="#ffffff"
             badge="2"
           />
         </div>;
@@ -498,6 +504,8 @@ export default defineDoc({
           <FloatButton
             icon={<ArrowUpIcon />}
             backToTop
+            variant="ghost"
+            hoverTextColor="var(--willa-text-strong)"
             target={() => document.querySelector("[data-float-button-scroll]")}
           />
         </div>;
@@ -536,22 +544,33 @@ export default defineDoc({
       type: "string",
       description: "自定义按钮背景色。",
     },
+    {
+      name: "hoverBackgroundColor",
+      type: "string",
+      description: "自定义 hover 状态背景色。ghost 未传时保持透明。",
+    },
     {
       name: "textColor",
       type: "string",
       description: "自定义按钮文字和图标颜色。",
     },
+    {
+      name: "hoverTextColor",
+      type: "string",
+      description: "自定义 hover 状态文字和图标颜色。",
+    },
     {
       name: "variant",
-      type: '"default" | "primary"',
+      type: '"default" | "primary" | "ghost"',
       defaultValue: '"default"',
-      description: "视觉变体。",
+      description: "视觉变体。ghost 会隐藏背景、边框和阴影，只保留内容。",
     },
     {
       name: "shape",
       type: '"circle" | "square"',
-      defaultValue: "内容按钮自动推导",
-      description: "按钮形状。未传时会根据是否有文字自动推导。",
+      defaultValue: "backToTop 为圆形，否则为方形",
+      description:
+        "按钮形状。未传时普通悬浮按钮使用方形，回到顶部按钮使用圆形。",
     },
     {
       name: "size",

package/example/src/docs/Lightbox.demo.tsx

@@ -69,7 +69,8 @@ export default defineDoc({
   id: "lightbox",
   name: "Lightbox",
   packageName: "willa/Lightbox",
-  description: "占满视口的图片预览弹层。",
+  description:
+    "占满视口的图片预览弹层，打开时会锁定页面滚动，并支持 Escape 关闭和左右方向键切换。",
   imports: [
     { name: "Button", from: "willa/Button" },
     { name: "Image", from: "willa/Image" },
@@ -152,17 +153,20 @@ export default defineDoc({
     {
       name: "onClose",
       type: "() => void",
-      description: "受控模式下弹层需要关闭时触发。",
+      description:
+        "受控模式下弹层需要关闭时触发；点击背景、点击图片或按 Escape 都会调用。",
     },
     {
       name: "onPrev",
       type: "() => void",
-      description: "可选的上一张图片操作。",
+      description:
+        "可选的上一张图片操作；传入后左侧按钮和 ArrowLeft 都会调用。",
     },
     {
       name: "onNext",
       type: "() => void",
-      description: "可选的下一张图片操作。",
+      description:
+        "可选的下一张图片操作；传入后右侧按钮和 ArrowRight 都会调用。",
     },
     {
       name: "backdrop",

package/example/src/docs/List.demo.tsx

@@ -912,6 +912,12 @@ export default defineDoc({
       type: "(item: ListItem) => ReactNode",
       description: "完全自定义单条渲染。",
     },
+    {
+      name: "renderLink",
+      type: "(props: WillaRenderLinkProps) => ReactNode",
+      description:
+        "自定义条目链接渲染，可接入客户端路由；仅在条目有 href 且未禁用时调用。",
+    },
     {
       name: "onItemsChange",
       type: "(items: Array<ListItem>) => void",
@@ -1000,6 +1006,12 @@ export default defineDoc({
       type: "HTMLAnchorElement['target']",
       description: "链接打开方式。",
     },
+    {
+      name: "ListItem.rel",
+      type: "HTMLAnchorElement['rel']",
+      description:
+        "链接 rel 属性；target 为 _blank 且未传 rel 时默认使用 noreferrer。",
+    },
     {
       name: "virtualScrollItemHeight",
       type: "number",

package/example/src/docs/Mdx.demo.tsx

@@ -1,7 +1,7 @@
 import { unindent } from "aidly";
-import { useState, type ElementType } from "react";
+import { useState, type ComponentProps, type ElementType } from "react";
 import { Lightbox } from "willa/Lightbox";
-import { Mdx } from "willa/Mdx";
+import { Mdx, type MdxComponents } from "willa/Mdx";
 
 import "willa/Mdx.css";
 
@@ -30,6 +30,28 @@ const galleryImages = [
 const resolveDemoAssetUrl = (_articleSourcePath: string, assetPath: string) =>
   assetPath;
 
+const ArticleLink = (props: ComponentProps<"a">) => {
+  const { children, style, ...rest } = props;
+
+  return (
+    <a
+      {...rest}
+      style={{
+        color: "var(--willa-color-blue)",
+        fontWeight: 720,
+        textUnderlineOffset: "0.18em",
+        ...style,
+      }}
+    >
+      {children}
+    </a>
+  );
+};
+
+const mdxComponents = {
+  a: ArticleLink,
+} satisfies MdxComponents;
+
 const DemoMdxContent = (props: Record<string, unknown>) => {
   const components = (props.components ?? {}) as Record<string, ElementType>;
   const H1 = components.h1 ?? "h1";
@@ -258,6 +280,7 @@ const MdxPreview = () => {
         articleSourcePath="/posts/demo.mdx"
         resolveAssetUrl={resolveDemoAssetUrl}
         openLightbox={setLightbox}
+        components={mdxComponents}
       />
       {lightbox?.selectedImage ? (
         <Lightbox
@@ -282,12 +305,25 @@ export default defineDoc({
     component: MdxPreview,
   },
   code: unindent(`
-    import { Mdx } from "willa/Mdx";
+    import { Mdx, type MdxComponents } from "willa/Mdx";
     import "willa/Mdx.css";
 
     const resolveAssetUrl = (_articleSourcePath: string, assetPath: string) =>
       assetPath;
 
+    const mdxComponents = {
+      a: ({ href, children, ...props }) =>
+        href?.startsWith("https://") ? (
+          <a href={href} target="_blank" rel="noreferrer" {...props}>
+            {children}
+          </a>
+        ) : (
+          <a href={href} {...props}>
+            {children}
+          </a>
+        ),
+    } satisfies MdxComponents;
+
     function DemoMdxContent(props) {
       const {
         h1: H1 = "h1",
@@ -313,6 +349,7 @@ export default defineDoc({
       Content={DemoMdxContent}
       articleSourcePath="/posts/demo.mdx"
       resolveAssetUrl={resolveAssetUrl}
+      components={mdxComponents}
     />;
   `),
   props: [
@@ -334,6 +371,12 @@ export default defineDoc({
       required: true,
       description: "把 MDX 中的相对资源转换为可访问 URL。",
     },
+    {
+      name: "components",
+      type: "MdxComponents",
+      description:
+        "覆盖内置 MDX 组件映射。可接管链接、标题、图片或自定义组件策略，未覆盖的项继续使用 Willa 默认映射。",
+    },
     {
       name: "openLightbox",
       type: "(state: LightboxState | null) => void",

package/example/src/docs/Pagination.demo.tsx

@@ -219,6 +219,12 @@ export default defineDoc({
       description:
         "返回页码链接地址；适合文章列表、搜索结果等需要真实 URL 的分页。",
     },
+    {
+      name: "renderLink",
+      type: "(props: WillaRenderLinkProps) => ReactNode",
+      description:
+        "自定义页码链接渲染，可接入客户端路由；仅在 getPageHref 返回地址且页码可点击时调用。",
+    },
     {
       name: "getEllipsisPage",
       type: "(context: PaginationEllipsisContext) => number",

package/example/src/docs/SiteNav.demo.tsx

@@ -12,6 +12,17 @@ const navItems: Array<SiteNavItem> = [
   { label: "价格", href: "#pricing" },
 ];
 
+const routeNavItems: Array<SiteNavItem> = [
+  { label: "组件", href: "/components", active: true },
+  { label: "文档", href: "/docs" },
+  {
+    label: "GitHub",
+    href: "https://github.com/imtaotao/willa",
+    target: "_blank",
+    rel: "noreferrer",
+  },
+];
+
 export default defineDoc({
   id: "site-nav",
   name: "SiteNav",
@@ -91,6 +102,54 @@ export default defineDoc({
         />
       ),
     },
+    {
+      title: "路由链接",
+      code: `
+        import { Link } from "react-router-dom";
+        import { SiteNav, type SiteNavItem } from "willa/SiteNav";
+        import "willa/SiteNav.css";
+
+        const items: Array<SiteNavItem> = [
+          { label: "组件", href: "/components", active: true },
+          { label: "文档", href: "/docs" },
+          {
+            label: "GitHub",
+            href: "https://github.com/imtaotao/willa",
+            target: "_blank",
+            rel: "noreferrer",
+          },
+        ];
+
+        <SiteNav
+          brand="Willa"
+          brandHref="/"
+          items={items}
+          renderLink={({ href, children, ...props }) =>
+            href.startsWith("http") ? (
+              <a href={href} {...props}>
+                {children}
+              </a>
+            ) : (
+              <Link to={href} {...props}>
+                {children}
+              </Link>
+            )
+          }
+        />;
+      `,
+      content: (
+        <SiteNav
+          brand="Willa"
+          brandHref="/"
+          items={routeNavItems}
+          renderLink={({ href, children, ...props }) => (
+            <a href={href} {...props}>
+              {children}
+            </a>
+          )}
+        />
+      ),
+    },
   ],
   props: [
     {
@@ -126,6 +185,12 @@ export default defineDoc({
       defaultValue: "false",
       description: "是否吸附在页面顶部。",
     },
+    {
+      name: "renderLink",
+      type: "(props: WillaRenderLinkProps) => ReactNode",
+      description:
+        "自定义品牌和导航项链接渲染，可接入客户端路由；未传时渲染原生 a 标签。",
+    },
     {
       name: "SiteNavItem.label",
       type: "ReactNode",

package/example/src/docs/WillaShell.demo.tsx

@@ -0,0 +1,88 @@
+import { WillaShell } from "willa/WillaShell";
+import "willa/WillaShell.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const shellStyle = {
+  border: "1px solid var(--willa-border)",
+  borderRadius: "0.75rem",
+  padding: "1rem",
+  background: "var(--willa-surface)",
+} as const;
+
+export default defineDoc({
+  id: "willa-shell",
+  name: "WillaShell",
+  displayName: "Willa 作用域",
+  category: "layout",
+  packageName: "willa/WillaShell",
+  description: "为 Willa 组件提供统一的 .willa-shell 作用域和基础文本样式。",
+  imports: [{ name: "WillaShell", from: "willa/WillaShell" }],
+  css: "willa/WillaShell.css",
+  demo: {
+    name: "WillaShell",
+    component: WillaShell,
+    props: { style: shellStyle },
+    children: "页面或应用根节点可以包裹在 WillaShell 内。",
+  },
+  code: `
+    import { WillaShell } from "willa/WillaShell";
+    import "willa/WillaShell.css";
+
+    <WillaShell>
+      页面或应用根节点可以包裹在 WillaShell 内。
+    </WillaShell>;
+  `,
+  sections: [
+    {
+      title: "自定义根元素",
+      code: `
+        <WillaShell
+          as="main"
+          style={{
+            border: "1px solid var(--willa-border)",
+            borderRadius: "0.75rem",
+            padding: "1rem",
+            background: "var(--willa-surface)",
+          }}
+        >
+          <strong>文档页面</strong>
+          <p style={{ color: "var(--willa-text-soft)", margin: "0.5rem 0 0" }}>
+            WillaShell 会保留传入的根元素属性，并追加 willa-shell className。
+          </p>
+        </WillaShell>;
+      `,
+      content: (
+        <WillaShell as="main" style={shellStyle}>
+          <strong>文档页面</strong>
+          <p
+            style={{
+              color: "var(--willa-text-soft)",
+              margin: "0.5rem 0 0",
+            }}
+          >
+            WillaShell 会保留传入的根元素属性，并追加 willa-shell className。
+          </p>
+        </WillaShell>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "需要获得 Willa 作用域的页面或局部内容。",
+    },
+    {
+      name: "as",
+      type: "ElementType",
+      defaultValue: '"div"',
+      description: "自定义渲染标签或组件。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "追加到根节点的 className，会和 willa-shell 合并。",
+    },
+  ],
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willa-workspace",
-  "version": "0.0.3-alpha.2739b3e",
+  "version": "0.0.4",
   "type": "module",
   "license": "MIT",
   "author": "chentao.arthur",

package/packages/willa/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willa",
-  "version": "0.0.3-alpha.2739b3e",
+  "version": "0.0.4",
   "description": "Willa UI component library.",
   "author": "chentao.arthur",
   "license": "MIT",

package/packages/willa/src/Mdx/index.tsx

@@ -1 +1,5 @@
-export { Mdx, type MdxProps } from "@willa-ui/widgets/components/Mdx";
+export {
+  Mdx,
+  type MdxComponents,
+  type MdxProps,
+} from "@willa-ui/widgets/components/Mdx";

package/packages/willa/src/WillaShell/index.tsx

@@ -0,0 +1,2 @@
+export { WillaShell } from "@willa-ui/layout/components/WillaShell";
+export type { WillaShellProps } from "@willa-ui/layout/components/WillaShell";

package/packages/willa-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willa-ui/ai",
-  "version": "0.0.3-alpha.2739b3e",
+  "version": "0.0.4",
   "description": "Willa UI AI product components.",
   "author": "chentao.arthur",
   "license": "MIT",

package/packages/willa-content/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willa-ui/content",
-  "version": "0.0.3-alpha.2739b3e",
+  "version": "0.0.4",
   "description": "Willa UI content components.",
   "author": "chentao.arthur",
   "license": "MIT",