@ismaelsoilet/synapsejs 1.9.0 → 1.11.1

package/src/client/error-boundary.tsx

@@ -0,0 +1,59 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+export interface SliceErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode | ((error: Error) => ReactNode);
+  onError?: (error: Error, info: ErrorInfo) => void;
+}
+
+interface SliceErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class SliceErrorBoundary extends Component<SliceErrorBoundaryProps, SliceErrorBoundaryState> {
+  override state: SliceErrorBoundaryState = {
+    hasError: false,
+    error: null
+  };
+
+  static getDerivedStateFromError(error: Error): SliceErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    if (this.props.onError) {
+      this.props.onError(error, info);
+    } else {
+      console.error('[SliceErrorBoundary] Erro capturado na interface da fatia:', error, info);
+    }
+  }
+
+  override render(): ReactNode {
+    if (this.state.hasError && this.state.error) {
+      if (typeof this.props.fallback === 'function') {
+        return this.props.fallback(this.state.error);
+      }
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+      return (
+        <div
+          role="alert"
+          style={{
+            padding: '1rem',
+            border: '1px solid #f43f5e',
+            borderRadius: '0.375rem',
+            background: 'rgba(244, 63, 94, 0.1)',
+            color: '#f43f5e',
+            fontFamily: 'system-ui, -apple-system, sans-serif'
+          }}
+        >
+          <strong style={{ display: 'block', marginBottom: '0.25rem' }}>Erro na interface da fatia:</strong>
+          <span>{this.state.error.message}</span>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}

package/src/client/hooks.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Result } from '../core/machine-types';
 import { useSynapseContext } from './context';
+import { useToast } from './toast';
 
 export interface UseSubscriptionOptions {
   enabled?: boolean;
@@ -90,6 +91,7 @@ export interface UseActionResult<TPayload, TData, TError> {
 export interface UseActionOptions<TData, TError> {
   onSuccess?: (data: TData) => void;
   onError?: (error: TError) => void;
+  toast?: boolean | { success?: string; error?: string };
 }
 
 /**
@@ -104,6 +106,7 @@ export function useAction<TPayload = unknown, TData = unknown, TError = string>(
   const [data, setData] = useState<TData | null>(null);
   const [error, setError] = useState<TError | null>(null);
   const [isSuccess, setIsSuccess] = useState<boolean>(false);
+  const toast = useToast();
 
   const ctx = useSynapseContext();
   const resolvedAction =
@@ -141,10 +144,24 @@ export function useAction<TPayload = unknown, TData = unknown, TError = string>(
           setIsSuccess(true);
           setError(null);
           optionsRef.current?.onSuccess?.(result.value);
+          if (optionsRef.current?.toast) {
+            const successMsg =
+              typeof optionsRef.current.toast === 'object' && optionsRef.current.toast.success
+                ? optionsRef.current.toast.success
+                : 'Ação executada com sucesso!';
+            toast.success(successMsg);
+          }
         } else {
           setError(result.error);
           setIsSuccess(false);
           optionsRef.current?.onError?.(result.error);
+          if (optionsRef.current?.toast) {
+            const errorMsg =
+              typeof optionsRef.current.toast === 'object' && optionsRef.current.toast.error
+                ? optionsRef.current.toast.error
+                : String(result.error);
+            toast.error(errorMsg);
+          }
         }
         return result;
       } catch (err: unknown) {
@@ -152,12 +169,15 @@ export function useAction<TPayload = unknown, TData = unknown, TError = string>(
         setError(failure);
         setIsSuccess(false);
         optionsRef.current?.onError?.(failure);
+        if (optionsRef.current?.toast) {
+          toast.error(String(failure));
+        }
         return { ok: false, error: failure };
       } finally {
         setIsSubmitting(false);
       }
     },
-    [resolvedAction]
+    [resolvedAction, toast]
   );
 
   return {
@@ -171,3 +191,82 @@ export function useAction<TPayload = unknown, TData = unknown, TError = string>(
     reset
   };
 }
+
+/**
+ * Hook for reading dynamic URL route parameters (e.g. /:domain/:name/:id).
+ * Resolves from window.location pathname segments or SSR injected route params.
+ */
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T {
+  const ctx = useSynapseContext();
+  const [params] = useState<T>(() => {
+    if (ctx.props?.__synapse_params) {
+      return ctx.props.__synapse_params as T;
+    }
+    if (typeof window !== 'undefined') {
+      const globalParams = (window as unknown as { __SYNAPSE_ROUTE_PARAMS__?: T }).__SYNAPSE_ROUTE_PARAMS__;
+      if (globalParams) return globalParams;
+      const segments = window.location.pathname.split('/').filter(Boolean);
+      if (segments.length >= 3) {
+        const remaining = segments.slice(2);
+        const mapped: Record<string, string> = { id: remaining[0] };
+        for (let i = 0; i < remaining.length; i++) {
+          mapped[`param${i + 1}`] = remaining[i];
+        }
+        return mapped as T;
+      }
+    }
+    return {} as T;
+  });
+
+  return params;
+}
+
+/**
+ * Hook for reading and mutating query string search parameters seamlessly.
+ */
+export function useSearchParams(): [
+  URLSearchParams,
+  (updater: Record<string, string | null | undefined> | URLSearchParams) => void
+] {
+  const ctx = useSynapseContext();
+  const [searchParams, setSearchParamsState] = useState<URLSearchParams>(() => {
+    if (typeof window !== 'undefined') {
+      return new URLSearchParams(window.location.search);
+    }
+    if (ctx.url) {
+      try {
+        const u = new URL(ctx.url, 'http://localhost');
+        return u.searchParams;
+      } catch {
+        // fallback
+      }
+    }
+    return new URLSearchParams();
+  });
+
+  const setSearchParams = useCallback((updater: Record<string, string | null | undefined> | URLSearchParams) => {
+    if (typeof window === 'undefined') return;
+
+    const next = new URLSearchParams(window.location.search);
+    if (updater instanceof URLSearchParams) {
+      for (const [k, v] of updater.entries()) {
+        next.set(k, v);
+      }
+    } else {
+      for (const [k, v] of Object.entries(updater)) {
+        if (v === null || v === undefined) {
+          next.delete(k);
+        } else {
+          next.set(k, v);
+        }
+      }
+    }
+
+    const queryStr = next.toString();
+    const newUrl = queryStr ? `${window.location.pathname}?${queryStr}` : window.location.pathname;
+    window.history.pushState({}, '', newUrl);
+    setSearchParamsState(next);
+  }, []);
+
+  return [searchParams, setSearchParams];
+}

package/src/client/toast.tsx

@@ -0,0 +1,219 @@
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useRef, useState } from 'react';
+
+// ============================================================================
+// TOAST NOTIFICATION TYPES
+// ============================================================================
+export type ToastType = 'success' | 'error' | 'warning' | 'info';
+
+export interface ToastItem {
+  id: string;
+  type: ToastType;
+  title?: string;
+  message: string;
+  durationMs?: number;
+}
+
+export interface ToastContextValue {
+  toast: (options: Omit<ToastItem, 'id'>) => string;
+  success: (message: string, title?: string) => string;
+  error: (message: string, title?: string) => string;
+  warning: (message: string, title?: string) => string;
+  info: (message: string, title?: string) => string;
+  dismiss: (id: string) => void;
+  clear: () => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+let globalToastEmitter: ((item: Omit<ToastItem, 'id'>) => string) | null = null;
+
+// ============================================================================
+// TOAST PROVIDER & FLOATING STACK
+// ============================================================================
+export interface ToastProviderProps {
+  children?: ReactNode;
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+  maxToasts?: number;
+}
+
+export function ToastProvider({ children, position = 'bottom-right', maxToasts = 5 }: ToastProviderProps) {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+  const dismiss = useCallback((id: string) => {
+    const timer = timersRef.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersRef.current.delete(id);
+    }
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  const clear = useCallback(() => {
+    for (const timer of timersRef.current.values()) {
+      clearTimeout(timer);
+    }
+    timersRef.current.clear();
+    setToasts([]);
+  }, []);
+
+  const toast = useCallback(
+    (options: Omit<ToastItem, 'id'>): string => {
+      const id = `toast_${Math.random().toString(36).substring(2, 9)}`;
+      const duration = options.durationMs ?? 4000;
+      const newItem: ToastItem = { ...options, id };
+
+      setToasts((prev) => {
+        const next = [...prev, newItem];
+        if (next.length > maxToasts) {
+          const evicted = next.shift();
+          if (evicted) {
+            const timer = timersRef.current.get(evicted.id);
+            if (timer) clearTimeout(timer);
+            timersRef.current.delete(evicted.id);
+          }
+        }
+        return next;
+      });
+
+      if (duration > 0) {
+        const timer = setTimeout(() => {
+          dismiss(id);
+        }, duration);
+        timersRef.current.set(id, timer);
+      }
+
+      return id;
+    },
+    [dismiss, maxToasts]
+  );
+
+  const success = useCallback((message: string, title?: string) => toast({ type: 'success', message, title }), [toast]);
+  const error = useCallback((message: string, title?: string) => toast({ type: 'error', message, title }), [toast]);
+  const warning = useCallback((message: string, title?: string) => toast({ type: 'warning', message, title }), [toast]);
+  const info = useCallback((message: string, title?: string) => toast({ type: 'info', message, title }), [toast]);
+
+  useEffect(() => {
+    globalToastEmitter = toast;
+    return () => {
+      globalToastEmitter = null;
+      for (const timer of timersRef.current.values()) {
+        clearTimeout(timer);
+      }
+      timersRef.current.clear();
+    };
+  }, [toast]);
+
+  const positionStyles = {
+    'top-right': 'top-4 right-4 items-end',
+    'top-left': 'top-4 left-4 items-start',
+    'bottom-right': 'bottom-4 right-4 items-end',
+    'bottom-left': 'bottom-4 left-4 items-start'
+  };
+
+  const typeConfig: Record<ToastType, { bg: string; border: string; text: string; icon: string }> = {
+    success: {
+      bg: 'bg-emerald-950/90',
+      border: 'border-emerald-800',
+      text: 'text-emerald-300',
+      icon: '✓'
+    },
+    error: {
+      bg: 'bg-rose-950/90',
+      border: 'border-rose-800',
+      text: 'text-rose-300',
+      icon: '✕'
+    },
+    warning: {
+      bg: 'bg-amber-950/90',
+      border: 'border-amber-800',
+      text: 'text-amber-300',
+      icon: '⚠'
+    },
+    info: {
+      bg: 'bg-sky-950/90',
+      border: 'border-sky-800',
+      text: 'text-sky-300',
+      icon: 'ℹ'
+    }
+  };
+
+  return (
+    <ToastContext.Provider value={{ toast, success, error, warning, info, dismiss, clear }}>
+      {children}
+      <div
+        aria-live="polite"
+        className={`fixed z-50 flex flex-col gap-2 max-w-sm w-full pointer-events-none p-4 ${positionStyles[position]}`}
+      >
+        {toasts.map((item) => {
+          const conf = typeConfig[item.type] || typeConfig.info;
+          return (
+            <div
+              key={item.id}
+              role="alert"
+              className={`pointer-events-auto flex items-start gap-3 p-4 rounded-xl border backdrop-blur-md shadow-2xl transition-all duration-200 transform translate-y-0 text-xs w-full ${conf.bg} ${conf.border}`}
+            >
+              <span
+                className={`h-5 w-5 rounded-full flex items-center justify-center font-bold text-xs shrink-0 ${conf.text} bg-slate-900/60 border ${conf.border}`}
+              >
+                {conf.icon}
+              </span>
+              <div className="flex-1 min-w-0">
+                {item.title && <h5 className={`font-bold mb-0.5 ${conf.text}`}>{item.title}</h5>}
+                <p className="text-slate-200 leading-relaxed break-words">{item.message}</p>
+              </div>
+              <button
+                type="button"
+                onClick={() => dismiss(item.id)}
+                aria-label="Fechar notificação"
+                className="text-slate-400 hover:text-white transition-colors text-sm font-mono shrink-0 ml-1 p-0.5"
+              >
+                ✕
+              </button>
+            </div>
+          );
+        })}
+      </div>
+    </ToastContext.Provider>
+  );
+}
+
+// ============================================================================
+// HOOK & IMPERATIVE API
+// ============================================================================
+export function useToast(): ToastContextValue {
+  const ctx = useContext(ToastContext);
+  if (!ctx) {
+    // Fallback gracioso caso chamado fora do provider ou no server
+    return {
+      toast: (opts) => {
+        if (globalToastEmitter) return globalToastEmitter(opts);
+        if (typeof console !== 'undefined') console.log(`[Toast ${opts.type}] ${opts.message}`);
+        return 'noop';
+      },
+      success: (msg, title) => {
+        if (globalToastEmitter) return globalToastEmitter({ type: 'success', message: msg, title });
+        if (typeof console !== 'undefined') console.log(`[Toast success] ${msg}`);
+        return 'noop';
+      },
+      error: (msg, title) => {
+        if (globalToastEmitter) return globalToastEmitter({ type: 'error', message: msg, title });
+        if (typeof console !== 'undefined') console.error(`[Toast error] ${msg}`);
+        return 'noop';
+      },
+      warning: (msg, title) => {
+        if (globalToastEmitter) return globalToastEmitter({ type: 'warning', message: msg, title });
+        if (typeof console !== 'undefined') console.warn(`[Toast warning] ${msg}`);
+        return 'noop';
+      },
+      info: (msg, title) => {
+        if (globalToastEmitter) return globalToastEmitter({ type: 'info', message: msg, title });
+        if (typeof console !== 'undefined') console.info(`[Toast info] ${msg}`);
+        return 'noop';
+      },
+      dismiss: () => {},
+      clear: () => {}
+    };
+  }
+  return ctx;
+}

package/src/client/upload.ts

@@ -0,0 +1,153 @@
+import { useCallback, useRef, useState } from 'react';
+import type { Result } from '../core/machine-types';
+
+export interface UseUploadOptions {
+  /** Target upload URL (default: /_synapse/files/general) */
+  url?: string;
+  /** Maximum allowed file size in bytes (default: 50MB) */
+  maxBytes?: number;
+  /** Allowed MIME types (e.g. ['image/png', 'image/jpeg', 'application/pdf']) */
+  allowedTypes?: string[];
+  /** Callback fired as upload progress increments */
+  onProgress?: (percent: number, loaded: number, total: number) => void;
+  /** Callback fired on successful upload completion */
+  onSuccess?: (response: unknown) => void;
+  /** Callback fired on upload failure */
+  onError?: (error: Error) => void;
+}
+
+export interface UseUploadResult {
+  upload: (file: File) => Promise<Result<unknown, string>>;
+  progress: number;
+  loaded: number;
+  total: number;
+  isUploading: boolean;
+  abort: () => void;
+  reset: () => void;
+}
+
+/**
+ * Universal browser hook for client-side file uploads with granular progress events and abort controls.
+ */
+export function useUpload(options: UseUploadOptions = {}): UseUploadResult {
+  const [progress, setProgress] = useState<number>(0);
+  const [loaded, setLoaded] = useState<number>(0);
+  const [total, setTotal] = useState<number>(0);
+  const [isUploading, setIsUploading] = useState<boolean>(false);
+  const xhrRef = useRef<XMLHttpRequest | null>(null);
+
+  const reset = useCallback(() => {
+    if (xhrRef.current) {
+      xhrRef.current.abort();
+      xhrRef.current = null;
+    }
+    setProgress(0);
+    setLoaded(0);
+    setTotal(0);
+    setIsUploading(false);
+  }, []);
+
+  const abort = useCallback(() => {
+    if (xhrRef.current) {
+      xhrRef.current.abort();
+      xhrRef.current = null;
+      setIsUploading(false);
+    }
+  }, []);
+
+  const upload = useCallback(
+    async (file: File): Promise<Result<unknown, string>> => {
+      // 1. Client-Side Pre-Flight Validations
+      if (options.maxBytes && file.size > options.maxBytes) {
+        const err = `Arquivo excede o tamanho máximo permitido (${options.maxBytes} bytes)`;
+        options.onError?.(new Error(err));
+        return { ok: false, error: 'FILE_TOO_LARGE' };
+      }
+
+      if (options.allowedTypes && options.allowedTypes.length > 0) {
+        if (!options.allowedTypes.includes(file.type)) {
+          const err = `Tipo de arquivo "${file.type}" não permitido. Aceitos: ${options.allowedTypes.join(', ')}`;
+          options.onError?.(new Error(err));
+          return { ok: false, error: 'FILE_TYPE_NOT_ALLOWED' };
+        }
+      }
+
+      setIsUploading(true);
+      setProgress(0);
+      setLoaded(0);
+      setTotal(file.size);
+
+      return new Promise((resolve) => {
+        const xhr = new XMLHttpRequest();
+        xhrRef.current = xhr;
+
+        const targetUrl = options.url || '/_synapse/files/general';
+        xhr.open('POST', targetUrl, true);
+        xhr.setRequestHeader('Accept', 'application/json');
+
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable) {
+            const pct = Math.round((e.loaded / e.total) * 100);
+            setProgress(pct);
+            setLoaded(e.loaded);
+            setTotal(e.total);
+            options.onProgress?.(pct, e.loaded, e.total);
+          }
+        };
+
+        xhr.onload = () => {
+          setIsUploading(false);
+          xhrRef.current = null;
+          if (xhr.status >= 200 && xhr.status < 300) {
+            setProgress(100);
+            try {
+              const res = JSON.parse(xhr.responseText);
+              options.onSuccess?.(res);
+              resolve({ ok: true, value: res });
+            } catch {
+              options.onSuccess?.(xhr.responseText);
+              resolve({ ok: true, value: xhr.responseText });
+            }
+          } else {
+            let errorMsg = `Upload falhou com status HTTP ${xhr.status}`;
+            try {
+              const parsed = JSON.parse(xhr.responseText);
+              if (parsed.error) errorMsg = parsed.error;
+            } catch {}
+            options.onError?.(new Error(errorMsg));
+            resolve({ ok: false, error: errorMsg });
+          }
+        };
+
+        xhr.onerror = () => {
+          setIsUploading(false);
+          xhrRef.current = null;
+          const err = new Error('Erro de rede ao enviar arquivo.');
+          options.onError?.(err);
+          resolve({ ok: false, error: 'NETWORK_ERROR' });
+        };
+
+        xhr.onabort = () => {
+          setIsUploading(false);
+          xhrRef.current = null;
+          resolve({ ok: false, error: 'UPLOAD_ABORTED' });
+        };
+
+        const formData = new FormData();
+        formData.append('file', file, file.name);
+        xhr.send(formData);
+      });
+    },
+    [options]
+  );
+
+  return {
+    upload,
+    progress,
+    loaded,
+    total,
+    isUploading,
+    abort,
+    reset
+  };
+}

package/src/client.ts

@@ -23,12 +23,28 @@ export {
   type DataFormProps,
   DataTable,
   type DataTableProps,
+  Drawer,
+  type DrawerProps,
+  DropdownItem,
+  type DropdownItemProps,
+  DropdownMenu,
+  type DropdownMenuProps,
   expandNestedObject,
   type FormField,
   getNestedProperty,
+  Modal,
+  type ModalProps,
   Pagination,
   type PaginationProps,
-  setNestedProperty
+  setNestedProperty,
+  Tab,
+  TabList,
+  type TabListProps,
+  TabPanel,
+  type TabPanelProps,
+  type TabProps,
+  Tabs,
+  type TabsProps
 } from './client/components';
 // Context & SSR data isolation
 export {
@@ -39,13 +55,19 @@ export {
   useSession,
   useSynapseContext
 } from './client/context';
-// Reactive Action & Realtime Subscription Hooks
+export {
+  SliceErrorBoundary,
+  type SliceErrorBoundaryProps
+} from './client/error-boundary';
+// Reactive Action, Routing & Realtime Subscription Hooks
 export {
   type UseActionOptions,
   type UseActionResult,
   type UseSubscriptionOptions,
   type UseSubscriptionResult,
   useAction,
+  useParams,
+  useSearchParams,
   useSubscription
 } from './client/hooks';
 export {
@@ -60,6 +82,19 @@ export {
   type SliceOutletProviderProps
 } from './client/outlet';
 export { SubSlice, type SubSliceProps } from './client/sub-slice';
+export {
+  type ToastContextValue,
+  type ToastItem,
+  ToastProvider,
+  type ToastProviderProps,
+  type ToastType,
+  useToast
+} from './client/toast';
+export {
+  type UseUploadOptions,
+  type UseUploadResult,
+  useUpload
+} from './client/upload';
 export {
   type UseWebSocketOptions,
   type UseWebSocketResult,