@excom/quark 0.1.0

package/support/docs/SYNTAX.md

@@ -0,0 +1,36 @@
+# Syntax
+
+Quark is a derivative of CSS with CSS-compatible syntax. A CSS engine tokenizes a Quark sheet and drops what it does not understand, so a Quark construct never breaks the CSS around it. Nested rules, `&`, custom properties and `/* */` comments are CSS's own — Quark inherits them rather than inventing them. On top of CSS it adds `$variables`, expressions, `#{…}` interpolation inside strings, and its own at-rules: `@use`, `@scope`, `@on`, `@dispatch` / `@command`, `@view-transition`, `@delay`, `@warn` / `@debug` / `@error`. It is a derivative, not a superset: those at-rules are the only ones the language has, and every other one — `@media`, `@keyframes`, `@supports`, SCSS's `@if` / `@mixin` and the rest — is a parse error, as are `%placeholder` selectors, `#{…}` outside a string, `!important` / `!default` / `!global`, and nested property blocks.
+
+## Essentials
+
+The full grammar (EBNF, precedence, disambiguation rules) is the `quark-parser` package's *Language reference*; the essentials:
+
+- **Rules** `selector { … }` nest. A nested selector is a descendant of its parent unless it uses `&` (`&[open]`, `&-active`). Lists use `,`; combinators are whitespace, `>`, `+`, `~`.
+- **Declarations** `key: value;` — the `;` is optional before `}`. Keys are attribute names, `$variables`, `--css-vars`, `content`, `class`, `dataset`, `ariaset`.
+- **At-rules** `@use "url" as *;` imports; `@on click, change (options) { … }` wires listeners inside a rule (a comma list of event names, an optional `(options)` map, then a block applied once per event, or just the options — JS callouts are `handle: fn` in the map); `@dispatch` / `@command` send events from an `@on` block; `@scope { … }` anchors rules to the host.
+- **Literals** `"strings"` / `'strings'` with `\` escapes and `#{$interpolation}`; numbers `42`, `1.5`, `10px` (a unit makes it a string); `#ccc` colors (strings); `true`, `false`, `null`. Bare words are value keywords, `@use` exports, or built-ins.
+- **Operators**, loosest to tightest: `or` · `and` · `not` · `==` `!=` · `<` `>` `<=` `>=` · `+` `-` · `*` `/` `%` · unary `-` `+` · `.` `[…]` `(…)`. Parentheses group.
+- **Accessors and calls** `$obj.field`, `$list[0]`, `$obj["key"]`, `ns.$var`; methods `item.name.trim()`; calls `fn($a, $b)`, named `fn($opt: 1)`, spread `fn($args...)`. Only bare names and member chains are callable, not `$variables`.
+- **Conditionals** `if($cond: a; $other: b; else: c)` or `ternary($cond, a, b)`.
+- **Lists and maps** `1, 2, 3` and `1px solid red` both evaluate to arrays; `(a: 1, b: 2)` is a map. Spacing around a sign matters: `$x +1` is a two-item list, `$x + 1` / `$x+1` add.
+- **Comments** `/* … */` only, anywhere whitespace is allowed. `//` is not a comment: a sheet has to stay tokenizable by a CSS engine, and CSS tokenizers read `//` as text, so a `//` line is a parse error.
+- **Not supported** `? :`, `?.`, `??`, `===`, `||`, `&&`, arrow functions — parse errors by design.
+
+## Example
+
+```quark
+/* a comment */
+[data-cart] {
+  $items: prop("provision").items;
+  $total: $items.length or 0;
+  data-is-empty: $total == 0; /* a boolean writes "" or removes the attribute */
+  [bind-summary] { content: if($total == 1: "1 item"; else: "#{$total} items"); }
+  &[data-is-empty] [bind-summary] { content: "Empty"; }
+  &[data-is-empty] button[data-action="clear"] { disabled: ""; }
+  &:not([data-is-empty]) button[data-action="clear"] { disabled: none; }
+  button { @on click (prevent-default, handle: clearCart($items)); }
+}
+```
+
+How each declaration key is interpreted: [Declaration kinds](./DECLARATIONS.md). How values evaluate: [Expressions](./EXPRESSIONS.md).

package/support/docs/USE.md

@@ -0,0 +1,24 @@
+# @use
+
+Import JS modules directly in the sheet; pure functions are the sanctioned way for logic to enter a sheet.
+
+## Importing
+
+`as *` exposes exports bare; `as name` (or the name derived from the url) namespaces them:
+
+```quark
+@use "/helpers.js" as *;
+@use "/api-client.js" as api;
+
+#out {
+  content: formatPrice(api.getAmount());
+}
+```
+
+Imports start as soon as the sheet is parsed and load in parallel; the first rule run waits until they resolve. A failed import is logged and skipped. A `with (…)` clause is a parse error.
+
+`quark:` URLs import Quark's own helpers without a fetch — `@use "quark:math";` derives the namespace `math` — see [Built-in modules](./MODULES.md). Reach for them before writing a module function of your own.
+
+## Writing module functions
+
+Exports are plain functions called from expressions (`formatPrice($amount)`), as `@on` handlers (`@on click (handle: addToCart)`, or a call evaluated per event: `@on click (handle: addToCart(element, event))`), or handed the matched node through `element`. Prefer pure functions; a function that needs to write State does it through [`element.quark`](./JS_WRITES.md) or by dispatching an event an `@on` block turns into attributes.

package/support/docs/VALUES.md

@@ -0,0 +1,27 @@
+# Values & keywords
+
+Three bare words steer what a write does — remove, leave alone, or fall through — and every expression result maps onto one of them.
+
+## Keywords
+
+Bare words with a fixed meaning in every expression. *Generated.*
+
+<!-- generated:value-keywords -->
+| Keyword | Meaning |
+| --- | --- |
+| `none` | `null`: removes the attribute / CSS variable, clears content, or stores `null` in a `$variable`. |
+| `preserve` | Explicit no-op: leaves the attribute / content / binding exactly as it is. Idiom for loading states: `content: $todo.title or preserve`. |
+| `unset` | `$variables` only: deletes the binding from the matched element so consumers fall through to the next ancestor. On any other target it degrades to a wipe. |
+<!-- /generated -->
+
+## Wipes and no-ops
+
+- `none` → `null`: removes the target attribute / clears content.
+- An expression resolving to `undefined` or `null` also **wipes** its target (a matched declaration that resolves to nothing clears what it manages).
+- `preserve`: explicit no-op — leaves the current attribute / content / binding untouched. Handy for loading states: `content: $todo.title or preserve;`
+- `unset`: variables only — deletes the binding (falls through to ancestors).
+- A failed expression evaluation never wipes; it logs and no-ops — the Orchestrator never destroys state by mistake.
+
+## Literals
+
+Unitless numbers are numbers; a number with a unit (`10px`, `50%`) and a color (`#ccc`) evaluate to strings; `true`, `false`, `null` are themselves. Strings unescape `\n`, `\t`, `\r`, and `\x` → `x`; interpolated strings (`"Hello #{$name}"`) and `url(…)` join their parts, with `null` / `undefined` parts rendered empty. Lists (space or comma separated) evaluate to arrays; maps (`(name: "Ada")`) to objects — see [Expressions](./EXPRESSIONS.md).

package/support/docs/VARIABLES.md

@@ -0,0 +1,47 @@
+# Variables
+
+`$variables` behave like CSS custom properties: stored on the elements a rule matches, resolved up the DOM, shared across sheets.
+
+## Declaring and reading
+
+```quark
+main {
+  $label: "Ready";
+  $count: twice(21);
+  [bind-label] { content: $label; }
+  [bind-count] { content: $count; }
+}
+```
+
+A `$variable` declaration stores its value on each element the rule matches, and a consumer resolves it by walking up from its own element to the nearest ancestor (self included) that holds the binding. They cascade across sheets — a sheet can read a binding another sheet set on an ancestor. Nesting rules is still good style, but a sibling rule's (or another sheet's) variable resolves fine as long as the binding lives on a DOM ancestor of the consumer:
+
+```quark
+main { $theme: "dark"; }
+[bind-theme] { content: $theme; } /* resolves if inside <main> */
+```
+
+## Shadowing and namespaces
+
+When bindings shadow, the nearest DOM ancestor wins (like CSS inheritance). Because storage is shared per element, same-named writers collide (last writer wins) — namespace app bindings (e.g. `$app-theme`) to avoid clashes.
+
+## `unset`
+
+Use `unset` to delete a binding from the matched elements so consumers fall through to the next ancestor — here the open `<details>` shadows the host's binding, and closing it falls back:
+
+<include-content data-demo="unset"></include-content>
+
+## Raising state
+
+A `$variable` declared on a descendant *shadows* the ancestor's; it does not update it. To change an owner's binding from below, write it **on the owner**: an `@on` block on the owner rule, with `target:` delegation when the interaction happens in a descendant:
+
+```quark
+:scope {
+  $count: 0;
+  [bind-count] { content: $count; }
+  @on click (target: "button") { $count: $count + 1; }
+}
+```
+
+A row that raises state reflects a dash-named attribute the owner can read: `ul { @on click (target: "li[data-id]") { $selected: target.getAttribute("data-id"); } }`.
+
+Writing a binding from JavaScript: [Writing from JS](./JS_WRITES.md).

package/support/docs/VIEW_TRANSITION.md

