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

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

@@ -1,38 +1,74 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * SDUI page definitions for Unity packages.
- * Backend schema: SDUI_PAGE (v2) — `SDUIPageConfig` in
- * `app/hub_platform/sdui/unity_package/sdui_page_interface.py`.
- *
- * Dependency order: FUNCTION → SDUI_PAGE → CUSTOM_APP.
- */
-
 import type { ManifestFunction } from './manifest-function';
 import type { ManifestScope } from './manifest-builder';
 
+/**
+ * Initialization properties for {@link SduiPage}.
+ */
 export interface SduiPageProps {
-  /** Required. Unique ID for this page within the package. */
+  /**
+   * Unique identifier for this page within the package (e.g. `'gym_today_schedule'`).
+   *
+   * Required.
+   */
   sduiPageId: string;
-  /** Required. Display name shown as the tab label. */
+  /**
+   * Display name shown as the tab label in the app (e.g. `'Today\'s schedule'`).
+   *
+   * Required.
+   */
   name: string;
   /**
-   * Required. Backing function. Pass a live `ManifestFunction` ref (the SDK
-   * reads its api_name) or a raw api_name string for functions authored
-   * outside this manifest.
+   * The function that renders this page. Pass a live {@link ManifestFunction} reference,
+   * or a raw api_name string for functions defined outside this manifest.
+   *
+   * Required.
    */
   function: ManifestFunction | string;
-  /** Optional. Human-readable description. */
+  /**
+   * Human-readable description of what this page shows.
+   *
+   * Optional. @default `''`
+   */
   description?: string;
 }
 
