@nextsparkjs/theme-default 0.1.0-beta.1

package/entities/pages/pages.config.ts

@@ -0,0 +1,94 @@
+/**
+ * Pages Entity Configuration
+ *
+ * Pages are builder-enabled entities that render at root URLs (e.g., /about, /contact).
+ * This configuration enables the WordPress-like page builder experience for content creation.
+ */
+
+import { FileText } from 'lucide-react'
+import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+import { pagesFields } from './pages.fields'
+
+export const pagesEntityConfig: EntityConfig = {
+  // ==========================================
+  // 1. BASIC IDENTIFICATION
+  // ==========================================
+  slug: 'pages',
+  enabled: true,
+
+  names: {
+    singular: 'page',
+    plural: 'Pages',
+  },
+
+  icon: FileText,
+  tableName: 'pages',
+
+  // ==========================================
+  // 2. ACCESS AND SCOPE CONFIGURATION
+  // ==========================================
+  access: {
+    public: true,    // Pages are public content
+    api: true,       // Has external API endpoints
+    metadata: false, // Pages don't use metadata system
+    shared: true,    // All authenticated users can see all pages
+    basePath: '/',   // Pages render at root: /about, /contact, etc.
+  },
+
+  // ==========================================
+  // 3. UI/UX FEATURES
+  // ==========================================
+  ui: {
+    dashboard: {
+      showInMenu: true,
+      showInTopbar: true,
+      filters: [
+        { field: 'status', type: 'multiSelect' },
+      ],
+    },
+    public: {
+      hasArchivePage: false, // Pages don't have an archive page
+      hasSinglePage: true,   // Individual pages render at /[slug]
+    },
+    features: {
+      searchable: true,
+      sortable: true,
+      filterable: true,
+      bulkOperations: true,
+      importExport: false,
+    },
+  },
+
+  // ==========================================
+  // 4. PERMISSIONS SYSTEM
+  // ==========================================
+  // Permissions are now centralized in permissions.config.ts
+  // See: contents/themes/default/permissions.config.ts -> entities.pages
+
+  // ==========================================
+  // 6. BUILDER CONFIGURATION
+  // ==========================================
+  builder: {
+    enabled: true,
+    sidebarFields: ['locale'], // Pages don't have extra sidebar fields beyond basic settings
+    seo: true, // Enable SEO fields panel in editor
+  },
+
+  // ==========================================
+  // 7. TAXONOMIES CONFIGURATION
+  // ==========================================
+  taxonomies: {
+    enabled: false, // Pages don't use taxonomies by default
+    types: [],
+  },
+
+  // ==========================================
+  // FIELDS
+  // ==========================================
+  fields: pagesFields,
+
+  // ==========================================
+  // METADATA
+  // ==========================================
+  source: 'theme',
+}

package/entities/pages/pages.fields.ts

