@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
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
- # Temporary Holding Version
1
+ # @usethrottle/storefront-react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`.