@adobe/aio-commerce-lib-admin-ui 0.2.0-beta-20260714082406 → 0.2.0

package/dist/es/web/index.mjs

@@ -48,6 +48,37 @@ function isControlFrame() {
 	return isEmbeddedInHost() && !window.name;
 }
 
+//#endregion
+//#region source/web/react/result.ts
+/** Creates a successful data result. */
+function ok(data) {
+	return {
+		data,
+		error: null
+	};
+}
+/** Creates a failed data result. */
+function error(message, options) {
+	return {
+		data: null,
+		error: new Error(message, options)
+	};
+}
+/** Creates a successful actions result. */
+function okActions(actions) {
+	return {
+		actions,
+		error: null
+	};
+}
+/** Creates a failed actions result. */
+function actionsError(message, options) {
+	return {
+		actions: null,
+		error: new Error(message, options)
+	};
+}
+
 //#endregion
 //#region source/web/react/auth/context/ims-context.tsx
 const ImsContextValue = createContext(void 0);
@@ -55,14 +86,13 @@ const ImsContextValue = createContext(void 0);
 * Returns the IMS credentials provided by the host. Works inside the Commerce Admin and the
 * Experience Cloud shell.
 *
-* @throws If no host provides credentials (e.g. the app is running standalone, outside both the
-* Commerce Admin and the Experience Cloud shell).
+* Returns an error when no host provides credentials.
 */
 function useIms() {
 	const credentials = use(ImsContextValue);
-	if (credentials === void 0) throw new Error("useIms must be used inside an ImsContextProvider.");
-	if (!credentials) throw new Error("useIms requires running inside the Commerce Admin or the Experience Cloud shell, which provide the IMS credentials.");
-	return credentials;
+	if (credentials === void 0) return error("useIms must be used inside an ImsContextProvider.");
+	if (!credentials) return error("useIms requires running inside the Commerce Admin or the Experience Cloud shell, which provide the IMS credentials.");
+	return ok(credentials);
 }
 /**
 * Provides the IMS credentials for a mounted Admin UI iframe app.
@@ -84,9 +114,7 @@ const SharedContextValue = createContext(void 0);
 * Returns the current Commerce shared context provider state.
 */
 function useInternalSharedContext() {
-	const context = use(SharedContextValue);
-	if (context === void 0) throw new Error("useSharedContext must be used inside a SharedContextProvider, which is only available in the Commerce Admin.");
-	return context;
+	return use(SharedContextValue);
 }
 /**
 * Returns the current Commerce shared context. The guest connection is already established by
@@ -96,26 +124,29 @@ function useInternalSharedContext() {
 * Prefer a purpose-built hook ({@link useCommerce}, {@link useMassActionContext},
 * {@link useOrderViewButtonContext}) when one covers what you need.
 *
-* @throws If used outside a {@link SharedContextProvider}.
-*
 * @example
 * ```tsx
 * import { useSharedContext } from "@adobe/aio-commerce-lib-admin-ui/web";
 *
 * function ImsTokenLabel() {
-*   const { sharedContext } = useSharedContext();
-*   return <span>{sharedContext.get("imsToken")}</span>;
+*   const { data, error } = useSharedContext();
+*   if (error) return null;
+*   return <span>{data.sharedContext.get("imsToken")}</span>;
 * }
 * ```
 */
 function useSharedContext() {
-	const { extensionId, guestConnection } = useInternalSharedContext();
-	const sharedContext = useLiveSharedContext(guestConnection);
-	return {
-		extensionId,
-		host: guestConnection.host,
-		sharedContext
-	};
+	const context = useInternalSharedContext();
+	const sharedContext = useLiveSharedContext(context?.guestConnection);
+	return useMemo(() => {
+		if (!context) return error("useSharedContext must be used inside a SharedContextProvider, which is only available in the Commerce Admin.");
+		if (!sharedContext) return error("The Commerce host did not provide a shared context for this extension.");
+		return ok({
+			extensionId: context.extensionId,
+			host: context.guestConnection.host,
+			sharedContext
+		});
+	}, [context, sharedContext]);
 }
 /**
 * Tracks the live UIX `sharedContext` for a connection.
@@ -127,7 +158,10 @@ function useSharedContext() {
 * @param guestConnection - The established guest connection.
 */
 function useLiveSharedContext(guestConnection) {
-	return useSyncExternalStore(useCallback((onContextChange) => guestConnection.addEventListener("contextchange", onContextChange), [guestConnection]), () => guestConnection.sharedContext);
+	return useSyncExternalStore(useCallback((onContextChange) => {
+		if (!guestConnection) return () => void 0;
+		return guestConnection.addEventListener("contextchange", onContextChange);
+	}, [guestConnection]), () => guestConnection?.sharedContext ?? null);
 }
 /**
 * Provides the Commerce shared context for a mounted Admin UI iframe app.
@@ -149,28 +183,33 @@ function SharedContextProvider(props) {
 //#endregion
 //#region source/web/react/promise-cache.ts
 /**
-* Creates a keyed cache that memoizes in-flight, resolved, and rejected promises, giving `use()`
+* Creates a keyed cache that memoizes in-flight, successful, and failed promises, giving `use()`
 * the reference-stable promise it needs while suspended and single-flighting side-effecting
 * establishment calls across re-renders, remounts, and StrictMode double-invocation.
 *
-* Rejections are retained (not evicted) so `use()` replays them to an error boundary instead of
-* suspending forever on a fresh pending promise. Retry a failed key via {@link RetryablePromiseCache.evict}.
+* Promise rejections are failures by default. Pass `isFailure` when a fulfilled value, such as an
+* error result, must also be retryable. Failed entries remain cached until `evictIfFailed` is
+* called, so retries never replace a stable promise during render.
+*
+* @param isFailure - Determines whether a fulfilled value represents a failure.
 */
