nextpress-core 1.0.0

package/lib/acf-functions/core/acf-builder.ts

@@ -0,0 +1,105 @@
+/**
+ * Class representing ACF builder.
+ */
+export class ACFBuilder
+{
+    /** Array of ACF field groups. */
+    private fieldGroups: ACFFieldGroup[] = [];
+
+    public constructor() {};
+
+    /**
+     * Gets built field groups.
+     *
+     * @returns {ACFFieldGroup[]} Array of field groups.
+     */
+    public getFieldGroups(): ACFFieldGroup[] {
+        return this.fieldGroups;
+    }
+
+    /**
+     * Converts field groups to JSON string.
+     *
+     * @returns {string} JSON string representation of field groups.
+     */
+    public toJSON(): string {
+        return JSON.stringify(this.fieldGroups);
+    }
+
+    /**
+     * Registers and processes Nextpress field groups.
+     *
+     * @param {NextpressFieldGroup[]} fieldGroups - Array of field groups to register.
+     * @returns {this} Current instance.
+     */
+    public registerFieldGroups(fieldGroups: NextpressFieldGroup[]): this {
+        const keyedFieldGroups: ACFFieldGroup[] = fieldGroups.map(fieldGroup => ({
+            ...fieldGroup,
+            key: `group_${this.formatKeySuffix(fieldGroup.title)}`,
+            fields: this.setFieldKeys(fieldGroup.fields, fieldGroup.title),
+        }));
+
+        this.fieldGroups = [...this.fieldGroups, ...keyedFieldGroups];
+
+        return this;
+    }
+
+    /**
+     * Sets keys for fields based on parent name.
+     *
+     * @param {NextpressField[]} fields - Array of fields to process.
+     * @param {string} parentName - Parent string name.
+     * @returns {ACFField[]} Array of fields with generated keys.
+     */
+    private setFieldKeys(fields: NextpressField[], parentName: string): ACFField[] {
+        return fields.map(field => {
+            const keySuffix = this.formatKeySuffix(`${parentName}_${field.name}`);
+
+            const childFields = field.sub_fields
+                ? this.setFieldKeys(field.sub_fields, keySuffix)
+                : undefined;
+
+            const childLayouts = field.layouts
+                ? this.setLayoutKeys(field.layouts, keySuffix)
+                : undefined;
+
+            return {
+                ...field,
+                key: `field_${keySuffix}`,
+                sub_fields: childFields,
+                layouts: childLayouts
+            }});
+    }
+
+    /**
+     * Sets keys for layouts based on parent name.
+     *
+     * @param {NextpressLayout[]} layouts - Array of layouts to process.
+     * @param {string} parentName - Parent string name.
+     * @returns {ACFLayout[]} Array of layouts with generated keys.
+     */
+    private setLayoutKeys(layouts: NextpressLayout[], parentName: string): ACFLayout[] {
+        return layouts.map(layout => {
+            const keySuffix = this.formatKeySuffix(`${parentName}_${layout.name}`);
+
+            const childFields = layout.sub_fields
+                ? this.setFieldKeys(layout.sub_fields, `${parentName}_${layout.name}`)
+                : undefined;
+
+            return {
+                ...layout,
+                key: `layout_${keySuffix}`,
+                sub_fields: childFields || [],
+        }})
+    }
+
+    /**
+     * Formats suffix string.
+     *
+     * @param {string} suffix - Suffix to format.
+     * @returns {string} Formatted string.
+     */
+    private formatKeySuffix(suffix: string): string {
+        return suffix.replace(/[\s-]+/g, '_').toLowerCase();
+    }
+}

