ab-ecosystem-sso 0.1.18 → 0.1.19

package/README.md

@@ -4,6 +4,7 @@ Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service**
 
 - ⚛️ React 18 / 19, shipped as ESM + CJS with full TypeScript types.
 - 🎨 Self-contained, theme-aware CSS that **won't leak into or be overridden by** your app.
+- 🌗 Built-in **light and dark mode** — per component, via a single `mode` prop.
 - 🔌 Use it declaratively (`<AccountSettings />`) or imperatively (`openAccountSettings()`).
 - 🧩 Every network call also available as a plain function for custom UIs.
 
@@ -21,6 +22,7 @@ Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service**
 - [Fetching user data](#fetching-user-data) — `getUserProfile` · `getUserWallet` · `getUserCreditWallet` · `getUserSubscription`
 - [Two-factor setup](#two-factor-setup)
 - [Hooks](#hooks)
+- [Light & dark mode](#light--dark-mode)
 - [Theming](#theming)
 - [API reference](#api-reference)
 - [TypeScript](#typescript)
@@ -84,6 +86,8 @@ function LoginPage() {
 }
 ```
 
+The password field has a **show/hide (eye) toggle** — it always starts masked, and the same control appears on `Signup`, the `ForgotPassword` reset step, and the Account Settings change-password modal.
+
 `Login` first fetches the project's `auth-config` (captcha provider/site-key, branding, which links to show) and renders accordingly. If the account has **2FA** enabled it automatically shows a **segmented 6-digit OTP** step (with captcha when the project requires it), and only calls `onSuccess` after verification succeeds.
 
 **Magic-link sign-in** works automatically: point your magic link at `/login#<access_token>` (a bare `/login#access_token=<token>` is also accepted). On mount, `Login` reads the token from the URL hash, validates it with a `/me` call, and — if valid — strips it from the URL and fires `onSuccess({ token, user })`, exactly like a password sign-in. While it validates, a loading state shows; if the token is invalid or expired, it falls back to the normal sign-in form with a short notice (and calls `onError`). No extra wiring needed beyond routing the link to your login page.
@@ -177,6 +181,7 @@ On success it calls `onVerified` (send the user to login) and shows a **Continue
 | `onSuccess` | `({ token, user }) => void` | On successful auth. |
 | `onError` | `(error: Error) => void` | On failure. |
 | `classNames` | `AuthClassNames` | Per-element class overrides: `card`, `input`, `label`, `button`, `link`, `captcha`, `error`, … |
+| `mode` | `"light" \| "dark"` | Colour scheme. Default `"light"`. See [Light & dark mode](#light--dark-mode). |
 
 Per-screen extras: `Login` adds `onForgotPassword` / `onSignupClick`; `Signup` adds `onLoginClick` / `countries`; `ForgotPassword` adds `onBackToLogin` / `resetToken` / `onResetSuccess`; `VerifyEmail` adds `token` / `onVerified` / `onLoginClick` / `onSignupClick` (and has no `onSuccess`, since no session is created).
 
@@ -271,8 +276,10 @@ const [open, setOpen] = useState(false);
 | `token` | `string` | Bearer token. |
 | `apiBaseUrl` | `string` | Optional API origin. |
 | `initialSection` | `"general" \| "account" \| "wallet" \| "plans" \| "credits"` | First section shown. Default `"general"`. |
+| `customComponents` | `AccountSettingsCustomPanel[]` | Add your own panels to the modal. See [Custom panels](#custom-panels). |
 | `syncUrlHash` | `boolean` | Mirror open state + active section in the URL hash. Default `true`. See [URL hash & refresh](#url-hash--refresh). |
 | `title` | `string` | Modal heading. Default `"Settings"`. |
+| `mode` | `"light" \| "dark"` | Colour scheme. Default `"light"`. See [Light & dark mode](#light--dark-mode). |
 | `data` | `Partial<AccountSettingsData>` | Override sample data (non-API mode / previews). |
 | `onLogout` | `() => void` | Sign-out action (closes the modal, then runs this). |
 | `onSaveProfile` | `(profile) => void` | Fires alongside the profile save. |
@@ -282,6 +289,45 @@ const [open, setOpen] = useState(false);
 
 > In live mode the modal performs the API calls itself (save profile, change password, subscribe, recharge, etc.); the callbacks are observation hooks, not required wiring.
 
+### Custom panels
+
+Add your own screens to the modal via `customComponents` — an array of `AccountSettingsCustomPanel`. Each entry renders a **trigger** (in the sidebar, pinned to the sidebar bottom, or in the header next to the close button) and shows its `component` in the modal body when activated.
+
+```tsx
+<AccountSettings
+  open={open}
+  onOpenChange={setOpen}
+  projectId="your-project-id"
+  token={token}
+  customComponents={[
+    {
+      id: "referrals",
+      location: "sidebar",            // "sidebar" | "sidebar-bottom" | "header"
+      label: "Referrals",
+      icon: <GiftIcon />,             // any node (an inline SVG works best)
+      component: <ReferralsPanel />,  // rendered in the modal body
+    },
+    {
+      id: "help",
+      location: "header",
+      label: "Help",
+      icon: <HelpIcon />,
+      component: <HelpCenter />,
+    },
+  ]}
+/>
+```
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | `string` | **Required**, unique. Tracks which panel is active. |
+| `location` | `"sidebar" \| "sidebar-bottom" \| "header"` | Where the trigger appears. Default `"sidebar"`. |
+| `label` | `string` | Sidebar text; header button tooltip + `aria-label`. |
+| `icon` | `ReactNode` | Optional trigger icon. |
+| `component` | `ReactNode` | Rendered in the body when the panel is active. |
+
+The same `customComponents` array works with the imperative `openAccountSettings({ customComponents: [...] })`. Panels are host-owned — they don't affect the URL hash, and activating one doesn't run the built-in section's API calls.
+
 ### URL hash & refresh
 
 While the modal is open it reflects the active section in the URL hash as `#settings-<section>` (e.g. `#settings-general`, `#settings-plans`), updating as the user switches tabs and clearing it on close. This means a **page refresh can re-open the modal on the same section**. It uses `history.replaceState`, so it never adds browser-history entries and never clobbers an unrelated `#anchor`. Opt out with `syncUrlHash={false}`.
@@ -329,7 +375,7 @@ onClick={() => logout({
 await logoutApi("your-project-id", token, "https://your-api");
 ```
 
-`logout` POSTs to `/auth/logout` and **always runs `onSuccess` once the request settles** — so the user is logged out client-side even if the server call fails (`onError` fires for observability). Inside a `SessionProvider`, `<LogoutButton />` with no props uses the provider's logout instead.
+`<LogoutButton />` also takes `mode="dark"`. `logout` POSTs to `/auth/logout` and **always runs `onSuccess` once the request settles** — so the user is logged out client-side even if the server call fails (`onError` fires for observability). Inside a `SessionProvider`, `<LogoutButton />` with no props uses the provider's logout instead.
 
 ---
 
@@ -389,6 +435,7 @@ import { TwoFactorSetup } from "ab-ecosystem-sso";
   projectId="your-project-id"
   token={token}
   apiBaseUrl="https://your-api"
+  mode="dark"            // optional — "light" (default) or "dark"
   onEnabled={() => …}
   onDisabled={() => …}
   onError={(err) => …}
@@ -407,6 +454,58 @@ import { TwoFactorSetup } from "ab-ecosystem-sso";
 
 ---
 
+## Light & dark mode
+
+Every component renders in **light mode by default**. Pass `mode="dark"` to switch:
+
+```tsx
+<Login projectId="…" mode="dark" onSuccess={handleAuth} />
+<Signup projectId="…" mode="dark" onLoginClick={() => navigate("/login")} />
+<ForgotPassword projectId="…" mode="dark" />
+<VerifyEmail projectId="…" mode="dark" />
+<AccountSettings open={open} onOpenChange={setOpen} mode="dark" />
+<TwoFactorSetup projectId="…" token={token} mode="dark" />
+<LogoutButton mode="dark" />
+
+openAccountSettings({ projectId, token, mode: "dark" });
+```
+
+`mode` is **per component**, not global — each component root carries a
+`data-aas-theme="light" | "dark"` attribute and the palette inherits from there, so a dark
+login card and a light settings modal can coexist on the same page.
+
+Follow your app's own theme by passing the value you already track:
+
+```tsx
+const { theme } = useTheme();          // your app's theme state
+<Login projectId="…" mode={theme === "dark" ? "dark" : "light"} />
+```
+
+To follow the OS setting instead:
+
+```tsx
+import type { AuthMode } from "ab-ecosystem-sso";
+
+const [mode, setMode] = useState<AuthMode>(
+  () => (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light")
+);
+
+useEffect(() => {
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const onChange = (e: MediaQueryListEvent) => setMode(e.matches ? "dark" : "light");
+  mq.addEventListener("change", onChange);
+  return () => mq.removeEventListener("change", onChange);
+}, []);
+
+<Login projectId="…" mode={mode} />
+```
+
+> The package deliberately does **not** read `prefers-color-scheme` itself — an auth screen
+> that silently disagrees with the host app's theme is worse than one that follows it, and only
+> your app knows which theme it's in.
+
+---
+
 ## Theming
 
 The UI reads `--aas-*` CSS custom properties, so you can retheme without touching the components. Override them on `:root` (or any ancestor) after importing the stylesheet:
@@ -424,6 +523,28 @@ The UI reads `--aas-*` CSS custom properties, so you can retheme without touchin
 }
 ```
 
+Dark mode is the same variables redeclared on `[data-aas-theme='dark']`, so retheming dark is symmetrical — override there and light stays untouched:
+
+```css
+[data-aas-theme="dark"] {
+  --aas-background: oklch(0.16 0.01 265);
+  --aas-card: oklch(0.21 0.01 265);
+  --aas-primary: oklch(0.72 0.17 265);
+  --aas-primary-foreground: oklch(0.16 0.01 265);
+}
+```
+
+Beyond the shadcn-style tokens above, a few extra ones exist so dark mode is a pure variable
+swap — override them to fine-tune either palette:
+
+| Token | Used for |
+| --- | --- |
+| `--aas-sidebar` | Account Settings sidebar panel. |
+| `--aas-hover` / `--aas-hover-strong` | Nav/icon-button hover and active fills. |
+| `--aas-overlay` / `--aas-overlay-strong` | The blur overlays on loading cards and settings sections. |
+| `--aas-success` / `--aas-success-bg` | "Verified" badges and credit amounts. |
+| `--aas-switch-track`, `--aas-switch-knob`, `--aas-switch-knob-on` | The settings toggle switch. |
+
 The styles are theme-aware and scoped to the components — they won't affect the rest of your app, and your app's global resets can't override them.
 
 ---
@@ -456,7 +577,7 @@ Everything is fully typed. Notable exports:
 
 ```ts
 import type {
-  LoginProps, SignupProps, ForgotPasswordProps, VerifyEmailProps, AuthClassNames,
+  LoginProps, SignupProps, ForgotPasswordProps, VerifyEmailProps, AuthClassNames, AuthMode,
   AccountSettingsProps, AccountSettingsSection, AccountSettingsData, ProfileFormValues,
   OpenAccountSettingsOptions, AccountSettingsHandle,
   AuthConfig, CaptchaConfig, CardLayoutConfig,