central-auth-js-sdk 1.0.12 → 1.0.13

package/INTEGRATION_GUIDE.md

@@ -96,6 +96,7 @@ Call once (e.g. at app load) to set defaults. Returns `{ startSignup, startLogin
 | `loginMethods` | object | — | Default login methods (see Login config) |
 | `frsAsSecondFactor` | boolean | `false` | Default: require face verification after primary auth |
 | `enableFaceRegistration` | boolean | `true` | Whether sign-up includes face registration step |
+| `onBack` | function | — | Default callback when user clicks ← Back on the first screen of signup/login (see [§ 9](#9-returning-to-the-parent-application)) |
 
 **Environments:** The SDK uses only `env` to choose the API base URL:
 
@@ -142,6 +143,7 @@ Starts the **sign-up flow** (email + name → verify → mobile → verify → p
 | `enableFaceRegistration` | boolean | no | Include face registration step (default from init or `true`) |
 | **`onSignupComplete(payload)`** | function | no | Called **once** when signup completes. `payload`: `email`, `mobile`, `userId` + any fields from final API (e.g. `access_token`, `refresh_token`). |
 | **`onContinue()`** | function | no | Called when user clicks **Continue to application** on the success screen. Use to unmount and redirect. |
+| **`onBack()`** | function | no | Called when user clicks **← Back** on the **first screen** of signup. Use to unmount the SDK and return to your app. See [§ 9](#9-returning-to-the-parent-application). |
 | **`onSwitchToLogin()`** | function | no | Called when user clicks **Sign in** (e.g. “Already have an account? Sign in”). Use to unmount signup and start the login flow in the **same container** (e.g. login + FRS). |
 
 **Returns:** `{ unmount, getState, getFlow, getCurrentStep }` or `null` if container is invalid.
@@ -163,6 +165,10 @@ const instance = startSignup({
     instance.unmount();
     redirectToDashboard();
   },
+  onBack() {
+    instance.unmount();
+    showYourAppScreen();
+  },
   onSwitchToLogin() {
     instance.unmount();
     startLogin({ container: '#auth-container', env: 'dev', appIdentifier: 'my-app', loginMethods: { emailFrs: true }, onContinue: goToApp, onSignUp: showSignup });
@@ -266,6 +272,7 @@ Starts the **login flow**. If the parent enables **only one** login method, the
 | **`onSignUp()`** | function | no | Called when user clicks **Sign up** on the login screen (e.g. unmount login and start signup in the **same container**). |
 | **`onLoginComplete(payload)`** | function | no | Called **once** when login completes. `payload`: `identifier` + any fields from final API (e.g. `access_token`, `refresh_token`). |
 | **`onContinue()`** | function | no | Called when user clicks **Continue to application** on the success screen. |
+| **`onBack()`** | function | no | Called when user clicks **← Back** on the **first screen** of login. Use to unmount the SDK and return to your app. See [§ 9](#9-returning-to-the-parent-application). |
 
 **Login methods** (`loginMethods`):
 
@@ -298,6 +305,10 @@ startLogin({
     instance.unmount();
     redirectToApp();
   },
+  onBack() {
+    instance.unmount();
+    redirectToApp();
+  },
   onSignUp() {
     instance.unmount();
     startSignup({ container: '#auth-container', env: 'dev', appIdentifier: '...', onContinue: goToApp, onSwitchToLogin: showLoginFrs });
@@ -321,6 +332,7 @@ startLogin({
   frsAsSecondFactor: true,
   onLoginComplete(payload) { /* ... */ },
   onContinue() { /* ... */ },
+  onBack() { /* unmount + return to parent app */ },
   onSignUp() { /* ... */ },
 });
 ```
@@ -372,16 +384,79 @@ You can also read **`instance.getState()`** after the flow completes; it include
 
 ## 9. Returning to the parent application
 
