@djangocfg/layouts 2.1.334 → 2.1.336

package/src/layouts/AuthLayout/README.md

@@ -1,11 +1,15 @@
 # AuthLayout
 
-Apple HIG-style authentication layout with animated mesh gradient background.
+Shell-based authentication layout with two visual variants:
+- `centered` (default) — Apple HIG-style, frameless, centered, glow background
+- `split` — Two-column on desktop (form + sidebar), single-column on mobile
 
 Supports: email OTP, phone OTP, GitHub OAuth, 2FA (TOTP + backup codes).
 
 ## Usage
 
+### Centered variant (default)
+
 ```tsx
 import { AuthLayout } from '@djangocfg/layouts';
 
@@ -24,10 +28,41 @@ import { AuthLayout } from '@djangocfg/layouts';
 </AuthLayout>
 ```
 
+### Split variant (two-column)
+
+```tsx
+import { AuthLayout } from '@djangocfg/layouts';
+
+<AuthLayout
+  variant="split"
+  sourceUrl="https://myapp.com"
+  background={{
+    imageUrl: '/assets/signup-bg.jpg',
+    overlay: 'hsl(var(--background) / 0.6)',
+    blur: '8px',
+  }}
+  sidebar={
+    <div>
+      <blockquote>"Amazing product!"</blockquote>
+      <cite>— Jane Doe, CEO</cite>
+    </div>
+  }
+>
+  {/* Optional: custom header */}
+  <div>
+    <h1>Get started</h1>
+    <p>Already have an account? <a href="/login">Login</a></p>
+  </div>
+</AuthLayout>
+```
+
 ## Props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `variant` | `'centered' \| 'split'` | `'centered'` | Shell layout variant |
+| `background` | `AuthBackgroundConfig` | — | Background image/gradient/overlay/blur |
+| `sidebar` | `ReactNode` | — | Right column content (split variant only) |
 | `sourceUrl` | `string` | — | App URL for analytics/tracking |
 | `redirectUrl` | `string` | `/dashboard` | Where to redirect after auth |
 | `enableGithubAuth` | `boolean` | `false` | Show GitHub OAuth button |
@@ -40,6 +75,15 @@ import { AuthLayout } from '@djangocfg/layouts';
 | `className` | `string` | — | Extra class on root element |
 | `children` | `ReactNode` | — | Custom header (identifier step only) |
 
+### AuthBackgroundConfig
+
+| Prop | Type | Description |
+|---|---|---|
+| `imageUrl` | `string` | Background image URL (loaded via `useImageLoader`) |
+| `gradient` | `string` | CSS gradient fallback |
+| `overlay` | `string` | Overlay color with opacity |
+| `blur` | `string` | Backdrop blur amount (default: `8px`) |
+
 ## Callbacks
 
 ```tsx
@@ -63,9 +107,31 @@ import { AuthLayout } from '@djangocfg/layouts';
 
 `children` (custom header) are only rendered on the `identifier` step — hidden on all others.
 
-## Background
+## Architecture
+
+AuthLayout is built on a **shell pattern** (inspired by PublicLayout's navbar/footer slots):
+
+```
+AuthLayout/
+├── shells/
+│   ├── AuthShell.tsx      — Orchestrator: loads bg image, dispatches variant
+│   ├── CenteredShell.tsx  — Apple-style frameless layout
+│   ├── SplitShell.tsx     — Two-column card layout
+│   ├── context.tsx        — Shell context (variant, hasSidebar)
+│   └── types.ts           — AuthShellVariant, AuthBackgroundConfig
+├── components/steps/      — Auth step components (IdentifierStep, OTPStep, ...)
+├── components/shared/     — Reusable UI primitives (AuthButton, AuthHeader, ...)
+├── styles/
+│   ├── auth.css           — Shared form/button/input styles
+│   ├── centered-shell.css — Centered variant layout
+│   └── split-shell.css    — Split variant layout
+```
 
-The animated mesh gradient background (`GlowBackground`) is always rendered. It uses `position: absolute inset-0` inside the layout container and works on both light and dark themes.
+Adding a new variant:
+1. Add variant name to `AuthShellVariant` in `shells/types.ts`
+2. Create `<NewShell>.tsx` in `shells/`
+3. Add CSS in `styles/new-shell.css`
+4. Wire it up in `AuthShell.tsx`
 
 ## Context
 
@@ -76,3 +142,11 @@ import { useAuthFormContext } from '@djangocfg/layouts';
 
 const { step, identifier, isLoading } = useAuthFormContext();
 ```
