ObjectView.tsx

/**
 * ObjectUI
 * Copyright (c) 2024-present ObjectStack Inc.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

/**
 * ObjectView Component
 *
 * A complete object management interface that combines multi-view data display
 * (grid, kanban, calendar, gallery, timeline, gantt, map) with ObjectForm
 * for create/edit operations.
 *
 * Features:
 * - Multi-view type rendering via SchemaRenderer
 * - Named listViews support (e.g., "All", "My Records", "Active")
 * - Navigation config for row click behavior (page/drawer/modal/none/new_window)
 * - Direct data fetching for all view types
 * - Integrated search, filter, and sort controls
 * - ViewSwitcher for toggling between view types
 */

import React, { useEffect, useState, useCallback, useMemo, useRef } from 'react';
import type {
  ObjectViewSchema,
  ObjectGridSchema,
  ObjectFormSchema,
  DataSource,
  ViewSwitcherSchema,
  FilterUISchema,
  SortUISchema,
  ViewType,
  NamedListView,
  ViewNavigationConfig,
} from '@object-ui/types';
import { ObjectGrid } from '@object-ui/plugin-grid';
import { ObjectForm } from '@object-ui/plugin-form';
import {
  cn,
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  Drawer,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
  NavigationOverlay,
  Button,
  Tabs,
  TabsList,
  TabsTrigger,
  useIsMobile,
} from '@object-ui/components';
import { Plus } from 'lucide-react';
import { useObjectTranslation } from '@object-ui/i18n';
import { buildExpandFields } from '@object-ui/core';
import { SchemaRenderer as ImportedSchemaRenderer } from '@object-ui/react';
import { ViewSwitcher } from './ViewSwitcher';
import { deriveRecordSurface } from './recordSurface';

/**
 * SchemaRenderer from @object-ui/react, used to render sub-view schemas.
 */
const SchemaRendererComponent: React.FC<any> = ImportedSchemaRenderer;

/**
 * Record-create verb, shared with the runtime object pages: both surfaces
 * resolve `console.objectView.new` ("New" / 新建) so the Studio grid toolbar
 * and the running app never disagree (framework#2615 P3). Falls back to
 * English when no I18nProvider is mounted (standalone usage) — via the
 * key-identity probe, not a caught throw.
 */
function useCreateVerb(): string {
  // No try/catch: `useObjectTranslation` is provider-safe (optional context
  // read + react-i18next global-instance fallback) and never throws, so the
  // key-identity probe below is the whole "no provider" path. Wrapping a hook
  // in try/catch violates rules-of-hooks — a throw after it ran would desync
  // hook order on the next render (objectui#2879, same class as #2595/#2596).
  const { t } = useObjectTranslation();
  const value = t('console.objectView.new');
  return value === 'console.objectView.new' ? 'New' : value;
}

export interface ObjectViewProps {
  /**
   * The schema configuration for the view
   */
  schema: ObjectViewSchema;

  /**
   * Data source (ObjectQL or ObjectStack adapter).
   * If not provided, falls back to SchemaRendererProvider context.
   */
  dataSource: DataSource;

  /**
   * Additional CSS class
   */
  className?: string;

  /**
   * Views available for the ViewSwitcher.
   * Each view defines a type (grid, kanban, calendar, etc.) and display columns/config.
   * If not provided, uses schema.listViews or falls back to default grid view.
   */
  views?: Array<{
    id: string;
    label: string;
    type: ViewType;
    columns?: string[];
    sort?: Array<{ field: string; direction: 'asc' | 'desc' }>;
    filter?: any[];
    [key: string]: any;
  }>;

  /**
   * The currently active view ID.
   * Used for controlled ViewSwitcher state.
   */
  activeViewId?: string;

  /**
   * Callback when the active view changes
   */
  onViewChange?: (viewId: string) => void;

  /**
   * Callback when a row is clicked (for record detail navigation)
   */
  onRowClick?: (record: Record<string, unknown>) => void;

  /**
   * Callback when edit is triggered on a record
   */
  onEdit?: (record: Record<string, unknown>) => void;

  /**
   * Render a custom ListView implementation for multi-view support.
   * When provided, this replaces the default view rendering for the content area.
   */
  /**
   * ADR-0053: when the host (app-shell ObjectView) already renders the view
   * switcher (ViewTabBar), set this so the inner view doesn't render its own
   * duplicate named-view tab row. Standalone consumers leave it unset.
   */
  hideNamedViewTabs?: boolean;

  renderListView?: (props: {
    schema: any;
    dataSource: DataSource;
    onEdit?: (record: Record<string, unknown>) => void;
    onRowClick?: (record: Record<string, unknown>) => void;
    className?: string;
    /** Current refresh counter — increment signals that a mutation occurred */
    refreshKey?: number;
    /** Same handler the built-in toolbar's "+ New" button uses — forward it
     * into the custom list view's own add-record affordance (e.g. ListView's
     * `addRecord.enabled` toolbar button) so callers can fold record creation
     * into their list's toolbar instead of the separate `showCreate` row. */
    onAddRecord?: () => void;
  }) => React.ReactNode;

  /**
   * Toolbar addon: extra elements to render in the toolbar (e.g., MetadataToggle)
   */
  toolbarAddon?: React.ReactNode;

  /**
   * Callback when the "+" create view button is clicked in ViewSwitcher.
   */
  onCreateView?: () => void;

  /**
   * Callback when a per-view action is triggered in ViewSwitcher.
   */
  onViewAction?: (action: string, viewType: ViewType) => void;
}

type FormMode = 'create' | 'edit' | 'view';

