@garagem-ai/site-sdk 0.4.14 → 0.5.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.
@@ -8,26 +8,25 @@
8
8
  * while chromeStrategy is self-inject (v0 copies identifiers; a layout tag
9
9
  * also breaks the pancake stack).
10
10
  */
11
+ import { SEARCH_EMPTY_COPY } from "./search-engine";
12
+
11
13
  export const STUDIO_SDK_PACKAGE = "@garagem-ai/site-sdk" as const;
12
14
 
13
15
  export const STUDIO_SDK_CONTRACT = {
14
16
  package: STUDIO_SDK_PACKAGE,
15
17
  /**
16
18
  * Exact pin for generated Studio sites. Must match a tarball already on
17
- * npm — v0 installs this version. After the 0.4.13 changeset publishes,
18
- * bump this and move that release's names from `optionalReactExports`
19
- * into `reactExports`.
19
+ * npm — v0 installs this version. After a later changeset publishes, bump
20
+ * this and move that release's names from `optionalReactExports` /
21
+ * `unpublishedSearchExports` into the prompt-safe lists. Do not bump here
22
+ * until that tarball is on npm. Headless SearchPage already shipped in
23
+ * 0.4.12 (`visibleSearchFilters` / `toolbarFilterIds` are on that pin).
20
24
  */
21
25
  minNpmVersion: "0.4.12",
22
- /** First release where ListingCard and ResultsSkeleton inject the sheet. */
26
+ /** First release where ListingCard and ResultsSkeleton inject card CSS. */
23
27
  selfInjectSince: "0.4.2",
24
28
  chromeStrategy: "self-inject" as const,
25
- reactExports: [
26
- "SearchPage",
27
- "ListingCard",
28
- "usePublicSearch",
29
- "ResultsSkeleton",
30
- ] as const,
29
+ reactExports: ["usePublicSearch", "ListingCard", "ResultsSkeleton"] as const,
31
30
  /**
32
31
  * Names that exist in git / the unpublished patch. Completeness treats an
33
32
  * import as `sdk-export-mismatch` when the generated pin is older than
@@ -36,10 +35,22 @@ export const STUDIO_SDK_CONTRACT = {
36
35
  * throws FatalRendererError.
37
36
  */
38
37
  optionalReactExports: {
39
- SearchPageFallback: "0.4.1",
40
38
  SearchChromeStyles: "0.4.1",
41
39
  ListingDetailFields: "0.4.13",
42
40
  } as const,
41
+ /**
42
+ * Former `/react` chrome. Completeness flags imports as mismatch (not in
43
+ * `reactExports`). Prompts must not mention these names at all — v0 copies
44
+ * identifiers even inside “never import”.
45
+ */
46
+ retiredReactExports: [
47
+ "SearchPage",
48
+ "SearchQueryForm",
49
+ "SearchSortSelect",
50
+ "FilterPanel",
51
+ "SearchPagination",
52
+ "SearchPageFallback",
53
+ ] as const,
43
54
  forbiddenImports: ["@garagem-ai/site-sdk/react/search.css"] as const,
44
55
  leadStrategy: "visit-default" as const,
45
56
  leadExports: [
@@ -54,6 +65,30 @@ export const STUDIO_SDK_CONTRACT = {
54
65
  ] as const,
55
66
  listingDetailExports: ["listingDetailModel", "getSimilarListings"] as const,
56
67
  amenityExports: ["listingAmenityGroups"] as const,
68
+ /**
69
+ * Names already on the pinned npm tarball (`minNpmVersion` / 0.4.12) —
70
+ * safe for Studio prompts and completeness. Includes
71
+ * `visibleSearchFilters` + `toolbarFilterIds` (shipped in 0.4.12). Do not
72
+ * confuse with `unpublishedSearchExports` (`searchChromeModel`, …).
73
+ */
74
+ searchExports: [
75
+ "searchResultsHeading",
76
+ "searchSortOptions",
77
+ "visibleSearchFilters",
78
+ "toolbarFilterIds",
79
+ "paginationPages",
80
+ "hrefWithExplicitPage",
81
+ ] as const,
82
+ /**
83
+ * Main-package helpers in git / newer tarballs but not required on
84
+ * `minNpmVersion`. Prompts must not mention these until the pin bumps and
85
+ * they move into `searchExports`. Independent of the 0.4.12 filter helpers
86
+ * already listed in `searchExports`.
87
+ */
88
+ unpublishedSearchExports: [
89
+ "searchChromeModel",
90
+ "rangeDraftFromPath",
91
+ ] as const,
57
92
  } as const;
58
93
 
59
94
  export type StudioSdkContract = typeof STUDIO_SDK_CONTRACT;
@@ -94,7 +129,7 @@ Every page section is two layers: (1) surface — \`section\` / header / footer
94
129
  }
95
130
 
96
131
  export function studioSearchLandmarkInstruction(): string {
97
- return `Search at \`/imoveis\` (hard rule). The page landmark is \`<main className="${STUDIO_SITE_LAYOUT.searchMainClassName}">\` with one child \`${STUDIO_SITE_LAYOUT.wrapperClassName}\`. Pass \`as="div"\` to \`SearchPage\` so it is not a second main. Mount as one line: \`<SearchPage as="div" siteId={() => resolveSiteId(window.location.host)} baseUrl={GARAGEM_API_BASE} variant="toolbar" />\`. Do not wrap \`SearchPage\` in \`<section>\` or add another \`<h1>\`. SearchPage owns the SEO heading: count in \`data-slot="search-heading-count"\` (sibling \`<span>\`), title in \`<h1 data-slot="search-heading-title">\` — never put the count inside the H1. Do not put vertical padding on SearchPage. \`pt-4 pb-12\` is the default on that search \`<main>\` — 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.`;
132
+ 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">\` — never put the count inside the H1 and never put the h1 first. \`pt-4 pb-12\` is the default on that search \`<main>\` — 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.`;
98
133
  }
