@usethrottle/builder-react 0.0.0-stage → 0.2.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.
- package/CLAUDE.md +228 -0
- package/dist/chunk-NUE2KNT2.js +2026 -0
- package/dist/chunk-S2XR224A.cjs +2026 -0
- package/dist/index.cjs +2317 -0
- package/dist/index.d.cts +452 -0
- package/dist/index.d.ts +452 -0
- package/dist/index.js +2320 -0
- package/dist/next.cjs +93 -0
- package/dist/next.d.cts +52 -0
- package/dist/next.d.ts +52 -0
- package/dist/next.js +93 -0
- package/dist/seo-Dz439Jlk.d.cts +149 -0
- package/dist/seo-Dz439Jlk.d.ts +149 -0
- package/dist/server.cjs +118 -0
- package/dist/server.d.cts +88 -0
- package/dist/server.d.ts +88 -0
- package/dist/server.js +118 -0
- package/package.json +96 -3
- package/README.md +0 -3
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,452 @@
|
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
import { ReactNode, ComponentType, CSSProperties } from 'react';
|
|
3
|
+
import { TemplateAst, WidgetNode, SettingValue, WidgetDefinition, DataSourceDescriptor, PageDocument, FrozenAsset, WidgetRegistry, CustomWidgetSnapshot, SettingField, DataBinding } from '@usethrottle/builder-schema';
|
|
4
|
+
import { BuilderClient } from '@usethrottle/builder';
|
|
5
|
+
export { BuilderNotFoundError, BuilderUnavailableError } from '@usethrottle/builder';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* The most nodes one custom widget may render. It is the number the template
|
|
9
|
+
* validator bounds statically (`templateWeight`, `MAX_TEMPLATE_WEIGHT`), so a
|
|
10
|
+
* validated template can never hit it, and a snapshot that was not validated
|
|
11
|
+
* (or a hostile one) stops here instead of building a huge tree.
|
|
12
|
+
*/
|
|
13
|
+
declare const MAX_RENDERED_NODES = 20000;
|
|
14
|
+
/** A count of rendered nodes with a ceiling. One per custom widget render. */
|
|
15
|
+
declare class RenderBudget {
|
|
16
|
+
readonly limit: number;
|
|
17
|
+
private spent;
|
|
18
|
+
constructor(limit?: number);
|
|
19
|
+
/** Takes `count` nodes. False, and nothing taken, when that would pass the limit. */
|
|
20
|
+
take(count?: number): boolean;
|
|
21
|
+
get used(): number;
|
|
22
|
+
get exhausted(): boolean;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* What a renderer needs of a budget: the public members of `RenderBudget`, not the class. The server entries' type
|
|
26
|
+
* files carry their own copy of the class, and its private field would make a pack made against one copy unusable
|
|
27
|
+
* with the other (`loadSite({ packs })`).
|
|
28
|
+
*/
|
|
29
|
+
type Budget = Pick<RenderBudget, 'limit' | 'used' | 'exhausted' | 'take'>;
|
|
30
|
+
/** True when a template's worst case fits the budget; the interpreter refuses the template otherwise. */
|
|
31
|
+
declare const fitsBudget: (ast: TemplateAst, limit?: number) => boolean;
|
|
32
|
+
|
|
33
|
+
/** Resolved data by binding key (`bindingKey`), plus `context.*` entries a slot supplies. */
|
|
34
|
+
type DataMap = Record<string, unknown>;
|
|
35
|
+
type WidgetRenderProps = {
|
|
36
|
+
node: WidgetNode;
|
|
37
|
+
/** The node's settings at this variant, defaults filled, translatable text resolved, image ids replaced by their frozen asset. */
|
|
38
|
+
props: Record<string, SettingValue>;
|
|
39
|
+
/** Resolved data by the widget's named inputs. Absent until a perShopper source has resolved in the browser. */
|
|
40
|
+
data: Record<string, unknown>;
|
|
41
|
+
editMode: boolean;
|
|
42
|
+
locale: string;
|
|
43
|
+
/** The only origin a media `src` may be on; pass it to `AssetImage`. */
|
|
44
|
+
mediaOrigin: string;
|
|
45
|
+
/** In the editor only: the inline editor of one text setting of this node, or null. */
|
|
46
|
+
inlineEdit?: ((key: string) => ReactNode | null) | undefined;
|
|
47
|
+
/** The href of a link target (page, catalog kinds), or null. Callers still check the result with `safeUrl`. */
|
|
48
|
+
resolveLink?: ((target: {
|
|
49
|
+
kind: string;
|
|
50
|
+
[key: string]: unknown;
|
|
51
|
+
}) => string | null) | undefined;
|
|
52
|
+
/** Custom widgets only: the node budget of this render (`MAX_RENDERED_NODES`). */
|
|
53
|
+
budget?: Budget | undefined;
|
|
54
|
+
};
|
|
55
|
+
type EditModeHooks = {
|
|
56
|
+
onSelect(id: string): void;
|
|
57
|
+
onHover(id: string | null): void;
|
|
58
|
+
/** An inline editor for one text setting of a node, or null when the editor has none. */
|
|
59
|
+
inlineEdit(id: string, key: string): ReactNode | null;
|
|
60
|
+
};
|
|
61
|
+
type ResolveContext = {
|
|
62
|
+
locale: string;
|
|
63
|
+
/** The store's main currency, when the site knows it. Never defaulted here. */
|
|
64
|
+
currency?: string | undefined;
|
|
65
|
+
preview: boolean;
|
|
66
|
+
/** The slot context (`{ product }` or `{ listing }`) for `context.*` bindings. */
|
|
67
|
+
context?: unknown;
|
|
68
|
+
signal: AbortSignal;
|
|
69
|
+
};
|
|
70
|
+
type DataSourceResolver = (params: Record<string, SettingValue>, ctx: ResolveContext) => Promise<unknown>;
|
|
71
|
+
type PackDataSource = DataSourceDescriptor & {
|
|
72
|
+
resolve: DataSourceResolver;
|
|
73
|
+
};
|
|
74
|
+
type PackWidget = WidgetDefinition & {
|
|
75
|
+
Component: ComponentType<WidgetRenderProps>;
|
|
76
|
+
};
|
|
77
|
+
/** The pickers and href resolution of a pack's link targets (catalog: category, collection, product, search). */
|
|
78
|
+
type LinkTargetProvider = {
|
|
79
|
+
/** The href of a menu target the pack owns, or null when it cannot resolve one. */
|
|
80
|
+
resolve(target: {
|
|
81
|
+
kind: string;
|
|
82
|
+
[key: string]: unknown;
|
|
83
|
+
}): string | null;
|
|
84
|
+
};
|
|
85
|
+
type SlotPoint = {
|
|
86
|
+
name: string;
|
|
87
|
+
context: 'product' | 'listing' | 'none';
|
|
88
|
+
};
|
|
89
|
+
/** A set of widgets and data sources (spec §9.4). `basic` ships with this package. */
|
|
90
|
+
type WidgetPack = {
|
|
91
|
+
id: string;
|
|
92
|
+
/** The npm version that ships it. */
|
|
93
|
+
version: string;
|
|
94
|
+
widgets: PackWidget[];
|
|
95
|
+
dataSources: PackDataSource[];
|
|
96
|
+
linkTargets?: LinkTargetProvider;
|
|
97
|
+
slots?: SlotPoint[];
|
|
98
|
+
};
|
|
99
|
+
/** A page document as the store reads it (a published snapshot). */
|
|
100
|
+
type PageAssets = Record<string, FrozenAsset>;
|
|
101
|
+
type LoadedPage = {
|
|
102
|
+
kind: 'page';
|
|
103
|
+
slug: string;
|
|
104
|
+
title: string;
|
|
105
|
+
path: string;
|
|
106
|
+
generation: number;
|
|
107
|
+
document: PageDocument;
|
|
108
|
+
assets: PageAssets;
|
|
109
|
+
/** Data of every non-perShopper binding, resolved on the server. Never holds perShopper data. */
|
|
110
|
+
initialData: DataMap;
|
|
111
|
+
/** The page's other fields as the read API sent them (seo, description, ...). */
|
|
112
|
+
meta: Record<string, unknown>;
|
|
113
|
+
};
|
|
114
|
+
type LoadedRedirect = {
|
|
115
|
+
kind: 'redirect';
|
|
116
|
+
redirectTo: string;
|
|
117
|
+
};
|
|
118
|
+
/** What a site part or a slot holds once the server has read it. */
|
|
119
|
+
type LoadedPart = {
|
|
120
|
+
document: PageDocument;
|
|
121
|
+
assets: PageAssets;
|
|
122
|
+
initialData: DataMap;
|
|
123
|
+
};
|
|
124
|
+
/**
|
|
125
|
+
* The store's site design, read once per request. `unavailable` means the
|
|
126
|
+
* Builder could not answer and there is no last good answer: every part then
|
|
127
|
+
* renders nothing (ruling R8) and the catalog's own design takes over.
|
|
128
|
+
*/
|
|
129
|
+
type LoadedSite = {
|
|
130
|
+
status: 'ok';
|
|
131
|
+
locale: string;
|
|
132
|
+
generation: number;
|
|
133
|
+
siteVersion: number;
|
|
134
|
+
/** The origin media files must be on (https). Images from anywhere else are refused. */
|
|
135
|
+
mediaOrigin: string;
|
|
136
|
+
/** Site settings resolved for the locale (localized values are strings). */
|
|
137
|
+
settings: Record<string, unknown>;
|
|
138
|
+
header: LoadedPart;
|
|
139
|
+
footer: LoadedPart;
|
|
140
|
+
slots: Record<string, LoadedPart>;
|
|
141
|
+
} | {
|
|
142
|
+
status: 'unavailable';
|
|
143
|
+
locale: string;
|
|
144
|
+
};
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* The definitions of the schema registry plus what only the renderer has: the
|
|
148
|
+
* component of each widget and the resolver of each data source.
|
|
149
|
+
*/
|
|
150
|
+
interface RendererRegistry extends WidgetRegistry {
|
|
151
|
+
/** The component for a node, or undefined (the renderer then treats the node as missing). */
|
|
152
|
+
component(node: WidgetNode): ComponentType<WidgetRenderProps> | undefined;
|
|
153
|
+
resolver(sourceId: string): DataSourceResolver | undefined;
|
|
154
|
+
/** The same registry with a published document's frozen custom widgets added. */
|
|
155
|
+
withCustom(snapshots: readonly CustomWidgetSnapshot[]): RendererRegistry;
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Builds the component for one frozen custom widget (Task 14: template and
|
|
159
|
+
* composite runtime). Returns null for a disabled or unknown snapshot. It gets
|
|
160
|
+
* the registry the widget renders in: a composite renders its inner nodes with it.
|
|
161
|
+
*/
|
|
162
|
+
type CustomWidgetFactory = (snapshot: CustomWidgetSnapshot, registry: RendererRegistry) => ComponentType<WidgetRenderProps> | null;
|
|
163
|
+
type RendererRegistryOptions = {
|
|
164
|
+
customWidget?: CustomWidgetFactory;
|
|
165
|
+
};
|
|
166
|
+
/** Builds the registry the renderer reads. The built-in packs come first; a pack cannot replace a built-in type. */
|
|
167
|
+
declare function createRendererRegistry(packs: readonly WidgetPack[], options?: RendererRegistryOptions): RendererRegistry;
|
|
168
|
+
|
|
169
|
+
type BuilderRendererProps = {
|
|
170
|
+
document: PageDocument;
|
|
171
|
+
registry: RendererRegistry;
|
|
172
|
+
data: DataMap;
|
|
173
|
+
editMode?: EditModeHooks | undefined;
|
|
174
|
+
locale: string;
|
|
175
|
+
assets: Record<string, FrozenAsset>;
|
|
176
|
+
/**
|
|
177
|
+
* The one origin media files may come from (`https://...`). A media `src`
|
|
178
|
+
* anywhere else, or over http, is refused. Empty (the default) refuses all.
|
|
179
|
+
*/
|
|
180
|
+
mediaOrigin?: string | undefined;
|
|
181
|
+
/** The href of a link target (page, catalog kinds), or null. A `url` target needs no resolver. */
|
|
182
|
+
resolveLink?: ((target: {
|
|
183
|
+
kind: string;
|
|
184
|
+
[key: string]: unknown;
|
|
185
|
+
}) => string | null) | undefined;
|
|
186
|
+
};
|
|
187
|
+
/** The text of a localized map for a locale: the locale, its language, `en`, then any. */
|
|
188
|
+
declare function pickLocale(value: Record<string, unknown>, locale: string): string;
|
|
189
|
+
/**
|
|
190
|
+
* Turns a published page document into React (spec §8, §9). It is a plain
|
|
191
|
+
* function of its props with no state, effects or context, so it renders the
|
|
192
|
+
* same in a server component, on the server side of a client render and in the
|
|
193
|
+
* editor canvas.
|
|
194
|
+
*
|
|
195
|
+
* - Every node has a wrapper with `data-b-id`; the compiled CSS is scoped to it.
|
|
196
|
+
* - An unknown widget type renders nothing, with `data-b-missing`.
|
|
197
|
+
* - A widget older than the registry's is upgraded in memory.
|
|
198
|
+
* - Template values only ever go through React; nothing here sets inner HTML.
|
|
199
|
+
*/
|
|
200
|
+
declare function BuilderRenderer(props: BuilderRendererProps): ReactNode;
|
|
201
|
+
type RenderWarning = {
|
|
202
|
+
code: 'MULTIPLE_H1';
|
|
203
|
+
message: string;
|
|
204
|
+
nodeIds: string[];
|
|
205
|
+
};
|
|
206
|
+
/**
|
|
207
|
+
* Warnings about a document that never stop it from rendering (the editor shows
|
|
208
|
+
* them; the store ignores them). One page with more than one `h1` is a single
|
|
209
|
+
* warning, not a block.
|
|
210
|
+
*/
|
|
211
|
+
declare function validateRender(doc: PageDocument): RenderWarning[];
|
|
212
|
+
|
|
213
|
+
/** The CSS text of one setting value, or null when it is not valid for its control. */
|
|
214
|
+
declare function cssValue(control: SettingField['control'], value: unknown): string | null;
|
|
215
|
+
/**
|
|
216
|
+
* The stylesheet for a document: a plain rule per node for desktop, then the
|
|
217
|
+
* tablet changes in `@media (max-width:1024px)` and the phone changes (against
|
|
218
|
+
* tablet, which still applies at phone width) in `@media (max-width:767px)`.
|
|
219
|
+
* `assets` defaults to the document's own frozen assets; a background image is
|
|
220
|
+
* used only when it is on `mediaOrigin`.
|
|
221
|
+
*/
|
|
222
|
+
declare function compileResponsiveCss(doc: PageDocument, registry: RendererRegistry, assets?: Record<string, FrozenAsset> | undefined, mediaOrigin?: string): string;
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* The containment every custom widget sits in. The CSS sanitiser allows
|
|
226
|
+
* `transform`, `translate`, `scale` and negative margins (spec §10.3), so
|
|
227
|
+
* without a box a widget could paint over, and take clicks from, a store's own
|
|
228
|
+
* button. `contain: paint` and `overflow: clip` stop anything it draws at its
|
|
229
|
+
* edge, and `isolation: isolate` keeps its stacking inside. Widget CSS is
|
|
230
|
+
* scoped to descendants of the wrapper (`[data-b-w] .x`), so it can never
|
|
231
|
+
* restyle the wrapper itself; the declarations are also inline, which beats any
|
|
232
|
+
* stylesheet.
|
|
233
|
+
*/
|
|
234
|
+
declare const CUSTOM_WIDGET_CONTAINMENT: CSSProperties;
|
|
235
|
+
type NodePart = 'section' | 'column' | 'widget';
|
|
236
|
+
type NodeWrapperProps = {
|
|
237
|
+
id: string;
|
|
238
|
+
part: NodePart;
|
|
239
|
+
/** The widget type; sections and columns have none. */
|
|
240
|
+
type?: string;
|
|
241
|
+
as?: 'div' | 'section';
|
|
242
|
+
className: string;
|
|
243
|
+
anchor?: string | undefined;
|
|
244
|
+
/** A custom widget: it gets the containment box and `data-b-w`, the scope of its CSS. */
|
|
245
|
+
custom?: boolean;
|
|
246
|
+
missing?: boolean;
|
|
247
|
+
/** Hooks of the editor canvas, or undefined on a store. */
|
|
248
|
+
edit?: EditModeHooks | undefined;
|
|
249
|
+
children?: ReactNode;
|
|
250
|
+
};
|
|
251
|
+
/**
|
|
252
|
+
* One element per node: it carries `data-b-id` (what the compiled CSS is scoped
|
|
253
|
+
* by) and `data-throttle-part`, and in the editor the select and hover hooks.
|
|
254
|
+
* Links inside it are inert in the editor.
|
|
255
|
+
*/
|
|
256
|
+
declare function NodeWrapper(props: NodeWrapperProps): ReactNode;
|
|
257
|
+
|
|
258
|
+
/** A frozen asset as the renderer hands it to a widget in place of a media asset id. */
|
|
259
|
+
declare function isFrozenAsset(value: unknown): value is FrozenAsset;
|
|
260
|
+
type AssetImageProps = {
|
|
261
|
+
asset: FrozenAsset | SettingValue | undefined;
|
|
262
|
+
/** The origin a media file must be on (`WidgetRenderProps.mediaOrigin`). Empty shows no image. */
|
|
263
|
+
mediaOrigin: string;
|
|
264
|
+
alt: string;
|
|
265
|
+
sizes?: string;
|
|
266
|
+
className?: string;
|
|
267
|
+
loading?: 'lazy' | 'eager';
|
|
268
|
+
style?: CSSProperties;
|
|
269
|
+
};
|
|
270
|
+
/**
|
|
271
|
+
* An image of a frozen asset. It always has `width`, `height` and an
|
|
272
|
+
* `aspect-ratio` from the asset's own size, so the space is reserved before the
|
|
273
|
+
* file loads and the page does not shift. `srcset` comes from the asset's width
|
|
274
|
+
* variants. Renders nothing for a missing asset, and for a file that is not https
|
|
275
|
+
* on the media origin (spec: `src` outside the media origin is refused).
|
|
276
|
+
*/
|
|
277
|
+
declare function AssetImage(props: AssetImageProps): ReactNode;
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* Widget CSS goes into the page as the text of a `<style>` element and nowhere
|
|
281
|
+
* else, never as raw HTML. React writes a string child as text, so markup in it
|
|
282
|
+
* cannot become an element. The CSS has already been re-serialised from its AST
|
|
283
|
+
* by the sanitiser; as a last guard, text that holds `<` (which could only be
|
|
284
|
+
* the start of a closing tag) is refused whole.
|
|
285
|
+
*/
|
|
286
|
+
declare function WidgetStyle({ css }: {
|
|
287
|
+
css: string;
|
|
288
|
+
}): ReactNode;
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* The renderer's stylesheet. Every rule is in `@layer throttle` and every class
|
|
292
|
+
* starts with `tb-`. Widgets read their settings as `var(--b-<key>, <default>)`;
|
|
293
|
+
* layout reads the `--tb-*` custom properties the compiler sets per node.
|
|
294
|
+
*/
|
|
295
|
+
declare const BASE_CSS = "@layer throttle{\n:root{--tb-scale:1;--tb-space-xs:calc(.25rem*var(--tb-scale));--tb-space-s:calc(.5rem*var(--tb-scale));--tb-space-m:calc(1rem*var(--tb-scale));--tb-space-l:calc(1.5rem*var(--tb-scale));--tb-space-xl:calc(2.5rem*var(--tb-scale));--tb-space-2xl:calc(4rem*var(--tb-scale));\n--tb-text-xs:.75rem;--tb-text-s:.875rem;--tb-text-m:1rem;--tb-text-l:1.25rem;--tb-text-xl:1.5rem;--tb-text-2xl:2rem;--tb-text-3xl:2.75rem}\n.tb-root{display:block;inline-size:100%}\n.tb-section,.tb-col,.tb-w{--tb-hide:initial}\n.tb-section,.tb-col{--tb-bg:initial;--tb-bgimg:initial;--tb-bgpos:initial;--tb-bgsize:initial;--tb-overlay:initial}\n.tb-section{--tb-valign:initial;--tb-minh:initial;--tb-pady:initial;--tb-padx:initial;--tb-gap:initial;--tb-maxw:initial;--tb-flow:initial}\n.tb-col{--tb-pad:initial;--tb-self:initial}\n.tb-section{box-sizing:border-box;position:relative;display:var(--tb-hide,flex);flex-direction:column;justify-content:var(--tb-valign,flex-start);min-block-size:var(--tb-minh,0px);padding-block:var(--tb-pady,0px);padding-inline:var(--tb-padx,0px);background-color:var(--tb-bg,transparent);background-image:var(--tb-bgimg,none);background-position:var(--tb-bgpos,center);background-size:var(--tb-bgsize,cover);background-repeat:no-repeat}\n.tb-section::before{content:\"\";position:absolute;inset:0;background:var(--tb-overlay,transparent);pointer-events:none}\n.tb-inner{box-sizing:border-box;position:relative;inline-size:100%;max-inline-size:var(--tb-maxw,1200px);margin-inline:auto}\n.tb-row{display:flex;flex-flow:var(--tb-flow,row wrap);gap:var(--tb-gap,0px);align-items:stretch}\n.tb-col{box-sizing:border-box;display:var(--tb-hide,flex);flex-direction:column;flex:0 0 auto;inline-size:calc((100% - var(--tb-cn,0)*var(--tb-gap,0px))*var(--tb-cw,1));min-inline-size:0;align-self:var(--tb-self,stretch);padding:var(--tb-pad,0px);background-color:var(--tb-bg,transparent);background-image:var(--tb-bgimg,none);background-position:var(--tb-bgpos,center);background-size:var(--tb-bgsize,cover);background-repeat:no-repeat}\n.tb-w{display:var(--tb-hide,block);min-inline-size:0;margin-block-start:var(--b-spacingTop,var(--w-spacingTop,0px));margin-block-end:var(--b-spacingBottom,var(--w-spacingBottom,0px))}\n.tb-missing{padding:var(--tb-space-s);border:1px dashed var(--tb-color-border-control,currentColor);font-size:var(--tb-text-s)}\n@media (min-width:1025px){.tb-v:not(.tb-only-desktop){display:none!important}}\n@media (min-width:768px) and (max-width:1024px){.tb-v:not(.tb-only-tablet){display:none!important}}\n@media (max-width:767px){.tb-v:not(.tb-only-phone){display:none!important}}\n}";
|
|
296
|
+
|
|
297
|
+
type BuilderProviderProps = {
|
|
298
|
+
/** The publishable Builder key (`tb_pk_...`). Only needed for a `BuilderPage` that reads its own page. */
|
|
299
|
+
builderKey?: string;
|
|
300
|
+
client?: BuilderClient;
|
|
301
|
+
packs: readonly WidgetPack[];
|
|
302
|
+
/** What `loadSite()` read on the server. */
|
|
303
|
+
site: LoadedSite;
|
|
304
|
+
children: ReactNode;
|
|
305
|
+
};
|
|
306
|
+
/**
|
|
307
|
+
* Fills `SiteDesignContext` (menus, brand, announcement, strings, connections,
|
|
308
|
+
* the theme and a renderer for a Builder page by slug) and `SlotOutletContext`
|
|
309
|
+
* from a loaded site, and gives the Builder components their registry.
|
|
310
|
+
*
|
|
311
|
+
* Put it in a client module of the store, where the packs are created: a pack
|
|
312
|
+
* holds components and functions, which a server component cannot pass down.
|
|
313
|
+
* With a site the Builder could not answer (`status: 'unavailable'`) it fills
|
|
314
|
+
* nothing, so the catalog's own design shows and every part renders nothing.
|
|
315
|
+
*/
|
|
316
|
+
declare function BuilderProvider({ builderKey, client, packs, site, children }: BuilderProviderProps): ReactNode;
|
|
317
|
+
|
|
318
|
+
type BuilderContextValue = {
|
|
319
|
+
client: BuilderClient | null;
|
|
320
|
+
packs: readonly WidgetPack[];
|
|
321
|
+
registry: RendererRegistry;
|
|
322
|
+
site: LoadedSite;
|
|
323
|
+
locale: string;
|
|
324
|
+
mediaOrigin: string;
|
|
325
|
+
resolveLink: (target: {
|
|
326
|
+
kind: string;
|
|
327
|
+
[key: string]: unknown;
|
|
328
|
+
}) => string | null;
|
|
329
|
+
};
|
|
330
|
+
declare const BuilderContext: react.Context<BuilderContextValue | null>;
|
|
331
|
+
/** The provider's value, or null outside a `BuilderProvider`. */
|
|
332
|
+
declare const useBuilder: () => BuilderContextValue | null;
|
|
333
|
+
|
|
334
|
+
/** A loaded page rendered with the provider's registry. Data the server could not resolve fills in after mount. */
|
|
335
|
+
declare function BuilderPageView({ page, resolve }: {
|
|
336
|
+
page: LoadedPage;
|
|
337
|
+
resolve?: 'shopper' | 'all';
|
|
338
|
+
}): ReactNode;
|
|
339
|
+
/**
|
|
340
|
+
* A Builder page by slug. Pass `initial` (what `loadBuilderPage` read on the
|
|
341
|
+
* server) to render with no second read. Without it the page is read through the
|
|
342
|
+
* provider's client and the component suspends until it arrives.
|
|
343
|
+
*
|
|
344
|
+
* With no answer from the Builder it throws `BuilderUnavailableError`, so the
|
|
345
|
+
* store's error boundary shows its error page and never a blank 200 (ruling R8).
|
|
346
|
+
*/
|
|
347
|
+
declare function BuilderPage({ slug, initial }: {
|
|
348
|
+
slug: string;
|
|
349
|
+
initial?: LoadedPage;
|
|
350
|
+
}): ReactNode;
|
|
351
|
+
|
|
352
|
+
/** The store's published header. Renders nothing when the Builder is unavailable or the header is empty. */
|
|
353
|
+
declare const BuilderHeader: () => ReactNode;
|
|
354
|
+
/** The store's published footer. Renders nothing when the Builder is unavailable or the footer is empty. */
|
|
355
|
+
declare const BuilderFooter: () => ReactNode;
|
|
356
|
+
|
|
357
|
+
/**
|
|
358
|
+
* A named slot (`product.below`, `shop.above`, ...). `context` is what the
|
|
359
|
+
* storefront knows at that point (`{ product }` or `{ listing }`) and feeds the
|
|
360
|
+
* `context.*` data bindings of the slot's widgets. Renders nothing when the
|
|
361
|
+
* Builder is unavailable, the slot is unpublished or it is empty.
|
|
362
|
+
*/
|
|
363
|
+
declare function BuilderSlot({ name, context }: {
|
|
364
|
+
name: string;
|
|
365
|
+
context?: unknown;
|
|
366
|
+
}): ReactNode;
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* The key one binding is stored under. Identical bindings (same source, same
|
|
370
|
+
* params) share it, which is what makes "resolve once" work. A `context.*`
|
|
371
|
+
* binding is its own source id, since the slot supplies it.
|
|
372
|
+
*/
|
|
373
|
+
declare function bindingKey(binding: DataBinding): string;
|
|
374
|
+
/** The bindings of a node: its own, plus the definition's default for every input it leaves unset. */
|
|
375
|
+
declare function bindingsOf(node: WidgetNode, registry: Pick<RendererRegistry, 'widget'>): Record<string, DataBinding>;
|
|
376
|
+
/** Every distinct binding in a document, once, in document order. */
|
|
377
|
+
declare function collectBindings(doc: PageDocument, registry: Pick<RendererRegistry, 'widget'>): Map<string, DataBinding>;
|
|
378
|
+
/**
|
|
379
|
+
* Resolves each distinct binding once. `include` picks which sources run: the
|
|
380
|
+
* server passes `static` (a perShopper source never reaches SSR or a shared
|
|
381
|
+
* cache), the browser passes `shopper` after mount (or `all` when nothing was
|
|
382
|
+
* resolved on the server). `context.*` bindings and unknown sources are left out. A resolver that rejects leaves its key absent,
|
|
383
|
+
* so the widget renders its neutral state, never a broken page.
|
|
384
|
+
*/
|
|
385
|
+
declare function resolveBindings(bindings: ReadonlyMap<string, DataBinding>, registry: Pick<RendererRegistry, 'source' | 'resolver'>, ctx: ResolveContext, options: {
|
|
386
|
+
include: 'static' | 'shopper' | 'all';
|
|
387
|
+
}): Promise<DataMap>;
|
|
388
|
+
|
|
389
|
+
type VideoRef = {
|
|
390
|
+
provider: 'youtube' | 'vimeo';
|
|
391
|
+
id: string;
|
|
392
|
+
};
|
|
393
|
+
/**
|
|
394
|
+
* YouTube and Vimeo only, over https, as a watch, share or embed link. Anything
|
|
395
|
+
* else (another host, another scheme, credentials in the URL, a malformed id) is
|
|
396
|
+
* null. The embed address is rebuilt from the validated id, never from the input.
|
|
397
|
+
*/
|
|
398
|
+
declare function parseVideoUrl(input: string): VideoRef | null;
|
|
399
|
+
/** The iframe address: `youtube-nocookie.com` or `player.vimeo.com`, built from the id. */
|
|
400
|
+
declare function embedSrc(video: VideoRef, muted: boolean): string;
|
|
401
|
+
|
|
402
|
+
type El = {
|
|
403
|
+
tag: string;
|
|
404
|
+
href?: string | null;
|
|
405
|
+
children: (El | string)[]; /** Root only: some of the input was not read (an unfinished tag, or a size cap). */
|
|
406
|
+
truncated?: boolean;
|
|
407
|
+
};
|
|
408
|
+
/** The allow-listed tree of an HTML string. */
|
|
409
|
+
declare function parseRichText(source: string, mediaOrigin: string): El;
|
|
410
|
+
/** Untrusted HTML, shown through the allow-list. */
|
|
411
|
+
declare function RichText({ html, mediaOrigin, className, editMode, }: {
|
|
412
|
+
html: string;
|
|
413
|
+
mediaOrigin: string;
|
|
414
|
+
className?: string;
|
|
415
|
+
editMode?: boolean;
|
|
416
|
+
}): ReactNode;
|
|
417
|
+
|
|
418
|
+
/** The component of each `basic.*` type. The definitions are builder-schema's and are never re-declared here. */
|
|
419
|
+
declare const BASIC_COMPONENTS: Readonly<Record<string, ComponentType<WidgetRenderProps>>>;
|
|
420
|
+
/** The `basic` widget pack (spec §9.2): every renderer carries it. */
|
|
421
|
+
declare const basicPack: WidgetPack;
|
|
422
|
+
|
|
423
|
+
type TemplateWidgetProps = WidgetRenderProps & {
|
|
424
|
+
snapshot: CustomWidgetSnapshot;
|
|
425
|
+
registry: RendererRegistry;
|
|
426
|
+
};
|
|
427
|
+
/**
|
|
428
|
+
* A frozen template widget (spec §10.3). The body renders inside the part
|
|
429
|
+
* boundary and a Suspense, so a template that throws, in the browser or while
|
|
430
|
+
* the server renders, leaves an empty box and the rest of the page alone.
|
|
431
|
+
*/
|
|
432
|
+
declare function TemplateWidget(props: TemplateWidgetProps): ReactNode;
|
|
433
|
+
|
|
434
|
+
type CompositeWidgetProps = WidgetRenderProps & {
|
|
435
|
+
snapshot: CustomWidgetSnapshot;
|
|
436
|
+
registry: RendererRegistry;
|
|
437
|
+
};
|
|
438
|
+
/**
|
|
439
|
+
* A frozen composite widget. It renders inside the part boundary and a Suspense,
|
|
440
|
+
* so an inner widget that throws leaves an empty box and the rest of the page alone.
|
|
441
|
+
*/
|
|
442
|
+
declare function CompositeWidget(props: CompositeWidgetProps): ReactNode;
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* The component of one frozen custom widget, or null (the renderer then renders
|
|
446
|
+
* an empty box) for a disabled widget and for one that does not pass the
|
|
447
|
+
* validator. Template widgets are checked here with the same functions the
|
|
448
|
+
* Widget API used, so nothing unvalidated is ever interpreted.
|
|
449
|
+
*/
|
|
450
|
+
declare const customWidgetFactory: CustomWidgetFactory;
|
|
451
|
+
|
|
452
|
+
export { AssetImage, BASE_CSS, BASIC_COMPONENTS, BuilderContext, type BuilderContextValue, BuilderFooter, BuilderHeader, BuilderPage, BuilderPageView, BuilderProvider, type BuilderProviderProps, BuilderRenderer, type BuilderRendererProps, BuilderSlot, CUSTOM_WIDGET_CONTAINMENT, CompositeWidget, type CompositeWidgetProps, type CustomWidgetFactory, type DataMap, type DataSourceResolver, type EditModeHooks, type LinkTargetProvider, type LoadedPage, type LoadedPart, type LoadedRedirect, type LoadedSite, MAX_RENDERED_NODES, NodeWrapper, type PackDataSource, type PackWidget, RenderBudget, type RenderWarning, type RendererRegistry, type RendererRegistryOptions, type ResolveContext, RichText, type SlotPoint, TemplateWidget, type TemplateWidgetProps, type WidgetPack, type WidgetRenderProps, WidgetStyle, basicPack, bindingKey, bindingsOf, collectBindings, compileResponsiveCss, createRendererRegistry, cssValue, customWidgetFactory, embedSrc, fitsBudget, isFrozenAsset, parseRichText, parseVideoUrl, pickLocale, resolveBindings, useBuilder, validateRender };
|