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

package/dist/cjs/web/index.d.cts

@@ -23,15 +23,35 @@ type ImsContext = {
   imsOrgId: string;
 };
 //#endregion
+//#region source/web/react/result.d.ts
+/** The result of reading data that might not be available in the current host context. */
+type Result<T, E = Error> = {
+  data: T;
+  error: null;
+} | {
+  data: null;
+  error: E;
+};
+type ActionMap = {
+  [key: string]: (...args: unknown[]) => PromiseLike<unknown>;
+};
+/** The result of exposing an API that might not be available in the current host context. */
+type ActionsResult<T extends ActionMap, E = Error> = {
+  actions: T;
+  error: null;
+} | {
+  actions: null;
+  error: E;
+};
+//#endregion
 //#region source/web/react/auth/context/ims-context.d.ts
 /**
  * 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.
  */
-declare function useIms(): ImsContext;
+declare function useIms(): Result<ImsContext>;
 //#endregion
 //#region source/web/react/commerce/types.d.ts
 /** The guest connection that shares the context between the extension and the Admin UI host. */
@@ -71,67 +91,66 @@ type OrderViewButtonContext = {
  * 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>;
  * }
  * ```
  */
-declare function useSharedContext(): SharedContext;
+declare function useSharedContext(): Result<SharedContext>;
 //#endregion
 //#region source/web/react/commerce/hooks/use-commerce.d.ts
+type CommerceData = {
+  commerceHost: string;
+};
+/** Drops a failed Commerce host resolution for `extensionId`, so a later render retries it. */
 /**
  * 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.
  */
-declare function useCommerce(): {
-  commerceHost: string;
-};
+declare function useCommerce(): Result<CommerceData>;
 //#endregion
 //#region source/web/react/commerce/hooks/use-extension-context.d.ts
 /**
  * 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.
  */
-declare function useMassActionContext(): MassActionContext;
+declare function useMassActionContext(): Result<MassActionContext>;
 /**
  * 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.
  */
-declare function useOrderViewButtonContext(): OrderViewButtonContext;
+declare function useOrderViewButtonContext(): Result<OrderViewButtonContext>;
 //#endregion
 //#region source/web/react/commerce/hooks/use-host-connection.d.ts
 /**
  * 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>;
  * }
  * ```
  */
-declare function useHostConnection(): HostConnection;
+declare function useHostConnection(): ActionsResult<HostConnection>;
 //#endregion
 //#region source/web/react/routing/types.d.ts
 declare module "@react-spectrum/s2/Provider" {
@@ -140,27 +159,21 @@ declare module "@react-spectrum/s2/Provider" {
     routerOptions: Omit<NavigateOptions, keyof ToOptions>;
   }
 }
-/** Defines a route that is marked as the index (entrypoint) */
-type IndexRoute = {
-  index: true; /** The React element to render for the index route. */
-  element: ReactNode;
-};
 /** Defines a route that exists at a given path. */
 type ExtensionRoute = {
   /** The path for the route. */path: string; /** The React element to render for the route. */
   element: ReactNode;
 };
-/** Defines the routes for an extension app, which must include at least one index route (first item). */
-type ExtensionAppRoutes = [IndexRoute, ...ExtensionRoute[]];
 //#endregion
 //#region source/web/react/extension/create-app.d.ts
 /** Configuration options when instantiating an extension app. */
 type CreateExtensionAppOptions = {
   /** General metadata about the extension app. */metadata: {
     /** The unique identifier for the extension app. */extensionId: string;
-  }; /** Optional root element where the app will be mounted. */
-  root?: HTMLElement; /** A list of routes for the extension app, specifying an index route is mandatory. */
-  routes: ExtensionAppRoutes;
+  }; /** The optional app page opened from the Commerce Admin menu and by default in Experience Cloud Shell. */
+  menu?: ReactNode; /** Optional root element where the app will be mounted. */
+  root?: HTMLElement; /** Additional path-based routes for the extension app. */
+  routes?: ExtensionRoute[];
 };
 /**
  * Mounts a Commerce Admin UI iframe app and handles Experience Cloud Shell, UIX
@@ -179,14 +192,15 @@ type CreateExtensionAppOptions = {
  *
  * createExtensionApp({
  *   metadata: { extensionId: "my-extension-id" },
- *   routes: [{ index: true, element: <MainPage /> }],
+ *   menu: <MainPage />,
  * });
  * ```
  */
 declare function createExtensionApp({
+  menu,
   metadata,
   routes,
   root: customRoot
 }: CreateExtensionAppOptions): void;
 //#endregion
