@jesscss/core 2.0.0-alpha.5 → 2.0.0-alpha.6

package/src/tree/node-type.ts

@@ -0,0 +1,122 @@
+/**
+ * Bitmask-based node type system.
+ *
+ * Each concrete node type gets a single bit. Abstract parent types
+ * (Selector, SimpleSelector) are masks combining their children's bits.
+ * A node's `nodeType` field is the OR of its own bit and all ancestor bits.
+ *
+ * isNode(x, N.Foo) compiles to: x.nodeType & Foo (one bitwise AND)
+ */
+
+// ── Leaf bits (one bit per concrete type) ──────────────────────────
+// These are types that are checked via isNode AND are concrete (not abstract).
+// Sorted roughly by hierarchy grouping.
+
+export enum N {
+  // Selector subtypes
+  BasicSelector     = 1 << 0,
+  Ampersand         = 1 << 1,
+  PseudoSelector    = 1 << 2,
+  CompoundSelector  = 1 << 3,
+  ComplexSelector   = 1 << 4,
+  SelectorList      = 1 << 5,
+  Combinator        = 1 << 6,
+
+  // Value types
+  Any               = 1 << 7,
+  Color             = 1 << 8,
+  Dimension         = 1 << 9,
+  Quoted            = 1 << 10,
+  Expression        = 1 << 11,
+  Operation         = 1 << 12,
+  Paren             = 1 << 13,
+  Range             = 1 << 14,
+  List              = 1 << 15,
+  Sequence          = 1 << 16,
+  Nil               = 1 << 17,
+
+  // Callable types
+  Call              = 1 << 18,
+  Func              = 1 << 19,
+  Mixin             = 1 << 20,
+
+  // Declaration types
+  Declaration       = 1 << 21,
+  VarDeclaration    = 1 << 22,
+
+  // Container types
+  Rules             = 1 << 23,
+  Collection        = 1 << 24,
+  Ruleset           = 1 << 25,
+  AtRule            = 1 << 26,
+
+  // Other types
+  Reference         = 1 << 27,
+  Comment           = 1 << 28,
+  JsFunction        = 1 << 29,
+  JsObject          = 1 << 30,
+  // Note: 1 << 31 is negative in JS (sign bit), so we use it carefully
+  JsArray           = 1 << 31,
+
+  // ── Abstract / parent masks ──────────────────────────────────────
+  // These combine child bits so isNode(x, N.Selector) matches any selector.
+
+  SimpleSelector    = BasicSelector | Ampersand | PseudoSelector,
+  Selector          = SimpleSelector | CompoundSelector | ComplexSelector | SelectorList | Combinator
+}
+
+/**
+ * Map from type name string → bitmask.
+ * Used by defineType to look up the mask for a given type name
+ * when walking the prototype chain.
+ */
+/**
+ * Map from type name string → bitmask.
+ * Used by defineType to look up the bit for a given type name
+ * when walking the prototype chain.
+ *
+ * IMPORTANT: Abstract parent types (Selector, SimpleSelector) map to 0 here.
+ * Their combined masks (N.Selector, N.SimpleSelector) are only used by
+ * isNode callers, NOT by defineType. Each concrete child already has its own
+ * bit, so when defineType walks the chain, the child's bit is sufficient.
+ */
+export const nodeTypeBits: Record<string, number> = {
+  // Concrete leaf types — each gets its own bit
+  BasicSelector: N.BasicSelector,
+  Ampersand: N.Ampersand,
+  PseudoSelector: N.PseudoSelector,
+  CompoundSelector: N.CompoundSelector,
+  ComplexSelector: N.ComplexSelector,
+  SelectorList: N.SelectorList,
+  Combinator: N.Combinator,
+  Any: N.Any,
+  Color: N.Color,
+  Dimension: N.Dimension,
+  Quoted: N.Quoted,
+  Expression: N.Expression,
+  Operation: N.Operation,
+  Paren: N.Paren,
+  Range: N.Range,
+  List: N.List,
+  Sequence: N.Sequence,
+  Nil: N.Nil,
+  Call: N.Call,
+  Func: N.Func,
+  Mixin: N.Mixin,
+  Declaration: N.Declaration,
+  VarDeclaration: N.VarDeclaration,
+  Rules: N.Rules,
+  Collection: N.Collection,
+  Ruleset: N.Ruleset,
+  AtRule: N.AtRule,
+  Reference: N.Reference,
+  Comment: N.Comment,
+  JsFunction: N.JsFunction,
+  JsObject: N.JsObject,
+  JsArray: N.JsArray,
+
+  // Abstract parent types — 0 because children already have their own bits.
+  // The combined masks (N.Selector, N.SimpleSelector) are for isNode callers only.
+  Selector: 0,
+  SimpleSelector: 0
+};

