@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.
- package/CLAUDE.md +67 -0
- package/README.md +119 -2
- package/dist/StorefrontProvider-Br4wUHui.d.cts +559 -0
- package/dist/StorefrontProvider-DLEPEjg6.d.ts +559 -0
- package/dist/account/index.cjs +69 -0
- package/dist/account/index.cjs.map +1 -0
- package/dist/account/index.d.cts +23 -0
- package/dist/account/index.d.ts +23 -0
- package/dist/account/index.js +68 -0
- package/dist/account/index.js.map +1 -0
- package/dist/chunk-2LCPIY2P.cjs +16 -0
- package/dist/chunk-2LCPIY2P.cjs.map +1 -0
- package/dist/chunk-3A72UY6T.js +2126 -0
- package/dist/chunk-3A72UY6T.js.map +1 -0
- package/dist/chunk-3JMIVAHN.js +185 -0
- package/dist/chunk-3JMIVAHN.js.map +1 -0
- package/dist/chunk-4J6AGWNC.cjs +24 -0
- package/dist/chunk-4J6AGWNC.cjs.map +1 -0
- package/dist/chunk-4U6MYDZV.js +17 -0
- package/dist/chunk-4U6MYDZV.js.map +1 -0
- package/dist/chunk-66HDJVPS.js +22 -0
- package/dist/chunk-66HDJVPS.js.map +1 -0
- package/dist/chunk-6X2OZSNV.cjs +83 -0
- package/dist/chunk-6X2OZSNV.cjs.map +1 -0
- package/dist/chunk-6ZMMZ245.cjs +2127 -0
- package/dist/chunk-6ZMMZ245.cjs.map +1 -0
- package/dist/chunk-7R37CVAB.cjs +23 -0
- package/dist/chunk-7R37CVAB.cjs.map +1 -0
- package/dist/chunk-A3IFWQUV.js +368 -0
- package/dist/chunk-A3IFWQUV.js.map +1 -0
- package/dist/chunk-AYC2YK4E.cjs +95 -0
- package/dist/chunk-AYC2YK4E.cjs.map +1 -0
- package/dist/chunk-AZV5U7YB.cjs +18 -0
- package/dist/chunk-AZV5U7YB.cjs.map +1 -0
- package/dist/chunk-CE2SKNQP.cjs +71 -0
- package/dist/chunk-CE2SKNQP.cjs.map +1 -0
- package/dist/chunk-D76CRI4X.js +2175 -0
- package/dist/chunk-D76CRI4X.js.map +1 -0
- package/dist/chunk-DOAII637.cjs +186 -0
- package/dist/chunk-DOAII637.cjs.map +1 -0
- package/dist/chunk-DYHHAOMG.cjs +17 -0
- package/dist/chunk-DYHHAOMG.cjs.map +1 -0
- package/dist/chunk-EYSVU5SJ.js +196 -0
- package/dist/chunk-EYSVU5SJ.js.map +1 -0
- package/dist/chunk-HSUUDZWS.js +37 -0
- package/dist/chunk-HSUUDZWS.js.map +1 -0
- package/dist/chunk-HZ6VEN6Q.cjs +101 -0
- package/dist/chunk-HZ6VEN6Q.cjs.map +1 -0
- package/dist/chunk-IJOTLGPT.js +16 -0
- package/dist/chunk-IJOTLGPT.js.map +1 -0
- package/dist/chunk-ISDATHVC.js +219 -0
- package/dist/chunk-ISDATHVC.js.map +1 -0
- package/dist/chunk-LW2A6USV.js +100 -0
- package/dist/chunk-LW2A6USV.js.map +1 -0
- package/dist/chunk-M4YXSLRG.cjs +369 -0
- package/dist/chunk-M4YXSLRG.cjs.map +1 -0
- package/dist/chunk-NDUEJJLP.cjs +2176 -0
- package/dist/chunk-NDUEJJLP.cjs.map +1 -0
- package/dist/chunk-NNE4FYRT.js +820 -0
- package/dist/chunk-NNE4FYRT.js.map +1 -0
- package/dist/chunk-NW3EFHY2.js +15 -0
- package/dist/chunk-NW3EFHY2.js.map +1 -0
- package/dist/chunk-NZRUQUN5.js +167 -0
- package/dist/chunk-NZRUQUN5.js.map +1 -0
- package/dist/chunk-P6HHE57S.cjs +38 -0
- package/dist/chunk-P6HHE57S.cjs.map +1 -0
- package/dist/chunk-PHY7AY27.cjs +197 -0
- package/dist/chunk-PHY7AY27.cjs.map +1 -0
- package/dist/chunk-PNJOFFTL.cjs +128 -0
- package/dist/chunk-PNJOFFTL.cjs.map +1 -0
- package/dist/chunk-PXZQ4ONA.js +127 -0
- package/dist/chunk-PXZQ4ONA.js.map +1 -0
- package/dist/chunk-Q3VTUBPP.js +82 -0
- package/dist/chunk-Q3VTUBPP.js.map +1 -0
- package/dist/chunk-Q3XFD5UI.js +45 -0
- package/dist/chunk-Q3XFD5UI.js.map +1 -0
- package/dist/chunk-QM7KTT7F.js +94 -0
- package/dist/chunk-QM7KTT7F.js.map +1 -0
- package/dist/chunk-RLWZOLXL.js +70 -0
- package/dist/chunk-RLWZOLXL.js.map +1 -0
- package/dist/chunk-SV53BRP2.js +23 -0
- package/dist/chunk-SV53BRP2.js.map +1 -0
- package/dist/chunk-VWXJO427.cjs +821 -0
- package/dist/chunk-VWXJO427.cjs.map +1 -0
- package/dist/chunk-WIIOJDHR.cjs +220 -0
- package/dist/chunk-WIIOJDHR.cjs.map +1 -0
- package/dist/chunk-XQHGFWLG.cjs +46 -0
- package/dist/chunk-XQHGFWLG.cjs.map +1 -0
- package/dist/chunk-ZHCXI2ZZ.cjs +168 -0
- package/dist/chunk-ZHCXI2ZZ.cjs.map +1 -0
- package/dist/index-RSj2Rg62.d.cts +8 -0
- package/dist/index-RSj2Rg62.d.ts +8 -0
- package/dist/index.cjs +2829 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1718 -0
- package/dist/index.d.ts +1718 -0
- package/dist/index.js +2828 -0
- package/dist/index.js.map +1 -0
- package/dist/metadata-QhKw-tvz.d.cts +188 -0
- package/dist/metadata-QhKw-tvz.d.ts +188 -0
- package/dist/next/client.cjs +84 -0
- package/dist/next/client.cjs.map +1 -0
- package/dist/next/client.d.cts +40 -0
- package/dist/next/client.d.ts +40 -0
- package/dist/next/client.js +83 -0
- package/dist/next/client.js.map +1 -0
- package/dist/next/index.cjs +1090 -0
- package/dist/next/index.cjs.map +1 -0
- package/dist/next/index.d.cts +218 -0
- package/dist/next/index.d.ts +218 -0
- package/dist/next/index.js +1049 -0
- package/dist/next/index.js.map +1 -0
- package/dist/server/index.cjs +994 -0
- package/dist/server/index.cjs.map +1 -0
- package/dist/server/index.d.cts +229 -0
- package/dist/server/index.d.ts +229 -0
- package/dist/server/index.js +951 -0
- package/dist/server/index.js.map +1 -0
- package/dist/styles.css +2111 -0
- package/dist/use-part-DCfFk7kf.d.ts +24 -0
- package/dist/use-part-DgjPBL_O.d.cts +24 -0
- package/package.json +121 -3
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# @usethrottle/storefront-react
|
|
2
|
+
|
|
3
|
+
Settings-driven React storefront components. Built on `@usethrottle/ui` (theme
|
|
4
|
+
core, primitives, preset tokens) and `@usethrottle/catalog` (client, hooks,
|
|
5
|
+
settings types). Build: `pnpm --filter @usethrottle/storefront-react build`;
|
|
6
|
+
test: `pnpm --filter @usethrottle/storefront-react test` (the build-output and
|
|
7
|
+
exports tests read `dist/`, so build first; `pnpm build` is also the typecheck).
|
|
8
|
+
|
|
9
|
+
## Invariants an agent must not break
|
|
10
|
+
|
|
11
|
+
- **`src/index.ts` is complete.** It re-exports every area barrel
|
|
12
|
+
(`./pieces`, `./shop`, ...). An area adds exports to its own barrel, never to
|
|
13
|
+
`index.ts`. The entry stubs (`server`, `next`, `next/client`, `account`) are
|
|
14
|
+
filled by their own tasks.
|
|
15
|
+
- **Server-safe modules stay server-safe.** `settings/*`, `site/{resolve,catalog-adapter,menu}.ts`,
|
|
16
|
+
`theme/*` and `url/routes.ts` are re-exported from `./server`, which has no
|
|
17
|
+
`"use client"` banner. They may import React or `@usethrottle/ui` only as types;
|
|
18
|
+
preset tokens come from `@usethrottle/ui/presets`. `server-safe.test.ts` checks it.
|
|
19
|
+
- **One `CatalogProvider`.** `StorefrontProvider` creates it and forwards the cart wiring
|
|
20
|
+
(`cartStorage`, `customerCart`, `cartUrls`, `throttleBaseUrl`, `throttleCheckoutUrl`); never nest a second
|
|
21
|
+
one. The package and every app that mounts it must resolve one copy of `@usethrottle/catalog`, `react` and
|
|
22
|
+
`next` (`build-output.test.ts` checks the workspace; keep `next` and `@types/node` versions equal, because
|
|
23
|
+
pnpm makes a copy per peer set).
|
|
24
|
+
- **Cost rule.** Nothing revalidates in under 3600 s, search stays `no-store`, no `revalidatePath`.
|
|
25
|
+
`primaryCache: 'no-store'` is the one opt-in live read (the page's own product or collection).
|
|
26
|
+
- **Site-design resolution is R11** (`site/resolve.ts`): theme group is Builder,
|
|
27
|
+
then props, then the catalog adapter, then defaults; every other field is
|
|
28
|
+
Builder, then adapter. A `null` is a value, `undefined` falls through.
|
|
29
|
+
`catalogSiteDesign` is `@deprecated` and goes at Builder M4.
|
|
30
|
+
- **Parts.** An element's attributes come from `usePart(key)`; the key must be in
|
|
31
|
+
its area's `src/parts/<area>.ts` list (`parts-drift.test.tsx`). Class order:
|
|
32
|
+
`tsf-<key>`, `appearance.parts[key]`, `classNames[key]`, `className`.
|
|
33
|
+
- **CSS** lives in `STOREFRONT_STYLES` inside `@layer throttle`: single-class
|
|
34
|
+
selectors, logical properties only, no descendant selector outside a
|
|
35
|
+
`[data-throttle-preset]` rule (`styles.test.ts`). Per-area CSS goes in
|
|
36
|
+
`src/styles/<area>.css.ts`, per-preset CSS in `src/presets/*.css.ts`. A
|
|
37
|
+
template literal: no backticks inside.
|
|
38
|
+
- **Strings** resolve site design, then catalog settings, then `localization`,
|
|
39
|
+
then English (`strings/use-strings.ts`). Add an area's English to
|
|
40
|
+
`src/strings/<area>.ts`.
|
|
41
|
+
- **Part keys are a versioned contract.** `STOREFRONT_PART_KEYS` is documented on the docs site and styled by
|
|
42
|
+
stores; never rename or remove a key in a minor release.
|
|
43
|
+
- **No clock in the markup.** A card ages its `new` badge against the `generatedAt` the server stamped, never
|
|
44
|
+
`Date.now()` or `new Date()`, so server and client render the same markup (no hydration mismatch). The one clock
|
|
45
|
+
read in render (`shownAt` in `use-shop-all.ts`) is a fallback only a client-rendered list uses.
|
|
46
|
+
- **Money only through `@usethrottle/money`.** Show an amount with `formatMoney(minor, currency)` of the record's
|
|
47
|
+
own currency; a decimal for analytics comes from `toDecimalString`. Never `/ 100`, `toFixed(2)`, `Intl` currency
|
|
48
|
+
styles, a literal symbol or a `'USD'` default. Slots receive `minor` and `currency`, never a formatted string.
|
|
49
|
+
- **Sync attributes (R2).** Components emit the `data-*` attributes listed in `SYNC_ATTRIBUTES` (`parts/sync.ts`)
|
|
50
|
+
so a store built on them is sync-testable; do not drop or rename one.
|
|
51
|
+
- **Entry boundaries.** `.` is client (`"use client"`), `./server` has no React and no directive, `./next` is
|
|
52
|
+
server-only (route handlers), `./next/client` is client, `./account` is the only entry that reads
|
|
53
|
+
`@usethrottle/auth`. A module belongs to exactly one side; `server-safe.test.ts` and `build-output.test.ts` check it.
|
|
54
|
+
- **JSDoc on every export.** `src/jsdoc.test.ts` fails when an export of an entry, or a property of a `*Props`
|
|
55
|
+
type, has no JSDoc comment, and when `catalogSiteDesign` loses `@deprecated`. Add the comment with the code.
|
|
56
|
+
Its limits: it reads only symbols declared in this package's `src` (not re-exports such as `getPreviewToken`),
|
|
57
|
+
only types whose export name ends in `Props` (an `*Options`, `*Input` or slot type is checked as an export, not
|
|
58
|
+
property by property), and only that a comment exists (not that it is accurate, or that parameters and returns
|
|
59
|
+
are described). Review those by hand.
|
|
60
|
+
- **Docs.** The developer docs are `apps/web/src/pages/docs/product-catalog/storefront-components/`, and their
|
|
61
|
+
samples are typechecked files in `apps/web/src/data/catalog-snippets/storefront-*` (they import this package's
|
|
62
|
+
`dist/`). A change to a prop, an entry or a cost rule updates both in the same PR.
|
|
63
|
+
- **No Builder imports.** The core talks to a Builder only through
|
|
64
|
+
`useSiteDesign()` and `useSlotOutlet()` from `@usethrottle/ui`.
|
|
65
|
+
- **Tests use the fixture catalog** (`test/fixture-client.ts`), never the live
|
|
66
|
+
one. An area adds fixture files under `test/fixtures/<area>/`; a file with a
|
|
67
|
+
`$route` and `$answer` routes itself.
|
package/README.md
CHANGED
|
@@ -1,3 +1,120 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @usethrottle/storefront-react
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Drop-in, settings-driven React storefront components for Throttle catalogs.
|
|
4
|
+
Components read their display from the catalog's storefront settings and take
|
|
5
|
+
their theme from a preset, so a store needs a few lines, not a design system.
|
|
6
|
+
|
|
7
|
+
Documentation: <https://usethrottle.dev/docs/product-catalog/storefront-components/> (components, theming, Next.js and
|
|
8
|
+
the hosting-cost rules, recipes). A new Next.js store is one command: `npx @usethrottle/create-store my-store`.
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
pnpm add @usethrottle/storefront-react @usethrottle/catalog @usethrottle/money
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
import { StorefrontProvider } from '@usethrottle/storefront-react';
|
|
16
|
+
import '@usethrottle/storefront-react/styles.css'; // or let the provider inject the same sheet
|
|
17
|
+
|
|
18
|
+
export function App({ children }) {
|
|
19
|
+
return (
|
|
20
|
+
<StorefrontProvider catalogKey="pc_pk_..." preset="editorial">
|
|
21
|
+
{children}
|
|
22
|
+
</StorefrontProvider>
|
|
23
|
+
);
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## One catalog, one cart
|
|
28
|
+
|
|
29
|
+
`StorefrontProvider` creates the one `CatalogProvider` of the app, so its
|
|
30
|
+
add-to-cart, cart button and drawer read the same cart as your own `useCart()`.
|
|
31
|
+
Do not mount a second `CatalogProvider` around it. Hand the cart wiring to the
|
|
32
|
+
provider: `cartStorage`, `customerCart`, `cartUrls` (`returnUrl`, `cancelUrl`,
|
|
33
|
+
`storefrontUrl`), `throttleBaseUrl` and `throttleCheckoutUrl` are forwarded as
|
|
34
|
+
they are. `StorefrontNextProvider` takes the same props.
|
|
35
|
+
|
|
36
|
+
Your app and this package must resolve **one copy** of `@usethrottle/catalog`
|
|
37
|
+
(and of `react`): two copies are two React contexts, and each reads a different
|
|
38
|
+
cart. The peer range is `@usethrottle/catalog ^1.4.1`. In a pnpm workspace a
|
|
39
|
+
copy is made per distinct peer set, so keep `next` and `@types/node` at the
|
|
40
|
+
same version everywhere, and check with `pnpm why @usethrottle/catalog`: it
|
|
41
|
+
must show one version with one path.
|
|
42
|
+
|
|
43
|
+
## Two catalog keys
|
|
44
|
+
|
|
45
|
+
A catalog has a **browser key** (`NEXT_PUBLIC_THROTTLE_CATALOG_KEY`, public, answered only from your allowed websites) and
|
|
46
|
+
a **server key** (`THROTTLE_CATALOG_SERVER_KEY`, read by your server, which sends no website origin). The provider takes
|
|
47
|
+
the browser key; the loaders and route helpers take the server key. Never put the server key in a `NEXT_PUBLIC_` variable.
|
|
48
|
+
|
|
49
|
+
## Keeping hosting costs down
|
|
50
|
+
|
|
51
|
+
On Vercel every regenerated page and cached read is a billed ISR write. The defaults avoid them: reads are kept until the
|
|
52
|
+
catalog changes (`STOREFRONT_CACHE_POLICY`, nothing under one hour), search is `no-store` and dynamic, a signed webhook
|
|
53
|
+
(`createRevalidateHandler`) and an open-tab check (`createGenerationSyncHandler`) clear one coarse tag at most once a
|
|
54
|
+
minute per instance, and `createProductPage` prerenders nothing unless you set `staticParams` (every deploy writes every
|
|
55
|
+
prerendered page). Never call `revalidatePath` or set a `revalidate` under 3600. The full rules, with bots and deep
|
|
56
|
+
pagination, are in the docs under "Next.js and caching".
|
|
57
|
+
|
|
58
|
+
## Fresh product and collection lookups
|
|
59
|
+
|
|
60
|
+
The loaders keep the long cache by default: the server client holds every read
|
|
61
|
+
until the catalog changes (the signed revalidate webhook and the generation
|
|
62
|
+
watcher clear it), and nothing revalidates in under an hour. A store that has
|
|
63
|
+
the webhook set up should keep that default.
|
|
64
|
+
|
|
65
|
+
A store without it can pass `primaryCache: 'no-store'` to `loadProduct` and
|
|
66
|
+
`loadShopAll`, or to `createProductPage` and `createShopAllPage`. The product,
|
|
67
|
+
collection or category the page is about is then read live on every request,
|
|
68
|
+
so a deleted product answers 404 (and a renamed one 308) at once instead of a
|
|
69
|
+
cached 200. The cost: that route renders on demand (Next treats a `no-store`
|
|
70
|
+
fetch as dynamic), so there are no ISR writes but a render and a catalog read
|
|
71
|
+
per visit; the config, lists, related products and reviews stay cached. Search
|
|
72
|
+
is always `no-store`. Nothing in the package calls `revalidatePath`.
|
|
73
|
+
|
|
74
|
+
## Layout options
|
|
75
|
+
|
|
76
|
+
- `StoreFrame`'s `footer` prop (and `Footer`'s own) takes `brand`, drawn before
|
|
77
|
+
the menu, and `children`, drawn between the menu and the copyright line.
|
|
78
|
+
- `CollectionShelf` and `ProductCarousel` take `eyebrow`, a small label above the
|
|
79
|
+
heading (a paragraph, not a heading; part `*-eyebrow`).
|
|
80
|
+
- `ProductCard` takes `meta: 'brand' | 'category'` for the line above the title
|
|
81
|
+
(`category` is the catalog's product type). `ShopAll`, `CollectionShelf`,
|
|
82
|
+
`ProductCarousel` and `RecentlyViewed` pass it on as `cardMeta`.
|
|
83
|
+
- `Reviews` takes `layout: 'stack' | 'columns'` (`ProductPage.Root` as
|
|
84
|
+
`reviewsLayout`): `columns` puts the summary and histogram beside the list
|
|
85
|
+
from 768 px.
|
|
86
|
+
|
|
87
|
+
## Theme precedence
|
|
88
|
+
|
|
89
|
+
The theme group (preset, tokens, colour scheme) resolves as: a Throttle Builder's
|
|
90
|
+
site design, then the `preset` / `theme` / `scheme` props, then the catalog's own
|
|
91
|
+
theme, then the `clean` preset. Every other site field (brand, menus,
|
|
92
|
+
announcement, SEO defaults, site strings) is the Builder's, then the catalog's.
|
|
93
|
+
`appearance.variables` overrides the mapped theme variables in every case.
|
|
94
|
+
|
|
95
|
+
## Styling
|
|
96
|
+
|
|
97
|
+
Every element carries `data-throttle-part="<part-key>"` and the class
|
|
98
|
+
`tsf-<part-key>`. The sheet is wrapped in `@layer throttle`, so an unlayered
|
|
99
|
+
store rule or a Tailwind utility passed through `classNames` wins, while
|
|
100
|
+
Tailwind's preflight reset (its `base` layer) does not override the package.
|
|
101
|
+
That needs the layer order `@layer theme, base, throttle, components,
|
|
102
|
+
utilities;`. In the browser the package declares it itself, first in `<head>`.
|
|
103
|
+
When you render on the server, `styles.css` starts with that line, so import it
|
|
104
|
+
before your Tailwind CSS (or any other CSS that declares layers) and nothing
|
|
105
|
+
else is needed. If your own CSS has to load first, make the same line its first
|
|
106
|
+
line.
|
|
107
|
+
|
|
108
|
+
## Keyboard
|
|
109
|
+
|
|
110
|
+
`QuickAdd`'s option panel takes focus when it opens. Tab through its controls;
|
|
111
|
+
Tab past the last control, Shift+Tab out of the first, or Escape closes it and
|
|
112
|
+
returns focus to the card's button, so the next Tab continues from the card.
|
|
113
|
+
The cart drawer, quick view and the filter drawer trap focus and return it to
|
|
114
|
+
what opened them on Escape.
|
|
115
|
+
|
|
116
|
+
## Entries
|
|
117
|
+
|
|
118
|
+
`.` (client), `./server` (loaders and metadata, no React), `./next` and
|
|
119
|
+
`./next/client` (Next.js helpers), `./account` (needs `@usethrottle/auth`),
|
|
120
|
+
`./styles.css`.
|