@tempots/beatui 0.82.0 → 0.83.0

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

@@ -1,28 +1,157 @@
+/**
+ * Authentication Validation Schemas
+ *
+ * Custom validation schemas for validating authentication form data.
+ * Provides schema factories for sign-in, sign-up, and reset password forms,
+ * as well as utility functions for email and password validation and
+ * password strength calculation.
+ *
+ * @module auth/schemas
+ */
 import { StringValidator, SafeParseResult } from '../form/schema/custom-validation';
 import { StandardSchemaV1 } from '../form/schema/standard-schema-v1';
 import { PasswordRules, ResetPasswordData, SignInFormData, SignUpFormData } from './types';
-export declare function createPasswordSchema(rules?: PasswordRules): StringValidator;
+/**
+ * Localizable validation messages for authentication schemas.
+ *
+ * Pass this to schema factory functions to override the default English messages.
+ * Obtain localized values from `AuthI18n` provider messages.
+ */
+export interface AuthValidationMessages {
+    passwordMinLength?: (min: number) => string;
+    passwordRequireUppercase?: string;
+    passwordRequireLowercase?: string;
+    passwordRequireNumber?: string;
+    passwordRequireSpecialChar?: string;
+    emailRequired?: string;
+    invalidEmail?: string;
+    passwordRequired?: string;
+    nameRequired?: string;
+    confirmPasswordRequired?: string;
+    acceptTermsRequired?: string;
+    passwordsDoNotMatch?: string;
+    invalidPassword?: string;
+    invalidEmailAddress?: string;
+}
+/**
+ * Creates a password validation schema based on the provided rules.
+ *
+ * Builds a `StringValidator` that enforces minimum length, character class
+ * requirements, and optional custom validation logic.
+ *
+ * @param rules - The password validation rules to enforce. Defaults to {@link defaultPasswordRules}.
+ * @returns A `StringValidator` that validates passwords against the given rules.
+ *
+ * @example
+ * ```ts
+ * const schema = createPasswordSchema({ minLength: 10, requireNumbers: true })
+ * const result = schema.validate('hello123')
+ * ```
+ */
+export declare function createPasswordSchema(rules?: PasswordRules, messages?: AuthValidationMessages): StringValidator;
+/**
+ * Creates an email validation schema with optional localized messages.
+ *
+ * @param messages - Optional localized validation messages
+ * @returns A `StringValidator` that validates email addresses
+ */
+export declare function createEmailSchema(messages?: AuthValidationMessages): StringValidator;
+/**
+ * Base email validation schema.
+ *
+ * Validates that the value is a non-empty string with a valid email format.
+ */
 export declare const emailSchema: StringValidator;
