@lms-cms/core

Core functionality for the LMS CMS system, providing state management, validation, and foundational utilities.

Overview

This package contains the core functionality that powers the entire LMS CMS system. It includes state management, data validation, type definitions, and utility functions that are shared across all other packages.

Installation

npm install @lms-cms/core

Dependencies

• zod: Schema validation and type safety
• zustand: Lightweight state management
• uuid: Unique identifier generation
• React (peer dependency): >=18.0.0

Features

• State Management: Zustand-based stores for course, lesson, and user data
• Data Validation: Zod schemas for type-safe data handling
• Type Definitions: TypeScript types and interfaces for the entire system
• Utility Functions: Helper functions for common operations
• Constants: System-wide constants and configuration

Core Concepts

Content System

The core package provides a block-based content system:

import { createDoc, createBlock, ContentDoc, ContentBlock } from '@lms-cms/core';

// Create a content document
const doc: ContentDoc = createDoc([
  createBlock('text', { content: 'Hello World' }),
  createBlock('image', { url: '/image.jpg', alt: 'Image' })
]);

// Access content structure
doc.blocks.forEach(block => {
  console.log(block.type, block.data);
});

Block Registry

Register and manage block definitions:

import { registerBlock, getBlock, listBlocks, useRegistry } from '@lms-cms/core';

// Register a custom block
registerBlock({
  type: 'my-block',
  version: 1,
  label: 'My Block',
  schema: z.object({ content: z.string() }),
  defaultData: { content: '' },
  EditorComponent: MyEditor,
  RenderComponent: MyRenderer
});

// Get block definition
const blockDef = getBlock('my-block');

// List all blocks
const allBlocks = listBlocks();

Data Validation

Zod schemas ensure type safety and data integrity:

import { ContentDocSchema, ContentBlockSchema } from '@lms-cms/core';

// Validate content document
const doc = ContentDocSchema.parse({
  id: 'doc-123',
  version: 1,
  meta: {},
  blocks: []
});

Type Definitions

Comprehensive TypeScript types for the LMS system:

import type { 
  ContentDoc, 
  ContentBlock, 
  BlockDefinition, 
  BlockEditorProps, 
  BlockRenderProps,
  IContentAdapter,
  LMSTheme 
} from '@lms-cms/core';

Theming System

Customizable theme system for consistent styling:

import { defaultTheme, mergeTheme, themeToCSS } from '@lms-cms/core';

// Merge custom theme
const customTheme = mergeTheme(defaultTheme, {
  '--color-primary': '#ff0000',
  '--font-body': 'Arial, sans-serif'
});

// Convert to CSS
const css = themeToCSS(customTheme);

API Reference

Content Creation

• createBlock<TData>(type, data, version?): Create a new content block
• createDoc(blocks, meta?): Create a content document

Registry Functions

• registerBlock(def): Register a block definition
• getBlock(type): Get a block definition by type
• listBlocks(category?): List all registered blocks
• useRegistry(): Hook for registry state

Migration Functions

• migrateBlock(block, toVersion): Migrate block to target version
• migrateDoc(doc): Migrate document blocks to latest versions

Theme Functions

• defaultTheme: Default theme configuration
• mergeTheme(base, override): Merge theme configurations
• themeToCSS(theme): Convert theme to CSS variables

Validation Schemas

• ContentDocSchema: Content document validation
• ContentBlockSchema: Content block validation

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

Architecture

The core package follows a modular architecture:

src/
  stores/          # Zustand state stores
  schemas/         # Zod validation schemas
  types/           # TypeScript type definitions
  utils/           # Utility functions
  constants/       # System constants
  index.ts         # Main exports

Best Practices

• Use Zod schemas for all data validation
• Leverage Zustand for state management instead of Context API
• Follow the established type definitions
• Use utility functions for common operations
• Keep the core package lightweight and framework-agnostic