@iamsaroj/smart-ui 0.2.0

package/dist/data-grid/pagination.d.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+/**
+ * Wrap an item schema in the Spring Data `Page<T>` envelope, the response shape
+ * produced by a Spring `Page`/`Pageable` controller (and a common pagination
+ * contract generally):
+ *
+ * ```jsonc
+ * { "content": [...], "totalElements": 20, "totalPages": 4, "number": 0, "size": 5, ... }
+ * ```
+ *
+ * Validate a paged response with `pageSchema(itemSchema).parse(data)`, mirroring
+ * the `schema.parse` convention used by every other hook in this layer.
+ *
+ * @example
+ * ```ts
+ * const usersPageSchema = pageSchema(userRowSchema);
+ * const page = usersPageSchema.parse(await api.get("/users", { params }));
+ * ```
+ */
+export declare const pageSchema: <TItem extends z.ZodTypeAny>(item: TItem) => z.ZodObject<{
+    content: z.ZodArray<TItem>;
+    totalElements: z.ZodNumber;
+    totalPages: z.ZodNumber;
+    number: z.ZodNumber;
+    size: z.ZodNumber;
+    first: z.ZodOptional<z.ZodBoolean>;
+    last: z.ZodOptional<z.ZodBoolean>;
+    numberOfElements: z.ZodOptional<z.ZodNumber>;
+    empty: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Convenience type mirroring what {@link pageSchema} parses into — the Spring
+ * Data `Page<T>` response envelope.
+ *
+ * (Named `SPageResponse` rather than `SPage` so it doesn't collide with the
+ * `SPage` page-layout component.)
+ */
+export interface SPageResponse<TItem> {
+    content: TItem[];
+    totalElements: number;
+    totalPages: number;
+    number: number;
+    size: number;
+    first?: boolean;
+    last?: boolean;
+    numberOfElements?: number;
+    empty?: boolean;
+}
+/** A single sort instruction. */
+export interface ServerSort {
+    field: string;
+    dir: "asc" | "desc";
+}
+/**
+ * A single normalized filter, distilled from AG Grid's heterogeneous filter
+ * model into a flat, transport-agnostic shape an app can serialize however its
+ * backend expects.
+ */
+export interface ServerFilter {
+    /** Column field the filter applies to. */
+    field: string;
+    /** AG Grid filter family: `"text" | "number" | "date" | "set"`. */
+    filterType: string;
+    /** Operator, e.g. `"contains" | "equals" | "greaterThan" | "inRange" | "set"`. */
+    type: string;
+    /** Primary value (or the array of selected values for a set filter). */
+    value: unknown;
+    /** Upper bound for range operators (`inRange`). */
+    valueTo?: unknown;
+}
+/**
+ * What {@link SmartServerGrid}'s `fetchRows` receives — everything the server
+ * needs to return one block of rows, in a framework-agnostic form. Both the AG
+ * Grid block coordinates (`startRow`/`endRow`) and the page-oriented equivalents
+ * (`page`/`pageSize`) are provided so callers can use whichever their API speaks.
+ */
+export interface ServerFetchParams {
+    /** Zero-based index of the first requested row (inclusive). */
+    startRow: number;
+    /** Index of the row after the last requested row (exclusive). */
+    endRow: number;
+    /** Zero-based page index — `floor(startRow / pageSize)`. */
+    page: number;
+    /** Rows per page/block — `endRow - startRow`. */
+    pageSize: number;
+    /** Active sort instructions, in priority order. */
+    sort: ServerSort[];
+    /** Active filters. */
+    filters: ServerFilter[];
+}
+/** What `fetchRows` resolves to: the block of rows plus the total row count. */
+export interface ServerFetchResult<TRow> {
+    rows: TRow[];
+    /** Total rows on the server for the current filters (e.g. `Page.totalElements`). */
+    total: number;
+}
+/** Convert an AG Grid filter model into a flat list of {@link ServerFilter}. */
+export declare const normalizeFilterModel: (filterModel: Record<string, unknown> | null | undefined) => ServerFilter[];
+/**
+ * Translate one AG Grid Infinite-Row-Model `getRows` request into the
+ * normalized {@link ServerFetchParams} passed to a grid's `fetchRows`. Pure and
+ * framework-agnostic (AG Grid's `sortModel`/`filterModel` are accepted by
+ * structural shape, so this module never imports AG Grid).
+ */
+export declare const buildServerFetchParams: (input: {
+    startRow: number;
+    endRow: number;
+    sortModel: ReadonlyArray<{
+        colId: string;
+        sort: "asc" | "desc";
+    }>;
+    filterModel?: Record<string, unknown> | null;
+}) => ServerFetchParams;
+/**
+ * Serialize sort instructions into Spring's `sort=field,dir` strings (one per
+ * sorted column, in priority order). The page (`page`/`size`) and filter dialect
+ * vary per backend, so those stay app-owned — only the unambiguous sort encoding
+ * is provided here.
+ *
+ * @example `toSpringSort([{ field: "mrr", dir: "desc" }])` → `["mrr,desc"]`
+ */
+export declare const toSpringSort: (sort: ReadonlyArray<ServerSort>) => string[];
+/**
+ * Serialize a single {@link ServerFilter} into the `<op>:<value>` value used by
+ * the Spring query dialect below:
+ *
+ * - `inRange` → `inRange:<from>:<to>`
+ * - set (array value) → `set:<a>,<b>,<c>`
+ * - everything else → `<op>:<value>`
+ */
+export declare const encodeSpringFilter: (filter: ServerFilter) => string;
+/**
+ * Serialize normalized {@link ServerFetchParams} into a Spring Data query string
+ * (without the leading `?`) — the encoder half of the query contract:
+ *
+ * - paging  → `page=0&size=20`
+ * - sorting → `sort=name,asc&sort=mrr,desc`  (repeatable, Spring style)
+ * - filters → `<field>=<op>:<value>`, e.g. `name=contains:ada`,
+ *             `mrr=inRange:1000:2000`, `status=set:Active,Pending`
+ *
+ * This is the default `buildQuery` for {@link createPageFetcher}. The matching
+ * *decoder* stays server/app-side (backends parse however they like), so it is
+ * intentionally not shipped here.
+ */
+export declare const buildSpringQuery: (params: ServerFetchParams) => string;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/data-grid/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/data-grid/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,KAAK;;;;;;;;;;iBAoB9D,CAAA;AAEJ;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC,OAAO,EAAE,KAAK,EAAE,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAMD,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,KAAK,GAAG,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,KAAK,EAAE,OAAO,CAAA;IACd,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,IAAI,EAAE,UAAU,EAAE,CAAA;IAClB,sBAAsB;IACtB,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB,CAAC,IAAI;IACrC,IAAI,EAAE,IAAI,EAAE,CAAA;IACZ,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAA;CACd;AAuCD,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,GAC/B,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,KACtD,YAAY,EAKd,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO;IAC5C,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC,CAAA;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC7C,KAAG,iBAUH,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,aAAa,CAAC,UAAU,CAAC,KAAG,MAAM,EAC7B,CAAA;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,YAAY,KAAG,MAQzD,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,iBAAiB,KAAG,MAQ5D,CAAA"}

package/dist/data-grid/pagination.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+/* -------------------------------------------------------------------------- */
+/*                          Spring Data `Page<T>` shape                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Wrap an item schema in the Spring Data `Page<T>` envelope, the response shape
+ * produced by a Spring `Page`/`Pageable` controller (and a common pagination
+ * contract generally):
+ *
+ * ```jsonc
+ * { "content": [...], "totalElements": 20, "totalPages": 4, "number": 0, "size": 5, ... }
+ * ```
+ *
+ * Validate a paged response with `pageSchema(itemSchema).parse(data)`, mirroring
+ * the `schema.parse` convention used by every other hook in this layer.
+ *
+ * @example
+ * ```ts
+ * const usersPageSchema = pageSchema(userRowSchema);
+ * const page = usersPageSchema.parse(await api.get("/users", { params }));
+ * ```
+ */
+export const pageSchema = (item) => z.object({
+    /** The rows for this page. */
+    content: z.array(item),
+    /** Total rows across every page (drives the infinite-scroll row count). */
+    totalElements: z.number(),
+    /** Total number of pages. */
+    totalPages: z.number(),
+    /** Zero-based index of the current page. */
+    number: z.number(),
+    /** Page size used for this response. */
+    size: z.number(),
+    /** Whether this is the first page. */
+    first: z.boolean().optional(),
+    /** Whether this is the last page. */
+    last: z.boolean().optional(),
+    /** Number of rows actually present in `content`. */
+    numberOfElements: z.number().optional(),
+    /** Whether the page is empty. */
+    empty: z.boolean().optional(),
+});
+const normalizeFilterItem = (field, raw) => {
+    // For combined conditions we take the first condition (a pragmatic v1 choice —
+    // most server contracts accept a single predicate per field).
+    const item = raw.condition1 ?? raw;
+    const isSet = Array.isArray(item.values);
+    return {
+        field,
+        filterType: item.filterType ?? (isSet ? "set" : "text"),
+        type: item.type ?? (isSet ? "set" : "contains"),
+        value: isSet ? item.values : (item.filter ?? item.dateFrom),
+        valueTo: item.filterTo ?? item.dateTo,
+    };
+};
+/** Convert an AG Grid filter model into a flat list of {@link ServerFilter}. */
+export const normalizeFilterModel = (filterModel) => {
+    if (!filterModel)
+        return [];
+    return Object.entries(filterModel).map(([field, raw]) => normalizeFilterItem(field, (raw ?? {})));
+};
+/**
+ * Translate one AG Grid Infinite-Row-Model `getRows` request into the
+ * normalized {@link ServerFetchParams} passed to a grid's `fetchRows`. Pure and
+ * framework-agnostic (AG Grid's `sortModel`/`filterModel` are accepted by
+ * structural shape, so this module never imports AG Grid).
+ */
+export const buildServerFetchParams = (input) => {
+    const pageSize = Math.max(input.endRow - input.startRow, 1);
+    return {
+        startRow: input.startRow,
+        endRow: input.endRow,
+        pageSize,
+        page: Math.floor(input.startRow / pageSize),
+        sort: input.sortModel.map((s) => ({ field: s.colId, dir: s.sort })),
+        filters: normalizeFilterModel(input.filterModel),
+    };
+};
+/**
+ * Serialize sort instructions into Spring's `sort=field,dir` strings (one per
+ * sorted column, in priority order). The page (`page`/`size`) and filter dialect
+ * vary per backend, so those stay app-owned — only the unambiguous sort encoding
+ * is provided here.
+ *
+ * @example `toSpringSort([{ field: "mrr", dir: "desc" }])` → `["mrr,desc"]`
+ */
+export const toSpringSort = (sort) => sort.map((s) => `${s.field},${s.dir}`);
+/**
+ * Serialize a single {@link ServerFilter} into the `<op>:<value>` value used by
+ * the Spring query dialect below:
+ *
+ * - `inRange` → `inRange:<from>:<to>`
+ * - set (array value) → `set:<a>,<b>,<c>`
+ * - everything else → `<op>:<value>`
+ */
+export const encodeSpringFilter = (filter) => {
+    if (filter.type === "inRange") {
+        return `inRange:${String(filter.value)}:${String(filter.valueTo)}`;
+    }
+    if (Array.isArray(filter.value)) {
+        return `set:${filter.value.map(String).join(",")}`;
+    }
+    return `${filter.type}:${String(filter.value)}`;
+};
+/**
+ * Serialize normalized {@link ServerFetchParams} into a Spring Data query string
+ * (without the leading `?`) — the encoder half of the query contract:
+ *
+ * - paging  → `page=0&size=20`
+ * - sorting → `sort=name,asc&sort=mrr,desc`  (repeatable, Spring style)
+ * - filters → `<field>=<op>:<value>`, e.g. `name=contains:ada`,
+ *             `mrr=inRange:1000:2000`, `status=set:Active,Pending`
+ *
+ * This is the default `buildQuery` for {@link createPageFetcher}. The matching
+ * *decoder* stays server/app-side (backends parse however they like), so it is
+ * intentionally not shipped here.
+ */
+export const buildSpringQuery = (params) => {
+    const sp = new URLSearchParams();
+    sp.set("page", String(params.page));
+    sp.set("size", String(params.pageSize));
+    for (const sort of toSpringSort(params.sort))
+        sp.append("sort", sort);
+    for (const filter of params.filters)
+        sp.append(filter.field, encodeSpringFilter(filter));
+    return sp.toString();
+};
+//# sourceMappingURL=pagination.js.map

package/dist/data-grid/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/data-grid/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAA6B,IAAW,EAAE,EAAE,CACpE,CAAC,CAAC,MAAM,CAAC;IACP,8BAA8B;IAC9B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;IACtB,2EAA2E;IAC3E,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,6BAA6B;IAC7B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,4CAA4C;IAC5C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,wCAAwC;IACxC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,sCAAsC;IACtC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC7B,qCAAqC;IACrC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5B,oDAAoD;IACpD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACvC,iCAAiC;IACjC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAA;AAiGJ,MAAM,mBAAmB,GAAG,CAC1B,KAAa,EACb,GAAsB,EACR,EAAE;IAChB,+EAA+E;IAC/E,8DAA8D;IAC9D,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAA;IAClC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACxC,OAAO;QACL,KAAK;QACL,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QACvD,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;QAC/C,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC;QAC3D,OAAO,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM;KACtC,CAAA;AACH,CAAC,CAAA;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,WAAuD,EACvC,EAAE;IAClB,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,CAAA;IAC3B,OAAO,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,CACtD,mBAAmB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAsB,CAAC,CAC7D,CAAA;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAKtC,EAAqB,EAAE;IACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ;QACR,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC3C,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC;KACjD,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAA+B,EAAY,EAAE,CACxE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAoB,EAAU,EAAE;IACjE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,WAAW,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;IACpE,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;IACpD,CAAC;IACD,OAAO,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AACjD,CAAC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAyB,EAAU,EAAE;IACpE,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAA;IAChC,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACnC,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IACvC,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACrE,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO;QACjC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAA;IACrD,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAA;AACtB,CAAC,CAAA"}

package/dist/data-grid/server-data-grid.d.ts

@@ -0,0 +1,109 @@
+import { type ForwardedRef, type ReactElement, type ReactNode } from "react";
+import { type ServerFetchParams, type ServerFetchResult, type ServerFilter } from "./pagination";
+import { type DataGridColumn, type DataGridDensity } from "./grid-internals";
+import { type ServerSelection } from "./use-server-grid-selection";
+import type { GridActionColumnOptions } from "./action-column";
+export type { ServerSelection };
+/** Imperative handle exposed via `ref`. */
+export interface SmartServerGridHandle<TRow> {
+    /** Re-fetch the loaded blocks from the server, keeping scroll position. */
+    refresh: () => void;
+    /** Purge every block and re-fetch from the first row. */
+    reload: () => void;
+    /** All selected row ids (including rows not currently loaded). */
+    getSelectedIds: () => string[];
+    /** Selected rows currently loaded in the grid cache. */
+    getSelectedRows: () => TRow[];
+    /** Clear the selection. */
+    clearSelection: () => void;
+}
+export interface SmartServerGridProps<TRow> {
+    /** Column definitions. */
+    columns: DataGridColumn<TRow>[];
+    /**
+     * Fetch one block of rows from the server. Receives normalized paging, sort
+     * and filter params plus an `AbortSignal`, and resolves to `{ rows, total }`.
+     * Rejecting (or throwing) surfaces the error overlay with a **Retry** button.
+     */
+    fetchRows: (params: ServerFetchParams, signal: AbortSignal) => Promise<ServerFetchResult<TRow>>;
+    /** Stable row id — required for selection and block reconciliation across pages. */
+    getRowId: (row: TRow) => string;
+    /**
+     * Config-driven Edit/Delete action column — pinned, permission-aware and
+     * row-aware, with per-row loading and optional delete confirmation. The
+     * column auto-hides when disabled or when every action is statically hidden.
+     */
+    actionColumn?: GridActionColumnOptions<TRow>;
+    /**
+     * External filters merged into every fetch — e.g. driven by a dedicated search
+     * form rather than the column headers. Changing this array (by identity)
+     * resets to page 1 and refetches; it stays out of the grid's own state, so
+     * typing in the form never hits the server until you swap the array in.
+     */
+    filters?: ServerFilter[];
+    /** Show the classic pager (`true`) or stream via infinite scroll (`false`). Default `true`. */
+    pagination?: boolean;
+    /** Rows per server block / page. Default `20`. */
+    pageSize?: number;
+    /** Page-size options shown in the pager selector. */
+    pageSizeOptions?: number[];
+    /** Row selection mode. Default `"none"`. */
+    selection?: "single" | "multiple" | "none";
+    /** Fired when selection changes — loaded selected rows plus every selected id. */
+    onSelectionChange?: (selection: ServerSelection<TRow>) => void;
+    /**
+     * Fired on row double-click with the full row object. Designed as the
+     * extension point for row-level actions (open a drawer, navigate, …).
+     */
+    onRowDoubleClick?: (row: TRow) => void;
+    /**
+     * Per-column header filters (text/number/set inputs + filter menu). Default
+     * `true`. Set `false` to remove all in-header filtering — sorting stays
+     * enabled — when filtering is driven by an external search form instead.
+     */
+    columnFilters?: boolean;
+    /** Floating filter row beneath the headers (only applies when `columnFilters`). Default `true`. */
+    floatingFilters?: boolean;
+    /**
+     * `localStorage` key. When set, the grid persists column order / size /
+     * visibility plus the active sort and filters, and restores them on reload.
+     */
+    persistStateKey?: string;
+    /** Title rendered in the toolbar. */
+    title?: ReactNode;
+    /** Extra toolbar content rendered on the right. */
+    toolbarActions?: ReactNode;
+    /** Manual refresh button. Default `true`. */
+    refreshable?: boolean;
+    /** Column visibility menu. Default `true`. */
+    columnSelector?: boolean;
+    /** Export-to-Excel (`.xlsx`) button — exports the loaded/displayed rows. Default `true`. */
+    exportExcel?: boolean;
+    /** Export file name (without extension); a timestamp + `.xlsx` are appended. Default `"export"`. */
+    exportFileName?: string;
+    /** Row density. Default `"normal"`. */
+    density?: DataGridDensity;
+    /**
+     * Fill the parent instead of using a fixed `height`. The grid becomes a
+     * flex column (`h-full`) whose body grows to consume the remaining space and
+     * resizes automatically with its container — use inside a
+     * `flex-1 min-h-0` parent for a full-viewport layout. Default `false`.
+     */
+    fill?: boolean;
+    /** Grid height when `fill` is `false`. Default `480`. */
+    height?: number | string;
+    /** Empty-state content shown when the server returns no rows. */
+    emptyState?: {
+        title?: string;
+        description?: string;
+    };
+    className?: string;
+}
+/**
+ * `forwardRef` erases generics, so re-assert the generic call signature. This is
+ * the standard "generic forwardRef" cast — runtime is unchanged.
+ */
+export declare const SmartServerGrid: <TRow>(props: SmartServerGridProps<TRow> & {
+    ref?: ForwardedRef<SmartServerGridHandle<TRow>>;
+}) => ReactElement;
+//# sourceMappingURL=server-data-grid.d.ts.map

package/dist/data-grid/server-data-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-data-grid.d.ts","sourceRoot":"","sources":["../../src/data-grid/server-data-grid.tsx"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAgBd,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,eAAe,EAErB,MAAM,kBAAkB,CAAA;AAQzB,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,6BAA6B,CAAA;AACpC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAK9D,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B,2CAA2C;AAC3C,MAAM,WAAW,qBAAqB,CAAC,IAAI;IACzC,2EAA2E;IAC3E,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,yDAAyD;IACzD,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,kEAAkE;IAClE,cAAc,EAAE,MAAM,MAAM,EAAE,CAAA;IAC9B,wDAAwD;IACxD,eAAe,EAAE,MAAM,IAAI,EAAE,CAAA;IAC7B,2BAA2B;IAC3B,cAAc,EAAE,MAAM,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB,CAAC,IAAI;IACxC,0BAA0B;IAC1B,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,CAAA;IAC/B;;;;OAIG;IACH,SAAS,EAAE,CACT,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAA;IACrC,oFAAoF;IACpF,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,CAAA;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAC,IAAI,CAAC,CAAA;IAE5C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;IAExB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAE1B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAA;IAC1C,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA;IAC9D;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAA;IAEtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,mGAAmG;IACnG,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB,qCAAqC;IACrC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,mDAAmD;IACnD,cAAc,CAAC,EAAE,SAAS,CAAA;IAC1B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,4FAA4F;IAC5F,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACxB,iEAAiE;IACjE,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAsYD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAA+B,CAAC,IAAI,EAC9D,KAAK,EAAE,oBAAoB,CAAC,IAAI,CAAC,GAAG;IAClC,GAAG,CAAC,EAAE,YAAY,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAA;CAChD,KACE,YAAY,CAAA"}

