@excom/quark 0.1.0

package/src/types.ts

@@ -0,0 +1,155 @@
+import type { ListenerOptionSource } from "./ast";
+import type { Attribute, Listener, Variable } from "./properties";
+import type { TQuarkElement } from "./quark-element";
+import type { Rule } from "./rule";
+export type UtilFn = (e: any) => any;
+
+export type Vars = Record<string, any>;
+
+export interface AST {
+  type: string;
+  value: string;
+  children: AST[];
+}
+
+export type PaintFn = () => void;
+
+/**
+ * A `@view-transition` block as the writes inside it carry it
+ * (`Property.transition`; nested rules and `@on` blocks inherit it through
+ * `Rule.transition`, a nested block replaces it). Options are evaluated per
+ * resolve (see `resolveTransitionOptions`).
+ */
+export interface TransitionSpec {
+  /** Options as written, in source order. */
+  optionSources: ListenerOptionSource[];
+  /** Display text: `@view-transition (types: "todo-change")`. */
+  source: string;
+  /** The block lists `first-render` (read statically: no evaluation needed). */
+  firstRender: boolean;
+  /**
+   * The rule the block is written in: the element it matches is where the
+   * options are evaluated and `until: "<selector>"` is checked. `null` for
+   * a sheet-level block, whose element is the host.
+   */
+  ownerRule: Rule | null;
+  /** Option names already warned about for this block. */
+  warned: Set<string>;
+}
+
+export interface QuarkOptions {
+  observe?: boolean;
+  /**
+   * Wrap the sheet in an implicit `@scope { }` at the host (quark-sheet's
+   * default, via `is-global` inversion). Without it, top-level rules run
+   * in the root context and authors write `@scope { }` themselves.
+   */
+  isScoped?: boolean;
+  rule?: Rule;
+  /** The property being resolved (set for the duration of one resolve). */
+  property?: Variable | Attribute | Listener;
+  runId?: string;
+  isFirstRun?: boolean;
+  properties?: Array<Variable | Attribute | Listener>;
+  propertiesToRun?: Array<Variable | Attribute | Listener>;
+  isAsyncRun?: boolean;
+  /**
+   * Set while an `@on` block runs, and while its per-event options
+   * (`handle`, `target`, …) evaluate: the DOM event being handled. The
+   * `event` built-in; `undefined` outside a block.
+   */
+  event?: Event;
+  /**
+   * Set while an `@on` block runs: the element the `target:` option
+   * matched (the delegate), else the event's target. The `target`
+   * built-in.
+   */
+  eventTarget?: Element | null;
+  /** Set on `quark-binding-change` fan-out runs; enables the nearness skip. */
+  changedBinding?: {
+    name: string;
+    origin: WeakRef<HTMLElement>;
+    /**
+     * For changes deferred to the end of a sheet's run: sequence number
+     * at write time plus the run's trace, so consumers that already ran
+     * after the write are not run again.
+     */
+    sinceSeq?: number;
+    trace?: RunTrace;
+  };
+}
+
+/**
+ * What one sheet run executed, in order: every (element, property) pair
+ * gets the sequence number at which it ran. Lives only for the outermost
+ * `Quark.run()`; binding writes during that run carry the seq they were
+ * made at.
+ */
+export interface RunTrace {
+  seq: number;
+  /** Property executions: the sequence number at which each ran. */
+  ran: Map<Element, Map<Variable | Attribute | Listener, number>>;
+  /**
+   * Property visits (`Property.run` reached, executed or not). Seq 0
+   * marks a property the run skipped on purpose (its key was the
+   * triggering mutation); always stale for a later write.
+   */
+  visited: Map<Element, Map<Variable | Attribute | Listener, number>>;
+  /** `$names` written so far during the run (any owner). */
+  written: Set<string>;
+  /**
+   * Per rule: subtree roots the rule fanned out from with its full
+   * property set. Every match below such a root was visited.
+   */
+  coverage: Map<Rule, Set<Element>>;
+}
+
+export type QuarkListenerConfig = [
+  Node | WeakRef<Node>,
+  string,
+  (e: CustomEvent) => void,
+][];
+
+export interface QuarkArgs {
+  host: HTMLElement;
+  sheet: string;
+  variables?: Vars;
+}
+
+export interface ContextSheet {
+  host?: HTMLElement;
+  hash: string;
+  options: QuarkOptions;
+}
+
+export interface ContextField extends ContextSheet {
+  element: TQuarkElement;
+  key: string;
+  value: string | null;
+  /**
+   * Set for `@on` at-rules: DOM event types, storage slot (display key,
+   * unique per event list + options within a rule), option sources, and
+   * for `@on … { }` the block rule applied once per event.
+   */
+  listener?: {
+    eventTypes: string[];
+    slot: string;
+    optionSources: ListenerOptionSource[];
+    block?: Rule;
+  };
+}
+
+export type MutationMap = Map<HTMLElement, Set<string>>;
+
+export type ExpressionResult =
+  | {
+      type: "html";
+      value: string;
+      after?: () => void;
+    }
+  | {
+      type: "nodes";
+      value: Node[];
+      after?: () => void;
+    }
+  | undefined;

