[objectstack-fleet]

domain:ui#3 · os-bill · session_01Utp6CaJoinvGQSbHeDaWBe

Requested by Bill · project thread

维护者速读

• 改了什么：Studio 流程节点检查器里，超过 120 个字符的字段帮助默认折成两行，带「了解更多 / 收起」开关；列表列（如审批节点的审批人）的 schema 说明不再塞进输入框占位符，改成列下方的帮助。
• 为什么改：HotCRM 浏览器走查（Setup and Studio: suggestions from a full HotCRM browser pass on 18.2.0: user onboarding, packaged automation state, run-now for scheduled flows, admin lists, and Studio entry, field table, flow inspector wording and one designer per item #27356 第 15 行）看到节点帮助是一整段引擎说明，占位符里写着「ADR-0105 D9 — organization…」，被截断，一打字就消失。
• 风险与回滚：只改展示，不改存储的值，也不改文字本身；回滚就是 revert 本 PR。
• 先看：FlowFieldHelp.tsx（折叠逻辑），json-schema-to-fields.ts 里 columnsFor 的两处（说明从 placeholder 改成 help），FlowObjectListField.tsx 渲染列帮助的四处。
• 两分钟验证：pnpm --dir ui exec vitest run packages/app-shell/src/views/metadata-admin/inspectors/FlowFieldHelp.learnMore-27356.test.tsx，应见 4 passed。
• 需要你做的：无，席位落地。

Part of #27356 (row 15, hotcrm#2320 Studio S4: node inspector help and placeholder)
Clause-②: no
Metadata-protocol: none

What changes

Row 15 has two halves. This PR is the Studio half: how help is shown. The words half is not Studio's (see Acceptance notes).

• Long help opens clamped. FlowFieldHelp (new, views/metadata-admin/inspectors/) renders the help line under a flow inspector field. Help longer than FLOW_HELP_CLAMP_CHARS (120) opens clamped to two lines (line-clamp-2) with a Learn more button (aria-expanded, aria-controls); Show less folds it again. Shorter help renders in full with no button, as before. The full text stays in the DOM in both states. FlowNodeConfigField uses it for every field's help (its only help site).
• Column descriptions are help, not placeholders. jsonSchemaToFlowFields used to put an objectList column's schema description into the column's placeholder. On the approval node's Approvers list this put the served organization description ("ADR-0105 D9 — organization whose directory resolves this approver: …") into the input as a cut-off placeholder, and the served value description likewise. FlowConfigColumn gains help; both columnsFor sites (scalar columns and nested-list columns) now write the description there, and FlowObjectListField shows it under the column with FlowFieldHelp, in the default row layout, the decision branch cards and under nested list columns. A hand-written column placeholder (the offline table) is unchanged.
• i18n. Two keys added to the studio namespace, en and zh: engine.inspector.flowNode.help.learnMore, engine.inspector.flowNode.help.showLess. No key renamed.

Boundary: the Add-node menu is #27521 row 39 and is not touched here; this PR changes the node inspector only.

Tests

• New FlowFieldHelp.learnMore-27356.test.tsx (4 tests). The column half reads the installed contract: z.toJSONSchema(ApprovalNodeConfigSchema, { io: 'input' }) through jsonSchemaToFlowFields, then asserts the organization column carries the description as help and no placeholder, and that a rendered Approvers row has no element whose placeholder is that description while a help line shows it. The clamp half renders FlowNodeConfigField with a long and a short help.
• json-schema-to-fields.test.ts: the approver value column assertion moved from placeholder to help (plus placeholder undefined). That line pinned the behaviour this PR changes.

Readings (head 491ca52 for gates; tests on bc2046a, merge of origin/main touched none of these packages)

