@eztrak/shared 0.7.0 → 0.7.2

package/README.md

@@ -8,13 +8,38 @@ Shared utilities, hooks, and UI components for Eztrak applications.
 npm install @eztrak/shared
 ```
 
-Peer dependencies (hooks + `handleApiError` + components):
+Peer dependencies:
 
 ```bash
-npm install react react-dom react-router-dom react-hot-toast sweetalert2
+npm install react react-dom react-router-dom react-hot-toast sweetalert2 react-icons framer-motion
 ```
 
-Your app must render `<Toaster />` from react-hot-toast (e.g. in your root layout).
+Your app must render `<Toaster />` from `react-hot-toast` (e.g. in your root layout).
+
+Import loader styles once if you use the `Loader` component:
+
+```ts
+import "@eztrak/shared/components/loader.css";
+```
+
+`CustomCellEditor` does **not** require `loader.css` — it uses an inline SVG spinner for the save button.
+
+## Development
+
+From the monorepo root:
+
+```bash
+npm run build:shared
+npm run storybook
+```
+
+From `packages/shared`:
+
+```bash
+npm run build
+npm run storybook
+npm run build:storybook
+```
 
 ## Usage
 
@@ -171,6 +196,77 @@ import {
 
 `ResetColumnsButton` shows a SweetAlert2 confirmation before calling `onReset`.
 
+### Components — CustomCellEditor
+
+AG Grid cell editor with inline save/cancel buttons, keyboard shortcuts (Enter to save, Escape to cancel), and toast feedback. Implements the AG Grid `ICellEditor` ref API (`getValue`, `isCancelBeforeStart`, `isCancelAfterEnd`).
+
+Your app owns the API call via `onSave` — the package does not use RTK Query or app-specific endpoints.
+
+For narrow columns, set `cellEditorPopup: true` on the column definition so the editor (and save/cancel buttons) is not clipped.
+
+```tsx
+import { CustomCellEditor } from "@eztrak/shared/components";
+import { ELITE_API } from "../constants/apiConstants";
+import { createCellEditorOnSave } from "../utils/cellEditorOnSave";
+
+// In column defs:
+{
+  field: "name",
+  editable: true,
+  cellEditor: CustomCellEditor,
+  cellEditorPopup: true,
+  cellEditorSelector: (params) => ({
+    component: CustomCellEditor,
+    params: {
+      value: params.value,
+      name: "name",
+      entityId: params.data.id,
+      entityName: "Package",
+      inputType: "text",
+      onSave: createCellEditorOnSave([ELITE_API.PACKAGE]),
+      dropdownOptions: [], // when inputType is "dropdown"
+    },
+  }),
+}
+```
+
+Example `createCellEditorOnSave` helper (elite-pilot pattern):
+
+```js
+import { ELITE_API } from "../constants/apiConstants";
+import { store } from "../redux/store";
+import { generalApi } from "../redux/api/generalApi";
+
+export function createCellEditorOnSave(invalidate = []) {
+  return async (payload) => {
+    const result = await store.dispatch(
+      generalApi.endpoints.updateRecord.initiate({
+        endpoint: ELITE_API.SAVE_CELL_EDIT,
+        data: payload,
+        invalidate: invalidate.map((endpoint) => ({
+          type: "General",
+          id: endpoint,
+        })),
+      })
+    );
+    if (result.error) {
+      throw new Error(result.error?.data?.message || "Failed to update record");
+    }
+  };
+}
+```
+
+#### Input types
+
+| `inputType` | Behavior |
+| --- | --- |
+| `text` | Standard text input |
+| `number` | Numeric input (filters non-numeric characters); `propertyValue` is sent as a `number` |
+| `date` | Date picker (`YYYY-MM-DD` via `toDateInputValue`) |
+| `dropdown` | Select from `dropdownOptions` |
+
+Save is disabled when the value is unchanged (compares as strings so `42` and `"42"` are treated as equal). Pressing Enter while a save is in progress does not submit twice.
+
 ### Components — ResetFiltersButton
 
 Clears all URL search params (`react-router-dom`) in one click. Self-contained — no app `Button` needed.
@@ -196,6 +292,104 @@ import { ResetFiltersButton } from "@eztrak/shared/components";
 | `onReset` | `() => void` | — | Called after search params are cleared |
 | `disabled` | `boolean` | `false` | Disables the button |
 
+### Components — SearchInput
+
+URL-synced search field with optional debounced live search. Requires a React Router context (`useSearchParams`).
+
+```tsx
+import { SearchInput } from "@eztrak/shared/components";
+
+// Submit on Enter or search icon click (updates ?query= in the URL)
+<SearchInput placeholder="Search items..." />
+```
+
+#### Live search (debounced)
+
+```tsx
+<SearchInput
+  placeholder="Search..."
+  liveSearch
+  debounceDelay={500}
+/>
+```
+
+#### Custom URL param name
+
+```tsx
+<SearchInput defaultParam="search" placeholder="Find a user..." />
+```
+
+#### Custom styling and icon
+
+```tsx
+<SearchInput
+  searchWrapperClass="border border-gray-200 shadow-sm"
+  searchClassName="w-full"
+  searchIconClassName="text-blue-500"
+  showIcon
+/>
+```
+
+#### Hide icon / custom icon
+
+```tsx
+import { HiOutlineSearch } from "react-icons/hi";
+
+<SearchInput showIcon={false} />
+
+<SearchInput customIcon={<HiOutlineSearch className="h-5 w-5" />} />
+```
+
+`SearchInput` reads and writes a single query param (default `query`). Clearing the input removes that param from the URL. The input stays in sync when the URL changes externally (e.g. browser back/forward or `ResetFiltersButton`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `placeholder` | `string` | `"Search..."` | Input placeholder |
+| `defaultParam` | `string` | `"query"` | URL search param key |
+| `defaultValue` | `string` | — | Initial value when the param is absent |
+| `liveSearch` | `boolean` | `false` | Update URL on input change (debounced) |
+| `debounceDelay` | `number` | `500` | Debounce delay in ms when `liveSearch` is true |
+| `showIcon` | `boolean` | `true` | Show the submit/search icon button |
+| `customIcon` | `ReactNode \| null` | `null` | Replace the default search icon |
+| `name` | `string` | `"search"` | Form input `name` (used on submit) |
+| `type` | `string` | `"search"` | Input `type` attribute |
+| `searchWrapperClass` | `string` | — | Classes for the form wrapper |
+| `searchClassName` | `string` | — | Classes for the input |
+| `searchBtn` | `string` | — | Classes for the icon button |
+| `searchIconClassName` | `string` | — | Classes for the default search icon |
+
+Also accepts standard `<input>` HTML attributes (except `name`, `type`, `value`, `onChange`, and `defaultValue`, which are managed internally).
+
+### Components — Loader
+
+Spinner for full-page or inline loading states. Requires `loader.css`:
+
+```tsx
+import { Loader } from "@eztrak/shared/components";
+import "@eztrak/shared/components/loader.css";
+
+<Loader size="36px" color="#F54C00" />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `string` | `"50px"` | Spinner diameter |
+| `color` | `string` | `"#F54C00"` | Spinner accent color |
+| `speed` | `string` | `"1s"` | Animation duration |
+| `className` | `string` | — | Extra class on the spinner element |
+
+### Components — Modal
+
+Animated modal dialog (uses `framer-motion`).
+
+```tsx
+import { Modal } from "@eztrak/shared/components";
+
+<Modal isOpen={open} onClose={() => setOpen(false)} title="Confirm">
+  <p>Modal content</p>
+</Modal>
+```
+
 ### Components — EztrakTabs
 
 Import styles once in your app entry or layout:
