@campxdev/shared 3.1.23 → 3.1.24-alpha.2

package/CLAUDE.md

@@ -0,0 +1,202 @@
+# CLAUDE.md
+
+## Project Overview
+
+**Package**: `@campxdev/shared` (v3.1.23)
+**Entry point**: `./exports.ts`
+**Type**: Shared React component library (internally called "X1 UI package")
+
+This is a shared frontend library consumed by **all CampX frontend microfrontends** (27+ apps). It provides common React components, hooks, utilities, contexts, layouts, and theme configuration. It is the **legacy** shared UI layer (X1, built on MUI + styled-components). The newer design system is `@campxdev/react-blueprint` (X3), but this package remains widely used and actively maintained.
+
+**Consumers**: Every `campx-*-web` frontend repo imports from `@campxdev/shared`. Changes here propagate across the entire platform.
+
+## Architecture
+
+### Package Structure
+
+```
+src/
+├── components/       # Reusable UI components (the bulk of this package)
+├── hooks/            # Custom React hooks
+├── utils/            # Helper functions, formatters, parsers
+├── contexts/         # React context providers (auth, tenant, etc.)
+├── layouts/          # Page layout shells and wrappers
+├── theme/            # MUI theme configuration and overrides
+├── config/           # Axios instances, app config
+├── constants/        # Shared constants and enums
+├── shared-state/     # Pullstate global stores
+├── permissions/      # Permission definitions and helpers
+├── sitemap/          # Route/navigation definitions
+├── assets/           # Shared icons, images, static files
+├── stories/          # Storybook stories
+├── pages/            # Shared pages (login, error, profile, etc.)
+├── App.tsx           # Dev/preview app (not exported)
+├── index.tsx         # Dev server entry point (not exported)
+```
+
+### Entry Point
+
+The **published entry point** is `exports.ts` (at project root, NOT `src/index.tsx`). This file re-exports everything consumers can import. `src/index.tsx` is only for local dev/preview via `react-scripts start`.
+
+When adding new exports, **always add them to `exports.ts`** — otherwise consumers cannot access them.
+
+### Key Technology Stack
+
+- **React 18** with TypeScript
+- **MUI v7** (`@mui/material`, `@mui/icons-material`, `@mui/lab`, `@mui/x-date-pickers`)
+- **Emotion** (`@emotion/react`, `@emotion/styled`) — MUI's styling engine
+- **styled-components** — also present for legacy styled components
+- **react-hook-form** + **yup** — form state and validation
+- **react-query v3** — server state management
+- **react-table v7** — table components
+- **Pullstate** — lightweight global state
+- **Axios** — HTTP client
+- **react-router-dom v6** — routing utilities
+- **react-toastify** — toast notifications
+- **Moment.js** — date handling
+- **Fuse.js** — fuzzy search
+- **Storybook 6** — component documentation (dev only)
+
+## Key Commands
+
+| Command | Purpose |
+|---------|---------|
+| `yarn start` / `yarn dev` | Start local dev server (CRA, port 3000) for previewing components |
+| `yarn build` | Production build (`CI=false && react-scripts build`) |
+| `yarn test` | Run tests via react-scripts |
+| `yarn lint` | ESLint check across all src files |
+| `yarn lint:fix` | Auto-fix lint issues |
+| `yarn format` | Prettier format all source files |
+| `yarn storybook` | Start Storybook on port 6006 |
+| `yarn build-storybook` | Build static Storybook site |
+
+### Local Linking Workflow (yalc)
+
+This is a **library package** — it is not deployed standalone. To test changes in a consuming app:
+
+1. **In this repo**: make changes, then run:
+   ```bash
+   yalc push
+   ```
+2. **In the consuming repo** (e.g., `campx-common-workspace`):
+   ```bash
+   yalc add @campxdev/shared
+   yarn install
+   ```
+3. After iterating, repeat `yalc push` — consuming repos with `yalc link` will auto-update.
+4. **Before committing** in the consuming repo, remove yalc link:
+   ```bash
+   yalc remove @campxdev/shared
+   yarn install
+   ```
+
+> **Note**: The `CI=false` in the build script suppresses treating warnings as errors. This is intentional for CRA builds.
+
+## Exports
+
+The `exports.ts` file is the source of truth. Exports are organized by category:
+
+### Components (`src/components/`)
+
+The largest export surface. Key component groups:
+
+- **Layout & Navigation**: `PageHeader`, `PageContent`, `Breadcrumbs`, `Layout/*`, `Tabs/*`, `StepsHeader/*`
+- **Forms**: `HookForm/*` (react-hook-form wrappers), `Form/*`, `Input/*`, `Selectors/*`, `ImageUpload`, `ExcelToJsonInput/*`
+- **Tables**: `Table`, `Tables/*`, `StyledTableContainer`, `CustomizeReport/*`
+- **Feedback**: `Spinner`, `FullScreenLoader`, `LinearProgress`, `ErrorBox`, `ErrorModal`, `ErrorModalWrapper/*`, `ErrorBoundary/*`, `NoDataIllustration`
+- **Overlays**: `DrawerWrapper/*`, `PopupConfirm/*`, `UploadFileDialog/*`, `ModalButtons/*`
+- **Data Display**: `Card`, `CardsGrid`, `Detail`, `DetailsGrid`, `LabelValue`, `JsonPreview`, `Chips`, `IconLabel`
+- **Actions**: `ActionButton`, `IconButtons/*`, `DropDownButton/*`, `UploadButton/*`, `SwitchButton`, `ListItemButton`
+- **Domain-specific**: `StudentCard/*`, `FeeCard`, `LoginForm`, `ChangePassword`, `ResetPassword`, `MyProfile/*`, `ActiveDevices/*`, `ActivityLog/*`, `ApplicationProfile/*`, `MongoCharts/*`, `Institutions/*`, `DatabaseConfiguration/*`
+- **Misc**: `Attachment`, `FloatingContainer`, `DividerHeading`, `ReportHeader`, `SignatureFooter`, `ReactJoyRide`, `ToastContainer/*`, `MediaRow/*`, `AutocompleteSearch/*`, `FilterComponents/*`
+
+### Hooks (`src/hooks/`)
+
+Custom hooks for common patterns — data fetching wrappers, form utilities, UI state, permissions checks, etc.
+
+### Utilities (`src/utils/`)
+
+Helper functions: formatters (dates, currency, names), validators, file handling, API helpers, permission checks, etc.
+
+### Contexts (`src/contexts/`)
+
+React context providers for auth state, tenant info, app-level configuration that wraps consuming apps.
+
+### Shared State (`src/shared-state/`)
+
+Pullstate stores shared across the app — user state, UI state, notifications, etc.
+
+### Theme (`src/theme/`)
+
+MUI theme object, palette definitions, typography overrides, component style overrides. Consumers wrap their app with this theme.
+
+### Permissions (`src/permissions/`)
+
+Permission constants and helper utilities for role-based access control across the CampX platform.
+
+### Config (`src/config/`)
+
+Axios instance configuration, API base URL setup, app-level config constants.
+
+### Constants (`src/constants/`)
+
+Shared enums, magic strings, configuration constants used across multiple frontend apps.
+
+### Sitemap (`src/sitemap/`)
+
+Route definitions and navigation structure shared across microfrontends.
+
+## Versioning
+
+- **Current version**: 3.1.23
+- **Semver conventions**:
+  - **Patch** (3.1.x): Bug fixes, style tweaks, non-breaking additions
+  - **Minor** (3.x.0): New components, new hooks, new exports (backward-compatible)
+  - **Major** (x.0.0): Breaking changes to existing component APIs, removed exports, theme changes that affect all consumers
+- **Bump version** in `package.json` before publishing
+- **Publishing**: Handled via CI/GitHub Actions — do not publish manually to npm
+
+### Breaking Change Considerations
+
+Since 27+ microfrontends consume this package, **breaking changes are high-impact**:
+- Never rename or remove an exported component/hook/utility without coordinating migration across all consumers
+- Never change component prop interfaces in a breaking way without a major version bump
+- Prefer adding new props with defaults over modifying existing behavior
+- Deprecate before removing — add console warnings in the interim
+
+## Consuming Repo Conventions
+
+Patterns that consuming repos follow (and that this package must support):
+
+- **Imports**: Consumers import directly from the package name:
+  ```tsx
+  import { PageHeader, useAuth, formatDate } from '@campxdev/shared'
+  ```
+- **Theme**: Consumers wrap their app with the theme provider exported from this package
+- **Axios**: Consumers may use the Axios instance from this package's config or from `@campxdev/campx-web-utils`
+- **react-hook-form**: Form components expect react-hook-form v7 context. Consumers use `useForm` from react-hook-form and pass `control`/`register` to shared form components
+- **react-query v3**: Hooks that use react-query expect a `QueryClientProvider` in the consumer's tree
+- **react-router-dom v6**: Components that use routing (Breadcrumbs, Layout, etc.) expect a v6 router context
+- **MUI v7**: Consumers must have compatible MUI v7 peer dependencies
+- **Multi-tenancy**: All API-calling utilities must respect tenant context. Never hardcode tenant-specific values
+- **Pullstate**: Consumers share Pullstate stores exported from this package for cross-cutting concerns (user state, etc.)
+
+## Code Style
+
+- **TypeScript** throughout — avoid `any` types; prefer explicit interfaces
+- **ESLint + Prettier** configured — run `yarn lint:fix` and `yarn format` before committing
+- **Prettier config**: `.prettierrc` at project root
+- **Component pattern**: Functional components with hooks, no class components
+- **Styling**: Prefer MUI `sx` prop or Emotion `styled()`. styled-components exists but is legacy — prefer Emotion for new code
+
+## Storybook
+
+Storybook is available for component documentation and visual testing:
+- `yarn storybook` — starts on port 6006
+- Stories live in `src/stories/`
+- Uses `storybook-addon-react-router-v6` for components requiring router context
+- `cross-env NODE_OPTIONS=--openssl-legacy-provider` is needed for the build due to Storybook 6 + Node 18+ compatibility
+
+## Last Updated
+
+2026-03-13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@campxdev/shared",
-  "version": "3.1.23",
+  "version": "3.1.24-alpha.2",
   "main": "./exports.ts",
   "scripts": {
     "start": "react-scripts start",
@@ -36,6 +36,7 @@
     "@mui/material": "^7.0.2",
     "@mui/x-date-pickers": "^8.1.0",
     "axios": "^1.7.2",
+    "crypto-js": "^4.2.0",
     "device-detector-js": "^3.0.3",
     "fuse.js": "^6.6.2",
     "js-cookie": "^3.0.5",
@@ -69,6 +70,7 @@
     "@storybook/preset-create-react-app": "^4.0.0",
     "@storybook/react": "^6.5.14",
     "@storybook/testing-library": "^0.0.13",
+    "@types/crypto-js": "^4.2.2",
     "@types/js-cookie": "^3.0.6",
     "@types/node": "^18.11.8",
     "@types/react": "^18.3.3",

package/src/config/axios.ts

@@ -2,6 +2,7 @@ import Axios, { InternalAxiosRequestConfig } from 'axios'
 import Cookies from 'js-cookie'
 import { toast } from 'react-toastify'
 import { NetworkStore } from '../components/ErrorBoundary/GlobalNetworkLoadingIndicator'
+import { generateClientToken } from '../utils/clientAuthToken'
 
 // Declare the extended axios types to include our custom property
 declare module 'axios' {
@@ -95,6 +96,16 @@ axios.interceptors.request.use(
       config.headers.set('campx_open_payments_key', openPaymentsKey)
     }
 
+    // Inject client authentication token
+    const campxClientId = process.env.REACT_APP_CLIENT_ID
+    const campxClientSecret = process.env.REACT_APP_CAMPX_CLIENT_SECRET
+    if (campxClientId && campxClientSecret) {
+      config.headers.set(
+        'x-campx-client',
+        generateClientToken(campxClientId, campxClientSecret),
+      )
+    }
+
     return {
       ...config,
       params,
@@ -138,7 +149,7 @@ export const axiosErrorToast = (error: any, fallback?: string) => {
   const fallbackMessage = fallback ?? 'Something went wrong.'
   const errorMessage =
     typeof error?.response?.data?.message !== 'string'
-      ? (error?.response?.data?.message?.join('\n') ?? fallbackMessage)
+      ? error?.response?.data?.message?.join('\n') ?? fallbackMessage
       : error?.response?.data?.message
 
   return toast.error(errorMessage)

package/src/config/axiosEvaluator.ts

@@ -1,7 +1,7 @@
 import Axios from 'axios'
 import Cookies from 'js-cookie'
 import { NetworkStore } from '../components/ErrorBoundary/GlobalNetworkLoadingIndicator'
-import { isDevelopment } from '../constants'
+import { generateClientToken } from '../utils/clientAuthToken'
 import { formatParams } from './axios'
 
 // const sessionKey = Cookies.get('campx_session_key')
@@ -25,6 +25,15 @@ axiosEvaluator.interceptors.request.use(
     NetworkStore.update((s) => {
       s.loading = true
     })
+    // Inject client authentication token
+    const campxClientId = process.env.REACT_APP_CLIENT_ID
+    const campxClientSecret = process.env.REACT_APP_CAMPX_CLIENT_SECRET
+    if (campxClientId && campxClientSecret) {
+      config.headers.set(
+        'x-campx-client',
+        generateClientToken(campxClientId, campxClientSecret),
+      )
+    }
     return { ...config, params }
   },
   function (error) {

package/src/config/axiosXTenant.ts

@@ -2,6 +2,7 @@ import Axios from 'axios'
 import Cookies from 'js-cookie'
 import { NetworkStore } from '../components/ErrorBoundary/GlobalNetworkLoadingIndicator'
 import { isDevelopment } from '../constants'
+import { generateClientToken } from '../utils/clientAuthToken'
 import { formatParams } from './axios'
 
 const sessionKey = Cookies.get('campx_session_key')
@@ -33,6 +34,15 @@ axiosTenant.interceptors.request.use(
     NetworkStore.update((s) => {
       s.loading = true
     })
+    // Inject client authentication token
+    const campxClientId = process.env.REACT_APP_CLIENT_ID
+    const campxClientSecret = process.env.REACT_APP_CAMPX_CLIENT_SECRET
+    if (campxClientId && campxClientSecret) {
+      config.headers.set(
+        'x-campx-client',
+        generateClientToken(campxClientId, campxClientSecret),
+      )
+    }
     return { ...config, params }
   },
   function (error) {

package/src/utils/clientAuthToken.ts

@@ -0,0 +1,17 @@
+import CryptoJS from 'crypto-js'
+
+function toBase64Url(base64: string): string {
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
+export function generateClientToken(clientId: string, secret: string): string {
+  const payload = { clientId, iat: Math.floor(Date.now() / 1000) }
+  const payloadBase64url = toBase64Url(btoa(JSON.stringify(payload)))
+
+  const signatureWordArray = CryptoJS.HmacSHA256(payloadBase64url, secret)
+  const signatureBase64url = toBase64Url(
+    CryptoJS.enc.Base64.stringify(signatureWordArray),
+  )
+
+  return `${payloadBase64url}.${signatureBase64url}`
+}