react-listing-engine 0.6.5 → 0.6.7

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-IG1awue3.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-IG1awue3.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-GSWGCJCO.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-BtNNEkX1.d.cts

@@ -0,0 +1,347 @@
+import * as react from 'react';
+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`), reporting which registered filters currently affect an
+ * applied `TFilters` (`activeKeys`), and building the reset-everything patch
+ * (`clearedParams`).
+ *
+ * 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[];
+    clearedParams(): Partial<TFilters>;
+}
+
+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';
+/**
+ * An action button in the mobile chrome (e.g. "Add"/"Save"). Despite the
+ * name (kept for API compatibility), it renders in `MobileHeader`, not here.
+ */
+interface IBottomNavAction {
+    label: string;
+    icon?: ReactNode;
+    onClick(): void;
+}
+interface IBottomNavProps {
+    view: BottomNavView;
+    onViewChange(view: BottomNavView): void;
+}
+/**
+ * Mobile-only bottom navigation (`.rle-bottom-nav`, CSS-hidden above the
+ * mobile breakpoint -- see `styles.css`'s layout-shell section, the single
+ * source of truth for it): a floating **List | Map** segmented toggle
+ * (`.rle-viewtoggle`) that drives which of `StyledListingLayout`'s two
+ * full-area panels is visible. The **Filters** button and the optional caller
+ * action (e.g. "Save") live in the mobile header (`MobileHeader`) instead, so
+ * the footer pill carries the view toggle alone. No lucide/icon library
+ * dependency -- every icon here is a small inline SVG, matching the rest of
+ * `/styled`'s zero-extra-dependency policy.
+ */
+declare function BottomNav({ view, onViewChange }: IBottomNavProps): react.JSX.Element;
+
+interface IStyledListingLayoutProps {
+    /**
+     * 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
+     * header. Do NOT also register `filterKey` as a `ListingFilters` control --
+     * it would then render twice. Omitted entirely when not passed.
+     */
+    search?: {
+        filterKey: string;
+        placeholder?: string;
+    };
+    /** Extra content rendered in `.rle-list-header` (above the list), to the right of `ListingResultHeader` (e.g. a sort control + save-search). */
+    toolbarEnd?: ReactNode;
+    /** Optional mobile-header action button (e.g. "Save"), forwarded verbatim to `<MobileHeader action={...} />`. Omit to render just the search + Filters button there. */
+    mobileAction?: IBottomNavAction;
+    /**
+     * Whether a map is configured. When `false`, the map region is dropped and
+     * the results list fills the full width as a multi-column grid, and the
+     * mobile List|Map toggle is omitted (nothing to toggle to). Defaults to
+     * `engine.map != null` -- the engine is the source of truth, so this only
+     * needs passing to override that (e.g. to hide a configured map).
+     */
+    hasMap?: boolean;
+    /** Whether the layout fetches the first page itself on mount (`engine.applyFilters({})`). Defaults to `true`. */
+    autoFetch?: boolean;
+    /** Forwarded verbatim to `<ListingMap center={mapCenter} />` -- see that component's "Auto-fit" doc comment. */
+    mapCenter?: LatLng;
+    /** Forwarded verbatim to `<ListingMap zoom={mapZoom} />`. */
+    mapZoom?: number;
+    className?: string;
+}
+/**
+ * Full, responsive, Tailwind-free listing experience -- built from the
+ * structure-only compound components (`~/react`) plus the injected
+ * `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.
+ *
+ * STRUCTURE (`.rle-app`) -- the mobile/desktop breakpoint and the grid's
+ * column sizing live in ONE place, `styles.css`'s layout-shell section; the
+ * bullets below say only which side of it each piece renders on:
+ * - `.rle-filter-bar` (desktop only, CSS-hidden below the breakpoint): the
+ *   optional `Search` slot and `<ListingFilters>` laid out as a single
+ *   horizontally-scrolling row (`className="rle-filters-row"`,
+ *   `groupClassName="rle-filter-group"`) with edge fades. The result header +
+ *   `toolbarEnd` are NOT here -- they sit in `.rle-list-header` above the list.
+ * - `.rle-list-header` (top of `.rle-list`): `<ListingResultHeader>` (title +
+ *   count) at the left, `toolbarEnd` (sort control, save-search, ...) at the
+ *   right -- a heading for the results, on every viewport.
+ * - `.rle-body.rle-split`: a list-majority list|map CSS grid from the
+ *   breakpoint up; below it, a single full-area panel with exactly one of
+ *   `.rle-list`/`.rle-map` visible at a time via `data-mobile-view` (see
+ *   `styles.css`'s mobile media query). Both regions stay mounted at ALL
+ *   times regardless of viewport/toggle state -- only their visibility flips
+ *   -- so neither `ListingList` nor `ListingMap` remounts (and re-triggers
+ *   its own mount effects) on toggle or resize.
+ * - `<MobileHeader>` (mobile only): the same search box, a **Filters** button
+ *   (opens the `<BottomSheet>`, with an applied-filter count badge) and the
+ *   optional `mobileAction`.
+ * - `<BottomNav>` (mobile only): the floating List|Map view toggle, wired to
+ *   the same `mobileView` state as the CSS toggle. Omitted when there is no
+ *   map (nothing to toggle to).
+ * - `<BottomSheet title="Filters">`: the SAME `<ListingFilters>` component,
+ *   stacked vertically (`className="rle-filter-stack"`) for the sheet's
+ *   narrower body, plus a footer with "Clear all" (applies
+ *   `engine.filters.clearedParams()` -- see that method's doc for why a reset
+ *   round-trips each def's to/fromParams) and "Show N results" (just closes
+ *   the sheet -- every filter 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 -- pass `autoFetch={false}`
+ *   to opt out and drive the first fetch yourself.
+ */
+declare function StyledListingLayout({ search, toolbarEnd, mobileAction, autoFetch, hasMap: hasMapProp, mapCenter, mapZoom, className, }: IStyledListingLayoutProps): react.JSX.Element;
+
+/**
+ * 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;
+    center?: LatLng;
+    zoom?: number;
+} | {
+    apiKey: string;
+    mapId?: string;
+    center?: LatLng;
+    zoom?: number;
+};
+interface ListingAppProps<TFilters> {
+    /**
+     * One or more marker-layer datasets; the FIRST entry is the primary
+     * dataset (drives the results list + pagination) -- same "insertion
+     * order" rule `composeListingProviders`/`withDataset` already follow.
+     * Entity-erased (`any`, not `TEntity`) for the same reason
+     * `DatasetRegistry<unknown, TFilters>` is: one array can legitimately hold
+     * heterogeneous layers (a properties dataset and a businesses dataset have
+     * different entity types) -- see `compose-listing-providers.ts`'s
+     * `withDataset` doc comment.
+     */
+    datasets: DatasetDefinition<any, TFilters>[];
+    /** A `(reg) => { reg.add(...); }` callback that registers your filters -- forwarded verbatim to `withFilters`. */
+    filters?: (reg: FilterRegistry<TFilters>) => void;
+    /** A ready `MapProvider`, or `{ apiKey, mapId? }` to build a `googleProvider` internally. Omit for no map -- the layout drops the map region and renders the list full-width. */
+    map?: ListingAppMapProp;
+    /** Slot overrides, merged OVER the `/styled` defaults -- see this file's doc comment for how the merge works. */
+    components?: Partial<IListingComponents>;
+    /**
+     * Hydrates the engine's initial filters on mount -- typically parsed from
+     * the CONSUMER's own URL (your own query-string parser over `new
+     * URLSearchParams(window.location.search)`), but any source works. Half
+     * of the event-based URL API this component exposes: `ListingApp` never
+     * reads `window.location` itself, it only accepts filters as a prop.
+     */
+    initialFilters?: TFilters;
+    /**
+     * EVENT OUT: fires with the engine's current filters (`TFilters`, not the
+     * store's `DeepReadonly` wrapper) every time `ListingEventType.FiltersChanged`
+     * fires on the underlying engine -- i.e. on every `engine.applyFilters(...)`
+     * call, INCLUDING the one `StyledListingLayout` makes on mount when
+     * `autoFetch` is on (a `{}` patch that still round-trips through
+     * `currentFilters()` and re-emits the very `initialFilters` this component
+     * was given). That first call is intentionally NOT suppressed: a
+     * consumer's handler is expected to write filters back to a URL via
+     * `history.replaceState` (or a router's equivalent), and replacing the URL
+     * with the SAME query string it already hydrated from is a no-op, not a
+     * visible echo -- so "just always emit" is simpler than tracking a
+     * first-call flag for no behavioral gain. This is the OTHER half of the
+     * event-based URL API: `ListingApp` (and the engine underneath it) never
+     * touches `window.history` -- the CONSUMER owns routing, driven by this
+     * callback plus `initialFilters` above. `UrlSyncController`/`BrowserHistoryPort`
+     * (`~/core`, `~/react`) remain exported as optional, lower-level helpers
+     * for consumers who want the library to own `window.history` directly, but
+     * they are no longer the primary/recommended path for new integrations.
+     */
+    onFiltersChange?: (filters: TFilters) => void;
+    /** The mobile header action (e.g. "Save"/"Add") -- forwarded verbatim to `StyledListingLayout`/`MobileHeader`. */
+    mobileAction?: IBottomNavAction;
+    search?: IStyledListingLayoutProps['search'];
+    toolbarEnd?: IStyledListingLayoutProps['toolbarEnd'];
+    config?: Partial<IListingConfigOptions>;
+    autoFetch?: boolean;
+    className?: string;
+}
+/**
+ * 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,
+ * and `<StyledListingLayout>` for you.
+ *
+ * `TEntity` still can't be inferred from these props (`datasets` narrows it,
+ * but a multi-dataset array widens back to the union/`unknown` in practice)
+ * -- annotate the call site when entity-level typing matters, exactly like
+ * `<ListingProvider<TEntity, TFilters>>` itself.
+ *
+ * COMPONENTS MERGE: `components` overrides are applied ON TOP of the
+ * `/styled` defaults via ONE explicit `{ ...styledDefaultComponents,
+ * ...components }` object, passed to a single `<ListingComponentsProvider>`
+ * -- never as a nested `<ListingComponentsProvider>` inside
+ * `StyledComponentsProviderWithDefaults`. `ListingComponentsProvider` merges
+ * `provided ?? ITS OWN private, unstyled fallbacks` per slot (it does not
+ * read the parent context -- see `src/react/components-provider.tsx`), so
+ * nesting would silently discard every un-overridden `/styled` default
+ * instead of keeping it.
+ *
+ * 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'
+ * doc comments for the full contract. This keeps the library's surface
+ * router-agnostic (a plain `history.replaceState`, a Next.js `router.replace`,
+ * a React Router `setSearchParams`, etc. all work identically from the
+ * consumer's side) instead of assuming `window.history` is the right target.
+ */
+declare function ListingApp<TEntity, TFilters>(props: ListingAppProps<TFilters>): react.JSX.Element | null;
+
+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 };