@garagem-ai/site-sdk 0.5.0 → 0.5.2

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/README.md CHANGED
@@ -283,10 +283,11 @@ inside the page `<main>`. Constrain width with `.max-w-site` and
283
283
  Theme cards via CSS variables (`SEARCH_CSS_VARS` / `SEARCH_CSS_RECIPE` in
284
284
  `globals.css`) and `data-slot`. Home and search should share
285
285
  `ListingCard`. Listing detail maps `listingDetailModel` leaves and
286
- `listingAmenityGroups`. The search H1 is SEO
287
- stable: hit count is a sibling `<span>`, not inside `<h1>`. Presentation
288
- tokens stay framework-free on the main entry so other adapters can reuse
289
- them.
286
+ `listingAmenityGroups`. The search H1 is SEO stable: count
287
+ `<span data-slot="search-heading-count">` first, then
288
+ `<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.
290
291
 
291
292
  Hand-written Next apps that prefer a layout tag can import
292
293
  `SearchChromeStyles` after it ships on npm; until then it is not part of
package/dist/index.d.mts CHANGED
@@ -348,9 +348,11 @@ declare const STUDIO_SDK_CONTRACT: {
348
348
  readonly package: "@garagem-ai/site-sdk";
349
349
  /**
350
350
  * Exact pin for generated Studio sites. Must match a tarball already on
351
- * npm — v0 installs this version. After the 0.4.13 changeset publishes,
352
- * bump this and move that release's names from `optionalReactExports`
353
- * into `reactExports`. Do not bump here until a headless tarball is on npm.
351
+ * npm — v0 installs this version. After a later changeset publishes, bump
352
+ * this and move that release's names from `optionalReactExports` /
353
+ * `unpublishedSearchExports` into the prompt-safe lists. Do not bump here
354
+ * until that tarball is on npm. Headless SearchPage already shipped in
355
+ * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
354
356
  */
355
357
  readonly minNpmVersion: "0.4.12";
356
358
  /** First release where ListingCard and ResultsSkeleton inject card CSS. */
@@ -379,11 +381,18 @@ declare const STUDIO_SDK_CONTRACT: {
379
381
  readonly leadExports: readonly ["getLeadUi", "submitVisitLead", "submitContactLead", "slotsForDate", "expandVisitSchedule", "expandVisitTimeSlots", "isVisitSlotAllowed", "STUDIO_DEFAULT_VISIT_SCHEDULE"];
380
382
  readonly listingDetailExports: readonly ["listingDetailModel", "getSimilarListings"];
381
383
  readonly amenityExports: readonly ["listingAmenityGroups"];
382
- /** Names on the pinned tarball — safe to put in Studio prompts. */
383
- readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "paginationPages", "hrefWithExplicitPage"];
384
384
  /**
385
- * Main-package helpers in git but not on `minNpmVersion`. Prompts must
386
- * not mention these until the pin bumps and they move into `searchExports`.
385
+ * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
386
+ * safe for Studio prompts and completeness. Includes
387
+ * `visibleSearchFilters` + `toolbarFilterIds` (shipped in 0.4.12). Do not
388
+ * confuse with `unpublishedSearchExports` (`searchChromeModel`, …).
389
+ */
390
+ readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "visibleSearchFilters", "toolbarFilterIds", "paginationPages", "hrefWithExplicitPage"];
391
+ /**
392
+ * Main-package helpers in git / newer tarballs but not required on
393
+ * `minNpmVersion`. Prompts must not mention these until the pin bumps and
394
+ * they move into `searchExports`. Independent of the 0.4.12 filter helpers
395
+ * already listed in `searchExports`.
387
396
  */
388
397
  readonly unpublishedSearchExports: readonly ["searchChromeModel", "rangeDraftFromPath"];
389
398
  };
package/dist/index.d.ts CHANGED
@@ -348,9 +348,11 @@ declare const STUDIO_SDK_CONTRACT: {
348
348
  readonly package: "@garagem-ai/site-sdk";
349
349
  /**
350
350
  * Exact pin for generated Studio sites. Must match a tarball already on
351
- * npm — v0 installs this version. After the 0.4.13 changeset publishes,
352
- * bump this and move that release's names from `optionalReactExports`
353
- * into `reactExports`. Do not bump here until a headless tarball is on npm.
351
+ * npm — v0 installs this version. After a later changeset publishes, bump
352
+ * this and move that release's names from `optionalReactExports` /
353
+ * `unpublishedSearchExports` into the prompt-safe lists. Do not bump here
354
+ * until that tarball is on npm. Headless SearchPage already shipped in
355
+ * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
354
356
  */
355
357
  readonly minNpmVersion: "0.4.12";
356
358
  /** First release where ListingCard and ResultsSkeleton inject card CSS. */
@@ -379,11 +381,18 @@ declare const STUDIO_SDK_CONTRACT: {
379
381
  readonly leadExports: readonly ["getLeadUi", "submitVisitLead", "submitContactLead", "slotsForDate", "expandVisitSchedule", "expandVisitTimeSlots", "isVisitSlotAllowed", "STUDIO_DEFAULT_VISIT_SCHEDULE"];
380
382
  readonly listingDetailExports: readonly ["listingDetailModel", "getSimilarListings"];
381
383
  readonly amenityExports: readonly ["listingAmenityGroups"];
382
- /** Names on the pinned tarball — safe to put in Studio prompts. */
383
- readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "paginationPages", "hrefWithExplicitPage"];
384
384
  /**
385
- * Main-package helpers in git but not on `minNpmVersion`. Prompts must
386
- * not mention these until the pin bumps and they move into `searchExports`.
385
+ * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
386
+ * safe for Studio prompts and completeness. Includes
387
+ * `visibleSearchFilters` + `toolbarFilterIds` (shipped in 0.4.12). Do not
388
+ * confuse with `unpublishedSearchExports` (`searchChromeModel`, …).
389
+ */
390
+ readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "visibleSearchFilters", "toolbarFilterIds", "paginationPages", "hrefWithExplicitPage"];
391
+ /**
392
+ * Main-package helpers in git / newer tarballs but not required on
393
+ * `minNpmVersion`. Prompts must not mention these until the pin bumps and
394
+ * they move into `searchExports`. Independent of the 0.4.12 filter helpers
395
+ * already listed in `searchExports`.
387
396
  */
388
397
  readonly unpublishedSearchExports: readonly ["searchChromeModel", "rangeDraftFromPath"];
389
398
  };
package/dist/index.js CHANGED
@@ -2369,9 +2369,11 @@ var STUDIO_SDK_CONTRACT = {
2369
2369
  package: STUDIO_SDK_PACKAGE,
2370
2370
  /**
2371
2371
  * Exact pin for generated Studio sites. Must match a tarball already on
2372
- * npm — v0 installs this version. After the 0.4.13 changeset publishes,
2373
- * bump this and move that release's names from `optionalReactExports`
2374
- * into `reactExports`. Do not bump here until a headless tarball is on npm.
2372
+ * npm — v0 installs this version. After a later changeset publishes, bump
2373
+ * this and move that release's names from `optionalReactExports` /
2374
+ * `unpublishedSearchExports` into the prompt-safe lists. Do not bump here
2375
+ * until that tarball is on npm. Headless SearchPage already shipped in
2376
+ * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
2375
2377
  */
2376
2378
  minNpmVersion: "0.4.12",
2377
2379
  /** First release where ListingCard and ResultsSkeleton inject card CSS. */
@@ -2416,16 +2418,25 @@ var STUDIO_SDK_CONTRACT = {
2416
2418
  ],
2417
2419
  listingDetailExports: ["listingDetailModel", "getSimilarListings"],
2418
2420
  amenityExports: ["listingAmenityGroups"],
2419
- /** Names on the pinned tarball — safe to put in Studio prompts. */
2421
+ /**
2422
+ * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
2423
+ * safe for Studio prompts and completeness. Includes
2424
+ * `visibleSearchFilters` + `toolbarFilterIds` (shipped in 0.4.12). Do not
2425
+ * confuse with `unpublishedSearchExports` (`searchChromeModel`, …).
2426
+ */
2420
2427
  searchExports: [
2421
2428
  "searchResultsHeading",
2422
2429
  "searchSortOptions",
2430
+ "visibleSearchFilters",
2431
+ "toolbarFilterIds",
2423
2432
  "paginationPages",
2424
2433
  "hrefWithExplicitPage"
2425
2434
  ],
2426
2435
  /**
2427
- * Main-package helpers in git but not on `minNpmVersion`. Prompts must
2428
- * not mention these until the pin bumps and they move into `searchExports`.
2436
+ * Main-package helpers in git / newer tarballs but not required on
2437
+ * `minNpmVersion`. Prompts must not mention these until the pin bumps and
2438
+ * they move into `searchExports`. Independent of the 0.4.12 filter helpers
2439
+ * already listed in `searchExports`.
2429
2440
  */
2430
2441
  unpublishedSearchExports: [
2431
2442
  "searchChromeModel",
@@ -2459,7 +2470,7 @@ ${studioSiteWidthCss()}
2459
2470
  Every page section is two layers: (1) surface \u2014 \`section\` / header / footer \`${STUDIO_SITE_LAYOUT.surfaceClassName}\`, background to the viewport edges, no max-width class and no horizontal padding; (2) wrapper \u2014 one child \`${STUDIO_SITE_LAYOUT.wrapperClassName}\`. Header and footer use that same inner wrapper. Components fill the wrapper (\`w-full\`). Never nest a second max-width container with extra horizontal padding. ${studioSearchLandmarkInstruction()} Do not use \`ml-auto\` on the content wrapper. To make the site narrower or wider, change ONLY \`--site-max-width\` in \`app/globals.css\` (allowed: ${scale}; default ${STUDIO_SITE_LAYOUT.maxWidthRem}). Do not edit wrapper class names or horizontal padding. Full-bleed image surfaces (home hero, listing gallery) stay flush with the header \u2014 do not add vertical padding there.`;
2460
2471
  }
2461
2472
  function studioSearchLandmarkInstruction() {
2462
- return `Search at \`/imoveis\` (hard rule). The page landmark is \`<main className="${STUDIO_SITE_LAYOUT.searchMainClassName}">\` with one child \`${STUDIO_SITE_LAYOUT.wrapperClassName}\`. Wire the catalog with \`usePublicSearch\` from \`${STUDIO_SDK_PACKAGE}/react\` inside \`<Suspense fallback={<ResultsSkeleton />}>\`. Do not wrap the search UI in \`<section>\` or a second max-width. The page owns the SEO heading: count in a sibling \`<span data-slot="search-heading-count">\`, title in \`<h1 data-slot="search-heading-title">\` \u2014 never put the count inside the H1. \`pt-4 pb-12\` is the default on that search \`<main>\` \u2014 change those values if the design needs it. Flush search (glued to the header) is allowed only with \`${STUDIO_SITE_LAYOUT.searchFlushMarker}\` on that \`<main>\`. Never add that vertical padding to home heroes or listing galleries.`;
2473
+ return `Search at \`/imoveis\` (hard rule). The page landmark is \`<main className="${STUDIO_SITE_LAYOUT.searchMainClassName}">\` with one child \`${STUDIO_SITE_LAYOUT.wrapperClassName}\`. Wire the catalog with \`usePublicSearch\` from \`${STUDIO_SDK_PACKAGE}/react\` inside \`<Suspense fallback={<ResultsSkeleton />}>\`. Do not wrap the search UI in \`<section>\` or a second max-width. The page owns the SEO heading as \`<div data-slot="search-heading">\`: count \`<span data-slot="search-heading-count">\` FIRST, then \`<h1 data-slot="search-heading-title">\` \u2014 never put the count inside the H1 and never put the h1 first. \`pt-4 pb-12\` is the default on that search \`<main>\` \u2014 change those values if the design needs it. Flush search (glued to the header) is allowed only with \`${STUDIO_SITE_LAYOUT.searchFlushMarker}\` on that \`<main>\`. Never add that vertical padding to home heroes or listing galleries.`;
2463
2474
  }
