@applicaster/zapp-react-native-utils 16.0.0-alpha.1833861900 → 16.0.0-alpha.1852433906

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,71 @@ 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);
+
+/**
+ * Reorders `items` based on an ordered array of IDs (`orderedIds`).
+ * Items whose IDs are in `orderedIds` appear first in that exact sequence.
+ * Any remaining items not present in `orderedIds` are appended at the end preserving their relative order.
+ */
+export function reorderByIds<T>(
+  items: T[],
+  orderedIds: string[],
+  getId: (item: T) => string = (item: any) => item?.id
+): T[] {
+  if (!items || items.length === 0) return [];
+  if (!orderedIds || orderedIds.length === 0) return [...items];
+
+  const itemMap = new Map<string, T>();
+
+  items.forEach((item) => {
+    const id = getId(item);
+
+    if (
+      id !== undefined &&
+      id !== null &&
+      id !== "" &&
+      !itemMap.has(String(id))
+    ) {
+      itemMap.set(String(id), item);
+    }
+  });
+
+  const reorderedSubset: T[] = [];
+  const orderedIdsSet = new Set<string>();
+
+  orderedIds.forEach((id) => {
+    const strId = String(id);
+    const item = itemMap.get(strId);
+
+    if (item && !orderedIdsSet.has(strId)) {
+      reorderedSubset.push(item);
+      orderedIdsSet.add(strId);
+    }
+  });
+
+  if (reorderedSubset.length === 0) return [...items];
+
+  let subsetIdx = 0;
+
+  return items.map((item) => {
+    const id = getId(item);
+
+    if (
+      id !== undefined &&
+      id !== null &&
+      id !== "" &&
+      orderedIdsSet.has(String(id)) &&
+      subsetIdx < reorderedSubset.length
+    ) {
+      return reorderedSubset[subsetIdx++];
+    }
+
+    return item;
+  });
+}

package/bottomSheet/__tests__/scrollContext.test.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { Text } from "react-native";
+import { render, screen } from "@testing-library/react-native";
+import { BottomSheetContext, useBottomSheet } from "../index";
+
+const Probe = () => {
+  const ctx = useBottomSheet();
+
+  return <Text testID="probe">{ctx ? "has-context" : "no-context"}</Text>;
+};
+
+describe("useBottomSheet", () => {
+  it("returns null when no provider is present", () => {
+    render(<Probe />);
+    expect(screen.getByTestId("probe")).toHaveTextContent("no-context");
+  });
+
+  it("returns the provided value inside a provider", () => {
+    const value = {
+      scrollRef: React.createRef<any>(),
+      masterDrawerRef: React.createRef<any>(),
+      setBodyDragEnabled: jest.fn(),
+      onDragGestureEvent: jest.fn(),
+      onDragStateChange: jest.fn(),
+    };
+
+    render(
+      <BottomSheetContext.Provider value={value}>
+        <Probe />
+      </BottomSheetContext.Provider>
+    );
+
+    expect(screen.getByTestId("probe")).toHaveTextContent("has-context");
+  });
+});

package/bottomSheet/index.ts

@@ -0,0 +1,17 @@
+import { createContext, useContext, RefObject } from "react";
+
+export type BottomSheetContextValue = {
+  /** The sheet's master TapGestureHandler ref — the scrollable waits for it. */
+  masterDrawerRef: RefObject<any>;
+  /** Header drag-zone wiring: the sheet's pan gesture event handler. */
+  onDragGestureEvent: (...args: any[]) => void;
+  /** Header drag-zone wiring: the sheet's pan state-change handler. */
+  onDragStateChange: (event: { nativeEvent: any }) => void;
+};
+
+export const BottomSheetContext = createContext<BottomSheetContextValue | null>(
+  null
+);
+
+export const useBottomSheet = (): BottomSheetContextValue | null =>
+  useContext(BottomSheetContext);

package/cellUtils/__tests__/getButtonsEnabled.test.ts

