@rippling/rippling-sdk 0.2.0-alpha.36 → 0.2.0-alpha.38

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

@@ -1,4 +1,5 @@
 import { generateId } from './_helpers';
+import { CustomObjectFieldSection } from './custom-object-field-section';
 import type { CustomObject } from './custom-object';
 import type { Field } from './field';
 
@@ -65,10 +66,8 @@ export interface HeaderEdits {
 // tab_edits — TabEditsDTO + section/tab DTOs
 // ---------------------------------------------------------------------------
 
-/** One field entry inside a `fields_section`. */
-export interface SectionField {
-  /** RQL name of the field to display. Required. */
-  fieldRqlName: string;
+/** Options for one field entry inside a `fields_section`. */
+export interface SectionFieldOptions {
   /** Hide this field from view. Optional. */
   hidden?: boolean;
   /** Allow inline editing of this field. Optional. */
@@ -77,15 +76,28 @@ export interface SectionField {
   movementOption?: 'tab' | 'free';
 }
 
+/** A typed field entry inside a `fields_section`. */
+export interface SectionFieldRef extends SectionFieldOptions {
+  /** Field to display. Required. */
+  field: Field;
+}
+
+/** One field entry inside a `fields_section`. */
+export type SectionField = Field | SectionFieldRef;
+
 /** A standard field-grid section inside a tab. */
 export interface FieldsSection {
   type: 'fields_section';
-  /** Stable key for this section. Required. */
-  key: string;
-  /** Display name of the section. Required. */
-  name: string;
+  /** 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. */
   fields: SectionField[];
+  /** Column layout for the fields. Optional. @default `'responsive'` (backend default). */
+  layout?: SectionFieldsLayout;
 }
 
 /**
@@ -255,6 +267,197 @@ export interface CustomObjectPageLayoutProps {
   blueprintKey?: string;
 }
 
+interface SerializedSectionField extends SectionFieldOptions {
+  fieldRqlName: string;
+}
+
+interface SerializedFieldsSection {
+  type: 'fields_section';
+  key: string;
+  name: string;
+  fields: SerializedSectionField[];
+  layout?: SectionFieldsLayout;
+}
+
+interface SerializedTabWithSections {
+  type: 'tab_with_sections';
+  key: string;
+  name: string;
+  sections: SerializedFieldsSection[];
+}
+
+type SerializedPageLayoutTab = SerializedTabWithSections | CustomTab;
+
+interface SerializedSystemSectionEdit extends Omit<SystemSectionEdit, 'newFields'> {
+  newFields?: SerializedSectionField[];
+}
+
+interface SerializedSystemTabEdit extends Omit<SystemTabEdit, 'newSections' | 'systemSectionEdits'> {
+  newSections?: SerializedFieldsSection[];
+  systemSectionEdits?: Record<string, SerializedSystemSectionEdit>;
+}
+
+interface SerializedTabEdits extends Omit<TabEdits, 'newTabs' | 'systemTabEdits'> {
+  newTabs?: SerializedPageLayoutTab[];
+  systemTabEdits?: Record<string, SerializedSystemTabEdit>;
+}
+
+function isField(value: unknown): value is Field {
+  const candidate = value as {
+    getApiName?: unknown;
+    getCustomObjectApiName?: unknown;
+    getSectionId?: unknown;
+    _assignSection?: unknown;
+  } | null;
+  return (
+    candidate != null &&
+    typeof candidate.getApiName === 'function' &&
+    typeof candidate.getCustomObjectApiName === 'function' &&
+    typeof candidate.getSectionId === 'function' &&
+    typeof candidate._assignSection === 'function'
+  );
+}
+
+function isFieldRef(value: SectionField): value is SectionFieldRef {
+  const candidate = value as { field?: unknown } | null;
+  return candidate != null && typeof candidate === 'object' && isField(candidate.field);
+}
+
+function assertSameObject(customObject: CustomObject, field: Field, sectionKey: string): void {
+  if (field.getCustomObjectApiName() !== customObject.getApiName()) {
+    throw new Error(
+      `CustomObjectPageLayout fields_section "${sectionKey}" references field "${field.getApiName()}" ` +
+        `from "${field.getCustomObjectApiName()}", but the layout belongs to "${customObject.getApiName()}".`,
+    );
+  }
+}
+
+function assertSectionBelongsTo(customObject: CustomObject, section: CustomObjectFieldSection): void {
+  if (section.getModelApiName() !== customObject.getApiName()) {
+    throw new Error(
+      `CustomObjectPageLayout section "${section.getSectionId()}" belongs to "${section.getModelApiName()}", ` +
+        `but the layout belongs to "${customObject.getApiName()}".`,
+    );
+  }
+}
+
+function toSerializedSectionField(
+  fieldRqlName: string,
+  options: SectionFieldOptions = {},
+): SerializedSectionField {
+  const normalized: SerializedSectionField = { fieldRqlName };
+  if (options.hidden != null) normalized.hidden = options.hidden;
+  if (options.editable != null) normalized.editable = options.editable;
+  if (options.movementOption != null) normalized.movementOption = options.movementOption;
+  return normalized;
+}
+
+function normalizeSectionField(
+  customObject: CustomObject,
+  section: CustomObjectFieldSection | string,
+  sectionKey: string,
+  entry: SectionField,
+): SerializedSectionField {
+  if (isField(entry)) {
+    assertSameObject(customObject, entry, sectionKey);
+    entry._assignSection(section);
+    return toSerializedSectionField(entry.getApiName());
+  }
+
+  if (isFieldRef(entry)) {
+    assertSameObject(customObject, entry.field, sectionKey);
+    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 }.',
+  );
+}
+
+function normalizeFieldsSection(
+  customObject: CustomObject,
+  input: PageLayoutSection,
+): SerializedFieldsSection {
+  assertSectionBelongsTo(customObject, input.section);
+  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) => normalizeSectionField(customObject, input.section, key, field)),
+  };
+  if (input.layout != null) normalized.layout = input.layout;
+  return normalized;
+}
+
+function normalizeTab(customObject: CustomObject, tab: PageLayoutTab): SerializedPageLayoutTab {
+  if (tab.type === 'custom_tab') return tab;
+  return {
+    ...tab,
+    sections: tab.sections.map((section) => normalizeFieldsSection(customObject, section)),
+  };
+}
+
+function normalizeSystemSectionEdit(
+  customObject: CustomObject,
+  tabKey: string,
+  sectionKey: string,
+  edit: SystemSectionEdit,
+): SerializedSystemSectionEdit {
+  const { newFields: _newFields, ...rest } = edit;
+  const normalized: SerializedSystemSectionEdit = { ...rest };
+  if (edit.newFields != null) {
+    normalized.newFields = edit.newFields.map((field) =>
+      normalizeSectionField(customObject, sectionKey, `${tabKey}.${sectionKey}`, field),
+    );
+  }
+  return normalized;
+}
+
+function normalizeSystemTabEdit(
+  customObject: CustomObject,
+  tabKey: string,
+  edit: SystemTabEdit,
+): SerializedSystemTabEdit {
+  const { newSections: _newSections, systemSectionEdits: _systemSectionEdits, ...rest } = edit;
+  const normalized: SerializedSystemTabEdit = { ...rest };
+  if (edit.newSections != null) {
+    normalized.newSections = edit.newSections.map((section) => normalizeFieldsSection(customObject, section));
+  }
+  if (edit.systemSectionEdits != null) {
+    const systemSectionEdits: Record<string, SerializedSystemSectionEdit> = {};
+    for (const [sectionKey, sectionEdit] of Object.entries(edit.systemSectionEdits)) {
+      systemSectionEdits[sectionKey] = normalizeSystemSectionEdit(
+        customObject,
+        tabKey,
+        sectionKey,
+        sectionEdit,
+      );
+    }
+    normalized.systemSectionEdits = systemSectionEdits;
+  }
+  return normalized;
+}
+
+function normalizeTabEdits(customObject: CustomObject, tabEdits: TabEdits): SerializedTabEdits {
+  const { newTabs: _newTabs, systemTabEdits: _systemTabEdits, ...rest } = tabEdits;
+  const normalized: SerializedTabEdits = { ...rest };
+  if (tabEdits.newTabs != null) {
+    normalized.newTabs = tabEdits.newTabs.map((tab) => normalizeTab(customObject, tab));
+  }
+  if (tabEdits.systemTabEdits != null) {
+    const systemTabEdits: Record<string, SerializedSystemTabEdit> = {};
+    for (const [tabKey, tabEdit] of Object.entries(tabEdits.systemTabEdits)) {
+      systemTabEdits[tabKey] = normalizeSystemTabEdit(customObject, tabKey, tabEdit);
+    }
+    normalized.systemTabEdits = systemTabEdits;
+  }
+  return normalized;
+}
+
 // ---------------------------------------------------------------------------
 // Class
 // ---------------------------------------------------------------------------
@@ -283,11 +486,11 @@ export interface CustomObjectPageLayoutProps {
  *     newTabs: [{
  *       key: 'member', name: 'Member', type: 'tab_with_sections',
  *       sections: [{
- *         key: 'profile', name: 'Profile', type: 'fields_section',
- *         fields: [
- *           { fieldRqlName: memberFirstName.getApiName() },
- *           { fieldRqlName: memberEmail.getApiName() },
- *         ],
+ *         key: 'profile',
+ *         name: 'Profile',
+ *         type: 'fields_section',
+ *         section: profileSection,
+ *         fields: [memberFirstName, memberEmail],
  *       }],
  *     }],
  *     systemTabEdits: {},
@@ -304,7 +507,7 @@ export class CustomObjectPageLayout {
   private readonly _apiName: string;
   private readonly _customObjectApiName: string;
   private readonly _name: string;
-  private readonly _tabEdits: TabEdits;
+  private readonly _tabEdits: SerializedTabEdits;
   private readonly _headerEdits: HeaderEdits;
   private readonly _visibilityConditions: VisibilityConditions;
   private readonly _blueprintKey: string | undefined;
@@ -321,7 +524,7 @@ export class CustomObjectPageLayout {
     this._apiName = props.apiName;
     this._customObjectApiName = customObject.getApiName();
     this._name = props.name;
-    this._tabEdits = props.tabEdits ?? {};
+    this._tabEdits = normalizeTabEdits(customObject, props.tabEdits ?? {});
     this._headerEdits = props.headerEdits ?? {};
     this._visibilityConditions = props.visibilityConditions ?? {};
     this._blueprintKey = props.blueprintKey;
@@ -396,6 +599,11 @@ export class CustomObjectPageLayout {
   ): 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',
+    });
     return new CustomObjectPageLayout(customObject, {
       apiName: 'default',
       name: `${coName} Layout`,
@@ -410,9 +618,8 @@ export class CustomObjectPageLayout {
                 key: 'general',
                 name: 'General',
                 type: 'fields_section',
-                fields: (props.fields ?? []).map((f: Field) => ({
-                  fieldRqlName: f.getApiName(),
-                })),
+                section: generalSection,
+                fields: props.fields ?? [],
               },
             ],
           },

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

@@ -215,6 +215,21 @@ export interface CustomObjectProps {
    * Overrides for the auto-number name field — controls the format string and starting number.
    * Leave `null` to use the default name field behavior.
    *
+   * Example:
+   * ```ts
+   * nameFieldDetails: {
+   *   is_autonumber_field: true,
+   *   starting_number: 1,
+   *   autonumber_format: 'EXP-{0000}',
+   * }
+   * ```
+   *
+   * @remarks
+   * The backend auto-appends `{0000}` to `autonumber_format` if the format string
+   * doesn't already contain a sequence token — so `'EXP-'` becomes `'EXP-{0000}'`
+   * on the wire. Include the token explicitly when you want a different width
+   * (e.g. `'EXP-{00000}'`).
+   *
    * Optional. @default null
    */
   nameFieldDetails?: Record<string, any> | null;
@@ -241,7 +256,7 @@ export interface CustomObjectProps {
  *   name: 'Gym Membership Management',
  * });
  *
- * const gymCategory = new Category(manifest, { apiName: 'gym__c', name: 'Gym' });
+ * const gymCategory = new Category(manifest, { apiName: 'gym__c', name: 'Gym', description: 'Gym domain' });
  *
  * const memberObj = new CustomObject(manifest, {
  *   apiName: 'gym_member__c',
@@ -266,6 +281,20 @@ export interface CustomObjectProps {
  * with `DEPENDENCY_ERROR: Page layout config for CO (api_name=...) not found in package
  * configs. CO requires at least one page layout in the package.`
  * Use {@link CustomObjectPageLayout.basic} for a minimal single-tab layout.
+ *
+ * **Consider defining at least one {@link ListViewDef}.** Without a list view,
+ * the records page has nothing to display by default — users land on an empty grid.
+ * Consider shipping a "default" view with the columns most users want to see
+ * (typically `name`, the status / category field, owner, and `created_at`), sorted
+ * however the records are most commonly browsed.
+ *
+ * **Consider system fields before authoring new ones.** Every CO ships with
+ * `owner_role`, `created_by`, and `last_modified_by` (all `Employee` references),
+ * plus `name`, `created_at`, `updated_at`, `external_id`, and `id`. For any
+ * "the employee responsible for this record" semantics, consider using
+ * `owner_role` rather than adding a new {@link LookupField} targeting `'role'`.
+ * `owner_role` drives Rippling's record-level permissions, so a parallel field
+ * can fragment ownership and complicate the permission story.
  */
 export class CustomObject implements ManifestScope {
   private readonly _scope: ManifestScope;

package/src/lib/manifest/field.ts

@@ -130,7 +130,7 @@ export class Field {
   private readonly _rqlFormula: string | null;
   private readonly _formulaAttrMetas: Record<string, any> | null;
   private readonly _derivedFieldFormula: string | null;
-  private readonly _section: string | null;
+  private _section: string | null;
   private readonly _summarySpec: SummarySpec | null;
   private readonly _derivedAggregatedFieldStatic: Record<string, any> | null;
 
@@ -202,6 +202,14 @@ export class Field {
   isSummary(): boolean {
     return this._summarySpec != null;
   }
+  /** Returns the field section id assigned to this field, if any. */
+  getSectionId(): string | null {
+    return this._section;
+  }
+  /** @internal Assigns this field to a field section during page-layout normalization. */
+  _assignSection(section: CustomObjectFieldSection | string): void {
+    this._section = typeof section === 'string' ? section : section.getSectionId();
+  }
 
   // ── Serialization ──────────────────────────────────────────────────────
 
@@ -438,7 +446,12 @@ export interface SelectFieldProps extends CommonFieldProps {
   /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Dropdown single-select field. */
+/**
+ * Multi-select dropdown field. Renders as a dropdown that allows multiple
+ * options to be selected at once.
+ *
+ * Use {@link RadioField} instead when only one option should be selectable.
+ */
 export class SelectField extends Field {
   constructor(customObject: CustomObject, props: SelectFieldProps) {
     super(customObject, { ...props, fieldType: 'SELECT' });
@@ -456,7 +469,11 @@ export interface RadioFieldProps extends CommonFieldProps {
   /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Radio button group field. */
+/**
+ * Single-select radio button group field. Exactly one option can be selected.
+ *
+ * Use {@link SelectField} instead when multiple options should be selectable.
+ */
 export class RadioField extends Field {
   constructor(customObject: CustomObject, props: RadioFieldProps) {
     super(customObject, { ...props, fieldType: 'RADIO' });
@@ -530,6 +547,15 @@ export interface LookupFieldProps extends CommonFieldProps {
  *
  * Use {@link ParentChildField} instead when the relationship should create a
  * parent-child hierarchy with rollup support.
+ *
+ * @remarks
+ * **For "the employee responsible for this record" semantics, consider the built-in
+ * `owner_role` standard field instead of a new `LookupField` to `'role'`.** Every
+ * `CustomObject` ships with `owner_role` (an Employee reference) plus `created_by`
+ * and `last_modified_by`. `owner_role` drives Rippling's record-level permissions,
+ * so a parallel custom employee field can fragment ownership and complicate the
+ * permission story. Consider a new `LookupField` to `'role'` when you need a
+ * *second*, non-owner employee reference (e.g. an "approver", a "manager on record").
  */
 export class LookupField extends Field {
   constructor(customObject: CustomObject, props: LookupFieldProps) {

package/src/lib/manifest/index.ts

@@ -35,6 +35,8 @@ export {
   type PageLayoutSection,
   type PageLayoutTab,
   type SectionField,
+  type SectionFieldOptions,
+  type SectionFieldRef,
   type SectionFieldsLayout,
   type SystemHeaderFieldEdit,
   type SystemSectionEdit,

package/src/lib/manifest/manifest-builder.ts

@@ -63,7 +63,7 @@ export interface ManifestBuilderProps {
  *   description: 'Members, trainers, schedules, and check-in',
  * });
  *
- * const category = new Category(manifest, { apiName: 'gym__c', name: 'Gym' });
+ * const category = new Category(manifest, { apiName: 'gym__c', name: 'Gym', description: 'Gym domain' });
  * const memberObj = new CustomObject(manifest, { apiName: 'gym_member__c', name: 'Member', category });
  * // ... define fields, rules, list views, etc. ...
  *

package/src/lib/manifest/manifest-function.ts

@@ -68,8 +68,14 @@ export interface ManifestFunctionProps {
  * Defines a serverless function and registers it with the manifest.
  *
  * A `ManifestFunction` packages TypeScript handler code that runs on Rippling's
- * serverless infrastructure. Functions are the backing implementation for
- * {@link SduiPage} surfaces. The handler must export `onRipplingEvent`.
+ * serverless infrastructure. The handler must export `onRipplingEvent`.
+ *
+ * Functions have two primary uses:
+ * 1. **Authoring SDUI for Custom Apps** — the function returns an SDUI spec
+ *    (built with `@rippling/sdui-builder`) that renders as a page tab. Wrap the
+ *    function in an {@link SduiPage} and reference it from an {@link App}.
+ * 2. **Workflow / event handlers** — functions invoked from rules, automations,
+ *    or callbacks that do not render UI.
  *
  * This class is named `ManifestFunction` to avoid collision with the JavaScript
  * built-in `Function`. It is also re-exported as `Function` from the barrel for

package/src/lib/sdui/actions.ts

@@ -12,15 +12,19 @@ export function set(ref: unknown, value: unknown): ActionBinding {
 }
 
 export function push(ref: unknown, value: unknown, opts?: { clear?: unknown }): ActionBinding {
-  const params: Record<string, unknown> = { statePath: extractPath(ref), value };
-  if (opts?.clear) {
-    params['clearStatePath'] = extractPath(opts.clear);
-  }
+  const params: Record<string, unknown> = {
+    statePath: extractPath(ref),
+    value,
+    ...(opts?.clear ? { clearStatePath: extractPath(opts.clear) } : {}),
+  };
   return { action: 'pushState', params };
 }
 
 export function remove(ref: unknown, index: unknown): ActionBinding {
-  return { action: 'removeState', params: { statePath: extractPath(ref), index } };
+  return {
+    action: 'removeState',
+    params: { statePath: extractPath(ref), index },
+  };
 }
 
 export function callFunction(
@@ -29,11 +33,20 @@ export function callFunction(
   opts?: Record<string, unknown>,
 ): ActionBinding {
   const { responsePath, onSuccess, onError, ...rest } = opts || {};
-  const params: Record<string, unknown> = { functionId, action, ...rest };
-  if (responsePath !== undefined) params['responsePath'] = responsePath;
-  const binding: ActionBinding = { action: 'triggerFunction', params };
-  if (onSuccess) binding.onSuccess = onSuccess as ActionBinding;
-  if (onError) binding.onError = onError as ActionBinding;
+  // Spread rest FIRST so explicit functionId/action always win if opts
+  // happens to carry colliding keys.
+  const params: Record<string, unknown> = {
+    ...rest,
+    functionId,
+    action,
+    ...(responsePath !== undefined ? { responsePath } : {}),
+  };
+  const binding: ActionBinding = {
+    action: 'triggerFunction',
+    params,
+    ...(onSuccess ? { onSuccess: onSuccess as ActionBinding } : {}),
+    ...(onError ? { onError: onError as ActionBinding } : {}),
+  };
   return binding;
 }