@coinbase/cdp-react 0.0.98 → 0.0.100

package/dist/components/LinkAuth/LinkAuthFlowProvider.d.ts

@@ -3,31 +3,91 @@ import { AuthMethod } from '../CDPReactProvider';
 import { SwitchSlideTransitionRef } from '../ui/SwitchSlideTransition';
 import { SignInContentRef } from './LinkAuthFlow';
 import { LinkAuthFlowView } from './types';
+/**
+ * The value of the link auth flow context.
+ *
+ * @see {@link useLinkAuthFlow}
+ */
 export interface LinkAuthFlowContextValue {
+    /** A function to call when the back button is clicked. */
     back: () => void;
+    /** The direction of the flow transition. */
     direction?: "left" | "right";
+    /** A function to call when the user links an auth method. */
     link: (method: AuthMethod) => void;
+    /** A function to call when an auth method is successfully linked. */
     linkSuccess: () => void;
 }
+/**
+ * The value of the link auth flow context for the internal use of the component.
+ *
+ * @see {@link useLinkAuthFlowInternal}
+ */
 export interface LinkAuthFlowContextValueInternal extends LinkAuthFlowContextValue {
+    /** A ref to the flow transition. */
     transitionRef: RefObject<SwitchSlideTransitionRef<LinkAuthFlowView> | null> | null;
+    /** A ref that provides the ability to go back to the previous step of the sign in flow. */
     signInRef: RefObject<SignInContentRef | null> | null;
 }
+/**
+ * Props for the LinkAuthFlowProvider component.
+ *
+ * @see {@link LinkAuthFlowProvider}
+ */
 interface LinkAuthFlowProviderProps {
+    /** The children of the component. */
     children?: ReactNode;
+    /** The direction of the flow transition. */
     direction?: LinkAuthFlowContextValue["direction"];
+    /** A function to call when the back button is clicked. */
     onBack: LinkAuthFlowContextValue["back"];
+    /** A function to call when the user links an auth method. */
     onLink: LinkAuthFlowContextValue["link"];
+    /** A function to call when an auth method is successfully linked. */
     onLinkSuccess: LinkAuthFlowContextValue["linkSuccess"];
+    /** A ref to the flow transition. */
     transitionRef: LinkAuthFlowContextValueInternal["transitionRef"];
+    /** A ref that provides the ability to go back to the previous step of the sign in flow. */
     signInRef: LinkAuthFlowContextValueInternal["signInRef"];
 }
+/**
+ * A hook to get the link auth flow context value.
+ *
+ * @returns {LinkAuthFlowContextValueInternal} The link auth flow context value.
+ *
+ * @group Hooks
+ */
 export declare const useLinkAuthFlowInternal: () => LinkAuthFlowContextValueInternal;
+/**
+ * A hook to get the link auth flow context value.
+ *
+ * @returns {LinkAuthFlowContextValue} The link auth flow context value.
+ *
+ * @see {@link LinkAuthFlow}
+ * @see {@link LinkAuth}
+ *
+ * @group Hooks
+ */
 export declare const useLinkAuthFlow: () => {
+    /** A function to call when the back button is clicked. */
     back: () => void;
+    /** The direction of the flow transition. */
     direction?: "left" | "right";
+    /** A function to call when the user links an auth method. */
     link: (method: AuthMethod) => void;
+    /** A function to call when an auth method is successfully linked. */
     linkSuccess: () => void;
 };
+/**
+ * A provider for the link auth flow.
+ *
+ * @param {LinkAuthFlowProviderProps} props - The props for the LinkAuthFlowProvider component.
+ * @returns {JSX.Element} The LinkAuthFlowProvider component.
+ *
+ * @see {@link LinkAuthFlow}
+ * @see {@link LinkAuth}
+ *
+ * @group Components
+ */
 export declare const LinkAuthFlowProvider: ({ direction, children, onBack, onLink, onLinkSuccess, signInRef, transitionRef, }: LinkAuthFlowProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/LinkAuth/LinkAuthItem.d.ts

@@ -1,13 +1,36 @@
 import { MouseEventHandler, ReactNode } from 'react';
 import { LinkAuthMethod } from './types';
+/**
+ * The props for the LinkAuthItem component.
+ *
+ * @see {@link LinkAuthItem}
+ */
 interface LinkAuthItemProps {
+    /** A user-readable label for the auth method */
     authMethod: LinkAuthMethod["method"];
+    /** Whether the auth method is linked to the current user's account */
     isLinked: boolean;
+    /** Whether the auth method linking is pending */
     isPending?: boolean;
+    /** An icon to display */
     icon?: ReactNode;
+    /** A label for the auth method */
     label: string;
+    /** The user alias for the auth method (i.e. email address, phone number, etc.) */
     userAlias?: string;
+    /** A function to call when the auth method is linked. */
     onLink: MouseEventHandler<HTMLButtonElement>;
 }
+/**
+ * A component for displaying an auth method in the link auth list.
+ *
+ * @param {LinkAuthItemProps} props - The props for the LinkAuthItem component.
+ * @returns {JSX.Element} The LinkAuthItem component.
+ *
+ * @see {@link LinkAuthItems}
+ * @see {@link LinkAuth}
+ *
+ * @group Components
+ */
 declare const LinkAuthItem: ({ authMethod: _authMethod, userAlias, icon, isLinked, isPending, label, onLink, }: LinkAuthItemProps) => import("react/jsx-runtime").JSX.Element;
 export { LinkAuthItem, type LinkAuthItemProps };

package/dist/components/LinkAuth/LinkAuthItems.d.ts

@@ -1,9 +1,26 @@
 import { HTMLAttributes, ReactNode } from 'react';
 import { AuthMethod } from '../CDPReactProvider';
 import { LinkAuthItemProps } from './LinkAuthItem';
+/**
+ * The props for the LinkAuthItems component.
+ *
+ * @see {@link LinkAuthItems}
+ */
 interface LinkAuthItemsProps extends Omit<HTMLAttributes<HTMLUListElement>, "children"> {
+    /** A render function for the auth method item. */
     children?: (props: LinkAuthItemProps) => ReactNode;
+    /** A function to call when the link button is clicked. */
     onLink?: (method: AuthMethod) => void | Promise<void>;
 }
+/**
+ * A list of auth methods for linking to the current user's account.
+ *
+ * @param {LinkAuthItemsProps} props - The props for the LinkAuthItems component.
+ * @returns {JSX.Element} The LinkAuthItems component.
+ *
+ * @see {@link LinkAuth}
+ *
+ * @group Components
+ */
 declare const LinkAuthItems: ({ children, className, onLink, ...props }: LinkAuthItemsProps) => import("react/jsx-runtime").JSX.Element;
 export { LinkAuthItems, type LinkAuthItemsProps };

package/dist/components/LinkAuth/LinkAuthItems.js

@@ -1,44 +1,44 @@
-import { jsx as l } from "react/jsx-runtime";
-import { c as u } from "../../chunks/lite.1fxw3LjI.js";
-import { useMemo as b } from "react";
+import { jsx as e } from "react/jsx-runtime";
+import { c as b } from "../../chunks/lite.1fxw3LjI.js";
+import { useMemo as g } from "react";
 import "../../chunks/CDPReactProvider.0yuqyXCv.js";
-import { IconAppleLogo as g } from "../../icons/IconAppleLogo.js";
-import { IconEnvelope as d } from "../../icons/IconEnvelope.js";
-import { IconGoogleColorLogo as f } from "../../icons/IconGoogleColorLogo.js";
-import { IconPhone as L } from "../../icons/IconPhone.js";
-import { IconTelegramLogo as _ } from "../../icons/IconTelegramLogo.js";
-import { IconXLogo as A } from "../../icons/IconXLogo.js";
-import { LinkAuthItem as P } from "./LinkAuthItem.js";
-import { useLinkAuthContext as T } from "./LinkAuthProvider.js";
-import '../../assets/LinkAuthItems.css';const k = "LinkAuthItems-module__list___5AimM", x = {
-  list: k
-}, M = {
-  email: { Icon: /* @__PURE__ */ l(d, { "aria-label": "Email" }), label: "Email" },
-  sms: { Icon: /* @__PURE__ */ l(L, { "aria-label": "Phone" }), label: "Phone" },
-  "oauth:google": { Icon: /* @__PURE__ */ l(f, { "aria-label": "Google" }), label: "Google" },
-  "oauth:apple": { Icon: /* @__PURE__ */ l(g, { "aria-label": "Apple" }), label: "Apple" },
-  "oauth:x": { Icon: /* @__PURE__ */ l(A, { "aria-label": "X" }), label: "X" },
-  "oauth:telegram": { Icon: /* @__PURE__ */ l(_, { "aria-label": "Telegram" }), label: "Telegram" }
-}, O = ({ children: m, className: s = "", onLink: t, ...c }) => {
-  const { state: p, dispatch: a } = T(), { authMethods: i, isPending: r, methodToLink: n } = p, h = b(() => i.map((o) => {
-    const { Icon: e, label: I } = M[o.method];
+import { IconAppleLogo as d } from "../../icons/IconAppleLogo.js";
+import { IconEnvelope as f } from "../../icons/IconEnvelope.js";
+import { IconGoogleColorLogo as L } from "../../icons/IconGoogleColorLogo.js";
+import { IconPhone as _ } from "../../icons/IconPhone.js";
+import { IconTelegramLogo as A } from "../../icons/IconTelegramLogo.js";
+import { IconXLogo as P } from "../../icons/IconXLogo.js";
+import { LinkAuthItem as T } from "./LinkAuthItem.js";
+import { useLinkAuthContext as k } from "./LinkAuthProvider.js";
+import '../../assets/LinkAuthItems.css';const x = "LinkAuthItems-module__list___5AimM", M = {
+  list: x
+}, m = {
+  email: { Icon: /* @__PURE__ */ e(f, { "aria-label": "Email" }), label: "Email" },
+  sms: { Icon: /* @__PURE__ */ e(_, { "aria-label": "Phone" }), label: "Phone" },
+  "oauth:google": { Icon: /* @__PURE__ */ e(L, { "aria-label": "Google" }), label: "Google" },
+  "oauth:apple": { Icon: /* @__PURE__ */ e(d, { "aria-label": "Apple" }), label: "Apple" },
+  "oauth:x": { Icon: /* @__PURE__ */ e(P, { "aria-label": "X" }), label: "X" },
+  "oauth:telegram": { Icon: /* @__PURE__ */ e(A, { "aria-label": "Telegram" }), label: "Telegram" }
+}, O = ({ children: s, className: c = "", onLink: t, ...p }) => {
+  const { state: h, dispatch: a } = k(), { authMethods: i, isPending: r, methodToLink: n } = h, I = g(() => i.filter((o) => m[o.method]).map((o) => {
+    const { Icon: l, label: u } = m[o.method];
     return {
       ...o,
-      icon: e,
-      label: I,
+      icon: l,
+      label: u,
       onLink: async () => {
         a({ type: "LINK_AUTH_METHOD", payload: { method: o.method } }), await t?.(o.method);
       }
     };
   }), [i, a, t]);
-  return /* @__PURE__ */ l("ul", { className: u(x.list, s), ...c, children: h.map(({ method: o, ...e }) => /* @__PURE__ */ l("li", { children: m?.({
-    ...e,
+  return /* @__PURE__ */ e("ul", { className: b(M.list, c), ...p, children: I.map(({ method: o, ...l }) => /* @__PURE__ */ e("li", { children: s?.({
+    ...l,
     authMethod: o,
     isPending: r && n === o
-  }) || /* @__PURE__ */ l(
-    P,
+  }) || /* @__PURE__ */ e(
+    T,
     {
-      ...e,
+      ...l,
       authMethod: o,
       isPending: r && n === o
     }

package/dist/components/LinkAuth/LinkAuthProvider.d.ts

@@ -1,12 +1,43 @@
 import { Dispatch, ReactNode } from 'react';
 import { LinkAuthAction, LinkAuthState } from './types';
+/**
+ * The value of the link auth context.
+ *
+ * @see {@link useLinkAuthContext}
+ */
 interface LinkAuthContextValue {
+    /** The current state of the link auth component. */
     state: LinkAuthState;
+    /** The dispatch function for the link auth component. */
     dispatch: Dispatch<LinkAuthAction>;
 }
+/**
+ * Props for the LinkAuthProvider component.
+ *
+ * @see {@link LinkAuthProvider}
+ */
 interface LinkAuthProviderProps {
+    /** The children to render. */
     children: ReactNode;
 }
+/**
+ * A provider for the account linking context.
+ *
+ * @param {LinkAuthProviderProps} props - The props for the LinkAuthProvider component.
+ * @param {ReactNode} props.children - The children to render.
+ * @returns {JSX.Element} The LinkAuthProvider component.
+ *
+ * @group Components
+ */
 declare const LinkAuthProvider: ({ children }: LinkAuthProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * A hook to access the link auth context.
+ *
+ * @returns {LinkAuthContextValue} The link auth context.
+ *
+ * @see {@link LinkAuth}
+ *
+ * @group Hooks
+ */
 declare const useLinkAuthContext: () => LinkAuthContextValue;
 export { LinkAuthProvider, useLinkAuthContext, type LinkAuthProviderProps, type LinkAuthContextValue, };

package/dist/components/LinkAuth/LinkAuthTitle.d.ts

@@ -1,6 +1,23 @@
 import { ElementType, HTMLAttributes, ReactNode } from 'react';
+/**
+ * Props for the LinkAuthTitle component.
+ *
+ * @see {@link LinkAuthTitle}
+ */
 export interface LinkAuthTitleProps extends HTMLAttributes<HTMLElement> {
+    /** The element type to render the title as. */
     as?: ElementType;
+    /** The children of the component. */
     children?: ReactNode;
 }
+/**
+ * A title for the LinkAuth component.
+ *
+ * @param {LinkAuthTitleProps} props - The props for the component.
+ * @returns {JSX.Element} The LinkAuthTitle component.
+ *
+ * @see {@link LinkAuth}
+ *
+ * @group Components
+ */
 export declare const LinkAuthTitle: ({ as: Component, children, className, ...props }: LinkAuthTitleProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/LinkAuth/index.d.ts

@@ -8,10 +8,180 @@ import { LinkAuthItems, LinkAuthItemsProps } from './LinkAuthItems';
 import { useLinkAuthContext, LinkAuthContextValue } from './LinkAuthProvider';
 import { LinkAuthTitle, LinkAuthTitleProps } from './LinkAuthTitle';
 import { LinkAuthState, LinkAuthMethod, LinkAuthAction } from './types';
+/**
+ * Props for the LinkAuth component
+ *
+ * @see {@link LinkAuth}
+ */
 interface LinkAuthProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * The children of the component. Leave empty to use the default UI.
+     *
+     * If a function is provided, it will be called with the current state of the link auth flow.
+     * The function should return a `ReactNode`.
+     */
     children?: ReactNode | ((state: LinkAuthState) => ReactNode);
+    /** A function to call when an auth method is successfully linked. */
     onLinkSuccess?: (method: AuthMethod | null) => void;
 }
+/**
+ * A component for displaying an error banner in the LinkAuth component.
+ *
+ * @param {HTMLAttributes<HTMLDivElement>} props - The props for the LinkAuthError component.
+ * @returns {JSX.Element} The LinkAuthError component.
+ *
+ * @group Components
+ */
 declare const LinkAuthError: ({ role, ...props }: HTMLAttributes<HTMLDivElement>) => import("react/jsx-runtime").JSX.Element | null;
+/**
+ * A component for managing linked authentication methods for the current user.
+ *
+ * This component displays a list of available authentication methods (email, phone, OAuth providers)
+ * and allows users to link or unlink them from their account.
+ *
+ * @param {LinkAuthProps} props - The props for the component.
+ * @param {(method: string) => void} [props.onLinkSuccess] - A function to call when an auth method is successfully linked.
+ * @returns {JSX.Element} The LinkAuth component.
+ *
+ * @group Components
+ *
+ * @document ./README.md
+ *
+ * @see {@link LinkAuthError}
+ * @see {@link LinkAuthFlow}
+ * @see {@link LinkAuthFlowBackButton}
+ * @see {@link LinkAuthItem}
+ * @see {@link LinkAuthItems}
+ * @see {@link LinkAuthTitle}
+ * @see {@link useLinkAuthContext}
+ * @see {@link useLinkAuthFlow}
+ *
+ * @example
+ * ```tsx lines
+ * // Render the LinkAuth component with a custom success handler
+ *
+ * function App() {
+ *   return (
+ *     <CDPReactProvider config={config}>
+ *       <LinkAuth onLinkSuccess={method => console.log(`Linked ${method}`)} />
+ *     </CDPReactProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx lines
+ * // Recreate the default UI
+ *
+ * function App() {
+ *   return (
+ *     <CDPReactProvider config={config}>
+ *       <LinkAuth>
+ *         <div className="header">
+ *           <LinkAuthTitle />
+ *           <LinkAuthFlowBackButton />
+ *         </div>
+ *         <div className="error">
+ *           <LinkAuthError />
+ *         </div>
+ *         <LinkAuthFlow />
+ *       </LinkAuth>
+ *     </CDPReactProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx lines
+ * // Add a message based on the LinkAuth state
+ *
+ * function App() {
+ *   return (
+ *     <CDPReactProvider config={config}>
+ *       <LinkAuth>
+ *         {state => (
+ *           <>
+ *             <div className="header">
+ *               <LinkAuthTitle />
+ *               <LinkAuthFlowBackButton />
+ *             </div>
+ *             {state.methodToLink && (
+ *               <p className="message">
+ *                 Linking {state.methodToLink}...
+ *               </p>
+ *             )}
+ *             <div className="error">
+ *               <LinkAuthError />
+ *             </div>
+ *             <LinkAuthFlow />
+ *           </>
+ *         )}
+ *       </LinkAuth>
+ *     </CDPReactProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx lines
+ * // Customize LinkAuthItems to show a modal for non-OAuth methods instead of transitioning in place.
+ *
+ * function CustomLinkAuthItems() {
+ *   const { link, back } = useLinkAuthFlow();
+ *   const { authMethods } = useAppConfig();
+ *   const [openModal, setOpenModal] = useState<AuthMethod | null>(null);
+ *
+ *   const modalMethods = useMemo(
+ *     () => authMethods.filter(method => !method.startsWith("oauth:")),
+ *     [authMethods],
+ *   );
+ *
+ *   const handleClose = useCallback(() => {
+ *     setOpenModal(null);
+ *     back();
+ *   }, [back, setOpenModal]);
+ *
+ *  const handleLink = useCallback(
+ *    (method: AuthMethod) => {
+ *      link(method);
+ *      if (!method.startsWith("oauth:")) {
+ *        setOpenModal(method);
+ *      }
+ *    },
+ *    [link, setOpenModal],
+ *  );
+ *
+ *   return (
+ *     <>
+ *       <LinkAuthItems onLink={handleLink} />
+ *       {modalMethods.map(method => {
+ *         return (
+ *           <SignInModal
+ *             key={method}
+ *             open={openModal === method}
+ *             authMethods={[method]}
+ *             setIsOpen={isOpen => (isOpen ? setOpenModal(method) : handleClose())}
+ *             onSuccess={() => setOpenModal(null)}
+ *           >
+ *             <SignInModalTrigger>null</SignInModalTrigger>
+ *           </SignInModal>
+ *         );
+ *       })}
+ *     </>
+ *   );
+ * };
+ *
+ * function App() {
+ *   return (
+ *     <CDPReactProvider config={config}>
+ *       <LinkAuth>
+ *         <h2>Link a profile</h2>
+ *         <CustomLinkAuthItems />
+ *       </LinkAuth>
+ *     </CDPReactProvider>
+ *   );
+ * }
+ * ```
+ */
 declare const LinkAuth: (props: LinkAuthProps) => import("react/jsx-runtime").JSX.Element;
 export { LinkAuthError, LinkAuthFlow, LinkAuthFlowBackButton, LinkAuthItem, LinkAuthItems, LinkAuthTitle, LinkAuth, useLinkAuthContext, useLinkAuthFlow, type LinkAuthAction, type LinkAuthContextValue, type LinkAuthFlowBackButtonProps, type LinkAuthFlowContextValue, type LinkAuthFlowProps, type LinkAuthItemProps, type LinkAuthItemsProps, type LinkAuthMethod, type LinkAuthProps, type LinkAuthState, type LinkAuthTitleProps, };

package/dist/components/LinkAuth/types.d.ts

@@ -1,15 +1,40 @@
 import { AuthMethod } from '../CDPReactProvider';
+/**
+ * Representation of auth method
+ *
+ * @see {@link LinkAuthState}
+ * @see {@link LinkAuth}
+ */
 export type LinkAuthMethod = {
+    /** Whether the user has this auth method linked to their account */
     isLinked: boolean;
+    /** The auth method */
     method: AuthMethod;
+    /** The user's identifier for this auth method (i.e. email address, phone number, etc.) */
     userAlias: string;
 };
+/**
+ * The state of the account linking component
+ *
+ * @see {@link LinkAuthAction}
+ * @see {@link LinkAuth}
+ */
 export interface LinkAuthState {
+    /** The auth methods with data about the user and whether they are linked */
     authMethods: LinkAuthMethod[];
+    /** Error message if fetching linked accounts failed */
     error: string | null;
+    /** Whether the account linking is pending */
     isPending: boolean;
+    /** The auth method to link */
     methodToLink: AuthMethod | null;
 }
+/**
+ * The actions that can be performed on the LinkAuth state.
+ *
+ * @see {@link LinkAuthState}
+ * @see {@link LinkAuth}
+ */
 export type LinkAuthAction = {
     type: "LINK_AUTH_METHOD";
     payload: {
@@ -28,5 +53,11 @@ export type LinkAuthAction = {
 } | {
     type: "RESET_STATE";
 };
+/**
+ * The views of the link auth flow.
+ */
 export declare const LINK_AUTH_FLOW_VIEWS: readonly ["list", "email", "sms"];
+/**
+ * The view of the link auth flow.
+ */
 export type LinkAuthFlowView = (typeof LINK_AUTH_FLOW_VIEWS)[number];

package/dist/components/LinkAuth/utils.d.ts

@@ -1,4 +1,16 @@
 import { AuthMethod } from '../CDPReactProvider';
 import { LinkAuthFlowView } from './types';
+/**
+ * Typeguard function to checks if a string is a valid view for the link auth flow.
+ *
+ * @param view - The string to check.
+ * @returns {boolean} Whether the view is a valid view.
+ */
 export declare const isView: (view: string) => view is LinkAuthFlowView;
+/**
+ * Converts a method to a view for the link auth flow.
+ *
+ * @param method - The method to convert to a view.
+ * @returns {LinkAuthFlowView} The view for the method. If the method is not a valid view, returns "list".
+ */
 export declare const methodToView: (method: AuthMethod | null) => LinkAuthFlowView;