@garagem-ai/site-sdk 0.9.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -2735,11 +2735,13 @@ var STUDIO_SDK_CONTRACT = {
2735
2735
  * this and move that release's names from `optionalReactExports` /
2736
2736
  * `unpublishedSearchExports` / `unpublishedPhoneExports` into the
2737
2737
  * prompt-safe lists. Do not bump here until that tarball is on npm.
2738
- * Phone mask helpers shipped in 0.6.0. Search filter helpers
2738
+ * Phone mask helpers shipped in 0.6.0. Map search
2739
+ * (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
2740
+ * does not export them. Search filter helpers
2739
2741
  * (`visibleSearchFilters` / `toolbarFilterIds`) shipped in 0.4.12 and
2740
2742
  * remain on this pin.
2741
2743
  */
2742
- minNpmVersion: "0.6.0",
2744
+ minNpmVersion: "0.9.0",
2743
2745
  /** Historical: older tarballs inject card CSS when those components mount. */
2744
2746
  selfInjectSince: "0.4.2",
2745
2747
  chromeStrategy: "app-owned",
@@ -2752,7 +2754,8 @@ var STUDIO_SDK_CONTRACT = {
2752
2754
  * throws FatalRendererError.
2753
2755
  */
2754
2756
  optionalReactExports: {
2755
- usePublicPhotoSearch: "0.7.0"
2757
+ usePublicPhotoSearch: "0.7.0",
2758
+ useMapSearch: "0.9.0"
2756
2759
  },
2757
2760
  /**
2758
2761
  * Former `/react` chrome (including card/skeleton inject). Completeness
@@ -2863,14 +2866,15 @@ var STUDIO_SDK_CONTRACT = {
2863
2866
  ],
2864
2867
  /**
2865
2868
  * maps.fndn.ai helpers (static map, street view, boundaries, travel
2866
- * time) plus friendly map search. They ship in `mapsSince`;
2867
- * `studioMapsInstruction()` is empty and these names are codegen
2868
- * violations until `minNpmVersion` reaches that release — bump the pin
2869
- * after the tarball is on npm and the listing guidance turns on by
2870
- * itself. `useMapSearch` is a `/react` hook named in that same
2871
- * instruction; it stays off `reactExports` until the pin moves.
2869
+ * time) plus friendly map search. They ship in npm 0.9.0 (`mapsSince`).
2870
+ * Listing-detail map guidance stays empty: `studioMapsInstruction()`
2871
+ * keeps the listing contract for a later task and Studio does not
2872
+ * inject it. Map search is `studioMapSearchInstruction()`, and only
2873
+ * the site that opted into list-and-map may include that text.
2874
+ * `useMapSearch` is a `/react` hook in `optionalReactExports`; the
2875
+ * pin sentence does not name it.
2872
2876
  */
2873
- mapsSince: "0.7.0",
2877
+ mapsSince: "0.9.0",
2874
2878
  mapsExports: [
2875
2879
  "listingStaticMapUrl",
2876
2880
  "listingStreetViewUrl",
@@ -3006,7 +3010,7 @@ function studioPublishableKeyInstruction() {
3006
3010
  }
3007
3011
  function studioSdkPinInstruction() {
3008
3012
  const version = STUDIO_SDK_CONTRACT.minNpmVersion;
3009
- const names = [...reactExportsAvailableAt(version)].join(", ");
3013
+ const names = STUDIO_SDK_CONTRACT.reactExports.join(", ");
3010
3014
  return `In \`package.json\` set \`"@garagem-ai/site-sdk": "${version}"\` (exact). Import only these \`${STUDIO_SDK_PACKAGE}/react\` names: ${names}.`;
3011
3015
  }
3012
3016
  function studioLeadInstruction() {
@@ -3061,7 +3065,11 @@ function mapsExportsPublished(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3061
3065
  function studioMapsInstruction(options = {}) {
3062
3066
  if (!mapsExportsPublished(options.pin)) return "";
3063
3067
  const names = STUDIO_SDK_CONTRACT.mapsExports.join(", ");
3064
- return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (\u2248100 m by default) \u2014 pass the listing object as-is; never un-mask, never re-geocode the street address to get a sharper point, never add decimals (\`maxDecimals\` can only coarsen). Always pass \`siteId\` (the resolved site id / publishable key) so maps.fndn.ai meters the site. Static map: \`const mapSrc = listingStaticMapUrl(listing, { width: 640, height: 320, zoom: 15, style: "roadmap", siteId })\` then \`{mapSrc ? <img src={mapSrc} alt={model.location.label} /> : null}\` \u2014 \`null\` means no coordinates, so omit the block (never a placeholder image). Zoom is capped by the coordinate precision (16 on the default mask); do not work around it. Street View: on the server page \`const sv = await listingStreetViewAvailable(listing, { siteId })\` (metadata is free), and only when \`sv.available\` render \`<img src={listingStreetViewUrl(listing, { width: 640, height: 400, siteId })} alt="Street View" />\` \u2014 the image is billed per load. Neighbourhood outline on an interactive map: load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` (never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`); in \`initMap\` do \`const outline = await neighborhoodBoundaryLayer(listing.location.city, listing.location.neighborhood, { siteId })\` and \`if (outline.feature) map.data.addGeoJson(outline.feature)\`; with MapLibre the vector source url is \`boundaryLayerUrl(listing.location.city)\`. Travel time (\u201Cquanto tempo at\xE9\u2026\u201D): \`const trip = await travelTimeFromListing(listing, destination, { mode: "driving", siteId })\` gives \`{ minutes, distanceKm }\` or \`null\` (hide the row). Every uncached call is a billed Google Directions request: call it on demand \u2014 a destination the visitor typed, or at most one fixed landmark per listing page \u2014 never per listing card, never inside a search loop, keep the SDK cache on (default 15 min LRU, \`cache: null\` only in tests), and do not re-run it on every render. Map search (search page: search as the map moves, or draw an area): searchListingsInBounds(siteId, { bounds: { north, south, east, west }, zoom, q, sort, location, filters, page, pageSize, publishableKey }) and searchListingsInPolygon(siteId, { polygon: [[lat, lng], ...], q, sort, location, filters, page, pageSize, publishableKey }). Polygon points are [lat, lng], not GeoJSON. The server builds the allowlisted coordinates geo filter from those numbers; do not send a raw filter string from the browser. Pins are { id, lat, lng, price, coverImage } copied from the listings the API returned \u2014 masked pins, plot them as returned, never geocode the street to sharpen one. clusterPins(pins, zoom) is the headless grid: one pin keeps its coordinates, a group centroid is rounded back to the coarsest pin. The React hook useMapSearch (on the /react entry, next to usePublicSearch) debounces viewport changes by 400ms, cancels the stale request, caps pageSize at 100, and returns those pins plus cards from toListingCardModel. Pass the same q, sort, location, filters, and publishableKey as the list (queryListings / usePublicSearch). Dropping them pins listings outside the active query or spends the anonymous listings budget. Cost: every viewport change is a search call \u2014 keep the debounce, do not raise the page size, and do not call travel time or Street View inside that loop.`;
3068
+ return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (\u2248100 m by default) \u2014 pass the listing object as-is; never un-mask, never re-geocode the street address to get a sharper point, never add decimals (\`maxDecimals\` can only coarsen). Always pass \`siteId\` (the resolved site id / publishable key) so maps.fndn.ai meters the site. Static map: \`const mapSrc = listingStaticMapUrl(listing, { width: 640, height: 320, zoom: 15, style: "roadmap", siteId })\` then \`{mapSrc ? <img src={mapSrc} alt={model.location.label} /> : null}\` \u2014 \`null\` means no coordinates, so omit the block (never a placeholder image). Zoom is capped by the coordinate precision (16 on the default mask); do not work around it. Street View: on the server page \`const sv = await listingStreetViewAvailable(listing, { siteId })\` (metadata is free), and only when \`sv.available\` render \`<img src={listingStreetViewUrl(listing, { width: 640, height: 400, siteId })} alt="Street View" />\` \u2014 the image is billed per load. Neighbourhood outline on an interactive map: load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` (never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`); in \`initMap\` do \`const outline = await neighborhoodBoundaryLayer(listing.location.city, listing.location.neighborhood, { siteId })\` and \`if (outline.feature) map.data.addGeoJson(outline.feature)\`; with MapLibre the vector source url is \`boundaryLayerUrl(listing.location.city)\`. Travel time (\u201Cquanto tempo at\xE9\u2026\u201D): \`const trip = await travelTimeFromListing(listing, destination, { mode: "driving", siteId })\` gives \`{ minutes, distanceKm }\` or \`null\` (hide the row). Every uncached call is a billed Google Directions request: call it on demand \u2014 a destination the visitor typed, or at most one fixed landmark per listing page \u2014 never per listing card, never inside a search loop, keep the SDK cache on (default 15 min LRU, \`cache: null\` only in tests), and do not re-run it on every render.`;
3069
+ }
3070
+ function studioMapSearchInstruction(options = {}) {
3071
+ if (!mapsExportsPublished(options.pin)) return "";
3072
+ return `Map search on \`/imoveis\` (list and map of the same query). The list stays: keep \`usePublicSearch\` for the list, including its sort and pagination. The visitor switches on the same page. \`?modo=mapa\` is the map \u2014 read it on first paint. The list is the URL without \`modo\`; do not write \`modo=lista\` or \`modo=grade\`. Choosing the map sets \`modo=mapa\` and drops \`page\`. Choosing the list removes \`modo\`. On the map, hide sort and pagination. Do not add a map pager. The heading stays. Filters apply to both. Load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` \u2014 never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`, never \`maps.googleapis.com\`, never \`@vis.gl/react-google-maps\`. From \`${STUDIO_SDK_PACKAGE}/react\` import useMapSearch; it fetches, debounces, and clusters. \`const map = useMapSearch({ siteId, baseUrl: GARAGEM_API_BASE, bounds, zoom, q, sort, location, filters, publishableKey })\` with the same q, sort, location, filters, and publishableKey as the list. Pass the map's current zoom on every zoom change, including after a cluster click. Changing zoom recomputes \`map.clusters\` and does not refetch; a bounds change refetches. Do not send filter_by, vector_query, or nl_query from the browser. Request page 1 and pageSize at most 100. Do not walk totalPages. Pins are the masked coordinates the API returned \u2014 plot them as returned, never geocode the street. Render \`map.clusters\` with \`google.maps.Marker\` (no map id needed), in two styles that never look alike. A cluster (\`count > 1\`) is a filled circle in the brand color with a white border and the white count as its label. A listing (\`count === 1\` with \`cluster.pin\`) is a white rounded-rectangle chip with a brand-color border, labelled with the short price in the brand color ("R$ 850 mil", "R$ 1,2 mi"; "Consulte" when the price is null or 0): \`icon: { path: "M-34,-12 h68 a6,6 0 0 1 6,6 v12 a6,6 0 0 1 -6,6 h-68 a6,6 0 0 1 -6,-6 v-12 a6,6 0 0 1 6,-6 z", fillColor: "#ffffff", fillOpacity: 1, strokeColor: brand, strokeWeight: 1.5, scale: 1, labelOrigin: new google.maps.Point(0, 0) }\`. Never draw a listing as a dot or a circle, and never without its price. Clicking a listing selects it and shows its card. Clicking a cluster opens its members: \`const members = map.pins.filter((pin) => cluster.pinIds.includes(pin.id))\`, then \`fitBounds\` a LatLngBounds of their coordinates with about 64px padding, so the listings land inside the new view and split into chips. Do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. When every member has the same coordinates, or the map is already at zoom 18, do not zoom: open a small list of those listings, each with its price and a link. Layout, top to bottom: query, heading, toolbar, then the view. On desktop the toolbar is one row: featured filters on the left, and the list/map toggle immediately beside the sort select on the right. On a narrow screen the filters stay in one horizontal scroll that does not wrap, and the toggle plus the sort sit together on the row below that scroll. On the map the sort is hidden, so the toggle keeps that place beside where the sort was. In map mode the map fills the remaining viewport height, with a minimum of about 240px. Keep the hook's 400ms viewport debounce. A drawn polygon is not required. Do not add a separate /mapa route, a regions page, or a map on the listing page. Do not call Street View or travel time inside the map search.`;
3065
3073
  }
3066
3074
  function marketExportsAvailableAt(pin) {
3067
3075
  return compareSemver(pin, STUDIO_SDK_CONTRACT.marketExportsSince) >= 0;
@@ -3890,15 +3898,15 @@ function usablePin(pin) {
3890
3898
  return finitePair(pin.lat, pin.lng) !== null && !(pin.lat === 0 && pin.lng === 0);
3891
3899
  }
3892
3900
  function groupPrecision(group) {
3893
- let min = 12;
3901
+ let max = 0;
3894
3902
  for (const pin of group) {
3895
- min = Math.min(
3896
- min,
3903
+ max = Math.max(
3904
+ max,
3897
3905
  coordinateDecimals(pin.lat),
3898
3906
  coordinateDecimals(pin.lng)
3899
3907
  );
3900
3908
  }
3901
- return min;
3909
+ return max;
3902
3910
  }
3903
3911
  function multiCluster(key, group) {
3904
3912
  const lat = group.reduce((sum, pin) => sum + pin.lat, 0) / group.length;
@@ -4626,6 +4634,7 @@ export {
4626
4634
  studioLeadInstruction,
4627
4635
  studioListingCardInstruction,
4628
4636
  studioListingDetailInstruction,
4637
+ studioMapSearchInstruction,
4629
4638
  studioMapsInstruction,
4630
4639
  studioMarketInstruction,
4631
4640
  studioPhotoInstruction,