The block DSL

Overview

A block is a web/configurations/components/<id>/ folder (or fragments/<id>/). When that folder holds a tree.json whose root carries a primitive key, the page renders the block from that tree: its shape, copy, state, computed values, validation and actions are JSON, read by an engine shared by every project. The DSL is that engine's closed vocabulary. A key it does not know is ignored, with no error message.

What a tree.json renders: a bakery demo's order block, with the cart, the pickup slot and the summary.

A page mounts the block from its structure.json, by folder id: a component node reads components/<id>/, a fragment node reads fragments/<id>/.

Static block, interactive block

Two engines render a tree. A static block is rendered on the server, without JavaScript, and only understands {slot} text markers. A block becomes interactive as soon as its root carries logic, state, actions, onMount, derive, watch or effects, one of its nodes carries on, when, unless or repeat, or a logic/<id>/bindings.json file declares calls. It then goes to the interactive engine, which runs in the browser, and everything below applies.

Tree nodes

A node is a JSON object. The root of tree.json is a node like the others, which also carries the behavior keys described in The block root.

Node types

Primitives

A wrapper's attributes go through a closed list: className, id, role, hidden, inert, tabIndex, title, disabled, data-* and aria-*, style (an object, filtered like a styleJson) and, on an SVG element, its geometry attributes (viewBox, d, fill...), plus ref and region. Others are dropped without an error. Write ARIA with a dash (aria-label, aria-pressed); the ariaLabel form is converted.

A field whose value is bound without an input or change event is rendered read-only. Checkbox, Radio and SliderCheckbox are driven by checked, not by value.

Embedding another block

A fragment node mounts a block by its name: a project block (its id) or a block provided by Kubbler (its name, for example StripeCheckoutForm). props.__variantId picks an id other than the name, and the other props replace its options.json. pass hands it resolved properties; a { "action": ... } value becomes a function that runs that action in the parent block, the received value being readable as $arg. name and __variantId accept a $ref.

Tree writing rules

• Every node carries a primitive (a string) and an id matching [A-Za-z0-9_-]+, unique in the tree.
• Maximum depth: 64 levels. At most 2000 nodes.
• children is a list. The keys __proto__, constructor and prototype are refused.
• The Workshop checks these rules on every write of the file: a tree.json or slots.json that breaks them is refused (400).

Copy: slots and dictionaries

Block copy is not written in clear in the tree. The tree carries a {slot} marker, slots.json declares the slot, and each language dictionary holds its value.

A slot's dictionary key is <slot>_<suffix>. The suffix is the last segment of the block id after its last dash: the orderFlow block gives _orderFlow, an order-flow block would give _flow. The block's dictionaries are merged into the page's when the view lists the block in its structure.json.

Slots in the Inspector: each text of the block with its <slot>_<suffix> key (titleA_homeHero, subtitle_homeHero) and its value.w/[wsSlug]/p/[slug]?sel=ui:{id}

How a marker resolves

• {x}, when x is a slot of the block: the engine reads the key x_<suffix>. If it is missing, an interactive block shows the slot's defaultValue, a static block shows need_trads.
• {x}, when x is not a slot: the engine reads the key x as is in the page dictionary; if that is missing too, it shows x.
• {$path}: the key is the value read at $path, then the same resolution applies. This is how a block shows a label chosen by its configuration.

In the grocery demo, options.json lists the aisles; each aisle names its title by a slot id (aisleFl). The tree writes {$a.title} inside the loop: the value aisleFl is a slot, so the text shown is the one under the key aisleFl_productList.

Text goes in props.text, or as a string in children when it sits between nodes. A string can mix fixed text, values and keys: "x${it.quantity}", "${p.name}, ${v.label} : {addedToast}".

Values and operators

Every value in the tree (a prop, a condition, an action argument) is resolved at render time, or when the action runs, according to its form:

The scope

The scope is the set of names a $path can read. From weakest to strongest (a stronger name hides the same weaker name):

