@medalsocial/meda 1.2.0 → 1.3.0

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

@@ -6,18 +6,22 @@ import { IconRail } from './icon-rail.js';
 import { MobileBottomNav } from './internal/mobile-bottom-nav.js';
 import { MobileDrawers } from './internal/mobile-drawers.js';
 import { MobileHeader } from './internal/mobile-header.js';
+import { useResolvedPanelViews } from './panel-views-provider.js';
 import { RightPanel } from './right-panel.js';
 import { ShellHeader } from './shell-header.js';
 import { ShellMain } from './shell-main.js';
 import { useShellViewport } from './use-shell-viewport.js';
+const EMPTY_PANEL_VIEWS = [];
 export function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalActions, children, }) {
     const viewport = useShellViewport();
     const isMobile = viewport === 'mobile';
+    const staticPanelViews = rightPanel?.panelViews ?? EMPTY_PANEL_VIEWS;
+    const resolvedRightPanel = useResolvedPanelViews(staticPanelViews, rightPanel?.defaultView);
     // Derive the bottom-nav items from the variant config so each button maps
     // to a drawer that actually has content. Without this filter, partial
     // configs (e.g. iconRail only) would show Module/Panels/AI buttons that
     // dispatch into the void.
-    const navItems = buildMobileNavItems(iconRail, contextRail, rightPanel);
+    const navItems = buildMobileNavItems(iconRail, contextRail, resolvedRightPanel.panelViews);
     const hasDrawerContent = navItems.length > 0;
     // Mobile menu drawer needs both main and utility items — desktop IconRail
     // shows both, so dropping utilityItems here would orphan items like Help/
@@ -33,21 +37,22 @@ export function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalAct
     // rendered without an explicit-height ancestor (tests, direct imports). The
     // <AppShell> wrapper already enforces h-screen for the workspace variant, so
     // nested viewport-height divs collapse cleanly — no double-scroll.
-    return (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions })), _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 })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId })), _jsx(ShellMain, { layout: "workspace", children: children }), !isMobile && rightPanel && (_jsx(RightPanel, { panelViews: rightPanel.panelViews, defaultView: rightPanel.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, module: contextRail?.module, panelViews: rightPanel?.panelViews ?? [], defaultView: rightPanel?.defaultView }))] }));
+    return (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions })), _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: "workspace", 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, module: contextRail?.module, moduleAppId: contextRail?.appId, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
 }
