feat: enhance AppShell with branding support and CSS custom properties

feat: extend ObjectView component with multi-view support, including ViewSwitcher, FilterUI, and SortUI

fix: resolve dataSource context in ObjectViewRenderer for better integration with SchemaRendererProvider

refactor: update useActionRunner to support custom confirmation and toast handlers

chore: add new methods to DataSource interface for view and app definitions

feat: introduce RecordDetailView component for displaying single record details

feat: create ExpressionProvider for dynamic visibility and expression evaluation context

docs: add Console Architecture guide detailing data flow and routing

docs: create Console App documentation for quick start and configuration details

Author: hotlong

apps/console/src/App.tsx

@@ -13,14 +13,12 @@ import { CommandPalette } from './components/CommandPalette';
 import { ErrorBoundary } from './components/ErrorBoundary';
 import { LoadingScreen } from './components/LoadingScreen';
 import { ObjectView } from './components/ObjectView';
+import { RecordDetailView } from './components/RecordDetailView';
 import { DashboardView } from './components/DashboardView';
 import { PageView } from './components/PageView';
 import { ReportView } from './components/ReportView';
 import { MetadataToggle, MetadataPanel, useMetadataInspector } from './components/MetadataInspector';
-import { useBranding } from './hooks/useBranding';
-
-import { DetailView } from '@object-ui/plugin-detail';
-import { useParams } from 'react-router-dom';
+import { ExpressionProvider } from './context/ExpressionProvider';
 
 /**
  * Patch: MSW discovery response uses 'routes' instead of 'endpoints'.
@@ -38,66 +36,8 @@ function patchDiscoveryEndpoints(adapter: ObjectStackAdapter) {
   }
 }
 
-// Detail View Component
-function RecordDetailView({ dataSource, objects, onEdit }: any) {
-  const { objectName, recordId } = useParams();
-  const { showDebug, toggleDebug } = useMetadataInspector();
-  const objectDef = objects.find((o: any) => o.name === objectName);
-
-  if (!objectDef) {
-    return (
-      <div className="flex h-full items-center justify-center p-4">
-        <Empty>
-          <EmptyTitle>Object Not Found</EmptyTitle>
-          <p>Object "{objectName}" definition missing.</p>
-        </Empty>
-      </div>
-    );
-  }
-
-  const detailSchema = {
-    type: 'detail-view',
-    objectName: objectDef.name,
-    resourceId: recordId,
-    showBack: true,
-    onBack: 'history',
-    showEdit: true,
-    title:  objectDef.label,
-    sections: [
-       {
-          title: 'Details',
-          fields: Object.keys(objectDef.fields || {}).map(key => ({
-             name: key, 
-             label: objectDef.fields[key].label || key,
-             type: objectDef.fields[key].type || 'text'
-          })),
-          columns: 2
-       }
-    ]
-  };
-
-  return (
-    <div className="h-full bg-background overflow-hidden flex flex-col relative">
-       <div className="absolute top-4 right-4 z-50">
-           <MetadataToggle open={showDebug} onToggle={toggleDebug} />
-       </div>
-
-       <div className="flex-1 overflow-hidden flex flex-row">
-           <div className="flex-1 overflow-auto p-4 lg:p-6">
-               <DetailView 
-                 schema={detailSchema}
-                 dataSource={dataSource}
-                 onEdit={() => onEdit({ _id: recordId, id: recordId })}
-               />
-           </div>
-           <MetadataPanel
-               open={showDebug}
-               sections={[{ title: 'View Schema', data: detailSchema }]}
-           />
-       </div>
-    </div>
-  );
-}
+import { useParams } from 'react-router-dom';
+import { ThemeProvider } from './components/theme-provider';
 
 export function AppContent() {
   const [dataSource, setDataSource] = useState<ObjectStackAdapter | null>(null);
@@ -118,8 +58,7 @@ export function AppContent() {
   const [editingRecord, setEditingRecord] = useState<any>(null);
   const [refreshKey, setRefreshKey] = useState(0);
 
-  // Apply app branding (primaryColor, favicon, title)
-  useBranding(activeApp);
+  // Branding is now applied by AppShell via ConsoleLayout
 
   useEffect(() => {
     initializeDataSource();
@@ -202,7 +141,11 @@ export function AppContent() {
     </div>
   );
 
+  // Expression context for dynamic visibility/disabled/hidden expressions
+  const expressionUser = { name: 'John Doe', email: 'admin@example.com', role: 'admin' };
+
   return (
+    <ExpressionProvider user={expressionUser} app={activeApp} data={{}}>
     <ConsoleLayout
         activeAppName={activeApp.name}
         activeApp={activeApp}
@@ -300,6 +243,7 @@ export function AppContent() {
        </Dialog>
       </SchemaRendererProvider>
     </ConsoleLayout>
+    </ExpressionProvider>
   );
 }
 
@@ -331,8 +275,6 @@ function RootRedirect() {
     return <LoadingScreen />;
 }
 
-import { ThemeProvider } from './components/theme-provider';
-
 export function App() {
   return (
     <ThemeProvider defaultTheme="system" storageKey="object-ui-theme">

apps/console/src/__tests__/ConsoleApp.test.tsx

@@ -85,8 +85,10 @@ vi.mock('@object-ui/components', async (importOriginal) => {
 });
 
 // Mock Lucide icons to avoid rendering SVG complexity
-vi.mock('lucide-react', async () => {
+vi.mock('lucide-react', async (importOriginal) => {
+    const actual = await importOriginal<any>();
     return {
+        ...actual,
         Database: () => <span data-testid="icon-database" />,
         LayoutDashboard: () => <span data-testid="icon-dashboard" />,
         Briefcase: () => <span data-testid="icon-briefcase" />,

apps/console/src/__tests__/ConsoleFeatures.test.tsx

@@ -47,16 +47,20 @@ vi.mock('@object-ui/components', async (importOriginal) => {
 });
 
 // Mock Icons
-vi.mock('lucide-react', () => ({
-    Plus: () => <span>+</span>,
-    Calendar: () => <span>Cal</span>,
-    Kanban: () => <span>Kan</span>,
-    Table: () => <span>Tab</span>,
-    AlignLeft: () => <span>Gantt</span>,
-    Filter: () => <span>FilterIcon</span>,
-    X: () => <span>X</span>,
-    Code2: () => <span>Code</span>
-}));
+vi.mock('lucide-react', async (importOriginal) => {
+    const actual = await importOriginal<any>();
+    return {
+        ...actual,
+        Plus: () => <span>+</span>,
+        Calendar: () => <span>Cal</span>,
+        Kanban: () => <span>Kan</span>,
+        Table: () => <span>Tab</span>,
+        AlignLeft: () => <span>Gantt</span>,
+        Filter: () => <span>FilterIcon</span>,
+        X: () => <span>X</span>,
+        Code2: () => <span>Code</span>,
+    };
+});
 
 describe('ObjectView Console Features', () => {
 

apps/console/src/components/AppHeader.tsx

@@ -1,3 +1,12 @@
+/**
+ * AppHeader
+ *
+ * Top header bar for the console application. Renders breadcrumb navigation
+ * derived from the current route, along with search, notifications, theme
+ * toggle, and connection status indicators.
+ * @module
+ */
+
 import { useLocation, useParams, Link } from 'react-router-dom';
 import { 
   Breadcrumb, 

apps/console/src/components/AppSidebar.tsx

@@ -1,3 +1,12 @@
+/**
+ * AppSidebar
+ *
+ * Collapsible sidebar navigation for the console. Displays the active app's
+ * objects, dashboards, pages, and reports as grouped menu items, with an
+ * app-switcher dropdown and user profile footer.
+ * @module
+ */
+
 import * as React from 'react';
 import { useLocation, Link } from 'react-router-dom';
 import * as LucideIcons from 'lucide-react';
@@ -36,14 +45,18 @@ import {
   ChevronRight,
 } from 'lucide-react';
 import appConfig from '../../objectstack.shared';
+import { useExpressionContext, evaluateVisibility } from '../context/ExpressionProvider';
 
-// Helper to get icon from Lucide
-function getIcon(name?: string) {
+/**
+ * Resolve a Lucide icon component by name string.
+ * Supports camelCase, PascalCase, and kebab-case icon names.
+ */
+function getIconComponent(name?: string): React.ComponentType<any> {
   if (!name) return LucideIcons.Database;
-  
-  // 1. Try direct match (e.g. if user passed "User")
+
+  // 1. Direct match (PascalCase or camelCase)
   if ((LucideIcons as any)[name]) {
-      return (LucideIcons as any)[name];
+    return (LucideIcons as any)[name];
   }
 
   // 2. Try converting kebab-case to PascalCase (e.g. "shopping-cart" -> "ShoppingCart")
@@ -257,11 +270,11 @@ function NavigationItemRenderer({ item, activeAppName }: { item: any, activeAppN
     const Icon = getIcon(item.icon);
     const location = useLocation();
     const [isOpen, setIsOpen] = React.useState(item.expanded !== false);
+    const { evaluator } = useExpressionContext();
 
-    // Handle visibility condition from spec (visible field)
-    // In a real implementation, this would evaluate the expression
-    // For now, we'll just check if it exists and is not explicitly false
-    if (item.visible === 'false' || item.visible === false) {
+    // Evaluate visibility expression (supports boolean, string, and ${} template expressions)
+    const isVisible = evaluateVisibility(item.visible ?? item.visibleOn, evaluator);
+    if (!isVisible) {
         return null;
     }
 

apps/console/src/components/CommandPalette.tsx

@@ -29,6 +29,7 @@ import {
   Monitor,
 } from 'lucide-react';
 import { useTheme } from './theme-provider';
+import { useExpressionContext, evaluateVisibility } from '../context/ExpressionProvider';
 
 /** Resolve a Lucide icon by name (kebab-case or PascalCase) */
 function getIcon(name?: string): React.ElementType {
@@ -54,6 +55,7 @@ export function CommandPalette({ apps, activeApp, objects: _objects, onAppChange
   const navigate = useNavigate();
   const { appName } = useParams();
   const { setTheme } = useTheme();
+  const { evaluator } = useExpressionContext();
 
   // ⌘+K / Ctrl+K shortcut
   useEffect(() => {
@@ -74,8 +76,10 @@ export function CommandPalette({ apps, activeApp, objects: _objects, onAppChange
     command();
   }, []);
 
-  // Extract navigation items from active app
-  const navItems = flattenNavigation(activeApp?.navigation || []);
+  // Extract navigation items from active app, filtering by visibility expressions
+  const navItems = flattenNavigation(activeApp?.navigation || []).filter(
+    (item) => evaluateVisibility(item.visible ?? item.visibleOn, evaluator)
+  );
 
   return (
     <CommandDialog open={open} onOpenChange={setOpen}>

apps/console/src/components/ConsoleLayout.tsx

@@ -1,3 +1,11 @@
+/**
+ * ConsoleLayout
+ *
+ * Root layout shell for the console application. Composes the AppShell
+ * with the sidebar, header, and main content area.
+ * @module
+ */
+
 import React from 'react';
 import { AppShell } from '@object-ui/layout';
 import { AppSidebar } from './AppSidebar';
@@ -37,6 +45,19 @@ export function ConsoleLayout({
           />
       }
       className="p-0 overflow-hidden bg-muted/5"
+      branding={
+        activeApp?.branding
+          ? {
+              primaryColor: activeApp.branding.primaryColor,
+              accentColor: activeApp.branding.accentColor,
+              favicon: activeApp.branding.favicon,
+              logo: activeApp.branding.logo,
+              title: activeApp.label
+                ? `${activeApp.label} — ObjectStack Console`
+                : undefined,
+            }
+          : undefined
+      }
     >
       {children}
     </AppShell>