react-listing-engine 0.6.5 → 0.6.6

package/dist/index.d.ts

@@ -1,12 +1,9 @@
 import { P as Page, B as Bounds, E as EntityId, M as MapPoint, U as Unsubscribe, a as MapProvider, Q as QueryParams, L as LatLng } from './map-provider.interface-DT-v1plm.js';
 export { b as EntityAdapter, c as MapHandle, d as MapInitOptions, e as PageRequest, R as RenderedLayer } from './map-provider.interface-DT-v1plm.js';
-import { P as PaginationMode, D as DatasetDefinition, I as IListingConfigOptions, F as FilterRegistry, a as IListingToolbarProps } from './components-provider-cWVWEDXC.js';
-export { C as ClusterOptions, b as FilterControlProps, c as FilterDefinition, d as IListingCardProps, e as IListingComponents, f as IListingEmptyProps, g as IListingFilterPanelProps, h as IListingLoadingProps, i as IListingMarkerProps, j as IListingPopupProps, k as IListingResultHeaderProps, l as IListingSearchProps, m as IListingSidebarProps, L as ListingComponentsProvider, M as MarkerRenderer, u as useListingComponents } from './components-provider-cWVWEDXC.js';
-import { H as HistoryPort, U as UrlSyncController } from './url-sync.controller-DK5W_0OZ.js';
-export { a as UrlSyncEngine, b as UrlSyncOptions } from './url-sync.controller-DK5W_0OZ.js';
+import { P as PaginationMode, D as DatasetDefinition, I as IListingConfigOptions, F as FilterRegistry, a as IListingToolbarProps } from './listing-app-CkEGdUV9.js';
+export { C as ClusterOptions, b as FilterControlProps, c as FilterDefinition, d as IListingCardProps, e as IListingComponents, f as IListingEmptyProps, g as IListingFilterPanelProps, h as IListingLoadingProps, i as IListingMarkerProps, j as IListingPopupProps, k as IListingResultHeaderProps, l as IListingSearchProps, m as IListingSidebarProps, L as ListingApp, n as ListingAppProps, o as ListingComponentsProvider, M as MarkerRenderer, u as useListingComponents } from './listing-app-CkEGdUV9.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
-export { L as ListingApp, a as ListingAppProps } from './listing-app-BSJKGh7k.js';
 
 declare enum ListingEventType {
     FiltersChanged = "FiltersChanged",
@@ -213,6 +210,18 @@ declare class ListingEngine<TEntity, TFilters> {
     private clearDebounce;
 }
 
+/**
+ * DOM-agnostic abstraction over "the URL's query string" — or, in tests/SSR,
+ * an in-memory stand-in (`MemoryHistoryPort`). `UrlSyncController` talks to
+ * this interface only, never to `window.location`/`history` directly, so it
+ * stays framework- and environment-free like the rest of `src/core`.
+ */
+interface HistoryPort {
+    getQuery(): QueryParams;
+    setQuery(params: QueryParams): void;
+    subscribe(cb: () => void): () => void;
+}
+
 /**
  * In-memory `HistoryPort` — holds `QueryParams` in a plain field instead of
  * the browser URL. Used by tests (fast, no DOM/jsdom `history` needed) and by
@@ -228,6 +237,79 @@ declare class MemoryHistoryPort implements HistoryPort {
     private notify;
 }
 
+interface UrlSyncEngine<TFilters> {
+    subscribe(cb: () => void): () => void;
+    readonly state: {
+        readonly filters: TFilters;
+    };
+    applyFilters(patch: Partial<TFilters>): Promise<void> | void;
+}
+interface UrlSyncOptions<TFilters> {
+    history: HistoryPort;
+    toQuery(filters: TFilters): QueryParams;
+    toFilters(query: QueryParams): Partial<TFilters>;
+    hydrateOnStart?: boolean;
+}
+/**
+ * Bidirectional, DOM-agnostic sync between an engine's `filters` and a
+ * `HistoryPort`'s query params. Framework-free: talks to `UrlSyncEngine`
+ * (a structural subset `ListingEngine` satisfies) and `HistoryPort`, nothing
+ * else — no `window`, no React.
+ *
+ * OPTIONAL, not the primary path: `styled/listing-app.tsx`'s turnkey
+ * `ListingApp` (the package's main-entry default) does NOT wire this up —
+ * it uses an event-based URL API instead (`initialFilters` in,
+ * `onFiltersChange` out; see that file's doc comment), so the library never
+ * touches `window.history` by default. This class remains exported for
+ * consumers who explicitly want the library to own history writes/reads
+ * itself, by wiring it directly against a hand-built engine.
+ *
+ * Echo-loop guard: both subscriptions below are driven by the SAME
+ * `isSyncing` flag. `ListingEngine.applyFilters()` and `MemoryHistoryPort`
+ * (and any real browser HistoryPort) both notify their subscribers
+ * SYNCHRONOUSLY as part of the write (`store.setFilters()` -> `notify()`
+ * happens before any debounce timer, and `MemoryHistoryPort.setQuery()`
+ * notifies before returning) — so when this controller initiates a write on
+ * one side, the reciprocal subscription on the other side fires within the
+ * very same call stack, before `isSyncing` is reset. Wrapping each
+ * controller-initiated write in `isSyncing = true; ...; isSyncing = false`
+ * (via try/finally, so a throwing `toQuery`/`toFilters`/notify can't leave it
+ * stuck) means that reciprocal callback observes `isSyncing === true` and
+ * short-circuits instead of writing back — one hop each direction, never a
+ * cascade. `hydrateOnStart`'s initial engine write is wrapped the same way,
+ * since it must not immediately echo the just-hydrated filters back out to
+ * history as a redundant `setQuery`.
+ *
+ * `isSyncing` only covers that SYNCHRONOUS window, though — the real
+ * `ListingEngine.applyFilters()` notifies AGAIN, asynchronously: after
+ * `await adapter.list(...)` resolves, `store.setResults()` and
+ * `store.setLoading(false)` each call `notify()`, well after `isSyncing` has
+ * already been reset to `false` by the `withSyncGuard` that kicked the query
+ * off. Left unguarded, that async tail would fire the engine subscription
+ * below and echo an identical (but spurious) `history.setQuery(...)` on
+ * every completed query. Rather than widening `isSyncing` to cover the whole
+ * async query (which would also swallow legitimate concurrent history
+ * changes that land mid-query), `syncEngineToHistory` is idempotent BY
+ * VALUE instead: it computes the target query and skips the write entirely
+ * when it already matches `history.getQuery()` — timing-independent, so it
+ * suppresses the async-tail echo without touching `isSyncing` at all.
+ */
+declare class UrlSyncController<TFilters> {
+    private readonly history;
+    private readonly toQueryFn;
+    private readonly toFiltersFn;
+    private readonly hydrateOnStart;
+    private isSyncing;
+    private unsubscribeEngine;
+    private unsubscribeHistory;
+    constructor(opts: UrlSyncOptions<TFilters>);
+    start(engine: UrlSyncEngine<TFilters>): void;
+    stop(): void;
+    private syncEngineToHistory;
+    private applyFiltersSafely;
+    private withSyncGuard;
+}
+
 /**
  * Aggregated provider props — the composition entry point of
  * react-listing-engine, mirroring `react-wizard-engine`'s
@@ -296,8 +378,8 @@ interface IListingFiltersProps {
      * styling hook -- this component stays structure-only, so it never bakes
      * in its own layout beyond the `space-y-5` fallback below. Pass a
      * horizontal row (e.g. `"flex flex-wrap items-end gap-3"`) to flow filter
-     * groups inline instead of stacking them, as `/shadcn`'s `ListingLayout`
-     * does for its top filter bar.
+     * groups inline instead of stacking them, as the `/styled` adapter's
+     * `StyledListingLayout` does for its top filter bar.
      */
     className?: string;
     /** ClassName applied to each individual filter group's wrapper `<div>` (including the string-placeholder case). */
@@ -322,7 +404,7 @@ interface IListingFiltersProps {
  *   `"text"`/`"range"`/`"toggle"`): there is no shared named-control registry
  *   yet, so this renders an inert `<div data-filter={def.key} />` placeholder.
  *   Wiring a real named-control registry (so `"range"` etc. resolve to an
- *   actual control, likely in the `/shadcn` adapter) is a documented future
+ *   actual control) is a documented future
  *   enhancement, not attempted in this task.
  *
  * Each filter group is wrapped in its own `<div>`: when `def.label` is set,
