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

package/src/tree/mixin.ts

@@ -0,0 +1,331 @@
+import { CANONICAL, EVAL, F_VISIBLE, Node, defineType, type OptionalLocation } from './node.js';
+import type { Condition } from './condition.js';
+import { type List } from './list.js';
+import type { Any, AnyRole } from './any.js';
+import type { Rules } from './rules.js';
+import { Interpolated } from './interpolated.js';
+import type { Context, TreeContext } from '../context.js';
+import { type PrintOptions, getPrintOptions } from './util/print.js';
+import { type MaybePromise, isThenable } from '@jesscss/awaitable-pipe';
+import { setParent } from './util/field-helpers.js';
+
+export interface MixinValue<Name extends AnyRole = 'name'> {
+  /**
+   * Mixin names can include . or # - in Sass they have to be escaped.
+   *
+   * Valid mixin names:
+   *   foo
+   *   foo.bar
+   *   foo#bar
+   *   foo.bar#baz
+   *   foo#bar.baz
+   *   -foo
+   *   _foo (private, from Sass both -foo and _foo are parsed as _foo)
+   *
+   * @todo - Should anonymous mixins have a different class type?
+   */
+  name?: Any<Name> | Interpolated<Name>;
+  /**
+   * Functions can be assigned an expression when parsing,
+   * but it will be evaluated as a set of Rules with a scope
+   * and an implicit `return`
+   */
+  rules: Rules;
+  /**
+   * - A plain node is a kind of value guard.
+   * - A name is just a named variable.
+   * - A var declaration is a named variable with a default value.
+   * - A rest is a rest parameter.
+   */
+  params?: List<Node>;
+  guard?: Condition;
+}
+
+export type MixinOptions = {
+  /** This is a flag that will set during parsing */
+  hasDefault?: boolean;
+
+  /**
+   * Cannot be overloaded. Written as !my-mixin() in Jess.
+   * If multiple mixin matches are found with the same
+   * name in a scope, it will throw an error.
+   */
+  unique?: boolean;
+};
+
+// const COMPOUND_REGEX = /[#.]?[-_a-zA-Z\xA0-\uFFFF][-_a-zA-Z0-9\xA0-\uFFFF]*/ug;
+/**
+ * someMixin (arg1; arg2: 10px) {
+ *   color: black;
+ *   background-color: white;
+ *   border-radius: $arg2;
+ * }
+ *
+ *
+ * Note that mixin calls are called as JavaScript functions,
+ * with either only positional arguments, or a plain object
+ * as the first argument, representing named arguments,
+ * followed by positional arguments.
+ *
+ * e.g. `foo($a; $b) { ... }`
+ *   can be called from JS like:
+ *     foo(1, 2) or
+ *     foo({ a: 1, b: 2 }) or
+ *     foo({ b: 2 }, 1)
+ *
+ * @todo - Even though we allow a selector as a name.
+ */
+export type MixinChildData = {
+  name: Any<AnyRole> | Interpolated<AnyRole> | undefined;
+  rules: Rules;
+  params: List<Node> | undefined;
+  guard: Condition | undefined;
+};
+
+export interface Mixin {
+  type: 'Mixin';
+  shortType: 'mixin';
+}
+
+export class Mixin extends Node<MixinValue, MixinOptions, MixinChildData> {
+  static override childKeys = ['name', 'rules', 'params', 'guard'] as const;
+
+  name: Any<AnyRole> | Interpolated<AnyRole> | undefined;
+  rules!: Rules;
+  params: List<Node> | undefined;
+  guard: Condition | undefined;
+
+  override clone(deep?: boolean, cloneFn?: (n: Node) => Node, ctx?: Context): this {
+    const name = this.get('name', ctx);
+    const rules = this.get('rules', ctx);
+    const params = this.get('params', ctx);
+    const guard = this.get('guard', ctx);
+    const cloneData: MixinValue = {
+      name: deep && name instanceof Node ? name.clone(deep, cloneFn, ctx) : name,
+      rules: deep ? rules.clone(deep, cloneFn, ctx) : rules,
+      params: deep && params instanceof Node ? params.clone(deep, cloneFn, ctx) : params,
+      guard: deep && guard instanceof Node ? guard.clone(deep, cloneFn, ctx) : guard
+    };
+
+    let priorChildParents: Array<[Node, Node | undefined]> | undefined;
+    if (!deep && ctx) {
+      priorChildParents = [];
+      if (cloneData.name instanceof Node) {
+        priorChildParents.push([cloneData.name, cloneData.name.parent]);
+      }
+      if (cloneData.rules instanceof Node) {
+        priorChildParents.push([cloneData.rules, cloneData.rules.parent]);
+      }
+      if (cloneData.params instanceof Node) {
+        priorChildParents.push([cloneData.params, cloneData.params.parent]);
+      }
+      if (cloneData.guard instanceof Node) {
+        priorChildParents.push([cloneData.guard, cloneData.guard.parent]);
+      }
+    }
+
+    const options = this._meta?.options;
+    const newNode: this = Reflect.construct(this.constructor, [
+      cloneData,
+      options ? { ...options } : undefined,
+      this.location,
+      this.treeContext
+    ]);
+
+    if (priorChildParents) {
+      for (const [child, priorParent] of priorChildParents) {
+        setParent(child, newNode, ctx!);
+        Reflect.set(child, 'parent', priorParent);
+      }
+    }
+
+    newNode.inherit(this);
+    return newNode;
+  }
+
+  constructor(value: MixinValue, options?: MixinOptions, location?: OptionalLocation, context?: TreeContext) {
+    super(value, options, location, context);
+    this.name = value.name;
+    this.rules = value.rules;
+    this.params = value.params;
+    this.guard = value.guard;
+    if (this.name instanceof Node) {
+      this.adopt(this.name);
+    }
+    if (this.rules instanceof Node) {
+      this.adopt(this.rules);
+    }
+    if (this.params instanceof Node) {
+      this.adopt(this.params);
+    }
+    if (this.guard instanceof Node) {
+      this.adopt(this.guard);
+    }
+    this.removeFlag(F_VISIBLE);
+  }
+
+  // Mixin has preEval method but doesn't need to set flags - preEvaluated is tracked as boolean
+
+  /** Return a selector-like keySet */
+  private _keySet: Set<string> | undefined;
+
+  get keySet() {
+    let keySet = this._keySet;
+    if (!keySet) {
+      const name = this.name;
+      if (!name) {
+        return (this._keySet = new Set());
+      }
+      keySet = this._keySet = new Set([name.valueOf()]);
+    }
+    return keySet;
+  }
+
+  getKeySet(context?: Context): Set<string> {
+    if (!context) {
+      return this.keySet;
+    }
+    const name = this.get('name', context);
+    if (!name) {
+      return new Set();
+    }
+    return new Set([name.valueOf()]);
+  }
+
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const context = options.context;
+    const name = this.get('name', context);
+    const rules = this.get('rules', context).withRenderOwner(this, context?.renderKey, context);
+    const params = this.get('params', context);
+    const guard = this.get('guard', context);
+    const mark = w.mark();
+    w.add(name ? `${name}` : '@');
+    if (name || params || guard) {
+      w.add('(');
+      if (params) {
+        params.toString(options);
+      }
+      w.add(')');
+    }
+    if (guard) {
+      w.add(' when ');
+      w.add(`${guard}`);
+    }
+    if (name || params || guard) {
+      w.add(' ');
+    }
+    // Emit rules directly into shared writer; do not re-add return value
+    rules.toBraced(options);
+    return w.getSince(mark);
+  }
+
+  override preEval(context: Context): MaybePromise<this> {
+    if (this.preEvaluated) {
+      return this;
+    }
+    // Mixins should NOT pre-evaluate their rules during initial registration.
+    // Rules inside mixins should only be pre-evaluated when the mixin is called.
+    // So we only handle the name (if interpolated) and mark as preEvaluated,
+    // but do NOT call super.preEval() which would pre-evaluate children.
+    const edgeContext = {
+      ...context,
+      renderKey: context.renderKey ?? EVAL
+    } as Context;
+    let node = this.clone(false, undefined, edgeContext);
+    node.preEvaluated = true;
+    node.sourceNode ??= this;
+    node.renderKey = edgeContext.renderKey;
+
+    const name = node.get('name', context);
+    let rules = node.get('rules', context).withRenderOwner(node, context.renderKey, context);
+    if (rules.renderKey === CANONICAL) {
+      const wrappedRules = rules.createShallowBodyWrapper(context);
+      node.rules = wrappedRules;
+      node.adopt(wrappedRules, context);
+      rules = wrappedRules;
+    }
+    // Set visibility on the canonical rules options — mixin body visibility
+    // is set on the derived mixin body wrapper for this eval path.
+    const rulesVisibility = { ...(rules.options.rulesVisibility ?? {}) };
+    if (context.leakyRules) {
+      rulesVisibility.Mixin = 'public';
+      rulesVisibility.VarDeclaration = 'optional';
+    } else {
+      rulesVisibility.Mixin = 'private';
+      rulesVisibility.VarDeclaration = 'private';
+    }
+    rules.options = { ...rules.options, rulesVisibility };
+    if (name && name instanceof Interpolated) {
+      const maybeKey = name.eval(context);
+      if (isThenable(maybeKey)) {
+        return maybeKey.then((key) => {
+          node.name = key;
+          return node;
+        });
+      }
+      node.name = maybeKey;
+    }
+    return node;
+  }
+
+  /** Since this is a mixin definition, it's not evaluated until it's called. */
+  override evalNode() {
+    return this;
+  }
+
+  // override async evalNode(context: Context): Promise<Rules | Expression> {
+  //   let { name, body, params, guard } = this.data
+  //   if (name instanceof Interpolated) {
+  //     name
+  // }
+
+  /**
+   * @todo -
+   * Return either a ruleset if `this` is the eval context,
+   * or return ruleset.obj() if not (for React/Vue)
+   *
+   * @todo - move to visitors
+   */
+  // toModule(context: Context, out: OutputCollector) {
+  //   const { name, args, value } = this
+  //   const nm = name.value
+  //   if (context.depth === 0) {
+  //     out.add(`export let ${nm}`, this.location)
+  //     context.exports.add(nm)
+  //   } else {
+  //     if (context.depth !== 1) {
+  //       out.add('let ')
+  //     }
+  //     out.add(`${nm} = function(`)
+  //     if (args) {
+  //       const length = args.value.length - 1
+  //       args.value.forEach((node, i) => {
+  //         if (node instanceof JsIdent) {
+  //           out.add(node.value)
+  //         } else {
+  //           out.add(node.name.value)
+  //           out.add(' = ')
+  //           node.value.toModule(context, out)
+  //         }
+  //         if (i < length) {
+  //           out.add(', ')
+  //         }
+  //       })
+  //     }
+  //     out.add(') { return ')
+  //     value.toModule(context, out)
+  //     out.add('}')
+  //   }
+  // }
+}
+
+type MixinConstructorParams = ConstructorParameters<typeof Mixin>;
+
+export const mixin = defineType(Mixin, 'Mixin') as (
+  value: MixinValue<AnyRole> | MixinConstructorParams[0],
+  options?: MixinConstructorParams[1],
+  location?: MixinConstructorParams[2],
+  treeContext?: MixinConstructorParams[3]
+) => Mixin;

package/src/tree/negative.ts

@@ -0,0 +1,58 @@
+import { Node, defineType, F_VISIBLE, F_NON_STATIC, type NodeOptions, type OptionalLocation, type TreeContext } from './node.js';
+import type { Context } from '../context.js';
+import { Dimension } from './dimension.js';
+import { type MaybePromise, pipe, tryStep } from '@jesscss/awaitable-pipe';
+import { getPrintOptions, type PrintOptions } from './util/print.js';
+
+export type NegativeChildData = { value: Node };
+
+/**
+ * The negative sign before a node
+ */
+export interface Negative extends Node<Node, NodeOptions, NegativeChildData> {
+  type: 'Negative';
+  shortType: 'negative';
+  eval(context: Context): MaybePromise<Node>;
+}
+
+export class Negative extends Node<Node, NodeOptions, NegativeChildData> {
+  static override childKeys = ['value'] as const;
+
+  readonly value!: Node;
+
+  constructor(value: Node, options?: NodeOptions, location?: OptionalLocation, treeContext?: TreeContext) {
+    super(value, options, location, treeContext);
+    this.value = value;
+    if (value instanceof Node) {
+      this.adopt(value);
+    }
+    // Negative 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 value = this.get('value', options.context);
+
+    w.add('-', this);
+    value.toString(options);
+
+    return w.getSince(mark);
+  }
+
+  override evalNode(context: Context): MaybePromise<Node> {
+    return pipe(
+      () => this.get('value', context).eval(context),
+      tryStep((value: Node) => {
+        if (!value.operate) {
+          throw new TypeError(`Cannot operate on ${value.type}`);
+        }
+        return value.operate(new Dimension({ number: -1 }), '*', context);
+      }, { rethrow: true })
+    );
+  }
+}
+
+export const negative = defineType(Negative, 'Negative');

