@usethrottle/storefront-react 0.0.0-stage → 0.1.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 (122) hide show
  1. package/CLAUDE.md +67 -0
  2. package/README.md +119 -2
  3. package/dist/StorefrontProvider-Br4wUHui.d.cts +559 -0
  4. package/dist/StorefrontProvider-DLEPEjg6.d.ts +559 -0
  5. package/dist/account/index.cjs +69 -0
  6. package/dist/account/index.cjs.map +1 -0
  7. package/dist/account/index.d.cts +23 -0
  8. package/dist/account/index.d.ts +23 -0
  9. package/dist/account/index.js +68 -0
  10. package/dist/account/index.js.map +1 -0
  11. package/dist/chunk-2LCPIY2P.cjs +16 -0
  12. package/dist/chunk-2LCPIY2P.cjs.map +1 -0
  13. package/dist/chunk-3A72UY6T.js +2126 -0
  14. package/dist/chunk-3A72UY6T.js.map +1 -0
  15. package/dist/chunk-3JMIVAHN.js +185 -0
  16. package/dist/chunk-3JMIVAHN.js.map +1 -0
  17. package/dist/chunk-4J6AGWNC.cjs +24 -0
  18. package/dist/chunk-4J6AGWNC.cjs.map +1 -0
  19. package/dist/chunk-4U6MYDZV.js +17 -0
  20. package/dist/chunk-4U6MYDZV.js.map +1 -0
  21. package/dist/chunk-66HDJVPS.js +22 -0
  22. package/dist/chunk-66HDJVPS.js.map +1 -0
  23. package/dist/chunk-6X2OZSNV.cjs +83 -0
  24. package/dist/chunk-6X2OZSNV.cjs.map +1 -0
  25. package/dist/chunk-6ZMMZ245.cjs +2127 -0
  26. package/dist/chunk-6ZMMZ245.cjs.map +1 -0
  27. package/dist/chunk-7R37CVAB.cjs +23 -0
  28. package/dist/chunk-7R37CVAB.cjs.map +1 -0
  29. package/dist/chunk-A3IFWQUV.js +368 -0
  30. package/dist/chunk-A3IFWQUV.js.map +1 -0
  31. package/dist/chunk-AYC2YK4E.cjs +95 -0
  32. package/dist/chunk-AYC2YK4E.cjs.map +1 -0
  33. package/dist/chunk-AZV5U7YB.cjs +18 -0
  34. package/dist/chunk-AZV5U7YB.cjs.map +1 -0
  35. package/dist/chunk-CE2SKNQP.cjs +71 -0
  36. package/dist/chunk-CE2SKNQP.cjs.map +1 -0
  37. package/dist/chunk-D76CRI4X.js +2175 -0
  38. package/dist/chunk-D76CRI4X.js.map +1 -0
  39. package/dist/chunk-DOAII637.cjs +186 -0
  40. package/dist/chunk-DOAII637.cjs.map +1 -0
  41. package/dist/chunk-DYHHAOMG.cjs +17 -0
  42. package/dist/chunk-DYHHAOMG.cjs.map +1 -0
  43. package/dist/chunk-EYSVU5SJ.js +196 -0
  44. package/dist/chunk-EYSVU5SJ.js.map +1 -0
  45. package/dist/chunk-HSUUDZWS.js +37 -0
  46. package/dist/chunk-HSUUDZWS.js.map +1 -0
  47. package/dist/chunk-HZ6VEN6Q.cjs +101 -0
  48. package/dist/chunk-HZ6VEN6Q.cjs.map +1 -0
  49. package/dist/chunk-IJOTLGPT.js +16 -0
  50. package/dist/chunk-IJOTLGPT.js.map +1 -0
  51. package/dist/chunk-ISDATHVC.js +219 -0
  52. package/dist/chunk-ISDATHVC.js.map +1 -0
  53. package/dist/chunk-LW2A6USV.js +100 -0
  54. package/dist/chunk-LW2A6USV.js.map +1 -0
  55. package/dist/chunk-M4YXSLRG.cjs +369 -0
  56. package/dist/chunk-M4YXSLRG.cjs.map +1 -0
  57. package/dist/chunk-NDUEJJLP.cjs +2176 -0
  58. package/dist/chunk-NDUEJJLP.cjs.map +1 -0
  59. package/dist/chunk-NNE4FYRT.js +820 -0
  60. package/dist/chunk-NNE4FYRT.js.map +1 -0
  61. package/dist/chunk-NW3EFHY2.js +15 -0
  62. package/dist/chunk-NW3EFHY2.js.map +1 -0
  63. package/dist/chunk-NZRUQUN5.js +167 -0
  64. package/dist/chunk-NZRUQUN5.js.map +1 -0
  65. package/dist/chunk-P6HHE57S.cjs +38 -0
  66. package/dist/chunk-P6HHE57S.cjs.map +1 -0
  67. package/dist/chunk-PHY7AY27.cjs +197 -0
  68. package/dist/chunk-PHY7AY27.cjs.map +1 -0
  69. package/dist/chunk-PNJOFFTL.cjs +128 -0
  70. package/dist/chunk-PNJOFFTL.cjs.map +1 -0
  71. package/dist/chunk-PXZQ4ONA.js +127 -0
  72. package/dist/chunk-PXZQ4ONA.js.map +1 -0
  73. package/dist/chunk-Q3VTUBPP.js +82 -0
  74. package/dist/chunk-Q3VTUBPP.js.map +1 -0
  75. package/dist/chunk-Q3XFD5UI.js +45 -0
  76. package/dist/chunk-Q3XFD5UI.js.map +1 -0
  77. package/dist/chunk-QM7KTT7F.js +94 -0
  78. package/dist/chunk-QM7KTT7F.js.map +1 -0
  79. package/dist/chunk-RLWZOLXL.js +70 -0
  80. package/dist/chunk-RLWZOLXL.js.map +1 -0
  81. package/dist/chunk-SV53BRP2.js +23 -0
  82. package/dist/chunk-SV53BRP2.js.map +1 -0
  83. package/dist/chunk-VWXJO427.cjs +821 -0
  84. package/dist/chunk-VWXJO427.cjs.map +1 -0
  85. package/dist/chunk-WIIOJDHR.cjs +220 -0
  86. package/dist/chunk-WIIOJDHR.cjs.map +1 -0
  87. package/dist/chunk-XQHGFWLG.cjs +46 -0
  88. package/dist/chunk-XQHGFWLG.cjs.map +1 -0
  89. package/dist/chunk-ZHCXI2ZZ.cjs +168 -0
  90. package/dist/chunk-ZHCXI2ZZ.cjs.map +1 -0
  91. package/dist/index-RSj2Rg62.d.cts +8 -0
  92. package/dist/index-RSj2Rg62.d.ts +8 -0
  93. package/dist/index.cjs +2829 -0
  94. package/dist/index.cjs.map +1 -0
  95. package/dist/index.d.cts +1718 -0
  96. package/dist/index.d.ts +1718 -0
  97. package/dist/index.js +2828 -0
  98. package/dist/index.js.map +1 -0
  99. package/dist/metadata-QhKw-tvz.d.cts +188 -0
  100. package/dist/metadata-QhKw-tvz.d.ts +188 -0
  101. package/dist/next/client.cjs +84 -0
  102. package/dist/next/client.cjs.map +1 -0
  103. package/dist/next/client.d.cts +40 -0
  104. package/dist/next/client.d.ts +40 -0
  105. package/dist/next/client.js +83 -0
  106. package/dist/next/client.js.map +1 -0
  107. package/dist/next/index.cjs +1090 -0
  108. package/dist/next/index.cjs.map +1 -0
  109. package/dist/next/index.d.cts +218 -0
  110. package/dist/next/index.d.ts +218 -0
  111. package/dist/next/index.js +1049 -0
  112. package/dist/next/index.js.map +1 -0
  113. package/dist/server/index.cjs +994 -0
  114. package/dist/server/index.cjs.map +1 -0
  115. package/dist/server/index.d.cts +229 -0
  116. package/dist/server/index.d.ts +229 -0
  117. package/dist/server/index.js +951 -0
  118. package/dist/server/index.js.map +1 -0
  119. package/dist/styles.css +2111 -0
  120. package/dist/use-part-DCfFk7kf.d.ts +24 -0
  121. package/dist/use-part-DgjPBL_O.d.cts +24 -0
  122. package/package.json +121 -3
