CUBE.JS
๐ Introduction
A frontend framework built entirely on web standards.
Modular Cube is a frontend framework that builds directly on web standards, enabling modular and maintainable applications without virtual DOMs or build pipelines.
What is Modular Cube?
Modular Cube is a frontend framework designed around web standards. It operates entirely on native browser features such as Custom Elements, HTML Templates, ES Modules, and the Shadow DOM. This foundation enables user interface components to be defined with standard HTML and JavaScript while supporting scoped rendering, declarative structure, and encapsulated behaviors. The framework avoids virtual DOM abstractions and transpilation layers. By following this model, Modular Cube supports the development of modular, maintainable applications that run directly in the browser without additional build processes or external dependencies.
Why use Modular Cube?
- Modular Cube is designed to simplify frontend development while relying solely on modern web standards.
- ๐น
Built entirely on native browser features such as Custom Elements, Shadow DOM, and ES Modules. No external dependencies or build tools are required.
- ๐น
Avoids the overhead from complex runtime engines or compilation steps, making applications faster to load and easier to maintain.
- ๐น
Encapsulation by design, with isolated structure and styling through Shadow DOM, ensuring clean separation without global conflicts.
- ๐น
Interoperable and compatible, since it uses only HTML, CSS, and JavaScript, allowing seamless integration with existing codebases and libraries.
- ๐น
Reduced abstraction layers, which promotes long-term sustainability, predictability, and easier debugging.
Key features
Embed JavaScript expressions directly in your HTML using
${this.expression}. Supported in text content, attributes,
class names, and inline styles.
Use if directives and its extended forms
(e.g. else if, else) to selectively include
elements in the DOM based on runtime conditions.
Use forEach directives to generate repeated
markup from iterable data structures.
Bind native DOM events using a consistent pattern
(clickEvent, inputEvent, etc.) to trigger scoped
logic without manually registering listeners.
DOM updates are scoped and localized, reducing overhead and eliminating re-renders.
Architecture Based on Web Standards
The architecture of Modular Cube is structured around the core features natively supported by browsers. By relying on these capabilities, the framework ensures that components remain portable, efficient, and aligned with the evolution of the web platform.
Encapsulate behavior, state, and rendering logic in self-contained components defined as JavaScript classes. Each element is registered as a native HTML tag, allowing seamless integration into the DOM.
Provides reusable blocks of markup that are parsed but not rendered immediately. Templates serve as the foundation for dynamic rendering and runtime instantiation.
Enable modular development by defining clear boundaries for imports and exports. All components and logic are authored as ES modules, ensuring compatibility with the standard JavaScript module system.
Delivers encapsulation of both structure and styling, isolating internal implementations from the global DOM while supporting predictable component behavior.
๐ก Design Intent
Modular Cube does not aim to create a new way of building the web, it simply leverages the web as it exists today. Its goal is to empower developers to write UI code that is expressive, explicit, and maintainable, while avoiding the hidden complexity often introduced by large abstractions. It makes no assumptions about how your application is structured, but provides lightweight conventions to support common frontend needs: data-binding, conditional logic, event handling, and templating. By using only platform features, Modular Cube ensures forward compatibility and encourages a development style that aligns closely with how browsers operate. It is ideal for projects where performance, clarity, and long-term maintainability are key concerns.
These web standards work together to provide a consistent foundation for building components. They ensure that applications remain compatible with the native browser environment, while keeping the architecture simple and easy to extend.
๐ Core Concepts
Modular Cube lifecycle builds on the native Web Component lifecycle, extending it with custom states for more granular control over initialization and rendering. This ensures components are predictable, configurable, and modular throughout their lifetime in the DOM.
Lifecycle
The lifecycle of a component defines the sequence of stages a component passes through from creation to removal. It combines standard Web Component callbacks with framework specific processing states to ensure proper initialization, configuration, and rendering.
- The Web Component lifecycle methods are as follows:
- ๐น
constructor()
- ๐น
connectedCallback()
- ๐น
adoptedCallback()
- ๐น
attributeChangedCallback()
- ๐น
disconnectedCallback()
constructor
When a component instance is created, the constructor method is invoked.
In Modular Cube, this immediately calls the preProcess state. At this
stage, the component loads and validates its configuration, ensuring all required
parameters (such as references to HTML, CSS, or behavior settings) are in place before
any further lifecycle steps begin.
constructor โ preProcess
When a componentโs constructor is invoked, the preProcess state is
automatically executed.
During this stage, configuration data is loaded, validated, and prepared before any
rendering or attachment to the DOM occurs.
The constructor expects a mandatory configuration object with the following structure.
(MyComponent.config.json)
(MyComponent.js)
connectedCallback
The connectedCallback() method is invoked automatically when a custom
element is added to the DOM.
This marks the point where the component becomes active and begins its operational
lifecycle.
This stage is aligned with the toProcess, atProcess, and
inProcess states, which provide a structured sequence for initialization,
rendering, and post-render logic.
This structured approach ensures that components are consistently initialized and
rendered in a predictable order, reducing errors and improving maintainability.
connectedCallback โ toProcess
When the component is first attached to the DOM, it enters the toProcess
state.
This marks the beginning of the active lifecycle, where the component validates
prerequisites and prepares resources, but no rendering has yet taken place.
connectedCallback โ atProcess
Immediately after prerequisites are resolved within connectedCallback, the
atProcess state runs.
The component has reached the point where rendering logic is about to be executed.
connectedCallback โ inProcess
This state occurs after the component has completed its rendering phase. The DOM is now fully available for manipulation, and all initial behaviors are active. At this point, logic that depends on the rendered structure, such as querying the DOM with querySelector, setting focus, or attaching runtime event listeners can be safely executed.
adoptedCallback
The adoptedCallback is a lifecycle method that is called when a custom
element is moved from one document to another, such as between iframes or windows.
attributeChangedCallback
The attributeChangedCallback is a lifecycle method in Web Components,
specifically in the Custom Elements API.
It's used in custom HTML elements to detect when one of the element's observed
attributes has changed.
disconnectedCallback
The disconnectedCallback is a lifecycle method thatโs called when a custom
element is removed from the DOM.
๐ Overview
The Modular Cube component lifecycle defines how components transition through
initialization, configuration, rendering, and cleanup.
It combines the standard Web Component lifecycle methods with custom internal states
preProcess, toProcess, atProcess, and
inProcess to ensure predictable behavior, structured processing, and safe
DOM interactions throughout a componentโs existence.
The component lifecycle in Modular Cube unifies the standard Web Component callbacks with additional custom states. This approach establishes a predictable sequence in which configuration is validated, resources are prepared, rendering takes place, and post-render behavior becomes available. By following this structured progression, components remain consistent, modular, and easier to maintain, regardless of complexity or use case.
๐๏ธ Project Structure
Overall Folder Organization
- A project consists of a set of files and folders that can be organized in a consistent structure.
- ๐น
Configuration files, initialization logic, and the main entry point reside at the root level.
- ๐น
UI components are grouped within the
app/directory. - ๐น
Supporting folders such as
static/,modules/, andservices/are used to manage assets, reusable functionality, and core application logic.
This organization establishes distinct responsibilities for different parts of the project, making it easier to navigate, maintain, and extend over time.
Application Configuration (app.config.json)
To make a component available to the application, it must be registered in the global
application configuration file: app.config.json.
This setup allows the framework to dynamically load and define the components at
runtime.
The application configuration file app.config.json contains a root object
named modularCube, which describes both the application entry
point and the components that will be registered.
๐ก Notes
The application attribute is optional. Its purpose is to define the root
application container.
-
When the application is initialized using
Dom.init(), it first looks at thecomponentsattribute list. If an entry component (for instance,app-root) is defined there, it will be instantiated as the root. -
If no entry component is found in the
componentsattribute list,Dom.init()will then check whether anapplicationattribute exists. If present, theapplicationwill be used to define and initialize the root container.
Component Initialization (init.js)
The init.js file is the bootstrap script.
Its job is to initialize your application, load the configuration, and register
components before rendering.
After defining and registering all components, the application must initialize the
system using the Dom.init() method.
By default, app.config.json should be placed at the same folder level as
init.js.
If no parameter is provided, the initializer will look for it automatically.
If the configuration file is stored elsewhere, you can provide its path explicitly:
Entry Point (index.html)
The index.html is the root document of your project.
It loads the initialization script and acts as the starting point for rendering UI
components.
To ensure components are initialized properly at application startup, the
init.js file must be imported in the main HTML file.
The import map, initialization script, and root component provide the foundation of the
application.
The index.html file serves as the starting point where these elements are
brought together to initialize and render the user interface.
๐๏ธ Component Setup
Component File Structure
Each component in Modular Cube is encapsulated using the Shadow DOM to ensure scoped styles and isolated behavior. By convention, a component can be composed of four main files:
The framework allows you to keep HTML and CSS in separate files
for clarity.
Component Files
- A Modular Cube component is built from a small set of well-defined files, each responsible for a specific concern. This separation of structure, styling, configuration, and behavior promotes clarity and maintainability. By convention, every component consists of four files:
- ๐น
A configuration file
(.config.json)to declare metadata, file paths, and runtime options. - ๐น
A CSS stylesheet
(.css)to provide encapsulated styles. - ๐น
An HTML template
(.html)to define the componentโs structure. - ๐น
A JavaScript module
(.js)to implement the componentโs logic and lifecycle.
Together, these files ensure that each component remains self-contained, easy to reason about, and reusable across different parts of the application.
Component Files โ Configuration (.config.json)
The configuration file defines metadata, file references, and runtime behaviors for the
component.
It specifies the paths to the associated HTML and CSS files,
along with options such as appendToBody, lazyLoading, and
debug.
Component Files โ Styling (.css)
The stylesheet provides styles scoped to the component through the Shadow DOM. This ensures that styles remain encapsulated and do not leak into the global document. Keeping styles in a separate file helps maintain a clean separation between structure, logic, and presentation.
Component Files โ Template (.html)
The HTML template defines the componentโs structure and static markup. It serves as the foundation of the componentโs UI, which is later combined with the stylesheet and logic during initialization. Using an external template file improves readability and keeps layout concerns separate from logic.
Component Files โ MyComponent (.js)
The JavaScript file implements the componentโs logic, lifecycle, and behaviors.
It loads the configuration, processes the referenced HTML and
CSS files (via preProcess()), and manages dynamic
interactions.
This file is responsible for defining how the component behaves.
Each of these files plays a specific role in defining a component.
The configuration file describes its metadata and behavior, the
CSS handles encapsulated styling, the HTML defines its
structure, and the JavaScript manages its logic and lifecycle.
Together, they provide a clear and modular approach to building self-contained,
maintainable components.
๐งฉ Using Components
HTML
Directives
HTML directives provide a declarative way to extend component templates by using attributes. They make components easier to read and maintain by clearly expressing intent in the markup. Directives support dynamic binding, allowing variables, expressions, or configuration values to be injected directly into the template. They can also control behavior, such as managing conditional rendering, iterating over collections, or binding events to elements.
Directives โ Variable
Variables in Modular Cube templates are expressed in two complementary forms: template interpolation and parameter injection. Both approaches allow component data to be incorporated into the DOM in a controlled and explicit manner, but they serve distinct purposes.
Directives โ Variable โ Template Interpolation
The template interpolation enables the embedding of
JavaScript expressions directly within HTML content, using the
${this.expression} syntax.
This mechanism allows dynamic rendering of component state and computed values inline
within native HTML templates.
Interpolation is resolved at render time and evaluated within the current data context
(typically the component instance this or the shadow root scope).
- ๐น
Only valid JavaScript expressions are allowed. These must reference properties or methods available in the current scope.
- ๐น
Functions used within expressions must be side-effect-free and return a value.
- ๐น
Expressions should remain simple and easy to read. Complex logic or deeply nested expressions should be avoided.
๐ Constraints and Best Practices
๐ Syntax & Supported Contexts
Expressions are enclosed in $ { expression }:
- Text content within HTML elements.
- Attribute values (
class,title,placeholder, ... ). - Class attribute for dynamic class names.
- Inline styles via the style attribute.
Inspector View (Elements)
Directives โ variable โ Parameter injection
The parameter injection feature provides a mechanism to
inject parameter values directly into templates.
Unlike interpolation, which operates inline, parameter injection designates explicit
placeholder elements that are fully replaced with evaluated values during the initial
rendering.
The <param value=""> element is used as a placeholder for injecting
parameter values into HTML templates.
At render time, the placeholder is replaced by the evaluated parameter, and the
<param value=""> tag itself does not persist in the DOM.
- ๐น
Each
<param>element with avalueattribute is replaced with the current value of the corresponding parameter during the initial render. - ๐น
Parameter values are evaluated from the componentโs declared parameter scope.
- ๐น
Complex or computed values should be resolved before assignment to parameters.
- ๐น
The
<param>tag is a placeholder element and does not produce standalone DOM elements after rendering; it is replaced entirely by the parameterโs value.
๐ Constraints and Best Practices
๐ Syntax & Supported Contexts
Parameter injection is expressed using the
<param value=""> element.
- Unlike template interpolation (
${this.expression}), parameter injection cannot be used inside attributes such asclass,style, ortitle. - The
<param>element is limited to injecting values directly into DOM content.
Inspector View (Elements)
Together, interpolation and parameter injection provide complementary approaches for embedding dynamic values into component templates. While interpolation supports inline expressions within attributes and text nodes, parameter injection offers a direct mechanism for inserting parameter values into the DOM.
Directives โ if / else if / else
The if directive provides conditional rendering in HTML templates using declarative expressions. It enables developers to control whether a given element and its children should be rendered based on the evaluation of a boolean condition.
- ๐น
Single Condition Per Element: Each element can only have one conditional directive (
if,elseIf, orelse). - ๐น
Evaluation Order: Conditions are evaluated top-to-bottom. The first matching branch is rendered; subsequent branches are skipped.
- ๐น
Mutual Exclusivity: Only one element in a chain (
ifโelseIfโelse) is rendered at a time. - ๐น
Expression Validity: Conditions must resolve to a boolean value or an expression that can be evaluated to true/false.
- ๐น
Clarity Over Complexity: Keep conditions simple and readable. Prefer computed properties or helper methods for complex logic.
- ๐น
Mutual Exclusivity: Only one element in a chain (
ifโelseIfโelse) is rendered at a time.
๐ Constraints and Best Practices
๐ Syntax & Supported Contexts
Conditional directives are expressed as HTML attributes on elements and evaluated at render time:
if="${this.expression}"โ Renders the element only if the expression evaluates to true.elseIf="${this.expression}"โ Renders the element if all precedingif/elseIfconditions are false and this expression evaluates to true.elseโ Renders the element if all precedingif/elseIfconditions are false.
Supported Contexts:
- Directly on standard HTML elements in the template.
- Nested structures, allowing chains of
ifโelseIfโelse. - Expressions are evaluated in the component instance scope
thisand may reference component properties or methods.
Inspector View (Elements)
Inspector View (Elements)
Inspector View (Elements)
๐ก Notes
In JavaScript, you can absolutely use if, else if,
else if without a final else.
The else block is completely optional.
- โ
You can have just
if - โ
You can have
if...else - โ
You can have
if...else if...else - โ
You can have
if...else if...else if(with or withoutelse)
The if directive allows declarative, structured control
of what elements are rendered based on logical conditions. Support for
else if, else, and nested conditionals provides flexibility
while maintaining clear and predictable rendering behavior.
The use of native HTML syntax and controlled evaluation reinforces clarity, performance,
and consistency with modern web development practices.
Directives โ forEach
The forEach directive in enables declarative iteration over collections within HTML templates. It renders a repeated structure for each item in a given array or iterable, following a clear and scoped expression pattern. This approach brings structured, readable list rendering to markup using standard JavaScript expression syntax. This directive is designed to integrate seamlessly with the component's data context and maintain clarity in both simple and nested list structures.
- ๐น
Scoped Variables: The loop variable is only valid inside the iteration block. It should not conflict with variables declared in outer scopes.
- ๐น
Combined with Directives: Loop-generated elements can also use conditional directives (
if,elseIf,else) within the iteration body. - ๐น
Static and Dynamic Data: Works with both static arrays defined at initialization and dynamic data updated during component lifecycle.
๐ Constraints and Best Practices
๐ Syntax & Supported Contexts
The forEach directive is expressed as an HTML attribute and enables iteration over iterable data structures:
${this.forExpression}โ Repeats the element for each value in the iterablethis.items, binding the current value to the loop variable.
Supported Contexts:
- Applied to any HTML element as a directive attribute.
- Loop variable may be referenced inside the repeated element using interpolation
(
${this.forExpressionItem}) or parameter injection (<param value="${this.forExpressionItem}">). - Iteration supports arrays and any iterable object in JavaScript.
- Nested iterations are allowed, with each loop maintaining its own scope.
Inspector View (Elements)
The forEach directive offers a concise and powerful way to generate HTML content dynamically based on collection data. With native expression support and clear scope handling, it supports structured iteration at any depth and promotes maintainable template design. Repeated content is easy to define and aligns with modern rendering practices through direct integration with JavaScript evaluation and native web capabilities.
Events
HTML directives support binding JavaScript event handlers directly within your markup
using a simple and consistent syntax.
It handle DOM events like click, input, keydown,
mouseenter, and more.
These bindings follow standard JavaScript event behavior but are declared directly in
the template, no need for addEventListener or inline onclick attributes.
- ๐น
Use the format:
placeholderEvent="this.functionCall(...)". - ๐น
The event name must be lowercase and match a standard DOM event (e.g.
click,input,keydown). - ๐น
You must append
Eventto the event name:clickEvent,inputEvent,keydownEvent, etc. - ๐น
The value must be a valid JavaScript function call (with or without arguments).
- ๐น
The
$eventobject can be passed to access native event data.
๐ Important Rules
Inspector View (Console)
๐ก Notes
- โ You can bind any number of events to an element.
- โ Any function accessible in the componentโs scope can be used.
- โ
$eventgives you access to native event details (like target, key, etc.). - โ Do not use
onClick,onInput, etc. โ useclickEvent,inputEvent, etc. instead. - โ
Event bindings can be combined with
if/else if/elseandforEachfor dynamic UI behavior.
CSS
Directives
CSS directives provide a way to make component styling more flexible and maintainable by supporting variable substitution and scoped customization. They enable styles to adapt dynamically at runtime without breaking encapsulation.
Directives โ variable
Template interpolation enables the embedding of JavaScript expressions directly within
CSS content, using the ${this.expression} syntax.
This works similarly to HTML template interpolation, allowing you to bind JavaScript
properties or return values directly into your styles at render time.
- ๐น
Expressions must be valid JavaScript and scoped to the current component (
this.propertyorthis.method()). - ๐น
Only values that result in a valid CSS value are allowed (colors, units, keywords).
- ๐น
Function calls must return a value and must be pure (no side effects).
- ๐น
You can interpolate in inline styles, style blocks, or custom properties (e.g.,
--my-color: $ {this.color}). - ๐น
Do not use interpolation inside CSS selectors or media queries, only in property values.
- ๐น
Keep expressions simple and readable. Avoid chaining or complex logic inside styles.
๐ Important Rules
Inspector View (Elements)
๐ก Notes
- CSS interpolation works at render time, changes to reactive properties will automatically reflect in styles.
- This feature is framework-specific and not standard browser behavior. It is optimized for Shadow DOM scoping and dynamic styling needs.
- Only string-compatible values will work, no objects, arrays, or DOM references.
- You can use component-scoped CSS variables for theming or design tokens,
--theme-accent: $ {this.accentColor}.
JavaScript
Observable
The framework includes a lightweight Observable utility for managing event-based communication between components or logic blocks. This pattern allows you to decouple parts of your application by subscribing to and publishing named events, similar to a pub/sub model.
- ๐น
subscribe(name, subscriber): Register a function to run when a named event is published. - ๐น
unsubscribe(name): Remove a previously registered event handler. - ๐น
publish(name, payload): Trigger all subscriber callbacks for the given event name, passing in an optional payload. - ๐น
Each event supports a single active subscriber, subsequent calls with the same name will replace previous ones.
๐ Core Concepts
๐ก Notes
- Component A notifies Component B to refresh data.
- This is a global system, use unique event names to avoid collisions.
The Observable system can be used for reactive data handling, custom event broadcasting, or integrating cross-component behaviors in a clean, manageable way.
๐ Changelog
Initial Beta Release
- Added
- Initial ModularCube beta release.
-
Base
HTMLComponentclass with Shadow DOM support. -
Structured component convention using
.js,.html,.css, and.config.json. -
Component registry through
app.config.json. -
Global
Dom.init()initialization mechanism. -
Support for
lazyLoading. - Template interpolation within HTML content and CSS.
-
Conditional template directives:
if,else if, andelse. -
forEachtemplate directive for repeated content. -
Initial component lifecycle:
preProcess()โtoProcess()โatProcess()โinProcess().
- Work in progress
- Targeted Updates โ scoped and localized DOM updates.
-
Support for
apendToBody.
- Planned
- Reactive Data Binding โ automatically synchronize DOM content with changing data.