@granite-js/micro-frontend 2.0.0

package/src/host/PendingHostComponent.tsx

@@ -0,0 +1,92 @@
+import { useCallback, useState, useSyncExternalStore } from 'react';
+import { StyleSheet, View } from 'react-native';
+import {
+  getPendingHostComponentStoreVersion,
+  getIsPendingHostComponentHidden,
+  resetPendingHostComponent,
+  resolvePendingHostComponent,
+  subscribePendingHostComponentStore,
+} from './pendingHostComponentStore';
+
+export interface PendingHostComponentProps {
+  readonly url: string | null | undefined;
+}
+
+export interface PendingHostComponentController {
+  readonly url: string | null;
+  readonly isPresent: boolean;
+  readonly isHidden: boolean;
+  readonly present: (url: string | null) => void;
+  readonly dismiss: () => void;
+}
+
+export function useIsPendingHostComponentHidden() {
+  return useSyncExternalStore(subscribePendingHostComponentStore, getIsPendingHostComponentHidden, getIsPendingHostComponentHidden);
+}
+
+function usePendingHostComponentStoreVersion() {
+  return useSyncExternalStore(subscribePendingHostComponentStore, getPendingHostComponentStoreVersion, getPendingHostComponentStoreVersion);
+}
+
+export function useResolvedPendingHostComponent(url: string | null | undefined) {
+  usePendingHostComponentStoreVersion();
+
+  if (url == null) {
+    return null;
+  }
+
+  return resolvePendingHostComponent(url);
+}
+
+export function PendingHostComponent({ url }: PendingHostComponentProps) {
+  const resolvedPendingHostComponent = useResolvedPendingHostComponent(url);
+  const isHidden = useIsPendingHostComponentHidden();
+
+  if (resolvedPendingHostComponent == null || isHidden) {
+    return null;
+  }
+
+  const Component = resolvedPendingHostComponent.component;
+
+  return (
+    <View
+      accessibilityElementsHidden={true}
+      importantForAccessibility="no-hide-descendants"
+      pointerEvents="none"
+      style={styles.root}
+    >
+      <Component {...resolvedPendingHostComponent.params} />
+    </View>
+  );
+}
+
+export function usePendingHostComponentController(): PendingHostComponentController {
+  const [url, setUrl] = useState<string | null>(null);
+  const [isPresent, setIsPresent] = useState(false);
+  const isHidden = useIsPendingHostComponentHidden();
+
+  const present = useCallback((nextUrl: string | null) => {
+    setIsPresent((wasPresent) => {
+      if (wasPresent) {
+        resetPendingHostComponent();
+      }
+
+      return true;
+    });
+    setUrl(nextUrl);
+  }, []);
+
+  const dismiss = useCallback(() => {
+    resetPendingHostComponent();
+    setUrl(null);
+    setIsPresent(false);
+  }, []);
+
+  return { url, isPresent, isHidden, present, dismiss };
+}
+
+const styles = StyleSheet.create({
+  root: {
+    ...StyleSheet.absoluteFillObject,
+  },
+});

package/src/host/index.ts

@@ -0,0 +1,26 @@
+export type { PendingHostComponentController, PendingHostComponentProps } from './PendingHostComponent';
+export {
+  PendingHostComponent,
+  usePendingHostComponentController,
+  useIsPendingHostComponentHidden,
+  useResolvedPendingHostComponent,
+} from './PendingHostComponent';
+export type {
+  PendingHostComponentAppConfig,
+  PendingHostComponentRenderer,
+  PendingHostComponentParams,
+  PendingHostComponentRouteRequest,
+  RegisterPendingHostComponentRouteOptions,
+  ResolvedPendingHostComponent,
+} from './types';
+export {
+  createPendingHostComponentRoutePrefix,
+  normalizeRoutePath,
+} from './routeMatcher';
+export {
+  hidePendingHostComponent,
+  installPendingHostComponentBridge,
+  registerPendingHostComponentRoute,
+  resetPendingHostComponent,
+  resolvePendingHostComponent,
+} from './pendingHostComponentStore';

package/src/host/pendingHostComponentStore.ts

