yugoo-design 0.2.7 → 0.2.8

package/payload/shared/authoring/studio-creators/source/.agents/skills/design-bundle-creator/references/bundle-checklist.md

@@ -27,7 +27,7 @@
 
 控件和组件是封闭集合，写入前读 `panel-dsl.ts` 中相应类型与绑定规则。例如当前有 `list` / `multi_select`，没有一个可任意猜用的 `tags` 控件；子表格控件还受 `ROW_COLUMN_CONTROLS` 限制。按数据和交互目标选类型，不照搬其他 UI 框架的命名。
 
-问题清单优先使用标准 `question_workspace`（无侧栏需求的极小清单可用 `question_list`），不要用 `record_form` 重新拼一套问答 UI。工作区复用通用 `panel_workspace` 的左侧导航和主内容边界；左侧只承载导航，工作区说明写在 `description`，由共享的顶部悬浮 Tip Bar 呈现，不要把长说明塞进窄侧栏。可选 `round` 自动形成轮次，未声明轮次时仍形成一个“当前问题”分组。记录的通用字段是 `prompt`、可选 `note`、`kind`（`text | single | multiple`）、可选 `choices`、`answer` 和可选 `detail`；其中 `choices` 仅服务交互选项，用户事实以非空 `answer` 为准。文本题只编辑一个 `answer` 文本框，已有 `detail` 作为只读上下文保留；选择题可用 `detail` 补充所选答案。可选 `rejected` 只表达问题交互状态；可选 `multimodal_answer` 使用标准本地附件引用，上传字节由 Host 的浏览器传输与 Panel Save 原子保存，绝不能进入 canonical JSON。不要为不需要的 Bundle 强制添加轮次、拒答或附件字段。
+问题清单优先使用标准 `question_workspace`（无侧栏需求的极小清单可用 `question_list`），不要用 `record_form` 重新拼一套问答 UI。工作区复用通用 `panel_workspace` 的左侧导航和主内容边界；左侧只承载导航，工作区说明写在 `description`，由共享的顶部悬浮 Tip Bar 呈现，不要把长说明塞进窄侧栏。可选 `round` 自动形成轮次，未声明轮次时仍形成一个“当前问题”分组。记录的通用字段是 `prompt`、可选 `note`、`kind`（`text | single | multiple`）、可选 `choices`、`answer` 和可选 `detail`；其中 `choices` 仅服务交互选项，用户事实以非空 `answer` 为准。文本题只显示一个 `answer` 文本框，不另显示 `detail` 输入或历史只读区；选择题可用 `detail` 补充所选答案。可选 `rejected` 只表达问题交互状态；可选 `multimodal_answer` 使用标准本地附件引用，上传字节由 Host 的浏览器传输与 Panel Save 原子保存，绝不能进入 canonical JSON。不要为不需要的 Bundle 强制添加轮次、拒答或附件字段。
 
 需要 Panel 内左侧导航的其他信息切片使用 `panel_workspace` 的 `sidebar` / `main` slots，复用统一的 containment、滚动和窄宽度退化；不要只为某个 Kit 复制一套双栏 CSS。该布局只定义交互骨架，不改变 Bundle 的 canonical 所有权和领域结构。
 

package/payload/shared/authoring/studio-creators/source/.agents/skills/design-bundle-creator/references/panel-authoring.md

@@ -155,8 +155,10 @@ Kit loader 检查条件约束。结构校验不等于 schema、交互或保存
 - 嵌套表单复用完整字段组与重复集合：组间16px、组内8px，添加位于所属集合尾部，
   折叠只改变可见性。不靠空白节点、分割线或 CSS 补偿共享组件的排版缺陷；
   发现缺陷应修共享实现并横向验证至少一个同形态的其他面板。
