@gears-frontx/react 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/index.d.cts

@@ -585,32 +585,94 @@ declare function useMfeBridge(): ChildMfeBridge;
 /**
  * useSharedProperty Hook - Shared property subscription
  *
- * Subscribes to shared property updates from the host.
+ * Subscribes to shared property updates from the host, either through the
+ * ambient MfeProvider context or through an explicitly supplied bridge.
  *
  * React Layer: L3
  */
+
 /**
- * Hook for subscribing to a shared property.
- *
- * Subscribes to property updates from the host and returns the current value.
- * Must be used within a MfeProvider (i.e., inside an MFE component).
- *
- * NOTE: This hook provides the interface and uses useSyncExternalStore with a stub subscription.
- * Full bridge subscription should be implemented when bridge methods are available.
- *
- * @param _propertyTypeId - Type ID of the shared property to subscribe to (currently unused)
- * @returns Current property value
- *
- * @example
+ * Options for {@link useSharedProperty}.
+ */
+interface UseSharedPropertyOptions<T> {
+    /**
+     * Bridge to read the property from, bypassing `MfeContext`.
+     *
+     * Pass this when the calling component never mounts `MfeProvider` (for
+     * example, a component that receives its bridge directly as a prop or from
+     * a non-React entry point). When omitted, the hook falls back to the
+     * bridge from `MfeContext` and throws if no `MfeProvider` is mounted,
+     * matching the zero-argument form.
+     *
+     * `bridge` and `propertyTypeId` identify the subscription: changing either
+     * one unsubscribes from the old source and subscribes to the new one, and
+     * the returned value reflects the new source on the same render.
+     */
+    bridge?: ChildMfeBridge;
+    /**
+     * Value returned while the host has not published the property yet
+     * (`bridge.getProperty()` returns `undefined`).
+     *
+     * Only the `undefined` sentinel is substituted: a published `null` is a
+     * real value and is returned as-is. The host validates every published
+     * value against the property's schema before it reaches any MFE
+     * (`TypeSystemPlugin.register()` throws on a schema mismatch and the
+     * update is never stored or delivered), so no consumer-side filtering is
+     * needed -- `T` is simply the caller's declaration of that schema.
+     *
+     * `fallback` may be passed inline on every render; it does not affect the
+     * host subscription.
+     */
+    fallback?: T;
+}
+/**
+ * Subscribe to a shared property from the host.
+ *
+ * Two forms:
+ *
+ * 1. **Context form** -- `useSharedProperty(propertyTypeId)`. Reads the
+ *    bridge from `MfeContext` and throws if no `MfeProvider` is mounted.
+ * 2. **Options form** -- `useSharedProperty(propertyTypeId, options)`. Pass
+ *    `options.bridge` for components that never mount `MfeProvider`, and/or
+ *    `options.fallback` for a value to show until the host publishes one.
+ *    `options.bridge` may be omitted, in which case the hook still falls
+ *    back to `MfeContext`.
+ *
+ * Both forms read through `useSyncExternalStore`: the bridge is the store,
+ * `bridge.getProperty()` is the snapshot, so the first render already shows
+ * the host's current value, a publish between render and commit is picked
+ * up when React re-reads the snapshot after subscribing, and the value is
+ * tearing-protected under concurrent rendering.
+ *
+ * @param propertyTypeId - GTS type ID of the shared property to subscribe to
+ * @param options - Optional bridge override and fallback
+ * @returns The current property value; `T` when `options.fallback` is set,
+ *   otherwise `T | undefined`
+ *
+ * @example Context form (inside MfeProvider)
  * ```tsx
- * function MyMfeComponent() {
- *   const userData = useSharedProperty('gts.frontx.mfes.comm.shared_property.v1~myapp.user_data.v1');
+ * function ThemedComponent() {
+ *   const theme = useSharedProperty<{ primaryColor: string }>(THEME_PROPERTY_ID);
+ *   return <div style={{ color: theme?.primaryColor }} />;
+ * }
+ * ```
  *
- *   return <div>User: {userData?.name}</div>;
+ * @example Explicit bridge with fallback (no MfeProvider)
+ * ```tsx
+ * function StandaloneComponent({ bridge }: { bridge: ChildMfeBridge }) {
+ *   const label = useSharedProperty<string>(LABEL_PROPERTY_ID, {
+ *     bridge,
+ *     fallback: 'Untitled',
+ *   });
+ *   return <span>{label}</span>;
  * }
  * ```
  */
 declare function useSharedProperty<T = unknown>(propertyTypeId: string): T | undefined;
