willa-workspace 0.0.3-alpha.2739b3e

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

@@ -0,0 +1,342 @@
+import { Avatar } from "willa/Avatar";
+import "willa/Avatar.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const avatarRowStyle = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "0.75rem",
+  alignItems: "center",
+} as const;
+
+const profileCardStyle = {
+  display: "grid",
+  minWidth: "12rem",
+  gap: "0.35rem",
+} as const;
+
+const profileNameStyle = {
+  color: "var(--willa-text-strong)",
+  fontSize: "0.92rem",
+  fontWeight: 600,
+  lineHeight: 1.3,
+} as const;
+
+const profileMetaStyle = {
+  color: "var(--willa-text-soft)",
+  fontSize: "0.82rem",
+  lineHeight: 1.45,
+} as const;
+
+const profileStatStyle = {
+  display: "flex",
+  gap: "0.5rem",
+  color: "var(--willa-text-faint)",
+  fontSize: "0.78rem",
+} as const;
+
+export default defineDoc({
+  id: "avatar",
+  name: "Avatar",
+  packageName: "willa/Avatar",
+  description: "用于作者、评论、社区内容和引用来源中的头像展示。",
+  imports: [{ name: "Avatar", from: "willa/Avatar" }],
+  css: "willa/Avatar.css",
+  demo: {
+    name: "Avatar",
+    component: Avatar,
+    props: {
+      src: "https://github.com/imtaotao.png",
+      name: "Tao Tao",
+      alt: "Tao Tao",
+      previewable: true,
+    },
+  },
+  code: `
+    import { Avatar } from "willa/Avatar";
+    import "willa/Avatar.css";
+
+    <Avatar
+      src="https://github.com/imtaotao.png"
+      name="Tao Tao"
+      alt="Tao Tao"
+      previewable
+    />;
+  `,
+  sections: [
+    {
+      title: "悬浮信息",
+      code: `
+        <div style={avatarRowStyle}>
+          <Avatar
+            src="https://github.com/imtaotao.png"
+            name="Tao Tao"
+            alt="Tao Tao"
+            hoverCard={
+              <div style={profileCardStyle}>
+                <strong style={profileNameStyle}>Tao Tao</strong>
+                <span style={profileMetaStyle}>
+                  Willa 组件库维护者，关注内容平台和文档体验。
+                </span>
+                <span style={profileStatStyle}>
+                  <span>128 篇文章</span>
+                  <span>4.8k 关注</span>
+                </span>
+              </div>
+            }
+          />
+        </div>;
+      `,
+      content: (
+        <div style={avatarRowStyle}>
+          <Avatar
+            src="https://github.com/imtaotao.png"
+            name="Tao Tao"
+            alt="Tao Tao"
+            hoverCard={
+              <div style={profileCardStyle}>
+                <strong style={profileNameStyle}>Tao Tao</strong>
+                <span style={profileMetaStyle}>
+                  Willa 组件库维护者，关注内容平台和文档体验。
+                </span>
+                <span style={profileStatStyle}>
+                  <span>128 篇文章</span>
+                  <span>4.8k 关注</span>
+                </span>
+              </div>
+            }
+          />
+        </div>
+      ),
+    },
+    {
+      title: "点击预览和跳转",
+      code: `
+        <div style={avatarRowStyle}>
+          <Avatar
+            src="https://github.com/imtaotao.png"
+            name="Tao Tao"
+            alt="点击预览头像"
+            previewable
+          />
+          <Avatar
+            src="https://github.com/github.png"
+            name="GitHub"
+            alt="打开 GitHub"
+            href="https://github.com"
+            target="_blank"
+          />
+          <Avatar name="Hover Only" hoverable />
+        </div>;
+      `,
+      content: (
+        <div style={avatarRowStyle}>
+          <Avatar
+            src="https://github.com/imtaotao.png"
+            name="Tao Tao"
+            alt="点击预览头像"
+            previewable
+          />
+          <Avatar
+            src="https://github.com/github.png"
+            name="GitHub"
+            alt="打开 GitHub"
+            href="https://github.com"
+            target="_blank"
+          />
+          <Avatar name="Hover Only" hoverable />
+        </div>
+      ),
+    },
+    {
+      title: "图片和文本",
+      code: `
+        <div style={avatarRowStyle}>
+          <Avatar src="https://github.com/imtaotao.png" name="Tao Tao" alt="Tao Tao" />
+          <Avatar name="Willa UI" />
+          <Avatar name="Content Author" alt="文档作者" />
+          <Avatar src="https://example.invalid/avatar.png" name="Broken Image" />
+        </div>;
+      `,
+      content: (
+        <div style={avatarRowStyle}>
+          <Avatar
+            src="https://github.com/imtaotao.png"
+            name="Tao Tao"
+            alt="Tao Tao"
+          />
+          <Avatar name="Willa UI" />
+          <Avatar name="Content Author" alt="文档作者" />
+          <Avatar
+            src="https://example.invalid/avatar.png"
+            name="Broken Image"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "尺寸",
+      code: `
+        <div style={avatarRowStyle}>
+          <Avatar name="Small" size="sm" />
+          <Avatar name="Medium" size="md" />
+          <Avatar name="Large" size="lg" />
+          <Avatar name="Extra Large" size="xl" />
+        </div>;
+      `,
+      content: (
+        <div style={avatarRowStyle}>
+          <Avatar name="Small" size="sm" />
+          <Avatar name="Medium" size="md" />
+          <Avatar name="Large" size="lg" />
+          <Avatar name="Extra Large" size="xl" />
+        </div>
+      ),
+    },
+    {
+      title: "形状",
+      code: `
+        <div style={avatarRowStyle}>
+          <Avatar name="Circle" shape="circle" />
+          <Avatar name="Rounded" shape="rounded" />
+          <Avatar name="Square" shape="square" />
+        </div>;
+      `,
+      content: (
+        <div style={avatarRowStyle}>
+          <Avatar name="Circle" shape="circle" />
+          <Avatar name="Rounded" shape="rounded" />
+          <Avatar name="Square" shape="square" />
+        </div>
+      ),
+    },
+    {
+      title: "自定义颜色",
+      code: `
+        <div style={avatarRowStyle}>
+          <Avatar backgroundColor="#f6e7c8" name="Warm Author" textColor="#3f2a12" />
+          <Avatar backgroundColor="rgba(96, 165, 250, 0.14)" name="Blue Writer" />
+        </div>;
+      `,
+      content: (
+        <div style={avatarRowStyle}>
+          <Avatar
+            backgroundColor="#f6e7c8"
+            name="Warm Author"
+            textColor="#3f2a12"
+          />
+          <Avatar
+            backgroundColor="rgba(96, 165, 250, 0.14)"
+            name="Blue Writer"
+          />
+        </div>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "src",
+      type: "string",
+      description: "头像图片地址。",
+    },
+    {
+      name: "alt",
+      type: "string",
+      description: "图片头像的替代文本；未传时使用 name。",
+    },
+    {
+      name: "name",
+      type: "string",
+      required: true,
+      description:
+        "头像名称，必填；图片缺失或加载失败时取后两个单词首字母展示。",
+    },
+    {
+      name: "previewable",
+      type: "boolean",
+      defaultValue: "false",
+      description: "启用点击放大预览。",
+    },
+    {
+      name: "previewSrc",
+      type: "string",
+      description: "预览时使用的图片地址，未传时复用 src。",
+    },
+    {
+      name: "hoverCard",
+      type: "ReactNode",
+      description: "头像 hover 或键盘聚焦时展示的自定义弹框内容。",
+    },
+    {
+      name: "hoverCardClassName",
+      type: "string",
+      description: "传给 hover 弹框容器的类名。",
+    },
+    {
+      name: "href",
+      type: "string",
+      description:
+        "传入后渲染为可跳转链接；与 previewable 同时传入时优先预览。",
+    },
+    {
+      name: "hoverable",
+      type: "boolean",
+      defaultValue: "false",
+      description: "仅启用 hover 交互状态，不改变点击行为。",
+    },
+    {
+      name: "size",
+      type: '"sm" | "md" | "lg" | "xl"',
+      defaultValue: '"md"',
+      description: "头像尺寸。",
+    },
+    {
+      name: "shape",
+      type: '"circle" | "rounded" | "square"',
+      defaultValue: '"circle"',
+      description: "头像外形。",
+    },
+    {
+      name: "imageProps",
+      type: "ImgHTMLAttributes<HTMLImageElement>",
+      description:
+        "透传给内部图片的属性，不包含 src、alt、className 和 children。",
+    },
+    {
+      name: "backgroundColor",
+      type: "string",
+      description: "自定义文字头像背景颜色，支持 CSS 颜色值。",
+    },
+    {
+      name: "textColor",
+      type: "string",
+      description: "自定义文字头像颜色，支持 CSS 颜色值。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "自定义 className。",
+    },
+    {
+      name: "closeLabel",
+      type: "string",
+      description: "文案标签。",
+    },
+    {
+      name: "previewLabel",
+      type: "string",
+      description: "文案标签。",
+    },
+    {
+      name: "rel",
+      type: "string",
+      description: "链接关系属性。",
+    },
+    {
+      name: "target",
+      type: "string",
+      description: "链接打开方式。",
+    },
+  ],
+});

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

@@ -0,0 +1,196 @@
+import {
+  CheckCircledIcon,
+  ClockIcon,
+  ExclamationTriangleIcon,
+  RocketIcon,
+} from "@radix-ui/react-icons";
+import { Badge } from "willa/Badge";
+import { Group } from "willa/Group";
+import "willa/Badge.css";
+import "willa/Group.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+export default defineDoc({
+  id: "badge",
+  name: "Badge",
+  packageName: "willa/Badge",
+  description: "用于文章、文档和 MDX 内容中的分类、版本、状态和轻量标记。",
+  imports: [
+    { name: "Badge", from: "willa/Badge" },
+    { name: "Group", from: "willa/Group" },
+  ],
+  css: "willa/Badge.css",
+  demo: {
+    name: "Badge",
+    component: Badge,
+    props: {
+      tone: "info",
+      icon: <RocketIcon />,
+    },
+    children: "新功能",
+  },
+  code: `
+    import { RocketIcon } from "@radix-ui/react-icons";
+    import { Badge } from "willa/Badge";
+    import "willa/Badge.css";
+
+    <Badge tone="info" icon={<RocketIcon />}>
+      新功能
+    </Badge>;
+  `,
+  sections: [
+    {
+      title: "语义类型",
+      code: `
+        <Group gap="sm">
+          <Badge>默认</Badge>
+          <Badge tone="info">文档</Badge>
+          <Badge tone="success">已发布</Badge>
+          <Badge tone="warning">实验性</Badge>
+          <Badge tone="danger">已废弃</Badge>
+        </Group>;
+      `,
+      content: (
+        <Group gap="sm">
+          <Badge>默认</Badge>
+          <Badge tone="info">文档</Badge>
+          <Badge tone="success">已发布</Badge>
+          <Badge tone="warning">实验性</Badge>
+          <Badge tone="danger">已废弃</Badge>
+        </Group>
+      ),
+    },
+    {
+      title: "视觉类型",
+      code: `
+        <Group gap="sm">
+          <Badge tone="info" variant="soft">
+            Soft
+          </Badge>
+          <Badge tone="info" variant="outline">
+            Outline
+          </Badge>
+          <Badge tone="info" variant="solid">
+            Solid
+          </Badge>
+        </Group>;
+      `,
+      content: (
+        <Group gap="sm">
+          <Badge tone="info" variant="soft">
+            Soft
+          </Badge>
+          <Badge tone="info" variant="outline">
+            Outline
+          </Badge>
+          <Badge tone="info" variant="solid">
+            Solid
+          </Badge>
+        </Group>
+      ),
+    },
+    {
+      title: "尺寸和图标",
+      code: `
+        import {
+          CheckCircledIcon,
+          ClockIcon,
+          ExclamationTriangleIcon,
+        } from "@radix-ui/react-icons";
+
+        <Group gap="sm">
+          <Badge size="sm" tone="success" icon={<CheckCircledIcon />}>
+            稳定
+          </Badge>
+          <Badge size="md" tone="warning" icon={<ExclamationTriangleIcon />}>
+            Beta
+          </Badge>
+          <Badge tone="neutral" trailingIcon={<ClockIcon />}>
+            3 分钟阅读
+          </Badge>
+        </Group>;
+      `,
+      content: (
+        <Group gap="sm">
+          <Badge size="sm" tone="success" icon={<CheckCircledIcon />}>
+            稳定
+          </Badge>
+          <Badge size="md" tone="warning" icon={<ExclamationTriangleIcon />}>
+            Beta
+          </Badge>
+          <Badge tone="neutral" trailingIcon={<ClockIcon />}>
+            3 分钟阅读
+          </Badge>
+        </Group>
+      ),
+    },
+    {
+      title: "常见组合",
+      code: `
+        <Group gap="sm">
+          <Badge tone="info">v0.3</Badge>
+          <Badge tone="success">推荐</Badge>
+          <Badge tone="warning" variant="outline">
+            Preview
+          </Badge>
+          <Badge tone="danger" variant="soft">
+            Breaking
+          </Badge>
+        </Group>;
+      `,
+      content: (
+        <Group gap="sm">
+          <Badge tone="info">v0.3</Badge>
+          <Badge tone="success">推荐</Badge>
+          <Badge tone="warning" variant="outline">
+            Preview
+          </Badge>
+          <Badge tone="danger" variant="soft">
+            Breaking
+          </Badge>
+        </Group>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "variant",
+      type: '"soft" | "outline" | "solid"',
+      defaultValue: '"soft"',
+      description: "徽标的视觉类型。",
+    },
+    {
+      name: "tone",
+      type: '"neutral" | "info" | "success" | "warning" | "danger"',
+      defaultValue: '"neutral"',
+      description: "徽标的语义颜色。",
+    },
+    {
+      name: "size",
+      type: '"sm" | "md"',
+      defaultValue: '"md"',
+      description: "徽标尺寸。",
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      description: "展示在文字前的图标。",
+    },
+    {
+      name: "trailingIcon",
+      type: "ReactNode",
+      description: "展示在文字后的图标。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "可选的外层 className。",
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "徽标内容。",
+    },
+  ],
+});