willa-workspace 0.0.3-alpha.2739b3e

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

@@ -0,0 +1,233 @@
+import { Alert } from "willa/Alert";
+import { Button } from "willa/Button";
+import "willa/Alert.css";
+import "willa/Button.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const alertStackStyle = {
+  display: "grid",
+  gap: "0.85rem",
+} as const;
+
+const alertGridStyle = {
+  display: "grid",
+  gridTemplateColumns: "repeat(auto-fit, minmax(280px, 1fr))",
+  gap: "0.85rem",
+} as const;
+
+export default defineDoc({
+  id: "alert",
+  name: "Alert",
+  packageName: "willa/Alert",
+  description:
+    "用于页面或区块内展示操作结果、异步状态和系统反馈，支持关闭、操作区、横幅和可访问性播报；文档正文里的长文本语义提示优先使用 Callout。",
+  imports: [{ name: "Alert", from: "willa/Alert" }],
+  css: "willa/Alert.css",
+  demo: {
+    name: "Alert",
+    component: Alert,
+    props: {
+      type: "success",
+      showIcon: true,
+      title: "发布成功",
+      description: "内容已保存并进入发布队列，稍后可在任务中心查看处理结果。",
+    },
+  },
+  code: `
+    import { Alert } from "willa/Alert";
+    import "willa/Alert.css";
+
+    <Alert
+      type="success"
+      showIcon
+      title="发布成功"
+      description="内容已保存并进入发布队列，稍后可在任务中心查看处理结果。"
+    />;
+  `,
+  sections: [
+    {
+      title: "语义类型",
+      code: `
+        <div style={{ display: "grid", gap: "0.85rem" }}>
+          <Alert type="info" showIcon title="同步进行中" description="系统正在拉取最新配置，页面数据可能会短暂延迟。" />
+          <Alert type="success" showIcon title="保存完成" description="表单变更已写入服务端，团队成员可以查看最新版本。" />
+          <Alert type="warning" showIcon title="发布窗口即将关闭" description="当前任务仍可继续提交，但建议在截止前完成确认。" />
+          <Alert type="error" showIcon title="提交失败" description="接口返回校验错误，请修复表单中的必填项后重试。" />
+        </div>;
+      `,
+      content: (
+        <div style={alertStackStyle}>
+          <Alert
+            type="info"
+            showIcon
+            title="同步进行中"
+            description="系统正在拉取最新配置，页面数据可能会短暂延迟。"
+          />
+          <Alert
+            type="success"
+            showIcon
+            title="保存完成"
+            description="表单变更已写入服务端，团队成员可以查看最新版本。"
+          />
+          <Alert
+            type="warning"
+            showIcon
+            title="发布窗口即将关闭"
+            description="当前任务仍可继续提交，但建议在截止前完成确认。"
+          />
+          <Alert
+            type="error"
+            showIcon
+            title="提交失败"
+            description="接口返回校验错误，请修复表单中的必填项后重试。"
+          />
+        </div>
+      ),
+    },
+    {
+      title: "操作与关闭",
+      code: `
+        <Alert
+          type="warning"
+          showIcon
+          closable
+          title="版本即将过期"
+          description="当前配置仍可继续使用，但建议在下次发布前完成迁移。"
+          action={<Button size="sm" variant="soft">查看详情</Button>}
+        />;
+      `,
+      content: (
+        <Alert
+          type="warning"
+          showIcon
+          closable
+          title="版本即将过期"
+          description="当前配置仍可继续使用，但建议在下次发布前完成迁移。"
+          action={
+            <Button size="sm" variant="soft">
+              查看详情
+            </Button>
+          }
+        />
+      ),
+    },
+    {
+      title: "横幅提示",
+      code: `
+        <Alert
+          banner
+          showIcon
+          closable={{ closeLabel: "关闭发布提示" }}
+          title="系统将在 22:00 发布更新"
+          description="发布期间部分写入操作可能短暂排队。"
+        />;
+      `,
+      content: (
+        <Alert
+          banner
+          showIcon
+          closable={{ closeLabel: "关闭发布提示" }}
+          title="系统将在 22:00 发布更新"
+          description="发布期间部分写入操作可能短暂排队。"
+        />
+      ),
+    },
+    {
+      title: "视觉样式",
+      code: `
+        <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(280px, 1fr))", gap: "0.85rem" }}>
+          <Alert type="success" variant="outlined" showIcon title="Outlined" description="适合普通页面信息提示。" />
+          <Alert type="success" variant="filled" showIcon title="Filled" description="适合需要更强视觉提示的状态。" />
+        </div>;
+      `,
+      content: (
+        <div style={alertGridStyle}>
+          <Alert
+            type="success"
+            variant="outlined"
+            showIcon
+            title="Outlined"
+            description="适合普通页面信息提示。"
+          />
+          <Alert
+            type="success"
+            variant="filled"
+            showIcon
+            title="Filled"
+            description="适合需要更强视觉提示的状态。"
+          />
+        </div>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "type",
+      type: '"success" | "info" | "warning" | "error"',
+      defaultValue: 'banner ? "warning" : "info"',
+      description: "提示的语义类型，同时影响默认图标、颜色和默认 role。",
+    },
+    {
+      name: "variant",
+      type: '"outlined" | "filled"',
+      defaultValue: '"outlined"',
+      description: "提示的视觉样式。",
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "提示标题。",
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "提示说明内容。",
+    },
+    {
+      name: "action",
+      type: "ReactNode",
+      description: "右侧操作区，常用于放置按钮或链接。",
+    },
+    {
+      name: "banner",
+      type: "boolean",
+      defaultValue: "false",
+      description: "使用横幅样式；未指定 type 时默认使用 warning。",
+    },
+    {
+      name: "showIcon",
+      type: "boolean",
+      defaultValue: "banner 时为 true，否则为 false",
+      description: "是否展示左侧语义图标。",
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      description: "自定义左侧图标，未传时按 type 使用默认图标。",
+    },
+    {
+      name: "closable",
+      type: "boolean | AlertClosableOptions",
+      defaultValue: "false",
+      description:
+        "是否展示关闭按钮；对象形式可配置 closeIcon、closeLabel、onClose 和 afterClose。",
+    },
+    {
+      name: "classes",
+      type: 'Partial<Record<"root" | "icon" | "content" | "title" | "description" | "actions" | "close", string>>',
+      description: "语义槽位 className，用于局部样式扩展。",
+    },
+    {
+      name: "styles",
+      type: 'Partial<Record<"root" | "icon" | "content" | "title" | "description" | "actions" | "close", CSSProperties>>',
+      description: "语义槽位内联样式，用于局部样式扩展。",
+    },
+    {
+      name: "role",
+      type: "ComponentPropsWithoutRef<'div'>['role']",
+      defaultValue: "warning/error 为 alert，其它类型为 status",
+      description: "覆盖根节点可访问性语义。",
+    },
+  ],
+});

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

@@ -0,0 +1,244 @@
+import { unindent } from "aidly";
+import { Anchor } from "willa/Anchor";
+import { Stack } from "willa/Stack";
+import "willa/Anchor.css";
+import "willa/Stack.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const anchorItems = [
+  { id: "anchor-overview", title: "概览" },
+  {
+    id: "anchor-usage",
+    title: "使用方式",
+    children: [
+      { id: "anchor-basic", title: "基础用法" },
+      { id: "anchor-nested", title: "嵌套目录" },
+    ],
+  },
+  { id: "anchor-api", title: "API" },
+];
+
+const AnchorPreview = () => (
+  <div
+    style={{
+      display: "grid",
+      gridTemplateColumns: "14rem minmax(0, 1fr)",
+      gap: "1rem",
+      maxWidth: "48rem",
+    }}
+  >
+    <Anchor items={anchorItems} defaultActiveId="anchor-overview" />
+    <Stack gap="lg">
+      <section id="anchor-overview">
+        <h3>概览</h3>
+        <p>Anchor 适合长文档、配置页和详情页目录。</p>
+      </section>
+      <section id="anchor-usage">
+        <h3>使用方式</h3>
+        <p>点击目录会滚动到对应区域，并同步 active 状态。</p>
+      </section>
+      <section id="anchor-basic">
+        <h3>基础用法</h3>
+        <p>默认使用 #id 定位，也可以给条目传 href。</p>
+      </section>
+      <section id="anchor-nested">
+        <h3>嵌套目录</h3>
+        <p>children 用于展示二级目录。</p>
+      </section>
+      <section id="anchor-api">
+        <h3>API</h3>
+        <p>支持受控 activeId、offsetTop 和点击回调。</p>
+      </section>
+    </Stack>
+  </div>
+);
+
+const navigationItems = [
+  {
+    id: "anchor-nav-ai",
+    title: "PromptInput",
+    meta: "提示词输入",
+    description: "AI 输入、提交和上下文提示。",
+  },
+  {
+    id: "anchor-nav-form",
+    title: "DatePicker",
+    meta: "日期选择器",
+    description: "日期、范围和滚动选择。",
+  },
+  {
+    id: "anchor-nav-layout",
+    title: "Grid",
+    meta: "网格布局",
+    description: "响应式列和间距控制。",
+  },
+];
+
+const NavigationAnchorPreview = () => (
+  <div style={{ width: "min(100%, 22rem)" }}>
+    <Anchor
+      items={navigationItems}
+      defaultActiveId="anchor-nav-ai"
+      variant="navigation"
+    />
+  </div>
+);
+
+export default defineDoc({
+  id: "anchor",
+  name: "Anchor",
+  category: "content",
+  packageName: "willa/Anchor",
+  description: "用于长页面目录导航和锚点定位。",
+  imports: [{ name: "Anchor", from: "willa/Anchor" }],
+  css: "willa/Anchor.css",
+  demo: {
+    name: "AnchorPreview",
+    component: AnchorPreview,
+  },
+  code: unindent(`
+    import { Anchor } from "willa/Anchor";
+    import "willa/Anchor.css";
+
+    const items = [
+      { id: "overview", title: "概览" },
+      {
+        id: "usage",
+        title: "使用方式",
+        children: [{ id: "basic", title: "基础用法" }],
+      },
+    ];
+
+    <Anchor items={items} defaultActiveId="overview" />
+  `),
+  sections: [
+    {
+      title: "导航形态",
+      code: unindent(`
+        import { Anchor } from "willa/Anchor";
+        import "willa/Anchor.css";
+
+        const items = [
+          {
+            id: "prompt-input",
+            title: "PromptInput",
+            meta: "提示词输入",
+            description: "AI 输入、提交和上下文提示。",
+          },
+          {
+            id: "date-picker",
+            title: "DatePicker",
+            meta: "日期选择器",
+            description: "日期、范围和滚动选择。",
+          },
+        ];
+
+        <Anchor
+          items={items}
+          defaultActiveId="prompt-input"
+          variant="navigation"
+        />;
+      `),
+      content: <NavigationAnchorPreview />,
+    },
+  ],
+  props: [
+    {
+      name: "items",
+      type: "Array<AnchorItem>",
+      required: true,
+      description: "目录项。",
+    },
+    { name: "activeId", type: "string", description: "受控激活项 id。" },
+    { name: "defaultActiveId", type: "string", description: "默认激活项 id。" },
+    {
+      name: "offsetTop",
+      type: "number",
+      defaultValue: "0",
+      description: "滚动监听时距离视口顶部的偏移。",
+    },
+    {
+      name: "size",
+      type: '"sm" | "md"',
+      defaultValue: '"md"',
+      description: "尺寸。",
+    },
+    {
+      name: "variant",
+      type: '"toc" | "navigation"',
+      defaultValue: '"toc"',
+      description: "展示形态。toc 用于正文目录，navigation 用于侧边导航列表。",
+    },
+    {
+      name: "sticky",
+      type: "boolean",
+      defaultValue: "false",
+      description: "是否使用 sticky 定位。",
+    },
+    {
+      name: "showMarker",
+      type: "boolean",
+      defaultValue: "true",
+      description: "是否显示激活标记。",
+    },
+    {
+      name: "classNames",
+      type: "Partial<Record<AnchorSlot, string>>",
+      description: "按语义槽位追加 className，用于定制局部样式。",
+    },
+    {
+      name: "styles",
+      type: "Partial<Record<AnchorSlot, CSSProperties>>",
+      description: "按语义槽位追加内联样式，用于轻量定制。",
+    },
+    {
+      name: "onActiveChange",
+      type: "(id: string) => void",
+      description: "激活项变化回调。",
+    },
+    {
+      name: "onItemClick",
+      type: "(item: AnchorItem, event: MouseEvent<HTMLAnchorElement>) => void",
+      description: "目录项点击回调。",
+    },
+    {
+      name: "AnchorItem.id",
+      type: "string",
+      required: true,
+      group: "AnchorItem",
+      description: "锚点项唯一标识，也作为默认 href 的目标 id。",
+    },
+    {
+      name: "AnchorItem.title",
+      type: "ReactNode",
+      required: true,
+      group: "AnchorItem",
+      description: "锚点主标题。",
+    },
+    {
+      name: "AnchorItem.description",
+      type: "ReactNode",
+      group: "AnchorItem",
+      description: "导航形态下的补充说明。",
+    },
+    {
+      name: "AnchorItem.meta",
+      type: "ReactNode",
+      group: "AnchorItem",
+      description: "导航形态下显示在右侧的辅助信息。",
+    },
+    {
+      name: "AnchorItem.href",
+      type: "string",
+      group: "AnchorItem",
+      description: "自定义链接。不传时使用 #id。",
+    },
+    {
+      name: "AnchorItem.children",
+      type: "Array<AnchorItem>",
+      group: "AnchorItem",
+      description: "子级锚点项。",
+    },
+  ],
+});

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