-  内联折叠的标题文字对齐正文左边界，箭头紧跟标题、间隔8px，不继承普通按钮
-  的水平内边距；展开不额外缩进，首组仍间隔16px。不要用字段声明补空格。
+  已有语义灰组统一支持整体折叠、默认展开，允许并开，不按条目或字段数量判断，
+  不为普通字段或选项另添包装。标题文字对齐正文左边界，整条标题栏按“标题 → 帮助／数量／操作 → 最右折叠箭头”排列，
+  箭头不能停在题干后、操作前，同类内容组不保留居中箭头例外；
+  展开不额外缩进，标题到所属正文8px，独立内容组间16px（紧凑6px/12px）。不要用字段声明补空格。
   这不是结构树规则：树的前置层级箭头与缩进保持不变。
 - 简短同级单选显式使用 `choice_layout: row_wrap`，横向排列并随内容区宽度自然
   换行，复用共享行间8px/列间20px；不拉伸选项、不缩字、不增加横向滚动。
@@ -322,8 +324,8 @@ reference_field）；普通关联绝不自动级联删除。当前契约仅支
 用户文件。显示标签与领域绑定归 Bundle，运行时不能按 Bundle 名选择特例。
 
 长记录可使用静态 `form.body` 的 `kind: tabs`（id/title/tabs，每页 id/title/items），
-页内复用 field/row/group，禁止递归 tabs；字段不能跨页重复。低频字段组可声明
-`collapsible: true` 并提供明确标题。共享页签与折叠只改变显示，保留完整编辑内容；
+页内复用 field/row/group，禁止递归 tabs；字段不能跨页重复。语义灰组的折叠沿用共享默认展开，
+已有 `collapsible` / `default_open` 声明仍遵循目标运行时契约，不因低频另定一套开关规则。共享页签与折叠只改变显示，保留完整编辑内容；
 默认页先回答用户最重要的产品问题，不以技术配置开场。这些静态 form 扩展不
 自动进入生成式 A2UI 白名单。实际作者仍须核对当前 DSL 与渲染回归。
 

