@usethrottle/builder-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.
- package/CLAUDE.md +178 -0
- package/dist/bundle-x5Vxd-xE.d.cts +136 -0
- package/dist/bundle-x5Vxd-xE.d.ts +136 -0
- package/dist/chunk-DRQNR5GN.js +1929 -0
- package/dist/chunk-RWDLDDSF.cjs +1929 -0
- package/dist/index.cjs +2315 -0
- package/dist/index.d.cts +446 -0
- package/dist/index.d.ts +446 -0
- package/dist/index.js +2318 -0
- package/dist/next.cjs +95 -0
- package/dist/next.d.cts +41 -0
- package/dist/next.d.ts +41 -0
- package/dist/next.js +95 -0
- package/dist/server.cjs +74 -0
- package/dist/server.d.cts +59 -0
- package/dist/server.d.ts +59 -0
- package/dist/server.js +74 -0
- package/package.json +95 -3
- package/README.md +0 -3
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# @usethrottle/builder-react
|
|
2
|
+
|
|
3
|
+
Renders a published Throttle Builder page document as React in a merchant's
|
|
4
|
+
store, and gives the store its header, footer, slots and site design.
|
|
5
|
+
`"private": true` in `package.json` keeps release-publish from publishing
|
|
6
|
+
`0.0.0`; the release task (Task 16) removes it together with adding the
|
|
7
|
+
changeset. There is no changeset on this branch on purpose.
|
|
8
|
+
|
|
9
|
+
Dependency direction: `@usethrottle/ui` <- this package <- `storefront-react/builder`;
|
|
10
|
+
`builder-schema` <- `builder` <- this package. Nothing in `ui` or the storefront
|
|
11
|
+
core imports this package.
|
|
12
|
+
|
|
13
|
+
## Entries
|
|
14
|
+
|
|
15
|
+
| Entry | Directive | Holds |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `.` | `"use client"` banner on the whole output | `BuilderRenderer`, `compileResponsiveCss`, `BuilderProvider`, `BuilderHeader`, `BuilderFooter`, `BuilderSlot`, `BuilderPage`, `BuilderPageView`, `AssetImage`, `WidgetStyle`, registry, data helpers, types, `BuilderUnavailableError` (re-exported from `@usethrottle/builder`, never redefined) |
|
|
18
|
+
| `./server` | none | `loadSite`, `loadBuilderPage`, `builderSitemap`, `getBundle` |
|
|
19
|
+
| `./next` | none | `createBuilderPage` -> `{ Page, generateMetadata }` |
|
|
20
|
+
|
|
21
|
+
esbuild cannot keep a per-module directive in a bundle, so the client entry is
|
|
22
|
+
one bundle with the directive on the output. `./next` holds only a *reference* to
|
|
23
|
+
`BuilderPageView`: it imports `@usethrottle/builder-react` by name (kept external
|
|
24
|
+
by `tsup.config.ts`, aliased to `src/index.ts` in vitest and in `tsconfig` paths).
|
|
25
|
+
|
|
26
|
+
## The flow in a store
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
// app/layout.tsx (server): one read for the request
|
|
30
|
+
const site = await loadSite({ builderKey, locale, slots: ['product.above', 'product.below', 'shop.above', 'shop.below'], packs });
|
|
31
|
+
// a client module of the store, where the packs are created
|
|
32
|
+
<BuilderProvider builderKey={builderKey} packs={packs} site={site}>
|
|
33
|
+
<BuilderHeader />{children}<BuilderFooter />
|
|
34
|
+
</BuilderProvider>
|
|
35
|
+
// app/pages/[handle]/page.tsx
|
|
36
|
+
const { Page, generateMetadata } = createBuilderPage({ fromParams: 'handle', builderKey, packs });
|
|
37
|
+
export default Page;
|
|
38
|
+
export { generateMetadata };
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`BuilderProvider` is a client component: a pack holds components and functions,
|
|
42
|
+
which a server component cannot pass down, so the store creates its packs in a
|
|
43
|
+
client module. `site` is plain data (what `loadSite` returned).
|
|
44
|
+
|
|
45
|
+
## Rules (do not break)
|
|
46
|
+
|
|
47
|
+
- **No time-based revalidation, ever.** Every read goes through the
|
|
48
|
+
`@usethrottle/builder` client, which is `until-changed`. This package never
|
|
49
|
+
calls `revalidatePath`, `revalidateTag` or `unstable_cache`, and sets no
|
|
50
|
+
`revalidate` time; `server.test.ts` scans `src` for them.
|
|
51
|
+
- **One read per request (R8).** `getBundle` shares one `client.bundle()` per
|
|
52
|
+
request through `react.cache`: an ask that an earlier read covers (same client
|
|
53
|
+
and locale, same page or none, every slot) reuses it, and asks in the same tick
|
|
54
|
+
merge into one read. A read that nothing covers is a second read: a layout does
|
|
55
|
+
not know the page, so on a Builder page route the layout read and the page read
|
|
56
|
+
are two reads per request unless `loadSite({ page })` names the page (a provider
|
|
57
|
+
placed in the route can). Metadata and page share one.
|
|
58
|
+
- **The Builder being down never blanks the store.** `loadSite` answers
|
|
59
|
+
`{ status: 'unavailable' }` for a `BuilderUnavailableError` with no last good
|
|
60
|
+
answer (logged once per process); header, footer and slots then render nothing
|
|
61
|
+
and the provider fills no design. A page throws `BuilderUnavailableError` and
|
|
62
|
+
lets the store's error boundary answer. A part or slot whose widget throws is
|
|
63
|
+
caught by `PartBoundary` and renders nothing.
|
|
64
|
+
- **Media `src` is on the media origin.** `loadSite({ mediaOrigin })` puts it in
|
|
65
|
+
`LoadedSite`; the provider, the renderer (`mediaOrigin` prop, `WidgetRenderProps.mediaOrigin`),
|
|
66
|
+
`AssetImage`, the background images in `css-compiler.ts` and the logo, favicon and
|
|
67
|
+
share image all use `safeUrl(url, 'src', { mediaOrigin })`: https, exactly that
|
|
68
|
+
origin. No origin means no image. Widgets pass `mediaOrigin` to `AssetImage`.
|
|
69
|
+
- **Redirects are site paths** (`safe-path.ts` `sitePath`): one leading `/` then not
|
|
70
|
+
`/` or `\`, no control character or whitespace, and still a path once decoded.
|
|
71
|
+
- **Own properties only** (`Object.hasOwn`) for every lookup keyed by document or
|
|
72
|
+
settings data (assets, slots, locales, data keys, alignments, fonts).
|
|
73
|
+
- **Anchors** are re-checked against `ANCHOR_RE` in `NodeWrapper`; a `resolveLink`
|
|
74
|
+
result is re-checked with `safeUrl`.
|
|
75
|
+
- **A part that throws during SSR** is caught by the `Suspense` inside its
|
|
76
|
+
`PartBoundary` (boundaries do not catch on the server; `ssr.test.tsx`).
|
|
77
|
+
- **Never raw HTML.** No `dangerouslySetInnerHTML`, `innerHTML` and the like in
|
|
78
|
+
`src` (`security.test.tsx` scans for them). Template values go through React.
|
|
79
|
+
Widget CSS goes in only through `WidgetStyle`, as the text of a `<style>`.
|
|
80
|
+
- **Every custom widget is boxed in** by `NodeWrapper`: inline
|
|
81
|
+
`contain: layout paint; isolation: isolate; overflow: clip` and `data-b-w`
|
|
82
|
+
(the scope of its sanitised CSS, `[data-b-w="<type>"] .x`, so its CSS can never
|
|
83
|
+
restyle the box). `containment.test.ts` proves in Chromium, at the three
|
|
84
|
+
breakpoints, that a widget using `transform: translate(-9999px) scale(50)` or
|
|
85
|
+
negative margins cannot paint over or take clicks from a sibling button, with a
|
|
86
|
+
negative control that fails without the box.
|
|
87
|
+
- **Node cap.** `RenderBudget` / `MAX_RENDERED_NODES` equal `MAX_TEMPLATE_WEIGHT`
|
|
88
|
+
(20 000). The renderer hands a fresh budget to each custom widget; the template
|
|
89
|
+
interpreter (`src/custom/`) calls `fitsBudget(ast)` first and `budget.take()` per node.
|
|
90
|
+
- **Custom widgets (`src/custom/`).** `customWidgetFactory` (the registry's default
|
|
91
|
+
`CustomWidgetFactory`, now `(snapshot, registry)`) builds the component of a frozen
|
|
92
|
+
`custom.*` widget, or null (an empty box) for a snapshot that does not pass the validator. A
|
|
93
|
+
`status: 'disabled'` snapshot gets a component that renders nothing in a store and a
|
|
94
|
+
placeholder in `editMode`.
|
|
95
|
+
- *Template:* only the snapshot's `template` source is read (an `ast` field is
|
|
96
|
+
ignored). `compileTemplate` runs `parseTemplate`, `validateTemplate` against the
|
|
97
|
+
snapshot's settings, data inputs and the registry's sources, `fitsBudget` and
|
|
98
|
+
`sanitizeWidgetCss` once per snapshot and registry; any failure refuses the whole
|
|
99
|
+
widget. `interpreter.tsx` is a switch over the closed AST that returns React
|
|
100
|
+
elements: own-property lookups that refuse `__proto__`, `constructor`, `prototype`
|
|
101
|
+
and inherited names and never read into arrays, `#each` at most 100 items,
|
|
102
|
+
`budget.take()` per node, a 1 000 000 character cap on text, element/attribute/class/
|
|
103
|
+
role allow-lists re-checked, `safeUrl` on every `href` and `src`. CSS is `WidgetStyle`
|
|
104
|
+
text inside the containment box.
|
|
105
|
+
- *Composite:* the body goes through `pageDocumentSchema` (as the validator wraps it),
|
|
106
|
+
each binding writes the setting's prepared value into the inner prop (checked with
|
|
107
|
+
`validateSettingValue`, same control only), data inputs reach inner nodes as
|
|
108
|
+
`composite.<name>` data, inner anchors are dropped, another composite in the body is
|
|
109
|
+
cut, and the inner template weights are taken from the widget's budget. Inner nodes
|
|
110
|
+
render with `BuilderRenderer` and the same registry, each node under an id hashed from
|
|
111
|
+
the composite's node id (so `data-b-id` is unique per instance). Links in a body resolve
|
|
112
|
+
through `WidgetRenderProps.resolveLink` (the page's resolver), and the inner renderer
|
|
113
|
+
runs `safeUrl` on the result.
|
|
114
|
+
- Both render inside `PartBoundary` + `Suspense`, so a throw (browser or SSR) blanks
|
|
115
|
+
only that widget.
|
|
116
|
+
- **The renderer is a pure function of its props**: no state, effects or
|
|
117
|
+
context, so it renders the same in a server component, in SSR of a client
|
|
118
|
+
tree and in the editor canvas. Interactivity (the perShopper data after mount,
|
|
119
|
+
the part boundary, the page read) is in `part-view.tsx`, `page.tsx`, `shopper-data.ts`.
|
|
120
|
+
- **perShopper data is never in SSR.** `loadBuilderPage`/`loadSite` resolve
|
|
121
|
+
`staticDataFor` (non-perShopper) only; `useResolvedData` resolves perShopper
|
|
122
|
+
sources in the browser after mount.
|
|
123
|
+
- **Settings reach CSS as custom properties only.** A `css` setting becomes
|
|
124
|
+
`--b-<key>` (`--w-<key>` for a custom widget, what its sanitised CSS reads) in
|
|
125
|
+
rules scoped by `[data-b-id="<id>"]`: desktop in a plain rule, tablet and phone
|
|
126
|
+
changes in `@media (max-width:1024px)` and `@media (max-width:767px)`. Layout
|
|
127
|
+
of sections and columns is `--tb-*`. A value is built from a validated token,
|
|
128
|
+
number, colour or enum, and dropped when it holds anything outside
|
|
129
|
+
`[A-Za-z0-9#%.,()-+*/_: ]`. Every widget stylesheet must read
|
|
130
|
+
`var(--b-<key>, <default>)` (defaults are emitted for desktop too).
|
|
131
|
+
- **Markup variants.** A `markup` setting that differs per device renders each
|
|
132
|
+
distinct variant once with `tb-v` and `tb-only-desktop|tablet|phone` classes;
|
|
133
|
+
a `css` setting never splits a widget. Only the first variant carries the anchor id.
|
|
134
|
+
- **Styles** are `@layer throttle` with the `tb-` prefix (`styles.ts`), emitted
|
|
135
|
+
once through `<style href="tb-base" precedence="throttle">` (React 19 hoists
|
|
136
|
+
and dedupes it). The host defines `--tb-color-<token>` and `--tb-scale`;
|
|
137
|
+
`BuilderProvider` does, from the site theme. Preset tokens apply while
|
|
138
|
+
`theme.customized` is false.
|
|
139
|
+
- **Bundle size** of the client entry, minified and gzipped, dependencies
|
|
140
|
+
external: at most 35 KB (`pnpm --filter @usethrottle/builder-react size`, the
|
|
141
|
+
limit is in `size-limit.json`).
|
|
142
|
+
|
|
143
|
+
## Shared files (Task 12 owns them; Tasks 13 and 14 edit marked sections only)
|
|
144
|
+
|
|
145
|
+
- `src/index.ts`: `// <task-13>` ... `// </task-13>`, `// <task-14>` ... `// </task-14>`.
|
|
146
|
+
- `src/registry.ts`: `BUILTIN_PACKS` (`basicPack` goes in `<task-13>`) and
|
|
147
|
+
`DEFAULT_CUSTOM_WIDGET` (the template and composite runtime goes in `<task-14>`).
|
|
148
|
+
|
|
149
|
+
## Basic widgets (`src/basics`, Task 13)
|
|
150
|
+
|
|
151
|
+
`basicPack` (`id: 'basic'`, v1 each) pairs builder-schema's `BASIC_WIDGET_DEFINITIONS`
|
|
152
|
+
with a component; it is in `BUILTIN_PACKS`, so every renderer has it and a pack
|
|
153
|
+
cannot replace a `basic.*` type. Definitions are never re-declared here.
|
|
154
|
+
|
|
155
|
+
- **Site parts** (`logo`, `menu`, `announcement`, `copyright`) read `useSiteDesign()`
|
|
156
|
+
(`@usethrottle/ui`), which `BuilderProvider` fills. Without one they render nothing
|
|
157
|
+
(a hint in the editor). Menus are looked up by own name; every href is `safeUrl` again.
|
|
158
|
+
- **Images** (`basic.image`, `basic.logo`) are `https` on `mediaOrigin` only (fail-closed).
|
|
159
|
+
- **Rich text** (`basic.text`): `basics/rich-text.tsx` tokenizes the string and builds React
|
|
160
|
+
elements (p, br, strong, em, u, s, a, ul, ol, li, h2-h4, blockquote, code); `href` only
|
|
161
|
+
on `a`, through `safeUrl`. Never an HTML string. Word paste reduces to p/strong/em/a.
|
|
162
|
+
- **Video**: YouTube/Vimeo only (`parseVideoUrl`), poster drawn locally, the iframe
|
|
163
|
+
(`youtube-nocookie.com` / `player.vimeo.com`, built from the id) loads on click.
|
|
164
|
+
- **`select` settings that need a mapping** (image radius/fit, divider style, video ratio)
|
|
165
|
+
cannot be read from the compiled `--b-<key>: <option>`, so `enumCss` emits `--bx-<key>`
|
|
166
|
+
per device from a closed table. Other settings are read as `var(--b-<key>, default)`.
|
|
167
|
+
- Stylesheet: `basics/styles.ts`, `@layer throttle`, `tb-b-*`, hoisted like the base CSS.
|
|
168
|
+
- `pnpm --filter @usethrottle/builder-react dev` serves `playground/main.tsx` (every basic,
|
|
169
|
+
port 5192) for looking at 390, 768 and 1280 px. Media there is a fake https origin that
|
|
170
|
+
the browser check answers itself.
|
|
171
|
+
|
|
172
|
+
## Tests
|
|
173
|
+
|
|
174
|
+
`pnpm --filter @usethrottle/builder-react test` (build `ui`, `builder-schema` and
|
|
175
|
+
`builder` first: they are read from `dist`). `containment.test.ts` and
|
|
176
|
+
`layout.test.ts` launch Chromium through `playwright`
|
|
177
|
+
(`pnpm exec playwright install chromium`). Tests stand in for a request with
|
|
178
|
+
`__tests__/request-cache.ts` (a `react.cache` that memoizes per `newRequest()`).
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import { ComponentType, ReactNode } from 'react';
|
|
2
|
+
import { WidgetDefinition, WidgetNode, SettingValue, DataSourceDescriptor, PageDocument, FrozenAsset } from '@usethrottle/builder-schema';
|
|
3
|
+
import { BuilderClient, BuilderBundle } from '@usethrottle/builder';
|
|
4
|
+
|
|
5
|
+
/** A count of rendered nodes with a ceiling. One per custom widget render. */
|
|
6
|
+
declare class RenderBudget {
|
|
7
|
+
readonly limit: number;
|
|
8
|
+
private spent;
|
|
9
|
+
constructor(limit?: number);
|
|
10
|
+
/** Takes `count` nodes. False, and nothing taken, when that would pass the limit. */
|
|
11
|
+
take(count?: number): boolean;
|
|
12
|
+
get used(): number;
|
|
13
|
+
get exhausted(): boolean;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Resolved data by binding key (`bindingKey`), plus `context.*` entries a slot supplies. */
|
|
17
|
+
type DataMap = Record<string, unknown>;
|
|
18
|
+
type WidgetRenderProps = {
|
|
19
|
+
node: WidgetNode;
|
|
20
|
+
/** The node's settings at this variant, defaults filled, translatable text resolved, image ids replaced by their frozen asset. */
|
|
21
|
+
props: Record<string, SettingValue>;
|
|
22
|
+
/** Resolved data by the widget's named inputs. Absent until a perShopper source has resolved in the browser. */
|
|
23
|
+
data: Record<string, unknown>;
|
|
24
|
+
editMode: boolean;
|
|
25
|
+
locale: string;
|
|
26
|
+
/** The only origin a media `src` may be on; pass it to `AssetImage`. */
|
|
27
|
+
mediaOrigin: string;
|
|
28
|
+
/** In the editor only: the inline editor of one text setting of this node, or null. */
|
|
29
|
+
inlineEdit?: ((key: string) => ReactNode | null) | undefined;
|
|
30
|
+
/** The href of a link target (page, catalog kinds), or null. Callers still check the result with `safeUrl`. */
|
|
31
|
+
resolveLink?: ((target: {
|
|
32
|
+
kind: string;
|
|
33
|
+
[key: string]: unknown;
|
|
34
|
+
}) => string | null) | undefined;
|
|
35
|
+
/** Custom widgets only: the node budget of this render (`MAX_RENDERED_NODES`). */
|
|
36
|
+
budget?: RenderBudget | undefined;
|
|
37
|
+
};
|
|
38
|
+
type ResolveContext = {
|
|
39
|
+
locale: string;
|
|
40
|
+
/** The store's main currency, when the site knows it. Never defaulted here. */
|
|
41
|
+
currency?: string | undefined;
|
|
42
|
+
preview: boolean;
|
|
43
|
+
/** The slot context (`{ product }` or `{ listing }`) for `context.*` bindings. */
|
|
44
|
+
context?: unknown;
|
|
45
|
+
signal: AbortSignal;
|
|
46
|
+
};
|
|
47
|
+
type DataSourceResolver = (params: Record<string, SettingValue>, ctx: ResolveContext) => Promise<unknown>;
|
|
48
|
+
type PackDataSource = DataSourceDescriptor & {
|
|
49
|
+
resolve: DataSourceResolver;
|
|
50
|
+
};
|
|
51
|
+
type PackWidget = WidgetDefinition & {
|
|
52
|
+
Component: ComponentType<WidgetRenderProps>;
|
|
53
|
+
};
|
|
54
|
+
/** The pickers and href resolution of a pack's link targets (catalog: category, collection, product, search). */
|
|
55
|
+
type LinkTargetProvider = {
|
|
56
|
+
/** The href of a menu target the pack owns, or null when it cannot resolve one. */
|
|
57
|
+
resolve(target: {
|
|
58
|
+
kind: string;
|
|
59
|
+
[key: string]: unknown;
|
|
60
|
+
}): string | null;
|
|
61
|
+
};
|
|
62
|
+
type SlotPoint = {
|
|
63
|
+
name: string;
|
|
64
|
+
context: 'product' | 'listing' | 'none';
|
|
65
|
+
};
|
|
66
|
+
/** A set of widgets and data sources (spec §9.4). `basic` ships with this package. */
|
|
67
|
+
type WidgetPack = {
|
|
68
|
+
id: string;
|
|
69
|
+
/** The npm version that ships it. */
|
|
70
|
+
version: string;
|
|
71
|
+
widgets: PackWidget[];
|
|
72
|
+
dataSources: PackDataSource[];
|
|
73
|
+
linkTargets?: LinkTargetProvider;
|
|
74
|
+
slots?: SlotPoint[];
|
|
75
|
+
};
|
|
76
|
+
/** A page document as the store reads it (a published snapshot). */
|
|
77
|
+
type PageAssets = Record<string, FrozenAsset>;
|
|
78
|
+
type LoadedPage = {
|
|
79
|
+
kind: 'page';
|
|
80
|
+
slug: string;
|
|
81
|
+
title: string;
|
|
82
|
+
path: string;
|
|
83
|
+
generation: number;
|
|
84
|
+
document: PageDocument;
|
|
85
|
+
assets: PageAssets;
|
|
86
|
+
/** Data of every non-perShopper binding, resolved on the server. Never holds perShopper data. */
|
|
87
|
+
initialData: DataMap;
|
|
88
|
+
/** The page's other fields as the read API sent them (seo, description, ...). */
|
|
89
|
+
meta: Record<string, unknown>;
|
|
90
|
+
};
|
|
91
|
+
type LoadedRedirect = {
|
|
92
|
+
kind: 'redirect';
|
|
93
|
+
redirectTo: string;
|
|
94
|
+
};
|
|
95
|
+
/** What a site part or a slot holds once the server has read it. */
|
|
96
|
+
type LoadedPart = {
|
|
97
|
+
document: PageDocument;
|
|
98
|
+
assets: PageAssets;
|
|
99
|
+
initialData: DataMap;
|
|
100
|
+
};
|
|
101
|
+
/**
|
|
102
|
+
* The store's site design, read once per request. `unavailable` means the
|
|
103
|
+
* Builder could not answer and there is no last good answer: every part then
|
|
104
|
+
* renders nothing (ruling R8) and the catalog's own design takes over.
|
|
105
|
+
*/
|
|
106
|
+
type LoadedSite = {
|
|
107
|
+
status: 'ok';
|
|
108
|
+
locale: string;
|
|
109
|
+
generation: number;
|
|
110
|
+
siteVersion: number;
|
|
111
|
+
/** The origin media files must be on (https). Images from anywhere else are refused. */
|
|
112
|
+
mediaOrigin: string;
|
|
113
|
+
/** Site settings resolved for the locale (localized values are strings). */
|
|
114
|
+
settings: Record<string, unknown>;
|
|
115
|
+
header: LoadedPart;
|
|
116
|
+
footer: LoadedPart;
|
|
117
|
+
slots: Record<string, LoadedPart>;
|
|
118
|
+
} | {
|
|
119
|
+
status: 'unavailable';
|
|
120
|
+
locale: string;
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
type BundleAsk = {
|
|
124
|
+
client: BuilderClient;
|
|
125
|
+
locale: string;
|
|
126
|
+
page?: string | undefined;
|
|
127
|
+
slots?: readonly string[] | undefined;
|
|
128
|
+
};
|
|
129
|
+
/** The bundle for an ask, shared per request. It rejects exactly as `client.bundle` does. */
|
|
130
|
+
declare function getBundle(ask: BundleAsk): Promise<BuilderBundle>;
|
|
131
|
+
type ClientOptions = {
|
|
132
|
+
client?: BuilderClient | undefined;
|
|
133
|
+
builderKey?: string | undefined;
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
export { type BundleAsk as B, type ClientOptions as C, type LoadedPage as L, type WidgetPack as W, type LoadedRedirect as a, type LoadedSite as b, getBundle as g };
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import { ComponentType, ReactNode } from 'react';
|
|
2
|
+
import { WidgetDefinition, WidgetNode, SettingValue, DataSourceDescriptor, PageDocument, FrozenAsset } from '@usethrottle/builder-schema';
|
|
3
|
+
import { BuilderClient, BuilderBundle } from '@usethrottle/builder';
|
|
4
|
+
|
|
5
|
+
/** A count of rendered nodes with a ceiling. One per custom widget render. */
|
|
6
|
+
declare class RenderBudget {
|
|
7
|
+
readonly limit: number;
|
|
8
|
+
private spent;
|
|
9
|
+
constructor(limit?: number);
|
|
10
|
+
/** Takes `count` nodes. False, and nothing taken, when that would pass the limit. */
|
|
11
|
+
take(count?: number): boolean;
|
|
12
|
+
get used(): number;
|
|
13
|
+
get exhausted(): boolean;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Resolved data by binding key (`bindingKey`), plus `context.*` entries a slot supplies. */
|
|
17
|
+
type DataMap = Record<string, unknown>;
|
|
18
|
+
type WidgetRenderProps = {
|
|
19
|
+
node: WidgetNode;
|
|
20
|
+
/** The node's settings at this variant, defaults filled, translatable text resolved, image ids replaced by their frozen asset. */
|
|
21
|
+
props: Record<string, SettingValue>;
|
|
22
|
+
/** Resolved data by the widget's named inputs. Absent until a perShopper source has resolved in the browser. */
|
|
23
|
+
data: Record<string, unknown>;
|
|
24
|
+
editMode: boolean;
|
|
25
|
+
locale: string;
|
|
26
|
+
/** The only origin a media `src` may be on; pass it to `AssetImage`. */
|
|
27
|
+
mediaOrigin: string;
|
|
28
|
+
/** In the editor only: the inline editor of one text setting of this node, or null. */
|
|
29
|
+
inlineEdit?: ((key: string) => ReactNode | null) | undefined;
|
|
30
|
+
/** The href of a link target (page, catalog kinds), or null. Callers still check the result with `safeUrl`. */
|
|
31
|
+
resolveLink?: ((target: {
|
|
32
|
+
kind: string;
|
|
33
|
+
[key: string]: unknown;
|
|
34
|
+
}) => string | null) | undefined;
|
|
35
|
+
/** Custom widgets only: the node budget of this render (`MAX_RENDERED_NODES`). */
|
|
36
|
+
budget?: RenderBudget | undefined;
|
|
37
|
+
};
|
|
38
|
+
type ResolveContext = {
|
|
39
|
+
locale: string;
|
|
40
|
+
/** The store's main currency, when the site knows it. Never defaulted here. */
|
|
41
|
+
currency?: string | undefined;
|
|
42
|
+
preview: boolean;
|
|
43
|
+
/** The slot context (`{ product }` or `{ listing }`) for `context.*` bindings. */
|
|
44
|
+
context?: unknown;
|
|
45
|
+
signal: AbortSignal;
|
|
46
|
+
};
|
|
47
|
+
type DataSourceResolver = (params: Record<string, SettingValue>, ctx: ResolveContext) => Promise<unknown>;
|
|
48
|
+
type PackDataSource = DataSourceDescriptor & {
|
|
49
|
+
resolve: DataSourceResolver;
|
|
50
|
+
};
|
|
51
|
+
type PackWidget = WidgetDefinition & {
|
|
52
|
+
Component: ComponentType<WidgetRenderProps>;
|
|
53
|
+
};
|
|
54
|
+
/** The pickers and href resolution of a pack's link targets (catalog: category, collection, product, search). */
|
|
55
|
+
type LinkTargetProvider = {
|
|
56
|
+
/** The href of a menu target the pack owns, or null when it cannot resolve one. */
|
|
57
|
+
resolve(target: {
|
|
58
|
+
kind: string;
|
|
59
|
+
[key: string]: unknown;
|
|
60
|
+
}): string | null;
|
|
61
|
+
};
|
|
62
|
+
type SlotPoint = {
|
|
63
|
+
name: string;
|
|
64
|
+
context: 'product' | 'listing' | 'none';
|
|
65
|
+
};
|
|
66
|
+
/** A set of widgets and data sources (spec §9.4). `basic` ships with this package. */
|
|
67
|
+
type WidgetPack = {
|
|
68
|
+
id: string;
|
|
69
|
+
/** The npm version that ships it. */
|
|
70
|
+
version: string;
|
|
71
|
+
widgets: PackWidget[];
|
|
72
|
+
dataSources: PackDataSource[];
|
|
73
|
+
linkTargets?: LinkTargetProvider;
|
|
74
|
+
slots?: SlotPoint[];
|
|
75
|
+
};
|
|
76
|
+
/** A page document as the store reads it (a published snapshot). */
|
|
77
|
+
type PageAssets = Record<string, FrozenAsset>;
|
|
78
|
+
type LoadedPage = {
|
|
79
|
+
kind: 'page';
|
|
80
|
+
slug: string;
|
|
81
|
+
title: string;
|
|
82
|
+
path: string;
|
|
83
|
+
generation: number;
|
|
84
|
+
document: PageDocument;
|
|
85
|
+
assets: PageAssets;
|
|
86
|
+
/** Data of every non-perShopper binding, resolved on the server. Never holds perShopper data. */
|
|
87
|
+
initialData: DataMap;
|
|
88
|
+
/** The page's other fields as the read API sent them (seo, description, ...). */
|
|
89
|
+
meta: Record<string, unknown>;
|
|
90
|
+
};
|
|
91
|
+
type LoadedRedirect = {
|
|
92
|
+
kind: 'redirect';
|
|
93
|
+
redirectTo: string;
|
|
94
|
+
};
|
|
95
|
+
/** What a site part or a slot holds once the server has read it. */
|
|
96
|
+
type LoadedPart = {
|
|
97
|
+
document: PageDocument;
|
|
98
|
+
assets: PageAssets;
|
|
99
|
+
initialData: DataMap;
|
|
100
|
+
};
|
|
101
|
+
/**
|
|
102
|
+
* The store's site design, read once per request. `unavailable` means the
|
|
103
|
+
* Builder could not answer and there is no last good answer: every part then
|
|
104
|
+
* renders nothing (ruling R8) and the catalog's own design takes over.
|
|
105
|
+
*/
|
|
106
|
+
type LoadedSite = {
|
|
107
|
+
status: 'ok';
|
|
108
|
+
locale: string;
|
|
109
|
+
generation: number;
|
|
110
|
+
siteVersion: number;
|
|
111
|
+
/** The origin media files must be on (https). Images from anywhere else are refused. */
|
|
112
|
+
mediaOrigin: string;
|
|
113
|
+
/** Site settings resolved for the locale (localized values are strings). */
|
|
114
|
+
settings: Record<string, unknown>;
|
|
115
|
+
header: LoadedPart;
|
|
116
|
+
footer: LoadedPart;
|
|
117
|
+
slots: Record<string, LoadedPart>;
|
|
118
|
+
} | {
|
|
119
|
+
status: 'unavailable';
|
|
120
|
+
locale: string;
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
type BundleAsk = {
|
|
124
|
+
client: BuilderClient;
|
|
125
|
+
locale: string;
|
|
126
|
+
page?: string | undefined;
|
|
127
|
+
slots?: readonly string[] | undefined;
|
|
128
|
+
};
|
|
129
|
+
/** The bundle for an ask, shared per request. It rejects exactly as `client.bundle` does. */
|
|
130
|
+
declare function getBundle(ask: BundleAsk): Promise<BuilderBundle>;
|
|
131
|
+
type ClientOptions = {
|
|
132
|
+
client?: BuilderClient | undefined;
|
|
133
|
+
builderKey?: string | undefined;
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
export { type BundleAsk as B, type ClientOptions as C, type LoadedPage as L, type WidgetPack as W, type LoadedRedirect as a, type LoadedSite as b, getBundle as g };
|