@vitrine-kit/vitrine 0.4.1 → 0.5.0

package/kit/registry/wishlist/files/components/wishlist/WishlistButton.tsx

@@ -0,0 +1,37 @@
+'use client';
+import { useEffect, useState } from 'react';
+import type { Product } from '@vitrine-kit/contracts';
+import { isWishlisted, toggleWishlist } from '../../lib/wishlist/storage.js';
+
+export interface WishlistButtonProps {
+  product?: Product;
+}
+
+export function WishlistButton({ product }: WishlistButtonProps) {
+  const slug = product?.slug;
+  const [on, setOn] = useState(false);
+
+  useEffect(() => {
+    if (!slug) return;
+    setOn(isWishlisted(slug));
+    const sync = () => setOn(isWishlisted(slug));
+    window.addEventListener('vitrine:wishlist', sync);
+    window.addEventListener('storage', sync);
+    return () => {
+      window.removeEventListener('vitrine:wishlist', sync);
+      window.removeEventListener('storage', sync);
+    };
+  }, [slug]);
+
+  if (!slug) return null;
+
+  return (
+    <button
+      type="button"
+      className="vt-wishlist-button w-fit text-sm text-muted-fg underline underline-offset-2 transition hover:text-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+      onClick={() => setOn(toggleWishlist(slug).includes(slug))}
+    >
+      {on ? 'Remove from wishlist' : 'Add to wishlist'}
+    </button>
+  );
+}

package/kit/registry/wishlist/files/components/wishlist/WishlistIndicator.tsx

@@ -0,0 +1,30 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { readWishlist } from '../../lib/wishlist/storage.js';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
+
+export function WishlistIndicator() {
+  const [count, setCount] = useState(0);
+  const label = useChromeLabel('wishlist');
+
+  useEffect(() => {
+    const sync = () => setCount(readWishlist().length);
+    sync();
+    window.addEventListener('vitrine:wishlist', sync);
+    window.addEventListener('storage', sync);
+    return () => {
+      window.removeEventListener('vitrine:wishlist', sync);
+      window.removeEventListener('storage', sync);
+    };
+  }, []);
+
+  return (
+    <a
+      href="/wishlist"
+      className="vt-wishlist-indicator text-fg transition hover:text-primary focus-visible:outline-none focus-visible:ring-2 ring-ring"
+    >
+      {label}
+      {count > 0 ? ` (${count})` : ''}
+    </a>
+  );
+}

package/kit/registry/wishlist/files/components/wishlist/WishlistView.tsx