• store: the site memory, read as $store.<name>Reducer.<path>.
• locale: the page language, read as $locale.
• The keys of options.config, then of options.fragments: config.aisles is read as $aisles.
• The behavior hook's return value, if there is one.
• The state atoms.
• The derive values, computed in the order they are written.

Depending on context, the scope also holds: the variables of a repeat (the item, index, n, isFirst, isLast, count), $event inside an action, the result named by as, $prev and $next inside a watch, $arg inside an action passed through pass.

Operators

An operator is an object with exactly one key, and that key is an operator name. Its arguments are written as a list (a single argument may skip the list) and are resolved before the call, so an operator can contain another one. when, unless, where and an action's when treat an empty list as false; everywhere else, and so inside not, and, or and if, a value is true in the JavaScript sense, and an empty list is true there: test a list with empty. The operator list is closed:

The block root: state, computed values, validation

Besides its node keys, the root of tree.json carries the block's behavior:

state

Each atom is read as $atom and written by the set action. A dotted name writes into an object atom ("set": "form.email"). Validation writes a field's message into the <field>Error atom; the demos declare it as "".

derive

A derive calls a named function with arguments resolved in the scope (args may be a single value). The derive entries are computed in the order they are written, and each one reads those before it: a derive that reads one declared further down receives undefined, which numeric functions count as 0. An unknown function gives undefined. The function list is closed:

A price simulator chains its computations from top to bottom; waste is a boolean, which mul counts as 1 or 0:

validate

validate maps each field (a state atom) to a list of rules, tried in order: the first one that fails gives the field's message. A rule is written { "rule": "<name>", "args": [...], "error": "<key>" }; with "when": <condition>, it only applies when the condition is true. Validation only runs through an action (validate or validateAll): it clears <field>Error for every checked field, then writes the text of the error key there, or the key itself when the dictionary does not hold it.

Behavior in JavaScript

When the DSL is not enough, a useLogic hook completes the block. The engine looks for web/configurations/logic/<id>/index.js (the block id), then for the Kubbler-provided behavior named by the logic key. The hook receives { name, id, options, dictionary, args }; what it returns joins the scope: a value is read as $name, a function is called through the call verb or by its name. A few-line hook is enough to expose a route parameter:

onMount and watch

onMount runs an action once, in the browser, after the first render, with that render's scope. watch maps a value to an action: the value is read again on every render, and the action runs when it has changed (never at mount), with $prev (the old value) and $next (the new one). This is how a block reacts to a change in the site memory.

At mount, the chosen store may not be known yet: skipEmpty does not send an empty storeId, and the watch fetches the slots again as soon as currentId changes.

refs declares element references ("refs": ["field"]), which a node receives through "ref": "$field". effects attaches a named effect to one ({ "fn": "autofocus", "ref": "field" }), run at mount and again when its when value changes.

Conditions, lists and events

when and unless

when renders the node when its value is true, unless when it is false. The value can be any DSL value: a $ref or an operator. A hidden node is not rendered at all, neither it nor its children.

repeat

repeat renders the node once per item of over. A value that is not a list renders nothing.

Each iteration exposes the item under its name, index (from 0), n (from 1), isFirst, isLast and count (the number of rendered items). "unless": "$isLast" on a node inside a repeated group places a separator between items.

on

on maps an event to an action. The engine wires these events, and $event.value holds:

input and change wire the same React handler (onChange): on a text field, both fire on every keystroke. A set without to writes $event.value: { "set": "email" } on input keeps the atom up to date, and the second step clears the error message.

To react to a single key, guard the action with a condition: { "when": { "eq": ["$event.value", "Enter"] }, "then": "submit" } on keydown.

Actions

An action takes one of three forms:

• A string: the name of an action in actions; failing that, a behavior function, called with no argument.
• A list: actions run one after the other; each step waits for the previous one to finish, API calls included.
• An object: one or more verbs.

Inside an object, verbs always run in this order, whatever order they are written in: when, validate, validateAll, set, toggle, forEach, call, dispatch, fetch, reset, navigate, toast, then then.

