@perch33/react-usefilter-hook 1.0.0

package/LICENCE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Percy Saul Rondan Chuzon
+
+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/README.md

@@ -0,0 +1,164 @@
+# @perch733/react-usefilter-hook
+
+A lightweight and reusable React hook for filtering lists with accent normalization, punctuation removal, and TypeScript support.  
+Ideal for search bars, dynamic lists, admin dashboards, e-commerce filters, etc.
+
+---
+
+## 🔥 Features
+
+- 🔠 Removes accents (á → a)
+- ✂️ Removes punctuation and special characters
+- 🔎 Case-insensitive search
+- ⚛️ Fully typed with TypeScript
+- 🔁 Auto-updates when `data` changes
+- 🔧 Accepts custom error component
+- 🧩 Framework-agnostic, works in any React project
+
+---
+
+## 📦 Installation
+
+```sh
+npm install @perch733/react-usefilter-hook
+```
+
+or
+
+```sh
+yarn add @perch733/react-usefilter-hook
+
+```
+
+## 🚀 Usage Example (Basic)
+
+```tsx
+import { useFilter } from "@perch733/react-usefilter-hook";
+
+const products = [
+  { title: "Cámara Fotográfica" },
+  { title: "Microfono" },
+  { title: "Cable HDMI" },
+];
+
+export default function App() {
+  const { filterText, filteredData, handleFilterChange } = useFilter(
+    products,
+    "title",
+    <p>No results found</p>
+  );
+
+  return (
+    <div>
+      <input
+        type="search"
+        placeholder="Search..."
+        value={filterText}
+        onChange={handleFilterChange}
+      />
+
+      <ul>
+        {filteredData.map((p, i) => (
+          <li key={i}>{p.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## 🎯 Advanced Example
+
+```tsx
+const { filterText, filteredData, error, handleFilterChange } = useFilter(
+  users,
+  "name",
+  <div style={{ color: "red" }}>No users found</div>
+);
+
+return (
+  <>
+    <input
+      type="text"
+      placeholder="Search users"
+      value={filterText}
+      onChange={handleFilterChange}
+    />
+
+    {filteredData.length === 0
+      ? error
+      : filteredData.map((u) => <p key={u.id}>{u.name}</p>)}
+  </>
+);
+```
+
+## 🧠 API Reference
+
+```tsx
+useFilter<T>(data, key, errorComponent);
+```
+
+| Param            | Type              | Description                       |
+| ---------------- | ----------------- | --------------------------------- |
+| `data`           | `T[]`             | Array of objects to filter        |
+| `key`            | `keyof T`         | Object field used for filtering   |
+| `errorComponent` | `React.ReactNode` | Element displayed when no matches |
+
+## Returns
+
+| Property             | Type                                 | Description                           |
+| -------------------- | ------------------------------------ | ------------------------------------- |
+| `filterText`         | `string`                             | Current normalized search text        |
+| `filteredData`       | `T[]`                                | List filtered according to user input |
+| `error`              | `React.ReactNode \| null`            | Error component if no matches         |
+| `handleFilterChange` | `(e: ChangeEvent<HTMLInputElement>)` | Input handler                         |
+
+### ⚙️ How filtering works
+
+- This hook automatically:
+
+- Converts text to lowercase
+
+- Removes accents (áéíóú → aeiou)
+
+- Removes punctuation and special characters
+
+- Performs a normalized comparison
+
+- Filters in real time as the user types
+
+### 💡 When to use this hook?
+
+- Product search inputs
+
+- Admin panel filters
+
+- Searchable dropdowns
+
+- User lists
+
+- Blog post search
+
+- Table filtering
+
+- Autocomplete components
+
+## 📁 Project Structure
+
+Your installation will contain:
+
+```
+
+dist/
+  ├─ cjs/
+  ├─ esm/
+  ├─ types/
+src/
+README.md
+```
+
+## 👤 Author / Autor
+
+**Percy Chuzon**
+📧 [contacto@percychuzon.com](mailto:contacto@percychuzon.com)
+🌐 [https://wwww.percychuzon.com](https://www.percychuzon.com)

package/dist/cjs/index.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFilter = void 0;
+const react_1 = require("react");
+/**
+ * 🔠 Normaliza texto para facilitar búsquedas:
+ * - Convierte a minúsculas
+ * - Elimina tildes (á → a)
+ * - Elimina signos de puntuación
+ * - Quita espacios sobrantes
+ */
+/** 🔠 Elimina tildes, signos, y pasa todo a minúsculas */
+function normalizarTexto(texto) {
+    return texto
+        .normalize("NFD") // separa letras con tildes en componentes
+        .replace(/[\u0300-\u036f]/g, "") // elimina los diacríticos (tildes)
+        .replace(/[.,/#!$%^&*;:{}=\-_`~()¿?¡!]/g, "") // elimina signos
+        .toLowerCase()
+        .trim();
+}
+const useFilter = (data, key, errorComponent) => {
+    const [filterText, setFilterText] = (0, react_1.useState)("");
+    const [filteredData, setFilteredData] = (0, react_1.useState)(data);
+    const [error, setError] = (0, react_1.useState)(null);
+    /** Maneja el texto que escribe el usuario en el input */
+    const handleFilterChange = (e) => {
+        const searchText = normalizarTexto(e.target.value);
+        setFilterText(searchText);
+    };
+    /** Filtra la lista cada vez que cambia el texto o los datos */
+    (0, react_1.useEffect)(() => {
+        const filteredItems = data.filter((item) => {
+            const valorCampo = String(item[key]);
+            return normalizarTexto(valorCampo).includes(filterText);
+        });
+        setFilteredData(filteredItems);
+        if (filteredItems.length === 0 && filterText !== "") {
+            setError(errorComponent);
+        }
+        else {
+            setError(null);
+        }
+    }, [data, filterText, key]);
+    return {
+        filterText,
+        filteredData,
+        error,
+        handleFilterChange,
+    };
+};
+exports.useFilter = useFilter;

