@latte-macchiat-io/latte-payload 1.0.1

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "@latte-macchiat-io/latte-payload",
+  "version": "1.0.1",
+  "description": "Reusable Payload CMS collections, utilities, and components for Latte projects",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./collections": {
+      "import": "./dist/collections/index.js",
+      "types": "./dist/collections/index.d.ts"
+    },
+    "./globals": {
+      "import": "./dist/globals/index.js",
+      "types": "./dist/globals/index.d.ts"
+    },
+    "./access": {
+      "import": "./dist/access/index.js",
+      "types": "./dist/access/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils/index.js",
+      "types": "./dist/utils/index.d.ts"
+    },
+    "./config": {
+      "import": "./dist/config/index.js",
+      "types": "./dist/config/index.d.ts"
+    },
+    "./tasks": {
+      "import": "./dist/tasks/index.js",
+      "types": "./dist/tasks/index.d.ts"
+    },
+    "./components": {
+      "import": "./dist/components/index.js",
+      "types": "./dist/components/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm clean && pnpm build",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "prettier": "prettier --check \"**/*.{js,jsx,ts,tsx}\"",
+    "prettier:fix": "prettier --write \"**/*.{js,jsx,ts,tsx}\"",
+    "test": "vitest",
+    "test:unit": "vitest --config vitest.config.ts --run",
+    "test:integration": "vitest --config vitest.integration.config.ts --run",
+    "test:all": "pnpm test:unit && pnpm test:integration",
+    "test:watch": "vitest --config vitest.config.ts",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --config vitest.config.ts --run --coverage",
+    "docs:generate": "typedoc --out docs src/index.ts",
+    "docs:serve": "npx http-server docs -p 8080"
+  },
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "cms",
+    "latte",
+    "starter",
+    "template"
+  ],
+  "author": "Latte Macchiat.io",
+  "license": "MIT",
+  "dependencies": {
+    "@date-fns/tz": "^1.4.1",
+    "next-intl": "^4.6.1",
+    "slugify": "^1.6.6",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@payloadcms/db-postgres": "^3.64.0",
+    "@payloadcms/email-nodemailer": "^3.64.0",
+    "@payloadcms/email-resend": "^3.64.0",
+    "@payloadcms/next": "^3.64.0",
+    "@payloadcms/richtext-lexical": "^3.64.0",
+    "@payloadcms/storage-s3": "^3.64.0",
+    "@payloadcms/ui": "^3.64.0",
+    "next": "^15.0.0",
+    "payload": "^3.64.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "sharp": "^0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "@payloadcms/email-nodemailer": {
+      "optional": true
+    },
+    "@payloadcms/email-resend": {
+      "optional": true
+    },
+    "@payloadcms/storage-s3": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@payloadcms/db-sqlite": "^3.64.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^20.6.0",
+    "@types/react": "19.1.10",
+    "@types/react-dom": "19.1.7",
+    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/ui": "^2.1.8",
+    "dotenv": "^17.2.3",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsx-a11y": "^6.6.1",
+    "eslint-plugin-storybook": "^10.1.6",
+    "happy-dom": "^20.0.11",
+    "prettier": "^3.7.4",
+    "typedoc": "^0.27.5",
+    "typedoc-plugin-markdown": "^4.3.3",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.21.0",
+    "vitest": "^2.1.8"
+  },
+  "packageManager": "pnpm@10.9.0",
+  "engines": {
+    "node": ">=22.x",
+    "pnpm": "^10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latte-macchiat-io/latte-payload"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - '@parcel/watcher'
+  - '@swc/core'
+  - unrs-resolver

package/src/access/adminAccessOnly.ts

@@ -0,0 +1,13 @@
+import { PayloadRequest } from 'payload';
+
+import { admins } from './admins';
+
+export const adminAccessOnly = {
+  admin: ({ req }: { req: PayloadRequest }) => Boolean(req.user?.roles?.includes('admin')),
+  create: admins,
+  delete: admins,
+  read: admins,
+  readVersions: admins,
+  unlock: admins,
+  update: admins,
+};

package/src/access/admins.ts

@@ -0,0 +1,78 @@
+import type { FieldAccess, PayloadRequest } from 'payload';
+
+/**
+ * Access control function that restricts access to admin users only.
+ *
+ * @description
+ * This function checks if the authenticated user has the 'admin' role in their roles array.
+ * Commonly used for collection-level or operation-level access control in PayloadCMS.
+ *
+ * @param {Object} params - Access control parameters
+ * @param {PayloadRequest} params.req - The Payload request object containing user information
+ *
+ * @returns {boolean} True if user has admin role, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Use in a collection config
+ * export const AdminOnlyCollection: CollectionConfig = {
+ *   slug: 'admin-only',
+ *   access: {
+ *     create: admins,
+ *     read: admins,
+ *     update: admins,
+ *     delete: admins,
+ *   },
+ *   fields: [...],
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use for specific operations
+ * if (admins({ req })) {
+ *   // User is admin, allow operation
+ * }
+ * ```
+ *
+ * @see {@link adminsFieldLevel} for field-level admin access control
+ * @see {@link adminAccessOnly} for a complete access control object with all operations restricted to admins
+ */
+export const admins = ({ req }: { req: PayloadRequest }) => {
+  // Return true or false based on if the user has an admin role
+  return Boolean(req.user?.roles?.includes('admin'));
+};
+
+/**
+ * Field-level access control function that restricts field access to admin users only.
+ *
+ * @description
+ * Similar to {@link admins} but designed for use with field-level access control.
+ * Checks if the user has the 'admin' role to determine field visibility/editability.
+ *
+ * @param {Object} params - Field access parameters
+ * @param {Object} params.req - The request object
+ * @param {Object} params.req.user - The authenticated user
+ *
+ * @returns {boolean} True if user has admin role, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Restrict field to admins only
+ * {
+ *   name: 'sensitiveField',
+ *   type: 'text',
+ *   access: {
+ *     read: adminsFieldLevel,
+ *     update: adminsFieldLevel,
+ *   },
+ * }
+ * ```
+ *
+ * @see {@link admins} for collection-level admin access control
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const adminsFieldLevel: FieldAccess<any, any> = ({ req: { user } }) => {
+  // Return true or false based on if the user has an admin role
+  return Boolean(user?.roles?.includes('admin'));
+};

package/src/access/anyone.ts

@@ -0,0 +1,35 @@
+import type { Access } from 'payload';
+
+/**
+ * Access control function that allows unrestricted public access.
+ *
+ * @description
+ * This function always returns true, allowing access to all users regardless of authentication status.
+ * Use this for truly public content like blog posts, landing pages, or public API endpoints.
+ *
+ * @returns {boolean} Always returns true
+ *
+ * @example
+ * ```typescript
+ * // Use for public content
+ * export const BlogPostsCollection: CollectionConfig = {
+ *   slug: 'blog-posts',
+ *   access: {
+ *     read: anyone, // Anyone can read
+ *     create: admins, // Only admins can create
+ *     update: admins,
+ *     delete: admins,
+ *   },
+ *   fields: [...],
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with publicReadAuthenticatedAccess for read-only public access
+ * import { publicReadAuthenticatedAccess } from '@latte-macchiat-io/latte-payload/access';
+ * ```
+ *
+ * @see {@link publicReadAuthenticatedAccess} for public read with authenticated write pattern
+ */
+export const anyone: Access = () => true;

package/src/access/authenticated.ts

@@ -0,0 +1,70 @@
+import type { Access, FieldAccess } from 'payload';
+
+/**
+ * Access control function that allows access to any authenticated user.
+ *
+ * @description
+ * This function checks if there is an authenticated user in the request, regardless of their role.
+ * Useful for content that should be accessible to all logged-in users but not to the public.
+ *
+ * @param {Object} params - Access control parameters
+ * @param {Object} params.req - The request object
+ * @param {Object} params.req.user - The authenticated user (if any)
+ *
+ * @returns {boolean} True if user is authenticated, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Use in a collection config
+ * export const UserContentCollection: CollectionConfig = {
+ *   slug: 'user-content',
+ *   access: {
+ *     create: authenticated,
+ *     read: authenticated,
+ *     update: authenticated,
+ *     delete: authenticated,
+ *   },
+ *   fields: [...],
+ * };
+ * ```
+ *
+ * @see {@link authenticatedFieldLevel} for field-level authenticated access control
+ * @see {@link authenticatedAccessOnly} for a complete access control object
+ */
+export const authenticated: Access = ({ req: { user } }) => {
+  // Return true or false based on if the user is authenticated
+  return Boolean(!!user);
+};
+
+/**
+ * Field-level access control function that restricts field access to authenticated users.
+ *
+ * @description
+ * Similar to {@link authenticated} but designed for use with field-level access control.
+ * Checks if the user is authenticated to determine field visibility/editability.
+ *
+ * @param {Object} params - Field access parameters
+ * @param {Object} params.req - The request object
+ * @param {Object} params.req.user - The authenticated user (if any)
+ *
+ * @returns {boolean} True if user is authenticated, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Hide field from unauthenticated users
+ * {
+ *   name: 'memberOnlyField',
+ *   type: 'text',
+ *   access: {
+ *     read: authenticatedFieldLevel,
+ *     update: authenticatedFieldLevel,
+ *   },
+ * }
+ * ```
+ *
+ * @see {@link authenticated} for collection-level authenticated access control
+ */
+export const authenticatedFieldLevel: FieldAccess = ({ req: { user } }) => {
+  // Return true or false based on if the user is authenticated
+  return Boolean(!!user);
+};

package/src/access/authenticatedAccessOnly.ts

@@ -0,0 +1,13 @@
+import { PayloadRequest } from 'payload';
+
+import { authenticated } from './authenticated';
+
+export const authenticatedAccessOnly = {
+  admin: ({ req }: { req: PayloadRequest }) => !!req.user,
+  create: authenticated,
+  delete: authenticated,
+  read: authenticated,
+  readVersions: authenticated,
+  unlock: authenticated,
+  update: authenticated,
+};

package/src/access/index.ts

@@ -0,0 +1,6 @@
+export { anyone } from './anyone';
+export { authenticated, authenticatedFieldLevel } from './authenticated';
+export { admins, adminsFieldLevel } from './admins';
+export { adminAccessOnly } from './adminAccessOnly';
+export { authenticatedAccessOnly } from './authenticatedAccessOnly';
+export { publicReadAuthenticatedAccess } from './publicReadAuthenticatedAccess';

package/src/access/publicReadAuthenticatedAccess.ts

@@ -0,0 +1,14 @@
+import { PayloadRequest } from 'payload';
+
+import { anyone } from './anyone';
+import { authenticated } from './authenticated';
+
+export const publicReadAuthenticatedAccess = {
+  admin: ({ req }: { req: PayloadRequest }) => !!req.user,
+  create: authenticated,
+  delete: authenticated,
+  read: anyone,
+  readVersions: authenticated,
+  unlock: authenticated,
+  update: authenticated,
+};

package/src/collections/ContactMessages/hooks/sendEmailNotification.ts

@@ -0,0 +1,58 @@
+import { CollectionAfterChangeHook } from 'payload';
+
+export interface SendEmailNotificationConfig {
+  /**
+   * Email address to send notifications to
+   * If not provided, uses process.env.EMAIL_DEFAULT_CONTACT_ADDRESS
+   */
+  contactEmail?: string;
+
+  /**
+   * Subject for the notification email
+   * Default: 'Nouveau message de contact'
+   */
+  subject?: string;
+
+  /**
+   * Custom email body generator
+   * @param doc - The contact message document
+   * @returns Email body text
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  generateEmailBody?: (doc: any) => string;
+}
+
+/**
+ * Create a sendEmailNotification hook with custom configuration
+ *
+ * @param config - Optional configuration for email notifications
+ * @returns CollectionAfterChangeHook
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createSendEmailNotificationHook(config?: SendEmailNotificationConfig): CollectionAfterChangeHook<any> {
+  return async ({ req: { payload }, doc }) => {
+    const toEmail = config?.contactEmail || process.env.EMAIL_DEFAULT_CONTACT_ADDRESS;
+
+    if (!toEmail) {
+      payload.logger.error('No contact email address configured for sendEmailNotification hook');
+      return;
+    }
+
+    payload.logger.info('Sending email notification to the admin');
+
+    const emailBody =
+      config?.generateEmailBody?.(doc) ||
+      `Un nouveau message de contact a été reçu de la part de ${doc.name} (${doc.email}).\n\nSujet: ${doc.subject}\n\nMessage: ${doc.message}`;
+
+    await payload.sendEmail({
+      to: toEmail,
+      subject: config?.subject || 'Nouveau message de contact',
+      text: emailBody,
+    });
+  };
+}
+
+/**
+ * Default sendEmailNotification hook
+ */
+export const sendEmailNotification = createSendEmailNotificationHook();

package/src/collections/ContactMessages/index.ts

@@ -0,0 +1,100 @@
+import { CollectionConfig } from 'payload';
+
+import { createSendEmailNotificationHook, sendEmailNotification, type SendEmailNotificationConfig } from './hooks/sendEmailNotification';
+import { authenticated } from '../../access/authenticated';
+import type { Locale } from '../../types';
+
+export interface ContactMessagesConfig {
+  /**
+   * Allowed locales for contact messages
+   * @default ['en', 'fr', 'nl']
+   */
+  locales?: Locale[];
+
+  /**
+   * Configuration for email notifications
+   */
+  emailNotificationConfig?: SendEmailNotificationConfig;
+}
+
+/**
+ * Create ContactMessages collection with optional configuration
+ *
+ * @param config - Optional configuration for the ContactMessages collection
+ * @returns CollectionConfig for ContactMessages
+ */
+export function createContactMessagesCollection(config?: ContactMessagesConfig): CollectionConfig {
+  const locales = config?.locales || (['en', 'fr', 'nl'] as Locale[]);
+
+  return {
+    slug: 'contact-messages',
+    labels: {
+      singular: { fr: 'Message reçu', nl: 'Ontvangen bericht', en: 'Received Message' },
+      plural: { fr: 'Messages reçus', nl: 'Ontvangen berichten', en: 'Received Messages' },
+    },
+    admin: {
+      description: {
+        fr: 'Messages reçus via le formulaire de contact',
+        nl: 'Berichten ontvangen via het contactformulier',
+        en: 'Messages received via the contact form',
+      },
+      group: { fr: '✉️ Communication', nl: '✉️ Communicatie', en: '✉️ Communication' },
+      useAsTitle: 'subject',
+      defaultColumns: ['name', 'email', 'subject', 'createdAt'],
+      hideAPIURL: true,
+      hidden: true, // Hide from the admin UI
+    },
+    access: {
+      create: () => false, // Not available
+      delete: authenticated,
+      read: authenticated,
+      update: () => false, // Not available
+    },
+    hooks: {
+      afterChange: [config?.emailNotificationConfig ? createSendEmailNotificationHook(config.emailNotificationConfig) : sendEmailNotification],
+    },
+    fields: [
+      {
+        name: 'name',
+        label: { fr: 'Nom', nl: 'Naam', en: 'Name' },
+        type: 'text',
+        required: true,
+      },
+      {
+        name: 'email',
+        label: { fr: 'Email', nl: 'E-mail', en: 'Email' },
+        type: 'email',
+        required: true,
+      },
+      {
+        name: 'subject',
+        label: { fr: 'Sujet', nl: 'Onderwerp', en: 'Subject' },
+        type: 'text',
+        required: true,
+      },
+      {
+        name: 'message',
+        label: { fr: 'Message', nl: 'Bericht', en: 'Message' },
+        type: 'textarea',
+        required: true,
+      },
+      {
+        name: 'locale',
+        label: { fr: 'Langue', nl: 'Taal', en: 'Language' },
+        type: 'text',
+        required: true,
+        validate: (value: string | string[] | null | undefined) => {
+          return locales.includes(value as Locale) || 'Invalid locale';
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Default ContactMessages collection
+ */
+export const ContactMessages = createContactMessagesCollection();
+
+// Re-export for customization
+export { createSendEmailNotificationHook, type SendEmailNotificationConfig };

package/src/collections/EmailTemplates/index.ts

@@ -0,0 +1,89 @@
+import { CollectionConfig } from 'payload';
+import { admins } from '../../access/admins';
+
+/**
+ * Configuration options for EmailTemplates collection
+ */
+export interface EmailTemplatesConfig {
+  /**
+   * Allowed email template codes
+   * Default: ['verify-email', 'password-lost']
+   */
+  emailCodes?: Array<{ label: string; value: string }>;
+}
+
+/**
+ * Create EmailTemplates collection with optional configuration
+ *
+ * @param config - Optional configuration for email codes
+ * @returns CollectionConfig for EmailTemplates
+ */
+export function createEmailTemplatesCollection(config?: EmailTemplatesConfig): CollectionConfig {
+  const emailCodes = config?.emailCodes || [
+    { label: 'verify-email', value: 'verify-email' },
+    { label: 'password-lost', value: 'password-lost' },
+  ];
+
+  return {
+    slug: 'email-templates',
+    labels: {
+      singular: { fr: "Modèle d'email", nl: 'E-mail sjabloon', en: 'Email Template' },
+      plural: { fr: "Modèles d'emails", nl: 'E-mail sjablonen', en: 'Email Templates' },
+    },
+    admin: {
+      description: { fr: "Gérer les modèles d'emails", nl: 'Beheer e-mail sjablonen', en: 'Manage email templates' },
+      group: { fr: '✉️ Communication', nl: '✉️ Communicatie', en: '✉️ Communication' },
+      useAsTitle: 'name',
+      defaultColumns: ['code', 'name'],
+      hideAPIURL: true,
+    },
+    access: {
+      create: admins, // Not allowed to create new emails templates
+      delete: () => false, // Not allowed to delete emails templates
+      read: admins,
+      update: admins,
+    },
+    fields: [
+      {
+        type: 'row',
+        fields: [
+          {
+            name: 'name',
+            label: { fr: 'Nom (interne)', nl: 'Naam (intern)', en: 'Name (internal)' },
+            type: 'text',
+            required: true,
+            unique: true,
+          },
+
+          {
+            name: 'code',
+            label: { fr: 'Identifiant', nl: 'Identificatie', en: 'Identifier' },
+            type: 'select',
+            options: emailCodes,
+            required: true,
+            unique: true,
+          },
+        ],
+      },
+      {
+        name: 'subject',
+        label: { fr: "Sujet de l'email", nl: 'Onderwerp van de e-mail', en: 'Email subject' },
+        type: 'text',
+        required: true,
+        localized: true,
+      },
+      {
+        name: 'body',
+        label: { fr: "Corps de l'email", nl: 'Inhoud van de e-mail', en: 'Email body' },
+        type: 'richText',
+        required: true,
+        localized: true,
+      },
+    ],
+  };
+}
+
+/**
+ * Default EmailTemplates collection with standard email codes
+ */
+export const EmailTemplates = createEmailTemplatesCollection();

package/src/collections/Media/index.ts

@@ -0,0 +1,24 @@
+import type { CollectionConfig } from 'payload';
+
+import { publicReadAuthenticatedAccess } from '../../access/publicReadAuthenticatedAccess';
+
+export const Media: CollectionConfig = {
+  slug: 'media',
+  labels: {
+    singular: { fr: 'Upload', en: 'Upload', nl: 'Upload' },
+    plural: { fr: 'Uploads', en: 'Uploads', nl: 'Uploads' },
+  },
+  admin: {
+    hideAPIURL: true,
+    group: { fr: 'Uploads et médias', en: 'Uploads and Media', nl: 'Uploads en media' },
+  },
+  access: publicReadAuthenticatedAccess,
+  fields: [
+    {
+      name: 'alt',
+      type: 'text',
+      required: false,
+    },
+  ],
+  upload: true,
+};

package/src/collections/QueuedEmails/components/HtmlViewer.tsx

@@ -0,0 +1,16 @@
+import type { TextareaFieldServerComponent } from 'payload';
+
+export const HTMLViewer: TextareaFieldServerComponent = async ({ data }) => {
+  return (
+    <div
+      style={{
+        padding: '1rem',
+        border: '1px solid #ccc',
+        backgroundColor: '#f9f9f9',
+        borderRadius: '6px',
+        marginTop: '0.5rem',
+      }}
+      dangerouslySetInnerHTML={{ __html: data.htmlBody || '' }}
+    />
+  );
+};