@@ -0,0 +1,64 @@
+# @view-transition
+
+`@view-transition [(options)] { … }` commits the writes inside it inside `document.startViewTransition()`, so CSS can animate what changed — rows that leave included, which plain CSS transitions cannot reach.
+
+## A paint policy
+
+The block decides *how* its declarations and its nested rules' writes land, never *when* rules run.
+
+```quark
+provider-fetch[is-success] {
+  $todos: prop("provision").body;
+  @view-transition (types: "todo-change") {
+    ul { content: iterate($todos, none, "id"); }
+    [bind-count] { content: $todos.length; }
+  }
+}
+```
+
+```css
+ul { view-transition-name: todos; }
+li { view-transition-name: match-element; view-transition-class: todo; }
+::view-transition-new(.todo):only-child { animation: todo-in 250ms; }
+::view-transition-old(.todo):only-child { animation: todo-out 200ms; }
+:root:active-view-transition-type(todo-change) ::view-transition-old(root) { animation: none; }
+```
+
+<include-content data-demo="view-transition"></include-content>
+
+- **One tick, one cut.** Every Quark write of the same tick lands in the same cut, and writes that react to those writes land in it too as long as Quark settles within `timeout`. Writes more than a tick later are a separate fact and a separate transition.
+- **Put the writes of one cut inside the block** (the list, its counter, the empty state). Only a write inside a block starts a transition; writes outside it join the cut when they happen meanwhile. `$variables` do not paint, so a block holding only `$variable` writes never starts one.
+- **Keyed `iterate()` rows persist**, so named rows move instead of leaving and entering again.
+- **Styling is CSS's job.** Name elements (`view-transition-name`, `match-element`, `view-transition-class`) and target `::view-transition-group` / `-old` / `-new` and `:active-view-transition-type()`. While the animation runs, captured elements are drawn from those pseudo-elements, so real-DOM styles only show on elements that are not captured. A name that comes from State is one CSS variable away: `li { --vt-name: "row-#{item.id}"; }` in the sheet, `li { view-transition-name: var(--vt-name); }` in the CSS.
+- **Options belong to the block.** They are evaluated per write, on the block's element — what the rule it sits in matches, or the host for a sheet-level block — so `attr()`, `prop()` and `item` read that element.
+
+## Options
+
+| Option | Effect |
+| --- | --- |
+| `types: "a b"` | Names for `:active-view-transition-type()`: a string (space-separated) or a list; `"todo-#{$op}"` interpolates. The types of every write in one transition are combined. |
+| `timeout: <ms>` | How long the transition waits for Quark to settle before the new state is captured. Default 300, or 1000 with `until`. On expiry it captures what is there and warns once per block. |
+| `delay: <ms>` | Hold these writes back first, then commit them in their own transition. Other writes of the same tick are not held and land first. |
+| `first-render` | Also animate the sheet's first render (off by default, like `spa-manager`'s `transition-first-render`). |
+| `if-active: skip` / `replace` | While another view transition runs (a route change, or Quark's own still animating): commit unanimated (`skip`, the default) or start anyway, which ends the running one (`replace`, the browser's own behavior). |
+| `until: "<selector>"` / `until: <promise>` | Keep the transition open until the block's element matches the selector (`"[is-success], [is-error]"`, `":not([is-loading])"`, `":has(li)"`) or the promise settles, capped by `timeout`. |
+
+## `until`
+
+**`until` is for short waits.** The page stays frozen on the old state while the transition is open, so wait for a template or view that is about to render, never for a data fetch — animate a fetch as two cuts (`[is-loading]`, then `[is-success]`) instead. Put the block on the element that owns the fact and nest the writes; a block on a descendant waiting for an ancestor's attribute only times out:
+
+```quark
+provider-fetch[is-loading] {
+  @view-transition (until: "[is-success], [is-error]", timeout: 800) {
+    ul { content: none; }
+  }
+}
+```
+
+## When no transition runs
+
+Committed without a transition: writes that change nothing, the sheet's first render, `prefers-reduced-motion: reduce`, a hidden document, browsers without the API (the writes land as usual) and, under `if-active: skip`, writes while another transition is active. A document runs one view transition at a time; scoped (per-element) transitions are not available yet.
+
+## Costs
+
+Each transition snapshots the page once, its writes land one rendering opportunity later than without the block, and pointer input goes to the transition overlay while it animates — keep animations short. It is the one place Quark stops being "write and forget": a State write waits for a rendering opportunity.

package/support/docs-sections.json

@@ -0,0 +1,65 @@
+{
+  "sections": [
+    {
+      "id": "syntax",
+      "title": "Syntax",
+      "docs": [
+        "sheets",
+        "syntax"
+      ]
+    },
+    {
+      "id": "selectors",
+      "title": "Selectors",
+      "docs": [
+        "selectors",
+        "reactivity",
+        "no_reversion"
+      ]
+    },
+    {
+      "id": "declarations",
+      "title": "Declarations",
+      "docs": [
+        "declarations",
+        "attributes",
+        "content",
+        "css_variables"
+      ]
+    },
+    {
+      "id": "values",
+      "title": "Values & Expressions",
+      "docs": [
+        "variables",
+        "js_writes",
+        "values",
+        "expressions",
+        "builtins",
+        "modules",
+        "methods",
+        "element_properties"
+      ]
+    },
+    {
+      "id": "at-rules",
+      "title": "At-Rules",
+      "docs": [
+        "at_rules",
+        "use",
+        "on",
+        "dispatch",
+        "view_transition"
+      ]
+    },
+    {
+      "id": "runtime",
+      "title": "Runtime",
+      "docs": [
+        "js_api",
+        "loop_guard",
+        "limitations"
+      ]
+    }
+  ]
+}