@jhits/plugin-blog 0.0.1

package/README.md

@@ -0,0 +1,216 @@
+# Blog Plugin - Block-Based Architecture
+
+A modern, modular Blog Plugin system with a Block-Based Architecture (similar to Notion or Gutenberg) where posts are stored as JSON arrays of "Blocks" rather than HTML blobs.
+
+## 🏗️ Architecture Overview
+
+### Core Principles
+
+1. **Block-Based Storage**: Posts are stored as structured JSON arrays of blocks
+2. **Headless Ready**: All data is saved as structured JSON, perfect for headless CMS usage
+3. **Extensible Registry**: Register new block types without refactoring core
+4. **Separation of Concerns**: Library components are decoupled from editor shell
+5. **Migration-Friendly**: Easy to convert legacy HTML/data to block format
+
+## 📁 Directory Structure
+
+```
+src/
+├── types/              # TypeScript definitions
+├── registry/           # Block Registry system
+├── state/              # State management (Context + Reducer)
+├── lib/                # Library components (decoupled)
+│   ├── blocks/        # Block rendering
+│   ├── utils/         # Utilities (slugify, etc.)
+│   └── migration/     # Legacy data mapper
+├── views/              # Editor views (to be implemented)
+├── components/         # Shared UI components (to be implemented)
+└── hooks/              # Custom hooks (to be implemented)
+```
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed structure.
+
+## 🧩 Block System
+
+### Default Block Types
+
+- **Heading** (`heading`) - H1-H6 headings
+- **Paragraph** (`paragraph`) - Text paragraphs
+- **Image** (`image`) - Single images with captions
+- **Gallery** (`gallery`) - Image galleries
+- **CTA** (`cta`) - Call-to-action blocks
+
+### Registering New Blocks
+
+```typescript
+import { blockRegistry } from '@jhits/plugin-blog';
+
+blockRegistry.register({
+    type: 'custom-block',
+    name: 'Custom Block',
+    description: 'My custom block',
+    defaultData: {
+        customField: '',
+    },
+    category: 'custom',
+});
+```
+
+## 🔄 State Management
+
+The editor uses React Context + Reducer pattern for state management:
+
+```typescript
+import { useEditor } from '@jhits/plugin-blog';
+
+function MyComponent() {
+    const { state, helpers } = useEditor();
+    
+    // Access state
+    const { blocks, title, slug } = state;
+    
+    // Use helpers
+    helpers.addBlock('paragraph');
+    helpers.updateBlock(blockId, { text: 'New text' });
+    helpers.save();
+}
+```
+
+### State Structure
+
+- `blocks`: Array of Block objects
+- `title`: Post title
+- `slug`: URL slug
+- `seo`: SEO metadata
+- `metadata`: Categories, tags, featured image
+- `status`: Publication status
+- `isDirty`: Has unsaved changes
+- `focusMode`: Editor focus mode
+
+## 📦 Library Components
+
+### Block Renderer
+
+Headless block rendering (decoupled from editor):
+
+```typescript
+import { BlocksRenderer } from '@jhits/plugin-blog/lib';
+
+<BlocksRenderer blocks={post.blocks} />
+```
+
+### Utilities
+
+```typescript
+import { slugify, generateSlugFromTitle, checkSlugCollision } from '@jhits/plugin-blog/lib';
+
+const slug = slugify('My Blog Post');
+const uniqueSlug = generateSlugFromTitle('My Post', existingSlugs);
+const { isCollision } = checkSlugCollision(slug, existingSlugs);
+```
+
+### Migration
+
+Convert legacy HTML to blocks:
+
+```typescript
+import { mapLegacyPostToBlogPost } from '@jhits/plugin-blog/lib/migration';
+
+const newPost = mapLegacyPostToBlogPost(legacyPost, {
+    defaultStatus: 'draft',
+    authorId: 'user-123',
+});
+```
+
+## 🎯 Core Views (To Be Implemented)
+
+1. **Canvas Editor** - Drag-and-drop block editor
+2. **Slug & SEO Manager** - URL and SEO management with collision detection
+3. **Preview Bridge** - Live preview of posts
+4. **Post Manager** - List view with filters and bulk actions
+
+## 🚀 Usage
+
+### Basic Setup
+
+```typescript
+import { EditorProvider } from '@jhits/plugin-blog';
+
+function BlogEditor() {
+    return (
+        <EditorProvider onSave={async (state) => {
+            // Save to API
+            await fetch('/api/blog/posts', {
+                method: 'POST',
+                body: JSON.stringify(state),
+            });
+        }}>
+            <CanvasEditor />
+        </EditorProvider>
+    );
+}
+```
+
+## 📝 Data Format
+
+### Block Structure
+
+```json
+{
+    "id": "block-123",
+    "type": "paragraph",
+    "data": {
+        "text": "This is a paragraph"
+    },
+    "meta": {
+        "order": 0
+    }
+}
+```
+
+### Post Structure
+
+```json
+{
+    "id": "post-123",
+    "title": "My Blog Post",
+    "slug": "my-blog-post",
+    "blocks": [...],
+    "seo": {
+        "title": "SEO Title",
+        "description": "Meta description"
+    },
+    "publication": {
+        "status": "published",
+        "date": "2024-01-01T00:00:00Z"
+    },
+    "metadata": {
+        "categories": ["tech"],
+        "tags": ["react", "typescript"]
+    }
+}
+```
+
+## 🔧 Extensibility
+
+The system is designed to be extended:
+
+1. **New Block Types**: Register via `blockRegistry.register()`
+2. **Custom Renderers**: Pass to `BlockRenderer` via `customRenderers` prop
+3. **Custom Actions**: Extend reducer with new action types
+4. **Migration Mappers**: Extend mapper for custom legacy formats
+
+## 📚 Next Steps
+
+1. Implement Canvas Editor with drag-and-drop
+2. Implement Slug & SEO Manager
+3. Implement Preview Bridge
+4. Implement Post Manager
+5. Add API routes for CRUD operations
+6. Add database integration
+
+## 📖 Documentation
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) - Detailed architecture documentation
+- [VIEWS.md](./Markdown/VIEWS.md) - Planned views and features
+

