@propeller-commerce/propeller-v2-react-ui 0.4.6

package/CHANGELOG.md

@@ -0,0 +1,359 @@
+# Changelog
+
+All notable changes to `propeller-v2-react-ui` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+once it reaches 1.0. Until then (the `0.x` line) the public API may change
+between minor versions; breaking changes are called out below and in
+[MIGRATION.md](./MIGRATION.md).
+
+## [0.4.6] - 2026-06-09
+
+### Fixed
+
+- **`CartItem` cart actions silently no-op (quantity +/-, delete, notes).**
+  The compound-API refactor in 0.3.0 (commit 564f8d0) switched `CartItem`
+  from `useInfraProps(rawProps)` to
+  `useResolvedProps(rawProps, CART_ITEM_RESOLVE_SPEC)`, but the new spec
+  only listed the slot-injection keys (`priceComponent`, `stockComponent`,
+  `surchargesComponent`) — the Tier 1 infra keys (`graphqlClient`, `user`,
+  `language`, `currency`, `configuration`, `companyId`, `includeTax`)
+  weren't declared, so they never got filled in from `<PropellerProvider>`.
+  The internal `useCart()` call received `graphqlClient: undefined`, every
+  service mutation threw inside the SDK, and the consumer saw no spinner,
+  no toast, no change — just buttons that did nothing.
+  Added the missing infra entries to `CART_ITEM_RESOLVE_SPEC` so resolution
+  matches the precedence the rest of the surface uses
+  (`ClusterCard.RESOLVE_SPEC`, `ProductCard.RESOLVE_SPEC`).
+
+## [0.4.5] - 2026-06-04
+
+### Fixed
+
+- **List-view / cart row collapse against a consumer's Tailwind cascade.**
+  `ProductCard` (row layout), `ClusterCard` (row layout), and `CartItem`
+  use responsive override pairs in the markup — `w-full md:w-auto`,
+  `border-t md:border-t-0`, `py-2 md:py-0`, `flex-wrap md:flex-nowrap`.
+  When a consumer also runs Tailwind v4, its generated stylesheet re-emits
+  the base utilities (`.w-full`, `.border-t`, …) but not the `md:` variants
+  that only appear inside this package's components. On equal specificity
+  the consumer sheet wins, the card footer goes full-width, and the body's
+  `flex-1 min-w-0` collapses to zero — title and SKU render at 0px width
+  while the placeholder image still occupies space (the symptom looks like
+  "missing product name" but the element is actually there).
+  Restated the desktop (≥768px) intent on the BEM hook classes scoped under
+  the card root in `styles.css` so the selector is specificity (0,2,0) —
+  it beats any single-class utility (0,1,0) regardless of sheet order.
+  This mirrors the `propeller-v2-vue-ui` fix from May (commit ce7a899).
+
+## [0.4.4] - 2026-06-04
+
+### Changed
+
+- **SDK dependency switched from GitHub tarball to npm.** Both the
+  `peerDependencies` entry and the `devDependencies` test pin now point
+  at `@propeller-commerce/propeller-sdk-v2@^0.11.1` instead of
+  `github:propeller-commerce/propeller-sdk-v2#master`. All 113 source +
+  test files renamed accordingly (`from 'propeller-sdk-v2'` →
+  `from '@propeller-commerce/propeller-sdk-v2'`).
+
+### Dependencies
+
+- Bumps `propeller-v2-core-ui` to 0.2.4 (its own SDK switch to npm).
+
+### Why
+
+The SDK is now published on npm as a properly scoped package. Pinning
+via npm removes the GitLab→GitHub mirror dependency from the install
+chain and gives consumers semver ranges instead of a moving master tip.
+Behaviour is unchanged.
+
+## [0.4.3] - 2026-06-04
+
+### Fixed
+
+- **`CartItem` now resolves product / bundle / crossupsell names via
+  `getLanguageString`** (from `propeller-v2-core-ui@0.2.3`), matching
+  the active language and walking the localised entries for the first
+  non-empty value before falling back to `'Product'`. Previously each
+  helper hard-coded `names?.[0]?.value || 'Product'`, which always
+  picked the first SDK entry regardless of language and rendered blank
+  when that first entry's `value` was empty. Cart pages now show the
+  correct localised name and never collapse to invisible rows on
+  datasets with sparse localisation.
+
+### Dependencies
+
+- Bumps `propeller-v2-core-ui` to 0.2.3 (the resolver fix that powers
+  the above).
+
+## [0.4.0] - 2026-06-02
+
+Finishes the prop-cascade cleanup started in 0.3.0. Every component on
+the main entry now resolves Tier 1 + Tier 2 infra from
+`<PropellerProvider>` when not passed explicitly — consumer islands can
+drop redundant `graphqlClient` / `user` / `companyId` / `language` /
+`includeTax` / `currency` / `configuration` / `portalMode` passes on
+every component (not just the 31 retrofitted in 0.3.0).
+
+### Changed
+
+- **6 client components retrofitted** to call `useInfraProps(rawProps)`:
+  `CategoryDescription`, `ProductDescription`, `GridFilters`,
+  `GridToolbar`, `AddressSelector`, `CartPaymethods`. Same mechanical
+  pattern as the 31 already retrofitted in 0.3.0.
+
+### Added
+
+- **Provider-aware client wrappers for the 6 `@rsc-safe` components**:
+  `Breadcrumbs`, `GridTitle`, `ProductPrice`, `ProductBulkPrices`,
+  `ProductShortDescription`, `CategoryShortDescription`. The pure RSC-safe
+  components still exist and are still exported from `/pure` for Server
+  Component use. The **main `/` entry now exports the wrapper** under the
+  original name (`Breadcrumbs`, etc.), so client islands automatically
+  pick up provider-aware versions with no consumer-side import change.
+  Server pages that need the pure component should import from
+  `propeller-v2-react-ui/pure` (this was already the canonical pattern).
+
+### Migration
+
+Additive. Existing call sites that pass explicit infra props keep
+working unchanged. Client islands can now drop those passes. Server
+pages importing from `/pure` are unaffected.
+
+### Verification
+
+- `tsc --noEmit` clean.
+- 21 / 21 vitest pass.
+- `tsup` build emits both client (with `"use client"` banner) and `/pure`
+  (without banner) shapes correctly; dts unchanged for the pure entry.
+
+## [0.3.0] - 2026-06-02
+
+Loosens 5 components' required infra props to optional, plus retrofits
+`UserDetails` to consume `useInfraProps()` like the other 30 retrofitted
+components. Consumers can now drop redundant `:user=` / `:language=`
+passes on these components when `<PropellerProvider>` wraps the subtree.
+
+### Changed
+
+- **`UserDetails`** — `user: Contact | Customer` → `user?: Contact |
+Customer | null`. Component now calls `useInfraProps(rawProps)` to
+  resolve `user` from the provider when omitted. Existing call sites
+  that pass `user` keep working unchanged.
+- **`AddressSelector`** — `user: Contact | Customer | null` →
+  `user?: Contact | Customer | null`.
+- **`CartPaymethods`** — `user: Contact | Customer | null` →
+  `user?: Contact | Customer | null`.
+- **`GridTitle`** — `language: string` → `language?: string`.
+- **`CategoryDescription`** — `language: string` → `language?: string`.
+
+### Migration
+
+Same shape as `propeller-v2-vue-ui@0.3.0`. Additive. Existing call sites
+keep working. A follow-up cleanup in `propeller-next` will prune ~85
+redundant prop-lines from the consumer islands.
+
+### Verification
+
+- `tsc --noEmit` clean.
+- 21 / 21 vitest tests pass unchanged.
+- `tsup` build emits identical dts shape.
+
+## 0.2.3
+
+### Fixed
+
+- `AccountIconAndMenu` no longer forwards its own `labels` (which contains menu-UI slugs like `accountLabel`, `logoutLabel`) to the embedded `<LoginForm>` — that previously caused LoginForm's `email`, `password`, `forgotPassword` strings to fail translation. Use the new `loginFormLabels?` prop instead.
+
+### Added
+
+- `AccountIconAndMenu`: new `loginFormLabels?: Record<string, string>` prop, forwarded to the embedded `<LoginForm>`. Lets consumers pass the LoginForm namespace's translations through to the dropdown sign-in form.
+
+## 0.2.2
+
+### Added
+
+- `ProductCard` / `ProductGrid` / `ProductSlider`: new `priceLabels?: Record<string, string>` prop, forwarded through to the embedded `<ProductPrice>` display inside each card. Lets consumers translate `inclTax` / `exclTax` / `loginToSeePrices` strings on grid/slider pages without per-card wiring. `ClusterCard` is intentionally unchanged — it builds its own price span and doesn't render `<ProductPrice>`.
+
+## 0.2.1
+
+### Added
+
+- `ProductGrid` / `ProductSlider`: new props `productCardLabels?`, `clusterCardLabels?` for forwarding translations to embedded `<ProductCard>` / `<ClusterCard>`. Mirrors the existing `stockLabels?` / `addToCartLabels?` pattern.
+- `PriceToggle`: new `labels?: Record<string, string>` prop with slugs `pricesLabel`, `inclVat`, `exclVat`. Previously these strings were hardcoded.
+- `OrderList`: filter column field labels and sort-field dropdown options now route through the `labels` prop. Column labels use slug `col<Capitalized>` (e.g. `colTerm`, `colCreatedAt`); sort-field options use the enum value as the slug (e.g. `createdAt`, `price`); sort-order options (ASC/DESC) and order type options also route through `labels`. All fallbacks preserve existing English behavior, so the change is non-breaking for consumers that don't supply the new keys.
+
+### Fixed
+
+- `ProductSlider` no longer forwards its own `labels` (which contains slider-UI slugs such as `scrollLeft`, `noProducts`) to embedded `ClusterCard` — that previously caused card-level strings to fail translation. Use the new `clusterCardLabels?` prop instead.
+
+## [0.2.0] - 2026-06-01
+
+Adds shop-mode-aware user gating. Existing public API is unchanged; new
+fields are optional and default to backward-compatible behaviour.
+
+### Added
+
+- **`shopMode?: ShopMode`** on `PropellerScope`. Declares whether the shop
+  is `'b2b'`, `'b2c'`, or `'hybrid'`. Defaults to `'hybrid'` when omitted
+  so existing call sites keep their current branching semantics (any
+  logged-in Contact treated as B2B).
+- **Derived `userMode: UserMode`** on `PropellerInfra`. Computed via
+  `deriveUserMode(user, shopMode)` from `propeller-v2-core-ui`. Values:
+  `'anonymous' | 'b2b' | 'b2c'`. B2B-gated UI (company switcher, B2B
+  side-nav items, quote/authorization affordances) should read this
+  instead of re-deriving from `isContact(user)` ad hoc.
+- **`useUserMode()` hook**. Direct read of `userMode` for components that
+  only need that one signal.
+
+### Why this matters
+
+Hybrid shops need a single, consistent gate that says "is the current
+viewer behaving as B2B or B2C?" Previously every B2B-gated component
+re-derived this from `isContact(user)` ad hoc, which was correct but
+duplicated and ignored the shop's `mode` (a B2C shop that somehow had a
+Contact session would still light up the B2B surface). Centralising the
+derivation eliminates the duplication and makes the shop mode authoritative.
+
+### Requires
+
+- `propeller-v2-core-ui` ≥ 0.2.0 (for `deriveUserMode`, `ShopMode`,
+  `UserMode`).
+
+---
+
+## [0.1.0] — Unreleased
+
+First version of the package. Extracted from the `propeller-next`
+boilerplate so the Propeller Commerce React surface can be consumed as a
+standalone library. Not yet published to a registry — consumed via a
+`file:` link during stabilization.
+
+### Added
+
+- **Initial extraction (Phase E).** 60 components, the React composables
+  (hooks), the runtime-agnostic `composables/shared/` layer (utilities and
+  domain types), and the two contexts (`PropellerContext`,
+  `ProductGridContext`) moved into this package from `propeller-next`.
+- **Build pipeline.** `tsup` produces dual ESM + CJS bundles with `.d.ts`
+  declarations. The client bundle (`index`) gets a `"use client";` banner
+  prepended in a post-build hook; the `shared` and `pure` bundles are
+  runtime-agnostic with no banner.
+- **Three code entry points.** `propeller-v2-react-ui` (components, hooks,
+  contexts, `createServices`, `toPlain`), `propeller-v2-react-ui/pure` (the
+  12 pure/presentational components, RSC-safe — see below), and
+  `propeller-v2-react-ui/shared` (pure TS — `createServices`, `toPlain`,
+  formatters, helpers, all domain types — safe to import from Server
+  Components).
+- **`/pure` RSC-safe component entry.** A third `tsup` entry exporting the
+  12 pure/presentational components (`Breadcrumbs`, `ProductPrice`,
+  `ItemStock`, `OrderTotals`, `ProductBulkPrices`, `ProductShortDescription`,
+  `ProductDownloads`, `ProductVideos`, `OrderItemCard`, `OrderSummary`,
+  `GridTitle`, `CategoryShortDescription`). The `pure` bundle is built
+  **without** the `"use client"` banner, so a React Server Component can
+  import and render these components directly — server-rendering real
+  product/price/order markup — without drawing a client boundary or
+  shipping the client bundle. Each is verified to use no hooks, state,
+  effects, handlers, browser APIs or context reads. The same components
+  remain available from the main entry for use inside client boundaries.
+- **Precompiled stylesheet** (`dist/styles.css`). The package's Tailwind v4
+  classes are compiled to vanilla CSS at build time and shipped. Consumers
+  import it once and do **not** need Tailwind in their own project.
+- **Three styling override surfaces** — theme tokens (CSS variables), BEM
+  hooks (`.propeller-product-card__price`, …), and per-instance `className`.
+  Documented in [STYLING.md](./STYLING.md).
+- **`PropellerProvider`** — the single integration point. Takes one value
+  object (`PropellerInfra`) carrying `graphqlClient`, `services`, `user`,
+  `companyId`, `language`, `includeTax`, `currency`, `portalMode`,
+  `configuration`. Imports zero host contexts.
+- **`createServices(client)`** — factory that builds the typed `Services`
+  bundle (`product`, `cart`, `user`, `order`, …) keyed to a consumer-built
+  `GraphQLClient`. Memoized per client via `WeakMap`.
+- **`toPlain(value)`** — recursively strips the SDK's underscore-prefixed
+  backing fields from class instances.
+- **`useServices()`** — reads the `Services` bundle from `PropellerProvider`;
+  throws a clear error when used outside a provider.
+- Public-grade documentation: [README.md](./README.md), [STYLING.md](./STYLING.md),
+  [TECH.md](./TECH.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
+  [MIGRATION.md](./MIGRATION.md), [SECURITY.md](./SECURITY.md), and an MIT
+  `LICENSE`.
+- **Unit tests.** Vitest suite covering the pure-logic surface — `src/lib/`
+  (`createServices`, `toPlain`) and the 11 framework-free shared utilities
+  (formatters, truncation, inventory/label/visibility helpers, attribute
+  extraction, country lookup, language resolution, product helpers, user
+  identity, video URL transforms). 183 tests, ~99% statement / 100%
+  function coverage of that surface. Scripts: `test`, `test:watch`,
+  `test:coverage`.
+- **CI pipeline** (`.gitlab-ci.yml`). A `verify` stage (typecheck, unit
+  tests + coverage, build) and a `downstream` stage that builds the
+  package, installs it into a fresh checkout of propeller-next, and runs
+  that repo's full Playwright e2e suite — the package's component
+  regression gate. Components are intentionally not unit-tested against a
+  mock SDK; the consumer's real e2e suite is the verification layer.
+  Required GitLab CI/CD variables are documented in
+  [CONTRIBUTING.md](./CONTRIBUTING.md).
+- **Storybook** (`.storybook/`). A story per component (60 total),
+  rendering each in isolation against fixture data and a mock
+  `PropellerProvider`. The "Docs" tab auto-generates each component's
+  full `*Props` table from the TypeScript source via
+  `react-docgen-typescript`. Mock foundation in `src/__mocks__/`
+  (`fixtures.ts`, `mockServices.ts`, `decorators.tsx`). Scripts:
+  `storybook`, `build-storybook`.
+- **Documentation site** (`docs/`). A self-contained Docusaurus 3 app —
+  its own `package.json` / lockfile, not published to npm, not part of
+  the package build. Eight guide pages (introduction, getting started,
+  the SDK seam, styling, server components, component reference,
+  Storybook, contributing) sourced from the package's own markdown.
+  The component prop reference is intentionally not duplicated here —
+  the site links out to Storybook's auto-generated prop tables.
+
+- **`Menu`: optional pre-fetched `tree` prop.** When the host supplies
+  `tree: MenuCategory[]`, `Menu` skips its internal `useMenu` fetch
+  entirely and renders the tree directly — mirroring the
+  `ProductGrid.products` opt-in. Lets host apps fetch the category tree
+  server-side (e.g. in a Next.js layout) and have the menu HTML land in
+  the initial response. Omitting the prop preserves the legacy
+  client-side fetch behaviour — no breaking change.
+
+### Changed
+
+- **Decoupled the SDK seam from Next.js (breaking, pre-publish).** The
+  package no longer ships a module-level `graphqlClient` singleton, a
+  hardcoded `/api/graphql` endpoint, or `NEXT_PUBLIC_*` environment reads.
+  The consumer now constructs its own `GraphQLClient`, calls
+  `createServices(client)`, and passes both into `PropellerProvider`.
+  `getServices` (singleton-defaulting accessor) was replaced by
+  `createServices` (pure factory). See [MIGRATION.md](./MIGRATION.md).
+- **Removed the `/server` entry.** The previous
+  `propeller-v2-react-ui/server` subpath (`createServerClient`,
+  `getServerInfra`, `fetchProduct`, `fetchCategory`) was deleted —
+  server-side GraphQL wiring (endpoint, API keys, cookie names, auth) is
+  application-specific. Consumers host their own server module; the package
+  exports `createServices` from `/shared` for server-side use.
+- **Dropped the `next` peer dependency.** The package has zero `next/*`
+  imports. Next.js apps still work out of the box.
+- `PropellerInfra` gained a required `services: Services` field.
+
+### Fixed
+
+- **`OrderActions` button layout.** Buttons no longer wrap mid-word when
+  `OrderActions` shares a flex row with `OrderTotals` — added
+  `flex-shrink-0` to the wrapper and `whitespace-nowrap` to the buttons.
+- **`CartItem` alignment.** The product image and footer are top-aligned
+  with the title row instead of vertically centering against tall content
+  (cross-sells) — root changed from `items-center` to `items-start`.
+- **`ProductCard` row layout.** Responsive utilities (`md:flex-nowrap`,
+  etc.) buried inside template-literal ternaries were missing from the
+  compiled stylesheet; force-included via `@source inline(...)` so list
+  view stays single-row at desktop widths.
+- **`GridFilters` — active filters now visible on first render.** A filter
+  group with a selected value starts expanded even when `collapsed` is
+  `true`, and its checkboxes render checked, on the very first render
+  (including SSR — previously this depended on a client-only effect that
+  never ran server-side). Restoring a filtered URL no longer hides the
+  ticked checkboxes. A group the user explicitly toggles still wins, and a
+  user collapsing a group with an active filter is not fought.
+
+[0.1.0]: https://github.com/propeller-commerce/propeller-v2-react-ui/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Propeller Commerce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,217 @@
+# Migration Guide
+
+Breaking changes between versions of `propeller-v2-react-ui`, with the steps
+to upgrade. The package is pre-1.0, so breaking changes can land in `0.x`
+minor versions — each one is documented here.
+
+---
+
+## `Menu`: optional pre-fetched `tree` prop (additive)
+
+**When:** during `0.1.0` stabilization (pre-publish).
+
+`Menu` now accepts an optional `tree?: MenuCategory[]` prop. When supplied,
+the component skips its internal `useMenu` fetch and renders the tree
+directly — mirroring the long-standing `ProductGrid.products` opt-in.
+
+**No migration required.** Omitting the prop preserves the legacy
+client-side fetch behaviour. This is purely opt-in for hosts that want to
+move the category tree fetch into a Server Component (e.g. a Next.js
+layout) so the menu HTML lands in the initial response and the host can
+attach framework cache hints — see also `GraphQLFetchOptions` in
+`propeller-sdk-v2` v0.11.0.
+
+### Recommended pattern for Next.js consumers
+
+```tsx
+// app/layout.tsx — Server Component
+import { fetchMenu, getAnonymousInfra } from '@/lib/server';
+import Header from '@/components/layout/Header';
+
+export default async function RootLayout({ children }) {
+  const menuTree = await fetchMenu(getAnonymousInfra(), BASE_CATEGORY_ID, lang);
+  return (
+    <html><body>
+      <Header menuTree={menuTree} />
+      {children}
+    </body></html>
+  );
+}
+
+// components/layout/Header.tsx — 'use client'
+import { Menu } from 'propeller-v2-react-ui';
+export default function Header({ menuTree }) {
+  return <Menu categoryId={BASE_CATEGORY_ID} tree={menuTree} onMenuItemClick={...} />;
+}
+```
+
+The internal `useEffect` short-circuits when `tree` is present, so there is
+no avoidable client-side round trip after hydration.
+
+See [TECH.md §7 "Pre-fetched data prop pattern"](./TECH.md) for the broader
+context and the same pattern as it applies to `ProductGrid`.
+
+---
+
+## Decoupling the SDK seam from Next.js
+
+**When:** during `0.1.0` stabilization (pre-publish).
+
+The package used to ship a module-level GraphQL client singleton with a
+hardcoded `/api/graphql` endpoint and `NEXT_PUBLIC_*` environment reads, plus
+a `/server` entry for server-side fetching. Both baked a specific app shape
+(a Next.js app proxying at exactly that path) into the library. They were
+removed.
+
+### What changed
+
+| Before | After |
+| ------ | ----- |
+| `import { graphqlClient } from 'propeller-v2-react-ui'` | Consumer constructs its own `GraphQLClient` |
+| `import { getServices } from 'propeller-v2-react-ui'` | `import { createServices } from 'propeller-v2-react-ui'` |
+| `getServices()` (singleton default) | `createServices(client)` — explicit client, required |
+| `propeller-v2-react-ui/server` entry | Removed — host your own server module |
+| `next` peer dependency | Removed — the package has no `next/*` imports |
+| `PropellerInfra` without `services` | `PropellerInfra` requires a `services` field |
+
+### How to upgrade
+
+#### 1. Own your GraphQL client
+
+Create a small module in your app that constructs the client and the
+services bundle:
+
+```ts
+// lib/api.ts — in YOUR app
+import { GraphQLClient } from 'propeller-sdk-v2';
+import { createServices } from 'propeller-v2-react-ui';
+
+export const graphqlClient = new GraphQLClient({
+  endpoint: '/api/graphql',              // your endpoint / proxy path
+  apiKey: '',
+  orderEditorApiKey: process.env.NEXT_PUBLIC_ORDER_EDITOR_API_KEY || '',
+  timeout: 30_000,
+  headers: {},
+});
+
+export const services = createServices(graphqlClient);
+```
+
+The endpoint, env-var names, and timeout are now **your** decision — pick
+whatever fits your app (a route-handler proxy, a direct upstream URL, a
+custom rewrite).
+
+#### 2. Pass `graphqlClient` and `services` into `PropellerProvider`
+
+`PropellerInfra` now requires `services`:
+
+```tsx
+import { PropellerProvider } from 'propeller-v2-react-ui';
+import { graphqlClient, services } from '@/lib/api';
+
+<PropellerProvider value={{
+  graphqlClient,
+  services,           // ← newly required
+  user,
+  companyId,
+  language: 'NL',
+  includeTax: false,
+  currency: '€',
+  portalMode: 'OPEN',
+  configuration: {},
+}}>
+  {children}
+</PropellerProvider>
+```
+
+#### 3. Replace `graphqlClient` / `getServices` imports
+
+Anywhere you imported these from the package, import from your own
+`lib/api` instead:
+
+```diff
+- import { graphqlClient, getServices } from 'propeller-v2-react-ui';
++ import { graphqlClient, services } from '@/lib/api';
+```
+
+Call sites collapse — `getServices(graphqlClient).cart` becomes
+`services.cart`:
+
+```diff
+- await getServices(graphqlClient).cart.deleteCart({ id });
++ await services.cart.deleteCart({ id });
+```
+
+Components and composables rendered inside `PropellerProvider` can also use
+the `useServices()` hook instead of importing `services` directly.
+
+#### 4. Update the shared cart helpers
+
+`initCart`, `fetchActiveCart`, and `mergeAnonymousCart` previously took a
+`graphqlClient` field in their config object. They now take `services`:
+
+```diff
+  await fetchActiveCart({
+-   graphqlClient,
++   services,
+    user,
+    language,
+    imageSearchFilters,
+    imageVariantFilters,
+  });
+```
+
+#### 5. Replace the `/server` entry
+
+If you imported `createServerClient`, `getServerInfra`, `fetchProduct`, or
+`fetchCategory` from `propeller-v2-react-ui/server`, that entry is gone.
+Host a server module in your own app instead. The pattern:
+
+```ts
+// lib/server.ts — in YOUR app
+import 'server-only';
+import { cookies } from 'next/headers';        // or your framework's equivalent
+import { GraphQLClient } from 'propeller-sdk-v2';
+import { createServices, toPlain } from 'propeller-v2-react-ui/shared';
+
+export function createServerClient() {
+  return new GraphQLClient({
+    endpoint: process.env.PROPELLER_GRAPHQL_ENDPOINT!,  // your env name
+    apiKey: process.env.PROPELLER_API_KEY!,
+    securityMode: 'direct',
+    getAccessToken: async () => (await cookies()).get('access_token')?.value,
+  });
+}
+
+export async function fetchProduct(productId: number, language = 'NL') {
+  const services = createServices(createServerClient());
+  const result = await services.product.getProduct({
+    productId, language, imageSearchFilters: {},
+    imageVariantFilters: { transformations: [] },
+  });
+  return result ? toPlain(result) : null;
+}
+```
+
+`createServices` is exported from `propeller-v2-react-ui/shared` precisely so
+it can be used server-side without pulling the client bundle into the server
+graph. The `propeller-next` repo's `lib/server.ts` is a complete reference
+implementation — copy it and adjust the env-var names and cookie name.
+
+#### 6. Drop `next` from your reasoning, not your app
+
+The package no longer peer-depends on `next`. Your Next.js app obviously
+still depends on Next — nothing changes there. The point is the package
+itself is now framework-neutral; nothing to do on your side beyond noting it.
+
+### Why this change
+
+GraphQL transport — the endpoint URL, whether you proxy, how you resolve
+auth tokens, which environment-variable convention you use — is
+application-specific. A library that hardcodes `/api/graphql` and
+`NEXT_PUBLIC_*` is usable only by an app shaped exactly like the one it was
+extracted from. Moving the client construction into the consumer makes the
+package usable by any React app (Next.js App Router or Pages Router, Vite,
+Remix, CRA) and makes it testable with a mock client.
+
+See [TECH.md](./TECH.md) §6 for the full rationale.