@ultimat3/mail 5.0.1 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "5.0.1",
+  "version": "7.0.0",
   "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "5.0.1",
-    "@ultimat3/i18n": "5.0.1",
-    "@ultimat3/jobs": "5.0.1",
-    "@ultimat3/schema": "5.0.1",
-    "@ultimat3/time": "5.0.1"
+    "@ultimat3/core": "7.0.0",
+    "@ultimat3/i18n": "7.0.0",
+    "@ultimat3/jobs": "7.0.0",
+    "@ultimat3/schema": "7.0.0",
+    "@ultimat3/time": "7.0.0"
   }
 }

package/src/catalog.ts

@@ -9,7 +9,7 @@ import {
   type Locale,
   loadCatalog,
   type NestedCatalog,
-  registerCatalog,
+  registerBaseCatalog,
 } from '@ultimat3/i18n';
 
 export const MAIL_CATALOG_SOURCE: NestedCatalog = {
@@ -85,24 +85,18 @@ export const MAIL_CATALOG: Catalog = loadCatalog(MAIL_CATALOG_SOURCE);
 /** The one locale these strings are written in. */
 export const MAIL_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
 
-/**
- * Register the mail templates' own strings under the ONE locale they are written in.
- *
- * **No locale parameter, and that is the fix**: this catalog is English, so `registerMailCatalog('es')`
- * seated English subjects and headings under `es` where `isMiss` then read FALSE — a fallback locale
- * chain wearing registration as a disguise, the same defect `registerFrameworkCatalog` carried until
- * it lost its own parameter. A locale argument is now a compile error rather than a silent one.
- *
- * **Call it once, at boot.** This is NOT idempotent, and the comment here claimed it was:
- * `registerCatalog` merges the existing entry first and its argument second, so a second call after
- * an app has overridden `mail.*` keys puts the English strings back on top of exactly the keys that
- * app cared enough to translate. Guarding on "has this locale a catalog" — the shape
- * `registerFrameworkCatalog` uses — cannot work here, because the framework catalog has already
- * claimed this locale by the time mail registers; a guard by CONTENT needs an i18n primitive that
- * does not exist, and remembering the call in a module flag goes stale the moment
- * `resetCatalogs()` runs (`packages/testing/src/registry-snapshot.ts`), which would silently stop
- * registering altogether. Stating the limit beats inventing a guard that fails quietly.
- */
-export function registerMailCatalog(): void {
-  registerCatalog(MAIL_CATALOG_LOCALE, MAIL_CATALOG);
-}
+// At module scope, and that is the whole point: importing `@ultimat3/mail` is what installs these
+// strings, so no app and no boot can forget them. `registerMailCatalog()` was the alternative and
+// it had **zero** production callers — only this package's own tests — so every `mail.*` string in
+// every running Ultimate app rendered as a loud miss, which is issue #249 one package over.
+//
+// Under an app's catalog, never over it: `registerBaseCatalog` merges the base FIRST and whatever
+// `registerCatalog` seated second, so an app that translated `mail.footer.unsubscribe` keeps it
+// through every later install. That is the "guard by CONTENT" this file said needed an i18n
+// primitive that did not exist — it exists now, and it is idempotent by construction rather than
+// by a module flag `resetCatalogs()` would go stale against.
+//
+// Under the ONE locale these strings are written in. Seating English under `es` made `isMiss` read
+// FALSE for a subject nobody had translated — a fallback locale chain wearing registration as a
+// disguise. A non-`en` app translates the `mail.*` keys it renders into its own catalog.
+registerBaseCatalog(MAIL_CATALOG_LOCALE, MAIL_CATALOG);

package/src/index.ts

@@ -7,12 +7,7 @@ export { t } from '@ultimat3/schema';
 export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
 export { blocks } from './blocks';
 
-export {
-  MAIL_CATALOG,
-  MAIL_CATALOG_LOCALE,
-  MAIL_CATALOG_SOURCE,
-  registerMailCatalog,
-} from './catalog';
+export { MAIL_CATALOG, MAIL_CATALOG_LOCALE, MAIL_CATALOG_SOURCE } from './catalog';
 export type {
   MailDriver,
   MailMessage,

package/src/layout.ts

@@ -21,21 +21,20 @@ export type MailToken =
   | 'calloutDangerBg'
   | 'calloutDangerText';
 
-export const MAIL_TOKENS: Readonly<Record<MailToken, Readonly<Record<ColorScheme, string>>>> =
-  Object.freeze({
-    pageBg: { light: '#f4f5f7', dark: '#0b0d10' },
-    surfaceBg: { light: '#ffffff', dark: '#14181d' },
-    textPrimary: { light: '#16191d', dark: '#e7eaee' },
-    textMuted: { light: '#5c6470', dark: '#9aa4b1' },
-    borderSubtle: { light: '#e2e6ea', dark: '#262c33' },
-    accentBg: { light: '#2f6df6', dark: '#4f86ff' },
-    accentText: { light: '#ffffff', dark: '#0b0d10' },
-    linkText: { light: '#2f6df6', dark: '#7aa7ff' },
-    calloutInfoBg: { light: '#eef3ff', dark: '#141c2c' },
-    calloutInfoText: { light: '#1f3f8f', dark: '#b9cdfb' },
-    calloutDangerBg: { light: '#fdeceb', dark: '#2a1416' },
-    calloutDangerText: { light: '#8c2118', dark: '#f5b3ad' },
-  });
+export const MAIL_TOKENS = Object.freeze<Record<MailToken, Readonly<Record<ColorScheme, string>>>>({
+  pageBg: { light: '#f4f5f7', dark: '#0b0d10' },
+  surfaceBg: { light: '#ffffff', dark: '#14181d' },
+  textPrimary: { light: '#16191d', dark: '#e7eaee' },
+  textMuted: { light: '#5c6470', dark: '#9aa4b1' },
+  borderSubtle: { light: '#e2e6ea', dark: '#262c33' },
+  accentBg: { light: '#2f6df6', dark: '#4f86ff' },
+  accentText: { light: '#ffffff', dark: '#0b0d10' },
+  linkText: { light: '#2f6df6', dark: '#7aa7ff' },
+  calloutInfoBg: { light: '#eef3ff', dark: '#141c2c' },
+  calloutInfoText: { light: '#1f3f8f', dark: '#b9cdfb' },
+  calloutDangerBg: { light: '#fdeceb', dark: '#2a1416' },
+  calloutDangerText: { light: '#8c2118', dark: '#f5b3ad' },
+});
 
 /** Resolve a token to a hex value. The only function in the package that returns a colour. */
 export function token(name: MailToken, scheme: ColorScheme = 'light'): string {

package/src/render.ts

@@ -5,6 +5,13 @@
 
 import { directionOf, type TranslateVars, type Translator, translatorFor } from '@ultimat3/i18n';
 import type { CalloutTone, MailBlock, MailTemplate } from './blocks';
+// The renderer depends on the strings it renders. This is the only module that resolves a `mail.*`
+// key, and `catalog.ts` installs them at ITS module scope — so importing it here is what makes
+// "a rendered mail has words in it" structural rather than something a caller has to arrange.
+// Without this edge, only the package ENTRY reached the catalog: every deep import of `render.ts`
+// produced `⟦mail.welcome.subject⟧`, and the tests that would have noticed were the ones calling
+// `registerMailCatalog()` themselves — the exact shape of issue #249.
+import './catalog';
 import { layoutUnknown, textMissing } from './errors';
 import { escapeHtml, safeUrl, styleAttr } from './html';
 import { layoutFor, registeredLayouts, token } from './layout';