-export { type CreateExtensionAppOptions, type ExtensionAppRoutes, type ExtensionRoute, type HostConnection, type ImsContext, type IndexRoute, type MassActionContext, type OrderViewButtonContext, type SharedContext, createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };
+export { type CreateExtensionAppOptions, type ExtensionRoute, type HostConnection, type ImsContext, type MassActionContext, type OrderViewButtonContext, type SharedContext, createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };

package/dist/es/mass-actions/index.d.mts

@@ -42,47 +42,6 @@ import { ErrorResponse, SuccessResponse } from "@adobe/aio-commerce-lib-core/res
  */
 declare function getMassActionAclResourceId(metadataId: string, entity: AdminUiEntity, actionId: string): string;
 //#endregion
-//#region source/mass-actions/view/schema.d.ts
-/**
- * Schema for the `selection` query parameter Commerce appends to the iframe URL
- * of a view mass action.
- *
- * Commerce serializes the selection as a JSON-encoded string:
- * `?selection={"ids":["000000001"],"gridType":"customer"}`
- */
-declare const MassActionSelectionSchema: v.ObjectSchema<{
-  readonly gridType: v.PicklistSchema<["order", "product", "customer"], undefined>;
-  readonly ids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, undefined>, v.MinLengthAction<string[], 1, "The value of \"ids\" must contain at least one entry">]>;
-}, undefined>;
-//#endregion
-//#region source/mass-actions/view/types.d.ts
-/** Parsed `selection` query parameter appended by Commerce to the iframe URL. */
-type MassActionSelection = v.InferOutput<typeof MassActionSelectionSchema>;
-//#endregion
-//#region source/mass-actions/view/presets.d.ts
-/**
- * Parses the `selection` query parameter Commerce appends to the iframe URL of
- * a view mass action.
- *
- * Commerce serializes the selection as a JSON string:
- * `?selection={"ids":["000000001","000000002"],"gridType":"customer"}`
- *
- * Throws a `CommerceSdkValidationError` if the input is missing, not valid
- * JSON, or does not match the expected shape.
- *
- * @param rawSelection - The raw string value of the `selection` query parameter.
- *
- * @example
- * ```ts
- * import { parseMassActionSelection } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
- *
- * // In your SPA route handler:
- * const raw = new URLSearchParams(window.location.search).get("selection");
- * const { ids, gridType } = parseMassActionSelection(raw);
- * ```
- */
-declare function parseMassActionSelection(rawSelection: unknown): MassActionSelection;
-//#endregion
 //#region source/mass-actions/worker/schema.d.ts
 /**
  * Grid identifier sent by Commerce on the `commerce/backend-ui/2` wire contract
@@ -157,4 +116,4 @@ declare function okMassActionResponse(body?: MassActionResponseBody): SuccessRes
  */
 declare function massActionErrorResponse(statusCode: number, errorMessage: string): ErrorResponse<MassActionErrorBody>;
 //#endregion
-export { type AdminUiEntity, type MassActionErrorBody, type MassActionGridType, MassActionGridTypeSchema, type MassActionRequest, MassActionRequestSchema, type MassActionResponseBody, type MassActionSelection, MassActionSelectionSchema, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest, parseMassActionSelection };
+export { type AdminUiEntity, type MassActionErrorBody, type MassActionGridType, MassActionGridTypeSchema, type MassActionRequest, MassActionRequestSchema, type MassActionResponseBody, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest };

package/dist/es/mass-actions/index.mjs

@@ -48,58 +48,6 @@ function getMassActionAclResourceId(metadataId, entity, actionId) {
 	return `${appRoot}_${entity}_massactions_${sanitizeSegment(actionId)}`;
 }
 
-//#endregion
-//#region source/mass-actions/view/schema.ts
-/**
-* Schema for the `selection` query parameter Commerce appends to the iframe URL
-* of a view mass action.
-*
-* Commerce serializes the selection as a JSON-encoded string:
-* `?selection={"ids":["000000001"],"gridType":"customer"}`
-*/
-const MassActionSelectionSchema = v.object({
-	gridType: v.picklist([
-		"order",
-		"product",
-		"customer"
-	]),
-	ids: v.pipe(v.array(nonEmptyStringValueSchema("id")), v.minLength(1, "The value of \"ids\" must contain at least one entry"))
-});
-
-//#endregion
-//#region source/mass-actions/view/presets.ts
-/**
-* Parses the `selection` query parameter Commerce appends to the iframe URL of
-* a view mass action.
-*
-* Commerce serializes the selection as a JSON string:
-* `?selection={"ids":["000000001","000000002"],"gridType":"customer"}`
-*
-* Throws a `CommerceSdkValidationError` if the input is missing, not valid
-* JSON, or does not match the expected shape.
-*
-* @param rawSelection - The raw string value of the `selection` query parameter.
-*
-* @example
-* ```ts
-* import { parseMassActionSelection } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
-*
-* // In your SPA route handler:
-* const raw = new URLSearchParams(window.location.search).get("selection");
-* const { ids, gridType } = parseMassActionSelection(raw);
-* ```
-*/
-function parseMassActionSelection(rawSelection) {
-	if (rawSelection === null || rawSelection === void 0) throw new Error("Invalid mass action selection: the selection query parameter is missing.");
-	let parsed;
-	try {
-		parsed = JSON.parse(String(rawSelection));
-	} catch (error) {
-		throw new Error(`Invalid mass action selection: expected a JSON string, got: ${String(rawSelection)}`, { cause: error });
-	}
-	return parseOrThrow(MassActionSelectionSchema, parsed, "Invalid mass action selection");
-}
-
 //#endregion
 //#region source/mass-actions/worker/schema.ts
 /**
@@ -175,4 +123,4 @@ function massActionErrorResponse(statusCode, errorMessage) {
 }
 
 //#endregion
-export { MassActionGridTypeSchema, MassActionRequestSchema, MassActionSelectionSchema, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest, parseMassActionSelection };
+export { MassActionGridTypeSchema, MassActionRequestSchema, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest };

package/dist/es/web/index.d.mts

@@ -23,15 +23,35 @@ type ImsContext = {
   imsOrgId: string;
 };
 //#endregion
+//#region source/web/react/result.d.ts
+/** The result of reading data that might not be available in the current host context. */
+type Result<T, E = Error> = {
+  data: T;
+  error: null;
+} | {
+  data: null;
+  error: E;
+};
+type ActionMap = {
+  [key: string]: (...args: unknown[]) => PromiseLike<unknown>;
+};
+/** The result of exposing an API that might not be available in the current host context. */
+type ActionsResult<T extends ActionMap, E = Error> = {
+  actions: T;
+  error: null;
+} | {
+  actions: null;
+  error: E;
+};
+//#endregion
 //#region source/web/react/auth/context/ims-context.d.ts
 /**
  * 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.
  */
-declare function useIms(): ImsContext;
+declare function useIms(): Result<ImsContext>;
 //#endregion
 //#region source/web/react/commerce/types.d.ts
 /** The guest connection that shares the context between the extension and the Admin UI host. */
