@multiplatform.one/table 6.0.0

package/src/utils/urlStateUtils.spec.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from "vitest";
+import type { TableFilter } from "../types";
+import { serializeTableState, deserializeTableState, validateUrlState } from "./urlStateUtils";
+
+const mkFilter = (id: string, value: string): TableFilter => ({
+  id,
+  columnId: id,
+  value: { operator: "is", value },
+});
+
+describe("serializeTableState", () => {
+  it("serializes pagination (1-based page)", () => {
+    const result = serializeTableState({
+      pagination: { pageIndex: 2, pageSize: 25 },
+    });
+    expect(result.page).toBe("3");
+    expect(result.pageSize).toBe("25");
+  });
+
+  it("serializes sorting", () => {
+    const result = serializeTableState({
+      sorting: [
+        { id: "name", desc: false },
+        { id: "date", desc: true },
+      ],
+    });
+    expect(result.sort).toBe("name:asc,date:desc");
+  });
+
+  it("serializes filters as base64 JSON", () => {
+    const filters = [mkFilter("status", "active")];
+    const result = serializeTableState({ filters });
+    expect(JSON.parse(atob(result.filters))).toEqual(filters);
+  });
+
+  it("serializes global filter as search", () => {
+    const result = serializeTableState({ globalFilter: "hello" });
+    expect(result.search).toBe("hello");
+  });
+
+  it("serializes active view", () => {
+    const result = serializeTableState({ activeViewId: "view-1" });
+    expect(result.view).toBe("view-1");
+  });
+
+  it("returns empty object for empty state", () => {
+    expect(serializeTableState({})).toEqual({});
+  });
+
+  it("omits empty sorting array", () => {
+    const result = serializeTableState({ sorting: [] });
+    expect(result.sort).toBeUndefined();
+  });
+
+  it("omits empty filters array", () => {
+    const result = serializeTableState({ filters: [] });
+    expect(result.filters).toBeUndefined();
+  });
+});
+
+describe("deserializeTableState", () => {
+  it("deserializes pagination (converts to 0-based)", () => {
+    const result = deserializeTableState({ page: "3", pageSize: "25" });
+    expect(result.pagination).toEqual({ pageIndex: 2, pageSize: 25 });
+  });
+
+  it("defaults page size to 10 when not provided", () => {
+    const result = deserializeTableState({ page: "1" });
+    expect(result.pagination).toEqual({ pageIndex: 0, pageSize: 10 });
+  });
+
+  it("deserializes sorting", () => {
+    const result = deserializeTableState({ sort: "name:asc,date:desc" });
+    expect(result.sorting).toEqual([
+      { id: "name", desc: false },
+      { id: "date", desc: true },
+    ]);
+  });
+
+  it("deserializes filters from base64", () => {
+    const filters = [mkFilter("status", "active")];
+    const result = deserializeTableState({
+      filters: btoa(JSON.stringify(filters)),
+    });
+    expect(result.filters).toEqual(filters);
+  });
+
+  it("deserializes search", () => {
+    const result = deserializeTableState({ search: "query" });
+    expect(result.globalFilter).toBe("query");
+  });
+
+  it("deserializes active view", () => {
+    const result = deserializeTableState({ view: "v2" });
+    expect(result.activeViewId).toBe("v2");
+  });
+
+  it("returns empty state for empty input", () => {
+    expect(deserializeTableState({})).toEqual({});
+  });
+
+  it("handles invalid page number gracefully", () => {
+    const result = deserializeTableState({ page: "abc" });
+    expect(result.pagination).toBeUndefined();
+  });
+
+  it("handles invalid filters gracefully", () => {
+    const result = deserializeTableState({ filters: "not-base64!" });
+    expect(result.filters).toBeUndefined();
+  });
+});
+
+describe("serializeTableState + deserializeTableState roundtrip", () => {
+  it("roundtrips pagination", () => {
+    const original = { pagination: { pageIndex: 4, pageSize: 50 } };
+    const serialized = serializeTableState(original);
+    const deserialized = deserializeTableState(serialized);
+    expect(deserialized.pagination).toEqual(original.pagination);
+  });
+
+  it("roundtrips sorting", () => {
+    const original = {
+      sorting: [
+        { id: "col1", desc: true },
+        { id: "col2", desc: false },
+      ],
+    };
+    const serialized = serializeTableState(original);
+    const deserialized = deserializeTableState(serialized);
+    expect(deserialized.sorting).toEqual(original.sorting);
+  });
+
+  it("roundtrips filters", () => {
+    const original = {
+      filters: [mkFilter("status", "active"), mkFilter("type", "user")],
+    };
+    const serialized = serializeTableState(original);
+    const deserialized = deserializeTableState(serialized);
+    expect(deserialized.filters).toEqual(original.filters);
+  });
+});
+
+describe("validateUrlState", () => {
+  it("returns valid for empty state", () => {
+    expect(validateUrlState({})).toEqual({ isValid: true, errors: [] });
+  });
+
+  it("validates correct state", () => {
+    const result = validateUrlState({
+      page: "1",
+      pageSize: "10",
+      sort: "name:asc",
+      filters: btoa(JSON.stringify([])),
+    });
+    expect(result.isValid).toBe(true);
+  });
+
+  it("rejects invalid page number", () => {
+    const result = validateUrlState({ page: "abc" });
+    expect(result.isValid).toBe(false);
+    expect(result.errors).toContain("Invalid page number");
+  });
+
+  it("rejects zero page number", () => {
+    const result = validateUrlState({ page: "0" });
+    expect(result.isValid).toBe(false);
+  });
+
+  it("rejects invalid page size", () => {
+    const result = validateUrlState({ pageSize: "-5" });
+    expect(result.isValid).toBe(false);
+    expect(result.errors).toContain("Invalid page size");
+  });
+
+  it("rejects sort without direction", () => {
+    const result = validateUrlState({ sort: "name" });
+    expect(result.isValid).toBe(false);
+    expect(result.errors[0]).toContain("Invalid sort parameter");
+  });
+
+  it("rejects sort with invalid direction", () => {
+    const result = validateUrlState({ sort: "name:up" });
+    expect(result.isValid).toBe(false);
+  });
+
+  it("rejects non-base64 filters", () => {
+    const result = validateUrlState({ filters: "not-base64!" });
+    expect(result.isValid).toBe(false);
+    expect(result.errors).toContain("Invalid filters format");
+  });
+
+  it("rejects non-array filters", () => {
+    const result = validateUrlState({ filters: btoa('{"not":"array"}') });
+    expect(result.isValid).toBe(false);
+    expect(result.errors).toContain("Filters must be an array");
+  });
+});

