includio-cms 0.36.1 → 0.36.3

package/API.md

@@ -1,8 +1,8 @@
-# includio-cms — Public API v0.36.1
+# includio-cms — Public API v0.36.3
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 
-Entry points: **19** · Stable: **492** · Experimental: **4**
+Entry points: **19** · Stable: **495** · Experimental: **4**
 
 Tags:
 - `@public` — frozen for v1.0; semver-protected.
@@ -446,6 +446,7 @@ Tags:
 - `type Currency = 'PLN'`
 - `defineShop(config: ShopConfig): ResolvedShopConfig`
 - `type DepositAmount = { type: 'percent'; value: number } | { type: 'amount'; value: number }` — Deposit amount specifier. `percent` charges `floor(base * value / 100)` of
+- `interface EmailContext` — Context passed to a {@link SubjectPlaceholderResolver}. Currently carries
 - `fakturowniaAdapter(opts: FakturowniaAdapterOptions): InvoicingAdapter` — Invoicing adapter backed by Fakturownia (fakturownia.pl). Issues a paid VAT
 - `interface FakturowniaAdapterOptions`
 - `filterUpcoming(variants: T[], config: VariantExpiryConfig | null, now?: Date): T[]` — Return the subset of `variants` that have not yet expired. Order is
@@ -471,6 +472,7 @@ Tags:
 - `type Order = typeof shopOrdersTable.$inferSelect` — Public row type for a single shop order — mirrors the Drizzle `shop_orders`
 - `interface OrderRef`
 - `type OrderStatus = | 'new' | 'awaitingPayment' | 'paid' | 'preparing' | 'sent' | 'done' | 'cancelled' | 'paymentReje...`
+- `interface OrderStatusConfig` — Per-status configuration. Lets consumer projects hide a built-in status from
 - `interface PartialPayment` — Persisted partial-payment summary on `order.partialPayment` when the order
 - `interface PaymentAdapter`
 - `interface PaymentCreateContext`
@@ -490,6 +492,7 @@ Tags:
 - `interface ShopFeatures`
 - `stripeAdapter(opts: StripeAdapterOptions): PaymentAdapter` — Stripe payment adapter (Checkout Session flow).
 - `interface StripeAdapterOptions`
+- `type SubjectPlaceholderResolver = (order: Order, ctx: EmailContext) => string` — Resolves one `{placeholder}` token in an email subject template to a string.
 - `type VariantAttribute = | VariantAttributeText | VariantAttributeNumber | VariantAttributeDatetime | VariantAttributeSele...` — Schema descriptor for one product-variant attribute (city, startsAt, …).
 - `interface VariantAttributeBoolean`
 - `interface VariantAttributeDatetime`

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.36.3 — 2026-06-11
+
+Relacje opcjonalne — fix: niewybrana relacja (pole bez `required`) blokowała zapis wpisu („Invalid input: expected string, received null") albo wywalała populację przy pustym stringu. Teraz „brak wyboru" działa w obie strony — Zod akceptuje null/""/undefined, a populacja pomija puste wartości.
+
+### Fixed
+- Schemat Zod relacji niewymaganej (`generateZodSchemaFromField`) akceptuje teraz `null` obok `""`/`undefined` (`z.string().nullish().default("")`). Wcześniej `null` (znormalizowane dane lub wyczyszczenie pola w adminie) rzucał „Invalid input: expected string, received null" i blokował zapis wpisu. Bez nowej walidacji uuid — dowolny string nadal przechodzi, więc zero regresji dla istniejących danych.
+- `resolveRelationFields` pomija puste stringi przy zbieraniu ID do populacji (relacje pojedyncze i multiple). Pusty string nie trafia już do zapytania `WHERE id IN ('')`, które Postgres odrzucał jako nieprawidłowy uuid (`invalid input syntax for type uuid: ""`).
+- Efekt łączny: opcjonalna relacja bez wyboru działa w obie strony — zapis w adminie (Zod akceptuje null/"") oraz odczyt na froncie (populacja pomija puste). Dodany regression test dla akceptacji null/""/undefined.
+
+## 0.36.2 — 2026-06-08
+
+Per-status overrides (`ShopConfig.orderStatuses`) + globalny rejestr subject placeholders (`formatSubject`/`ShopConfig.emailSubjectPlaceholders`) + nowy hook `ShopConfig.resolveStatusSubject` do czytania subject z CMS + Handlebars helper `{{{structured}}}` renderujący `StructuredContentDoc` (TipTap) jako email-safe HTML z automatycznym token replacement. Email context rozszerzony o billing fields (firma/NIP/adres/telefon). Dwa fixy bugów w resolverze CMS singletons w mailach. Zaprojektowane pod sklepy ze szkoleniami/wydarzeniami (stationary), gdzie statusy `preparing`/`sent` nie mają sensu. Wszystkie API generyczne, do reusu w innych consumer projects.
+
+### Added
+- **`ShopConfig.orderStatuses?: OrderStatusConfig[]`** — opcjonalna lista per-status overrides. `hidden: true` chowa status z admin dropdownu (`shop-order-detail-page.svelte`) i blokuje manual transitions z admina rzucając nowy `HiddenStatusTransitionError` (kod `HIDDEN_STATUS_TRANSITION`). `sendEmail: false` powoduje, że `sendOrderStatusEmail` early-returnuje przy wejściu w ten status. Webhook / carrier-driven transitions BYPASSują guard — provider-driven update musi przejść bez względu na config (rola engine fundamentalna). Nowy parametr `updateOrderStatus(orderId, status, { source: "admin" })` rozróżnia kontekst; `source: "webhook" | "system"` (default) zawsze pomija check. Pure helpery: `assertManualStatusAllowed(status, orderStatuses)` (rzuca) i `shouldSendStatusEmail(status, orderStatuses)` (zwraca bool).
+- **`formatSubject` + `builtInSubjectPlaceholders`** (`$lib/shop/server/emailSubject.js`) — generyczna interpolacja `{key}` w subject mailach. Built-in: `{order_number}`, `{customer_name}`, `{customer_email}`, `{total_gross}` (formatted PLN currency), `{currency}`. Nowy `ShopConfig.emailSubjectPlaceholders?: Record<string, SubjectPlaceholderResolver>` — projektowe rozszerzenia (np. `{event_date}` dla szkoleń), mergowane na built-in (custom wins). `sendOrderStatusEmail` przepuszcza fallback subject (`STATUS_SUBJECTS[status][lang] · {order_number}`) przez `formatSubject` zanim wyśle. Nieznane placeholdery są lenient — zostają w stringu.
+- **`ShopConfig.resolveStatusSubject?(status, ctx) => string | null | undefined`** — async hook pozwalający consumerowi pobrać template subject z dowolnego źródła (typically CMS singleton). Wywoływany w `sendOrderStatusEmail` przed `formatSubject`, więc tokeny działają tak samo jak w defaultach. Pusta wartość / błąd → fallback do `STATUS_SUBJECTS`. Paczka pozostaje agnostyczna o CMS schemie consumera.
+- **Handlebars helper `{{{structured doc}}}`** (`emailTemplateRegistry.ts`) — renderuje `StructuredContentDoc` (output TipTap fielda `content`) jako inline HTML dla maili. Używa `structuredToHtml()` z core; zwraca `SafeString`. Po render — automatyczne **token replacement** przez `formatSubject` (built-in + `emailSubjectPlaceholders`) jeśli `order` jest w Handlebars context. Pozwala wpisać `{order_number}` w polu TipTap w CMSie i mieć je podmienione w wysłanym mailu. Pusty/undefined doc → "".
+- **Email context rozszerzony o billing fields** (`email.ts`): `order.customerCompanyName`, `customerNip`, `customerPhone`, `billingAddress` (`{street, postalCode, city, country?}`) + flagi `hasCompany` / `hasBillingAddress` dla wygodnych `{{#if}}` w templates. Pozwala renderować WooCommerce-style billing block bez custom JOIN.
+
+### Fixed
+- **`extractCmsSlugs` skanuje partials** — wcześniej AST tylko głównego templatu był parsowany, więc `cms.<slug>.*` referencje w partials (np. `cms.globalSettings.legalEntity` w `_partials/footer.pl.html`) były ignorowane → singleton nie był prefetchowany → context był pusty → fallbacki renderowane mimo wypełnionego CMSa. Teraz dodatkowo iteruje przez wszystkie zarejestrowane `Handlebars.partials` i merguje slugi.
+- **`resolveCmsContext` poprawnie spłaszcza entry** — wcześniej używał `entry?.data ?? {}`, ale `resolveEntry` zwraca obiekt spreadowany (`{ _id, _slug, _type, _publishedAt, _url, ...fields }`) bez pola `.data`. Efekt: każdy `cms.<slug>` w mailu był pustym obiektem. Teraz strip-uje meta keys (`_*`) i zwraca user fields. Mock w testach był niezgodny z prawdziwym API, dlatego bug przetrwał — naprawiony, dodany regression test dla nested path.
+
 ## 0.36.1 — 2026-06-08
 
 Fakturownia adapter — fix B2C: gdy brak `buyer.nip` i `buyer.companyName`, payload zawiera `buyer_first_name` + `buyer_last_name` (rozdzielone przez `splitFullName` — spójnie z PayU/InPost). Bez tej zmiany Fakturownia API odrzuca fakturę dla osoby fizycznej z 422 `buyer_tax_no — nie może być puste`.

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.36.1)
+# Includio CMS Documentation (v0.36.3)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 