-function createRetryablePromiseCache() {
+function createRetryablePromiseCache(isFailure = () => false) {
 	const cache = /* @__PURE__ */ new Map();
 	return {
-		evictIfRejected(key) {
-			if (cache.get(key)?.rejected) cache.delete(key);
+		evictIfFailed(key) {
+			if (cache.get(key)?.failed) cache.delete(key);
 		},
 		get(key, create) {
 			const cached = cache.get(key);
 			if (cached) return cached.promise;
 			const entry = {
-				promise: create(),
-				rejected: false
+				failed: false,
+				promise: create()
 			};
-			entry.promise.catch(() => {
-				entry.rejected = true;
+			entry.promise.then((value) => {
+				entry.failed = isFailure(value);
+			}).catch(() => {
+				entry.failed = true;
 			});
 			cache.set(key, entry);
 			return entry.promise;
@@ -180,7 +219,7 @@ function createRetryablePromiseCache() {
 
 //#endregion
 //#region source/web/react/commerce/hooks/use-commerce.ts
-const commerceHosts = createRetryablePromiseCache();
+const commerceHosts = createRetryablePromiseCache((result) => result.error !== null);
 /**
 * Returns the cached Commerce Admin host promise for an extension, resolving it once over the
 * given guest connection. The value is static for the lifetime of the connection.
@@ -189,24 +228,31 @@ const commerceHosts = createRetryablePromiseCache();
 * @param connection - The established guest connection.
 */
 function getCommerceHostPromise(extensionId, connection) {
-	const { integration } = connection.host;
-	if (!integration) throw new Error("The host does not provide the integration API needed to resolve the Commerce host.");
-	return commerceHosts.get(extensionId, () => integration.getCommerceHost());
+	return commerceHosts.get(extensionId, async () => {
+		const { integration } = connection.host;
+		if (!integration) return error("The host does not provide the integration API needed to resolve the Commerce host.");
+		try {
+			return ok({ commerceHost: await integration.getCommerceHost() });
+		} catch (cause) {
+			return error("Failed to resolve the Commerce host.", { cause });
+		}
+	});
 }
 /** Drops a failed Commerce host resolution for `extensionId`, so a later render retries it. */
 function retryCommerceHost(extensionId) {
-	commerceHosts.evictIfRejected(extensionId);
+	commerceHosts.evictIfFailed(extensionId);
 }
 /**
 * Returns the host (domain) of the Commerce Admin the extension is embedded in, resolving it over
 * the guest connection.
 *
-* @throws If used outside a Commerce Admin UI frame, or when the host does not expose the
-* Commerce integration API.
+* Returns an error when used outside a Commerce Admin UI frame, when the host does not expose the
+* Commerce integration API, or when resolving the host fails.
 */
 function useCommerce() {
-	const { extensionId, guestConnection } = useInternalSharedContext();
-	return { commerceHost: use(getCommerceHostPromise(extensionId, guestConnection)) };
+	const context = useInternalSharedContext();
+	if (!context) return error("useCommerce requires running inside the Commerce Admin.");
+	return use(getCommerceHostPromise(context.extensionId, context.guestConnection));
 }
 
 //#endregion
@@ -215,28 +261,31 @@ function useCommerce() {
 * Returns the context for a mass-action extension point: the selected row IDs the action was
 * triggered with. The value is read from the host-provided Commerce context.
 *
-* @throws If used outside the Commerce shared context, or when that context does not include a
-* mass-action selection.
+* Returns an error outside the Commerce shared context, or when the mass-action selection is
+* missing, empty, or contains a non-string row ID.
 */
 function useMassActionContext() {
-	const { sharedContext } = useSharedContext();
+	const { data, error: contextError } = useSharedContext();
 	return useMemo(() => {
-		const selectedIds = sharedContext.get("selectedIds");
-		if (!Array.isArray(selectedIds)) throw new Error("Could not find `selectedIds` in the Commerce shared context. Is this frame running as a mass-action extension point?");
-		return { selectedIds };
-	}, [sharedContext]);
+		if (contextError) return error(contextError.message, { cause: contextError });
+		const selectedIds = data.sharedContext.get("selectedIds");
+		if (!Array.isArray(selectedIds)) return error("Could not find `selectedIds` in the Commerce shared context. Is this frame running as a mass-action extension point?");
+		if (selectedIds.length === 0) return error("No rows selected. A mass-action extension point must be triggered with at least one selected row.");
+		if (selectedIds.some((id) => typeof id !== "string")) return error("Some of the `selectedIds` in the Commerce shared context are not strings. All selected row IDs must be strings.");
+		return ok({ selectedIds });
+	}, [data, contextError]);
 }
 /**
 * Returns the context for an order view-button extension point: the order ID the button was
 * triggered from.
 *
-* @throws If no order ID is present in the page URL.
+* Returns an error when no order ID is present in the page URL.
 */
 function useOrderViewButtonContext() {
 	return useMemo(() => {
 		const orderId = parseOrderId(globalThis.location.href);
-		if (orderId === null) throw new Error("Could not find an order ID. Is this frame running as an order view-button extension point?");
-		return { orderId };
+		if (orderId === null) return error("Could not find an order ID. Is this frame running as an order view-button extension point?");
+		return ok({ orderId });
 	}, []);
 }
 
@@ -245,51 +294,39 @@ function useOrderViewButtonContext() {
 /**
 * Returns typed helpers for interacting with the Commerce Admin host.
 *
-* @throws If called before the guest connection is established, or when the host frame actions
-* are unavailable.
-*
 * @example
 * ```tsx
 * import { useHostConnection } from "@adobe/aio-commerce-lib-admin-ui/web";
 *
 * function DoneButton() {
-*   const { close } = useHostConnection();
-*   return <button onClick={() => void close()}>Done</button>;
+*   const { actions, error } = useHostConnection();
+*   if (error) return null;
+*   return <button onClick={actions.close}>Done</button>;
 * }
 * ```
 */
 function useHostConnection() {
-	const { host } = useSharedContext();
+	const { data, error: contextError } = useSharedContext();
 	return useMemo(() => {
-		const { field } = host;
-		const requireField = () => {
-			if (!field) throw new Error("Host frame actions are unavailable. They require an established guest connection with a host that exposes frame actions.");
-			return field;
-		};
-		return {
-			close: () => requireField().close(),
-			closeWithError: () => requireField().onError()
-		};
-	}, [host]);
+		if (contextError) return actionsError(contextError.message, { cause: contextError });
+		const { field } = data.host;
+		if (!field) return actionsError("Host frame actions are unavailable. They require an established guest connection with a host that exposes frame actions.");
+		return okActions({
+			close: () => field.close(),
+			closeWithError: () => field.onError()
+		});
+	}, [data, contextError]);
 }
 
 //#endregion
 //#region source/web/react/routing/lib.ts
 const HASH_ROUTE_PREFIX_PATTERN = /^[#/]+/u;
 /**
-* Determines if a given route is an index route.
-* @param route The route to check.
-*/
-function isIndexRoute(route) {
-	return "index" in route && route.index;
-}
-/**
 * Returns the path for a given route, removing any leading hash or slash characters.
 * @param route The route to get the path for.
 */
 function getRoutePath(route) {
-	if (isIndexRoute(route)) return "/";
-	return route.path.replace(HASH_ROUTE_PREFIX_PATTERN, "");
+	return route.path.replace(HASH_ROUTE_PREFIX_PATTERN, "") || "/";
 }
 /**
 * Returns the "to" path for a given route, removing any leading hash or slash characters.
@@ -431,7 +468,7 @@ function useGuestConnection(extensionId) {
 }
 /** Drops a failed connection for `extensionId`, so a later render re-attaches. */
 function retryGuestConnection(extensionId) {
-	guestConnections.evictIfRejected(extensionId);
+	guestConnections.evictIfFailed(extensionId);
 }
 
 //#endregion
@@ -622,9 +659,10 @@ function CommerceGuestConnection(props) {
 }
 /** Renders IMS-gated route content for a Commerce Admin UI frame. */
 function CommerceExtensionContent() {
-	const { sharedContext } = useSharedContext();
+	const { data, error } = useSharedContext();
+	if (error) throw error;
 	return /* @__PURE__ */ jsx(ImsContextProvider, {
-		credentials: resolveCommerceImsCredentials(sharedContext),
+		credentials: resolveCommerceImsCredentials(data.sharedContext),
 		children: /* @__PURE__ */ jsx(Outlet, {})
 	});
 }
@@ -780,11 +818,12 @@ function Entrypoint(props) {
 *
 * createExtensionApp({
 *   metadata: { extensionId: "my-extension-id" },
-*   routes: [{ index: true, element: <MainPage /> }],
+*   menu: <MainPage />,
 * });
 * ```
 */
-function createExtensionApp({ metadata, routes, root: customRoot }) {
+function createExtensionApp({ menu, metadata, routes = [], root: customRoot }) {
+	if (menu !== void 0 && routes.some((route) => getRouteTo(route.path) === "/")) throw new Error("The \"/\" route is reserved for the menu. Pass its element through the menu option instead.");
 	const rootElement = customRoot ?? document.getElementById("root");
 	if (!rootElement) throw new Error("Could not find an element with id \"root\".");
 	const root = createRoot(rootElement);
@@ -793,7 +832,10 @@ function createExtensionApp({ metadata, routes, root: customRoot }) {
 			extensionId: metadata.extensionId,
 			initialConfigurationPromise,
 			runtime
-		}), routes);
+		}), menu === void 0 ? routes : [{
+			element: menu,
+			path: "/"
+		}, ...routes]);
 		root.render(/* @__PURE__ */ jsx(StrictMode, { children: /* @__PURE__ */ jsx(RouterProvider, { router }) }));
 	};
 	try {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@adobe/aio-commerce-lib-admin-ui",
   "type": "module",
   "author": "Adobe Inc.",
-  "version": "0.2.0-beta-20260714082406",
+  "version": "0.2.0",
   "private": false,
   "engines": {
     "node": ">=22 <=24"
@@ -113,8 +113,8 @@
     "ky": "^1.9.0",
     "react-error-boundary": "^6.1.2",
     "valibot": "^1.1.0",
-    "@adobe/aio-commerce-lib-api": "1.3.0-beta-20260714082406",
-    "@adobe/aio-commerce-lib-core": "1.2.0-beta-20260714082406"
+    "@adobe/aio-commerce-lib-api": "1.3.0",
+    "@adobe/aio-commerce-lib-core": "1.2.0"
   },
   "peerDependencies": {
     "@react-spectrum/s2": "^1.5.1",
@@ -139,12 +139,12 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "typescript": "^6.0.0",
-    "@aio-commerce-sdk/common-utils": "0.2.6-beta-20260714082406",
+    "@aio-commerce-sdk/common-utils": "0.2.6",
     "@aio-commerce-sdk/config-tsdown": "1.0.1",
     "@aio-commerce-sdk/config-typedoc": "1.0.0",
     "@aio-commerce-sdk/config-typescript": "1.0.0",
     "@aio-commerce-sdk/config-vitest": "1.0.0",
-    "@aio-commerce-sdk/scripting-utils": "0.3.4-beta-20260714082406",
+    "@aio-commerce-sdk/scripting-utils": "0.3.4",
     "@aio-commerce-sdk/scripts": "0.1.0"
   },
   "sideEffects": false,