-function buildMobileNavItems(iconRail, contextRail, rightPanel) {
+function buildMobileNavItems(iconRail, contextRail, panelViews) {
     const items = [];
     if (iconRail) {
         items.push({ id: 'menu', label: 'Menu', icon: Menu, opens: 'menu-drawer' });
     }
-    if (contextRail?.module) {
+    if (contextRail?.module &&
+        ((contextRail.module.items ?? []).length > 0 || Boolean(contextRail.module.render))) {
         items.push({ id: 'module', label: 'Module', icon: LayoutGrid, opens: 'module-drawer' });
     }
     // Panels button only when there's an actual view to render — empty
     // panelViews would open an empty drawer (dead-end tap).
-    if (rightPanel && rightPanel.panelViews.length > 0) {
+    if (panelViews.length > 0) {
         items.push({ id: 'panels', label: 'Panels', icon: PanelTop, opens: 'panels-drawer' });
-        if (rightPanel.panelViews.some((v) => v.id === 'ai')) {
+        if (panelViews.some((v) => v.id === 'ai')) {
             items.push({ id: 'ai', label: 'AI', icon: Sparkles, opens: 'ai-drawer' });
         }
     }

package/dist/shell/command-palette.js

@@ -109,7 +109,8 @@ export function CommandPalette({ children }) {
     // -------------------------------------------------------------------------
     return (_jsxs(CommandRegistryContext.Provider, { value: registry, children: [children, _jsx(CommandDialog, { open: open, onOpenChange: setOpen, children: _jsxs(Command, { children: [_jsx(CommandInput, { placeholder: "Search commands\u2026" }), _jsxs(CommandList, { children: [_jsx(CommandEmpty, { children: "No results." }), grouped.map((group) => (_jsx(CommandGroup, { heading: group.label, children: group.commands.map((cmd) => {
                                         const Icon = cmd.icon;
-                                        return (_jsxs(CommandItem, { value: `${group.label} ${cmd.label}`, onSelect: () => handleSelect(cmd), children: [Icon && _jsx(Icon, { size: 16, "aria-hidden": "true" }), _jsx("span", { children: cmd.label }), cmd.shortcut && _jsx(CommandShortcut, { children: cmd.shortcut })] }, cmd.id));
+                                        const shortcut = cmd.shortcut ?? cmd.hotkey;
+                                        return (_jsxs(CommandItem, { value: `${group.label} ${cmd.label}`, onSelect: () => handleSelect(cmd), children: [Icon && _jsx(Icon, { size: 16, "aria-hidden": "true" }), _jsx("span", { children: cmd.label }), shortcut && _jsx(CommandShortcut, { children: shortcut })] }, cmd.id));
                                     }) }, group.id)))] })] }) })] }));
 }
 // ---------------------------------------------------------------------------

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

@@ -14,4 +14,4 @@ export interface ContextRailProps {
     renderLink?: (args: ShellLinkRenderArgs) => ReactNode;
     className?: string;
 }
-export declare function ContextRail({ appId: _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, 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: _appId, module, hidden = false, collapsible = true, activeItemId, renderLink, className, }) {
+export function ContextRail({ appId, module, hidden = false, collapsible = true, activeItemId, renderLink, className, }) {
     const band = useShellViewport();
     const ctx = useMedaShell();
     // collapsible={false} means the rail must always render expanded — even if
@@ -91,12 +91,13 @@ export function ContextRail({ appId: _appId, module, hidden = false, collapsible
     // is called on pointerUp to persist via useShellLayoutState.
     const [displayWidth, setDisplayWidth] = useState(null);
     const width = displayWidth ?? ctx.contextRail.width;
+    const items = module?.items ?? [];
     if (band === 'mobile')
         return null;
     if (hidden) {
         return _jsx("div", { "aria-hidden": "true", className: "hidden", "data-testid": "context-rail-hidden" });
     }
-    if (!module || module.items.length === 0) {
+    if (!module || (items.length === 0 && !module.render)) {
         return _jsx("div", { "aria-hidden": "true", className: "hidden", "data-testid": "context-rail-empty" });
     }
     const handleResize = (w) => {
@@ -112,7 +113,7 @@ export function ContextRail({ appId: _appId, module, hidden = false, collapsible
     // 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 }))] }), _jsx("nav", { "aria-label": `${module.label} navigation`, className: "flex flex-col gap-0.5 p-2", children: module.items.map((item) => {
+    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'
@@ -123,5 +124,5 @@ export function ContextRail({ appId: _appId, module, hidden = false, collapsible
                                 return renderLink({ item, isActive, className: klass, children: inner });
                             }
                             return (_jsx("a", { href: item.to, "aria-current": isActive ? 'page' : undefined, className: klass, children: inner }, item.id));
-                        }) })] }), !collapsed && (_jsx(ResizeHandle, { currentWidth: width, onResize: handleResize, onCommit: handleCommit }))] }));
+                        }) })), module.render?.({ workspaceId: ctx.workspace.id, appId })] }), !collapsed && (_jsx(ResizeHandle, { currentWidth: width, onResize: handleResize, onCommit: handleCommit }))] }));
 }

package/dist/shell/index.d.ts

@@ -9,6 +9,8 @@ export { IconRail, RailDivider } from './icon-rail.js';
 export type { ShellStorageAdapter } from './layout-state.js';
 export { createLocalStorageAdapter } from './layout-state.js';
 export { motion } from './motion.js';
+export type { PanelViewsProviderProps } from './panel-views-provider.js';
+export { PanelViewsProvider } from './panel-views-provider.js';
 export type { RailDropSlotProps, RailDropSlotState } from './rail-drop-slot.js';
 export { RailDropSlot } from './rail-drop-slot.js';
 export type { RailDropZonesProps } from './rail-drop-zones.js';

package/dist/shell/index.js

@@ -18,6 +18,7 @@ export { IconRail, RailDivider } from './icon-rail.js';
 export { createLocalStorageAdapter } from './layout-state.js';
 // Hooks + tokens
 export { motion } from './motion.js';