@@ -488,8 +570,8 @@ declare function ListingMap(props: IListingMapProps): react.JSX.Element;
  *
  * Renders a plain `<button>` rather than an injected component: `useListingComponents()`
  * (`IListingComponents`) has no `Button` slot yet, so there is nothing to
- * delegate to here. Wiring this up to a real Button slot (and to the shadcn
- * adapter's styled Button) is a documented future enhancement once that slot
+ * delegate to here. Wiring this up to a real Button slot (and a styled Button
+ * in the `/styled` adapter) is a documented future enhancement once that slot
  * exists.
  */
 declare function ListingPagination(): react.JSX.Element | null;
@@ -676,4 +758,4 @@ interface IListingProviderComponentProps<TFilters> extends IListingProviderProps
  */
 declare function ListingProvider<TEntity, TFilters>(props: IListingProviderComponentProps<TFilters>): react.JSX.Element | null;
 
-export { Bounds, BrowserHistoryPort, type BrowserHistoryPortOptions, DatasetDefinition, DatasetRegistry, EntityId, FilterRegistry, HistoryPort, IListingConfigOptions, type IListingFiltersProps, type IListingMapProps, type IListingProviderProps, IListingToolbarProps, LatLng, ListingConfig, ListingEngine, ListingEngineContext, type ListingEngineOptions, type ListingEvent, ListingEventType, ListingFilters, ListingList, ListingMap, ListingPagination, ListingProvider, type ListingProviderMod, ListingResultHeader, type ListingState, ListingStore, type ListingStoreInit, ListingToolbar, MapPoint, MapProvider, MemoryHistoryPort, Page, PaginationMode, QueryParams, TypedEmitter, Unsubscribe, UrlSyncController, composeListingProviders, listingDefaultConfig, useListing, useListingEvent, useListingFilters, useListingLayer, useListingMap, useListingResults, useListingState, withConfig, withDataset, withFilters, withInitialFilters, withMap, withPrimaryDataset, withUrlSync };
+export { Bounds, BrowserHistoryPort, type BrowserHistoryPortOptions, DatasetDefinition, DatasetRegistry, EntityId, FilterRegistry, type HistoryPort, IListingConfigOptions, type IListingFiltersProps, type IListingMapProps, type IListingProviderProps, IListingToolbarProps, LatLng, ListingConfig, ListingEngine, ListingEngineContext, type ListingEngineOptions, type ListingEvent, ListingEventType, ListingFilters, ListingList, ListingMap, ListingPagination, ListingProvider, type ListingProviderMod, ListingResultHeader, type ListingState, ListingStore, type ListingStoreInit, ListingToolbar, MapPoint, MapProvider, MemoryHistoryPort, Page, PaginationMode, QueryParams, TypedEmitter, Unsubscribe, UrlSyncController, type UrlSyncEngine, type UrlSyncOptions, composeListingProviders, listingDefaultConfig, useListing, useListingEvent, useListingFilters, useListingLayer, useListingMap, useListingResults, useListingState, withConfig, withDataset, withFilters, withInitialFilters, withMap, withPrimaryDataset, withUrlSync };

package/dist/index.js

@@ -1,2 +1,2 @@
 "use client";
-import{a as S}from"./chunk-35KYEBAC.js";import{a as K,p as f}from"./chunk-CGT3RHJ7.js";import{A as J,B as N,a as P,b as L,c as x,d as b,e as v,f as Q,g as C,h as k,i as q,j as B,k as I,l as H,m as R,n as $,o as O,p as A,q as p,r as F,s as n,t as a,u as T,v as U,w as j,x as z,y as D,z as G}from"./chunk-R3FX2V3N.js";var y=(o=>(o.Paged="paged",o.Infinite="infinite",o))(y||{});var h=(r=>(r.FiltersChanged="FiltersChanged",r.ResultsLoaded="ResultsLoaded",r.PointClicked="PointClicked",r.BoundsChanged="BoundsChanged",r.LayerToggled="LayerToggled",r))(h||{});var d=class{query;listeners=new Set;constructor(e={}){this.query={...e}}getQuery(){return{...this.query}}setQuery(e){this.query={...e},this.notify()}subscribe(e){return this.listeners.add(e),()=>{this.listeners.delete(e)}}notify(){for(let e of[...this.listeners])e()}};var c=class{mode;constructor(e={}){this.mode=e.mode??"replace"}getQuery(){if(typeof window>"u")return{};let e=new URLSearchParams(window.location.search),o={};for(let[i,s]of e)s!==""&&(o[i]=s);return o}setQuery(e){if(typeof window>"u")return;let o=new URLSearchParams;for(let[m,u]of Object.entries(e))u===void 0||u===""||o.set(m,u);let i=o.toString(),s=i?`?${i}`:"";if(s===window.location.search)return;let r=`${window.location.pathname}${s}${window.location.hash}`;this.mode==="push"?window.history.pushState(window.history.state,"",r):window.history.replaceState(window.history.state,"",r)}subscribe(e){return typeof window>"u"?()=>{}:(window.addEventListener("popstate",e),()=>{window.removeEventListener("popstate",e)})}};import{jsx as w}from"react/jsx-runtime";function _({children:t}){let{Toolbar:e}=p();return w(e,{children:t})}import{useCallback as l}from"react";function re(){let t=n(),e=a(),o=l(s=>t.loadPoints(s),[t]),i=l((s,r)=>t.selectPoint(s,r),[t]);return{bounds:e.bounds,points:e.points,loadPoints:o,selectPoint:i}}import{useCallback as g}from"react";function ue(t){let e=n(),o=a(),i=g(()=>e.toggleLayer(t),[e,t]);return{visible:o.layers[t]??!0,points:o.points[t]??[],toggle:i}}export{c as BrowserHistoryPort,x as DatasetRegistry,L as FilterRegistry,f as ListingApp,A as ListingComponentsProvider,Q as ListingConfig,C as ListingEngine,F as ListingEngineContext,h as ListingEventType,U as ListingFilters,z as ListingList,D as ListingMap,G as ListingPagination,N as ListingProvider,J as ListingResultHeader,P as ListingStore,_ as ListingToolbar,d as MemoryHistoryPort,y as PaginationMode,b as TypedEmitter,S as UrlSyncController,k as composeListingProviders,v as listingDefaultConfig,n as useListing,p as useListingComponents,K as useListingEvent,T as useListingFilters,ue as useListingLayer,re as useListingMap,j as useListingResults,a as useListingState,q as withConfig,I as withDataset,H as withFilters,$ as withInitialFilters,B as withMap,O as withPrimaryDataset,R as withUrlSync};
+import{A as J,B as K,C as N,R as f,a as w,b as F,c as S,d as Q,e as x,f as T,g as L,h as H,i as O,j as k,k as q,l as E,m as C,n as U,o as B,p as I,q as l,r as G,s as n,t as a,u as R,v as $,w as j,x as A,y as z,z as D}from"./chunk-OXSYNZAJ.js";var m=(e=>(e.Paged="paged",e.Infinite="infinite",e))(m||{});var g=(s=>(s.FiltersChanged="FiltersChanged",s.ResultsLoaded="ResultsLoaded",s.PointClicked="PointClicked",s.BoundsChanged="BoundsChanged",s.LayerToggled="LayerToggled",s))(g||{});var y=class{query;listeners=new Set;constructor(t={}){this.query={...t}}getQuery(){return{...this.query}}setQuery(t){this.query={...t},this.notify()}subscribe(t){return this.listeners.add(t),()=>{this.listeners.delete(t)}}notify(){for(let t of[...this.listeners])t()}};function P(r,t){let e=new Set([...Object.keys(r),...Object.keys(t)]);for(let i of e)if(r[i]!==t[i])return!1;return!0}var c=class{history;toQueryFn;toFiltersFn;hydrateOnStart;isSyncing=!1;unsubscribeEngine=null;unsubscribeHistory=null;constructor(t){this.history=t.history,this.toQueryFn=t.toQuery,this.toFiltersFn=t.toFilters,this.hydrateOnStart=t.hydrateOnStart??!0}start(t){this.stop(),this.unsubscribeEngine=t.subscribe(()=>{this.isSyncing||this.syncEngineToHistory(t)}),this.unsubscribeHistory=this.history.subscribe(()=>{this.isSyncing||this.withSyncGuard(()=>{this.applyFiltersSafely(t,this.toFiltersFn(this.history.getQuery()))})}),this.hydrateOnStart&&this.withSyncGuard(()=>{this.applyFiltersSafely(t,this.toFiltersFn(this.history.getQuery()))})}stop(){this.unsubscribeEngine?.(),this.unsubscribeEngine=null,this.unsubscribeHistory?.(),this.unsubscribeHistory=null}syncEngineToHistory(t){let e=this.toQueryFn(t.state.filters);P(e,this.history.getQuery())||this.withSyncGuard(()=>this.history.setQuery(e))}applyFiltersSafely(t,e){Promise.resolve(t.applyFilters(e)).catch(()=>{})}withSyncGuard(t){this.isSyncing=!0;try{t()}finally{this.isSyncing=!1}}};var p=class{mode;constructor(t={}){this.mode=t.mode??"replace"}getQuery(){if(typeof window>"u")return{};let t=new URLSearchParams(window.location.search),e={};for(let[i,o]of t)o!==""&&(e[i]=o);return e}setQuery(t){if(typeof window>"u")return;let e=new URLSearchParams;for(let[h,u]of Object.entries(t))u===void 0||u===""||e.set(h,u);let i=e.toString(),o=i?`?${i}`:"";if(o===window.location.search)return;let s=`${window.location.pathname}${o}${window.location.hash}`;this.mode==="push"?window.history.pushState(window.history.state,"",s):window.history.replaceState(window.history.state,"",s)}subscribe(t){return typeof window>"u"?()=>{}:(window.addEventListener("popstate",t),()=>{window.removeEventListener("popstate",t)})}};import{jsx as b}from"react/jsx-runtime";function M({children:r}){let{Toolbar:t}=l();return b(t,{children:r})}import{useCallback as d}from"react";function ot(){let r=n(),t=a(),e=d(o=>r.loadPoints(o),[r]),i=d((o,s)=>r.selectPoint(o,s),[r]);return{bounds:t.bounds,points:t.points,loadPoints:e,selectPoint:i}}import{useCallback as v}from"react";function yt(r){let t=n(),e=a(),i=v(()=>t.toggleLayer(r),[t,r]);return{visible:e.layers[r]??!0,points:e.points[r]??[],toggle:i}}export{p as BrowserHistoryPort,S as DatasetRegistry,F as FilterRegistry,f as ListingApp,I as ListingComponentsProvider,T as ListingConfig,L as ListingEngine,G as ListingEngineContext,g as ListingEventType,$ as ListingFilters,A as ListingList,z as ListingMap,D as ListingPagination,N as ListingProvider,J as ListingResultHeader,w as ListingStore,M as ListingToolbar,y as MemoryHistoryPort,m as PaginationMode,Q as TypedEmitter,c as UrlSyncController,H as composeListingProviders,x as listingDefaultConfig,n as useListing,l as useListingComponents,K as useListingEvent,R as useListingFilters,yt as useListingLayer,ot as useListingMap,j as useListingResults,a as useListingState,O as withConfig,q as withDataset,E as withFilters,U as withInitialFilters,k as withMap,B as withPrimaryDataset,C as withUrlSync};

package/dist/{listing-app-BSJKGh7k.d.ts → listing-app-4Vs_SMNl.d.cts}

@@ -1,7 +1,132 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { L as LatLng, a as MapProvider } from './map-provider.interface-DT-v1plm.js';
-import { D as DatasetDefinition, F as FilterRegistry, e as IListingComponents, I as IListingConfigOptions } from './components-provider-cWVWEDXC.js';
+import { ComponentType, ReactNode } from 'react';
+import { b as EntityAdapter, M as MapPoint, L as LatLng, a as MapProvider } from './map-provider.interface-DT-v1plm.cjs';
+
+interface FilterControlProps<TValue> {
+    value: TValue;
+    onChange(next: TValue): void;
+}
+interface FilterDefinition<TFilters, TValue = unknown> {
+    key: string;
+    order: number;
+    render: string | ComponentType<FilterControlProps<TValue>>;
+    toParams(value: TValue): Partial<TFilters>;
+    fromParams(filters: TFilters): TValue;
+    isActive?(filters: TFilters): boolean;
+    /** Optional human-readable label rendered above the control by `ListingFilters`. Omit for an unlabeled filter (backward compatible). */
+    label?: string;
+}
+
+interface ClusterOptions {
+    maxZoom?: number;
+    radius?: number;
+}
+interface MarkerRenderer<TEntity> {
+    iconUrl?(entity: TEntity): string;
+    element?(entity: TEntity): HTMLElement;
+    onClick?(entity: TEntity): void;
+}
+interface DatasetDefinition<TEntity, TFilters> {
+    id: string;
+    adapter: EntityAdapter<TEntity, TFilters>;
+    marker: MarkerRenderer<TEntity>;
+    clustering?: ClusterOptions | false;
+    visible?: () => boolean;
+}
+
+declare enum PaginationMode {
+    Paged = "paged",
+    Infinite = "infinite"
+}
+
+interface IListingConfigOptions {
+    pagination: PaginationMode;
+    pageSize: number;
+    debounceMs: number;
+}
+
+/**
+ * Framework-free registry for `FilterDefinition`s: programmatic add / remove /
+ * reorder / replace, plus folding raw control values into `TFilters`
+ * (`toFilters`) and reporting which registered filters currently affect an
+ * applied `TFilters` (`activeKeys`).
+ *
+ * Defs are stored by VALUE (shallow-cloned on `add`/`replace`), never by the
+ * caller's original reference — `reorder()` rewrites `order` in place on the
+ * registry's own copy. This is deliberate: the same `FilterDefinition` object
+ * can legitimately be registered in more than one `FilterRegistry` instance
+ * (e.g. two listing pages sharing a base filter set), and without cloning,
+ * one registry's `reorder()` would silently mutate `.order` on the shared
+ * object and bleed into every other registry (and the caller) holding it.
+ */
+declare class FilterRegistry<TFilters> {
+    private readonly defs;
+    add<TValue = unknown>(def: FilterDefinition<TFilters, TValue>): this;
+    remove(key: string): this;
+    replace<TValue = unknown>(key: string, def: FilterDefinition<TFilters, TValue>): this;
+    reorder(keys: string[]): this;
+    list(): FilterDefinition<TFilters>[];
+    has(key: string): boolean;
+    toFilters(values: Record<string, unknown>): TFilters;
+    activeKeys(filters: TFilters): string[];
+}
+
+interface IListingCardProps {
+    item: unknown;
+    selected?: boolean;
+    onSelect?: () => void;
+}
+interface IListingMarkerProps {
+    point: MapPoint<unknown>;
+}
+interface IListingPopupProps {
+    entity: unknown;
+    onClose?: () => void;
+}
+interface IListingSidebarProps {
+    children?: ReactNode;
+}
+interface IListingFilterPanelProps {
+    children?: ReactNode;
+}
+interface IListingSearchProps {
+    value: string;
+    onChange(value: string): void;
+    placeholder?: string;
+}
+interface IListingEmptyProps {
+}
+interface IListingLoadingProps {
+}
+interface IListingResultHeaderProps {
+    count: number;
+    total?: number;
+}
+interface IListingToolbarProps {
+    children?: ReactNode;
+}
+interface IListingComponents {
+    Card: ComponentType<IListingCardProps>;
+    Marker: ComponentType<IListingMarkerProps>;
+    Popup: ComponentType<IListingPopupProps>;
+    Sidebar: ComponentType<IListingSidebarProps>;
+    FilterPanel: ComponentType<IListingFilterPanelProps>;
+    Search: ComponentType<IListingSearchProps>;
+    Empty: ComponentType<IListingEmptyProps>;
+    Loading: ComponentType<IListingLoadingProps>;
+    ResultHeader: ComponentType<IListingResultHeaderProps>;
+    Toolbar: ComponentType<IListingToolbarProps>;
+}
+/**
+ * Injection point for custom-component overrides. Every slot is optional —
+ * anything not provided falls back to the (unstyled) default. Mirrors
+ * `react-wizard-engine`'s `WizardComponentsProvider`: explicit per-slot
+ * `provided ?? defaults.X` merge, not a generic/reflective loop.
+ */
+declare function ListingComponentsProvider(props: Partial<IListingComponents> & {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useListingComponents(): IListingComponents;
 
 type BottomNavView = 'list' | 'map';
 interface IBottomNavAction {
@@ -27,8 +152,8 @@ declare function BottomNav({ view, onViewChange }: IBottomNavProps): react.JSX.E
 
 interface IStyledListingLayoutProps {
     /**
-     * Optional header search box, LIBRARY-wired (unlike `/shadcn`'s
-     * consumer-managed `search`): name the `TFilters` field it drives via
+     * Optional header search box, LIBRARY-wired: name the `TFilters` field it
+     * drives via
      * `filterKey`, and the layout reads the current value from the engine's
      * filters and writes edits back with `applyFilters({ [filterKey]: value ||
      * undefined })`. Rendered in BOTH the desktop filter bar and the mobile
@@ -59,12 +184,11 @@ interface IStyledListingLayoutProps {
     className?: string;
 }
 /**
- * Full, responsive, Tailwind-free listing experience -- the `/styled`
- * counterpart to `/shadcn`'s `ListingLayout`, built from the same
+ * Full, responsive, Tailwind-free listing experience -- built from the
  * structure-only compound components (`~/react`) plus the injected
- * `Styled*` slot components, but with a richer mobile experience: a bottom
- * nav (`BottomNav`) and a bottom sheet (`BottomSheet`) for filters, instead
- * of `/shadcn`'s inline mobile toggle bar. Every class used here is one of
+ * `Styled*` slot components, with a rich mobile experience: a bottom
+ * nav (`BottomNav`) and a bottom sheet (`BottomSheet`) for filters. Every
+ * class used here is one of
  * the `.rle-*` layout classes added to `styles.css` alongside this file --
  * no Tailwind, no inline styles, no other stylesheet required.
  *
@@ -96,18 +220,17 @@ interface IStyledListingLayoutProps {
  *   control already applies live via its own `onChange`, so there is nothing
  *   left to commit).
  * - Fetches the first page itself on mount (`engine.applyFilters({})`) by
- *   default, exactly like `/shadcn`'s `ListingLayout` -- pass `autoFetch={false}`
+ *   default -- pass `autoFetch={false}`
  *   to opt out and drive the first fetch yourself.
  */
 declare function StyledListingLayout({ search, toolbarEnd, mobileAction, autoFetch, hasMap, mapCenter, mapZoom, className, }: IStyledListingLayoutProps): react.JSX.Element;
 
 /**
- * Same two-shape `map` prop as `/shadcn`'s `ListingApp` (see that file's
- * `useResolvedMap` doc comment for why the `{ apiKey }` shorthand is resolved
- * via a dynamic `import()` rather than a static one -- the reasoning is
- * identical here). Re-declared rather than imported from `~/shadcn`: the two
- * styled adapters are SIBLINGS, not a hierarchy -- `/styled` never depends on
- * `/shadcn` (or vice versa), each is self-contained against `~/core`/`~/react`.
+ * Two-shape `map` prop: pass a ready `MapProvider`, or the `{ apiKey, mapId? }`
+ * shorthand. The shorthand is resolved via a DYNAMIC `import()` of
+ * `~/maps/google` (see `useResolvedMap` below) rather than a static one, so an
+ * app that never sets `map` doesn't pull `@googlemaps/js-api-loader` into its
+ * bundle.
  */
 type ListingAppMapProp = {
     provider: MapProvider;
@@ -175,9 +298,8 @@ interface ListingAppProps<TFilters> {
     className?: string;
 }
 /**
- * Turnkey, batteries-included, Tailwind-free entry point -- the `/styled`
- * counterpart to `/shadcn`'s `ListingApp`, and (per `src/index.ts`) the
- * package's MAIN-ENTRY default: `import { ListingApp } from
+ * Turnkey, batteries-included, Tailwind-free entry point -- and (per
+ * `src/index.ts`) the package's MAIN-ENTRY default: `import { ListingApp } from
  * 'react-listing-engine'` gives you this component. Pass datasets + filters +
  * a map + component overrides, and `ListingApp` composes
  * `composeListingProviders(...)`, `<ListingProvider>`, the `/styled` defaults,
@@ -198,8 +320,8 @@ interface ListingAppProps<TFilters> {
  * nesting would silently discard every un-overridden `/styled` default
  * instead of keeping it.
  *
- * URL SYNC IS EVENT-BASED, NOT INTERNAL: unlike `/shadcn`'s `ListingApp`,
- * this component takes no `urlSync` prop and never constructs/starts a
+ * URL SYNC IS EVENT-BASED, NOT INTERNAL: this component takes no `urlSync`
+ * prop and never constructs/starts a
  * `UrlSyncController` -- it never touches `window.history`. Instead it
  * accepts `initialFilters` (hydrate FROM the consumer's URL) and emits
  * `onFiltersChange` (write TO the consumer's URL/router) -- see both props'
@@ -210,4 +332,4 @@ interface ListingAppProps<TFilters> {
  */
 declare function ListingApp<TEntity, TFilters>(props: ListingAppProps<TFilters>): react.JSX.Element | null;
 
-export { BottomNav as B, type IBottomNavAction as I, ListingApp as L, StyledListingLayout as S, type ListingAppProps as a, type BottomNavView as b, type IBottomNavProps as c, type IStyledListingLayoutProps as d, type ListingAppMapProp as e };
+export { BottomNav as B, type ClusterOptions as C, type DatasetDefinition as D, FilterRegistry as F, type IListingConfigOptions as I, ListingApp as L, type MarkerRenderer as M, PaginationMode as P, StyledListingLayout as S, type IListingToolbarProps as a, type FilterControlProps as b, type FilterDefinition as c, type IListingCardProps as d, type IListingComponents as e, type IListingEmptyProps as f, type IListingFilterPanelProps as g, type IListingLoadingProps as h, type IListingMarkerProps as i, type IListingPopupProps as j, type IListingResultHeaderProps as k, type IListingSearchProps as l, type IListingSidebarProps as m, type ListingAppProps as n, ListingComponentsProvider as o, type BottomNavView as p, type IBottomNavAction as q, type IBottomNavProps as r, type IStyledListingLayoutProps as s, type ListingAppMapProp as t, useListingComponents as u };

package/dist/{listing-app-BMoMKD4c.d.cts → listing-app-CkEGdUV9.d.ts}

@@ -1,7 +1,132 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { L as LatLng, a as MapProvider } from './map-provider.interface-DT-v1plm.cjs';
-import { D as DatasetDefinition, F as FilterRegistry, e as IListingComponents, I as IListingConfigOptions } from './components-provider-FinfaqUT.cjs';
+import { ComponentType, ReactNode } from 'react';
+import { b as EntityAdapter, M as MapPoint, L as LatLng, a as MapProvider } from './map-provider.interface-DT-v1plm.js';
+
+interface FilterControlProps<TValue> {
+    value: TValue;
+    onChange(next: TValue): void;
+}
+interface FilterDefinition<TFilters, TValue = unknown> {
+    key: string;
+    order: number;
+    render: string | ComponentType<FilterControlProps<TValue>>;
+    toParams(value: TValue): Partial<TFilters>;
+    fromParams(filters: TFilters): TValue;
+    isActive?(filters: TFilters): boolean;
+    /** Optional human-readable label rendered above the control by `ListingFilters`. Omit for an unlabeled filter (backward compatible). */
+    label?: string;
+}
+
+interface ClusterOptions {
+    maxZoom?: number;
+    radius?: number;
+}
+interface MarkerRenderer<TEntity> {
+    iconUrl?(entity: TEntity): string;
+    element?(entity: TEntity): HTMLElement;
+    onClick?(entity: TEntity): void;
+}
+interface DatasetDefinition<TEntity, TFilters> {
+    id: string;
+    adapter: EntityAdapter<TEntity, TFilters>;
+    marker: MarkerRenderer<TEntity>;
+    clustering?: ClusterOptions | false;
+    visible?: () => boolean;
+}
+
+declare enum PaginationMode {
+    Paged = "paged",
+    Infinite = "infinite"
+}
+
+interface IListingConfigOptions {
+    pagination: PaginationMode;
+    pageSize: number;
+    debounceMs: number;
+}
+
+/**
+ * Framework-free registry for `FilterDefinition`s: programmatic add / remove /
+ * reorder / replace, plus folding raw control values into `TFilters`
+ * (`toFilters`) and reporting which registered filters currently affect an
+ * applied `TFilters` (`activeKeys`).
+ *
+ * Defs are stored by VALUE (shallow-cloned on `add`/`replace`), never by the
+ * caller's original reference — `reorder()` rewrites `order` in place on the
+ * registry's own copy. This is deliberate: the same `FilterDefinition` object
+ * can legitimately be registered in more than one `FilterRegistry` instance
+ * (e.g. two listing pages sharing a base filter set), and without cloning,
+ * one registry's `reorder()` would silently mutate `.order` on the shared
+ * object and bleed into every other registry (and the caller) holding it.
+ */
+declare class FilterRegistry<TFilters> {
+    private readonly defs;
+    add<TValue = unknown>(def: FilterDefinition<TFilters, TValue>): this;
+    remove(key: string): this;
+    replace<TValue = unknown>(key: string, def: FilterDefinition<TFilters, TValue>): this;
+    reorder(keys: string[]): this;
+    list(): FilterDefinition<TFilters>[];
+    has(key: string): boolean;
+    toFilters(values: Record<string, unknown>): TFilters;
+    activeKeys(filters: TFilters): string[];
+}
+
+interface IListingCardProps {
+    item: unknown;
+    selected?: boolean;
+    onSelect?: () => void;
+}
+interface IListingMarkerProps {
+    point: MapPoint<unknown>;
+}
+interface IListingPopupProps {
+    entity: unknown;
+    onClose?: () => void;
+}
+interface IListingSidebarProps {
+    children?: ReactNode;
+}
+interface IListingFilterPanelProps {
+    children?: ReactNode;
+}
+interface IListingSearchProps {
+    value: string;
+    onChange(value: string): void;
+    placeholder?: string;
+}
+interface IListingEmptyProps {
+}
+interface IListingLoadingProps {
+}
+interface IListingResultHeaderProps {
+    count: number;
+    total?: number;
+}
+interface IListingToolbarProps {
+    children?: ReactNode;
+}
+interface IListingComponents {
+    Card: ComponentType<IListingCardProps>;
+    Marker: ComponentType<IListingMarkerProps>;
+    Popup: ComponentType<IListingPopupProps>;
+    Sidebar: ComponentType<IListingSidebarProps>;
+    FilterPanel: ComponentType<IListingFilterPanelProps>;
+    Search: ComponentType<IListingSearchProps>;
+    Empty: ComponentType<IListingEmptyProps>;
+    Loading: ComponentType<IListingLoadingProps>;
+    ResultHeader: ComponentType<IListingResultHeaderProps>;
+    Toolbar: ComponentType<IListingToolbarProps>;
+}
+/**
+ * Injection point for custom-component overrides. Every slot is optional —
+ * anything not provided falls back to the (unstyled) default. Mirrors
+ * `react-wizard-engine`'s `WizardComponentsProvider`: explicit per-slot
+ * `provided ?? defaults.X` merge, not a generic/reflective loop.
+ */
+declare function ListingComponentsProvider(props: Partial<IListingComponents> & {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useListingComponents(): IListingComponents;
 
 type BottomNavView = 'list' | 'map';
 interface IBottomNavAction {
@@ -27,8 +152,8 @@ declare function BottomNav({ view, onViewChange }: IBottomNavProps): react.JSX.E
 
 interface IStyledListingLayoutProps {
     /**
-     * Optional header search box, LIBRARY-wired (unlike `/shadcn`'s
-     * consumer-managed `search`): name the `TFilters` field it drives via
+     * Optional header search box, LIBRARY-wired: name the `TFilters` field it
+     * drives via
      * `filterKey`, and the layout reads the current value from the engine's
      * filters and writes edits back with `applyFilters({ [filterKey]: value ||
      * undefined })`. Rendered in BOTH the desktop filter bar and the mobile
@@ -59,12 +184,11 @@ interface IStyledListingLayoutProps {
     className?: string;
 }
 /**
- * Full, responsive, Tailwind-free listing experience -- the `/styled`
- * counterpart to `/shadcn`'s `ListingLayout`, built from the same
+ * Full, responsive, Tailwind-free listing experience -- built from the
  * structure-only compound components (`~/react`) plus the injected
- * `Styled*` slot components, but with a richer mobile experience: a bottom
- * nav (`BottomNav`) and a bottom sheet (`BottomSheet`) for filters, instead
- * of `/shadcn`'s inline mobile toggle bar. Every class used here is one of
+ * `Styled*` slot components, with a rich mobile experience: a bottom
+ * nav (`BottomNav`) and a bottom sheet (`BottomSheet`) for filters. Every
+ * class used here is one of
  * the `.rle-*` layout classes added to `styles.css` alongside this file --
  * no Tailwind, no inline styles, no other stylesheet required.
  *
@@ -96,18 +220,17 @@ interface IStyledListingLayoutProps {
  *   control already applies live via its own `onChange`, so there is nothing
  *   left to commit).
  * - Fetches the first page itself on mount (`engine.applyFilters({})`) by
- *   default, exactly like `/shadcn`'s `ListingLayout` -- pass `autoFetch={false}`
+ *   default -- pass `autoFetch={false}`
  *   to opt out and drive the first fetch yourself.
  */
 declare function StyledListingLayout({ search, toolbarEnd, mobileAction, autoFetch, hasMap, mapCenter, mapZoom, className, }: IStyledListingLayoutProps): react.JSX.Element;
 
 /**
- * Same two-shape `map` prop as `/shadcn`'s `ListingApp` (see that file's
- * `useResolvedMap` doc comment for why the `{ apiKey }` shorthand is resolved
- * via a dynamic `import()` rather than a static one -- the reasoning is
- * identical here). Re-declared rather than imported from `~/shadcn`: the two
- * styled adapters are SIBLINGS, not a hierarchy -- `/styled` never depends on
- * `/shadcn` (or vice versa), each is self-contained against `~/core`/`~/react`.
+ * Two-shape `map` prop: pass a ready `MapProvider`, or the `{ apiKey, mapId? }`
+ * shorthand. The shorthand is resolved via a DYNAMIC `import()` of
+ * `~/maps/google` (see `useResolvedMap` below) rather than a static one, so an
+ * app that never sets `map` doesn't pull `@googlemaps/js-api-loader` into its
+ * bundle.
  */
 type ListingAppMapProp = {
     provider: MapProvider;
@@ -175,9 +298,8 @@ interface ListingAppProps<TFilters> {
     className?: string;
 }
 /**
- * Turnkey, batteries-included, Tailwind-free entry point -- the `/styled`
- * counterpart to `/shadcn`'s `ListingApp`, and (per `src/index.ts`) the
- * package's MAIN-ENTRY default: `import { ListingApp } from
+ * Turnkey, batteries-included, Tailwind-free entry point -- and (per
+ * `src/index.ts`) the package's MAIN-ENTRY default: `import { ListingApp } from
  * 'react-listing-engine'` gives you this component. Pass datasets + filters +
  * a map + component overrides, and `ListingApp` composes
  * `composeListingProviders(...)`, `<ListingProvider>`, the `/styled` defaults,
@@ -198,8 +320,8 @@ interface ListingAppProps<TFilters> {
  * nesting would silently discard every un-overridden `/styled` default
  * instead of keeping it.
  *
- * URL SYNC IS EVENT-BASED, NOT INTERNAL: unlike `/shadcn`'s `ListingApp`,
- * this component takes no `urlSync` prop and never constructs/starts a
+ * URL SYNC IS EVENT-BASED, NOT INTERNAL: this component takes no `urlSync`
+ * prop and never constructs/starts a
  * `UrlSyncController` -- it never touches `window.history`. Instead it
  * accepts `initialFilters` (hydrate FROM the consumer's URL) and emits
  * `onFiltersChange` (write TO the consumer's URL/router) -- see both props'
@@ -210,4 +332,4 @@ interface ListingAppProps<TFilters> {
  */
 declare function ListingApp<TEntity, TFilters>(props: ListingAppProps<TFilters>): react.JSX.Element | null;
 
-export { BottomNav as B, type IBottomNavAction as I, ListingApp as L, StyledListingLayout as S, type ListingAppProps as a, type BottomNavView as b, type IBottomNavProps as c, type IStyledListingLayoutProps as d, type ListingAppMapProp as e };
+export { BottomNav as B, type ClusterOptions as C, type DatasetDefinition as D, FilterRegistry as F, type IListingConfigOptions as I, ListingApp as L, type MarkerRenderer as M, PaginationMode as P, StyledListingLayout as S, type IListingToolbarProps as a, type FilterControlProps as b, type FilterDefinition as c, type IListingCardProps as d, type IListingComponents as e, type IListingEmptyProps as f, type IListingFilterPanelProps as g, type IListingLoadingProps as h, type IListingMarkerProps as i, type IListingPopupProps as j, type IListingResultHeaderProps as k, type IListingSearchProps as l, type IListingSidebarProps as m, type ListingAppProps as n, ListingComponentsProvider as o, type BottomNavView as p, type IBottomNavAction as q, type IBottomNavProps as r, type IStyledListingLayoutProps as s, type ListingAppMapProp as t, useListingComponents as u };

package/dist/styled/index.cjs

@@ -1,2 +1,2 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
-var _chunkRXHR66FScjs = require('../chunk-RXHR66FS.cjs');var _chunkEYXV5OMYcjs = require('../chunk-EYXV5OMY.cjs');var _jsxruntime = require('react/jsx-runtime');function L({children:o}){return _jsxruntime.jsx.call(void 0, _chunkEYXV5OMYcjs.p,{..._chunkRXHR66FScjs.l,children:o})}exports.BottomNav = _chunkRXHR66FScjs.m; exports.BottomSheet = _chunkRXHR66FScjs.n; exports.ListingApp = _chunkRXHR66FScjs.p; exports.StyledCard = _chunkRXHR66FScjs.b; exports.StyledComponentsProviderWithDefaults = L; exports.StyledEmpty = _chunkRXHR66FScjs.c; exports.StyledFilterPanel = _chunkRXHR66FScjs.d; exports.StyledListingLayout = _chunkRXHR66FScjs.o; exports.StyledLoading = _chunkRXHR66FScjs.e; exports.StyledMarker = _chunkRXHR66FScjs.f; exports.StyledPopup = _chunkRXHR66FScjs.g; exports.StyledResultHeader = _chunkRXHR66FScjs.h; exports.StyledSearch = _chunkRXHR66FScjs.i; exports.StyledSidebar = _chunkRXHR66FScjs.j; exports.StyledToolbar = _chunkRXHR66FScjs.k; exports.styledDefaultComponents = _chunkRXHR66FScjs.l;
+var _chunkPE27NATScjs = require('../chunk-PE27NATS.cjs');var _jsxruntime = require('react/jsx-runtime');function L({children:o}){return _jsxruntime.jsx.call(void 0, _chunkPE27NATScjs.p,{..._chunkPE27NATScjs.N,children:o})}exports.BottomNav = _chunkPE27NATScjs.O; exports.BottomSheet = _chunkPE27NATScjs.P; exports.ListingApp = _chunkPE27NATScjs.R; exports.StyledCard = _chunkPE27NATScjs.D; exports.StyledComponentsProviderWithDefaults = L; exports.StyledEmpty = _chunkPE27NATScjs.E; exports.StyledFilterPanel = _chunkPE27NATScjs.F; exports.StyledListingLayout = _chunkPE27NATScjs.Q; exports.StyledLoading = _chunkPE27NATScjs.G; exports.StyledMarker = _chunkPE27NATScjs.H; exports.StyledPopup = _chunkPE27NATScjs.I; exports.StyledResultHeader = _chunkPE27NATScjs.J; exports.StyledSearch = _chunkPE27NATScjs.K; exports.StyledSidebar = _chunkPE27NATScjs.L; exports.StyledToolbar = _chunkPE27NATScjs.M; exports.styledDefaultComponents = _chunkPE27NATScjs.N;