• New file: 4/4 passed.
• Every ui test file naming FlowNodeConfigField, FlowObjectListField, json-schema-to-fields, FlowNodeInspector or FlowFieldHelp (72 files): 72 passed, 1065 passed / 1 skipped.
• pnpm --filter @object-ui/app-shell --filter @object-ui/i18n run type-check: both Done, exit 0 (lock VERDICT command-exit 0).
• Ablation 1, through scripts/ablation-replace.mjs (anchor 1 to 0): the scalar column's help: prop.description back to placeholder: prop.description: 2 failed / 2 passed (both column tests red); restored blob = HEAD blob f12818610a37, git diff HEAD empty.
• Ablation 2: const long = text.length > FLOW_HELP_CLAMP_CHARS; to const long = false;: 1 failed / 3 passed (the clamp test red); restored blob = HEAD blob c4b6a6f0cf77, git diff HEAD empty.
• vitest resolves @object-ui/* to source here, so neither ablation needed a rebuild.

Acceptance notes

• The words are the engine's. The help and column descriptions on an approval node come from @objectstack/spec automation/approval.zod.ts (.describe() / .meta({ description })), published by the server as the node's configSchema; Studio shows the producer's sentence and keeps only the zh rendering (FLOW_FIELD_ZH). Rewriting them in business words (for example excludeSubmitter's paragraph naming submitter_id and onEmptyApprovers, and the organization description that opens with an ADR citation) is a spec change, outside this Studio surface. It is filed as Flow node help in business words: approval config describe text and node palette descriptions are written for engineers (#27356 row 15, #27521 row 39) #27838 (domain:spec, together with Setup and Studio: suggestions from the 18.3.0 RC browser walkthrough: Setup naming and machine values, invitation and user onboarding, permission-set authoring, dialog focus, Studio first run, validation and flow builders, and publish-panel wording #27521 row 39), not done here.
• The 120-character threshold is a length, not a measured overflow: jsdom has no layout, and a length keeps the behaviour deterministic. The threshold was chosen, not measured against a rendered width.
• Hand-written help in the offline field table that runs past 120 characters (for example the decision branches help) now also opens clamped. That is the intended reading of row 15 ("the detail behind learn more").

Verification

On head 491ca521: dispatch-gates --commands derived 34 families for this diff; all 34 were run locally, each exit 0, and --ran reconciled 34 run, 0 NOT-MEASURED, 0 UNRUN (node scripts/check-sdui-manifest.mjs among them). check:new-line-citations: 0 new. CI check-runs were in progress when this was opened.

---

Generated by Claude Code

[objectstack-fleet]

domain:ui#3 · os-bill · session_01Utp6CaJoinvGQSbHeDaWBe

席位核对

ACCEPT · head 491ca521ddfe983a4ed6fb7f9467cdfec7c8bc96 · 2026-10-30T01:26Z

• Shape: draft → main, Part of #27356 (row 15 only; the order lands one PR per row, so the card stays open), no closing keyword. Clause-②: no and Metadata-protocol: none match the claim; Studio-side only (@object-ui/app-shell, private: true). No contract review owed.
• Premise, measured: row 15 asked for inspector help, not a placeholder carrying the description: json-schema-to-fields now puts a column description into help instead of placeholder, and the new FlowFieldHelp clamps help above 120 characters behind Learn more / Show less. The words themselves stay the producer's (approval.zod.ts describe text); Studio keeps only its zh rendering.
• Gates (check-runs on the head): 46 success, 13 skipped, 0 failure; mergeable_state clean. check-governed-merges --pr 27832: NOT governed (0 of 10 paths), 191 changed lines.
• Accepted deviations: the 120-character threshold is a chosen length, not a measured overflow (jsdom has no layout); hand-written help over that length now also opens clamped, which is the row's intended reading.
• Out of scope: rewriting the approval node's describe text in business words is filed as Flow node help in business words: approval config describe text and node palette descriptions are written for engineers (#27356 row 15, #27521 row 39) #27838 (domain:spec, together with Setup and Studio: suggestions from the 18.3.0 RC browser walkthrough: Setup naming and machine values, invitation and user onboarding, permission-set authoring, dialog focus, Studio first run, validation and flow builders, and publish-panel wording #27521 row 39); the seat patched the body to name it.
• Landing: non-governed, all checks green, mergeable_state clean ⇒ the seat lands it (pr_ready + automerge_enable). Row 18 follows from the new main.

---

Generated by Claude Code