@garagem-ai/site-sdk 0.5.2 → 0.6.0

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.
Files changed (42) hide show
  1. package/README.md +16 -25
  2. package/dist/index.d.mts +296 -28
  3. package/dist/index.d.ts +296 -28
  4. package/dist/index.js +469 -53
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +458 -51
  7. package/dist/index.mjs.map +1 -1
  8. package/dist/react.d.mts +18 -60
  9. package/dist/react.d.ts +18 -60
  10. package/dist/react.js +265 -874
  11. package/dist/react.js.map +1 -1
  12. package/dist/react.mjs +246 -841
  13. package/dist/react.mjs.map +1 -1
  14. package/dist/{search-engine-4ocM0UPk.d.mts → search-engine-CtnLzmwW.d.mts} +13 -181
  15. package/dist/{search-engine-4ocM0UPk.d.ts → search-engine-CtnLzmwW.d.ts} +13 -181
  16. package/package.json +11 -13
  17. package/src/amenity-labels.ts +9 -2
  18. package/src/fetchers.ts +2 -1
  19. package/src/index.ts +20 -2
  20. package/src/internal/url.ts +1 -0
  21. package/src/leads.ts +45 -6
  22. package/src/listing-card-model.ts +4 -1
  23. package/src/listing-detail.ts +8 -2
  24. package/src/phone-countries.ts +97 -0
  25. package/src/phone.ts +431 -0
  26. package/src/presentation.ts +1 -24
  27. package/src/react/index.ts +1 -11
  28. package/src/react/public-search-snapshot.ts +165 -0
  29. package/src/react/staged-filters-mirror.ts +38 -0
  30. package/src/react/types.ts +17 -30
  31. package/src/react/use-public-search.ts +121 -42
  32. package/src/search-engine.ts +3 -0
  33. package/src/studio-contract.ts +63 -21
  34. package/src/types.ts +12 -0
  35. package/src/react/cn.ts +0 -3
  36. package/src/react/listing-card.tsx +0 -98
  37. package/src/react/listing-detail-fields.tsx +0 -119
  38. package/src/react/search-chrome.tsx +0 -29
  39. package/src/react/search.css +0 -214
  40. package/src/react/styles/index.ts +0 -1
  41. package/src/react/styles/search-chrome-css.generated.ts +0 -5
  42. package/src/react/styles/search-chrome-styles.tsx +0 -31
package/README.md CHANGED
@@ -70,7 +70,7 @@ raw escape hatch when you need full control.
70
70
  | `submitContactLead({ siteId, listingId, … })` | POST a contact lead (no date/time) |
71
71
  | `slotsForDate` / `normalizeVisitDate` / `expandVisitSchedule` | Pure schedule helpers (`America/Sao_Paulo`, default Mon–Fri 06:00–22:00) |
72
72
  | `listingDetailModel(listing)` | Listing-detail blocks: breadcrumb, location + Maps href, `description` string + toggle label, video/tour overlays. Studio pages map `facts` / `values` via `.label` / `.text` leaves. |
73
- | `listingDetailFieldsModel(listing, dictionary?)` | Facts, values, and amenity groups that are safe to render: every row has a real label + text; missing condo/IPTU/empty groups are omitted. Used by `ListingDetailFields` (0.4.13+). |
73
+ | `listingDetailFieldsModel(listing, dictionary?)` | Facts, values, and amenity groups that are safe to render: every row has a real label + text; missing condo/IPTU/empty groups are omitted. |
74
74
  | `listingAmenityGroups(listing, dictionary?)` | Unit / building amenity labels (`Comodidades`, `Comodidades do condomínio`). Reads `propertyFeatures` + `buildingAmenities` (works when `building` is null). Tenant `getSearchUi().dictionary` first, then the SDK fallback. Studio pages call this helper directly. |
75
75
  | `resolvePublicSiteId({ host?, fallback? })` | Preview uses `fallback` (`GARAGEM_SITE_ID`); live hosts resolve via `getSite({ domain })` |
76
76
 
@@ -89,7 +89,9 @@ raw escape hatch when you need full control.
89
89
 
90
90
  All fetchers accept:
91
91
 
92
- - `baseUrl` — defaults to `https://app.garagem.ai`. Override for a custom proxy or staging.
92
+ - `baseUrl` — data fetchers default to `https://app.garagem.ai`; `getSite`
93
+ defaults to `https://cdn.fndn.ai/site` so production resolution traverses the
94
+ tenant-locator edge. Override for a custom proxy or staging.
93
95
  - `fetch` — custom fetch implementation (testing, retries, edge runtimes).
94
96
  - `next: { revalidate, tags }` — forwarded directly to the underlying `fetch` for Next.js App Router caching. Ignored on runtimes that don't understand it.
95
97
 
@@ -252,19 +254,14 @@ option on `createGaragemClient`.
252
254
  ## Search UI (`@garagem-ai/site-sdk/react`)
253
255
 
254
256
  Headless URL/search helpers live on the main entry (`readPublicSearch`,
255
- `searchChromeModel`, `hrefForPathFilters`, `toListingCardModel`, …). The
256
- React adapter is a separate subpath — peer `react` + `next`.
257
+ `hrefForPathFilters`, `toListingCardModel`, …). The React adapter is a
258
+ separate subpath — peer `react` + `next` — and exports `usePublicSearch`
259
+ only. Card, skeleton, and search chrome markup belong in the app.
257
260
 
258
261
  Studio codegen follows `STUDIO_SDK_CONTRACT`: pin
259
262
  `@garagem-ai/site-sdk` to `minNpmVersion` and import only
260
- `reactExports` (`usePublicSearch`, `ListingCard`, `ResultsSkeleton` on
261
- the Studio pin). Preview, open-in-new-tab, and published `next build`
262
- all resolve that tarball. Do **not** import npm CSS
263
- (`@garagem-ai/site-sdk/react/search.css`) in Studio.
264
-
265
- `ListingCard` and `ResultsSkeleton` inject card/skeleton CSS (JS
266
- `<style>` tag). Search chrome (query, toolbar, sort, filters,
267
- pagination, heading) is composed in the app with `usePublicSearch`.
263
+ `reactExports` (`usePublicSearch`). Do **not** import npm CSS
264
+ (`@garagem-ai/site-sdk/react/search.css`).
268
265
 
269
266
  ```tsx
270
267
  "use client";
@@ -276,22 +273,16 @@ export function ImoveisSearch({ siteId }: { siteId: string }) {
276
273
  }
277
274
  ```
278
275
 
279
- Wrap that client component in `<Suspense fallback={<ResultsSkeleton />}>`
280
- inside the page `<main>`. Constrain width with `.max-w-site` and
276
+ Wrap that client component in `<Suspense>` whose fallback is the app’s
277
+ listing-card skeleton. Constrain width with `.max-w-site` and
281
278
  `--site-max-width` (`STUDIO_SITE_LAYOUT` — Editor default `80rem` / `px-4`).
282
279
 
283
- Theme cards via CSS variables (`SEARCH_CSS_VARS` / `SEARCH_CSS_RECIPE` in
284
- `globals.css`) and `data-slot`. Home and search should share
285
- `ListingCard`. Listing detail maps `listingDetailModel` leaves and
286
- `listingAmenityGroups`. The search H1 is SEO stable: count
287
- `<span data-slot="search-heading-count">` first, then
280
+ Home, search, and similar listings share one site-owned card fed by
281
+ `toListingCardModel` / `listingPublicPath`. Listing detail maps
282
+ `listingDetailModel` leaves and `listingAmenityGroups`. The search H1 is
283
+ SEO stable: count `<span data-slot="search-heading-count">` first, then
288
284
  `<h1 data-slot="search-heading-title">`. Hit count is never inside
289
- `<h1>`. Presentation tokens stay framework-free on the main entry so
290
- other adapters can reuse them.
291
-
292
- Hand-written Next apps that prefer a layout tag can import
293
- `SearchChromeStyles` after it ships on npm; until then it is not part of
294
- the Studio pin.
285
+ `<h1>`.
295
286
 
296
287
  ## What's NOT in this release
297
288
 
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
- import { R as RequestNextOptions, L as ListingFilters, Q as QueryListingsParams, S as SearchListingsParams, C as CmsCollection, a as CmsEntriesResult, b as CmsEntry, c as ListingDetail, d as ListingsResult, e as SearchUi, f as SimilarListingsResult, g as Site, h as QueryListingsResult, i as SearchListingsResult, j as SearchPathFilters, k as SearchUiDictionary, l as QueryListingsFilters, A as AppliedSearchQuery, m as AppliedSearchChange } from './search-engine-4ocM0UPk.mjs';
2
- export { n as AMENITY_FALLBACK_LABELS, o as AmenityLabelDictionary, p as AmenityLabelOption, q as CmsEntryStatus, r as CmsFieldDefinition, s as CmsFieldType, t as CmsSeoData, F as FORBIDDEN_SEARCH_QUERY_KEYS, u as LISTING_AMENITY_TITLES, v as LISTING_DESCRIPTION_CLAMP, w as Listing, x as ListingAmenityGroup, y as ListingAmenityGroupKey, z as ListingAmenitySource, B as ListingBreadcrumbCrumb, D as ListingBusinessType, E as ListingCardModel, G as ListingDescriptionPreview, H as ListingDetailFieldsModel, I as ListingDetailFieldsSource, J as ListingDetailModel, K as ListingFact, M as ListingLocation, N as ListingLocationBlock, O as ListingMedia, P as ListingMediaOverlay, T as ListingPriceVisibility, U as ListingPropertySummary, V as ListingValue, W as LocationNameTables, X as QueryListingsLocation, Y as SEARCH_EMPTY_COPY, Z as SEARCH_SORT_RELEVANCE, _ as SearchChromeModel, $ as SearchPathLocation, a0 as SearchUiFilter, a1 as SearchUiOption, a2 as TOOLBAR_PRIMARY_FILTER_IDS, a3 as applyPathFilter, a4 as buildQueryListingsParams, a5 as canonicalizeSearchHref, a6 as clearStagedPathFilters, a7 as countFacetChoices, a8 as countOptionLabel, a9 as displayPathLocation, aa as hrefForAppliedChange, ab as hrefForPathFilters, ac as hrefWithExplicitPage, ad as isListingDetailPath, ae as labelAmenities, af as listingAmenityGroups, ag as listingBreadcrumb, ah as listingDescriptionPreview, ai as listingDetailFieldsModel, aj as listingDetailModel, ak as listingFacts, al as listingLocationBlock, am as listingLocationLabel, an as listingMapsHref, ao as listingMediaOverlays, ap as listingValues, aq as paginationPages, ar as pathFilterHasOption, as as pathFilterValue, at as publicSearchHref, au as rangeDraftFromPath, av as readPublicSearch, aw as searchChromeModel, ax as searchHrefUsesLegacyFilterQuery, ay as searchResultsHeading, az as searchSortOptions, aA as toListingCardModel, aB as toolbarFilterIds, aC as visibleSearchFilters } from './search-engine-4ocM0UPk.mjs';
1
+ import { R as RequestNextOptions, L as ListingFilters, Q as QueryListingsParams, S as SearchListingsParams, C as CmsCollection, a as CmsEntriesResult, b as CmsEntry, c as ListingDetail, d as ListingsResult, e as SearchUi, f as SimilarListingsResult, g as Site, h as QueryListingsResult, i as SearchListingsResult, j as ListingLocation, k as ListingMedia, l as ListingBusinessType, m as ListingPriceVisibility, n as Listing, o as SearchPathFilters, p as SearchUiDictionary, q as QueryListingsFilters, A as AppliedSearchQuery, r as AppliedSearchChange } from './search-engine-CtnLzmwW.mjs';
2
+ export { s as CmsEntryStatus, t as CmsFieldDefinition, u as CmsFieldType, v as CmsSeoData, F as FORBIDDEN_SEARCH_QUERY_KEYS, w as ListingPropertySummary, x as LocationNameTables, y as QueryListingsLocation, z as SEARCH_EMPTY_COPY, B as SEARCH_SORT_RELEVANCE, D as SearchChromeModel, E as SearchPathLocation, G as SearchUiFilter, H as SearchUiOption, T as TOOLBAR_PRIMARY_FILTER_IDS, I as applyPathFilter, J as buildQueryListingsParams, K as canonicalizeSearchHref, M as clearStagedPathFilters, N as countFacetChoices, O as countOptionLabel, P as displayPathLocation, U as hrefForAppliedChange, V as hrefForPathFilters, W as hrefWithExplicitPage, X as isListingDetailPath, Y as paginationPages, Z as pathFilterHasOption, _ as pathFilterValue, $ as publicSearchHref, a0 as rangeDraftFromPath, a1 as readPublicSearch, a2 as searchChromeModel, a3 as searchHrefUsesLegacyFilterQuery, a4 as searchResultsHeading, a5 as searchSortOptions, a6 as toolbarFilterIds, a7 as visibleSearchFilters } from './search-engine-CtnLzmwW.mjs';
3
3
 
4
4
  /** Custom fetch implementation. Defaults to the global `fetch`. */
5
5
  type FetchLike = typeof fetch;
@@ -226,6 +226,13 @@ type LeadSubmitBase = LeadContact & {
226
226
  baseUrl?: string;
227
227
  fetch?: FetchLike;
228
228
  listingId: string;
229
+ /**
230
+ * Active listing modality (`sale` | `rental` | `rent`). Always pass
231
+ * `listing.businessType`, sale included; the server only fills a missing
232
+ * value from the catalog as a safety net.
233
+ */
234
+ listingType?: string;
235
+ businessType?: string;
229
236
  visitorId?: string;
230
237
  brokerRef?: string;
231
238
  referrer?: string;
@@ -258,6 +265,52 @@ declare function getLeadUi(options: GetLeadUiOptions): Promise<LeadUi>;
258
265
  declare function submitVisitLead(input: VisitLeadInput): Promise<LeadSubmitResult>;
259
266
  declare function submitContactLead(input: ContactLeadInput): Promise<LeadSubmitResult>;
260
267
 
268
+ /**
269
+ * Portuguese labels for listing amenity ids. Tenant search-ui dictionary
270
+ * wins; this map is the default-catalog fallback so generated Studio pages
271
+ * never print camelCase keys.
272
+ */
273
+ declare const LISTING_AMENITY_TITLES: {
274
+ readonly unit: "Comodidades";
275
+ readonly building: "Comodidades do condomínio";
276
+ };
277
+ type AmenityLabelOption = {
278
+ id: string;
279
+ label: string;
280
+ };
281
+ type AmenityLabelDictionary = {
282
+ propertyFeatures?: AmenityLabelOption[];
283
+ buildingAmenities?: AmenityLabelOption[];
284
+ amenitySectionTitles?: {
285
+ unit?: string;
286
+ building?: string;
287
+ };
288
+ };
289
+ type ListingAmenityGroupKey = keyof typeof LISTING_AMENITY_TITLES;
290
+ type ListingAmenityGroup = {
291
+ key: ListingAmenityGroupKey;
292
+ title: string;
293
+ labels: string[];
294
+ };
295
+ type ListingAmenitySource = {
296
+ amenities?: string[] | null;
297
+ propertyFeatures?: string[] | null;
298
+ /** Condo amenity ids, even when `building` is null (no buildingId). */
299
+ buildingAmenities?: string[] | null;
300
+ building?: {
301
+ amenities?: string[] | null;
302
+ } | null;
303
+ };
304
+ /**
305
+ * Default tenant ids + canonical `has*` / `is*` keys seen on public listings.
306
+ * Aligned with DEFAULT_PROPERTY_FEATURES and DEFAULT_BUILDING_FEATURES from
307
+ * Foundation's field-definitions.ts so generated Studio pages never need a
308
+ * dictionary for standard amenities.
309
+ */
310
+ declare const AMENITY_FALLBACK_LABELS: Record<string, string>;
311
+ declare function labelAmenities(ids: readonly string[] | null | undefined, dictionary?: AmenityLabelOption[]): string[];
312
+ declare function listingAmenityGroups(listing: ListingAmenitySource, dictionary?: AmenityLabelDictionary): ListingAmenityGroup[];
313
+
261
314
  /** Public listing URLs. Prefer `listing.path` from the API; fallback is `/imoveis/id-{listingCode}`. */
262
315
  declare function listingLookupKey(raw: string): string;
263
316
  declare function listingPublicPath(listing: {
@@ -266,22 +319,150 @@ declare function listingPublicPath(listing: {
266
319
  id?: string | null;
267
320
  }): string;
268
321
 
322
+ declare const LISTING_DESCRIPTION_CLAMP = 280;
323
+ /** Visible listing fact. The number / area / floor is `text` — never omit it. */
324
+ type ListingFact = {
325
+ key: string;
326
+ label: string;
327
+ text: string;
328
+ };
329
+ /** Visible listing amount. Price, condomínio and IPTU are `text`. */
330
+ type ListingValue = {
331
+ key: string;
332
+ label: string;
333
+ text: string;
334
+ };
335
+ type ListingBreadcrumbCrumb = {
336
+ label: string;
337
+ href: string;
338
+ };
339
+ type ListingLocationBlock = {
340
+ label: string;
341
+ mapsHref: string | null;
342
+ };
343
+ type ListingDescriptionPreview = {
344
+ text: string;
345
+ truncated: boolean;
346
+ toggleLabel: string | null;
347
+ };
348
+ type ListingMediaOverlay = {
349
+ key: "video" | "tour";
350
+ hash: "video" | "tour";
351
+ title: string;
352
+ href: string;
353
+ embedSrc: string;
354
+ };
355
+ type ListingDetailModel = {
356
+ breadcrumb: ListingBreadcrumbCrumb[];
357
+ values: ListingValue[];
358
+ facts: ListingFact[];
359
+ location: ListingLocationBlock | null;
360
+ /** Complete description string — never a sliced preview. */
361
+ description: string | null;
362
+ descriptionTruncated: boolean;
363
+ descriptionToggleLabel: string | null;
364
+ mediaOverlays: ListingMediaOverlay[];
365
+ };
366
+ declare function listingValues(listing: {
367
+ price?: number | null;
368
+ currency?: string | null;
369
+ priceVisibility?: string | null;
370
+ propertyTaxLabel?: string | null;
371
+ property?: {
372
+ condoFee?: number | null;
373
+ propertyTax?: number | null;
374
+ } | null;
375
+ }): ListingValue[];
376
+ declare function listingFacts(listing: {
377
+ property?: {
378
+ totalArea?: number | null;
379
+ usableArea?: number | null;
380
+ bedrooms?: number | null;
381
+ suites?: number | null;
382
+ parkingSpaces?: number | null;
383
+ rooms?: number | null;
384
+ floor?: number | string | null;
385
+ } | null;
386
+ }): ListingFact[];
387
+ declare function listingMapsHref(location: ListingLocation | null | undefined): string | null;
388
+ declare function listingLocationBlock(listing: {
389
+ location?: ListingLocation | null;
390
+ } | null | undefined): ListingLocationBlock | null;
391
+ declare function listingBreadcrumb(listing: {
392
+ path?: string | null;
393
+ listingCode?: string | null;
394
+ id?: string | null;
395
+ }): ListingBreadcrumbCrumb[];
396
+ declare function listingDescriptionPreview(description: string | null | undefined, expanded?: boolean): ListingDescriptionPreview | null;
397
+ declare function listingMediaOverlays(listing: {
398
+ media?: ListingMedia[] | null;
399
+ }): ListingMediaOverlay[];
400
+ declare function listingDetailModel(listing: Pick<ListingDetail, "id" | "listingCode" | "path" | "price" | "priceVisibility" | "description"> & {
401
+ property?: ListingDetail["property"] | null;
402
+ location?: ListingLocation | null;
403
+ media?: ListingMedia[] | null;
404
+ }, options?: {
405
+ descriptionExpanded?: boolean;
406
+ }): ListingDetailModel;
407
+
408
+ type ListingDetailFieldsModel = {
409
+ facts: ListingFact[];
410
+ values: ListingValue[];
411
+ amenityGroups: ListingAmenityGroup[];
412
+ };
413
+ type ListingDetailFieldsSource = ListingAmenitySource & Pick<ListingDetail, "price" | "priceVisibility"> & {
414
+ property?: ListingDetail["property"] | null;
415
+ };
269
416
  /**
270
- * Presentation helpers with no UI framework.
271
- * React / React Native / Flutter adapters consume these formatters and
272
- * CSS custom-property names; they must not live inside JSX.
417
+ * Facts, values, and amenity groups that are safe to render: every row has
418
+ * a real label and text. Missing condo/IPTU/empty facts never appear.
273
419
  */
274
- declare const SEARCH_CSS_VARS: {
275
- readonly cardRadius: "--garagem-listing-card-radius";
276
- readonly cardGap: "--garagem-listing-card-gap";
277
- readonly priceSize: "--garagem-listing-price-size";
278
- readonly mediaRatio: "--garagem-listing-media-ratio";
279
- readonly controlHeight: "--garagem-search-control-height";
280
- readonly iconSize: "--garagem-search-icon-size";
281
- readonly skeleton: "--garagem-skeleton";
420
+ declare function listingDetailFieldsModel(listing: ListingDetailFieldsSource, dictionary?: AmenityLabelDictionary): ListingDetailFieldsModel;
421
+
422
+ /** Fields every listing card must have — no JSX. */
423
+ type ListingCardModel = {
424
+ href: string;
425
+ title: string;
426
+ businessType: ListingBusinessType;
427
+ businessLabel: string;
428
+ priceVisibility: ListingPriceVisibility;
429
+ price: number | null;
430
+ priceLabel: string;
431
+ pricePeriod: string | null;
432
+ locationLabel: string;
433
+ propertyType: string | null;
434
+ coverSrc: string | null;
435
+ coverAlt: string;
436
+ bedrooms: number | null;
437
+ bathrooms: number | null;
438
+ parkingSpaces: number | null;
439
+ areaM2: number | null;
282
440
  };
283
- /** Paste into generated `globals.css` to override tokens. Layout lives in the chrome artifact. */
284
- declare const SEARCH_CSS_RECIPE: string;
441
+ declare function listingLocationLabel(location: {
442
+ neighborhood?: string | null;
443
+ city?: string | null;
444
+ state?: string | null;
445
+ }): string;
446
+ declare function toListingCardModel(listing: Pick<Listing, "id" | "listingCode" | "path" | "title" | "businessType" | "price" | "currency" | "priceVisibility" | "coverImage"> & {
447
+ property?: {
448
+ type?: string | null;
449
+ bedrooms?: number | null;
450
+ bathrooms?: number | null;
451
+ parkingSpaces?: number | null;
452
+ usableArea?: number | null;
453
+ totalArea?: number | null;
454
+ };
455
+ location?: {
456
+ neighborhood?: string | null;
457
+ city?: string | null;
458
+ state?: string | null;
459
+ };
460
+ }): ListingCardModel;
461
+
462
+ /**
463
+ * Presentation helpers with no UI framework.
464
+ * Adapters consume these formatters; they must not live inside JSX.
465
+ */
285
466
  declare function formatListingPrice(amount: number | null | undefined, locale?: string, currency?: string): string;
286
467
  /** Input mask: `499000` → `"499.000"` (no currency symbol). */
287
468
  declare function formatGroupedInteger(value: string | number | null | undefined, locale?: string): string;
@@ -290,6 +471,79 @@ declare function parseGroupedInteger(value: unknown): number | undefined;
290
471
  declare function formatAreaM2(area: number | null | undefined): string | null;
291
472
  declare function listingBusinessLabel(businessType: string | undefined): string;
292
473
 
474
+ /**
475
+ * Countries for Studio phone pickers (labels pt-BR).
476
+ * Same catalog shape as `@garagem/ui` PhoneInput — generated sites compose
477
+ * the UI; this list is headless data only.
478
+ */
479
+ interface PhoneCountry {
480
+ code: string;
481
+ name: string;
482
+ dialCode: string;
483
+ flag: string;
484
+ }
485
+ declare const DEFAULT_PHONE_COUNTRY_CODE = "BR";
486
+ declare const PHONE_COUNTRIES: PhoneCountry[];
487
+ /** cmdk / filter value: name, ISO, DDI, and +DDI so "59" / "+598" both match. */
488
+ declare function phoneCountrySearchValue(country: PhoneCountry): string;
489
+ declare function findPhoneCountry(code: string | null | undefined): PhoneCountry | undefined;
490
+ declare function defaultPhoneCountry(): PhoneCountry;
491
+
492
+ /**
493
+ * Headless phone mask / E.164 helpers for Studio-generated lead forms.
494
+ * UI (country picker, input) stays in the app — same contract as CRM
495
+ * `@garagem/ui` PhoneInput without shipping markup.
496
+ */
497
+
498
+ /** ITU-T E.164 national number upper bound. */
499
+ declare const MAX_NATIONAL_PHONE_DIGITS = 15;
500
+ declare function nationalPhoneDigits(value: string | null | undefined): string;
501
+ declare function truncateNationalPhoneDigits(digits: string, max?: number): string;
502
+ /**
503
+ * Collapse DDD + extra `9` + 9-digit BR mobile (12 national digits).
504
+ * Matches CRM `collapseDuplicatedBrazilianMobileNine` for common typos.
505
+ */
506
+ declare function collapseDuplicatedBrazilianMobileNine(digits: string): string;
507
+ /**
508
+ * National display mask for the selected country (`(11) 96690-6900` for BR).
509
+ * Pass national digits or a messy draft; non-digits are stripped.
510
+ */
511
+ declare function formatPhoneNational(value: string | null | undefined, countryCode?: string): string;
512
+ type ParsedPhoneInput = {
513
+ ddi: string | null;
514
+ national: string;
515
+ countryCode: string | null;
516
+ };
517
+ /**
518
+ * Split E.164 / `+DDI…` paste vs national draft. Without `+`, `ddi` is null
519
+ * and `national` is all digits (country comes from the picker).
520
+ */
521
+ declare function parsePhoneInput(input: string | null | undefined): ParsedPhoneInput;
522
+ /**
523
+ * Canonical submit value: `+5511966906900`. Empty draft → `""`.
524
+ * Callers that need a guaranteed-valid number should also run `isValidPhone`.
525
+ */
526
+ declare function toE164(value: string | null | undefined, countryCode?: string): string;
527
+ /**
528
+ * Validate national digits or E.164 for the selected country (CRM-aligned).
529
+ */
530
+ declare function isValidPhone(value: string | null | undefined, countryCode?: string): boolean;
531
+ /**
532
+ * Re-mask national digits after the visitor changes country (PhoneInput flow).
533
+ *
534
+ * Lossless on purpose, like CRM PhoneInput `handleCountryChange`: the digits
535
+ * already in the field are kept as-is (truncated to E.164 length), only the
536
+ * mask and the dial code change. The accidental dial-prefix strip and the
537
+ * Brazilian extra-9 collapse are for freshly typed/pasted input — running
538
+ * them here against the destination country eats legitimate digits (NANP
539
+ * dial `1` would take the first digit of a BR `11…` national on a toggle).
540
+ */
541
+ declare function remaskPhoneForCountry(nationalOrDraft: string | null | undefined, countryCode: string): {
542
+ display: string;
543
+ e164: string;
544
+ country: PhoneCountry;
545
+ };
546
+
293
547
  declare function composeSearchPublicPath(filters: SearchPathFilters, dictionary?: SearchUiDictionary): string;
294
548
  declare function parseSearchPublicPath(pathname: string, dictionary?: SearchUiDictionary): SearchPathFilters | null;
295
549
  /**
@@ -355,31 +609,44 @@ declare const STUDIO_SDK_CONTRACT: {
355
609
  * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
356
610
  */
357
611
  readonly minNpmVersion: "0.4.12";
358
- /** First release where ListingCard and ResultsSkeleton inject card CSS. */
612
+ /** Historical: older tarballs inject card CSS when those components mount. */
359
613
  readonly selfInjectSince: "0.4.2";
360
- readonly chromeStrategy: "self-inject";
361
- readonly reactExports: readonly ["usePublicSearch", "ListingCard", "ResultsSkeleton"];
614
+ readonly chromeStrategy: "app-owned";
615
+ readonly reactExports: readonly ["usePublicSearch"];
362
616
  /**
363
- * Names that exist in git / the unpublished patch. Completeness treats an
617
+ * Names that exist in git / unpublished patches. Completeness treats an
364
618
  * import as `sdk-export-mismatch` when the generated pin is older than
365
619
  * `since`. Studio prompts must not mention these names at all (even as
366
620
  * “never import”) — v0 copies the identifier and the preview ESM loader
367
621
  * throws FatalRendererError.
368
622
  */
369
- readonly optionalReactExports: {
370
- readonly SearchChromeStyles: "0.4.1";
371
- readonly ListingDetailFields: "0.4.13";
372
- };
623
+ readonly optionalReactExports: Record<string, string>;
373
624
  /**
374
- * Former `/react` chrome. Completeness flags imports as mismatch (not in
375
- * `reactExports`). Prompts must not mention these names at all — v0 copies
376
- * identifiers even inside “never import”.
625
+ * Former `/react` chrome (including card/skeleton inject). Completeness
626
+ * flags imports as mismatch (not in `reactExports`). Prompts must not
627
+ * mention these names at all — v0 copies identifiers even inside
628
+ * “never import”.
377
629
  */
378
- readonly retiredReactExports: readonly ["SearchPage", "SearchQueryForm", "SearchSortSelect", "FilterPanel", "SearchPagination", "SearchPageFallback"];
630
+ readonly retiredReactExports: readonly ["SearchPage", "SearchQueryForm", "SearchSortSelect", "FilterPanel", "SearchPagination", "SearchPageFallback", "ListingCard", "ResultsSkeleton", "SearchChromeStyles", "ListingDetailFields"];
379
631
  readonly forbiddenImports: readonly ["@garagem-ai/site-sdk/react/search.css"];
380
632
  readonly leadStrategy: "visit-default";
381
633
  readonly leadExports: readonly ["getLeadUi", "submitVisitLead", "submitContactLead", "slotsForDate", "expandVisitSchedule", "expandVisitTimeSlots", "isVisitSlotAllowed", "STUDIO_DEFAULT_VISIT_SCHEDULE"];
382
634
  readonly listingDetailExports: readonly ["listingDetailModel", "getSimilarListings"];
635
+ /** Main-package card helpers — markup stays in the generated app. */
636
+ readonly listingCardExports: readonly ["toListingCardModel", "listingPublicPath", "formatAreaM2", "listingBusinessLabel", "formatListingPrice"];
637
+ /**
638
+ * Prompt-safe phone helpers on `minNpmVersion`. Empty until a published
639
+ * tarball exports them and this pin bumps — then move names here from
640
+ * `unpublishedPhoneExports`.
641
+ */
642
+ readonly phoneExports: readonly [];
643
+ /**
644
+ * Headless phone mask helpers in git / newer tarballs but not on
645
+ * `minNpmVersion` (0.4.12). Prompts, completeness, and repair text must
646
+ * not mention these until the pin bumps — v0 installs the pin and the
647
+ * ESM loader throws on missing named exports.
648
+ */
649
+ readonly unpublishedPhoneExports: readonly ["PHONE_COUNTRIES", "formatPhoneNational", "toE164", "isValidPhone", "parsePhoneInput", "phoneCountrySearchValue", "findPhoneCountry", "remaskPhoneForCountry"];
383
650
  readonly amenityExports: readonly ["listingAmenityGroups"];
384
651
  /**
385
652
  * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
@@ -423,6 +690,7 @@ declare function parseReactSdkNamedImports(source: string): string[];
423
690
  declare function unavailableReactImports(source: string, pin: string): string[];
424
691
  declare function studioSdkPinInstruction(): string;
425
692
  declare function studioLeadInstruction(): string;
693
+ declare function studioListingCardInstruction(): string;
426
694
  declare function studioListingDetailInstruction(): string;
427
695
  declare function studioAmenityInstruction(): string;
428
696
  declare function studioSearchInstruction(): string;
@@ -541,4 +809,4 @@ interface GaragemClient {
541
809
  */
542
810
  declare function createGaragemClient(options?: CreateGaragemClientOptions): GaragemClient;
543
811
 
544
- export { AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetLeadUiOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, type HHmm, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, ListingDetail, ListingFilters, ListingsResult, type LocationFilterInput, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, SEARCH_CSS_RECIPE, SEARCH_CSS_VARS, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, coerceNpmVersion, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, expandVisitSchedule, expandVisitTimeSlots, formatAreaM2, formatGroupedInteger, formatListingPrice, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getLeadUi, getListing, getListings, getSearchUi, getSimilarListings, getSite, hasShowcaseLeadsPostUrl, isStudioPreviewHost, isVisitSlotAllowed, listingBusinessLabel, listingLookupKey, listingPublicPath, mergeAppliedSearchQueryIntoSearch, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, queryListings, reduceAppliedSearchQuery, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingDetailInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, unavailableReactImports };
812
+ export { AMENITY_FALLBACK_LABELS, type AmenityLabelDictionary, type AmenityLabelOption, AppliedSearchChange, AppliedSearchQuery, CmsCollection, CmsEntriesResult, CmsEntry, type ContactLeadInput, type CreateGaragemClientOptions, DEFAULT_PHONE_COUNTRY_CODE, type FetchLike, type GaragemClient, GaragemSdkError, type GetCmsCollectionOptions, type GetCmsCollectionsOptions, type GetCmsEntriesOptions, type GetCmsEntryOptions, type GetLeadUiOptions, type GetListingOptions, type GetListingsOptions, type GetSearchUiOptions, type GetSimilarListingsOptions, type GetSiteOptions, type HHmm, LISTING_AMENITY_TITLES, LISTING_DESCRIPTION_CLAMP, type LeadContact, type LeadField, type LeadFieldId, LeadSubmitError, type LeadSubmitErrorCode, type LeadSubmitResult, type LeadUi, Listing, type ListingAmenityGroup, type ListingAmenityGroupKey, type ListingAmenitySource, type ListingBreadcrumbCrumb, ListingBusinessType, type ListingCardModel, type ListingDescriptionPreview, ListingDetail, type ListingDetailFieldsModel, type ListingDetailFieldsSource, type ListingDetailModel, type ListingFact, ListingFilters, ListingLocation, type ListingLocationBlock, ListingMedia, type ListingMediaOverlay, ListingPriceVisibility, type ListingValue, ListingsResult, type LocationFilterInput, MAX_NATIONAL_PHONE_DIGITS, PHONE_COUNTRIES, type ParsedPhoneInput, type PhoneCountry, QueryListingsFilters, type QueryListingsOptions, QueryListingsParams, QueryListingsResult, RequestNextOptions, type ResolvePublicSiteIdOptions, STUDIO_DEFAULT_VISIT_SCHEDULE, STUDIO_SDK_CONTRACT, STUDIO_SDK_PACKAGE, STUDIO_SITE_LAYOUT, type SearchListingsOptions, SearchListingsParams, SearchListingsResult, SearchPathFilters, SearchUi, SearchUiDictionary, SimilarListingsResult, Site, type StudioSdkContract, VISIT_TIME_ZONE, type VisitHours, type VisitLeadInput, type VisitSchedule, type VisitScheduleConfig, coerceNpmVersion, collapseDuplicatedBrazilianMobileNine, compareSemver, composeSearchPublicHref, composeSearchPublicPath, createGaragemClient, defaultPhoneCountry, expandVisitSchedule, expandVisitTimeSlots, findPhoneCountry, formatAreaM2, formatGroupedInteger, formatListingPrice, formatPhoneNational, getCmsCollection, getCmsCollections, getCmsEntries, getCmsEntry, getLeadUi, getListing, getListings, getSearchUi, getSimilarListings, getSite, hasShowcaseLeadsPostUrl, isStudioPreviewHost, isValidPhone, isVisitSlotAllowed, labelAmenities, listingAmenityGroups, listingBreadcrumb, listingBusinessLabel, listingDescriptionPreview, listingDetailFieldsModel, listingDetailModel, listingFacts, listingLocationBlock, listingLocationLabel, listingLookupKey, listingMapsHref, listingMediaOverlays, listingPublicPath, listingValues, mergeAppliedSearchQueryIntoSearch, nationalPhoneDigits, normalizeVisitDate, normalizeVisitTime, parseAppliedSearchQuery, parseGroupedInteger, parsePhoneInput, parseReactSdkNamedImports, parseSearchPublicPath, pathFiltersToQueryFilters, pathLocationToFilterInput, phoneCountrySearchValue, queryListings, reduceAppliedSearchQuery, remaskPhoneForCountry, resolvePublicSiteId, searchListings, serializeAppliedSearchQuery, slotsForDate, studioAmenityInstruction, studioChromeInstruction, studioCodegenContractViolations, studioDefaultLeadUi, studioLayoutInstruction, studioLeadInstruction, studioListingCardInstruction, studioListingDetailInstruction, studioSdkPinInstruction, studioSearchInstruction, studioSearchLandmarkInstruction, studioSiteWidthCss, submitContactLead, submitVisitLead, toE164, toListingCardModel, truncateNationalPhoneDigits, unavailableReactImports };