(null);
+
+ return {
+ filterIcon: (filtered: boolean) => (
+
+ ),
+ filterDropdown: ({ selectedKeys, setSelectedKeys, confirm, clearFilters }: FilterDropdownProps) => (
+ e.stopPropagation()}>
+ setSelectedKeys(e.target.value ? [e.target.value] : [])}
+ onSearch={() => confirm({ closeDropdown: true })}
+ onClear={() => {
+ clearFilters?.({ closeDropdown: false });
+ confirm({ closeDropdown: true });
+ }}
+ />
+
+ ),
+ filterDropdownProps: {
+ onOpenChange: (open: boolean) => {
+ if (open) {
+ setTimeout(() => searchInput.current?.select(), 100);
+ }
+ },
+ },
+ onFilter: (value: React.Key | boolean, record: T) => (
+ getText(record).toLowerCase().includes(String(value).toLowerCase())
+ ),
+ };
+}
diff --git a/packages/web_ui/src/index.ts b/packages/web_ui/src/index.ts
index 8ced5c7c..e870e173 100644
--- a/packages/web_ui/src/index.ts
+++ b/packages/web_ui/src/index.ts
@@ -42,3 +42,6 @@ export { default as SectionHeader } from "./components/SectionHeader";
export { default as Link } from "./components/Link";
export { default as FactorioIcon } from "./components/FactorioIcon";
+
+export { default as useTableQueryState } from "./util/useTableQueryState";
+export { default as useColumnSearch } from "./components/useColumnSearch";
diff --git a/packages/web_ui/src/util/tableQuery.ts b/packages/web_ui/src/util/tableQuery.ts
new file mode 100644
index 00000000..27e3ae81
--- /dev/null
+++ b/packages/web_ui/src/util/tableQuery.ts
@@ -0,0 +1,168 @@
+/**
+ * Pure helpers for storing antd Table state (sort / filters / pagination) in
+ * the URL query string. Kept free of React and antd runtime imports so the
+ * serialisation can be unit tested in isolation.
+ *
+ * Every parameter is namespaced with the table's name so the URL is
+ * self-describing and two tables could coexist on one page without colliding:
+ * .sort column key the table is sorted by
+ * .order "ascend" | "descend"
+ * .page 1-based page number
+ * .pageSize rows per page
+ * . filter value for that column (e.g. user.name, user.admin)
+ *
+ * `prefix` below is the namespace with its trailing dot, e.g. "user.".
+ * Multi-value filters use a repeated parameter (`user.roles=1&user.roles=2`)
+ * so URLSearchParams handles all encoding/decoding exactly once.
+ */
+
+export type SortOrder = "ascend" | "descend";
+
+export interface TableSortState {
+ /** Column key the table is sorted by, or undefined for no/default sort. */
+ columnKey?: string;
+ /** Sort direction, or undefined when unsorted. */
+ order?: SortOrder;
+}
+
+export interface TablePageState {
+ page: number;
+ pageSize: number;
+}
+
+/** A single filter value as produced by antd (React.Key is string | number | bigint). */
+export type FilterValue = string | number | bigint | boolean;
+
+/**
+ * Maps a single column's antd filter value to/from one or more query
+ * parameters. Lets a column that bundles several controls (e.g. the user
+ * filter) persist as separate readable params instead of one opaque blob.
+ * `prefix` is the table namespace with its trailing dot, e.g. "user.".
+ */
+export interface FilterCodec {
+ /** Read this column's `filteredValue` from the query, or null when inactive. */
+ decode(params: URLSearchParams, prefix: string): string[] | null;
+ /** Write this column's antd filter value into `params` (mutating). */
+ encode(params: URLSearchParams, value: ReadonlyArray | null, prefix: string): void;
+}
+
+/** Suffixes reserved for table-level state; any other `` is a column filter. */
+const RESERVED_SUFFIXES = new Set(["sort", "order", "page", "pageSize"]);
+
+/** Parse an order parameter, returning undefined for anything unexpected. */
+export function parseOrder(value: string | null): SortOrder | undefined {
+ return value === "ascend" || value === "descend" ? value : undefined;
+}
+
+/**
+ * Read the sort state from the query, falling back to the supplied defaults
+ * when no (valid) sort parameter is present.
+ */
+export function parseSort(
+ params: URLSearchParams,
+ prefix: string,
+ defaultKey?: string,
+ defaultOrder: SortOrder = "ascend",
+): TableSortState {
+ const columnKey = params.get(`${prefix}sort`);
+ if (!columnKey) {
+ return { columnKey: defaultKey, order: defaultKey ? defaultOrder : undefined };
+ }
+ return { columnKey, order: parseOrder(params.get(`${prefix}order`)) ?? defaultOrder };
+}
+
+/** Read pagination state from the query, tolerating missing/garbage values. */
+export function parsePagination(
+ params: URLSearchParams,
+ prefix: string,
+ defaultPageSize: number,
+ defaultPage = 1,
+): TablePageState {
+ const page = Number.parseInt(params.get(`${prefix}page`) ?? "", 10);
+ const pageSize = Number.parseInt(params.get(`${prefix}pageSize`) ?? "", 10);
+ return {
+ page: Number.isInteger(page) && page >= 1 ? page : defaultPage,
+ pageSize: Number.isInteger(pageSize) && pageSize >= 1 ? pageSize : defaultPageSize,
+ };
+}
+
+/** Collect every namespaced column-filter parameter into a map of column key -> values. */
+export function parseFilters(params: URLSearchParams, prefix: string): Record {
+ const filters: Record = {};
+ for (const key of params.keys()) {
+ if (key.startsWith(prefix)) {
+ const column = key.slice(prefix.length);
+ if (!RESERVED_SUFFIXES.has(column) && !(column in filters)) {
+ filters[column] = params.getAll(key);
+ }
+ }
+ }
+ return filters;
+}
+
+/**
+ * Write the sort state into `params` (mutating it). The parameters are omitted
+ * when the sort matches the table default or is cleared, keeping default URLs
+ * clean.
+ */
+export function applySort(
+ params: URLSearchParams,
+ prefix: string,
+ sort: TableSortState,
+ defaultKey?: string,
+ defaultOrder: SortOrder = "ascend",
+): void {
+ const { columnKey, order } = sort;
+ const isDefault = columnKey === defaultKey && (order ?? defaultOrder) === defaultOrder;
+ if (!columnKey || !order || isDefault) {
+ params.delete(`${prefix}sort`);
+ params.delete(`${prefix}order`);
+ return;
+ }
+ params.set(`${prefix}sort`, columnKey);
+ params.set(`${prefix}order`, order);
+}
+
+/**
+ * Write the filter state into `params` (mutating it). `filters` is the object
+ * antd hands to onChange: every filterable column key mapped to its current
+ * value array, or null when inactive.
+ */
+export function applyFilters(
+ params: URLSearchParams,
+ prefix: string,
+ filters: Record | null>,
+): void {
+ for (const [key, values] of Object.entries(filters)) {
+ const param = prefix + key;
+ params.delete(param);
+ if (values) {
+ for (const value of values) {
+ params.append(param, String(value));
+ }
+ }
+ }
+}
+
+/**
+ * Write pagination into `params` (mutating it). Defaults (page 1 / default
+ * page size) are omitted to keep URLs clean.
+ */
+export function applyPagination(
+ params: URLSearchParams,
+ prefix: string,
+ page: number,
+ pageSize: number,
+ defaultPageSize: number,
+): void {
+ if (page > 1) {
+ params.set(`${prefix}page`, String(page));
+ } else {
+ params.delete(`${prefix}page`);
+ }
+ if (pageSize !== defaultPageSize) {
+ params.set(`${prefix}pageSize`, String(pageSize));
+ } else {
+ params.delete(`${prefix}pageSize`);
+ }
+}
diff --git a/packages/web_ui/src/util/useTableQueryState.ts b/packages/web_ui/src/util/useTableQueryState.ts
new file mode 100644
index 00000000..3d471ac9
--- /dev/null
+++ b/packages/web_ui/src/util/useTableQueryState.ts
@@ -0,0 +1,105 @@
+import { useSearchParams } from "react-router-dom";
+import type { TablePaginationConfig } from "antd";
+import type { ColumnType, FilterValue, SorterResult } from "antd/es/table/interface";
+
+import {
+ applyFilters, applyPagination, applySort,
+ parseFilters, parsePagination, parseSort,
+ type FilterCodec, type SortOrder,
+} from "./tableQuery";
+
+export interface TableQueryStateOptions {
+ /** Table name used to namespace every query parameter, e.g. "user" -> `user.sort`, `user.name`. */
+ namespace: string;
+ /** Column key sorted by default (no `sort` param present). Omit for no default sort. */
+ defaultSortKey?: string;
+ /** Direction of the default sort. Default "ascend". */
+ defaultSortOrder?: SortOrder;
+ /** Pass an object to persist pagination; omit/false for `pagination={false}` tables. */
+ pagination?: false | { defaultPageSize?: number };
+ /** Per-column-key codecs to persist a bundled filter value as separate readable params. */
+ filterCodecs?: Record;
+}
+
+export interface TableQueryState {
+ /** Spread onto `` to persist sort/filter/pagination (pushes history). */
+ onChange: (
+ pagination: TablePaginationConfig,
+ filters: Record,
+ sorter: SorterResult | SorterResult[],
+ ) => void;
+ /** Wrap each column to inject controlled `sortOrder`/`filteredValue` from the URL. */
+ applyColumn: (column: ColumnType) => ColumnType;
+ /** Controlled pagination ({@link current}/{@link pageSize}), or `false` when disabled. */
+ pagination: false | TablePaginationConfig;
+ /** The active column filters parsed from the URL, keyed by column key. */
+ filters: Record;
+}
+
+/**
+ * Persist an antd Table's sort, column filters and pagination into the URL
+ * query string, so reload, link-sharing and browser back/forward restore the
+ * same view (clusterio issue #927).
+ */
+export default function useTableQueryState(options: TableQueryStateOptions): TableQueryState {
+ const { defaultSortKey, defaultSortOrder = "ascend" } = options;
+ const prefix = `${options.namespace}.`;
+ const codecs = options.filterCodecs ?? {};
+ const paginationOptions = options.pagination && typeof options.pagination === "object"
+ ? options.pagination
+ : undefined;
+ const paginationEnabled = paginationOptions !== undefined;
+ const defaultPageSize = paginationOptions?.defaultPageSize ?? 10;
+
+ const [params, setParams] = useSearchParams();
+
+ const sort = parseSort(params, prefix, defaultSortKey, defaultSortOrder);
+ const filters = parseFilters(params, prefix);
+ const page = paginationEnabled ? parsePagination(params, prefix, defaultPageSize) : undefined;
+
+ return {
+ onChange(pagination, tableFilters, sorter) {
+ const single = Array.isArray(sorter) ? sorter[0] : sorter;
+ const order = single && single.order ? single.order : undefined;
+ const columnKey = order ? String(single.columnKey ?? single.field ?? "") : undefined;
+
+ const next = new URLSearchParams(params);
+ applySort(next, prefix, { columnKey, order }, defaultSortKey, defaultSortOrder);
+ const plainFilters: Record = {};
+ for (const [key, values] of Object.entries(tableFilters)) {
+ const codec = codecs[key];
+ if (codec) {
+ codec.encode(next, values, prefix);
+ } else {
+ plainFilters[key] = values;
+ }
+ }
+ applyFilters(next, prefix, plainFilters);
+ if (paginationEnabled) {
+ applyPagination(
+ next, prefix, pagination.current ?? 1, pagination.pageSize ?? defaultPageSize, defaultPageSize
+ );
+ }
+ setParams(next);
+ },
+
+ applyColumn(column) {
+ const key = String(column.key ?? column.dataIndex ?? "");
+ const next: ColumnType = { ...column };
+ if (column.sorter) {
+ next.sortOrder = key === sort.columnKey ? (sort.order ?? null) : null;
+ }
+ if (column.filters || column.onFilter || column.filterDropdown) {
+ const codec = codecs[key];
+ next.filteredValue = codec ? codec.decode(params, prefix) : (filters[key] ?? null);
+ }
+ return next;
+ },
+
+ pagination: paginationEnabled && page
+ ? { current: page.page, pageSize: page.pageSize }
+ : false,
+
+ filters,
+ };
+}
diff --git a/plugins/subspace_storage/web/index.tsx b/plugins/subspace_storage/web/index.tsx
index 63f669d7..a90d803c 100644
--- a/plugins/subspace_storage/web/index.tsx
+++ b/plugins/subspace_storage/web/index.tsx
@@ -1,16 +1,16 @@
import { useContext, useEffect, useState } from "react";
-import { Input, Table, Typography } from "antd";
+import { Table } from "antd";
+import type { ColumnsType } from "antd/es/table";
import {
BaseWebPlugin, PageLayout, PageHeader, Control, ControlContext, notifyErrorHandler,
useExportLocale, useExportPrototypeMetadata, useDefaultModPack, FactorioIcon,
+ useTableQueryState, useColumnSearch,
} from "@clusterio/web_ui";
import { GetStorageRequest, Item, SetStorageSubscriptionRequest, UpdateStorageEvent } from "../messages";
import "./style.css";
-const { Paragraph } = Typography;
-
function useStorage(control: Control) {
let plugin = control.plugins.get("subspace_storage") as WebPlugin;
@@ -37,8 +37,10 @@ function StoragePage() {
let itemMetadata = prototypes?.get("item");
let fluidMetadata = prototypes?.get("fluid");
let storage = useStorage(control);
- type ItemFilter = ([name, item]: [string, Item]) => boolean;
- let [filter, setFilter] = useState(null);
+ const tableState = useTableQueryState<[string, Item]>({
+ namespace: "storage", defaultSortKey: "quantity", defaultSortOrder: "descend", pagination: false,
+ });
+ const resourceSearch = useColumnSearch<[string, Item]>(item => getLocaleName(item[1].name), "Search");
function getLocaleName(itemName: string) {
let localeName = itemName;
@@ -65,33 +67,32 @@ function StoragePage() {
let numberFormat = new Intl.NumberFormat("en-US");
+ // Build the regex the resource search uses: word-boundary anchored, spaces match any gap.
+ function matchesResource(value: string | number | bigint | boolean, item: [string, Item]) {
+ let search = String(value).trim();
+ if (!search) {
+ return true;
+ }
+ search = search.replace(/(^| )(\w)/g, "$1\\b$2").replace(/ +/g, ".*");
+ let filterExpr;
+ try {
+ filterExpr = new RegExp(search, "i");
+ } catch {
+ return true;
+ }
+ return filterExpr.test(getLocaleName(item[1].name)) || filterExpr.test(item[1].name);
+ }
+
return
-
- {
- let search = event.target.value.trim();
- if (!search) {
- setFilter(null);
- return;
- }
- search = search.replace(/(^| )(\w)/g, "$1\\b$2");
- search = search.replace(/ +/g, ".*");
- let filterExpr = new RegExp(search, "i");
- setFilter(() => ((item: [string, Item]) => {
- let name = getLocaleName(item[1].name);
- return filterExpr.test(name) || filterExpr.test(item[1].name);
- }));
- }}
- />
-
{
let aName = getLocaleName(a[1].name);
let bName = getLocaleName(b[1].name);
@@ -119,14 +120,14 @@ function StoragePage() {
title: "Quantity",
key: "quantity",
align: "right",
- defaultSortOrder: "descend",
sorter: (a, b) => a[1].count - b[1].count,
render: (_, item) => numberFormat.format(item[1].count),
},
- ]}
- dataSource={filter ? storage.filter(filter) : storage}
+ ] satisfies ColumnsType<[string, Item]>).map(tableState.applyColumn)}
+ dataSource={storage}
rowKey={item => item[0]}
- pagination={false}
+ pagination={tableState.pagination}
+ onChange={tableState.onChange}
/>
;
}
diff --git a/test/web_ui/tableQuery.js b/test/web_ui/tableQuery.js
new file mode 100644
index 00000000..12656ce1
--- /dev/null
+++ b/test/web_ui/tableQuery.js
@@ -0,0 +1,105 @@
+"use strict";
+const assert = require("assert").strict;
+const {
+ parseOrder, parseSort, parsePagination, parseFilters,
+ applySort, applyFilters, applyPagination,
+} = require("@clusterio/web_ui/dist/browser/src/util/tableQuery");
+
+// All helpers take the table namespace prefix (with trailing dot) as 2nd arg.
+const P = "t.";
+
+describe("web_ui/util/tableQuery", function() {
+ describe("parseOrder", function() {
+ it("accepts ascend/descend and rejects anything else", function() {
+ assert.equal(parseOrder("ascend"), "ascend");
+ assert.equal(parseOrder("descend"), "descend");
+ assert.equal(parseOrder("sideways"), undefined);
+ assert.equal(parseOrder(null), undefined);
+ });
+ });
+
+ describe("parseSort", function() {
+ it("falls back to the supplied defaults when absent", function() {
+ assert.deepEqual(parseSort(new URLSearchParams(""), P, "name"), { columnKey: "name", order: "ascend" });
+ assert.deepEqual(parseSort(new URLSearchParams(""), P), { columnKey: undefined, order: undefined });
+ });
+ it("reads an explicit namespaced sort column and order", function() {
+ assert.deepEqual(
+ parseSort(new URLSearchParams("t.sort=cpu&t.order=descend"), P, "name"),
+ { columnKey: "cpu", order: "descend" }
+ );
+ });
+ });
+
+ describe("parsePagination", function() {
+ it("uses defaults for missing or garbage values", function() {
+ assert.deepEqual(parsePagination(new URLSearchParams(""), P, 50), { page: 1, pageSize: 50 });
+ assert.deepEqual(
+ parsePagination(new URLSearchParams("t.page=x&t.pageSize=-3"), P, 50), { page: 1, pageSize: 50 }
+ );
+ });
+ it("reads valid values", function() {
+ assert.deepEqual(
+ parsePagination(new URLSearchParams("t.page=3&t.pageSize=20"), P, 50), { page: 3, pageSize: 20 }
+ );
+ });
+ });
+
+ describe("parseFilters", function() {
+ it("collects namespaced column filters but excludes reserved suffixes", function() {
+ const params = new URLSearchParams("t.roles=1&t.roles=2&t.sort=name&other.x=1");
+ assert.deepEqual(parseFilters(params, P), { roles: ["1", "2"] });
+ });
+ });
+
+ describe("applySort", function() {
+ it("omits parameters when the sort equals the default", function() {
+ const params = new URLSearchParams();
+ applySort(params, P, { columnKey: "name", order: "ascend" }, "name", "ascend");
+ assert.equal(params.toString(), "");
+ });
+ it("writes a namespaced non-default sort", function() {
+ const params = new URLSearchParams();
+ applySort(params, P, { columnKey: "cpu", order: "descend" }, "name", "ascend");
+ assert.equal(params.get("t.sort"), "cpu");
+ assert.equal(params.get("t.order"), "descend");
+ });
+ it("clears the sort when the order is cleared", function() {
+ const params = new URLSearchParams("t.sort=cpu&t.order=descend");
+ applySort(params, P, { columnKey: undefined, order: undefined }, "name", "ascend");
+ assert.equal(params.has("t.sort"), false);
+ assert.equal(params.has("t.order"), false);
+ });
+ });
+
+ describe("applyFilters", function() {
+ it("sets active filters as repeated params and deletes inactive ones", function() {
+ const params = new URLSearchParams("t.roles=old");
+ applyFilters(params, P, { roles: ["1", "2"], lastSeen: null });
+ assert.deepEqual(params.getAll("t.roles"), ["1", "2"]);
+ assert.equal(params.has("t.lastSeen"), false);
+ });
+ it("round-trips a JSON-blob filter value with single encoding", function() {
+ const params = new URLSearchParams();
+ const blob = '{"admin":false}';
+ applyFilters(params, P, { name: [blob] });
+ // Single-encoded (%7B…), not double-encoded (%257B…).
+ assert.equal(params.toString(), "t.name=%7B%22admin%22%3Afalse%7D");
+ assert.deepEqual(parseFilters(params, P), { name: [blob] });
+ });
+ });
+
+ describe("applyPagination", function() {
+ it("omits page 1 and the default page size", function() {
+ const params = new URLSearchParams();
+ applyPagination(params, P, 1, 50, 50);
+ assert.equal(params.toString(), "");
+ });
+ it("writes non-default page and page size", function() {
+ const params = new URLSearchParams();
+ applyPagination(params, P, 2, 20, 50);
+ assert.equal(params.get("t.page"), "2");
+ assert.equal(params.get("t.pageSize"), "20");
+ });
+ });
+});