@tempots/beatui 0.82.0 → 0.83.0

package/dist/types/better-auth/types.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Better Auth Types
+ *
+ * TypeScript interfaces for the better-auth integration layer. Defines structural
+ * interfaces for the better-auth client (avoiding hard import dependencies),
+ * session types, bridge configuration, and plugin client interfaces for
+ * two-factor authentication and passkeys.
+ *
+ * @module better-auth/types
+ */
+import { Signal } from '@tempots/dom';
+import { AuthContainerLabels, AuthContainerOptions, AuthProviderInfo, AuthProviderName, PasswordRules, ResetPasswordFormOptions, SignInFormOptions, SignUpFormOptions } from '../components/auth';
+/**
+ * Structural interface for the better-auth client.
+ *
+ * Defines the expected shape of the better-auth client object without
+ * importing the actual library, avoiding a hard dependency. Components
+ * that receive a `BetterAuthClient` can work with any object that
+ * satisfies this interface.
+ */
+export interface BetterAuthClient {
+    signIn: {
+        email: (opts: {
+            email: string;
+            password: string;
+            rememberMe?: boolean;
+            callbackURL?: string;
+        }) => Promise<BetterAuthResult<unknown>>;
+        social: (opts: {
+            provider: string;
+            callbackURL?: string;
+            errorCallbackURL?: string;
+        }) => Promise<BetterAuthResult<unknown>>;
+        magicLink?: (opts: {
+            email: string;
+            callbackURL?: string;
+        }) => Promise<BetterAuthResult<unknown>>;
+        passkey?: (opts?: {
+            autoFill?: boolean;
+        }) => Promise<BetterAuthResult<unknown>>;
+    };
+    signUp: {
+        email: (opts: {
+            name?: string;
+            email: string;
+            password: string;
+            callbackURL?: string;
+        }) => Promise<BetterAuthResult<unknown>>;
+    };
+    signOut: (opts?: object) => Promise<BetterAuthResult<unknown>>;
+    getSession: () => Promise<BetterAuthResult<{
+        session: unknown;
+        user: BetterAuthUser;
+    }>>;
+    requestPasswordReset: (opts: {
+        email: string;
+        redirectTo?: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+    resetPassword?: (opts: {
+        newPassword: string;
+        token: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+    changePassword?: (opts: {
+        newPassword: string;
+        currentPassword: string;
+        revokeOtherSessions?: boolean;
+    }) => Promise<BetterAuthResult<unknown>>;
+    sendVerificationEmail?: (opts: {
+        email: string;
+        callbackURL: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+    twoFactor?: TwoFactorClient;
+    passkey?: PasskeyClient;
+    magicLink?: {
+        verify: (opts: {
+            token: string;
+        }) => Promise<BetterAuthResult<unknown>>;
+    };
+}
+/**
+ * Result type returned by better-auth client methods.
+ *
+ * Either `data` or `error` will be non-null, but not both.
+ *
+ * @typeParam T - The type of the success data.
+ */
+export interface BetterAuthResult<T> {
+    /** The success data, or `null` if the operation failed. */
+    data: T | null;
+    /** The error details, or `null` if the operation succeeded. */
+    error: {
+        message: string;
+        status: number;
+        statusText: string;
+    } | null;
+}
+/**
+ * Represents a user object from the better-auth system.
+ */
+export interface BetterAuthUser {
+    /** The unique user identifier. */
+    id: string;
+    /** The user's display name. */
+    name?: string;
+    /** The user's email address. */
+    email: string;
+    /** URL to the user's profile image. */
+    image?: string;
+}
+/**
+ * Client interface for two-factor authentication operations.
+ *
+ * Provides methods for enabling/disabling 2FA, verifying TOTP codes,
+ * sending and verifying OTP codes, and managing backup codes.
+ */
+export interface TwoFactorClient {
+    enable: (opts: {
+        password: string;
+        issuer?: string;
+    }) => Promise<BetterAuthResult<{
+        totpURI: string;
+        backupCodes: string[];
+    }>>;
+    disable: (opts: {
+        password: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+    getTotpUri: (opts: {
+        password: string;
+    }) => Promise<BetterAuthResult<{
+        totpURI: string;
+    }>>;
+    verifyTotp: (opts: {
+        code: string;
+        trustDevice?: boolean;
+    }) => Promise<BetterAuthResult<unknown>>;
+    sendOtp?: (opts?: {
+        trustDevice?: boolean;
+    }) => Promise<BetterAuthResult<unknown>>;
+    verifyOtp?: (opts: {
+        code: string;
+        trustDevice?: boolean;
+    }) => Promise<BetterAuthResult<unknown>>;
+    generateBackupCodes: (opts: {
+        password: string;
+    }) => Promise<BetterAuthResult<{
+        backupCodes: string[];
+    }>>;
+    verifyBackupCode: (opts: {
+        code: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+}
+/**
+ * Client interface for passkey (WebAuthn) operations.
+ *
+ * Provides methods for adding, listing, deleting, and renaming passkeys.
+ */
+export interface PasskeyClient {
+    addPasskey: (opts?: {
+        name?: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+    listUserPasskeys: () => Promise<BetterAuthResult<PasskeyInfo[]>>;
+    deletePasskey: (opts: {
+        id: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+    updatePasskey: (opts: {
+        id: string;
+        name: string;
+    }) => Promise<BetterAuthResult<unknown>>;
+}
+/**
+ * Information about a registered passkey.
+ */
+export interface PasskeyInfo {
+    /** The unique passkey identifier. */
+    id: string;
+    /** The user-assigned name for this passkey. */
+    name?: string;
+    /** The ISO 8601 date string when the passkey was created. */
+    createdAt: string;
+}
+/**
+ * Configuration options for the better-auth bridge.
+ *
+ * Controls OAuth callback URLs, social providers, form display options,
+ * session polling, and event callbacks.
+ */
+export interface BetterAuthBridgeOptions {
+    /** The URL to redirect to after successful authentication. */
+    callbackURL?: string;
+    /** The URL to redirect to when an authentication error occurs. */
+    errorCallbackURL?: string;
+    /** List of social provider names to display login buttons for. */
+    socialProviders?: AuthProviderName[];
+    /** Password validation rules for sign-in and sign-up forms. */
+    passwordRules?: PasswordRules;
+    /** Whether to show the "remember me" checkbox. */
+    showRememberMe?: boolean;
+    /** Whether to show the name field on the sign-up form. */
+    showNameField?: boolean;
+    /** Whether to show the confirm password field on the sign-up form. */
+    showConfirmPassword?: boolean;
+    /** Whether to show the password strength indicator on the sign-up form. */
+    showPasswordStrength?: boolean;
+    /** Session polling interval in milliseconds. Set to `0` to disable. @default 0 */
+    refreshInterval?: number;
+    /**
+     * Callback invoked whenever the session state changes.
+     * @param session - The new session, or `null` if the user signed out.
+     */
+    onSessionChange?: (session: BetterAuthSession | null) => void;
+    /**
+     * Callback invoked when an authentication error occurs.
+     * @param error - The error details including message and HTTP status.
+     */
+    onError?: (error: {
+        message: string;
+        status: number;
+    }) => void;
+    /** Custom label overrides for all auth form text. */
+    labels?: AuthContainerLabels;
+}
+/**
+ * Represents an active authentication session.
+ *
+ * Contains the authenticated user and any additional session data
+ * from the better-auth backend.
+ */
+export interface BetterAuthSession {
+    /** The authenticated user. */
+    user: BetterAuthUser;
+    /** Additional session properties from the backend. */
+    [key: string]: unknown;
+}
+/**
+ * The bridge object returned by {@link createBetterAuthBridge}.
+ *
+ * Provides reactive session state, pre-configured form options for auth
+ * components, and methods for sign-out and session management.
+ *
+ * @example
+ * ```ts
+ * const bridge = createBetterAuthBridge(authClient, { socialProviders: ['google'] })
+ *
+ * // Use reactive state
+ * When(bridge.isAuthenticated, () => html.div('Welcome!'))
+ *
+ * // Use pre-configured options
+ * AuthContainer(bridge.containerOptions)
+ * ```
+ */
+export interface BetterAuthBridge {
+    /** Reactive signal containing the current session, or `null` if not authenticated. */
+    session: Signal<BetterAuthSession | null>;
+    /** Reactive signal that is `true` while the initial session fetch is in progress. */
+    isPending: Signal<boolean>;
+    /** Reactive signal containing the current user, or `null` if not authenticated. */
+    user: Signal<BetterAuthUser | null>;
+    /** Reactive signal that is `true` when the user is authenticated. */
+    isAuthenticated: Signal<boolean>;
+    /** Pre-configured options for the {@link AuthContainer} component. */
+    containerOptions: AuthContainerOptions;
+    /** Pre-configured options for the {@link SignInForm} component. */
+    signInOptions: SignInFormOptions;
+    /** Pre-configured options for the {@link SignUpForm} component. */
+    signUpOptions: SignUpFormOptions;
+    /** Pre-configured options for the {@link ResetPasswordForm} component. */
+    resetOptions: ResetPasswordFormOptions;
+    /** The list of social provider configurations derived from bridge options. */
+    socialProviders: AuthProviderInfo[];
+    /** Signs the user out and refreshes the session state. */
+    signOut: () => Promise<void>;
+    /** Manually refreshes the session by re-fetching from the server. */
+    refreshSession: () => Promise<void>;
+    /** Disposes all reactive signals and clears any polling intervals. */
+    dispose: () => void;
+}

package/dist/types/components/auth/auth-container.d.ts

@@ -1,6 +1,67 @@
+/**
+ * Auth Container Component
+ *
+ * The main authentication UI container that switches between sign-in,
+ * sign-up, and reset-password modes. Coordinates social login buttons,
+ * form fields, mode navigation links, and i18n labels.
+ *
+ * @module auth/auth-container
+ */
 import { TNode } from '@tempots/dom';
 import { AuthContainerOptions } from './index';
-export declare function AuthContainer({ mode: initialMode, socialProviders, initialName, initialEmail, passwordRules, showRememberMe, showSocialDivider, showPasswordStrength, labels, onSignIn, onSignUp, onResetPassword, onModeChange, showContainer, }: AuthContainerOptions, ...children: TNode[]): TNode;
+/**
+ * Renders the main authentication container that switches between sign-in,
+ * sign-up, and reset-password modes.
+ *
+ * The container manages mode state, renders the appropriate form for the
+ * current mode, displays optional social login buttons with a divider,
+ * and provides navigation links to switch between modes.
+ *
+ * @param options - Configuration options for the auth container.
+ * @param children - Additional child nodes to render inside the container.
+ * @returns A `TNode` representing the complete auth container UI.
+ *
+ * @example
+ * ```ts
+ * AuthContainer({
+ *   mode: 'signin',
+ *   socialProviders: [{ provider: 'google' }, { provider: 'github' }],
+ *   onSignIn: async (data) => {
+ *     const error = await api.signIn(data)
+ *     return error ?? null
+ *   },
+ *   onSignUp: async (data) => {
+ *     const error = await api.signUp(data)
+ *     return error ?? null
+ *   },
+ *   onResetPassword: async (data) => {
+ *     const error = await api.resetPassword(data)
+ *     return error ?? null
+ *   },
+ *   showRememberMe: true,
+ *   showSocialDivider: true,
+ * })
+ * ```
+ */
+export declare function AuthContainer({ mode: initialMode, socialProviders, initialName, initialEmail, passwordRules, showRememberMe, showSocialDivider, showPasswordStrength, labels, onSignIn, onSignUp, onResetPassword, onModeChange, onSocialLogin, showContainer, }: AuthContainerOptions, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Creates an authentication container displayed inside a modal dialog.
+ *
+ * Provides a callback-based API where the consumer receives an `open` function
+ * that triggers the modal with auth container content. The modal is small-sized,
+ * dismissable, and includes a close button.
+ *
+ * @param fn - A function that receives an `open` callback and returns the trigger `TNode`.
+ *   The `open` callback accepts {@link AuthContainerOptions} plus an optional `modalTitle`.
+ * @returns A `TNode` that includes both the trigger element and the modal.
+ *
+ * @example
+ * ```ts
+ * AuthModal((open) =>
+ *   Button({ onClick: () => open({ onSignIn: handleSignIn }) }, 'Sign In')
+ * )
+ * ```
+ */
 export declare function AuthModal(fn: (open: (options: AuthContainerOptions & {
     modalTitle?: () => string;
-}) => void) => TNode): TNode;
+}) => void) => TNode): import("@tempots/dom").Renderable;

package/dist/types/components/auth/auth-divider.d.ts

@@ -1,8 +1,38 @@
+/**
+ * Auth Divider Component
+ *
+ * A horizontal divider with centered text (typically "or") used to visually
+ * separate social login buttons from the email/password form.
+ *
+ * @module auth/auth-divider
+ */
 import { Renderable, Value } from '@tempots/dom';
+/**
+ * Options for the {@link AuthDivider} component.
+ */
 export interface AuthDividerOptions {
+    /** Optional label overrides. */
     labels?: {
+        /** Custom text to display in the divider (e.g., `'or'`). Falls back to i18n `orDivider`. */
         text?: () => string;
     };
+    /** Additional CSS class names to apply to the divider container. */
     className?: Value<string>;
 }
+/**
+ * Renders a horizontal divider line with centered text.
+ *
+ * Typically displays "or" (localized) between social login buttons and
+ * the email/password form. The text can be customized via the `labels` option
+ * or overridden by the active locale's `orDivider` translation.
+ *
+ * @param options - Configuration options for the divider.
+ * @returns A `Renderable` DOM element representing the divider.
+ *
+ * @example
+ * ```ts
+ * AuthDivider()
+ * AuthDivider({ labels: { text: () => 'or continue with email' } })
+ * ```
+ */
 export declare function AuthDivider({ labels, className, }?: AuthDividerOptions): Renderable;

package/dist/types/components/auth/auth-email-prop.d.ts

@@ -1 +1,26 @@
+/**
+ * Auth Email Persistence
+ *
+ * Provides a reactive property backed by `localStorage` that persists the
+ * user's email address across sessions. Used by the "remember me" checkbox
+ * in sign-in and reset password forms.
+ *
+ * @module auth/auth-email-prop
+ */
+/**
+ * Creates a reactive `localStorage`-backed property for persisting the user's email.
+ *
+ * When the "remember me" checkbox is checked, the email is stored under the key
+ * `'bui_auth_email'`. When unchecked, the value is set to `null`, removing it
+ * from storage.
+ *
+ * @returns A reactive `Prop<string | null>` backed by `localStorage`.
+ *
+ * @example
+ * ```ts
+ * const emailProp = useAuthEmailProp()
+ * emailProp.value = 'user@example.com' // persists to localStorage
+ * emailProp.value = null               // removes from localStorage
+ * ```
+ */
 export declare const useAuthEmailProp: () => import("@tempots/dom").Prop<string | null>;

package/dist/types/components/auth/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Authentication Components
+ *
+ * Re-exports all auth-related UI components, types, schemas, and utilities.
+ * These components are UI-only and use callbacks for all authentication actions,
+ * making them decoupled from any specific auth library.
+ *
+ * @module auth
+ */
 export * from './auth-container';
 export * from './auth-divider';
 export * from './auth-email-prop';

package/dist/types/components/auth/password-strength-indicator.d.ts

@@ -1,5 +1,63 @@
+/**
+ * Password Strength Indicator Component
+ *
+ * Visual feedback components for password complexity and security requirements.
+ * Includes a full indicator with bar, label, and requirements checklist, as well
+ * as simplified bar-only and text-only variants.
+ *
+ * @module auth/password-strength-indicator
+ */
 import { Renderable } from '@tempots/dom';
 import { PasswordStrengthIndicatorOptions } from './index';
+/**
+ * Renders a full password strength indicator with a progress bar,
+ * an optional strength label, and a checklist of password requirements.
+ *
+ * Reactively updates as the password value changes. Each requirement
+ * shows a check mark when satisfied.
+ *
+ * @param options - Configuration options for the indicator.
+ * @returns A `Renderable` DOM element representing the password strength indicator.
+ *
+ * @example
+ * ```ts
+ * const password = prop('')
+ * PasswordStrengthIndicator({
+ *   password,
+ *   rules: { minLength: 8, requireUppercase: true, requireNumbers: true },
+ *   showLabel: true,
+ * })
+ * ```
+ */
 export declare function PasswordStrengthIndicator({ password, rules, showLabel, className, }: PasswordStrengthIndicatorOptions): Renderable;
+/**
+ * Renders a simplified password strength indicator showing only the progress bar.
+ *
+ * A lightweight alternative to {@link PasswordStrengthIndicator} that omits
+ * the label and requirements checklist.
+ *
+ * @param options - Configuration options (same as `PasswordStrengthIndicatorOptions` minus `showLabel`).
+ * @returns A `Renderable` DOM element representing the strength bar.
+ *
+ * @example
+ * ```ts
+ * const password = prop('')
+ * PasswordStrengthBar({ password, rules: { minLength: 8 } })
+ * ```
+ */
 export declare function PasswordStrengthBar({ password, rules, className, }: Omit<PasswordStrengthIndicatorOptions, 'showLabel'>): Renderable;
+/**
+ * Renders a text-only password strength indicator (e.g., "Weak", "Strong").
+ *
+ * Displays only the localized strength label without any visual bar or checklist.
+ *
+ * @param options - Configuration options (same as `PasswordStrengthIndicatorOptions` minus `showLabel`).
+ * @returns A `Renderable` DOM element containing the strength text.
+ *
+ * @example
+ * ```ts
+ * const password = prop('')
+ * PasswordStrengthText({ password })
+ * ```
+ */
 export declare function PasswordStrengthText({ password, rules, className, }: Omit<PasswordStrengthIndicatorOptions, 'showLabel'>): Renderable;

package/dist/types/components/auth/reset-password-form.d.ts

@@ -1,3 +1,36 @@
+/**
+ * Reset Password Form Component
+ *
+ * Renders a simple form for initiating the password reset flow. Contains
+ * a description, email input, and submit button with validation and
+ * loading state management.
+ *
+ * @module auth/reset-password-form
+ */
 import { Renderable } from '@tempots/dom';
 import { ResetPasswordFormOptions } from './index';
+/**
+ * Renders the reset password form with an email input field.
+ *
+ * Features include:
+ * - Schema-based email validation
+ * - Pre-population from persisted email (if "remember me" was used)
+ * - Loading state and form disabling during submission
+ * - Error display via a notice component
+ * - Descriptive text explaining the reset flow
+ * - i18n support for all labels and button text
+ *
+ * @param options - Configuration options for the reset password form.
+ * @returns A `Renderable` form element.
+ *
+ * @example
+ * ```ts
+ * ResetPasswordForm({
+ *   onResetPassword: async (data) => {
+ *     const error = await api.requestPasswordReset(data.email)
+ *     return error ?? null
+ *   },
+ * })
+ * ```
+ */
 export declare function ResetPasswordForm({ onResetPassword, labels, }: ResetPasswordFormOptions): Renderable;