react-listing-engine 0.1.0

package/dist/testing/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); var _class;"use client";
+var o= (_class =class{constructor() { _class.prototype.__init.call(this);_class.prototype.__init2.call(this);_class.prototype.__init3.call(this);_class.prototype.__init4.call(this);_class.prototype.__init5.call(this);_class.prototype.__init6.call(this);_class.prototype.__init7.call(this); }__init() {this.mounts=[]}__init2() {this.renderedLayers=[]}__init3() {this.removedLayers=[]}__init4() {this.fitBoundsCalls=[]}__init5() {this.destroyed=[]}__init6() {this.destroyCount=0}__init7() {this.boundsListeners=new Set}mount(t,e){let n={raw:{el:t,opts:e}};return this.mounts.push(n),n}renderLayer(t,e){this.renderedLayers.push(e);let n=!1;return()=>{if(n)return;n=!0;let s=this.renderedLayers.indexOf(e);s!==-1&&(this.renderedLayers.splice(s,1),this.removedLayers.push(e))}}onBoundsChange(t,e){return this.boundsListeners.add(e),()=>{this.boundsListeners.delete(e)}}emitBounds(t){for(let e of this.boundsListeners)e(t)}fitBounds(t,e){this.fitBoundsCalls.push(e)}destroy(t){this.destroyed.push(t),this.destroyCount+=1,this.boundsListeners.clear()}}, _class);var d=class{constructor(t,e,n,s=r=>r.id){this.rows=t;this.predicate=e;this.toLatLng=n;this.idOf=s}async list(t,e){let n=this.rows.filter(u=>this.predicate(u,t)),s=e.cursor==null?0:Number(e.cursor)+1,r=n.slice(s,s+e.limit),i=s+r.length-1,l=i+1<n.length;return{items:r,nextCursor:l?String(i):null,total:n.length}}async getPoints(t,e){let s=this.rows.filter(r=>this.predicate(r,t)).map(r=>({id:this.idOf(r),position:this.toLatLng(r),entity:r}));return e?s.filter(r=>this.isInBounds(r.position,e)):s}async getById(t){let e=this.rows.find(n=>this.idOf(n)===t);if(!e)throw new Error(`InMemoryEntityAdapter: no row with id "${String(t)}"`);return e}isInBounds(t,e){return t.lat<=e.north&&t.lat>=e.south&&t.lng>=e.west&&t.lng<=e.east}};exports.FakeMapProvider = o; exports.InMemoryEntityAdapter = d;

package/dist/testing/index.d.cts

@@ -0,0 +1,51 @@
+import { B as Bounds, a as EntityAdapter, L as LatLng, E as EntityId, b as PageRequest, P as Page, M as MapPoint } from '../entity-adapter.interface-BDgbSxhq.cjs';
+import { M as MapProvider, a as MapHandle, R as RenderedLayer, b as MapInitOptions, U as Unsubscribe } from '../map-provider.interface-BMnwW3ob.cjs';
+
+type BoundsListener = (b: Bounds) => void;
+/**
+ * Headless in-memory `MapProvider` test double. Records everything it is
+ * asked to do (mounts, rendered layers, fitBounds calls, destroys) into
+ * public arrays/counters, and exposes `emitBounds()` so a test can simulate
+ * a user pan/zoom without a real map SDK or browser.
+ */
+declare class FakeMapProvider implements MapProvider {
+    readonly mounts: MapHandle[];
+    readonly renderedLayers: RenderedLayer[];
+    readonly removedLayers: RenderedLayer[];
+    readonly fitBoundsCalls: Bounds[];
+    readonly destroyed: MapHandle[];
+    destroyCount: number;
+    private readonly boundsListeners;
+    mount(el: HTMLElement, opts: MapInitOptions): MapHandle;
+    renderLayer(_handle: MapHandle, layer: RenderedLayer): Unsubscribe;
+    onBoundsChange(_handle: MapHandle, cb: BoundsListener): Unsubscribe;
+    /** Test-only: simulates a user pan/zoom by invoking every registered bounds listener. */
+    emitBounds(b: Bounds): void;
+    fitBounds(_handle: MapHandle, b: Bounds): void;
+    destroy(handle: MapHandle): void;
+}
+
+/**
+ * In-memory `EntityAdapter` test double. `list()` filters `rows` through
+ * `predicate` and paginates by array index: `cursor` is the (stringified)
+ * index of the last row already served (`null` means start from the
+ * beginning), and the returned `nextCursor` is that same kind of value for
+ * the next call — `null` once nothing is left. `getPoints()` runs the same
+ * predicate filter and projects each surviving row through `toLatLng`
+ * (further narrowed to `bounds` when one is given). `idOf` defaults to
+ * reading `row.id`, mirroring most real adapters, but can be overridden for
+ * rows keyed by something else.
+ */
+declare class InMemoryEntityAdapter<TEntity, TFilters> implements EntityAdapter<TEntity, TFilters> {
+    private readonly rows;
+    private readonly predicate;
+    private readonly toLatLng;
+    private readonly idOf;
+    constructor(rows: TEntity[], predicate: (row: TEntity, filters: TFilters) => boolean, toLatLng: (row: TEntity) => LatLng, idOf?: (row: TEntity) => EntityId);
+    list(filters: TFilters, page: PageRequest): Promise<Page<TEntity>>;
+    getPoints(filters: TFilters, bounds?: Bounds): Promise<MapPoint<TEntity>[]>;
+    getById(id: EntityId): Promise<TEntity>;
+    private isInBounds;
+}
+
+export { FakeMapProvider, InMemoryEntityAdapter };

