npm package: @litforge/login-form
Description: A complete login form component built with Lit, featuring email and password inputs, validation, and customizable styling.
Latest version: 0.1.22

# @litforge/login-form

A complete login form component built with Lit, featuring email and password inputs, validation, and customizable styling.

## Overview

The `LoginForm` component provides a ready-to-use login form with:
- Email and password inputs with validation
- Optional password visibility toggle
- Loading states
- Error handling
- Logo support
- Fully customizable via CSS variables

## Installation

```bash
npm install @litforge/login-form
# or
pnpm add @litforge/login-form
# or
yarn add @litforge/login-form
```

**Note**: This component depends on:
- `@litforge/email-input`
- `@litforge/password-input`
- `@litforge/loading-button`
- `@litforge/logo-img`

## Basic Usage

```html
<script type="module">
  import '@litforge/login-form';
</script>

<login-form
  heading="Welcome Back"
  subheading="Sign in to your account"
  button-label="Sign In"
  @login-submit="${handleLogin}"
></login-form>
```

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `heading` | `string` | `undefined` | Main heading text |
| `subheading` | `string` | `undefined` | Subheading text |
| `logoImgSrc` | `string` | `undefined` | Logo image source URL |
| `logoImgAlt` | `string` | `undefined` | Logo image alt text |
| `logoImgSize` | `string` | `undefined` | Logo image size |
| `email` | `string` | `undefined` | Initial email value |
| `emailLabel` | `string` | `undefined` | Email input label |
| `emailPlaceholder` | `string` | `undefined` | Email input placeholder |
| `emailError` | `string` | `undefined` | Email error message |
| `password` | `string` | `undefined` | Initial password value |
| `passwordLabel` | `string` | `undefined` | Password input label |
| `passwordPlaceholder` | `string` | `undefined` | Password input placeholder |
| `passwordError` | `string` | `undefined` | Password error message |
| `buttonLabel` | `string` | `undefined` | Submit button label |
| `login` | `boolean` | `false` | Shows login state |
| `disabled` | `boolean` | `false` | Disables the form |
| `showPasswordToggle` | `boolean` | `false` | Shows password visibility toggle |
| `errorMessage` | `string` | `undefined` | General error message |
| `allowUsername` | `boolean` | `false` | Allows login with username instead of email validation |

## Events

### `login-submit`

Fired when the form is submitted with valid data.

```typescript
interface LoginSubmitDetail {
  email: string;
  password: string;
}
```

## Examples

### Basic Login Form

```html
<login-form
  heading="Sign In"
  button-label="Login"
  @login-submit="${(e) => console.log(e.detail)}"
></login-form>
```

### With Logo and Custom Labels

```html
<login-form
  heading="Welcome Back"
  subheading="Sign in to continue"
  logo-img-src="/logo.png"
  logo-img-alt="Company Logo"
  email-label="Email Address"
  password-label="Password"
  button-label="Sign In"
  show-password-toggle
  @login-submit="${handleLogin}"
></login-form>
```

### With Error Handling

```html
<login-form
  email-error="${emailError}"
  password-error="${passwordError}"
  error-message="${generalError}"
  @login-submit="${handleLogin}"
></login-form>
```

### With Username Support

When `allowUsername` is enabled, the form will accept both email and username formats without email validation:

```html
<login-form
  allow-username
  heading="Sign In"
  subheading="Use your username or email"
  email-label="Username or Email"
  email-placeholder="username or email@example.com"
  button-label="Login"
  @login-submit="${handleLogin}"
></login-form>
```

**Note**: When `allowUsername` is `true`, the email field will only validate that it's not empty, allowing both usernames and email formats.

## Event Handling

```javascript
function handleLogin(event) {
  const { email, password } = event.detail;
  // Handle login logic
  console.log('Login attempt:', { email, password });
}

document.querySelector('login-form')
  .addEventListener('login-submit', handleLogin);
```

## Styling

The component uses CSS variables for theming:

```css
login-form {
  --lf-login-form-font-family: 'Inter', sans-serif;
  --lf-login-form-text-color: #111827;
  --lf-login-form-radius: 12px;
  --lf-login-form-space-lg: 16px;
  /* ... more variables */
}
```

## TypeScript

```typescript
import { LoginForm } from '@litforge/login-form';
import type { LoginFormProps, LoginSubmitDetail } from '@litforge/login-form';

const props: LoginFormProps = {
  heading: 'Welcome',
  buttonLabel: 'Sign In',
  onLoginSubmit: (event: CustomEvent<LoginSubmitDetail>) => {
    console.log(event.detail);
  }
};
```

## License

Part of the LitForge component library.