feat: standardize list refresh after mutation (P0/P1/P2)

P0: Add refreshTrigger prop to ListViewSchema, wire it through
    ObjectView renderListView → ListView data fetch effect.
P1: ListView now exposes imperative refresh() via forwardRef.
P2: Add MutationEvent type + onMutation() subscriber to DataSource,
    implement in ValueDataSource, auto-subscribe in ListView.

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/objectui/sessions/3c0631ac-e239-4237-bce5-9d8dad44cf99

Author: Copilot

apps/console/src/components/ObjectView.tsx

@@ -532,8 +532,10 @@ export function ObjectView({ dataSource, objects, onEdit }: any) {
     }, [drawerRecordId]);
 
     // Render multi-view content via ListView plugin (for kanban, calendar, etc.)
-    const renderListView = useCallback(({ schema: listSchema, dataSource: ds, onEdit: editHandler, className }: any) => {
-        const key = `${objectName}-${activeView.id}-${refreshKey}`;
+    const renderListView = useCallback(({ schema: listSchema, dataSource: ds, onEdit: editHandler, className, refreshKey: pluginRefreshKey }: any) => {
+        // Combine local refreshKey with the plugin ObjectView's refreshKey for full propagation
+        const combinedRefreshKey = refreshKey + (pluginRefreshKey || 0);
+        const key = `${objectName}-${activeView.id}-${combinedRefreshKey}`;
         const viewDef = activeView;
 
         // Warn in dev mode if flat properties are used instead of nested spec format

packages/core/src/adapters/ValueDataSource.ts

@@ -11,6 +11,7 @@
 
 import type {
   DataSource,
+  MutationEvent,
   QueryParams,
   QueryResult,
   AggregateParams,
@@ -228,13 +229,21 @@ function selectFields<T>(record: T, fields?: string[]): T {
 export class ValueDataSource<T = any> implements DataSource<T> {
   private items: T[];
   private idField: string | undefined;
+  private mutationListeners = new Set<(event: MutationEvent<T>) => void>();
 
   constructor(config: ValueDataSourceConfig<T>) {
     // Deep clone to prevent external mutation
     this.items = JSON.parse(JSON.stringify(config.items));
     this.idField = config.idField;
   }
 
+  /** Notify all mutation subscribers */
+  private emitMutation(event: MutationEvent<T>): void {
+    for (const listener of this.mutationListeners) {
+      try { listener(event); } catch { /* swallow listener errors */ }
+    }
+  }
+
   // -----------------------------------------------------------------------
   // DataSource interface
   // -----------------------------------------------------------------------
@@ -308,6 +317,7 @@ export class ValueDataSource<T = any> implements DataSource<T> {
       (record as any)[field] = `auto_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     }
     this.items.push(record);
+    this.emitMutation({ type: 'create', resource: _resource, record: { ...record } });
     return { ...record };
   }
 
@@ -323,6 +333,7 @@ export class ValueDataSource<T = any> implements DataSource<T> {
       throw new Error(`ValueDataSource: Record with id "${id}" not found`);
     }
     this.items[index] = { ...this.items[index], ...data };
+    this.emitMutation({ type: 'update', resource: _resource, id, record: { ...this.items[index] } });
     return { ...this.items[index] };
   }
 
@@ -332,6 +343,7 @@ export class ValueDataSource<T = any> implements DataSource<T> {
     );
     if (index === -1) return false;
     this.items.splice(index, 1);
+    this.emitMutation({ type: 'delete', resource: _resource, id });
     return true;
   }
 
@@ -422,6 +434,15 @@ export class ValueDataSource<T = any> implements DataSource<T> {
     });
   }
 
+  // -----------------------------------------------------------------------
+  // Mutation subscription (P2 — Event Bus)
+  // -----------------------------------------------------------------------
+
+  onMutation(callback: (event: MutationEvent<T>) => void): () => void {
+    this.mutationListeners.add(callback);
+    return () => { this.mutationListeners.delete(callback); };
+  }
+
   // -----------------------------------------------------------------------
   // Extra utilities
   // -----------------------------------------------------------------------

packages/core/src/adapters/__tests__/ValueDataSource.test.ts

@@ -470,3 +470,102 @@ describe('ValueDataSource — aggregate', () => {
     expect(result.find((r: any) => r.category === 'B')?.amount).toBe(50);
   });
 });
+
+// ---------------------------------------------------------------------------
+// onMutation (P2 — Event Bus)
+// ---------------------------------------------------------------------------
+
+describe('ValueDataSource — onMutation', () => {
+  it('should emit "create" event when a record is created', async () => {
+    const ds = createDS();
+    const events: any[] = [];
+    ds.onMutation((e) => events.push(e));
+
+    await ds.create('users', { name: 'Zara', age: 40 });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('create');
+    expect(events[0].resource).toBe('users');
+    expect(events[0].record.name).toBe('Zara');
+  });
+
+  it('should emit "update" event when a record is updated', async () => {
+    const ds = createDS();
+    const events: any[] = [];
+    ds.onMutation((e) => events.push(e));
+
+    await ds.update('users', '1', { age: 31 });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('update');
+    expect(events[0].resource).toBe('users');
+    expect(events[0].id).toBe('1');
+    expect(events[0].record.age).toBe(31);
+  });
+
+  it('should emit "delete" event when a record is deleted', async () => {
+    const ds = createDS();
+    const events: any[] = [];
+    ds.onMutation((e) => events.push(e));
+
+    await ds.delete('users', '2');
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('delete');
+    expect(events[0].resource).toBe('users');
+    expect(events[0].id).toBe('2');
+    expect(events[0].record).toBeUndefined();
+  });
+
+  it('should not emit "delete" for non-existent record', async () => {
+    const ds = createDS();
+    const events: any[] = [];
+    ds.onMutation((e) => events.push(e));
+
+    await ds.delete('users', '999');
+
+    expect(events).toHaveLength(0);
+  });
+
+  it('should support multiple subscribers', async () => {
+    const ds = createDS();
+    const eventsA: any[] = [];
+    const eventsB: any[] = [];
+    ds.onMutation((e) => eventsA.push(e));
+    ds.onMutation((e) => eventsB.push(e));
+
+    await ds.create('users', { name: 'Multi' });
+
+    expect(eventsA).toHaveLength(1);
+    expect(eventsB).toHaveLength(1);
+  });
+
+  it('should unsubscribe correctly', async () => {
+    const ds = createDS();
+    const events: any[] = [];
+    const unsub = ds.onMutation((e) => events.push(e));
+
+    await ds.create('users', { name: 'Before' });
+    expect(events).toHaveLength(1);
+
+    unsub();
+
+    await ds.create('users', { name: 'After' });
+    expect(events).toHaveLength(1); // No new event
+  });
+
+  it('should emit events for bulk operations', async () => {
+    const ds = createDS();
+    const events: any[] = [];
+    ds.onMutation((e) => events.push(e));
+
+    await ds.bulk!('users', 'create', [
+      { name: 'Bulk1' },
+      { name: 'Bulk2' },
+    ]);
+
+    // Bulk create calls create() for each item
+    expect(events).toHaveLength(2);
+    expect(events.every((e: any) => e.type === 'create')).toBe(true);
+  });
+});

packages/plugin-list/src/ListView.tsx

@@ -273,7 +273,24 @@ function useListFieldLabel() {
   }
 }
 
-export const ListView: React.FC<ListViewProps> = ({
+/**
+ * Imperative handle exposed by ListView via React.forwardRef.
+ * Allows parent components to trigger a data refresh programmatically.
+ *
+ * @example
+ * ```tsx
+ * const listRef = React.useRef<ListViewHandle>(null);
+ * <ListView ref={listRef} schema={schema} />
+ * // After a mutation:
+ * listRef.current?.refresh();
+ * ```
+ */
+export interface ListViewHandle {
+  /** Force the ListView to re-fetch data from the DataSource */
+  refresh(): void;
+}
+
+export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
   schema: propSchema,
   className,
   onViewChange,
@@ -283,7 +300,7 @@ export const ListView: React.FC<ListViewProps> = ({
   onRowClick,
   showViewSwitcher = false,
   ...props
-}) => {
+}, ref) => {
   // i18n support for record count and other labels
   const { t } = useListViewTranslation();
   const { fieldLabel: resolveFieldLabel } = useListFieldLabel();
@@ -393,6 +410,22 @@ export const ListView: React.FC<ListViewProps> = ({
   const [refreshKey, setRefreshKey] = React.useState(0);
   const [dataLimitReached, setDataLimitReached] = React.useState(false);
 
+  // --- P1: Imperative refresh API ---
+  React.useImperativeHandle(ref, () => ({
+    refresh: () => setRefreshKey(k => k + 1),
+  }), []);
+
+  // --- P2: Auto-subscribe to DataSource mutation events ---
+  React.useEffect(() => {
+    if (!dataSource?.onMutation || !schema.objectName) return;
+    const unsub = dataSource.onMutation((event) => {
+      if (event.resource === schema.objectName) {
+        setRefreshKey(k => k + 1);
+      }
+    });
+    return unsub;
+  }, [dataSource, schema.objectName]);
+
   // Dynamic page size state (wired from pageSizeOptions selector)
   const [dynamicPageSize, setDynamicPageSize] = React.useState<number | undefined>(undefined);
   const effectivePageSize = dynamicPageSize ?? schema.pagination?.pageSize ?? 100;
@@ -683,7 +716,7 @@ export const ListView: React.FC<ListViewProps> = ({
     fetchData();
 
     return () => { isMounted = false; };
-  }, [schema.objectName, schema.data, dataSource, schema.filters, effectivePageSize, currentSort, currentFilters, activeQuickFilters, normalizedQuickFilters, userFilterConditions, refreshKey, searchTerm, schema.searchableFields, expandFields, objectDefLoaded]); // Re-fetch on filter/sort/search change
+  }, [schema.objectName, schema.data, dataSource, schema.filters, effectivePageSize, currentSort, currentFilters, activeQuickFilters, normalizedQuickFilters, userFilterConditions, refreshKey, searchTerm, schema.searchableFields, expandFields, objectDefLoaded, schema.refreshTrigger]); // Re-fetch on filter/sort/search/refreshTrigger change
 
   // Available view types based on schema configuration
   const availableViews = React.useMemo(() => {
@@ -1685,4 +1718,6 @@ export const ListView: React.FC<ListViewProps> = ({
       )}
     </div>
   );
-};
+});
+
+ListView.displayName = 'ListView';