simplycms 0.4.0

package/src/i18n/catalogs/uk/properties.ts

@@ -0,0 +1,18 @@
+/** Публічні сторінки властивостей: список, значення властивості, добірка товарів. */
+export const messages = {
+  'properties.title': 'Властивості',
+  'properties.pageTitle': 'Властивості товарів',
+  'properties.subtitle': 'Перегляньте товари за характеристиками',
+  'properties.optionCount': '{count} значень',
+  'properties.empty': 'Властивостей із сторінками поки немає',
+
+  'properties.notFound': 'Властивість не знайдено',
+  'properties.backToProperties': 'Повернутись до властивостей',
+  'properties.chooseValue': 'Оберіть значення для перегляду товарів',
+  'properties.optionsEmpty': 'Значень для цієї властивості поки немає',
+
+  'properties.pageNotFound': 'Сторінку не знайдено',
+  'properties.products': 'Товари',
+  'properties.productsFiltered': 'Товари ({property}: {option})',
+  'properties.productsEmpty': 'Товарів з цією характеристикою поки немає',
+} as const;

package/src/i18n/catalogs/uk/reviews.ts

@@ -0,0 +1,34 @@
+/** Відгуки на товар: рейтинг, форма, картка відгуку, лайтбокс фото. */
+export const messages = {
+  // Лічильник відгуків (форми множини — див. `pluralReviewsKey` у reviews-ui)
+  'reviews.countOne': 'відгук',
+  'reviews.countFew': 'відгуки',
+  'reviews.countMany': 'відгуків',
+
+  'reviews.alreadySubmitted': 'Ви вже залишили відгук на цей товар.',
+  'reviews.writeReview': 'Написати відгук',
+  'reviews.loginPrompt': 'Щоб залишити відгук, увійдіть в свій акаунт',
+  'reviews.loginOrRegister': 'Увійти або зареєструватись',
+  'reviews.empty': 'Ще немає відгуків. Будьте першим!',
+
+  // Картка відгуку
+  'reviews.anonymousAuthor': 'Користувач',
+  'reviews.pendingBadge': 'На модерації',
+  'reviews.delete.confirmTitle': 'Видалити відгук?',
+  'reviews.delete.confirmText': 'Цю дію неможливо скасувати.',
+  'reviews.photoAlt': 'Фото {index}',
+  'reviews.enlargedPhotoAlt': 'Збільшене фото',
+
+  // Форма відгуку
+  'reviews.form.ratingLabel': 'Оцінка *',
+  'reviews.form.ratingRequired': 'Оберіть оцінку',
+  'reviews.form.titleLabel': "Заголовок (необов'язково)",
+  'reviews.form.titlePlaceholder': 'Коротко про враження',
+  'reviews.form.contentLabel': 'Текст відгуку',
+  'reviews.form.contentPlaceholder': 'Напишіть ваш відгук...',
+  'reviews.form.photosLabel': 'Фото (до 5)',
+  'reviews.form.submit': 'Надіслати відгук',
+
+  // Редактор тексту відгуку (тулбар посилання)
+  'reviews.editor.linkUrl': 'URL посилання',
+} as const;

package/src/i18n/catalogs/uk/validation.ts

