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

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