quark

CSS-like orchestration for your HTML — bind attributes, render lists, and wire events without a component tree.

Quark is a derivative of CSS, written in CSS syntax. Selectors, nesting, declarations and comments are CSS's own; the few additions Quark makes, such as variables, expressions and at-rules of its own, stay compatible with that syntax, so anyone who can read a stylesheet can read a sheet. What differs is the runtime: a stylesheet paints, a Quark sheet writes State — attributes, content and variables on the elements it matches. Media queries, keyframes and the rest of the browser's style engine stay in your stylesheet.

Prefer <quark-sheet> for apps; use the Quark class when you need a programmatic host (tests, tooling).

Features

• CSS-like sheets Selectors + nested rules that mutate the live DOM
• $variables Scoped values that nest and resolve in expressions
• JS writes element.quark.setProperty() hands values app JS already holds to the document as $variables
• CSS variables Write --custom-props from state; style via var()
• Content rendering content, template(), iterate(), dangerous-html()
• Element properties prop("provision") reads Neutron provisions / any JS property, re-running on assignment
• Events @on at-rules with delegation, key, timing and host options, plus prevent-default / stop-propagation
• View transitions @view-transition commits a block's writes inside document.startViewTransition(), so CSS animates list changes, removals included
• Delayed writes @delay 2000 { … } applies a block after a pause — flashes, toasts, undo windows — dropped if the rule stopped matching
• Diagnostics @warn / @debug / @error report from a rule; the selector is the condition
• Built-in modules @use "quark:math", quark:list, quark:map, quark:string, quark:date, quark:url, quark:util — pure helpers, imported like JS modules
• Attribute helpers dataset, ariaset, class, none to clear
• JS modules Pure functions from @use "/url", called in expressions
• Scoped host Sheet + targets share a parent; updates follow DOM mutations
• DevTools Quark.attachDevtools() reports rule applications and $variables to the Nucleus DevTools extension

Installation

<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/quark@0.4.1/dist/index.umd.min.js"></script>

npm install @excom/quark

import { /* … */ } from "@excom/quark";

Usage

App authors almost always load Quark through <quark-sheet>:

<section>
  <quark-sheet>
    details[open] [bind-status] {
      content: "Open";
    }
    details:not([open]) [bind-status] {
      content: "Closed";
    }
  </quark-sheet>
  <details>
    <summary>Panel</summary>
    <span bind-status></span>
  </details>
</section>

Programmatic API (tests / custom hosts):

import { Quark } from "@excom/quark";
​
const quark = new Quark({
  src: `span { content: "four times two equals #{twice(4)}"; }`,
});
quark.register({
  sheetElement, // host = sheetElement.parentElement
  modules: { dfault: { twice: (n) => n * 2 } },
});
// …
quark.unregister();

Documentation

Syntax

• Sheets & scoping — <quark-sheet>, @scope, is-global, what runs
• Syntax — rules, declarations, literals, operators, if()

Selectors

• Selectors — combinators and pseudo-classes, what is observed
• Reactivity — when a rule re-runs, loops, timing
• No reversion — write the inverse rule

Declarations

• Declaration kinds — what a key does
• Attributes — attributes, class / dataset / ariaset, form controls
• Content — content, template(), iterate(), dangerous-html()
• CSS variables — --custom-props

Values & expressions

• Variables — $variables, cascade, unset, raising state
• Writing from JS — element.quark.setProperty()
• Values & keywords — none / preserve / unset, wipes and no-ops
• Expressions — name resolution, operators, if(), lists and maps
• Built-in functions — attr(), prop(), iterate(), event, …
• Allowed methods — .toFixed(), .join(), …
• Built-in modules — @use "quark:math", quark:list, quark:map, quark:string, quark:date, quark:url, quark:util
• Element properties — prop("provision"), element

At-rules

• At-rules — the ones that run
• @use — JS modules, asynchronous work
• @on — events, blocks, options
• @dispatch / @command — outgoing events and commands
• @view-transition — animated writes
• @delay — deferred writes
• @warn / @debug / @error — diagnostics from a rule

Runtime

• JS API — Quark, whenSettled(), DevTools
• Loop guard — runaway chains are cut
• Limitations — beta limits and pitfalls

The grammar (EBNF, precedence, AST) is the quark-parser package's Language reference.

Examples

React to element state

Native element state drives content — no JS, no listeners:

List from a provider

prop("provision") pulls the fetch payload; iterate() renders a row per item and re-renders on every provision:

Call a module helper

<quark-sheet>
  @use "/helpers.js" as *;
​
  #out { content: formatPrice($amount); }
</quark-sheet>

Hand a value from app JS

App JS that already holds a rich value (feature flags, a messages dictionary) hands it to the document with element.quark.setProperty(), and every rule reading that $variable below the element re-runs. See Writing from JS.