@applicaster/zapp-react-native-utils 16.0.0-alpha.1042942411 → 16.0.0-alpha.1052711356

package/arrayUtils/index.ts

@@ -3,17 +3,16 @@ import * as R from "ramda";
 import { invariant } from "@applicaster/zapp-react-native-utils/errorUtils";
 
 /**
- * shifts an array by the given offset. a negative offset will take items
- * from the end of the array and add them at the beginning, while a positive offset
- * will take an item at the beginning and shift it to the end
- * shiftArray(-1, [1,2,3,4]) => [4, 1, 2, 3]
- * shiftArray(1, [1,2,3,4]) => [2, 3, 4, 1]
- * an offset of 0 leaves the array unchanged
- * this function returns a new array and doesn't mutate the original one
- * curried function which can be invoked like offset => array => result
- * @param {Number} offset offset to shift the array
- * @param {Array<T>} array array to shift
- * @returns {Array<T>}
+ * Shifts an array by the given offset and returns a new array (does not mutate).
+ * A positive offset moves items from the head to the tail;
+ * a negative offset moves items from the tail to the head.
+ * An offset of `0` leaves the order unchanged.
+ *
+ * Curried (Ramda): `shiftArray(offset)(array)` or `shiftArray(offset, array)`.
+ *
+ * @example
+ * shiftArray(-1, [1, 2, 3, 4]) // => [4, 1, 2, 3]
+ * shiftArray(1, [1, 2, 3, 4])  // => [2, 3, 4, 1]
  */
 export const shiftArray = R.curry(
   <T extends unknown>(offset: number, array: T[]): T[] => {
@@ -25,10 +24,9 @@ export const shiftArray = R.curry(
 );
 
 /**
- * Tries to remove an item from an array, and returns the array if the item is not found
- * @param {any} item to remove
- * @param {Array<any>} list to remove the item from
- * @returns {Array<any>}
+ * Removes the first item equal to `item` from `list` (Ramda `equals` / deep equality).
+ * If the item is not found, returns the same list reference; otherwise returns a new
+ * array without that element.
  */
 export function removeItemFromList<T extends unknown>(item: T, list: T[]): T[] {
   return R.compose(
@@ -37,6 +35,12 @@ export function removeItemFromList<T extends unknown>(item: T, list: T[]): T[] {
   )(list);
 }
 
+/**
+ * Maps each value to a promise and resolves them all in parallel via `Promise.all`.
+ * The mapper receives `(value, index)`.
+ *
+ * Curried (Ramda): `mapPromises(fn)(values)` or `mapPromises(fn, values)`.
+ */
 export const mapPromises = R.curry(
   <T extends unknown, S extends unknown>(
     fn: (value: T, index?: number) => Promise<S>,
@@ -44,6 +48,10 @@ export const mapPromises = R.curry(
   ): Promise<S[]> => Promise.all(R.addIndex(R.map)(R.nAry(2, fn), values))
 );
 
+/**
+ * Awaits `previousPromise`, then runs `fn(currentValue, previousValue, index)`.
+ * Used internally by `reducePromises` as a Ramda-indexed reducer step.
+ */
 const waitForPromiseAndRun = R.curryN(
   3,
   async <T extends unknown, S extends unknown>(
@@ -58,6 +66,14 @@ const waitForPromiseAndRun = R.curryN(
   }
 );
 
+/**
+ * Reduces a list by applying an async function sequentially.
+ * Each step awaits the previous result, then calls `fn(current, previous, index)`.
+ * An empty list resolves to `initialValue` without calling `fn`.
+ *
+ * Curried (Ramda): `reducePromises(fn)(initialValue)(values)` or
+ * `reducePromises(fn, initialValue, values)`.
+ */
 export const reducePromises = R.curry(
   <T extends unknown, S extends unknown>(
     fn: (current: T, previous: S, index?: number) => Promise<S>,
@@ -71,18 +87,32 @@ export const reducePromises = R.curry(
     )
 );
 
+/**
+ * Returns a function that maps a list with `mapperFn`, then splits the result
+ * into chunks of size `chunks` (`R.splitEvery`).
+ *
+ * Curried (Ramda): `mapAndSplit(mapperFn, chunks)(values)`.
+ */
 export const mapAndSplit = R.curry(
   <T extends unknown, S extends unknown>(
-    mapperFn: (T) => S,
+    mapperFn: (value: T) => S,
     chunks: number
-  ): S[][] => R.compose(R.splitEvery(chunks), R.map(mapperFn))
+  ): ((values: T[]) => S[][]) =>
+    (values: T[]) =>
+      R.splitEvery(chunks, R.map(mapperFn, values))
 );
 
+/** Returns `true` when `index` is at or past the last position (`length - 1`). */
 export const isLast = (index: number, length: number): boolean =>
   index >= length - 1;
 
+/** Returns `true` when `index` is `0` or negative. */
 export const isFirst = (index: number): boolean => index <= 0;
 
+/**
+ * Returns `true` when `index` is a valid zero-based index for a list of the
+ * given `length`. Returns `false` for empty/negative lengths or negative indexes.
+ */
 export const isIndexInRange = (index: number, length: number): boolean => {
   if (length <= 0) return false;
   if (index < 0) return false;
@@ -90,24 +120,29 @@ export const isIndexInRange = (index: number, length: number): boolean => {
   return index + 1 <= length;
 };
 
+/** Builds `[0, 1, ..., size - 1]`. Negative or zero `size` yields `[]`. */
 export const makeListOfIndexes = (size: number): number[] =>
   Array.from({ length: size }, (_, index) => index);
 
+/** Builds an array of the given `size` filled with `value`. */
 export const makeListOf = <T>(value: T, size: number): T[] => {
   return Array(size).fill(value);
 };
 
-/** Checks if a value is a non-empty array */
+/** Checks if a value is a non-empty array. */
 export function isFilledArray(value: unknown): boolean {
   return Array.isArray(value) && value.length > 0;
 }
 
-/** Checks if a value is a empty array */
+/** Checks if a value is an empty array. */
 export function isEmptyArray(value: unknown): boolean {
   return Array.isArray(value) && value.length === 0;
 }
 
-// get random item from the list
+/**
+ * Returns a random item from a non-empty array.
+ * Throws (in development via `invariant`) if the input is not an array or is empty.
+ */
 export const sample = (xs: unknown[]): unknown => {
   invariant(Array.isArray(xs), `input value is not an array: ${xs}`);
   invariant(isFilledArray(xs), `input array is empty: ${xs}`);
@@ -117,7 +152,9 @@ export const sample = (xs: unknown[]): unknown => {
   return xs[index];
 };
 
+/** Returns `true` when `xs` is non-empty and every value is truthy. */
 export const allTruthy = (xs: boolean[]) =>
   isFilledArray(xs) && xs.every(Boolean);
 
+/** Returns `true` when at least one value in `xs` is truthy. */
 export const anyTruthy = (xs: boolean[]) => xs.some(Boolean);

package/modalState/ContentViewModel.ts

@@ -0,0 +1,111 @@
+import { BehaviorSubject, Observable } from "rxjs";
+import {
+  Content,
+  MenuItem,
+  SelectionBehavior,
+  DynamicCollectionOptions,
+} from "./types";
+import { loadItemsFromSource } from "../actionsExecutor/actions/openBottomSheet";
+import { resolveEditableCollection } from "./EditableCollectionRegistry";
+import { EditableCollection } from "./EditableCollection";
+
+export interface ContentState {
+  items: MenuItem[];
+  isLoading: boolean;
+  error?: Error | string;
+  role?: string;
+  behavior?: SelectionBehavior;
+  dynamicCollection?: DynamicCollectionOptions;
+}
+
+export class ContentViewModel {
+  private state$: BehaviorSubject<ContentState>;
+  readonly itemsUrl?: string;
+  public editableCollection: EditableCollection | null = null;
+  private content: Content;
+
+  constructor(content: Content) {
+    this.content = content;
+    this.itemsUrl = content.itemsUrl;
+
+    this.state$ = new BehaviorSubject<ContentState>({
+      items: content.items || [],
+      isLoading: false,
+      role: content.role,
+      behavior: content.behavior,
+      dynamicCollection: content.dynamicCollection,
+    });
+
+    this.initEditableCollection(content);
+
+    if (this.itemsUrl && this.state$.value.items.length === 0) {
+      this.refetch();
+    }
+  }
+
+  private initEditableCollection(content: Content) {
+    this.editableCollection = resolveEditableCollection(content, this.refetch);
+  }
+
+  getState = (): ContentState => this.state$.value;
+
+  get stateObservable(): Observable<ContentState> {
+    return this.state$.asObservable();
+  }
+
+  subscribe = (listener: (state: ContentState) => void) => {
+    const subscription = this.state$.subscribe(listener);
+
+    return () => subscription.unsubscribe();
+  };
+
+  private updateState(partialState: Partial<ContentState>) {
+    this.state$.next({ ...this.state$.value, ...partialState });
+  }
+
+  refetch = async () => {
+    if (!this.itemsUrl) return;
+
+    this.updateState({ isLoading: true, error: undefined });
+
+    try {
+      const separator = this.itemsUrl.includes("?") ? "&" : "?";
+      const cacheBustedUrl = `${this.itemsUrl}${separator}_t=${Date.now()}`;
+
+      const { items, role, behavior, dynamicCollection } =
+        await loadItemsFromSource(cacheBustedUrl);
+
+      this.content = {
+        ...this.content,
+        items,
+        role,
+        behavior,
+        dynamicCollection,
+      };
+
+      this.updateState({
+        items,
+        role,
+        behavior,
+        dynamicCollection,
+        isLoading: false,
+      });
+
+      if (this.editableCollection) {
+        // Reuse the existing collection instance. Pushing the freshly loaded
+        // server items replaces any optimistic local state with the
+        // authoritative result (and rolls forward a successful mutation).
+        this.editableCollection.sync?.(items);
+      } else {
+        // The collection may only become resolvable once options arrive from
+        // the feed (e.g. inline content had none). Create it lazily here.
+        this.initEditableCollection(this.content);
+      }
+    } catch (err) {
+      this.updateState({
+        error: err?.message || "Failed to load",
+        isLoading: false,
+      });
+    }
+  };
+}

package/modalState/EditableCollection.ts

@@ -0,0 +1,17 @@
+import { Observable } from "rxjs";
+import { MenuItem, Operation } from "./types";
+
+export interface EditableCollection {
+  items$: Observable<MenuItem[]>;
+  operations: Operation[];
+  add?(item?: MenuItem): void | Promise<void>;
+  remove?(index: number): void | Promise<void>;
+  move?(itemIds: string[]): void | Promise<void>;
+  deleteCollection?(): void | Promise<void>;
+  /**
+   * Push authoritative items (e.g. a fresh server feed after a mutation) into
+   * the collection, replacing any optimistic local state. Called by the
+   * ContentViewModel on refetch so the instance is reused instead of recreated.
+   */
+  sync?(items: MenuItem[]): void;
+}

package/modalState/EditableCollectionRegistry.ts

@@ -0,0 +1,51 @@
+import { Content } from "./types";
+import { EditableCollection } from "./EditableCollection";
+import { RemoteEditableCollection } from "./RemoteEditableCollection";
+import { createLogger } from "../logger";
+
+const { log_error } = createLogger({
+  subsystem: "modalState",
+  category: "EditableCollectionRegistry",
+});
+
+type ProviderFactory = () => EditableCollection;
+
+export class EditableCollectionRegistry {
+  private static providers: Record<string, ProviderFactory> = {};
+
+  static register(token: string, factory: ProviderFactory) {
+    this.providers[token] = factory;
+  }
+
+  static getProvider(token: string): EditableCollection | null {
+    const factory = this.providers[token];
+
+    return factory ? factory() : null;
+  }
+}
+
+export function resolveEditableCollection(
+  content: Content,
+  refetch: () => Promise<void>
+): EditableCollection | null {
+  const options = content.dynamicCollection;
+  if (!options) return null;
+
+  if (options.provider) {
+    const provider = EditableCollectionRegistry.getProvider(options.provider);
+
+    if (!provider) {
+      log_error(
+        `No EditableCollection provider registered for token "${options.provider}"`
+      );
+    }
+
+    return provider;
+  }
+
+  if (options.postUrl) {
+    return new RemoteEditableCollection(content, refetch);
+  }
+
+  return null;
+}

package/modalState/ModalOrchestrator.ts

@@ -0,0 +1,198 @@
+import { dismissModal, modalStore, openBottomSheetModal } from "./store";
+import { isPresentSubMenuAction, Menu, MenuItem } from "./types";
+import { ContentViewModel } from "./ContentViewModel";
+
+export type { Menu, MenuItem };
+
+export { isPresentSubMenuAction };
+
+/**
+ * Converts a Menu model into the props expected by BottomSheetModalContent.
+ * - Maps MenuItem.title → label (required by BottomSheetModalContent)
+ * - Maps MenuItem.icon  → image src
+ * - Flattens header.title / header.subtitle into top-level title / summary
+ */
+interface StackEntry {
+  menu: Menu;
+  onItemPress?: (item: MenuItem) => void | Promise<void>;
+  viewModel: ContentViewModel;
+}
+
+function menuToModalArgs(
+  menu: Menu,
+  viewModel: ContentViewModel,
+  onItemPress: (item: MenuItem) => void | Promise<void>,
+  key: string
+): OpenModalBottomSheetArgs {
+  const items = menu.content.items.map((item) => ({
+    ...item,
+    // BottomSheetModalContent renders `theme[item.label] ?? item.label`
+    label: item.title,
+  }));
+
+  return {
+    modalBottomSheetContentProps: {
+      key,
+      items,
+      itemsUrl: menu.content.itemsUrl,
+      title: menu.header?.title ?? menu.content.title,
+      summary: menu.header?.subtitle,
+      onPress: onItemPress,
+      viewModel,
+    },
+    options: {},
+  };
+}
+
+/**
+ * ModalOrchestrator manages a stack of Menu modals, enabling push/pop
+ * navigation between bottom sheet screens.
+ *
+ * Usage:
+ *   modalOrchestrator.open(menu);
+ *   modalOrchestrator.back();    // go to previous modal in the stack
+ *   modalOrchestrator.close();   // dismiss all and clear the stack
+ */
+class ModalOrchestrator {
+  private _stack: StackEntry[] = [];
+
+  /** Number of entries currently in the stack. */
+  get stackSize(): number {
+    return this._stack.length;
+  }
+
+  /** Whether there is a previous modal to go back to. */
+  get canGoBack(): boolean {
+    return this._stack.length > 1;
+  }
+
+  /** The Menu currently shown, or null if the stack is empty. */
+  get current(): Menu | null {
+    return this._stack[this._stack.length - 1]?.menu ?? null;
+  }
+
+  /**
+   * Push a new Menu onto the stack and display it.
+   * If a menu item carries a PresentSubMenuAction it will automatically
+   * push the sub-menu when pressed; all other items delegate to
+   * the optional `onItemPress` callback.
+   */
+  open(
+    menu: Menu,
+    onItemPress?: (item: MenuItem) => void | Promise<void>
+  ): void {
+    const viewModel = new ContentViewModel(menu.content);
+    this._stack.push({ menu, onItemPress, viewModel });
+    this._present(menu, viewModel, onItemPress);
+  }
+
+  /**
+   * Pop the current modal and return to the previous one.
+   * If the stack has only one entry, closes entirely.
+   */
+  back(): void {
+    if (this._stack.length === 0) {
+      return;
+    }
+
+    this._stack.pop();
+
+    const previous = this._stack[this._stack.length - 1];
+
+    if (previous) {
+      this._present(previous.menu, previous.viewModel, previous.onItemPress);
+    } else {
+      dismissModal();
+    }
+  }
+
+  /**
+   * Close all modals and clear the entire stack.
+   */
+  close(): void {
+    this._stack = [];
+    dismissModal();
+  }
+
+  /**
+   * Replace the current top of the stack without adding a new history entry.
+   */
+  replace(
+    menu: Menu,
+    onItemPress?: (item: MenuItem) => void | Promise<void>
+  ): void {
+    if (this._stack.length === 0) {
+      this.open(menu, onItemPress);
+
+      return;
+    }
+
+    const viewModel = new ContentViewModel(menu.content);
+    this._stack[this._stack.length - 1] = { menu, onItemPress, viewModel };
+    this._present(menu, viewModel, onItemPress);
+  }
+
+  private _buildOnPress(
+    onItemPress?: (item: MenuItem) => void | Promise<void>
+  ): (item: MenuItem) => void | Promise<void> {
+    return (item: MenuItem) => {
+      if (isPresentSubMenuAction(item.action)) {
+        // Navigate deeper into the sub-menu
+        this.open(item.action.menu, onItemPress);
+
+        return;
+      }
+
+      return onItemPress?.(item);
+    };
+  }
+
+  /**
+   * Called when the UI dismisses the modal (swipe / overlay tap).
+   * Clears the stack without calling dismissModal() again to avoid
+   * a feedback loop with the store reset.
+   */
+  private _onUIDismiss(): void {
+    this._stack = [];
+  }
+
+  /**
+   * True when the Zustand modal store already has a visible bottom sheet.
+   * Used to skip the slide-in animation when navigating to a deeper level.
+   */
+  private get _isOpen(): boolean {
+    return modalStore.getState().modalState.visible;
+  }
+
+  private _present(
+    menu: Menu,
+    viewModel: ContentViewModel,
+    onItemPress?: (item: MenuItem) => void | Promise<void>
+  ): void {
+    const key = `menu-level-${this._stack.length}`;
+
+    const args = menuToModalArgs(
+      menu,
+      viewModel,
+      this._buildOnPress(onItemPress),
+      key
+    );
+
+    const alreadyOpen = this._isOpen;
+
+    openBottomSheetModal({
+      ...args,
+      options: {
+        ...args.options,
+        // Skip the slide-in when updating an already-visible sheet (sub-level nav)
+        animated: !alreadyOpen,
+        animationType: alreadyOpen ? "none" : "slide",
+        // Keep the stack in sync when the user dismisses via swipe or overlay
+        onDismiss: () => this._onUIDismiss(),
+        onRequestClose: () => this._onUIDismiss(),
+      },
+    });
+  }
+}
+
+export const modalOrchestrator = new ModalOrchestrator();