@hitachivantara/app-shell-services 1.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @hitachivantara/app-shell-services
+
+Hitachi Vantara App Shell Services. Support package to manage services at the App Shell ecosystem.
+
+## Overview
+
+This package provides service management capabilities including:
+
+- Service registration and resolution
+- React hooks for service consumption
+- Type-safe service interfaces
+
+## Usage
+
+Services supports a consumer/provider model where:
+
+- Consumers, like an app owning a header action for example, will consume a given service _contract_ either from the shared-services package from other app or, if also a provider, its own shared-services package. The services are identified by an `id` that, ideally, should be unique while also providing information about the type it expects like `main-app:AppsMetadata`. This way, the consumers know the type they expect and the providers know what to implement, without collisions in the multi-tenant App Shell ecosystem.
+- Providers implement services that match the consumer's contract and register them under the consumer's `id` in its `app-shell.config.ts` file as example below:
+
+```typescript
+services: {
+  "@some-package/main-app-services:AppsMetadata": [{
+    instance: {
+       value: {
+         name: "dummy app",
+         description: "This is 'dummy app' description",
+         version: 2.0,
+         final: false,
+       }
+    }
+  }],
+}
+```
+
+This way, looking at the configuration, it is clear that there is a consumer application (main-app) that expects service-providers to implement the `AppsMetadata` contract and register them under its `@some-package/main-app-services:AppsMetadata` service definition, keeping the consumer resilient: as long as service-providers adhere to the declared contract the consumer code will not break.
+
+## Example (consumer)
+
+Exploring the example above, the consumer should register the service contract and definition in a package that can be shared between the consumer and the provider:
+
+```typescript
+// @some-package/main-app-services
+export type AppsMetadata = {
+  appId: string;
+  appName: string;
+  version: number;
+  isRelease: boolean;
+};
+
+/**
+ * Service definitions that the consumer 'main app' exposes on a services shared package.
+ */
+export const MainAppServiceDefinitions = {
+  /**
+   * The {@const AppsMetadata} service represents the service-provider application metadata.
+   *
+   * The service-providers that implement this contract will have its implementation displayed on a page.
+   *
+   * Instances of this service are typescript constants of type {@link AppsMetadata}.
+   */
+  AppsMetadata: {
+    id: "@some-package/main-app-services:AppsMetadata",
+  },
+};
+```
+
+The main app consumes all the service definitions under its identifier using the `useServices` hook, which returns all the successfully loaded services of the requested identifier, namely the `MainAppServiceDefinitions.AppsMetadata` service definition.
+This way, as long as any provider implements and registers a service that matches the `AppsMetadata` contract, it will be safe to render as expected:
+
+```typescript
+const AboutApps: FC = () => {
+  const { services: appsMetadata[], isPending, error } = useServices<AppsMetadata[]>(
+    ServiceDefinitions.AppsMetadata.id,
+  );
+
+  if (isPending) {
+    return <HvLoading>Loading apps metadata from services...</HvLoading>;
+  }
+
+  if (error) {
+    const errorMessage = `Failed to apps metadata: ${ServiceDefinitions.AppsMetadata.id}`;
+    return <HvTypography>{errorMessage}</HvTypography>;
+  }
+
+  return (
+    <HvContainer maxWidth="lg">
+      <HvTypography variant="title1">Applications information</HvTypography>
+      <HvGrid container spacing={3}>
+        {appsMetadata.map((metadata, index) => {
+          return (
+            <HvGrid item key={metadata.appId}>
+              <HvTypography>
+                <strong>Application: </strong> {metadata.appName}
+              </HvTypography>
+              <HvTypography>
+                {metadata.version} - {metadata.isRelease ? "Release" : "In development"}
+              </HvTypography>
+            </HvGrid>
+          );
+        })}
+      </HvGrid>
+    </HvContainer>
+  );
+};
+```
+
+## Example (provider)
+
+A simple way to implement a service-provider that matches the `AppsMetadata` contract is a constant like below:
+
+```typescript
+import { AppsMetadata } from "@some-package/main-app-services";
+
+const dummyAppMetadata: AppsMetadata = {
+  appId: "ProviderApp",
+  appName: "A provider app",
+  version: 1.0,
+  isRelease: true,
+};
+```
+
+and having it registered on its `app-shell.config.ts` file, under the consumer service identifier.
+
+```typescript
+  //...
+  services: {
+    "@some-package/main-app-services:AppsMetadata": [
+      {
+        instance: {
+          bundle: "dummy-app/metadata/dummyAppMetadata.js",
+        },
+        ranking: 100,
+      }
+    ],
+  },
+  //...
+```
+
+### More examples
+
+To see more examples, please check the [Default App](../../apps/default-app) `ServicesDemo` page and the `app-shell.config.ts` file.
+
+## Installation
+
+The App Shell Services is available as an NPM package, and can be installed with:
+
+```bash
+npm install @hitachivantara/app-shell-services
+```