@@ -0,0 +1,241 @@
+import { resolvePendingHostComponentParams } from './resolveParams';
+import {
+  createPendingHostComponentRoutePrefix,
+  getQueryParamsFromUrl,
+  getRoutePathFromUrl,
+  matchRoutePath,
+  normalizePendingHostComponentAppName,
+  normalizeRoutePath,
+} from './routeMatcher';
+import type {
+  PendingHostComponentRenderer,
+  PendingHostComponentRouteRequest,
+  RegisterPendingHostComponentRouteOptions,
+  ResolvedPendingHostComponent,
+  ValidateParams,
+} from './types';
+
+interface PendingHostComponentRouteEntry {
+  readonly id: string;
+  readonly routePath: string;
+  readonly routePrefix: string;
+  readonly appName: string;
+  readonly component: PendingHostComponentRenderer<Readonly<object>>;
+  readonly parserParams?: (params: Record<string, unknown>) => Record<string, unknown>;
+  readonly validateParams?: ValidateParams<Readonly<object> | undefined>;
+}
+
+interface MatchedPendingHostComponentRoute {
+  readonly entry: PendingHostComponentRouteEntry;
+  readonly pathParams: Record<string, string>;
+  readonly params: Record<string, unknown>;
+  readonly routePath: string;
+  readonly url: string | null;
+}
+
+interface PendingHostComponentStore {
+  entries: PendingHostComponentRouteEntry[];
+  hidden: boolean;
+  readonly listeners: Set<() => void>;
+  version: number;
+}
+
+interface GlobalWithPendingHostComponentStore {
+  __graniteMicroFrontendPendingHostComponentStore?: PendingHostComponentStore;
+  hideSharedPendingHostComponent?: () => void;
+}
+
+function getGlobalObject() {
+  return globalThis as typeof globalThis & GlobalWithPendingHostComponentStore;
+}
+
+function getPendingHostComponentStore() {
+  const globalObject = getGlobalObject();
+
+  if (globalObject.__graniteMicroFrontendPendingHostComponentStore == null) {
+    globalObject.__graniteMicroFrontendPendingHostComponentStore = {
+      entries: [],
+      hidden: false,
+      listeners: new Set(),
+      version: 0,
+    };
+  }
+
+  return globalObject.__graniteMicroFrontendPendingHostComponentStore;
+}
+
+function emitPendingHostComponentStoreChange() {
+  const store = getPendingHostComponentStore();
+  store.version += 1;
+  store.listeners.forEach(listener => listener());
+}
+
+export function subscribePendingHostComponentStore(listener: () => void) {
+  const store = getPendingHostComponentStore();
+  store.listeners.add(listener);
+
+  return () => store.listeners.delete(listener);
+}
+
+export function getPendingHostComponentStoreVersion() {
+  return getPendingHostComponentStore().version;
+}
+
+export function getIsPendingHostComponentHidden() {
+  return getPendingHostComponentStore().hidden;
+}
+
+function setPendingHostComponentHidden(hidden: boolean) {
+  const store = getPendingHostComponentStore();
+
+  if (store.hidden === hidden) {
+    return;
+  }
+
+  store.hidden = hidden;
+  emitPendingHostComponentStoreChange();
+}
+
+export function hidePendingHostComponent() {
+  setPendingHostComponentHidden(true);
+
+  const hideSharedPendingHostComponent = getGlobalObject().hideSharedPendingHostComponent;
+  if (typeof hideSharedPendingHostComponent === 'function' && hideSharedPendingHostComponent !== hidePendingHostComponent) {
+    hideSharedPendingHostComponent();
+  }
+}
+
+export function resetPendingHostComponent() {
+  setPendingHostComponentHidden(false);
+}
+
+export function installPendingHostComponentBridge() {
+  getGlobalObject().hideSharedPendingHostComponent = hidePendingHostComponent;
+}
+
+export function registerPendingHostComponentRoute<
+  TParams extends Readonly<object> | undefined = undefined,
+>(routePath: string, options: RegisterPendingHostComponentRouteOptions<TParams>) {
+  const store = getPendingHostComponentStore();
+  const normalizedRoutePath = normalizeRoutePath(routePath);
+  const appName = normalizePendingHostComponentAppName(options.app.name);
+  const routePrefix = createPendingHostComponentRoutePrefix(options.app);
+  const id = `${routePrefix}:${normalizedRoutePath}`;
+  const entry: PendingHostComponentRouteEntry = {
+    id,
+    routePath: normalizedRoutePath,
+    routePrefix,
+    appName,
+    component: options.component,
+    parserParams: options.parserParams,
+    validateParams: options.validateParams,
+  };
+  const existingIndex = store.entries.findIndex(item => item.id === id);
+
+  if (existingIndex >= 0) {
+    store.entries[existingIndex] = entry;
+  } else {
+    store.entries.push(entry);
+  }
+
+  emitPendingHostComponentStoreChange();
+}
+
+export function removePendingHostComponentRoutes(appName: string) {
+  const store = getPendingHostComponentStore();
+  const normalizedAppName = normalizePendingHostComponentAppName(appName);
+  const remainingEntries = store.entries.filter(entry => entry.appName !== normalizedAppName);
+
+  if (remainingEntries.length === store.entries.length) {
+    return;
+  }
+
+  store.entries = remainingEntries;
+  emitPendingHostComponentStoreChange();
+}
+
+export function resolvePendingHostComponent(request: PendingHostComponentRouteRequest | string): ResolvedPendingHostComponent | null {
+  const matched = typeof request === 'string' ? findRouteByUrl(request) : findRouteByRequest(request);
+
+  return resolveMatchedPendingHostComponent(matched);
+}
+
+function resolveMatchedPendingHostComponent(matched: MatchedPendingHostComponentRoute | null): ResolvedPendingHostComponent | null {
+  if (matched == null) {
+    return null;
+  }
+
+  const params = resolvePendingHostComponentParams(
+    { ...matched.pathParams, ...matched.params },
+    matched.entry.parserParams,
+    matched.entry.validateParams
+  );
+
+  if (params.status === 'invalid') {
+    return null;
+  }
+
+  return {
+    component: matched.entry.component,
+    params: params.value,
+    url: matched.url,
+    routePath: matched.routePath,
+    appName: matched.entry.appName,
+  };
+}
+
+function findRouteByUrl(url: string): MatchedPendingHostComponentRoute | null {
+  const entries = getPendingHostComponentStore().entries;
+
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry == null) {
+      continue;
+    }
+
+    const routePath = getRoutePathFromUrl(url, entry.routePrefix);
+    const pathParams = routePath == null ? null : matchRoutePath(entry.routePath, routePath);
+    if (routePath == null || pathParams == null) {
+      continue;
+    }
+
+    return { entry, pathParams, params: getQueryParamsFromUrl(url), routePath, url };
+  }
+
+  return null;
+}
+
+function findRouteByRequest(request: PendingHostComponentRouteRequest): MatchedPendingHostComponentRoute | null {
+  const appName = normalizePendingHostComponentAppName(request.appName);
+
+  for (let index = getPendingHostComponentStore().entries.length - 1; index >= 0; index -= 1) {
+    const entry = getPendingHostComponentStore().entries[index];
+    if (entry == null || entry.appName !== appName) {
+      continue;
+    }
+
+    const routePath = normalizeRoutePath(request.routePath);
+    const pathParams = matchRoutePath(entry.routePath, routePath);
+    if (pathParams == null) {
+      continue;
+    }
+
+    return {
+      entry,
+      pathParams,
+      params: request.params ?? {},
+      routePath,
+      url: request.url ?? null,
+    } satisfies MatchedPendingHostComponentRoute;
+  }
+
+  return null;
+}
+
+export function resetPendingHostComponentStoreForTest() {
+  const store = getPendingHostComponentStore();
+  store.entries = [];
+  store.hidden = false;
+  store.version = 0;
+  emitPendingHostComponentStoreChange();
+}