@@ -315,6 +509,10 @@ import {
   useGridHeight,
   EztrakTabs,
   CustomPagination,
+  SearchInput,
+  CustomCellEditor,
+  Loader,
+  Modal,
 } from "@eztrak/shared";
 ```
 
@@ -323,12 +521,14 @@ import {
 Run the component playground locally (dev-only, not published to npm):
 
 ```bash
+# From monorepo root
+npm run storybook
+
+# From packages/shared
 npm run storybook
-# or from the monorepo root:
-npm run storybook -w @eztrak/shared
 ```
 
-Opens on [http://localhost:6006](http://localhost:6006) with stories for `EztrakTabs`, `CustomPagination`, and `ResetColumnsButton`.
+Opens on [http://localhost:6006](http://localhost:6006) with stories for `EztrakTabs`, `CustomPagination`, `ResetColumnsButton`, `CustomCellEditor`, and `Loader`.
 
 ## Exports
 
@@ -337,8 +537,9 @@ Opens on [http://localhost:6006](http://localhost:6006) with stories for `Eztrak
 | `@eztrak/shared` | Main entry — re-exports utils, hooks, and components |
 | `@eztrak/shared/utils` | `cn`, `handleApiError`, `confirmationAlert`, date/format helpers, API error helpers, form field helpers |
 | `@eztrak/shared/hooks` | `usePaginationUrlSync`, `useGridHeight` |
