@ruledwdl/core

v0.3.3

Published

2 days ago

Web Definition Language (WDL) core runtime and component layout engine.

0High
0Medium
0Low

ruledweb

wdl web-definition-language ruledwdl renderer layers html template-engine

Web Definition Language — Core Engine (`@ruledwdl/core`)

WDL (Web Definition Language) is a host-agnostic, declarative language runtime and component layout engine. It renders WDL definitions (REGISTRY / COMPONENTS / DATA, layouts, and components) directly to optimized HTML using a pluggable store.

Features & Recent Updates (v0.3.2)

Host-Agnostic Engine: Zero framework overhead — runs natively in Node.js, Cloudflare Workers, Edge runtimes, or modern browsers with 0 build tools.
Registry Schema V2.1: Native browser Scoped CSS Rules (@scope) support via flat rules: [{ selector, media?, css }] arrays compiled directly into <style data-wdl="components">.
Variant Attribute Generation: Automatic data-variant="..." attribute emission and :scope[data-variant="..."] CSS selector mapping.
Layers Component Expressions: Ultra-lean component syntax using WDL Layers expressions (tag.semantic_id, >, +, < de-indent/subset, <*N repeaters, <@N depth reference, * data loops) backed by WDLDomTree.
Design Token Cascade: Layered design and brand tokens integrated directly into WDL JSON and compiled into <style data-wdl="theme-tokens">, design-tokens, and brand-tokens.
100% Zero-Dependency Core: Zero external markdown runtime requirement; includes pluggable transformData and transformText hooks for external markdown engines (marked, markdown-it, remark).

Specifications & Documentation

REGISTRY Specification (v2.1) — Scoped CSS rules, token inheritance & syntax rules.
Registry Schema V2.1 Reference — Complete Scoped CSS @scope rules design guide.
COMPONENTS Specification (v2.0) — Component definitions, overrides, and layers grammar.
DATA Specification (v2.0) — Page state, array loop binding, SEO, and token declarations.
RuledWDL Complete Engine Reference — Architecture, stores, and layout composition guide.

Installation

npm install @ruledwdl/core

Ecosystem Packages

The RuledWDL monorepo maintains three core packages:

Quick Start

import { composePage, createMemoryStore } from '@ruledwdl/core';

// 1. Initialize a WDL Store
const store = createMemoryStore({
  layouts: {
    base: {
      name: 'base',
      COMPONENTS: [{ layers: 'div.shell', attr: { '.shell': { text: '{{content}}' } } }],
      DATA: { __design_tokens: ':root { --color-primary: #0284c7; }' }
    }
  }
});

// 2. Define a WDL Page with Schema V2.1 Scoped CSS Rules
const page = {
  title: 'Home Page',
  layout: 'base',
  REGISTRY: {
    $version: '2.1',
    card: {
      rules: [
        { selector: ':scope', css: { display: 'flex', padding: '1.5rem' } },
        { selector: '& .title', css: { color: 'var(--color-primary)' } }
      ]
    }
  },
  COMPONENTS: [
    { layers: 'div.card > h1.title', attr: { '.title': { text: 'Welcome ${name}' } } }
  ],
  DATA: { name: 'World' }
};

// 3. Compose to HTML
const { html, dynamic } = await composePage(store, 'demo-tenant', page);
console.log(html);

Direct Browser / CDN Usage (No Build Step)

Include the single standalone bundle file directly in your HTML:

<script src="https://cdn.jsdelivr.net/npm/@ruledwdl/core/dist/ruledwdl.min.js"></script>
<script>
  const { composePage, createMemoryStore } = WDL;
  // Use WDL directly in the browser via window.WDL
</script>

CLI Usage

# Render a page to stdout
npx ruledwdl render <project-dir> <slug>

# Run live preview server
npx ruledwdl serve [project-dir] [port]

Running Tests

npm test

License & Specifications

Code Implementation: Licensed under GNU Affero General Public License v3.0 (AGPL-3.0-or-later).
Language Specifications & Docs: Licensed under GNU General Public License v3.0 (GPL-3.0).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Web Definition Language — Core Engine (@ruledwdl/core)

Features & Recent Updates (v0.3.2)

Specifications & Documentation

Installation

Ecosystem Packages

Quick Start

Direct Browser / CDN Usage (No Build Step)

CLI Usage

Running Tests

License & Specifications

Web Definition Language — Core Engine (`@ruledwdl/core`)