@ethanhann/mantine-dataview 0.1.0

package/dist/types/options.d.ts

@@ -0,0 +1,95 @@
+import { MantineBreakpoint } from '@mantine/core';
+import { Column, Table } from '@tanstack/react-table';
+import { ExportCsvOptions } from '../core/exportCsv';
+import { UrlSerializer, UrlStateAdapter } from '../url/types';
+import { ColumnDataType, ColumnFormatOption, DataColumnDef } from './column';
+import { FacetData } from './facets';
+import { DataViewRequest } from './request';
+import { DataViewState, DataViewStatus, Status, ViewMode } from './state';
+/** Force cards at or below a Mantine breakpoint. Cards are the preferred view on small screens. */
+export interface ResponsiveOptions {
+    forceCardsBelow?: MantineBreakpoint;
+    lockSwitcherOnMobile?: boolean;
+}
+/** URL state sync that is agnostic about the router. */
+export interface UrlSyncOptions {
+    adapter: UrlStateAdapter;
+    /** Override param names or codecs. */
+    serialize?: Partial<UrlSerializer>;
+    /** Which slices of state to sync. The default is all of them. */
+    include?: Array<keyof DataViewState>;
+}
+/**
+ * Debounce in milliseconds for request emission on filter and search changes. A single number
+ * applies to both. An object sets a separate timing for each field.
+ */
+export type DebounceOptions = number | {
+    globalFilter?: number;
+    columnFilters?: number;
+};
+export interface UseDataViewOptions<TData> {
+    columns: DataColumnDef<TData>[];
+    rows: TData[];
+    /** Total rows across all pages, for page math. */
+    rowCount: number;
+    status: Status;
+    error?: unknown;
+    /**
+     * Stable identity. It is required for selection that survives paging. It is wrapped in
+     * `NoInfer` so `TData` is pinned by `rows` and `columns`, not by this callback.
+     */
+    getRowId: (row: NoInfer<TData>) => string;
+    /** Fired whenever view state changes. Turn it into a fetch and feed `rows` back in. */
+    onRequestChange?: (request: DataViewRequest) => void;
+    initialState?: Partial<DataViewState>;
+    state?: Partial<DataViewState>;
+    onStateChange?: (state: DataViewState) => void;
+    /** Default `'table'`. */
+    defaultView?: ViewMode;
+    /** Default `[10, 25, 50, 100]`. */
+    pageSizeOptions?: number[];
+    enableRowSelection?: boolean | ((row: NoInfer<TData>) => boolean);
+    enableGlobalFilter?: boolean;
+    debounce?: DebounceOptions;
+    responsive?: ResponsiveOptions;
+    urlSync?: UrlSyncOptions;
+    /** Table-level format defaults keyed by data type. Column-level `format` overrides these. */
+    formatDefaults?: Partial<Record<ColumnDataType, ColumnFormatOption>>;
+    /** Facet aggregation data from the server, keyed by column ID. */
+    facets?: Record<string, FacetData>;
+}
+/** Current selection, derived from `rowSelection` keyed by `getRowId`. */
+export interface DataViewSelection<TData> {
+    count: number;
+    /** Ids of every selected row across all pages. This is the stable basis for bulk actions. */
+    ids: string[];
+    /** Selected rows present on the current page. The core holds no data for other pages. */
+    rows: TData[];
+    clear: () => void;
+}
+export interface UseDataViewReturn<TData> {
+    /** The underlying v8 instance, offered as an escape hatch. */
+    table: Table<TData>;
+    /** Current normalized request. */
+    request: DataViewRequest;
+    state: DataViewState;
+    view: ViewMode;
+    setView: (v: ViewMode) => void;
+    /** True when the responsive rule forces cards. */
+    isMobileForced: boolean;
+    status: Status;
+    error: unknown;
+    /** Renderer facing state. One of loading, empty, filtered empty, error, or ready. */
+    renderStatus: DataViewStatus;
+    /** Emit the current request again. The error state retry uses this. */
+    refetch: () => void;
+    /** Resolved page size choices for the pager. The default is `[10, 25, 50, 100]`. */
+    pageSizeOptions: number[];
+    sortableColumns: Column<TData>[];
+    filterableColumns: Column<TData>[];
+    selection: DataViewSelection<TData>;
+    /** Export visible columns and current page rows as a CSV file download. */
+    exportCsv: (options?: ExportCsvOptions) => void;
+    /** Latest facet data from the server response, keyed by column ID. */
+    facets: Record<string, FacetData>;
+}