-When the user clicks **Continue to application** on the success screen, the SDK calls **`onContinue()`** if you provided it. Use it to unmount the SDK and show your app (e.g. redirect or switch view):
+The SDK does **not** automatically navigate your app when the user leaves auth. Your parent app is responsible for showing/hiding the auth container and routing the user back to your own UI. Use the callbacks below.
+
+### Two kinds of “Back”
+
+| Where | What happens |
+|-------|----------------|
+| **First screen** (signup email entry, login method picker, or single-method identifier screen) | **← Back** calls **`onBack()`** — intended to leave auth and return to your app |
+| **Later steps** (password, OTP, face capture, etc.) | **← Back** goes to the **previous step inside the SDK** only. Does **not** call `onBack()` |
+
+The first-screen back button is always shown. What happens when it is clicked depends on whether you pass **`onBack`**.
+
+### If you omit `onBack`
+
+The SDK uses a **default**: it unmounts itself (removes its UI from the container and cleans up theme). It does **not** show your app’s main screen, change routes, or hide overlays — you must do that yourself if needed.
+
+### What the parent app should do (recommended)
+
+Define one helper (e.g. `returnToApp`) and pass it to **`onBack`** and usually **`onContinue`** as well:
+
+```javascript
+let authInstance = null;
+
+function returnToApp() {
+  if (authInstance) authInstance.unmount();
+  authInstance = null;
+  document.getElementById('auth-container').style.display = 'none';
+  document.getElementById('app-root').style.display = 'block';
+  // or: router.push('/'); window.history.back(); etc.
+}
+
+authInstance = startLogin({
+  container: '#auth-container',
+  env: 'dev',
+  loginMethods: { emailPassword: true },
+  onBack: returnToApp,
+  onContinue: returnToApp,
+  onLoginComplete(payload) {
+    saveToken(payload.access_token);
+    returnToApp();
+  },
+});
+```
+
+**Typical steps inside `returnToApp` (or equivalent):**
+
+1. Call **`instance.unmount()`** — removes SDK DOM and theme
+2. Clear your reference to the instance (`authInstance = null`)
+3. Hide the auth container and show your main app UI (or navigate with your router)
+
+You can set **`onBack`** once in **`initializeAuth({ onBack: returnToApp, ... })`** and reuse it in `startSignup` / `startLogin` (per-call config overrides defaults).
+
+### Success screen — `onContinue()`
+
+When the user clicks **Continue to application** on the success screen, the SDK calls **`onContinue()`** if you provided it. Use the same pattern as **`onBack`**: unmount the SDK and show your app:
 
 ```javascript
 onContinue() {
   instance.unmount();
   window.location.href = '/dashboard';
-  // or: showYourAppView();
+  // or: returnToApp();
 }
 ```
 
+### Summary
+
+| Callback | When it fires | Parent app action |
+|----------|---------------|-------------------|
+| **`onBack()`** | User clicks ← Back on **first screen** | Unmount SDK + return to your app UI |
+| **`onContinue()`** | User clicks Continue on **success screen** | Unmount SDK + enter your app (often same as `onBack`) |
+| *(none)* | First-screen back, if `onBack` omitted | SDK unmounts only; parent UI unchanged |
+
+Returning to the parent app is **not automatic** beyond SDK unmount. Integrators should pass **`onBack`** (and **`onContinue`**) to fully control navigation in their application.
+
 ---
 
 ## 10. Full integration example
@@ -421,6 +496,7 @@ function showSignup() {
       goToApp();
     },
     onContinue: goToApp,
+    onBack: goToApp,
     onSwitchToLogin: showLoginFrs,
   });
 }
@@ -435,6 +511,7 @@ function showLoginFrs() {
       goToApp();
     },
     onContinue: goToApp,
+    onBack: goToApp,
     onSignUp: showSignup,
   });
 }
@@ -449,6 +526,7 @@ function showLogin(loginMethods = { emailPassword: true }) {
       goToApp();
     },
     onContinue: goToApp,
+    onBack: goToApp,
     onSignUp: showSignup,
   });
 }

package/login.js

