Merge pull request #1035 from objectstack-ai/copilot/fix-mobile-detail-page-layout

Author: hotlong

ROADMAP.md

@@ -1474,6 +1474,20 @@ All 313 `@object-ui/fields` tests pass.
 
 ---
 
+### DetailSection — Mobile Responsive col-span Fix (March 2026)
+
+> **Bug:** On mobile devices, detail page fields displayed in 3-column layout instead of single column, causing content to squeeze together and severely impacting readability.
+
+**Root Cause:** When `applyAutoSpan` set `span: 3` on wide fields (textarea, markdown, etc.) in a 3-column layout, the resulting `col-span-3` CSS class was applied without responsive prefixes. In CSS Grid, when an item has `col-span-3` in a `grid-cols-1` layout, the browser creates 2 implicit column tracks — and subsequent auto-placed items flow into those implicit columns, producing a 3-column layout even on mobile.
+
+**Fix:**
+
+- **DetailSection** (`packages/plugin-detail/src/DetailSection.tsx`): Added `getResponsiveSpanClass()` helper that generates responsive col-span classes matching the grid breakpoints. For a 3-column layout: no col-span at base (mobile single-column), `md:col-span-2` at tablet, `lg:col-span-3` at desktop. For a 2-column layout: no col-span at base, `md:col-span-2` at tablet+. This ensures col-span never exceeds the visible column count at each breakpoint, preventing implicit grid columns on mobile.
+
+**Tests:** 11 new tests (8 getResponsiveSpanClass unit tests + 3 DetailSection integration tests verifying no bare col-span-N classes appear). All 52 plugin-detail tests pass.
+
+---
+
 ### RecordDetailView — Action Button Full-Chain Integration (March 2026)
 
 > **Issue #107:** All Action buttons on record detail pages (Change Stage, Mark as Won, etc.) clicked with zero response — no dialogs, no API calls, no toast, no data refresh.

packages/plugin-detail/src/DetailSection.tsx

@@ -31,6 +31,28 @@ import { applyDetailAutoLayout } from './autoLayout';
 import { useDetailTranslation } from './useDetailTranslation';
 import { useSafeFieldLabel } from '@object-ui/react';
 
+/**
+ * Compute responsive col-span classes so that col-span never exceeds the
+ * visible column count at each Tailwind breakpoint.
+ *
+ * For columns=1: no span class (always single column)
+ * For columns=2: md:col-span-{min(span,2)}
+ * For columns>=3: md:col-span-{min(span,2)} lg:col-span-{min(span,3)}
+ */
+export function getResponsiveSpanClass(span: number | undefined, columns: number): string {
+  if (!span || span <= 1 || columns <= 1) return '';
+
+  if (columns === 2) {
+    return span >= 2 ? 'md:col-span-2' : '';
+  }
+
+  // columns >= 3: grid-cols-1 md:grid-cols-2 lg:grid-cols-3
+  if (span === 2) return 'md:col-span-2';
+  if (span >= 3) return 'md:col-span-2 lg:col-span-3';
+
+  return '';
+}
+
 export interface DetailSectionProps {
   section: DetailViewSectionType;
   data?: any;
@@ -67,6 +89,23 @@ export const DetailSection: React.FC<DetailSectionProps> = ({
     });
   }, []);
 
