willa-workspace 0.0.3-alpha.2739b3e

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

@@ -0,0 +1,143 @@
+import { Callout } from "willa/Callout";
+import "willa/Callout.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const calloutStackStyle = {
+  display: "grid",
+  gap: "0.85rem",
+} as const;
+
+const calloutArticleStyle = {
+  display: "grid",
+  gap: "0.75rem",
+  maxWidth: "720px",
+} as const;
+
+export default defineDoc({
+  id: "callout",
+  name: "Callout",
+  packageName: "willa/Callout",
+  description:
+    "用于文档、MDX 和文章正文中的语义提示块，适合承载解释、建议、注意事项和长文本说明；页面操作反馈优先使用 Alert。",
+  imports: [{ name: "Callout", from: "willa/Callout" }],
+  css: "willa/Callout.css",
+  demo: {
+    name: "Callout",
+    component: Callout,
+    props: { tone: "tip", title: "阅读建议" },
+    children:
+      "这类内容会跟随正文长期存在，用来补充上下文，而不是反馈一次操作结果。",
+  },
+  code: `
+    import { Callout } from "willa/Callout";
+    import "willa/Callout.css";
+
+    <Callout tone="tip" title="阅读建议">
+      这类内容会跟随正文长期存在，用来补充上下文，而不是反馈一次操作结果。
+    </Callout>;
+  `,
+  sections: [
+    {
+      title: "内容边界",
+      code: `
+        <div style={{ display: "grid", gap: "0.75rem", maxWidth: "720px" }}>
+          <Callout tone="warning" title="迁移前确认">
+            <p>Callout 适合出现在文档正文里，用来承载会长期保留的解释性内容。</p>
+            <p>如果内容表示一次保存、发布、提交或异步任务的结果，应使用 Alert。</p>
+          </Callout>
+          <Callout tone="note" title="正文语境">
+            这类提示会跟随文章、教程或 MDX 页面长期展示，不提供关闭按钮、操作区和 live region。
+          </Callout>
+        </div>;
+      `,
+      content: (
+        <div style={calloutArticleStyle}>
+          <Callout tone="warning" title="迁移前确认">
+            <p>
+              Callout 适合出现在文档正文里，用来承载会长期保留的解释性内容。
+            </p>
+            <p>
+              如果内容表示一次保存、发布、提交或异步任务的结果，应使用 Alert。
+            </p>
+          </Callout>
+          <Callout tone="note" title="正文语境">
+            这类提示会跟随文章、教程或 MDX
+            页面长期展示，不提供关闭按钮、操作区和 live region。
+          </Callout>
+        </div>
+      ),
+    },
+    {
+      title: "语义类型",
+      code: `
+        <div style={{ display: "grid", gap: "0.85rem" }}>
+          <Callout tone="note" title="说明">
+            在组件文档、迁移说明或教程正文中补充背景和定义。
+          </Callout>
+          <Callout tone="tip" title="提示">
+            给读者一个更推荐的写法、捷径或实践建议。
+          </Callout>
+          <Callout tone="warning" title="注意">
+            标记会影响理解或使用结果的前置条件。
+          </Callout>
+          <Callout tone="success" title="完成">
+            在教程步骤里说明某个阶段应达到的稳定结果。
+          </Callout>
+          <Callout tone="error" title="错误">
+            解释常见失败原因和读者需要检查的上下文。
+          </Callout>
+        </div>;
+      `,
+      content: (
+        <div style={calloutStackStyle}>
+          <Callout tone="note" title="说明">
+            在组件文档、迁移说明或教程正文中补充背景和定义。
+          </Callout>
+          <Callout tone="tip" title="提示">
+            给读者一个更推荐的写法、捷径或实践建议。
+          </Callout>
+          <Callout tone="warning" title="注意">
+            标记会影响理解或使用结果的前置条件。
+          </Callout>
+          <Callout tone="success" title="完成">
+            在教程步骤里说明某个阶段应达到的稳定结果。
+          </Callout>
+          <Callout tone="error" title="错误">
+            解释常见失败原因和读者需要检查的上下文。
+          </Callout>
+        </div>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "tone",
+      type: '"note" | "tip" | "warning" | "success" | "error"',
+      defaultValue: '"note"',
+      description: "信息块的视觉语义。",
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      defaultValue: "由 tone 决定",
+      description: "展示在正文上方的可选标题。",
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      defaultValue: "由 tone 决定",
+      description: "自定义左侧图标，未传时按 tone 使用默认图标。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "可选的外层 className。",
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "信息块的主要内容。",
+    },
+  ],
+});

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

@@ -0,0 +1,254 @@
+import { ArrowRightIcon, BookmarkIcon } from "@radix-ui/react-icons";
+import { Badge } from "willa/Badge";
+import "willa/Badge.css";
+import { Button } from "willa/Button";
+import "willa/Button.css";
+import { Card } from "willa/Card";
+import "willa/Card.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const cardGridStyle = {
+  display: "grid",
+  gridTemplateColumns: "repeat(auto-fit, minmax(14rem, 1fr))",
+  gap: "0.9rem",
+  width: "min(100%, 56rem)",
+} as const;
+
+const mediaStyle = {
+  aspectRatio: "16 / 9",
+  background:
+    "linear-gradient(135deg, rgba(37, 99, 235, 0.18), rgba(5, 150, 105, 0.12))",
+} as const;
+
+export default defineDoc({
+  id: "card",
+  name: "Card",
+  category: "layout",
+  packageName: "willa/Card",
+  description: "用于资源入口、文章摘要、链接推荐和组合式内容块。",
+  imports: [{ name: "Card", from: "willa/Card" }],
+  css: "willa/Card.css",
+  demo: {
+    name: "Card",
+    component: Card,
+    props: {
+      eyebrow: "指南",
+      title: "构建内容组件",
+      description: "用统一的结构和主题变量组织文章页里的推荐资源。",
+    },
+  },
+  code: `
+    import { Card } from "willa/Card";
+    import "willa/Card.css";
+
+    <Card
+      eyebrow="指南"
+      title="构建内容组件"
+      description="用统一的结构和主题变量组织文章页里的推荐资源。"
+    />;
+  `,
+  sections: [
+    {
+      title: "基础用法",
+      code: `
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(auto-fit, minmax(14rem, 1fr))",
+            gap: "0.9rem",
+          }}
+        >
+          <Card
+            eyebrow="指南"
+            title="内容组件边界"
+            description="把文章、文档和 MDX 页面中高频出现的结构沉淀成可复用组件。"
+            footer={<Badge tone="info">Docs</Badge>}
+          />
+          <Card
+            eyebrow="资源"
+            title="组件主题变量"
+            description="主题值集中在所属包里维护，结构样式保持可组合。"
+            footer="5 分钟阅读"
+          />
+        </div>;
+      `,
+      content: (
+        <div style={cardGridStyle}>
+          <Card
+            eyebrow="指南"
+            title="内容组件边界"
+            description="把文章、文档和 MDX 页面中高频出现的结构沉淀成可复用组件。"
+            footer={<Badge tone="info">Docs</Badge>}
+          />
+          <Card
+            eyebrow="资源"
+            title="组件主题变量"
+            description="主题值集中在所属包里维护，结构样式保持可组合。"
+            footer="5 分钟阅读"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "可点击卡片",
+      code: `
+        <Card
+          href="https://github.com"
+          target="_blank"
+          eyebrow={<Badge tone="success">推荐</Badge>}
+          title="查看项目仓库"
+          description="把整张卡片作为明确的链接入口。"
+        />;
+      `,
+      content: (
+        <Card
+          href="https://github.com"
+          target="_blank"
+          eyebrow={<Badge tone="success">推荐</Badge>}
+          title="查看项目仓库"
+          description="把整张卡片作为明确的链接入口，适合资源推荐和文章延伸阅读。"
+          actions={<ArrowRightIcon />}
+        />
+      ),
+    },
+    {
+      title: "视觉类型",
+      code: `
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(auto-fit, minmax(14rem, 1fr))",
+            gap: "0.9rem",
+          }}
+        >
+          <Card
+            variant="surface"
+            title="Surface"
+            description="带边框和轻阴影的默认卡片。"
+          />
+          <Card
+            variant="soft"
+            title="Soft"
+            description="更轻的色块卡片，适合嵌在正文中。"
+          />
+          <Card
+            variant="outline"
+            title="Outline"
+            description="只保留边框，适合密集列表。"
+          />
+        </div>;
+      `,
+      content: (
+        <div style={cardGridStyle}>
+          <Card
+            variant="surface"
+            title="Surface"
+            description="带边框和轻阴影的默认卡片。"
+          />
+          <Card
+            variant="soft"
+            title="Soft"
+            description="更轻的色块卡片，适合嵌在正文中。"
+          />
+          <Card
+            variant="outline"
+            title="Outline"
+            description="只保留边框，适合密集列表。"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "组合内容",
+      code: `
+        <Card
+          padding="lg"
+          eyebrow={<Badge tone="warning">Preview</Badge>}
+          title="面向内容页的组合卡片"
+          description="Card 可以和 Badge、Button、媒体区域组合。"
+          footer="更新于今天"
+          actions={
+            <Button size="sm" variant="outline">
+              收藏
+            </Button>
+          }
+        />;
+      `,
+      content: (
+        <Card
+          padding="lg"
+          media={<div style={mediaStyle} />}
+          eyebrow={<Badge tone="warning">Preview</Badge>}
+          title="面向内容页的组合卡片"
+          description="Card 可以和 Badge、Button、媒体区域组合，用来承载更完整的资源信息。"
+          footer="更新于今天"
+          actions={
+            <Button size="sm" variant="outline" trailingIcon={<BookmarkIcon />}>
+              收藏
+            </Button>
+          }
+        />
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "variant",
+      type: '"surface" | "soft" | "outline"',
+      defaultValue: '"surface"',
+      description: "卡片的视觉类型。",
+    },
+    {
+      name: "padding",
+      type: '"sm" | "md" | "lg"',
+      defaultValue: '"md"',
+      description: "卡片内边距。",
+    },
+    {
+      name: "href",
+      type: "string",
+      description: "传入后渲染为可点击链接卡片。",
+    },
+    {
+      name: "eyebrow",
+      type: "ReactNode",
+      description: "标题上方的辅助信息，可组合 Badge。",
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "卡片标题。",
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "卡片描述。",
+    },
+    {
+      name: "media",
+      type: "ReactNode",
+      description: "卡片顶部媒体区域。",
+    },
+    {
+      name: "footer",
+      type: "ReactNode",
+      description: "卡片底部辅助信息。",
+    },
+    {
+      name: "actions",
+      type: "ReactNode",
+      description: "卡片底部右侧操作区。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "可选的外层 className。",
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "自定义正文内容。",
+    },
+  ],
+});