willa-workspace 0.0.3-alpha.2739b3e

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

@@ -0,0 +1,285 @@
+import { useState } from "react";
+import { ChatBubbleIcon, CodeIcon, FileTextIcon } from "@radix-ui/react-icons";
+import { Badge } from "willa/Badge";
+import "willa/Badge.css";
+import { Tabs } from "willa/Tabs";
+import "willa/Tabs.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const tabsItems = [
+  {
+    value: "overview",
+    label: "概览",
+    children: "用标签把同一上下文下的内容分组，减少页面里的纵向堆叠。",
+  },
+  {
+    value: "usage",
+    label: "使用方式",
+    children: "适合文章示例、参数说明、资源信息和多版本内容切换。",
+  },
+  {
+    value: "notes",
+    label: "注意事项",
+    children: "标签文案应保持短句，内容区域只承载当前选中标签的信息。",
+  },
+];
+
+const docsItems = [
+  {
+    value: "react",
+    label: "React",
+    icon: <CodeIcon />,
+    children: (
+      <p>在内容页中展示 React 示例，可以把安装、基础代码和样式导入拆成标签。</p>
+    ),
+  },
+  {
+    value: "css",
+    label: "CSS",
+    icon: <FileTextIcon />,
+    children: (
+      <p>
+        单组件样式通过 <code>willa/Tabs.css</code> 引入，主题变量来自 content
+        包。
+      </p>
+    ),
+  },
+  {
+    value: "disabled",
+    label: "待补充",
+    icon: <ChatBubbleIcon />,
+    disabled: true,
+    children: "这个面板不会被选中。",
+  },
+];
+
+const ControlledTabsExample = () => {
+  const [value, setValue] = useState("draft");
+
+  return (
+    <div style={{ display: "grid", gap: "0.75rem" }}>
+      <Badge tone="info">当前：{value}</Badge>
+      <Tabs
+        value={value}
+        onValueChange={setValue}
+        items={[
+          {
+            value: "draft",
+            label: "草稿",
+            children: "保存还没有发布的内容提纲。",
+          },
+          {
+            value: "review",
+            label: "审核",
+            children: "集中查看需要修改或确认的信息。",
+          },
+          {
+            value: "published",
+            label: "已发布",
+            children: "展示已经对外可见的内容版本。",
+          },
+        ]}
+      />
+    </div>
+  );
+};
+
+export default defineDoc({
+  id: "tabs",
+  name: "Tabs",
+  packageName: "willa/Tabs",
+  description:
+    "用于在同一上下文里切换多组内容面板；只切换视图、模式或筛选状态时优先使用 Segmented。",
+  imports: [{ name: "Tabs", from: "willa/Tabs" }],
+  css: "willa/Tabs.css",
+  demo: {
+    name: "Tabs",
+    component: Tabs,
+    props: {
+      items: tabsItems,
+    },
+  },
+  code: `
+    import { Tabs } from "willa/Tabs";
+    import "willa/Tabs.css";
+
+    const items = [
+      {
+        value: "overview",
+        label: "概览",
+        children: "用标签把同一上下文下的内容分组，减少页面里的纵向堆叠。",
+      },
+      {
+        value: "usage",
+        label: "使用方式",
+        children: "适合文章示例、参数说明、资源信息和多版本内容切换。",
+      },
+    ];
+
+    <Tabs items={items} />;
+  `,
+  sections: [
+    {
+      title: "基础用法",
+      code: `
+        <Tabs items={tabsItems} />;
+      `,
+      content: <Tabs items={tabsItems} />,
+    },
+    {
+      title: "禁用标签",
+      code: `
+        <Tabs items={docsItems} defaultValue="css" />;
+      `,
+      content: <Tabs items={docsItems} defaultValue="css" />,
+    },
+    {
+      title: "图标标签",
+      code: `
+        <Tabs items={docsItems} />;
+      `,
+      content: <Tabs items={docsItems} />,
+    },
+    {
+      title: "小尺寸",
+      code: `
+        <Tabs size="sm" items={tabsItems} />;
+      `,
+      content: <Tabs size="sm" items={tabsItems} />,
+    },
+    {
+      title: "受控状态",
+      code: `
+        import { useState } from "react";
+        import { Badge } from "willa/Badge";
+        import { Tabs } from "willa/Tabs";
+        import "willa/Badge.css";
+        import "willa/Tabs.css";
+
+        const Demo = () => {
+          const [value, setValue] = useState("draft");
+
+          return (
+            <div style={{ display: "grid", gap: "0.75rem" }}>
+              <Badge tone="info">当前：{value}</Badge>
+              <Tabs
+                value={value}
+                onValueChange={setValue}
+                items={[
+                  {
+                    value: "draft",
+                    label: "草稿",
+                    children: "保存还没有发布的内容提纲。",
+                  },
+                  {
+                    value: "review",
+                    label: "审核",
+                    children: "集中查看需要修改或确认的信息。",
+                  },
+                  {
+                    value: "published",
+                    label: "已发布",
+                    children: "展示已经对外可见的内容版本。",
+                  },
+                ]}
+              />
+            </div>
+          );
+        };
+      `,
+      content: <ControlledTabsExample />,
+    },
+    {
+      title: "使用边界",
+      code: `
+        <Badge tone="info">
+          Tabs 用于内容分组；Segmented 用于视图、模式和筛选维度切换。
+        </Badge>;
+      `,
+      content: (
+        <div style={{ display: "grid", gap: "0.75rem", maxWidth: "34rem" }}>
+          <Badge tone="info">Tabs：每个选项对应独立内容面板</Badge>
+          <p style={{ margin: 0, color: "var(--willa-content-muted)" }}>
+            例如安装说明、代码示例、参数解释、多版本内容。若只是切换列表/看板、
+            预览/源码、紧凑/宽松或一组显示开关，使用 Segmented 更合适。
+          </p>
+        </div>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "items",
+      type: "Array<TabsItem>",
+      required: true,
+      description: "标签和面板内容列表。",
+    },
+    {
+      name: "value",
+      type: "string",
+      description: "当前选中的标签值，传入后组件进入受控模式。",
+    },
+    {
+      name: "defaultValue",
+      type: "string",
+      defaultValue: "第一个可用项",
+      description: "非受控模式下的默认选中值。",
+    },
+    {
+      name: "onValueChange",
+      type: "(value: string) => void",
+      description: "选中标签变化时触发。",
+    },
+    {
+      name: "size",
+      type: '"sm" | "md"',
+      defaultValue: '"md"',
+      description: "标签按钮尺寸。",
+    },
+    {
+      name: "ariaLabel",
+      type: "string",
+      defaultValue: '"Tabs"',
+      description: "标签列表的无障碍名称。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "可选的外层 className。",
+    },
+    {
+      name: "TabsItem.icon",
+      type: "ReactNode",
+      group: "TabsItem",
+      description: "展示在标签文案前面的图标。",
+    },
+    {
+      name: "TabsItem.value",
+      type: "string",
+      required: true,
+      group: "TabsItem",
+      description: "标签唯一值。",
+    },
+    {
+      name: "TabsItem.label",
+      type: "ReactNode",
+      required: true,
+      group: "TabsItem",
+      description: "标签按钮内容。",
+    },
+    {
+      name: "TabsItem.children",
+      type: "ReactNode",
+      required: true,
+      group: "TabsItem",
+      description: "标签对应的面板内容。",
+    },
+    {
+      name: "TabsItem.disabled",
+      type: "boolean",
+      group: "TabsItem",
+      description: "是否禁用当前标签。",
+    },
+  ],
+});

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

@@ -0,0 +1,264 @@
+import {
+  CheckCircledIcon,
+  Component1Icon,
+  ReaderIcon,
+} from "@radix-ui/react-icons";
+import { useState } from "react";
+import { Group } from "willa/Group";
+import { Stack } from "willa/Stack";
+import { Tag } from "willa/Tag";
+import "willa/Group.css";
+import "willa/Stack.css";
+import "willa/Tag.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const ClosableTagsPreview = () => {
+  const [tags, setTags] = useState(["React", "MDX", "AI 内容"]);
+
+  return (
+    <Group gap="sm" wrap>
+      {tags.map((tag) => (
+        <Tag
+          key={tag}
+          tone="info"
+          shape="pill"
+          close={{
+            ariaLabel: `移除 ${tag}`,
+            onClose: () =>
+              setTags((currentTags) =>
+                currentTags.filter((currentTag) => currentTag !== tag),
+              ),
+          }}
+        >
+          {tag}
+        </Tag>
+      ))}
+      {tags.length === 0 ? <Tag tone="neutral">暂无标签</Tag> : null}
+    </Group>
+  );
+};
+
+export default defineDoc({
+  id: "tag",
+  name: "Tag",
+  packageName: "willa/Tag",
+  description:
+    "用于内容分类、筛选条件和可移除标签；状态反馈优先使用 Badge，表单录入使用 TagInput。",
+  imports: [
+    { name: "Tag", from: "willa/Tag" },
+    { name: "Group", from: "willa/Group" },
+    { name: "Stack", from: "willa/Stack" },
+  ],
+  css: "willa/Tag.css",
+  demo: {
+    name: "Tag",
+    component: Tag,
+    props: {
+      tone: "info",
+      shape: "pill",
+    },
+    children: "文档",
+  },
+  code: `
+    import { Tag } from "willa/Tag";
+    import "willa/Tag.css";
+
+    <Tag tone="info" shape="pill">
+      文档
+    </Tag>;
+  `,
+  sections: [
+    {
+      title: "基础用法",
+      code: `
+        <Group gap="sm" wrap>
+          <Tag>默认</Tag>
+          <Tag tone="info">文档</Tag>
+          <Tag tone="success">生产可用</Tag>
+          <Tag tone="warning">需复核</Tag>
+          <Tag tone="danger">高风险</Tag>
+        </Group>;
+      `,
+      content: (
+        <Group gap="sm" wrap>
+          <Tag>默认</Tag>
+          <Tag tone="info">文档</Tag>
+          <Tag tone="success">生产可用</Tag>
+          <Tag tone="warning">需复核</Tag>
+          <Tag tone="danger">高风险</Tag>
+        </Group>
+      ),
+    },
+    {
+      title: "视觉类型",
+      code: `
+        <Stack gap="sm">
+          <Group gap="sm" wrap>
+            <Tag tone="info" variant="soft">
+              Soft
+            </Tag>
+            <Tag tone="info" variant="outline">
+              Outline
+            </Tag>
+            <Tag tone="info" variant="solid">
+              Solid
+            </Tag>
+          </Group>
+          <Group gap="sm" wrap>
+            <Tag shape="rounded">圆角</Tag>
+            <Tag shape="pill">胶囊</Tag>
+            <Tag size="sm">小尺寸</Tag>
+            <Tag size="md">中尺寸</Tag>
+          </Group>
+        </Stack>;
+      `,
+      content: (
+        <Stack gap="sm">
+          <Group gap="sm" wrap>
+            <Tag tone="info" variant="soft">
+              Soft
+            </Tag>
+            <Tag tone="info" variant="outline">
+              Outline
+            </Tag>
+            <Tag tone="info" variant="solid">
+              Solid
+            </Tag>
+          </Group>
+          <Group gap="sm" wrap>
+            <Tag shape="rounded">圆角</Tag>
+            <Tag shape="pill">胶囊</Tag>
+            <Tag size="sm">小尺寸</Tag>
+            <Tag size="md">中尺寸</Tag>
+          </Group>
+        </Stack>
+      ),
+    },
+    {
+      title: "图标和选中态",
+      code: `
+        import {
+          CheckCircledIcon,
+          Component1Icon,
+          ReaderIcon,
+        } from "@radix-ui/react-icons";
+
+        <Group gap="sm" wrap>
+          <Tag tone="info" icon={<ReaderIcon />}>
+            文档
+          </Tag>
+          <Tag tone="success" icon={<CheckCircledIcon />}>
+            已采纳
+          </Tag>
+          <Tag tone="neutral" trailingIcon={<Component1Icon />}>
+            组件库
+          </Tag>
+          <Tag tone="info" selected>
+            当前筛选
+          </Tag>
+        </Group>;
+      `,
+      content: (
+        <Group gap="sm" wrap>
+          <Tag tone="info" icon={<ReaderIcon />}>
+            文档
+          </Tag>
+          <Tag tone="success" icon={<CheckCircledIcon />}>
+            已采纳
+          </Tag>
+          <Tag tone="neutral" trailingIcon={<Component1Icon />}>
+            组件库
+          </Tag>
+          <Tag tone="info" selected>
+            当前筛选
+          </Tag>
+        </Group>
+      ),
+    },
+    {
+      title: "可移除标签",
+      code: `
+        const [tags, setTags] = useState(["React", "MDX", "AI 内容"]);
+
+        <Group gap="sm" wrap>
+          {tags.map((tag) => (
+            <Tag
+              key={tag}
+              tone="info"
+              shape="pill"
+              close={{
+                ariaLabel: \`移除 \${tag}\`,
+                onClose: () =>
+                  setTags((currentTags) =>
+                    currentTags.filter((currentTag) => currentTag !== tag),
+                  ),
+              }}
+            >
+              {tag}
+            </Tag>
+          ))}
+        </Group>;
+      `,
+      content: <ClosableTagsPreview />,
+    },
+  ],
+  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: "shape",
+      type: '"rounded" | "pill"',
+      defaultValue: '"rounded"',
+      description: "标签圆角形态。",
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      description: "展示在文字前的图标。",
+    },
+    {
+      name: "trailingIcon",
+      type: "ReactNode",
+      description: "展示在文字后的图标。",
+    },
+    {
+      name: "selected",
+      type: "boolean",
+      defaultValue: "false",
+      description: "是否展示选中态，用于筛选条件或当前分类。",
+    },
+    {
+      name: "close",
+      type: "boolean | { ariaLabel?: string; disabled?: boolean; onClose?: (event: MouseEvent<HTMLButtonElement>) => void }",
+      defaultValue: "false",
+      description: "是否显示移除按钮，传入对象时可配置关闭行为。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "可选的外层 className。",
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "标签内容。",
+    },
+  ],
+});