package/dist/bundles/app-shell-services.esm.js

@@ -0,0 +1,347 @@
+import { useState, useEffect, createContext, useMemo, useContext, useCallback, useRef } from "react";
+import { isEqual, cloneDeep } from "lodash";
+import { jsx } from "react/jsx-runtime";
+function useAsync(promiseFactory, options) {
+  const dataProp = options?.dataProp ?? "data";
+  const pendingData = options?.pendingData;
+  const [data, setData] = useState(
+    pendingData
+  );
+  const [error, setError] = useState(null);
+  const [isPending, setIsPending] = useState(true);
+  useEffect(() => {
+    let isMounted = true;
+    promiseFactory().then((result) => {
+      if (isMounted) {
+        setData(() => result);
+        setError(null);
+        setIsPending(false);
+      }
+    }).catch((err) => {
+      if (isMounted) {
+        setError(err);
+        setData(void 0);
+        setIsPending(false);
+      }
+    });
+    return () => {
+      isMounted = false;
+    };
+  }, [promiseFactory]);
+  if (error) {
+    return {
+      isPending: false,
+      error,
+      [dataProp]: void 0
+    };
+  }
+  if (isPending) {
+    return {
+      isPending: true,
+      error: null,
+      [dataProp]: pendingData
+    };
+  }
+  return {
+    isPending: false,
+    error: null,
+    [dataProp]: data
+  };
+}
+function createServiceReferenceBase(serviceId, serviceConfig, getService) {
+  return {
+    serviceId,
+    ranking: serviceConfig.ranking ?? 0,
+    getService
+  };
+}
+function validateImportedModule(imported, serviceId, bundlePath) {
+  if (!imported) {
+    throw new Error(
+      `Bundle import failed for ${bundlePath} and service ${serviceId}`
+    );
+  }
+  if (typeof imported === "object" && "default" in imported && imported.default != null) {
+    return imported.default;
+  }
+  throw new Error(
+    `ESM default export missing for ${bundlePath} (service ${serviceId}). Ensure the module uses a default export.`
+  );
+}
+function selectValueOrBundle(provider, serviceId, kind) {
+  const hasValue = "value" in provider && provider.value !== void 0;
+  const hasBundle = "bundle" in provider && typeof provider.bundle === "string";
+  if (hasValue) {
+    if (hasBundle) {
+      console.warn(
+        `${kind} service config for ${serviceId} contains both 'value' and 'bundle'. 'value' takes precedence and 'bundle' will be ignored.`
+      );
+    }
+    return { mode: "value", value: provider.value };
+  }
+  if (hasBundle) {
+    return { mode: "bundle", bundle: provider.bundle, config: provider.config };
+  }
+  throw new Error(`Invalid ${kind} service config for ${serviceId}`);
+}
+function createInstanceReference(serviceId, config) {
+  const selection = selectValueOrBundle(
+    config.instance,
+    serviceId,
+    "instance"
+  );
+  const serviceLoader = async () => {
+    if (selection.mode === "value") {
+      return selection.value;
+    }
+    const imported = await import(
+      /* @vite-ignore */
+      selection.bundle
+    );
+    return validateImportedModule(
+      imported,
+      serviceId,
+      selection.bundle
+    );
+  };
+  return createServiceReferenceBase(serviceId, config, serviceLoader);
+}
+function createFactoryReference(serviceId, config) {
+  let loaded = false;
+  let serviceInstance;
+  const selection = selectValueOrBundle(
+    config.factory,
+    serviceId,
+    "factory"
+  );
+  const serviceLoader = async () => {
+    if (!loaded) {
+      let factoryExport;
+      let providedConfig;
+      if (selection.mode === "value") {
+        factoryExport = selection.value;
+      } else {
+        const imported = await import(
+          /* @vite-ignore */
+          selection.bundle
+        );
+        factoryExport = validateImportedModule(
+          imported,
+          serviceId,
+          selection.bundle
+        );
+        providedConfig = selection.config;
+      }
+      if (typeof factoryExport !== "function") {
+        throw new Error(
+          `Factory service for ${serviceId} did not resolve to a function. Value: ${factoryExport}`
+        );
+      }
+      const factoryFn = factoryExport;
+      serviceInstance = factoryFn(providedConfig);
+      loaded = true;
+    }
+    return serviceInstance;
+  };
+  return createServiceReferenceBase(serviceId, config, serviceLoader);
+}
+function createComponentReference(serviceId, config) {
+  let loaded = false;
+  let serviceInstance;
+  const selection = selectValueOrBundle(
+    config.component,
+    serviceId,
+    "component"
+  );
+  const serviceLoader = async () => {
+    if (!loaded) {
+      let componentExport;
+      let providedConfig;
+      if (selection.mode === "value") {
+        componentExport = selection.value;
+      } else {
+        const imported = await import(
+          /* @vite-ignore */
+          selection.bundle
+        );
+        componentExport = validateImportedModule(
+          imported,
+          serviceId,
+          selection.bundle
+        );
+        providedConfig = selection.config;
+      }
+      if (typeof componentExport !== "function") {
+        throw new Error(
+          `Component definition for service ${serviceId} is not a React component function`
+        );
+      }
+      serviceInstance = bindComponent(
+        componentExport,
+        providedConfig ?? {}
+      );
+      loaded = true;
+    }
+    return serviceInstance;
+  };
+  return createServiceReferenceBase(serviceId, config, serviceLoader);
+}
+function createServiceReference(serviceId, serviceConfig) {
+  if ("instance" in serviceConfig) {
+    return createInstanceReference(serviceId, serviceConfig);
+  }
+  if ("factory" in serviceConfig) {
+    return createFactoryReference(serviceId, serviceConfig);
+  }
+  if ("component" in serviceConfig) {
+    return createComponentReference(
+      serviceId,
+      serviceConfig
+    );
+  }
+  throw new Error(
+    `Unsupported service provider configuration for service ${serviceId}`
+  );
+}
+function bindComponent(Component, configProps) {
+  const BoundComponent = (props) => {
+    const mergedProps = { ...configProps, ...props };
+    return /* @__PURE__ */ jsx(Component, { ...mergedProps });
+  };
+  return BoundComponent;
+}
+function createServiceReferenceMap(services = {}) {
+  return Object.entries(services).reduce(
+    (map, [serviceId, serviceConfigs]) => {
+      const serviceReferences = serviceConfigs.map(
+        (serviceConfig) => createServiceReference(serviceId, serviceConfig)
+      ).sort((a, b) => b.ranking - a.ranking);
+      map.set(serviceId, serviceReferences);
+      return map;
+    },
+    /* @__PURE__ */ new Map()
+  );
+}
+function createServiceManager({
+  services
+}) {
+  const serviceReferenceMap = createServiceReferenceMap(services);
+  function queryServiceReferences(serviceId, _options) {
+    return serviceReferenceMap.get(serviceId) ?? [];
+  }
+  function queryServiceReference(serviceId, options) {
+    const references = queryServiceReferences(serviceId);
+    if (references.length === 0) {
+      throw new Error(`Service ${serviceId} has no service providers.`);
+    }
+    return references[0];
+  }
+  return {
+    getServiceReference(serviceId, options) {
+      return queryServiceReference(serviceId);
+    },
+    getServiceReferences(serviceId, options) {
+      return queryServiceReferences(serviceId);
+    },
+    async getService(serviceId, options) {
+      const reference = queryServiceReference(serviceId);
+      return reference.getService();
+    },
+    async getServices(serviceId, options) {
+      const references = queryServiceReferences(serviceId);
+      if (references.length === 0) {
+        return [];
+      }
+      const errorHandling = options?.errorHandling ?? "reject-on-all-failures";
+      const results = await Promise.allSettled(
+        references.map((reference) => reference.getService())
+      );
+      const successful = [];
+      const errors = [];
+      results.forEach((result) => {
+        if (result.status === "fulfilled") {
+          successful.push(result.value);
+        } else {
+          errors.push(
+            result.reason instanceof Error ? result.reason : new Error(String(result.reason))
+          );
+        }
+      });
+      switch (errorHandling) {
+        case "reject-on-any-failure":
+          if (errors.length > 0) {
+            throw errors[0];
+          }
+          break;
+        case "reject-on-all-failures":
+          if (errors.length === results.length) {
+            throw new Error(
+              `All service providers failed for service '${serviceId}'. First error: ${errors[0].message}`
+            );
+          }
+          break;
+      }
+      return successful;
+    }
+  };
+}
+const ServicesContext = createContext(
+  void 0
+);
+const ServiceManagerProvider = ({ config, children }) => {
+  const serviceManager = useMemo(() => createServiceManager(config), [config]);
+  return /* @__PURE__ */ jsx(ServicesContext.Provider, { value: serviceManager, children });
+};
+const useServicesContext = () => {
+  const context = useContext(ServicesContext);
+  if (!context) {
+    throw new Error(
+      "useServicesContext must be used within an ServiceManagerProvider"
+    );
+  }
+  return context;
+};
+function useDeepMemo(value) {
+  const ref = useRef();
+  if (!isEqual(value, ref.current)) {
+    ref.current = cloneDeep(value);
+  }
+  return ref.current;
+}
+function useService(serviceIdOrRef, options) {
+  const { getService } = useServicesContext();
+  const opts = useDeepMemo(options || {});
+  const promiseFactory = useCallback(
+    () => isServiceReference(serviceIdOrRef) ? serviceIdOrRef.getService() : getService(serviceIdOrRef, opts),
+    [serviceIdOrRef, getService, opts]
+  );
+  return useAsync(promiseFactory, { dataProp: "service" });
+}
+function useServices(serviceId, options) {
+  const { getServices } = useServicesContext();
+  const opts = useDeepMemo(options || {});
+  const promiseFactory = useCallback(
+    () => getServices(serviceId, opts),
+    [getServices, serviceId, opts]
+  );
+  return useAsync(promiseFactory, { dataProp: "services", pendingData: [] });
+}
+function useServiceReference(serviceId, options = {}) {
+  const { getServiceReference } = useServicesContext();
+  return getServiceReference(serviceId, options);
+}
+function useServiceReferences(serviceId, options = {}) {
+  const { getServiceReferences } = useServicesContext();
+  return getServiceReferences(serviceId, options);
+}
+function isServiceReference(value) {
+  return !!value && typeof value === "object" && typeof value.getService === "function";
+}
+export {
+  ServiceManagerProvider as default,
+  useService,
+  useServiceReference,
+  useServiceReferences,
+  useServices,
+  useServicesContext
+};

