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

package/src/lib/manifest/app.ts

@@ -58,9 +58,9 @@ export interface AppProps {
   /**
    * SDUI pages shown as tabs in the app. Tab order matches the array order.
    *
-   * Optional. @default `[]`
+   * Required. Must include at least one page.
    */
-  pages?: AppPage[];
+  pages: AppPage[];
 }
 
 function resolvePage(entry: AppPage): Record<string, any> {
@@ -77,6 +77,20 @@ function resolvePage(entry: AppPage): Record<string, any> {
   };
 }
 
+function resolvePages(pages: AppPage[] | undefined): Record<string, any>[] {
+  if (pages == null || pages.length === 0) {
+    throw new Error('App pages must include at least one page.');
+  }
+  return pages.map(resolvePage);
+}
+
+function clonePages(value: unknown): Record<string, any>[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error('App pages must include at least one page.');
+  }
+  return cloneJson(value) as Record<string, any>[];
+}
+
 function cloneJson<T>(value: T): T {
   if (value == null) return value;
   return JSON.parse(JSON.stringify(value)) as T;
@@ -130,7 +144,7 @@ export class App {
     this._description = props.description;
     this._appType = props.appType;
     this._icon = props.icon;
-    this._pages = (props.pages ?? []).map(resolvePage);
+    this._pages = resolvePages(props.pages);
     scope._register(this);
   }
 
@@ -150,7 +164,7 @@ export class App {
       _description: component['description'],
       _appType: component['app_type'],
       _icon: App.appIconFromExistingComponent(component['icon']),
-      _pages: cloneJson(component['pages'] ?? []),
+      _pages: clonePages(component['pages']),
     });
     scope._register(app);
     return app;
@@ -193,7 +207,7 @@ export class App {
       component['icon'] = { s3_bucket: this._icon.s3Bucket, s3_key: this._icon.s3Key };
     }
     if (this._appType != null) component['app_type'] = this._appType;
-    if (this._pages.length > 0) component['pages'] = this._pages.map((p) => ({ ...p }));
+    component['pages'] = this._pages.map((p) => ({ ...p }));
     return component;
   }
 }

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[];
@@ -351,7 +351,7 @@ export interface RemoveSystemPageLayoutSectionOptions {
 
 /** 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;
@@ -754,7 +754,49 @@ function normalizeHeaderEdits(headerEdits: HeaderEdits): HeaderEdits {
     );
   }
 
-  return headerEdits;
+  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;
@@ -784,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;
@@ -1231,7 +1282,9 @@ export class CustomObjectPageLayout {
         options.tabKey,
         options.allowDuplicate,
       );
+      const sectionsOrder = this.ensureSystemSectionsOrder(tabEdit);
       insertAt(sections, normalized, options.position);
+      insertUniqueAt(sectionsOrder, layoutSectionKey(normalized), options.position);
       return this;
     }
 
@@ -1275,6 +1328,7 @@ export class CustomObjectPageLayout {
       }
       const sectionEdit = this.ensureSystemSectionEdit(options.tabKey, sectionOrKey);
       sectionEdit.deleted = true;
+      removeKeyFromOrder(this._tabEdits.systemTabEdits?.[options.tabKey]?.sectionsOrder, sectionOrKey);
       this.removeSectionVisibility(sectionOrKey);
       return this;
     }
@@ -1338,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;
   }
 
@@ -1381,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;
   }
 
@@ -1394,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}"`,
@@ -1408,40 +1460,94 @@ 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,

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.2.0-alpha.45'; // x-release-please-version
+export const VERSION = '0.2.0-alpha.46'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.45";
+export declare const VERSION = "0.2.0-alpha.46";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.45";
+export declare const VERSION = "0.2.0-alpha.46";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.2.0-alpha.45'; // x-release-please-version
+exports.VERSION = '0.2.0-alpha.46'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.2.0-alpha.45'; // x-release-please-version
+export const VERSION = '0.2.0-alpha.46'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map