@@ -208,6 +208,7 @@ export function mountLogin(container, options = {}) {
     const identifier = state.get('identifier');
     let apiResult = null;
 
+    layout.setLoading(true, 'Verifying your face…');
     try {
       if (method === LOGIN_METHODS.EMAIL_FRS) {
         apiResult = await api.loginEmailFr(identifier, file, null, config.appIdentifier);
@@ -230,6 +231,8 @@ export function mountLogin(container, options = {}) {
       const msg = err?.data?.error || err?.message || 'Verification failed';
       state.set('error', msg);
       showError(msg);
+    } finally {
+      layout.setLoading(false);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "central-auth-js-sdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Vanilla JS sign-up and login flow SDK — embeddable auth UI with configurable methods",
   "type": "module",
   "main": "index.js",

package/signup.js

@@ -229,6 +229,7 @@ export function mount(container, options = {}) {
       showError('Please capture your face first.');
       return;
     }
+    layout.setLoading(true, 'Registering your face…');
     try {
       let apiResult = null;
       if (isSocial()) {
@@ -253,6 +254,8 @@ export function mount(container, options = {}) {
       const msg = err?.data?.error || err?.message || 'Face registration failed';
       state.set('error', msg);
       showError(msg);
+    } finally {
+      layout.setLoading(false);
     }
   }
 

package/styles.css

@@ -300,6 +300,67 @@
   display: none;
 }
 
+/* ============================= LOADING BAR ============================= */
+
+.wf-loading-bar {
+  height: 3px;
+  margin: -0.25rem 0 1rem;
+  border-radius: 999px;
+  background: var(--wf-muted-bg, rgba(0, 0, 0, 0.06));
+  overflow: hidden;
+}
+
+.wf-loading-bar.hidden {
+  display: none;
+}
+
+.wf-loading-bar-indeterminate {
+  height: 100%;
+  width: 40%;
+  border-radius: 999px;
+  background: linear-gradient(90deg, var(--wf-primary-grad-start) 0%, var(--wf-primary) 50%, var(--wf-primary-grad-end) 100%);
+  animation: wf-loading-slide 1.2s ease-in-out infinite;
+}
+
+@keyframes wf-loading-slide {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(350%); }
+}
+
+.wf-loading-status {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  margin-bottom: 1rem;
+  padding: 0.5rem 0.75rem;
+  border-radius: var(--wf-radius);
+  background: var(--wf-muted-bg, rgba(0, 0, 0, 0.04));
+  color: var(--wf-fg-soft);
+  font-size: 0.8125rem;
+  font-weight: 500;
+}
+
+.wf-loading-status.hidden {
+  display: none;
+}
+
+.wf-loading-status::before {
+  content: '';
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid var(--wf-border);
+  border-top-color: var(--wf-primary);
+  border-radius: 50%;
+  animation: wf-spin 0.7s linear infinite;
+  flex-shrink: 0;
+}
+
+#wf-form-inner.wf-loading-active {
+  pointer-events: none;
+  opacity: 0.65;
+}
+
 /* ============================= PAGE FOOTER ============================= */
 
 .wf-page-footer {

package/ui/layout.js

@@ -45,6 +45,10 @@ export function createLayout(container) {
           </div>
         </div>
         <div class="wf-card-body">
+          <div class="wf-loading-bar hidden" id="wf-loading-bar" role="progressbar" aria-busy="false" aria-label="Loading">
+            <div class="wf-loading-bar-indeterminate"></div>
+          </div>
+          <div class="wf-loading-status hidden" id="wf-loading-status"></div>
           <div class="wf-error-banner hidden" id="wf-error-banner" role="alert"></div>
           <div id="wf-form-inner"></div>
         </div>
@@ -60,6 +64,8 @@ export function createLayout(container) {
   const ringNum = root.querySelector('#wf-ring-num');
   const ring = root.querySelector('.wf-ring');
   const errorBanner = root.querySelector('#wf-error-banner');
+  const loadingBar = root.querySelector('#wf-loading-bar');
+  const loadingStatus = root.querySelector('#wf-loading-status');
 
   function setContent(el) {
     formInner.innerHTML = '';
@@ -90,11 +96,33 @@ export function createLayout(container) {
     errorBanner.classList.remove('hidden');
   }
 
+  function setLoading(active, message = '') {
+    if (active) {
+      loadingBar.classList.remove('hidden');
+      loadingBar.setAttribute('aria-busy', 'true');
+      formInner.classList.add('wf-loading-active');
+      if (message) {
+        loadingStatus.textContent = message;
+        loadingStatus.classList.remove('hidden');
+      } else {
+        loadingStatus.textContent = '';
+        loadingStatus.classList.add('hidden');
+      }
+    } else {
+      loadingBar.classList.add('hidden');
+      loadingBar.setAttribute('aria-busy', 'false');
+      formInner.classList.remove('wf-loading-active');
+      loadingStatus.classList.add('hidden');
+      loadingStatus.textContent = '';
+    }
+  }
+
   return {
     root,
     setContent,
     updateProgress,
     showError,
+    setLoading,
     renderContent: setContent,
   };
 }