Merge pull request #488 from objectstack-ai/copilot/optimize-mobile-user-experience

Author: hotlong

ROADMAP.md

@@ -4,7 +4,7 @@
 > **Current Version:** v0.5.x
 > **Spec Version:** @objectstack/spec v3.0.0
 > **Client Version:** @objectstack/client v3.0.0
-> **Current Priority:** 🎯 Developer Experience · User Experience · Component Excellence · Documentation
+> **Current Priority:** 🎯 Developer Experience · User Experience · Component Excellence · Documentation · Mobile UX
 
 ---
 
@@ -20,6 +20,7 @@ ObjectUI is a universal Server-Driven UI (SDUI) engine built on React + Tailwind
 2. **🎨 User Experience (UX)** — Console polish, i18n completeness, accessibility, performance at scale
 3. **🧩 Component Excellence** — Every component polished, well-tested, and delightful to use
 4. **📖 Documentation** — Complete API docs, rich Storybook stories, tutorials, and guides
+5. **📱 Mobile User Experience** — Responsive layouts, touch-friendly interactions, PWA support
 
 > 📄 Companion documents:
 > - [SPEC_COMPLIANCE_EVALUATION.md](./SPEC_COMPLIANCE_EVALUATION.md) — Per-package spec compliance (98% current)
@@ -283,6 +284,193 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 
 ---
 
