@excom/quark 0.1.0

package/src/evaluator.ts

@@ -0,0 +1,317 @@
+/**
+ * Quark expression evaluator.
+ *
+ * Evaluates `@excom/quark-parser` expression ASTs against a scope
+ * (built by `resolveVariable`). Replaces the old `new Function` + `with`
+ * path: no arbitrary JS, CSP-safe, methods limited to an allowlist of
+ * pure / read-only calls.
+ */
+import { METHOD_ALLOWLIST } from "./language-tables";
+import type {
+  Argument,
+  Expression,
+  Interpolation,
+} from "@excom/quark-parser";
+import { parseExpression } from "@excom/quark-parser";
+
+export interface EvalContext {
+  /** Lazy name resolver (see `createScope` in variables.ts). */
+  scope: { lookup(name: string): unknown };
+  element: Element;
+}
+
+export class QuarkEvalError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "QuarkEvalError";
+  }
+}
+
+/**
+ * Parse an expression source to an AST, memoized. Declaration values
+ * repeat a lot across elements / runs, so each unique source parses
+ * once.
+ */
+const EXPRESSION_CACHE = new Map<string, Expression>();
+export const getExpressionAst = (src: string): Expression => {
+  let ast = EXPRESSION_CACHE.get(src);
+  if (!ast) {
+    ast = parseExpression(src);
+    EXPRESSION_CACHE.set(src, ast);
+  }
+  return ast;
+};
+
+/**
+ * Collect referenced `$variable` names (prefixed with `$`, same shape
+ * as the old `extractVarNames` used by `resolveVariable`).
+ */
+export const collectVariableNames = (expr: Expression): string[] => {
+  const names = new Set<string>();
+  const visit = (node: any): void => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (node.type === "variable") names.add("$" + node.name);
+    for (const key in node) {
+      if (key === "start" || key === "end" || key === "type") continue;
+      const value = node[key];
+      if (value && typeof value === "object") visit(value);
+    }
+  };
+  visit(expr);
+  return [...names];
+};
+
+/**
+ * Collect literal string args of `<callee>("name")` calls (`attr("x")`,
+ * `prop("x")`). Only static names can be observed (attr filters and
+ * property subscriptions come from them). Non-literal args set
+ * `hasNonLiteral` so callers can warn.
+ */
+export const collectLiteralCalls = (
+  expr: Expression | null,
+  callee: string
+): { names: string[]; hasNonLiteral: boolean } => {
+  const names = new Set<string>();
+  let hasNonLiteral = false;
+  const visit = (node: any): void => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (
+      node.type === "function" &&
+      node.callee?.type === "identifier" &&
+      node.callee.name === callee
+    ) {
+      const arg = node.args?.[0]?.value;
+      if (arg?.type === "string" && arg.value != null) {
+        names.add(arg.value);
+      } else {
+        hasNonLiteral = true;
+      }
+    }
+    for (const key in node) {
+      if (key === "start" || key === "end" || key === "type") continue;
+      const value = node[key];
+      if (value && typeof value === "object") visit(value);
+    }
+  };
+  if (expr) visit(expr);
+  return { names: [...names], hasNonLiteral };
+};
+
+export const collectAttrCalls = (expr: Expression | null) =>
+  collectLiteralCalls(expr, "attr");
+export const collectPropCalls = (expr: Expression | null) =>
+  collectLiteralCalls(expr, "prop");
+
+const unescapeString = (raw: string): string =>
+  raw.includes("\\")
+    ? raw.replace(/\\(.)/g, (_, c: string) =>
+        c === "n" ? "\n" : c === "t" ? "\t" : c === "r" ? "\r" : c
+      )
+    : raw;
+
+const interpolationToString = (value: any): string =>
+  value == null ? "" : String(value);
+
+const truthy = (value: any): boolean => !!value;
+
+export const evaluateExpression = (
+  expr: Expression,
+  context: EvalContext
+): any => {
+  return evaluate(expr, context);
+};
+
+const evaluate = (node: Expression, ctx: EvalContext): any => {
+  switch (node.type) {
+    case "string": {
+      if (node.value !== null) return unescapeString(node.value);
+      return node.parts
+        .map((part) =>
+          typeof part === "string"
+            ? unescapeString(part)
+            : interpolationToString(evaluate(part.expression, ctx))
+        )
+        .join("");
+    }
+    case "number":
+      return node.unit ? `${node.value}${node.unit}` : node.value;
+    case "color":
+      return node.value;
+    case "boolean":
+      return node.value;
+    case "null":
+      return null;
+    case "identifier":
+      // unknown bare identifiers throw inside `lookup`
+      return ctx.scope.lookup(node.name);
+    case "variable":
+      // `$bindings` never throw: unbound resolves to `undefined` (wipe)
+      return ctx.scope.lookup("$" + node.name);
+    case "parent_reference":
+      // Legacy behavior: `&` in an expression resolves to the element's tag
+      // name (used as a selector string).
+      return ctx.element.localName;
+    case "interpolation":
+      return evaluate(node.expression, ctx);
+    case "url":
+      return node.parts
+        .map((part) =>
+          typeof part === "string"
+            ? part
+            : interpolationToString(evaluate(part.expression, ctx))
+        )
+        .join("");
+    case "member": {
+      // Null propagation is built in: accessing a field of null/undefined
+      // resolves to undefined instead of erroring.
+      const object = evaluate(node.object, ctx);
+      if (object == null) return undefined;
+      return object[node.variable ? "$" + node.property : node.property];
+    }
+    case "index": {
+      const object = evaluate(node.object, ctx);
+      if (object == null) return undefined;
+      return object[evaluate(node.index, ctx)];
+    }
+    case "function":
+      return evaluateCall(node.callee, node.args, ctx);
+    case "if": {
+      // CSS-style `if($cond: a; else: b)`: first truthy arm wins.
+      for (const arm of node.arms) {
+        if (arm.condition === null || truthy(evaluate(arm.condition, ctx))) {
+          return evaluate(arm.value, ctx);
+        }
+      }
+      // No arm matched and no `else`: undefined = Quark no-op.
+      return undefined;
+    }
+    case "unary": {
+      const value = evaluate(node.argument, ctx);
+      if (node.operator === "-") return -value;
+      if (node.operator === "+") return +value;
+      return !truthy(value);
+    }
+    case "binary": {
+      const left = evaluate(node.left, ctx);
+      switch (node.operator) {
+        // Short-circuiting, JS semantics (matches the legacy eval behavior).
+        case "and":
+          return truthy(left) ? evaluate(node.right, ctx) : left;
+        case "or":
+          return truthy(left) ? left : evaluate(node.right, ctx);
+      }
+      const right = evaluate(node.right, ctx);
+      switch (node.operator) {
+        case "+":
+          return left + right;
+        case "-":
+          return left - right;
+        case "*":
+          return left * right;
+        case "/":
+          return left / right;
+        case "%":
+          return left % right;
+        // Loose equality preserves legacy `==` behavior in existing sheets.
+
+        case "==":
+          return left == right;
+
+        case "!=":
+          return left != right;
+        case "<":
+          return left < right;
+        case "<=":
+          return left <= right;
+        case ">":
+          return left > right;
+        case ">=":
+          return left >= right;
+      }
+      throw new QuarkEvalError(`Unknown operator "${node.operator}"`);
+    }
+    case "list":
+      return node.items.map((item) => evaluate(item, ctx));
+    case "map": {
+      const result: Record<string, any> = {};
+      for (const entry of node.entries) {
+        result[mapKeyToString(entry.key, ctx)] = evaluate(entry.value, ctx);
+      }
+      return result;
+    }
+    default:
+      throw new QuarkEvalError(
+        `Unsupported expression node "${(node as Expression).type}"`
+      );
+  }
+};
+
+/** Map keys: bare identifiers are literal strings (`(a: 1)` -> key "a"). */
+const mapKeyToString = (key: Expression, ctx: EvalContext): string => {
+  if (key.type === "identifier") return key.name;
+  return interpolationToString(evaluate(key, ctx));
+};
+
+const evaluateCall = (
+  callee: Expression,
+  args: Argument[],
+  ctx: EvalContext
+): any => {
+  const argValues: any[] = [];
+  for (const arg of args) {
+    const value = evaluate(arg.value, ctx);
+    if (arg.spread) {
+      if (Array.isArray(value)) argValues.push(...value);
+      else argValues.push(value);
+    } else {
+      argValues.push(value);
+    }
+  }
+
+  // Method call on a value (dot accessor).
+  if (callee.type === "member") {
+    const object = evaluate(callee.object, ctx);
+    const method = callee.property;
+    // Null propagation: calling a method on null/undefined is a no-op.
+    if (object == null) return undefined;
+    const own =
+      typeof object === "object" &&
+      Object.prototype.hasOwnProperty.call(object, method);
+    if (own && typeof object[method] === "function") {
+      // Own-property functions are user-provided (e.g. @use module
+      // namespaces like `api.version()`), not built-in prototype methods.
+      return object[method](...argValues);
+    }
+    // Prototype methods (string/array/number/DOM) are allowlisted only
+    // (`ALLOWED_METHOD_NAMES` in language-tables.ts).
+    if (!METHOD_ALLOWLIST.has(method)) {
+      throw new QuarkEvalError(
+        `Method "${method}" is not allowed in Quark expressions. ` +
+          `Register a module function and call it instead.`
+      );
+    }
+    const fn = object[method];
+    if (typeof fn !== "function") {
+      throw new QuarkEvalError(`"${method}" is not a function`);
+    }
+    return fn.apply(object, argValues);
+  }
+
+  const fn = evaluate(callee, ctx);
+  if (typeof fn !== "function") {
+    throw new QuarkEvalError(
+      `"${callee.type === "identifier" ? callee.name : "<expression>"}" is not a function`
+    );
+  }
+  return fn(...argValues);
+};
+
+export type { Expression, Interpolation };