+declare function useSharedProperty<T>(propertyTypeId: string, options: UseSharedPropertyOptions<T> & {
+    fallback: T;
+}): T;
+declare function useSharedProperty<T = unknown>(propertyTypeId: string, options?: UseSharedPropertyOptions<T>): T | undefined;
 
 /**
  * useHostAction Hook - Host action requests
@@ -997,4 +1059,4 @@ interface EventPayloadMap extends EventPayloadMap$1 {
  */
 declare const eventBus: EventBus<EventPayloadMap>;
 
-export { type ApiInfiniteQueryOptions, type ApiInfiniteQueryPageContext, ApiInfiniteQueryResult, ApiMutationResult, type ApiQueryOverrides, ApiQueryResult, type ApiStreamOptions, type ApiStreamResult, ApiSuspenseInfiniteQueryResult, ApiSuspenseQueryResult, CanAccess, CanAccessProps, type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, FrontXContext, FrontXProvider, FrontXProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, MutationCallbackContext, QueryCache, ThemeAwareReactLifecycle, type UseApiMutationOptions, UseCanAccessResult, UseFormattersReturn, UseScreenTranslationsReturn, UseThemeReturn, UseTranslationReturn, eventBus, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiStream, useApiSuspenseInfiniteQuery, useApiSuspenseQuery, useAppDispatch, useAppSelector, useCanAccess, useDomainExtensions, useFormatters, useFrontX, useHostAction, useMfeBridge, useMountedExtensions, useQueryCache, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };
+export { type ApiInfiniteQueryOptions, type ApiInfiniteQueryPageContext, ApiInfiniteQueryResult, ApiMutationResult, type ApiQueryOverrides, ApiQueryResult, type ApiStreamOptions, type ApiStreamResult, ApiSuspenseInfiniteQueryResult, ApiSuspenseQueryResult, CanAccess, CanAccessProps, type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, FrontXContext, FrontXProvider, FrontXProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, MutationCallbackContext, QueryCache, ThemeAwareReactLifecycle, type UseApiMutationOptions, UseCanAccessResult, UseFormattersReturn, UseScreenTranslationsReturn, type UseSharedPropertyOptions, UseThemeReturn, UseTranslationReturn, eventBus, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiStream, useApiSuspenseInfiniteQuery, useApiSuspenseQuery, useAppDispatch, useAppSelector, useCanAccess, useDomainExtensions, useFormatters, useFrontX, useHostAction, useMfeBridge, useMountedExtensions, useQueryCache, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };

package/dist/index.d.ts

@@ -585,32 +585,94 @@ declare function useMfeBridge(): ChildMfeBridge;
 /**
  * useSharedProperty Hook - Shared property subscription
  *
- * Subscribes to shared property updates from the host.
+ * Subscribes to shared property updates from the host, either through the
+ * ambient MfeProvider context or through an explicitly supplied bridge.
  *
  * React Layer: L3
  */