package/src/utils.ts

@@ -0,0 +1,79 @@
+import { KitLogManager } from "@excom/kit-logger";
+import { isNumber } from "@excom/kit-utils";
+
+export const stringToHash = (str: string, seed: number = 0): string => {
+  let h1 = 0xdeadbeef ^ seed,
+    h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0, ch; i < str.length; i++) {
+    ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0) + "";
+};
+
+export const getQuarkHost = (el: Element | null): HTMLElement =>
+  ((["HTML", "HEAD", "BODY"].includes(el?.tagName as string)
+    ? document.body
+    : el) ?? document.body) as HTMLElement;
+
+export const getQuarkMin = (sheet: string) => {
+  return minifyQuark(sheet ?? "");
+};
+
+/**
+ * Normalize sheet source before parsing: collapse horizontal whitespace
+ * to one space and blank-line runs to one newline. Comments stay for the
+ * parser (a regex pre-strip ate `//` inside strings like `"https://…"`).
+ */
+export function minifyQuark(scssString: string): string {
+  return scssString
+    .replace(/[ \t\f\r]+/g, " ")
+    .replace(/ ?\n[ \n]*/g, "\n")
+    .trim();
+}
+
+interface QuarkLog {
+  method?: string;
+  sheetId?: string;
+  runId?: string;
+  ruleId?: string;
+  options?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+export const QuarkLogger = new KitLogManager({
+  namespace: "Quark",
+  formatArgs: ([
+    name,
+    { method, sheetId, runId, ruleId, options, ...other },
+  ]: QuarkLog[]) => [
+    method !== "run" ? "    " : "",
+    `${(runId || " ").padEnd(8)}  | `,
+    `${(method || "").padEnd(15)}  | `,
+    isNumber(sheetId) ? `sheet: ${sheetId}  | ` : "",
+    isNumber(ruleId) ? `rule: ${ruleId?.toString().padEnd(3)}  | ` : "",
+    "options: ",
+    [options],
+    ...Object.entries(other || {})
+      .map(([key, value]) => [`  |  ${key}: `, value])
+      .flat(2),
+    `  |  (${name})`,
+  ],
+});
+
+/**
+ * Hot paths build log payloads (matched-element arrays, mutation maps)
+ * that are discarded below `info`. Gate their construction.
+ */
+export const isInfoLogging = () => QuarkLogger.level >= 4;
+
+export const deref = <T extends HTMLElement | Node>(
+  el: T | WeakRef<T>
+): T | undefined => {
+  return el instanceof WeakRef ? el.deref() : el;
+};

package/src/variables.ts

@@ -0,0 +1,359 @@
+import { readBinding } from "./bindings";
+import { VALUE_MAP } from "./constants";
+import { QuarkEvalError } from "./evaluator";
+import { getQuarkInternal } from "./quark-internal";
+import type { ExpressionResult, QuarkOptions } from "./types";
+import { QuarkLogger } from "./utils";
+import { hashObject } from "@excom/hash-object";
+import {
+  di,
+  execWhenReady,
+  getChildren,
+  isPojo,
+  isPrimitive,
+  resolveTemplateContent,
+} from "@excom/kit-utils";
+
+const setLoopData = (
+  el,
+  index?: number,
+  item?: any,
+  hash?: string,
+  key?: string
+) => {
+  const elementInternal = getQuarkInternal(el);
+  // Always set index, whether number or string (for dicts)
+  if (index !== undefined) elementInternal.setLoopIndex(index);
+  if (item !== undefined) elementInternal.setLoopItem(item);
+  if (typeof hash === "string") elementInternal.setLoopHash(hash);
+  if (key !== undefined) elementInternal.setLoopKey(key);
+  return el;
+};
+
+type BuiltinContext = {
+  elRef: WeakRef<HTMLElement>;
+  options: QuarkOptions;
+};
+
+/** Queue `element` for the next rule run of the sheet resolving `options`. */
+const requeue = (
+  options: QuarkOptions,
+  element: HTMLElement,
+  attribute: "content" | "NEW_SELF"
+) => options.rule?.quarkInstance.queueRunRules({ element, attribute });
+
+/**
+ * Built-in expression names. Each factory produces the value for one
+ * evaluation; most return a function. `element` is the matched element;
+ * `item` / `index` read the element's loop context. Factories run only
+ * when an expression actually references the name (see `createScope`).
+ */
+const BUILTINS: Record<string, (ctx: BuiltinContext) => unknown> = {
+  /*
+   * The matched element (the listening element inside `@on` blocks,
+   * where `target` is the delegate). Hand the node to `@use` functions.
+   * Reads through it are not observed.
+   */
+  element: ({ elRef }: BuiltinContext): HTMLElement | undefined =>
+    di.apply([elRef], (el) => el),
+  item: ({ elRef }: BuiltinContext): unknown | undefined | null =>
+    di.apply([elRef], (el) => {
+      const itemEl = el.closest("[q-loop] > *");
+      if (itemEl) {
+        return getQuarkInternal(itemEl as HTMLElement).getLoopItem();
+      }
+    }),
+  index: ({ elRef }: BuiltinContext): number | undefined =>
+    di.apply([elRef], (el) => {
+      const itemEl = el.closest("[q-loop] > *");
+      if (itemEl) {
+        return getQuarkInternal(itemEl as HTMLElement).getLoopIndex();
+      }
+    }),
+  // `@on … { }` blocks: the event being handled (see Rule.runEvent)
+  event: ({ options }: BuiltinContext): Event | undefined => options.event,
+  // `@on (target: "…") { }` blocks: the delegate element; else event.target
+  target: ({ options }: BuiltinContext): EventTarget | null | undefined =>
+    options.eventTarget ?? options.event?.target,
+  "prevent-default":
+    () =>
+    (e: Event): void =>
+      e.preventDefault(),
+  "stop-propagation":
+    () =>
+    (e: Event): void =>
+      e.stopPropagation(),
+  /*
+   * `prop("x")`: the matched element's JS property (the `attr()` of
+   * properties). Literal names the property statically references are
+   * subscribed on first read so a JS assignment re-runs it.
+   */
+  prop:
+    ({ elRef, options }: BuiltinContext) =>
+    (name: string): unknown =>
+      di.apply([elRef], (el) => {
+        if (typeof name !== "string") return undefined;
+        const property = options.property;
+        if (property?.referencedPropNames.includes(name)) {
+          options.rule?.quarkInstance.subscribeProp(el, name);
+        }
+        return (el as unknown as Record<string, unknown>)[name];
+      }),
+  attr:
+    ({ elRef }: BuiltinContext) =>
+    (attrName: string): string | null | undefined =>
+      di.apply([elRef], (el) => {
+        if (attrName === "content") {
+          return el?.innerHTML;
+        } else {
+          return el?.getAttribute(attrName);
+        }
+      }),
+  closest:
+    ({ elRef }: BuiltinContext) =>
+    (selector: string): unknown | undefined | null =>
+      di.apply([elRef], (el) => el.closest(selector)),
+  ternary:
+    () =>
+    (condition: boolean, trueValue: any, falseValue?: any): any =>
+      condition ? trueValue : (falseValue ?? null),
+  // debugging
+  log:
+    () =>
+    <A>(...args: A[]): A[] => {
+      console.log("Quark log() -> ", ...args);
+      return args;
+    },
+  debug:
+    () =>
+    <A>(...args: A[]): A[] => {
+      args;
+      debugger;
+      return args;
+    },
+  "dangerous-html":
+    ({ elRef }: BuiltinContext) =>
+    (result: string): ExpressionResult =>
+      di.apply([elRef], () => {
+        if (isPrimitive(typeof result)) {
+          return {
+            type: "html",
+            value: result as string,
+          };
+        }
+      }),
+  template:
+    ({ elRef }: BuiltinContext) =>
+    (templateRef: string): Promise<ExpressionResult> | undefined =>
+      di.apply([elRef], (el) => {
+        return execWhenReady(
+          resolveTemplateContent(
+            templateRef || ":scope > template",
+            {
+              scope: el,
+            }
+            // template needs cloning, otherwise it will be removed from the DOM
+          ),
+          (templateHtml) => {
+            const node = document.importNode(templateHtml, true) as Node;
+            return {
+              type: "nodes" as const,
+              value: [node],
+            };
+          }
+        );
+      }),
+  iterate:
+    ({ elRef, options }: BuiltinContext) =>
+    (
+      result,
+      templateRef,
+      keyProperty
+    ): Promise<ExpressionResult | null> | undefined | null => {
+      // no collection → wipe rendered children (use `preserve` to opt out)
+      if (result == null) return null;
+      return di.apply([elRef], async (el) => {
+        const isArray = Array.isArray(result);
+        const isObject = !isArray && isPojo(result);
+        if (!isArray && !isObject) return undefined;
+        return execWhenReady(
+          resolveTemplateContent(
+            templateRef || ":scope > template",
+            {
+              scope: el,
+            }
+            // template needs cloning, otherwise it will be removed from the DOM
+          ),
+          (templateHtml) => {
+            el.setAttribute("q-loop", "");
+            const existingChildren = getChildren(el).otherChildren;
+            const entriesResult = isArray
+              ? result.map((item, index) => [index, item])
+              : Object.entries(result);
+            if (!entriesResult.length) {
+              // empty collection → wipe non-template children
+              return {
+                type: "nodes" as const,
+                value: [],
+              };
+            }
+            QuarkLogger.info({
+              method: "iterate",
+              runId: options.runId,
+              result: [[entriesResult]],
+              options,
+            });
+            const changedElements: Node[] = [];
+            const returnChildren = entriesResult.map(
+              ([resultIndex, resultItem]) => {
+                const resultKey = keyProperty
+                  ? resultItem[keyProperty]
+                  : hashObject(resultItem);
+                const existingChild = existingChildren.find((c) => {
+                  // TODO account for scenario where data matches multiple elements
+                  return (
+                    resultKey ===
+                    getQuarkInternal(c as HTMLElement).getLoopKey()
+                  );
+                });
+                if (!existingChild) {
+                  // if key is not found, create new element
+                  const newChild = setLoopData(
+                    document.importNode(templateHtml, true) as Element,
+                    resultIndex,
+                    resultItem,
+                    // use hash for key if key property is not provided
+                    !keyProperty ? resultKey : hashObject(resultItem),
+                    resultKey
+                  );
+                  changedElements.push(newChild);
+                  return newChild;
+                }
+                const hash = !keyProperty ? resultKey : hashObject(resultItem);
+                const internal = getQuarkInternal(existingChild as HTMLElement);
+                let didChange = false;
+
+                if (resultIndex !== internal.getLoopIndex()) {
+                  // if data was re-ordered, update index
+                  setLoopData(existingChild, resultIndex);
+                  didChange = true;
+                }
+                const existingHash = internal.getLoopHash();
+                const existingKey = internal.getLoopKey();
+                if (hash !== existingHash) {
+                  // if data changed, update data and hash. If hash and key were the same, update key with new hash
+                  setLoopData(
+                    existingChild,
+                    undefined,
+                    resultItem,
+                    hash,
+                    existingHash === existingKey ? hash : undefined
+                  );
+                  didChange = true;
+                }
+                if (didChange) {
+                  changedElements.push(existingChild);
+                }
+                return existingChild;
+              }
+            );
+            return {
+              type: "nodes" as const,
+              value: returnChildren as Node[],
+              after: di.bind([elRef], (el) => {
+                /*
+                 * Inserted / moved rows reach rules through the childList
+                 * observer. A keyed row whose data changed in place
+                 * moves no DOM node, so requeue those directly. All rows
+                 * changed: one `content` entry on the parent (dedupes
+                 * with the observer); otherwise each changed row as
+                 * itself.
+                 */
+                if (entriesResult.length === changedElements.length) {
+                  requeue(options, el, "content");
+                } else {
+                  changedElements.forEach((c) => {
+                    requeue(options, c as HTMLElement, "NEW_SELF");
+                  });
+                }
+              }),
+            };
+          }
+        );
+      });
+    },
+};
+
+/** Built-in names, for the language-metadata sync test (`language.ts`). */
+export const BUILTIN_NAMES: readonly string[] = Object.keys(BUILTINS);
+
+const hasOwn = (obj: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(obj, key);
+
+/**
+ * `@use` module exports flattened into one lookup object, cached per
+ * modules record. `addModules` replaces the record, so the WeakMap key
+ * changes exactly when the module set does.
+ */
+const MODULE_SCOPE_CACHE = new WeakMap<object, Record<string, unknown>>();
+const getModuleScope = (options: QuarkOptions): Record<string, unknown> => {
+  const instance = options.rule?.quarkInstance;
+  if (!instance) return {};
+  const modules: Record<string, Record<string, unknown>> | undefined =
+    getQuarkInternal(instance.host.deref())?.getModules(instance.hash);
+  if (!modules) return {};
+  const cached = MODULE_SCOPE_CACHE.get(modules);
+  if (cached) return cached;
+  const { dfault, ...others } = modules;
+  const scope: Record<string, unknown> = { ...dfault, ...others };
+  MODULE_SCOPE_CACHE.set(modules, scope);
+  return scope;
+};
+
+export interface QuarkScope {
+  /**
+   * Resolve a bare identifier or `$variable` for the evaluating element.
+   * Order: value keywords → `@use` exports → built-ins → `$bindings`
+   * (walk ancestors; `undefined` when unbound). Unknown bare ids throw.
+   */
+  lookup(name: string): unknown;
+}
+
+/**
+ * Lazy expression scope. Nothing resolves until the evaluator asks for
+ * a name, so an expression pays only for what it references: no module
+ * spread, no built-in construction, no `item` / `index` `closest()`
+ * walks unless used. $bindings are tree-scoped: walk ancestors from the
+ * consumer (nearest owner wins), whichever sheet set them (CSS
+ * custom-property semantics). VALUE_MAP supplies the behavior keywords
+ * (none / preserve / unset).
+ */
+export const createScope = ({
+  element,
+  options,
+}: {
+  element: HTMLElement;
+  options: QuarkOptions;
+}): QuarkScope => {
+  const modules = getModuleScope(options);
+  let ctx: BuiltinContext | null = null;
+  let builtins: Record<string, unknown> | null = null;
+  return {
+    lookup(name: string): unknown {
+      if (hasOwn(VALUE_MAP, name)) return VALUE_MAP[name];
+      if (hasOwn(modules, name)) return modules[name];
+      if (hasOwn(BUILTINS, name)) {
+        // one instance per name per evaluation (`item` twice in one
+        // expression walks once)
+        builtins ??= {};
+        if (!hasOwn(builtins, name)) {
+          ctx ??= { elRef: new WeakRef(element), options };
+          builtins[name] = BUILTINS[name](ctx);
+        }
+        return builtins[name];
+      }
+      if (name.startsWith("$")) return readBinding(element, name);
+      throw new QuarkEvalError(`"${name}" is not defined`);
+    },
+  };
+};

package/support/demos/css-variables.html

@@ -0,0 +1,18 @@
+<div>
+  <details>
+    <summary>Open me</summary>
+    <p>The border turns blue while open.</p>
+  </details>
+  <quark-sheet>
+    details { --border-color: "silver"; }
+    details[open] { --border-color: "#3fa9f5"; }
+  </quark-sheet>
+  <style>
+    #demo-quark-css-variables > :first-child {
+      details {
+        border: 2px solid var(--border-color);
+        padding: 0.5rem;
+      }
+    }
+  </style>
+</div>

package/support/demos/dispatch.html

@@ -0,0 +1,20 @@
+<div>
+  <button type="button" data-action="ping">Ping the panel</button>
+  <section aria-label="panel">
+    <output></output>
+  </section>
+  <quark-sheet>
+    button[data-action="ping"] {
+      @on click {
+        @dispatch demo-ping (target: "[aria-label='panel']", detail: (at: event.timeStamp));
+      }
+    }
+    [aria-label="panel"] {
+      @on demo-ping {
+        $pings: (+attr("data-pings") or 0) + 1;
+        data-pings: $pings;
+        output { content: "pinged #{$pings}×"; }
+      }
+    }
+  </quark-sheet>
+</div>

package/support/demos/events.html

@@ -0,0 +1,9 @@
+<div>
+  <a href="https://example.com">Click me — navigation is prevented</a>
+  <output></output>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    a { @on click (prevent-default, handle: noteEvent); }
+  </quark-sheet>
+</div>

package/support/demos/iterate.html

@@ -0,0 +1,13 @@
+<div>
+  <ul>
+    <template>
+      <li bind-name></li>
+    </template>
+  </ul>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    ul { content: iterate(getPlanets()); }
+    [bind-name] { content: item; }
+  </quark-sheet>
+</div>

package/support/demos/js-api.html

@@ -0,0 +1,17 @@
+<div data-demo-counter>
+  <button>+1</button>
+  <output></output>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    :scope {
+      $count: 0;
+    }
+    button {
+      @on click (handle: incrementFromJs(closest("[data-demo-counter]")));
+    }
+    output {
+      content: "Clicked #{$count} times";
+    }
+  </quark-sheet>
+</div>

package/support/demos/provider-list.html

@@ -0,0 +1,16 @@
+<div>
+  <provider-fetch api-url="/api/todos?_limit=4">
+    <ul>
+      <template>
+        <li bind-title></li>
+      </template>
+    </ul>
+  </provider-fetch>
+  <quark-sheet>
+    provider-fetch[is-success] {
+      $todos: prop("provision").body;
+      ul { content: iterate($todos); }
+      [bind-title] { content: item.title; }
+    }
+  </quark-sheet>
+</div>