@metadiv-studio/app-layout-001

@metadiv-studio/app-layout-001

A comprehensive React application layout package that provides a professional, responsive layout system with sidebar navigation, header, and page content management. Built with TypeScript and Tailwind CSS, this package offers a complete solution for building consistent application interfaces.

📦 Installation

npm i @metadiv-studio/app-layout-001

🎯 Package Description

@metadiv-studio/app-layout-001 is a feature-rich layout package that provides:

• AppLayout: A complete application shell with header, sidebar, and content area
• PageLayout: A flexible page content wrapper with customizable headers and content cards
• useLayoutContext: A React context hook for managing layout state (sidebar/app panel visibility)
• Responsive Design: Built with Tailwind CSS for mobile-first responsive layouts
• TypeScript Support: Full type definitions for all components and props
• Dark Mode Support: Built-in dark mode styling with CSS custom properties

🚀 Quick Start

import AppLayout, { PageLayout, useLayoutContext } from '@metadiv-studio/app-layout-001';

function MyApp() {
  return (
    <AppLayout
      systemIcon={<YourLogo />}
      sidebarItems={sidebarConfig}
      currentUser={user}
    >
      <PageLayout headerTitle="Dashboard">
        <div>Your page content here</div>
      </PageLayout>
    </AppLayout>
  );
}

🏗️ Components

AppLayout

The main application shell component that provides the overall structure.

import AppLayout from '@metadiv-studio/app-layout-001';

<AppLayout
  systemIcon={<YourLogo />}
  sidebarItems={sidebarItems}
  currentUser={currentUser}
  currentWorkspaceMember={workspaceMember}
  isHighlightHandler={(item) => item.link === currentPath}
  footerMenuItems={footerItems}
  userMenuItems={userMenuItems}
>
  {/* Your page content goes here */}
</AppLayout>

Props

Prop	Type	Description
children	React.ReactNode	Content to render in the main area
systemIcon	React.ReactNode	Logo or system icon for the header
sidebarItems	SidebarItem[]	Array of sidebar navigation items
currentWorkspaceMember	WorkspaceMemberDTO	Current workspace member data
currentUser	SystemUserDTO | SystemAdminDTO	Current authenticated user
isHighlightHandler	(item: SidebarItem) => boolean	Function to determine active sidebar item
footerMenuItems	MenuItem[]	Footer menu items for the sidebar
userMenuItems	MenuItem[]	User dropdown menu items

PageLayout

A flexible page content wrapper that provides consistent page structure.

import { PageLayout } from '@metadiv-studio/app-layout-001';

// Basic usage
<PageLayout headerTitle="Dashboard">
  <div>Your page content here</div>
</PageLayout>

// With custom header right content
<PageLayout 
  headerTitle="Users" 
  headerRight={<button>Add User</button>}
>
  <div>User management content</div>
</PageLayout>

// Without content card (full bleed)
<PageLayout 
  headerTitle="Analytics" 
  hideContentCard={true}
>
  <div>Full-width analytics content</div>
</PageLayout>

// Custom styling
<PageLayout 
  headerTitle="Settings" 
  className="p-6"
>
  <div>Settings configuration</div>
</PageLayout>

Props

Prop	Type	Default	Description
headerTitle	React.ReactNode	-	Title displayed in the page header
headerRight	React.ReactNode	-	Right-aligned content in the header
children	React.ReactNode	-	Page content
className	string	-	Additional CSS classes for the content area
hideSubHeader	boolean	false	Hide the page header completely
hideContentCard	boolean	false	Remove the content card wrapper (full bleed)

🎛️ useLayoutContext Hook

A React context hook for managing layout state across your application.

import { useLayoutContext } from '@metadiv-studio/app-layout-001';

function MyComponent() {
  const { 
    getSidebarOpen, 
    setSidebarOpen, 
    getAppPanelOpen, 
    setAppPanelOpen 
  } = useLayoutContext();

  const isSidebarOpen = getSidebarOpen();
  const isAppPanelOpen = getAppPanelOpen();

  const toggleSidebar = () => {
    setSidebarOpen(!isSidebarOpen);
  };

  const toggleAppPanel = () => {
    setAppPanelOpen(!isAppPanelOpen);
  };

  return (
    <div>
      <button onClick={toggleSidebar}>
        {isSidebarOpen ? 'Close' : 'Open'} Sidebar
      </button>
      
      <button onClick={toggleAppPanel}>
        {isAppPanelOpen ? 'Close' : 'Open'} App Panel
      </button>
      
      <p>Sidebar is {isSidebarOpen ? 'open' : 'closed'}</p>
      <p>App Panel is {isAppPanelOpen ? 'open' : 'closed'}</p>
    </div>
  );
}

Context Methods

Method	Type	Description
getSidebarOpen()	() => boolean	Get current sidebar open state
setSidebarOpen(open: boolean)	(boolean) => void	Set sidebar open/closed state
getAppPanelOpen()	() => boolean	Get current app panel open state
setAppPanelOpen(open: boolean)	(boolean) => void	Set app panel open/closed state

📋 Type Definitions

SidebarItem

