@meindesk/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,429 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes } from 'react';
+import * as _meindesk_sdk from '@meindesk/sdk';
+import { User, Session, AuthConfig, MeindeskClient, SignInData, SignInResult, SignUpData, AuthResult, FormField } from '@meindesk/sdk';
+import { AuthExperienceConfig, ExperienceId, ProviderId, ProviderConfig, AppearanceConfig, ProfileFieldConfig } from '@meindesk/auth-config';
+
+interface AuthContextValue {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    user: User | null;
+    session: Session | null;
+    sessionToken: string | null;
+    config: AuthConfig | null;
+    client: MeindeskClient;
+    /** Set when OAuth code exchange fails during bootstrap. */
+    oauthError: string | null;
+    signIn: (data: SignInData) => Promise<SignInResult>;
+    signUp: (data: SignUpData) => Promise<AuthResult>;
+    signOut: () => Promise<void>;
+    verifyMfa: (data: {
+        mfaToken: string;
+        code: string;
+    }) => Promise<AuthResult>;
+    startOAuth: (provider: string, options?: {
+        redirectUrl?: string;
+        purpose?: "sign_in" | "link";
+        sessionToken?: string;
+    }) => void;
+    exchangeOAuthCode: (code: string) => Promise<AuthResult>;
+    setActive: (result: AuthResult) => void;
+    refreshUser: () => Promise<User | null>;
+    /** Refetch application auth config (experience, providers, settings). */
+    reloadConfig: () => Promise<void>;
+}
+interface AuthProviderProps {
+    /** Defaults to `NEXT_PUBLIC_MEINDESK_PUBLISHABLE_KEY`. */
+    publishableKey?: string;
+    /** Defaults to `NEXT_PUBLIC_API_URL` or http://localhost:4000. */
+    apiUrl?: string;
+    children: ReactNode;
+}
+declare function AuthProvider({ publishableKey: publishableKeyProp, apiUrl: apiUrlProp, children, }: AuthProviderProps): react.FunctionComponentElement<{
+    children: ReactNode;
+}>;
+declare function useAuthContext(): AuthContextValue;
+
+declare function useAuth(): {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    user: _meindesk_sdk.User | null;
+    session: _meindesk_sdk.Session | null;
+    sessionToken: string | null;
+    signIn: (data: _meindesk_sdk.SignInData) => Promise<_meindesk_sdk.SignInResult>;
+    signUp: (data: _meindesk_sdk.SignUpData) => Promise<_meindesk_sdk.AuthResult>;
+    signOut: () => Promise<void>;
+};
+declare function useUser(): {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    user: _meindesk_sdk.User | null;
+};
+declare function useSession(): {
+    isLoaded: boolean;
+    session: _meindesk_sdk.Session | null;
+    sessionToken: string | null;
+};
+
+interface ConditionalProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+declare function SignedIn({ children, fallback }: ConditionalProps): ReactNode;
+declare function SignedOut({ children, fallback }: ConditionalProps): ReactNode;
+interface ProtectProps extends ConditionalProps {
+    /** When false, render fallback even if signed in. */
+    condition?: boolean;
+}
+declare function Protect({ children, fallback, condition, }: ProtectProps): ReactNode;
+
+interface SignInProps {
+    onSuccess?: (result: AuthResult) => void;
+    onError?: (error: Error) => void;
+    redirectUrl?: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    subtitle?: string;
+}
+declare function SignIn({ onSuccess, onError, redirectUrl, className, style, }: SignInProps): react.JSX.Element;
+
+interface SignUpProps {
+    onSuccess?: (result: AuthResult) => void;
+    onError?: (error: Error) => void;
+    redirectUrl?: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    subtitle?: string;
+}
+declare function SignUp({ onSuccess, onError, redirectUrl, className, style, }: SignUpProps): react.JSX.Element;
+
+interface SsoCallbackProps {
+    /** Where to send the user after a successful exchange. Defaults to `redirect_url` query or `/`. */
+    fallbackRedirectUrl?: string;
+    /** Shown while exchanging. */
+    loading?: ReactNode;
+    /** Custom error renderer. */
+    renderError?: (error: string) => ReactNode;
+}
+/**
+ * Optional dedicated OAuth landing page.
+ * Most apps do not need this — AuthProvider exchanges on any page and
+ * authMiddleware lets `?code=&provider=` through. Use when you want a
+ * dedicated sign-in progress screen.
+ */
+declare function SsoCallback({ fallbackRedirectUrl, loading, renderError, }: SsoCallbackProps): react.JSX.Element;
+
+interface ForgotPasswordProps {
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+    redirectUrl?: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    subtitle?: string;
+}
+declare function ForgotPassword({ onSuccess, onError, className, style, }: ForgotPasswordProps): react.JSX.Element;
+
+interface ResetPasswordProps {
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+    redirectUrl?: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    subtitle?: string;
+    token?: string;
+}
+declare function ResetPassword({ onSuccess, onError, redirectUrl, className, style, token: tokenProp, }: ResetPasswordProps): react.JSX.Element;
+
+interface MagicLinkSignInProps {
+    onSuccess?: (result: AuthResult) => void;
+    onError?: (error: Error) => void;
+    redirectUrl?: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    subtitle?: string;
+    token?: string;
+}
+declare function MagicLinkSignIn({ onSuccess, onError, redirectUrl, className, style, token: tokenProp, }: MagicLinkSignInProps): react.JSX.Element;
+
+interface VerifyEmailProps {
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+    redirectUrl?: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    subtitle?: string;
+    token?: string;
+}
+declare function VerifyEmail({ onSuccess, onError, redirectUrl, className, style, token: tokenProp, }: VerifyEmailProps): react.JSX.Element;
+
+type UserProfileTab = "profile" | "security" | "preferences" | "email";
+interface UserProfileProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    defaultTab?: UserProfileTab;
+    /** When opening via email shortcut, expand the email editor. */
+    expandEmailOnOpen?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+declare function UserProfile({ open: controlledOpen, onOpenChange, defaultTab, expandEmailOnOpen, className, style, }: UserProfileProps): react.JSX.Element | null;
+declare function UserProfileButton({ className, style, label, defaultTab, }: {
+    className?: string;
+    style?: CSSProperties;
+    label?: string;
+    defaultTab?: UserProfileTab;
+}): react.JSX.Element | null;
+
+interface UserButtonProps {
+    className?: string;
+    style?: CSSProperties;
+    afterSignOutUrl?: string;
+    showName?: boolean;
+    userProfileDefaultTab?: UserProfileTab;
+}
+declare function UserButton({ className, style, afterSignOutUrl, showName, userProfileDefaultTab, }: UserButtonProps): react.JSX.Element | null;
+
+interface RenderFormFieldProps {
+    field: FormField;
+    value: string;
+    disabled?: boolean;
+    onChange: (name: string, value: string) => void;
+    autoComplete?: string;
+}
+declare function FormFieldControl({ field, value, disabled, onChange, autoComplete, }: RenderFormFieldProps): react.JSX.Element;
+declare function autoCompleteForField(fieldName: string, mode?: "sign-in" | "sign-up"): string | undefined;
+
+declare const authStyles: string;
+declare function ensureAuthStyles(): void;
+
+type AuthMode = "live" | "preview";
+interface ExperienceScreenProps {
+    config: AuthExperienceConfig;
+    mode: AuthMode;
+    theme?: "light" | "dark";
+    className?: string;
+    onNavigate?: (experience: ExperienceId) => void;
+    onProviderClick?: (id: ProviderId) => void;
+    onSubmit?: (values: Record<string, string>) => void | Promise<void>;
+}
+declare function SignInScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function SignUpScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function ForgotPasswordScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function ResetPasswordScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function MagicLinkScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function EmailVerificationScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function MfaScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function OrganizationSelectionScreen(props: ExperienceScreenProps): react.JSX.Element;
+declare function OrganizationCreationScreen(props: ExperienceScreenProps): react.JSX.Element;
+
+interface AuthExperienceProps {
+    experience: ExperienceId;
+    /** Full experience config. When omitted in live mode, derived from AuthProvider config. */
+    config?: AuthExperienceConfig;
+    /** Raw SDK AuthConfig used to assemble experience when `config` is omitted. */
+    authConfig?: AuthConfig | null;
+    mode?: AuthMode;
+    theme?: "light" | "dark";
+    className?: string;
+    style?: CSSProperties;
+    onExperienceChange?: (experience: ExperienceId) => void;
+    onProviderClick?: (id: ProviderId) => void;
+    onSubmit?: (values: Record<string, string>) => void | Promise<void>;
+}
+declare function authConfigToExperience(authConfig?: AuthConfig | null): AuthExperienceConfig;
+/** Minimal placeholder while AuthProvider finishes loading config. */
+declare function AuthExperienceLoading({ className, style, }: {
+    className?: string;
+    style?: CSSProperties;
+}): react.JSX.Element;
+declare function AuthExperience({ experience: experienceProp, config: configProp, authConfig, mode, theme, className, style, onExperienceChange, onProviderClick, onSubmit, }: AuthExperienceProps): react.JSX.Element;
+
+declare function ProviderButtons({ providers, position, onProviderClick, disabled, }: {
+    providers: ProviderConfig[];
+    position: "before" | "after";
+    onProviderClick?: (id: ProviderId) => void;
+    disabled?: boolean;
+}): react.JSX.Element | null;
+
+declare function AuthShell({ config, theme, className, style, children, }: {
+    config: AuthExperienceConfig;
+    theme?: "light" | "dark";
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}): react.JSX.Element;
+
+declare function appearanceToCssVars(appearance: AppearanceConfig, theme?: "light" | "dark"): CSSProperties;
+
+/** Centralized motion timings (ms). Keep auth UI fast — utility, not marketing. */
+declare const MOTION_DURATION: {
+    readonly instant: 120;
+    readonly fast: 160;
+    readonly normal: 220;
+    readonly slow: 320;
+};
+type MotionDuration = keyof typeof MOTION_DURATION;
+/** Controlled easings — no overshoot / bounce. */
+declare const MOTION_EASING: {
+    readonly standard: "cubic-bezier(0.2, 0, 0, 1)";
+    readonly enter: "cubic-bezier(0.16, 1, 0.3, 1)";
+    readonly exit: "cubic-bezier(0.4, 0, 1, 1)";
+    readonly emphasis: "cubic-bezier(0.2, 0, 0, 1)";
+};
+type MotionEasing = keyof typeof MOTION_EASING;
+declare const MOTION_DISTANCE: {
+    /** Max Y shift for form / dropdown enter (px). */
+    readonly subtle: 6;
+};
+
+declare function getPrefersReducedMotion(): boolean;
+/** Subscribe to prefers-reduced-motion. Prefer opacity-only / instant swaps when true. */
+declare function useReducedMotion(): boolean;
+
+interface FadePresenceProps {
+    /** When this changes, content crossfades. */
+    contentKey: string;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Skip Y translate (opacity only). */
+    opacityOnly?: boolean;
+}
+/**
+ * Keyed crossfade. Latest key wins immediately (interruptible — no queue).
+ */
+declare function FadePresence({ contentKey, children, className, style, opacityOnly, }: FadePresenceProps): react.JSX.Element;
+
+interface FormTransitionProps {
+    contentKey: string;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Stable auth form shell: crossfade content and tween height so the card
+ * does not collapse then expand between steps.
+ */
+declare function FormTransition({ contentKey, children, className, style, }: FormTransitionProps): react.JSX.Element;
+
+interface CollapseTransitionProps {
+    open: boolean;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Reveal / hide inline messages without a harsh layout jump. */
+declare function CollapseTransition({ open, children, className, style, }: CollapseTransitionProps): react.JSX.Element | null;
+
+interface LoadingButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    loading?: boolean;
+    loadingLabel?: string;
+    /** Keep visible label while spinning (default true). */
+    showLabelWhileLoading?: boolean;
+    variant?: "primary" | "secondary" | "ghost" | "danger";
+    /** Skip default `.meindesk-button` styles (host supplies className). */
+    bare?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+declare const LoadingButton: react.ForwardRefExoticComponent<LoadingButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+type AuthLoaderVariant = "inline" | "button" | "content" | "page" | "modal";
+interface AuthLoaderProps extends HTMLAttributes<HTMLDivElement> {
+    variant?: AuthLoaderVariant;
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Shared thin-ring spinner for auth hydration, buttons, and modals. */
+declare function AuthLoader({ variant, label, className, style, ...rest }: AuthLoaderProps): react.JSX.Element;
+
+type SkeletonShape = "circle" | "line" | "rect" | "avatar";
+interface SkeletonProps extends HTMLAttributes<HTMLDivElement> {
+    shape?: SkeletonShape;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Soft pulse placeholder — match final layout, avoid aggressive shimmer. */
+declare function Skeleton({ shape, width, height, className, style, ...rest }: SkeletonProps): react.JSX.Element;
+declare function UserButtonSkeleton({ className }: {
+    className?: string;
+}): react.JSX.Element;
+
+interface FieldErrorProps {
+    message?: string | null;
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    id?: string;
+    /** `form` = banner under the form; `field` = compact message under an input. */
+    variant?: "form" | "field";
+}
+declare function FieldError({ message, children, className, style, id, variant, }: FieldErrorProps): react.JSX.Element;
+
+interface SuccessIndicatorProps {
+    message?: string | null;
+    children?: ReactNode;
+    show?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+declare function SuccessIndicator({ message, children, show, className, style, }: SuccessIndicatorProps): react.JSX.Element;
+
+type AuthToastTone = "success" | "error" | "info";
+interface AuthToastItem {
+    id: string;
+    message: string;
+    tone: AuthToastTone;
+}
+interface AuthToastContextValue {
+    toasts: AuthToastItem[];
+    push: (message: string, tone?: AuthToastTone) => void;
+    dismiss: (id: string) => void;
+}
+declare function AuthToastProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useAuthToast(): AuthToastContextValue;
+
+type AuthFormFieldErrors = Record<string, string>;
+interface AuthFormErrorResult {
+    /** Banner / form-level message. */
+    formError: string | null;
+    /** Per-field messages keyed by field id (email, password, code, …). */
+    fieldErrors: AuthFormFieldErrors;
+}
+/** Prefer API message; fall back to a readable default for common codes. */
+declare function formatAuthError(err: unknown, fallback?: string): string;
+/**
+ * Map an API/client error into form + field errors.
+ * Credential failures stay form-level (no email/password leak via field highlights).
+ */
+declare function mapAuthErrorToForm(err: unknown): AuthFormErrorResult;
+
+interface ValidateAuthFieldsOptions {
+    /** Extra fields not in ProfileFieldConfig (e.g. MFA `code`). */
+    extras?: Array<{
+        id: string;
+        label?: string;
+        required?: boolean;
+        minLength?: number;
+        kind?: "email" | "password" | "code" | "text";
+    }>;
+    passwordMinLength?: number;
+}
+/** Client-side validation before submit. Returns field errors (empty = valid). */
+declare function validateAuthFields(fields: ProfileFieldConfig[] | undefined, values: Record<string, string>, options?: ValidateAuthFieldsOptions): AuthFormFieldErrors;
+declare function hasFieldErrors(errors: AuthFormFieldErrors): boolean;
+declare function firstFieldErrorId(errors: AuthFormFieldErrors, order: string[]): string | null;
+
+export { type AuthContextValue, AuthExperience, AuthExperienceLoading, type AuthExperienceProps, type AuthFormErrorResult, type AuthFormFieldErrors, AuthLoader, type AuthLoaderProps, type AuthLoaderVariant, type AuthMode, AuthProvider, type AuthProviderProps, AuthShell, type AuthToastItem, AuthToastProvider, type AuthToastTone, CollapseTransition, type CollapseTransitionProps, type ConditionalProps, EmailVerificationScreen, type ExperienceScreenProps, FadePresence, type FadePresenceProps, FieldError, type FieldErrorProps, ForgotPassword, type ForgotPasswordProps, ForgotPasswordScreen, FormFieldControl, FormTransition, type FormTransitionProps, LoadingButton, type LoadingButtonProps, MOTION_DISTANCE, MOTION_DURATION, MOTION_EASING, MagicLinkScreen, MagicLinkSignIn, type MagicLinkSignInProps, MfaScreen, type MotionDuration, type MotionEasing, OrganizationCreationScreen, OrganizationSelectionScreen, Protect, type ProtectProps, ProviderButtons, type RenderFormFieldProps, ResetPassword, type ResetPasswordProps, ResetPasswordScreen, SignIn, type SignInProps, SignInScreen, SignUp, type SignUpProps, SignUpScreen, SignedIn, SignedOut, Skeleton, type SkeletonProps, type SkeletonShape, SsoCallback, type SsoCallbackProps, SuccessIndicator, type SuccessIndicatorProps, UserButton, type UserButtonProps, UserButtonSkeleton, UserProfile, UserProfileButton, type UserProfileProps, type UserProfileTab, type ValidateAuthFieldsOptions, VerifyEmail, type VerifyEmailProps, appearanceToCssVars, authConfigToExperience, authStyles, autoCompleteForField, ensureAuthStyles, firstFieldErrorId, formatAuthError, getPrefersReducedMotion, hasFieldErrors, mapAuthErrorToForm, useAuth, useAuthContext, useAuthToast, useReducedMotion, useSession, useUser, validateAuthFields };