npm package: @syuttechnologies/layout
Description: Enterprise React Layout Component with UI Components
Latest version: 1.0.24

# @syuttechnologies/layout

Enterprise React Layout Component with sidebar navigation, tabs, dark mode, and notifications.

## Repository

**GitLab:** https://gitlab.com/enterprise-templates/react-app-foundation.git

---

## Installation

### Using GitLab (Recommended)

```bash
npm install git+https://gitlab.com/enterprise-templates/react-app-foundation.git#V1.0.1
```

Or add to `package.json`:

```json
{
  "dependencies": {
    "@syuttechnologies/layout": "git+https://gitlab.com/enterprise-templates/react-app-foundation.git#V1.0.1"
  }
}
```

### Using npm Registry

```bash
npm install @syuttechnologies/layout@1.0.1
```

---

## Quick Start Guide

### Step 1: Create Component Registry

Create `src/components/common/ComponentRegistry.ts`:

```typescript
import React from 'react';
import Dashboard from '../modules/Dashboard';
import Settings from '../modules/Settings';
import UserManagement from '../modules/UserManagement';

export const COMPONENT_REGISTRY: Record<string, React.ComponentType<any>> = {
  Dashboard,
  Settings,
  UserManagement,
  // Add more components as needed
};
```

### Step 2: Create Layout Configuration

Create `src/config/layoutConfig.ts`:

```typescript
import type { EnterpriseLayoutConfig } from '@syuttechnologies/layout';
import { COMPONENT_REGISTRY } from '../components/common/ComponentRegistry';

export const createLayoutConfig = (): EnterpriseLayoutConfig => ({
  // =========================================================================
  // BRANDING
  // =========================================================================
  branding: {
    appName: "My Application",
    logo: {
      alt: "App Logo",
      width: "28px",
      height: "28px",
      showText: true,
    },
    favicon: null,
    colors: {
      primary: "#2563eb",
      secondary: "#64748b",
      success: "#16a34a",
      warning: "#d97706",
      danger: "#dc2626",
      info: "#0ea5e9",
    },
  },

  // =========================================================================
  // LAYOUT
  // =========================================================================
  layout: {
    headerHeight: "3rem",
    sidebarWidth: "16rem",
    sidebarCollapsedWidth: "4rem",
    footerHeight: "2rem",
    tabBarHeight: "2.5rem",
    enableTabMode: true,
    enableDarkMode: true,
    enableFooter: true,
    defaultTheme: "light",
    responsive: true,
    collapsibleSidebar: true,
    showBreadcrumbs: true,
    autoCollapseSidebar: true,
    compactModeStrategy: "smart-grouping",
  },

  // =========================================================================
  // FOOTER
  // =========================================================================
  footer: {
    appVersion: "v1.0.0",
    environment: "Development",
    copyright: "© 2025 My Company. All rights reserved.",
    supportLink: "mailto:support@company.com",
    supportText: "Support",
  },

  // =========================================================================
  // USER
  // =========================================================================
  user: {
    name: "John Doe",
    role: "Administrator",
    avatar: "JD",
    permissions: ["read", "write", "admin"],
  },

  // =========================================================================
  // NAVIGATION
  // =========================================================================
  navigation: [
    {
      section: "Dashboard",
      icon: "layout",
      items: [
        { id: "overview", title: "Dashboard", icon: "home", active: true },
      ],
    },
    {
      section: "Administration",
      icon: "settings",
      items: [
        { id: "users", title: "User Management", icon: "users" },
        { id: "settings", title: "Settings", icon: "settings" },
      ],
    },
  ],

  // =========================================================================
  // MODULES
  // =========================================================================
  modules: {
    "overview": {
      showHeader: false,
      title: "Dashboard",
      description: "Main dashboard",
      component: COMPONENT_REGISTRY.Dashboard,
      actions: [],
      permissions: ["read"],
      breadcrumb: ["Dashboard"],
    },
    "users": {
      showHeader: false,
      title: "User Management",
      description: "Manage users",
      component: COMPONENT_REGISTRY.UserManagement,
      actions: ["add", "edit", "delete"],
      permissions: ["admin"],
      breadcrumb: ["Administration", "Users"],
    },
    "settings": {
      showHeader: false,
      title: "Settings",
      description: "App settings",
      component: COMPONENT_REGISTRY.Settings,
      actions: ["edit"],
      permissions: ["admin"],
      breadcrumb: ["Administration", "Settings"],
    },
  },

  // =========================================================================
  // HOOKS
  // =========================================================================
  hooks: {
    onModuleChange: (moduleId, config) => {
      console.log('Module changed:', moduleId);
    },
    onThemeChange: (theme) => {
      console.log('Theme changed:', theme);
    },
    onLogout: () => {
      console.log('Logout');
      // window.location.href = '/login';
    },
  },
});

export default createLayoutConfig;
```

### Step 3: Create MainLayout Component

Create `src/components/layout/MainLayout.tsx`:

```typescript
import React from 'react';
import { EnterpriseLayout } from '@syuttechnologies/layout';
import { COMPONENT_REGISTRY } from '../common/ComponentRegistry';
import { createLayoutConfig } from '../../config/layoutConfig';

const MainLayout: React.FC = () => {
  const config = createLayoutConfig();

  return (
    <div style={{ height: "100vh", width: "100%" }}>
      <EnterpriseLayout
        config={config}
        componentRegistry={COMPONENT_REGISTRY}
      />
    </div>
  );
};

export default MainLayout;
```

### Step 4: Create Sample Module Components

Create `src/components/modules/Dashboard.tsx`:

```typescript
import React from 'react';

const Dashboard: React.FC = () => {
  return (
    <div style={{ padding: '20px' }}>
      <h1>Dashboard</h1>
      <p>Welcome to the dashboard!</p>
    </div>
  );
};

export default Dashboard;
```

Create `src/components/modules/Settings.tsx`:

```typescript
import React from 'react';

const Settings: React.FC = () => {
  return (
    <div style={{ padding: '20px' }}>
      <h1>Settings</h1>
      <p>Configure your application here.</p>
    </div>
  );
};

export default Settings;
```

Create `src/components/modules/UserManagement.tsx`:

```typescript
import React from 'react';

const UserManagement: React.FC = () => {
  return (
    <div style={{ padding: '20px' }}>
      <h1>User Management</h1>
      <p>Manage users here.</p>
    </div>
  );
};

export default UserManagement;
```

### Step 5: Use in App.tsx

```typescript
import React from 'react';
import MainLayout from './components/layout/MainLayout';

function App() {
  return <MainLayout />;
}

export default App;
```

---

## Package Management with GitLab

### Publishing Updates

1. **Make changes** in `src/` folder

2. **Build the package:**
   ```bash
   npm run build
   ```

3. **Update version** in `package.json`:
   ```json
   "version": "1.0.2"
   ```

4. **Commit and tag:**
   ```bash
   git add .
   git commit -m "Update V1.0.2 - description of changes"
   git tag V1.0.2
   git push origin main
   git push --tags
   ```

### Installing Specific Versions

```bash
# Latest version (main branch)
npm install git+https://gitlab.com/enterprise-templates/react-app-foundation.git

# Specific tag/version
npm install git+https://gitlab.com/enterprise-templates/react-app-foundation.git#V1.0.1

# Specific branch
npm install git+https://gitlab.com/enterprise-templates/react-app-foundation.git#develop

# Specific commit
npm install git+https://gitlab.com/enterprise-templates/react-app-foundation.git#abc1234
```

---

## Updating Package in Consumer Projects (IMPORTANT)

After making changes and pushing to GitLab, follow these steps to update the package in your consumer projects (e.g., prima-web):

### Step 1: Update package.json

Update the version tag in your project's `package.json`:

```json
{
  "dependencies": {
    "@syuttechnologies/layout": "git+https://gitlab.com/enterprise-templates/react-app-foundation.git#V1.0.2"
  }
}
```

### Step 2: Force Clear Cache & Reinstall

Run these commands in your project directory:

```bash
# Clear npm cache forcefully
npm cache clean --force

# Remove existing package
npm uninstall @syuttechnologies/layout

# Reinstall the package
npm install @syuttechnologies/layout
```

### Alternative: One-liner Command

```bash
npm cache clean --force && npm uninstall @syuttechnologies/layout && npm install
```

### Step 3: Restart Development Server

```bash
npm start
```

### Troubleshooting

If the package is not updating correctly:

1. **Delete node_modules and reinstall:**
   ```bash
   rm -rf node_modules
   rm -rf package-lock.json
   npm cache clean --force
   npm install
   ```

2. **Verify installed version:**
   ```bash
   npm list @syuttechnologies/layout
   ```

3. **Check package contents:**
   ```bash
   ls node_modules/@syuttechnologies/layout
   ```

---

## Configuration Reference

### Branding

| Property | Type | Description |
|----------|------|-------------|
| `appName` | string | Application name displayed in header |
| `logo.alt` | string | Logo alt text |
| `logo.width` | string | Logo width |
| `logo.height` | string | Logo height |
| `logo.showText` | boolean | Show app name next to logo |
| `colors.primary` | string | Primary theme color |
| `colors.secondary` | string | Secondary color |
| `colors.success` | string | Success color |
| `colors.warning` | string | Warning color |
| `colors.danger` | string | Danger color |
| `colors.info` | string | Info color |

### Layout

| Property | Type | Description |
|----------|------|-------------|
| `headerHeight` | string | Header height (e.g., "3rem") |
| `sidebarWidth` | string | Sidebar width when expanded |
| `sidebarCollapsedWidth` | string | Sidebar width when collapsed |
| `enableTabMode` | boolean | Enable tab-based navigation |
| `enableDarkMode` | boolean | Enable dark mode toggle |
| `enableFooter` | boolean | Show footer |
| `defaultTheme` | "light" \| "dark" | Default theme |
| `collapsibleSidebar` | boolean | Allow sidebar collapse |
| `showBreadcrumbs` | boolean | Show breadcrumbs |

### Navigation

```typescript
navigation: [
  {
    section: "Section Name",
    icon: "icon-name",
    items: [
      { id: "module-id", title: "Display Title", icon: "icon", active: true }
    ]
  }
]
```

### Modules

```typescript
modules: {
  "module-id": {
    showHeader: boolean,
    title: string,
    description: string,
    component: React.ComponentType,
    actions: string[],
    permissions: string[],
    breadcrumb: string[]
  }
}
```

### Hooks

| Hook | Parameters | Description |
|------|------------|-------------|
| `onModuleChange` | (moduleId, config) | Called when module changes |
| `onThemeChange` | (theme) | Called when theme changes |
| `onUserAction` | (action, data) | Called on user actions |
| `onNavigate` | (path, params) | Called on navigation |
| `onChangePassword` | () | Called when change password clicked |
| `onLogout` | () | Called when logout clicked |

---

## Folder Structure for New Project

```
my-project/
├── src/
│   ├── components/
│   │   ├── common/
│   │   │   └── ComponentRegistry.ts
│   │   ├── layout/
│   │   │   └── MainLayout.tsx
│   │   └── modules/
│   │       ├── Dashboard.tsx
│   │       ├── Settings.tsx
│   │       └── UserManagement.tsx
│   ├── config/
│   │   └── layoutConfig.ts
│   ├── App.tsx
│   └── index.tsx
├── package.json
└── tsconfig.json
```

---

## Exports

```typescript
// Components
import { EnterpriseLayout } from '@syuttechnologies/layout';
import { ChangePasswordModal } from '@syuttechnologies/layout';

// Services
import { notificationService } from '@syuttechnologies/layout';

// Types
import type {
  EnterpriseLayoutConfig,
  EnterpriseLayoutProps,
  ComponentRegistry,
  NavigationSection,
  NavigationItem,
  ModuleConfig,
  BrandingConfig,
  LayoutConfig,
  FooterConfig,
  UserConfig,
  HooksConfig,
} from '@syuttechnologies/layout';
```

---

## Support

For issues or questions, contact: support@syuttechnologies.com