feat(AppShell): add Services package to the App Shell suite [PPUC-187]

Author: loonatic

package-lock.json

@@ -0,0 +1,130 @@
+# @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
+
+Below is an example of how one could get all registered services (provided by multiple other packages/plugins in the AppShell ecosystem) for, for example, a header action dropdown menu.
+
+First, and although not mandatory it would be ideal that the types of the services are defined in a separate package, so that both the service providers and consumers can depend on it:
+
+```typescript
+// @some-package/my-app-services
+// index.ts
+export type MyAppCreateHeaderAction = {
+  id: string;
+  ordinal?: number;
+  label: string;
+  icon?: ReactNode;
+  onAction: () => void;
+};
+
+export type UseMyAppCreateHeaderAction = () =>
+  | MyAppCreateHeaderAction
+  | undefined;
+
+/**
+ * Service definitions for my app.
+ */
+export const MyAppServiceDefinitions = {
+  UseMyAppCreateHeaderAction: {
+    id: "my-app-header-action-id",
+  },
+};
+```
+
+```typescript
+import { FC, useCallback, useMemo } from "react";
+import { useServices, SERVICES_ERROR_HANDLING } from "@hitachivantara/app-shell-services";
+import { PlusCircleIcon } from "@phosphor-icons/react";
+import {
+    HvDropDownMenu,
+    HvDropDownMenuProps,
+    HvIconContainer,
+    HvListValue
+} from "@hitachivantara/uikit-react-core";
+import { MyAppServiceDefinitions, MyAppUseCreateHeaderAction, MyAppCreateHeaderAction } from "@some-package/my-app-services";
+
+type OnDropDownMenuClickCallback = NonNullable<HvDropDownMenuProps["onClick"]>;
+
+function isNonNull<T>(value: T): value is NonNullable<T> {
+    return value != null;
+}
+
+function createListValue(action: MyAppCreateHeaderAction): HvListValue {
+  return {
+    id: action.id,
+    label: action.label,
+    icon: action.icon
+  } as HvListValue;
+}
+
+const CreateHeaderActionComponentInner: FC<{
+    actionHooks: UseMyAppCreateHeaderAction[];
+}> = ({ actionHooks }) => {
+  // Call all hooks directly at the top level as each hook call happens consistently on every render
+  const actionResults = actionHooks.map(actionHook => actionHook()).filter(isNonNull);
+
+  // Create menu items
+  const dataList = useMemo(() => actionResults.map(createListValue), [actionResults]);
+
+  const onClick = useCallback<OnDropDownMenuClickCallback>(
+    (_event, dataListItem) => {
+      const action = actionResults.find(action => action.id === dataListItem.id);
+      if (action) {
+        action.onAction();
+      }
+    },
+    [actionResults]
+  );
+
+  // If no valid actions, do not render anything.
+  if (dataList.length === 0) {
+    return null;
+  }
+
+  return (
+    <HvDropDownMenu
+      icon={
+        <HvIconContainer size="sm">
+          <PlusCircleIcon />
+        </HvIconContainer>
+      }
+      dataList={dataList}
+      keepOpened={false}
+      onClick={onClick}
+    />
+  );
+};
+
+function CreateHeaderActionComponent() {
+  // For getting multiple services with error handling set to reject on any failure (error on import, type mismatch, etc.)
+  const {
+    services: actionHooks,
+    isPending,
+    error
+  } = useServices<UseMyAppCreateHeaderAction>(MyAppServiceDefinitions.UseMyAppCreateHeaderAction.id, { errorHandling: SERVICES_ERROR_HANDLING.REJECT_ON_ANY_FAILURE });
+
+  if (isPending) return <div>Loading services...</div>;
+  if (error) return <div>Error loading services: {error.message}</div>;
+
+  // Services are now available to use
+  return <CreateHeaderActionComponentInner actionHooks={actionHooks} />;
+}
+```
+
+## Installation
+
+The App Shell Services is available as an NPM package, and can be installed with:
+
+```bash
+npm install @hitachivantara/app-shell-services
+```

packages/app-shell-services/README.md

@@ -0,0 +1,53 @@
+{
+  "name": "@hitachivantara/app-shell-services",
+  "version": "0.0.1",
+  "type": "module",
+  "private": false,
+  "author": "Hitachi Vantara UI Kit Team",
+  "description": "AppShell Services",
+  "homepage": "https://github.com/lumada-design/hv-uikit-react",
+  "main": "./src/index.ts",
+  "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",
+  "scripts": {
+    "build": "npm run clean && vite build",
+    "clean": "npx rimraf dist package",
+    "prepublishOnly": "npm run build && npx clean-publish"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "directory": "package",
+    "module": "dist/esm/index.js",
+    "types": "./dist/types/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/types/index.d.ts",
+        "import": "./dist/esm/index.js",
+        "default": "./dist/esm/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "clean-publish": {
+    "withoutPublish": true,
+    "tempDir": "package",
+    "fields": [
+      "main"
+    ],
+    "files": [
+      "tsconfig.json"
+    ]
+  }
+}

packages/app-shell-services/package.json