+### P5. Mobile User Experience 📱
+
+**Goal:** Every component and page delivers a native-quality experience on phones and tablets — responsive layout, touch-friendly interactions, and fast performance on mobile networks.
+
+> **Existing Infrastructure:** `@object-ui/mobile` provides `useBreakpoint` (isMobile/isTablet/isDesktop), `useResponsive`, `useGesture`, `useTouchTarget`, `MobileProvider`, and `ResponsiveContainer`. `@object-ui/layout` provides `ResponsiveGrid` with Tailwind-aligned breakpoints. These building blocks are production-ready but under-adopted across plugin views and the Console app.
+
+#### P5.1 Plugin Views — Mobile-First Layouts
+
+Each plugin view must work seamlessly from 320px (small phone) to 2560px (ultrawide).
+
+##### ObjectGrid (`plugin-grid`)
+- [ ] Wrap data table in `overflow-x-auto` container for horizontal scroll on mobile
+- [ ] Add responsive toolbar: stack filter/sort/search controls vertically below `sm:` breakpoint
+- [ ] Collapse non-essential columns on mobile via `hidden sm:table-cell` pattern
+- [ ] Scale row padding: `px-2 py-1.5 sm:px-3 sm:py-2 md:px-4 md:py-2.5`
+- [ ] Add mobile card-view fallback for screens below 480px (toggle between table and card layout)
+- [ ] Ensure touch targets ≥ 44px for all interactive row elements
+
+##### ObjectKanban (`plugin-kanban`)
+- [ ] Stack columns vertically on mobile with horizontal swipe navigation between columns
+- [ ] Scale card sizing: `p-2 sm:p-3 md:p-4` with responsive typography
+- [ ] Add touch-friendly drag-and-drop via `useGesture` (long-press to initiate, haptic feedback)
+- [ ] Column headers: `text-sm sm:text-base` with truncation on mobile
+- [ ] Add column count badge and swipe indicator on mobile
+- [ ] Limit visible card fields on mobile (show title + status only, expand on tap)
+
+##### ObjectForm (`plugin-form`)
+- [ ] Ensure mobile-first column stacking: 1 column on `xs`, 2 on `sm:`, 3+ on `md:`
+- [ ] Scale field labels: `text-xs sm:text-sm` with proper spacing
+- [ ] Make action buttons full-width on mobile: `w-full sm:w-auto`
+- [ ] Increase touch targets for all form controls (min 44×44px)
+- [ ] Optimize select/dropdown fields for mobile (bottom sheet pattern on phones)
+- [ ] Ensure date pickers and multi-select fields are mobile-friendly
+
+##### ObjectDashboard (`plugin-dashboard`)
+- [ ] Implement responsive grid: `grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4`
+- [ ] Scale widget padding: `p-3 sm:p-4 md:p-6` per widget card
+- [ ] Stack dashboard header controls on mobile (title above actions)
+- [ ] Add swipeable widget carousel option for mobile
+- [ ] Chart widgets: reduce axis label density on mobile
+
+##### ObjectCalendar (`plugin-calendar`)
+- [ ] Replace fixed `h-[calc(100vh-200px)]` with responsive height: `h-[calc(100vh-120px)] sm:h-[calc(100vh-160px)] md:h-[calc(100vh-200px)]`
+- [ ] Default to day or agenda view on mobile (month view unreadable on phones)
+- [ ] Add swipe-to-navigate between days/weeks on mobile via `useGesture`
+- [ ] Scale event text: `text-xs sm:text-sm` with single-line truncation
+- [ ] Make event creation touch-friendly (long-press on timeslot)
+
+##### ObjectTimeline (`plugin-timeline`)
+- [ ] Switch from side-by-side to single-column layout on mobile
+- [ ] Scale item padding: `p-2 sm:p-3 md:p-4` with responsive typography
+- [ ] Truncate event descriptions on mobile with "Show more" expand
+- [ ] Add pull-to-refresh via `usePullToRefresh` for timeline data
+
+##### ObjectList (`plugin-list`)
+- [ ] Stack toolbar controls vertically on mobile with collapsible filter panel
+- [ ] Scale search bar: `w-full sm:w-48 lg:w-64` (full-width on mobile)
+- [ ] Responsive list item padding: `px-2 sm:px-3 md:px-4`
+- [ ] Ensure action menus use bottom sheet on mobile instead of popovers
+- [ ] Touch-friendly row selection (checkbox size ≥ 44px)
+
+##### DetailView (`plugin-detail`)
+- [ ] Stack header actions vertically on narrow screens: `flex-col sm:flex-row`
+- [ ] Full-width action buttons on mobile: `w-full sm:w-auto`
+- [ ] Scale section padding: `p-3 sm:p-4 md:p-6`
+- [ ] Convert metadata panel to bottom drawer on mobile
+- [ ] Increase field value touch targets for copy-to-clipboard
+
+##### Charts (`plugin-charts`)
+- [ ] Set responsive chart heights: `h-48 sm:h-64 md:h-80 lg:h-96`
+- [ ] Reduce axis label count on mobile to prevent overlap
+- [ ] Enable touch-to-inspect data points (tooltip on tap)
+- [ ] Stack legend below chart on mobile: `flex-col sm:flex-row`
+
+##### Map (`plugin-map`)
+- [ ] Enable pinch-to-zoom and two-finger pan on mobile
+- [ ] Scale info popup sizing for mobile screens
+- [ ] Add mobile-friendly location search with bottom sheet
+- [ ] Ensure map controls (zoom, layer toggle) are touch-accessible
+
+##### Gantt (`plugin-gantt`)
+- [ ] Add horizontal scroll container with touch momentum
+- [ ] Scale bar heights: `h-6 sm:h-8 md:h-10`
+- [ ] Collapse task details on mobile (show name only, expand on tap)
+- [ ] Add responsive zoom levels (day view on mobile, week on tablet, month on desktop)
+
+#### P5.2 Console Pages — Responsive Layouts
+
+##### AppHeader
+- [ ] Ensure all header actions are accessible on mobile (overflow menu for hidden actions)
+- [ ] Add mobile-specific command palette trigger (prominent search icon)
+- [ ] Scale header height: `h-12 sm:h-14 md:h-16`
+- [ ] Responsive breadcrumb: show only current page on mobile, full path on desktop
+
+##### AppSidebar
+- [ ] Auto-collapse to icon-only mode on tablet, full overlay on mobile
+- [ ] Add swipe-from-edge gesture to open sidebar on mobile via `useGesture`
+- [ ] Scale menu item padding for touch: `py-2.5 sm:py-2` (larger on mobile)
+- [ ] Bottom navigation bar option for mobile (5-item tab bar)
+
+##### DashboardView (Console)
+- [ ] Stack title and metadata toggle vertically on mobile
+- [ ] Scale heading: `text-lg sm:text-xl md:text-2xl`
+- [ ] Add responsive padding: `p-3 sm:p-4 md:p-6 lg:p-8`
+- [ ] Optimize metadata panel as collapsible accordion on mobile
+
+##### RecordDetailView
+- [ ] Scale dialog width: `w-[calc(100vw-1rem)] sm:w-[calc(100vw-2rem)] md:max-w-2xl lg:max-w-4xl`
+- [ ] Stack field label and value vertically on mobile
+- [ ] Add responsive padding: `p-3 sm:p-4 md:p-6`
+- [ ] Ensure inline editing works with on-screen keyboard
+
+##### Create/Edit Dialogs
+- [ ] Full-screen modal on mobile: `h-[100dvh] sm:h-auto sm:max-h-[90vh]`
+- [ ] Sticky action buttons at bottom on mobile
+- [ ] Add swipe-to-dismiss for mobile dialogs
+
+#### P5.3 Core Component Primitives
+
+##### DataTable (`components/renderers/complex`)
+- [ ] Add outer `overflow-x-auto` wrapper with `-webkit-overflow-scrolling: touch`
+- [ ] Scale pagination controls: full-width on mobile with larger touch targets
+- [ ] Responsive column visibility system (priority-based column hiding)
+- [ ] Mobile-optimized search/filter bar: full-width, collapsible
+- [ ] Horizontal scroll indicator (shadow/gradient) on mobile
+
+##### Form Renderer (`components/renderers/form`)
+- [ ] Verify responsive column mapping works correctly for all column counts (1–4)
+- [ ] Ensure wizard/stepper variant shows 1 step at a time on mobile
+- [ ] Scale step indicators for mobile: `text-xs sm:text-sm`, smaller circles
+- [ ] Full-width submit/cancel buttons on mobile
+
+##### Navigation Components
+- [ ] Breadcrumb: truncate to current + parent on mobile with "..." overflow
+- [ ] Tab navigation: horizontal scroll with `overflow-x-auto` for many tabs
+- [ ] DropdownMenu: use bottom sheet pattern on mobile via `useIsMobile()` detection
+
+#### P5.4 Mobile Infrastructure Enhancements
+
+##### Touch & Gesture System
+- [ ] Integrate `usePullToRefresh` into all data-fetching views (Grid, List, Timeline, Calendar)
+- [ ] Add swipe-to-go-back gesture for Console navigation
+- [ ] Integrate `useTouchTarget` hook to enforce minimum 44px touch targets across all interactive elements
+- [ ] Add haptic feedback triggers for drag-and-drop completion
+
+##### Performance on Mobile Networks
+- [ ] Implement progressive image loading for all image fields and avatars
+- [ ] Add connection-aware data fetching (reduce page size on slow connections)
+- [ ] Enable service worker caching for static assets via `registerServiceWorker`
+- [ ] Add `loading="lazy"` to all below-fold images and iframes
+
+##### PWA Support
+- [ ] Integrate `MobileProvider` into Console app root with PWA configuration
+- [ ] Generate app manifest via `generatePWAManifest()` utility
+- [ ] Add app install prompt for mobile browsers
+- [ ] Implement offline indicator and cached-data fallback
+
+##### Viewport & Input Handling
+- [ ] Handle virtual keyboard resize (100dvh instead of 100vh for mobile)
+- [ ] Prevent zoom on input focus (`font-size: 16px` minimum for inputs)
+- [ ] Add viewport meta tag validation in Console HTML template
+- [ ] Support safe-area-inset for notched devices (`env(safe-area-inset-*)`)
+
+#### P5.5 Testing & Quality Assurance
+
+- [ ] Add Playwright mobile viewport tests (iPhone SE 375px, iPhone 14 390px, iPad 768px)
+- [ ] Add visual regression tests for all views at mobile breakpoints
+- [ ] Add touch interaction tests (swipe, pinch, long-press) via Playwright touch emulation
+- [ ] Verify all views pass axe-core at mobile viewport sizes
+- [ ] Add Storybook mobile viewport decorator for all component stories
+- [ ] Test on-screen keyboard interaction for all form fields
+- [ ] Performance benchmark on simulated mobile CPU (4× slowdown) and 3G network
+
+#### P5.6 Mobile-Specific Success Metrics
+
+| Metric | Target | How Measured |
+|--------|--------|--------------|
+| **Touch Target Compliance** | 100% ≥ 44px | Automated scan via `useTouchTarget` |
+| **Mobile Lighthouse Score** | ≥ 90 (Performance, Accessibility) | Lighthouse CI on mobile preset |
+| **First Contentful Paint (Mobile 3G)** | < 1.5s | Lighthouse / Web Vitals |
+| **Time to Interactive (Mobile 3G)** | < 3.5s | Lighthouse / Web Vitals |
+| **Responsive Breakpoint Coverage** | All 13+ views × 3 breakpoints | Playwright viewport tests |
+| **Mobile Gesture Coverage** | Swipe, pinch, long-press in all applicable views | E2E gesture tests |
+| **PWA Install Success** | Manifest + service worker valid | Lighthouse PWA audit |
+
+---
+
 ## 🔮 Future Vision (Deferred)
 
 > The following items are **not** in the current sprint. They will be re-evaluated once P1–P4 are substantially complete.
