@renderx-plugins/header

RenderX Plugin Header

A customizable header UI plugin for RenderX, providing flexible header components, theme toggling, and seamless integration with the RenderX host application. Designed for easy installation as an npm package and dynamic loading via the RenderX plugin manifest system.

Features

• 🎨 Customizable Header Components - Flexible and themeable header UI elements
• 🌓 Theme Toggle Support - Built-in dark/light theme switching
• 🔌 Plugin Architecture - Seamless integration with RenderX host applications
• 📦 NPM Package - Easy installation and dependency management
• 🔄 Dynamic Loading - Runtime plugin loading via manifest configuration
• 📱 Responsive Design - Mobile-friendly header components
• 🎯 TypeScript Support - Full TypeScript definitions and ESM compatibility
• 🔄 Sequence-Driven Interactions - Support for complex UI workflows

Installation

Install the plugin via npm:

npm install renderx-plugin-header

Or with yarn:

yarn add renderx-plugin-header

Usage

Basic Usage

import { HeaderTitle, HeaderControls, HeaderThemeToggle } from 'renderx-plugin-header';

// Basic header setup
function App() {
  return (
    <div className="app">
      <header className="app-header">
        <HeaderTitle title="My Application" />
        <HeaderControls>
          <HeaderThemeToggle />
        </HeaderControls>
      </header>
      {/* Your app content */}
    </div>
  );
}

Advanced Configuration

import { 
  HeaderTitle, 
  HeaderControls, 
  HeaderThemeToggle,
  HeaderNavigation 
} from 'renderx-plugin-header';

function AppHeader() {
  const handleThemeChange = (theme) => {
    console.log('Theme changed to:', theme);
  };

  return (
    <header className="custom-header">
      <HeaderTitle 
        title="RenderX Application"
        subtitle="Plugin Demo"
        logoUrl="/assets/logo.png"
      />
      
      <HeaderNavigation
        items={[
          { label: 'Home', href: '/' },
          { label: 'About', href: '/about' },
          { label: 'Contact', href: '/contact' }
        ]}
      />
      
      <HeaderControls>
        <HeaderThemeToggle 
          onThemeChange={handleThemeChange}
          defaultTheme="light"
        />
      </HeaderControls>
    </header>
  );
}

RenderX Host Integration

Plugin Manifest Configuration

Add the header plugin to your RenderX application's plugin manifest:

{
  "plugins": [
    {
      "name": "renderx-plugin-header",
      "version": "^1.0.0",
      "type": "ui-component",
      "entryPoint": "dist/index.js",
      "manifest": {
        "components": [
          "HeaderTitle",
          "HeaderControls", 
          "HeaderThemeToggle",
          "HeaderNavigation"
        ],
        "styles": "dist/styles.css",
        "dependencies": []
      },
      "loadStrategy": "eager",
      "scope": "global"
    }
  ]
}

Dynamic Plugin Loading

// In your RenderX host application
import { loadPlugin } from 'renderx-core';

async function initializeHeaderPlugin() {
  try {
    const headerPlugin = await loadPlugin('renderx-plugin-header');
    
    // Register plugin components with RenderX
    headerPlugin.register({
      container: document.getElementById('header-container'),
      config: {
        theme: 'auto',
        showNavigation: true,
        enableThemeToggle: true
      }
    });
    
    console.log('Header plugin loaded successfully');
  } catch (error) {
    console.error('Failed to load header plugin:', error);
  }
}

Integration with RenderX Context

import { useRenderXContext } from 'renderx-core';
import { HeaderTitle, HeaderThemeToggle } from 'renderx-plugin-header';

function IntegratedHeader() {
  const { theme, updateTheme, appConfig } = useRenderXContext();
  
  return (
    <header>
      <HeaderTitle title={appConfig.title} />
      <HeaderThemeToggle 
        currentTheme={theme}
        onThemeChange={updateTheme}
      />
    </header>
  );
}

Available Components

HeaderTitle

A customizable title component for your application header.

<HeaderTitle 
  title="Application Name"
  subtitle="Optional subtitle"
  logoUrl="/path/to/logo.png"
  onClick={() => navigate('/home')}
/>

Props:

• title (string, required) - The main title text
• subtitle (string, optional) - Secondary text below the title
• logoUrl (string, optional) - URL to logo image
• onClick (function, optional) - Click handler for the title

HeaderControls

A container component for header action items and controls.

<HeaderControls 
  align="right"
  spacing="medium"
>
  {/* Your control components */}
</HeaderControls>

Props:

• align (string, optional) - Alignment: 'left', 'center', 'right'
• spacing (string, optional) - Spacing between items: 'small', 'medium', 'large'
• children (ReactNode) - Control components to render

HeaderThemeToggle

A theme switching toggle button with support for light, dark, and auto modes.