@@ -0,0 +1,38 @@
+/**
+ * Повідомлення валідації форм (Zod).
+ *
+ * Окремий неймспейс, а не `common`, бо ці рядки має бачити один споживач —
+ * фабрика схеми (`buildSchema(t)`), і плутати їх із підписами полів не варто:
+ * «Назва» і «Назва обовʼязкова» — різні ролі в тому самому екрані.
+ */
+export const messages = {
+  'validation.nameRequired': "Назва обов'язкова",
+  'validation.codeRequired': "Код обов'язковий",
+  'validation.cityRequired': "Місто обов'язкове",
+  'validation.addressRequired': "Адреса обов'язкова",
+
+  'validation.min2': 'Мінімум 2 символи',
+  'validation.min6': 'Мінімум 6 символів',
+  'validation.max20': 'Максимум 20 символів',
+  'validation.max100': 'Максимум 100 символів',
+  'validation.positive': 'Значення має бути додатнім',
+
+  'validation.email': 'Введіть коректний email',
+  'validation.emailFormat': 'Невірний формат email',
+  'validation.phone': 'Введіть коректний номер телефону',
+  // Дозволений набір символів для машинних ідентифікаторів (slug, code).
+  'validation.slug': 'Тільки латинські літери, цифри та _',
+
+  'validation.firstNameMin2': "Ім'я має містити мінімум 2 символи",
+  'validation.lastNameMin2': 'Прізвище має містити мінімум 2 символи',
+  'validation.passwordMin6': 'Пароль має містити мінімум 6 символів',
+  'validation.passwordMismatch': 'Паролі не співпадають',
+
+  'validation.shippingRequired': 'Оберіть спосіб доставки',
+  'validation.paymentRequired': 'Оберіть спосіб оплати',
+  'validation.contactRequired': "Вкажіть email або телефон для зв'язку",
+  'validation.recipientRequired': "Заповніть всі обов'язкові поля отримувача",
+  'validation.groupRequired': 'Оберіть групу',
+  'validation.priceTypeRequired': 'Оберіть вид ціни',
+  'validation.targetCategoryRequired': 'Оберіть категорію призначення',
+} as const;

package/src/i18n/index.ts

@@ -0,0 +1,14 @@
+// Кореневий барель пакета i18n.
+//
+// Контракт: транслятор створюється per-request/per-render від локалі з конфіга.
+// Глобального mutable-стану (`setLocale`) немає навмисно — SSR-safety.
+
+export { createTranslator, normalizeLocale, interpolate } from './translator';
+export { I18nProvider, useT, useLocale } from './I18nProvider';
+export type {
+  Locale,
+  MessageKey,
+  MessageParams,
+  Catalog,
+  Translator,
+} from './types';

package/src/i18n/translator.ts

@@ -0,0 +1,53 @@
+import { messages as uk } from './catalogs/uk/index';
+import { messages as en } from './catalogs/en/index';
+import type {
+  Catalog,
+  Locale,
+  MessageKey,
+  MessageParams,
+  Translator,
+} from './types';
+
+/** Реєстр каталогів за локаллю. uk — повний, решта часткові. */
+const catalogs: Record<Locale, Catalog> = { uk, en };
+
+const SUPPORTED: readonly Locale[] = ['uk', 'en'];
+const DEFAULT_LOCALE: Locale = 'uk';
+
+/** `uk-UA` → `uk`, `EN` → `en`, невідома/порожня → `uk`. */
+export function normalizeLocale(input: string): Locale {
+  const base = input.split('-')[0]?.toLowerCase() ?? '';
+  return SUPPORTED.find((locale) => locale === base) ?? DEFAULT_LOCALE;
+}
+
+/**
+ * Підстановка `{name}` значеннями з `params`; невідомий плейсхолдер лишається як є.
+ *
+ * 🔴 Експортована навмисно: `useThemeT` (`simplycms/themes`) підставляє
+ * параметри в каталог ТЕМИ за тією самою семантикою, і дублювати цю функцію
+ * там означало б два джерела правди для одного форматування.
+ */
+export function interpolate(template: string, params?: MessageParams): string {
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (match, name: string) => {
+    const value = params[name];
+    return value === undefined ? match : String(value);
+  });
+}
+
+/**
+ * Створює транслятор під конкретну локаль.
+ *
+ * Транслятор — замикання без модульного mutable-стану: жодного `setLocale`.
+ * Тому SSR може тримати кілька трансляторів різних локалей одночасно
+ * (per-request), і вони не впливають один на одного.
+ */
+export function createTranslator(locale: Locale): Translator {
+  const catalog = catalogs[locale] ?? catalogs[DEFAULT_LOCALE];
+
+  return (key: MessageKey, params?: MessageParams): string => {
+    // Ланцюг: локаль → uk → сам ключ (видимий сигнал про пропущений переклад).
+    const template = catalog[key] ?? uk[key] ?? key;
+    return interpolate(template, params);
+  };
+}

package/src/i18n/types.ts