package/src/tree/nil.ts

@@ -0,0 +1,57 @@
+/**
+ * Import from node-base to avoid circular dependency.
+ * The patching of Node.prototype.nil happens in node.ts
+ */
+import {
+  Node,
+  F_VISIBLE,
+  F_STATIC,
+  defineType,
+  type OptionalLocation,
+  type NodeOptions
+} from './node-base.js';
+import type { Context, TreeContext } from '../context.js';
+
+export interface Nil extends Node<''> {
+  type: 'Nil';
+  shortType: 'nil';
+  valueOf(): '';
+  eval(context: Context): Nil;
+}
+
+/**
+ * A Node type that outputs nothing.
+ *
+ * We need this for things like rulesets,
+ * which need dynamically-linked nodes
+ *
+ * This is also the default value for declarations like:
+ * `$var:;`
+ */
+export class Nil extends Node<''> {
+  static override childKeys = null as null;
+
+  constructor(
+    value?: any,
+    options?: NodeOptions,
+    location?: OptionalLocation,
+    treeContext?: TreeContext) {
+    super('', options, location, treeContext);
+    this.allowRoot = true;
+    this.allowRuleRoot = true;
+    this.addFlag(F_STATIC);
+    this.removeFlag(F_VISIBLE);
+    // Nil nodes should never render, even if fullRender is set on prototype (e.g., in tests)
+    this.fullRender = false;
+  }
+
+  override toTrimmedString() {
+    return '';
+  }
+
+  override toString() {
+    return '';
+  }
+}
+
+export const nil = defineType(Nil, 'Nil');