@vitrine-kit/vitrine 0.4.3 → 0.5.0

package/kit/registry/search/files/lib/search/data.ts

@@ -0,0 +1,8 @@
+// Search via CatalogSource.search — portable across Payload and Vendure adapters.
+import type { CatalogSource, Product } from '@vitrine-kit/contracts';
+
+export async function loadSearch(source: CatalogSource, term: string): Promise<Product[]> {
+  const q = term.trim();
+  if (!q) return [];
+  return source.search(q);
+}

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

@@ -0,0 +1,8 @@
+// Registers the search feature's slots. SearchForm sits in the header actions
+// (before CartIndicator when cart is installed).
+import { registerSlot } from '@vitrine-kit/core';
+import { SearchForm } from '../../components/search/SearchForm.js';
+
+export function registerSearchSlots(): void {
+  registerSlot({ slot: 'global.header-actions', component: SearchForm, order: 5 });
+}

package/kit/registry/seo/docs/seo.md

@@ -1,14 +1,17 @@
 # Feature: seo
 
-Page metadata and schema.org JSON-LD from domain types.
+Page metadata and schema.org JSON-LD from domain types, plus sitewide crawl files.
 
 ## Modules
 - `lib/seo/metadata` — `buildProductMetadata(product)` → `SiteMetadata` (structurally compatible with Next `Metadata`; in the client it's returned from `generateMetadata`).
 - `lib/seo/jsonld` — `productJsonLd(product)` → a schema.org `Product`/`Offer` object.
 - `components/seo/JsonLd` — `<JsonLd data={…} />` embeds a `<script type="application/ld+json">`.
+- `app/sitemap.ts` — dynamic sitemap from `CatalogSource` (home, categories, products).
+- `app/robots.ts` — robots.txt pointing at the sitemap; disallows admin/api/cart/order.
 
 ## Contracts
 Only `@vitrine-kit/contracts` (the `Product` type). Registers no slots.
 
 ## Note
 The price in JSON-LD is converted from minor units (`price/100`).
+Home and category pages set `generateMetadata` in the base template.

package/kit/registry/seo/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "seo",
   "title": "SEO — metadata and JSON-LD",
-  "kitVersion": "0.4.3",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",
@@ -20,6 +20,10 @@
     {
       "from": "files/lib/seo/",
       "to": "lib/seo/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
     }
   ],
   "config": {

package/kit/registry/seo/files/app/robots.ts

@@ -0,0 +1,13 @@
+import type { MetadataRoute } from 'next';
+import { baseUrl } from '@/lib/site';
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: ['/admin/', '/api/', '/cart', '/order/', '/account', '/wishlist'],
+    },
+    sitemap: `${baseUrl}/sitemap.xml`,
+  };
+}

package/kit/registry/seo/files/app/sitemap.ts

@@ -0,0 +1,27 @@
+import type { MetadataRoute } from 'next';
+import { getCatalogSource } from '@/lib/adapter';
+import { baseUrl } from '@/lib/site';
+
+/** Dynamic sitemap from the catalog (products + categories + home). */
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const source = await getCatalogSource();
+  const [products, categories] = await Promise.all([
+    source.listProducts({ perPage: 500 }),
+    source.listCategories(),
+  ]);
+
+  const entries: MetadataRoute.Sitemap = [
+    { url: baseUrl, changeFrequency: 'daily', priority: 1 },
+    ...categories.map((c) => ({
+      url: `${baseUrl}/categories/${c.slug}`,
+      changeFrequency: 'weekly' as const,
+      priority: 0.7,
+    })),
+    ...products.map((p) => ({
+      url: `${baseUrl}/products/${p.slug}`,
+      changeFrequency: 'weekly' as const,
+      priority: 0.8,
+    })),
+  ];
+  return entries;
+}

package/kit/registry/stubs/route-glue.d.ts

