component-instance

Components and Instances

• COMPONENT or COMPONENT_SET nodes are reusable (symbols).
• Insert instances with type: "ref" pointing to component/componentSet ID.
• For Component/ComponentSet: call batch_read with the ID to get componentPropertyDefinitions, then batch_edit to update instance properties.
• Instance overrides:
  • Root properties: set directly on the ref object
  • Descendant properties: use descendants map — {descendants: {"childId": {content: "New"}}}
  • Nested instances: slash-separated paths — instanceId/nestedInstanceId/childId
  • Replace subtree: include type in descendant override
  • "Delete" descendant: override visible: false
• When using descendants, paths can access multi-level descendant nodes — use paths in descendants keys, DO NOT create multiple levels of descendants objects.
• Prefer updating the component over individual instances for shared changes.
• ID formats: rendered tree uses semicolons (instanceId;childId), batch_edit uses binding + nodeID (card+"childId"). Fall back to semicolon ID if binding fails.
• Reuse existing components instead of creating duplicates.
• Instead of duplicating the same component multiple times with small tweaks, try to make them more generic so instances can reuse in more places.
• Cannot reference components across files — copy them over.
• Place reusable components on the side, next to the main design.
• Overrides are applied only to the overridden object — changes will NOT be inherited to all children.
• When parsing designs, treat "component" broadly — some are formal symbols, others are ad-hoc groupings visually behaving like components (sometimes prefixed "component/").

Composition Contract

Before inserting a component, inspect its root sizing, exposed properties, visible controls, and nested instances. A component is reusable only when its semantics fit the role in this screen.

• No duplicate affordances: inspect composed components for built-in status bars, back buttons, search controls, titles, close actions, tabs, or bottom navigation before adding siblings with the same role. Keep exactly one primary affordance per action unless the user explicitly asks for both. "It is part of the native component" does not justify two back buttons or two status bars.
• Give every repeated and nested instance distinct, scenario-derived text and icons: update the text and icon slots within each relevant nested instance to reflect its real purpose and never keeps a component default. For menu rows, tabs, list rows, table columns, and cards, replace generic labels such as "菜单" or "默认选项", placeholder sequences, and repeated default or empty-box icons with a coherent set inferred from the page scenario; otherwise, it is a generation defect.
  • Operations: inspect nested descendants with batch_read using sufficient readDepth and properties: ["mainComponent"]. Override text through its TEXT component property or U(instance+"childId", {content: "..."}), and swap icons through INSTANCE_SWAP or U(path, {mainComponent: "matchingIconId"}).
• Semantic fit over coverage: do not instance a Table, Picker, Card, or other component merely because it was returned by search. Use it only when its interaction and content model match the requested module.
• Preserve composite structure: reuse the smallest complete component root; never use internal rows, columns, cells, items, or slots as standalone modules. Tables/DataGrids need headers, at least two columns, and data rows; otherwise use a list or fallback.
• Adaptive sizing: use fill_container on parent-driven axes and hug_contents on content-driven axes. Preserve verified intrinsic/fixed variants, and update relevant nested wrappers when their fixed sizing causes clipping or artificial gaps.