@sublimee/auth-ui 0.1.1 → 0.1.12

package/AI_INDEX.md

@@ -0,0 +1,64 @@
+# @sublimee/auth-ui AI Index
+
+Token-efficient entry point for AI agents reading the installed npm package.
+
+## Use This Package For
+
+- ready-to-use OAuth buttons,
+- built-in button motion and loading,
+- token-driven button customization without rebuilding base styling.
+
+## First Move
+
+```tsx
+import "@sublimee/tokens/tokens.css";
+import { OAuthButton } from "@sublimee/auth-ui";
+
+<OAuthButton provider="google" />
+```
+
+## Current Public Surface
+
+- `OAuthButton`
+- `GoogleIcon`
+- `DiscordIcon`
+- `useButtonAnimation`
+
+Current providers:
+- `google`
+- `discord`
+
+## Important Defaults
+
+- built on `@base-ui/react/button`
+- default variant: `secondary`
+- default animation: `press`
+- loading is built in
+- default loading animation: `spinner`
+- runtime button styles are included automatically
+
+## Key Props
+
+- `provider`
+- `variant`
+- `animation`
+- `loading`
+- `loadingAnimation`
+- `disabled`
+- `className`
+- `children`
+
+## Read Next
+
+1. [README.md](./README.md)
+2. [src/types.ts](./src/types.ts)
+3. [src/oauth-button.tsx](./src/oauth-button.tsx)
+4. [src/base-button.tsx](./src/base-button.tsx)
+5. [src/runtime-styles.ts](./src/runtime-styles.ts)
+
+## Non-Goals
+
+Do not assume:
+- this package is headless,
+- the consumer must import extra component CSS for the normal path,
+- the consumer should rebuild spacing, border, or focus behavior from scratch.

package/README.md

@@ -1,169 +1,129 @@
 # @sublimee/auth-ui
 
-Headless authentication UI components for Sublime, built on base-ui primitives.
+AI-first package doc for Sublime auth components.
 
-## Design Philosophy
+If you are an AI agent reading the installed npm package directly, start with [AI_INDEX.md](./AI_INDEX.md).
 
-**"Headless but sensible"**
+## Use This Package When
 