package/src/utils/urlStateUtils.ts

@@ -0,0 +1,162 @@
+import type { DataTableState, TableFilter, TableSorting } from "../types";
+
+// URL State Serialization
+
+export function serializeTableState(state: Partial<DataTableState>): Record<string, string> {
+  const urlState: Record<string, string> = {};
+
+  // Pagination
+  if (state.pagination) {
+    urlState.page = String(state.pagination.pageIndex + 1); // 1-based for URL
+    urlState.pageSize = String(state.pagination.pageSize);
+  }
+
+  // Sorting
+  if (state.sorting && state.sorting.length > 0) {
+    urlState.sort = state.sorting
+      .map((sort) => `${sort.id}:${sort.desc ? "desc" : "asc"}`)
+      .join(",");
+  }
+
+  // Filters
+  if (state.filters && state.filters.length > 0) {
+    try {
+      urlState.filters = btoa(JSON.stringify(state.filters));
+    } catch (e) {
+      console.warn("Failed to serialize filters for URL:", e);
+    }
+  }
+
+  // Global Filter (Search)
+  if (state.globalFilter) {
+    urlState.search = state.globalFilter;
+  }
+
+  // Active View
+  if (state.activeViewId) {
+    urlState.view = state.activeViewId;
+  }
+
+  return urlState;
+}
+
+// URL State Deserialization
+
+export function deserializeTableState(urlState: Record<string, string>): Partial<DataTableState> {
+  const state: Partial<DataTableState> = {};
+
+  // Pagination
+  if (urlState.page) {
+    const pageIndex = Number.parseInt(urlState.page, 10) - 1; // Convert to 0-based
+    const pageSize = urlState.pageSize ? Number.parseInt(urlState.pageSize, 10) : 10;
+
+    if (!Number.isNaN(pageIndex) && !Number.isNaN(pageSize)) {
+      state.pagination = { pageIndex, pageSize };
+    }
+  }
+
+  // Sorting
+  if (urlState.sort) {
+    try {
+      const sorting: TableSorting[] = urlState.sort
+        .split(",")
+        .map((sortStr) => {
+          const [id, direction] = sortStr.split(":");
+          return {
+            id,
+            desc: direction === "desc",
+          };
+        })
+        .filter((sort) => sort.id); // Filter out invalid entries
+
+      if (sorting.length > 0) {
+        state.sorting = sorting;
+      }
+    } catch (error) {
+      console.warn("Failed to deserialize sorting from URL:", error);
+    }
+  }
+
+  // Filters
+  if (urlState.filters) {
+    try {
+      const filters: TableFilter[] = JSON.parse(atob(urlState.filters));
+      if (Array.isArray(filters)) {
+        state.filters = filters;
+      }
+    } catch (error) {
+      console.warn("Failed to deserialize filters from URL:", error);
+    }
+  }
+
+  // Global Filter (Search)
+  if (urlState.search) {
+    state.globalFilter = urlState.search;
+  }
+
+  // Active View
+  if (urlState.view) {
+    state.activeViewId = urlState.view;
+  }
+
+  return state;
+}
+
+// URL State Validation
+
+export function validateUrlState(urlState: Record<string, string>): {
+  isValid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  // Validate pagination
+  if (urlState.page) {
+    const pageNum = Number.parseInt(urlState.page, 10);
+    if (Number.isNaN(pageNum) || pageNum < 1) {
+      errors.push("Invalid page number");
+    }
+  }
+
+  if (urlState.pageSize) {
+    const pageSizeNum = Number.parseInt(urlState.pageSize, 10);
+    if (Number.isNaN(pageSizeNum) || pageSizeNum < 1) {
+      errors.push("Invalid page size");
+    }
+  }
+
+  // Validate sorting
+  if (urlState.sort) {
+    try {
+      const sortParts = urlState.sort.split(",");
+      for (const sortPart of sortParts) {
+        const [id, direction] = sortPart.split(":");
+        if (!id || !["asc", "desc"].includes(direction)) {
+          errors.push(`Invalid sort parameter: ${sortPart}`);
+          break;
+        }
+      }
+    } catch {
+      errors.push("Invalid sort format");
+    }
+  }
+
+  // Validate filters (basic structure check)
+  if (urlState.filters) {
+    try {
+      const filters = JSON.parse(atob(urlState.filters));
+      if (!Array.isArray(filters)) {
+        errors.push("Filters must be an array");
+      }
+    } catch {
+      errors.push("Invalid filters format");
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+}
+
+// URL State Compression/Decompression