package/dist/testing/index.d.ts

@@ -0,0 +1,51 @@
+import { B as Bounds, a as EntityAdapter, L as LatLng, E as EntityId, b as PageRequest, P as Page, M as MapPoint } from '../entity-adapter.interface-BDgbSxhq.js';
+import { M as MapProvider, a as MapHandle, R as RenderedLayer, b as MapInitOptions, U as Unsubscribe } from '../map-provider.interface-BxexMT3X.js';
+
+type BoundsListener = (b: Bounds) => void;
+/**
+ * Headless in-memory `MapProvider` test double. Records everything it is
+ * asked to do (mounts, rendered layers, fitBounds calls, destroys) into
+ * public arrays/counters, and exposes `emitBounds()` so a test can simulate
+ * a user pan/zoom without a real map SDK or browser.
+ */
+declare class FakeMapProvider implements MapProvider {
+    readonly mounts: MapHandle[];
+    readonly renderedLayers: RenderedLayer[];
+    readonly removedLayers: RenderedLayer[];
+    readonly fitBoundsCalls: Bounds[];
+    readonly destroyed: MapHandle[];
+    destroyCount: number;
+    private readonly boundsListeners;
+    mount(el: HTMLElement, opts: MapInitOptions): MapHandle;
+    renderLayer(_handle: MapHandle, layer: RenderedLayer): Unsubscribe;
+    onBoundsChange(_handle: MapHandle, cb: BoundsListener): Unsubscribe;
+    /** Test-only: simulates a user pan/zoom by invoking every registered bounds listener. */
+    emitBounds(b: Bounds): void;
+    fitBounds(_handle: MapHandle, b: Bounds): void;
+    destroy(handle: MapHandle): void;
+}
+
+/**
+ * In-memory `EntityAdapter` test double. `list()` filters `rows` through
+ * `predicate` and paginates by array index: `cursor` is the (stringified)
+ * index of the last row already served (`null` means start from the
+ * beginning), and the returned `nextCursor` is that same kind of value for
+ * the next call — `null` once nothing is left. `getPoints()` runs the same
+ * predicate filter and projects each surviving row through `toLatLng`
+ * (further narrowed to `bounds` when one is given). `idOf` defaults to
+ * reading `row.id`, mirroring most real adapters, but can be overridden for
+ * rows keyed by something else.
+ */
+declare class InMemoryEntityAdapter<TEntity, TFilters> implements EntityAdapter<TEntity, TFilters> {
+    private readonly rows;
+    private readonly predicate;
+    private readonly toLatLng;
+    private readonly idOf;
+    constructor(rows: TEntity[], predicate: (row: TEntity, filters: TFilters) => boolean, toLatLng: (row: TEntity) => LatLng, idOf?: (row: TEntity) => EntityId);
+    list(filters: TFilters, page: PageRequest): Promise<Page<TEntity>>;
+    getPoints(filters: TFilters, bounds?: Bounds): Promise<MapPoint<TEntity>[]>;
+    getById(id: EntityId): Promise<TEntity>;
+    private isInBounds;
+}
+
+export { FakeMapProvider, InMemoryEntityAdapter };

package/dist/testing/index.js