package/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "@jhits/plugin-blog",
+    "version": "0.0.1",
+    "description": "Professional blog management system for the JHITS ecosystem",
+    "publishConfig": {
+      "access": "public"
+    },
+    "main": "./src/index.tsx",
+    "types": "./src/index.tsx",
+    "exports": {
+      ".": {
+        "types": "./src/index.tsx",
+        "default": "./src/index.tsx"
+      },
+      "./server": {
+        "types": "./src/index.server.ts",
+        "default": "./src/index.server.ts"
+      }
+    },
+    "dependencies": {
+      "@jhits/plugin-core": "^0.0.1",
+      "@jhits/plugin-content": "^0.0.1",
+      "@jhits/plugin-images": "^0.0.1",
+      "bcrypt": "^6.0.0",
+      "framer-motion": "^12.23.26",
+      "lucide-react": "^0.562.0",
+      "mongodb": "^7.0.0",
+      "next-auth": "^4.24.13"
+    },
+    "peerDependencies": {
+      "next": ">=15.0.0",
+      "next-intl": ">=4.0.0",
+      "next-themes": ">=0.4.0",
+      "react": ">=18.0.0",
+      "react-dom": ">=18.0.0"
+    },
+    "devDependencies": {
+      "@tailwindcss/postcss": "^4",
+      "@types/bcrypt": "^6.0.0",
+      "@types/node": "^20.19.27",
+      "@types/react": "^19",
+      "@types/react-dom": "^19",
+      "eslint": "^9",
+      "eslint-config-next": "16.1.1",
+      "next": "16.1.1",
+      "next-intl": "4.6.1",
+      "next-themes": "0.4.6",
+      "react": "19.2.3",
+      "react-dom": "19.2.3",
+      "tailwindcss": "^4",
+      "typescript": "^5"
+    },
+    "files": [
+      "src",
+      "package.json"
+    ]
+  }

package/src/api/README.md