@@ -0,0 +1,69 @@
+import { useCallback } from "react";
+
+import {
+  ServiceId,
+  ServiceReference,
+  UseGetServiceReferenceOptions,
+  UseGetServiceReferencesOptions,
+  UseServiceOptions,
+  UseServiceReferenceResult,
+  UseServiceResult,
+  UseServicesOptions,
+  UseServicesResult,
+} from "../types/service";
+import { useAsyncGeneric } from "./useAsyncGeneric";
+import useServiceManager from "./useServiceManager";
+
+export function useService<TService>(
+  serviceId: ServiceId,
+  options: UseServiceOptions = {},
+): UseServiceResult<TService> {
+  const serviceManager = useServiceManager();
+
+  const promiseFactory = useCallback(
+    () => serviceManager.getService<TService>(serviceId, options),
+    [serviceManager, serviceId, options],
+  );
+
+  return useAsyncGeneric(promiseFactory, "service", undefined);
+}
+
+export function useServices<TService>(
+  serviceId: ServiceId,
+  options: UseServicesOptions = {},
+): UseServicesResult<TService> {
+  const serviceManager = useServiceManager();
+
+  return useAsyncGeneric(
+    () => serviceManager.getServices<TService>(serviceId, options),
+    "services",
+    [],
+  );
+}
+
+export function useGetServiceReference<TService>(
+  serviceId: ServiceId,
+  options: UseGetServiceReferenceOptions = {},
+): ServiceReference<TService> {
+  const serviceManager = useServiceManager();
+  return serviceManager.getServiceReference<TService>(serviceId, options);
+}
+
+export function useGetServiceReferences<TService>(
+  serviceId: ServiceId,
+  options: UseGetServiceReferencesOptions = {},
+): ServiceReference<TService>[] {
+  const serviceManager = useServiceManager();
+  return serviceManager.getServiceReferences<TService>(serviceId, options);
+}
+
+// Gets a reference's service as an async result.
+export function useServiceReference<TService>(
+  serviceReference: ServiceReference<TService>,
+): UseServiceReferenceResult<TService> {
+  return useAsyncGeneric(
+    () => serviceReference.getService(),
+    "service",
+    undefined,
+  );
+}

packages/app-shell-services/src/hooks/Hooks.tsx

@@ -0,0 +1,102 @@
+import { useEffect, useRef, useState } from "react";
+
+import {
+  ErrorBase,
+  UseAsyncErrorResult,
+  UseAsyncPendingResult,
+  UseAsyncResult,
+  UseAsyncSuccessResult,
+} from "../types/async";
+
+/**
+ * Generic async hook with full control over data property name and pending data.
+ * TODO ideally called useAsync, but making optional arguments and defaults work with generics is tricky...
+ *
+ * @param promiseFactory Function that returns a Promise
+ * @param dataProp Custom property name for the data
+ * @param pendingData Initial data while pending
+ * @returns UseAsyncResult with custom data property name
+ */
+export function useAsyncGeneric<
+  TData,
+  TError extends ErrorBase = Error,
+  TDataProp extends string = "data",
+  TDataPending extends TData | undefined = undefined,
+>(
+  promiseFactory: () => Promise<TData>,
+  dataProp: TDataProp,
+  pendingData: TDataPending,
+): UseAsyncResult<TData, TError, TDataProp, TDataPending> {
+  const [data, setData] = useState<TData | undefined>(pendingData);
+  const [error, setError] = useState<TError | null>(null);
+  const [isPending, setIsPending] = useState(true);
+
+  const promiseFactoryRef = useRef(promiseFactory);
+  const pendingDataRef = useRef(pendingData);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    // Reset state when starting a new async operation
+    setError(null);
+    setIsPending(true);
+    setData(pendingDataRef.current);
+
+    promiseFactoryRef
+      .current()
+      .then((result) => {
+        if (isMounted) {
+          setData(result);
+          setError(null);
+          setIsPending(false);
+        }
+      })
+      .catch((err) => {
+        if (isMounted) {
+          setError(err as TError);
+          setData(undefined);
+          setIsPending(false);
+        }
+      });
+
+    return () => {
+      isMounted = false;
+    };
+  }, []);
+
+  if (error) {
+    return {
+      isPending: false,
+      error,
+      [dataProp]: undefined,
+    } as UseAsyncErrorResult<TData, TError, TDataProp, TDataPending>;
+  }
+
+  if (isPending) {
+    return {
+      isPending: true,
+      error: null,
+      [dataProp]: pendingData,
+    } as UseAsyncPendingResult<TData, TError, TDataProp, TDataPending>;
+  }
+
+  return {
+    isPending: false,
+    error: null,
+    [dataProp]: data,
+  } as UseAsyncSuccessResult<TData, TError, TDataProp, TDataPending>;
+}
+
+/**
+ * Convenience hook for async data fetching with "data" property.
+ *
+ * @param promiseFactory Function that returns a Promise
+ * @param initialData Initial data while pending
+ * @returns UseAsyncResult with "data" property
+ */
+export function useAsyncData<TData, TError extends ErrorBase = Error>(
+  promiseFactory: () => Promise<TData>,
+  initialData?: TData,
+): UseAsyncResult<TData, TError, "data", TData | undefined> {
+  return useAsyncGeneric(promiseFactory, "data", initialData);
+}