/**
 * @license
 *
 * Copyright 2026 Adobe. All rights reserved.
 * This file is licensed to you under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may obtain a copy
 * of the License at http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under
 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
 * OF ANY KIND, either express or implied. See the License for the specific language
 * governing permissions and limitations under the License.
 */

import { ReactNode } from "react";
import { attach } from "@adobe/uix-guest";
import { NavigateOptions, ToOptions } from "@tanstack/react-router";
//#region source/web/react/auth/types.d.ts
/** The IMS credentials provided by the host (Commerce Admin or Experience Cloud shell). */
type ImsContext = {
  imsToken: string;
  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.
 *
 * Returns an error when no host provides credentials.
 */
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. */
type GuestConnection = Awaited<ReturnType<typeof attach>>;
/**
 * The Commerce shared context for a mounted Admin UI iframe app.
 *
 * This only exists when the app runs inside the Commerce Admin: it is provided by the Commerce UIX
 * host over the guest connection. It is distinct from the IMS credentials ({@link ImsContext}),
 * which are also available in the Experience Cloud shell.
 */
type SharedContext = {
  /** The extension ID of the app. */
  extensionId: string;
  /** The live `sharedContext` object provided by the host. */
  sharedContext: NonNullable<GuestConnection["sharedContext"]>;
  /** The host proxy, used by `useHostConnection` to invoke host-frame actions (close/onError). */
  host: NonNullable<GuestConnection["host"]>;
};
/** Actions for closing the extension iframe and returning control to the Commerce Admin. */
type HostConnection = {
  /** Closes the iframe and navigates back to the originating grid or order. */
  close: () => Promise<void>;
  /** Closes the iframe and navigates back, flagging the originating page that an error occurred. */
  closeWithError: () => Promise<void>;
};
/** The context shared with mass-action extension points. */
type MassActionContext = {
  selectedIds: string[];
};
/** The context shared with order view-button extension points. */
type OrderViewButtonContext = {
  orderId: string;
};
//#endregion
//#region source/web/react/commerce/context/shared-context.d.ts
/**
 * Returns the current Commerce shared context. The guest connection is already established by
 * the time this can be called (see {@link SharedContextProvider}).
 *
 * This is a low-level escape hatch that exposes the raw `sharedContext` and `host` objects.
 * Prefer a purpose-built hook ({@link useCommerce}, {@link useMassActionContext},
 * {@link useOrderViewButtonContext}) when one covers what you need.
 *
 * @example
 * ```tsx
 * import { useSharedContext } from "@adobe/aio-commerce-lib-admin-ui/web";
 *
 * function ImsTokenLabel() {
 *   const { data, error } = useSharedContext();
 *   if (error) return null;
 *   return <span>{data.sharedContext.get("imsToken")}</span>;
 * }
 * ```
 */
declare function useSharedContext(): Result<SharedContext>;
//#endregion
//#region source/web/react/commerce/hooks/use-commerce.d.ts
type CommerceData = {
  commerceHost: string;
};
/**
 * Returns the host (domain) of the Commerce Admin the extension is embedded in, resolving it over
 * the guest connection.
 *
 * 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(): 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.
 *
 * 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(): Result<MassActionContext>;
/**
 * Returns the context for an order view-button extension point: the order ID the button was
 * triggered from.
 *
 * Returns an error when no order ID is present in the page URL.
 */
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.
 *
 * @example
 * ```tsx
 * import { useHostConnection } from "@adobe/aio-commerce-lib-admin-ui/web";
 *
 * function DoneButton() {
 *   const { actions, error } = useHostConnection();
 *   if (error) return null;
 *   return <button onClick={actions.close}>Done</button>;
 * }
 * ```
 */
declare function useHostConnection(): ActionsResult<HostConnection>;
//#endregion
//#region source/web/react/routing/types.d.ts
declare module "@react-spectrum/s2/Provider" {
  interface RouterConfig {
    href: ToOptions;
    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
  }
}
/** 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;
};
//#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;
  };
  /** 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
 * registration, shared-context attachment, routing, and Spectrum setup.
 *
 * The app is wrapped in React's `<StrictMode>` only in development builds
 * (`process.env.NODE_ENV !== "production"`), so components render twice and effects
 * run an extra setup + cleanup cycle on mount. Production builds
 * (`process.env.NODE_ENV === "production"`) render without `<StrictMode>`, so it is
 * stripped from the production bundle.
 *
 * @param options - App bootstrap options.
 *
 * @example
 * ```tsx
 * import { createExtensionApp } from "@adobe/aio-commerce-lib-admin-ui/web";
 * import { MainPage } from "./pages/main-page.jsx";
 *
 * createExtensionApp({
 *   metadata: { extensionId: "my-extension-id" },
 *   menu: <MainPage />,
 * });
 * ```
 */
declare function createExtensionApp({ menu, metadata, routes, root: customRoot }: CreateExtensionAppOptions): void;
//#endregion
export { type CreateExtensionAppOptions, type ExtensionRoute, type HostConnection, type ImsContext, type MassActionContext, type OrderViewButtonContext, type SharedContext, createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };