@object-ui/react 2.0.0 → 3.0.0

package/src/hooks/useClientNotifications.ts

@@ -0,0 +1,251 @@
+/**
+ * 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 - useClientNotifications
+ *
+ * Bridge hook between the @objectstack/client notifications API
+ * and the local NotificationContext state. Fetches server-side
+ * notifications and surfaces them through the existing provider.
+ */
+
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { SchemaRendererContext } from '../context/SchemaRendererContext';
+import { useNotifications } from '../context/NotificationContext';
+import type { NotificationSeverityLevel } from '../context/NotificationContext';
+
+/* ------------------------------------------------------------------ */
+/*  Public types                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface UseClientNotificationsOptions {
+  /** ObjectStack client instance (optional, from context if available) */
+  client?: any;
+  /** Whether to auto-fetch notifications on mount */
+  autoFetch?: boolean;
+  /** Polling interval in ms (0 to disable) */
+  pollInterval?: number;
+}
+
+export interface UseClientNotificationsResult {
+  /** Fetch notifications from server */
+  fetchNotifications: () => Promise<void>;
+  /** Register device for push notifications */
+  registerDevice: (token: string, platform: string) => Promise<void>;
+  /** Get notification preferences */
+  getPreferences: () => Promise<any>;
+  /** Update notification preferences */
+  updatePreferences: (prefs: any) => Promise<void>;
+  /** Mark a notification as read on the server */
+  markAsRead: (id: string) => Promise<void>;
+  /** Loading state */
+  loading: boolean;
+  /** Error state */
+  error: Error | null;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                           */
+/* ------------------------------------------------------------------ */
+
+/** Normalise severity coming from the server into a valid local level. */
+function toSeverity(value: unknown): NotificationSeverityLevel {
+  const valid: NotificationSeverityLevel[] = ['info', 'success', 'warning', 'error'];
+  if (typeof value === 'string' && valid.includes(value as NotificationSeverityLevel)) {
+    return value as NotificationSeverityLevel;
+  }
+  return 'info';
+}
+
+/**
+ * Resolve the ObjectStack client from explicit option or SchemaRendererContext.
+ *
+ * The dataSource stored in context is typically an ObjectStackAdapter which
+ * exposes `getClient()`.  When the caller passes a client directly we use
+ * that instead.
+ */
+function useResolvedClient(explicit?: any): any {
+  const rendererCtx = useContext(SchemaRendererContext);
+  if (explicit) return explicit;
+
+  const dataSource = rendererCtx?.dataSource;
+  if (dataSource && typeof dataSource.getClient === 'function') {
+    return dataSource.getClient();
+  }
+  return null;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Hook                                                              */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Bridge between the `@objectstack/client` notifications API and the
+ * local {@link NotificationContext}.
+ *
+ * The hook resolves the ObjectStack client either from the explicit
+ * `client` option or from the `SchemaRendererContext` dataSource, then
+ * delegates to `client.notifications.*` methods.  Fetched notifications
+ * are fed into the local provider via `useNotifications().notify()`.
+ *
+ * @example
+ * ```tsx
+ * function NotificationBell() {
+ *   const { fetchNotifications, loading } = useClientNotifications({
+ *     autoFetch: true,
+ *     pollInterval: 30_000,
+ *   });
+ *
+ *   return <Button onClick={fetchNotifications} disabled={loading}>🔔</Button>;
+ * }
+ * ```
+ */
+export function useClientNotifications(
+  options: UseClientNotificationsOptions = {},
+): UseClientNotificationsResult {
+  const { client: explicitClient, autoFetch = false, pollInterval = 0 } = options;
+
+  const client = useResolvedClient(explicitClient);
+  const { notify, markAsRead: localMarkAsRead } = useNotifications();
+
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Track IDs that have already been pushed into the local context so we
+  // don't add duplicates on subsequent fetches / polls.
+  const seenIdsRef = useRef<Set<string>>(new Set());
+
+  /* ---- fetchNotifications ---- */
+
+  const fetchNotifications = useCallback(async () => {
+    if (!client?.notifications) return;
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await client.notifications.list({});
+      const items: any[] = Array.isArray(result) ? result : result?.data ?? result?.items ?? [];
+
+      for (const item of items) {
+        const id = String(item.id ?? '');
+        if (!id || seenIdsRef.current.has(id)) continue;
+
+        seenIdsRef.current.add(id);
+        notify({
+          title: item.title ?? 'Notification',
+          message: item.message ?? item.body,
+          severity: toSeverity(item.severity ?? item.level),
+          duration: 0, // server-driven notifications are persistent
+        });
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to fetch notifications'));
+    } finally {
+      setLoading(false);
+    }
+  }, [client, notify]);
+
+  /* ---- registerDevice ---- */
+
+  const registerDevice = useCallback(
+    async (token: string, platform: string) => {
+      if (!client?.notifications) return;
+      setError(null);
+      try {
+        await client.notifications.registerDevice(token, platform);
+      } catch (err) {
+        const wrapped = err instanceof Error ? err : new Error('Failed to register device');
+        setError(wrapped);
+        throw wrapped;
+      }
+    },
+    [client],
+  );
+
+  /* ---- getPreferences ---- */
+
+  const getPreferences = useCallback(async () => {
+    if (!client?.notifications) return null;
+    setError(null);
+    try {
+      return await client.notifications.getPreferences();
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error('Failed to get preferences');
+      setError(wrapped);
+      throw wrapped;
+    }
+  }, [client]);
+
+  /* ---- updatePreferences ---- */
+
+  const updatePreferences = useCallback(
+    async (prefs: any) => {
+      if (!client?.notifications) return;
+      setError(null);
+      try {
+        await client.notifications.updatePreferences(prefs);
+      } catch (err) {
+        const wrapped = err instanceof Error ? err : new Error('Failed to update preferences');
+        setError(wrapped);
+        throw wrapped;
+      }
+    },
+    [client],
+  );
+
+  /* ---- markAsRead (server + local) ---- */
+
+  const markAsRead = useCallback(
+    async (id: string) => {
+      // Optimistically mark locally first
+      localMarkAsRead(id);
+
+      if (!client?.notifications) return;
+      setError(null);
+      try {
+        await client.notifications.markAsRead(id);
+      } catch (err) {
+        const wrapped = err instanceof Error ? err : new Error('Failed to mark as read');
+        setError(wrapped);
+        throw wrapped;
+      }
+    },
+    [client, localMarkAsRead],
+  );
+
+  /* ---- auto-fetch on mount ---- */
+
+  useEffect(() => {
+    if (autoFetch && client?.notifications) {
+      fetchNotifications();
+    }
+  }, [autoFetch, client, fetchNotifications]);
+
+  /* ---- polling ---- */
+
+  useEffect(() => {
+    if (!pollInterval || pollInterval <= 0 || !client?.notifications) return;
+
+    const id = setInterval(() => {
+      fetchNotifications();
+    }, pollInterval);
+
+    return () => clearInterval(id);
+  }, [pollInterval, client, fetchNotifications]);
+
+  return {
+    fetchNotifications,
+    registerDevice,
+    getPreferences,
+    updatePreferences,
+    markAsRead,
+    loading,
+    error,
+  };
+}

package/src/hooks/useColumnSummary.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 { useMemo } from 'react';
+
+/** Summary function types aligned with ColumnSummarySchema */
+export type SummaryFunction = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'distinct';
+
+export interface ColumnSummaryConfig {
+  /** The field/column to aggregate */
+  field: string;
+  /** The aggregation function */
+  function: SummaryFunction;
+  /** Optional label for the summary */
+  label?: string;
+  /** Number format options */
+  format?: Intl.NumberFormatOptions;
+}
+
+export interface ColumnSummaryResult {
+  /** The computed value */
+  value: number;
+  /** Formatted display string */
+  formatted: string;
+  /** The label */
+  label: string;
+}
+
+/**
+ * Hook for computing column-level summaries (SUM, AVG, COUNT, MIN, MAX, DISTINCT).
+ * Implements ColumnSummarySchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * const summary = useColumnSummary(data, { field: 'amount', function: 'sum', label: 'Total' });
+ * // summary.formatted => "$12,345.67"
+ * ```
+ */
+export function useColumnSummary(
+  data: Record<string, unknown>[],
+  config: ColumnSummaryConfig,
+  locale?: string
+): ColumnSummaryResult {
+  return useMemo(() => {
+    const values = data
+      .map((row) => {
+        const val = row[config.field];
+        return typeof val === 'number' ? val : Number(val);
+      })
+      .filter((v) => !isNaN(v));
+
+    let value: number;
+
+    switch (config.function) {
+      case 'sum':
+        value = values.reduce((acc, v) => acc + v, 0);
+        break;
+      case 'avg':
+        value = values.length > 0 ? values.reduce((acc, v) => acc + v, 0) / values.length : 0;
+        break;
+      case 'count':
+        value = data.length;
+        break;
+      case 'min':
+        value = values.length > 0 ? Math.min(...values) : 0;
+        break;
+      case 'max':
+        value = values.length > 0 ? Math.max(...values) : 0;
+        break;
+      case 'distinct':
+        value = new Set(data.map((row) => row[config.field])).size;
+        break;
+      default:
+        value = 0;
+    }
+
+    const formatted = new Intl.NumberFormat(locale, config.format).format(value);
+    const label = config.label ?? config.function.toUpperCase();
+
+    return { value, formatted, label };
+  }, [data, config.field, config.function, config.label, config.format, locale]);
+}

package/src/hooks/useCrudShortcuts.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 { useMemo } from 'react';
+import {
+  useKeyboardShortcuts,
+  type KeyboardShortcutDefinition,
+} from './useKeyboardShortcuts';
+
+export interface CrudShortcutCallbacks {
+  onCreate?: () => void;
+  onEdit?: () => void;
+  onDelete?: () => void;
+  onSave?: () => void;
+  onDuplicate?: () => void;
+  onCancel?: () => void;
+  onSearch?: () => void;
+}
+
+/**
+ * Registers standard CRUD keyboard shortcuts using the useKeyboardShortcuts hook.
+ *
+ * Shortcuts:
+ * - Ctrl/Cmd+N: Create new record
+ * - Ctrl/Cmd+E: Edit selected record
+ * - Delete / Backspace: Delete selected record(s)
+ * - Ctrl/Cmd+S: Save current record
+ * - Ctrl/Cmd+D: Duplicate selected record
+ * - Escape: Cancel/close current operation
+ * - Ctrl/Cmd+F: Focus search
+ *
+ * @example
+ * ```tsx
+ * useCrudShortcuts({
+ *   onCreate: () => openCreateDialog(),
+ *   onSave: () => saveRecord(),
+ *   onDelete: () => deleteSelected(),
+ *   onCancel: () => closeDialog(),
+ * });
+ * ```
+ */
+export function useCrudShortcuts(
+  callbacks: CrudShortcutCallbacks,
+  enabled = true
+): void {
+  const shortcuts = useMemo<KeyboardShortcutDefinition[]>(() => {
+    const defs: KeyboardShortcutDefinition[] = [];
+
+    if (callbacks.onCreate) {
+      defs.push({
+        key: 'n',
+        ctrlOrMeta: true,
+        handler: () => callbacks.onCreate!(),
+        description: 'New record',
+      });
+    }
+
+    if (callbacks.onEdit) {
+      defs.push({
+        key: 'e',
+        ctrlOrMeta: true,
+        handler: () => callbacks.onEdit!(),
+        description: 'Edit selected record',
+      });
+    }
+
+    if (callbacks.onDelete) {
+      defs.push(
+        {
+          key: 'Delete',
+          handler: () => callbacks.onDelete!(),
+          description: 'Delete selected record(s)',
+        },
+        {
+          key: 'Backspace',
+          handler: () => callbacks.onDelete!(),
+          description: 'Delete selected record(s)',
+        }
+      );
+    }
+
+    if (callbacks.onSave) {
+      defs.push({
+        key: 's',
+        ctrlOrMeta: true,
+        handler: () => callbacks.onSave!(),
+        description: 'Save current record',
+      });
+    }
+
+    if (callbacks.onDuplicate) {
+      defs.push({
+        key: 'd',
+        ctrlOrMeta: true,
+        handler: () => callbacks.onDuplicate!(),
+        description: 'Duplicate selected record',
+      });
+    }
+
+    if (callbacks.onCancel) {
+      defs.push({
+        key: 'Escape',
+        handler: () => callbacks.onCancel!(),
+        description: 'Cancel/close current operation',
+      });
+    }
+
+    if (callbacks.onSearch) {
+      defs.push({
+        key: 'f',
+        ctrlOrMeta: true,
+        handler: () => callbacks.onSearch!(),
+        description: 'Focus search',
+      });
+    }
+
+    return defs;
+  }, [callbacks]);
+
+  useKeyboardShortcuts(shortcuts, { enabled });
+}

package/src/hooks/useDensityMode.ts

@@ -0,0 +1,102 @@
+/**
+ * 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, useMemo } from 'react';
+
+/** Density mode aligned with DensityMode from @objectstack/spec v2.0.7 */
+export type DensityModeValue = 'compact' | 'comfortable' | 'spacious';
+
+export interface DensityConfig {
+  /** Row height in pixels for each density mode */
+  rowHeights?: Record<DensityModeValue, number>;
+  /** Padding classes for each density mode */
+  paddingClasses?: Record<DensityModeValue, string>;
+  /** Font size classes for each density mode */
+  fontSizeClasses?: Record<DensityModeValue, string>;
+}
+
+export interface DensityResult {
+  /** Current density mode */
+  mode: DensityModeValue;
+  /** Set the density mode */
+  setMode: (mode: DensityModeValue) => void;
+  /** Cycle through density modes */
+  cycle: () => void;
+  /** Row height for the current mode (in pixels) */
+  rowHeight: number;
+  /** Tailwind padding class for the current mode */
+  paddingClass: string;
+  /** Tailwind font-size class for the current mode */
+  fontSizeClass: string;
+}
+
+const DEFAULT_ROW_HEIGHTS: Record<DensityModeValue, number> = {
+  compact: 32,
+  comfortable: 40,
+  spacious: 52,
+};
+
+const DEFAULT_PADDING_CLASSES: Record<DensityModeValue, string> = {
+  compact: 'py-1 px-2',
+  comfortable: 'py-2 px-3',
+  spacious: 'py-3 px-4',
+};
+
+const DEFAULT_FONT_SIZE_CLASSES: Record<DensityModeValue, string> = {
+  compact: 'text-xs',
+  comfortable: 'text-sm',
+  spacious: 'text-base',
+};
+
+const DENSITY_ORDER: DensityModeValue[] = ['compact', 'comfortable', 'spacious'];
+
+/**
+ * Hook for managing view density modes (compact/comfortable/spacious).
+ * Implements DensityMode from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * const density = useDensityMode('comfortable');
+ *
+ * return (
+ *   <div className={density.paddingClass}>
+ *     <table style={{ rowHeight: density.rowHeight }}>...</table>
+ *     <button onClick={density.cycle}>Toggle Density</button>
+ *   </div>
+ * );
+ * ```
+ */
+export function useDensityMode(
+  initialMode: DensityModeValue = 'comfortable',
+  config?: DensityConfig
+): DensityResult {
+  const [mode, setMode] = useState<DensityModeValue>(initialMode);
+
+  const rowHeights = config?.rowHeights ?? DEFAULT_ROW_HEIGHTS;
+  const paddingClasses = config?.paddingClasses ?? DEFAULT_PADDING_CLASSES;
+  const fontSizeClasses = config?.fontSizeClasses ?? DEFAULT_FONT_SIZE_CLASSES;
+
+  const cycle = useCallback(() => {
+    setMode((current) => {
+      const idx = DENSITY_ORDER.indexOf(current);
+      return DENSITY_ORDER[(idx + 1) % DENSITY_ORDER.length];
+    });
+  }, []);
+
+  return useMemo(
+    () => ({
+      mode,
+      setMode,
+      cycle,
+      rowHeight: rowHeights[mode],
+      paddingClass: paddingClasses[mode],
+      fontSizeClass: fontSizeClasses[mode],
+    }),
+    [mode, cycle, rowHeights, paddingClasses, fontSizeClasses]
+  );
+}