@nextsparkjs/theme-blog 0.1.0-beta.17 → 0.1.0-beta.170

package/entities/categories/api/presets.ts

@@ -0,0 +1,67 @@
+/**
+ * API Presets for Categories Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage blog categories for organizing posts',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Categories',
+      description: 'Get all categories with pagination',
+      method: 'GET',
+      params: {
+        limit: 50
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'search-by-name',
+      title: 'Search by Name',
+      description: 'Search categories by name',
+      method: 'GET',
+      params: {
+        search: '{{name}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'create-category',
+      title: 'Create Category',
+      description: 'Create a new category',
+      method: 'POST',
+      payload: {
+        name: 'New Category',
+        slug: 'new-category',
+        description: 'Category description'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'update-category',
+      title: 'Update Category',
+      description: 'Update an existing category',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        name: '{{name}}',
+        description: '{{description}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-category',
+      title: 'Delete Category',
+      description: 'Delete a category record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/entities/posts/api/docs.md

@@ -0,0 +1,174 @@
+# Posts API
+
+Manage blog posts with content builder, featured images, categories, and publication workflow.
+
+## Overview
+
+The Posts API allows you to create, read, update, and delete blog posts. Posts support a flexible content builder system, category organization, and a draft-to-published workflow.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+**Note:** For public access to published posts, use the [Public Posts API](/api/v1/theme/blog/posts/public) instead.
+
+## Endpoints
+
+### List Posts
+`GET /api/v1/posts`
+
+Returns a paginated list of posts.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `status` (string, optional): Filter by status (draft, published)
+- `featured` (boolean, optional): Filter by featured flag
+- `search` (string, optional): Search by title, excerpt, content
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "post_abc123",
+      "title": "Getting Started with Next.js",
+      "slug": "getting-started-with-nextjs",
+      "excerpt": "A comprehensive guide to building modern web apps",
+      "content": "[{\"type\":\"text\",\"content\":\"...\"}]",
+      "featuredImage": "https://example.com/image.jpg",
+      "featured": true,
+      "status": "published",
+      "publishedAt": "2024-01-15T10:30:00Z",
+      "createdAt": "2024-01-10T08:00:00Z",
+      "updatedAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 25,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Post
+`GET /api/v1/posts/[id]`
+
+Returns a single post by ID.
+
+### Create Post
+`POST /api/v1/posts`
+
+Create a new blog post.
+
+**Request Body:**
+```json
+{
+  "title": "My New Post",
+  "slug": "my-new-post",
+  "excerpt": "A brief description of the post",
+  "content": "[{\"type\":\"text\",\"content\":\"Post content here\"}]",
+  "featuredImage": "https://example.com/image.jpg",
+  "featured": false,
+  "status": "draft"
+}
+```
+
+### Update Post
+`PATCH /api/v1/posts/[id]`
+
+Update an existing post. Supports partial updates.
+
+### Publish Post
+`PATCH /api/v1/posts/[id]`
+
+Publish a draft post by setting status and publishedAt.
+
+**Request Body:**
+```json
+{
+  "status": "published",
+  "publishedAt": "2024-01-15T10:30:00Z"
+}
+```
+
+### Delete Post
+`DELETE /api/v1/posts/[id]`
+
+Delete a post record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | text | Yes | Post title |
+| slug | text | Yes | URL-friendly slug (auto-generated if not provided) |
+| excerpt | text | No | Brief description for previews |
+| content | json | No | Page builder content blocks |
+| featuredImage | url | No | Featured image URL |
+| featured | boolean | No | Whether post is featured. Default: false |
+| status | select | No | Status: draft, published. Default: draft |
+| publishedAt | datetime | No | Publication date/time |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Content Builder
+
+Posts use a flexible content builder system. The `content` field stores an array of content blocks in JSON format:
+
+```json
+[
+  {
+    "type": "text",
+    "content": "Paragraph content here..."
+  },
+  {
+    "type": "heading",
+    "level": 2,
+    "content": "Section Title"
+  },
+  {
+    "type": "image",
+    "src": "https://example.com/image.jpg",
+    "alt": "Image description"
+  }
+]
+```
+
+## Categories
+
+Posts can be organized into categories using a many-to-many relationship. Categories are managed via the `/api/v1/categories` endpoint and linked to posts through a pivot table.
+
+To filter posts by category, use the Public Posts API with the `category` query parameter.
+
+## Features
+
+- **Searchable**: title, excerpt, content
+- **Sortable**: Most fields
+- **Public Access**: Published posts available via public API
+- **Metadata**: Supported
+
+## Permissions
+
+- **Create/Update/Delete**: Owner only (single-user blog mode)
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Post doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Categories](/api/v1/categories)** - Post categorization
+- **[Public Posts](/api/v1/theme/blog/posts/public)** - Public feed (no auth required)
+- **[Authors](/api/v1/theme/blog/authors)** - Author profiles

package/entities/posts/api/presets.ts

@@ -0,0 +1,137 @@
+/**
+ * API Presets for Posts Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage blog posts with content builder and publication workflow',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Posts',
+      description: 'Get all posts with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-published',
+      title: 'List Published Posts',
+      description: 'Get all published posts',
+      method: 'GET',
+      params: {
+        status: 'published'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-drafts',
+      title: 'List Draft Posts',
+      description: 'Get all draft posts',
+      method: 'GET',
+      params: {
+        status: 'draft'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-featured',
+      title: 'List Featured Posts',
+      description: 'Get all featured posts',
+      method: 'GET',
+      params: {
+        featured: 'true'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'search-by-title',
+      title: 'Search by Title',
+      description: 'Search posts by title',
+      method: 'GET',
+      params: {
+        search: '{{title}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'create-draft',
+      title: 'Create Draft Post',
+      description: 'Create a new draft post',
+      method: 'POST',
+      payload: {
+        title: 'New Post Title',
+        slug: 'new-post-title',
+        excerpt: 'Brief description of the post',
+        status: 'draft'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'publish-post',
+      title: 'Publish Post',
+      description: 'Publish a draft post',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: 'published',
+        publishedAt: '{{publishedAt}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'unpublish-post',
+      title: 'Unpublish Post',
+      description: 'Revert a post to draft',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: 'draft'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'set-featured',
+      title: 'Set as Featured',
+      description: 'Mark a post as featured',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        featured: true
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'update-content',
+      title: 'Update Content',
+      description: 'Update post content blocks',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        content: '{{content}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-post',
+      title: 'Delete Post',
+      description: 'Delete a post record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/lib/selectors.ts

@@ -9,8 +9,7 @@
  * - Cypress tests (via tests/cypress/src/selectors.ts)
  */
 
