@ory/elements-react 1.0.0-rc.5 → 1.0.0-rc.6

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { UiNodeInputAttributes, UiNode, UiNodeAnchorAttributes, UiNodeTextAttributes, UiNodeImageAttributes, UiNodeGroupEnum, UiText, FlowType, LoginFlow, RegistrationFlow, RecoveryFlow, VerificationFlow, SettingsFlow, UiContainer, OAuth2ConsentRequest, Session, FlowError, ConfigurationParameters, AccountExperienceConfiguration, UpdateLoginFlowBody, UpdateRegistrationFlowBody, UpdateVerificationFlowBody, UpdateRecoveryFlowBody, UpdateSettingsFlowBody, OnRedirectHandler, FrontendApi } from '@ory/client-fetch';
-import { ComponentPropsWithoutRef, FormEventHandler, MouseEventHandler, PropsWithChildren, DetailedHTMLProps, HTMLAttributes, ComponentType, Dispatch } from 'react';
+import { UiNodeInputAttributes, UiNode, UiNodeAnchorAttributes, UiNodeTextAttributes, UiNodeImageAttributes, UiText, FlowType, LoginFlow, RegistrationFlow, RecoveryFlow, VerificationFlow, SettingsFlow, UiContainer, OAuth2ConsentRequest, Session, FlowError, ConfigurationParameters, AccountExperienceConfiguration, UpdateLoginFlowBody, UpdateRegistrationFlowBody, UpdateVerificationFlowBody, UpdateRecoveryFlowBody, UpdateSettingsFlowBody, OnRedirectHandler, UiNodeGroupEnum, FrontendApi } from '@ory/client-fetch';
+import { ComponentPropsWithoutRef, PropsWithChildren, FormEventHandler, MouseEventHandler, ComponentType, Dispatch } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -31,6 +31,10 @@ type OryCardLogoProps = Record<string, never>;
 type OryNodeCaptchaProps = {
     node: UiNode;
 };
+/**
+ * Props for the Form.Group component.
+ */
+type OryFormGroupProps = PropsWithChildren;
 /**
  * Props for the AuthMethodListItem component. This component is used
  * to render a single auth method in the AuthMethodList component.
@@ -51,9 +55,11 @@ type OryNodeImageProps = {
  * A generic type for the form values.
  */
 type FormValues = Record<string, string | boolean | number | undefined>;
