willa-workspace 0.0.3-alpha.2739b3e

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

@@ -0,0 +1,133 @@
+import { EnglishCards } from "willa/EnglishCards";
+import { Separator } from "willa/Separator";
+import "willa/EnglishCards.css";
+import "willa/Separator.css";
+import { unindent } from "aidly";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const items = [
+  {
+    word: "component",
+    phonetic: "/kəmˈpoʊnənt/",
+    partOfSpeech: "noun",
+    translation: "组件",
+    explanation: "一个可复用的界面构建单元。",
+    example: {
+      text: "Each Willa component can be imported directly.",
+      translation: "每个 Willa 组件都可以直接导入。",
+    },
+    tags: ["ui", "react"],
+  },
+  {
+    word: "interface",
+    phonetic: "/ˈɪntərfeɪs/",
+    partOfSpeech: "noun",
+    translation: "界面；接口",
+    explanation: "连接用户、系统或模块的交互边界。",
+    example: {
+      text: "A clean interface makes product workflows easier to scan.",
+      translation: "清晰的界面能让产品流程更容易扫读。",
+    },
+    tags: ["product", "design"],
+  },
+  {
+    word: "context",
+    phonetic: "/ˈkɑːntekst/",
+    partOfSpeech: "noun",
+    translation: "上下文",
+    explanation: "帮助理解当前任务、内容或决策的相关信息。",
+    example: {
+      text: "The assistant needs enough context before generating an answer.",
+      translation: "助手在生成答案前需要足够的上下文。",
+    },
+    tags: ["ai", "workflow"],
+  },
+];
+
+const previewStyle = {
+  width: "min(100%, 64rem)",
+  margin: "0 auto",
+} as const;
+
+const EnglishCardsPreview = () => {
+  return (
+    <div className="docs-demo-stack" style={previewStyle}>
+      <section className="docs-demo-group">
+        <div className="docs-demo-title">学习模式</div>
+        <EnglishCards title="词汇卡片" items={items} />
+      </section>
+
+      <Separator className="docs-demo-separator" size="sm" />
+
+      <section className="docs-demo-group">
+        <div className="docs-demo-title">练习模式</div>
+        <EnglishCards title="词汇练习" items={items} defaultMode="practice" />
+      </section>
+    </div>
+  );
+};
+
+export default defineDoc({
+  id: "english-cards",
+  name: "EnglishCards",
+  category: "widgets",
+  packageName: "willa/EnglishCards",
+  description: "展示翻译、例句和参考信息的单词卡片。",
+  imports: [{ name: "EnglishCards", from: "willa/EnglishCards" }],
+  css: "willa/EnglishCards.css",
+  demo: {
+    name: "EnglishCardsPreview",
+    component: EnglishCardsPreview,
+  },
+  code: unindent(`
+    import { EnglishCards } from "willa/EnglishCards";
+    import "willa/EnglishCards.css";
+
+    const items = [
+      {
+        word: "component",
+        translation: "组件",
+        explanation: "一个可复用的界面构建单元。",
+        example: {
+          text: "Each Willa component can be imported directly.",
+          translation: "每个 Willa 组件都可以直接导入。",
+        },
+        tags: ["ui", "react"],
+      },
+    ];
+
+    export function Demo() {
+      return (
+        <>
+          <EnglishCards title="词汇卡片" items={items} />
+
+          <EnglishCards title="词汇练习" items={items} defaultMode="practice" />
+        </>
+      );
+    }
+  `),
+  props: [
+    {
+      name: "items",
+      type: "Array<EnglishCardItem>",
+      description: "需要渲染的词汇条目。",
+    },
+    {
+      name: "defaultMode",
+      type: '"study" | "practice"',
+      defaultValue: '"study"',
+      description: "初始展示模式。",
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "可选的分区标题。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "可选的外层 className。",
+    },
+  ],
+});

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

@@ -0,0 +1,219 @@
+import { useState } from "react";
+
+import {
+  FeedbackBar,
+  type FeedbackBarPayload,
+  type FeedbackBarState,
+} from "willa/FeedbackBar";
+import "willa/FeedbackBar.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const frameStyle = {
+  display: "grid",
+  gap: "1rem",
+  width: "min(100%, 48rem)",
+} as const;
+
+const statusStyle = {
+  width: "max-content",
+  maxWidth: "100%",
+  border: "1px solid var(--willa-line)",
+  borderRadius: "0.62rem",
+  background: "var(--willa-panel-bg)",
+  color: "var(--willa-text-soft)",
+  fontSize: "0.86rem",
+  fontWeight: 520,
+  lineHeight: 1.45,
+  padding: "0.48rem 0.62rem",
+} as const;
+
+const FeedbackBarPreview = () => {
+  const [payload, setPayload] = useState<FeedbackBarPayload | null>(null);
+
+  return (
+    <div style={frameStyle}>
+      <FeedbackBar
+        targetId="answer-1024"
+        onSubmit={(nextPayload) => {
+          setPayload(nextPayload);
+        }}
+        onUndo={() => {
+          setPayload(null);
+        }}
+      />
+      <div style={statusStyle}>
+        最近提交：
+        {payload
+          ? `${payload.value}${payload.reason ? ` / ${payload.reason}` : ""}`
+          : "暂无"}
+      </div>
+    </div>
+  );
+};
+
+const FeedbackBarControlled = () => {
+  const [state, setState] = useState<FeedbackBarState>({
+    value: "down",
+    reason: "内容不准确",
+    note: "引用的数据范围需要更新。",
+  });
+
+  return (
+    <div style={frameStyle}>
+      <FeedbackBar
+        targetId="answer-controlled"
+        state={state}
+        onSubmit={(payload) => {
+          setState({
+            value: payload.value,
+            reason: payload.reason,
+            note: payload.note,
+          });
+        }}
+        onUndo={() => {
+          setState({ value: "up" });
+        }}
+      />
+    </div>
+  );
+};
+
+const FeedbackBarDisabled = () => (
+  <div style={frameStyle}>
+    <FeedbackBar
+      targetId="answer-disabled"
+      disabled
+      disabledMessage="当前回答来自归档会话，反馈入口已关闭。"
+      onSubmit={() => {
+        return;
+      }}
+    />
+  </div>
+);
+
+export default defineDoc({
+  id: "feedback-bar",
+  name: "FeedbackBar",
+  displayName: "回答反馈",
+  category: "ai",
+  packageName: "willa/FeedbackBar",
+  description: "AI 回复反馈入口，支持点赞、点踩、举报原因和补充说明。",
+  imports: [{ name: "FeedbackBar", from: "willa/FeedbackBar" }],
+  css: "willa/FeedbackBar.css",
+  demo: {
+    name: "FeedbackBarPreview",
+    component: FeedbackBarPreview,
+  },
+  code: `
+    import { useState } from "react";
+    import { FeedbackBar } from "willa/FeedbackBar";
+    import "willa/FeedbackBar.css";
+
+    const Demo = () => {
+      const [payload, setPayload] = useState(null);
+
+      return (
+        <FeedbackBar
+          targetId="answer-1024"
+          onSubmit={(nextPayload) => {
+            setPayload(nextPayload);
+          }}
+        />
+      );
+    };
+  `,
+  sections: [
+    {
+      title: "主链路（提交反馈）",
+      code: `
+        <FeedbackBar
+          targetId="answer-1024"
+          onSubmit={(nextPayload) => {
+            setPayload(nextPayload);
+          }}
+          onUndo={() => {
+            setPayload(null);
+          }}
+        />;
+      `,
+      content: <FeedbackBarPreview />,
+    },
+    {
+      title: "受控状态",
+      code: `
+        <FeedbackBar
+          targetId="answer-controlled"
+          state={state}
+          onSubmit={(payload) => {
+            setState({
+              value: payload.value,
+              reason: payload.reason,
+              note: payload.note,
+            });
+          }}
+        />;
+      `,
+      content: <FeedbackBarControlled />,
+    },
+    {
+      title: "边界（禁用）",
+      code: `
+        <FeedbackBar
+          targetId="answer-disabled"
+          disabled
+          disabledMessage="当前回答来自归档会话，反馈入口已关闭。"
+          onSubmit={() => {}}
+        />;
+      `,
+      content: <FeedbackBarDisabled />,
+    },
+  ],
+  props: [
+    {
+      name: "targetId",
+      type: "string",
+      required: true,
+      description: "反馈关联的回答或目标 ID。",
+    },
+    {
+      name: "state",
+      type: "FeedbackBarState",
+      description: "受控反馈状态。",
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      defaultValue: "false",
+      description: "是否禁用反馈入口。",
+    },
+    {
+      name: "disabledMessage",
+      type: "ReactNode",
+      defaultValue: '"当前反馈入口已禁用"',
+      description: "禁用态提示内容。",
+    },
+    {
+      name: "reportReasons",
+      type: "Array<string>",
+      defaultValue: '["内容不准确", "目标不清晰", "语气不合适", "其他"]',
+      description: "点踩或举报时可选的原因列表。",
+    },
+    {
+      name: "onSubmit",
+      type: "(payload: FeedbackBarPayload) => void | Promise<void>",
+      required: true,
+      description: "提交反馈时触发。",
+    },
+    {
+      name: "onUndo",
+      type: "() => void",
+      description: "点击撤回时触发。",
+    },
+    {
+      name: "onReport",
+      type: "(id: string) => void",
+      description: "举报类反馈提交成功后触发。",
+    },
+  ],
+});

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

@@ -0,0 +1,234 @@
+import { FileCard, FileCardIcon } from "willa/FileCard";
+import "willa/FileCard.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const fileListStyle = {
+  display: "grid",
+  gap: "0.75rem",
+  justifyItems: "center",
+} as const;
+
+const compactFileListStyle = {
+  ...fileListStyle,
+  gridTemplateColumns: "repeat(auto-fit, minmax(13.5rem, 1fr))",
+  width: "min(100%, 56rem)",
+} as const;
+
+const files = [
+  { name: "excel-has-long-long-long-file-name.xlsx", size: "1 KB" },
+  { name: "word-file.docx", size: "1 KB" },
+  { name: "pdf-file.pdf", size: "1 KB" },
+  { name: "ppt-file.pptx", size: "1 KB" },
+  { name: "feedback.csv", size: "12 KB" },
+  { name: "screen-capture.png", size: "428 KB" },
+  { name: "meeting-audio.mp3", size: "8 MB" },
+  { name: "launch-video.mp4", size: "26 MB" },
+  { name: "component-data.json", size: "2 KB" },
+  { name: "zip-file.zip", size: "1 KB" },
+  { name: "javascript-file.js", size: "1 KB" },
+];
+
+const FileListPreview = () => (
+  <div style={fileListStyle}>
+    {files.map((file) => (
+      <FileCard key={file.name} name={file.name} size={file.size} />
+    ))}
+  </div>
+);
+
+export default defineDoc({
+  id: "file-card",
+  name: "FileCard",
+  packageName: "willa/FileCard",
+  description: "用于文章、资料下载和附件列表中的文件卡片。",
+  imports: [
+    { name: "FileCard", from: "willa/FileCard" },
+    { name: "FileCardIcon", from: "willa/FileCard" },
+  ],
+  css: "willa/FileCard.css",
+  demo: {
+    name: "FileListPreview",
+    component: FileListPreview,
+  },
+  code: `
+    import { FileCard } from "willa/FileCard";
+    import "willa/FileCard.css";
+
+    const files = [
+      { name: "excel-has-long-long-long-file-name.xlsx", size: "1 KB" },
+      { name: "word-file.docx", size: "1 KB" },
+      { name: "pdf-file.pdf", size: "1 KB" },
+      { name: "ppt-file.pptx", size: "1 KB" },
+      { name: "feedback.csv", size: "12 KB" },
+      { name: "screen-capture.png", size: "428 KB" },
+      { name: "meeting-audio.mp3", size: "8 MB" },
+      { name: "launch-video.mp4", size: "26 MB" },
+      { name: "component-data.json", size: "2 KB" },
+    ];
+
+    <div style={{ display: "grid", gap: "0.75rem" }}>
+      {files.map((file) => (
+        <FileCard key={file.name} name={file.name} size={file.size} />
+      ))}
+    </div>;
+  `,
+  sections: [
+    {
+      title: "链接文件",
+      code: `
+        <FileCard
+          href="https://example.com/report.pdf"
+          target="_blank"
+          name="quarterly-report.pdf"
+          size="428 KB"
+        />;
+      `,
+      content: (
+        <FileCard
+          href="https://example.com/report.pdf"
+          target="_blank"
+          name="quarterly-report.pdf"
+          size="428 KB"
+        />
+      ),
+    },
+    {
+      title: "自定义类型",
+      code: `
+        <div style={compactFileListStyle}>
+          <FileCard name="README" extension="md" size="2 KB" />
+          <FileCard name="dataset" extension="csv" size="24 KB" />
+          <FileCard name="archive.backup" tone="archive" size="1.2 MB" />
+        </div>;
+      `,
+      content: (
+        <div style={compactFileListStyle}>
+          <FileCard name="README" extension="md" size="2 KB" />
+          <FileCard name="dataset" extension="csv" size="24 KB" />
+          <FileCard name="archive.backup" tone="archive" size="1.2 MB" />
+        </div>
+      ),
+    },
+    {
+      title: "图片和媒体类型",
+      code: `
+        <div style={compactFileListStyle}>
+          <FileCard name="feedback.csv" size="12 KB" />
+          <FileCard name="screen-capture.png" size="428 KB" />
+          <FileCard name="meeting-audio.mp3" size="8 MB" />
+          <FileCard name="launch-video.mp4" size="26 MB" />
+          <FileCard name="component-data.json" size="2 KB" />
+        </div>;
+      `,
+      content: (
+        <div style={compactFileListStyle}>
+          <FileCard name="feedback.csv" size="12 KB" />
+          <FileCard name="screen-capture.png" size="428 KB" />
+          <FileCard name="meeting-audio.mp3" size="8 MB" />
+          <FileCard name="launch-video.mp4" size="26 MB" />
+          <FileCard name="component-data.json" size="2 KB" />
+        </div>
+      ),
+    },
+    {
+      title: "文件图标",
+      code: `
+        <div
+          style={{
+            display: "flex",
+            gap: "0.75rem",
+            alignItems: "center",
+            justifyContent: "center",
+          }}
+        >
+          <FileCardIcon name="feedback.csv" size="sm" />
+          <FileCardIcon name="roadmap.md" size="md" />
+          <FileCardIcon name="screen-capture.png" size="lg" />
+        </div>;
+      `,
+      content: (
+        <div
+          style={{
+            display: "flex",
+            gap: "0.75rem",
+            alignItems: "center",
+            justifyContent: "center",
+          }}
+        >
+          <FileCardIcon name="feedback.csv" size="sm" />
+          <FileCardIcon name="roadmap.md" size="md" />
+          <FileCardIcon name="screen-capture.png" size="lg" />
+        </div>
+      ),
+    },
+    {
+      title: "自定义图标",
+      code: `
+        <FileCard
+          name="design-source.fig"
+          extension="fig"
+          icon={<span>F</span>}
+          tone="neutral"
+          size="860 KB"
+        />;
+      `,
+      content: (
+        <FileCard
+          name="design-source.fig"
+          extension="fig"
+          icon={<span>F</span>}
+          tone="neutral"
+          size="860 KB"
+        />
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "name",
+      type: "string",
+      required: true,
+      description: "文件名，组件会根据扩展名自动推断图标色调。",
+    },
+    {
+      name: "href",
+      type: "string",
+      description: "传入后渲染为可点击链接卡片。",
+    },
+    {
+      name: "size",
+      type: "ReactNode",
+      description: "文件大小或副文案。",
+    },
+    {
+      name: "extension",
+      type: "string",
+      defaultValue: "从 name 推导",
+      description: "手动指定扩展名，适合文件名不包含后缀的场景。",
+    },
+    {
+      name: "tone",
+      type: '"excel" | "word" | "pdf" | "ppt" | "image" | "audio" | "video" | "archive" | "code" | "text" | "neutral"',
+      description: "手动指定图标色调。",
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      defaultValue: "由文件类型决定",
+      description: "自定义文件图标内容。",
+    },
+    {
+      name: "FileCardIcon.size",
+      type: '"sm" | "md" | "lg"',
+      group: "FileCardIcon",
+      defaultValue: '"md"',
+      description: "文件图标尺寸。列表、预览类场景通常使用 sm。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "可选的外层 className。",
+    },
+  ],
+});