@@ -0,0 +1,229 @@
1
+ import { CatalogClient, ProductsQuery, ListProduct, StorefrontProduct } from '@usethrottle/catalog';
2
+ import { DEFAULT_CACHE_POLICY, createServerCatalogClient } from '@usethrottle/catalog/server';
3
+ import { L as LoadProductInput, P as ProductData, R as RedirectData, a as LoadSearchInput, e as ShopAllData, b as LoadSettingsInput, N as NormalizedSettings, c as LoadShopAllInput, f as ShopQuery, g as ShopSource } from '../metadata-QhKw-tvz.js';
4
+ export { C as Crumb, d as LoaderMeta, S as SearchParamsInput, h as StorefrontMetadata, i as canonicalForShopQuery, p as pageWindow, j as parseShopQuery, k as productMetadata, r as robotsForShopQuery, s as searchMetadata, l as shopAllMetadata, m as shopQueryToSearch, v as variantFromSearch } from '../metadata-QhKw-tvz.js';
5
+ import { SiteDesign, PresetName, ThemeTokens, SiteMenuItem, SlotRenderer } from '@usethrottle/ui';
6
+
7
+ type CachePolicy = NonNullable<Parameters<typeof createServerCatalogClient>[0]['cachePolicy']>;
8
+ /**
9
+ * How long each kind of catalog read is cached on the server: long, with coarse
10
+ * invalidation. Everything but search is `'until-changed'`: kept (the SDK caps
11
+ * it at an hour as a safety TTL) and cleared sooner by the catalog's
12
+ * `throttle-catalog` cache tags and the generation watcher
13
+ * (`createRevalidateHandler`, `syncCatalogGeneration`). Next regenerates a page
14
+ * on its lowest revalidate, so a short window on any one read (the SDK's own
15
+ * default is 60 s for lists, filters, related and reviews) would regenerate
16
+ * every shop, collection and product page, per filter, sort and page, that often.
17
+ *
18
+ * Search is `'no-store'` (the SDK's `search` kind is the suggest endpoint). A
19
+ * search page's own list request, `products.list?q=`, is a `listings` read, so
20
+ * `loadSearch` (and any listing carrying `q`) sends it with
21
+ * `fetchInit: { cache: 'no-store' }`. Its URLs are unbounded, so the search
22
+ * route must render dynamically (read `searchParams`, or
23
+ * `export const dynamic = 'force-dynamic'`). A customer-token, cart or preview
24
+ * request is never cached whatever this says.
25
+ */
26
+ declare const STOREFRONT_CACHE_POLICY: typeof DEFAULT_CACHE_POLICY;
27
+ /**
28
+ * The catalog client for server components, on `STOREFRONT_CACHE_POLICY`.
29
+ * `cachePolicy` overrides single kinds (`{ listings: '120m' }`). Keep an
30
+ * override at an hour or more: a shorter one makes every page that reads that
31
+ * kind regenerate that often (ISR writes on Vercel). `previewToken` reads draft
32
+ * settings and pages, uncached.
33
+ */
34
+ declare function createStorefrontServerClient(o: {
35
+ catalogKey: string;
36
+ previewToken?: string;
37
+ baseUrl?: string;
38
+ cachePolicy?: CachePolicy;
39
+ }): CatalogClient;
40
+
41
+ /** The store's settings, normalised: a partial or missing answer takes the defaults. */
42
+ declare function loadSettings(i: LoadSettingsInput): Promise<NormalizedSettings>;
43
+ /**
44
+ * The first page of a shop, collection, category or tag listing for the URL's
45
+ * query. `null`: the collection, category or list does not exist, or the tag has no products; `{ redirectTo }`:
46
+ * a collection was renamed (the handle it has now). Other catalog failures are thrown.
47
+ */
48
+ declare const loadShopAll: (i: LoadShopAllInput) => Promise<ShopAllData | RedirectData | null>;
49
+ /** A search's results: the same data as a listing, `source.kind` `'search'`. */
50
+ declare function loadSearch({ q, ...rest }: LoadSearchInput): Promise<ShopAllData>;
51
+ /**
52
+ * A product page's data. `null`: no such product; `{ redirectTo }`: the handle
53
+ * was renamed. Related products come with it (none when the section is off, or
54
+ * when only that request fails).
55
+ */
56
+ declare function loadProduct(i: LoadProductInput): Promise<ProductData | RedirectData | null>;
57
+
58
+ /** What a section lists. Plain data, so a Builder can store it as a widget's prop. */
59
+ type ProductSource = {
60
+ kind: 'collection' | 'category' | 'tag';
61
+ handle: string;
62
+ } | {
63
+ kind: 'featured' | 'newest' | 'best_rated';
64
+ } | {
65
+ kind: 'manual';
66
+ handles: string[];
67
+ };
68
+ /** The catalog's `products.list` query. */
69
+ type ListQuery = ProductsQuery;
70
+ /**
71
+ * What `loadMerchProducts` answers and a section's `initialData` takes. Plain JSON.
72
+ * `title` is a collection's own title and `priceContext` is the list answer's; both are optional.
73
+ */
74
+ type MerchProductsData = {
75
+ products: ListProduct[];
76
+ /** When the server built this answer (ISO 8601). The `new` badge ages against it. */
77
+ generatedAt: string;
78
+ title?: string;
79
+ priceContext?: 'anonymous' | 'customer' | 'email_unverified' | 'anonymous_fallback';
80
+ };
81
+ /**
82
+ * The `products.list` query for a source: the shelf mapping of Meridian
83
+ * `lib/home.ts` (`featured` is the featured flag; `newest` and `best_rated` are
84
+ * those sorts). A `manual` source asks for its handles in one request; the
85
+ * catalog does not promise their order, so `orderByHandles` restores it.
86
+ * `fields` is `cardFields(settings)`, the same one the server loader uses.
87
+ */
88
+ declare function productSourceQuery(source: ProductSource, limit: number, o?: {
89
+ fields?: readonly string[];
90
+ }): ListQuery;
91
+
92
+ /** Input of `loadMerchProducts`: where the products come from and how many. */
93
+ type LoadMerchProductsInput = {
94
+ client: CatalogClient;
95
+ source: ProductSource;
96
+ limit: number;
97
+ locale?: string;
98
+ currency?: string;
99
+ /** The store's settings, when the page already has them (`loadSettings`): saves this call its own `/config` read. */
100
+ settings?: NormalizedSettings;
101
+ };
102
+ /**
103
+ * The products of a section's source, in one `products.list` request (a manual
104
+ * source's handles go together in it; a collection also asks for its title, in
105
+ * parallel). A source that names nothing, or a collection, category or list
106
+ * the catalog does not have, answers no products, so the section renders
107
+ * nothing instead of failing the page. Other failures are thrown. The answer is
108
+ * plain JSON: pass it to a section as `initialData`.
109
+ */
110
+ declare function loadMerchProducts(i: LoadMerchProductsInput): Promise<MerchProductsData>;
111
+
112
+ /**
113
+ * The `fields` a product list asks for. A custom tag badge needs the product's
114
+ * tags, which the default (lite) answer leaves out. Undefined otherwise, so the
115
+ * request is the default one.
116
+ */
117
+ declare function cardFields(settings: NormalizedSettings): readonly string[] | undefined;
118
+ /**
119
+ * The `products.list` query for a listing. Pure, and the one place it is built:
120
+ * the server loader and a client island both call it, so the island's request
121
+ * matches the server's and starts on its answer (`initialData`).
122
+ *
123
+ * The page's path (`source`) names the collection, category or tag. A sort that
124
+ * is not the store's default counts as asked for (the URL omits the default):
125
+ * it is kept when it makes sense, `relevance` only with a search and `manual`
126
+ * only on a manual collection (`manualCollection`). With no sort asked for, the
127
+ * shop, a category or a tag takes `listing.defaultSort` (`featured` is the
128
+ * catalog's own default); a collection keeps its own order and a search keeps
129
+ * relevance. Pass `fields` from `cardFields(settings)`.
130
+ */
131
+ declare function shopListQuery(query: ShopQuery, source: ShopSource, settings: NormalizedSettings, o?: {
132
+ fields?: readonly string[];
133
+ manualCollection?: boolean;
134
+ }): ProductsQuery;
135
+
136
+ /** A site design with every field decided (R11): what the components read. */
137
+ type ResolvedSiteDesign = {
138
+ source: 'builder' | 'catalog-adapter';
139
+ preset: PresetName;
140
+ scheme: 'light' | 'dark' | 'auto';
141
+ theme: ThemeTokens;
142
+ brand: {
143
+ storeName: string;
144
+ logo: {
145
+ light?: string;
146
+ dark?: string;
147
+ } | null;
148
+ };
149
+ menus: Record<string, SiteMenuItem[]>;
150
+ announcement: {
151
+ message: string;
152
+ href?: string;
153
+ } | null;
154
+ /** The site strings: the Builder's over the catalog adapter's. */
155
+ strings: Record<string, string>;
156
+ /** Only what the Builder provided. It outranks the `localization` prop; the adapter's strings are catalog text and do not. */
157
+ builderStrings: Record<string, string>;
158
+ seo: {
159
+ titleTemplate: string;
160
+ defaultDescription?: string;
161
+ shareImage?: string;
162
+ };
163
+ routes: {
164
+ page: string;
165
+ };
166
+ throttlePublishableKey: string | null;
167
+ pageOutlet: ((handle: string) => SlotRenderer | null) | null;
168
+ };
169
+ /**
170
+ * The inputs of `resolveSiteDesign`: the Builder's site (or `null`), the catalog's settings and the developer's props. The theme group resolves Builder, props, catalog, defaults; every other field Builder, then catalog.
171
+ */
172
+ type ResolveSiteDesignInput = {
173
+ site: SiteDesign | null;
174
+ settings: NormalizedSettings;
175
+ preset?: PresetName;
176
+ theme?: Partial<ThemeTokens>;
177
+ scheme?: 'light' | 'dark' | 'auto';
178
+ throttlePublishableKey?: string;
179
+ };
180
+ /**
181
+ * Decides every site-design field (R11, owner ruling 2026-11-15). Pure and
182
+ * server-safe.
183
+ *
184
+ * - **Theme group** (`preset`, tokens, colour scheme): Builder, then the
185
+ * developer's `preset` / `theme` / `scheme` props, then the catalog adapter,
186
+ * then the defaults (`clean`, `auto`). An explicit `preset` or `theme` prop
187
+ * skips the adapter's theme. A Builder with `customized: false` contributes
188
+ * only its preset and colour scheme. Tokens are `PRESET_TOKENS[preset]`, then
189
+ * the `theme` prop, then the winning source's values, deep-merged.
190
+ * - **Every other field**: Builder, then the catalog adapter, field by field; a
191
+ * field a source leaves `undefined` falls through and `null` is a value.
192
+ * - **Account key**: the `throttlePublishableKey` prop, then the Builder's
193
+ * `connections`, then `null`.
194
+ *
195
+ * A `preset` / `theme` / `scheme` prop that a Builder theme shadows logs one
196
+ * development warning naming the prop.
197
+ */
198
+ declare function resolveSiteDesign(input: ResolveSiteDesignInput): ResolvedSiteDesign;
199
+
200
+ /**
201
+ * A link by the store's route patterns (`settings.routes`). `'page'` uses the
202
+ * site design's page route when it names one (a Builder site owns it), and
203
+ * `'search'` fills `{q}`. Ported from Meridian `lib/menu.ts`
204
+ * (`routeHref` / `searchHref`). Server-safe.
205
+ */
206
+ declare function routeHref(settings: NormalizedSettings, kind: 'product' | 'collection' | 'category' | 'tag' | 'page' | 'search', value: string, site?: ResolvedSiteDesign): string;
207
+
208
+ /**
209
+ * schema.org `Product` for a product page: its images, brand, SKU and one
210
+ * `Offer` at the lowest price a variant sells for (prices as decimal text).
211
+ * Available when any variant is in stock; with none, pre-order, back-order, else out of stock.
212
+ */
213
+ declare function productJsonLd(product: StorefrontProduct, o: {
214
+ url: string;
215
+ settings: NormalizedSettings;
216
+ currency: string;
217
+ }): object;
218
+ /** schema.org `BreadcrumbList`. `url`s are absolute. */
219
+ declare function breadcrumbJsonLd(crumbs: {
220
+ name: string;
221
+ url: string;
222
+ }[]): object;
223
+ /** schema.org `ItemList` of a listing's products, each a link to its page. */
224
+ declare function itemListJsonLd(products: ListProduct[], o: {
225
+ baseUrl: string;
226
+ settings: NormalizedSettings;
227
+ }): object;
228
+
229
+ export { type ListQuery, type LoadMerchProductsInput, LoadProductInput, LoadSearchInput, LoadSettingsInput, LoadShopAllInput, type MerchProductsData, ProductData, type ProductSource, RedirectData, type ResolveSiteDesignInput, type ResolvedSiteDesign, STOREFRONT_CACHE_POLICY, ShopAllData, ShopQuery, ShopSource, breadcrumbJsonLd, cardFields, createStorefrontServerClient, itemListJsonLd, loadMerchProducts, loadProduct, loadSearch, loadSettings, loadShopAll, productJsonLd, productSourceQuery, resolveSiteDesign, routeHref, shopListQuery };