package/ROADMAP.md

@@ -57,6 +57,7 @@
 ## Backlog
 
 - [ ] `[feature]` `[P2]` Date/datetime field — przebudowa na shadcn-svelte (bits-ui Calendar/DatePicker) zamiast natywnego inputu. Zgłoszone w QA Etap 5a (4/5); funkcjonalnie OK, odłożone jako osobny redesign pola daty. <!-- files: src/lib/admin/components/fields/date-field.svelte, datetime-field.svelte -->
+- [ ] `[feature]` `[P2]` `<Video>` — eksponować ref wewnętrznego `<video>` (np. bindable `element` prop lub forward `bind:this`). Obecnie konsument potrzebujący programowej kontroli (play/pause, scrub, mute toggle) musi owijać w `<div bind:this>` + `querySelector('video')` — boilerplate i kruche. Zgłoszone przy customowym hero-wideo (autoplay + przycisk pauzy). <!-- files: src/lib/sveltekit/components/video.svelte -->
 - [ ] `[feature]` `[P1]` Re-introduce entry autosave with strict draft-only guard (opt-in via `cms.config.ts`, never touch published versions, debounced + visual countdown). Removed in 0.26.0 / S8 because old impl could touch published data ambiguously.
 - [ ] `[feature]` `[P2]` Migrate `shipping-method-form` na sveltekit-superforms + formsnap (S8 zostawił hand-rolled validation + FormErrorSummary; pełna migracja wymaga schema dla multi-lang record + dynamic carrier config + price net/gross toggle).
 - [ ] `[feature]` `[P2]` Storybook story dla `entry-page` (Default/Saving/Saved/Error/Draft/WithErrors/Confirmation) — wymaga mock context: `setRemotes` (5 commands), `setBreadcrumbs`, `setContentLanguage`, RawEntry/DbEntryVersion fixtures. S8 odłożone do S10 a11y sweep.

package/dist/admin/client/shop/shop-order-detail-page.svelte

@@ -148,6 +148,13 @@
 		{ value: 'refunded', label: 'Zwrócone' }
 	];
 
+	// Statuses the consumer marked `hidden: true` in defineShop({ orderStatuses })
+	// — never shown in the dropdown (manual transitions blocked server-side too).
+	const hiddenStatuses = $derived(
+		new Set<OrderStatus>(((query.current?.hiddenStatuses as OrderStatus[] | undefined) ?? []))
+	);
+	const visibleStatuses = $derived(STATUSES.filter((s) => !hiddenStatuses.has(s.value)));
+
 	let newStatus = $state<OrderStatus | ''>('');
 	let note = $state('');
 	let saving = $state(false);