@@ -0,0 +1,101 @@
+/**
+ * Pages Entity Fields Configuration
+ *
+ * Fields required for builder-enabled pages.
+ * Note: 'blocks' field is NOT in fields[] - it's managed by the builder view automatically.
+ */
+
+import type { EntityField } from '@nextsparkjs/core/lib/entities/types'
+
+export const pagesFields: EntityField[] = [
+  {
+    name: 'title',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Title',
+      description: 'Page title',
+      placeholder: 'Enter page title...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 1,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'slug',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Slug',
+      description: 'URL-friendly identifier',
+      placeholder: 'page-slug',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 2,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'status',
+    type: 'select',
+    required: true,
+    defaultValue: 'draft',
+    options: [
+      { value: 'draft', label: 'Draft' },
+      { value: 'published', label: 'Published' },
+      { value: 'scheduled', label: 'Scheduled' },
+      { value: 'archived', label: 'Archived' },
+    ],
+    display: {
+      label: 'Status',
+      description: 'Publication status',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 3,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      filterable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'locale',
+    type: 'select',
+    required: true,
+    defaultValue: 'en',
+    options: [
+      { value: 'en', label: 'English' },
+      { value: 'es', label: 'Español' },
+    ],
+    display: {
+      label: 'Locale',
+      description: 'Page language',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 4,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      filterable: true,
+      readOnly: false,
+    },
+  },
+  // Note: SEO fields (seoTitle, seoDescription, etc.) are managed by the builder SEO panel
+  // Note: 'blocks' field is a system field for builder-enabled entities - NOT defined here
+]

package/entities/pages/pages.service.ts

@@ -0,0 +1,290 @@
+/**
+ * Pages Service
+ *
+ * Provides data access methods for pages, separating public queries
+ * (without RLS) from authenticated queries (with RLS).
+ *
+ * @module PagesService
+ */
+
+import { query, queryOne, queryOneWithRLS } from '@nextsparkjs/core/lib/db'
+import type {
+  PagePublic,
+  PageMetadata,
+  PageListOptions,
+  PageListResult,
+  Block,
+} from './pages.types'
+
+// Database row type for page
+interface DbPage {
+  id: string
+  slug: string
+  title: string
+  blocks: Block[]
+  locale: string
+  status: string
+  createdAt: string
+}
+
+// Database row type for metadata query
+interface DbPageMetadata {
+  title: string
+  seoTitle: string | null
+  seoDescription: string | null
+  ogImage: string | null
+}
+
+export class PagesService {
+  // ============================================
+  // PUBLIC METHODS (sin RLS)
+  // ============================================
+
+  /**
+   * Get a published page by slug
+   *
+   * Fetches the full page data including blocks.
+   * Only returns published pages.
+   *
+   * @param slug - Page slug
+   * @param locale - Optional locale filter (defaults to 'en')
+   * @returns Page data or null if not found/not published
+   *
+   * @example
+   * const page = await PagesService.getPublishedBySlug('about')
+   * if (!page) notFound()
+   */
+  static async getPublishedBySlug(
+    slug: string,
+    locale: string = 'en'
+  ): Promise<PagePublic | null> {
+    try {
+      if (!slug || slug.trim() === '') {
+        throw new Error('Page slug is required')
+      }
+
+      const page = await queryOne<DbPage>(
+        `
+        SELECT
+          id,
+          slug,
+          title,
+          blocks,
+          locale,
+          status,
+          "createdAt"
+        FROM pages
+        WHERE slug = $1 AND status = 'published' AND locale = $2
+        `,
+        [slug, locale]
+      )
+
+      if (!page) {
+        return null
+      }
+
+      return {
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        blocks: page.blocks,
+        locale: page.locale,
+      }
+    } catch (error) {
+      console.error('PagesService.getPublishedBySlug error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch page'
+      )
+    }
+  }
+
+  /**
+   * Get page metadata for SEO/head tags
+   *
+   * Lightweight query that only fetches SEO-related fields.
+   * Used in generateMetadata for better performance.
+   *
+   * @param slug - Page slug
+   * @param locale - Optional locale filter (defaults to 'en')
+   * @returns Metadata or null if not found/not published
+   *
+   * @example
+   * const metadata = await PagesService.getPublishedMetadata('about')
+   * return { title: metadata?.seoTitle || metadata?.title }
+   */
+  static async getPublishedMetadata(
+    slug: string,
+    locale: string = 'en'
+  ): Promise<PageMetadata | null> {
+    try {
+      if (!slug || slug.trim() === '') {
+        throw new Error('Page slug is required')
+      }
+
+      const result = await query<DbPageMetadata>(
+        `
+        SELECT
+          title,
+          "seoTitle",
+          "seoDescription",
+          "ogImage"
+        FROM pages
+        WHERE slug = $1 AND status = 'published' AND locale = $2
+        `,
+        [slug, locale]
+      )
+
+      if (result.rows.length === 0) {
+        return null
+      }
+
+      const page = result.rows[0]
+
+      return {
+        title: page.title,
+        seoTitle: page.seoTitle ?? undefined,
+        seoDescription: page.seoDescription ?? undefined,
+        ogImage: page.ogImage ?? undefined,
+      }
+    } catch (error) {
+      console.error('PagesService.getPublishedMetadata error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch page metadata'
+      )
+    }
+  }
+
+  /**
+   * List published pages with pagination
+   *
+   * @param options - List options (limit, offset, locale, orderBy, orderDir)
+   * @returns Object with pages array and total count
+   *
+   * @example
+   * const { pages, total } = await PagesService.listPublished({ limit: 10 })
+   */
+  static async listPublished(
+    options: PageListOptions = {}
+  ): Promise<PageListResult> {
+    try {
+      const {
+        limit = 10,
+        offset = 0,
+        locale = 'en',
+        orderBy = 'createdAt',
+        orderDir = 'desc',
+      } = options
+
+      // Validate orderBy to prevent SQL injection
+      const validOrderBy = ['createdAt', 'title'].includes(orderBy) ? orderBy : 'createdAt'
+      const validOrderDir = orderDir === 'asc' ? 'ASC' : 'DESC'
+      const orderColumn = validOrderBy === 'createdAt' ? '"createdAt"' : 'title'
+
+      // Get total count
+      const countResult = await query<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM pages WHERE status = 'published' AND locale = $1`,
+        [locale]
+      )
+      const total = parseInt(countResult.rows[0]?.count || '0', 10)
+
+      // Get pages
+      const pagesResult = await query<DbPage>(
+        `
+        SELECT
+          id,
+          slug,
+          title,
+          blocks,
+          locale,
+          status,
+          "createdAt"
+        FROM pages
+        WHERE status = 'published' AND locale = $1
+        ORDER BY ${orderColumn} ${validOrderDir}
+        LIMIT $2 OFFSET $3
+        `,
+        [locale, limit, offset]
+      )
+
+      const pages: PagePublic[] = pagesResult.rows.map((page) => ({
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        blocks: page.blocks,
+        locale: page.locale,
+      }))
+
+      return { pages, total }
+    } catch (error) {
+      console.error('PagesService.listPublished error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to list pages'
+      )
+    }
+  }
+
+  // ============================================
+  // AUTHENTICATED METHODS (con RLS)
+  // ============================================
+
+  /**
+   * Get a page by ID (authenticated)
+   *
+   * For dashboard/admin views. Respects RLS policies.
+   *
+   * @param id - Page ID
+   * @param userId - Current user ID for RLS
+   * @returns Page data or null if not found/not authorized
+   *
+   * @example
+   * const page = await PagesService.getById('page-uuid', currentUserId)
+   */
+  static async getById(
+    id: string,
+    userId: string
+  ): Promise<PagePublic | null> {
+    try {
+      if (!id || id.trim() === '') {
+        throw new Error('Page ID is required')
+      }
+
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const page = await queryOneWithRLS<DbPage>(
+        `
+        SELECT
+          id,
+          slug,
+          title,
+          blocks,
+          locale,
+          status,
+          "createdAt"
+        FROM pages
+        WHERE id = $1
+        `,
+        [id],
+        userId
+      )
+
+      if (!page) {
+        return null
+      }
+
+      return {
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        blocks: page.blocks,
+        locale: page.locale,
+      }
+    } catch (error) {
+      console.error('PagesService.getById error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch page'
+      )
+    }
+  }
+}

package/entities/pages/pages.types.ts

@@ -0,0 +1,124 @@
+/**
+ * Pages Service Types
+ *
+ * Type definitions for the PagesService.
+ * Separates public types (for rendering) from internal types.
+ *
+ * @module PagesTypes
+ */
+
+/**
+ * Block structure for page builder content
+ */
+export interface Block {
+  id: string
+  blockSlug: string
+  props: Record<string, unknown>
+}
+
+/**
+ * Page data for public rendering
+ * Includes blocks for full page display
+ */
+export interface PagePublic {
+  id: string
+  slug: string
+  title: string
+  blocks: Block[]
+  locale: string
+}
+
+/**
+ * Lightweight page metadata for SEO/head tags
+ * Does not include blocks
+ */
+export interface PageMetadata {
+  title: string
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+}
+
+/**
+ * Options for listing published pages
+ */
+export interface PageListOptions {
+  limit?: number
+  offset?: number
+  locale?: string
+  orderBy?: 'createdAt' | 'title'
+  orderDir?: 'asc' | 'desc'
+}
+
+/**
+ * Result of listing pages with pagination
+ */
+export interface PageListResult {
+  pages: PagePublic[]
+  total: number
+}
+
+// ============================================
+// MANAGEMENT TYPES (for authenticated CRUD)
+// ============================================
+
+/**
+ * Full page data including status and SEO fields
+ * Used for dashboard/admin operations
+ */
+export interface PageFull extends PagePublic {
+  status: 'draft' | 'published'
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * Data for creating a new page
+ */
+export interface PageCreateData {
+  slug: string
+  title: string
+  blocks?: Block[]
+  locale?: string
+  status?: 'draft' | 'published'
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+  teamId: string
+}
+
+/**
+ * Data for updating a page (metadata only, not blocks)
+ */
+export interface PageUpdateData {
+  slug?: string
+  title?: string
+  status?: 'draft' | 'published'
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+}
+
+/**
+ * Options for listing pages in management context
+ */
+export interface PageManagementListOptions {
+  limit?: number
+  offset?: number
+  locale?: string
+  status?: 'draft' | 'published' | 'all'
+  orderBy?: 'createdAt' | 'updatedAt' | 'title'
+  orderDir?: 'asc' | 'desc'
+  teamId?: string
+}
+
+/**
+ * Result of listing pages in management context
+ */
+export interface PageManagementListResult {
+  pages: PageFull[]
+  total: number
+}

package/entities/posts/components/post-header.tsx

@@ -0,0 +1,97 @@
+import { Badge } from '@nextsparkjs/core/components/ui/badge'
+import Image from 'next/image'
+
+interface Category {
+  id: string
+  name: string
+  color?: string
+}
+
+interface PostHeaderProps {
+  post: {
+    title: string
+    excerpt?: string
+    featuredImage?: string
+    createdAt: string
+    categories?: Category[]
+  }
+}
+
+export function PostHeader({ post }: PostHeaderProps) {
+  return (
+    <div className="w-full" data-cy="post-header">
+      {/* Featured Image */}
+      {post.featuredImage && (
+        <div className="relative w-full h-[400px] md:h-[500px] mb-8" data-cy="post-featured-image-display">
+          <Image
+            src={post.featuredImage}
+            alt={post.title}
+            fill
+            className="object-cover rounded-lg"
+            priority
+          />
+        </div>
+      )}
+
+      {/* Post Meta */}
+      <div className="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8 mb-8">
+        {/* Categories */}
+        {post.categories && post.categories.length > 0 && (
+          <div className="flex gap-2 mb-4" data-cy="post-categories-display">
+            {post.categories.map((category) => (
+              <Badge
+                key={category.id}
+                variant="outline"
+                style={{
+                  backgroundColor: category.color ? `${category.color}20` : undefined,
+                  borderColor: category.color || undefined,
+                  color: category.color || undefined,
+                }}
+              >
+                {category.name}
+              </Badge>
+            ))}
+          </div>
+        )}
+
+        {/* Title */}
+        <h1
+          className="text-4xl md:text-5xl font-bold text-foreground mb-4"
+          data-cy="post-title"
+        >
+          {post.title}
+        </h1>
+
+        {/* Excerpt */}
+        {post.excerpt && (
+          <p
+            className="text-xl text-muted-foreground mb-4"
+            data-cy="post-excerpt"
+          >
+            {post.excerpt}
+          </p>
+        )}
+
+        {/* Date - using suppressHydrationWarning to prevent server/client mismatch */}
+        <div className="flex items-center gap-4 text-sm text-muted-foreground">
+          <time
+            dateTime={new Date(post.createdAt).toISOString()}
+            suppressHydrationWarning
+          >
+            {new Date(post.createdAt).toLocaleDateString('en-US', {
+              year: 'numeric',
+              month: 'long',
+              day: 'numeric',
+              timeZone: 'UTC',
+            })}
+          </time>
+        </div>
+      </div>
+
+      {/* Separator */}
+      <div className="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8">
+        <hr className="border-border mb-8" />
+      </div>
+    </div>
+  )
+}