@propeller-commerce/propeller-v2-vue-ui 0.3.14

package/MIGRATION.md

@@ -0,0 +1,178 @@
+# Migration guide
+
+## `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 the SSR layer (e.g. propeller-vue's
+`entry-server.ts` always-on prefetch) so the menu HTML lands in the initial
+response and the host can attach cache tags via the SDK's `headers` config.
+
+### Recommended pattern for Vue SSR consumers
+
+```ts
+// entry-server.ts — Vue 3 + Vite SSR (or any Node-side render hook)
+import { fetchMenu, getAnonymousInfra } from '@/lib/server'
+import { useMenuStore } from '@/stores/menu'
+
+// Inside the render flow, before renderToString:
+const tree = await fetchMenu(getAnonymousInfra(), BASE_CATEGORY_ID)
+useMenuStore().setTree(tree)
+```
+
+```vue
+<!-- AppHeader.vue or wherever the menu lives -->
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Menu as PropellerMenu } from 'propeller-v2-vue-ui'
+import { useMenuStore } from '@/stores/menu'
+
+const menuStore = useMenuStore()
+const menuTreeProp = computed(() => menuStore.tree ?? undefined)
+</script>
+
+<template>
+  <PropellerMenu
+    :graphqlClient="graphqlClient"
+    :categoryId="BASE_CATEGORY_ID"
+    :language="lang"
+    :tree="menuTreeProp"
+    :onMenuItemClick="handleClick"
+  />
+</template>
+```
+
+`MenuCategory` is exported from `/shared` (type-only) so the server-side
+fetch helper can build the tree without pulling the Vue composable's
+runtime into the server bundle.
+
+See [TECH.md §7 "Pre-fetched data prop pattern"](./TECH.md) for the broader
+context and the same pattern as it applies to `ProductGrid`.
+
+---
+
+## From in-app components → the `propeller-v2-vue-ui` package
+
+Before this package existed, the Propeller Commerce Vue components and
+composables lived directly inside the `propeller-vue` storefront under
+`src/components/propeller/` and `src/composables/`. They are now a
+standalone package. This guide is for moving a consumer onto it.
+
+### 1. Install the package
+
+```bash
+npm install propeller-v2-vue-ui propeller-sdk-v2 --install-links
+```
+
+`propeller-sdk-v2` is a **peer dependency** — install it yourself so the
+package and your app share one SDK instance. `--install-links` is needed
+on Windows for `file:` / `github:` installs (a symlinked install breaks the
+nested `propeller-sdk-v2` resolution).
+
+### 2. Import the stylesheet
+
+```ts
+// main.ts
+import 'propeller-v2-vue-ui/styles.css';
+```
+
+Import it once, at your app entry. You no longer compile the components'
+Tailwind classes yourself — the package ships a precompiled stylesheet.
+
+### 3. Build the SDK seam and install the provider
+
+The biggest change: the package ships **no `graphqlClient` singleton**.
+Previously composables imported a shared client from `src/lib/api.ts` and
+did `new XxxService(graphqlClient)` internally. Now:
+
+```ts
+// src/lib/api.ts — YOUR app keeps this file; it just changes shape
+import { GraphQLClient } from 'propeller-sdk-v2';
+import { createServices } from 'propeller-v2-vue-ui';
+
+export const graphqlClient = new GraphQLClient({
+  endpoint: import.meta.env.VITE_GRAPHQL_ENDPOINT || '/api/graphql',
+  apiKey: import.meta.env.VITE_API_KEY || '',
+  timeout: 30_000,
+});
+
+export const services = createServices(graphqlClient);
+```
+
+Then install the provider once, high in the tree (root `App.vue`):
+
+```vue
+<script setup lang="ts">
+import { providePropeller } from 'propeller-v2-vue-ui';
+import { graphqlClient, services } from '@/lib/api';
+import { useAuthStore } from '@/stores/auth';
+import { useLanguageStore } from '@/stores/language';
+// …
+
+const auth = useAuthStore();
+const lang = useLanguageStore();
+
+providePropeller({
+  graphqlClient,
+  services,
+  user: auth.user,
+  companyId: undefined,
+  language: lang.language,
+  includeTax: false,
+  currency: '€',
+  configuration: config,
+  portalMode: 'open',
+});
+</script>
+```
+
+### 4. Update component imports
+
+```diff
+- import ProductCard from '@/components/propeller/ProductCard.vue';
++ import { ProductCard } from 'propeller-v2-vue-ui';
+```
+
+The 60 component names are unchanged.
+
+### 5. Composables
+
+Composable signatures are unchanged — they still accept a `graphqlClient`
+option. Internally they now route through `createServices`. Update imports:
+
+```diff
+- import { useCart } from '@/composables/useCart';
++ import { useCart } from 'propeller-v2-vue-ui';
+```
+
+The three framework-agnostic cart helpers (`initCart`, `fetchActiveCart`,
+`mergeAnonymousCart`) take a `services` bundle in their config rather than
+a raw `graphqlClient`.
+
+### 6. URL builders and routing
+
+`ProductCard` no longer depends on `vue-router`. Pass an `onProductClick`
+callback for SPA navigation:
+
+```vue
+<ProductCard :product="p" :onProductClick="(prod) => router.push(productUrl(prod))" />
+```
+
+`SearchBar` and `CartIconAndSidebar` build result URLs from the
+`configuration.urls` builders you pass in — supply
+`configuration.urls.getProductUrl` / `getClusterUrl` if you need
+language-prefixed or custom paths.
+
+### What you keep in your own app
+
+- `src/lib/api.ts` — the `GraphQLClient` construction and `createServices`
+  call. Endpoint, env-var names, timeout — all consumer-specific.
+- Any server-side (Nuxt) data fetching — the package has no `/server`
+  entry.
+- Routing, Pinia stores, the app shell.