/**
 * ObjectView Component
 *
 * Renders a complete object management interface with multi-view rendering
 * and integrated CRUD operations.
 *
 * @example Basic usage (grid only)
 * ```tsx
 * <ObjectView
 *   schema={{
 *     type: 'object-view',
 *     objectName: 'users',
 *     layout: 'drawer',
 *     showSearch: true,
 *     showFilters: true,
 *   }}
 *   dataSource={dataSource}
 * />
 * ```
 *
 * @example Named listViews
 * ```tsx
 * <ObjectView
 *   schema={{
 *     type: 'object-view',
 *     objectName: 'contacts',
 *     listViews: {
 *       all: { label: 'All Contacts', type: 'grid', columns: ['name', 'email', 'phone'] },
 *       board: { label: 'By Status', type: 'kanban', options: { kanban: { groupField: 'status' } } },
 *       calendar: { label: 'Meetings', type: 'calendar', options: { calendar: { startDateField: 'meeting_date' } } },
 *     },
 *     defaultListView: 'all',
 *   }}
 *   dataSource={dataSource}
 * />
 * ```
 *
 * @example With navigation config
 * ```tsx
 * <ObjectView
 *   schema={{
 *     type: 'object-view',
 *     objectName: 'accounts',
 *     navigation: { mode: 'drawer', width: '600px' },
 *   }}
 *   dataSource={dataSource}
 * />
 * ```
 */
