@object-ui/react 2.0.0 → 3.0.0

package/src/context/NotificationContext.tsx

@@ -0,0 +1,280 @@
+/**
+ * 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.
+ */
+
+/**
+ * @object-ui/react - Notification Context
+ *
+ * Provides a spec-driven notification system to the component tree.
+ * Implements NotificationSchema, NotificationConfigSchema, and
+ * NotificationActionSchema from @objectstack/spec v2.0.7.
+ */
+
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
+
+/** Notification severity levels aligned with NotificationSeveritySchema */
+export type NotificationSeverityLevel = 'info' | 'success' | 'warning' | 'error';
+
+/** Notification display type aligned with NotificationTypeSchema */
+export type NotificationDisplayType = 'toast' | 'banner' | 'snackbar' | 'modal';
+
+/** Notification position aligned with NotificationPositionSchema */
+export type NotificationPositionValue =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+/** Action button on a notification */
+export interface NotificationActionButton {
+  label: string;
+  onClick: () => void;
+  variant?: 'default' | 'destructive' | 'outline';
+}
+
+/** A single notification item */
+export interface NotificationItem {
+  id: string;
+  title: string;
+  message?: string;
+  severity: NotificationSeverityLevel;
+  displayType?: NotificationDisplayType;
+  actions?: NotificationActionButton[];
+  /** Duration in ms (0 = persistent). Default: 5000 */
+  duration?: number;
+  /** Whether the notification has been read */
+  read?: boolean;
+  /** Timestamp */
+  createdAt: Date;
+  /** Optional icon name (lucide icon) */
+  icon?: string;
+}
+
+/** Configuration for the notification system */
+export interface NotificationSystemConfig {
+  /** Default position for toast notifications */
+  position?: NotificationPositionValue;
+  /** Default duration in ms */
+  defaultDuration?: number;
+  /** Maximum number of visible notifications */
+  maxVisible?: number;
+  /** Whether to stack notifications */
+  stacking?: boolean;
+}
+
+export interface NotificationProviderProps {
+  children: React.ReactNode;
+  /** System configuration */
+  config?: NotificationSystemConfig;
+  /** External toast handler (e.g., Sonner) for rendering toasts */
+  onToast?: (notification: NotificationItem) => void;
+}
+
+interface NotificationContextValue {
+  /** All notifications (including history) */
+  notifications: NotificationItem[];
+  /** Unread notification count */
+  unreadCount: number;
+  /** Add a notification */
+  notify: (notification: Omit<NotificationItem, 'id' | 'createdAt' | 'read'>) => string;
+  /** Convenience: show info notification */
+  info: (title: string, message?: string) => string;
+  /** Convenience: show success notification */
+  success: (title: string, message?: string) => string;
+  /** Convenience: show warning notification */
+  warning: (title: string, message?: string) => string;
+  /** Convenience: show error notification */
+  error: (title: string, message?: string) => string;
+  /** Mark a notification as read */
+  markAsRead: (id: string) => void;
+  /** Mark all notifications as read */
+  markAllAsRead: () => void;
+  /** Dismiss a notification */
+  dismiss: (id: string) => void;
+  /** Clear all notifications */
+  clearAll: () => void;
+  /** System configuration */
+  config: NotificationSystemConfig;
+}
+
+let notificationCounter = 0;
+
+const NotificationCtx = createContext<NotificationContextValue | null>(null);
+
+/**
+ * NotificationProvider — Provides a spec-driven notification system.
+ *
+ * @example
+ * ```tsx
+ * <NotificationProvider
+ *   config={{ position: 'top-right', defaultDuration: 5000, maxVisible: 5 }}
+ *   onToast={(n) => toast[n.severity](n.title, { description: n.message })}
+ * >
+ *   <App />
+ * </NotificationProvider>
+ * ```
+ */
+export const NotificationProvider: React.FC<NotificationProviderProps> = ({
+  children,
+  config: userConfig = {},
+  onToast,
+}) => {
+  const config = useMemo<NotificationSystemConfig>(
+    () => ({
+      position: 'top-right',
+      defaultDuration: 5000,
+      maxVisible: 5,
+      stacking: true,
+      ...userConfig,
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(userConfig)],
+  );
+
+  const [notifications, setNotifications] = useState<NotificationItem[]>([]);
+
+  const notify = useCallback(
+    (input: Omit<NotificationItem, 'id' | 'createdAt' | 'read'>): string => {
+      const id = `notification-${++notificationCounter}`;
+      const notification: NotificationItem = {
+        ...input,
+        id,
+        createdAt: new Date(),
+        read: false,
+      };
+
+      setNotifications((prev) => [notification, ...prev]);
+
+      // Delegate to external toast handler if provided
+      if (onToast) {
+        onToast(notification);
+      }
+
+      // Auto-dismiss non-persistent notifications
+      const duration = input.duration ?? config.defaultDuration ?? 5000;
+      if (duration > 0) {
+        setTimeout(() => {
+          setNotifications((prev) => prev.filter((n) => n.id !== id));
+        }, duration);
+      }
+
+      return id;
+    },
+    [config.defaultDuration, onToast],
+  );
+
+  const info = useCallback(
+    (title: string, message?: string) =>
+      notify({ title, message, severity: 'info' }),
+    [notify],
+  );
+
+  const success = useCallback(
+    (title: string, message?: string) =>
+      notify({ title, message, severity: 'success' }),
+    [notify],
+  );
+
+  const warning = useCallback(
+    (title: string, message?: string) =>
+      notify({ title, message, severity: 'warning' }),
+    [notify],
+  );
+
+  const error = useCallback(
+    (title: string, message?: string) =>
+      notify({ title, message, severity: 'error' }),
+    [notify],
+  );
+
+  const markAsRead = useCallback((id: string) => {
+    setNotifications((prev) =>
+      prev.map((n) => (n.id === id ? { ...n, read: true } : n)),
+    );
+  }, []);
+
+  const markAllAsRead = useCallback(() => {
+    setNotifications((prev) => prev.map((n) => ({ ...n, read: true })));
+  }, []);
+
+  const dismiss = useCallback((id: string) => {
+    setNotifications((prev) => prev.filter((n) => n.id !== id));
+  }, []);
+
+  const clearAll = useCallback(() => {
+    setNotifications([]);
+  }, []);
+
+  const unreadCount = useMemo(
+    () => notifications.filter((n) => !n.read).length,
+    [notifications],
+  );
+
+  const value = useMemo<NotificationContextValue>(
+    () => ({
+      notifications,
+      unreadCount,
+      notify,
+      info,
+      success,
+      warning,
+      error,
+      markAsRead,
+      markAllAsRead,
+      dismiss,
+      clearAll,
+      config,
+    }),
+    [
+      notifications,
+      unreadCount,
+      notify,
+      info,
+      success,
+      warning,
+      error,
+      markAsRead,
+      markAllAsRead,
+      dismiss,
+      clearAll,
+      config,
+    ],
+  );
+
+  return (
+    <NotificationCtx.Provider value={value}>
+      {children}
+    </NotificationCtx.Provider>
+  );
+};
+
+NotificationProvider.displayName = 'NotificationProvider';
+
+/**
+ * Hook to consume the NotificationProvider context.
+ *
+ * @throws Error if used outside a NotificationProvider
+ */
+export function useNotifications(): NotificationContextValue {
+  const ctx = useContext(NotificationCtx);
+  if (!ctx) {
+    throw new Error(
+      'useNotifications must be used within a <NotificationProvider>. ' +
+        'Wrap your app with <NotificationProvider> to use the notification system.',
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Hook to check if a NotificationProvider is available.
+ */
+export function useHasNotificationProvider(): boolean {
+  return useContext(NotificationCtx) !== null;
+}

package/src/context/__tests__/DndContext.test.tsx

@@ -0,0 +1,150 @@
+/**
+ * Tests for DndProvider and useDnd
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import React from 'react';
+import {
+  DndProvider,
+  useDnd,
+  useHasDndProvider,
+} from '../DndContext';
+
+const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+  <DndProvider>{children}</DndProvider>
+);
+
+describe('DndProvider', () => {
+  it('provides DnD context', () => {
+    const { result } = renderHook(() => useDnd(), { wrapper });
+    expect(result.current.enabled).toBe(true);
+    expect(result.current.activeItem).toBeNull();
+  });
+
+  it('starts drag operation', () => {
+    const onDragStart = vi.fn();
+    const customWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+      <DndProvider onDragStart={onDragStart}>{children}</DndProvider>
+    );
+
+    const { result } = renderHook(() => useDnd(), { wrapper: customWrapper });
+
+    act(() => {
+      result.current.startDrag({ id: 'item-1', type: 'card' });
+    });
+
+    expect(result.current.activeItem).toEqual({ id: 'item-1', type: 'card' });
+    expect(onDragStart).toHaveBeenCalledTimes(1);
+  });
+
+  it('ends drag operation', () => {
+    const onDrop = vi.fn();
+    const customWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+      <DndProvider onDrop={onDrop}>{children}</DndProvider>
+    );
+
+    const { result } = renderHook(() => useDnd(), { wrapper: customWrapper });
+
+    act(() => {
+      result.current.startDrag({ id: 'item-1', type: 'card' });
+    });
+
+    act(() => {
+      result.current.endDrag('zone-1');
+    });
+
+    expect(result.current.activeItem).toBeNull();
+    expect(onDrop).toHaveBeenCalledTimes(1);
+    expect(onDrop).toHaveBeenCalledWith(
+      expect.objectContaining({ item: { id: 'item-1', type: 'card' }, targetZoneId: 'zone-1' })
+    );
+  });
+
+  it('cancels drag operation', () => {
+    const onDragCancel = vi.fn();
+    const customWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+      <DndProvider onDragCancel={onDragCancel}>{children}</DndProvider>
+    );
+
+    const { result } = renderHook(() => useDnd(), { wrapper: customWrapper });
+
+    act(() => {
+      result.current.startDrag({ id: 'item-1', type: 'card' });
+    });
+
+    act(() => {
+      result.current.cancelDrag();
+    });
+
+    expect(result.current.activeItem).toBeNull();
+    expect(onDragCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('registers and checks drop zones', () => {
+    const { result } = renderHook(() => useDnd(), { wrapper });
+
+    act(() => {
+      result.current.registerDropZone({
+        id: 'zone-1',
+        acceptTypes: ['card', 'widget'],
+      });
+    });
+
+    expect(result.current.canDrop('zone-1', 'card')).toBe(true);
+    expect(result.current.canDrop('zone-1', 'unknown')).toBe(false);
+    expect(result.current.canDrop('nonexistent', 'card')).toBe(false);
+  });
+
+  it('unregisters drop zones', () => {
+    const { result } = renderHook(() => useDnd(), { wrapper });
+
+    act(() => {
+      result.current.registerDropZone({
+        id: 'zone-1',
+        acceptTypes: ['card'],
+      });
+    });
+
+    act(() => {
+      result.current.unregisterDropZone('zone-1');
+    });
+
+    expect(result.current.canDrop('zone-1', 'card')).toBe(false);
+  });
+
+  it('respects disabled config', () => {
+    const onDragStart = vi.fn();
+    const customWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+      <DndProvider config={{ enabled: false }} onDragStart={onDragStart}>{children}</DndProvider>
+    );
+
+    const { result } = renderHook(() => useDnd(), { wrapper: customWrapper });
+
+    act(() => {
+      result.current.startDrag({ id: 'item-1', type: 'card' });
+    });
+
+    expect(result.current.activeItem).toBeNull();
+    expect(onDragStart).not.toHaveBeenCalled();
+  });
+});
+
+describe('useHasDndProvider', () => {
+  it('returns false outside provider', () => {
+    const { result } = renderHook(() => useHasDndProvider());
+    expect(result.current).toBe(false);
+  });
+
+  it('returns true inside provider', () => {
+    const { result } = renderHook(() => useHasDndProvider(), { wrapper });
+    expect(result.current).toBe(true);
+  });
+});
+
+describe('useDnd without provider', () => {
+  it('throws error', () => {
+    expect(() => {
+      renderHook(() => useDnd());
+    }).toThrow('useDnd must be used within a <DndProvider>');
+  });
+});

package/src/context/__tests__/NotificationContext.test.tsx

@@ -0,0 +1,176 @@
+/**
+ * Tests for NotificationProvider and useNotifications
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import React from 'react';
+import {
+  NotificationProvider,
+  useNotifications,
+  useHasNotificationProvider,
+} from '../NotificationContext';
+
+const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+  <NotificationProvider>{children}</NotificationProvider>
+);
+
+describe('NotificationProvider', () => {
+  it('provides notifications context', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+    expect(result.current.notifications).toEqual([]);
+    expect(result.current.unreadCount).toBe(0);
+  });
+
+  it('adds a notification via notify', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    act(() => {
+      result.current.notify({ title: 'Hello', severity: 'info' });
+    });
+
+    expect(result.current.notifications).toHaveLength(1);
+    expect(result.current.notifications[0].title).toBe('Hello');
+    expect(result.current.unreadCount).toBe(1);
+  });
+
+  it('adds info notification', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    act(() => {
+      result.current.info('Info title', 'Info message');
+    });
+
+    expect(result.current.notifications[0].severity).toBe('info');
+  });
+
+  it('adds success notification', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    act(() => {
+      result.current.success('Success!');
+    });
+
+    expect(result.current.notifications[0].severity).toBe('success');
+  });
+
+  it('adds warning notification', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    act(() => {
+      result.current.warning('Warning!');
+    });
+
+    expect(result.current.notifications[0].severity).toBe('warning');
+  });
+
+  it('adds error notification', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    act(() => {
+      result.current.error('Error!');
+    });
+
+    expect(result.current.notifications[0].severity).toBe('error');
+  });
+
+  it('marks notification as read', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    let id: string = '';
+    act(() => {
+      id = result.current.info('Test');
+    });
+
+    act(() => {
+      result.current.markAsRead(id);
+    });
+
+    expect(result.current.notifications[0].read).toBe(true);
+    expect(result.current.unreadCount).toBe(0);
+  });
+
+  it('marks all as read', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    act(() => {
+      result.current.info('Test 1');
+      result.current.info('Test 2');
+    });
+
+    act(() => {
+      result.current.markAllAsRead();
+    });
+
+    expect(result.current.unreadCount).toBe(0);
+  });
+
+  it('dismisses a notification', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    let id: string = '';
+    act(() => {
+      id = result.current.info('Test');
+    });
+
+    act(() => {
+      result.current.dismiss(id);
+    });
+
+    expect(result.current.notifications).toHaveLength(0);
+  });
+
+  it('clears all notifications', () => {
+    const { result } = renderHook(() => useNotifications(), { wrapper });
+
+    act(() => {
+      result.current.info('Test 1');
+      result.current.info('Test 2');
+    });
+
+    act(() => {
+      result.current.clearAll();
+    });
+
+    expect(result.current.notifications).toHaveLength(0);
+  });
+
+  it('calls onToast handler', () => {
+    const onToast = vi.fn();
+    const customWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+      <NotificationProvider onToast={onToast}>{children}</NotificationProvider>
+    );
+
+    const { result } = renderHook(() => useNotifications(), {
+      wrapper: customWrapper,
+    });
+
+    act(() => {
+      result.current.info('Toast test');
+    });
+
+    expect(onToast).toHaveBeenCalledTimes(1);
+    expect(onToast).toHaveBeenCalledWith(
+      expect.objectContaining({ title: 'Toast test', severity: 'info' })
+    );
+  });
+});
+
+describe('useHasNotificationProvider', () => {
+  it('returns false outside provider', () => {
+    const { result } = renderHook(() => useHasNotificationProvider());
+    expect(result.current).toBe(false);
+  });
+
+  it('returns true inside provider', () => {
+    const { result } = renderHook(() => useHasNotificationProvider(), { wrapper });
+    expect(result.current).toBe(true);
+  });
+});
+
+describe('useNotifications without provider', () => {
+  it('throws error', () => {
+    expect(() => {
+      renderHook(() => useNotifications());
+    }).toThrow('useNotifications must be used within a <NotificationProvider>');
+  });
+});

package/src/context/index.ts

@@ -9,3 +9,5 @@
 export * from './SchemaRendererContext';
 export * from './ActionContext';
 export * from './ThemeContext';
+export * from './NotificationContext';
+export * from './DndContext';

package/src/hooks/__tests__/useAnimation.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Tests for useAnimation and useReducedMotion hooks
+ */
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useAnimation } from '../useAnimation';
+import { useReducedMotion } from '../useReducedMotion';
+
+describe('useAnimation', () => {
+  it('returns empty className and style for no config', () => {
+    const { result } = renderHook(() => useAnimation());
+    expect(result.current.className).toBe('');
+    expect(result.current.style).toEqual({});
+  });
+
+  it('returns empty when preset is none', () => {
+    const { result } = renderHook(() => useAnimation({ preset: 'none' }));
+    expect(result.current.className).toBe('');
+  });
+
+  it('returns empty when disabled', () => {
+    const { result } = renderHook(() =>
+      useAnimation({ preset: 'fade', enabled: false })
+    );
+    expect(result.current.className).toBe('');
+  });
+
+  it('returns correct className for fade preset', () => {
+    const { result } = renderHook(() => useAnimation({ preset: 'fade' }));
+    expect(result.current.className).toContain('fade-in');
+  });
+
+  it('returns correct className for slide-up preset', () => {
+    const { result } = renderHook(() => useAnimation({ preset: 'slide-up' }));
+    expect(result.current.className).toContain('slide-in-from-bottom');
+  });
+
+  it('returns correct className for scale preset', () => {
+    const { result } = renderHook(() => useAnimation({ preset: 'scale' }));
+    expect(result.current.className).toContain('zoom-in');
+  });
+
+  it('returns correct className for scale-fade preset', () => {
+    const { result } = renderHook(() => useAnimation({ preset: 'scale-fade' }));
+    expect(result.current.className).toContain('fade-in');
+    expect(result.current.className).toContain('zoom-in');
+  });
+
+  it('applies custom duration', () => {
+    const { result } = renderHook(() =>
+      useAnimation({ preset: 'fade', duration: 300 })
+    );
+    expect(result.current.style.animationDuration).toBe('300ms');
+  });
+
+  it('applies custom delay', () => {
+    const { result } = renderHook(() =>
+      useAnimation({ preset: 'fade', delay: 100 })
+    );
+    expect(result.current.style.animationDelay).toBe('100ms');
+  });
+
+  it('applies easing function', () => {
+    const { result } = renderHook(() =>
+      useAnimation({ preset: 'fade', easing: 'spring' })
+    );
+    expect(result.current.style.animationTimingFunction).toContain('cubic-bezier');
+  });
+});
+
+describe('useReducedMotion', () => {
+  it('returns a boolean value', () => {
+    const { result } = renderHook(() => useReducedMotion());
+    expect(typeof result.current).toBe('boolean');
+  });
+
+  it('defaults to false when matchMedia returns false', () => {
+    const { result } = renderHook(() => useReducedMotion());
+    // jsdom matchMedia always returns false by default
+    expect(result.current).toBe(false);
+  });
+});