@@ -71,67 +91,66 @@ type OrderViewButtonContext = {
  * 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>;
  * }
  * ```
  */
-declare function useSharedContext(): SharedContext;
+declare function useSharedContext(): Result<SharedContext>;
 //#endregion
 //#region source/web/react/commerce/hooks/use-commerce.d.ts
+type CommerceData = {
+  commerceHost: string;
+};
+/** Drops a failed Commerce host resolution for `extensionId`, so a later render retries it. */
 /**
  * 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.
  */
-declare function useCommerce(): {
-  commerceHost: string;
-};
+declare function useCommerce(): Result<CommerceData>;
 //#endregion
 //#region source/web/react/commerce/hooks/use-extension-context.d.ts
 /**
  * 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.
  */
-declare function useMassActionContext(): MassActionContext;
+declare function useMassActionContext(): Result<MassActionContext>;
 /**
  * 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.
  */
-declare function useOrderViewButtonContext(): OrderViewButtonContext;
+declare function useOrderViewButtonContext(): Result<OrderViewButtonContext>;
 //#endregion
 //#region source/web/react/commerce/hooks/use-host-connection.d.ts
 /**
  * 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>;
  * }
  * ```
  */
-declare function useHostConnection(): HostConnection;
+declare function useHostConnection(): ActionsResult<HostConnection>;
 //#endregion
 //#region source/web/react/routing/types.d.ts
 declare module "@react-spectrum/s2/Provider" {
@@ -140,27 +159,21 @@ declare module "@react-spectrum/s2/Provider" {
     routerOptions: Omit<NavigateOptions, keyof ToOptions>;
   }
 }
-/** Defines a route that is marked as the index (entrypoint) */
-type IndexRoute = {
-  index: true; /** The React element to render for the index route. */
-  element: ReactNode;
-};
 /** Defines a route that exists at a given path. */
 type ExtensionRoute = {
   /** The path for the route. */path: string; /** The React element to render for the route. */
   element: ReactNode;
 };
-/** Defines the routes for an extension app, which must include at least one index route (first item). */
-type ExtensionAppRoutes = [IndexRoute, ...ExtensionRoute[]];
 //#endregion
 //#region source/web/react/extension/create-app.d.ts
 /** Configuration options when instantiating an extension app. */
 type CreateExtensionAppOptions = {
   /** General metadata about the extension app. */metadata: {
     /** The unique identifier for the extension app. */extensionId: string;
-  }; /** Optional root element where the app will be mounted. */
-  root?: HTMLElement; /** A list of routes for the extension app, specifying an index route is mandatory. */
-  routes: ExtensionAppRoutes;
+  }; /** The optional app page opened from the Commerce Admin menu and by default in Experience Cloud Shell. */
+  menu?: ReactNode; /** Optional root element where the app will be mounted. */
+  root?: HTMLElement; /** Additional path-based routes for the extension app. */
+  routes?: ExtensionRoute[];
 };
 /**
  * Mounts a Commerce Admin UI iframe app and handles Experience Cloud Shell, UIX
@@ -179,14 +192,15 @@ type CreateExtensionAppOptions = {
  *
  * createExtensionApp({
  *   metadata: { extensionId: "my-extension-id" },
- *   routes: [{ index: true, element: <MainPage /> }],
+ *   menu: <MainPage />,
  * });
  * ```
  */
 declare function createExtensionApp({
+  menu,
   metadata,
   routes,
   root: customRoot
 }: CreateExtensionAppOptions): void;
 //#endregion
-export { type CreateExtensionAppOptions, type ExtensionAppRoutes, type ExtensionRoute, type HostConnection, type ImsContext, type IndexRoute, type MassActionContext, type OrderViewButtonContext, type SharedContext, createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };
+export { type CreateExtensionAppOptions, type ExtensionRoute, type HostConnection, type ImsContext, type MassActionContext, type OrderViewButtonContext, type SharedContext, createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };