@ceedcv-maya/shared-hooks-react 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maya-AQSS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ceedcv-maya/shared-hooks-react",
+  "version": "0.4.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "react-router-dom": "^7.0.0"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "echo \"no tests yet\" && exit 0",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"no linter configured\""
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maya-AQSS/maya_platform.git",
+    "directory": "packages/js/shared-hooks-react"
+  },
+  "publishConfig": { "access": "public" },
+  "description": "Shared React hooks for the Maya ecosystem: useAutoSave, useFilterState.",
+  "sideEffects": false,
+  "files": ["src", "LICENSE", "tsconfig.json"]
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { useAutoSave, type SaveStatus, type UseAutoSaveResult } from './useAutoSave';
+export { useFilterState, type FilterRecord, type UseFilterStateResult } from './useFilterState';

package/src/useAutoSave.ts

@@ -0,0 +1,77 @@
+import { useCallback, useRef, useState } from 'react';
+
+export type SaveStatus = 'idle' | 'saving' | 'saved' | 'error';
+
+export interface UseAutoSaveResult {
+  isSaving: boolean;
+  saveStatus: SaveStatus;
+  lastSaved: Date | null;
+  triggerSave: () => void;
+  forceSave: () => Promise<void>;
+}
+
+/**
+ * Hook de autoguardado con debounce unificado.
+ * Reutilizable en WizardStep2Blocks, TemplateEditor y DocumentWizard.
+ *
+ * @param saveFn  Función async que realiza el guardado.
+ * @param delay   Milisegundos de debounce (por defecto 1500ms).
+ */
+export function useAutoSave(
+  saveFn: () => Promise<void>,
+  delay = 1500,
+): UseAutoSaveResult {
+  const [saveStatus, setSaveStatus] = useState<SaveStatus>('idle');
+  const [lastSaved, setLastSaved] = useState<Date | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const savedClearRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Always call the latest version of saveFn
+  const saveFnRef = useRef(saveFn);
+  saveFnRef.current = saveFn;
+
+  const executeSave = useCallback(async () => {
+    setSaveStatus('saving');
+    try {
+      await saveFnRef.current();
+      setLastSaved(new Date());
+      setSaveStatus('saved');
+      if (savedClearRef.current) clearTimeout(savedClearRef.current);
+      savedClearRef.current = setTimeout(() => setSaveStatus('idle'), 3000);
+    } catch (error) {
+      setSaveStatus('error');
+      throw error;
+    }
+  }, []);
+
+  /** Reinicia el debounce cada vez que se llama. */
+  const triggerSave = useCallback((): Promise<void> => {
+    return new Promise((resolve, reject) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+
+      setSaveStatus('idle');
+
+      timerRef.current = setTimeout(async () => {
+        try {
+          await executeSave();
+          resolve();
+        } catch (error) {
+          reject(error);
+        }
+      }, delay);
+    });
+  }, [delay, executeSave]);
+
+  /** Ejecuta el guardado inmediatamente, cancelando el debounce pendiente. */
+  const forceSave = useCallback(async () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    await executeSave();
+  }, [executeSave]);
+
+  return {
+    isSaving: saveStatus === 'saving',
+    saveStatus,
+    lastSaved,
+    triggerSave,
+    forceSave,
+  };
+}

package/src/useFilterState.ts

@@ -0,0 +1,76 @@
+import { useCallback, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export type FilterRecord = Record<string, string | undefined>;
+
+export interface UseFilterStateResult<T extends FilterRecord> {
+  filters: T;
+  setFilter: (key: keyof T, value: string | undefined) => void;
+  setFilters: (patch: Partial<T>) => void;
+  resetFilters: () => void;
+}
+
+/**
+ * URL-backed filter state. Stores all filter values as URL query params.
+ * Changing any filter resets page to 1 automatically.
+ *
+ * Usage:
+ *   const { filters, setFilter } = useFilterState({ search: '', status: '' });
+ */
+export function useFilterState<T extends FilterRecord>(
+  defaults: T,
+): UseFilterStateResult<T> {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const filters = useMemo((): T => {
+    const result = { ...defaults } as T;
+    for (const key of Object.keys(defaults) as Array<keyof T & string>) {
+      const value = searchParams.get(key);
+      if (value !== null) {
+        (result as FilterRecord)[key] = value;
+      }
+    }
+    return result;
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [searchParams]);
+
+  const setFilter = useCallback(
+    (key: keyof T, value: string | undefined): void => {
+      setSearchParams((prev) => {
+        const next = new URLSearchParams(prev);
+        if (value === undefined || value === '') {
+          next.delete(key as string);
+        } else {
+          next.set(key as string, value);
+        }
+        next.delete('page');
+        return next;
+      }, { replace: true });
+    },
+    [setSearchParams],
+  );
+
+  const setFilters = useCallback(
+    (patch: Partial<T>): void => {
+      setSearchParams((prev) => {
+        const next = new URLSearchParams(prev);
+        for (const [k, v] of Object.entries(patch)) {
+          if (v === undefined || v === '') {
+            next.delete(k);
+          } else {
+            next.set(k, v as string);
+          }
+        }
+        next.delete('page');
+        return next;
+      }, { replace: true });
+    },
+    [setSearchParams],
+  );
+
+  const resetFilters = useCallback((): void => {
+    setSearchParams(new URLSearchParams(), { replace: true });
+  }, [setSearchParams]);
+
+  return { filters, setFilter, setFilters, resetFilters };
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}