@@ -482,7 +489,7 @@
 							class="border-border w-full rounded-lg border px-3 py-2 text-sm"
 						>
 							<option value="">— wybierz —</option>
-							{#each STATUSES as s (s.value)}
+							{#each visibleStatuses as s (s.value)}
 								<option value={s.value} disabled={s.value === order.status}>{s.label}</option>
 							{/each}
 						</select>

package/dist/admin/remote/shop.remote.d.ts

@@ -211,6 +211,7 @@ export declare const getOrderForAdmin: import("@sveltejs/kit").RemoteQueryFuncti
         code: string;
         discountAmount: number;
     } | null;
+    hiddenStatuses: import("../../shop/types.js").OrderStatus[];
 } | null>;
 export declare const updateOrderStatusCmd: import("@sveltejs/kit").RemoteCommand<{
     orderId: string;

package/dist/admin/remote/shop.remote.js

@@ -171,7 +171,8 @@ export const getOrderForAdmin = query(z.string(), async (id) => {
         getOrderStatusHistory(id),
         getOrderCoupon(id).catch(() => null)
     ]);
-    return { order, items, history, coupon };
+    const hiddenStatuses = getCMS().shopConfig?.orderStatuses?.filter((s) => s.hidden).map((s) => s.key) ?? [];
+    return { order, items, history, coupon, hiddenStatuses };
 });
 export const updateOrderStatusCmd = command(z.object({
     orderId: z.string(),
@@ -179,7 +180,11 @@ export const updateOrderStatusCmd = command(z.object({
     note: z.string().optional()
 }), async ({ orderId, status, note }) => {
     requireAuth();
-    const updated = await updateOrderStatus(orderId, status, { note, changedBy: 'admin' });
+    const updated = await updateOrderStatus(orderId, status, {
+        note,
+        changedBy: 'admin',
+        source: 'admin'
+    });
     return updated;
 });
 export const deleteOrderCmd = command(z.object({ orderId: z.string() }), async ({ orderId }) => {

package/dist/core/fields/fieldSchemaToTs.js

@@ -214,7 +214,11 @@ export function generateZodSchemaFromField(field, languages, options = {
             if (field.required) {
                 return z.string().uuid({ message: msg.required });
             }
-            return z.string().optional().default('');
+            // Non-required: a relation id, or "no selection". The admin (and legacy
+            // data) may send '', null or undefined for an unset relation — accept
+            // all of them (`.nullish()` adds null + undefined) so an empty optional
+            // relation never blocks save. Empty values are skipped at populate time.
+            return z.string().nullish().default('');
         }
         case 'object': {
             // Children's `required` is enforced when the object itself is required OR

package/dist/core/server/fields/resolveRelationFields.js

@@ -30,13 +30,15 @@ export async function resolveRelationFields(data, fields, ctx) {
             }
             switch (field.type) {
                 case 'relation': {
+                    // Skip empty strings — an unset optional relation stores '' and must
+                    // never reach the id query (Postgres rejects '' as uuid).
                     if (field.multiple && Array.isArray(val)) {
                         for (const id of val) {
-                            if (typeof id === 'string')
+                            if (typeof id === 'string' && id !== '')
                                 entriesIds.push(id);
                         }
                     }
-                    else if (typeof val === 'string') {
+                    else if (typeof val === 'string' && val !== '') {
                         entriesIds.push(val);
                     }
                     break;

package/dist/shop/index.d.ts

@@ -12,6 +12,6 @@ export type { InpostAdapterOptions, InpostSenderAddress, GeowidgetConfigPreset,
 export { fakturowniaAdapter } from './adapters/fakturownia/index.js';
 export type { FakturowniaAdapterOptions } from './adapters/fakturownia/index.js';
 export { isValidNip } from './nip.js';
-export type { ShopConfig, ResolvedShopConfig, Currency, Order, OrderStatus, PaymentAdapter, PaymentCreateContext, PaymentRefundInput, PaymentRefundResult, CarrierAdapter, CarrierEvent, ShipmentCreateInput, ShipmentCreateResult, ShipmentLabel, ConsentConfig, ShopFeatures, PaymentCreateResult, PaymentEvent, OrderRef, CouponRef, I18nText, VariantAttribute, VariantAttributeText, VariantAttributeNumber, VariantAttributeDatetime, VariantAttributeSelect, VariantAttributeBoolean, VariantAttributeImage, VariantAttributeEntry, VariantAttributeSlug, VariantLabelConfig, VariantExpiryConfig, PaymentPolicy, DepositAmount, PartialPayment, InvoicingAdapter, InvoiceIssuePolicy, InvoiceBuyer, InvoiceLineItem, InvoicePayload, InvoiceCreateResult, InvoiceContext } from './types.js';
+export type { ShopConfig, ResolvedShopConfig, Currency, Order, OrderStatus, OrderStatusConfig, SubjectPlaceholderResolver, EmailContext, PaymentAdapter, PaymentCreateContext, PaymentRefundInput, PaymentRefundResult, CarrierAdapter, CarrierEvent, ShipmentCreateInput, ShipmentCreateResult, ShipmentLabel, ConsentConfig, ShopFeatures, PaymentCreateResult, PaymentEvent, OrderRef, CouponRef, I18nText, VariantAttribute, VariantAttributeText, VariantAttributeNumber, VariantAttributeDatetime, VariantAttributeSelect, VariantAttributeBoolean, VariantAttributeImage, VariantAttributeEntry, VariantAttributeSlug, VariantLabelConfig, VariantExpiryConfig, PaymentPolicy, DepositAmount, PartialPayment, InvoicingAdapter, InvoiceIssuePolicy, InvoiceBuyer, InvoiceLineItem, InvoicePayload, InvoiceCreateResult, InvoiceContext } from './types.js';
 export { interpolateTemplate, renderShopName } from './template.js';
 export type { I18nTemplate } from './template.js';

package/dist/shop/server/email.d.ts

@@ -1,4 +1,12 @@
-import type { OrderStatus } from '../types.js';
+import type { OrderStatus, OrderStatusConfig } from '../types.js';
+/**
+ * Decide whether a status-change email should be sent for a given status,
+ * given the consumer-supplied per-status config (`ShopConfig.orderStatuses`).
+ * Defaults to `true` — only an entry with `sendEmail === false` suppresses
+ * the email. Pure helper, exported for testing + reuse.
+ * @public
+ */
+export declare function shouldSendStatusEmail(status: OrderStatus, orderStatuses: OrderStatusConfig[] | undefined): boolean;
 /**
  * List of template names a shop install must ship in `dist/shop/templates/`.
  * Consumed by `validateBuiltinTemplates` at CMS bootstrap.

package/dist/shop/server/email.js

@@ -4,6 +4,18 @@ import { getOrderCoupon } from './coupons.js';
 import { requireShopConfig } from './db.js';
 import { buildOrderViewUrl } from './order-access-url.js';
 import { renderEmailTemplate } from './emailTemplateRegistry.js';
+import { formatSubject } from './emailSubject.js';
+/**
+ * Decide whether a status-change email should be sent for a given status,
+ * given the consumer-supplied per-status config (`ShopConfig.orderStatuses`).
+ * Defaults to `true` — only an entry with `sendEmail === false` suppresses
+ * the email. Pure helper, exported for testing + reuse.
+ * @public
+ */
+export function shouldSendStatusEmail(status, orderStatuses) {
+    const cfg = orderStatuses?.find((s) => s.key === status);
+    return cfg?.sendEmail !== false;
+}
 const STATUS_SUBJECTS = {
     new: { pl: 'Zamówienie przyjęte', en: 'Order received' },
     awaitingPayment: { pl: 'Oczekiwanie na płatność', en: 'Awaiting payment' },
@@ -53,6 +65,8 @@ export const REQUIRED_TEMPLATE_NAMES = [
 export async function sendOrderStatusEmail(orderId, status) {
     const cms = getCMS();
     const shop = requireShopConfig();
+    if (!shouldSendStatusEmail(status, shop.orderStatuses))
+        return;
     const emailAdapter = cms.emailAdapter;
     if (!emailAdapter) {
         console.warn('[shop] No email adapter configured — skipping status email.');
@@ -134,6 +148,12 @@ export async function sendOrderStatusEmail(orderId, status) {
             status: order.status,
             customerName: order.customerName ?? '',
             customerEmail: order.customerEmail,
+            customerPhone: order.customerPhone ?? null,
+            customerCompanyName: order.customerCompanyName ?? null,
+            customerNip: order.customerNip ?? null,
+            billingAddress: (order.billingAddress ?? null),
+            hasCompany: Boolean(order.customerCompanyName || order.customerNip),
+            hasBillingAddress: Boolean(order.billingAddress && order.billingAddress.street),
             language: order.language,
             totalGross: formatPrice(order.totalGross, order.currency),
             totalNet: formatPrice(order.totalNet, order.currency),
@@ -167,7 +187,21 @@ export async function sendOrderStatusEmail(orderId, status) {
             adminEmail: shop.adminEmail ?? null
         }
     };
-    const subject = `${STATUS_SUBJECTS[status][subjectKey]} · ${order.number}`;
+    // Subject template lookup: project hook (typically reads CMS) → package default.
+    // Both feed through `formatSubject` so `{order_number}` etc. are formatted the same way.
+    let subjectTemplate;
+    if (shop.resolveStatusSubject) {
+        try {
+            subjectTemplate = await shop.resolveStatusSubject(status, { order, language: lang });
+        }
+        catch (err) {
+            console.error('[shop] resolveStatusSubject threw — falling back to default:', err);
+        }
+    }
+    if (!subjectTemplate || typeof subjectTemplate !== 'string' || !subjectTemplate.trim()) {
+        subjectTemplate = `${STATUS_SUBJECTS[status][subjectKey]} · {order_number}`;
+    }
+    const subject = formatSubject(subjectTemplate, order, { language: lang }, shop.emailSubjectPlaceholders);
     const templateName = STATUS_TO_TEMPLATE[status];
     let html;
     try {

package/dist/shop/server/emailSubject.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Subject placeholder registry — generic `{key}`-style interpolation for the
+ * email subject string fed to {@link sendOrderStatusEmail}. Built-in keys
+ * cover the data common to every shop order; consumer projects merge custom
+ * resolvers via `ShopConfig.emailSubjectPlaceholders` to add domain-specific
+ * tokens (e.g. `{event_date}`).
+ *
+ * Unknown placeholders are left untouched (lenient), so a typo in CMS-managed
+ * copy never breaks delivery.
+ */
+import type { EmailContext, Order, SubjectPlaceholderResolver } from '../types.js';
+/**
+ * Default subject-placeholder resolvers, available in every shop install.
+ * Merged with `ShopConfig.emailSubjectPlaceholders` in {@link formatSubject};
+ * custom resolvers take precedence on key collision.
+ * @public
+ */
+export declare const builtInSubjectPlaceholders: Record<string, SubjectPlaceholderResolver>;
+/**
+ * Replace every `{key}` token in `template` with the result of the matching
+ * resolver. Custom resolvers (e.g. from `ShopConfig.emailSubjectPlaceholders`)
+ * are merged on top of {@link builtInSubjectPlaceholders} — colliding keys
+ * are overridden. Unknown keys are left untouched.
+ *
+ * @param template Subject template (CMS string or hardcoded fallback).
+ * @param order Resolved order row passed to each resolver.
+ * @param ctx Minimal email context (currently just `language`).
+ * @param custom Optional per-project resolvers merged into the registry.
+ * @public
+ */
+export declare function formatSubject(template: string, order: Order, ctx: EmailContext, custom?: Record<string, SubjectPlaceholderResolver>): string;

package/dist/shop/server/emailSubject.js

@@ -0,0 +1,53 @@
+/**
+ * Subject placeholder registry — generic `{key}`-style interpolation for the
+ * email subject string fed to {@link sendOrderStatusEmail}. Built-in keys
+ * cover the data common to every shop order; consumer projects merge custom
+ * resolvers via `ShopConfig.emailSubjectPlaceholders` to add domain-specific
+ * tokens (e.g. `{event_date}`).
+ *
+ * Unknown placeholders are left untouched (lenient), so a typo in CMS-managed
+ * copy never breaks delivery.
+ */
+function formatMoney(minorUnits, currency) {
+    const cur = typeof currency === 'string' && currency.length > 0 ? currency : 'PLN';
+    return new Intl.NumberFormat('pl-PL', {
+        style: 'currency',
+        currency: cur,
+        minimumFractionDigits: 2
+    }).format(minorUnits / 100);
+}
+/**
+ * Default subject-placeholder resolvers, available in every shop install.
+ * Merged with `ShopConfig.emailSubjectPlaceholders` in {@link formatSubject};
+ * custom resolvers take precedence on key collision.
+ * @public
+ */
+export const builtInSubjectPlaceholders = {
+    order_number: (o) => o.number,
+    customer_name: (o) => o.customerName ?? '',
+    customer_email: (o) => o.customerEmail,
+    total_gross: (o) => formatMoney(o.totalGross, o.currency),
+    currency: (o) => o.currency
+};
+const PLACEHOLDER_RE = /\{(\w+)\}/g;
+/**
+ * Replace every `{key}` token in `template` with the result of the matching
+ * resolver. Custom resolvers (e.g. from `ShopConfig.emailSubjectPlaceholders`)
+ * are merged on top of {@link builtInSubjectPlaceholders} — colliding keys
+ * are overridden. Unknown keys are left untouched.
+ *
+ * @param template Subject template (CMS string or hardcoded fallback).
+ * @param order Resolved order row passed to each resolver.
+ * @param ctx Minimal email context (currently just `language`).
+ * @param custom Optional per-project resolvers merged into the registry.
+ * @public
+ */
+export function formatSubject(template, order, ctx, custom) {
+    const resolvers = custom
+        ? { ...builtInSubjectPlaceholders, ...custom }
+        : builtInSubjectPlaceholders;
+    return template.replace(PLACEHOLDER_RE, (match, key) => {
+        const fn = resolvers[key];
+        return fn ? fn(order, ctx) : match;
+    });
+}

package/dist/shop/server/emailTemplateRegistry.d.ts

@@ -20,7 +20,9 @@ interface ResolveResult {
 declare function resolveTemplatePath(projectDir: string, name: string, lang: Lang, fallbackLang: Lang): ResolveResult | null;
 /**
  * Traverse Handlebars AST and collect all `cms.<slug>.*` accessor slugs.
- * Returns the unique set so the renderer can prefetch them.
+ * Also scans all currently-registered partials so `cms.*` refs inside
+ * `{{> footer}}` etc. are also prefetched. Returns the unique set so the
+ * renderer can prefetch them.
  */
 declare function extractCmsSlugs(ast: hbs.AST.Program): Set<string>;
 /**

package/dist/shop/server/emailTemplateRegistry.js

@@ -12,6 +12,9 @@ import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
 import { getCMS } from '../../core/cms.js';
 import { resolveEntry } from '../../sveltekit/server/index.js';
+import { structuredToHtml } from '../../core/fields/structuredToHtml.js';
+import { formatSubject } from './emailSubject.js';
+import { requireShopConfig } from './db.js';
 const PACKAGE_TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates');
 const cache = new Map();
 let helpersRegistered = false;
@@ -50,6 +53,32 @@ function registerHelpers() {
         return new Intl.DateTimeFormat('pl-PL').format(d);
     });
     Handlebars.registerHelper('eq', (a, b) => a === b);
+    // `{{{structured doc}}}` — render a TipTap `StructuredContentDoc` (output of
+    // AriaCMS `content` fields) as inline HTML for email. Returns a SafeString
+    // so the caller's triple-stache passes the markup through; pre-rendered text
+    // inside `doc` is still HTML-escaped by `structuredToHtml`.
+    //
+    // Token replacement: any `{key}` token found inside the rendered HTML is
+    // substituted via `formatSubject` (built-in placeholders + project
+    // `emailSubjectPlaceholders`). Requires `order` in the rendering context.
+    // Uses `function` (not arrow) so `this` is the Handlebars root context.
+    Handlebars.registerHelper('structured', function (doc) {
+        if (!doc || typeof doc !== 'object')
+            return '';
+        let html = structuredToHtml(doc);
+        // Best-effort token replacement — silently skip when no order in scope.
+        const order = this?.order;
+        if (order) {
+            try {
+                const shop = requireShopConfig();
+                html = formatSubject(html, order, { language: order.language ?? 'pl' }, shop.emailSubjectPlaceholders);
+            }
+            catch {
+                // shop config not initialized — leave HTML as-is
+            }
+        }
+        return new Handlebars.SafeString(html);
+    });
     helpersRegistered = true;
 }
 /**
@@ -77,7 +106,9 @@ function resolveTemplatePath(projectDir, name, lang, fallbackLang) {
 }
 /**
  * Traverse Handlebars AST and collect all `cms.<slug>.*` accessor slugs.
- * Returns the unique set so the renderer can prefetch them.
+ * Also scans all currently-registered partials so `cms.*` refs inside
+ * `{{> footer}}` etc. are also prefetched. Returns the unique set so the
+ * renderer can prefetch them.
  */
 function extractCmsSlugs(ast) {
     const slugs = new Set();
@@ -114,6 +145,19 @@ function extractCmsSlugs(ast) {
         }
     };
     visit(ast);
+    // Also visit ASTs of every registered partial — `cms.*` paths in shared
+    // partials like footer/legal_notice would otherwise be missed and the
+    // underlying singleton would never be prefetched.
+    for (const partial of Object.values(Handlebars.partials)) {
+        if (typeof partial !== 'string')
+            continue;
+        try {
+            visit(Handlebars.parse(partial));
+        }
+        catch {
+            // malformed partial — already logged elsewhere when it tries to render
+        }
+    }
     return slugs;
 }
 /**
@@ -185,7 +229,16 @@ async function resolveCmsContext(slugs) {
     const entries = await Promise.all(slugList.map(async (slug) => {
         try {
             const entry = await resolveEntry({ collection: slug });
-            return [slug, entry?.data ?? {}];
+            if (!entry)
+                return [slug, {}];
+            // `resolveEntry` returns a flat object: `{ _id, _slug, _type, _publishedAt, _url, ...fields }`.
+            // Strip leading-underscore meta keys so `cms.<slug>.<field>` matches the user-defined schema.
+            const data = {};
+            for (const [k, v] of Object.entries(entry)) {
+                if (!k.startsWith('_'))
+                    data[k] = v;
+            }
+            return [slug, data];
         }
         catch {
             return [slug, {}];

package/dist/shop/server/orders.d.ts

@@ -1,6 +1,6 @@
 import { shopOrderItemsTable, shopOrderStatusHistoryTable, shopOrdersTable } from '../../db-postgres/schema/shop/index.js';
 import type { CartItemRef } from '../cart/types.js';
-import type { OrderStatus } from '../types.js';
+import type { OrderStatus, OrderStatusConfig } from '../types.js';
 /**
  * @public
  * Thrown by `createOrderFromCart` when the cart contains items from multiple
@@ -40,6 +40,25 @@ export type OrderDeletionDecision = {
 export declare function decideOrderDeletion(status: OrderStatus, invoice: {
     status: 'pending' | 'issued' | 'sent' | 'failed';
 } | null): OrderDeletionDecision;
+/**
+ * @public
+ * Thrown by {@link assertManualStatusAllowed} (and {@link updateOrderStatus}
+ * when called from the admin UI) for a manual transition into a status the
+ * consumer marked as hidden in `ShopConfig.orderStatuses`. Webhook /
+ * carrier-driven transitions bypass this check — `source: 'webhook'`.
+ */
+export declare class HiddenStatusTransitionError extends Error {
+    readonly status: OrderStatus;
+    readonly code = "HIDDEN_STATUS_TRANSITION";
+    constructor(status: OrderStatus);
+}
+/**
+ * @public
+ * Throw a {@link HiddenStatusTransitionError} when the target status is marked
+ * `hidden: true` in the consumer config. No-op when no config / no matching
+ * entry. Pure check, exported for testing + reuse by admin pre-flight UI.
+ */
+export declare function assertManualStatusAllowed(status: OrderStatus, orderStatuses: OrderStatusConfig[] | undefined): void;
 /**
  * @public
  * Thrown by `softDeleteOrder` when the order can't be hidden: either its status
@@ -98,6 +117,13 @@ export declare function updateOrderStatus(orderId: string, status: OrderStatus,
     note?: string;
     changedBy?: string;
     paymentKind?: 'full' | 'deposit' | 'balance';
+    /**
+     * Caller context. `'admin'` enforces the `orderStatuses[].hidden` guard
+     * (throws {@link HiddenStatusTransitionError}). `'webhook'` and `'system'`
+     * (default) bypass it — provider-driven and engine-internal transitions
+     * are always allowed so a hidden status never silently drops a webhook.
+     */
+    source?: 'admin' | 'webhook' | 'system';
 }): Promise<OrderRow>;
 /**
  * @internal

package/dist/shop/server/orders.js

@@ -60,6 +60,33 @@ export function decideOrderDeletion(status, invoice) {
     }
     return { ok: true };
 }
+/**
+ * @public
+ * Thrown by {@link assertManualStatusAllowed} (and {@link updateOrderStatus}
+ * when called from the admin UI) for a manual transition into a status the
+ * consumer marked as hidden in `ShopConfig.orderStatuses`. Webhook /
+ * carrier-driven transitions bypass this check — `source: 'webhook'`.
+ */
+export class HiddenStatusTransitionError extends Error {
+    status;
+    code = 'HIDDEN_STATUS_TRANSITION';
+    constructor(status) {
+        super(`Manual transition into hidden status "${status}" is not allowed.`);
+        this.status = status;
+        this.name = 'HiddenStatusTransitionError';
+    }
+}
+/**
+ * @public
+ * Throw a {@link HiddenStatusTransitionError} when the target status is marked
+ * `hidden: true` in the consumer config. No-op when no config / no matching
+ * entry. Pure check, exported for testing + reuse by admin pre-flight UI.
+ */
+export function assertManualStatusAllowed(status, orderStatuses) {
+    const cfg = orderStatuses?.find((s) => s.key === status);
+    if (cfg?.hidden === true)
+        throw new HiddenStatusTransitionError(status);
+}
 /**
  * @public
  * Thrown by `softDeleteOrder` when the order can't be hidden: either its status
@@ -385,6 +412,9 @@ export async function updateOrderStatus(orderId, status, opts = {}) {
     if (order.status === status)
         return order;
     const shop = requireShopConfig();
+    if (opts.source === 'admin') {
+        assertManualStatusAllowed(status, shop.orderStatuses);
+    }
     // Deposit-kind transition to `paid`: bump partialPayment.paidAmount to the
     // deposit amount, stamp paidAt, and flag balanceOwed = true. Stock is
     // permanently confirmed by the existing `paid` branch below — no TTL

package/dist/shop/types.d.ts

@@ -8,6 +8,43 @@ export type Currency = 'PLN';
  */
 export type Order = typeof shopOrdersTable.$inferSelect;
 export type OrderStatus = 'new' | 'awaitingPayment' | 'paid' | 'preparing' | 'sent' | 'done' | 'cancelled' | 'paymentRejected' | 'refunded';
+/**
+ * Per-status configuration. Lets consumer projects hide a built-in status from
+ * the admin status dropdown (`hidden`) and / or skip the customer status email
+ * when the order enters that status (`sendEmail: false`). Useful when the
+ * product is stationary (events, courses) and the shipping-oriented states
+ * (`preparing`, `sent`) don't apply.
+ *
+ * `hidden: true` blocks manual transitions from the admin UI, but webhook /
+ * carrier driven transitions still go through — those updates are
+ * engine-fundamental and the consumer can't always foresee what a provider
+ * will send.
+ * @public
+ */
+export interface OrderStatusConfig {
+    key: OrderStatus;
+    /** Hide from admin dropdown + block manual admin transition. Default `false`. */
+    hidden?: boolean;
+    /** Send status email when the order enters this status. Default `true`. */
+    sendEmail?: boolean;
+}
+/**
+ * Context passed to a {@link SubjectPlaceholderResolver}. Currently carries
+ * just the resolved order language; expand as new built-in placeholders need
+ * extra data.
+ * @public
+ */
+export interface EmailContext {
+    language: string;
+}
+/**
+ * Resolves one `{placeholder}` token in an email subject template to a string.
+ * Registered globally via {@link ShopConfig.emailSubjectPlaceholders} —
+ * consumer projects add their own (e.g. `{event_date}`) without touching the
+ * shop engine. Receives the full order row + a minimal context object.
+ * @public
+ */
+export type SubjectPlaceholderResolver = (order: Order, ctx: EmailContext) => string;
 export type I18nText = {
     [lang: string]: string;
 };
@@ -437,6 +474,56 @@ export interface ShopConfig {
         /** Throw on missing tokens / unknown CMS slugs. Default `false` (lenient → ""). */
         strict?: boolean;
     };
+    /**
+     * Per-status overrides — hide a status from the admin dropdown and / or
+     * skip the customer status email when the order enters that status. Useful
+     * for product types that don't ship physically (stationary events, digital
+     * services). Each entry targets one of the built-in {@link OrderStatus}
+     * keys; built-in status semantics are preserved, only UI visibility +
+     * email-send are toggled.
+     *
+     * `hidden: true` blocks admin manual transitions but webhook-driven
+     * transitions are unaffected.
+     * @public
+     */
+    orderStatuses?: OrderStatusConfig[];
+    /**
+     * Project-specific subject placeholder resolvers, merged on top of the
+     * built-in registry (`order_number`, `customer_name`, `customer_email`,
+     * `total_gross`, `currency`). Use to add tokens specific to the consumer's
+     * domain (e.g. `{event_date}` for course shops).
+     *
+     * Templates use `{key}` syntax in any subject string (CMS or hardcoded
+     * fallback); unknown keys are left untouched (lenient).
+     * @public
+     */
+    emailSubjectPlaceholders?: Record<string, SubjectPlaceholderResolver>;
+    /**
+     * Optional resolver for the email subject template per order status.
+     * Receives the resolved status + order language and returns a subject
+     * template string (with `{placeholder}` tokens), or `null`/`undefined`
+     * to fall back to the package default.
+     *
+     * The returned string is fed through {@link formatSubject} just like the
+     * default, so built-in and {@link emailSubjectPlaceholders} tokens both work.
+     *
+     * Use this to source subjects from a CMS singleton (the package itself stays
+     * agnostic about your CMS schema). Async — you can hit the DB here.
+     *
+     * @example
+     * ```ts
+     * resolveStatusSubject: async (status, { language }) => {
+     *   const entry = await resolveEntry({ collection: 'shopEmails' });
+     *   const key = STATUS_TO_CMS_KEY[status];
+     *   return entry?.statuses?.[key]?.subject;
+     * }
+     * ```
+     * @public
+     */
+    resolveStatusSubject?: (status: OrderStatus, ctx: {
+        order: Order;
+        language: string;
+    }) => Promise<string | null | undefined> | string | null | undefined;
     /**
      * Optional callback fired after an order transitions to `paid`.
      *

package/dist/updates/0.36.2/index.d.ts

@@ -0,0 +1,2 @@
+import type { CmsUpdate } from '../index.js';
+export declare const update: CmsUpdate;

package/dist/updates/0.36.2/index.js

@@ -0,0 +1,17 @@
+export const update = {
+    version: '0.36.2',
+    date: '2026-06-08',
+    description: 'Per-status overrides (`ShopConfig.orderStatuses`) + globalny rejestr subject placeholders (`formatSubject`/`ShopConfig.emailSubjectPlaceholders`) + nowy hook `ShopConfig.resolveStatusSubject` do czytania subject z CMS + Handlebars helper `{{{structured}}}` renderujący `StructuredContentDoc` (TipTap) jako email-safe HTML z automatycznym token replacement. Email context rozszerzony o billing fields (firma/NIP/adres/telefon). Dwa fixy bugów w resolverze CMS singletons w mailach. Zaprojektowane pod sklepy ze szkoleniami/wydarzeniami (stationary), gdzie statusy `preparing`/`sent` nie mają sensu. Wszystkie API generyczne, do reusu w innych consumer projects.',
+    features: [
+        '**`ShopConfig.orderStatuses?: OrderStatusConfig[]`** — opcjonalna lista per-status overrides. `hidden: true` chowa status z admin dropdownu (`shop-order-detail-page.svelte`) i blokuje manual transitions z admina rzucając nowy `HiddenStatusTransitionError` (kod `HIDDEN_STATUS_TRANSITION`). `sendEmail: false` powoduje, że `sendOrderStatusEmail` early-returnuje przy wejściu w ten status. Webhook / carrier-driven transitions BYPASSują guard — provider-driven update musi przejść bez względu na config (rola engine fundamentalna). Nowy parametr `updateOrderStatus(orderId, status, { source: "admin" })` rozróżnia kontekst; `source: "webhook" | "system"` (default) zawsze pomija check. Pure helpery: `assertManualStatusAllowed(status, orderStatuses)` (rzuca) i `shouldSendStatusEmail(status, orderStatuses)` (zwraca bool).',
+        '**`formatSubject` + `builtInSubjectPlaceholders`** (`$lib/shop/server/emailSubject.js`) — generyczna interpolacja `{key}` w subject mailach. Built-in: `{order_number}`, `{customer_name}`, `{customer_email}`, `{total_gross}` (formatted PLN currency), `{currency}`. Nowy `ShopConfig.emailSubjectPlaceholders?: Record<string, SubjectPlaceholderResolver>` — projektowe rozszerzenia (np. `{event_date}` dla szkoleń), mergowane na built-in (custom wins). `sendOrderStatusEmail` przepuszcza fallback subject (`STATUS_SUBJECTS[status][lang] · {order_number}`) przez `formatSubject` zanim wyśle. Nieznane placeholdery są lenient — zostają w stringu.',
+        '**`ShopConfig.resolveStatusSubject?(status, ctx) => string | null | undefined`** — async hook pozwalający consumerowi pobrać template subject z dowolnego źródła (typically CMS singleton). Wywoływany w `sendOrderStatusEmail` przed `formatSubject`, więc tokeny działają tak samo jak w defaultach. Pusta wartość / błąd → fallback do `STATUS_SUBJECTS`. Paczka pozostaje agnostyczna o CMS schemie consumera.',
+        '**Handlebars helper `{{{structured doc}}}`** (`emailTemplateRegistry.ts`) — renderuje `StructuredContentDoc` (output TipTap fielda `content`) jako inline HTML dla maili. Używa `structuredToHtml()` z core; zwraca `SafeString`. Po render — automatyczne **token replacement** przez `formatSubject` (built-in + `emailSubjectPlaceholders`) jeśli `order` jest w Handlebars context. Pozwala wpisać `{order_number}` w polu TipTap w CMSie i mieć je podmienione w wysłanym mailu. Pusty/undefined doc → "".',
+        '**Email context rozszerzony o billing fields** (`email.ts`): `order.customerCompanyName`, `customerNip`, `customerPhone`, `billingAddress` (`{street, postalCode, city, country?}`) + flagi `hasCompany` / `hasBillingAddress` dla wygodnych `{{#if}}` w templates. Pozwala renderować WooCommerce-style billing block bez custom JOIN.'
+    ],
+    fixes: [
+        '**`extractCmsSlugs` skanuje partials** — wcześniej AST tylko głównego templatu był parsowany, więc `cms.<slug>.*` referencje w partials (np. `cms.globalSettings.legalEntity` w `_partials/footer.pl.html`) były ignorowane → singleton nie był prefetchowany → context był pusty → fallbacki renderowane mimo wypełnionego CMSa. Teraz dodatkowo iteruje przez wszystkie zarejestrowane `Handlebars.partials` i merguje slugi.',
+        '**`resolveCmsContext` poprawnie spłaszcza entry** — wcześniej używał `entry?.data ?? {}`, ale `resolveEntry` zwraca obiekt spreadowany (`{ _id, _slug, _type, _publishedAt, _url, ...fields }`) bez pola `.data`. Efekt: każdy `cms.<slug>` w mailu był pustym obiektem. Teraz strip-uje meta keys (`_*`) i zwraca user fields. Mock w testach był niezgodny z prawdziwym API, dlatego bug przetrwał — naprawiony, dodany regression test dla nested path.'
+    ],
+    breakingChanges: []
+};

package/dist/updates/0.36.3/index.d.ts

@@ -0,0 +1,2 @@
+import type { CmsUpdate } from '../index.js';
+export declare const update: CmsUpdate;

package/dist/updates/0.36.3/index.js

@@ -0,0 +1,12 @@
+export const update = {
+    version: '0.36.3',
+    date: '2026-06-11',
+    description: 'Relacje opcjonalne — fix: niewybrana relacja (pole bez `required`) blokowała zapis wpisu („Invalid input: expected string, received null") albo wywalała populację przy pustym stringu. Teraz „brak wyboru" działa w obie strony — Zod akceptuje null/""/undefined, a populacja pomija puste wartości.',
+    features: [],
+    fixes: [
+        'Schemat Zod relacji niewymaganej (`generateZodSchemaFromField`) akceptuje teraz `null` obok `""`/`undefined` (`z.string().nullish().default("")`). Wcześniej `null` (znormalizowane dane lub wyczyszczenie pola w adminie) rzucał „Invalid input: expected string, received null" i blokował zapis wpisu. Bez nowej walidacji uuid — dowolny string nadal przechodzi, więc zero regresji dla istniejących danych.',
+        '`resolveRelationFields` pomija puste stringi przy zbieraniu ID do populacji (relacje pojedyncze i multiple). Pusty string nie trafia już do zapytania `WHERE id IN (\'\')`, które Postgres odrzucał jako nieprawidłowy uuid (`invalid input syntax for type uuid: ""`).',
+        'Efekt łączny: opcjonalna relacja bez wyboru działa w obie strony — zapis w adminie (Zod akceptuje null/"") oraz odczyt na froncie (populacja pomija puste). Dodany regression test dla akceptacji null/""/undefined.'
+    ],
+    breakingChanges: []
+};

package/dist/updates/index.js

@@ -68,6 +68,8 @@ import { update as update0341 } from './0.34.1/index.js';
 import { update as update0350 } from './0.35.0/index.js';
 import { update as update0360 } from './0.36.0/index.js';
 import { update as update0361 } from './0.36.1/index.js';
+import { update as update0362 } from './0.36.2/index.js';
+import { update as update0363 } from './0.36.3/index.js';
 export const updates = [
     update0065,
     update0066,
@@ -138,7 +140,9 @@ export const updates = [
     update0341,
     update0350,
     update0360,
-    update0361
+    update0361,
+    update0362,
+    update0363
 ];
 export const getUpdatesFrom = (fromVersion) => {
     const fromParts = fromVersion.split('.').map(Number);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "includio-cms",
-	"version": "0.36.1",
+	"version": "0.36.3",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",