@vitrine-kit/vitrine 0.4.3 → 0.5.0

package/kit/registry/checkout/files/lib/checkout/notify.ts

@@ -0,0 +1,52 @@
+// Order confirmation email. Uses Payload sendEmail when the email feature + SMTP
+// are configured; otherwise logs to the console (zero-config).
+import type { Order } from '@vitrine-kit/contracts';
+import { siteConfig } from '@/site.config';
+import { siteName } from '@/lib/site';
+
+export async function notifyOrderConfirmation(order: Order): Promise<void> {
+  const to = order.email?.trim();
+  if (!to) return;
+
+  const provider = siteConfig.integrations.email;
+  const subject = `Order confirmation — ${siteName}`;
+  const body = [
+    `Thanks for your order at ${siteName}.`,
+    ``,
+    `Order total: ${(order.total / 100).toFixed(2)} ${order.currency}`,
+    `Status: ${order.status}`,
+    `Lines: ${order.lines.map((l) => `${l.quantity}× ${l.title}`).join(', ')}`,
+  ].join('\n');
+
+  let from: string | undefined;
+  try {
+    const emailMod = await import('../email/adapter.js');
+    from = emailMod.emailFromAddress();
+  } catch {
+    // email feature not installed
+  }
+
+  if (provider || from) {
+    try {
+      const { getPayload } = await import('payload');
+      const config = (await import('@payload-config')).default;
+      const payload = await getPayload({ config });
+      await payload.sendEmail({
+        to,
+        from: from ?? undefined,
+        subject,
+        text: body,
+      });
+      return;
+    } catch (error) {
+      console.warn(
+        '[vitrine] payload.sendEmail failed — falling back to console log',
+        error instanceof Error ? error.message : error,
+      );
+    }
+  }
+
+  console.info(
+    `[vitrine] order email${provider ? ` via "${provider}"` : ''}${from ? ` from ${from}` : ''} → ${to}\n${subject}\n${body}`,
+  );
+}

package/kit/registry/checkout-paddle/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-paddle",
   "title": "Payment — Paddle",
-  "kitVersion": "0.4.3",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout-stripe/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-stripe",
   "title": "Payment — Stripe",
-  "kitVersion": "0.4.3",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout-yookassa/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-yookassa",
   "title": "Payment — YooKassa",
-  "kitVersion": "0.4.3",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/email/docs/email.md

@@ -0,0 +1,19 @@
+# Feature: email
+
+Wires Payload's email transport for order confirmations and auth mail.
+
+## Modules
+- `lib/email/adapter.ts` — `resolveEmailAdapter()` builds `@payloadcms/email-nodemailer`
+  from `SMTP_*` / `EMAIL_FROM`, or a **console adapter** when `EMAIL_FROM` is set without
+  `SMTP_HOST` (reset links and order mail print to the terminal / `docker compose logs`)
+- `payload.config` (template) awaits the adapter when the file is present
+- Checkout `notifyOrderConfirmation` calls `payload.sendEmail` when an adapter is configured
+
+## Setup
+1. `vitrine add email` (installs `@payloadcms/email-nodemailer` + `nodemailer`)
+2. Set `EMAIL_FROM` (required for any adapter). Optionally `SMTP_HOST` / `SMTP_PORT` /
+   `SMTP_USER` / `SMTP_PASS` / `EMAIL_FROM_NAME` for real delivery
+3. `integrations.email` is set to `"smtp"` by the feature config
+
+Without `SMTP_HOST`, zero-config still works — messages (including password-reset links)
+are logged to the console via the console adapter.

package/kit/registry/email/feature.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "email",
+  "title": "Transactional email",
+  "kitVersion": "0.5.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {},
+  "npm": [
+    "@payloadcms/email-nodemailer@^3.0.0",
+    "nodemailer@^6.9.0"
+  ],
+  "files": [
+    {
+      "from": "files/lib/email/",
+      "to": "lib/email/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.email": true
+    }
+  },
+  "slots": [],
+  "env": [
+    {
+      "key": "EMAIL_FROM",
+      "required": false
+    },
+    {
+      "key": "EMAIL_FROM_NAME",
+      "required": false
+    },
+    {
+      "key": "SMTP_HOST",
+      "required": false
+    },
+    {
+      "key": "SMTP_PORT",
+      "required": false
+    },
+    {
+      "key": "SMTP_USER",
+      "required": false
+    },
+    {
+      "key": "SMTP_PASS",
+      "required": false
+    }
+  ],
+  "claudeDoc": "docs/email.md",
+  "conflicts": [],
+  "removable": true
+}

