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

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

@@ -27,7 +27,7 @@ export interface SystemHeaderFieldEdit {
  * Custom header field added via `newFields`.
  *
  * `key` is required and must be non-empty — it is used as the stable identity
- * for this field in `headerFieldsOrder` and visibility conditions.
+ * for this field in visibility conditions.
  */
 export interface NewHeaderField {
   /** RQL field name to display. Required. */
@@ -64,7 +64,7 @@ export interface HeaderEdits {
   systemFieldEdits?: Record<string, SystemHeaderFieldEdit>;
   /** Additional custom fields to add to the header. Optional. */
   newFields?: NewHeaderField[];
-  /** Ordered list of header field `key` values (custom + system). Optional. */
+  /** Ordered list of header field RQL names. Custom header keys are accepted and converted. Optional. */
   headerFieldsOrder?: string[];
   /** Action button keys to show in the header. Optional. */
   buttons?: string[];
@@ -98,8 +98,6 @@ export interface FieldsSection {
   type: 'fields_section';
   /** Field section metadata for the fields displayed in this layout section. Required. */
   section: CustomObjectFieldSection;
-  /** Stable layout key for this section. Optional. Defaults to the field section id. */
-  key?: string;
   /** Display name of the layout section. Optional. Defaults to the field section name. */
   name?: string;
   /** Fields to display in this section. Required. */
@@ -227,53 +225,93 @@ export interface VisibilityConditions {
 /** 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;
+interface AddPageLayoutFieldOptionsBase extends SectionFieldOptions {
   /** 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;
+}
+
+/** Options for adding a field to a typed custom-object field section. */
+export interface AddCustomPageLayoutFieldOptions extends AddPageLayoutFieldOptionsBase {
+  /**
+   * Tab key containing the target section. Optional when `section` is unique
+   * across the layout.
+   */
+  tabKey?: string;
+  /** Field section to add the field to. Required for custom layout sections. */
+  section: CustomObjectFieldSection;
+  /** Raw section keys are only accepted for built-in system sections. */
+  sectionKey?: never;
+  /** Deprecated. Use `section`. */
+  fieldSection?: never;
+  /** Custom layout sections are selected by `section`; `sectionKey` is only for system sections. */
+  systemSection?: false;
+}
+
+/** Options for adding a field to a built-in system section. */
+export interface AddSystemPageLayoutFieldOptions extends AddPageLayoutFieldOptionsBase {
   /**
    * 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.
+   * When true, `tabKey` and `sectionKey` are required and the edit is created
+   * if it does not already exist.
    */
-  systemSection?: boolean;
+  systemSection: true;
+  /** System tab key containing the target section. Required. */
+  tabKey: string;
+  /** Built-in system section key. Required. */
+  sectionKey: string;
+  /** Custom field-section objects are only accepted for custom layout sections. */
+  section?: never;
+  /** Deprecated. Use `section` for custom sections, or `sectionKey` for system sections. */
+  fieldSection?: never;
 }
 
+/** Options for adding a field to an existing layout section. */
+export type AddPageLayoutFieldOptions = AddCustomPageLayoutFieldOptions | AddSystemPageLayoutFieldOptions;
+
 /** 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;
+interface RemovePageLayoutFieldOptionsBase {
   /**
    * 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 removing fields from typed custom-object field sections. */
+export interface RemoveCustomPageLayoutFieldOptions extends RemovePageLayoutFieldOptionsBase {
+  /** Limit removal to one tab. Optional. */
+  tabKey?: string;
+  /** Limit removal to one field section. Optional. */
+  section?: CustomObjectFieldSection;
+  /** Raw section keys are only accepted for built-in system sections. */
+  sectionKey?: never;
+  /** Custom layout sections are selected by `section`; `sectionKey` is only for system sections. */
+  systemSection?: false;
+}
+
+/** Options for removing fields from built-in system section edits. */
+export interface RemoveSystemPageLayoutFieldOptions extends RemovePageLayoutFieldOptionsBase {
+  /** Remove from a built-in system section edit. Required. */
+  systemSection: true;
+  /** System tab key containing the target section. Required. */
+  tabKey: string;
+  /** Built-in system section key. Required. */
+  sectionKey: string;
+  /** Custom field-section objects are only accepted for custom layout sections. */
+  section?: never;
+}
+
+/** Options for removing fields from a layout. */
+export type RemovePageLayoutFieldOptions =
+  | RemoveCustomPageLayoutFieldOptions
+  | RemoveSystemPageLayoutFieldOptions;
+
 /** Options for adding a section to an existing tab. */
 export interface AddPageLayoutSectionOptions {
   /** Tab key to add the section to. Required. */
@@ -299,13 +337,21 @@ export interface RemovePageLayoutSectionOptions {
    * more than once throws. Optional. @default true
    */
   removeAll?: boolean;
-  /** Delete a built-in system section via `systemSectionEdits`. Requires `tabKey`. */
-  systemSection?: boolean;
+  /** Custom layout sections are selected by `CustomObjectFieldSection`; raw keys are only for system sections. */
+  systemSection?: false;
+}
+
+/** Options for removing a built-in system section from a layout. */
+export interface RemoveSystemPageLayoutSectionOptions {
+  /** System tab key containing the target section. Required. */
+  tabKey: string;
+  /** Delete a built-in system section via `systemSectionEdits`. Required. */
+  systemSection: true;
 }
 
 /** Options for adding a tab to a layout. */
 export interface AddPageLayoutTabOptions {
-  /** Insert position inside `newTabs`. Optional. @default `'end'` */
+  /** Insert position inside `newTabs` and `tabsOrder`. Optional. @default `'end'` */
   position?: PageLayoutMutationPosition;
   /** Allow another tab with the same key. Optional. @default false */
   allowDuplicate?: boolean;
@@ -409,7 +455,6 @@ interface SerializedSectionField extends SectionFieldOptions {
 
 interface SerializedFieldsSection {
   type: 'fields_section';
-  key: string;
   name: string;
   fields: SerializedSectionField[];
   layout?: SectionFieldsLayout;
@@ -459,6 +504,44 @@ function isFieldRef(value: SectionField): value is SectionFieldRef {
   return candidate != null && typeof candidate === 'object' && isField(candidate.field);
 }
 
+const FIELD_SECTION_ID = Symbol('CustomObjectPageLayout.fieldSectionId');
+
+function isCustomObjectFieldSection(value: unknown): value is CustomObjectFieldSection {
+  return value instanceof CustomObjectFieldSection;
+}
+
+function attachFieldSectionId(section: SerializedFieldsSection, sectionId: string): SerializedFieldsSection {
+  Object.defineProperty(section, FIELD_SECTION_ID, {
+    value: sectionId,
+    enumerable: false,
+    configurable: true,
+  });
+  return section;
+}
+
+function layoutSectionKey(section: SerializedFieldsSection): string | undefined {
+  return (section as unknown as Record<typeof FIELD_SECTION_ID, string | undefined>)[FIELD_SECTION_ID];
+}
+
+function layoutSectionMatches(section: SerializedFieldsSection, sectionKey: string): boolean {
+  return layoutSectionKey(section) === sectionKey;
+}
+
+function inputFieldsSectionHasKey(input: PageLayoutSection): boolean {
+  const record = input as unknown as Record<string, unknown>;
+  return Object.prototype.hasOwnProperty.call(record, 'key') && record['key'] != null;
+}
+
+function assertNoSerializedSectionKey(section: SerializedFieldsSection): void {
+  const record = section as unknown as Record<string, unknown>;
+  if (Object.prototype.hasOwnProperty.call(record, 'key') && record['key'] != null) {
+    throw new Error(
+      'CustomObjectPageLayout loaded fields_section key is not supported. ' +
+        'Remove key and target the section with CustomObjectFieldSection metadata.',
+    );
+  }
+}
+
 function assertSameObject(customObject: CustomObject, field: Field, sectionKey: string): void {
   if (field.getCustomObjectApiName() !== customObject.getApiName()) {
     throw new Error(
@@ -477,6 +560,22 @@ function assertSectionBelongsTo(customObject: CustomObject, section: CustomObjec
   }
 }
 
+function requireFieldSectionOption(value: unknown, label: string): CustomObjectFieldSection {
+  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: unknown, key: string, message: string): void {
+  if (options == null || typeof options !== 'object') return;
+  if (Object.prototype.hasOwnProperty.call(options, key)) throw new TypeError(message);
+}
+
 function toSerializedSectionField(
   fieldRqlName: string,
   options: SectionFieldOptions = {},
@@ -517,16 +616,18 @@ function normalizeFieldsSection(
   input: PageLayoutSection,
 ): SerializedFieldsSection {
   assertSectionBelongsTo(customObject, input.section);
-  const key = input.key ?? input.section.getSectionId();
+  const sectionId = input.section.getSectionId();
+  if (inputFieldsSectionHasKey(input)) {
+    throw new Error('CustomObjectPageLayout fields_section key is not supported. Omit key.');
+  }
   const name = input.name ?? input.section.getName();
   const normalized: SerializedFieldsSection = {
-    key,
     name,
     type: 'fields_section',
-    fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, key, field)),
+    fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, sectionId, field)),
   };
   if (input.layout != null) normalized.layout = input.layout;
-  return normalized;
+  return attachFieldSectionId(normalized, sectionId);
 }
 
 function normalizeTab(customObject: CustomObject, tab: PageLayoutTab): SerializedPageLayoutTab {
@@ -599,11 +700,111 @@ function cloneJson<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
+const HEADER_EDIT_KEYS = new Set([
+  'newTitleField',
+  'titleFieldDeleted',
+  'newDescriptionField',
+  'descriptionFieldDeleted',
+  'systemFieldEdits',
+  'newFields',
+  'headerFieldsOrder',
+  'buttons',
+]);
+
+const SYSTEM_HEADER_FIELD_EDIT_KEYS = new Set(['newRqlField', 'deleted']);
+
+const NEW_HEADER_FIELD_KEYS = new Set(['rqlName', 'key', 'canBeDeleted', 'canBeChanged', 'canBeMoved']);
+
+function assertKnownKeys(
+  record: Record<string, unknown>,
+  allowedKeys: ReadonlySet<string>,
+  label: string,
+  hint: string,
+): void {
+  for (const key of Object.keys(record)) {
+    if (!allowedKeys.has(key)) {
+      throw new Error(`${label} contains unsupported key "${key}". ${hint}`);
+    }
+  }
+}
+
+function normalizeHeaderEdits(headerEdits: HeaderEdits): HeaderEdits {
+  assertKnownKeys(
+    headerEdits as unknown as Record<string, unknown>,
+    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 as Record<string, unknown>,
+      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 as unknown as Record<string, unknown>,
+      NEW_HEADER_FIELD_KEYS,
+      `CustomObjectPageLayout headerEdits.newFields[${index}]`,
+      'Use { rqlName, key } entries, or call addHeaderField(field).',
+    );
+  }
+
+  if (headerEdits.headerFieldsOrder == null) return headerEdits;
+  return {
+    ...headerEdits,
+    headerFieldsOrder: normalizeHeaderFieldsOrder(headerEdits),
+  };
+}
+
+function addUniqueHeaderOrderField(order: string[], field: unknown): void {
+  if (typeof field !== 'string' || field.length === 0) return;
+  if (!order.includes(field)) order.push(field);
+}
+
+function normalizeHeaderFieldsOrder(headerEdits: HeaderEdits): string[] {
+  const customFieldRqlByKey = new Map(
+    (headerEdits.newFields ?? []).map((field) => [field.key, field.rqlName]),
+  );
+  const systemFieldRqlByKey = new Map(
+    Object.entries(headerEdits.systemFieldEdits ?? {})
+      .filter((entry): entry is [string, SystemHeaderFieldEdit & { newRqlField: string }] => {
+        const [, edit] = entry;
+        return typeof edit.newRqlField === 'string' && edit.newRqlField.length > 0;
+      })
+      .map(([key, edit]) => [key, edit.newRqlField]),
+  );
+  const order: string[] = [];
+
+  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;
+}
+
 type MutableSectionField = SerializedSectionField | Record<string, any> | string;
 
 interface MutableFieldContainer {
   tabKey: string;
-  sectionKey: string;
+  sectionKey: string | undefined;
+  section?: SerializedFieldsSection;
   fields: MutableSectionField[];
   label: string;
 }
@@ -625,6 +826,15 @@ function insertAt<T>(items: T[], item: T, position: PageLayoutMutationPosition |
   items.splice(insertionIndex(items.length, position), 0, item);
 }
 
+function insertUniqueAt(
+  items: string[],
+  item: string | null | undefined,
+  position: PageLayoutMutationPosition | undefined,
+): void {
+  if (item == null || item.length === 0 || items.includes(item)) return;
+  insertAt(items, item, position);
+}
+
 function fieldRqlNameOf(entry: unknown): string | undefined {
   if (typeof entry === 'string') return entry;
   if (entry == null || typeof entry !== 'object') return undefined;
@@ -633,6 +843,61 @@ function fieldRqlNameOf(entry: unknown): string | undefined {
   return typeof fieldRqlName === 'string' ? fieldRqlName : undefined;
 }
 
+function explicitFieldSectionId(entry: unknown): string | undefined {
+  if (entry == null || typeof entry !== 'object') return undefined;
+  const record = entry as Record<string, any>;
+  const fieldSectionId = record['fieldSection'] ?? record['field_section'];
+  return typeof fieldSectionId === 'string' ? fieldSectionId : undefined;
+}
+
+function inferredSectionIdFromFields(
+  section: SerializedFieldsSection,
+  resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
+): string | undefined {
+  const sectionIds = new Set<string>();
+  for (const field of section.fields ?? []) {
+    const explicitSectionId = explicitFieldSectionId(field);
+    if (explicitSectionId != null) {
+      sectionIds.add(explicitSectionId);
+      continue;
+    }
+
+    const fieldApiName = fieldRqlNameOf(field);
+    if (fieldApiName == null || resolveFieldSectionId == null) continue;
+    const resolvedSectionId = resolveFieldSectionId(fieldApiName);
+    if (resolvedSectionId != null) sectionIds.add(resolvedSectionId);
+  }
+  return sectionIds.size === 1 ? [...sectionIds][0] : undefined;
+}
+
+function annotateLoadedFieldsSection(
+  section: SerializedFieldsSection,
+  resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
+): SerializedFieldsSection {
+  assertNoSerializedSectionKey(section);
+  const sectionId = layoutSectionKey(section) ?? inferredSectionIdFromFields(section, resolveFieldSectionId);
+  return sectionId == null ? section : attachFieldSectionId(section, sectionId);
+}
+
+function annotateLoadedTabEdits(
+  tabEdits: SerializedTabEdits,
+  resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
+): SerializedTabEdits {
+  for (const tab of tabEdits.newTabs ?? []) {
+    if (!isTabWithSections(tab)) continue;
+    tab.sections = tab.sections.map((section) => annotateLoadedFieldsSection(section, resolveFieldSectionId));
+  }
+
+  for (const tabEdit of Object.values(tabEdits.systemTabEdits ?? {})) {
+    if (tabEdit.newSections != null) {
+      tabEdit.newSections = tabEdit.newSections.map((section) =>
+        annotateLoadedFieldsSection(section, resolveFieldSectionId),
+      );
+    }
+  }
+  return tabEdits;
+}
+
 function removeIndexes<T>(items: T[], indexes: number[]): void {
   for (const index of [...indexes].sort((a, b) => b - a)) {
     items.splice(index, 1);
@@ -715,7 +980,6 @@ function ensureArrayProperty<T>(record: Record<string, any>, key: string, label:
  *     newTabs: [{
  *       key: 'member', name: 'Member', type: 'tab_with_sections',
  *       sections: [{
- *         key: 'profile',
  *         name: 'Profile',
  *         type: 'fields_section',
  *         section: profileSection,
@@ -764,7 +1028,7 @@ export class CustomObjectPageLayout {
     this._customObjectApiName = customObject.getApiName();
     this._name = props.name;
     this._tabEdits = normalizeTabEdits(customObject, props.tabEdits ?? {});
-    this._headerEdits = props.headerEdits ?? {};
+    this._headerEdits = normalizeHeaderEdits(props.headerEdits ?? {});
     this._visibilityConditions = props.visibilityConditions ?? {};
     this._blueprintKey = props.blueprintKey;
     customObject._register(this);
@@ -788,6 +1052,7 @@ export class CustomObjectPageLayout {
   static _fromExistingComponent(
     customObject: CustomObject,
     component: Record<string, any>,
+    resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
   ): CustomObjectPageLayout {
     const layout = Object.create(CustomObjectPageLayout.prototype) as CustomObjectPageLayout;
     Object.assign(layout as Record<string, any>, {
@@ -799,7 +1064,7 @@ export class CustomObjectPageLayout {
         CustomObjectPageLayout.componentType,
       ),
       _name: requireStringComponentField(component, 'name', CustomObjectPageLayout.componentType),
-      _tabEdits: cloneJson(component['tab_edits'] ?? {}),
+      _tabEdits: annotateLoadedTabEdits(cloneJson(component['tab_edits'] ?? {}), resolveFieldSectionId),
       _headerEdits: cloneJson(component['header_edits'] ?? {}),
       _visibilityConditions: cloneJson(component['visibility_conditions'] ?? {}),
       _blueprintKey: component['blueprint_key'],
@@ -842,17 +1107,59 @@ export class CustomObjectPageLayout {
   /**
    * Adds multiple fields to an existing layout section.
    *
-   * Fields are inserted in the order provided. If a field does not already have
-   * field-section metadata, pass `options.fieldSection` so the corresponding
-   * `CUSTOM_OBJECT_FIELD_SECTION` component is registered in the manifest.
+   * Fields are inserted in the order provided. For custom layout sections,
+   * pass `options.section` so TypeScript and runtime validation agree on the
+   * target `CUSTOM_OBJECT_FIELD_SECTION`.
    */
   addFields(fields: Field[], options: AddPageLayoutFieldsOptions): this {
     if (fields.length === 0) return this;
+
+    let fieldSectionForMutation: CustomObjectFieldSection | undefined;
     const container =
       options.systemSection === true ?
-        this.ensureSystemSectionFieldContainer(options.tabKey, options.sectionKey)
-      : this.requireOneFieldContainer(options.tabKey, options.sectionKey);
-    const entries = fields.map((field) => this.serializeFieldForMutation(field, options.sectionKey, options));
+        (() => {
+          assertOptionAbsent(
+            options,
+            'section',
+            'CustomObjectPageLayout addField section is only supported for custom layout sections.',
+          );
+          assertOptionAbsent(
+            options,
+            'fieldSection',
+            'CustomObjectPageLayout addField fieldSection is no longer supported. ' +
+              'Use sectionKey only for systemSection: true.',
+          );
+          return this.ensureSystemSectionFieldContainer(options.tabKey, options.sectionKey);
+        })()
+      : (() => {
+          assertOptionAbsent(
+            options,
+            'sectionKey',
+            'CustomObjectPageLayout addField sectionKey is only supported with systemSection: true. ' +
+              'Pass section: CustomObjectFieldSection for custom layout sections.',
+          );
+          assertOptionAbsent(
+            options,
+            'fieldSection',
+            'CustomObjectPageLayout addField fieldSection is no longer supported. ' +
+              'Pass section: CustomObjectFieldSection instead.',
+          );
+          const section = requireFieldSectionOption(
+            options.section,
+            'CustomObjectPageLayout addField section',
+          );
+          this.assertFieldSectionBelongsToLayout(section);
+          fieldSectionForMutation = section;
+          return this.requireOneFieldContainer(options.tabKey, section.getSectionId(), section);
+        })();
+    const entries = fields.map((field) =>
+      this.serializeFieldForMutation(
+        field,
+        container.sectionKey ?? container.label,
+        options,
+        fieldSectionForMutation,
+      ),
+    );
 
     if (options.allowDuplicate !== true) {
       const existing = new Set(container.fields.map((entry) => fieldRqlNameOf(entry)).filter(Boolean));
@@ -883,9 +1190,34 @@ export class CustomObjectPageLayout {
     const fieldApiName = typeof field === 'string' ? field : field.getApiName();
     if (isField(field)) this.assertFieldBelongsToLayout(field);
 
+    let sectionKey: string | undefined;
+    if (options.systemSection === true) {
+      assertOptionAbsent(
+        options,
+        'section',
+        'CustomObjectPageLayout removeField section is only supported for custom layout sections.',
+      );
+      sectionKey = options.sectionKey;
+    } else {
+      assertOptionAbsent(
+        options,
+        'sectionKey',
+        'CustomObjectPageLayout removeField sectionKey is only supported with systemSection: true. ' +
+          'Pass section: CustomObjectFieldSection for custom layout sections.',
+      );
+      if (options.section != null) {
+        const section = requireFieldSectionOption(
+          options.section,
+          'CustomObjectPageLayout removeField section',
+        );
+        this.assertFieldSectionBelongsToLayout(section);
+        sectionKey = section.getSectionId();
+      }
+    }
+
     const containers = this.findFieldContainers({
       tabKey: options.tabKey,
-      sectionKey: options.sectionKey,
+      sectionKey,
       systemSectionOnly: options.systemSection === true,
     });
     const matches: Array<{ container: MutableFieldContainer; index: number }> = [];
@@ -944,9 +1276,15 @@ export class CustomObjectPageLayout {
         'newSections',
         `systemTabEdits.${options.tabKey}.newSections`,
       );
-      this.assertSectionKeyAvailable(sections, normalized.key, options.tabKey, options.allowDuplicate);
+      this.assertSectionKeyAvailable(
+        sections,
+        layoutSectionKey(normalized),
+        options.tabKey,
+        options.allowDuplicate,
+      );
+      const sectionsOrder = this.ensureSystemSectionsOrder(tabEdit);
       insertAt(sections, normalized, options.position);
-      if (tabEdit.sectionsOrder != null) insertAt(tabEdit.sectionsOrder, normalized.key, options.position);
+      insertUniqueAt(sectionsOrder, layoutSectionKey(normalized), options.position);
       return this;
     }
 
@@ -957,7 +1295,12 @@ export class CustomObjectPageLayout {
           'Pass systemTab: true to add a section to a built-in system tab.',
       );
     }
-    this.assertSectionKeyAvailable(tab.sections, normalized.key, options.tabKey, options.allowDuplicate);
+    this.assertSectionKeyAvailable(
+      tab.sections,
+      layoutSectionKey(normalized),
+      options.tabKey,
+      options.allowDuplicate,
+    );
     insertAt(tab.sections, normalized, options.position);
     return this;
   }
@@ -968,19 +1311,34 @@ export class CustomObjectPageLayout {
    * Pass `systemSection: true` with `tabKey` to delete a built-in section via
    * `systemSectionEdits[sectionKey].deleted`.
    */
-  removeSection(sectionKey: string, options: RemovePageLayoutSectionOptions = {}): this {
+  removeSection(section: CustomObjectFieldSection, options?: RemovePageLayoutSectionOptions): this;
+  removeSection(sectionKey: string, options: RemoveSystemPageLayoutSectionOptions): this;
+  removeSection(
+    sectionOrKey: CustomObjectFieldSection | string,
+    options: RemovePageLayoutSectionOptions | RemoveSystemPageLayoutSectionOptions = {},
+  ): this {
     if (options.systemSection === true) {
+      if (typeof sectionOrKey !== 'string') {
+        throw new TypeError(
+          'CustomObjectPageLayout removeSection with systemSection: true requires a system section key.',
+        );
+      }
       if (options.tabKey == null) {
         throw new Error('CustomObjectPageLayout removeSection with systemSection: true requires tabKey.');
       }
-      const sectionEdit = this.ensureSystemSectionEdit(options.tabKey, sectionKey);
+      const sectionEdit = this.ensureSystemSectionEdit(options.tabKey, sectionOrKey);
       sectionEdit.deleted = true;
-      this.removeSectionVisibility(sectionKey);
+      removeKeyFromOrder(this._tabEdits.systemTabEdits?.[options.tabKey]?.sectionsOrder, sectionOrKey);
+      this.removeSectionVisibility(sectionOrKey);
       return this;
     }
 
+    const section = requireFieldSectionOption(sectionOrKey, 'CustomObjectPageLayout removeSection section');
+    this.assertFieldSectionBelongsToLayout(section);
+    const sectionKey = section.getSectionId();
     const matches: Array<{
       sections: SerializedFieldsSection[];
+      section: SerializedFieldsSection;
       index: number;
       tabEdit?: SerializedSystemTabEdit;
       tabKey: string;
@@ -989,14 +1347,15 @@ export class CustomObjectPageLayout {
       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 });
+        if (layoutSectionMatches(section, sectionKey))
+          matches.push({ sections: tab.sections, section, index, tabKey: tab.key });
       });
     }
     for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
       if (options.tabKey != null && tabKey !== options.tabKey) continue;
       (tabEdit.newSections ?? []).forEach((section, index) => {
-        if (section.key === sectionKey)
-          matches.push({ sections: tabEdit.newSections!, index, tabEdit, tabKey });
+        if (layoutSectionMatches(section, sectionKey))
+          matches.push({ sections: tabEdit.newSections!, section, index, tabEdit, tabKey });
       });
     }
 
@@ -1018,11 +1377,11 @@ export class CustomObjectPageLayout {
       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);
     }
-    this.removeSectionVisibility(sectionKey);
     return this;
   }
 
@@ -1033,10 +1392,9 @@ export class CustomObjectPageLayout {
     if (options.allowDuplicate !== true && newTabs.some((existing) => existing.key === normalized.key)) {
       throw new Error(`CustomObjectPageLayout already contains tab "${normalized.key}".`);
     }
+    const tabsOrder = this.ensureTabsOrder();
     insertAt(newTabs, normalized, options.position);
-    if (this._tabEdits.tabsOrder != null) {
-      insertAt(this._tabEdits.tabsOrder, normalized.key, options.position);
-    }
+    insertUniqueAt(tabsOrder, normalized.key, options.position);
     return this;
   }
 
@@ -1076,10 +1434,9 @@ export class CustomObjectPageLayout {
     if (options.allowDuplicate !== true && newFields.some((existing) => existing.key === headerField.key)) {
       throw new Error(`CustomObjectPageLayout header already contains field key "${headerField.key}".`);
     }
+    const headerFieldsOrder = this.ensureHeaderFieldsOrder();
     insertAt(newFields, headerField, options.position);
-    if (this._headerEdits.headerFieldsOrder != null) {
-      insertAt(this._headerEdits.headerFieldsOrder, headerField.key, options.position);
-    }
+    insertUniqueAt(headerFieldsOrder, headerField.rqlName, options.position);
     return this;
   }
 
@@ -1089,12 +1446,12 @@ export class CustomObjectPageLayout {
     if (isField(fieldOrKey)) this.assertFieldBelongsToLayout(fieldOrKey);
     const key = typeof fieldOrKey === 'string' ? fieldOrKey : fieldApiName;
     const newFields = this._headerEdits.newFields ?? [];
-    const removedKeys: string[] = [];
+    const removedFields: NewHeaderField[] = [];
     const removed = removeFromArray(
       newFields,
       (field) => {
         const matched = field.key === key || (fieldApiName != null && field.rqlName === fieldApiName);
-        if (matched) removedKeys.push(field.key);
+        if (matched) removedFields.push(field);
         return matched;
       },
       `CustomObjectPageLayout header field "${key}"`,
@@ -1103,47 +1460,102 @@ export class CustomObjectPageLayout {
     if (removed === 0) {
       throw new Error(`CustomObjectPageLayout header does not contain field "${key}".`);
     }
-    for (const removedKey of removedKeys) {
-      removeKeyFromOrder(this._headerEdits.headerFieldsOrder, removedKey);
-    }
+    for (const removedField of removedFields) this.removeHeaderOrderFieldIfUnused(removedField);
     return this;
   }
 
   /** Sets the record title field in `header_edits`. */
   setTitleField(field: Field | string | null): this {
-    this._headerEdits.newTitleField = this.headerFieldApiName(field);
+    const previousTitleField = this._headerEdits.newTitleField;
+    const nextTitleField = this.headerFieldApiName(field);
+    this._headerEdits.newTitleField = nextTitleField;
     if (field != null) this._headerEdits.titleFieldDeleted = false;
+    insertUniqueAt(this.ensureHeaderFieldsOrder(), nextTitleField, 'end');
+    this.removeHeaderOrderFieldIfUnused(previousTitleField);
     return this;
   }
 
   /** Removes the record title field from the header. */
   removeTitleField(): this {
+    const previousTitleField = this._headerEdits.newTitleField;
     this._headerEdits.newTitleField = null;
     this._headerEdits.titleFieldDeleted = true;
+    this.removeHeaderOrderFieldIfUnused(previousTitleField);
     return this;
   }
 
   /** Sets the record description field in `header_edits`. */
   setDescriptionField(field: Field | string | null): this {
-    this._headerEdits.newDescriptionField = this.headerFieldApiName(field);
+    const previousDescriptionField = this._headerEdits.newDescriptionField;
+    const nextDescriptionField = this.headerFieldApiName(field);
+    this._headerEdits.newDescriptionField = nextDescriptionField;
     if (field != null) this._headerEdits.descriptionFieldDeleted = false;
+    insertUniqueAt(this.ensureHeaderFieldsOrder(), nextDescriptionField, 'end');
+    this.removeHeaderOrderFieldIfUnused(previousDescriptionField);
     return this;
   }
 
   /** Removes the record description field from the header. */
   removeDescriptionField(): this {
+    const previousDescriptionField = this._headerEdits.newDescriptionField;
     this._headerEdits.newDescriptionField = null;
     this._headerEdits.descriptionFieldDeleted = true;
+    this.removeHeaderOrderFieldIfUnused(previousDescriptionField);
     return this;
   }
 
+  private ensureTabsOrder(): string[] {
+    const order = (this._tabEdits.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;
+  }
+
+  private ensureSystemSectionsOrder(tabEdit: SerializedSystemTabEdit): string[] {
+    const order = (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;
+  }
+
+  private ensureHeaderFieldsOrder(): string[] {
+    this._headerEdits.headerFieldsOrder = normalizeHeaderFieldsOrder({
+      ...this._headerEdits,
+      headerFieldsOrder: this._headerEdits.headerFieldsOrder ?? [],
+    });
+    return this._headerEdits.headerFieldsOrder;
+  }
+
+  private headerOrderFieldIsUsed(rqlName: string): boolean {
+    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)
+    );
+  }
+
+  private removeHeaderOrderFieldIfUnused(field: NewHeaderField | string | null | undefined): void {
+    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);
+  }
+
   private serializeFieldForMutation(
     field: Field,
     fallbackSectionKey: string,
     options: AddPageLayoutFieldOptions,
+    fieldSection: CustomObjectFieldSection | undefined,
   ): SerializedSectionField {
     this.assertFieldBelongsToLayout(field);
-    this.assignFieldSectionForMutation(field, fallbackSectionKey, options.fieldSection);
+    this.assignFieldSectionForMutation(field, fallbackSectionKey, fieldSection);
     return toSerializedSectionField(field.getApiName(), options);
   }
 
@@ -1171,23 +1583,22 @@ export class CustomObjectPageLayout {
   }
 
   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}".`,
-      );
-    }
+    this.assertFieldSectionBelongsToLayout(input.section);
 
-    const key = input.key ?? input.section.getSectionId();
+    const sectionId = input.section.getSectionId();
+    if (inputFieldsSectionHasKey(input)) {
+      throw new Error('CustomObjectPageLayout fields_section key is not supported. Omit key.');
+    }
     const name = input.name ?? input.section.getName();
     const normalized: SerializedFieldsSection = {
-      key,
       name,
       type: 'fields_section',
-      fields: input.fields.map((field) => this.normalizeSectionFieldForMutation(input.section, key, field)),
+      fields: input.fields.map((field) =>
+        this.normalizeSectionFieldForMutation(input.section, sectionId, field),
+      ),
     };
     if (input.layout != null) normalized.layout = input.layout;
-    return normalized;
+    return attachFieldSectionId(normalized, sectionId);
   }
 
   private normalizeTabForMutation(tab: PageLayoutTab): SerializedPageLayoutTab {
@@ -1207,7 +1618,7 @@ export class CustomObjectPageLayout {
     if (rawFieldSection != null) {
       if (typeof rawFieldSection === 'string') {
         throw new TypeError(
-          `CustomObjectPageLayout fieldSection must be a CustomObjectFieldSection object; ` +
+          `CustomObjectPageLayout section must be a CustomObjectFieldSection object; ` +
             `received raw section id "${rawFieldSection}". Load/include the existing field section first.`,
         );
       }
@@ -1226,7 +1637,7 @@ export class CustomObjectPageLayout {
     if (field.getSectionId() == null) {
       throw new Error(
         `CustomObjectPageLayout field "${field.getApiName()}" is missing field-section metadata. ` +
-          `Construct the field with a CustomObjectFieldSection or pass fieldSection when adding it to ` +
+          `Construct the field with a CustomObjectFieldSection or pass section when adding it to ` +
           `section "${fallbackSectionKey}".`,
       );
     }
@@ -1241,17 +1652,63 @@ export class CustomObjectPageLayout {
     }
   }
 
-  private requireOneFieldContainer(tabKey: string | undefined, sectionKey: string): MutableFieldContainer {
+  private assertFieldSectionBelongsToLayout(section: CustomObjectFieldSection): void {
+    if (section.getModelApiName() !== this._customObjectApiName) {
+      throw new Error(
+        `CustomObjectPageLayout field section "${section.getSectionId()}" belongs to ` +
+          `"${section.getModelApiName()}", but the layout belongs to "${this._customObjectApiName}".`,
+      );
+    }
+  }
+
+  private requireOneFieldContainer(
+    tabKey: string | undefined,
+    sectionKey: string | undefined,
+    fallbackFieldSection?: CustomObjectFieldSection,
+  ): 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 (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] as MutableFieldContainer & {
+            section: SerializedFieldsSection;
+          };
+          attachFieldSectionId(container.section, fallbackFieldSection.getSectionId());
+          container.sectionKey = fallbackFieldSection.getSectionId();
+          container.label = `${container.tabKey}.${container.sectionKey}`;
+          return container;
+        }
+      }
+      const scope =
+        sectionKey == null ? 'a field section' : (
+          `section "${tabKey != null ? `${tabKey}.` : ''}${sectionKey}"`
+        );
+      throw new Error(`CustomObjectPageLayout could not find ${scope}.`);
     }
     if (containers.length > 1) {
+      if (sectionKey == null) {
+        throw new Error(
+          `CustomObjectPageLayout matched multiple sections: ` +
+            `${containers.map((container) => container.label).join(', ')}. Pass section to choose one.`,
+        );
+      }
       throw new Error(
         `CustomObjectPageLayout section "${sectionKey}" matched multiple sections: ` +
           `${containers.map((container) => container.label).join(', ')}. Pass tabKey to choose one.`,
@@ -1271,34 +1728,40 @@ export class CustomObjectPageLayout {
       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;
+        for (const [index, section] of tab.sections.entries()) {
+          const sectionKey = layoutSectionKey(section);
+          if (filter.sectionKey != null && !layoutSectionMatches(section, filter.sectionKey)) continue;
+          const label = sectionKey == null ? `${tab.key}.sections[${index}]` : `${tab.key}.${sectionKey}`;
           containers.push({
             tabKey: tab.key,
-            sectionKey: section.key,
+            sectionKey,
+            section,
             fields: ensureArrayProperty<MutableSectionField>(
               section as unknown as Record<string, any>,
               'fields',
-              `newTabs.${tab.key}.sections.${section.key}.fields`,
+              `newTabs.${label}.fields`,
             ),
-            label: `${tab.key}.${section.key}`,
+            label,
           });
         }
       }
 
       for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
         if (filter.tabKey != null && tabKey !== filter.tabKey) continue;
-        for (const section of tabEdit.newSections ?? []) {
-          if (filter.sectionKey != null && section.key !== filter.sectionKey) continue;
+        for (const [index, section] of (tabEdit.newSections ?? []).entries()) {
+          const sectionKey = layoutSectionKey(section);
+          if (filter.sectionKey != null && !layoutSectionMatches(section, filter.sectionKey)) continue;
+          const label = sectionKey == null ? `${tabKey}.newSections[${index}]` : `${tabKey}.${sectionKey}`;
           containers.push({
             tabKey,
-            sectionKey: section.key,
+            sectionKey,
+            section,
             fields: ensureArrayProperty<MutableSectionField>(
               section as unknown as Record<string, any>,
               'fields',
-              `systemTabEdits.${tabKey}.newSections.${section.key}.fields`,
+              `systemTabEdits.${label}.fields`,
             ),
-            label: `${tabKey}.${section.key}`,
+            label,
           });
         }
       }
@@ -1329,11 +1792,14 @@ export class CustomObjectPageLayout {
 
   private ensureSystemSectionFieldContainer(
     tabKey: string | undefined,
-    sectionKey: string,
+    sectionKey: string | undefined,
   ): MutableFieldContainer {
     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.`);
@@ -1396,12 +1862,12 @@ export class CustomObjectPageLayout {
 
   private assertSectionKeyAvailable(
     sections: SerializedFieldsSection[],
-    sectionKey: string,
+    sectionKey: string | undefined,
     tabKey: string,
     allowDuplicate: boolean | undefined,
   ): void {
     if (allowDuplicate === true) return;
-    if (sections.some((section) => section.key === sectionKey)) {
+    if (sectionKey != null && sections.some((section) => layoutSectionMatches(section, sectionKey))) {
       throw new Error(`CustomObjectPageLayout tab "${tabKey}" already contains section "${sectionKey}".`);
     }
   }
@@ -1476,12 +1942,13 @@ export class CustomObjectPageLayout {
    * tabs or sections. Always uses `apiName: 'default'`.
    *
    * @param customObject - The custom object to create the layout for.
-   * @param props - Optional. Pass `fields` to populate the General section.
+   * @param props - Optional. Pass `section` and `fields` to populate the General section.
    * @returns A new `CustomObjectPageLayout` registered with the manifest.
    *
    * @example
    * ```ts
    * CustomObjectPageLayout.basic(memberObj, {
+   *   section: profileSection,
    *   fields: [memberFirstName, memberEmail, memberStatusField],
    * });
    * ```
@@ -1489,16 +1956,40 @@ export class CustomObjectPageLayout {
   static basic(
     customObject: CustomObject,
     props: {
+      section?: CustomObjectFieldSection;
       fields?: Field[];
     } = {},
   ): CustomObjectPageLayout {
     const coApiName = customObject.getApiName();
     const coName = customObject.getName();
-    const sectionPrefix = coApiName.replace(/__c$/, '').replace(/[^a-zA-Z0-9]+/g, '_');
-    const generalSection = new CustomObjectFieldSection(customObject, {
-      sectionId: `sec_${sectionPrefix}_general`,
-      name: 'General',
-    });
+    const fields = props.fields ?? [];
+    const generalSection =
+      props.section ??
+      (() => {
+        const alreadySectionedField = fields.find((field) => field.getSectionId() != null);
+        if (alreadySectionedField != null) {
+          throw new Error(
+            `CustomObjectPageLayout.basic field "${alreadySectionedField.getApiName()}" already belongs to ` +
+              `field section "${alreadySectionedField.getSectionId()}". Pass that CustomObjectFieldSection ` +
+              'as section so basic() does not reassign the field.',
+          );
+        }
+        const sectionPrefix = coApiName.replace(/__c$/, '').replace(/[^a-zA-Z0-9]+/g, '_');
+        return new CustomObjectFieldSection(customObject, {
+          sectionId: `sec_${sectionPrefix}_general`,
+          name: 'General',
+        });
+      })();
+    assertSectionBelongsTo(customObject, generalSection);
+    for (const field of fields) {
+      const fieldSectionId = field.getSectionId();
+      if (fieldSectionId != null && fieldSectionId !== generalSection.getSectionId()) {
+        throw new Error(
+          `CustomObjectPageLayout.basic field "${field.getApiName()}" belongs to field section ` +
+            `"${fieldSectionId}", but basic() was given section "${generalSection.getSectionId()}".`,
+        );
+      }
+    }
     return new CustomObjectPageLayout(customObject, {
       apiName: 'default',
       name: `${coName} Layout`,
@@ -1510,11 +2001,10 @@ export class CustomObjectPageLayout {
             type: 'tab_with_sections',
             sections: [
               {
-                key: 'general',
                 name: 'General',
                 type: 'fields_section',
                 section: generalSection,
-                fields: props.fields ?? [],
+                fields,
               },
             ],
           },