LoginForm Component
Relevant source files
The following files were used as context for generating this wiki page:
The LoginForm component is a client-side React component that provides a two-step authentication interface using One-Time Passwords (OTP). It serves as the primary entry point for users to access CellarNode dashboards, supporting both "importer" and "producer" user types. The component handles the collection of user emails, the requesting of OTP codes via an external API, and the subsequent verification of those codes to establish a session.
Sources: src/react/login-form.tsx:1-55, src/types.ts:75-81
Architecture and Data Flow
The component follows a state-machine pattern to manage the transition between the email entry phase and the OTP verification phase. It integrates directly with the AuthApi for network requests and the AuthStore for persisting the resulting access tokens.
Authentication Lifecycle
The authentication flow begins with the user providing a work email. Upon submission, the component triggers an OTP request. If successful, the UI transitions to a 6-digit input field with a countdown timer.
The diagram shows the sequential steps from initial email input to final session establishment.
Sources: src/react/login-form.tsx:135-212
Component State Management
The component tracks several critical pieces of information to manage the UI and timers:
- Step: Current view (
emailorotp). - Countdown: Visual representation of the OTP expiration time and the resend availability window.
- Loading State: Tracks
isSubmittingto disable buttons and show loaders during API calls. - Error Handling: Specifically handles
AuthErrorinstances to show context-aware messages (e.g., rate limits, invalid codes).
Sources: src/react/login-form.tsx:94-110, src/types.ts:44-55
API Integration
The LoginForm relies on the AuthApi interface to communicate with the backend. This abstraction allows the UI to remain agnostic of the underlying fetch implementation.
| Method | Purpose | Key Parameters |
|---|---|---|
requestOtp | Sends a code to the user's email | email |
verifyOtp | Validates the 6-digit code | email, code |
setAccessToken | Persists the session in the store | token, expiresIn |
Sources: src/auth-api.ts:25-60, src/types.ts:75-81
OTP Verification Sequence
When a user enters the 6-digit code, the following sequence occurs:
The sequence illustrates how the component validates the user's role before finalizing the login.
Sources: src/react/login-form.tsx:177-200, src/auth-api.ts:38-60
UI Components and Visuals
OTP Input System
The component utilizes a specialized InputOTP system composed of groups and slots to provide a high-fidelity input experience. This includes visual feedback for active slots and "shaking" animations on error.
- InputOTPGroup: Containers for segments of the 6-digit code.
- InputOTPSlot: Individual digit boxes with caret blinking and fade-in animations.
- InputOTPSeparator: Visual break (dash) between digit groups.
Sources: src/react/input-otp-slots.tsx:64-159, src/react/login-form.tsx:340-365
SquircleShift Decoration
For desktop layouts, the LoginForm includes a SquircleShift component. This is a WebGL-based decorative background rendered via @react-three/fiber using custom GLSL shaders. It adjusts its background color based on the theme prop (light or dark).
The diagram outlines the rendering pipeline for the decorative background.
Sources: src/react/squircle-shift.tsx:191-226, src/react/login-form.tsx:441-445
Configuration Options (Props)
The component is highly configurable to support different brand identities and deployment scenarios.
| Prop | Type | Description |
|---|---|---|
userType | "importer" | "producer" | Limits login to specific account types. |
brandName | string | Display name of the application. |
authApi | AuthApi | Implementation of the authentication API. |
authStore | AuthStore | Interface for token storage. |
inviteMode | boolean | If true, shows a banner about organization invitations. |
theme | "light" | "dark" | Sets the visual style (defaults to light). |
notFoundContent | ReactNode | Custom UI shown when a user email is not found. |
Sources: src/react/login-form.tsx:32-60, src/types.ts:88-92
Error Handling Logic
The component maps internal error codes to user-friendly messages. If an onError callback is provided, the component delegates the full error reporting (e.g., to a toast system) and only shows a brief hint in the UI.
| Error Code | UI Message |
|---|---|
USER_NOT_FOUND | "No account found with this email." |
OTP_RATE_LIMIT | "Too many code requests. Please wait..." |
OTP_NOT_FOUND | "Code expired. Please request a new one." |
OTP_INVALID | "Invalid code. X attempt(s) remaining." |
Sources: src/react/login-form.tsx:75-81, src/react/login-form.tsx:114-133
Summary
The LoginForm component provides a secure and polished OTP-based entry point for the CellarNode ecosystem. By abstracting API logic and focusing on state-driven UI transitions, it ensures a consistent authentication experience across different dashboard implementations while maintaining strict enforcement of user roles and session persistence.