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

package/{lib/tree/index.js → src/tree/index.ts}

@@ -6,15 +6,41 @@
  *
  * @todo - rewrite the above, this is no longer true
  */
+
 /**
  * Import from node.ts which applies all the prototype patches
  * (nil, operate, treeContext) and re-exports from node-base.ts
  */
-import { Node, F_VISIBLE, F_MAY_ASYNC, F_STATIC, F_NON_STATIC } from './node.js';
-import { TreeContext } from '../context.js';
+import {
+  Node,
+  type LocationInfo,
+  type LocationInfoOrEmpty,
+  type OptionalLocation,
+  EVAL,
+  F_VISIBLE,
+  F_MAY_ASYNC,
+  F_STATIC,
+  F_NON_STATIC
+} from './node.js';
+import { type Context, TreeContext } from '../context.js';
 import { compare } from './util/compare.js';
-export { Node, TreeContext, F_VISIBLE, F_MAY_ASYNC, F_STATIC, F_NON_STATIC };
+
+export {
+  Node,
+  TreeContext,
+  type LocationInfo,
+  type LocationInfoOrEmpty,
+  type OptionalLocation,
+  EVAL,
+  F_VISIBLE,
+  F_MAY_ASYNC,
+  F_STATIC,
+  F_NON_STATIC
+};
+export { N } from './node-type.js';
+
 import { Selector } from './selector.js';
+
 export * from './at-rule.js';
 export * from './block.js';
 export * from './bool.js';
@@ -70,26 +96,27 @@ export * from './selector-interpolated.js';
 export * from './default-guard.js';
 export * from './rest.js';
 export * from './url.js';
+
 // Patch Selector.compare after all exports to avoid circular dependency
-import { selectorCompare } from './util/compare.js';
+import { selectorMatch } from './util/selector-match-core.js';
+
 /** Patch Selector to avoid circularity */