An object stopped by when, validate or validateAll goes no further, but the list that contains it carries on. A validation written alone in one step therefore does not prevent the next step: write the validation and the submission in the same object.

What an action chain reads

An action reads the scope of the render the event came from. A set changes the state for the next render, not for the following steps of the same chain: $atom keeps its old value there, so does validate, and $store stays as it was before a dispatch. To chain on a result, name it with as; to react to a memory change, use watch.

A complete save: the empty with keys listed in skipEmpty are not sent, the result is named created, and the rest shows a message then opens the created record, or sets an error message.

The site memory and the project's API

The site memory (the Redux stores) is declared in web/configurations/stores/stores.json. Each entry creates a memory named <name>Reducer.

A thunk calls a route of the project's API and returns its response as is, { status, body }: it does not throw on a 4xx or 5xx status. The actions/<thunk>/index.js file decides what the memory keeps.

From the tree

A tree reads the memory through $store.<name>Reducer.<path> ($store.cartReducer.items) and renders again when it changes. It acts on it through the dispatch verb:

A thunk result, named by as, has the shape { result: { status, body }, thunkDuration }: read $res.result.status and $res.result.body. It is undefined when the call failed (network down) or was cancelled; the rest of the action still runs, with an else branch for that case.

Calling the project's API

• The route exists in the project's API: here POST /orders/submit, in the orders group.
• stores.json declares the thunk in cases, with its two files thunks/ and actions/. The thunk targets the endpoint1 entry of api.json and the route path.
• The tree runs { "dispatch": { "store": "ordersReducer", "thunk": "submitOrder", "with": { ... } } }, then reads the response through as or through $store.ordersReducer.

Where the order lands: the orders collection in the Workshop's Data, one order open in the Inspector.w/[wsSlug]/p/[slug]?sel=data:col:orders

The fetch verb calls a route without a thunk: path (resolved), endpoint (an api.json entry, endpoint1 by default), method, params (the query string), body and into. The response is written into the atom named by into, with <into>.loading and <into>.error. GET reads; any other method is sent as POST, with body or, failing that, the whole local state of the block. A web/configurations/logic/<id>/bindings.json file can declare these calls outside the tree, { "calls": [{ "endpoint", "path", "method", "into", "trigger" }] }: without trigger (or with "mount"), at mount; otherwise after the action of the same name.

Complete example: an order flow

The bakery demo sells cakes for in-store pickup. Its orderFlow block (web/configurations/components/orderFlow/) chains the cart, the choice of a pickup slot, the contact details and payment, with no block-specific JavaScript. The commander page mounts it through a component node with id orderFlow.

The orderFlow block inspected in the Mechanisms: its tree.json, 15 state variables, 3 actions, and the two routes it calls (listSlots, submitOrder).w/[wsSlug]/p/[slug]?sel=map:behavior:orderFlow

State and computed value

The root declares the form atoms (date, pickupAt, pickupLabel, customerName, email, phone, note), one message atom per validated field, three step messages (cartError, pickupError, submitError) and two copy atoms (snapshot, snapshotTotal). A single computed value: minD, today plus two days, set as the min of the date field to enforce 48 hours of notice. The block root section shows the full state and the validation of customerName and email.

The cart comes from the memory

The cart is not in the block state. It lives in the cart memory, kept in the browser (persist: true) and filled through the synchronous addItem action from the home page and the cakes page. The block reads it (repeat over $store.cartReducer.items, total $store.cartReducer.total formatted in euros) and changes it through its synchronous actions incrementItem, decrementItem and removeItem, with "layer": "statics" and the line id as arg.

The pickup slot

The date field writes date, then calls the pickDate action with the same event. pickDate clears the chosen slot and, when a date is set, runs the fetchSlots thunk with { "date": "$event.value" }. Depending on the orders memory, the block then shows a loading message (status is "loading"), a message when the list is empty, or one button per slot. A click calls pickSlot, which copies $s.value and $s.label; the chosen button gets aria-pressed and the is-picked class (see the join example in Values).

Paying