package/dist/types/request.d.ts

@@ -0,0 +1,18 @@
+import { FacetData } from './facets';
+import { DataViewFilter, DataViewPagination, DataViewSort } from './state';
+/** Emitted by the core whenever view state changes. The consumer turns it into a fetch. */
+export interface DataViewRequest {
+    pagination: DataViewPagination;
+    sorting: DataViewSort[];
+    /** Filters keyed by column. The `value` shape depends on the filter variant. */
+    filters: DataViewFilter[];
+    globalFilter: string;
+}
+/** What the consumer feeds back in for the current page. */
+export interface DataViewResponse<TData> {
+    rows: TData[];
+    /** Total rows across all pages, used for page math. */
+    rowCount: number;
+    /** Optional facet aggregation data, keyed by column ID. */
+    facets?: Record<string, FacetData>;
+}

package/dist/types/state.d.ts

@@ -0,0 +1,57 @@
+/** The two presentations that one core state instance can be projected into. */
+export type ViewMode = "table" | "cards";
+/** Raw fetch lifecycle reported by the consumer. */
+export type Status = "idle" | "loading" | "success" | "error";
+export interface DataViewPagination {
+    pageIndex: number;
+    pageSize: number;
+}
+export interface DataViewSort {
+    id: string;
+    desc: boolean;
+}
+export interface DataViewFilter {
+    /** Column id the filter is keyed by. */
+    id: string;
+    /** Value shape depends on the column's filter variant. */
+    value: unknown;
+}
+/**
+ * The single source of truth for every feature. All affordances such as table headers, card
+ * overlays, and toolbar controls are projections of this object, keyed by column id.
+ */
+/** Columns pinned to the left or right edge of the table. */
+export interface DataViewColumnPinning {
+    left?: string[];
+    right?: string[];
+}
+export interface DataViewState {
+    pagination: DataViewPagination;
+    sorting: DataViewSort[];
+    columnFilters: DataViewFilter[];
+    globalFilter: string;
+    /** Keyed by `getRowId`, so selection survives paging and refetches. */
+    rowSelection: Record<string, boolean>;
+    columnVisibility: Record<string, boolean>;
+    columnPinning: DataViewColumnPinning;
+    view: ViewMode;
+}
+/**
+ * Derived renderer facing status as a discriminated union. Both presentations switch over it
+ * exhaustively so the four states stay consistent across views. Those states are loading, empty,
+ * filtered empty, and error. There are also idle and the populated `ready` state.
+ */
+export type DataViewStatus = {
+    phase: "idle";
+} | {
+    phase: "loading";
+} | {
+    phase: "ready";
+} | {
+    phase: "empty";
+} | {
+    phase: "empty-filtered";
+} | {
+    phase: "error";
+    error: unknown;
+};

package/dist/url/index.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../serializer-CGmBq-Jz.cjs");function t(){return{read(){return Object.fromEntries(new URLSearchParams(window.location.search).entries())},write(e,t){let n=new URLSearchParams(e),r=`${window.location.pathname}?${n.toString()}${window.location.hash}`;t?.replace?window.history.replaceState(null,``,r):window.history.pushState(null,``,r)},subscribe(e){return window.addEventListener(`popstate`,e),()=>window.removeEventListener(`popstate`,e)}}}exports.defaultUrlSerializer=e.t,exports.deserializeParams=e.n,exports.resolveInclude=e.r,exports.serializeState=e.i,exports.windowHistoryAdapter=t;
+//# sourceMappingURL=index.cjs.map

package/dist/url/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/url/index.ts"],"sourcesContent":["// Subpath entry for @ethanhann/mantine-dataview/url.\n// It exports windowHistoryAdapter and the serializer utilities.\n\nimport type { UrlStateAdapter } from \"./types\";\n\n// Serializer utilities for consumers building custom adapters or param schemes.\nexport {\n\tdefaultUrlSerializer,\n\tdeserializeParams,\n\tresolveInclude,\n\ttype SyncableKey,\n\tserializeState,\n} from \"./serializer\";\nexport type { UrlSerializer, UrlStateAdapter } from \"./types\";\n\n/** Default adapter built on the History API. It has no dependencies. */\nexport function windowHistoryAdapter(): UrlStateAdapter {\n\treturn {\n\t\tread() {\n\t\t\treturn Object.fromEntries(\n\t\t\t\tnew URLSearchParams(window.location.search).entries(),\n\t\t\t);\n\t\t},\n\t\twrite(next, opts) {\n\t\t\tconst params = new URLSearchParams(next);\n\t\t\tconst url = `${window.location.pathname}?${params.toString()}${window.location.hash}`;\n\t\t\tif (opts?.replace) {\n\t\t\t\twindow.history.replaceState(null, \"\", url);\n\t\t\t} else {\n\t\t\t\twindow.history.pushState(null, \"\", url);\n\t\t\t}\n\t\t},\n\t\tsubscribe(onChange) {\n\t\t\twindow.addEventListener(\"popstate\", onChange);\n\t\t\treturn () => window.removeEventListener(\"popstate\", onChange);\n\t\t},\n\t};\n}\n"],"mappings":"iHAgBA,SAAgB,GAAwC,CACvD,MAAO,CACN,MAAO,CACN,OAAO,OAAO,YACb,IAAI,gBAAgB,OAAO,SAAS,MAAM,EAAE,QAAQ,CACrD,CACD,EACA,MAAM,EAAM,EAAM,CACjB,IAAM,EAAS,IAAI,gBAAgB,CAAI,EACjC,EAAM,GAAG,OAAO,SAAS,SAAS,GAAG,EAAO,SAAS,IAAI,OAAO,SAAS,OAC3E,GAAM,QACT,OAAO,QAAQ,aAAa,KAAM,GAAI,CAAG,EAEzC,OAAO,QAAQ,UAAU,KAAM,GAAI,CAAG,CAExC,EACA,UAAU,EAAU,CAEnB,OADA,OAAO,iBAAiB,WAAY,CAAQ,MAC/B,OAAO,oBAAoB,WAAY,CAAQ,CAC7D,CACD,CACD"}

package/dist/url/index.d.ts

@@ -0,0 +1,5 @@
+import { UrlStateAdapter } from './types';
+export { defaultUrlSerializer, deserializeParams, resolveInclude, type SyncableKey, serializeState, } from './serializer';
+export type { UrlSerializer, UrlStateAdapter } from './types';
+/** Default adapter built on the History API. It has no dependencies. */
+export declare function windowHistoryAdapter(): UrlStateAdapter;

package/dist/url/index.js

@@ -0,0 +1,20 @@
+import { i as e, n as t, r as n, t as r } from "../serializer-u2zq_sU7.js";
+//#region src/url/index.ts
+function i() {
+	return {
+		read() {
+			return Object.fromEntries(new URLSearchParams(window.location.search).entries());
+		},
+		write(e, t) {
+			let n = new URLSearchParams(e), r = `${window.location.pathname}?${n.toString()}${window.location.hash}`;
+			t?.replace ? window.history.replaceState(null, "", r) : window.history.pushState(null, "", r);
+		},
+		subscribe(e) {
+			return window.addEventListener("popstate", e), () => window.removeEventListener("popstate", e);
+		}
+	};
+}
+//#endregion
+export { r as defaultUrlSerializer, t as deserializeParams, n as resolveInclude, e as serializeState, i as windowHistoryAdapter };
+
+//# sourceMappingURL=index.js.map