package/kit/registry/email/files/lib/email/adapter.ts

@@ -0,0 +1,89 @@
+// Avoid importing `payload` types here — registry typecheck has no Payload deps.
+export type VitrineEmailAdapter = {
+  name: string;
+  defaultFromAddress: string;
+  defaultFromName: string;
+  sendEmail: (message: unknown) => Promise<unknown>;
+};
+
+type EmailMessage = {
+  to?: string | string[];
+  subject?: string;
+  html?: string;
+  text?: string;
+};
+
+export function emailFromAddress(): string | undefined {
+  return process.env.EMAIL_FROM?.trim() || undefined;
+}
+
+export function emailFromName(): string {
+  return process.env.EMAIL_FROM_NAME?.trim() || 'Store';
+}
+
+/** Dev/zero-config adapter: logs the full message (incl. reset links) to the console. */
+function consoleEmailAdapter(from: string): VitrineEmailAdapter {
+  return {
+    name: 'vitrine-console',
+    defaultFromAddress: from,
+    defaultFromName: emailFromName(),
+    async sendEmail(message: unknown) {
+      const msg = (message ?? {}) as EmailMessage;
+      const to = Array.isArray(msg.to) ? msg.to.join(', ') : (msg.to ?? '(unknown)');
+      const body = msg.text || msg.html || '';
+      console.info(
+        [
+          '[vitrine] console email (no SMTP_HOST)',
+          `  from: ${from}`,
+          `  to: ${to}`,
+          `  subject: ${msg.subject ?? '(none)'}`,
+          '  ---',
+          body,
+          '  ---',
+        ].join('\n'),
+      );
+      return { messageId: `console-${Date.now()}` };
+    },
+  };
+}
+
+/**
+ * Resolve Payload's `email` config entry. Dynamic-imports `@payloadcms/email-nodemailer`
+ * when SMTP is configured; otherwise returns a console adapter so auth reset links
+ * and order mail still surface in docker logs / the terminal.
+ */
+export async function resolveEmailAdapter(): Promise<VitrineEmailAdapter | undefined> {
+  const from = emailFromAddress();
+  const host = process.env.SMTP_HOST?.trim();
+  if (!from) return undefined;
+
+  if (!host) {
+    console.info(`[vitrine] EMAIL_FROM=${from} (no SMTP_HOST — console email adapter)`);
+    return consoleEmailAdapter(from);
+  }
+
+  try {
+    const { nodemailerAdapter } = await import('@payloadcms/email-nodemailer');
+    const port = Number(process.env.SMTP_PORT || 587);
+    const user = process.env.SMTP_USER?.trim();
+    const pass = process.env.SMTP_PASS ?? '';
+    console.info(`[vitrine] SMTP email adapter → ${host}:${port} from ${from}`);
+    return nodemailerAdapter({
+      defaultFromAddress: from,
+      defaultFromName: emailFromName(),
+      skipVerify: process.env.NODE_ENV !== 'production',
+      transportOptions: {
+        host,
+        port,
+        secure: port === 465,
+        auth: user ? { user, pass } : undefined,
+      },
+    }) as unknown as VitrineEmailAdapter;
+  } catch (error) {
+    console.warn(
+      '[vitrine] @payloadcms/email-nodemailer not installed — falling back to console email adapter',
+      error instanceof Error ? error.message : error,
+    );
+    return consoleEmailAdapter(from);
+  }
+}

package/kit/registry/filters/docs/filters.md

@@ -0,0 +1,13 @@
+# Feature: filters
+
+Catalog toolbar for sort, option facets, and price range via the `catalog.toolbar` slot.
+
+## Modules
+- `components/filters/CatalogToolbar` — GET form updating `?sort=`, `?size=`, `?color=`,
+  `?priceMin=` / `?priceMax=` (major currency units) on the current listing URL
+- Mounted into `catalog.toolbar` on home and category pages
+
+## Contracts
+- `ProductQuery.sort` (`newest` | `price-asc` | `price-desc` | `relevance`)
+- `ProductQuery.filters` — option facets, e.g. `{ size: ['S'], color: ['Black'] }`
+- `ProductQuery.priceMin` / `priceMax` — inclusive bounds in minor units (cents)

