@oussemasahbeni/keycloakify-login-shadcn 250004.0.8 → 250004.0.10

package/README.md

@@ -0,0 +1,317 @@
+# Keycloakify Shadcn Starter
+
+A modern, production-ready Keycloak login theme built with React, TypeScript, Tailwind CSS v4, shadcn/ui, and Keycloakify v11.
+
+**npm Package:** [@oussemasahbeni/keycloakify-login-shadcn](https://www.npmjs.com/package/@oussemasahbeni/keycloakify-login-shadcn)
+
+---
+
+## ✨ Features
+
+- 🎨 **Modern UI** - Beautiful, responsive design using Tailwind CSS v4 and shadcn/ui components
+- 🌙 **Dark Mode** - Built-in dark/light/system theme toggle with persistent preferences
+- 🌍 **Multi-language Support** - i18n ready with English, French, and Arabic translations (RTL supported)
+- 📧 **Custom Email Templates** - Styled email templates using jsx-email for all Keycloak events
+- 🔐 **Complete Login Flow** - All 35+ Keycloak login pages fully customized
+- 🎭 **Social Login Providers** - Pre-styled icons for 16+ OAuth providers (Google, GitHub, Microsoft, etc.)
+- 📖 **Storybook Integration** - Visual testing and documentation for all components
+- ⚡ **Vite Powered** - Fast development with HMR and optimized builds
+- 🔧 **Type-Safe** - Full TypeScript support throughout the codebase
+
+---
+
+## 🚀 Quick Start with npm
+
+Get started quickly by using the published npm package in your own project.
+
+### Step 1: Create a new Vite + React + TypeScript project
+
+```bash
+pnpm create vite
+```
+
+When prompted:
+
+- **Project name:** `keycloak-theme` (or your preferred name)
+- **Select a framework:** Choose **React**
+- **Select a variant:** Choose **TypeScript**
+
+```bash
+cd keycloak-theme
+```
+
+### Step 2: Install dependencies
+
+```bash
+pnpm add keycloakify @oussemasahbeni/keycloakify-login-shadcn
+pnpm install
+```
+
+### Step 3: Initialize Keycloakify
+
+```bash
+npx keycloakify init
+```
+
+When prompted:
+
+- **Which theme type would you like to initialize?** Select **(x) login**
+- **Do you want to install the Stories?** Select **(x) Yes (Recommended)**
+
+### Step 4: Configure Vite
+
+Update your `vite.config.ts` to include Tailwind CSS, path aliases, and the Keycloakify plugin:
+
+```typescript
+import react from "@vitejs/plugin-react";
+import { keycloakify } from "keycloakify/vite-plugin";
+import { defineConfig } from "vite";
+import path from "node:path";
+import tailwindcss from "@tailwindcss/vite";
+
+// https://vite.dev/config/
+export default defineConfig({
+    plugins: [
+        react(),
+        tailwindcss(),
+        keycloakify({
+            accountThemeImplementation: "none"
+        })
+    ],
+    resolve: {
+        alias: {
+            "@": path.resolve(__dirname, "./src")
+        }
+    }
+});
+```
+
+### Step 5: Configure TypeScript paths
+
+Add the path alias to your `tsconfig.app.json`:
+
+```json
+{
+    "compilerOptions": {
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    }
+}
+```
+
+### Step 6: Run Storybook and build
+
+```bash
+# Run Storybook for component development and testing
+pnpm storybook
+
+# Build the Keycloak theme JAR file
+pnpm build-keycloak-theme
+```
+
+That's it! You now have a fully functional Keycloak login theme using the published package.
+
+---
+
+## 🛠️ Development (for contributors)
+
+If you want to clone this repository and develop/customize the theme locally:
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm (or npm/yarn)
+- [Maven](https://maven.apache.org/) (for building the theme JAR)
+
+### Clone and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/Oussemasahbeni/keycloakify-shadcn-starter.git
+cd keycloakify-shadcn-starter
+
+# Install dependencies
+pnpm install
+```
+
+### Development Commands
+
+```bash
+# Start development server with hot reload
+pnpm dev
+
+# Run Storybook for component development
+pnpm storybook
+
+# Preview email templates
+pnpm emails:preview
+
+# Build the Keycloak theme JAR
+pnpm build-keycloak-theme
+```
+
+---
+
+## 🖼️ Supported Pages
+
+This theme includes custom implementations for all Keycloak login pages:
+
+| Authentication      | Account Management  | Security              |
+| ------------------- | ------------------- | --------------------- |
+| Login               | Register            | WebAuthn Authenticate |
+| Login with Username | Update Profile      | WebAuthn Register     |
+| Login with Password | Update Email        | Configure TOTP        |
+| Login OTP           | Delete Account      | Recovery Codes        |
+| Login with Passkeys | Logout Confirm      | Reset OTP             |
+| OAuth Grant         | Terms & Conditions  | X509 Info             |
+| Device Verification | Select Organization | Delete Credential     |
+
+---
+
+### Branding
+
+1. **Logo**: Replace `src/login/assets/img/auth-logo.svg` with your company logo
+2. **Colors**: Modify CSS variables in `src/login/index.css`
+3. **Fonts**: Update font imports in `src/login/assets/fonts/`
+
+### Internationalization
+
+Add or modify translations in `src/login/i18n.ts`:
+
+```typescript
+.withCustomTranslations({
+    en: {
+        welcomeMessage: "Welcome to Your App",
+        loginAccountTitle: "Login to your account",
+        // ... more translations
+    },
+    fr: { /* French translations */ },
+    ar: { /* Arabic translations */ }
+})
+```
+
+### UI Components
+
+The theme uses shadcn/ui components located in `src/components/ui/`:
+
+- `alert.tsx` - Alert messages
+- `button.tsx` - Buttons with variants
+- `card.tsx` - Card containers
+- `checkbox.tsx` - Checkbox inputs
+- `input.tsx` - Text inputs
+- `label.tsx` - Form labels
+- `dropdown-menu.tsx` - Dropdown menus
+- `radio-group.tsx` - Radio button groups
+- `tooltip.tsx` - Tooltips
+
+---
+
+## 📧 Email Templates
+
+Custom email templates are built with [jsx-email](https://jsx.email/) and support multiple languages.
+
+### Available Templates
+
+| Template                     | Description                     |
+| ---------------------------- | ------------------------------- |
+| `email-verification.tsx`     | Email verification              |
+| `password-reset.tsx`         | Password reset link             |
+| `executeActions.tsx`         | Required actions                |
+| `identity-provider-link.tsx` | IDP linking                     |
+| `org-invite.tsx`             | Organization invitation         |
+| `event-login_error.tsx`      | Login error notification        |
+| `event-update_password.tsx`  | Password change notification    |
+| `event-update_totp.tsx`      | TOTP configuration notification |
+| And more...                  |                                 |
+
+### Preview Emails Locally
+
+```bash
+pnpm emails:preview
+```
+
+### Email Locales
+
+Translations are in `src/email/locales/{locale}/translation.json`:
+
+- `en/` - English
+- `fr/` - French
+- `ar/` - Arabic
+
+---
+
+## 🔨 Building for Production
+
+### Install Maven
+
+Required for building the Keycloak theme JAR file.
+
+- **macOS**: `brew install maven`
+- **Ubuntu/Debian**: `sudo apt-get install maven`
+- **Windows**: `choco install openjdk && choco install maven`
+
+### Build the Theme
+
+```bash
+pnpm build-keycloak-theme
+```
+
+The built theme will be output as a `.jar` file in the `dist_keycloak/` directory.
+
+### Deploy to Keycloak
+
+1. Copy the `.jar` file to your Keycloak's `providers/` directory
+2. Restart Keycloak
+3. Go to Keycloak Admin Console → **Realm Settings** → **Themes**
+4. Select your custom theme from the dropdown
+
+---
+
+## 🧪 Testing
+
+### Storybook
+
+Run Storybook for visual testing and component documentation:
+
+```bash
+pnpm storybook
+```
+
+### Local Keycloak Testing
+
+For local testing with a Keycloak instance, see the [Keycloakify documentation](https://docs.keycloakify.dev/testing-your-theme).
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License.
+
+---
+
+## 🙏 Acknowledgments
+
+- [Keycloakify](https://keycloakify.dev) - For making Keycloak theming with React possible
+- [shadcn/ui](https://ui.shadcn.com) - For the beautiful UI components
+- [Tailwind CSS](https://tailwindcss.com) - For the utility-first CSS framework
+- [jsx-email](https://jsx.email) - For React email templates
+
+---
+
+## 📦 Package Information
+
+**npm:** [@oussemasahbeni/keycloakify-login-shadcn](https://www.npmjs.com/package/@oussemasahbeni/keycloakify-login-shadcn)  
+**GitHub:** [Oussemasahbeni/keycloakify-shadcn-starter](https://github.com/Oussemasahbeni/keycloakify-shadcn-starter)

package/keycloak-theme/components/ui/alert.tsx

@@ -1,81 +1,89 @@
+import { cn } from "@/components/lib/utils";
 import { cva, type VariantProps } from "class-variance-authority";
 import { AlertTriangle, Info, XCircle } from "lucide-react";
 import * as React from "react";
 import { MdCheckCircle } from "react-icons/md";
 
-import { cn } from "@/components/lib/utils";
-
 const alertVariants = cva(
-    "relative w-full rounded-lg border p-4 text-sm [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg~*]:pl-7",
+    "relative w-full rounded-lg border px-5 py-4 text-sm flex items-center gap-4 transition-all",
     {
         variants: {
             variant: {
                 info: "bg-card text-card-foreground",
-                error: "border-red-200 bg-red-50 text-red-800 dark:border-red-800 dark:bg-red-950/50 dark:text-red-300 [&>svg]:text-red-800 dark:[&>svg]:text-red-300",
-                warning:
-                    "border-amber-200 bg-amber-50 text-amber-800 dark:border-amber-800 dark:bg-amber-950/50 dark:text-amber-300 [&>svg]:text-amber-800 dark:[&>svg]:text-amber-300",
-                success:
-                    "border-green-200 bg-green-50 text-green-800 dark:border-green-800 dark:bg-green-950/50 dark:text-green-300 [&>svg]:text-green-800 dark:[&>svg]:text-green-300"
-            }
+                success: "bg-emerald-50/50 border-emerald-200 text-emerald-900 dark:bg-emerald-500/5 dark:border-emerald-500/20 dark:text-emerald-400",
+                warning: "bg-amber-50/50 border-amber-200 text-amber-900 dark:bg-amber-500/5 dark:border-amber-500/20 dark:text-amber-400",
+                error: "bg-destructive/5 border-destructive/20 text-destructive",
+            },
         },
         defaultVariants: {
-            variant: "info"
-        }
+            variant: "info",
+        },
     }
 );
 
-const Alert = React.forwardRef<
-    HTMLDivElement,
-    React.HTMLAttributes<HTMLDivElement> &
-        VariantProps<typeof alertVariants> & { showIcon?: boolean }
->(({ className, showIcon = true, variant, ...props }, ref) => (
-    <div
-        ref={ref}
-        role="alert"
-        className={cn(alertVariants({ variant }), className)}
-        {...props}
-    >
-        <div className="flex items-start gap-3">
-            {showIcon && (
-                <>
-                    {variant === "info" && <Info className="h-5 w-5 shrink-0" />}
-                    {variant === "error" && <XCircle className="h-5 w-5 shrink-0" />}
-                    {variant === "warning" && (
-                        <AlertTriangle className="h-5 w-5 shrink-0" />
-                    )}
-                    {variant === "success" && (
-                        <MdCheckCircle className="h-5 w-5 shrink-0" />
-                    )}
-                </>
-            )}
-            {props.children}
+interface AlertProps
+    extends React.ComponentProps<"div">,
+    VariantProps<typeof alertVariants> {
+    showIcon?: boolean;
+}
+
+function Alert({
+    className,
+    variant = "info",
+    showIcon = true,
+    children,
+    ...props
+}: AlertProps) {
+    const Icon = {
+        info: Info,
+        error: XCircle,
+        warning: AlertTriangle,
+        success: MdCheckCircle,
+    }[variant as string] || Info;
+
+    return (
+        <div
+            data-slot="alert"
+            role="alert"
+            className={cn(alertVariants({ variant }), className)}
+            {...props}
+        >
+            {showIcon && <Icon className="size-5 shrink-0" data-slot="alert-icon" />}
+            {/* We use a div wrapper for children to ensure Title and Description stack vertically */}
+            <div className="flex flex-col gap-0.5 flex-1">
+                {children}
+            </div>
         </div>
-    </div>
-));
-Alert.displayName = "Alert";
+    );
+}
 
-const AlertTitle = React.forwardRef<
-    HTMLParagraphElement,
-    React.HTMLAttributes<HTMLHeadingElement>
->(({ className, ...props }, ref) => (
-    <h5
-        ref={ref}
-        className={cn("mb-1 font-medium leading-none tracking-tight", className)}
-        {...props}
-    />
-));
-AlertTitle.displayName = "AlertTitle";
+function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="alert-title"
+            className={cn(
+                "font-medium leading-none tracking-tight",
+                className
+            )}
+            {...props}
+        />
+    );
+}
 
-const AlertDescription = React.forwardRef<
-    HTMLParagraphElement,
-    React.HTMLAttributes<HTMLParagraphElement>
->(({ className, ...props }, ref) => (
-    <div
-        ref={ref}
-        className={cn("text-sm [&_p]:leading-relaxed", className)}
-        {...props}
-    />
-));
-AlertDescription.displayName = "AlertDescription";
+function AlertDescription({
+    className,
+    ...props
+}: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="alert-description"
+            className={cn(
+                "text-muted-foreground text-sm [&_p]:leading-relaxed",
+                className
+            )}
+            {...props}
+        />
+    );
+}
 
 export { Alert, AlertDescription, AlertTitle };

package/keycloak-theme/components/ui/button.tsx

@@ -1,56 +1,62 @@
-import { Slot } from "@radix-ui/react-slot";
-import { cva, type VariantProps } from "class-variance-authority";
-import * as React from "react";
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+import * as React from "react"
+import { cn } from '../lib/utils'
 
-import { cn } from "@/components/lib/utils";
 
 const buttonVariants = cva(
-    "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+    "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
     {
         variants: {
             variant: {
-                default: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+                default: "bg-primary text-primary-foreground hover:bg-primary/90",
                 destructive:
-                    "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+                    "bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
                 outline:
-                    "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+                    "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
                 secondary:
-                    "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
-                ghost: "hover:bg-accent hover:text-accent-foreground",
-                link: "text-primary underline-offset-4 hover:underline"
+                    "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+                ghost:
+                    "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+                link: "text-primary underline-offset-4 hover:underline",
             },
             size: {
-                default: "h-9 px-4 py-2",
-                sm: "h-8 rounded-md px-3 text-xs",
-                lg: "h-10 rounded-md px-8",
-                icon: "h-9 w-9"
-            }
+                default: "h-9 px-4 py-2 has-[>svg]:px-3",
+                sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+                lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+                icon: "size-9",
+                "icon-sm": "size-8",
+                "icon-lg": "size-10",
+            },
         },
         defaultVariants: {
             variant: "default",
-            size: "default"
-        }
+            size: "default",
+        },
     }
-);
+)
 
-export interface ButtonProps
-    extends React.ButtonHTMLAttributes<HTMLButtonElement>,
-        VariantProps<typeof buttonVariants> {
-    asChild?: boolean;
-}
+function Button({
+    className,
+    variant = "default",
+    size = "default",
+    asChild = false,
+    ...props
+}: React.ComponentProps<"button"> &
+    VariantProps<typeof buttonVariants> & {
+        asChild?: boolean
+    }) {
+    const Comp = asChild ? Slot : "button"
 
-const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-    ({ className, variant, size, asChild = false, ...props }, ref) => {
-        const Comp = asChild ? Slot : "button";
-        return (
-            <Comp
-                className={cn(buttonVariants({ variant, size, className }))}
-                ref={ref}
-                {...props}
-            />
-        );
-    }
-);
-Button.displayName = "Button";
+    return (
+        <Comp
+            data-slot="button"
+            data-variant={variant}
+            data-size={size}
+            className={cn(buttonVariants({ variant, size, className }))}
+            {...props}
+        />
+    )
+}
 
-export { Button, buttonVariants };
+export { Button, buttonVariants }