@granite-js/micro-frontend 2.0.0

package/ios/PortalView.mm

@@ -0,0 +1,426 @@
+//
+//  PortalView.mm
+//  Pods
+//
+//  Created by Kiryl Ziusko on 02/09/2025.
+//
+// allow: SIZE_OK - Fabric portal mounting, layout, and touch handling share one component lifecycle.
+
+#import "PortalView.h"
+#import "PortalHostView.h"
+#import "PortalRegistry.h"
+
+#import <react/renderer/components/GraniteMicroFrontendRuntimeSpec/EventEmitters.h>
+#import <react/renderer/components/GraniteMicroFrontendRuntimeSpec/Props.h>
+#import <react/renderer/components/GraniteMicroFrontendRuntimeSpec/RCTComponentViewHelpers.h>
+#import <react/renderer/components/GraniteMicroFrontendRuntimeSpec/RNTPortalViewComponentDescriptor.h>
+#import <react/renderer/components/GraniteMicroFrontendRuntimeSpec/RNTPortalViewShadowNode.h>
+
+#import "RCTFabricComponentsPlugins.h"
+
+#import <React/RCTSurfaceTouchHandler.h>
+
+using namespace facebook::react;
+
+@interface PortalView () <RCTPortalViewViewProtocol>
+
+@property (nonatomic, strong) NSString *hostName;
+// Weak so a detached/dead host cannot keep the destination tree alive through
+// the portal after unregister. Falls back to contentView when nil.
+@property (nonatomic, weak) UIView *targetView;
+
+@end
+
+@implementation PortalView {
+  NSMutableArray<UIView *> *_ownChildren;
+  PortalViewShadowNode::ConcreteState::Shared _state;
+}
+
+static BOOL GranitePortalHostNamesEqual(NSString * _Nullable left, NSString * _Nullable right)
+{
+  if (left == right) {
+    return YES;
+  }
+  if (left == nil || right == nil) {
+    return NO;
+  }
+  return [left isEqualToString:right];
+}
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+  return concreteComponentDescriptorProvider<PortalViewComponentDescriptor>();
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+    static const auto defaultProps = std::make_shared<const PortalViewProps>();
+    _props = defaultProps;
+
+    UIView *content = [[UIView alloc] init];
+    self.contentView = content;
+    self.targetView = content;
+    _ownChildren = [NSMutableArray array];
+  }
+
+  return self;
+}
+
+- (CGRect)screenRectForView:(UIView *)view
+{
+  if (!view.window) {
+    return CGRectNull;
+  }
+
+  return [view convertRect:view.bounds toCoordinateSpace:view.window.screen.coordinateSpace];
+}
+
+- (void)resetPortalLayoutStateIfNeeded
+{
+  if (!_state) {
+    return;
+  }
+
+  PortalViewState newData = {};
+  _state->updateState(
+      [=](const PortalViewShadowNode::ConcreteState::Data &oldData)
+          -> PortalViewShadowNode::ConcreteState::SharedData {
+        if (oldData.hostWidth == newData.hostWidth && oldData.hostHeight == newData.hostHeight &&
+            oldData.offsetX == newData.offsetX && oldData.offsetY == newData.offsetY) {
+          return nullptr;
+        }
+
+        return std::make_shared<const PortalViewShadowNode::ConcreteState::Data>(newData);
+      });
+}
+
+- (UIView *)resolvedTargetView
+{
+  return self.targetView ?: self.contentView;
+}
+
+- (nullable UIViewController *)nearestViewControllerForView:(UIView *)view
+{
+  for (UIResponder *responder = view; responder != nil; responder = responder.nextResponder) {
+    if ([responder isKindOfClass:[UIViewController class]]) {
+      return (UIViewController *)responder;
+    }
+  }
+  return nil;
+}
+
+- (void)updatePortalLayoutStateIfNeeded
+{
+  if (!_state) {
+    return;
+  }
+
+  UIView *targetView = [self resolvedTargetView];
+  if (!self.hostName || ![targetView isKindOfClass:[PortalHostView class]]) {
+    [self resetPortalLayoutStateIfNeeded];
+    return;
+  }
+
+  CGRect sourceRect = [self screenRectForView:self];
+  CGRect hostRect = [self screenRectForView:targetView];
+
+  if (CGRectIsNull(sourceRect) || CGRectIsNull(hostRect)) {
+    return;
+  }
+
+  // Children are physically mounted under the host, but measured through this
+  // PortalView shadow node. Store the host's native layout so Fabric
+  // measurement follows the destination after it re-layouts.
+  CGSize hostSize = targetView.bounds.size;
+
+  PortalViewState newData = {
+      static_cast<Float>(hostSize.width),
+      static_cast<Float>(hostSize.height),
+      static_cast<Float>(hostRect.origin.x - sourceRect.origin.x),
+      static_cast<Float>(hostRect.origin.y - sourceRect.origin.y)};
+
+  _state->updateState(
+      [=](const PortalViewShadowNode::ConcreteState::Data &oldData)
+          -> PortalViewShadowNode::ConcreteState::SharedData {
+        if (oldData.hostWidth == newData.hostWidth && oldData.hostHeight == newData.hostHeight &&
+            oldData.offsetX == newData.offsetX && oldData.offsetY == newData.offsetY) {
+          return nullptr;
+        }
+
+        return std::make_shared<const PortalViewShadowNode::ConcreteState::Data>(newData);
+      });
+}
+
+- (void)moveOwnChildrenToTarget:(UIView *)target
+{
+  NSArray<UIView *> *children = [_ownChildren copy];
+  NSArray<UIViewController *> *detachedViewControllers =
+      [self detachViewControllersFromChildren:children];
+
+  if ([target isKindOfClass:[PortalHostView class]]) {
+    PortalHostView *host = (PortalHostView *)target;
+    for (NSInteger i = 0; i < (NSInteger)children.count; i++) {
+      NSInteger idx = [host nextInsertionIndexForChildAt:i];
+      [target insertSubview:children[i] atIndex:idx];
+    }
+  } else {
+    for (UIView *child in children) {
+      [target addSubview:child];
+    }
+  }
+
+  [self attachViewControllers:detachedViewControllers toView:target];
+}
+
+- (void)collectViewControllersInView:(UIView *)view
+                              result:(NSMutableSet<UIViewController *> *)viewControllers
+{
+  UIResponder *nextResponder = view.nextResponder;
+  if ([nextResponder isKindOfClass:[UIViewController class]]) {
+    [viewControllers addObject:(UIViewController *)nextResponder];
+  }
+
+  for (UIView *subview in view.subviews) {
+    [self collectViewControllersInView:subview result:viewControllers];
+  }
+}
+
+- (NSArray<UIViewController *> *)detachViewControllersFromChildren:(NSArray<UIView *> *)children
+{
+  NSMutableSet<UIViewController *> *viewControllers = [NSMutableSet set];
+  for (UIView *child in children) {
+    [self collectViewControllersInView:child result:viewControllers];
+  }
+
+  NSMutableArray<UIViewController *> *viewControllersToDetach = [NSMutableArray array];
+  for (UIViewController *viewController in viewControllers) {
+    UIViewController *parent = viewController.parentViewController;
+    if (parent && ![viewControllers containsObject:parent]) {
+      [viewController willMoveToParentViewController:nil];
+      [viewControllersToDetach addObject:viewController];
+    }
+  }
+
+  for (UIView *child in children) {
+    [child removeFromSuperview];
+  }
+
+  for (UIViewController *viewController in viewControllersToDetach) {
+    [viewController removeFromParentViewController];
+  }
+
+  return viewControllersToDetach;
+}
+
+- (void)attachViewControllers:(NSArray<UIViewController *> *)viewControllers
+                       toView:(UIView *)target
+{
+  if (viewControllers.count == 0) {
+    return;
+  }
+
+  UIViewController *parentViewController = [self nearestViewControllerForView:target];
+  if (parentViewController == nil) {
+    return;
+  }
+
+  for (UIViewController *viewController in viewControllers) {
+    if (viewController.parentViewController == parentViewController) {
+      continue;
+    }
+    if (viewController.parentViewController != nil) {
+      [viewController willMoveToParentViewController:nil];
+      [viewController removeFromParentViewController];
+    }
+    [parentViewController addChildViewController:viewController];
+    [viewController didMoveToParentViewController:parentViewController];
+  }
+}
+
+- (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &)oldProps
+{
+  const auto &newViewProps = *std::static_pointer_cast<PortalViewProps const>(props);
+
+  std::string newHostStr = newViewProps.hostName;
+  NSString *newHostName =
+      newHostStr.empty() ? nil : [NSString stringWithUTF8String:newHostStr.c_str()];
+
+  if (!GranitePortalHostNamesEqual(self.hostName, newHostName)) {
+    if (self.hostName) {
+      [[PortalRegistry sharedInstance] unregisterPendingPortal:self withHostName:self.hostName];
+    }
+
+    self.hostName = newHostName;
+
+    PortalHostView *hostView = nil;
+    if (self.hostName) {
+      hostView = [[PortalRegistry sharedInstance] resolveHostWithName:self.hostName
+                                                           sourceView:self];
+    }
+
+    UIView *newTarget = hostView ? (UIView *)hostView : self.contentView;
+
+    if (newTarget != [self resolvedTargetView]) {
+      self.targetView = newTarget;
+      [self moveOwnChildrenToTarget:newTarget];
+    }
+
+    if (self.hostName) {
+      [[PortalRegistry sharedInstance] registerPendingPortal:self withHostName:self.hostName];
+    }
+  }
+
+  [super updateProps:props oldProps:oldProps];
+  [self updatePortalLayoutStateIfNeeded];
+}
+
+/// Finds the host index of the first next sibling (in _ownChildren) that is
+/// already present in the host.  Returns -1 when none is found (caller should append).
+- (NSInteger)findNextSiblingHostIndex:(NSInteger)ownIndex
+{
+  UIView *targetView = [self resolvedTargetView];
+  for (NSInteger i = ownIndex + 1; i < (NSInteger)_ownChildren.count; i++) {
+    UIView *sibling = _ownChildren[i];
+    NSInteger siblingIdx = [targetView.subviews indexOfObject:sibling];
+    if (siblingIdx != NSNotFound) {
+      return (NSInteger)siblingIdx;
+    }
+  }
+  return -1;
+}
+
+- (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                          index:(NSInteger)index
+{
+  NSInteger clampedIndex = MIN(MAX(index, 0), (NSInteger)_ownChildren.count);
+  [_ownChildren insertObject:childComponentView atIndex:clampedIndex];
+
+  UIView *targetView = [self resolvedTargetView];
+  if (targetView == self.contentView) {
+    // when adding to self, preserve the React tree order with the provided index
+    NSInteger subviewIndex = MIN(clampedIndex, (NSInteger)targetView.subviews.count);
+    [targetView insertSubview:childComponentView atIndex:subviewIndex];
+  } else {
+    NSInteger ownIndex = [_ownChildren indexOfObject:childComponentView];
+    NSInteger hostIndex = [self findNextSiblingHostIndex:ownIndex];
+    if (hostIndex >= 0) {
+      [targetView insertSubview:childComponentView atIndex:hostIndex];
+    } else {
+      [targetView addSubview:childComponentView];
+    }
+  }
+}
+
+- (void)unmountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                            index:(NSInteger)index
+{
+  [_ownChildren removeObject:childComponentView];
+  [childComponentView removeFromSuperview];
+}
+
+- (void)onHostChanged
+{
+  PortalHostView *hostView = [[PortalRegistry sharedInstance] resolveHostWithName:self.hostName
+                                                                       sourceView:self];
+
+  if (!hostView) {
+    // Match updateProps: when the destination disappears, reclaim children under
+    // the local contentView so they are not stuck under a dead host.
+    UIView *fallbackTarget = self.contentView;
+    if ([self resolvedTargetView] != fallbackTarget) {
+      self.targetView = fallbackTarget;
+      [self moveOwnChildrenToTarget:fallbackTarget];
+    }
+    [self resetPortalLayoutStateIfNeeded];
+    return;
+  }
+
+  UIView *newTarget = hostView;
+  if (newTarget != [self resolvedTargetView]) {
+    self.targetView = newTarget;
+    [self moveOwnChildrenToTarget:newTarget];
+  }
+
+  [self updatePortalLayoutStateIfNeeded];
+}
+
+- (void)onHostLayoutChanged
+{
+  [self updatePortalLayoutStateIfNeeded];
+}
+
+- (void)layoutSubviews
+{
+  [super layoutSubviews];
+  [self updatePortalLayoutStateIfNeeded];
+}
+
+- (void)updateState:(const facebook::react::State::Shared &)state
+           oldState:(const facebook::react::State::Shared &)oldState
+{
+  _state = std::static_pointer_cast<const PortalViewShadowNode::ConcreteState>(state);
+  [self updatePortalLayoutStateIfNeeded];
+}
+
+- (void)prepareForRecycle
+{
+  [super prepareForRecycle];
+
+  if (self.hostName) {
+    [[PortalRegistry sharedInstance] unregisterPendingPortal:self withHostName:self.hostName];
+  }
+
+  // Reset all portal state so recycled views don't retain stale host references.
+  // Without this, a recycled PortalView's targetView still points to the old host,
+  // causing mountChildComponentView to add children to the wrong host and
+  // moveOwnChildrenToTarget to operate on a stale source.
+  self.hostName = nil;
+  self.targetView = self.contentView;
+  [_ownChildren removeAllObjects];
+  _state.reset();
+}
+
+// MARK: touch handling
+- (UIView *)hitTest:(CGPoint)point withEvent:(UIEvent *)event
+{
+  BOOL canReceiveTouchEvents = ([self isUserInteractionEnabled] && ![self isHidden]);
+  if (!canReceiveTouchEvents) {
+    return nil;
+  }
+
+  // `hitSubview` is the topmost subview which was hit. The hit point can
+  // be outside the bounds of `view` (e.g., if -clipsToBounds is NO).
+  UIView *hitSubview = nil;
+  BOOL isPointInside = [self pointInside:point withEvent:event];
+  if (![self clipsToBounds] || isPointInside) {
+    // The default behaviour of UIKit is that if a view does not contain a point,
+    // then no subviews will be returned from hit testing, even if they contain
+    // the hit point. By doing hit testing directly on the subviews, we bypass
+    // the strict containment policy (i.e., UIKit guarantees that every ancestor
+    // of the hit view will return YES from -pointInside:withEvent:). See:
+    //  - https://developer.apple.com/library/ios/qa/qa2013/qa1812.html
+    UIView *targetView = [self resolvedTargetView];
+    for (UIView *subview in [targetView.subviews reverseObjectEnumerator]) {
+      // Prevent circular hit-testing by checking if we're in the subview's hierarchy
+      if ([self isDescendantOfView:subview]) {
+        // Skip views that contain us to prevent cycles
+        continue;
+      }
+
+      CGPoint convertedPoint = [subview convertPoint:point fromView:self];
+      hitSubview = [subview hitTest:convertedPoint withEvent:event];
+      if (hitSubview != nil) {
+        break;
+      }
+    }
+  }
+  return hitSubview;
+}
+
+Class<RCTComponentViewProtocol> PortalViewCls(void)
+{
+  return PortalView.class;
+}
+
+@end

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@granite-js/micro-frontend",
+  "version": "2.0.0",
+  "description": "Micro-frontend build, runtime, session, and Portal contracts for Granite brownfield applications",
+  "main": "./dist/module/index.js",
+  "types": "./dist/typescript/index.d.ts",
+  "react-native": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/typescript/index.d.ts",
+      "react-native": "./src/index.ts",
+      "default": "./dist/module/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/typescript/plugin/index.d.ts",
+      "default": "./dist/module/plugin/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/**/*.spec.*",
+    "dist",
+    "android",
+    "ios",
+    "common",
+    "*.podspec",
+    "react-native.config.js",
+    "README.md",
+    "LICENSE",
+    "LICENSE.react-native-teleport",
+    "NOTICE",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!examples/**",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "prepack": "yarn build",
+    "build": "bob build && tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toss/granite.git",
+    "directory": "packages/micro-frontend"
+  },
+  "dependencies": {
+    "@granite-js/utils": "workspace:*",
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@granite-js/plugin-core": "*",
+    "@granite-js/react-native": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "@granite-js/plugin-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@granite-js/plugin-core": "workspace:*",
+    "@granite-js/react-native": "workspace:*",
+    "@types/node": "catalog:tools",
+    "@types/react": "catalog:react-native",
+    "@types/react-test-renderer": "^19",
+    "react": "catalog:react-native",
+    "react-native": "catalog:react-native",
+    "react-native-builder-bob": "catalog:tools",
+    "react-test-renderer": "19.2.3",
+    "typescript": "catalog:tools",
+    "vitest": "^4.0.12"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "dist",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ]
+    ],
+    "exclude": "{**/{__tests__,__fixtures__,__mocks__}/**,**/*.spec.*,**/*.test.*}"
+  },
+  "codegenConfig": {
+    "name": "GraniteMicroFrontendRuntimeSpec",
+    "type": "all",
+    "jsSrcsDir": "src/specs",
+    "android": {
+      "javaPackageName": "run.granite.microfrontend"
+    },
+    "ios": {
+      "componentProvider": {
+        "PortalView": "PortalView",
+        "PortalHostView": "PortalHostView"
+      }
+    }
+  },
+  "sideEffects": false
+}

package/react-native.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        componentDescriptors: [
+          'PortalViewComponentDescriptor',
+          'PortalHostViewComponentDescriptor',
+        ],
+        cmakeListsPath: '../android/src/main/jni/CMakeLists.txt',
+      },
+    },
+  },
+};

package/src/createMicroFrontendRuntime.ts

@@ -0,0 +1,22 @@
+import { removePendingHostComponentRoutes } from './host/pendingHostComponentStore';
+import { createMicroFrontendRuntimeWithDependencies } from './runtime/createMicroFrontendRuntime';
+import { parseNativeRuntimeEvent } from './runtime/parseNativeRuntimeEvent';
+import { microFrontendModuleRegistry } from './runtime/registry';
+import NativeGraniteMicroFrontendRuntime from './specs/NativeGraniteMicroFrontendRuntime';
+import type { MicroFrontendAdapter, MicroFrontendRuntimeApi } from './types';
+
+export interface CreateMicroFrontendRuntimeOptions {
+  readonly adapter: MicroFrontendAdapter;
+  readonly onPreloadError?: (error: unknown) => void;
+}
+
+export function createMicroFrontendRuntime(options: CreateMicroFrontendRuntimeOptions): MicroFrontendRuntimeApi {
+  return createMicroFrontendRuntimeWithDependencies({
+    adapter: options.adapter,
+    nativeRuntime: NativeGraniteMicroFrontendRuntime,
+    onPreloadError: options.onPreloadError ?? (() => undefined),
+    parseEvent: parseNativeRuntimeEvent,
+    registry: microFrontendModuleRegistry,
+    removePendingHostComponentRoutes,
+  });
+}

package/src/createRoute.ts

@@ -0,0 +1,84 @@
+import {
+  createRoute as createGraniteRoute,
+  getSchemeUri,
+  type RegisterScreenInput,
+  type RouteOptions,
+  useNavigation,
+} from '@granite-js/react-native';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { registerPendingHostComponentRoute } from './host/pendingHostComponentStore';
+import type { PendingHostComponentAppConfig, PendingHostComponentRenderer } from './host/types';
+
+export type MicroFrontendRouteOptions<TParams extends Readonly<object> | undefined> = RouteOptions<TParams> & {
+  readonly hostPendingComponent?: PendingHostComponentRenderer<TParams>;
+};
+
+type SetParamsFunction<TParams> = (params: TParams extends undefined ? undefined : Partial<TParams>) => void;
+type ReplaceParamsFunction<TParams> = (params: TParams extends undefined ? undefined : TParams) => void;
+
+type MicroFrontendRouteResult<TInput, TOutput> = {
+  readonly _path: keyof RegisterScreenInput;
+  readonly useNavigation: typeof useNavigation;
+  readonly useParams: () => TOutput;
+  readonly useSetParams: () => SetParamsFunction<TInput>;
+  readonly useReplaceParams: () => ReplaceParamsFunction<TInput>;
+  readonly _inputType: TInput;
+  readonly _outputType: TOutput;
+};
+
+export function createRoute<TSchema extends StandardSchemaV1<unknown, Readonly<object> | undefined>>(
+  path: keyof RegisterScreenInput,
+  options: Omit<RouteOptions<StandardSchemaV1.InferOutput<TSchema>>, 'validateParams'> & {
+    readonly validateParams: TSchema;
+    readonly hostPendingComponent?: PendingHostComponentRenderer<StandardSchemaV1.InferOutput<TSchema>>;
+  }
+): MicroFrontendRouteResult<StandardSchemaV1.InferInput<TSchema>, StandardSchemaV1.InferOutput<TSchema>>;
+export function createRoute<TParams extends Readonly<object> | undefined>(
+  path: keyof RegisterScreenInput,
+  options: MicroFrontendRouteOptions<TParams>
+): MicroFrontendRouteResult<TParams, TParams>;
+export function createRoute<TParams extends Readonly<object> | undefined>(
+  path: keyof RegisterScreenInput,
+  options: MicroFrontendRouteOptions<TParams>
+) {
+  const { hostPendingComponent, ...routeOptions } = options;
+
+  if (hostPendingComponent != null) {
+    const app = getCurrentGraniteApp();
+    if (app != null) {
+      registerPendingHostComponentRoute(String(path), {
+        app,
+        component: hostPendingComponent,
+        parserParams: routeOptions.parserParams,
+        validateParams: routeOptions.validateParams,
+      });
+    }
+  }
+
+  return createGraniteRoute(path, routeOptions);
+}
+
+function getCurrentGraniteApp(): PendingHostComponentAppConfig | null {
+  const granite: unknown = Reflect.get(globalThis, '__granite');
+  if (!isPropertyMap(granite) || !isPropertyMap(granite['app'])) {
+    return null;
+  }
+
+  const host = granite['app']['host'];
+  const name = granite['app']['name'];
+  if (typeof host !== 'string' || typeof name !== 'string') {
+    return null;
+  }
+
+  const scheme = new URL(getSchemeUri()).protocol.replace(/:$/g, '');
+
+  return {
+    name,
+    scheme,
+    host,
+  };
+}
+
+function isPropertyMap(value: unknown): value is Readonly<Record<PropertyKey, unknown>> {
+  return typeof value === 'object' && value !== null;
+}