package/kit/registry/filters/feature.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "filters",
+  "title": "Catalog sort, facets, and price filters",
+  "kitVersion": "0.5.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "catalog",
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "catalog"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/components/filters/",
+      "to": "components/filters/"
+    },
+    {
+      "from": "files/lib/filters/",
+      "to": "lib/filters/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.filters": true
+    }
+  },
+  "slots": [
+    {
+      "slot": "catalog.toolbar",
+      "component": "CatalogToolbar",
+      "order": 10
+    }
+  ],
+  "env": [],
+  "claudeDoc": "docs/filters.md",
+  "conflicts": [],
+  "removable": true
+}

package/kit/registry/filters/files/components/filters/CatalogToolbar.tsx

@@ -0,0 +1,123 @@
+// Catalog listing toolbar — sort + option facets + price range. Uses GET so
+// listings stay shareable.
+'use client';
+
+export interface CatalogToolbarProps {
+  /** Current sort value from the page query string. */
+  sort?: string;
+  /** Form action (pathname). Defaults to "/". */
+  action?: string;
+  /** Available option facets from the current catalog slice. */
+  facets?: Record<string, string[]>;
+  /** Currently selected option filters. */
+  filters?: Record<string, string[]>;
+  /** Minor-unit price bounds (string so uncontrolled inputs stay simple). */
+  priceMin?: string;
+  priceMax?: string;
+}
+
+const SORT_OPTIONS: { value: string; label: string }[] = [
+  { value: 'newest', label: 'Newest' },
+  { value: 'price-asc', label: 'Price: low to high' },
+  { value: 'price-desc', label: 'Price: high to low' },
+];
+
+export function CatalogToolbar({
+  sort = 'newest',
+  action = '/',
+  facets = {},
+  filters = {},
+  priceMin = '',
+  priceMax = '',
+}: CatalogToolbarProps) {
+  const facetEntries = Object.entries(facets).filter(([, values]) => values.length > 0);
+
+  return (
+    <form
+      action={action}
+      method="get"
+      className="vt-catalog-toolbar flex flex-col gap-gutter"
+    >
+      <div className="flex flex-wrap items-end gap-gutter">
+        <label className="flex items-center gap-unit text-sm text-fg">
+          <span className="text-muted-fg">Sort</span>
+          <select
+            name="sort"
+            defaultValue={sort}
+            className="rounded-md border border-input bg-surface px-gutter py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+            onChange={(e) => e.currentTarget.form?.requestSubmit()}
+          >
+            {SORT_OPTIONS.map((opt) => (
+              <option key={opt.value} value={opt.value}>
+                {opt.label}
+              </option>
+            ))}
+          </select>
+        </label>
+
+        <label className="flex items-center gap-unit text-sm text-fg">
+          <span className="text-muted-fg">Min $</span>
+          <input
+            type="number"
+            name="priceMin"
+            min={0}
+            step={0.01}
+            defaultValue={priceMin}
+            placeholder="0"
+            className="w-24 rounded-md border border-input bg-surface px-gutter py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+          />
+        </label>
+        <label className="flex items-center gap-unit text-sm text-fg">
+          <span className="text-muted-fg">Max $</span>
+          <input
+            type="number"
+            name="priceMax"
+            min={0}
+            step={0.01}
+            defaultValue={priceMax}
+            placeholder="—"
+            className="w-24 rounded-md border border-input bg-surface px-gutter py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+          />
+        </label>
+
+        <button
+          type="submit"
+          className="rounded-md border border-border px-gutter py-unit text-sm text-fg hover:bg-muted focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          Apply
+        </button>
+      </div>
+
+      {facetEntries.length > 0 ? (
+        <div className="flex flex-wrap gap-section">
+          {facetEntries.map(([key, values]) => (
+            <fieldset key={key} className="flex flex-col gap-unit">
+              <legend className="text-sm capitalize text-muted-fg">{key}</legend>
+              <div className="flex flex-wrap gap-gutter">
+                {values.map((value) => {
+                  const checked = Boolean(filters[key]?.includes(value));
+                  return (
+                    <label
+                      key={value}
+                      className="flex items-center gap-unit text-sm text-fg"
+                    >
+                      <input
+                        type="checkbox"
+                        name={key}
+                        value={value}
+                        defaultChecked={checked}
+                        className="rounded border-input"
+                        onChange={(e) => e.currentTarget.form?.requestSubmit()}
+                      />
+                      {value}
+                    </label>
+                  );
+                })}
+              </div>
+            </fieldset>
+          ))}
+        </div>
+      ) : null}
+    </form>
+  );
+}

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