interface SidebarItem {
  name?: React.ReactNode;        // Display name
  icon?: React.ReactNode;        // Icon component
  link?: string;                 // Navigation link
  hidden?: boolean;              // Hide from sidebar
  items?: SidebarItem[];         // Sub-items for nested navigation
  onClick?: () => void;          // Click handler
}

MenuItem

interface MenuItem {
  icon?: React.ReactNode;        // Menu item icon
  name?: React.ReactNode;        // Menu item label
  onClick?: () => void;          // Click handler
}

🎨 Complete Example

Here's a complete example showing how to use all components together:

import React from 'react';
import AppLayout, { PageLayout, useLayoutContext } from '@metadiv-studio/app-layout-001';
import { HomeIcon, UsersIcon, SettingsIcon, ChartBarIcon } from 'lucide-react';

// Sidebar configuration
const sidebarItems = [
  {
    name: 'Dashboard',
    icon: <HomeIcon className="w-5 h-5" />,
    link: '/dashboard'
  },
  {
    name: 'Users',
    icon: <UsersIcon className="w-5 h-5" />,
    link: '/users'
  },
  {
    name: 'Analytics',
    icon: <ChartBarIcon className="w-5 h-5" />,
    link: '/analytics'
  },
  {
    name: 'Settings',
    icon: <SettingsIcon className="w-5 h-5" />,
    link: '/settings'
  }
];

// Footer menu items
const footerMenuItems = [
  {
    name: 'Help',
    icon: <HelpIcon className="w-4 h-4" />,
    onClick: () => window.open('/help', '_blank')
  }
];

// User menu items
const userMenuItems = [
  {
    name: 'Profile',
    icon: <UserIcon className="w-4 h-4" />,
    onClick: () => navigate('/profile')
  },
  {
    name: 'Logout',
    icon: <LogOutIcon className="w-4 h-4" />,
    onClick: () => logout()
  }
];

// Example page component using useLayoutContext
function DashboardPage() {
  const { getSidebarOpen, setSidebarOpen } = useLayoutContext();
  
  return (
    <PageLayout 
      headerTitle="Dashboard" 
      headerRight={
        <button 
          onClick={() => setSidebarOpen(!getSidebarOpen())}
          className="px-3 py-2 bg-blue-500 text-white rounded-md"
        >
          Toggle Sidebar
        </button>
      }
    >
      <div className="p-6">
        <h2 className="text-2xl font-bold mb-4">Welcome to Dashboard</h2>
        <p className="text-gray-600">
          This is your dashboard content. The sidebar can be toggled using the button above.
        </p>
        
        <div className="mt-6 grid grid-cols-1 md:grid-cols-3 gap-4">
          <div className="bg-white p-4 rounded-lg shadow">
            <h3 className="font-semibold">Total Users</h3>
            <p className="text-2xl text-blue-600">1,234</p>
          </div>
          <div className="bg-white p-4 rounded-lg shadow">
            <h3 className="font-semibold">Active Sessions</h3>
            <p className="text-2xl text-green-600">567</p>
          </div>
          <div className="bg-white p-4 rounded-lg shadow">
            <h3 className="font-semibold">Revenue</h3>
            <p className="text-2xl text-purple-600">$89,123</p>
          </div>
        </div>
      </div>
    </PageLayout>
  );
}

// Main app component
function App() {
  const currentUser = {
    id: '1',
    name: 'John Doe',
    email: '[e-mail]',
    avatar: 'https://example.com/avatar.jpg'
  };

  return (
    <AppLayout
      systemIcon={<YourCompanyLogo />}
      sidebarItems={sidebarItems}
      currentUser={currentUser}
      footerMenuItems={footerMenuItems}
      userMenuItems={userMenuItems}
      isHighlightHandler={(item) => item.link === window.location.pathname}
    >
      <DashboardPage />
    </AppLayout>
  );
}

export default App;

🎨 Styling

The package uses Tailwind CSS for styling. To ensure proper styling, add the following to your tailwind.config.js:

module.exports = {
  content: [
    // ... other content paths
    "./node_modules/@metadiv-studio/app-layout-001/**/*.{js,ts,jsx,tsx}",
  ],
  // ... rest of config
}

🔧 Dependencies

This package has the following peer dependencies:

• react ^18
• react-dom ^18

And includes these internal dependencies:

• @metadiv-studio/button ^0.9.0
• @metadiv-studio/context ^0.2.0
• @radix-ui/react-avatar ^1.1.10
• @radix-ui/react-dropdown-menu ^2.1.16
• @radix-ui/react-icons ^1.3.2

📱 Responsive Design

The layout automatically adapts to different screen sizes:

• Desktop: Full sidebar and header layout
• Tablet: Responsive sidebar with collapsible behavior
• Mobile: Mobile-optimized layout with touch-friendly interactions

🌙 Dark Mode

The package includes built-in dark mode support using CSS custom properties. Dark mode styles are automatically applied based on your application's theme configuration.

🚀 Performance

• Built with modern React patterns for optimal performance
• Efficient re-rendering with proper context usage
• Minimal bundle size impact
• Tree-shakeable exports

🤝 Contributing

This package is part of the Metadiv Studio ecosystem. For issues, feature requests, or contributions, please refer to the package repository.

📄 License

UNLICENSED - See package.json for details.