@@ -0,0 +1,19 @@
+import type { messages as ukMessages } from './catalogs/uk/index';
+
+/** Підтримувані локалі ядра. */
+export type Locale = 'uk' | 'en';
+
+/**
+ * Ключі повідомлень. Виводяться з українського каталогу — він повний, решта
+ * каталогів часткові, тож `keyof` саме uk дає замкнений і чесний union.
+ */
+export type MessageKey = keyof typeof ukMessages;
+
+/** Каталог перекладів: неповний за визначенням — решту добирає fallback на uk. */
+export type Catalog = Partial<Record<MessageKey, string>>;
+
+/** Параметри підстановки у плейсхолдери `{name}`. */
+export type MessageParams = Record<string, string | number>;
+
+/** Транслятор — чиста функція, створена під конкретну локаль. */
+export type Translator = (key: MessageKey, params?: MessageParams) => string;

package/src/index.ts

@@ -0,0 +1,12 @@
+// Корінь флагманського пакета `simplycms` — НАВМИСНО порожній вхід.
+//
+// Фреймворк споживається виключно субшляхами `exports`-мапи
+// (`simplycms/contracts`, `simplycms/ui`, `simplycms/admin`, …): рівно так,
+// як до К0 споживалися окремі пакети, один до одного. Барель-корінь із
+// реекспортами звів би всі тіри T0→T5 в ОДИН граф модулів — імпорт будь-чого
+// тягнув би за собою і серверні клієнти, і адмінку, і теми, вбиваючи
+// tree-shaking і межу тірів, яку стереже `eslint.tier-zones.mjs`.
+//
+// Вхід лишається оголошеним, щоб `import 'simplycms'` резолвився, а пакет
+// збирався й проходив гейти пакування нарівні з рештою.
+export {};

package/src/plugin-sdk/definePlugin.ts

@@ -0,0 +1,80 @@
+import { createElement } from 'react';
+import type { PluginManifest } from 'simplycms/plugins/types';
+import type { PluginDefinition, SdkPluginModule } from './types';
+
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Декларативний вхід автора плагіна (спека §7).
+ *
+ * Помилки контракту — виняток одразу, при імпорті модуля: автор бачить їх у
+ * dev-консолі першим же рендером, а в магазині `bootstrapPlugins` ловить
+ * throw у своєму try/catch і пропускає плагін, не валячи застосунок.
+ */
+export function definePlugin(definition: PluginDefinition): SdkPluginModule {
+  const { name } = definition;
+  // Явна перевірка типу: RegExp.test коерсить undefined у рядок 'undefined',
+  // який... проходить [a-z][a-z0-9-]* (знахідка рев'ю Фази 3).
+  if (typeof name !== 'string' || !NAME_RE.test(name)) {
+    throw new Error(
+      `[plugin-sdk] Невалідне імʼя плагіна "${name}": очікується [a-z][a-z0-9-]* ` +
+        `(воно стає ключем у БД, префіксом таблиць plg_* і ключів i18n)`,
+    );
+  }
+  if (!definition.displayName || !definition.version) {
+    throw new Error(
+      `[plugin-sdk] "${name}": displayName і version обовʼязкові`,
+    );
+  }
+  if (typeof definition.engines?.simplycms !== 'string') {
+    throw new Error(
+      `[plugin-sdk] "${name}": engines.simplycms обовʼязковий ` +
+        `(діапазон сумісності з ядром, спека §7)`,
+    );
+  }
+
+  const slotNames = Object.keys(definition.slots ?? {});
+  const hookNames = Object.keys(definition.hooks ?? {});
+  const collision = slotNames.find((slot) => hookNames.includes(slot));
+  if (collision) {
+    // HookRegistry тримає один запис на пару (hook, plugin) — другий
+    // register мовчки замінив би перший, тому колізія — помилка контракту.
+    throw new Error(
+      `[plugin-sdk] "${name}": "${collision}" оголошено і в slots, і в hooks`,
+    );
+  }
+
+  const manifest: PluginManifest = {
+    name,
+    displayName: definition.displayName,
+    version: definition.version,
+    description: definition.description,
+    author: definition.author,
+    engines: definition.engines,
+    hooks: [...slotNames, ...hookNames].map((hookName) => ({ name: hookName })),
+    migrations: definition.migrations,
+    edgeFunctions: definition.edgeFunctions,
+    buckets: definition.buckets,
+  };
+
+  return {
+    manifest,
+    definition,
+    messages: definition.messages,
+    register(registry) {
+      for (const [slot, Component] of Object.entries(definition.slots ?? {})) {
+        registry.register(slot, name, (context: unknown) =>
+          createElement(Component, { key: `${name}:${slot}`, context }),
+        );
+      }
+      for (const [hook, handler] of Object.entries(definition.hooks ?? {})) {
+        registry.register(hook, name, handler);
+      }
+    },
+    unregister(registry) {
+      for (const hookName of [...slotNames, ...hookNames]) {
+        registry.unregister(hookName, name);
+      }
+    },
+  };
+}

