@lms-cms/blocks

Modular block system for the LMS CMS, providing reusable content components with PDF rendering capabilities.

Overview

This package contains a collection of modular blocks that can be used to build educational content in the LMS CMS. Each block is a self-contained component that can handle different types of content, including text, images, videos, and PDF documents.

Installation

npm install @lms-cms/blocks

Dependencies

• @lms-cms/core: Core LMS CMS functionality
• react-pdf: PDF rendering capabilities
• zod: Schema validation
• React (peer dependency): >=18.0.0
• React DOM (peer dependency): >=18.0.0

Features

• 12 Built-in Block Types: Comprehensive content block library
• Modular Registration: Register individual blocks or all at once
• Type-Safe: Full TypeScript support with proper data schemas
• Extensible: Easy to create custom blocks following the same pattern
• LMS-Focused: Blocks specifically designed for educational content
• Mathematical Rendering: KaTeX-powered equation block with visual builder

API Reference

Block Definitions

• textBlockDef: Basic text content block
• headingBlockDef: Heading elements (h1-h6)
• imageBlockDef: Image display with captions
• videoBlockDef: Video player integration
• audioBlockDef: Audio player integration
• pdfBlockDef: PDF document rendering
• fileBlockDef: File download links
• embedBlockDef: Embedded content (iframe)
• equationBlockDef: Mathematical equations with KaTeX rendering
• quizBlockDef: Interactive quiz components
• progressBlockDef: Progress indicators
• checklistBlockDef: Interactive checklists

Utility Functions

• allBlocks: Array containing all built-in block definitions
• registerAllBlocks(): Function to register all built-in blocks

Usage

Register Individual Blocks

import { registerBlock } from '@lms-cms/core';
import { textBlockDef, imageBlockDef, videoBlockDef } from '@lms-cms/blocks';

// Register specific blocks
registerBlock(textBlockDef);
registerBlock(imageBlockDef);
registerBlock(videoBlockDef);

Register All Built-in Blocks

import { registerAllBlocks } from '@lms-cms/blocks';

// Register all built-in blocks at once
registerAllBlocks();

Use Blocks in Content

import { createDoc, createBlock } from '@lms-cms/core';
import { registerAllBlocks } from '@lms-cms/blocks';

// First register the blocks
registerAllBlocks();

// Create content with different block types
const doc = createDoc([
  createBlock('text', { content: 'Welcome to your lesson!' }),
  createBlock('heading', { content: 'Chapter 1', level: 1 }),
  createBlock('image', { url: '/image.jpg', alt: 'Course image' }),
  createBlock('video', { src: '/video.mp4', poster: '/poster.jpg' }),
  createBlock('equation', { 
    latex: 'E = mc^2',
    displayMode: true
  }),
  createBlock('quiz', { 
    question: 'What is 2+2?',
    options: ['3', '4', '5'],
    correctAnswer: 1
  })
]);

Available Block Definitions

Core Text Blocks

textBlockDef

• Type: text
• Data: { content: string }
• Purpose: Basic text content and paragraphs

headingBlockDef

• Type: heading
• Data: { content: string, level: number }
• Purpose: Heading elements (h1-h6)

Core Media Blocks

imageBlockDef

• Type: image
• Data: { url: string, alt: string, caption?: string }
• Purpose: Image display with captions

videoBlockDef

• Type: video
• Data: { src: string, poster?: string, title?: string }
• Purpose: Video player integration

audioBlockDef

• Type: audio
• Data: { src: string, title?: string }
• Purpose: Audio player integration

pdfBlockDef

• Type: pdf
• Data: { url: string, title?: string }
• Purpose: PDF document rendering

fileBlockDef

• Type: file
• Data: { url: string, filename: string, size?: number }
• Purpose: File download links

embedBlockDef

• Type: embed
• Data: { url: string, title?: string }
• Purpose: Embedded content (iframe)

Core Math Blocks

equationBlockDef

• Type: equation
• Data: { latex: string, displayMode: boolean }
• Purpose: Mathematical equations with KaTeX rendering and visual LaTeX builder
• Features:
  • Live KaTeX preview
  • Visual LaTeX builder with templates (fractions, matrices, calculus, etc.)
  • Quick-insert symbol palette
  • Inline and display mode support
  • Error handling for invalid LaTeX

LMS-Specific Blocks

quizBlockDef

• Type: quiz
• Data: { question: string, options: string[], correctAnswer: number }
• Purpose: Interactive quiz components

progressBlockDef

• Type: progress
• Data: { current: number, total: number, label?: string }
• Purpose: Progress indicators

checklistBlockDef

• Type: checklist
• Data: { items: { text: string, checked: boolean }[] }
• Purpose: Interactive checklists

Development

# Install dependencies
npm install

# Run development build
npm run dev

# Build for production
npm run build

# Run tests
npm run test

# Type checking
npm run type-check

Scripts

• npm run build: Build the package for production
• npm run dev: Build in watch mode for development
• npm run test: Run tests with Vitest
• npm run type-check: Run TypeScript type checking without emitting files

Contributing

When adding new blocks:

1. Create the block component in src/blocks/
2. Add proper TypeScript types
3. Include comprehensive tests
4. Update the export in src/index.ts
5. Document the block in this README