@@ -0,0 +1,6 @@
+import { registerSlot } from '@vitrine-kit/core';
+import { CatalogToolbar } from '../../components/filters/CatalogToolbar.js';
+
+export function registerFiltersSlots(): void {
+  registerSlot({ slot: 'catalog.toolbar', component: CatalogToolbar, order: 10 });
+}

package/kit/registry/i18n/docs/i18n.md

@@ -0,0 +1,24 @@
+# Feature: i18n
+
+Locale switcher plus optional path-prefix routing when more than one locale is configured.
+When `i18n.locales` lists more than one code, path middleware and the locale switcher
+activate, and the demo seed applies RU product/category copy. Payload always enables
+`localization` from `site.config.i18n` (even for a single locale) so localized fields stay valid.
+
+## Modules
+- `LocaleSwitcher` — header control writing `vitrine_locale` and navigating to `/{locale}/…`
+- `middleware.ts` — when `i18n.locales.length > 1`, redirects bare paths to `/{locale}/…`
+  and rewrites to the unprefixed App Router tree (no route file move required)
+- `lib/i18n/dictionary.ts` — en/ru dictionaries for shared chrome strings
+- `lib/i18n/useChromeLabel.ts` — client hook used by cart/search/wishlist/account chrome
+- `lib/i18n/t.ts` — re-exports `t` / `MessageKey`
+- `lib/i18n/locale.ts` — `getRequestLocale()` from the cookie (used by catalog pages)
+
+The base template ships an English-only dictionary stub so chrome can always import
+`@/lib/i18n/*`; installing this feature overwrites it with multi-locale copy.
+
+## Setup
+Set `site.config` `i18n.locales` to more than one locale (e.g. `['en','ru']`). The switcher
+hides itself when only one locale is configured; middleware is a no-op in that case.
+Payload `localization` mirrors that list; mark product/category title and description as
+localized in the blueprint. Demo seed applies RU copy when `ru` is enabled.

package/kit/registry/i18n/feature.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "i18n",
+  "title": "Locale switcher and path prefixes",
+  "kitVersion": "0.5.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "catalog",
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/components/i18n/",
+      "to": "components/i18n/"
+    },
+    {
+      "from": "files/lib/i18n/",
+      "to": "lib/i18n/"
+    },
+    {
+      "from": "files/middleware.ts",
+      "to": "middleware.ts"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.i18n": true
+    }
+  },
+  "slots": [
+    {
+      "slot": "global.header-actions",
+      "component": "LocaleSwitcher",
+      "order": 30
+    }
+  ],
+  "env": [],
+  "claudeDoc": "docs/i18n.md",
+  "conflicts": [],
+  "removable": true
+}

package/kit/registry/i18n/files/components/i18n/LocaleSwitcher.tsx