+export { PanelViewsProvider } from './panel-views-provider.js';
 // Resize primitives
 export { RailDropSlot } from './rail-drop-slot.js';
 export { RailDropZones } from './rail-drop-zones.js';

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

@@ -1,11 +1,17 @@
 import { type ReactNode } from 'react';
-import type { IconRailItem } from '../icon-rail.js';
+import type { IconRailItem, IconRailProps } from '../icon-rail.js';
 import type { ContextModule, PanelView } from '../types.js';
 export interface MobileDrawersProps {
     /** Menu drawer source (icon-rail items). */
     menuItems?: IconRailItem[];
+    /** Active menu item id, sourced from icon rail config. */
+    menuActiveId?: string;
+    /** Custom menu link renderer, sourced from icon rail config. */
+    menuRenderLink?: IconRailProps['renderLink'];
     /** Module drawer source (current app's context-rail module). */
     module?: ContextModule;
+    /** App id used when rendering module custom content. */
+    moduleAppId?: string;
     /** Panels drawer source. */
     panelViews?: PanelView[];
     /**
@@ -23,4 +29,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, module, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;
+export declare function MobileDrawers({ menuItems, menuActiveId, menuRenderLink, module, moduleAppId, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect } from 'react';
+import { cloneElement, isValidElement, useEffect } from 'react';
 import { Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, } from '../../components/ui/drawer.js';
 import { cn } from '../../lib/utils.js';
 import { useMedaShell } from '../shell-provider.js';
@@ -9,7 +9,7 @@ import { useMedaShell } from '../shell-provider.js';
  * any custom-content drawers. Mount once near the AppShell root; drawers
  * open/close via `ctx.mobileDrawer.open` provider state.
  */
-export function MobileDrawers({ menuItems = [], module, panelViews = [], defaultView, customContent = {}, }) {
+export function MobileDrawers({ menuItems = [], menuActiveId, menuRenderLink, module, moduleAppId, panelViews = [], defaultView, customContent = {}, }) {
     const ctx = useMedaShell();
     const open = ctx.mobileDrawer.open;
     const setOpen = ctx.mobileDrawer.setOpen;
@@ -18,24 +18,52 @@ export function MobileDrawers({ menuItems = [], module, panelViews = [], default
         workspaceId: ctx.workspace.id,
         appId: ctx.activeAppId,
     };
-    return (_jsxs(_Fragment, { children: [_jsx(MenuDrawer, { open: open === 'menu-drawer', onClose: close, items: menuItems }), _jsx(ModuleDrawer, { open: open === 'module-drawer', onClose: close, module: module }), _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)))] }));
+    const moduleRenderCtx = {
+        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 }), _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)))] }));
 }
 // ---------------------------------------------------------------------------
 // Internal sub-drawers
 // ---------------------------------------------------------------------------
-function MenuDrawer({ open, onClose, items, }) {
-    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "left", children: _jsxs(DrawerContent, { children: [_jsxs(DrawerHeader, { children: [_jsx(DrawerTitle, { children: "Menu" }), _jsx(DrawerDescription, { className: "sr-only", children: "Switch between primary app areas." })] }), _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: 18, "aria-hidden": "true" }), _jsx("span", { children: item.label })] }, item.id));
-                    }) })] }) }));
+function MenuDrawer({ open, onClose, items, activeId, renderLink, }) {
+    return (_jsx(Drawer, { open: open, onOpenChange: (o) => !o && onClose(), direction: "left", children: _jsxs(DrawerContent, { children: [_jsxs(DrawerHeader, { children: [_jsx(DrawerTitle, { children: "Menu" }), _jsx(DrawerDescription, { className: "sr-only", children: "Switch between primary app areas." })] }), _jsx("nav", { className: "flex flex-col gap-0.5 p-2", children: items.map((item) => (_jsx(MenuDrawerItem, { item: item, isActive: item.id === activeId, onClose: onClose, renderLink: renderLink }, item.id))) })] }) }));
+}
+const menuItemClassName = 'flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-accent hover:text-foreground';
+function MenuDrawerItem({ item, isActive, onClose, renderLink, }) {
+    const Icon = item.icon;
+    const children = (_jsxs(_Fragment, { children: [_jsx(Icon, { size: 18, "aria-hidden": "true" }), _jsx("span", { children: item.label })] }));
+    if (renderLink) {
+        return closeAfterLinkClick(renderLink({
+            item,
+            isActive,
+            className: cn(menuItemClassName, isActive && 'bg-accent text-foreground'),
+            children,
+        }), onClose);
+    }
+    return (_jsx("a", { href: item.to, onClick: onClose, className: menuItemClassName, children: children }));
+}
+function closeAfterLinkClick(link, onClose) {
+    if (!isValidElement(link)) {
+        return link;
+    }
+    const originalOnClick = link.props.onClick;
+    return cloneElement(link, {
+        onClick: (event) => {
+            originalOnClick?.(event);
+            onClose();
+        },
+    });
 }
