@vinorcola/dynamic-table 1.3.0 → 1.4.1

package/lib/Dictionary.d.ts

@@ -1,10 +1,14 @@
-import type { ReactNode } from "react";
-import type { Primitive } from "./index.ts";
+import type { FC, ReactNode } from "react";
+import type { Primitive } from "./index.js";
 export interface DictionaryEntry {
     title: string;
     prepend?: ReactNode;
 }
+export type DictinaryValueWrapper = FC<{
+    children: ReactNode;
+}>;
 export default class Dictionary<Value extends Primitive> extends Map<Value, DictionaryEntry> {
     readonly unknownMessage: string;
-    constructor(unknownMessage: string, entries?: readonly (readonly [Value, DictionaryEntry])[] | null);
+    readonly valueWrapper: DictinaryValueWrapper;
+    constructor(unknownMessage: string, entries?: readonly (readonly [Value, DictionaryEntry])[] | null, valueWrapper?: DictinaryValueWrapper);
 }

package/lib/Dictionary.js

@@ -1,7 +1,9 @@
 export default class Dictionary extends Map {
     unknownMessage;
-    constructor(unknownMessage, entries) {
+    valueWrapper;
+    constructor(unknownMessage, entries, valueWrapper) {
         super(entries);
         this.unknownMessage = unknownMessage;
+        this.valueWrapper = valueWrapper ?? ((props) => props.children);
     }
 }

package/lib/StateWatcher/LocalStorageWatcher.d.ts

@@ -0,0 +1,5 @@
+import type { StateWatcherInterface } from ".";
+/**
+ * Generates a watcher that will save states in browser's LocalStorage.
+ */
+export default function generateLocalStorageWatcher(namespace: string): StateWatcherInterface;

package/lib/StateWatcher/LocalStorageWatcher.js

@@ -0,0 +1,38 @@
+function save(key, value) {
+    localStorage.setItem(key, JSON.stringify(value));
+}
+function load(key) {
+    return new Promise((resolve, reject) => {
+        try {
+            const storedValue = localStorage.getItem(key);
+            if (storedValue === null) {
+                return resolve(null);
+            }
+            return resolve(JSON.parse(storedValue));
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+function watch(key) {
+    return {
+        onChange(filterState) {
+            save(key, filterState);
+        },
+        loadInitial() {
+            return load(key);
+        },
+    };
+}
+/**
+ * Generates a watcher that will save states in browser's LocalStorage.
+ */
+export default function generateLocalStorageWatcher(namespace) {
+    return {
+        filterState: watch(`${namespace}-filter-state`),
+        sortState: watch(`${namespace}-sort-state`),
+        columnsMaskState: watch(`${namespace}-columns-mask-state`),
+        paginationState: watch(`${namespace}-pagination-state`),
+    };
+}

package/lib/StateWatcher/NoopWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { StateWatcherInterface } from ".";
+/**
+ * This watcher does nothing.
+ */
+declare const NoopWatcher: StateWatcherInterface;
+export default NoopWatcher;

package/lib/StateWatcher/NoopWatcher.js

@@ -0,0 +1,5 @@
+/**
+ * This watcher does nothing.
+ */
+const NoopWatcher = {};
+export default NoopWatcher;

package/lib/StateWatcher/index.d.ts

@@ -0,0 +1,14 @@
+import type { FilterState } from "../useFilterState";
+import type { ColumnsMaskState } from "../useMaskableColumns";
+import type { PaginationState } from "../usePagination";
+import type { SortState } from "../useSortState";
+export interface StateWatcherInterface {
+    filterState?: SpecificStateWatcher<FilterState>;
+    sortState?: SpecificStateWatcher<SortState>;
+    columnsMaskState?: SpecificStateWatcher<ColumnsMaskState>;
+    paginationState?: SpecificStateWatcher<PaginationState>;
+}
+export interface SpecificStateWatcher<State> {
+    onChange?(state: State): void;
+    loadInitial?(): Promise<State | null>;
+}

package/lib/StateWatcher/index.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -1,5 +1,6 @@
-import type { Key as ReactKey } from "react";
+import { type Key as ReactKey } from "react";
 import type { ColumnDefinition } from "./ColumnDefinition.js";
+import type { StateWatcherInterface } from "./StateWatcher/index.js";
 import { type FilterState } from "./useFilterState.js";
 import type { ColumnsMaskState } from "./useMaskableColumns.js";
 import { type PaginationState } from "./usePagination.js";
@@ -12,11 +13,14 @@ export type BaseItem = Record<string, any> & {
 export type ItemKey<Item extends BaseItem> = Extract<keyof Item, string>;
 export type { ColumnDefinition, ValueResolver } from "./ColumnDefinition.js";
 export { default as Dictionary, DictionaryEntry } from "./Dictionary.js";
+export type { StateWatcherInterface } from "./StateWatcher/index.js";
+export { default as LocalStorageWatcher } from "./StateWatcher/LocalStorageWatcher.js";
 export type { FilterState } from "./useFilterState.js";
 export type { SortDirection, SortState } from "./useSortState.js";
 export type { ColumnsMaskState } from "./useMaskableColumns.js";
 export type { PaginationState } from "./usePagination.js";
 interface BaseProps<Item extends BaseItem> {
+    namespace?: string;
     items: Item[];
     columns: ColumnDefinition<Item, Primitive>[];
     itemTarget?: (item: Item) => string;
@@ -24,6 +28,7 @@ interface BaseProps<Item extends BaseItem> {
     initialSortState?: SortState;
     initialColumnsMaskState?: ColumnsMaskState;
     initialPaginationState?: PaginationState;
+    watcher?: StateWatcherInterface;
 }
 type Props<Item extends BaseItem> = BaseProps<Item> & SelectionOptions<Item>;
 declare function DynamicTable<Item extends BaseItem>(props: Props<Item>): import("react").JSX.Element;

package/lib/index.js

@@ -1,6 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
 import Controller from "./Controller.js";
 import { BodyContainer, Button, Cell, ClickableCell, ColumnsPopup, ControllerContainer, FooterContainer, Header, HeaderActions, HeaderContainer, HeaderLine, HeaderStatus, ItemsPerPageSelector, Line, Loader, PageButton, PageSelector, Popup, SearchFilterPopup, SelectionCell, SelectionFilterPopup, SelectionHeader, Table, TableContainer, } from "./DefaultTheme.js";
+import generateLocalStorageWatcher from "./StateWatcher/LocalStorageWatcher.js";
+import NoopWatcher from "./StateWatcher/NoopWatcher.js";
 import UniquePopupProvider from "./UniquePopupProvider.js";
 import useColumns from "./useColumns.js";
 import useFilterState from "./useFilterState.js";
@@ -10,13 +13,16 @@ import usePagination from "./usePagination.js";
 import useSelection from "./useSelection.js";
 import useSortState from "./useSortState.js";
 export { default as Dictionary } from "./Dictionary.js";
+export { default as LocalStorageWatcher } from "./StateWatcher/LocalStorageWatcher.js";
 export default function DynamicTable(props) {
     const columns = useColumns(props.columns);
     const items = useItems(props.items, props.itemTarget, columns, props.canSelectItem);
-    const { columns: filteredColumns, items: filteredItems, clearFilterState, } = useFilterState(columns, items, props.initialFilterState);
-    const { columns: sortedColumns, items: sortedItems, clearSortState, } = useSortState(filteredColumns, filteredItems, props.initialSortState);
-    const { allColumns, columns: displayedColumns, items: displayedItems, } = useMaskableColumns(sortedColumns, sortedItems, props.initialColumnsMaskState);
-    const { items: paginatedItems, itemsPerPage, onItemsPerPageChange, totalPages, currentPage, onCurrentPageChange, } = usePagination(displayedItems, props.initialPaginationState);
+    const watcher = useMemo(() => props.watcher ??
+        (props.namespace === undefined ? NoopWatcher : generateLocalStorageWatcher(props.namespace)), [props.namespace, props.watcher]);
+    const { columns: filteredColumns, items: filteredItems, clearFilterState, } = useFilterState(columns, items, props.initialFilterState, watcher.filterState);
+    const { columns: sortedColumns, items: sortedItems, clearSortState, } = useSortState(filteredColumns, filteredItems, props.initialSortState, watcher.sortState);
+    const { allColumns, columns: displayedColumns, items: displayedItems, } = useMaskableColumns(sortedColumns, sortedItems, props.initialColumnsMaskState, watcher.columnsMaskState);
+    const { items: paginatedItems, itemsPerPage, onItemsPerPageChange, totalPages, currentPage, onCurrentPageChange, } = usePagination(displayedItems, props.initialPaginationState, watcher.paginationState);
     const { isInSelectionMode, totalSelectedQuantity, unvisibleSelectedQuantity, isItemSelected, onItemSelectionToggle, } = useSelection(props, paginatedItems);
     return (_jsx(UniquePopupProvider, { children: _jsxs(DynamicTable.TableContainer, { children: [_jsx(Controller, { columns: allColumns, clearFilterState: clearFilterState, clearSortState: clearSortState }), _jsxs(DynamicTable.Table, { children: [_jsx(DynamicTable.HeaderContainer, { children: _jsxs(DynamicTable.HeaderLine, { children: [isInSelectionMode && (_jsx(DynamicTable.SelectionHeader, { totalSelected: totalSelectedQuantity, unvisibleSelected: unvisibleSelectedQuantity })), displayedColumns.map((column) => (_jsx(DynamicTable.Header, { column: column, children: column.title }, column.id)))] }) }), _jsx(DynamicTable.BodyContainer, { children: paginatedItems.map((item) => (_jsxs(DynamicTable.Line, { children: [isInSelectionMode &&
                                         (item.isSelectable ? (_jsx(DynamicTable.SelectionCell, { selected: isItemSelected(item), onToggle: onItemSelectionToggle(item) })) : (_jsx(DynamicTable.Cell, {}))), item.target !== null

package/lib/useFilterState.d.ts

@@ -1,3 +1,4 @@
+import type { SpecificStateWatcher } from "./StateWatcher/index.js";
 import type { BaseItem, Primitive } from "./index.js";
 import type { InternalColumn, InternalColumns } from "./useColumns.js";
 import type { InternalItems } from "./useItems.js";
@@ -54,7 +55,7 @@ export declare function isSelectable<Item extends BaseItem, Value extends Primit
  * This hook will add filter state & filter control on each given columns, returning decorated columns. It will also
  * apply those filters on the items list, returning a filtered list.
  */
-export default function useFilterState<Item extends BaseItem>(columns: InternalColumns<Item>, items: InternalItems<Item>, initialFilterState?: FilterState): {
+export default function useFilterState<Item extends BaseItem>(columns: InternalColumns<Item>, items: InternalItems<Item>, initialState: FilterState | undefined, watcher: SpecificStateWatcher<FilterState> | undefined): {
     columns: InternalFilterableColumn<Item, Primitive>[];
     items: import("./useItems.js").InternalItem<Item>[];
     clearFilterState: () => void;

package/lib/useFilterState.js

@@ -1,6 +1,7 @@
 import { drop } from "@vinorcola/utils/object";
 import { extractSearchableText } from "@vinorcola/utils/text";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo } from "react";
+import useWatchedState from "./useWatchedState.js";
 export function isFilterable(column) {
     return ((column.searchText !== undefined && column.onSearchTextChange !== undefined) ||
         (column.hiddenValues !== undefined && column.onSelectionChange !== undefined));
@@ -17,8 +18,8 @@ export function isSelectable(column) {
  * This hook will add filter state & filter control on each given columns, returning decorated columns. It will also
  * apply those filters on the items list, returning a filtered list.
  */
-export default function useFilterState(columns, items, initialFilterState = {}) {
-    const [filterState, setFilterState] = useState(initialFilterState);
+export default function useFilterState(columns, items, initialState, watcher) {
+    const [filterState, setFilterState] = useWatchedState({}, initialState, watcher);
     return {
         columns: useMemo(() => columns.map((column) => {
             if (column.dictionary === undefined) {

package/lib/useItems.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { displayInteger } from "@vinorcola/utils/number";
 import { extractSearchableText } from "@vinorcola/utils/text";
-import { Fragment, useMemo } from "react";
+import { useMemo } from "react";
 import ValueList from "./ValueList.js";
 export default function useItems(items, itemTarget, columns, canSelectItem) {
     return useMemo(() => items.map((item) => ({
@@ -108,7 +108,7 @@ function resolveDisplayableSingleValue(value, dictionary, nodeKey) {
         if (dictionaryEntry === undefined) {
             return dictionary.unknownMessage;
         }
-        return dictionaryEntry.prepend !== undefined ? (_jsxs(Fragment, { children: [dictionaryEntry.prepend, dictionaryEntry.title] }, nodeKey)) : (dictionaryEntry.title);
+        return dictionaryEntry.prepend !== undefined ? (_jsxs(dictionary.valueWrapper, { children: [dictionaryEntry.prepend, dictionaryEntry.title] }, nodeKey)) : (dictionaryEntry.title);
     }
     if (typeof value === "boolean") {
         return value ? "true" : "false";

package/lib/useLazyInitializedState.d.ts

@@ -0,0 +1 @@
+export default function useLazyInitializedState<State>(defaultState: State, initial: State | undefined, lazyInitializer: (() => Promise<State | null>) | undefined): [State, import("react").Dispatch<import("react").SetStateAction<State>>];

package/lib/useLazyInitializedState.js

@@ -0,0 +1,16 @@
+import { useEffect, useState } from "react";
+export default function useLazyInitializedState(defaultState, initial, lazyInitializer) {
+    const state = useState(initial ?? defaultState);
+    useEffect(() => {
+        if (initial !== undefined) {
+            return;
+        }
+        lazyInitializer?.().then((initialState) => {
+            if (initialState === null) {
+                return;
+            }
+            state[1](initialState);
+        });
+    }, []); // eslint-disable-line react-hooks-configurable/exhaustive-deps
+    return state;
+}

package/lib/useMaskableColumns.d.ts

@@ -1,3 +1,4 @@
+import type { SpecificStateWatcher } from "./StateWatcher/index.js";
 import type { BaseItem, Primitive } from "./index.js";
 import type { InternalColumn } from "./useColumns.js";
 import type { InternalItems } from "./useItems.js";
@@ -22,7 +23,7 @@ export declare function isMaskable<Item extends BaseItem, Value extends Primitiv
  * Note that the returned `columns` contains only the displayed columns, while `allColumns` contains all the columns
  * (for control purpose).
  */
-export default function useMaskableColumns<Item extends BaseItem>(columns: InternalColumn<Item, Primitive>[], items: InternalItems<Item>, initialHiddenColumns?: ColumnsMaskState): {
+export default function useMaskableColumns<Item extends BaseItem>(columns: InternalColumn<Item, Primitive>[], items: InternalItems<Item>, initialState: ColumnsMaskState | undefined, watcher: SpecificStateWatcher<ColumnsMaskState> | undefined): {
     allColumns: InternalMaskableColumn<Item, Primitive>[];
     columns: InternalMaskableColumn<Item, Primitive>[];
     items: {

package/lib/useMaskableColumns.js

@@ -1,4 +1,5 @@
-import { useMemo, useState } from "react";
+import { useMemo } from "react";
+import useWatchedState from "./useWatchedState.js";
 export function isMaskable(column) {
     return column.displayed !== undefined && column.onDisplayToggle !== undefined;
 }
@@ -11,8 +12,8 @@ export function isMaskable(column) {
  * Note that the returned `columns` contains only the displayed columns, while `allColumns` contains all the columns
  * (for control purpose).
  */
-export default function useMaskableColumns(columns, items, initialHiddenColumns = []) {
-    const [hidden, setHidden] = useState(initialHiddenColumns);
+export default function useMaskableColumns(columns, items, initialState, watcher) {
+    const [hidden, setHidden] = useWatchedState([], initialState, watcher);
     const allColumns = useMemo(() => columns.map((column) => {
         const displayed = !hidden.includes(column.id);
         return {

package/lib/usePagination.d.ts

@@ -1,3 +1,4 @@
+import type { SpecificStateWatcher } from "./StateWatcher/index.js";
 import type { BaseItem } from "./index.js";
 import type { InternalItems } from "./useItems.js";
 /**
@@ -12,7 +13,7 @@ export interface PaginationState {
  *
  * Return pagination state & pagination control as well as items to display on the current page.
  */
-export default function usePagination<Item extends BaseItem>(items: InternalItems<Item>, initialPaginationState?: PaginationState): {
+export default function usePagination<Item extends BaseItem>(items: InternalItems<Item>, initialState: PaginationState | undefined, watcher: SpecificStateWatcher<PaginationState> | undefined): {
     items: import("./useItems.js").InternalItem<Item>[];
     itemsPerPage: number;
     onItemsPerPageChange: (itemsPerPage: number) => void;

package/lib/usePagination.js

@@ -1,11 +1,12 @@
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo } from "react";
+import useWatchedState from "./useWatchedState.js";
 /**
  * Apply pagination.
  *
  * Return pagination state & pagination control as well as items to display on the current page.
  */
-export default function usePagination(items, initialPaginationState = { currentPage: 1, itemsPerPage: 12 }) {
-    const [pagination, setPagination] = useState(initialPaginationState);
+export default function usePagination(items, initialState, watcher) {
+    const [pagination, setPagination] = useWatchedState({ currentPage: 1, itemsPerPage: 12 }, initialState, watcher);
     const totalPages = useMemo(() => Math.ceil(items.length / pagination.itemsPerPage), [items, pagination]);
     const currentPage = useMemo(() => Math.max(1, Math.min(totalPages, pagination.currentPage)), [totalPages, pagination]);
     return {

package/lib/useSortState.d.ts

@@ -1,3 +1,4 @@
+import type { SpecificStateWatcher } from "./StateWatcher/index.js";
 import type { BaseItem, Primitive } from "./index.js";
 import type { InternalColumn, InternalColumns } from "./useColumns.js";
 import type { InternalItems, InternalItem } from "./useItems.js";
@@ -34,7 +35,7 @@ export declare function isSortable<Item extends BaseItem, Value extends Primitiv
  * This hook will add sort state & sort control on each given columns, returning decorated columns. It will also apply
  * those sorts on the items list, returning a sorted list.
  */
-export default function useSortState<Item extends BaseItem>(columns: InternalColumns<Item>, items: InternalItems<Item>, initialSortState?: SortState): {
+export default function useSortState<Item extends BaseItem>(columns: InternalColumns<Item>, items: InternalItems<Item>, initialState: SortState | undefined, watcher: SpecificStateWatcher<SortState> | undefined): {
     columns: InternalSortableColumn<Item, Primitive>[];
     items: InternalItem<Item>[];
     clearSortState: () => void;

package/lib/useSortState.js

@@ -1,5 +1,6 @@
 import { dropElement, replaceElement } from "@vinorcola/utils/list";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo } from "react";
+import useWatchedState from "./useWatchedState.js";
 export function isSortable(column) {
     return column.sorted !== undefined && column.onSortToggle !== undefined;
 }
@@ -9,8 +10,8 @@ export function isSortable(column) {
  * This hook will add sort state & sort control on each given columns, returning decorated columns. It will also apply
  * those sorts on the items list, returning a sorted list.
  */
-export default function useSortState(columns, items, initialSortState = []) {
-    const [sortState, setSortState] = useState(initialSortState);
+export default function useSortState(columns, items, initialState, watcher) {
+    const [sortState, setSortState] = useWatchedState([], initialState, watcher);
     return {
         columns: useMemo(() => columns.map((column) => {
             const columnSortStateIndex = sortState.findIndex((columnSortState) => columnSortState.columnId === column.id);

package/lib/useWatchedState.d.ts

@@ -0,0 +1,3 @@
+import type { Dispatch, SetStateAction } from "react";
+import type { SpecificStateWatcher } from "./StateWatcher";
+export default function useWatchedState<State>(defaultState: State, initial: State | undefined, watcher: SpecificStateWatcher<State> | undefined): readonly [State, Dispatch<SetStateAction<State>>];

package/lib/useWatchedState.js

@@ -0,0 +1,25 @@
+import { useCallback, useEffect, useState } from "react";
+export default function useWatchedState(defaultState, initial, watcher) {
+    const [state, setState] = useState(initial ?? defaultState);
+    useEffect(() => {
+        if (initial !== undefined) {
+            return;
+        }
+        watcher?.loadInitial?.().then((initialState) => {
+            if (initialState === null) {
+                return;
+            }
+            setState(initialState);
+        });
+    }, []); // eslint-disable-line react-hooks-configurable/exhaustive-deps
+    return [
+        state,
+        useCallback((updater) => {
+            setState((state) => {
+                const newState = typeof updater === "function" ? updater(state) : updater;
+                watcher?.onChange?.(newState);
+                return newState;
+            });
+        }, []), // eslint-disable-line react-hooks-configurable/exhaustive-deps
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinorcola/dynamic-table",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "A table to ease the display of a filterable, sortable and paginable dataset.",
   "keywords": [
     "table",
@@ -44,6 +44,7 @@
   "devDependencies": {
     "@types/react": "^19.2.2",
     "@vinorcola/lint": "^1.0.5",
+    "eslint-plugin-react-hooks-configurable": "^7.1.1",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {