+
Enable compass
-
+
+
No reading yet — click above. Requires a device
sensor (desktop browsers usually have none).
-
Waiting…
- @use "/demo-utils" as *;
-
- #orient-demo { @on neutron-provision (handle: setOutputFromElementData); }
+ provider-orientation {
+ $reading: prop("provision");
+ &[is-success] output {
+ content: if($reading.bearing != null: "Heading #{$reading.bearing.toFixed(0)}°"; else: "Listening — no reading yet.");
+ }
+ &[is-error] output { content: $reading.message or $reading; }
+ }
diff --git a/packages/provider-orientation/support/tests/__snapshots__/request.view.test.ts.snap b/packages/provider-orientation/support/tests/__snapshots__/request.view.test.ts.snap
new file mode 100644
index 0000000..14775b7
--- /dev/null
+++ b/packages/provider-orientation/support/tests/__snapshots__/request.view.test.ts.snap
@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`request view > listens on request, then prints the heading > complexity 1`] = `
+{
+ "attributeRuns": 1,
+ "closest": 0,
+ "getVar": 2,
+ "importNode": 0,
+ "listenerRuns": 0,
+ "matches": 3,
+ "parentElement": 3,
+ "quarkRuns": 2,
+ "queryScopeCost": 2,
+ "querySelectorAll": 2,
+ "removeAttribute": 0,
+ "ruleRuns": 3,
+ "schedulePaint": 1,
+ "setAttribute": 1,
+ "setVar": 1,
+ "textContent": 1,
+ "variableRuns": 1,
+}
+`;
diff --git a/packages/provider-orientation/support/tests/request.view.test.ts b/packages/provider-orientation/support/tests/request.view.test.ts
index 6b3a087..35ea62a 100644
--- a/packages/provider-orientation/support/tests/request.view.test.ts
+++ b/packages/provider-orientation/support/tests/request.view.test.ts
@@ -1,39 +1,50 @@
import { invokeCommand } from "@excom/neutron";
-import "@excom/event-handler";
import "@excom/quark-sheet";
import "../../index";
import {
afterEach,
- beforeEach,
describe,
expect,
it,
+ waitForEvent,
} from "@excom/heft-rig/profiles/default/config/test-utils";
import {
+ expectComplexity,
flush,
- installDemoModules,
+ measureComplexity,
mountView,
readDemo,
- restoreDemoModules,
} from "@excom/quark/support/tests/view-helpers";
+/** What an Android sensor reports: `alpha` from north, `absolute` set. */
+const turnTo = (alpha: number) =>
+ window.dispatchEvent(
+ Object.assign(new Event("deviceorientation"), { alpha, absolute: true }),
+ );
+
describe("request view", () => {
- beforeEach(() => installDemoModules());
afterEach(() => {
document.body.innerHTML = "";
- restoreDemoModules();
});
- it("starts paused and accepts a request click", async () => {
- const { root } = await mountView(readDemo(import.meta.url, "request"));
- expect(root.querySelector("provider-orientation")?.hasAttribute("is-paused")).toBe(
- true,
- );
+ it("listens on request, then prints the heading", async () => {
+ const { root, quark } = await mountView(readDemo(import.meta.url, "request"));
+ const provider = root.querySelector("provider-orientation")!;
+ const output = root.querySelector("output")!;
const button = root.querySelector
("button[command]")!;
+ expect(provider.hasAttribute("is-paused")).toBe(true);
expect(button.getAttribute("command")).toBe("--request");
- // happy-dom has no Command API: dispatch what the button would have
- invokeCommand(root.querySelector("provider-orientation")!, "--request", button);
+ // happy-dom has no sensor permission API: the request starts listening
+ invokeCommand(provider, "--request", button);
+ await flush();
+ expect(provider.hasAttribute("is-success")).toBe(true);
+ expect(output.textContent).toBe("Listening — no reading yet.");
+ const meter = measureComplexity(quark!);
+ await waitForEvent(provider, "provider-orientation-success", () => turnTo(270));
await flush();
- expect(root.querySelector("output")?.textContent).toBeTruthy();
+ const budget = meter.take();
+ meter.stop();
+ expect(output.textContent).toBe("Heading 90°");
+ expectComplexity(budget);
});
});
diff --git a/packages/provider-storage/support/demos/simple.html b/packages/provider-storage/support/demos/simple.html
index 47af416..a53b0f7 100644
--- a/packages/provider-storage/support/demos/simple.html
+++ b/packages/provider-storage/support/demos/simple.html
@@ -1,18 +1,18 @@
-
- Seed localStorage & re-read
-
-
-
Not read yet — click above.
+
+ Seeded at:
+
+
Seed localStorage & re-read
Same-tab writes only show up after
key-name is re-set; a write from another tab is picked up
live.
@use "/demo-utils" as *;
- :scope {
- @on demo-seed-storage (handle: seedDemoStorage);
- @on neutron-provision (handle: setOutputFromElementData);
+ provider-storage {
+ $stored: prop("provision");
+ output { content: $stored.seededAt or "never"; }
}
+ button { @on click (handle: seedDemoStorage); }
= new Set([
/**
* Quark's at-rules — the whole set. Each has a dedicated AST node and a
- * parse method; any other name (`@media`, `@if`, `@keyframes`, …) is a
- * parse error, since Quark is a derivative of CSS, not a superset.
+ * parse method; any other name (`@media`, `@keyframes`, …) is a parse
+ * error.
*/
export const QUARK_AT_RULES = [
"use",
diff --git a/packages/quark-parser/src/types.ts b/packages/quark-parser/src/types.ts
index e500040..5a3c3ab 100644
--- a/packages/quark-parser/src/types.ts
+++ b/packages/quark-parser/src/types.ts
@@ -388,7 +388,7 @@ export interface AtRuleBase extends BaseNode {
name: string;
}
-/** `@use "url" [as name | as *];`: a `with (…)` clause is a parse error. */
+/** `@use "url" [as name | as *];`: imports a JS module. */
export interface UseRule extends AtRuleBase {
name: "use";
url: string;
@@ -432,12 +432,11 @@ export interface EventName extends BaseNode {
* Quark's listener at-rule. Events are bare identifiers (`click`,
* `super-form-success`) or strings, comma-separated. An optional
* parenthesised options group follows (`(target: "li", once, handle:
- * save($draft))`; names are idents, values single expressions; a bare
+ * focusInput)`; names are idents, values single expressions; a bare
* name is a flag). Then either a block — an ordinary rule body the
* runtime applies once per event — or `;`. A statement without options
- * has nothing to do and is a parse error; a handler list after the
- * events (the pre-2026-09-13 form) is a parse error pointing at
- * `handle:`. `@off` was removed (parse error).
+ * has nothing to do and is a parse error; so is a handler list after the
+ * events (the error points at `handle:`), and so is `@off`.
*/
export interface ListenerRule extends AtRuleBase {
name: "on";
diff --git a/packages/quark-parser/support/docs/README.md b/packages/quark-parser/support/docs/README.md
index 61ea391..ccd4f6d 100644
--- a/packages/quark-parser/support/docs/README.md
+++ b/packages/quark-parser/support/docs/README.md
@@ -35,13 +35,13 @@ const expr = parseExpression(`iterate($items, ":scope > template", "id")`);
## Language reference
-This section defines what **parses**. What the runtime does with a parsed sheet — declaration kinds, value keywords, built-in functions, allowed methods — is the `quark` package's documentation (one page per topic: declaration kinds, values, built-ins, allowed methods, selectors). Quark is a derivative of CSS: rules, selectors, and declarations carry over, the at-rules are its own, and a construct the engine never ran is a parse error rather than a statement the runtime skips (see *Rejected on purpose*).
+This section defines what **parses**. What the runtime does with a parsed sheet — declaration kinds, value keywords, built-in functions, allowed methods — is the `quark` package's documentation (one page per topic: declaration kinds, values, built-ins, allowed methods, selectors). Quark is a derivative of CSS, written in CSS syntax: rules, selectors, nesting, declarations and comments are CSS's own, and Quark's additions (variables, expressions and at-rules of its own) stay compatible with that syntax. A construct the engine does not run is a parse error rather than a statement the runtime skips (see *Rejected on purpose*).
Notation is EBNF: `=` defines, `|` alternates, `{ x }` repeats zero or more times, `[ x ]` is optional, `"x"` is literal text, and `ws` is whitespace. Every `quark` code block on this page is parsed by the package's tests; blocks marked *invalid* must fail.
### Lexical structure
-The tokenizer emits `ident`, `variable`, `at`, `string`, `number`, `hash`, `url`, and `punct` tokens. Whitespace is **not** a token: it sets a `ws` flag on the token that follows, and that flag decides descendant combinators, space-separated lists, and sign handling. Comments are `/* … */` only — a `//` raises `Line comments are not supported, use /* */`, so a sheet stays tokenizable by a CSS engine. They are collected separately and surface as `comment` statements between other statements; they never appear inside a selector or a value.
+The tokenizer emits `ident`, `variable`, `at`, `string`, `number`, `hash`, `url`, and `punct` tokens. Whitespace is **not** a token: it sets a `ws` flag on the token that follows, and that flag decides descendant combinators, space-separated lists, and sign handling. Comments are CSS's own `/* … */`; a `//` raises `Line comments are not supported, use /* */`. They are collected separately and surface as `comment` statements between other statements; they never appear inside a selector or a value.
```ebnf
ws = ( " " | "\t" | "\n" | "\r" | "\f" ) { " " | "\t" | "\n" | "\r" | "\f" }
@@ -94,7 +94,7 @@ property = ( ident | "*" ) { ident | "*" }
- A declaration's `;` is optional before `}` and at end of input; stray `;` are skipped.
- Declarations are allowed at the top level of a sheet (a Quark extension; CSS has none).
-- A variable key is a bare `$name`; a dot chain after it (`$sig.value:`, the former signal write) is a parse error that points at the owner-side forms (`@on` block on the owner, `element.quark.setProperty()` from JS).
+- A variable key is a bare `$name`; a dot chain after it (`$user.name:`) is a parse error that points at the owner-side forms (an `@on` block on the owner, `element.quark.setProperty()` from JS).
```quark
$app-theme: "dark";
@@ -114,10 +114,10 @@ The parser scans ahead (skipping `(…)`, `[…]`, and `#{…}`) to the first to
| --- | --- | --- |
| `;` / `}` / end | has a top-level `:` | declaration |
| `;` / `}` / end | no `:` | parse error |
-| `{` | `ident ":"` at the start **and** whitespace or `{` after the colon | parse error: a nested property block |
+| `{` | `ident ":"` at the start **and** whitespace or `{` after the colon | parse error: a declaration takes no block |
| `{` | anything else | rule |
-So `a:hover { … }` is a rule, while `a: hover { … }` is the nested property syntax Quark rejects.
+So `a:hover { … }` is a rule, while `a: hover { … }` is a parse error.
### Selectors
@@ -219,7 +219,7 @@ a {
title: item.meta.title.toUpperCase();
first: "#{$tags[0]} #{$obj["display-name"]}";
ns: math.$pi * math.round($r);
- named: fetch-user($id: 7, $opts...);
+ named: formatPrice($amount: 7, $opts...);
self: closest(&);
chained: prop("provision").body.items[index].name;
}
@@ -256,7 +256,7 @@ a {
#### Rejected syntax
-JavaScript syntax that appears in legacy sheets is a parse error, with a message naming the alternative. Conditionals use `if()` or `ternary()`; null-safe access is runtime behavior (accessing a field of `null` / `undefined` yields `undefined`), not syntax.
+JavaScript syntax is a parse error, with a message naming the alternative. Conditionals use `if()` or `ternary()`; null-safe access is runtime behavior (accessing a field of `null` / `undefined` yields `undefined`), not syntax.
```quark invalid
a { x: $a ? $b : $c; }
@@ -291,7 +291,7 @@ a { @on click go, prevent-default; }
```
```quark invalid
-form { @off submit save; }
+a { @off click go; }
```
```quark invalid
@@ -304,7 +304,7 @@ ul { @view-transition (types: "todo-change"); }
### At-rules
-Quark's at-rules are the whole set — `"@use"`, `"@scope"`, `"@on"`, `"@dispatch"`, `"@command"`, `"@view-transition"`, `"@delay"`, `"@warn"`, `"@debug"`, `"@error"` — and each has a dedicated node. One table, `QUARK_AT_RULES`, types the parser's dispatch map, so any other name is a parse error: CSS's `@media` / `@supports` / `@keyframes` / `@font-face` / `@layer` and SCSS's control flow, mixins, and module rules are not part of the language.
+Quark's at-rules are the whole set — `"@use"`, `"@scope"`, `"@on"`, `"@dispatch"`, `"@command"`, `"@view-transition"`, `"@delay"`, `"@warn"`, `"@debug"`, `"@error"` — and each has a dedicated node. One table, `QUARK_AT_RULES`, types the parser's dispatch map, so any other name is a parse error: features of the browser's style engine, such as `@media`, `@supports`, `@keyframes`, `@font-face` and `@layer`, stay in a stylesheet.
```ebnf
at-rule = "@use" string [ "as" ( ident | "*" ) ] [ ";" ]
@@ -319,24 +319,29 @@ option = ident [ ":" space-list ]
name-list = ( ident | string ) { "," ( ident | string ) }
```
-`@use` imports a JS module and takes no `with (…)` clause. `@scope` takes a block and no prelude. `@on` handlers live in the options group (`handle: fn` or `handle: (a, b)`); a bare expression after the event names — the handler list of earlier versions — is an error that points there, and so is an `@on` statement with neither options nor a block (nothing to do). `@off` is not part of the language (it was removed once `@on` gained options and blocks). `@dispatch` and `@command` are statements: a block is an error. `@view-transition` and `@delay` have no statement form: a missing block is an error, and so is a missing `@delay` duration.
+`@use` imports a JS module. `@scope` takes a block and no prelude. `@on` takes its listeners in the options group: `handle: fn`, `handle: (a, b)`, or a call that returns the listener. The expression is evaluated each time the event fires, so such a call runs on every event (runtime semantics: quark's [`@on`](/nucleus/packages/quark/on) page). A bare expression after the event names is an error that points at `handle:`, and so is an `@on` statement with neither options nor a block (nothing to do). There is no `@off`: gate a listener with its options or with event data inside its block. `@dispatch` and `@command` are statements: a block is an error. `@view-transition` and `@delay` have no statement form: a missing block is an error, and so is a missing `@delay` duration.
```quark
@use "/helpers.js" as *;
-@use "/api-client.js" as api;
+@use "/pricing.js" as pricing;
@scope {
- #out { content: api.getAmount(); }
+ #total { content: formatPrice(pricing.total($items, $tax-rate)); }
form {
- @on submit (prevent-default, handle: api.save);
+ @on submit (prevent-default) { is-submitted: ""; }
@on input, change (debounce: 300) { data-draft: event.target.value; }
@on keydown (key: "Escape", host: window) { is-open: none; }
- @on click (target: "li[data-id]", once, handle: pick);
@on reset (prevent-default) {
data-draft: none;
@dispatch draft-cleared (detail: (at: event.timeStamp), target: "#status");
@command --refresh (target: "#preview");
}
}
+ ul {
+ @on click (target: "li[data-id]") { data-selected: target.getAttribute("data-id"); }
+ }
+ dialog[open] > include-content {
+ @on include-content-did-render (handle: focusInput);
+ }
button[data-copy] {
@on click {
data-copied: "";
@@ -354,31 +359,20 @@ name-list = ( ident | string ) { "," ( ident | string ) }
### Rejected on purpose
-Quark keeps the CSS the engine runs and nothing else, so what it does not run does not parse. Every rejection names the construct, with the line and column.
+What the engine does not run does not parse. Every rejection names the construct, with the line and column.
| Construct | Message |
| --- | --- |
| an at-rule that is not Quark's own | `@media is not a Quark at-rule` |
-| `%placeholder` selectors | `Placeholder selectors are not supported` |
| `#{…}` outside a string — a selector, a property name, an attribute value | `Interpolation is only supported inside strings` |
-| `!important`, `!default`, `!global` | `!important is not supported` |
-| nested property blocks | `Nested property blocks are not supported` |
-| a `@use` configuration | `@use does not take a with clause` |
+| `!important` | `!important is not supported` |
```quark invalid
@media (width < 600px) { nav { is-compact: ""; } }
```
```quark invalid
-@each $name, $glyph in $icons { .icon-#{$name} { content: $glyph; } }
-```
-
-```quark invalid
-%error-message { content: $message; }
-```
-
-```quark invalid
-.icon-#{$name} { content: $glyph; }
+#step-#{$n} { is-active: ""; }
```
```quark invalid
@@ -386,21 +380,13 @@ li[data-id=#{$id}] { is-current: ""; }
```
```quark invalid
-a { border-#{$side}-radius: 3px; }
+a { data-#{$key}: $value; }
```
```quark invalid
a { color: red !important; }
```
-```quark invalid
-a { font: { size: 1rem; } }
-```
-
-```quark invalid
-@use "/theme.js" with ($accent: "red");
-```
-
### AST
`types.ts` is the contract. Every node has `type`, `start`, and `end` (offsets into the source), so consumers slice original text instead of re-serializing.
@@ -410,7 +396,7 @@ a { font: { size: 1rem; } }
| sheet | `stylesheet` → `body: Statement[]` |
| `selector { … }` | `rule` → `selector: selector_list`, `block` |
| `key: value;` | `declaration` → `property` (a `property` with a `name`, or a `variable`), `value` |
-| `@use "/x.js" as api;` | `atrule` → `name: "use"`, `url`, `namespace` (`null` = derived from the url, `"*"` = global) |
+| `@use "/x.js" as pricing;` | `atrule` → `name: "use"`, `url`, `namespace` (`null` = derived from the url, `"*"` = global) |
| `@scope { … }` | `atrule` → `name: "scope"`, `block` |
| `@on click, submit (once, handle: a) { … }` / `@on click (handle: a);` | `atrule` → `name: "on"`, `events: event_name[]` (each `name`, `quoted`), `options: listener_option[]` (each `name`, `value: Expression \| null` — `null` for a flag), `block` (`null` in the statement form) |
| `@dispatch cart-add (detail: $d);` / `@command --refresh (target: "#x");` | `atrule` → `name: "dispatch" \| "command"`, `names: event_name[]`, `options: listener_option[]` |
@@ -438,6 +424,6 @@ The data-driven parts of the grammar are exported so tooling never re-types them
## Design notes
- Single-pass, charcode-based tokenizer (no regexes on the hot path). Whitespace is a flag on tokens, not a token; comments are collected separately so expression parsing never has to skip them.
-- Recursive-descent statement parser + Pratt expression parser. Node naming loosely follows `salesforce-ux/scss-parser` (`stylesheet`, `rule`, `declaration`, `atrule`, `function`, `variable`, ...), but values are structured expression nodes rather than token lists.
+- Recursive-descent statement parser + Pratt expression parser. Values are structured expression nodes rather than token lists.
- Every node carries `start` / `end` source offsets. `QuarkParseError` reports line / column.
- `QUARK_AT_RULES` types the parser's dispatch map, so an at-rule is one table entry plus one method, and the same table rejects every other name.
diff --git a/packages/quark/src/builtin-modules.ts b/packages/quark/src/builtin-modules.ts
index c26ef60..87e20bf 100644
--- a/packages/quark/src/builtin-modules.ts
+++ b/packages/quark/src/builtin-modules.ts
@@ -1,9 +1,8 @@
/**
- * Built-in `@use "quark:"` modules: pure helpers grouped the way
- * Sass groups `sass:math` / `sass:list` / `sass:map` / `sass:string`.
- * Nothing here is global — a sheet imports what it needs
- * (`@use "quark:math" as math;` → `math.clamp(0, $x, 1)`; `as *` merges
- * the exports bare). Every function is pure, null-tolerant (a missing
+ * Built-in `@use "quark:"` modules: pure helpers grouped by the
+ * kind of value they work on. Nothing here is global — a sheet imports
+ * what it needs (`@use "quark:math" as math;` → `math.clamp(0, $x, 1)`;
+ * `as *` merges the exports bare). Every function is pure, null-tolerant (a missing
* collection reads as empty, a missing value passes through) and returns
* copies, never mutating its arguments. Dashed names (`sort-by`) are
* plain object keys: the evaluator calls own-property functions by name.
@@ -57,7 +56,7 @@ const math: Vars = {
$e: Math.E,
min: (...values: unknown[]) => Math.min(...values.flat().map(toNumber)),
max: (...values: unknown[]) => Math.max(...values.flat().map(toNumber)),
- // CSS / Sass argument order: clamp(min, value, max)
+ // CSS argument order: clamp(min, value, max)
clamp: (min: unknown, value: unknown, max: unknown) =>
Math.min(Math.max(toNumber(value), toNumber(min)), toNumber(max)),
round: (value: unknown, digits: unknown = 0) => {
diff --git a/packages/quark/src/constants.ts b/packages/quark/src/constants.ts
index 409e315..273dd69 100644
--- a/packages/quark/src/constants.ts
+++ b/packages/quark/src/constants.ts
@@ -45,3 +45,22 @@ export const VALUE_MAP = {
export const isWipe = (value: unknown): boolean => TYPES_WIPE.includes(value);
export const isNoop = (value: unknown): boolean => TYPES_NOOP.includes(value);
+
+export const isThenable = (value: unknown): value is PromiseLike =>
+ !!value &&
+ typeof value === "object" &&
+ typeof (value as PromiseLike).then === "function";
+
+/*
+ * Promises of Quark's own render built-ins (`template()`, `iterate()`):
+ * the only ones `content:` awaits. Any other promise is refused.
+ */
+const RENDER_PROMISES = new WeakSet();
+
+export const markRenderPromise = (value: T): T => {
+ if (isThenable(value)) RENDER_PROMISES.add(value);
+ return value;
+};
+
+export const isRenderPromise = (value: unknown): boolean =>
+ RENDER_PROMISES.has(value as object);
diff --git a/packages/quark/src/devtools-hook.ts b/packages/quark/src/devtools-hook.ts
index ad82873..00102e2 100644
--- a/packages/quark/src/devtools-hook.ts
+++ b/packages/quark/src/devtools-hook.ts
@@ -41,7 +41,7 @@ export type QuarkInspectSnapshot = {
/**
* Listeners from Quark `@on` at-rules, per event type, one entry per
* attached function, tagged with the declaration that produced it
- * (`$expression`, e.g. `setOutputFromDetail`).
+ * (`$expression`, e.g. `focusInput`).
*/
listeners: Record;
/** `iterate()` row context, when this element is a rendered row. */
diff --git a/packages/quark/src/language.ts b/packages/quark/src/language.ts
index ee7953d..25c3f10 100644
--- a/packages/quark/src/language.ts
+++ b/packages/quark/src/language.ts
@@ -4,9 +4,8 @@
* module. Prose-free tables live in `language-tables.ts`
* (`METHOD_ALLOWLIST`, `PSEUDO_CLASS_SUPPORT`) so docs stay out of
* production. Tests check `variables.ts` / `constants.ts` against it;
- * `support/scripts/build-language-docs.mjs` renders the README language
- * reference. Published as `@excom/quark/language`. No deps, so plain
- * Node can import it.
+ * `support/scripts/build-language-docs.mjs` renders the generated regions
+ * of the doc pages. Published as `@excom/quark/language`.
*/
import {
ALLOWED_METHOD_NAMES,
@@ -92,12 +91,13 @@ export const DECLARATION_KINDS: readonly DeclarationKindDoc[] = [
key: "content",
description:
"Replaces the element's rendered children (a source `` " +
- "child is kept). Promises are awaited. Writing into a `` " +
- "targets its `.content`. On a `