-| `@eztrak/shared/components` | `EztrakTabs`, `CustomPagination`, `ResetColumnsButton`, `TableLayoutToolbarControls`, `ResetFiltersButton`, and related types |
+| `@eztrak/shared/components` | `EztrakTabs`, `CustomPagination`, `CustomCellEditor`, `SearchInput`, `ResetFiltersButton`, `Modal`, `Loader`, `TableLayoutToolbarControls`, `ResetColumnsButton`, and related types |
 | `@eztrak/shared/components/tabs.css` | Default tab styles (CSS variables) |
+| `@eztrak/shared/components/loader.css` | Loader spinner styles |
 
 ### EztrakTabs props
 
@@ -375,12 +576,30 @@ Keyboard: Arrow keys move between tabs; Home/End jump to first/last enabled tab.
 
 `CustomPagination` writes `page` and `perPage` to the URL via `react-router-dom`. Your page should read those params, fetch data, and pass the result back as `paginationData`.
 
+### CustomCellEditor props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string \| number \| null` | required | Initial cell value (AG Grid passes via `cellEditorParams`) |
+| `name` | `string` | required | Property name sent in save payload as `propertyName` |
+| `stopEditing` | `() => void` | required | AG Grid callback to close the editor |
+| `entityId` | `string \| number` | required | Entity id sent in save payload |
+| `entityName` | `string` | `"Record"` | Entity type name sent in save payload |
+| `inputType` | `CellEditorInputType` | `"text"` | `text`, `number`, `date`, or `dropdown` |
+| `onSave` | `(payload: CellEditPayload) => Promise<void>` | required | Async save handler; throw on failure to show error toast |
+| `dropdownOptions` | `DropdownOption[]` | `[]` | Options when `inputType` is `dropdown` |
+
+`CellEditPayload` shape: `{ propertyName, propertyValue, entityId, entityName }`. For `inputType: "number"`, `propertyValue` is a `number` (via `parseFloat`).
+
 ## Requirements
 
 - Node.js 18+
 - React 18+ (for hooks and components)