-export declare function createSignInSchema(passwordRules?: PasswordRules): StandardSchemaV1<SignInFormData> & {
+/**
+ * Creates a validation schema for the sign-in form.
+ *
+ * Validates email (required, valid format) and password fields.
+ * When `passwordRules` is provided, the password field is validated
+ * against those rules; otherwise, only a non-empty check is applied.
+ *
+ * @param passwordRules - Optional password validation rules. If omitted, only a "required" check is used.
+ * @returns A `StandardSchemaV1<SignInFormData>` with a `safeParse` method.
+ *
+ * @example
+ * ```ts
+ * const schema = createSignInSchema({ minLength: 8, requireNumbers: true })
+ * const result = schema.safeParse({ email: 'user@test.com', password: 'pass1234' })
+ * ```
+ */
+export declare function createSignInSchema(passwordRules?: PasswordRules, messages?: AuthValidationMessages): StandardSchemaV1<SignInFormData> & {
     safeParse: (value: unknown) => SafeParseResult<SignInFormData>;
 };
+/**
+ * Creates a validation schema for the sign-up form.
+ *
+ * Validates name (optional), email, password, confirm password, and
+ * terms acceptance fields. Password confirmation matching is enforced
+ * when `showConfirmPassword` is enabled.
+ *
+ * @param passwordRules - Password validation rules. Defaults to {@link defaultPasswordRules}.
+ * @param options - Optional flags controlling which fields are shown and required.
+ * @param options.showNameField - Whether the name field is shown. @default true
+ * @param options.showConfirmPassword - Whether the confirm password field is shown. @default true
+ * @param options.showAcceptTermsAndConditions - Whether the terms checkbox is shown. @default true
+ * @returns A `StandardSchemaV1<SignUpFormData>` with a `safeParse` method.
+ *
+ * @example
+ * ```ts
+ * const schema = createSignUpSchema(undefined, { showNameField: false })
+ * const result = schema.safeParse({
+ *   email: 'user@test.com',
+ *   password: 'Pass1234',
+ *   confirmPassword: 'Pass1234',
+ *   acceptTerms: true,
+ * })
+ * ```
+ */
 export declare function createSignUpSchema(passwordRules?: PasswordRules, options?: {
     showNameField?: boolean;
     showConfirmPassword?: boolean;
     showAcceptTermsAndConditions?: boolean;
-}): StandardSchemaV1<SignUpFormData> & {
+}, messages?: AuthValidationMessages): StandardSchemaV1<SignUpFormData> & {
     safeParse: (value: unknown) => SafeParseResult<SignUpFormData>;
 };
+/**
+ * Validation schema for the reset password form.
+ *
+ * Validates that the email field is present and in a valid format.
+ */
 export declare const resetPasswordSchema: StandardSchemaV1<ResetPasswordData> & {
     safeParse: (value: unknown) => SafeParseResult<ResetPasswordData>;
 };
+/**
+ * Pre-built sign-in schema using default password rules.
+ *
+ * Convenience constant equivalent to `createSignInSchema()`.
+ */
 export declare const defaultSignInSchema: StandardSchemaV1<import("./types").SignInData, import("./types").SignInData> & {
     safeParse: (value: unknown) => SafeParseResult<SignInFormData>;
 };
+/**
+ * Pre-built sign-up schema using default password rules.
+ *
+ * Convenience constant equivalent to `createSignUpSchema()`.
+ */
 export declare const defaultSignUpSchema: StandardSchemaV1<SignUpFormData, SignUpFormData> & {
     safeParse: (value: unknown) => SafeParseResult<SignUpFormData>;
 };
+/**
+ * Alias for {@link ResetPasswordData}, used as the form data type for the reset password form.
+ */
 export type ResetPasswordFormData = ResetPasswordData;
+/**
+ * Collection of schema factory functions for dynamic configuration.
+ *
+ * Provides convenient access to all auth schema creators.
+ *
+ * @example
+ * ```ts
+ * const signInSchema = authSchemas.signIn({ minLength: 12 })
+ * const resetSchema = authSchemas.resetPassword()
+ * ```
+ */
 export declare const authSchemas: {
     signIn: typeof createSignInSchema;
     signUp: typeof createSignUpSchema;
@@ -30,8 +159,57 @@ export declare const authSchemas: {
         safeParse: (value: unknown) => SafeParseResult<ResetPasswordData>;
     };
 };