package/src/plugin-sdk/index.ts

@@ -0,0 +1,22 @@
+// simplycms/plugin-sdk — єдина поверхня, яку дозволено імпортувати плагіну
+// (межа довіри, спека §7; примус — dependency-lint у eslint.config.mjs).
+
+export { definePlugin } from './definePlugin';
+// Валідатор живе в plugin-system (його кличе bootstrap) — тут лише реекспорт,
+// щоб автор плагіна мав усе з одного імпорту.
+//
+// 🔴 Не з барелю `simplycms/plugins`, а прямо з модуля: барель тягне ще й
+// lifecycle адмінки, який досі ходить у БД через supabase-js. Через цей
+// реекспорт PostgREST потрапляв у КОЖЕН чанк, що імпортує SDK, — тобто в
+// слоти вітрини. Валідатор — чиста функція без стану, тож дублювання його
+// коду в бандлі SDK нічого не коштує.
+export { validatePluginModule } from '../plugins/validatePluginModule';
+export { usePluginT } from './usePluginT';
+export { usePluginTable, type PluginTablePort } from './usePluginTable';
+export { usePluginConfig, type PluginConfigResult } from './usePluginConfig';
+export type {
+  PluginDefinition,
+  PluginMessages,
+  SdkPluginModule,
+  SlotComponent,
+} from './types';

package/src/plugin-sdk/server/config-db.ts

@@ -0,0 +1,57 @@
+import { eq } from 'drizzle-orm';
+import { plugins } from 'simplycms/schema';
+import {
+  withStorefrontDb,
+  withStoreOperatorDb,
+  type JsonValue,
+} from 'simplycms/storefront/loaders';
+
+/**
+ * Конфіг плагіна — рядок `plugins.config`. Читає будь-хто (грант SELECT на
+ * `plugins` має й анонім), пише лише адмін.
+ */
+
+/**
+ * Значення `config` або `null`, якщо рядка плагіна немає.
+ *
+ * 🔴 Розрізняти «рядка немає» і «config порожній» обовʼязково: перше — це
+ * типовий розсинхрон ключа конфігу з `manifest.name`, і мовчазні дефолти
+ * ховали б його (адмінка «успішно» зберігала б налаштування, яких плагін
+ * ніколи не побачить).
+ */
+export async function selectPluginConfig(
+  pluginName: string,
+): Promise<{ found: boolean; config: JsonValue }> {
+  const [row] = await withStorefrontDb((db) =>
+    db
+      .select({ config: plugins.config })
+      .from(plugins)
+      .where(eq(plugins.name, pluginName))
+      .limit(1),
+  );
+
+  return row
+    ? { found: true, config: (row.config ?? {}) as JsonValue }
+    : { found: false, config: {} };
+}
+
+/**
+ * Записати конфіг плагіна. `isAdmin` рахує СЕРВЕР — грант UPDATE на
+ * `plugins` має лише `app_admin`. Повертає `false`, якщо права немає.
+ */
+export async function savePluginConfig(
+  pluginName: string,
+  config: Record<string, JsonValue>,
+  isAdmin: boolean,
+): Promise<boolean> {
+  if (!isAdmin) return false;
+
+  await withStoreOperatorDb((db) =>
+    db
+      .update(plugins)
+      .set({ config, updatedAt: new Date().toISOString() })
+      .where(eq(plugins.name, pluginName)),
+  );
+
+  return true;
+}