+  // Filter out empty fields when hideEmpty is set
+  const visibleFields = section.hideEmpty
+    ? section.fields.filter((field) => {
+        const value = data?.[field.name] ?? field.value;
+        return value !== null && value !== undefined && value !== '';
+      })
+    : section.fields;
+
+  // Hide entire section when all fields are empty
+  if (visibleFields.length === 0) return null;
+
+  // Apply auto-layout: infer columns and auto-span wide fields
+  const { fields: layoutFields, columns: effectiveColumns } = applyDetailAutoLayout(
+    visibleFields,
+    section.columns
+  );
+
   const renderField = (field: DetailViewField) => {
     const value = data?.[field.name] ?? field.value;
 
@@ -75,13 +114,9 @@ export const DetailSection: React.FC<DetailSectionProps> = ({
       return <SchemaRenderer schema={field.render} data={{ ...data, value }} />;
     }
 
-    // Calculate span class based on field.span value
-    const spanClass = field.span === 1 ? 'col-span-1' :
-                      field.span === 2 ? 'col-span-2' :
-                      field.span === 3 ? 'col-span-3' :
-                      field.span === 4 ? 'col-span-4' :
-                      field.span === 5 ? 'col-span-5' :
-                      field.span === 6 ? 'col-span-6' : '';
+    // Calculate responsive span class so col-span never exceeds the visible
+    // column count at each breakpoint, preventing implicit columns on mobile.
+    const spanClass = getResponsiveSpanClass(field.span, effectiveColumns);
 
     const displayValue = (() => {
       if (value === null || value === undefined) return <span className="text-muted-foreground/50 text-xs italic">—</span>;
@@ -178,23 +213,6 @@ export const DetailSection: React.FC<DetailSectionProps> = ({
     );
   };
 
-  // Filter out empty fields when hideEmpty is set
-  const visibleFields = section.hideEmpty
-    ? section.fields.filter((field) => {
-        const value = data?.[field.name] ?? field.value;
-        return value !== null && value !== undefined && value !== '';
-      })
-    : section.fields;
-
-  // Hide entire section when all fields are empty
-  if (visibleFields.length === 0) return null;
-
-  // Apply auto-layout: infer columns and auto-span wide fields
-  const { fields: layoutFields, columns: effectiveColumns } = applyDetailAutoLayout(
-    visibleFields,
-    section.columns
-  );
-
   const content = (
     <div 
       className={cn(

packages/plugin-detail/src/__tests__/DetailSection.test.tsx

@@ -8,7 +8,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { render, screen } from '@testing-library/react';
-import { DetailSection } from '../DetailSection';
+import { DetailSection, getResponsiveSpanClass } from '../DetailSection';
 
 describe('DetailSection', () => {
   it('should render text fields as plain text', () => {
@@ -317,4 +317,113 @@ describe('DetailSection', () => {
     // Should use 'text' renderer, not 'number'
     expect(screen.getByText('Alice')).toBeInTheDocument();
   });
+
+  it('should use responsive span classes for wide fields in 3-column layout', () => {
+    const section = {
+      title: 'Wide Fields',
+      fields: Array.from({ length: 12 }, (_, i) => ({
+        name: `field_${i}`,
+        label: `Field ${i}`,
+        type: i === 5 ? 'textarea' : 'text',
+      })),
+    };
+    const { container } = render(
+      <DetailSection section={section} data={{}} />
+    );
+    const grid = container.querySelector('.grid');
+    expect(grid).toBeTruthy();
+    expect(grid!.className).toContain('lg:grid-cols-3');
+    // Wide field (textarea) should have responsive span, not bare col-span-3
+    const fields = container.querySelectorAll('[class*="col-span"]');
+    fields.forEach((field) => {
+      // No bare col-span-3 at base level — must be lg: prefixed
+      const classes = field.className.split(/\s+/);
+      const hasBareSpan3 = classes.some((c: string) => c === 'col-span-3');
+      expect(hasBareSpan3).toBe(false);
+    });
+  });
+
+  it('should use responsive span classes for wide fields in 2-column layout', () => {
+    const section = {
+      title: 'Wide Fields',
+      fields: [
+        { name: 'a', label: 'A', type: 'text' },
+        { name: 'b', label: 'B', type: 'text' },
+        { name: 'c', label: 'C', type: 'text' },
+        { name: 'd', label: 'D', type: 'text' },
+        { name: 'notes', label: 'Notes', type: 'textarea' },
+      ],
+    };
+    const { container } = render(
+      <DetailSection section={section} data={{}} />
+    );
+    const grid = container.querySelector('.grid');
+    expect(grid!.className).toContain('md:grid-cols-2');
+    // Wide field should have md:col-span-2, not bare col-span-2
+    const fields = container.querySelectorAll('[class*="col-span"]');
+    fields.forEach((field) => {
+      const classes = field.className.split(/\s+/);
+      const hasBareSpan2 = classes.some((c: string) => c === 'col-span-2');
+      expect(hasBareSpan2).toBe(false);
+    });
+  });
+
+  it('should not apply col-span at base breakpoint to prevent implicit grid columns on mobile', () => {
+    const section = {
+      title: 'Mobile Safe',
+      fields: Array.from({ length: 15 }, (_, i) => ({
+        name: `field_${i}`,
+        label: `Field ${i}`,
+        type: i === 0 ? 'textarea' : 'text',
+      })),
+    };
+    const { container } = render(
+      <DetailSection section={section} data={{}} />
+    );
+    // Ensure no bare col-span-N (N>1) classes without responsive prefix
+    const allElements = container.querySelectorAll('*');
+    allElements.forEach((el) => {
+      const classes = el.className?.split?.(/\s+/) || [];
+      classes.forEach((cls: string) => {
+        if (cls.match(/^col-span-[2-9]$/)) {
+          throw new Error(`Found bare "${cls}" class without responsive prefix — would break mobile single-column layout`);
+        }
+      });
+    });
+  });
+});
+
+describe('getResponsiveSpanClass', () => {
+  it('should return empty string for no span', () => {
+    expect(getResponsiveSpanClass(undefined, 2)).toBe('');
+  });
+
+  it('should return empty string for span=1', () => {
+    expect(getResponsiveSpanClass(1, 3)).toBe('');
+  });
+
+  it('should return empty string for 1-column layout', () => {
+    expect(getResponsiveSpanClass(3, 1)).toBe('');
+  });
+
+  it('should return md:col-span-2 for span=2 in 2-column layout', () => {
+    expect(getResponsiveSpanClass(2, 2)).toBe('md:col-span-2');
+  });
+
+  it('should cap span to 2 in 2-column layout', () => {
+    expect(getResponsiveSpanClass(3, 2)).toBe('md:col-span-2');
+    expect(getResponsiveSpanClass(6, 2)).toBe('md:col-span-2');
+  });
+
+  it('should return md:col-span-2 for span=2 in 3-column layout', () => {
+    expect(getResponsiveSpanClass(2, 3)).toBe('md:col-span-2');
+  });
+
+  it('should return responsive classes for span=3 in 3-column layout', () => {
+    expect(getResponsiveSpanClass(3, 3)).toBe('md:col-span-2 lg:col-span-3');
+  });
+
+  it('should cap span to 3 in 3-column layout', () => {
+    expect(getResponsiveSpanClass(6, 3)).toBe('md:col-span-2 lg:col-span-3');
+  });
 });