package/lib/acf-functions/core/acf-component-autoloader.ts

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import path from 'path';
+import { NextpressComponent } from '../types/components/nextpress-component';
+
+/**
+ * Autoloads ACF components dynamically from the templates directory.
+ * * **Requirements for it to work:**
+ * Each `.tsx` file within the `src/app/_templates/components/` directory MUST export the following:
+ * 1. `layout` (Named Export): The configuration for the ACF layout, typically defined using the `defineLayout` function.
+ * 2. `default` (Default Export): The React component (JSX/TSX function) that renders the layout.
+ *
+ * @returns {Promise<NextpressComponent[]>} A promise resolving to an array of mapped layout configurations and their respective components.
+ */
+export async function acfComponentAutoloader(): Promise<NextpressComponent[]> {
+    const absolutePath = path.join(process.cwd(), 'src', 'app', '_templates', 'components');
+    const files = fs.readdirSync(absolutePath);
+
+    const layouts: NextpressComponent[] = [];
+
+    for (const file of files) {
+        if (!file.endsWith('.tsx')) continue;
+
+        const imported = await import(`@/app/_templates/components/${file}`);
+
+        const layout = imported.layout;
+        const component = imported.default;
+        if (!layout || !component) continue;
+
+        layouts.push({layout, Component: component});
+    }
+
+    return layouts;
+}

package/lib/acf-functions/core/acf-field-group-autoloader.ts

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Autoloads ACF field groups dynamically from the field-groups directory.
+ * * **Requirements for it to work:**
+ * Each `.ts` file within the `src/app/_templates/components/field-groups/` directory MUST export the following:
+ * 1. `default` (Default Export): The configuration object for the ACF Field Group, typically defined using the `defineFieldGroup` function.
+ *
+ * @returns {Promise<NextpressFieldGroup[]>} A promise resolving to an array of loaded ACF field group configurations.
+ */
+export async function acfFieldGroupAutoloader(): Promise<NextpressFieldGroup[]> {
+    const absolutePath = path.join(process.cwd(), 'src', 'app', '_templates', 'components', 'field-groups');
+    const files = fs.readdirSync(absolutePath);
+
+    const fieldGroups: NextpressFieldGroup[] = [];
+
+    for (const file of files) {
+        if (!file.endsWith('.ts')) continue;
+
+        const imported = await import(`@/app/_templates/components/field-groups/${file}`);
+        const fieldGroup = imported.default;
+
+        fieldGroups.push(fieldGroup);
+    }
+
+    return fieldGroups;
+}

package/lib/acf-functions/services/define-field-group.ts

@@ -0,0 +1,10 @@
+/**
+ * Defines field group configuration and applies typing.
+ *
+ * @template T - Field group type extending NextpressFieldGroup.
+ * @param {T} layout - Field group configuration object.
+ * @returns {T} Passed field group configuration object.
+ */
+export function defineFieldGroup<const T extends NextpressFieldGroup>(layout: T): T {
+    return layout;
+}

package/lib/acf-functions/services/define-layout.ts

@@ -0,0 +1,10 @@
+/**
+ * Defines layout configuration and applies typing.
+ *
+ * @template T - Layout type extending NextpressLayout.
+ * @param {T} layout - Layout configuration object.
+ * @returns {T} Passed layout configuration object.
+ */
+export function defineLayout<const T extends NextpressLayout>(layout: T): T {
+    return layout;
+}

package/lib/acf-functions/services/map-fields/helpers/map-choice-object.ts

@@ -0,0 +1,20 @@
+import { ACFChoiceObject } from "@/acf-functions/types/components/field-props";
+
+export function mapChoiceObject(return_format: 'array' | 'label' | 'value', value?: string, choices?: Choices): ACFChoiceObject | string | undefined {
+    if (return_format === 'value') {
+        return value;
+    }
+    if (!choices) return;
+
+    const label = choices[value ?? ''];
+
+    if (return_format === 'array') {
+        const result: ACFChoiceObject = {
+            label: label,
+            value: value
+        }
+        return result;
+    } else if (return_format === 'label') {
+        return label;
+    }
+}

package/lib/acf-functions/services/map-fields/map-fields.ts