+
 /**
- * Hook for subscribing to a shared property.
- *
- * Subscribes to property updates from the host and returns the current value.
- * Must be used within a MfeProvider (i.e., inside an MFE component).
- *
- * NOTE: This hook provides the interface and uses useSyncExternalStore with a stub subscription.
- * Full bridge subscription should be implemented when bridge methods are available.
- *
- * @param _propertyTypeId - Type ID of the shared property to subscribe to (currently unused)
- * @returns Current property value
- *
- * @example
+ * Options for {@link useSharedProperty}.
+ */
+interface UseSharedPropertyOptions<T> {
+    /**
+     * Bridge to read the property from, bypassing `MfeContext`.
+     *
+     * Pass this when the calling component never mounts `MfeProvider` (for
+     * example, a component that receives its bridge directly as a prop or from
+     * a non-React entry point). When omitted, the hook falls back to the
+     * bridge from `MfeContext` and throws if no `MfeProvider` is mounted,
+     * matching the zero-argument form.
+     *
+     * `bridge` and `propertyTypeId` identify the subscription: changing either
+     * one unsubscribes from the old source and subscribes to the new one, and
+     * the returned value reflects the new source on the same render.
+     */
+    bridge?: ChildMfeBridge;
+    /**
+     * Value returned while the host has not published the property yet
+     * (`bridge.getProperty()` returns `undefined`).
+     *
+     * Only the `undefined` sentinel is substituted: a published `null` is a
+     * real value and is returned as-is. The host validates every published
+     * value against the property's schema before it reaches any MFE
+     * (`TypeSystemPlugin.register()` throws on a schema mismatch and the
+     * update is never stored or delivered), so no consumer-side filtering is
+     * needed -- `T` is simply the caller's declaration of that schema.
+     *
+     * `fallback` may be passed inline on every render; it does not affect the
+     * host subscription.
+     */
+    fallback?: T;
+}
+/**
+ * Subscribe to a shared property from the host.
+ *
+ * Two forms:
+ *
+ * 1. **Context form** -- `useSharedProperty(propertyTypeId)`. Reads the
+ *    bridge from `MfeContext` and throws if no `MfeProvider` is mounted.
+ * 2. **Options form** -- `useSharedProperty(propertyTypeId, options)`. Pass
+ *    `options.bridge` for components that never mount `MfeProvider`, and/or
+ *    `options.fallback` for a value to show until the host publishes one.
+ *    `options.bridge` may be omitted, in which case the hook still falls
+ *    back to `MfeContext`.
+ *
+ * Both forms read through `useSyncExternalStore`: the bridge is the store,
+ * `bridge.getProperty()` is the snapshot, so the first render already shows
+ * the host's current value, a publish between render and commit is picked
+ * up when React re-reads the snapshot after subscribing, and the value is
+ * tearing-protected under concurrent rendering.
+ *
+ * @param propertyTypeId - GTS type ID of the shared property to subscribe to
+ * @param options - Optional bridge override and fallback
+ * @returns The current property value; `T` when `options.fallback` is set,
+ *   otherwise `T | undefined`
+ *
+ * @example Context form (inside MfeProvider)
  * ```tsx
- * function MyMfeComponent() {
- *   const userData = useSharedProperty('gts.frontx.mfes.comm.shared_property.v1~myapp.user_data.v1');
+ * function ThemedComponent() {
+ *   const theme = useSharedProperty<{ primaryColor: string }>(THEME_PROPERTY_ID);
+ *   return <div style={{ color: theme?.primaryColor }} />;
+ * }
+ * ```
  *
- *   return <div>User: {userData?.name}</div>;
+ * @example Explicit bridge with fallback (no MfeProvider)
+ * ```tsx
+ * function StandaloneComponent({ bridge }: { bridge: ChildMfeBridge }) {
+ *   const label = useSharedProperty<string>(LABEL_PROPERTY_ID, {
+ *     bridge,
+ *     fallback: 'Untitled',
+ *   });
+ *   return <span>{label}</span>;
  * }
  * ```
  */
 declare function useSharedProperty<T = unknown>(propertyTypeId: string): T | undefined;
+declare function useSharedProperty<T>(propertyTypeId: string, options: UseSharedPropertyOptions<T> & {
+    fallback: T;
+}): T;
+declare function useSharedProperty<T = unknown>(propertyTypeId: string, options?: UseSharedPropertyOptions<T>): T | undefined;
 
 /**
  * useHostAction Hook - Host action requests
@@ -997,4 +1059,4 @@ interface EventPayloadMap extends EventPayloadMap$1 {
  */
 declare const eventBus: EventBus<EventPayloadMap>;
 
