@rippling/rippling-sdk 0.2.0-alpha.44 → 0.2.0-alpha.46

package/lib/manifest/custom-object-page-layout.mjs

@@ -14,6 +14,35 @@ function isFieldRef(value) {
     const candidate = value;
     return candidate != null && typeof candidate === 'object' && isField(candidate.field);
 }
+const FIELD_SECTION_ID = Symbol('CustomObjectPageLayout.fieldSectionId');
+function isCustomObjectFieldSection(value) {
+    return value instanceof CustomObjectFieldSection;
+}
+function attachFieldSectionId(section, sectionId) {
+    Object.defineProperty(section, FIELD_SECTION_ID, {
+        value: sectionId,
+        enumerable: false,
+        configurable: true,
+    });
+    return section;
+}
+function layoutSectionKey(section) {
+    return section[FIELD_SECTION_ID];
+}
+function layoutSectionMatches(section, sectionKey) {
+    return layoutSectionKey(section) === sectionKey;
+}
+function inputFieldsSectionHasKey(input) {
+    const record = input;
+    return Object.prototype.hasOwnProperty.call(record, 'key') && record['key'] != null;
+}
+function assertNoSerializedSectionKey(section) {
+    const record = section;
+    if (Object.prototype.hasOwnProperty.call(record, 'key') && record['key'] != null) {
+        throw new Error('CustomObjectPageLayout loaded fields_section key is not supported. ' +
+            'Remove key and target the section with CustomObjectFieldSection metadata.');
+    }
+}
 function assertSameObject(customObject, field, sectionKey) {
     if (field.getCustomObjectApiName() !== customObject.getApiName()) {
         throw new Error(`CustomObjectPageLayout fields_section "${sectionKey}" references field "${field.getApiName()}" ` +
@@ -26,6 +55,21 @@ function assertSectionBelongsTo(customObject, section) {
             `but the layout belongs to "${customObject.getApiName()}".`);
     }
 }
+function requireFieldSectionOption(value, label) {
+    if (isCustomObjectFieldSection(value))
+        return value;
+    if (typeof value === 'string') {
+        throw new TypeError(`${label} must be a CustomObjectFieldSection object; received raw section id "${value}". ` +
+            'Load/include the existing field section first.');
+    }
+    throw new TypeError(`${label} must be a CustomObjectFieldSection object.`);
+}
+function assertOptionAbsent(options, key, message) {
+    if (options == null || typeof options !== 'object')
+        return;
+    if (Object.prototype.hasOwnProperty.call(options, key))
+        throw new TypeError(message);
+}
 function toSerializedSectionField(fieldRqlName, options = {}) {
     const normalized = { fieldRqlName };
     if (options.hidden != null)
@@ -52,17 +96,19 @@ function normalizeSectionField(customObject, section, sectionKey, entry) {
 }
 function normalizeFieldsSection(customObject, input) {
     assertSectionBelongsTo(customObject, input.section);
-    const key = input.key ?? input.section.getSectionId();
+    const sectionId = input.section.getSectionId();
+    if (inputFieldsSectionHasKey(input)) {
+        throw new Error('CustomObjectPageLayout fields_section key is not supported. Omit key.');
+    }
     const name = input.name ?? input.section.getName();
     const normalized = {
-        key,
         name,
         type: 'fields_section',
-        fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, key, field)),
+        fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, sectionId, field)),
     };
     if (input.layout != null)
         normalized.layout = input.layout;
