feat: add onChange API for collection state with useCollectionURLState

[IzumiSy]

Summary

Add an onChange callback to useCollectionVariables that notifies on every user-initiated state change (filters, sort, pageSize). Includes a built-in useCollectionURLState hook that provides a read/write accessor for URL-based state.

Design

Instead of a persistence interface that the hook calls internally, the API follows standard React conventions:

• params — synchronous initial state (no delayed hydration)
• onChange — explicit notification on state changes (unidirectional data flow)

Helper hooks like useCollectionURLState return a { read, write } accessor that wires directly into params and onChange:

const urlState = useCollectionURLState({ prefix: "dt1" });
const { variables, control } = useCollectionVariables({
  params: { ...urlState.read(), pageSize: urlState.read().pageSize ?? 20 },
  tableMetadata: productMetadata,
  onChange: urlState.write,
});

API

useCollectionVariables options

interface UseCollectionOptions<TFieldName extends string = string> {
  params?: {
    initialFilters?: Filter<TFieldName>[];
    initialSort?: { field: TFieldName; direction: "Asc" | "Desc" }[];
    pageSize?: number;
  };
  /** Called on every user-initiated state change. */
  onChange?: (state: CollectionSnapshot<TFieldName>) => void;
}

useCollectionURLState

interface CollectionURLStateAccessor<TFieldName extends string = string> {
  read(): { initialFilters?: Filter<TFieldName>[]; initialSort?: SortState[]; pageSize?: number };
  write: (state: CollectionSnapshot<TFieldName>) => void;
}

function useCollectionURLState<TFieldName>(options?: {
  prefix?: string;
  debounceMs?: number;
}): CollectionURLStateAccessor<TFieldName>;

URL format:

• Page size: p=20
• Sort: s=name:asc
• Filters: f.field:operator=value (repeated params for multi-value filters)

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@tailor-platform/app-shell@292

npm i https://pkg.pr.new/@tailor-platform/app-shell-sdk-plugin@292

npm i https://pkg.pr.new/@tailor-platform/app-shell-vite-plugin@292

commit: 5decd69