@@ -0,0 +1,28 @@
+import { getButtonsEnabled } from "..";
+
+describe("getButtonsEnabled", () => {
+  it("returns true when the buttons container is enabled", () => {
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: true })
+    ).toBe(true);
+
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: "true" })
+    ).toBe(true);
+  });
+
+  it("returns false when the buttons container is disabled", () => {
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: false })
+    ).toBe(false);
+
+    expect(
+      getButtonsEnabled({ mobile_buttons_container_buttons_enabled: "false" })
+    ).toBe(false);
+  });
+
+  it("returns false when the key or styles are missing", () => {
+    expect(getButtonsEnabled({})).toBe(false);
+    expect(getButtonsEnabled(undefined)).toBe(false);
+  });
+});

package/cellUtils/__tests__/getCellNavigationEnabled.test.ts

@@ -0,0 +1,36 @@
+import { getCellNavigationEnabled } from "..";
+
+describe("getCellNavigationEnabled", () => {
+  it("returns true when cell navigation is enabled", () => {
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: true,
+      })
+    ).toBe(true);
+
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: "true",
+      })
+    ).toBe(true);
+  });
+
+  it("returns false when cell navigation is disabled", () => {
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: false,
+      })
+    ).toBe(false);
+
+    expect(
+      getCellNavigationEnabled({
+        mobile_buttons_container_cell_navigation_enabled: "false",
+      })
+    ).toBe(false);
+  });
+
+  it("returns false when the key or styles are missing", () => {
+    expect(getCellNavigationEnabled({})).toBe(false);
+    expect(getCellNavigationEnabled(undefined)).toBe(false);
+  });
+});

package/cellUtils/__tests__/getIsCellNavigationEnabled.test.ts

@@ -0,0 +1,35 @@
+import { getIsCellNavigationEnabled } from "..";
+
+describe("getIsCellNavigationEnabled", () => {
+  it("is disabled when buttons are enabled and cell navigation is off", () => {
+    expect(
+      getIsCellNavigationEnabled({
+        mobile_buttons_container_buttons_enabled: true,
+        mobile_buttons_container_cell_navigation_enabled: false,
+      })
+    ).toBe(false);
+  });
+
+  it("is enabled when buttons and cell navigation are both on", () => {
+    expect(
+      getIsCellNavigationEnabled({
+        mobile_buttons_container_buttons_enabled: true,
+        mobile_buttons_container_cell_navigation_enabled: true,
+      })
+    ).toBe(true);
+  });
+
+  it("is enabled when buttons are disabled", () => {
+    expect(
+      getIsCellNavigationEnabled({
+        mobile_buttons_container_buttons_enabled: false,
+        mobile_buttons_container_cell_navigation_enabled: false,
+      })
+    ).toBe(true);
+  });
+
+  it("is enabled when the keys or styles are missing", () => {
+    expect(getIsCellNavigationEnabled({})).toBe(true);
+    expect(getIsCellNavigationEnabled(undefined)).toBe(true);
+  });
+});

package/cellUtils/__tests__/isCellNavigationEnabled.test.ts

@@ -0,0 +1,21 @@
+import { isCellNavigationEnabled } from "..";
+
+describe("isCellNavigationEnabled", () => {
+  it("is enabled when buttons are disabled, regardless of the toggle", () => {
+    expect(isCellNavigationEnabled(false, false)).toBe(true);
+    expect(isCellNavigationEnabled(false, true)).toBe(true);
+    expect(isCellNavigationEnabled(undefined, undefined)).toBe(true);
+    expect(isCellNavigationEnabled("false", false)).toBe(true);
+  });
+
+  it("is disabled when buttons are enabled and the toggle is off or missing", () => {
+    expect(isCellNavigationEnabled(true, false)).toBe(false);
+    expect(isCellNavigationEnabled(true, undefined)).toBe(false);
+    expect(isCellNavigationEnabled("true", "false")).toBe(false);
+  });
+
+  it("is enabled when buttons and the toggle are both enabled", () => {
+    expect(isCellNavigationEnabled(true, true)).toBe(true);
+    expect(isCellNavigationEnabled("true", "true")).toBe(true);
+  });
+});

package/cellUtils/index.ts

@@ -1,7 +1,7 @@
 import * as R from "ramda";
 import { dayjs } from "../dateUtils";
-import validateColor from "validate-color";
 