+/**
+ * Defines an SDUI page and registers it with the manifest.
+ *
+ * An SDUI page is a custom UI surface backed by a {@link ManifestFunction}. It appears
+ * as a tab in a Rippling {@link App}. You would normally define SDUI pages after the
+ * functions they reference, then pass them to an `App` via `pages`.
+ *
+ * @example
+ * ```ts
+ * const todaySchedulePage = new SduiPage(manifest, {
+ *   sduiPageId: 'gym_today_schedule',
+ *   name: 'Today\'s schedule',
+ *   function: todayScheduleFn,
+ *   description: 'SDUI list of class sessions for front desk',
+ * });
+ *
+ * new App(manifest, {
+ *   apiName: 'gym_membership_management_app',
+ *   name: 'Gym Membership Management',
+ *   pages: [memberObj, trainerObj, todaySchedulePage],
+ * });
+ * ```
+ *
+ * @see {@link ManifestFunction} — provides the handler that renders this page.
+ * @see {@link App} — hosts this page as a tab via `pages`.
+ */
 export class SduiPage {
   private readonly _sduiPageId: string;
   private readonly _name: string;
   private readonly _functionApiName: string;
   private readonly _description: string;
 
-  /** Build a new SDUI page and auto-register with `scope`; resolves the function api_name eagerly. */
+  /**
+   * @param scope - The manifest to register this page with.
+   * @param props - Initialization properties.
+   * @throws {Error} If `sduiPageId`, `name`, or `function` is missing.
+   */
   constructor(scope: ManifestScope, props: SduiPageProps) {
     if (!props.sduiPageId) throw new Error('sduiPageId is required');
     if (!props.name) throw new Error('name is required');
@@ -44,22 +80,32 @@ export class SduiPage {
     scope._register(this);
   }
 
-  /** Identifier slug for this page within the package. */
+  /**
+   * Returns the unique page identifier (e.g. `'gym_today_schedule'`).
+   */
   getSduiPageId(): string {
     return this._sduiPageId;
   }
 
-  /** Display name (tab label). */
+  /**
+   * Returns the display name (tab label) of this page.
+   */
   getName(): string {
     return this._name;
   }
 
-  /** api_name of the function backing this page. */
+  /**
+   * Returns the api_name of the function backing this page.
+   */
   getFunctionApiName(): string {
     return this._functionApiName;
   }
 
-  /** Serialize to the backend `SDUI_PAGE` wire shape. */
+  /**
+   * Serializes this SDUI page to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'SDUI_PAGE'`.
+   */
   toDict(): Record<string, any> {
     return {
       type: 'SDUI_PAGE',

package/src/lib/manifest/validation.ts

@@ -1,38 +1,89 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * Validation rules for custom objects (RQL formulas with violation semantics).
- * Backend schema: CUSTOM_OBJECT_VALIDATION_RULE (v2)
- *
- * VIOLATION SEMANTICS: `rqlFormula` returns true when the record is INVALID.
- * Construction is CDK-style: `new Validation(customObject, props)` — the CO
- * is the first positional arg, and the validation auto-registers with the
- * manifest via the CO's scope chain.
- */
-
 import { generateId, type ValidationLevel, type ValidationState } from './_helpers';
 import type { CustomObject } from './custom-object';
 import type { Field } from './field';
 
+/**
+ * Initialization properties for {@link Validation}.
+ */
 export interface ValidationProps {
-  /** Required. Display name of the validation rule. */
+  /**
+   * Display name of this validation rule shown in the UI.
+   *
+   * Required.
+   */
   displayName: string;
-  /** Required. RQL formula — returns true when the record is INVALID. */
+  /**
+   * RQL formula that returns `true` when the record is **invalid**.
+   *
+   * Required. Note the violation semantics: a truthy result triggers the error,
+   * not a passing check. Example: `'(end_time__c <= start_time__c)'` fires when
+   * end is not after start.
+   */
   rqlFormula: string;
-  /** Required. User-facing error message (empty string for no message). */
+  /**
+   * User-facing error message shown when the validation fires.
+   *
+   * Required. Pass an empty string for no message.
+   */
   errorMessage: string;
-  /** Required. Rule state. */
+  /**
+   * Whether this rule is active or inactive.
+   *
+   * Required. One of `'ACTIVE'` | `'INACTIVE'`.
+   */
   state: ValidationState;
-  /** Required. Rule level. */
+  /**
+   * Whether the error is shown at the record level or on a specific field.
+   *
+   * Required. One of `'RECORD'` | `'FIELD'`. When `'FIELD'`, also set `fieldRef`.
+   */
   level: ValidationLevel;
-  /** Required. Internal description (empty string if unused). */
+  /**
+   * Internal description of this rule (for developer reference only).
+   *
+   * Required. Pass an empty string if unused.
+   */
   ruleDescription: string;
-  /** Identity override. Override the rule identifier. @default generateId('rule') */
+  /**
+   * Stable identifier for this rule. Pass a human-readable slug
+   * (e.g. `'gym_session_end_after_start'`) to keep it stable across regenerations.
+   *
+   * Optional. Auto-generated when omitted. @default generateId('rule')
+   */
   ruleId?: string;
-  /** Optional. Field reference (typically paired with `level: 'FIELD'`). */
+  /**
+   * The field the error is pinned to. Typically paired with `level: 'FIELD'`.
+   *
+   * Optional.
+   */
   fieldRef?: Field;
 }
 
+/**
+ * Defines a validation rule and registers it with the manifest.
+ *
+ * A validation rule evaluates an RQL formula on save and blocks the operation
+ * when the formula returns `true`. You would normally define validations after
+ * the fields they reference.
+ *
+ * **Violation semantics:** the formula encodes the *invalid* condition, not the
+ * valid one. `'(end_time__c <= start_time__c)'` fires when end is before or equal
+ * to start — i.e., it is truthy when the record is wrong.
+ *
+ * @example
+ * ```ts
+ * new Validation(sessionObj, {
+ *   ruleId: 'gym_session_end_after_start',
+ *   displayName: 'End time must be after start',
+ *   rqlFormula: '(end_time__c <= start_time__c)',
+ *   errorMessage: 'End time must be after the start time.',
+ *   ruleDescription: 'Prevents zero-length or inverted intervals',
+ *   state: 'ACTIVE',
+ *   level: 'FIELD',
+ *   fieldRef: sessionEndField,
+ * });
+ * ```
+ */
 export class Validation {
   private readonly _ruleId: string;
   private readonly _customObjectApiName: string;
@@ -44,7 +95,10 @@ export class Validation {
   private readonly _ruleDescription: string;
   private readonly _fieldRef: Field | undefined;
 
-  /** Build a new validation rule and auto-register with the CO's scope. */
+  /**
+   * @param customObject - The custom object this rule applies to.
+   * @param props - Initialization properties.
+   */
   constructor(customObject: CustomObject, props: ValidationProps) {
     this._ruleId = props.ruleId ?? generateId('rule');
     this._customObjectApiName = customObject.getApiName();
@@ -58,17 +112,26 @@ export class Validation {
     customObject._register(this);
   }
 
-  /** Backend rule_id used as this validation's identifier. */
+  /**
+   * Returns the stable identifier for this validation rule (e.g. `'gym_session_end_after_start'`).
+   */
   getRuleId(): string {
     return this._ruleId;
   }
 
-  /** api_name of the CustomObject this validation lives on. */
+  /**
+   * Returns the api_name of the custom object this validation rule applies to.
+   */
   getCustomObjectApiName(): string {
     return this._customObjectApiName;
   }
 
-  /** Serialize to the backend `CUSTOM_OBJECT_VALIDATION_RULE` wire shape. */
+  /**
+   * Serializes this validation rule to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_OBJECT_VALIDATION_RULE'`.
+   * `field_rql_name` is omitted when `fieldRef` was not provided.
+   */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
       type: 'CUSTOM_OBJECT_VALIDATION_RULE',

package/src/lib/sdui/actions.ts

@@ -0,0 +1,58 @@
+import { extractPath } from './state';
+
+export interface ActionBinding {
+  action: string;
+  params?: Record<string, unknown>;
+  onSuccess?: ActionBinding | { set: Record<string, unknown> };
+  onError?: ActionBinding | { set: Record<string, unknown> };
+}
+
+export function set(ref: unknown, value: unknown): ActionBinding {
+  return { action: 'setState', params: { statePath: extractPath(ref), value } };
+}
+
+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);
+  }
+  return { action: 'pushState', params };
+}
+
+export function remove(ref: unknown, index: unknown): ActionBinding {
+  return { action: 'removeState', params: { statePath: extractPath(ref), index } };
+}
+
+export function callFunction(
+  functionId: string,
+  action: string,
+  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;
+  return binding;
+}
+
+export function nav(config: { path: string; openInNewTab?: boolean }): ActionBinding {
+  return { action: 'navigate', params: config };
+}
+
+export function notify(message: string, variant: string): ActionBinding {
+  return { action: 'showNotification', params: { message, variant } };
+}
+
+export function validate(statePath = '/formValidation'): ActionBinding {
+  return { action: 'validateForm', params: { statePath } };
+}
+
+export function openModal(modalId: string): ActionBinding {
+  return { action: 'openModal', params: { modalId } };
+}
+
+export function closeModal(): ActionBinding {
+  return { action: 'closeModal' };
+}

package/src/lib/sdui/component.ts

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ *
+ * Usage:
+ *   function MembersGrid(props) {
+ *     return component((ctx) => {
+ *       const local = ctx.useState({ data: [], loading: true })
+ *       ctx.useEffect(fetchAction)
+ *       return { element: DataGrid({ ... }), refresh: fetchAction }
+ *     })
+ *   }
+ */
+
+import type { SpecNode } from './components';
+import type { ActionBinding } from './actions';
+
+let _idCounter = 0;
+function generateId(): string {
+  return `auto_${(++_idCounter).toString(36)}_${Date.now().toString(36)}`;
+}
+
+// Reset counter (for testing)
+export function _resetIdCounter(): void {
+  _idCounter = 0;
+}
+
+export interface StateScope {
+  /** Read state value: { $state: "/auto_xxx/field" } */
+  readonly [key: string]: any;
+  /** Two-way bind: { $bindState: "/auto_xxx/field" } */
+  readonly $bind: { $bindState: string };
+  /** Raw path string */
+  readonly $path: string;
+}
+
+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;
+}
+
+interface ComponentResult {
+  element: SpecNode;
+  [key: string]: any; // exposed actions like refresh, reset, etc.
+}
+
+function createScopeProxy(basePath: string): StateScope {
+  const handler: ProxyHandler<object> = {
+    get(_target, prop) {
+      if (prop === '$bind') return { $bindState: basePath };
+      if (prop === '$path') return basePath;
+      if (prop === '$state') return basePath;
+      if (prop === 'toJSON') return () => ({ $state: basePath });
+      if (prop === Symbol.toPrimitive) return () => `$state:${basePath}`;
+
+      const childPath = `${basePath}/${String(prop)}`;
+      return createScopeProxy(childPath);
+    },
+  };
+  return new Proxy({} as any, handler);
+}
+
+export function component(factory: (ctx: ComponentContext) => ComponentResult): ComponentResult {
+  let localState: { path: string; initial: unknown } | null = null;
+  let mountAction: ActionBinding | ActionBinding[] | null = null;
+
+  const ctx: ComponentContext = {
+    useState<T extends Record<string, unknown>>(initial: T): StateScope {
+      const path = `/${generateId()}`;
+      localState = { path, initial };
+      return createScopeProxy(path);
+    },
+    useEffect(action: ActionBinding | ActionBinding[]) {
+      mountAction = 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) {
+    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;
+  }
+
+  const wrapper: SpecNode = {
+    type: '_LocalStateProvider',
+    props: providerProps,
+    children: [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,
+    };
+  }
+
+  return {
+    ...result,
+    element: wrapper,
+  };
+}