@servicenow/sdk-build-plugins 4.4.1 → 4.5.0

package/src/form-plugin.ts

@@ -0,0 +1,1411 @@
+import {
+    CallExpressionShape,
+    Plugin,
+    IdentifierShape,
+    ElementAccessExpressionShape,
+    type Factory,
+    type Diagnostics,
+    type ObjectShape,
+    type Record,
+    type RecordId,
+    type Shape,
+    Database,
+    isGUID,
+} from '@servicenow/sdk-build-core'
+import { create } from 'xmlbuilder2'
+import { createSdkDocEntry, showGuidFieldDiagnostic } from './utils'
+import { NowIdShape } from './now-id-plugin'
+
+const DEFAULT_VIEW = 'Default view'
+const DEFAULT_ANNOTATION_TYPE = '753f88a80f930000b12e6903cfe01206'
+const FORM_XML_TABLES = ['sys_ui_form', 'sys_ui_form_section']
+
+// Derive sys_id → key name maps from the source-of-truth constants
+function buildReverseMap(ns: { [key: string]: string }): Map<string, string> {
+    const map = new Map<string, string>()
+    for (const [key, value] of Object.entries(ns)) {
+        map.set(value, key)
+    }
+    return map
+}
+
+//TODO:: Import AnnotationType and Formatter from sdk-api once Form plugin is fixed.
+const AnnotationType = {}
+const Formatter = {}
+const ANNOTATION_TYPE_MAP = buildReverseMap(AnnotationType)
+const FORMATTER_MAP = buildReverseMap(Formatter)
+
+// Maps Formatter sys_id → element name (the `formatter` column on sys_ui_formatter)
+const FORMATTER_ELEMENT_MAP = new Map<string, string>([
+    ['444ea5c6bf310100e628555b3f0739d6', 'activity.xml'],
+    ['cfa76e850a0a0b1f01446f67c8538d00', 'attached_knowledge'],
+])
+
+// Split type constants for form layout
+const SPLIT_TYPE = {
+    BEGIN: '.begin_split',
+    MIDDLE: '.split',
+    END: '.end_split',
+} as const
+
+const SPLIT_TYPES = [SPLIT_TYPE.BEGIN, SPLIT_TYPE.MIDDLE, SPLIT_TYPE.END] as const
+
+function sortByPosition(records: Record[]): Record[] {
+    return records.sort(
+        (a, b) => (a.get('position')?.toNumber()?.getValue() ?? 0) - (b.get('position')?.toNumber()?.getValue() ?? 0)
+    )
+}
+
+/**
+ * Converts a UI element record to a FormElement for shape generation.
+ * Returns null for split marker elements (they are handled by groupElementsIntoLayoutBlocks).
+ */
+function convertElementToField(element: Record, descendants?: Database): FormElement | null {
+    const elementValue = element.get('element').asString().getValue()
+    const type = getOptionalString(element, 'type')
+    const formatter = getOptionalString(element, 'sys_ui_formatter')
+
+    // Split markers are handled by groupElementsIntoLayoutBlocks, not emitted as elements
+    if (SPLIT_TYPES.includes(type as (typeof SPLIT_TYPES)[number])) {
+        return null
+    }
+
+    if (type === 'annotation' && descendants) {
+        // element field of sys_ui_element contains the sys_id of the sys_ui_annotation record
+        const annotation = descendants.query('sys_ui_annotation').find((a) => a.getId().getValue() === elementValue)
+        if (annotation) {
+            const isPlainText = annotation.get('is_plain_text').toBoolean()?.getValue() ?? true
+            const annotationTypeSysId = getOptionalString(annotation, 'type')
+            const annotationTypeKey = ANNOTATION_TYPE_MAP.get(annotationTypeSysId)
+            return {
+                type: 'annotation',
+                annotationId: NowIdShape.from(annotation),
+                text: getOptionalString(annotation, 'text'),
+                isPlainText: isPlainText,
+                annotationType: annotationTypeKey ?? annotationTypeSysId,
+            }
+        }
+        return {
+            type: 'annotation',
+            annotationId: new NowIdShape({ source: element, id: elementValue }),
+            text: '',
+            annotationType: 'Info_Box_Blue',
+        }
+    }
+
+    if (type === 'formatter') {
+        const formatterKey = FORMATTER_MAP.get(formatter)
+        const derivableName = FORMATTER_ELEMENT_MAP.get(formatter)
+        return {
+            type: 'formatter',
+            // Only emit formatterName when it differs from the derivable value
+            ...(elementValue !== derivableName ? { formatterName: elementValue } : {}),
+            formatterRef: formatterKey ?? formatter,
+        }
+    }
+
+    if (type === 'list') {
+        // Parse the encoded element string to extract listType and list components
+        const parsed = parseListElement(elementValue)
+        if (parsed.listType === '12M' || parsed.listType === 'M2M') {
+            return {
+                type: 'list',
+                listType: parsed.listType,
+                listRef: `${parsed.listTable}.${parsed.listColumn}`,
+            }
+        }
+        if (parsed.listType === 'custom') {
+            return {
+                type: 'list',
+                listType: 'custom',
+                listRef: parsed.relationship,
+            }
+        }
+        return null
+    }
+
+    // Default: table field element
+    return {
+        field: elementValue,
+        type: 'table_field',
+    }
+}
+
+type ParsedListElement =
+    | { listType: '12M' | 'M2M'; listTable: string; listColumn: string }
+    | { listType: 'custom'; relationship: string }
+
+/**
+ * Parses an encoded list element string into its components.
+ * Formats:
+ *   - '12M.<parent>.<child>.<field>' → { listType: '12M', listTable: '<child>', listColumn: '<field>' }
+ *   - 'M2M.<parent>.<join>.<field>' → { listType: 'M2M', listTable: '<join>', listColumn: '<field>' }
+ *   - 'REL.<parent>.REL:<sys_id>' → { listType: 'custom', relationship: '<sys_id>' }
+ */
+function parseListElement(elementValue: string): ParsedListElement {
+    if (elementValue.startsWith('12M.')) {
+        const parts = elementValue.substring(4).split('.')
+        // parts: [parent_table, child_table, ref_column]
+        return { listType: '12M', listTable: parts[1] ?? '', listColumn: parts[2] ?? '' }
+    }
+    if (elementValue.startsWith('M2M.')) {
+        const parts = elementValue.substring(4).split('.')
+        // parts: [parent_table, join_table, ref_column]
+        return { listType: 'M2M', listTable: parts[1] ?? '', listColumn: parts[2] ?? '' }
+    }
+    if (elementValue.startsWith('REL.')) {
+        // Format: REL.<table>.REL:<sys_id>
+        const relMatch = elementValue.match(/^REL\.[^.]+\.REL:(.+)$/)
+        return { listType: 'custom', relationship: relMatch?.[1] ?? elementValue }
+    }
+    // Fallback
+    return { listType: 'custom', relationship: elementValue }
+}
+
+/**
+ * Groups a flat array of sorted sys_ui_element records into LayoutBlock[] for the content array.
+ * Recognizes .begin_split / .split / .end_split sequences and wraps them into two-column blocks.
+ * Consecutive non-split elements are grouped into one-column blocks.
+ */
+function groupElementsIntoLayoutBlocks(elements: Record[], descendants?: Database): LayoutBlock[] {
+    const blocks: LayoutBlock[] = []
+    let currentOneColumnElements: FormElement[] = []
+
+    // Flush accumulated one-column elements into a block. The length check handles
+    // edge cases where flushOneColumn is called with no pending elements, e.g. when
+    // a .begin_split is the first element or two split blocks are adjacent.
+    const flushOneColumn = () => {
+        if (currentOneColumnElements.length > 0) {
+            blocks.push({ layout: 'one-column', elements: currentOneColumnElements })
+            currentOneColumnElements = []
+        }
+    }
+
+    let i = 0
+    while (i < elements.length) {
+        const elem = elements[i]!
+        const type = getOptionalString(elem, 'type')
+
+        if (type === SPLIT_TYPE.BEGIN) {
+            // Flush any pending one-column elements
+            flushOneColumn()
+
+            // Collect left and right elements until .end_split
+            const leftElements: FormElement[] = []
+            const rightElements: FormElement[] = []
+            let side: 'left' | 'right' = 'left'
+            i++ // skip .begin_split
+
+            while (i < elements.length) {
+                const innerElem = elements[i]!
+                const innerType = getOptionalString(innerElem, 'type')
+                if (innerType === SPLIT_TYPE.END) {
+                    i++ // skip .end_split
+                    break
+                }
+                if (innerType === SPLIT_TYPE.MIDDLE) {
+                    side = 'right'
+                    i++
+                    continue
+                }
+                const converted = convertElementToField(innerElem, descendants)
+                if (converted) {
+                    if (side === 'left') {
+                        leftElements.push(converted)
+                    } else {
+                        rightElements.push(converted)
+                    }
+                }
+                i++
+            }
+
+            blocks.push({ layout: 'two-column', leftElements, rightElements })
+        } else if (type === SPLIT_TYPE.MIDDLE) {
+            // Handle lone .split without .begin_split / .end_split.
+            // ServiceNow can produce this when fields are dragged across columns.
+            // Treat accumulated one-column elements as leftElements,
+            // and everything after .split until the next split marker or end as rightElements.
+            const leftElements: FormElement[] = [...currentOneColumnElements]
+            currentOneColumnElements = []
+            const rightElements: FormElement[] = []
+            i++ // skip .split
+
+            while (i < elements.length) {
+                const innerElem = elements[i]!
+                const innerType = getOptionalString(innerElem, 'type')
+                if (innerType === SPLIT_TYPE.END || innerType === SPLIT_TYPE.MIDDLE || innerType === SPLIT_TYPE.BEGIN) {
+                    break
+                }
+                const converted = convertElementToField(innerElem, descendants)
+                if (converted) {
+                    rightElements.push(converted)
+                }
+                i++
+            }
+
+            blocks.push({ layout: 'two-column', leftElements, rightElements })
+        } else {
+            const converted = convertElementToField(elem, descendants)
+            if (converted) {
+                currentOneColumnElements.push(converted)
+            }
+            i++
+        }
+    }
+
+    // Flush remaining one-column elements
+    flushOneColumn()
+
+    return blocks
+}
+
+/**
+ * Gets an optional string value from a record field with a default fallback
+ */
+function getOptionalString(record: Record, field: string, defaultValue = ''): string {
+    return record.get(field).ifString()?.getValue() ?? defaultValue
+}
+
+/**
+ * Resolves a view value to its sys_id and view name for XML output.
+ * The name is needed as an attribute on the <view> XML element so the parser
+ * can create a RecordId with proper coalesce keys when re-reading the XML.
+ */
+function resolveView(view: ReturnType<Record['get']>, database: Database): { sysId: string; name: string } {
+    if (view.isRecordId() || view.isRecord()) {
+        const viewId = view.isRecordId() ? view : view.getId()
+        const sysId = viewId.getValue()
+        // Try to resolve the view record to get its name
+        const viewRecord = database.resolve(viewId)
+        if (viewRecord) {
+            const name = viewRecord.get('name').ifString()?.getValue() ?? ''
+            return { sysId, name }
+        }
+        // Fall back to primary key (view name) if available
+        if (view.isRecordId() && view.asRecordId().hasPrimaryKey()) {
+            const pk = view.asRecordId().getPrimaryKey()
+            if (pk && !isGUID(pk)) {
+                return { sysId, name: pk }
+            }
+        }
+        return { sysId, name: '' }
+    }
+
+    const viewValue = view.getValue()
+    if (viewValue === 'NULL' || viewValue === DEFAULT_VIEW) {
+        return { sysId: DEFAULT_VIEW, name: DEFAULT_VIEW }
+    }
+
+    // View is a string - try to resolve to record ID if it exists in database
+    const viewNameStr = view.ifString()?.getValue() ?? ''
+    if (!viewNameStr) {
+        return { sysId: '', name: '' }
+    }
+
+    const viewRecord = database.query('sys_ui_view').find((v) => v.get('name').ifString()?.getValue() === viewNameStr)
+    if (viewRecord) {
+        return { sysId: viewRecord.getId().getValue(), name: viewNameStr }
+    }
+    return { sysId: viewNameStr, name: isGUID(viewNameStr) ? '' : viewNameStr }
+}
+
+/**
+ * Resolves a view value to its string representation (sys_id or name)
+ * Handles RecordId, Record, string values, and database lookups
+ */
+function resolveViewName(view: ReturnType<Record['get']>, database: Database): string {
+    return resolveView(view, database).sysId
+}
+
+type FormElement =
+    | { field: string; type: 'table_field' }
+    | {
+          type: 'annotation'
+          annotationId: NowIdShape
+          text: string
+          isPlainText?: boolean
+          annotationType?: string
+      }
+    | { type: 'formatter'; formatterName?: string; formatterRef: string }
+    | { type: 'list'; listType: '12M' | 'M2M'; listRef: string }
+    | { type: 'list'; listType: 'custom'; listRef: string }
+
+type LayoutBlock =
+    | { layout: 'one-column'; elements: FormElement[] }
+    | { layout: 'two-column'; leftElements: FormElement[]; rightElements: FormElement[] }
+
+export const FormPlugin = Plugin.create({
+    name: 'FormPlugin',
+    docs: [
+        createSdkDocEntry('Form', [
+            'sys_ui_form',
+            'sys_ui_form_section',
+            'sys_ui_section',
+            'sys_ui_element',
+            'sys_ui_annotation',
+        ]),
+    ],
+    records: {
+        sys_ui_section: {
+            composite: true,
+            coalesce: ['name', 'caption', 'view', 'sys_domain'],
+            relationships: {
+                sys_ui_element: {
+                    via: 'sys_ui_section',
+                    descendant: true,
+                    relationships: {
+                        sys_ui_annotation: {
+                            // sys_ui_element.element field holds the sys_id of sys_ui_annotation
+                            via: 'element',
+                            inverse: true,
+                            descendant: true,
+                        },
+                    },
+                },
+                sys_ui_view: {
+                    via: 'view',
+                    inverse: true,
+                },
+            },
+            toFile(section, { config, descendants, database }) {
+                // For DELETE records, output a simple delete XML
+                if (section.getAction() === 'DELETE') {
+                    const xml = create().ele('record_update', { table: 'sys_ui_section' })
+                    const child = xml.ele('sys_ui_section', { action: 'DELETE' })
+                    child.ele('sys_id').txt(section.getId().getValue())
+                    child.ele('sys_scope', { display_value: config.scope }).txt(config.scopeId)
+                    child.ele('sys_update_name').txt(`sys_ui_section_${section.getId().getValue()}`)
+                    return {
+                        success: true,
+                        value: {
+                            source: section,
+                            name: `sys_ui_section_${section.getId().getValue()}.xml`,
+                            category: section.getInstallCategory(),
+                            content: xml.end({ prettyPrint: true }),
+                        },
+                    }
+                }
+
+                const sectionName = section.get('name').asString().getValue()
+                const caption = getOptionalString(section, 'caption')
+                const sysDomain = getOptionalString(section, 'sys_domain', 'global')
+                const { sysId: viewName, name: viewDisplayName } = resolveView(section.get('view'), database)
+
+                const xml = create().ele('record_update')
+                const root = xml.ele('sys_ui_section', {
+                    caption,
+                    section_id: section.getId().getValue(),
+                    sys_domain: sysDomain,
+                    table: sectionName,
+                    view: viewName,
+                })
+
+                // Add all sys_ui_annotation records for this section (excluding deleted ones)
+                const annotations = descendants
+                    .query('sys_ui_annotation')
+                    .filter((annotation) => annotation.getAction() !== 'DELETE')
+
+                for (const annotation of annotations) {
+                    const annotationChild = root.ele('sys_ui_annotation', { action: annotation.getAction() })
+                    const isPlainTextVal = annotation.get('is_plain_text').ifBoolean()?.getValue() ?? true
+                    annotationChild.ele('is_plain_text').txt(String(isPlainTextVal))
+                    annotationChild.ele('name').txt(getOptionalString(annotation, 'name'))
+                    annotationChild.ele('sys_id').txt(annotation.getId().getValue())
+                    annotationChild.ele('text').txt(getOptionalString(annotation, 'text'))
+                    const annotationType = annotation.get('type')
+                    if (annotationType?.isRecordId() || annotationType?.isRecord()) {
+                        const typeId = annotationType.isRecordId() ? annotationType : annotationType.getId()
+                        const typeDisplayValue = getOptionalString(annotation, 'type_display_value')
+                        annotationChild.ele('type', { display_value: typeDisplayValue }).txt(typeId.getValue())
+                    } else {
+                        annotationChild.ele('type').txt(getOptionalString(annotation, 'type'))
+                    }
+                }
+
+                // Add all sys_ui_element records for this section (excluding deleted ones)
+                const elements = sortByPosition(
+                    descendants.query('sys_ui_element').filter((element) => element.getAction() !== 'DELETE')
+                )
+
+                for (const element of elements) {
+                    const child = root.ele('sys_ui_element', { action: element.getAction() })
+                    child.ele('element').txt(element.get('element').asString().getValue())
+                    child.ele('position').txt(element.get('position').toNumber().getValue().toString())
+                    child.ele('sys_id').txt(element.getId().getValue())
+                    child.ele('sys_ui_formatter').txt(getOptionalString(element, 'sys_ui_formatter'))
+                    child
+                        .ele('sys_ui_section', {
+                            caption,
+                            display_value: caption,
+                            name: sectionName,
+                            sys_domain: sysDomain,
+                            view: viewName,
+                        })
+                        .txt(section.getId().getValue())
+                    child.ele('sys_user')
+                    child.ele('type').txt(getOptionalString(element, 'type'))
+                }
+
+                // Add the sys_ui_section record itself
+                const sectionChild = root.ele('sys_ui_section', { action: section.getAction() })
+                sectionChild.ele('caption').txt(caption)
+                sectionChild.ele('header').txt(String(section.get('header').ifBoolean()?.getValue() ?? false))
+                sectionChild.ele('name').txt(sectionName)
+                sectionChild.ele('roles').txt(getOptionalString(section, 'roles'))
+                sectionChild.ele('sys_domain').txt(sysDomain)
+                sectionChild.ele('sys_id').txt(section.getId().getValue())
+                sectionChild.ele('sys_scope', { display_value: config.scope }).txt(config.scopeId)
+                sectionChild.ele('sys_user')
+                sectionChild.ele('title').txt(String(section.get('title').ifBoolean()?.getValue() ?? false))
+                sectionChild.ele('view_name')
+                sectionChild.ele('view', viewDisplayName ? { name: viewDisplayName } : {}).txt(viewName)
+
+                return {
+                    success: true,
+                    value: {
+                        source: section,
+                        name: `sys_ui_section_${section.getId().getValue()}.xml`,
+                        category: section.getInstallCategory(),
+                        content: xml.end({ prettyPrint: true }),
+                    },
+                }
+            },
+            async diff(existing, incoming, _, { factory }) {
+                // If either database is empty, return the incoming as-is or empty database
+                if (incoming.query().length === 0 || existing.query().length === 0) {
+                    return {
+                        success: true,
+                        value: incoming.query().length === 0 ? new Database() : new Database(incoming.query()),
+                    }
+                }
+
+                const changeDatabase = new Database()
+                let hasChanges = false
+
+                const existingSection = existing.query('sys_ui_section')[0]
+                const incomingSection = incoming.query('sys_ui_section')[0]
+                const existingElements = existing.query('sys_ui_element')
+                const incomingElements = incoming.query('sys_ui_element')
+                const existingAnnotations = existing.query('sys_ui_annotation')
+                const incomingAnnotations = incoming.query('sys_ui_annotation')
+
+                // 1. Compare and merge the main form record
+                if (incomingSection && existingSection) {
+                    if (!existingSection.strictEquals(incomingSection)) {
+                        changeDatabase.insert(existingSection.merge(incomingSection))
+                        hasChanges = true
+                    }
+                } else if (incomingSection) {
+                    changeDatabase.insert(incomingSection)
+                    hasChanges = true
+                }
+
+                // 2. Compare and merge sys_ui_annotation records
+                const markAnnotationsForRemoval: Record[] = []
+                for (const annotation of existingAnnotations) {
+                    const match = incoming.resolve(annotation.getId())
+                    if (!match) {
+                        hasChanges = true
+                        markAnnotationsForRemoval.push(annotation)
+                    } else {
+                        hasChanges = hasChanges || !annotation.strictEquals(match)
+                        changeDatabase.insert(annotation.merge(match))
+                    }
+                }
+
+                // Add new annotations
+                incomingAnnotations.forEach((annotation) => {
+                    const match = changeDatabase.resolve(annotation.getId())
+                    if (!match) {
+                        changeDatabase.insert(annotation)
+                        hasChanges = true
+                    }
+                })
+
+                // Delete removed annotations
+                for (const annotation of markAnnotationsForRemoval) {
+                    const deleteRecord = await factory.createRecord({
+                        source: annotation.getSource(),
+                        table: 'sys_ui_annotation',
+                        explicitId: annotation.getId(),
+                        properties: annotation.properties(),
+                        action: 'DELETE',
+                    })
+                    changeDatabase.insert(deleteRecord)
+                }
+
+                // 3. Compare and merge sys_ui_element records
+                const markElementsForRemoval: Record[] = []
+                for (const element of existingElements) {
+                    const match = incoming.resolve(element.getId())
+                    if (!match) {
+                        hasChanges = true
+                        markElementsForRemoval.push(element)
+                    } else {
+                        hasChanges = hasChanges || !element.strictEquals(match)
+                        changeDatabase.insert(element.merge(match))
+                    }
+                }
+
+                // Add new elements
+                incomingElements.forEach((element) => {
+                    const match = changeDatabase.resolve(element.getId())
+                    if (!match) {
+                        changeDatabase.insert(element)
+                        hasChanges = true
+                    }
+                })
+
+                // Delete removed elements
+                for (const element of markElementsForRemoval) {
+                    const deleteRecord = await factory.createRecord({
+                        source: element.getSource(),
+                        table: 'sys_ui_element',
+                        explicitId: element.getId(),
+                        properties: element.properties(),
+                        action: 'DELETE',
+                    })
+                    changeDatabase.insert(deleteRecord)
+                }
+
+                return {
+                    success: true,
+                    value: hasChanges ? changeDatabase : new Database(),
+                }
+            },
+        },
+        sys_ui_element: {
+            coalesce: ['sys_ui_section', 'element', 'position'],
+        },
+        sys_ui_form_section: {
+            coalesce: ['sys_ui_form', 'sys_ui_section'],
+        },
+        sys_ui_form: {
+            coalesce: ['name', 'view', 'sys_domain'],
+            relationships: {
+                sys_ui_form_section: {
+                    via: 'sys_ui_form', // Reference column name on this table
+                    descendant: true,
+                    relationships: {
+                        sys_ui_section: {
+                            via: 'sys_ui_section',
+                            inverse: true, // Indicates the parent refers to this table
+                            descendant: true,
+                            relationships: {
+                                sys_ui_element: {
+                                    via: 'sys_ui_section',
+                                    descendant: true,
+                                    relationships: {
+                                        sys_ui_annotation: {
+                                            via: 'element',
+                                            inverse: true,
+                                            descendant: true,
+                                        },
+                                    },
+                                },
+                                sys_ui_view: {
+                                    via: 'view',
+                                    inverse: true,
+                                },
+                            },
+                        },
+                    },
+                },
+                sys_ui_view: {
+                    via: 'view',
+                    inverse: true,
+                },
+            },
+            toShape(record, { descendants, database }) {
+                const sections = sortByPosition(descendants.query('sys_ui_form_section'))
+                    .map((formSection) => {
+                        // Get section ID from form_section record
+                        const sectionId = formSection.get('sys_ui_section')
+
+                        // Find the section record
+                        const section = descendants.query('sys_ui_section').find((s) => s.getId().equals(sectionId))
+
+                        if (!section) {
+                            return null
+                        }
+
+                        // Get section caption
+                        const caption = section.get('caption').ifString()?.getValue() ?? ''
+                        const header = section.get('header')?.ifBoolean()?.getValue() ?? false
+                        const title = section.get('title')?.ifBoolean()?.getValue() ?? false
+
+                        // Get elements for this section, sorted by position
+                        const sortedElements = sortByPosition(
+                            descendants
+                                .query('sys_ui_element')
+                                .filter((elem) => elem.get('sys_ui_section').equals(sectionId))
+                        )
+
+                        // Group flat elements into layout blocks (one-column / two-column)
+                        const content = groupElementsIntoLayoutBlocks(sortedElements, descendants)
+
+                        return {
+                            caption,
+                            content,
+                            ...(header && { header }),
+                            ...(title && { title }),
+                        }
+                    })
+                    .filter(Boolean) // Remove any nulls
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'Form',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                table: $.from('name'),
+                                view: $.map((v) => {
+                                    if (v.equals(DEFAULT_VIEW)) {
+                                        return new IdentifierShape({ source: record, name: 'default_view' })
+                                    }
+                                    // Reuse resolveView to resolve the view value to its name
+                                    const resolved = resolveView(v, database)
+                                    if (resolved.name && resolved.name !== DEFAULT_VIEW) {
+                                        return resolved.name
+                                    }
+                                    return v.ifString() ?? v.toRecordId()
+                                }),
+                                user: $.from('sys_user').def(''),
+                                roles: $.from('roles')
+                                    .map((v) => {
+                                        return v.isString() && !v.isEmpty()
+                                            ? v
+                                                  .asString()
+                                                  .getValue()
+                                                  .split(',')
+                                                  .map((role) => role.trim())
+                                            : []
+                                    })
+                                    .def([]),
+                                sections: $.val(sections),
+                            })),
+                        ],
+                    }),
+                }
+            },
+            toFile(form, { config, descendants, database }) {
+                if (!form.has('name')) {
+                    return { success: false }
+                }
+
+                // For DELETE records, output a simple delete XML
+                if (form.getAction() === 'DELETE') {
+                    const xml = create().ele('record_update', { table: 'sys_ui_form' })
+                    const child = xml.ele('sys_ui_form', { action: 'DELETE' })
+                    child.ele('sys_id').txt(form.getId().getValue())
+                    child.ele('sys_scope', { display_value: config.scope }).txt(config.scopeId)
+                    child.ele('sys_update_name').txt(`sys_ui_form_sections_${form.getId().getValue()}`)
+                    return {
+                        success: true,
+                        value: {
+                            source: form,
+                            name: `sys_ui_form_sections_${form.getId().getValue()}.xml`,
+                            category: form.getInstallCategory(),
+                            content: xml.end({ prettyPrint: true }),
+                        },
+                    }
+                }
+
+                const formName = form.get('name').asString().getValue()
+                const formSysDomain = getOptionalString(form, 'sys_domain', 'global')
+                const { sysId: formViewName, name: formViewDisplayName } = resolveView(form.get('view'), database)
+
+                const xml = create().ele('record_update')
+                const root = xml.ele('sys_ui_form_sections', {
+                    form_id: form.getId().getValue(),
+                    sys_domain: formSysDomain,
+                    table: formName,
+                })
+
+                // Add all sys_ui_form_section records (excluding deleted ones)
+                const formSections = sortByPosition(
+                    descendants
+                        .query('sys_ui_form_section')
+                        .filter((formSection) => formSection.getAction() !== 'DELETE')
+                )
+
+                for (const formSection of formSections) {
+                    const child = root.ele('sys_ui_form_section', { action: 'INSERT_OR_UPDATE' })
+                    child.ele('position').txt(formSection.get('position').toNumber().getValue().toString())
+                    child.ele('sys_id').txt(formSection.getId().getValue())
+                    child
+                        .ele('sys_ui_form', {
+                            display_value: formName,
+                            name: formName,
+                            sys_domain: formSysDomain,
+                            view: formViewName,
+                        })
+                        .txt(form.getId().getValue())
+
+                    // Add section reference
+                    const sectionId = formSection.get('sys_ui_section')
+                    const section = descendants.query('sys_ui_section').find((s) => s.getId().equals(sectionId))
+
+                    if (section) {
+                        const sectionCaption = getOptionalString(section, 'caption')
+                        const sectionViewName = resolveViewName(section.get('view'), database)
+                        child
+                            .ele('sys_ui_section', {
+                                caption: sectionCaption,
+                                display_value: sectionCaption,
+                                name: formName,
+                                sys_domain: getOptionalString(section, 'sys_domain', 'global'),
+                                view: sectionViewName,
+                            })
+                            .txt(section.getId().getValue())
+                    }
+                }
+
+                // Add the sys_ui_form record itself
+                const formChild = root.ele('sys_ui_form', { action: 'INSERT_OR_UPDATE' })
+                formChild.ele('name').txt(formName)
+                formChild.ele('roles').txt(getOptionalString(form, 'roles'))
+                formChild.ele('sys_id').txt(form.getId().getValue())
+                formChild.ele('sys_scope', { display_value: config.scope }).txt(config.scopeId)
+                formChild.ele('sys_user').txt(getOptionalString(form, 'sys_user'))
+                formChild.ele('view', formViewDisplayName ? { name: formViewDisplayName } : {}).txt(formViewName)
+                formChild.ele('view_name')
+
+                return {
+                    success: true,
+                    value: {
+                        source: form,
+                        name: `sys_ui_form_sections_${form.getId().getValue()}.xml`,
+                        category: form.getInstallCategory(),
+                        content: xml.end({ prettyPrint: true }),
+                    },
+                }
+            },
+            async diff(existingDB, incomingDB, _, { factory }) {
+                /**
+                 * Exclude sys_ui_section and sys_ui_element records from this diff to handle incremental updates correctly.
+                 *
+                 * Why: If a user modifies only a UI section during incremental transformation, we don't want that change
+                 * to trigger a diff in sys_ui_form that would incorrectly remove form_sections. Instead, sys_ui_section
+                 * and sys_ui_element records are compared separately using their own dedicated diff function.
+                 */
+                const incoming = incomingDB.query().filter((r) => FORM_XML_TABLES.includes(r.getTable()))
+                const existing = existingDB.query().filter((r) => FORM_XML_TABLES.includes(r.getTable()))
+
+                // If either database is empty, return the incoming as-is or empty database
+                if (incoming.length === 0 || existing.length === 0) {
+                    return {
+                        success: true,
+                        value: incoming.length === 0 ? new Database() : new Database(incoming),
+                    }
+                }
+
+                const changeDatabase = new Database()
+                let hasChanges = false
+
+                // Get the main records
+                const existingForm = existing.filter((r) => r.getTable() === 'sys_ui_form')[0]
+                const incomingForm = incoming.filter((r) => r.getTable() === 'sys_ui_form')[0]
+                const existingFormSections = existing.filter((r) => r.getTable() === 'sys_ui_form_section')
+                const incomingFormSections = incoming.filter((r) => r.getTable() === 'sys_ui_form_section')
+
+                // 1. Compare and merge the main form record
+                if (incomingForm && existingForm) {
+                    if (!existingForm.strictEquals(incomingForm)) {
+                        changeDatabase.insert(existingForm.merge(incomingForm))
+                        hasChanges = true
+                    }
+                } else if (incomingForm) {
+                    changeDatabase.insert(incomingForm)
+                    hasChanges = true
+                }
+
+                // 2. Compare and merge sys_ui_form_section records (join table)
+                const markFormSectionsForRemoval: Record[] = []
+                for (const formSection of existingFormSections) {
+                    const match = incomingDB.resolve(formSection.getId())
+                    if (!match) {
+                        hasChanges = true
+                        markFormSectionsForRemoval.push(formSection)
+                    } else {
+                        hasChanges = hasChanges || !formSection.strictEquals(match)
+                        changeDatabase.insert(formSection.merge(match))
+                    }
+                }
+
+                incomingFormSections.forEach((formSection) => {
+                    const match = changeDatabase.resolve(formSection.getId())
+                    if (!match) {
+                        changeDatabase.insert(formSection)
+                        hasChanges = true
+                    }
+                })
+
+                // Delete removed form sections
+                for (const formSection of markFormSectionsForRemoval) {
+                    const deleteRecord = await factory.createRecord({
+                        source: formSection.getSource(),
+                        table: 'sys_ui_form_section',
+                        explicitId: formSection.getId(),
+                        properties: formSection.properties(),
+                        action: 'DELETE',
+                    })
+                    changeDatabase.insert(deleteRecord)
+                }
+
+                return {
+                    success: true,
+                    value: hasChanges ? changeDatabase : new Database(),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics }) {
+                if (callExpression.getCallee() !== 'Form') {
+                    return { success: false }
+                }
+
+                const arg = callExpression.getArgument(0).asObject()
+                const tableArg = arg.get('table')
+                const tableName = tableArg.ifString()
+
+                // View handling: supports Record, RecordId, and string (aligned with ListPlugin)
+                const viewArg = arg.get('view')
+
+                let viewReference: Record | RecordId | string
+
+                if (viewArg.isRecord()) {
+                    viewReference = viewArg.asRecord()
+                } else if (viewArg.isRecordId()) {
+                    viewReference = viewArg.asRecordId()
+                } else if (viewArg.isString()) {
+                    const stringValue = viewArg.asString().getValue()
+                    // Diagnostic 1: 'Default view' string literal footgun
+                    if (stringValue === DEFAULT_VIEW) {
+                        diagnostics.error(
+                            viewArg,
+                            `Do not use the hard-coded string '${DEFAULT_VIEW}' as the view. ` +
+                                `Use the exported 'default_view' identifier instead: view: default_view`
+                        )
+                        return { success: false }
+                    }
+                    viewReference = await factory.createReference({
+                        source: callExpression,
+                        table: 'sys_ui_view',
+                        keys: { name: stringValue },
+                    })
+                } else {
+                    // Default for any other case
+                    viewReference = DEFAULT_VIEW
+                }
+
+                // Process roles if they exist as an array
+                let rolesValue = ''
+                const rolesArray = arg.get('roles').ifArray()?.getElements() ?? []
+                if (rolesArray.length > 0) {
+                    rolesValue = rolesArray
+                        .map((role) => {
+                            if (role.isString()) {
+                                return role.asString().getValue()
+                            } else if (role.isObject()) {
+                                return role.get('name')?.ifString()?.getValue() ?? ''
+                            }
+                            return ''
+                        })
+                        .filter((name) => name !== '')
+                        .join(',')
+                }
+
+                // Create the main form record
+                const form = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_ui_form',
+                    properties: arg.transform(({ $ }) => ({
+                        name: $.val(tableName),
+                        view: $.val(viewReference),
+                        sys_user: $.from('user'),
+                        sys_domain: $.val('global'),
+                        roles: $.val(rolesValue).def(''),
+                    })),
+                })
+                // Process all sections
+                const sections = arg.get('sections').ifArray()?.getElements() || []
+                if (sections.length === 0) {
+                    diagnostics.error(arg.get('sections'), `Form does not have any sections. Add at least one section.`)
+                }
+                const sectionRecords: Record[] = []
+                const formSectionRecords: Record[] = []
+                const elementRecords: Record[] = []
+                const seenCaptions = new Map<string, number>()
+                const globalSeenFields = new Set<string>()
+
+                for (let sectionIndex = 0; sectionIndex < sections.length; sectionIndex++) {
+                    const sectionObj = sections[sectionIndex]?.asObject()
+                    if (!sectionObj) {
+                        continue
+                    }
+                    const caption = sectionObj.get('caption').ifString()?.getValue() ?? ''
+
+                    // Diagnostic 2: Empty section caption
+                    if (!caption.trim()) {
+                        diagnostics.warn(sectionObj.get('caption'), `Section caption cannot be empty.`)
+                    }
+
+                    // Diagnostic 3: Duplicate section captions
+                    // Note: When two sections share the same caption, fluent merges them into
+                    // a single section on the instance due to coalesce keys. This may be unexpected if captions collide by accident.
+                    if (caption.trim()) {
+                        const prevIndex = seenCaptions.get(caption)
+                        if (prevIndex !== undefined) {
+                            diagnostics.error(
+                                sectionObj.get('caption'),
+                                `Duplicate section caption '${caption}'. Each section must have a unique caption.`
+                            )
+                        } else {
+                            seenCaptions.set(caption, sectionIndex)
+                        }
+                    }
+                    // Create the section record
+                    const section = await factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_ui_section',
+                        properties: sectionObj.transform(({ $ }) => ({
+                            name: $.val(tableName),
+                            caption: $.val(caption),
+                            title: $.def(false),
+                            header: $.def(false),
+                            view: $.val(viewReference),
+                            sys_domain: $.val('global'),
+                        })),
+                    })
+
+                    sectionRecords.push(section)
+
+                    // Create the form-section linking record
+                    const formSection = await factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_ui_form_section',
+                        properties: arg.transform(({ $ }) => ({
+                            sys_ui_form: $.val(form),
+                            sys_ui_section: $.val(section.getId()),
+                            position: $.val(sectionIndex),
+                        })),
+                    })
+                    formSectionRecords.push(formSection)
+
+                    // Process content layout blocks
+                    await processContentBlocks(
+                        arg,
+                        sectionObj,
+                        callExpression,
+                        factory,
+                        section,
+                        elementRecords,
+                        diagnostics,
+                        caption,
+                        globalSeenFields
+                    )
+                }
+
+                return {
+                    success: true,
+                    value: form.with(...sectionRecords, ...formSectionRecords, ...elementRecords),
+                }
+            },
+        },
+    ],
+})
+/**
+ * Creates a sys_ui_element record
+ */
+async function createUiElement(
+    arg: ObjectShape,
+    callExpression: CallExpressionShape,
+    factory: Factory,
+    section: Record,
+    element: string,
+    position: number,
+    type: string = '',
+    formatter: string = ''
+) {
+    return await factory.createRecord({
+        source: callExpression,
+        table: 'sys_ui_element',
+        properties: arg.transform(({ $ }) => ({
+            sys_ui_section: $.val(section.getId()),
+            element: $.val(element),
+            position: $.val(position),
+            type: $.val(type),
+            sys_ui_formatter: $.val(formatter),
+        })),
+    })
+}
+
+/**
+ * Processes the content layout blocks in a form section and creates UI element records.
+ * Reads the `content` array of layout blocks (one-column / two-column) and flattens them
+ * into sys_ui_element records with proper positioning and split markers.
+ */
+async function processContentBlocks(
+    arg: ObjectShape,
+    sectionObj: ObjectShape,
+    callExpression: CallExpressionShape,
+    factory: Factory,
+    section: Record,
+    elementRecords: Record[],
+    diagnostics: Diagnostics,
+    caption: string,
+    globalSeenFields: Set<string>
+) {
+    const contentBlocks = sectionObj.get('content').ifArray()?.getElements() || []
+    let position = 0
+    const seenFields = new Set<string>()
+
+    // Diagnostic 6: Empty content blocks
+    if (contentBlocks.length === 0) {
+        diagnostics.warn(
+            sectionObj.get('content'),
+            `Section '${caption}' has no content blocks. The section will be empty on the form.`
+        )
+    }
+
+    /** Processes an array of element shapes, reporting errors for non-object entries. */
+    async function processElements(
+        elements: ReturnType<NonNullable<ReturnType<Shape['ifArray']>>['getElements']>,
+        context: string
+    ) {
+        for (const elem of elements) {
+            if (!elem || !elem.isObject()) {
+                diagnostics.error(
+                    elem ?? sectionObj,
+                    `Invalid element in ${context} of section '${caption}'. Each element must be an object.`
+                )
+                continue
+            }
+            position = await processFormElement(
+                arg,
+                callExpression,
+                factory,
+                section,
+                elementRecords,
+                elem.asObject(),
+                position,
+                diagnostics,
+                seenFields,
+                caption,
+                globalSeenFields
+            )
+        }
+    }
+
+    for (let blockIdx = 0; blockIdx < contentBlocks.length; blockIdx++) {
+        const block = contentBlocks[blockIdx]
+        if (!block || !block.isObject()) {
+            diagnostics.error(
+                block ?? sectionObj,
+                `Content block at index ${blockIdx} in section '${caption}' must be an object.`
+            )
+            continue
+        }
+        const blockObj = block.asObject()
+        const layout = blockObj.get('layout').ifString()?.getValue()
+
+        if (!layout || (layout !== 'one-column' && layout !== 'two-column')) {
+            diagnostics.error(
+                blockObj.get('layout'),
+                `Layout block requires 'layout' property set to 'one-column' or 'two-column'.`
+            )
+            continue
+        }
+
+        if (layout === 'one-column') {
+            await processElements(blockObj.get('elements').ifArray()?.getElements() || [], 'one-column block')
+        } else {
+            // Diagnostic 5: Empty two-column sides
+            const leftElements = blockObj.get('leftElements').ifArray()?.getElements() || []
+            const rightElements = blockObj.get('rightElements').ifArray()?.getElements() || []
+            if (leftElements.length === 0) {
+                diagnostics.warn(
+                    blockObj.get('leftElements'),
+                    `Two-column layout block at index ${blockIdx} in section '${caption}' has empty 'leftElements'. Consider using a one-column layout instead.`
+                )
+            }
+            if (rightElements.length === 0) {
+                diagnostics.warn(
+                    blockObj.get('rightElements'),
+                    `Two-column layout block at index ${blockIdx} in section '${caption}' has empty 'rightElements'. Consider using a one-column layout instead.`
+                )
+            }
+
+            // two-column: emit .begin_split, left elements, .split, right elements, .end_split
+            elementRecords.push(
+                await createUiElement(
+                    arg,
+                    callExpression,
+                    factory,
+                    section,
+                    SPLIT_TYPE.BEGIN,
+                    position++,
+                    SPLIT_TYPE.BEGIN
+                )
+            )
+            await processElements(leftElements, 'two-column leftElements')
+            elementRecords.push(
+                await createUiElement(
+                    arg,
+                    callExpression,
+                    factory,
+                    section,
+                    SPLIT_TYPE.MIDDLE,
+                    position++,
+                    SPLIT_TYPE.MIDDLE
+                )
+            )
+            await processElements(rightElements, 'two-column rightElements')
+            elementRecords.push(
+                await createUiElement(arg, callExpression, factory, section, SPLIT_TYPE.END, position++, SPLIT_TYPE.END)
+            )
+        }
+    }
+}
+
+/**
+ * Processes a single form element object and creates the appropriate record(s).
+ * Handles table_field, annotation, formatter, and list element types.
+ * Returns the next position index.
+ */
+async function processFormElement(
+    arg: ObjectShape,
+    callExpression: CallExpressionShape,
+    factory: Factory,
+    section: Record,
+    elementRecords: Record[],
+    field: ObjectShape,
+    position: number,
+    diagnostics: Diagnostics,
+    seenFields: Set<string>,
+    caption: string,
+    globalSeenFields: Set<string>
+): Promise<number> {
+    const typeField = field.get('type').ifString()?.getValue() ?? ''
+
+    const validTypes = ['table_field', 'annotation', 'formatter', 'list']
+    if (!validTypes.includes(typeField)) {
+        diagnostics.error(
+            field.get('type'),
+            `Invalid type '${typeField}'. Valid types are: ${validTypes.map((t) => `'${t}'`).join(', ')}`
+        )
+        return position
+    }
+
+    // ── table_field ──
+    if (typeField === 'table_field') {
+        const fieldName = field.get('field').ifString()?.getValue() ?? ''
+        if (!fieldName) {
+            diagnostics.error(field.get('field'), `Table field element requires a 'field' property.`)
+            return position
+        }
+        // Duplicate field check within the same section
+        if (seenFields.has(fieldName)) {
+            diagnostics.error(
+                field,
+                `Duplicate field '${fieldName}' in section '${caption}'. Each field should only appear once per section.`
+            )
+        }
+        seenFields.add(fieldName)
+
+        // Diagnostic 4: Duplicate field across sections
+        if (globalSeenFields.has(fieldName)) {
+            diagnostics.warn(
+                field,
+                `Field '${fieldName}' already appears in another section. Duplicate fields across sections may cause unexpected behavior on the form.`
+            )
+        }
+        globalSeenFields.add(fieldName)
+
+        elementRecords.push(await createUiElement(arg, callExpression, factory, section, fieldName, position))
+        return position + 1
+    }
+
+    // ── annotation ──
+    if (typeField === 'annotation') {
+        const annotationIdField = field.get('annotationId')
+
+        if (
+            !(annotationIdField instanceof ElementAccessExpressionShape && annotationIdField.getCallee() === 'Now.ID')
+        ) {
+            diagnostics.error(annotationIdField, `'annotationId' must be a Now.ID['...'] reference.`)
+            return position
+        }
+        const explicitId: Shape = annotationIdField
+
+        const textValue = field.get('text').ifString()?.getValue() ?? ''
+        const isPlainText = field.get('isPlainText').ifBoolean()?.getValue() ?? true
+
+        // Handle annotationType - can be AnnotationType record or string GUID
+        const annotationTypeArg = field.get('annotationType')
+        let annotationTypeValue = DEFAULT_ANNOTATION_TYPE
+
+        if (annotationTypeArg) {
+            if (annotationTypeArg.isRecord()) {
+                annotationTypeValue = annotationTypeArg.asRecord().getId().getValue()
+            } else if (annotationTypeArg.isString()) {
+                const annotationTypeStr = annotationTypeArg.asString().getValue()
+                if (annotationTypeStr in AnnotationType) {
+                    annotationTypeValue = AnnotationType[annotationTypeStr as keyof typeof AnnotationType]
+                } else if (isGUID(annotationTypeStr)) {
+                    annotationTypeValue = annotationTypeStr
+                } else {
+                    showGuidFieldDiagnostic(annotationTypeArg, 'annotationType', 'sys_ui_annotation_type', diagnostics)
+                }
+            }
+        }
+
+        // Create sys_ui_annotation record
+        const annotationRecord = await factory.createRecord({
+            source: callExpression,
+            table: 'sys_ui_annotation',
+            explicitId: explicitId,
+            properties: arg.transform(({ $ }) => ({
+                text: $.val(textValue),
+                is_plain_text: $.val(isPlainText).def(true),
+                type: $.val(annotationTypeValue),
+            })),
+        })
+        elementRecords.push(annotationRecord)
+
+        // Create sys_ui_element with element = annotation sys_id
+        elementRecords.push(
+            await createUiElement(
+                arg,
+                callExpression,
+                factory,
+                section,
+                annotationRecord.getId().getValue(),
+                position,
+                'annotation'
+            )
+        )
+        return position + 1
+    }
+
+    // ── formatter ──
+    if (typeField === 'formatter') {
+        const formatterRefArg = field.get('formatterRef')
+        let formatterRefValue = ''
+        let recordFormatterField = ''
+
+        if (formatterRefArg) {
+            if (formatterRefArg.isRecord()) {
+                const record = formatterRefArg.asRecord()
+                formatterRefValue = record.getId().getValue()
+                // Try to read the `formatter` column from the Record data
+                recordFormatterField = record.get('formatter')?.ifString()?.getValue() ?? ''
+            } else if (formatterRefArg.isString()) {
+                const formatterStr = formatterRefArg.asString().getValue()
+                if (formatterStr in Formatter) {
+                    formatterRefValue = Formatter[formatterStr as keyof typeof Formatter]
+                } else if (isGUID(formatterStr)) {
+                    formatterRefValue = formatterStr
+                } else {
+                    showGuidFieldDiagnostic(formatterRefArg, 'formatterRef', 'sys_ui_formatter', diagnostics)
+                }
+            }
+        }
+
+        // formatterName is optional — derive in order: explicit > Record `formatter` field > FORMATTER_ELEMENT_MAP > empty
+        let formatterName = field.get('formatterName').ifString()?.getValue() ?? ''
+        if (!formatterName && recordFormatterField) {
+            formatterName = recordFormatterField
+        }
+        if (!formatterName && formatterRefValue) {
+            formatterName = FORMATTER_ELEMENT_MAP.get(formatterRefValue) ?? ''
+        }
+
+        elementRecords.push(
+            await createUiElement(
+                arg,
+                callExpression,
+                factory,
+                section,
+                formatterName,
+                position,
+                'formatter',
+                formatterRefValue
+            )
+        )
+        return position + 1
+    }
+
+    // ── list ──
+    if (typeField === 'list') {
+        const listType = field.get('listType').ifString()?.getValue() ?? ''
+        if (!listType || !['12M', 'M2M', 'custom'].includes(listType)) {
+            diagnostics.error(
+                field.get('listType'),
+                `List element requires 'listType' set to '12M', 'M2M', or 'custom'.`
+            )
+            return position
+        }
+
+        let elementValue = ''
+        const tableName = arg.get('table').asString().getValue()
+        const listRefArg = field.get('listRef')
+
+        if (listType === 'custom') {
+            // Custom lists use Record<'sys_relationship'> reference or string GUID via 'listRef' key
+            if (listRefArg.isRecord()) {
+                const relSysId = listRefArg.asRecord().getId().getValue()
+                elementValue = `REL.${tableName}.REL:${relSysId}`
+            } else if (listRefArg.isString()) {
+                const relStr = listRefArg.asString().getValue()
+                if (isGUID(relStr)) {
+                    elementValue = `REL.${tableName}.REL:${relStr}`
+                } else {
+                    showGuidFieldDiagnostic(listRefArg, 'listRef', 'sys_relationship', diagnostics)
+                    return position
+                }
+            } else {
+                diagnostics.error(
+                    listRefArg,
+                    `Custom list requires 'listRef' with a Record<'sys_relationship'> reference or a sys_relationship sys_id string (GUID).`
+                )
+                return position
+            }
+        } else {
+            // 12M and M2M use listRef as 'table.column' dot-notation string
+            if (!listRefArg.isString()) {
+                diagnostics.error(
+                    field,
+                    `List element requires 'listRef' as a dot-notation string '<table_name>.<column_name>' for '${listType}' type.`
+                )
+                return position
+            }
+
+            const listRefStr = listRefArg.asString().getValue()
+            const parts = listRefStr.split('.')
+            if (parts.length !== 2 || !parts[0] || !parts[1]) {
+                diagnostics.error(
+                    listRefArg,
+                    `Invalid 'listRef' format '${listRefStr}'. Expected '<table_name>.<column_name>' (e.g., 'task_sla.task').`
+                )
+                return position
+            }
+
+            const [listTable, listColumn] = parts
+            elementValue = `${listType}.${tableName}.${listTable}.${listColumn}`
+        }
+
+        elementRecords.push(
+            await createUiElement(arg, callExpression, factory, section, elementValue, position, 'list')
+        )
+        return position + 1
+    }
+
+    return position
+}