@@ -0,0 +1,359 @@
+import { unserialize } from "php-serialize";
+import { acfComponentAutoloader } from "../../core/acf-component-autoloader";
+import { ACFGoogleMapsObject, ACFIconObject, ACFLinkObject } from "@/acf-functions/types/components/field-props";
+import { mapChoiceObject } from "./helpers/map-choice-object";
+import { processURL } from "@/services/utilities/process-url";
+
+const components = await acfComponentAutoloader();
+
+/**
+ * Parses PHP serialized string into JavaScript object or array.
+ *
+ * @param {string} [string] - PHP serialized string.
+ * @returns {unknown[] | { [key: string]: unknown }} Parsed object or array.
+ */
+function parsePhp(string?: string): unknown[] | { [key: string]: unknown } {
+    return unserialize(string ?? 'a:0:{}') ?? [];
+}
+
+/**
+ * Gets array of object IDs from string value.
+ *
+ * @param {string} value - String value containing IDs.
+ * @param {boolean} multiple - Indicates if multiple IDs are expected.
+ * @returns {number[]} Array of parsed object IDs.
+ */
+function getObjectIDs(value: string, multiple: boolean): number[] {
+    if (multiple) {
+        const postValueArray = parsePhp(value);
+        if (!Array.isArray(postValueArray)) return [];
+
+        return postValueArray.map(Number).filter(Boolean);
+    } else {
+        return [Number(value) ?? 0]
+    }
+}
+
+/**
+ * Maps individual ACF field to corresponding value.
+ *
+ * @param {NextpressField} field - Field configuration.
+ * @param {ACFRawValues} rawValues - Raw values map.
+ * @returns {Promise<any>} Promise resolving to mapped value.
+ */
+export async function mapField(field: NextpressField, rawValues: ACFRawValues): Promise<any> {
+    /**
+     * Basic scalar values and strings.
+     * These are stored as simple strings in the database and require no complex parsing.
+    */
+    switch (field.type){
+        case 'color_picker':
+        case 'date_picker':
+        case 'date_time_picker':
+        case 'time_picker':
+        case 'email':
+        case 'password':
+        case 'text':
+        case 'textarea':
+        case 'oembed':
+        case 'wysiwyg':
+        case 'file':
+        case 'image':
+            return rawValues.get(field.name);
+
+        /**
+         * Numeric fields.
+         * Casts the raw string from the database into a strict JavaScript Number.
+         */
+        case 'number':
+        case 'range':
+            return Number(rawValues.get(field.name));
+
+        /**
+         * True/False boolean field.
+         * Converts the truthy/falsy raw string/number into a strict JavaScript boolean.
+         */
+        case 'true_false':
+            return !!rawValues.get(field.name);
+
+        /**
+         * Google Map field.
+         * Deserializes the PHP array containing map data (address, lat, lng) into a structured object.
+         */
+        case 'google_map':
+            const mapValue = parsePhp(rawValues.get(field.name));
+            if (Array.isArray(mapValue)) return;
+
+            const mapObject: ACFGoogleMapsObject = mapValue as ACFGoogleMapsObject;
+            return mapObject;
+
+        /**
+         * Icon Picker field.
+         * Deserializes the PHP array and respects the return format (either a raw string class or an object).
+         */
+        case 'icon_picker':
+            const iconValue = parsePhp(rawValues.get(field.name));
+            if (Array.isArray(iconValue)) return;
+
+            const iconObject: ACFIconObject = iconValue as ACFIconObject;
+            if (field.return_format === 'string') {
+                return iconObject.value;
+            } else {
+                return iconObject;
+            }
+
+        /**
+         * Button Group field.
+         * Maps the selected choice value to its corresponding label/array using the choice map.
+         */
+        case 'button_group':
+            return mapChoiceObject(field.return_format ?? 'value', rawValues.get(field.name));
+
+        /**
+         * Checkbox field.
+         * Deserializes the array of selected options and maps each one to the requested return format.
+         */
+        case 'checkbox':
+            const checkBoxValues = parsePhp(rawValues.get(field.name));
+            if (!Array.isArray(checkBoxValues)) return;
+
+            return checkBoxValues.map(value => mapChoiceObject(field.return_format ?? 'value', typeof value === 'string' ? value : undefined, field.choices));
+
+        /**
+         * Radio field.
+         * Maps a single selected choice using the field's available choices.
+         */
+        case 'radio':
+            return mapChoiceObject(field.return_format ?? 'value', rawValues.get(field.name), field.choices);
+
+        /**
+         * Select field.
+         * Handles both multi-select (deserializes array) and single-select (processes raw string),
+         * applying the requested return format.
+         */
+        case 'select':
+            if (field.multiple === 1) {
+                const selectValues = parsePhp(rawValues.get(field.name));
+                if (!Array.isArray(selectValues)) return;
+
+                return selectValues.map(value => mapChoiceObject(field.return_format ?? 'value', typeof value === 'string' ? value : undefined, field.choices));
+            } else {
+                return mapChoiceObject(field.return_format ?? 'value', rawValues.get(field.name), field.choices);
+            }
+
+        /**
+         * Gallery field.
+         * Deserializes the PHP array of image IDs or objects.
+         */
+        case 'gallery':
+            const galleryValues = parsePhp(rawValues.get(field.name));
+            if (!Array.isArray(galleryValues)) return;
+
+            return galleryValues;
+
+        /**
+         * Flexible Content field.
+         * Iterates over saved layout names, extracts the relevant prefixed sub-fields for each block,
+         * recursively maps those sub-fields, and binds the resolved data to the correct React component.
+         */
+        case 'flexible_content':
+            const layoutValues = parsePhp(rawValues.get(field.name));
+            if (!Array.isArray(layoutValues)) return;
+
+            const layouts = field.layouts;
+            const fcRawEntries = Array.from(rawValues.entries());
+
+            const promises = layoutValues.map(async (layoutValue, index) => {
+                const layout = layouts?.find(layout => layout.name === layoutValue);
+
+                const prefix = `${field.name}_${index}_`;
+                const prefixLength = prefix.length;
+
+                const component = components.find(comp => comp.layout.name === layout?.name);
+
+                const subFieldEntries = fcRawEntries
+                    .filter(([key]) => key.startsWith(prefix))
+                    .map(([key, value]) => [key.slice(prefixLength), value] as [string, any]);
+
+                const flexibleValues = new Map<string, any>(subFieldEntries);
+
+                const resolvedValues = await mapLayout(layout as any, flexibleValues);
+
+                return {
+                    Component: component?.Component,
+                    content: resolvedValues
+                };
+            });
+
+            return Promise.all(promises);
+
+        /**
+         * Group field.
+         * Strips the parent group prefix from the database keys and recursively maps the internal sub-fields.
+         */
+        case 'group':
+            const groupValues = new Map(
+                [...rawValues.entries()]
+                    .filter(([key]) => key.startsWith(field.name) && key !== field.name)
+                    .map(([key, value]) => {
+                        const newKey = key.replace(`${field.name}_`, '');
+                        return [newKey, value];
+                    })
+            );
+            return await mapLayout(field as any, groupValues);
+
+        /**
+         * Repeater field.
+         * Gets the total repeat count, then iterates to extract prefixed sub-fields for each row,
+         * mapping them recursively into an array of objects.
+         */
+        case 'repeater':
+            const repeaterRepeats = Number(rawValues.get(field.name)) || 0;
+            const repeaterResults = [];
+
+            const rRawEntries = Array.from(rawValues.entries());
+
+            for (let index = 0; index < repeaterRepeats; index++) {
+                const prefix = `${field.name}_${index}_`;
+                const prefixLength = prefix.length;
+
+                const subFieldEntries = rRawEntries
+                    .filter(([key]) => key.startsWith(prefix))
+                    .map(([key, value]) => [key.slice(prefixLength), value] as [string, any]);
+
+                const repeatValues = new Map<string, any>(subFieldEntries);
+
+                repeaterResults.push(mapLayout(field as any, repeatValues));
+            }
+
+            return Promise.all(repeaterResults);
+
+        /**
+         * Link field.
+         * Deserializes link properties (title, url, target) and returns either the raw URL string or a structured object.
+         */
+        case 'link':
+            const linkValue = parsePhp(rawValues.get(field.name));
+            if (Array.isArray(linkValue)) return;
+
+            const linkObject: ACFLinkObject = {
+                title: typeof linkValue.title === 'string' ? linkValue.title : '',
+                url: typeof linkValue.url === 'string' ? processURL(linkValue.url) : '',
+                target: typeof linkValue.target === 'string' ? linkValue.target : '',
+            }
+
+            if (field.return_format === 'url') {
+                return linkObject.url;
+            } else {
+                return linkObject
+            }
+
+        /**
+         * Page Link field.
+         * Retrieves internal post paths dynamically based on post ID, or falls back to standard external URLs.
+         */
+        case 'page_link':
+            if (field.multiple == 1) {
+                const pageLinkValue = parsePhp(rawValues.get(field.name));
+                if (!Array.isArray(pageLinkValue)) return;
+                const pageLinkIds = pageLinkValue.map(Number).filter(Boolean);
+
+                const posts = await getPosts(pageLinkIds);
+                const postPaths = new Map(posts.map(post => [post.ID, post.path]));
+
+                return pageLinkValue.map(page => postPaths.has(Number(page)) ? postPaths.get(Number(page)) : processURL(page as string));
+            } else {
+                const pageLinkValue = rawValues.get(field.name);
+                const pageLinkId = Number(rawValues.get(field.name));
+                if (!pageLinkValue) return;
+
+                return pageLinkId ? (await getPost(pageLinkId))?.path : processURL(pageLinkValue);
+            }
+
+        /**
+         * Post Object field.
+         * Returns either the raw Post IDs or uses the Entity Loader to fetch and return the complete post models.
+         */
+        case 'post_object':
+            const postObjectIds: number[] = getObjectIDs(rawValues.get(field.name) ?? '', !!field.multiple)
+
+            if (field.return_format === 'id') {
+                return field.multiple ? postObjectIds : postObjectIds[0];
+            } else {
+                postLoader.prime(postObjectIds);
+                const posts = await Promise.all(postObjectIds.map(id => getPost(id)));
+                return field.multiple ? posts : posts[0];
+            }
+
+        /**
+         * Relationship field.
+         * Extracts multiple selected IDs from a PHP array, returning them directly or fetching the associated post models.
+         */
+        case 'relationship':
+            const relationshipArray = parsePhp(rawValues.get(field.name));
+            if (!Array.isArray(relationshipArray)) return [];
+
+            const relationshipIds = relationshipArray.map(Number).filter(Boolean);
+
+            if (field.return_format === 'id') {
+                return relationshipIds;
+            } {
+                postLoader.prime(relationshipIds);
+                return await Promise.all(relationshipIds.map(id => getPost(id)));
+            }
+
+        /**
+         * Taxonomy field.
+         * Parses selected Term IDs and optionally fetches the complete taxonomy Term objects from the database.
+         */
+        case 'taxonomy':
+            const termObjectIds = parsePhp(rawValues.get(field.name))
+            if (!Array.isArray(termObjectIds)) return [];
+
+            const termIds = termObjectIds.map(Number).filter(Boolean);
+
+            if (field.return_format === 'id') {
+                return field.multiple ? termIds : termIds[0];
+            } else {
+                const terms = await Promise.all(termIds.map(id => getTerm(id)));
+                return field.multiple ? terms : terms[0];
+            }
+
+        /**
+         * User field.
+         * Extracts User IDs and returns either the raw IDs or fetches and returns the full User entity objects.
+         */
+        case 'user':
+            const userObjectIds: number[] = getObjectIDs(rawValues.get(field.name) ?? '', !!field.multiple)
+
+            if (field.return_format === 'id') {
+                return field.multiple ? userObjectIds : userObjectIds[0];
+            } else {
+                const users = await Promise.all(userObjectIds.map(id => getUser(id)));
+                return field.multiple ? users : users[0];
+            }
+        }
+
+    return undefined;
+}
+
+/**
+ * Maps layout configuration to values object.
+ *
+ * @param {NextpressLayout} layout - Layout configuration.
+ * @param {ACFRawValues} rawValues - Raw values map.
+ * @returns {Promise<{ [key: string]: any }>} Promise resolving to layout values object.
+ */
+export async function mapLayout(layout: NextpressLayout, rawValues: ACFRawValues)  {
+    const values: { [key: string]: any } = {};
+
+    for (const subField of layout.sub_fields) {
+        try {
+            values[subField.name] = await mapField(subField, rawValues)
+        } catch (error: any) {
+            console.warn('Failed to map sub field: ', subField.name, error.message);
+        }
+    }
+
+    return values;
+}