-function ModuleDrawer({ open, onClose, module, }) {
-    if (!module)
+function ModuleDrawer({ open, onClose, module, renderCtx, }) {
+    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 }))] }), _jsx("nav", { className: "flex flex-col gap-0.5 p-2", children: module.items.map((item) => {
+    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)] }) }));
 }
 function PanelsDrawer({ open, onClose, panelViews, defaultView, renderCtx, }) {
     const ctx = useMedaShell();

package/dist/shell/panel-views-provider.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from 'react';
+import { type PanelViewRegistration } from './shell-provider.js';
+import type { PanelView } from './types.js';
+export interface PanelViewsProviderProps {
+    views: PanelView[];
+    defaultView?: string;
+    children: ReactNode;
+}
+export interface ResolvedPanelViews {
+    panelViews: PanelView[];
+    defaultView?: string;
+}
+export declare function mergePanelViews(staticViews: PanelView[] | undefined, registrations: PanelViewRegistration[], staticDefaultView?: string): ResolvedPanelViews;
+export declare function useResolvedPanelViews(staticViews?: PanelView[], staticDefaultView?: string): ResolvedPanelViews;
+export declare function PanelViewsProvider({ views, defaultView, children }: PanelViewsProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/panel-views-provider.js

@@ -0,0 +1,56 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useId, useLayoutEffect, useMemo, useRef } from 'react';
+import { useMedaShell } from './shell-provider.js';
+export function mergePanelViews(staticViews = [], registrations, staticDefaultView) {
+    const panelViews = [];
+    for (const view of staticViews) {
+        panelViews.push(view);
+    }
+    let defaultView = staticDefaultView;
+    for (const registration of registrations) {
+        for (const view of registration.views) {
+            const previousIndex = panelViews.findIndex((existingView) => existingView.id === view.id);
+            if (previousIndex >= 0) {
+                panelViews.splice(previousIndex, 1);
+            }
+            panelViews.push(view);
+        }
+        if (registration.defaultView !== undefined) {
+            defaultView = registration.defaultView;
+        }
+    }
+    return defaultView === undefined ? { panelViews } : { panelViews, defaultView };
+}
+export function useResolvedPanelViews(staticViews = [], staticDefaultView) {
+    const { panelViews } = useMedaShell();
+    return useMemo(() => mergePanelViews(staticViews, panelViews.registrations, staticDefaultView), [staticViews, panelViews.registrations, staticDefaultView]);
+}
+function getPanelViewsSignature(views) {
+    return views.map((view) => `${view.id}\u001f${view.label}`).join('\u001e');
+}
+export function PanelViewsProvider({ views, defaultView, children }) {
+    const { register } = useMedaShell().panelViews;
+    const registrationId = useId();
+    const latestViewsRef = useRef(views);
+    latestViewsRef.current = views;
+    const viewsSignature = getPanelViewsSignature(views);
+    const registeredViewsRef = useRef(null);
+    if (registeredViewsRef.current?.signature !== viewsSignature) {
+        registeredViewsRef.current = {
+            signature: viewsSignature,
+            views: views.map((view) => ({
+                id: view.id,
+                label: view.label,
+                icon: view.icon,
+                render: (ctx) => latestViewsRef.current.find((currentView) => currentView.id === view.id)?.render(ctx) ??
+                    null,
+            })),
+        };
+    }
+    const registeredViews = registeredViewsRef.current.views;
+    useLayoutEffect(() => {
+        return register(registrationId, registeredViews, defaultView);
+    }, [register, registrationId, registeredViews, defaultView]);
+    return _jsx(_Fragment, { children: children });
+}

package/dist/shell/right-panel.js

@@ -18,6 +18,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Maximize2, Minimize2, X } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 import { cn } from '../lib/utils.js';
+import { useResolvedPanelViews } from './panel-views-provider.js';
 import { useMedaShell } from './shell-provider.js';
 import { useShellViewport } from './use-shell-viewport.js';
 // ---------------------------------------------------------------------------
