@medalsocial/meda 1.7.0 → 2.0.0

package/README.md

@@ -109,6 +109,8 @@ Workspace shells also expose chrome-level composition slots:
 
 `workspace.menuItems`, `workspace.menuFooter`, and the theme toggle are available from the mobile Menu drawer. Use `mainLayout`/`mainClassName` when a workspace shell needs the same mobile chrome but a custom main scroll region, such as a full-bleed marketing page. `useCommands()` works from workspace descendants without manually mounting `CommandPalette`; lower-level primitive compositions can still mount `CommandPalette` directly.
 
+`ContextRail` is usable for both navigation rails and custom rendered rails. Navigation rails show Meda's label header by default. Custom rendered rails hide the automatic visible header by default so consumers can render their own heading without duplication. Rail bodies scroll vertically by default; use `contextRail={{ header: "visible" }}` or `contextRail={{ scroll: "none" }}` when you need explicit control.
+
 ## Foundation primitives
 
 Meda includes small foundation primitives for repeated loading, empty, and filtering surfaces:
@@ -126,7 +128,6 @@ npx shadcn add https://meda.medalsocial.com/r/meda-skeleton.json
 npx shadcn add https://meda.medalsocial.com/r/meda-empty-state.json
 npx shadcn add https://meda.medalsocial.com/r/meda-filter-rail.json
 ```
-
 For app-scoped brand tokens:
 
 ```ts

package/dist/shell/app-shell-workspace.js

@@ -39,7 +39,7 @@ export function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace
     // <AppShell> wrapper already enforces h-screen for the workspace variant, so
     // nested viewport-height divs collapse cleanly — no double-scroll.
     const commandRegistry = useContext(CommandRegistryContext);
