feat: complete P1/P2 — add useDataRefresh hook, onMutation for ObjectView/Kanban/Calendar

- P1: Create useDataRefresh() hook in @object-ui/react with 7 tests
- P2: Add onMutation subscription to plugin-view ObjectView
- P2: Add onMutation subscription to plugin-kanban ObjectKanban
- P2: Add onMutation subscription to plugin-calendar ObjectCalendar
- Updated CHANGELOG with complete scope

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/objectui/sessions/d269c01c-4c5b-4b90-8d2e-1427e459078f

Author: Copilot

CHANGELOG.md

@@ -13,10 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Standardized List Refresh After Mutation (P0/P1/P2)** (`@object-ui/types`, `@object-ui/plugin-list`, `@object-ui/plugin-view`, `@object-ui/core`, `apps/console`): Resolved a platform-level architectural deficiency where list views did not refresh after create/update/delete mutations. The fix spans three phases:
+- **Standardized List Refresh After Mutation (P0/P1/P2)** (`@object-ui/types`, `@object-ui/plugin-list`, `@object-ui/plugin-view`, `@object-ui/plugin-kanban`, `@object-ui/plugin-calendar`, `@object-ui/react`, `@object-ui/core`, `apps/console`): Resolved a platform-level architectural deficiency where list views did not refresh after create/update/delete mutations. The fix spans three phases:
   - **P0 — refreshTrigger Prop**: Added `refreshTrigger?: number` to `ListViewSchema`. When a parent component (e.g., `ObjectView`) increments this value after a mutation, `ListView` automatically re-fetches data. The plugin-view's `ObjectView.renderContent()` now passes its internal `refreshKey` as both a direct callback prop and embedded in the schema's `refreshTrigger`. The console `ObjectView` combines both its own and the plugin's refresh signals for full propagation.
-  - **P1 — Imperative `refresh()` API**: `ListView` is now wrapped with `React.forwardRef` and exposes a `refresh()` method via `useImperativeHandle`. Parents can trigger a re-fetch programmatically via `listRef.current?.refresh()`. Exported `ListViewHandle` type from `@object-ui/plugin-list`.
-  - **P2 — DataSource Mutation Event Bus**: Added `MutationEvent` interface and optional `onMutation(callback): unsubscribe` method to the `DataSource` interface. When a DataSource implements this, `ListView` auto-subscribes and refreshes on matching resource mutations. `ValueDataSource` now emits mutation events on create/update/delete. Includes 15 new tests covering all three phases.
+  - **P1 — Imperative `refresh()` API + `useDataRefresh` hook**: `ListView` is now wrapped with `React.forwardRef` and exposes a `refresh()` method via `useImperativeHandle`. Parents can trigger a re-fetch programmatically via `listRef.current?.refresh()`. Exported `ListViewHandle` type from `@object-ui/plugin-list`. Added reusable `useDataRefresh(dataSource, objectName)` hook to `@object-ui/react` that encapsulates the refreshKey state + `onMutation` subscription pattern for any view component.
+  - **P2 — DataSource Mutation Event Bus**: Added `MutationEvent` interface and optional `onMutation(callback): unsubscribe` method to the `DataSource` interface. All data-bound views now auto-subscribe to mutation events when the DataSource implements this: `ListView`, `ObjectView` (plugin-view), `ObjectKanban` (plugin-kanban), and `ObjectCalendar` (plugin-calendar). `ValueDataSource` emits mutation events on create/update/delete. Includes 22 new tests covering all three phases.
 
 - **Unified i18n Plugin Loading & Translation Injection** (`examples/crm`, `apps/console`): Unified the i18n loading mechanism so that both server and MSW/mock environments use the same translation pipeline. CRM's `objectstack.config.ts` now declares its translations via `i18n: { namespace: 'crm', translations: crmLocales }`. The shared config (`objectstack.shared.ts`) merges i18n bundles from all composed stacks. `createKernel` registers an i18n kernel service from the config bundles and auto-generates the `/api/v1/i18n/translations/:lang` MSW handler, returning translations in the standard `{ data: { locale, translations } }` spec envelope. Removed all manually-maintained i18n custom handlers and duplicate `loadAppLocale` functions from `browser.ts` and `server.ts`. The broker shim now supports `i18n.getTranslations` for server-side dispatch.
 

packages/plugin-calendar/src/ObjectCalendar.tsx