@@ -0,0 +1,224 @@
+# Blog API
+
+RESTful API handlers for blog posts, included in the `@jhits/plugin-blog` package.
+
+## Installation
+
+The API handlers are automatically available when you install `@jhits/plugin-blog`.
+
+## Setup
+
+### 1. Create API Route in Your App
+
+Create API routes in your Next.js app to mount the blog API handlers:
+
+**`src/app/api/blogs/route.ts`** - List and create blogs:
+```typescript
+import { NextRequest } from 'next/server';
+import { GET, POST, createBlogApiConfig } from '@jhits/plugin-blog/api';
+import clientPromise from '@/lib/mongodb';
+import { cookies } from 'next/headers';
+import jwt from 'jsonwebtoken';
+
+const JWT_SECRET = process.env.JWT_SECRET || 'secret';
+
+async function getUserId(req: NextRequest): Promise<string | null> {
+    try {
+        const cookieStore = await cookies();
+        const token = cookieStore.get('auth_token')?.value;
+        if (!token) return null;
+        const decoded = jwt.verify(token, JWT_SECRET) as { id: string };
+        return decoded.id;
+    } catch {
+        return null;
+    }
+}
+
+const config = createBlogApiConfig({
+    getDb: async () => clientPromise,
+    getUserId,
+    collectionName: 'blogs', // optional, defaults to 'blogs'
+});
+
+export async function GET(req: NextRequest) {
+    return GET(req, undefined, config);
+}
+
+export async function POST(req: NextRequest) {
+    return POST(req, undefined, config);
+}
+```
+
+**`src/app/api/blogs/[slug]/route.ts`** - Get, update, and delete by slug:
+```typescript
+import { NextRequest } from 'next/server';
+import { GET, PUT, DELETE, createBlogApiConfig } from '@jhits/plugin-blog/api';
+import clientPromise from '@/lib/mongodb';
+import { cookies } from 'next/headers';
+import jwt from 'jsonwebtoken';
+
+const JWT_SECRET = process.env.JWT_SECRET || 'secret';
+
+async function getUserId(req: NextRequest): Promise<string | null> {
+    try {
+        const cookieStore = await cookies();
+        const token = cookieStore.get('auth_token')?.value;
+        if (!token) return null;
+        const decoded = jwt.verify(token, JWT_SECRET) as { id: string };
+        return decoded.id;
+    } catch {
+        return null;
+    }
+}
+
+const config = createBlogApiConfig({
+    getDb: async () => clientPromise,
+    getUserId,
+    collectionName: 'blogs',
+});
+
+export async function GET(
+    req: NextRequest,
+    { params }: { params: Promise<{ slug: string }> }
+) {
+    return GET(req, { params }, config);
+}
+
+export async function PUT(
+    req: NextRequest,
+    { params }: { params: Promise<{ slug: string }> }
+) {
+    return PUT(req, { params }, config);
+}
+
+export async function DELETE(
+    req: NextRequest,
+    { params }: { params: Promise<{ slug: string }> }
+) {
+    return DELETE(req, { params }, config);
+}
+```
+
+## API Endpoints
+
+### GET /api/blogs
+List all blog posts.
+
+**Query Parameters:**
+- `limit` (number, default: 10) - Number of posts to return
+- `skip` (number, default: 0) - Number of posts to skip
+- `status` (string, optional) - Filter by status (`published`, `concept`, `draft`)
+- `admin` (boolean, default: false) - If true, returns all posts for authenticated user (including drafts)
+
+**Response:**
+```json
+{
+    "blogs": [...],
+    "total": 100
+}
+```
+
+### POST /api/blogs
+Create a new blog post.
+
+**Request Body:**
+```json
+{
+    "title": "My Blog Post",
+    "summary": "A brief summary",
+    "contentBlocks": [...],
+    "image": {
+        "src": "/uploads/image.jpg",
+        "alt": "Image alt text",
+        "brightness": 100,
+        "blur": 0
+    },
+    "categoryTags": {
+        "category": "Technology",
+        "tags": ["web", "development"]
+    },
+    "publicationData": {
+        "status": "concept" | "published",
+        "date": "2024-01-01T00:00:00.000Z"
+    },
+    "seo": {
+        "title": "SEO Title",
+        "description": "SEO Description",
+        "keywords": ["keyword1", "keyword2"],
+        "ogImage": "/uploads/og-image.jpg",
+        "canonicalUrl": "https://example.com/blog/my-post"
+    }
+}
+```
+
+**Response:**
+```json
+{
+    "message": "Draft saved successfully",
+    "blogId": "...",
+    "slug": "my-blog-post-draft-1234"
+}
+```
+
+### GET /api/blogs/[slug]
+Get a single blog post by slug.
+
+**Response:**
+```json
+{
+    "_id": "...",
+    "title": "My Blog Post",
+    "slug": "my-blog-post",
+    "contentBlocks": [...],
+    ...
+}
+```
+
+### PUT /api/blogs/[slug]
+Update a blog post by slug.
+
+**Request Body:** Same as POST /api/blogs
+
+**Response:**
+```json
+{
+    "message": "Blog updated successfully",
+    "slug": "updated-slug"
+}
+```
+
+### DELETE /api/blogs/[slug]
+Delete a blog post by slug.
+
+**Response:**
+```json
+{
+    "message": "Blog deleted successfully"
+}
+```
+
+## Security
+
+- All endpoints (except public GET) require authentication
+- Users can only access/modify their own posts
+- Published posts are visible to everyone
+- Drafts/concepts are only visible to the author
+
+## Error Responses
+
+All endpoints return standard HTTP status codes:
+- `200` - Success
+- `400` - Bad Request (validation errors)
+- `401` - Unauthorized (not authenticated)
+- `403` - Forbidden (not authorized)
+- `404` - Not Found
+- `500` - Internal Server Error
+
+Error response format:
+```json
+{
+    "error": "Error message",
+    "detail": "Detailed error information"
+}
+```
+

