@12-apps/notifications 4.7.1 → 4.9.0

package/dist/{types-CXLAG3UU.d.ts → types-BFmAY0P5.d.ts}

@@ -84,12 +84,44 @@ interface NotificationEvent<TPayload = unknown> {
  * generator never touches existing generators, the router, or any transport
  * (open/closed).
  */
+/**
+ * Who the content is being rendered FOR — the reader, at the moment the
+ * generator is asked.
+ *
+ * A notification is stored as rendered TEXT: title and body are columns, so
+ * the language is chosen once, when the row is written, and never again. That
+ * makes this the only honest place to ask. A generator is registered at BOOT —
+ * a host that resolved its words there would pin every future reader to
+ * whichever language the process happened to start in, invisibly, because a
+ * single-locale host cannot tell the difference.
+ *
+ * The tag is the RECIPIENT's, never the request's. The person who triggers a
+ * notification is routinely not the person who reads it: an invite is sent
+ * because an administrator acted and is read by the invitee. Reading
+ * `Accept-Language` here would be a bug that only ever surfaces as somebody
+ * being told things in a language they do not speak.
+ *
+ * Absent means "nobody said" — a host with one audience, or one that stores no
+ * per-user language, populates nothing and every generator answers with its
+ * own default exactly as it did before this existed.
+ */
+interface NotificationGenerateContext {
+    readonly locale?: string | null;
+}
 interface NotificationGenerator<TPayload = unknown> {
     /** The event key, dot-namespaced ("order.paid"). One generator per type. */
     type: string;
     /** The preference category the router gates this type's fan-out on. */
     category: NotificationCategory;
-    generate: (payload: TPayload) => NotificationContent;
+    /**
+     * Render this event's content for ONE recipient.
+     *
+     * `context` is OPTIONAL, and that is what keeps every generator written
+     * before it working: a one-parameter `generate` is assignable to this
+     * signature unchanged. A host that passes nothing is stating a fact — it has
+     * no language for this reader — rather than asserting a default.
+     */
+    generate: (payload: TPayload, context?: NotificationGenerateContext) => NotificationContent;
 }
 /**
  * The recipient as a transport sees them: resolved destinations only. Built by
@@ -100,6 +132,11 @@ interface NotificationGenerator<TPayload = unknown> {
 interface TransportRecipient {
     userId: string;
     email: string | null;
+    /**
+     * The recipient's own language, when the host's contact directory states
+     * one. Absent means "nobody said" — see {@link NotificationGenerateContext}.
+     */
+    locale?: string | null;
     /** Phone as the host stores it (transports normalize per provider rules). */
     phone: string | null;
     /** How many active browser push subscriptions the user holds. */
@@ -152,4 +189,4 @@ interface NotificationLogger {
     error(message: string, ...meta: unknown[]): void;
 }
 
-export { type DeliveryStatus as D, NOTIFICATION_CHANNELS as N, type TransportRecipient as T, type NotificationCategory as a, type NotificationChannel as b, type NotificationContent as c, type NotificationEvent as d, type NotificationGenerator as e, type NotificationLogger as f, type NotificationRecipient as g, type NotificationTaxonomy as h, type NotificationTransport as i, taxonomyOf as t };
+export { type DeliveryStatus as D, type NotificationGenerator as N, type TransportRecipient as T, NOTIFICATION_CHANNELS as a, type NotificationCategory as b, type NotificationChannel as c, type NotificationContent as d, type NotificationEvent as e, type NotificationGenerateContext as f, type NotificationLogger as g, type NotificationRecipient as h, type NotificationTaxonomy as i, type NotificationTransport as j, taxonomyOf as t };

package/dist/web-push/index.d.ts

@@ -1,5 +1,5 @@
-import { c as WebPushSender } from '../web-push-Cs14Wp9u.js';
-import '../types-CXLAG3UU.js';
+import { c as WebPushSender } from '../web-push-D-ysQd5h.js';
+import '../types-BFmAY0P5.js';
 
 /**
  * `@12-apps/notifications/web-push` — the VAPID sender, behind its own subpath.

package/dist/{web-push-Cs14Wp9u.d.ts → web-push-D-ysQd5h.d.ts}

@@ -1,4 +1,4 @@
-import { f as NotificationLogger, c as NotificationContent, i as NotificationTransport } from './types-CXLAG3UU.js';
+import { g as NotificationLogger, d as NotificationContent, j as NotificationTransport } from './types-BFmAY0P5.js';
 
 /**
  * The DRIVER port — the reason a host adds a vendor with a config entry and no

package/dist/{wire-6dzyfDE7.d.ts → wire-_coV3tJk.d.ts}

@@ -1,4 +1,4 @@
-import { a as NotificationCategory, b as NotificationChannel } from './types-CXLAG3UU.js';
+import { b as NotificationCategory, c as NotificationChannel } from './types-BFmAY0P5.js';
 
 /**
  * Every sentence this package can say to a USER, stated by the HOST.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/notifications",
-  "version": "4.7.1",
+  "version": "4.9.0",
   "type": "module",
   "sideEffects": false,
   "description": "Plug-and-play notification system (12-15): an always-on in-app inbox, per-user × per-category channel preferences, and email / SMS / WhatsApp / web-push transports behind vendor DRIVERS so a second provider is a config entry. Framework-free core (.), host-mounted backend surface (./server: inbox / preferences / push-subscription endpoints, the channel router with delivery records + retry sweep, the permission fan-out, duck-typed Prisma seam), Hono adapter (./hono), React surface (./react: bell + badge, inbox drawer, preferences screen), VAPID sender (./web-push) and the package-owned Prisma partial + migrations. Standardized adoption contract in ADOPTING.md.",
@@ -9,6 +9,26 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./email": {
+      "types": "./dist/email/index.d.ts",
+      "default": "./dist/email/index.js"
+    },
+    "./email/locales": {
+      "types": "./dist/email/locales.d.ts",
+      "default": "./dist/email/locales.js"
+    },
+    "./email/previews": {
+      "types": "./dist/email/previews/index.d.ts",
+      "default": "./dist/email/previews/index.js"
+    },
+    "./email/previews/hono": {
+      "types": "./dist/email/previews/hono.d.ts",
+      "default": "./dist/email/previews/hono.js"
+    },
+    "./email/previews/react": {
+      "types": "./dist/email/previews/react/index.d.ts",
+      "default": "./dist/email/previews/react/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"
@@ -51,7 +71,7 @@
     "prisma:sync:check": "node scripts/sync-notifications-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/ui": "^6.11.1"
+    "@12-apps/ui": "^6.14.0"
   },
   "peerDependencies": {
     "@12-apps/wiring": ">=1.3.0",
@@ -80,7 +100,7 @@
   "devDependencies": {
     "@12-apps/eslint-config": "^1.22.0",
     "@12-apps/typescript-config": "^1.21.0",
-    "@12-apps/wiring": "^1.14.0",
+    "@12-apps/wiring": "^1.16.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",

package/src/email/chrome.en-US.ts

@@ -0,0 +1,8 @@
+import type { EmailChromeCopy } from './template';
+
+/** US English — the twin that makes {@link PT_BR_EMAIL_CHROME} a choice. */
+export const EN_US_EMAIL_CHROME: EmailChromeCopy = {
+  fallbackHint: 'If the button above does not work, copy and paste this address into your browser:',
+  automated: 'This is an automated message. Please do not reply to this email.',
+  tagline: (brand) => `Sent by ${brand}.`,
+};

package/src/email/chrome.pt-BR.ts

@@ -0,0 +1,21 @@
+import type { EmailChromeCopy } from './template';
+
+/**
+ * Brazilian Portuguese, as a NAMED pack.
+ *
+ * A host passes this by name — `chrome: PT_BR_EMAIL_CHROME`, or
+ * `localeCopy(EMAIL_CHROME)` for a host whose readers do not share one
+ * language. It is never a default: a pack a host CHOOSES is a decision in a
+ * diff, and a pack a package applies silently is another product's voice in
+ * somebody's inbox.
+ *
+ * The tagline names the brand and stops. It is deliberately not a description
+ * of what the product does — that sentence is the host's, it belongs to a
+ * vocabulary this package cannot know, and a package that guessed one would be
+ * putting words in every adopter's footer.
+ */
+export const PT_BR_EMAIL_CHROME: EmailChromeCopy = {
+  fallbackHint: 'Se o botão acima não funcionar, copie e cole este endereço no seu navegador:',
+  automated: 'Esta é uma mensagem automática. Não responda a este e-mail.',
+  tagline: (brand) => `Enviado por ${brand}.`,
+};

package/src/email/index.ts

@@ -0,0 +1,43 @@
+/**
+ * `@12-apps/notifications/email` — ONE transactional-mail layout.
+ *
+ * ## Why it lives in this package
+ *
+ * This package already owned the delivery half: the `EmailDriver` port, the
+ * vendor table (`EMAIL_DRIVERS`) and, in `server/transports/email.ts`, a
+ * `formatEmail` that built a mail out of three `<p>` tags. That formatter is
+ * one of the three ad-hoc renderers this layout replaces — so shipping the
+ * layout anywhere else would have left the replacement in a package this one
+ * does not depend on, and the estate's own lesson is that adoption without
+ * deletion is the worst of both: two ways to render a mail, both maintained.
+ *
+ * Here, `formatEmail` renders THROUGH the layout the moment a host supplies a
+ * brand and a copy pack, and the ad-hoc path is what remains when it does not.
+ *
+ * Framework-free and dependency-free: safe in a browser, in a job, in a
+ * webhook — which is why it is its own subpath rather than part of `.`, whose
+ * consumers are the inbox and the preference matrix.
+ *
+ * The preview catalogue and its routes are `./email/previews`; the operator
+ * screen is `./email/previews/react`; the layout's own copy packs are
+ * `./email/locales`.
+ */
+export {
+  renderEmail,
+  renderEmailHtml,
+  safeHref,
+  type EmailAction,
+  type EmailChromeCopy,
+  type EmailDocument,
+  type EmailFact,
+  type RenderedEmail,
+} from './template';
+
+export { renderEmailText } from './text';
+
+export {
+  EMAIL_CONTENT_WIDTH,
+  EMAIL_FONT_STACK,
+  NEUTRAL_EMAIL_THEME,
+  type EmailTheme,
+} from './theme';

package/src/email/locales.ts

@@ -0,0 +1,29 @@
+import { EN_US_EMAIL_CHROME } from './chrome.en-US';
+import { PT_BR_EMAIL_CHROME } from './chrome.pt-BR';
+import type { EmailChromeCopy } from './template';
+
+/**
+ * The layout's own words, in every language this package ships.
+ *
+ * Its own subpath (`@12-apps/notifications/email/locales`) for the reason every
+ * copy-shipping package here uses one: keeping the packs off the layout entry
+ * is what lets that entry stay the framework-free mechanism a browser can
+ * import, and it is what makes "which language" a decision a host takes by
+ * name rather than one this package takes by default.
+ *
+ * Shaped as `Record<tag, pack>` rather than importing `@12-apps/i18n`'s
+ * `LocalePack`: a package must stay liftable into a repo that has never heard
+ * of that one, so the type is a local structural mirror. The two agree by tag,
+ * and `scripts/locale-coverage-gate.mjs` is what checks that they do.
+ *
+ * A host with ONE audience passes a pack by name. A host whose readers do not
+ * share a language passes `localeCopy(EMAIL_CHROME)` and each message is
+ * written in its own recipient's language — which is the whole reason
+ * `EmailDocument.chrome` is resolved per message rather than at a mount.
+ */
+export const EMAIL_CHROME: Readonly<Record<string, EmailChromeCopy>> = {
+  'pt-BR': PT_BR_EMAIL_CHROME,
+  'en-US': EN_US_EMAIL_CHROME,
+};
+
+export { EN_US_EMAIL_CHROME, PT_BR_EMAIL_CHROME };

package/src/email/previews/catalog.ts

@@ -0,0 +1,208 @@
+import type { RenderedEmail } from '../template';
+
+/**
+ * The preview catalogue: every message a host can send, as a navigable set.
+ *
+ * ## The problem it exists for
+ *
+ * There is normally no way to SEE a transactional mail without triggering the
+ * event that sends it — signing up with a throwaway address to look at the
+ * verification mail, settling an order to look at the receipt, exhausting a
+ * quota to look at that alert. So nobody looks, and a host that renders mail in
+ * three different ways does not find out.
+ *
+ * A layout nobody can see is one release from being three layouts again, which
+ * is why this ships in the same package as the layout rather than beside it.
+ *
+ * ## What is the package's and what is the host's
+ *
+ * The MECHANISM is here: group by owner, render one message for one reader,
+ * report what cannot be shown. WHICH messages exist is the host's, and it
+ * cannot be otherwise — a package cannot know that a host sends a
+ * "your quota is exhausted" notice, let alone what data that notice is
+ * rendered from.
+ *
+ * So a host declares SOURCES. Each names an owner and answers with its
+ * messages, and the catalogue is the union. That inverts the obvious design,
+ * where the package would hold a registry a host writes into: a source is
+ * asked, per request, so a source backed by a registry that fills at import
+ * time answers with whatever is registered NOW rather than with whatever had
+ * been registered when the mount was built.
+ *
+ * ## Why coverage is a first-class output
+ *
+ * A catalogue that quietly omits a message looks exactly like a product that
+ * does not send it. So a source may report what it knows it cannot show —
+ * a message with no sample data, or sample data for a message that no longer
+ * exists — and the surface returns that beside the list rather than swallowing
+ * it. A gap that is visible is a gap somebody closes.
+ */
+
+/** One previewable message. */
+export interface EmailPreviewMessage {
+  /**
+   * Stable id, and the path segment the console navigates by.
+   *
+   * The host chooses the spelling; the surface only requires it to be unique
+   * across every source. Ids that survive a rename are what make a link to one
+   * mail worth sending to a colleague.
+   */
+  readonly id: string;
+  /** The wire identity — an event type, a template key. Shown beside the subject. */
+  readonly key: string;
+  /** Which mail path this belongs to, for grouping inside one owner. */
+  readonly family: string;
+  /** Render it for one reader. MUST be pure — nothing may be sent. */
+  render(locale: string): RenderedEmail;
+}
+
+/** What a source knows it cannot show. Both directions are worth reporting. */
+export interface EmailPreviewCoverage {
+  /** Messages that exist but have no sample data, so no preview. */
+  readonly missing: readonly string[];
+  /** Sample data for a message nothing produces any more. */
+  readonly orphan: readonly string[];
+}
+
+/** One group of messages, owned by whichever code words them. */
+export interface EmailPreviewSource {
+  /**
+   * Who owns these messages — a package name, or the host's own module.
+   *
+   * This is the console's grouping, and it is the answer to "which parts of
+   * this system send mail", which is a question most hosts cannot otherwise
+   * answer at all.
+   */
+  readonly owner: string;
+  /** Called PER REQUEST — see the docblock above for why that matters. */
+  list(): readonly EmailPreviewMessage[];
+  /** Optional: what this source cannot show. Absent means "nothing missing". */
+  coverage?(): EmailPreviewCoverage;
+}
+
+/** One catalogue row: everything the sidebar needs, and no rendered bytes. */
+export interface EmailPreviewRow {
+  readonly id: string;
+  readonly key: string;
+  readonly family: string;
+  readonly owner: string;
+  /** The subject in the requested language, so the list reads as an inbox. */
+  readonly subject: string;
+}
+
+/** One rendered message: what the vendor would be handed, verbatim. */
+export interface EmailPreviewDetail extends EmailPreviewRow {
+  readonly locale: string;
+  readonly html: string;
+  readonly text: string;
+}
+
+export interface EmailPreviewIndex {
+  readonly locale: string;
+  readonly locales: readonly string[];
+  readonly items: readonly EmailPreviewRow[];
+  readonly coverage: EmailPreviewCoverage;
+}
+
+export interface EmailPreviewsConfig {
+  /** The host's sources, in the order the console should list their owners. */
+  readonly sources: readonly EmailPreviewSource[];
+  /**
+   * The languages a preview may be asked for.
+   *
+   * REQUIRED, and not derived from the shipped packs: a host's own messages may
+   * be written in languages this package has never heard of, and a preview that
+   * silently refused one of them would look exactly like a product with no
+   * translation.
+   */
+  readonly locales: readonly string[];
+  /** The language a preview opens in when the caller names none. */
+  readonly defaultLocale: string;
+}
+
+/** An id that appears in more than one source — the one thing that must not happen. */
+export class DuplicateEmailPreviewIdError extends Error {
+  constructor(id: string) {
+    super(`@12-apps/notifications: two e-mail preview messages share the id "${id}".`);
+    this.name = 'DuplicateEmailPreviewIdError';
+    Object.setPrototypeOf(this, DuplicateEmailPreviewIdError.prototype);
+  }
+}
+
+/** The catalogue, assembled from every source. */
+export interface ApiEmailPreviews {
+  /** Every message, with each subject rendered in `locale`. */
+  index(locale?: string): EmailPreviewIndex;
+  /** One rendered message, or `null` when no source owns that id. */
+  render(id: string, locale?: string): EmailPreviewDetail | null;
+  /** The union of every source's gaps. */
+  coverage(): EmailPreviewCoverage;
+  /** Is this a language the host said it writes in? */
+  supportsLocale(locale: string): boolean;
+}
+
+/** One source's messages, tagged with their owner. */
+interface OwnedMessage {
+  readonly owner: string;
+  readonly message: EmailPreviewMessage;
+}
+
+function collect(sources: readonly EmailPreviewSource[]): OwnedMessage[] {
+  const owned = sources.flatMap((source) =>
+    source.list().map((message) => ({ owner: source.owner, message })),
+  );
+  const seen = new Set<string>();
+  for (const { message } of owned) {
+    // A duplicate id makes one message unreachable and the other ambiguous —
+    // and silently, since the console would simply show whichever came first.
+    // Throwing here surfaces it on the request that would have hidden it.
+    if (seen.has(message.id)) throw new DuplicateEmailPreviewIdError(message.id);
+    seen.add(message.id);
+  }
+  return owned;
+}
+
+export function createEmailPreviews(config: EmailPreviewsConfig): ApiEmailPreviews {
+  const { sources, locales, defaultLocale } = config;
+  const localeOf = (locale?: string): string =>
+    locale && locales.includes(locale) ? locale : defaultLocale;
+
+  const rowOf = ({ owner, message }: OwnedMessage, locale: string): EmailPreviewRow => ({
+    id: message.id,
+    key: message.key,
+    family: message.family,
+    owner,
+    subject: message.render(locale).subject,
+  });
+
+  return {
+    index(locale) {
+      const tag = localeOf(locale);
+      return {
+        locale: tag,
+        locales,
+        items: collect(sources).map((owned) => rowOf(owned, tag)),
+        coverage: this.coverage(),
+      };
+    },
+    render(id, locale) {
+      const owned = collect(sources).find((entry) => entry.message.id === id);
+      if (!owned) return null;
+      const tag = localeOf(locale);
+      const message = owned.message.render(tag);
+      return { ...rowOf(owned, tag), locale: tag, html: message.html, text: message.text };
+    },
+    coverage() {
+      const missing: string[] = [];
+      const orphan: string[] = [];
+      for (const source of sources) {
+        const gap = source.coverage?.();
+        if (!gap) continue;
+        missing.push(...gap.missing);
+        orphan.push(...gap.orphan);
+      }
+      return { missing: missing.sort(), orphan: orphan.sort() };
+    },
+    supportsLocale: (locale) => locales.includes(locale),
+  };
+}

package/src/email/previews/hono.ts

@@ -0,0 +1,69 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+
+import { emailPreviewRoutes } from './routes';
+import type { EmailPreviewsConfig } from './catalog';
+
+/**
+ * `@12-apps/notifications/email/previews/hono` — the catalogue as a router.
+ *
+ * The framework-neutral descriptors in `./server` are the contract; this is the
+ * adapter for the framework we happen to use, behind its own subpath with
+ * `hono` as an OPTIONAL peer — a host on Express, or one that only wants the
+ * layout, never resolves it.
+ *
+ * A host writes:
+ *
+ *   const previews = emailPreviewsRouter({ sources, locales, defaultLocale });
+ *   app.use('/api/platform/email-previews/*', requirePlatformOperator);
+ *   app.route('/api/platform/email-previews', previews.router);
+ *
+ * ## The `use` line above is not decoration
+ *
+ * This surface publishes a host's whole transactional-mail inventory and the
+ * exact wording of its verification and reset mails. The routes declare no
+ * session of their own because a package cannot know who a host lets look — so
+ * the gate is the host's, it is REQUIRED, and it is written here rather than
+ * left to be inferred, because the failure is silent: an ungated mount answers
+ * every stranger and nothing about it looks wrong.
+ */
+
+export interface EmailPreviewsHonoConfig extends EmailPreviewsConfig {
+  /**
+   * Optional last-resort refusal, for a host that would rather state the gate
+   * once here than mount middleware around the router.
+   *
+   * Returning `false` answers 403 before any handler runs. Absent means the
+   * host has gated the mount itself — which is the ordinary case, and why this
+   * is not required: a package that demanded its own guard would be a second
+   * authorization system beside the one the host already runs.
+   */
+  readonly allow?: (c: Context) => Promise<boolean> | boolean;
+}
+
+/** The mounted router, plus the descriptors it was built from. */
+export interface EmailPreviewsRouter {
+  router: Hono;
+}
+
+export function emailPreviewsRouter(config: EmailPreviewsHonoConfig): EmailPreviewsRouter {
+  const router = new Hono();
+
+  for (const route of emailPreviewRoutes(config)) {
+    router.get(route.path, async (c) => {
+      if (config.allow && !(await config.allow(c))) {
+        return c.json({ error: 'Forbidden.' }, 403);
+      }
+      const response = await route.handle({
+        params: c.req.param() as Record<string, string | undefined>,
+        // `Object.fromEntries` over the parsed query rather than the raw string:
+        // a repeated `?locale=` is a caller error, and taking the last value is
+        // the same answer every framework here gives.
+        query: c.req.query() as Record<string, string | undefined>,
+      });
+      return c.json(response.body as Record<string, unknown>, response.status as 200 | 400 | 404);
+    });
+  }
+
+  return { router };
+}

package/src/email/previews/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `@12-apps/notifications/email/previews` — the preview catalogue and the
+ * routes over it.
+ *
+ * Behind its own subpath so a web bundle importing `./email` (the layout) or
+ * `./react` (the inbox) never resolves the server half.
+ */
+export {
+  createEmailPreviews,
+  DuplicateEmailPreviewIdError,
+  type ApiEmailPreviews,
+  type EmailPreviewCoverage,
+  type EmailPreviewDetail,
+  type EmailPreviewIndex,
+  type EmailPreviewMessage,
+  type EmailPreviewRow,
+  type EmailPreviewSource,
+  type EmailPreviewsConfig,
+} from './catalog';
+
+export {
+  emailPreviewRoutes,
+  type EmailPreviewRequest,
+  type EmailPreviewResponse,
+  type EmailPreviewRoute,
+} from './routes';

package/src/email/previews/react/copy.en-US.ts

@@ -0,0 +1,24 @@
+import type { EmailPreviewScreenCopy } from './copy';
+
+/** US English — the twin that makes {@link PT_BR_EMAIL_PREVIEW_COPY} a choice. */
+export const EN_US_EMAIL_PREVIEW_COPY: EmailPreviewScreenCopy = {
+  title: 'Email previews',
+  description: 'Every email this system sends, grouped by the package that owns it. Nothing is sent from here.',
+  searchLabel: 'Filter',
+  searchPlaceholder: 'subject, event or package',
+  noMatches: 'No message matches the filter.',
+  pickOne: 'Pick a message from the list to see its preview.',
+  tabHtml: 'HTML',
+  tabText: 'Text',
+  tabSource: 'Source',
+  widthDesktop: 'Desktop',
+  widthMobile: 'Mobile',
+  subjectLabel: 'Subject',
+  frameTitle: 'Email preview',
+  coverageTitle: 'Incomplete coverage',
+  missingSamples: (keys) => `No sample data, so no preview: ${keys}.`,
+  orphanSamples: (keys) => `A sample exists but nothing produces this message any more: ${keys}.`,
+  loading: 'Loading...',
+  loadError: 'The previews could not be loaded.',
+  retry: 'Try again',
+};

package/src/email/previews/react/copy.pt-BR.ts

@@ -0,0 +1,24 @@
+import type { EmailPreviewScreenCopy } from './copy';
+
+/** Brazilian Portuguese, as a NAMED pack — never a default. */
+export const PT_BR_EMAIL_PREVIEW_COPY: EmailPreviewScreenCopy = {
+  title: 'Prévia de e-mails',
+  description: 'Todos os e-mails que este sistema envia, agrupados por pacote. Nada é enviado a partir daqui.',
+  searchLabel: 'Filtrar',
+  searchPlaceholder: 'assunto, evento ou pacote',
+  noMatches: 'Nenhuma mensagem corresponde ao filtro.',
+  pickOne: 'Escolha uma mensagem na lista para ver a prévia.',
+  tabHtml: 'HTML',
+  tabText: 'Texto',
+  tabSource: 'Código',
+  widthDesktop: 'Computador',
+  widthMobile: 'Celular',
+  subjectLabel: 'Assunto',
+  frameTitle: 'Prévia do e-mail',
+  coverageTitle: 'Cobertura incompleta',
+  missingSamples: (keys) => `Sem dados de exemplo, então não há prévia: ${keys}.`,
+  orphanSamples: (keys) => `Há exemplo, mas nada mais produz esta mensagem: ${keys}.`,
+  loading: 'Carregando...',
+  loadError: 'Não foi possível carregar as prévias.',
+  retry: 'Tentar novamente',
+};

package/src/email/previews/react/copy.ts

@@ -0,0 +1,42 @@
+/**
+ * The SHAPE of the operator screen's words — no words.
+ *
+ * REQUIRED config with no default in any language, the copy-portability
+ * doctrine. `./copy.pt-BR` and `./copy.en-US` ship packs a host passes BY NAME.
+ *
+ * What is NOT here is anything from the mails themselves: a subject, a body and
+ * a button label all arrive from the server already rendered in whichever
+ * language the preview was asked for. That separation is the point of the
+ * language switch — the CHROME follows the operator, the MESSAGE follows its
+ * own recipient.
+ */
+export interface EmailPreviewScreenCopy {
+  readonly title: string;
+  readonly description: string;
+  /** The sidebar's filter field. */
+  readonly searchLabel: string;
+  readonly searchPlaceholder: string;
+  /** Nothing matched the filter. */
+  readonly noMatches: string;
+  /** No row is selected yet. */
+  readonly pickOne: string;
+  /** The three views of one message. */
+  readonly tabHtml: string;
+  readonly tabText: string;
+  readonly tabSource: string;
+  /** The two widths the HTML view renders at. */
+  readonly widthDesktop: string;
+  readonly widthMobile: string;
+  /** The subject line's label above the preview. */
+  readonly subjectLabel: string;
+  /** The sandboxed frame's title, for screen readers. */
+  readonly frameTitle: string;
+  /** The coverage strip, when the surface reports a gap. */
+  readonly coverageTitle: string;
+  readonly missingSamples: (keys: string) => string;
+  readonly orphanSamples: (keys: string) => string;
+  /** Loading and failure states. */
+  readonly loading: string;
+  readonly loadError: string;
+  readonly retry: string;
+}

package/src/email/previews/react/index.tsx

@@ -0,0 +1,14 @@
+/**
+ * `@12-apps/notifications/email/previews/react` — the operator screen over the
+ * preview catalogue.
+ *
+ * Its own subpath rather than a member of `./react`, which is the INBOX: the
+ * bell and the preference matrix ship to every signed-in user, and this screen
+ * is a platform-staff diagnostic. A host that mounts one has no reason to
+ * resolve the other.
+ */
+export { createEmailPreviewScreen, type EmailPreviewScreenConfig } from './preview-screen';
+export { type EmailPreviewScreenCopy } from './copy';
+export { EN_US_EMAIL_PREVIEW_COPY } from './copy.en-US';
+export { PT_BR_EMAIL_PREVIEW_COPY } from './copy.pt-BR';
+export { type PreviewTab, type PreviewWidth } from './message-view';