Widget System Documentation

Welcome to the comprehensive SveltyCMS widget system documentation. The widget system is built on a modern 3-Pillar Architecture providing type safety, performance optimization, and developer-friendly patterns.

📚 Documentation Structure

Core Documentation

0. Visual Overview ⭐

Visual guide with comprehensive Mermaid diagrams explaining the entire system.

Covers:

• 🎯 Complete system flow diagrams
• 🏗️ 3-Pillar architecture deep dive
• 🔄 Widget lifecycle & data flow
• 🏪 Store state management
• 🗄️ Database relationships
• 📊 Performance strategies

Read this when: You prefer visual learning or need to understand system interactions.

1. Widget System Overview

Start here for understanding the widget system concepts and capabilities.

Covers:

• 🏗️ 3-Pillar Architecture (Definition, Input, Display)
• 🎯 Widget types (Core vs Custom)
• 🔄 System features and lifecycle
• 📁 Directory structure
• 🚀 Performance optimizations

Read this when: You’re new to the widget system or need a high-level understanding.

2. Widget Architecture

Technical deep-dive into the widget system implementation.

Covers:

• 🏭 Widget Factory System
• 🏪 Widget Store Management
• 🗄️ Database Integration
• 🔧 Runtime Implementation
• 🛡️ Type Safety
• 📊 Performance Optimizations
• 🚀 Batch Data Loading (New modifyRequestBatch API)

Read this when: You need to understand how the system works internally or debug issues.

3. Development Guide

Practical tutorial for creating and customizing widgets.

Covers:

• 🚀 Quick start tutorial
• 📝 Step-by-step widget creation
• 🔧 Advanced features
• 🧪 Testing strategies
• 📦 Widget management
• 🚀 Deployment best practices

Read this when: You want to create custom widgets or modify existing ones.

4. Widget Security

Comprehensive security guide for widget development and implementation.

Covers:

• 🛡️ XSS prevention techniques
• 🔒 Injection attack protection
• 📁 File upload validation
• 🌐 SSRF prevention
• 🔐 IDOR protection
• ✅ Input sanitization patterns
• 🧪 Security testing

Read this when: You need to understand or implement widget security measures.

5. Multilingual Widget Guide

Complete guide to building multilingual widgets.

Covers:

• 🌍 Translation architecture
• 🔄 Language-aware components
• 💾 Database storage patterns
• 🎯 Content vs system languages
• ✅ Best practices

Read this when: You’re building widgets that need translation support.

🎯 Quick Navigation

For Different Roles

By Task

🚀 Quick Start Examples

Using Existing Widgets

// In a collection schema
import { widgets } from '@src/widgets';

export default {
	fields: [
		widgets.Input({
			label: 'Title',
			required: true,
			maxLength: 100
		}),
		widgets.RichText({
			label: 'Content',
			translated: true
		}),
		widgets.Date({
			label: 'Published Date',
			required: true
		})
	]
};

Creating a Simple Custom Widget

// src/widgets/custom/rating/index.ts
import { createWidget } from '@src/widgets/factory';

const RatingWidget = createWidget({
	Name: 'Rating',
	Icon: 'mdi:star',
	Description: 'Star rating widget',
	inputComponentPath: '/src/widgets/custom/rating/Input.svelte',
	displayComponentPath: '/src/widgets/custom/rating/Display.svelte',
	validationSchema: number(),
	defaults: {
		maxRating: 5,
		allowHalfStars: false
	}
});

export default RatingWidget;

📖 Individual Widget Documentation

Each widget includes its own comprehensive documentation:

Core Widgets

• Input Widget - Text input with validation
• Rich Text Widget - WYSIWYG editor
• Date Widget - Date and time picker
• Media Upload Widget - File upload
• Relation Widget - Entity relationships

Custom Widgets

• SEO Widget - SEO meta tags and schema
• Address Widget - Address with geocoding
• Currency Widget - Monetary values
• Color Picker Widget - Color selection

🛠️ System Features

3-Pillar Architecture

Every widget follows the same architectural pattern:

1. 📋 Definition (index.ts) - Widget configuration and validation
2. ✏️ Input (Input.svelte) - Interactive editing component
3. 👁️ Display (Display.svelte) - Optimized display component

Key Capabilities

• ✅ Type Safety - Full TypeScript support throughout
• 🔄 Dynamic Loading - Widgets loaded on-demand for performance
• 🏢 Multi-Tenant - Different widget configurations per tenant
• 🔒 Security - Permission-based widget access control
• 📚 Self-Documenting - Each widget includes MDX documentation
• 🧪 Testable - Comprehensive testing support
• 🌍 Multilingual - Built-in translation support via contentLanguage for all text-based widgets

Multilingual Widget Support

SveltyCMS widgets support multilingual content through the translated field property:

Enable Translation:

// Collection field configuration
{
  widget: 'input',
  label: 'Article Title',
  db_fieldName: 'title',
  translated: true,  // ← Enables multilingual support
  required: true
}

Data Storage Format:

// Database-agnostic format (MongoDB nested, SQL relational)
{
  "title": {
    "en": "Hello World",
    "de": "Hallo Welt",
    "fr": "Bonjour le monde"
  }
}

Supported Widgets:

Learn More:

• Language Architecture - Complete multilingual system guide
• Widget Architecture - Multilingual Section - Implementation patterns
• Widget Development Guide - Translation Support - Building translatable widgets

🔗 Related Documentation

API References

• Widget API - REST API endpoints
• Collection API - Collection management
• GraphQL API - GraphQL schema generation

Architecture Guides

• Runtime Widget Discovery - Zero-downtime widget installation
• Validation Instant Feedback - Smart validation system
• Collection Store Dataflow - Data flow patterns
• Database Methods - Database operations
• Code Structure - Overall codebase structure
• Language Architecture - Multilingual system

Security Documentation

• Widget Security - Comprehensive widget security guide
• Security Overview - System-wide security measures
• Authentication System - User authentication
• Cryptography Module - Encryption and hashing

Development Resources

• Widget Test Coverage - Testing documentation
• Contributing Guide - Contributing to widgets

🧪 Testing

Widget Test Coverage

SveltyCMS includes comprehensive testing for all widgets:

• ✅ 359+ Tests: Covering core widgets, custom widgets, and factory architecture
• ✅ 86% Coverage: Complete widget system code coverage
• ✅ Type Safety: Full TypeScript validation testing
• ✅ Multilingual: Translation support testing
• ✅ Database: Aggregation and query testing

Test Suite Breakdown:

Run Widget Tests

# All widget tests
bun test tests/bun/widgets/

# Specific test files
bun test tests/bun/widgets/core-widgets.test.ts
bun test tests/bun/widgets/custom-widgets.test.ts
bun test tests/bun/widgets/widget-system.test.ts

# With coverage
bun test --coverage tests/bun/widgets/

Test Documentation

For complete testing documentation, patterns, and best practices:

📚 Widget Test Coverage Documentation

Includes:

• Detailed test results by widget
• Test patterns and best practices
• Running tests and debugging
• CI/CD integration
• Performance benchmarks
• Known issues and solutions

🎯 Next Steps

1. New to widgets? Start with Widget System Overview
2. Want to create widgets? Follow the Development Guide
3. Need technical details? Dive into Widget Architecture
4. Testing widgets? Check Widget Test Coverage
5. Looking for specific widgets? Browse the individual widget documentation above

• Structure: group, repeater

Custom Widgets (Optional)

Located in src/widgets/custom/:

• Forms & Input: colorPicker, rating, currency
• SEO: seo, metadata
• Advanced: phoneNumber, address
• E-commerce: product, pricing (marketplace)
• Social: socialShare, embedder (marketplace)

📚 Documentation

Core Documentation

• Widget Management System

  • 3-pillar architecture details
  • Widget lifecycle and dependencies
  • Multi-tenant configuration
  • API endpoints

• Widget Marketplace System

  • Marketplace integration
  • Widget discovery and installation
  • Payment and licensing
  • Community features

• Widget Management Enhancement

  • Recent improvements
  • Enhanced dashboard features
  • Migration guide

🎯 Quick Start

Using Widgets

// In collection schema
import { widgets } from '@widgets';

export default {
	fields: [
		widgets.Input({
			label: 'Title',
			inputType: 'text',
			required: true
		}),
		widgets.RichText({
			label: 'Content',
			toolbar: 'full'
		}),
		widgets.MediaUpload({
			label: 'Featured Image',
			accept: 'image/*'
		})
	]
};

Creating Widgets

// src/widgets/custom/myWidget/index.ts
import { createWidget } from '@widgets/factory';
import * as v from 'valibot';

export default createWidget({
	Name: 'MyWidget',
	Icon: 'mdi:puzzle-plus',
	Description: 'Custom widget with 3-pillar architecture',

	// 3-Pillar paths
	inputComponentPath: '/src/widgets/custom/myWidget/Input.svelte',
	displayComponentPath: '/src/widgets/custom/myWidget/Display.svelte',

	// Validation
	validationSchema: v.object({
		value: v.string([v.minLength(1)])
	}),

	// Defaults
	defaults: {
		value: ''
	}
});

🖥️ Management Interface

Access widget management at /config/widgetManagement:

Features

• 📊 Statistics Dashboard: Real-time metrics
• 🔍 Search & Filter: Quick widget discovery
• 📋 2-Column Layout: Professional grid (desktop)
• 🏪 Marketplace Tab: Browse and install widgets
• 🎯 3-Pillar Visibility: See component implementation status
• ⚙️ Quick Actions: One-click activation/deactivation

Statistics Explained

• Total Widgets: All registered widgets (core + custom)
• Active: Currently enabled and usable in collections
• Core: Essential widgets (cannot be disabled)
• Custom: Optional widgets (can be toggled)
• Input: Widgets with Input component (editing capability)
• Display: Widgets with Display component (viewing capability)

🔧 Widget Store API

Key Functions

import { widgetStoreActions, isWidgetActive, canDisableWidget, getWidgetDependencies } from '@stores/widgetStore.svelte';

// Initialize widgets
await widgetStoreActions.initializeWidgets('tenant-id');

// Check status
const isActive = isWidgetActive('SEO');
const canDisable = canDisableWidget('SEO');
const deps = getWidgetDependencies('SEO');

// Update status
await widgetStoreActions.updateWidgetStatus('SEO', 'active', 'tenant-id');

📦 File Structure

src/
├── widgets/
│   ├── core/                    # Core widgets
│   │   ├── input/
│   │   │   ├── index.ts        # Definition
│   │   │   ├── Input.svelte    # Edit component
│   │   │   └── Display.svelte  # View component
│   │   └── ...
│   ├── custom/                  # Custom widgets
│   │   ├── seo/
│   │   │   ├── index.ts
│   │   │   ├── Input.svelte
│   │   │   └── Display.svelte
│   │   └── ...
│   ├── factory.ts               # Widget factory
│   └── types.ts                 # Type definitions
├── stores/
│   └── widgetStore.svelte.ts   # Centralized state
└── routes/
    └── (app)/config/widgetManagement/
        ├── +page.svelte
        ├── +page.server.ts
        ├── WidgetDashboardEnhanced.svelte
        └── WidgetCard.svelte

🔐 Security & Permissions

Permission Levels

• config:widgetManagement - View widget management
• config:widgetInstall - Install widgets
• config:widgetUninstall - Uninstall widgets
• config:widgetActivate - Activate/deactivate widgets
• config:marketplace - Access marketplace

Multi-Tenant Isolation

• Each tenant has separate widget configurations
• Core widgets are always active for all tenants
• Custom widgets are tenant-specific
• Database stores per-tenant widget states

📋 Security Checklist

Use this checklist when creating new widgets:

Input Validation

• MIME type whitelist (file widgets)
• File size limits (upload widgets)
• Extension validation (file widgets)
• Path traversal prevention
• Input length limits (text widgets)
• Format validation (email, phone, URL)
• Regex pattern validation
• Whitelist-based validation

Output Encoding

• HTML entity escaping
• CSS value sanitization
• URL encoding
• JavaScript string escaping
• SQL parameterization

XSS Prevention

• Use Sanitize component for HTML
• Escape user-generated content
• Content Security Policy compliance
• Avoid {@html} without sanitization
• Validate URLs before rendering

SSRF Prevention

• URL protocol whitelist (https only)
• Domain whitelist
• Block private IPs
• Block localhost
• Block cloud metadata endpoints

IDOR Prevention

• Tenant ID filtering
• User ID validation
• Permission checks
• Relation validation

DoS Prevention

• Input length limits
• File size limits
• Rate limiting considerations
• Regex complexity limits
• Resource consumption limits

🚀 Best Practices

Widget Development

1. Always implement 3 pillars: Definition, Input, Display
2. Use factory pattern: Leverage createWidget() for consistency
3. Validate with Valibot: Centralize validation in definition
4. Document dependencies: Clearly specify widget dependencies
5. Test thoroughly: Unit test each pillar independently

Widget Management

1. Regular audits: Review installed widgets periodically
2. Monitor dependencies: Track widget relationships
3. Security updates: Keep widgets updated
4. Usage analysis: Track which widgets are actively used
5. Performance: Monitor impact on system performance

🔗 Related Resources

• Content Types - Using widgets in collections
• API Development - Widget API integration
• Testing - Widget testing strategies
• Security - Widget security considerations

The Widget System provides a powerful, extensible foundation for content management in SveltyCMS with modern architecture and professional management tools.