package/dist/esm/hooks/Hooks.js

@@ -0,0 +1,46 @@
+import { useCallback, useRef } from "react";
+import { isEqual, cloneDeep } from "lodash";
+import { useAsync } from "./useAsync.js";
+import { useServicesContext } from "./useServicesContext.js";
+function useDeepMemo(value) {
+  const ref = useRef();
+  if (!isEqual(value, ref.current)) {
+    ref.current = cloneDeep(value);
+  }
+  return ref.current;
+}
+function useService(serviceIdOrRef, options) {
+  const { getService } = useServicesContext();
+  const opts = useDeepMemo(options || {});
+  const promiseFactory = useCallback(
+    () => isServiceReference(serviceIdOrRef) ? serviceIdOrRef.getService() : getService(serviceIdOrRef, opts),
+    [serviceIdOrRef, getService, opts]
+  );
+  return useAsync(promiseFactory, { dataProp: "service" });
+}
+function useServices(serviceId, options) {
+  const { getServices } = useServicesContext();
+  const opts = useDeepMemo(options || {});
+  const promiseFactory = useCallback(
+    () => getServices(serviceId, opts),
+    [getServices, serviceId, opts]
+  );
+  return useAsync(promiseFactory, { dataProp: "services", pendingData: [] });
+}
+function useServiceReference(serviceId, options = {}) {
+  const { getServiceReference } = useServicesContext();
+  return getServiceReference(serviceId, options);
+}
+function useServiceReferences(serviceId, options = {}) {
+  const { getServiceReferences } = useServicesContext();
+  return getServiceReferences(serviceId, options);
+}
+function isServiceReference(value) {
+  return !!value && typeof value === "object" && typeof value.getService === "function";
+}
+export {
+  useService,
+  useServiceReference,
+  useServiceReferences,
+  useServices
+};

