@rowakit/table 0.2.2 → 0.3.0

package/README.md

@@ -12,8 +12,12 @@ RowaKit Table is a React table component designed for real-world internal applic
 ✅ **Escape hatch** - `col.custom()` for any rendering need  
 ✅ **Action buttons** - Built-in support for row actions with confirmation  
 ✅ **7 column types** - Text, Date, Boolean, Badge, Number, Actions, Custom  
-✅ **Column modifiers** - Width, align, truncate support (v0.2.0+)  
+✅ **Column modifiers** - Width, align, truncate, minWidth, maxWidth (v0.2.0+)  
 ✅ **Server-side filters** - Type-specific filter UI with auto-generated inputs (v0.2.0+)  
+✅ **Column resizing** - Drag-to-resize handles with constraints (v0.3.0+)  
+✅ **Saved views** - Save/load table state with localStorage persistence (v0.3.0+)  
+✅ **URL state sync** - Share URLs with exact table configuration (v0.3.0+)  
+✅ **Number range filters** - Min/max filtering for numeric columns (v0.3.0+)  
 ✅ **State management** - Automatic loading, error, and empty states  
 ✅ **Smart fetching** - Retry on error, stale request handling
 
@@ -852,6 +856,165 @@ col.actions([
 - Keyboard accessible (Tab to focus, Enter/Space to activate)
 - Actions column is never sortable
 
+---
+
+## Advanced Features (v0.3.0+)
+
+### Column Resizing (C-01)
+
+Enable users to resize columns by dragging the right edge of column headers.
+
+**Basic Usage:**
+
+```typescript
+<RowaKitTable
+  fetcher={fetchData}
+  columns={[
+    col.text('name', { 
+      minWidth: 100,   // Minimum width (default: 80)
+      maxWidth: 400    // Maximum width (optional)
+    }),
+    col.number('price', { 
+      minWidth: 80 
+    })
+  ]}
+  enableColumnResizing={true}  // Enable resize feature
+/>
+```
+
+**Features:**
+- **Auto-width by default** - Columns automatically size based on header text
+- **Drag to resize** - Drag the blue handle on the right edge of column headers
+- **Double-click to auto-fit** - Double-click the resize handle to auto-fit content width (measures visible header + cells)
+- **Min/max constraints** - Enforced in real-time during drag
+- **Smooth performance** - RAF throttling prevents lag during resize
+- **Large hitbox** - 12px wide invisible zone (1px visible line) makes dragging easy
+- **State persistence** - Widths stored in-memory (or persisted via URL sync/saved views)
+
+**Interaction:**
+- **Hover** - Resize handle appears as a blue vertical line
+- **Drag** - Click and drag to resize column width
+- **Double-click** - Auto-fits to content (max 600px by default)
+- Text selection is disabled during drag for smooth UX
+
+### Saved Views + URL State Sync (C-02)
+
+Save and restore table configurations, and share URLs with exact table state.
+
+**Basic Usage:**
+
+```typescript
+<RowaKitTable
+  fetcher={fetchData}
+  columns={columns}
+  syncToUrl={true}        // Sync to URL query string
+  enableSavedViews={true} // Show save/load view buttons
+/>
+```
+
+**Features:**
+
+1. **URL Sync** - Automatically saves table state to URL query parameters:
+   ```
+   ?page=2&pageSize=20&sortField=name&sortDirection=asc&filters=...&columnWidths=...
+   ```
+   - Share URLs to preserve exact table configuration
+   - State automatically restored on page load
+   - Works with browser back/forward buttons
+
+2. **Saved Views** - Save current table state as named presets:
+   ```
+   [Save View] button → Name your view → State saved to localStorage
+   [My View] button → Click to restore saved state
+   × button → Delete saved view
+   [Reset] button → Clear all state
+   ```
+
+**Synced State:**
+- Page number and size
+- Sort field and direction
+- All active filters
+- Column widths (if resizing enabled)
+
+**Example:**
+
+```typescript
+// User filters to "active users" and resizes columns
+// They click "Save View" and name it "Active"
+// Later, they apply different filters
+// They click "Active" button to instantly restore previous state
+
+// Or they copy the URL and send it to a colleague
+// The colleague sees the exact same filters and layout
+```
+
+### Advanced Number Range Filters (C-03)
+
+Number columns support min/max range filtering with optional value transformation.
+
+**Basic Range Filter:**
+
+```typescript
+col.number('price', {
+  label: 'Price',
+  width: 100
+})
+
+// UI shows two inputs: [Min] [Max]
+// User enters: min=100, max=500
+// Backend receives: { op: 'range', value: { from: 100, to: 500 } }
+```
+
+**With Filter Transform:**
+
+```typescript
+col.number('discount', {
+  label: 'Discount %',
+  // Transform percentage input to fraction for backend
+  filterTransform: (percentageInput) => {
+    // User enters "15" (15%)
+    // Backend receives "0.15" (fraction)
+    if (percentageInput > 1) {
+      return percentageInput / 100;
+    }
+    return percentageInput;
+  }
+})
+```
+
+**Features:**
+- Min and max inputs can be filled independently
+- Example: "at least 50" (min only), "up to 100" (max only), or "50-100" (both)
+- Optional `filterTransform` to adapt filter values before sending to server
+- Useful for unit conversion, percentage ↔ decimal, etc.
+
+**Handling Range Filters in Fetcher:**
+
+```typescript
+const fetchProducts: Fetcher<Product> = async (query) => {
+  let filtered = [...allProducts];
+
+  if (query.filters) {
+    for (const [field, filter] of Object.entries(query.filters)) {
+      if (filter?.op === 'range') {
+        const { from, to } = filter.value as { from?: number; to?: number };
+        filtered = filtered.filter(item => {
+          const val = item[field as keyof Product];
+          if (from !== undefined && val < from) return false;
+          if (to !== undefined && val > to) return false;
+          return true;
+        });
+      }
+    }
+  }
+
+  return {
+    items: filtered.slice(0, query.pageSize),
+    total: filtered.length
+  };
+};
+```
+
 ## Examples
 
 ### Basic Table
@@ -1292,7 +1455,7 @@ Full TypeScript support. Your data model drives type checking throughout.
 
 ## Roadmap
 
-**Stage A - MVP 0.1** ✅ Complete (2024-12-31)
+**Stage A - MVP (v0.1)** ✅ Complete (2024-12-31)
 - ✅ A-01: Repo scaffold
 - ✅ A-02: Core types (Fetcher, ColumnDef, ActionDef)
 - ✅ A-03: Column helpers (col.*)
@@ -1304,19 +1467,25 @@ Full TypeScript support. Your data model drives type checking throughout.
 - ✅ A-09: Minimal styling tokens (CSS variables, responsive, className)
 - ✅ A-10: Documentation & examples (4 complete examples, CHANGELOG, CONTRIBUTING)
 
-**Stage B - Production Ready (v0.2.2)** — Production release 2026-01-02
-- Column visibility toggle
-- Bulk actions
-- Search/text filter
-- Export (CSV, Excel)
-- Dense/comfortable view modes
-- Additional column types (badge, number)
-
-**Stage C - Advanced (Demand-Driven)** (Future)
+**Stage B - Production Ready (v0.2.0-0.2.2)** ✅ Complete (2026-01-02)
+- ✅ Badge column type with visual tones (neutral, success, warning, danger)
+- ✅ Number column type with Intl formatting (currency, percentages, decimals)
+- ✅ Server-side header filter UI (type-specific inputs)
+- ✅ Column modifiers (width, align, truncate)
+- ✅ Fixed numeric filter value coercion
+- ✅ Production hardening and comprehensive documentation
+
+**Stage C - Advanced Features (v0.3.0)** ✅ Complete (2026-01-03)
+- ✅ C-01: Column resizing with drag handles (minWidth/maxWidth constraints)
+- ✅ C-02: Saved views with localStorage persistence
+- ✅ C-02: URL state sync (page, pageSize, sort, filters, columnWidths)
+- ✅ C-03: Number range filters with optional filterTransform
+
+**Stage D - Future** (Demand-Driven)
 - Multi-column sorting
-- Advanced filters
-- Column resizing
-- Saved views
+- Row selection + bulk actions
+- Export CSV (server-triggered)
+- Column visibility toggle
 
 ## Changelog
 

package/dist/index.cjs

@@ -169,7 +169,11 @@ function renderCell(column, row, isLoading, setConfirmState) {
       return numValue.toLocaleString();
     }
     case "actions": {
-      return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "rowakit-table-actions", children: column.actions.map((action) => {
+      const columnWithActions = column;
+      if (!Array.isArray(columnWithActions.actions)) {
+        return null;
+      }
+      return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "rowakit-table-actions", children: columnWithActions.actions.map((action) => {
         const isDisabled = isLoading || action.disabled === true || typeof action.disabled === "function" && action.disabled(row);
         const handleClick = () => {
           if (isDisabled || action.loading) {
@@ -213,7 +217,10 @@ function RowaKitTable({
   pageSizeOptions = [10, 20, 50],
   rowKey,
   className = "",
-  enableFilters = false
+  enableFilters = false,
+  enableColumnResizing = false,
+  syncToUrl = false,
+  enableSavedViews = false
 }) {
   const [dataState, setDataState] = react.useState({
     state: "idle",
@@ -225,8 +232,64 @@ function RowaKitTable({
     pageSize: defaultPageSize
   });
   const [filters, setFilters] = react.useState({});
+  const [columnWidths, setColumnWidths] = react.useState({});
+  const resizeRafRef = react.useRef(null);
+  const resizePendingRef = react.useRef(null);
+  const tableRef = react.useRef(null);
+  const [savedViews, setSavedViews] = react.useState([]);
   const [confirmState, setConfirmState] = react.useState(null);
   const requestIdRef = react.useRef(0);
+  react.useEffect(() => {
+    if (!syncToUrl) return;
+    const params = new URLSearchParams();
+    params.set("page", String(query.page));
+    params.set("pageSize", String(query.pageSize));
+    if (query.sort) {
+      params.set("sortField", query.sort.field);
+      params.set("sortDirection", query.sort.direction);
+    }
+    if (query.filters && Object.keys(query.filters).length > 0) {
+      params.set("filters", JSON.stringify(query.filters));
+    }
+    if (enableColumnResizing && Object.keys(columnWidths).length > 0) {
+      params.set("columnWidths", JSON.stringify(columnWidths));
+    }
+    window.history.replaceState(null, "", `?${params.toString()}`);
+  }, [query, columnWidths, syncToUrl, enableColumnResizing]);
+  react.useEffect(() => {
+    if (!syncToUrl) return;
+    const params = new URLSearchParams(window.location.search);
+    const page = parseInt(params.get("page") ?? "1", 10);
+    const pageSize = parseInt(params.get("pageSize") ?? String(defaultPageSize), 10);
+    const sortField = params.get("sortField");
+    const sortDirection = params.get("sortDirection");
+    const filtersStr = params.get("filters");
+    const columnWidthsStr = params.get("columnWidths");
+    const newQuery = {
+      page: Math.max(1, page),
+      pageSize: Math.max(1, pageSize)
+    };
+    if (sortField && sortDirection) {
+      newQuery.sort = { field: sortField, direction: sortDirection };
+    }
+    if (filtersStr) {
+      try {
+        const parsedFilters = JSON.parse(filtersStr);
+        if (parsedFilters && typeof parsedFilters === "object") {
+          setFilters(parsedFilters);
+          newQuery.filters = parsedFilters;
+        }
+      } catch {
+      }
+    }
+    if (enableColumnResizing && columnWidthsStr) {
+      try {
+        setColumnWidths(JSON.parse(columnWidthsStr));
+      } catch {
+      }
+    }
+    setQuery(newQuery);
+  }, [syncToUrl, defaultPageSize, enableColumnResizing]);
   react.useEffect(() => {
     if (!enableFilters) return;
     const activeFilters = {};
@@ -312,10 +375,154 @@ function RowaKitTable({
     }
     return query.sort.direction === "asc" ? " \u2191" : " \u2193";
   };
+  const scheduleColumnWidthUpdate = (colId, width) => {
+    resizePendingRef.current = { colId, width };
+    if (resizeRafRef.current != null) return;
+    resizeRafRef.current = requestAnimationFrame(() => {
+      resizeRafRef.current = null;
+      const pending = resizePendingRef.current;
+      if (!pending) return;
+      handleColumnResize(pending.colId, pending.width);
+    });
+  };
+  const handleColumnResize = (columnId, newWidth) => {
+    const minWidth = columns.find((c) => c.id === columnId)?.minWidth ?? 80;
+    const maxWidth = columns.find((c) => c.id === columnId)?.maxWidth;
+    let finalWidth = Math.max(minWidth, newWidth);
+    if (maxWidth) {
+      finalWidth = Math.min(finalWidth, maxWidth);
+    }
+    setColumnWidths((prev) => ({
+      ...prev,
+      [columnId]: finalWidth
+    }));
+  };
+  const startColumnResize = (e, columnId) => {
+    e.preventDefault();
+    const startX = e.clientX;
+    const th = e.currentTarget.parentElement;
+    let startWidth = columnWidths[columnId] ?? th.offsetWidth;
+    const MIN_DRAG_WIDTH = 80;
+    if (startWidth < MIN_DRAG_WIDTH) {
+      const nextTh = th.nextElementSibling;
+      if (nextTh && nextTh.offsetWidth >= 50) {
+        startWidth = nextTh.offsetWidth;
+      } else {
+        startWidth = 100;
+      }
+    }
+    document.body.classList.add("rowakit-resizing");
+    const handleMouseMove = (moveEvent) => {
+      const delta = moveEvent.clientX - startX;
+      const newWidth = startWidth + delta;
+      scheduleColumnWidthUpdate(columnId, newWidth);
+    };
+    const handleMouseUp = () => {
+      document.removeEventListener("mousemove", handleMouseMove);
+      document.removeEventListener("mouseup", handleMouseUp);
+      document.body.classList.remove("rowakit-resizing");
+    };
+    document.addEventListener("mousemove", handleMouseMove);
+    document.addEventListener("mouseup", handleMouseUp);
+  };
+  const handleColumnResizeDoubleClick = (columnId) => {
+    const tableEl = tableRef.current;
+    if (!tableEl) return;
+    const th = tableEl.querySelector(`th[data-col-id="${columnId}"]`);
+    if (!th) return;
+    const tds = Array.from(tableEl.querySelectorAll(`td[data-col-id="${columnId}"]`));
+    const headerW = th.scrollWidth;
+    const cellsMaxW = tds.reduce((max, td) => Math.max(max, td.scrollWidth), 0);
+    const padding = 24;
+    const raw = Math.max(headerW, cellsMaxW) + padding;
+    const minW = columns.find((c) => c.id === columnId)?.minWidth ?? 80;
+    const maxW = columns.find((c) => c.id === columnId)?.maxWidth ?? 600;
+    const finalW = Math.max(minW, Math.min(raw, maxW));
+    setColumnWidths((prev) => ({ ...prev, [columnId]: finalW }));
+  };
+  const saveCurrentView = (name) => {
+    const viewState = {
+      page: query.page,
+      pageSize: query.pageSize,
+      sort: query.sort,
+      filters: query.filters,
+      columnWidths: enableColumnResizing ? columnWidths : void 0
+    };
+    setSavedViews((prev) => {
+      const filtered = prev.filter((v) => v.name !== name);
+      return [...filtered, { name, state: viewState }];
+    });
+    if (typeof window !== "undefined" && window.localStorage) {
+      try {
+        localStorage.setItem(`rowakit-view-${name}`, JSON.stringify(viewState));
+      } catch {
+      }
+    }
+  };
+  const loadSavedView = (name) => {
+    const view = savedViews.find((v) => v.name === name);
+    if (!view) return;
+    const { state } = view;
+    setQuery({
+      page: state.page,
+      pageSize: state.pageSize,
+      sort: state.sort,
+      filters: state.filters
+    });
+    setFilters(state.filters ?? {});
+    if (state.columnWidths && enableColumnResizing) {
+      setColumnWidths(state.columnWidths);
+    }
+  };
+  const deleteSavedView = (name) => {
+    setSavedViews((prev) => prev.filter((v) => v.name !== name));
+    if (typeof window !== "undefined" && window.localStorage) {
+      try {
+        localStorage.removeItem(`rowakit-view-${name}`);
+      } catch {
+      }
+    }
+  };
+  const resetTableState = () => {
+    setQuery({
+      page: 1,
+      pageSize: defaultPageSize
+    });
+    setFilters({});
+    setColumnWidths({});
+  };
+  const transformFilterValueForColumn = (column, value) => {
+    if (!value || column?.kind !== "number") {
+      return value;
+    }
+    const numberColumn = column;
+    if (!numberColumn.filterTransform) {
+      return value;
+    }
+    if (value.op === "equals" && typeof value.value === "number") {
+      return {
+        ...value,
+        value: numberColumn.filterTransform(value.value)
+      };
+    }
+    if (value.op === "range" && typeof value.value === "object") {
+      const { from, to } = value.value;
+      return {
+        op: "range",
+        value: {
+          from: from !== void 0 && typeof from === "number" ? numberColumn.filterTransform(from) : from,
+          to: to !== void 0 && typeof to === "number" ? numberColumn.filterTransform(to) : to
+        }
+      };
+    }
+    return value;
+  };
   const handleFilterChange = (field, value) => {
+    const column = columns.find((c) => c.id === field);
+    const transformedValue = transformFilterValueForColumn(column, value);
     setFilters((prev) => ({
       ...prev,
-      [field]: value
+      [field]: transformedValue
     }));
   };
   const handleClearFilter = (field) => {
@@ -336,6 +543,52 @@ function RowaKitTable({
   const canGoNext = query.page < totalPages && !isLoading;
   const hasActiveFilters = enableFilters && Object.values(filters).some((v) => v !== void 0);
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: `rowakit-table${className ? ` ${className}` : ""}`, children: [
+    enableSavedViews && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "rowakit-saved-views-group", children: [
+      /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          onClick: () => {
+            const name = typeof window !== "undefined" ? window.prompt("Enter view name:") : null;
+            if (name) {
+              saveCurrentView(name);
+            }
+          },
+          className: "rowakit-saved-view-button",
+          type: "button",
+          children: "Save View"
+        }
+      ),
+      savedViews.map((view) => /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "rowakit-saved-view-item", children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            onClick: () => loadSavedView(view.name),
+            className: "rowakit-saved-view-button",
+            type: "button",
+            children: view.name
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            onClick: () => deleteSavedView(view.name),
+            className: "rowakit-saved-view-button rowakit-saved-view-button-delete",
+            type: "button",
+            title: "Delete this view",
+            children: "\xD7"
+          }
+        )
+      ] }, view.name)),
+      (hasActiveFilters || query.page > 1 || query.sort) && /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          onClick: resetTableState,
+          className: "rowakit-saved-view-button",
+          type: "button",
+          children: "Reset"
+        }
+      )
+    ] }),
     hasActiveFilters && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "rowakit-table-filter-controls", children: /* @__PURE__ */ jsxRuntime.jsx(
       "button",
       {
@@ -345,14 +598,17 @@ function RowaKitTable({
         children: "Clear all filters"
       }
     ) }),
-    /* @__PURE__ */ jsxRuntime.jsxs("table", { children: [
+    /* @__PURE__ */ jsxRuntime.jsxs("table", { ref: tableRef, children: [
       /* @__PURE__ */ jsxRuntime.jsxs("thead", { children: [
         /* @__PURE__ */ jsxRuntime.jsx("tr", { children: columns.map((column) => {
           const isSortable = column.kind !== "actions" && (column.kind === "custom" ? false : column.sortable === true);
           const field = column.kind === "actions" ? "" : column.kind === "custom" ? column.field : column.field;
+          const isResizable = enableColumnResizing && column.kind !== "actions";
+          const actualWidth = columnWidths[column.id] ?? column.width;
           return /* @__PURE__ */ jsxRuntime.jsxs(
             "th",
             {
+              "data-col-id": column.id,
               onClick: isSortable ? () => handleSort(String(field)) : void 0,
               role: isSortable ? "button" : void 0,
               tabIndex: isSortable ? 0 : void 0,
@@ -364,13 +620,23 @@ function RowaKitTable({
               } : void 0,
               "aria-sort": isSortable && query.sort?.field === String(field) ? query.sort.direction === "asc" ? "ascending" : "descending" : void 0,
               style: {
-                width: column.width ? `${column.width}px` : void 0,
-                textAlign: column.align
+                width: actualWidth ? `${actualWidth}px` : void 0,
+                textAlign: column.align,
+                position: isResizable ? "relative" : void 0
               },
-              className: column.truncate ? "rowakit-cell-truncate" : void 0,
+              className: column.truncate && !isResizable ? "rowakit-cell-truncate" : void 0,
               children: [
                 getHeaderLabel(column),
-                isSortable && getSortIndicator(String(field))
+                isSortable && getSortIndicator(String(field)),
+                isResizable && /* @__PURE__ */ jsxRuntime.jsx(
+                  "div",
+                  {
+                    className: "rowakit-column-resize-handle",
+                    onMouseDown: (e) => startColumnResize(e, column.id),
+                    onDoubleClick: () => handleColumnResizeDoubleClick(column.id),
+                    title: "Drag to resize | Double-click to auto-fit content"
+                  }
+                )
               ]
             },
             column.id
@@ -470,6 +736,51 @@ function RowaKitTable({
             ] }) }, column.id);
           }
           const isNumberColumn = column.kind === "number";
+          if (isNumberColumn) {
+            const fromValue = filterValue?.op === "range" ? String(filterValue.value.from ?? "") : filterValue?.op === "equals" && typeof filterValue.value === "number" ? String(filterValue.value) : "";
+            const toValue = filterValue?.op === "range" ? String(filterValue.value.to ?? "") : "";
+            const showRangeUI = !filterValue || filterValue.op === "range";
+            if (showRangeUI) {
+              return /* @__PURE__ */ jsxRuntime.jsx("th", { children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "rowakit-filter-number-range", children: [
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "input",
+                  {
+                    type: "number",
+                    className: "rowakit-filter-input",
+                    placeholder: "Min",
+                    value: fromValue,
+                    onChange: (e) => {
+                      const from = e.target.value ? Number(e.target.value) : void 0;
+                      const to = toValue ? Number(toValue) : void 0;
+                      if (from === void 0 && to === void 0) {
+                        handleClearFilter(field);
+                      } else {
+                        handleFilterChange(field, { op: "range", value: { from, to } });
+                      }
+                    }
+                  }
+                ),
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "input",
+                  {
+                    type: "number",
+                    className: "rowakit-filter-input",
+                    placeholder: "Max",
+                    value: toValue,
+                    onChange: (e) => {
+                      const to = e.target.value ? Number(e.target.value) : void 0;
+                      const from = fromValue ? Number(fromValue) : void 0;
+                      if (from === void 0 && to === void 0) {
+                        handleClearFilter(field);
+                      } else {
+                        handleFilterChange(field, { op: "range", value: { from, to } });
+                      }
+                    }
+                  }
+                )
+              ] }) }, column.id);
+            }
+          }
           return /* @__PURE__ */ jsxRuntime.jsx("th", { children: /* @__PURE__ */ jsxRuntime.jsx(
             "input",
             {
@@ -521,12 +832,14 @@ function RowaKitTable({
               column.kind === "number" ? "rowakit-cell-number" : "",
               column.truncate ? "rowakit-cell-truncate" : ""
             ].filter(Boolean).join(" ") || void 0;
+            const actualWidth = columnWidths[column.id];
             return /* @__PURE__ */ jsxRuntime.jsx(
               "td",
               {
+                "data-col-id": column.id,
                 className: cellClass,
                 style: {
-                  width: column.width ? `${column.width}px` : void 0,
+                  width: actualWidth ? `${actualWidth}px` : void 0,
                   textAlign: column.align || (column.kind === "number" ? "right" : void 0)
                 },
                 children: renderCell(column, row, isLoading, setConfirmState)