@tempots/beatui 0.82.1 → 0.83.0

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;

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;