@@ -25,6 +26,7 @@ import { useShellViewport } from './use-shell-viewport.js';
 // ---------------------------------------------------------------------------
 const MIN_WIDTH = 300;
 const MAX_WIDTH = 520;
+const EMPTY_PANEL_VIEWS = [];
 function ResizeHandle({ currentWidth, onResize, onCommit }) {
     const startWidthRef = useRef(currentWidth);
     const startXRef = useRef(0);
@@ -61,17 +63,28 @@ function ResizeHandle({ currentWidth, onResize, onCommit }) {
 // ---------------------------------------------------------------------------
 // RightPanel
 // ---------------------------------------------------------------------------
-export function RightPanel({ panelViews = [], defaultView, modes = ['panel', 'expanded', 'fullscreen'], className, }) {
+export function RightPanel({ panelViews = EMPTY_PANEL_VIEWS, defaultView, modes = ['panel', 'expanded', 'fullscreen'], className, }) {
     const band = useShellViewport();
     const ctx = useMedaShell();
     const { mode, activeView, width, setMode, setActiveView, setWidth } = ctx.panel;
-    // Hydrate defaultView on mount if no active view set
-    // biome-ignore lint/correctness/useExhaustiveDependencies: intentional one-time mount effect
+    const { panelViews: resolvedPanelViews, defaultView: resolvedDefaultView } = useResolvedPanelViews(panelViews, defaultView);
+    const hydratedDefaultRef = useRef(null);
+    // Hydrate a default when static or route-registered views become available.
     useEffect(() => {
-        if (!activeView && defaultView) {
-            setActiveView(defaultView);
+        const defaultExists = resolvedDefaultView != null &&
+            resolvedPanelViews.some((view) => view.id === resolvedDefaultView);
+        if (!defaultExists)
+            return;
+        const source = resolvedDefaultView !== defaultView ? 'registered' : 'static';
+        const canReplaceStaticDefault = activeView === hydratedDefaultRef.current?.id &&
+            hydratedDefaultRef.current.source === 'static' &&
+            source === 'registered' &&
+            activeView !== resolvedDefaultView;
+        if (!activeView || canReplaceStaticDefault) {
+            hydratedDefaultRef.current = { id: resolvedDefaultView, source };
+            setActiveView(resolvedDefaultView);
         }
-    }, []);
+    }, [activeView, defaultView, resolvedDefaultView, resolvedPanelViews, setActiveView]);
     // Local display width tracks pointer-move updates live;
     // setWidth (persist) is called on pointerUp.
     const [displayWidth, setDisplayWidth] = useState(null);
@@ -109,14 +122,14 @@ export function RightPanel({ panelViews = [], defaultView, modes = ['panel', 'ex
     })();
     // Z-index escalation: fullscreen covers header + rails
     const zIndexClass = mode === 'fullscreen' ? 'z-[var(--z-shell-fullscreen)]' : 'z-[var(--z-shell-panel)]';
-    const activePanelView = panelViews.find((v) => v.id === activeView);
+    const activePanelView = resolvedPanelViews.find((v) => v.id === activeView);
     const cycleAriaLabel = mode === 'panel' ? 'Expand panel' : mode === 'expanded' ? 'Maximize panel' : 'Restore panel';
     const handleResize = (w) => setDisplayWidth(w);
     const handleCommit = (w) => {
         setDisplayWidth(null);
         setWidth(w);
     };
-    return (_jsx("aside", { "data-meda-panel-mode": mode, "aria-hidden": mode === 'closed' ? 'true' : undefined, className: cn('relative h-full shrink-0 overflow-hidden border-l border-shell-border bg-shell-panel', 'transition-[width] ease-[var(--motion-ease)] duration-[var(--motion-panel)]', mode === 'fullscreen' && 'fixed inset-0 h-screen w-screen border-none', zIndexClass, className), style: widthStyle, children: mode !== 'closed' && (_jsxs("div", { className: "flex h-full flex-col", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-shell-border px-3 py-2", children: [_jsx("div", { className: "flex items-center gap-1", children: panelViews.map((view) => {
+    return (_jsx("aside", { "data-meda-panel-mode": mode, "aria-hidden": mode === 'closed' ? 'true' : undefined, className: cn('relative h-full shrink-0 overflow-hidden border-l border-shell-border bg-shell-panel', 'transition-[width] ease-[var(--motion-ease)] duration-[var(--motion-panel)]', mode === 'fullscreen' && 'fixed inset-0 h-screen w-screen border-none', zIndexClass, className), style: widthStyle, children: mode !== 'closed' && (_jsxs("div", { className: "flex h-full flex-col", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-shell-border px-3 py-2", children: [_jsx("div", { className: "flex items-center gap-1", children: resolvedPanelViews.map((view) => {
                                 const isActive = view.id === activeView;
                                 const Icon = view.icon;
                                 return (_jsxs("button", { type: "button", "aria-current": isActive ? 'true' : undefined, onClick: () => setActiveView(view.id), className: cn('inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors', isActive

package/dist/shell/shell-provider.d.ts

@@ -1,7 +1,12 @@
 import { type ReactNode } from 'react';
 import { type ShellStorageAdapter } from './layout-state.js';
-import type { AppDefinition, MobileBottomNavItem, PanelMode, ThemeAdapter, WorkspaceDefinition } from './types.js';
+import type { AppDefinition, MobileBottomNavItem, PanelMode, PanelView, ThemeAdapter, WorkspaceDefinition } from './types.js';
 export type MobileDrawerKind = 'menu-drawer' | 'module-drawer' | 'panels-drawer' | 'ai-drawer' | (string & {}) | null;
+export interface PanelViewRegistration {
+    id: string;
+    views: PanelView[];
+    defaultView?: string;
+}
 interface MedaShellContextValue {
     workspace: WorkspaceDefinition;
     workspaces: WorkspaceDefinition[];
@@ -15,6 +20,9 @@ interface MedaShellContextValue {
         setMode: (m: PanelMode) => void;
         setActiveView: (v: string | null) => void;
         setWidth: (w: number) => void;
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
         /** Opens panel + switches to viewId in one call.
          * Sugar for app keyboard shortcuts (e.g. Cmd+J → panel.focus('ai')).
          * If already open in 'panel', 'expanded', or 'fullscreen', the existing
@@ -26,6 +34,7 @@ interface MedaShellContextValue {
         collapsed: boolean;
         setWidth: (w: number) => void;
         setCollapsed: (c: boolean) => void;
+        toggle: () => void;
     };
     mobileBottomNav: MobileBottomNavItem[];
     mobileDrawer: {
@@ -36,6 +45,10 @@ interface MedaShellContextValue {
         open: boolean;
         setOpen: (open: boolean) => void;
     };
+    panelViews: {
+        registrations: PanelViewRegistration[];
+        register: (id: string, views: PanelView[], defaultView?: string) => () => void;
+    };
     commandPaletteHotkey: string;
     /** Selection bridge between main workspace and right panel views (spec §17). */
     selection: unknown | null;

package/dist/shell/shell-provider.js

@@ -1,9 +1,10 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { LayoutGrid, Menu, PanelTop, Sparkles } from 'lucide-react';
-import { createContext, lazy, Suspense, useContext, useMemo, useState, } from 'react';
+import { createContext, lazy, Suspense, useCallback, useContext, useMemo, useState, } from 'react';
 import { createLocalStorageAdapter, useShellLayoutState, } from './layout-state.js';
 import { DefaultThemeProvider, ThemeCtx } from './theme.js';
+import { useShellViewport } from './use-shell-viewport.js';
 // ---------------------------------------------------------------------------
 // Theme adapter wiring
 // ---------------------------------------------------------------------------
@@ -78,11 +79,35 @@ export function MedaShellProvider(props) {
         open: commandPaletteOpen,
         setOpen: setCommandPaletteOpen,
     }), [commandPaletteOpen]);
+    const [panelViewRegistrations, setPanelViewRegistrations] = useState([]);
+    const registerPanelViews = useCallback((id, views, defaultView) => {
+        setPanelViewRegistrations((prev) => {
+            const existing = prev.find((registration) => registration.id === id);
+            if (existing?.views === views && existing.defaultView === defaultView)
+                return prev;
+            const nextRegistration = defaultView === undefined ? { id, views } : { id, views, defaultView };
+            if (existing == null)
+                return [...prev, nextRegistration];
+            return prev.map((registration) => (registration.id === id ? nextRegistration : registration));
+        });
+        return () => {
+            setPanelViewRegistrations((prev) => prev.some((registration) => registration.id === id &&
+                registration.views === views &&
+                registration.defaultView === defaultView)
+                ? prev.filter((registration) => registration.id !== id)
+                : prev);
+        };
+    }, []);
+    const panelViews = useMemo(() => ({
+        registrations: panelViewRegistrations,
+        register: registerPanelViews,
+    }), [panelViewRegistrations, registerPanelViews]);
     const [layoutState, setLayoutState] = useShellLayoutState({
         workspaceId: props.workspace.id,
         appId: activeAppId,
         storage,
     });
+    const isMobile = useShellViewport() === 'mobile';
     const panel = useMemo(() => ({
         mode: layoutState.rightPanel.mode,
         activeView: layoutState.rightPanel.activeView,
@@ -99,6 +124,37 @@ export function MedaShellProvider(props) {
             ...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) => {
@@ -108,7 +164,7 @@ export function MedaShellProvider(props) {
                 rightPanel: { ...prev.rightPanel, mode: nextMode, activeView: viewId },
             };
         }),
-    }), [layoutState, setLayoutState]);
+    }), [isMobile, layoutState, setLayoutState]);
     const contextRail = useMemo(() => ({
         width: layoutState.contextRail.width,
         collapsed: layoutState.contextRail.collapsed,
@@ -120,6 +176,10 @@ export function MedaShellProvider(props) {
             ...prev,
             contextRail: { ...prev.contextRail, collapsed },
         })),
+        toggle: () => setLayoutState((prev) => ({
+            ...prev,
+            contextRail: { ...prev.contextRail, collapsed: !prev.contextRail.collapsed },
+        })),
     }), [layoutState, setLayoutState]);
     const value = useMemo(() => ({
         workspace: props.workspace,
@@ -132,6 +192,7 @@ export function MedaShellProvider(props) {
         mobileBottomNav: props.mobileBottomNav ?? defaultMobileBottomNav,
         mobileDrawer,
         commandPalette,
+        panelViews,
         commandPaletteHotkey: props.commandPaletteHotkey ?? 'mod+k',
         selection,
         setSelection,
@@ -145,6 +206,7 @@ export function MedaShellProvider(props) {
         props.mobileBottomNav,
         mobileDrawer,
         commandPalette,
+        panelViews,
         props.commandPaletteHotkey,
         selection,
     ]);

package/dist/shell/types.d.ts

@@ -14,7 +14,8 @@ export interface ContextModule {
     id: string;
     label: string;
     description?: string;
-    items: ContextItem[];
+    items?: ContextItem[];
+    render?: (ctx: ShellRenderContext) => ReactNode;
 }
 export interface ContextItem {
     id: string;
@@ -55,6 +56,8 @@ export interface CommandDefinition {
     icon?: LucideIcon;
     group: string;
     shortcut?: string;
+    /** Display-only alias for `shortcut`; `shortcut` wins when both are supplied. */
+    hotkey?: string;
     run: () => void | Promise<void>;
 }
 export interface ThemeAdapter {
@@ -76,6 +79,7 @@ export interface AppShellIconRailConfig {
     utilityItems?: import('./icon-rail.js').IconRailItem[];
     footer?: ReactNode;
     activeId?: string;
+    renderLink?: import('./icon-rail.js').IconRailProps['renderLink'];
 }
 /** ContextRail configuration for `<AppShell variant="workspace">`. */
 export interface AppShellContextRailConfig {

package/package.json

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