@@ -326,6 +514,9 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 | **WCAG AA Compliance** | Full Console pages | Full Console pages | axe-core audit |
 | **CLI Commands Working** | 11 | 11 (all verified) | `objectui doctor` |
 | **TODO/FIXME Count** | 0 files | 0 | Grep `TODO\|FIXME\|HACK` |
+| **Mobile Responsive Views** | Partial (2/13) | 13/13 (100%) | Playwright mobile tests |
+| **Mobile Lighthouse Score** | Not measured | ≥ 90 | Lighthouse CI mobile preset |
+| **Touch Target Compliance** | Not measured | 100% ≥ 44px | Automated touch target scan |
 
 ### DX Success Criteria
 - [x] New developer can `git clone` → `pnpm install` → `pnpm dev` → see Console in < 5 minutes
@@ -339,6 +530,13 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 - [x] Grid view handles 10,000+ records without jank (< 100ms interaction latency)
 - [x] Full keyboard navigation for all Console workflows (no mouse required)
 
+### Mobile UX Success Criteria
+- [ ] All 13+ views render correctly at 375px viewport (iPhone SE)
+- [ ] Touch targets ≥ 44px for all interactive elements
+- [ ] Console Lighthouse mobile score ≥ 90 (Performance + Accessibility)
+- [ ] All views support horizontal scroll or responsive stacking on mobile
+- [ ] Swipe gestures work for navigation, Kanban columns, and Calendar days
+
 ---
 
 ## ⚠️ Risk Management
