@applicaster/zapp-react-native-ui-components 15.0.0-rc.144 → 15.0.0-rc.145

package/Components/FocusableGroup/index.tsx

@@ -1,4 +1,5 @@
 import * as React from "react";
+import { View } from "react-native";
 
 import { BaseFocusable } from "../BaseFocusable";
 import { FocusableGroupContextProvider } from "../../Contexts/FocusableGroupContext";
@@ -75,7 +76,7 @@ class FocusableGroup extends BaseFocusable<Props> {
     const focusableId = `focusable-group-${id}`;
 
     return (
-      <div
+      <View
         id={focusableId}
         data-testid={focusableId}
         style={style}
@@ -84,7 +85,7 @@ class FocusableGroup extends BaseFocusable<Props> {
         <FocusableGroupContextProvider id={id}>
           {children}
         </FocusableGroupContextProvider>
-      </div>
+      </View>
     );
   }
 }

package/Components/Layout/TV/__tests__/__snapshots__/index.test.tsx.snap

@@ -9,6 +9,11 @@ exports[`Layout TV renders 1`] = `
     excludeFromFocusSearching={true}
     id="/river/A1234"
     preferredFocus={true}
+    style={
+      {
+        "flex": 1,
+      }
+    }
   >
     <View
       Components={

package/Components/MasterCell/CONFIG_BUILDER_TO_REACT_COMPONENT.md

@@ -0,0 +1,144 @@
+# Config Builder -> React Component Migration Guide
+
+This guide explains how to migrate MasterCell config-builders to React components incrementally, without breaking existing config-node rendering.
+
+## Why This Exists
+
+MasterCell currently supports config-node builders such as:
+
+```ts
+{
+  type: "View",
+  style: {},
+  additionalProps: {},
+  data: [],
+  elements: []
+}
+```
+
+This is still valid and should continue to work.
+
+For incremental migration, MasterCell also supports inline React nodes:
+
+```ts
+{
+  type: "ReactComponent",
+  style: {},
+  additionalProps: {
+    component: MyComponent
+  }
+}
+```
+
+This lets you migrate one builder at a time.
+
+## Rendering Pipeline
+
+1. Builder returns node config (`type`, `style`, `additionalProps`, `data`, `elements`).
+2. `configInflater` converts `additionalProps` into runtime `props` and resolves `data`.
+3. `elementMapper` renders:
+4. String `type` nodes via component registry (`components[type]`).
+5. `type: "ReactComponent"` nodes via `props.component`.
+
+## Migration Pattern
+
+1. Keep existing builder API unchanged.
+2. Add a dedicated React component for the node being migrated.
+3. Change builder output from string `type` to `type: "ReactComponent"`.
+4. Pass component reference through `additionalProps.component`.
+5. Keep behavioral props unchanged (`testID`, roles, accessibility props).
+6. Set `renderChildren` explicitly:
+7. `false` when React component renders everything itself.
+8. `true` (or omit) when builder still provides `elements` children.
+9. Set `requiresCellUUID: true` only if the component needs `cellUUID`.
+10. Update builder-shape tests and rendering tests together.
+
+## Example Using `TextLabelsContainer.ts`
+
+Current builder (config-node only):
+
+```ts
+export const TextLabelsContainer = ({ actionIdentifier, testID, style, extraProps }) => ({
+  type: "View",
+  additionalProps: {
+    mobileActionRole: "label_container",
+  },
+  elements: [
+    {
+      type: "Text",
+      style,
+      additionalProps: {
+        label: { context: actionIdentifier, name: "label_1" },
+        state: "default",
+        mobileActionRole: "label",
+        testID: testID ? `${testID}-label` : undefined,
+        ...extraProps,
+      },
+    },
+  ],
+});
+```
+
+Incremental migration target:
+
+```ts
+import { TextLabelsContainerView } from "./TextLabelsContainerView";
+
+export const TextLabelsContainer = ({ actionIdentifier, testID, style, extraProps }) => ({
+  type: "ReactComponent",
+  additionalProps: {
+    component: TextLabelsContainerView,
+    renderChildren: false,
+    mobileActionRole: "label_container",
+    actionIdentifier,
+    testID,
+    textStyle: style,
+    textProps: extraProps,
+  },
+});
+```
+
+And React component:
+
+```tsx
+export const TextLabelsContainerView = ({
+  actionIdentifier,
+  testID,
+  textStyle,
+  textProps,
+  mobileActionRole,
+}) => (
+  <View mobileActionRole={mobileActionRole}>
+    <Text
+      style={textStyle}
+      label={{ context: actionIdentifier, name: "label_1" }}
+      state="default"
+      mobileActionRole="label"
+      testID={testID ? `${testID}-label` : undefined}
+      {...textProps}
+    />
+  </View>
+);
+```
+
+This keeps external behavior and props contract intact while moving implementation to React.
+
+## Rules for Safe Incremental Migration
+
+1. Do not change role markers used by parent logic (for example `mobileActionRole`).
+2. Do not rename `testID` contracts during migration.
+3. Keep output shape stable for parent builders (`null` handling, `elements` presence).
+4. Keep data-mapping semantics identical (`label`, `state`, `entry`, etc.).
+5. Migrate one node per PR where possible.
+
+## Testing Checklist
+
+1. Builder test: node type and required props (`component`, role, `testID`) are correct.
+2. Rendering test: `configInflater + elementMapper` still renders expected UI.
+3. Behavior test: parent container logic that clones/filters children still works.
+4. Regression test: hidden/empty states still return `null` as before.
+
+## Important Limitation
+
+`additionalProps.component` is a function reference and is suitable for local JS-built trees.
+If a tree must be fully serialized JSON, use a string `componentKey` and resolve it in a registry instead of storing a function directly.

package/Components/MasterCell/DefaultComponents/ActionButtonsCore/components/ActionButtonController.tsx

@@ -0,0 +1,165 @@
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useActions } from "@applicaster/zapp-react-native-utils/reactHooks/actions";
+
+type ActionDefinition = {
+  identifier?: string;
+};
+
+type ControllerRenderProps = {
+  actionContext: any;
+  actionState: any;
+  entry: any;
+  isActive: boolean;
+  onPress: () => Promise<unknown> | unknown;
+};
+
+type Props = {
+  action?: ActionDefinition;
+  pluginIdentifier?: string;
+  entry?: any;
+  onMissingActionContext?: (identifier?: string) => void;
+  children: (props: ControllerRenderProps) => React.ReactNode;
+};
+
+const resolveIsActive = (actionState: any, fallbackSelected = false) => {
+  if (actionState == null) {
+    return fallbackSelected;
+  }
+
+  return Boolean(
+    actionState?.active ??
+      actionState?.isActive ??
+      actionState?.selected ??
+      actionState?.isSelected ??
+      fallbackSelected
+  );
+};
+
+const buildLegacySelection = (entry: any, actionContext: any) => {
+  const defaultIsSelected = Array.isArray(actionContext?.state)
+    ? (actionContext?.state || []).includes(entry)
+    : false;
+
+  return actionContext?.masterCell?.isSelected
+    ? actionContext.masterCell.isSelected(entry)
+    : defaultIsSelected;
+};
+
+export function ActionButtonController({
+  action,
+  pluginIdentifier,
+  entry,
+  onMissingActionContext,
+  children,
+}: Props) {
+  const resolvedEntry = entry;
+  const resolvedIdentifier = action?.identifier || pluginIdentifier || "";
+  const actionContext = useActions(resolvedIdentifier);
+
+  const actionDisabled =
+    typeof actionContext?.isActionAvailable === "function" &&
+    !actionContext.isActionAvailable(resolvedEntry);
+
+  const supportsEntryState =
+    typeof actionContext?.initialEntryState === "function" && !actionDisabled;
+
+  const hydrationKey = `${resolvedIdentifier}::${String(resolvedEntry?.id ?? "")}`;
+  const lastHydratedKeyRef = useRef<string | null>(null);
+
+  const [actionState, setActionState] = useState(() =>
+    supportsEntryState ? actionContext.initialEntryState(resolvedEntry) : null
+  );
+
+  useEffect(() => {
+    if (supportsEntryState) {
+      if (lastHydratedKeyRef.current === hydrationKey) {
+        return;
+      }
+
+      lastHydratedKeyRef.current = hydrationKey;
+      setActionState(actionContext.initialEntryState(resolvedEntry));
+    }
+  }, [supportsEntryState, actionContext, resolvedEntry, hydrationKey]);
+
+  useEffect(() => {
+    if (typeof actionContext?.addListener === "function") {
+      return actionContext.addListener(String(resolvedEntry?.id), (nextState) =>
+        setActionState(nextState)
+      );
+    }
+
+    if (typeof actionContext?.addListeners === "function") {
+      return actionContext.addListeners(
+        ({ entryState, entry: updatedEntry }) => {
+          if (updatedEntry?.id === resolvedEntry?.id) {
+            setActionState(entryState);
+          }
+        }
+      );
+    }
+
+    return undefined;
+  }, [
+    actionContext,
+    resolvedEntry?.id,
+    resolvedIdentifier,
+    actionContext?.addListener,
+    actionContext?.addListeners,
+  ]);
+
+  const legacySelected = useMemo(() => {
+    if (!actionContext || supportsEntryState) {
+      return false;
+    }
+
+    return buildLegacySelection(resolvedEntry, actionContext);
+  }, [actionContext, supportsEntryState, resolvedEntry]);
+
+  const isActive = resolveIsActive(actionState, legacySelected);
+
+  const onPress = useCallback(async () => {
+    if (!actionContext) {
+      return;
+    }
+
+    if (supportsEntryState) {
+      return actionContext.invokeAction?.(resolvedEntry, {
+        updateState: setActionState,
+      });
+    }
+
+    const favouritesAction = legacySelected
+      ? actionContext.removeFavourite
+      : actionContext.addFavourite;
+
+    const toggleAction = actionContext?.invokeAction ?? favouritesAction;
+
+    return toggleAction?.(resolvedEntry);
+  }, [actionContext, supportsEntryState, resolvedEntry, legacySelected]);
+
+  if (!actionContext || actionDisabled) {
+    if (!actionContext) {
+      onMissingActionContext?.(resolvedIdentifier);
+    }
+
+    return null;
+  }
+
+  return (
+    <>
+      {children({
+        actionContext,
+        actionState,
+        entry: resolvedEntry,
+        isActive,
+        onPress,
+      })}
+    </>
+  );
+}