-    const shell = (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions, headerCenter: headerCenter, appTabsRenderLink: appTabs?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })), banners ? (_jsx("div", { "data-meda-banners": "", className: "flex-shrink-0", children: banners })) : (false), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId })), _jsx(ShellMain, { layout: mainLayout ?? 'workspace', className: mainClassName, children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter, module: contextRail?.module, moduleAppId: contextRail?.appId, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
+    const shell = (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions, headerCenter: headerCenter, appTabsRenderLink: appTabs?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })), banners ? (_jsx("div", { "data-meda-banners": "", className: "flex-shrink-0", children: banners })) : (false), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId, header: contextRail.header, scroll: contextRail.scroll })), _jsx(ShellMain, { layout: mainLayout ?? 'workspace', className: mainClassName, children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter, module: contextRail?.module, moduleAppId: contextRail?.appId, moduleHeader: contextRail?.header, moduleScroll: contextRail?.scroll, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
     return commandRegistry ? shell : _jsx(CommandPalette, { children: shell });
 }
 function buildMobileNavItems(contextRail, panelViews) {

package/dist/shell/context-rail.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { ContextModule, ShellLinkRenderArgs } from './types.js';
+import type { ContextModule, ContextRailHeader, ContextRailScroll, ShellLinkRenderArgs } from './types.js';
 export interface ContextRailProps {
     /** Drives the persistence key for layout state. */
     appId: string;
@@ -12,6 +12,8 @@ export interface ContextRailProps {
     /** Optional active item id for nav active state (preferred over useMedaShell().selection). */
     activeItemId?: string;
     renderLink?: (args: ShellLinkRenderArgs) => ReactNode;
+    header?: ContextRailHeader;
+    scroll?: ContextRailScroll;
     className?: string;
 }
-export declare function ContextRail({ appId, module, hidden, collapsible, activeItemId, renderLink, className, }: ContextRailProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ContextRail({ appId, module, hidden, collapsible, activeItemId, renderLink, header, scroll, className, }: ContextRailProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/context-rail.js

@@ -75,7 +75,7 @@ function ContextRailToggle({ railId }) {
 // ---------------------------------------------------------------------------
 // ContextRail
 // ---------------------------------------------------------------------------
-export function ContextRail({ appId, module, hidden = false, collapsible = true, activeItemId, renderLink, className, }) {
+export function ContextRail({ appId, module, hidden = false, collapsible = true, activeItemId, renderLink, header = 'auto', scroll = 'auto', className, }) {
     const band = useShellViewport();
     const ctx = useMedaShell();
     // collapsible={false} means the rail must always render expanded — even if
@@ -92,6 +92,8 @@ export function ContextRail({ appId, module, hidden = false, collapsible = true,
     const [displayWidth, setDisplayWidth] = useState(null);
     const width = displayWidth ?? ctx.contextRail.width;
     const items = module?.items ?? [];
+    const hasRender = typeof module?.render === 'function';
+    const showHeader = header === 'visible' || (header === 'auto' && items.length > 0 && !hasRender);
     if (band === 'mobile')
         return null;
     if (hidden) {
@@ -113,22 +115,28 @@ export function ContextRail({ appId, module, hidden = false, collapsible = true,
     // transition then so the rail snaps to the cursor instead of lagging
     // behind it.
     const isDragging = displayWidth !== null;
-    return (_jsxs("aside", { id: railId, "data-testid": "context-rail", "aria-label": module.label, className: cn('relative h-full shrink-0 border-r border-shell-border bg-shell-context', !isDragging && 'transition-[width] duration-200 ease-in-out motion-reduce:transition-none', collapsed && 'w-0', className), style: { width: collapsed ? 0 : width }, children: [collapsible && _jsx(ContextRailToggle, { railId: railId }), _jsxs("div", { className: "h-full overflow-hidden", "aria-hidden": collapsed, inert: collapsed || undefined, children: [_jsxs("div", { className: "border-b border-shell-border px-4 py-3", children: [_jsx("h2", { className: "text-sm font-semibold text-foreground", children: module.label }), module.description && (_jsx("p", { className: "mt-0.5 text-xs text-muted-foreground", children: module.description }))] }), items.length > 0 && (_jsx("nav", { "aria-label": `${module.label} navigation`, className: "flex flex-col gap-0.5 p-2", children: items.map((item) => {
-                            const isActive = item.id === activeItemId;
-                            const klass = cn('flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors', isActive
-                                ? 'bg-primary/10 text-primary'
-                                : 'text-muted-foreground hover:bg-accent hover:text-foreground');
-                            const IconComp = item.icon;
-                            const inner = (_jsxs(_Fragment, { children: [_jsx(IconComp, { size: 16, "aria-hidden": "true", className: "shrink-0" }), _jsx("span", { className: "truncate", children: item.label }), item.shortcut && (_jsx("kbd", { className: "ml-auto font-mono text-[10px] text-muted-foreground", children: item.shortcut }))] }));
-                            const linkProps = {
-                                href: item.to,
-                                'aria-current': isActive ? 'page' : undefined,
-                                className: klass,
-                                children: inner,
-                            };
-                            if (renderLink) {
-                                return (_jsx(Fragment, { children: renderLink({ item, isActive, className: klass, children: inner, linkProps }) }, item.id));
-                            }
-                            return _jsx("a", { ...linkProps }, item.id);
-                        }) })), module.render?.({ workspaceId: ctx.workspace.id, appId })] }), !collapsed && (_jsx(ResizeHandle, { currentWidth: width, onResize: handleResize, onCommit: handleCommit }))] }));
+    return (_jsxs("aside", { id: railId, "data-testid": "context-rail", "aria-label": module.label, className: cn('relative h-full shrink-0 border-r border-shell-border bg-shell-context', !isDragging && 'transition-[width] duration-200 ease-in-out motion-reduce:transition-none', collapsed && 'w-0', className), style: { width: collapsed ? 0 : width }, children: [collapsible && _jsx(ContextRailToggle, { railId: railId }), _jsxs("div", { className: "flex h-full min-w-0 flex-col overflow-hidden", "aria-hidden": collapsed, inert: collapsed || undefined, children: [showHeader && (_jsxs("div", { className: "shrink-0 border-b border-shell-border px-4 py-3", children: [_jsx("h2", { className: "text-sm font-semibold text-foreground", children: module.label }), module.description && (_jsx("p", { className: "mt-0.5 text-xs text-muted-foreground", children: module.description }))] })), _jsxs("div", { "data-meda-context-rail-scroll-area": "", className: cn('min-h-0 flex-1', scroll === 'auto' ? 'overflow-y-auto overflow-x-hidden' : 'overflow-hidden'), children: [items.length > 0 && (_jsx("nav", { "aria-label": `${module.label} navigation`, className: "flex flex-col gap-0.5 p-2", children: items.map((item) => {
+                                    const isActive = item.id === activeItemId;
+                                    const klass = cn('flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors', isActive
+                                        ? 'bg-primary/10 text-primary'
+                                        : 'text-muted-foreground hover:bg-accent hover:text-foreground');
+                                    const IconComp = item.icon;
+                                    const inner = (_jsxs(_Fragment, { children: [_jsx(IconComp, { size: 16, "aria-hidden": "true", className: "shrink-0" }), _jsx("span", { className: "truncate", children: item.label }), item.shortcut && (_jsx("kbd", { className: "ml-auto font-mono text-[10px] text-muted-foreground", children: item.shortcut }))] }));
+                                    const linkProps = {
+                                        href: item.to,
+                                        'aria-current': isActive ? 'page' : undefined,
+                                        className: klass,
+                                        children: inner,
+                                    };
+                                    if (renderLink) {
+                                        return (_jsx(Fragment, { children: renderLink({
+                                                item,
+                                                isActive,
+                                                className: klass,
+                                                children: inner,
+                                                linkProps,
+                                            }) }, item.id));
+                                    }
+                                    return _jsx("a", { ...linkProps }, item.id);
+                                }) })), module.render?.({ workspaceId: ctx.workspace.id, appId })] })] }), !collapsed && (_jsx(ResizeHandle, { currentWidth: width, onResize: handleResize, onCommit: handleCommit }))] }));
 }

package/dist/shell/index.d.ts

@@ -27,5 +27,5 @@ export type { MedaShellProviderProps } from './shell-provider.js';
 export { MedaShellProvider, useMedaShell, useShellSelection } from './shell-provider.js';
 export { DefaultThemeProvider, ThemeToggle, useTheme } from './theme.js';
 export { NextThemesAdapter } from './theme-next-themes.js';
-export type { AppDefinition, AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, AppTabRenderLinkArgs, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
+export type { AppDefinition, AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, AppTabRenderLinkArgs, CommandDefinition, ContextItem, ContextModule, ContextRailHeader, ContextRailScroll, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
 export { useShellViewport } from './use-shell-viewport.js';

package/dist/shell/internal/mobile-drawers.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import type { IconRailItem, IconRailProps } from '../icon-rail.js';
-import type { ContextModule, PanelView, WorkspaceMenuItem } from '../types.js';
+import type { ContextModule, ContextRailHeader, ContextRailScroll, PanelView, WorkspaceMenuItem } from '../types.js';
 export interface MobileDrawersProps {
     /** Menu drawer source (icon-rail items). */
     menuItems?: IconRailItem[];
@@ -16,6 +16,10 @@ export interface MobileDrawersProps {
     module?: ContextModule;
     /** App id used when rendering module custom content. */
     moduleAppId?: string;
+    /** Header behavior mirrored from the desktop ContextRail. */
+    moduleHeader?: ContextRailHeader;
+    /** Scroll behavior mirrored from the desktop ContextRail. */
+    moduleScroll?: ContextRailScroll;
     /** Panels drawer source. */
     panelViews?: PanelView[];
     /**
@@ -33,4 +37,4 @@ export interface MobileDrawersProps {
  * any custom-content drawers. Mount once near the AppShell root; drawers
  * open/close via `ctx.mobileDrawer.open` provider state.
  */
-export declare function MobileDrawers({ menuItems, menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;
+export declare function MobileDrawers({ menuItems, menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, moduleHeader, moduleScroll, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/internal/mobile-drawers.js

@@ -11,7 +11,7 @@ import { useTheme } from '../theme.js';
  * any custom-content drawers. Mount once near the AppShell root; drawers
  * open/close via `ctx.mobileDrawer.open` provider state.
  */
-export function MobileDrawers({ menuItems = [], menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, panelViews = [], defaultView, customContent = {}, }) {
+export function MobileDrawers({ menuItems = [], menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, moduleHeader, moduleScroll, panelViews = [], defaultView, customContent = {}, }) {
     const ctx = useMedaShell();
     const open = ctx.mobileDrawer.open;
     const setOpen = ctx.mobileDrawer.setOpen;
@@ -24,7 +24,7 @@ export function MobileDrawers({ menuItems = [], menuActiveId, menuRenderLink, wo
         workspaceId: ctx.workspace.id,
         appId: moduleAppId ?? ctx.activeAppId,
     };
-    return (_jsxs(_Fragment, { children: [_jsx(MenuDrawer, { open: open === 'menu-drawer', onClose: close, items: menuItems, activeId: menuActiveId, renderLink: menuRenderLink, workspaceItems: workspaceMenuItems, workspaceFooter: workspaceMenuFooter }), _jsx(ModuleDrawer, { open: open === 'module-drawer', onClose: close, module: module, renderCtx: moduleRenderCtx }), _jsx(PanelsDrawer, { open: open === 'panels-drawer', onClose: close, panelViews: panelViews, defaultView: defaultView, renderCtx: renderCtx }), _jsx(AiDrawer, { open: open === 'ai-drawer', onClose: close, panelViews: panelViews, renderCtx: renderCtx }), Object.entries(customContent).map(([id, renderFn]) => (_jsx(Drawer, { open: open === id, onOpenChange: (o) => !o && close(), direction: "bottom", children: _jsx(DrawerContent, { children: renderFn(close) }) }, id)))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(MenuDrawer, { open: open === 'menu-drawer', onClose: close, items: menuItems, activeId: menuActiveId, renderLink: menuRenderLink, workspaceItems: workspaceMenuItems, workspaceFooter: workspaceMenuFooter }), _jsx(ModuleDrawer, { open: open === 'module-drawer', onClose: close, module: module, renderCtx: moduleRenderCtx, header: moduleHeader, scroll: moduleScroll }), _jsx(PanelsDrawer, { open: open === 'panels-drawer', onClose: close, panelViews: panelViews, defaultView: defaultView, renderCtx: renderCtx }), _jsx(AiDrawer, { open: open === 'ai-drawer', onClose: close, panelViews: panelViews, renderCtx: renderCtx }), Object.entries(customContent).map(([id, renderFn]) => (_jsx(Drawer, { open: open === id, onOpenChange: (o) => !o && close(), direction: "bottom", children: _jsx(DrawerContent, { children: renderFn(close) }) }, id)))] }));
 }
 // ---------------------------------------------------------------------------
 // Internal sub-drawers
@@ -110,14 +110,17 @@ function MobileThemeMenuItem({ onClose }) {
             onClose();
         }, children: [_jsx(Icon, { size: 18, "aria-hidden": "true" }), _jsx("span", { children: THEME_LABEL[theme] })] }));
 }
-function ModuleDrawer({ open, onClose, module, renderCtx, }) {
+function ModuleDrawer({ open, onClose, module, renderCtx, header = 'auto', scroll = 'auto', }) {
     const items = module?.items ?? [];
     if (!module || (items.length === 0 && !module.render))
         return null;
-    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "left", children: _jsxs(DrawerContent, { children: [_jsxs(DrawerHeader, { children: [_jsx(DrawerTitle, { children: module.label }), module.description && (_jsx(DrawerDescription, { className: "text-muted-foreground text-xs", children: module.description }))] }), items.length > 0 && (_jsx("nav", { className: "flex flex-col gap-0.5 p-2", children: items.map((item) => {
-                        const Icon = item.icon;
-                        return (_jsxs("a", { href: item.to, onClick: onClose, className: "flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground", children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), _jsx("span", { children: item.label })] }, item.id));
-                    }) })), module.render?.(renderCtx)] }) }));
+    const hasRender = typeof module.render === 'function';
+    const showHeader = header === 'visible' || (header === 'auto' && items.length > 0 && !hasRender);
+    const title = (_jsxs(_Fragment, { children: [_jsx(DrawerTitle, { className: showHeader ? undefined : 'sr-only', children: module.label }), module.description && (_jsx(DrawerDescription, { className: showHeader ? 'text-muted-foreground text-xs' : 'sr-only', children: module.description }))] }));
+    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "left", children: _jsxs(DrawerContent, { children: [showHeader ? _jsx(DrawerHeader, { children: title }) : title, _jsxs("div", { "data-meda-context-rail-scroll-area": "", className: cn('min-h-0 flex-1', scroll === 'auto' ? 'overflow-y-auto overflow-x-hidden' : 'overflow-hidden'), children: [items.length > 0 && (_jsx("nav", { className: "flex flex-col gap-0.5 p-2", children: items.map((item) => {
+                                const Icon = item.icon;
+                                return (_jsxs("a", { href: item.to, onClick: onClose, className: "flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground", children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), _jsx("span", { children: item.label })] }, item.id));
+                            }) })), module.render?.(renderCtx)] })] }) }));
 }
 function PanelsDrawer({ open, onClose, panelViews, defaultView, renderCtx, }) {
     const ctx = useMedaShell();

package/dist/shell/shell-provider.js

@@ -107,63 +107,79 @@ export function MedaShellProvider(props) {
         storage,
     });
     const isMobile = useShellViewport() === 'mobile';
+    const setPanelMode = useCallback((mode) => setLayoutState((prev) => ({
+        ...prev,
+        rightPanel: { ...prev.rightPanel, mode },
+    })), [setLayoutState]);
+    const setPanelActiveView = useCallback((activeView) => setLayoutState((prev) => ({
+        ...prev,
+        rightPanel: { ...prev.rightPanel, activeView },
+    })), [setLayoutState]);
+    const setPanelWidth = useCallback((width) => setLayoutState((prev) => ({
+        ...prev,
+        rightPanel: { ...prev.rightPanel, width },
+    })), [setLayoutState]);
+    const openPanel = useCallback(() => {
+        if (isMobile)
+            setMobileDrawerOpen('panels-drawer');
+        setLayoutState((prev) => ({
+            ...prev,
+            rightPanel: {
+                ...prev.rightPanel,
+                mode: prev.rightPanel.mode === 'closed' ? 'panel' : prev.rightPanel.mode,
+            },
+        }));
+    }, [isMobile, setLayoutState]);
+    const closePanel = useCallback(() => {
+        if (isMobile)
+            setMobileDrawerOpen((open) => (open === 'panels-drawer' ? null : open));
+        setLayoutState((prev) => ({
+            ...prev,
+            rightPanel: { ...prev.rightPanel, mode: 'closed' },
+        }));
+    }, [isMobile, setLayoutState]);
+    const togglePanel = useCallback(() => {
+        if (isMobile) {
+            setMobileDrawerOpen((open) => (open === 'panels-drawer' ? null : 'panels-drawer'));
+        }
+        setLayoutState((prev) => ({
+            ...prev,
+            rightPanel: {
+                ...prev.rightPanel,
+                mode: prev.rightPanel.mode === 'closed' ? 'panel' : 'closed',
+            },
+        }));
+    }, [isMobile, setLayoutState]);
+    const focusPanel = useCallback((viewId) => setLayoutState((prev) => {
+        const nextMode = prev.rightPanel.mode === 'closed' ? 'panel' : prev.rightPanel.mode;
+        return {
+            ...prev,
+            rightPanel: { ...prev.rightPanel, mode: nextMode, activeView: viewId },
+        };
+    }), [setLayoutState]);
     const panel = useMemo(() => ({
         mode: layoutState.rightPanel.mode,
         activeView: layoutState.rightPanel.activeView,
         width: layoutState.rightPanel.width,
-        setMode: (mode) => setLayoutState((prev) => ({
-            ...prev,
-            rightPanel: { ...prev.rightPanel, mode },
-        })),
-        setActiveView: (activeView) => setLayoutState((prev) => ({
-            ...prev,
-            rightPanel: { ...prev.rightPanel, activeView },
-        })),
-        setWidth: (width) => setLayoutState((prev) => ({
-            ...prev,
-            rightPanel: { ...prev.rightPanel, width },
-        })),
-        open: () => {
-            if (isMobile)
-                setMobileDrawerOpen('panels-drawer');
-            setLayoutState((prev) => ({
-                ...prev,
-                rightPanel: {
-                    ...prev.rightPanel,
-                    mode: prev.rightPanel.mode === 'closed' ? 'panel' : prev.rightPanel.mode,
-                },
-            }));
-        },
-        close: () => {
-            if (isMobile)
-                setMobileDrawerOpen((open) => (open === 'panels-drawer' ? null : open));
-            setLayoutState((prev) => ({
-                ...prev,
-                rightPanel: { ...prev.rightPanel, mode: 'closed' },
-            }));
-        },
-        toggle: () => {
-            if (isMobile) {
-                setMobileDrawerOpen((open) => (open === 'panels-drawer' ? null : 'panels-drawer'));
-            }
-            setLayoutState((prev) => ({
-                ...prev,
-                rightPanel: {
-                    ...prev.rightPanel,
-                    mode: prev.rightPanel.mode === 'closed' ? 'panel' : 'closed',
-                },
-            }));
-        },
-        // focus(viewId) — opens panel + switches to view in one call.
-        // Only flips closed → panel; preserves expanded / fullscreen modes.
-        focus: (viewId) => setLayoutState((prev) => {
-            const nextMode = prev.rightPanel.mode === 'closed' ? 'panel' : prev.rightPanel.mode;
-            return {
-                ...prev,
-                rightPanel: { ...prev.rightPanel, mode: nextMode, activeView: viewId },
-            };
-        }),
-    }), [isMobile, layoutState, setLayoutState]);
+        setMode: setPanelMode,
+        setActiveView: setPanelActiveView,
+        setWidth: setPanelWidth,
+        open: openPanel,
+        close: closePanel,
+        toggle: togglePanel,
+        focus: focusPanel,
+    }), [
+        layoutState.rightPanel.mode,
+        layoutState.rightPanel.activeView,
+        layoutState.rightPanel.width,
+        setPanelMode,
+        setPanelActiveView,
+        setPanelWidth,
+        openPanel,
+        closePanel,
+        togglePanel,
+        focusPanel,
+    ]);
     const contextRail = useMemo(() => ({
         width: layoutState.contextRail.width,
         collapsed: layoutState.contextRail.collapsed,

package/dist/shell/types.d.ts

@@ -50,6 +50,8 @@ export interface PanelView {
 export type PanelMode = 'closed' | 'panel' | 'expanded' | 'fullscreen';
 export type ShellMainLayout = 'workspace' | 'centered' | 'fullbleed';
 export type ShellViewport = 'mobile' | 'tablet' | 'desktop' | 'wide' | 'ultrawide';
+export type ContextRailHeader = 'auto' | 'visible' | 'hidden';
+export type ContextRailScroll = 'auto' | 'none';
 export interface MobileBottomNavItem {
     id: string;
     label: string | (() => string);
@@ -103,6 +105,8 @@ export interface AppShellContextRailConfig {
     appId: string;
     module: ContextModule;
     activeItemId?: string;
+    header?: ContextRailHeader;
+    scroll?: ContextRailScroll;
 }
 /** RightPanel configuration for `<AppShell variant="workspace">`. */
 export interface AppShellRightPanelConfig {

package/dist/shell/use-shell-viewport.js

@@ -7,11 +7,18 @@ const BREAKPOINTS = {
     wide: '(min-width: 1280px) and (max-width: 1535px)',
     ultrawide: '(min-width: 1536px)',
 };
-function detectViewport() {
+function getMatchMedia() {
     if (typeof window === 'undefined')
+        return null;
+    if (typeof window.matchMedia !== 'function')
+        return null;
+    return window.matchMedia.bind(window);
+}
+function detectViewport(matchMedia = getMatchMedia()) {
+    if (!matchMedia)
         return 'desktop';
     for (const [band, query] of Object.entries(BREAKPOINTS)) {
-        if (window.matchMedia(query).matches)
+        if (matchMedia(query).matches)
             return band;
     }
     return 'desktop';
@@ -21,9 +28,12 @@ export function useShellViewport() {
     // client's first paint — actual band resolves in the post-mount effect.
     const [viewport, setViewport] = useState('desktop');
     useEffect(() => {
-        setViewport(detectViewport());
+        const matchMedia = getMatchMedia();
+        setViewport(detectViewport(matchMedia));
+        if (!matchMedia)
+            return;
         const cleanups = Object.entries(BREAKPOINTS).map(([band, query]) => {
-            const mql = window.matchMedia(query);
+            const mql = matchMedia(query);
             const onChange = () => {
                 if (mql.matches)
                     setViewport(band);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/meda",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "description": "Shared Meda UI shell and runtime package.",
   "license": "Apache-2.0",
   "repository": {