@nestbotics/nct_frontend_common_components v1.1.0

@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

npm install @nestbotics/nct_frontend_common_components

🚀 Quick Start

1. Install Peer Dependencies

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

2. Basic Setup

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:

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

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:

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:

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:

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:

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:

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

# 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

# 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

# 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

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

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

# Publish to npm
npm publish

Option B: Publish to GitHub Packages

# 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

# 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?

# 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:

   npm install react-hot-toast react-toastify styled-components

2. Add Toast Provider to your app:

   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.

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.

🐛 Issues

Report issues on our GitHub Issues page.