package/dist/data-grid/server-data-grid.js

@@ -0,0 +1,240 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { AgGridReact } from "ag-grid-react";
+import { FileSpreadsheet } from "lucide-react";
+import { cn } from "@iamsaroj/smart-ui/lib/utils";
+import { downloadXlsx, timestampForFilename } from "@iamsaroj/smart-ui/lib/xlsx";
+import { GridToolbar } from "./grid-toolbar";
+import { SmartLoadingOverlay } from "@iamsaroj/smart-ui/smart-components/loading-overlay";
+import { SmartPageError } from "@iamsaroj/smart-ui/smart-components/page/smart-page-error";
+import { dataGridTheme } from "./grid-theme";
+import { ensureGridModules, NoRowsOverlay, resolveColumnId, resolveColumnLabel, rowHeightByDensity, } from "./grid-internals";
+import { collectGridExport, createGridDatasource, debounce, readPersistedGridState, writePersistedGridState, } from "./server-grid-internals";
+import { useServerGridSelection, } from "./use-server-grid-selection";
+import { useGridActionColumn, withActionColumn } from "./use-action-column";
+/**
+ * Server-driven data grid built on AG Grid Community's **Infinite Row Model**.
+ * One datasource powers both modes: with `pagination` it renders a classic
+ * pager, without it streams rows via infinite scroll. Sorting runs server-side
+ * (each change re-queries through `fetchRows`) and filtering is supplied through
+ * the `filters` prop (e.g. a search form) rather than column headers. It ships
+ * loading + error/retry states, manual refresh, column resize/reorder, a column
+ * visibility menu, Excel export, row double-click, cross-page selection, an
+ * optional full-viewport `fill` layout, and column-state persistence.
+ *
+ * @example
+ * ```tsx
+ * <SmartServerGrid
+ *   columns={columns}
+ *   getRowId={(u) => u.id}
+ *   fetchRows={fetchUsersPage}
+ *   filters={searchFilters}   // from a search form
+ *   columnFilters={false}
+ *   pagination={false}        // infinite scroll
+ *   selection="multiple"
+ *   fill
+ * />
+ * ```
+ */
+const SmartServerGridInner = (props, ref) => {
+    const { columns, fetchRows, getRowId, actionColumn, filters, pagination = true, pageSize = 20, pageSizeOptions = [5, 10, 20, 50], selection = "none", onSelectionChange, onRowDoubleClick, columnFilters = true, floatingFilters = true, persistStateKey, title, toolbarActions, refreshable = true, columnSelector = true, exportExcel = true, exportFileName = "export", density = "normal", fill = false, height = 480, emptyState, className, } = props;
+    ensureGridModules();
+    // Latest props read by the (stable) datasource + grid callbacks, without
+    // re-creating them — recreating the datasource would reset the grid.
+    const gridApiRef = useRef(null);
+    const fetchRowsRef = useRef(fetchRows);
+    const getRowIdRef = useRef(getRowId);
+    const onRowDoubleClickRef = useRef(onRowDoubleClick);
+    const filtersRef = useRef(filters);
+    const persistKeyRef = useRef(persistStateKey);
+    useLayoutEffect(() => {
+        fetchRowsRef.current = fetchRows;
+        getRowIdRef.current = getRowId;
+        onRowDoubleClickRef.current = onRowDoubleClick;
+        filtersRef.current = filters;
+        persistKeyRef.current = persistStateKey;
+    });
+    const controllersRef = useRef(new Set());
+    const [initialLoading, setInitialLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // In-flight block count drives the "loading more" bar shown while infinite
+    // scroll fetches subsequent pages (the overlay only covers the first load).
+    const inFlightRef = useRef(0);
+    const [loadingMore, setLoadingMore] = useState(false);
+    const [columnVisibility, setColumnVisibility] = useState(() => {
+        const initial = {};
+        columns.forEach((column, index) => {
+            initial[resolveColumnId(column, index)] = column.hide !== true;
+        });
+        return initial;
+    });
+    // Cross-page selection lives in a dedicated hook — the selected-id set is the
+    // source of truth, so a selection survives block reloads (see the hook).
+    const gridSelection = useServerGridSelection(gridApiRef, onSelectionChange);
+    const actionColumnDef = useGridActionColumn(actionColumn);
+    const effectiveColumns = useMemo(() => withActionColumn(columns, actionColumnDef), [columns, actionColumnDef]);
+    const saveState = useCallback(() => {
+        const api = gridApiRef.current;
+        const key = persistKeyRef.current;
+        if (!api || !key)
+            return;
+        writePersistedGridState(key, {
+            columnState: api.getColumnState(),
+            filterModel: api.getFilterModel(),
+        });
+    }, []);
+    const schedulePersistRef = useRef(null);
+    useEffect(() => {
+        schedulePersistRef.current = debounce(saveState, 300);
+    }, [saveState]);
+    const schedulePersist = useCallback(() => schedulePersistRef.current?.(), []);
+    const restoreState = useCallback((api) => {
+        const key = persistKeyRef.current;
+        if (!key)
+            return;
+        const parsed = readPersistedGridState(key);
+        if (!parsed)
+            return;
+        if (parsed.columnState)
+            api.applyColumnState({ state: parsed.columnState, applyOrder: true });
+        if (parsed.filterModel)
+            api.setFilterModel(parsed.filterModel);
+    }, []);
+    // External filters changed (Search / Reset) → reset to page 1 and refetch.
+    // Skip the mount run so the datasource's own first fetch isn't duplicated.
+    const didMountRef = useRef(false);
+    useEffect(() => {
+        if (!didMountRef.current) {
+            didMountRef.current = true;
+            return;
+        }
+        setError(null);
+        setInitialLoading(true);
+        gridApiRef.current?.purgeInfiniteCache();
+    }, [filters]);
+    const defaultColDef = useMemo(() => ({
+        sortable: true,
+        filter: columnFilters,
+        floatingFilter: columnFilters && floatingFilters,
+        resizable: true,
+        flex: 1,
+        minWidth: 120,
+    }), [columnFilters, floatingFilters]);
+    const rowSelection = useMemo(() => {
+        // No `headerCheckbox` in the infinite row model (AG Grid warning #129) — a
+        // "select all" can't span rows the client hasn't loaded. Per-row checkboxes
+        // plus our cross-page id tracking are what make sense here. `multiRow`
+        // defaults headerCheckbox to true, so it must be disabled explicitly.
+        if (selection === "multiple")
+            return { mode: "multiRow", checkboxes: true, headerCheckbox: false };
+        if (selection === "single")
+            return { mode: "singleRow", checkboxes: true };
+        return undefined;
+    }, [selection]);
+    const toggleableColumns = useMemo(() => columns.map((column, index) => {
+        const id = resolveColumnId(column, index);
+        return { id, label: resolveColumnLabel(column, id) };
+    }), [columns]);
+    const getRowIdCb = useCallback((params) => getRowIdRef.current(params.data), []);
+    const handleGridReady = useCallback((event) => {
+        gridApiRef.current = event.api;
+        // Restore sort/filter/columns BEFORE the first fetch so the first request
+        // already reflects the persisted state, then start the datasource.
+        restoreState(event.api);
+        // Created once per grid instantiation (gridReady fires once), so the
+        // datasource identity is stable for the grid's lifetime — a new one
+        // would purge the cache. It reads the latest `fetchRows` / `filters`
+        // through ref getters; the translation/abort/error flow lives in
+        // `createGridDatasource` (server-grid-internals), where it is unit-tested.
+        event.api.setGridOption("datasource", createGridDatasource({
+            getFetchRows: () => fetchRowsRef.current,
+            getExternalFilters: () => filtersRef.current,
+            controllers: controllersRef.current,
+            onFetchStart: () => {
+                inFlightRef.current += 1;
+                setLoadingMore(true);
+            },
+            onSuccess: () => setError(null),
+            onError: setError,
+            onSettled: () => {
+                setInitialLoading(false);
+                inFlightRef.current = Math.max(0, inFlightRef.current - 1);
+                if (inFlightRef.current === 0)
+                    setLoadingMore(false);
+            },
+        }));
+    }, [restoreState]);
+    const handleRowDoubleClicked = useCallback((event) => {
+        if (event.data)
+            onRowDoubleClickRef.current?.(event.data);
+    }, []);
+    const handleRetry = useCallback(() => {
+        setError(null);
+        setInitialLoading(true);
+        gridApiRef.current?.purgeInfiniteCache();
+    }, []);
+    const handleRefresh = useCallback(() => {
+        setError(null);
+        gridApiRef.current?.refreshInfiniteCache();
+    }, []);
+    const handleToggleColumn = useCallback((id, visible) => {
+        setColumnVisibility((prev) => ({ ...prev, [id]: visible }));
+        gridApiRef.current?.setColumnsVisible([id], visible);
+        schedulePersist();
+    }, [schedulePersist]);
+    const handleExport = useCallback(() => {
+        const api = gridApiRef.current;
+        if (!api)
+            return;
+        // Export the displayed columns (respecting visibility + order) and the rows
+        // currently loaded in the cache, using each cell's *displayed* value.
+        const { headers, rows } = collectGridExport(api);
+        const sheetName = typeof title === "string" && title.length > 0 ? title : "Export";
+        downloadXlsx(`${exportFileName}-${timestampForFilename()}`, {
+            name: sheetName,
+            headers,
+            rows,
+        });
+    }, [exportFileName, title]);
+    useImperativeHandle(ref, () => ({
+        refresh: () => gridApiRef.current?.refreshInfiniteCache(),
+        reload: handleRetry,
+        getSelectedIds: gridSelection.getSelectedIds,
+        getSelectedRows: gridSelection.collectLoadedSelectedRows,
+        clearSelection: gridSelection.clearSelection,
+    }), [
+        handleRetry,
+        gridSelection.getSelectedIds,
+        gridSelection.collectLoadedSelectedRows,
+        gridSelection.clearSelection,
+    ]);
+    const showToolbar = title ||
+        refreshable ||
+        columnSelector ||
+        exportExcel ||
+        toolbarActions ||
+        selection !== "none";
+    return (_jsxs("div", { className: cn("flex flex-col gap-3", fill && "h-full min-h-0", className), style: fill ? { height: "100%" } : undefined, children: [showToolbar ? (_jsx(GridToolbar, { className: cn("shrink-0", fill && "px-4 pt-4"), title: title, leadingContent: selection !== "none" && gridSelection.selectedCount > 0 ? (_jsxs("span", { className: "text-sm text-muted-foreground", children: [gridSelection.selectedCount, " selected"] })) : null, toolbarActions: toolbarActions, onRefresh: refreshable ? handleRefresh : undefined, columns: columnSelector
+                    ? toggleableColumns.map((column) => ({
+                        ...column,
+                        visible: columnVisibility[column.id] ?? true,
+                    }))
+                    : undefined, onToggleColumn: handleToggleColumn, onExport: exportExcel ? handleExport : undefined, exportIcon: _jsx(FileSpreadsheet, { className: "h-4 w-4" }) })) : null, _jsxs("div", { className: cn("relative w-full", fill && "min-h-0 flex-1"), style: fill ? undefined : { height }, children: [_jsx(AgGridReact, { className: "h-full w-full", theme: dataGridTheme, rowModelType: "infinite", cacheBlockSize: pageSize, columnDefs: effectiveColumns, defaultColDef: defaultColDef, suppressCellFocus: true, rowSelection: rowSelection, pagination: pagination, 
+                        // Page-size props only apply to the pager; passing them in infinite
+                        // scroll mode trips AG Grid warning #94 when `pageSize` isn't one of
+                        // the selector options (`cacheBlockSize` already carries the size).
+                        paginationPageSize: pagination ? pageSize : undefined, paginationPageSizeSelector: pagination ? pageSizeOptions : undefined, rowHeight: rowHeightByDensity[density], getRowId: getRowIdCb, animateRows: true, noRowsOverlayComponent: NoRowsOverlay, noRowsOverlayComponentParams: {
+                            title: emptyState?.title,
+                            description: emptyState?.description,
+                        }, onGridReady: handleGridReady, onModelUpdated: gridSelection.reapplySelection, onRowSelected: gridSelection.handleRowSelected, onRowDoubleClicked: handleRowDoubleClicked, onSortChanged: schedulePersist, onFilterChanged: schedulePersist, onColumnMoved: schedulePersist, onColumnResized: schedulePersist, onColumnVisible: schedulePersist, onColumnPinned: schedulePersist }), loadingMore && !initialLoading && !error ? (_jsx("div", { role: "status", "aria-live": "polite", "aria-label": "Loading more rows", className: "pointer-events-none absolute inset-x-0 top-0 z-40 h-0.5 overflow-hidden bg-primary/20", children: _jsx("div", { className: "h-full w-1/4 bg-primary", style: {
+                                animation: "grid-indeterminate 1.1s ease-in-out infinite",
+                            } }) })) : null, initialLoading && !error ? (_jsx(SmartLoadingOverlay, { loading: true, label: "Loading data\u2026" })) : null, error ? (_jsx(SmartPageError, { variant: "overlay", title: "Couldn\u2019t load data", description: error, onRetry: handleRetry, retryLabel: "Retry" })) : null] })] }));
+};
+const SmartServerGridForwarded = forwardRef(SmartServerGridInner);
+SmartServerGridForwarded.displayName = "SmartServerGrid";
+/**
+ * `forwardRef` erases generics, so re-assert the generic call signature. This is
+ * the standard "generic forwardRef" cast — runtime is unchanged.
+ */
+export const SmartServerGrid = SmartServerGridForwarded;
+//# sourceMappingURL=server-data-grid.js.map