-- `react-router-dom` (required for `CustomPagination` and `usePaginationUrlSync`)
-- `sweetalert2` (required for `ResetColumnsButton` and `confirmationAlert`)
+- `react-router-dom` — `CustomPagination`, `SearchInput`, `ResetFiltersButton`, and `usePaginationUrlSync` (optional peer; install if you use these)
+- `react-hot-toast` — toast feedback in `CustomCellEditor` and `handleApiError`
+- `sweetalert2` — `ResetColumnsButton` and `confirmationAlert`
+- `react-icons` — `CustomCellEditor`, `SearchInput`, and `Modal`
+- `framer-motion` — `Modal`
 - Works with any bundler that supports the [Node.js `exports` field](https://nodejs.org/api/packages.html#exports)
 
 ## License

package/dist/{chunk-J6FBBM4R.mjs → chunk-BLCEEXZR.mjs}

@@ -1,7 +1,8 @@
 import {
   cn,
-  confirmationAlert
-} from "./chunk-5OG22DIX.mjs";
+  confirmationAlert,
+  toDateInputValue
+} from "./chunk-GVIHLI67.mjs";
 
 // src/components/tabs/EztrakTabs.tsx
 import {
@@ -682,7 +683,7 @@ function SearchInput({
     {
       onSubmit: handleSearch,
       className: cn(
-        "flex items-center justify-between bg-white rounded-md px-2 h-11",
+        "flex items-center justify-between bg-white rounded-xl px-2 h-11 border",
         searchWrapperClass
       ),
       children: [
@@ -919,6 +920,216 @@ function Modal({
   return createPortal(modalContent, modalRoot);
 }
 
+// src/components/cell-editor/CustomCellEditor.tsx
+import {
+  forwardRef,
+  useEffect as useEffect4,
+  useImperativeHandle,
+  useRef as useRef4,
+  useState as useState3
+} from "react";
+import toast from "react-hot-toast";
+import { FaCheck, FaTimes } from "react-icons/fa";
+import { jsx as jsx7, jsxs as jsxs6 } from "react/jsx-runtime";
+function ButtonSpinner() {
+  return /* @__PURE__ */ jsxs6(
+    "svg",
+    {
+      className: "animate-spin",
+      width: 8,
+      height: 8,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      "aria-hidden": true,
+      children: [
+        /* @__PURE__ */ jsx7(
+          "circle",
+          {
+            cx: "12",
+            cy: "12",
+            r: "10",
+            stroke: "white",
+            strokeWidth: "4",
+            strokeOpacity: "0.25"
+          }
+        ),
+        /* @__PURE__ */ jsx7(
+          "path",
+          {
+            d: "M12 2a10 10 0 0 1 10 10",
+            stroke: "white",
+            strokeWidth: "4",
+            strokeLinecap: "round"
+          }
+        )
+      ]
+    }
+  );
+}
+function normalizeInitialValue(initialValue, inputType) {
+  if (inputType === "date" && initialValue != null && initialValue !== "") {
+    return toDateInputValue(String(initialValue));
+  }
+  if (initialValue == null) {
+    return "";
+  }
+  return initialValue;
+}
+var CustomCellEditor = forwardRef(
+  ({
+    value: initialValue,
+    name,
+    inputType = "text",
+    stopEditing,
+    entityId,
+    entityName = "Record",
+    onSave,
+    dropdownOptions = []
+  }, ref) => {
+    const normalizedInitial = normalizeInitialValue(initialValue, inputType);
+    const [value, setValue] = useState3(normalizedInitial);
+    const [isLoading, setIsLoading] = useState3(false);
+    const inputRef = useRef4(null);
+    const selectRef = useRef4(null);
+    useImperativeHandle(ref, () => ({
+      getValue: () => value,
+      isCancelBeforeStart: () => false,
+      isCancelAfterEnd: () => false
+    }));
+    useEffect4(() => {
+      if (inputType === "dropdown") {
+        const el2 = selectRef.current;
+        if (el2) {
+          el2.focus();
+        }
+        return;
+      }
+      const el = inputRef.current;
+      if (!el) {
+        return;
+      }
+      el.focus();
+      if (inputType !== "date") {
+        el.select();
+      }
+    }, [inputType]);
+    const handleSave = async () => {
+      if (isLoading) {
+        return;
+      }
+      if (String(value) === String(normalizedInitial)) {
+        stopEditing();
+        return;
+      }
+      if (!entityId) {
+        toast.error("Entity ID is required");
+        return;
+      }
+      if (!name) {
+        toast.error("Property name is required");
+        return;
+      }
+      setIsLoading(true);
+      const payloadValue = inputType === "number" && value !== "" ? parseFloat(String(value)) : value;
+      const payload = {
+        propertyName: name,
+        propertyValue: payloadValue,
+        entityId,
+        entityName
+      };
+      try {
+        await onSave(payload);
+        toast.success("Record updated successfully");
+        stopEditing();
+      } catch (error) {
+        console.error("Update error:", error);
+        const errorMessage = error instanceof Error ? error.message : "Failed to update record";
+        toast.error(errorMessage);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    const handleCancel = () => {
+      setValue(normalizedInitial);
+      stopEditing();
+    };
+    const handleKeyDown = (event) => {
+      if (event.key === "Enter") {
+        event.preventDefault();
+        handleSave();
+      } else if (event.key === "Escape") {
+        event.preventDefault();
+        handleCancel();
+      }
+    };
+    const handleInputChange = (event) => {
+      let newValue = event.target.value;
+      if (inputType === "number") {
+        newValue = newValue.replace(/[^0-9.-]/g, "");
+      }
+      setValue(newValue);
+    };
+    const handleDropdownChange = (event) => {
+      setValue(event.target.value);
+    };
+    const isSaveDisabled = isLoading || String(value) === String(normalizedInitial);
+    return /* @__PURE__ */ jsxs6("div", { className: "flex items-center w-full h-full min-h-0 overflow-hidden gap-0.5 min-w-[80px]", children: [
+      inputType === "dropdown" ? /* @__PURE__ */ jsxs6(
+        "select",
+        {
+          ref: selectRef,
+          value: String(value),
+          onChange: handleDropdownChange,
+          onKeyDown: handleKeyDown,
+          className: "flex-1 h-full p-0 text-[10px] border border-gray-300 rounded-sm focus:outline-none focus:ring-1 focus:ring-blue-400 min-w-0 truncate",
+          disabled: isLoading,
+          children: [
+            /* @__PURE__ */ jsx7("option", { value: "", disabled: true, children: "Select option..." }),
+            dropdownOptions.map((opt) => /* @__PURE__ */ jsx7("option", { value: opt.value, children: opt.label }, opt.value))
+          ]
+        }
+      ) : /* @__PURE__ */ jsx7(
+        "input",
+        {
+          ref: inputRef,
+          type: inputType,
+          value: String(value),
+          onChange: handleInputChange,
+          onKeyDown: handleKeyDown,
+          className: "flex-1 h-full p-0 text-[10px] border border-gray-300 rounded-sm focus:outline-none focus:ring-1 focus:ring-blue-400 min-w-0 truncate",
+          placeholder: "...",
+          disabled: isLoading
+        }
+      ),
+      /* @__PURE__ */ jsxs6("div", { className: "flex items-center shrink-0 gap-0.5", children: [
+        /* @__PURE__ */ jsx7(
+          "button",
+          {
+            type: "button",
+            onClick: handleSave,
+            disabled: isSaveDisabled,
+            className: "flex items-center justify-center w-4 h-4 text-white bg-green-500 rounded-sm hover:bg-green-600 disabled:opacity-50",
+            title: "Save (Enter)",
+            children: isLoading ? /* @__PURE__ */ jsx7(ButtonSpinner, {}) : /* @__PURE__ */ jsx7(FaCheck, { size: 7, "aria-hidden": true })
+          }
+        ),
+        /* @__PURE__ */ jsx7(
+          "button",
+          {
+            type: "button",
+            onClick: handleCancel,
+            disabled: isLoading,
+            className: "flex items-center justify-center w-4 h-4 text-white bg-red-500 rounded-sm hover:bg-red-600 disabled:opacity-50",
+            title: "Cancel (Escape)",
+            children: /* @__PURE__ */ jsx7(FaTimes, { size: 7, "aria-hidden": true })
+          }
+        )
+      ] })
+    ] });
+  }
+);
+CustomCellEditor.displayName = "CustomCellEditor";
+
 export {
   EztrakTabs,
   ResetColumnsButton,
@@ -927,6 +1138,7 @@ export {
   ResetFiltersButton,
   SearchInput,
   Loader,
-  Modal
+  Modal,
+  CustomCellEditor
 };
-//# sourceMappingURL=chunk-J6FBBM4R.mjs.map
+//# sourceMappingURL=chunk-BLCEEXZR.mjs.map