package/src/api/categories.ts

@@ -0,0 +1,43 @@
+/**
+ * Blog Categories API Handler
+ * GET /api/plugin-blog/categories - Get all unique categories
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { BlogApiConfig } from './handler';
+
+export async function GET(req: NextRequest, config: BlogApiConfig): Promise<NextResponse> {
+    try {
+        const dbConnection = await config.getDb();
+        const db = dbConnection.db();
+        const blogs = db.collection(config.collectionName || 'blogs');
+
+        // Get all unique categories from blog posts
+        const categories = await blogs.distinct('categoryTags.category');
+
+        // Also get categories from Hero blocks in contentBlocks
+        const heroBlocks = await blogs.aggregate([
+            { $unwind: '$contentBlocks' },
+            { $match: { 'contentBlocks.type': 'hero' } },
+            { $project: { category: '$contentBlocks.data.category' } },
+            { $match: { category: { $exists: true, $ne: null, $nin: [''] } } },
+            { $group: { _id: '$category' } },
+        ]).toArray();
+
+        const heroCategories = heroBlocks.map((block: any) => block._id);
+
+        // Combine and deduplicate
+        const allCategories = Array.from(
+            new Set([...categories.filter(Boolean), ...heroCategories.filter(Boolean)])
+        ).sort();
+
+        return NextResponse.json({ categories: allCategories });
+    } catch (err: any) {
+        console.error('[BlogAPI] Categories error:', err);
+        return NextResponse.json(
+            { error: 'Failed to fetch categories', detail: err.message },
+            { status: 500 }
+        );
+    }
+}
+

package/src/api/check-title.ts

@@ -0,0 +1,60 @@
+/**
+ * Blog Check Title API Handler
+ * GET /api/plugin-blog/check-title - Check if a blog title already exists
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { BlogApiConfig } from './handler';
+
+export async function GET(req: NextRequest, config: BlogApiConfig): Promise<NextResponse> {
+    try {
+        const url = new URL(req.url);
+        const title = url.searchParams.get('title');
+        const excludeSlug = url.searchParams.get('excludeSlug');
+
+        // If title is empty or too short, don't bother the database
+        if (!title || title.trim().length < 3) {
+            return NextResponse.json({ duplicate: false });
+        }
+
+        const dbConnection = await config.getDb();
+        const db = dbConnection.db();
+        const blogs = db.collection(config.collectionName || 'blogs');
+
+        /**
+         * We search for a title match using:
+         * 1. A case-insensitive regex (^ and $ ensure it's the exact full string)
+         * 2. An exclusion of the current slug (so editing an article doesn't flag itself)
+         */
+        const query: any = {
+            title: {
+                $regex: new RegExp(`^${title.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'i')
+            }
+        };
+
+        if (excludeSlug) {
+            query.slug = { $ne: excludeSlug };
+        }
+
+        const duplicate = await blogs.findOne(query);
+
+        if (duplicate) {
+            return NextResponse.json({
+                duplicate: true,
+                blog: {
+                    title: duplicate.title,
+                    slug: duplicate.slug
+                }
+            });
+        }
+
+        return NextResponse.json({ duplicate: false });
+    } catch (err: any) {
+        console.error('[BlogAPI] Check title error:', err);
+        return NextResponse.json(
+            { error: 'Internal server error', detail: err.message },
+            { status: 500 }
+        );
+    }
+}
+