package/src/tree/node.ts

@@ -0,0 +1,118 @@
+/**
+ * This file is the entry point for the Node class.
+ * It imports from node-base.ts, applies prototype patches,
+ * and re-exports everything.
+ *
+ * This ensures that ANY import of Node gets the patched version,
+ * regardless of whether it goes through tree/index.ts or not.
+ */
+
+// First, import everything from node-base (the pure Node class)
+export * from './node-base.js';
+import { Node } from './node-base.js';
+
+// Import dependencies needed for patching (these import from node-base, not node)
+import { Nil } from './nil.js';
+import { Any } from './any.js';
+import { TreeContext } from '../context.js';
+import { type Operator } from './util/calculate.js';
+
+const LEGACY_DATA_INTERNAL = new Set([
+  'parent', 'index', 'frames', 'pre', 'post', 'state', 'nodeType',
+  'isSelector', 'keySetLibrary', 'role',
+  'fullRender',
+  'rulesetRegistry', 'mixinRegistry', 'declarationRegistry', 'functionRegistry',
+  'rulesIndexed', '_indexing',
+  'pendingExtends',
+  '_valueOf', '_keySet', '_visibleKeySet', '_requiredKeySet'
+]);
+
+function getLegacyData(this: Node) {
+  const childKeys = (this.constructor as typeof Node).childKeys;
+
+  if (Array.isArray(childKeys)) {
+    const extraKeys = Object.keys(this).filter((key) => {
+      return !key.startsWith('_') && !LEGACY_DATA_INTERNAL.has(key) && !childKeys.includes(key);
+    });
+
+    if (childKeys.length === 1 && extraKeys.length === 0) {
+      return (this as any)[childKeys[0]!];
+    }
+
+    const out: Record<string, unknown> = {};
+    for (const key of childKeys) {
+      const value = (this as any)[key];
+      if (value !== undefined) {
+        out[key] = value;
+      }
+    }
+    for (const key of extraKeys) {
+      const value = (this as any)[key];
+      if (value !== undefined) {
+        out[key] = value;
+      }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  }
+
+  const directValue = (this as any).value;
+  if (directValue !== undefined) {
+    return directValue;
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(this)) {
+    if (key.startsWith('_') || LEGACY_DATA_INTERNAL.has(key)) {
+      continue;
+    }
+    const value = (this as any)[key];
+    if (value !== undefined) {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Patch Node.prototype.nil to return a Nil instance
+ */
+Node.prototype.nil = function() {
+  return new Nil();
+};
+
+/**
+ * Patch Node.prototype.operate for string concatenation
+ */
+Node.prototype.operate = function(b: Node, op: Operator) {
+  let aVal = this.toString();
+  let bVal = b.toString();
+  if (op === '+') {
+    return new Any(aVal + bVal).inherit(this);
+  }
+  throw new Error(`Cannot operate on ${this.type}`);
+};
+
+/**
+ * Define a fallback treeContext for testing.
+ * Reads from _meta.treeContext (set by constructor), falls back to
+ * a lazily-created empty TreeContext for nodes created without one.
+ */
+Object.defineProperty(Node.prototype, 'treeContext', {
+  get() {
+    let context = this._meta?.treeContext;
+    if (!context) {
+      context = this._treeContext;
+      if (!context) {
+        context = this._treeContext = new TreeContext();
+      }
+    }
+    return context;
+  }
+});
+
+Object.defineProperty(Node.prototype, 'data', {
+  get: getLegacyData,
+  set(value) {
+    this.setData(value);
+  }
+});

package/src/tree/number.ts

@@ -0,0 +1,54 @@
+import {
+  type OptionalLocation,
+  type NodeOptions,
+  type TreeContext,
+  defineType,
+  type Node
+} from './node.js';
+import { Dimension } from './dimension.js';
+import { Color } from './color.js';
+import { type Context } from '../context.js';
+import { type Operator } from './util/calculate.js';
+import { isPlainObject } from './util/collections.js';
+
+/**
+ * A number. Named `Num` to avoid conflict with the built-in `Number` class.
+ */
+export interface Num {
+  type: 'Num';
+  shortType: 'num';
+}
+export class Num extends Dimension {
+  // Numbers are static and don't need evaluation
+
+  constructor(value: number | { number: number }, options?: NodeOptions, location?: OptionalLocation, treeContext?: TreeContext) {
+    super(isPlainObject(value) ? value as { number: number } : { number: value as number }, options, location, treeContext);
+  }
+
+  // Method overloads for better type safety
+  override operate(b: Num, op: Operator, context?: Context): Num | Dimension;
+  override operate(b: Dimension, op: Operator, context?: Context): Dimension;
+  override operate(b: Color, op: Operator, context?: Context): Color;
+  override operate(b: Node, op: Operator, context?: Context): Dimension | Color;
+  override operate(b: Node, op: Operator, context?: Context): Dimension | Color {
+    // Call super.operate() to get the result
+    const result = super.operate(b, op, context);
+
+    // If the result is a Dimension and has an empty unit, convert it to a Num
+    if (result instanceof Dimension && !result.unit) {
+      return new Num(result.number).inherit(this);
+    }
+
+    // Otherwise, pass through the result as-is
+    return result;
+  }
+}
+
+defineType(Num, 'Num');
+
+export const num = (
+  value: number,
+  options?: NodeOptions,
+  location?: OptionalLocation,
+  treeContext?: TreeContext
+) => new Num(value, options, location, treeContext);

package/src/tree/operation.ts

@@ -0,0 +1,187 @@
+import { Node, defineType, F_VISIBLE, F_NON_STATIC, type NodeOptions, type OptionalLocation, type TreeContext } from './node.js';
+import type { Context } from '../context.js';
+import type { Operator } from './util/calculate.js';
+import { type MaybePromise, isThenable } from '@jesscss/awaitable-pipe';
+import { getPrintOptions, type PrintOptions } from './util/print.js';
+import { isNode } from './util/is-node.js';
+import { N } from './node-type.js';
+import { Call } from './call.js';
+import { list } from './list.js';
+import {
+  mergeDependencies,
+  setDependency,
+  setEvaluated
+} from './util/field-helpers.js';
+
+export type { Operator };
+/** Operation is always a tuple */
+export type OperationValue = [
+  left: Node,
+  op: Operator,
+  right: Node
+];
+
+export type OperationChildData = { left: Node; operator: Operator; right: Node };
+
+export interface Operation {
+  type: 'Operation';
+  shortType: 'op';
+}
+/**
+ * A math operation OR a value with a slash. CSS is ambiguous
+ * in syntax about which is which, so we just classify `value / value`
+ * as an operation.
+ */
+export class Operation extends Node<OperationValue, NodeOptions, OperationChildData> {
+  static override childKeys = ['left', 'right'] as const;
+
+  left!: Node;
+  private operator!: Operator;
+  right!: Node;
+
+  override clone(deep?: boolean): this {
+    const options = this._meta?.options;
+    const value: OperationValue = [
+      deep ? this.left.clone(deep) : this.left,
+      this.operator,
+      deep ? this.right.clone(deep) : this.right
+    ];
+    const newNode: this = Reflect.construct(this.constructor, [
+      value,
+      options ? { ...options } : undefined,
+      this.location,
+      this.treeContext
+    ]);
+    newNode.inherit(this);
+    return newNode;
+  }
+
+  constructor(value: OperationValue, options?: NodeOptions, location?: OptionalLocation, treeContext?: TreeContext) {
+    super(value, options, location, treeContext);
+    this.left = value[0];
+    this.operator = value[1];
+    this.right = value[2];
+    if (this.left instanceof Node) {
+      this.adopt(this.left);
+    }
+    if (this.right instanceof Node) {
+      this.adopt(this.right);
+    }
+    // Operations are always non-static, but can inherit may_async from children
+    this.addFlags(F_VISIBLE, F_NON_STATIC);
+  }
+
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const mark = w.mark();
+    const context = options.context;
+    const left = this.get('left', context);
+    const op = this.operator;
+    const right = this.get('right', context);
+    let leftStr = w.capture(() => left.toString(options));
+    let rightStr = w.capture(() => right.toString(options));
+    w.add(leftStr.trimEnd(), left);
+    w.add(` ${op} `, this);
+    w.add(rightStr.trimStart(), right);
+    return w.getSince(mark);
+  }
+
+  override evalNode(context: Context): MaybePromise<Node> {
+    let n = this;
+    const left = n.get('left', context);
+    const op = n.operator;
+    const right = n.get('right', context);
+    const maybeLeft = left.eval(context);
+    const applyMergedDependency = (result: Node, l: Node, r: Node): Node => {
+      const dependency = mergeDependencies([l, r], context);
+      if (dependency?.dependsOn && dependency.dependsOn.size > 0) {
+        setDependency(result, {
+          dependsOn: new Set(dependency.dependsOn),
+          sourceExpr: this
+        }, context);
+      }
+      return result;
+    };
+    const finalize = (l: Node, r: Node): MaybePromise<Node> => {
+      if (context.shouldOperate(op, l, r)) {
+        if (isNode(l, N.Operation) || isNode(r, N.Operation)) {
+          // Preserve composite expressions such as `10px / 2 * 2` when a nested
+          // operation intentionally remains unevaluated under current math mode.
+          const outOperation = n.clone(false);
+          outOperation.adopt(l, context);
+          outOperation.adopt(r, context);
+          Reflect.set(outOperation, 'left', l);
+          Reflect.set(outOperation, 'right', r);
+          return applyMergedDependency(outOperation, l, r);
+        }
+        const unitMode = context?.opts?.unitMode ?? 'preserve';
+        const isPreserveMode = unitMode === 'preserve';
+
+        // In preserve mode, catch unit errors and return calc() call
+        if (isPreserveMode && isNode(l, N.Dimension) && isNode(r, N.Dimension)) {
+          try {
+            let out = l.operate(r, op, context);
+            out.pre = left.pre;
+            out.post = right.post;
+            return out;
+          } catch (error) {
+            // If it's a unit error (TypeError), return calc(operation)
+            if (error instanceof TypeError) {
+              // Preserve canonical operation state by materializing an isolated wrapper when needed.
+              const calcOperation = n.clone(false);
+              calcOperation.adopt(l, context);
+              calcOperation.adopt(r, context);
+              Reflect.set(calcOperation, 'left', l);
+              Reflect.set(calcOperation, 'right', r);
+              setEvaluated(calcOperation, true, context);
+              setEvaluated(l, true, context);
+              setEvaluated(r, true, context);
+              const calcCall = new Call({ name: 'calc', args: list([calcOperation]) });
+              calcCall.pre = left.pre;
+              calcCall.post = right.post;
+              return applyMergedDependency(calcCall, l, r);
+            }
+            // Re-throw non-unit errors
+            throw error;
+          }
+        }
+
+        let out: Node;
+        try {
+          out = l.operate(r, op, context);
+        } catch (error) {
+          throw error;
+        }
+        out.pre = left.pre;
+        out.post = right.post;
+        return applyMergedDependency(out, l, r);
+      }
+      if (l === n.left && r === n.right) {
+        return applyMergedDependency(n, l, r);
+      }
+      const outOperation = n.clone(false);
+      outOperation.adopt(l, context);
+      outOperation.adopt(r, context);
+      Reflect.set(outOperation, 'left', l);
+      Reflect.set(outOperation, 'right', r);
+      return applyMergedDependency(outOperation, l, r);
+    };
+    const handleLeft = (l: Node): MaybePromise<Node> => {
+      const maybeRight = right.eval(context);
+      if (isThenable(maybeRight)) {
+        return (maybeRight as Promise<Node>).then((r) => {
+          return finalize(l, r);
+        });
+      }
+      const r = maybeRight as Node;
+      return finalize(l, r);
+    };
+    if (isThenable(maybeLeft)) {
+      return (maybeLeft as Promise<Node>).then(handleLeft);
+    }
+    return handleLeft(maybeLeft as Node);
+  }
+}
+
+export const op = defineType(Operation, 'Operation', 'op');

package/src/tree/paren.ts

@@ -0,0 +1,132 @@
+import { type Context } from '../context.js';
+import { Bool } from './bool.js';
+import { Expression } from './expression.js';
+import { Operation } from './operation.js';
+import { Node, defineType, F_NON_STATIC, type OptionalLocation, type TreeContext } from './node.js';
+import { Dimension } from './dimension.js';
+import { type MaybePromise, isThenable } from '@jesscss/awaitable-pipe';
+import { type PrintOptions, getPrintOptions } from './util/print.js';
+
+export type ParenOptions = {
+  escaped?: boolean;
+  delimiter?: 'paren' | 'square';
+};
+
+export type ParenChildData = { value: Node | undefined };
+
+const isOpOrExpression = (node: Node): node is Operation | Expression => {
+  return node instanceof Operation || node instanceof Expression;
+};
+
+/**
+ * An expression in parenthesis
+ */
+export interface Paren {
+  type: 'Paren';
+  shortType: 'paren';
+  eval(context: Context): MaybePromise<Node>;
+}
+
+export class Paren extends Node<Node | undefined, ParenOptions, ParenChildData> {
+  static override childKeys = ['value'] as const;
+
+  value: Node | undefined;
+
+  constructor(value?: Node, options?: ParenOptions, location?: OptionalLocation, treeContext?: TreeContext) {
+    super(value, options, location, treeContext);
+    this.value = value;
+    if (value instanceof Node) {
+      this.adopt(value);
+    }
+    if (options?.escaped) {
+      this.addFlag(F_NON_STATIC);
+    }
+  }
+
+  private _isEscaped(_context?: Context): boolean {
+    return Boolean(this.options?.escaped);
+  }
+
+  private _unwrapValue(value: Node, context?: Context): Node {
+    let current = value;
+    while (current instanceof Paren) {
+      const next = current.get('value', context);
+      if (!next) {
+        break;
+      }
+      current = next;
+    }
+    return current;
+  }
+
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const mark = w.mark();
+    const parenOptions = this.options;
+    const escapeChar = parenOptions?.escaped ? '~' : '';
+    const delimiter = parenOptions?.delimiter ?? 'paren';
+    const open = delimiter === 'square' ? '[' : '(';
+    const close = delimiter === 'square' ? ']' : ')';
+    if (escapeChar) {
+      w.add(escapeChar, this);
+    }
+    w.add(open);
+    let value = this.get('value', options.context);
+    if (value) {
+      if (value instanceof Node) {
+        let out = w.capture(() => value.toString(options));
+        w.add(out.replace(/^[ \t\r\f]*|[ \t\r\f]*$/g, ''), value);
+      } else {
+        w.add(String(value), this);
+      }
+    }
+    w.add(close);
+    return w.getSince(mark);
+  }
+
+  override evalNode(context: Context): MaybePromise<Node> {
+    let value = this.get('value', context);
+    if (value) {
+      let isOp = isOpOrExpression(value);
+      if (isOp) {
+        context.parenFrames.push(true);
+      }
+      const maybeEvald = value.eval(context);
+      const after = (v: Node): Node => {
+        value = v;
+        if (isOp) {
+          context.parenFrames.pop();
+        }
+        if (this._isEscaped(context) && value instanceof Node) {
+          return value;
+        }
+        const delimiter = this.options?.delimiter ?? 'paren';
+        if (delimiter === 'paren') {
+          value = this._unwrapValue(value, context);
+          if (value instanceof Bool || value instanceof Dimension) {
+            return value;
+          }
+          if (isOp && !isOpOrExpression(value)) {
+            return value;
+          }
+        }
+        const node = this.clone();
+        const previousValue = node.value;
+        node.value = value;
+        if (previousValue instanceof Node && previousValue !== value) {
+          previousValue.parent = undefined;
+        }
+        node.adopt(value);
+        return node;
+      };
+      if (isThenable(maybeEvald)) {
+        return (maybeEvald as Promise<Node>).then(after);
+      }
+      return after(maybeEvald as Node);
+    }
+    return this;
+  }
+}
+
+export const paren = defineType(Paren, 'Paren');

package/src/tree/query-condition.ts

@@ -0,0 +1,47 @@
+import type { Context } from '../context.js';
+import type { PrintOptions } from '..';
+import { getPrintOptions } from './util/print.js';
+import { defineType } from './node.js';
+import { Sequence } from './sequence.js';
+
+/**
+ * Used by `@media`, `@supports`, and `@container`
+ *
+ * This just helps identify conditions if we need to
+ * merge them later.
+ *
+ * @todo - add more structure?
+ */
+export interface QueryCondition {
+  type: 'QueryCondition';
+  shortType: 'query';
+}
+
+export class QueryCondition extends Sequence {
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const mark = w.mark();
+    let value = this.get('value', options.context);
+    let length = value.length;
+
+    if (length === 0) {
+      return '';
+    }
+
+    // Print first node as-is
+    let node = value[0]!;
+    let out = w.capture(() => node.toString(options));
+    w.add(out.replace(/^\s*|\s*$/g, ''), node);
+
+    // Space out sub-nodes
+    for (let i = 1; i < length; i++) {
+      let node = value[i]!;
+      w.add(' ');
+      let out = w.capture(() => node.toString(options));
+      w.add(out.replace(/^\s*|\s*$/g, ''), node);
+    }
+    return w.getSince(mark);
+  }
+}
+export const query = defineType(QueryCondition, 'QueryCondition', 'query');