@thorprovider/storefront 0.4.0-mvp.0 → 0.4.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/README.md +174 -156
- package/VENDOR.md +69 -0
- package/assets/openspec/config.yaml +38 -0
- package/assets/templates/AGENTS.md +76 -0
- package/assets/templates/app/app/[[...slug]]/page.tsx +56 -2
- package/assets/templates/app/app/[[...slug]]/renderer.tsx +44 -2
- package/assets/templates/app/app/globals.css +5 -8
- package/assets/templates/app/app/layout.tsx +1 -5
- package/assets/templates/app/app/robots.ts +9 -3
- package/assets/templates/app/app/sitemap.ts +64 -5
- package/assets/templates/app/lib/__STOREFRONT__/account-boundary.client.tsx +76 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-lifecycle.client.tsx +461 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-mutation.client.ts +46 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-private.core.ts +103 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-reconcile.client.ts +465 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-session.core.ts +177 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-session.ts +44 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-user.core.ts +65 -0
- package/assets/templates/app/lib/__STOREFRONT__/actions.ts +135 -16
- package/assets/templates/app/lib/__STOREFRONT__/catalog.ts +19 -9
- package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +61 -0
- package/assets/templates/app/lib/__STOREFRONT__/composition.ts +26 -0
- package/assets/templates/app/lib/__STOREFRONT__/handlers.core.ts +36 -4
- package/assets/templates/app/lib/__STOREFRONT__/mappers.ts +17 -18
- package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx +209 -0
- package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.ts +247 -0
- package/assets/templates/app/lib/__STOREFRONT__/registry.tsx +123 -62
- package/assets/templates/app/lib/__STOREFRONT__/runtime.ts +3 -0
- package/assets/templates/app/lib/__STOREFRONT__/schema.ts +78 -25
- package/assets/templates/app/lib/__STOREFRONT__/section-observation.ts +182 -0
- package/assets/templates/app/lib/__STOREFRONT__/section-sources.ts +128 -0
- package/assets/templates/app/lib/__STOREFRONT__/shell/content.ts +31 -7
- package/assets/templates/app/lib/__STOREFRONT__/shell/props.ts +4 -0
- package/assets/templates/app/lib/__STOREFRONT__/spec/index.ts +81 -26
- package/assets/templates/app/lib/__STOREFRONT__/spec/seo.ts +165 -0
- package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +4 -2
- package/assets/templates/app/lib/__STOREFRONT__/store-context.ts +26 -7
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/cta.client.tsx +1 -1
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/faq.client.tsx +1 -1
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +2 -1
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/logoCloud.tsx +1 -1
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/pricing.tsx +1 -1
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.client.tsx +100 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.tsx +19 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.products.ts +39 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/statistics.tsx +1 -1
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/testimonials.tsx +1 -1
- package/assets/templates/features/checkout/handlers.ts +6 -0
- package/assets/templates/features/customer-auth/handlers.ts +19 -23
- package/assets/templates/features/customer-auth/state.ts +31 -1
- package/assets/templates/views/account/index.tsx +20 -8
- package/assets/templates/views/account/registry.tsx +294 -154
- package/assets/templates/views/account/schema.ts +1 -0
- package/assets/templates/views/cart/content.ts +11 -0
- package/assets/templates/views/cart/data.ts +23 -0
- package/assets/templates/views/cart/index.tsx +53 -0
- package/assets/templates/views/cart/props.ts +12 -0
- package/assets/templates/views/cart/registry.tsx +82 -0
- package/assets/templates/views/cart/schema.ts +52 -0
- package/assets/templates/views/category/assembly/assembly.json +2 -1
- package/assets/templates/views/category/assembly/index.skeleton.tsx +64 -6
- package/assets/templates/views/category/assembly/registry.skeleton.tsx +7 -6
- package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/binding.json +5 -0
- package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/catalog.part +4 -0
- package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/element.part +7 -0
- package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/registry.part +18 -0
- package/assets/templates/views/category/index.tsx +76 -7
- package/assets/templates/views/category/props.ts +7 -0
- package/assets/templates/views/category/registry.tsx +25 -6
- package/assets/templates/views/category/schema.ts +13 -0
- package/assets/templates/views/checkout/registry.tsx +3 -5
- package/assets/templates/views/home/assembly/assembly.json +12 -3
- package/assets/templates/views/home/assembly/index.skeleton.tsx +24 -5
- package/assets/templates/views/home/assembly/registry.skeleton.tsx +4 -1
- package/assets/templates/views/home/assembly/slots/benefits/cards/binding.json +5 -0
- package/assets/templates/views/home/assembly/slots/benefits/cards/registry.part +17 -0
- package/assets/templates/views/home/assembly/slots/benefits/split/binding.json +5 -0
- package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → split}/registry.part +6 -2
- package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/binding.json +5 -0
- package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/catalog.part +8 -0
- package/assets/templates/views/home/assembly/slots/categories/{ProductCategory2 → CategoryGrid}/element.part +1 -1
- package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/registry.part +31 -0
- package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/binding.json +5 -0
- package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/catalog.part +4 -0
- package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/element.part +5 -0
- package/assets/templates/views/home/assembly/slots/hero/{StorefrontHero1 → StorefrontHero}/registry.part +5 -3
- package/assets/templates/views/home/content.ts +22 -0
- package/assets/templates/views/home/data.ts +9 -0
- package/assets/templates/views/home/index.tsx +34 -11
- package/assets/templates/views/home/props.ts +1 -0
- package/assets/templates/views/home/registry.tsx +41 -17
- package/assets/templates/views/home/schema.ts +141 -24
- package/assets/templates/views/product/data.ts +5 -3
- package/assets/templates/views/product/index.tsx +49 -5
- package/assets/templates/views/product/props.ts +7 -0
- package/assets/templates/views/product/registry.tsx +34 -5
- package/assets/templates/views/product/schema.ts +49 -1
- package/assets/templates/views/static/content.ts +4 -4
- package/assets/templates/views/static/index.tsx +1 -1
- package/bin/storefront.js +1231 -154
- package/examples/merchandising/category-led.json +37 -0
- package/examples/merchandising/collection-led.json +37 -0
- package/package.json +10 -7
- package/recipes/archetypes.json +33 -46
- package/recipes/catalog.json +245 -153
- package/recipes/catalog.mjs +10 -0
- package/recipes/catalog.schema.json +4 -0
- package/recipes/features.json +28 -5
- package/recipes/recipe.schema.json +1 -1
- package/recipes/recipes.json +159 -59
- package/recipes/sections.json +10 -0
- package/recipes/validate.mjs +75 -4
- package/scripts/candidate.mjs +4 -4
- package/scripts/composers.mjs +25 -5
- package/scripts/env-file.mjs +86 -0
- package/scripts/file-classes.mjs +15 -0
- package/scripts/migrate-english-routes.mjs +276 -0
- package/scripts/ownership-conflict.mjs +5 -2
- package/scripts/pinning.mjs +74 -5
- package/scripts/plan-apply.mjs +149 -5
- package/scripts/reconcile.mjs +49 -11
- package/scripts/render-templates.mjs +97 -44
- package/scripts/section-config.mjs +253 -0
- package/scripts/starter.mjs +17 -0
- package/scripts/theme/color.mjs +185 -0
- package/scripts/theme/css-theme.mjs +233 -0
- package/scripts/theme/fonts.mjs +123 -0
- package/scripts/theme/import-export.mjs +125 -0
- package/scripts/theme/preset.mjs +93 -0
- package/scripts/theme/theme-plan.mjs +292 -0
- package/scripts/theme/tokens.mjs +137 -0
- package/scripts/view-assembly.mjs +57 -3
- package/scripts/view-selection.mjs +1 -1
- package/skills/sf-feature/SKILL.md +32 -19
- package/skills/sf-setup/SKILL.md +79 -0
- package/skills/sf-theme-gen/SKILL.md +99 -36
- package/skills/sf-theme-gen/references/shadcn-theming.md +87 -0
- package/skills/{shadcn-theming/references/templates → sf-theme-gen/references}/theme-setup.md +15 -19
- package/skills/{shadcn-theming → sf-theme-gen}/references/theming-guide.md +6 -11
- package/skills/sf-view-gen/SKILL.md +63 -40
- package/skills/sf-view-gen/assets/recipes/archetypes.json +33 -46
- package/skills/sf-view-gen/assets/recipes/catalog.json +245 -153
- package/skills/sf-view-gen/assets/recipes/catalog.schema.json +4 -0
- package/skills/sf-view-gen/assets/recipes/features.json +28 -5
- package/skills/sf-view-gen/assets/recipes/recipes.json +159 -59
- package/skills/sf-view-gen/assets/recipes/sections.json +10 -0
- package/skills/sf-view-gen/assets/templates/views/sections/cta.client.tsx +1 -1
- package/skills/sf-view-gen/assets/templates/views/sections/faq.client.tsx +1 -1
- package/skills/sf-view-gen/assets/templates/views/sections/logoCloud.client.tsx +1 -1
- package/skills/sf-view-gen/assets/templates/views/sections/pricing.client.tsx +1 -1
- package/skills/sf-view-gen/assets/templates/views/sections/products.client.tsx +100 -0
- package/skills/sf-view-gen/assets/templates/views/sections/products.tsx +19 -0
- package/skills/sf-view-gen/assets/templates/views/sections/schema.products.ts +39 -0
- package/skills/sf-view-gen/assets/templates/views/sections/statistics.client.tsx +1 -1
- package/skills/sf-view-gen/assets/templates/views/sections/testimonials.client.tsx +1 -1
- package/skills/{json-render-core/SKILL.md → sf-view-gen/references/json-render-core.md} +4 -27
- package/skills/{json-render-next/SKILL.md → sf-view-gen/references/json-render-next.md} +5 -8
- package/skills/{json-render-react/SKILL.md → sf-view-gen/references/json-render-react.md} +3 -5
- package/skills/{json-render-shadcn/SKILL.md → sf-view-gen/references/json-render-shadcn.md} +3 -5
- package/skills/sf-view-gen/references/views.md +28 -37
- package/skills/sf-view-gen/scripts/catalog.mjs +10 -0
- package/skills/sf-view-gen/scripts/validate.mjs +75 -4
- package/skills/storefront-workflow/SKILL.md +94 -31
- package/skills/{storefront-best-practices/reference/design.md → storefront-workflow/references/design-consistency.md} +13 -29
- package/CHANGELOG.md +0 -84
- package/assets/templates/views/home/assembly/slots/benefits/Feature1/binding.json +0 -5
- package/assets/templates/views/home/assembly/slots/benefits/Feature2/binding.json +0 -5
- package/assets/templates/views/home/assembly/slots/benefits/Feature2/registry.part +0 -10
- package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/binding.json +0 -5
- package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/catalog.part +0 -4
- package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/registry.part +0 -16
- package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/binding.json +0 -5
- package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/catalog.part +0 -4
- package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/element.part +0 -5
- package/assets/templates/views/user-panel/index.tsx +0 -106
- package/assets/templates/views/user-panel/registry.tsx +0 -54
- package/assets/templates/views/user-panel/schema.ts +0 -79
- package/commands/sf-add-view.md +0 -57
- package/commands/sf-feature.md +0 -28
- package/commands/sf-theme.md +0 -26
- package/commands/sf-view.md +0 -67
- package/skills/building-storefronts/SKILL.md +0 -178
- package/skills/building-storefronts/references/frontend-integration.md +0 -229
- package/skills/json-render-remotion/SKILL.md +0 -111
- package/skills/json-render-solid/SKILL.md +0 -204
- package/skills/nextjs-shadcn/SKILL.md +0 -367
- package/skills/nextjs-shadcn/references/architecture.md +0 -499
- package/skills/nextjs-shadcn/references/project-setup.md +0 -162
- package/skills/nextjs-shadcn/references/shadcn-platform.md +0 -261
- package/skills/nextjs-shadcn/references/sidebar.md +0 -274
- package/skills/nextjs-shadcn/references/styling.md +0 -555
- package/skills/shadcn-component-discovery/SKILL.md +0 -273
- package/skills/shadcn-component-discovery/references/registries.md +0 -226
- package/skills/shadcn-theming/SKILL.md +0 -104
- package/skills/storefront-best-practices/SKILL.md +0 -421
- package/skills/storefront-best-practices/reference/components/breadcrumbs.md +0 -123
- package/skills/storefront-best-practices/reference/components/cart-popup.md +0 -189
- package/skills/storefront-best-practices/reference/components/country-selector.md +0 -298
- package/skills/storefront-best-practices/reference/components/footer.md +0 -112
- package/skills/storefront-best-practices/reference/components/hero.md +0 -241
- package/skills/storefront-best-practices/reference/components/megamenu.md +0 -239
- package/skills/storefront-best-practices/reference/components/navbar.md +0 -397
- package/skills/storefront-best-practices/reference/components/popups.md +0 -221
- package/skills/storefront-best-practices/reference/components/product-card.md +0 -125
- package/skills/storefront-best-practices/reference/components/product-reviews.md +0 -217
- package/skills/storefront-best-practices/reference/components/product-slider.md +0 -174
- package/skills/storefront-best-practices/reference/components/search.md +0 -101
- package/skills/storefront-best-practices/reference/connecting-to-backend.md +0 -391
- package/skills/storefront-best-practices/reference/features/promotions.md +0 -307
- package/skills/storefront-best-practices/reference/features/wishlist.md +0 -230
- package/skills/storefront-best-practices/reference/layouts/account.md +0 -380
- package/skills/storefront-best-practices/reference/layouts/cart.md +0 -316
- package/skills/storefront-best-practices/reference/layouts/checkout.md +0 -486
- package/skills/storefront-best-practices/reference/layouts/home-page.md +0 -264
- package/skills/storefront-best-practices/reference/layouts/order-confirmation.md +0 -231
- package/skills/storefront-best-practices/reference/layouts/product-details.md +0 -527
- package/skills/storefront-best-practices/reference/layouts/product-listing.md +0 -520
- package/skills/storefront-best-practices/reference/layouts/static-pages.md +0 -356
- package/skills/storefront-best-practices/reference/medusa.md +0 -307
- /package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → cards}/catalog.part +0 -0
- /package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → cards}/element.part +0 -0
- /package/assets/templates/views/home/assembly/slots/benefits/{Feature2 → split}/catalog.part +0 -0
- /package/assets/templates/views/home/assembly/slots/benefits/{Feature2 → split}/element.part +0 -0
- /package/skills/{storefront-best-practices/reference → storefront-workflow/references}/mobile-responsiveness.md +0 -0
- /package/skills/{storefront-best-practices/reference → storefront-workflow/references}/seo.md +0 -0
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
'use client'
|
|
2
|
+
|
|
3
|
+
// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx)
|
|
4
|
+
//
|
|
5
|
+
// React binding for the projection-ownership ledger. The renderer creates one
|
|
6
|
+
// ledger per tab and provides it here; account mutation/reconciliation code
|
|
7
|
+
// (tasks 3.x) reads the SAME instance through `useProjectionOwnership` so a
|
|
8
|
+
// successful mutation claims the account slice and the renderer stops a later,
|
|
9
|
+
// older server projection from overwriting it. No global mutable and no token.
|
|
10
|
+
//
|
|
11
|
+
// `useAccountOwnership` is the atomic account-ownership helper: claiming the
|
|
12
|
+
// overlay and writing `/account*` in one call keeps the two in lockstep (a
|
|
13
|
+
// divergence would make the overlay mask a different store value). It MUST be
|
|
14
|
+
// called from a client component rendered inside the storefront renderer — a
|
|
15
|
+
// React hook cannot run in a Server Action. Server Actions return data; the
|
|
16
|
+
// client handler awaits the action and then calls `claimAccount(result)` or
|
|
17
|
+
// `claimResolved(result, guard)`.
|
|
18
|
+
//
|
|
19
|
+
// INVARIANT (Important-D): an older server snapshot never overwrites a newer
|
|
20
|
+
// result. The ledger orders CLAIMS, so any authoritative result you display —
|
|
21
|
+
// login/register/logout, or a cross-tab re-resolution (4.x) — MUST be claimed
|
|
22
|
+
// via `claimResolved(result, guard)` (generation guard + claim, atomic). Never
|
|
23
|
+
// display a result and then release to the server: `releaseAccount` /
|
|
24
|
+
// `reconcileAccount` carry no age evidence, so an arbitrary delayed
|
|
25
|
+
// `router.refresh()`/RSC projection could overwrite it. `reconcileAccount` is
|
|
26
|
+
// only an explicit transfer that accepts the NEXT server refresh.
|
|
27
|
+
//
|
|
28
|
+
// IDENTITY-CHANGE INVALIDATION (task 3.3): `claimAccount` also clears the
|
|
29
|
+
// identity-dependent account-PRIVATE order slice whenever the identity key
|
|
30
|
+
// changes, ATOMICALLY with the trio write and only after a `claimResolved`
|
|
31
|
+
// guard. Because every authoritative identity change (login/register/logout,
|
|
32
|
+
// retry/reconcile re-resolution, shell/4.2 claim) flows through `claimAccount`,
|
|
33
|
+
// the private reset happens AT the trigger even when the `/account` panel is
|
|
34
|
+
// unmounted and no effect can run. Same-identity claims are a no-op and the
|
|
35
|
+
// guest cart is never touched (`clearAccountPrivateOrders`).
|
|
36
|
+
|
|
37
|
+
import { createContext, useContext, useMemo, useRef, type ReactNode } from 'react'
|
|
38
|
+
import { useStateStore } from '@json-render/react'
|
|
39
|
+
import type { AccountIdentity, AccountResolution } from './account-session.core'
|
|
40
|
+
import { accountIdentityKey, clearAccountPrivateOrders } from './account-private.core'
|
|
41
|
+
import {
|
|
42
|
+
ACCOUNT_OWNED_KEYS,
|
|
43
|
+
createProjectionOwnership,
|
|
44
|
+
type OwnershipToken,
|
|
45
|
+
type ProjectionOwnership,
|
|
46
|
+
} from './projection-ownership'
|
|
47
|
+
|
|
48
|
+
const ProjectionOwnershipContext = createContext<ProjectionOwnership | null>(null)
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Provide the per-tab ownership ledger. Passing `ownership` is for composition
|
|
52
|
+
* and tests; in the renderer an internal instance is created once and kept for
|
|
53
|
+
* the mounted lifetime of the tab.
|
|
54
|
+
*/
|
|
55
|
+
export function ProjectionOwnershipProvider({
|
|
56
|
+
ownership,
|
|
57
|
+
children,
|
|
58
|
+
}: {
|
|
59
|
+
ownership?: ProjectionOwnership
|
|
60
|
+
children: ReactNode
|
|
61
|
+
}) {
|
|
62
|
+
const ref = useRef<ProjectionOwnership | null>(null)
|
|
63
|
+
if (ref.current === null) ref.current = ownership ?? createProjectionOwnership()
|
|
64
|
+
return (
|
|
65
|
+
<ProjectionOwnershipContext.Provider value={ref.current}>
|
|
66
|
+
{children}
|
|
67
|
+
</ProjectionOwnershipContext.Provider>
|
|
68
|
+
)
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Access the tab's ownership ledger. Throws outside the storefront renderer. */
|
|
72
|
+
export function useProjectionOwnership(): ProjectionOwnership {
|
|
73
|
+
const ownership = useContext(ProjectionOwnershipContext)
|
|
74
|
+
if (!ownership) {
|
|
75
|
+
throw new Error('useProjectionOwnership must be used within the storefront renderer')
|
|
76
|
+
}
|
|
77
|
+
return ownership
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** The allowlisted account values a mutation claims and writes together. */
|
|
81
|
+
export interface AccountClaimValues {
|
|
82
|
+
accountCustomer: AccountIdentity | null
|
|
83
|
+
accountAuthenticated: boolean
|
|
84
|
+
accountResolution: AccountResolution
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Atomic account ownership: claim the overlay and write the store in one call. */
|
|
88
|
+
export interface AccountOwnership {
|
|
89
|
+
/**
|
|
90
|
+
* Claim the account slice and write `/account*` with the same values. When the
|
|
91
|
+
* identity key changes, the identity-dependent private order slice is cleared
|
|
92
|
+
* in the SAME call (atomic with the trio write); a same-identity claim is a
|
|
93
|
+
* no-op and the guest cart is never touched.
|
|
94
|
+
*/
|
|
95
|
+
claimAccount(values: AccountClaimValues): OwnershipToken
|
|
96
|
+
/**
|
|
97
|
+
* Apply an authoritative action/reconciliation result ATOMICALLY with its
|
|
98
|
+
* generation guard. When `guard` is no longer current (a newer mutation or
|
|
99
|
+
* reconciliation already superseded it), the stale result is discarded and
|
|
100
|
+
* null is returned; otherwise the result is claimed (overlay + store write) so
|
|
101
|
+
* it wins over any later-arriving OLDER server projection, and the new token is
|
|
102
|
+
* returned. This is the REQUIRED path for any authoritative result you display
|
|
103
|
+
* (login/register/logout, cross-tab re-resolution in 4.x). Never display a
|
|
104
|
+
* result and then release to the server: `release`/`reconcileAccount` carry no
|
|
105
|
+
* age evidence, so an arbitrary delayed router projection could overwrite it.
|
|
106
|
+
*/
|
|
107
|
+
claimResolved(values: AccountClaimValues, guard?: OwnershipToken | null): OwnershipToken | null
|
|
108
|
+
/** Return the account slice to the server when `token` is still current. */
|
|
109
|
+
releaseAccount(token: OwnershipToken): void
|
|
110
|
+
/**
|
|
111
|
+
* Explicit transfer of the account slice to the NEXT server projection (e.g. a
|
|
112
|
+
* `router.refresh()` whose ordering the framework/app guarantees). Use it ONLY
|
|
113
|
+
* when the authoritative values will arrive through that refresh — NOT for a
|
|
114
|
+
* cross-tab/action result you display (`claimResolved` is that path). Releases
|
|
115
|
+
* whether the slice was seeded or claimed, so a tab that only mounted still
|
|
116
|
+
* adopts the next refresh.
|
|
117
|
+
*/
|
|
118
|
+
reconcileAccount(): void
|
|
119
|
+
/** True while `token` is still the current account claim. */
|
|
120
|
+
isCurrent(token: OwnershipToken): boolean
|
|
121
|
+
/**
|
|
122
|
+
* Acquire the per-tab auth-mutation gate shared by every consumer in this
|
|
123
|
+
* renderer (the global mount, the account forms, a future nav sign-out).
|
|
124
|
+
* Returns false when another auth mutation/reconciliation is already in
|
|
125
|
+
* flight, so two consumers cannot issue concurrent auth requests. The gate is
|
|
126
|
+
* per-tab ledger state — never a module global.
|
|
127
|
+
*/
|
|
128
|
+
acquireAuthMutation(): boolean
|
|
129
|
+
/** Release the per-tab auth-mutation gate (the acquirer only). */
|
|
130
|
+
releaseAuthMutation(): void
|
|
131
|
+
/** True while an auth mutation/reconciliation holds the gate. */
|
|
132
|
+
isAuthMutationPending(): boolean
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* The atomic account-ownership helper. Call it from a client component inside
|
|
137
|
+
* the renderer (for example the account registry) — a React hook cannot run in a
|
|
138
|
+
* Server Action. Server Actions return data; the client handler awaits the
|
|
139
|
+
* action and then calls `claimAccount`/`claimResolved`.
|
|
140
|
+
*
|
|
141
|
+
* Invariant: an older server snapshot never overwrites a newer result. The
|
|
142
|
+
* ledger orders CLAIMS (a claim wins until release), so any authoritative result
|
|
143
|
+
* you display must be claimed — `claimResolved(result, guard)` — never released
|
|
144
|
+
* to the server after display. `reconcileAccount`/`releaseAccount` only hand the
|
|
145
|
+
* slice to the next server projection.
|
|
146
|
+
*/
|
|
147
|
+
export function useAccountOwnership(): AccountOwnership {
|
|
148
|
+
const ownership = useProjectionOwnership()
|
|
149
|
+
const { set, getSnapshot } = useStateStore()
|
|
150
|
+
return useMemo(() => {
|
|
151
|
+
const claimAccount = (values: AccountClaimValues): OwnershipToken => {
|
|
152
|
+
// Normalize once so the overlay and the store cannot diverge (Minor-A).
|
|
153
|
+
const accountCustomer = values.accountCustomer ?? null
|
|
154
|
+
const accountAuthenticated = values.accountAuthenticated === true
|
|
155
|
+
// Identity-change invalidation, ATOMIC with the trio write and
|
|
156
|
+
// generation-safe (this only runs after a guard check in `claimResolved`):
|
|
157
|
+
// when the authorized customer changes — logout, customer switch,
|
|
158
|
+
// expiry/invalidation, or unavailable — clear the identity-dependent
|
|
159
|
+
// private order slice in the SAME call, so the reset happens AT the
|
|
160
|
+
// trigger even when the `/account` panel is unmounted and no effect can
|
|
161
|
+
// run. The prior key is read from the LIVE store (not a render closure),
|
|
162
|
+
// so it is correct regardless of which route is mounted. A same-identity
|
|
163
|
+
// claim (a re-resolution, or `beginMutation`'s snapshot claim) is a no-op,
|
|
164
|
+
// and `clearAccountPrivateOrders` never writes a guest cart key.
|
|
165
|
+
const priorKey = accountIdentityKey(
|
|
166
|
+
(getSnapshot().accountCustomer ?? null) as { id?: string | null } | null,
|
|
167
|
+
)
|
|
168
|
+
const nextKey = accountIdentityKey(accountCustomer)
|
|
169
|
+
const token = ownership.claim(ACCOUNT_OWNED_KEYS, {
|
|
170
|
+
accountCustomer,
|
|
171
|
+
accountAuthenticated,
|
|
172
|
+
accountResolution: values.accountResolution,
|
|
173
|
+
})
|
|
174
|
+
// Clear BEFORE writing the new identity so no reader ever observes the
|
|
175
|
+
// new identity alongside the previous customer's private rows.
|
|
176
|
+
if (priorKey !== nextKey) clearAccountPrivateOrders(set)
|
|
177
|
+
set('/accountCustomer', accountCustomer)
|
|
178
|
+
set('/accountAuthenticated', accountAuthenticated)
|
|
179
|
+
set('/accountResolution', values.accountResolution)
|
|
180
|
+
return token
|
|
181
|
+
}
|
|
182
|
+
return {
|
|
183
|
+
claimAccount,
|
|
184
|
+
claimResolved(values, guard = null) {
|
|
185
|
+
if (guard && !ownership.isCurrent(guard)) return null
|
|
186
|
+
return claimAccount(values)
|
|
187
|
+
},
|
|
188
|
+
releaseAccount(token) {
|
|
189
|
+
ownership.release(token)
|
|
190
|
+
},
|
|
191
|
+
reconcileAccount() {
|
|
192
|
+
const token = ownership.currentToken(ACCOUNT_OWNED_KEYS)
|
|
193
|
+
if (token) ownership.release(token)
|
|
194
|
+
},
|
|
195
|
+
isCurrent(token) {
|
|
196
|
+
return ownership.isCurrent(token)
|
|
197
|
+
},
|
|
198
|
+
acquireAuthMutation() {
|
|
199
|
+
return ownership.acquireMutationGate()
|
|
200
|
+
},
|
|
201
|
+
releaseAuthMutation() {
|
|
202
|
+
ownership.releaseMutationGate()
|
|
203
|
+
},
|
|
204
|
+
isAuthMutationPending() {
|
|
205
|
+
return ownership.isMutationGateHeld()
|
|
206
|
+
},
|
|
207
|
+
}
|
|
208
|
+
}, [ownership, set])
|
|
209
|
+
}
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/projection-ownership.ts)
|
|
2
|
+
//
|
|
3
|
+
// Client-owned projection arbitration for the storefront renderer.
|
|
4
|
+
//
|
|
5
|
+
// `@json-render/react`'s StateProvider re-applies the initial values whose
|
|
6
|
+
// flattened pointers changed between two *server* projections. A client edit
|
|
7
|
+
// made with `set()` lives only in the store, so a changed server projection for
|
|
8
|
+
// the same key overwrites it. Storefront state is therefore split:
|
|
9
|
+
//
|
|
10
|
+
// - server-owned keys (route/catalog/spec/SEO/product data): the server always
|
|
11
|
+
// wins, so navigation keeps working;
|
|
12
|
+
// - client-owned keys (`CLIENT_OWNED_KEYS` = the account slice the SSR projects
|
|
13
|
+
// and the cart slice the cart Server Actions mutate): seeded from the first
|
|
14
|
+
// projection and then protected, so a later (or older) projection cannot
|
|
15
|
+
// overwrite a live cart or a newer local auth result.
|
|
16
|
+
//
|
|
17
|
+
// A mutation can `claim` a client-owned key with a generation (its value wins
|
|
18
|
+
// until release). Authoritative reconciliation releases the slice back to the
|
|
19
|
+
// server: `currentToken(keys)` + `release(token)` downgrades a claim OR a seed,
|
|
20
|
+
// so a tab that only seeded (mounted then never mutated) can still adopt a later
|
|
21
|
+
// logout/expiry projection without a prior local mutation. The generation guards
|
|
22
|
+
// make an older in-flight result unable to release or supersede a newer claim
|
|
23
|
+
// (task 3.3).
|
|
24
|
+
//
|
|
25
|
+
// INVARIANT: the ledger orders CLAIMS, not server projections. A `release` hands
|
|
26
|
+
// the slice to the next server projection and carries no age evidence, so any
|
|
27
|
+
// authoritative result that is displayed MUST be claimed (a newer claim wins
|
|
28
|
+
// until release) — never released to the server after display. The client helper
|
|
29
|
+
// `claimResolved(values, guard)` performs the generation guard + claim
|
|
30
|
+
// atomically; `reconcileAccount` is only an explicit transfer that accepts the
|
|
31
|
+
// next server refresh.
|
|
32
|
+
//
|
|
33
|
+
// Framework-free: no React/Next import, no global state, no token. The per-tab
|
|
34
|
+
// instance lives in `./projection-ownership.client`. `claim`/`seed` store only
|
|
35
|
+
// the declared keys, so a value carrying extra (for example secret) fields can
|
|
36
|
+
// never reach the projection.
|
|
37
|
+
|
|
38
|
+
/** The account state keys the catch-all SSR seeds and an auth mutation owns. */
|
|
39
|
+
export const ACCOUNT_OWNED_KEYS = [
|
|
40
|
+
'accountCustomer',
|
|
41
|
+
'accountAuthenticated',
|
|
42
|
+
'accountResolution',
|
|
43
|
+
] as const
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The cart slice the cart Server Actions mutate locally and the SSR seeds. The
|
|
47
|
+
* server's read-failure/status flags (`cartReadError`, `receiptAvailable`) are
|
|
48
|
+
* deliberately NOT here: they are server-owned so an outage still surfaces.
|
|
49
|
+
*/
|
|
50
|
+
export const CART_OWNED_KEYS = [
|
|
51
|
+
'cart',
|
|
52
|
+
'cartTotals',
|
|
53
|
+
'cartId',
|
|
54
|
+
'cartQuantity',
|
|
55
|
+
'cartCompleted',
|
|
56
|
+
'cartSelectedShippingOptionId',
|
|
57
|
+
] as const
|
|
58
|
+
|
|
59
|
+
/** Every key the renderer protects from a changed server projection. */
|
|
60
|
+
export const CLIENT_OWNED_KEYS = [...ACCOUNT_OWNED_KEYS, ...CART_OWNED_KEYS] as const
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* A claim handle. `generation` is monotonic per ownership instance and is the
|
|
64
|
+
* token downstream mutation/reconciliation paths use to discard stale work.
|
|
65
|
+
*/
|
|
66
|
+
export interface OwnershipToken {
|
|
67
|
+
readonly generation: number
|
|
68
|
+
readonly keys: readonly string[]
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** How a client-owned key is currently governed. */
|
|
72
|
+
export type OwnershipAuthority = 'seed' | 'client' | 'server'
|
|
73
|
+
|
|
74
|
+
/** The ownership ledger the renderer arbitrates against. */
|
|
75
|
+
export interface ProjectionOwnership {
|
|
76
|
+
/** The latest generation issued; 0 before any claim. */
|
|
77
|
+
generation(): number
|
|
78
|
+
/**
|
|
79
|
+
* Capture the first server value of every client-owned key not yet seen, so it
|
|
80
|
+
* is protected from later projections. Idempotent: an already-seeded key is
|
|
81
|
+
* never overwritten, and an existing claim is never replaced.
|
|
82
|
+
*/
|
|
83
|
+
seed(projection: Record<string, unknown> | undefined): void
|
|
84
|
+
/**
|
|
85
|
+
* Take client ownership of `keys` with `values` (every key must be present),
|
|
86
|
+
* superseding any earlier claim for those keys. Returns the generation token.
|
|
87
|
+
*/
|
|
88
|
+
claim(keys: readonly string[], values: Record<string, unknown>): OwnershipToken
|
|
89
|
+
/**
|
|
90
|
+
* The generation token for the current ownership (seed or claim) of `keys`, or
|
|
91
|
+
* null when they are already server-owned. Use it to release a SEEDED slice
|
|
92
|
+
* during authoritative reconciliation, without a prior local mutation.
|
|
93
|
+
*/
|
|
94
|
+
currentToken(keys: readonly string[]): OwnershipToken | null
|
|
95
|
+
/**
|
|
96
|
+
* Return authority to the server for the keys of `token` when it is still the
|
|
97
|
+
* current ownership (seed or claim). An older token is ignored, so a late
|
|
98
|
+
* reconciliation cannot drop a newer claim.
|
|
99
|
+
*/
|
|
100
|
+
release(token: OwnershipToken): void
|
|
101
|
+
/** True while `token` is still the current client claim for all its keys. */
|
|
102
|
+
isCurrent(token: OwnershipToken): boolean
|
|
103
|
+
/** True while `key` is protected from the server projection. */
|
|
104
|
+
isOwned(key: string): boolean
|
|
105
|
+
/** The client-owned key/value overlay across every seeded/claimed key. */
|
|
106
|
+
overlay(): Record<string, unknown>
|
|
107
|
+
/**
|
|
108
|
+
* Acquire the per-tab auth-mutation gate. Returns false when another auth
|
|
109
|
+
* mutation/reconciliation already holds it, so two consumers sharing this tab
|
|
110
|
+
* (the global mount, an account form, a nav sign-out control) cannot issue
|
|
111
|
+
* concurrent auth requests. The gate is per-tab state on this ledger — never a
|
|
112
|
+
* module global — so it cannot leak across requests, tabs, or store contexts.
|
|
113
|
+
*/
|
|
114
|
+
acquireMutationGate(): boolean
|
|
115
|
+
/** Release the per-tab auth-mutation gate (the acquirer only). */
|
|
116
|
+
releaseMutationGate(): void
|
|
117
|
+
/** True while an auth mutation/reconciliation holds the gate. */
|
|
118
|
+
isMutationGateHeld(): boolean
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
interface OwnedEntry {
|
|
122
|
+
authority: OwnershipAuthority
|
|
123
|
+
generation: number
|
|
124
|
+
value: unknown
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Create one per-tab ownership ledger. */
|
|
128
|
+
export function createProjectionOwnership(): ProjectionOwnership {
|
|
129
|
+
const owned = new Map<string, OwnedEntry>()
|
|
130
|
+
let generation = 0
|
|
131
|
+
// Per-tab auth-mutation gate: one in-flight auth request at a time across
|
|
132
|
+
// every consumer that shares this ledger (the global mount, the account forms,
|
|
133
|
+
// a future nav sign-out). Deliberately NOT a module global — a new ledger per
|
|
134
|
+
// tab/request keeps tabs and store contexts isolated.
|
|
135
|
+
let mutationGateHeld = false
|
|
136
|
+
|
|
137
|
+
return {
|
|
138
|
+
generation: () => generation,
|
|
139
|
+
seed(projection) {
|
|
140
|
+
if (!projection) return
|
|
141
|
+
for (const key of CLIENT_OWNED_KEYS) {
|
|
142
|
+
if (owned.has(key)) continue
|
|
143
|
+
if (Object.prototype.hasOwnProperty.call(projection, key)) {
|
|
144
|
+
owned.set(key, { authority: 'seed', generation: 0, value: projection[key] })
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
},
|
|
148
|
+
claim(keys, values) {
|
|
149
|
+
const missing = keys.filter((key) => !Object.prototype.hasOwnProperty.call(values, key))
|
|
150
|
+
if (missing.length > 0) {
|
|
151
|
+
throw new Error(
|
|
152
|
+
`ProjectionOwnership.claim: missing value(s) for owned key(s): ${missing.join(', ')}`,
|
|
153
|
+
)
|
|
154
|
+
}
|
|
155
|
+
generation += 1
|
|
156
|
+
const token: OwnershipToken = { generation, keys: [...keys] }
|
|
157
|
+
for (const key of keys) owned.set(key, { authority: 'client', generation, value: values[key] })
|
|
158
|
+
return token
|
|
159
|
+
},
|
|
160
|
+
release(token) {
|
|
161
|
+
for (const key of token.keys) {
|
|
162
|
+
const entry = owned.get(key)
|
|
163
|
+
if (entry && entry.authority !== 'server' && entry.generation === token.generation) {
|
|
164
|
+
owned.set(key, { authority: 'server', generation: token.generation, value: undefined })
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
},
|
|
168
|
+
currentToken(keys) {
|
|
169
|
+
// Assumes a slice's keys share one generation: `claimAccount` always passes
|
|
170
|
+
// all ACCOUNT_OWNED_KEYS and `page.tsx` seeds the whole account slice or
|
|
171
|
+
// none. A key absent from the first projection yields null (no-op release).
|
|
172
|
+
let generationForKeys = -1
|
|
173
|
+
for (const key of keys) {
|
|
174
|
+
const entry = owned.get(key)
|
|
175
|
+
if (!entry || entry.authority === 'server') return null
|
|
176
|
+
generationForKeys = Math.max(generationForKeys, entry.generation)
|
|
177
|
+
}
|
|
178
|
+
return generationForKeys < 0 ? null : { generation: generationForKeys, keys: [...keys] }
|
|
179
|
+
},
|
|
180
|
+
isCurrent(token) {
|
|
181
|
+
return token.keys.every((key) => {
|
|
182
|
+
const entry = owned.get(key)
|
|
183
|
+
return entry?.authority === 'client' && entry.generation === token.generation
|
|
184
|
+
})
|
|
185
|
+
},
|
|
186
|
+
isOwned(key) {
|
|
187
|
+
const entry = owned.get(key)
|
|
188
|
+
return entry !== undefined && entry.authority !== 'server'
|
|
189
|
+
},
|
|
190
|
+
overlay() {
|
|
191
|
+
const result: Record<string, unknown> = {}
|
|
192
|
+
for (const [key, entry] of owned) {
|
|
193
|
+
if (entry.authority !== 'server') result[key] = entry.value
|
|
194
|
+
}
|
|
195
|
+
return result
|
|
196
|
+
},
|
|
197
|
+
acquireMutationGate() {
|
|
198
|
+
if (mutationGateHeld) return false
|
|
199
|
+
mutationGateHeld = true
|
|
200
|
+
return true
|
|
201
|
+
},
|
|
202
|
+
releaseMutationGate() {
|
|
203
|
+
mutationGateHeld = false
|
|
204
|
+
},
|
|
205
|
+
isMutationGateHeld() {
|
|
206
|
+
return mutationGateHeld
|
|
207
|
+
},
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* Merge the client-owned overlay over a server projection. Server-owned keys are
|
|
213
|
+
* always taken from the server, so a protected cart/account slice never freezes
|
|
214
|
+
* the route/catalog data. When nothing is owned the original projection is
|
|
215
|
+
* returned by reference.
|
|
216
|
+
*/
|
|
217
|
+
export function arbitrateProjection(
|
|
218
|
+
ownership: ProjectionOwnership,
|
|
219
|
+
serverProjection: Record<string, unknown> | undefined,
|
|
220
|
+
): Record<string, unknown> {
|
|
221
|
+
const base = serverProjection ?? {}
|
|
222
|
+
const overlay = ownership.overlay()
|
|
223
|
+
if (Object.keys(overlay).length === 0) return base
|
|
224
|
+
return { ...base, ...overlay }
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** A projection stabilized by serialized content, so an equivalent refresh is a no-op. */
|
|
228
|
+
export interface StabilizedProjection {
|
|
229
|
+
readonly key: string
|
|
230
|
+
readonly value: Record<string, unknown>
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* Keep the previous stabilized projection while the serialized content is
|
|
235
|
+
* unchanged, so `StateProvider` does not re-apply identical server values (which
|
|
236
|
+
* would reset client-owned state). A genuinely changed projection yields a new
|
|
237
|
+
* value. This is the reference-stability the renderer relies on.
|
|
238
|
+
*/
|
|
239
|
+
export function stabilizeProjection(
|
|
240
|
+
previous: StabilizedProjection | null,
|
|
241
|
+
projection: Record<string, unknown> | undefined,
|
|
242
|
+
): StabilizedProjection {
|
|
243
|
+
const value = projection ?? {}
|
|
244
|
+
const key = JSON.stringify(value)
|
|
245
|
+
if (previous && previous.key === key) return previous
|
|
246
|
+
return { key, value }
|
|
247
|
+
}
|