@vinorcola/dynamic-table 1.2.3 → 1.4.0

package/lib/ColumnDefinition.d.ts

@@ -1,11 +1,11 @@
 import type { ReactNode } from "react";
 import type { BaseItem, Dictionary, ItemKey, Primitive } from "./index.js";
-export type ValueDecorator<Item extends BaseItem, Value extends Primitive> = (value: Value, defaultDisplay: ReactNode, item: Item) => ReactNode;
-export type ValueResolver<Item extends BaseItem, Value extends Primitive> = (item: Item) => Value | null;
+export type ValueDecorator<Item extends BaseItem, Value extends Primitive | Primitive[]> = (value: Value, defaultDisplay: ReactNode, item: Item) => ReactNode;
+export type ValueResolver<Item extends BaseItem, Value extends Primitive | Primitive[]> = (item: Item) => Value | null;
 interface BaseColumneDefinition<Item extends BaseItem, Value extends Primitive> {
     readonly title: string;
     readonly dictionary?: Dictionary<Value> | Promise<Dictionary<Value>>;
-    readonly decorateValue?: ValueDecorator<Item, Value>;
+    readonly decorateValue?: ValueDecorator<Item, Value | Value[]>;
     readonly decorateNoValue?: () => ReactNode;
 }
 /**
@@ -19,7 +19,7 @@ interface AccessorColumnDefinition<Item extends BaseItem, Value extends Primitiv
  */
 interface ResolvedColumnDefinition<Item extends BaseItem, Value extends Primitive> extends BaseColumneDefinition<Item, Value> {
     readonly id: string;
-    readonly resolveValue: ValueResolver<Item, Value>;
+    readonly resolveValue: ValueResolver<Item, Value | Value[]>;
 }
 export type ColumnDefinition<Item extends BaseItem, Value extends Primitive> = AccessorColumnDefinition<Item, Value> | ResolvedColumnDefinition<Item, Value>;
 export declare function isAccessorColumnDefinition<Item extends BaseItem, Value extends Primitive>(definition: ColumnDefinition<Item, Value>): definition is AccessorColumnDefinition<Item, Value>;

package/lib/Controller.d.ts

@@ -5,5 +5,5 @@ interface Props<Item extends BaseItem> {
     clearFilterState: () => void;
     clearSortState: () => void;
 }
-export default function Controller<Item extends BaseItem>(props: Props<Item>): import("react/jsx-runtime").JSX.Element;
+export default function Controller<Item extends BaseItem>(props: Props<Item>): import("react").JSX.Element;
 export {};

package/lib/DefaultTheme.d.ts

@@ -6,90 +6,90 @@ import { type InternalSortableColumn } from "./useSortState.js";
 export interface Props {
     children?: ReactNode;
 }
-export declare function TableContainer(props: Props): import("react/jsx-runtime").JSX.Element;
+export declare function TableContainer(props: Props): import("react").JSX.Element;
 export interface ControllerButtonsGroupProps {
     filterButton: ReactElement;
     sortButton: ReactElement;
     columnButton: ReactElement;
     columnPopup?: ReactElement;
 }
-export declare function ControllerContainer(props: ControllerButtonsGroupProps): import("react/jsx-runtime").JSX.Element;
+export declare function ControllerContainer(props: ControllerButtonsGroupProps): import("react").JSX.Element;
 export interface ColumnsPopupProps<Item extends BaseItem> {
     columns: InternalColumns<Item>;
     onDismiss: () => void;
 }
-export declare function ColumnsPopup<Item extends BaseItem>(props: ColumnsPopupProps<Item>): import("react/jsx-runtime").JSX.Element;
-export declare function Table(props: Props): import("react/jsx-runtime").JSX.Element;
-export declare function HeaderContainer(props: Props): import("react/jsx-runtime").JSX.Element;
-export declare function HeaderLine(props: Props): import("react/jsx-runtime").JSX.Element;
+export declare function ColumnsPopup<Item extends BaseItem>(props: ColumnsPopupProps<Item>): import("react").JSX.Element;
+export declare function Table(props: Props): import("react").JSX.Element;
+export declare function HeaderContainer(props: Props): import("react").JSX.Element;
+export declare function HeaderLine(props: Props): import("react").JSX.Element;
 export interface SelectionHeaderProps extends Props {
     totalSelected: number;
     unvisibleSelected: number;
 }