@@ -352,6 +550,7 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 | **Component API inconsistency** | Audit checklist, automated prop-type validation, Storybook as source of truth |
 | **Documentation drift** | TSDoc generation from source, Storybook stories alongside code, link checker CI |
 | **Accessibility regression** | axe-core tests on full Console pages (not just primitives), WCAG AA CI check |
+| **Mobile responsiveness regression** | Playwright mobile viewport tests, Lighthouse CI mobile preset, touch target audit |
 
 ---
 

packages/components/src/renderers/complex/data-table.tsx

@@ -510,13 +510,13 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
   const showToolbar = searchable || exportable || (selectable && selectedRowIds.size > 0) || hasPendingChanges;
 
   return (
-    <div className={`flex flex-col h-full gap-4 ${className || ''}`}>
+    <div className={`flex flex-col h-full gap-2 sm:gap-4 ${className || ''}`}>
       {/* Toolbar */}
       {showToolbar && (
-        <div className="flex items-center justify-between gap-4 flex-none">
+        <div className="flex flex-col sm:flex-row items-stretch sm:items-center justify-between gap-2 sm:gap-4 flex-none">
           <div className="flex items-center gap-2 flex-1">
             {searchable && (
-              <div className="relative max-w-sm flex-1">
+              <div className="relative w-full sm:max-w-sm flex-1">
                 <Search className="absolute left-2 top-1/2 transform -translate-y-1/2 h-4 w-4 text-muted-foreground" />
                 <Input
                   placeholder="Search..."
@@ -531,7 +531,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
             )}
           </div>
 
-          <div className="flex items-center gap-2">
+          <div className="flex flex-wrap items-center gap-2">
             {hasPendingChanges && (
               <>
                 <div className="text-sm text-muted-foreground">
@@ -580,7 +580,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
       )}
 
       {/* Table */}
-      <div className="rounded-md border flex-1 min-h-0 overflow-auto relative bg-background">
+      <div className="rounded-md border flex-1 min-h-0 overflow-auto relative bg-background [-webkit-overflow-scrolling:touch]">
         <Table>
           {caption && <TableCaption>{caption}</TableCaption>}
           <TableHeader className="sticky top-0 bg-background z-10 shadow-sm">
@@ -804,7 +804,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
 
       {/* Pagination */}
       {pagination && sortedData.length > 0 && (
-        <div className="flex items-center justify-between">
+        <div className="flex flex-col sm:flex-row items-center justify-between gap-2">
           <div className="flex items-center gap-2">
             <span className="text-sm text-muted-foreground">Rows per page:</span>
             <Select

packages/plugin-calendar/src/ObjectCalendar.tsx

@@ -326,7 +326,7 @@ export const ObjectCalendar: React.FC<ObjectCalendarProps> = ({
 
   return (
     <div className={className}>
-      <div className="border rounded-lg bg-background h-[calc(100vh-200px)] min-h-[600px]">
+      <div className="border rounded-lg bg-background h-[calc(100vh-120px)] sm:h-[calc(100vh-160px)] md:h-[calc(100vh-200px)] min-h-[400px] sm:min-h-[600px]">
         <CalendarView
           events={events}
           currentDate={currentDate}

packages/plugin-dashboard/src/DashboardRenderer.tsx

@@ -56,9 +56,15 @@ export const DashboardRenderer = forwardRef<HTMLDivElement, DashboardRendererPro
     return (
       <div
         ref={ref}
-        className={cn("grid auto-rows-min", className)}
+        className={cn(
+          "grid auto-rows-min",
+          // Responsive grid: 1 column on mobile, 2 on sm, 3 on lg, 4 on xl
+          // When columns > 4, inline gridTemplateColumns style overrides these classes
+          "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+          className
+        )}
         style={{
-            gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+            ...(columns > 4 && { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }),
             gap: `${gap * 0.25}rem`
         }}
         {...props}
@@ -166,7 +172,7 @@ export const DashboardRenderer = forwardRef<HTMLDivElement, DashboardRendererPro
                         </CardHeader>
                     )}
                     <CardContent className="p-0">
-                        <div className={cn("h-full w-full", !widget.title ? "p-4" : "p-4")}>
+                        <div className={cn("h-full w-full", "p-3 sm:p-4 md:p-6")}>
                             <SchemaRenderer schema={componentSchema} />
                         </div>
                     </CardContent>

packages/plugin-detail/src/DetailView.tsx

@@ -182,8 +182,8 @@ export const DetailView: React.FC<DetailViewProps> = ({
     <TooltipProvider>
       <div className={cn('space-y-6', className)}>
         {/* Header - Airtable-inspired layout */}
-        <div className="flex items-start justify-between gap-4 pb-4 border-b">
-          <div className="flex items-start gap-3 flex-1 min-w-0">
+        <div className="flex flex-col sm:flex-row items-start justify-between gap-3 sm:gap-4 pb-4 border-b">
+          <div className="flex items-start gap-2 sm:gap-3 flex-1 min-w-0">
             {(schema.showBack ?? true) && (
               <Tooltip>
                 <TooltipTrigger asChild>
@@ -196,7 +196,7 @@ export const DetailView: React.FC<DetailViewProps> = ({
             )}
             <div className="flex-1 min-w-0">
               <div className="flex items-center gap-2">
-                <h1 className="text-2xl font-bold truncate">{schema.title || 'Details'}</h1>
+                <h1 className="text-xl sm:text-2xl font-bold truncate">{schema.title || 'Details'}</h1>
                 <Tooltip>
                   <TooltipTrigger asChild>
                     <Button 
@@ -227,7 +227,7 @@ export const DetailView: React.FC<DetailViewProps> = ({
             </div>
           </div>
 
-          <div className="flex items-center gap-1.5 shrink-0">
+          <div className="flex flex-wrap items-center gap-1.5 shrink-0">
             {schema.actions?.map((action, index) => (
               <SchemaRenderer key={index} schema={action} data={data} />
             ))}

packages/plugin-form/src/ObjectForm.tsx

@@ -511,7 +511,7 @@ const SimpleObjectForm: React.FC<ObjectFormProps> = ({
   // Render error state
   if (error) {
     return (
-      <div className="p-4 border border-red-300 bg-red-50 rounded-md">
+      <div className="p-3 sm:p-4 border border-red-300 bg-red-50 rounded-md">
         <h3 className="text-red-800 font-semibold">Error loading form</h3>
         <p className="text-red-600 text-sm mt-1">{error.message}</p>
       </div>
@@ -521,7 +521,7 @@ const SimpleObjectForm: React.FC<ObjectFormProps> = ({
   // Render loading state
   if (loading) {
     return (
-      <div className="p-8 text-center">
+      <div className="p-4 sm:p-8 text-center">
         <div className="inline-block animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900"></div>
         <p className="mt-2 text-sm text-gray-600">Loading form...</p>
       </div>