package/dist/url/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/url/index.ts"],"sourcesContent":["// Subpath entry for @ethanhann/mantine-dataview/url.\n// It exports windowHistoryAdapter and the serializer utilities.\n\nimport type { UrlStateAdapter } from \"./types\";\n\n// Serializer utilities for consumers building custom adapters or param schemes.\nexport {\n\tdefaultUrlSerializer,\n\tdeserializeParams,\n\tresolveInclude,\n\ttype SyncableKey,\n\tserializeState,\n} from \"./serializer\";\nexport type { UrlSerializer, UrlStateAdapter } from \"./types\";\n\n/** Default adapter built on the History API. It has no dependencies. */\nexport function windowHistoryAdapter(): UrlStateAdapter {\n\treturn {\n\t\tread() {\n\t\t\treturn Object.fromEntries(\n\t\t\t\tnew URLSearchParams(window.location.search).entries(),\n\t\t\t);\n\t\t},\n\t\twrite(next, opts) {\n\t\t\tconst params = new URLSearchParams(next);\n\t\t\tconst url = `${window.location.pathname}?${params.toString()}${window.location.hash}`;\n\t\t\tif (opts?.replace) {\n\t\t\t\twindow.history.replaceState(null, \"\", url);\n\t\t\t} else {\n\t\t\t\twindow.history.pushState(null, \"\", url);\n\t\t\t}\n\t\t},\n\t\tsubscribe(onChange) {\n\t\t\twindow.addEventListener(\"popstate\", onChange);\n\t\t\treturn () => window.removeEventListener(\"popstate\", onChange);\n\t\t},\n\t};\n}\n"],"mappings":";;AAgBA,SAAgB,IAAwC;CACvD,OAAO;EACN,OAAO;GACN,OAAO,OAAO,YACb,IAAI,gBAAgB,OAAO,SAAS,MAAM,EAAE,QAAQ,CACrD;EACD;EACA,MAAM,GAAM,GAAM;GACjB,IAAM,IAAS,IAAI,gBAAgB,CAAI,GACjC,IAAM,GAAG,OAAO,SAAS,SAAS,GAAG,EAAO,SAAS,IAAI,OAAO,SAAS;GAC/E,AAAI,GAAM,UACT,OAAO,QAAQ,aAAa,MAAM,IAAI,CAAG,IAEzC,OAAO,QAAQ,UAAU,MAAM,IAAI,CAAG;EAExC;EACA,UAAU,GAAU;GAEnB,OADA,OAAO,iBAAiB,YAAY,CAAQ,SAC/B,OAAO,oBAAoB,YAAY,CAAQ;EAC7D;CACD;AACD"}

package/dist/url/serializer.d.ts

@@ -0,0 +1,33 @@
+import { ColumnFilterMeta } from '../types/column';
+import { DataViewState } from '../types/state';
+import { UrlSerializer } from './types';
+export type SyncableKey = "pagination" | "sorting" | "columnFilters" | "globalFilter" | "view";
+export declare const SYNCABLE_KEYS: readonly SyncableKey[];
+type FilterMetaLookup = (id: string) => ColumnFilterMeta | undefined;
+/** Default param names and a filter codec for each variant. Every field can be overridden. */
+export declare const defaultUrlSerializer: UrlSerializer;
+/** Resolves the `include` option to the supported, syncable subset. The default is all of them. */
+export declare function resolveInclude(include?: Array<keyof DataViewState>): SyncableKey[];
+export interface SerializeContext {
+    serializer: UrlSerializer;
+    include: SyncableKey[];
+    getFilterMeta?: FilterMetaLookup;
+}
+/**
+ * Serializes the included slices to query params. Empty or default values are omitted to keep
+ * the URL clean. The page is emitted only past the first page, counting from one. Empty search,
+ * sort, and filter values drop out entirely.
+ */
+export declare function serializeState(state: DataViewState, { serializer, include, getFilterMeta }: SerializeContext): Record<string, string>;
+export interface DeserializeContext extends SerializeContext {
+    /** Fallback for slices not present in the URL (defaults on hydrate, current on popstate). */
+    current: DataViewState;
+}
+/**
+ * Parses query params into a state patch. The URL is authoritative for every included slice. An
+ * absent sort, search, or filter means none, and an absent page means the first page.
+ */
+export declare function deserializeParams(params: Record<string, string>, { serializer, include, getFilterMeta, current }: DeserializeContext): Partial<DataViewState>;
+/** Remove the params this serializer manages (for the included slices), preserving the rest. */
+export declare function stripManagedParams(params: Record<string, string>, serializer: UrlSerializer, include: SyncableKey[]): Record<string, string>;
+export {};

package/dist/url/types.d.ts

@@ -0,0 +1,23 @@
+import { ColumnFilterMeta } from '../types/column';
+export interface UrlStateAdapter {
+    /** Current query params as a flat record. */
+    read(): Record<string, string>;
+    /** Write the next params. The `replace` flag chooses between a new history entry and a push. */
+    write(next: Record<string, string>, opts?: {
+        replace?: boolean;
+    }): void;
+    /** Optional. Notifies on external navigation such as back or forward. Returns a cleanup. */
+    subscribe?(onChange: () => void): () => void;
+}
+export interface UrlSerializer {
+    page: string;
+    size: string;
+    sort: string;
+    search: string;
+    view: string;
+    /** Prefix for column filters. For example `f.` produces `f.<columnId>=<encoded>`. */
+    filterPrefix: string;
+    /** The column's filter meta, its variant and options, selects the codec. */
+    encodeFilter(columnId: string, value: unknown, meta?: ColumnFilterMeta): string;
+    decodeFilter(columnId: string, raw: string, meta?: ColumnFilterMeta): unknown;
+}