@@ -4,7 +4,24 @@
 declare module 'next/server' {
   export class NextResponse {
     static json(body: unknown, init?: ResponseInit): NextResponse;
+    static next(): NextResponse;
+    static redirect(url: URL | string): NextResponse;
+    static rewrite(url: URL | string): NextResponse;
+    cookies: {
+      set(name: string, value: string, options?: Record<string, unknown>): void;
+    };
   }
+  export interface NextRequest {
+    nextUrl: URL & { clone(): URL & { pathname: string } };
+    cookies: { get(name: string): { value: string } | undefined };
+  }
+}
+
+declare module 'next/navigation' {
+  export function useRouter(): {
+    push(href: string): void;
+    refresh(): void;
+  };
 }
 
 declare module 'next/headers' {
@@ -43,3 +60,57 @@ declare module '@/lib/checkout-yookassa/provider' {
   import type { PaymentProvider } from '@vitrine-kit/core';
   export const yookassaProvider: PaymentProvider;
 }
+
+declare module 'payload' {
+  export function getPayload(args: { config: unknown }): Promise<{
+    findByID(args: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    find(args: Record<string, unknown>): Promise<{ docs: Array<Record<string, unknown>> }>;
+    update(args: Record<string, unknown>): Promise<unknown>;
+    create(args: Record<string, unknown>): Promise<unknown>;
+  }>;
+}
+
+declare module '@payload-config' {
+  const config: unknown;
+  export default config;
+}
+
+declare module '@/site.config' {
+  import type { SiteConfig } from '@vitrine-kit/contracts';
+  export const siteConfig: SiteConfig;
+  export default siteConfig;
+}
+
+declare module '@/lib/i18n/dictionary' {
+  export type MessageKey =
+    | 'cart'
+    | 'search'
+    | 'checkout'
+    | 'wishlist'
+    | 'orders'
+    | 'account'
+    | 'continueShopping'
+    | 'addToCart'
+    | 'thankYou'
+    | 'signIn'
+    | 'createAccount';
+  export function t(key: MessageKey, locale?: string): string;
+  export function supportedLocales(): string[];
+}
+
+declare module '@/lib/i18n/useChromeLabel' {
+  import type { MessageKey } from '@/lib/i18n/dictionary';
+  export function useChromeLabel(key: MessageKey, fallbackLocale?: string): string;
+  export function chromeLabel(key: MessageKey, locale?: string): string;
+}
+
+declare module '@/lib/reviews/types' {
+  export interface ProductReview {
+    id: string;
+    author: string;
+    rating: number;
+    body: string;
+    createdAt: string;
+  }
+  export function parseReviews(value: unknown): ProductReview[];
+}

package/kit/registry/tsconfig.json

@@ -10,12 +10,17 @@
     "*/files/components/**/*.ts",
     "*/files/components/**/*.tsx",
     "*/files/lib/**/*.ts",
-    "*/files/lib/**/*.tsx"
+    "*/files/lib/**/*.tsx",
+    "stubs/**/*.d.ts"
   ],
   "exclude": [
     "**/node_modules",
     "**/dist",
     "*/files/lib/checkout-*/**",
-    "*/files/lib/checkout/fulfill.ts"
+    "*/files/lib/checkout/fulfill.ts",
+    "*/files/lib/checkout/notify.ts",
+    "*/files/lib/email/**",
+    "*/files/lib/accounts/session.ts",
+    "*/files/middleware.ts"
   ]
 }

package/kit/registry/wishlist/docs/wishlist.md

@@ -0,0 +1,11 @@
+# Feature: wishlist
+
+Client-side wishlist (localStorage). No backend — works on every tier including catalog-only.
+
+## Modules
+- `WishlistButton` — toggle on the product page (`product.below-price`)
+- `WishlistIndicator` — header link with count (`global.header-actions`)
+- `/wishlist` — list of saved product slugs resolved via `CatalogSource`
+
+## Note
+Guest-only. Clearing site data clears the wishlist. Accounts can later sync this storage.

package/kit/registry/wishlist/feature.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "wishlist",
+  "title": "Wishlist",
+  "kitVersion": "0.5.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "catalog",
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "catalog",
+    "product-page"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/components/wishlist/",
+      "to": "components/wishlist/"
+    },
+    {
+      "from": "files/lib/wishlist/",
+      "to": "lib/wishlist/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.wishlist": true
+    }
+  },
+  "slots": [
+    {
+      "slot": "product.below-price",
+      "component": "WishlistButton",
+      "order": 20
+    },
+    {
+      "slot": "global.header-actions",
+      "component": "WishlistIndicator",
+      "order": 15
+    }
+  ],
+  "env": [],
+  "claudeDoc": "docs/wishlist.md",
+  "conflicts": [],
+  "removable": true
+}

package/kit/registry/wishlist/files/app/(frontend)/wishlist/page.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next';
+import { WishlistView } from '@/components/wishlist/WishlistView';
+
+export const metadata: Metadata = {
+  title: 'Wishlist',
+  robots: { index: false, follow: true },
+};
+
+export default function WishlistPage() {
+  return (
+    <div className="flex flex-col gap-section">
+      <h1 className="font-heading text-fg">Wishlist</h1>
+      <WishlistView />
+    </div>
+  );
+}

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 });