feat: implement CoreAppShell component with flexible layout configurations and state management context

apps/web/src/apps/index.tsx

@@ -6,6 +6,7 @@ import { NotFound, Forbidden, Maintenance, ComingSoon } from '@repo/ui/component
 const AuthModule = lazy(() => import('./auth'));
 const AppModule = lazy(() => import('./modules'));
 const ShowcaseView = lazy(() => import('./showcase/showcase-view'));
+const ShellDemo = lazy(() => import('./shell-demo'));
 
 export default function App() {
   const [colorScheme, setColorScheme] = useState<ColorSchemeType>('light');
@@ -29,6 +30,7 @@ export default function App() {
                 />
               }
             />
+            <Route path="/shell-demo" element={<ShellDemo />} />
             <Route path="/404" element={<NotFound />} />
             <Route path="/403" element={<Forbidden />} />
             <Route path="/maintenance" element={<Maintenance />} />

apps/web/src/apps/shell-demo/index.tsx

@@ -0,0 +1,306 @@
+import { useState, useMemo, ReactNode } from 'react';
+import { Link } from 'react-router-dom';
+import { ArrowLeft } from 'lucide-react';
+import { 
+  Box, 
+  Button, 
+  Group, 
+  SegmentedControl, 
+  Stack, 
+  Text, 
+  Paper,
+  Switch,
+  Select,
+  Burger
+} from '@repo/ui/components';
+import { 
+  CoreAppShell, 
+  CorePageContainer, 
+  CoreAppShellConfig, 
+  LayoutVariant, 
+  DesktopCollapseVariant,
+  useCoreAppShell
+} from '@repo/ui/components';
+import { Home, BarChart2, Settings as SettingsIcon } from 'lucide-react';
+
+// Sub-component to test hook methods
+function LayoutControls() {
+  const { toggleDesktop, toggleMobile, sidebarVariant, setSidebarVariant, toggleAside, toggleNavbarPanel } = useCoreAppShell();
+
+  return (
+    <Group mb="md">
+      <Button onClick={toggleDesktop} variant="default" size="xs">Toggle Desktop Sidebar</Button>
+      <Button onClick={toggleMobile} variant="default" size="xs" hiddenFrom="sm">Toggle Mobile Sidebar</Button>
+      <Button 
+        onClick={() => setSidebarVariant(sidebarVariant === 'expanded' ? 'mini' : 'expanded')} 
+        variant="default"
+        size="xs"
+      >
+        Toggle Sidebar Variant (Current: {sidebarVariant})
+      </Button>
+      <Button onClick={toggleNavbarPanel} variant="light" color="grape" size="xs">
+        Toggle Secondary Panel (Double Sidebar)
+      </Button>
+      <Button onClick={toggleAside} variant="filled" color="cyan" size="xs">
+        Toggle Aside via Context
+      </Button>
+    </Group>
+  );
+}
+
+function MockHeader() {
+  const { mobileOpened, toggleMobile } = useCoreAppShell();
+  return (
+    <Group h="100%" px="md" justify="space-between" bg="green.1" c="green.9" style={{ borderBottom: '1px solid var(--mantine-color-green-3)' }}>
+      <Group>
+        <Burger opened={mobileOpened} onClick={toggleMobile} hiddenFrom="sm" size="sm" />
+        <Text fw={700} size="lg">Mock Header (bg="green.1")</Text>
+      </Group>
+    </Group>
+  );
+}
+
+function MockMobileDrawer() {
+  return (
+    <Box p="md" h="100%" bg="yellow.1" c="yellow.9">
+      <Text fw={700} mb="sm">Mock Mobile Drawer (bg="yellow.1")</Text>
+      <Stack gap="xs">
+        <Button variant="light" color="yellow" justify="flex-start" fullWidth>Mobile Dashboard</Button>
+        <Button variant="light" color="yellow" justify="flex-start" fullWidth>Mobile Settings</Button>
+      </Stack>
+    </Box>
+  );
+}
+
+function SettingRow({ title, description, control }: { title: string; description: string; control: ReactNode }) {
+  return (
+    <Paper withBorder p="md" radius="md">
+      <Group justify="space-between" wrap="nowrap">
+        <Stack gap={0}>
+          <Text fw={500}>{title}</Text>
+          <Text c="dimmed" size="sm">{description}</Text>
+        </Stack>
+        <Box>{control}</Box>
+      </Group>
+    </Paper>
+  );
+}
+
+export default function ShellDemo() {
+  const [layoutVariant, setLayoutVariant] = useState<LayoutVariant>('header-first');
+  const [collapseVariant, setCollapseVariant] = useState<DesktopCollapseVariant>('hide');
+  const [withUtilityBar, setWithUtilityBar] = useState(true);
+  const [withAside, setWithAside] = useState(true);
+  const [withFooter, setWithFooter] = useState(true);
+  const [withDoubleSidebar, setWithDoubleSidebar] = useState(true);
+  const [copied, setCopied] = useState(false);
+
+  const liveConfig = useMemo(() => {
+    return {
+      variant: layoutVariant,
+      features: {
+        desktopCollapseVariant: collapseVariant,
+        withUtilityBar: withUtilityBar ? undefined : false,
+        withAside: withAside ? undefined : false,
+        withFooter: withFooter ? undefined : false,
+        withDoubleSidebar,
+      }
+    };
+  }, [layoutVariant, collapseVariant, withUtilityBar, withAside, withFooter, withDoubleSidebar]);
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(JSON.stringify(liveConfig, null, 2));
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2500);
+  };
+
+  const config: CoreAppShellConfig = {
+    variant: layoutVariant,
+    features: {
+      desktopCollapseVariant: collapseVariant,
+      withUtilityBar: withUtilityBar ? undefined : false,
+      withAside: withAside ? undefined : false,
+      withFooter: withFooter ? undefined : false,
+      withDoubleSidebar,
+      persistState: false, // Don't persist for the demo to avoid confusing other showcases
+      disabled: false,     // Allow nested render overrides if needed
+      zIndex: 100,
+    }
+  };
+
+  return (
+    <CoreAppShell
+      config={config}
+    
+          slots={{
+            utilityBar: (
+              <Group h="100%" px="md" justify="flex-end" bg="blue.1" c="blue.9">
+                <Text size="xs" fw={600}>Mock Utility Bar (bg="blue.1")</Text>
+              </Group>
+            ),
+            header: <MockHeader />,
+            navbarMobile: <MockMobileDrawer />,
+            navbar: !withDoubleSidebar ? (
+              <Box p="md" h="100%" bg="grape.1" c="grape.9" style={{ borderRight: '1px solid var(--mantine-color-grape-3)' }}>
+                <Text fw={700} mb="sm">Mock Standard Navbar (bg="grape.1")</Text>
+                <Stack gap="xs">
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Dashboard</Button>
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Users</Button>
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Reports</Button>
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Settings</Button>
+                </Stack>
+              </Box>
+            ) : undefined,
+            navbarRail: withDoubleSidebar ? (
+              <Stack align="center" gap="lg" pt="md" h="100%" bg="orange.1" c="orange.9">
+                <Text size="xs" fw={700} style={{ writingMode: 'vertical-rl', transform: 'rotate(180deg)' }}>
+                  Mock Rail (bg="orange.1")
+                </Text>
+                <Home size={24} />
+                <BarChart2 size={24} />
+                <SettingsIcon size={24} />
+              </Stack>
+            ) : undefined,
+            navbarPanel: withDoubleSidebar ? (
+              <Box p="md" h="100%" bg="grape.1" c="grape.9" style={{ borderRight: '1px solid var(--mantine-color-grape-3)' }}>
+                <Text fw={700} mb="sm">Mock Panel (bg="grape.1")</Text>
+                <Stack gap="xs">
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Dashboard</Button>
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Users</Button>
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Reports</Button>
+                  <Button variant="light" color="grape" justify="flex-start" fullWidth>Settings</Button>
+                </Stack>
+              </Box>
+            ) : undefined,
+            aside: (
+              <Box p="md" h="100%" bg="cyan.1" c="cyan.9">
+                <Text fw={700} mb="md">Mock Aside</Text>
+                <Text size="sm">This area could be used for notifications, help text, or contextual settings.</Text>
+              </Box>
+            ),
+            footer: (
+              <Group h="100%" px="md" justify="space-between" bg="gray.1" style={{ borderTop: '1px solid var(--mantine-color-default-border)' }}>
+                <Text size="sm" fw={600}>Mock Footer (bg="gray.1")</Text>
+              </Group>
+            ),
+        
+
+          }}
+      >
+        <CorePageContainer
+          headerSlot={
+            <Group justify="space-between" align="center">
+              <Text component="h1" size="xl" fw={700} m={0}>
+                Layout Engine Interactive Demo
+              </Text>
+              <Group>
+                <Button component={Link} to="/showcase" leftSection={<ArrowLeft size={16} />} variant="default">
+                  Back to Showcase
+                </Button>
+              </Group>
+            </Group>
+          }
+          stickyHeader
+        >
+          <Stack gap="md">
+            <Paper withBorder p="md" bg="var(--mantine-color-gray-0)">
+              <LayoutControls />
+            </Paper>
+
+            <SettingRow 
+              title="Layout Variant"
+              description="Switch between standard cloud or SaaS layout styles."
+              control={
+                <Select
+                  value={layoutVariant}
+                  onChange={(value) => setLayoutVariant((value as LayoutVariant) || 'sidebar-first')}
+                  data={[
+                    { label: 'Sidebar First (Alt)', value: 'sidebar-first' },
+                    { label: 'Header First (Default)', value: 'header-first' },
+                    { label: 'Top Nav (Hidden Sidebar)', value: 'top-nav' },
+                  ]}
+                />
+              }
+            />
+
+            <SettingRow 
+              title="Desktop Collapse Strategy"
+              description="Determine if the sidebar shrinks to icons or slides out completely."
+              control={
+                <SegmentedControl
+                  value={collapseVariant}
+                  onChange={(value) => setCollapseVariant(value as DesktopCollapseVariant)}
+                  data={[
+                    { label: 'Hide (Slide Out)', value: 'hide' },
+                    { label: 'Mini (Shrink)', value: 'mini' },
+                  ]}
+                />
+              }
+            />
+
+            <SettingRow 
+              title="Enable Double Sidebar"
+              description="Activate the Google-style rail and contextual panel navigation."
+              control={
+                <Switch
+                  checked={withDoubleSidebar}
+                  onChange={(event) => setWithDoubleSidebar(event.currentTarget.checked)}
+                />
+              }
+            />
+
+            <SettingRow 
+              title="Render Utility Bar"
+              description="Show a system-level announcement bar above the main header."
+              control={
+                <Switch
+                  checked={withUtilityBar}
+                  onChange={(event) => setWithUtilityBar(event.currentTarget.checked)}
+                />
+              }
+            />
+
+            <SettingRow 
+              title="Render Aside"
+              description="Toggle the right-hand properties or filter panel."
+              control={
+                <Switch
+                  checked={withAside}
+                  onChange={(event) => setWithAside(event.currentTarget.checked)}
+                />
+              }
+            />
+
+            <SettingRow 
+              title="Render Footer"
+              description="Toggle the bottom application footer."
+              control={
+                <Switch
+                  checked={withFooter}
+                  onChange={(event) => setWithFooter(event.currentTarget.checked)}
+                />
+              }
+            />
+
+            <Box mt="xl">
+              <Group justify="space-between" mb="sm">
+                <Text fw={700} size="lg">Configuration Preview</Text>
+                <Button 
+                    variant={copied ? 'filled' : 'light'} 
+                    color={copied ? 'teal' : 'blue'} 
+                    size="xs" 
+                    onClick={handleCopy}
+                  >
+                    {copied ? 'Copied to Clipboard!' : 'Copy JSON'}
+                  </Button>
+              </Group>
+              <Paper withBorder p="md" bg="dark.8" c="gray.0" style={{ fontFamily: 'monospace', overflowX: 'auto' }}>
+                <pre style={{ margin: 0 }}>{JSON.stringify(liveConfig, null, 2)}</pre>
+              </Paper>
+            </Box>
+
+          </Stack>
+        </CorePageContainer>
+      </CoreAppShell>
+  );
+}