@@ -0,0 +1,2 @@
+"use client";
+var o=class{mounts=[];renderedLayers=[];removedLayers=[];fitBoundsCalls=[];destroyed=[];destroyCount=0;boundsListeners=new Set;mount(t,e){let n={raw:{el:t,opts:e}};return this.mounts.push(n),n}renderLayer(t,e){this.renderedLayers.push(e);let n=!1;return()=>{if(n)return;n=!0;let s=this.renderedLayers.indexOf(e);s!==-1&&(this.renderedLayers.splice(s,1),this.removedLayers.push(e))}}onBoundsChange(t,e){return this.boundsListeners.add(e),()=>{this.boundsListeners.delete(e)}}emitBounds(t){for(let e of this.boundsListeners)e(t)}fitBounds(t,e){this.fitBoundsCalls.push(e)}destroy(t){this.destroyed.push(t),this.destroyCount+=1,this.boundsListeners.clear()}};var d=class{constructor(t,e,n,s=r=>r.id){this.rows=t;this.predicate=e;this.toLatLng=n;this.idOf=s}rows;predicate;toLatLng;idOf;async list(t,e){let n=this.rows.filter(u=>this.predicate(u,t)),s=e.cursor==null?0:Number(e.cursor)+1,r=n.slice(s,s+e.limit),i=s+r.length-1,l=i+1<n.length;return{items:r,nextCursor:l?String(i):null,total:n.length}}async getPoints(t,e){let s=this.rows.filter(r=>this.predicate(r,t)).map(r=>({id:this.idOf(r),position:this.toLatLng(r),entity:r}));return e?s.filter(r=>this.isInBounds(r.position,e)):s}async getById(t){let e=this.rows.find(n=>this.idOf(n)===t);if(!e)throw new Error(`InMemoryEntityAdapter: no row with id "${String(t)}"`);return e}isInBounds(t,e){return t.lat<=e.north&&t.lat>=e.south&&t.lng>=e.west&&t.lng<=e.east}};export{o as FakeMapProvider,d as InMemoryEntityAdapter};

package/dist/url-sync.controller-CsU_QxoS.d.cts

@@ -0,0 +1,89 @@
+import { Q as QueryParams } from './entity-adapter.interface-BDgbSxhq.cjs';
+
+/**
+ * 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;
+}
+
+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 (e.g. via `/shadcn`'s `ListingApp.urlSync`, or 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;
+}
+
+export { type HistoryPort as H, UrlSyncController as U, type UrlSyncEngine as a, type UrlSyncOptions as b };

package/dist/url-sync.controller-DX67JivW.d.ts

@@ -0,0 +1,89 @@
+import { Q as QueryParams } from './entity-adapter.interface-BDgbSxhq.js';
+
+/**
+ * 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;
+}
+
+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 (e.g. via `/shadcn`'s `ListingApp.urlSync`, or 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;
+}
+
+export { type HistoryPort as H, UrlSyncController as U, type UrlSyncEngine as a, type UrlSyncOptions as b };

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "react-listing-engine",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Headless, composable listing engine for React: filterable list + Google-Maps multi-layer map, with pluggable data adapters, a filter/dataset registry, injectable components, and a shadcn-compatible styled adapter.",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/knazark"
+    },
+    {
+      "type": "individual",
+      "url": "https://send.monobank.ua/jar/2jfphHthfY"
+    }
+  ],
+  "keywords": [
+    "react",
+    "listing",
+    "map",
+    "google-maps",
+    "filters",
+    "real-estate",
+    "directory",
+    "store-locator",
+    "headless",
+    "typescript",
+    "nextjs",
+    "react18",
+    "react19",
+    "shadcn"
+  ],
+  "author": "knazark",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knazark/react-listing-engine.git"
+  },
+  "homepage": "https://github.com/knazark/react-listing-engine#readme",
+  "bugs": {
+    "url": "https://github.com/knazark/react-listing-engine/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./shadcn": {
+      "types": "./dist/shadcn/index.d.ts",
+      "import": "./dist/shadcn/index.js",
+      "require": "./dist/shadcn/index.cjs"
+    },
+    "./styled": {
+      "types": "./dist/styled/index.d.ts",
+      "import": "./dist/styled/index.js",
+      "require": "./dist/styled/index.cjs"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./maps/google": {
+      "types": "./dist/maps/google/index.d.ts",
+      "import": "./dist/maps/google/index.js",
+      "require": "./dist/maps/google/index.cjs"
+    },
+    "./presets/rental": {
+      "types": "./dist/presets/rental/index.d.ts",
+      "import": "./dist/presets/rental/index.js",
+      "require": "./dist/presets/rental/index.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "require": "./dist/testing/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@googlemaps/js-api-loader": ">=1",
+    "@googlemaps/markerclusterer": ">=2",
+    "@radix-ui/react-slot": ">=1",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@googlemaps/js-api-loader": {
+      "optional": true
+    },
+    "@googlemaps/markerclusterer": {
+      "optional": true
+    },
+    "@radix-ui/react-slot": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@googlemaps/js-api-loader": "^2.1.1",
+    "@googlemaps/markerclusterer": "^2.6.2",
+    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/google.maps": "^3.65.3",
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^10.8.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "happy-dom": "^20.11.1",
+    "lucide-react": "^1.26.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "release": "changeset publish"
+  }
+}