@plutocms/pluto 0.12.0 → 0.14.0

package/modules/pluto-i18n/locale-files.ts

@@ -0,0 +1,187 @@
+// Pure helpers for the pluto-i18n module. They do not import `nuxt/kit`, so
+// the unit tests can call them directly.
+import { join } from 'node:path'
+
+// One source for the matcher: the runtime plugin uses it too.
+export { matchLocale } from '../../app/composables/internal/i18n-core'
+
+/** Where a layer (or the app) keeps its locale files, under its root dir. */
+export const LOCALE_DIR = 'i18n/locales'
+
+/** A valid locale code: `en`, `pt-BR`. A language, and an optional region. */
+const LOCALE_CODE = /^[a-z]{2,3}(?:-[A-Z]{2})?$/
+
+export function isLocaleCode(value: string): boolean {
+  return LOCALE_CODE.test(value)
+}
+
+function toPosix(path: string): string {
+  return path.replaceAll('\\', '/')
+}
+
+/**
+ * Returns the locale files of every layer, grouped by locale code. Each list
+ * has the base layer first and the app last, so a later file overrides an
+ * earlier one. Nuxt lists the layers top first (the app, then each layer it
+ * extends), so the list is reversed. `listDir` returns the file names in a
+ * directory, or an empty list if the directory is missing. A file whose name
+ * is not `<code>.json` with a valid code is ignored.
+ */
+export function findLayerLocaleFiles(
+  layerRoots: string[],
+  listDir: (dir: string) => string[]
+): Record<string, string[]> {
+  const files: Record<string, string[]> = {}
+  for (const root of [...layerRoots].reverse()) {
+    const dir = join(root, LOCALE_DIR)
+    for (const name of listDir(dir).toSorted()) {
+      if (!name.endsWith('.json')) {
+        continue
+      }
+      const code = name.slice(0, -'.json'.length)
+      if (isLocaleCode(code)) {
+        (files[code] ??= []).push(toPosix(join(dir, name)))
+      }
+    }
+  }
+  return files
+}
+
+/**
+ * Returns the Nuxt UI locale file name (without extension) for a locale
+ * code. `available` lists the file names in Nuxt UI's locale directory, such
+ * as `en` and `pt_br`. The order: the full code (`pt-BR` gives `pt_br`), the
+ * base language (`pt`), then `en`.
+ */
+export function resolveNuxtUiLocaleFile(code: string, available: string[]): string {
+  const full = code.toLowerCase().replaceAll('-', '_')
+  if (available.includes(full)) {
+    return full
+  }
+  const base = full.split('_')[0]!
+  if (available.includes(base)) {
+    return base
+  }
+  return 'en'
+}
+
+export interface I18nTemplateInput {
+  /** Locale files by code, from `findLayerLocaleFiles`. */
+  files: Record<string, string[]>
+  defaultLocale: string
+  /** Absolute directory of Nuxt UI's locale files. */
+  uiLocaleDir: string
+  /** The file names in `uiLocaleDir`, without extension. */
+  uiLocaleFiles: string[]
+}
+
+/** Renders the source of `#build/pluto-i18n.mjs`. */
+export function renderI18nTemplate(input: I18nTemplateInput): string {
+  const codes = Object.keys(input.files).toSorted()
+  const messageLoaders = codes.map((code) => {
+    const imports = input.files[code]!.map((file) => `import(${JSON.stringify(file)})`).join(', ')
+    return `  ${JSON.stringify(code)}: async () => merge(...(await Promise.all([${imports}])).map((m) => m.default ?? m)),`
+  })
+  const uiLocaleLoaders = codes.map((code) => {
+    const file = resolveNuxtUiLocaleFile(code, input.uiLocaleFiles)
+    const path = `${toPosix(input.uiLocaleDir).replace(/\/$/, '')}/${file}.js`
+    return `  ${JSON.stringify(code)}: () => import(${JSON.stringify(path)}).then((m) => m.default),`
+  })
+  return [
+    '// Generated by @plutocms/pluto (modules/pluto-i18n). Do not edit.',
+    '// Each layer\'s i18n/locales/<code>.json, base layer first, the app last.',
+    `export const localeCodes = ${JSON.stringify(codes)}`,
+    `export const defaultLocale = ${JSON.stringify(input.defaultLocale)}`,
+    '',
+    'function isTree(value) {',
+    '  return typeof value === \'object\' && value !== null',
+    '}',
+    '',
+    'function merge(...trees) {',
+    '  const result = {}',
+    '  for (const tree of trees) {',
+    '    for (const [key, value] of Object.entries(tree)) {',
+    '      result[key] = isTree(value) ? merge(isTree(result[key]) ? result[key] : {}, value) : value',
+    '    }',
+    '  }',
+    '  return result',
+    '}',
+    '',
+    'export const messageLoaders = {',
+    ...messageLoaders,
+    '}',
+    '',
+    'export const uiLocaleLoaders = {',
+    ...uiLocaleLoaders,
+    '}',
+    '',
+  ].join('\n')
+}
+
+/** Renders the type declaration of `#build/pluto-i18n.mjs`. */
+export function renderI18nTypes(): string {
+  return [
+    '// Generated by @plutocms/pluto (modules/pluto-i18n). Do not edit.',
+    'export declare const localeCodes: string[]',
+    'export declare const defaultLocale: string',
+    'export declare const messageLoaders: Record<string, () => Promise<Record<string, unknown>>>',
+    'export declare const uiLocaleLoaders: Record<string, () => Promise<any>>',
+    '',
+  ].join('\n')
+}
+
+export interface PlutoI18nOptions {
+  /** The fallback locale, and the last choice of every resolve order. Default `en`. */
+  defaultLocale?: string
+  /** Locales the admin offers. Default: every discovered locale. */
+  adminLocales?: string[]
+  /** Locales the public site can use. Default: every discovered locale. */
+  siteLocales?: string[]
+  /** The public site's locale. Default: `defaultLocale`. */
+  siteLocale?: string
+}
+
+export interface ResolvedI18nOptions {
+  defaultLocale: string
+  adminLocales: string[]
+  siteLocales: string[]
+  siteLocale: string
+  warnings: string[]
+}
+
+/**
+ * Fills the module options from the discovered locale codes. A locale an
+ * option names but no file provides is dropped, with a warning.
+ */
+export function resolveI18nOptions(options: PlutoI18nOptions, discovered: string[]): ResolvedI18nOptions {
+  const warnings: string[] = []
+  const known = new Set(discovered)
+
+  function pick(name: string, wanted: string[] | undefined): string[] {
+    if (!wanted) {
+      return [...discovered]
+    }
+    const kept = wanted.filter((code) => known.has(code))
+    for (const code of wanted.filter((code) => !known.has(code))) {
+      warnings.push(`plutoI18n.${name} lists "${code}", but no layer has i18n/locales/${code}.json. Dropped.`)
+    }
+    return kept
+  }
+
+  let defaultLocale = options.defaultLocale ?? 'en'
+  if (!known.has(defaultLocale)) {
+    warnings.push(`plutoI18n.defaultLocale "${defaultLocale}" has no locale file. Using "en".`)
+    defaultLocale = 'en'
+  }
+
+  const adminLocales = pick('adminLocales', options.adminLocales)
+  const siteLocales = pick('siteLocales', options.siteLocales)
+
+  let siteLocale = options.siteLocale ?? defaultLocale
+  if (!siteLocales.includes(siteLocale)) {
+    warnings.push(`plutoI18n.siteLocale "${siteLocale}" is not in siteLocales. Using "${defaultLocale}".`)
+    siteLocale = defaultLocale
+  }
+
+  return { defaultLocale, adminLocales, siteLocales, siteLocale, warnings }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/pluto",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "The layerable CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",

package/scripts/generate-admin-theme.cjs

@@ -13,7 +13,12 @@ const scales = Object.entries(roles).map(([role, hue]) => `  /* ${role}: ${hue}
 const semantic = (shade) => Object.keys(roles).filter((r) => r !== 'neutral').map((r) => `  --ui-${r}: var(--ui-color-${r}-${shade});`).join('\n')
 const n = (s) => `var(--ui-color-neutral-${s})`
 const neutralLight = { 'text-dimmed': n(400), 'text-muted': n(500), 'text-toned': n(600), 'text': n(700), 'text-highlighted': n(900), 'text-inverted': '#fff', 'bg': '#fff', 'bg-muted': n(50), 'bg-elevated': n(100), 'bg-accented': n(200), 'bg-inverted': n(900), 'border': n(200), 'border-muted': n(200), 'border-accented': n(300), 'border-inverted': n(900) }
-const neutralDark = { 'text-dimmed': n(500), 'text-muted': n(400), 'text-toned': n(300), 'text': n(200), 'text-highlighted': '#fff', 'text-inverted': n(900), 'bg': n(900), 'bg-muted': n(800), 'bg-elevated': n(800), 'bg-accented': n(700), 'bg-inverted': '#fff', 'border': n(800), 'border-muted': n(700), 'border-accented': n(700), 'border-inverted': '#fff' }
+// Dark cards sit one step above the zinc-900 canvas: between zinc-900 and
+// zinc-800. The chart palette passes the dataviz checks on this surface.
+const CARD_DARK = 'oklch(24% 0.006 286)'
+// The dark sidebar sits between the zinc-950 navbar and the zinc-900 canvas.
+const SIDEBAR_DARK = 'oklch(17.5% 0.0055 286)'
+const neutralDark = { 'text-dimmed': n(500), 'text-muted': n(400), 'text-toned': n(300), 'text': n(200), 'text-highlighted': '#fff', 'text-inverted': n(900), 'bg': CARD_DARK, 'bg-muted': n(800), 'bg-elevated': n(800), 'bg-accented': n(700), 'bg-inverted': '#fff', 'border': n(800), 'border-muted': n(700), 'border-accented': n(700), 'border-inverted': '#fff' }
 const tokens = (o) => Object.entries(o).map(([k, val]) => `  --ui-${k}: ${val};`).join('\n')
 // Validated with the dataviz palette checks on white (light) and zinc-900
 // (dark). Re-run the checks before you change a slot.
@@ -32,6 +37,10 @@ const css = `/*
  * - \`[data-pluto-admin-scope]\`: for admin chrome that also shows on the
  *   public site, such as the admin navbar for a logged-in admin.
  *
+ * \`[data-pluto-admin-dark]\` takes the dark tokens in both color modes. The
+ * admin navbar is near black in light mode too, so its text and buttons need
+ * the dark values.
+ *
  * Every value is a literal. The consumer app styles its public site through
  * its own app.config colors and @theme. Both reach the admin unless the admin
  * pins its own values: app.config colors set Nuxt UI's --ui-color-* scales on
@@ -59,27 +68,32 @@ ${tokens(neutralLight)}
 
 ${chart(chartLight)}
 
-  /* Surfaces */
+  /* Surfaces. The navbar is near black in both modes. */
   --pluto-admin-canvas: #fff;
   --pluto-admin-sidebar: ${v('zinc-50')};
-  --pluto-admin-navbar: #fff;
+  --pluto-admin-navbar: ${v('zinc-950')};
 
   --ui-radius: 0.375rem;
   --font-sans: "Outfit", ui-sans-serif, system-ui, sans-serif;
 }
 
 :root[data-pluto-admin].dark,
-.dark [data-pluto-admin-scope] {
+.dark [data-pluto-admin-scope],
+[data-pluto-admin-dark] {
 ${semantic(400)}
 
 ${tokens(neutralDark)}
 
 ${chart(chartDark)}
 
-  /* Cards (--ui-bg, zinc-900) sit one step above the canvas (zinc-950). */
-  --pluto-admin-canvas: ${v('zinc-950')};
-  --pluto-admin-sidebar: ${v('zinc-950')};
+  /*
+   * Four steps, darkest at the top: a near-black navbar, a darker sidebar,
+   * a dim dark gray canvas (not pitch black), and cards (--ui-bg) one step
+   * above the canvas.
+   */
   --pluto-admin-navbar: ${v('zinc-950')};
+  --pluto-admin-sidebar: ${SIDEBAR_DARK};
+  --pluto-admin-canvas: ${v('zinc-900')};
 }
 
 :root[data-pluto-admin] body {

package/server/utils/pluto-content-handlers.ts

@@ -1,7 +1,7 @@
 import type { H3Event } from 'h3'
-import { createError } from 'h3'
 import { validateContentPayload } from '../../shared/utils/content-validate'
 import { getContentAdapter, getContentType } from './pluto-content'
+import { createPlutoError } from './pluto-error'
 
 /**
  * The real logic behind the generic content routes, kept in plain exported
@@ -14,7 +14,12 @@ export function requireContentType(name: string): PlutoContentType {
   const type = getContentType(name)
 
   if (!type) {
-    throw createError({ statusCode: 404, statusMessage: `Content type "${name}" not found.` })
+    throw createPlutoError({
+      statusCode: 404,
+      message: `Content type "${name}" not found.`,
+      key: 'pluto.errors.contentTypeNotFound',
+      params: { name },
+    })
   }
 
   return type
@@ -24,7 +29,11 @@ export function requireContentAdapter(): PlutoContentAdapter {
   const adapter = getContentAdapter()
 
   if (!adapter) {
-    throw createError({ statusCode: 500, statusMessage: 'No content adapter is registered.' })
+    throw createPlutoError({
+      statusCode: 500,
+      message: 'No content adapter is registered.',
+      key: 'pluto.errors.noContentAdapter',
+    })
   }
 
   return adapter
@@ -97,7 +106,7 @@ export async function getContentItem(ctx: PlutoContentContext, idOrSlug: string
   const item = await requireContentAdapter().get(ctx, idOrSlug)
 
   if (!item) {
-    throw createError({ statusCode: 404, statusMessage: 'Not found.' })
+    throw createPlutoError({ statusCode: 404, message: 'Not found.', key: 'pluto.errors.notFound' })
   }
 
   return item
@@ -105,7 +114,11 @@ export async function getContentItem(ctx: PlutoContentContext, idOrSlug: string
 
 function requirePlainObjectBody(body: unknown): Record<string, unknown> {
   if (typeof body !== 'object' || body === null || Array.isArray(body)) {
-    throw createError({ statusCode: 400, statusMessage: 'Request body must be a JSON object.' })
+    throw createPlutoError({
+      statusCode: 400,
+      message: 'Request body must be a JSON object.',
+      key: 'pluto.errors.bodyNotObject',
+    })
   }
 
   return body as Record<string, unknown>
@@ -122,7 +135,12 @@ export async function createContentItem(ctx: PlutoContentContext, body: unknown)
 
   const errors = validateContentPayload(ctx.type, payload)
   if (errors.length > 0) {
-    throw createError({ statusCode: 400, statusMessage: 'Validation failed.', data: { errors } })
+    throw createPlutoError({
+      statusCode: 400,
+      message: 'Validation failed.',
+      key: 'pluto.errors.validationFailed',
+      data: { errors },
+    })
   }
 
   await authorizeContentOperation(ctx.event, ctx.type.capabilities?.write)
@@ -151,7 +169,12 @@ export async function updateContentItem(
 
   const errors = validateContentPayload(ctx.type, payload, { partial: true })
   if (errors.length > 0) {
-    throw createError({ statusCode: 400, statusMessage: 'Validation failed.', data: { errors } })
+    throw createPlutoError({
+      statusCode: 400,
+      message: 'Validation failed.',
+      key: 'pluto.errors.validationFailed',
+      data: { errors },
+    })
   }
 
   await authorizeContentOperation(ctx.event, ctx.type.capabilities?.write)

package/server/utils/pluto-error.ts

@@ -0,0 +1,27 @@
+import type { H3Error } from 'h3'
+import { createError } from 'h3'
+
+export interface PlutoErrorOptions {
+  statusCode: number
+  /** English text. It becomes the `statusMessage`, so the server always speaks English. */
+  message: string
+  /** Translation key of the same message, for the admin UI. Example: `pluto.errors.notFound`. */
+  key: string
+  /** Values for the translated message. */
+  params?: Record<string, unknown>
+  /** Extra response data, for example `{ errors }`. It sits next to `i18n`. */
+  data?: Record<string, unknown>
+}
+
+/**
+ * Creates an H3 error that the admin can show in its own language. The
+ * `statusMessage` stays English. The translation key and its values go in
+ * `data.i18n`, and the client reads them with `usePlutoErrorText()`.
+ */
+export function createPlutoError(options: PlutoErrorOptions): H3Error {
+  return createError({
+    statusCode: options.statusCode,
+    statusMessage: options.message,
+    data: { ...options.data, i18n: { key: options.key, params: options.params } },
+  })
+}

package/shared/types/i18n.d.ts

@@ -0,0 +1,10 @@
+import type { PlutoI18nRuntimeConfig } from './i18n'
+
+// The `pluto-i18n` module fills this key. See modules/pluto-i18n/index.ts.
+declare module '@nuxt/schema' {
+  interface PublicRuntimeConfig {
+    plutoI18n: PlutoI18nRuntimeConfig
+  }
+}
+
+export {}

package/shared/types/i18n.ts

@@ -0,0 +1,14 @@
+/**
+ * The options of the `pluto-i18n` module, as the module resolves them and
+ * exposes them in `runtimeConfig.public.plutoI18n`.
+ */
+export interface PlutoI18nRuntimeConfig {
+  /** The fallback locale. */
+  defaultLocale: string
+  /** Locales the admin offers. */
+  adminLocales: string[]
+  /** Locales the public site can use. */
+  siteLocales: string[]
+  /** The public site's locale before a visitor picks one. */
+  siteLocale: string
+}

package/shared/types/registry.ts

@@ -61,6 +61,17 @@ export interface PlutoSettingsDriver extends PlutoEntry {
   save: (patch: Record<string, string>) => Promise<void>
 }
 
+/**
+ * Loads and saves the current user's admin language. One backend layer
+ * registers this, the same way one layer registers a PlutoSettingsDriver.
+ * `load` returns the stored locale code, or null when the user chose
+ * Automatic (browser language). `save` stores a code, or null for Automatic.
+ */
+export interface PlutoLocaleDriver extends PlutoEntry {
+  load: () => Promise<string | null>
+  save: (locale: string | null) => Promise<void>
+}
+
 /**
  * A capability a layer defines. `key` is the real capability string, for
  * example 'posts:publish'. It is kept separate from `id` on purpose: the
@@ -151,6 +162,7 @@ export interface PlutoExtension {
   dashboardWidgets?: PlutoDashboardWidget[]
   settingsPanels?: PlutoSettingsPanel[]
   settingsDriver?: PlutoSettingsDriver
+  localeDriver?: PlutoLocaleDriver
   capabilities?: PlutoCapability[]
   permissionsDriver?: PlutoPermissionsDriver
   contentTypes?: PlutoContentTypeEntry[]
@@ -178,6 +190,7 @@ export interface PlutoRegistry {
   pages: PlutoRegistryBucket<PlutoAdminPage>
   settingsPanels: PlutoRegistryBucket<PlutoSettingsPanel>
   settingsDrivers: PlutoRegistryBucket<PlutoSettingsDriver>
+  localeDrivers: PlutoRegistryBucket<PlutoLocaleDriver>
   dashboardWidgets: PlutoRegistryBucket<PlutoDashboardWidget>
   capabilities: PlutoRegistryBucket<PlutoCapability>
   permissionsDrivers: PlutoRegistryBucket<PlutoPermissionsDriver>

package/shared/utils/content-validate.ts

@@ -1,8 +1,16 @@
 import type { PlutoContentType } from '../types/content'
 
+/** Why a field failed. Each code has a `pluto.validation.<code>` message key. */
+export type ContentValidationCode = 'required' | 'number' | 'integer' | 'min' | 'max' | 'boolean' | 'option' | 'maxLength'
+
 export interface ContentValidationError {
   field: string
+  /** English text. It never changes with the admin language. */
   message: string
+  /** Machine-readable reason. The admin form uses it to show a translated message. */
+  code?: ContentValidationCode
+  /** Values for the translated message, for example `{ min: 1 }`. */
+  params?: Record<string, unknown>
 }
 
 /**
@@ -32,7 +40,7 @@ export function validateContentPayload(
       const skipBecausePartial = options?.partial === true && !present
       const empty = value === undefined || value === null || value === ''
       if (!skipBecausePartial && empty) {
-        errors.push({ field: field.name, message: `"${field.label}" is required.` })
+        errors.push({ field: field.name, message: `"${field.label}" is required.`, code: 'required' })
         continue
       }
     }
@@ -46,31 +54,31 @@ export function validateContentPayload(
       case 'number': {
         const numeric = typeof value === 'number' ? value : Number(value)
         if ((typeof value !== 'number' && typeof value !== 'string') || Number.isNaN(numeric)) {
-          errors.push({ field: field.name, message: `"${field.label}" must be a number.` })
+          errors.push({ field: field.name, message: `"${field.label}" must be a number.`, code: 'number' })
           break
         }
         if (field.integer && !Number.isInteger(numeric)) {
-          errors.push({ field: field.name, message: `"${field.label}" must be an integer.` })
+          errors.push({ field: field.name, message: `"${field.label}" must be an integer.`, code: 'integer' })
         }
         if (field.min !== undefined && numeric < field.min) {
-          errors.push({ field: field.name, message: `"${field.label}" must be at least ${field.min}.` })
+          errors.push({ field: field.name, message: `"${field.label}" must be at least ${field.min}.`, code: 'min', params: { min: field.min } })
         }
         if (field.max !== undefined && numeric > field.max) {
-          errors.push({ field: field.name, message: `"${field.label}" must be at most ${field.max}.` })
+          errors.push({ field: field.name, message: `"${field.label}" must be at most ${field.max}.`, code: 'max', params: { max: field.max } })
         }
         break
       }
 
       case 'boolean': {
         if (typeof value !== 'boolean') {
-          errors.push({ field: field.name, message: `"${field.label}" must be a boolean.` })
+          errors.push({ field: field.name, message: `"${field.label}" must be a boolean.`, code: 'boolean' })
         }
         break
       }
 
       case 'select': {
         if (!field.options.some((option) => option.value === value)) {
-          errors.push({ field: field.name, message: `"${field.label}" must be one of the allowed options.` })
+          errors.push({ field: field.name, message: `"${field.label}" must be one of the allowed options.`, code: 'option' })
         }
         break
       }
@@ -86,6 +94,8 @@ export function validateContentPayload(
           errors.push({
             field: field.name,
             message: `"${field.label}" must be at most ${maxLength} characters.`,
+            code: 'maxLength',
+            params: { max: maxLength },
           })
         }
         break