package/dist/url/useUrlSync.d.ts

@@ -0,0 +1,23 @@
+import { ColumnFilterMeta } from '../types/column';
+import { UrlSyncOptions } from '../types/options';
+import { DataViewState } from '../types/state';
+import { SyncableKey } from './serializer';
+import { UrlSerializer, UrlStateAdapter } from './types';
+type FilterMetaLookup = (id: string) => ColumnFilterMeta | undefined;
+export interface ResolvedUrlConfig {
+    adapter: UrlStateAdapter;
+    serializer: UrlSerializer;
+    include: SyncableKey[];
+}
+/** Merges the consumer's `urlSync` options with defaults, or returns `null` when sync is off. */
+export declare function resolveUrlConfig(urlSync: UrlSyncOptions | undefined): ResolvedUrlConfig | null;
+/** Reads the URL once and produces the initial state patch. It is safe to call during render. */
+export declare function hydrateFromUrl(config: ResolvedUrlConfig | null, current: DataViewState, getFilterMeta: FilterMetaLookup): Partial<DataViewState>;
+interface UseUrlSyncArgs {
+    config: ResolvedUrlConfig | null;
+    state: DataViewState;
+    applyPatch: (patch: Partial<DataViewState>) => void;
+    getFilterMeta: FilterMetaLookup;
+}
+export declare function useUrlSync({ config, state, applyPatch, getFilterMeta, }: UseUrlSyncArgs): void;
+export {};

package/package.json

@@ -0,0 +1,90 @@
+{
+	"name": "@ethanhann/mantine-dataview",
+	"version": "0.1.0",
+	"description": "A React library that renders server-driven, paginated datasets as a table or card grid, switchable at runtime, built on Mantine v9 and TanStack Table v8",
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./url": {
+			"types": "./dist/url/index.d.ts",
+			"import": "./dist/url/index.js",
+			"require": "./dist/url/index.cjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"scripts": {
+		"dev": "storybook dev -p 6006",
+		"build": "vite build",
+		"test": "vitest",
+		"test:run": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"typecheck": "tsc --noEmit",
+		"storybook:build": "storybook build",
+		"prepublishOnly": "npm run build"
+	},
+	"peerDependencies": {
+		"@mantine/core": "^9.0.0",
+		"@mantine/dates": "^9.0.0",
+		"@mantine/hooks": "^9.0.0",
+		"@tanstack/react-table": "^8.0.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0"
+	},
+	"devDependencies": {
+		"@axe-core/react": "^4.11.1",
+		"@biomejs/biome": "2.4.16",
+		"@mantine/code-highlight": "^9.3.0",
+		"@mantine/core": "^9.3.0",
+		"@mantine/dates": "^9.3.0",
+		"@mantine/hooks": "^9.3.0",
+		"@storybook/addon-a11y": "^10.3.4",
+		"@storybook/react": "^10.3.4",
+		"@storybook/react-vite": "^10.3.4",
+		"@tabler/icons-react": "^3.41.1",
+		"@tanstack/react-table": "^8.21.3",
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
+		"@types/bun": "^1.3.11",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^6.0.1",
+		"@vitest/coverage-v8": "^4.1.2",
+		"dayjs": "^1.11.21",
+		"highlight.js": "^11.11.1",
+		"jsdom": "^29.0.1",
+		"postcss": "^8.5.8",
+		"postcss-preset-mantine": "^1.18.0",
+		"postcss-simple-vars": "^7.0.1",
+		"react": "^19.2.4",
+		"react-dom": "^19.2.4",
+		"storybook": "^10.3.4",
+		"typescript": "^6.0.2",
+		"unplugin-dts": "^1.0.2",
+		"vite": "^8.0.3",
+		"vitest": "^4.1.2",
+		"vitest-axe": "^0.1.0",
+		"vitest-canvas-mock": "^1.1.4"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ethanhann/mantine-grid.git"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org"
+	},
+	"license": "MIT"
+}