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

package/src/lib/manifest/rule.ts

@@ -1,6 +1,13 @@
 import { generateId, type TriggerType, type UpdateTriggerType } from './_helpers';
 import type { CustomObject } from './custom-object';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { Field } from './field';
+import type { ManifestComponentDeletion } from './manifest-builder';
+
+export interface RuleDeletionIdentifier {
+  flowId: string;
+  modelRqlName: string;
+}
 
 /**
  * A single action performed when a {@link Rule} fires.
@@ -79,6 +86,10 @@ export interface RuleProps {
   actions?: RuleAction[];
 }
 
+export interface RuleLoadFromExistingOptions extends ExistingManifestContextOptions {
+  customObjectApiName?: string;
+}
+
 /** SELECT / RADIO rule actions use list `fixed_value` (Rippling rule builder). */
 function fixedValueToWire(targetField: Field, value: any): any {
   const ft = targetField.getFieldType();
@@ -103,6 +114,10 @@ function actionToDict(action: RuleAction): Record<string, any> {
   return out;
 }
 
+function hasOwn(value: Record<string, any>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
 /**
  * Defines a record-triggered automation rule and registers it with the manifest.
  *
@@ -122,6 +137,16 @@ function actionToDict(action: RuleAction): Record<string, any> {
  * ```
  */
 export class Rule {
+  static readonly componentType = 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW' as const;
+
+  static toDeletionIdentifier(identifier: RuleDeletionIdentifier): ManifestComponentDeletion {
+    return {
+      type: Rule.componentType,
+      flow_id: identifier.flowId,
+      model_rql_name: identifier.modelRqlName,
+    };
+  }
+
   private readonly _flowId: string;
   private readonly _customObjectApiName: string;
   private readonly _flowName: string;
@@ -154,6 +179,40 @@ export class Rule {
     customObject._register(this);
   }
 
+  /**
+   * Loads this record-triggered rule from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(flowId: string, options: RuleLoadFromExistingOptions = {}): Rule {
+    return getExistingManifestContext(options).loadRule(flowId, options);
+  }
+
+  /** @internal Hydrates a record-triggered rule from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    customObject: CustomObject,
+    component: Record<string, any>,
+    resolveField: (apiName: string) => Field,
+  ): Rule {
+    const props: RuleProps = {
+      flowId: component['flow_id'],
+      flowName: component['flow_name'] ?? component['flow_id'],
+      triggerType: component['trigger_type'],
+      actions: (component['actions'] ?? []).map((action: Record<string, any>): RuleAction => {
+        const out: RuleAction = {
+          targetField: resolveField(action['target_field']),
+        };
+        if (hasOwn(action, 'fixed_value')) out.fixedValue = action['fixed_value'];
+        if (hasOwn(action, 'rql_formula')) out.rqlFormula = action['rql_formula'];
+        return out;
+      }),
+    };
+    if (component['description'] !== undefined) props.description = component['description'];
+    if (component['rql_condition'] !== undefined) props.rqlCondition = component['rql_condition'];
+    if (component['update_trigger_type'] !== undefined) {
+      props.updateTriggerType = component['update_trigger_type'];
+    }
+    return new Rule(customObject, props);
+  }
+
   /**
    * Returns the stable identifier for this rule (e.g. `'gym_default_enrollment_status'`).
    */
@@ -176,7 +235,7 @@ export class Rule {
    */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
-      type: 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW',
+      type: Rule.componentType,
       model_rql_name: this._customObjectApiName,
       flow_id: this._flowId,
       flow_name: this._flowName,

package/src/lib/manifest/sdui-page.ts

@@ -1,5 +1,6 @@
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { ManifestFunction } from './manifest-function';
-import type { ManifestScope } from './manifest-builder';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
 
 /**
  * Initialization properties for {@link SduiPage}.
@@ -59,6 +60,15 @@ export interface SduiPageProps {
  * @see {@link App} — hosts this page as a tab via `pages`.
  */
 export class SduiPage {
+  static readonly componentType = 'SDUI_PAGE' as const;
+
+  static toDeletionIdentifier(sduiPageId: string): ManifestComponentDeletion {
+    return {
+      type: SduiPage.componentType,
+      sdui_page_id: sduiPageId,
+    };
+  }
+
   private readonly _sduiPageId: string;
   private readonly _name: string;
   private readonly _functionApiName: string;
@@ -80,6 +90,31 @@ export class SduiPage {
     scope._register(this);
   }
 
+  /**
+   * Loads this SDUI page from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(sduiPageId: string, options: ExistingManifestContextOptions = {}): SduiPage {
+    return getExistingManifestContext(options).loadSduiPage(sduiPageId);
+  }
+
+  /** @internal Hydrates an SDUI page from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    scope: ManifestScope,
+    component: Record<string, any>,
+    resolveFunction: (apiName: string) => ManifestFunction | string,
+  ): SduiPage {
+    const functionApiName = component['function_api_name'];
+    const props: SduiPageProps = {
+      sduiPageId: component['sdui_page_id'],
+      name: component['name'] ?? component['sdui_page_id'],
+      function: typeof functionApiName === 'string' ? resolveFunction(functionApiName) : functionApiName,
+    };
+    if (component['description'] !== undefined) {
+      props.description = component['description'];
+    }
+    return new SduiPage(scope, props);
+  }
+
   /**
    * Returns the unique page identifier (e.g. `'gym_today_schedule'`).
    */
@@ -108,7 +143,7 @@ export class SduiPage {
    */
   toDict(): Record<string, any> {
     return {
-      type: 'SDUI_PAGE',
+      type: SduiPage.componentType,
       name: this._name,
       sdui_page_id: this._sduiPageId,
       function_api_name: this._functionApiName,

package/src/lib/manifest/validation.ts

@@ -1,6 +1,13 @@
 import { generateId, type ValidationLevel, type ValidationState } from './_helpers';
 import type { CustomObject } from './custom-object';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { Field } from './field';
+import type { ManifestComponentDeletion } from './manifest-builder';
+
+export interface ValidationDeletionIdentifier {
+  ruleId: string;
+  modelRqlName: string;
+}
 
 /**
  * Initialization properties for {@link Validation}.
@@ -59,6 +66,10 @@ export interface ValidationProps {
   fieldRef?: Field;
 }
 
+export interface ValidationLoadFromExistingOptions extends ExistingManifestContextOptions {
+  customObjectApiName?: string;
+}
+
 /**
  * Defines a validation rule and registers it with the manifest.
  *
@@ -85,6 +96,16 @@ export interface ValidationProps {
  * ```
  */
 export class Validation {
+  static readonly componentType = 'CUSTOM_OBJECT_VALIDATION_RULE' as const;
+
+  static toDeletionIdentifier(identifier: ValidationDeletionIdentifier): ManifestComponentDeletion {
+    return {
+      type: Validation.componentType,
+      rule_id: identifier.ruleId,
+      model_rql_name: identifier.modelRqlName,
+    };
+  }
+
   private readonly _ruleId: string;
   private readonly _customObjectApiName: string;
   private readonly _displayName: string;
@@ -112,6 +133,32 @@ export class Validation {
     customObject._register(this);
   }
 
+  /**
+   * Loads this validation rule from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(ruleId: string, options: ValidationLoadFromExistingOptions = {}): Validation {
+    return getExistingManifestContext(options).loadValidation(ruleId, options);
+  }
+
+  /** @internal Hydrates a validation rule from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    customObject: CustomObject,
+    component: Record<string, any>,
+    resolveField: (apiName: string) => Field,
+  ): Validation {
+    const props: ValidationProps = {
+      ruleId: component['rule_id'],
+      displayName: component['display_name'] ?? component['rule_id'],
+      rqlFormula: component['rql_formula'] ?? '',
+      errorMessage: component['custom_error_message'] ?? '',
+      state: component['state'],
+      level: component['level'],
+      ruleDescription: component['rule_description'] ?? '',
+    };
+    if (component['field_rql_name'] != null) props.fieldRef = resolveField(component['field_rql_name']);
+    return new Validation(customObject, props);
+  }
+
   /**
    * Returns the stable identifier for this validation rule (e.g. `'gym_session_end_after_start'`).
    */
@@ -134,7 +181,7 @@ export class Validation {
    */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
-      type: 'CUSTOM_OBJECT_VALIDATION_RULE',
+      type: Validation.componentType,
       model_rql_name: this._customObjectApiName,
       rule_id: this._ruleId,
       state: this._state,

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,
   };
 }