package/dist/cjs/index.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.useFilter=void 0;const react_1=require("react");function normalizarTexto(e){return e.normalize("NFD").replace(/[\u0300-\u036f]/g,"").replace(/[.,/#!$%^&*;:{}=\-_`~()¿?¡!]/g,"").toLowerCase().trim()}const useFilter=(e,t,r)=>{const[a,l]=(0,react_1.useState)(""),[o,n]=(0,react_1.useState)(e),[s,u]=(0,react_1.useState)(null);return(0,react_1.useEffect)(()=>{const l=e.filter(e=>normalizarTexto(String(e[t])).includes(a));n(l),0===l.length&&""!==a?u(r):u(null)},[e,a,t]),{filterText:a,filteredData:o,error:s,handleFilterChange:e=>{const t=normalizarTexto(e.target.value);l(t)}}};exports.useFilter=useFilter;

package/dist/esm/index.js

@@ -0,0 +1,47 @@
+import { useState, useEffect } from "react";
+/**
+ * 🔠 Normaliza texto para facilitar búsquedas:
+ * - Convierte a minúsculas
+ * - Elimina tildes (á → a)
+ * - Elimina signos de puntuación
+ * - Quita espacios sobrantes
+ */
+/** 🔠 Elimina tildes, signos, y pasa todo a minúsculas */
+function normalizarTexto(texto) {
+    return texto
+        .normalize("NFD") // separa letras con tildes en componentes
+        .replace(/[\u0300-\u036f]/g, "") // elimina los diacríticos (tildes)
+        .replace(/[.,/#!$%^&*;:{}=\-_`~()¿?¡!]/g, "") // elimina signos
+        .toLowerCase()
+        .trim();
+}
+export const useFilter = (data, key, errorComponent) => {
+    const [filterText, setFilterText] = useState("");
+    const [filteredData, setFilteredData] = useState(data);
+    const [error, setError] = useState(null);
+    /** Maneja el texto que escribe el usuario en el input */
+    const handleFilterChange = (e) => {
+        const searchText = normalizarTexto(e.target.value);
+        setFilterText(searchText);
+    };
+    /** Filtra la lista cada vez que cambia el texto o los datos */
+    useEffect(() => {
+        const filteredItems = data.filter((item) => {
+            const valorCampo = String(item[key]);
+            return normalizarTexto(valorCampo).includes(filterText);
+        });
+        setFilteredData(filteredItems);
+        if (filteredItems.length === 0 && filterText !== "") {
+            setError(errorComponent);
+        }
+        else {
+            setError(null);
+        }
+    }, [data, filterText, key]);
+    return {
+        filterText,
+        filteredData,
+        error,
+        handleFilterChange,
+    };
+};

package/dist/esm/index.min.js

@@ -0,0 +1 @@
+import{useState,useEffect}from"react";function normalizarTexto(e){return e.normalize("NFD").replace(/[\u0300-\u036f]/g,"").replace(/[.,/#!$%^&*;:{}=\-_`~()¿?¡!]/g,"").toLowerCase().trim()}export const useFilter=(e,t,r)=>{const[a,l]=useState(""),[n,o]=useState(e),[u,i]=useState(null);return useEffect(()=>{const l=e.filter(e=>normalizarTexto(String(e[t])).includes(a));o(l),0===l.length&&""!==a?i(r):i(null)},[e,a,t]),{filterText:a,filteredData:n,error:u,handleFilterChange:e=>{const t=normalizarTexto(e.target.value);l(t)}}};

package/dist/types/index.d.ts

@@ -0,0 +1,49 @@
+import type { ChangeEvent } from "react";
+/**
+ * ────────────────────────────────────────────────────────────────
+ * 📌 useFilter — Hook reutilizable para filtrar listas de datos
+ * ────────────────────────────────────────────────────────────────
+ *
+ * ✔ Permite filtrar un array (data) según un campo específico (key)
+ * ✔ Devuelve:
+ *    - filterText → texto escrito por el usuario
+ *    - filteredData → lista filtrada
+ *    - error → componente mostrado cuando no hay resultados
+ *    - handleFilterChange → manejador para input de búsqueda
+ *
+ * @template T Tipo genérico del array a filtrar
+ *
+ * @param {T[]} data
+ *        Lista completa de objetos que se desea filtrar
+ *
+ * @param {keyof T} key
+ *        Propiedad del objeto que se usará para filtrar (ej: "title")
+ *
+ * @param {React.ReactNode} errorComponent
+ *        Componente mostrado si no se encuentran resultados
+ *
+ * @returns {{
+ *   filterText: string,
+ *   filteredData: T[],
+ *   error: React.ReactNode,
+ *   handleFilterChange: (e: ChangeEvent<HTMLInputElement>) => void
+ * }}
+ *
+ * @Error
+ *  Se activa cuando:
+ *  - El usuario escribe algo
+ *  - No existen resultados coincidentes
+ *
+ *  Puedes usarlo para mostrar:
+ *  <p>No se encontró nada</p>
+ *
+ * ────────────────────────────────────────────────────────────────
+ */
+type UseFilterReturn<T> = {
+    filterText: string;
+    filteredData: T[];
+    error: React.ReactNode;
+    handleFilterChange: (e: ChangeEvent<HTMLInputElement>) => void;
+};
+export declare const useFilter: <T>(data: T[], key: keyof T, errorComponent: React.ReactNode) => UseFilterReturn<T>;
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@perch33/react-usefilter-hook",
+  "version": "1.0.0",
+  "description": "A lightweight and reusable React hook for filtering lists with accent normalization, punctuation removal and TypeScript support.",
+  "main": "dist/cjs/index.min.js",
+  "module": "dist/esm/index.min.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.min.js",
+      "require": "./dist/cjs/index.min.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/cjs",
+    "dist/esm",
+    "dist/types"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && terser dist/cjs/index.js -o dist/cjs/index.min.js --compress --mangle && terser dist/esm/index.js -o dist/esm/index.min.js --compress --mangle"
+  },
+  "keywords": [
+    "react",
+    "hook",
+    "filter",
+    "usefilter",
+    "search",
+    "list filter",
+    "normalization",
+    "typescript",
+    "frontend",
+    "react hook",
+    "filter hook"
+  ],
+  "author": "Percy Chuzon <contacto@percychuzon.com>",
+  "license": "MIT",
+  "homepage": "https://react-usefilter-hook.percychuzon.com/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/perch733/perch733-react-usefilter-hook.git"
+  },
+  "bugs": {
+    "url": "https://github.com/perch733/perch733-react-usefilter-hook/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.21",
+    "@types/react-dom": "^18.3.7",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "terser": "^5.39.2"
+  }
+}