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

package/src/lib/manifest/category.ts

@@ -19,9 +19,11 @@ export interface CategoryProps {
   /**
    * Human-readable description of what this category groups.
    *
-   * Optional. @default null
+   * Required. The backend (`CustomCategoryConfig.description: str`) requires the
+   * key to be present and rejects `null`. Pass an empty string only if you truly
+   * have no meaningful copy.
    */
-  description?: string | null;
+  description: string;
 }
 
 /**
@@ -57,7 +59,7 @@ export interface CategoryProps {
 export class Category {
   private readonly _apiName: string;
   private readonly _name: string;
-  private readonly _description: string | null;
+  private readonly _description: string;
 
   /**
    * @param scope - The manifest to register this category with.
@@ -66,7 +68,7 @@ export class Category {
   constructor(scope: ManifestScope, props: CategoryProps) {
     this._apiName = props.apiName;
     this._name = props.name;
-    this._description = props.description ?? null;
+    this._description = props.description;
     scope._register(this);
   }
 
@@ -94,7 +96,7 @@ export class Category {
       type: 'CUSTOM_CATEGORY',
       api_name: this._apiName,
       name: this._name,
-      description: this._description ?? null,
+      description: this._description,
     };
   }
 }

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

@@ -96,6 +96,8 @@ export interface FieldsSection {
   name?: string;
   /** Fields to display in this section. Required. */
   fields: SectionField[];
+  /** Column layout for the fields. Optional. @default `'responsive'` (backend default). */
+  layout?: SectionFieldsLayout;
 }
 
 /**
@@ -274,6 +276,7 @@ interface SerializedFieldsSection {
   key: string;
   name: string;
   fields: SerializedSectionField[];
+  layout?: SectionFieldsLayout;
 }
 
 interface SerializedTabWithSections {
@@ -380,12 +383,14 @@ function normalizeFieldsSection(
   assertSectionBelongsTo(customObject, input.section);
   const key = input.key ?? input.section.getSectionId();
   const name = input.name ?? input.section.getName();
-  return {
+  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 {

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

@@ -446,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' });
@@ -464,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' });
@@ -538,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/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;
 }
 

package/src/lib/sdui/component.ts

@@ -1,25 +1,38 @@
 /**
  * component() — creates a stateful component boundary.
  *
- * Provides ctx.useState (scoped local state) and ctx.useEffect (onMount actions).
- * The returned element is automatically wrapped with _LocalStateProvider in the rendered spec.
+ * Provides ctx.localState (scoped local state slot) and ctx.onMount (an
+ * action that fires once when the component mounts on the client). The
+ * runtime handles state setup and mount firing; consumers don't need to
+ * know how the wrapping is implemented.
+ *
+ * NOTE: these are NOT React hooks. The factory runs ONCE at spec-build
+ * time, producing a JSON description of the UI. `localState` returns a
+ * path-builder proxy (not a [value, setter] tuple); `onMount` registers
+ * a JSON action that fires on first client render (not an effect that
+ * re-runs).
  *
  * Usage:
  *   function MembersGrid(props) {
  *     return component((ctx) => {
- *       const local = ctx.useState({ data: [], loading: true })
- *       ctx.useEffect(fetchAction)
- *       return { element: DataGrid({ ... }), refresh: fetchAction }
+ *       const local = ctx.localState({ data: [], loading: true })
+ *       ctx.onMount(fetchAction)
+ *       return { element: DataGrid({ ... }) }
  *     })
  *   }
  */
 
-import type { SpecNode } from './components';
 import type { ActionBinding } from './actions';
+import type { SpecNode } from './components';
 
 let _idCounter = 0;
+// Counter-only IDs (no Date.now()) so the same factory body produces the
+// same paths across runs. The counter is monotonic per process; calling
+// `_resetIdCounter()` (tests only) brings it back to 0 so snapshot tests
+// stay stable.
 function generateId(): string {
-  return `auto_${(++_idCounter).toString(36)}_${Date.now().toString(36)}`;
+  _idCounter += 1;
+  return `auto_${_idCounter.toString(36)}`;
 }
 
 // Reset counter (for testing)