package/dist/esm/hooks/useAsync.js

@@ -0,0 +1,51 @@
+import { useState, useEffect } from "react";
+function useAsync(promiseFactory, options) {
+  const dataProp = options?.dataProp ?? "data";
+  const pendingData = options?.pendingData;
+  const [data, setData] = useState(
+    pendingData
+  );
+  const [error, setError] = useState(null);
+  const [isPending, setIsPending] = useState(true);
+  useEffect(() => {
+    let isMounted = true;
+    promiseFactory().then((result) => {
+      if (isMounted) {
+        setData(() => result);
+        setError(null);
+        setIsPending(false);
+      }
+    }).catch((err) => {
+      if (isMounted) {
+        setError(err);
+        setData(void 0);
+        setIsPending(false);
+      }
+    });
+    return () => {
+      isMounted = false;
+    };
+  }, [promiseFactory]);
+  if (error) {
+    return {
+      isPending: false,
+      error,
+      [dataProp]: void 0
+    };
+  }
+  if (isPending) {
+    return {
+      isPending: true,
+      error: null,
+      [dataProp]: pendingData
+    };
+  }
+  return {
+    isPending: false,
+    error: null,
+    [dataProp]: data
+  };
+}
+export {
+  useAsync
+};

package/dist/esm/hooks/useServicesContext.js

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { ServicesContext } from "../providers/ServiceManagerProvider.js";
+const useServicesContext = () => {
+  const context = useContext(ServicesContext);
+  if (!context) {
+    throw new Error(
+      "useServicesContext must be used within an ServiceManagerProvider"
+    );
+  }
+  return context;
+};
+export {
+  useServicesContext
+};

package/dist/esm/index.js

@@ -0,0 +1,11 @@
+import { useService, useServiceReference, useServiceReferences, useServices } from "./hooks/Hooks.js";
+import { useServicesContext } from "./hooks/useServicesContext.js";
+import { default as default2 } from "./providers/ServiceManagerProvider.js";
+export {
+  default2 as default,
+  useService,
+  useServiceReference,
+  useServiceReferences,
+  useServices,
+  useServicesContext
+};