package/src/plugin-sdk/server/guard.ts

@@ -0,0 +1,77 @@
+import { eq } from 'drizzle-orm';
+import { plugins } from 'simplycms/schema';
+import { withStorefrontDb } from 'simplycms/storefront/loaders';
+
+/**
+ * Межа даних плагіна (спека §7, рішення B9) — ЧИСТА частина.
+ *
+ * 🔴 Гард обовʼязково серверний. Раніше префікс `plg_` перевіряв хук у
+ * браузері, а доступ обмежувала RLS: імʼя таблиці все одно їхало в PostgREST,
+ * і межу тримала база. У контурі v2 бази на тому кінці немає — запит виконує
+ * НАШ хендлер під роллю магазину. Тобто якби імʼя таблиці не перевірялося
+ * тут, плагін прочитав би `orders` чи `users` рівно тим самим викликом.
+ */
+
+/** Ідентифікатор SQL, який гард узагалі згоден підставити в запит. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+
+/** Ключ плагіна в іменах таблиць: `hello-world` → `hello_world`. */
+export function tablePrefix(pluginName: string): string {
+  return `plg_${pluginName.toLowerCase().replace(/-/g, '_')}`;
+}
+
+/** Колонка у фільтрі/сортуванні. Кидає — інакше імʼя пішло б у SQL як є. */
+export function assertColumn(column: string): string {
+  if (!IDENTIFIER.test(column)) {
+    throw new Error(
+      `[plugin-sdk] Недопустиме імʼя колонки: ${JSON.stringify(column)}`,
+    );
+  }
+  return column;
+}
+
+/**
+ * Перевірити, що `table` — ВЛАСНА таблиця плагіна `pluginName`.
+ *
+ * Два незалежні критерії, обидва обовʼязкові:
+ *   1) імʼя = `plg_<ключ плагіна>` або `plg_<ключ плагіна>_<…>` — префікса
+ *      `plg_` самого по собі мало: він пустив би плагін у таблицю СУСІДА;
+ *   2) плагін відомий магазину — рядок у `plugins` існує. Це і є «манифест»
+ *      на боці сервера: реєстр модулів у браузері, і вірити його імені
+ *      хендлер не може.
+ */
+export function assertOwnTable(pluginName: string, table: string): string {
+  if (!IDENTIFIER.test(table)) {
+    throw new Error(
+      `[plugin-sdk] Недопустиме імʼя таблиці: ${JSON.stringify(table)}`,
+    );
+  }
+
+  const prefix = tablePrefix(pluginName);
+  if (table !== prefix && !table.startsWith(`${prefix}_`)) {
+    throw new Error(
+      `[plugin-sdk] Плагін "${pluginName}" не володіє таблицею "${table}": ` +
+        `порт працює лише з "${prefix}" і "${prefix}_*" (спека §7).`,
+    );
+  }
+
+  return table;
+}
+
+/** Чи знає магазин про такий плагін (рядок у `plugins`). */
+export async function assertKnownPlugin(pluginName: string): Promise<void> {
+  const [row] = await withStorefrontDb((db) =>
+    db
+      .select({ name: plugins.name })
+      .from(plugins)
+      .where(eq(plugins.name, pluginName))
+      .limit(1),
+  );
+
+  if (!row) {
+    throw new Error(
+      `[plugin-sdk] Плагін "${pluginName}" не зареєстрований у магазині — ` +
+        `порт даних недоступний.`,
+    );
+  }
+}

package/src/plugin-sdk/server/index.ts