package/payload/shared/authoring/studio-creators/source/.agents/skills/design-bundle-creator/scripts/inspect-panel-component.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 /** Source-derived authoring reference, not another schema or runtime validator. */
-import { readFile, readdir } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import { resolve, relative, join } from 'node:path'
+import { resolve, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 // The complete trusted shared guide has a separate budget from each focused
 // component section (16 KiB), the DSL document (256 KiB), and the packaged
-// authoring artifact (4 MB). Keep the guide whole; never truncate its methods.
-const MAX_SHARED_STANDARD_BYTES = 128 * 1024
+// authoring artifact (6,000,000 bytes). Keep the guide whole; never truncate its methods.
+const MAX_SHARED_STANDARD_BYTES = 256 * 1024
 
 async function inspectionContext(repo) {
   repo = resolve(repo)
@@ -161,34 +161,23 @@ async function inspectWithContext(context, name, typeName, options = {}) {
   const { parsePanelManifest } = await import(pathToFileURL(join(repo, contractPath)).href)
   const examples = []
   const invalidExamples = []
-  const packages = join(repo, 'packages')
-  const packageEntries = (await readdir(packages, { withFileTypes: true }))
-    .filter(entry => entry.isDirectory() && entry.name.startsWith('skills-'))
-    .sort((a, b) => a.name.localeCompare(b.name))
-  for (const entry of packageEntries) {
-    const packageRoot = join(packages, entry.name)
-    const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
-    const skills = join(packageRoot, manifest.designSystem?.kit?.bundles ?? manifest.designSystem?.kit?.skills ?? './skills')
-    let bundles
-    try { bundles = await readdir(skills, { withFileTypes: true }) }
-    catch (error) { if (error.code === 'ENOENT') continue; throw error }
-    for (const bundle of bundles.filter(item => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
-      const path = join(skills, bundle.name, 'panel.yaml')
-      let text
-      try { text = await readFile(path, 'utf8') }
-      catch (error) { if (error.code === 'ENOENT') continue; throw error }
-      let manifest
-      try { manifest = parsePanelManifest(text) }
-      catch (error) { invalidExamples.push({ file: relative(repo, path), error: error.message }); continue }
-      function visit(node, pointer) {
-        if (node.component === name) examples.push({
-          file: relative(repo, path), pointer, node, validation: 'panel-structure-only',
-        })
-        for (const [index, child] of (node.children ?? []).entries()) visit(child, `${pointer}/children/${index}`)
-        for (const [slot, child] of Object.entries(node.slots ?? {})) if (child) visit(child, `${pointer}/slots/${slot}`)
-      }
-      visit(manifest.ui, '/ui')
+  // Share the exact build-time source paths used by input hashing. Runtime
+  // package declarations can point to lib/, but source examples never read it.
+  const { panelAuthoringInputPaths } = await import(pathToFileURL(join(repo, 'scripts/companion-authoring-material.mjs')).href)
+  for (const file of (await panelAuthoringInputPaths(repo)).filter(path => path.endsWith('/panel.yaml'))) {
+    const path = join(repo, file)
+    const text = await readFile(path, 'utf8')
+    let manifest
+    try { manifest = parsePanelManifest(text) }
+    catch (error) { invalidExamples.push({ file, error: error.message }); continue }
+    function visit(node, pointer) {
+      if (node.component === name) examples.push({
+        file, pointer, node, validation: 'panel-structure-only',
+      })
+      for (const [index, child] of (node.children ?? []).entries()) visit(child, `${pointer}/children/${index}`)
+      for (const [slot, child] of Object.entries(node.slots ?? {})) if (child) visit(child, `${pointer}/slots/${slot}`)
     }
+    visit(manifest.ui, '/ui')
   }
   return {
     ...base,
@@ -229,10 +218,15 @@ export async function exportPanelAuthoringReference(repo) {
     else names.push(name)
   }
   const components = Object.create(null), contracts = Object.create(null)
+  let sharedStandards
   for (const name of COMPONENT_KINDS) {
     const reference = await inspectWithContext(context, name)
     const documentation = await inspectWithContext(context, name, undefined, { documentationOnly: true })
-    components[name] = { ...reference, documentation: documentation.documentation }
+    // Store the complete common guide once; component-specific documentation
+    // remains inline. Packaged docs queries restore the existing response shape.
+    const { sharedStandards: guide, ...componentDocumentation } = documentation.documentation
+    sharedStandards ??= guide
+    components[name] = { ...reference, documentation: componentDocumentation }
   }
   // Contract names are source-derived, including focused nested properties;
   // they are not another component vocabulary or a per-component JSON Schema.
@@ -241,7 +235,7 @@ export async function exportPanelAuthoringReference(repo) {
   }
   const callbackSource = await readFile(join(repo, 'packages/panel/src/interpreter.ts'), 'utf8')
   return {
-    format: 'panel-authoring-reference/v1', catalogIdentity: panelAuthoringCatalogIdentity(), components, contracts,
+    format: 'panel-authoring-reference/v1', catalogIdentity: panelAuthoringCatalogIdentity(), components, contracts, sharedStandards,
     hostCallbackContract: {
       file: 'packages/panel/src/interpreter.ts', type: 'RenderOptions',
       declaration: (() => {

package/payload/shared/authoring/studio-creators/source/docs/dsl-spec.md

@@ -120,11 +120,13 @@ manifest against the actual target version before publishing it.
 
 ### Long text editing
 
-Authored `textarea` fields may opt into `textarea_rows: 3..20` to give complete
-instructions or configuration text a readable initial viewport. This is finite
-presentation only: it does not trim text, parse it, change storage or impose a
+Multiline fields fit actual content from one line up to five automatic lines,
+then scroll internally. Users can resize them beyond that automatic limit.
+`textarea_rows`, when provided, chooses an automatic row budget between three
+and five; larger existing values are capped at five, never used as a minimum
+height. This is finite presentation only: it does not trim text, parse it, change storage or impose a
 character limit. Typed `record_map.item_fields` use the same leaf rule. Omission
-preserves existing sizing; generated-origin panels do not expose this option.
+uses the five-line automatic budget; generated-origin panels do not expose this option.
 
 ### Same-record inspector views
 
@@ -200,14 +202,17 @@ are read on demand through the existing host artifact port, only when the path
 is safe, is present in `artifactFiles`, and an exact `sourceRevision` is available.
 The source revision is passed to the reader. The preview is escaped plain text,
 bounded to 262,144 characters, with unavailable and retry states; no code, HTML or
-model is executed. Nonempty provenance/evidence uses a folded readonly view;
+model is executed. File reading starts only when the user explicitly opens that
+file preview; opening a surrounding group does not activate it.
+Nonempty provenance/evidence uses an initially open readonly group;
 empty technical fields are not presented as a form. Other unbound fields retain
 their original field controls, not an inferred metadata role.
 
 Each statement is a collapsible card, expanded initially, containing its business explanation, formula
-and relevant shared symbol definitions, with a source disclosure at the bottom.
-Per-formula symbol definitions are initially folded, showing their count; source,
-complete-model and technical-record disclosures also start folded.
+and relevant shared symbol definitions, with readonly source context at the bottom.
+Per-formula symbol definitions, the complete model and technical records reuse
+the shared initially open disclosure groups. Users can close each independently;
+neither one-item content nor property count removes the disclosure control.
 The complete formulation is a separate collapsible card containing the editable
 symbol glossary. Folds are local presentation, not saved facts or approval.
 Symbol usage is a read-only projection of matching rendered MathML notation; it
@@ -634,12 +639,25 @@ contain only the existing field/row/group items: no nested tabs or groups.
 They reuse the shared `tabs` component, including keyboard navigation, stable
 ID selection and mounted inactive editors. Fields remain unique across all
 pages and the record header; fallback fields are appended once outside tabs.
+Section `description` supplies whole-record guidance in the shared record header;
+group descriptions and field help appear beside their captions through shared
+hover/focus/click help, not as trailing paragraphs. Saved descriptive fields
+remain ordinary editable business content.
 Changing page, language or disclosure state emits no canonical edit and never
 clears existing values. Readonly follows the original field's authority.
-`group.collapsible: true` requires a nonempty title, starts closed and uses the
-shared disclosure glyph with native keyboard-accessible details semantics.
-Its content remains mounted; display state is not another data field. Choose
-this only for optional material, not to hide an unresolved blocking decision.
+`group.collapsible: true` requires a nonempty title and uses the shared disclosure
+glyph with native keyboard-accessible details semantics. All existing semantic
+grey content groups support disclosure and start open by default; several groups
+may remain open together. Item, property and option counts do not decide whether
+a group can collapse. Ordinary fields and choices do not gain extra wrappers.
+The complete content header orders the title, existing help/count/actions, then
+the disclosure glyph at its far right; actions must not follow the glyph.
+This does not change the leading chevrons of ordinary navigation trees.
+The existing optional `default_open` boolean remains valid only on an explicitly
+collapsible authored group; an explicit `false` retains its initial-state meaning.
+Later renders, locale changes and readonly changes do
+not reset the user's disclosure choice. Content remains mounted; display state
+is not another data field. Never hide an unresolved blocking decision by default.
 Both additions are static authored form presentation; generated-origin A2UI
 still rejects the complete `form` extension rather than silently dropping it.
 
@@ -987,10 +1005,30 @@ Ordinary `detail_sections` retain their existing same-record nested-form meaning
 directly, cards have no artificial group heading, and the overview connects the
 root directly to records. Do not bind long summaries merely to satisfy grouping;
 this projection never adds a grouping field to canonical records.
-Sidebar selection scrolls to a card; it does not start editing. Description and
-badge drafts have explicit Save/Cancel, while rejected records remain inspectable
-without granting edit access. Optional `board.id_field` binds a declared visible,
-readonly `text` field and displays its existing string beside the card title and
+Sidebar selection scrolls the board's own content to the card title; it does not
+start editing or move the host conversation. Manual scrolling updates the current
+sidebar record, including a current cue on a collapsed navigation group. The
+reading order honors the section's durable order; grouping preserves first-group
+and within-group order without changing stored data. `board.overview: false`
+omits the generated mind-map entry when it does not help the task.
+
+Optional `board.body_fields` declares an ordered list of visible text/textarea
+fields, including `description`. It replaces the unlabeled description with labeled
+content using the existing field labels. Editable cards expose those fields and the
+optional group field directly in the shared Panel draft. Readonly cards retain labels
+for required fields even when empty; optional empty values do not occupy reading space.
+Header, group and detail
+bindings cannot duplicate the body fields. Ordinary section creation/deletion and
+reordering remain available when the existing section allows them; request-based
+creation retains its host-owned workflow.
+Grouped reordering swaps adjacent visible records within their current group in
+the durable order, leaving other groups and filtered-out records in place. The
+first and last records in that group disable their respective move actions.
+Description, body, title and badge edits use the Panel's existing Save/Cancel boundary;
+cards do not add a second save mode. Rejected records remain inspectable without
+granting edit access. Available move/delete actions remain visible on the right of
+the card title. Optional `board.id_field` binds a declared visible,
+readonly `text` field and displays its existing string before the card title and
 at the top of cover details. Inline details retain the same card header. It does
 not add an ID editor, generate a fallback ID or write state; omission retains the
 existing title-only presentation. `board.detail_fields` restricts the parent fields
@@ -1097,9 +1135,13 @@ authored extension.
 
 Each group may declare a `presentation` object containing only optional boolean
 `always_expanded`, `show_detail`, and `show_attachments` properties. These select
-shared component behavior, not Bundle-specific styling. Omission preserves the
-usual collapse, detail, and attachment controls. Hiding a control preserves its
-canonical data; keeping a card expanded does not grant editing permission.
+shared component behavior, not Bundle-specific styling. `always_expanded` selects
+the answer area's reading/editing presentation; it does not prevent the user from
+collapsing the outer grey question frame. That frame starts open, and its
+disclosure is independent of editing, finishing or rejecting an answer.
+Omission preserves the usual answer, detail and attachment behavior. Hiding a
+control or closing the frame preserves canonical data and mounted drafts;
+keeping an answer expanded does not grant editing permission.
 Read-only, disabled, protected, historical and rejection guards still apply.
 
 `question_workspace` composes the same question cards with the standard
@@ -1282,6 +1324,49 @@ mounting does not collide with host navigation. Hosts must load shared Panel
 styles; the component does not inject CSS. Test keyboard/hidden behavior and
 narrow-container overflow in a real browser in addition to structural checks.
 
+## Reading nested saved facts
+
+`structured_data` reads its existing `source` path. Optional `read_fields`
+declares display labels and reading order without adding fields to Design JSON:
+
+```yaml
+component: structured_data
+id: shared-reading
+source: common_spec
+read_fields:
+  - {key: layout, label: '$t:layout'}
+  - key: navigation
+    label: $t:navigation
+    item_label_field: label
+    fields:
+      - {key: target_page_id, label: '$t:targetPage', options_from_section: pages}
+      - {key: icon_ref, label: '$t:iconReference', collapsed: true}
+  - {key: source, label: '$t:source', collapsed: true}
+```
+
+Each declaration has a direct own-property `key` and nonempty `label`.
+`fields` describes a nested object, or each object in an array;
+`item_label_field` uses an existing scalar property as an array item's heading.
+That property is not repeated as a separate row when its value is shown in the
+heading. Missing, empty or non-scalar headings leave the original property
+readable. String arrays remain ordinary text lists. `collapsed: true` folds
+low-frequency details, including scalar references; declared content otherwise
+opens directly. Labels use the existing `$t:` resources recursively; property
+keys, source paths, reference IDs and saved values never translate.
+
+`options_from_section` names an existing declared section. Its current record
+label is shown beside the original ID; unresolved references keep their ID.
+This is the existing section/record-label lookup, not an external lookup or
+permission grant. Declared keys appear first in authored order, followed by
+undeclared keys in their saved order with their original names. Declarations
+never remove unknown properties, rewrite values, create missing content, or
+make this reading view editable. Without `read_fields`, existing generic
+reading remains unchanged. The same bounded traversal (eight levels and 100
+entries per level, with visible overflow feedback) applies. Declarations are
+limited to eight levels and 100 entries per level; duplicate keys, unsafe
+property names, unknown section references and invalid option types fail
+manifest validation.
+
 ## Validation rules (fail loud)
 
 `parsePanelManifest` / `validatePanelManifest` reject a manifest when: