@jhits/plugin-blog 0.0.1

package/src/state/types.ts

@@ -0,0 +1,160 @@
+/**
+ * State Management Types
+ * Types for the editor state management system
+ */
+
+import { Block } from '../types/block';
+import { BlogPost, PostStatus, SEOMetadata, PostMetadata } from '../types/post';
+
+/**
+ * Editor State
+ * Represents the current state of the editor
+ */
+export interface EditorState {
+    /** Array of blocks in the editor */
+    blocks: Block[];
+    
+    /** Post title */
+    title: string;
+    
+    /** Post slug */
+    slug: string;
+    
+    /** SEO metadata */
+    seo: SEOMetadata;
+    
+    /** Post metadata */
+    metadata: PostMetadata;
+    
+    /** Publication status */
+    status: PostStatus;
+    
+    /** Whether the post has unsaved changes */
+    isDirty: boolean;
+    
+    /** Whether the editor is in focus mode */
+    focusMode: boolean;
+    
+    /** Currently selected block ID */
+    selectedBlockId: string | null;
+    
+    /** Currently dragged block ID */
+    draggedBlockId: string | null;
+    
+    /** Post ID (if editing existing post) */
+    postId: string | null;
+}
+
+/**
+ * Editor Actions
+ * Actions that can be dispatched to modify editor state
+ */
+export type EditorAction =
+    | { type: 'SET_BLOCKS'; payload: Block[] }
+    | { type: 'ADD_BLOCK'; payload: { block: Block; index?: number; containerId?: string } }
+    | { type: 'UPDATE_BLOCK'; payload: { id: string; data: Partial<Block['data']> } }
+    | { type: 'DELETE_BLOCK'; payload: { id: string } }
+    | { type: 'DUPLICATE_BLOCK'; payload: { id: string } }
+    | { type: 'MOVE_BLOCK'; payload: { id: string; newIndex: number; containerId?: string } }
+    | { type: 'SET_TITLE'; payload: string }
+    | { type: 'SET_SLUG'; payload: string }
+    | { type: 'SET_SEO'; payload: Partial<SEOMetadata> }
+    | { type: 'SET_METADATA'; payload: Partial<PostMetadata> }
+    | { type: 'SET_STATUS'; payload: PostStatus }
+    | { type: 'SET_FOCUS_MODE'; payload: boolean }
+    | { type: 'SELECT_BLOCK'; payload: string | null }
+    | { type: 'SET_DRAGGED_BLOCK'; payload: string | null }
+    | { type: 'LOAD_POST'; payload: BlogPost }
+    | { type: 'RESET_EDITOR' }
+    | { type: 'MARK_CLEAN' }
+    | { type: 'MARK_DIRTY' }
+    | { type: 'UNDO' }
+    | { type: 'REDO' }
+    | { type: 'SAVE_HISTORY' };
+
+/**
+ * Editor Context Value
+ * The value provided by the EditorContext
+ */
+export interface EditorContextValue {
+    /** Current editor state */
+    state: EditorState;
+    
+    /** Dispatch an action to modify state */
+    dispatch: (action: EditorAction) => void;
+    
+    /** Enable dark mode for content area and wrappers */
+    darkMode: boolean;
+    
+    /** Background colors for the editor */
+    backgroundColors?: {
+        /** Background color for light mode (REQUIRED) */
+        light: string;
+        /** Background color for dark mode (optional) */
+        dark?: string;
+    };
+    
+    /** Helper functions for common operations */
+    helpers: {
+        /** Add a new block (supports nested containers via containerId) */
+        addBlock: (type: string, index?: number, containerId?: string) => void;
+        
+        /** Update a block's data */
+        updateBlock: (id: string, data: Partial<Block['data']>) => void;
+        
+        /** Delete a block */
+        deleteBlock: (id: string) => void;
+        
+        /** Duplicate a block */
+        duplicateBlock: (id: string) => void;
+        
+        /** Move a block to a new position (supports nested containers via containerId) */
+        moveBlock: (id: string, newIndex: number, containerId?: string) => void;
+        
+        /** Load a post into the editor */
+        loadPost: (post: BlogPost) => void;
+        
+        /** Reset editor to initial state */
+        resetEditor: () => void;
+        
+        /** Save current state (triggers save callback) */
+        save: () => Promise<void>;
+        
+        /** Undo last action */
+        undo: () => void;
+        
+        /** Redo last undone action */
+        redo: () => void;
+    };
+    
+    /** Whether undo is available */
+    canUndo: boolean;
+    
+    /** Whether redo is available */
+    canRedo: boolean;
+}
+
+/**
+ * Initial Editor State
+ */
+export const initialEditorState: EditorState = {
+    blocks: [],
+    title: '',
+    slug: '',
+    seo: {
+        title: '',
+        description: '',
+    },
+    metadata: {
+        categories: [],
+        tags: [],
+        excerpt: '',
+    },
+    status: 'draft',
+    isDirty: false,
+    focusMode: false,
+    selectedBlockId: null,
+    draggedBlockId: null,
+    postId: null,
+};
+

package/src/types/block.ts

@@ -0,0 +1,269 @@
+/**
+ * Core Block Types
+ * Foundation for the Block-Based Architecture
+ * Multi-Tenant Plugin Architecture - Blocks are provided by client applications
+ */
+
+import React from 'react';
+
+/**
+ * Base Block Interface
+ * Every block in the system extends this structure
+ */
+export interface Block {
+    /** Unique identifier for the block */
+    id: string;
+    
+    /** Block type identifier (e.g., 'heading', 'paragraph', 'image', 'plantSpec') */
+    type: string;
+    
+    /** Block-specific data (varies by type) */
+    data: Record<string, unknown>;
+    
+    /** 
+     * Child blocks (for container blocks like Section, Columns)
+     * Can be an array of Block IDs (for flat storage) or Block objects (for nested structure)
+     */
+    children?: string[] | Block[];
+    
+    /** Optional metadata for editor state, styling, etc. */
+    meta?: {
+        /** Visual order in the editor */
+        order?: number;
+        /** Whether block is collapsed in editor */
+        collapsed?: boolean;
+        /** Custom styling overrides */
+        style?: Record<string, string>;
+        /** Editor-specific flags */
+        flags?: string[];
+        /** Column index (for column container blocks) */
+        columnIndex?: number;
+        /** Additional custom metadata */
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Block Edit Component Props
+ * Props passed to the Edit component in the dashboard editor
+ */
+export interface BlockEditProps {
+    /** The block being edited */
+    block: Block;
+    
+    /** Update handler - call this to update the block's data */
+    onUpdate: (data: Partial<Block['data']>) => void;
+    
+    /** Delete handler - call this to remove the block */
+    onDelete?: () => void;
+    
+    /** Duplicate handler - call this to duplicate the block */
+    onDuplicate?: () => void;
+    
+    /** Whether the block is currently selected */
+    isSelected?: boolean;
+    
+    /** Whether the block is currently being dragged */
+    isDragging?: boolean;
+    
+    /** Focus mode state */
+    focusMode?: boolean;
+    
+    /** Child blocks (for container blocks like Section, Columns) */
+    childBlocks?: Block[];
+    
+    /** Add a child block (for container blocks) */
+    onChildBlockAdd?: (type: string, index?: number, containerId?: string) => void;
+    
+    /** Update a child block (for container blocks) */
+    onChildBlockUpdate?: (id: string, data: Partial<Block['data']>, containerId?: string) => void;
+    
+    /** Delete a child block (for container blocks) */
+    onChildBlockDelete?: (id: string, containerId?: string) => void;
+    
+    /** Move a child block (for container blocks) */
+    onChildBlockMove?: (id: string, newIndex: number, containerId?: string) => void;
+}
+
+/**
+ * Block Preview Component Props
+ * Props passed to the Preview component for headless rendering
+ */
+export interface BlockPreviewProps {
+    /** The block to render */
+    block: Block;
+    
+    /** Additional rendering context */
+    context?: {
+        /** Site ID */
+        siteId?: string;
+        /** Locale */
+        locale?: string;
+        /** Custom render props */
+        [key: string]: unknown;
+    };
+    
+    /** Child blocks (for container blocks like Section, Columns) */
+    childBlocks?: Block[];
+    
+    /** Render a child block (for container blocks) */
+    renderChild?: (childBlock: Block) => React.ReactElement;
+}
+
+/**
+ * Strict Block Component Interface
+ * Every client-provided block MUST implement this interface
+ */
+export interface IBlockComponent {
+    /** 
+     * Edit Component - Rendered in the dashboard editor
+     * Must use dashboard design system (earth-tone palette, typography)
+     */
+    Edit: React.ComponentType<BlockEditProps>;
+    
+    /** 
+     * Preview Component - Rendered in headless/frontend context
+     * Can use client's own design system
+     */
+    Preview: React.ComponentType<BlockPreviewProps>;
+    
+    /** 
+     * Icon Component - Shown in block palette
+     * Should be a simple icon (lucide-react recommended)
+     */
+    Icon?: React.ComponentType<{ className?: string }>;
+}
+
+/**
+ * Block Type Definition
+ * Complete definition of a block type for the registry
+ */
+export interface BlockTypeDefinition {
+    /** Unique type identifier */
+    type: string;
+    
+    /** Human-readable name */
+    name: string;
+    
+    /** Description of the block (shown in tooltips) */
+    description: string;
+    
+    /** Icon component (React component) - Optional, falls back to block component's Icon */
+    icon?: React.ComponentType<{ className?: string }>;
+    
+    /** Default data structure for this block type */
+    defaultData: Record<string, unknown>;
+    
+    /** Validation schema (optional, for runtime validation) */
+    validate?: (data: Record<string, unknown>) => boolean;
+    
+    /** Whether this block can contain nested blocks */
+    isContainer?: boolean;
+    
+    /** Allowed child block types (if container) */
+    allowedChildren?: string[];
+    
+    /** Category for grouping in block palette */
+    category?: 'text' | 'media' | 'layout' | 'interactive' | 'custom';
+    
+    /** 
+     * Block Components - REQUIRED for client-provided blocks
+     * Edit and Preview components must be provided
+     */
+    components: IBlockComponent;
+}
+
+/**
+ * Rich Text Formatting Configuration
+ * Optional configuration for rich text formatting in text blocks
+ */
+export interface RichTextFormattingConfig {
+    /** Whether bold formatting is available */
+    bold?: boolean;
+    /** Whether italic formatting is available */
+    italic?: boolean;
+    /** Whether underline formatting is available */
+    underline?: boolean;
+    /** Whether links are available */
+    links?: boolean;
+    /** Available colors (array of color values or Tailwind classes) */
+    colors?: string[];
+    /** Custom CSS classes for formatted text */
+    styles?: {
+        bold?: string;
+        italic?: string;
+        underline?: string;
+        link?: string;
+        /** Color classes mapped by color value */
+        colorClasses?: Record<string, string>;
+    };
+}
+
+/**
+ * Client Block Definition
+ * Simplified interface for client apps to provide blocks
+ */
+export interface ClientBlockDefinition {
+    /** Unique type identifier */
+    type: string;
+    
+    /** Human-readable name */
+    name: string;
+    
+    /** Description of the block */
+    description: string;
+    
+    /** Icon component (optional) */
+    icon?: React.ComponentType<{ className?: string }>;
+    
+    /** Default data structure */
+    defaultData: Record<string, unknown>;
+    
+    /** Validation function (optional) */
+    validate?: (data: Record<string, unknown>) => boolean;
+    
+    /** Whether this block can contain nested blocks */
+    isContainer?: boolean;
+    
+    /** Allowed child block types (if container) */
+    allowedChildren?: string[];
+    
+    /** Category for grouping */
+    category?: 'text' | 'media' | 'layout' | 'interactive' | 'custom';
+    
+    /** Block components - REQUIRED */
+    components: IBlockComponent;
+    
+    /** Rich text formatting configuration (optional) */
+    richTextFormatting?: RichTextFormattingConfig;
+}
+
+/**
+ * Block Registry Configuration
+ * Central registry of all available block types
+ */
+export interface BlockRegistry {
+    /** Map of block type to definition */
+    types: Map<string, BlockTypeDefinition>;
+    
+    /** Register a new block type */
+    register(definition: BlockTypeDefinition): void;
+    
+    /** Register multiple client blocks at once */
+    registerClientBlocks(definitions: ClientBlockDefinition[]): void;
+    
+    /** Get block type definition */
+    get(type: string): BlockTypeDefinition | undefined;
+    
+    /** Get all registered block types */
+    getAll(): BlockTypeDefinition[];
+    
+    /** Get block types by category */
+    getByCategory(category: BlockTypeDefinition['category']): BlockTypeDefinition[];
+    
+    /** Check if a block type is registered */
+    has(type: string): boolean;
+    
+    /** Clear all registered blocks */
+    clear(): void;
+}

package/src/types/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Central type exports
+ */
+
+export * from './block';
+export * from './post';
+
+// Re-export commonly used types for convenience
+export type {
+    IBlockComponent,
+    BlockEditProps,
+    BlockPreviewProps,
+    ClientBlockDefinition,
+} from './block';
+

package/src/types/post.ts

@@ -0,0 +1,165 @@
+/**
+ * Post Types
+ * Data structures for blog posts
+ */
+
+import { Block } from './block';
+
+/**
+ * Post Status
+ */
+export type PostStatus = 'draft' | 'published' | 'scheduled' | 'archived';
+
+/**
+ * SEO Metadata
+ */
+export interface SEOMetadata {
+    /** SEO title (can differ from post title) */
+    title?: string;
+    
+    /** Meta description */
+    description?: string;
+    
+    /** Open Graph image URL */
+    ogImage?: string;
+    
+    /** Keywords/tags for SEO */
+    keywords?: string[];
+    
+    /** Canonical URL */
+    canonicalUrl?: string;
+}
+
+/**
+ * Publication Data
+ */
+export interface PublicationData {
+    /** Publication status */
+    status: PostStatus;
+    
+    /** Publication date (ISO string) */
+    date?: string;
+    
+    /** Scheduled publication date (if status is 'scheduled') */
+    scheduledDate?: string;
+    
+    /** Author ID */
+    authorId?: string;
+    
+    /** Last modified date */
+    updatedAt?: string;
+}
+
+/**
+ * Privacy Settings
+ */
+export interface PrivacySettings {
+    /** Whether the post is private (not publicly accessible) */
+    isPrivate?: boolean;
+    
+    /** Password protection (if set, post requires password to view) */
+    password?: string;
+    
+    /** List of user IDs who have access (from plugin-users) */
+    sharedWithUsers?: string[];
+}
+
+/**
+ * Post Metadata
+ */
+export interface PostMetadata {
+    /** Featured image */
+    featuredImage?: {
+        id?: string; // Image ID (preferred, for plugin-images system)
+        src?: string; // Image URL (legacy support, will be converted to id)
+        alt?: string;
+        brightness?: number; // 0-200, 100 = normal
+        blur?: number; // 0-20
+    };
+    
+    /** Categories */
+    categories?: string[];
+    
+    /** Tags */
+    tags?: string[];
+    
+    /** Excerpt/summary */
+    excerpt?: string;
+    
+    /** Language code */
+    lang?: string;
+    
+    /** Privacy settings */
+    privacy?: PrivacySettings;
+}
+
+/**
+ * Complete Blog Post Structure
+ * This is the headless JSON structure stored in the database
+ */
+export interface BlogPost {
+    /** Unique post identifier */
+    id: string;
+    
+    /** Post title */
+    title: string;
+    
+    /** URL slug (unique, auto-generated from title) */
+    slug: string;
+    
+    /** Array of content blocks */
+    blocks: Block[];
+    
+    /** SEO metadata */
+    seo: SEOMetadata;
+    
+    /** Publication data */
+    publication: PublicationData;
+    
+    /** Additional metadata */
+    metadata: PostMetadata;
+    
+    /** Creation timestamp */
+    createdAt: string;
+    
+    /** Last update timestamp */
+    updatedAt: string;
+    
+    /** Version number for revision tracking */
+    version?: number;
+}
+
+/**
+ * Post List Item (for list views)
+ * Lightweight version of BlogPost for performance
+ */
+export interface PostListItem {
+    id: string;
+    title: string;
+    slug: string;
+    status: PostStatus;
+    date?: string;
+    excerpt?: string;
+    featuredImage?: string;
+    authorId?: string;
+    updatedAt: string;
+    category?: string;
+}
+
+/**
+ * Post Filter Options
+ */
+export interface PostFilterOptions {
+    status?: PostStatus | PostStatus[];
+    category?: string;
+    tag?: string;
+    authorId?: string;
+    search?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    limit?: number;
+    skip?: number;
+    sortBy?: 'date' | 'title' | 'updatedAt';
+    sortOrder?: 'asc' | 'desc';
+}
+

package/src/utils/README.md

@@ -0,0 +1,75 @@
+# Blog Plugin Client Utilities
+
+Helper functions for fetching blog data in client applications (non-React).
+
+## fetchBlogs
+
+Fetch blog posts from the API (returns a Promise).
+
+### Usage
+
+```ts
+import { fetchBlogs } from '@jhits/plugin-blog';
+
+async function loadBlogs() {
+    try {
+        const { blogs, total } = await fetchBlogs({
+            limit: 10,
+            skip: 0,
+            status: 'published',
+            admin: false,
+            apiBaseUrl: '/api/blogs',
+        });
+
+        console.log(`Found ${total} posts`);
+        blogs.forEach(blog => {
+            console.log(blog.title);
+        });
+    } catch (error) {
+        console.error('Failed to fetch blogs:', error);
+    }
+}
+```
+
+### Options
+
+- `limit` (number, default: 10): Maximum number of posts to fetch
+- `skip` (number, default: 0): Number of posts to skip (for pagination)
+- `status` (string, optional): Filter by status ('published', 'draft', 'concept')
+- `admin` (boolean, default: false): Whether to fetch all posts for admin (includes drafts)
+- `apiBaseUrl` (string, default: '/api/blogs'): API base URL
+
+### Returns
+
+Promise resolving to:
+- `blogs` (PostListItem[]): Array of blog posts
+- `total` (number): Total number of posts available
+
+## fetchBlog
+
+Fetch a single blog post by slug (returns a Promise).
+
+### Usage
+
+```ts
+import { fetchBlog } from '@jhits/plugin-blog';
+
+async function loadBlogPost(slug: string) {
+    try {
+        const blog = await fetchBlog({ slug });
+        console.log(blog.title);
+    } catch (error) {
+        console.error('Failed to fetch blog:', error);
+    }
+}
+```
+
+### Options
+
+- `slug` (string, required): Blog post slug
+- `apiBaseUrl` (string, default: '/api/blogs'): API base URL
+
+### Returns
+
+Promise resolving to a `BlogPost` object.
+