willa-workspace 0.0.3-alpha.2739b3e

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

@@ -0,0 +1,275 @@
+import { useState } from "react";
+
+import { HumanApprovalCard } from "willa/HumanApprovalCard";
+import "willa/HumanApprovalCard.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const frameStyle = {
+  display: "grid",
+  gap: "1rem",
+  width: "min(100%, 54rem)",
+} as const;
+
+const paragraphStyle = {
+  margin: 0,
+} as const;
+
+const HumanApprovalCardPreview = () => {
+  const [status, setStatus] = useState<"pending" | "approved" | "rejected">(
+    "pending",
+  );
+
+  return (
+    <div style={frameStyle}>
+      <HumanApprovalCard
+        title="发送外部邮件前需要确认"
+        description="AI 即将把整理后的事故复盘发送给客户联系人。"
+        status={status}
+        tone="warning"
+        meta="高影响操作"
+        details={[
+          { label: "收件人", value: "3 人" },
+          { label: "附件", value: "2 个" },
+          { label: "风险", value: "中" },
+        ]}
+        onApprove={() => {
+          setStatus("approved");
+        }}
+        onReject={() => {
+          setStatus("rejected");
+        }}
+      >
+        <p style={paragraphStyle}>
+          邮件包含事故时间线、影响范围和补偿说明。确认后将进入发送队列。
+        </p>
+      </HumanApprovalCard>
+    </div>
+  );
+};
+
+export default defineDoc({
+  id: "human-approval-card",
+  name: "HumanApprovalCard",
+  displayName: "人工确认卡片",
+  category: "ai",
+  packageName: "willa/HumanApprovalCard",
+  description: "用于 AI 执行高影响操作前请求人工确认，并展示审批状态。",
+  imports: [{ name: "HumanApprovalCard", from: "willa/HumanApprovalCard" }],
+  css: "willa/HumanApprovalCard.css",
+  demo: {
+    name: "HumanApprovalCardPreview",
+    component: HumanApprovalCardPreview,
+  },
+  code: `
+    import { useState } from "react";
+    import { HumanApprovalCard } from "willa/HumanApprovalCard";
+    import "willa/HumanApprovalCard.css";
+
+    const Demo = () => {
+      const [status, setStatus] = useState("pending");
+
+      return (
+        <HumanApprovalCard
+          title="发送外部邮件前需要确认"
+          description="AI 即将把整理后的事故复盘发送给客户联系人。"
+          status={status}
+          tone="warning"
+          meta="高影响操作"
+          details={[
+            { label: "收件人", value: "3 人" },
+            { label: "附件", value: "2 个" },
+            { label: "风险", value: "中" },
+          ]}
+          onApprove={() => setStatus("approved")}
+          onReject={() => setStatus("rejected")}
+        >
+          邮件包含事故时间线、影响范围和补偿说明。确认后将进入发送队列。
+        </HumanApprovalCard>
+      );
+    };
+  `,
+  sections: [
+    {
+      title: "异步确认",
+      code: `
+        <HumanApprovalCard
+          title="执行批量退款"
+          description="确认后会创建批量退款任务，并通知财务系统。"
+          tone="danger"
+          details={[
+            { label: "订单", value: "42 笔" },
+            { label: "金额", value: "¥18,420" },
+          ]}
+          onApprove={() => {
+            return new Promise((resolve) => window.setTimeout(resolve, 800));
+          }}
+          onReject={() => {
+            return Promise.resolve();
+          }}
+        />;
+      `,
+      content: (
+        <HumanApprovalCard
+          title="执行批量退款"
+          description="确认后会创建批量退款任务，并通知财务系统。"
+          tone="danger"
+          details={[
+            { label: "订单", value: "42 笔" },
+            { label: "金额", value: "¥18,420" },
+          ]}
+          onApprove={() => {
+            return new Promise((resolve) => window.setTimeout(resolve, 800));
+          }}
+          onReject={() => {
+            return Promise.resolve();
+          }}
+        />
+      ),
+    },
+    {
+      title: "终态展示",
+      code: `
+        <div style={frameStyle}>
+          <HumanApprovalCard
+            title="已允许读取私有知识库"
+            description="审批完成后，AI 可以继续执行检索和总结。"
+            status="approved"
+            details={[{ label: "审批人", value: "Ming" }]}
+          />
+          <HumanApprovalCard
+            title="导出客户数据"
+            description="审批已过期，需要重新提交确认请求。"
+            status="expired"
+            details={[{ label: "过期时间", value: "10 分钟前" }]}
+          />
+        </div>;
+      `,
+      content: (
+        <div style={frameStyle}>
+          <HumanApprovalCard
+            title="已允许读取私有知识库"
+            description="审批完成后，AI 可以继续执行检索和总结。"
+            status="approved"
+            details={[{ label: "审批人", value: "Ming" }]}
+          />
+          <HumanApprovalCard
+            title="导出客户数据"
+            description="审批已过期，需要重新提交确认请求。"
+            status="expired"
+            details={[{ label: "过期时间", value: "10 分钟前" }]}
+          />
+        </div>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "title",
+      type: "ReactNode",
+      required: true,
+      description: "确认卡片标题。",
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "标题下方的说明文案。",
+    },
+    {
+      name: "status",
+      type: '"pending" | "approved" | "rejected" | "expired"',
+      defaultValue: '"pending"',
+      description: "当前审批状态；非 pending 状态不会展示确认和拒绝按钮。",
+    },
+    {
+      name: "tone",
+      type: '"neutral" | "warning" | "danger"',
+      defaultValue: '"neutral"',
+      description: "pending 状态下的风险色调。",
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      description: "自定义左侧图标。",
+    },
+    {
+      name: "meta",
+      type: "ReactNode",
+      description: "右上角辅助信息。",
+    },
+    {
+      name: "details",
+      type: "Array<HumanApprovalCardDetail>",
+      description: "审批对象、风险、操作者等结构化明细。",
+    },
+    {
+      name: "approveText",
+      type: "ReactNode",
+      defaultValue: '"确认继续"',
+      description: "确认按钮文案。",
+    },
+    {
+      name: "rejectText",
+      type: "ReactNode",
+      defaultValue: '"拒绝"',
+      description: "拒绝按钮文案。",
+    },
+    {
+      name: "approveDisabled",
+      type: "boolean",
+      defaultValue: "false",
+      description: "是否禁用确认按钮。",
+    },
+    {
+      name: "rejectDisabled",
+      type: "boolean",
+      defaultValue: "false",
+      description: "是否禁用拒绝按钮。",
+    },
+    {
+      name: "approveLoading",
+      type: "boolean",
+      defaultValue: "false",
+      description: "外部受控的确认按钮 loading 状态。",
+    },
+    {
+      name: "rejectLoading",
+      type: "boolean",
+      defaultValue: "false",
+      description: "外部受控的拒绝按钮 loading 状态。",
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "审批内容预览或风险说明。",
+    },
+    {
+      name: "onApprove",
+      type: "(event: MouseEvent<HTMLButtonElement>) => void | Promise<void>",
+      description:
+        "点击确认按钮时触发；返回 Promise 时组件会展示内部 loading。",
+    },
+    {
+      name: "onReject",
+      type: "(event: MouseEvent<HTMLButtonElement>) => void | Promise<void>",
+      description:
+        "点击拒绝按钮时触发；返回 Promise 时组件会展示内部 loading。",
+    },
+    {
+      name: "onActionError",
+      type: "(error: unknown, action: HumanApprovalCardAction, event: MouseEvent<HTMLButtonElement>) => void",
+      description:
+        "确认或拒绝动作抛错时触发；组件会清理内部 loading，并继续抛出该错误。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "透传到根 section 的类名。",
+    },
+    {
+      name: "style",
+      type: "CSSProperties",
+      description: "透传到根 section 的内联样式。",
+    },
+  ],
+});

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

@@ -0,0 +1,354 @@
+import {
+  ArrowRightIcon,
+  BookmarkIcon,
+  CheckIcon,
+  ClipboardCopyIcon,
+  DownloadIcon,
+  ExternalLinkIcon,
+  HeartIcon,
+  MagnifyingGlassIcon,
+  Share2Icon,
+} from "@radix-ui/react-icons";
+import { IconButton } from "willa/IconButton";
+import "willa/IconButton.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const iconButtonRowStyle = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "0.75rem",
+  alignItems: "center",
+} as const;
+
+export default defineDoc({
+  id: "icon-button",
+  name: "IconButton",
+  packageName: "willa/IconButton",
+  description: "用于工具栏、卡片操作区和内联内容中的纯图标按钮。",
+  imports: [{ name: "IconButton", from: "willa/IconButton" }],
+  css: "willa/IconButton.css",
+  demo: {
+    name: "IconButton",
+    component: IconButton,
+    props: {
+      ariaLabel: "分享文章",
+      icon: <Share2Icon />,
+    },
+  },
+  code: `
+    import { Share2Icon } from "@radix-ui/react-icons";
+    import { IconButton } from "willa/IconButton";
+    import "willa/IconButton.css";
+
+    <IconButton ariaLabel="分享文章" icon={<Share2Icon />} />;
+  `,
+  sections: [
+    {
+      title: "视觉类型",
+      code: `
+        <div style={iconButtonRowStyle}>
+          <IconButton ariaLabel="收藏" icon={<BookmarkIcon />} variant="solid" />
+          <IconButton ariaLabel="喜欢" icon={<HeartIcon />} variant="soft" />
+          <IconButton ariaLabel="下载" icon={<DownloadIcon />} variant="outline" />
+          <IconButton ariaLabel="搜索" icon={<MagnifyingGlassIcon />} variant="ghost" />
+        </div>;
+      `,
+      content: (
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="收藏"
+            icon={<BookmarkIcon />}
+            variant="solid"
+          />
+          <IconButton ariaLabel="喜欢" icon={<HeartIcon />} variant="soft" />
+          <IconButton
+            ariaLabel="下载"
+            icon={<DownloadIcon />}
+            variant="outline"
+          />
+          <IconButton
+            ariaLabel="搜索"
+            icon={<MagnifyingGlassIcon />}
+            variant="ghost"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "尺寸和形状",
+      code: `
+        <div style={iconButtonRowStyle}>
+          <IconButton ariaLabel="上一步" icon={<ArrowRightIcon />} size="sm" />
+          <IconButton ariaLabel="外部链接" icon={<ExternalLinkIcon />} shape="circle" />
+          <IconButton
+            ariaLabel="确认"
+            icon={<CheckIcon />}
+            shape="circle"
+            size="lg"
+            variant="outline"
+          />
+        </div>;
+      `,
+      content: (
+        <div style={iconButtonRowStyle}>
+          <IconButton ariaLabel="上一步" icon={<ArrowRightIcon />} size="sm" />
+          <IconButton
+            ariaLabel="外部链接"
+            icon={<ExternalLinkIcon />}
+            shape="circle"
+          />
+          <IconButton
+            ariaLabel="确认"
+            icon={<CheckIcon />}
+            shape="circle"
+            size="lg"
+            variant="outline"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "链接、禁用和加载",
+      code: `
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="打开 GitHub"
+            href="https://github.com"
+            icon={<ExternalLinkIcon />}
+            target="_blank"
+            variant="outline"
+          />
+          <IconButton ariaLabel="不可点击" disabled icon={<BookmarkIcon />} />
+          <IconButton
+            ariaLabel="保存"
+            icon={<CheckIcon />}
+            loading
+            loadingLabel="保存中"
+            variant="soft"
+          />
+        </div>;
+      `,
+      content: (
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="打开 GitHub"
+            href="https://github.com"
+            icon={<ExternalLinkIcon />}
+            target="_blank"
+            variant="outline"
+          />
+          <IconButton ariaLabel="不可点击" disabled icon={<BookmarkIcon />} />
+          <IconButton
+            ariaLabel="保存"
+            icon={<CheckIcon />}
+            loading
+            loadingLabel="保存中"
+            variant="soft"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "按下态",
+      code: `
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="收藏"
+            icon={<BookmarkIcon />}
+            pressed
+            variant="ghost"
+          />
+          <IconButton
+            ariaLabel="确认选择"
+            icon={<CheckIcon />}
+            pressed
+            variant="outline"
+          />
+        </div>;
+      `,
+      content: (
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="收藏"
+            icon={<BookmarkIcon />}
+            pressed
+            variant="ghost"
+          />
+          <IconButton
+            ariaLabel="确认选择"
+            icon={<CheckIcon />}
+            pressed
+            variant="outline"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "点击复制",
+      code: `
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="复制安装命令"
+            copyText="pnpm add willa"
+            icon={<ClipboardCopyIcon />}
+          />
+          <IconButton
+            ariaLabel="复制组件引入"
+            copyText="import { IconButton } from 'willa/IconButton';"
+            icon={<ClipboardCopyIcon />}
+            variant="outline"
+          />
+        </div>;
+      `,
+      content: (
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="复制安装命令"
+            copyText="pnpm add willa"
+            icon={<ClipboardCopyIcon />}
+          />
+          <IconButton
+            ariaLabel="复制组件引入"
+            copyText="import { IconButton } from 'willa/IconButton';"
+            icon={<ClipboardCopyIcon />}
+            variant="outline"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "自定义颜色",
+      code: `
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="暖色收藏"
+            backgroundColor="#f6e7c8"
+            icon={<BookmarkIcon />}
+            textColor="#3f2a12"
+          />
+          <IconButton
+            ariaLabel="蓝色搜索"
+            backgroundColor="rgba(96, 165, 250, 0.14)"
+            icon={<MagnifyingGlassIcon />}
+            textColor="currentColor"
+            variant="outline"
+          />
+        </div>;
+      `,
+      content: (
+        <div style={iconButtonRowStyle}>
+          <IconButton
+            ariaLabel="暖色收藏"
+            backgroundColor="#f6e7c8"
+            icon={<BookmarkIcon />}
+            textColor="#3f2a12"
+          />
+          <IconButton
+            ariaLabel="蓝色搜索"
+            backgroundColor="rgba(96, 165, 250, 0.14)"
+            icon={<MagnifyingGlassIcon />}
+            textColor="currentColor"
+            variant="outline"
+          />
+        </div>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "ariaLabel",
+      type: "string",
+      required: true,
+      description: "无可见文字时提供给辅助技术的按钮名称。",
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      required: true,
+      description: "按钮内展示的图标。",
+    },
+    {
+      name: "variant",
+      type: '"solid" | "soft" | "outline" | "ghost"',
+      defaultValue: '"soft"',
+      description: "按钮的视觉类型。",
+    },
+    {
+      name: "size",
+      type: '"sm" | "md" | "lg"',
+      defaultValue: '"md"',
+      description: "按钮尺寸。",
+    },
+    {
+      name: "shape",
+      type: '"square" | "circle"',
+      defaultValue: '"square"',
+      description: "按钮外形。",
+    },
+    {
+      name: "href",
+      type: "string",
+      description: "传入后渲染为链接按钮。",
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      defaultValue: "false",
+      description: "禁用按钮或链接按钮。",
+    },
+    {
+      name: "loading",
+      type: "boolean",
+      defaultValue: "false",
+      description: "展示加载状态，并阻止点击、复制和链接跳转。",
+    },
+    {
+      name: "loadingLabel",
+      type: "string",
+      description: "加载时替换 ariaLabel 的辅助技术文案。",
+    },
+    {
+      name: "pressed",
+      type: "boolean",
+      description: "按钮是否处于按下态；传入后会同步 aria-pressed 语义。",
+    },
+    {
+      name: "backgroundColor",
+      type: "string",
+      description: "自定义按钮背景颜色，支持 CSS 颜色值。",
+    },
+    {
+      name: "textColor",
+      type: "string",
+      description: "自定义图标颜色，支持 CSS 颜色值。",
+    },
+    {
+      name: "copyText",
+      type: "boolean | string",
+      description:
+        "启用复制能力；传 true 时复制 ariaLabel，传字符串时复制该字符串。",
+    },
+    {
+      name: "copiedDuration",
+      type: "number",
+      defaultValue: "300",
+      description: "复制成功反馈持续时间，默认 300ms。",
+    },
+    {
+      name: "onCopyText",
+      type: "(text: string) => void",
+      description: "复制成功后的回调。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "自定义 className。",
+    },
+    {
+      name: "type",
+      type: "string",
+      description: "组件类型。",
+    },
+  ],
+});