package/dist/esm/providers/ServiceManagerProvider.js

@@ -0,0 +1,89 @@
+import { jsx } from "react/jsx-runtime";
+import { createContext, useMemo } from "react";
+import { createServiceReference } from "../utils/serviceReference.js";
+function createServiceReferenceMap(services = {}) {
+  return Object.entries(services).reduce(
+    (map, [serviceId, serviceConfigs]) => {
+      const serviceReferences = serviceConfigs.map(
+        (serviceConfig) => createServiceReference(serviceId, serviceConfig)
+      ).sort((a, b) => b.ranking - a.ranking);
+      map.set(serviceId, serviceReferences);
+      return map;
+    },
+    /* @__PURE__ */ new Map()
+  );
+}
+function createServiceManager({
+  services
+}) {
+  const serviceReferenceMap = createServiceReferenceMap(services);
+  function queryServiceReferences(serviceId, _options) {
+    return serviceReferenceMap.get(serviceId) ?? [];
+  }
+  function queryServiceReference(serviceId, options) {
+    const references = queryServiceReferences(serviceId);
+    if (references.length === 0) {
+      throw new Error(`Service ${serviceId} has no service providers.`);
+    }
+    return references[0];
+  }
+  return {
+    getServiceReference(serviceId, options) {
+      return queryServiceReference(serviceId);
+    },
+    getServiceReferences(serviceId, options) {
+      return queryServiceReferences(serviceId);
+    },
+    async getService(serviceId, options) {
+      const reference = queryServiceReference(serviceId);
+      return reference.getService();
+    },
+    async getServices(serviceId, options) {
+      const references = queryServiceReferences(serviceId);
+      if (references.length === 0) {
+        return [];
+      }
+      const errorHandling = options?.errorHandling ?? "reject-on-all-failures";
+      const results = await Promise.allSettled(
+        references.map((reference) => reference.getService())
+      );
+      const successful = [];
+      const errors = [];
+      results.forEach((result) => {
+        if (result.status === "fulfilled") {
+          successful.push(result.value);
+        } else {
+          errors.push(
+            result.reason instanceof Error ? result.reason : new Error(String(result.reason))
+          );
+        }
+      });
+      switch (errorHandling) {
+        case "reject-on-any-failure":
+          if (errors.length > 0) {
+            throw errors[0];
+          }
+          break;
+        case "reject-on-all-failures":
+          if (errors.length === results.length) {
+            throw new Error(
+              `All service providers failed for service '${serviceId}'. First error: ${errors[0].message}`
+            );
+          }
+          break;
+      }
+      return successful;
+    }
+  };
+}
+const ServicesContext = createContext(
+  void 0
+);
+const ServiceManagerProvider = ({ config, children }) => {
+  const serviceManager = useMemo(() => createServiceManager(config), [config]);
+  return /* @__PURE__ */ jsx(ServicesContext.Provider, { value: serviceManager, children });
+};
+export {
+  ServicesContext,
+  ServiceManagerProvider as default
+};

package/dist/esm/utils/serviceReference.js