@@ -0,0 +1,73 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { readWishlist, writeWishlist } from '../../lib/wishlist/storage.js';
+
+interface WishItem {
+  slug: string;
+  title?: string;
+}
+
+export function WishlistView() {
+  const [items, setItems] = useState<WishItem[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const slugs = readWishlist();
+    if (slugs.length === 0) {
+      setItems([]);
+      setLoading(false);
+      return;
+    }
+    Promise.all(
+      slugs.map(async (slug) => {
+        try {
+          const res = await fetch(`/api/products?where[slug][equals]=${encodeURIComponent(slug)}&limit=1`);
+          if (!res.ok) return { slug };
+          const data = (await res.json()) as { docs?: Array<{ title?: string }> };
+          return { slug, title: data.docs?.[0]?.title };
+        } catch {
+          return { slug };
+        }
+      }),
+    ).then((list) => {
+      setItems(list);
+      setLoading(false);
+    });
+  }, []);
+
+  if (loading) return <p className="text-muted-fg">Loading wishlist…</p>;
+
+  if (items.length === 0) {
+    return (
+      <div className="flex flex-col gap-gutter">
+        <p className="text-muted-fg">Your wishlist is empty.</p>
+        <a href="/" className="w-fit text-fg underline underline-offset-2">
+          Browse catalog
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <ul role="list" className="flex flex-col gap-gutter">
+      {items.map((item) => (
+        <li key={item.slug} className="flex items-center justify-between gap-gutter border-b border-border py-unit">
+          <a href={`/products/${item.slug}`} className="text-fg underline-offset-2 hover:underline">
+            {item.title ?? item.slug}
+          </a>
+          <button
+            type="button"
+            className="text-sm text-muted-fg underline underline-offset-2 hover:text-fg"
+            onClick={() => {
+              const next = readWishlist().filter((s) => s !== item.slug);
+              writeWishlist(next);
+              setItems((prev) => prev.filter((p) => p.slug !== item.slug));
+            }}
+          >
+            Remove
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/kit/registry/wishlist/files/lib/wishlist/register.ts

@@ -0,0 +1,8 @@
+import { registerSlot } from '@vitrine-kit/core';
+import { WishlistButton } from '../../components/wishlist/WishlistButton.js';
+import { WishlistIndicator } from '../../components/wishlist/WishlistIndicator.js';
+
+export function registerWishlistSlots(): void {
+  registerSlot({ slot: 'product.below-price', component: WishlistButton, order: 20 });
+  registerSlot({ slot: 'global.header-actions', component: WishlistIndicator, order: 15 });
+}

package/kit/registry/wishlist/files/lib/wishlist/storage.ts

@@ -0,0 +1,30 @@
+// localStorage wishlist of product slugs. Pure browser helper — no server.
+const KEY = 'vitrine_wishlist';
+
+export function readWishlist(): string[] {
+  if (typeof window === 'undefined') return [];
+  try {
+    const raw = window.localStorage.getItem(KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw) as unknown;
+    return Array.isArray(parsed) ? parsed.filter((x): x is string => typeof x === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+export function writeWishlist(slugs: string[]): void {
+  window.localStorage.setItem(KEY, JSON.stringify([...new Set(slugs)]));
+  window.dispatchEvent(new Event('vitrine:wishlist'));
+}
+
+export function toggleWishlist(slug: string): string[] {
+  const current = readWishlist();
+  const next = current.includes(slug) ? current.filter((s) => s !== slug) : [...current, slug];
+  writeWishlist(next);
+  return next;
+}
+
+export function isWishlisted(slug: string): boolean {
+  return readWishlist().includes(slug);
+}

package/kit/templates/backend-payload/files/Dockerfile

@@ -25,5 +25,8 @@ WORKDIR /app
 COPY --from=build /app/public ./public
 COPY --from=build /app/.next/standalone ./
 COPY --from=build /app/.next/static ./.next/static
+# Demo seed + uploads (SEED_ON_BOOT); media is also a named volume in compose.
+COPY --from=build /app/seed-assets ./seed-assets
+RUN mkdir -p /app/media
 EXPOSE 3000
 CMD ["node", "server.js"]

package/kit/templates/backend-payload/files/docker-compose.yml

@@ -1,5 +1,6 @@
 # Reference Vitrine deployment on a VPS: app (Next+Payload) + Postgres.
 # Run: PAYLOAD_SECRET=... docker compose up --build
+# First boot seeds demo catalog + admin when SEED_ON_BOOT=1 (default here).
 services:
   db:
     image: postgres:16-alpine
@@ -25,11 +26,18 @@ services:
       DATABASE_URL: postgres://vitrine:${POSTGRES_PASSWORD:-vitrine}@db:5432/vitrine
       PAYLOAD_SECRET: ${PAYLOAD_SECRET:?set PAYLOAD_SECRET}
       NEXT_PUBLIC_SITE_URL: ${NEXT_PUBLIC_SITE_URL:-http://localhost:3000}
+      SEED_ON_BOOT: ${SEED_ON_BOOT:-1}
+      DEV_ADMIN_EMAIL: ${DEV_ADMIN_EMAIL:-admin@example.com}
+      DEV_ADMIN_PASSWORD: ${DEV_ADMIN_PASSWORD:-}
+      EMAIL_FROM: ${EMAIL_FROM:-noreply@localhost}
     ports:
       - '3000:3000'
+    volumes:
+      - media:/app/media
     depends_on:
       db:
         condition: service_healthy
 
 volumes:
   pgdata:
+  media:

package/kit/templates/backend-payload/files/lib/adapter/payload-catalog.ts

@@ -9,19 +9,25 @@ import type {
   ProductSort,
 } from '@vitrine-kit/contracts';
 import { mapCategory, mapProduct } from './map.js';
+import { applyProductQuery } from './product-query.js';
 import type { ProductDoc, VariantDoc } from './payload-types.js';
 
 function sortExpr(sort?: ProductSort): string {
+  // Price sorts are applied in memory after variants load (see applyProductQuery).
   switch (sort) {
     case 'price-asc':
-      return 'createdAt'; // price lives in the variants collection — price sorting is provided by the filters feature
     case 'price-desc':
+    case 'relevance':
       return '-createdAt';
-    default: // newest and unspecified sort
+    default:
       return '-createdAt';
   }
 }
 
+function localeOpt(locale?: string): { locale?: string } {
+  return locale ? { locale } : {};
+}
+
 export class PayloadCatalogSource implements CatalogSource {
   constructor(
     private readonly payload: Payload,
@@ -39,41 +45,69 @@ export class PayloadCatalogSource implements CatalogSource {
   }
 
   async listProducts(query: ProductQuery = {}): Promise<Product[]> {
-    const where = query.category ? { 'categories.slug': { equals: query.category } } : {};
+    const where: Record<string, unknown> = {};
+    if (query.category) {
+      where['categories.slug'] = { equals: query.category };
+    }
+    // Prefer DB-side title match when searching; applyProductQuery also matches description.
+    if (query.search?.trim() && !query.filters && query.priceMin == null && query.priceMax == null) {
+      where.title = { like: query.search.trim() };
+    }
+
+    // When filtering by variant options/price or sorting by price, pull a wider page then refine.
+    const needsMemoryPass =
+      Boolean(query.filters && Object.keys(query.filters).length > 0) ||
+      query.priceMin != null ||
+      query.priceMax != null ||
+      query.sort === 'price-asc' ||
+      query.sort === 'price-desc' ||
+      query.sort === 'relevance';
+
+    const limit = needsMemoryPass ? Math.max(query.perPage ?? 24, 100) : (query.perPage ?? 24);
     const res = await this.payload.find({
       collection: 'products',
       where,
       depth: 1,
-      limit: query.perPage ?? 24,
-      page: query.page ?? 1,
+      limit,
+      page: needsMemoryPass ? 1 : (query.page ?? 1),
       sort: sortExpr(query.sort),
+      ...localeOpt(query.locale),
     });
-    return Promise.all(res.docs.map((d) => this.withVariants(d as unknown as ProductDoc)));
+    let products = await Promise.all(res.docs.map((d) => this.withVariants(d as unknown as ProductDoc)));
+    products = applyProductQuery(products, query);
+
+    if (needsMemoryPass) {
+      const page = query.page ?? 1;
+      const perPage = query.perPage ?? 24;
+      const start = (page - 1) * perPage;
+      return products.slice(start, start + perPage);
+    }
+    return products;
   }
 
-  async getProduct(slug: string): Promise<Product | null> {
+  async getProduct(slug: string, locale?: string): Promise<Product | null> {
     const res = await this.payload.find({
       collection: 'products',
       where: { slug: { equals: slug } },
       depth: 1,
       limit: 1,
+      ...localeOpt(locale),
     });
     const doc = res.docs[0];
     return doc ? this.withVariants(doc as unknown as ProductDoc) : null;
   }
 
-  async listCategories(): Promise<Category[]> {
-    const res = await this.payload.find({ collection: 'categories', depth: 0, limit: 200 });
+  async listCategories(locale?: string): Promise<Category[]> {
+    const res = await this.payload.find({
+      collection: 'categories',
+      depth: 0,
+      limit: 200,
+      ...localeOpt(locale),
+    });
     return res.docs.map((d) => mapCategory(d as unknown as never));
   }
 
-  async search(term: string): Promise<Product[]> {
-    const res = await this.payload.find({
-      collection: 'products',
-      where: { title: { like: term } },
-      depth: 1,
-      limit: 24,
-    });
-    return Promise.all(res.docs.map((d) => this.withVariants(d as unknown as ProductDoc)));
+  async search(term: string, locale?: string): Promise<Product[]> {
+    return this.listProducts({ search: term, sort: 'relevance', perPage: 24, locale });
   }
 }

package/kit/templates/backend-payload/files/lib/adapter/payload-commerce.ts

@@ -72,6 +72,15 @@ export class PayloadCommerceBackend implements CommerceBackend {
       id: variantId,
       depth: 1,
     })) as unknown as VariantDoc;
+    if (typeof variant.stock === 'number') {
+      if (variant.stock <= 0) throw new Error('[vitrine] variant is out of stock');
+      const alreadyInCart = cart.lines
+        .filter((l) => l.variantId === String(variant.id))
+        .reduce((sum, l) => sum + l.quantity, 0);
+      if (alreadyInCart + qty > variant.stock) {
+        throw new Error('[vitrine] not enough stock for this variant');
+      }
+    }
     const product = variant.product && typeof variant.product === 'object' ? (variant.product as ProductDoc) : null;
     const firstImage =
       product?.images && product.images.length > 0 && typeof product.images[0] === 'object'
@@ -120,6 +129,15 @@ export class PayloadCommerceBackend implements CommerceBackend {
     const current = await this.getCart(cartId);
     if (!current || current.lines.length === 0) throw new Error('[vitrine] cart is empty');
     const cart = await this.reprice(current);
+    for (const line of cart.lines) {
+      const variant = (await this.payload
+        .findByID({ collection: 'variants', id: line.variantId })
+        .catch(() => null)) as unknown as VariantDoc | null;
+      if (!variant) throw new Error('[vitrine] a cart line refers to a missing variant');
+      if (typeof variant.stock === 'number' && line.quantity > variant.stock) {
+        throw new Error('[vitrine] not enough stock for this variant');
+      }
+    }
     // The active provider (Stripe/Paddle/YooKassa) is resolved by integrations.payments;
     // its checkout-<provider> feature registered it in the registry via lib/payments.ts.
     return payments.resolve(this.siteConfig).createCheckout({ cart, baseUrl: this.baseUrl });

package/kit/templates/backend-payload/files/lib/adapter/product-query.ts

@@ -0,0 +1,126 @@
+// Pure ProductQuery helpers — filter/sort in memory after the adapter loads products.
+// Price lives on variants, so Payload cannot ORDER BY price in SQL without a denormalized
+// field; this keeps the contract honest for catalog-sized datasets.
+import type { Product, ProductQuery, ProductSort } from '@vitrine-kit/contracts';
+
+export function parseProductSort(value: string | undefined | null): ProductSort | undefined {
+  if (value === 'newest' || value === 'price-asc' || value === 'price-desc' || value === 'relevance') {
+    return value;
+  }
+  return undefined;
+}
+
+/** Parse `?size=S&size=L&color=Black` style params into ProductQuery.filters. */
+export function parseProductFilters(
+  params: Record<string, string | string[] | undefined>,
+  facetKeys: string[] = ['size', 'color'],
+): Record<string, string[]> | undefined {
+  const filters: Record<string, string[]> = {};
+  for (const key of facetKeys) {
+    const raw = params[key];
+    if (raw == null) continue;
+    const values = (Array.isArray(raw) ? raw : [raw])
+      .flatMap((v) => String(v).split(','))
+      .map((v) => v.trim())
+      .filter(Boolean);
+    if (values.length) filters[key] = [...new Set(values)];
+  }
+  return Object.keys(filters).length ? filters : undefined;
+}
+
+export function parsePriceBound(
+  value: string | string[] | undefined | null,
+): number | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw == null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  // URL values are major currency units ($); ProductQuery uses minor units.
+  return Math.round(n * 100);
+}
+
+/** Aggregate option values present on the given products (for toolbar facets). */
+export function collectOptionFacets(products: Product[]): Record<string, string[]> {
+  const buckets = new Map<string, Set<string>>();
+  for (const p of products) {
+    for (const v of p.variants) {
+      if (!v.options) continue;
+      for (const [key, val] of Object.entries(v.options)) {
+        if (!val) continue;
+        let set = buckets.get(key);
+        if (!set) {
+          set = new Set();
+          buckets.set(key, set);
+        }
+        set.add(val);
+      }
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const [key, set] of [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    out[key] = [...set].sort((a, b) => a.localeCompare(b));
+  }
+  return out;
+}
+
+function matchesFilters(product: Product, filters: Record<string, string[]>): boolean {
+  for (const [key, wanted] of Object.entries(filters)) {
+    if (!wanted.length) continue;
+    const has = product.variants.some((v) => {
+      const actual = v.options?.[key];
+      return actual != null && wanted.includes(actual);
+    });
+    if (!has) return false;
+  }
+  return true;
+}
+
+function matchesSearch(product: Product, term: string): boolean {
+  const q = term.trim().toLowerCase();
+  if (!q) return true;
+  const hay = `${product.title} ${product.description ?? ''} ${product.slug}`.toLowerCase();
+  return hay.includes(q);
+}
+
+function priceOf(product: Product): number {
+  return product.priceRange?.min ?? product.variants[0]?.price ?? Number.POSITIVE_INFINITY;
+}
+
+function matchesPrice(product: Product, priceMin?: number, priceMax?: number): boolean {
+  if (priceMin == null && priceMax == null) return true;
+  // A product matches if any variant price falls in range (merchandising expectation).
+  return product.variants.some((v) => {
+    if (priceMin != null && v.price < priceMin) return false;
+    if (priceMax != null && v.price > priceMax) return false;
+    return true;
+  });
+}
+
+/** Apply search / filters / sort that the DB layer cannot express cheaply. */
+export function applyProductQuery(products: Product[], query: ProductQuery = {}): Product[] {
+  let out = products;
+  if (query.search?.trim()) {
+    out = out.filter((p) => matchesSearch(p, query.search!));
+  }
+  if (query.filters && Object.keys(query.filters).length > 0) {
+    out = out.filter((p) => matchesFilters(p, query.filters!));
+  }
+  if (query.priceMin != null || query.priceMax != null) {
+    out = out.filter((p) => matchesPrice(p, query.priceMin, query.priceMax));
+  }
+  const sort = query.sort ?? 'newest';
+  if (sort === 'price-asc') {
+    out = [...out].sort((a, b) => priceOf(a) - priceOf(b));
+  } else if (sort === 'price-desc') {
+    out = [...out].sort((a, b) => priceOf(b) - priceOf(a));
+  } else if (sort === 'relevance' && query.search?.trim()) {
+    const q = query.search.trim().toLowerCase();
+    out = [...out].sort((a, b) => {
+      const aTitle = a.title.toLowerCase().startsWith(q) ? 0 : a.title.toLowerCase().includes(q) ? 1 : 2;
+      const bTitle = b.title.toLowerCase().startsWith(q) ? 0 : b.title.toLowerCase().includes(q) ? 1 : 2;
+      return aTitle - bTitle || a.title.localeCompare(b.title);
+    });
+  }
+  // newest: keep adapter order (typically -createdAt)
+  return out;
+}

package/kit/templates/backend-payload/files/lib/seed/admin.ts

@@ -3,7 +3,7 @@
 // to the console once.
 import { randomBytes } from 'node:crypto';
 import type { Payload } from 'payload';
-import { shouldRunDevTask } from './guards.js';
+import { seedOnBootEnabled, shouldRunDevTask } from './guards.js';
 
 function randomPassword(length = 16): string {
   return randomBytes(length).toString('base64url').slice(0, length);
@@ -12,12 +12,22 @@ function randomPassword(length = 16): string {
 export async function ensureDevAdmin(payload: Payload): Promise<void> {
   const isProd = process.env.NODE_ENV === 'production';
   const { totalDocs } = await payload.count({ collection: 'users' });
-  if (!shouldRunDevTask({ isProd, existingCount: totalDocs })) return;
+  if (!shouldRunDevTask({ isProd, existingCount: totalDocs, seedOnBoot: seedOnBootEnabled() })) {
+    return;
+  }
 
-  const email = process.env.DEV_ADMIN_EMAIL ?? 'admin@dev.local';
-  const password = process.env.DEV_ADMIN_PASSWORD ?? randomPassword();
-  await payload.create({ collection: 'users', data: { email, password } });
+  // `.env.example` ships `DEV_ADMIN_EMAIL=` / `DEV_ADMIN_PASSWORD=` — empty strings must
+  // not win over defaults (`??` only treats null/undefined).
+  const email = process.env.DEV_ADMIN_EMAIL?.trim() || 'admin@example.com';
+  const password = process.env.DEV_ADMIN_PASSWORD?.trim() || randomPassword();
+  await payload.create({
+    collection: 'users',
+    data: { email, password },
+    overrideAccess: true,
+  });
   payload.logger.warn(
-    `[vitrine] DEV ADMIN ${email} / ${password} — development only, change before deploying`,
+    isProd
+      ? `[vitrine] BOOTSTRAP ADMIN ${email} / ${password} — change immediately (SEED_ON_BOOT)`
+      : `[vitrine] DEV ADMIN ${email} / ${password} — development only, change before deploying`,
   );
 }