@burdenoff/microfe-movethewheels 2026.703.2 → 2026.703.4

package/src/movethewheels/components/DataTable.tsx

@@ -66,12 +66,25 @@ interface DataTableProps<T> {
   emptyAction?: ReactNode;
   className?: string;
   getRowId?: (row: T) => string;
+  /**
+   * Controlled (server-side) pagination. When `onPageChange` is provided the
+   * table stops slicing client-side — `data` is treated as the current page —
+   * and the pager Prev/Next/First/Last call the callbacks instead. Provide
+   * either `totalItems` (a real grand total is known) or `hasNextPage`
+   * (unknown total — Next is enabled while the last fetch returned a full page).
+   */
+  pageIndex?: number;
+  onPageChange?: (pageIndex: number) => void;
+  onPageSizeChange?: (pageSize: number) => void;
+  totalItems?: number;
+  hasNextPage?: boolean;
 }
 
 type SortDirection = 'asc' | 'desc' | null;
 
 /**
- * DataTable - A reusable data table component with sorting, search, and pagination
+ * DataTable - A reusable data table component with sorting, search, and both
+ * client-side and controlled (server-side) pagination.
  */
 export function DataTable<T extends object>({
   columns,
@@ -81,8 +94,8 @@ export function DataTable<T extends object>({
   searchPlaceholder = 'Search...',
   searchFields,
   pagination = true,
-  pageSize: initialPageSize = 10,
-  pageSizeOptions = [5, 10, 20, 50],
+  pageSize: pageSizeProp = 10,
+  pageSizeOptions = [10, 25, 50, 100],
   onRowClick,
   rowClassName,
   emptyMessage = 'No data found',
@@ -92,14 +105,25 @@ export function DataTable<T extends object>({
   emptyAction,
   className,
   getRowId,
+  pageIndex,
+  onPageChange,
+  onPageSizeChange,
+  totalItems,
+  hasNextPage,
 }: DataTableProps<T>) {
+  const isControlled = typeof onPageChange === 'function';
+  const controlledPageIndex = pageIndex ?? 0;
+
   const [searchQuery, setSearchQuery] = useState('');
   const [sortColumn, setSortColumn] = useState<string | null>(null);
   const [sortDirection, setSortDirection] = useState<SortDirection>(null);
   const [currentPage, setCurrentPage] = useState(1);
-  const [pageSize, setPageSize] = useState(initialPageSize);
+  const [internalPageSize, setInternalPageSize] = useState(pageSizeProp);
+
+  const activePageSize = isControlled ? pageSizeProp : internalPageSize;
 
-  // Filter data based on search
+  // Filter data based on search (client-side; in controlled mode this scopes to
+  // the current page only, which is expected for server-paginated lists).
   const filteredData = useMemo(() => {
     if (!searchQuery || !searchFields || searchFields.length === 0) {
       return data;
@@ -147,15 +171,20 @@ export function DataTable<T extends object>({
     });
   }, [filteredData, sortColumn, sortDirection, columns]);
 
-  // Paginate data
+  // Paginate data — controlled mode never slices (server already did).
   const paginatedData = useMemo(() => {
-    if (!pagination) return sortedData;
+    if (!pagination || isControlled) return sortedData;
 
-    const start = (currentPage - 1) * pageSize;
-    return sortedData.slice(start, start + pageSize);
-  }, [sortedData, currentPage, pageSize, pagination]);
+    const start = (currentPage - 1) * internalPageSize;
+    return sortedData.slice(start, start + internalPageSize);
+  }, [sortedData, currentPage, internalPageSize, pagination, isControlled]);
 
-  const totalPages = Math.ceil(sortedData.length / pageSize);
+  const totalPagesClient = Math.max(1, Math.ceil(sortedData.length / internalPageSize));
+
+  const hasTotal = typeof totalItems === 'number';
+  const totalPagesControlled = hasTotal
+    ? Math.max(1, Math.ceil(totalItems / activePageSize))
+    : undefined;
 
   // Handle sort
   const handleSort = (columnId: string) => {
@@ -206,7 +235,8 @@ export function DataTable<T extends object>({
             <Skeleton className="h-10 w-64" />
           </div>
         )}
-        <div className="rounded-card border border-border-seam bg-bg-surface shadow-elevation-1">
+        {/* Desktop skeleton */}
+        <div className="hidden md:block rounded-card border border-border-seam bg-bg-surface shadow-elevation-1">
           <Table>
             <TableHeader>
               <TableRow>
@@ -230,10 +260,49 @@ export function DataTable<T extends object>({
             </TableBody>
           </Table>
         </div>
+        {/* Mobile skeleton */}
+        <div className="md:hidden space-y-3">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div
+              key={i}
+              className="rounded-card border border-border-seam bg-bg-surface p-4 shadow-elevation-1"
+            >
+              <Skeleton className="h-4 w-2/3 mb-2 motion-safe:animate-vc-shimmer" />
+              <Skeleton className="h-4 w-1/2 motion-safe:animate-vc-shimmer" />
+            </div>
+          ))}
+        </div>
       </div>
     );
   }
 
+  const isEmpty = paginatedData.length === 0;
+
+  const renderEmpty = () =>
+    emptyIllustration ? (
+      searchQuery ? (
+        <IllustratedEmptyState
+          illustration="empty-search"
+          title="No matches"
+          description={`Nothing matches “${searchQuery}”. Try a different search.`}
+        />
+      ) : (
+        <IllustratedEmptyState
+          illustration={emptyIllustration}
+          title={emptyTitle ?? emptyMessage}
+          description={emptyDescription}
+          action={emptyAction}
+        />
+      )
+    ) : (
+      <p className="text-text-secondary">{emptyMessage}</p>
+    );
+
+  // Pagination footer visibility
+  const showFooter =
+    pagination &&
+    (isControlled ? sortedData.length > 0 || controlledPageIndex > 0 : sortedData.length > 0);
+
   return (
     <div className={cn('space-y-4', className)}>
       {/* Search */}
@@ -254,8 +323,8 @@ export function DataTable<T extends object>({
         </div>
       )}
 
-      {/* Table */}
-      <div className="overflow-x-auto rounded-card border border-border-seam bg-bg-surface shadow-elevation-1">
+      {/* Table (desktop / tablet) */}
+      <div className="hidden md:block overflow-x-auto rounded-card border border-border-seam bg-bg-surface shadow-elevation-1">
         <Table>
           <TableHeader>
             <TableRow>
@@ -277,27 +346,10 @@ export function DataTable<T extends object>({
             </TableRow>
           </TableHeader>
           <TableBody>
-            {paginatedData.length === 0 ? (
+            {isEmpty ? (
               <TableRow>
                 <TableCell colSpan={columns.length} className="py-8 text-center">
-                  {emptyIllustration ? (
-                    searchQuery ? (
-                      <IllustratedEmptyState
-                        illustration="empty-search"
-                        title="No matches"
-                        description={`Nothing matches “${searchQuery}”. Try a different search.`}
-                      />
-                    ) : (
-                      <IllustratedEmptyState
-                        illustration={emptyIllustration}
-                        title={emptyTitle ?? emptyMessage}
-                        description={emptyDescription}
-                        action={emptyAction}
-                      />
-                    )
-                  ) : (
-                    <p className="text-text-secondary">{emptyMessage}</p>
-                  )}
+                  {renderEmpty()}
                 </TableCell>
               </TableRow>
             ) : (
@@ -325,19 +377,78 @@ export function DataTable<T extends object>({
         </Table>
       </div>
 
+      {/* Card list (mobile) */}
+      <div className="md:hidden space-y-3">
+        {isEmpty ? (
+          <div className="rounded-card border border-border-seam bg-bg-surface p-6 text-center shadow-elevation-1">
+            {renderEmpty()}
+          </div>
+        ) : (
+          paginatedData.map((row, index) => {
+            const rowId = getRowId ? getRowId(row) : index;
+            const rowClasses =
+              typeof rowClassName === 'function' ? rowClassName(row) : rowClassName;
+
+            return (
+              <div
+                key={rowId}
+                role={onRowClick ? 'button' : undefined}
+                tabIndex={onRowClick ? 0 : undefined}
+                className={cn(
+                  'rounded-card border border-border-seam bg-bg-surface p-4 shadow-elevation-1',
+                  onRowClick && 'cursor-pointer hover:bg-bg-sunken/50',
+                  rowClasses
+                )}
+                onClick={() => onRowClick?.(row)}
+                onKeyDown={(e) => {
+                  if (onRowClick && (e.key === 'Enter' || e.key === ' ')) {
+                    e.preventDefault();
+                    onRowClick(row);
+                  }
+                }}
+              >
+                <dl className="space-y-2">
+                  {columns.map((column) => (
+                    <div key={column.id} className="flex items-start justify-between gap-3">
+                      <dt className="text-xs font-medium text-text-secondary shrink-0">
+                        {column.header}
+                      </dt>
+                      <dd className="text-sm text-right min-w-0">{getCellValue(row, column)}</dd>
+                    </div>
+                  ))}
+                </dl>
+              </div>
+            );
+          })
+        )}
+      </div>
+
       {/* Pagination */}
-      {pagination && sortedData.length > 0 && (
-        <div className="flex items-center justify-between">
-          <div className="flex items-center gap-2 text-sm text-text-secondary">
-            <span>
-              Showing {(currentPage - 1) * pageSize + 1} to{' '}
-              {Math.min(currentPage * pageSize, sortedData.length)} of {sortedData.length}
-            </span>
+      {showFooter && (
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <div className="flex flex-wrap items-center gap-2 text-sm text-text-secondary">
+            {isControlled ? (
+              <span>
+                Showing {sortedData.length === 0 ? 0 : controlledPageIndex * activePageSize + 1} to{' '}
+                {controlledPageIndex * activePageSize + sortedData.length}
+                {hasTotal ? ` of ${totalItems}` : ''}
+              </span>
+            ) : (
+              <span>
+                Showing {(currentPage - 1) * internalPageSize + 1} to{' '}
+                {Math.min(currentPage * internalPageSize, sortedData.length)} of {sortedData.length}
+              </span>
+            )}
             <Select
-              value={String(pageSize)}
+              value={String(activePageSize)}
               onValueChange={(value) => {
-                setPageSize(Number(value));
-                setCurrentPage(1);
+                const next = Number(value);
+                if (isControlled) {
+                  onPageSizeChange?.(next);
+                } else {
+                  setInternalPageSize(next);
+                  setCurrentPage(1);
+                }
               }}
             >
               <SelectTrigger className="w-[70px] h-8">
@@ -354,47 +465,104 @@ export function DataTable<T extends object>({
             <span>per page</span>
           </div>
 
-          <div className="flex items-center gap-1">
-            <Button
-              variant="outline"
-              size="icon"
-              className="h-8 w-8"
-              onClick={() => setCurrentPage(1)}
-              disabled={currentPage === 1}
-            >
-              <ChevronsLeft className="h-4 w-4" />
-            </Button>
-            <Button
-              variant="outline"
-              size="icon"
-              className="h-8 w-8"
-              onClick={() => setCurrentPage((p) => Math.max(1, p - 1))}
-              disabled={currentPage === 1}
-            >
-              <ChevronLeft className="h-4 w-4" />
-            </Button>
-            <span className="px-3 text-sm">
-              Page {currentPage} of {totalPages}
-            </span>
-            <Button
-              variant="outline"
-              size="icon"
-              className="h-8 w-8"
-              onClick={() => setCurrentPage((p) => Math.min(totalPages, p + 1))}
-              disabled={currentPage === totalPages}
-            >
-              <ChevronRight className="h-4 w-4" />
-            </Button>
-            <Button
-              variant="outline"
-              size="icon"
-              className="h-8 w-8"
-              onClick={() => setCurrentPage(totalPages)}
-              disabled={currentPage === totalPages}
-            >
-              <ChevronsRight className="h-4 w-4" />
-            </Button>
-          </div>
+          {isControlled ? (
+            <div className="flex items-center gap-1">
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8"
+                aria-label="First page"
+                onClick={() => onPageChange?.(0)}
+                disabled={controlledPageIndex === 0}
+              >
+                <ChevronsLeft className="h-4 w-4" />
+              </Button>
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8"
+                aria-label="Previous page"
+                onClick={() => onPageChange?.(Math.max(0, controlledPageIndex - 1))}
+                disabled={controlledPageIndex === 0}
+              >
+                <ChevronLeft className="h-4 w-4" />
+              </Button>
+              <span className="px-3 text-sm">
+                Page {controlledPageIndex + 1}
+                {hasTotal ? ` of ${totalPagesControlled}` : ''}
+              </span>
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8"
+                aria-label="Next page"
+                onClick={() => onPageChange?.(controlledPageIndex + 1)}
+                disabled={
+                  hasTotal ? controlledPageIndex + 1 >= (totalPagesControlled ?? 1) : !hasNextPage
+                }
+              >
+                <ChevronRight className="h-4 w-4" />
+              </Button>
+              {hasTotal && (
+                <Button
+                  variant="outline"
+                  size="icon"
+                  className="h-8 w-8"
+                  aria-label="Last page"
+                  onClick={() => onPageChange?.((totalPagesControlled ?? 1) - 1)}
+                  disabled={controlledPageIndex + 1 >= (totalPagesControlled ?? 1)}
+                >
+                  <ChevronsRight className="h-4 w-4" />
+                </Button>
+              )}
+            </div>
+          ) : (
+            <div className="flex items-center gap-1">
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8"
+                aria-label="First page"
+                onClick={() => setCurrentPage(1)}
+                disabled={currentPage === 1}
+              >
+                <ChevronsLeft className="h-4 w-4" />
+              </Button>
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8"
+                aria-label="Previous page"
+                onClick={() => setCurrentPage((p) => Math.max(1, p - 1))}
+                disabled={currentPage === 1}
+              >
+                <ChevronLeft className="h-4 w-4" />
+              </Button>
+              <span className="px-3 text-sm">
+                Page {currentPage} of {totalPagesClient}
+              </span>
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8"
+                aria-label="Next page"
+                onClick={() => setCurrentPage((p) => Math.min(totalPagesClient, p + 1))}
+                disabled={currentPage === totalPagesClient}
+              >
+                <ChevronRight className="h-4 w-4" />
+              </Button>
+              <Button
+                variant="outline"
+                size="icon"
+                className="h-8 w-8"
+                aria-label="Last page"
+                onClick={() => setCurrentPage(totalPagesClient)}
+                disabled={currentPage === totalPagesClient}
+              >
+                <ChevronsRight className="h-4 w-4" />
+              </Button>
+            </div>
+          )}
         </div>
       )}
     </div>

package/src/movethewheels/components/DocumentsCard.tsx

@@ -0,0 +1,102 @@
+/**
+ * DocumentsCard — reuse of the platform Files module (wspace-files-svc).
+ *
+ * Lists the real files tagged for a MoveTheWheels entity (vehicle / driver /
+ * order) and deep-links to the Files module for uploading and managing them.
+ * MoveTheWheels does not store documents itself — this is honest cross-module
+ * reuse. When there are no files (or the query errors), we show an honest empty
+ * state with a working link to Files rather than any fabricated rows.
+ */
+
+import { FileText, ExternalLink, Download, Upload } from 'lucide-react';
+import { Card, CardContent, CardHeader, CardTitle, Button } from './ui';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { useEntityDocuments, type EntityDocumentType } from '../hooks/useEntityDocuments';
+import { formatDate } from '../utils/formatters';
+
+interface DocumentsCardProps {
+  entityType: EntityDocumentType;
+  entityId: string;
+}
+
+function formatFileSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '—';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(value >= 10 || unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+export function DocumentsCard({ entityType, entityId }: DocumentsCardProps) {
+  const { navigate } = useMoveTheWheels();
+  const { documents, isLoading } = useEntityDocuments(entityType, entityId);
+
+  // Deep-link to the host Files module (mounted at /files in the app shell).
+  // This is a host-absolute path, so it uses the raw navigate — not the
+  // MoveTheWheels base-path-joined one.
+  const openFiles = () => navigate('/files/browse');
+
+  return (
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between">
+        <CardTitle className="flex items-center gap-2">
+          <FileText size={18} /> Documents
+        </CardTitle>
+        <Button variant="outline" size="sm" onClick={openFiles}>
+          <Upload size={14} /> Add / Manage
+        </Button>
+      </CardHeader>
+      <CardContent>
+        {isLoading ? (
+          <p className="text-text-secondary text-center py-4">Loading documents…</p>
+        ) : documents.length > 0 ? (
+          <div className="space-y-3">
+            {documents.map((doc) => (
+              <div
+                key={doc.id}
+                className="flex items-center justify-between gap-3 p-3 border rounded-lg"
+              >
+                <div className="min-w-0">
+                  <p className="font-medium truncate">{doc.name}</p>
+                  <p className="text-sm text-text-secondary">
+                    {formatFileSize(doc.size)} · {formatDate(doc.createdAt, 'relative')}
+                  </p>
+                </div>
+                {doc.downloadUrl ? (
+                  <a
+                    href={doc.downloadUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="shrink-0 inline-flex items-center gap-1 text-sm text-primary hover:underline"
+                  >
+                    <Download size={14} /> Open
+                  </a>
+                ) : (
+                  <Button variant="ghost" size="sm" onClick={openFiles}>
+                    <ExternalLink size={14} /> View
+                  </Button>
+                )}
+              </div>
+            ))}
+          </div>
+        ) : (
+          <div className="text-center py-6">
+            <FileText size={32} className="mx-auto mb-2 text-text-secondary opacity-50" />
+            <p className="text-text-secondary">No documents yet</p>
+            <button
+              type="button"
+              onClick={openFiles}
+              className="mt-1 text-sm text-primary hover:underline"
+            >
+              Add them in Files
+            </button>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/movethewheels/components/Notice.tsx

@@ -0,0 +1,61 @@
+/**
+ * Notice — inline success / info feedback banner.
+ *
+ * The MoveTheWheels MFE does not mount its own sonner Toaster (mounting a second
+ * Toaster inside a host shell causes duplicate toasts), so action feedback is
+ * shown inline via this banner. Renders nothing when there is no message, so it
+ * can be dropped in unconditionally. Uses semantic status tokens so it themes
+ * correctly. Pair it with `useNotice` for auto-dismiss behaviour.
+ */
+
+import { useCallback, useRef, useState } from 'react';
+import { CheckCircle, Info } from 'lucide-react';
+
+type NoticeVariant = 'success' | 'info';
+
+interface NoticeProps {
+  message?: string | null;
+  variant?: NoticeVariant;
+}
+
+export function Notice({ message, variant = 'success' }: NoticeProps) {
+  if (!message) return null;
+  const isSuccess = variant === 'success';
+  return (
+    <div
+      role="status"
+      className={`flex items-start gap-2 rounded-lg border px-4 py-3 text-sm ${
+        isSuccess
+          ? 'border-status-success-border bg-status-success-bg-subtle text-status-success-text'
+          : 'border-status-info-border bg-status-info-bg-subtle text-status-info-text'
+      }`}
+    >
+      {isSuccess ? (
+        <CheckCircle size={18} className="mt-0.5 shrink-0" />
+      ) : (
+        <Info size={18} className="mt-0.5 shrink-0" />
+      )}
+      <span>{message}</span>
+    </div>
+  );
+}
+
+/**
+ * useNotice — transient success/info message that auto-clears after a delay.
+ * Returns the current message plus a `notify` setter, mirroring a toast API.
+ */
+export function useNotice(autoDismissMs = 4000) {
+  const [message, setMessage] = useState<string | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const notify = useCallback(
+    (next: string) => {
+      setMessage(next);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => setMessage(null), autoDismissMs);
+    },
+    [autoDismissMs]
+  );
+
+  return { message, notify };
+}

package/src/movethewheels/components/index.ts

@@ -24,3 +24,10 @@ export {
 
 // Table components
 export { DataTable, type Column } from './DataTable';
+
+// Feedback components
+export { FormError } from './FormError';
+export { Notice, useNotice } from './Notice';
+
+// Documents (reuse of wspace-files-svc)
+export { DocumentsCard } from './DocumentsCard';

package/src/movethewheels/hooks/index.ts

@@ -41,6 +41,8 @@ export {
   useOrderAnalytics,
   useFleetAnalytics,
   usePerformanceAnalytics,
+  useFinanceMetrics,
+  type FinanceMetrics,
 } from './useAnalytics';
 
 // Tracking
@@ -65,3 +67,10 @@ export { useImportExport } from './useImportExport';
 
 // Module settings
 export { useModuleSettings } from './useSettings';
+
+// Entity documents (reuse of wspace-files-svc)
+export {
+  useEntityDocuments,
+  type EntityDocument,
+  type EntityDocumentType,
+} from './useEntityDocuments';