+import { isValidColor } from "@applicaster/zapp-react-native-utils/colorUtils";
 import { transformColorCode as fixColorHexCode } from "@applicaster/zapp-react-native-utils/transform";
 import {
   capitalize,
@@ -12,6 +12,7 @@ import { isWeb } from "@applicaster/zapp-react-native-utils/reactUtils";
 import { isNotNil } from "@applicaster/zapp-react-native-utils/reactUtils/helpers";
 
 import { toNumberWithDefault, toNumberWithDefaultZero } from "../numberUtils";
+import { isTrue } from "../booleanUtils";
 
 const CUSTOM_KEY = "other";
 
@@ -65,11 +66,38 @@ export const isEmptyOrNil = (value: any): boolean =>
  */
 export const getLabel = (dataKeyValue, customDataKeyValue) => (entry) => {
   const label = getKeyForLabel(dataKeyValue, customDataKeyValue);
-  const isPath = label && R.length(label) > 0;
-  const fallback = isEmptyOrNil(label) ? "" : R.head(label);
+  const isPath = label && label.length > 0;
+
+  // An unresolved key is rendered as-is, because a data key is allowed to be a
+  // literal label ("More") rather than a path. Fall back to the whole key
+  // instead of its first segment: "extensions.section" reads as an unresolved
+  // path, while "extensions" reads as a legitimate label and hides the problem.
+  const fallback = isEmptyOrNil(label) ? "" : label.join(".");
 
   try {
-    return isPath ? R.pathOr(fallback, label, entry) : fallback;
+    if (!isPath) {
+      return fallback;
+    }
+
+    const resolved = label.reduce(
+      (value, key) => (value == null ? undefined : value[key]),
+      entry
+    );
+
+    if (isNotNil(resolved)) {
+      return resolved;
+    }
+
+    // A multi-segment key is unambiguously a path, so failing to resolve it is
+    // a misconfiguration rather than someone typing a literal label.
+    if (label.length > 1) {
+      cellUtilsLogger.warning({
+        message: `getLabel: data key "${fallback}" was not found on the entry, rendering the key itself`,
+        data: { dataKeyValue, customDataKeyValue, entryId: entry?.id },
+      });
+    }
+
+    return fallback;
   } catch (error) {
     cellUtilsLogger.warning({
       data: { error, dataKeyValue, customDataKeyValue },
@@ -468,15 +496,13 @@ export const getColorFromData = ({
   data,
   valueFromLayout,
 }: GetColorFromData): string => {
-  // Temporary hack to fix color validation when alpha is floating point number
-  // https://github.com/dreamyguy/validate-color/issues/44
-  if (validateColor(valueFromLayout.replace(".00", ""))) {
+  if (isValidColor(valueFromLayout)) {
     return valueFromLayout;
   }
 
   const pathValue = R.path(valueFromLayout.split("."), data);
 
-  if (pathValue && validateColor(pathValue)) {
+  if (pathValue && isValidColor(pathValue)) {
     return pathValue;
   }
 
@@ -547,3 +573,42 @@ export const hasTextLabelsEnabled = (
     return Boolean(value);
   });
 };
+
+/**
+ * Reads the mobile buttons container "buttons enabled" switch from cell styles.
+ */
+export const getButtonsEnabled = (styles?: Record<string, any>): boolean => {
+  return isTrue(styles?.mobile_buttons_container_buttons_enabled);
+};
+
+/**
+ * Reads the mobile buttons container "cell navigation enabled" switch from cell styles.
+ */
+export const getCellNavigationEnabled = (
+  styles?: Record<string, any>
+): boolean => {
+  return isTrue(styles?.mobile_buttons_container_cell_navigation_enabled);
+};
+
+/**
+ * Whether tapping a cell outside its action buttons triggers the cell's navigation.
+ * Always true when the buttons are disabled.
+ * @param buttonsEnabled the cell's "buttons enabled" switch value
+ * @param cellNavigationEnabled the cell's "cell navigation enabled" switch value
+ */
+export const isCellNavigationEnabled = (
+  buttonsEnabled: unknown,
+  cellNavigationEnabled: unknown
+): boolean => !isTrue(buttonsEnabled) || isTrue(cellNavigationEnabled);
+
+/**
+ * Whether tapping a mobile cell outside its action buttons triggers the cell's navigation,
+ * read from the cell styles.
+ */
+export const getIsCellNavigationEnabled = (
+  styles?: Record<string, any>
+): boolean =>
+  isCellNavigationEnabled(
+    getButtonsEnabled(styles),
+    getCellNavigationEnabled(styles)
+  );

package/colorUtils/__tests__/isTransparentColor.test.ts

@@ -0,0 +1,76 @@
+import { isTransparentColor } from "..";
+
+describe("isTransparentColor", () => {
+  it("returns true for transparent keyword and rgba colors with zero alpha", () => {
+    const transparentColors = [
+      "transparent",
+      "rgba(0,0,0,0)",
+      "rgba(255, 255, 255, 0)",
+      "rgba(0,0,0,0.0)",
+      "rgba(0,0,0,0.00)",
+      "rgba(0,0,0, 0)",
+      "hsla(0,0%,0%,0)",
+    ];
+
+    expect.assertions(transparentColors.length);
+
+    transparentColors.forEach((color) => {
+      expect(isTransparentColor(color)).toBe(true);
+    });
+  });
+
+  it("returns false for valid colors that are not fully transparent", () => {
+    const nonTransparentColors = [
+      "red",
+      "#fff",
+      "#ffffff",
+      "rgb(0,0,0)",
+      "rgba(0,0,0)",
+      "rgba(0,0,0,0.5)",
+      "rgba(255, 255, 255, 0.3)",
+      "rgba(255, 255, 255, 1.0)",
+      "rgba(239,239,239,1.0)",
+      "currentColor",
+      "inherit",
+      "#00000000",
+      "#fff0",
+    ];
+
+    expect.assertions(nonTransparentColors.length);
+
+    nonTransparentColors.forEach((color) => {
+      expect(isTransparentColor(color)).toBe(false);
+    });
+  });
+
+  it("returns false for case variants of the transparent keyword", () => {
+    expect(isTransparentColor("Transparent")).toBe(false);
+    expect(isTransparentColor("TRANSPARENT")).toBe(false);
+  });
+
+  it("returns false for invalid color strings", () => {
+    const invalidColors = [
+      "invalid",
+      "",
+      "#gggggg",
+      "#fff.00",
+      "unset",
+      " rgba(0,0,0,0) ",
+      "transparent ",
+    ];
+
+    expect.assertions(invalidColors.length);
+
+    invalidColors.forEach((color) => {
+      expect(isTransparentColor(color)).toBe(false);
+    });
+  });
+
+  it("returns false for nullish and non-string values", () => {
+    expect(isTransparentColor(undefined)).toBe(false);
+    expect(isTransparentColor(null)).toBe(false);
+    expect(isTransparentColor(123)).toBe(false);
+    expect(isTransparentColor({})).toBe(false);
+    expect(isTransparentColor([])).toBe(false);
+  });
+});

package/colorUtils/__tests__/isValidColor.test.ts

@@ -0,0 +1,70 @@
+import { isValidColor } from "..";
+
+describe("isValidColor", () => {
+  it("returns true for valid hex colors", () => {
+    const validHexColors = ["#fff", "#ffffff", "#FF0000", "#000", "#abc123"];
+
+    expect.assertions(validHexColors.length);
+
+    validHexColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+
+  it("returns true for valid rgb and rgba colors", () => {
+    const validRgbColors = [
+      "rgb(255,0,0)",
+      "rgb(255, 0, 0)",
+      "rgba(255,0,0,0.5)",
+      "rgba(255, 0, 0, 0.5)",
+    ];
+
+    expect.assertions(validRgbColors.length);
+
+    validRgbColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+
+  it("returns true for valid named and special CSS colors", () => {
+    const validNamedColors = ["red", "transparent", "currentColor", "inherit"];
+
+    expect.assertions(validNamedColors.length);
+
+    validNamedColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+
+  it("returns true for valid hsl colors", () => {
+    expect(isValidColor("hsl(0, 100%, 50%)")).toBe(true);
+  });
+
+  it("returns false for invalid color strings", () => {
+    const invalidColors = [
+      "invalid",
+      "",
+      "#gggggg",
+      "#fff.00",
+      "unset",
+      undefined,
+      null,
+    ];
+
+    expect.assertions(invalidColors.length);
+
+    invalidColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(false);
+    });
+  });
+
+  it("returns true for valid rgb and rgba colors", () => {
+    const validRgbColors = ["rgba(239,239,239,1.0)"];
+
+    expect.assertions(validRgbColors.length);
+
+    validRgbColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+});