npm package: @sublimee/auth-ui
Description: Production-ready authentication UI components for Sublime
Author: Sublime Team
Latest version: 0.1.22

# @sublimee/auth-ui

AI-first package doc for Sublime auth components.

If you are an AI agent reading the installed npm package directly, start with [AI_INDEX.md](./AI_INDEX.md).

## Use This Package When

- you need a ready-to-use OAuth button,
- you want built-in structure, motion, loading, and accessibility defaults,
- you want token-driven customization instead of rebuilding button styles from scratch.

## First Move

```tsx
import { OAuthButton } from "@sublimee/auth-ui";

<OAuthButton provider="google" />
```

The package injects its runtime button styles automatically. No extra component stylesheet import or `@sublimee/tokens` install is required for the normal path.

If you want shared Sublime theming across your app, install `@sublimee/tokens` and import its CSS once:

```tsx
import "@sublimee/tokens/tokens.css";
```

## Current Public Surface

### Components

- `OAuthButton`

### Other exports

- `GoogleIcon`
- `DiscordIcon`
- `useButtonAnimation`

### Current providers

- `google`
- `discord`

## Important Defaults

- built on `@base-ui/react/button`
- default variant: `secondary`
- default interaction motion: `press`
- loading is built in
- default loading animation: `spinner`
- focus styling is semantic-token driven

## Primary API

```tsx
<OAuthButton
  provider="google"
  variant="secondary"
  loading={false}
  disabled={false}
>
  Continuar con Google
</OAuthButton>
```

| Prop | Type | Default | Meaning |
|------|------|---------|---------|
| `provider` | `'google' \| 'discord'` | required | OAuth provider |
| `variant` | `'primary' \| 'secondary'` | `'secondary'` | emphasis level |
| `animation` | `'press' \| 'spring'` | `'press'` | interaction motion (legacy, use `animationConfig`) |
| `animationConfig` | `ButtonAnimationConfig` | - | advanced animation control |
| `loading` | `boolean` | `false` | shows loading UI and disables interaction |
| `loadingAnimation` | `'spinner'` | `'spinner'` | loading indicator |
| `disabled` | `boolean` | `false` | disables interaction |
| `className` | `string` | - | additional CSS classes |
| `children` | `ReactNode` | provider label | custom content; pass `{null}` for icon-only |

### ButtonAnimationConfig

```typescript
interface ButtonAnimationConfig {
  mode: 'press' | 'spring';
  pressDuration?: number;    // ms for press phase (spring only) - default: 150
  releaseDuration?: number;  // ms for release phase (spring only) - default: 150
  threshold?: number;        // ms to detect quick click (spring only) - default: 200
}
```

**Animation modes:**
- `press` (default): Button stays pressed while holding, releases immediately on mouseup with 180ms animation.
- `spring`: Quick clicks (<200ms) trigger a full spring animation (150ms press + 150ms release) that completes regardless of when you release. Long presses behave like standard press.

## Task Routing

### Google auth button

```tsx
<OAuthButton provider="google" />
```

### Primary call to action

```tsx
<OAuthButton provider="google" variant="primary" />
```

### Loading state

```tsx
<OAuthButton provider="google" loading />
```

### Spring animation

```tsx
<OAuthButton
  provider="google"
  animationConfig={{ mode: 'spring' }}
/>
```

### Extruded 3D button

Use the `sublime-button--extruded` class for a 3D box effect with stacked shadows:

```tsx
<OAuthButton
  provider="google"
  className="sublime-button--extruded"
/>
```

Combine with spring animation:

```tsx
<OAuthButton
  provider="google"
  className="sublime-button--extruded"
  animationConfig={{ mode: 'spring' }}
/>
```

**Extruded button CSS custom properties:**

```css
.sublime-button--extruded {
  --sublime-button-extrude-depth: 5.5px;        /* Extrusion depth */
  --sublime-button-extrude-border-light: #E4E4E8;  /* Top/left border color */
  --sublime-button-extrude-shadow-1: #EBEBEF;   /* Shadow layer 1 (lightest) */
  --sublime-button-extrude-shadow-2: #E6E6EA;   /* Shadow layer 2 */
  --sublime-button-extrude-shadow-3: #E0E0E6;   /* Shadow layer 3 */
  --sublime-button-extrude-shadow-4: #DADAE0;   /* Shadow layer 4 */
  --sublime-button-extrude-shadow-5: #D4D4DA;   /* Shadow layer 5 */
  --sublime-button-extrude-shadow-6: #CECED4;   /* Shadow layer 6 (darkest) */
}
```

## Customization Order

Use this order:
1. install and import `@sublimee/tokens` when you want shared app-wide theming
2. override semantic CSS custom properties
3. use props like `variant`, `loading`, and `disabled`
4. use `className` for visual variants like `sublime-button--extruded`
5. use `animationConfig` for interaction customization

Example:

```css
@import "@sublimee/tokens/tokens.css";

:root {
  --sublime-color-interactive-primary: #ec4899;
  --sublime-color-interactive-primary-hover: #db2777;
  --sublime-color-focus-ring: #ec4899;
  --sublime-radius-button: 9999px;
}
```

## Zero-Setup Contract

For this package, zero-setup means:
- the button should look like a button on first render,
- provider icon and layout should be built in,
- the consumer should not rebuild spacing, border, focus, or interaction states,
- the consumer should not need `@sublimee/tokens` for a usable default render,
- customization should extend the component rather than complete it.

## Notes

- `@sublimee/auth-ui/animations.css` still exists as a legacy optional export, but the normal path should not require it.
- Public-facing default copy is currently Spanish.
- The `sublime-button--extruded` class provides a 3D box effect using stacked box-shadows. It adapts colors automatically for primary/secondary variants and dark mode.

## License

MIT