",
+ " ",
+ " {platform === \"macos\" && }",
+ "
",
+ " ",
+ " {center}",
+ "
",
+ " {platform === \"windows\" && }",
+ " ",
+ ");",
+].join("\n");
+
+/**
+ * React / 现状 — File=DesktopTitlebar：现在的样子，React 组件当普通函数：输入参数一格塞整个解构、类型一格塞整个类型字面量，
+ * 输出参数「未标注」；两个钩子、一个派生值是普通变量块，返回的 JSX 是一整段译文。
+ */
+function currentTitlebar(ctx) {
+ const node = frame(ctx, "File=DesktopTitlebar", { component: true, width: TREE_W, gap: 8 });
+ const { content } = cardShell(ctx, "Block / L12", BLOCK_KINDS.function, { parent: node, kids: true });
+ propRow(ctx, content, "名称", [{ text: TITLEBAR_CARD.name, color: COLORS.tokenFunction }]);
+ propRow(ctx, content, "说明", [{ text: TITLEBAR_CARD.doc, color: COLORS.comment }]);
+ propRow(ctx, content, "访问级别", [{ text: "公共", color: COLORS.tokenControl }]);
+ propRow(ctx, content, "异步", yesNo(false));
+ propRow(ctx, content, "输入参数", countSegments(["{ platform }"]), { twisty: true });
+ paramRows(ctx, content, [{ name: "{ platform }", type: '{ platform: DesktopShell["platform"] }', value: "" }], "typescript");
+ propRow(ctx, content, "输出参数", [{ text: "未标注", color: COLORS.desc }]);
+ const { list } = levelList(ctx, node, "Children / L12");
+ for (const [line, name, value] of TITLEBAR_BODY) {
+ const { content: body } = cardShell(ctx, `Block / L${line}`, BLOCK_KINDS.variable, { parent: list });
+ propRow(ctx, body, "名称", [{ text: name, color: COLORS.tokenVariable }]);
+ propRow(ctx, body, "初始值", tsSegments(value));
+ }
+ const { content: returned } = cardShell(ctx, "Block / L17", BLOCK_KINDS.return, { parent: list });
+ richText(ctx, returned, "Plain", tsSegments(TITLEBAR_JSX));
+ return node;
+}
+
+/** Explorer / ReactSidebar — File=titlebar：侧栏，luffy 的目录展开到两个示例文件，DesktopTitlebar.tsx 选中；行和主画板同一套。 */
+function reactSidebar(ctx, lib) {
+ const node = frame(ctx, "File=titlebar", { component: true, width: SIDEBAR_W, height: MAIN_H, fill: COLORS.side });
+ node.clipsContent = true;
+ node.overflowDirection = "VERTICAL";
+ const header = lib.explorerHeader.get("default").createInstance();
+ header.name = "Header";
+ append(node, header, true);
+ rootRow(ctx, node, REACT_ROOT, 0);
+ treeRows(ctx, node, lib, REACT_TREE, "titlebar");
+ return node;
+}
+
+/** Reader / FilterBar — File=titlebar：预览顶部的筛选栏，这个文件里出现过的属性各一个下拉框，右边块数。 */
+function reactFilterBar(ctx, lib) {
+ const node = frame(ctx, "File=titlebar", { component: true, dir: "HORIZONTAL", width: TREE_W, height: FILTER_BAR_H, gap: 8, align: "CENTER" });
+ filterLabel(ctx, node);
+ for (const facet of ["种类", "访问级别", "仅类型"]) {
+ const chip = append(node, lib.filterChip.get("default").createInstance());
+ chip.name = `Chip / ${facet}`;
+ setText(chip, "Text", facet);
+ }
+ append(node, frame(ctx, "Spacer", { width: 10, height: 1 }), true);
+ text(ctx, node, "Summary", `共 ${TITLEBAR_IMPORTS.length + 1} 块`, { hug: true, size: 12, lineHeight: 16, color: COLORS.desc });
+ return node;
+}
+
+/** Prototype / React 组件 · 简单：编辑器全貌，侧栏 DesktopTitlebar.tsx 选中，预览里五条导入后面是它的 React 组件卡片。 */
+function reactWindow(ctx, page, lib) {
+ const name = "React 组件 · 简单";
+ return timed(`Prototype / ${name}`, () => {
+ const { screen, editor, side } = windowShell(ctx, page, lib, name, { mode: "preview", file: REACT_FILES.titlebar, root: REACT_ROOT, crumbs: "titlebar",
+ sidebar: (main) => {
+ const pane = lib.reactSidebar.get("titlebar").createInstance();
+ pane.name = "Sidebar";
+ append(main, pane);
+ pane.layoutSizingVertical = "FILL";
+ return pane;
+ } });
+ const row = filled(ctx, editor, "Filter row", { align: "CENTER", px: VIEW_PAD, fill: COLORS.editor });
+ row.strokes = paint(COLORS.border);
+ row.strokeBottomWeight = 1;
+ row.strokeTopWeight = row.strokeLeftWeight = row.strokeRightWeight = 0;
+ const bar = lib.reactFilter.get("titlebar").createInstance();
+ bar.name = "Filter bar";
+ append(row, bar);
+ const view = filled(ctx, editor, "Preview view", { align: "CENTER", px: VIEW_PAD });
+ view.layoutSizingVertical = "FILL";
+ view.clipsContent = true;
+ view.overflowDirection = "VERTICAL";
+ const tree = append(view, frame(ctx, `Block tree / ${REACT_FILES.titlebar.name}`, { width: TREE_W, py: 20, fill: COLORS.editor }));
+ const { list } = levelList(ctx, tree, "Level 0");
+ const blocks = [...TITLEBAR_IMPORTS.map(([line]) => [line, lib.titlebarBlocks.get(line)]), [TITLEBAR_CARD.line, lib.reactCards.get(TITLEBAR_CARD.name)]];
+ for (const [line, component] of blocks) {
+ const instance = component.createInstance();
+ instance.name = `Block / L${line}`;
+ append(list, instance, true);
+ }
+ return { screen, sidebar: side, view, tree };
+ });
+}
+
+/** 只放卡片的画板（和主画板的库规则画板一样宽）。 */
+function cardBoard(ctx, page, name, components) {
+ const board = frame(ctx, name, { width: TREE_W + 2 * VIEW_PAD, pad: VIEW_PAD, gap: 8, fill: COLORS.editor });
+ page.appendChild(board);
+ for (const [blockName, component] of components) {
+ const instance = component.createInstance();
+ instance.name = blockName;
+ append(board, instance, true);
+ }
+ return board;
+}
+
+// 说明板上的例子，都照抄 luffy 的真实写法：
+// ShareButton（components/share/ShareButton.tsx）的属性里有回调；StepLabel（referral/components/poster/PosterDialog.tsx）的属性里有 children
+const SHARE_PROPS = { rows: [
+ { name: "open", type: "boolean", required: true },
+ { name: "onOpenChange", type: "(next: boolean) => void", required: true, role: "callback" },
+ { name: "deployUrl", type: "string | null", required: true, doc: "已发布的持久 URL; null = 尚未发布 (点击后由父组件驱动发布)。" },
+ { name: "sessionId", type: "string", required: true },
+ { name: "title", type: "string", required: true },
+] };
+const STEP_LABEL_PROPS = { rows: [{ name: "n", type: "number", required: true }, { name: "children", type: "ReactNode", required: true, role: "children" }] };
+// 钩子 → 分区：[写法, 放进, 怎么画]
+const REACT_HOOK_SECTIONS = [
+ ["[f|useState] / [f|useReducer]", "状态", "名称 / 初始值 / 改它的"],
+ ["[f|useRef]", "引用", "名称 / 初始值 / 用在"],
+ ["[f|useContext]、自定义钩子 [f|useXxx]", "读取的数据", "变量 / 来自 / 意思，调用读成中文：[f|useDesktopShell](([v|s]) => [v|s].[v|title]) → 从 desktop store 读 [v|title]"],
+ ["组件体里的常量、[f|useMemo] / [f|useCallback]", "派生值", "名称 / 怎么算 / 什么时候算，用中文读出来；useMemo / useCallback 写依赖"],
+ ["[f|useEffect] / [f|useLayoutEffect]", "副作用", "每个一张子卡片：时机 / 做什么 / 清理"],
+ ["组件里定义的函数", "事件处理", "名称 / 绑定在 / 做什么，点名称展开子卡片"],
+ ["[k|return] 的 JSX", "渲染", "缩进的结构大纲，写法见下"],
+];
+// 副作用的时机按依赖数组读
+const EFFECT_TIMINGS = [["[[v|doc], [v|headings]]", "[v|doc]、[v|headings] [k|变了时]"], ["[]", "[k|只在挂载时]"], ["[d|不写]", "[k|每次渲染后]"]];
+// 渲染大纲的写法各一段：DesktopTitlebar 的一行原生标签和组件、DeleteAppDialog（components/apps）的三元和列表、
+// DesktopSettingsDialog（components/desktop）的提前返回、AppVaultSummary（app/(main)/chat/code）的片段
+const OUTLINE_TAGS = [
+ { el: "span", cls: "max-w-[40vw] truncate font-medium text-foreground", text: "[d|{][v|center][d|}]" },
+ { el: "WindowControls", comp: true },
+];
+const OUTLINE_WHEN = [{ when: '[v|platform] [k|是] [q|"windows"]', el: "WindowControls", comp: true }];
+const OUTLINE_TERNARY = [{ el: "Button", comp: true, attrs: '[v|variant]=[q|"destructive"] [v|onClick]=[d|() => ][v|remove].[f|mutate]() [v|disabled]=[s|非] [v|ready] [s|或者] [v|pending]', kids: [
+ { ternary: "[v|pending]", yes: [{ text: '[q|"删除中…"]' }], no: [{ text: '[q|"确认删除并清空数据"]' }] },
+] }];
+const OUTLINE_LIST = [{ el: "ul", cls: "flex flex-col gap-2 text-[13px] text-foreground", kids: [
+ { each: "[v|losses]", item: "{ [v|icon]: [r|Icon], [v|text] }", key: "[v|text]", kids: [
+ { el: "li", cls: "flex items-start gap-2", kids: [
+ { el: "Icon", comp: true, cls: "mt-0.5 shrink-0 text-destructive", attrs: "[v|size]=[n|14]" },
+ { el: "span", text: "[d|{][v|text][d|}]" },
+ ] },
+ ] },
+] }];
+const OUTLINE_RETURNS = [
+ { when: "[v|section] [k|没有值]", none: true },
+ { when: null, nodes: [{ el: "Dialog", comp: true, attrs: "[v|open] [v|onOpenChange]=[d|(next) => ][s|非] [v|next] [s|并且] [f|closeSettings]()", kids: [
+ { el: "DialogContent", comp: true, cls: "h-[560px] overflow-hidden p-0 sm:max-w-[880px]", kids: [{ more: "Tabs：左边分页列表，右边 4 个分页" }] },
+ ] }] },
+];
+const OUTLINE_FRAGMENT = [{ frag: true, kids: [
+ { el: "SettingHeader", comp: true, attrs: '[v|compact] [v|align]=[q|"center"] [v|title]=[q|"密钥与变量"] [v|right]=[r|]' },
+ { when: "[v|effective].[v|length] > [n|0]", el: "ul", cls: "mt-2 space-y-1", kids: [
+ { each: "[v|effective]", item: "{ [v|item], [v|label] }", key: "[v|item].[v|id]", kids: [{ more: "li：名字和来源" }] },
+ ] },
+] }];
+
+/**
+ * Prototype / React 组件 · 标记说明：名称行的小标签、属性表的「来自 / 回调 / 子元素」、钩子和分区的对应、副作用的时机、
+ * 渲染大纲的各种写法（原生标签和组件、样式小标、条件、三元、列表、提前返回、片段、注释），每样一句短说明，下面是例子。
+ */
+function reactLegend(ctx, page) {
+ const board = frame(ctx, "Prototype / React 组件 · 标记说明", { width: TREE_W + 2 * VIEW_PAD, pad: VIEW_PAD, gap: 10, fill: COLORS.editor });
+ page.appendChild(board);
+ const section = (title) => text(ctx, board, `Section / ${title}`, title, { medium: true, size: 14, lineHeight: 30, color: COLORS.fgStrong });
+ const sample = (name, draw) => {
+ const box = filled(ctx, board, `Sample / ${name}`, { pad: 10, gap: 3, radius: 6, stroke: COLORS.border });
+ draw(box);
+ return box;
+ };
+ section("名称行的小标签");
+ legendNote(ctx, board, COLORS.tokenControl, "具名导出", "export const DesktopTitlebar = …，别处按这个名字导入");
+ legendNote(ctx, board, COLORS.tokenControl, "默认导出", "export default function RootPage()（app/page.tsx），导入时自己起名");
+ legendNote(ctx, board, COLORS.component, "客户端组件", "文件顶部写了 \"use client\"，这一行不再单独成块");
+ legendNote(ctx, board, COLORS.tokenStorage, "记忆化", "memo(…) 包着：属性没变就不重新渲染");
+ legendNote(ctx, board, COLORS.tokenStorage, "转发 ref", "forwardRef(…) 包着：父组件传的 ref 直接拿到它里面的元素");
+ sample("名称行", (box) => {
+ reactNameRow(ctx, box, "DesktopTitlebar", ["具名导出", "客户端组件"]);
+ reactNameRow(ctx, box, "PosterCanvas", ["具名导出", "客户端组件", "转发 ref"]);
+ });
+ section("属性");
+ legendNote(ctx, board, null, "来自", "props 用接口或类型别名声明时展开它的字段，「属性」后面写来自哪个类型（LegalDocPage 来自 LegalDocPageProps）");
+ legendNote(ctx, board, COLORS.component, "回调", "onXxx 这类函数属性，类型写成函数签名（ShareButton 的 onOpenChange）");
+ legendNote(ctx, board, COLORS.component, "子元素", "children（PosterDialog 里的 StepLabel）");
+ sample("属性表", (box) => {
+ reactNameRow(ctx, box, "ShareButton", ["具名导出", "客户端组件"]);
+ reactProps(ctx, box, SHARE_PROPS);
+ reactNameRow(ctx, box, "StepLabel", []);
+ reactProps(ctx, box, STEP_LABEL_PROPS);
+ });
+ section("钩子放进哪个分区");
+ propTable(ctx, board, "Hooks", [["写法", 260], ["放进", 100], ["怎么画", 0]], REACT_HOOK_SECTIONS.map(([hook, part, how]) =>
+ [`Hook / ${part}`, [rich(hook), [{ text: part, color: COLORS.fgStrong }], rich(how)]]));
+ legendNote(ctx, board, EFFECT_KIND.color, "时机", "副作用按依赖数组读时机");
+ propTable(ctx, board, "Timings", [["依赖", 260], ["读成", 0]], EFFECT_TIMINGS.map(([deps, reading], index) => [`Timing / ${index + 1}`, [rich(deps), rich(reading)]]));
+ section("渲染大纲的写法");
+ legendNote(ctx, board, null, "标签和组件", "每行一个元素：div、span 这类原生标签灰色；组件用组件色，Cmd+单击跳到它的定义");
+ sample("标签和组件", (box) => outlineLevel(ctx, box, OUTLINE_TAGS));
+ legendNote(ctx, board, null, "样式", "长的 className 收成「样式 N 个类」，点开看全部类名，再点收起；按条件切换的写「随 X 变」");
+ sample("样式", (box) => {
+ // 下面那个是点开的样子，弹出的类名占着下面的留白
+ box.paddingBottom = 110;
+ box.itemReverseZIndex = true;
+ for (const [node, state] of [[TITLEBAR_CARD.render[0], "closed"], [LEGAL_HEADER.kids[2].kids[0], "open"]]) {
+ const line = outlineLine(ctx, box, `Line / ${node.el}`);
+ richText(ctx, line, "Element", [{ text: node.el }], { hug: true, color: node.comp ? COLORS.component : COLORS.nativeTag });
+ styleChipInstance(ctx, line, node.cls, state);
+ richText(ctx, line, "Attrs", rich(node.attrs), { hug: true });
+ }
+ });
+ legendNote(ctx, board, BLOCK_KINDS.if.color, "条件", "cond && 写成前缀「当 … 时」（DesktopTitlebar）");
+ sample("条件", (box) => outlineLevel(ctx, box, OUTLINE_WHEN));
+ legendNote(ctx, board, BLOCK_KINDS.if.color, "三元", "a ? X : Y 写成「如果 a」，下面「是 / 否」两支（DeleteAppDialog 的删除按钮）");
+ sample("三元", (box) => outlineLevel(ctx, box, OUTLINE_TERNARY));
+ legendNote(ctx, board, BLOCK_KINDS.loop.color, "列表", "items.map(…) 写成「对 items 的每一项」，后面标出 key，下面缩进每一项渲染的元素（DeleteAppDialog）");
+ sample("列表", (box) => outlineLevel(ctx, box, OUTLINE_LIST));
+ legendNote(ctx, board, BLOCK_KINDS.return.color, "提前返回", "先 return null 写成「当 … 时 不渲染」；有几个 return 就分几段，各带条件（DesktopSettingsDialog）");
+ sample("提前返回", (box) => outlineReturns(ctx, box, OUTLINE_RETURNS));
+ legendNote(ctx, board, null, "片段", "<>… 写成一行「片段」，不产生元素，子元素照常缩进（AppVaultSummary）");
+ sample("片段", (box) => outlineLevel(ctx, box, OUTLINE_FRAGMENT));
+ legendNote(ctx, board, COLORS.comment, "注释", "JSX 里的 {/* … */} 照写成一行注释（LegalDocPage）");
+ return board;
+}
+
+/** Prototype / React 组件 · 对照：左边是现在当普通函数的样子，右边是 React 组件卡片，各自上面一行标题。 */
+function reactCompare(ctx, page, lib) {
+ const board = frame(ctx, "Prototype / React 组件 · 对照", { dir: "HORIZONTAL", pad: VIEW_PAD, gap: 40, fill: COLORS.editor });
+ page.appendChild(board);
+ for (const [key, heading, component] of [["Now", "现在：当普通函数", lib.current.get("DesktopTitlebar")],
+ ["New", "改后：React 组件卡片", lib.reactCards.get(TITLEBAR_CARD.name)]]) {
+ const column = append(board, frame(ctx, `Column / ${key}`, { width: TREE_W, gap: 10 }));
+ text(ctx, column, "Heading", heading, { medium: true, size: 14, lineHeight: 30, color: COLORS.fgStrong });
+ const instance = component.createInstance();
+ instance.name = `Block / ${key}`;
+ append(column, instance, true);
+ }
+ return board;
+}
+
+/** 插件菜单「React 组件」：一页，只建用得到的组件；编辑器全貌、复杂组件、对照、标记说明四张画板。 */
+async function buildReactPage(ctx, api, page, stage) {
+ stage("生成组件");
+ const sets = [];
+ const lib = {};
+ ctx.lib = lib;
+ const make = setMaker(ctx, page, sets);
+ lib.toggle = make("Reader / ModeToggle", MODES, 2, (mode) => modeToggle(ctx, mode));
+ lib.tools = make("Reader / BlockTools", MODES.slice().reverse(), 2, (state) => blockToolsComponent(ctx, state));
+ lib.filterChip = make("Reader / FilterChip", ["default"], 1, (state) => filterChip(ctx, state));
+ lib.reactFilter = make("Reader / FilterBar", ["titlebar"], 1, () => reactFilterBar(ctx, lib));
+ lib.styleChip = make("React / StyleChip", ["closed", "open"], 2, (state) => styleChip(ctx, state));
+ lib.effects = make("React / 副作用", LEGAL_EFFECTS.flatMap((effect) => ["open", "closed"].map((state) => `${effect.key}/${state}`)), 2, (entry) => {
+ const [key, state] = entry.split("/");
+ return effectCard(ctx, LEGAL_EFFECTS.find((effect) => effect.key === key), state);
+ }, (item) => item.node);
+ lib.handlers = make("React / 事件处理", ["none", ...LEGAL_HANDLERS.map((handler) => handler.name)], 1, (open) => handlerTable(ctx, LEGAL_HANDLERS, open), (item) => item.node);
+ lib.titlebarBlocks = make(`React / ${REACT_FILES.titlebar.name}`, TITLEBAR_IMPORTS.map(([line]) => line), 2,
+ (line) => reactImportCard(ctx, TITLEBAR_IMPORTS.find((entry) => entry[0] === line)));
+ lib.reactCards = make("React / 组件卡片", REACT_CARDS.map((card) => card.name), 2, (name) => reactCard(ctx, lib, REACT_CARDS.find((card) => card.name === name)));
+ lib.current = make("React / 现状", ["DesktopTitlebar"], 1, () => currentTitlebar(ctx));
+ lib.row = make("Explorer / TreeRow", REACT_ROW_VARIANTS, 2, (entry) => treeRow(ctx, ...entry.split("/")));
+ lib.explorerHeader = make("Explorer / Header", ["default"], 1, (state) => explorerHeader(ctx, state));
+ lib.reactSidebar = make("Explorer / ReactSidebar", ["titlebar"], 1, () => reactSidebar(ctx, lib));
+ lib.windowTitle = make("Window / TitleBar", ["active"], 1, () => windowTitle(ctx));
+ lib.activity = make("Window / ActivityBar", ["reader"], 1, () => activityBar(ctx));
+ lib.status = make("Window / StatusBar", ["preview"], 1, (mode) => statusBar(ctx, mode));
+ lib.editorTitle = make("Editor / TitleBar", ["preview"], 1, (mode) => editorTitle(ctx, lib, mode));
+ lib.breadcrumb = make("Editor / Breadcrumb", ["titlebar"], 1, (key) => breadcrumb(ctx, key, REACT_FILES.titlebar));
+
+ stage("生成演示画板");
+ const simple = reactWindow(ctx, page, lib);
+ const complex = timed("Prototype / React 组件 · 复杂", () => cardBoard(ctx, page, "Prototype / React 组件 · 复杂",
+ [[`Block / L${LEGAL_CARD.line}`, lib.reactCards.get(LEGAL_CARD.name)]]));
+ const compare = timed("Prototype / React 组件 · 对照", () => reactCompare(ctx, page, lib));
+ const legend = timed("Prototype / React 组件 · 标记说明", () => reactLegend(ctx, page));
+
+ stage("连接演示入口");
+ // 都连在组件里，各处实例都能点：「样式」小标点开 / 收起；副作用子卡片的折叠箭头；事件处理表点名称展开 / 换一个 / 收起，子卡片的折叠箭头收起。
+ // 窗口里侧栏点 LegalDocPage.tsx → 复杂组件那张。
+ const wires = [];
+ const link = (...args) => { wires.push(connect(...args)); };
+ link(lib.styleChip.get("closed"), lib.styleChip.get("open"), "CHANGE_TO");
+ link(lib.styleChip.get("open"), lib.styleChip.get("closed"), "CHANGE_TO");
+ for (const effect of LEGAL_EFFECTS) {
+ const open = lib.effects.get(`${effect.key}/open`);
+ const closed = lib.effects.get(`${effect.key}/closed`);
+ link(open.toggle, closed.node, "CHANGE_TO");
+ link(closed.toggle, open.node, "CHANGE_TO");
+ }
+ for (const [open, variant] of lib.handlers) {
+ for (const [name, cell] of variant.names) link(cell, lib.handlers.get(name === open ? "none" : name).node, "CHANGE_TO");
+ if (variant.fold) link(variant.fold, lib.handlers.get("none").node, "CHANGE_TO");
+ }
+ link(named(simple.sidebar, "Row / LegalDocPage.tsx"), complex, "NAVIGATE");
+ await Promise.all(wires);
+
+ stage("排布画板");
+ const screens = [simple.screen, complex, compare, legend];
+ let y = 0;
+ for (const screen of screens) {
+ screen.x = 0;
+ screen.y = y;
+ y += screen.height + 120;
+ }
+ const setX = Math.max(...screens.map((screen) => screen.width)) + 160;
+ let setY = 0;
+ for (const set of sets) {
+ set.x = setX;
+ set.y = setY;
+ setY += set.height + 64;
+ }
+ page.flowStartingPoints = [{ nodeId: simple.screen.id, name: "React 组件" }, { nodeId: complex.id, name: "React 组件 · 复杂" }];
+ for (const node of page.children) node.expanded = false;
+ api.viewport.scrollAndZoomIntoView([simple.screen]);
+ return { clock, page, components: { lib, sets }, board: simple.screen, boards: { simple, complex, compare, legend }, screens, start: simple.screen.name };
+}
+
// ─── Entry ───────────────────────────────────────────────────────────────────
-/** command：插件菜单里点的哪一项，main = 主画板，diff = 代码差异，其余见 SCRIPT_PAGES（shell、docker）。 */
+// 插件菜单里自己一页、自己一套画法的几项；shell、docker 共用一套画法，见 SCRIPT_PAGES
+const OWN_PAGES = { diff: { page: DIFF_PAGE_NAME, build: buildDiffPage }, react: { page: REACT_PAGE_NAME, build: buildReactPage } };
+
+/** command：插件菜单里点的哪一项，main = 主画板，diff = 代码差异，react = React 组件，其余见 SCRIPT_PAGES（shell、docker）。 */
async function build(api, stage = () => {}, command = "main") {
clock = new Map();
stage("加载中文字体");
const ctx = { api, fonts: await chooseFonts(api) };
stage("新建独立页面");
- const name = nextPageName(api.root.children, command === "diff" ? DIFF_PAGE_NAME : SCRIPT_PAGES[command] ? SCRIPT_PAGES[command].page : PAGE_NAME);
+ const own = OWN_PAGES[command];
+ const name = nextPageName(api.root.children, own ? own.page : SCRIPT_PAGES[command] ? SCRIPT_PAGES[command].page : PAGE_NAME);
const page = api.createPage();
page.name = name;
await api.setCurrentPageAsync(page);
page.backgrounds = paint("#111214");
page.setSharedPluginData(NAMESPACE, "generator", GENERATOR);
- if (command === "diff") return buildDiffPage(ctx, api, page, stage);
+ if (own) return own.build(ctx, api, page, stage);
if (SCRIPT_PAGES[command]) return buildScriptPage(ctx, api, page, stage, command);
stage("生成组件");
@@ -3707,6 +4571,6 @@ async function run(api) {
}
if (typeof module !== "undefined") {
- module.exports = { DIFF_PAGE_NAME, DIFF_BLOCKS, DIFF_COLORS, DIFF_SAMPLE, UNCOMMITTED_GROUPS, diffParts, diffStatsText, NEXT_DOCKERFILE, BACKEND_DOCKERFILE, DOCKER_PAGE_NAME, SHELL_BLOCKS, SHELL_PAGE_NAME, NESTED_CALL_SAMPLE, parseCall, ROUTER_SAMPLE, ROUTE_SAMPLE, REVIEW, REVIEW_ISSUES, ASK_SAMPLE, BEAT_SCHEDULE, ENUM_SAMPLE, SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, blockAttributes, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, parseImport, parseVariable, translateCode, build, run, nextPageName, PAGE_NAME, NAMESPACE, TREE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, typeSegments };
+ module.exports = { REACT_PAGE_NAME, REACT_CARDS, TITLEBAR_CARD, LEGAL_CARD, LEGAL_EFFECTS, LEGAL_HANDLERS, TITLEBAR_IMPORTS, REACT_TREE, EXTRA_KINDS, DIFF_PAGE_NAME, DIFF_BLOCKS, DIFF_COLORS, DIFF_SAMPLE, UNCOMMITTED_GROUPS, diffParts, diffStatsText, NEXT_DOCKERFILE, BACKEND_DOCKERFILE, DOCKER_PAGE_NAME, SHELL_BLOCKS, SHELL_PAGE_NAME, NESTED_CALL_SAMPLE, parseCall, ROUTER_SAMPLE, ROUTE_SAMPLE, REVIEW, REVIEW_ISSUES, ASK_SAMPLE, BEAT_SCHEDULE, ENUM_SAMPLE, SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, blockAttributes, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, parseImport, parseVariable, translateCode, build, run, nextPageName, PAGE_NAME, NAMESPACE, TREE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, typeSegments };
}
if (typeof figma !== "undefined") void run(figma);
diff --git a/docs/prototype/code-reader/figma-plugin/manifest.json b/docs/prototype/code-reader/figma-plugin/manifest.json
index 72ec024..d67e618 100644
--- a/docs/prototype/code-reader/figma-plugin/manifest.json
+++ b/docs/prototype/code-reader/figma-plugin/manifest.json
@@ -27,6 +27,10 @@
{
"name": "代码差异",
"command": "diff"
+ },
+ {
+ "name": "React 组件",
+ "command": "react"
}
]
}
diff --git a/docs/prototype/code-reader/figma-plugin/test.js b/docs/prototype/code-reader/figma-plugin/test.js
index 3658464..8d1aa8b 100644
--- a/docs/prototype/code-reader/figma-plugin/test.js
+++ b/docs/prototype/code-reader/figma-plugin/test.js
@@ -2,7 +2,7 @@ const assert = require("node:assert/strict");
const { test } = require("node:test");
const fs = require("node:fs");
const path = require("node:path");
-const { DIFF_PAGE_NAME, DIFF_BLOCKS, DIFF_COLORS, DIFF_SAMPLE, UNCOMMITTED_GROUPS, diffParts, diffStatsText, NEXT_DOCKERFILE, BACKEND_DOCKERFILE, DOCKER_PAGE_NAME, SHELL_BLOCKS, SHELL_PAGE_NAME, NESTED_CALL_SAMPLE, parseCall, ROUTER_SAMPLE, ROUTE_SAMPLE, REVIEW, REVIEW_ISSUES, ASK_SAMPLE, BEAT_SCHEDULE, ENUM_SAMPLE, SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, build, run, nextPageName, PAGE_NAME, NAMESPACE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, parseImport, parseVariable, typeSegments } = require("./code.js");
+const { REACT_PAGE_NAME, TITLEBAR_CARD, LEGAL_CARD, LEGAL_EFFECTS, TITLEBAR_IMPORTS, EXTRA_KINDS, DIFF_PAGE_NAME, DIFF_BLOCKS, DIFF_COLORS, DIFF_SAMPLE, UNCOMMITTED_GROUPS, diffParts, diffStatsText, NEXT_DOCKERFILE, BACKEND_DOCKERFILE, DOCKER_PAGE_NAME, SHELL_BLOCKS, SHELL_PAGE_NAME, NESTED_CALL_SAMPLE, parseCall, ROUTER_SAMPLE, ROUTE_SAMPLE, REVIEW, REVIEW_ISSUES, ASK_SAMPLE, BEAT_SCHEDULE, ENUM_SAMPLE, SQLA_MODEL, ITERATION_SAMPLES, iterationSegments, facetCounts, filteredOut, filterPresets, FILTER_FILE, NOTES, NOTE_DRAFT, PLAIN_KINDS, build, run, nextPageName, PAGE_NAME, NAMESPACE, WORKSPACES, FILES, CODE_TREE, BLOCK_KINDS, SOURCES, blockCode, lineRange, walkTree, translateBlock, highlightCode, parseSignature, parseImport, parseVariable, typeSegments } = require("./code.js");
const { fakeFigma } = require("../../figma-lab/fake-figma");
function action(node) { return node.reactions[0].actions[0]; }
@@ -100,9 +100,10 @@ test("manifest stays local, without a fabricated plugin ID", () => {
assert.deepEqual(manifest.editorType, ["figma"]);
assert.deepEqual(manifest.networkAccess.allowedDomains, ["none"]);
assert.equal("id" in manifest, false);
- // 插件菜单：主画板、Shell 脚本、Dockerfile、代码差异，各自只生成自己那一页
- assert.deepEqual(manifest.menu.map((item) => item.command), ["main", "shell", "docker", "diff"]);
+ // 插件菜单：主画板、Shell 脚本、Dockerfile、代码差异、React 组件，各自只生成自己那一页
+ assert.deepEqual(manifest.menu.map((item) => item.command), ["main", "shell", "docker", "diff", "react"]);
assert.equal(manifest.menu.find((item) => item.command === "diff").name, "代码差异");
+ assert.equal(manifest.menu.find((item) => item.command === "react").name, "React 组件");
});
test("plugin source passes Figma's load-time scan", () => {
@@ -755,6 +756,193 @@ test("running the diff command twice numbers the page", async () => {
assert.equal(second.page.name, `${DIFF_PAGE_NAME} 2`);
});
+// React 组件页：一次生成，下面几个测试共用
+let reactRun;
+function reactPage() {
+ if (!reactRun) {
+ const api = fakeFigma();
+ reactRun = build(api, () => {}, "react").then((result) => ({ api, result }));
+ }
+ return reactRun;
+}
+const childNames = (node) => node.children.map((child) => child.name);
+
+test("the React 组件 menu item builds its own page with four boards, under the layer budget", async () => {
+ const { result } = await reactPage();
+ assert.equal(result.page.name, REACT_PAGE_NAME);
+ assert.deepEqual(result.screens.map((screen) => screen.name),
+ ["Prototype / React 组件 · 简单", "Prototype / React 组件 · 复杂", "Prototype / React 组件 · 对照", "Prototype / React 组件 · 标记说明"]);
+ assert.equal(result.page.flowStartingPoints[0].nodeId, result.boards.simple.screen.id);
+ let owned = 0;
+ const walk = (node) => { owned += 1; if (node.type !== "INSTANCE") node.children.forEach(walk); };
+ result.page.children.forEach(walk);
+ assert.ok(owned < 3000, `React page owns ${owned} layers`);
+ const blocks = [...result.screens, ...result.components.sets];
+ for (const block of blocks) assert.equal(block.parent, result.page);
+ for (let i = 0; i < blocks.length; i += 1) {
+ for (let j = i + 1; j < blocks.length; j += 1) assert.equal(overlaps(blocks[i], blocks[j]), false, `${blocks[i].name} overlaps ${blocks[j].name}`);
+ }
+ const setIds = new Set(result.components.sets.flatMap((set) => set.children.map((component) => component.id)));
+ for (const screen of result.screens) {
+ for (const instance of screen.findAll((node) => node.type === "INSTANCE")) assert.ok(setIds.has(instance.mainComponentId), `${instance.name} comes from a set`);
+ }
+});
+
+test("React window: DesktopTitlebar.tsx selected in the sidebar, its imports then the React card in the preview", async () => {
+ const { result } = await reactPage();
+ const { lib } = result.components;
+ const { simple } = result.boards;
+ assert.equal(named(simple.screen, "Title").characters, `DesktopTitlebar.tsx — luffy-agent-platform`);
+ assert.equal(named(simple.sidebar, "Row / DesktopTitlebar.tsx").mainComponentId, lib.row.get("file/selected").id);
+ assert.equal(named(simple.sidebar, "Row / LegalDocPage.tsx").mainComponentId, lib.row.get("file/default").id);
+ assert.ok(named(simple.screen, "Filter bar"));
+ // "use client" 和文档注释并进卡片，不单独成块：导入五块，然后是组件卡片
+ const placed = simple.tree.findAll((node) => node.type === "INSTANCE" && node.name.startsWith("Block / "));
+ assert.deepEqual(placed.map((node) => node.name), [...TITLEBAR_IMPORTS.map(([line]) => `Block / L${line}`), `Block / L${TITLEBAR_CARD.line}`]);
+ assert.equal(placed[placed.length - 1].mainComponentId, lib.reactCards.get("DesktopTitlebar").id);
+ assert.equal(named(named(lib.titlebarBlocks.get(5), "Prop / 仅类型"), "Value").characters, "是");
+});
+
+test("React cards: name tags, one row per destructured prop, sections in order, no 输入参数 / 输出参数", async () => {
+ const { result } = await reactPage();
+ const { lib } = result.components;
+ const titlebar = named(lib.reactCards.get("DesktopTitlebar"), "Content");
+ assert.ok(named(lib.reactCards.get("DesktopTitlebar"), "Kind / React 组件"));
+ assert.deepEqual(childNames(titlebar), ["Prop / 名称", "Prop / 说明", "Prop / 属性", "Props", "Prop / 读取的数据", "Reads", "Prop / 派生值", "Derived", "Prop / 渲染", "Outline"]);
+ assert.deepEqual(named(titlebar, "Prop / 名称").findAll((node) => node.name.startsWith("Tag / ")).map((node) => node.name), ["Tag / 具名导出", "Tag / 客户端组件"]);
+ assert.deepEqual(texts(named(titlebar, "Property / platform")), ["platform", 'DesktopShell["platform"]', "—", "是"]);
+ assert.deepEqual(texts(named(titlebar, "Row / title")), ["title", "useDesktopShell((s) => s.title)", "从 desktop store 读 title"]);
+ assert.deepEqual(texts(named(titlebar, "Row / center")), ["center", "title；没有就按路径查 PAGE_TITLES；再没有就空", "每次渲染"]);
+ const legal = named(lib.reactCards.get("LegalDocPage"), "Content");
+ assert.deepEqual(childNames(legal).filter((name) => name.startsWith("Prop / ")),
+ ["Prop / 名称", "Prop / 说明", "Prop / 属性", "Prop / 状态", "Prop / 引用", "Prop / 读取的数据", "Prop / 派生值", "Prop / 副作用", "Prop / 事件处理", "Prop / 渲染"]);
+ for (const card of [titlebar, legal]) {
+ assert.equal(named(card, "Prop / 输入参数"), null);
+ assert.equal(named(card, "Prop / 输出参数"), null);
+ }
+ // props 来自接口：展开字段，「属性」后面写来自哪里；有说明就多一列
+ assert.equal(named(named(legal, "Prop / 属性"), "Value").characters, "1 个 · 来自 LegalDocPageProps");
+ assert.equal(texts(named(legal, "Property / doc")).pop(), "terms = 用户服务协议; privacy = 隐私政策");
+ assert.equal(texts(named(legal, "Row / headings")).pop(), "markdown 变了时（useMemo）");
+ // 回调、子元素：名字后面跟小标签，回调的类型写成函数签名
+ const legend = result.boards.legend;
+ const callback = named(legend, "Property / onOpenChange");
+ assert.ok(named(callback, "Tag / 回调"));
+ assert.equal(texts(callback)[2], "(next: 布尔) => 无");
+ assert.ok(named(named(legend, "Property / children"), "Tag / 子元素"));
+});
+
+test("React render outline: native tags grey, components coloured, style chips, conditions, ternaries, lists, early returns, fragments", async () => {
+ const { result } = await reactPage();
+ const { lib } = result.components;
+ const outline = named(lib.reactCards.get("DesktopTitlebar"), "Outline");
+ const windowControls = named(outline, "Line / WindowControls");
+ assert.equal(named(named(windowControls, "Pill / when"), "Text").characters, '当 platform 是 "windows" 时');
+ assert.ok(sameColor(colorOf(named(windowControls, "Element")), "#61dafb"), "components in the component colour");
+ assert.ok(sameColor(colorOf(named(named(outline, "Line / span"), "Element")), "#808080"), "native tags grey");
+ const rootStyle = named(named(outline, "Line / div"), "Style");
+ assert.equal(rootStyle.mainComponentId, lib.styleChip.get("closed").id);
+ assert.equal(named(rootStyle, "Label").characters, "样式 8 个类");
+ assert.equal(named(rootStyle, "Text").characters, TITLEBAR_CARD.render[0].cls);
+ assert.equal(named(lib.styleChip.get("closed"), "Classes").visible, false);
+ assert.equal(named(lib.styleChip.get("open"), "Classes").visible, true);
+ const legal = named(lib.reactCards.get("LegalDocPage"), "Outline");
+ const list = named(legal, "Line / 列表");
+ assert.equal(named(named(list, "Pill / each"), "Text").characters, "对 headings 的每一项 h");
+ assert.equal(named(list, "Key").characters, "key h.id");
+ const ternary = named(legal, "Line / 三元");
+ assert.equal(named(named(ternary, "Pill / when"), "Text").characters, "如果 markdown.trim() 有内容");
+ const branches = ternary.parent.children[ternary.parent.children.indexOf(ternary) + 1];
+ assert.deepEqual(branches.findAll((node) => node.name === "Pill / branch").map((node) => named(node, "Text").characters), ["是", "否"]);
+ assert.ok(texts(legal).includes("// 顶部导航栏: 返回 + 文档切换 + 打印"), "JSX comments stay as comment lines");
+ const legend = result.boards.legend;
+ const early = named(named(legend, "Sample / 提前返回"), "Line / 不渲染");
+ assert.deepEqual(texts(early), ["当 section 没有值 时", "不渲染"]);
+ assert.equal(named(named(named(legend, "Sample / 提前返回"), "Line / 返回"), "Text").characters, "否则");
+ assert.deepEqual(texts(named(named(legend, "Sample / 片段"), "Line / <>")), ["<>", "片段，不产生元素"]);
+ assert.equal(named(named(legend, "Sample / 样式"), "Line / Link").findOne((node) => node.name === "Style").mainComponentId, lib.styleChip.get("open").id);
+});
+
+test("React effects and handlers: sub-cards with timing, body and cleanup; the handler table opens a sub-card under it", async () => {
+ const { result } = await reactPage();
+ const { lib } = result.components;
+ const effect = (key, state) => lib.effects.get(`${key}/${state}`).node;
+ assert.equal(named(named(effect("effect-2", "open"), "Prop / 时机"), "Value").characters, "doc、headings 变了时");
+ assert.equal(named(named(effect("effect-2", "open"), "Prop / 清理"), "Value").characters, 'container.removeEventListener("scroll", handleScroll)');
+ assert.equal(named(effect("effect-1", "open"), "Prop / 清理"), null, "cleanup only when the effect returns one");
+ assert.equal(named(effect("effect-2", "open"), "Body").findAll((node) => node.name.startsWith("Statement / ")).length, LEGAL_EFFECTS[1].body.length);
+ assert.equal(named(effect("effect-2", "closed"), "Summary").characters, "doc、headings 变了时 · 滚动时按标题的位置高亮当前章节 · 有清理");
+ assert.ok(named(effect("effect-1", "open"), "Kind / 副作用"));
+ const placed = named(lib.reactCards.get("LegalDocPage"), "Content").findAll((node) => node.type === "INSTANCE" && node.name.startsWith("Effect / "));
+ assert.deepEqual(placed.map((node) => node.mainComponentId), LEGAL_EFFECTS.map((item) => effect(item.key, "open").id));
+ const none = lib.handlers.get("none");
+ assert.equal(named(none.node, "Handler card"), null);
+ assert.deepEqual(texts(named(none.node, "Handler / handleBack")), ["handleBack", "