Custom-tag reference

The declarations below reproduce the exported custom-tag types from @mxlang/core’s custom-tags.ts. Referenced IR types (Attr, AttributeTag, Block, Expr, ForSource, IrNode, and Position) are also exported by @mxlang/core.

export interface CustomTagParseOptions {
  text?: boolean;
  preserveWhitespace?: boolean;
  openTagOnly?: boolean;
}

export interface CustomTagAttribute {
  type?: "string" | "number" | "boolean" | "expression" | "array" | "function";
  items?: "string" | "number" | "boolean";
  required?: boolean;
  enum?: string[];
  default?: unknown;
  literalOnly?: boolean;
}

export interface CustomTagAttributeTag {
  defaultTag?: string;
  repeatable?: boolean;
  required?: boolean;
  attributes?: Record<string, CustomTagAttribute>;
  attributeTags?: Record<string, CustomTagAttributeTag>;
  children?: Record<string, CustomTagChild>;
}

export interface CustomTagChild {
  repeatable?: boolean;
  required?: boolean;
}

export interface TagStore {
  get<T>(key: string): T | undefined;
  set<T>(key: string, value: T): void;
}

export interface AnalyzeContext {
  store: TagStore;
  fail(message: string, at?: Position): never;
}

export interface FinalizeContext {
  store: TagStore;
  build: IrBuilders;
  gensym(hint?: string): string;
}

export interface TagCall {
  name: string;
  loc: Position;
  attrs: Attr[];
  content: Block | null;
  attributeTags: AttributeTag[];
  params: string[];
  var: string | null;
}

export interface TransformContext {
  build: IrBuilders;
  gensym(hint?: string): string;
  fail(message: string, at?: Position): never;
  hoist(code: string): void;
  store: TagStore;
}

export interface CustomTag {
  defaultTag?: string;
  parseOptions?: CustomTagParseOptions;
  attributes?: Record<string, CustomTagAttribute>;
  attributeTags?: Record<string, CustomTagAttributeTag>;
  analyze?(calls: readonly TagCall[], ctx: AnalyzeContext): void;
  transform?(call: TagCall, ctx: TransformContext): IrNode[];
  finalize?(ctx: FinalizeContext): IrNode[];
}

export interface IrBuilders {
  text(value: string): IrNode;
  interpolation(expr: Expr, escaped?: boolean): IrNode;
  element(
    name: string,
    attrs?: Attr[],
    children?: IrNode[],
    options?: { void?: boolean },
  ): IrNode;
  attr(name: string, value: string): Attr;
  dynamicAttr(name: string, value: Expr): Attr;
  booleanAttr(name: string): Attr;
  expr(code: string): Expr;
  ifChain(
    branches: Array<{ condition: Expr | null; children: IrNode[] }>,
  ): IrNode;
  forLoop(options: {
    source: ForSource;
    params: string[];
    bindings?: string[];
    key?: Expr | null;
    children: IrNode[];
  }): IrNode;
  block(children: IrNode[], params?: string[]): Block;
  delegatedTag(
    name: string,
    children: IrNode[],
    attributeTags: AttributeTag[],
  ): IrNode;
  template(call: TagCall): IrNode[];
}

The exported limits are MAX_EXPANSION_DEPTH = 64 nested calls and MAX_EXPANSION_NODES = 100_000 nodes from one transform or finalize result.

Member guide

CustomTag

Parse and declaration members

TagCall

/var on a custom tag call (e.g. <counter/n start=1/>) binds the value the tag’s template hands back with <return> — see Returning a value. A tag with no template at all (a sidecar that builds IR) has no <return> to bind, so /var on one is a positioned compile error.

Contexts and store

Builders

Positioned errors

Messages begin with the relevant tag name unless the problem belongs to a discovery file. Dynamic values such as names, paths, counts, expected types, and thrown messages are inserted into the forms below.

Registration and phase errors

Attribute errors

Attribute-tag errors

Builder boundary errors

Template errors

A template is a separate module, so the cycle, spread, bare-input and import-collision errors the inlining model needed no longer exist: recursion is ordinary ESM, a spread is an ordinary object, input is a parameter, and a template’s imports never enter the caller’s module.

Discovery and sidecar errors

Warnings and non-fatal diagnostics

The last two are scanner diagnostics: the bad entry is skipped and discovery continues. The language server surfaces them as warnings; build integrations warn once per distinct problem.