@delmaredigital/payload-puck 0.1.3 → 0.3.0

package/dist/admin/index.d.mts

@@ -1,157 +0,0 @@
-import { Config, Plugin, Data } from '@measured/puck';
-import { Field } from 'payload';
-
-/**
- * Props for the PuckEditorView component
- */
-interface PuckEditorViewProps {
-    /**
-     * Puck configuration with components and settings
-     */
-    config: Config;
-    /**
-     * Collection slug for API endpoints
-     * @default 'pages'
-     */
-    collectionSlug?: string;
-    /**
-     * Base API path for Puck operations
-     * @default '/api/puck'
-     */
-    apiBasePath?: string;
-    /**
-     * URL to navigate to when back button is clicked
-     * Falls back to /admin/collections/{collectionSlug}
-     */
-    backUrl?: string;
-    /**
-     * Preview URL or function to generate preview URL from slug
-     */
-    previewUrl?: string | ((slug: string) => string);
-    /**
-     * Layout styles for theme-aware preview
-     */
-    layoutStyles?: Record<string, {
-        background: string;
-        isDark: boolean;
-    }>;
-    /**
-     * Key in root.props to read layout value from
-     * @default 'pageLayout'
-     */
-    layoutKey?: string;
-    /**
-     * Additional Puck plugins to use.
-     * The headingAnalyzer plugin is included by default.
-     * Set to `false` to disable all default plugins.
-     */
-    plugins?: Plugin[] | false;
-    /**
-     * Callback on successful save
-     */
-    onSaveSuccess?: (data: Data) => void;
-    /**
-     * Callback on save error
-     */
-    onSaveError?: (error: Error) => void;
-}
-
-/**
- * Props for EditWithPuckButton when used standalone
- */
-interface EditWithPuckButtonProps {
-    /**
-     * Document ID to edit
-     */
-    id?: string;
-    /**
-     * Collection slug
-     * @default 'pages'
-     */
-    collectionSlug?: string;
-    /**
-     * Custom path pattern for the Puck editor
-     * Use {id} as placeholder for the document ID
-     * @default '/pages/{id}/edit'
-     */
-    editorPathPattern?: string;
-    /**
-     * Button label
-     * @default 'Edit with Puck'
-     */
-    label?: string;
-    /**
-     * Whether to show as icon only
-     * @default false
-     */
-    iconOnly?: boolean;
-}
-
-/**
- * Props for configuring the EditWithPuckCell component
- */
-interface EditWithPuckCellConfig {
-    /**
-     * Collection slug for building the editor URL
-     * @default 'pages'
-     */
-    collectionSlug?: string;
-    /**
-     * Custom editor path pattern
-     * Use {id} as placeholder for the document ID
-     * @default '/admin/puck/{collectionSlug}/{id}/edit'
-     */
-    editorPathPattern?: string;
-}
-
-/**
- * Configuration for generating the edit button field
- */
-interface AdminComponentsConfig {
-    /**
-     * Collection slug for the pages collection
-     * @default 'pages'
-     */
-    collectionSlug?: string;
-    /**
-     * URL pattern for the Puck editor page
-     * Use {id} as placeholder for document ID
-     * @default '/pages/{id}/edit'
-     */
-    editorPathPattern?: string;
-    /**
-     * Button label text
-     * @default 'Edit with Puck'
-     */
-    buttonLabel?: string;
-    /**
-     * Position of the edit button in admin
-     * @default 'sidebar'
-     */
-    buttonPosition?: 'sidebar' | 'main';
-}
-/**
- * Generates the UI field configuration for the Edit with Puck button
- *
- * Use this if you want to manually add the edit button field to your
- * collection instead of using the plugin's auto-generation.
- *
- * @example
- * ```ts
- * import { generatePuckEditField } from '@delmaredigital/payload-puck/admin'
- *
- * const Pages: CollectionConfig = {
- *   slug: 'pages',
- *   fields: [
- *     // ... other fields
- *     generatePuckEditField({
- *       editorPathPattern: '/pages/{id}/edit',
- *       buttonLabel: 'Visual Editor',
- *     }),
- *   ],
- * }
- * ```
- */
-declare function generatePuckEditField(config?: AdminComponentsConfig): Field;
-
-export { type AdminComponentsConfig, type EditWithPuckButtonProps, type EditWithPuckCellConfig, type PuckEditorViewProps, generatePuckEditField };

