Summit.directive

Summit.directive adds a new s- attribute to Summit. Your directive runs when Summit initializes an element that carries it, with the same utilities the built-in directives use, so a directive you write is a first-class citizen.

#Registering a directive

Call Summit.directive(name, handler, priority?). The name is used without the s- prefix. This registers s-tooltip:

Summit.directive("tooltip", (el, meta, utils) => {
  utils.effect(() => {
    el.setAttribute("title", String(utils.evaluate(meta.expression)));
  });
});

<button s-tooltip="'Copied ' + count + ' times'">Copy</button>

Summit.directive returns the Summit global, so registrations chain.

#The handler signature

The handler receives three arguments: (el, meta, utils).

el is the element the directive is on.

meta describes how the attribute was written:

• name, the directive name without s- (here, "tooltip").
• value, the part after a colon, or null if absent ("click" in s-on:click).
• modifiers, the dot-separated modifiers as an array (["prevent", "stop"]).
• expression, the attribute's value string, ready to pass to evaluate.
• raw, the original attribute name as written in the DOM.

utils is the directive author's toolkit:

• evaluate(expression) runs a value expression in the element's scope.
• evaluateAction(expression, locals?) runs statements (like an s-on handler), optionally with extra local variables.
• effect(fn) creates a reactive effect that re-runs when its dependencies change and is torn down automatically with the element.
• cleanup(fn) registers a teardown callback.
• initTree(el, scopes?) and destroyTree(el) initialize or tear down a subtree, used by structural directives that manage their own children.
• scopes is the scope stack visible at this element.
• makeEnv(el, locals?) builds a fresh evaluation environment for an element.
• Summit is the global itself.

Use effect for anything that should react to state, and cleanup for anything that must be undone (a listener, a timer). Errors thrown in a handler are caught and logged, so one broken directive will not stop the rest of the page.

#Priority

The optional third argument sets ordering. When an element has several directives, lower numbers run earlier. The default is 100, so pass a smaller number to run before most directives and a larger one to run after:

Summit.directive("setup", handler, 0); // runs early, before default directives

#Timing

Registration is timing-safe: register before or after Summit.start. Built-in directives are registered when Summit loads, and registering a custom directive with the same name overrides the built-in.

For a fuller walkthrough, see Writing directives and plugins.