@rippling/rippling-sdk 0.2.0-alpha.39 → 0.2.0-alpha.40

package/src/lib/manifest/custom-object-page-layout.ts

@@ -219,6 +219,130 @@ export interface VisibilityConditions {
   tabs?: Record<string, VisibilityCondition>;
 }
 
+// ---------------------------------------------------------------------------
+// Mutation helpers
+// ---------------------------------------------------------------------------
+
+/** Where to insert a new layout item. Defaults to `'end'`. */
+export type PageLayoutMutationPosition = 'start' | 'end' | number;
+
+/** Options for adding a field to an existing layout section. */
+export interface AddPageLayoutFieldOptions extends SectionFieldOptions {
+  /**
+   * Tab key containing the target section. Optional when `sectionKey` is unique
+   * across the layout.
+   */
+  tabKey?: string;
+  /** Section key to add the field to. Required. */
+  sectionKey: string;
+  /**
+   * Field-section metadata to assign to the field component.
+   *
+   * Existing layouts often use layout section keys that differ from field section
+   * ids. Pass this when the field was not constructed with a `section`.
+   */
+  fieldSection?: CustomObjectFieldSection | string;
+  /** Insert position inside the section field list. Optional. @default `'end'` */
+  position?: PageLayoutMutationPosition;
+  /** Allow the same field to appear twice in the same section. Optional. @default false */
+  allowDuplicate?: boolean;
+  /**
+   * Add to a built-in system section via `systemTabEdits`.
+   *
+   * When true, `tabKey` is required and the edit is created if it does not
+   * already exist.
+   */
+  systemSection?: boolean;
+}
+
+/** Options for adding multiple fields to an existing layout section. */
+export type AddPageLayoutFieldsOptions = AddPageLayoutFieldOptions;
+
+/** Options for removing fields from a layout. */
+export interface RemovePageLayoutFieldOptions {
+  /** Limit removal to one tab. Optional. */
+  tabKey?: string;
+  /** Limit removal to one section. Optional. */
+  sectionKey?: string;
+  /**
+   * Remove all matching occurrences. When false, removing a field that appears
+   * more than once throws. Optional. @default true
+   */
+  removeAll?: boolean;
+  /** Remove from a built-in system section edit. Optional. */
+  systemSection?: boolean;
+}
+
+/** Options for adding a section to an existing tab. */
+export interface AddPageLayoutSectionOptions {
+  /** Tab key to add the section to. Required. */
+  tabKey: string;
+  /** Insert position inside the tab. Optional. @default `'end'` */
+  position?: PageLayoutMutationPosition;
+  /** Allow another section with the same key in the same tab. Optional. @default false */
+  allowDuplicate?: boolean;
+  /**
+   * Add to a built-in system tab via `systemTabEdits.newSections`.
+   *
+   * When false, the tab must already be present in `newTabs`.
+   */
+  systemTab?: boolean;
+}
+
+/** Options for removing sections from a layout. */
+export interface RemovePageLayoutSectionOptions {
+  /** Limit removal to one tab. Optional. */
+  tabKey?: string;
+  /**
+   * Remove all matching occurrences. When false, removing a section that appears
+   * more than once throws. Optional. @default true
+   */
+  removeAll?: boolean;
+  /** Delete a built-in system section via `systemSectionEdits`. Requires `tabKey`. */
+  systemSection?: boolean;
+}
+
+/** Options for adding a tab to a layout. */
+export interface AddPageLayoutTabOptions {
+  /** Insert position inside `newTabs`. Optional. @default `'end'` */
+  position?: PageLayoutMutationPosition;
+  /** Allow another tab with the same key. Optional. @default false */
+  allowDuplicate?: boolean;
+}
+
+/** Options for removing a tab from a layout. */
+export interface RemovePageLayoutTabOptions {
+  /**
+   * Remove all matching occurrences. When false, removing a tab that appears
+   * more than once throws. Optional. @default true
+   */
+  removeAll?: boolean;
+  /** Delete a built-in system tab via `systemTabEdits`. */
+  systemTab?: boolean;
+}
+
+/** Options for adding a custom header field. */
+export interface AddHeaderFieldOptions extends Omit<NewHeaderField, 'rqlName' | 'key'> {
+  /**
+   * Stable header key. Defaults to the field api_name when adding a `Field`.
+   * Required when adding a raw `NewHeaderField`.
+   */
+  key?: string;
+  /** Insert position inside `newFields` and `headerFieldsOrder`. Optional. @default `'end'` */
+  position?: PageLayoutMutationPosition;
+  /** Allow another custom header field with the same key. Optional. @default false */
+  allowDuplicate?: boolean;
+}
+
+/** Options for removing custom header fields. */
+export interface RemoveHeaderFieldOptions {
+  /**
+   * Remove all matching occurrences. When false, removing a header field that
+   * appears more than once throws. Optional. @default true
+   */
+  removeAll?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Public props
 // ---------------------------------------------------------------------------
@@ -474,6 +598,94 @@ function cloneJson<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
+type MutableSectionField = SerializedSectionField | Record<string, any> | string;
+
+interface MutableFieldContainer {
+  tabKey: string;
+  sectionKey: string;
+  fields: MutableSectionField[];
+  label: string;
+}
+
+function isTabWithSections(tab: SerializedPageLayoutTab): tab is SerializedTabWithSections {
+  return tab.type === 'tab_with_sections';
+}
+
+function insertionIndex(length: number, position: PageLayoutMutationPosition | undefined): number {
+  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<T>(items: T[], item: T, position: PageLayoutMutationPosition | undefined): void {
+  items.splice(insertionIndex(items.length, position), 0, item);
+}
+
+function fieldRqlNameOf(entry: unknown): string | undefined {
+  if (typeof entry === 'string') return entry;
+  if (entry == null || typeof entry !== 'object') return undefined;
+  const record = entry as Record<string, any>;
+  const fieldRqlName = record['fieldRqlName'] ?? record['field_rql_name'];
+  return typeof fieldRqlName === 'string' ? fieldRqlName : undefined;
+}
+
+function removeIndexes<T>(items: T[], indexes: number[]): void {
+  for (const index of [...indexes].sort((a, b) => b - a)) {
+    items.splice(index, 1);
+  }
+}
+
+function removeFromArray<T>(
+  items: T[],
+  predicate: (item: T) => boolean,
+  label: string,
+  removeAll = true,
+): number {
+  const indexes: number[] = [];
+  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: string[] | undefined, key: string): void {
+  if (order == null) return;
+  removeFromArray(order, (entry) => entry === key, `order key "${key}"`);
+}
+
+function ensureRecordProperty(record: Record<string, any>, key: string, label: string): Record<string, any> {
+  const existing = record[key];
+  if (existing == null) {
+    const next: Record<string, any> = {};
+    record[key] = next;
+    return next;
+  }
+  if (typeof existing !== 'object' || Array.isArray(existing)) {
+    throw new Error(`${label} must be an object.`);
+  }
+  return existing as Record<string, any>;
+}
+
+function ensureArrayProperty<T>(record: Record<string, any>, key: string, label: string): T[] {
+  const existing = record[key];
+  if (existing == null) {
+    const next: T[] = [];
+    record[key] = next;
+    return next;
+  }
+  if (!Array.isArray(existing)) {
+    throw new Error(`${label} must be an array.`);
+  }
+  return existing as T[];
+}
+
 // ---------------------------------------------------------------------------
 // Class
 // ---------------------------------------------------------------------------
@@ -612,6 +824,611 @@ export class CustomObjectPageLayout {
     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: Field, options: AddPageLayoutFieldOptions): this {
+    return this.addFields([field], options);
+  }
+
+  /**
+   * 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, it is assigned to `options.fieldSection` when
+   * provided, otherwise to `options.sectionKey`.
+   */
+  addFields(fields: Field[], options: AddPageLayoutFieldsOptions): this {
+    if (fields.length === 0) return this;
+    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));
+
+    if (options.allowDuplicate !== true) {
+      const existing = new Set(container.fields.map((entry) => fieldRqlNameOf(entry)).filter(Boolean));
+      const seen = new Set<string>();
+      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: Field | string, options: RemovePageLayoutFieldOptions = {}): this {
+    const fieldApiName = typeof field === 'string' ? field : field.getApiName();
+    if (isField(field)) this.assertFieldBelongsToLayout(field);
+
+    const containers = this.findFieldContainers({
+      tabKey: options.tabKey,
+      sectionKey: options.sectionKey,
+      systemSectionOnly: options.systemSection === true,
+    });
+    const matches: Array<{ container: MutableFieldContainer; index: number }> = [];
+    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<MutableFieldContainer, number[]>();
+    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: Array<Field | string>, options: RemovePageLayoutFieldOptions = {}): this {
+    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: PageLayoutSection, options: AddPageLayoutSectionOptions): this {
+    const normalized = this.normalizeSectionForMutation(section);
+    if (options.systemTab === true) {
+      const tabEdit = this.ensureSystemTabEdit(options.tabKey);
+      const sections = ensureArrayProperty<SerializedFieldsSection>(
+        tabEdit as Record<string, any>,
+        'newSections',
+        `systemTabEdits.${options.tabKey}.newSections`,
+      );
+      this.assertSectionKeyAvailable(sections, normalized.key, options.tabKey, options.allowDuplicate);
+      insertAt(sections, normalized, options.position);
+      if (tabEdit.sectionsOrder != null) insertAt(tabEdit.sectionsOrder, normalized.key, options.position);
+      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, normalized.key, 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: string, options: RemovePageLayoutSectionOptions = {}): this {
+    if (options.systemSection === true) {
+      if (options.tabKey == null) {
+        throw new Error('CustomObjectPageLayout removeSection with systemSection: true requires tabKey.');
+      }
+      const sectionEdit = this.ensureSystemSectionEdit(options.tabKey, sectionKey);
+      sectionEdit.deleted = true;
+      this.removeSectionVisibility(sectionKey);
+      return this;
+    }
+
+    const matches: Array<{
+      sections: SerializedFieldsSection[];
+      index: number;
+      tabEdit?: SerializedSystemTabEdit;
+      tabKey: string;
+    }> = [];
+    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 (section.key === sectionKey) matches.push({ sections: tab.sections, 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 (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<SerializedFieldsSection[], number[]>();
+    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);
+    }
+    for (const [sections, indexes] of byArray.entries()) {
+      removeIndexes(sections, indexes);
+    }
+    this.removeSectionVisibility(sectionKey);
+    return this;
+  }
+
+  /** Adds a new tab to `tab_edits.newTabs`. */
+  addTab(tab: PageLayoutTab, options: AddPageLayoutTabOptions = {}): this {
+    const normalized = this.normalizeTabForMutation(tab);
+    const newTabs = (this._tabEdits.newTabs ??= []);
+    if (options.allowDuplicate !== true && newTabs.some((existing) => existing.key === normalized.key)) {
+      throw new Error(`CustomObjectPageLayout already contains tab "${normalized.key}".`);
+    }
+    insertAt(newTabs, normalized, options.position);
+    if (this._tabEdits.tabsOrder != null) {
+      insertAt(this._tabEdits.tabsOrder, normalized.key, options.position);
+    }
+    return this;
+  }
+
+  /**
+   * Removes a tab from `newTabs`.
+   *
+   * Pass `systemTab: true` to delete a built-in tab via `systemTabEdits[tabKey].deleted`.
+   */
+  removeTab(tabKey: string, options: RemovePageLayoutTabOptions = {}): this {
+    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: Field | NewHeaderField, options: AddHeaderFieldOptions = {}): this {
+    const headerField = this.normalizeHeaderFieldForMutation(field, options);
+    const newFields = (this._headerEdits.newFields ??= []);
+    if (options.allowDuplicate !== true && newFields.some((existing) => existing.key === headerField.key)) {
+      throw new Error(`CustomObjectPageLayout header already contains field key "${headerField.key}".`);
+    }
+    insertAt(newFields, headerField, options.position);
+    if (this._headerEdits.headerFieldsOrder != null) {
+      insertAt(this._headerEdits.headerFieldsOrder, headerField.key, options.position);
+    }
+    return this;
+  }
+
+  /** Removes custom header fields from `header_edits.newFields`. */
+  removeHeaderField(fieldOrKey: Field | string, options: RemoveHeaderFieldOptions = {}): this {
+    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 removedKeys: string[] = [];
+    const removed = removeFromArray(
+      newFields,
+      (field) => {
+        const matched = field.key === key || (fieldApiName != null && field.rqlName === fieldApiName);
+        if (matched) removedKeys.push(field.key);
+        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);
+    }
+    return this;
+  }
+
+  /** Sets the record title field in `header_edits`. */
+  setTitleField(field: Field | string | null): this {
+    this._headerEdits.newTitleField = this.headerFieldApiName(field);
+    if (field != null) this._headerEdits.titleFieldDeleted = false;
+    return this;
+  }
+
+  /** Removes the record title field from the header. */
+  removeTitleField(): this {
+    this._headerEdits.newTitleField = null;
+    this._headerEdits.titleFieldDeleted = true;
+    return this;
+  }
+
+  /** Sets the record description field in `header_edits`. */
+  setDescriptionField(field: Field | string | null): this {
+    this._headerEdits.newDescriptionField = this.headerFieldApiName(field);
+    if (field != null) this._headerEdits.descriptionFieldDeleted = false;
+    return this;
+  }
+
+  /** Removes the record description field from the header. */
+  removeDescriptionField(): this {
+    this._headerEdits.newDescriptionField = null;
+    this._headerEdits.descriptionFieldDeleted = true;
+    return this;
+  }
+
+  private serializeFieldForMutation(
+    field: Field,
+    fallbackSectionKey: string,
+    options: AddPageLayoutFieldOptions,
+  ): SerializedSectionField {
+    this.assertFieldBelongsToLayout(field);
+    this.assignFieldSectionForMutation(field, fallbackSectionKey, options.fieldSection);
+    return toSerializedSectionField(field.getApiName(), options);
+  }
+
+  private normalizeSectionFieldForMutation(
+    section: CustomObjectFieldSection | string,
+    sectionKey: string,
+    entry: SectionField,
+  ): SerializedSectionField {
+    if (isField(entry)) {
+      this.assertFieldBelongsToLayout(entry);
+      entry._assignSection(section);
+      return toSerializedSectionField(entry.getApiName());
+    }
+
+    if (isFieldRef(entry)) {
+      this.assertFieldBelongsToLayout(entry.field);
+      entry.field._assignSection(section);
+      return toSerializedSectionField(entry.field.getApiName(), entry);
+    }
+
+    throw new Error(
+      `CustomObjectPageLayout fields_section "${sectionKey}" has an invalid field entry; ` +
+        'pass a Field instance or { field }.',
+    );
+  }
+
+  private normalizeSectionForMutation(input: PageLayoutSection): SerializedFieldsSection {
+    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}".`,
+      );
+    }
+
+    const key = input.key ?? input.section.getSectionId();
+    const name = input.name ?? input.section.getName();
+    const normalized: SerializedFieldsSection = {
+      key,
+      name,
+      type: 'fields_section',
+      fields: input.fields.map((field) => this.normalizeSectionFieldForMutation(input.section, key, field)),
+    };
+    if (input.layout != null) normalized.layout = input.layout;
+    return normalized;
+  }
+
+  private normalizeTabForMutation(tab: PageLayoutTab): SerializedPageLayoutTab {
+    if (tab.type === 'custom_tab') return { ...tab };
+    return {
+      ...tab,
+      sections: tab.sections.map((section) => this.normalizeSectionForMutation(section)),
+    };
+  }
+
+  private assignFieldSectionForMutation(
+    field: Field,
+    fallbackSectionKey: string,
+    fieldSection: CustomObjectFieldSection | string | undefined,
+  ): void {
+    if (fieldSection != null) {
+      if (typeof fieldSection !== 'string' && fieldSection.getModelApiName() !== this._customObjectApiName) {
+        throw new Error(
+          `CustomObjectPageLayout field section "${fieldSection.getSectionId()}" belongs to ` +
+            `"${fieldSection.getModelApiName()}", but the layout belongs to "${this._customObjectApiName}".`,
+        );
+      }
+      field._assignSection(fieldSection);
+      return;
+    }
+
+    if (field.getSectionId() == null) {
+      field._assignSection(fallbackSectionKey);
+    }
+  }
+
+  private assertFieldBelongsToLayout(field: Field): void {
+    if (field.getCustomObjectApiName() !== this._customObjectApiName) {
+      throw new Error(
+        `CustomObjectPageLayout references field "${field.getApiName()}" from ` +
+          `"${field.getCustomObjectApiName()}", but the layout belongs to "${this._customObjectApiName}".`,
+      );
+    }
+  }
+
+  private requireOneFieldContainer(tabKey: string | undefined, sectionKey: string): MutableFieldContainer {
+    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 (containers.length > 1) {
+      throw new Error(
+        `CustomObjectPageLayout section "${sectionKey}" matched multiple sections: ` +
+          `${containers.map((container) => container.label).join(', ')}. Pass tabKey to choose one.`,
+      );
+    }
+    return containers[0] as MutableFieldContainer;
+  }
+
+  private findFieldContainers(filter: {
+    tabKey: string | undefined;
+    sectionKey: string | undefined;
+    systemSectionOnly: boolean;
+  }): MutableFieldContainer[] {
+    const containers: MutableFieldContainer[] = [];
+
+    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 section of tab.sections) {
+          if (filter.sectionKey != null && section.key !== filter.sectionKey) continue;
+          containers.push({
+            tabKey: tab.key,
+            sectionKey: section.key,
+            fields: ensureArrayProperty<MutableSectionField>(
+              section as unknown as Record<string, any>,
+              'fields',
+              `newTabs.${tab.key}.sections.${section.key}.fields`,
+            ),
+            label: `${tab.key}.${section.key}`,
+          });
+        }
+      }
+
+      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) continue;
+          containers.push({
+            tabKey,
+            sectionKey: section.key,
+            fields: ensureArrayProperty<MutableSectionField>(
+              section as unknown as Record<string, any>,
+              'fields',
+              `systemTabEdits.${tabKey}.newSections.${section.key}.fields`,
+            ),
+            label: `${tabKey}.${section.key}`,
+          });
+        }
+      }
+    }
+
+    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 as Record<string, any>)['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 as MutableSectionField[],
+          label: `${tabKey}.${sectionKey}`,
+        });
+      }
+    }
+
+    return containers;
+  }
+
+  private ensureSystemSectionFieldContainer(
+    tabKey: string | undefined,
+    sectionKey: string,
+  ): MutableFieldContainer {
+    if (tabKey == null) {
+      throw new Error('CustomObjectPageLayout addField with systemSection: true requires tabKey.');
+    }
+    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<MutableSectionField>(
+        sectionEdit as Record<string, any>,
+        'newFields',
+        `systemTabEdits.${tabKey}.systemSectionEdits.${sectionKey}.newFields`,
+      ),
+      label: `${tabKey}.${sectionKey}`,
+    };
+  }
+
+  private ensureSystemTabEdit(tabKey: string): SerializedSystemTabEdit {
+    const systemTabEdits = ensureRecordProperty(
+      this._tabEdits as unknown as Record<string, any>,
+      'systemTabEdits',
+      'tab_edits.systemTabEdits',
+    );
+    return ensureRecordProperty(
+      systemTabEdits,
+      tabKey,
+      `systemTabEdits.${tabKey}`,
+    ) as SerializedSystemTabEdit;
+  }
+
+  private ensureSystemSectionEdit(tabKey: string, sectionKey: string): SerializedSystemSectionEdit {
+    const tabEdit = this.ensureSystemTabEdit(tabKey);
+    const systemSectionEdits = ensureRecordProperty(
+      tabEdit as Record<string, any>,
+      'systemSectionEdits',
+      `systemTabEdits.${tabKey}.systemSectionEdits`,
+    );
+    return ensureRecordProperty(
+      systemSectionEdits,
+      sectionKey,
+      `systemTabEdits.${tabKey}.systemSectionEdits.${sectionKey}`,
+    ) as SerializedSystemSectionEdit;
+  }
+
+  private findNewTabWithSections(tabKey: string): SerializedTabWithSections | undefined {
+    let found: SerializedTabWithSections | undefined;
+    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;
+  }
+
+  private assertSectionKeyAvailable(
+    sections: SerializedFieldsSection[],
+    sectionKey: string,
+    tabKey: string,
+    allowDuplicate: boolean | undefined,
+  ): void {
+    if (allowDuplicate === true) return;
+    if (sections.some((section) => section.key === sectionKey)) {
+      throw new Error(`CustomObjectPageLayout tab "${tabKey}" already contains section "${sectionKey}".`);
+    }
+  }
+
+  private normalizeHeaderFieldForMutation(
+    field: Field | NewHeaderField,
+    options: AddHeaderFieldOptions,
+  ): NewHeaderField {
+    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: NewHeaderField = { 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;
+  }
+
+  private headerFieldApiName(field: Field | string | null): string | null {
+    if (field == null) return null;
+    if (typeof field === 'string') return field;
+    this.assertFieldBelongsToLayout(field);
+    return field.getApiName();
+  }
+
+  private removeSectionVisibility(sectionKey: string): void {
+    if (this._visibilityConditions.sections != null) {
+      delete this._visibilityConditions.sections[sectionKey];
+    }
+  }
+
+  private removeTabVisibility(tabKey: string): void {
+    if (this._visibilityConditions.tabs != null) {
+      delete this._visibilityConditions.tabs[tabKey];
+    }
+  }
+
   /**
    * Serializes this layout to the wire format consumed by the manifest install endpoint.
    *