@@ -0,0 +1,118 @@
+import { createServerFn } from '@tanstack/react-start';
+import { getRequest } from '@tanstack/react-start/server';
+import { z } from 'zod';
+import { isAdminRequest } from 'simplycms/auth';
+import type { JsonValue } from 'simplycms/storefront/loaders';
+import { selectPluginConfig, savePluginConfig } from './config-db';
+import {
+  deletePluginRow,
+  insertPluginRow,
+  selectPluginRows,
+  updatePluginRow,
+  type PluginRow,
+} from './table-db';
+
+/**
+ * Транспорт портів плагіна (рішення B9 спеки v2). Лише `createServerFn` —
+ * жодного звичайного експорту (див. докблок у `themes/server/index.ts`).
+ *
+ * 🔴 Контракт назовні бекенд-нейтральний: плагін називає таблицю й фільтри,
+ * а ЧИМ це виконано (Postgres, `withActor`, роль транзакції) з SDK не видно
+ * взагалі — саме тому порт пережив зміну бекенда без правок у плагінах.
+ */
+
+const cell = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const target = z.object({
+  plugin: z.string().min(1).max(100),
+  table: z.string().min(1).max(63),
+});
+
+/** Читання власної таблиці плагіна. Публічне: слоти вітрини бачить і гість. */
+export const pluginTableList = createServerFn({ method: 'GET' })
+  .inputValidator(
+    target.extend({
+      eq: z.record(z.string(), cell).optional(),
+      orderBy: z.string().max(63).optional(),
+      ascending: z.boolean().optional(),
+    }),
+  )
+  .handler(async ({ data }): Promise<PluginRow[]> => {
+    const input = data as z.output<typeof target> & {
+      eq?: Record<string, z.output<typeof cell>>;
+      orderBy?: string;
+      ascending?: boolean;
+    };
+    return selectPluginRows(input.plugin, input.table, input);
+  });
+
+/** Вставка рядка — лише адмін. */
+export const pluginTableInsert = createServerFn({ method: 'POST' })
+  .inputValidator(target.extend({ row: z.record(z.string(), cell) }))
+  .handler(async ({ data }): Promise<PluginRow> => {
+    const input = data as z.output<typeof target> & {
+      row: Record<string, z.output<typeof cell>>;
+    };
+    await requireAdmin();
+    return insertPluginRow(input.plugin, input.table, input.row);
+  });
+
+/** Оновлення рядка за `id` — лише адмін. */
+export const pluginTableUpdate = createServerFn({ method: 'POST' })
+  .inputValidator(
+    target.extend({
+      id: z.string().min(1).max(64),
+      patch: z.record(z.string(), cell),
+    }),
+  )
+  .handler(async ({ data }): Promise<PluginRow> => {
+    const input = data as z.output<typeof target> & {
+      id: string;
+      patch: Record<string, z.output<typeof cell>>;
+    };
+    await requireAdmin();
+    return updatePluginRow(input.plugin, input.table, input.id, input.patch);
+  });
+
+/** Видалення рядка за `id` — лише адмін. */
+export const pluginTableRemove = createServerFn({ method: 'POST' })
+  .inputValidator(target.extend({ id: z.string().min(1).max(64) }))
+  .handler(async ({ data }): Promise<void> => {
+    const input = data as z.output<typeof target> & { id: string };
+    await requireAdmin();
+    await deletePluginRow(input.plugin, input.table, input.id);
+  });
+
+/** Конфіг плагіна: `found: false` — рядка з таким `name` у БД немає. */
+export const pluginConfigRead = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ plugin: z.string().min(1).max(100) }))
+  .handler(async ({ data }): Promise<{ found: boolean; config: JsonValue }> =>
+    selectPluginConfig((data as { plugin: string }).plugin),
+  );
+
+/** Запис конфіга плагіна — лише адмін; `false` означає відмову доступу. */
+export const pluginConfigWrite = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      plugin: z.string().min(1).max(100),
+      config: z.record(z.string(), z.json()),
+    }),
+  )
+  .handler(async ({ data }): Promise<boolean> => {
+    const input = data as { plugin: string; config: Record<string, JsonValue> };
+    return savePluginConfig(
+      input.plugin,
+      input.config,
+      await isAdminRequest(getRequest().headers),
+    );
+  });
+
+/**
+ * 🔴 Мутації падають ДО походу в БД, а не покладаються на грант. Роль
+ * `app_admin` вмикається типізованою перевіркою в TS (перший рубіж B5″), тож
+ * хендлер, який пустив би чужий запит під нею, зняв би цей рубіж власноруч.
+ */
+async function requireAdmin(): Promise<void> {
+  if (!(await isAdminRequest(getRequest().headers))) {
+    throw new Error('[plugin-sdk] Запис у таблицю плагіна доступний адміну.');
+  }
+}