package/src/host/resolveParams.ts

@@ -0,0 +1,70 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ParserParams, ValidateParams } from './types';
+
+type ResolvedParams =
+  | { readonly status: 'resolved'; readonly value: Readonly<object> }
+  | { readonly status: 'invalid'; readonly cause?: Error };
+
+export function resolvePendingHostComponentParams(
+  rawParams: Record<string, unknown>,
+  parserParams: ParserParams | undefined,
+  validateParams: ValidateParams<Readonly<object> | undefined> | undefined
+): ResolvedParams {
+  const parsedParams = (parserParams ?? defaultParserParams)(rawParams);
+
+  if (validateParams == null) {
+    return { status: 'resolved', value: parsedParams };
+  }
+
+  try {
+    if (isStandardSchema(validateParams)) {
+      const result = validateParams['~standard'].validate(parsedParams);
+
+      if (result instanceof Promise) {
+        return { status: 'invalid', cause: new Error('Async pending host component validation is not supported') };
+      }
+
+      if (result.issues != null) {
+        return {
+          status: 'invalid',
+          cause: new Error(result.issues.map(issue => issue.message).join(', ')),
+        };
+      }
+
+      return { status: 'resolved', value: result.value ?? {} };
+    }
+
+    return { status: 'resolved', value: validateParams(parsedParams) ?? {} };
+  } catch (error) {
+    return {
+      status: 'invalid',
+      cause: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}
+
+function defaultParserParams(params: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(params).map(([key, value]) => {
+      if (typeof value !== 'string') {
+        return [key, value];
+      }
+
+      try {
+        return [key, JSON.parse(value)];
+      } catch (error) {
+        if (!(error instanceof SyntaxError)) {
+          throw error;
+        }
+
+        return [key, value];
+      }
+    })
+  );
+}
+
+function isStandardSchema<TParams extends Readonly<object> | undefined>(
+  value: ValidateParams<TParams>
+): value is StandardSchemaV1<unknown, TParams> {
+  return typeof value === 'object' && value !== null && '~standard' in value;
+}

package/src/host/routeMatcher.ts

@@ -0,0 +1,117 @@
+import type { PendingHostComponentAppConfig } from './types';
+
+export function normalizeRoutePath(routePath: string) {
+  const pathname = routePath.split('#')[0]?.split('?')[0] ?? '/';
+  const pathWithLeadingSlash = pathname.startsWith('/') ? pathname : `/${pathname}`;
+  const normalizedPathname = pathWithLeadingSlash.replace(/\/+/g, '/');
+
+  return normalizedPathname === '/' ? '/' : normalizedPathname.replace(/\/+$/g, '');
+}
+
+export function createPendingHostComponentRoutePrefix(app: PendingHostComponentAppConfig) {
+  const scheme = app.scheme.replace(/:$/g, '');
+  const appName = normalizePendingHostComponentAppName(app.name);
+  const host = app.host == null ? '' : app.host.replace(/^\/+|\/+$/g, '');
+
+  return host.length > 0 ? `${scheme}://${host}/${appName}` : `${scheme}://${appName}`;
+}
+
+export function getRoutePathFromUrl(url: string, routePrefix: string) {
+  const normalizedPrefix = trimTrailingSlash(routePrefix);
+  const urlWithoutSearch = trimTrailingSlash(stripSearchAndHash(url));
+
+  if (urlWithoutSearch === normalizedPrefix) {
+    return '/';
+  }
+
+  if (!urlWithoutSearch.startsWith(`${normalizedPrefix}/`)) {
+    return null;
+  }
+
+  return normalizeRoutePath(urlWithoutSearch.slice(normalizedPrefix.length));
+}
+
+export function getQueryParamsFromUrl(url: string): Record<string, string> {
+  try {
+    return Object.fromEntries(new URL(url).searchParams.entries());
+  } catch (error) {
+    if (!(error instanceof TypeError)) {
+      throw error;
+    }
+
+    const questionMarkIndex = url.indexOf('?');
+    if (questionMarkIndex === -1) {
+      return {};
+    }
+
+    const fragmentIndex = url.indexOf('#', questionMarkIndex + 1);
+    const queryEndIndex = fragmentIndex === -1 ? url.length : fragmentIndex;
+
+    return Object.fromEntries(new URLSearchParams(url.slice(questionMarkIndex + 1, queryEndIndex)).entries());
+  }
+}
+
+export function matchRoutePath(pattern: string, routePath: string) {
+  const patternSegments = splitRoutePath(pattern);
+  const routeSegments = splitRoutePath(routePath);
+
+  if (patternSegments.length !== routeSegments.length) {
+    return null;
+  }
+
+  const params: Record<string, string> = {};
+
+  for (let index = 0; index < patternSegments.length; index += 1) {
+    const patternSegment = patternSegments[index];
+    const routeSegment = routeSegments[index];
+
+    if (patternSegment == null || routeSegment == null) {
+      return null;
+    }
+
+    if (patternSegment.startsWith(':')) {
+      const paramName = patternSegment.slice(1);
+      if (paramName.length === 0) {
+        return null;
+      }
+
+      params[paramName] = decodeRouteSegment(routeSegment);
+      continue;
+    }
+
+    if (patternSegment !== routeSegment) {
+      return null;
+    }
+  }
+
+  return params;
+}
+
+export function normalizePendingHostComponentAppName(appName: string) {
+  return appName.replace(/^\/+|\/+$/g, '');
+}
+
+function splitRoutePath(routePath: string) {
+  const normalizedRoutePath = normalizeRoutePath(routePath);
+  return normalizedRoutePath === '/' ? [] : normalizedRoutePath.slice(1).split('/');
+}
+
+function stripSearchAndHash(url: string) {
+  return url.split('#')[0]?.split('?')[0] ?? url;
+}
+
+function trimTrailingSlash(value: string) {
+  return value.length > 1 ? value.replace(/\/+$/g, '') : value;
+}
+
+function decodeRouteSegment(value: string) {
+  try {
+    return decodeURIComponent(value);
+  } catch (error) {
+    if (!(error instanceof URIError)) {
+      throw error;
+    }
+
+    return value;
+  }
+}

package/src/host/types.ts

@@ -0,0 +1,45 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ReactNode } from 'react';
+
+export type PendingHostComponentParams<TParams extends Readonly<object> | undefined = undefined> =
+  TParams extends Readonly<object> ? TParams : Readonly<Record<string, never>>;
+
+export type PendingHostComponentRenderer<TParams extends Readonly<object> | undefined = undefined> = {
+  bivarianceHack(params: PendingHostComponentParams<TParams>): ReactNode;
+}['bivarianceHack'];
+
+export type ParserParams = (params: Record<string, unknown>) => Record<string, unknown>;
+
+export type ValidateParams<TParams extends Readonly<object> | undefined> =
+  | ((params: Readonly<object> | undefined) => TParams)
+  | StandardSchemaV1<unknown, TParams>;
+
+export interface PendingHostComponentAppConfig {
+  readonly name: string;
+  readonly scheme: string;
+  readonly host?: string | null;
+}
+
+export interface RegisterPendingHostComponentRouteOptions<
+  TParams extends Readonly<object> | undefined = undefined,
+> {
+  readonly component: PendingHostComponentRenderer<TParams>;
+  readonly parserParams?: ParserParams;
+  readonly validateParams?: ValidateParams<TParams>;
+  readonly app: PendingHostComponentAppConfig;
+}
+
+export interface PendingHostComponentRouteRequest {
+  readonly routePath: string;
+  readonly params?: Record<string, unknown>;
+  readonly appName: string;
+  readonly url?: string | null;
+}
+
+export interface ResolvedPendingHostComponent {
+  readonly component: PendingHostComponentRenderer<Readonly<object>>;
+  readonly params: Readonly<object>;
+  readonly url: string | null;
+  readonly routePath: string;
+  readonly appName: string | null;
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+export { createMicroFrontendRuntime } from './createMicroFrontendRuntime';
+export type { CreateMicroFrontendRuntimeOptions } from './createMicroFrontendRuntime';
+export { createRoute } from './createRoute';
+export type { MicroFrontendRouteOptions } from './createRoute';
+export type { PendingHostComponentController, PendingHostComponentProps } from './host/PendingHostComponent';
+export {
+  PendingHostComponent,
+  usePendingHostComponentController,
+  useIsPendingHostComponentHidden,
+  useResolvedPendingHostComponent,
+} from './host/PendingHostComponent';
+export type {
+  PendingHostComponentAppConfig,
+  PendingHostComponentRenderer,
+  PendingHostComponentParams,
+  PendingHostComponentRouteRequest,
+  RegisterPendingHostComponentRouteOptions,
+  ResolvedPendingHostComponent,
+} from './host/types';
+export {
+  createPendingHostComponentRoutePrefix,
+  normalizeRoutePath,
+} from './host/routeMatcher';
+export {
+  hidePendingHostComponent,
+  installPendingHostComponentBridge,
+  registerPendingHostComponentRoute,
+  resetPendingHostComponent,
+  resolvePendingHostComponent,
+} from './host/pendingHostComponentStore';
+export {
+  MicroFrontendSessionProvider,
+  MissingMicroFrontendSessionError,
+  useMicroFrontendSession,
+} from './session/MicroFrontendSessionContext';
+export type { MicroFrontendSession, MicroFrontendSessionProviderProps } from './session/MicroFrontendSessionContext';
+export { useMicroFrontendSessions } from './session/useMicroFrontendSessions';
+export type { MicroFrontendSessionState } from './session/useMicroFrontendSessions';
+export { default as Portal } from './specs/PortalViewNativeComponent';
+export type {
+  AppRequest,
+  MicroFrontendAppProps,
+  MicroFrontendAdapter,
+  MicroFrontendBundle,
+  MicroFrontendBundleRequest,
+  MicroFrontendRuntimeApi,
+  MicroFrontendRuntimeEvent,
+  MicroFrontendRuntimeEventSubscription,
+  MicroFrontendSessionEvent,
+} from './types';
+export {
+  AppContainerNotFoundError,
+  ExposedModuleNotFoundError,
+  InvalidAppNameError,
+  InvalidAppRequestError,
+  InvalidNativeRuntimeEventError,
+} from './runtime/errors';

package/src/plugin/index.ts

@@ -0,0 +1,2 @@
+export { microFrontend } from './microFrontendPlugin';
+export type { MicroFrontendPluginOptions } from './types';