@stokr/components-library 3.0.32 → 3.0.33

package/README.md

@@ -1,96 +1,43 @@
 # @stokr/components-library
 
-React component library for STOKR applications. Includes modals, forms, buttons, tables, and shared styles.
-
-## Table of contents
-
-- [Installation](#installation)
-- [How to start](#how-to-start)
-- [Configuration](#configuration)
-  - [Runtime config (npm consumers)](#runtime-config)
-  - [URL variables and behavior](#url-variables-and-behavior)
-  - [Reading config with `getConfig()`](#reading-config-with-getconfig)
-  - [Ionicons](#ionicons)
-  - [React Router](#react-router)
-- [Troubleshooting](#troubleshooting)
-- [Development & publishing](#development--publishing)
-
----
-
-## Installation
-
-```bash
-npm install @stokr/components-library
-```
+React UI library for STOKR apps: modals, forms, navigation, tables, auth context, styles.
 
-**Peer dependencies** (install in your app if not already present):
-
-```bash
-npm install react react-dom styled-components react-router-dom
-```
-
-- **React** 18 or 19
-- **styled-components** 6.x
-- **react-router-dom** 6.x (required if you use routing-dependent components)
-
----
+## Contents
 
-## Implementing in your app
-
-Minimal path to use the library in a **Vite + React** consumer:
-
-1. **Install** the package and [peer dependencies](#installation) (`react`, `react-dom`, `styled-components`, and `react-router-dom` if you use routing-heavy components).
-2. **Router** — Wrap the tree with `BrowserRouter` (or another React Router v6 router) if you use `HeaderHo`, `MainMenu`, `LearnMore`, etc. If the host app may already provide a router (e.g. micro-frontend), use **`RouterWrapper`** from the package once at your root so you do not nest two `BrowserRouter` instances (see [step 2](#2-wrap-your-app-with-a-router-if-you-use-routing)).
-3. **Runtime config** — Wrap your authenticated area with `<AuthProvider config={…}>` and pass **your** `import.meta.env.VITE_*` values (see [Runtime config](#runtime-config)). This is required for correct API URLs, Firebase, cookies, and domain-based links in pre-built npm installs.
-4. **Optional** — `configure()` before `AuthProvider` if something (e.g. analytics) must read config earlier; `IoniconsStyles` or `styles.css` if you use icons or shared fonts (see below).
-
-Then import components from `@stokr/components-library` as in [step 4 under How to start](#4-import-and-use-components).
+- [Quick start](#quick-start) — install, router, `AuthProvider`, styles
+- [Configuration reference](#runtime-config) — `config` keys & helpers
+- [AuthProvider & AuthContext](#authprovider-optional-props)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development--publishing)
 
 ---
 
-## How to start
+## Quick start
 
-### 1. Install the package and peers
+**Install**
 
 ```bash
-npm install @stokr/components-library react react-dom styled-components react-router-dom
+npm install @stokr/components-library
+npm install react react-dom styled-components react-router-dom
 ```
 
-### 2. Wrap your app with a Router (if you use routing)
-
-Components that use navigation (e.g. `MainMenu`, `LearnMore`, `HeaderHo`) must live inside a React Router.
+Peers: React 18+/19+, styled-components 6.x, react-router-dom 6.x when you use routing-driven components (`HeaderHo`, `MainMenu`, …).
 
-**Simple app** — wrap with `BrowserRouter`:
+**1. Router** — Navigation helpers need a React Router:
 
 ```jsx
-// main.jsx or App.jsx
 import { BrowserRouter } from 'react-router-dom'
-import App from './App'
-
-root.render(
-  <BrowserRouter>
-    <App />
-  </BrowserRouter>,
-)
-```
-
-**Host already has a router** (or you want one `BrowserRouter` only when needed) — wrap the library subtree with **`RouterWrapper`** from `@stokr/components-library`. It renders `BrowserRouter` only when `useInRouterContext()` is false, so you avoid duplicate routers and keep SPA navigation for `withRouter` / `useNavigate`:
-
-```jsx
 import { RouterWrapper } from '@stokr/components-library'
-import { BrowserRouter } from 'react-router-dom'
-import App from './App'
 
-// Host owns the router:
+// Normal app
 root.render(
   <BrowserRouter>
-    <RouterWrapper>
-      <App />
-    </RouterWrapper>
+    <App />
   </BrowserRouter>,
 )
 
-// Standalone shell (no outer router): RouterWrapper adds BrowserRouter once.
+// Outside a Router: RouterWrapper wraps children in BrowserRouter once.
+// Inside an existing Router: it renders children only (no nested BrowserRouter).
 root.render(
   <RouterWrapper>
     <App />
@@ -98,53 +45,12 @@ root.render(
 )
 ```
 
-### 3. (Optional) Add Ionicons for icons
-
-If you use **Modal**, **ConfirmModal**, **BackButton**, **Select**, **InfoIcon**, etc., add the icon styles once at the root:
-
-```jsx
-import { IoniconsStyles } from '@stokr/components-library'
-
-function App() {
-  return (
-    <>
-      <IoniconsStyles />
-      {/* your app */}
-    </>
-  )
-}
-```
-
-You can skip this; the library will inject icon styles when you first use a component that needs them.
-
-### 4. Import and use components
-
-```jsx
-import { ConfirmModal, Button } from '@stokr/components-library'
-
-function MyPage() {
-  const [open, setOpen] = useState(false)
-  return (
-    <>
-      <Button onClick={() => setOpen(true)}>Open</Button>
-      <ConfirmModal isOpen={open} onClose={() => setOpen(false)} onConfirm={() => {}} title="Confirm?" />
-    </>
-  )
-}
-```
-
----
-
-## Configuration
-
-### Runtime config (required when consuming as npm package) {#runtime-config}
-
-Since v3.0.16, the library uses a **runtime config** system. When this package is consumed by an external Vite app, `import.meta.env` values are baked at **library build time** and do not reflect the consuming app's `.env` file. Pass a `config` prop to `<AuthProvider>` so API URLs, Firebase credentials, and cookie domain are resolved from **your** environment:
+**2. Auth & runtime config (required when consuming via npm)** — Vite freezes `import.meta.env` inside pre-built deps, so push your `.env` at runtime via `config`:
 
 ```jsx
 import { AuthProvider } from '@stokr/components-library'
 
-function App() {
+export default function App() {
   return (
     <AuthProvider
       config={{
@@ -167,215 +73,94 @@ function App() {
           measurementId: import.meta.env.VITE_FIREBASE_MEASUREMENT_ID,
         },
       }}>
-      {/* your app */}
+      {/* app */}
     </AuthProvider>
   )
 }
 ```
 
-| Prop key             | Env variable it replaces | Purpose                                                                                                                                             |
-| -------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `apiUrl`             | `VITE_API_URL`           | Backend API base URL                                                                                                                                |
-| `baseUrlPublic`      | `VITE_BASE_URL_PUBLIC`   | Public (no-auth) API base URL                                                                                                                       |
-| `cookieDomain`       | `VITE_COOKIE_DOMAIN`     | Domain attribute for auth cookies                                                                                                                   |
-| `websiteDomain`      | `VITE_WEBSITE_DOMAIN`    | Platform domain (redirects, links)                                                                                                                  |
-| `photoApiUrl`        | `VITE_PHOTO_API_URL`     | Photo upload / avatar API URL                                                                                                                       |
-| `onboardingUrl`      | `VITE_ONBOARDING_URL`    | Full onboarding app URL (signup/signin flow)                                                                                                        |
-| `dashboardUrl`       | `VITE_DASHBOARD_URL`     | Full investor dashboard URL                                                                                                                          |
-| `adminUrl`           | `VITE_ADMIN_URL`         | Full admin/venture dashboard URL                                                                                                                     |
-| `registerUrl`        | `VITE_REGISTER_URL`      | Public registration entry URL                                                                                                                        |
-| `firebase`           | `VITE_FIREBASE_*`        | Full Firebase config object                                                                                                                         |
-
-> **Why is this needed?** With the old CRA / `react-scripts` build, Webpack re-processed library code through the consuming app's build pipeline, so the app's `.env` values were injected automatically. Vite treats npm packages as pre-built — `import.meta.env` values in the compiled library are frozen at library build time. The `config` prop passes them at runtime instead.
-
-If you also need config values **before** `<AuthProvider>` mounts (e.g. for analytics init), you can call `configure()` directly:
-
-```js
-import { configure } from '@stokr/components-library'
-
-configure({
-  apiUrl: import.meta.env.VITE_API_URL,
-  cookieDomain: import.meta.env.VITE_COOKIE_DOMAIN,
-  // ...
-})
-```
-
-After `configure()` / `<AuthProvider config>`, the library may log a **one-time `console.warn`** listing any **`VITE_*`** variables that are still missing (no override and no env fallback). Fix your `.env` or extend the `config` object until the list is empty.
+**3. Earlier config** (e.g. analytics before mount): `import { configure } from '@stokr/components-library'` with the same shape as `config`.
 
-### URL variables and behavior {#url-variables-and-behavior}
+**4. Icons / fonts** — Optional: `<IoniconsStyles />` at root, or rely on lazy injection when a component uses icons; for Layout / Open Sans: `import '@stokr/components-library/styles.css'`.
 
-The URL model is now explicit: pass full app URLs instead of routing mode/path segment rules.
+**5. Imports** — `import { ConfirmModal, Button, … } from '@stokr/components-library'`.
 
-Expected URL env variables (matching current `.env.local`):
+Full URL env example:
 
 ```bash
-VITE_WEBSITE_DOMAIN=stokr.info
-VITE_ONBOARDING_URL=https://signup.stokr.info
-VITE_DASHBOARD_URL=https://dashboard.stokr.info
-VITE_ADMIN_URL=https://admin.stokr.info
-VITE_REGISTER_URL=https://stokr.info/signup
+VITE_WEBSITE_DOMAIN=example.com
+VITE_ONBOARDING_URL=https://signup.example.com
+VITE_DASHBOARD_URL=https://dashboard.example.com
+VITE_ADMIN_URL=https://admin.example.com
+VITE_REGISTER_URL=https://example.com/signup
 ```
 
-How each value is used:
-
-- `VITE_ONBOARDING_URL`: signup/signin flow redirects (for example `/welcome`, `/resend-activation-email`).
-- `VITE_DASHBOARD_URL`: investor dashboard entry point.
-- `VITE_ADMIN_URL`: admin/venture dashboard entry point.
-- `VITE_REGISTER_URL`: register CTA/entry URL.
-- `VITE_WEBSITE_DOMAIN`: base host used by `getPlatformURL()` and fixed subdomains (analytics/backoffice).
-
-Derived helpers:
-
-- `getPlatformURL()` => `https://{VITE_WEBSITE_DOMAIN}` (for example `https://stokr.info`).
-- `getAnalyticsIngestUrl()` => `https://analytics.{VITE_WEBSITE_DOMAIN}`.
-- `getBackofficeAppUrl('/path')` => `https://backoffice.{VITE_WEBSITE_DOMAIN}/path`.
-
-**Authentication-only HTTP** — backend routes under `auth/*` (e.g. forgot password) are exposed as **`authenticationApi.post(segment, body)`** from `src/api/authenticationApi.js` (also re-exported from the package entry). The default axios instance is the **general API client** for all authenticated backend calls, not auth-only.
-
-### Reading config with `getConfig()` {#reading-config-with-getconfig}
-
-In your app (or in code next to the library), read the same resolved values the package uses:
-
-```js
-import { getConfig } from '@stokr/components-library'
-
-const api = getConfig('apiUrl')
-const domain = getConfig('websiteDomain')
-const firebaseOptions = getConfig('firebase') // override object or env-built fallback
-const onboarding = getConfig('onboardingUrl')
-const dashboard = getConfig('dashboardUrl')
-const admin = getConfig('adminUrl')
-const register = getConfig('registerUrl')
-```
-
-Supported keys: `apiUrl`, `baseUrlPublic`, `cookieDomain`, `websiteDomain`, `photoApiUrl`, `onboardingUrl`, `dashboardUrl`, `adminUrl`, `registerUrl`, `firebase`. Resolution order is always **explicit `configure()` / `AuthProvider` `config`** first, then **`import.meta.env`** in the consuming Vite app (where a `VITE_*` mapping exists).
-
-**Marketing site origin** — the old `platformDomain` / `platformURL` exports were removed. Use **`getPlatformURL()`** for `https://{websiteDomain}`, or **`getConfig('websiteDomain')`** for the bare host (e.g. `"example.com"`). Both read the same runtime config after **`configure()`** / **`AuthProvider`**.
-
-```js
-import { getConfig, getPlatformURL } from '@stokr/components-library'
-
-const host = getConfig('websiteDomain') // e.g. "example.com"
-const origin = getPlatformURL() // e.g. "https://example.com"
-```
-
-**Footer link groups** — if you previously imported the static `footerGroups` from `FooterLayout`, import **`getFooterGroups`** instead (same package entry as other footer exports). It returns fresh URLs using the current `getPlatformURL()`.
-
-### Ionicons
-
-Components such as **Modal**, **ConfirmModal**, **BackButton**, **InfoIcon**, **Select**, **MainMenu**, and **RegisterLiquidSteps** use [Ionicons](http://ionicons.com/). You can enable them in three ways:
-
-| Approach             | When to use                                                                                                                   |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| **Global injection** | Render `<IoniconsStyles />` once at app root. Full icon set, singleton.                                                       |
-| **No setup**         | Don’t render anything; styles inject on first use of an icon component.                                                       |
-| **CSS import**       | Prefer loading via CSS: `import '@stokr/components-library/styles.css'` or `import '@stokr/components-library/ionicons.css'`. |
-
-**Global injection example:**
-
-```jsx
-import { IoniconsStyles } from '@stokr/components-library'
-
-function App() {
-  return (
-    <>
-      <IoniconsStyles />
-      {/* your routes, layout, etc. */}
-    </>
-  )
-}
-```
-
-If you use **Layout**, **GlobalStyle**, or need **Open Sans**, import the full styles once:
-
-```js
-import '@stokr/components-library/styles.css'
-```
-
-### React Router
-
-Any component that uses `useNavigate()` or routing must be rendered inside a `Router` from `react-router-dom` (e.g. `BrowserRouter`), or under **`RouterWrapper`** so a router exists when the host does not provide one. Components wrapped with **`withRouter`** receive `navigate` from `useNavigate()` when inside a Router; outside a Router, `navigate` throws with a message to add `BrowserRouter` or `RouterWrapper`. See [How to start – step 2](#2-wrap-your-app-with-a-router-if-you-use-routing).
-
 ---
 
-## Troubleshooting
+## Configuration reference {#runtime-config}
 
-### "useNavigate() may be used only in the context of a \<Router\> component"
+| `config` key      | Typical `VITE_*`           | Role                                      |
+| ----------------- | -------------------------- | ----------------------------------------- |
+| `apiUrl`          | `VITE_API_URL`             | Authenticated REST base                   |
+| `baseUrlPublic`   | `VITE_BASE_URL_PUBLIC`     | Public API base                           |
+| `cookieDomain`    | `VITE_COOKIE_DOMAIN`       | Auth cookie `domain` attribute            |
+| `websiteDomain`   | `VITE_WEBSITE_DOMAIN`      | Bare host → links / `getPlatformURL()`    |
+| `photoApiUrl`     | `VITE_PHOTO_API_URL`       | Avatars / media                           |
+| `onboardingUrl`   | `VITE_ONBOARDING_URL`      | Full signup/sign-in app URL               |
+| `dashboardUrl`    | `VITE_DASHBOARD_URL`       | Investor dashboard URL                    |
+| `adminUrl`        | `VITE_ADMIN_URL`           | Venture / admin dashboard URL             |
+| `registerUrl`     | `VITE_REGISTER_URL`        | Public registration entry                 |
+| `firebase`        | `VITE_FIREBASE_*`          | Firebase client config                    |
 
-Wrap your app with a Router, or use **`RouterWrapper`** at the root when you are not already inside a host `BrowserRouter`:
+**Helpers:** `getConfig('…')` for any key above; `getPlatformURL()` → `https://{websiteDomain}`; `getAnalyticsIngestUrl()`, `getBackofficeAppUrl(path)`; **`getFooterGroups()`** replaces static footer URL lists.
 
-```jsx
-import { BrowserRouter } from 'react-router-dom'
+**Auth-only HTTP:** `authenticationApi.post(segment, body)` for `auth/*`; default axios stays the main API client after login.
 
-root.render(
-  <BrowserRouter>
-    <App />
-  </BrowserRouter>,
-)
-```
+Missing overrides may trigger a **one-time** warning listing unresolved `VITE_*` expectations.
 
-```jsx
-import { RouterWrapper } from '@stokr/components-library'
+---
 
-root.render(
-  <RouterWrapper>
-    <App />
-  </RouterWrapper>,
-)
-```
+## AuthProvider & AuthContext {#authprovider-optional-props}
 
-Install the peer dependency: `npm install react-router-dom`
+`AuthProvider` is wrapped with **`withRouter`** — mount it inside a **`Router`** so redirects work.
 
-### "Invalid hook call" / "Cannot read properties of null (reading 'use')"
+### Optional provider props
 
-Your app and the library must use the **same** React instance.
+- **`inactivityTimeMs`** — Idle timeout before auto-logout + session modal (default 5 min).
+- **`accessTokenExpiryMs`** — Cookie TTL when **`Auth.setAccessToken`** runs (default **`DEFAULT_TOKEN_EXPIRY_MS`** = 1 h); not extended by **`getUser`** alone.
+- **`hideInactivityModal`** — Suppress built-in session modal.
+- **`customValidateGetUser(user)`** — Hook after **`user/get`** succeeds (see `src/context/AuthContext.js`).
 
-1. Install peer dependencies:  
-   `npm install react react-dom styled-components`
+### AuthContext consumer {#authcontext-usecontext}
 
-2. **Vite apps** – add dedupe in `vite.config.js` or `vite.config.ts`:
+`import { AuthContext } from '…'` then `useContext(AuthContext)`.
 
-   ```js
-   export default defineConfig({
-     resolve: {
-       dedupe: ['react', 'react-dom', 'styled-components'],
-     },
-     // ...rest of config
-   })
-   ```
+- **Invalid Firebase guard:** value is **`{ user: null, isFetchingUser: false }`** only (no methods).
+- **State (grouped):** `user` / `firebaseUser`, `isFetchingUser`, `avatar`; MFA (`waitingFor2fa`, `userMfaEnrollment`, `firebaseError`); verify-email (`verifyEmailError`, `isVerifyingEmail`); session UX (`loggedOutDueToInactivity`, `loggedOutDueToCookieExpiry`, `sessionExpiryPendingReason`).
+- **Actions (grouped):** `userRef`, `loginUser`, `logoutUser`, `getUser`, `setUser`, `updateUser`, `refreshIdToken`; `checkUserIsValid`, `checkTokenIsValid`; `uploadPhoto`, `deletePhoto`, `checkUserPhoto`; MFA enroll / verify / unenroll + `reset2faFlow`; subscription/onboarding helpers; password & email (`handleResetPassword`, `handleVerifyEmail`, `requestUpdateEmail`, …); wallets / PoA (`uploaProofOfAddress` keeps the source spelling); **`dismissSessionExpiryModal`**.
 
-3. Reinstall or refresh the library after updating (e.g. `npm install` or clear cache and reinstall).
+Use **`AuthConsumer`** for the render-prop pattern.
 
 ---
 
-## Development & publishing
-
-### Run Storybook
+## Troubleshooting {#troubleshooting}
 
-```bash
-npm run storybook
-```
+**`useNavigate` / Router**
 
-Use **Story Source** for consumption examples and **Viewport** for different screen sizes.
+Add `BrowserRouter` (or **`RouterWrapper`** from this package where the shell has no router). Install `react-router-dom`.
 
-### Build for distribution
+**Invalid hook call / duplicated React**
 
-```bash
-npm run build:dist
-```
+Dedupe peers in Vite: `resolve: { dedupe: ['react', 'react-dom', 'styled-components'] }`.
 
-This runs `vite build` and copies static assets to `dist/`.
-
-### Publish a new version
-
-1. Commit your changes.
-2. Update [CHANGELOG.md](CHANGELOG.md) – add a new `# vX.Y.Z` section at the top with the list of changes.
-3. Bump the version: `npm version <version>` (e.g. `npm version 3.0.7`).
-4. (ensure you are authenticated) Run `npm login` to log first on NPM package (only needed one time a day)
-5. Run `npm run pub` (will first run `npm run build:dist`).
+---
 
-Consumers can see what changed in each release in [CHANGELOG.md](CHANGELOG.md).
+## Development {#development--publishing}
 
-### Reference
+| Command              | Meaning                          |
+| -------------------- | -------------------------------- |
+| `npm run storybook`  | Local docs / stories             |
+| `npm run build:dist` | Library build + static copy      |
+| `npm run pub`        | Build then publish (`npm login`) |
 
-- [How to publish a React component library](https://medium.com/better-programming/how-to-publish-a-react-component-library-c89a07566770)
+Release: changelog entry → `npm version` → `npm run pub`. Details: [CHANGELOG.md](CHANGELOG.md).

package/dist/components/2FA/login-with-otp-flow.js

@@ -11,7 +11,7 @@ import { authenticationApi } from "../../api/authenticationApi.js";
 import { getConfig, getPlatformURL } from "../../runtime-config.js";
 import { navigateToHref } from "../../routing/navigate-app.js";
 import { useNavigate } from "react-router-dom";
-const LoginWithOTP = ({ withBackground }) => {
+const LoginWithOTP = ({ withBackground, useRelativePathForMenu = false }) => {
   const navigate = useNavigate();
   const { loginUser, waitingFor2fa, firebaseError, loginUserWithTotp, reset2faFlow } = useContext(AuthContext);
   const [isModalOpen, setIsModalOpen] = useState({
@@ -60,7 +60,7 @@ const LoginWithOTP = ({ withBackground }) => {
     });
   };
   const backgroundProp = `url(${background}) left top no-repeat`;
-  return /* @__PURE__ */ jsxs(Layout, { noHeader: true, noFooter: true, children: [
+  return /* @__PURE__ */ jsxs(Layout, { noHeader: true, noFooter: true, useRelativePathForMenu, children: [
     /* @__PURE__ */ jsx(
       stdin_default$1,
       {