package/dist/admin/index.mjs

@@ -1,29 +0,0 @@
-// src/admin/generateAdminComponents.ts
-function generatePuckEditField(config = {}) {
-  const {
-    collectionSlug = "pages",
-    editorPathPattern = "/pages/{id}/edit",
-    buttonLabel = "Edit with Puck",
-    buttonPosition = "sidebar"
-  } = config;
-  return {
-    name: "puckEdit",
-    type: "ui",
-    admin: {
-      position: buttonPosition,
-      components: {
-        Field: "@delmaredigital/payload-puck/admin/client#EditWithPuckButton",
-        Cell: "@delmaredigital/payload-puck/admin/client#EditWithPuckCell"
-      },
-      custom: {
-        collectionSlug,
-        editorPathPattern,
-        label: buttonLabel
-      }
-    }
-  };
-}
-
-export { generatePuckEditField };
-//# sourceMappingURL=index.mjs.map
-//# sourceMappingURL=index.mjs.map

package/dist/api/index.d.mts

@@ -1,460 +0,0 @@
-import * as payload from 'payload';
-import { NextRequest } from 'next/server';
-import { Data } from '@measured/puck';
-
-/**
- * Authenticated user from the auth system
- */
-interface AuthenticatedUser {
-    id: string;
-    [key: string]: unknown;
-}
-/**
- * Result of an authentication check
- */
-interface AuthResult {
-    authenticated: boolean;
-    user?: AuthenticatedUser;
-    error?: string;
-}
-/**
- * Result of a permission check
- */
-interface PermissionResult {
-    allowed: boolean;
-    error?: string;
-}
-/**
- * Authentication and authorization hooks for Puck API routes
- *
- * These hooks allow you to integrate with any authentication system
- * (Better Auth, NextAuth, Payload auth, custom JWT, etc.)
- *
- * @example
- * ```typescript
- * // Example with Better Auth
- * const authHooks: PuckApiAuthHooks = {
- *   authenticate: async (request) => {
- *     const session = await auth.api.getSession({ headers: await headers() })
- *     if (!session?.user) return { authenticated: false }
- *     return { authenticated: true, user: session.user }
- *   },
- *   canEdit: async (user, pageId) => {
- *     return { allowed: hasRole(user, 'editor') }
- *   },
- * }
- * ```
- */
-interface PuckApiAuthHooks {
-    /**
-     * Authenticate the incoming request
-     * Should return the authenticated user or authentication failure
-     */
-    authenticate: (request: NextRequest) => Promise<AuthResult>;
-    /**
-     * Check if user can list pages
-     * @default Always allowed for authenticated users
-     */
-    canList?: (user: AuthenticatedUser) => Promise<PermissionResult> | PermissionResult;
-    /**
-     * Check if user can view a specific page
-     * @default Always allowed for authenticated users
-     */
-    canView?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
-    /**
-     * Check if user can create new pages
-     * @default Always allowed for authenticated users
-     */
-    canCreate?: (user: AuthenticatedUser) => Promise<PermissionResult> | PermissionResult;
-    /**
-     * Check if user can edit a specific page
-     * @default Always allowed for authenticated users
-     */
-    canEdit?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
-    /**
-     * Check if user can publish a specific page (change status to published)
-     * @default Same as canEdit
-     */
-    canPublish?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
-    /**
-     * Check if user can delete a specific page
-     * @default Always allowed for authenticated users
-     */
-    canDelete?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
-}
-/**
- * Mapping configuration for syncing Puck root.props to Payload fields
- *
- * @example
- * ```typescript
- * // Simple mapping
- * { from: 'pageLayout', to: 'pageLayout' }
- *
- * // Nested field mapping (uses official @payloadcms/plugin-seo convention)
- * { from: 'title', to: 'meta.title' }
- *
- * // With transformation
- * {
- *   from: 'publishDate',
- *   to: 'publishedAt',
- *   transform: (value) => value ? new Date(value as string).toISOString() : null
- * }
- * ```
- */
-interface RootPropsMapping {
-    /**
-     * Property name in Puck root.props
-     */
-    from: string;
-    /**
-     * Field path in Payload document (supports dot notation for nested fields)
-     */
-    to: string;
-    /**
-     * Optional transformation function
-     */
-    transform?: (value: unknown) => unknown;
-}
-/**
- * Error context passed to onError callback
- */
-interface ErrorContext {
-    operation: string;
-    request: NextRequest;
-    pageId?: string;
-}
-/**
- * Configuration for Puck API routes
- *
- * @example
- * ```typescript
- * const config: PuckApiRoutesConfig = {
- *   collection: 'pages',
- *   auth: {
- *     authenticate: async (request) => {
- *       // Your auth logic here
- *     },
- *     canPublish: async (user) => {
- *       return { allowed: user.role === 'admin' }
- *     },
- *   },
- *   rootPropsMapping: [
- *     { from: 'title', to: 'meta.title' },
- *     { from: 'description', to: 'meta.description' },
- *   ],
- *   enableDrafts: true,
- * }
- * ```
- */
-interface PuckApiRoutesConfig {
-    /**
-     * Payload collection slug for pages
-     * @default 'pages'
-     */
-    collection?: string;
-    /**
-     * Payload configuration - import from @payload-config
-     * Required for Turbopack/Next.js 16+ compatibility
-     *
-     * @example
-     * ```typescript
-     * import config from '@payload-config'
-     *
-     * createPuckApiRoutesWithId({
-     *   payloadConfig: config,
-     *   // ...
-     * })
-     * ```
-     */
-    payloadConfig: Promise<payload.SanitizedConfig>;
-    /**
-     * Authentication and authorization hooks
-     */
-    auth: PuckApiAuthHooks;
-    /**
-     * Custom mappings from Puck root.props to Payload fields
-     * These are merged with the default mappings
-     */
-    rootPropsMapping?: RootPropsMapping[];
-    /**
-     * Default Puck data for new pages
-     */
-    defaultPuckData?: Data;
-    /**
-     * Enable draft mode for page creation/updates
-     * @default true
-     */
-    enableDrafts?: boolean;
-    /**
-     * Custom error handler for logging/monitoring
-     */
-    onError?: (error: unknown, context: ErrorContext) => void;
-}
-/**
- * Context passed to Next.js App Router route handlers
- */
-interface RouteHandlerContext {
-    params: Promise<Record<string, string>>;
-}
-/**
- * Context for route handlers that require an id parameter
- */
-interface RouteHandlerWithIdContext {
-    params: Promise<{
-        id: string;
-    }>;
-}
-/**
- * Next.js App Router route handler type
- */
-type RouteHandler = (request: NextRequest, context: RouteHandlerContext) => Promise<Response>;
-/**
- * Next.js App Router route handler type for [id] routes
- */
-type RouteHandlerWithId = (request: NextRequest, context: RouteHandlerWithIdContext) => Promise<Response>;
-/**
- * Route handlers returned by createPuckApiRoutes
- */
-interface PuckApiRouteHandlers {
-    GET: RouteHandler;
-    POST: RouteHandler;
-}
-/**
- * Route handlers returned by createPuckApiRoutesWithId
- */
-interface PuckApiRouteWithIdHandlers {
-    GET: RouteHandlerWithId;
-    PATCH: RouteHandlerWithId;
-    DELETE: RouteHandlerWithId;
-}
-/**
- * Request body for creating a new page
- */
-interface CreatePageBody {
-    title: string;
-    slug: string;
-    puckData?: Data;
-    status?: 'draft' | 'published';
-}
-/**
- * Request body for updating a page
- */
-interface UpdatePageBody {
-    puckData?: Data;
-    title?: string;
-    slug?: string;
-    status?: 'draft' | 'published';
-    /**
-     * When true, save as draft without publishing.
-     * Used by Payload's versions.drafts system.
-     */
-    draft?: boolean;
-}
-/**
- * Standard API response wrapper
- */
-interface ApiResponse<T = unknown> {
-    doc?: T;
-    docs?: T[];
-    error?: string;
-    success?: boolean;
-    totalDocs?: number;
-    totalPages?: number;
-    page?: number;
-    limit?: number;
-    hasPrevPage?: boolean;
-    hasNextPage?: boolean;
-}
-/**
- * A version entry from Payload's versions system
- */
-interface PageVersion {
-    id: string;
-    parent: string;
-    version: {
-        title?: string;
-        slug?: string;
-        puckData?: Data;
-        _status?: 'draft' | 'published';
-        updatedAt: string;
-        createdAt: string;
-    };
-    createdAt: string;
-    updatedAt: string;
-    autosave?: boolean;
-    latest?: boolean;
-}
-/**
- * Route handlers returned by createPuckApiRoutesVersions
- */
-interface PuckApiVersionsRouteHandlers {
-    GET: RouteHandlerWithId;
-    POST: RouteHandlerWithId;
-}
-
-/**
- * Create API route handlers for /api/puck/pages
- *
- * Provides GET (list pages) and POST (create page) handlers
- * with configurable authentication and authorization.
- *
- * @example
- * ```typescript
- * // src/app/api/puck/pages/route.ts
- * import { createPuckApiRoutes } from '@delmaredigital/payload-puck/api'
- * import config from '@payload-config'
- *
- * export const { GET, POST } = createPuckApiRoutes({
- *   collection: 'pages',
- *   payloadConfig: config,
- *   auth: {
- *     authenticate: async (request) => {
- *       const session = await getSession(request)
- *       if (!session?.user) return { authenticated: false }
- *       return { authenticated: true, user: session.user }
- *     },
- *     canCreate: async (user) => {
- *       return { allowed: user.role === 'admin' || user.role === 'editor' }
- *     },
- *   },
- * })
- * ```
- */
-declare function createPuckApiRoutes(routeConfig: PuckApiRoutesConfig): PuckApiRouteHandlers;
-
-/**
- * Create API route handlers for /api/puck/pages/[id]
- *
- * Provides GET (fetch page), PATCH (update page), and DELETE (delete page)
- * handlers with configurable authentication and authorization.
- *
- * @example
- * ```typescript
- * // src/app/api/puck/pages/[id]/route.ts
- * import { createPuckApiRoutesWithId } from '@delmaredigital/payload-puck/api'
- * import config from '@payload-config'
- *
- * export const { GET, PATCH, DELETE } = createPuckApiRoutesWithId({
- *   collection: 'pages',
- *   payloadConfig: config,
- *   auth: {
- *     authenticate: async (request) => {
- *       const session = await getSession(request)
- *       if (!session?.user) return { authenticated: false }
- *       return { authenticated: true, user: session.user }
- *     },
- *     canPublish: async (user) => {
- *       return { allowed: user.role === 'admin' }
- *     },
- *   },
- *   rootPropsMapping: [
- *     { from: 'customField', to: 'customPayloadField' },
- *   ],
- * })
- * ```
- */
-declare function createPuckApiRoutesWithId(routeConfig: PuckApiRoutesConfig): PuckApiRouteWithIdHandlers;
-
-/**
- * Create API route handlers for /api/puck/pages/[id]/versions
- *
- * Provides GET (list versions) and POST (restore version) handlers
- * for managing page version history.
- *
- * @example
- * ```typescript
- * // src/app/api/puck/pages/[id]/versions/route.ts
- * import { createPuckApiRoutesVersions } from '@delmaredigital/payload-puck/api'
- * import config from '@payload-config'
- *
- * export const { GET, POST } = createPuckApiRoutesVersions({
- *   collection: 'pages',
- *   payloadConfig: config,
- *   auth: {
- *     authenticate: async (request) => {
- *       const session = await getSession(request)
- *       if (!session?.user) return { authenticated: false }
- *       return { authenticated: true, user: session.user }
- *     },
- *   },
- * })
- * ```
- */
-declare function createPuckApiRoutesVersions(routeConfig: PuckApiRoutesConfig): PuckApiVersionsRouteHandlers;
-
-/**
- * Default mappings from Puck root.props to Payload fields
- *
- * These mappings sync common page properties from Puck's visual editor
- * to the corresponding Payload collection fields.
- *
- * SEO fields use the official @payloadcms/plugin-seo convention: meta.title, meta.description
- */
-declare const DEFAULT_ROOT_PROPS_MAPPINGS: RootPropsMapping[];
-/**
- * Set a nested value in an object using dot notation path
- *
- * @example
- * ```typescript
- * const obj = {}
- * setNestedValue(obj, 'meta.title', 'My Title')
- * // Result: { meta: { title: 'My Title' } }
- * ```
- */
-declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void;
-/**
- * Get a nested value from an object using dot notation path
- *
- * @example
- * ```typescript
- * const obj = { meta: { title: 'My Title' } }
- * getNestedValue(obj, 'meta.title') // 'My Title'
- * ```
- */
-declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
-/**
- * Merge mappings, with custom mappings taking precedence over defaults
- *
- * @param customMappings - Custom mappings to merge with defaults
- * @returns Merged array of mappings with duplicates resolved (custom wins)
- */
-declare function mergeMappings(customMappings?: RootPropsMapping[]): RootPropsMapping[];
-/**
- * Map Puck root.props to Payload field update data
- *
- * Takes the root.props from Puck data and maps them to the appropriate
- * Payload fields based on the provided mappings.
- *
- * @param rootProps - The root.props object from Puck data
- * @param customMappings - Optional custom mappings to merge with defaults
- * @returns Object ready to be spread into Payload update data
- *
- * @example
- * ```typescript
- * const rootProps = {
- *   title: 'My Page',
- *   metaTitle: 'My Page | Site Name',
- *   metaDescription: 'Description here',
- * }
- *
- * const updateData = mapRootPropsToPayloadFields(rootProps)
- * // Result: {
- * //   title: 'My Page',
- * //   meta: {
- * //     title: 'My Page | Site Name',
- * //     description: 'Description here',
- * //   },
- * // }
- * ```
- */
-declare function mapRootPropsToPayloadFields(rootProps: Record<string, unknown>, customMappings?: RootPropsMapping[]): Record<string, unknown>;
-/**
- * Deep merge objects, with source values overwriting target values
- *
- * @param target - The target object to merge into
- * @param source - The source object to merge from
- * @returns The merged object (target is modified in place)
- */
-declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
-
-export { type ApiResponse, type AuthResult, type AuthenticatedUser, type CreatePageBody, DEFAULT_ROOT_PROPS_MAPPINGS, type ErrorContext, type PageVersion, type PermissionResult, type PuckApiAuthHooks, type PuckApiRouteHandlers, type PuckApiRouteWithIdHandlers, type PuckApiRoutesConfig, type PuckApiVersionsRouteHandlers, type RootPropsMapping, type RouteHandler, type RouteHandlerContext, type RouteHandlerWithId, type RouteHandlerWithIdContext, type UpdatePageBody, createPuckApiRoutes, createPuckApiRoutesVersions, createPuckApiRoutesWithId, deepMerge, getNestedValue, mapRootPropsToPayloadFields, mergeMappings, setNestedValue };