@svadmin/core 0.0.6 → 0.4.1

package/src/data-transfer.ts

@@ -1,108 +1,186 @@
-// Data transfer utilities — CSV export/import
-
-import { getDataProvider } from './context';
-import type { GetListResult } from './types';
+import { getDataProviderForResource } from './context.svelte';
+import { useParsed } from './useParsed';
+import type { GetListResult, Sort, Filter, BaseRecord } from './types';
+
+export interface UseExportOptions<TData extends BaseRecord = BaseRecord> {
+  resource?: string;
+  mapData?: (item: TData) => Record<string, unknown>;
+  sorters?: Sort[];
+  filters?: Filter[];
+  maxItemCount?: number;
+  pageSize?: number;
+  download?: boolean;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+  onError?: (error: Error) => void;
+}
 
 /**
- * useExport — export all records from a resource as CSV download
+ * useExport — export records from a resource as CSV download
+ * Supports mapData, sorters, filters, maxItemCount, pageSize
  */
-export function useExport(resource: string) {
-  let isExporting = $state(false);
+export function useExport<TData extends BaseRecord = BaseRecord>(options: UseExportOptions<TData> = {}) {
+  const parsed = useParsed();
+  const resource = options.resource ?? parsed.resource ?? '';
+  let isLoading = $state(false);
 
-  async function exportCSV(opts?: { filename?: string; fields?: string[] }) {
-    const provider = getDataProvider();
-    isExporting = true;
+  async function triggerExport() {
+    const provider = getDataProviderForResource(resource, options.dataProviderName);
+    isLoading = true;
 
     try {
-      // Fetch all records (up to 10000)
-      const result: GetListResult = await provider.getList({
-        resource,
-        pagination: { current: 1, pageSize: 10000 },
-      });
-
-      if (result.data.length === 0) return;
-
-      const records = result.data as Record<string, unknown>[];
-      const fields = opts?.fields ?? Object.keys(records[0]);
-
-      // Build CSV
-      const header = fields.join(',');
-      const rows = records.map(record =>
-        fields.map(f => {
-          const val = record[f];
-          const str = val === null || val === undefined ? '' : String(val);
-          // Escape commas and quotes
-          return str.includes(',') || str.includes('"') || str.includes('\n')
-            ? `"${str.replace(/"/g, '""')}"`
-            : str;
-        }).join(',')
-      );
-
-      const csv = [header, ...rows].join('\n');
-      const blob = new Blob(['\uFEFF' + csv], { type: 'text/csv;charset=utf-8;' });
-      const url = URL.createObjectURL(blob);
-      const a = document.createElement('a');
-      a.href = url;
-      a.download = opts?.filename ?? `${resource}_export.csv`;
-      a.click();
-      URL.revokeObjectURL(url);
+      const batchSize = options.pageSize ?? 20;
+      const maxItems = options.maxItemCount ?? Infinity;
+      let allRecords: TData[] = [];
+      let page = 1;
+
+      while (allRecords.length < maxItems) {
+        const result = await provider.getList<TData>({
+          resource,
+          pagination: { current: page, pageSize: batchSize },
+          sorters: options.sorters,
+          filters: options.filters,
+          meta: options.meta,
+        });
+
+        allRecords = [...allRecords, ...result.data];
+        if (result.data.length < batchSize || allRecords.length >= result.total) break;
+        page++;
+      }
+
+      if (maxItems !== Infinity) allRecords = allRecords.slice(0, maxItems);
+      if (allRecords.length === 0) return allRecords;
+
+      const mapped = options.mapData
+        ? allRecords.map(options.mapData)
+        : allRecords.map(r => r as unknown as Record<string, unknown>);
+
+      if (options.download !== false) {
+        const fields = Object.keys(mapped[0]);
+        const header = fields.join(',');
+        const rows = mapped.map(record =>
+          fields.map(f => {
+            const val = record[f];
+            const str = val === null || val === undefined ? '' : String(val);
+            return str.includes(',') || str.includes('"') || str.includes('\n')
+              ? `"${str.replace(/"/g, '""')}"`
+              : str;
+          }).join(',')
+        );
+
+        const csv = [header, ...rows].join('\n');
+        const blob = new Blob(['\uFEFF' + csv], { type: 'text/csv;charset=utf-8;' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `${resource}_export.csv`;
+        a.click();
+        URL.revokeObjectURL(url);
+      }
+
+      return allRecords;
+    } catch (error) {
+      options.onError?.(error as Error);
+      return [];
     } finally {
-      isExporting = false;
+      isLoading = false;
     }
   }
 
   return {
-    exportCSV,
-    get isExporting() { return isExporting; },
+    triggerExport,
+    get isLoading() { return isLoading; },
   };
 }
 
+export interface UseImportOptions<TData = Record<string, unknown>> {
+  resource?: string;
+  mapData?: (item: Record<string, unknown>) => TData;
+  batchSize?: number;
+  onFinish?: (result: { succeeded: unknown[]; errored: { request: unknown; error: unknown }[] }) => void;
+  onProgress?: (info: { totalAmount: number; processedAmount: number }) => void;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+}
+
 /**
  * useImport — import records from a CSV file
+ * Supports mapData, batchSize, onFinish, onProgress, meta
  */
-export function useImport(resource: string) {
-  let isImporting = $state(false);
-  let importResult = $state<{ success: number; failed: number } | null>(null);
-
-  async function importCSV(file: File): Promise<{ success: number; failed: number }> {
-    const provider = getDataProvider();
-    isImporting = true;
-    let success = 0;
-    let failed = 0;
+export function useImport<TData = Record<string, unknown>>(options: UseImportOptions<TData> = {}) {
+  const parsed = useParsed();
+  const resource = options.resource ?? parsed.resource ?? '';
+  let isLoading = $state(false);
+  let mutationResult = $state<{ succeeded: unknown[]; errored: { request: unknown; error: unknown }[] } | null>(null);
+
+  async function handleChange(info: { file: File }) {
+    const provider = getDataProviderForResource(resource, options.dataProviderName);
+    isLoading = true;
+    const succeeded: unknown[] = [];
+    const errored: { request: unknown; error: unknown }[] = [];
 
     try {
-      const text = await file.text();
+      const text = await info.file.text();
       const lines = text.split('\n').filter(l => l.trim() !== '');
-      if (lines.length < 2) return { success: 0, failed: 0 };
+      if (lines.length < 2) return;
 
       const headers = parseCSVLine(lines[0]);
+      const records: Record<string, unknown>[] = [];
 
       for (let i = 1; i < lines.length; i++) {
         const values = parseCSVLine(lines[i]);
         const record: Record<string, unknown> = {};
-        headers.forEach((h, idx) => {
-          record[h] = values[idx] ?? '';
-        });
+        headers.forEach((h, idx) => { record[h] = values[idx] ?? ''; });
+        records.push(options.mapData ? (options.mapData(record) as unknown as Record<string, unknown>) : record);
+      }
 
-        try {
-          await provider.create({ resource, variables: record });
-          success++;
-        } catch {
-          failed++;
+      const batchSize = options.batchSize ?? 1;
+      let processed = 0;
+
+      if (batchSize === 1) {
+        for (const record of records) {
+          try {
+            const res = await provider.create({ resource, variables: record, meta: options.meta });
+            succeeded.push(res);
+          } catch (error) {
+            errored.push({ request: record, error });
+          }
+          processed++;
+          options.onProgress?.({ totalAmount: records.length, processedAmount: processed });
+        }
+      } else {
+        for (let i = 0; i < records.length; i += batchSize) {
+          const batch = records.slice(i, i + batchSize);
+          try {
+            if (provider.createMany) {
+              const res = await provider.createMany({ resource, variables: batch, meta: options.meta });
+              succeeded.push(res);
+            } else {
+              for (const record of batch) {
+                const res = await provider.create({ resource, variables: record, meta: options.meta });
+                succeeded.push(res);
+              }
+            }
+          } catch (error) {
+            errored.push({ request: batch, error });
+          }
+          processed += batch.length;
+          options.onProgress?.({ totalAmount: records.length, processedAmount: processed });
         }
       }
 
-      importResult = { success, failed };
-      return { success, failed };
+      mutationResult = { succeeded, errored };
+      options.onFinish?.({ succeeded, errored });
     } finally {
-      isImporting = false;
+      isLoading = false;
     }
   }
 
   return {
-    importCSV,
-    get isImporting() { return isImporting; },
-    get importResult() { return importResult; },
+    inputProps: { type: 'file' as const, accept: '.csv' },
+    handleChange,
+    get isLoading() { return isLoading; },
+    get mutationResult() { return mutationResult; },
   };
 }
 

package/src/form-hooks.svelte.ts

@@ -0,0 +1,266 @@
+import { useQueryClient } from '@tanstack/svelte-query';
+import { useParsed } from './useParsed';
+import { getAdminOptions } from './options';
+import { getDataProviderForResource } from './context.svelte';
+import { createQuery, createMutation } from '@tanstack/svelte-query';
+import { toast } from './toast.svelte';
+import { t } from './i18n.svelte';
+import { audit } from './audit';
+import { navigate } from './router';
+import { HttpError } from './types';
+import type { BaseRecord, MutationMode, KnownResources } from './types';
+
+export interface UseFormOptions<TQueryFnData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>, TData extends BaseRecord = TQueryFnData> {
+  resource?: KnownResources;
+  action?: 'create' | 'edit' | 'clone';
+  id?: string | number;
+  redirect?: 'list' | 'edit' | 'show' | false;
+  successNotification?: string | false;
+  errorNotification?: string | false;
+  dataProviderName?: string;
+  onMutationSuccess?: (data: unknown) => void;
+  onMutationError?: (error: Error) => void;
+  meta?: Record<string, unknown>;
+  queryMeta?: Record<string, unknown>;
+  mutationMeta?: Record<string, unknown>;
+  disableServerSideValidation?: boolean;
+  validate?: (values: TVariables) => Record<string, string> | null;
+  autoSave?: {
+    enabled: boolean;
+    debounce?: number;
+    onFinish?: (values: TVariables) => TVariables;
+    invalidateOnUnmount?: boolean;
+    invalidates?: string[];
+  };
+  mutationMode?: MutationMode;
+  undoableTimeout?: number;
+  invalidates?: string[] | false;
+  optimisticUpdateMap?: {
+    list?: boolean | ((previous: unknown, variables: TVariables, id?: string | number) => unknown);
+    detail?: boolean | ((previous: unknown, variables: TVariables, id?: string | number) => unknown);
+  };
+  queryOptions?: { staleTime?: number; enabled?: boolean };
+  createMutationOptions?: Record<string, unknown>;
+  updateMutationOptions?: Record<string, unknown>;
+  warnWhenUnsavedChanges?: boolean;
+}
+
+export type UseFormResult<TQueryFnData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>, TData extends BaseRecord = TQueryFnData> = {
+  readonly query: unknown;
+  readonly mutation: unknown;
+  readonly formLoading: boolean;
+  readonly errors: Record<string, string>;
+  setFieldError: (field: string, message: string) => void;
+  clearErrors: () => void;
+  clearFieldError: (field: string) => void;
+  onFinish: (values: TVariables, finishOptions?: { redirect?: 'list' | 'edit' | 'show' | false }) => Promise<void>;
+  onFinishAutoSave: (values: TVariables) => Promise<void>;
+  triggerAutoSave: (values: TVariables) => void;
+  readonly autoSaveStatus: 'idle' | 'saving' | 'saved' | 'error';
+  readonly resource: string;
+  readonly action: 'create' | 'edit' | 'clone';
+  readonly id: string | number | undefined;
+  setId: (newId: string | number) => void;
+  readonly mutationMode: MutationMode;
+  redirect: (to: 'list' | 'edit' | 'show' | false) => void;
+  readonly autoSaveProps: { status: 'idle' | 'loading' | 'success' | 'error'; data: unknown; error: unknown };
+};
+
+export function useForm<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError = HttpError,
+  TVariables = Record<string, unknown>,
+  TData extends BaseRecord = TQueryFnData
+>(options: UseFormOptions<TQueryFnData, TError, TVariables, TData> = {}): UseFormResult<TQueryFnData, TError, TVariables, TData> {
+  const queryClient = useQueryClient();
+  const parsed = useParsed();
+  const adminOptions = getAdminOptions();
+  
+  const resource = options.resource ?? parsed.resource ?? '';
+  const action = options.action ?? (parsed.action === 'list' ? 'create' : parsed.action as 'create' | 'edit' | 'clone') ?? 'create';
+  let currentId = $state<string | number | undefined>(options.id ?? parsed.id);
+  
+  const {
+    redirect: redirectDefault = 'list',
+    successNotification, errorNotification,
+    onMutationSuccess, onMutationError,
+    meta: hookMeta, queryMeta: hookQueryMeta, mutationMeta: hookMutationMeta,
+    disableServerSideValidation, validate, autoSave,
+    mutationMode = adminOptions.mutationMode ?? 'pessimistic',
+    undoableTimeout = adminOptions.undoableTimeout ?? 5000,
+    dataProviderName, invalidates: invalidateScopes,
+    optimisticUpdateMap,
+    queryOptions,
+  } = options;
+
+  const provider = getDataProviderForResource(resource, dataProviderName);
+  const parsedMeta = typeof window !== 'undefined' ? Object.fromEntries(new URLSearchParams(window.location.search).entries()) : {};
+  const queryMeta = { ...parsedMeta, ...hookMeta, ...hookQueryMeta };
+  const mutationMeta = { ...parsedMeta, ...hookMeta, ...hookMutationMeta };
+
+  function setId(newId: string | number) { currentId = newId; }
+
+  let errors = $state<Record<string, string>>({});
+  function setFieldError(field: string, message: string) { errors = { ...errors, [field]: message }; }
+  function clearErrors() { errors = {}; }
+  function clearFieldError(field: string) { delete errors[field]; }
+
+  function runValidation(values: TVariables): boolean {
+    clearErrors();
+    if (validate) {
+      const result = validate(values);
+      if (result && Object.keys(result).length > 0) {
+        errors = result;
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function handleHttpError(error: Error) {
+    if (error instanceof HttpError && error.errors && !disableServerSideValidation) {
+      for (const [field, messages] of Object.entries(error.errors)) {
+        const msg = Array.isArray(messages) ? messages[0] : messages;
+        setFieldError(field, msg);
+      }
+      if (errorNotification !== false) toast.error(errorNotification || error.message || t('common.operationFailed'));
+    } else {
+      if (errorNotification !== false) toast.error(errorNotification || t('common.operationFailed') + ': ' + error.message);
+    }
+  }
+
+  const query = (action === 'edit' || action === 'clone') && currentId != null
+    ? createQuery(() => ({
+        queryKey: [resource, 'one', currentId],
+        queryFn: async () => {
+          const result = await provider.getOne<TQueryFnData>({ resource, id: currentId!, meta: queryMeta });
+          return result.data;
+        },
+        enabled: (queryOptions?.enabled ?? true) && currentId != null,
+        staleTime: queryOptions?.staleTime,
+      }))
+    : null;
+
+  const createMut = createMutation(() => ({
+    ...options.createMutationOptions,
+    mutationFn: (variables: TVariables) => provider.create<TData, TVariables>({ resource, variables, meta: mutationMeta }),
+    onSuccess: (data: { data: TData }) => {
+      if (invalidateScopes !== false) queryClient.invalidateQueries({ queryKey: [resource] });
+      if (successNotification !== false) toast.success(successNotification || t('common.createSuccess'));
+      audit({ action: 'create', resource, recordId: String(data.data.id) });
+      onMutationSuccess?.(data);
+      if (redirectOverride !== false) doRedirect(redirectOverride ?? redirectDefault);
+    },
+    onError: (error: Error) => { handleHttpError(error); onMutationError?.(error); },
+  }));
+
+  const updateMut = createMutation(() => ({
+    ...options.updateMutationOptions,
+    mutationFn: (variables: TVariables) => provider.update<TData, TVariables>({ resource, id: currentId!, variables, meta: mutationMeta }),
+    onSuccess: (data: { data: TData }) => {
+      if (invalidateScopes !== false) queryClient.invalidateQueries({ queryKey: [resource] });
+      if (successNotification !== false) toast.success(successNotification || t('common.updateSuccess'));
+      audit({ action: 'update', resource, recordId: String(currentId) });
+      onMutationSuccess?.(data);
+      if (redirectOverride !== false) doRedirect(redirectOverride ?? redirectDefault);
+    },
+    onError: (error: Error) => { handleHttpError(error); onMutationError?.(error); },
+  }));
+
+  let redirectOverride: 'list' | 'edit' | 'show' | false | undefined;
+
+  function doRedirect(to: 'list' | 'edit' | 'show' | false) {
+    if (to === 'list') navigate(`/${resource}`);
+    else if (to === 'edit' && currentId) navigate(`/${resource}/edit/${currentId}`);
+    else if (to === 'show' && currentId) navigate(`/${resource}/show/${currentId}`);
+  }
+
+  async function onFinish(values: TVariables, finishOptions?: { redirect?: 'list' | 'edit' | 'show' | false }) {
+    if (!runValidation(values)) { toast.warning(t('validation.required')); return; }
+    redirectOverride = finishOptions?.redirect;
+    if (action === 'create' || action === 'clone') await createMut.mutateAsync(values);
+    else await updateMut.mutateAsync(values);
+  }
+
+  async function onFinishAutoSave(values: TVariables) {
+    if (action === 'create' || action === 'clone') return; // Only autosave on edit
+    redirectOverride = false; // Never redirect on autoSave
+    await updateMut.mutateAsync(values);
+  }
+
+  let autoSaveStatus = $state<'idle' | 'saving' | 'saved' | 'error'>('idle');
+  let autoSaveTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function triggerAutoSave(values: TVariables) {
+    if (!autoSave?.enabled || action === 'create') return;
+    if (autoSaveTimer) clearTimeout(autoSaveTimer);
+
+    autoSaveTimer = setTimeout(async () => {
+      const finalValues = autoSave.onFinish ? autoSave.onFinish(values) : values;
+      autoSaveStatus = 'saving';
+      try {
+        await provider.update<TData, TVariables>({ resource, id: currentId!, variables: finalValues, meta: mutationMeta });
+        const scopes = autoSave.invalidates ?? ['resourceAll'];
+        for (const scope of scopes) {
+          if (scope === 'resourceAll') queryClient.invalidateQueries({ queryKey: [resource] });
+          else if (scope === 'detail' && currentId) queryClient.invalidateQueries({ queryKey: [resource, 'one', currentId] });
+          else if (scope === 'list') queryClient.invalidateQueries({ queryKey: [resource, 'list'] });
+        }
+        autoSaveStatus = 'saved';
+        lastAutoSaveData = undefined; // placeholder for returned data
+        lastAutoSaveError = null;
+        setTimeout(() => { autoSaveStatus = 'idle'; }, 2000);
+      } catch (e) {
+        autoSaveStatus = 'error';
+        lastAutoSaveError = e;
+      }
+    }, autoSave.debounce ?? 1000);
+  }
+
+  let lastAutoSaveData = $state<unknown>(null);
+  let lastAutoSaveError = $state<unknown>(null);
+
+  if (autoSave?.invalidateOnUnmount) {
+    $effect(() => {
+      return () => queryClient.invalidateQueries({ queryKey: [resource] });
+    });
+  }
+
+  // warnWhenUnsavedChanges
+  const shouldWarn = options.warnWhenUnsavedChanges ?? adminOptions.warnWhenUnsavedChanges;
+  if (shouldWarn && typeof window !== 'undefined') {
+    $effect(() => {
+      const handler = (e: BeforeUnloadEvent) => {
+        // Here we'd typically check a dirty state, but useForm itself doesn't track dirty fields.
+        // Usually the form library (svelte-forms etc) handles dirty state.
+        // Assuming we always warn if enabled for now.
+        e.preventDefault();
+        e.returnValue = '';
+      };
+      window.addEventListener('beforeunload', handler);
+      return () => window.removeEventListener('beforeunload', handler);
+    });
+  }
+
+  return {
+    query,
+    get formLoading() { return (query?.isLoading ?? false) || createMut.isPending || updateMut.isPending; },
+    mutation: action === 'edit' ? updateMut : createMut,
+    onFinish,
+    onFinishAutoSave,
+    get errors() { return errors; },
+    setFieldError, clearErrors, clearFieldError,
+    triggerAutoSave,
+    get autoSaveStatus() { return autoSaveStatus; },
+    resource, action,
+    get id() { return currentId; },
+    setId, mutationMode, redirect: doRedirect,
+    get autoSaveProps() {
+      return {
+        status: autoSaveStatus as 'idle' | 'loading' | 'success' | 'error',
+        data: lastAutoSaveData,
+        error: lastAutoSaveError,
+      };
+    },
+  };
+}

package/src/helpers.ts

@@ -0,0 +1,157 @@
+// Refine v5 compatible utility helpers
+
+import type { Filter, Sort, CrudOperator } from './types';
+import { t } from './i18n.svelte';
+import { getTextTransformers } from './options';
+
+// ─── Table Helpers ────────────────────────────────────────────
+
+/**
+ * Get the current filter value for a field from a filter array.
+ * Useful for setting default values in filter inputs.
+ */
+export function getDefaultFilter(
+  columnName: string,
+  filters?: Filter[],
+  operatorType: CrudOperator = 'eq',
+): unknown | undefined {
+  if (!filters) return undefined;
+  const filter = filters.find((f) => {
+    if ('field' in f) {
+      return f.field === columnName && f.operator === operatorType;
+    }
+    return false;
+  });
+  return filter && 'value' in filter ? filter.value : undefined;
+}
+
+/**
+ * Get the current sort order for a field from a sorter array.
+ * Returns 'asc', 'desc', or undefined.
+ */
+export function getDefaultSortOrder(
+  columnName: string,
+  sorters?: Sort[],
+): 'asc' | 'desc' | undefined {
+  if (!sorters) return undefined;
+  const sortItem = sorters.find((item) => item.field === columnName);
+  return sortItem?.order as 'asc' | 'desc' | undefined;
+}
+
+/**
+ * Merge two filter arrays, deduplicating by field+operator.
+ * Filters in `newFilters` take priority over `prevFilters`.
+ * `permanentFilter` items are always preserved.
+ * Filters with undefined values are removed from the result.
+ */
+export function unionFilters(
+  permanentFilter: Filter[],
+  newFilters: Filter[],
+  prevFilters: Filter[] = [],
+): Filter[] {
+  const compareFilters = (a: Filter, b: Filter): boolean => {
+    if ('field' in a && 'field' in b) {
+      return a.field === b.field && a.operator === b.operator;
+    }
+    return false;
+  };
+
+  // Start with previous filters
+  let result = [...prevFilters];
+
+  // Apply new filters (override previous by field+operator)
+  for (const newFilter of newFilters) {
+    const idx = result.findIndex((f) => compareFilters(f, newFilter));
+    if (idx >= 0) {
+      result[idx] = newFilter;
+    } else {
+      result.push(newFilter);
+    }
+  }
+
+  // Ensure permanent filters are always present
+  for (const perm of permanentFilter) {
+    const idx = result.findIndex((f) => compareFilters(f, perm));
+    if (idx >= 0) {
+      result[idx] = perm;
+    } else {
+      result.push(perm);
+    }
+  }
+
+  // Remove filters with undefined values
+  return result.filter((f) => !('value' in f && f.value === undefined));
+}
+
+/**
+ * Merge two sorter arrays, deduplicating by field.
+ * Sorters in `newSorters` take priority.
+ */
+export function unionSorters(
+  permanentSorters: Sort[],
+  newSorters: Sort[],
+): Sort[] {
+  const result = [...newSorters];
+
+  for (const perm of permanentSorters) {
+    if (!result.some((s) => s.field === perm.field)) {
+      result.push(perm);
+    }
+  }
+
+  return result;
+}
+
+// ─── Upload Helpers ───────────────────────────────────────────
+
+/**
+ * Convert a File (or file-like object) to a base64 data URL string.
+ * Useful for image uploads and previews.
+ */
+export function file2Base64(file: File | { uid?: string } & Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.readAsDataURL(file as Blob);
+    reader.addEventListener('load', () => {
+      resolve(reader.result as string);
+    });
+    reader.addEventListener('error', () => {
+      reject(reader.error);
+    });
+  });
+}
+
+// ─── Document Title Helper ────────────────────────────────────
+
+/**
+ * Generate a default document title for a resource page.
+ * e.g., "Edit Post #5 | Admin" or "Posts | Admin"
+ */
+export function generateDefaultDocumentTitle(options?: {
+  resource?: string;
+  action?: string;
+  id?: string | number;
+  suffix?: string;
+}): string {
+  const { resource, action, id, suffix = ' | Admin' } = options ?? {};
+  const transformers = getTextTransformers();
+
+  if (!resource) {
+    return t('documentTitle.default', {}) || `Admin${suffix}`;
+  }
+
+  const resourceLabel = transformers.humanize
+    ? transformers.humanize(resource)
+    : resource.charAt(0).toUpperCase() + resource.slice(1);
+
+  const actionPrefixes: Record<string, string> = {
+    create: `${t('common.create', {}) || 'Create'} `,
+    clone: `#${id ?? ''} ${t('common.clone', {}) || 'Clone'} `,
+    edit: `#${id ?? ''} ${t('common.edit', {}) || 'Edit'} `,
+    show: `#${id ?? ''} ${t('common.detail', {}) || 'Show'} `,
+    list: '',
+  };
+
+  const prefix = action ? (actionPrefixes[action] ?? '') : '';
+  return `${prefix}${resourceLabel}${suffix}`;
+}