@medalsocial/meda 1.6.0 → 2.0.0

package/README.md

@@ -109,6 +109,25 @@ 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:
+
+```tsx
+import { EmptyState, FilterRail, Skeleton } from '@medalsocial/meda';
+```
+
+`Skeleton` mirrors shadcn's simple loading placeholder shape. `EmptyState` standardizes zero/error states across panels and content areas. `FilterRail` provides a dense filter surface while leaving selected values, URL syncing, and query logic in the consuming app.
+
+The same primitives are available from the shadcn-compatible registry when an app wants local source ownership:
+
+```bash
+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/index.d.ts

@@ -3,6 +3,7 @@ export * from './brand/public.js';
 export * from './chat/public.js';
 export * from './marketing/public.js';
 export * from './panel/public.js';
+export * from './primitives/index.js';
 export * from './shell/index.js';
 export * from './theme/index.js';
 export * from './timeline/public.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './brand/public.js';
 export * from './chat/public.js';
 export * from './marketing/public.js';
 export * from './panel/public.js';
+export * from './primitives/index.js';
 export * from './shell/index.js'; // v2 surface
 export * from './theme/index.js';
 export * from './timeline/public.js';

package/dist/primitives/empty-state.d.ts

@@ -0,0 +1,11 @@
+import type { LucideIcon } from 'lucide-react';
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+export type EmptyStateVariant = 'default' | 'panel' | 'inline';
+export interface EmptyStateProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+    icon?: LucideIcon | ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    variant?: EmptyStateVariant;
+}
+export declare function EmptyState({ icon, title, description, action, variant, className, ...props }: EmptyStateProps): import("react/jsx-runtime").JSX.Element;

package/dist/primitives/empty-state.js

@@ -0,0 +1,23 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isValidElement } from 'react';
+import { cn } from '../lib/utils.js';
+function isIconComponent(icon) {
+    if (typeof icon === 'function')
+        return true;
+    if (typeof icon !== 'object')
+        return false;
+    return '$$typeof' in icon && !isValidElement(icon);
+}
+function renderIcon(icon) {
+    if (!icon)
+        return null;
+    if (isIconComponent(icon)) {
+        const Icon = icon;
+        return _jsx(Icon, { "data-testid": "empty-state-icon", className: "size-10", "aria-hidden": "true" });
+    }
+    return (_jsx("span", { "data-testid": "empty-state-icon", "aria-hidden": "true", className: "inline-flex", children: icon }));
+}
+export function EmptyState({ icon, title, description, action, variant = 'default', className, ...props }) {
+    return (_jsxs("div", { "data-slot": "empty-state", "data-variant": variant, className: cn('flex flex-col items-center justify-center text-center', variant === 'default' && 'px-6 py-16', variant === 'panel' && 'px-4 py-10', variant === 'inline' && 'px-3 py-6', className), ...props, children: [icon ? (_jsx("div", { "data-slot": "empty-state-icon", className: cn('mb-4 inline-flex items-center justify-center rounded-md text-muted-foreground', variant === 'inline' ? 'size-9' : 'size-12'), children: renderIcon(icon) })) : null, _jsx("h3", { "data-slot": "empty-state-title", className: cn('font-semibold text-foreground', variant === 'default' && 'text-lg', variant === 'panel' && 'text-base', variant === 'inline' && 'text-sm'), children: title }), description ? (_jsx("p", { "data-slot": "empty-state-description", className: cn('mt-1 max-w-sm text-muted-foreground', variant === 'inline' ? 'text-xs' : 'text-sm'), children: description })) : null, action ? (_jsx("div", { "data-slot": "empty-state-action", className: "mt-5", children: action })) : null] }));
+}

package/dist/primitives/filter-rail.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+export interface FilterRailProps extends Omit<ComponentPropsWithoutRef<'aside'>, 'title'> {
+    title?: ReactNode;
+    description?: ReactNode;
+    search?: ReactNode;
+    actions?: ReactNode;
+    footer?: ReactNode;
+    children?: ReactNode;
+}
+export interface FilterRailGroupProps extends Omit<ComponentPropsWithoutRef<'fieldset'>, 'title'> {
+    title?: ReactNode;
+    description?: ReactNode;
+    children?: ReactNode;
+}
+declare function FilterRailGroup({ title, description, children, className, ...props }: FilterRailGroupProps): import("react/jsx-runtime").JSX.Element;
+declare function FilterRailRoot({ title, description, search, actions, footer, children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }: FilterRailProps): import("react/jsx-runtime").JSX.Element;
+export declare const FilterRail: typeof FilterRailRoot & {
+    Group: typeof FilterRailGroup;
+};
+export {};

package/dist/primitives/filter-rail.js

@@ -0,0 +1,16 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { cn } from '../lib/utils.js';
+function FilterRailGroup({ title, description, children, className, ...props }) {
+    return (_jsxs("fieldset", { "data-slot": "filter-rail-group", className: cn('space-y-2 border-0 p-0', className), ...props, children: [title ? (_jsx("legend", { "data-slot": "filter-rail-group-title", className: "text-xs font-semibold text-foreground", children: title })) : null, description ? (_jsx("p", { "data-slot": "filter-rail-group-description", className: "text-xs text-muted-foreground", children: description })) : null, _jsx("div", { "data-slot": "filter-rail-group-content", className: "space-y-1.5", children: children })] }));
+}
+function FilterRailRoot({ title, description, search, actions, footer, children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }) {
+    const titleId = useId();
+    const label = ariaLabel ?? (ariaLabelledBy ? undefined : typeof title === 'string' ? title : undefined);
+    const labelledBy = ariaLabelledBy ?? (label ? undefined : title ? titleId : undefined);
+    return (_jsxs("aside", { "data-slot": "filter-rail", "aria-label": label, "aria-labelledby": labelledBy, className: cn('flex min-h-0 w-full flex-col border-border bg-card text-card-foreground', className), ...props, children: [title || description || actions ? (_jsxs("div", { "data-slot": "filter-rail-header", className: "flex shrink-0 items-start justify-between gap-3 border-b border-border px-4 py-3", children: [_jsxs("div", { className: "min-w-0", children: [title ? (_jsx("h2", { id: titleId, "data-slot": "filter-rail-title", className: "text-sm font-semibold text-foreground", children: title })) : null, description ? (_jsx("p", { "data-slot": "filter-rail-description", className: "mt-0.5 text-xs text-muted-foreground", children: description })) : null] }), actions ? (_jsx("div", { "data-slot": "filter-rail-actions", className: "shrink-0", children: actions })) : null] })) : null, search ? (_jsx("div", { "data-slot": "filter-rail-search", className: "shrink-0 border-b border-border p-3", children: search })) : null, _jsx("div", { "data-slot": "filter-rail-content", className: "min-h-0 flex-1 space-y-5 overflow-y-auto p-4", children: children }), footer ? (_jsx("div", { "data-slot": "filter-rail-footer", className: "shrink-0 border-t border-border p-3", children: footer })) : null] }));
+}
+export const FilterRail = Object.assign(FilterRailRoot, {
+    Group: FilterRailGroup,
+});

package/dist/primitives/index.d.ts

@@ -0,0 +1,6 @@
+export type { EmptyStateProps, EmptyStateVariant } from './empty-state.js';
+export { EmptyState } from './empty-state.js';
+export type { FilterRailGroupProps, FilterRailProps } from './filter-rail.js';
+export { FilterRail } from './filter-rail.js';
+export type { SkeletonProps } from './skeleton.js';
+export { Skeleton } from './skeleton.js';

package/dist/primitives/index.js

@@ -0,0 +1,3 @@
+export { EmptyState } from './empty-state.js';
+export { FilterRail } from './filter-rail.js';
+export { Skeleton } from './skeleton.js';

package/dist/primitives/skeleton.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentProps } from 'react';
+export type SkeletonProps = ComponentProps<'div'>;
+export declare function Skeleton({ className, 'aria-hidden': ariaHidden, ...props }: SkeletonProps): import("react/jsx-runtime").JSX.Element;

package/dist/primitives/skeleton.js

@@ -0,0 +1,6 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../lib/utils.js';
+export function Skeleton({ className, 'aria-hidden': ariaHidden = true, ...props }) {
+    return (_jsx("div", { "data-slot": "skeleton", "aria-hidden": ariaHidden, className: cn('animate-pulse rounded-md bg-muted', className), ...props }));
+}

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.6.0",
+  "version": "2.0.0",
   "description": "Shared Meda UI shell and runtime package.",
   "license": "Apache-2.0",
   "repository": {