@@ -37,15 +50,25 @@ export interface StateScope {
 }
 
 interface ComponentContext {
-  /** Declare scoped local state. Returns a proxy for reading/binding. */
-  useState<T extends Record<string, unknown>>(initial: T): StateScope;
-  /** Register an action to fire on mount (when element becomes visible). */
-  useEffect(action: ActionBinding | ActionBinding[]): void;
+  /**
+   * Declare a scoped local state slot. Returns a path-builder proxy whose
+   * property accesses produce `{ $state: '/path' }` references for reading
+   * and `.$bind` for two-way binding. Not a React hook — runs once when
+   * the factory is invoked, never returns `[value, setter]`.
+   */
+  localState<T extends Record<string, unknown>>(initial: T): StateScope;
+
+  /**
+   * Register a JSON action to fire once when the component mounts on the
+   * client. Not a React effect — does not re-run, has no dependency
+   * tracking. Pass an `ActionBinding` (e.g. from `set(...)`, `callFunction(...)`)
+   * or an array of them.
+   */
+  onMount(action: ActionBinding | ActionBinding[]): void;
 }
 
 interface ComponentResult {
   element: SpecNode;
-  [key: string]: any; // exposed actions like refresh, reset, etc.
 }
 
 function createScopeProxy(basePath: string): StateScope {
@@ -65,58 +88,75 @@ function createScopeProxy(basePath: string): StateScope {
 }
 
 export function component(factory: (ctx: ComponentContext) => ComponentResult): ComponentResult {
-  let localState: { path: string; initial: unknown } | null = null;
-  let mountAction: ActionBinding | ActionBinding[] | null = null;
+  const states: { path: string; initial: unknown }[] = [];
+  const mountActions: (ActionBinding | ActionBinding[])[] = [];
 
   const ctx: ComponentContext = {
-    useState<T extends Record<string, unknown>>(initial: T): StateScope {
+    localState<T extends Record<string, unknown>>(initial: T): StateScope {
       const path = `/${generateId()}`;
-      localState = { path, initial };
+      states.push({ path, initial });
       return createScopeProxy(path);
     },
-    useEffect(action: ActionBinding | ActionBinding[]) {
-      mountAction = action;
+    onMount(action: ActionBinding | ActionBinding[]) {
+      mountActions.push(action);
     },
   };
 
   const result = factory(ctx);
 
-  // Capture state after factory execution (TS can't track closure mutations)
-  const capturedState = localState as { path: string; initial: unknown } | null;
-  const capturedMount = mountAction;
-
-  // If no local state and no effects, return as-is
-  if (!capturedState && !capturedMount) {
+  // No state, no effects → return as-is.
+  if (states.length === 0 && mountActions.length === 0) {
     return result;
   }
 
-  // Wrap element with _LocalStateProvider
-  const providerProps: Record<string, unknown> = {};
-  if (capturedState) {
-    providerProps['statePath'] = capturedState.path;
-    providerProps['initialValue'] = capturedState.initial;
-  }
-  if (capturedMount) {
-    providerProps['onMountAction'] = capturedMount;
+  // Collapse zero/one/many mount actions for the single onMountAction slot
+  // on the innermost wrapper.
+  let combinedMount: ActionBinding | ActionBinding[] | undefined;
+  if (mountActions.length === 1) {
+    combinedMount = mountActions[0];
+  } else if (mountActions.length > 1) {
+    combinedMount = mountActions.flatMap((a) => (Array.isArray(a) ? a : [a]));
   }
 
-  const wrapper: SpecNode = {
-    type: '_LocalStateProvider',
-    props: providerProps,
-    children: [result.element],
-  };
+  let wrapped: SpecNode = result.element;
 
-  // Attach the local state to the spec's state tree
-  // The render() function will collect this via a special marker
-  if (capturedState) {
-    (wrapper as any)._localStateRegistration = {
-      path: capturedState.path,
-      initial: capturedState.initial,
+  if (states.length === 0) {
+    // Mount-only: a single state-provider wrapper carries onMountAction.
+    wrapped = {
+      type: '_LocalStateProvider',
+      props: combinedMount ? { onMountAction: combinedMount } : {},
+      children: [wrapped],
     };
+  } else {
+    // One state-provider wrapper per localState() call, nested
+    // innermost-first. Mount actions attach to the innermost wrapper so
+    // every state slot is initialized before any action fires.
+    for (let i = states.length - 1; i >= 0; i--) {
+      const state = states[i];
+      if (state) {
+        const isInnermost = i === states.length - 1;
+        const props: Record<string, unknown> = {
+          statePath: state.path,
+          initialValue: state.initial,
+          ...(isInnermost && combinedMount ? { onMountAction: combinedMount } : {}),
+        };
+        const wrapper: SpecNode = {
+          type: '_LocalStateProvider',
+          props,
+          children: [wrapped],
+        };
+        // render() picks up this marker to populate spec.state.
+        (wrapper as any)._localStateRegistration = {
+          path: state.path,
+          initial: state.initial,
+        };
+        wrapped = wrapper;
+      }
+    }
   }
 
   return {
     ...result,
-    element: wrapper,
+    element: wrapped,
   };
 }