igloo-d2c-components 1.0.6 → 1.0.7

package/README.md

@@ -1,91 +1,336 @@
 # D2C Component Library
-Reusable React component library with tenant-aware theming for B2C applications.
+
+Reusable React component library with **centralized tenant themes** and tenant-aware theming for B2C applications.
+
+## 📋 Table of Contents
+
+- [Overview](#-overview)
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Centralized Themes](#-centralized-themes)
+- [Components](#-components)
+- [Hooks & Utilities](#-hooks--utilities)
+- [Development](#-development)
+- [Publishing](#-publishing)
+- [Storybook](#-storybook)
+- [Technical Details](#-technical-details)
+- [Troubleshooting](#-troubleshooting)
+- [Contributing](#-contributing)
+
+---
+
+## 🎯 Overview
+
+The D2C Component Library provides reusable, tenant-aware UI components with **centralized theme management**. All tenant themes are defined in one place, ensuring consistency across all applications.
+
+### Key Highlights
+
+- 🎨 **Centralized Themes** - All tenant themes (Igloo, CIMB, AmmetLife) in one library
+- 🧩 **Tenant-Aware Components** - Automatically adapt to tenant branding
+- 📦 **ES2015 Compatible** - Works with older webpack configurations
+- 🔧 **Unminified Output** - Better debugging and tree-shaking
+- 📖 **Full TypeScript Support** - Complete type definitions
+- ⚡ **Tree-Shakeable** - Import only what you need
+
+---
+
+## ✨ Features
+
+### Centralized Theme System
+
+- ✅ **Single source of truth** for all tenant themes
+- ✅ **Type-safe** theme access with TypeScript
+- ✅ **Dynamic theme loading** with `getTenantTheme()`
+- ✅ **~585 lines of code removed** from consuming apps
+- ✅ **Easy to maintain** - update once, reflects everywhere
+
+### Available Themes
+
+| Tenant | Theme Export | Description |
+|--------|-------------|-------------|
+| **Igloo** | `iglooTheme` | Default insurance brand |
+| **CIMB** | `cimbTheme` | Banking partner theme |
+| **AmmetLife** | `ammetlifeTheme` | Life insurance partner |
+
+### Components
+
+- **Button** - Tenant-themed button component
+- **Card** - Card with tenant accent border
+- **Banner** - Promotional banner with gradients
+
+### Hooks
+
+- `useTenantTheme()` - Access tenant theme and ID
+- `useTenantId()` - Get current tenant ID
+- `useIsTenant()` - Check tenant match
+
+### Utilities
+
+- `getTenantTheme()` - Get theme by tenant ID
+- `isValidTenantId()` - Validate tenant ID
+- `getThemeColor()` - Extract colors from theme
+- `createThemeCSSVariables()` - Generate CSS variables
+
+---
 
 ## 📦 Installation
 
-### For Local Development (npm link)
+### Option 1: Local Development (Recommended for Development)
+
+Perfect for active development when working on the library.
 
 ```bash
-# In d2c-component-library directory
+# 1. Build the library
+cd /path/to/d2c-component-library
 yarn install
 yarn build
-yarn link
 
-# In b2c-web-demo directory
-yarn link "igloo-d2c-components"
+# 2. In consuming app (b2c-web-demo)
+cd /path/to/b2c-web-demo
+
+# Add to package.json:
+{
+  "dependencies": {
+    "igloo-d2c-components": "file:../d2c-component-library"
+  }
+}
+
+# Install
+yarn install
 ```
 
-### For Production (npm package)
+**Workflow:**
+```bash
+# Make changes to library
+cd d2c-component-library
+# ... edit files ...
+yarn build
+
+# Update consuming app
+cd ../b2c-web-demo
+yarn install  # Copies updated build
+```
+
+### Option 2: NPM Registry (Production)
+
+For production deployments and CI/CD.
 
+**Install:**
 ```bash
 yarn add igloo-d2c-components
 # or
 npm install igloo-d2c-components
 ```
 
+**Configure authentication (if using private registry):**
+```bash
+# For npm
+export NPM_AUTH_TOKEN="your-npm-token"
+
+# For GitLab Package Registry
+export GITLAB_NPM_TOKEN="glpat-your-token"
+```
+
+---
+
 ## 🚀 Quick Start
 
-### 1. Wrap your app with TenantThemeProvider
+### 1. Import Pre-built Themes (Recommended)
 
 ```tsx
-import { TenantThemeProvider } from 'igloo-d2c-components'
-
-const tenantTheme = {
- palette: {
-  primary: {
-   main: '#5656F6',
-   dark: '#1300A9',
-   light: '#8183FF',
-  },
-  secondary: {
-   main: '#FF7D7D',
-   light: '#FFB3B1',
-  },
- },
- typography: {
-  fontFamily: '"Manrope", "Roboto", sans-serif',
- },
-}
+import {
+  TenantThemeProvider,
+  iglooTheme,
+  cimbTheme,
+  ammetlifeTheme
+} from 'igloo-d2c-components'
 
 function App() {
- return (
-  <TenantThemeProvider tenantId="igloo" theme={tenantTheme}>
-   <YourApp />
-  </TenantThemeProvider>
- )
+  return (
+    <TenantThemeProvider tenantId="igloo" theme={iglooTheme}>
+      <YourApp />
+    </TenantThemeProvider>
+  )
+}
+```
+
+### 2. Dynamic Theme Loading
+
+```tsx
+import { TenantThemeProvider, getTenantTheme } from 'igloo-d2c-components'
+
+function App({ tenantId }) {
+  const theme = getTenantTheme(tenantId) // 'igloo', 'cimb', or 'ammetlife'
+
+  return (
+    <TenantThemeProvider tenantId={tenantId} theme={theme}>
+      <YourApp />
+    </TenantThemeProvider>
+  )
 }
 ```
 
-### 2. Use Components
+### 3. Use Components
 
 ```tsx
 import { Button, Card, Banner } from 'igloo-d2c-components'
 
 function MyPage() {
- return (
-  <div>
-   {/* Tenant-themed button */}
-   <Button tenantColored>Click Me</Button>
-
-   {/* Tenant-themed card */}
-   <Card
-    title="My Card"
-    content="Card content"
-    tenantAccent
-   />
-
-   {/* Tenant-themed banner */}
-   <Banner
-    title="Welcome"
-    description="Get started today"
-    gradient
-   />
-  </div>
- )
+  return (
+    <div>
+      {/* Tenant-themed button */}
+      <Button tenantColored variant="contained">
+        Click Me
+      </Button>
+
+      {/* Tenant-themed card */}
+      <Card
+        title="My Card"
+        content="Card content"
+        tenantAccent
+      />
+
+      {/* Tenant-themed banner */}
+      <Banner
+        title="Welcome"
+        description="Get started today"
+        gradient
+      />
+    </div>
+  )
+}
+```
+
+---
+
+## 🎨 Centralized Themes
+
+### Why Centralized Themes?
+
+**Before** (❌ Old Way):
+```typescript
+// In each consuming app - duplicated code
+const iglooTheme = {
+  palette: {
+    primary: { main: '#5656F6', dark: '#1300A9', ... },
+    // ... 60+ lines per tenant
+  }
+}
+```
+
+**After** (✅ New Way):
+```typescript
+// Import from library - single source of truth
+import { iglooTheme } from 'igloo-d2c-components'
+```
+
+### Available Theme Exports
+
+```typescript
+import {
+  // Individual themes
+  iglooTheme,      // Igloo brand theme
+  cimbTheme,       // CIMB bank theme
+  ammetlifeTheme,  // AmmetLife insurance theme
+
+  // Theme registry
+  tenantThemes,    // { igloo: iglooTheme, cimb: cimbTheme, ... }
+
+  // Utility functions
+  getTenantTheme,  // (tenantId: TenantId) => TenantThemeConfig
+  isValidTenantId, // (id: string) => boolean
+  getAvailableTenants, // () => TenantId[]
+} from 'igloo-d2c-components'
+```
+
+### Theme Structure
+
+Each theme includes:
+
+```typescript
+interface TenantThemeConfig {
+  palette: {
+    // Core palettes
+    primary: { main, dark, light, bright, plain, border }
+    secondary: { dim, dark, main, bright, mediumBright, light, lighter }
+    tertiary: { dim, dark, main, light, bright }
+    natural: { dim, dark, main, light, bright, granite }
+
+    // Product-specific colors
+    motor: { main, light, bright }
+    car: { main, light, darkAI }
+    travel: { main, light }
+    health: { main, light? }
+    life: { main, light }
+    pet: { main }
+
+    // CIMB-specific (optional)
+    paCimb?: { main, light, bright, buttonBg }
+  }
+  typography: {
+    fontFamily: string
+  }
+  logo: string
+  favicon: string
+}
+```
+
+### Using Themes
+
+**In Tenant Configuration:**
+```typescript
+// config/tenants/igloo.ts
+import { iglooTheme } from 'igloo-d2c-components'
+
+const iglooConfig: TenantConfig = {
+  id: 'igloo',
+  theme: iglooTheme, // ✨ That's it!
+  // ... other config
+}
+```
+
+**Dynamic Loading:**
+```typescript
+import { getTenantTheme, isValidTenantId } from 'igloo-d2c-components'
+
+function loadTheme(tenantId: string) {
+  if (isValidTenantId(tenantId)) {
+    return getTenantTheme(tenantId)
+  }
+  throw new Error(`Invalid tenant: ${tenantId}`)
+}
+```
+
+**In Components:**
+```typescript
+import { useTenantTheme } from 'igloo-d2c-components'
+
+function MyComponent() {
+  const { theme, tenantId } = useTenantTheme()
+
+  return (
+    <div style={{
+      backgroundColor: theme.palette.primary.main,
+      color: theme.palette.primary.bright
+    }}>
+      Current tenant: {tenantId}
+    </div>
+  )
 }
 ```
 
-## 📚 Available Components
+### Theme Benefits
+
+- ✅ **Single source of truth** - Update in one place
+- ✅ **Type-safe** - Full TypeScript support
+- ✅ **Consistent** - Same themes across all apps
+- ✅ **Maintainable** - Easy to update and extend
+- ✅ **Scalable** - Add new tenants easily
+
+---
+
+## 📚 Components
 
 ### Button
 
@@ -94,17 +339,18 @@ Tenant-aware button component based on MUI Button.
 ```tsx
 import { Button } from 'igloo-d2c-components'
 
+// Tenant-colored button
 <Button tenantColored variant="contained">
- Tenant Colored Button
+  Tenant Colored Button
 </Button>
 
-<Button color="primary">
- Default MUI Button
+// Standard MUI button
+<Button color="primary" variant="outlined">
+  Default Button
 </Button>
 ```
 
 **Props:**
-
 - `tenantColored?: boolean` - Use tenant primary color
 - `variant?: 'text' | 'outlined' | 'contained'` - Button variant
 - All MUI ButtonProps
@@ -117,19 +363,19 @@ Tenant-aware card component based on MUI Card.
 import { Card } from 'igloo-d2c-components'
 
 <Card
- title="Card Title"
- content="Card content goes here"
- actions={<Button>Action</Button>}
- tenantAccent
+  title="Card Title"
+  content="Card content goes here"
+  actions={<Button>Action</Button>}
+  tenantAccent
 />
 ```
 
 **Props:**
-
 - `title?: React.ReactNode` - Card title
 - `content?: React.ReactNode` - Card content
 - `actions?: React.ReactNode` - Card actions
 - `tenantAccent?: boolean` - Add tenant-colored top border
+- `headerAction?: React.ReactNode` - Action in header
 - All MUI CardProps
 
 ### Banner
@@ -140,39 +386,42 @@ Promotional banner with tenant theming.
 import { Banner } from 'igloo-d2c-components'
 
 <Banner
- title="Special Offer"
- description="Limited time only"
- action={<Button>Learn More</Button>}
- gradient
+  title="Special Offer"
+  description="Limited time only"
+  action={<Button>Learn More</Button>}
+  gradient
 />
 ```
 
 **Props:**
-
-- `title: string` - Banner title
+- `title: string` - Banner title (required)
 - `description?: string` - Banner description
 - `action?: React.ReactNode` - Action button/element
-- `gradient?: boolean` - Use gradient background
+- `gradient?: boolean` - Use gradient background (default: true)
 - All MUI BoxProps
 
+---
+
 ## 🎨 Hooks & Utilities
 
-### useTenantTheme
+### Hooks
+
+#### useTenantTheme()
 
-Access tenant theme configuration.
+Access tenant theme configuration and ID.
 
 ```tsx
 import { useTenantTheme } from 'igloo-d2c-components'
 
 function MyComponent() {
- const { theme, tenantId } = useTenantTheme()
- const primaryColor = theme.palette.primary?.main
+  const { theme, tenantId } = useTenantTheme()
+  const primaryColor = theme.palette.primary.main
 
- return <div style={{ color: primaryColor }}>...</div>
+  return <div style={{ color: primaryColor }}>...</div>
 }
 ```
 
-### useTenantId
+#### useTenantId()
 
 Get current tenant ID.
 
@@ -180,12 +429,12 @@ Get current tenant ID.
 import { useTenantId } from 'igloo-d2c-components'
 
 function MyComponent() {
- const tenantId = useTenantId()
- return <div>Current tenant: {tenantId}</div>
+  const tenantId = useTenantId() // 'igloo' | 'cimb' | 'ammetlife'
+  return <div>Current tenant: {tenantId}</div>
 }
 ```
 
-### useIsTenant
+#### useIsTenant()
 
 Check if current tenant matches a specific ID.
 
@@ -193,140 +442,732 @@ Check if current tenant matches a specific ID.
 import { useIsTenant } from 'igloo-d2c-components'
 
 function MyComponent() {
- const isCIMB = useIsTenant('cimb')
+  const isCIMB = useIsTenant('cimb')
 
- if (isCIMB) {
-  return <CIMBSpecificFeature />
- }
+  if (isCIMB) {
+    return <CIMBSpecificFeature />
+  }
 
- return <DefaultFeature />
+  return <DefaultFeature />
 }
 ```
 
-### getThemeColor
+### Utility Functions
 
-Utility to get color from theme palette.
+#### getTenantTheme()
+
+Get theme configuration by tenant ID.
 
 ```tsx
-import { getThemeColor } from 'igloo-d2c-components'
+import { getTenantTheme } from 'igloo-d2c-components'
 
-const primaryColor = getThemeColor(theme, 'primary.main', '#000000')
+const theme = getTenantTheme('igloo')
+console.log(theme.palette.primary.main) // '#5656F6'
 ```
 
-## 🏗️ Tech Stack
+**Throws:** Error if tenant ID is invalid
 
-- **React 17** - UI library
-- **TypeScript 4.9+** - Type safety
-- **MUI 5** - Material-UI components
-- **Emotion** - CSS-in-JS
-- **Rollup** - Build tooling
+#### isValidTenantId()
 
-## 📖 TypeScript Support
+Type guard to check if a string is a valid tenant ID.
 
-Full TypeScript support with type definitions included.
+```tsx
+import { isValidTenantId } from 'igloo-d2c-components'
+
+if (isValidTenantId(userInput)) {
+  const theme = getTenantTheme(userInput) // Type-safe!
+}
+```
+
+#### getAvailableTenants()
+
+Get list of all available tenant IDs.
 
 ```tsx
-import type { ButtonProps, CardProps, TenantThemeConfig } from 'igloo-d2c-components'
+import { getAvailableTenants } from 'igloo-d2c-components'
+
+const tenants = getAvailableTenants()
+// ['igloo', 'cimb', 'ammetlife']
 ```
 
+#### getThemeColor()
+
+Extract color from theme using dot notation.
+
+```tsx
+import { getThemeColor } from 'igloo-d2c-components'
+
+const color = getThemeColor(theme, 'primary.main', '#000')
+// Returns theme.palette.primary.main or '#000' if not found
+```
+
+#### createThemeCSSVariables()
+
+Create CSS variables from theme.
+
+```tsx
+import { createThemeCSSVariables } from 'igloo-d2c-components'
+
+const vars = createThemeCSSVariables(theme, '--my-app')
+// { '--my-app-primary-main': '#5656F6', ... }
+```
+
+---
+
 ## 🔧 Development
 
-### Build the library
+### Prerequisites
 
+- **Node.js**: `>=16.20.0 <=18.x`
+- **Yarn**: `^1.22.0` (recommended) or npm
+
+Check your version:
 ```bash
-# Development mode (watch)
-yarn dev
+node --version  # Should be 16.20.0 - 18.x
+yarn --version  # Should be 1.22.x
+```
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://gitlab.iglooinsure.com/axinan/fe/d2c-component-library.git
+cd d2c-component-library
+
+# Install dependencies
+yarn install
+```
 
+### Build Commands
+
+```bash
 # Production build
 yarn build
+
+# Development mode (watch)
+yarn dev
+
+# Clean build artifacts
+yarn clean
+
+# Clean and rebuild
+yarn clean && yarn build
 ```
 
-### Lint code
+### Code Quality
 
 ```bash
+# Lint code
 yarn lint
+
+# Type check
+yarn type-check
 ```
 
-### Type check
+### Build Output
+
+The library outputs **unminified** code targeting **ES2015** for maximum compatibility:
 
+```
+dist/
+├── cjs/
+│   ├── index.js          # CommonJS bundle (unminified, ES2015)
+│   └── index.js.map      # Source map
+├── esm/
+│   ├── index.js          # ES Module bundle (unminified, ES2015)
+│   └── index.js.map      # Source map
+└── types/
+    └── index.d.ts        # TypeScript definitions
+```
+
+**Why unminified?**
+- ✅ Consuming apps handle minification
+- ✅ Better debugging experience
+- ✅ Better tree-shaking
+- ✅ No impact on final bundle size
+
+**Why ES2015?**
+- ✅ Maximum compatibility with older webpack configs
+- ✅ No babel-loader required in consuming apps
+- ✅ Optional chaining (`?.`) transpiled to verbose checks
+- ✅ Works with webpack 4+
+
+### Project Structure
+
+```
+d2c-component-library/
+├── src/
+│   ├── components/          # Component implementations
+│   │   ├── Button/
+│   │   ├── Card/
+│   │   └── Banner/
+│   ├── context/
+│   │   └── TenantThemeContext.tsx
+│   ├── themes/
+│   │   └── index.ts        # ⭐ Centralized theme definitions
+│   ├── types/
+│   │   └── tenant.ts       # TypeScript types
+│   ├── utils/
+│   │   └── theme.ts        # Theme utilities
+│   └── index.ts            # Main exports
+├── dist/                    # Build output (generated)
+├── examples/
+│   └── usage-example.tsx
+├── .storybook/             # Storybook configuration
+├── rollup.config.cjs       # Rollup build config
+├── tsconfig.json           # TypeScript config
+├── package.json
+├── README.md               # This file
+└── CHANGELOG.md            # Version history
+```
+
+---
+
+## 📦 Publishing
+
+### Prerequisites
+
+1. **Ensure clean working directory:**
+   ```bash
+   git status  # Should be clean
+   ```
+
+2. **Update version in package.json:**
+   ```json
+   {
+     "version": "1.0.7"
+   }
+   ```
+
+3. **Update CHANGELOG.md:**
+   Document changes in the new version section
+
+4. **Build the library:**
+   ```bash
+   yarn build
+   ```
+
+### Publishing to NPM
+
+**Set up NPM token:**
 ```bash
-yarn type-check
+# Get token from https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+export NPM_AUTH_TOKEN="npm_your_actual_token"
+
+# Or add to ~/.npmrc globally
+//registry.npmjs.org/:_authToken=npm_your_token
+```
+
+**Publish:**
+```bash
+# Automated script with safety checks
+./publish-to-npm.sh
+
+# Or manual
+yarn build
+npm publish --access public
+```
+
+### Publishing to GitLab Package Registry
+
+**Set up GitLab token:**
+```bash
+# Get token from https://gitlab.com/-/profile/personal_access_tokens
+# Scopes: api, read_registry, write_registry
+export GITLAB_NPM_TOKEN="glpat-your-token"
+```
+
+**Configure `.npmrc` for GitLab:**
+```ini
+@igloo:registry=https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/
+//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
+```
+
+**Publish:**
+```bash
+yarn build
+npm publish
+```
+
+### CI/CD Publishing
+
+The library includes a GitLab CI/CD configuration (`.gitlab-ci.yml`) that automatically:
+
+1. **Runs on main branch** or tags
+2. **Lints and type-checks** code
+3. **Builds** the library
+4. **Publishes** to registry (if tag)
+
+**Trigger CI/CD publish:**
+```bash
+# Create and push a tag
+git tag v1.0.7
+git push origin v1.0.7
+```
+
+### Version Management
+
+**Semantic Versioning:**
+- **Major** (1.0.0 → 2.0.0): Breaking changes
+- **Minor** (1.0.0 → 1.1.0): New features, backwards compatible
+- **Patch** (1.0.0 → 1.0.1): Bug fixes
+
+**Update version:**
+```bash
+# Manually in package.json
+"version": "1.0.7"
+
+# Or using npm version
+npm version patch  # 1.0.6 → 1.0.7
+npm version minor  # 1.0.6 → 1.1.0
+npm version major  # 1.0.6 → 2.0.0
+```
+
+### Post-Publishing
+
+After publishing:
+
+1. **Tag the release:**
+   ```bash
+   git tag v1.0.7
+   git push origin v1.0.7
+   ```
+
+2. **Update consuming apps:**
+   ```bash
+   cd ../b2c-web-demo
+   yarn upgrade igloo-d2c-components@latest
+   ```
+
+3. **Announce the release** to the team
+
+---
+
+## 📖 Storybook
+
+The library includes Storybook for component documentation and testing.
+
+### Running Storybook
+
+```bash
+# Start Storybook dev server
+yarn storybook
+# Opens at http://localhost:6006
+
+# Build static Storybook
+yarn build-storybook
+# Output in storybook-static/
 ```
 
-## 📝 Usage in b2c-web-demo
+### Storybook Features
+
+- **Component Playground** - Interactive component testing
+- **Props Documentation** - Auto-generated from TypeScript
+- **Theme Switching** - Test with different tenant themes
+- **Responsive Design** - Test different viewports
+- **Accessibility** - Built-in a11y addon
+
+### Adding Stories
 
-### Integration Example
+Create a `.stories.tsx` file next to your component:
 
 ```tsx
-// In b2c-web-demo/src/layouts/index.tsx
-import { TenantThemeProvider } from 'igloo-d2c-components'
-import { getCurrentTenantConfig } from '@/config/tenants'
-
-function Layout({ children }) {
- const tenantConfig = getCurrentTenantConfig()
-
- return (
-  <TenantThemeProvider
-   tenantId={tenantConfig.id}
-   theme={{
-    palette: tenantConfig.theme.palette,
-    typography: tenantConfig.theme.typography,
-   }}
-  >
-   <ThemeProvider theme={muiTheme}>
-    {children}
-   </ThemeProvider>
-  </TenantThemeProvider>
- )
+// src/components/MyComponent/MyComponent.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { TenantThemeProvider, iglooTheme } from '../../index'
+import { MyComponent } from './MyComponent'
+
+const meta: Meta<typeof MyComponent> = {
+  title: 'Components/MyComponent',
+  component: MyComponent,
+  decorators: [
+    (Story) => (
+      <TenantThemeProvider tenantId="igloo" theme={iglooTheme}>
+        <Story />
+      </TenantThemeProvider>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof MyComponent>
+
+export const Default: Story = {
+  args: {
+    prop1: 'value1',
+  },
+}
+```
+
+---
+
+## 🔬 Technical Details
+
+### Build Configuration
+
+**Rollup Configuration** (`rollup.config.cjs`):
+```javascript
+{
+  input: 'src/index.ts',
+  output: [
+    {
+      file: 'dist/cjs/index.js',
+      format: 'cjs',
+      sourcemap: true,
+      exports: 'named',
+      banner: '"use client"',
+    },
+    {
+      file: 'dist/esm/index.js',
+      format: 'esm',
+      sourcemap: true,
+      exports: 'named',
+      banner: '"use client"',
+    },
+  ],
+  plugins: [
+    peerDepsExternal(),
+    resolve(),
+    commonjs(),
+    typescript({
+      tsconfig: './tsconfig.json',
+      compilerOptions: {
+        declaration: false,
+        target: 'ES2015', // For compatibility
+      },
+    }),
+    // NO terser() - libraries should not be minified
+  ],
 }
 ```
 
-### Using Components
+### TypeScript Configuration
+
+**Target:** ES2015 for maximum compatibility
+**Module:** ESNext for tree-shaking
+**Strict:** Enabled for type safety
+
+### Peer Dependencies
+
+```json
+{
+  "peerDependencies": {
+    "@emotion/react": "^11.11.4",
+    "@emotion/styled": "^11.11.5",
+    "@mui/icons-material": "^5.15.20",
+    "@mui/material": "^5.15.20",
+    "@mui/styles": "^5.15.20",
+    "react": "^17.0.0",
+    "react-dom": "^17.0.0"
+  }
+}
+```
 
-```tsx
-// In any component
-import { Button, Card, Banner } from 'igloo-d2c-components'
+### Package Exports
 
-function MyPage() {
- return (
-  <>
-   <Banner
-    title="Welcome to Insurance"
-    description="Find the best deals"
-    action={<Button tenantColored>Get Quote</Button>}
-    gradient
-   />
-
-   <Card
-    title="Popular Plans"
-    content="View our most popular insurance plans"
-    tenantAccent
-   />
-  </>
- )
+```json
+{
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "files": ["dist", "README.md"]
+}
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Webpack Module Parse Error
+
+**Error:**
+```
+Module parse failed: Unexpected token
+```
+
+**Cause:** Webpack can't parse the library output.
+
+**Solution:**
+
+1. **Check library build target:** The library should be built with ES2015 target (✅ already configured)
+2. **Rebuild library:**
+   ```bash
+   cd d2c-component-library
+   yarn clean && yarn build
+   ```
+3. **Reinstall in consuming app:**
+   ```bash
+   cd ../b2c-web-demo
+   rm -rf node_modules/igloo-d2c-components
+   yarn install
+   ```
+
+**Prevention:** The library is configured to output ES2015 JavaScript which is compatible with webpack 4+. Modern syntax like optional chaining (`?.`) is transpiled to verbose null checks.
+
+### Theme Not Found Error
+
+**Error:**
+```
+Theme not found for tenant: xxx
+```
+
+**Solution:** Use valid tenant IDs: `'igloo'`, `'cimb'`, or `'ammetlife'`.
+
+```typescript
+import { isValidTenantId, getTenantTheme } from 'igloo-d2c-components'
+
+if (isValidTenantId(tenantId)) {
+  const theme = getTenantTheme(tenantId)
+} else {
+  console.error('Invalid tenant ID:', tenantId)
 }
 ```
 
+### TypeScript Errors with Imports
+
+**Error:**
+```
+Module '"igloo-d2c-components"' has no exported member 'iglooTheme'
+```
+
+**Solution:**
+
+1. **Rebuild the library:**
+   ```bash
+   cd d2c-component-library
+   yarn build
+   ```
+
+2. **Reinstall in consuming app:**
+   ```bash
+   cd ../b2c-web-demo
+   yarn remove igloo-d2c-components
+   yarn add igloo-d2c-components@file:../d2c-component-library
+   ```
+
+3. **Restart TypeScript server** in your IDE:
+   - VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"
+
+### Build Failures
+
+**Error:** Build fails with memory issues
+
+**Solution:**
+```bash
+export NODE_OPTIONS="--max-old-space-size=4096"
+yarn build
+```
+
+**Error:** Type errors during build
+
+**Solution:**
+```bash
+# Check types first
+yarn type-check
+
+# Fix any type errors, then build
+yarn build
+```
+
+### Missing Peer Dependencies
+
+**Warning:** `peer dependency "react" not installed`
+
+**Solution:** Install peer dependencies in consuming app:
+```bash
+yarn add react@17 react-dom@17 @mui/material@5 @emotion/react @emotion/styled
+```
+
+---
+
 ## 🎯 Best Practices
 
-1. **Always wrap with TenantThemeProvider** - Required for tenant theming to work
-2. **Use tenantColored prop** - For components that should follow tenant branding
-3. **Maintain type safety** - Use TypeScript types provided by the library
-4. **Extend cautiously** - Extend components via composition, not modification
+### For Library Development
+
+1. **Always build before testing** - Run `yarn build` after changes
+2. **Use ES2015 features** - Avoid ES2020+ syntax
+3. **Test in consuming apps** - Test changes in b2c-web-demo
+4. **Update CHANGELOG** - Document all changes
+5. **Version appropriately** - Follow semantic versioning
+
+### For Library Usage
+
+1. **Wrap with TenantThemeProvider** - Required for theming to work
+2. **Use pre-built themes** - Import `iglooTheme`, `cimbTheme`, `ammetlifeTheme`
+3. **Use tenantColored prop** - For tenant-specific styling
+4. **Maintain type safety** - Use provided TypeScript types
+5. **Extend via composition** - Don't modify library components
+
+### For Theme Management
+
+1. **Update themes in library** - Not in consuming apps
+2. **Test all tenants** - When changing theme structure
+3. **Document breaking changes** - If theme interface changes
+4. **Version bump** - Increment version after theme changes
+
+---
+
+## 🤝 Contributing
+
+### Getting Started
+
+1. **Fork the repository**
+2. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+3. **Make your changes**
+4. **Test thoroughly:**
+   ```bash
+   yarn lint
+   yarn type-check
+   yarn build
+   ```
+5. **Test in consuming app:**
+   ```bash
+   cd ../b2c-web-demo
+   yarn install
+   yarn start-igloo-dev
+   ```
+6. **Commit your changes:**
+   ```bash
+   git commit -m "feat: add new feature"
+   ```
+7. **Push to branch:**
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+8. **Create a Pull Request**
+
+### Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting)
+- `refactor`: Code refactoring
+- `test`: Test additions/changes
+- `chore`: Maintenance tasks
+
+**Examples:**
+```
+feat(themes): add new tenant theme
+fix(Button): correct hover state color
+docs: update installation guide
+chore: bump version to 1.0.7
+```
+
+### Adding a New Tenant
+
+1. **Add theme to `src/themes/index.ts`:**
+   ```typescript
+   export const newTenantTheme: TenantThemeConfig = {
+     palette: { /* ... */ },
+     typography: { /* ... */ },
+     logo: '/assets/new-tenant/logo.svg',
+     favicon: 'https://...',
+   }
+
+   export const tenantThemes: Record<TenantId, TenantThemeConfig> = {
+     igloo: iglooTheme,
+     cimb: cimbTheme,
+     ammetlife: ammetlifeTheme,
+     newtenant: newTenantTheme, // Add here
+   }
+   ```
+
+2. **Update TenantId type in `src/types/tenant.ts`:**
+   ```typescript
+   export type TenantId = 'igloo' | 'cimb' | 'ammetlife' | 'newtenant'
+   ```
+
+3. **Build and test:**
+   ```bash
+   yarn build
+   cd ../b2c-web-demo
+   yarn install
+   ```
+
+4. **Update documentation and CHANGELOG**
+
+---
 
 ## 📄 License
 
 MIT
 
-## 🤝 Contributing
+---
+
+## 👥 Team
+
+Frontend Engineering Team - Axinan/Igloo
+
+---
+
+## 🔗 Links
+
+- **Repository:** https://gitlab.iglooinsure.com/axinan/fe/d2c-component-library
+- **NPM Package:** https://www.npmjs.com/package/igloo-d2c-components
+- **Consuming App:** https://gitlab.iglooinsure.com/axinan/fe/b2c-web-demo
+- **Issue Tracker:** https://gitlab.iglooinsure.com/axinan/fe/d2c-component-library/-/issues
 
-1. Create feature branch
-2. Make changes
-3. Run `yarn build` and `yarn lint`
-4. Test in b2c-web-demo using `yarn link`
-5. Submit PR
+---
+
+## 📝 Quick Reference
+
+### Installation
+```bash
+# Local development
+yarn add igloo-d2c-components@file:../d2c-component-library
+
+# Production
+yarn add igloo-d2c-components@latest
+```
+
+### Import Themes
+```typescript
+import { iglooTheme, cimbTheme, ammetlifeTheme, getTenantTheme } from 'igloo-d2c-components'
+```
+
+### Import Components
+```typescript
+import { Button, Card, Banner, TenantThemeProvider } from 'igloo-d2c-components'
+```
+
+### Import Hooks
+```typescript
+import { useTenantTheme, useTenantId, useIsTenant } from 'igloo-d2c-components'
+```
+
+### Build & Publish
+```bash
+# Build
+yarn build
+
+# Publish to NPM
+./publish-to-npm.sh
+
+# Publish to GitLab
+npm publish
+```
 
 ---
 
-**Version:** 1.0.0
-**Author:** Igloo Team
+**Version:** 1.0.6
+**Last Updated:** November 12, 2025
+**Node.js:** >=16.20.0 <=18.x
+**Target:** ES2015
+**Output:** Unminified
+
+For version history, see [CHANGELOG.md](./CHANGELOG.md)