feat: enhance API response handling and add new components for module management

packages/ui/src/hooks/use-action-with-toast.ts

@@ -0,0 +1,67 @@
+'use client';
+
+import { useAction } from 'next-safe-action/hooks';
+import type { HookSafeActionFn } from 'next-safe-action/hooks';
+
+import { toast } from '../shadcn/sonner';
+
+const DEFAULT_ERROR = 'Ein Fehler ist aufgetreten';
+
+interface UseActionWithToastOptions<TData> {
+  successMessage: string;
+  errorMessage?: string;
+  onSuccess?: (data: TData) => void;
+  onError?: (error: string, data?: TData) => void;
+  showSuccessToast?: boolean;
+}
+
+/**
+ * Wraps next-safe-action's `useAction` with unified toast notifications.
+ *
+ * Handles three cases:
+ * 1. Action succeeds with `{ success: true }` → toast.success
+ * 2. Action returns `{ success: false, error }` → toast.error
+ * 3. Action throws (serverError) → toast.error
+ */
+export function useActionWithToast<
+  TData extends { success: boolean; error?: string; [key: string]: unknown },
+>(
+  action: HookSafeActionFn<any, any, any, TData>,
+  options: UseActionWithToastOptions<TData>,
+) {
+  const {
+    successMessage,
+    errorMessage,
+    onSuccess,
+    onError,
+    showSuccessToast = true,
+  } = options;
+
+  return useAction(action, {
+    onSuccess: ({ data }) => {
+      if (!data) return;
+
+      // Application-level error: action returned { success: false }
+      if (!data.success) {
+        const msg = data.error ?? errorMessage ?? DEFAULT_ERROR;
+        toast.error(msg);
+        onError?.(msg, data);
+        return;
+      }
+
+      if (showSuccessToast) {
+        toast.success(successMessage);
+      }
+
+      onSuccess?.(data);
+    },
+    onError: ({ error }) => {
+      const msg =
+        (error as { serverError?: string }).serverError ??
+        errorMessage ??
+        DEFAULT_ERROR;
+      toast.error(msg);
+      onError?.(msg);
+    },
+  });
+}

packages/ui/src/hooks/use-file-download-action.ts

@@ -0,0 +1,73 @@
+'use client';
+
+import type { HookSafeActionFn } from 'next-safe-action/hooks';
+
+import { useActionWithToast } from './use-action-with-toast';
+
+interface FileDownloadData {
+  success: boolean;
+  error?: string;
+  data?: {
+    content: string;
+    filename: string;
+    mimeType: string;
+  };
+  [key: string]: unknown;
+}
+
+interface UseFileDownloadOptions {
+  successMessage?: string;
+  errorMessage?: string;
+}
+
+function downloadBlob(blob: Blob, filename: string) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+function isBase64(str: string): boolean {
+  // Text content (CSV, XML) won't start with common base64 patterns
+  // Base64 encoded binary content is typically longer and matches the pattern
+  return /^[A-Za-z0-9+/]+=*$/.test(str.slice(0, 100)) && str.length > 200;
+}
+
+/**
+ * Wraps a server action that returns a file download payload.
+ * Automatically creates a blob and triggers download.
+ *
+ * Expects the action to return: { success: true, data: { content, filename, mimeType } }
+ */
+export function useFileDownloadAction(
+  action: HookSafeActionFn<any, any, any, FileDownloadData>,
+  options: UseFileDownloadOptions = {},
+) {
+  return useActionWithToast<FileDownloadData>(action, {
+    successMessage: options.successMessage ?? 'Export heruntergeladen',
+    errorMessage: options.errorMessage ?? 'Export fehlgeschlagen',
+    onSuccess: (data) => {
+      const file = data.data;
+      if (!file?.content) return;
+
+      let blob: Blob;
+
+      if (isBase64(file.content)) {
+        // Binary content (Excel, PDF): decode base64
+        const byteChars = atob(file.content);
+        const byteNums = new Uint8Array(byteChars.length);
+        for (let i = 0; i < byteChars.length; i++) {
+          byteNums[i] = byteChars.charCodeAt(i);
+        }
+        blob = new Blob([byteNums], { type: file.mimeType });
+      } else {
+        // Text content (CSV, XML): use directly
+        blob = new Blob([file.content], { type: file.mimeType });
+      }
+
+      downloadBlob(blob, file.filename);
+    },
+  });
+}

packages/ui/src/makerkit/list-toolbar.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import { useRouter, useSearchParams, usePathname } from 'next/navigation';
+
+import { Search } from 'lucide-react';
+
+import { Button } from '../shadcn/button';
+import { Input } from '../shadcn/input';
+
+interface FilterOption {
+  value: string;
+  label: string;
+}
+
+interface FilterConfig {
+  /** URL param name (e.g. "status") */
+  param: string;
+  /** Display label (e.g. "Status") */
+  label: string;
+  /** Dropdown options including an "all" default */
+  options: FilterOption[];
+}
+
+interface ListToolbarProps {
+  /** Placeholder text for search input */
+  searchPlaceholder?: string;
+  /** URL param name for search (default: "q") */
+  searchParam?: string;
+  /** Filter dropdowns */
+  filters?: FilterConfig[];
+  /** Whether to show search input (default: true) */
+  showSearch?: boolean;
+}
+
+/**
+ * Reusable toolbar for list pages with search and filter dropdowns.
+ * Syncs state with URL search params so server components can read them.
+ * Resets to page 1 on any filter/search change.
+ */
+export function ListToolbar({
+  searchPlaceholder = 'Suchen...',
+  searchParam = 'q',
+  filters = [],
+  showSearch = true,
+}: ListToolbarProps) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  const updateParams = useCallback(
+    (updates: Record<string, string | null>) => {
+      const params = new URLSearchParams(searchParams.toString());
+      params.delete('page');
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === null || value === '') {
+          params.delete(key);
+        } else {
+          params.set(key, value);
+        }
+      }
+      const qs = params.toString();
+      router.push(qs ? `${pathname}?${qs}` : pathname);
+    },
+    [router, pathname, searchParams],
+  );
+
+  const currentSearch = searchParams.get(searchParam) ?? '';
+
+  return (
+    <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+      {showSearch && (
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            const formData = new FormData(e.currentTarget);
+            const value = (formData.get('search') as string) ?? '';
+            updateParams({ [searchParam]: value || null });
+          }}
+          className="flex gap-2"
+        >
+          <Input
+            name="search"
+            type="search"
+            defaultValue={currentSearch}
+            placeholder={searchPlaceholder}
+            className="w-64"
+          />
+          <Button type="submit" variant="outline" size="sm">
+            <Search className="mr-1 h-4 w-4" />
+            Suchen
+          </Button>
+        </form>
+      )}
+
+      {filters.length > 0 && (
+        <div className="flex items-center gap-3">
+          {filters.map((filter) => (
+            <select
+              key={filter.param}
+              value={searchParams.get(filter.param) ?? ''}
+              onChange={(e) =>
+                updateParams({ [filter.param]: e.target.value || null })
+              }
+              className="border-input bg-background flex h-9 rounded-md border px-3 py-1 text-sm shadow-sm"
+            >
+              {filter.options.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}