-import { createSelectorHelpers } from '@nextsparkjs/core/lib/test/selector-factory'
-import { CORE_SELECTORS } from '@nextsparkjs/core/lib/test/core-selectors'
+import { createSelectorHelpers, CORE_SELECTORS } from '@nextsparkjs/core/selectors'
 
 // =============================================================================
 // BLOCK SELECTORS
@@ -175,5 +174,5 @@ export const entitySelectors = helpers.entitySelectors
 export type ThemeSelectorsType = typeof THEME_SELECTORS
 export type BlockSelectorsType = typeof BLOCK_SELECTORS
 export type EntitySelectorsType = typeof ENTITY_SELECTORS
-export type { Replacements } from '@nextsparkjs/core/lib/test/selector-factory'
+export type { Replacements } from '@nextsparkjs/core/selectors'
 export { CORE_SELECTORS }

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@nextsparkjs/theme-blog",
-  "version": "0.1.0-beta.17",
+  "version": "0.1.0-beta.170",
   "private": false,
   "type": "module",
   "main": "./config/theme.config.ts",
   "requiredPlugins": [],
   "dependencies": {},
   "peerDependencies": {
+    "@nextsparkjs/core": "*",
+    "@nextsparkjs/testing": "*",
     "lucide-react": "^0.539.0",
     "next": "^15.0.0",
     "next-intl": "^4.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "zod": "^4.0.0",
-    "@nextsparkjs/core": "0.1.0-beta.17"
+    "zod": "^4.0.0"
   },
   "nextspark": {
     "type": "theme",

package/styles/globals.css

@@ -3,8 +3,41 @@
  *
  * Warm amber/orange palette with editorial typography.
  * Fonts: Oxanium (sans), Merriweather (serif), Fira Code (mono)
+ *
+ * ÚNICA FUENTE DE VERDAD para estilos del theme.
+ * Editar este archivo para customizar el design system.
  */
 
+/* =============================================
+   IMPORTS
+   ============================================= */
+@import "tailwindcss";
+
+/* =============================================
+   TAILWIND v4 DARK MODE CONFIGURATION
+
+   Por defecto Tailwind v4 usa @media (prefers-color-scheme: dark)
+   para las variantes dark:. Esto causa problemas porque:
+   - next-themes usa la clase .dark en el HTML
+   - El sistema operativo puede tener dark mode aunque la app use light
+
+   Esta configuración hace que Tailwind use el selector de clase .dark
+   en lugar de la media query, sincronizándose con next-themes.
+   ============================================= */
+@custom-variant dark (&:where(.dark, .dark *));
+
+@plugin "@tailwindcss/container-queries";
+@import "@nextsparkjs/core/styles/ui.css";
+@import "@nextsparkjs/core/styles/utilities.css";
+@import "@nextsparkjs/core/styles/docs.css";
+@source "../../../**/*.{js,ts,jsx,tsx}";
+/* Core package: monorepo (short path) + npm projects (long path) */
+@source "../node_modules/@nextsparkjs/core/dist/**/*.js";
+@source "../../../../node_modules/@nextsparkjs/core/dist/**/*.js";
+
+/* =============================================
+   BLOG THEME - LIGHT MODE
+   ============================================= */
 :root {
     --background: oklch(0.9885 0.0057 84.5659);
     --foreground: oklch(0.3660 0.0251 49.6085);
@@ -152,6 +185,18 @@
     --shadow-2xl: var(--shadow-2xl);
 }
 
+/* =============================================
+   BASE STYLES
+   ============================================= */
+* {
+  border-color: var(--border);
+}
+
+body {
+  background-color: var(--background);
+  color: var(--foreground);
+}
+
 /* ============================================================================
    TYPOGRAPHY
    ============================================================================ */

package/tests/cypress/e2e/README.md

@@ -0,0 +1,170 @@
+# Blog Theme - E2E Testing Suite
+
+## Overview
+
+Complete E2E testing infrastructure for the Blog theme. The blog theme operates in **single-user mode** where each user owns their own isolated blog without team collaboration.
+
+## Test Status: ✅ All Tests Passing (52/52)
+
+| Test File | Tests | Status |
+|-----------|-------|--------|
+| `categories/categories-crud.cy.ts` | 9 | ✅ Passing |
+| `posts/posts-crud.cy.ts` | 16 | ✅ Passing |
+| `posts/posts-editor.cy.ts` | 19 | ✅ Passing |
+| `posts/posts-status-workflow.cy.ts` | 8 | ✅ Passing |
+| **Total** | **52** | **100%** |
+
+## Test Structure
+
+```
+test/cypress/e2e/themes/blog/
+├── posts/
+│   ├── posts-crud.cy.ts           # Full CRUD operations (16 tests)
+│   ├── posts-status-workflow.cy.ts # Publish/Unpublish workflow (8 tests)
+│   └── posts-editor.cy.ts         # WYSIWYG editor tests (19 tests)
+├── categories/
+│   └── categories-crud.cy.ts      # Standard CRUD (9 tests)
+└── README.md                      # This file
+```
+
+## Test Users
+
+All blog theme tests use isolated blog author accounts:
+
+| Author | Email | Description |
+|--------|-------|-------------|
+| **Marcos** (Primary) | `blog_author_marcos@nextspark.dev` | Main test author |
+| Lucia | `blog_author_lucia@nextspark.dev` | Lifestyle blog author |
+| Carlos | `blog_author_carlos@nextspark.dev` | Finance blog author |
+
+**Password for all users:** `Test1234`
+
+## POM Classes
+
+Blog theme POM classes are located at `test/cypress/src/classes/themes/blog/`:
+
+| Class | Description |
+|-------|-------------|
+| `PostsList.js` | Posts list page interactions (filters, views, actions) |
+| `PostEditor.js` | Create/Edit post pages (supports both modes) |
+| `WysiwygEditor.js` | Rich text editor component |
+| `FeaturedImageUpload.js` | Image upload component |
+| `session-helpers.ts` | Blog-specific login helpers |
+
+## Session Helpers
+
+Blog theme has its own session helpers for isolated login:
+
+```typescript
+import { loginAsBlogAuthor, BLOG_USERS } from '../../../src/session-helpers'
+
+// Login as default author (Marcos)
+loginAsBlogAuthor('MARCOS')
+
+// Login as specific author
+loginAsBlogAuthor('LUCIA')
+loginAsBlogAuthor('CARLOS')
+```
+
+## Running Tests
+
+```bash
+# Run all blog theme tests
+npx cypress run --spec "test/cypress/e2e/themes/blog/**/*.cy.ts"
+
+# Run only posts tests
+npx cypress run --spec "test/cypress/e2e/themes/blog/posts/**/*.cy.ts"
+
+# Run only categories tests
+npx cypress run --spec "test/cypress/e2e/themes/blog/categories/**/*.cy.ts"
+
+# Run with blog theme active
+NEXT_PUBLIC_ACTIVE_THEME=blog npx cypress run --spec "test/cypress/e2e/themes/blog/**/*.cy.ts"
+```
+
+## Data-cy Selectors
+
+### Posts List Page
+
+```
+[data-cy="posts-list-container"]
+[data-cy="posts-stat-all|published|draft|scheduled"]
+[data-cy="posts-search-input"]
+[data-cy="posts-sort-select"]
+[data-cy="posts-view-table|grid"]
+[data-cy="posts-row-{id}"]
+[data-cy="posts-title-{id}"]
+[data-cy="posts-status-{id}"]
+[data-cy="posts-actions-{id}"]
+[data-cy="posts-edit-{id}"]
+[data-cy="posts-publish-{id}"]
+[data-cy="posts-delete-{id}"]
+[data-cy="posts-create-button"]
+[data-cy="posts-delete-dialog"]
+[data-cy="posts-delete-confirm|cancel"]
+```
+
+### Post Editor (Create/Edit)
+
+```
+[data-cy="post-{mode}-container"]       # mode = create|edit
+[data-cy="post-{mode}-header"]
+[data-cy="post-{mode}-back"]
+[data-cy="post-{mode}-status"]
+[data-cy="post-{mode}-autosaved"]
+[data-cy="post-{mode}-save"]
+[data-cy="post-{mode}-publish"]
+[data-cy="post-{mode}-unpublish"]       # edit only
+[data-cy="post-{mode}-title"]
+[data-cy="post-{mode}-content"]
+[data-cy="post-{mode}-settings"]
+[data-cy="post-{mode}-status-select"]
+[data-cy="post-{mode}-slug"]
+[data-cy="post-{mode}-excerpt"]
+[data-cy="post-{mode}-featured-image"]
+[data-cy="post-{mode}-featured-toggle"]
+[data-cy="post-{mode}-delete"]          # edit only
+[data-cy="post-{mode}-delete-dialog"]
+```
+
+### WYSIWYG Editor
+
+```
+[data-cy="wysiwyg-container"]
+[data-cy="wysiwyg-toolbar"]
+[data-cy="wysiwyg-content"]
+[data-cy="wysiwyg-preview"]
+[data-cy="wysiwyg-preview-toggle"]
+[data-cy="wysiwyg-{command}"]           # undo, redo, bold, italic, etc.
+[data-cy="wysiwyg-formatBlock-{tag}"]   # h1, h2, h3, blockquote, pre
+[data-cy="wysiwyg-wordcount"]
+```
+
+### Featured Image Upload
+
+```
+[data-cy="featured-image-container"]
+[data-cy="featured-image-dropzone"]
+[data-cy="featured-image-input"]
+[data-cy="featured-image-preview"]
+[data-cy="featured-image-remove"]
+[data-cy="featured-image-loading"]
+[data-cy="featured-image-error"]
+```
+
+## Dependencies
+
+- Generic POM classes from `test/cypress/src/classes/components/entities/`
+- DevKeyring for authentication: `test/cypress/src/classes/components/auth/DevKeyring.js`
+- Core session helpers (NOT modified): `test/cypress/src/helpers/session-helpers.ts`
+
+## Notes
+
+- Blog theme uses **custom UI** for posts (PostsList, PostEditor) unlike generic EntityList/EntityForm
+- Categories use the **generic EntityList/EntityForm** pattern
+- All tests use **cy.session()** for cached authentication (3-5x faster)
+- Tests are designed to be **self-contained** and create their own test data
+
+---
+
+**Last Updated:** 2025-12-04