@@ -168,6 +168,19 @@ export const ObjectCalendar: React.FC<ObjectCalendarProps> = ({
   const [view, setView] = useState<'month' | 'week' | 'day'>('month');
   const [refreshKey, setRefreshKey] = useState(0);
 
+  // P2: Auto-subscribe to DataSource mutation events (standalone mode only).
+  // When rendered as a child of ObjectView with external data, parent handles refresh.
+  useEffect(() => {
+    if (hasExternalData) return; // Parent handles refresh
+    if (!dataSource?.onMutation || !schema.objectName) return;
+    const unsub = dataSource.onMutation((event: any) => {
+      if (event.resource === schema.objectName) {
+        setRefreshKey(k => k + 1);
+      }
+    });
+    return unsub;
+  }, [dataSource, schema.objectName, hasExternalData]);
+
   const handlePullRefresh = useCallback(async () => {
     setRefreshKey(k => k + 1);
   }, []);

packages/plugin-kanban/src/ObjectKanban.tsx

@@ -46,10 +46,24 @@ export const ObjectKanban: React.FC<ObjectKanbanProps> = ({
   // loading state
   const [loading, setLoading] = useState(hasExternalData ? (externalLoading ?? false) : false);
   const [error, setError] = useState<Error | null>(null);
+  const [refreshKey, setRefreshKey] = useState(0);
 
   // Resolve bound data if 'bind' property exists
   const boundData = useDataScope(schema.bind);
 
+  // P2: Auto-subscribe to DataSource mutation events (standalone mode only).
+  // When rendered as a child of ListView, data is managed externally and this is skipped.
+  useEffect(() => {
+    if (hasExternalData) return; // Parent handles refresh
+    if (!dataSource?.onMutation || !schema.objectName) return;
+    const unsub = dataSource.onMutation((event: any) => {
+      if (event.resource === schema.objectName) {
+        setRefreshKey(k => k + 1);
+      }
+    });
+    return unsub;
+  }, [dataSource, schema.objectName, hasExternalData]);
+
   // Sync external data changes from parent (e.g. ListView re-fetches after filter change)
   useEffect(() => {
     if (hasExternalData && externalLoading !== undefined) {
@@ -109,7 +123,7 @@ export const ObjectKanban: React.FC<ObjectKanbanProps> = ({
         fetchData();
     }
     return () => { isMounted = false; };
-  }, [schema.objectName, dataSource, boundData, schema.data, schema.filter, hasExternalData, objectDef]);
+  }, [schema.objectName, dataSource, boundData, schema.data, schema.filter, hasExternalData, objectDef, refreshKey]);
 
   // Determine which data to use: external -> bound -> inline -> fetched
   const rawData = (hasExternalData ? externalData : undefined) || boundData || schema.data || fetchedData;

packages/plugin-view/src/ObjectView.tsx

@@ -224,6 +224,20 @@ export const ObjectView: React.FC<ObjectViewProps> = ({
   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.
+  useEffect(() => {
+    if (!dataSource?.onMutation || !schema.objectName) return;
+    const unsub = dataSource.onMutation((event: any) => {
+      if (event.resource === schema.objectName) {
+        setRefreshKey(prev => prev + 1);
+      }
+    });
+    return unsub;
+  }, [dataSource, schema.objectName]);
+
   // Data fetching state for non-grid views
   const [data, setData] = useState<any[]>([]);
   const [loading, setLoading] = useState(false);

packages/react/src/hooks/__tests__/useDataRefresh.test.ts

@@ -0,0 +1,115 @@
+/**
+ * ObjectUI — useDataRefresh Tests
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * Tests for the reusable data-refresh hook (P1/P2).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useDataRefresh } from '../useDataRefresh';
+
+describe('useDataRefresh', () => {
+  it('should return refreshKey=0 and a refresh function', () => {
+    const { result } = renderHook(() => useDataRefresh(undefined, undefined));
+
+    expect(result.current.refreshKey).toBe(0);
+    expect(typeof result.current.refresh).toBe('function');
+  });
+
+  it('should increment refreshKey when refresh() is called', () => {
+    const { result } = renderHook(() => useDataRefresh(undefined, 'contacts'));
+
+    act(() => {
+      result.current.refresh();
+    });
+
+    expect(result.current.refreshKey).toBe(1);
+
+    act(() => {
+      result.current.refresh();
+    });
+
+    expect(result.current.refreshKey).toBe(2);
+  });
+
+  it('should auto-subscribe to DataSource.onMutation() when available', () => {
+    let listener: ((event: any) => void) | null = null;
+    const unsub = vi.fn();
+    const ds: any = {
+      onMutation: vi.fn((cb: any) => {
+        listener = cb;
+        return unsub;
+      }),
+    };
+
+    const { result } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    expect(ds.onMutation).toHaveBeenCalledOnce();
+
+    // Simulate a mutation on the same resource
+    act(() => {
+      listener?.({ type: 'create', resource: 'contacts' });
+    });
+
+    expect(result.current.refreshKey).toBe(1);
+  });
+
+  it('should NOT increment refreshKey for mutations on a different resource', () => {
+    let listener: ((event: any) => void) | null = null;
+    const ds: any = {
+      onMutation: vi.fn((cb: any) => {
+        listener = cb;
+        return vi.fn();
+      }),
+    };
+
+    const { result } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    act(() => {
+      listener?.({ type: 'create', resource: 'accounts' });
+    });
+
+    expect(result.current.refreshKey).toBe(0);
+  });
+
+  it('should unsubscribe on unmount', () => {
+    const unsub = vi.fn();
+    const ds: any = {
+      onMutation: vi.fn(() => unsub),
+    };
+
+    const { unmount } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    expect(unsub).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(unsub).toHaveBeenCalledOnce();
+  });
+
+  it('should work without onMutation (backward compatible)', () => {
+    const ds: any = {
+      find: vi.fn(),
+    };
+
+    const { result } = renderHook(() => useDataRefresh(ds, 'contacts'));
+
+    expect(result.current.refreshKey).toBe(0);
+    // Should not throw
+    act(() => {
+      result.current.refresh();
+    });
+    expect(result.current.refreshKey).toBe(1);
+  });
+
+  it('should skip subscription when objectName is undefined', () => {
+    const ds: any = {
+      onMutation: vi.fn(() => vi.fn()),
+    };
+
+    renderHook(() => useDataRefresh(ds, undefined));
+
+    expect(ds.onMutation).not.toHaveBeenCalled();
+  });
+});

packages/react/src/hooks/index.ts

@@ -33,3 +33,4 @@ export * from './useSchemaPersistence';
 export * from './useGlobalUndo';
 export * from './useDebugMode';
 export * from './useActionEngine';
+export * from './useDataRefresh';

packages/react/src/hooks/useDataRefresh.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+import { useState, useCallback, useEffect } from 'react';
+import type { DataSource } from '@object-ui/types';
+
+/**
+ * Reusable hook that encapsulates the data-refresh pattern:
+ *  1. A numeric `refreshKey` that triggers React effect re-runs when incremented.
+ *  2. An imperative `refresh()` function to trigger a re-fetch on demand.
+ *  3. Auto-subscription to `DataSource.onMutation()` — if the DataSource
+ *     implements the optional mutation event bus, the hook auto-refreshes
+ *     whenever a mutation occurs on the matching `objectName`.
+ *
+ * @param dataSource - The DataSource instance (may be undefined during initial render)
+ * @param objectName - The resource/object name to watch for mutations
+ * @returns `{ refreshKey, refresh }` — include `refreshKey` in your effect deps
+ *
+ * @example
+ * ```tsx
+ * const { refreshKey, refresh } = useDataRefresh(dataSource, schema.objectName);
+ *
+ * useEffect(() => {
+ *   dataSource.find(objectName, params).then(setData);
+ * }, [objectName, refreshKey]);
+ *
+ * // Or trigger manually:
+ * <button onClick={refresh}>Refresh</button>
+ * ```
+ */
+export function useDataRefresh(
+  dataSource: DataSource | undefined,
+  objectName: string | undefined,
+): { refreshKey: number; refresh: () => void } {
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  const refresh = useCallback(() => {
+    setRefreshKey(k => k + 1);
+  }, []);
+
+  // Auto-subscribe to DataSource mutation events
+  useEffect(() => {
+    if (!dataSource?.onMutation || !objectName) return;
+    const unsub = dataSource.onMutation((event) => {
+      if (event.resource === objectName) {
+        setRefreshKey(k => k + 1);
+      }
+    });
+    return unsub;
+  }, [dataSource, objectName]);
+
+  return { refreshKey, refresh };
+}