+/**
+ * Props for the Form.Root component.
+ */
 type OryFormRootProps = ComponentPropsWithoutRef<"form"> & {
     onSubmit: FormEventHandler<HTMLFormElement>;
-    "data-testid"?: string;
 };
 type OryNodeInputProps = {
     attributes: UiNodeInputAttributes;
@@ -74,8 +80,17 @@ type OryFormSectionFooterProps = PropsWithChildren<{
 }>;
 
 type OryCardHeaderProps = Record<string, never>;
+/**
+ * Returns the header of the Ory Card.
+ *
+ * @returns The header of the Ory Card.
+ * @group Components
+ */
 declare function OryCardHeader(): react_jsx_runtime.JSX.Element;
 
+/**
+ * @interface
+ */
 type OryCardRootProps = PropsWithChildren;
 /**
  * The root component of the Ory Card.
@@ -86,10 +101,16 @@ type OryCardRootProps = PropsWithChildren;
  *
  * @param props - pass children to render instead of the default Ory Card components
  * @returns
+ * @group Components
  */
 declare function OryCard({ children }: PropsWithChildren): react_jsx_runtime.JSX.Element;
 
 type OryCardFooterProps = Record<string, never>;
+/**
+ *
+ * @returns The footer of a card component.
+ * @group Components
+ */
 declare function OryCardFooter(): react_jsx_runtime.JSX.Element;
 
 /**
@@ -106,11 +127,42 @@ type OryCardContentProps = PropsWithChildren;
  *
  * @param props - pass children to render instead of the default Ory Card components
  * @returns
+ * @group Components
  */
 declare function OryCardContent({ children }: OryCardContentProps): react_jsx_runtime.JSX.Element;
 
-declare function OryTwoStepCard(): react_jsx_runtime.JSX.Element;
+/**
+ * The `OrySelfServiceFlowCard` component is an umbrella component that can render the self-service flows.
+ *
+ * Note: prefer using the {@link @ory/elements-react/theme!Login | <Login /> component}, etc. directly instead of this component.
+ *
+ * It renders different forms based on the current flow state, such as providing an identifier,
+ * entering a password or one time code or selecting a method for authentication.
+ *
+ * The component must be use within an {@link OryProvider} that provides the flow context and components to use.
+ *
+ * @example
+ * ```jsx
+ * import { OrySelfServiceFlowCard } from "@ory/elements-react";
+ *
+ * function MyComponent() {
+ *  return <OryProvider ...>
+ *    <OrySelfServiceFlowCard />
+ *  </OryProvider>;
+ * }
+ * ```
+ *
+ * @returns The Ory Two-Step Card component that renders different forms based on the current flow state.
+ * @group Components
+ */
+declare function OrySelfServiceFlowCard(): react_jsx_runtime.JSX.Element;
 
+/**
+ * The `OryConsentCard` component renders a card for displaying the OAuth2 consent flow.
+ *
+ * @returns The consent card component.
+ * @group Components
+ */
 declare function OryConsentCard(): react_jsx_runtime.JSX.Element;
 
 /**
@@ -118,19 +170,38 @@ declare function OryConsentCard(): react_jsx_runtime.JSX.Element;
  */
 type OryCardDividerProps = Record<string, never>;
 /**
- * Renders the @see Card.Divider between the groups of nodes in the Ory Form.
+ * Renders the {@link OryFlowComponents.Card.Divider} between the groups of nodes in the Ory Form.
  *
  * You can use this component to build fully custom implementations of the Ory Flows.
  *
  * However, you most likely want to override the individual components instead.
  *
  * @returns
+ * @group Components
  */
 declare function OryFormGroupDivider(): react_jsx_runtime.JSX.Element | null;
 
 type OryPageHeaderProps = Record<never, never>;
-declare const HeadlessPageHeader: () => react_jsx_runtime.JSX.Element;
+/**
+ * The OryPageHeader component renders the header of the page.
+ *
+ * Customize the header by providing a custom {@link OryFlowComponents.Page.Header} component in the `components` prop of the {@link OryProvider}.
+ *
+ * @returns a React component that renders the page header.
+ * @group Components
+ */
+declare const OryPageHeader: () => react_jsx_runtime.JSX.Element;
 
+/**
+ * Renders the Ory Settings Card component.
+ *
+ * This component is used to display the settings flow for the user.
+ * It utilizes the `useOryFlow` hook to access the current flow and renders the nodes with components
+ * provided by the Ory Elements context.
+ *
+ * @returns The Ory Settings Card component that renders the settings flow.
+ * @group Components
+ */
 declare function OrySettingsCard(): react_jsx_runtime.JSX.Element;
 
 type OrySettingsRecoveryCodesProps = {
@@ -147,7 +218,7 @@ type OrySettingsTotpProps = {
     totpUnlink: UiNode | undefined;
     onUnlink: () => void;
 };
-type OrySettingsOidcProps = {
+type OrySettingsSsoProps = {
     linkButtons: (UiNode & {
         onClick: () => void;
     })[];
@@ -173,39 +244,106 @@ type OrySettingsPasskeyProps = {
     })[];
 };
 
-type OryFormGroupsProps = PropsWithChildren<{
-    groups: UiNodeGroupEnum[];
-}>;
-type OryFormGroupProps = PropsWithChildren;
-declare function OryFormGroups({ groups }: OryFormGroupsProps): react_jsx_runtime.JSX.Element;
-
+/**
+ * Props for the OryMessageContent component.
+ *
+ * @interface
+ */
 type OryMessageContentProps = {
+    /**
+     * The message to display.
+     */
     message: UiText;
 };
-type OryMessageRootProps = DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>;
-declare function OryCardValidationMessages({ ...props }: OryMessageRootProps): react_jsx_runtime.JSX.Element | null;
+/**
+ *
+ * @interface
+ * @expand
+ */
+type OryMessageRootProps = PropsWithChildren;
+/**
+ * Props for the {@link OryCardValidationMessages} component.
+ *
+ * @inline
+ * @hidden
+ */
+interface OryCardValidationMessagesProps {
+    /**
+     * An array of message IDs that should be hidden.
+     * This is useful for hiding specific messages that are not relevant to the user or are rendered elsewhere.
+     * If not provided, the default list of message IDs to hide will be used.
+     * @default [1040009, 1060003, 1080003, 1010004, 1010014, 1040005, 1010016, 1010003]
+     *
+     * @see https://www.ory.sh/docs/kratos/concepts/ui-messages
+     */
+    hiddenMessageIds?: number[];
+}
+/**
+ * Renders the {@link OryFlowComponents.Message.Content} component for each message in the current flow.
+ *
+ * See also {@link useOryFlow}
+ * @returns
+ * @group Components
+ */
+declare function OryCardValidationMessages({ hiddenMessageIds, }: OryCardValidationMessagesProps): react_jsx_runtime.JSX.Element | null;
 
-type OryFormProps$1 = Omit<ComponentPropsWithoutRef<"form">, "action" | "method" | "onSubmit">;
-type OryFormSectionProps = PropsWithChildren<OryFormProps$1 & {
+/**
+ * Props for the OrySettingsFormSection component.
+ * This type extends the form element props but omits the `action`, `method`, and `onSubmit` properties.
+ */
+type OrySettingsFormProps = Omit<ComponentPropsWithoutRef<"form">, "action" | "method" | "onSubmit">;
+/**
+ * Props for the OrySettingsFormSection component.
+ *
+ * @inline
+ * @hidden
+ */
+interface OryFormSectionProps extends PropsWithChildren, OrySettingsFormProps {
     nodes?: UiNode[];
-}>;
-type OryCardSettingsSectionProps = PropsWithChildren & {
+}
+interface OryCardSettingsSectionProps extends PropsWithChildren {
     action: string;
     method: string;
     onSubmit: FormEventHandler<HTMLFormElement>;
-};
-declare function OryFormSection({ children, nodes, ...rest }: OryFormSectionProps): react_jsx_runtime.JSX.Element;
+}
+/**
+ * OrySettingsFormSection is a component that provides a form section for Ory settings.
+ *
+ * Can be used independently to render a form section with Ory nodes.
+ *
+ * @param props - The properties for the OrySettingsFormSection component.
+ * @returns
+ * @group Components
+ */
+declare function OrySettingsFormSection({ children, nodes, ...rest }: OryFormSectionProps): react_jsx_runtime.JSX.Element;
 
-type OryFormOidcRootProps = PropsWithChildren<{
+type OryFormSsoRootProps = PropsWithChildren<{
     nodes: UiNode[];
 }>;
-type OryNodeOidcButtonProps = {
+/**
+ * Props for the OryNodeSsoButton component.
+ */
+type OryNodeSsoButtonProps = {
     node: UiNode;
     attributes: UiNodeInputAttributes;
     onClick?: () => void;
 };
-declare function OryFormOidcButtons(): react_jsx_runtime.JSX.Element | null;
-declare function OryFormSocialButtonsForm(): react_jsx_runtime.JSX.Element | null;
+/**
+ * Renders the flow's OIDC buttons.
+ *
+ * @returns a React component that renders the OIDC buttons.
+ * @group Components
+ */
+declare function OryFormSsoButtons(): react_jsx_runtime.JSX.Element | null;
+/**
+ * The `OryFormSsoForm` component renders the Ory Form for SSO methods (OIDC and SAML).
+ *
+ * It needs to be its own form, as the OIDC buttons are form submits but are not related to the main form.
+ *
+ * @returns a React component that renders the Ory Form for SSO methods.
+ * @group Components
+ */
+declare function OryFormSsoForm(): react_jsx_runtime.JSX.Element | null;
 
 /**
  * A record of all the components that are used in the OryForm component.
@@ -217,11 +355,11 @@ type OryFlowComponents = {
          */
         Button: ComponentType<OryNodeButtonProps>;
         /**
-         * The SocialButton component is rendered whenever a button of group "oidc" node is encountered.
+         * The SsoButton component is rendered whenever a button of group "oidc" or "saml" node is encountered.
          *
          * It renders the "Login with Google", "Login with Facebook" etc. buttons.
          */
-        OidcButton: ComponentType<OryNodeOidcButtonProps>;
+        SsoButton: ComponentType<OryNodeSsoButtonProps>;
         /**
          * Anchor component, rendered whenever an "anchor" node is encountered
          */
@@ -327,7 +465,7 @@ type OryFlowComponents = {
          *
          * You most likely don't want to override this component directly.
          */
-        OidcRoot: ComponentType<OryFormOidcRootProps>;
+        SsoRoot: ComponentType<OryFormSsoRootProps>;
         /**
          * The FormGroup is rendered around each group of nodes in the UI nodes.
          */
@@ -335,7 +473,7 @@ type OryFlowComponents = {
         /**
          * The section on the settings page, rendering the OIDC settings
          */
-        OidcSettings: ComponentType<OrySettingsOidcProps>;
+        SsoSettings: ComponentType<OrySettingsSsoProps>;
         /**
          * The section on the settings page, rendering the Webauthn settings
          */
@@ -362,94 +500,176 @@ type OryFlowComponents = {
          * The Message component is rendered whenever a message is encountered.
          */
         Content: ComponentType<OryMessageContentProps>;
+        /**
+         * The Toast component is rendered for toast messages.
+         *
+         * Currently only used in the settings page to display messages.
+         */
+        Toast: ComponentType<OryToastProps>;
     };
     Page: {
         Header: ComponentType<OryPageHeaderProps>;
     };
 };
-type DeepPartialTwoLevels<T> = {
-    [P in keyof T]?: T[P] extends object ? {
-        [K in keyof T[P]]?: T[P][K];
-    } : T[P];
+type OryToastProps = {
+    message: UiText;
+    id: string | number;
+};
+/**
+ * Makes the components in OryFlowComponents optional, so that you can override only the components you want to change.
+ */
+type OryFlowComponentOverrides = {
+    [P in keyof OryFlowComponents]?: OryFlowComponents[P] extends object ? {
+        [K in keyof OryFlowComponents[P]]?: OryFlowComponents[P][K];
+    } : OryFlowComponents[P];
 };
-type OryFlowComponentOverrides = DeepPartialTwoLevels<OryFlowComponents>;
-type OryFormProps = PropsWithChildren<{
+/**
+ * The props for the OryForm component.
+ * @inline
+ * @hidden
+ */
+interface OryFormProps extends PropsWithChildren {
+    /**
+     * A callback function that is called after the form is submitted.
+     *
+     * It is always called after the form is submitted, unless the form submission is prevented by client side
+     * validation or the API response dictated that the client should be redirected
+     *
+     * @param method - The method that was submitted.
+     */
     onAfterSubmit?: (method: string | number | boolean | undefined) => void;
-    "data-testid"?: string;
-}>;
-declare function OryForm({ children, onAfterSubmit, "data-testid": dataTestId, }: OryFormProps): react_jsx_runtime.JSX.Element;
+}
+/**
+ * The OryForm component is the main form container for Ory flows.
+ *
+ * It renders the form with the correct action and method, and handles the submission of the form.
+ *
+ * @param props - The props for the OryForm component.
+ * @returns
+ * @group Components
+ */
+declare function OryForm({ children, onAfterSubmit }: OryFormProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * The `useComponents` hook provides access to the Ory Flow components provided in the `OryComponentProvider`.
+ *
+ * You can use this hook to access the components defined in the `components` prop of the `OryComponentProvider`.
+ *
+ * @returns the current component context value.
+ * @group Hooks
+ */
 declare function useComponents(): OryFlowComponents;
+/**
+ * The `useNodeSorter` hook provides a way to access the node sorting function
+ *
+ * The node sorting function is used to determine the order of nodes in a flow based on their attributes and context.
+ *
+ * To customize the sorting behavior, you can provide a custom `nodeSorter` function to the `OryComponentProvider`.
+ *
+ * @returns a function that sorts nodes based on the provided context.
+ * @group Hooks
+ */
 declare function useNodeSorter(): (a: UiNode, b: UiNode, ctx: {
     flowType: string;
 }) => number;
 
 /**
- * A generic flow container, containing a flowType, the flow itself and the config object
- *
- * @see OryClientConfiguration
+ * A flow container for the {@link LoginFlow}
+ * @interface
  */
-type OryFlow<TFlowType extends FlowType, TFlow> = {
-    flowType: TFlowType;
-    flow: TFlow;
+type LoginFlowContainer = {
+    flowType: FlowType.Login;
+    flow: LoginFlow;
 };
 /**
- * A flow container for the login flow
- *
- * @see OryFlow
- * @see LoginFlow
+ * A flow container for the {@link RegistrationFlow}
+ * @interface
  */
-type LoginFlowContainer = OryFlow<FlowType.Login, LoginFlow>;
+type RegistrationFlowContainer = {
+    flowType: FlowType.Registration;
+    flow: RegistrationFlow;
+};
 /**
- * A flow container for the registration flow
- *
- * @see OryFlow
- * @see RegistrationFlow
+ * A flow container for the {@link RecoveryFlow}
+ * @interface
  */
-type RegistrationFlowContainer = OryFlow<FlowType.Registration, RegistrationFlow>;
+type RecoveryFlowContainer = {
+    flowType: FlowType.Recovery;
+    flow: RecoveryFlow;
+};
 /**
- * A flow container for the recovery flow
- *
- * @see OryFlow
- * @see RecoveryFlow
+ * A flow container for the {@link VerificationFlow}
+ * @interface
  */
-type RecoveryFlowContainer = OryFlow<FlowType.Recovery, RecoveryFlow>;
+type VerificationFlowContainer = {
+    flowType: FlowType.Verification;
+    flow: VerificationFlow;
+};
 /**
- * A flow container for the verification flow
- *
- * @see OryFlow
- * @see VerificationFlow
- *
+ * A flow container for the {@link SettingsFlow}
+ * @interface
  */
-type VerificationFlowContainer = OryFlow<FlowType.Verification, VerificationFlow>;
+type SettingsFlowContainer = {
+    flowType: FlowType.Settings;
+    flow: SettingsFlow;
+};
 /**
- * A flow container for the settings flow
- *
- * @see OryFlow
- * @see SettingsFlow
+ * A flow container for the {@link FlowError}
+ * @interface
  */
-type SettingsFlowContainer = OryFlow<FlowType.Settings, SettingsFlow>;
+type ErrorFlowContainer = {
+    flowType: FlowType.Error;
+    flow: FlowError;
+};
 /**
- * A flow container for the error flow
- *
- * @see OryFlow
- * @see FlowError (Error flow)
+ * A flow container for the OAuth2 consent flow
  *
+ * Note: This is a polyfill for the OAuth2 consent flow, which is not yet implemented in the Ory SDK.
+ * It tries to mirror the structure of the other flow containers as closely as possible.
+ * @interface
  */
-type ErrorFlowContainer = OryFlow<FlowType.Error, FlowError>;
 type ConsentFlow = {
+    /**
+     * When the flow was created.
+     */
     created_at: Date;
+    /**
+     * When the flow expires.
+     */
     expires_at: Date;
-    id: string;
+    /**
+     * Always "UNSET" as the consent flow does not have a specific ID.
+     */
+    id: "UNSET";
+    /**
+     * When the flow was issued.
+     */
     issued_at: Date;
+    /**
+     * The state of the consent flow.
+     *
+     * - "show_form": The form is being shown to the user.
+     * - "rejected": The user has rejected the consent request.
+     * - "accepted": The user has accepted the consent request.
+     */
     state: "show_form" | "rejected" | "accepted";
-    active: string;
+    /**
+     * The active part of the flow, which is always "oauth2_consent" for this flow.
+     */
+    active: "oauth2_consent";
     ui: UiContainer;
     consent_request: OAuth2ConsentRequest;
     session: Session;
     return_to?: string;
 };
-type ConsentFlowContainer = OryFlow<FlowType.OAuth2Consent, ConsentFlow>;
+/**
+ * A flow container for the OAuth2 {@link ConsentFlow}
+ * @interface
+ */
+type ConsentFlowContainer = {
+    flowType: FlowType.OAuth2Consent;
+    flow: ConsentFlow;
+};
 /**
  * A union type of all flow containers
  */
@@ -459,12 +679,25 @@ type LocaleMap = Record<string, Record<string, string>>;
 declare const OryLocales: LocaleMap;
 
 type Locale = keyof typeof OryLocales;
-type IntlContextProps = {
+
+/**
+ * The configuration for internationalization (i18n) in Ory Elements.
+ *
+ * This configuration is used to set the locale and can be used to provide custom translations.
+ * The locale is used to determine the language of the UI.
+ */
+type IntlConfig = {
+    /**
+     * The locale to use for internationalization.
+     *
+     * @defaultValue "en"
+     */
     locale: Locale;
+    /**
+     * Provide custom translations for the UI.
+     */
     customTranslations?: Partial<LocaleMap>;
 };
-
-type IntlConfig = IntlContextProps;
 /**
  * The configuration for Ory Elements.
  *
@@ -475,13 +708,21 @@ type IntlConfig = IntlContextProps;
  * You can also set the name of the application, the logo URL, and the SDK configuration.
  * By default, the name and logo are displayed in the card's header.
  */
-type OryClientConfiguration = {
+interface OryClientConfiguration {
     /**
      * The SDK configuration.
      * This configuration is used to set the URL of the Ory SDK and any additional options used for the SDK client.
      */
     sdk?: {
+        /**
+         * The URL the Ory SDK should connect to.
+         * This is typically the base URL of your Ory instance.
+         */
         url?: string;
+        /**
+         * Additional parameters for the Ory SDK configuration.
+         * This can include options like headers, credentials, and other settings.
+         */
         options?: Partial<ConfigurationParameters>;
     };
     /**
@@ -495,7 +736,7 @@ type OryClientConfiguration = {
      * The configuration for the project.
      */
     project: AccountExperienceConfiguration;
-};
+}
 
 /**
  * Converts a UiText to a FormattedMessage.
@@ -503,41 +744,46 @@ type OryClientConfiguration = {
  * The context is used to inject values into the message from Ory, e.g. a timestamp.
  * For example a UI Node from Ory might look like this:
  *
- * \{
+ * ```json
+ * {
  *  "type":"input",
  *  "group":"default",
- *  "attributes": \{
+ *  "attributes": {
  *      "name":"traits.email",
  *      "type":"email",
  *      "required":true,
  *      "autocomplete":"email",
  *      "disabled":false,
  *      "node_type":"input"
- *  \},
+ *  },
  *  "messages":[],
- *  "meta": \{
- *    "label": \{
+ *  "meta": {
+ *    "label": {
  *      "id":1070002,
  *      "text":"E-Mail",
  *      "type":"info",
- *      "context":\{
+ *      "context":{
  *        "title":"E-Mail"
- *      \},
- *    \}
- *  \}
- * \}
+ *      },
+ *    }
+ *  }
+ * }
+ * ```
  *
  * The context has the key "title" which matches the formatter template name "\{title\}"
  * An example translation file would look like this:
- * \{
- *  "identities.messages.1070002": "\{title\}"
- * \}
+ * ```json
+ * {
+ *  "identities.messages.1070002": "{title}"
+ * }
+ * ```
  *
  * The formatter would then take the meta.label.id and look for the translation with the key matching the id.
  * It would then replace the template "\{title\}" with the value from the context with the key "title".
  *
  * @param uiText - The UiText is part of the UiNode object sent by Kratos when performing a flow.
  * @param intl - The intl object from react-intl
+ * @group Utilities
  */
 declare const uiTextToFormattedMessage: ({ id, context, text }: Omit<UiText, "type">, intl: IntlShape) => string;
 
@@ -564,6 +810,7 @@ type OnSubmitHandlerProps<T extends UpdateLoginFlowBody | UpdateRegistrationFlow
  *
  * @param message - the UiText message to generate a test id for
  * @returns a unique, stable test id for the message
+ * @group Utilities
  */
 declare function messageTestId(message: {
     id: number | string;
@@ -571,28 +818,87 @@ declare function messageTestId(message: {
     "data-testid": string;
 };
 
+/**
+ * Represents the state of the form when selecting an authentication method.
+ * This type is used when the user is in the process of selecting an authentication method
+ * (e.g., password, passkey, etc.) during the login or registration flow.
+ * @inline
+ * @hidden
+ */
 type FormStateSelectMethod = {
     current: "select_method";
 };
+/**
+ * Represents the state of the form when providing an identifier.
+ * This type is used when the user is required to provide an identifier (e.g., email or username)
+ * before proceeding with the authentication flow.
+ * @inline
+ * @hidden
+ */
 type FormStateProvideIdentifier = {
     current: "provide_identifier";
 };
+/**
+ * Represents the state of the form when an authentication method is active.
+ * This type is used when the user is interacting with a specific authentication method
+ * (e.g., entering a password or entering a code received via email).
+ *
+ * The `method` field indicates which authentication method is currently active.
+ * @inline
+ * @hidden
+ */
 type FormStateMethodActive = {
     current: "method_active";
     method: UiNodeGroupEnum;
 };
+/**
+ * Represents the state of the form based on the flow type and active method.
+ * This type is used to determine which part of the form should be displayed.
+ *
+ * It can be one of the following:
+ * - `select_method`: The user is selecting an authentication method.
+ * - `provide_identifier`: The user is providing an identifier (e.g., email or username).
+ * - `method_active`: An authentication method is active, and the user is interacting with it.
+ * - `success_screen`: The flow has successfully completed (only used in the verification flow).
+ * - `settings`: The user is in the settings flow.
+ */
 type FormState = FormStateSelectMethod | FormStateProvideIdentifier | FormStateMethodActive | {
     current: "success_screen";
 } | {
     current: "settings";
 };
+/**
+ * Represents the actions that can be dispatched to update the form state.
+ * These actions are used to change the current state of the form based on user interactions or flow updates.
+ */
 type FormStateAction = {
+    /**
+     * Action to update the flow state.
+     * This action is dispatched when the flow is updated, and it will parse the new flow
+     * to determine the current form state.
+     */
     type: "action_flow_update";
+    /**
+     * The updated flow container that contains the new flow data.
+     */
     flow: OryFlowContainer;
 } | {
+    /**
+     * Action to select an authentication method.
+     * This action is dispatched when the user selects an authentication method
+     * (e.g., password, passkey, etc.) from the available options.
+     */
     type: "action_select_method";
+    /**
+     * The authentication method that the user has selected.
+     */
     method: UiNodeGroupEnum;
 } | {
+    /**
+     * Action to clear the active authentication method.
+     * This action is dispatched when the user wants to clear the currently active method
+     * and return to the method selection state.
+     */
     type: "action_clear_active_method";
 };
 
@@ -600,10 +906,12 @@ type FormStateAction = {
  * Returns an object that contains the current flow and the flow type, as well as the configuration.
  *
  * @returns The current flow container
+ * @group Hooks
  */
 declare function useOryFlow(): FlowContextValue;
 /**
  * Function to set the flow container.
+ * @interface
  */
 type FlowContainerSetter = Dispatch<OryFlowContainer>;
 /**
@@ -625,16 +933,90 @@ type FlowContextValue = OryFlowContainer & {
     dispatchFormState: Dispatch<FormStateAction>;
 };
 
+/**
+ * Props type for the OryProvider component.
+ */
 type OryProviderProps = {
+    /**
+     * The components to use for rendering Ory flows.
+     * You can provide custom components to override the default Ory components.
+     */
     components: OryFlowComponents;
+    /**
+     * The Ory client configuration.
+     * This includes the SDK and project configuration.
+     */
     config: OryClientConfiguration;
 } & OryFlowContainer & PropsWithChildren;
+/**
+ * OryProvider is a React component that provides the necessary context for rendering Ory flows.
+ *
+ * It wraps the application in several context providers, including {@link OryConfigurationProvider}.
+ *
+ * You can use this component to set up the Ory SDK, provide custom translations, and specify the components to use for rendering Ory flows.
+ *
+ * @example
+ * ```tsx
+ * import { OryProvider, LoginFlow, OryFlowComponents, OryClientConfiguration } from "@ory/elements-react";
+ *
+ *
+ * export type Props = {
+ *   flow: LoginFlow
+ *   components: OryFlowComponents
+ *   config: OryClientConfiguration
+ * }
+ *
+ * function App({
+ *   flow,
+ *   config,
+ *   children,
+ *   components,
+ * }: PropsWithChildren<Props>) {
+ *   return (
+ *     <OryProvider
+ *       config={config}
+ *       flow={flow}
+ *       flowType={FlowType.Login}
+ *       components={components}
+ *     >
+ *       {children}
+ *     </OryProvider>
+ *   )
+ * }
+ *
+ * ```
+ *
+ * @param props - The properties for the OryProvider component.
+ * @returns
+ * @group Components
+ */
 declare function OryProvider({ children, components: Components, config, ...oryFlowProps }: OryProviderProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * The Ory Elements configuration object.
+ *
+ * @interface
+ */
 type OryElementsConfiguration = {
+    /**
+     * The Ory SDK configuration.
+     * This includes the URL and options for the Ory SDK.
+     */
     sdk: OrySDK;
+    /**
+     * The project configuration.
+     * This includes the project name, URLs, and other settings for the Ory Elements project.
+     */
     project: AccountExperienceConfiguration;
 };
+/**
+ * The `useOryConfiguration` hook provides access to the Ory Elements configuration.
+ *
+ * This includes the SDK configuration and the project configuration. To customize the configuration, provide the `sdk` and `project` properties in the `OryConfigurationProvider`.
+ *
+ * @returns the Ory Elements configuration, which includes the SDK and project configuration.
+ * @group Hooks
+ */
 declare function useOryConfiguration(): OryElementsConfiguration;
 type OrySDK = SDKConfig & {
     /**
@@ -651,9 +1033,32 @@ type SDKConfig = {
     url: string;
     options?: Partial<ConfigurationParameters>;
 };
-declare function OryConfigurationProvider({ children, sdk: initialConfig, project, }: PropsWithChildren<{
-    sdk?: Partial<OryClientConfiguration["sdk"]>;
+/**
+ * Props for the `OryConfigurationProvider` component.
+ *
+ * @hidden
+ * @inline
+ */
+interface OryConfigurationProviderProps extends PropsWithChildren {
+    /**
+     * The Ory SDK configuration to use.
+     * If not provided, the SDK URL will be determined automatically based on the environment.
+     *
+     * Always required for production environments.
+     */
+    sdk?: OryClientConfiguration["sdk"];
+    /**
+     * This configuration is used to customize the behavior and appearance of Ory Elements.
+     */
     project?: Partial<AccountExperienceConfiguration>;
-}>): react_jsx_runtime.JSX.Element;
+}
+/**
+ * The `OryConfigurationProvider` component provides the Ory Elements configuration to its children.
+ *
+ * @param props - The properties for the OryConfigurationProvider component.
+ * @returns
+ * @group Components
+ */
+declare function OryConfigurationProvider({ children, sdk: initialConfig, project, }: OryConfigurationProviderProps): react_jsx_runtime.JSX.Element;
 
-export { type ConsentFlow, type ConsentFlowContainer, type ErrorFlowContainer, type FlowContainerSetter, type FlowContextValue, type FormState, type FormStateAction, type FormStateMethodActive, type FormStateProvideIdentifier, type FormStateSelectMethod, type FormValues, HeadlessPageHeader, type IntlConfig, type LoginFlowContainer, type OnSubmitHandlerProps, OryCard, type OryCardAuthMethodListItemProps, OryCardContent, type OryCardContentProps, type OryCardDividerProps, OryCardFooter, type OryCardFooterProps, OryCardHeader, type OryCardHeaderProps, type OryCardLogoProps, type OryCardRootProps as OryCardProps, type OryCardSettingsSectionProps, OryCardValidationMessages, type OryClientConfiguration, OryConfigurationProvider, OryConsentCard, type OryElementsConfiguration, type OryFlowComponentOverrides, type OryFlowComponents, type OryFlowContainer, OryForm, OryFormGroupDivider, type OryFormGroupProps, OryFormGroups, type OryFormGroupsProps, OryFormOidcButtons, type OryFormOidcRootProps, type OryFormProps, type OryFormRootProps, OryFormSection, type OryFormSectionContentProps, type OryFormSectionFooterProps, type OryFormSectionProps, OryFormSocialButtonsForm, OryLocales, type OryMessageContentProps, type OryMessageRootProps, type OryNodeAnchorProps, type OryNodeButtonProps, type OryNodeCaptchaProps, type OryNodeConsentScopeCheckboxProps, type OryNodeImageProps, type OryNodeInputProps, type OryNodeLabelProps, type OryNodeOidcButtonProps, type OryNodeTextProps, type OryPageHeaderProps, OryProvider, type OryProviderProps, OrySettingsCard, type OrySettingsOidcProps, type OrySettingsPasskeyProps, type OrySettingsRecoveryCodesProps, type OrySettingsTotpProps, type OrySettingsWebauthnProps, OryTwoStepCard, type RecoveryFlowContainer, type RegistrationFlowContainer, type SettingsFlowContainer, type VerificationFlowContainer, messageTestId, uiTextToFormattedMessage, useComponents, useNodeSorter, useOryConfiguration, useOryFlow };
+export { type ConsentFlow, type ConsentFlowContainer, type ErrorFlowContainer, type FlowContainerSetter, type FlowContextValue, type FormState, type FormStateAction, type FormStateMethodActive, type FormStateProvideIdentifier, type FormStateSelectMethod, type FormValues, type IntlConfig, type LoginFlowContainer, type OnSubmitHandlerProps, OryCard, type OryCardAuthMethodListItemProps, OryCardContent, type OryCardContentProps, type OryCardDividerProps, OryCardFooter, type OryCardFooterProps, OryCardHeader, type OryCardHeaderProps, type OryCardLogoProps, type OryCardRootProps as OryCardProps, type OryCardSettingsSectionProps, OryCardValidationMessages, type OryCardValidationMessagesProps, type OryClientConfiguration, OryConfigurationProvider, OryConsentCard, type OryElementsConfiguration, type OryFlowComponentOverrides, type OryFlowComponents, type OryFlowContainer, OryForm, OryFormGroupDivider, type OryFormGroupProps, type OryFormProps, type OryFormRootProps, type OryFormSectionContentProps, type OryFormSectionFooterProps, type OryFormSectionProps, OryFormSsoButtons, OryFormSsoForm, type OryFormSsoRootProps, OryLocales, type OryMessageContentProps, type OryMessageRootProps, type OryNodeAnchorProps, type OryNodeButtonProps, type OryNodeCaptchaProps, type OryNodeConsentScopeCheckboxProps, type OryNodeImageProps, type OryNodeInputProps, type OryNodeLabelProps, type OryNodeSsoButtonProps, type OryNodeTextProps, OryPageHeader, type OryPageHeaderProps, OryProvider, type OryProviderProps, OrySelfServiceFlowCard, OrySettingsCard, type OrySettingsFormProps, OrySettingsFormSection, type OrySettingsPasskeyProps, type OrySettingsRecoveryCodesProps, type OrySettingsSsoProps, type OrySettingsTotpProps, type OrySettingsWebauthnProps, type OryToastProps, type RecoveryFlowContainer, type RegistrationFlowContainer, type SettingsFlowContainer, type VerificationFlowContainer, messageTestId, uiTextToFormattedMessage, useComponents, useNodeSorter, useOryConfiguration, useOryFlow };