<HeaderThemeToggle 
  defaultTheme="auto"
  onThemeChange={(theme) => console.log(theme)}
  showLabel={true}
/>

Props:

• defaultTheme (string, optional) - Initial theme: 'light', 'dark', 'auto'
• onThemeChange (function, optional) - Callback when theme changes
• showLabel (boolean, optional) - Whether to show theme label text

HeaderNavigation

A navigation component for header menu items.

<HeaderNavigation 
  items={[
    { label: 'Home', href: '/', active: true },
    { label: 'About', href: '/about' },
    { label: 'Services', children: [...] }
  ]}
  orientation="horizontal"
/>

Props:

• items (array, required) - Navigation items with label, href, and optional children
• orientation (string, optional) - Layout: 'horizontal', 'vertical'
• onNavigate (function, optional) - Custom navigation handler

Styling and Theming

The plugin includes CSS custom properties for easy theming:

:root {
  --header-bg-color: #ffffff;
  --header-text-color: #333333;
  --header-border-color: #e1e5e9;
  --header-height: 60px;
  --header-padding: 0 1rem;
}

[data-theme="dark"] {
  --header-bg-color: #1a1a1a;
  --header-text-color: #ffffff;
  --header-border-color: #333333;
}

Import the base styles in your application:

import 'renderx-plugin-header/dist/styles.css';

Contributing

We welcome contributions! Please follow these steps:

• Fork the repository

  git clone https://github.com/BPMSoftwareSolutions/renderx-plugin-header.git
  cd renderx-plugin-header
  

• Install dependencies

  npm install
  

• Create a feature branch

  git checkout -b feature/your-feature-name
  

• Make your changes and commit

  git add .
  git commit -m "feat: add your feature description"
  

• Run tests and linting

  npm run test
  npm run lint
  

• Push and create a Pull Request

  git push origin feature/your-feature-name
  

Development Setup

# Install dependencies
npm install

# Start development server
npm run dev

# Build the plugin
npm run build

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Format code
npm run format

Testing

The plugin includes comprehensive test coverage using Jest and React Testing Library.

Running Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm run test HeaderTitle.test.js

Test Structure

tests/
├── components/
│   ├── HeaderTitle.test.js
│   ├── HeaderControls.test.js
│   ├── HeaderThemeToggle.test.js
│   └── HeaderNavigation.test.js
├── integration/
│   ├── renderx-integration.test.js
│   └── plugin-loading.test.js
└── utils/
    └── test-helpers.js

Writing Tests

When contributing, please include tests for new features:

import { render, screen, fireEvent } from '@testing-library/react';
import { HeaderThemeToggle } from '../src/components/HeaderThemeToggle';

describe('HeaderThemeToggle', () => {
  it('should toggle theme on click', () => {
    const onThemeChange = jest.fn();
    render(<HeaderThemeToggle onThemeChange={onThemeChange} />);
    
    const toggleButton = screen.getByRole('button', { name: /theme/i });
    fireEvent.click(toggleButton);
    
    expect(onThemeChange).toHaveBeenCalledWith('dark');
  });
});

Plugin Manifest Integration

For seamless integration with RenderX applications, use the following manifest configuration:

Complete Manifest Example

{
  "name": "my-renderx-app",
  "version": "1.0.0",
  "plugins": [
    {
      "name": "renderx-plugin-header",
      "version": "^1.0.0",
      "type": "ui-component",
      "entryPoint": "dist/index.js",
      "manifest": {
        "components": [
          {
            "name": "HeaderTitle",
            "export": "HeaderTitle",
            "type": "react-component"
          },
          {
            "name": "HeaderControls",
            "export": "HeaderControls", 
            "type": "react-component"
          },
          {
            "name": "HeaderThemeToggle",
            "export": "HeaderThemeToggle",
            "type": "react-component"
          },
          {
            "name": "HeaderNavigation",
            "export": "HeaderNavigation",
            "type": "react-component"
          }
        ],
        "styles": [
          "dist/styles.css"
        ],
        "dependencies": {
          "react": "^18.0.0",
          "react-dom": "^18.0.0"
        }
      },
      "loadStrategy": "eager",
      "scope": "global",
      "config": {
        "theme": {
          "default": "auto",
          "variants": ["light", "dark", "auto"]
        },
        "features": {
          "navigation": true,
          "themeToggle": true,
          "responsive": true
        }
      }
    }
  ]
}

Conditional Loading

{
  "plugins": [
    {
      "name": "renderx-plugin-header",
      "loadConditions": {
        "environment": ["production", "development"],
        "features": ["header", "navigation"],
        "viewport": {
          "minWidth": 768
        }
      }
    }
  ]
}

API Reference

For detailed API documentation, visit our API Reference.

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Changelog

See CHANGELOG.md for a list of changes and version history.