headless-table-core 0.1.7 → 0.1.8

package/README.md

@@ -1,22 +1,18 @@
-# headless-table-core
+# headless-table-core — How to Use
 
-Simple, headless utilities for building **searchable, sortable, paginated tables**.
-
-No UI.  
-No framework lock-in.  
-Works with Angular, React, Vue, or plain JavaScript.
+This guide shows **practical usage patterns** of `headless-table-core` in real projects.
 
 ---
 
-## Install
+## 1️⃣ Install
 
 ```bash
 npm install headless-table-core
-````
+```
 
 ---
 
-## Import
+## 2️⃣ Import
 
 ```ts
 import {
@@ -29,7 +25,9 @@ import {
 
 ---
 
-## Example data
+## 3️⃣ Prepare your data
+
+Your data can come from **any API** and can be **nested**.
 
 ```ts
 const users = [
@@ -48,80 +46,188 @@ const users = [
 
 ---
 
-## getValue – safe nested access
+## 4️⃣ Display nested values (safe way)
+
+### Problem
+
+Direct access can crash:
+
+```ts
+row.user.profile.name
+```
+
+### Solution
+
+Use `getValue`:
 
 ```ts
-getValue(users[0], "user.name");          // "Ali"
-getValue(users[0], "user.profile.age");  // 28
-getValue(users[0], "user.address.city"); // ""
+getValue(row, "user.name");
+getValue(row, "user.profile.age");
 ```
 
 With fallback:
 
 ```ts
-getValue(users[0], "user.address.city", "N/A");
+getValue(row, "user.address.city", "N/A");
 ```
 
+Use this **in rendering**.
+
 ---
 
-## sortData – sort by column
+## 5️⃣ Search (global search)
+
+### Step 1: Choose searchable fields
 
 ```ts
-sortData(users, "user.name", "asc");
-sortData(users, "user.profile.age", "desc");
+const searchKeys = ["user.name", "email"];
 ```
 
-* Non-mutating
-* Supports nested keys
+### Step 2: Apply search
+
+```ts
+const searchedRows = filterData(users, searchText, searchKeys);
+```
 
 ---
 
-## filterData – global search
+## 6️⃣ Sort (column sorting)
+
+### Sort by text
 
 ```ts
-filterData(users, "ali", ["user.name", "email"]);
+const sortedByName = sortData(searchedRows, "user.name", "asc");
 ```
 
-* Case-insensitive
-* Searches multiple fields
+### Sort by number
+
+```ts
+const sortedByAge = sortData(searchedRows, "user.profile.age", "desc");
+```
 
 ---
 
-## paginate – pagination logic
+## 7️⃣ Paginate (page data)
 
 ```ts
-paginate(users, 1, 10);
+const result = paginate(sortedByAge, page, pageSize);
 ```
 
-Returns:
+Use:
 
 ```ts
-{
-  data: [...],
-  total: number,
-  page: number,
-  limit: number
-}
+result.data   // rows for current page
+result.total  // total rows
 ```
 
 ---
 
-## Recommended usage (real flow)
+## 8️⃣ Full usage flow (MOST IMPORTANT)
+
+This is the **correct order** and **most common usage**.
 
 ```ts
 let rows = users;
 
-rows = filterData(rows, searchText, ["user.name", "email"]);
+// 1. Search
+rows = filterData(rows, searchText, [
+  "user.name",
+  "email"
+]);
+
+// 2. Sort
 rows = sortData(rows, sortKey, sortOrder);
+
+// 3. Paginate
 const result = paginate(rows, page, limit);
+```
+
+You render:
+
+```ts
+result.data
+```
+
+---
+
+## 9️⃣ Example: Plain JavaScript table
+
+```ts
+const searchText = "ali";
+const sortKey = "user.name";
+const sortOrder = "asc";
+const page = 1;
+const limit = 10;
+
+let rows = users;
+
+rows = filterData(rows, searchText, ["user.name", "email"]);
+rows = sortData(rows, sortKey, sortOrder);
+const table = paginate(rows, page, limit);
+
+console.log(table.data);
+```
+
+---
+
+## 🔟 Example: Angular component
+
+```ts
+this.rows = paginate(
+  sortData(
+    filterData(this.users, this.searchText, ["user.name", "email"]),
+    this.sortKey,
+    this.sortOrder
+  ),
+  this.page,
+  10
+).data;
+```
+
+---
 
-// render result.data
+## 1️⃣1️⃣ Example: React component
+
+```ts
+const filtered = filterData(data, search, ["user.name", "email"]);
+const sorted = sortData(filtered, sortKey, order);
+const pageData = paginate(sorted, page, 10).data;
 ```
 
 ---
 
-## Notes
+## 1️⃣2️⃣ Common mistakes (avoid these)
+
+❌ Sorting before filtering
+❌ Mutating original array
+❌ Expecting UI components
+❌ Passing wrong nested keys
+
+---
+
+## 1️⃣3️⃣ When to use this library
+
+Use `headless-table-core` when:
+
+* You have more than one table
+* API responses are nested
+* You want consistent behavior
+* You want framework-agnostic logic
+
+---
+
+## 1️⃣4️⃣ When NOT to use it
+
+* One-off small table
+* No search/sort/pagination needed
+
+---
+
+## Summary (TL;DR)
+
+1. Install
+2. Import
+3. Filter → Sort → Paginate
+4. Render result.data
 
-* This library handles **logic only**
-* You control UI and rendering
-* Original data is never mutated
+That’s it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "headless-table-core",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Headless utilities for building sortable, searchable tables",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",