Composr

A lightweight, declarative framework for building dynamic HTML interfaces using JSON models. Composr allows you to define UI structure and behavior in JSON format with JavaScript-powered compositions.

Features

• Declarative JSON syntax - Define UI structure and behavior in JSON
• Built-in directives - Conditional rendering, loops, context binding
• Expression evaluation - Safe JavaScript expressions in templates
• Composition system - Reusable JavaScript functions
• Model validation - Built-in validation and error handling
• TypeScript support - Full type safety and IntelliSense
• Zero dependencies - Lightweight and fast

Quick Start

import { renderHtml } from "./src";

const model = {
  div: {
    _class: "container",
    h1: {
      _content: "Hello, World!",
    },
    p: {
      _content: "Welcome to Composr",
    },
  },
};

const html = await renderHtml(model);
console.log(html); // <div class="container"><h1>Hello, World!</h1><p>Welcome to Composr</p></div>

Core Concepts

Basic Structure

Composr models use element names as keys and properties as values:

const model = {
  div: {
    _class: "my-class", // Attributes (prefixed with _)
    _id: "my-id",
    span: {
      _content: "Text", // Element content
    },
  },
};

Directives

Conditional Rendering (_if)

const model = {
  div: {
    _if: "showContent()",
    _content: "Visible content",
  },
};

const compositions = {
  showContent: () => true,
};

const html = await renderHtml(model, compositions);

Loops (_each)

const model = {
  _each: "items()",
  _as: "item",
  div: {
    _content: "item.name",
  },
};

const compositions = {
  items: () => [{ name: "Item 1" }, { name: "Item 2" }],
};

Context Binding (_with)

const model = {
  _with: "getUserData()",
  _as: "user",
  div: {
    _content: "user.name - user.email",
  },
};

const compositions = {
  getUserData: () => ({ name: "John", email: "john@example.com" }),
};

Expressions

Use JavaScript expressions in templates:

const model = {
  div: {
    _content: 'greeting("World")',
    _class: 'user().isActive ? "active" : "inactive"',
  },
};

const compositions = {
  greeting: (name: string) => `Hello, ${name}!`,
  user: () => ({ isActive: true }),
};

API Reference

renderHtml(jsonModel, compositions?, options?)

Renders a JSON model to HTML string.

Parameters:

• jsonModel: JsonModel - The JSON model to render
• compositions?: Compositions - JavaScript functions for expressions
• options?: RenderOptions - Optional rendering configuration

Returns: Promise<string> - Generated HTML

Options:

interface RenderOptions {
  strict?: boolean; // Enable strict mode (throws on missing functions)
  cache?: boolean; // Enable caching
  debug?: boolean; // Enable debug mode
  maxDepth?: number; // Maximum nesting depth
  allowUnsafeEval?: boolean; // Allow unsafe evaluation
}

validateModel(model)

Validates a JSON model structure.

const errors = validateModel(model);
if (errors.length > 0) {
  console.error("Validation errors:", errors);
}

extendModel(baseModel, extensions)

Extends a model with additional properties.

const extended = extendModel(baseModel, {
  footer: {
    _content: "Copyright 2024",
  },
});

Error Handling

try {
  const html = await renderHtml(model, compositions, { strict: true });
} catch (error) {
  console.error("Render error:", error.message);
}

// Graceful fallback in non-strict mode
const model = {
  div: {
    _content: 'missingFunction() || "fallback"',
  },
};

License

MIT License - see LICENSE file for details.