@crescentjs/crescent NPM

Crescent was designed with existing existing projects in mind. Allowing you to pick up and start designing components with no setup time.

Crescent has a very small scope, the creation and managment of reactive components using Handlebars. No more, no less.

Components

Components are broken down into two types, partial and root. You do not need to worry about declaring one or the other as they are both interchangeable and the library will decide for you based on its role.
With Crescent only what is needed is reproduced. When a component needs updating only that component is reproduced and rendered. Children and parents are ignored.

Partial Components (aka child components)

Simply put partial components are components intended to be loaded as children.
Unlike in standard Handlebars templates partials are loaded using the Component helper function.

{{Component 'CompName' passedString='string value' passedObject=obj}}

All partial components are single file components.

Simple partial component that takes in an array of strings and displays it preceded by a string "str" in the local context.

<script type="text/x-handlebars-template">

    <ul class="list-group list-group-flush">
        <li class="list-group-item">{{str}}</li>
        {{#each $args.attrs}}
            <li class="list-group-item">{{this}}</li>
        {{/each}}
    </ul>

</script>

<script>
    var component = Component({
        args: {
            attrs: "object"
        },
        context: {
            str: "Some String",
        },
        Ready: function ()
        {
            setTimeout(() => { this.str += " Modified!"; }, 2000);
        }
    });
</script>

Root Components

Any component loaded directly to the page is considered a root component. Root components play a vital role. Along side the executing context they make a component chain unique, allowing you to create duplicate child components.

At their core root components are no different than partial components and are completely interchangable. The main difference is the role they play in the rendering chain.
A root component is responsible for not only rendering itself on the page but also for rendering all child components that do not have an existing DOM structure.
Meaning that a child/partial does not perform the initial draw of its own DOM. It is not until the DOM exists that a child component is ready to take control. This is an important
concept to understand as it affects the flow of events (see event stream below).

Eval helper

The use of the eval helper isn't as much of a performance killer as you might think. The gloabal eval method is only used once on the initial call. After which the string and resulting function are both cached for future lookups.
This is not to say its use should be encouraged. It's an eye sore and complex logic really belongs in the components context rather than inline. Eval statments are wrapped in a function declaration. 'this' is set to the executing context. The param 'args' is available and holds any hash values passed to the helper.

Reactive CSS Templating

With Crescent you can not only create reactive html but reactive css. Just use a style tag inside a component and template it like any other handlebars template. Favor more tags with less rules over larger tags with more rules. Performance is directly proportional to the size of each style declaration.
Templating styles also allows you to create unique rules for each component.

Unique Reactive CSS Rule:

<style>
    .reactiveCss-{{id}} {
        {{#if active}}
            background-color:red;
        {{else}}
            background-color:blue;
        {{/if}}
    }
</style>

Compiling

To improve performance you should consider pre compiling your templates. Better yet you should use the packager below.

crescent -c <file or directory>

Packaging

Crescent has its own packaging tool. No need for webpack! Components loaded through packages pass a compiled function rather than a string to the promise returned by IncludeComponent. Beyond loading much quicker, packages come with the benefit of not needing the eval function. This is the largest performance improvment you can do for crescent components.

Consider keeping your packages small. Only include the components that are needed for the initial load and allow the others to lazy load. You can still compile them seperately or just leave them as html.

To use the packaging tool create a crescent.json in the root file of your components.

Example crescent.json:

{
    "root": "/", //prepended on every component path
    "output": "component_packages", //output folder that will hold the packages
    "packages": [
        {
            "name": "testPackage", //output file name for this package
            "components": [
                "singleFileRoot.html",
                "components/alerts/basic.html",
                "components/cards/card_with_attr/card_with_attr.html",
                "components/cards/card_with_attr/attributes.html"
            ]
        }
    ]
}

Run in the directory containing crescent.json:

crescent -p

Include a component from a package

IncludeComponent("/components/cards/card_with_attr/attributes.html", "CardAttributes", "testPackage");

Notes

When inside a method within the context. 'this' is assigned to the context itself.
Any code executed in a component outside of a context method will execute immediately after the include is evaluated. 'this' references the component.

Handlebars Notes