apps/web/src/apps/showcase/showcase-view.tsx

@@ -1,4 +1,5 @@
 import { useState } from 'react';
+import { useNavigate } from 'react-router-dom';
 import { ColorSchemeType, DensityType } from '@repo/ui/provider';
 import {
   Button,
@@ -41,6 +42,7 @@ interface ShowcaseViewProps {
 export default function ShowcaseView({ colorScheme, setColorScheme, density, setDensity }: ShowcaseViewProps) {
   const [activeTab, setActiveTab] = useState<string | null>('ui-components');
   const { i18n } = useTranslation();
+  const navigate = useNavigate();
 
   // Mock data for the table
   const tableData = [
@@ -65,6 +67,8 @@ export default function ShowcaseView({ colorScheme, setColorScheme, density, set
         return 'Global Event Bus Synchronization';
       case 'hardware':
         return 'Hardware Integration & Printers';
+      case 'layout-engine':
+        return 'Core Layout Engine & Variants';
       default:
         return 'Architecture Showcase';
     }
@@ -76,7 +80,13 @@ export default function ShowcaseView({ colorScheme, setColorScheme, density, set
         orientation="vertical"
         placement="left"
         value={activeTab}
-        onChange={setActiveTab}
+        onChange={(val) => {
+          if (val === 'layout-engine') {
+            navigate('/shell-demo');
+          } else {
+            setActiveTab(val);
+          }
+        }}
         variant="pills"
         radius="md"
         className="h-screen"
@@ -106,6 +116,9 @@ export default function ShowcaseView({ colorScheme, setColorScheme, density, set
           <Tabs.Tab value="ui-components" leftSection={<Layout size={18} />}>
             UI Components
           </Tabs.Tab>
+          <Tabs.Tab value="layout-engine" leftSection={<Layout size={18} />}>
+            Layout Engine
+          </Tabs.Tab>
           <Tabs.Tab value="forms" leftSection={<FileText size={18} />}>
             Form Engine
           </Tabs.Tab>
@@ -360,6 +373,8 @@ export default function ShowcaseView({ colorScheme, setColorScheme, density, set
                   </Card>
                 </Stack>
               )}
+
+
             </Container>
           </Box>
         </Tabs.Panel>

packages/ui/src/components/core-app-shell/core-app-shell-context.tsx

@@ -0,0 +1,70 @@
+import { createContext, useContext, useState, ReactNode } from 'react';
+import { useLocalStorage } from '@mantine/hooks';
+import { CoreAppShellConfig, SidebarVariant } from './types';
+
+interface CoreAppShellContextValue {
+  mobileOpened: boolean;
+  desktopOpened: boolean;
+  sidebarVariant: SidebarVariant;
+  asideOpened: boolean;
+  navbarPanelOpened: boolean;
+  config: CoreAppShellConfig;
+  toggleMobile: () => void;
+  toggleDesktop: () => void;
+  toggleAside: () => void;
+  toggleNavbarPanel: () => void;
+  setSidebarVariant: (variant: SidebarVariant) => void;
+}
+
+const CoreAppShellContext = createContext<CoreAppShellContextValue | null>(null);
+
+interface CoreAppShellProviderProps {
+  children: ReactNode;
+  config: CoreAppShellConfig;
+}
+
+export function CoreAppShellProvider({ children, config }: CoreAppShellProviderProps) {
+  const [mobileOpened, setMobileOpened] = useState(false);
+  const [desktopOpened, setDesktopOpened] = useState(true);
+  const [asideOpened, setAsideOpened] = useState(false);
+  const [navbarPanelOpened, setNavbarPanelOpened] = useState(true);
+
+  const [sidebarVariant, setSidebarVariant] = useLocalStorage<SidebarVariant>({
+    key: 'core-app-shell-sidebar-variant',
+    defaultValue: 'expanded',
+    getInitialValueInEffect: !config.features?.persistState,
+  });
+
+  const toggleMobile = () => setMobileOpened((o) => !o);
+  const toggleDesktop = () => setDesktopOpened((o) => !o);
+  const toggleAside = () => setAsideOpened((o) => !o);
+  const toggleNavbarPanel = () => setNavbarPanelOpened((o) => !o);
+
+  return (
+    <CoreAppShellContext.Provider
+      value={{
+        mobileOpened,
+        desktopOpened,
+        sidebarVariant,
+        asideOpened,
+        navbarPanelOpened,
+        config,
+        toggleMobile,
+        toggleDesktop,
+        toggleAside,
+        toggleNavbarPanel,
+        setSidebarVariant,
+      }}
+    >
+      {children}
+    </CoreAppShellContext.Provider>
+  );
+}
+
+export function useCoreAppShell() {
+  const context = useContext(CoreAppShellContext);
+  if (!context) {
+    throw new Error('useCoreAppShell must be used within CoreAppShellProvider');
+  }
+  return context;
+}

packages/ui/src/components/core-app-shell/core-app-shell.tsx

@@ -0,0 +1,205 @@
+import React, { useMemo } from 'react';
+import { AppShell, Flex, Box } from '@mantine/core';
+import { CoreAppShellProvider, useCoreAppShell } from './core-app-shell-context';
+import { CoreAppShellConfig, CoreAppShellSlots, CoreAppShellDimensions } from './types';
+
+
+const DEFAULT_DIMENSIONS: Required<CoreAppShellDimensions> = {
+  headerHeight: 60,
+  navbarWidth: 260,
+  navbarMiniWidth: 80,
+  navbarRailWidth: 54,
+  utilityBarHeight: 32,
+  asideWidth: 260,
+};
+
+interface CoreAppShellInnerProps {
+  slots: CoreAppShellSlots;
+  children: React.ReactNode;
+}
+
+function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
+  const { mobileOpened, desktopOpened, sidebarVariant, asideOpened, navbarPanelOpened, config } = useCoreAppShell();
+  const { variant, dimensions, features } = config;
+  const dims = { ...DEFAULT_DIMENSIONS, ...dimensions };
+
+  const isDoubleSidebar = features?.withDoubleSidebar;
+  const isTopNav = variant === 'top-nav';
+  const isFooterOffset = variant === 'header-first';
+  
+  // Calculate Navbar Width based on states
+  const navbarWidth = useMemo(() => {
+    if (isTopNav) return 0;
+    if (isDoubleSidebar) {
+      return navbarPanelOpened ? dims.navbarWidth : dims.navbarRailWidth;
+    }
+    if (sidebarVariant === 'mini' && dims.navbarMiniWidth) {
+      return dims.navbarMiniWidth;
+    }
+    return dims.navbarWidth;
+  }, [sidebarVariant, dims, isTopNav, isDoubleSidebar, navbarPanelOpened]);
+
+  // Determine AppShell Layout
+  const appShellLayout = variant === 'sidebar-first' ? 'alt' : 'default';
+  
+  // Smart defaults for slots
+  const showUtilityBar = (features?.withUtilityBar ?? Boolean(slots.utilityBar)) && Boolean(slots.utilityBar);
+  const showAside = (features?.withAside ?? Boolean(slots.aside)) && Boolean(slots.aside);
+  const showFooter = (features?.withFooter ?? Boolean(slots.footer)) && Boolean(slots.footer);
+
+  
+  // Header height needs to account for utility bar if present
+  const totalHeaderHeight = useMemo(() => {
+    if (!showUtilityBar) return dims.headerHeight;
+    // Basic summation assuming pixel values or numeric equivalents if both are numbers
+    if (typeof dims.headerHeight === 'number' && typeof dims.utilityBarHeight === 'number') {
+      return dims.headerHeight + dims.utilityBarHeight;
+    }
+    return `calc(${dims.headerHeight}${typeof dims.headerHeight === 'number' ? 'px' : ''} + ${dims.utilityBarHeight}${typeof dims.utilityBarHeight === 'number' ? 'px' : ''})`;
+  }, [dims.headerHeight, dims.utilityBarHeight, showUtilityBar]);
+
+  return (
+    <AppShell
+      layout={appShellLayout}
+      disabled={features?.disabled}
+      zIndex={features?.zIndex ?? 200}
+      header={{ height: totalHeaderHeight }}
+      navbar={
+        !isTopNav
+          ? {
+              width: navbarWidth,
+              breakpoint: 'sm',
+              collapsed: {
+                mobile: !mobileOpened,
+                desktop: features?.desktopCollapseVariant === 'hide' ? !desktopOpened : false,
+              },
+            }
+          : undefined
+      }
+      aside={
+        showAside && dims.asideWidth
+          ? {
+              width: dims.asideWidth,
+              breakpoint: 'sm',
+              collapsed: { mobile: !asideOpened, desktop: !asideOpened },
+            }
+          : undefined
+      }
+      footer={
+        showFooter
+          ? { height: 60 } // Example default footer height
+          : undefined
+      }
+      padding="md"
+    >
+      <AppShell.Header>
+        <Flex direction="column" h="100%">
+          {showUtilityBar && (
+            <Box h={dims.utilityBarHeight} display={{ base: 'none', sm: 'block' }}>
+              {slots.utilityBar}
+            </Box>
+          )}
+          <Box flex={1}>
+            {slots.header}
+          </Box>
+        </Flex>
+      </AppShell.Header>
+
+      {!isTopNav && (
+        <AppShell.Navbar
+          zIndex={isFooterOffset ? 105 : 100}
+          style={
+            isFooterOffset
+              ? {
+                  bottom: 0,
+                  height: 'calc(100dvh - var(--app-shell-header-offset, 0px))',
+                }
+              : undefined
+          }
+        >
+          <Box visibleFrom="sm" h="100%">
+            {isDoubleSidebar ? (
+              <Flex h="100%" direction="row" wrap="nowrap">
+                <Box 
+                  w={dims.navbarRailWidth} 
+                  h="100%" 
+                  style={{ 
+                    flexShrink: 0,
+                    borderRight: '1px solid var(--mantine-color-default-border)' 
+                  }}
+                >
+                  {slots.navbarRail}
+                </Box>
+                {navbarPanelOpened && (
+                  <Box flex={1} h="100%" style={{ overflow: 'hidden' }}>
+                    {slots.navbarPanel}
+                  </Box>
+                )}
+              </Flex>
+            ) : (
+              slots.navbar
+            )}
+          </Box>
+          <Box hiddenFrom="sm" h="100%">
+            {slots.navbarMobile || slots.navbar}
+          </Box>
+        </AppShell.Navbar>
+      )}
+
+      {showAside && (
+        <AppShell.Aside
+          zIndex={isFooterOffset ? 105 : 100}
+          style={
+            isFooterOffset
+              ? {
+                  bottom: 0,
+                  height: 'calc(100dvh - var(--app-shell-header-offset, 0px))',
+                }
+              : undefined
+          }
+        >
+          {slots.aside}
+        </AppShell.Aside>
+      )}
+
+      <AppShell.Main>
+        {children}
+      </AppShell.Main>
+
+      {showFooter && (
+        <AppShell.Footer
+          zIndex={isFooterOffset ? 100 : 105}
+          style={
+            isFooterOffset
+              ? {
+                  left: 'var(--app-shell-navbar-offset, 0px)',
+                  right: 'var(--app-shell-aside-offset, 0px)',
+                }
+              : {
+                  left: 0,
+                  right: 0,
+                }
+          }
+        >
+          {slots.footer}
+        </AppShell.Footer>
+      )}
+    </AppShell>
+  );
+}
+
+export interface CoreAppShellProps {
+  config: CoreAppShellConfig;
+  slots: CoreAppShellSlots;
+  children: React.ReactNode;
+}
+
+export function CoreAppShell({ config, slots, children }: CoreAppShellProps) {
+  return (
+    <CoreAppShellProvider config={config}>
+      <CoreAppShellInner slots={slots}>
+        {children}
+      </CoreAppShellInner>
+    </CoreAppShellProvider>
+  );
+}

packages/ui/src/components/core-app-shell/core-page-container.tsx

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+import { Box, Container, Stack, ContainerProps } from '@mantine/core';
+
+export interface CorePageContainerProps extends ContainerProps {
+  headerSlot?: ReactNode;
+  children: ReactNode;
+  stickyHeader?: boolean;
+}
+
+export function CorePageContainer({
+  headerSlot,
+  stickyHeader = false,
+  children,
+  px = "md",
+  py = "md",
+  ...others
+}: CorePageContainerProps) {
+  return (
+    <Box m="calc(var(--mantine-spacing-md) * -1)">
+      <Stack gap={0}>
+        {headerSlot && (
+          <Box
+            style={{
+              position: stickyHeader ? 'sticky' : 'static',
+              top: stickyHeader ? 'var(--app-shell-header-offset, 0px)' : undefined,
+              zIndex: stickyHeader ? 10 : undefined,
+              backgroundColor: 'var(--mantine-color-body)',
+              borderBottom: '1px solid var(--mantine-color-default-border)',
+            }}
+          >
+            <Container fluid px={px} py={py}>
+              {headerSlot}
+            </Container>
+          </Box>
+        )}
+
+        <Container fluid px={px} py={py} w="100%" {...others}>
+          {children}
+        </Container>
+      </Stack>
+    </Box>
+  );
+}

packages/ui/src/components/core-app-shell/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './core-app-shell-context';
+export * from './core-app-shell';
+export * from './core-page-container';

packages/ui/src/components/core-app-shell/types.ts

@@ -0,0 +1,42 @@
+import { ReactNode } from 'react';
+
+export type LayoutVariant = 'header-first' | 'sidebar-first' | 'top-nav';
+export type SidebarVariant = 'expanded' | 'mini' | 'hidden';
+export type DesktopCollapseVariant = 'hide' | 'mini';
+
+export interface CoreAppShellDimensions {
+  utilityBarHeight?: number | string;
+  headerHeight?: number | string;
+  navbarWidth?: number | string;
+  navbarMiniWidth?: number | string;
+  navbarRailWidth?: number | string;
+  asideWidth?: number | string;
+}
+
+export interface CoreAppShellFeatures {
+  desktopCollapseVariant?: DesktopCollapseVariant;
+  withUtilityBar?: boolean;
+  withAside?: boolean;
+  withFooter?: boolean;
+  withDoubleSidebar?: boolean;
+  persistState?: boolean;
+  zIndex?: number;
+  disabled?: boolean;
+}
+
+export interface CoreAppShellConfig {
+  variant: LayoutVariant;
+  dimensions?: CoreAppShellDimensions;
+  features?: CoreAppShellFeatures;
+}
+
+export interface CoreAppShellSlots {
+  utilityBar?: ReactNode;
+  header?: ReactNode;
+  navbar?: ReactNode;
+  navbarMobile?: ReactNode;
+  navbarRail?: ReactNode;
+  navbarPanel?: ReactNode;
+  aside?: ReactNode;
+  footer?: ReactNode;
+}

packages/ui/src/components/index.ts

@@ -9,3 +9,4 @@ export * from './system-pages/coming-soon';
 export * from './system-pages/forbidden';
 export * from './system-pages/maintenance';
 export * from './system-pages/not-found';
+export * from './core-app-shell';