package/README.md

@@ -0,0 +1,282 @@
+# propeller-v2-vue-ui
+
+A Vue 3 component library for **Propeller Commerce** storefronts. It ships
+ready-made e-commerce UI — product cards, grids, carts, checkout, account
+pages — together with headless composables that talk to the Propeller
+GraphQL API, plus the shared utilities and types those parts build on.
+
+It is the Vue mirror of [`propeller-v2-react-ui`](https://github.com/propeller-commerce/propeller-v2-react-ui):
+same component set, same SDK seam, same styling contract.
+
+The package is framework-flexible within the Vue ecosystem: it runs in any
+Vue 3.4+ app — a Vite SPA, a Nuxt 3 app — and ships its own precompiled
+stylesheet, so you do **not** need Tailwind in your project to use it.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Peer dependencies](#peer-dependencies)
+- [Entry points](#entry-points)
+- [Core concept: the SDK seam](#core-concept-the-sdk-seam)
+- [Quick start](#quick-start)
+- [The Propeller provider](#the-propeller-provider)
+- [Using components](#using-components)
+- [Using composables](#using-composables)
+- [Styling](#styling)
+- [API reference](#api-reference)
+- [Building from source](#building-from-source)
+
+## Installation
+
+```bash
+npm install propeller-v2-vue-ui propeller-sdk-v2 --install-links
+```
+
+`propeller-sdk-v2` is a **peer dependency** — install it yourself so the
+package and your application share a single SDK instance. `--install-links`
+is needed on Windows for `file:` / `github:` installs.
+
+## Peer dependencies
+
+| Package            | Version  | Required |
+| ------------------ | -------- | -------- |
+| `vue`              | `>=3.4`  | Yes      |
+| `propeller-sdk-v2` | `*`      | Yes      |
+
+There is no dependency on Nuxt or `vue-router` — nothing in the package
+imports them. A plain Vite + Vue app works out of the box.
+
+## Entry points
+
+| Import path                  | Contents                                              |
+| ----------------------------- | ----------------------------------------------------- |
+| `propeller-v2-vue-ui`         | Components, composables, the provider, `createServices`, `toPlain` |
+| `propeller-v2-vue-ui/shared`  | `createServices`, `toPlain`, formatters, helpers, types — pure TS |
+| `propeller-v2-vue-ui/pure`    | SSR-safe presentational components — no composables, no browser APIs |
+| `propeller-v2-vue-ui/styles.css` | The precompiled stylesheet |
+
+The `/shared` entry is plain TypeScript with no Vue dependency — import the
+pure helpers and `createServices` from there when you want them outside a
+component (a Nuxt server route, a build script, a test).
+
+The `/pure` entry re-exports a curated subset of components that are
+guaranteed SSR-safe: no composable calls, no `window`/`localStorage`/`document`
+access, no `onMounted` fetching. Render them directly into the static shell
+of a server-rendered page with no hydration mismatch. Mirrors the React
+package's `/pure` entry component-for-component.
+
+## Core concept: the SDK seam
+
+This is the one architectural idea to understand before using the package.
+
+**The package ships no GraphQL client** and **no hardcoded API endpoint.**
+GraphQL transport is application-specific — a Vite SPA hits the API through
+its dev proxy; a Nuxt app may use a server route; another app uses a custom
+rewrite. Baking a URL into a component library would lock it to one app
+shape.
+
+The contract is three steps:
+
+1. **You construct the `GraphQLClient`** from `propeller-sdk-v2`, with your
+   endpoint, headers and auth resolver.
+2. **You call `createServices(client)`** once — it returns a typed
+   `Services` bundle (`product`, `cart`, `user`, `order`, …) keyed to that
+   client.
+3. **You install both** via `providePropeller({ graphqlClient, services, … })`.
+
+Inside the provider, every component and composable reads the services via
+`useServices()` — they never instantiate the SDK themselves.
+
+`createServices` is a pure factory, memoized per client via a `WeakMap`, so
+calling it again with the same client returns the same bundle. `toPlain`
+recursively strips the SDK's underscore-prefixed backing fields so
+downstream code sees the clean public shape.
+
+## Quick start
+
+### 1. Build the client and services
+
+```ts
+// src/lib/api.ts — your app owns this file
+import { GraphQLClient } from 'propeller-sdk-v2';
+import { createServices } from 'propeller-v2-vue-ui';
+
+export const graphqlClient = new GraphQLClient({
+  endpoint: import.meta.env.VITE_GRAPHQL_ENDPOINT || '/api/graphql',
+  apiKey: import.meta.env.VITE_API_KEY || '',
+  timeout: 30_000,
+});
+
+export const services = createServices(graphqlClient);
+```
+
+### 2. Install the provider and the stylesheet
+
+```ts
+// src/main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import 'propeller-v2-vue-ui/styles.css';
+
+createApp(App).mount('#app');
+```
+
+```vue
+<!-- src/App.vue -->
+<script setup lang="ts">
+import { providePropeller } from 'propeller-v2-vue-ui';
+import { graphqlClient, services } from '@/lib/api';
+
+providePropeller({
+  graphqlClient,
+  services,
+  user: null,            // your auth state (a Contact / Customer or null)
+  companyId: undefined,
+  language: 'NL',
+  includeTax: false,
+  currency: '€',
+  configuration: {},     // free-form config bag (url builders, image filters)
+  portalMode: 'open',
+});
+</script>
+
+<template>
+  <RouterView />
+</template>
+```
+
+`providePropeller` must be called in a component's `setup()` (typically the
+root `App.vue`) so the `provide` reaches the whole tree.
+
+### 3. Use components and composables anywhere below the provider
+
+```vue
+<script setup lang="ts">
+import { ProductCard } from 'propeller-v2-vue-ui';
+</script>
+
+<template>
+  <ProductCard :product="product" />
+</template>
+```
+
+## The Propeller provider
+
+`providePropeller(value)` installs a `PropellerInfra` object for the
+component subtree. `usePropellerContext()` reads it (non-throwing — returns
+`null` outside a provider).
+
+### `PropellerInfra` fields
+
+| Field           | Type                       | Notes |
+| --------------- | -------------------------- | ----- |
+| `graphqlClient` | `GraphQLClient`            | The client you constructed. |
+| `services`      | `Services`                 | The bundle from `createServices(client)`. |
+| `user`          | `Contact \| Customer \| null` | Your auth state. |
+| `companyId`     | `number \| undefined`      | Active company for B2B pricing. |
+| `language`      | `string`                   | e.g. `'NL'`, `'EN'`. |
+| `includeTax`    | `boolean`                  | Leading price is net (incl. VAT) when true. |
+| `currency`      | `string`                   | Currency symbol for price formatting. |
+| `configuration` | `unknown`                  | Free-form bag (url builders, image filters). |
+| `portalMode`    | `string`                   | e.g. `'open'`, `'semi-closed'`. |
+
+A component reads infra via `useInfraProps(props)` — an explicit prop always
+wins, otherwise the value comes from the provider, otherwise a default. This
+means components also work standalone (no provider) for tests and
+Storybook.
+
+## Using components
+
+The package exports 60 components. They are prop-driven. Components that
+need infrastructure resolve it from the provider, so most usages are short:
+
+```vue
+<ProductGrid :categoryId="17" />
+<CartIconAndSidebar />
+<Breadcrumbs :categoryPath="category.categoryPath" />
+```
+
+`ProductGrid` installs a Tier-2 grid config (`provideProductGridConfig`)
+that `ProductCard` / `ClusterCard` and their subtree consume — so you do not
+thread display flags and callbacks through by hand.
+
+See [STYLING.md](./STYLING.md) for restyling, and the docs site for the full
+component catalogue.
+
+## Partner extension API
+
+Customise nested components (price, stock, add-to-cart, whole card) without
+forking. See [docs/extension-api.md](docs/extension-api.md) for the full
+guide covering injection slots, cascade rules, before/after iteration slots,
+whole-card swap, ProductInfo expanded shell, and contract types.
+
+## Using composables
+
+The 15 composables are headless — reactive state + actions, no markup.
+
+```ts
+import { useCart } from 'propeller-v2-vue-ui';
+import { computed } from 'vue';
+import { graphqlClient } from '@/lib/api';
+
+const { cart, addItem, loading } = useCart({
+  graphqlClient,
+  user: computed(() => authStore.user),
+  language: computed(() => languageStore.language),
+  configuration: { imageSearchFiltersGrid: {}, imageVariantFiltersSmall: {} },
+});
+```
+
+Composables that take `user` / `companyId` / `language` expect **refs** —
+wrap props or store values with `computed()` before passing them in, so the
+composable tracks changes.
+
+The framework-agnostic cart helpers (`initCart`, `fetchActiveCart`,
+`mergeAnonymousCart`) take a `services` bundle rather than a raw client.
+
+## Styling
+
+The package ships a precompiled stylesheet — import it once:
+
+```ts
+import 'propeller-v2-vue-ui/styles.css';
+```
+
+Three override surfaces — theme tokens (CSS variables), BEM hook classes,
+and a per-instance `class` attribute. Full detail in [STYLING.md](./STYLING.md).
+
+## API reference
+
+### From `propeller-v2-vue-ui`
+
+- **SDK seam:** `createServices`, `toPlain`, `Services` (type)
+- **Provider:** `providePropeller`, `usePropellerContext`,
+  `provideProductGridConfig`, `useProductGridConfig`, `PropellerInfra` /
+  `ProductGridConfig` (types)
+- **Composables:** `useAddress`, `useAuth`, `useCart`, `useCheckout`,
+  `useClusterConfigurator`, `useCompany`, `useFavorites`, `useInfraProps`,
+  `useMenu`, `useOrders`, `useProductBundles`, `useProductInfo`,
+  `useProductSearch`, `useProductSlider`, `useProductSpecs`,
+  `usePurchaseAuthorizationConfigurator`,
+  `usePurchaseAuthorizationRequests`, `useResolvedProps`, `useServices`
+- **Utilities:** `formatPrice`, `formatDate`, `getLanguageString`,
+  `getProductImageUrl`, `getStockStatus`, `getLabel`, `isContact`,
+  `isCustomer`, … (see `src/index.ts` for the full list)
+- **60 components** — `AccountIconAndMenu` … `UserDetails`
+
+### From `propeller-v2-vue-ui/shared`
+
+The runtime-agnostic subset: `createServices`, `toPlain`, the framework-free
+utilities, and all domain types. No Vue, safe in a server context.
+
+## Building from source
+
+```bash
+npm install        # runs `prepare` → build
+npm run build      # vite build + Tailwind CSS compile
+npm run typecheck  # vue-tsc --noEmit
+npm test           # Vitest unit suite
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow and
+[TECH.md](./TECH.md) for the architecture.

package/STYLING.md

@@ -0,0 +1,119 @@
+# Styling propeller-v2-vue-ui
+
+The package ships a precompiled stylesheet (`dist/styles.css`) that bundles
+every Tailwind utility class its components reference plus the theme tokens
+those utilities resolve against. Consumers import it once:
+
+```ts
+// main.ts (or your app entry)
+import 'propeller-v2-vue-ui/styles.css';
+```
+
+If you don't want default styling at all, skip the import — every component
+will render unstyled (Tailwind classes resolve to nothing) and you'll be on
+your own.
+
+The token names and BEM hook class names are **identical** to
+`propeller-v2-react-ui`. A project running both frameworks can share a
+single stylesheet of overrides.
+
+## Three override surfaces
+
+Pick the one that matches the scope of your change.
+
+### 1. Theme tokens (most cases)
+
+The package's `:root` block declares CSS variables like `--card`,
+`--primary`, `--border`, `--radius-container`, etc. at low specificity. A
+consumer that re-declares the same variable anywhere with equal or higher
+specificity wins, and every utility that resolved against it updates
+instantly.
+
+```css
+/* your global stylesheet — re-skin the whole package without touching components */
+:root {
+  --primary:            #ff7043;  /* changes bg-primary, text-primary, … */
+  --primary-foreground: #ffffff;
+  --card:               #fafafa;
+  --border:             #e1e1e1;
+  --radius-container:   12px;
+}
+```
+
+Scope-limited overrides work too:
+
+```css
+.brand-x { --primary: #1e88e5; }
+.brand-y { --primary: #43a047; }
+```
+
+`<div class="brand-x"><ProductCard ... /></div>` and the embedded
+`bg-primary` / `text-primary` calls inside the card resolve to blue. Same
+component, different scope.
+
+Full token list (declared in `src/styles.css`): background, foreground,
+foreground-subtle, card, card-foreground, popover, popover-foreground,
+surface-hover, primary (+fg), secondary (+fg), muted (+fg), accent (+fg),
+destructive (+fg), success (+fg), warning (+fg), border, border-subtle,
+input, ring, radius, radius-control, radius-container.
+
+### 2. BEM hooks (component-specific overrides)
+
+Every styled element in every component carries a BEM class alongside its
+Tailwind utilities — `.propeller-product-card`,
+`.propeller-product-card__price`, `.propeller-breadcrumbs`, etc. The package
+emits its utilities inside `@layer utilities`, so any unlayered consumer
+rule that targets a BEM class wins by cascade order regardless of where it
+appears in the stylesheet.
+
+```css
+.propeller-product-card {
+  background: #fff8e1;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+}
+
+.propeller-product-card__price {
+  font-weight: 700;
+  color: #b45309;
+}
+
+.propeller-breadcrumbs__separator { display: none; }
+```
+
+The `@layer utilities` vs plain-rule cascade rule is part of the CSS spec —
+no `!important` required.
+
+### 3. Per-instance `class`
+
+Vue merges a `class` attribute passed to a component onto that component's
+root element automatically (standard fallthrough-attribute behaviour), so a
+one-off override is a regular attribute:
+
+```vue
+<ProductCard :product="p" class="bg-yellow-100 ring-2 ring-yellow-400" />
+<Breadcrumbs :categoryPath="[]" currentLabel="Home" class="text-sm text-muted-foreground" />
+```
+
+The consumer's class is merged with the component's base classes — it adds
+to them, it does not replace them. To *strip* a default, use the BEM hook
+approach.
+
+## What does NOT work
+
+- **No replacing internal markup.** Use slots where a component exposes
+  them; otherwise the component's structure is fixed. Re-skin via tokens or
+  BEM hooks.
+- **No global `@apply` directives that target package classes from the
+  host's Tailwind config.** The package's `bg-card` etc. are not registered
+  in your `@apply` resolver — they only exist in `dist/styles.css`. Write a
+  host-side override as plain CSS targeting the BEM hook.
+- **No theme tokens you didn't declare.** Tailwind v4 utility classes that
+  reference tokens absent from the cascade resolve to nothing. Declare any
+  custom token in your own `@theme` block.
+
+## Tailwind dependency
+
+The package's styles compile to vanilla CSS at build time. **Consumers do
+NOT need Tailwind** to use the package — `dist/styles.css` works in any Vue
+project. If you also use Tailwind, importing the package's CSS doesn't
+conflict; your own Tailwind output is a separate stylesheet.