-export declare function validateEmail(email: string): string | null;
-export declare function validatePassword(password: string, rules?: PasswordRules): string | null;
+/**
+ * Validates an email address against the email schema.
+ *
+ * @param email - The email address to validate.
+ * @returns An error message string if invalid, or `null` if valid.
+ *
+ * @example
+ * ```ts
+ * validateEmail('user@test.com') // null
+ * validateEmail('invalid')       // 'Please enter a valid email address'
+ * ```
+ */
+export declare function validateEmail(email: string, messages?: AuthValidationMessages): string | null;
+/**
+ * Validates a password against the provided rules.
+ *
+ * @param password - The password to validate.
+ * @param rules - The password validation rules to check against. Defaults to {@link defaultPasswordRules}.
+ * @returns An error message string if invalid, or `null` if valid.
+ *
+ * @example
+ * ```ts
+ * validatePassword('weak', { minLength: 8 }) // 'Password must be at least 8 characters'
+ * validatePassword('StrongPass1', { minLength: 8, requireUppercase: true, requireNumbers: true }) // null
+ * ```
+ */
+export declare function validatePassword(password: string, rules?: PasswordRules, messages?: AuthValidationMessages): string | null;
+/**
+ * Calculates the strength of a password based on the provided rules.
+ *
+ * Evaluates each enabled rule and produces a strength level, a numerical
+ * score (0-100), and a detailed breakdown of which checks passed.
+ *
+ * @param password - The password to evaluate.
+ * @param rules - The password rules to evaluate against. Defaults to {@link defaultPasswordRules}.
+ * @returns An object containing:
+ *   - `strength` - The qualitative strength level: `'weak'`, `'fair'`, `'good'`, or `'strong'`.
+ *   - `score` - A numerical score from 0 to 100.
+ *   - `checks` - An object indicating which individual checks passed.
+ *
+ * @example
+ * ```ts
+ * const result = calculatePasswordStrength('Hello123', {
+ *   minLength: 8,
+ *   requireUppercase: true,
+ *   requireNumbers: true,
+ * })
+ * // result.strength === 'good'
+ * // result.score === 67
+ * ```
+ */
 export declare function calculatePasswordStrength(password: string, rules?: PasswordRules): {
     strength: 'weak' | 'fair' | 'good' | 'strong';
     score: number;

package/dist/types/components/auth/signin-form.d.ts

@@ -1,3 +1,36 @@
+/**
+ * Sign In Form Component
+ *
+ * Renders the email/password sign-in form with optional "remember me" checkbox.
+ * Includes form validation, loading state management, and email persistence
+ * via `localStorage`.
+ *
+ * @module auth/signin-form
+ */
 import { Renderable } from '@tempots/dom';
 import { SignInFormOptions } from './index';
+/**
+ * Renders the sign-in form with email and password fields.
+ *
+ * Features include:
+ * - Schema-based validation with configurable password rules
+ * - "Remember me" checkbox that persists the email to `localStorage`
+ * - Loading state and form disabling during submission
+ * - Error display via a notice component
+ * - i18n support for all labels and button text
+ *
+ * @param options - Configuration options for the sign-in form.
+ * @returns A `Renderable` form element.
+ *
+ * @example
+ * ```ts
+ * SignInForm({
+ *   onSignIn: async (data) => {
+ *     const error = await api.signIn(data.email, data.password)
+ *     return error ?? null
+ *   },
+ *   showRememberMe: true,
+ * })
+ * ```
+ */
 export declare function SignInForm({ onSignIn, passwordRules, labels, showRememberMe, }: SignInFormOptions): Renderable;

package/dist/types/components/auth/signup-form.d.ts

@@ -1,3 +1,39 @@
+/**
+ * Sign Up Form Component
+ *
+ * Renders the registration form with name, email, password, confirm password,
+ * and terms acceptance fields. Includes password strength indicator,
+ * schema-based validation, and loading state management.
+ *
+ * @module auth/signup-form
+ */
 import { Renderable } from '@tempots/dom';
 import { SignUpFormOptions } from './index';
+/**
+ * Renders the sign-up (registration) form.
+ *
+ * Features include:
+ * - Configurable fields: name, email, password, confirm password, terms checkbox
+ * - Schema-based validation with configurable password rules
+ * - Optional password strength indicator
+ * - Loading state and form disabling during submission
+ * - Error display via a notice component
+ * - i18n support for all labels and button text
+ *
+ * @param options - Configuration options for the sign-up form.
+ * @returns A `Renderable` form element.
+ *
+ * @example
+ * ```ts
+ * SignUpForm({
+ *   onSignUp: async (data) => {
+ *     const error = await api.signUp(data)
+ *     return error ?? null
+ *   },
+ *   showPasswordStrength: true,
+ *   showConfirmPassword: true,
+ *   showAcceptTermsAndConditions: true,
+ * })
+ * ```
+ */
 export declare function SignUpForm({ passwordRules, labels, initialEmail, initialName, showPasswordStrength, onSignUp, showNameField, showConfirmPassword, showAcceptTermsAndConditions, termsAndConditions, }: SignUpFormOptions): Renderable;

package/dist/types/components/auth/social-login-button.d.ts

@@ -1,45 +1,258 @@
+/**
+ * Social Login Button Component
+ *
+ * Reusable button components for social authentication providers. Includes
+ * a generic `SocialLoginButton`, a multi-button `SocialLoginButtons` container,
+ * and pre-configured convenience variants for each supported provider.
+ *
+ * @module auth/social-login-button
+ */
 import { Renderable, Value } from '@tempots/dom';
 import { SocialLoginButtonOptions, AuthProviderName } from './index';
 import { ControlSize } from '../theme';
 import { ThemeColorName } from '../../tokens';
+/**
+ * Renders a branded social login button for a specific authentication provider.
+ *
+ * Displays the provider's icon and a localized "Continue with {provider}" label.
+ * Handles both redirect and popup OAuth flows via the `onClick` handler.
+ *
+ * @param options - Configuration options for the social login button.
+ * @returns A `Renderable` button element styled for the specified provider.
+ *
+ * @example
+ * ```ts
+ * SocialLoginButton({
+ *   provider: 'google',
+ *   name: 'Google',
+ *   icon: 'logos:google-icon',
+ *   color: 'red',
+ *   onClick: async () => { await authClient.signIn.social({ provider: 'google' }) },
+ * })
+ * ```
+ */
 export declare function SocialLoginButton({ provider, onClick, size, name, icon, color, flow, labels, }: SocialLoginButtonOptions): Renderable;
+/**
+ * Minimal provider configuration passed to social login components.
+ *
+ * Contains the provider name and optional OAuth flow type.
+ */
 export type AuthProviderInfo = {
+    /** The social provider identifier. */
     provider: AuthProviderName;
+    /** The OAuth flow type. @default 'redirect' */
     flow?: 'redirect' | 'popup';
 };
+/**
+ * Renders a vertical stack of social login buttons for multiple providers.
+ *
+ * Iterates over the provided list of providers and renders a {@link SocialLoginButton}
+ * for each, using the provider metadata from {@link socialProviderInfo}.
+ *
+ * @param options - Configuration for the button group.
+ * @param options.providers - Reactive array of provider configurations.
+ * @param options.onProviderClick - Callback invoked when any provider button is clicked.
+ * @param options.size - The size of all buttons. @default 'md'
+ * @param options.className - Additional CSS class names for the container.
+ * @returns A `Renderable` stack of social login buttons.
+ *
+ * @example
+ * ```ts
+ * SocialLoginButtons({
+ *   providers: [{ provider: 'google' }, { provider: 'github' }],
+ *   onProviderClick: async (provider) => { await handleSocialLogin(provider) },
+ * })
+ * ```
+ */
 export declare function SocialLoginButtons({ providers, onProviderClick, size, className, }: {
     providers: Value<Array<AuthProviderInfo>>;
     onProviderClick?: (provider: AuthProviderName) => Promise<void>;
     size?: Value<ControlSize>;
     className?: Value<string>;
 }): Renderable;
+/**
+ * Mapping of all supported social provider names to their display metadata.
+ *
+ * Contains the human-readable name, Iconify icon identifier, and BeatUI theme
+ * color name for each provider. Used internally by social login button components.
+ */
 export declare const socialProviderInfo: Record<AuthProviderName, {
     name: string;
     icon: string;
     color: ThemeColorName | 'black';
 }>;
+/**
+ * Options type for specialized social login button variants.
+ *
+ * Same as {@link SocialLoginButtonOptions} but with `provider`, `name`, `icon`, and `color`
+ * pre-configured for the specific provider.
+ */
 export type SpecialSocialLoginButtonOptions = Omit<SocialLoginButtonOptions, 'provider' | 'name' | 'icon' | 'color'>;
+/**
+ * Pre-configured Google social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Google-branded login button.
+ */
 export declare const GoogleLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured GitHub social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` GitHub-branded login button.
+ */
 export declare const GitHubLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Apple social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Apple-branded login button.
+ */
 export declare const AppleLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Facebook social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Facebook-branded login button.
+ */
 export declare const FacebookLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured X (formerly Twitter) social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` X-branded login button.
+ */
 export declare const XLoginButtin: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Twitter social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Twitter-branded login button.
+ */
 export declare const TwitterLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Microsoft social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Microsoft-branded login button.
+ */
 export declare const MicrosoftLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Discord social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Discord-branded login button.
+ */
 export declare const DiscordLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured LinkedIn social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` LinkedIn-branded login button.
+ */
 export declare const LinkedInLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Instagram social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Instagram-branded login button.
+ */
 export declare const InstagramLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured TikTok social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` TikTok-branded login button.
+ */
 export declare const TiktokLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Snapchat social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Snapchat-branded login button.
+ */
 export declare const SnapchatLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Reddit social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Reddit-branded login button.
+ */
 export declare const RedditLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Pinterest social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Pinterest-branded login button.
+ */
 export declare const PinterestLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Twitch social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Twitch-branded login button.
+ */
 export declare const TwitchLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Steam social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Steam-branded login button.
+ */
 export declare const SteamLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Epic Games social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Epic Games-branded login button.
+ */
 export declare const EpicLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured PlayStation social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` PlayStation-branded login button.
+ */
 export declare const PlayStationLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Xbox social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Xbox-branded login button.
+ */
 export declare const XboxLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured WhatsApp social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` WhatsApp-branded login button.
+ */
 export declare const WhatsAppLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured WeChat social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` WeChat-branded login button.
+ */
 export declare const WeChatLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Amazon social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Amazon-branded login button.
+ */
 export declare const AmazonLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured Yahoo social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` Yahoo-branded login button.
+ */
 export declare const YahooLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;
+/**
+ * Pre-configured PayPal social login button.
+ *
+ * @param options - Button options (provider, name, icon, and color are pre-filled).
+ * @returns A `Renderable` PayPal-branded login button.
+ */
 export declare const PayPalLoginButton: (options: SpecialSocialLoginButtonOptions) => Renderable;

package/dist/types/components/auth/social-providers.d.ts

@@ -1,2 +1,28 @@
+/**
+ * Social Providers Component
+ *
+ * Renders a stack of social login buttons based on the provided configuration.
+ *
+ * @module auth/social-providers
+ */
 import { SocialProvidersOptions } from './types';
-export declare function SocialProviders({ providers }: SocialProvidersOptions): import("@tempots/dom").Renderable;
+/**
+ * Renders a vertical stack of social login buttons for the configured providers.
+ *
+ * A thin wrapper around {@link SocialLoginButtons} that maps `onSocialLogin`
+ * to the `onProviderClick` callback.
+ *
+ * @param options - Configuration for which providers to display and how to handle clicks.
+ * @returns A `TNode` containing a stack of social login buttons.
+ *
+ * @example
+ * ```ts
+ * SocialProviders({
+ *   providers: [{ provider: 'google' }, { provider: 'github' }],
+ *   onSocialLogin: async (provider) => {
+ *     await authClient.signIn.social({ provider })
+ *   },
+ * })
+ * ```
+ */
+export declare function SocialProviders({ providers, onSocialLogin, }: SocialProvidersOptions): import("@tempots/dom").Renderable;