-Our components are built on top of [base-ui](https://base-ui.com/) primitives. This means:
+- 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.
 
-- ✅ **We inherit base-ui's sensible defaults** — cursor-pointer, focus states, keyboard navigation, accessibility
-- ✅ **We DON'T impose visual opinions** — you control 100% of styling via Tailwind `className`
-- ✅ **You get a solid, accessible foundation** that looks exactly how you want
+## First Move
 
-This approach solves recurring UI issues (like missing `cursor: pointer`) once and for all, while preserving complete flexibility over visual design.
-
-## Installation
+```tsx
+import "@sublimee/tokens/tokens.css";
+import { OAuthButton } from "@sublimee/auth-ui";
 
-```bash
-pnpm add @sublimee/auth-ui
+<OAuthButton provider="google" />
 ```
 
-## Dependencies
+The package injects its runtime button styles automatically. No extra component stylesheet import is required for the normal path.
 
-- `@base-ui/react` — Button primitives with sensible defaults
-- `react` ^19.0.0
-- `react-dom` ^19.0.0
+## Current Public Surface
 
-## Components
+### Components
 
-### OAuthButton
+- `OAuthButton`
 
-A headless OAuth authentication button with Google and Discord provider icons.
+### Other exports
 
-```tsx
-import { OAuthButton } from '@sublimee/auth-ui';
+- `GoogleIcon`
+- `DiscordIcon`
+- `useButtonAnimation`
 
-// Basic usage — inherits cursor-pointer and focus states from base-ui
-<OAuthButton
-  provider="google"
-  onClick={signInWithGoogle}
-  className="flex items-center gap-3 px-6 py-3 bg-white text-gray-900 rounded-lg font-medium"
-/>
+### Current providers
 
-// Outline style
-<OAuthButton
-  provider="discord"
-  onClick={signInWithDiscord}
-  className="flex items-center gap-3 px-6 py-3 border border-white/20 text-white rounded-lg hover:bg-white/5"
-/>
+- `google`
+- `discord`
 
-// Icon only — pass {null} as children
-<OAuthButton
-  provider="google"
-  onClick={signInWithGoogle}
-  className="p-3 rounded-full bg-white/10 hover:bg-white/20 transition-colors"
->
-  {null}
-</OAuthButton>
+## Important Defaults
 
-// Loading state
-<OAuthButton
-  provider="google"
-  loading
-  className="opacity-50"
-/>
+- 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
 
-// Custom text
+## Primary API
+
+```tsx
 <OAuthButton
   provider="google"
-  onClick={signInWithGoogle}
-  className="px-6 py-3 bg-blue-600 text-white rounded-lg"
+  variant="secondary"
+  loading={false}
+  disabled={false}
 >
-  Sign in with Google
+  Continuar con Google
 </OAuthButton>
 ```
 
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `provider` | `'google' \| 'discord'` | required | OAuth provider to authenticate with |
-| `onClick` | `() => void` | - | Click handler |
-| `loading` | `boolean` | `false` | Shows spinner when true |
-| `disabled` | `boolean` | `false` | Disables the button |
-| `className` | `string` | - | Tailwind classes for styling |
-| `children` | `ReactNode` | provider name | Button text. Pass `{null}` for icon-only |
-
-#### Sensible defaults we provide
+| Prop | Type | Default | Meaning |
+|------|------|---------|---------|
+| `provider` | `'google' \| 'discord'` | required | OAuth provider |
+| `variant` | `'primary' \| 'secondary'` | `'secondary'` | emphasis level |
+| `animation` | `'press'` | `'press'` | interaction motion |
+| `loading` | `boolean` | `false` | shows loading UI and disables interaction |
+| `loadingAnimation` | `'spinner'` | `'spinner'` | loading indicator |
+| `disabled` | `boolean` | `false` | disables interaction |
+| `className` | `string` | - | later override hook |
+| `children` | `ReactNode` | provider label | custom content; pass `{null}` for icon-only |
 
-`OAuthButton` includes these UX fundamentals automatically:
+## Task Routing
 
-| Behavior | Automatic? |
-|----------|------------|
-| `cursor: pointer` on hover | ✅ |
-| `cursor: not-allowed` when disabled/loading | ✅ |
-| **Focus visible states** via base-ui | ✅ |
-| **Keyboard navigation** via base-ui | ✅ |
-| **ARIA attributes** via base-ui | ✅ |
-| **Disabled state handling** via base-ui | ✅ |
-
-You don't need to add `cursor-pointer` to your className — it's automatic. Your `className` is merged with our sensible defaults, with your styles taking precedence.
-
-### Icons
-
-Individual icons are also exported if you need them separately:
+### Google auth button
 
 ```tsx
-import { GoogleIcon, DiscordIcon, SpinnerIcon } from '@sublimee/auth-ui';
-
-<GoogleIcon size={24} className="text-red-500" />
-<DiscordIcon size={20} />
-<SpinnerIcon size={16} className="animate-spin" />
+<OAuthButton provider="google" />
 ```
 
-## Styling Guidelines
-
-Since components are headless, you provide all styles via `className`. Here are recommended patterns:
-
-### Common Patterns
+### Primary call to action
 
 ```tsx
-// Full-width button
-className="w-full flex items-center justify-center gap-3 px-6 py-3 bg-white text-gray-900 rounded-lg"
-
-// Minimal icon button
-className="p-2 rounded-full hover:bg-white/10 transition-colors"
-
-// Outline variant
-className="flex items-center gap-2 px-4 py-2 border border-current rounded-md hover:bg-white/5"
-
-// Loading state
-className="opacity-50 cursor-wait"
+<OAuthButton provider="google" variant="primary" />
 ```
 
-### State Handling
-
-The component accepts a `disabled` prop and renders in a loading state when `loading={true}`. These states automatically get `cursor: not-allowed` from base-ui, but you may want to add visual indicators:
+### Loading state
 
 ```tsx
-<OAuthButton
-  provider="google"
-  loading={isLoading}
-  disabled={isLoading}
-  className={`flex items-center gap-3 px-6 py-3 rounded-lg ${
-    isLoading ? 'opacity-50' : 'hover:bg-gray-50'
-  }`}
-/>
+<OAuthButton provider="google" loading />
 ```
 
-## TypeScript
+## Customization Order
 
-Full TypeScript support is included:
+Use this order:
+1. import tokens
+2. override semantic CSS custom properties
+3. use props like `variant`, `loading`, and `disabled`
+4. use `className` only for edge-case local adjustments
 
-```tsx
-import type { OAuthButtonProps, OAuthProvider, OAuthIconsProps } from '@sublimee/auth-ui';
+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;
+}
 ```
 
-## Why base-ui?
+## 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,
+- customization should extend the component rather than complete it.
 
-We chose base-ui as our foundation because:
+## Notes
 
-1. **Sensible defaults out of the box** — No more forgetting `cursor: pointer`
-2. **Accessibility built-in** — Proper ARIA, focus management, keyboard support
-3. **Headless by design** — Complete control over styling
-4. **Production-tested** — Built by the MUI team, battle-tested at scale
+- `@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.
 
 ## License
 

package/dist/animations.css

@@ -0,0 +1,52 @@
+/**
+ * @sublimee/auth-ui runtime animations
+ *
+ * Optional legacy export.
+ * Most consumers should not need to import this file because auth-ui now
+ * injects its runtime button styles automatically.
+ */
+
+@keyframes sublime-button-press-release {
+  0% {
+    transform: translateY(1px) scale(0.985);
+    box-shadow: var(--sublime-button-shadow-active);
+  }
+  100% {
+    transform: translateY(0) scale(1);
+    box-shadow: var(--sublime-button-shadow);
+  }
+}
+
+@keyframes sublime-button-spinner {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.sublime-button-pressed {
+  transform: translateY(1px) scale(0.985);
+  box-shadow: var(--sublime-button-shadow-active);
+}
+
+.animate-sublime-button-press-release {
+  animation: sublime-button-press-release 180ms var(--sublime-ease-out, cubic-bezier(0, 0, 0.2, 1));
+}
+
+.sublime-button__spinner {
+  animation: sublime-button-spinner 720ms linear infinite;
+  transform-origin: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-sublime-button-press-release {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+  }
+
+  .sublime-button__spinner {
+    animation-duration: 1.6s !important;
+  }
+}

package/dist/index.d.mts

@@ -1,88 +1,105 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode } from 'react';
+import { ButtonHTMLAttributes, MouseEventHandler, ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type OAuthProvider = 'google' | 'discord';
+type ButtonVariant = 'primary' | 'secondary';
+type ButtonAnimation = 'press';
+type ButtonLoadingAnimation = 'spinner';
 interface OAuthButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
     /**
-     * The OAuth provider to authenticate with
+     * The OAuth provider to authenticate with.
      */
     provider: OAuthProvider;
     /**
-     * Click handler - typically calls supabase.auth.signInWithOAuth
+     * Click handler - typically calls supabase.auth.signInWithOAuth.
      */
-    onClick?: () => void;
+    onClick?: MouseEventHandler<HTMLButtonElement>;
     /**
-     * Loading state - shows spinner when true
+     * Loading state - shows the configured loading animation and disables interaction.
      */
     loading?: boolean;
     /**
-     * Custom className - use Tailwind for styling
-     * @example "flex items-center gap-2 px-4 py-2 bg-white text-gray-900 rounded-lg"
+     * Loading animation shown while `loading` is true.
+     * @default 'spinner'
+     */
+    loadingAnimation?: ButtonLoadingAnimation;
+    /**
+     * Visual variant of the button.
+     * - primary: High emphasis, filled background
+     * - secondary: Medium emphasis, bordered (default)
+     * @default 'secondary'
+     */
+    variant?: ButtonVariant;
+    /**
+     * Interaction motion applied on press.
+     * @default 'press'
+     */
+    animation?: ButtonAnimation;
+    /**
+     * Custom className appended after the built-in runtime classes.
      */
     className?: string;
     /**
-     * Button children - defaults to provider name
-     * Pass `null` for icon-only mode
+     * Button children - defaults to provider name in Spanish.
+     * Pass `null` for icon-only mode.
      */
     children?: ReactNode;
 }
 interface OAuthIconsProps {
     /**
-     * Icon size in pixels (min: 1)
+     * Icon size in pixels (min: 1).
      * @default 24
      */
     size?: number;
+    /**
+     * Optional className for icon-specific styling.
+     */
+    className?: string;
+}
+interface UseButtonAnimationResult {
+    /**
+     * CSS classes to apply for the current animation state.
+     */
+    animationClassName: string;
+    /**
+     * Event handlers to attach to the button.
+     */
+    eventHandlers: Pick<ButtonHTMLAttributes<HTMLButtonElement>, 'onBlur' | 'onKeyDown' | 'onKeyUp' | 'onMouseDown' | 'onMouseLeave' | 'onMouseUp' | 'onTouchEnd' | 'onTouchStart'>;
 }
 
 /**
  * OAuthButton component
  *
- * A headless OAuth button built on top of base-ui's Button primitive.
- * Includes sensible defaults (cursor-pointer) while remaining fully
- * customizable via className.
- *
- * Design Philosophy:
- * - We add sensible UX defaults (cursor-pointer, proper disabled states)
- * - We don't impose visual opinions - you control all styling via className
- * - The result is a solid, accessible foundation that looks exactly how you want
+ * Built on top of the shared Sublime button foundation so it inherits
+ * runtime styling, semantic variants, curated press motion, and loading
+ * behavior by default.
  *
  * @example
  * ```tsx
- * // Basic usage - cursor-pointer is automatic
- * <OAuthButton
- *   provider="google"
- *   onClick={signInWithGoogle}
- *   className="flex items-center gap-3 px-6 py-3 bg-white text-gray-900 rounded-lg font-medium"
- * />
- *
- * // Icon only - pass {null} as children
- * <OAuthButton
- *   provider="google"
- *   className="p-3 rounded-full hover:bg-white/10"
- * >
- *   {null}
- * </OAuthButton>
- *
- * // Loading state - cursor-not-allowed is automatic
- * <OAuthButton provider="google" loading className="opacity-50" />
+ * <OAuthButton provider="google" />
+ * <OAuthButton provider="discord" variant="primary" loading />
  * ```
  */
 declare const OAuthButton: react.ForwardRefExoticComponent<OAuthButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Hook to provide the curated button press animation.
+ *
+ * Handles mouse, touch, and keyboard interaction so motion feedback stays
+ * consistent across the different ways users can activate a button.
+ */
+declare function useButtonAnimation(animation?: ButtonAnimation | null): UseButtonAnimationResult;
+
 /**
  * Google Logo Icon
  * Official Google "G" logo for OAuth authentication
  */
-declare function GoogleIcon({ size }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
+declare function GoogleIcon({ size, className }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
 /**
  * Discord Logo Icon
  * Official Discord logo for OAuth authentication
  */
-declare function DiscordIcon({ size }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
-/**
- * Spinner Icon for loading state
- */
-declare function SpinnerIcon({ size }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
+declare function DiscordIcon({ size, className }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
 
-export { DiscordIcon, GoogleIcon, OAuthButton, type OAuthButtonProps, type OAuthIconsProps, type OAuthProvider, SpinnerIcon };
+export { type ButtonAnimation, type ButtonLoadingAnimation, type ButtonVariant, DiscordIcon, GoogleIcon, OAuthButton, type OAuthButtonProps, type OAuthIconsProps, type OAuthProvider, type UseButtonAnimationResult, useButtonAnimation };

package/dist/index.d.ts

@@ -1,88 +1,105 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode } from 'react';
+import { ButtonHTMLAttributes, MouseEventHandler, ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type OAuthProvider = 'google' | 'discord';
+type ButtonVariant = 'primary' | 'secondary';
+type ButtonAnimation = 'press';
+type ButtonLoadingAnimation = 'spinner';
 interface OAuthButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
     /**
-     * The OAuth provider to authenticate with
+     * The OAuth provider to authenticate with.
      */
     provider: OAuthProvider;
     /**
-     * Click handler - typically calls supabase.auth.signInWithOAuth
+     * Click handler - typically calls supabase.auth.signInWithOAuth.
      */
-    onClick?: () => void;
+    onClick?: MouseEventHandler<HTMLButtonElement>;
     /**
-     * Loading state - shows spinner when true
+     * Loading state - shows the configured loading animation and disables interaction.
      */
     loading?: boolean;
     /**
-     * Custom className - use Tailwind for styling
-     * @example "flex items-center gap-2 px-4 py-2 bg-white text-gray-900 rounded-lg"
+     * Loading animation shown while `loading` is true.
+     * @default 'spinner'
+     */
+    loadingAnimation?: ButtonLoadingAnimation;
+    /**
+     * Visual variant of the button.
+     * - primary: High emphasis, filled background
+     * - secondary: Medium emphasis, bordered (default)
+     * @default 'secondary'
+     */
+    variant?: ButtonVariant;
+    /**
+     * Interaction motion applied on press.
+     * @default 'press'
+     */
+    animation?: ButtonAnimation;
+    /**
+     * Custom className appended after the built-in runtime classes.
      */
     className?: string;
     /**
-     * Button children - defaults to provider name
-     * Pass `null` for icon-only mode
+     * Button children - defaults to provider name in Spanish.
+     * Pass `null` for icon-only mode.
      */
     children?: ReactNode;
 }
 interface OAuthIconsProps {
     /**
-     * Icon size in pixels (min: 1)
+     * Icon size in pixels (min: 1).
      * @default 24
      */
     size?: number;
+    /**
+     * Optional className for icon-specific styling.
+     */
+    className?: string;
+}
+interface UseButtonAnimationResult {
+    /**
+     * CSS classes to apply for the current animation state.
+     */
+    animationClassName: string;
+    /**
+     * Event handlers to attach to the button.
+     */
+    eventHandlers: Pick<ButtonHTMLAttributes<HTMLButtonElement>, 'onBlur' | 'onKeyDown' | 'onKeyUp' | 'onMouseDown' | 'onMouseLeave' | 'onMouseUp' | 'onTouchEnd' | 'onTouchStart'>;
 }
 
 /**
  * OAuthButton component
  *
- * A headless OAuth button built on top of base-ui's Button primitive.
- * Includes sensible defaults (cursor-pointer) while remaining fully
- * customizable via className.
- *
- * Design Philosophy:
- * - We add sensible UX defaults (cursor-pointer, proper disabled states)
- * - We don't impose visual opinions - you control all styling via className
- * - The result is a solid, accessible foundation that looks exactly how you want
+ * Built on top of the shared Sublime button foundation so it inherits
+ * runtime styling, semantic variants, curated press motion, and loading
+ * behavior by default.
  *
  * @example
  * ```tsx
- * // Basic usage - cursor-pointer is automatic
- * <OAuthButton
- *   provider="google"
- *   onClick={signInWithGoogle}
- *   className="flex items-center gap-3 px-6 py-3 bg-white text-gray-900 rounded-lg font-medium"
- * />
- *
- * // Icon only - pass {null} as children
- * <OAuthButton
- *   provider="google"
- *   className="p-3 rounded-full hover:bg-white/10"
- * >
- *   {null}
- * </OAuthButton>
- *
- * // Loading state - cursor-not-allowed is automatic
- * <OAuthButton provider="google" loading className="opacity-50" />
+ * <OAuthButton provider="google" />
+ * <OAuthButton provider="discord" variant="primary" loading />
  * ```
  */
 declare const OAuthButton: react.ForwardRefExoticComponent<OAuthButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Hook to provide the curated button press animation.
+ *
+ * Handles mouse, touch, and keyboard interaction so motion feedback stays
+ * consistent across the different ways users can activate a button.
+ */
+declare function useButtonAnimation(animation?: ButtonAnimation | null): UseButtonAnimationResult;
+
 /**
  * Google Logo Icon
  * Official Google "G" logo for OAuth authentication
  */
-declare function GoogleIcon({ size }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
+declare function GoogleIcon({ size, className }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
 /**
  * Discord Logo Icon
  * Official Discord logo for OAuth authentication
  */
-declare function DiscordIcon({ size }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
-/**
- * Spinner Icon for loading state
- */
-declare function SpinnerIcon({ size }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
+declare function DiscordIcon({ size, className }: OAuthIconsProps): react_jsx_runtime.JSX.Element;
 
-export { DiscordIcon, GoogleIcon, OAuthButton, type OAuthButtonProps, type OAuthIconsProps, type OAuthProvider, SpinnerIcon };
+export { type ButtonAnimation, type ButtonLoadingAnimation, type ButtonVariant, DiscordIcon, GoogleIcon, OAuthButton, type OAuthButtonProps, type OAuthIconsProps, type OAuthProvider, type UseButtonAnimationResult, useButtonAnimation };