The pay action is a list of four steps. The first three set the messages: submitError cleared, cartError depending on whether the cart is empty (when, then, else), pickupError when no slot is chosen. None of these steps stops the others: all messages show at once.

The fourth step carries the whole submission in a single object. Its when requires a non-empty cart and a slot; validate checks the name, email and phone and stops the object if one fails; dispatch sends the order to the submitOrder thunk. note goes through { "if": ["$note", "$note"] }: when empty, it is undefined and the key is not sent, since JSON does not write an undefined value.

The result is named order. When the response carries a providerSecret (looked up in two places with or, since the response may wrap it in data), the block copies the cart and its total into snapshot and snapshotTotal, hands the secret to the payment memory (setProviderSecret), then empties the cart (clearCart). The copy reads the cart from the render the click came from, so before it is emptied. Otherwise submitError receives {errSubmit}; a network error gives an undefined result and takes the same branch.

The payment screen

Moving on to payment is not a block atom: it is $store.paymentReducer.providerSecret. The form steps carry "unless": "$store.paymentReducer.providerSecret", the paying node carries the opposite when and embeds the paymentStep block through a fragment node. The summary reads the cart until payment has started, then snapshot, and the total follows the same rule with an if:

Limits and pitfalls

What the DSL does not do, and the mistakes that produce no message.

No route parameter in the scope

The scope contains neither the dynamic route segments (devis/[id]) nor the query string. A few-line hook, web/configurations/logic/<id>/index.js, exposes them: the page passes it args, which carries locale, pathname and one field per dynamic segment (see Behavior in JavaScript). For the query string, the hook reads it with Next's useSearchParams.

No division, no rounding

For arithmetic, derive offers add, mul and clamp: no subtraction, no division, no rounding. A subtraction is written add(a, mul(b, -1)), a division mul(a, 0.01) (the inverse of the divisor). The only rounding is amountFromCents, which rounds to the unit and returns a text: multiply by 100 first to round an amount to the euro. A configurator computes a price, a deposit and a balance this way:

The CSS specificity of styleJson

styleJson styles are compiled into the /* forge:nodes:start */ ... /* forge:nodes:end */ region of the block's style.css, under a doubled selector carrying the block id and the node id: [data-forge-id="orderFlow--root"][data-forge-id="orderFlow--root"], with a specificity of (0,2,0). The region is appended at the end of the file, after the hand-written CSS. A one-class rule (.orderFlow-pay) loses against it; a two-part rule (.orderFlow-slot.is-picked, .orderFlow-pay:hover) loses too, at equal specificity, because it comes first.

• A property that changes with a state (hover, an is-on class, :disabled) must not also be set in the node's styleJson: keep it in the class, or write the state in the hover, focus-visible or active blocks of the styleJson. In the demo, the payment button has no styleJson: its background, hover and disabled state live together in .orderFlow-pay.
• The blocks of a styleJson: base, hover, focus-visible, active, before, after, hover-before, hover-after, and the minimum-width thresholds sm (576 px), md (768 px), lg (992 px), xl (1200 px), xxl (1400 px).
• The region is rewritten by the tools that save the block (Workshop, API); the CSS outside the region is never touched. A styleJson edited by hand only shows once the region is recompiled.
• Every item of a repeat shares the node's data-forge-id: one rule reaches them all.

Other pitfalls

• when on a repeat node is evaluated before the list: filter with repeat.where.
• "as": "n", "index", "count", "isFirst" or "isLast": the item is overwritten by the iteration variable.
• A derive that reads one declared further down receives undefined, counted as 0.
• Input is text: eq compares without conversion, go through number.
• An empty list is false for when, but true inside not, and, or and if: test it with empty.
• A set is not visible to the following steps of the same chain.
• A validate alone in a step does not stop the next step.
• navigate does not prefix the language; Link does.
• fetch sends any method other than GET as POST.
• toast always shows an information-level message.
• A thunk missing from cases does nothing; an identical call repeated within 10 seconds of a failure is cancelled.
• An embedded block only gets its own dictionaries if it is also listed in the page's structure.json.