-    return normalized;
+    return attachFieldSectionId(normalized, sectionId);
 }
 function normalizeTab(customObject, tab) {
     if (tab.type === 'custom_tab')
@@ -115,6 +161,68 @@ function cloneJson(value) {
         return value;
     return JSON.parse(JSON.stringify(value));
 }
+const HEADER_EDIT_KEYS = new Set([
+    'newTitleField',
+    'titleFieldDeleted',
+    'newDescriptionField',
+    'descriptionFieldDeleted',
+    'systemFieldEdits',
+    'newFields',
+    'headerFieldsOrder',
+    'buttons',
+]);
+const SYSTEM_HEADER_FIELD_EDIT_KEYS = new Set(['newRqlField', 'deleted']);
+const NEW_HEADER_FIELD_KEYS = new Set(['rqlName', 'key', 'canBeDeleted', 'canBeChanged', 'canBeMoved']);
+function assertKnownKeys(record, allowedKeys, label, hint) {
+    for (const key of Object.keys(record)) {
+        if (!allowedKeys.has(key)) {
+            throw new Error(`${label} contains unsupported key "${key}". ${hint}`);
+        }
+    }
+}
+function normalizeHeaderEdits(headerEdits) {
+    assertKnownKeys(headerEdits, HEADER_EDIT_KEYS, 'CustomObjectPageLayout headerEdits', 'Use addHeaderField(), setTitleField(), setDescriptionField(), or the HeaderEdits keys documented by the SDK.');
+    for (const [key, edit] of Object.entries(headerEdits.systemFieldEdits ?? {})) {
+        assertKnownKeys(edit, SYSTEM_HEADER_FIELD_EDIT_KEYS, `CustomObjectPageLayout headerEdits.systemFieldEdits.${key}`, 'Use newRqlField and deleted for system header field edits.');
+    }
+    for (const [index, field] of (headerEdits.newFields ?? []).entries()) {
+        assertKnownKeys(field, NEW_HEADER_FIELD_KEYS, `CustomObjectPageLayout headerEdits.newFields[${index}]`, 'Use { rqlName, key } entries, or call addHeaderField(field).');
+    }
+    if (headerEdits.headerFieldsOrder == null)
+        return headerEdits;
+    return {
+        ...headerEdits,
+        headerFieldsOrder: normalizeHeaderFieldsOrder(headerEdits),
+    };
+}
+function addUniqueHeaderOrderField(order, field) {
+    if (typeof field !== 'string' || field.length === 0)
+        return;
+    if (!order.includes(field))
+        order.push(field);
+}
+function normalizeHeaderFieldsOrder(headerEdits) {
+    const customFieldRqlByKey = new Map((headerEdits.newFields ?? []).map((field) => [field.key, field.rqlName]));
+    const systemFieldRqlByKey = new Map(Object.entries(headerEdits.systemFieldEdits ?? {})
+        .filter((entry) => {
+        const [, edit] = entry;
+        return typeof edit.newRqlField === 'string' && edit.newRqlField.length > 0;
+    })
+        .map(([key, edit]) => [key, edit.newRqlField]));
+    const order = [];
+    for (const entry of headerEdits.headerFieldsOrder ?? []) {
+        addUniqueHeaderOrderField(order, customFieldRqlByKey.get(entry) ?? systemFieldRqlByKey.get(entry) ?? entry);
+    }
+    addUniqueHeaderOrderField(order, headerEdits.newTitleField);
+    addUniqueHeaderOrderField(order, headerEdits.newDescriptionField);
+    for (const field of headerEdits.newFields ?? []) {
+        addUniqueHeaderOrderField(order, field.rqlName);
+    }
+    for (const systemEdit of Object.values(headerEdits.systemFieldEdits ?? {})) {
+        addUniqueHeaderOrderField(order, systemEdit.newRqlField);
+    }
+    return order;
+}
 function isTabWithSections(tab) {
     return tab.type === 'tab_with_sections';
 }
@@ -131,6 +239,11 @@ function insertionIndex(length, position) {
 function insertAt(items, item, position) {
     items.splice(insertionIndex(items.length, position), 0, item);
 }
+function insertUniqueAt(items, item, position) {
+    if (item == null || item.length === 0 || items.includes(item))
+        return;
+    insertAt(items, item, position);
+}
 function fieldRqlNameOf(entry) {
     if (typeof entry === 'string')
         return entry;
@@ -140,6 +253,48 @@ function fieldRqlNameOf(entry) {
     const fieldRqlName = record['fieldRqlName'] ?? record['field_rql_name'];
     return typeof fieldRqlName === 'string' ? fieldRqlName : undefined;
 }
+function explicitFieldSectionId(entry) {
+    if (entry == null || typeof entry !== 'object')
+        return undefined;
+    const record = entry;
+    const fieldSectionId = record['fieldSection'] ?? record['field_section'];
+    return typeof fieldSectionId === 'string' ? fieldSectionId : undefined;
+}
+function inferredSectionIdFromFields(section, resolveFieldSectionId) {
+    const sectionIds = new Set();
+    for (const field of section.fields ?? []) {
+        const explicitSectionId = explicitFieldSectionId(field);
+        if (explicitSectionId != null) {
+            sectionIds.add(explicitSectionId);
+            continue;
+        }
+        const fieldApiName = fieldRqlNameOf(field);
+        if (fieldApiName == null || resolveFieldSectionId == null)
+            continue;
+        const resolvedSectionId = resolveFieldSectionId(fieldApiName);
+        if (resolvedSectionId != null)
+            sectionIds.add(resolvedSectionId);
+    }
+    return sectionIds.size === 1 ? [...sectionIds][0] : undefined;
+}
+function annotateLoadedFieldsSection(section, resolveFieldSectionId) {
+    assertNoSerializedSectionKey(section);
+    const sectionId = layoutSectionKey(section) ?? inferredSectionIdFromFields(section, resolveFieldSectionId);
+    return sectionId == null ? section : attachFieldSectionId(section, sectionId);
+}
+function annotateLoadedTabEdits(tabEdits, resolveFieldSectionId) {
+    for (const tab of tabEdits.newTabs ?? []) {
+        if (!isTabWithSections(tab))
+            continue;
+        tab.sections = tab.sections.map((section) => annotateLoadedFieldsSection(section, resolveFieldSectionId));
+    }
+    for (const tabEdit of Object.values(tabEdits.systemTabEdits ?? {})) {
+        if (tabEdit.newSections != null) {
+            tabEdit.newSections = tabEdit.newSections.map((section) => annotateLoadedFieldsSection(section, resolveFieldSectionId));
+        }
+    }
+    return tabEdits;
+}
 function removeIndexes(items, indexes) {
     for (const index of [...indexes].sort((a, b) => b - a)) {
         items.splice(index, 1);
@@ -213,7 +368,6 @@ function ensureArrayProperty(record, key, label) {
  *     newTabs: [{
  *       key: 'member', name: 'Member', type: 'tab_with_sections',
  *       sections: [{
- *         key: 'profile',
  *         name: 'Profile',
  *         type: 'fields_section',
  *         section: profileSection,
@@ -252,7 +406,7 @@ export class CustomObjectPageLayout {
         this._customObjectApiName = customObject.getApiName();
         this._name = props.name;
         this._tabEdits = normalizeTabEdits(customObject, props.tabEdits ?? {});
-        this._headerEdits = props.headerEdits ?? {};
+        this._headerEdits = normalizeHeaderEdits(props.headerEdits ?? {});
         this._visibilityConditions = props.visibilityConditions ?? {};
         this._blueprintKey = props.blueprintKey;
         customObject._register(this);
@@ -268,14 +422,14 @@ export class CustomObjectPageLayout {
         return getExistingManifestContext(options).loadPageLayout(layoutIdOrApiName, options);
     }
     /** @internal Hydrates a page layout from existing manifest wire JSON. */
-    static _fromExistingComponent(customObject, component) {
+    static _fromExistingComponent(customObject, component, resolveFieldSectionId) {
         const layout = Object.create(CustomObjectPageLayout.prototype);
         Object.assign(layout, {
             _layoutId: requireStringComponentField(component, 'layout_id', CustomObjectPageLayout.componentType),
             _apiName: requireStringComponentField(component, 'api_name', CustomObjectPageLayout.componentType),
             _customObjectApiName: requireStringComponentField(component, 'object_rql_name', CustomObjectPageLayout.componentType),
             _name: requireStringComponentField(component, 'name', CustomObjectPageLayout.componentType),
-            _tabEdits: cloneJson(component['tab_edits'] ?? {}),
+            _tabEdits: annotateLoadedTabEdits(cloneJson(component['tab_edits'] ?? {}), resolveFieldSectionId),
             _headerEdits: cloneJson(component['header_edits'] ?? {}),
             _visibilityConditions: cloneJson(component['visibility_conditions'] ?? {}),
             _blueprintKey: component['blueprint_key'],
@@ -313,17 +467,32 @@ export class CustomObjectPageLayout {
     /**
      * Adds multiple fields to an existing layout section.
      *
-     * Fields are inserted in the order provided. If a field does not already have
-     * field-section metadata, pass `options.fieldSection` so the corresponding
-     * `CUSTOM_OBJECT_FIELD_SECTION` component is registered in the manifest.
+     * Fields are inserted in the order provided. For custom layout sections,
+     * pass `options.section` so TypeScript and runtime validation agree on the
+     * target `CUSTOM_OBJECT_FIELD_SECTION`.
      */
     addFields(fields, options) {
         if (fields.length === 0)
             return this;
+        let fieldSectionForMutation;
         const container = options.systemSection === true ?
-            this.ensureSystemSectionFieldContainer(options.tabKey, options.sectionKey)
-            : this.requireOneFieldContainer(options.tabKey, options.sectionKey);
-        const entries = fields.map((field) => this.serializeFieldForMutation(field, options.sectionKey, options));
+            (() => {
+                assertOptionAbsent(options, 'section', 'CustomObjectPageLayout addField section is only supported for custom layout sections.');
+                assertOptionAbsent(options, 'fieldSection', 'CustomObjectPageLayout addField fieldSection is no longer supported. ' +
+                    'Use sectionKey only for systemSection: true.');
+                return this.ensureSystemSectionFieldContainer(options.tabKey, options.sectionKey);
+            })()
+            : (() => {
+                assertOptionAbsent(options, 'sectionKey', 'CustomObjectPageLayout addField sectionKey is only supported with systemSection: true. ' +
+                    'Pass section: CustomObjectFieldSection for custom layout sections.');
+                assertOptionAbsent(options, 'fieldSection', 'CustomObjectPageLayout addField fieldSection is no longer supported. ' +
+                    'Pass section: CustomObjectFieldSection instead.');
+                const section = requireFieldSectionOption(options.section, 'CustomObjectPageLayout addField section');
+                this.assertFieldSectionBelongsToLayout(section);
+                fieldSectionForMutation = section;
+                return this.requireOneFieldContainer(options.tabKey, section.getSectionId(), section);
+            })();
+        const entries = fields.map((field) => this.serializeFieldForMutation(field, container.sectionKey ?? container.label, options, fieldSectionForMutation));
         if (options.allowDuplicate !== true) {
             const existing = new Set(container.fields.map((entry) => fieldRqlNameOf(entry)).filter(Boolean));
             const seen = new Set();
@@ -349,9 +518,23 @@ export class CustomObjectPageLayout {
         const fieldApiName = typeof field === 'string' ? field : field.getApiName();
         if (isField(field))
             this.assertFieldBelongsToLayout(field);
+        let sectionKey;
+        if (options.systemSection === true) {
+            assertOptionAbsent(options, 'section', 'CustomObjectPageLayout removeField section is only supported for custom layout sections.');
+            sectionKey = options.sectionKey;
+        }
+        else {
+            assertOptionAbsent(options, 'sectionKey', 'CustomObjectPageLayout removeField sectionKey is only supported with systemSection: true. ' +
+                'Pass section: CustomObjectFieldSection for custom layout sections.');
+            if (options.section != null) {
+                const section = requireFieldSectionOption(options.section, 'CustomObjectPageLayout removeField section');
+                this.assertFieldSectionBelongsToLayout(section);
+                sectionKey = section.getSectionId();
+            }
+        }
         const containers = this.findFieldContainers({
             tabKey: options.tabKey,
-            sectionKey: options.sectionKey,
+            sectionKey,
             systemSectionOnly: options.systemSection === true,
         });
         const matches = [];
@@ -400,10 +583,10 @@ export class CustomObjectPageLayout {
         if (options.systemTab === true) {
             const tabEdit = this.ensureSystemTabEdit(options.tabKey);
             const sections = ensureArrayProperty(tabEdit, 'newSections', `systemTabEdits.${options.tabKey}.newSections`);
-            this.assertSectionKeyAvailable(sections, normalized.key, options.tabKey, options.allowDuplicate);
+            this.assertSectionKeyAvailable(sections, layoutSectionKey(normalized), options.tabKey, options.allowDuplicate);
+            const sectionsOrder = this.ensureSystemSectionsOrder(tabEdit);
             insertAt(sections, normalized, options.position);
-            if (tabEdit.sectionsOrder != null)
-                insertAt(tabEdit.sectionsOrder, normalized.key, options.position);
+            insertUniqueAt(sectionsOrder, layoutSectionKey(normalized), options.position);
             return this;
         }
         const tab = this.findNewTabWithSections(options.tabKey);
@@ -411,26 +594,27 @@ export class CustomObjectPageLayout {
             throw new Error(`CustomObjectPageLayout could not find new tab "${options.tabKey}". ` +
                 'Pass systemTab: true to add a section to a built-in system tab.');
         }
-        this.assertSectionKeyAvailable(tab.sections, normalized.key, options.tabKey, options.allowDuplicate);
+        this.assertSectionKeyAvailable(tab.sections, layoutSectionKey(normalized), options.tabKey, options.allowDuplicate);
         insertAt(tab.sections, normalized, options.position);
         return this;
     }
-    /**
-     * Removes a section from `newTabs` / `systemTabEdits.newSections`.
-     *
-     * Pass `systemSection: true` with `tabKey` to delete a built-in section via
-     * `systemSectionEdits[sectionKey].deleted`.
-     */
-    removeSection(sectionKey, options = {}) {
+    removeSection(sectionOrKey, options = {}) {
         if (options.systemSection === true) {
+            if (typeof sectionOrKey !== 'string') {
+                throw new TypeError('CustomObjectPageLayout removeSection with systemSection: true requires a system section key.');
+            }
             if (options.tabKey == null) {
                 throw new Error('CustomObjectPageLayout removeSection with systemSection: true requires tabKey.');
             }
-            const sectionEdit = this.ensureSystemSectionEdit(options.tabKey, sectionKey);
+            const sectionEdit = this.ensureSystemSectionEdit(options.tabKey, sectionOrKey);
             sectionEdit.deleted = true;
-            this.removeSectionVisibility(sectionKey);
+            removeKeyFromOrder(this._tabEdits.systemTabEdits?.[options.tabKey]?.sectionsOrder, sectionOrKey);
+            this.removeSectionVisibility(sectionOrKey);
             return this;
         }
+        const section = requireFieldSectionOption(sectionOrKey, 'CustomObjectPageLayout removeSection section');
+        this.assertFieldSectionBelongsToLayout(section);
+        const sectionKey = section.getSectionId();
         const matches = [];
         for (const tab of this._tabEdits.newTabs ?? []) {
             if (!isTabWithSections(tab))
@@ -438,16 +622,16 @@ export class CustomObjectPageLayout {
             if (options.tabKey != null && tab.key !== options.tabKey)
                 continue;
             tab.sections.forEach((section, index) => {
-                if (section.key === sectionKey)
-                    matches.push({ sections: tab.sections, index, tabKey: tab.key });
+                if (layoutSectionMatches(section, sectionKey))
+                    matches.push({ sections: tab.sections, section, index, tabKey: tab.key });
             });
         }
         for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
             if (options.tabKey != null && tabKey !== options.tabKey)
                 continue;
             (tabEdit.newSections ?? []).forEach((section, index) => {
-                if (section.key === sectionKey)
-                    matches.push({ sections: tabEdit.newSections, index, tabEdit, tabKey });
+                if (layoutSectionMatches(section, sectionKey))
+                    matches.push({ sections: tabEdit.newSections, section, index, tabEdit, tabKey });
             });
         }
         if (matches.length === 0) {
@@ -466,11 +650,11 @@ export class CustomObjectPageLayout {
             byArray.set(match.sections, indexes);
             if (match.tabEdit != null)
                 removeKeyFromOrder(match.tabEdit.sectionsOrder, sectionKey);
+            this.removeSectionVisibility(sectionKey);
         }
         for (const [sections, indexes] of byArray.entries()) {
             removeIndexes(sections, indexes);
         }
-        this.removeSectionVisibility(sectionKey);
         return this;
     }
     /** Adds a new tab to `tab_edits.newTabs`. */
@@ -481,10 +665,9 @@ export class CustomObjectPageLayout {
         if (options.allowDuplicate !== true && newTabs.some((existing) => existing.key === normalized.key)) {
             throw new Error(`CustomObjectPageLayout already contains tab "${normalized.key}".`);
         }
+        const tabsOrder = this.ensureTabsOrder();
         insertAt(newTabs, normalized, options.position);
-        if (this._tabEdits.tabsOrder != null) {
-            insertAt(this._tabEdits.tabsOrder, normalized.key, options.position);
-        }
+        insertUniqueAt(tabsOrder, normalized.key, options.position);
         return this;
     }
     /**
@@ -517,10 +700,9 @@ export class CustomObjectPageLayout {
         if (options.allowDuplicate !== true && newFields.some((existing) => existing.key === headerField.key)) {
             throw new Error(`CustomObjectPageLayout header already contains field key "${headerField.key}".`);
         }
+        const headerFieldsOrder = this.ensureHeaderFieldsOrder();
         insertAt(newFields, headerField, options.position);
-        if (this._headerEdits.headerFieldsOrder != null) {
-            insertAt(this._headerEdits.headerFieldsOrder, headerField.key, options.position);
-        }
+        insertUniqueAt(headerFieldsOrder, headerField.rqlName, options.position);
         return this;
     }
     /** Removes custom header fields from `header_edits.newFields`. */
@@ -530,50 +712,104 @@ export class CustomObjectPageLayout {
             this.assertFieldBelongsToLayout(fieldOrKey);
         const key = typeof fieldOrKey === 'string' ? fieldOrKey : fieldApiName;
         const newFields = this._headerEdits.newFields ?? [];
-        const removedKeys = [];
+        const removedFields = [];
         const removed = removeFromArray(newFields, (field) => {
             const matched = field.key === key || (fieldApiName != null && field.rqlName === fieldApiName);
             if (matched)
-                removedKeys.push(field.key);
+                removedFields.push(field);
             return matched;
         }, `CustomObjectPageLayout header field "${key}"`, options.removeAll !== false);
         if (removed === 0) {
             throw new Error(`CustomObjectPageLayout header does not contain field "${key}".`);
         }
-        for (const removedKey of removedKeys) {
-            removeKeyFromOrder(this._headerEdits.headerFieldsOrder, removedKey);
-        }
+        for (const removedField of removedFields)
+            this.removeHeaderOrderFieldIfUnused(removedField);
         return this;
     }
     /** Sets the record title field in `header_edits`. */
     setTitleField(field) {
-        this._headerEdits.newTitleField = this.headerFieldApiName(field);
+        const previousTitleField = this._headerEdits.newTitleField;
+        const nextTitleField = this.headerFieldApiName(field);
+        this._headerEdits.newTitleField = nextTitleField;
         if (field != null)
             this._headerEdits.titleFieldDeleted = false;
+        insertUniqueAt(this.ensureHeaderFieldsOrder(), nextTitleField, 'end');
+        this.removeHeaderOrderFieldIfUnused(previousTitleField);
         return this;
     }
     /** Removes the record title field from the header. */
     removeTitleField() {
+        const previousTitleField = this._headerEdits.newTitleField;
         this._headerEdits.newTitleField = null;
         this._headerEdits.titleFieldDeleted = true;
+        this.removeHeaderOrderFieldIfUnused(previousTitleField);
         return this;
     }
     /** Sets the record description field in `header_edits`. */
     setDescriptionField(field) {
-        this._headerEdits.newDescriptionField = this.headerFieldApiName(field);
+        const previousDescriptionField = this._headerEdits.newDescriptionField;
+        const nextDescriptionField = this.headerFieldApiName(field);
+        this._headerEdits.newDescriptionField = nextDescriptionField;
         if (field != null)
             this._headerEdits.descriptionFieldDeleted = false;
+        insertUniqueAt(this.ensureHeaderFieldsOrder(), nextDescriptionField, 'end');
+        this.removeHeaderOrderFieldIfUnused(previousDescriptionField);
         return this;
     }
     /** Removes the record description field from the header. */
     removeDescriptionField() {
+        const previousDescriptionField = this._headerEdits.newDescriptionField;
         this._headerEdits.newDescriptionField = null;
         this._headerEdits.descriptionFieldDeleted = true;
+        this.removeHeaderOrderFieldIfUnused(previousDescriptionField);
         return this;
     }
-    serializeFieldForMutation(field, fallbackSectionKey, options) {
+    ensureTabsOrder() {
+        var _a;
+        const order = ((_a = this._tabEdits).tabsOrder ?? (_a.tabsOrder = []));
+        for (const tab of this._tabEdits.newTabs ?? [])
+            insertUniqueAt(order, tab.key, 'end');
+        for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
+            if (tabEdit.deleted !== true)
+                insertUniqueAt(order, tabKey, 'end');
+        }
+        return order;
+    }
+    ensureSystemSectionsOrder(tabEdit) {
+        const order = (tabEdit.sectionsOrder ?? (tabEdit.sectionsOrder = []));
+        for (const section of tabEdit.newSections ?? [])
+            insertUniqueAt(order, layoutSectionKey(section), 'end');
+        for (const [sectionKey, sectionEdit] of Object.entries(tabEdit.systemSectionEdits ?? {})) {
+            if (sectionEdit.deleted !== true)
+                insertUniqueAt(order, sectionKey, 'end');
+        }
+        return order;
+    }
+    ensureHeaderFieldsOrder() {
+        this._headerEdits.headerFieldsOrder = normalizeHeaderFieldsOrder({
+            ...this._headerEdits,
+            headerFieldsOrder: this._headerEdits.headerFieldsOrder ?? [],
+        });
+        return this._headerEdits.headerFieldsOrder;
+    }
+    headerOrderFieldIsUsed(rqlName) {
+        return (this._headerEdits.newTitleField === rqlName ||
+            this._headerEdits.newDescriptionField === rqlName ||
+            (this._headerEdits.newFields ?? []).some((field) => field.rqlName === rqlName) ||
+            Object.values(this._headerEdits.systemFieldEdits ?? {}).some((edit) => edit.newRqlField === rqlName));
+    }
+    removeHeaderOrderFieldIfUnused(field) {
+        const rqlName = typeof field === 'string' ? field : field?.rqlName;
+        if (field != null && typeof field !== 'string' && field.key !== rqlName) {
+            removeKeyFromOrder(this._headerEdits.headerFieldsOrder, field.key);
+        }
+        if (rqlName == null || this.headerOrderFieldIsUsed(rqlName))
+            return;
+        removeKeyFromOrder(this._headerEdits.headerFieldsOrder, rqlName);
+    }
+    serializeFieldForMutation(field, fallbackSectionKey, options, fieldSection) {
         this.assertFieldBelongsToLayout(field);
-        this.assignFieldSectionForMutation(field, fallbackSectionKey, options.fieldSection);
+        this.assignFieldSectionForMutation(field, fallbackSectionKey, fieldSection);
         return toSerializedSectionField(field.getApiName(), options);
     }
     normalizeSectionFieldForMutation(section, sectionKey, entry) {
@@ -591,21 +827,20 @@ export class CustomObjectPageLayout {
             'pass a Field instance or { field }.');
     }
     normalizeSectionForMutation(input) {
-        if (input.section.getModelApiName() !== this._customObjectApiName) {
-            throw new Error(`CustomObjectPageLayout section "${input.section.getSectionId()}" belongs to ` +
-                `"${input.section.getModelApiName()}", but the layout belongs to "${this._customObjectApiName}".`);
+        this.assertFieldSectionBelongsToLayout(input.section);
+        const sectionId = input.section.getSectionId();
+        if (inputFieldsSectionHasKey(input)) {
+            throw new Error('CustomObjectPageLayout fields_section key is not supported. Omit key.');
         }
-        const key = input.key ?? input.section.getSectionId();
         const name = input.name ?? input.section.getName();
         const normalized = {
-            key,
             name,
             type: 'fields_section',
-            fields: input.fields.map((field) => this.normalizeSectionFieldForMutation(input.section, key, field)),
+            fields: input.fields.map((field) => this.normalizeSectionFieldForMutation(input.section, sectionId, field)),
         };
         if (input.layout != null)
             normalized.layout = input.layout;
-        return normalized;
+        return attachFieldSectionId(normalized, sectionId);
     }
     normalizeTabForMutation(tab) {
         if (tab.type === 'custom_tab')
@@ -619,7 +854,7 @@ export class CustomObjectPageLayout {
         const rawFieldSection = fieldSection;
         if (rawFieldSection != null) {
             if (typeof rawFieldSection === 'string') {
-                throw new TypeError(`CustomObjectPageLayout fieldSection must be a CustomObjectFieldSection object; ` +
+                throw new TypeError(`CustomObjectPageLayout section must be a CustomObjectFieldSection object; ` +
                     `received raw section id "${rawFieldSection}". Load/include the existing field section first.`);
             }
             if (rawFieldSection.getModelApiName() !== this._customObjectApiName) {
@@ -631,7 +866,7 @@ export class CustomObjectPageLayout {
         }
         if (field.getSectionId() == null) {
             throw new Error(`CustomObjectPageLayout field "${field.getApiName()}" is missing field-section metadata. ` +
-                `Construct the field with a CustomObjectFieldSection or pass fieldSection when adding it to ` +
+                `Construct the field with a CustomObjectFieldSection or pass section when adding it to ` +
                 `section "${fallbackSectionKey}".`);
         }
     }
@@ -641,17 +876,45 @@ export class CustomObjectPageLayout {
                 `"${field.getCustomObjectApiName()}", but the layout belongs to "${this._customObjectApiName}".`);
         }
     }
-    requireOneFieldContainer(tabKey, sectionKey) {
+    assertFieldSectionBelongsToLayout(section) {
+        if (section.getModelApiName() !== this._customObjectApiName) {
+            throw new Error(`CustomObjectPageLayout field section "${section.getSectionId()}" belongs to ` +
+                `"${section.getModelApiName()}", but the layout belongs to "${this._customObjectApiName}".`);
+        }
+    }
+    requireOneFieldContainer(tabKey, sectionKey, fallbackFieldSection) {
         const containers = this.findFieldContainers({
             tabKey,
             sectionKey,
             systemSectionOnly: false,
         });
         if (containers.length === 0) {
-            const prefix = tabKey != null ? `${tabKey}.` : '';
-            throw new Error(`CustomObjectPageLayout could not find section "${prefix}${sectionKey}".`);
+            if (sectionKey != null && fallbackFieldSection != null) {
+                const unkeyedContainers = this.findFieldContainers({
+                    tabKey,
+                    sectionKey: undefined,
+                    systemSectionOnly: false,
+                }).filter((container) => container.section != null && container.sectionKey == null);
+                if (unkeyedContainers.length === 1) {
+                    if (fallbackFieldSection.getModelApiName() !== this._customObjectApiName) {
+                        throw new Error(`CustomObjectPageLayout field section "${fallbackFieldSection.getSectionId()}" belongs to ` +
+                            `"${fallbackFieldSection.getModelApiName()}", but the layout belongs to "${this._customObjectApiName}".`);
+                    }
+                    const container = unkeyedContainers[0];
+                    attachFieldSectionId(container.section, fallbackFieldSection.getSectionId());
+                    container.sectionKey = fallbackFieldSection.getSectionId();
+                    container.label = `${container.tabKey}.${container.sectionKey}`;
+                    return container;
+                }
+            }
+            const scope = sectionKey == null ? 'a field section' : (`section "${tabKey != null ? `${tabKey}.` : ''}${sectionKey}"`);
+            throw new Error(`CustomObjectPageLayout could not find ${scope}.`);
         }
         if (containers.length > 1) {
+            if (sectionKey == null) {
+                throw new Error(`CustomObjectPageLayout matched multiple sections: ` +
+                    `${containers.map((container) => container.label).join(', ')}. Pass section to choose one.`);
+            }
             throw new Error(`CustomObjectPageLayout section "${sectionKey}" matched multiple sections: ` +
                 `${containers.map((container) => container.label).join(', ')}. Pass tabKey to choose one.`);
         }
@@ -665,28 +928,34 @@ export class CustomObjectPageLayout {
                     continue;
                 if (filter.tabKey != null && tab.key !== filter.tabKey)
                     continue;
-                for (const section of tab.sections) {
-                    if (filter.sectionKey != null && section.key !== filter.sectionKey)
+                for (const [index, section] of tab.sections.entries()) {
+                    const sectionKey = layoutSectionKey(section);
+                    if (filter.sectionKey != null && !layoutSectionMatches(section, filter.sectionKey))
                         continue;
+                    const label = sectionKey == null ? `${tab.key}.sections[${index}]` : `${tab.key}.${sectionKey}`;
                     containers.push({
                         tabKey: tab.key,
-                        sectionKey: section.key,
-                        fields: ensureArrayProperty(section, 'fields', `newTabs.${tab.key}.sections.${section.key}.fields`),
-                        label: `${tab.key}.${section.key}`,
+                        sectionKey,
+                        section,
+                        fields: ensureArrayProperty(section, 'fields', `newTabs.${label}.fields`),
+                        label,
                     });
                 }
             }
             for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
                 if (filter.tabKey != null && tabKey !== filter.tabKey)
                     continue;
-                for (const section of tabEdit.newSections ?? []) {
-                    if (filter.sectionKey != null && section.key !== filter.sectionKey)
+                for (const [index, section] of (tabEdit.newSections ?? []).entries()) {
+                    const sectionKey = layoutSectionKey(section);
+                    if (filter.sectionKey != null && !layoutSectionMatches(section, filter.sectionKey))
                         continue;
+                    const label = sectionKey == null ? `${tabKey}.newSections[${index}]` : `${tabKey}.${sectionKey}`;
                     containers.push({
                         tabKey,
-                        sectionKey: section.key,
-                        fields: ensureArrayProperty(section, 'fields', `systemTabEdits.${tabKey}.newSections.${section.key}.fields`),
-                        label: `${tabKey}.${section.key}`,
+                        sectionKey,
+                        section,
+                        fields: ensureArrayProperty(section, 'fields', `systemTabEdits.${label}.fields`),
+                        label,
                     });
                 }
             }
@@ -717,6 +986,9 @@ export class CustomObjectPageLayout {
         if (tabKey == null) {
             throw new Error('CustomObjectPageLayout addField with systemSection: true requires tabKey.');
         }
+        if (sectionKey == null) {
+            throw new Error('CustomObjectPageLayout addField with systemSection: true requires sectionKey.');
+        }
         const sectionEdit = this.ensureSystemSectionEdit(tabKey, sectionKey);
         if (sectionEdit.deleted === true) {
             throw new Error(`CustomObjectPageLayout system section "${tabKey}.${sectionKey}" is marked deleted.`);
@@ -755,7 +1027,7 @@ export class CustomObjectPageLayout {
     assertSectionKeyAvailable(sections, sectionKey, tabKey, allowDuplicate) {
         if (allowDuplicate === true)
             return;
-        if (sections.some((section) => section.key === sectionKey)) {
+        if (sectionKey != null && sections.some((section) => layoutSectionMatches(section, sectionKey))) {
             throw new Error(`CustomObjectPageLayout tab "${tabKey}" already contains section "${sectionKey}".`);
         }
     }
@@ -827,12 +1099,13 @@ export class CustomObjectPageLayout {
      * tabs or sections. Always uses `apiName: 'default'`.
      *
      * @param customObject - The custom object to create the layout for.
-     * @param props - Optional. Pass `fields` to populate the General section.
+     * @param props - Optional. Pass `section` and `fields` to populate the General section.
      * @returns A new `CustomObjectPageLayout` registered with the manifest.
      *
      * @example
      * ```ts
      * CustomObjectPageLayout.basic(memberObj, {
+     *   section: profileSection,
      *   fields: [memberFirstName, memberEmail, memberStatusField],
      * });
      * ```
@@ -840,11 +1113,29 @@ export class CustomObjectPageLayout {
     static basic(customObject, props = {}) {
         const coApiName = customObject.getApiName();
         const coName = customObject.getName();
-        const sectionPrefix = coApiName.replace(/__c$/, '').replace(/[^a-zA-Z0-9]+/g, '_');
-        const generalSection = new CustomObjectFieldSection(customObject, {
-            sectionId: `sec_${sectionPrefix}_general`,
-            name: 'General',
-        });
+        const fields = props.fields ?? [];
+        const generalSection = props.section ??
+            (() => {
+                const alreadySectionedField = fields.find((field) => field.getSectionId() != null);
+                if (alreadySectionedField != null) {
+                    throw new Error(`CustomObjectPageLayout.basic field "${alreadySectionedField.getApiName()}" already belongs to ` +
+                        `field section "${alreadySectionedField.getSectionId()}". Pass that CustomObjectFieldSection ` +
+                        'as section so basic() does not reassign the field.');
+                }
+                const sectionPrefix = coApiName.replace(/__c$/, '').replace(/[^a-zA-Z0-9]+/g, '_');
+                return new CustomObjectFieldSection(customObject, {
+                    sectionId: `sec_${sectionPrefix}_general`,
+                    name: 'General',
+                });
+            })();
+        assertSectionBelongsTo(customObject, generalSection);
+        for (const field of fields) {
+            const fieldSectionId = field.getSectionId();
+            if (fieldSectionId != null && fieldSectionId !== generalSection.getSectionId()) {
+                throw new Error(`CustomObjectPageLayout.basic field "${field.getApiName()}" belongs to field section ` +
+                    `"${fieldSectionId}", but basic() was given section "${generalSection.getSectionId()}".`);
+            }
+        }
         return new CustomObjectPageLayout(customObject, {
             apiName: 'default',
             name: `${coName} Layout`,
@@ -856,11 +1147,10 @@ export class CustomObjectPageLayout {
                         type: 'tab_with_sections',
                         sections: [
                             {
-                                key: 'general',
                                 name: 'General',
                                 type: 'fields_section',
                                 section: generalSection,
-                                fields: props.fields ?? [],
+                                fields,
                             },
                         ],
                     },