package/src/form-controls.ts

@@ -0,0 +1,69 @@
+/**
+ * Form-control sync. Native `<input>`, `<option>`, and `<textarea>`
+ * markup is only the *default* (`value` / `checked` / `selected`, or
+ * textarea text). After the user edits (spec "dirty" flags), the live
+ * `.value` / `.checked` / `.selected` stop following those attrs, so a
+ * rule write would silently not show.
+ *
+ * The attribute stays the serializable source of truth. After a rule
+ * write, we push the same state onto the live property. Compare against
+ * the *live* value, not the attr, so a re-run that resolves to the
+ * current attr still restores a control the user has edited away.
+ *
+ * Custom elements are left alone (they own reflection). `<select>` has
+ * no `value` attr; write `selected` on its options.
+ */
+
+/** Attribute keys synced to a live property, per native tag. */
+export const FORM_CONTROL_ATTRIBUTES: Readonly<
+  Record<string, readonly string[]>
+> = {
+  input: ["value", "checked"],
+  option: ["selected"],
+};
+
+/** Tags whose text is a default value mirrored to `.value`. */
+export const TEXT_CONTROL_TAGS: readonly string[] = ["textarea"];
+
+/** `true` when Quark syncs `name` on `element` (documented table above). */
+export const isFormControlAttribute = (element: Element, name: string) =>
+  !!FORM_CONTROL_ATTRIBUTES[element.localName]?.includes(name);
+
+/**
+ * After an attr write (`value` = the string, `null` = removed), push the
+ * same state onto the live property when it differs.
+ */
+export const syncFormControlAttribute = (
+  element: Element,
+  name: string,
+  value: string | null
+) => {
+  if (!isFormControlAttribute(element, name)) return;
+  if (name === "value") {
+    const input = element as HTMLInputElement;
+    // a file input's value is read-only (assigning anything but "" throws)
+    if (input.type === "file") return;
+    const next = value ?? "";
+    if (input.value !== next) input.value = next;
+    return;
+  }
+  // `checked` / `selected`: presence attributes
+  const present = value !== null;
+  const control = element as HTMLInputElement & HTMLOptionElement;
+  if (control[name] !== present) control[name] = present;
+};
+
+/**
+ * After a text paint / wipe into a text control, mirror the new default
+ * onto `.value` when the live value has drifted.
+ */
+export const syncTextControl = (target: Node, text: string) => {
+  if (
+    target.nodeType !== Node.ELEMENT_NODE ||
+    !TEXT_CONTROL_TAGS.includes((target as Element).localName)
+  ) {
+    return;
+  }
+  const control = target as HTMLTextAreaElement;
+  if (control.value !== text) control.value = text;
+};