2464
2475
  var REACT_SDK_NAMED_IMPORT_RE = /(?:^|[\n;])\s*import\s+(?!type\b)(?:type\s+)?\{([^}]+)\}\s+from\s+['"]@garagem-ai\/site-sdk\/react['"]/g;
2465
2476
  var SHOWCASE_LEADS_POST_URL_RE = /\/api\/sites\/[^\s"']*\/leads(?!\/ui)/;
@@ -2534,7 +2545,7 @@ function studioAmenityInstruction() {
2534
2545
  function studioSearchInstruction() {
2535
2546
  const reactNames = STUDIO_SDK_CONTRACT.reactExports.join(", ");
2536
2547
  const libNames = STUDIO_SDK_CONTRACT.searchExports.join(", ");
2537
- return `Search: import ${reactNames} from \`${STUDIO_SDK_PACKAGE}/react\`. From \`${STUDIO_SDK_PACKAGE}\` import ${libNames}. Call \`usePublicSearch({ siteId, baseUrl: GARAGEM_API_BASE })\` in a client component inside \`<Suspense>\` (\`useSearchParams\`). Compose the page UI in the app \u2014 do not paste a canonical search TSX. Title from \`searchResultsHeading\`; sort \`.id\` / \`.label\` from \`searchSortOptions\`. Never interpolate \`schema\`, \`pathFilters\`, or a filter object as a React child. \`queryListings\` key is \`params\`. The URL is the document. Empty copy: ${JSON.stringify(SEARCH_EMPTY_COPY)}`;
2548
+ return `Search: import ${reactNames} from \`${STUDIO_SDK_PACKAGE}/react\`. From \`${STUDIO_SDK_PACKAGE}\` import ${libNames}. Call \`const search = usePublicSearch({ siteId, baseUrl: GARAGEM_API_BASE })\` in a client component inside \`<Suspense>\` (\`useSearchParams\`). Compose the page UI in the app \u2014 do not paste a canonical search TSX. Required chrome (design is free; omit none): query (\`qDraft\` / \`setQDraft\` / form \`preventDefault\` + \`submitQuery\`), heading (count span FIRST then h1 from \`searchResultsHeading(search.pathFilters, search.schema?.dictionary, search.locationNames)\` \u2014 never \`searchResultsHeading({})\`), toolbar (\`toolbarFilterIds\` + \`applyFilter\`; range \u201CAtualizar\u201D on that toolbar item only) vs sheet (\`visibleSearchFilters\` extras, \`stageFilter\`, one footer \`applyStaged\`), sort (\`searchSortOptions\` + \`setSort\`; first option id is \`""\` \u2014 map to Select sentinel \`"relevancia"\`, never \`SelectItem value=""\`; on change \`setSort(id === "relevancia" ? "" : id)\`), grid (\`listings.map\` + \`ListingCard\`; \`ResultsSkeleton\` is only the Suspense fallback; do not \`throw\` in that chrome), pagination (\`paginationPages\` + \`hrefWithExplicitPage\`). Never interpolate \`schema\`, \`pathFilters\`, or a filter object as a React child. \`queryListings\` key is \`params\`. The URL is the document. Empty copy: ${JSON.stringify(SEARCH_EMPTY_COPY)}`;
2538
2549
  }
2539
2550
  function studioChromeInstruction() {
2540
2551
  return `ListingCard and ResultsSkeleton inject card/skeleton CSS (JS \`<style>\` tag). Never \`import "${STUDIO_SDK_CONTRACT.forbiddenImports[0]}"\` \u2014 v0 preview cannot load npm CSS. Do not copy SDK card layout into the app. Theme cards via CSS variables in \`app/globals.css\` (\`SEARCH_CSS_RECIPE\` / \`--garagem-*\`). Search chrome (query, toolbar, sort, filters, pagination) is app-owned \u2014 theme with the site tokens, not an SDK stylesheet.`;