@stokr/components-library 3.0.22 → 3.0.24

package/README.md

@@ -1,467 +1,467 @@
-# @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)
-  - [Path-based URLs vs subdomains](#path-based-urls-vs-subdomains)
-  - [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
-```
-
-**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)
-
----
-
-## 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).
-
----
-
-## How to start
-
-### 1. Install the package and peers
-
-```bash
-npm install @stokr/components-library 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.
-
-**Simple app** — wrap with `BrowserRouter`:
-
-```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:
-root.render(
-  <BrowserRouter>
-    <RouterWrapper>
-      <App />
-    </RouterWrapper>
-  </BrowserRouter>,
-)
-
-// Standalone shell (no outer router): RouterWrapper adds BrowserRouter once.
-root.render(
-  <RouterWrapper>
-    <App />
-  </RouterWrapper>,
-)
-```
-
-### 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:
-
-```jsx
-import { AuthProvider } from '@stokr/components-library'
-
-function App() {
-  return (
-    <AuthProvider
-      config={{
-        apiUrl: import.meta.env.VITE_API_URL,
-        baseUrlPublic: import.meta.env.VITE_BASE_URL_PUBLIC,
-        cookieDomain: import.meta.env.VITE_COOKIE_DOMAIN,
-        websiteDomain: import.meta.env.VITE_WEBSITE_DOMAIN,
-        photoApiUrl: import.meta.env.VITE_PHOTO_API_URL,
-        firebase: {
-          apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
-          authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
-          projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
-          storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
-          messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
-          appId: import.meta.env.VITE_FIREBASE_APP_ID,
-          measurementId: import.meta.env.VITE_FIREBASE_MEASUREMENT_ID,
-        },
-      }}>
-      {/* your 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                                                                                                                       |
-| `firebase`           | `VITE_FIREBASE_*`        | Full Firebase config object                                                                                                                         |
-| `routingMode`        | `VITE_ROUTING_MODE`      | Set to `path` for single-origin app URLs (see below).                                                                                               |
-| `appUrlPaths`        | —                        | Optional object overriding first path segments in path mode (e.g. `{ onboarding: '/signup', dashboard: '/app' }`).                                  |
-| `surfaceRoutingMode` | —                        | Optional per-surface `'path'` / `'subdomain'` overrides for incremental URL migration (see [below](#incremental-url-migration-surfaceRoutingMode)). |
-
-> **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.
-
-### Path-based URLs vs subdomains {#path-based-urls-vs-subdomains}
-
-By default the library builds **subdomain** links (`https://dashboard.{websiteDomain}`, `https://signup.{websiteDomain}/welcome`, `https://admin.{websiteDomain}`, etc.), matching historical STOKR hosting.
-
-To switch to **one origin + path prefixes** (for example `https://example.com/dashboard`, `https://example.com/signin/welcome`, `https://example.com/admin`), pass **`routingMode: 'path'`** (or `VITE_ROUTING_MODE=path`) and optionally **`appUrlPaths`** overrides. The public origin for path mode is always **`https://{websiteDomain}`** (same as **`getPlatformURL()`**).
-
-```jsx
-<AuthProvider
-  config={{
-    apiUrl: import.meta.env.VITE_API_URL,
-    websiteDomain: import.meta.env.VITE_WEBSITE_DOMAIN,
-    routingMode: 'path',
-    appUrlPaths: {
-      onboarding: '/signin', // flows that used https://signup.{domain}
-      registerEntry: '/signup', // CTA from login; default in code is /signup
-      dashboard: '/dashboard',
-      admin: '/admin',
-    },
-    firebase: { /* … */ },
-    /* …other keys */
-  }}>
-```
-
-**Analytics and backoffice** always use legacy subdomains **`https://analytics.{websiteDomain}`** and **`https://backoffice.{websiteDomain}`**, even in path mode. They are implemented in **`src/utils/app-urls-analytics-backoffice.js`** and re-exported from **`app-urls.js`** (`getAnalyticsIngestUrl`, `getBackofficeAppUrl`); they are not driven by **`appUrlPaths`**.
-
-#### Incremental URL migration (`surfaceRoutingMode`) {#incremental-url-migration-surfaceRoutingMode}
-
-You do not have to flip every surface at once.
-
-- **Global default:** `routingMode: 'path'` means “use path URLs for every surface that supports it”, unless overridden. Leaving `routingMode` unset (or not `'path'`) keeps **subdomain** URLs by default.
-- **Per-surface override:** pass **`surfaceRoutingMode`** on `configure()` / `<AuthProvider config>`. Each key is one of **`onboarding`**, **`dashboard`**, **`admin`**, **`registerEntry`**, **`investorRoot`** (see **`SURFACE_ROUTING_PATH_KEYS`** on the package entry). Each value is **`'path'`** or **`'subdomain'`**. Any surface **omitted** from the object follows the global **`routingMode`**.
-
-Examples:
-
-1. **Path everywhere except admin** (admin still `https://admin.{domain}` until infra is ready):
-
-```js
-configure({
-  websiteDomain: 'example.com',
-  routingMode: 'path',
-  appUrlPaths: { dashboard: '/dashboard', onboarding: '/signin', registerEntry: '/signup', admin: '/admin' },
-  surfaceRoutingMode: { admin: 'subdomain' },
-})
-```
-
-2. **Subdomains by default, dashboard and admin on path** (e.g. first rollout):
-
-```js
-configure({
-  websiteDomain: 'example.com',
-  appUrlPaths: { dashboard: '/dashboard', admin: '/admin' },
-  surfaceRoutingMode: { dashboard: 'path', admin: 'path' },
-})
-```
-
-In host UI or guards, use **`isPathForSurface('dashboard')`** / **`isPathForSurface('admin')`** (exported from **`@stokr/components-library`**) so behaviour matches **`resolveAppHref`**.
-
-##### Worked example (no script)
-
-Assume **`websiteDomain: 'acme.com'`** and default **`appUrlPaths`** (among others: **`dashboard`** → **`/dashboard`**, **`admin`** → **`/admin`**).
-
-**A — Full path mode** (every surface that supports paths uses **`https://acme.com`** + prefix):
-
-```js
-import { configure, resolveAppHref, isPathForSurface, AppSurface } from '@stokr/components-library'
-
-configure({ websiteDomain: 'acme.com', routingMode: 'path' })
-```
-
-| Call                                                 | Result                                 |
-| ---------------------------------------------------- | -------------------------------------- |
-| `resolveAppHref(AppSurface.DASHBOARD, '')`           | `https://acme.com/dashboard`           |
-| `resolveAppHref(AppSurface.DASHBOARD, '/checklist')` | `https://acme.com/dashboard/checklist` |
-| `resolveAppHref(AppSurface.ADMIN, '')`               | `https://acme.com/admin`               |
-| `isPathForSurface('dashboard')`                      | `true`                                 |
-| `isPathForSurface('admin')`                          | `true`                                 |
-
-**B — Path mode, but admin stays on subdomain** until infra is ready:
-
-```js
-configure({
-  websiteDomain: 'acme.com',
-  routingMode: 'path',
-  surfaceRoutingMode: { admin: 'subdomain' },
-})
-```
-
-| Call                                                 | Result                                             |
-| ---------------------------------------------------- | -------------------------------------------------- |
-| `resolveAppHref(AppSurface.DASHBOARD, '/checklist')` | `https://acme.com/dashboard/checklist` (unchanged) |
-| `resolveAppHref(AppSurface.ADMIN, '')`               | `https://admin.acme.com`                           |
-| `isPathForSurface('admin')`                          | `false`                                            |
-
-**C — Global default is still subdomain; dashboard and admin use path** (incremental first step):
-
-```js
-configure({
-  websiteDomain: 'acme.com',
-  surfaceRoutingMode: { dashboard: 'path', admin: 'path' },
-})
-```
-
-(`routingMode` is not **`'path'`**, so any surface **not** listed in **`surfaceRoutingMode`** keeps subdomain URLs.)
-
-| Call                                       | Result                       |
-| ------------------------------------------ | ---------------------------- |
-| `resolveAppHref(AppSurface.DASHBOARD, '')` | `https://acme.com/dashboard` |
-| `resolveAppHref(AppSurface.ADMIN, '')`     | `https://acme.com/admin`     |
-| `isPathForSurface('dashboard')`            | `true`                       |
-| `isPathForSurface('admin')`                | `true`                       |
-
-**Rule of thumb:** for each routable surface, the code checks **`surfaceRoutingMode[surfaceKey]`** first (`'path'` or `'subdomain'`). If that key is **omitted**, it falls back to the global flag **`routingMode === 'path'`**. **`resolveAppHref`** and **`isPathForSurface`** use the same logic.
-
-Readable routing API (recommended):
-
-- **`AppSurface`** / **`AppRoute`** — named surfaces and path suffixes (`src/routing/app-routes.js`).
-- **`resolveAppHref(surface, path)`** — one function that returns the absolute URL for any surface + suffix.
-- **`isPathForSurface(key)`** / **`SURFACE_ROUTING_PATH_KEYS`** — align host code with per-surface path vs subdomain resolution when using **`surfaceRoutingMode`**.
-- **`navigateApp(navigate, surface, path)`** / **`navigateToHref(navigate, url)`** — use the `navigate` function from `react-router-dom` when the target is **same-origin** (SPA transition); otherwise they fall back to `location.assign` (e.g. `admin.` / `signup.` subdomains).
-- **`RouterWrapper`** — optional root helper: mounts `BrowserRouter` only when the tree is not already under a Router (same-origin SPA navigation without nesting two browser routers).
-
-Legacy helpers (`buildDashboardUrl`, `getAdminAppUrl`, …) remain on **`./utils/app-urls`** for compatibility.
-
-**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
-```
-
-Supported keys: `apiUrl`, `baseUrlPublic`, `cookieDomain`, `websiteDomain`, `photoApiUrl`, `routingMode`, `appUrlPaths`, `surfaceRoutingMode`, `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
-
-### "useNavigate() may be used only in the context of a \<Router\> component"
-
-Wrap your app with a Router, or use **`RouterWrapper`** at the root when you are not already inside a host `BrowserRouter`:
-
-```jsx
-import { BrowserRouter } from 'react-router-dom'
-
-root.render(
-  <BrowserRouter>
-    <App />
-  </BrowserRouter>,
-)
-```
-
-```jsx
-import { RouterWrapper } from '@stokr/components-library'
-
-root.render(
-  <RouterWrapper>
-    <App />
-  </RouterWrapper>,
-)
-```
-
-Install the peer dependency: `npm install react-router-dom`
-
-### "Invalid hook call" / "Cannot read properties of null (reading 'use')"
-
-Your app and the library must use the **same** React instance.
-
-1. Install peer dependencies:  
-   `npm install react react-dom styled-components`
-
-2. **Vite apps** – add dedupe in `vite.config.js` or `vite.config.ts`:
-
-   ```js
-   export default defineConfig({
-     resolve: {
-       dedupe: ['react', 'react-dom', 'styled-components'],
-     },
-     // ...rest of config
-   })
-   ```
-
-3. Reinstall or refresh the library after updating (e.g. `npm install` or clear cache and reinstall).
-
----
-
-## Development & publishing
-
-### Run Storybook
-
-```bash
-npm run storybook
-```
-
-Use **Story Source** for consumption examples and **Viewport** for different screen sizes.
-
-### Build for distribution
-
-```bash
-npm run build:dist
-```
-
-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).
-
-### Reference
-
-- [How to publish a React component library](https://medium.com/better-programming/how-to-publish-a-react-component-library-c89a07566770)
+# @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)
+  - [Path-based URLs vs subdomains](#path-based-urls-vs-subdomains)
+  - [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
+```
+
+**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)
+
+---
+
+## 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).
+
+---
+
+## How to start
+
+### 1. Install the package and peers
+
+```bash
+npm install @stokr/components-library 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.
+
+**Simple app** — wrap with `BrowserRouter`:
+
+```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:
+root.render(
+  <BrowserRouter>
+    <RouterWrapper>
+      <App />
+    </RouterWrapper>
+  </BrowserRouter>,
+)
+
+// Standalone shell (no outer router): RouterWrapper adds BrowserRouter once.
+root.render(
+  <RouterWrapper>
+    <App />
+  </RouterWrapper>,
+)
+```
+
+### 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:
+
+```jsx
+import { AuthProvider } from '@stokr/components-library'
+
+function App() {
+  return (
+    <AuthProvider
+      config={{
+        apiUrl: import.meta.env.VITE_API_URL,
+        baseUrlPublic: import.meta.env.VITE_BASE_URL_PUBLIC,
+        cookieDomain: import.meta.env.VITE_COOKIE_DOMAIN,
+        websiteDomain: import.meta.env.VITE_WEBSITE_DOMAIN,
+        photoApiUrl: import.meta.env.VITE_PHOTO_API_URL,
+        firebase: {
+          apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+          authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+          projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+          storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
+          messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
+          appId: import.meta.env.VITE_FIREBASE_APP_ID,
+          measurementId: import.meta.env.VITE_FIREBASE_MEASUREMENT_ID,
+        },
+      }}>
+      {/* your 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                                                                                                                       |
+| `firebase`           | `VITE_FIREBASE_*`        | Full Firebase config object                                                                                                                         |
+| `routingMode`        | `VITE_ROUTING_MODE`      | Set to `path` for single-origin app URLs (see below).                                                                                               |
+| `appUrlPaths`        | —                        | Optional object overriding first path segments in path mode (e.g. `{ onboarding: '/signup', dashboard: '/app' }`).                                  |
+| `surfaceRoutingMode` | —                        | Optional per-surface `'path'` / `'subdomain'` overrides for incremental URL migration (see [below](#incremental-url-migration-surfaceRoutingMode)). |
+
+> **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.
+
+### Path-based URLs vs subdomains {#path-based-urls-vs-subdomains}
+
+By default the library builds **subdomain** links (`https://dashboard.{websiteDomain}`, `https://signup.{websiteDomain}/welcome`, `https://admin.{websiteDomain}`, etc.), matching historical STOKR hosting.
+
+To switch to **one origin + path prefixes** (for example `https://example.com/dashboard`, `https://example.com/signin/welcome`, `https://example.com/admin`), pass **`routingMode: 'path'`** (or `VITE_ROUTING_MODE=path`) and optionally **`appUrlPaths`** overrides. The public origin for path mode is always **`https://{websiteDomain}`** (same as **`getPlatformURL()`**).
+
+```jsx
+<AuthProvider
+  config={{
+    apiUrl: import.meta.env.VITE_API_URL,
+    websiteDomain: import.meta.env.VITE_WEBSITE_DOMAIN,
+    routingMode: 'path',
+    appUrlPaths: {
+      onboarding: '/signin', // flows that used https://signup.{domain}
+      registerEntry: '/signup', // CTA from login; default in code is /signup
+      dashboard: '/dashboard',
+      admin: '/admin',
+    },
+    firebase: { /* … */ },
+    /* …other keys */
+  }}>
+```
+
+**Analytics and backoffice** always use legacy subdomains **`https://analytics.{websiteDomain}`** and **`https://backoffice.{websiteDomain}`**, even in path mode. They are implemented in **`src/utils/app-urls-analytics-backoffice.js`** and re-exported from **`app-urls.js`** (`getAnalyticsIngestUrl`, `getBackofficeAppUrl`); they are not driven by **`appUrlPaths`**.
+
+#### Incremental URL migration (`surfaceRoutingMode`) {#incremental-url-migration-surfaceRoutingMode}
+
+You do not have to flip every surface at once.
+
+- **Global default:** `routingMode: 'path'` means “use path URLs for every surface that supports it”, unless overridden. Leaving `routingMode` unset (or not `'path'`) keeps **subdomain** URLs by default.
+- **Per-surface override:** pass **`surfaceRoutingMode`** on `configure()` / `<AuthProvider config>`. Each key is one of **`onboarding`**, **`dashboard`**, **`admin`**, **`registerEntry`**, **`investorRoot`** (see **`SURFACE_ROUTING_PATH_KEYS`** on the package entry). Each value is **`'path'`** or **`'subdomain'`**. Any surface **omitted** from the object follows the global **`routingMode`**.
+
+Examples:
+
+1. **Path everywhere except admin** (admin still `https://admin.{domain}` until infra is ready):
+
+```js
+configure({
+  websiteDomain: 'example.com',
+  routingMode: 'path',
+  appUrlPaths: { dashboard: '/dashboard', onboarding: '/signin', registerEntry: '/signup', admin: '/admin' },
+  surfaceRoutingMode: { admin: 'subdomain' },
+})
+```
+
+2. **Subdomains by default, dashboard and admin on path** (e.g. first rollout):
+
+```js
+configure({
+  websiteDomain: 'example.com',
+  appUrlPaths: { dashboard: '/dashboard', admin: '/admin' },
+  surfaceRoutingMode: { dashboard: 'path', admin: 'path' },
+})
+```
+
+In host UI or guards, use **`isPathForSurface('dashboard')`** / **`isPathForSurface('admin')`** (exported from **`@stokr/components-library`**) so behaviour matches **`resolveAppHref`**.
+
+##### Worked example (no script)
+
+Assume **`websiteDomain: 'acme.com'`** and default **`appUrlPaths`** (among others: **`dashboard`** → **`/dashboard`**, **`admin`** → **`/admin`**).
+
+**A — Full path mode** (every surface that supports paths uses **`https://acme.com`** + prefix):
+
+```js
+import { configure, resolveAppHref, isPathForSurface, AppSurface } from '@stokr/components-library'
+
+configure({ websiteDomain: 'acme.com', routingMode: 'path' })
+```
+
+| Call                                                 | Result                                 |
+| ---------------------------------------------------- | -------------------------------------- |
+| `resolveAppHref(AppSurface.DASHBOARD, '')`           | `https://acme.com/dashboard`           |
+| `resolveAppHref(AppSurface.DASHBOARD, '/checklist')` | `https://acme.com/dashboard/checklist` |
+| `resolveAppHref(AppSurface.ADMIN, '')`               | `https://acme.com/admin`               |
+| `isPathForSurface('dashboard')`                      | `true`                                 |
+| `isPathForSurface('admin')`                          | `true`                                 |
+
+**B — Path mode, but admin stays on subdomain** until infra is ready:
+
+```js
+configure({
+  websiteDomain: 'acme.com',
+  routingMode: 'path',
+  surfaceRoutingMode: { admin: 'subdomain' },
+})
+```
+
+| Call                                                 | Result                                             |
+| ---------------------------------------------------- | -------------------------------------------------- |
+| `resolveAppHref(AppSurface.DASHBOARD, '/checklist')` | `https://acme.com/dashboard/checklist` (unchanged) |
+| `resolveAppHref(AppSurface.ADMIN, '')`               | `https://admin.acme.com`                           |
+| `isPathForSurface('admin')`                          | `false`                                            |
+
+**C — Global default is still subdomain; dashboard and admin use path** (incremental first step):
+
+```js
+configure({
+  websiteDomain: 'acme.com',
+  surfaceRoutingMode: { dashboard: 'path', admin: 'path' },
+})
+```
+
+(`routingMode` is not **`'path'`**, so any surface **not** listed in **`surfaceRoutingMode`** keeps subdomain URLs.)
+
+| Call                                       | Result                       |
+| ------------------------------------------ | ---------------------------- |
+| `resolveAppHref(AppSurface.DASHBOARD, '')` | `https://acme.com/dashboard` |
+| `resolveAppHref(AppSurface.ADMIN, '')`     | `https://acme.com/admin`     |
+| `isPathForSurface('dashboard')`            | `true`                       |
+| `isPathForSurface('admin')`                | `true`                       |
+
+**Rule of thumb:** for each routable surface, the code checks **`surfaceRoutingMode[surfaceKey]`** first (`'path'` or `'subdomain'`). If that key is **omitted**, it falls back to the global flag **`routingMode === 'path'`**. **`resolveAppHref`** and **`isPathForSurface`** use the same logic.
+
+Readable routing API (recommended):
+
+- **`AppSurface`** / **`AppRoute`** — named surfaces and path suffixes (`src/routing/app-routes.js`).
+- **`resolveAppHref(surface, path)`** — one function that returns the absolute URL for any surface + suffix.
+- **`isPathForSurface(key)`** / **`SURFACE_ROUTING_PATH_KEYS`** — align host code with per-surface path vs subdomain resolution when using **`surfaceRoutingMode`**.
+- **`navigateApp(navigate, surface, path)`** / **`navigateToHref(navigate, url)`** — use the `navigate` function from `react-router-dom` when the target is **same-origin** (SPA transition); otherwise they fall back to `location.assign` (e.g. `admin.` / `signup.` subdomains).
+- **`RouterWrapper`** — optional root helper: mounts `BrowserRouter` only when the tree is not already under a Router (same-origin SPA navigation without nesting two browser routers).
+
+Legacy helpers (`buildDashboardUrl`, `getAdminAppUrl`, …) remain on **`./utils/app-urls`** for compatibility.
+
+**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
+```
+
+Supported keys: `apiUrl`, `baseUrlPublic`, `cookieDomain`, `websiteDomain`, `photoApiUrl`, `routingMode`, `appUrlPaths`, `surfaceRoutingMode`, `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
+
+### "useNavigate() may be used only in the context of a \<Router\> component"
+
+Wrap your app with a Router, or use **`RouterWrapper`** at the root when you are not already inside a host `BrowserRouter`:
+
+```jsx
+import { BrowserRouter } from 'react-router-dom'
+
+root.render(
+  <BrowserRouter>
+    <App />
+  </BrowserRouter>,
+)
+```
+
+```jsx
+import { RouterWrapper } from '@stokr/components-library'
+
+root.render(
+  <RouterWrapper>
+    <App />
+  </RouterWrapper>,
+)
+```
+
+Install the peer dependency: `npm install react-router-dom`
+
+### "Invalid hook call" / "Cannot read properties of null (reading 'use')"
+
+Your app and the library must use the **same** React instance.
+
+1. Install peer dependencies:  
+   `npm install react react-dom styled-components`
+
+2. **Vite apps** – add dedupe in `vite.config.js` or `vite.config.ts`:
+
+   ```js
+   export default defineConfig({
+     resolve: {
+       dedupe: ['react', 'react-dom', 'styled-components'],
+     },
+     // ...rest of config
+   })
+   ```
+
+3. Reinstall or refresh the library after updating (e.g. `npm install` or clear cache and reinstall).
+
+---
+
+## Development & publishing
+
+### Run Storybook
+
+```bash
+npm run storybook
+```
+
+Use **Story Source** for consumption examples and **Viewport** for different screen sizes.
+
+### Build for distribution
+
+```bash
+npm run build:dist
+```
+
+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).
+
+### Reference
+
+- [How to publish a React component library](https://medium.com/better-programming/how-to-publish-a-react-component-library-c89a07566770)