@stokr/components-library

React UI library for STOKR apps: modals, forms, navigation, tables, auth context, styles.

Contents

• Quick start — install, router, AuthProvider, styles
• Configuration reference — config keys & helpers
• AuthProvider & AuthContext
• Troubleshooting
• Development

Quick start

Install

npm install @stokr/components-library
npm install react react-dom styled-components react-router-dom

Peers: React 18+/19+, styled-components 6.x, react-router-dom 6.x when you use routing-driven components (HeaderHo, MainMenu, …).

1. Router — Navigation helpers need a React Router:

import { BrowserRouter } from 'react-router-dom'
import { RouterWrapper } from '@stokr/components-library'

// Normal app
root.render(
  <BrowserRouter>
    <App />
  </BrowserRouter>,
)

// Outside a Router: RouterWrapper wraps children in BrowserRouter once.
// Inside an existing Router: it renders children only (no nested BrowserRouter).
root.render(
  <RouterWrapper>
    <App />
  </RouterWrapper>,
)

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:

import { AuthProvider } from '@stokr/components-library'

export default 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,
        onboardingUrl: import.meta.env.VITE_ONBOARDING_URL,
        dashboardUrl: import.meta.env.VITE_DASHBOARD_URL,
        adminUrl: import.meta.env.VITE_ADMIN_URL,
        registerUrl: import.meta.env.VITE_REGISTER_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,
        },
      }}>
      {/* app */}
    </AuthProvider>
  )
}

3. Earlier config (e.g. analytics before mount): import { configure } from '@stokr/components-library' with the same shape as config.

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'.

5. Imports — import { ConfirmModal, Button, … } from '@stokr/components-library'.

Full URL env example:

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

Configuration reference {#runtime-config}

| 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() | | 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 |

Helpers: getConfig('…') for any key above; getPlatformURL() → https://{websiteDomain}; getAnalyticsIngestUrl(), getBackofficeAppUrl(path); getFooterGroups() replaces static footer URL lists.

Auth-only HTTP: authenticationApi.post(segment, body) for auth/*; default axios stays the main API client after login.

Missing overrides may trigger a one-time warning listing unresolved VITE_* expectations.

AuthProvider & AuthContext {#authprovider-optional-props}

AuthProvider is wrapped with withRouter — mount it inside a Router so redirects work.

Optional provider props

• inactivityTimeMs — Idle timeout before auto-logout + session modal (default 5 min).
• inactivityWarningBeforeMs — How long before that timeout to show the “session about to expire” warning modal (default 30 s). See Inactivity auto-logout.
• accessTokenExpiryMs — Cookie TTL when Auth.setAccessToken runs (default DEFAULT_TOKEN_EXPIRY_MS = 1 h); not extended by getUser alone.
• hideInactivityModal — Suppress both built-in inactivity modals (warning + session expired).
• onSessionExpiredLoginClick — Called when the user clicks Log in on the session-expired modal.
• customValidateGetUser(user) — Hook after user/get succeeds (see src/context/AuthContext.js).

Inactivity auto-logout {#inactivity-auto-logout}

When a user is logged in, AuthProvider resets an idle timer on mouse, keyboard, click, scroll, and touch events.

1. Warning modal — Shown inactivityWarningBeforeMs before the idle deadline (default: 30 s before the 5 min timeout). The user can click To continue, press here to reset the idle timer, or close the modal (logout still happens at the deadline). Any activity also resets the timer and closes the warning.
2. Session expired modal — Shown when the idle deadline is reached (existing behaviour). The warning modal closes automatically at the same moment.

Neither modal is shown when the user is not logged in. Both are skipped when hideInactivityModal is set.

Storybook: Authentication / Auto-logout (inactivity) → With warning modal (20 s idle, warning at 10 s).

AuthContext consumer {#authcontext-usecontext}

import { AuthContext } from '…' then useContext(AuthContext).

• 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, showInactivityWarningModal).
• 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, extendSessionFromInactivityWarning, dismissInactivityWarningModal.

Use AuthConsumer for the render-prop pattern.

Troubleshooting {#troubleshooting}

useNavigate / Router

Add BrowserRouter (or RouterWrapper from this package where the shell has no router). Install react-router-dom.

Invalid hook call / duplicated React

Dedupe peers in Vite: resolve: { dedupe: ['react', 'react-dom', 'styled-components'] }.

Development {#development--publishing}

| Command | Meaning | | -------------------- | -------------------------------- | | npm run storybook | Local docs / stories | | npm run build:dist | Library build + static copy | | npm run pub | Build then publish (npm login) |

Release: changelog entry → npm version → npm run pub. Details: CHANGELOG.md.