@rippling/rippling-sdk 0.2.0-alpha.100

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

@@ -0,0 +1,1319 @@
+import { generateId } from "./_helpers.mjs";
+import { CustomObjectFieldSection } from "./custom-object-field-section.mjs";
+import { getExistingManifestContext } from "./existing-manifest-context.mjs";
+import { requireStringComponentField } from "./_existing-component-fields.mjs";
+function isField(value) {
+    const candidate = value;
+    return (candidate != null &&
+        typeof candidate.getApiName === 'function' &&
+        typeof candidate.getCustomObjectApiName === 'function' &&
+        typeof candidate.getSectionId === 'function' &&
+        typeof candidate._assignSection === 'function');
+}
+function isFieldRef(value) {
+    const candidate = value;
+    return (candidate != null &&
+        typeof candidate === 'object' &&
+        (isField(candidate.field) || typeof candidate.field === 'string'));
+}
+const LAYOUT_SECTION_KEY = Symbol('CustomObjectPageLayout.layoutSectionKey');
+function isCustomObjectFieldSection(value) {
+    return value instanceof CustomObjectFieldSection;
+}
+function explicitLayoutSectionKey(section) {
+    const record = section;
+    const key = section.key ?? record['layout_section_key'] ?? record['layoutSectionKey'];
+    return typeof key === 'string' ? key : undefined;
+}
+function attachLayoutSectionKey(section, sectionKey) {
+    if (explicitLayoutSectionKey(section) == null)
+        section.key = sectionKey;
+    Object.defineProperty(section, LAYOUT_SECTION_KEY, {
+        value: sectionKey,
+        enumerable: false,
+        configurable: true,
+    });
+    return section;
+}
+function layoutSectionKey(section) {
+    return (explicitLayoutSectionKey(section) ??
+        section[LAYOUT_SECTION_KEY]);
+}
+function layoutSectionMatches(section, sectionKey) {
+    return layoutSectionKey(section) === sectionKey;
+}
+function isSerializedFieldsSection(section) {
+    return section.type === 'fields_section';
+}
+function assertSameObject(customObject, field, sectionKey) {
+    if (field.getCustomObjectApiName() !== customObject.getApiName()) {
+        throw new Error(`CustomObjectPageLayout fields_section "${sectionKey}" references field "${field.getApiName()}" ` +
+            `from "${field.getCustomObjectApiName()}", but the layout belongs to "${customObject.getApiName()}".`);
+    }
+}
+function assignSectionForLayout(field, section) {
+    if (!field.isStandard())
+        field._assignSection(section);
+}
+function assertSectionBelongsTo(customObject, section) {
+    if (section.getModelApiName() !== customObject.getApiName()) {
+        throw new Error(`CustomObjectPageLayout section "${section.getSectionId()}" belongs to "${section.getModelApiName()}", ` +
+            `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)
+        normalized.hidden = options.hidden;
+    if (options.editable != null)
+        normalized.editable = options.editable;
+    if (options.readOnly != null)
+        normalized.readOnly = options.readOnly;
+    if (options.defaultValue != null)
+        normalized.defaultValue = options.defaultValue;
+    if (options.height != null)
+        normalized.height = options.height;
+    if (options.canBeDeleted != null)
+        normalized.canBeDeleted = options.canBeDeleted;
+    return normalized;
+}
+function copySectionOptions(target, input) {
+    if (input.canBeDeleted != null)
+        target.canBeDeleted = input.canBeDeleted;
+    if (input.canBeRenamed != null)
+        target.canBeRenamed = input.canBeRenamed;
+    if (input.hideName != null)
+        target.hideName = input.hideName;
+    return target;
+}
+function normalizeSectionField(customObject, section, sectionKey, entry) {
+    if (isField(entry) || typeof entry === 'string') {
+        const field = customObject._resolveField(entry);
+        assertSameObject(customObject, field, sectionKey);
+        assignSectionForLayout(field, section);
+        return toSerializedSectionField(field.getApiName());
+    }
+    if (isFieldRef(entry)) {
+        const field = customObject._resolveField(entry.field);
+        assertSameObject(customObject, field, sectionKey);
+        assignSectionForLayout(field, section);
+        return toSerializedSectionField(field.getApiName(), entry);
+    }
+    throw new Error(`CustomObjectPageLayout fields_section "${sectionKey}" has an invalid field entry; ` +
+        'pass a Field instance or { field }.');
+}
+function normalizeFieldsSection(customObject, input) {
+    assertSectionBelongsTo(customObject, input.section);
+    const sectionKey = input.key ?? input.section.getSectionId();
+    const name = input.name ?? input.section.getName();
+    const normalized = copySectionOptions({
+        name,
+        type: 'fields_section',
+        fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, sectionKey, field)),
+    }, input);
+    if (input.layout != null)
+        normalized.layout = input.layout;
+    return attachLayoutSectionKey(normalized, sectionKey);
+}
+function normalizeSection(customObject, section) {
+    if (section.type === 'fields_section')
+        return normalizeFieldsSection(customObject, section);
+    return { ...section };
+}
+function normalizeTab(customObject, tab) {
+    if (tab.type === 'custom_tab')
+        return tab;
+    return {
+        ...tab,
+        sections: tab.sections.map((section) => normalizeSection(customObject, section)),
+    };
+}
+function normalizeSystemSectionEdit(customObject, tabKey, sectionKey, edit) {
+    const { newFields: _newFields, ...rest } = edit;
+    const normalized = { ...rest };
+    if (edit.newFields != null) {
+        normalized.newFields = edit.newFields.map((field) => normalizeSectionField(customObject, sectionKey, `${tabKey}.${sectionKey}`, field));
+    }
+    return normalized;
+}
+function normalizeSystemTabEdit(customObject, tabKey, edit) {
+    const { newSections: _newSections, systemSectionEdits: _systemSectionEdits, ...rest } = edit;
+    const normalized = { ...rest };
+    if (edit.newSections != null) {
+        normalized.newSections = edit.newSections.map((section) => normalizeSection(customObject, section));
+    }
+    if (edit.systemSectionEdits != null) {
+        const systemSectionEdits = {};
+        for (const [sectionKey, sectionEdit] of Object.entries(edit.systemSectionEdits)) {
+            systemSectionEdits[sectionKey] = normalizeSystemSectionEdit(customObject, tabKey, sectionKey, sectionEdit);
+        }
+        normalized.systemSectionEdits = systemSectionEdits;
+    }
+    return normalized;
+}
+function normalizeTabEdits(customObject, tabEdits) {
+    const { newTabs: _newTabs, systemTabEdits: _systemTabEdits, ...rest } = tabEdits;
+    const normalized = { ...rest };
+    if (tabEdits.newTabs != null) {
+        normalized.newTabs = tabEdits.newTabs.map((tab) => normalizeTab(customObject, tab));
+    }
+    if (tabEdits.systemTabEdits != null) {
+        const systemTabEdits = {};
+        for (const [tabKey, tabEdit] of Object.entries(tabEdits.systemTabEdits)) {
+            systemTabEdits[tabKey] = normalizeSystemTabEdit(customObject, tabKey, tabEdit);
+        }
+        normalized.systemTabEdits = systemTabEdits;
+    }
+    return normalized;
+}
+function cloneJson(value) {
+    if (value == null)
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
+function stripMovementOptions(value) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            stripMovementOptions(item);
+        return;
+    }
+    if (value == null || typeof value !== 'object')
+        return;
+    const record = value;
+    delete record['movementOption'];
+    for (const item of Object.values(record))
+        stripMovementOptions(item);
+}
+const HEADER_EDIT_KEYS = new Set([
+    'newTitleField',
+    'titleFieldDeleted',
+    'newDescriptionField',
+    'descriptionFieldDeleted',
+    'systemFieldEdits',
+    'newFields',
+    'headerFieldsOrder',
+]);
+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.newTitleField === '') {
+        throw new Error('CustomObjectPageLayout headerEdits.newTitleField cannot be empty. Use titleFieldDeleted.');
+    }
+    if (headerEdits.newDescriptionField === '') {
+        throw new Error('CustomObjectPageLayout headerEdits.newDescriptionField cannot be empty. Use descriptionFieldDeleted.');
+    }
+    if (headerEdits.newTitleField != null && headerEdits.titleFieldDeleted === true) {
+        throw new Error('CustomObjectPageLayout headerEdits cannot both set newTitleField and titleFieldDeleted.');
+    }
+    if (headerEdits.newDescriptionField != null && headerEdits.descriptionFieldDeleted === true) {
+        throw new Error('CustomObjectPageLayout headerEdits cannot both set newDescriptionField and descriptionFieldDeleted.');
+    }
+    const normalized = { ...headerEdits };
+    if (headerEdits.headerFieldsOrder == null)
+        return normalized;
+    return {
+        ...normalized,
+        headerFieldsOrder: normalizeHeaderFieldsOrder(normalized),
+    };
+}
+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';
+}
+function insertionIndex(length, position) {
+    if (position == null || position === 'end')
+        return length;
+    if (position === 'start')
+        return 0;
+    if (!Number.isInteger(position) || position < 0 || position > length) {
+        throw new Error(`Invalid insertion position ${position}; expected 'start', 'end', or 0-${length}.`);
+    }
+    return 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;
+    if (entry == null || typeof entry !== 'object')
+        return undefined;
+    const record = entry;
+    const fieldRqlName = record['fieldRqlName'] ?? record['field_rql_name'] ?? record['apiName'] ?? record['api_name'];
+    return typeof fieldRqlName === 'string' ? fieldRqlName : undefined;
+}
+function addFieldSectionLayoutSection(index, fieldSectionId, entry) {
+    const entries = index.get(fieldSectionId) ?? [];
+    if (!entries.some((existing) => existing.tabKey === entry.tabKey && existing.sectionKey === entry.sectionKey)) {
+        entries.push(entry);
+    }
+    index.set(fieldSectionId, entries);
+}
+function indexFieldsSectionInput(index, tabKey, section) {
+    addFieldSectionLayoutSection(index, section.section.getSectionId(), {
+        tabKey,
+        sectionKey: section.key ?? section.section.getSectionId(),
+    });
+}
+function indexPageLayoutSectionInput(index, tabKey, section) {
+    if (section.type === 'fields_section')
+        indexFieldsSectionInput(index, tabKey, section);
+}
+function buildFieldSectionLayoutIndexFromProps(tabEdits) {
+    const index = new Map();
+    if (tabEdits == null)
+        return index;
+    for (const tab of tabEdits.newTabs ?? []) {
+        if (tab.type !== 'tab_with_sections')
+            continue;
+        for (const section of tab.sections)
+            indexPageLayoutSectionInput(index, tab.key, section);
+    }
+    for (const [tabKey, tabEdit] of Object.entries(tabEdits.systemTabEdits ?? {})) {
+        for (const section of tabEdit.newSections ?? []) {
+            indexPageLayoutSectionInput(index, tabKey, section);
+        }
+    }
+    return index;
+}
+function indexLoadedFieldsSection(index, tabKey, section, resolveFieldSectionId) {
+    const sectionKey = layoutSectionKey(section);
+    if (sectionKey == null || resolveFieldSectionId == null)
+        return;
+    for (const field of section.fields ?? []) {
+        const fieldRqlName = fieldRqlNameOf(field);
+        if (fieldRqlName == null)
+            continue;
+        const fieldSectionId = resolveFieldSectionId(fieldRqlName);
+        if (fieldSectionId != null) {
+            addFieldSectionLayoutSection(index, fieldSectionId, { tabKey, sectionKey });
+        }
+    }
+}
+function buildFieldSectionLayoutIndexFromLoadedTabEdits(tabEdits, resolveFieldSectionId) {
+    const index = new Map();
+    for (const tab of tabEdits.newTabs ?? []) {
+        if (!isTabWithSections(tab))
+            continue;
+        for (const section of tab.sections) {
+            if (isSerializedFieldsSection(section)) {
+                indexLoadedFieldsSection(index, tab.key, section, resolveFieldSectionId);
+            }
+        }
+    }
+    for (const [tabKey, tabEdit] of Object.entries(tabEdits.systemTabEdits ?? {})) {
+        for (const section of tabEdit.newSections ?? []) {
+            if (isSerializedFieldsSection(section)) {
+                indexLoadedFieldsSection(index, tabKey, section, resolveFieldSectionId);
+            }
+        }
+    }
+    return index;
+}
+function annotateLoadedFieldsSection(section) {
+    const sectionKey = layoutSectionKey(section);
+    return sectionKey == null ? section : attachLayoutSectionKey(section, sectionKey);
+}
+function annotateLoadedTabEdits(tabEdits) {
+    for (const tab of tabEdits.newTabs ?? []) {
+        if (!isTabWithSections(tab))
+            continue;
+        tab.sections = tab.sections.map((section) => isSerializedFieldsSection(section) ? annotateLoadedFieldsSection(section) : section);
+    }
+    for (const tabEdit of Object.values(tabEdits.systemTabEdits ?? {})) {
+        if (tabEdit.newSections != null) {
+            tabEdit.newSections = tabEdit.newSections.map((section) => isSerializedFieldsSection(section) ? annotateLoadedFieldsSection(section) : section);
+        }
+    }
+    return tabEdits;
+}
+function removeIndexes(items, indexes) {
+    for (const index of [...indexes].sort((a, b) => b - a)) {
+        items.splice(index, 1);
+    }
+}
+function removeFromArray(items, predicate, label, removeAll = true) {
+    const indexes = [];
+    items.forEach((item, index) => {
+        if (predicate(item))
+            indexes.push(index);
+    });
+    if (indexes.length > 1 && !removeAll) {
+        throw new Error(`${label} matched ${indexes.length} entries; pass removeAll: true to remove them all.`);
+    }
+    removeIndexes(items, removeAll ? indexes : indexes.slice(0, 1));
+    return removeAll ? indexes.length : Math.min(indexes.length, 1);
+}
+function removeKeyFromOrder(order, key) {
+    if (order == null)
+        return;
+    removeFromArray(order, (entry) => entry === key, `order key "${key}"`);
+}
+function ensureRecordProperty(record, key, label) {
+    const existing = record[key];
+    if (existing == null) {
+        const next = {};
+        record[key] = next;
+        return next;
+    }
+    if (typeof existing !== 'object' || Array.isArray(existing)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return existing;
+}
+function ensureArrayProperty(record, key, label) {
+    const existing = record[key];
+    if (existing == null) {
+        const next = [];
+        record[key] = next;
+        return next;
+    }
+    if (!Array.isArray(existing)) {
+        throw new Error(`${label} must be an array.`);
+    }
+    return existing;
+}
+// ---------------------------------------------------------------------------
+// Class
+// ---------------------------------------------------------------------------
+/**
+ * Defines a page layout and registers it with the manifest.
+ *
+ * A page layout controls the tab structure, section groupings, header fields,
+ * and visibility conditions on a custom object's record detail page. You would
+ * normally define one layout per custom object using `apiName: 'default'`.
+ *
+ * For simple single-tab layouts, use the {@link CustomObjectPageLayout.basic}
+ * factory instead of constructing the full props manually.
+ *
+ * > **Caution:** all keys inside `tabEdits` and `headerEdits` must be camelCase.
+ * > Snake_case keys are silently dropped on the wire and produce an empty layout.
+ *
+ * @example
+ * ```ts
+ * new CustomObjectPageLayout(memberObj, {
+ *   apiName: 'default',
+ *   name: 'Member',
+ *   layoutId: 'layout_gym_member',
+ *   tabEdits: {
+ *     newTabs: [{
+ *       key: 'member', name: 'Member', type: 'tab_with_sections',
+ *       sections: [{
+ *         name: 'Profile',
+ *         type: 'fields_section',
+ *         section: profileSection,
+ *         fields: [{ field: 'name', editable: true }, memberEmail],
+ *       }],
+ *     }],
+ *     systemTabEdits: {},
+ *     tabsOrder: ['member'],
+ *   },
+ *   visibilityConditions: {},
+ * });
+ * ```
+ *
+ * @see {@link CustomObjectPageLayout.basic} — factory for simple single-tab layouts.
+ */
+export class CustomObjectPageLayout {
+    static toDeletionIdentifier(identifier) {
+        return {
+            type: CustomObjectPageLayout.componentType,
+            layout_id: identifier.layoutId,
+            object_rql_name: identifier.objectRqlName,
+        };
+    }
+    /**
+     * @param customObject - The custom object this layout belongs to.
+     * @param props - Initialization properties.
+     * @throws {Error} If `apiName` or `name` is empty.
+     */
+    constructor(customObject, props) {
+        if (!props.apiName)
+            throw new Error('CustomObjectPageLayout: apiName cannot be empty');
+        if (!props.name)
+            throw new Error('CustomObjectPageLayout: name cannot be empty');
+        this._layoutId = props.layoutId ?? generateId('layout');
+        this._apiName = props.apiName;
+        this._customObjectApiName = customObject.getApiName();
+        this._customObject = customObject;
+        this._name = props.name;
+        this._tabEdits = normalizeTabEdits(customObject, props.tabEdits ?? {});
+        this._fieldSectionLayoutSections = buildFieldSectionLayoutIndexFromProps(props.tabEdits);
+        this._headerEdits = normalizeHeaderEdits(props.headerEdits ?? {});
+        this._visibilityConditions = props.visibilityConditions ?? {};
+        this._blueprintKey = props.blueprintKey;
+        customObject._register(this);
+    }
+    /**
+     * Loads this page layout from the active existing-manifest JSON context.
+     *
+     * `id` resolves against `layout_id` first, then `api_name`. When loading by
+     * api_name such as `'default'`, pass `customObjectApiName` if multiple objects
+     * have a layout with the same api_name.
+     */
+    static loadFromExisting(layoutIdOrApiName, options = {}) {
+        return getExistingManifestContext(options).loadPageLayout(layoutIdOrApiName, options);
+    }
+    /** @internal Hydrates a page layout from existing manifest wire JSON. */
+    static _fromExistingComponent(customObject, component, resolveFieldSectionId) {
+        const layout = Object.create(CustomObjectPageLayout.prototype);
+        const tabEdits = annotateLoadedTabEdits(cloneJson(component['tab_edits'] ?? {}));
+        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),
+            _customObject: customObject,
+            _name: requireStringComponentField(component, 'name', CustomObjectPageLayout.componentType),
+            _tabEdits: tabEdits,
+            _headerEdits: cloneJson(component['header_edits'] ?? {}),
+            _visibilityConditions: cloneJson(component['visibility_conditions'] ?? {}),
+            _blueprintKey: component['blueprint_key'],
+            _fieldSectionLayoutSections: buildFieldSectionLayoutIndexFromLoadedTabEdits(tabEdits, resolveFieldSectionId),
+        });
+        customObject._register(layout);
+        return layout;
+    }
+    /**
+     * Returns the stable identifier for this layout record (e.g. `'layout_gym_member'`).
+     */
+    getLayoutId() {
+        return this._layoutId;
+    }
+    /**
+     * Returns the api_name of this layout (e.g. `'default'`).
+     */
+    getApiName() {
+        return this._apiName;
+    }
+    /**
+     * Returns the api_name of the custom object this layout belongs to.
+     */
+    getCustomObjectApiName() {
+        return this._customObjectApiName;
+    }
+    /**
+     * Adds one field to an existing layout section.
+     *
+     * For loaded layouts, this mutates the preserved `tab_edits` JSON in place
+     * and normalizes only the inserted field entry.
+     */
+    addField(field, options) {
+        return this.addFields([field], options);
+    }
+    /**
+     * Adds multiple fields to an existing layout section.
+     *
+     * Fields are inserted in the order provided. For custom layout sections,
+     * pass `section` to choose the typed field section. Use `sectionKey` only
+     * when a field section maps to multiple layout sections.
+     */
+    addFields(fields, options) {
+        if (fields.length === 0)
+            return this;
+        let fieldSectionForMutation;
+        const container = options.systemSection === true ?
+            (() => {
+                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, 'fieldSection', 'CustomObjectPageLayout addField fieldSection is no longer supported. ' +
+                    'Pass section: CustomObjectFieldSection instead.');
+                const section = options.section == null ?
+                    undefined
+                    : requireFieldSectionOption(options.section, 'CustomObjectPageLayout addField section');
+                if (section != null) {
+                    this.assertFieldSectionBelongsToLayout(section);
+                    fieldSectionForMutation = section;
+                }
+                const sectionKey = options.sectionKey ??
+                    (section == null ? undefined : this.layoutSectionKeyForFieldSection(options.tabKey, section)) ??
+                    section?.getSectionId();
+                return this.requireOneFieldContainer(options.tabKey, sectionKey, 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();
+            for (const entry of entries) {
+                const fieldRqlName = entry.fieldRqlName;
+                if (existing.has(fieldRqlName) || seen.has(fieldRqlName)) {
+                    throw new Error(`CustomObjectPageLayout section "${container.label}" already contains field "${fieldRqlName}".`);
+                }
+                seen.add(fieldRqlName);
+            }
+        }
+        const index = insertionIndex(container.fields.length, options.position);
+        container.fields.splice(index, 0, ...entries);
+        return this;
+    }
+    /**
+     * Removes a field from the layout's field sections.
+     *
+     * This only removes the field from the page layout. It does not delete the
+     * `CUSTOM_OBJECT_FIELD` component from the manifest.
+     */
+    removeField(field, options = {}) {
+        const fieldApiName = this.fieldApiName(field);
+        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 {
+            sectionKey = options.sectionKey;
+            if (options.section != null) {
+                const section = requireFieldSectionOption(options.section, 'CustomObjectPageLayout removeField section');
+                this.assertFieldSectionBelongsToLayout(section);
+                sectionKey ?? (sectionKey = this.layoutSectionKeyForFieldSection(options.tabKey, section));
+                sectionKey ?? (sectionKey = section.getSectionId());
+            }
+        }
+        const containers = this.findFieldContainers({
+            tabKey: options.tabKey,
+            sectionKey,
+            systemSectionOnly: options.systemSection === true,
+        });
+        const matches = [];
+        for (const container of containers) {
+            container.fields.forEach((entry, index) => {
+                if (fieldRqlNameOf(entry) === fieldApiName) {
+                    matches.push({ container, index });
+                }
+            });
+        }
+        if (matches.length === 0) {
+            throw new Error(`CustomObjectPageLayout does not contain field "${fieldApiName}".`);
+        }
+        const removeAll = options.removeAll !== false;
+        if (matches.length > 1 && !removeAll) {
+            throw new Error(`CustomObjectPageLayout field "${fieldApiName}" matched ${matches.length} entries; ` +
+                'pass removeAll: true to remove them all.');
+        }
+        const removals = removeAll ? matches : matches.slice(0, 1);
+        const byContainer = new Map();
+        for (const match of removals) {
+            const indexes = byContainer.get(match.container) ?? [];
+            indexes.push(match.index);
+            byContainer.set(match.container, indexes);
+        }
+        for (const [container, indexes] of byContainer.entries()) {
+            removeIndexes(container.fields, indexes);
+        }
+        return this;
+    }
+    /** Removes multiple fields from the layout's field sections. */
+    removeFields(fields, options = {}) {
+        for (const field of fields) {
+            this.removeField(field, options);
+        }
+        return this;
+    }
+    /**
+     * Adds a section to an existing tab.
+     *
+     * Pass `systemTab: true` to add a new section to a built-in tab via
+     * `systemTabEdits.newSections`.
+     */
+    addSection(section, options) {
+        const normalized = this.normalizeSectionForMutation(section);
+        if (options.systemTab === true) {
+            const tabEdit = this.ensureSystemTabEdit(options.tabKey);
+            const sections = ensureArrayProperty(tabEdit, 'newSections', `systemTabEdits.${options.tabKey}.newSections`);
+            this.assertSectionKeyAvailable(sections, layoutSectionKey(normalized), options.tabKey, options.allowDuplicate);
+            const sectionsOrder = this.ensureSystemSectionsOrder(tabEdit);
+            insertAt(sections, normalized, options.position);
+            insertUniqueAt(sectionsOrder, layoutSectionKey(normalized), options.position);
+            if (section.type === 'fields_section') {
+                this.rememberFieldSectionLayoutSection(section.section, options.tabKey, layoutSectionKey(normalized));
+            }
+            return this;
+        }
+        const tab = this.findNewTabWithSections(options.tabKey);
+        if (tab == null) {
+            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, layoutSectionKey(normalized), options.tabKey, options.allowDuplicate);
+        insertAt(tab.sections, normalized, options.position);
+        if (section.type === 'fields_section') {
+            this.rememberFieldSectionLayoutSection(section.section, tab.key, layoutSectionKey(normalized));
+        }
+        return this;
+    }
+    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, sectionOrKey);
+            sectionEdit.deleted = true;
+            removeKeyFromOrder(this._tabEdits.systemTabEdits?.[options.tabKey]?.sectionsOrder, sectionOrKey);
+            this.removeSectionVisibility(sectionOrKey);
+            return this;
+        }
+        let sectionKey;
+        if (typeof sectionOrKey === 'string') {
+            sectionKey = sectionOrKey;
+        }
+        else {
+            const section = requireFieldSectionOption(sectionOrKey, 'CustomObjectPageLayout removeSection section');
+            this.assertFieldSectionBelongsToLayout(section);
+            sectionKey = this.layoutSectionKeyForFieldSection(options.tabKey, section) ?? section.getSectionId();
+        }
+        const matches = [];
+        for (const tab of this._tabEdits.newTabs ?? []) {
+            if (!isTabWithSections(tab))
+                continue;
+            if (options.tabKey != null && tab.key !== options.tabKey)
+                continue;
+            tab.sections.forEach((section, index) => {
+                if (isSerializedFieldsSection(section) && 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 (isSerializedFieldsSection(section) && layoutSectionMatches(section, sectionKey))
+                    matches.push({ sections: tabEdit.newSections, section, index, tabEdit, tabKey });
+            });
+        }
+        if (matches.length === 0) {
+            throw new Error(`CustomObjectPageLayout does not contain section "${sectionKey}".`);
+        }
+        const removeAll = options.removeAll !== false;
+        if (matches.length > 1 && !removeAll) {
+            throw new Error(`CustomObjectPageLayout section "${sectionKey}" matched ${matches.length} entries; ` +
+                'pass removeAll: true to remove them all.');
+        }
+        const removals = removeAll ? matches : matches.slice(0, 1);
+        const byArray = new Map();
+        for (const match of removals) {
+            const indexes = byArray.get(match.sections) ?? [];
+            indexes.push(match.index);
+            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);
+        }
+        return this;
+    }
+    /** Adds a new tab to `tab_edits.newTabs`. */
+    addTab(tab, options = {}) {
+        var _a;
+        const normalized = this.normalizeTabForMutation(tab);
+        const newTabs = ((_a = this._tabEdits).newTabs ?? (_a.newTabs = []));
+        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);
+        insertUniqueAt(tabsOrder, normalized.key, options.position);
+        if (tab.type === 'tab_with_sections') {
+            for (const section of tab.sections)
+                indexPageLayoutSectionInput(this._fieldSectionLayoutSections, tab.key, section);
+        }
+        return this;
+    }
+    /**
+     * Removes a tab from `newTabs`.
+     *
+     * Pass `systemTab: true` to delete a built-in tab via `systemTabEdits[tabKey].deleted`.
+     */
+    removeTab(tabKey, options = {}) {
+        if (options.systemTab === true) {
+            const tabEdit = this.ensureSystemTabEdit(tabKey);
+            tabEdit.deleted = true;
+            removeKeyFromOrder(this._tabEdits.tabsOrder, tabKey);
+            this.removeTabVisibility(tabKey);
+            return this;
+        }
+        const newTabs = this._tabEdits.newTabs ?? [];
+        const removed = removeFromArray(newTabs, (tab) => tab.key === tabKey, `CustomObjectPageLayout tab "${tabKey}"`, options.removeAll !== false);
+        if (removed === 0) {
+            throw new Error(`CustomObjectPageLayout does not contain tab "${tabKey}".`);
+        }
+        removeKeyFromOrder(this._tabEdits.tabsOrder, tabKey);
+        this.removeTabVisibility(tabKey);
+        return this;
+    }
+    /** Adds a custom header field to `header_edits.newFields`. */
+    addHeaderField(field, options = {}) {
+        var _a;
+        const headerField = this.normalizeHeaderFieldForMutation(field, options);
+        const newFields = ((_a = this._headerEdits).newFields ?? (_a.newFields = []));
+        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);
+        insertUniqueAt(headerFieldsOrder, headerField.rqlName, options.position);
+        return this;
+    }
+    /** Removes custom header fields from `header_edits.newFields`. */
+    removeHeaderField(fieldOrKey, options = {}) {
+        const fieldApiName = typeof fieldOrKey === 'string' ? undefined : fieldOrKey.getApiName();
+        if (isField(fieldOrKey))
+            this.assertFieldBelongsToLayout(fieldOrKey);
+        const key = typeof fieldOrKey === 'string' ? fieldOrKey : fieldApiName;
+        const newFields = this._headerEdits.newFields ?? [];
+        const removedFields = [];
+        const removed = removeFromArray(newFields, (field) => {
+            const matched = field.key === key || (fieldApiName != null && field.rqlName === fieldApiName);
+            if (matched)
+                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 removedField of removedFields)
+            this.removeHeaderOrderFieldIfUnused(removedField);
+        return this;
+    }
+    setTitleField(field) {
+        const previousTitleField = this._headerEdits.newTitleField;
+        const nextTitleField = this.headerFieldApiName(field);
+        this._headerEdits.newTitleField = nextTitleField;
+        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;
+    }
+    setDescriptionField(field) {
+        const previousDescriptionField = this._headerEdits.newDescriptionField;
+        const nextDescriptionField = this.headerFieldApiName(field);
+        this._headerEdits.newDescriptionField = nextDescriptionField;
+        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;
+    }
+    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) {
+        const resolved = this._resolveField(field);
+        this.assertFieldBelongsToLayout(resolved);
+        this.assignFieldSectionForMutation(resolved, fallbackSectionKey, fieldSection);
+        return toSerializedSectionField(resolved.getApiName(), options);
+    }
+    normalizeSectionFieldForMutation(section, sectionKey, entry) {
+        if (isField(entry) || typeof entry === 'string') {
+            const field = this._resolveField(entry);
+            this.assertFieldBelongsToLayout(field);
+            assignSectionForLayout(field, section);
+            return toSerializedSectionField(field.getApiName());
+        }
+        if (isFieldRef(entry)) {
+            const field = this._resolveField(entry.field);
+            this.assertFieldBelongsToLayout(field);
+            assignSectionForLayout(field, section);
+            return toSerializedSectionField(field.getApiName(), entry);
+        }
+        throw new Error(`CustomObjectPageLayout fields_section "${sectionKey}" has an invalid field entry; ` +
+            'pass a Field instance or { field }.');
+    }
+    normalizeSectionForMutation(input) {
+        if (input.type !== 'fields_section')
+            return { ...input };
+        this.assertFieldSectionBelongsToLayout(input.section);
+        const sectionKey = input.key ?? input.section.getSectionId();
+        const name = input.name ?? input.section.getName();
+        const normalized = copySectionOptions({
+            name,
+            type: 'fields_section',
+            fields: input.fields.map((field) => this.normalizeSectionFieldForMutation(input.section, sectionKey, field)),
+        }, input);
+        if (input.layout != null)
+            normalized.layout = input.layout;
+        return attachLayoutSectionKey(normalized, sectionKey);
+    }
+    normalizeTabForMutation(tab) {
+        if (tab.type === 'custom_tab')
+            return { ...tab };
+        return {
+            ...tab,
+            sections: tab.sections.map((section) => this.normalizeSectionForMutation(section)),
+        };
+    }
+    assignFieldSectionForMutation(field, fallbackSectionKey, fieldSection) {
+        if (field.isStandard())
+            return;
+        const rawFieldSection = fieldSection;
+        if (rawFieldSection != null) {
+            if (typeof rawFieldSection === 'string') {
+                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) {
+                throw new Error(`CustomObjectPageLayout field section "${rawFieldSection.getSectionId()}" belongs to ` +
+                    `"${rawFieldSection.getModelApiName()}", but the layout belongs to "${this._customObjectApiName}".`);
+            }
+            field._assignSection(rawFieldSection);
+            return;
+        }
+        if (field.getSectionId() == null) {
+            throw new Error(`CustomObjectPageLayout field "${field.getApiName()}" is missing field-section metadata. ` +
+                `Construct the field with a CustomObjectFieldSection or pass section when adding it to ` +
+                `section "${fallbackSectionKey}".`);
+        }
+    }
+    assertFieldBelongsToLayout(field) {
+        if (field.getCustomObjectApiName() !== this._customObjectApiName) {
+            throw new Error(`CustomObjectPageLayout references field "${field.getApiName()}" from ` +
+                `"${field.getCustomObjectApiName()}", but the layout belongs to "${this._customObjectApiName}".`);
+        }
+    }
+    _resolveField(field) {
+        return this._customObject._resolveField(field);
+    }
+    fieldApiName(field) {
+        if (typeof field !== 'string')
+            return field.getApiName();
+        if (field.endsWith('__c'))
+            return field;
+        return this._customObject.standardField(field).getApiName();
+    }
+    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}".`);
+        }
+    }
+    rememberFieldSectionLayoutSection(section, tabKey, sectionKey) {
+        if (sectionKey == null)
+            return;
+        addFieldSectionLayoutSection(this._fieldSectionLayoutSections, section.getSectionId(), {
+            tabKey,
+            sectionKey,
+        });
+    }
+    layoutSectionKeyForFieldSection(tabKey, section) {
+        const entries = this._fieldSectionLayoutSections.get(section.getSectionId()) ?? [];
+        const matches = tabKey == null ? entries : entries.filter((entry) => entry.tabKey === tabKey);
+        const sectionKeys = [...new Set(matches.map((entry) => entry.sectionKey))];
+        if (sectionKeys.length === 0)
+            return undefined;
+        if (sectionKeys.length === 1)
+            return sectionKeys[0];
+        const scope = tabKey == null ? '' : ` in tab "${tabKey}"`;
+        throw new Error(`CustomObjectPageLayout field section "${section.getSectionId()}" maps to multiple layout sections${scope}: ` +
+            `${sectionKeys.join(', ')}. Pass sectionKey to choose one.`);
+    }
+    requireOneFieldContainer(tabKey, sectionKey, fallbackFieldSection) {
+        const containers = this.findFieldContainers({
+            tabKey,
+            sectionKey,
+            systemSectionOnly: false,
+        });
+        if (containers.length === 0) {
+            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];
+                    attachLayoutSectionKey(container.section, sectionKey);
+                    container.sectionKey = sectionKey;
+                    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.`);
+        }
+        return containers[0];
+    }
+    findFieldContainers(filter) {
+        const containers = [];
+        if (!filter.systemSectionOnly) {
+            for (const tab of this._tabEdits.newTabs ?? []) {
+                if (!isTabWithSections(tab))
+                    continue;
+                if (filter.tabKey != null && tab.key !== filter.tabKey)
+                    continue;
+                for (const [index, section] of tab.sections.entries()) {
+                    if (!isSerializedFieldsSection(section))
+                        continue;
+                    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,
+                        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 [index, section] of (tabEdit.newSections ?? []).entries()) {
+                    if (!isSerializedFieldsSection(section))
+                        continue;
+                    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,
+                        fields: ensureArrayProperty(section, 'fields', `systemTabEdits.${label}.fields`),
+                        label,
+                    });
+                }
+            }
+        }
+        for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
+            if (filter.tabKey != null && tabKey !== filter.tabKey)
+                continue;
+            for (const [sectionKey, sectionEdit] of Object.entries(tabEdit.systemSectionEdits ?? {})) {
+                if (filter.sectionKey != null && sectionKey !== filter.sectionKey)
+                    continue;
+                const fields = sectionEdit['newFields'];
+                if (fields == null)
+                    continue;
+                if (!Array.isArray(fields)) {
+                    throw new Error(`systemTabEdits.${tabKey}.systemSectionEdits.${sectionKey}.newFields must be an array.`);
+                }
+                containers.push({
+                    tabKey,
+                    sectionKey,
+                    fields: fields,
+                    label: `${tabKey}.${sectionKey}`,
+                });
+            }
+        }
+        return containers;
+    }
+    ensureSystemSectionFieldContainer(tabKey, sectionKey) {
+        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.`);
+        }
+        return {
+            tabKey,
+            sectionKey,
+            fields: ensureArrayProperty(sectionEdit, 'newFields', `systemTabEdits.${tabKey}.systemSectionEdits.${sectionKey}.newFields`),
+            label: `${tabKey}.${sectionKey}`,
+        };
+    }
+    ensureSystemTabEdit(tabKey) {
+        const systemTabEdits = ensureRecordProperty(this._tabEdits, 'systemTabEdits', 'tab_edits.systemTabEdits');
+        return ensureRecordProperty(systemTabEdits, tabKey, `systemTabEdits.${tabKey}`);
+    }
+    ensureSystemSectionEdit(tabKey, sectionKey) {
+        const tabEdit = this.ensureSystemTabEdit(tabKey);
+        const systemSectionEdits = ensureRecordProperty(tabEdit, 'systemSectionEdits', `systemTabEdits.${tabKey}.systemSectionEdits`);
+        return ensureRecordProperty(systemSectionEdits, sectionKey, `systemTabEdits.${tabKey}.systemSectionEdits.${sectionKey}`);
+    }
+    findNewTabWithSections(tabKey) {
+        let found;
+        for (const tab of this._tabEdits.newTabs ?? []) {
+            if (tab.key !== tabKey)
+                continue;
+            if (!isTabWithSections(tab)) {
+                throw new Error(`CustomObjectPageLayout tab "${tabKey}" is a custom_tab and cannot contain sections.`);
+            }
+            if (found != null) {
+                throw new Error(`CustomObjectPageLayout contains multiple new tabs with key "${tabKey}".`);
+            }
+            found = tab;
+        }
+        return found;
+    }
+    assertSectionKeyAvailable(sections, sectionKey, tabKey, allowDuplicate) {
+        if (allowDuplicate === true)
+            return;
+        if (sectionKey != null && sections.some((section) => layoutSectionMatches(section, sectionKey))) {
+            throw new Error(`CustomObjectPageLayout tab "${tabKey}" already contains section "${sectionKey}".`);
+        }
+    }
+    normalizeHeaderFieldForMutation(field, options) {
+        const source = isField(field) ? undefined : field;
+        const rqlName = isField(field) ? field.getApiName() : field.rqlName;
+        if (isField(field))
+            this.assertFieldBelongsToLayout(field);
+        if (!rqlName)
+            throw new Error('CustomObjectPageLayout header field rqlName cannot be empty.');
+        const key = options.key ?? source?.key ?? (isField(field) ? field.getApiName() : undefined);
+        if (!key)
+            throw new Error('CustomObjectPageLayout header field key cannot be empty.');
+        const normalized = { rqlName, key };
+        const canBeDeleted = options.canBeDeleted ?? source?.canBeDeleted;
+        const canBeChanged = options.canBeChanged ?? source?.canBeChanged;
+        const canBeMoved = options.canBeMoved ?? source?.canBeMoved;
+        if (canBeDeleted != null)
+            normalized.canBeDeleted = canBeDeleted;
+        if (canBeChanged != null)
+            normalized.canBeChanged = canBeChanged;
+        if (canBeMoved != null)
+            normalized.canBeMoved = canBeMoved;
+        return normalized;
+    }
+    headerFieldApiName(field) {
+        if (typeof field === 'string')
+            return this.fieldApiName(field);
+        this.assertFieldBelongsToLayout(field);
+        return field.getApiName();
+    }
+    removeSectionVisibility(sectionKey) {
+        if (this._visibilityConditions.sections != null) {
+            delete this._visibilityConditions.sections[sectionKey];
+        }
+    }
+    removeTabVisibility(tabKey) {
+        if (this._visibilityConditions.tabs != null) {
+            delete this._visibilityConditions.tabs[tabKey];
+        }
+    }
+    /**
+     * Serializes this layout to the wire format consumed by the manifest install endpoint.
+     *
+     * @returns A plain object with `type: 'CUSTOM_OBJECT_PAGE_LAYOUT'`.
+     */
+    toDict() {
+        const tabEdits = cloneJson(this._tabEdits);
+        stripMovementOptions(tabEdits);
+        const d = {
+            type: CustomObjectPageLayout.componentType,
+            layout_id: this._layoutId,
+            api_name: this._apiName,
+            object_rql_name: this._customObjectApiName,
+            name: this._name,
+            // Packaged layouts are never system-created (backend invariant).
+            system_created: false,
+            tab_edits: tabEdits,
+            header_edits: this._headerEdits,
+            visibility_conditions: this._visibilityConditions,
+            blueprint_key: this._blueprintKey ?? this._customObjectApiName,
+        };
+        return d;
+    }
+    /**
+     * Creates a simple single-tab "Details" layout with a single "General" section.
+     *
+     * Use this factory when you want a straightforward layout without customizing
+     * tabs or sections. Always uses `apiName: 'default'`.
+     *
+     * @param customObject - The custom object to create the layout for.
+     * @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],
+     * });
+     * ```
+     */
+    static basic(customObject, props = {}) {
+        const coApiName = customObject.getApiName();
+        const coName = customObject.getName();
+        const fields = (props.fields ?? []).map((field) => customObject._resolveField(field));
+        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`,
+            tabEdits: {
+                newTabs: [
+                    {
+                        key: 'details',
+                        name: 'Details',
+                        type: 'tab_with_sections',
+                        sections: [
+                            {
+                                name: 'General',
+                                type: 'fields_section',
+                                section: generalSection,
+                                fields,
+                            },
+                        ],
+                    },
+                ],
+                systemTabEdits: {},
+                tabsOrder: ['details'],
+            },
+            headerEdits: {},
+            visibilityConditions: {},
+        });
+    }
+}
+CustomObjectPageLayout.componentType = 'CUSTOM_OBJECT_PAGE_LAYOUT';
+//# sourceMappingURL=custom-object-page-layout.mjs.map