-export declare function SelectionHeader(props: SelectionHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SelectionHeader(props: SelectionHeaderProps): import("react").JSX.Element;
 export interface HeaderProps<Item extends BaseItem, Value extends Primitive> extends Props {
     column: InternalColumn<Item, Value>;
 }
-export declare function Header<Item extends BaseItem, Value extends Primitive>(props: HeaderProps<Item, Value>): import("react/jsx-runtime").JSX.Element;
+export declare function Header<Item extends BaseItem, Value extends Primitive>(props: HeaderProps<Item, Value>): import("react").JSX.Element;
 export interface HeaderActionsProps {
     filterType?: FilterType;
     onFilterPopupToggle?: () => void;
     onDisplayToggle?: () => void;
 }
-export declare function HeaderActions(props: HeaderActionsProps): import("react/jsx-runtime").JSX.Element;
+export declare function HeaderActions(props: HeaderActionsProps): import("react").JSX.Element;
 export interface HeaderStatusProps {
     filterType?: FilterType;
     sortState?: NonNullable<InternalSortableColumn<BaseItem, Primitive>["sorted"]>;
 }
-export declare function HeaderStatus(props: HeaderStatusProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function HeaderStatus(props: HeaderStatusProps): import("react").JSX.Element | null;
 export interface SearchFilterPopupProps {
     searchText: string;
     onSearchTextChange: (searchText: string) => void;
     onDismiss: () => void;
 }
-export declare function SearchFilterPopup(props: SearchFilterPopupProps): import("react/jsx-runtime").JSX.Element;
+export declare function SearchFilterPopup(props: SearchFilterPopupProps): import("react").JSX.Element;
 export interface SelectionFilterPopupProps<Value extends Primitive> {
     dictionary: Dictionary<Value> | null;
     hiddenValues: Value[];
     onHiddenValuesChange: (hiddenValues: Value[]) => void;
     onDismiss: () => void;
 }
-export declare function SelectionFilterPopup<Value extends Primitive>(props: SelectionFilterPopupProps<Value>): import("react/jsx-runtime").JSX.Element;
-export declare function BodyContainer(props: Props): import("react/jsx-runtime").JSX.Element;
-export declare function Line(props: Props): import("react/jsx-runtime").JSX.Element;
+export declare function SelectionFilterPopup<Value extends Primitive>(props: SelectionFilterPopupProps<Value>): import("react").JSX.Element;
+export declare function BodyContainer(props: Props): import("react").JSX.Element;
+export declare function Line(props: Props): import("react").JSX.Element;
 interface SelectionCellProps extends Props {
     selected: boolean;
     onToggle: () => void;
 }
-export declare function SelectionCell(props: SelectionCellProps): import("react/jsx-runtime").JSX.Element;
-export declare function Cell(props: Props): import("react/jsx-runtime").JSX.Element;
+export declare function SelectionCell(props: SelectionCellProps): import("react").JSX.Element;
+export declare function Cell(props: Props): import("react").JSX.Element;
 export interface ClickableProps extends Props {
     target: string;
 }
-export declare function ClickableCell(props: ClickableProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClickableCell(props: ClickableProps): import("react").JSX.Element;
 export interface FooterContainerProps {
     totalColums: number;
     pageSelector: ReactNode;
     itemsPerPageSelector: ReactNode;
 }
-export declare function FooterContainer(props: FooterContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function FooterContainer(props: FooterContainerProps): import("react").JSX.Element;
 export interface ItemsPerPageSelectorProps extends Props {
     itemsPerPage: number;
     onItemsPerPageChange: (itemsPerPage: number) => void;
 }
-export declare function ItemsPerPageSelector(props: ItemsPerPageSelectorProps): import("react/jsx-runtime").JSX.Element;
+export declare function ItemsPerPageSelector(props: ItemsPerPageSelectorProps): import("react").JSX.Element;
 export interface PageSelectorProps extends Props {
     totalPages: number;
     currentPage: number;
     onCurrentPageChange: (page: number) => void;
 }
-export declare function PageSelector(props: PageSelectorProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function PageSelector(props: PageSelectorProps): import("react").JSX.Element | null;
 export interface PageButtonProps extends Props {
     enabled: boolean;
     active?: boolean;
     onClick: () => void;
 }
-export declare function PageButton(props: PageButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function PageButton(props: PageButtonProps): import("react").JSX.Element;
 export interface ButtonProps extends Props {
     className?: string;
     disabled?: boolean;
@@ -112,11 +112,11 @@ export interface ButtonProps extends Props {
  * background color (when button is non-hovered) by defining a custom `--bg-default-color`, for example:
  * `<DynamicTable.Button className="[--bg-default-color:transparent]">...</DynamicTable.Button>`
  */
-export declare function Button(props: ButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function Button(props: ButtonProps): import("react").JSX.Element;
 export interface PopupProps extends Props {
     className?: string;
     onDismiss: () => void;
 }
-export declare function Popup(props: PopupProps): import("react/jsx-runtime").JSX.Element;
-export declare function Loader(): import("react/jsx-runtime").JSX.Element;
+export declare function Popup(props: PopupProps): import("react").JSX.Element;
+export declare function Loader(): import("react").JSX.Element;
 export {};

package/lib/Icon.d.ts

@@ -1,13 +1,13 @@
 export declare const DEFAULT_CLASS = "inline grow-0 shrink-0 size-[1em]";
-export declare function CheckedIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function UncheckedIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function CloseIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function ColumnsIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function FilterIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function HideIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function NextIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function PreviousIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function SearchIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function SortIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function AscSortIcon(): import("react/jsx-runtime").JSX.Element;
-export declare function DescSortIcon(): import("react/jsx-runtime").JSX.Element;
+export declare function CheckedIcon(): import("react").JSX.Element;
+export declare function UncheckedIcon(): import("react").JSX.Element;
+export declare function CloseIcon(): import("react").JSX.Element;
+export declare function ColumnsIcon(): import("react").JSX.Element;
+export declare function FilterIcon(): import("react").JSX.Element;
+export declare function HideIcon(): import("react").JSX.Element;
+export declare function NextIcon(): import("react").JSX.Element;
+export declare function PreviousIcon(): import("react").JSX.Element;
+export declare function SearchIcon(): import("react").JSX.Element;
+export declare function SortIcon(): import("react").JSX.Element;
+export declare function AscSortIcon(): import("react").JSX.Element;
+export declare function DescSortIcon(): import("react").JSX.Element;

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/UniquePopupProvider.d.ts

@@ -18,5 +18,5 @@ export declare function usePopup(): PopupState;
 interface Props {
     children?: ReactNode;
 }
-export default function UniquePopupProvider(props: Props): import("react/jsx-runtime").JSX.Element;
+export default function UniquePopupProvider(props: Props): import("react").JSX.Element;
 export {};

package/lib/UniquePopupProvider.js

@@ -11,21 +11,25 @@ const PopupContext = createContext(createRef());
  */
 // eslint-disable-next-line react-refresh/only-export-components
 export function usePopup() {
-    const dismiss = useContext(PopupContext);
+    const dismissRef = useContext(PopupContext);
     const [display, setDisplay] = useState(false);
     return {
         display,
         show: useCallback(() => {
-            if (dismiss.current !== null) {
-                dismiss.current();
+            if (dismissRef.current !== null) {
+                dismissRef.current();
             }
-            dismiss.current = () => {
+            dismissRef.current = () => {
                 setDisplay(false);
-                dismiss.current = null;
+                dismissRef.current = null;
             };
             setDisplay(true);
-        }, [dismiss]),
-        dismiss: dismiss.current,
+        }, [dismissRef]),
+        dismiss: useCallback(() => {
+            if (dismissRef.current !== null) {
+                dismissRef.current();
+            }
+        }, [dismissRef]),
     };
 }
 export default function UniquePopupProvider(props) {

package/lib/ValueList.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+interface Props {
+    separator?: string;
+    items: ReactNode[];
+}
+export default function ValueList(props: Props): ReactNode[];
+export {};

package/lib/ValueList.js

@@ -0,0 +1,10 @@
+export default function ValueList(props) {
+    const separator = props.separator ?? ", ";
+    return props.items.reduce((nodes, item) => {
+        if (nodes.length > 0) {
+            nodes.push(separator);
+        }
+        nodes.push(item);
+        return nodes;
+    }, []);
+}

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,9 +28,10 @@ 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-runtime").JSX.Element;
+declare function DynamicTable<Item extends BaseItem>(props: Props<Item>): import("react").JSX.Element;
 declare namespace DynamicTable {
     var TableContainer: typeof import("./DefaultTheme.js").TableContainer;
     var ControllerContainer: typeof import("./DefaultTheme.js").ControllerContainer;

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/useColumns.d.ts

@@ -9,8 +9,8 @@ export interface LoadingInternalColumn<Item extends BaseItem, Value extends Prim
     readonly title: string;
     readonly loadingDictionary: true;
     readonly dictionary: Promise<Dictionary<Value>>;
-    readonly resolveValue: ValueResolver<Item, Value>;
-    readonly decorateValue?: ValueDecorator<Item, Value>;
+    readonly resolveValue: ValueResolver<Item, Value | Value[]>;
+    readonly decorateValue?: ValueDecorator<Item, Value | Value[]>;
     readonly decorateNoValue?: () => ReactNode;
 }
 /**
@@ -21,8 +21,8 @@ export interface LoadedInternalColumn<Item extends BaseItem, Value extends Primi
     readonly title: string;
     readonly loadingDictionary: false;
     readonly dictionary?: Dictionary<Value>;
-    readonly resolveValue: ValueResolver<Item, Value>;
-    readonly decorateValue?: ValueDecorator<Item, Value>;
+    readonly resolveValue: ValueResolver<Item, Value | Value[]>;
+    readonly decorateValue?: ValueDecorator<Item, Value | Value[]>;
     readonly decorateNoValue?: () => ReactNode;
 }
 /**

package/lib/useColumns.js

@@ -14,6 +14,7 @@ export default function useColumns(definitions) {
     useEffect(() => {
         definitionVersion.current++;
         const currentVersion = definitionVersion.current;
+        // eslint-disable-next-line react-hooks/set-state-in-effect
         setColumns(resolveInitialColumnState(definitions));
         definitions.forEach((definition, index) => {
             if (definition.dictionary instanceof Promise) {

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) {
@@ -47,25 +48,26 @@ export default function useFilterState(columns, items, initialFilterState = {})
                 };
             }
         }), [columns, filterState]),
-        items: useMemo(() => items.filter((items) => items.values.every((value) => {
-            if (value.loading) {
-                // Keep loading values.
-                return true;
-            }
-            const columnFilterState = filterState[value.column] ?? null;
-            if (columnFilterState === null) {
-                // There is no filter on this column.
-                return true;
-            }
-            return isSearchedState(columnFilterState)
-                ? matchSearch(value, columnFilterState)
-                : matchSelection(value, columnFilterState);
-        })), [items, filterState]),
+        items: useMemo(() => items.filter((items) => items.values.every((value) => isValueMatchingColumnFilter(filterState, value))), [items, filterState]),
         clearFilterState: useCallback(() => {
             setFilterState({});
         }, []),
     };
 }
+function isValueMatchingColumnFilter(filterState, value) {
+    if (value.loading) {
+        // Keep loading values.
+        return true;
+    }
+    const columnFilterState = filterState[value.column] ?? null;
+    if (columnFilterState === null) {
+        // There is no filter on this column.
+        return true;
+    }
+    return isSearchedState(columnFilterState)
+        ? matchSearch(value, columnFilterState)
+        : matchSelection(value, columnFilterState);
+}
 function isSearchedState(state) {
     return state.searchText !== undefined;
 }
@@ -81,5 +83,8 @@ function matchSelection(value, filterState) {
         // Filter out empty values.
         return false;
     }
+    if (Array.isArray(value.raw)) {
+        return value.raw.some((rawValue) => !filterState.hiddenValues.includes(rawValue));
+    }
     return !filterState.hiddenValues.includes(value.raw);
 }

package/lib/useItems.d.ts

@@ -5,18 +5,18 @@ import type { SortableValue } from "./useSortState.js";
 /**
  * A value that is loading (waiting for an async column dictionary to be available).
  */
-export interface LoadingInternalValue {
+export interface LoadingInternalValue<Value extends Primitive | Primitive[] = Primitive | Primitive[]> {
     readonly column: string;
     readonly loading: true;
-    readonly raw: Primitive | null;
+    readonly raw: Value | null;
 }
 /**
  * A loaded value, ready for filter, sort and display.
  */
-export interface LoadedInternalValue {
+export interface LoadedInternalValue<Value extends Primitive | Primitive[] = Primitive | Primitive[]> {
     readonly column: string;
     readonly loading: false;
-    readonly raw: Primitive | null;
+    readonly raw: Value | null;
     readonly search: string | null;
     readonly sort: SortableValue;
     readonly display: ReactNode;
@@ -24,7 +24,7 @@ export interface LoadedInternalValue {
 /**
  * A value, either in loading state ou in loaded state.
  */
-export type InternalValue = LoadingInternalValue | LoadedInternalValue;
+export type InternalValue<Value extends Primitive | Primitive[] = Primitive | Primitive[]> = LoadingInternalValue<Value> | LoadedInternalValue<Value>;
 /**
  * An internal item.
  */

package/lib/useItems.js

@@ -1,7 +1,8 @@
-import { Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { displayInteger } from "@vinorcola/utils/number";
 import { extractSearchableText } from "@vinorcola/utils/text";
-import { useMemo } from "react";
+import { Fragment, useMemo } from "react";
+import ValueList from "./ValueList.js";
 export default function useItems(items, itemTarget, columns, canSelectItem) {
     return useMemo(() => items.map((item) => ({
         key: item.id,
@@ -12,35 +13,46 @@ export default function useItems(items, itemTarget, columns, canSelectItem) {
     })), [items, itemTarget, columns, canSelectItem]);
 }
 function resolveInternalValue(item, column) {
-    const raw = column.resolveValue(item);
+    const value = column.resolveValue(item);
     if (column.loadingDictionary) {
         return {
             column: column.id,
             loading: true,
-            raw,
+            raw: value,
         };
     }
-    let display = resolveDisplayableValue(raw, column.dictionary);
-    if (raw === null || raw === undefined || raw === "") {
+    let display;
+    if (value === null || value === undefined || value === "") {
         if (column.decorateNoValue !== undefined) {
             display = column.decorateNoValue();
         }
+        else {
+            display = null;
+        }
+    }
+    else if (column.decorateValue !== undefined) {
+        display = column.decorateValue(value, display, item);
     }
     else {
-        if (column.decorateValue !== undefined) {
-            display = column.decorateValue(raw, display, item);
-        }
+        display = resolveDisplayableValue(value, column.dictionary);
     }
     return {
         column: column.id,
         loading: false,
-        raw,
-        search: resolveSearchableValue(raw, column.dictionary),
-        sort: resolveSortableValue(raw, column.dictionary),
+        raw: value,
+        search: resolveSearchableValue(value, column.dictionary),
+        sort: resolveSortableValue(value, column.dictionary),
         display,
     };
 }
+const ARBITRARY_SEARCH_SEPARATOR = "#|!$#"; // To avoid searching text across several values, we separate each value by
+//                                         // this arbitrary (unlikely searched by users) text.
 function resolveSearchableValue(value, dictionary) {
+    return Array.isArray(value)
+        ? value.map((value) => resolveSearchableSingleValue(value, dictionary)).join(ARBITRARY_SEARCH_SEPARATOR)
+        : resolveSearchableSingleValue(value, dictionary);
+}
+function resolveSearchableSingleValue(value, dictionary) {
     if (dictionary !== undefined) {
         // Columns with dictionary are selectable, not searchable.
         return null;
@@ -60,6 +72,13 @@ function resolveSearchableValue(value, dictionary) {
     return extractSearchableText(value);
 }
 function resolveSortableValue(value, dictionary) {
+    return Array.isArray(value)
+        ? value.length === 0
+            ? null
+            : resolveSortableSingleValue(value[0], dictionary) // Sort using first value (until we find a better way!)
+        : resolveSortableSingleValue(value, dictionary);
+}
+function resolveSortableSingleValue(value, dictionary) {
     if (value === null) {
         return null;
     }
@@ -78,6 +97,9 @@ function resolveSortableValue(value, dictionary) {
     return value.toLocaleLowerCase();
 }
 function resolveDisplayableValue(value, dictionary) {
+    return Array.isArray(value) ? (_jsx(ValueList, { items: value.map((value, index) => resolveDisplayableSingleValue(value, dictionary, index)) })) : (resolveDisplayableSingleValue(value, dictionary));
+}
+function resolveDisplayableSingleValue(value, dictionary, nodeKey) {
     if (value === null) {
         return null;
     }
@@ -86,7 +108,7 @@ function resolveDisplayableValue(value, dictionary) {
         if (dictionaryEntry === undefined) {
             return dictionary.unknownMessage;
         }
-        return dictionaryEntry.prepend !== undefined ? (_jsxs(_Fragment, { children: [dictionaryEntry.prepend, dictionaryEntry.title] })) : (dictionaryEntry.title);
+        return dictionaryEntry.prepend !== undefined ? (_jsxs(Fragment, { 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,11 +23,11 @@ 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: {
-        values: import("./useItems.js").InternalValue[];
+        values: import("./useItems.js").InternalValue<Primitive | Primitive[]>[];
         key: import("react").Key;
         item: Item;
         isSelectable: boolean;

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.2.3",
+  "version": "1.4.0",
   "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": {