99
134
 
100
135
  const REACT_SDK_NAMED_IMPORT_RE =
@@ -182,15 +217,18 @@ export function studioAmenityInstruction(): string {
182
217
  return `Listing amenities: Portuguese labels from \`listingAmenityGroups(listing)\` (optional dictionary from \`getSearchUi()\`). Each group is \`{ title, labels: string[] }\` — render \`group.labels.map((label) => …)\` and hide a group when \`group.labels.length === 0\`. Titles: \`Comodidades\` / \`Comodidades do condomínio\`. Never print amenity ids, never invent a local label map, and never title a section "Comodidades da unidade".`;
183
218
  }
184
219
 
220
+ export function studioSearchInstruction(): string {
221
+ const reactNames = STUDIO_SDK_CONTRACT.reactExports.join(", ");
222
+ const libNames = STUDIO_SDK_CONTRACT.searchExports.join(", ");
223
+ 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 — 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)\` — never \`searchResultsHeading({})\`), toolbar (\`toolbarFilterIds\` + \`applyFilter\`; range “Atualizar” on that toolbar item only) vs sheet (\`visibleSearchFilters\` extras, \`stageFilter\`, one footer \`applyStaged\`), sort (\`searchSortOptions\` + \`setSort\`), grid (\`listings.map\` + \`ListingCard\`; \`ResultsSkeleton\` is only the Suspense fallback), 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)}`;
224
+ }
225
+
185
226
  export function studioChromeInstruction(): string {
186
- const injectors =
187
- compareSemver(
188
- STUDIO_SDK_CONTRACT.minNpmVersion,
189
- STUDIO_SDK_CONTRACT.selfInjectSince
190
- ) >= 0
191
- ? "`SearchPage`, `ListingCard`, and `ResultsSkeleton`"
192
- : "`SearchPage`";
193
- return `Search chrome CSS is injected by ${injectors} (JS \`<style>\` tag). Never \`import "@garagem-ai/site-sdk/react/search.css"\` — v0 preview cannot load npm CSS. Do not copy SDK card/toolbar layout into the app. Theme via CSS variables in \`app/globals.css\` (\`SEARCH_CSS_RECIPE\` / \`--garagem-*\`), \`classNames\`, and \`data-slot\`.`;
227
+ return `ListingCard and ResultsSkeleton inject card/skeleton CSS (JS \`<style>\` tag). Never \`import "${STUDIO_SDK_CONTRACT.forbiddenImports[0]}"\` — 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 — theme with the site tokens, not an SDK stylesheet.`;
228
+ }
229
+
230
+ function mentionsExportName(text: string, name: string): boolean {
231
+ return new RegExp(`\\b${name}\\b`).test(text);
194
232
  }
195
233
 
