@nestbotics/nct_frontend_common_components/README.md

A collection of reusable React components with theme management and styling utilities

# @nestbotics/nct_frontend_common_components

**nct_frontend_common_components** is a collection of reusable React components for building consistent, modern applications. It includes shared components such as **Header**, **Footer**, **Sidebar**, **Theme** management, and a comprehensive styling system.

## 📦 Installation

```bash
npm install @nestbotics/nct_frontend_common_components
```

## 🚀 Quick Start

### 1. Install Peer Dependencies

```bash
npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled
```

### 2. Basic Setup

```javascript
import React from 'react';
import { 
  Header, 
  Footer, 
  Sidebar, 
  UserDataProvider,
  useMode,
  ColorModeContext 
} from '@nestbotics/nct_frontend_common_components';
import { ThemeProvider, CssBaseline } from '@mui/material';

function App() {
  const [theme, colorMode] = useMode();

  return (
    <ColorModeContext.Provider value={colorMode}>
      <ThemeProvider theme={theme}>
        <CssBaseline />
        <UserDataProvider>
          <div className="app">
            <Sidebar />
            <main className="content">
              <Header title="My App" subtitle="Welcome to my application" />
              {/* Your app content */}
              <Footer />
            </main>
          </div>
        </UserDataProvider>
      </ThemeProvider>
    </ColorModeContext.Provider>
  );
}

export default App;
```

### 3. Import Styles (Optional)

If you want to use the pre-built CSS classes:

```javascript
import '@nestbotics/nct_frontend_common_components/styles';
```

## 🎨 Components

### Core Components

- **Header**: Application header with theme toggle and user actions
- **Footer**: Application footer
- **Sidebar**: Navigation sidebar with customizable menu items
- **Button Components**: SaveButton, CancelButton, DeleteButton, CustomButton
- **Form Components**: CustomTextField
- **Data Display**: GenericDataGrid, DynamicTable, HelperTable
- **Modals**: AlertPopup, OrderAlert, AddManageModal

### Example Usage

```javascript
import { 
  CustomButton, 
  CustomTextField, 
  GenericDataGrid 
} from '@nestbotics/nct_frontend_common_components';

function MyComponent() {
  return (
    <div>
      <CustomTextField 
        label="Username" 
        value={username}
        onChange={(e) => setUsername(e.target.value)}
      />
      <CustomButton 
        variant="primary" 
        onClick={handleSubmit}
      >
        Submit
      </CustomButton>
      <GenericDataGrid 
        rows={data}
        columns={columns}
      />
    </div>
  );
}
```

## 🎭 Theme System

The library includes a comprehensive theme system with dark/light mode support:

```javascript
import { useMode, ColorModeContext, tokens } from '@nestbotics/nct_frontend_common_components';

function ThemedComponent() {
  const theme = useTheme();
  const colors = tokens(theme.palette.mode);
  const colorMode = useContext(ColorModeContext);

  return (
    <div style={{ backgroundColor: colors.primary[500] }}>
      <button onClick={colorMode.toggleColorMode}>
        Toggle Theme
      </button>
    </div>
  );
}
```

## 🎯 Style Provider System

Advanced styling with variants and utilities:

```javascript
import { 
  StyleProvider, 
  useStyleVariants, 
  getVariantStyle,
  StyledText 
} from '@nestbotics/nct_frontend_common_components';

function StyledComponent() {
  const { variants } = useStyleVariants();
  
  return (
    <StyleProvider>
      <StyledText variant="titleL">Large Title</StyledText>
      <StyledText variant="bodyM">Medium body text</StyledText>
      
      {/* Using CSS classes */}
      <h1 className="titleL">HTML with class</h1>
      <p className="bodyS">Small body text</p>
    </StyleProvider>
  );
}
```

### Available Typography Variants

- **Titles**: `titleL`, `titleM`, `titleS`
- **Body**: `bodyL`, `bodyM`, `bodyS`  
- **Labels**: `labelL`, `labelM`, `labelS`
- **Emphasis**: `emphasisL`, `emphasisM`, `emphasisS`

## 🔧 Context Providers

### UserDataProvider

Manages user authentication and application state:

```javascript
import { UserDataProvider, userDataContext } from '@nestbotics/nct_frontend_common_components';

function UserProfile() {
  const { user, setUser, activeFields, toggleActiveField } = useContext(userDataContext);
  
  return (
    <div>
      <p>Welcome, {user.name}!</p>
      <button onClick={() => toggleActiveField('notifications')}>
        Toggle Notifications
      </button>
    </div>
  );
}
```

## 🛠️ Utilities

### CSS Generation

Generate CSS from JavaScript objects:

```javascript
import { 
  styleObjectToCss, 
  generateVariantCss,
  generateCompleteCss 
} from '@nestbotics/nct_frontend_common_components';

// Convert style object to CSS
const cssString = styleObjectToCss({
  fontSize: '16px',
  color: '#333'
}, '.my-class');

// Generate complete CSS file
const completeCss = generateCompleteCss();
```

## 📝 TypeScript Support

The library includes TypeScript declarations:

```typescript
import { 
  HeaderProps, 
  ButtonProps, 
  UserDataContextType 
} from '@nestbotics/nct_frontend_common_components';

const MyHeader: React.FC<HeaderProps> = ({ title, subtitle }) => {
  return <Header title={title} subtitle={subtitle} />;
};
```

## 🔗 Peer Dependencies

- React >=16.8.0
- React DOM >=16.8.0
- Material-UI >=5.0.0
- Emotion (React & Styled)

## 🔧 Development & Publishing Guide

### For Library Developers

If you're working on this component library and need to make changes, follow these steps:

#### 1. Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/Nestbotics/nct_frontend_common_components.git
cd nct_frontend_common_components

# Install dependencies
npm install
```

#### 2. Development Workflow

```bash
# Start development build (watches for changes)
npm run dev

# Or manually build for testing
npm run build
```

#### 3. Making Changes

When you modify components in the `src/` folder:

- **Components**: Edit files in `src/components/common/`
- **Themes**: Modify `src/theme/Theme.js`, `src/theme/dark_theme.js`, or `src/theme/light_theme.js`
- **Context**: Update `src/context/UserDataProvider.jsx` or `src/context/user_data/StyleProvider.jsx`
- **Styles**: Edit `src/assets/styles/global.css`
- **Exports**: Update `src/index.js` to expose new components

#### 4. Testing Changes Locally

```bash
# Build the package
npm run build

# Create a local package for testing
npm pack

# This creates a .tgz file that you can install in other projects:
# npm install /path/to/nestbotics-nct_frontend_common_components-1.0.4.tgz
```

#### 5. Version Management

```bash
# Update version (patch: 1.0.4 -> 1.0.5)
npm version patch

# Update version (minor: 1.0.4 -> 1.1.0)
npm version minor

# Update version (major: 1.0.4 -> 2.0.0)
npm version major
```

#### 6. Publishing Process

**Option A: Publish to NPM (Recommended)**

```bash
# Login to npm (one-time setup)
npm login

# Publish to npm
npm publish
```

**Option B: Publish to GitHub Packages**

```bash
# Login to GitHub packages (one-time setup)
npm login --registry=https://npm.pkg.github.com/

# Publish to GitHub packages
npm publish --registry=https://npm.pkg.github.com/
```

#### 7. Complete Release Workflow

```bash
# 1. Make your changes
git add .
git commit -m "feat: add new component or fix bug"

# 2. Update version
npm version patch  # or minor/major

# 3. Build the package
npm run build

# 4. Test the build
npm run test  # if you have tests

# 5. Publish
npm publish

# 6. Push changes and tags to GitHub
git push origin main --tags
```

#### 8. Build Process Details

The build process creates:

- **`dist/index.js`** - CommonJS version for older projects
- **`dist/index.esm.js`** - ES Modules version for modern projects
- **`dist/index.d.ts`** - TypeScript declarations
- **`dist/assets/`** - Styles, fonts, and images
- **`dist/components/`** - Compiled components

#### 9. What Gets Published

The `.npmignore` file ensures only these files are published:

- `dist/` folder (compiled code)
- `README.md`
- `LICENSE`
- `package.json`

The `src/` folder and development files are excluded from the published package.

#### 10. Troubleshooting

**Build fails?**
```bash
# Clean and rebuild
npm run clean
npm run build
```

**Import issues after changes?**
- Check that new components are exported in `src/index.js`
- Ensure proper default exports in component files
- Verify TypeScript declarations are updated

**Publish fails?**
- Check if you're logged in: `npm whoami`
- Verify version hasn't been published: check npm registry
- Ensure you have publish rights to the package

## 🔧 Troubleshooting

### Toast Functionality Error: `S.keyframes is not a function`

If you encounter this error, it's due to a styled-components conflict with react-hot-toast. Follow these steps:

1. **Install required dependencies:**
   ```bash
   npm install react-hot-toast react-toastify styled-components
   ```

2. **Add Toast Provider to your app:**
   ```jsx
   import { Toaster } from 'react-hot-toast';

   function App() {
     return (
       <div>
         {/* Your app content */}
         <Toaster
           position="top-right"
           toastOptions={{
             duration: 4000,
             style: {
               background: '#363636',
               color: '#fff',
             },
           }}
         />
       </div>
     );
   }
   ```

3. **Alternative: Use without toast libraries**
   The components work without toast libraries - toast calls will fallback to console logging.

For detailed troubleshooting, see [TOAST_TROUBLESHOOTING.md](./TOAST_TROUBLESHOOTING.md).

### Common Issues

- **Missing peer dependencies**: Run `npm ls` to check for missing peer dependencies
- **Version conflicts**: Ensure React version >= 16.8.0
- **Theme not loading**: Make sure to wrap your app with the theme provider

## 📄 License

MIT

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📚 Documentation

For more detailed documentation and examples, visit our [GitHub repository](https://github.com/Nestbotics/nct_frontend_common_components).

## 🐛 Issues

Report issues on our [GitHub Issues page](https://github.com/Nestbotics/nct_frontend_common_components/issues).