@@ -0,0 +1,64 @@
+'use client';
+import { useEffect, useState } from 'react';
+
+const COOKIE = 'vitrine_locale';
+
+function readCookie(): string | null {
+  if (typeof document === 'undefined') return null;
+  const match = document.cookie.match(new RegExp(`(?:^|; )${COOKIE}=([^;]*)`));
+  return match ? decodeURIComponent(match[1]!) : null;
+}
+
+function writeCookie(locale: string): void {
+  // biome-ignore lint/suspicious/noDocumentCookie: locale preference cookie; Cookie Store API is not universal enough yet.
+  document.cookie = `${COOKIE}=${encodeURIComponent(locale)};path=/;max-age=31536000;samesite=lax`;
+}
+
+/** Strip a leading `/{locale}` segment when present. */
+function stripLocale(pathname: string, locales: string[]): string {
+  const seg = pathname.split('/')[1] ?? '';
+  if (locales.includes(seg)) {
+    return pathname.slice(seg.length + 1) || '/';
+  }
+  return pathname || '/';
+}
+
+/** Locales come from site.config via optional prop; falls back to en/ru demo pair. */
+export interface LocaleSwitcherProps {
+  locales?: string[];
+  defaultLocale?: string;
+}
+
+export function LocaleSwitcher({ locales, defaultLocale = 'en' }: LocaleSwitcherProps) {
+  const options = locales && locales.length > 0 ? locales : ['en', 'ru'];
+  const [locale, setLocale] = useState(defaultLocale);
+
+  useEffect(() => {
+    setLocale(readCookie() ?? defaultLocale);
+  }, [defaultLocale]);
+
+  if (options.length < 2) return null;
+
+  return (
+    <label className="vt-locale-switcher flex items-center gap-unit text-sm text-fg">
+      <span className="sr-only">Language</span>
+      <select
+        value={locale}
+        className="rounded-md border border-input bg-surface px-unit py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        onChange={(e) => {
+          const next = e.target.value;
+          writeCookie(next);
+          setLocale(next);
+          const rest = stripLocale(location.pathname, options);
+          location.assign(rest === '/' ? `/${next}` : `/${next}${rest}`);
+        }}
+      >
+        {options.map((code) => (
+          <option key={code} value={code}>
+            {code.toUpperCase()}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}

package/kit/registry/i18n/files/lib/i18n/dictionary.ts

@@ -0,0 +1,52 @@
+// Multi-locale chrome dictionary. Overwrites the base English stub when `i18n` is installed.
+export type MessageKey =
+  | 'cart'
+  | 'search'
+  | 'checkout'
+  | 'wishlist'
+  | 'orders'
+  | 'account'
+  | 'continueShopping'
+  | 'addToCart'
+  | 'thankYou'
+  | 'signIn'
+  | 'createAccount';
+
+const en: Record<MessageKey, string> = {
+  cart: 'Cart',
+  search: 'Search',
+  checkout: 'Checkout',
+  wishlist: 'Wishlist',
+  orders: 'Orders',
+  account: 'Account',
+  continueShopping: 'Continue shopping',
+  addToCart: 'Add to cart',
+  thankYou: 'Thank you for your order',
+  signIn: 'Sign in',
+  createAccount: 'Create account',
+};
+
+const ru: Record<MessageKey, string> = {
+  cart: 'Корзина',
+  search: 'Поиск',
+  checkout: 'Оформить',
+  wishlist: 'Избранное',
+  orders: 'Заказы',
+  account: 'Аккаунт',
+  continueShopping: 'Продолжить покупки',
+  addToCart: 'В корзину',
+  thankYou: 'Спасибо за заказ',
+  signIn: 'Войти',
+  createAccount: 'Создать аккаунт',
+};
+
+const dictionaries: Record<string, Record<MessageKey, string>> = { en, ru };
+
+export function t(key: MessageKey, locale = 'en'): string {
+  const dict = dictionaries[locale] ?? en;
+  return dict[key] ?? en[key] ?? key;
+}
+
+export function supportedLocales(): string[] {
+  return Object.keys(dictionaries);
+}

package/kit/registry/i18n/files/lib/i18n/locale.ts

@@ -0,0 +1,11 @@
+// Request locale from the vitrine_locale cookie (set by i18n middleware / switcher).
+import { cookies } from 'next/headers';
+import { siteConfig } from '@/site.config';
+
+export async function getRequestLocale(): Promise<string> {
+  const jar = await cookies();
+  const fromCookie = jar.get('vitrine_locale')?.value;
+  const locales = siteConfig.i18n.locales;
+  if (fromCookie && locales.includes(fromCookie)) return fromCookie;
+  return siteConfig.i18n.defaultLocale;
+}

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

@@ -0,0 +1,6 @@
+import { registerSlot } from '@vitrine-kit/core';
+import { LocaleSwitcher } from '../../components/i18n/LocaleSwitcher.js';
+
+export function registerI18nSlots(): void {
+  registerSlot({ slot: 'global.header-actions', component: LocaleSwitcher, order: 30 });
+}

package/kit/registry/i18n/files/lib/i18n/t.ts

@@ -0,0 +1 @@
+export { t, type MessageKey, supportedLocales } from './dictionary.js';