package/src/language-tables.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime language tables, the prose-free half of `language.ts`. The
+ * engine imports only this module (evaluator method allowlist, selector
+ * classifier's pseudo-class support), so the docs in `language.ts` stay
+ * out of production. `language.ts` builds its documented rows on these
+ * tables; `language-docs.test.ts` keeps the two in step.
+ */
+
+/**
+ * Prototype methods an expression may call via the dot accessor
+ * (`item.name.toLowerCase()`). Anything else throws. Own-property
+ * functions (`@use` namespaces, provided objects) are callable without
+ * being listed. Documented in `language.ts` `ALLOWED_METHODS`.
+ */
+export const ALLOWED_METHOD_NAMES: readonly string[] = [
+  // string
+  "toLowerCase",
+  "toUpperCase",
+  "trim",
+  "split",
+  "charAt",
+  "startsWith",
+  "endsWith",
+  "padStart",
+  "padEnd",
+  "replace",
+  "replaceAll",
+  "toString",
+  // string + array
+  "includes",
+  "slice",
+  "indexOf",
+  "lastIndexOf",
+  "concat",
+  "at",
+  // array
+  "join",
+  "flat",
+  // number / date
+  "toFixed",
+  "toLocaleString",
+  "toLocaleDateString",
+  "toLocaleTimeString",
+  "toISOString",
+  // element
+  "getAttribute",
+  "hasAttribute",
+  "matches",
+  "closest",
+];
+
+export const METHOD_ALLOWLIST: ReadonlySet<string> = new Set(
+  ALLOWED_METHOD_NAMES
+);
+
+export type PseudoClassKind =
+  | "logical"
+  | "relational"
+  | "structural"
+  | "attribute"
+  | "static"
+  | "unobserved";
+
+export interface PseudoClassSupport {
+  kind: PseudoClassKind;
+  /** `attribute` kind: the attribute names the pseudo-class reflects. */
+  attributes?: readonly string[];
+}
+
+const attribute = (...attributes: string[]): PseudoClassSupport => ({
+  kind: "attribute",
+  attributes,
+});
+
+/**
+ * Pseudo-class name (no colon) → how Quark observes it.
+ * `selector-utils.ts` classifies from this table; anything missing is
+ * `unobserved` (first run only, warned at build). Every entry has a row
+ * in `language.ts` `PSEUDO_CLASSES`.
+ */
+export const PSEUDO_CLASS_SUPPORT: Readonly<
+  Record<string, PseudoClassSupport>
+> = {
+  // logical
+  is: { kind: "logical" },
+  where: { kind: "logical" },
+  not: { kind: "logical" },
+  // relational
+  has: { kind: "relational" },
+  // structural
+  "first-child": { kind: "structural" },
+  "last-child": { kind: "structural" },
+  "only-child": { kind: "structural" },
+  "nth-child": { kind: "structural" },
+  "nth-last-child": { kind: "structural" },
+  "first-of-type": { kind: "structural" },
+  "last-of-type": { kind: "structural" },
+  "only-of-type": { kind: "structural" },
+  "nth-of-type": { kind: "structural" },
+  "nth-last-of-type": { kind: "structural" },
+  empty: { kind: "structural" },
+  // attribute-backed
+  disabled: attribute("disabled"),
+  enabled: attribute("disabled"),
+  required: attribute("required"),
+  optional: attribute("required"),
+  "read-only": attribute("readonly", "disabled", "contenteditable"),
+  "read-write": attribute("readonly", "disabled", "contenteditable"),
+  "any-link": attribute("href"),
+  lang: attribute("lang"),
+  open: attribute("open"),
+  // static
+  scope: { kind: "static" },
+  root: { kind: "static" },
+  // unobserved (interaction / browser state with no attribute behind it)
+  hover: { kind: "unobserved" },
+  focus: { kind: "unobserved" },
+  "focus-within": { kind: "unobserved" },
+  "focus-visible": { kind: "unobserved" },
+  active: { kind: "unobserved" },
+  visited: { kind: "unobserved" },
+  link: { kind: "unobserved" },
+  target: { kind: "unobserved" },
+  checked: { kind: "unobserved" },
+  indeterminate: { kind: "unobserved" },
+  default: { kind: "unobserved" },
+  valid: { kind: "unobserved" },
+  invalid: { kind: "unobserved" },
+  "in-range": { kind: "unobserved" },
+  "out-of-range": { kind: "unobserved" },
+  "placeholder-shown": { kind: "unobserved" },
+  "popover-open": { kind: "unobserved" },
+  modal: { kind: "unobserved" },
+  fullscreen: { kind: "unobserved" },
+  defined: { kind: "unobserved" },
+  dir: { kind: "unobserved" },
+};