196
234
  /**
@@ -200,7 +238,17 @@ export function studioChromeInstruction(): string {
200
238
  export function studioCodegenContractViolations(text: string): string[] {
201
239
  const violations: string[] = [];
202
240
  for (const name of Object.keys(STUDIO_SDK_CONTRACT.optionalReactExports)) {
203
- if (text.includes(name)) violations.push(name);
241
+ if (mentionsExportName(text, name)) violations.push(name);
242
+ }
243
+ for (const name of STUDIO_SDK_CONTRACT.retiredReactExports) {
244
+ if (mentionsExportName(text, name) && !violations.includes(name)) {
245
+ violations.push(name);
246
+ }
247
+ }
248
+ for (const name of STUDIO_SDK_CONTRACT.unpublishedSearchExports) {
249
+ if (mentionsExportName(text, name) && !violations.includes(name)) {
250
+ violations.push(name);
251
+ }
204
252
  }
205
253
  const pin = STUDIO_SDK_CONTRACT.minNpmVersion;
206
254
  const available = reactExportsAvailableAt(pin);
@@ -1,248 +0,0 @@
1
- "use client";
2
-
3
- import type { ReactElement } from "react";
4
-
5
- import { formatGroupedInteger } from "../presentation";
6
- import {
7
- countFacetChoices,
8
- pathFilterHasOption,
9
- pathFilterValue,
10
- } from "../search-engine";
11
- import type { SearchPathFilters, SearchUiFilter } from "../types";
12
-
13
- export type RangeCommitSource = "blur" | "enter" | "apply";
14
-
15
- export type FilterPanelProps = {
16
- filters: SearchUiFilter[];
17
- pathFilters: SearchPathFilters;
18
- onChange: (filterId: string, value: unknown) => void;
19
- rangeDraft: Record<string, { min: string; max: string }>;
20
- onRangePatch: (filterId: string, side: "min" | "max", value: string) => void;
21
- onRangeCommit: (filterId: string, source?: RangeCommitSource) => void;
22
- };
23
-
24
- function RangeFields({
25
- filter,
26
- rangeDraft,
27
- onRangePatch,
28
- onRangeCommit,
29
- }: {
30
- filter: SearchUiFilter;
31
- rangeDraft: FilterPanelProps["rangeDraft"];
32
- onRangePatch: FilterPanelProps["onRangePatch"];
33
- onRangeCommit: FilterPanelProps["onRangeCommit"];
34
- }): ReactElement {
35
- const draft = rangeDraft[filter.id] || { min: "", max: "" };
36
- const isPrice = filter.id === "price";
37
- const patch = (side: "min" | "max", raw: string) => {
38
- onRangePatch(filter.id, side, isPrice ? formatGroupedInteger(raw) : raw);
39
- };
40
- return (
41
- <fieldset data-slot="search-filter">
42
- <legend>{filter.label}</legend>
43
- <div data-slot="search-range-row">
44
- <RangeSide
45
- id={`${filter.id}-min`}
46
- label="Mín"
47
- isPrice={isPrice}
48
- value={draft.min}
49
- onPatch={(raw) => patch("min", raw)}
50
- onCommit={() => onRangeCommit(filter.id, "blur")}
51
- onEnter={() => onRangeCommit(filter.id, "enter")}
52
- />
53
- <RangeSide
54
- id={`${filter.id}-max`}
55
- label="Máx"
56
- isPrice={isPrice}
57
- value={draft.max}
58
- onPatch={(raw) => patch("max", raw)}
59
- onCommit={() => onRangeCommit(filter.id, "blur")}
60
- onEnter={() => onRangeCommit(filter.id, "enter")}
61
- />
62
- <button
63
- type="button"
64
- data-slot="search-range-apply"
65
- onClick={() => onRangeCommit(filter.id, "apply")}
66
- >
67
- Atualizar
68
- </button>
69
- </div>
70
- </fieldset>
71
- );
72
- }
73
-
74
- function RangeSide({
75
- id,
76
- label,
77
- isPrice,
78
- value,
79
- onPatch,
80
- onCommit,
81
- onEnter,
82
- }: {
83
- id: string;
84
- label: string;
85
- isPrice: boolean;
86
- value: string;
87
- onPatch: (raw: string) => void;
88
- onCommit: () => void;
89
- onEnter: () => void;
90
- }): ReactElement {
91
- const input = (
92
- <input
93
- id={id}
94
- type={isPrice ? "text" : "number"}
95
- inputMode={isPrice ? "numeric" : "decimal"}
96
- min={isPrice ? undefined : 0}
97
- step={isPrice ? undefined : 0.01}
98
- value={value}
99
- placeholder={isPrice ? "0" : undefined}
100
- onChange={(event) => onPatch(event.target.value)}
101
- onBlur={onCommit}
102
- onKeyDown={(event) => {
103
- if (event.key === "Enter") {
104
- event.preventDefault();
105
- onEnter();
106
- }
107
- }}
108
- data-slot="search-range-input"
109
- />
110
- );
111
- return (
112
- <label data-slot="search-range-side" htmlFor={id}>
113
- <span>{label}</span>
114
- {isPrice ? (
115
- <span data-slot="search-range-affix">
116
- <span data-slot="search-range-prefix">R$</span>
117
- {input}
118
- </span>
119
- ) : (
120
- input
121
- )}
122
- </label>
123
- );
124
- }
125
-
126
- function CountFields({
127
- filter,
128
- pathFilters,
129
- onChange,
130
- }: {
131
- filter: SearchUiFilter;
132
- pathFilters: SearchPathFilters;
133
- onChange: FilterPanelProps["onChange"];
134
- }): ReactElement {
135
- const selected = pathFilterValue(pathFilters, filter.id);
136
- const choices = countFacetChoices(filter.options);
137
- return (
138
- <fieldset data-slot="search-filter">
139
- <legend>{filter.label}</legend>
140
- <div data-slot="search-count-group" role="group">
141
- {choices.map((choice) => (
142
- <button
143
- key={choice.id}
144
- type="button"
145
- data-slot="search-count-choice"
146
- data-selected={selected === choice.id ? "true" : undefined}
147
- onClick={() => onChange(filter.id, Number(choice.id))}
148
- >
149
- {choice.label}
150
- </button>
151
- ))}
152
- </div>
153
- </fieldset>
154
- );
155
- }
156
-
157
- function EnumFields({
158
- filter,
159
- pathFilters,
160
- onChange,
161
- }: {
162
- filter: SearchUiFilter;
163
- pathFilters: SearchPathFilters;
164
- onChange: FilterPanelProps["onChange"];
165
- }): ReactElement {
166
- const options = filter.options || [];
167
- const scroll = options.length > 8;
168
- return (
169
- <fieldset data-slot="search-filter">
170
- <legend>{filter.label}</legend>
171
- <div data-slot={scroll ? "search-scroll" : "search-enum-list"}>
172
- {options.map((option) => (
173
- <label key={option.id} data-slot="search-enum-option">
174
- <input
175
- type="checkbox"
176
- data-slot="search-checkbox"
177
- checked={pathFilterHasOption(pathFilters, filter.id, option.id)}
178
- onChange={() => onChange(filter.id, option.id)}
179
- />
180
- <span>{option.label}</span>
181
- </label>
182
- ))}
183
- </div>
184
- </fieldset>
185
- );
186
- }
187
-
188
- export function FilterPanel({
189
- filters,
190
- pathFilters,
191
- onChange,
192
- rangeDraft,
193
- onRangePatch,
194
- onRangeCommit,
195
- }: FilterPanelProps): ReactElement {
196
- return (
197
- <div data-slot="search-filters">
198
- {filters.map((filter) => {
199
- if (filter.type === "range") {
200
- return (
201
- <RangeFields
202
- key={filter.id}
203
- filter={filter}
204
- rangeDraft={rangeDraft}
205
- onRangePatch={onRangePatch}
206
- onRangeCommit={onRangeCommit}
207
- />
208
- );
209
- }
210
- if (filter.type === "count") {
211
- return (
212
- <CountFields
213
- key={filter.id}
214
- filter={filter}
215
- pathFilters={pathFilters}
216
- onChange={onChange}
217
- />
218
- );
219
- }
220
- return (
221
- <EnumFields
222
- key={filter.id}
223
- filter={filter}
224
- pathFilters={pathFilters}
225
- onChange={onChange}
226
- />
227
- );
228
- })}
229
- </div>
230
- );
231
- }
232
-
233
- export function rangeDraftFromPath(
234
- pathFilters: SearchPathFilters
235
- ): Record<string, { min: string; max: string }> {
236
- const price = pathFilters.price || {};
237
- const area = pathFilters.area || {};
238
- return {
239
- price: {
240
- min: price.min != null ? formatGroupedInteger(price.min) : "",
241
- max: price.max != null ? formatGroupedInteger(price.max) : "",
242
- },
243
- property_area_total: {
244
- min: area.min != null ? String(area.min) : "",
245
- max: area.max != null ? String(area.max) : "",
246
- },
247
- };
248
- }
@@ -1,46 +0,0 @@
1
- import type { ReactElement, SVGProps } from "react";
2
-
3
- type IconProps = SVGProps<SVGSVGElement>;
4
-
5
- function Icon({ children, ...props }: IconProps): ReactElement {
6
- return (
7
- <svg
8
- viewBox="0 0 24 24"
9
- fill="none"
10
- stroke="currentColor"
11
- strokeWidth={2}
12
- strokeLinecap="round"
13
- strokeLinejoin="round"
14
- aria-hidden
15
- data-slot="search-icon"
16
- {...props}
17
- >
18
- {children}
19
- </svg>
20
- );
21
- }
22
-
23
- export function SearchLensIcon(props: IconProps): ReactElement {
24
- return (
25
- <Icon {...props}>
26
- <circle cx="11" cy="11" r="7" />
27
- <path d="M20 20l-3.5-3.5" />
28
- </Icon>
29
- );
30
- }
31
-
32
- export function SearchClearIcon(props: IconProps): ReactElement {
33
- return (
34
- <Icon {...props}>
35
- <path d="M6 6l12 12M18 6L6 18" />
36
- </Icon>
37
- );
38
- }
39
-
40
- export function SearchCheckIcon(props: IconProps): ReactElement {
41
- return (
42
- <Icon {...props}>
43
- <path d="M5 12l5 5L20 7" />
44
- </Icon>
45
- );
46
- }