-Selector.prototype.compare = function (other) {
-    // Avoid `instanceof Selector` here: module identity can diverge under Vite/Vitest
-    // if the same file is loaded via different specifiers.
-    if (!!other && typeof other === 'object' && other.isSelector === true) {
-        const otherSelector = other;
-        const forward = selectorCompare(this, otherSelector);
-        if (forward.isEquivalent) {
-            return 0;
-        }
-        if (forward.hasPartialMatch) {
-            return -1;
-        }
-        const backward = selectorCompare(otherSelector, this);
-        if (backward.hasPartialMatch) {
-            return 1;
-        }
+Selector.prototype.compare = function(other: Node, context?: Context) {
+  // Avoid `instanceof Selector` here: module identity can diverge under Vite/Vitest
+  // if the same file is loaded via different specifiers.
+  if (!!other && typeof other === 'object' && 'isSelector' in other && other.isSelector === true) {
+    const otherSelector = other as unknown as Selector;
+    const forward = selectorMatch(this, otherSelector, undefined, context);
+    if (forward.fullMatch) {
+      return 0;
+    }
+    if (forward.partialMatch) {
+      return -1;
+    }
+    const backward = selectorMatch(otherSelector, this, undefined, context);
+    if (backward.partialMatch) {
+      return 1;
     }
-    return compare(this.valueOf(), other?.valueOf?.());
+  }
+  return compare(this.valueOf(), other?.valueOf?.());
 };
-//# sourceMappingURL=index.js.map

package/src/tree/interpolated.ts

@@ -0,0 +1,346 @@
+import { Node, F_MAY_ASYNC, F_VISIBLE, F_NON_STATIC, defineType } from './node.js';
+import { Any, type AnyRole, type AnyOptions } from './any.js';
+import type { Context } from '../context.js';
+import { BasicSelector } from './selector-basic.js';
+import { CompoundSelector } from './selector-compound.js';
+import type { Selector } from './selector.js';
+import { PseudoSelector } from './selector-pseudo.js';
+import { isNode } from './util/is-node.js';
+import { N } from './node-type.js';
+import { type PrintOptions, getPrintOptions } from './util/print.js';
+import { type MaybePromise, serialForEach, isThenable } from '@jesscss/awaitable-pipe';
+
+// Placeholder that's very unlikely to appear in user strings
+// but is also easily typeable for tests
+export const INTERPOLATION_PLACEHOLDER = '%%';
+const INTERPOLATION_PLACEHOLDER_REGEXP = /%%/g;
+
+function shouldWrapSelectorInIs(replacement: Node): boolean {
+  if (isNode(replacement, N.SelectorList)) {
+    return true;
+  }
+  if (isNode(replacement, N.ComplexSelector)) {
+    return true;
+  }
+  if (replacement.type === 'SelectorCapture') {
+    const arg = (replacement as unknown as { value: Node }).value;
+    return isNode(arg, N.SelectorList) || isNode(arg, N.ComplexSelector);
+  }
+  const str = String(replacement.valueOf?.() ?? replacement);
+  return str.includes(',');
+}
+
+function getIsWrapperArg(replacement: Node): Node {
+  if (replacement.type === 'SelectorCapture') {
+    return (replacement as unknown as { value: Node }).value;
+  }
+  return replacement;
+}
+
+function serializeGeneratedIsWrapper(replacement: Node): string {
+  const arg = getIsWrapperArg(replacement);
+  const pseudo = PseudoSelector.create({ name: ':is', arg });
+  pseudo.generated = true;
+  return pseudo.toTrimmedString().replace(/\n\s*/g, ' ');
+}
+
+export type InterpolatedValue = {
+  /** String with INTERPOLATION_PLACEHOLDER placeholders */
+  source: string;
+  replacements: Node[];
+};
+
+export type InterpolatedChildData = { source: string; replacements: Node[] };
+
+/**
+ * Merge an interface to declare the specific types
+ *
+ * @todo - Instead of extending simple selector, create a selector "wrapper"
+ * that goes around expressions and interpolated values, so that it
+ * casts as a selector after evaluation.
+ *
+ * This would eliminate the need for the `evalToSelector` and `evalToGeneric`
+ * methods, because the wrapper would handle the returned node type.
+ */
+export interface Interpolated<
+  Role extends AnyRole = AnyRole
+> extends Node<InterpolatedValue, AnyOptions<Role>, InterpolatedChildData> {
+  type: 'Interpolated';
+  shortType: 'interpolated';
+  eval(context: Context): MaybePromise<Any<Role>>;
+}
+/**
+ * An interpolated value is one that contains
+ * reference variables, or expressions, but
+ * which MUST resolve to a node with a string value
+ * (like Anonymous) when evaluated.
+ *
+ * @example
+ *   in Less:
+ *     - `@@foo` is an interpolated variable
+ *     - `--prop-@{foo}` is an interpolated property
+ */
+export class Interpolated<
+  Role extends AnyRole = AnyRole
+> extends Node<InterpolatedValue, AnyOptions<Role>, InterpolatedChildData> {
+  static override childKeys = ['source', 'replacements'] as const;
+
+  source!: string;
+  replacements!: Node[];
+
+  constructor(value: InterpolatedValue, options?: AnyOptions<Role>, location?: any, treeContext?: any) {
+    super(value, options, location, treeContext);
+    this.source = value.source;
+    this.replacements = value.replacements;
+    for (const r of this.replacements) {
+      if (r instanceof Node) {
+        this.adopt(r);
+      }
+    }
+    // Interpolated nodes are always non-static and may be async
+    this.addFlags(F_VISIBLE, F_MAY_ASYNC, F_NON_STATIC);
+  }
+
+  override clone(deep?: boolean): this {
+    const replacements = deep
+      ? this.replacements.map(replacement => replacement.clone(true))
+      : this.replacements;
+    const node = new (this.constructor as typeof Interpolated<Role>)(
+      { source: this.source, replacements: [] },
+      this.options ? { ...this.options } : undefined,
+      this.location,
+      this.treeContext
+    ) as this;
+    node.inherit(this);
+    node.replacements = replacements;
+    if (deep) {
+      for (const replacement of replacements) {
+        node.adopt(replacement);
+      }
+    }
+    return node;
+  }
+
+  override valueOf(): string {
+    return this.source;
+  }
+
+  private _withReplacements(replacements: Node[]): this {
+    const node = new (this.constructor as typeof Interpolated<Role>)(
+      { source: this.source, replacements: [] },
+      this.options ? { ...this.options } : undefined,
+      this.location,
+      this.treeContext
+    ) as this;
+    node.inherit(this);
+    node.replacements = replacements;
+    return node;
+  }
+
+  replace(replacements?: Node[], options?: PrintOptions): string {
+    const printOpts = getPrintOptions(options);
+    const context = printOpts.context;
+    const source = this.get('source', context);
+    const activeReplacements = replacements ?? this.get('replacements', context);
+    let output = source;
+    let i = 0;
+    let w = printOpts!.writer;
+    INTERPOLATION_PLACEHOLDER_REGEXP.lastIndex = 0;
+    output = output.replace(INTERPOLATION_PLACEHOLDER_REGEXP, () => {
+      let replacement: Node | undefined;
+      try {
+        replacement = activeReplacements[i++];
+      } catch (error: unknown) {
+        throw error;
+      }
+      let result = '';
+      if (replacement) {
+        if (isNode(replacement, N.Reference)) {
+          // Preserve exact interpolation reference syntax (including quoted property keys).
+          result = w.capture(() => replacement.toTrimmedString(printOpts));
+        } else if (isNode(replacement, N.Quoted)) {
+          // Interpolated string slots merge raw string content.
+          // Using valueOf() avoids re-emitting inner quote delimiters.
+          result = String(replacement.valueOf());
+        } else {
+          result = w.capture(() => replacement!.toTrimmedString(printOpts));
+        }
+        if (!isNode(replacement, N.Reference)) {
+          result = result.trim();
+        }
+      }
+      return result;
+    });
+
+    return output;
+  }
+
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const mark = w.mark();
+    const result = this.replace(undefined, options);
+    w.add(result, this);
+    return w.getSince(mark);
+  }
+
+  /**
+   * Can turn simple #id, .class, element or SelectorCapture into a selector.
+   * Legacy "list of mixin references" (e.g. @var: .a, .b, .c) is not supported; use *[.a, .b, .c].
+   */
+  createSelector(context?: Context) {
+    const source = this.get('source', context);
+    const replacements = this.get('replacements', context);
+    const segments = source.split(INTERPOLATION_PLACEHOLDER);
+    const isWholeSelectorInterpolation = (
+      replacements.length === 1
+      && segments.length === 2
+      && segments[0]!.trim() === ''
+      && segments[1]!.trim() === ''
+    );
+    // For full-selector interpolation, collapse directly to the resolved selector/text.
+    // Generated :is wrappers are only needed for embedded interpolation fragments.
+    if (isWholeSelectorInterpolation) {
+      const replacement = replacements[0]!;
+      if (context && !replacement.evaluated) {
+        throw new Error('Cannot create selector from un-evaluated interpolated node');
+      }
+      if (isNode(replacement, N.Selector)) {
+        return replacement.clone(false).inherit(this) as Selector;
+      }
+      return new BasicSelector(replacement.toTrimmedString().trim()).inherit(this);
+    }
+    let output = '';
+    for (let [i, replacement] of replacements.entries()) {
+      if (context && !replacement.evaluated) {
+        throw new Error('Cannot create selector from un-evaluated interpolated node');
+      }
+      let part = replacement.toTrimmedString();
+      if (shouldWrapSelectorInIs(replacement)) {
+        part = serializeGeneratedIsWrapper(replacement);
+      }
+      output += (segments[i] ?? '') + part;
+    }
+    // Preserve any trailing literal segment after the last interpolation placeholder.
+    if (segments.length > replacements.length) {
+      output += segments.slice(replacements.length).join(INTERPOLATION_PLACEHOLDER);
+    }
+    // Interpolated selector output can produce compound selectors (e.g. ".a#b").
+    // Preserve token boundaries so keySet/registry lookup can match correctly.
+    const simpleTokens = output.match(/[#.][^#.\s]+|[^#.\s]+/g) ?? [output];
+    if (
+      simpleTokens.length > 1
+      && !output.includes(':')
+      && !output.includes('[')
+      && !output.includes('&')
+    ) {
+      return new CompoundSelector(simpleTokens.map(token => new BasicSelector(token))).inherit(this);
+    }
+    return new BasicSelector(output).inherit(this);
+  }
+
+  createGeneric(context?: Context) {
+    const trimmedString = this.toTrimmedString(context ? { context } : undefined);
+    let any = new Any<Role>(trimmedString, { role: this.options.role }).inherit(this);
+    return any;
+  }
+
+  /** Convenience: evaluate replacements then convert to Selector (BasicSelector or SelectorList) */
+  evalToSelector(context: Context): MaybePromise<Selector> {
+    const out = this._evalToInterpolated(context);
+    if (isThenable(out)) {
+      return (out as Promise<Interpolated<Role>>).then(node => node.createSelector(context));
+    }
+    return (out as Interpolated<Role>).createSelector(context);
+  }
+
+  override evalNode(context: Context): MaybePromise<Any> {
+    const out = this._evalToInterpolated(context);
+    if (isThenable(out)) {
+      return (out as Promise<Interpolated<Role>>).then((node) => {
+        return node.createGeneric(context);
+      });
+    }
+    const result = (out as Interpolated<Role>).createGeneric(context);
+    return result;
+  }
+
+  /**
+   * Just evaluate replacements and return. We don't stringify yet,
+   * because depending on the context, it will turn into different
+   * node types.
+   */
+  override preEval(context: Context): MaybePromise<this> {
+    if (this.preEvaluated) {
+      return this;
+    }
+    const node = this.clone() as this;
+    node.preEvaluated = true;
+    const replacements = [...this.replacements];
+    let changed = false;
+    const maybe = serialForEach(replacements, (replacement, idx) => {
+      const out = replacement.preEval(context);
+      if (isThenable(out)) {
+        return (out as Promise<Node>).then((result) => {
+          if (result !== replacement) {
+            replacements[idx] = result;
+            changed = true;
+          }
+        });
+      }
+      if ((out as Node) !== replacement) {
+        replacements[idx] = out as Node;
+        changed = true;
+      }
+      return undefined;
+    });
+    if (isThenable(maybe)) {
+      return (maybe as Promise<void>).then(() => {
+        if (changed) {
+          node.replacements = replacements;
+        }
+        return node;
+      });
+    }
+    if (changed) {
+      node.replacements = replacements;
+    }
+    return node;
+  }
+
+  _evalToInterpolated(context: Context): MaybePromise<this> {
+    let node = this;
+    let replacements = [...node.get('replacements', context)];
+    const markEvaluated = (result: Node): Node => {
+      result.evaluated = true;
+      return result;
+    };
+
+    let maybe = serialForEach(replacements, (n, idx) => {
+      const out = n.eval(context);
+      if (isThenable(out)) {
+        return (out as Promise<Node>).then((result) => {
+          replacements[idx] = markEvaluated(result);
+        });
+      }
+      replacements[idx] = markEvaluated(out as Node);
+      return undefined;
+    });
+    if (isThenable(maybe)) {
+      return maybe.then(() => {
+        if (node === this) {
+          return this._withReplacements(replacements);
+        }
+        node.replacements = replacements;
+        return node;
+      });
+    }
+    if (node === this) {
+      return this._withReplacements(replacements);
+    }
+    node.replacements = replacements;
+    return node;
+  }
+}
+
+export const interpolated = defineType(Interpolated, 'Interpolated');

package/src/tree/js-array.ts

@@ -0,0 +1,21 @@
+import { Node, defineType } from './node.js';
+
+/**
+ * A plain JS array.
+ */
+export interface JsArray {
+  type: 'JsArray';
+  shortType: 'jsarray';
+}
+export class JsArray extends Node<readonly any[]> {
+  static override childKeys = null as null;
+
+  value!: readonly any[];
+
+  constructor(value: readonly any[], options?: any, location?: any, treeContext?: any) {
+    super(value, options, location, treeContext);
+    this.value = value;
+  }
+}
+
+export const jsarray = defineType(JsArray, 'JsArray', 'jsarray');

package/src/tree/js-expr.ts

@@ -0,0 +1,50 @@
+import { type Context } from '../context.js';
+import { Node, defineType } from './node.js';
+import { cast } from './util/cast.js';
+import { type PrintOptions, getPrintOptions } from './util/print.js';
+import { type MaybePromise } from '@jesscss/awaitable-pipe';
+
+/**
+ * Deprecated Less feature
+ *
+ * @deprecated - use `@-use` instead
+ */
+export interface JsExpression extends Node<string> {
+  type: 'JsExpression';
+  shortType: 'jsexpr';
+  eval(context: Context): Promise<Node>;
+}
+
+export class JsExpression extends Node<string> {
+  static override childKeys = null as null;
+
+  value!: string;
+
+  constructor(value: string, options?: any, location?: any, treeContext?: any) {
+    super(value, options, location, treeContext);
+    this.value = value;
+  }
+
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const mark = w.mark();
+    w.add('`', this);
+    w.add(this.value);
+    w.add('`');
+    return w.getSince(mark);
+  }
+
+  /**
+   * @todo - install deno-bin to run scripts securely
+   * @todo - Figure out pipe / MaybePromise when this is actually evaluating JS
+   */
+  override evalNode(context: Context): Promise<Node> {
+    return (async () => {
+      const result = await eval(this.value);
+      return cast(result);
+    })();
+  }
+}
+
+export const jsexpr = defineType(JsExpression, 'JsExpression', 'jsexpr');

package/src/tree/js-function.ts

@@ -0,0 +1,31 @@
+import { Node, defineType, type OptionalLocation, type TreeContext, type NodeOptions } from './node.js';
+
+type Fn = (...args: any[]) => any;
+/**
+ * A JS function.
+ */
+export interface JsFunction {
+  type: 'JsFunction';
+  shortType: 'jsfunc';
+}
+export class JsFunction extends Node<Fn> {
+  static override childKeys = null as null;
+
+  value!: Fn;
+  name?: string | undefined;
+
+  constructor(
+    value: { name: string; fn: Fn } | Fn,
+    options?: NodeOptions,
+    location?: OptionalLocation,
+    treeContext?: TreeContext
+  ) {
+    const fn = typeof value === 'function' ? value : value.fn;
+
+    super(fn, options, location, treeContext);
+    this.value = fn;
+    this.name = typeof value === 'function' ? undefined : value.name;
+  }
+}
+
+export const jsfunc = defineType(JsFunction, 'JsFunction', 'jsfunc');

package/src/tree/js-object.ts

@@ -0,0 +1,22 @@
+import { Node, defineType } from './node.js';
+
+/**
+ * A plain JS object.
+ */
+export interface JsObject {
+  type: 'JsObject';
+  shortType: 'jsobj';
+}
+
+export class JsObject extends Node<Record<string, any>> {
+  static override childKeys = null as null;
+
+  value!: Record<string, any>;
+
+  constructor(value: Record<string, any>, options?: any, location?: any, treeContext?: any) {
+    super(value, options, location, treeContext);
+    this.value = value;
+  }
+}
+
+export const jsobj = defineType(JsObject, 'JsObject', 'jsobj');