@@ -0,0 +1,166 @@
+import { jsx } from "react/jsx-runtime";
+function createServiceReferenceBase(serviceId, serviceConfig, getService) {
+  return {
+    serviceId,
+    ranking: serviceConfig.ranking ?? 0,
+    getService
+  };
+}
+function validateImportedModule(imported, serviceId, bundlePath) {
+  if (!imported) {
+    throw new Error(
+      `Bundle import failed for ${bundlePath} and service ${serviceId}`
+    );
+  }
+  if (typeof imported === "object" && "default" in imported && imported.default != null) {
+    return imported.default;
+  }
+  throw new Error(
+    `ESM default export missing for ${bundlePath} (service ${serviceId}). Ensure the module uses a default export.`
+  );
+}
+function selectValueOrBundle(provider, serviceId, kind) {
+  const hasValue = "value" in provider && provider.value !== void 0;
+  const hasBundle = "bundle" in provider && typeof provider.bundle === "string";
+  if (hasValue) {
+    if (hasBundle) {
+      console.warn(
+        `${kind} service config for ${serviceId} contains both 'value' and 'bundle'. 'value' takes precedence and 'bundle' will be ignored.`
+      );
+    }
+    return { mode: "value", value: provider.value };
+  }
+  if (hasBundle) {
+    return { mode: "bundle", bundle: provider.bundle, config: provider.config };
+  }
+  throw new Error(`Invalid ${kind} service config for ${serviceId}`);
+}
+function createInstanceReference(serviceId, config) {
+  const selection = selectValueOrBundle(
+    config.instance,
+    serviceId,
+    "instance"
+  );
+  const serviceLoader = async () => {
+    if (selection.mode === "value") {
+      return selection.value;
+    }
+    const imported = await import(
+      /* @vite-ignore */
+      selection.bundle
+    );
+    return validateImportedModule(
+      imported,
+      serviceId,
+      selection.bundle
+    );
+  };
+  return createServiceReferenceBase(serviceId, config, serviceLoader);
+}
+function createFactoryReference(serviceId, config) {
+  let loaded = false;
+  let serviceInstance;
+  const selection = selectValueOrBundle(
+    config.factory,
+    serviceId,
+    "factory"
+  );
+  const serviceLoader = async () => {
+    if (!loaded) {
+      let factoryExport;
+      let providedConfig;
+      if (selection.mode === "value") {
+        factoryExport = selection.value;
+      } else {
+        const imported = await import(
+          /* @vite-ignore */
+          selection.bundle
+        );
+        factoryExport = validateImportedModule(
+          imported,
+          serviceId,
+          selection.bundle
+        );
+        providedConfig = selection.config;
+      }
+      if (typeof factoryExport !== "function") {
+        throw new Error(
+          `Factory service for ${serviceId} did not resolve to a function. Value: ${factoryExport}`
+        );
+      }
+      const factoryFn = factoryExport;
+      serviceInstance = factoryFn(providedConfig);
+      loaded = true;
+    }
+    return serviceInstance;
+  };
+  return createServiceReferenceBase(serviceId, config, serviceLoader);
+}
+function createComponentReference(serviceId, config) {
+  let loaded = false;
+  let serviceInstance;
+  const selection = selectValueOrBundle(
+    config.component,
+    serviceId,
+    "component"
+  );
+  const serviceLoader = async () => {
+    if (!loaded) {
+      let componentExport;
+      let providedConfig;
+      if (selection.mode === "value") {
+        componentExport = selection.value;
+      } else {
+        const imported = await import(
+          /* @vite-ignore */
+          selection.bundle
+        );
+        componentExport = validateImportedModule(
+          imported,
+          serviceId,
+          selection.bundle
+        );
+        providedConfig = selection.config;
+      }
+      if (typeof componentExport !== "function") {
+        throw new Error(
+          `Component definition for service ${serviceId} is not a React component function`
+        );
+      }
+      serviceInstance = bindComponent(
+        componentExport,
+        providedConfig ?? {}
+      );
+      loaded = true;
+    }
+    return serviceInstance;
+  };
+  return createServiceReferenceBase(serviceId, config, serviceLoader);
+}
+function createServiceReference(serviceId, serviceConfig) {
+  if ("instance" in serviceConfig) {
+    return createInstanceReference(serviceId, serviceConfig);
+  }
+  if ("factory" in serviceConfig) {
+    return createFactoryReference(serviceId, serviceConfig);
+  }
+  if ("component" in serviceConfig) {
+    return createComponentReference(
+      serviceId,
+      serviceConfig
+    );
+  }
+  throw new Error(
+    `Unsupported service provider configuration for service ${serviceId}`
+  );
+}
+function bindComponent(Component, configProps) {
+  const BoundComponent = (props) => {
+    const mergedProps = { ...configProps, ...props };
+    return /* @__PURE__ */ jsx(Component, { ...mergedProps });
+  };
+  return BoundComponent;
+}
+export {
+  createServiceReference
+};

package/dist/types/index.d.ts