package/lib/acf-functions/types/acf-field-group.d.ts

@@ -0,0 +1,118 @@
+type TransformACFFieldGroup<T> = T extends any
+    ? Omit<T, 'key' | 'fields'> &
+        ('fields' extends keyof T ? { fields: NextpressField[] } : [])
+    : never;
+
+/** ACF Field Group without key constraints to allow key generation */
+type NextpressFieldGroup = TransformACFFieldGroup<ACFFieldGroup>
+
+/**
+ * Represents an Advanced Custom Fields (ACF) Field Group configuration.
+ */
+interface ACFFieldGroup {
+    /**
+     * Unique identifier for the field group with group_ prefix (e.g. 'group_abc123')
+     */
+    key: string
+    /**
+     * The title/name of this entity
+     */
+    title: string
+    /**
+     * Array of field definitions. If empty array, field group appears but contains no fields.
+     */
+    fields: ACFField[]
+    /**
+     * The order of this entity in the admin menu
+     */
+    menu_order?: number
+    /**
+     * [ACF] Whether this entity is active
+     */
+    active?: boolean
+    /**
+     * [ACF Export Only] Unix timestamp of last modification
+     */
+    modified?: number
+    /**
+     * Location rules determining where this field group appears. Array of rule groups (OR logic between groups, AND logic within groups). If omitted or empty, field group won't appear on any edit screens.
+     */
+    location?: ACFLocationGroup[]
+    /**
+     * Position of the field group on the edit screen
+     */
+    position?: "normal" | "side" | "acf_after_title"
+    /**
+     * Visual style of the field group metabox
+     */
+    style?: "default" | "seamless"
+    /**
+     * Placement of field labels relative to fields
+     */
+    label_placement?: "top" | "left"
+    /**
+     * Placement of field instructions
+     */
+    instruction_placement?: "label" | "field"
+    /**
+     * Screen elements to hide when this field group is displayed
+     */
+    hide_on_screen?: (
+        | "permalink"
+        | "the_content"
+        | "excerpt"
+        | "custom_fields"
+        | "discussion"
+        | "comments"
+        | "revisions"
+        | "slug"
+        | "author"
+        | "format"
+        | "page_attributes"
+        | "featured_image"
+        | "categories"
+        | "tags"
+        | "send-trackbacks"
+    )[]
+    /**
+     * Description of the field group
+     */
+    description?: string
+    /**
+     * Whether to expose this field group's fields in the REST API
+     */
+    show_in_rest?: boolean | number
+    /**
+     * Whether to expose this field group to AI integrations
+     */
+    allow_ai_access?: boolean | number
+    /**
+     * Description that helps AI integrations understand how to use this field group
+     */
+    ai_description?: string
+    /**
+     * Alternative display title for the field group
+     */
+    display_title?: string
+}
+
+/**
+ * Group of location rules (AND logic within group)
+ */
+type ACFLocationGroup = [ACFLocationRule, ...ACFLocationRule[]]
+
+interface ACFLocationRule {
+    /**
+     * The parameter to compare (e.g. 'post_type', 'page_template', 'user_role')
+     */
+    param: string
+    /**
+     * Comparison operator
+     */
+    operator: "==" | "!="
+    /**
+     * Value to compare against
+     */
+    value: string
+    [k: string]: unknown
+}