+
+Shell metadata is available via `useAuthShell()`:
+
+```tsx
+import { useAuthShell } from '@djangocfg/layouts';
+
+const { variant, hasSidebar } = useAuthShell();
+```

package/src/layouts/AuthLayout/index.ts

@@ -8,6 +8,14 @@ export { AuthLayout, useAuthLayoutContext } from './AuthLayout';
 // Context and hooks
 export { AuthFormProvider, useAuthFormContext } from './context';
 
+// Shells
+export {
+  AuthShell,
+  AuthShellProvider,
+  useAuthShell,
+  useAuthShellOptional,
+} from './shells';
+
 // Step components
 export {
   IdentifierStep,
@@ -34,4 +42,8 @@ export type {
   AuthFormContextType,
   AuthLayoutProps,
   AuthHelpProps,
+  // Shell types
+  AuthShellVariant,
+  AuthBackgroundConfig,
+  AuthShellContextValue,
 } from './types';

package/src/layouts/AuthLayout/shells/AuthShell.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import React, { useMemo } from 'react';
+
+import { useImageLoader } from '@djangocfg/ui-core/hooks';
+
+import { AuthShellProvider } from './context';
+import { CenteredShell } from './CenteredShell';
+import { SplitShell } from './SplitShell';
+import type { AuthShellProps } from './types';
+
+/**
+ * AuthShell — shared orchestrator for auth layout variants.
+ *
+ * Handles common concerns:
+ *  - background image loading (via useImageLoader)
+ *  - shell context registration
+ *  - variant dispatch (centered | split)
+ *
+ * Variants own their own chrome (positioning, shape, background).
+ */
+export const AuthShell: React.FC<AuthShellProps> = ({
+  variant,
+  children,
+  background,
+  sidebar,
+  className,
+}) => {
+  const { isLoaded: bgLoaded, hasError: bgError } = useImageLoader(background?.imageUrl);
+
+  const hasBgImage = Boolean(background?.imageUrl) && bgLoaded && !bgError;
+
+  const bgStyle = useMemo(() => {
+    if (hasBgImage && background?.imageUrl) {
+      return {
+        backgroundImage: `url(${background.imageUrl})`,
+        backgroundSize: 'cover',
+        backgroundPosition: 'center',
+        backgroundRepeat: 'no-repeat',
+      } as React.CSSProperties;
+    }
+    if (background?.gradient) {
+      return { background: background.gradient } as React.CSSProperties;
+    }
+    return undefined;
+  }, [hasBgImage, background]);
+
+  const overlayStyle = useMemo(() => {
+    if (!background?.overlay) return undefined;
+    return { background: background.overlay } as React.CSSProperties;
+  }, [background?.overlay]);
+
+  const blurValue = background?.blur ?? '8px';
+
+  const shellContext = useMemo(
+    () => ({
+      variant,
+      hasSidebar: Boolean(sidebar),
+    }),
+    [variant, sidebar]
+  );
+
+  const commonShellProps = {
+    children,
+    className,
+    bgStyle,
+    overlayStyle,
+    blurValue,
+  };
+
+  return (
+    <AuthShellProvider value={shellContext}>
+      {variant === 'split' ? (
+        <SplitShell {...commonShellProps} sidebar={sidebar} />
+      ) : (
+        <CenteredShell {...commonShellProps} />
+      )}
+    </AuthShellProvider>
+  );
+};

package/src/layouts/AuthLayout/shells/CenteredShell.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import React from 'react';
+
+import { GlowBackground } from '@djangocfg/ui-core/components';
+
+import type { ShellRenderProps } from './types';
+
+/**
+ * CenteredShell — Apple-style frameless auth layout.
+ *
+ * Features:
+ * - Full viewport centering
+ * - Glow background (default)
+ * - Optional custom background image/gradient via shell props
+ * - No visible card chrome
+ */
+export const CenteredShell: React.FC<ShellRenderProps> = ({
+  children,
+  className,
+  bgStyle,
+  overlayStyle,
+}) => {
+  const hasCustomBg = Boolean(bgStyle);
+
+  return (
+    <div className={`auth-shell-centered ${className || ''}`}>
+      {/* Background layer */}
+      {hasCustomBg ? (
+        <>
+          <div className="auth-shell-centered__bg" style={bgStyle} />
+          {overlayStyle && (
+            <div className="auth-shell-centered__overlay" style={overlayStyle} />
+          )}
+        </>
+      ) : (
+        <GlowBackground />
+      )}
+
+      {/* Content */}
+      <div className="auth-shell-centered__content">
+        {children}
+      </div>
+    </div>
+  );
+};

package/src/layouts/AuthLayout/shells/SplitShell.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import React from 'react';
+
+import type { ShellRenderProps } from './types';
+
+interface SplitShellProps extends ShellRenderProps {
+  sidebar?: React.ReactNode;
+}
+
+/**
+ * SplitShell — Two-column auth layout (desktop) / single-column (mobile).
+ *
+ * Layout:
+ * - Mobile (< xl): single column, centered form, optional background
+ * - Desktop (>= xl): two columns inside a card — form left, sidebar right
+ *
+ * Background: full-bleed image/gradient with optional overlay + blur.
+ */
+export const SplitShell: React.FC<SplitShellProps> = ({
+  children,
+  className,
+  bgStyle,
+  overlayStyle,
+  blurValue,
+  sidebar,
+}) => {
+  return (
+    <div className={`auth-shell-split ${className || ''}`}>
+      {/* Background layer */}
+      {bgStyle && (
+        <div className="auth-shell-split__bg" style={bgStyle} />
+      )}
+      {overlayStyle && (
+        <div
+          className="auth-shell-split__overlay"
+          style={{
+            ...overlayStyle,
+            backdropFilter: `blur(${blurValue})`,
+            WebkitBackdropFilter: `blur(${blurValue})`,
+          }}
+        />
+      )}
+
+      {/* Card container */}
+      <div className="auth-shell-split__card">
+        {/* Left: form */}
+        <div className="auth-shell-split__form">
+          <div className="auth-shell-split__form-inner">
+            {children}
+          </div>
+        </div>
+
+        {/* Right: sidebar (desktop only) */}
+        {sidebar && (
+          <div className="auth-shell-split__sidebar">
+            {sidebar}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/layouts/AuthLayout/shells/context.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import React, { createContext, useContext } from 'react';
+
+import type { AuthShellContextValue } from './types';
+
+const AuthShellContext = createContext<AuthShellContextValue | undefined>(undefined);
+
+export const AuthShellProvider: React.FC<{
+  value: AuthShellContextValue;
+  children: React.ReactNode;
+}> = ({ value, children }) => (
+  <AuthShellContext.Provider value={value}>{children}</AuthShellContext.Provider>
+);
+
+export const useAuthShell = (): AuthShellContextValue => {
+  const ctx = useContext(AuthShellContext);
+  if (!ctx) {
+    throw new Error('useAuthShell must be used within an AuthShellProvider');
+  }
+  return ctx;
+};
+
+export const useAuthShellOptional = (): AuthShellContextValue | undefined =>
+  useContext(AuthShellContext);

package/src/layouts/AuthLayout/shells/index.ts

@@ -0,0 +1,9 @@
+export { AuthShell } from './AuthShell';
+export { AuthShellProvider, useAuthShell, useAuthShellOptional } from './context';
+
+export type {
+  AuthShellVariant,
+  AuthBackgroundConfig,
+  AuthShellProps,
+  AuthShellContextValue,
+} from './types';

package/src/layouts/AuthLayout/shells/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Auth Shell Types
+ *
+ * UI-specific configuration for auth layout shells.
+ * Auth logic types live in ../types.ts (re-exported from @djangocfg/api/auth).
+ */
+
+import type { CSSProperties, ReactNode } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shell Variants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * - `centered` — Apple-style frameless, centered, glow background (default).
+ * - `split`    — Two-column: form left, sidebar right on desktop;
+ *                single-column centered on mobile.
+ */
+export type AuthShellVariant = 'centered' | 'split';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Background Configuration
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthBackgroundConfig {
+  /** Background image URL (loaded via useImageLoader). */
+  imageUrl?: string;
+  /** CSS gradient fallback when no image or image fails to load. */
+  gradient?: string;
+  /** Overlay color with opacity (e.g. `hsl(var(--background) / 0.6)`). */
+  overlay?: string;
+  /** Backdrop blur amount (e.g. `8px`). */
+  blur?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shell Props
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthShellProps {
+  variant: AuthShellVariant;
+  children: ReactNode;
+  /** Background configuration — image, gradient, overlay, blur. */
+  background?: AuthBackgroundConfig;
+  /** Slot for the right column in split variant (testimonial, branding, etc.). */
+  sidebar?: ReactNode;
+  className?: string;
+}
+
+/** Internal props passed from AuthShell orchestrator to variant shells. */
+export interface ShellRenderProps {
+  children: ReactNode;
+  className?: string;
+  bgStyle?: CSSProperties;
+  overlayStyle?: CSSProperties;
+  blurValue?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shell Context
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthShellContextValue {
+  variant: AuthShellVariant;
+  /** True when sidebar slot is provided (split variant only). */
+  hasSidebar: boolean;
+}

package/src/layouts/AuthLayout/styles/auth.css

@@ -1,9 +1,8 @@
 /**
- * Auth Layout Styles — Apple HIG
+ * Auth Base Styles
  *
- * Frameless, centered layout. No visible card/border.
- * Uses system-level typography and spacing rhythm.
- * Design tokens from @djangocfg/ui-core.
+ * Shared across all shell variants: forms, buttons, inputs, OTP, errors, etc.
+ * Shell-specific layout styles live in centered-shell.css and split-shell.css.
  */
 
 /* ===== SPRING EASINGS ===== */
@@ -17,35 +16,7 @@
   --auth-radius-xs: 0.375rem;
 }
 
-/* ===== LAYOUT ===== */
-
-.auth-layout {
-  position: relative;
-  min-height: 100vh;
-  min-height: 100dvh;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  /* Responsive padding: 24px on mobile → 40px on desktop */
-  padding: 1.5rem clamp(1.5rem, 5vw, 2.5rem);
-  padding-bottom: max(1.5rem, env(safe-area-inset-bottom, 1rem));
-}
-
-/* Glow layer override — force z-index 0 behind auth content */
-.auth-glow-layer {
-  z-index: 0;
-  pointer-events: none;
-}
-
-/* All direct auth content sits above the glow */
-.auth-layout > *:not(.auth-glow-layer) {
-  position: relative;
-  z-index: 1;
-}
-
 /* ===== CONTAINER ===== */
-/* Apple HIG: No card chrome on auth screens — frameless, content-first */
 
 .auth-container {
   width: 100%;
@@ -85,7 +56,7 @@
   height: 56px;
   margin-bottom: 0.75rem;
   object-fit: contain;
-  border-radius: 14px; /* iOS app icon radius */
+  border-radius: 14px;
   animation: authLogoIn 0.5s var(--spring-bounce) both;
 }
 
@@ -402,7 +373,6 @@
 }
 
 /* ===== CHANNEL TOGGLE ===== */
-/* Apple HIG segmented control */
 
 .auth-channel-toggle {
   display: flex;
@@ -467,7 +437,6 @@
   width: 100%;
 }
 
-
 .auth-otp-wrapper input {
   width: 3rem;
   height: 3.5rem;
@@ -509,7 +478,6 @@
   box-shadow: 0 2px 12px hsl(0 0% 0% / 0.1);
 }
 
-/* Collapsible with centered trigger (e.g. "Can't scan? Enter manually") */
 .auth-collapsible-centered {
   display: flex;
   flex-direction: column;
@@ -628,7 +596,6 @@
 }
 
 /* ===== 2FA BOX ===== */
-/* Visual differentiation for the two-factor step */
 
 .auth-2fa-box {
   padding: 1.5rem 1.25rem 1.25rem;
@@ -661,7 +628,6 @@
   height: 1.375rem;
 }
 
-/* Actions row inside 2fa box — allow wrapping on very narrow screens */
 .auth-2fa-box .auth-actions {
   flex-wrap: wrap;
   row-gap: 0.625rem;
@@ -698,10 +664,6 @@
 /* ===== RESPONSIVE ===== */
 
 @media (max-width: 480px) {
-  .auth-layout {
-    overflow-y: auto;
-  }
-
   .auth-title {
     font-size: 1.375rem;
   }

package/src/layouts/AuthLayout/styles/centered-shell.css

@@ -0,0 +1,57 @@
+/**
+ * Centered Shell Styles
+ *
+ * Apple-style frameless layout: full viewport centering, glow background.
+ * The auth form floats in the center with no visible card chrome.
+ */
+
+.auth-shell-centered {
+  position: relative;
+  min-height: 100vh;
+  min-height: 100dvh;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  /* Responsive padding: 24px mobile → 40px desktop */
+  padding: 1.5rem clamp(1.5rem, 5vw, 2.5rem);
+  padding-bottom: max(1.5rem, env(safe-area-inset-bottom, 1rem));
+}
+
+/* Background layers */
+.auth-shell-centered__bg {
+  position: fixed;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+}
+
+.auth-shell-centered__overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+}
+
+/* Glow layer override — force z-index 0 behind auth content */
+.auth-glow-layer {
+  z-index: 0;
+  pointer-events: none;
+}
+
+/* Content sits above background */
+.auth-shell-centered__content {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+/* Mobile overflow handling */
+@media (max-width: 480px) {
+  .auth-shell-centered {
+    overflow-y: auto;
+  }
+}

package/src/layouts/AuthLayout/styles/split-shell.css

@@ -0,0 +1,101 @@
+/**
+ * Split Shell Styles
+ *
+ * Two-column auth layout (desktop) / single-column (mobile).
+ * Desktop: card with form left, sidebar right.
+ * Mobile: centered form, sidebar hidden.
+ */
+
+.auth-shell-split {
+  position: relative;
+  min-height: 100vh;
+  min-height: 100dvh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+}
+
+/* Background layers */
+.auth-shell-split__bg {
+  position: fixed;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+}
+
+.auth-shell-split__overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+}
+
+/* Card container */
+.auth-shell-split__card {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  width: 100%;
+  max-width: 420px;
+  background: hsl(var(--background));
+  border-radius: var(--auth-radius);
+  outline: 1px solid hsl(var(--border));
+  box-shadow: 0 4px 24px hsl(0 0% 0% / 0.08);
+  overflow: hidden;
+}
+
+/* Form column */
+.auth-shell-split__form {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2rem 1.5rem;
+}
+
+.auth-shell-split__form-inner {
+  width: 100%;
+  max-width: 360px;
+}
+
+/* Sidebar column — hidden by default (mobile) */
+.auth-shell-split__sidebar {
+  display: none;
+  flex: 1;
+  flex-direction: column;
+  justify-content: center;
+  padding: 2.5rem 2rem;
+  background: hsl(var(--muted) / 0.25);
+}
+
+/* Desktop: show sidebar, expand card */
+@media (min-width: 1280px) {
+  .auth-shell-split__card {
+    max-width: 960px;
+  }
+
+  .auth-shell-split__form {
+    padding: 2.5rem;
+  }
+
+  .auth-shell-split__sidebar {
+    display: flex;
+  }
+}
+
+/* Reduced padding on smaller tablets */
+@media (min-width: 1024px) and (max-width: 1279px) {
+  .auth-shell-split__card {
+    max-width: 880px;
+  }
+
+  .auth-shell-split__form {
+    padding: 2rem;
+  }
+
+  .auth-shell-split__sidebar {
+    display: flex;
+    padding: 2rem 1.5rem;
+  }
+}