@@ -0,0 +1,192 @@
+import { Badge } from "willa/Badge";
+import { Button } from "willa/Button";
+import { AppShell } from "willa/AppShell";
+import { Panel } from "willa/Panel";
+import { Stack } from "willa/Stack";
+import "willa/AppShell.css";
+import "willa/Badge.css";
+import "willa/Button.css";
+import "willa/Panel.css";
+import "willa/Stack.css";
+
+import { defineDoc } from "#example/catalog/defineDoc";
+
+const shellNavStyle = {
+  display: "grid",
+  gap: "0.45rem",
+  color: "var(--willa-text-soft)",
+} as const;
+
+export default defineDoc({
+  id: "app-shell",
+  name: "AppShell",
+  category: "layout",
+  packageName: "willa/AppShell",
+  description: "用于产品级页面骨架，组合顶栏、侧栏、主内容、辅助栏和底部区域。",
+  imports: [
+    { name: "AppShell", from: "willa/AppShell" },
+    { name: "Panel", from: "willa/Panel" },
+    { name: "Stack", from: "willa/Stack" },
+    { name: "Button", from: "willa/Button" },
+    { name: "Badge", from: "willa/Badge" },
+  ],
+  css: "willa/AppShell.css",
+  demo: {
+    name: "AppShell",
+    component: AppShell,
+    props: {
+      header: "Willa",
+      sidebar: "导航",
+      aside: "详情",
+    },
+    children: "工作区",
+  },
+  code: `
+    import { AppShell } from "willa/AppShell";
+    import "willa/AppShell.css";
+
+    <AppShell header="Willa" sidebar="导航" aside="详情">
+      工作区
+    </AppShell>;
+  `,
+  sections: [
+    {
+      title: "产品骨架",
+      code: `
+        <AppShell
+          header={
+            <strong>Willa Console</strong>
+          }
+          sidebar={
+            <div style={{ display: "grid", gap: "0.45rem", color: "var(--willa-text-soft)" }}>
+              <span>概览</span>
+              <span>组件</span>
+              <span>设置</span>
+            </div>
+          }
+          aside={
+            <Stack gap="sm">
+              <Badge tone="info">当前项目</Badge>
+              <span>产品反馈分析</span>
+            </Stack>
+          }
+          footer="当前工作区会保存上下文和最近操作。"
+        >
+          <Panel
+            title="组件工作台"
+            description="集中展示任务、组件状态和配置入口。"
+            actions={<Button size="sm">新建任务</Button>}
+          >
+            已同步 12 个组件状态。
+          </Panel>
+        </AppShell>;
+      `,
+      content: (
+        <AppShell
+          header={<strong>Willa Console</strong>}
+          sidebar={
+            <div style={shellNavStyle}>
+              <span>概览</span>
+              <span>组件</span>
+              <span>设置</span>
+            </div>
+          }
+          aside={
+            <Stack gap="sm">
+              <Badge tone="info">当前项目</Badge>
+              <span>产品反馈分析</span>
+            </Stack>
+          }
+          footer="当前工作区会保存上下文和最近操作。"
+        >
+          <Panel
+            title="组件工作台"
+            description="集中展示任务、组件状态和配置入口。"
+            actions={<Button size="sm">新建任务</Button>}
+          >
+            已同步 12 个组件状态。
+          </Panel>
+        </AppShell>
+      ),
+    },
+    {
+      title: "无辅助栏",
+      code: `
+        <AppShell
+          header="文档工作台"
+          sidebar={<Stack gap="xs"><span>开始</span><span>组件</span></Stack>}
+        >
+          <Panel title="文档内容">适合文档站和设置页的基础框架。</Panel>
+        </AppShell>;
+      `,
+      content: (
+        <AppShell
+          header="文档工作台"
+          sidebar={
+            <Stack gap="xs">
+              <span>开始</span>
+              <span>组件</span>
+            </Stack>
+          }
+        >
+          <Panel title="文档内容">适合文档站和设置页的基础框架。</Panel>
+        </AppShell>
+      ),
+    },
+  ],
+  props: [
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "主内容。",
+    },
+    {
+      name: "header",
+      type: "ReactNode",
+      description: "顶部区域。",
+    },
+    {
+      name: "sidebar",
+      type: "ReactNode",
+      description: "左侧栏内容。",
+    },
+    {
+      name: "aside",
+      type: "ReactNode",
+      description: "右侧辅助区域。",
+    },
+    {
+      name: "footer",
+      type: "ReactNode",
+      description: "底部区域。",
+    },
+    {
+      name: "sidebarWidth",
+      type: "string",
+      defaultValue: '"16rem"',
+      description: "侧栏宽度。",
+    },
+    {
+      name: "asideWidth",
+      type: "string",
+      defaultValue: '"18rem"',
+      description: "辅助栏宽度。",
+    },
+    {
+      name: "stickyHeader",
+      type: "boolean",
+      defaultValue: "false",
+      description: "顶部区域是否吸顶。",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "自定义 className。",
+    },
+    {
+      name: "minContentWidth",
+      type: "string",
+      description: "最小内容宽度。",
+    },
+  ],
+});