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

package/CHANGELOG.md

@@ -0,0 +1,549 @@
+# Changelog
+
+All notable changes to `propeller-v2-vue-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.3.14] - 2026-06-09
+
+### Fixed
+
+- **`FavoriteListDetails` stuck on "Loading..." forever** when the consumer
+  doesn't pass `:graphqlClient` / `:user` / `:configuration` explicitly. Routed
+  every infra read through `useInfraProps`.
+- **`PurchaseAuthorizationRequests` rendered no rows** for the same reason.
+  Routed every infra read through `useInfraProps`.
+
+## [0.3.13] - 2026-06-09
+
+### Fixed
+
+Three more components silently ignored the documented "resolve from
+`<PropellerProvider>`" contract because they read infrastructure off
+`props.*` directly instead of through `useInfraProps`. Consumers that follow
+the contract and DON'T pass these props (e.g. propeller-vue) got broken
+features with no error. This is the same class of bug as 0.3.8 / 0.3.9 and
+brings the Vue package to parity with `propeller-v2-react-ui`, whose
+`ProductSlider` / `ProductGrid` already resolve these via `useInfraProps`:
+
+- **`ProductGrid` never fetched on the client.** It passed `props.graphqlClient`
+  to `useProductSearch`; with no client the fetch short-circuits, so the grid
+  only ever showed SSR-seeded items and went empty on every client-side
+  category/search navigation (products "only appeared after a hard refresh").
+  Now resolves `graphqlClient`, `configuration`, `user`, `companyId`,
+  `language`, `includeTax`, `portalMode` via `useInfraProps`; nested
+  ProductCard/ClusterCard pass-throughs read the resolved values too.
+  (Complements the 0.3.12 `useProductSearch` watcher-timing fix — that made
+  the fetch *fire* on SPA nav; this gives it a *client* to fire with.)
+
+- **`ProductSlider` rendered nothing on PDP / cluster pages.** Same root cause:
+  `props.graphqlClient` was undefined, so the crossupsell fetch threw, was
+  swallowed, and the cross/up-sell sliders never appeared. Now resolves infra
+  via `useInfraProps`. `graphqlClient` and `language` props relaxed to optional.
+
+- **`AccountIconAndMenu` stayed in its signed-out state forever.** It called
+  `useInfraProps` but the template/helpers still read `props.user`, which is
+  `undefined` for provider-driven consumers — so the header dropdown kept
+  showing the login form after login, and the account-page sidebar variant
+  rendered empty. Template + `getUserName()` + the menu-close watch now read a
+  script-level `const user = computed(() => infra.user ?? null)`. Also removed
+  a stray debug `console.log` from `handleIconClick`.
+
+## [0.3.12] - 2026-06-09
+
+### Fixed
+
+- **`useProductSearch` stayed stuck on the previous category's data after
+  an SPA navigation between catalog pages.** The composable's input watcher
+  fired when `categoryId` changed, but early-returned via
+  `if (!isControlled.value) fetchProducts()` because `isControlled` was still
+  `true` at that tick — the parent boilerplate's flip from controlled mode
+  (SSR-seeded items) to uncontrolled mode (`:products="undefined"`) was queued
+  in a separate, later-flushing watcher. Once controlled mode flipped off,
+  no input the composable tracked had changed again, so the fetch that
+  should have run for the new category never started. The visible symptom
+  was an empty "No products found" grid on the destination category until
+  the user pressed F5 (which re-ran SSR and re-seeded the new category).
+  Added `isControlled` to the watcher's tracked sources so a parent that
+  flips controlled mode off re-fires the watcher with the now-uncontrolled
+  flag and the deferred fetch runs.
+- **`UserDetails` template tripped vue-tsc in CI** with `TS18048:
+  '__VLS_ctx.user' is possibly 'undefined'`. The 0.3.11 fix switched the
+  `user` prop to optional and added a script-level `const user = computed(...)`
+  resolved via `useInfraProps`, but the template binding for the email field
+  still read `{{ user.email }}` unconditionally. Switched to `{{ user?.email }}`,
+  matching the optional-chaining pattern the rest of the template
+  (`getActiveCompany()?.name`, etc.) already uses.
+
+## [0.3.11] - 2026-06-09
+
+### Fixed
+
+- **`UserDetails` crash on the account dashboard** (`TypeError: Cannot read
+  properties of undefined (reading 'email')`). Mirror of the 0.3.9
+  `CompanySwitcher` fix: the template binds to `user.email` via Vue's
+  auto-exposed `props.user`; consumers that follow the documented "resolve
+  from `<PropellerProvider>`" contract and don't pass `:user` blew up the
+  render. Wired `useInfraProps(props)` + a script-level `const user = computed(...)`
+  that overrides the auto-exposure with the provider fallback. Switched
+  the `user` prop to optional.
+
+## [0.3.10] - 2026-06-09
+
+### Fixed
+
+- **`ProductInfo` rendered an empty image/badges column on every legacy call
+  site.** The `useNewShell` heuristic — which decides whether to render the
+  composable PDP shell or the legacy SKU+title block — included the nine
+  Boolean `show*` props in its presence check (`props[k] !== undefined`).
+  Vue 3 runtime-normalizes any declared Boolean prop the parent doesn't pass
+  to `false`, not `undefined`, so every consumer doing
+  `<ProductInfo :product="…" />` flipped the heuristic to the new shell.
+  Inside the new shell the per-slot `v-if="show* !== false"` then evaluated
+  `false !== false` → `false`, so the image, badges, favourite, price, stock,
+  add-to-cart, bundles, bulk-prices and surcharges sections silently
+  skipped their default content — the visible symptom was an empty
+  `propeller-product-info__media` column on the PDP. Removed the Boolean
+  `show*` keys from `NEW_SHELL_KEYS`; only `*Component` injection props now
+  opt the consumer into the new shell. The per-section `show*` flags still
+  work inside the new shell once it is opted into.
+
+## [0.3.9] - 2026-06-09
+
+### Fixed
+
+- **`CompanySwitcher` crash on first render after login** (`TypeError: Cannot
+  read properties of undefined (reading 'companies')`). The component read
+  `props.user.companies` directly without falling back to the propellerVue
+  plugin scope or guarding against `user === undefined`, so any consumer that
+  relied on the documented "resolved from `<PropellerProvider>`" contract
+  blew up Vue's render. Wired `useInfraProps(props)`, switched the `user`
+  prop to optional, and added a `(infra.user ?? props.user)` guard.
+- **`CartIconAndSidebar` silent no-op + reactivity gaps.** Same provider
+  gap: `useCart` received `props.graphqlClient!` (undefined → SDK crash on
+  any drawer mutation), and `showCheckoutButton` / `showRequestAuthorizationButton`
+  + currency formatting all read `props.user` / `props.companyId` /
+  `props.currency` directly. Routed every infra read through `useInfraProps`
+  so AppHeader can mount the drawer with just `:cart="..."` and have
+  everything else resolve.
+
+## [0.3.8] - 2026-06-09
+
+### Fixed
+
+- **`LoginForm`, `AccountIconAndMenu`, `AddToCart`, `CartItem` silently no-op
+  when the consumer doesn't pass `:graphqlClient` explicitly.** These four
+  components were reading `props.graphqlClient` directly instead of resolving
+  it through `useInfraProps` / `useResolvedProps`, so the value never fell
+  back from the `propellerVue` plugin scope. The login button submitted
+  nothing, PDP "Add to cart" did nothing, and the cart row +/- / delete
+  buttons did nothing — every handler hit a `if (!props.graphqlClient) return;`
+  guard.
+  - `LoginForm.vue`: added `useInfraProps(props)` and routed `useAuth` +
+    the submit guard through it.
+  - `AccountIconAndMenu.vue`: added `useInfraProps(props)` and passes
+    `infra.graphqlClient` to the embedded `<LoginForm>`.
+  - `AddToCart.vue`: added `useInfraProps(props)` and routes `useCart`
+    + the submit guard through it.
+  - `CartItem.vue`: extended `RESOLVE_SPEC` with the Tier 1 infra keys
+    (`graphqlClient`, `user`, `companyId`, `configuration`, `language`,
+    `currency`, `includeTax`) so the spec matches `ProductCard` /
+    `ClusterCard`. Direct-prop precedence preserved.
+
+## [0.3.7] - 2026-06-08
+
+### Fixed
+
+- **SSR crash on catalog pages when consumer omits `:configuration` prop.**
+  `ProductCard.getProductUrl()`, `ClusterCard.getClusterUrl()`, and
+  `Breadcrumbs.getCategoryUrl()` dereferenced `props.configuration.urls`
+  without optional chaining, throwing `Cannot read properties of undefined
+  (reading 'urls')` at SSR time. Guarded all three with `?.urls?.` and a
+  `?? '#'` fallback so the components render harmlessly when the consumer
+  hasn't wired `:configuration` through (e.g. on `<ProductGrid>` cards
+  inside SearchView / CategoryView). Matches the guard `CartItem` already
+  had. No API change.
+
+## [0.3.6] - 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 121 source +
+  test files (incl. `.vue` SFCs) 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.3.5] - 2026-06-04
+
+### Fixed
+
+- **`CartItem` now resolves product / bundle / crossupsell / cluster
+  option 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'` / `'Option'`. Previously each template
+  binding and 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.3.4] - 2026-06-03
+
+**Menu pre-fetch fix.** `<Menu :tree="...">` previously treated *any*
+array (including `[]`) as a successful host pre-fetch and locked itself
+into the empty state — no client-side fallback fetch, no recovery.
+
+This bit SSR setups whose `lib/server.ts` `fetchMenu` swallows errors
+and returns `[]` by design (so a transient backend hiccup doesn't break
+the whole render). The consumer stored the empty result in its menu
+store, AppHeader passed `:tree="[]"`, and `<Menu>` showed
+"No categories found" with no way out, even after the backend recovered.
+
+### Changed
+
+- `hasPrefetchedTree` now requires `props.tree` to be a NON-empty array.
+  `[]` is no longer treated as a pre-fetch; the component falls back to
+  its internal `useMenu` fetch, which can succeed where the SSR
+  pre-fetch failed. A legitimately-empty backend still renders the
+  empty state because the client fetch also returns `[]`.
+
+## [0.3.2] - 2026-06-03
+
+**Reactivity fix** for the provider snapshot. After 0.3.1 fixed the
+`inject()`-inside-`computed` bug, components that read infra props via
+`useInfraProps()` still went stale on provider updates. Symptom:
+`AccountIconAndMenu` rendered the anonymous state until the page was
+refreshed after login — `auth.user` updated on the store and propagated
+into `<PropellerProvider :user>`, but the package-side `AccountIconAndMenu`
+kept reading the old value.
+
+Root cause: `usePropellerContext()` returned `{ ...deps, ...scope, userMode }`
+— spreading the reactive `scope` snapshotted its current values into a
+plain object. `useInfraProps()` (correctly) caches that object at setup,
+so every subsequent infra read was reading a frozen copy and missed all
+provider updates.
+
+### Changed
+
+- **`usePropellerContext()` / `useRequiredPropellerContext()`** now build
+  the composite via getters that pierce through to the live reactive
+  scope (user, companyId, language, includeTax, portalMode, userMode).
+  Consumers that capture the returned object at setup keep getting live
+  reads — login / language switch / VAT toggle propagate without a
+  refresh. No call-site changes required.
+
+### Verification
+
+- `vue-tsc --noEmit` clean.
+- `npm run test` — 183 tests pass unchanged (none asserted on the
+  snapshot semantics, so no test churn).
+- Manual smoke: scaffolded `vue-shop` from the accelerator + logged in
+  via AccountIconAndMenu's embedded form → menu re-renders to the
+  authenticated layout on the same page tick, no refresh required.
+
+## [0.3.1] - 2026-06-02
+
+**Critical fix** for the 0.3.0 retrofit. The previous release wrapped
+`useInfraProps(props)` in `computed(() => useInfraProps(props))` in
+every component. The composable internally calls Vue's `inject()`, which
+only works inside `setup()`. When the computed re-ran later (during a
+click handler, an effect, or any reactive recalc), `inject()` returned
+the default value (`null`) and the component silently lost its provider
+context — graphqlClient, user, language, configuration all undefined.
+
+Symptom in 0.3.0: **anonymous "Add to cart" did nothing**. The
+`handleAddToCart` early-returns when `infra.value.graphqlClient` is
+falsy. Logged-in flows that happened to capture the resolved infra on
+the very first synchronous read during setup looked fine until any
+reactive dependency invalidated the computed.
+
+### Changed
+
+- **`useInfraProps()`** now resolves the `PropellerContext` exactly once
+  at setup time (where `inject()` is legal) and returns a `reactive`
+  object whose infra-key reads forward to either the live prop or the
+  ctx snapshot. Reactivity is preserved (the provider scope is itself
+  reactive) without a wrapping computed.
+- **All 51 retrofitted components** change from
+  `const infra = computed(() => useInfraProps(props))` →
+  `const infra = useInfraProps(props)`, and every `infra.value.X` →
+  `infra.X`. No behaviour change on the happy path; the previously
+  broken late-read path now works.
+
+### Verification
+
+- `vue-tsc --noEmit` clean.
+- 22 / 22 vitest pass.
+- `npm run build` emits identical dts shape.
+- Browser repro of anonymous AddToCart on the cluster page in
+  propeller-vue now logs `infra.graphqlClient` truthy and reaches
+  `addItem` → `initCart` → cart creation.
+
+## [0.3.0] - 2026-06-02
+
+Wires every component into the existing `<PropellerProvider>` via the
+`useInfraProps()` composable. Consumers can now omit Tier 1 / Tier 2
+infra props (`graphqlClient`, `services`, `user`, `companyId`,
+`language`, `includeTax`, `currency`, `configuration`, `portalMode`) and
+the component resolves them from the provider — bringing the Vue
+package in line with what React UI already did in 30 of its 66
+components.
+
+Before 0.3.0, only `CartBonusItems` and `OrderBonusItems` honoured the
+provider; the other 50 components required every infra prop to be
+passed by the consumer at every render site. After 0.3.0, all 52
+components resolve from the provider as a fallback. Explicit props still
+win — call sites that pass values keep their previous behaviour
+unchanged.
+
+### Changed
+
+- **52 components** now wrap their `props` through
+  `useInfraProps(props)` in a `computed`, matching the canonical
+  `CartBonusItems.vue` pattern. The full list:
+  `AccountIconAndMenu`, `ActionCode`, `AddToCart`, `AddToFavorite`,
+  `AddressSelector`, `Breadcrumbs`, `CartCarriers`, `CartIconAndSidebar`,
+  `CartItem`, `CartPaymethods`, `CartSummary`, `CategoryDescription`,
+  `CategoryShortDescription`, `ClusterCard`, `ClusterInfo`,
+  `ClusterOptions`, `CompanySwitcher`, `FavoriteListDetails`,
+  `FavoriteListItem`, `FavoriteLists`, `ForgotPassword`, `GridFilters`,
+  `GridToolbar`, `ItemsOverview`, `LoginForm`, `Menu`, `OrderActions`,
+  `OrderItemCard`, `OrderList`, `OrderSummary`, `OrderTotals`,
+  `ProductBulkPrices`, `ProductBundles`, `ProductCard`,
+  `ProductDescription`, `ProductDownloads`, `ProductGrid`, `ProductInfo`,
+  `ProductPrice`, `ProductShortDescription`, `ProductSlider`,
+  `ProductSpecifications`, `ProductTabs`, `ProductVideos`, `QuoteActions`,
+  `PurchaseAuthorizationConfigurator`, `PurchaseAuthorizationRequests`,
+  `RegisterForm`, `SearchBar`, `UserDetails`.
+- Template forwards inside `ProductCard.vue` and `ProductGrid.vue` that
+  passed `:foo="props.X"` to child components now pass `:foo="infra.X"`
+  so the explicit-or-provider value flows uniformly down the tree.
+- Three components grew a shadow `const X = computed(() => infra.value.X)`
+  binding (`AccountIconAndMenu`, `AddToFavorite`, `UserDetails`)
+  because their templates reference the infra value bare
+  (`v-if="user"`, `{{ user.email }}`) and Vue's setup-binding lookup
+  needs a setup-scope ref to read from.
+
+### Migration
+
+Existing consumers that pass all infra props keep working unchanged —
+the resolver's contract is "explicit wins, otherwise provider, otherwise
+undefined." Consumers should now feel free to drop redundant prop passes
+where `<PropellerProvider>` wraps the subtree.
+
+A follow-up cleanup PR in `propeller-vue` will prune the ~245 redundant
+prop-lines its views currently pass, starting with `ProductDetailView`,
+`CategoryView`, and `CartView`.
+
+### Verification
+
+- `vue-tsc --noEmit` clean.
+- 22 / 22 vitest tests pass unchanged.
+- `npm run build` emits identical dts shape (infra prop types were
+  already optional in 0.2.0; the change is purely internal wiring).
+
+## 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?`, `addToCartLabels?` for forwarding translations to embedded `<ProductCard>` / `<ClusterCard>` / inner `<AddToCart>`. Mirrors the existing `stockLabels?` 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 options use the enum value as the slug. All fallbacks preserve existing English behavior, so the change is non-breaking.
+
+### Fixed
+
+- `ProductSlider` no longer forwards its own `labels` (slider-UI slugs) to embedded `ClusterCard` / `ProductCard` — that previously caused card-level strings to fail translation. Use the new `clusterCardLabels?` / `productCardLabels?` props instead.
+
+## [0.2.0] - 2026-06-01
+
+Adds shop-mode-aware user gating. Mirrors the React UI change. 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()` composable**. 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-vue`
+storefront so the Propeller Commerce Vue surface can be consumed as a
+standalone library. The Vue mirror of `propeller-v2-react-ui`. Not yet
+published to a registry — consumed via a `file:` link or `github:` URL
+during stabilization.
+
+### Added
+
+- **Initial extraction.** 60 components, the 15 Vue composables, the
+  runtime-agnostic `composables/shared/` layer (utilities and domain
+  types), and the three reactive shared wrappers (`usePagination`,
+  `useServiceFetch`, `useUserIdentity`) moved into this package from
+  `propeller-vue`.
+- **Build pipeline.** Vite library mode (`@vitejs/plugin-vue` +
+  `vite-plugin-dts`) produces dual ESM + CJS bundles with `.d.ts`
+  declarations. Unlike the React package there is no `"use client"`
+  banner — Vue has no such directive.
+- **Three entry points.** `propeller-v2-vue-ui` (components, composables,
+  the provider, `createServices`, `toPlain`); `propeller-v2-vue-ui/shared`
+  (pure TS — `createServices`, `toPlain`, formatters, helpers, all domain
+  types — safe to import from a Nuxt server context or a build script);
+  and `propeller-v2-vue-ui/pure` (SSR-safe presentational components —
+  `ProductPrice`, `ItemStock`, `GridTitle`, `OrderTotals`, … — with no
+  composables and no browser APIs, cheap to render into an SSR shell).
+  Mirrors `propeller-v2-react-ui`'s `/pure` entry component-for-component.
+- **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. Token names and BEM hook class names are kept identical to
+  `propeller-v2-react-ui`.
+- **Three styling override surfaces** — theme tokens (CSS variables), BEM
+  hooks, and per-instance `class`. Documented in [STYLING.md](./STYLING.md).
+- **`providePropeller` / `usePropellerContext`** — the single integration
+  point, a `provide`/`inject` provider. `providePropeller(value)` installs
+  the `PropellerInfra` (carrying `graphqlClient`, `services`, `user`,
+  `companyId`, `language`, `includeTax`, `currency`, `configuration`,
+  `portalMode`). Imports zero host code.
+- **`provideProductGridConfig` / `useProductGridConfig`** — Tier-2 grid
+  config provider used by `ProductGrid` to collapse ~20 cascaded props on
+  `ProductCard` / `ClusterCard`.
+- **`createServices(client)`** — factory that builds the typed `Services`
+  bundle (`product`, `cart`, `user`, `order`, …) keyed to a
+  consumer-built `GraphQLClient`. Memoized per client via `WeakMap`.
+  Copied verbatim from `propeller-v2-react-ui` — pure, framework-agnostic.
+- **`toPlain(value)`** — recursively strips the SDK's underscore-prefixed
+  backing fields from class instances.
+- **`useServices()`** — reads the `Services` bundle from the provider;
+  throws a clear error when used outside `providePropeller()`.
+- **`useInfraProps()` / `useResolvedProps()`** — resolve component props
+  against the provider (and the grid config) with explicit-prop-wins
+  precedence. New to the Vue surface (the React package had them; the Vue
+  composables did not).
+- 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 framework-free shared utilities.
+  13 test files, 183 tests, ported from `propeller-v2-react-ui`.
+- **CI pipeline** (`.gitlab-ci.yml`). A `verify` stage (typecheck, unit
+  tests + coverage, build), a `downstream` stage that builds the package
+  and runs `propeller-vue`'s Playwright e2e suite against it (the
+  component regression gate), and a `mirror` stage that mirrors to the
+  public GitHub repo.
+- **Storybook** (`.storybook/`, Storybook 9 + `@storybook/vue3-vite`). A
+  story per component (60 total), rendering each in isolation against
+  fixture data and a mock provider. Mock foundation in `src/__mocks__/`
+  (`fixtures.ts`, `mockServices.ts`, `decorators.ts`).
+- **Documentation site** (`docs/`). A self-contained Docusaurus 3 app —
+  hand-written MDX guides, a six-page **API integration** section
+  (`guides/api/`) explaining how the composables reach the GraphQL
+  backend domain by domain, and a **generated TypeDoc API reference**
+  (`content/api/`, rebuilt by `npm run gen:api` from the package's
+  pure-TS headless surface — composables, provider, SDK seam, utilities
+  and types). The `.vue` components' prop tables stay in Storybook, since
+  TypeDoc cannot parse Single-File Components. Not published, not in the
+  package build.
+
+- **`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 `entry-server.ts`'s always-on prefetch) and have
+  the menu HTML land in the initial response. Omitting the prop preserves
+  the legacy client-side fetch behaviour — no breaking change.
+- **`MenuCategory` type exported from `/shared`.** Type-only re-export so
+  server modules (e.g. a host's `lib/server.ts`) can build the tree without
+  pulling the Vue composable's runtime into the server bundle.
+
+### Changed
+
+- **Decoupled the SDK seam from the host (vs the in-app original).** Every
+  composable previously did `new XxxService(graphqlClient)` inline (57
+  call sites). They now resolve services through the memoized
+  `createServices(graphqlClient)` factory. The package ships no
+  `graphqlClient` singleton, no hardcoded endpoint, and reads no
+  `import.meta.env`. The consumer constructs its own `GraphQLClient`,
+  calls `createServices(client)`, and installs both via
+  `providePropeller`.
+- **Removed host coupling from components.** `ProductCard` no longer
+  imports `vue-router` (navigation via the `onProductClick` callback prop,
+  with a native location fallback). `SearchBar` and `CartIconAndSidebar`
+  no longer import `localizeHref` from the host config — URLs come from
+  the `configuration` prop's url builders. `AddToCart` and
+  `CartIconAndSidebar` use a plain `<a>` instead of `<router-link>`.
+
+### Fixed
+
+- **~186 pre-existing type errors.** The original `propeller-vue` excluded
+  `components/propeller/` from its `vue-tsc` run, so the 60 components were
+  never type-checked. This package type-checks the whole surface;
+  `vue-tsc --noEmit` is clean. The bulk were inline event handlers using
+  `e.target.value` on the bare `EventTarget` type (fixed with an
+  `HTMLInputElement` cast) plus assorted SDK type-name and narrowing
+  corrections.

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.