export const ObjectView: React.FC<ObjectViewProps> = ({
  schema,
  dataSource,
  className,
  views: viewsProp,
  activeViewId,
  onViewChange,
  onRowClick,
  onEdit: onEditProp,
  renderListView,
  hideNamedViewTabs,
  toolbarAddon,
  onCreateView,
  onViewAction,
}) => {
  const createVerb = useCreateVerb();
  const [objectSchema, setObjectSchema] = useState<Record<string, unknown> | null>(null);
  // Assigned in the render body (not in an effect) so the fetchData effect always
  // reads the latest objectSchema without needing it as a dependency. This matches
  // the same pattern used in ObjectCalendar's objectSchemaRef.
  const objectSchemaRef = useRef<Record<string, unknown> | null>(null);
  objectSchemaRef.current = objectSchema;
  const [isFormOpen, setIsFormOpen] = useState(false);
  const [formMode, setFormMode] = useState<FormMode>('create');
  const [selectedRecord, setSelectedRecord] = useState<Record<string, unknown> | null>(null);
  const [refreshKey, setRefreshKey] = useState(0);

  // P2: Auto-subscribe to DataSource mutation events for non-grid views.
  // When a DataSource implements onMutation(), ObjectView auto-refreshes
  // its own data fetch (for non-grid view types like kanban, calendar, etc.)
  // whenever a create/update/delete occurs on the same objectName.
  //
  // ListView-driven configurations already manage refreshKey via
  // form success / delete handlers. To avoid double refreshes and
  // duplicate find() calls, skip auto-subscription when renderListView is provided.
  useEffect(() => {
    if (!dataSource?.onMutation || !schema.objectName) return;
    if (renderListView) return;
    const unsub = dataSource.onMutation((event: any) => {
      if (event.resource === schema.objectName) {
        setRefreshKey(prev => prev + 1);
      }
    });
    return unsub;
  }, [dataSource, schema.objectName, renderListView]);

  // Data fetching state for non-grid views
  const [data, setData] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);

  // Filter & Sort state
  const [filterValues, setFilterValues] = useState<Record<string, any>>({});
  const [sortConfig, setSortConfig] = useState<Array<{ field: string; direction: 'asc' | 'desc' }>>([]);

  // --- Named listViews ---
  const namedListViews = schema.listViews;
  const hasNamedViews = namedListViews != null && Object.keys(namedListViews).length > 0;
  const [activeNamedView, setActiveNamedView] = useState<string>(() => {
    if (schema.defaultListView && namedListViews?.[schema.defaultListView]) {
      return schema.defaultListView;
    }
    if (namedListViews) {
      const keys = Object.keys(namedListViews);
      return keys[0] || '';
    }
    return '';
  });

  // Get current named view config
  const currentNamedViewConfig: NamedListView | null = useMemo(() => {
    if (!hasNamedViews || !activeNamedView) return null;
    return namedListViews![activeNamedView] || null;
  }, [hasNamedViews, activeNamedView, namedListViews]);

  // --- Multi-view type state (prop-based views) ---
  const viewsPropResolved = useMemo(() => {
    if (viewsProp && viewsProp.length > 0) return viewsProp;
    return null;
  }, [viewsProp]);

  const hasMultiView = viewsPropResolved != null && viewsPropResolved.length > 0;
  const currentActiveViewId = activeViewId || viewsPropResolved?.[0]?.id;
  const activeView = viewsPropResolved?.find(v => v.id === currentActiveViewId) || viewsPropResolved?.[0];

  // Current view type from named view, multi-view prop, or default
  const currentViewType: string = useMemo(() => {
    if (currentNamedViewConfig?.type) return currentNamedViewConfig.type;
    if (activeView?.type) return activeView.type;
    return schema.defaultViewType || 'grid';
  }, [currentNamedViewConfig, activeView, schema.defaultViewType]);

  // Navigation config
  const navigationConfig: ViewNavigationConfig | undefined = schema.navigation;

  // Fetch object schema from ObjectQL/ObjectStack
  useEffect(() => {
    let isMounted = true;
    const fetchObjectSchema = async () => {
      try {
        const schemaData = await dataSource.getObjectSchema(schema.objectName);
        if (isMounted) setObjectSchema(schemaData);
      } catch (err) {
        console.error('Failed to fetch object schema:', err);
      }
    };
    if (schema.objectName && dataSource) {
      fetchObjectSchema();
    }
    return () => { isMounted = false; };
  }, [schema.objectName, dataSource]);

  // Fetch data for non-grid view types (grid handles its own data via ObjectGrid)
  useEffect(() => {
    let isMounted = true;

    const fetchData = async () => {
      // When renderListView is provided, the custom list view (e.g. ListView)
      // handles its own data fetching — skip to avoid duplicate requests and
      // unnecessary re-renders that can cause duplicate records in child views.
      if (renderListView) return;
      // Only fetch for non-grid views (ObjectGrid has its own data fetching)
      if (currentViewType === 'grid') return;
      if (!dataSource || !schema.objectName) return;

      setLoading(true);
      try {
        // Build filter
        const baseFilter = currentNamedViewConfig?.filter || activeView?.filter || schema.table?.defaultFilters || [];
        const userFilter = Object.entries(filterValues)
          .filter(([, v]) => v !== undefined && v !== '' && v !== null)
          .map(([field, value]) => [field, '=', value]);

        let finalFilter: any = [];
        if (baseFilter.length > 0 && userFilter.length > 0) {
          finalFilter = ['and', ...baseFilter, ...userFilter];
        } else if (userFilter.length === 1) {
          finalFilter = userFilter[0];
        } else if (userFilter.length > 1) {
          finalFilter = ['and', ...userFilter];
        } else {
          finalFilter = baseFilter;
        }

        // Build sort
        const sort = sortConfig.length > 0
          ? sortConfig.map(s => ({ field: s.field, order: s.direction }))
          : (currentNamedViewConfig?.sort || activeView?.sort || schema.table?.defaultSort || undefined);

        // Auto-inject $expand for lookup/master_detail fields.
        // Use a ref instead of the state variable to avoid re-running this effect
        // every time the object schema loads — that would cause a double-fetch and
        // duplicate events in child views like the calendar.
        const expand = buildExpandFields((objectSchemaRef.current as any)?.fields);
        const results = await dataSource.find(schema.objectName, {
          $filter: finalFilter.length > 0 ? finalFilter : undefined,
          $orderby: sort,
          $top: 100,
          ...(expand.length > 0 ? { $expand: expand } : {}),
        });

        let items: any[] = [];
        if (Array.isArray(results)) {
          items = results;
        } else if (results && typeof results === 'object') {
          if (Array.isArray((results as any).data)) {
            items = (results as any).data;
          } else if (Array.isArray((results as any).records)) {
            items = (results as any).records;
          } else if (Array.isArray((results as any).value)) {
            items = (results as any).value;
          }
        }

        if (isMounted) setData(items);
      } catch (err) {
        console.error('ObjectView data fetch error:', err);
      } finally {
        if (isMounted) setLoading(false);
      }
    };

    fetchData();
    return () => { isMounted = false; };
    // objectSchema intentionally omitted from deps — read via ref to prevent double-fetch
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [schema.objectName, dataSource, currentViewType, filterValues, sortConfig, refreshKey, currentNamedViewConfig, activeView, renderListView]);

  // Determine layout mode. #2578: default the record surface from how heavy the
  // object is — a field-heavy object opens create/edit/detail as a full page, a
  // light one as a drawer. Mobile always pages. An explicit `schema.layout` (or
  // a per-view navigation config, handled in handleRowClick) still wins.
  const isMobile = useIsMobile();
  const layout = schema.layout || deriveRecordSurface(objectSchema, { viewport: isMobile ? 'mobile' : 'desktop' });

  // Determine enabled operations
  const operations = schema.operations || schema.table?.operations || {
    create: true,
    read: true,
    update: true,
    delete: true,
  };

  // Handle create action
  const handleCreate = useCallback(() => {
    if (layout === 'page' && schema.onNavigate) {
      schema.onNavigate('new', 'edit');
    } else {
      setFormMode('create');
      setSelectedRecord(null);
      setIsFormOpen(true);
    }
  }, [layout, schema]);

  // Handle edit action
  const handleEdit = useCallback((record: Record<string, unknown>) => {
    if (onEditProp) {
      onEditProp(record);
      return;
    }
    if (layout === 'page' && schema.onNavigate) {
      const recordId = record.id || record._id;
      schema.onNavigate(recordId as string | number, 'edit');
    } else {
      setFormMode('edit');
      setSelectedRecord(record);
      setIsFormOpen(true);
    }
  }, [layout, schema, onEditProp]);

  // Handle view action (read a record)
  const handleView = useCallback((record: Record<string, unknown>) => {
    if (layout === 'page' && schema.onNavigate) {
      const recordId = record.id || record._id;
      schema.onNavigate(recordId as string | number, 'view');
    } else {
      setFormMode('view');
      setSelectedRecord(record);
      setIsFormOpen(true);
    }
  }, [layout, schema]);

  // Handle row click - respects NavigationConfig
  const handleRowClick = useCallback((record: Record<string, unknown>) => {
    if (onRowClick) {
      onRowClick(record);
      return;
    }

    // Check NavigationConfig
    if (navigationConfig) {
      if (navigationConfig.mode === 'none' || navigationConfig.preventNavigation) {
        return; // Do nothing
      }
      if (navigationConfig.mode === 'new_window' || navigationConfig.openNewTab) {
        const recordId = record.id || record._id;
        const url = `/${schema.objectName}/${encodeURIComponent(String(recordId))}`;
        window.open(url, '_blank');
        return;
      }
      if (navigationConfig.mode === 'drawer') {
        setFormMode('view');
        setSelectedRecord(record);
        setIsFormOpen(true);
        return;
      }
      if (navigationConfig.mode === 'modal') {
        setFormMode('view');
        setSelectedRecord(record);
        setIsFormOpen(true);
        return;
      }
      if (navigationConfig.mode === 'page') {
        const recordId = record.id || record._id;
        if (schema.onNavigate) {
          schema.onNavigate(recordId as string | number, 'view');
        }
        return;
      }
      if (navigationConfig.mode === 'split' || navigationConfig.mode === 'popover') {
        setFormMode('view');
        setSelectedRecord(record);
        setIsFormOpen(true);
        return;
      }
    }

    // Default behavior
    if (operations.read !== false) {
      handleView(record);
    }
  }, [onRowClick, navigationConfig, operations.read, handleView, schema]);

  // Handle delete action
  const handleDelete = useCallback((_record: Record<string, unknown>) => {
    setRefreshKey(prev => prev + 1);
  }, []);

  // Handle bulk delete action
  const handleBulkDelete = useCallback((_records: Record<string, unknown>[]) => {
    setRefreshKey(prev => prev + 1);
  }, []);

  // Handle form submission
  const handleFormSuccess = useCallback(() => {
    setIsFormOpen(false);
    setSelectedRecord(null);
    setRefreshKey(prev => prev + 1);
  }, []);

  // Handle form cancellation
  const handleFormCancel = useCallback(() => {
    setIsFormOpen(false);
    setSelectedRecord(null);
  }, []);

  // Handle refresh
  const handleRefresh = useCallback(() => {
    setRefreshKey(prev => prev + 1);
  }, []);

  // --- ViewSwitcher schema (for multi-view prop views) ---
  const viewSwitcherSchema: ViewSwitcherSchema | null = useMemo(() => {
    if (!hasMultiView || !viewsPropResolved || viewsPropResolved.length <= 1) return null;
    return {
      type: 'view-switcher' as const,
      variant: 'tabs',
      position: 'top',
      persistPreference: true,
      storageKey: `view-pref-${schema.objectName}`,
      defaultView: (activeView?.type || 'grid') as ViewType,
      activeView: (activeView?.type || 'grid') as ViewType,
      views: viewsPropResolved.map(v => {
        const iconMap: Record<string, string> = {
          kanban: 'kanban',
          calendar: 'calendar',
          map: 'map',
          gallery: 'layout-grid',
          timeline: 'activity',
          gantt: 'gantt-chart',
          grid: 'table',
          list: 'list',
          detail: 'file-text',
          chart: 'bar-chart-3',
        };
        return {
          type: v.type as ViewType,
          label: v.label,
          icon: iconMap[v.type] || 'table',
        };
      }),
      allowCreateView: schema.allowCreateView,
      viewActions: schema.viewActions,
    };
  }, [hasMultiView, viewsPropResolved, activeView, schema.objectName, schema.allowCreateView, schema.viewActions]);

  // Handle view type change from ViewSwitcher → map back to view ID
  const handleViewTypeChange = useCallback((viewType: ViewType) => {
    if (!viewsPropResolved) return;
    const matched = viewsPropResolved.find(v => v.type === viewType);
    if (matched && onViewChange) {
      onViewChange(matched.id);
    }
  }, [viewsPropResolved, onViewChange]);

  // Handle named view change
  const handleNamedViewChange = useCallback((viewKey: string) => {
    setActiveNamedView(viewKey);
  }, []);

  // --- FilterUI schema (auto-generated from objectSchema or filterableFields) ---
  const filterSchema: FilterUISchema | null = useMemo(() => {
    if (schema.showFilters === false) return null;

    // If filterableFields specified, use only those
    const filterableFieldNames = schema.filterableFields;
    const fields = (objectSchema as any)?.fields || {};

    const fieldEntries = filterableFieldNames
      ? filterableFieldNames.map(name => [name, fields[name] || { label: name }] as [string, any])
      : Object.entries(fields).filter(([, f]: [string, any]) => !f.hidden).slice(0, 8);

    const filterableFieldDefs = fieldEntries.map(([key, f]: [string, any]) => {
      const fieldType = f.type || 'text';
      let filterType: 'text' | 'number' | 'select' | 'multi-select' | 'date' | 'boolean' = 'text';
      let options: Array<{ label: string; value: any }> | undefined;

      if (fieldType === 'number' || fieldType === 'currency' || fieldType === 'percent') {
        filterType = 'number';
      } else if (fieldType === 'boolean' || fieldType === 'toggle') {
        filterType = 'boolean';
      } else if (fieldType === 'date' || fieldType === 'datetime') {
        filterType = 'date';
      } else if (fieldType === 'select' || fieldType === 'status' || f.options) {
        filterType = 'select';
        options = (f.options || []).map((o: any) =>
          typeof o === 'string' ? { label: o, value: o } : { label: o.label, value: o.value },
        );
      } else if (fieldType === 'lookup' || fieldType === 'master_detail' || fieldType === 'user' || fieldType === 'owner') {
        if (f.options && f.options.length > 0) {
          filterType = 'multi-select';
          options = (f.options || []).map((o: any) =>
            typeof o === 'string' ? { label: o, value: o } : { label: o.label, value: o.value },
          );
        }
      }
      return {
        field: key,
        label: f.label || key,
        type: filterType,
        placeholder: `Filter ${f.label || key}...`,
        ...(options ? { options } : {}),
      };
    });

    if (filterableFieldDefs.length === 0) return null;

    return {
      type: 'filter-ui' as const,
      layout: 'popover' as const,
      showClear: true,
      showApply: true,
      filters: filterableFieldDefs,
      values: filterValues,
    };
  }, [schema.showFilters, schema.filterableFields, objectSchema, filterValues]);

  // --- SortUI schema ---
  const showSort = (schema as ObjectViewSchema).showSort;
  const sortSchema: SortUISchema | null = useMemo(() => {
    if (showSort === false) return null;

    const fields = (objectSchema as any)?.fields || {};
    const sortableFields = Object.entries(fields)
      .filter(([, f]: [string, any]) => !f.hidden)
      .slice(0, 10)
      .map(([key, f]: [string, any]) => ({ field: key, label: f.label || key }));

    if (sortableFields.length === 0) return null;

    return {
      type: 'sort-ui' as const,
      variant: 'dropdown' as const,
      multiple: false,
      fields: sortableFields,
      sort: sortConfig,
    };
  }, [objectSchema, sortConfig, showSort]);

  // --- Generate view component schema for non-grid views ---
  const generateViewSchema = useCallback((viewType: string): any => {
    const baseProps: Record<string, any> = {
      objectName: schema.objectName,
      fields: currentNamedViewConfig?.columns || activeView?.columns || schema.table?.fields,
      className: 'h-full w-full',
      showSearch: activeView?.showSearch ?? schema.showSearch ?? false,
      showSort: activeView?.showSort ?? schema.showSort ?? false,
      showFilters: activeView?.showFilters ?? schema.showFilters ?? false,
      striped: activeView?.striped ?? false,
      bordered: activeView?.bordered ?? false,
      color: activeView?.color,
    };

    // Resolve type-specific options from current named view or active view
    // Per @objectstack/spec, type-specific config MUST be nested under the view type key
    const viewOptions = currentNamedViewConfig?.options || activeView || {};

    // Dev-mode warning for flat property access violations
    if (process.env.NODE_ENV === 'development') {
        const flatKeys = ['startDateField', 'endDateField', 'dateField', 'groupBy', 'groupField',
            'locationField', 'imageField', 'dependenciesField', 'progressField', 'titleField',
            'subtitleField', 'latitudeField', 'longitudeField'];
        const nestedConfig = viewOptions[viewType] || {};
        const found = flatKeys.filter(k => k in viewOptions && !(k in nestedConfig));
        if (found.length > 0) {
            console.warn(
                `[Spec Compliance] View options use flat properties ${JSON.stringify(found)}. ` +
                `Move them under options.${viewType} per @objectstack/spec protocol.`
            );
        }
    }

    switch (viewType) {
      case 'kanban': {
        // Per @objectstack/spec, kanban-specific config lives under view.kanban.*
        // `groupByField` is the canonical name (spec); `groupField` is a legacy alias.
        // `kanban.columns` (when provided) lists the FIELDS to render on each card —
        // these are NOT lanes; lanes are derived from the groupBy field's options.
        const kanbanCfg = viewOptions.kanban || {};
        const groupBy =
          kanbanCfg.groupByField ||
          kanbanCfg.groupField ||
          'status';
        // Card display fields: prefer explicit kanban.columns, fall back to the
        // view's outer columns. Strip out these from the spread below so they
        // don't leak into schema.columns (which the kanban component interprets
        // as LANES).
        const cardFields: string[] =
          (Array.isArray(kanbanCfg.columns) && kanbanCfg.columns.length > 0
            ? kanbanCfg.columns
            : baseProps.fields) || [];
        // eslint-disable-next-line @typescript-eslint/no-unused-vars
        const { columns: _kanbanColumns, groupByField: _gbf, groupField: _gf, titleField: _tf, conditionalFormatting: _kanbanCf, ...restKanban } = kanbanCfg;
        // Forward conditional formatting to kanban (issue #1584): nested
        // `options.kanban.conditionalFormatting` wins, then the view-level, then
        // the schema-level rule — matching how the grid branch resolves it.
        // Previously the top-level rule was dropped for kanban entirely.
        const kanbanConditionalFormatting =
          kanbanCfg.conditionalFormatting ??
          activeView?.conditionalFormatting ??
          (schema as any).conditionalFormatting;
        return {
          type: 'object-kanban',
          ...baseProps,
          groupBy,
          groupField: groupBy,
          titleField: kanbanCfg.titleField || 'name',
          cardFields,
          ...restKanban,
          ...(kanbanConditionalFormatting ? { conditionalFormatting: kanbanConditionalFormatting } : {}),
        };
      }
      case 'calendar':
        return {
          type: 'object-calendar',
          ...baseProps,
          startDateField: viewOptions.calendar?.startDateField || 'start_date',
          endDateField: viewOptions.calendar?.endDateField || 'end_date',
          titleField: viewOptions.calendar?.titleField || 'name',
          ...(viewOptions.calendar || {}),
        };
      case 'gallery':
        return {
          type: 'object-gallery',
          ...baseProps,
          // `coverField` is the spec key; `imageField` is the legacy alias that
          // ObjectGallery still consults as a flat prop.
          imageField: viewOptions.gallery?.coverField || viewOptions.gallery?.imageField,
          titleField: viewOptions.gallery?.titleField || 'name',
          ...(viewOptions.gallery || {}),
        };
      case 'timeline':
        return {
          type: 'object-timeline',
          ...baseProps,
          // `startDateField` is the spec key; `dateField` is the legacy alias.
          startDateField: viewOptions.timeline?.startDateField || viewOptions.timeline?.dateField || 'created_at',
          titleField: viewOptions.timeline?.titleField || 'name',
          ...(viewOptions.timeline || {}),
        };
      case 'gantt':
        return {
          type: 'object-gantt',
          ...baseProps,
          startDateField: viewOptions.gantt?.startDateField || 'start_date',
          endDateField: viewOptions.gantt?.endDateField || 'end_date',
          progressField: viewOptions.gantt?.progressField || 'progress',
          dependenciesField: viewOptions.gantt?.dependenciesField || 'dependencies',
          ...(viewOptions.gantt || {}),
        };
      case 'map':
        return {
          type: 'object-map',
          ...baseProps,
          locationField: viewOptions.map?.locationField || 'location',
          ...(viewOptions.map || {}),
        };
      case 'tree':
        return {
          type: 'object-tree',
          ...baseProps,
          // Single-parent pointer field; auto-detected from the object's
          // `tree`/self-reference field when not specified.
          parentField: viewOptions.tree?.parentField,
          labelField: viewOptions.tree?.labelField || viewOptions.tree?.titleField || 'name',
          // The view's columns double as the tree-grid's flat columns.
          fields: viewOptions.tree?.fields || baseProps.fields,
          defaultExpandedDepth: viewOptions.tree?.defaultExpandedDepth,
          ...(viewOptions.tree || {}),
        };
      case 'chart': {
        // Aggregated chart of the object's records, delegating to the same
        // object-chart component the dashboard uses.
        const chartCfg = viewOptions.chart || {};
        // ADR-0021 (#1890): dataset-bound chart — the single author-facing shape.
        if (chartCfg.dataset) {
          const dims: string[] = Array.isArray(chartCfg.dimensions) ? chartCfg.dimensions : [];
          const vals: string[] = Array.isArray(chartCfg.values) ? chartCfg.values : [];
          return {
            type: 'object-chart',
            dataset: chartCfg.dataset,
            dimensions: dims,
            values: vals,
            chartType: chartCfg.chartType || 'bar',
            xAxisKey: dims[0],
            series: vals.map((v: string) => ({ dataKey: v, label: v })),
            className: 'h-[400px] w-full',
          };
        }
        // Legacy inline aggregate (deprecated — pre-ADR-0021 metadata).
        const valueField = (Array.isArray(chartCfg.yAxisFields) && chartCfg.yAxisFields[0])
          || chartCfg.valueField || 'value';
        const categoryField = chartCfg.xAxisField || chartCfg.categoryField || 'name';
        return {
          type: 'object-chart',
          objectName: schema.objectName,
          chartType: chartCfg.chartType || 'bar',
          aggregate: {
            field: valueField,
            function: chartCfg.aggregation || 'count',
            groupBy: categoryField,
          },
          xAxisKey: categoryField,
          series: [{ dataKey: valueField, label: valueField }],
          className: 'h-[400px] w-full',
        };
      }
      default:
        return null;
    }
  }, [schema.objectName, schema.table?.fields, currentNamedViewConfig, activeView]);

  // Build grid schema (default content renderer)
  const gridSchema: ObjectGridSchema = useMemo(() => ({
    type: 'object-grid',
    objectName: schema.objectName,
    title: schema.table?.title,
    description: schema.table?.description,
    fields: currentNamedViewConfig?.columns || activeView?.columns || schema.table?.fields,
    columns: currentNamedViewConfig?.columns || activeView?.columns || schema.table?.columns,
    operations: {
      ...operations,
      create: false, // Create is handled by the view's create button
    },
    defaultFilters: currentNamedViewConfig?.filter || activeView?.filter || schema.table?.defaultFilters,
    defaultSort: currentNamedViewConfig?.sort || activeView?.sort || schema.table?.defaultSort,
    pageSize: schema.table?.pageSize,
    selectable: schema.table?.selectable,
    striped: activeView?.striped ?? schema.table?.striped,
    bordered: activeView?.bordered ?? schema.table?.bordered,
    className: schema.table?.className,
  }), [schema, operations, currentNamedViewConfig, activeView]);

  // Build form schema
  const buildFormSchema = (): ObjectFormSchema => {
    const recordId = selectedRecord
      ? ((selectedRecord.id || selectedRecord._id) as string | number | undefined)
      : undefined;

    return {
      type: 'object-form',
      objectName: schema.objectName,
      mode: formMode,
      recordId,
      title: schema.form?.title,
      description: schema.form?.description,
      fields: schema.form?.fields,
      customFields: schema.form?.customFields,
      // #2545: `sections` is the spec-aligned key (it used to be dropped
      // here); `groups` is its deprecated legacy alias, normalized to
      // sections inside ObjectForm.
      sections: schema.form?.sections,
      groups: schema.form?.groups,
      layout: schema.form?.layout,
      columns: schema.form?.columns,
      showSubmit: schema.form?.showSubmit,
      submitText: schema.form?.submitText,
      showCancel: schema.form?.showCancel,
      cancelText: schema.form?.cancelText,
      showReset: schema.form?.showReset,
      initialValues: schema.form?.initialValues,
      // framework#1894 / #2998: forward the spec-aligned structured
      // `buttons`/`defaults`; ObjectForm folds them onto the flat props above
      // (an explicitly-set flat key still wins).
      buttons: schema.form?.buttons,
      defaults: schema.form?.defaults,
      readOnly: schema.form?.readOnly || formMode === 'view',
      className: schema.form?.className,
      // Master-detail by config: a form view can declare inline child
      // collections; ObjectForm renders them as an atomic master-detail form
      // (no bespoke page). ObjectForm skips them in view mode.
      subforms: schema.form?.subforms,
      onSuccess: handleFormSuccess,
      onCancel: handleFormCancel,
    };
  };

  // Get form title based on mode
  const getFormTitle = (): string => {
    if (schema.form?.title) return schema.form.title;
    const objectLabel = (objectSchema?.label as string) || schema.objectName;
    switch (formMode) {
      case 'create': return `Create ${objectLabel}`;
      case 'edit': return `Edit ${objectLabel}`;
      case 'view': return `View ${objectLabel}`;
      default: return objectLabel;
    }
  };

  // Determine form container width from navigation config
  const formWidthClass = useMemo(() => {
    const w = navigationConfig?.width;
    if (!w) return '';
    if (typeof w === 'number') return `max-w-[${w}px]`;
    return `max-w-[${w}]`;
  }, [navigationConfig]);

  // Render the form in a drawer
  const renderDrawerForm = () => (
    <Drawer open={isFormOpen} onOpenChange={setIsFormOpen} direction="right">
      <DrawerContent className={cn('w-full sm:max-w-2xl', formWidthClass)}>
        <DrawerHeader>
          <DrawerTitle>{getFormTitle()}</DrawerTitle>
          {schema.form?.description && (
            <DrawerDescription>{schema.form.description}</DrawerDescription>
          )}
        </DrawerHeader>
        <div className="flex-1 overflow-y-auto px-4 pb-4">
          <ObjectForm schema={buildFormSchema()} dataSource={dataSource} />
        </div>
      </DrawerContent>
    </Drawer>
  );

  // Render the form in a modal
  const renderModalForm = () => (
    <Dialog open={isFormOpen} onOpenChange={setIsFormOpen}>
      <DialogContent className={cn('max-w-2xl max-h-[90vh] overflow-y-auto', formWidthClass)}>
        <DialogHeader>
          <DialogTitle>{getFormTitle()}</DialogTitle>
          {schema.form?.description && (
            <DialogDescription>{schema.form.description}</DialogDescription>
          )}
        </DialogHeader>
        <ObjectForm schema={buildFormSchema()} dataSource={dataSource} />
      </DialogContent>
    </Dialog>
  );

  // Compute merged filters for the list
  const mergedFilters = useMemo(() => {
    const hasUserFilters = Object.keys(filterValues).some(
      k => filterValues[k] !== undefined && filterValues[k] !== '' && filterValues[k] !== null,
    );
    if (hasUserFilters) {
      return Object.entries(filterValues)
        .filter(([, v]) => v !== undefined && v !== '' && v !== null)
        .map(([field, value]) => ({ field, operator: 'equals' as const, value }));
    }
    return currentNamedViewConfig?.filter || activeView?.filter || schema.table?.defaultFilters;
  }, [filterValues, currentNamedViewConfig, activeView, schema.table?.defaultFilters]);

  const mergedSort = useMemo(() => {
    return sortConfig.length > 0
      ? sortConfig
      : currentNamedViewConfig?.sort || activeView?.sort || schema.table?.defaultSort;
  }, [sortConfig, currentNamedViewConfig, activeView, schema.table?.defaultSort]);

  // --- Content renderer ---
  const renderContent = () => {
    const key = `${schema.objectName}-${activeNamedView || activeView?.id || 'default'}-${currentViewType}-${refreshKey}`;

    // If a custom renderListView is provided, use it
    if (renderListView) {
      return renderListView({
        schema: {
          type: 'list-view',
          objectName: schema.objectName,
          viewType: currentViewType as any,
          // Active view's display label — ListView appends it to export
          // download filenames.
          label: (currentNamedViewConfig as any)?.label ?? activeView?.label,
          // Spec-canonical key (#2890) — the view configs this reads from are
          // already `columns`-keyed, so emitting `fields` here was a pure
          // canonical→legacy downgrade.
          columns: currentNamedViewConfig?.columns || activeView?.columns || schema.table?.fields,
          filter: mergedFilters,
          sort: mergedSort,
          // Propagate appearance/view-config properties for live preview
          rowHeight: activeView?.rowHeight,
          densityMode: activeView?.densityMode,
          groupBy: activeView?.groupBy,
          groupBy2: activeView?.groupBy2,
          grouping: activeView?.grouping,
          options: currentNamedViewConfig?.options || activeView,
          // Propagate toolbar toggle flags
          showSearch: activeView?.showSearch ?? schema.showSearch,
          showFilters: activeView?.showFilters ?? schema.showFilters,
          showSort: activeView?.showSort ?? schema.showSort,
          showHideFields: activeView?.showHideFields ?? (schema as any).showHideFields,
          showGroup: activeView?.showGroup ?? (schema as any).showGroup,
          showColor: activeView?.showColor ?? (schema as any).showColor,
          showDensity: activeView?.showDensity ?? (schema as any).showDensity,
          compactToolbar: activeView?.compactToolbar ?? (schema as any).compactToolbar,
          allowExport: activeView?.allowExport ?? (schema as any).allowExport,
          // Propagate display properties
          striped: activeView?.striped ?? (schema as any).striped,
          bordered: activeView?.bordered ?? (schema as any).bordered,
          color: activeView?.color ?? (schema as any).color,
          // Propagate view-config properties (Bug 4 / items 14-22)
          inlineEdit: activeView?.inlineEdit ?? (schema as any).inlineEdit,
          wrapHeaders: activeView?.wrapHeaders ?? (schema as any).wrapHeaders,
          clickIntoRecordDetails: activeView?.clickIntoRecordDetails ?? (schema as any).clickIntoRecordDetails,
          addRecordViaForm: activeView?.addRecordViaForm ?? (schema as any).addRecordViaForm,
          addDeleteRecordsInline: activeView?.addDeleteRecordsInline ?? (schema as any).addDeleteRecordsInline,
          collapseAllByDefault: activeView?.collapseAllByDefault ?? (schema as any).collapseAllByDefault,
          fieldTextColor: activeView?.fieldTextColor ?? (schema as any).fieldTextColor,
          prefixField: activeView?.prefixField ?? (schema as any).prefixField,
          showDescription: activeView?.showDescription ?? (schema as any).showDescription,
          // ViewData source override (spec `data` key) — e.g. gantt views fed
          // by a composite api endpoint; without this pick the api provider
          // never reaches the renderer.
          data: (currentNamedViewConfig as any)?.data ?? (activeView as any)?.data ?? (schema as any).data,
          // Propagate new spec properties (P0/P1/P2)
          navigation: activeView?.navigation ?? (schema as any).navigation,
          selection: activeView?.selection ?? (schema as any).selection,
          pagination: activeView?.pagination ?? (schema as any).pagination,
          searchableFields: activeView?.searchableFields ?? (schema as any).searchableFields,
          filterableFields: activeView?.filterableFields ?? (schema as any).filterableFields,
          resizable: activeView?.resizable ?? (schema as any).resizable,
          hiddenFields: activeView?.hiddenFields ?? (schema as any).hiddenFields,
          rowActions: activeView?.rowActions ?? (schema as any).rowActions,
          rowActionDefs: (activeView as any)?.rowActionDefs ?? (schema as any).rowActionDefs,
          bulkActions: activeView?.bulkActions ?? (schema as any).bulkActions,
          sharing: activeView?.sharing ?? (schema as any).sharing,
          addRecord: activeView?.addRecord ?? (schema as any).addRecord,
          conditionalFormatting: activeView?.conditionalFormatting ?? (schema as any).conditionalFormatting,
          userFilters: activeView?.userFilters ?? (schema as any).userFilters,
          showRecordCount: activeView?.showRecordCount ?? (schema as any).showRecordCount,
          allowPrinting: activeView?.allowPrinting ?? (schema as any).allowPrinting,
          virtualScroll: activeView?.virtualScroll ?? (schema as any).virtualScroll,
          emptyState: activeView?.emptyState ?? (schema as any).emptyState,
          aria: activeView?.aria ?? (schema as any).aria,
          // Propagate refresh signal so ListView re-fetches after mutations
          refreshTrigger: refreshKey,
        },
        dataSource,
        onEdit: handleEdit,
        onRowClick: handleRowClick,
        className: 'h-full',
        refreshKey,
        onAddRecord: handleCreate,
      });
    }

    // For non-grid views, use SchemaRenderer with generated schema
    if (currentViewType !== 'grid') {
      const viewSchema = generateViewSchema(currentViewType);
      if (viewSchema && SchemaRendererComponent) {
        return (
          <SchemaRendererComponent
            key={key}
            schema={viewSchema}
            dataSource={dataSource}
            data={data}
            loading={loading}
          />
        );
      }
      // Fallback: if SchemaRenderer is not available or schema not generated
      if (!SchemaRendererComponent) {
        return (
          <div className="flex items-center justify-center h-40 text-muted-foreground">
            <p>SchemaRenderer not available. Install @object-ui/react to render {currentViewType} views.</p>
          </div>
        );
      }
    }

    // Default: use ObjectGrid
    return (
      <ObjectGrid
        key={key}
        schema={gridSchema}
        dataSource={dataSource}
        onRowClick={handleRowClick}
        onEdit={operations.update !== false ? handleEdit : undefined}
        onDelete={operations.delete !== false ? handleDelete : undefined}
        onBulkDelete={operations.delete !== false ? handleBulkDelete : undefined}
      />
    );
  };

  // --- Named list views tabs ---
  const renderNamedViewTabs = () => {
    // ADR-0053: host owns the switcher (ViewTabBar) — don't duplicate it.
    if (hideNamedViewTabs) return null;
    if (!hasNamedViews) return null;
    const entries = Object.entries(namedListViews!);
    if (entries.length <= 1) return null;

    return (
      <Tabs value={activeNamedView} onValueChange={handleNamedViewChange} className="w-full">
        <TabsList className="w-auto">
          {entries.map(([key, view]) => (
            <TabsTrigger key={key} value={key} className="text-sm">
              {view.label || key}
            </TabsTrigger>
          ))}
        </TabsList>
      </Tabs>
    );
  };

  // Render toolbar — only named view tabs; filter/sort/search is handled by ListView
  const renderToolbar = () => {
    const showCreateButton = schema.showCreate !== false && operations.create !== false;
    const showViewSwitcherToggle = schema.showViewSwitcher === true; // Changed: default to false (hidden)

    const namedViewTabs = renderNamedViewTabs();

    // Hide toolbar entirely if there is nothing to show
    if (!namedViewTabs && !showViewSwitcherToggle && !showCreateButton && !toolbarAddon) return null;

    return (
      <div className="flex flex-col gap-3">
        {/* Named view tabs (if any) */}
        {namedViewTabs}

        {/* ViewSwitcher + action buttons row */}
        {(showViewSwitcherToggle || showCreateButton || toolbarAddon) && (
          <div className="flex items-center justify-between gap-4">
            <div className="flex items-center gap-2">
              {showViewSwitcherToggle && viewSwitcherSchema && (
                <ViewSwitcher
                  schema={viewSwitcherSchema}
                  onViewChange={handleViewTypeChange}
                  onCreateView={onCreateView}
                  onViewAction={onViewAction}
                  className="overflow-x-auto"
                />
              )}
            </div>

            {/* Right side: Actions */}
            <div className="flex items-center gap-2">
              {toolbarAddon}
              {showCreateButton && (
                <Button size="sm" onClick={handleCreate}>
                  <Plus className="h-4 w-4" />
                  {createVerb}
                </Button>
              )}
            </div>
          </div>
        )}
      </div>
    );
  };

  // Determine which form container to render
  const formLayout = navigationConfig?.mode === 'modal' ? 'modal'
    : navigationConfig?.mode === 'drawer' ? 'drawer'
    : navigationConfig?.mode === 'split' ? 'split'
    : navigationConfig?.mode === 'popover' ? 'popover'
    : layout;

  // Build the record detail content for NavigationOverlay (split/popover modes)
  const renderOverlayDetail = (_record: Record<string, unknown>) => (
    <div className="space-y-3">
      <ObjectForm schema={buildFormSchema()} dataSource={dataSource} />
    </div>
  );

  // Shared handler for NavigationOverlay onOpenChange — close form when overlay is dismissed
  const handleOverlayOpenChange = useCallback((open: boolean) => {
    if (!open) handleFormCancel();
  }, [handleFormCancel]);

  // Computed once so a `null` toolbar (nothing to show — no named views, no
  // view switcher, no create button, no addon) doesn't still leave behind an
  // empty `mb-4` spacer div above the content.
  const toolbar = renderToolbar();

  // For split mode, wrap content inside NavigationOverlay with mainContent
  if (formLayout === 'split') {
    const objectLabel = (objectSchema?.label as string) || schema.objectName;
    return (
      <div className={cn('flex flex-col h-full min-w-0 overflow-hidden', className)}>
        {(schema.title || schema.description) && (
          <div className="mb-4 shrink-0">
            {schema.title && <h2 className="text-2xl font-bold tracking-tight">{schema.title}</h2>}
            {schema.description && <p className="text-muted-foreground mt-1">{schema.description}</p>}
          </div>
        )}
        {toolbar && <div className="mb-4 shrink-0">{toolbar}</div>}
        <div className="flex-1 min-h-0 min-w-0 overflow-hidden">
          {isFormOpen && selectedRecord ? (
            <NavigationOverlay
              isOpen={isFormOpen}
              selectedRecord={selectedRecord}
              mode="split"
              close={handleFormCancel}
              setIsOpen={handleOverlayOpenChange}
              width={navigationConfig?.width}
              isOverlay={true}
              title={`${objectLabel} Detail`}
              mainContent={<div className="h-full overflow-auto">{renderContent()}</div>}
            >
              {renderOverlayDetail}
            </NavigationOverlay>
          ) : (
            renderContent()
          )}
        </div>
      </div>
    );
  }

  return (
    <div className={cn('flex flex-col h-full min-w-0 overflow-hidden', className)}>
      {/* Title and description */}
      {(schema.title || schema.description) && (
        <div className="mb-4 shrink-0">
          {schema.title && (
            <h2 className="text-2xl font-bold tracking-tight">{schema.title}</h2>
          )}
          {schema.description && (
            <p className="text-muted-foreground mt-1">{schema.description}</p>
          )}
        </div>
      )}

      {/* Toolbar */}
      {toolbar && <div className="mb-4 shrink-0">{toolbar}</div>}

      {/* Content */}
      <div className="flex-1 min-h-0 min-w-0 overflow-hidden">
        {renderContent()}
      </div>

      {/* Form (drawer or modal) */}
      {formLayout === 'drawer' && renderDrawerForm()}
      {formLayout === 'modal' && renderModalForm()}
      {/* Popover mode — uses NavigationOverlay Dialog fallback (no popoverTrigger) */}
      {formLayout === 'popover' && isFormOpen && selectedRecord && (
        <NavigationOverlay
          isOpen={isFormOpen}
          selectedRecord={selectedRecord}
          mode="popover"
          close={handleFormCancel}
          setIsOpen={handleOverlayOpenChange}
          width={navigationConfig?.width}
          isOverlay={true}
          title={getFormTitle()}
        >
          {renderOverlayDetail}
        </NavigationOverlay>
      )}
    </div>
  );
};