@@ -0,0 +1,249 @@
+import { FC } from 'react';
+import { PropsWithChildren } from 'react';
+import { ServiceManager as ServiceManager_2 } from '..';
+
+/** Bundle for lazy loading */
+export declare type Bundle = {
+    bundle: string;
+};
+
+export declare type BundleConfig = Record<string, unknown>;
+
+export declare type ComponentServiceConfig = ServiceConfigBase & {
+    component: ComponentValueOrBundle;
+};
+
+export declare type ComponentValueOrBundle<TBundleConfig = BundleConfig> = Value | (Bundle & {
+    config?: TBundleConfig;
+});
+
+export declare type ErrorBase = NonNullable<unknown>;
+
+export declare type FactoryExport<TService = unknown, TConfig = BundleConfig> = FactoryServiceFunction<TService, TConfig>;
+
+export declare type FactoryServiceConfig = ServiceConfigBase & {
+    factory: FactoryValueOrBundle;
+};
+
+export declare type FactoryServiceFunction<TService = unknown, TConfig = BundleConfig> = (config?: TConfig) => TService;
+
+export declare type FactoryValueOrBundle<TBundleConfig = BundleConfig> = {
+    value: FactoryServiceFunction;
+} | (Bundle & {
+    config?: TBundleConfig;
+});
+
+/**
+ * Base options for service operations.
+ * Used as a foundation for more specific service option types.
+ */
+export declare type GetServiceBaseOptions = {};
+
+/**
+ * Options when getting a single service.
+ */
+export declare type GetServiceOptions = GetServiceBaseOptions;
+
+/**
+ * Options when getting a service reference.
+ */
+export declare type GetServiceReferenceOptions = GetServiceBaseOptions;
+
+/**
+ * Options when getting multiple service references.
+ */
+export declare type GetServiceReferencesOptions = GetServiceBaseOptions;
+
+/**
+ * Options when getting multiple services, with error handling configuration.
+ */
+export declare type GetServicesOptions = GetServiceBaseOptions & {
+    errorHandling?: ServicesErrorHandling;
+};
+
+export declare type InstanceServiceConfig = ServiceConfigBase & {
+    instance: InstanceValueOrBundle;
+};
+
+export declare type InstanceValueOrBundle = Value | Bundle;
+
+export declare type PropertyWithName<K extends string, T> = {
+    [P in K]: T;
+};
+
+declare interface Props extends PropsWithChildren {
+    config: ServiceManagerConfig;
+}
+
+/**
+ * A service configuration can be one of several kinds (instance, factory, component),
+ * each of which supports two declaration modes:
+ *  - Value: directly provide the instance, factory or component
+ *  - Bundle: module to be lazy loaded with optional config object
+ */
+export declare type ServiceConfig = InstanceServiceConfig | FactoryServiceConfig | ComponentServiceConfig;
+
+export declare type ServiceConfigBase = {
+    ranking?: number;
+};
+
+export declare type ServiceId = string;
+
+/**
+ * Loader function type for asynchronously loading of a service that returns a promise resolving to the service instance.
+ */
+export declare type ServiceLoader<TService> = () => Promise<TService>;
+
+export declare type ServiceManager = {
+    /**
+     * Accepts a service ID and optional options. Returns a promise resolving to the highest-ranked service instance, or rejects if resolution fails.
+     */
+    getService<TService>(serviceId: ServiceId, options?: GetServiceOptions): Promise<TService>;
+    /**
+     * Accepts a service ID and optional options. Returns a promise resolving to all successfully resolved service instances, following the error handling strategy.
+     */
+    getServices<TService>(serviceId: ServiceId, options?: GetServicesOptions): Promise<TService[]>;
+    /**
+     * Accepts a service ID and optional options. Returns a reference to the highest-ranked service.
+     */
+    getServiceReference<TService>(serviceId: ServiceId, options?: GetServiceReferenceOptions): ServiceReference<TService>;
+    /**
+     * Accepts a service ID and optional options. Returns all service references for the ID, sorted by descending ranking.
+     */
+    getServiceReferences<TService>(serviceId: ServiceId, options?: GetServiceReferencesOptions): ServiceReference<TService>[];
+};
+
+declare type ServiceManagerConfig = {
+    services?: ServicesConfig;
+};
+
+declare const ServiceManagerProvider: FC<Props>;
+export default ServiceManagerProvider;
+
+/**
+ * Reference to a service, including metadata and a loader function.
+ * Can be used to access service details and also resolve its service instance.
+ */
+export declare type ServiceReference<TService = unknown> = {
+    serviceId: ServiceId;
+    ranking: number;
+    getService(): Promise<TService>;
+};
+
+export declare type ServicesConfig = Record<ServiceId, ServiceConfig[]>;
+
+/**
+ * Error handling strategies that determine how errors are managed when loading services:
+ * - "reject-on-any-failure": Rejects if any service resolution fails (use for critical services);
+ * - "reject-on-all-failures" (default): Only rejects if all service resolutions fail (optimistic approach);
+ * - "ignore-failures": Never rejects, returns only successfully resolved services.
+ */
+export declare type ServicesErrorHandling = "reject-on-any-failure" | "reject-on-all-failures" | "ignore-failures";
+
+export declare type UseAsyncBaseResult<TData, TError extends ErrorBase = Error, TDataProp extends string = "data", TDataPending extends TData | undefined = undefined> = {
+    isPending: boolean;
+    error: TError | null;
+} & PropertyWithName<TDataProp, TData | TDataPending | undefined>;
+
+export declare type UseAsyncErrorResult<TData, TError extends ErrorBase = Error, TDataProp extends string = "data", TDataPending extends TData | undefined = undefined> = UseAsyncBaseResult<TData, TError, TDataProp, TDataPending> & {
+    isPending: false;
+    error: TError;
+} & PropertyWithName<TDataProp, undefined>;
+
+export declare type UseAsyncPendingResult<TData, TError extends ErrorBase = Error, TDataProp extends string = "data", TDataPending extends TData | undefined = undefined> = UseAsyncBaseResult<TData, TError, TDataProp> & {
+    isPending: true;
+    error: null;
+} & PropertyWithName<TDataProp, TDataPending>;
+
+export declare type UseAsyncResult<TData, TError extends ErrorBase = Error, TDataProp extends string = "data", TDataPending extends TData | undefined = undefined> = UseAsyncPendingResult<TData, TError, TDataProp, TDataPending> | UseAsyncErrorResult<TData, TError, TDataProp, TDataPending> | UseAsyncSuccessResult<TData, TError, TDataProp, TDataPending>;
+
+export declare type UseAsyncSuccessResult<TData, TError extends ErrorBase = Error, TDataProp extends string = "data", TDataPending extends TData | undefined = undefined> = UseAsyncBaseResult<TData, TError, TDataProp, TDataPending> & {
+    isPending: false;
+    error: null;
+} & PropertyWithName<TDataProp, TData>;
+
+/**
+ * Resolves and returns the service instance for a given service id or reference.
+ *
+ * Overloads:
+ * - useService<TService>(serviceReference: ServiceReference<TService>): UseServiceResult<TService>
+ * - useService<TService>(serviceId: ServiceId, options?: UseServiceOptions): UseServiceResult<TService>
+ *
+ * @param serviceReference - A {@link ServiceReference} object to resolve to a service instance.
+ * @param serviceId - The identifier of the service to resolve.
+ * @param options - Options to control service resolution.
+ * @returns A {@link UseServiceResult} object representing the loading state, error, and resolved service instance.
+ *
+ * When called with a {@link ServiceReference}, resolves that reference using its getService().
+ * When called with a {@link ServiceId}, resolves and returns the highest-ranked service instance for that id.
+ * If resolution fails, the error is available in the result.
+ */
+export declare function useService<TService>(serviceReference: ServiceReference<TService>): UseServiceResult<TService>;
+
+export declare function useService<TService>(serviceId: ServiceId, options?: UseServiceOptions): UseServiceResult<TService>;
+
+/**
+ * Options to control service resolution
+ */
+export declare type UseServiceOptions = GetServiceOptions;
+
+/**
+ * Gets the highest-ranked service reference for the given id.
+ *
+ * @param serviceId - The identifier of the service to get a reference for.
+ * @param options - Options to control the service reference to return.
+ * @returns A {@link ServiceReference} object.
+ */
+export declare function useServiceReference<TService>(serviceId: ServiceId, options?: UseServiceReferenceOptions): ServiceReference<TService>;
+
+/**
+ * Options to control the service reference to return.
+ */
+export declare type UseServiceReferenceOptions = GetServiceReferenceOptions;
+
+/**
+ * Gets all service references for the given service id, sorted by descending ranking.
+ *
+ * @param serviceId - The identifier of the service to get references for.
+ * @param options - Options to control the service references to return.
+ * @returns An array of {@link ServiceReference} objects.
+ */
+export declare function useServiceReferences<TService>(serviceId: ServiceId, options?: UseServiceReferencesOptions): ServiceReference<TService>[];
+
+/**
+ * Options to control the service references to return.
+ */
+export declare type UseServiceReferencesOptions = GetServiceReferencesOptions;
+
+/**
+ * Result type for the {@link useService} hook that represents the async state of a single service fetch operation.
+ */
+export declare type UseServiceResult<TService> = UseAsyncResult<TService, Error, "service">;
+
+/**
+ * Gets all service instances for a given service id.
+ *
+ * @param serviceId - The identifier of the services to resolve.
+ * @param options - Options to control services resolution, like error handling strategy.
+ * @returns A {@link UseServicesResult} object representing the loading state, error, and resolved array of service instances.
+ */
+export declare function useServices<TService>(serviceId: ServiceId, options?: UseServicesOptions): UseServicesResult<TService>;
+
+export declare const useServicesContext: () => ServiceManager_2;
+
+/**
+ * Options to control services resolution, like error handling strategy.
+ */
+export declare type UseServicesOptions = GetServicesOptions;
+
+/**
+ * Result type for the {@link useServices} hook that represents the async state of fetching multiple services.
+ */
+export declare type UseServicesResult<TService> = UseAsyncResult<TService[], Error, "services", TService[]>;
+
+/** Directly provided value */
+export declare type Value = {
+    value: unknown;
+};
+
+export { }

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@hitachivantara/app-shell-services",
+  "version": "1.1.0",
+  "type": "module",
+  "private": false,
+  "author": "Hitachi Vantara UI Kit Team",
+  "description": "AppShell Services",
+  "homepage": "https://github.com/lumada-design/hv-uikit-react",
+  "sideEffects": false,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lumada-design/hv-uikit-react.git",
+    "directory": "packages/app-shell-services"
+  },
+  "bugs": "https://github.com/lumada-design/hv-uikit-react/issues",
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json",
+    "./bundles/*": "./dist/bundles/*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "package"
+  },
+  "gitHead": "18bba1bbe7a6ecddfcb9f56d1613c547bfd0e6d7",
+  "types": "./dist/types/index.d.ts",
+  "module": "dist/esm/index.js"
+}