-export { type ApiInfiniteQueryOptions, type ApiInfiniteQueryPageContext, ApiInfiniteQueryResult, ApiMutationResult, type ApiQueryOverrides, ApiQueryResult, type ApiStreamOptions, type ApiStreamResult, ApiSuspenseInfiniteQueryResult, ApiSuspenseQueryResult, CanAccess, CanAccessProps, type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, FrontXContext, FrontXProvider, FrontXProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, MutationCallbackContext, QueryCache, ThemeAwareReactLifecycle, type UseApiMutationOptions, UseCanAccessResult, UseFormattersReturn, UseScreenTranslationsReturn, UseThemeReturn, UseTranslationReturn, eventBus, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiStream, useApiSuspenseInfiniteQuery, useApiSuspenseQuery, useAppDispatch, useAppSelector, useCanAccess, useDomainExtensions, useFormatters, useFrontX, useHostAction, useMfeBridge, useMountedExtensions, useQueryCache, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };
+export { type ApiInfiniteQueryOptions, type ApiInfiniteQueryPageContext, ApiInfiniteQueryResult, ApiMutationResult, type ApiQueryOverrides, ApiQueryResult, type ApiStreamOptions, type ApiStreamResult, ApiSuspenseInfiniteQueryResult, ApiSuspenseQueryResult, CanAccess, CanAccessProps, type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, FrontXContext, FrontXProvider, FrontXProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, MutationCallbackContext, QueryCache, ThemeAwareReactLifecycle, type UseApiMutationOptions, UseCanAccessResult, UseFormattersReturn, UseScreenTranslationsReturn, type UseSharedPropertyOptions, UseThemeReturn, UseTranslationReturn, eventBus, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiStream, useApiSuspenseInfiniteQuery, useApiSuspenseQuery, useAppDispatch, useAppSelector, useCanAccess, useDomainExtensions, useFormatters, useFrontX, useHostAction, useMfeBridge, useMountedExtensions, useQueryCache, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };

package/dist/index.js

@@ -964,20 +964,27 @@ function useMfeBridge() {
 }
 
 // src/mfe/hooks/useSharedProperty.ts
-import { useSyncExternalStore as useSyncExternalStore4, useCallback as useCallback5 } from "react";
-function useSharedProperty(propertyTypeId) {
-  const { bridge } = useMfeContext();
-  const subscribe = useCallback5((callback) => {
-    return bridge.subscribeToProperty(propertyTypeId, () => {
-      callback();
-    });
-  }, [bridge, propertyTypeId]);
+import { useCallback as useCallback5, useContext as useContext4, useSyncExternalStore as useSyncExternalStore4 } from "react";
+function useSharedProperty(propertyTypeId, options) {
+  const contextValue = useContext4(MfeContext);
+  const bridge = options?.bridge ?? contextValue?.bridge;
+  const fallback = options?.fallback;
+  if (!bridge) {
+    throw new Error(
+      "useSharedProperty must be used within a MfeProvider, or given an explicit `bridge` option, for components that never mount MfeProvider."
+    );
+  }
+  const subscribe = useCallback5(
+    (onStoreChange) => bridge.subscribeToProperty(propertyTypeId, () => {
+      onStoreChange();
+    }),
+    [bridge, propertyTypeId]
+  );
   const getSnapshot = useCallback5(() => {
-    const property = bridge.getProperty(propertyTypeId);
-    return property?.value;
-  }, [bridge, propertyTypeId]);
-  const value = useSyncExternalStore4(subscribe, getSnapshot, getSnapshot);
-  return value;
+    const raw = bridge.getProperty(propertyTypeId)?.value;
+    return raw === void 0 ? fallback : raw;
+  }, [bridge, propertyTypeId, fallback]);
+  return useSyncExternalStore4(subscribe, getSnapshot, getSnapshot);
 }
 
 // src/mfe/hooks/useHostAction.ts